Mankiw Economics Lab (Principles of Economics Simulation System)

An interactive, code-first learning project based on Mankiw's Principles of Economics — implement every core model of microeconomics and macroeconomics by hand in Python.

This project takes the classic models in Mankiw's Principles of Economics textbook — from the "production possibilities frontier" to the "Phillips curve" — and turns each one into runnable, experimentable, testable Python code. Instead of just reading the graphs and formulas in a textbook, you can run the code, tweak parameters, and watch how markets converge and how the economy fluctuates.

✨ Highlights

• Covers Mankiw's ten principles of economics — every principle has a corresponding runnable experiment
• Complete micro + macro system — from supply-demand equilibrium to the Solow growth model, all covered
• Advanced model toolbox — consumer choice theory, game theory (Nash equilibrium, Cournot), loanable funds market, and the IS-LM model
• Dual-entry CLI — --macro and --demo demo the macro models and the ten principles with one command
• 280 unit and integration tests — every economic model is mathematically verified for correctness
• Full visualization — supply/demand curves, price convergence, Solow convergence paths, AD-AS equilibrium, Phillips curve, IS-LM…
• Deterministic and reproducible — fixed random seeds make experimental results exactly reproducible
• Teaching-friendly — comments + line-by-line formula derivations + mathematical verification tests

📚 Ten Principles × Code Implementations

📂 Project Structure

mankiwecolab/
├── main.py                    # CLI entry (full simulation / macro demo / ten principles)
├── config.py                  # All tunable parameters
├── experiments.py             # 10 classic economics experiments
├── agents/                    # Microeconomic agents
│   ├── consumer.py            #   Consumer: utility function + demand
│   └── producer.py            #   Producer: cost function + supply
├── market/                    # Market mechanisms
│   ├── market.py              #   Supply-demand aggregation + price discovery + market clearing
│   └── equilibrium.py         #   Equilibrium solving + surplus + elasticity
├── micro/                     # Microeconomics modules
│   ├── ppf.py                 #   Production possibilities frontier
│   ├── trade.py               #   Comparative advantage and trade
│   ├── externality.py         #   Externalities and Pigouvian taxes
│   ├── market_structure.py    #   Perfect competition / oligopoly / monopoly
│   ├── consumer_choice.py     #   Budget constraint, Cobb-Douglas utility, optimal choice
│   └── game_theory.py         #   Nash equilibrium, dominant strategies, Cournot oligopoly
├── macro/                     # Macroeconomics modules
│   ├── gdp.py                 #   GDP accounting and deflator
│   ├── inflation.py           #   CPI and the quantity theory of money
│   ├── unemployment.py        #   Unemployment rate and natural rate of unemployment
│   ├── solow.py               #   Solow growth model
│   ├── money.py               #   Money creation and multiplier
│   ├── ad_as.py               #   Aggregate demand – aggregate supply model
│   ├── phillips.py            #   Phillips curve
│   ├── loanable_funds.py      #   Loanable funds market and crowding out
│   └── islm.py                #   IS-LM model of output and interest rates
├── utils/                     # Utility functions
│   ├── economics.py           #   Gini coefficient, welfare analysis, policy interventions
│   ├── visualization.py       #   Micro/macro visualization
│   └── output.py              #   Console table and formatting helpers
├── notebooks/                 # Interactive Jupyter labs
│   └── interactive_lab.ipynb  #   Hands-on tour of the model toolbox
├── tests/                     # 280 unit and integration tests
└── output/                    # Charts and CSV data generated at runtime

🚀 Quick Start

Install from PyPI (recommended)

pip install mankiwecolab

New versions may take a few hours to appear on regional PyPI mirrors. If the install fails, fall back to the official index:

pip install -i https://pypi.org/simple mankiwecolab

After installation, use the command-line tool:

mankiw-econ --help          # View all commands
mankiw-econ                 # Full microeconomic market simulation
mankiw-econ --macro         # Macroeconomics model demo
mankiw-econ --demo          # Mankiw's ten principles demo
mankiw-econ --experiments   # Run all economics experiments
mankiw-econ --version       # Show the installed version

You can also download the .whl file from GitHub Releases and install it:

pip install ./mankiwecolab-2.1.0-py3-none-any.whl

Run from Source (development mode)

git clone https://github.com/NoahIsARider/MankiwEcoLab.git
cd MankiwEcoLab
pip install -r requirements.txt
python main.py

Run the Full Market Simulation

python main.py

Simulates a market with 1,000 consumers and 200 producers; observe how prices gradually converge to equilibrium.

Run the Macroeconomics Model Demo

python main.py --macro

Walks through GDP accounting, CPI, unemployment, Solow growth, money creation, the AD-AS model, the Phillips curve, the loanable funds market, and the IS-LM model in sequence.

Run Mankiw's Ten Principles Demo

python main.py --demo

Run All Economics Experiments

python experiments.py

or:

python main.py --experiments

The ten experiments cover market equilibrium, demand/supply shifts, elasticity, price controls, externalities, market structure, macro models, consumer choice, and game theory.

Interactive Jupyter Notebooks

jupyter notebook notebooks/interactive_lab.ipynb

A self-contained, parameterized tour of consumer choice, game theory, the loanable funds market, and the IS-LM model.

Run the Tests

pip install pytest
pytest tests/

🖼️ Visualization Examples

After running python main.py, the following charts are generated in the output/ directory.

See docs/ for detailed documentation.

📖 Documentation

🧪 Quality Assurance

This project verifies every economic model with 280 automated tests:

• Mathematical correctness tests: marginal utility = derivative of the utility function, steady-state investment = break-even investment, golden rule f'(k) = δ+n, Cournot equilibrium q* = (a−c)/(b(n+1)), IS-LM equilibrium verification…
• Economic law tests: demand falls as price rises, supply rises as price rises, monopoly prices are higher than competitive prices, crowding out in the loanable funds market…
• Game theory tests: dominant strategy equilibrium, pure and mixed Nash equilibria, Pareto optimality…
• Determinism tests: identical random seeds produce exactly identical experimental results
• Integration tests: complete simulation flows and generation of all visualizations

Run pytest tests/ to reproduce all tests.

🤝 Contributing

Any form of contribution is welcome!

1. Add new economic models: create a new module under micro/ or macro/ with accompanying tests
2. Improve visualization: add more intuitive charts to utils/visualization.py
3. Improve tutorials: write teaching documentation under docs/tutorials/
4. Fix issues: submit an issue or pull request

Please make sure pytest tests/ passes before submitting. See CONTRIBUTING.md for details.

📄 License

MIT

📚 References

• Mankiw, Principles of Microeconomics (8th edition)
• Mankiw, Principles of Macroeconomics (8th edition)
• Romer, Advanced Macroeconomics
• Varian, Intermediate Microeconomics

_{Built with love for economics learners around the world}