romtools.workflows.uq#

Monte Carlo uncertainty-quantification workflows.

class romtools.workflows.uq.MonteCarloResult(parameter_samples, qoi_values, mean, variance, standard_deviation, standard_error, run_times)[source]#

Bases: object

Outputs from a Monte Carlo QoI-mean estimate.

variance and standard_deviation describe the sampled QoI distribution. standard_error describes uncertainty in the estimated mean and equals standard_deviation / sqrt(number_of_samples). Each array has one entry per flattened QoI component.

Parameters:

  • parameter_samples (ndarray)

  • qoi_values (ndarray)

  • mean (ndarray)

  • variance (ndarray)

  • standard_deviation (ndarray)

  • standard_error (ndarray)

  • run_times (ndarray)

class romtools.workflows.uq.MultifidelityMonteCarloResult(parameter_samples, high_fidelity_qoi_values, low_fidelity_qoi_values, mean, variance, standard_error, control_variate_coefficients, paired_correlations, high_fidelity_sample_count, low_fidelity_sample_count, pilot_sample_count, low_to_high_fidelity_cost_ratio, high_fidelity_equivalent_cost, used_multifidelity_estimator, high_fidelity_run_times, low_fidelity_run_times)[source]#

Bases: object

Outputs from a fixed or pilot-allocated two-level MFMC estimate.

variance is the estimated variance of the multifidelity mean estimator, rather than the variance of the underlying QoI distribution. The first high_fidelity_sample_count rows of low_fidelity_qoi_values are paired with the high-fidelity values.

Parameters:

  • parameter_samples (ndarray)

  • high_fidelity_qoi_values (ndarray)

  • low_fidelity_qoi_values (ndarray)

  • mean (ndarray)

  • variance (ndarray)

  • standard_error (ndarray)

  • control_variate_coefficients (ndarray)

  • paired_correlations (ndarray)

  • high_fidelity_sample_count (int)

  • low_fidelity_sample_count (int)

  • pilot_sample_count (int | None)

  • low_to_high_fidelity_cost_ratio (float)

  • high_fidelity_equivalent_cost (float)

  • used_multifidelity_estimator (bool)

  • high_fidelity_run_times (ndarray)

  • low_fidelity_run_times (ndarray)

romtools.workflows.uq.run_monte_carlo(model, parameter_space, absolute_work_dir=None, number_of_samples=None, random_seed=1, evaluation_concurrency=1, overwrite=False, dispatcher=None, *, absolute_uq_directory=None, dry_run=False)[source]#

Estimate the mean of a model QoI by Monte Carlo sampling.

For every generated parameter sample, the workflow calls the three QoiModel methods in order: populate_run_directory, run_model, and compute_qoi. Scalar and array-valued QoIs are accepted; array-valued outputs are flattened and statistics are computed componentwise.

Parameters:

  • model (QoiModel) – Model implementing the QoiModel protocol.

  • parameter_space (ParameterSpace) – Distribution used to generate independent parameter samples. Its parameter names define the dictionary passed to the model methods.

  • absolute_work_dir (str | None) – Absolute output path. Sample i is evaluated in run_i and aggregate results are saved to uq_stats.npz.

  • number_of_samples (int | None) – Number of model evaluations. Must be at least two.

  • random_seed (int) – Seed forwarded to parameter_space.generate_samples.

  • evaluation_concurrency (int) – Maximum simultaneous model evaluations. A spawn-based process pool is used above one, so the model and dispatcher must be pickleable.

  • overwrite (bool) – If False, reuse run directories containing passed.txt. If True, populate and evaluate every sample.

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

  • dry_run (bool) – Prepare run directories and inputs without executing models, computing QoIs, or writing aggregate statistics.

  • absolute_uq_directory (str | None)

Returns:

Samples, flattened QoI values, sample moments, standard errors, and measured model run times.

Return type:

MonteCarloDryRunResult when dry_run is True, otherwise MonteCarloResult

Raises:

  • ValueError – If inputs or returned QoI dimensions are invalid.

  • RuntimeError – If a model evaluation returns a nonzero status.

Note

A successful marker is written only after both run_model and compute_qoi complete. Reused evaluations have NaN run times because their original timings are not reconstructed.

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.

Modules

monte_carlo

Monte Carlo and two-level multifidelity Monte Carlo workflows.

sample_allocation

Pilot-based sample allocation for two-level MFMC.

statistics

Statistical estimators used by Monte Carlo UQ workflows.