romtools.workflows.uq.run_multifidelity_monte_carlo#

romtools.workflows.uq.run_multifidelity_monte_carlo(high_fidelity_model, low_fidelity_model, parameter_space, absolute_work_dir=None, number_of_high_fidelity_samples=None, number_of_low_fidelity_samples=None, pilot_sample_count=None, high_fidelity_equivalent_budget=None, low_to_high_fidelity_cost_ratio=None, allocation_qoi_index=0, random_seed=1, high_fidelity_evaluation_concurrency=1, low_fidelity_evaluation_concurrency=1, control_variate_coefficients=None, overwrite=False, dispatcher=None, *, absolute_uq_directory=None, dry_run=False)[source]#

Estimate a QoI mean using two-level multifidelity Monte Carlo.

The first N_H low-fidelity evaluations are paired with the high-fidelity evaluations at identical parameter samples. For each QoI component, the estimator is

\[\widehat{\mu}_{MF} = \overline{Q}_H^{N_H} + \alpha\left(\overline{Q}_L^{N_L} - \overline{Q}_L^{N_H}\right).\]

Exactly one allocation mode must be selected. Fixed mode accepts explicit high- and low-fidelity sample counts. Pilot mode accepts a paired pilot count and high-fidelity-equivalent budget, then estimates correlation and coefficients and performs an integer search under N_H + cost_ratio * N_L <= budget. Pilot evaluations count toward the final allocation and budget. The workflow falls back to high-fidelity Monte Carlo when the pilot predicts no benefit from additional low-fidelity samples.

Parameters:

  • high_fidelity_model (QoiModel) – High-fidelity QoiModel implementation.

  • low_fidelity_model (QoiModel) – Low-fidelity QoiModel implementation. It must return the same flattened QoI dimension as the high-fidelity model.

  • parameter_space (ParameterSpace) – Distribution used to generate shared samples.

  • absolute_work_dir (str | None) – Absolute output path. Evaluations are stored in high_fidelity and low_fidelity subdirectories and aggregate results are written to uq_stats.npz.

  • number_of_high_fidelity_samples (int | None) – Final high-fidelity count in fixed mode. Must be at least two.

  • number_of_low_fidelity_samples (int | None) – Final low-fidelity count in fixed mode. Must be no smaller than the high-fidelity count.

  • pilot_sample_count (int | None) – Initial paired count in pilot mode. Must be at least two and fit within the budget.

  • high_fidelity_equivalent_budget (float | None) – Pilot-mode budget in high-fidelity evaluation units.

  • low_to_high_fidelity_cost_ratio (float | None) – Positive ratio c_L / c_H. If omitted in pilot mode, paired pilot run times estimate it.

  • allocation_qoi_index (int) – Flattened QoI component used to select sample counts. Statistics and coefficients are computed for every component.

  • random_seed (int) – Seed used to generate the paired samples.

  • high_fidelity_evaluation_concurrency (int) – Maximum simultaneous high-fidelity evaluations.

  • low_fidelity_evaluation_concurrency (int) – Maximum simultaneous low-fidelity evaluations.

  • control_variate_coefficients (ndarray | None) – Optional scalar or componentwise values for fixed mode. If omitted, paired samples estimate them. Pilot mode always estimates and freezes its coefficients.

  • overwrite (bool) – If False, reuse successful evaluations marked by passed.txt; otherwise rerun them.

  • dispatcher (BaseDispatcher | None) – Filesystem/dispatch implementation. Defaults to LocalDispatcher.

  • dry_run (bool) – Prepare inputs without model execution or statistics. Pilot-allocation mode prepares only the initial paired pilot; the final allocation requires pilot QoI evaluations.

  • absolute_uq_directory (str | None)

Returns:

Ordered samples and QoIs, mean estimate, estimator variance and standard error, allocation metadata, correlations, coefficients, and run times.

Return type:

MonteCarloDryRunResult when dry_run is True, otherwise MultifidelityMonteCarloResult

Raises:

  • ValueError – If allocation inputs, costs, or QoI dimensions are invalid.

  • RuntimeError – If either model returns a nonzero status.

Note

Confidence intervals are intentionally not constructed. Callers can use the returned mean and standard error with assumptions appropriate to their application.