Add the DC-EGM solver (discrete-continuous endogenous grid method)

.github/workflows/benchmark-main.yml

@@ -24,7 +24,7 @@ jobs:
             sleep 60
           done
           echo "GPU is free."
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
       - name: Install environment

.github/workflows/benchmark-pr.yml

@@ -32,7 +32,7 @@ jobs:
             sleep 60
           done
           echo "GPU is free."
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           ref: ${{ github.event.pull_request.head.sha }}
           fetch-depth: 0

.github/workflows/main.yml

@@ -29,27 +29,46 @@ jobs:
           - windows-latest
         python-version:
           - '3.14'
+        # The small macOS runner can't host four parallel JAX AOT compiles of the
+        # DC-EGM solve/oracle battery (it swap-thrashes for hours). Drop the `slow`
+        # set there; the platform-independent kernel stays covered on Linux + GPU.
+        include:
+          - os: macos-latest
+            pytest_extra: -m "not slow"
     steps:
-      - uses: actions/checkout@v6
-      - uses: prefix-dev/setup-pixi@v0.9.6
+      - uses: actions/checkout@v7
+      - uses: prefix-dev/setup-pixi@v0.10.0
         with:
-          pixi-version: v0.70.1
+          pixi-version: v0.72.0
           cache: true
           cache-write: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
           environments: tests-cpu
           activate-environment: true
           frozen: true
       - name: Run pytest
         shell: bash {0}
-        run: pixi run -e tests-cpu tests
+        run: pixi run -e tests-cpu tests ${{ matrix.pytest_extra }}
         if: runner.os != 'Linux' || matrix.python-version != '3.14'
       - name: Run pytest and collect coverage
         shell: bash {0}
-        run: pixi run -e tests-cpu tests-with-cov
+        # Phased: JAX compile caches make a pytest process's resident memory
+        # grow with every distinct compiled program it has run, and the DC-EGM
+        # solve/oracle battery (`slow`) compiles enough programs that one
+        # full-suite pass exhausts the 16 GB runner (the agent receives a
+        # shutdown signal mid-suite). Sequential invocations release each
+        # phase's memory before the next starts; coverage is appended across
+        # them.
+        run: |
+          pixi run -e tests-cpu pytest tests -m "not slow" \
+            --cov=./ --cov-report= -n 4 \
+          && pixi run -e tests-cpu pytest tests/solution -m slow \
+            --cov=./ --cov-append --cov-report= -n 2 \
+          && pixi run -e tests-cpu pytest tests --ignore=tests/solution -m slow \
+            --cov=./ --cov-append --cov-report=xml -n 2
         if: runner.os == 'Linux' && matrix.python-version == '3.14'
       - name: Upload coverage report
         if: runner.os == 'Linux' && matrix.python-version == '3.14'
-        uses: codecov/codecov-action@v6.0.1
+        uses: codecov/codecov-action@v7.0.0
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
   run-ty:
@@ -61,17 +80,19 @@ jobs:
         python-version:
           - '3.14'
     steps:
-      - uses: actions/checkout@v6
-      - uses: prefix-dev/setup-pixi@v0.9.6
+      - uses: actions/checkout@v7
+      - uses: prefix-dev/setup-pixi@v0.10.0
         with:
-          pixi-version: v0.70.1
+          pixi-version: v0.72.0
           cache: true
           cache-write: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
           environments: type-checking
           frozen: true
       - name: Run ty
         shell: bash {0}
-        run: pixi run ty
+        # The prek `ty` hook is skipped on pre-commit.ci (no pixi envs there);
+        # this job runs it against the `type-checking` env instead.
+        run: pixi run -e type-checking prek run ty --all-files
   run-tests-gpu:
     name: Run tests on GPU
     # Config:
@@ -84,17 +105,29 @@ jobs:
         run: |
           nvidia-smi
           nvcc --version || echo "nvcc not found"
-      - uses: actions/checkout@v6
-      - uses: prefix-dev/setup-pixi@v0.9.6
+      - uses: actions/checkout@v7
+      - uses: prefix-dev/setup-pixi@v0.10.0
         with:
-          pixi-version: v0.70.1
+          pixi-version: v0.72.0
           cache: true
           cache-write: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
           environments: tests-cuda12
           frozen: false
       - name: Run pytest on GPU
         shell: bash {0}
