Simulation¶

This section contains the API documentation for simulation tools and analysis functions.

Monte Carlo Simulation¶

The simulation module provides Monte Carlo simulation engines for economic models.

AgentTypeMonteCarloSimulator¶

A Monte Carlo simulation engine inspired by agent-based modeling frameworks. This simulator includes aging and mortality assumptions.

class skagent.simulation.monte_carlo.AgentTypeMonteCarloSimulator(calibration, block, dr, initial, seed=0, agent_count=1, T_sim=10)¶

Bases: Simulator

A Monte Carlo simulation engine for agent-based economic models with aging and mortality.

This class extends the base Simulator with: - Age tracking for agents - Mortality handling (agents die when live state <= 0) - Age-varying calibration and decision rules - Pre-specified shock history support

This simulator makes assumptions about population birth and mortality which are not generic. All agents are replaced with newborns when they expire.

Parameters:

calibration (Mapping[str, Any]) – Model calibration parameters
block (DBlock) – Has shocks, dynamics, and rewards
dr (Mapping[str, Callable]) – Decision rules for control variables
initial (dict) – Initial state distributions
seed (int) – A seed for this instance’s random number generator
agent_count (int) – The number of agents to simulate
T_sim (int) – The number of periods to simulate

get_mortality()¶: Simulates mortality or agent turnover. Agents die when their state live is less than or equal to zero.

initialize_sim()¶: Prepares for a new simulation with age tracking.

make_shock_history()¶

Makes a pre-specified history of shocks for the simulation.

This method runs the simulation loop and stores shock values, then sets read_shocks to True so these shocks are used in future simulations.

Returns:: shock_history – The subset of simulation history that are the shocks for each agent and time.
Return type:: dict

sim_birth(which_agents)¶

Makes new agents for the simulation with age tracking.

Parameters:: which_agents (np.array(Bool)) – Boolean array of size self.agent_count indicating which agents should be “born”.

sim_one_period()¶: Simulates one period with mortality and age-varying parameters.

MonteCarloSimulator¶

A simplified Monte Carlo simulation engine that doesn’t make assumptions about aging or mortality.

skagent.simulation.monte_carlo.MonteCarloSimulator¶: alias of Simulator

Base Simulator¶

class skagent.simulation.monte_carlo.Simulator(calibration, block, dr, initial, seed=0, agent_count=1, T_sim=10)¶

Bases: object

Base class for Monte Carlo simulation engines.

Provides common functionality for simulation including: - RNG management and seeding - State variable tracking - History management - Simulation loop structure

Parameters:

calibration (Mapping[str, Any]) – Model calibration parameters
block (DBlock) – Has shocks, dynamics, and rewards
dr (Mapping[str, Callable]) – Decision rules for control variables
initial (dict) – Initial state distributions
seed (int) – A seed for this instance’s random number generator
agent_count (int) – The number of agents to simulate
T_sim (int) – The number of periods to simulate

clear_history()¶: Clears the histories.

initialize_sim()¶: Prepares for a new simulation. Resets the internal random number generator, makes initial states for all agents, clears histories of tracked variables.

reset_rng()¶: Reset the random number generator for this type.

sim_birth(which_agents)¶

Makes new agents for the simulation.

Parameters:: which_agents (np.array(Bool)) – Boolean array of size self.agent_count indicating which agents should be “born”.

sim_one_period()¶: Simulates one period for this type. Subclasses may override to add mortality/aging logic.

simulate(sim_periods=None)¶

Simulates this agent type for a given number of periods. Defaults to self.T_sim if no input.

Parameters:: sim_periods (int, optional) – Number of periods to simulate.
Returns:: history – The history tracked during the simulation.
Return type:: dict

state_vars = []¶

Simulation Utility Functions¶

Drawing Shocks¶

skagent.simulation.monte_carlo.draw_shocks(shocks, conditions=(), n=None, rng=None)¶

Draw from each shock distribution values, subject to given conditions.

Parameters:

Mapping[str (shocks) – A dictionary-like mapping from shock names to distributions from which to draw
Distribution] – A dictionary-like mapping from shock names to distributions from which to draw
conditions (Sequence[int]) – An array of conditions, one for each agent. Typically these will be agent ages. # TODO: generalize this to wider range of inputs.
n (int (optional)) – Number of draws to do. An alternative to a conditions sequence.
rng (np.random.Generator, optional) – Random number generator to use for drawing. If provided, will be used for distributions that support it.
shocks (Mapping[str, Distribution])

Returns:

draws – A mapping from shock names to drawn shock values.

Return type:

Mapping[str, Sequence]

Age-Varying Calibration¶

skagent.simulation.monte_carlo.calibration_by_age(ages, calibration)¶

Returns calibration for this model, but with vectorized values which map age-varying values to agent ages.

Parameters:

ages (np.array) – An array of agent ages.
calibration (dict) – A calibration dictionary

Returns:

aged_calibration – A dictionary of parameter values. If a parameter is age-varying, the value is a vector corresponding to the values for each input age.

Return type:

dict

Example Usage¶

Basic Simulation¶

import skagent as ska
from skagent.models.consumer import consumption_block, calibration

# Set up decision rules (simplified example)
dr = {"c": lambda m: 0.9 * m}

# Initialize simulation
simulator = ska.MonteCarloSimulator(
    calibration=calibration,
    block=consumption_block,
    dr=dr,
    initial={"k": 1.0, "p": 1.0},
    agent_count=1000,
    T_sim=50,
)

# Run simulation
results = simulator.simulate()

Agent-Type Simulation with Aging¶

# For models with aging and mortality
simulator = ska.AgentTypeMonteCarloSimulator(
    calibration=calibration,
    block=consumption_block,
    dr=dr,
    initial={"k": 1.0, "p": 1.0},
    agent_count=1000,
    T_sim=50,
)

results = simulator.simulate()

This page is under construction. Content will be added as the API develops.