CliMaPan-Lab: Climate-Pandemic Economic Modeling Laboratory

CliMaPan-Lab is an agent-based economic modeling framework for studying interactions between climate change, pandemic dynamics, and economic systems.

Installation

# Install from PyPI (Recommended)
pip install climapan-lab

# Install from source
git clone https://github.com/a11to1n3/CliMaPan-Lab.git
cd CliMaPan-Lab
pip install -e .

# Or install directly from GitHub
pip install git+https://github.com/a11to1n3/CliMaPan-Lab.git

Quick Start

from climapan_lab.model import EconModel
from climapan_lab.base_params import economic_params

# Create model with default parameters
params = economic_params.copy()
params['steps'] = 120  # 10 years (monthly steps)

# Run simulation
model = EconModel(params)
results = model.run()

# Access results
df = results.variables.EconModel
print(f"Final GDP: {df['GDP'].iloc[-1]}")

Example Script

python climapan_lab/examples/simple_example.py

Command Line Interface

Basic Usage

# Basic simulation
climapan-run --settings BAU

# With carbon tax
climapan-run --settings CT --plot

# Multiple runs
climapan-run --noOfRuns 5

# Help
climapan-run --help

Complete Command Line Arguments

The run_sim script supports the following arguments:

Argument	Short	Type	Default	Description
--noOfRuns	-n	int	1	Number of simulation runs to execute
--settings	-s	str	"BAU"	Economic scenario: BAU, CT, CTRa, CTRb, CTRc, CTRd
--covidSettings	-c	str	None	COVID scenario: BAU, DIST, LOCK, VAX
--climateDamage	-d	str	"AggPop"	Climate damage type: AggPop, Idiosyncratic, or None
--extractedVarListPathNpy	-l	str	None	Path to text file with variables to extract as numpy files
--extractedVarListPathCsv	-v	str	None	Path to text file with variables to extract as CSV files
--plot	-p	flag	False	Generate plots of simulation results

Advanced Examples

# Single run with carbon tax and plotting
climapan-run -s CT -p

# Multiple runs with COVID lockdown scenario
climapan-run -n 10 -s BAU -c LOCK

# Full scenario with climate damage and plotting
climapan-run -s CTRa -c VAX -d AggPop -p

# Extract specific variables to separate files
climapan-run -s CT -l variables_list.txt -v output_vars.txt -p

# Complex multi-parameter scenario
climapan-run -n 5 -s CTRb -c DIST -d Idiosyncratic -p

# Scenario without climate damage
climapan-run -s CT -c BAU -d None -p

Scenario Descriptions

Economic Settings (--settings):

• BAU: Business as usual (baseline scenario)
• CT: Carbon tax implementation
• CTRa: Carbon tax with revenue recycling option A
• CTRb: Carbon tax with revenue recycling option B
• CTRc: Carbon tax with revenue recycling option C
• CTRd: Carbon tax with revenue recycling option D

COVID Settings (--covidSettings):

• BAU: COVID baseline scenario
• DIST: Social distancing measures
• LOCK: Lockdown implementation
• VAX: Vaccination rollout scenario

Climate Damage Settings (--climateDamage):

• AggPop: Aggregate population-level climate damage
• Idiosyncratic: Individual-level climate damage variation
• None: No climate damage effects

Variable Extraction

To extract specific model variables to separate files, create a text file with variable names (one per line):

# variables_list.txt
GDP
UnemploymentRate
InflationRate
Consumption
Wage
TotalTaxes
BankDataWriter

Then use:

climapan-run -s CT -l variables_list.txt -v variables_list.txt -p

Key Parameters

• Economic Settings: 'BAU', 'CT', 'CTRa', 'CTRb', 'CTRc', 'CTRd'
• COVID Settings: None, 'BAU', 'DIST', 'LOCK', 'VAX'
• Climate Module: Enable/disable with climateModuleFlag
• Simulation Length: Set steps (monthly time steps)

Model Features

• Agents: Consumers, firms, banks, government with comprehensive lifecycle documentation
• Climate Integration: Climate shocks and economic impacts with detailed step-by-step dynamics
• Pandemic Dynamics: COVID-19 effects on economic activity with SEIR-like progression
• Policy Analysis: Carbon taxes, fiscal policies with clear implementation details
• Flexible Scenarios: Various economic and environmental conditions
• Well-Documented Codebase: Extensive inline documentation explaining agent behavior, simulation flow, and component interactions

Example Scenarios

# Carbon tax scenario
params['settings'] = 'CT'
params['co2_tax'] = 0.05
params['climateModuleFlag'] = True

# Pandemic lockdown scenario  
params['covid_settings'] = 'LOCK'
params['lockdown_scale'] = 0.7

# Business as usual
params['settings'] = 'BAU'
params['covid_settings'] = None

Testing

CliMaPan-Lab includes a comprehensive test suite with 60+ tests across 5 categories:

# Run all tests
cd tests
python run_all_tests.py

# Run fast tests (excludes performance tests)
python run_all_tests.py --fast

# Run specific test categories
python -m pytest test_basic_functionality.py -v
python -m pytest test_model_components.py -v
python -m pytest test_integration.py -v
python -m pytest test_examples.py -v
python -m pytest test_performance.py -v

Test Categories

• Basic Functionality: Model creation, parameter validation
• Model Components: Agent behavior, climate/COVID scenarios
• Integration: End-to-end workflows, multi-scenario analysis
• Examples: Script validation, import testing
• Performance: Benchmarking, memory efficiency, scaling

CI/CD

The project uses GitHub Actions for automated testing and quality assurance:

• CI: Quick checks on every commit (syntax, formatting, basic tests)
• Tests: Comprehensive testing on Python 3.8-3.11
• Security: Weekly security and dependency audits
• Release: Automated releases on version tags

For more details, see .github/README.md.

License

MIT License - see LICENSE file for details.

Citation

@article{d2025climapan,
  title={CliMaPan-Lab: An open-source Python framework for agent-based macroeconomic simulation of climate-and pandemic-related systemic risks},
  author={D’Orazio, Paola and Pham, Anh-Duy and Nguyen, Son Hong},
  journal={SoftwareX},
  volume={32},
  pages={102408},
  year={2025},
  publisher={Elsevier}
}