Skip to main content

Foundation: An Economics Simulation Framework

Project description

Foundation: An Economic Simulation Framework

This repo contains an implementation of Foundation, a framework for flexible, modular, and composable environments that model socio-economic behaviors and dynamics in a society with both agents and governments.

Foundation provides a Gym-style API:

  • reset: resets the environment's state and returns the observation.
  • step: advances the environment by one timestep, and returns the tuple (observation, reward, done, info).

This simulation can be used in conjunction with reinforcement learning to learn optimal economic policies, as detailed in the following papers:

The AI Economist: Improving Equality and Productivity with AI-Driven Tax Policies, Stephan Zheng, Alexander Trott, Sunil Srinivasa, Nikhil Naik, Melvin Gruesbeck, David C. Parkes, Richard Socher.

The AI Economist: Optimal Economic Policy Design via Two-level Deep Reinforcement Learning Stephan Zheng, Alexander Trott, Sunil Srinivasa, David C. Parkes, Richard Socher.

Building a Foundation for Data-Driven, Interpretable, and Robust Policy Design using the AI Economist Alexander Trott, Sunil Srinivasa, Douwe van der Wal, Sebastien Haneuse, Stephan Zheng.

If you use this code in your research, please cite us using this BibTeX entry:

 Author = {Stephan Zheng, Alexander Trott, Sunil Srinivasa, Nikhil Naik, Melvin Gruesbeck, David C. Parkes, Richard Socher},
 Title = {The AI Economist: Improving Equality and Productivity with AI-Driven Tax Policies},
 Year = {2020},
 Eprint = {arXiv:2004.13332},

For more information and context, check out:

Simulation Cards: Ethics Review and Intended Use

Please see our Simulation Card for a review of the intended use and ethical review of our framework.

Please see our COVID-19 Simulation Card for a review of the ethical aspects of the pandemic simulation (and as fitted for COVID-19).

Join us on Slack

If you're interested in extending this framework, discussing machine learning for economics, and collaborating on research project:

Installation Instructions

To get started, you'll need to have Python 3.7+ installed.

Using pip

Simply use the Python package manager:

pip install ai-economist

Installing from Source

  1. Clone this repository to your local machine:
 git clone
  1. Create a new conda environment (named "ai-economist" below - replace with anything else) and activate it
 conda create --name ai-economist python=3.7 --yes
 conda activate ai-economist
  1. Either

    a) Edit the PYTHONPATH to include the ai-economist directory

 export PYTHONPATH=<local path to ai-economist>:$PYTHONPATH


b) Install as an editable Python package

 cd ai-economist
 pip install -e .

Useful tip: for quick access, add the following to your ~/.bashrc or ~/.bash_profile:

alias aiecon="conda activate ai-economist; cd <local path to ai-economist>"

You can then simply run aiecon once to activate the conda environment.

Testing your Install

To test your installation, try running:

conda activate ai-economist
python -c "import ai_economist"

Getting Started

To familiarize yourself with Foundation, check out the tutorials in the tutorials folder. You can run these notebooks interactively in your browser on Google Colab.

Multi-Agent Simulations

Multi-Agent Training

To run these notebooks locally, you need Jupyter. See for installation instructions and ( for examples of how to work with Jupyter.

Structure of the Code

  • The simulation is located in the ai_economist/foundation folder.

The code repository is organized into the following components:

Component Description
base Contains base classes to can be extended to define Agents, Components and Scenarios.
agents Agents represent economic actors in the environment. Currently, we have mobile Agents (representing workers) and a social planner (representing a government).
entities Endogenous and exogenous components of the environment. Endogenous entities include labor, while exogenous entity includes landmarks (such as Water and Grass) and collectible Resources (such as Wood and Stone).
components Components are used to add some particular dynamics to an environment. They also add action spaces that define how Agents can interact with the environment via the Component.
scenarios Scenarios compose Components to define the dynamics of the world. It also computes rewards and exposes states for visualization.
  • The datasets (including the real-world data on COVID-19) are located in the ai_economist/datasets folder.

Releases and Contributing

  • Please let us know if you encounter any bugs by filing a GitHub issue.
  • We appreciate all your contributions. If you plan to contribute new Components, Scenarios Entities, or anything else, please see our contribution guidelines.


For the complete release history, see


Foundation and the AI Economist are released under the BSD-3 License.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ai-economist-1.7.1.tar.gz (111.3 kB view hashes)

Uploaded source

Built Distribution

ai_economist-1.7.1-py3-none-any.whl (1.1 MB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page