Metadata-Version: 2.1
Name: ai-economist
Version: 1.7.1
Summary: Foundation: An Economics Simulation Framework
Home-page: https://github.com/salesforce/ai-economist
Author: Stephan Zheng, Alex Trott, Sunil Srinivasa
Author-email: stephan.zheng@salesforce.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: appdirs (==1.4.4)
Requires-Dist: appnope (==0.1.2)
Requires-Dist: argon2-cffi (==20.1.0)
Requires-Dist: astroid (==2.5.6)
Requires-Dist: async-generator (==1.10)
Requires-Dist: attrs (==21.2.0)
Requires-Dist: backcall (==0.2.0)
Requires-Dist: beautifulsoup4 (==4.9.3)
Requires-Dist: black (==21.5b1)
Requires-Dist: bleach (==3.3.0)
Requires-Dist: bs4 (==0.0.1)
Requires-Dist: certifi (==2020.12.5)
Requires-Dist: cffi (==1.14.5)
Requires-Dist: chardet (==4.0.0)
Requires-Dist: click (==8.0.1)
Requires-Dist: cycler (==0.10.0)
Requires-Dist: decorator (==5.0.9)
Requires-Dist: defusedxml (==0.7.1)
Requires-Dist: entrypoints (==0.3)
Requires-Dist: et-xmlfile (==1.1.0)
Requires-Dist: flake8 (==3.9.2)
Requires-Dist: GPUtil (==1.4.0)
Requires-Dist: idna (==2.10)
Requires-Dist: iniconfig (==1.1.1)
Requires-Dist: ipykernel (==5.5.5)
Requires-Dist: ipython (==7.31.1)
Requires-Dist: ipython-genutils (==0.2.0)
Requires-Dist: ipywidgets (==7.6.3)
Requires-Dist: isort (==5.8.0)
Requires-Dist: jedi (==0.18.0)
Requires-Dist: Jinja2 (==3.0.1)
Requires-Dist: jsonschema (==3.2.0)
Requires-Dist: jupyter (==1.0.0)
Requires-Dist: jupyter-client (==6.1.12)
Requires-Dist: jupyter-console (==6.4.0)
Requires-Dist: jupyter-core (==4.7.1)
Requires-Dist: jupyterlab-pygments (==0.1.2)
Requires-Dist: jupyterlab-widgets (==1.0.0)
Requires-Dist: kiwisolver (==1.3.1)
Requires-Dist: lazy-object-proxy (==1.6.0)
Requires-Dist: lz4 (==3.1.3)
Requires-Dist: MarkupSafe (==2.0.1)
Requires-Dist: matplotlib (==3.2.1)
Requires-Dist: matplotlib-inline (==0.1.2)
Requires-Dist: mccabe (==0.6.1)
Requires-Dist: mistune (==0.8.4)
Requires-Dist: mypy-extensions (==0.4.3)
Requires-Dist: nbclient (==0.5.3)
Requires-Dist: nbconvert (==6.0.7)
Requires-Dist: nbformat (==5.1.3)
Requires-Dist: nest-asyncio (==1.5.1)
Requires-Dist: notebook (==6.4.1)
Requires-Dist: numpy (==1.21.0)
Requires-Dist: openpyxl (==3.0.7)
Requires-Dist: packaging (==20.9)
Requires-Dist: pandas (==1.2.4)
Requires-Dist: pandocfilters (==1.4.3)
Requires-Dist: parso (==0.8.2)
Requires-Dist: pathspec (==0.8.1)
Requires-Dist: pexpect (==4.8.0)
Requires-Dist: pickleshare (==0.7.5)
Requires-Dist: Pillow (==9.0.0)
Requires-Dist: pluggy (==0.13.1)
Requires-Dist: prometheus-client (==0.10.1)
Requires-Dist: prompt-toolkit (==3.0.18)
Requires-Dist: ptyprocess (==0.7.0)
Requires-Dist: py (==1.10.0)
Requires-Dist: pycodestyle (==2.7.0)
Requires-Dist: pycparser (==2.20)
Requires-Dist: pycryptodome (==3.10.1)
Requires-Dist: pyflakes (==2.3.1)
Requires-Dist: Pygments (==2.9.0)
Requires-Dist: pylint (==2.8.2)
Requires-Dist: pyparsing (==2.4.7)
Requires-Dist: pyrsistent (==0.17.3)
Requires-Dist: pytest (==6.2.4)
Requires-Dist: python-dateutil (==2.8.1)
Requires-Dist: pytz (==2021.1)
Requires-Dist: pyyaml (==5.4.1)
Requires-Dist: pyzmq (==22.0.3)
Requires-Dist: qtconsole (==5.1.0)
Requires-Dist: QtPy (==1.9.0)
Requires-Dist: regex (==2021.4.4)
Requires-Dist: requests (==2.25.1)
Requires-Dist: scipy (==1.6.3)
Requires-Dist: Send2Trash (==1.5.0)
Requires-Dist: six (==1.16.0)
Requires-Dist: soupsieve (==2.2.1)
Requires-Dist: terminado (==0.10.0)
Requires-Dist: testpath (==0.5.0)
Requires-Dist: toml (==0.10.2)
Requires-Dist: tornado (==6.1)
Requires-Dist: tqdm (==4.60.0)
Requires-Dist: traitlets (==5.0.5)
Requires-Dist: typing-extensions (==3.10.0.0)
Requires-Dist: urllib3 (==1.26.5)
Requires-Dist: wcwidth (==0.2.5)
Requires-Dist: webencodings (==0.5.1)
Requires-Dist: widgetsnbextension (==3.5.1)
Requires-Dist: wrapt (==1.12.1)

