Cobre

Cobre solves long-term hydrothermal dispatch – the problem of scheduling water and fuel across power grids with large hydroelectric capacity. It provides an open-source, reproducible implementation built on Rust, Parquet for data interchange, and Python for analysis workflows.

Navigation

Coming from other energy optimization software? If you already work with hydrothermal dispatch tools and want to convert existing case data, see the cobre-bridge conversion guide.

New to SDDP? If you want to understand the algorithm before diving into code, read What Cobre Solves.

Python user? If you want to run studies from Jupyter or a Python script, see the Python Quickstart.

Starting from scratch? See Installation and then Quickstart.

What Cobre Does

• Solve long-term hydrothermal dispatch via Stochastic Dual Dynamic Programming (SDDP), with training, simulation, and policy export.
• Model complex power systems – hydro cascades with variable-head production, thermal units, transmission networks, non-controllable sources, and user-defined generic constraints.
• Generate stochastic scenarios using periodic autoregressive (PAR) inflow models with correlated multi-site noise.
• Run across clusters with hybrid MPI + thread parallelism, producing bit-for-bit identical results regardless of rank or thread count.
• Analyze results from Python using Arrow zero-copy bindings, or directly from Parquet output files.

Quick Links

What Cobre Solves

The Problem

Power systems with large hydroelectric capacity face a fundamental dilemma: water stored in reservoirs today could generate cheap electricity now, but saving it might avoid burning expensive fuel months from now. The decision is complicated by uncertainty – nobody knows how much rain will fall next month.

This is the hydrothermal dispatch problem: given a network of hydro plants, thermal generators, transmission lines, and uncertain future inflows, find the least-cost operating policy over a multi-year horizon. It is one of the central problems in energy planning for countries like Brazil, Colombia, and Norway.

The problem is hard because decisions are coupled across time (water used today is gone tomorrow), across space (reservoirs in a cascade share the same river), and across scenarios (a drought year requires completely different decisions than a wet year).

How SDDP Works (Conceptual)

Stochastic Dual Dynamic Programming (SDDP) solves this problem by iterating between two phases:

1. Forward pass – Simulate the system from the first stage to the last, making decisions at each stage under sampled uncertainty (random inflows). Record the resulting costs and state transitions.

2. Backward pass – Starting from the last stage and working backwards, use the forward decisions to build “cuts” – linear approximations of the future cost. These cuts capture the trade-off: “if you use this much water now, the expected future cost is at least this much.”

Each iteration improves the policy. After enough iterations, the lower bound (from cuts) and the upper bound (from forward simulations) converge, producing a near-optimal dispatch policy.

What Cobre Provides

• System modeling – Define hydro plants (with cascades, variable-head production, evaporation), thermal units, transmission lines, non-controllable sources, and user-defined constraints.
• Stochastic scenario generation – Fit periodic autoregressive (PAR) models to historical inflow records and generate correlated scenarios.
• SDDP solver – Train a dispatch policy with configurable stopping rules, risk measures, and cut selection strategies.
• Simulation – Evaluate the trained policy across thousands of scenarios, producing per-scenario cost breakdowns and operational trajectories.
• Multiple interfaces – Use the CLI for batch runs, Python for interactive analysis, or the MCP server for AI agent workflows.

Installation

Cobre is a statically linked binary available for the platforms listed below. Choose the method that best fits your environment.

Pre-built Binaries (Recommended)

No Rust toolchain or C compiler required.

Linux and macOS

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/cobre-rs/cobre/releases/latest/download/cobre-cli-installer.sh | sh

The installer places the cobre binary in $CARGO_HOME/bin (typically ~/.cargo/bin). Add that directory to your PATH if it is not already present.

Windows (PowerShell)

powershell -ExecutionPolicy Bypass -c "irm https://github.com/cobre-rs/cobre/releases/latest/download/cobre-cli-installer.ps1 | iex"

Supported Platforms

You can also download individual archives directly from the GitHub Releases page.

Verify the Installation

cobre version

Expected output (exact versions and arch will vary):

cobre   v0.9.1
solver: HiGHS
comm:   local
zstd:   enabled
arch:   x86_64-linux
build:  release (lto=thin)

From crates.io

cargo install cobre-cli

Requires Rust 1.88+ and build prerequisites (see Build from Source below). Installs to $CARGO_HOME/bin.

Build from Source

For contributors or unsupported platforms.

Prerequisites

Steps

# Clone the repository
git clone https://github.com/cobre-rs/cobre.git
cd cobre

# Initialize HiGHS submodule (required for the solver backend)
git submodule update --init --recursive

# Build the release binary
cargo build --release -p cobre-cli

The binary is written to target/release/cobre. Optionally install to $CARGO_HOME/bin:

cargo install --path crates/cobre-cli

Verify:

./target/release/cobre version
cargo test --workspace

Choosing the LP Backend

Cobre supports two LP solver backends, selected at build time via Cargo features. Exactly one backend is compiled into any given binary.

Default build (HiGHS)

cargo build --release -p cobre-cli

No flags are needed. HiGHS is the default backend and the one shipped in pre-built binaries.

CLP build

# Initialize the CLP and CoinUtils submodules first
git submodule update --init --recursive

# Build with CLP, disabling the HiGHS default
cargo build --release -p cobre-cli --no-default-features --features clp

Mutual exclusivity

The highs and clp features are mutually exclusive — exactly one LP backend is compiled into a binary, and enabling both at once is a compile error. Because highs is the default feature, selecting CLP requires --no-default-features to suppress the default before --features clp is applied; a plain --features clp leaves the highs default on and fails the build. Enabling neither backend is also a compile error, so a backend is always chosen explicitly. The default build (no extra flags) uses HiGHS.

Identifying the active backend

The cobre version banner shows which backend is compiled in:

cobre   v0.9.1
solver: CLP 1.17.11
comm:   local
...

The solver and solver_version fields in each run’s output metadata record the active backend identifier ("highs" or "clp") and its library version string. These fields are written by both the CLI and the Python bindings.

Determinism

Each backend is internally deterministic: the same input, solved twice, produces bit-for-bit identical results; permuting the input entities produces the correspondingly permuted output. Switching from one backend to the other may legitimately change numerical results — the two simplex implementations can reach different optimal vertices on degenerate problems, all of which are valid. No cross-backend numerical equality is guaranteed; each backend maintains its own parity baselines.

Migration note

Existing builds are unaffected. The default backend is HiGHS, unchanged from prior releases. The CLP backend is strictly opt-in: users who do not pass --no-default-features --features clp continue to build and run against HiGHS exactly as before.

Known limitation

Re-loading a fresh model into a CLP solver instance after a hot-start snapshot has been taken is unsupported and guarded against at runtime. This situation does not arise on the production solve paths; it is relevant only to callers that construct solver instances directly and interleave load_model calls with hot-start operations.

Next Steps

• Quickstart — run a complete study end to end using the built-in 1dtoy template
• Running Studies — validate, run, and inspect results for any case directory
• CLI Reference — complete flag and subcommand reference

Quickstart

This page takes you from zero to a completed SDDP study in three commands using the built-in 1dtoy template. The template models a single-bus hydrothermal system with one hydro plant and two thermal units over a 4-stage finite planning horizon — small enough to run in seconds, complete enough to demonstrate every stage of the workflow.

If you have not installed Cobre yet, start with Installation.

Step 1: Scaffold a Case Directory

cobre init --template 1dtoy my_first_study

Cobre writes 11 input files into a new my_first_study/ directory and prints a summary to stderr:

 ━━━━━━━━━━━●
 ━━━━━━━━━━━●⚡  COBRE v0.9.1
 ━━━━━━━━━━━●   Power systems in Rust

Created my_first_study case directory from template '1dtoy':

  ✔ config.json                    Algorithm configuration: training (forward passes, stopping rules) and simulation settings
  ✔ initial_conditions.json        Initial reservoir storage volumes for each hydro plant at the start of the planning horizon
  ✔ penalties.json                 Global penalty costs for constraint violations (deficit, excess, spillage, storage bounds, etc.)
  ✔ stages.json                    Planning horizon definition: policy graph type, discount rate, stage dates, time blocks, and scenario counts
  ✔ system/buses.json              Electrical bus definitions with deficit cost segments
  ✔ system/hydros.json             Hydro plant definitions: reservoir bounds, outflow limits, turbine model, and generation limits
  ✔ system/hydro_production_models.json  Per-(hydro, stage) production-model configuration carrying the productivity coefficient
  ✔ system/lines.json              Transmission line definitions (empty in this single-bus example)
  ✔ system/thermals.json           Thermal plant definitions with piecewise cost segments and generation bounds
  ✔ scenarios/inflow_seasonal_stats.parquet  Seasonal PAR(p) statistics for hydro inflow scenario generation (mean, std, lag correlations)
  ✔ scenarios/load_seasonal_stats.parquet    Seasonal PAR(p) statistics for electrical load scenario generation (mean, std, lag correlations)

Next steps:
  -> cobre validate my_first_study
  -> cobre run my_first_study --output my_first_study/results

The directory structure is:

my_first_study/
  config.json
  initial_conditions.json
  penalties.json
  stages.json
  system/
    buses.json
    hydros.json
    hydro_production_models.json
    lines.json
    thermals.json
  scenarios/
    inflow_seasonal_stats.parquet
    load_seasonal_stats.parquet

Step 2: Validate the Case

cobre validate my_first_study

The validation pipeline checks all layers — schema, references, physical feasibility, stochastic consistency, and solver feasibility — and prints entity counts on success:

Valid case: 1 buses, 1 hydros, 2 thermals, 0 lines
  buses: 1
  hydros: 1
  thermals: 2
  lines: 0

If any layer fails, Cobre prints each error prefixed with error: and exits with code 1. The 1dtoy template always passes validation.

Step 3: Run the Study

cobre run my_first_study --output my_first_study/results

Cobre runs the SDDP training loop (128 iterations, 1 forward pass each) followed by a simulation pass (100 scenarios). Output is written to my_first_study/results/. The banner, a progress bar, and a post-run summary are printed to stderr:

Training complete in 0.5s (128 iterations, iteration_limit)
  Lower bound:  1.55955e7 $/stage
  Upper bound:  5.79592e5 +/- 0.00000e0 $/stage
  Gap:          -2590.8% (started at 70.5%)
  Policy rows:  384 active / 384 generated
  LP solves:    5632 (5632 first-try, 0 retried, 0 failed)

Simulation complete in 0.6s (100 scenarios)
  Completed: 100  Failed: 0

Output written to my_first_study/results/

Why is the gap a large negative number? The 1dtoy config uses forward_passes: 1, which means each training iteration draws a single scenario trajectory for the upper-bound estimate. A single scenario is an extremely noisy sample of the true expected cost — one unlucky trajectory can land far below the lower bound, driving the gap deeply negative. This is expected behavior, not a solver error. The gap only becomes well-behaved and stable when training runs with multiple forward passes, because averaging over more scenarios produces a reliable upper-bound estimate. The 1dtoy template keeps forward_passes: 1 for speed; in a production study you would increase this value and add a convergence-based stopping rule so training halts when the gap truly stabilizes.

Exact numerical values (bounds, gap, policy row counts, timing) will vary across runs because scenario sampling is stochastic. The gap and iteration count depend on the random seed and the convergence tolerance configured in config.json.

The results directory contains training convergence data, a FlatBuffers policy checkpoint, and Hive-partitioned Parquet files for simulation dispatch results:

my_first_study/results/
  training/
    metadata.json
    convergence.parquet
    dictionaries/
    timing/
  policy/
    cuts/
      stage_000.bin  ...  stage_003.bin
    basis/
      stage_000.bin  ...  stage_003.bin
    metadata.json
  simulation/
    metadata.json
    costs/
    hydros/
    thermals/
    buses/

What’s Next

You have completed a full SDDP study from case setup to results. The following pages go deeper into how the case is structured and how to interpret the output:

• Anatomy of a Case — what each input file controls
• Understanding Results — how to read Parquet output and convergence metrics
• CLI Reference — all flags, subcommands, and exit codes
• Configuration — every config.json field documented

Python Quickstart

Install Cobre and run a study in a few steps.

Installation

pip install cobre-python

Requires Python 3.12, 3.13, or 3.14.

Run a Case

import cobre

result = cobre.run.run("path/to/case")

The cobre.run.run() function loads the case, trains an SDDP policy, optionally runs simulation, and writes output files. It returns a dictionary with the following keys:

print(f"Converged: {result['converged']}")
print(f"Iterations: {result['iterations']}")
print(f"Lower bound: {result['lower_bound']:.2f}")
if result['gap_percent'] is not None:
    print(f"Gap: {result['gap_percent']:.2f}%")
print(f"Output dir: {result['output_dir']}")

Optional Parameters

result = cobre.run.run(
    "path/to/case",
    output_dir="path/to/output",   # default: case_dir/output
    threads=4,                      # default: 1
    skip_simulation=True,           # default: False
)

Read Output with Polars

Cobre writes results as Parquet files, which can be loaded directly with Polars or any Arrow-compatible library:

import polars as pl

# Convergence trajectory
convergence = pl.read_parquet("output/training/convergence.parquet")
print(convergence.head())

# Simulation costs (if simulation was enabled) — Hive-partitioned
costs = pl.read_parquet("output/simulation/costs/")
print(costs.describe())

Arrow Zero-Copy Loading

For larger datasets, use the built-in Arrow loaders that avoid serialization overhead:

# Returns a pyarrow.Table (zero-copy)
convergence_table = cobre.results.load_convergence_arrow("output/")
simulation_tables = cobre.results.load_simulation_arrow("output/")

# Convert to Polars without copying
import polars as pl
df = pl.from_arrow(convergence_table)

Next Steps

• See the case directory format for input file specifications.
• Explore the examples for ready-to-run cases.
• Read the Jupyter quickstart notebook for a complete end-to-end workflow with visualization.

Anatomy of a Case

A Cobre case directory is a self-contained folder of input files. When you run cobre run or cobre validate, the first thing Cobre does is call load_case on that directory. load_case reads every file, runs the layered validation pipeline (schema, references, physical feasibility, stochastic consistency, solver feasibility), and produces a fully-validated System object ready for the solver.

This page walks through every file in the 1dtoy example, explaining what each field controls and why it matters. The example lives in examples/1dtoy/ in the repository and is also available via cobre init --template 1dtoy.

For the complete field-by-field schema reference, see Case Format Reference.

Directory Structure

The 1dtoy case contains the input files listed below, across three directories:

1dtoy/
  config.json
  initial_conditions.json
  penalties.json
  stages.json
  system/
    buses.json
    hydros.json
    hydro_production_models.json
    lines.json
    thermals.json
  scenarios/
    inflow_seasonal_stats.parquet
    load_seasonal_stats.parquet

The four root-level files configure the solver and define the time horizon. The system/ subdirectory holds the power system entities. The scenarios/ subdirectory holds the stochastic input data that drives scenario generation.

Root-Level Files

config.json

config.json controls all solver parameters: how many training iterations to run, when to stop, whether to follow training with a simulation pass, and more.

{
  "training": {
    "forward_passes": 1,
    "stopping_rules": [
      {
        "type": "iteration_limit",
        "limit": 128
      }
    ]
  },
  "simulation": {
    "enabled": true,
    "num_scenarios": 100
  }
}

The training section is mandatory. forward_passes: 1 means each training iteration draws one scenario trajectory. The stopping_rules array must contain at least one iteration_limit rule. Here the solver stops after 128 iterations. For production studies you would typically also add a convergence-based stopping rule such as bound_stalling, but for a small tutorial case an iteration limit is sufficient.

The simulation section is optional and defaults to disabled. Here it is enabled with 100 scenarios. After training completes, Cobre evaluates the trained policy over 100 independently sampled scenarios and writes the results to the output directory.

For the full list of configuration options, see Configuration.

penalties.json

penalties.json defines the global penalty cost defaults. These costs are added to the LP objective whenever a physical constraint is violated in a soft-constraint sense — for example, when demand cannot be fully served (deficit) or when a reservoir bound is violated. Setting these costs high relative to actual generation costs ensures that violations are used as a last resort rather than a cheap dispatch option.

{
  "bus": {
    "deficit_segments": [
      {
        "depth_mw": 500.0,
        "cost": 7000.0
      },
      {
        "depth_mw": null,
        "cost": 7500.0
      }
    ],
    "excess_cost": 100.0
  },
  "line": {
    "exchange_cost": 2.0
  },
  "hydro": {
    "spillage_cost": 0.01,
    "turbined_cost": 0.05,
    "diversion_cost": 0.1,
    "storage_violation_below_cost": 10000.0,
    "filling_target_violation_cost": 6000.0,
    "turbined_violation_below_cost": 500.0,
    "outflow_violation_below_cost": 500.0,
    "outflow_violation_above_cost": 500.0,
    "generation_violation_below_cost": 1000.0,
    "evaporation_violation_cost": 5000.0,
    "water_withdrawal_violation_cost": 1000.0
  },
  "non_controllable_source": {
    "curtailment_cost": 0.005
  }
}

The bus.deficit_segments array defines a piecewise-linear deficit cost curve. The first segment covers the first 500 MW of unserved energy at 7000 $/MWh. Beyond 500 MW, the cost rises to 7500 $/MWh (the segment with depth_mw: null is always the final unbounded tier). The two-tier structure mimics a typical Value of Lost Load model where the first tranche represents interruptible load and the second represents non-interruptible load. excess_cost penalizes over-injection at 100 $/MWh.

Hydro penalty costs cover a range of operational constraint violations. The low spillage_cost (0.01 $/hm3) makes spillage the cheapest way to release water when turbine capacity is exhausted. The high storage_violation_below_cost (10,000 $/hm3) makes dropping below the minimum reservoir storage the costliest hydro violation — priced above even the deficit cost — so the solver avoids it except in genuine water shortage. filling_target_violation_cost (6,000 $/hm3) is deliberately set below the deficit cost, so missing a reservoir filling target is discouraged but never takes priority over serving load.

Individual entities can override these global defaults in their own JSON files using a penalties block. The reference page documents all override options.

stages.json

stages.json defines the temporal structure of the study: the sequence of planning stages, the load blocks within each stage, the number of scenarios to sample at each stage during training, and the policy graph horizon type.

{
  "policy_graph": {
    "type": "finite_horizon",
    "annual_discount_rate": 0.12
  },
  "stages": [
    {
      "id": 0,
      "start_date": "2024-01-01",
      "end_date": "2024-02-01",
      "blocks": [
        {
          "id": 0,
          "name": "SINGLE",
          "hours": 744
        }
      ],
      "num_scenarios": 10
    },
    {
      "id": 1,
      "start_date": "2024-02-01",
      "end_date": "2024-03-01",
      "blocks": [
        {
          "id": 0,
          "name": "SINGLE",
          "hours": 696
        }
      ],
      "num_scenarios": 10
    },
    {
      "id": 2,
      "start_date": "2024-03-01",
      "end_date": "2024-04-01",
      "blocks": [
        {
          "id": 0,
          "name": "SINGLE",
          "hours": 744
        }
      ],
      "num_scenarios": 10
    },
    {
      "id": 3,
      "start_date": "2024-04-01",
      "end_date": "2024-05-01",
      "blocks": [
        {
          "id": 0,
          "name": "SINGLE",
          "hours": 720
        }
      ],
      "num_scenarios": 10
    }
  ]
}

policy_graph.type: "finite_horizon" means the planning horizon is a linear sequence of stages with no cyclic structure and zero terminal value after the last stage. The annual_discount_rate: 0.12 applies a 12% annual discount to future stage costs.

The stages array defines four monthly stages covering January through April 2024. Each stage has a single load block named SINGLE that spans the entire month. The hours values match the actual number of hours in each calendar month (744 for January, 696 for February in 2024, and so on). These hours are used when converting power (MW) to energy (MWh) in the LP objective.

num_scenarios: 10 means 10 scenario trajectories are sampled at each stage during training forward passes. A small number like 10 keeps the tutorial fast; real studies use more trajectories for a more representative scenario tree.

Each stage can optionally include a risk_measure field. When omitted (as in the 1dtoy example), it defaults to "expectation" (risk-neutral expected value). To use CVaR (Conditional Value at Risk), specify an object:

"risk_measure": { "cvar": { "alpha": 0.50, "lambda": 0.25 } }

alpha is the CVaR confidence level (0, 1] and lambda is the weight on the CVaR component in the convex combination (1 - lambda) * E[Z] + lambda * CVaR_alpha[Z]. Setting lambda: 0 or alpha: 1 reduces to expectation.

initial_conditions.json

initial_conditions.json provides the reservoir storage levels at the beginning of the study. Every hydro plant that participates in the study must have an entry here.

{
  "storage": [
    {
      "hydro_id": 0,
      "value_hm3": 83.222
    }
  ],
  "filling_storage": []
}

storage covers operating reservoirs: plants that both generate power and store water between stages. hydro_id: 0 corresponds to UHE1 defined in system/hydros.json. The initial storage is 83.222 hm³, which is about 8.3% of the 1000 hm³ maximum capacity — a low-storage starting condition that forces the solver to balance generation against the risk of running dry.

filling_storage covers filling reservoirs — reservoirs that do not generate power but feed downstream plants. The 1dtoy case has no filling reservoirs, so this array is empty. It must still be present (even if empty) to satisfy the schema.

system/ Files

system/buses.json

Buses are the nodes of the electrical network. Every generator and load is connected to a bus. The bus balance constraint ensures that injections equal withdrawals at every bus in every LP solve.

{
  "buses": [
    {
      "id": 0,
      "name": "SIN",
      "deficit_segments": [
        {
          "depth_mw": null,
          "cost": 7500.0
        }
      ]
    }
  ]
}

The 1dtoy case has a single bus named SIN (Sistema Interligado Nacional, the Brazilian interconnected system). A single-bus model treats the entire system as one copper-plate node: there are no transmission constraints.

The bus-level deficit_segments here overrides the global default from penalties.json with a simpler single-tier structure: unlimited deficit at 7500 $/MWh. When an entity-level override is present, it takes precedence over the global default.

system/lines.json

Transmission lines connect pairs of buses and carry power flows subject to capacity limits. In a single-bus model, no lines are needed.

{
  "lines": []
}

The file must be present even if the lines array is empty. The validator checks for the file and would raise a schema error if it were absent.

system/hydros.json

Hydro plants have a reservoir (water storage), a turbine (converts water flow to electricity), and optional cascade linkage to downstream plants.

{
  "hydros": [
    {
      "id": 0,
      "name": "UHE1",
      "bus_id": 0,
      "downstream_id": null,
      "reservoir": {
        "min_storage_hm3": 0.0,
        "max_storage_hm3": 1000.0
      },
      "outflow": {
        "min_outflow_m3s": 0.0,
        "max_outflow_m3s": 50.0
      },
      "generation": {
        "model": "constant_productivity",
        "min_turbined_m3s": 0.0,
        "max_turbined_m3s": 50.0,
        "min_generation_mw": 0.0,
        "max_generation_mw": 50.0
      }
    }
  ]
}

UHE1 connects to bus 0 (SIN). downstream_id: null means it is a tailwater plant — there is no plant downstream that receives its outflow.

The reservoir block defines storage bounds in hm³ (cubic hectometres). UHE1 can hold between 0 and 1000 hm³. The minimum of 0 means the reservoir can be fully emptied, which is common for run-of-river-adjacent plants.

The outflow block limits total outflow (turbined + spilled) to 50 m³/s maximum. This is a physical constraint representing the river channel capacity below the dam.

The generation block uses "constant_productivity", the simplest turbine model: generation (MW) equals turbined flow (m³/s) times the productivity coefficient from system/hydro_production_models.json. The turbine can pass between 0 and 50 m³/s, and the resulting generation is bounded between 0 and 50 MW.

system/hydro_production_models.json

hydro_production_models.json defines how each hydro plant converts turbined flow into electrical power. It is an optional system input — when absent, each plant falls back to the model field in its generation block in hydros.json. When present, it overrides that model on a per-plant, per-stage-range basis, enabling different productivity models across seasons or study periods.

The 1dtoy case uses a constant-productivity model for UHE1 across all stages:

{
  "$schema": "https://raw.githubusercontent.com/cobre-rs/cobre/refs/heads/main/book/src/schemas/production_models.schema.json",
  "production_models": [
    {
      "hydro_id": 0,
      "selection_mode": "stage_ranges",
      "stage_ranges": [
        {
          "start_stage_id": 0,
          "end_stage_id": null,
          "model": "constant_productivity",
          "productivity_mw_per_m3s": 1.0
        }
      ]
    }
  ]
}

The production_models array holds one entry per hydro plant that requires an override. selection_mode: "stage_ranges" means the model is selected by stage range: each stage_ranges entry applies from start_stage_id to end_stage_id (inclusive; null means the last stage). Here a single range covers all four stages with constant_productivity at 1.0 MW/(m³/s), meaning every cubic metre per second of turbined flow yields exactly 1 MW of generation.

For the complete field reference, see Case Format Reference.

system/thermals.json

Thermal plants are dispatchable generators with a fixed cost per MWh. The piecewise cost structure allows modeling fuel cost curves by defining multiple capacity segments at increasing costs.

{
  "thermals": [
    {
      "id": 0,
      "name": "UTE1",
      "bus_id": 0,
      "cost_segments": [
        {
          "capacity_mw": 15.0,
          "cost_per_mwh": 5.0
        }
      ],
      "generation": {
        "min_mw": 0.0,
        "max_mw": 15.0
      }
    },
    {
      "id": 1,
      "name": "UTE2",
      "bus_id": 0,
      "cost_segments": [
        {
          "capacity_mw": 15.0,
          "cost_per_mwh": 10.0
        }
      ],
      "generation": {
        "min_mw": 0.0,
        "max_mw": 15.0
      }
    }
  ]
}

Both thermal plants connect to bus 0. UTE1 is the cheaper unit at 5 $/MWh and UTE2 costs 10 $/MWh. Both are limited to 15 MW maximum dispatch. In the LP, Cobre will always prefer UTE1 over UTE2 and prefer both over deficit (7500 $/MWh), creating a natural merit-order dispatch.

Each thermal has a single cost segment covering its entire capacity. For plants with variable heat rates you would add additional segments — for example, { "capacity_mw": 10.0, "cost_per_mwh": 8.0 } followed by { "capacity_mw": 5.0, "cost_per_mwh": 12.0 } to model a plant that becomes progressively more expensive at higher output.

scenarios/ Files

The scenarios/ directory holds Parquet files that parameterize the stochastic models used to generate inflow and load scenarios during training and simulation. Unlike the JSON files, these are binary columnar files that cannot be inspected with a text editor.

scenarios/inflow_seasonal_stats.parquet

This file contains the seasonal mean and standard deviation of historical inflows for each (hydro plant, stage) pair, plus the autoregressive order for the PAR(p) model. Cobre uses these statistics to fit a periodic autoregressive model that generates correlated inflow scenarios across stages.

