Uncertainty Quantification Workflows
====================================

Monte Carlo
-----------

``run_monte_carlo`` evaluates a :class:`~romtools.workflows.models.QoiModel`
at samples generated by a
:class:`~romtools.workflows.parameter_spaces.ParameterSpace`. It returns the
componentwise sample mean, variance, standard deviation, and standard error.

.. code-block:: python

   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:

.. code-block:: python

   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.

.. code-block:: python

   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

.. math::

   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
:doc:`demos/uq_cdr_demo`.

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

.. autosummary::
   :toctree: generated

   romtools.workflows.uq.run_monte_carlo
   romtools.workflows.uq.run_multifidelity_monte_carlo
   romtools.workflows.uq.MonteCarloResult
   romtools.workflows.uq.MultifidelityMonteCarloResult