mixle.inference.scenario module

simulate(scenario) -> Simulator – on-the-fly conditional simulators for special scenarios.

See notes/designs/M2.md for the full design: source selection (explicit / registry / auto- designed), why interventions must compose with evidence as do() FIRST then condition() (and how that is realized for a HeterogeneousBayesianNetwork, whose do() result M0’s condition() does not dispatch on), the HMM/state-space temporal-rollout extension past M0’s conditioned window, and the plausibility receipt (the scenario’s evidence log-density under the UNMODIFIED base model).

Distinct from mixle.inference.simulate (Scenario/Simulator/simulate(model)), a narrower, BN-intervention-only tool already consumed by mixle.substrate.act: this module does not touch that one, and is imported under its own names (mixle.inference.scenario.simulate, not re-exported under the same bare name from mixle.inference).

class Scenario(evidence=<factory>, interventions=<factory>, priors=<factory>, horizon=1)

Bases: object

{evidence, interventions, priors, horizon} – what to build a simulator for.

priors is the generic model-source configuration slot (see notes/designs/M2.md): priors["registry"] = (Registry, name, version="latest") to fetch a stored model, or priors["data"] (+ optional priors["llm"]) to auto-design one from scarce scenario data via mixle.task.design.design_model(), when base is not given directly to simulate().

Parameters:

• evidence (dict[tuple[int, ...] | int, Any])

• interventions (dict[tuple[int, ...] | int, Any])

• priors (dict[str, Any])

• horizon (int)

class SimulationReceipt(plausibility, plausibility_method, method, ess=None, ess_ratio=None, composition_order='do-then-condition', warnings=<factory>)

Bases: object

What simulate() actually did: plausibility of the evidence, and the conditioning health.

Parameters:

• plausibility (float | None)

• plausibility_method (str)

• method (str)

• ess (float | None)

• ess_ratio (float | None)

• composition_order (str)

• warnings (list[str])

class FieldPosterior(values)

Bases: object

An empirical marginal for one field, built from rollout draws (.mean()/.std()/.sample()).

Parameters:

values (np.ndarray)

class Simulator(*, base, scenario, seed, n_particles=4096)

Bases: object

A scenario resolved to a runnable generator, with a plausibility + conditioning receipt.

Parameters:

• base (Any)

• scenario (Scenario)

• seed (int | None)

• n_particles (int)

rollout(n=1)

n draws from the resolved scenario (do() applied, evidence conditioned, seed-fixed).

Parameters:

n (int)

Return type:

list[Any]

posterior(field, *, n=2000)

An empirical marginal for one field, from n rollout draws (see class docstring).

Parameters:

• field (tuple[int, ...] | int)

• n (int)

Return type:

FieldPosterior

simulate(scenario, *, base=None, seed=None)

Assemble a generative model for scenario and package it as a Simulator.

Source selection (explicit base, registry, or auto-designed from scenario.priors), do()-then-condition() composition, HMM temporal rollout, and the plausibility receipt are all covered in notes/designs/M2.md.

Parameters:

• scenario (Scenario)

• base (Any | None)

• seed (int | None)

Return type:

Simulator