Uncertainty Quantification Workflows#

Monte Carlo#

run_monte_carlo evaluates a QoiModel at samples generated by a ParameterSpace. It returns the componentwise sample mean, variance, standard deviation, and standard error.

from romtools.workflows.uq import run_monte_carlo

result = run_monte_carlo(
    qoi_model,
    parameter_space,
    "/absolute/path/to/mc",
    number_of_samples=100,
    random_seed=7,
)
print(result.mean, result.standard_error)

Multifidelity Monte Carlo#

The two-level multifidelity workflow uses paired high- and low-fidelity QoIs as a control variate. Fixed allocation accepts both sample counts directly:

from romtools.workflows.uq import run_multifidelity_monte_carlo

result = run_multifidelity_monte_carlo(
    high_fidelity_model,
    low_fidelity_model,
    parameter_space,
    "/absolute/path/to/mfmc",
    number_of_high_fidelity_samples=20,
    number_of_low_fidelity_samples=200,
    low_to_high_fidelity_cost_ratio=0.05,
)

Pilot allocation#

Pilot mode evaluates both models at an initial paired set, estimates their correlation and control-variate coefficient, and selects integer final sample counts under a high-fidelity-equivalent budget. The pilot evaluations count toward both the final sample counts and the budget.

result = run_multifidelity_monte_carlo(
    high_fidelity_model,
    low_fidelity_model,
    parameter_space,
    "/absolute/path/to/pilot-mfmc",
    pilot_sample_count=10,
    high_fidelity_equivalent_budget=100.0,
    low_to_high_fidelity_cost_ratio=0.05,
    allocation_qoi_index=0,
)

The budget constraint is

\[N_H + (c_L/c_H)N_L \leq B.\]

If the pilot predicts that purchasing more low-fidelity samples is no better than using the remaining budget for high-fidelity Monte Carlo, the workflow automatically falls back to that estimator. For vector-valued QoIs, allocation_qoi_index selects the component used to allocate samples while statistics and control-variate coefficients are still returned for every component. If low_to_high_fidelity_cost_ratio is omitted, pilot mode estimates it from measured model run times.

A complete single- and multifidelity example using the existing steady convection-diffusion-reaction model is available in Monte Carlo UQ for Convection-Diffusion-Reaction.

Results and restart behavior#

Each workflow returns a result dataclass and saves the same statistics and allocation metadata in uq_stats.npz. Individual successful evaluations are marked in their run directories and reused unless overwrite=True.

API#

`romtools.workflows.uq.run_monte_carlo`(model, ...)	Estimate the mean of a model QoI by Monte Carlo sampling.
`romtools.workflows.uq.run_multifidelity_monte_carlo`(...)	Estimate a QoI mean using two-level multifidelity Monte Carlo.
`romtools.workflows.uq.MonteCarloResult`(...)	Outputs from a Monte Carlo QoI-mean estimate.
`romtools.workflows.uq.MultifidelityMonteCarloResult`(...)	Outputs from a fixed or pilot-allocated two-level MFMC estimate.