Engine

The core simulation engine. The simulate() function is the main entry point for running Monte Carlo simulations.

SimulationResult

SimulationResult dataclass

Output of a simulation run.

simulate

simulate(plan, market, policies, sim_config)

Run a Monte Carlo simulation.

Parameters:

Name	Type	Description	Default
plan	PlanConfig	Financial plan configuration.	required
market	MarketAssumptions	Market return and inflation assumptions.	required
policies	PolicyBundle	Spending, withdrawal, and rebalancing policies.	required
sim_config	SimulationConfig	Simulation execution parameters.	required

Returns:

Type	Description
SimulationResult	SimulationResult with success probability, percentiles, and time series.

Timeline

Timeline dataclass

Monthly time grid derived from plan ages.

Attributes:

Name	Type	Description
current_age	int	Starting age in years.
retirement_age	int	Retirement age in years.
end_age	int	End of simulation age in years.
income_end_age	int	Age when earned income stops.
n_steps	int	Total number of monthly steps.
retirement_step	int	Step index when retirement begins.
income_end_step	int	Step index when income stops.

from_ages(current_age, retirement_age, end_age, income_end_age=None) classmethod

Create a Timeline from age parameters.

is_retired(step)

Check if the simulation is in the retirement phase at a given step.

has_income(step)

Check if earned income is active at a given step.

age_at(step)

Return the age (as a float) at a given step.

month_of_year(step)

Return the calendar month (1-12) at a given step.

Assumes the simulation starts in January.

SimulationState

SimulationState dataclass

Mutable state for all paths at a given time step.

Uses plain numpy arrays for performance. NOT Pydantic — this is mutated every step in the hot loop.

Attributes:

Name	Type	Description
positions	NDArray[floating[Any]]	(n_paths, n_accounts, n_assets) dollar holdings per asset within each account.
cumulative_inflation	NDArray[floating[Any]]	(n_paths,) cumulative inflation factor (starts at 1.0).
is_depleted	NDArray[bool_]	(n_paths,) boolean mask for paths with zero total wealth.
step	int	Current time step index.
n_paths	int	Number of simulation paths.
n_accounts	int	Number of accounts.
n_assets	int	Number of asset classes.
account_types	list[str]	List of account type strings.

balances property

Account balances, shape (n_paths, n_accounts).

Derived from positions by summing over assets.

total_wealth property

Total wealth across all accounts, shape (n_paths,).

initialize(n_paths, initial_balances, account_types, target_weights) classmethod

Create initial simulation state.

Each account's balance is distributed across assets according to target_weights.

Parameters:

Name	Type	Description	Default
n_paths	int	Number of simulation paths.	required
initial_balances	list[float]	Starting balance for each account.	required
account_types	list[str]	Account type labels.	required
target_weights	NDArray[floating[Any]]	(n_assets,) target asset allocation weights summing to 1.	required

RNG

make_rng(seed)

Create a deterministic numpy Generator from a seed.

Uses PCG64DXSM for high-quality, reproducible random number generation.