Home
Bellman calculus is a declarative language for expressing modular Bellman problems in economics. It gives Bellman operators (\(\mathbb{T}\)) a standard, inspectable computational representation, so models can be built, communicated, and reimplemented without reinventing notation or deciphering bespoke research code.
-
Expressive
Write down a Bellman operator once—unambiguously, in a way that matches the mathematics.
-
Modular
Build models from reusable stages; variants and robustness checks become composition, not reinvention.
-
Implementation-agnostic
You choose and code all implementations so models can evolve and be run across different programming languages.
\(\mathbb{T}\)-calculus in your workflow¶
Every economic model maps between three layers: the math you write on paper, the syntax that describes it to a computer, and the code that runs. Usually, these mappings are implicit—locked inside solver conventions, paper appendices, and local assumptions.
What is Bellman calculus (SYM/CORE)?
Bellman calculus is a functional programming system: it specifies sets of named expressions that define Bellman operators and their composition. The core Bellman-calculus syntax (CORE) is an abstract representation that maps to the formal definition of a modular dynamic programming language. Symbolic implementations in this repo are SYM layers; today this is dolo-plus / Dolang+, which uses implicit (desugaring/inference) rules to normalize surface YAML into a well-typed Bellman-calculus stage before compilation.
\(\mathbb{T}\)-calculus makes the cross translation between the math to the syntax to the code transparent, painless and explicit:
-
Υ (meaning map)
Syntax \(\leftrightarrow\) theoretical markov decision process
-
\(\mathbf{\mathrm{Ρ}}\) (representation map)
Methodized + calibrated model \(\leftrightarrow\) representation ready for computation (\(\mathbf{\mathrm{Ρ}}\)-facing)
dolo-plus
dolo-plus extends Dolo with a YAML syntax for stages and their composition.
Author stages/periods in YAML, then compile to executable model objects.
Matsya (MatsΥa)
Translate between model descriptions, stage YAML, and formal math. Use it to draft specs/examples and to check notation against the docs.
Bridging theory and computation¶
\(\mathbb{T}\)-calculus makes the Bellman operator explicit: a typed, inspectable declaration of the economic problem you mean. A well-typed declaration corresponds to a well-defined functional Bellman problem — without committing you to a particular solution method, value representation, or software architecture.
-
Υ What you specify
Information timing (perches), typed symbols, transitions, rewards, and constraints — i.e. the objects that define a concrete Bellman operator.
-
ρ What stays flexible
Solver choice (VFI/EGM/…), discretization and interpolation, value representations, and backend code objects/classes.
Stages¶
Within a stage: information sets, forward kernels, backward operators¶
The building block of Bellman calculus is a stage: a modular Bellman operator factored into three perches (information sets). A perch is the bundle of model objects (states, controls, value objects, constraints, and operators) that are measurable at that information set.
-
≺ Arrival (
[<])Objects measurable before within-stage shocks are realized.
-
· Decision (unmarked)
Objects measurable after shocks are observed, when choosing an action.
-
≻ Continuation (
[>])Objects measurable after the action is taken and within-stage uncertainty is resolved.
Variables (states, controls, values) carry perch tags (z[<] for arrival, unmarked for decision, z[>] for continuation) to encode information timing: a tag says what the variable is allowed to depend on at that perch.
Backward solution (movers)¶
Solution proceeds backward from continuation to arrival via two movers (value transformers) that link adjacent perches:
-
B Continuation → Decision (\(\mathbb{B}\))
At decision time, take expectations and/or optimize over controls.
\[ \mathrm{v}(x) = (\mathbb{B}\, \mathrm{v}_{\succ})(x) = \sup_{a \in \Gamma(x)}\Bigl\{\mathrm{r}(x, a) + \beta\,\mathbb{E}\bigl[\mathrm{v}_{\succ}\!\bigl(\mathrm{g}(x, a, \eta)\bigr) \mid \mathcal{F}\bigr]\Bigr\}. \] -
I Decision → Arrival (\(\mathbb{I}\))
At arrival time, integrate over shocks realized before the decision.
\[ \mathrm{v}_{\prec}(x_{\prec}) = (\mathbb{I}\, \mathrm{v})(x_{\prec}) = \mathbb{E}\Bigl[v\!\bigl(\mathrm{f}(x_{\prec}, \zeta)\bigr)\Bigr]. \]
The factored Bellman operator for a stage is:
\(\mathbb{T} = \mathbb{I} \circ \mathbb{B}\), so \(\mathrm{v}_{\prec} = \mathbb{T}\, \mathrm{v}_{\succ}\).
Forward transitions (kernels)¶
Forward evolution within a stage is specified by two transition kernels (pure functions) declared in YAML as
arvl_to_dcsn_transition and dcsn_to_cntn_transition. These kernels are measurable maps between perches: they enforce information timing by construction.
-
f Arrival → Decision kernel (\(\mathrm{f}\))
Shock realization / information reveal. (YAML:
equations.arvl_to_dcsn_transition)\[ x = \mathrm{f}(x_{\prec}, \zeta) \] -
g Decision → Continuation kernel (\(\mathrm{g}\))
Apply the action (policy) and resolve any remaining within-stage uncertainty. (YAML:
equations.dcsn_to_cntn_transition)\[ x_{\succ} = \mathrm{g}(x, a, \eta), \qquad a = \pi(x) \]
Composition¶
Models are built by composition: wiring reusable stages together by a shared boundary field name (a state variable in the common namespace of a period).
Formally, \(\langle \mathsf S_1, \mathsf S_2 \rangle\) is valid when the continuation space of \(\mathsf S_1\) matches the arrival space of \(\mathsf S_2\) (or is made to match by an explicit connector \(\mathrm{c}\)).
-
P period
A local namespace containing an ordered list of stage occurrences (with an entry/exit boundary field).
-
κ connectors (intra + inter-period)
Rename maps when boundary names don't line up: within-period connectors (stage-to-stage) and between-period connectors (period-to-period). Uses
:=:field isomorphism syntax. -
N nest
A finite-horizon sequence of period instances wired by between-period connectors (position-aligned renames).
What it looks like (YAML)¶
A stage declaration makes a Bellman operator concrete by specifying typed symbols at each perch, two transition kernels (\(\mathrm{f}, \mathrm{g}\)), and two backward movers (\(\mathbf{B}, \mathbf{I}\)).
In dolo-plus (Dolang+), you typically keep three small YAML files: a stage file (symbolic), a methodization file (numerical schemes), and a calibration file (parameter/setting values).
name: cons_stage
symbols:
prestate:
m: "@in R++"
states:
m_d: "@in R++"
controls:
c: "@in R+"
poststates:
a: "@in R+"
values:
V[<]: "@in R"
V[-]: "@in R"
V[>]: "@in R"
equations:
arvl_to_dcsn_transition: |
m_d = m
dcsn_to_cntn_transition: |
a = m_d - c
cntn_to_dcsn_mover:
Bellman: |
V[-] = max_{c}((c^(1-ρ))/(1-ρ) + β*V[>])
See the DDSL YAML schema for the full v0.1 object shapes and invariants.
Ask Matsya¶
Translate a model description into stage YAML, or ask about any part of the Bellman calculus spec.
Start your journey¶
Want the math?
The formal foundations — stages, factored Bellman operators, contraction, and composition.
Learn by example
Annotated YAML models from consumption-savings to lifecycle portfolio choice.
