Extension Points

Purpose

This spec defines how Cobre selects, composes, and validates algorithm variants at configuration time. The training loop is parameterized by four abstraction points — risk measure, cut formulation, horizon mode, and sampling scheme — each with a defined set of variants. This spec maps each variant to its configuration source, lists validation rules, and documents cross-variant compatibility constraints.

For the behavioral contracts that the training loop imposes on each abstraction point, see Training Loop SS3. For the mathematical definitions of each variant, see the referenced math specs.

1. Variant Architecture Overview

The training loop has a fixed structure (forward pass, backward pass, MPI synchronization, convergence monitoring) parameterized by four configurable abstraction points:

Fixed components (not configurable — same behavior regardless of variant selection):

• Forward pass execution and parallel distribution (Training Loop SS4)
• Backward pass execution and stage synchronization (Training Loop SS6)
• MPI cut synchronization (Cut Management Implementation SS4)
• Convergence monitoring and stopping rules (Convergence Monitoring)
• LP construction and solver interaction (Solver Abstraction)

2. Risk Measure Variants

The risk measure determines how backward pass outcomes (one per opening) are aggregated into a single cut. It can vary per stage (configured in each stage’s risk_measure field in stages.json).

2.1 Variant Table

2.2 Configuration Mapping

The risk_measure field appears per stage in stages.json (see Input Scenarios SS1.7):

{
  "stages": [
    { "id": 0, "risk_measure": { "cvar": { "alpha": 0.95, "lambda": 0.5 } } },
    { "id": 1, "risk_measure": "expectation" }
  ]
}

2.3 Validation Rules

2.4 Behavioral Contract

Each risk measure variant must provide two operations consumed by the training loop:

1. Cut aggregation — Given $N_{\text{openings}}$ backward outcomes with their probabilities, produce a single set of cut coefficients $(\alpha ,\pi )$. For Expectation, the weights are uniform. For CVaR, the weights are computed via the sorting-based greedy allocation from Risk Measures SS7.

2. Risk evaluation — Given a set of cost values and probabilities, produce a scalar risk-adjusted cost. Used for convergence bound computation.

Bound validity warning: When CVaR is active, the first-stage LP objective is a convergence indicator only — it is NOT a valid lower bound. See Risk Measures SS10.

2.5 Deferred Variants

No additional risk measure variants are currently planned. The Expectation + CVaR convex combination covers the standard risk-averse SDDP formulation. Entropic risk measures would require a different dual representation and are not in scope.

3. Cut Formulation Variants

The cut formulation determines the structure of cuts added to the FCF at each backward pass stage.

3.1 Variant Table

3.2 Configuration

No configuration required — single-cut is the only available formulation. When multi-cut is implemented, it will be selectable via config.json → training.cut_formulation.

4. Horizon Mode Variants

The horizon mode determines stage traversal, terminal conditions, and discount factors. It is derived from the policy_graph field in stages.json.

4.1 Variant Table

4.2 Configuration Mapping

The horizon mode is implicitly selected by the policy_graph structure in stages.json (see Input Scenarios SS1.2):

Finite horizon:

{
  "policy_graph": {
    "type": "finite_horizon",
    "annual_discount_rate": 0.06,
    "transitions": [
      { "source_id": 0, "target_id": 1, "probability": 1.0 },
      { "source_id": 1, "target_id": 2, "probability": 1.0 }
    ]
  }
}

Cyclic (infinite periodic) horizon:

{
  "policy_graph": {
    "type": "cyclic",
    "annual_discount_rate": 0.06,
    "transitions": [
      { "source_id": 0, "target_id": 1, "probability": 1.0 },
      { "source_id": 59, "target_id": 48, "probability": 1.0 }
    ]
  }
}

4.3 Validation Rules

4.4 Behavioral Contract

Each horizon mode variant must provide:

1. Successor computation — Given a stage, return successor stages with transition probabilities
2. Terminal detection — Whether a stage has no successors (finite only; cyclic stages are never terminal)
3. Discount factor — The discount factor $d_{t\to t+1}$ for each transition. For finite horizon, this comes from the per-transition or global annual_discount_rate (may be 1.0 if undiscounted). For cyclic, the back-edge transition always applies the discount factor.
4. Validation — Verify stage configuration is valid for the selected mode

Forward pass termination in cyclic mode: The forward pass simulates multiple cycles until the cumulative discount drops below a tolerance threshold or a max_horizon_length safety bound is reached. See Infinite Horizon SS6.

5. Sampling Scheme Variants

The sampling scheme determines how the forward pass selects scenario realizations at each stage. This is the fourth abstraction point defined in Training Loop SS3.4.

5.1 Variant Table

5.2 Configuration Mapping

The scenario_source field in config.json (see Configuration Reference):

{ "scenario_source": { "sampling_scheme": "in_sample", "seed": 42 } }

{
  "scenario_source": {
    "sampling_scheme": "external",
    "selection_mode": "random"
  }
}

{ "scenario_source": { "sampling_scheme": "historical" } }

5.3 Validation Rules

5.4 Key Invariant

The backward pass always uses the fixed opening tree, regardless of the forward sampling scheme. The separation of forward and backward noise sources is fundamental to SDDP correctness — see Scenario Generation SS3.1.

6. Variant Selection Pipeline

At startup, the variant selection pipeline resolves configuration into concrete algorithm behavior. This happens during the initialization phase described in CLI and Lifecycle:

The risk measure is per-stage (step 3 produces a mapping from stage ID to risk measure variant). All other abstraction points are global (one selection for the entire run).

7. Dispatch Mechanism

Open design point: The dispatch mechanism — how variant-specific behavior is invoked at runtime — is an implementation decision deferred to coding time.

The per-stage risk measure requirement (SS2.2) rules out pure compile-time monomorphization for the risk measure dimension. Enum dispatch is the natural fit for a small, fixed set of variants.

Note: The solver abstraction uses compile-time cfg-feature selection for the LP solver backend (CLP vs HiGHS) — see Solver Abstraction SS10. The algorithm variant dispatch mechanism is a separate decision and need not use the same approach.

8. Variant Composition Validation

Some variant combinations have specific interactions that require validation or special handling.

8.1 Cross-Variant Rules

8.2 Default Configuration

When fields are omitted, the following defaults apply:

Cross-References

• Training Loop SS3 — Behavioral contracts for the four abstraction points that this spec maps variants to
• Training Loop SS2 — Training orchestrator components and iteration lifecycle
• Risk Measures — Mathematical definitions: CVaR (SS2), convex combination (SS3), cut weight computation (SS7), lower bound invalidity (SS10)
• SDDP Algorithm SS4 — Policy graph topologies (finite SS4.1, cyclic SS4.2)
• SDDP Algorithm SS6 — Single-cut (SS6.1) and multi-cut (SS6.2) formulations
• Infinite Horizon — Cyclic policy graph: periodic structure, cut sharing, forward/backward pass behavior, convergence
• Discount Rate — Discount factor mechanics for horizon modes
• Scenario Generation SS3 — Sampling scheme abstraction, forward/backward noise source separation
• Input Scenarios SS1.2 — policy_graph schema for horizon mode configuration
• Input Scenarios SS1.7 — risk_measure field schema for per-stage risk configuration
• Input Scenarios SS2.1 — scenario_source schema for sampling scheme configuration
• Configuration Reference SS5, SS6.2-SS6.3 — Horizon mode, risk measure, and scenario source config tables
• Solver Abstraction SS10 — Compile-time solver selection (contrasted with algorithm variant dispatch)
• Deferred Features — Multi-cut (C.3), Monte Carlo backward sampling (C.14)