-        run: pixi run -e tests-cuda12 tests
+        # Run serially (-n0 overrides the task's -n 4): the single GPU runner is
+        # starved of host CPU/memory by parallel JAX AOT compiles. CPU jobs keep -n 4.
+        #
+        # The GPU-scale Mahler & Yum module runs first, in its own process: its
+        # solve kernels only fit the device when XLA fully fuses the
+        # max-over-actions reduction, and compiling them late in a long-lived
+        # process that has run the whole DC-EGM battery has produced an
+        # unfused executable whose scratch arena (half the state-action product)
+        # exceeds device memory. A fresh process pins the fused compile.
+        run: |
+          pixi run -e tests-cuda12 pytest tests/test_mahler_yum_2024.py -n0 \
+          && pixi run -e tests-cuda12 pytest tests -n0 \
+            --ignore=tests/test_mahler_yum_2024.py
   run-tests-gpu-32bit:
     name: Run tests on GPU (32-bit precision)
     runs-on: ubuntu-latest-gpu
@@ -103,25 +136,27 @@ jobs:
         run: |
           nvidia-smi
           nvcc --version || echo "nvcc not found"
-      - uses: actions/checkout@v6
-      - uses: prefix-dev/setup-pixi@v0.9.6
+      - uses: actions/checkout@v7
+      - uses: prefix-dev/setup-pixi@v0.10.0
         with:
-          pixi-version: v0.70.1
+          pixi-version: v0.72.0
           cache: true
           cache-write: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
           environments: tests-cuda12
           frozen: false
       - name: Run pytest on GPU with 32-bit precision
         shell: bash {0}
-        run: pixi run -e tests-cuda12 tests-32bit
+        # Run serially (-n0 overrides the task's -n 4): the single GPU runner is
+        # starved of host CPU/memory by parallel JAX AOT compiles. CPU jobs keep -n 4.
+        run: pixi run -e tests-cuda12 tests-32bit -n0
   run-explanation-notebooks:
     name: Run explanation notebooks on Python 3.14
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: prefix-dev/setup-pixi@v0.9.6
+      - uses: actions/checkout@v7
+      - uses: prefix-dev/setup-pixi@v0.10.0
         with:
-          pixi-version: v0.70.1
+          pixi-version: v0.72.0
           cache: true
           cache-write: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
           environments: docs

.github/workflows/publish-to-pypi.yml

@@ -6,7 +6,7 @@ jobs:
     name: Build and publish Python 🐍 distributions 📦 to PyPI
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - name: Set up Python 3.13
         uses: actions/setup-python@v6
         with:

.pre-commit-config.yaml

@@ -5,7 +5,7 @@ repos:
       - id: check-hooks-apply
       - id: check-useless-excludes
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: v2.23.0
+    rev: v2.25.1
     hooks:
       - id: pyproject-fmt
   - repo: https://github.com/lyz-code/yamlfix
@@ -39,7 +39,7 @@ repos:
       - id: name-tests-test
         args:
           - --pytest-test-first
-        exclude: tests/mock_regime.py|^tests/test_models/|^tests/data/
+        exclude: tests/mock_regime.py|^tests/test_models/|^tests/data/|tests/solution/_envelope_oracle.py|tests/solution/_rfc_2d_host.py|tests/solution/_branch_aware_vfi_oracle.py|tests/solution/_ds2024_housing_vfi_oracle.py
       - id: no-commit-to-branch
         args:
           - --branch
@@ -50,11 +50,11 @@ repos:
     hooks:
       - id: yamllint
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.37.2
+    rev: 0.37.4
     hooks:
       - id: check-github-workflows
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.16
+    rev: v0.15.20
     hooks:
       - id: ruff-check
         args:
@@ -68,6 +68,15 @@ repos:
           - jupyter
           - pyi
           - python
+  - repo: https://github.com/astral-sh/ty-pre-commit
+    rev: v0.0.56
+    hooks:
+      - id: ty
+        # `--no-project` keeps uv from creating a `.venv`/`uv.lock` in this
+        # pixi-managed repo; ty resolves third-party imports from the env named
+        # in `[tool.ty] environment.python` (run `pixi install` once).
+        args:
+          - --no-project
   - repo: https://github.com/kynan/nbstripout
     rev: 0.9.1
     hooks:
@@ -99,3 +108,7 @@ repos:
         exclude: docs/index\.md
 ci:
   autoupdate_schedule: monthly
