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, ref_update_verbose=True, 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 unknown samples are 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.

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.

  • ref_update_verbose – Print progress messages during reference updates.

  • 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.