Expected columns:

The 1dtoy file has 4 rows, one for each stage, for the single hydro plant UHE1 (hydro_id = 0). When an inflow_ar_coefficients.parquet file is also present, Cobre uses the lag coefficients to build a PAR(p) model. The 1dtoy case has no AR coefficients file, so all inflows use white noise (order 0).

To inspect a Parquet file on your machine, use any of:

import polars as pl
df = pl.read_parquet("scenarios/inflow_seasonal_stats.parquet")
print(df)

import pandas as pd
df = pd.read_parquet("scenarios/inflow_seasonal_stats.parquet")
print(df)

-- DuckDB
SELECT * FROM read_parquet('scenarios/inflow_seasonal_stats.parquet');

scenarios/load_seasonal_stats.parquet

This file contains the seasonal statistics for electrical load at each bus. It drives the stochastic load model that generates demand scenarios during training and simulation.

Expected columns:

The 1dtoy file has 4 rows, one for each stage, for the single bus SIN (bus_id = 0). The load mean and standard deviation determine how much demand the system must serve in each scenario and how uncertain that demand is.

Additional Files in Production Cases

The 1dtoy example contains the files shown above. Larger cases may include additional files that are not needed for this minimal example:

my_real_case/
  config.json
  initial_conditions.json
  penalties.json
  stages.json
  system/
    buses.json
    hydros.json
    lines.json
    thermals.json
    hydro_production_models.json       Per-plant production model overrides (optional)
    non_controllable_sources.json      NCS plant definitions (wind, solar)
  scenarios/
    inflow_seasonal_stats.parquet      Inflow PAR(p) statistics
    inflow_ar_coefficients.parquet     Pre-computed AR coefficients (optional)
    inflow_history.parquet             Historical inflow records for auto-estimation
    load_seasonal_stats.parquet        Load PAR(p) statistics
    non_controllable_stats.parquet     NCS stochastic availability factors
    non_controllable_factors.json      NCS per-block availability factors
    load_factors.json                  Per-bus, per-block load demand factors
    hydro_geometry.parquet             Forebay/tailrace curves for FPHA model
  constraints/
    generic_constraints.json           User-defined generic LP constraints
    generic_constraint_bounds.parquet  Per-stage bounds for generic constraints
    hydro_bounds.parquet               Per-stage hydro operational bounds
    thermal_bounds.parquet             Per-stage thermal generation bounds
    line_bounds.parquet                Per-stage transmission capacity bounds
    exchange_factors.json              Per-block exchange capacity factors

Not all of these files are required. Cobre loads them if present and skips them if absent (except for the core files, which are always mandatory; listed above).

What’s Next

Now that you understand what each file does, the next page walks you through creating a case from scratch:

• Building a System — step-by-step guide to creating every file
• Case Format Reference — complete field-by-field schema
• Configuration — all config.json fields documented

Building a System

This page walks you through creating a minimal case directory from scratch, explaining why each file exists and what each field controls. The target is a single-bus hydrothermal system identical to the 1dtoy template: one bus, one hydro plant, two thermal units, and a four-month planning horizon.

If you want to start from a working template instead, use:

cobre init --template 1dtoy my_study

This page is for users who want to understand the structure of every file before touching real data.

Prerequisites

Create an empty directory and enter it:

mkdir my_study
cd my_study
mkdir system

You will need the JSON files listed below. By the end of this guide your directory will look like:

my_study/
  config.json
  initial_conditions.json
  penalties.json
  stages.json
  system/
    buses.json
    hydros.json
    lines.json
    thermals.json

The scenarios/ subdirectory is optional for a minimal case. Cobre can generate white-noise inflow and load scenarios using only the stage definitions, without Parquet statistics files.

Step 1: Create config.json

config.json tells Cobre how to run the study. At minimum it needs a training section with a forward_passes count and at least one stopping_rules entry.

Create my_study/config.json:

{
  "training": {
    "forward_passes": 1,
    "stopping_rules": [
      {
        "type": "iteration_limit",
        "limit": 128
      }
    ]
  },
  "simulation": {
    "enabled": true,
    "num_scenarios": 100
  }
}

forward_passes controls how many scenario trajectories are drawn per training iteration. Start with 1 for fast iteration during case development; raise it for production runs, where more trajectories lower the per-iteration variance.

stopping_rules must contain at least one iteration_limit entry. The solver will run until one of the configured rules triggers. Here it stops after 128 iterations regardless of convergence. You can add a second rule — for example, { "type": "time_limit", "seconds": 300 } — and the solver will stop when either condition is met.

The simulation block is optional. When enabled: true, Cobre runs a post-training simulation pass using num_scenarios independently sampled scenarios and writes dispatch results to Parquet files.

For the full list of configuration options including warm-start, cut selection, and output controls, see Configuration.

Step 2: Create stages.json

stages.json defines the time horizon. Each stage represents a planning period. The solver builds one LP sub-problem per stage per scenario trajectory.

Create my_study/stages.json:

{
  "policy_graph": {
    "type": "finite_horizon",
    "annual_discount_rate": 0.12
  },
  "stages": [
    {
      "id": 0,
      "start_date": "2024-01-01",
      "end_date": "2024-02-01",
      "blocks": [
        {
          "id": 0,
          "name": "SINGLE",
          "hours": 744
        }
      ],
      "num_scenarios": 10
    },
    {
      "id": 1,
      "start_date": "2024-02-01",
      "end_date": "2024-03-01",
      "blocks": [
        {
          "id": 0,
          "name": "SINGLE",
          "hours": 696
        }
      ],
      "num_scenarios": 10
    },
    {
      "id": 2,
      "start_date": "2024-03-01",
      "end_date": "2024-04-01",
      "blocks": [
        {
          "id": 0,
          "name": "SINGLE",
          "hours": 744
        }
      ],
      "num_scenarios": 10
    },
    {
      "id": 3,
      "start_date": "2024-04-01",
      "end_date": "2024-05-01",
      "blocks": [
        {
          "id": 0,
          "name": "SINGLE",
          "hours": 720
        }
      ],
      "num_scenarios": 10
    }
  ]
}

policy_graph.type: "finite_horizon" is the correct choice for a planning horizon with a definite end date and no cycling. The annual_discount_rate is applied to discount future stage costs back to present value. A rate of 0.12 means costs one year in the future are worth 88% of present costs.

Each stage entry needs an id (0-indexed integer), a start_date and end_date in ISO 8601 format, an array of blocks, and a num_scenarios count.

The blocks array subdivides a stage into load periods. A single block named SINGLE that spans all the hours of the month is the simplest choice. More detailed studies use two or three blocks (peak/off-peak/overnight) to capture intra-stage load variation. The hours value must equal the actual number of hours in the stage: these hours convert MW dispatch levels to MWh costs in the LP objective.

num_scenarios is the number of inflow/load scenario trajectories sampled at each stage during training. More scenarios per iteration produce less-noisy cut estimates at the cost of more LP solves per iteration.

Step 3: Create penalties.json

Penalty costs define how much the solver pays when it cannot satisfy a constraint without violating a physical bound. High penalties make violations expensive so the solver avoids them; low penalties on minor constraints (like spillage) allow the solver to use flexibility when needed.

Create my_study/penalties.json:

{
  "bus": {
    "deficit_segments": [
      {
        "depth_mw": 500.0,
        "cost": 7000.0
      },
      {
        "depth_mw": null,
        "cost": 7500.0
      }
    ],
    "excess_cost": 100.0
  },
  "line": {
    "exchange_cost": 2.0
  },
  "hydro": {
    "spillage_cost": 0.01,
    "turbined_cost": 0.05,
    "diversion_cost": 0.1,
    "storage_violation_below_cost": 10000.0,
    "filling_target_violation_cost": 6000.0,
    "turbined_violation_below_cost": 500.0,
    "outflow_violation_below_cost": 500.0,
    "outflow_violation_above_cost": 500.0,
    "generation_violation_below_cost": 1000.0,
    "evaporation_violation_cost": 5000.0,
    "water_withdrawal_violation_cost": 1000.0
  },
  "non_controllable_source": {
    "curtailment_cost": 0.005
  }
}

The bus.deficit_segments array must end with a segment where depth_mw is null. This unbounded final segment ensures the LP always has a feasible solution even when generation capacity is insufficient to cover load. All four top-level sections (bus, line, hydro, non_controllable_source) are required even if your system contains none of that entity type.

Individual penalty values can be overridden per entity by adding a penalties block inside any entity definition in the system/ files. The global values here serve as the default for any entity that does not specify its own.

Step 4: Create system/buses.json

A bus is an electrical node. All generators and loads connect to a bus. Every system needs at least one bus.

Create my_study/system/buses.json:

{
  "buses": [
    {
      "id": 0,
      "name": "SIN",
      "deficit_segments": [
        {
          "depth_mw": null,
          "cost": 1000.0
        }
      ]
    }
  ]
}

id must be a unique non-negative integer. name is a human-readable label used in output files and validation messages. The deficit_segments override here replaces the global deficit curve from penalties.json for this specific bus. A single unbounded segment at 1000 $/MWh is the simplest possible deficit model.

If you omit deficit_segments from a bus, Cobre uses the global default from penalties.json for that bus. Explicit overrides are useful when different buses have different Value of Lost Load characteristics.

Step 5: Create system/lines.json

Transmission lines connect pairs of buses and impose flow limits between them. A single-bus system has no lines.

Create my_study/system/lines.json:

{
  "lines": []
}

The file must exist even with an empty array. The validator checks that the file is present and that its schema is valid. If you later add a second bus, you can add lines here by specifying source_bus_id, target_bus_id, direct_mw, and reverse_mw for each line.

Step 6: Create system/thermals.json

Thermal plants are dispatchable generators. They have a fixed cost per MWh of generation and physical capacity bounds. Add them in increasing cost order as a matter of convention, though the LP will find the optimal merit order regardless.

Create my_study/system/thermals.json:

{
  "thermals": [
    {
      "id": 0,
      "name": "UTE1",
      "bus_id": 0,
      "cost_per_mwh": 5.0,
      "generation": {
        "min_mw": 0.0,
        "max_mw": 15.0
      }
    },
    {
      "id": 1,
      "name": "UTE2",
      "bus_id": 0,
      "cost_per_mwh": 10.0,
      "generation": {
        "min_mw": 0.0,
        "max_mw": 15.0
      }
    }
  ]
}

bus_id: 0 connects both plants to the SIN bus. cost_per_mwh is the scalar marginal cost of generation [$/MWh]. The LP dispatches the plant at any level between min_mw and max_mw, with cost equal to dispatched_mw * hours_in_block * cost_per_mwh.

generation.min_mw: 0.0 means the plant can be turned off completely. A non-zero minimum would represent a must-run commitment constraint. max_mw caps the generation level.

The bus_id must reference a bus id defined in buses.json. The validator will catch any broken reference and report it as a reference integrity error.

Step 7: Create system/hydros.json

Hydro plants have three components: a reservoir (state variable between stages), a turbine (converts water flow to electricity), and optional cascade linkage to downstream plants.

Create my_study/system/hydros.json:

{
  "hydros": [
    {
      "id": 0,
      "name": "UHE1",
      "bus_id": 0,
      "downstream_id": null,
      "reservoir": {
        "min_storage_hm3": 0.0,
        "max_storage_hm3": 1000.0
      },
      "outflow": {
        "min_outflow_m3s": 0.0,
        "max_outflow_m3s": 50.0
      },
      "generation": {
        "model": "constant_productivity",
        "min_turbined_m3s": 0.0,
        "max_turbined_m3s": 50.0,
        "min_generation_mw": 0.0,
        "max_generation_mw": 50.0
      }
    }
  ]
}

downstream_id: null marks UHE1 as a tailwater plant. To model a cascade where plant A flows into plant B, you would set downstream_id: <B's id> on plant A. Cobre enforces that the downstream graph is acyclic.

The reservoir block uses hm³ (cubic hectometres) as the unit for water volume. min_storage_hm3: 0.0 allows the reservoir to empty completely. If your plant has a dead storage (volume below the turbine intake), set min_storage_hm3 to that value.

The outflow block limits total outflow (turbined flow plus spillage). The upper bound max_outflow_m3s: 50.0 models the river channel capacity. Setting a non-zero min_outflow_m3s would represent a minimum ecological flow requirement.

The generation block uses "constant_productivity", the simplest of the three supported turbine models. The other two — "linearized_head" and "fpha" (four- piece hyperplane approximation) — model head-dependent productivity for variable- head plants. The productivity coefficient that converts turbined flow to generated power is supplied in system/hydro_production_models.json. For details on all three models, see Hydro Plants.

Step 8: Create initial_conditions.json

Every hydro plant needs an initial reservoir storage value at the start of the study. This is the state the solver uses for stage 0’s water balance equation.

Create my_study/initial_conditions.json:

{
  "storage": [
    {
      "hydro_id": 0,
      "value_hm3": 83.222
    }
  ],
  "filling_storage": []
}

hydro_id: 0 matches UHE1 defined in system/hydros.json. Every hydro plant in the system must have exactly one entry in either storage or filling_storage — not both, not neither. The validator checks this.

value_hm3: 83.222 sets the initial reservoir at about 8.3% of its 1000 hm³ capacity. Choosing a realistic initial condition matters for short horizons because the first few stages will be heavily influenced by whether the reservoir starts full or nearly empty. For multi-year studies the initial condition has less impact on later stages.

filling_storage is for filling reservoirs — reservoirs that accumulate water but do not generate power. The 1dtoy system has none, so this array is empty. It must be present even when empty.

Step 9: Validate Your Case

With those files in place, validate the case to confirm every layer passes:

cobre validate my_study

On success, Cobre prints the entity counts:

Valid case: 1 buses, 1 hydros, 2 thermals, 0 lines
  buses: 1
  hydros: 1
  thermals: 2
  lines: 0

If any validation layer fails, each error is prefixed with error: and the exit code is 1. Common errors at this stage:

• reference error: hydro 0 references bus 99 which does not exist — a bus_id in hydros.json does not match any id in buses.json.
• initial conditions: hydro 0 has no initial storage entry — a hydro plant in hydros.json is missing from initial_conditions.json.
• penalties.json: non_controllable_source section missing — a required top-level section is absent from penalties.json, even if the system has no NCS plants.

Fix each reported error and re-run cobre validate until the exit code is 0.

What’s Next

Run the case directly:

cobre run my_study --output my_study/results

Your hand-built case should match the 1dtoy template; verify with the diff below:

cobre init --template 1dtoy 1dtoy_reference
diff -r my_study 1dtoy_reference

From here, the natural next steps are:

• Understanding Results — how to read the Parquet output files
• Anatomy of a Case — detailed explanation of every field in these files
• Case Format Reference — complete schema with all optional fields
• Configuration — advanced config.json options including warm-start and cut selection

System Modeling

A Cobre case describes a power system as a collection of entities. Each entity represents a physical component — a bus, a generator, a transmission line — or a contractual obligation. Together, they form the complete model that the solver turns into a sequence of LP sub-problems, one per stage per scenario trajectory.

The fundamental organizing principle: every generator and every load connects to a bus. A bus is an electrical node at which the power balance constraint must hold. At each stage and each load block, the LP enforces that the total power injected into a bus equals the total power withdrawn from it. When the constraint cannot be satisfied by physical generation alone, deficit slack variables absorb the gap at a penalty cost, ensuring the LP always has a feasible solution.

Entities are grouped by type and stored in a System object. The System is built from the case directory by load_case, which runs a layered validation pipeline before handing the model to the solver. Within the System, all entity collections are kept in canonical ID-sorted order. This ordering is an invariant: it guarantees that simulation results are bit-for-bit identical regardless of the order entities appear in the input files.

Entity Types

Every modeled entity type contributes LP variables and constraints in optimization and simulation.

Non-Controllable Sources

A non-controllable source (NCS) represents a variable renewable generator whose output is externally specified rather than optimized by the solver. Typical examples include wind farms, utility-scale solar arrays, and run-of-river hydro units without significant storage. The solver dispatches the NCS at its full available capacity unless doing so would oversupply the bus, in which case curtailment occurs and the solver pays a curtailment penalty.

Each NCS contributes one generation LP variable per block, bounded by:

0 <= generation_mw <= available_generation_mw * block_factor

where available_generation_mw comes from constraints/ncs_bounds.parquet (with system/non_controllable_sources.json providing the base value) and block_factor from scenarios/non_controllable_factors.json (default 1.0).

When scenarios/non_controllable_stats.parquet is present, NCS availability becomes stochastic: each forward and backward pass scenario draws a random availability factor and the LP column upper bound varies per scenario. See Stochastic Modeling for details.

The objective coefficient is -curtailment_cost * block_hours, making it cheaper to generate than to curtail. The NCS generation variable injects +1.0 MW at its connected bus in the power balance constraint, identical to a thermal plant.

Simulation output is written to simulation/non_controllables/ with columns for generation_mw, available_mw, curtailment_mw, and curtailment_cost per (stage, block, source) triplet. See the Output Format Reference for the complete schema.

Pumping Stations

A pumping station represents a pumped-storage or water-transfer installation that moves water from a source hydro reservoir uphill to a destination hydro reservoir, consuming electrical power in the process.

Each pumping station contributes one per-block pumped-flow decision variable, bounded by [min_m3s, max_m3s]. The pumped flow appears with opposite signs in the two reservoir water-balance rows: it is subtracted from the source reservoir and added to the destination reservoir. The power drawn from the station’s bus is:

power_consumed_mw = consumption_mw_per_m3s × flow_m3s

This power appears as a load on the bus power-balance row, identical in structure to a bus load demand. Simulation output is written to simulation/pumping_stations/ and the associated cost is reported in the pumping_cost column.

Pumping stations support the same commissioning window available on other entity types: when entry_stage_id and exit_stage_id are set, the station contributes LP variables only at stages in [entry_stage_id, exit_stage_id). Outside that window the station contributes no columns. A worked example is available at examples/deterministic/d32-reversible-plant.

Energy Contracts

An energy contract represents a bilateral purchase or sale obligation with a counterparty outside the modeled system. Each contract contributes one LP column per block per direction on its bus_id. An import contract injects power into the bus (+1.0 coefficient in the power-balance row); an export contract withdraws power from the bus (−1.0 coefficient). The column is bounded by:

min_mw <= power_mw <= max_mw

The price sign follows the economic convention: a positive price_per_mwh represents a cost (the system pays for imported energy), and a negative price_per_mwh represents revenue (the system earns from exported energy).

Contracts support the same commissioning window used by other entity types: when entry_stage_id and exit_stage_id are set, the contract is active only at stages in [entry_stage_id, exit_stage_id). At dormant stages the column bounds are pinned to [0, 0], and the output row is emitted with power_mw = 0 and operative_state_code = 1 — the row is never absent.

Stage-varying bounds and prices are supplied via constraints/contract_bounds.parquet, which accepts sparse (contract_id, stage_id) rows carrying any combination of min_mw, max_mw, and price_per_mwh. Absent rows use the base entity values. A non-zero min_mw at a given stage acts as a take-or-pay floor: the LP must dispatch at least that quantity at the contract price.

Contract dispatch is stateless: contracts carry no state variable and do not contribute to Benders cuts. All contract cost is booked inside resource_cost in the cost breakdown. Simulation output is written to simulation/contracts/ with columns for stage_id, block_id, contract_id, power_mw, energy_mwh, price_per_mwh, total_cost, and operative_state_code. See the Output Format Reference for the complete schema.

Worked example — examples/deterministic/d41-energy-contracts

The D41 case has two contracts on a single bus, with three stages of 730 h each.

Contract 0 — import, always active:

{
  "id": 0,
  "type": "import",
  "price_per_mwh": 200.0,
  "limits": { "min_mw": 0.0, "max_mw": 50.0 }
}

At stage 0 the import dispatches (power_mw > 0): the LP draws up to 50 MW of purchased energy at $200/MWh to balance the bus.

Contract 1 — export, commissioned at stage 1 only:

{
  "id": 1,
  "type": "export",
  "entry_stage_id": 1,
  "exit_stage_id": 2,
  "price_per_mwh": -150.0,
  "limits": { "min_mw": 0.0, "max_mw": 30.0 }
}

At stage 0 the export is dormant (operative_state_code = 1, power_mw = 0). At stage 1 the export is active: the LP can dispatch up to 30 MW of sold energy, earning $150/MWh (total_cost < 0).

Stage-2 override on contract 0 via constraints/contract_bounds.parquet:

At stage 2 the import is pinned to its min_mw = 10.0 take-or-pay floor and priced at $999/MWh. The LP must dispatch at least 10 MW regardless of the thermal cost, because the floor is a hard column lower bound in the LP.

How Entities Connect

The network is bus-centric. Every entity that produces or consumes power is attached to a bus via a bus_id field:

   Hydro ──┐
           │ inject
  Thermal ─┤
           ├──> Bus <──── Line ────> Bus
  NCS ─────┘
  Import ──┘
                │
               load
                │
           Export
         Pumping Station

At each stage and load block, the LP enforces the bus balance constraint:

  sum(generation at bus) + sum(imports from lines) + deficit
    = load_demand + sum(exports to lines) + excess

Deficit and excess slack variables absorb imbalance at a penalty cost, ensuring the LP is always feasible. When the deficit penalty is high enough relative to the cost of available generation, the solver will prefer to generate rather than incur deficit.

Cascade topology governs hydro plant interactions. A hydro plant with a non-null downstream_id sends all of its outflow — turbined flow plus spillage — into the downstream plant’s reservoir at the same stage. The cascade forms a directed forest: multiple upstream plants may flow into a single downstream plant, but no cycles are allowed. Water balance is computed in topological order — upstream plants first, downstream plants last — in a single pass per stage.

Declaration-Order Invariance

The order in which entities appear in the JSON input files does not affect results. Cobre reads all entities from their files, then sorts each collection by entity ID before building the System. Every function that processes entity collections operates on this canonical sorted order.

This invariant has a practical consequence: you can rearrange entries in buses.json, hydros.json, or any other entity file without changing the simulation output. You can also add new entities with lower IDs than existing ones without disturbing results for the existing entities.

Penalties and Soft Constraints

LP solvers require feasible problems. Physical constraints — minimum outflow, minimum turbined flow, reservoir bounds — can become infeasible under extreme stochastic scenarios (very low inflow, very high load). Cobre handles this by making nearly every physical constraint soft: instead of a hard infeasibility, the solver pays a penalty cost to violate the constraint by a small amount.

Penalties are set at three levels, resolved from most specific to most general:

1. Stage-level override — penalty files for individual stages, when present
2. Entity-level override — a penalties block inside the entity’s JSON object
3. Global default — the top-level penalties.json file in the case directory

This three-tier cascade lets you set a strict global spillage penalty and relax it for a specific plant that is known to spill frequently in wet years. For details on the penalty fields for each entity type, see the Configuration guide and the Case Format Reference.

The bus deficit segments are the most important penalty to configure correctly. A deficit cost that is too low makes the solver prefer deficit over building generation capacity; a cost that is too high (or an unbounded segment that is absent) can cause numerical instability. The final deficit segment must always have depth_mw: null (unbounded) to guarantee LP feasibility.

Entity Lifecycle

Entities can enter service or be decommissioned at specified stages using entry_stage_id and exit_stage_id fields:

These fields are available on Hydro, Thermal, Line, NonControllableSource, PumpingStation, and EnergyContract entities. When a plant has entry_stage_id: 12, the LP does not include any variables for that plant in stages 0 through 11. From stage 12 onward, the plant appears in every sub-problem as normal.

Lifecycle fields are useful for planning studies that span commissioning or retirement events: new thermal plants coming online mid-horizon, or aging hydro units being decommissioned. Each lifecycle event is validated to ensure that entry_stage_id falls within the stage range defined in stages.json.

Related Pages

• Hydro Plants — complete field reference for system/hydros.json
• Thermal Units — complete field reference for system/thermals.json
• Network Topology — buses, lines, deficit modeling, and transmission
• Anatomy of a Case — walkthrough of every file in the 1dtoy example
• Case Format Reference — complete JSON schema for all input files

Hydro Plants

Hydroelectric power plants are the central dispatchable resource in Cobre’s system model. Unlike thermal units, which convert fuel into electricity at a cost, hydro plants manage a reservoir — a state variable that persists between stages and couples the dispatch decisions of today to the feasibility of tomorrow. This intertemporal coupling is precisely why hydrothermal scheduling requires stochastic dynamic programming rather than a simple merit-order dispatch.

A hydro plant in Cobre is composed of three physical components: a reservoir that stores water between stages, a turbine that converts water flow into electrical generation, and a spillway that releases excess water without producing power. Each stage’s LP sub-problem contains one water balance constraint per plant: inflow plus beginning storage equals turbined flow plus spillage plus ending storage. The solver decides how much to turbine and how much to store, trading off present-stage generation against future-stage optionality.

Plants can be linked into a cascade via the downstream_id field. When plant A has downstream_id pointing to plant B, all water released from A (turbined flow plus spillage) enters B’s reservoir at the same stage. Cascade topology is validated to be acyclic — no chain of downstream references may loop back to an earlier plant.

For a step-by-step introduction to writing hydros.json, see Building a System and Anatomy of a Case. This page provides the complete field reference with all optional fields documented.

Theory reference: For the mathematical formulation of hydro modeling and the SDDP algorithm that drives dispatch decisions, see SDDP Theory in the methodology reference.

JSON Schema

Hydro plants are defined in system/hydros.json. The top-level object has a single key "hydros" containing an array of plant objects. The following example shows all fields — required and optional — for a single plant:

{
  "hydros": [
    {
      "id": 1,
      "name": "UHE Tucuruí",
      "bus_id": 0,
      "downstream_id": null,
      "entry_stage_id": null,
      "exit_stage_id": null,
      "reservoir": {
        "min_storage_hm3": 50.0,
        "max_storage_hm3": 45000.0
      },
      "outflow": {
        "min_outflow_m3s": 1000.0,
        "max_outflow_m3s": 100000.0
      },
      "generation": {
        "model": "constant_productivity",
        "min_turbined_m3s": 500.0,
        "max_turbined_m3s": 22500.0,
        "min_generation_mw": 0.0,
        "max_generation_mw": 8370.0
      },
      "tailrace": {
        "type": "polynomial",
        "coefficients": [5.0, 0.001]
      },
      "hydraulic_losses": {
        "type": "factor",
        "value": 0.03
      },
      "efficiency": {
        "type": "constant",
        "value": 0.93
      },
      "evaporation": {
        "coefficients_mm": [
          80.0, 75.0, 70.0, 65.0, 60.0, 55.0, 60.0, 65.0, 70.0, 75.0, 80.0, 85.0
        ]
      },
      "diversion": {
        "downstream_id": 2,
        "max_flow_m3s": 200.0
      },
      "filling": {
        "start_stage_id": 48,
        "filling_min_rate_m3s": 100.0
      },
      "penalties": {
        "spillage_cost": 0.01,
        "diversion_cost": 0.1,
        "turbined_cost": 0.05,
        "storage_violation_below_cost": 10000.0,
        "filling_target_violation_cost": 6000.0,
        "turbined_violation_below_cost": 500.0,
        "outflow_violation_below_cost": 500.0,
        "outflow_violation_above_cost": 500.0,
        "generation_violation_below_cost": 1000.0,
        "evaporation_violation_cost": 5000.0,
        "water_withdrawal_violation_cost": 1000.0
      }
    }
  ]
}

