Architecture

This section contains the architectural specifications that define how Cobre’s SDDP solver is structured at the software level. Where the Mathematical Formulations section defines what the solver computes and the Data Model section defines what data flows in and out, the architecture specs define how the solver is organized internally: the training loop that drives SDDP iteration, the simulation engine that evaluates trained policies, the solver abstraction layer that isolates LP solver dependencies, the scenario generation pipeline that produces correlated noise vectors, the input loading sequence that builds the in-memory model, the validation pipeline that rejects malformed inputs before any computation begins, the CLI entrypoint that orchestrates the full execution lifecycle, the convergence monitor that decides when to stop, the cut management implementation that maintains the future cost function, and the extension points that allow algorithm variants to be composed at configuration time.

Together, these 14 specs fully describe the runtime architecture of the Cobre solver. They are written at the behavioral level – specifying component responsibilities, interaction contracts, data flow, and parallelization strategy – without prescribing Rust module boundaries or struct layouts. A developer implementing a component should be able to read its architecture spec alongside the referenced math and data-model specs and produce a correct implementation without ambiguity. Where performance-critical design decisions exist (e.g., thread-trajectory affinity in the forward pass, streaming output in simulation, LP template cloning for solver workspaces, the performance adaptation layer that transforms domain types into solver-ready representations), each spec documents the rationale and the constraints that drove the choice.

The specs assume familiarity with the SDDP algorithm as described in SDDP Algorithm, the stage LP structure from LP Formulation, and the input/output contracts from the Data Model section. Readers new to the solver’s high-level design should start with CLI and Lifecycle, which maps the full execution sequence from process invocation to shutdown, before diving into the individual subsystem specs.

Reading Order

The specs have extensive cross-references, so reading order matters. The following sequence builds concepts from the outermost orchestration layer inward to the solver core:

1. Training Loop – Start here. Defines the SDDP iteration lifecycle (forward pass, backward pass, convergence check), the four abstraction points (risk measure, cut formulation, horizon mode, sampling scheme), state management, and dual extraction for cut coefficients. This is the central spec that most other architecture specs plug into.
2. Simulation Architecture – How trained policies are evaluated on large scenario sets: parallel distribution, per-scenario forward pass, policy compatibility validation, non-convex extensions, statistics computation, and streaming output.
3. Solver Abstraction – The unified interface through which the SDDP algorithm interacts with LP solvers: solver interface contract, LP layout convention, cut pool design, error categories, retry logic, dual normalization, basis storage, and compile-time solver selection.
4. Solver HiGHS Implementation – HiGHS-specific patterns for the C API, batch bound operations, retry strategy, basis management, memory footprint, and SDDP-tuned configuration.
5. Solver CLP Implementation – CLP-specific patterns for the C API baseline, mutable pointer optimization, C++ wrapper strategy for LP template cloning, retry strategy, basis management, and memory footprint.
6. Solver Workspaces – Thread-local solver workspace infrastructure and LP scaling: NUMA-local solver instances, pre-allocated buffers, and the bridge between the solver abstraction and the HPC execution layer.
7. Performance Adaptation Layer – How cobre-core’s domain types are transformed into cobre-sddp’s performance-adapted runtime representations: transformation taxonomy, adapted type inventory, initialization build order, entity data flow mapping, and adaptation contracts.
8. Scenario Generation – The scenario generation pipeline: PAR model preprocessing, correlated noise generation, the sampling scheme abstraction, external scenario integration, load scenario generation, and the memory layout optimized for the forward pass hot-path.
9. Input Loading Pipeline – Rank-0 centric loading pattern, file loading sequence with dependency ordering, sparse time-series expansion, data broadcasting, parallel policy loading for warm-start, and transition to the in-memory data model.
10. Extension Points – How algorithm variants are selected, composed, and validated at configuration time: the four abstraction points mapped to their configuration sources, validation rules, and cross-variant compatibility constraints.
11. CLI and Lifecycle – Program entrypoint, command-line interface, exit codes, execution phase lifecycle, conditional execution modes, configuration resolution hierarchy, and job scheduler integration.
12. Validation Architecture – Multi-layer input validation pipeline: the five validation layers, error collection strategy, error type catalog, and validation report format.
13. Convergence Monitoring – Convergence criteria, stopping rules, bound computation with cross-rank aggregation, and training log format for progress reporting.
14. Cut Management Implementation – How the mathematical cut management concepts are implemented: future cost function runtime structure, cut selection on the pre-allocated cut pool, FlatBuffers serialization for checkpoint/resume, cross-rank cut synchronization via MPI, cut coefficient extraction via fixing constraint duals, and cut activity tracking.

Spec Index

Conventions

All specs in this section describe behavioral contracts rather than implementation artifacts. Component responsibilities are stated as “the component does X” rather than “the struct has field Y”. This keeps the specs stable across refactors while remaining precise enough to verify an implementation against. Where a spec references mathematical quantities (cut coefficients, dual variables, risk weights), it uses the notation from Notation Conventions and links to the relevant math spec for the full derivation. Where a spec references data schemas (Parquet columns, JSON keys, FlatBuffers tables), it links to the relevant data-model spec for the normative definition. Cross-references to the High-Performance Computing section appear where parallelization strategy is architecturally significant (MPI distribution, OpenMP threading, NUMA placement).