mcframework.core.MonteCarloFramework

class mcframework.core.MonteCarloFramework

Bases: object

Registry for named simulations that runs and compares results.

Orchestrates multiple MonteCarloSimulation instances.

Examples

>>> from mcframework.core import MonteCarloFramework, MonteCarloSimulation
>>> class MySim(MonteCarloSimulation):
...     def single_simulation(self, _rng=None):
...         rng = self._rng(_rng, self.rng)
...         return float(rng.normal())
...
>>> sim1 = MySim(name="NormalSim")
>>> sim2 = MySim(name="AnotherSim")
>>> framework = MonteCarloFramework()
>>> framework.register_simulation(sim1)
>>> framework.register_simulation(sim2)
>>> res1 = framework.run_simulation("NormalSim", 10000, backend="auto")
>>> res2 = framework.run_simulation("AnotherSim", 10000)
>>> comparison = framework.compare_results(["NormalSim", "AnotherSim"], metric="mean")
>>> print(comparison)
{'NormalSim': 0.01234, 'AnotherSim': -0.05678}

Methods

compare_results	Compare a metric across previously run simulations.
register_simulation	Register a simulation instance under a name.
run_simulation	Run a registered simulation by name.

compare_results(names: list[str], metric: str = 'mean') → dict[str, float]

Compare a metric across previously run simulations.

Parameters:

nameslist of str

Simulation names (must exist in self.results).

metric{“mean”,”std”,”var”,”se”,”pX”}, default "mean"

Metric to extract. "pX" requests the X-th percentile (e.g. "p95").

Returns:

dict

{name: value} pairs.

Raises:

ValueError

If a requested percentile was not part of the user’s requested set at run time (enforced via result.metadata["requested_percentiles"]), or if the metric name is unknown.

register_simulation(simulation: MonteCarloSimulation, name: str | None = None)

Register a simulation instance under a name.

Parameters:

simulationMonteCarloSimulation

The simulation instance to register.

namestr, optional

If omitted, simulation.name is used.

run_simulation(name: str, n_simulations: int, **kwargs) → SimulationResult

Run a registered simulation by name.

Parameters:

namestr

Key used in register_simulation().

n_simulationsint

Number of draws.

**kwargsAny

Forwarded to MonteCarloSimulation.run().

Returns:

SimulationResult

__init__()

classmethod __new__(*args, **kwargs)