The 1dtoy template uses a minimal hydro definition that omits all optional fields. Only id, name, bus_id, downstream_id, reservoir, outflow, and generation are required. All other top-level keys (tailrace, hydraulic_losses, efficiency, evaporation, diversion, filling, penalties) are optional and default to off when absent.

Core Fields

These fields appear at the top level of each hydro plant object.

Reservoir

The reservoir block defines the operational storage bounds for the plant. Storage is tracked in hm³ (cubic hectometres; 1 hm³ = 10⁶ m³). The beginning-of-stage storage is the state variable that links consecutive stages in the LP.

"reservoir": {
  "min_storage_hm3": 0.0,
  "max_storage_hm3": 1000.0
}

Setting min_storage_hm3 to the dead volume of your reservoir is important for correctly computing the usable storage range. A reservoir with 500 hm³ total physical capacity but 100 hm³ below the turbine intakes should be modeled as min_storage_hm3: 100.0, max_storage_hm3: 500.0.

Outflow Constraints

The outflow block constrains total outflow from the plant. Total outflow equals turbined flow plus spillage. These constraints are enforced by soft penalties when they cannot be satisfied due to extreme scenario conditions.

"outflow": {
  "min_outflow_m3s": 0.0,
  "max_outflow_m3s": 50.0
}

Minimum outflow is a hard lower bound on the sum of turbined flow and spillage. When the solver cannot meet this bound (for example, because the reservoir is nearly empty and inflow is very low), a violation slack variable is added to the LP at the cost specified by outflow_violation_below_cost in the penalties block.

Generation Models

The generation block configures the turbine model for dispatch purposes. It provides the default production function used when no hydro_production_models.json file is present, or for any plant not listed there. All variants share the core turbine bounds (min_turbined_m3s, max_turbined_m3s) and generation bounds (min_generation_mw, max_generation_mw). The model key selects which production function converts flow to power.

"generation": {
  "model": "constant_productivity",
  "min_turbined_m3s": 0.0,
  "max_turbined_m3s": 50.0,
  "min_generation_mw": 0.0,
  "max_generation_mw": 50.0
}

Available Production Function Models

For the 1dtoy example and for most initial studies, constant_productivity is the correct choice. The productivity coefficient encodes the plant’s average efficiency and net head, and is supplied in system/hydro_production_models.json. For a plant with 80 m net head and 90% efficiency, the theoretical productivity is approximately 9.81 × 80 × 0.90 / 1000 ≈ 0.706 MW/(m³/s).

FPHA Production Model

The FPHA (Função de Produção Hidroelétrica Aproximada) model represents the nonlinear relationship between reservoir volume, turbined flow, spillage, and electrical generation as a piecewise-linear envelope. It captures the head dependence of hydro production — plants with high reservoir levels generate more power for the same turbined flow.

FPHA is configured per plant and per stage via system/hydro_production_models.json. A plant not listed in that file uses the model specified in its generation block in hydros.json.

Configuration File

system/hydro_production_models.json maps each hydro plant to a production model selection strategy. The file is optional; when absent, all plants use their generation.model from hydros.json.

Two selection strategies are supported:

stage_ranges — assigns a model to each contiguous stage interval:

{
  "$schema": "../schemas/production_models.schema.json",
  "production_models": [
    {
      "hydro_id": 1,
      "selection_mode": "stage_ranges",
      "stage_ranges": [
        {
          "start_stage_id": 0,
          "end_stage_id": null,
          "model": "fpha",
          "fpha_config": {
            "source": "precomputed"
          }
        }
      ]
    }
  ]
}

Each stage range and season entry for a constant_productivity or linearized_head plant must supply its productivity coefficient through exactly one source: either an inline productivity_mw_per_m3s field on the entry, or a matching (hydro, stage) row in system/hydro_energy_productivity.parquet (see Per-Range and Per-Season Productivity below).

seasonal — assigns a model based on season index, with a fallback for seasons not explicitly listed:

{
  "$schema": "../schemas/production_models.schema.json",
  "production_models": [
    {
      "hydro_id": 1,
      "selection_mode": "seasonal",
      "default_model": "constant_productivity",
      "seasons": [
        {
          "season_id": 0,
          "model": "fpha",
          "fpha_config": {
            "source": "computed",
            "volume_discretization_points": 7,
            "turbine_discretization_points": 7
          }
        }
      ]
    }
  ]
}

Season indices are 0-based and match the season map defined in stages.json.

reference_volume

Each stage range and season entry may carry an optional reference_volume sibling of fpha_config, declaring the reference operating volume the computed-FPHA fit and the equivalent-productivity derivation consume. Set exactly one of two mutually-exclusive forms:

• volume_hm3 — an absolute storage value in hm³ (finite and > 0.0).
• percentile — a fraction in [0.0, 1.0] of the plant’s operating range.

"reference_volume": { "percentile": 0.65 }

This is the single source of truth for the reference volume; it replaces the retired reference_volume_hm3 column of system/hydro_energy_productivity.parquet.

Hyperplane Sources

When a plant is configured with model: "fpha", the fpha_config.source field selects where the hyperplane coefficients come from.

source: "precomputed"

Hyperplanes are loaded directly from system/fpha_hyperplanes.parquet. Use this source when you have pre-fitted hyperplanes from a previous run or from an external tool.

"fpha_config": {
  "source": "precomputed"
}

The fpha_config block for "precomputed" requires no additional fields. The discretization and fitting options are ignored — the hyperplanes are used as-is.

The Parquet file must be present at system/fpha_hyperplanes.parquet. Its schema is:

Each (hydro_id, stage_id) group must have at least 1 plane. Rows are sorted by (hydro_id, stage_id, plane_id) ascending; null stage_id sorts before any non-null value.

source: "computed"

Hyperplanes are fitted at runtime from the plant’s physical geometry. Cobre evaluates the production function phi(v, q) (at spillage = 0) on a (volume, turbined-flow) grid, takes the 3-D convex hull of the resulting cloud using vendored qhull, applies a least-squares α correction to the intercept, and then fits a per-plane lateral/spillage secant. Fits are resolved independently per stage (one fit per season or stage range), so plants whose head-efficiency characteristics change across seasons get stage-specific plane sets. Run-of-river plants with a single operating volume (constant forebay) are supported: the volume dimension collapses and the fit produces a valid single-volume hyperplane set.

This source requires:

1. The hydro plant must have tailrace, hydraulic_losses, and efficiency models defined in hydros.json.
2. system/hydro_geometry.parquet must contain at least 1 row for the plant. A single row is valid for run-of-river plants with a constant forebay (γ_V = 0). linearized_head still requires at least 2 rows because it fits a head slope in volume; that constraint does not apply to FPHA.

"fpha_config": {
  "source": "computed",
  "volume_discretization_points": 5,
  "turbine_discretization_points": 5,
  "spillage_discretization_points": 5,
  "max_planes_per_hydro": 10,
  "fitting_window": null
}

All fields except source are optional:

The fitting_window field restricts which portion of the operating range is used to construct the grid. Use it when the plant rarely operates near one extreme and you want the planes to be tighter in the operating region. Two bound variants are supported per dimension, and they are mutually exclusive:

"fitting_window": {
  "volume_min_hm3": 1000.0,
  "volume_max_hm3": 40000.0
}

"fitting_window": {
  "volume_min_percentile": 5.0,
  "volume_max_percentile": 95.0
}

Do not mix absolute (_hm3) and percentile (_percentile) bounds for the same limit — the validator will reject the configuration.

Fit-Quality Warning

After fitting, Cobre evaluates every fitted plane set against the exact production function on the spillage = 0 grid (the V/Q envelope). When the relative mean absolute deviation between the fitted envelope and the exact function exceeds 5 %, a warning is logged naming the plant and stage:

Warning: hydro 'UHE Example' stage 3 FPHA fit deviation = 6.2 % (> 5 %).
Consider increasing discretization points or narrowing the fitting window.

The warning is informational — the run continues with the fitted planes. The threshold of 5 % is assessed on the spillage = 0 grid and reflects how well the V/Q envelope was captured; the spillage secant correction is applied separately and is not included in this check.

For source: "precomputed", the kappa column in system/fpha_hyperplanes.parquet is read as a back-compat correction factor applied to each plane’s intercept. When the column is absent or null, kappa defaults to 1.0 (the stored intercepts are used unchanged). The kappa derivation and warning are removed from the computed path; they apply only to precomputed inputs that carry an explicit kappa value.

Parquet Export for Round-Trip Use

When hyperplanes are fitted at runtime (source: "computed"), the fitted coefficients are automatically written to:

output/hydro_models/fpha_hyperplanes.parquet

This file uses the same 11-column schema as the input system/fpha_hyperplanes.parquet. To switch from computed to precomputed fitting on a subsequent run, copy this file to system/fpha_hyperplanes.parquet and change source to "precomputed" in hydro_production_models.json.

Plane Reduction (fpha_plane_reduction)

The optional file-level fpha_plane_reduction block in system/hydro_production_models.json merges near-parallel or near-coincident FPHA planes after fitting, reducing the LP column count without changing the fitted approximation significantly. It is off by default (absent = no reduction) and is applied uniformly to every plant in the file.

Two mutually exclusive methods are supported, selected by the method field:

Angle method — merges planes whose normal vectors are within tolerance_deg degrees of each other:

"fpha_plane_reduction": {
  "method": "angle",
  "tolerance_deg": 2.0
}

Distance method — merges planes whose sampled mean-squared distance stays within tolerance_pct of each other, using n_samples sample points:

"fpha_plane_reduction": {
  "method": "distance",
  "tolerance_pct": 0.01,
  "n_samples": 200
}

Supplying a field that belongs to the other method is a load-time error (deny_unknown_fields). The origin plane (zero generation at zero turbining) is never merged into another plane. The distance method is deterministically seeded: its sample draws are bit-identical across input ordering and rank count.

Per-Range and Per-Season Productivity

For constant_productivity and linearized_head hydros, the equivalent productivity ρ_eq [MW/(m³/s)] for each (hydro, stage) pair must be supplied by exactly one of two sources:

• system/hydro_production_models.json — set productivity_mw_per_m3s directly on a stage_range or seasonal entry. Use this when productivity is constant across a range of stages or repeats with the season cycle.
• system/hydro_energy_productivity.parquet — supply a row in the equivalent_productivity_mw_per_m3s column. A row with stage_id set refines a single stage; a row with stage_id = NULL is a per-hydro default that covers any stage not refined by a stage-specific row. Use this for per-stage numerical refinement of an otherwise declarative JSON configuration.

Resolution order at load time:

1. Parquet stage-specific row (exact stage_id match).
2. Parquet per-hydro default row (stage_id = NULL).
3. JSON productivity_mw_per_m3s on the matching stage range or season.

If neither source supplies a value for a (hydro, stage) pair, loading fails with a clear schema error naming both files. Supplying a value from both files for the same (hydro, stage) is also rejected — pick exactly one source per pair.

{
  "start_stage_id": 12,
  "end_stage_id": 24,
  "model": "constant_productivity",
  "productivity_mw_per_m3s": 0.72
}

Validation rules:

• productivity_mw_per_m3s must be finite and non-negative (>= 0.0) when present. 0.0 is accepted as a planned-outage marker.
• productivity_mw_per_m3s is rejected when model is "fpha" (FPHA derives productivity from VHA geometry and ρ_esp, not a scalar coefficient).
• For constant_productivity and linearized_head, the JSON value may be omitted (or set to null) when the parquet override supplies the value for the same (hydro, stage).

For FPHA hydros, ρ_eq is derived from VHA geometry and ρ_esp. The parquet column equivalent_productivity_mw_per_m3s may still supply an override that replaces the derivation when present.

Cascade Topology

The downstream_id field creates a directed chain of hydro plants. Water released from an upstream plant — whether turbined or spilled — enters the downstream plant’s reservoir in the same stage.

To model a three-plant cascade where plant 0 flows into plant 1, which flows into plant 2:

{ "id": 0, "downstream_id": 1, ... }
{ "id": 1, "downstream_id": 2, ... }
{ "id": 2, "downstream_id": null, ... }

Cobre validates that the downstream graph is acyclic: no chain of downstream_id references may return to a plant already in the chain. A cycle would make the water balance equation unsolvable. The validator reports the cycle as a topology error with the full chain of plant IDs.

Plants with downstream_id: null are tailwater plants — their outflow leaves the basin. Each connected component of the cascade graph must have exactly one tailwater plant (the chain’s end node). A cascade component with no tailwater plant would be a cycle, which the validator rejects.

Advanced Fields

The following fields enable more detailed physical modeling. They are all optional. For most system planning studies, these fields can be omitted; they become relevant when calibrating a model against historical dispatch data or when the head variation at a plant is significant.

Tailrace Model

The tailrace block models the downstream water level as a function of total outflow. The tailrace elevation affects the net hydraulic head and is used by the linearized_head and fpha generation models. When absent, tailrace elevation is treated as zero.

Two variants are supported:

Polynomial — height = a₀ + a₁·Q + a₂·Q² + …

"tailrace": {
  "type": "polynomial",
  "coefficients": [5.0, 0.001]
}

coefficients is an array of polynomial coefficients in ascending power order. coefficients[0] is the constant term (height at zero outflow in metres), coefficients[1] is the coefficient for Q¹, and so on.

Piecewise — linearly interpolated between (outflow, height) breakpoints.

"tailrace": {
  "type": "piecewise",
  "points": [
    { "outflow_m3s": 0.0, "height_m": 3.0 },
    { "outflow_m3s": 5000.0, "height_m": 4.5 },
    { "outflow_m3s": 15000.0, "height_m": 6.2 }
  ]
}

Points must be sorted in ascending outflow_m3s order. The solver interpolates linearly between adjacent points.

Hydraulic Losses

The hydraulic_losses block models head loss in the penstock and draft tube. Hydraulic losses reduce the effective head available at the turbine. When absent, the penstock is modeled as lossless.

Factor — loss as a fraction of net head:

"hydraulic_losses": { "type": "factor", "value": 0.03 }

value is a dimensionless fraction (e.g., 0.03 = 3% of net head).

Constant — fixed head loss regardless of flow:

"hydraulic_losses": { "type": "constant", "value_m": 2.5 }

value_m is the fixed head loss in metres.

Efficiency Model

The efficiency block scales the power output from the hydraulic power available. When absent, 100% efficiency is assumed.

Currently only the "constant" variant is supported:

"efficiency": { "type": "constant", "value": 0.93 }

value is a dimensionless fraction in the range (0, 1]. A value of 0.93 means the turbine converts 93% of available hydraulic power to electrical output.

Evaporation

The evaporation block models the net water flux at the reservoir surface. When absent, no evaporation is modeled. Coefficients are signed: positive values represent net evaporative loss, negative values represent net rainfall input on the lake surface (precipitation on the reservoir exceeds open-water evaporation, common in wet months of tropical and subtropical basins).

"evaporation": {
  "coefficients_mm": [
    80.0, 75.0, 70.0, 65.0, 60.0, 55.0,
    60.0, 65.0, 70.0, 75.0, 80.0, 85.0
  ],
  "reference_volumes_hm3": [
    15000, 12000, 10000, 8000, 6000, 5000,
    5500, 7000, 9000, 11000, 13000, 14500
  ]
}

Diversion Channel

The diversion block models a water diversion channel that routes flow directly from this plant’s reservoir to a downstream plant’s reservoir, bypassing turbines and spillways. When absent, no diversion is modeled.

"diversion": {
  "downstream_id": 2,
  "max_flow_m3s": 200.0
}

Filling Configuration

The filling block enables a filling operation mode, where the reservoir is intentionally filled from an external, fixed inflow source (such as a diversion works from an unrelated basin) during a defined stage window. When absent, no filling operation is active.

"filling": {
  "start_stage_id": 48,
  "filling_min_rate_m3s": 100.0
}

Penalties

The penalties block inside a hydro plant definition overrides the global defaults from penalties.json for that specific plant. When the block is absent, all penalty values fall back to the global defaults. When it is present, it must contain all penalty fields.

Penalty costs are added to the LP objective when soft constraint violations occur. They do not represent physical costs — they are optimization weights that guide the solver to avoid infeasible or undesirable operating states.

"penalties": {
  "spillage_cost": 0.01,
  "diversion_cost": 0.1,
  "turbined_cost": 0.05,
  "storage_violation_below_cost": 10000.0,
  "filling_target_violation_cost": 6000.0,
  "turbined_violation_below_cost": 500.0,
  "outflow_violation_below_cost": 500.0,
  "outflow_violation_above_cost": 500.0,
  "generation_violation_below_cost": 1000.0,
  "evaporation_violation_cost": 5000.0,
  "water_withdrawal_violation_cost": 1000.0,
  "water_withdrawal_violation_pos_cost": 1200.0,
  "water_withdrawal_violation_neg_cost": 800.0,
  "evaporation_violation_pos_cost": 5000.0,
  "evaporation_violation_neg_cost": 5000.0,
  "inflow_nonnegativity_cost": 1000.0
}

The evaporation_violation_cost and water_withdrawal_violation_cost fields act as symmetric defaults: the same penalty applies whether the violation is positive (over-evaporation or over-withdrawal) or negative (under-evaporation or under-withdrawal). When the directional fields are present (evaporation_violation_pos_cost, evaporation_violation_neg_cost, water_withdrawal_violation_pos_cost, water_withdrawal_violation_neg_cost), they override the symmetric default for their respective direction, allowing asymmetric penalty weights. The turbined_violation_below_cost, outflow_violation_below_cost, outflow_violation_above_cost, and generation_violation_below_cost penalties are applied independently to each dispatch block within a stage.

Three-Tier Resolution Cascade

Penalty values are resolved from the most specific to the most general source:

1. Stage-level override (defined in stage-specific penalty files, when present)
2. Entity-level override (the penalties block inside the plant’s JSON object)
3. Global default (the hydro section of penalties.json)

The penalties block on a plant replaces the global default for that plant alone. All plants that do not have a penalties block use the global values from penalties.json. The global penalties.json file must always be present and must contain all hydro penalty fields.

Validation Rules

Cobre’s layered validation pipeline checks the following conditions on hydro plants. Violations are reported as error messages with the failing plant’s id and the nature of the problem.

Related Pages

• Anatomy of a Case — walks through the complete 1dtoy hydro definition
• Building a System — step-by-step guide to writing hydros.json from scratch
• System Modeling — overview of all entity types and how they interact
• Case Format Reference — complete JSON schema for all input files

Energy Variables

Cobre computes five energy-related quantities for each hydro plant at every stage and writes them to simulation/hydros/. These quantities are derived from productivity coefficients that summarise how efficiently each plant — and its downstream cascade — converts water volume into electrical energy. This page explains what those coefficients are, how they are derived, and what the five output columns mean.

Equivalent Productivity (ρ_eq)

The equivalent productivity ρ_eq [MW/(m³/s)] is a single scalar that represents the power yield per unit of turbined flow at a specific operating point (V_ref, Q_ref). It collapses the head, tailrace, and hydraulic loss effects into one number for a given stage.

For the two fixed-productivity models (constant_productivity and linearized_head), ρ_eq is supplied per (hydro, stage) by exactly one of the inline productivity_mw_per_m3s field on system/hydro_production_models.json or the equivalent_productivity_mw_per_m3s column in system/hydro_energy_productivity.parquet. Supplying the same (hydro, stage) value in both files is rejected at load time. For FPHA plants the head is variable, so ρ_eq is computed at a reference operating point:

ρ_eq = ρ_esp × h_eq(V_ref, Q_ref)

where:
  ρ_esp  = specific productivity [MW/(m³/s)/m]
  h_eq   = h_fore(V_ref) − h_tail(Q_ref) − h_loss  [m]
  h_fore = forebay elevation interpolated from the VHA curve at V_ref
  h_tail = tailrace elevation at Q_ref (0 if no tailrace model)
  h_loss = hydraulic head loss at Q_ref (0 if no loss model)

The reference operating point defaults to:

V_ref = V_min + fraction × (V_max − V_min)
Q_ref = max_turbined_m3s

where fraction is a per-(hydro, season) value resolved from the reference volume configuration.

Derivation Precedence for FPHA Plants

Cobre resolves ρ_eq for each FPHA hydro in the following priority order at each stage:

1. Override table — an explicit equivalent_productivity_mw_per_m3s entry in system/hydro_energy_productivity.parquet for the (hydro_id, stage_id) pair (or a per-hydro default row with stage_id = NULL).
2. VHA geometry + ρ_esp — ρ_esp from the plant’s specific_productivity_mw_per_m3s_per_m field in hydros.json and VHA rows from system/hydro_geometry.parquet, evaluated at (V_ref, Q_ref).
3. Error — if neither source is available, StudySetup::new returns:

FPHA hydro '<name>' (<id>) cannot derive ρ_eq for stage <N>:
no VHA geometry + ρ_esp pair is present and no override entry exists.
Remediation: (1) supply VHA geometry rows and specific_productivity (ρ_esp)
for this hydro, (2) add an entry in system/hydro_energy_productivity.parquet,
or (3) change the hydro's generation_model away from FPHA.

Non-FPHA plants follow the same priority order minus the VHA path: the equivalent_productivity_mw_per_m3s column wins when present, otherwise the inline productivity_mw_per_m3s field on system/hydro_production_models.json is used. Supplying the same (hydro, stage) in both files is rejected at load time; supplying neither is also rejected.

Accumulated Productivity (ρ_acum)

The accumulated productivity ρ_acum [MW/(m³/s)] sums the equivalent productivities along the cascade from the plant itself down to the last plant before the sea (or tail of the river). A unit of water flowing through the entire downstream chain generates ρ_acum megawatts in aggregate.

ρ_acum(hydro) = ρ_eq(hydro) + ρ_acum(downstream hydro)

For the plant at the tail of the cascade (no downstream neighbour):

ρ_acum(tail) = ρ_eq(tail)

Two-Plant Cascade Example

Consider two plants, A and B, where A discharges into B:

River → [Reservoir A] → turbine A → [Reservoir B] → turbine B → tailwater

Suppose at a given stage:

ρ_eq(A) = 2.50 MW/(m³/s)
ρ_eq(B) = 1.80 MW/(m³/s)

Then:

ρ_acum(B) = ρ_eq(B)              = 1.80 MW/(m³/s)
ρ_acum(A) = ρ_eq(A) + ρ_acum(B) = 2.50 + 1.80 = 4.30 MW/(m³/s)

Water released by A eventually passes through both turbines; its energy value is 4.30 MW per m³/s of turbined flow.

The Five Output Columns

All five columns appear in every row of simulation/hydros/. The schema position is after generation_mwh and before spillage_cost.

equivalent_productivity_mw_per_m3s

The ρ_eq value for this plant at this stage, in MW/(m³/s). Never null.

Derived as described above: override table first, then VHA geometry, then stored scalar for non-FPHA models.

accumulated_productivity_mw_per_m3s

The ρ_acum value for this plant at this stage, in MW/(m³/s). Never null.

For a tail plant, equals equivalent_productivity_mw_per_m3s. For a headwater plant in a long cascade, may be several times larger.

incremental_inflow_energy_mw

The power equivalent of the natural incremental inflow to this plant at this stage, expressed as an average MW over the stage:

incremental_inflow_energy_mw = ρ_acum × incremental_inflow_m3s

This is the natural-inflow-energy contribution of this plant’s incremental inflow in MW. It measures how much firm energy the incoming water represents considering the full cascade downstream.

Using the two-plant cascade above with an incremental inflow to A of 200 m³/s:

incremental_inflow_energy_mw(A) = 4.30 × 200 = 860 MW

stored_energy_initial_mwh

The energy content of the water stored in the reservoir at the beginning of the stage, expressed in MWh:

stored_energy_initial_mwh = (storage_initial_hm3 − V_min) × ρ_acum × 1e6 / 3600

The factor 1e6 / 3600 converts hm³ to m³ and then seconds to hours (1 hm³ = 1×10⁶ m³; 1 MWh = 3600 MWs = 3600 MW·s). Only the usable storage above the minimum operational volume V_min is counted.

Using the cascade example with V_min(A) = 50 hm³ and storage_initial(A) = 200 hm³:

stored_energy_initial_mwh(A) = (200 − 50) × 4.30 × 1e6 / 3600 ≈ 179,167 MWh

stored_energy_final_mwh

Same formula as stored_energy_initial_mwh, applied to storage_final_hm3:

stored_energy_final_mwh = (storage_final_hm3 − V_min) × ρ_acum × 1e6 / 3600

This column is the stored energy at the end of the stage in MWh.

Productivity Override File

system/hydro_energy_productivity.parquet is an optional file that allows you to override any of the three scalars (ρ_eq, Q_ref, ρ_esp) on a per-(hydro, stage) basis. The reference operating volume V_ref is no longer an override column here — declare it per production model via reference_volume in system/hydro_production_models.json. Rows with stage_id = NULL serve as a per-hydro default that applies to all stages not covered by a stage-specific row.

See the Case Directory Format reference for the full column table and validation rules.

Diversion Channels

Plants with a diversion channel are treated as standard cascade members for energy-variable purposes. The plant’s ρ_eq and ρ_acum are derived from its own production model and its position in the main cascade topology. Diverted flow is accounted for in incremental_inflow_m3s through the normal water balance; the energy variables reflect the declared topology without special diversion-specific adjustments.

Scalar Parameters

A scalar parameter is a named, typed value that can be referenced by name from generic-constraint coefficient expressions. Instead of hard-coding a coefficient in the constraint expression, you declare the parameter once in an input file and reference it with the @name sigil. The solver resolves each parameter to a concrete f64 value before building the LP for each stage.

Parameters are useful when:

• The same physical quantity (e.g. a plant’s equivalent productivity) appears in multiple constraints and should stay consistent automatically.
• A coefficient varies by stage or season and you want a single place to maintain those values rather than editing multiple constraint expressions.
• The coefficient is derived from hydro geometry data and should be kept in sync with the model automatically.

Input Files

Scalar parameters are loaded from a single JSON file:

system/scalar_parameters.json

The file is optional. When absent, no parameters are loaded and any @name token in a constraint expression causes a load error.

Top-level object shape:

