Skip to content

DDSL Foundations Documentation

Version: 0.2.0
Date: December 8, 2025
Status: Working Draft

Version History

Version Date Tag Summary
0.2.1 Dec 22, 2025 foundations-v0.2.1 DDSL-SYM/T core two-layer architecture. Bijection requirement for backwards compatibility.
0.2.0 Dec 8, 2025 foundations-v0.2.0 Three-file architecture: stage/methodization/calibration separation. Removed @methods from movers. Added operator declarations and settings profiles.
0.1.0 Nov 24, 2025 foundations-v0.1.0 Initial foundations with Υ/ρ maps, symbol system, ADC structure.

Tagging Convention

To tag a version in git: 

git tag -a foundations-v0.2.0 -m "Foundations v0.2.0: Three-file architecture"
git push origin foundations-v0.2.0

Document Structure

This documentation is organized into separate files for each major section. Each file contains a complete, self-contained treatment of its topic.

Main Sections

  1. Mathematical Definition of the DDSL
  2. Universes and Spaces

  3. Layer Architecture

  4. Primitive Objects

  5. Primitive Numerical Objects

  6. Primitive Function Objects (Backus Objects)

  7. Symbol System

  8. Symbol Universe Partition
  9. Symbol Hierarchy (Spaces, Functions, Distributions, Movers)
  10. Operator Registry (E, argmax, ~, APPROX)
  11. Variables, Parameters, and Settings

  12. Methods and Schemas

  13. Stages, Methodization, and Calibration

  14. Syntactic Stages
  15. Methodization Functor (M) — attaches schemes to operators
  16. Two-Part Calibration (Parameters vs. Settings)

  17. From (operator, method) to AST under ρ

  18. Bellman Theory Integration

  19. Movers as Central Concept
  20. Built-in Operators Inside Movers
  21. ADC Structure and Perches

  22. Convergence in the Limit

  23. Representation Maps

  24. Mathematical Meaning Map (Υ) — syntax → math
  25. Computational Representation Map (ρ) — methodized + calibrated → numerical
  26. Numerical Meaning Function (lookup table)

  27. Equality Only in the Limit

  28. Execution Pipeline

  29. Complete 8-Stage Pipeline
  30. Methodization Before Calibration
  31. Threading Υ and ρ Through Pipeline

  32. End-to-End Example

  33. DDSL-SYM / T core Architecture (NEW - Dec 22, 2025)

  34. Two-Layer Syntax Architecture
  35. Bijection Requirement
  36. Backwards Compatibility Strategy

  37. Integration with Υ/ρ Framework

  38. Type System (Advanced - To be completed later)

Example Files (primitives/)

Appendices

A. Terminology

B. Primitive Objects Registry

C. Numerical Schemes Registry

Reading Guide

For First-Time Readers

Start with Section 1 (Mathematical Definition) to understand the foundational framework, then proceed sequentially through Sections 2-4 to grasp the symbol system, operator registry, and the methodization/calibration distinction.

For Implementers

Focus on Sections 3 (Symbol System with Operator Registry), 4 (Methodization and Calibration), 6 (Representation Maps), and 7 (Execution Pipeline) for the practical aspects of parsing and code generation.

For Theorists

Sections 1 (Mathematical Definition), 5 (Bellman Theory with Movers), and 6.1-6.2 (Υ and ρ definitions) provide the theoretical foundations.

Key Concepts

Concept Definition See Section
DDSL-SYM Surface syntax layer: economist-friendly, backwards-compatible §8
T core Internal representation: operator-theoretic, formally rigorous §8
φ (phi) Bijective translation map: SYM ↔ T core §8.3
Perch Information set / local context within a stage (a filtration step: arrival/decision/continuation) §3.4.10, §5.2
Mover Functional operator transforming functions/distributions between perches §3, §5
Operator Registry Built-in operators: E, argmax, ~, APPROX §3.5
Methodization (M) Attaching schemes to operators (before calibration) §4.2
Υ (Upsilon) Mathematical meaning map: syntax → math §6.2
ρ (rho) Computational representation: calibrated → numerical §6.3
APPROX Approximation operator that converts math to numerical §3.5.5

Document Status

Section Status Last Updated
1. Mathematical Definition Complete Nov 24, 2025
2. Primitive Objects Complete Nov 24, 2025
3. Symbol System Updated Dec 8, 2025
4. Stages and Calibration Updated Dec 8, 2025
5. Bellman Theory Updated Dec 8, 2025
6. Representation Maps Updated Dec 8, 2025
7. Execution Pipeline Updated Dec 8, 2025
8. SYM/T core Architecture NEW Dec 22, 2025
9. Type System Deferred -

Changes in v0.2.0 (Dec 8, 2025)

Based on AAS_notes.md and update-methodization-functor.md, the following key changes were integrated:

Structural Changes

  1. Three-File Architecture: Model specification is now split into:
  2. stage.yml — purely symbolic, declares operators but NO methods
  3. methodization.yml — binds operators to schemes/methods

  4. calibration.yml — provides concrete parameter/setting values

  5. No @methods in Movers: Perches contain purely symbolic mover definitions. Methods are attached externally via methodization config.

  6. Clarification: kernels (transition functions, utility, auxiliary definitions) are pure Υ-level objects and do not need method attachments merely by existing. Methods attach to operator instances used when executing movers under ρ (expectations, argmax/rootfinding, draws/push-forwards, APPROX/interpolation, etc.).

  7. Operator Declarations: Stages now include an operators: block declaring which operators are used.

Conceptual Changes

  1. Operator Registry (§3.5): Global registry of available schemes/methods in operation-registry.yml.

  2. Settings Profiles: Methodization uses settings_profile labels that calibration resolves to concrete values.

  3. APPROX Operator: Methodization wraps mover outputs in APPROX operators with specified interpolation schemes.

  4. Parameters vs. Settings: Parameters (Υ level) vs. settings profiles (ρ level after methodization).

Example Files

See foundations/primitives/ for complete examples: - operation-registry.yml — global schemes/methods - consind-stage.yml — buffer-stock stage (purely symbolic) - consind-methodization.yml — method choices - consind-calibration.yml — concrete values

Notation Conventions

  • \(\mathbb{X}\) - Mathematical universes and spaces
  • code - DDSL syntax and code examples
  • Term - First use of important terminology
  • \(f : A \to B\) - Function type signatures
  • @decorator - DDSL decorators
  • !scheme - Primitive method constructors
  • \(\Upsilon\) - Mathematical meaning map
  • \(\rho\) - Computational representation map
  • \(\mathcal{M}\) - Methodization functor
  • \(\mathbb{C}\) - Calibration functor