dsgelab 0.5.0__tar.gz

dsgelab-0.5.0/CHANGELOG.md

@@ -0,0 +1,235 @@
+# Changelog
+
+All notable changes to `dsgelab`. Versions follow [semantic versioning](https://semver.org/);
+before 1.0, a minor version may add to the API and a patch version only fixes bugs.
+
+## 0.5.0 — 2026-10-18
+
+The roadmap's milestone 0.5, the public release. No new solver features.
+
+### Added
+
+- `py.typed`: the package declares its type annotations (PEP 561).
+- CI tests the built wheel on Linux, macOS and Windows with Python 3.11 to 3.14, and
+  installs the sdist and tests it from its own tree. The site examples run in CI, and
+  `twine check --strict` passes on both artefacts. `DSGELAB_TEST_INSTALLED=1` makes the
+  suite import the installed package instead of `src/`.
+- `validation/run_all.sh` runs the whole external validation and summarises which
+  comparisons passed. `validation/setup_octave_packages.sh` installs the Octave packages
+  at the versions the comparison used, checked by sha256, and `validation/macromodelling/`
+  is a Julia project with MacroModelling.jl pinned. A weekly CI job runs all three.
+- A release workflow that publishes by trusted publishing, to TestPyPI first, tests what
+  TestPyPI serves, and only then publishes to PyPI.
+- `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and issue and pull-request templates. The
+  README has a section of known limitations.
+- `.github/workflows/pages.yml` publishes the site to GitHub Pages, pointing the links to
+  `docs/` at the files on GitHub. It is skipped while the repository is private.
+- The site in English, with the Portuguese version under `site/pt-br/`. The examples of
+  both versions run.
+- `validation/heutel/fetch.sh` downloads Heutel's MATLAB files from the public copy at
+  Georgia State University's repository and checks them; the six `.m` files are
+  byte-identical to the ones the port was validated on.
+- `dsgelab.examples.heutel.fetch()` downloads the same public copy, checks every file
+  by SHA-256, and writes the translated algebra of the port to a cache directory
+  (`~/.cache/dsgelab/heutel`, or `DSGELAB_HEUTEL_DIR`). Without it, `heutel.solve`
+  raises `HeutelSourceMissing` naming the call to make, and the Heutel tests are
+  skipped.
+
+### Changed
+
+- The validation scripts print their reports in English (`s.s.` for steady state,
+  `moments`, `max relative deviation`, ...), with the same columns and numbers.
+  `compare_estimation.py --no-mh` and `compare_policy.py --no-dynare` are the new flag
+  names, and `--sem-mh` and `--sem-dynare` still work.
+- The roadmap is in English (`ROADMAP.md`) and in Portuguese (`ROADMAP.pt-BR.md`).
+- Examples, documentation, tests and validation scripts import the package as
+  `import dsgelab as dsg`. The former alias `dk` came from the old name, dsgekit.
+- The site links to cgelab, whose `cgelab.bridge` uses dsgelab for the intertemporal part of
+  a model.
+- The one comparison made on a model that is not public (the applied DSGE of an unpublished
+  paper) is marked on the site as not reproducible from the repository.
+- The translated algebra of the Heutel port (`dsgelab/examples/_heutel_algebra.py`) is
+  no longer distributed, because it is a translation of Heutel's MATLAB files, which
+  carry no licence. `heutel.fetch()` generates it on the user's machine, and
+  `validation/heutel/translate.py` is gone.
+- The calibration example on the site and in the user guide is replaced by one whose
+  targets identify the free parameters (`target_jacobian` reports `identified=True`). The
+  former example had a target that held identically, and `calibrate` returned different
+  answers from different starting points.
+- The validation figures quoted on the site match the current run of
+  `validation/run_all.sh`. The README, `CONTRIBUTING.md`, the roadmap and the API
+  reference are corrected where they described the checks, the validation layers or the
+  API inaccurately.
+- Python 3.11 or later is required. Python 3.10 is dropped, because SciPy 1.15.3, the
+  last release for it, does not load on macOS 27.
+- Error messages, the labels of derived first-order conditions ("FOC for control c",
+  "Euler equation for state k", "constraint i: ...") and the header comments of files
+  written by `to_dynare` and `to_macromodelling` are in English. The exported model text
+  is unchanged.
+- The external validation runs on Dynare 7.2, with Octave 11.3.0 and the Octave packages
+  statistics 2.0.0 and datatypes 1.5.0. Every comparison prints the same numbers as on
+  Dynare 7.1, and the Heutel errors move in their last digit.
+
+### Fixed
+
+- `SecondOrderSolution.simulate`, `mean_correction` and `ergodic_mean`, `ThirdOrderSolution.simulate`
+  and `solve_third_order`, when given a covariance other than the one the solution was computed at,
+  combined risk terms (`g_ss`, `h_ss`) of the old covariance with shocks or a state covariance of the
+  new one. On the RBC with the standard deviation doubled, the mean correction of capital came out
+  5.8e-05 instead of 2.4e-03. They now solve again at the covariance asked for, through the new
+  `SecondOrderSolution.at_covariance`.
+- The sdist now carries `validation/heutel/reference.json`, which its own test suite
+  reads.
+- `validation/compare_diagnostics.py` honours `OCTAVE` and `DYNARE_MATLAB` and looks in
+  the same places as the other scripts, instead of only in Homebrew's.
+- `modelo.mod` and `modelo.jl`, written by a site example, had been committed at the
+  repository root; they are gone, and `tools/check_site_examples.py` now runs the
+  examples in a temporary directory.
+- Package metadata uses the SPDX license expression (`license = "MIT"`), which
+  setuptools will require from 2027.
+
+## 0.4.0 — 2026-10-11
+
+The roadmap's milestone 0.4: nonlinearities and the declaration of the model. Each item is
+validated against Dynare 7.1 on Dynare's own test files, against MacroModelling.jl, or
+against a closed form.
+
+### Added
+
+- `OccbinModel`, `occbin_simulate`, `OccbinResult`: occasionally binding constraints by
+  the piecewise-linear method of Guerrieri and Iacoviello (2015), as in Dynare's
+  `+occbin`, with any number of constraints, time-varying rules found backwards, Dynare's
+  regime update with `curb_retrench`, surprise shocks with re-planning, and the horizon
+  extended while a constraint binds at its end. `from_mod` reads `bind=`/`relax=` equation tags,
+  `occbin_constraints`, `shocks(surprise)` and the `occbin_setup`/`occbin_solver`
+  options; `ModFile.occbin_simulate` runs them. Against Dynare's `borrcon.mod` (one
+  constraint) and `dynrbc.mod` (two) to 2e-15, with identical regime histories.
+- `extended_path`, `quadrature_nodes`, `ExtendedPath`: the extended path (Fair and
+  Taylor, 1983) and the stochastic extended path (Adjemian and Juillard) of any order,
+  on Dynare's sparse or full tree of Gauss–Hermite nodes, with the hybrid second-order
+  risk correction, and `ModFile.extended_path`. Against Dynare's `burnside.mod` in seven
+  variants to 1.1e-11, and `linearmodel0.mod` to 2e-15.
+- Declared trends in `from_mod`: `trend_var`, `log_trend_var`, `var(deflator=)` and
+  `var(log_deflator=)` are detrended as Dynare does, and an equation that still depends
+  on the level of a trend is refused (Dynare's balanced-growth test, checked at several
+  points). `fs2000_nonstationary.mod` from Dynare's tests joins `compare_import`.
+- `balanced_growth`, `BalancedGrowth`, `ModFile.balanced_growth`: Dynare's `bgp.write`
+  problem, solved by Levenberg–Marquardt with restarts away from degenerate paths. The
+  residual matches Dynare's generated `bgpfun` to 2.2e-16 on its three tests.
+- `diagnose`, Dynare's `model_diagnostics`. It reports variables absent at the current
+  date, collinear relations of the static Jacobian with their variables and equations,
+  redundant equations of the dynamic Jacobian, and unit roots, and gives the same report
+  as Dynare on a model broken on purpose.
+- `analytic_steady_state`, `SteadyStateError`, `from_equations(steady_state_model=)` and
+  `ModFile.steady_state(analytic=True)`. A closed-form steady state is used only after it
+  zeroes the model's residuals, and refused otherwise, as Dynare refuses it.
+- Calibration equations inside the model, MacroModelling's `k[ss]/q[ss] = 2.5 | β`:
+  `from_equations(calibration_equations=)` and `steady_state(calibrate=)`. Against
+  MacroModelling.jl to 4e-15.
+- `steady_state(homotopy=)` and `homotopy_setup` in `from_mod`: continuation from a
+  parameter value where the model is easy, with adaptive steps.
+- `assemble`: several agents' optimisation problems and the closing equations in one
+  `Model`, refusing a variable chosen twice and renaming clashing multipliers.
+- `from_equations` accepts lags and leads of any order, each carried by an auxiliary
+  listed in `model.auxiliary`; a guess without the auxiliaries gets them from their
+  variables.
+
+### Changed
+
+- `perfect_foresight(jacobian="auto")` is the default: the stacked Jacobian is assembled
+  sparse from the model's exact derivatives when it has them (forward differences
+  otherwise); ex-post states use them too.
+- `klein` uses the real ordered QZ by default, the complex one as a fallback: SciPy 1.18's
+  complex reordering loses up to 1e-8 on a pencil with a zero root and refuses one with
+  several infinite roots.
+- Moments and variance decompositions of a model with a unit root mask the
+  nonstationary entries (`nan`) instead of failing; the Lyapunov equation is solved on
+  the stationary block of an ordered Schur form.
+- `from_mod` refuses a name declared twice.
+
+## 0.3.0 — 2026-10-11
+
+The first version that carries the roadmap's milestones 0.2 (optimal policy, welfare,
+perfect foresight with news) and 0.3 (estimation, smoothing, decomposition,
+forecasting), each item validated against Dynare 7.1 on Dynare's own files.
+
+### Changed
+
+- Renamed from `dsgekit` to `dsgelab`: `dsgekit` is taken on PyPI by an unrelated
+  project. The import name, distribution name, CLI entry point and URLs move together.
+
+### Added
+
+- `state_space`, `kalman_filter`, `kalman_smoother`: the state space of a first-order
+  solution, with observables in levels or logs (Dynare's `loglinear` with `logdata`),
+  measurement errors and missing data; the filter starts stationary roots at their
+  unconditional law and unit roots with the exact diffuse initialisation (Koopman and Durbin, 2000, unit
+  roots first in the Schur form, as Dynare does). The likelihood matches Dynare's on
+  `fs2000.mod` to 6e-12 and its `diffuse_filter` to 2.5e-12, and the smoother matches to
+  1e-14.
+- `EstimationProblem`, `posterior_mode`, `maximum_likelihood`, `metropolis_hastings`,
+  `smc`, `prior_predictive`, `model_probabilities`, `posterior_forecast`, `rhat`,
+  `effective_sample_size`: estimation, with Dynare's priors by mean and standard
+  deviation (`prior`), the Laplace and modified-harmonic-mean marginal likelihoods,
+  and `ModFile.estimation_problem` reading `estimated_params`, `varobs` and the options
+  of `estimation(...)`. Validated on Dynare's `fs2000.mod`: prior density to 4e-13, a
+  mode at least as high as Dynare's, Laplace by the same formula to 2e-13, and posterior
+  means within 3 Monte Carlo standard errors of Dynare's (largest 2.9).
+- `shock_decomposition`, `realtime_shock_decomposition`, `forecast`: against Dynare's
+  commands of the same names to 5e-15 (forecast bands to 6e-9).
+- `FirstOrderSolution.conditional_forecast(..., controlled=, levels=)`: Dynare's
+  `conditional_forecast` with `controlled_varexo`, to 1.6e-13 on its own test file.
+- `perfect_foresight_with_expectation_errors` and `News`: agents re-plan at each date of
+  news from the states they have reached; constant or shrinking horizon. Validated
+  against Dynare's `pfwee.mod` and `pfwee_constant_sim_length.mod` to 3e-12.
+- `perfect_foresight(..., shocks=)` validated against Dynare's `rbc_det1`–`3`
+  (anticipated shocks, initial conditions) to 1e-13.
+- `from_mod`: exogenous variables carry their level (`EXO_SS_e`, from `initval`), may
+  appear one period ahead, and the deterministic `shocks` block and `histval` are read;
+  `ModFile.deterministic`, `ModFile.news`, `ModFile.initial_states` and
+  `read_expectation_errors_csv` turn them into arguments for the solvers.
+- `osr(..., objective=, discount=)`: an optimal simple rule on welfare (minus
+  unconditional welfare at second order), Dynare's `osr` with `planner_objective`.
+- `discretionary_policy` and `DiscretionSolution`: optimal policy under discretion
+  (Dennis, 2007, as Dynare implements it), with IRFs, moments and welfare. Validated
+  against Galí's closed form and Dynare's `tests/discretionary_policy/dennis_1.mod`.
+- `osr` and `OSRResult`: optimal simple rules on a quadratic loss in unconditional
+  moments, Dynare's `optim_weights` convention. On Dynare's `osr_example.mod` the loss
+  matches Dynare's at its optimum to 2.6e-16, and the optimiser finds a lower one, which
+  Dynare's own objective confirms.
+- `welfare`, `welfare_model`, `consumption_equivalent`: second-order welfare,
+  conditional and unconditional, and for Ramsey models with the lagged multipliers at
+  zero. Matches Dynare's `evaluate_planner_objective` to 1.4e-12 for Ramsey and to
+  6.1e-10 under discretion.
+- `from_mod` reads `planner_objective`, `ramsey_model`, `discretionary_policy`,
+  `osr_params`, `optim_weights` and `osr_params_bounds`; `ramsey_model` and
+  `discretionary_policy` accept the resulting `ModFile`. `PrivateBlock` holds a
+  private sector with instruments left open.
+- `ramsey_model`, `ramsey_steady_state`, `ramsey_multipliers`: the Ramsey planner under
+  commitment, timeless perspective, derived symbolically from the private-sector
+  equations and a period objective. Validated against Galí's targeting rule and closed
+  form, and against Dynare's `ramsey_model` on three models
+  (`validation/compare_ramsey.py`).
+- `from_mod`, `ModFile`: read a Dynare `.mod` file, with macros, model-local variables,
+  `steady_state()`, and leads and lags of any order. Validated on eight `.mod` files read
+  unchanged, five of them from Dynare's `examples/` (`validation/compare_import.py`).
+- `solve(..., qz_criterium=)` and `klein(..., qz_criterium=)`: Dynare's convention that
+  admits a unit root.
+- `perfect_foresight(..., shocks=)`: a path of innovations, anticipated from the start.
+- `SecondOrderSolution.irf`: the generalised impulse response of the pruned rule.
+- `FirstOrderSolution.historical_decomposition` and `conditional_forecast`.
+- `symbolic.parse_system` and `symbolic.model_from_expressions`: the symbolic front end
+  split in two, so that derived equations reach the model builder without being printed
+  and re-parsed.
+
+## 0.2.0
+
+- Third-order risk slopes, linear estimation (Kalman filter, posterior mode,
+  random-walk Metropolis) and Chebyshev projection.
+- Standalone package, separate from the research repository.
+
+## 0.1.0
+
+- Steady state, first-order (Klein/QZ) and second-order perturbation, perfect foresight,
+  calibration on targets, symbolic front end, first-order-condition derivation,
+  exporters to Dynare and MacroModelling.jl.

dsgelab-0.5.0/CITATION.cff

@@ -0,0 +1,23 @@
+cff-version: 1.2.0
+message: "If you use this software in a publication, please cite it as below."
+type: software
+title: "dsgelab: a general toolkit for solving DSGE models in Python"
+abstract: >-
+  Steady state, Klein/QZ first-order solution, second-order perturbation and a partial third order (the cubic block and the risk slope), Chebyshev projection, perfect foresight with expectation errors, optimal policy (Ramsey, discretion, optimal simple rules) and welfare, Kalman filtering and smoothing, Bayesian estimation, shock decompositions and forecasts, reading Dynare .mod files, and export to Dynare and MacroModelling.jl. Validated against Dynare, MacroModelling.jl and closed-form solutions.
+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
+# The DOI is filled in with the first release archived on Zenodo, which makes the citation stable,
+# since a repository URL is not an archivable reference.
+repository-code: "https://github.com/GustavoHM/dsgelab"
+# doi: "10.5281/zenodo.XXXXXXX"
+keywords:
+  - "DSGE"
+  - "perturbation"
+  - "rational expectations"
+  - "Python"

dsgelab-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.

dsgelab-0.5.0/MANIFEST.in

@@ -0,0 +1,5 @@
+# The sdist carries the test suite, and test_heutel.py reads its reference
+# values from validation/. Nothing else under validation/ is needed to test.
+include CHANGELOG.md CITATION.cff LICENSE README.md
+recursive-include tests *.py
+include validation/heutel/reference.json

dsgelab-0.5.0/PKG-INFO

@@ -0,0 +1,332 @@
+Metadata-Version: 2.4
+Name: dsgelab
+Version: 0.5.0
+Summary: Solve, simulate and estimate DSGE models in Python: perturbation to second order (and a partial third order), perfect foresight, OccBin, optimal policy, Bayesian estimation and Dynare .mod import, validated against Dynare.
+Author-email: Gustavo Hoffmann Moreira <gustavo@gakusai.net>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/GustavoHM/dsgelab
+Project-URL: Documentation, https://github.com/GustavoHM/dsgelab/tree/main/docs
+Project-URL: Repository, https://github.com/GustavoHM/dsgelab
+Project-URL: Issues, https://github.com/GustavoHM/dsgelab/issues
+Keywords: dsge,perturbation,rational expectations,klein,macroeconomics
+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: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Intended Audience :: Science/Research
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: symbolic
+Requires-Dist: sympy>=1.12; extra == "symbolic"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# dsgelab
+
+[![tests](https://github.com/GustavoHM/dsgelab/actions/workflows/tests.yml/badge.svg)](https://github.com/GustavoHM/dsgelab/actions/workflows/tests.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/GustavoHM/dsgelab/blob/main/LICENSE)
+
+A general toolkit for solving DSGE models in Python. A model is declared once, as lists of
+state, jump and shock names and one function that returns the equilibrium residuals. The
+package computes the steady state, the first-order solution, impulse responses, moments,
+second-order risk corrections, nonlinear perfect-foresight transitions and calibration on
+targets from that declaration.
+
+The package is built so that the stochastic block and the deterministic transition are the
+*same model*. One way applied work fails is a perturbation solution built on one set of
+equations beside a transition path solved by a hand-written fixed point on another set, similar
+to the first but not identical. Here both call the same residual function, so the equations
+behind them cannot differ.
+
+```
+pip install dsgelab
+pip install "dsgelab[symbolic]"     # adds text equations with exact derivatives (sympy)
+```
+
+Requires Python 3.11 or later, numpy and scipy. Pandas is not needed.
+
+## Quick start
+
+```python
+import dsgelab as dsg
+from dsgelab.examples import rbc
+
+model, params, guess = rbc.build()
+sol = dsg.solve(model, params, guess=guess)
+
+print(sol.summary())
+irf = sol.irf("eps_a", size=0.01, periods=40)      # per cent deviations
+mom = sol.moments(cov={"eps_a": 0.007})            # std, corr, autocorr
+```
+
+A model of your own takes three lists and a function. The parameters can be any object with
+attributes, here a dataclass.
+
+```python
+import numpy as np
+from dataclasses import dataclass
+from dsgelab import Model, solve
+
+@dataclass
+class P:
+    alpha: float = 0.36
+    beta:  float = 0.99
+    delta: float = 1.0
+    gamma: float = 1.0
+    rho:   float = 0.95
+
+def equations(nxt, cur, eps, p):
+    y  = cur.a * cur.k ** p.alpha
+    y1 = nxt.a * nxt.k ** p.alpha
+    return [
+        nxt.k - ((1 - p.delta) * cur.k + y - cur.c),                       # resource
+        cur.c ** -p.gamma - p.beta * nxt.c ** -p.gamma                     # Euler
+            * (p.alpha * y1 / nxt.k + 1 - p.delta),
+        np.log(nxt.a) - p.rho * np.log(cur.a) - eps.eps_a,                 # technology
+    ]
+
+model = Model(states=["k", "a"], jumps=["c"], shocks=["eps_a"], equations=equations)
+sol = solve(model, P(), guess={"k": 0.2, "a": 1.0, "c": 0.36})
+```
+
+Variables are addressed by *name*, in `cur` for period `t` and `nxt` for `t+1`. When
+variables are read from a vector by position, swapping one index for another raises no error,
+and the program solves a different model from the one intended. Reading each variable by name
+rules that mistake out.
+
+The [user guide](https://github.com/GustavoHM/dsgelab/blob/main/docs/guide.md) goes from the
+declaration to second order, and the [site](https://gustavohm.github.io/dsgelab/) has runnable
+examples in English and Portuguese.
+
+## Terms
+
+- A *state* (predetermined variable) has its value for period `t` fixed before the innovation
+  of period `t` arrives, as capital and the technology level do. A *jump* (non-predetermined
+  variable), such as consumption, moves within the period in response to that innovation.
+- *Klein/QZ* is Klein's method for the linearised model, which orders the generalised Schur
+  (QZ) decomposition of the matrix pair `(B, A)` of the canonical form below.
+- The *risk correction* is the second-order term that shifts the decision rules in proportion
+  to the variance of future shocks. At first order it is zero.
+- *Pruning* drops, when the second-order rule is simulated, the terms of order higher than two
+  that the recursion would otherwise accumulate, so that simulated paths do not diverge.
+
+## What is in the box
+
+| Capability | Entry point |
+|---|---|
+| Steady state, with positivity and outer anchors | `steady_state` |
+| First-order solution (Klein/QZ, Blanchard–Kahn enforced) | `solve` |
+| Impulse responses, simulation, moments, variance decomposition | `FirstOrderSolution` |
+| Second-order perturbation and risk corrections | `solve_second_order` |
+| Third-order perturbation, partial (the cubic block and the risk slope) | `solve_third_order` |
+| Global solution by Chebyshev collocation, up to three states | `solve_projection` |
+| Nonlinear perfect-foresight transitions, announced policy and shock paths | `perfect_foresight` |
+| Perfect foresight with expectation errors (news, surprises) | `perfect_foresight_with_expectation_errors` |
+| Ramsey optimal policy under commitment (timeless), validated against Dynare | `ramsey_model` |
+| Optimal policy under discretion; optimal simple rules, on moments or on welfare | `discretionary_policy`, `osr` |
+| Kalman filter (exact diffuse start) and smoother; measurement error; missing data | `state_space`, `kalman_filter`, `kalman_smoother` |
+| Bayesian estimation: mode, Laplace, Metropolis-Hastings, SMC, R-hat, ESS, marginal likelihood; maximum likelihood | `EstimationProblem`, `posterior_mode`, `metropolis_hastings`, `smc` |
+| Shock decomposition (also real-time), forecasts with bands, conditional forecasts | `shock_decomposition`, `forecast`, the method `FirstOrderSolution.conditional_forecast` |
+| Welfare at second order, conditional and unconditional; consumption equivalent | `welfare`, `consumption_equivalent` |
+| Occasionally binding constraints (OccBin), any number of them, surprise shocks | `OccbinModel`, `occbin_simulate` |
+| Extended path, deterministic and stochastic (sparse or full tree, hybrid correction) | `extended_path` |
+| Models in levels: declared trends with Dynare's balanced-growth check; the growth path | `from_mod`, `balanced_growth` |
+| Read a Dynare `.mod` file, macros and leads/lags included | `from_mod` |
+| Export a model to Dynare and to MacroModelling.jl | `to_dynare`, `to_macromodelling` |
+| Calibration on targets, with an identification diagnostic; calibration equations inside the model | `calibrate`, `target_jacobian`, `from_equations(calibration_equations=)` |
+| Closed-form steady states, checked before use; homotopy for hard steady states | `analytic_steady_state`, `steady_state(homotopy=)` |
+| Model diagnostics (Dynare's `model_diagnostics`) and independent checks | `diagnose`, `dsgelab.diagnostics` |
+| Text equations with exact analytic derivatives, lags and leads of any order | `dsgelab.symbolic` |
+| Several agents' optimisation problems in one equilibrium | `assemble` |
+
+## Timing convention
+
+`eps` is the innovation dated `t+1`, unknown at `t`, with `E_t eps_{t+1} = 0`. An AR(1) is
+written as the residual
+
+```python
+def equations(nxt, cur, eps, p):
+    return [nxt.a - p.rho * cur.a - eps.eps_a]
+```
+
+and the resulting law of motion is `k_{t+1} = P k_t + Q eps_{t+1}`. Treating the innovation as
+known at `t` instead makes the model deterministic within the period, and every second-order
+risk correction then comes out zero without a warning. Of the package's conventions, this is
+the only one it cannot check in a user's model.
+
+Two checks run on every model without being requested. `solve` raises `BlanchardKahnError`
+when the Blanchard–Kahn condition fails, and the steady state is accepted only when it zeroes
+the residuals. Three others take one call each by the user. `check_identity` tests an
+identity such as Walras's law, `sol.accuracy()` reports the order of accuracy of a solution,
+and `target_jacobian` checks whether calibration targets identify the free parameters, which
+`calibrate` does not check by itself.
+
+## Canonical form
+
+```
+A E_t x_{t+1} = B x_t + C eps_{t+1},   x_t = [k_t ; u_t]
+u_t     = F k_t
+k_{t+1} = P k_t + Q eps_{t+1}
+```
+
+with `k` the predetermined variables (states) and `u` the non-predetermined ones (jumps). The
+Blanchard–Kahn condition requires the number of stable generalised eigenvalues of the matrix
+pair `(B, A)` to equal the number of states. When it fails, the equilibrium is indeterminate
+or does not exist, and `solve` raises `BlanchardKahnError` instead of returning `F` and `P`.
+
+## Documentation
+
+- [`docs/whitepaper.md`](https://github.com/GustavoHM/dsgelab/blob/main/docs/whitepaper.md), the mathematics the solvers implement
+- [`docs/guide.md`](https://github.com/GustavoHM/dsgelab/blob/main/docs/guide.md), the user guide, from the declaration to second order
+- [`docs/api.md`](https://github.com/GustavoHM/dsgelab/blob/main/docs/api.md), the API reference
+- [`docs/design-notes.md`](https://github.com/GustavoHM/dsgelab/blob/main/docs/design-notes.md), the numerical decisions and the errors each one avoids
+- [`docs/from-scripts.md`](https://github.com/GustavoHM/dsgelab/blob/main/docs/from-scripts.md), porting an existing research script
+- [`docs/comparison.md`](https://github.com/GustavoHM/dsgelab/blob/main/docs/comparison.md), how this package compares with the existing ones, and what it lacks
+- [`ROADMAP.md`](https://github.com/GustavoHM/dsgelab/blob/main/ROADMAP.md), what is still missing, and when it is planned
+- [`CONTRIBUTING.md`](https://github.com/GustavoHM/dsgelab/blob/main/CONTRIBUTING.md), how to report a problem and what a contribution needs
+- [The site](https://gustavohm.github.io/dsgelab/), with runnable examples in English and Portuguese (source in [`site/`](https://github.com/GustavoHM/dsgelab/tree/main/site))
+
+Questions and bug reports go to the [issue tracker](https://github.com/GustavoHM/dsgelab/issues).
+
+## Heutel environmental-policy example
+
+[`docs/heutel.md`](https://github.com/GustavoHM/dsgelab/blob/main/docs/heutel.md) documents the
+first-order port of Heutel's (2012) MATLAB replication scripts, including the optimal tax and
+the tax and quota rules with lagged information. The port is checked against the original
+algebra, run in Octave, and against impulse responses and moments solved independently in
+Dynare.
+
+```python
+from dsgelab.examples import heutel
+heutel.fetch()          # once per machine; needs an internet connection
+sol = heutel.solve("tax")
+irf = sol.irf("eps_a", size=0.01, periods=100)
+```
+
+The planner script's sensitivity calibration fails the admissible steady-state check, so the
+Table 2 baseline has to be requested explicitly, with `heutel.solve("planner", heutel.Params())`.
+Without it, `heutel.solve("planner")` raises `heutel.SteadyStateError`. The documentation lists
+the differences between the supplied code and the published paper.
+
+The port's scalar algebra is translated from Heutel's MATLAB files, which carry no licence, so
+it is not distributed with the package. `heutel.fetch()` downloads the public copy from Georgia
+State University's repository, checks each file against the SHA-256 of the files the port was
+validated on, and writes the translation to `~/.cache/dsgelab/heutel` (or to
+`DSGELAB_HEUTEL_DIR`).
+
+## Verification
+
+Each feature is validated against an independent reference where one exists, which may be
+another implementation, a closed form or a published result. A few rest on internal tests
+only, namely autocorrelations, variance decomposition, pruning, the second-order generalised
+impulse response, announced parameter paths and the Blanchard–Kahn check, and the export to
+MacroModelling.jl has no round trip. The checks come in three layers.
+
+The first layer is the test suite (`pytest`), which compares the output with answers known
+analytically. It has 148 tests. Of these, 65 need the `symbolic` extra (sympy) and 15 the
+Heutel files from `heutel.fetch()`, and without those files a run gives 137 passed and 11
+skipped. Among the closed forms it checks are the following.
+
+- The RBC with log utility and full depreciation has the solution `P = [[α, 1], [0, ρ]]` and
+  `F = [α, 1]`.
+- The New Keynesian example is determinate under a Taylor rule with `φπ = 1.5` and
+  indeterminate with `φπ = 0.8`, where `solve` raises `BlanchardKahnError`.
+- On a lognormal AR(1), the second-order coefficient `h_ss` equals `σ²`, so the risk
+  correction in the decision rule, `½·h_ss = σ²/2`, is the Jensen term.
+- The perfect-foresight transition reproduces the closed-form path `k_{t+1} = αβ k_t^α`.
+- On two independent AR(1) processes and one forward-looking equation, the shock loading is
+  the identity. The textbook formula read off the QZ treats every equation as holding ex post
+  and gives a dense loading here, which is why `klein` solves for the loading on the rows that
+  hold ex post
+  ([design notes](https://github.com/GustavoHM/dsgelab/blob/main/docs/design-notes.md#the-shock-loading-is-not-read-off-the-qz)).
+- Halving the displacement in `accuracy()` divides the first-order residual by about four and
+  the second-order residual by about eight.
+
+The suite runs from a clone of the repository.
+
+```
+git clone https://github.com/GustavoHM/dsgelab && cd dsgelab
+pip install -e ".[symbolic,test]" && pytest
+```
+
+The second layer, in [`validation/`](https://github.com/GustavoHM/dsgelab/blob/main/validation/README.md),
+runs Dynare's own example and test `.mod` files in Octave with Dynare, and one calibration in
+MacroModelling.jl. Each result is compared with `dsgelab`'s, for steady states, impulse
+responses, moments, optimal policy, perfect foresight, estimation, OccBin, the extended path,
+balanced growth and diagnostics. The same folder checks the port of Heutel (2012) against
+Heutel's own code. `bash validation/run_all.sh` runs all of it, and CI runs it weekly.
+
+The third layer is one comparison on an applied model from an unpublished paper by the author.
+That model is not public, so the comparison cannot be rerun from the repository. Of the three
+layers, the second is the one in which both the models and the reference software come from
+other authors.
+
+## Known limitations
+
+This section lists what the package does not do yet. The
+[roadmap](https://github.com/GustavoHM/dsgelab/blob/main/ROADMAP.md) says when each item is
+planned.
+
+- **Third order is partial.** The cubic block and the risk slope (`g_ssk` and `h_ssk`) are
+  implemented. Dynare's full decision-rule tensor, with the innovation in every monomial, and
+  the stochastic steady state are planned for 0.7. The tensors are dense, so their size grows
+  with the cube of the number of variables and shocks, and sparse tensors for large models are
+  planned for the same version.
+- **Estimation is linear.** The likelihood comes from the Kalman filter on the first-order
+  solution. There is no particle or inversion filter, so no estimation at second or third
+  order, and no gradient-based samplers (HMC/NUTS).
+- **No identification analysis, global sensitivity, or method of moments** (Dynare's
+  `+identification`, `+gsa`, `+mom`), and no HP- or band-pass-filtered theoretical moments.
+- **Global methods are limited** to Chebyshev collocation with up to three states. There is no
+  value or time iteration, endogenous grid, sparse grid, or Tauchen/Rouwenhorst discretisation.
+- **No Markov regime switching, heterogeneous agents, BVAR or DSGE-VAR.**
+- **No plotting.** Results are arrays and dictionaries, and plotting is left to the user.
+- **The extended path's hybrid correction stops at second order.**
+- **Trends can be declared only in a `.mod` file.** `from_equations` does not accept them yet.
+- **`from_mod` reads the model and ignores the script.** Commands such as `stoch_simul`,
+  `estimation` or `identification` are skipped, and their options are not applied. In the
+  model block, the constructs the reader cannot translate (`@#include`, `@#for`, `varexo_det`,
+  leads of a shock, `expectation`, `diff`, `adl`, external functions) are refused with an
+  error that quotes the line containing them. Coverage is validated on the Dynare examples and
+  tests listed in `validation/`.
+
+## Related package
+
+[cgelab](https://github.com/GustavoHM/cgelab), by the same author, solves computable general
+equilibrium models. Its module `cgelab.bridge` uses dsgelab for the intertemporal part of a
+model.
+
+## Citing
+
+If the package contributed to a published result, cite it as any other methodological input,
+with the version, because a number that reproduces only under one version cannot be reproduced
+without knowing which. [`CITATION.cff`](https://github.com/GustavoHM/dsgelab/blob/main/CITATION.cff)
+holds the same metadata in the format GitHub reads.
+
+Moreira, G. H. (2026). dsgelab: A general toolkit for solving DSGE models in Python (Version
+0.5.0) [Computer software]. https://github.com/GustavoHM/dsgelab
+
+```bibtex
+@software{dsgelab_2026,
+  author  = {Moreira, Gustavo Hoffmann},
+  title   = {{dsgelab}: a general toolkit for solving DSGE models in Python},
+  year    = {2026},
+  version = {0.5.0},
+  license = {MIT},
+  url     = {https://github.com/GustavoHM/dsgelab},
+  note    = {Python package}
+}
+```
+
+A DOI will be added with the first release archived on Zenodo.