Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/salesforce/ai-economist/llms.txt

Use this file to discover all available pages before exploring further.

The COVID-19 & Economy simulation jointly models infection dynamics and economic activity. It is built on empirical data and fitted epidemiological and economic models drawn from the real-world trajectory of the COVID-19 pandemic in the United States.
This simulation requires an activation code. When you instantiate CovidAndEconomyEnvironment, verify_activation_code() is called automatically. See the ethical review below for context on why this requirement exists.

​
What the simulation models

The environment comprises 51 agents — each representing a US state or Washington D.C. — and one federal government planner. At each timestep (one day):
  • State agents set the stringency level of their pandemic policy response (e.g. lockdown intensity).
  • The federal government provides direct payment subsidies to eligible individuals.
  • Infection dynamics follow a fitted SIR (Susceptible-Infected-Recovered) model.
  • Economic productivity is driven by the fraction of the working-age population that is employed and not too sick to work.
The simulation can operate in three modes:
Modeuse_real_world_datause_real_world_policiesDescription
Fully fittedFalseFalseFitted models drive both health and economic dynamics
Real-world policiesFalseTrueReal policy stringency levels are replayed; dynamics from fitted models
Full replayTrueTrueBoth dynamics and policies match historical data exactly

​
Scenario registration

The scenario is registered under the name: 
CovidAndEconomySimulation
The Python class is CovidAndEconomyEnvironment, defined in: 
ai_economist/foundation/scenarios/covid19/covid19_env.py

​
Key parameters

ParameterTypeDefaultDescription
use_real_world_databoolFalseReplay real-world SIR, unemployment, policy, and vaccination data
use_real_world_policiesboolFalseReplay historical policy stringency levels
path_to_data_and_fitted_paramsstr""Path to the directory containing fitted parameters and real-world data. Defaults to the bundled dataset.
start_datestr"2020-03-22"Simulation start date in YYYY-MM-DD format
pop_between_age_18_65float0.6Fraction of the population in the working-age bracket
infection_too_sick_to_work_ratefloat0.1Fraction of infected individuals unable to work
risk_free_interest_ratefloat0.03Interest rate at which the federal government borrows for direct payments
economic_reward_crra_etafloat2CRRA eta parameter for economic reward non-linearity
health_priority_scaling_agentsfloat1How much state agents weight health over the economy relative to the real world (1 = real-world calibration)
health_priority_scaling_plannerfloat1Same as above for the federal government
reward_normalization_factorfloat1Scalar applied to all rewards before returning them

​
Real-world data and fitted parameters

The bundled dataset is located at: 
ai_economist/datasets/covid19_datasets/data_and_fitted_params/
It includes:
  • real_world_data.npz: Historical SIR, unemployment, government policy stringency, and vaccination time series for all 51 US regions.
  • Fitted epidemiological and economic model parameters, loaded at init via load_model_constants() and load_fitted_params().
To re-derive the fitted parameters from raw data, run the notebook: 
ai_economist/datasets/covid19_datasets/gather_real_world_data_and_fit_parameters.ipynb

​
GPU acceleration with WarpDrive

The COVID-19 simulation supports CUDA C acceleration via WarpDrive. When a GPU is available, the simulation automatically imports WarpDrive constants and data feeds: 
from warp_drive.utils.constants import Constants
from warp_drive.utils.data_feed import DataFeed
If no GPU is detected, the simulation falls back to CPU execution automatically. Install WarpDrive with: 
pip install rl-warp-drive

​
Instantiating the environment

import ai_economist.foundation as foundation

env_config = {
    "scenario_name": "CovidAndEconomySimulation",
    "episode_length": 540,          # ~18 months of daily timesteps
    "n_agents": 51,                 # 50 US states + Washington D.C.

    # Data and policy mode
    "use_real_world_data": False,
    "use_real_world_policies": False,
    "start_date": "2020-03-22",

    # Population parameters
    "pop_between_age_18_65": 0.6,
    "infection_too_sick_to_work_rate": 0.1,

    # Economic parameters
    "risk_free_interest_rate": 0.03,
    "economic_reward_crra_eta": 2,

    # Policy priority weights (1.0 = real-world calibration)
    "health_priority_scaling_agents": 1.0,
    "health_priority_scaling_planner": 1.0,
}

env = foundation.make_env_instance(**env_config)
obs = env.reset()
When use_real_world_data=True, you must also set use_real_world_policies=True. If use_real_world_policies=True, the episode_length cannot exceed the number of available real-world policy timesteps from start_date.

​
Observation and reward structure

State agents observe:
  • Current SIR state (susceptible, infected, recovered fractions)
  • Current unemployment rate
  • Current and recent policy stringency levels
  • Subsidy amounts received
  • Time index
The federal government observes the aggregate state across all 51 regions. Rewards balance health outcomes and economic productivity. The relative weight between health and economy is controlled by health_priority_scaling_agents and health_priority_scaling_planner.

​
Ethical review

This simulation was designed with care. Before using it in research or policy work, please review:

​
Tutorials

COVID-19 and economic simulation

Introduction to the simulation and how to study health and economic policy trade-offs.

Multi-agent GPU training with WarpDrive

Use WarpDrive for high-throughput GPU-accelerated training on this scenario.

Build docs developers (and LLMs) love

Get started for freeTalk to us