{
  "$schema": "https://raw.githubusercontent.com/cobre-rs/cobre/refs/heads/main/book/src/schemas/scalar_parameters.schema.json",
  "scalar_parameters": [
    { "id": 1, "name": "discount_rate", "kind": "constant", "value": 0.05 },
    {
      "id": 2,
      "name": "demand",
      "kind": "per_stage",
      "values": [
        [0, 100.0],
        [1, 110.0],
        [2, 105.0]
      ]
    },
    {
      "id": 3,
      "name": "wet_season_factor",
      "kind": "seasonal",
      "values": [
        [0, 1.2],
        [1, 0.8]
      ]
    },
    {
      "id": 4,
      "name": "hydro_prod",
      "kind": "computed",
      "computed_spec": { "tag": "equivalent_productivity", "hydro_id": 7 }
    }
  ]
}

Per-entry fields present on every parameter:

Kind-specific payload fields (present only for the matching kind):

Unknown fields on any entry are rejected at parse time.

Parameter Kinds

constant

One value applied to every stage.

{ "id": 1, "name": "demand_scale", "kind": "constant", "value": 1.05 }

per_stage

One value per study stage. The values array contains [stage_id, value] pairs. Stage indices must form a contiguous range starting at 0 (i.e. [0, 1, 2, …, N-1]). Duplicate indices and gaps are both rejected.

{
  "id": 2,
  "name": "hydro_limit_factor",
  "kind": "per_stage",
  "values": [
    [0, 0.9],
    [1, 0.85],
    [2, 0.8]
  ]
}

seasonal

One value per season, keyed by season_id. The value for a given stage is looked up by the stage’s season. Season indices need not be contiguous but must be unique within the entry.

{
  "id": 3,
  "name": "wet_season_weight",
  "kind": "seasonal",
  "values": [
    [0, 1.2],
    [1, 0.95],
    [2, 0.8],
    [3, 1.1]
  ]
}

computed

The value is derived from hydro geometry data by the solver — no numeric values are needed. The computed_spec object carries the variant tag and plant reference:

{
  "id": 4,
  "name": "rho_eq_h1",
  "kind": "computed",
  "computed_spec": { "tag": "equivalent_productivity", "hydro_id": 1 }
}

Computed Parameter Catalog

Seven hydro-indexed quantities are available as computed parameters:

All seven are stage-resolved: the value provided to the LP builder is the scalar for the stage currently being built.

Referencing a Parameter in a Constraint

Generic constraints in constraints/generic_constraints.json carry a free-form expression string. Normally a coefficient is a literal number:

{
  "id": 0,
  "name": "min_cascade_energy",
  "expression": "3.6 * hydro_generation(1) + 3.6 * hydro_generation(2)",
  "sense": ">=",
  "slack": { "enabled": true, "penalty": 5000.0 }
}

Replace literal coefficients with @name to reference a parameter. The expression parser recognises three term shapes involving @:

@name * variable(...)              — parameter coefficient, implicit scale 1.0
literal * @name * variable(...)    — literal scale multiplied by parameter coefficient

Using a computed parameter instead:

{
  "id": 0,
  "name": "min_cascade_energy",
  "expression": "@rho_eq_h1 * hydro_generation(1) + @rho_eq_h2 * hydro_generation(2)",
  "sense": ">=",
  "slack": { "enabled": true, "penalty": 5000.0 }
}

With the definitions above (rho_eq_h1 resolved from the VHA geometry for hydro 1, rho_eq_h2 for hydro 2), the LP coefficient is updated automatically each stage as the equivalent productivity changes.

If @name is used but no parameter with that name has been loaded, the case fails with a schema error during load.

Validation Rules

• id values must be unique across all entries.
• name values must be unique (case-sensitive), non-empty, and have no leading or trailing whitespace.
• kind must be exactly one of constant, per_stage, seasonal, or computed.
• For constant: value must be present and finite.
• For per_stage: values must be present and non-empty; the stage_id integers must form a contiguous range starting at 0; all values must be finite.
• For seasonal: values must be present and non-empty; season_id values must be unique within the entry; all values must be finite.
• For computed: computed_spec must be present with a valid tag (one of the seven listed above) and a hydro_id integer. Existence of the referenced hydro is validated during cross-reference checks after all entity files are loaded.
• Unknown JSON fields on any entry are rejected immediately at parse time.

Thermal Units

Thermal power plants are the dispatchable generation assets that complement hydro in Cobre’s system model. The term “thermal” covers any generator whose output is bounded by installed capacity and whose dispatch incurs an explicit cost per MWh: combustion turbines, combined-cycle plants, coal-fired units, nuclear plants, and diesel generators all map onto the same Cobre Thermal entity type.

Unlike hydro plants, thermal units carry no state between stages. Each stage’s LP sub-problem treats a thermal unit as a bounded generation variable with a marginal cost. The solver dispatches thermal units in merit order — from cheapest to most expensive — to meet any residual demand not covered by hydro generation. In a hydrothermal system, the long-run value of stored water is compared against the short-run cost of thermal dispatch at each stage, which is the fundamental trade-off the SDDP algorithm optimizes.

The cost structure of a thermal unit is modeled with a scalar marginal cost (cost_per_mwh). The LP dispatches the unit at any level between min_mw and max_mw, with the generation cost equal to dispatched_mw * hours_in_block * cost_per_mwh.

For an introductory walkthrough of writing thermals.json, see Building a System and Anatomy of a Case. This page provides the complete field reference, including anticipated dispatch configuration.

JSON Schema

Thermal units are defined in system/thermals.json. The top-level object has a single key "thermals" containing an array of unit objects. The following example shows all fields, including the optional entry_stage_id, exit_stage_id, and anticipated_config:

{
  "thermals": [
    {
      "id": 0,
      "name": "UTE1",
      "bus_id": 0,
      "cost_per_mwh": 5.0,
      "generation": {
        "min_mw": 0.0,
        "max_mw": 15.0
      }
    },
    {
      "id": 1,
      "name": "Angra 1",
      "bus_id": 0,
      "entry_stage_id": null,
      "exit_stage_id": null,
      "cost_per_mwh": 50.0,
      "generation": {
        "min_mw": 0.0,
        "max_mw": 657.0
      },
      "anticipated_config": {
        "lead_stages": 2
      }
    }
  ]
}

The first plant (UTE1) matches the 1dtoy template format: a cost per MWh with no optional fields. The second plant (Angra 1) shows the complete schema with anticipated dispatch. The fields entry_stage_id, exit_stage_id, and anticipated_config are optional and can be omitted.

Core Fields

These fields appear at the top level of each thermal unit object.

Generation Bounds

The generation block sets the output limits for the unit (stored internally as min_generation_mw and max_generation_mw on the Thermal struct). These are enforced as hard bounds on the generation variable in each stage LP.

"generation": {
  "min_mw": 0.0,
  "max_mw": 657.0
}

A min_mw of 0.0 means the unit can be turned off completely — it is treated as an interruptible resource. A non-zero min_mw (for example, 100.0 for a plant whose turbine must spin continuously for mechanical reasons) means the LP must always dispatch at least that amount whenever the plant is active.

Anticipated Dispatch Configuration

The optional anticipated_config block enables anticipated dispatch for thermal units that require advance scheduling over multiple stages due to commitment lead times — for example, a plant that must be booked several weeks before the dispatch occurs.

"anticipated_config": {
  "lead_stages": 2
}

How anticipated dispatch works

When a thermal unit has lead_stages = K, its dispatch commitment is split across two roles that appear at different stages:

• Decision stage (t): the LP at stage t sets the generation level that will be delivered K stages later. This decision variable is carried forward as state.
• Delivery stage (t + K): the LP at stage t + K receives the committed MW value as a fixed bound, reflecting that the generation level was locked in earlier.

Consider a 3-stage finite-horizon study with one anticipated thermal unit configured as "lead_stages": 2:

The null values in this table are not errors — they reflect the position of a stage within the horizon. At the first stages the commitment is being placed but has not yet matured; at the last stage the commitment has matured but there are no more future stages to place new decisions into.

For a lead_stages = 1 configuration on a 2-stage study, the coupling is simpler: the decision placed at stage 0 matures at stage 1. Stage 0 shows a non-null anticipated_decision_mw and null anticipated_committed_mw; stage 1 shows the reverse.

Pairing with initial_conditions.json

Because anticipated dispatch carries state across stages, every anticipated thermal unit must have a corresponding entry in past_anticipated_commitments in initial_conditions.json:

{
  "storage": [],
  "filling_storage": [],
  "past_anticipated_commitments": [
    {
      "thermal_id": 2,
      "values_mw": [0.0, 0.0]
    }
  ]
}

The values_mw array must have exactly lead_stages entries. The values are ordered chronologically from oldest to most recent: values_mw[0] corresponds to the oldest pending slot and values_mw[lead_stages - 1] to the most recent. For the example above with lead_stages = 2, the array has length 2. Supplying an array of a different length is a validation error.

Current limitation: every entry in values_mw must be 0.0. Pre-horizon commitments (generation dispatched outside the study horizon that delivers during the study) cannot be expressed in the current version. The semantic validator rejects any non-zero values_mw entry with an explicit error message naming the thermal id and the offending slot index. Set all entries to 0.0 when constructing initial_conditions.json for studies with anticipated thermal units.

Support for non-zero pre-horizon commitments is planned for a future release.

The past_anticipated_commitments key is optional in the JSON file and defaults to an empty list for studies that have no anticipated thermal units.

Reading the outputs

After a simulation run, three additional columns appear in simulation/thermals/scenario_id=NNNN/data.parquet for every thermal unit. See Output Format Reference for the full column schema. The anticipated-dispatch columns are:

Regular (non-anticipated) thermal units always have is_anticipated = false and both optional columns set to null. Rows for anticipated units have is_anticipated = true; the two nullable columns are populated according to each stage’s position relative to the decision and delivery windows described above.

Training output also records anticipated-dispatch state in training/dictionaries/state_dictionary.json. For each anticipated thermal unit, the dictionary contains one entry per slot index from 0 to K_max - 1 where K_max is the maximum lead_stages across all anticipated thermals in the study. Entries are emitted in slot-major order. Each entry has the following shape:

{
  "type": "anticipated_state",
  "entity_type": "thermal",
  "entity_id": 2,
  "slot_index": 0,
  "lead_stages": 2,
  "unit": "MW"
}

The lead_stages field reflects the plant’s own K_i, not the study-wide K_max. For a plant where K_i < K_max (mixed-K studies), entries with slot_index >= lead_stages are structural padding — those slots are deterministically zero and exist only to align the ring buffer to a uniform stride. Filter slot_index < lead_stages to keep only the active slots.

For a study with a single anticipated thermal unit (id = 2) configured as lead_stages = 2, the state dictionary contains exactly two such entries: one with slot_index = 0 and one with slot_index = 1 — both active, since K_max = lead_stages = 2. The slot index identifies which pending commitment the state variable tracks: slot 0 holds the oldest still-pending commitment and slot lead_stages - 1 holds the most recent.

Constraining commitments via generic constraints

The anticipated-commitment decision variable can be referenced directly in a generic constraint using the anticipated_decision(N) expression syntax, where N is the thermal unit’s id. This lets you cap, floor, or couple the MW level committed at each decision stage across multiple anticipated thermals.

{
  "constraints": [
    {
      "id": 1,
      "name": "cap_ant_t1",
      "expression": "anticipated_decision(2)",
      "sense": "<=",
      "slack": { "enabled": false }
    }
  ]
}

With a matching bound row in constraints/generic_constraint_bounds.parquet that sets bound = 20.0 at stage 0, the constraint limits the commitment placed at stage 0 for delivery 2 stages later to at most 20 MW.

Two semantic rules apply:

• anticipated_decision(N) must reference a thermal that carries an anticipated_config block. Referencing a non-anticipated thermal is a hard error (BusinessRuleViolation).
• thermal_generation(N) referencing an anticipated thermal emits a SemanticAmbiguity warning, because the variable is the per-block generation at the current stage and does not represent the forward commitment. Use anticipated_decision(N) when the intent is to constrain the commitment level.

For context on the constraint file format see Generic Constraints.

Validation Rules

Cobre’s layered validation pipeline checks the following conditions on thermal units. Violations are reported as error messages with the failing unit’s id.

Related Pages

• Anatomy of a Case — walks through the complete 1dtoy thermal definitions
• Building a System — step-by-step guide to writing thermals.json from scratch
• System Modeling — overview of all entity types and how they interact
• Case Format Reference — complete JSON schema for all input files

Network Topology

The electrical network in Cobre describes how generators and loads are connected and how power can move between regions. At the heart of the network model is the bus: a named node at which power balance must be maintained every stage and every load block. Generators inject power into buses; loads withdraw power from buses; transmission lines transfer power between buses.

The simplest possible model is a single-bus (copper-plate) system: one bus that aggregates all generation and all load into a single node. In a copper-plate model there are no flow limits, no transmission losses, and no geographical differentiation in price or dispatch. The 1dtoy template uses a single-bus configuration. This is the right starting point for system-level capacity planning studies where the internal transmission network is not the focus.

A multi-bus system introduces two or more buses connected by transmission lines. Lines impose flow limits between buses. When a line’s capacity is binding, each bus has its own locational marginal price, and the dispatch in one region cannot freely substitute for a deficit in another. Multi-bus models are appropriate when regional subsystems have constrained interconnections that influence dispatch, investment decisions, or price formation.

Buses

Every generator and every load must be attached to a bus. Buses are defined in system/buses.json under a top-level "buses" array.

JSON Schema

{
  "buses": [
    {
      "id": 0,
      "name": "SIN",
      "deficit_segments": [
        {
          "depth_mw": null,
          "cost": 1000.0
        }
      ]
    }
  ]
}

This is the complete buses.json from the 1dtoy example: one bus with a single unbounded deficit segment at 1000 $/MWh. Surplus-generation (excess) cost is not a per-bus field; it comes from the global penalties.json default (with per-stage overrides via the penalty-override path).

Core Fields

Bus Balance Constraint

For every bus b, every stage t, and every load block k, the LP enforces:

  generation_injected(b, t, k)
  + imports_from_lines(b, t, k)
  + deficit(b, t, k)
  = load_demand(b, t, k)
  + exports_to_lines(b, t, k)
  + excess(b, t, k)

deficit and excess are non-negative slack variables added to the LP objective at their respective penalty costs. The deficit slack makes the problem feasible when there is not enough generation to meet demand. The excess slack absorbs surplus generation when more power is produced than can be consumed or transmitted away.

Deficit Modeling

Deficit represents unserved load — demand that the solver cannot cover with available generation. The deficit cost is the Value of Lost Load (VoLL) from the solver’s perspective: the penalty the LP pays per MWh of unserved demand.

Deficit Segments

Rather than a single flat VoLL, Cobre models deficit costs as a piecewise-linear curve: a sequence of segments with increasing costs. The segments are cumulative. The first segment covers the first depth_mw MW of deficit at the lowest cost, the second segment covers the next depth_mw MW at a higher cost, and so on.

"deficit_segments": [
  { "depth_mw": 500.0, "cost": 1000.0 },
  { "depth_mw": null,  "cost": 5000.0 }
]

In this two-segment example, the first 500 MW of deficit costs 1000 $/MWh. Any deficit above 500 MW costs 5000 $/MWh. The final segment must have depth_mw: null (unbounded), which guarantees the LP can always find a feasible solution regardless of the generation shortfall.

Two-Tier Penalty Resolution

Deficit segment costs are resolved from the most specific to the most general source:

1. Bus-level override — the deficit_segments array inside the bus’s JSON object
2. Global default — the bus.deficit_segments section of penalties.json

When deficit_segments is omitted from a bus definition, Cobre uses the global default from penalties.json. This makes it easy to set a system-wide VoLL and then override it for specific buses with different reliability requirements.

Note: Deficit segment costs are not stage-varying. Only excess_cost supports per-stage overrides via penalty override files.

Choosing Deficit Costs

A tiered configuration uses a moderate cost for the first segment (to allow partial deficit in extreme scenarios without distorting the optimality cuts too much) and a higher cost for the unbounded final segment (to make full deficit a last resort). The relative ordering of segment costs matters more than their absolute values: each tier must be higher than the one before it, and the final tier must be high enough that the solver prefers dispatching any available generation over incurring unbounded deficit.

Setting the deficit cost too low relative to thermal generation costs will cause the solver to prefer deficit over building reserves, which misrepresents the cost of unserved energy. Setting the final tier very high can worsen LP conditioning.

Lines

Transmission lines connect pairs of buses and impose flow limits on power transfer between them. Lines are defined in system/lines.json under a top-level "lines" array. A single-bus system has an empty lines array.

JSON Schema

The following example shows a two-bus system with a single connecting line:

{
  "lines": [
    {
      "id": 0,
      "name": "North-South Interconnection",
      "source_bus_id": 0,
      "target_bus_id": 1,
      "entry_stage_id": null,
      "exit_stage_id": null,
      "capacity": {
        "direct_mw": 1000.0,
        "reverse_mw": 800.0
      },
      "losses_percent": 2.5,
      "exchange_cost": 1.0
    }
  ]
}

This line allows up to 1000 MW to flow from bus 0 to bus 1, and up to 800 MW in the reverse direction. A 2.5% transmission loss is applied to all flow. The exchange_cost is an optional per-line override of the global value from penalties.json — it is a regularization penalty, not a physical cost.

Core Fields

Exchange Cost Note

The exchange_cost is not a tariff or a physical transmission cost — it is a regularization penalty added to the LP objective to give the solver a strict preference between equivalent dispatch solutions. Without any exchange cost, the solver is indifferent between using or not using a lossless, uncongested line, which can cause oscillations between equivalent solutions across iterations.

A small exchange cost (0.5–2.0 $/MWh) breaks this degeneracy without meaningfully distorting the economic dispatch. The global default is set in penalties.json under line.exchange_cost. Per-line overrides are supported via the optional exchange_cost field on each line object, which takes precedence over the global default. Lines without an explicit exchange_cost use the global value.

Transmission Losses

When losses_percent is non-zero, the power arriving at the target bus is less than the power leaving the source bus. If bus A sends F MW to bus B over a line with 2.5% losses, then:

• Bus A’s balance sees an outflow of F MW
• Bus B’s balance sees an inflow of F * (1 - 0.025) = 0.975 * F MW

The lost power (0.025 * F MW) does not appear anywhere in the network — it represents heat dissipated in the conductor. From the LP’s perspective, losses increase the effective cost of transferring power: the source bus must generate more to deliver the same amount at the target bus.

Setting losses_percent: 0.0 models a lossless (superconductive) connection. This is appropriate for short, high-voltage DC links or for cases where transmission losses are not a modeling concern.

Single-Bus vs Multi-Bus

When to use a single-bus model

A single bus (copper-plate) is appropriate when:

• You are building an initial case and want to isolate dispatch economics from network effects
• Transmission constraints are not binding in the scenarios you are studying
• The system is geographically compact with ample interconnection capacity
• You are validating the stochastic model before adding network complexity

The 1dtoy template is a single-bus case. All generators and loads connect to bus 0 (SIN), and lines.json contains an empty array.

When to use a multi-bus model

A multi-bus model is appropriate when:

• Different regions have distinct generation mixes and load profiles
• Transmission capacity is a binding constraint that affects dispatch or pricing
• You need locational marginal prices for investment decisions or contract pricing
• You are modeling a system where curtailment of cheap generation (wind in one region, hydro in another) is caused by transmission congestion

Adding a second bus

To extend the 1dtoy template to two buses, add a second bus to buses.json:

{
  "buses": [
    { "id": 0, "name": "North" },
    { "id": 1, "name": "South" }
  ]
}

Then add a line to lines.json:

{
  "lines": [
    {
      "id": 0,
      "name": "North-South",
      "source_bus_id": 0,
      "target_bus_id": 1,
      "capacity": {
        "direct_mw": 500.0,
        "reverse_mw": 500.0
      },
      "losses_percent": 1.0,
      "exchange_cost": 1.0
    }
  ]
}

Assign each generator and load to the appropriate bus by setting its bus_id. When you run cobre validate, the validator will confirm that all bus_id references resolve to existing buses.

Validation Rules

Cobre’s layered validation pipeline checks the following conditions for buses and lines. Violations are reported as error messages with the failing entity’s id.

When a bus ID referenced by a generator does not exist in buses.json, the validator reports the error as:

reference error: thermal 2 references bus 99 which does not exist

Fix the bus_id or add the missing bus and re-run cobre validate until the exit code is 0.

Related Pages

• System Modeling — overview of all entity types and how they compose the LP
• Anatomy of a Case — walkthrough of the complete 1dtoy case including buses.json and lines.json
• Building a System — step-by-step guide to creating buses and lines from scratch
• Case Format Reference — complete JSON schema for all input files

Stochastic Modeling

Hydrothermal dispatch is inherently uncertain. Reservoir inflows depend on rainfall and snowmelt that cannot be known in advance, and electrical load varies in ways that are predictable in aggregate but noisy at any given moment. A dispatch policy that ignores uncertainty will systematically under-prepare for dry periods and over-commit thermal capacity in wet years.

Cobre addresses this by treating inflows and loads as stochastic processes. During training, the solver samples many scenario trajectories and builds a policy that performs well across the distribution of possible futures — not just for a single forecast. The stochastic layer is responsible for generating those scenario trajectories in a statistically sound, reproducible way.

The stochastic models are driven by historical statistics provided by the user in the scenarios/ directory of the case. If no scenarios/ directory is present, Cobre falls back to white-noise generation using only the stage definitions in stages.json. For any study with real hydro plants, providing historical inflow statistics gives the PAR(p) model the seasonal means, standard deviations, and AR structure it needs; without it, Cobre falls back to white noise, which does not reflect real inflow dynamics.

The scenarios/ Directory

The scenarios/ directory sits alongside the other input files in the case directory:

my_study/
  config.json
  stages.json
  ...
  scenarios/
    inflow_seasonal_stats.parquet
    load_seasonal_stats.parquet
    inflow_ar_coefficients.parquet    (when PAR model order > 0)
    inflow_history.parquet            (alternative to pre-computed stats)
    non_controllable_stats.parquet    (stochastic NCS availability)
    external_inflow_scenarios.parquet (per-class external inflow)
    external_load_scenarios.parquet   (per-class external load)
    external_ncs_scenarios.parquet    (per-class external NCS)
    correlation.json
    noise_openings.parquet            (user-supplied opening tree, optional)

The directory is optional. When it is absent, Cobre generates independent standard-normal noise at each stage for each hydro plant and scales it by a default standard deviation — effectively treating all uncertainty as white noise. This is sufficient for verifying a case loads correctly, but is not representative of real inflow dynamics.

When scenarios/ is present, Cobre reads the Parquet files and fits a Periodic Autoregressive (PAR(p)) model for each hydro plant and each bus. The fitted model generates correlated, seasonally-varying inflow and load trajectories that reflect the historical statistics you supply.

Inflow Statistics

inflow_seasonal_stats.parquet provides the seasonal distribution of historical inflows for every (hydro plant, stage) pair.

Schema

The file must contain exactly one row per (hydro_id, stage_id) pair. Every hydro plant defined in hydros.json must have a row for every stage defined in stages.json. The validator will reject the case if any combination is missing. The AR model order (number of lags) is determined from the inflow_ar_coefficients.parquet file when present, not from this file.

For the 1dtoy example, the file has 4 rows — one for each of the four monthly stages — for the single hydro plant UHE1 (hydro_id = 0).

Inspecting the file

# Polars
import polars as pl
df = pl.read_parquet("scenarios/inflow_seasonal_stats.parquet")
print(df)

# Pandas
import pandas as pd
df = pd.read_parquet("scenarios/inflow_seasonal_stats.parquet")
print(df)

-- DuckDB
SELECT * FROM read_parquet('scenarios/inflow_seasonal_stats.parquet');

# R with arrow
library(arrow)
df <- read_parquet("scenarios/inflow_seasonal_stats.parquet")
print(df)

Load Statistics

load_seasonal_stats.parquet provides the seasonal distribution of electrical demand at each bus. It drives the stochastic load model used during training and simulation.

Schema

One row per (bus_id, stage_id) pair is required. Every bus in buses.json must have a row for every stage. The load mean and standard deviation determine both the expected demand level and how much it varies across scenarios in each stage. A std_mw of 0.0 indicates deterministic load for that bus-stage pair.

The PAR(p) Model

PAR(p) stands for Periodic Autoregressive model of order p. It is the standard model for hydro inflow time series in long-term hydrothermal planning because inflows have two key properties the model captures well: seasonal patterns (wet seasons and dry seasons recur predictably each year) and autocorrelation (a wet month tends to be followed by another wet month, and vice versa).

What the AR order controls

The AR order (number of autoregressive lags) is determined by the inflow_ar_coefficients.parquet file. If the file is absent or contains no coefficients for a given (hydro_id, stage_id), the model defaults to white noise (order 0). When estimated from history, the order is selected automatically via PACF (see Estimation from History).

Order 0 — white noise. The inflow at each stage is drawn independently from a normal distribution with the specified mean and standard deviation. There is no memory between stages: knowing last month’s inflow tells you nothing about this month’s. This is the simplest setting and appropriate when you lack historical data to fit AR coefficients, or when the inflow series shows very little autocorrelation.

Order > 0 — periodic autoregressive. The inflow at each stage depends on the inflows at the preceding p stages, weighted by coefficients that reflect the seasonal autocorrelation structure. A wet period is followed by another wet period with the probability implied by the coefficients. Higher AR orders capture longer-range dependencies: order 1 captures month-to-month persistence, order 2 adds two-month memory, and so on. Monthly inflow series often show strong order-1 or order-2 autocorrelation; validate against your data.

AR coefficients file

When a non-trivial AR model is desired, Cobre requires an inflow_ar_coefficients.parquet file in the scenarios/ directory. This file contains the fitted AR coefficients in standardized form (as produced by the periodic Yule-Walker equations). The schema and the fitting procedure are documented in the Case Format Reference.

The 1dtoy example has no AR coefficients file, so all inflows use white noise (order 0).

When to use higher AR orders

In general:

• Use order 0 when historical data is short or when you want to establish a baseline with the simplest possible model.
• Use order 1 for most real hydro systems. Monthly inflows have strong one-month autocorrelation, and a first-order model captures the bulk of it.
• Use order 2 or higher when the inflow series shows multi-month persistence (common in systems with large upstream catchments or snowmelt storage). Validate with autocorrelation plots of your historical data.
• AR coefficients require std_m3s > 0 in the corresponding seasonal statistics — zero variance makes the model non-identifiable.

For the theoretical derivation of the PAR(p) model, see Stochastic Modeling and PAR(p) Autoregressive Models in the methodology reference.

Annual component (PAR(p)-A)

