Simulation

ExperimentConfig requires a seed and names the independent dimensions as n_replicates and horizon. Common reward coupling is the default paired design; independent policy reward streams are available explicitly.

Results contain read-only arrays and recursively immutable configuration, metadata, and provenance. Use SimulationResult.equals instead of dataclass == for value comparison. JSON and NPZ save methods are atomic, normalize a missing suffix, and return the actual destination path.

Contextual runs record a digest by default. Set record_contexts=True to keep the complete context tensor when downstream auditing requires it.

Reproducible experiment orchestration.

class BackendCompatibilityReport[source]

Bases: object

Complete explanation of whether an experiment can run natively.

issues: tuple[str, ...]
property compatible: bool

Return whether no native compatibility issues were found.

message()[source]

Return one aggregated diagnostic suitable for an exception.

Return type:

str

__init__(issues)
Parameters:

issues (tuple[str, ...])

Return type:

None

class Experiment[source]

Bases: object

Run named policies against a reproducible simulated environment.

__init__(*, environment, policies, config, metadata=None)[source]
Parameters:
Return type:

None

run()[source]

Execute every independent replicate and return an immutable result.

Return type:

SimulationResult

backend_compatibility()[source]

Return every reason this experiment cannot use native execution.

Return type:

BackendCompatibilityReport

class ExperimentConfig[source]

Bases: object

Configuration for independent replicated bandit experiments.

horizon: int
n_replicates: int
seed: int
reward_coupling: str = 'common'
record_contexts: bool = False
backend: Literal['auto', 'rust', 'python'] = 'auto'
__init__(horizon, n_replicates, seed, reward_coupling='common', record_contexts=False, backend='auto')
Parameters:

  • horizon (int)

  • n_replicates (int)

  • seed (int)

  • reward_coupling (str)

  • record_contexts (bool)

  • backend (Literal['auto', 'rust', 'python'])

Return type:

None

Validated immutable simulation results and derived metrics.

class SimulationResult[source]

Bases: object

Read-only observations, ground truth, configuration, and provenance.

rewards: ndarray[tuple[Any, ...], dtype[float64]]
actions: ndarray[tuple[Any, ...], dtype[int64]]
expected_rewards: ndarray[tuple[Any, ...], dtype[float64]]
arm_means: ndarray[tuple[Any, ...], dtype[float64]]
optimal_mask: ndarray[tuple[Any, ...], dtype[bool]]
recommendations: ndarray[tuple[Any, ...], dtype[int64]]
policy_ids: tuple[str, ...]
replicate_seeds: tuple[int, ...]
config: Mapping[str, None | bool | int | float | str | tuple[None | bool | int | float | str | tuple[JSONValue, ...] | Mapping[str, JSONValue], ...] | Mapping[str, None | bool | int | float | str | tuple[JSONValue, ...] | Mapping[str, JSONValue]]]
provenance: RunProvenance
metadata: Mapping[str, None | bool | int | float | str | tuple[None | bool | int | float | str | tuple[JSONValue, ...] | Mapping[str, JSONValue], ...] | Mapping[str, None | bool | int | float | str | tuple[JSONValue, ...] | Mapping[str, JSONValue]]]
contexts: ndarray[tuple[Any, ...], dtype[float64]] | None = None
context_digest: str | None = None
schema_version: int = 3
library_version: str = ''
property n_replicates: int
property horizon: int
property n_policies: int
property n_arms: int
property optimal_values: ndarray[tuple[Any, ...], dtype[float64]]
property regret: ndarray[tuple[Any, ...], dtype[float64]]
property simple_regret: ndarray[tuple[Any, ...], dtype[float64]]
property cumulative_regret_by_replicate: ndarray[tuple[Any, ...], dtype[float64]]
property cumulative_regret: ndarray[tuple[Any, ...], dtype[float64]]
property average_reward_by_step: ndarray[tuple[Any, ...], dtype[float64]]
property cumulative_reward_by_step: ndarray[tuple[Any, ...], dtype[float64]]
property optimal_action_indicator: ndarray[tuple[Any, ...], dtype[bool]]
property optimal_action_rate_by_step: ndarray[tuple[Any, ...], dtype[float64]]
property recommendation_is_optimal: ndarray[tuple[Any, ...], dtype[bool]]
equals(other)[source]

Return value equality using explicit NumPy array semantics.

Parameters:

other (object)

Return type:

bool

to_dict()[source]

Return a schema-versioned JSON-compatible payload.

Return type:

dict[str, object]

classmethod from_dict(payload)[source]

Construct a result through the versioned persistence schema.

Parameters:

payload (Mapping[str, object])

Return type:

SimulationResult

save_npz(path)[source]

Atomically save a compressed result archive and return its path.

Parameters:

path (str | Path)

Return type:

Path

classmethod load_npz(path)[source]

Load and validate a compressed result archive.

Parameters:

path (str | Path)

Return type:

SimulationResult

save_json(path)[source]

Atomically save a JSON result and return its normalized path.

Parameters:

path (str | Path)

Return type:

Path

classmethod load_json(path)[source]

Load and validate a JSON result.

Parameters:

path (str | Path)

Return type:

SimulationResult

to_pandas()[source]

Return a vectorized tidy DataFrame; requires pymab[analysis].

Return type:

Any

__init__(rewards, actions, expected_rewards, arm_means, optimal_mask, recommendations, policy_ids, replicate_seeds, config, provenance, metadata=<factory>, contexts=None, context_digest=None, schema_version=3, library_version='')
Parameters:
Return type:

None

Metrics computed from simulation results.

average_reward_by_step(result)[source]

Mean realized reward per step and policy.

Parameters:

result (SimulationResult)

Return type:

ndarray

best_arm_identification_rate_by_step(result)[source]

Fraction of replicates recommending any optimal arm.

Parameters:

result (SimulationResult)

Return type:

ndarray

cumulative_regret_by_step(result)[source]

Cumulative expected regret averaged across replicates.

Parameters:

result (SimulationResult)

Return type:

ndarray

cumulative_reward_by_step(result)[source]

Cumulative mean realized reward per step and policy.

Parameters:

result (SimulationResult)

Return type:

ndarray

expected_regret_by_step(result)[source]

Expected regret per replicate, step, and policy.

Parameters:

result (SimulationResult)

Return type:

ndarray

moving_average(data, window)[source]

Compute a 1D moving average.

Parameters:
Return type:

ndarray

optimal_action_rate_by_step(result)[source]

Share of replicates selecting an optimal action at each step.

Parameters:

result (SimulationResult)

Return type:

ndarray

simple_regret_by_step(result)[source]

Mean recommendation regret per step and policy.

Parameters:

result (SimulationResult)

Return type:

ndarray