cgelab 0.5.0__tar.gz

cgelab-0.5.0/CHANGELOG.md

@@ -0,0 +1,268 @@
+# Changelog
+
+All notable changes to `cgelab`. Versions follow [semantic versioning](https://semver.org/);
+before 1.0, a minor version may add to the API and a patch version only fixes.
+
+## 0.5.0 — 2026-10-18
+
+The first public release, on PyPI together with dsgelab 0.5. It gathers the roadmap's
+milestones 0.3 and 0.4, which were not released on their own, and the release engineering of
+0.5. Python 3.10 is no longer supported.
+
+### Changed since 0.2.0
+
+- Renamed from `cgekit` to `cgelab`: `cgekit` is taken on PyPI by an
+  unrelated project. The import name, distribution name, CLI entry point,
+  the `CGELAB_RUN_JULIA` switch and the URLs all move together.
+
+### Added in 0.2, after 0.2.0
+
+- Large-country trade. `ModelSpec.export_demand` puts exports on a demand curve,
+  `E / E0 = (pWe / export_price)^(-η)`, and `ModelSpec.import_supply` puts
+  imports on a supply curve, `M / M0 = (pWm / world_price)^ψ`: the equations of
+  Hosoe's `lrgcge`. A scalar or a mapping by commodity; the rest stay price
+  takers. The scenario prices become the shifts of the curves, and
+  `PeriodResult.world_export_price` and `world_import_price` hold the solved
+  world prices. The base year is unchanged. `export_demand` needs
+  `export_rule="cet"`; the regional slice refuses both. The JuMP replica carries
+  the curves as constraints, and three new round-trip cases match it to 1e-12.
+- Import tariff and indirect tax on output, separate from the product tax on
+  absorption and inside the prices they fall on, as in Hosoe's `stdcge`.
+  `calibrate(..., tariffs=)` or `ModelSpec.tariff_account` sets the base-year
+  tariff (Hosoe's `taum`), and the Armington nest is calibrated on the
+  tariff-inclusive value of imports. `calibrate(..., output_taxes=)` or
+  `ModelSpec.indirect_tax_account` sets the output tax (Hosoe's `tauz` / IDT),
+  and the CET splits output at its tax-inclusive value, so exports carry it.
+  Government receives both as levels. `Scenario.tariff` and
+  `Scenario.output_tax` move one rate without moving the other; a tariff of
+  zero abolishes it. At the calibrated rates the base year is the SAM. The
+  JuMP replica carries the same prices.
+- `Closure(government="saving_rate")`: government saves the base-year share
+  of its income (`Economy.gov_savrate`) and spends the rest in base-year value
+  shares. `Closure(foreign_saving_unit="foreign_currency")`: foreign saving
+  fixed in dollars under `foreign="fixed_saving"`. Together they are Hosoe's
+  closure.
+- `cgelab.examples.hosoe`: the SAM, functional forms and closure of Hosoe,
+  Gasawa and Hashimoto's `stdcge` and, with `large_country=True`, `lrgcge`.
+  The tariff abolition of both matches a line-by-line JuMP transcription of the
+  GAMS programs (`validation/hosoe.jl`) in all 49 displayed variables, to
+  2.4e-12; `tests/test_hosoe_stdcge.py` checks it against the stored result.
+- The JuMP replica converges from a cold start on an applied SAM. Household
+  income, spending and the Armington shares now start at base-year levels
+  instead of at 1 and at guesses; factor prices and the exchange rate still start
+  displaced, so the Python answer never enters the start.
+- `PeriodResult.domestic_sales` and `p_domestic`: home sales of domestic output
+  and their price. `base_year_reproduction` now also checks imports and
+  exports against the SAM.
+- Several regions. `ModelSpec.regions` and `sigma_interregional`: a CES across
+  regions of origin under the Armington nest. Accounts are `region:local`.
+  Factors clear where they are; one national numeraire stays unsolved. A single
+  labelled region reproduces the legacy solver, including on the plain toy with
+  taxes and intermediates. `examples.regions` is a hand-written two-region SAM.
+  Margins, CET, LES, migration, non-default closures, `run_path` and `to_jump`
+  are refused by name on this slice.
+- `factor_demand_by_activity`, `real_gdp` and `sectoral_path`: employment by
+  activity, real GDP from both sides with the tax gap named, and a tidy sectoral
+  panel along a path. `PeriodResult.factor_demand_by_activity` holds the matrix
+  the solver used.
+- A replications page on the site (`site/replications.html`, and the Portuguese pair).
+  The benchmark of Hosoe, Gasawa and Hashimoto (2004), chapter 5, as printed in the
+  GAMS library file `splcge`, reproduces: output 15 and 35, prices 1. A SAM that
+  invests nothing no longer raises on an empty investment basket.
+- `Scenario.investment_mix`: commodity composition of the investment budget.
+  Absent, the base-year mix. Distinct from `Growth.allocation`, which shares
+  investment across capital stocks.
+- `Closure.labour`: `full_employment` (unchanged default), `fixed_real_wage`,
+  `wage_curve` and `elastic_supply`. The three new closures refuse a labour
+  numeraire. Unemployment is not paid. `PeriodResult.employment`,
+  `unemployment` and `real_wage`. The JuMP export carries the same equations.
+
+### Added in 0.3
+
+- SAM multipliers and input–output analysis (`cgelab.multipliers`):
+  `accounting_multipliers` (Pyatt and Round), `fixed_price_multipliers` with
+  marginal propensities from income elasticities and an Engel-aggregation check,
+  `leontief_multipliers` (activities and commodities endogenous), `linkages`
+  (backward from the Leontief inverse, forward from the Ghosh inverse, with
+  Rasmussen indices) and `structural_paths` (Defourny and Thorbecke). The
+  Leontief inverse reproduces Miller and Blair's two-sector example; the total
+  influences of all elementary paths add up to the multiplier (Lantner's
+  identity), to 1e-10.
+
+- National accounts (`national_accounts`): GDP at current prices by expenditure
+  and by income, which agree in every equilibrium, and GNI. Price and quantity
+  indices (`price_indices`): Laspeyres, Paasche and Fisher by component of final
+  demand, for GDP and for the terms of trade, against the base year or another
+  solved period. The government account (`government_account`,
+  `PeriodResult.government`): revenue by instrument, outlays and saving, recorded
+  by the solver at the solution. `PeriodResult.household_saving` and
+  `forced_saving`.
+
+- Systematic sensitivity (`sensitivity`, `spec_sweep`): Stroud's degree-3
+  quadrature, exact in the mean for results up to cubic in the parameters, and
+  Monte Carlo with a fixed seed, over `Uniform`, `Normal` and `Triangular`
+  parameters. `spec_sweep` recalibrates at every point.
+
+- Subtotals (`subtotals`, `path_decomposition`): the Harrison, Horridge and
+  Pearson decomposition of a result by groups of shocks, integrated along the
+  straight path from reference to alternative. The contributions add up to the
+  solved change, with a residual of order 1e-8 that is reported. On closed forms
+  they are the line integrals.
+
+- Welfare decomposition (`welfare_decomposition`): Huff and Hertel's split of
+  the change in real absorption into endowment, technology, one allocative term
+  per instrument, terms of trade and the external account, integrated along the
+  path. The identity closes to below 1e-9 in ten economies and closures; it is
+  not validated against GTAP, which needs the GTAP database.
+- `cgelab.examples.hosoe.build_simple()`: Hosoe's chapter 5 (`splcge`).
+
+### Fixed in 0.3
+
+- An undetermined exchange rate is refused. With fixed export shares, a
+  Cobb–Douglas Armington on every imported commodity and foreign saving fixed in
+  numeraire units, every exchange rate is an equilibrium; the solver used to
+  return whichever its start point was.
+
+- The activity tax paid by an own-account activity never reached government:
+  households paid it in the price and the tax block counted market activities
+  only, so the base year did not reproduce and Walras was off by the tax. The
+  JuMP replica had the same omission.
+
+### Added in 0.4
+
+- Government targets (`Closure.government_target`, `government_adjusts`):
+  government saving held fixed (a deficit target) or total revenue held fixed
+  (revenue-neutral tax replacement), met by scaling every direct tax rate, every
+  product tax rate, or government consumption in base-year shares.
+  `PeriodResult.tax_scale` is the factor. The JuMP replica carries the same
+  closures; `Economy.gov_saving0` and `gov_revenue0` are the base-year targets.
+
+- Emissions accounts (`add_emissions`, `emissions`) calibrated from base-year
+  totals by source (combustion in production, household and government fuel
+  use, process), and a carbon price (`Scenario.carbon_price`): a tax per unit of
+  output by emission intensity on activities, a specific tax on household fuel.
+  The revenue is reported by source and recycled by the revenue-neutral
+  closure. GDP, the welfare decomposition, subtotals and the JuMP replica carry
+  it.
+
+- Value-added-energy nesting (`ModelSpec.energy`, `sigma_vae`,
+  `sigma_energy`): an energy bundle, a CES across fuels, substitutes for value
+  added in a CES; other intermediates stay Leontief. The carbon price on a fuel
+  enters the price each activity pays for it. With zero elasticities the nest is
+  the Leontief model exactly; with positive ones the fuel ratios meet the CES
+  first-order conditions. The JuMP replica carries the nest.
+  `PeriodResult.input_coefficients` and `value_added_per_unit` are the
+  coefficients the equilibrium used.
+
+- GTAP-E's arrangement (`ModelSpec.energy_nest="capital"`, `energy_capital`,
+  `sigma_ke`): energy joins a capital factor in a capital-energy composite that
+  sits inside the value-added nest. With `sigma_ke = sigma_va` it collapses to the
+  value-added nest with `sigma_vae = sigma_va`, and the two solve to the same
+  equilibrium to 1e-11; capital and energy meet their first-order condition; the
+  JuMP replica carries both arrangements.
+- The bridge to dsgelab (`cgelab.bridge`, `pip install "cgelab[dsge]"`): a
+  Ramsey CGE in which an Euler equation chooses investment and every period is
+  the SAM model. dsgelab gives its steady state, first-order solution, impulse
+  responses and perfect-foresight transitions; `announced` turns a sequence of
+  scenarios into an announced policy. In a one-good closed economy it is the
+  stochastic growth model: same steady state, transition matrices and path, to
+  1e-7. `toy.build_one_good()` is that economy; `Scenario.investment_level`
+  sets real investment under `fixed_real`.
+
+- Physical units (`add_physical_units`, `physical`, `physical_coefficient`):
+  physical content per unit of a commodity's Armington composite and of an
+  activity's output, calibrated from base-year totals; physical supply, use by
+  agent, output and intensity of a solved period; and the translation of a
+  physical technical coefficient into a SAM entry. Supply meets use in every
+  equilibrium, margins included.
+
+### Fixed in 0.4
+
+- `homogeneity_test` held a fixed exchange rate at one while it scaled the
+  numeraire, so every `foreign="fixed_rate"` closure failed the test for a
+  reason that was the test's. The rate is nominal and now scales too.
+
+### Added toward 0.7
+
+- `read_har` and `write_har`: GEMPACK header array files, the format of the GTAP
+  database, without GEMPACK. On GTAP 10A (2014) the 86 headers harpy3 reads
+  agree with it exactly, and four GTAP identities close to single precision.
+  The data are licensed and never committed.
+
+### Release engineering (0.5)
+
+- CI runs the suite on Python 3.11–3.14 on Linux, macOS and Windows, and against
+  the installed wheel (`CGELAB_TEST_INSTALLED=1`), with `twine check`, both with
+  dsgelab installed so the bridge is tested. A
+  `validation` workflow runs the JuMP replica and the Hosoe transcription on
+  demand and weekly. A `release` workflow, started by pushing a tag `vX.Y.Z`,
+  checks that the tag matches the version in `pyproject.toml`, the package and
+  `CITATION.cff`, and that the dsgelab the `dsge` extra needs is on PyPI;
+  publishes to TestPyPI by trusted publishing, installs what TestPyPI serves and
+  runs the suite against it, and only then publishes to PyPI. The site's deploy
+  is skipped while the repository is private.
+- The sdist carries what its test suite needs (`MANIFEST.in`): the fixtures, the
+  site and the tool that runs its examples. `cgelab --version` and
+  `python -m cgelab`. The README's links are absolute, so they also work on PyPI.
+- `py.typed`; Python-version, OS and typing classifiers; the `dsge` extra, which
+  needs `dsgelab>=0.5`. The licence is declared as an SPDX expression (`MIT`),
+  with `LICENSE` as the licence file.
+- The examples, the docs and the site import the package as `cge` and dsgelab as
+  `dsg`, and link to dsgelab's site. The site's language selector names both
+  languages with an icon.
+- `CONTRIBUTING.md` with the definition of done and a release checklist; issue
+  and pull request templates; a known-limitations section in the README.
+- `docs/comparison.md` in English; the Portuguese version is
+  `docs/comparison.pt-br.md`.
+
+## 0.2.0 — 2026-09-25
+
+The first release as a standalone package. Four gaps and two bugs, found while building a
+regional recursive-dynamic CGE on the package, are closed. Every new `Economy` field defaults to
+zero, so a SAM without the new flows gives the same results as 0.1.0.
+
+### Fixed
+
+- **CET exports were never solved.** `export_rule="cet"` was accepted by `ModelSpec` and
+  advertised, but the solver always used fixed export shares. Output now splits along the CET
+  frontier; the domestic price comes from the inverse revenue function (`cet_domestic_price`).
+- **The external target was read from two fields.** Under `foreign="fixed_saving"` the trade
+  target came from `trade_balance0` and saving from `foreign_sav`, so moving `foreign_sav` alone
+  left a Walras residual that grew along a path. `foreign_sav` is now the single target.
+- **Institutional flows in the SAM were dropped.** Household income was read as the row total, but
+  the solver modelled only factor income: a SAM with a direct tax, a government transfer or a
+  remittance missed its own base year (by 12% on `toy.build_with_institutions`).
+- **LES marginal budget shares** assumed commodity spending equals income net of saving, which is
+  wrong with direct taxes or purchases made straight from an activity. They now use the calibrated
+  commodity budget (`Economy.hh_spend0`).
+
+### Added
+
+- `Scenario.export_price` — world export prices, read under CET and refused under fixed shares.
+  `sigma_cet` accepts a mapping by commodity.
+- Direct taxes (`gov <- hh`), government transfers (`hh <- gov`) and remittances (`hh <-> row`),
+  with saving out of disposable income. `PeriodResult.hh_direct_tax`; welfare income is net of
+  direct tax.
+- Factor income paid to government and abroad (`gov <- f`, `row <- f`); foreign saving is the
+  current account. `Scenario.foreign_factor_share` overrides the SAM's foreign shares.
+- `Scenario.fdi` — foreign direct investment that raises foreign saving and, in `run_path`, adds
+  the capital it buys to a foreign-owned stock whose returns leave the economy.
+  `PathResult.foreign_capital` records it.
+- Several capital stocks: `Growth.capital_factor` takes a sequence, `depreciation` a mapping, and
+  `allocation` shares domestic investment proportionally or by relative rent.
+- `run_path(economy=f(year, t))` — a different `Economy` each year, for changes that are not
+  scenario fields (input coefficients, a foreign-saving path).
+- `econ.diagnostics["unmodelled_flows"]` lists SAM cells the model does not read.
+- The JuMP export replicates all of the above; `validation/roundtrip_jump.py` runs 16 cases
+  against Ipopt (worst deviation 3e-12). Opt-in pytest cases with `CGELAB_RUN_JULIA=1`.
+- `toy.build_with_institutions` and `toy.build_with_specific_capital`.
+- A `LICENSE` file, continuous integration, a published site, and the comparison with other
+  packages as `docs/comparison.md`.
+
+## 0.1.0 — 2026-09-09
+
+First version, developed inside a research repository: SAM container, balance gate and
+sign-preserving RAS; calibration with margins, negative value added, LES and own-account
+activities; within-period solution under five closures; scenarios and wedge recycling; recursive
+dynamics; equivalent and compensating variation with composition-immune group aggregation;
+base-year, homogeneity and Walras diagnostics; export to JuMP.

cgelab-0.5.0/CITATION.cff

@@ -0,0 +1,24 @@
+cff-version: 1.2.0
+message: "If you use this software in a publication, please cite it as below."
+type: software
+title: "cgelab: a general toolkit for SAM-based computable general equilibrium models in Python"
+abstract: >-
+  Social accounting matrix handling and balancing, calibration, configurable nests and closures, CET and Armington trade, direct taxes, transfers and foreign ownership, within-period solution, recursive dynamics with several capital stocks and FDI, and welfare measurement, with base-year reproduction, homogeneity and Walras checks built in and an independent JuMP replica for validation.
+authors:
+  - family-names: "Moreira"
+    given-names: "Gustavo Hoffmann"
+    email: "gustavo@gakusai.net"
+    orcid: "https://orcid.org/0000-0003-0827-2521"
+version: "0.5.0"
+date-released: "2026-10-18"
+license: MIT
+# A repository URL is not an archivable reference. Connect the repository to Zenodo, cut a
+# release, and add the DOI below; that is what makes the citation stable.
+repository-code: "https://github.com/GustavoHM/cgelab"
+url: "https://gustavohm.github.io/cgelab/"
+# doi: "10.5281/zenodo.XXXXXXX"
+keywords:
+  - "computable general equilibrium"
+  - "social accounting matrix"
+  - "input-output"
+  - "Python"

cgelab-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Hoffmann Moreira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cgelab-0.5.0/MANIFEST.in

@@ -0,0 +1,9 @@
+# What the sdist needs beyond the package, so that its test suite runs from the
+# unpacked tree: the fixtures, the site whose examples are tested, and the tool
+# that runs them. validation/ needs Julia and stays out.
+include CHANGELOG.md CITATION.cff
+include tests/conftest.py
+recursive-include tests/data *.json
+include tools/check_site_examples.py
+graft site
+global-exclude .DS_Store

cgelab-0.5.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: cgelab
+Version: 0.5.0
+Summary: General-purpose toolkit for SAM-based computable general equilibrium models: balancing, calibration, closures, CET trade, institutions and foreign ownership, recursive dynamics with several capital stocks, and welfare.
+Author-email: Gustavo Hoffmann Moreira <gustavo@gakusai.net>
+License-Expression: MIT
+Project-URL: Homepage, https://gustavohm.github.io/cgelab/
+Project-URL: Documentation, https://github.com/GustavoHM/cgelab/tree/main/docs
+Project-URL: Repository, https://github.com/GustavoHM/cgelab
+Project-URL: Issues, https://github.com/GustavoHM/cgelab/issues
+Project-URL: Changelog, https://github.com/GustavoHM/cgelab/blob/main/CHANGELOG.md
+Keywords: cge,general equilibrium,social accounting matrix,input-output,armington
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Classifier: Topic :: Scientific/Engineering
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: pandas>=2.0
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=14; extra == "parquet"
+Provides-Extra: dsge
+Requires-Dist: dsgelab>=0.5; extra == "dsge"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# cgelab
+
+[![tests](https://github.com/GustavoHM/cgelab/actions/workflows/tests.yml/badge.svg)](https://github.com/GustavoHM/cgelab/actions/workflows/tests.yml)
+[![site](https://img.shields.io/badge/site-gustavohm.github.io%2Fcgelab-2b6cb0)](https://gustavohm.github.io/cgelab/)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/GustavoHM/cgelab/blob/main/LICENSE)
+
+A general toolkit for SAM-based computable general equilibrium models in Python.
+You supply a social accounting matrix. The package calibrates a standard nested
+CGE from it, solves each period, runs a recursive-dynamic path and measures
+welfare. The accounting checks that make any of it believable are built in
+rather than left to the user.
+
+A model is assembled from three separable objects, and keeping them separable is
+the point:
+
+| Object | Says |
+|---|---|
+| `SAM` | what the base year **was** |
+| `ModelSpec` | what is **assumed** about substitution and functional form |
+| `Closure` | which balances are imposed and **who adjusts** |
+
+Results can turn on the last two, so both travel with the results instead of
+living in a branch inside a solver.
+
+## Install
+
+```
+pip install cgelab                 # from PyPI
+pip install "cgelab[parquet]"      # adds pyarrow for .parquet SAMs
+pip install "cgelab[dsge]"         # adds dsgelab, for forward-looking investment
+pip install "cgelab @ git+https://github.com/GustavoHM/cgelab"   # the current main branch
+```
+
+For development:
+
+```
+git clone https://github.com/GustavoHM/cgelab && cd cgelab
+pip install -e ".[test]" && pytest
+```
+
+Requires Python 3.11+, numpy, scipy and pandas. Try it with no data at all:
+
+```
+cgelab                    # runs the bundled toy economy and prints the diagnostics
+cgelab my_sam.csv --sigma-armington 2.0 --sigma-va 0.5   # the same on your own SAM
+```
+
+## Quick start
+
+The bundled toy economy has every SAM entry written out, so the base year is
+known on paper and this runs as it is:
+
+```python
+import cgelab as cge
+from cgelab.examples import toy
+
+sam, econ = toy.build()
+print(cge.report(econ))           # base-year reproduction, Walras, homogeneity
+
+base  = cge.solve_period(econ)
+shock = cge.solve_period(econ, scenario=cge.Scenario(
+    name="tax +50%", product_tax=econ.ptax * 1.5))
+print(shock.summary())
+```
+
+A counterfactual over a horizon, and its welfare incidence:
+
+```python
+growth = cge.Growth(labour=0.005, tfp=0.010, depreciation=0.05, discount=0.05)
+years  = range(2021, 2046)
+
+W   = cge.consumer_wedge(econ, {"c_ind": 0.03})
+ref = cge.run_path(econ, years=years, growth=growth)
+alt = cge.run_path(econ, years=years, growth=growth,
+                   scenario=lambda y, t: cge.Scenario(consumer_wedge=W,
+                                                      wedge_revenue_to="capital")
+                                         if y >= 2026 else cge.Scenario())
+
+ev = cge.equivalent_variation(ref, alt)
+print(cge.ev_by_group(ev, {"hh_1": "rich", "hh_2": "poor"}))
+```
+
+With your own data, the first lines change (a `.parquet` SAM needs the `parquet` extra):
+
+```python
+sam  = cge.SAM.read("my_sam.parquet")       # or SAM.from_long(df) / SAM.from_square(df)
+sam.check_balance()                         # a hard gate, not a warning
+econ = cge.calibrate(sam, cge.ModelSpec(sigma_armington=2.0, sigma_va=0.5))
+```
+
+## Model structure
+
+* **Production:** Leontief between the intermediate bundle and value added, and
+  within the intermediate bundle. A configurable nest (CES, Cobb–Douglas or
+  Leontief) combines factors inside value added.
+* **Make:** commodity market shares are fixed at base-year proportions, so
+  activity levels follow from commodity output, `X = MSH @ Q`.
+* **Armington:** CES between domestic and imported varieties.
+* **Exports:** fixed shares by default, or a CET frontier that answers to world
+  export prices. The default is deliberate: the CET elasticity is the one
+  parameter of a standard CGE that input–output sources do not supply.
+* **Households:** Cobb–Douglas or LES over commodities, out of income net of
+  direct tax, saving and payments made straight to an activity. Income includes
+  government transfers and net transfers from abroad.
+* **Ownership:** factor income is shared among households, government and the
+  rest of the world. Returns to foreign-owned capital leave through the current
+  account, and foreign saving is the current account, not the trade balance.
+* **Government, investment, foreign:** five closure combinations, each with its
+  own adjusting variable (see `Closure`).
+* **Dynamics:** recursive, with one or several capital stocks accumulated from
+  their service flows, investment shared by relative rent, FDI that builds
+  foreign-owned capital, and an economy that may change year by year.
+
+The **numeraire factor's market is deliberately not solved**. It is left to
+Walras' law, so its residual is an independent check on the accounting rather
+than an identity the solver was told to satisfy. It is recorded on every
+period.
+
+## What is in the box
+
+| Capability | Entry point |
+|---|---|
+| SAM container, balance gate, sign-preserving RAS; GEMPACK/GTAP header array files | `SAM`, `read_har`, `write_har` |
+| Calibration: coefficients, nests, taxes (tariff and output tax inside prices), margins, LES subsistence, institutional flows, a list of cells the model does not read | `calibrate` |
+| Within-period equilibrium; investment, government (including deficit and revenue targets), foreign and labour closures | `solve_period`, `Closure` |
+| Trade: Armington, CET, export demand and import supply curves (large country) | `ModelSpec` |
+| Energy: a value-added-energy or capital-energy nest with interfuel substitution, emissions accounts, a carbon price, physical units | `ModelSpec.energy`, `add_emissions`, `add_physical_units` |
+| Counterfactuals: taxes, wedges, endowments, ownership, productivity, own-account levels, world prices, FDI, the investment basket | `Scenario` |
+| Recursive dynamics: several capital stocks, investment allocation, foreign-owned capital, a per-year economy | `run_path`, `Growth` |
+| Forward-looking investment (a Ramsey CGE solved by dsgelab) | `cgelab.bridge` |
+| Accounts: GDP from both sides, Laspeyres, Paasche and Fisher indices, terms of trade, the government account | `national_accounts`, `price_indices`, `government_account` |
+| Decompositions: subtotals by shock, Huff-Hertel welfare decomposition | `subtotals`, `welfare_decomposition` |
+| SAM multipliers, linkages, structural path analysis | `accounting_multipliers`, `linkages`, `structural_paths` |
+| Systematic sensitivity: Stroud quadrature and Monte Carlo over elasticities | `sensitivity`, `spec_sweep` |
+| Welfare: EV, CV and composition-immune group aggregation | `cgelab.welfare` |
+| Base-year reproduction, homogeneity, Walras | `cgelab.diagnostics` |
+| The same equilibrium as a JuMP model, for independent validation | `to_jump` |
+
+## Documentation
+
+- [Site](https://gustavohm.github.io/cgelab/): an overview with runnable examples, in English and Portuguese, and a replications page
+- [`docs/guide.md`](https://github.com/GustavoHM/cgelab/blob/main/docs/guide.md): the user guide, from SAM to welfare
+- [`docs/api.md`](https://github.com/GustavoHM/cgelab/blob/main/docs/api.md): API reference
+- [`docs/whitepaper.md`](https://github.com/GustavoHM/cgelab/blob/main/docs/whitepaper.md): the mathematics of calibration, the period equilibrium, recursive dynamics and welfare (in Portuguese)
+- [`docs/design-notes.md`](https://github.com/GustavoHM/cgelab/blob/main/docs/design-notes.md): the accounting decisions and the errors they prevent
+- [`docs/from-scripts.md`](https://github.com/GustavoHM/cgelab/blob/main/docs/from-scripts.md): porting an existing CGE pipeline
+- [`docs/comparison.md`](https://github.com/GustavoHM/cgelab/blob/main/docs/comparison.md): how this package compares with what exists, and where it does not win
+- [`CHANGELOG.md`](https://github.com/GustavoHM/cgelab/blob/main/CHANGELOG.md), [`ROADMAP.md`](https://github.com/GustavoHM/cgelab/blob/main/ROADMAP.md), [`CONTRIBUTING.md`](https://github.com/GustavoHM/cgelab/blob/main/CONTRIBUTING.md)
+
+## Verification
+
+Every number the package produces is checked against something it did not
+compute itself:
+
+- **Hand-built SAMs** whose every entry is written out, so the base year is known on
+  paper: base-year reproduction, zero-degree homogeneity and Walras' law in every
+  closure, on every variant (margins, own-account activities, institutions, trade
+  taxes, CET, energy nests, carbon).
+- **Closed forms and published tables**: Miller and Blair's Leontief inverse, the
+  stochastic growth model (for the bridge to dsgelab), Stroud quadrature on cubics,
+  CES first-order conditions, and the identities that hold in every equilibrium
+  (GDP from both sides, the welfare decomposition, subtotals that add up).
+- **A published model**: the tariff abolition of Hosoe, Gasawa and Hashimoto's
+  `stdcge` and `lrgcge` against a line-by-line JuMP transcription of the GAMS
+  programs, in all 49 displayed variables, to 2.4e-12.
+- **An independent replica**: `to_jump` writes the same equilibrium as a JuMP model
+  in which nothing is nested. `validation/roundtrip_jump.py` runs 34 cases; the
+  nested solver and Ipopt agree to 1.2e-11.
+
+```
+pytest                                                     # the suite, without external tools
+cd validation && julia --project=. -e 'using Pkg; Pkg.instantiate()' && cd ..
+python validation/roundtrip_jump.py                        # the JuMP replica
+python validation/replicate_hosoe.py                       # stdcge and lrgcge
+```
+
+## Scope and known limitations
+
+`cgelab` covers a single-country CGE at applied scale. It does not have the
+maturity of GAMS or GEMPACK, and [`docs/comparison.md`](https://github.com/GustavoHM/cgelab/blob/main/docs/comparison.md) says
+where it stands. Things to know before relying on it:
+
+- **Several regions** share one origin nest under the Armington. Factors do not
+  migrate, and the regional slice refuses margins, CET, LES, trade taxes, energy
+  nests and most closures by name. GTAP-style bilateral trade is 0.7.
+- **No complementarity**: activities cannot switch off, and there are no quotas,
+  price floors or capacity limits. That is 0.8.
+- **The solver** uses finite-difference Jacobians on a few unknowns. It is fine up
+  to a few hundred accounts; each commodity put on a trade curve adds an unknown.
+- **Fixed proportions everywhere** (`sigma_va = 0` in every activity) can leave
+  the model without a solution under full employment of every factor.
+- **Under fixed export shares** with a Cobb-Douglas Armington, the exchange rate is
+  not determined, and `solve_period` refuses that combination; near an Armington
+  elasticity of one it is badly conditioned.
+- **Forward-looking investment** goes through [dsgelab](https://github.com/GustavoHM/dsgelab)
+  (`pip install "cgelab[dsge]"`). `run_path` itself has no forward-looking agent.
+- **GTAP data** can be read, but not yet aggregated or turned into a SAM, and the
+  welfare decomposition has not been compared with GTAP's own.
+- **Platforms**: an editable install (`pip install -e`) can break silently on
+  Python 3.14 on macOS; install from the wheel if `import cgelab` fails.
+
+## Citing
+
+If a published result went through this package, cite it. Software is a
+methodological input like any other, and the version matters: a number that
+only reproduces under one version is not reproducible without it.
+[`CITATION.cff`](https://github.com/GustavoHM/cgelab/blob/main/CITATION.cff) carries the metadata, with the author's ORCID, in
+the format GitHub reads. A repository URL is not an archivable reference: each
+release will be archived on Zenodo, and the DOI it receives, which will be added
+to that file, is the reference to cite.
+
+## License
+
+MIT. See [`LICENSE`](https://github.com/GustavoHM/cgelab/blob/main/LICENSE).