0.1d Methodization

dolo-plus — spec_0.1d (methodization functor + method schemes)¶

1. Goal (methodization only)¶

Define a methodization step that attaches numerical-method metadata to an existing stage without: - embedding numbers in the stage file, - changing the math/function bodies, or - inventing new implicit target labels.

This milestone is intentionally small and Dolo-compatible: legacy Dolo models must continue to run unchanged; dolo-plus method metadata must be droppable for a “horse” down-compile.

2. File split + execution order¶

The methodization-related split is: - stage.yml: pure syntax (symbols + equations; no numbers) - methodization.yml: targets → schemes/methods + settings-symbol wiring - settings.yml: numeric values for settings symbols - calibration.yml: numeric values for economic parameters

Order (Foundations-consistent):

Parse stage → Validate stage → Methodize → Calibrate → Apply settings → ρ/Solve

3. Core contract¶

Methodization is a pure attachment step:

\[ \mathcal{M} : (\mathbb{S}, \text{OperationRegistry}, \text{MethodConfig}) \to \mathbb{S}_{\text{method}} \]

Implementation-facing representation choice: - methodized_stage ≅ (stage, methods) where methods is a dict/list derived from methodization.yml.

4. What can be methodized (targets)¶

Method schemes attach only to existing named labels in the stage, plus operator instances that appear in stage equation bodies.

Concretely, a target id in methodization.yml refers to one of: - a mover label: a key under equations: (including forward movers) - a mover subequation label via dot notation: e.g. cntn_to_dcsn_mover.InvEuler - any other named equation/function label present in the stage YAML - an operator instance id extracted from equation bodies, e.g.: - expectation: E_w corresponds to occurrences of E_{w}(...) in mover bodies - (optional later) other operator heads like maximization/rootfinding/draws

No synthetic targets (e.g., mover:...:approx:...) and no other implicit extra labels are created by methodization.

Forward movers are treated like any other mover label (if present), e.g. arvl_to_dcsn_mover, dcsn_to_cntn_mover.

5. Schemes vs methods vs settings (the only semantics 0.1d needs)¶

scheme: a registered string identifying the kind of numerical task (e.g. expectation, maximization, interpolation, grid, simulation, bellman_backward)
method: an opaque, unregistered label (YAML tag or string), interpreted downstream (e.g. !gauss-hermite, !egm, !cartesian, !linear)
settings: a mapping from method option keys → settings symbol names (strings). Numeric values live in settings.yml.

At v0.1d, registration is applied to schemes only. Methods are never registry-gated.

6. Canonical authoring surface: `methodization.yml`¶

Recommended minimal shape is a flat methods: list.

6.1 Schema¶

methods is a list of entries
each entry has:
on: <string> (target id; must refer to a stage label or extracted operator instance id)
schemes: <list> (may be empty)
each scheme block has:
scheme: <string> (registered)
optional method: <tag-or-string>
optional settings: { <option_key>: <settings_symbol_name>, ... }

6.2 Exhaustive listing rule¶

The methodization table is exhaustive over the target universe for the stage: - every stage label and operator instance id that can be targeted appears exactly once in methods: - if methodization.yml omits some targets, tooling must expand it by adding entries with schemes: []

This yields a fully explicit methodization surface with no hidden defaults.

6.3 Example¶

stage: consind

methods:
  # Operator instance: expectation (numeric integration choice)
  - on: E_w
    schemes:
      - scheme: expectation
        method: !gauss-hermite
        settings:
          n_nodes: n_w_nodes

  # Backward mover (algorithm choice)
  - on: cntn_to_dcsn_mover
    schemes:
      - scheme: bellman_backward
        method: !egm
        settings:
          maxit: egm_maxit
          tol: egm_tol

  # Sub-equation: approximation + interpolation choices for an intermediate function
  - on: cntn_to_dcsn_mover.InvEuler
    schemes:
      - scheme: grid
        method: !cartesian
        settings:
          n: n_w
          grid_min: w_grid_min
          grid_max: w_grid_max
      - scheme: interpolation
        method: !linear

  # Forward movers (explicit targets if present)
  - on: arvl_to_dcsn_mover
    schemes: []

  - on: dcsn_to_cntn_mover
    schemes: []

  # Any other named labels in the stage (explicitly listed even when unspecified)
  - on: utility
    schemes: []

7. Optional: operation registry (schemes only)¶

operation_registry.yml (location TBD; often in dolang/) is optional at v0.1d and serves as: - a catalog of registered scheme names - optional documentation of expected settings keys per scheme

It is a documentation/validation aid, not a gatekeeper.

8. Minimal validation rules (0.1d)¶

stage.yml mover bodies remain purely symbolic (no numeric settings embedded in mover bodies).
methodization.yml:
methods is a list (may be omitted; treated as empty list before expansion)
no duplicate on: targets
each scheme block has scheme: <string> and optional method and optional settings
method may be YAML tag or string (never registry-gated)
(optional) warn on unknown scheme name w.r.t. operation registry
(optional) warn if a referenced settings symbol is not declared in symbols.settings
error (or warn) if on: references an unknown target (not a stage label and not an extracted operator instance id)

9. Acceptance criteria (0.1d)¶

[ ] Separate step: a methodize(stage, methodization, registry=None) boundary exists and is pure (no mutation).
[ ] External authoring: canonical method data come from methodization.yml (not embedded in mover bodies).
[ ] Schemes registered, methods unregistered: registry (if present) validates scheme names only.
[ ] Exhaustive surface: methodization expands to list all stage labels + operator instances with schemes: [] for unspecified targets.
[ ] Targets are only stage labels + operator instances: movers and function/equation labels (including forward movers) plus extracted operator instance ids like E_w; no synthetic implicit target ids.
[ ] Backwards compatible: legacy Dolo unaffected; dolo-plus can be down-compiled by dropping method metadata.