Some hydro systems show persistence that spans more than one or two months — the kind of year-long memory that a standard PAR(p) model cannot capture with a few short lags. The annual component extension (PAR(p)-A) addresses this by adding one extra term to the autoregressive equation: the rolling 12-month average of the inflow series, which acts as a slow-moving background signal.

When to use it. Enable the annual component when your historical inflow series displays multi-year persistence or when a standard PAR model leaves significant residual autocorrelation at annual lags. It is most useful for systems with large upstream catchments where wet or dry conditions accumulate over an entire hydrological year.

How to enable it. Set "order_selection": "pacf_annual" in the estimation block of config.json. No other configuration change is required; Cobre detects the setting and extends the estimation pipeline automatically.

What it produces. In addition to the standard estimation outputs, Cobre writes inflow_annual_component.parquet to the output directory. This file contains five columns — hydro_id, stage_id, annual_coefficient, annual_mean_m3s, and annual_std_m3s — one row per (hydro, stage) pair. The AnnualComponent type on InflowModel carries the same three values at runtime.

For the mathematical derivation of the PAR(p)-A model, see PAR(p) Autoregressive Models in the methodology reference.

Estimation from History

Instead of supplying pre-computed seasonal statistics in inflow_seasonal_stats.parquet, you can provide raw historical inflow observations and let Cobre estimate the PAR(p) parameters for you.

Input: inflow_history.parquet

Place inflow_history.parquet in the scenarios/ directory. The schema and required column types are documented in the Case Format Reference. Each row represents one historical observation of inflow at a given hydro plant and stage.

What Cobre estimates

When inflow_history.parquet is present, Cobre performs the following estimation steps automatically before building the scenario model:

1. Seasonal statistics — mean and standard deviation are computed from the historical observations for each (hydro plant, stage) pair. These replace the values you would otherwise provide in inflow_seasonal_stats.parquet.

2. History classification — Each (hydro plant, stage) observation series is classified before fitting. Constant or near-constant series, saturating caps, and series dominated by a single modal value are detected automatically and routed to a degenerate fit (order 0) so that downstream stages do not over-fit a structurally uninformative bucket. Series with more than 10% strictly negative observations are flagged for diagnostics but otherwise fitted normally.

3. AR order selection — Cobre evaluates candidate orders and selects the best fit per (hydro plant, stage) using the periodic partial autocorrelation function (PACF) with a 95% significance threshold. This avoids overfitting in series with little autocorrelation and captures meaningful persistence where it exists. Two extensions over the classical PACF rule cover the corner cases the classical rule leaves implicit: (i) a structural-zero short-circuit forces the model to order 0 when the lag-1 conditional FACP is exactly zero (degenerate covariance), and (ii) a minimum-order-1 default keeps an AR(1) base whenever the lag-1 FACP is well defined but no lag exceeds the threshold.

4. AR coefficients — Coefficients for the selected order are estimated by solving the periodic Yule-Walker matrix system, which correctly accounts for the non-Toeplitz covariance structure of periodic autoregressive processes.

5. Maceira-Damazio iterative order reduction — After the initial fit, the recursively-composed contributions of each lag through the periodic monthly chain are computed. If any contribution is negative — a signal that the lag’s cumulative influence opposes the expected persistence direction and would propagate as an unstable Benders cut — the offending season’s AR ceiling is reduced and the Yule-Walker fit is re-run at the new ceiling. The reduction iterates across all seasons until every season’s contribution recursion yields non-negative entries.

6. Spatial correlation — The contemporaneous correlation between hydro plants is estimated from the historical residuals after AR fitting. The resulting correlation matrix is used by the spectral noise generator in exactly the same way as a manually specified correlation.json.

History vs. pre-computed stats: choose one

inflow_history.parquet and inflow_seasonal_stats.parquet serve different roles in the inflow model. When only inflow_history.parquet is present (and inflow_seasonal_stats.parquet is absent), Cobre activates the estimation path and derives seasonal statistics and AR coefficients from the historical data. When inflow_seasonal_stats.parquet is present, it is used directly regardless of whether inflow_history.parquet is also present. Use history-based estimation when raw observations are available and you want Cobre to handle the statistical fitting; use pre-computed stats when you have already fitted the model externally or when you need precise control over the parameters.

Inflow Source Resolution

The PAR(p) inflow model is built from up to five files in scenarios/. Three of them — inflow_history.parquet, inflow_seasonal_stats.parquet, and inflow_ar_coefficients.parquet — drive path resolution: their presence/absence selects which of seven estimation paths Cobre executes. The remaining two — correlation.json and inflow_annual_component.parquet — layer orthogonally on top of that path.

Path-driver flags

The seven estimation paths

For each combination of (H, S, R), Cobre selects exactly one path and resolves each model output as follows:

¹ When order_selection ≠ "pacf_annual", the fitted annual component is empty even on paths 4 and 6. ² Path 5 explicitly discards any user-supplied inflow_annual_component.parquet. ³ History is not re-consumed on path 7; correlation falls back to identity unless correlation.json is supplied.

Invalid combinations collapse to Deterministic. Cases with R=1 but H=0 and S=0 fall back to row 1 — AR coefficients alone cannot drive estimation.

The two orthogonal layers

correlation.json — wins on every path

When correlation.json is present, Cobre uses it verbatim regardless of which of the seven paths runs. When absent, behavior splits:

• Estimation paths (4, 5, 6) — Σ is estimated from PAR residuals on H.
• Pass-through paths (1, 2, 3, 7) — Σ defaults to identity (independent noise).

This is the only file in the inflow stack that behaves as a true global override.

inflow_annual_component.parquet — only honored on pass-through paths

The user file is loaded by cobre-io and threaded into assemble_inflow_models, but the estimation paths overwrite it:

To ship a hand-crafted PAR-A annual file, supply S and R so the run lands on path 7 (UserProvidedAll).

Decision tree

                       ┌─ inflow_history.parquet present? ─┐
                       │                                   │
                      yes                                  no
                       │                                   │
        ┌─ seasonal_stats present? ─┐         ┌─ seasonal_stats present? ─┐
        │                           │         │                           │
       yes                          no       yes                          no
        │                           │         │                           │
 ┌── ar_coeffs? ──┐         ┌── ar_coeffs? ──┐ │                  → Deterministic (1)
 │                │         │                │ │
yes               no        yes              no│
 │                │         │                │ │
UserProvidedAll   Partial   UserAr           Full
     (7)         Estimation HistoryStats     Estimation
                    (6)         (5)              (4)
                                              ┌── ar_coeffs? ──┐
                                              │                │
                                             yes               no
                                              │                │
                                       UserProvidedNoHistory  UserStatsWhiteNoise
                                              (3)                  (2)

Practical recipes

The canonical implementation lives in crates/cobre-sddp/src/stochastic/estimation.rs — EstimationPath::resolve and the dispatch in estimate_from_history — with the per-path fitting logic in run_estimation (path 4), run_partial_estimation (path 6), and run_user_ar_estimation (path 5).

Multi-Resolution Studies

Cobre supports studies that mix stages at different temporal resolutions — for example, weekly stages within a month followed by monthly stages, or monthly stages transitioning to quarterly stages. Three mechanisms handle the stochastic implications of these layouts automatically.

Noise Sharing

When multiple SDDP stages share the same season_id (for example, four weekly stages all assigned to the April season), Cobre automatically shares PAR noise draws across those stages. Each group of same-season_id stages within a calendar period receives identical noise realizations, so that sub-monthly stages present a consistent inflow trajectory that is consistent with the monthly PAR model they were fitted from.

This sharing is controlled by a noise_group_id precomputed for each stage at case load time. Uniform monthly studies assign a unique group to each stage, so noise sharing has no effect and zero runtime overhead for standard studies. The mechanism is seed-deterministic: identical tree_seed values produce identical grouped noise assignments across runs and across MPI ranks.

Observation Aggregation

When the study uses a Custom cycle type with seasons of different durations (for example, 12 monthly seasons followed by 4 quarterly seasons), Cobre aggregates fine-grained historical observations into coarser season buckets before PAR fitting. A user who provides monthly inflow_history.parquet for a study that includes quarterly stages does not need to pre-aggregate the data: Cobre calls aggregate_observations_to_season internally using duration-weighted averaging to derive one observation per (hydro, season, year) at the appropriate resolution for each PAR model.

The coarsening direction is mandatory — aggregating monthly to quarterly is supported; disaggregating quarterly to monthly is not and returns an error. Monthly-uniform studies bypass this step entirely.

Lag Resolution Transition

For studies that transition from monthly to quarterly stages, the PAR lag state must change resolution at the boundary. During the monthly phase, each monthly inflow is accumulated into a ring buffer indexed by the downstream (quarterly) lag. When the first quarterly stage is reached, the ring buffer contains a complete set of duration-weighted monthly contributions and the lag state is rebuilt from those values.

This transition is implemented in StageLagTransition via downstream accumulation fields and is transparent to the LP and the cut representation. The transition introduces no state variables in the LP; the lag state is an internal solver variable updated in the hot-path functions. For uniform-resolution studies, the downstream accumulation fields are unused and the transition is a no-op.

For the full technical background — including the ring buffer design, frozen-lag semantics, and the noise group precomputation algorithm — consult the temporal-resolution-debts design document in docs/design/.

Correlation

Hydro plants that share a watershed tend to have correlated inflows: when the upstream basin receives heavy rainfall, all plants along the river benefit simultaneously. Ignoring this correlation can cause the optimizer to underestimate the risk of a system-wide dry spell. Correlation can also be configured between load buses and between NCS entities.

Default behavior: independent noise

When no correlation configuration is provided, Cobre treats each entity’s noise as independent of all others. Each entity draws its own noise realization at each stage without any coupling. This is the correct setting for the 1dtoy example, which has only one hydro plant.

Configuring spatial correlation

For multi-entity systems, Cobre supports spectral spatial correlation. A correlation model is specified in correlation.json in the case directory and defines named correlation groups, each with a symmetric correlation matrix. The spectral method (eigendecomposition + matrix square root) is preferred because it handles estimated matrices that are not strictly positive-definite and rank-deficient matrices naturally, without requiring the matrix to satisfy Cholesky conditions.

{
  "method": "spectral",
  "profiles": {
    "default": {
      "correlation_groups": [
        {
          "name": "basin_south",
          "entities": [
            { "type": "inflow", "id": 0 },
            { "type": "inflow", "id": 1 }
          ],
          "matrix": [
            [1.0, 0.7],
            [0.7, 1.0]
          ]
        }
      ]
    }
  }
}

Backward compatibility: "method": "cholesky" is accepted for existing case files and behaves identically to "spectral" as of v0.4.0.

Valid entity types

The "type" field in each entity reference must be one of:

• "inflow" — hydro inflow series (entity id matches id in hydros.json)
• "load" — stochastic load demand (entity id matches id in buses.json)
• "ncs" — non-controllable source availability (entity id matches id in non_controllable_sources.json)

Same-type enforcement

All entities within a single correlation group must share the same entity type. Mixing entity types — for example, placing an "inflow" entity and a "load" entity in the same group — is not supported and produces a StochasticError::InvalidCorrelation error at case load time. If you want to correlate inflow with load, define separate groups with the same correlation structure for each class.

Entities not listed in any group retain independent noise. Multiple profiles can be defined and scheduled to activate for specific stages (for example, using a wet-season correlation structure in January through March and a dry-season structure for the remaining months). Detailed correlation configuration documentation will be added with future multi-plant example cases.

Stochastic Load

Electrical load at each bus can be modeled as a stochastic process in addition to, or independently of, inflow uncertainty. When load_seasonal_stats.parquet is present in the scenarios/ directory, Cobre applies a noise model to bus demand during training and simulation.

How load noise works

Load noise uses the same PAR(p) framework as inflows. For each bus and each stage, Cobre draws a noise realization scaled by the bus’s mean_mw and std_mw values from load_seasonal_stats.parquet. This realization is then applied as a multiplicative factor on the base demand for that bus and stage: the sampled load replaces the deterministic demand value during scenario generation.

A bus with std_mw = 0 gets deterministic demand at each stage; a bus with std_mw > 0 gets demand noise proportional to the standard deviation.

Optional: deterministic loads without the file

load_seasonal_stats.parquet is entirely optional. When the file is absent, Cobre treats all bus demands as deterministic: the demand at each bus and stage is the fixed value from the case data, with no noise applied. This is the correct setting for studies where load uncertainty is negligible or where you want to isolate inflow uncertainty in isolation.

Stochastic NCS Availability

Non-controllable sources (wind, solar, run-of-river) can have stochastic available generation. When scenarios/non_controllable_stats.parquet is present, Cobre samples a per-scenario availability factor for each NCS entity and applies it to the entity’s max_generation_mw.

Schema

The file provides one row per (ncs_id, stage_id) pair:

How it works

For each forward and backward pass scenario, Cobre draws a standard normal noise value η from the opening tree and computes:

A_r = max_generation_mw × clamp(mean + std × η, 0, 1)

The result A_r is then multiplied by the per-block factor from scenarios/non_controllable_factors.json (default 1.0) to produce the final NCS column upper bound:

col_upper = A_r × block_factor

With std = 0, the availability is deterministic at mean × max_generation_mw, making the stochastic pipeline a strict generalization of the deterministic ncs_bounds.parquet approach.

Optional: deterministic NCS without the file

When non_controllable_stats.parquet is absent, NCS availability is deterministic: the LP column upper bound comes from constraints/ncs_bounds.parquet (or defaults to max_generation_mw). No per-scenario variation occurs.

Seeds and Reproducibility

num_scenarios in stages.json

Each stage in stages.json has a num_scenarios field that controls how many scenario branches are pre-generated for the opening scenario tree used during the backward pass. A larger value gives the backward pass more diverse inflow realizations to evaluate cuts against, at the cost of a proportionally larger opening tree in memory. For the 1dtoy example this is set to 10. Larger values increase scenario-tree diversity at proportional memory cost.

forward_passes in config.json

The forward_passes field in config.json controls how many scenario trajectories are sampled during each training iteration’s forward pass. This is distinct from num_scenarios: the forward pass draws new trajectories on each iteration using a deterministic per-iteration seed, while num_scenarios controls the pre-generated backward-pass tree.

Dual-Seed Architecture

Cobre uses two independent seeds, each controlling a different part of the stochastic pipeline:

training.tree_seed in config.json — the base seed for the opening scenario tree. This seed governs all backward-pass openings and, when the sampling scheme is in_sample (the default), also governs the forward-pass scenario selection. When the same case is run with the same tree_seed, the opening tree is bitwise identical across runs, regardless of the number of MPI ranks.

training.scenario_source.seed in config.json — the forward seed used when the sampling scheme is out_of_sample, historical, or external. This seed controls the noise generated on-the-fly during each forward pass. It is completely independent of tree_seed: changing it does not affect the backward-pass tree, and changing tree_seed does not affect the forward pass.

tree_seed is optional: when omitted, Cobre uses a default seed of 42 (deterministic but arbitrary). scenario_source.seed is required when any class uses out_of_sample, historical, or external; it is unused (and may be omitted) when all classes use in_sample. To make a run fully reproducible, specify both seeds explicitly:

// config.json
{
  "training": {
    "tree_seed": 42,
    "forward_passes": 50,
    "stopping_rules": [{ "type": "iteration_limit", "limit": 200 }],
    "scenario_source": {
      "seed": 99,
      "inflow": { "scheme": "out_of_sample" },
      "load": { "scheme": "in_sample" },
      "ncs": { "scheme": "in_sample" }
    }
  }
}

When tree_seed is set to null in config.json, Cobre uses a default seed of 42, producing a deterministic opening tree. Set tree_seed explicitly to make the choice intentional. For scenario_source.seed, a null value is only valid when all classes use in_sample (where no forward-pass noise is generated); omitting it with any other scheme triggers a validation error.

Noise Methods

The sampling_method field in each stage entry of stages.json controls how noise vectors are generated within that stage when building the opening scenario tree. This is orthogonal to the sampling scheme (see Sampling Schemes below), which controls where the forward-pass noise comes from. The noise method controls the algorithm; the sampling scheme controls the source.

All methods produce standardized η ~ N(0,1) vectors. Everything downstream — the spectral correlation transform, the PAR model, and the LP constraint patching — is identical regardless of which method produced the noise. Switching from SAA to Sobol is a one-field configuration change.

The default method is "saa" when sampling_method is omitted.

SAA — Sample Average Approximation

SAA (Sample Average Approximation) is pure Monte Carlo sampling. Each opening draws an independent sequence of standard-normal values from a Pcg64 generator seeded deterministically from the stage and opening index. There is no coordination between openings; each is drawn without knowledge of the others.

SAA is the simplest and most general method. It works for any dimension count and any branching factor, and it has no restrictions on num_scenarios. Use SAA as your baseline when you are uncertain which method to choose, or when your branching factor is small (fewer than 50 scenarios per stage).

Configure SAA by setting "sampling_method": "saa" (or by omitting the field, since SAA is the default).

LHS — Latin Hypercube Sampling

LHS (Latin Hypercube Sampling) is stratified sampling. For a stage with N = num_scenarios openings, each dimension is divided into N equal-probability strata [k/N, (k+1)/N) for k = 0, …, N-1. Exactly one sample is placed within each stratum, and a Fisher-Yates shuffle independently assigns strata to openings for every dimension. The result is marginal uniformity: when you project all N noise vectors onto any single dimension, the resulting samples cover the entire range of the standard-normal distribution uniformly, with no stratum left empty.

LHS reduces the variance of sample-average estimates compared to SAA for the same N, which typically means a better-converged backward-pass cut approximation for the same computational budget. It is well-suited to moderate branching factors and works for any dimension count.

Configure LHS by setting "sampling_method": "lhs" in the stage entry.

QMC-Sobol

QMC-Sobol uses Sobol quasi-random sequences, which are low-discrepancy sequences that fill the unit hypercube more evenly than independent random draws. Cobre implements the Joe-Kuo 2010 direction number dataset with Matousek linear scrambling. The scrambling applies an affine transformation x' = a·x + b (mod 2^32) with seed-derived parameters to each dimension, breaking correlations between dimensions while preserving the low-discrepancy property. The batch generator uses a Gray-code recurrence for O(1) updates per point.

QMC-Sobol provides a faster convergence rate than both SAA and LHS for smooth integrands, meaning that a smaller branching factor can achieve equivalent policy quality. The convergence benefit is strongest when num_scenarios is a power of 2 (32, 64, 128, 256, …), because Sobol sequences have optimal 2-equidistribution properties at powers of 2. You can use other values of num_scenarios, but the theoretical convergence advantage is reduced.

QMC-Sobol supports up to 21,201 dimensions. If your system dimension (the total number of hydro plants, load buses, and NCS entities) exceeds 21,201, Cobre will return an error and refuse to run. In practice, this limit is never reached in hydrothermal planning models.

Configure QMC-Sobol by setting "sampling_method": "qmc_sobol".

QMC-Halton

QMC-Halton uses Halton sequences, another family of low-discrepancy sequences. Each dimension uses a distinct prime base: dimension 1 uses base 2, dimension 2 uses base 3, dimension 3 uses base 5, and so on. The prime bases are computed at initialization time using the sieve of Eratosthenes (sieve_primes). Cobre applies Owen-style random digit scrambling to each dimension: a random permutation table is applied to each digit position in each dimension, breaking the correlation artifacts that affect plain Halton sequences at high dimensions (sometimes called the “Halton curse”). Permutation tables are derived deterministically from the stage seed.

QMC-Halton has no dimension limit — it can handle arbitrarily many dimensions by sieving as many primes as needed. This makes it a good alternative to QMC-Sobol for very high-dimensional cases, though in practice the dimension limit of QMC-Sobol (21,201) is rarely reached. The convergence properties of QMC-Halton are similar to QMC-Sobol but the scrambling approach differs; some integrands favor one over the other.

Configure QMC-Halton by setting "sampling_method": "qmc_halton".

HistoricalResiduals

HistoricalResiduals uses standardized noise values derived from actual historical inflow observations rather than from synthetic distributions. For each opening in the stage, Cobre selects a historical year (a “window”) from the HistoricalScenarioLibrary and reads the pre-computed PAR residuals for that year and stage directly into the noise vector. No random number generator is invoked; the noise is determined entirely by which historical year is selected.

This method requires inflow_history.parquet in the scenarios/ directory. Cobre inverts the PAR(p) model for every valid (window, stage, hydro) triple at case load time, computing:

eta = (obs - mu - sum(psi[l] * lag[l])) / sigma

where obs is the raw historical inflow, mu and sigma are the seasonal mean and standard deviation, and psi[l] * lag[l] is the AR contribution from the preceding l lags. The resulting eta values are stored once and reused across training runs.

Window selection. For each opening, the window index is chosen deterministically using a hash of the base seed, the opening index, and the stage ID:

window_idx = derive_opening_seed(seed, opening, stage) % n_windows

Selection is with replacement, so the same historical year can appear in multiple openings of the same stage. When n_windows < branching_factor, the opening count for that stage is clamped to n_windows and Cobre emits a warning. Having fewer historical windows than the branching factor is acceptable — it means the opening tree samples the same years more than once — but the policy quality is limited by the size of the historical record.

Correlation handling. HistoricalResiduals skips the spectral correlation step that all other noise methods apply after generation. Because each window corresponds to a real historical year, the joint distribution of eta values across hydro plants already reflects the empirical spatial correlation from that year. Applying a synthetic correlation transform on top of real residuals would distort rather than improve the representation.

Non-hydro slots. Only the hydro segment of the noise vector is filled from the historical library. Load and NCS slots are zeroed; those entities use their own noise sources as configured by the sampling scheme.

Configure HistoricalResiduals by setting "sampling_method": "historical_residuals" in the stage entry of stages.json:

{
  "id": 0,
  "start_date": "2024-01-01",
  "end_date": "2024-02-01",
  "blocks": [{ "id": 0, "name": "SINGLE", "hours": 744 }],
  "num_scenarios": 50,
  "sampling_method": "historical_residuals"
}

Use HistoricalResiduals when you want the backward-pass opening tree to be grounded in real historical sequences rather than synthetic draws. This is particularly useful when the historical record contains unusual events (severe droughts, extreme wet years) that are difficult to represent faithfully with a parametric distribution.

Selective (Reserved)

The "selective" method is reserved for future use. It is intended to support representative scenario selection (clustering-based methods), but the required infrastructure is not yet implemented. If you configure a stage with "sampling_method": "selective", Cobre will return an error for the opening tree generator. In the out-of-sample forward pass, it falls back to SAA and emits a diagnostic warning.

Comparison

The following diagrams illustrate how each method distributes samples. SAA shows random clumps and gaps; LHS guarantees one sample per stratum; Sobol and Halton fill the space with low-discrepancy sequences.

Per-Stage Method Configuration

The sampling_method field is set per stage in stages.json. Different stages in the same study can use different methods. This is useful when you want a high-quality low-discrepancy method for the near-term stages (where policy quality matters most) while using the simpler SAA for distant stages where the investment decisions are less sensitive to sampling quality.

The following example configures a two-stage study where stage 0 uses LHS and stage 1 uses QMC-Sobol:

{
  "policy_graph": { "type": "finite_horizon", "annual_discount_rate": 0.12 },
  "stages": [
    {
      "id": 0,
      "start_date": "2024-01-01",
      "end_date": "2024-02-01",
      "blocks": [{ "id": 0, "name": "SINGLE", "hours": 744 }],
      "num_scenarios": 100,
      "sampling_method": "lhs"
    },
    {
      "id": 1,
      "start_date": "2024-02-01",
      "end_date": "2024-03-01",
      "blocks": [{ "id": 0, "name": "SINGLE", "hours": 696 }],
      "num_scenarios": 128,
      "sampling_method": "qmc_sobol"
    }
  ]
}

Mixed configurations are fully supported. Cobre applies each stage’s method independently when building the opening tree.

Sampling Schemes

The sampling scheme controls where the forward-pass noise comes from. This is a different concept from the noise method: the noise method controls the algorithm used to generate noise vectors for the opening tree, while the sampling scheme controls whether the forward pass reuses the pre-generated tree, generates fresh noise on-the-fly, replays historical observations, or reads from an externally supplied file.

Each entity class — inflow, load, and NCS — independently specifies its forward-pass noise source. The sampling scheme is configured in config.json under training.scenario_source using a per-class format:

// config.json
{
  "training": {
    "forward_passes": 50,
    "stopping_rules": [{ "type": "iteration_limit", "limit": 200 }],
    "scenario_source": {
      "seed": 42,
      "inflow": { "scheme": "in_sample" },
      "load": { "scheme": "in_sample" },
      "ncs": { "scheme": "in_sample" }
    }
  }
}

All three class keys ("inflow", "load", "ncs") default to "in_sample" when absent. The "seed" field is shared across all classes and is required when any class uses "out_of_sample", "historical", or "external".

Independent simulation sampling: simulation.scenario_source in config.json can be set independently of training.scenario_source. When simulation.scenario_source is absent, the simulation phase falls back to the scheme configured under training.scenario_source. This lets you train with in-sample noise and simulate with out-of-sample or historical noise without changing the training configuration.

InSample (default)

With "scheme": "in_sample", the forward pass reuses the pre-generated opening tree. At each (iteration, scenario, stage) triple, the solver selects one opening from the tree using a deterministic per-iteration hash derived from tree_seed. The backward pass and the forward pass see the same set of noise realizations: the same scenarios that were used to build cuts are the scenarios against which the forward trajectories are evaluated.

InSample is the default when training.scenario_source is absent from config.json. It is simple to configure, requires no additional seed, and is appropriate for most studies. The main limitation is that the forward pass cannot evaluate the policy on noise realizations outside the opening tree, which can lead to an optimistic bias when the branching factor is small.

OutOfSample

With "scheme": "out_of_sample", the forward pass generates fresh noise on-the-fly at each (iteration, scenario, stage) triple. The fresh noise is drawn from the same distribution as the opening tree but is independent of it — the forward pass never looks at the tree. Each call derives a unique noise vector from training.scenario_source.seed, the iteration index, the scenario index, and the stage ID. The per-stage sampling_method controls which algorithm (SAA, LHS, QMC-Sobol, or QMC-Halton) is used to generate the fresh noise.

OutOfSample requires training.scenario_source.seed to be set. Configure it as follows:

// config.json
{
  "training": {
    "forward_passes": 50,
    "stopping_rules": [{ "type": "iteration_limit", "limit": 200 }],
    "scenario_source": {
      "seed": 99,
      "inflow": { "scheme": "out_of_sample" },
      "load": { "scheme": "in_sample" },
      "ncs": { "scheme": "in_sample" }
    }
  }
}

OutOfSample is preferred when you want to evaluate policy quality on scenarios that are independent of the scenarios used to build the policy. This avoids the in-sample optimism that arises with small branching factors, where the policy has effectively “seen” all the noise realizations during training. OutOfSample is especially useful during simulation, where you want an unbiased estimate of the policy’s expected cost on new scenarios.