+  # pre-commit.ci has no pixi environments and blocks network at hook runtime;
+  # the GitHub Actions run-ty job covers type checking.
+  skip:
+    - ty

.roborev.toml

@@ -0,0 +1,49 @@
+# roborev local repo config.
+# review_guidelines is injected into every review prompt for this repo as a
+# "## Project Guidelines" section. Agent/model/reasoning come from the global
+# ~/.roborev/config.toml (review_agent = codex, reasoning = thorough).
+
+display_name = "dev-pylcm"
+
+review_guidelines = '''
+Run this review as a sequence of GATES. Treat the diff as work that must earn a
+PASS at each gate before you sign off. Default to FAIL under uncertainty —
+absence of evidence is not evidence of correctness.
+
+At each gate, evaluate the change from TWO adversarial stances, then reconcile
+them into a single PASS/FAIL verdict for that gate:
+
+  PROSECUTOR — "This change is broken. Find the failure."
+    Assume a defect exists. Hunt for: incorrect logic, off-by-one and boundary
+    errors, unhandled None/empty/NaN/error cases, broken invariants, mutable
+    default or aliasing bugs, race conditions, resource leaks, data loss,
+    regressions in callers, and silent behavior changes. Construct the concrete
+    input or call sequence that breaks it. If you cannot construct one after a
+    genuine attempt, say so explicitly.
+
+  DEFENDER — "This change is correct and complete. Justify it."
+    Point to the evidence: tests covering the new/changed paths, invariants
+    preserved, edge cases handled, types/docs updated. Where the defense relies
+    on an assumption not visible in the diff, name the assumption.
+
+  VERDICT: PASS only if the defense withstands the prosecution with evidence in
+  the diff. Otherwise FAIL, and report the prosecutor's strongest concrete
+  finding.
+
+GATES (apply each; a gate that does not apply to this diff is PASS — state why):
+  1. Correctness & logic — does it do what the commit intends, for all inputs?
+  2. Edge cases & error handling — empty, None, zero, large, concurrent,
+     failure paths; numerical stability where relevant.
+  3. Tests — are the changed paths actually exercised? New behavior without a
+     test is a finding unless tests are clearly out of scope for this commit.
+  4. Interfaces & callers — are all call sites updated; any breaking
+     signature/behavior change?
+  5. Safety — data loss/corruption, unsafe deserialization, injection, secrets,
+     path traversal.
+  6. Clarity & maintainability — naming, dead code, needless complexity
+     (report as low severity only).
+
+Report only findings that survive the adversarial pass. For each: file:line,
+the gate it failed, severity, and the concrete failure scenario or the minimal
+fix. Do not pad the review with style nits dressed up as defects.
+'''

AGENTS.md

@@ -19,8 +19,10 @@ automation. Python 3.14+ is required.
 - `pixi run tests-with-cov` - Run tests with coverage reporting
 - `pytest tests/test_specific_module.py` - Run specific test file
 - `pytest tests/test_specific_module.py::test_function_name` - Run specific test
-- `pixi run ty` - Type checking with ty
-- `prek run --all-files` - Run all pre-commit hooks
+- `prek run ty --all-files` - Type checking with ty (a pre-commit hook; resolves
+  third-party imports from the pixi env named in `[tool.ty] environment.python`, so run
+  `pixi install` once)
+- `prek run --all-files` - Run all pre-commit hooks (includes the `ty` hook)
 - `pixi run -e docs build-docs` - Build documentation
 - `pixi run -e docs view-docs` - Live preview documentation
 - `pixi install` - Install dependencies
@@ -572,7 +574,7 @@ prose hides cases.
 
 - Extensive use of typing with custom types: user-facing aliases in `src/lcm/typing.py`,
   engine-side aliases and protocols in `src/_lcm/typing.py`
-- Type checking with ty (pixi run ty)
+- Type checking with ty (`prek run ty --all-files`)
 - Use `# ty: ignore[error-code]` for type suppression, never `# type: ignore`
 - JAX typing integration via jaxtyping
 

CHANGES.md

