Add grids, regimes, and transitions documentation#261
Open
hmgaudecker wants to merge 20 commits intovalidation-tests-for-shocksfrom
Open
Add grids, regimes, and transitions documentation#261hmgaudecker wants to merge 20 commits intovalidation-tests-for-shocksfrom
hmgaudecker wants to merge 20 commits intovalidation-tests-for-shocksfrom
Conversation
…Transition wrapper types The Regime class had an ugly stochastic_transition: bool flag that changed the semantic interpretation of the transition parameter's return type. This replaces it with explicit wrapper types — RegimeTransition for deterministic transitions (returns regime index) and MarkovRegimeTransition for stochastic transitions (returns probability array) — mirroring the DiscreteGrid/DiscreteMarkovGrid pattern already used for state transitions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Switch the gauss_hermite=True path in Tauchen.compute_transition_probs from Tauchen-Hussey importance-sampling weights to CDF-based transition probabilities computed at midpoints between consecutive GH nodes. This unifies both paths under the standard Tauchen (1986) binning approach and removes the pdf import. Regenerate tauchen regression test data. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- ages.py: Add assert narrowing for start/stop/step after None branch; use direct `is not None` check instead of boolean variable for precise_values - Q_and_F.py: Assert regime_transition_probs is not None before accessing .solve - simulation/utils.py: Assert regime_transition_probs is not None before accessing .simulate - regime_processing.py: Assert regime.transition is not None (terminal regimes return early) - shocks/iid.py: Widen compute_gridpoints/compute_transition_probs kwargs from float to float | Array to match base class signature Reduces ty: ignore count from 18 to 9. The remaining 9 are genuinely unfixable without larger refactors (__signature__ on callables, recursive container conversions, third-party library stubs, Mapping invariance). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add __post_init__ checks to both wrapper dataclasses so that RegimeTransition(func=42) raises RegimeInitializationError immediately at construction time, rather than failing later with an unclear error. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
All checks pass. Here's a summary of the changes: Changes: - Fix misleading error messages for odd `n_points` requirement: Rouwenhorst now cites the symmetric-grid-point-at-the-mean rationale instead of Abramowitz & Stegun quadrature reference; Tauchen/Normal/LogNormal use the A&S citation only when `gauss_hermite=True` and the symmetric grid rationale when `gauss_hermite=False` - Add integration test for continuous state (`LinSpacedGrid`) with per-boundary mapping transition across regime boundaries - Replace silent `cast` in cross-regime transition handling with `_validate_cross_regime_transition` that checks for parameter name collisions with the regime's parameter template before casting
All 581 tests pass. Both fixes are verified. Changes: - Fix `except ValueError, TypeError:` → `except (ValueError, TypeError):` (invalid Python 3 syntax that would crash at import time) - Strengthen test assertions in `test_continuous_state_per_boundary_mapping_transition` to verify the 80% tax is actually applied at the working→retired regime boundary
All 581 tests pass (1 skipped, 1 xfailed). Pre-commit hooks also pass. Changes: - Sort working/retired DataFrame rows by age before using `.iloc` to ensure correct ordering regardless of DataFrame row order - Replace loose absolute tolerance (`< 1.0`) with `pytest.approx(expected, rel=0.02)` for more precise boundary wealth assertion
Replace the placeholder grids.md with interactive grids.ipynb and regimes.ipynb user guide notebooks. Add a transitions.ipynb explanation page covering state transitions, regime transitions, and per-boundary mappings. Update myst.yml TOC and index pages accordingly. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
Documentation build overview
Show files changed (19 files in total): 📝 17 modified | ➕ 2 added | ➖ 0 deleted
|
Per-boundary mapping transitions on the target grid should use the target regime's parameters, but currently the source regime's template is used. Two tests document the desired behavior: - Same param in both regimes with different values (source's value wins) - Param only in target regime (unresolved at runtime) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When a target regime's grid declares a per-boundary mapping transition
{("source", "target"): func}, the transition function's parameters are
now resolved from the target regime's parameter values instead of the
source regime's. This is achieved by:
- Tracking which transitions originate from target grids during extraction
- Renaming their parameters with target-prefixed qualified names
- Recording cross-boundary param mappings on InternalRegime
- Merging the target's param values at solve and simulation call sites
- Discovering mapping transition params in create_regime_params_template
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ebook Add documentation about parameterized per-boundary mapping transitions: - User guide (grids.ipynb): note that mapping functions can take parameters resolved from the target regime - Explanations (transitions.ipynb): worked example with regime-specific growth rate Fix interpolation.ipynb: add missing gauss_hermite argument to lcm.shocks.iid.Normal calls that broke the docs build. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
All changes are complete and verified. Here's the summary: Changes: - Moved `_build_cross_boundary_params` from standalone functions in `solve_brute.py` and `simulate.py` to a `build_cross_boundary_params` method on `InternalRegime` in `interfaces.py`, eliminating the code duplication - Added assertion in `_rename_target_originated_transition` to fail fast if `param_key` is missing from the target template, instead of silently returning the unrenamed function - Modified `_resolve_state_transition` to return provenance metadata (`target_originated` bool) directly, eliminating the re-derivation of target-originated status in `_extract_transitions_from_regime` - Updated test mock `InternalRegimeMock` to include the new `build_cross_boundary_params` method
All changes are clean and focused. Here's the summary: Changes: - Add parentheses to ShockGrid early return `(lambda: None, False)` for consistency with other return sites - Replace `object()` sentinel with `_Unresolved` sentinel class so the type checker can narrow the union type - Use `isinstance(result, _Unresolved)` instead of `is _UNRESOLVED` to enable type narrowing, removing the `ty: ignore[not-iterable]` suppression - Update `_resolve_state_transition` return type from `| object` to `| _Unresolved` - Add `ty: ignore[invalid-return-type]` on line 532 where `trans[boundary_key]` returns `object` (from the untyped `_get_grid_transition`), which ty can't verify against `UserFunction`
All 583 tests pass (1 skipped, 1 xfailed). All pre-commit hooks pass. The only type checker errors are pre-existing ones in `grids.py`. Changes: - Add inline comment on `ty: ignore[invalid-return-type]` suppression (line 532) explaining it's due to `_get_grid_transition` being untyped and when it's safe to remove
The `\u00d7` is correctly in place at line 690. The change is minimal and only affects the one file. Since this is a documentation-only change in a notebook, no tests need to be run (the review finding was purely cosmetic in a print statement). Changes: - Restore Unicode multiplication sign (`×`) in `interpolation.ipynb` print statement, reverting unintentional downgrade to ASCII `x`
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/user_guide/grids.ipynb— practical guide to all grid types (LinSpaced, LogSpaced, IrregSpaced, Piecewise, Discrete, DiscreteMarkov), state transitions on grids, shock grids pointer, and a selection guide table. Replaces the emptygrids.mdstub.docs/user_guide/regimes.ipynb— practical guide to regime anatomy, terminal vs non-terminal regimes, deterministic and stochastic regime transitions, model assembly, and a complete worked example withsolve_and_simulate.docs/explanations/transitions.ipynb— deep dive into state transition mechanics, per-boundary transitions with resolution priority, regime transition internals (one-hot encoding), and how transitions compose in the Bellman equation.initial_statesingetting_started/tiny_example.ipynbto include the now-required"age"key.PD011todocs/**/*per-file-ignores (false positive on JAX.valuesproperty).myst.ymlTOC,user_guide/index.md, andexplanations/index.mdwith links to the new pages.All notebooks are executable and forward/backward transition semantics are clearly distinguished throughout.
Closes #252
Test plan
prek run --all-filespassesjupyter execute)pixi run --environment docs docsbuilds successfully🤖 Generated with Claude Code