Architecture overview

equilibria is a Python framework for Computable General Equilibrium (CGE) modeling whose defining constraint is parity with reference GAMS models: every template is validated cell-by-cell against the original GAMS implementation before it is considered done.

The pipeline

Data I/O SAM · HAR · GDX · MIP Calibration benchmark → parameters Templates gtap · pep_pyomo · simple_open Solvers PATH (MCP) · IPOPT (NLP) Validation parity gates vs GAMS

  1. Data I/O (equilibria.babel, equilibria.sam_tools) reads and balances the input data: SAM matrices, GEMPACK HAR files (native pure-Python reader and writer), GAMS GDX containers, and raw MIP/IO tables (MIP → SAM, HAR I/O).

  2. Calibration (equilibria.calibration, equilibria.core, plus per-template calibration modules) fits the model’s parameters so the benchmark equilibrium reproduces the SAM exactly.

  3. Templates (equilibria.templates) are complete model implementations — sets, parameters, equations, closure — assembled on the core (equilibria.core, equilibria.backends for Pyomo) and the generic building blocks in equilibria.blocks (production, trade, demand, institutions, equilibrium).

  4. Solvers: the same model solves as an MCP (complementarity, PATH via the C API — Solving with PATH via the C API) or as an NLP (IPOPT), mirroring GAMS’s ifMCP switch. Solver support utilities live in equilibria.solver; the PATH/IPOPT drivers ship with each template.

  5. Validation compares every solved cell against a reference GAMS solution (Benchmarks, GTAP 7 Parity Coverage Matrix, PEP-1-1 Parity Coverage Matrix).

The parity philosophy

  • GAMS is the source of truth. A divergent cell is a bug (in the model, the calibration, or the reference itself) until proven otherwise — cells are never excluded to inflate a match number.

  • Same-engine comparisons. Parity is measured NLP-vs-NLP (IPOPT both sides) and MCP-vs-MCP (PATH both sides), so the solver’s equality tolerance cancels and the match% reflects model fidelity, not solver noise.

  • Gates, not snapshots. Coverage lives in one declarative matrix per model (scripts/gtap/coverage_matrix.py, scripts/pep/pep_coverage_matrix.py). Pytest gates re-measure the match and assert conservative floors; CI keeps the rendered docs in sync with the matrix source.

  • A solver-free structural canary. The .nl coefficient gate diffs Python-vs-GAMS Jacobian coefficients on every push — no solver needed, so it runs in CI and catches equation/parameter regressions in seconds.

Package map

Package

Responsibility

equilibria.sam_tools

SAM audit, balancing, MIP → SAM transforms

equilibria.babel

File formats: HAR reader/writer, GDX reader, SAM loaders

equilibria.core

Model assembly core: sets, parameters, variables, equations, calibration phases

equilibria.model, equilibria.datasets

Public model API and bundled datasets (load_bundled)

equilibria.blocks

Generic equation blocks: production, trade, demand, institutions, equilibrium

equilibria.calibration

Generic calibration utilities (CES, Leontief)

equilibria.backends

Pyomo backend (model construction)

equilibria.solver

Solver support: guards, Jacobian tooling, transforms

equilibria.templates.gtap

GTAP Standard 7 (multi-period, MCP + NLP, 6 datasets)

equilibria.templates.pep_pyomo

PEP-1-1 v2.1 ported to Pyomo (NLP + MCP)

equilibria.templates (simple_open)

Didactic open-economy model

equilibria.simulations

Scenario runtime, adapters, multi-model wrappers

equilibria.contracts, equilibria.qa

Validation contracts and SAM/QA checks

See the templates overview for per-template status and the API reference for the generated reference.