Historical

With "scheme": "historical", the forward pass replays standardized noise derived from historical inflow observations stored in inflow_history.parquet. This allows you to evaluate the policy against actual historical sequences — what would the policy have done during the drought of 1953 or the wet year of 1974?

Historical sampling applies only to the inflow class. The load and NCS classes configure their own schemes independently and are unaffected by the inflow class using Historical.

Window discovery

A “window” is a starting year y for which every hydro plant in the study has a complete sequence of historical observations covering the entire study period (plus the PAR model lag order of pre-study seasons needed to seed the AR state). Cobre discovers valid windows by scanning inflow_history.parquet and checking completeness for every candidate starting year.

When historical_years is absent from training.scenario_source, Cobre auto-discovers all valid windows from the history file. If the history file covers years 1940 through 2010 and the study spans 12 monthly stages, then every year for which the history is complete (accounting for the required pre-window lag seasons) becomes a valid window.

Configuring historical_years

To restrict the pool of candidate windows, set historical_years in scenario_source. Two forms are supported:

Explicit list — specify the exact starting years to use:

// config.json
{
  "training": {
    "forward_passes": 50,
    "stopping_rules": [{ "type": "iteration_limit", "limit": 200 }],
    "scenario_source": {
      "seed": 7,
      "inflow": { "scheme": "historical" },
      "load": { "scheme": "in_sample" },
      "ncs": { "scheme": "in_sample" },
      "historical_years": [1940, 1953]
    }
  }
}

Inclusive range — specify a contiguous span of starting years:

// config.json
{
  "training": {
    "forward_passes": 50,
    "stopping_rules": [{ "type": "iteration_limit", "limit": 200 }],
    "scenario_source": {
      "seed": 7,
      "inflow": { "scheme": "historical" },
      "load": { "scheme": "in_sample" },
      "ncs": { "scheme": "in_sample" },
      "historical_years": { "from": 1940, "to": 2010 }
    }
  }
}

In both forms, Cobre validates each candidate year against the history file and silently discards years for which the data is incomplete. If no valid windows remain after filtering, Cobre returns a StochasticError::InsufficientData error. When the number of valid windows is smaller than forward_passes, a diagnostic warning is emitted and windows are repeated across forward passes.

Lag seeding (apply_initial_state)

For PAR models with order > 0, the first stage of each forward pass requires historical inflow values from the stages immediately before the window’s start year — the “pre-study” lags. Historical sampling uses the raw historical observations at those pre-window stages directly as the PAR state vector. This means the AR dynamics of the first forward stage are initialized from the real historical record rather than from a generated value, preserving the continuity invariant between pre-window history and the replayed scenario.

How the HistoricalScenarioLibrary is used

At case load time, Cobre constructs a HistoricalScenarioLibrary by inverting the PAR(p) model for every valid (window, stage) pair: it computes the standardized noise value η = (obs − deterministic_base − Σ ψ[ℓ]·lag[ℓ]) / σ using the raw historical inflow as lags. The resulting eta values are stored in a flat buffer indexed by (window, stage, hydro). During the forward pass, the ClassSampler::Historical variant selects a window deterministically from the seed and iteration/scenario indices, then retrieves the pre-computed eta slice for each stage without any per-step recomputation.

Scenario selection: random without replacement

Historical, External, and LHS all use the same underlying mechanism to select items from a pool without repetition: a seed-derived Fisher-Yates permutation. Each forward-pass scenario gets a unique window (or external trajectory, or LHS stratum) within each round, with no inter-worker communication required.

External

With "scheme": "external", the forward pass reads pre-generated scenario realizations from per-class Parquet files in the scenarios/ directory. This enables integration with external scenario generation tools — for example, a climate model, a market forecast engine, or a bespoke sampling framework — and injects their output directly into the Cobre forward pass.

Each entity class that uses External sampling requires its own file. The three files and their schemas are:

external_inflow_scenarios.parquet

external_load_scenarios.parquet

external_ncs_scenarios.parquet

External standardization

Cobre does not use the raw values from external files directly. Before the forward pass can use them, each value is converted to the same standardized noise space (eta) that the PAR model and the opening tree use internally:

• Inflow — full PAR(p) inversion via solve_par_noise: the observed value is converted to η = (obs − deterministic_base − Σ ψ[ℓ]·lag[ℓ]) / σ using the fitted PAR model coefficients and seasonal statistics.
• Load — simple z-score normalization: η = (value − mean) / std using the mean_mw and std_mw from load_seasonal_stats.parquet.
• NCS — simple z-score normalization: η = (value − mean) / std using the mean and std from non_controllable_stats.parquet.

The resulting eta values are stored in an ExternalScenarioLibrary — one per class — and the ClassSampler::External variant retrieves them by (stage, scenario) index during the forward pass.

Configuring External sampling

// config.json
{
  "training": {
    "forward_passes": 50,
    "stopping_rules": [{ "type": "iteration_limit", "limit": 200 }],
    "scenario_source": {
      "seed": 1,
      "inflow": { "scheme": "external" },
      "load": { "scheme": "external" },
      "ncs": { "scheme": "in_sample" }
    }
  }
}

Each class is configured independently. In the example above, inflow and load use external files while NCS uses the in-sample opening tree.

User-Supplied Opening Trees

By default, Cobre generates the backward-pass opening tree internally using SipHash-derived seeds and the spatial correlation spectral factor. If you need to supply your own noise realizations — for cross-tool comparison, sensitivity analysis, or round-trip replay — you can place scenarios/noise_openings.parquet in the case directory before running.

When the file is present, Cobre loads the opening tree from it instead of calling the internal generator. When the file is absent, the default generator runs as usual.

Schema

The file has exactly four columns:

Entity ordering

The entity_index column follows the system dimension convention:

1. Hydro entities, sorted by canonical ID (ascending)
2. Load buses, sorted by canonical ID (ascending)
3. NCS entities, sorted by canonical ID (ascending)

This matches the ordering used by Cobre’s internal opening tree generator. The file stores only indices, not entity identifiers, so an incorrect ordering causes silent value misassignment rather than a schema error. Double-check the entity ordering when constructing the file externally.

Use cases

• Cross-tool comparison. Generate a set of noise realizations in an external tool and inject them into Cobre to compare policy quality on identical scenarios.
• Sensitivity analysis. Construct an extreme scenario (for example, all hydros at minimum inflow for the entire study) and evaluate how the policy responds.
• Round-trip replay. Export the opening tree that Cobre used in a training run with exports.stochastic: true in config.json, copy output/stochastic/noise_openings.parquet to scenarios/, and re-run to reproduce the exact same backward-pass context. See Exporting Stochastic Artifacts for the complete workflow.

Interaction with tree_seed

The training.tree_seed field in config.json remains required even when a user-supplied opening tree is present. The opening tree and forward-pass noise are independent: tree_seed governs the forward-pass scenario sampling performed by sample_forward(), which uses SipHash seeds derived independently of the opening tree. Supplying a custom opening tree has no effect on forward-pass noise.

Limitations

• Partial-stage override is not supported. You must supply openings for all study stages. If you want to replace a subset of stages while keeping the rest internally generated, you must supply a complete tree and duplicate the internally generated values for the unmodified stages.
• User-supplied noise is used as-is. The spectral spatial correlation factor is not applied again. You are responsible for any spatial correlation structure encoded in the values you supply.

The file schema and validation rules are documented in the noise_openings.rs module.

Inflow Non-Negativity

Normal distributions used in PAR(p) models have unbounded support: even with a positive mean, there is a non-zero probability of drawing a negative noise realisation that, after applying the AR dynamics, produces a negative inflow value. Negative inflow has no physical meaning and, if uncorrected, would violate water balance constraints in the LP.

Cobre provides two available methods for handling negative inflow realisations, controlled by the modeling.inflow_non_negativity.method field in config.json.

Penalty method (default)

The penalty method adds a high-cost slack variable to each water balance row. When the solver encounters a scenario where the inflow would be negative, it draws on this virtual inflow at the penalty cost rather than violating the balance constraint. The penalty cost is configurable via the inflow_non_negativity field in the case configuration; the default keeps it high enough that the slack is used only when necessary.

In practice, the penalty is rarely activated in well-specified studies. It acts as a backstop for low-probability tail realisations. It is the default method.

Truncation method

Available since v0.1.1, the truncation method evaluates the full inflow value before constructing the LP and clamps any negative result to zero. The water balance row receives the clamped inflow directly; no slack variable is added and no penalty cost is incurred. To enable truncation, set the method field in config.json:

{
  "modeling": {
    "inflow_non_negativity": {
      "method": "truncation"
    }
  }
}

Truncation eliminates the penalty cost for tail realisations at the expense of introducing a small bias: scenarios where the true inflow would be slightly negative are treated as zero-inflow scenarios, which is conservative but physically interpretable. For most well-specified studies, both methods produce similar results because negative realisations are rare.

Truncation with penalty

A combined truncation with penalty method is available, configured by setting method to "truncation_with_penalty" in config.json:

{
  "modeling": {
    "inflow_non_negativity": {
      "method": "truncation_with_penalty"
    }
  }
}

This method applies both truncation and a bounded slack variable: the inflow is clamped to zero and a slack penalised by penalties.json::hydro.inflow_nonnegativity_cost is added, providing a smooth backstop for extreme tail realisations.

For the mathematical theory behind all three methods, see the Inflow Non-Negativity page in the methodology reference, or Oliveira et al. (2022), Energies 15(3):1115.

Temporal Resolution and PAR

The PAR(p) model is parameterized by season_id. Every stage in stages.json carries a season_id that selects its PAR parameters — mean (mu), standard deviation (sigma), and autoregressive coefficients (psi) — from the fitted model. When multiple stages share the same season_id, they receive identical stochastic parameters.

This design choice reflects a fundamental data-resolution constraint. If the historical observations are at monthly resolution, the fitted PAR parameters describe the distribution of monthly inflows. Applying those parameters to sub-monthly stages (for example, four weekly stages all assigned season_id = 3 for April) does not create additional information — it reproduces the same monthly-scale noise for each week.

Why sub-monthly stages share noise. Sub-monthly stages sharing a season_id receive the same PAR parameters and, for the HistoricalResiduals noise method, the same noise realizations. This is not a limitation of the implementation — it is an honest representation of what monthly-resolution data can tell you. Monthly history cannot support independent weekly noise draws; doing so would fabricate variability that does not exist in the record. Users who need true sub-monthly variability should supply it through External scenarios from a dedicated short-term model.

Recommended pattern for weekly decision granularity. When weekly dispatch decisions matter but external weekly scenarios are not available, the recommended approach is to use a monthly SDDP stage with chronological blocks rather than multiple weekly SDDP stages:

{
  "id": 0,
  "start_date": "2024-01-01",
  "end_date": "2024-02-01",
  "season_id": 0,
  "blocks": [
    { "id": 0, "name": "WEEK1", "hours": 168 },
    { "id": 1, "name": "WEEK2", "hours": 168 },
    { "id": 2, "name": "WEEK3", "hours": 168 },
    { "id": 3, "name": "WEEK4", "hours": 240 }
  ],
  "num_scenarios": 50
}

One monthly stage with four weekly chronological blocks provides weekly dispatch granularity in the LP while keeping one noise realization per month — consistent with the data resolution. The stage boundary carries a single Benders cut at monthly resolution. This avoids both the fabricated weekly variability and the lag-accumulation complications that arise with four independent weekly SDDP stages.

For the full technical background on temporal resolution design, including applicability matrices for different study patterns, consult the temporal-resolution-debts design document in docs/design/.

Validation Rules

Cobre validates the consistency of temporal resolution settings at case load time. The following rules apply when season_definitions is present in stages.json and inflow_history.parquet is the active estimation source.

Rule 27 (error): season_id range coverage. Every stage season_id must reference a season defined in season_definitions. If a stage has season_id = 5 but the season map only defines seasons 0–11, Cobre emits a BusinessRuleViolation error and refuses to build the stochastic model.

• Triggers when: a stage’s season_id is not present in season_definitions.seasons[].id.
• Resolution: Add the missing season to season_definitions, or correct the season_id in the stage entry.

Rule 28 (warning): observation coverage. When a season has no inflow observations in inflow_history.parquet and the inflow sampling scheme is not external, PAR estimation for that season will have no data. Cobre emits a ModelQuality warning. This is not an error because External-only seasons legitimately have no history requirement.

• Triggers when: a season defined in season_definitions has zero observations in inflow_history.parquet and the inflow scheme is not external.
• Resolution: Provide historical observations for the season, switch the inflow scheme to external for that study, or remove the season if it is unused.

Rule 29 (error): resolution consistency. All stages sharing the same season_id must have durations within 7 days of each other. A stage group where one member is a monthly stage (28–31 days) and another is a quarterly stage (89–92 days) indicates conflicting PAR model parameterisations for the same season, and Cobre emits a BusinessRuleViolation error.

• Triggers when: the maximum and minimum durations among stages in the same season_id group differ by more than 7 days.
• Resolution: Assign distinct season_id values to stages at different temporal resolutions (e.g., monthly stages use IDs 0–11, quarterly stages use IDs 12–15 in a custom SeasonMap).

Rule 30 (warning): contiguity. A season defined in season_definitions but not referenced by any stage will have no PAR parameters and no observations. Cobre emits a ModelQuality warning for each such season. This catches accidental gaps in the season ID space (e.g., defining seasons 0–11 but stages only using 0–9).

• Triggers when: a season defined in season_definitions is not referenced by any stage’s season_id.
• Resolution: Remove the unreferenced season from season_definitions, or assign it to at least one stage.

Rule 31 (error): observation-to-season alignment. If any (hydro_id, season_id, year) triple has more than one observation in inflow_history.parquet, the observation data has finer temporal resolution than the season definitions. The PAR estimation pipeline expects exactly one observation per (hydro, season, year). Multiple observations distort parameter estimates. Cobre emits a BusinessRuleViolation error.

• Triggers when: a hydro plant has two or more observations in inflow_history.parquet that map to the same (season_id, year) pair (for example, daily observations paired with monthly seasons, or two monthly entries for the same hydro-season-year).
• Resolution: Aggregate the finer-resolution observations to match the season resolution before providing the file. Provide exactly one row per (hydro_id, season_id, year) in inflow_history.parquet.

Related Pages

• Anatomy of a Case — introductory walkthrough of the scenarios/ directory and Parquet schemas
• Configuration — full documentation of config.json fields including tree_seed and forward_passes
• cobre-stochastic — internal architecture of the stochastic crate: PAR preprocessing, spectral correlation, opening tree, and seed derivation

Configuration

All runtime parameters for cobre run are controlled by config.json in the case directory. This page documents every section and field.

Minimal Config

{
  "training": {
    "forward_passes": 50,
    "stopping_rules": [{ "type": "iteration_limit", "limit": 100 }]
  }
}

All other sections are optional with defaults documented below.

training

Controls the SDDP training phase.

Mandatory Fields

Optional Fields

For the per-class scenario_source configuration, see the scenario_source sub-section below and Stochastic Modeling.

scenario_source

Controls where the forward-pass noise comes from for each entity class during training. When absent, all classes default to in_sample (reusing the pre-generated opening tree).

Valid values for "scheme": "in_sample", "out_of_sample", "historical", "external".

Example — out-of-sample inflow with in-sample load and NCS:

{
  "training": {
    "tree_seed": 42,
    "forward_passes": 50,
    "stopping_rules": [{ "type": "iteration_limit", "limit": 200 }],
    "scenario_source": {
      "seed": 99,
      "inflow": { "scheme": "out_of_sample" },
      "load": { "scheme": "in_sample" },
      "ncs": { "scheme": "in_sample" }
    }
  }
}

See Stochastic Modeling — Sampling Schemes for a full description of each scheme and the historical_years field.

Stopping Rules

Each entry in stopping_rules is a JSON object with a "type" discriminator.

iteration_limit

Stop after a fixed number of training iterations.

{ "type": "iteration_limit", "limit": 200 }

time_limit

Stop after a wall-clock time budget is exhausted.

{ "type": "time_limit", "seconds": 3600.0 }

bound_stalling

Stop when the relative improvement in the lower bound falls below a threshold.

{ "type": "bound_stalling", "iterations": 20, "tolerance": 0.0001 }

simulation

Stop when both the lower bound and a Monte Carlo policy cost estimate have stabilized. Periodically runs a batch of forward simulations and compares the result against previous evaluations.

{
  "type": "simulation",
  "replications": 100,
  "period": 10,
  "bound_window": 5,
  "distance_tol": 0.01,
  "bound_tol": 0.0001
}

stopping_mode

When multiple stopping rules are listed, stopping_mode controls how they combine:

• "any" (default): stop when any one rule is satisfied.
• "all": stop only when every rule is satisfied simultaneously.

{
  "training": {
    "forward_passes": 50,
    "stopping_mode": "all",
    "stopping_rules": [
      { "type": "iteration_limit", "limit": 500 },
      { "type": "bound_stalling", "iterations": 20, "tolerance": 0.0001 }
    ]
  }
}

simulation

Controls the optional post-training simulation phase.

When simulation.enabled is false or num_scenarios is 0, the simulation phase is skipped entirely.

Example:

{
  "simulation": {
    "enabled": true,
    "num_scenarios": 1000
  }
}

scenario_source

Controls where the forward-pass noise comes from during the simulation phase. When absent, simulation falls back to the scheme configured under training.scenario_source. This allows you to train with in-sample noise and simulate with a different scheme (for example, out-of-sample or historical) without modifying the training configuration.

The fields are identical to training.scenario_source:

Example — simulate with out-of-sample inflow while training uses in-sample:

{
  "training": {
    "forward_passes": 50,
    "stopping_rules": [{ "type": "iteration_limit", "limit": 200 }]
  },
  "simulation": {
    "enabled": true,
    "num_scenarios": 2000,
    "scenario_source": {
      "seed": 77,
      "inflow": { "scheme": "out_of_sample" },
      "load": { "scheme": "in_sample" },
      "ncs": { "scheme": "in_sample" }
    }
  }
}

modeling

Controls physical modeling options.

inflow_non_negativity

• "none" – no treatment; negative inflows are passed through to the LP.
• "penalty" – adds a slack variable to the LP that absorbs negative inflow realisations. The slack carries a per-hydro objective cost from penalties.json::hydro.inflow_nonnegativity_cost.
• "truncation" – clamps negative PAR model draws to zero before applying noise.
• "truncation_with_penalty" – combines both: clamps the inflow to zero and adds a bounded slack variable penalised by penalties.json::hydro.inflow_nonnegativity_cost, providing a smooth backstop for extreme tail realisations.

Example:

{
  "modeling": {
    "inflow_non_negativity": {
      "method": "penalty"
    }
  }
}

cut_selection

Controls the row management pipeline for managing row pool growth. The pipeline has up to two stages: strategy-based selection and budget enforcement. Row management periodically scans the row pool and deactivates rows that are unlikely to improve the policy, reducing LP size without sacrificing convergence quality. For a detailed explanation of each stage, see Performance Accelerators.

The block has two always-on knobs at the top level plus a selection sub-object that chooses the method and carries only that method’s parameters. Omitting selection (or setting it to null) disables row selection — that is the default.

Always-on fields

The selection object

selection.method is the discriminator; each method exposes only its own parameters. Supplying a parameter that belongs to a different method is a config load error, and a misspelled method is rejected with the list of valid methods.

• "level1" — evaluates all populated rows at every visited state and retains any row whose value is within tie_tolerance of the per-state maximum at some state. Least aggressive; preserves the convergence guarantee.

  Field	Type	Default	Description
  tie_tolerance	float	1e-10	A row is active at a state when within this of the best row value there.
  check_frequency	integer	5	Iterations between periodic pruning checks. Must be > 0.

• "lml1" — at each visited state, retains only the oldest eligible row within tie_tolerance of the per-state maximum; the selected set is the union of those per-state survivors. More aggressive than "level1". Same fields as "level1" (tie_tolerance, check_frequency).

• "domination" — removes rows dominated at all visited states.

  Field	Type	Default	Description
  domination_tolerance	float	–	A row survives if within this of the maximum at any visited state. Required.
  check_frequency	integer	5	Iterations between periodic pruning checks. Must be > 0.

• "dynamic" — a per-solve lazy loop that loads only a small resident subset of rows per solve while retaining the full pool. The resident set is seeded from the most recent iterations, and each lazy-solve round adds the most-violated candidate rows.

  Field	Type	Default	Description
  start_iteration	integer	2	First 1-based iteration at which the lazy loop becomes active. Must be >= 1.
  seed_window	integer	5	Number of most-recent iterations whose rows seed the initial resident set. 0 is valid (seeds only the current iteration).
  candidate_recency	integer	null	Only rows generated within the last candidate_recency iterations are scored. null (the default) is unbounded — every pool row is a candidate, which preserves exactness. Some(n) (must be >= 1) makes the loop deliberately inexact: rows older than the window are never added.
  max_added_per_round	integer	10	Maximum rows added per lazy-solve round. Must be >= 1.
  violation_tolerance	float	1e-10	Violation tolerance for accepting a candidate row. Must be > 0.

The dynamic method is mutually exclusive with the periodic-pruning methods by construction — choosing it from the tagged selection block means none of level1 / lml1 / domination can run.

Example with the dynamic method:

{
  "training": {
    "cut_selection": {
      "row_activity_tolerance": 1e-6,
      "max_active_per_stage": 4000,
      "selection": {
        "method": "dynamic",
        "start_iteration": 2,
        "seed_window": 5,
        "max_added_per_round": 10,
        "violation_tolerance": 1e-10
      }
    }
  }
}

Example with the level1 method and a per-stage budget:

{
  "training": {
    "cut_selection": {
      "row_activity_tolerance": 1e-6,
      "max_active_per_stage": 500,
      "selection": {
        "method": "level1",
        "tie_tolerance": 1e-10,
        "check_frequency": 5
      }
    }
  }
}

estimation

Controls the PAR(p) model estimation pipeline. When the case provides inflow_history.parquet, Cobre can automatically estimate AR coefficients instead of requiring pre-computed inflow_ar_coefficients.parquet.

Example:

{
  "estimation": {
    "max_order": 6,
    "order_selection": "pacf",
    "min_observations_per_season": 30
  }
}

Setting "order_selection": "pacf_annual" activates the annual component extension. When enabled, the estimation pipeline performs four additional steps beyond the classical PAR path: (1) the Yule-Walker system is extended to include a cross-correlation term between the current-season inflow and the rolling 12-month average; (2) per-season sample statistics (mean and standard deviation) of that rolling average are computed for each hydro plant; (3) the coefficient, mean, and standard deviation are written to inflow_annual_component.parquet in the output directory; and (4) the lag stride used when building the LP noise columns is widened to accommodate the extra annual term. Use this option when your inflow series shows persistence that extends beyond the standard seasonal lag window.

policy

Controls policy persistence (checkpoint saving and warm-start loading).

checkpointing

boundary

Optional configuration for loading terminal-stage boundary cuts from a different Cobre policy checkpoint. When present, the solver loads cuts from the source checkpoint and injects them as fixed boundary conditions at the terminal stage of the current study. The imported cuts are not updated by training — they remain fixed throughout.

This enables Cobre-to-Cobre model coupling: a monthly study produces a policy checkpoint, and a weekly+monthly coupled study loads that checkpoint’s cuts as its terminal-stage future cost function.

Example — load stage 2’s cuts from a monthly policy as terminal boundary:

{
  "policy": {
    "mode": "fresh",
    "boundary": {
      "path": "../monthly_study/policy",
      "source_stage": 2
    }
  }
}

See Policy Management — Boundary Cuts for a full explanation of the coupling workflow.

Temporal Resolution

Cobre does not have dedicated config.json fields for temporal resolution. The resolution of each stage is determined entirely by the date boundaries in stages.json. However, when stages.json defines stages at different temporal resolutions — for example, four weekly stages within a month followed by monthly stages, or monthly stages transitioning to quarterly stages — three mechanisms activate automatically that users should understand.

Noise Group Sharing

When multiple SDDP stages share the same season_id within the same calendar period (for example, four weekly stages all assigned season_id: 0 for January), they receive identical PAR noise draws. This ensures that sub-monthly stages present an inflow trajectory consistent with the monthly PAR model they were fitted from, rather than fabricating independent weekly variability that the historical record does not support.

Observation Aggregation

When the study includes stages at different resolutions (for example, monthly and quarterly), Cobre automatically aggregates fine-grained historical observations into coarser season buckets before PAR fitting. A user supplying monthly inflow_history.parquet for a study that includes quarterly stages does not need to pre-aggregate the data; Cobre derives one observation per (entity, season, year) at the appropriate coarser resolution. Aggregating in the opposite direction (disaggregating coarser observations to a finer resolution) is not supported and will produce a validation error at case load time.

Lag Resolution Transition

For studies that transition from monthly to quarterly stages, the PAR lag state changes resolution at the boundary. During the monthly phase, each monthly inflow is accumulated into a ring buffer indexed by the downstream (quarterly) lag. When the first quarterly stage is reached, the ring buffer contains a complete set of duration-weighted monthly contributions, and the lag state is rebuilt automatically. This transition is transparent to the LP and the cut representation; it introduces no additional LP variables.

Example: Weekly Stages Within a Month

The following stages.json excerpt shows four weekly stages within January (stages 0-3, all with season_id: 0) followed by a normal monthly stage for February (season_id: 1). Stages 0-3 share the same season_id and will therefore receive identical PAR noise draws during training:

[
  {
    "id": 0,
    "start_date": "2024-01-01",
    "end_date": "2024-01-08",
    "season_id": 0,
    "num_scenarios": 50
  },
  {
    "id": 1,
    "start_date": "2024-01-08",
    "end_date": "2024-01-15",
    "season_id": 0,
    "num_scenarios": 50
  },
  {
    "id": 2,
    "start_date": "2024-01-15",
    "end_date": "2024-01-22",
    "season_id": 0,
    "num_scenarios": 50
  },
  {
    "id": 3,
    "start_date": "2024-01-22",
    "end_date": "2024-02-01",
    "season_id": 0,
    "num_scenarios": 50
  },
  {
    "id": 4,
    "start_date": "2024-02-01",
    "end_date": "2024-03-01",
    "season_id": 1,
    "num_scenarios": 50
  }
]

Recommended Alternative: Weekly Blocks Within a Monthly Stage

When weekly dispatch granularity is needed but true weekly-resolution noise data is unavailable, the recommended approach is to use a single monthly SDDP stage with chronological blocks rather than four separate weekly SDDP stages. This provides weekly LP granularity while keeping one noise realization per month — consistent with the data resolution — and avoids the lag-accumulation complications that arise with multiple independent weekly stages. See Stochastic Modeling — Temporal Resolution and PAR for the full explanation and a stages.json example of the block pattern.

See Also (Temporal Resolution)

