Skip to content

Macromodel API Reference

This section provides an overview and links to the main API documentation for the macromodel package.

Core Components

  • Country: Country-level aggregation and parameter management
  • Rest of World: External sector and international linkages
  • Economy: Economy-wide coordination and simulation
  • Agents: Economic agents (households, firms, banks, government, etc.)

Markets

Main API Sections

  • Agents: All economic agent classes and their behaviors
  • Country: Country-level aggregation and parameters
  • Economy: System-wide coordination and macro indicators
  • Simulation: Simulation engine and time-stepping

Each section provides detailed documentation for the relevant classes, methods, and functions.

Simulation

macromodel.simulation.Simulation dataclass

A multi-country macroeconomic simulation engine.

This class orchestrates the simulation of multiple interacting economies, including: - Multiple country-level economic models - Rest of world interactions - Global goods market clearing - Exchange rate dynamics

The simulation can be stepped through time, with each iteration updating all economic actors and markets in sequence. Results can be saved for later analysis.

Attributes:

Name Type Description
countries dict[str, Country]

Dictionary of country models, keyed by country code
rest_of_the_world RestOfTheWorld

Model for rest-of-world economic interactions
goods_market GoodsMarket

Global goods market clearing mechanism
exchange_rates ExchangeRates

Exchange rate dynamics between countries
timestep Timestep

Current simulation timestep
configuration SimulationConfiguration

Simulation parameters and settings
initial_year int

Starting year of the simulation
aggregate_country_price_index float

Aggregate price index across all countries
from_datawrapper(datawrapper: DataWrapper, simulation_configuration: SimulationConfiguration) classmethod

Initialize a simulation from preprocessed economic data.

This method creates a new simulation instance using preprocessed data from a DataWrapper object and a simulation configuration. It sets up all countries, markets, and economic relationships based on the provided data and configuration.

Parameters:

Name Type Description Default
datawrapper DataWrapper

Preprocessed economic data for all countries

 required
simulation_configuration SimulationConfiguration

Configuration parameters for the simulation

 required

Returns:

Name Type Description
Simulation

A new simulation instance initialized with the provided data

Raises:

Type Description
ValueError

If a country in the simulation configuration is not found in the data
reset(configuration: Optional[SimulationConfiguration] = None) -> None

Reset the simulation to its initial state.

Resets all simulation components (countries, markets, etc.) to their initial states. Optionally accepts a new configuration to modify simulation parameters during reset.

Parameters:

Name Type Description Default
configuration Optional[SimulationConfiguration]

New configuration to use after reset. If None, uses the current configuration.

 None
iterate()

Execute one timestep of the simulation.

Performs a complete iteration of the economic model, including: 1. Exchange rate updates 2. Country-level economic processes 3. Labor market clearing 4. Housing and credit market clearing 5. Goods market clearing 6. Metric updates and recording

run() -> None

Run the complete simulation for the configured number of timesteps.

Executes the simulation from the current state until t_max iterations have been completed. Each iteration represents one time period in the model.

save(save_dir: Path | str, file_name: str)

Save the complete simulation state to an HDF5 file.

Saves all simulation data including country states, market states, configuration, and random seed state to a file for later analysis or continuation.

Parameters:

Name Type Description Default
save_dir Path | str

Directory to save the file in

 required
file_name str

Name of the output file

 required
shallow_df_dict()

Create a dictionary of shallow (summary) DataFrames for each country.

Returns:

Name Type Description
dict

Dictionary mapping country codes to summary DataFrames
shallow_hdf_save(save_dir: Path | str, file_name: str)

Save a simplified version of the simulation results to an HDF5 file.

Saves summary statistics and key metrics for each country, using less storage space than a full save.

Parameters:

Name Type Description Default
save_dir Path | str

Directory to save the file in

 required
file_name str

Name of the output file

 required
get_country_shallow_output(country: str)

Get summary statistics for a specific country.

Parameters:

Name Type Description Default
country str

Country code to get data for

 required

Returns:

Type Description

pd.DataFrame: DataFrame containing summary statistics for the country