romtools.workflows.uq.run_monte_carlo#

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.