mcframework.validation.validate_convergence

mcframework.validation.validate_convergence(sim: MonteCarloSimulation, n: int, *, sigma_tol: float = 5.0, confidence: float = 0.99, seed: int = 0, **params: Any) → ConvergenceReport

Check that a simulation’s Monte Carlo estimate converges to its analytic reference.

Parameters:

simMonteCarloSimulation

The simulation to validate. Must implement analytic_reference() to be checkable; otherwise a "no-oracle" report is returned.

nint

Number of simulation draws.

sigma_tolfloat, default 5.0

Tolerance for ConvergenceReport.within_tol, expressed as a multiple of the standard error. The default of 5 sigma makes a fixed-seed check essentially non-flaky while still catching real bugs.

confidencefloat, default 0.99

Confidence level for the interval used by ConvergenceReport.within_ci.

seedint, default 0

Seed applied via set_seed() for reproducible validation.

**paramsAny

Forwarded to both analytic_reference() and run(), so the oracle and the run use identical parameters.

Returns:

ConvergenceReport

The structured outcome. status is "no-oracle" when no reference is declared, else "pass"/"fail" based on ConvergenceReport.within_tol.

Notes

The oracle is threaded through the stats engine as the context target (via run(..., extra_context={"target": oracle})), which also populates bias_to_target/mse_to_target in the result for free.