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.

This class focuses on simulation without model solving, and depends on dynamic equations, shocks, and decision rules paased into it.

The purpose of this class is to provide a way to simulate models without relying on inheritance from the AgentType class.

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])
block (DBlock) – Has shocks, dynamics, and rewards
dr (Mapping[str, Callable])
initial (dict)
seed (int) – A seed for this instance’s random number generator.

agent_count¶

The number of agents of this type to use in simulation.

Type:: int

T_sim¶

The number of periods to simulate.

Type:: int

clear_history()¶: Clears the histories.

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

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

make_shock_history()¶

Makes a pre-specified history of shocks for the simulation. Shock variables should be named in self.shock, a mapping from shock names to distributions. This method runs a subset of the standard simulation loop by simulating only mortality and shocks; each variable named in shocks is stored in a T_sim x agent_count array in history dictionary self.history[X]. Automatically sets self.read_shocks to True so that these pre-specified shocks are used for all subsequent calls to simulate().

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

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

sim_birth(which_agents)¶

Makes new agents for the simulation. Takes a boolean array as an input, indicating which agent indices are to be “born”. Does nothing by default, must be overwritten by a subclass.

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

sim_one_period()¶: Simulates one period for this type. Calls the methods get_mortality(), get_shocks() or read_shocks, get_states(), get_controls(), and get_poststates(). These should be defined for AgentType subclasses, except get_mortality (define its components sim_death and sim_birth instead) and read_shocks.

simulate(sim_periods=None)¶

Simulates this agent type for a given number of periods. Defaults to self.T_sim if no input. Records histories of attributes named in self.track_vars in self.history[sym].

Parameters:: None
Returns:: history – The history tracked during the simulation.
Return type:: dict

state_vars = []¶

MonteCarloSimulator¶

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

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

Bases: Simulator

A Monte Carlo simulation engine based.

Unlike the AgentTypeMonteCarloSimulator, this class does make any assumptions about aging or mortality. It operates only on model information passed in as blocks.

It also does not have read_shocks functionality; it is a strict subset of the AgentTypeMonteCarloSimulator functionality.

Parameters:

calibration (Mapping[str, Any])
block (DBlock) – Has shocks, dynamics, and rewards
dr (Mapping[str, Callable])
initial (dict)
seed (int) – A seed for this instance’s random number generator.

agent_count¶

The number of agents of this type to use in simulation.

Type:: int

T_sim¶

The number of periods to simulate.

Type:: int

clear_history()¶: Clears the histories.

initialize_sim()¶: Prepares for a new simulation. Resets the internal random number generator, makes initial states for all agents (using sim_birth), 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. Takes a boolean array as an input, indicating which agent indices are to be “born”. Does nothing by default, must be overwritten by a subclass.

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

sim_one_period()¶: Simulates one period for this type. Calls the methods get_mortality(), get_shocks() or read_shocks, get_states(), get_controls(), and get_poststates(). These should be defined for AgentType subclasses, except get_mortality (define its components sim_death and sim_birth instead) and read_shocks.

simulate(sim_periods=None)¶

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

Records histories of attributes named in self.track_vars in self.history[symame].

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

state_vars = []¶

Base Simulator¶

class skagent.simulation.monte_carlo.Simulator¶: Bases: object

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.