• Stochastic Modeling — Multi-Resolution Studies — detailed mechanism descriptions including the noise group precomputation algorithm, observation aggregation internals, and lag ring buffer design
• Stochastic Modeling — Temporal Resolution and PAR — the honest representation principle, the recommended weekly-block pattern, and validation rules 27-31

exports

Controls which outputs are written to the results directory.

Full Example

{
  "$schema": "https://raw.githubusercontent.com/cobre-rs/cobre/refs/heads/main/book/src/schemas/config.schema.json",
  "training": {
    "tree_seed": 42,
    "forward_passes": 50,
    "stopping_rules": [
      { "type": "iteration_limit", "limit": 200 },
      { "type": "bound_stalling", "iterations": 20, "tolerance": 0.0001 }
    ],
    "stopping_mode": "any",
    "scenario_source": {
      "seed": 99,
      "inflow": { "scheme": "out_of_sample" },
      "load": { "scheme": "in_sample" },
      "ncs": { "scheme": "in_sample" }
    },
    "cut_selection": {
      "row_activity_tolerance": 1e-6,
      "max_active_per_stage": null,
      "selection": {
        "method": "level1",
        "tie_tolerance": 1e-10,
        "check_frequency": 5
      }
    }
  },
  "modeling": {
    "inflow_non_negativity": {
      "method": "penalty"
    }
  },
  "simulation": {
    "enabled": true,
    "num_scenarios": 2000
  },
  "policy": {
    "path": "./policy",
    "mode": "fresh"
  },
  "exports": {
    "states": false,
    "stochastic": false
  }
}

Advanced Fields

The Config struct supports additional sections not documented on this page. These fields are deserialized from config.json when present but are intended for advanced use cases and may change between releases:

All fields have defaults and can be omitted. Every JSON input file rejects unknown keys, so misspelled fields raise a parse error rather than being silently ignored. For the complete list of fields and their types, see the Config struct in the cobre-io API docs.

See Also

• Case Directory Format — full schema for all input files
• Running Studies — end-to-end workflow guide
• Error Codes — validation errors including SchemaError for config fields
• Stochastic Modeling — Temporal Resolution — how stage resolution affects PAR noise sharing and validation rules

Performance Accelerators

This chapter documents the performance optimization techniques built into Cobre’s SDDP solver. Each accelerator addresses a specific cost driver in the training loop and is active by default unless noted otherwise. Understanding them helps users interpret timing statistics, configure cut management strategies, and diagnose performance regressions.

LP Setup Optimizations

Each SDDP iteration requires solving hundreds to thousands of LP subproblems. Minimizing per-solve overhead is critical.

Model Persistence

The structural LP for each stage (the constraint matrix, variable bounds, and objective coefficients) is assembled once at initialization into a StageTemplate. During the training loop, the solver loads the template once per (worker, stage) pair and then only patches the scenario-dependent row bounds for each forward-pass scenario. This avoids rebuilding the entire LP from scratch at every scenario evaluation.

The simulation pipeline uses the same pattern: a stage-major loop loads the LP once per (worker, stage) and then iterates over scenarios, patching bounds only. This reduces LP assembly overhead from O(scenarios x stages) to O(workers x stages).

Incremental Cut Injection

Benders cuts are appended to the persistent lower-bound LP via add_rows without rebuilding the structural model. A CutRowMap provides O(1) slot-to-row lookup so the incremental append skips cuts that are already present.

The LB LP is strictly append-only: rows generated during training are appended and never removed, which keeps the lower bound monotonically non-decreasing across iterations. Row selection in the shared row pool still affects the forward and backward passes — pool-deactivated rows remain as LP rows in the LB solver but are not re-evaluated, so they contribute only their binding value at the trial point.

PatchBuffer Pre-Allocation

The PatchBuffer holds three parallel arrays (indices, lower, upper) consumed by the solver’s set_row_bounds call. It is sized once at construction for the maximum number of patches across all stages:

Where N = hydro plants, L = max PAR order, M = stochastic load buses, B = max blocks per stage. The buffer is reused across all iterations and scenarios with zero hot-path allocation.

Solver Safeguards

When HiGHS returns a non-terminal error (SOLVE_ERROR or UNKNOWN), the solver automatically escalates through a 12-level retry sequence organized in two phases, with per-level and overall wall-clock budgets. The caller never sees intermediate failures — only the final Ok(solution) or Err(SolverError).

Phase 1 (levels 0–4): Cumulative Sequence

Each level stacks on top of the previous:

Phase 2 (levels 5–11): Extended Strategies

Each level starts from restored defaults with presolve and iteration limits, then applies level-specific options:

Budgets: 15 seconds per level in Phase 1, 30 seconds per level in Phase 2, 120 seconds overall. Iteration limits are set to max(100_000, 50 x num_cols) for simplex and 10,000 for IPM.

Default solver settings are restored unconditionally after the retry loop, regardless of outcome. The per-level retry histogram is recorded in SolverStatistics.retry_level_histogram and written to training/solver/retry_histogram.parquet for post-run analysis.

LP Scaling

Before each stage’s LP template is built, a prescaler normalizes the constraint matrix coefficients toward 1.0, improving numerical conditioning and reducing the need for HiGHS’s internal scaling.

Column Scaling

For each column j, the scale factor is 1 / sqrt(max|A_ij| * min|A_ij|) over non-zero entries. The matrix values, objective coefficients, and column bounds are scaled in-place. After solving, primal values are unscaled: x_original[j] = col_scale[j] * x_scaled[j].

Row Scaling

Applied after column scaling with the same geometric-mean formula per row. After solving, duals are unscaled: dual_original[i] = row_scale[i] * dual_scaled[i].

Cost Scale Factor

A constant COST_SCALE_FACTOR = 1000 is applied to all objective coefficients to reduce the magnitude of objective coefficients, improving simplex numerical stability.

Because the prescaler normalizes matrix entries toward 1.0, HiGHS’s internal scaling (simplex_scale_strategy) is disabled (set to 0) in every solver profile — including the retry-escalation levels — to avoid double-scaling the already-conditioned matrix.

The scaling diagnostics are written to training/scaling_report.json after template construction, documenting the coefficient range before and after scaling for each stage.

Cut Management Pipeline

As training progresses, the row pool grows and LP solve times increase. Cobre provides a two-stage row management pipeline to control this growth while preserving convergence guarantees.

The pipeline runs after each iteration’s backward pass and cut synchronization:

Stage 1: Strategy-based selection  (check_frequency gated)
    |
    v
Stage 2: Budget enforcement        (every iteration)

Stage 1: Strategy-Based Selection

Four strategies are available, configured via cut_selection in config.json:

level1, lml1, and domination respect check_frequency: selection runs only at iterations that are multiples of check_frequency. Stage 0 is always exempt (its rows drive the lower bound and are never backward-pass successors). Selection runs in parallel across stages via rayon.

level1, lml1, and domination share a single value-evaluation kernel that performs O(|populated cuts| x |visited states|) work per stage per check. Every populated cut is evaluated at every visited forward-pass state (including cuts currently flagged inactive, which means a previously deactivated cut can be reactivated when it later achieves the maximum at some state). The visited-states archive is collected during training for these three variants. The tie_tolerance parameter (default 1e-10) on level1 and lml1 controls how closely a cut must approach the per-state maximum to be retained; domination uses the domination_tolerance field for the same purpose.

dynamic (Dynamic Cut Selection, DCS) operates differently: it is a per-solve lazy selection loop that adds cuts on demand rather than deactivating from a full pool scan. It never invokes the value-evaluation kernel and does not respect check_frequency. The initial active set is seeded from the seed_window most recent iterations. See cut_selection for the full parameter reference.

Stage 2: Budget Enforcement

A hard-cap safety net on LP size, enabled via max_active_per_stage. When the number of active rows exceeds the budget after Stage 1, the pool evicts rows sorted by staleness (last_active_iter ascending, then active_count ascending). Rows from the current iteration are always protected.

Unlike Stage 1, budget enforcement runs every iteration (not gated by check_frequency).

Configuration:

{
  "training": {
    "cut_selection": {
      "max_active_per_stage": 500,
      "selection": {
        "method": "level1",
        "tie_tolerance": 1e-10,
        "check_frequency": 5
      }
    }
  }
}

Why it matters: High-parallelism configurations (many forward passes, few iterations) accumulate more active rows than low-parallelism configurations (fewer forward passes, more iterations), making each backward LP solve proportionally more expensive. Bounding LP size makes high-parallelism configurations viable without unbounded solve-time growth.

Observability

The row management pipeline writes per-stage statistics to training/cut_selection/iterations.parquet with 10 columns:

Basis Warm-Start

Reusing the LP simplex basis from the previous solve reduces the number of simplex pivots needed for subsequent solves.

BasisStore

The BasisStore holds one Basis per (scenario, stage) pair in a flat array indexed as bases[scenario * num_stages + stage]. Before the parallel forward pass, the store is split into disjoint per-worker sub-views (split_workers_mut) so no synchronization is needed during writes.

The Basis struct stores solver-native i32 status codes directly, enabling zero-copy warm-starts via memcpy — no per-element enum translation is needed.

Simulation Basis Broadcast

When running with MPI, rank 0’s scenario-0 basis is broadcast to all ranks before the simulation phase. This ensures all ranks warm-start simulation from the same LP vertex, regardless of rank count.

Basis Reconstruction

Each stored warm-start basis is wrapped in a CapturedBasis { basis, base_row_count, cut_row_slots, state_at_capture } struct that records the LP row count and the ordered list of row-pool slot indices at capture time, alongside the state vector at which the basis was captured. The reconstruct_basis function in cobre-sddp::basis_reconstruct is the sole entry point for applying a stored basis across row-set churn on the forward pass, backward pass, and simulation pipeline.

When a stored basis is applied to an LP whose appended rows have changed, reconstruct_basis walks the current LP’s appended rows, looks each slot up in an O(1) scratch map built from cut_row_slots, and classifies each row into one of two paths:

• Preserved (slot present in the stored basis): the original status is copied verbatim.
• New (slot not present — a row added since capture): the row is unconditionally assigned NONBASIC_LOWER (tight guess).

Each NONBASIC_LOWER classification on a new row requires a compensating demotion on a preserved row to keep HiGHS’s column-basic + row-basic invariant. The stalest preserved-LOWER candidate is promoted, ranked lexicographically by insertion order. When new-LOWER classifications outnumber preserved-LOWER candidates, a tail fallback flips the most recent new-LOWER rows back to BASIC until the invariant holds.

Reconstruction is always active when a stored basis exists — there is no configuration flag. The basis_activity_window config knob that earlier versions accepted has been removed; a config that still sets it now fails to load with an unknown-field error.

The in-memory SolverStatistics::basis_reconstructions counter tracks how often reconstruct_basis was invoked with a non-empty stored basis.

Backward-Pass Basis Cache

During training, rank 0’s ω=0 backward-pass worker captures a fresh basis for every stage into a per-iteration backward cache. At end of iteration the cache is broadcast to all ranks, and on the next iteration’s backward pass every rank’s ω=0 solve warm-starts from the cached basis instead of falling back to the forward-pass BasisStore. The first iteration has no backward cache yet, so it uses the forward cache exclusively.

The backward cache matters because rows added earlier in the current iteration’s backward walk are new relative to the previous iteration’s stored basis — so the classifier fires frequently on backward solves, while the forward pass sees mostly preserved slots and the classifier rarely runs. A warm-start at ω=0 also cascades through the remaining openings (ω=1..n_openings-1) via HiGHS’s retained factorization, amplifying the per-solve impact.

Parallel Execution

Backward Pass Work-Stealing

The backward pass parallelizes the inner trial-point loop using atomic counter work-stealing: each worker claims the next available trial-point index via AtomicUsize::fetch_add(1, Relaxed). This keeps all threads busy even when trial points solve in variable time.

After the parallel region, staged rows are sorted by trial_point_idx and inserted into the FCF in deterministic order, guaranteeing bit-for-bit identical results regardless of thread count or completion order.

Per-Phase Solver Profiles

Each algorithmic phase — forward sweep, backward sweep, and simulation — can be configured with a distinct HighsProfile that sets the LP solver’s feasibility tolerances and per-attempt iteration caps. Tuning BACKWARD_PROFILE to tighter tolerances or stricter iteration caps can reduce backward-pass solve time variance, which in turn improves load balance across worker threads and shortens wall-clock training time. FORWARD_PROFILE and SIMULATION_PROFILE ship equal to HighsProfile::default(), while BACKWARD_PROFILE already overrides simplex_price_strategy to 2 (RowHyperSparse) to exploit sparsity on the backward LPs; all other backward fields match the default.

Forward Pass and Simulation

Scenarios are statically partitioned across solver workspace instances (not rayon’s default work-stealing), making the scenario-to-worker assignment deterministic. Within each scenario, the LP is loaded once per stage and only row bounds are patched per scenario.

Lower Bound Evaluation

The lower bound evaluation (solving a stage-0 LP for every opening in the tree) runs as a single-threaded serial loop on rank 0. Each opening patches correctness-critical per-opening state (e.g. NCS column bounds) on a shared solver, so the openings cannot be split across workers without fragmenting those sequential steps; the step is therefore not parallelized.

Communication-Free Seed Derivation

Forward pass noise is generated without inter-rank communication. Each rank independently derives its noise seed from (base_seed, iteration, scenario, stage) using deterministic SipHash-1-3 seed derivation. The opening tree is pre-generated once before training and shared read-only.

Memory Efficiency

Pre-Allocation Discipline

The forward, backward, and simulation per-solve hot paths make no heap allocations inside the iteration loop; all workspace buffers are allocated once before the loop. (The periodic cut-selection pass is the one documented exception — its rayon fold/reduce kernel allocates per-leaf scratch.) The pre-allocated buffers are:

CutPool Flat Coefficient Storage

Row coefficients are stored as a single contiguous Vec<f64> of size capacity x state_dimension rather than a Vec<Vec<f64>>. This provides cache-friendly sequential access during batch iteration (row evaluation, dominance checks) and eliminates per-row heap allocation.

Lazy FCF Growth

The CutPool grows its coefficient storage on demand using a doubling strategy (minimum 16 slots) rather than pre-allocating to the theoretical maximum capacity. This prevents memory exhaustion on pathological parameter combinations (e.g., 1000 iterations x 1000 forward passes x 50 states x 120 stages would require 48 GB with eager pre-allocation).

O(1) Active Row Count

CutPool maintains a cached_active_count that is updated incrementally on each activation/deactivation, making active_count() O(1) instead of requiring a scan of the entire pool.

Compile-Time Solver Dispatch

SolverInterface is resolved as a generic type parameter at compile time, not as Box<dyn SolverInterface>. All solver calls monomorphize to direct function calls with no virtual dispatch overhead — critical when tens of millions of LP solves occur per training run.

See Also

• Configuration — row-selection and row management configuration
• Output Format — timing, solver statistics, and row-selection output schemas
• cobre-solver — solver interface and retry escalation details
• cobre-sddp — training loop architecture and data structures

Running Studies

End-to-end workflow for running an SDDP study with cobre run, interpreting output, and inspecting results.

Preparing a Case Directory

A case directory is a folder containing all input data files required by Cobre. The minimum required structure is:

my_study/
  config.json
  penalties.json
  stages.json
  initial_conditions.json
  system/
    buses.json
    hydros.json
    thermals.json
    lines.json

All eight files are required. Before running, validate the input:

cobre validate /path/to/my_study

Successful validation prints entity counts and exits with code 0:

When validation detects errors — such as missing required fields or constraint violations — it reports them with severity labels and exits with code 1:

Fix any reported errors before proceeding. See Case Directory Format for the full schema.

Running cobre run

cobre run /path/to/my_study

By default, results are written to <CASE_DIR>/output/. To specify a different location:

cobre run /path/to/my_study --output /path/to/results

Lifecycle Stages

1. Load — reads input files, runs layered validation (exits code 1 on validation failure, 2 on I/O error)
2. Train — builds the SDDP policy by iterating forward/backward passes; stops when stopping rules are met
3. Simulate — (optional) evaluates the policy over independent scenarios; requires simulation.enabled = true
4. Write — writes Hive-partitioned Parquet (tabular), JSON manifests/metadata, and FlatBuffers output

Terminal Output

Banner

When stderr is a terminal, a banner shows the version and solver backend. Use --quiet to suppress the banner, progress bars, and post-run summary. Errors are always written to stderr regardless of --quiet.

Progress Bars

During training, a progress bar shows current iteration count. In --quiet mode, no progress bars are printed. Errors are always written to stderr.

Summary

After all stages complete, a run summary is printed to stderr with:

• Training: iteration count, convergence status, bounds, gap, cuts, solves, time
• Simulation (when enabled): scenarios requested, completed, failed
• Output directory: absolute path to results

Checking Results

Use cobre report to inspect the results:

cobre report /path/to/my_study/output

Reads manifest files and prints JSON to stdout (suitable for piping to jq):

cobre report /path/to/my_study/output | jq '.training.convergence.final_gap_percent'

Exits with code 0 on success or 2 if the results directory does not exist.

Common Workflows

Training Only

To run training without simulation, set simulation.enabled to false in config.json:

{ "simulation": { "enabled": false } }

Simulation Against a Saved Policy

To evaluate a previously trained policy without re-training:

{
  "training": { "enabled": false },
  "policy": { "mode": "warm_start", "path": "./policy" }
}

Cobre loads the policy cuts, skips training entirely, and runs simulation. See Policy Management for details on warm-start and resume modes.

Multi-threading

Use --threads to accelerate training and simulation with intra-rank parallelism:

cobre run /path/to/my_study --threads 4

The thread pool is used for forward-pass batching and simulation scenario evaluation. Speedup depends on the number of forward passes and simulation scenarios configured.

Quiet Mode for Scripts

cobre run /path/to/my_study --quiet
exit_code=$?
if [ $exit_code -ne 0 ]; then
  echo "Study failed with exit code $exit_code" >&2
fi

Suppresses banner and progress output, suitable for batch scripts.

Checking Exit Codes

See CLI Reference for the full exit code table.

Exporting Stochastic Artifacts

Set exports.stochastic to true in config.json to write the stochastic preprocessing artifacts to output/stochastic/ before training begins:

{
  "exports": {
    "stochastic": true
  }
}

What is exported

“Estimation was performed” means the user did not supply the corresponding scenario file; Cobre derived it from inflow_history.parquet.

Round-trip workflow

Because every exported file uses the exact same schema as the corresponding input file, you can copy the exported artifacts back to scenarios/ and re-run to reproduce the identical stochastic context without re-running estimation:

# Step 1: initial run with stochastic export enabled in config.json
cobre run my_case

# Step 2: copy artifacts to scenarios/
cp -r my_case/output/stochastic/* my_case/scenarios/

# Step 3: re-run — estimation is skipped, opening tree is loaded directly
cobre run my_case

The re-run is faster (no Levinson-Durbin fitting or spectral decomposition) and produces bit-for-bit identical stochastic artifacts.

For the complete schema of each exported file, see Stochastic Artifacts in the Output Format Reference.

Policy Management

Cobre stores the trained future-cost function (cuts), LP basis, and visited states in a policy directory. The policy section of config.json controls where that directory lives, whether training starts from scratch or from a prior checkpoint, and how often intermediate checkpoints are written during training.

Policy Modes

The policy.mode field selects one of three initialization strategies. The default is "fresh".

Fresh (Default)

Training starts from an empty future-cost function. All prior cuts in policy.path are ignored (or the directory does not yet exist).

{ "policy": { "mode": "fresh" } }

Use "fresh" for new studies or when you want a clean training run with no influence from earlier iterations.

Warm Start

Cobre loads the cuts from an existing policy checkpoint before training begins. Training then continues, adding new cuts on top of the loaded ones. The loaded cuts count as the initial future-cost approximation.

{ "policy": { "mode": "warm_start", "path": "./policy" } }

Use "warm_start" when you have a policy from a previous run (possibly with different parameters) and want to accelerate convergence by reusing its cuts. Set policy.validate_compatibility to true (the default) to have Cobre verify that the state dimension and entity layout of the saved policy match the current system before loading.

Resume

Cobre reads the checkpoint metadata to determine how many iterations were completed, then resumes training from that point. The RNG seed and iteration counter are restored so the noise sequences are identical to an uninterrupted run.

{ "policy": { "mode": "resume", "path": "./policy" } }

Use "resume" after an interrupted training run (power loss, job timeout, or manual cancellation) to continue exactly where training stopped. Requires that checkpointing was enabled in the interrupted run.

Simulation-Only Mode

To evaluate a previously trained policy without re-running training, disable training and load the policy in warm-start mode:

{
  "training": { "enabled": false },
  "policy": { "mode": "warm_start", "path": "./policy" }
}

Cobre loads the cuts from policy.path, skips the training phase entirely, and runs the post-training simulation using the loaded future-cost function. This is useful for running additional simulation scenarios on a policy that has already converged, or for comparing multiple saved policies on the same scenarios.

Checkpointing Configuration

The policy.checkpointing section controls periodic checkpointing during training. All fields are optional; omitting a field leaves the solver default in effect.

Example enabling checkpointing every 50 iterations starting at iteration 100, with basis storage and compression:

{
  "policy": {
    "path": "./policy",
    "checkpointing": {
      "enabled": true,
      "initial_iteration": 100,
      "interval_iterations": 50,
      "store_basis": true,
      "compress": true
    }
  }
}

Checkpoint Directory Contents

A written checkpoint has the following layout under policy.path:

policy/
  metadata.json          -- run metadata and compatibility hashes (written last)
  cuts/
    stage_000.bin        -- cut coefficients and intercepts for stage 0
    stage_001.bin        -- cut coefficients and intercepts for stage 1
    ...
  basis/
    stage_000.bin        -- LP basis for stage 0 (when store_basis is enabled)
    stage_001.bin
    ...
  states/
    stage_000.bin        -- visited states for dominated cut selection, stage 0
    stage_001.bin
    ...

metadata.json is written last. Its presence signals that the checkpoint is complete and safe to load. An interrupted write leaves metadata.json absent; Cobre treats a directory without metadata.json as an incomplete checkpoint and refuses to load it.

The metadata.json file records the number of completed iterations, lower-bound and upper-bound values, state dimension, number of stages, configuration and system hashes (used by validate_compatibility), forward passes per iteration, and the RNG seed. These fields allow Cobre to verify that a saved policy is compatible with the current system before loading it in "warm_start" or "resume" mode.

Boundary Cuts

Boundary cuts allow a Cobre study to load terminal-stage future cost function (FCF) approximations from a different Cobre policy checkpoint. This is the mechanism for model coupling — a short-horizon study (e.g., weekly+monthly coupled study) can use the long-horizon policy (e.g., a monthly long-horizon model) as its terminal boundary condition, ensuring that end-of-horizon decisions account for the long-term future cost of water.

How it works

1. Run a monthly study and produce a policy checkpoint (the “outer” model).
2. Run a weekly+monthly study with policy.boundary pointing to the monthly checkpoint. Cobre loads cuts from the specified stage and injects them into the terminal stage’s row pool as fixed boundary conditions.

The imported boundary cuts are not updated by the SDDP training algorithm. They remain fixed throughout training and simulation, providing a floor on the terminal-stage future cost.

Configuration

Add a boundary object to the policy section of config.json:

{
  "policy": {
    "mode": "fresh",
    "boundary": {
      "path": "../monthly_study/policy",
      "source_stage": 2
    }
  }
}

When boundary is absent or null, no boundary cuts are loaded (the default).

Compatibility requirements

The source checkpoint must have the same state dimension (number of hydro plants and maximum PAR order) as the current study. Cobre validates this automatically when validate_compatibility is true. If the dimensions don’t match, loading fails with a descriptive error.

Production coupling workflow

The typical production coupling pipeline uses boundary cuts as follows:

Monthly Cobre study (12 stages)
  └─ policy checkpoint: cuts for stages 0–11

Weekly+monthly coupled study (W1, W2, W3, W4, M2)
  └─ policy.boundary.path = "../monthly/policy"
  └─ policy.boundary.source_stage = 2  (March cuts → terminal FCF)

The coupled study’s terminal stage (M2) receives the monthly model’s March cuts as its future cost function. The lag accumulation mechanism ensures that the state vector’s lag values at the terminal stage are monthly averages, making the imported cut coefficients evaluate correctly.

Interaction with warm-start

Boundary cuts and warm-start are independent features. You can combine them:

{
  "policy": {
    "mode": "warm_start",
    "path": "./policy",
    "boundary": {
      "path": "../monthly/policy",
      "source_stage": 2
    }
  }
}

This loads the previous coupled study’s own cuts via warm-start AND loads the monthly model’s boundary cuts at the terminal stage. Both sets of cuts contribute to the lower bound.

See Also

• Configuration — every config.json field documented
• Running Studies — common workflows including training-only and simulation-only runs
• Output Format — detailed description of every output file

cobre-bridge: Case Conversion

cobre-bridge is a standalone Python package that converts power system case data from legacy formats to the Cobre input format. It currently supports conversion from the data format used by Brazilian hydrothermal dispatch tools.

The package is maintained in a separate repository: github.com/cobre-rs/cobre-bridge.

Installation

pip install cobre-bridge

To enable post-conversion validation with the Cobre solver:

pip install cobre-bridge cobre-python

Converting a Case

The convert subcommand reads a source case directory and writes a complete Cobre case directory:

cobre-bridge convert newave /path/to/source/case /path/to/output/case

Options

What Gets Converted

The conversion pipeline transforms the source case’s input files into a complete Cobre case directory. The mapping covers:

Output Directory Structure

output/
  config.json
  stages.json
  penalties.json
  initial_conditions.json
  system/
    hydros.json
    thermals.json
    buses.json
    lines.json
    non_controllable_sources.json
    hydro_production_models.json       (when applicable)
    hydro_geometry.parquet             (forebay/tailrace curves)
  scenarios/
    inflow_seasonal_stats.parquet
    inflow_history.parquet
    load_seasonal_stats.parquet
    load_factors.json
    non_controllable_stats.parquet
    non_controllable_factors.json
  constraints/
    generic_constraints.json
    generic_constraint_bounds.parquet
    hydro_bounds.parquet
    thermal_bounds.parquet
    line_bounds.parquet
    exchange_factors.json

Not all files are always produced. Optional files (e.g., hydro_production_models.json, generic constraints) are written only when the source data contains the relevant configuration.

Comparing Results

After running both the source tool and Cobre on the same case, the compare subcommand checks LP bounds for consistency:

cobre-bridge compare newave /path/to/source/sintese /path/to/cobre/output \
  --tolerance 1e-3

The comparison reads the source tool’s synthesis output and Cobre’s training/dictionaries/bounds.parquet, aligns entities by name, and reports any mismatches beyond the tolerance.

Python API

For programmatic use, import the conversion pipeline directly:

from pathlib import Path
from cobre_bridge.pipeline import convert_newave_case

report = convert_newave_case(
    src=Path("/path/to/source/case"),
    dst=Path("/path/to/output/case"),
)
print(report)  # ConversionReport with entity counts and warnings

Conversion Details

Entity ID Remapping

Source systems typically use 1-based integer IDs. cobre-bridge remaps all entity IDs to 0-based integers in a deterministic order derived from the source configuration files. This ensures consistent output regardless of file ordering.

Fictitious Plant Filtering

Plants marked as fictitious in the source data (used internally by some tools for accounting purposes) are automatically excluded from the conversion output.

Risk Measure Support

When the source case configures risk-averse optimization (CVaR), cobre-bridge converts the alpha and lambda parameters to per-stage risk_measure entries in stages.json. Three modes are supported:

• Disabled – all stages use "expectation".
• Constant – all stages use the same CVaR parameters.
• Temporal – per-stage alpha/lambda values, with fallback to constants when a stage override is zero.

Generic Constraints

Three types of user-defined constraints are converted and merged into a single generic_constraints.json file with sequential IDs:

• VminOP – minimum stored energy constraints (weighted sum of storage across a group of reservoirs).
• Electric – operational constraints on hydro generation and line flows.
• AGRINT – group dispatch constraints for thermal and hydro plants.

Dependencies

See Also

• Anatomy of a Case – what each output file controls
• Configuration – all config.json fields
• Case Directory Format – complete input schema reference

Understanding Results

After cobre run completes, the output directory contains three categories of artifacts: training convergence data, a saved policy checkpoint, and simulation dispatch results. This page explains how to read each category and how to query the results programmatically using cobre report.

If you have not yet run the quickstart, complete Quickstart first — this page references the my_first_study/results/ directory produced by that walkthrough.

The Post-Run Summary

When cobre run finishes, it prints a summary block to stderr. The 1dtoy run from the quickstart produces output similar to:

Training complete in 0.5s (128 iterations, iteration_limit)
  Lower bound:  1.55955e7 $/stage
  Upper bound:  5.79592e5 +/- 0.00000e0 $/stage
  Gap:          -2590.8% (started at 70.5%)
  Policy rows:  384 active / 384 generated
  LP solves:    5632 (5632 first-try, 0 retried, 0 failed)

Simulation complete in 0.6s (100 scenarios)
  Completed: 100  Failed: 0

Output written to my_first_study/results/

Exact numerical values vary across runs because scenario sampling is stochastic. The values below are representative of the 1dtoy example; your run will differ slightly.

Lower bound vs. upper bound. The lower bound is the optimizer’s proven best estimate of the minimum achievable cost. The upper bound is the average cost observed when running the current policy over sampled scenarios. When the gap is small, the policy is near-optimal. When the gap is large, running more iterations will typically narrow it further.

Termination reasons. The parenthetical after the iteration count explains why training stopped:

• iteration_limit — the maximum iteration count was reached (the 1dtoy default).
• converged at iter N — a convergence criterion was met at iteration N and training stopped early. This appears when you configure a bound_stalling or similar rule in config.json.

Theory reference: For the mathematical definition of lower and upper bounds, optimality gap, and stopping criteria, see Convergence in the methodology reference.

Output Directory Structure

All artifacts are written under the results directory you specified with --output. The 1dtoy run produces:

my_first_study/results/
  training/
    metadata.json           Run metadata: configuration, convergence, row-pool, bounds, solve stats
    convergence.parquet     Per-iteration convergence metrics (lower bound, upper bound, gap)
    dictionaries/
      codes.json            Integer-to-string code mappings for entity categories
      state_dictionary.json State variable definitions and units
      entities.csv          Entity registry (id, name, type)
      variables.csv         LP variable registry
      bounds.parquet        LP variable bound definitions
    timing/
      iterations.parquet    Per-iteration wall-clock timing broken down by phase
  policy/
    cuts/
      stage_000.bin         FlatBuffers-encoded optimality cuts for stage 0
      stage_001.bin         ... stage 1
      stage_002.bin         ... stage 2
      stage_003.bin         ... stage 3
    basis/
      stage_000.bin         LP basis checkpoints for warm-starting
      stage_001.bin
      stage_002.bin
      stage_003.bin
    metadata.json           Policy metadata: stage count, cut counts per stage
  simulation/
    metadata.json           Run metadata: scenario counts, cost statistics, solve stats
    buses/
      scenario_id=0000/data.parquet
      scenario_id=0001/data.parquet
      ...                   One partition per scenario
    costs/
      scenario_id=0000/data.parquet
      ...
    hydros/
      scenario_id=0000/data.parquet
      ...
    thermals/
      scenario_id=0000/data.parquet
      ...
    inflow_lags/            Inflow lag state data used to initialize scenario chains

The three top-level subdirectories have distinct roles:

• training/ — everything produced during the training loop: convergence history, timing, and the dictionaries needed to interpret LP variable indices.
• policy/ — the trained policy checkpoint. These binary files encode the optimality cuts built during training. They can be used to resume or extend a study.
• simulation/ — the dispatch results from evaluating the trained policy over 100 simulation scenarios.

Training Results

Reading training/metadata.json

The training metadata file is the canonical record of what happened during training. The 1dtoy run produces:

{
  "cobre_version": "0.9.1",
  "hostname": "<hostname>",
  "solver": "highs",
  "solver_version": "<solver version>",
  "started_at": "<timestamp>",
  "completed_at": "<timestamp>",
  "duration_seconds": 0.15,
  "status": "complete",
  "configuration": {
    "seed": null,
    "max_iterations": 128,
    "forward_passes": 1,
    "stopping_mode": "any",
    "policy_mode": "fresh"
  },
  "problem_dimensions": {
    "num_stages": 4,
    "num_hydros": 1,
    "num_thermals": 2,
    "num_buses": 1,
    "num_lines": 0
  },
  "iterations": {
    "completed": 128,
    "converged_at": null
  },
  "convergence": {
    "achieved": false,
    "final_gap_percent": -2590.77437875556,
    "termination_reason": "iteration_limit"
  },
  "row_pool": {
    "total_generated": 384,
    "total_active": 384,
    "peak_active": 384,
    "cuts_active": 384,
    "rows_in_lp_total": 0,
    "rows_in_lp_solve_count": 0,
    "rows_in_lp_max": 0
  },
  "bounds": {
    "final_lower_bound": 15595518.381798675,
    "final_upper_bound": 579592.1986224408,
    "final_upper_bound_std": 0.0
  },
  "solve_stats": {
    "total_lp_solves": 5632,
    "first_try": 5632,
    "retried": 0,
    "failed": 0,
    "forward_solve_seconds": 0.016,
    "backward_solve_seconds": 0.079,
    "parallelism": 1
  },
  "distribution": {
    "backend": "local",
    "world_size": 1,
    "ranks_participated": 1,
    "num_nodes": 1,
    "threads_per_rank": 1,
    "hosts": [{ "hostname": "<hostname>", "ranks": [0] }]
  }
}

Field-by-field explanation of the key fields:

What “converged” means in practice. A converged run (convergence.achieved: true) means a stopping rule determined that continuing would not meaningfully improve the policy. The 1dtoy case hits its 128-iteration budget before a convergence rule fires, so achieved is false. For larger studies, configure a bound_stalling or gap_threshold stopping rule in config.json to stop automatically when the gap stabilizes.

Simulation Results

Hive-Partitioned Layout

The simulation output uses Hive partitioning: results are split into one data.parquet file per scenario, stored in a directory named scenario_id=NNNN/. This layout is natively understood by Polars, Pandas (via PyArrow), R’s arrow package, and DuckDB — they can read the entire simulation/costs/ directory as a single table and filter by scenario_id at the storage layer without loading all data into memory.

The four entity categories are:

Results are in Parquet format. To read them, use any columnar data tool:

# Polars — reads all 100 scenarios at once
import polars as pl
df = pl.read_parquet("my_first_study/results/simulation/costs/")
print(df.head())

# Pandas + PyArrow
import pandas as pd
df = pd.read_parquet("my_first_study/results/simulation/costs/")
print(df.head())

-- DuckDB — filter to a single scenario
SELECT * FROM read_parquet('my_first_study/results/simulation/costs/**/*.parquet')
WHERE scenario_id = 0;

