dolo-plus syntax guide¶

Technical reference for computer scientists and software engineers

Language Classification¶

DDSL is a declarative domain-specific language for dynamic optimization problems. Like SQL for relational queries, DDSL lets users specify what problem to solve rather than how to solve it. The compiler handles algorithm selection, discretization, and code generation.

Design Principles¶

Principle	Description
Declarative	Specify the mathematical problem; compiler chooses algorithms
Typed	Every symbol has a declared domain and kind
Layered	Surface syntax (SYM) maps bijectively to internal representation (CORE)
Separated	Model specification, algorithm choice, and parameter values live in separate files
Composable	Stages combine into multi-period problems via connectors

Two-Layer Syntax Architecture¶

DDSL maintains two syntactic representations connected by a bijective translation:

                         φ (bijection)
  DDSL-SYM  ◄────────────────────────────────►  T core
  (surface)                                     (internal)

  • User-friendly                    • Formally rigorous
  • Backwards-compatible             • Explicit type annotations  
  • Implicit typing allowed          • Operator-theoretic form

DDSL-SYM is the authoring format—readable and compatible with existing Dolo models. T core (formerly “DDSL-CORE”) is the internal representation where all types and operators are explicit, enabling static validation and unambiguous code generation.

Type System¶

Every symbol must be declared. The type categories are:

Category	Role	Example Declaration
Spaces	Domains and codomains	`Xa @def R+`
Variables	Typed identifiers	`xa @in Xa`
Parameters	Model constants (part of mathematical problem)	`β @in (0,1)`
Settings	Solver configuration (numerical implementation)	`n_grid @in Z+`
Functions	Mappings between spaces	`u: A -> R`
Distributions	Probability measures	`D_w: Dist(W)`
Movers	Functional operators	`B: [X->R] -> [Y->R]`

Key distinction: Parameters define the economic problem (discount factor β). Settings configure the numerical solver (grid size). This separation ensures the mathematical model is independent of implementation choices.

Operator Registry¶

Built-in operators handle standard mathematical operations:

Operator	Type Signature	Semantics
`E_w`	`[X×W→R] → [X→R]`	Expectation over random variable `w`
`argmax_{a}`	`[X×A→R] → [X→A]`	Optimal action (returns policy function)
`max_{a}`	`[X×A→R] → [X→R]`	Optimal value
`~`	`Dist(X) → X`	Sample from distribution
`APPROX`	`Operator → ApproxOperator`	Discretization for numerical computation

Operators are higher-order—they transform functions, not scalar values. The APPROX operator is central to the methodization process, converting exact mathematical operators to approximate numerical implementations.

Compilation Pipeline¶

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│   Syntax    │    Υ    │Mathematical │    ρ    │  Numerical  │
│  (DDSL-SYM) │ ──────► │   Object    │ ──────► │    Code     │
└─────────────┘         └─────────────┘         └─────────────┘
       │                       │                       │
   YAML files            Bellman operators,       NumPy arrays,
   with perch tags       value functions          interpolation,
                         on function spaces       quadrature

Υ (Upsilon): The meaning map translates syntax into mathematical objects—Bellman operators on appropriate function spaces.

ρ (rho): The representation map compiles the (methodized, calibrated) model into executable numerical code.

Critical property: Numerical results approximate mathematical truth. Equality holds only in the limit as discretization refines.

Perch Annotations¶

Perch tags declare information availability—which σ-algebra (information set) a variable belongs to:

variables:
  states:
    "wealth": m[<]       # known at stage arrival
  controls:
    "consumption": c     # chosen at decision point (unmarked = decision perch)
  poststates:
    "savings": a[>]      # determined after decision

These are measurability assertions: m[<] states that m is measurable with respect to the arrival filtration. The compiler validates that equations respect these constraints—variables can only depend on information available at their declared perch. The preferred tags are [<] (arrival), unmarked (decision), and [>] (continuation); aliases [_arvl]/[_dcsn]/[_cntn] and [<-]/[-]/[->] are also accepted.

Three-File Model Structure¶

# ══════════════════════════════════════════════════════════════
# stage.yml — Pure mathematical specification (no numerics)
# ══════════════════════════════════════════════════════════════
symbols:
  spaces:
    "state space": X @def R+
  variables:
    states:
      "wealth": m @in X
    controls:
      "consumption": c @in Interval(0, m)
  parameters:
    "discount factor": β @in (0,1)
  functions:
    "utility": u: R+ -> R

equations:
  bellman: |
    V(m) = max_{c} { u(c) + β * E[V(m')] }

# ══════════════════════════════════════════════════════════════
# methodization.yml — Algorithm selection
# ══════════════════════════════════════════════════════════════
operators:
  E_shock:
    scheme: !gauss-hermite
    settings_profile: quadrature_config
  argmax:
    scheme: !golden-section  
    settings_profile: optimizer_config
  APPROX:
    scheme: !cubic-spline
    settings_profile: interpolation_config

# ══════════════════════════════════════════════════════════════
# calibration.yml — Concrete parameter and setting values
# ══════════════════════════════════════════════════════════════
parameters:
  β: 0.96

settings:
  quadrature_config:
    n_nodes: 7
  optimizer_config:
    tolerance: 1.0e-8
  interpolation_config:
    n_grid_points: 100

Analogies to Familiar Concepts¶

DDSL Concept	Software Engineering Analog
Stage file	Interface / protocol definition
Methodization	Dependency injection / strategy pattern
Calibration	Configuration / environment variables
Perch tags	Access modifiers (information visibility)
Υ map	Type checker / semantic analyzer
\(\mathbf{\mathrm{Ρ}}\) map	Code generator / JIT compiler
Mover	Higher-order function / functor
APPROX	Lossy serialization / quantization