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 implementationCTRa: Carbon tax with revenue recycling option ACTRb: Carbon tax with revenue recycling option BCTRc: Carbon tax with revenue recycling option CCTRd: Carbon tax with revenue recycling option D
COVID Settings (--covidSettings):
BAU: COVID baseline scenarioDIST: Social distancing measuresLOCK: Lockdown implementationVAX: Vaccination rollout scenario
Climate Damage Settings (--climateDamage):
AggPop: Aggregate population-level climate damageIdiosyncratic: Individual-level climate damage variationNone: 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}
}
Metadata
Release files for climapan-lab 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| climapan_lab-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for climapan_lab-0.2.0-py3-none-any.whl |
Release files / climapan_lab-0.2.0-py3-none-any.whl
| Download URL | climapan_lab-0.2.0-py3-none-any.whl |
|---|---|
| Size | 116.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e1dc4dc48a3eb6b41445112467c3d3dd44a148aa4708dcc5578b0e1d48bbd0eb
|
|
BLAKE2b-256 checksum How to use checksums |
32bd5d2489a3c766bcdb40a49c9f7ab97ea7ea973d6dafa5d62ee3ea838cdc4c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.7
|
Security for climapan-lab 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.