# R with arrow
library(arrow)
ds <- open_dataset("my_first_study/results/simulation/costs/")
dplyr::collect(dplyr::filter(ds, scenario_id == 0))

Querying Results with cobre report

cobre report reads the JSON metadata files and prints a structured JSON summary to stdout. Use it with jq to extract specific metrics in scripts or CI pipelines.

# Print the full report
cobre report my_first_study/results

The output has this top-level shape:

{
  "output_directory": "/abs/path/to/results",
  "status": "complete",
  "bounds": { "final_lower_bound": ..., "final_upper_bound": ... },
  "training": { "iterations": {}, "convergence": {}, "row_pool": {}, "bounds": {}, "configuration": {}, "problem_dimensions": {} },
  "cost": { "mean_cost": ..., "std_cost": ... } | null,
  "simulation": { "scenarios": {}, "cost": {} } | null
}

Practical jq queries

# Extract the final convergence gap
cobre report my_first_study/results | jq '.training.convergence.final_gap_percent'

# Check how many iterations ran
cobre report my_first_study/results | jq '.training.iterations.completed'

# Check simulation scenario counts
cobre report my_first_study/results | jq '.simulation.scenarios'

# Use the status in a CI script: exit non-zero if training failed
status=$(cobre report my_first_study/results | jq -r '.status')
if [ "$status" != "complete" ]; then
  echo "Run did not complete successfully: $status" >&2
  exit 1
fi

# Check convergence was achieved (returns true or false)
cobre report my_first_study/results | jq '.training.convergence.achieved'

For the complete cobre report documentation and all available JSON fields, see CLI Reference.

For a detailed description of every field in every output file, see Output Format Reference.

See Also

• Convergence & Diagnostics — advanced analysis patterns and convergence assessment
• CLI Reference — all flags, subcommands, and exit codes
• Configuration — every config.json field documented

Convergence & Diagnostics

Understanding Results explains what each output file contains and how to read it. This page goes one level deeper: it provides practical analysis patterns for answering domain questions from the data. It assumes you are comfortable loading Parquet files in your preferred tool.

The focus is on convergence diagnostics and simulation analysis. By the end of this page you will know how to assess whether a run converged, how to extract generation and cost statistics across scenarios, and how to identify common problems from the output data.

Convergence Diagnostics

Reading the gap from training/metadata.json

The manifest is the first place to check after any run. The key fields for convergence assessment are:

{
  "convergence": {
    "achieved": false,
    "final_gap_percent": 0.6,
    "termination_reason": "iteration_limit"
  },
  "iterations": {
    "completed": 128,
    "converged_at": null
  }
}

Gap guidelines. There is no universal threshold — acceptable gap depends on the decision being made and the study’s time horizon. As rough guidance:

• Below 1%: acceptable for most decisions. The policy cost is within 1% of the theoretical optimum.
• 1% to 5%: acceptable for long-horizon planning studies where model uncertainty is already large.
• Above 5%: warrants investigation. The policy may be significantly suboptimal.

What to do if the gap is large:

1. Increase limit in the iteration_limit stopping rule.
2. Increase forward_passes in config.json to reduce noise in the upper bound estimate per iteration.
3. Check training/convergence.parquet (see next section) to see whether the gap is still decreasing or has plateaued.
4. Check for solver infeasibilities: if simulation/metadata.json shows failed scenarios, the policy may be encountering numerically difficult stages.

Reading Convergence History

training/convergence.parquet contains one row per training iteration with the full convergence history. Its schema:

Python (Polars)

import polars as pl
import matplotlib.pyplot as plt

df = pl.read_parquet("results/training/convergence.parquet")

# Plot convergence bounds over iterations
plt.figure(figsize=(10, 4))
plt.plot(df["iteration"], df["lower_bound"], label="Lower bound")
plt.plot(df["iteration"], df["upper_bound_mean"], label="Upper bound (mean)")
plt.fill_between(
    df["iteration"].to_list(),
    (df["upper_bound_mean"] - df["upper_bound_std"]).to_list(),
    (df["upper_bound_mean"] + df["upper_bound_std"]).to_list(),
    alpha=0.2,
    label="Upper bound ± 1 std",
)
plt.xlabel("Iteration")
plt.ylabel("Expected cost ($/stage)")
plt.legend()
plt.tight_layout()
plt.show()

# Check final gap
final = df.filter(pl.col("iteration") == df["iteration"].max())
print(final.select(["iteration", "lower_bound", "upper_bound_mean", "gap_percent"]))

R

library(arrow)
library(ggplot2)

df <- read_parquet("results/training/convergence.parquet")

# Plot convergence bounds
ggplot(df, aes(x = iteration)) +
  geom_line(aes(y = lower_bound, color = "Lower bound")) +
  geom_line(aes(y = upper_bound_mean, color = "Upper bound")) +
  geom_ribbon(
    aes(
      ymin = upper_bound_mean - upper_bound_std,
      ymax = upper_bound_mean + upper_bound_std
    ),
    alpha = 0.2
  ) +
  labs(
    x = "Iteration",
    y = "Expected cost ($/stage)",
    color = NULL
  ) +
  theme_minimal()

# Print final gap
tail(df[, c("iteration", "lower_bound", "upper_bound_mean", "gap_percent")], 1)

What to look for in the convergence plot:

• Both bounds should move toward each other over iterations. The lower bound rises; the upper bound mean falls and its standard deviation narrows.
• A lower bound that stays flat after the first few iterations suggests the backward pass cuts are not improving: check cuts_added to confirm cuts are being generated.
• An upper bound that oscillates widely without narrowing suggests the forward_passes count is too low to produce a stable estimate.

Analyzing Simulation Results

The simulation output is Hive-partitioned: results are stored in one data.parquet file per scenario under simulation/<category>/scenario_id=NNNN/. Polars, Pandas, R arrow, and DuckDB all support reading the entire directory as a single table and filtering by scenario_id at the storage layer.

Aggregating across scenarios

The most common operation is computing statistics across all scenarios for a given entity or stage.

Python (Polars) — mean and percentiles:

import polars as pl

# Load all hydro results across all scenarios
hydros = pl.read_parquet("results/simulation/hydros/")

# Mean generation per hydro plant per stage, across all scenarios
mean_gen = (
    hydros
    .group_by(["hydro_id", "stage_id"])
    .agg(
        pl.col("generation_mwh").mean().alias("mean_generation_mwh"),
        pl.col("generation_mwh").quantile(0.10).alias("p10_generation_mwh"),
        pl.col("generation_mwh").quantile(0.90).alias("p90_generation_mwh"),
    )
    .sort(["hydro_id", "stage_id"])
)
print(mean_gen)

R:

library(arrow)
library(dplyr)

# Load all hydro results
hydros <- open_dataset("results/simulation/hydros/") |> collect()

# Mean and P10/P90 generation per hydro plant per stage
mean_gen <- hydros |>
  group_by(hydro_id, stage_id) |>
  summarise(
    mean_generation_mwh = mean(generation_mwh),
    p10_generation_mwh  = quantile(generation_mwh, 0.10),
    p90_generation_mwh  = quantile(generation_mwh, 0.90),
    .groups = "drop"
  ) |>
  arrange(hydro_id, stage_id)

print(mean_gen)

Filtering to a single scenario

# Polars — read only scenario 0 (avoids loading all partitions)
costs_s0 = pl.read_parquet(
    "results/simulation/costs/",
    hive_partitioning=True,
).filter(pl.col("scenario_id") == 0)

-- DuckDB
SELECT * FROM read_parquet('results/simulation/costs/**/*.parquet')
WHERE scenario_id = 0
ORDER BY stage_id;

Common Analysis Tasks

(a) Expected generation by hydro plant

import polars as pl

hydros = pl.read_parquet("results/simulation/hydros/")
expected = (
    hydros
    .group_by("hydro_id")
    .agg(pl.col("generation_mwh").mean().alias("mean_annual_generation_mwh"))
    .sort("hydro_id")
)
print(expected)

(b) Expected thermal generation cost

thermals = pl.read_parquet("results/simulation/thermals/")
thermal_cost = (
    thermals
    .group_by("thermal_id")
    .agg(pl.col("generation_cost").mean().alias("mean_total_cost"))
    .sort("thermal_id")
)
print(thermal_cost)

In R:

library(arrow)
library(dplyr)

thermals <- open_dataset("results/simulation/thermals/") |> collect()

thermal_cost <- thermals |>
  group_by(thermal_id) |>
  summarise(mean_total_cost = mean(generation_cost), .groups = "drop") |>
  arrange(thermal_id)

print(thermal_cost)

(c) Deficit probability per bus

A scenario has a deficit at a given stage if deficit_mwh > 0 for any bus in that stage. The deficit probability is the fraction of scenarios where this occurs.

buses = pl.read_parquet("results/simulation/buses/")
n_scenarios = buses["scenario_id"].n_unique()

deficit_prob = (
    buses
    .group_by(["bus_id", "stage_id"])
    .agg(
        (pl.col("deficit_mwh") > 0).mean().alias("deficit_probability")
    )
    .sort(["bus_id", "stage_id"])
)
print(deficit_prob)

(d) Water value (shadow price) from hydro output

The water_value_per_hm3 column in simulation/hydros/ records the shadow price of reservoir storage at each stage — the marginal value of having one additional hm³ of stored water. This is the water value, a key output of the SDDP policy.

hydros = pl.read_parquet("results/simulation/hydros/")
water_value = (
    hydros
    .group_by(["hydro_id", "stage_id"])
    .agg(pl.col("water_value_per_hm3").mean().alias("mean_water_value"))
    .sort(["hydro_id", "stage_id"])
)
print(water_value)

A high water value at a given stage means the reservoir is scarce relative to expected future demand — the solver is conserving water for later stages. A water value near zero means the reservoir is abundant and water has little marginal value at that point in time.

Using cobre report

cobre report provides a quick machine-readable summary without loading any Parquet files:

cobre report results/

Use it in scripts or CI pipelines to extract a specific metric without writing a data loading script:

# Check the final gap in a CI pipeline
gap=$(cobre report results/ | jq '.training.convergence.final_gap_percent')
echo "Final gap: ${gap}%"

For all available cobre report fields and flags, see CLI Reference.

Troubleshooting

Gap not converging

The gap stays large after many iterations, or the lower bound rises very slowly.

Possible causes:

• Too few iterations. The most common cause. Increase the iteration_limit.
• Too few forward passes. A forward_passes count of 1 (as in the 1dtoy tutorial) gives high variance in the upper bound estimate. Raising the forward_passes count averages the estimate over more scenarios per iteration.
• Numerically difficult stages. Check training/convergence.parquet for iterations where cuts_added is zero — this can indicate stages where the backward pass is not generating improving cuts.
• Policy horizon issues. Verify stages.json has the correct stage ordering and that policy_graph.type is set correctly.

Unexpected deficit

Simulation scenarios show non-zero deficit_mwh in simulation/buses/ but the system should have enough capacity.

Possible causes:

• Insufficient thermal capacity. Compare total load (load_mw summed across buses) against total thermal capacity. If load exceeds generation capacity in some scenarios, deficit is unavoidable.
• Hydro reservoir ran dry. Check storage_final_hm3 in simulation/hydros/. If it hits zero in early stages, subsequent stages have no hydro generation and may resort to deficit.
• Very low deficit penalty. If deficit_segments in penalties.json are priced below thermal generation cost, the solver will prefer deficit over generation. Increase the deficit cost.

Zero generation from a plant

A thermal or hydro plant shows zero generation in all scenarios.

Possible causes:

• Plant is more expensive than deficit. Check the plant’s cost against the bus deficit penalty. If the cost exceeds the penalty, deficit is cheaper and the solver avoids dispatching the plant.
• Bus connectivity. Verify the plant’s bus_id matches a bus that actually has load. A plant connected to a zero-load bus will never be dispatched.
• Hydro: reservoir constraints too tight. If min_storage_hm3 is close to the initial storage level, the solver cannot turbine water without risking a storage violation. Review initial_conditions.json and storage bounds in hydros.json.

Related Pages

• Understanding Results — file-by-file walkthrough of every output artifact
• Output Format Reference — complete field-by-field schema for all output files
• Configuration — all config.json fields including stopping rules and seed

CLI Reference

Synopsis

cobre [--color <WHEN>] <SUBCOMMAND> [OPTIONS]

Global Options

Subcommands

cobre init

Scaffolds a new case directory from an embedded template. Creates all required input files (config.json, penalties.json, stages.json, system files, etc.) so a new user can start from a working example.

Arguments

Options

Examples

# List available templates
cobre init --list

# Scaffold the 1dtoy example in a new directory
cobre init --template 1dtoy my_study

# Overwrite files in an existing directory
cobre init --template 1dtoy --force my_study

cobre run

Executes the full solve lifecycle for a case directory:

1. Load — reads all input files and runs the layered validation pipeline
2. Train — trains an SDDP policy using the configured stopping rules
3. Simulate — (optional) evaluates the trained policy over simulation scenarios
4. Write — writes all output files to the results directory

Whether simulation runs is controlled by simulation.enabled in config.json. Stochastic artifact export is controlled by exports.stochastic in config.json.

Arguments

Options

Config-First Principle

The CLI follows a config-first design: config.json defines what to compute, CLI flags define how to run it. A study is fully specified by its case directory — the same case produces the same results regardless of which CLI flags are used.

Examples

# Run a study with default output location
cobre run /data/cases/hydro_study

# Write results to a custom directory
cobre run /data/cases/hydro_study --output /data/results/run_001

# Use 4 worker threads per MPI rank
cobre run /data/cases/hydro_study --threads 4

# Run without any terminal decorations (useful in scripts)
cobre run /data/cases/hydro_study --quiet

# Force color output when running under mpiexec
cobre --color always run /data/cases/hydro_study

# Run with MPI across 4 ranks
mpiexec -np 4 cobre run /data/cases/hydro_study

SLURM clusters

On SLURM-managed clusters, launch Cobre with srun instead of mpiexec. SLURM handles process placement, CPU binding, and NUMA-aware memory allocation automatically.

Basic launch:

srun --mpi=pmi2 -n 4 ./cobre-mpi run /data/cases/hydro_study

Hybrid MPI + threads (recommended for production):

Cobre uses MPI for inter-node communication and rayon threads for intra-node parallel LP solves. Set --cpus-per-task to control the thread count per rank:

#!/bin/bash
#SBATCH --job-name=cobre
#SBATCH --nodes=4
#SBATCH --ntasks-per-node=2
#SBATCH --cpus-per-task=16
#SBATCH --mem-bind=local
#SBATCH --output=cobre_%j.log

# Pin each rank to its allocated cores; use NUMA-local memory.
srun --cpu-bind=cores --mpi=pmi2 ./cobre-mpi run /data/case \
    --threads "$SLURM_CPUS_PER_TASK"

Key SLURM flags for Cobre:

Tip: On modern SLURM clusters (22.05+), --mpi=pmix is preferred over --mpi=pmi2 for better scalability. Check your cluster’s default with srun --mpi=list.

cobre validate

Runs the layered validation pipeline and prints a diagnostic report to stdout.

On success, prints entity counts:

Valid case: 3 buses, 12 hydros, 8 thermals, 4 lines
  buses: 3
  hydros: 12
  thermals: 8
  lines: 4

On failure, prints each error prefixed with error: and exits with code 1.

Arguments

Options

None.

Examples

# Validate a case directory before running
cobre validate /data/cases/hydro_study

# Use in a script: only proceed if validation passes
cobre validate /data/cases/hydro_study && cobre run /data/cases/hydro_study

cobre report

Reads the JSON manifests written by cobre run and prints a JSON summary to stdout.

The output has the following top-level shape:

{
  "output_directory": "/abs/path/to/results",
  "status": "complete",
  "bounds": { "final_lower_bound": ..., "final_upper_bound": ... },
  "training": { "iterations": {}, "convergence": {}, "row_pool": {}, "bounds": {}, "configuration": {}, "problem_dimensions": {} },
  "cost": { "mean_cost": ..., "std_cost": ... } | null,
  "simulation": { "scenarios": {}, "cost": {} } | null
}

cost and simulation are null when the corresponding files are absent (e.g., when simulation was disabled in config.json).

Arguments

Options

None.

Examples

# Print the full report to the terminal
cobre report /data/cases/hydro_study/output

# Extract the convergence gap using jq
cobre report /data/cases/hydro_study/output | jq '.training.convergence.final_gap_percent'

# Check the run status in a script
status=$(cobre report /data/cases/hydro_study/output | jq -r '.status')
if [ "$status" = "complete" ]; then
  echo "Training converged"
fi

cobre summary

Reads the training manifest and convergence log from a completed run’s output directory and prints the same human-readable summary table that cobre run displays at the end of a study. This lets users inspect a past run without re-executing it.

All output goes to stderr, matching the cobre run convention. stdout is reserved for machine-readable output (see cobre report).

File resolution

Output format

Training complete in 3m 42s (42 iterations, converged at iter 38)
  Lower bound:  4.85000e4 $/stage
  Upper bound:  4.90000e4 +/- 2.50000e2 $/stage
  Gap:          1.0%
  Cuts:         980000 active / 1250000 generated
  LP solves:    84000

Simulation complete in 0.0s (200 scenarios)
  Completed: 198  Failed: 2

The simulation section is omitted when simulation/metadata.json is absent (e.g., when simulation was disabled in config.json).

Arguments

Options

None.

Examples

# Print the summary for a completed run
cobre summary /data/cases/hydro_study/output

# Inspect a run that used a custom output directory
cobre summary /data/results/run_001

cobre schema

Manages JSON Schema files for case directory input types. Currently supports exporting schemas.

Subcommands

Examples

# Export schemas to the current directory
cobre schema export

# Export schemas to a specific directory
cobre schema export --output-dir /data/schemas

cobre version

Prints the binary version, active solver and communication backends, compression support, host architecture, and build profile.

Output Format

cobre   v0.9.1
solver: HiGHS
comm:   local
zstd:   enabled
arch:   x86_64-linux
build:  release (lto=thin)

Arguments

None.

Options

None.

Exit Codes

All subcommands follow the same exit code convention.

Codes 1–2 indicate user-correctable input problems; codes 3–4 indicate case/environment problems. Error messages are printed to stderr with error: prefix and hint lines. See Error Codes for a detailed catalog.

Environment Variables

The 1dtoy Example

The 1dtoy case ships in examples/1dtoy/ in the Cobre repository. It is the smallest complete hydrothermal dispatch problem that exercises every stage of the workflow: input loading, layered validation, stochastic training, and post-training simulation. The case solves in under a second and produces inspectable output files.

This page is a self-contained annotated reference. For the pedagogical walkthrough that explains each file field by field, see Anatomy of a Case. For the complete schema reference, see Case Format Reference.

System Description