Skip to content

Dolo Internals Documentation

A comprehensive guide to understanding how dolo works internally, from YAML model specification to compiled functions.

Contents

  1. Model Structure - Understanding the dolo Model object and its components
  2. YAML to Model - How YAML files are parsed and converted to Model objects
  3. Function Compilation - The process of compiling equations into vectorized functions
  4. Function Signatures - Understanding function inputs, outputs, and vectorization
  5. Practical Examples - Working examples and common patterns
  6. Time Indices in Compilation - How time indices (t, t+1, t-1) work in the compilation process
  7. Expectations vs Values (Recipes + Timing) - Where expectations live, and why V[t+1] differs from expectations:

Quick Overview

The Dolo Pipeline

YAML Model File
    ↓
Model Object Creation
    ↓
Equation Parsing
    ↓
Function Compilation (via recipes.yaml)
    ↓
Vectorized NumPy UFuncs
    ↓
Ready for Solving

Key Concepts

  • Model: Central object containing equations, symbols, calibration, and compiled functions
  • Symbols: Variables categorized by type (states, controls, exogenous, etc.)
  • Equations: Mathematical relationships defined in YAML blocks
  • Functions: Compiled, vectorized versions of equations for fast numerical evaluation
  • Recipes: Specifications defining function signatures and argument ordering

File Organization

packages/dolo/
├── dolo/
│   ├── compiler/
│   │   ├── model.py          # Model class and compilation
│   │   ├── model_import.py   # YAML import functionality
│   │   ├── factories.py      # Function factory creation
│   │   └── recipes.yaml      # Function signature specs
│   └── ...

Basic Usage

from dolo import yaml_import

# Load model from YAML
model = yaml_import('model.yaml')

# Access compiled functions
func = model.functions['transition']

# Vectorized evaluation
result = func(y_values, w_values, c_values, mr_values, params)

Key Insights

  1. Every equation block becomes a function - Each block in your YAML's equations: section gets compiled
  2. Functions are vectorized - Can evaluate thousands of points simultaneously
  3. Standardized signatures - All functions of the same type have consistent input/output patterns
  4. Two-file system - YAML defines the math, recipes.yaml defines the signatures

This documentation explains the internal workings of dolo v0.4.9.20 as used in the bellman-ddsl project.