rsr.rsr.run_ref_extraction_by_mcs¶

rsr.rsr.run_ref_extraction_by_mcs(*, sfun, probs, row_names, n_state, sys_upper_st, refs_upper=None, refs_lower=None, refs_mat_upper=None, refs_mat_lower=None, unk_prob_thres=0.01, unk_prob_opt='rel', max_rounds=10000, prob_update_every=500, save_every=10, n_sample=10000000, sample_batch_size=100000, max_search_loops=0, min_ref_search=True, active_ref_search=True, acq_gamma=1.0, acq_pool_size=1024, ref_update_verbose=True, track_overrides=False, n_workers=1, devices=None, output_dir='rsr_res', upper_json_name=None, lower_json_name=None, upper_pt_name=None, lower_pt_name=None, metrics_path='metrics.json')[source]¶

Extract boundary reference states via Monte Carlo search.

Iterates between exploring the unknown system-event space by Monte Carlo simulation and evaluating the system function on candidate component states. On each round, samples are drawn from probs, classified as upper, lower, or unknown against the current reference stores, and one or more of the unknown samples are selected and resolved by calling sfun. The resulting upper/lower references are minimised and merged back in. The loop terminates when the probability of the unknown region falls below unk_prob_thres or max_rounds is reached.

Which unknown samples get resolved is governed by active_ref_search. By default the selection is active: each unknown sample is scored by how much a new reference state found there would extend the current frontiers, and the best-scoring one(s) are evaluated. Setting active_ref_search=False restores uniform-random selection.

Parameters:

sfun – System function. Callable comps_dict -> (fval, sys_state, info).
probs (Tensor) – Categorical component probabilities of shape (n_var, n_state).
row_names (List[str]) – Component names matching the rows of probs.
n_state (int) – Number of states per component.
sys_upper_st (int) – System-state threshold that defines the upper reference set (samples with sys_state >= sys_upper_st).
refs_upper (Optional[List[Dict[str, Any]]]) – Optional initial list of upper reference dicts.
refs_lower (Optional[List[Dict[str, Any]]]) – Optional initial list of lower reference dicts.
refs_mat_upper (Optional[Tensor]) – Optional initial upper reference tensor (n_refs, n_var, n_state).
refs_mat_lower (Optional[Tensor]) – Optional initial lower reference tensor.

Keyword Arguments:

unk_prob_thres – Termination threshold on the unknown-region probability.
unk_prob_opt – Threshold interpretation — "abs" (absolute) or "rel" (relative to the previous round).
max_rounds – Hard cap on the number of rounds.
prob_update_every – Frequency (in rounds) at which the unknown probability is re-estimated.
save_every – Frequency (in rounds) at which references and metrics are written to disk.
n_sample – Total number of samples drawn per probability update.
sample_batch_size – Samples per batch inside one update.
max_search_loops – Max batches per round used to search for new unknown candidates. 0 means n_sample // sample_batch_size.
min_ref_search – Whether to minimise newly found references before inserting them.
active_ref_search – If True (default), choose which unknown sample(s) to resolve next by maximising the deficit-based acquisition score (d+ + d-) - acq_gamma * |d+ - d-| rather than drawing them uniformly at random, where d+/d- are the upper/lower deficits (see select_refs_by_acquisition()). Ties are broken by the lexicographically smallest component-state vector. Falls back to random selection while either reference set is still empty, since the deficits are undefined then.
acq_gamma – Non-negative weight balancing exploration against uncertainty in the acquisition score. 0 is pure exploration (pick the candidate furthest from both frontiers); larger values increasingly favour candidates that sit equidistant between the two frontiers, whose outcome is least predictable. Ignored when active_ref_search is False.
acq_pool_size – Cap on how many unknown samples are scored per round. When more are available, a random subset of this size is scored, which bounds the cost of the deficit computation on large reference sets. 0 scores every unknown sample. Ignored when active_ref_search is False.
ref_update_verbose – Print progress messages during reference updates.
track_overrides – If True, record every override event — i.e. whenever a newly found reference dominates and removes existing reference(s) — and return them under override_log in the result. Each entry is {"round", "kind", "found", "overridden"} where kind is "upper"/"lower", found is the newly found reference, and overridden is the list of existing references removed because of it. Default off. (In the parallel path, n_workers > 1, found holds all refs added that round — attribution is round-level.)
n_workers – Number of CPU worker processes for parallel sfun evaluation and state minimisation.
devices – GPU devices for multi-GPU sampling, e.g. ["cuda:0", "cuda:1"].
output_dir – Directory in which references and metrics are written.
upper_json_name – Filename for upper references (JSON). Defaults to refs_up_{sys_upper_st}.json.
lower_json_name – Filename for lower references (JSON). Defaults to refs_low_{sys_upper_st-1}.json.
upper_pt_name – Filename for the upper reference tensor (PyTorch).
lower_pt_name – Filename for the lower reference tensor (PyTorch).
metrics_path – Filename for the per-round metrics log.

Return type:

Dict[str, Any]

Returns:

A dictionary with the final refs_upper, refs_lower, refs_mat_upper, refs_mat_lower, and the metrics log. When track_overrides is True, it also includes override_log, a list of override events (see track_overrides).

Raises:

ValueError – If acq_gamma is negative while active_ref_search is enabled, or if acq_pool_size is negative.

Notes

Active selection of the next reference state. For an unknown sample x, the upper deficit d+(x) is the smallest total shortfall of x below any upper reference state, and the lower deficit d-(x) the smallest total excess of x above any lower reference state, both counting only the components that fall short (respectively exceed). d+ = 0 certifies survival and d- = 0 certifies failure, so unknown samples are exactly those with both deficits strictly positive. They are ranked by

\[A(x) = \big(d^{+}(x) + d^{-}(x)\big) - \gamma\,\big|d^{+}(x) - d^{-}(x)\big|.\]

The sum rewards samples lying far from both frontiers, which are the regions the current reference sets map most poorly. The absolute difference measures how one-sided a sample is: where it is large the outcome of evaluating sfun is predictable and the resulting reference state would sit adjacent to ones already known, adding little coverage. Subtracting it therefore favours samples that are both far from what is known and near-equidistant between the two frontiers. acq_gamma sets the balance.

Ties are broken by the lexicographically smallest component-state vector, so a round’s picks do not depend on the order in which samples happen to be drawn.

Two caveats. Selection falls back to uniform-random while either reference set is empty, since the deficits are undefined then — in practice this covers the first few rounds. And when a round yields more unknown samples than acq_pool_size, a random subset of that size is scored rather than all of them, which bounds the cost of the deficit computation on large reference sets; selection is greedy within that pool, not over every unknown sample.