# gustavohm/cgelab architecture

> Architecture diagram of the GitHub repository gustavohm/cgelab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gustavohm/cgelab
- Repository: https://github.com/gustavohm/cgelab

## Overview

cgelab is a Python toolkit for SAM-based computable general equilibrium analysis. The principal workflow is to read and balance a SAM, specify assumptions and closure, calibrate an economy, solve a period under a scenario, and interpret results; recursive paths and welfare analysis extend that workflow. Separate branches cover SAM construction and surveys, regional models, microsimulation, and robustness. Edges follow README statements or source-index references; many modules were not sampled, so uncertain internal calls are omitted.

Main entry points: [`src/cgelab/solve.py`](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/solve.py) (Period equilibrium), [`src/cgelab/calibrate.py`](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/calibrate.py) (Calibration), [`src/cgelab/sam.py`](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/sam.py) (SAM accounts), [`src/cgelab/results.py`](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/results.py) (Period results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Model setup"]
  node_sam[("SAM accounts<br/>[sam.py]")]
  node_spec["Model assumptions<br/>[spec.py]"]
  node_closure["Balance closures<br/>[closure.py]"]
  node_calibrate["Calibration<br/>[calibrate.py]"]
end

subgraph group_analysis["Equilibrium analysis"]
  node_scenario["Counterfactuals<br/>[scenario.py]"]
  node_solve["Period equilibrium<br/>[solve.py]"]
  node_diagnostics["Accounting checks<br/>[diagnostics.py]"]
  node_dynamics["Recursive paths<br/>[dynamics.py]"]
  node_baseline["Baseline paths<br/>[baseline.py]"]
  node_historical["Historical calibration<br/>[historical.py]"]
end

subgraph group_extensions["Model extensions"]
  node_regional["Regional equilibrium<br/>[regional.py]"]
  node_mobility["Factor mobility<br/>[mobility.py]"]
  node_segments["Labour segments<br/>[segments.py]"]
  node_emissions["Emissions accounts<br/>[emissions.py]"]
  node_physical["Physical units<br/>[physical.py]"]
  node_export["JuMP export<br/>[export.py]"]
  node_bridge["Forward-looking investment<br/>[bridge.py]"]
end

subgraph group_data["Data and distribution"]
  node_sam_io["SAM formats<br/>[har.py]"]
  node_sam_build["SAM construction<br/>[build.py]"]
  node_ibge["IBGE readers<br/>[ibge.py]"]
  node_micro["Survey microsimulation<br/>[micro.py]"]
  node_behaviour["Behavioural simulation<br/>[behaviour.py]"]
end

subgraph group_interpretation["Results and interpretation"]
  node_results["Period results<br/>[results.py]"]
  node_welfare["Welfare measures<br/>[welfare.py]"]
  node_decompose["Welfare decomposition<br/>[decompose.py]"]
  node_sensitivity["Sensitivity analysis<br/>[sensitivity.py]"]
  node_robustness["Robustness reports"]
  node_multipliers["SAM multipliers<br/>[multipliers.py]"]
end

node_user(("Analyst"))

node_user -->|"provides accounts"| node_sam
node_sam_io -->|"reads and writes"| node_sam
node_sam_build -->|"constructs"| node_sam
node_ibge -->|"supplies tables"| node_sam_build
node_user -->|"sets assumptions"| node_spec
node_user -->|"sets balances"| node_closure
node_sam -->|"calibrates from"| node_calibrate
node_spec -->|"configures"| node_calibrate
node_calibrate -->|"builds economy"| node_solve
node_closure -->|"sets adjustments"| node_solve
node_scenario -->|"varies inputs"| node_solve
node_solve -->|"produces"| node_results
node_solve -->|"checks equilibrium"| node_diagnostics
node_dynamics -->|"solves periods"| node_solve
node_baseline -->|"calibrates path"| node_calibrate
node_historical -->|"calibrates history"| node_calibrate
node_regional -->|"extends equilibrium"| node_solve
node_calibrate -->|"uses mobility"| node_mobility
node_calibrate -->|"uses segments"| node_segments
node_solve -->|"computes supply"| node_mobility
node_solve -->|"computes labour"| node_segments
node_user -->|"adds emissions"| node_emissions
node_user -->|"adds units"| node_physical
node_results -->|"maps survey impacts"| node_micro
node_micro -->|"supports behaviour"| node_behaviour
node_results -->|"measures welfare"| node_welfare
node_results -->|"decomposes effects"| node_decompose
node_solve -->|"resolves scenarios"| node_decompose
node_solve -->|"varies assumptions"| node_sensitivity
node_sensitivity -->|"summarizes robustness"| node_robustness
node_sam -->|"computes linkages"| node_multipliers
node_solve -->|"exports economy"| node_export
node_user -.->|"requests Ramsey model"| node_bridge

click node_sam "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/sam.py"
click node_sam_io "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/har.py"
click node_sam_build "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/build.py"
click node_ibge "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/ibge.py"
click node_spec "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/spec.py"
click node_closure "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/closure.py"
click node_calibrate "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/calibrate.py"
click node_scenario "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/scenario.py"
click node_solve "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/solve.py"
click node_diagnostics "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/diagnostics.py"
click node_dynamics "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/dynamics.py"
click node_baseline "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/baseline.py"
click node_historical "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/historical.py"
click node_regional "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/regional.py"
click node_mobility "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/mobility.py"
click node_segments "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/segments.py"
click node_emissions "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/emissions.py"
click node_physical "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/physical.py"
click node_micro "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/micro.py"
click node_behaviour "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/behaviour.py"
click node_results "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/results.py"
click node_welfare "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/welfare.py"
click node_decompose "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/decompose.py"
click node_sensitivity "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/sensitivity.py"
click node_robustness "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/robustness_report.py"
click node_multipliers "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/multipliers.py"
click node_export "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/export.py"
click node_bridge "https://github.com/gustavohm/cgelab/blob/main/src/cgelab/bridge.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sam,node_spec,node_closure,node_calibrate toneBlue
class node_scenario,node_solve,node_diagnostics,node_dynamics,node_baseline,node_historical toneAmber
class node_regional,node_mobility,node_segments,node_emissions,node_physical,node_export,node_bridge toneMint
class node_sam_io,node_sam_build,node_ibge,node_micro,node_behaviour toneRose
class node_results,node_welfare,node_decompose,node_sensitivity,node_robustness,node_multipliers,node_user toneIndigo
```

## Components

### Model setup

- [SAM accounts](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/sam.py): `src/cgelab/sam.py`
- [Model assumptions](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/spec.py): `src/cgelab/spec.py`
- [Balance closures](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/closure.py): `src/cgelab/closure.py`
- [Calibration](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/calibrate.py): `src/cgelab/calibrate.py`

### Equilibrium analysis

- [Counterfactuals](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/scenario.py): `src/cgelab/scenario.py`
- [Period equilibrium](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/solve.py): `src/cgelab/solve.py`
- [Accounting checks](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/diagnostics.py): `src/cgelab/diagnostics.py`
- [Recursive paths](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/dynamics.py): `src/cgelab/dynamics.py`
- [Baseline paths](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/baseline.py): `src/cgelab/baseline.py`
- [Historical calibration](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/historical.py): `src/cgelab/historical.py`

### Model extensions

- [Regional equilibrium](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/regional.py): `src/cgelab/regional.py`
- [Factor mobility](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/mobility.py): `src/cgelab/mobility.py`
- [Labour segments](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/segments.py): `src/cgelab/segments.py`
- [Emissions accounts](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/emissions.py): `src/cgelab/emissions.py`
- [Physical units](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/physical.py): `src/cgelab/physical.py`
- [JuMP export](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/export.py): `src/cgelab/export.py`
- [Forward-looking investment](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/bridge.py): `src/cgelab/bridge.py`

### Data and distribution

- [SAM formats](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/har.py): `src/cgelab/har.py`
- [SAM construction](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/build.py): `src/cgelab/build.py`
- [IBGE readers](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/ibge.py): `src/cgelab/ibge.py`
- [Survey microsimulation](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/micro.py): `src/cgelab/micro.py`
- [Behavioural simulation](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/behaviour.py): `src/cgelab/behaviour.py`

### Results and interpretation

- [Period results](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/results.py): `src/cgelab/results.py`
- [Welfare measures](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/welfare.py): `src/cgelab/welfare.py`
- [Welfare decomposition](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/decompose.py): `src/cgelab/decompose.py`
- [Sensitivity analysis](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/sensitivity.py): `src/cgelab/sensitivity.py`
- [Robustness reports](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/robustness_report.py): `src/cgelab/robustness_report.py`
- [SAM multipliers](https://github.com/gustavohm/cgelab/blob/main/src/cgelab/multipliers.py): `src/cgelab/multipliers.py`

### Other components

- **Analyst**

## Connections

- Analyst → SAM accounts: provides accounts (evidence: `README.md`)
- SAM formats → SAM accounts: reads and writes (evidence: `README.md`)
- SAM construction → SAM accounts: constructs (evidence: `README.md`)
- IBGE readers → SAM construction: supplies tables (evidence: `README.md`)
- Analyst → Model assumptions: sets assumptions (evidence: `README.md`)
- Analyst → Balance closures: sets balances (evidence: `README.md`)
- SAM accounts → Calibration: calibrates from (evidence: `README.md`)
- Model assumptions → Calibration: configures (evidence: `README.md`)
- Calibration → Period equilibrium: builds economy (evidence: `README.md`)
- Balance closures → Period equilibrium: sets adjustments (evidence: `README.md`)
- Counterfactuals → Period equilibrium: varies inputs (evidence: `README.md`)
- Period equilibrium → Period results: produces (evidence: `README.md`)
- Period equilibrium → Accounting checks: checks equilibrium (evidence: `README.md`)
- Recursive paths → Period equilibrium: solves periods (evidence: `src/cgelab/dynamics.py`)
- Baseline paths → Calibration: calibrates path (evidence: `README.md`)
- Historical calibration → Calibration: calibrates history (evidence: `README.md`)
- Regional equilibrium → Period equilibrium: extends equilibrium (evidence: `src/cgelab/regional.py`)
- Calibration → Factor mobility: uses mobility (evidence: `src/cgelab/calibrate.py`)
- Calibration → Labour segments: uses segments (evidence: `src/cgelab/calibrate.py`)
- Period equilibrium → Factor mobility: computes supply (evidence: `src/cgelab/solve.py`)
- Period equilibrium → Labour segments: computes labour (evidence: `src/cgelab/solve.py`)
- Analyst → Emissions accounts: adds emissions (evidence: `README.md`)
- Analyst → Physical units: adds units (evidence: `README.md`)
- Period results → Survey microsimulation: maps survey impacts (evidence: `README.md`)
- Survey microsimulation → Behavioural simulation: supports behaviour (evidence: `src/cgelab/micro.py`)
- Period results → Welfare measures: measures welfare (evidence: `README.md`)
- Period results → Welfare decomposition: decomposes effects (evidence: `README.md`)
- Period equilibrium → Welfare decomposition: resolves scenarios (evidence: `src/cgelab/decompose.py`)
- Period equilibrium → Sensitivity analysis: varies assumptions (evidence: `src/cgelab/sensitivity.py`)
- Sensitivity analysis → Robustness reports: summarizes robustness (evidence: `README.md`)
- SAM accounts → SAM multipliers: computes linkages (evidence: `README.md`)
- Period equilibrium → JuMP export: exports economy (evidence: `src/cgelab/__init__.py`)
- Analyst → Forward-looking investment: requests Ramsey model (evidence: `README.md`)