Examples¶
Every example below is a stage — the atomic unit of Bellman calculus. A stage encodes one decision problem: arrival state, shocks, transitions, constraints, preferences, and the Bellman operator that solves it. Multi-period models compose stages into periods via connectors.
Each stage is structured around three perches — information sets at which the agent's state is observed:
- Arrival — the agent enters with pre-state variables (e.g., beginning-of-period assets before shocks resolve).
- Decision — shocks have resolved; the agent observes states and chooses controls.
- Continuation — the decision has been made; post-state variables (e.g., end-of-period savings) carry forward.
Each model appears in two forms:
- dolo-plus YAML — the declarative specification a modeler writes. It defines symbol groups, equation blocks, and annotations following the DDSL YAML schema.
- Formal MDP — the mathematical document derived from the YAML: state/action spaces, Bellman equation, first-order conditions, and calibration.
These are two views of the same mathematical object. The correspondence is exact: translating YAML to MDP and back should yield the original (the round-trip property).
Schema templates¶
- DDSL YAML schema (v0.1) — symbol groups, equation blocks, and annotation syntax that every stage YAML must follow.
Examples¶
| Model | Description | Stages | YAML | Formal MDP |
|---|---|---|---|---|
| Consumption-Savings IID | Single-stage consumption choice with IID income shock, solved via EGM | 1 | YAML | MDP |
| Buffer Stock (Normalized) | Carroll (2024) buffer stock model normalized by permanent income; permanent and transitory shocks with unemployment risk | 1 | YAML | — |
| Housing Owner | Two-stage discrete housing choice + continuous consumption; branching stage | 2 | YAML | housing, cons |
| Retirement Choice (DCEGM) | Branching model with discrete retirement decision and continuous consumption; DC-EGM / FUES | 3 | YAML | — |
| Unemployment Branching Portfolio-Consumption | Exogenous employment branching into worker and unemployed portfolio stages with fan-in to a shared consumption stage | 4 | YAML | MDP |
Portfolio-consumption stages¶
The portfolio-consumption family illustrates the core idea of Bellman calculus: the same stage building blocks compose into four period configurations, each a valid economic model. Only the wiring changes.
| Stage | Description | YAML | Formal MDP |
|---|---|---|---|
| cons_stage | Deterministic consumption choice (EGM-compatible) | YAML | MDP |
| port_stage | Portfolio allocation with correlated shocks | YAML | MDP |
| noport_stage | No-portfolio-choice income stage | YAML | MDP |
See also: Solving via conjugation — how semi-conjugacy relates the four period configurations.
Notebooks¶
| Notebook | Description |
|---|---|
| Modular portfolio-consumption (FFP) | Self-contained walkthrough of Bellman calculus: four period configurations solved with functional fixed-point iteration |