mixle.inference.simulate module

Turn a fitted model into a reusable simulator with scenarios.

A fitted generative model already has sampling behavior. simulate() packages that behavior into a Simulator that can produce baseline synthetic data and, for learned Bayesian networks, named intervention scenarios.

Non-graph models simulate from their baseline distribution. Interventions require the causal structure exposed by HeterogeneousBayesianNetwork.

Every draw count is an exact positive integer and every run returns exactly that many records: a Monte Carlo precision claim, an effect comparison, or a receipt that says n trials were run is only worth what the realized sample size is, so an underproducing generator raises IncompleteSimulationError rather than silently shrinking the experiment.

exception IncompleteSimulationError(message, records, requested)

Bases: RuntimeError

A generator produced a different number of records than the experiment requested.

records holds what it did produce and requested the size that was asked for, so a caller can decide what to do with a short run instead of summarizing it as though it were the full one.

Parameters:

• message (str)

• records (list[Any])

• requested (int)

Return type:

None

class Scenario(name, interventions=<factory>)

Bases: object

A named simulation condition: which fields are clamped to which values (an intervention).

Parameters:

• name (str)

• interventions (dict[int, Any])

class Simulator(model)

Bases: object

A fitted model packaged as a data generator, runnable under a baseline or named scenarios.

Parameters:

model (Any)

scenario(name, interventions)

Register a named intervention scenario (requires a learned Bayesian network to apply).

Parameters:

• name (str)

• interventions (dict[int, Any])

Return type:

Simulator

run(n=100, *, scenario=None, interventions=None, seed=0)

Generate exactly n synthetic records under the baseline, a registered scenario, or ad-hoc interventions.

n must be an exact positive integer. Raises IncompleteSimulationError if the underlying generator yields a different number of records than requested.

Parameters:

• n (int)

• scenario (str | None)

• interventions (dict[int, Any] | None)

• seed (int)

Return type:

list[Any]

outcome_mean(field_index, *, scenario=None, n=2000, seed=0)

The mean of a numeric field over exactly n draws – the quantity to compare across conditions.

The run is size-checked first (see run()), so the returned mean is always over n observations rather than over however many the generator happened to yield.

Parameters:

• field_index (int)

• scenario (str | None)

• n (int)

• seed (int)

Return type:

float

compare(field_index, scenario_a, scenario_b, *, n=4000, seed=0)

mean(field | scenario_a) - mean(field | scenario_b) – the simulated effect of A vs B.

Parameters:

• field_index (int)

• scenario_a (str | None)

• scenario_b (str | None)

• n (int)

• seed (int)

Return type:

float

simulate(model)

Package a fitted model as a Simulator (see module docstring).

Parameters:

model (Any)

Return type:

Simulator