# 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](https://gym.openai.com/)-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](https://arxiv.org/abs/2004.13332)**,
*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](https://arxiv.org/abs/2108.02755)**
*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](https://arxiv.org/abs/2108.02904)**
*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:

```
@misc{2004.13332,
 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:

- [The AI Economist website](https://www.einstein.ai/the-ai-economist)
- [Blog: The AI Economist: Improving Equality and Productivity with AI-Driven Tax Policies](https://blog.einstein.ai/the-ai-economist/)
- [Blog: The AI Economist moonshot](https://blog.einstein.ai/the-ai-economist-moonshot/)
- [Blog: The AI Economist web demo of the COVID-19 case study](https://blog.einstein.ai/ai-economist-covid-case-study-ethics/)
- [Web demo: The AI Economist ethical review of AI policy design and COVID-19 case study](https://einstein.ai/the-ai-economist/ai-policy-foundation-and-covid-case-study)

## Simulation Cards: Ethics Review and Intended Use

Please see our [Simulation Card](https://github.com/salesforce/ai-economist/blob/master/Simulation_Card_Foundation_Economic_Simulation_Framework.pdf) for a review of the intended use and ethical review of our framework.

Please see our [COVID-19 Simulation Card](https://github.com/salesforce/ai-economist/blob/master/COVID-19_Simulation-Card.pdf) 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:

- join our Slack channel [aieconomist.slack.com](https://aieconomist.slack.com) using this [invite link](https://join.slack.com/t/aieconomist/shared_invite/zt-g71ajic7-XaMygwNIup~CCzaR1T0wgA), or
- email us @ ai.economist@salesforce.com.

## Installation Instructions

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

### Using pip

Simply use the Python package manager:

```python
pip install ai-economist
```

### Installing from Source

1. Clone this repository to your local machine:

  ```
   git clone www.github.com/salesforce/ai-economist
   ```

2. Create a new conda environment (named "ai-economist" below - replace with anything else) and activate it

  ```pyfunctiontypecomment
   conda create --name ai-economist python=3.7 --yes
   conda activate ai-economist
   ```

3. Either

   a) Edit the PYTHONPATH to include the ai-economist directory
  ```
   export PYTHONPATH=<local path to ai-economist>:$PYTHONPATH
   ```

   OR

   b) Install as an editable Python package
  ```pyfunctiontypecomment
   cd ai-economist
   pip install -e .
   ```

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

```pyfunctiontypecomment
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

- [economic_simulation_basic](https://www.github.com/salesforce/ai-economist/blob/master/tutorials/economic_simulation_basic.ipynb) ([Try this on Colab](http://colab.research.google.com/github/salesforce/ai-economist/blob/master/tutorials/economic_simulation_basic.ipynb)!): Shows how to interact with and visualize the simulation.
- [economic_simulation_advanced](https://www.github.com/salesforce/ai-economist/blob/master/tutorials/economic_simulation_advanced.ipynb) ([Try this on Colab](http://colab.research.google.com/github/salesforce/ai-economist/blob/master/tutorials/economic_simulation_advanced.ipynb)!): Explains how Foundation is built up using composable and flexible building blocks.
- [optimal_taxation_theory_and_simulation](https://github.com/salesforce/ai-economist/blob/master/tutorials/optimal_taxation_theory_and_simulation.ipynb) ([Try this on Colab](https://colab.research.google.com/github/salesforce/ai-economist/blob/master/tutorials/optimal_taxation_theory_and_simulation.ipynb)!): Demonstrates how economic simulations can be used to study the problem of optimal taxation.
- [covid19_and_economic_simulation](https://www.github.com/salesforce/ai-economist/blob/master/tutorials/covid19_and_economic_simulation.ipynb) ([Try this on Colab](http://colab.research.google.com/github/salesforce/ai-economist/blob/master/tutorials/covid19_and_economic_simulation.ipynb)!): Introduces a simulation on the COVID-19 pandemic and economy that can be used to study different health and economic policies .

### Multi-Agent Training
- [multi_agent_gpu_training_with_warp_drive](https://github.com/salesforce/ai-economist/blob/master/tutorials/multi_agent_gpu_training_with_warp_drive.ipynb) ([Try this on Colab](http://colab.research.google.com/github/salesforce/ai-economist/blob/master/tutorials/multi_agent_gpu_training_with_warp_drive.ipynb)!): Introduces our multi-agent reinforcement learning framework [WarpDrive](https://arxiv.org/abs/2108.13976), which we then use to train the COVID-19 and economic simulation.
- [multi_agent_training_with_rllib](https://github.com/salesforce/ai-economist/blob/master/tutorials/multi_agent_training_with_rllib.ipynb) ([Try this on Colab](http://colab.research.google.com/github/salesforce/ai-economist/blob/master/tutorials/multi_agent_training_with_rllib.ipynb)!): Shows how to perform distributed multi-agent reinforcement learning with [RLlib](https://docs.ray.io/en/latest/rllib/index.html).
- [two_level_curriculum_training_with_rllib](https://github.com/salesforce/ai-economist/blob/master/tutorials/two_level_curriculum_learning_with_rllib.md): Describes how to implement two-level curriculum training with [RLlib](https://docs.ray.io/en/latest/rllib/index.html).

To run these notebooks *locally*, you need [Jupyter](https://jupyter.org). See [https://jupyter.readthedocs.io/en/latest/install.html](https://jupyter.readthedocs.io/en/latest/install.html) for installation instructions and [(https://jupyter-notebook.readthedocs.io/en/stable/](https://jupyter-notebook.readthedocs.io/en/stable/) 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](https://www.github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/base) | Contains base classes to can be extended to define Agents, Components and Scenarios. |
| [agents](https://www.github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/agents) | Agents represent economic actors in the environment. Currently, we have mobile Agents (representing workers) and a social planner (representing a government). |
| [entities](https://www.github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/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](https://www.github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/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](https://www.github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/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](https://www.github.com/salesforce/ai-economist/blob/master/CONTRIBUTING.md).

## Changelog

For the complete release history, see [CHANGELOG.md](https://www.github.com/salesforce/ai-economist/blob/master/CHANGELOG.md).

## License

Foundation and the AI Economist are released under the [BSD-3 License](LICENSE.txt).