@@ -7,55 +7,26 @@ chronological order. We follow [semantic versioning](https://semver.org/).
 
 ## Unreleased
 
-### Phase grammar, cross-regime transitions, and model-level regime slots
-
-- `Phased(solve=..., simulate=...)` gives any regime-slot value a per-phase
-  variant; a bare value broadcasts to both phases. Carried states —
-  `Phased(solve=callable, simulate=Grid)` in `states` — are derived functions
-  during backward induction and genuine seeded-and-evolved states in
-  simulation. See the [phase grammar](docs/explanations/phase_grammar.ipynb)
-  explanation.
-
-- `fixed_transition(state_name)` marks a fixed state (identity law) in
-  `state_transitions`. The `None` spelling for fixed states is removed; a
-  regime-level `None` now masks a model-level entry instead.
-
-- Regime transitions take a third form: a per-target dict
-  `{target_regime: MarkovTransition(prob_func)}` whose key set declares the regime's
-  reachable targets — omitted regimes are structurally unreachable. Per-target
-  dicts in `state_transitions` hand state values across regime boundaries,
-  including into states the source regime does not carry and across grids that
-  differ between regimes.
-
-- Model-level regime slots: `Model(functions=..., constraints=..., states=...,
-  state_transitions=..., actions=...)` declares shared structure once and
-  merges it into every regime under the exactly-one-level rule. Broadcast
-  states and actions are pruned per regime by DAG reachability;
-  `model.pruned_variables` records the result.
-
-- `model.user_regimes` holds plain `lcm.regime.Regime` instances, finalized at
-  model build (model-level slots merged, default `H` injected, completeness
-  validated).
-
-### Per-target parameters
-
-- Per-target transition parameters nest under the target regime's name in the
-  params template — `template[regime][target][func][param]` — replacing the
-  `to_<target>_…` spelling. Param qnames parallel engine function qnames.
-
-- Parameters resolve at four levels, most to least specific: target / function
-  (one value broadcasts over the law's targets) / regime / model. Exactly one
-  level per parameter; multi-level specifications are ambiguity errors.
-
-- Canonical flat params always key transition-law params per target, every
-  target of a broadcast value sharing one leaf object. A coarse regime
-  transition is evaluated once and shared, so it takes no per-target
-  parameters.
-
-- Model-level `derived_categoricals` follow the exactly-one-level rule of the
-  other model-level slots: a name declared at model level and regime level is
-  an ambiguity error, also when the grids match.
-
+- Adds the DC-EGM solver (Iskhakov, Jørgensen, Rust & Schjerning 2017) as a
+  per-regime alternative to grid search: `Regime(solver=lcm.DCEGM(...))`.
+  Euler-equation inversion on an exogenous savings grid with a fast
+  upper-envelope scan (Dobrescu & Shanker 2022) — no consumption grid enters
+  the solve, and the credit-constrained segment is exact. Requires declared
+  `resources`, post-decision, and `inverse_marginal_utility` regime functions;
+  the model contract is validated at `Model` construction. Supports discrete
+  states and actions, EV1 taste shocks, stochastic processes, and passive
+  continuous states. Forward simulation works with grid-restricted consumption
+  (the intrinsic budget constraint is applied as a feasibility mask).
+
+- Adds regime-level EV1 taste shocks as a model property:
+  `Regime(taste_shocks=lcm.ExtremeValueTasteShocks())` with the scale as the
+  runtime param `{"taste_shocks": {"scale": ...}}`. The solve aggregates
+  discrete actions by the smoothed expected maximum and simulation draws the
+  discrete action by Gumbel-max — identical solutions under either solver.
+
+- Promotes the Iskhakov et al. (2017) retirement model to
+  `lcm_examples.iskhakov_et_al_2017` (brute-force and DC-EGM variants) with an
+  explanation notebook comparing the two solvers.
 
 ## 0.0.1
 

NOTICE

@@ -0,0 +1,18 @@
+PyLCM
+Copyright (c) 2023- The PyLCM Authors
+
+This product includes software adapted from third-party open-source projects.
+Their copyright notices and license terms are reproduced in the `licenses/`
+directory.
+
+--------------------------------------------------------------------------------
+OpenSourceEconomics/upper-envelope
+https://github.com/OpenSourceEconomics/upper-envelope
+
+Copyright (c) 2023-2025 The Upper-Envelope Authors
+Licensed under the Apache License, Version 2.0
+(full text in `licenses/upper-envelope-LICENSE`).
+
+The Fast Upper-Envelope Scan in `src/_lcm/egm/upper_envelope/fues.py` was adapted
+from this package and has since been substantially modified.
+--------------------------------------------------------------------------------