Input Hydro Extensions

Purpose

This spec defines the optional extension files for the hydro subsystem: reservoir geometry, production function model selection, and pre-computed FPHA hyperplanes. These files augment the core hydro registry defined in Input System Entities and live under system/ in the input case directory.

For other system elements (pumping stations, energy contracts, non-controllable sources), see Input System Entities. For deferred features (battery storage), see Deferred Features.

1. Hydro Geometry (system/hydro_geometry.parquet) — Optional

Format Rationale

Entity-level lookup table — Per-hydro tabular data (Volume-Height-Area curves) with multiple rows per hydro forming a static physical relationship. Parquet for typed columnar data with efficient per-hydro filtering.

Defines the Volume-Height-Area relationship for reservoirs. This data is used for:

• Evaporation modeling: Surface area as a function of storage determines evaporated volume (see evaporation coefficients in Input System Entities §3)
• Forebay level: Storage-to-height relationship for production function models that account for head variation (linearized_head, fpha)

Instead of polynomial fits, Cobre uses a tabular approach with linear interpolation — more transparent and easier to validate against surveyed data.

For the mathematical formulation of evaporation linearization and forebay level computation, see Hydro Production Functions and System Element Modeling.

Schema

Example rows (Sobradinho):

Validation

2. Hydro Production Models (system/hydro_production_models.json) — Optional

Format Rationale

Registry — Small config selecting model type per hydro with nested optional params and stage/season configuration. JSON handles optional/nested structures well.

Configures the hydro production function (HPF) modeling approach per hydro. Different stages or seasons can use different accuracy levels. See Hydro Production Functions for the mathematical formulation.

Model Hierarchy (increasing complexity and accuracy):

1. constant_productivity: Fixed productivity factor — single multiplication, fastest
2. linearized_head: Accounts for head variation with storage — requires geometry data. Simulation-only — excluded from training because the bilinear term changes the LP between iterations, breaking SDDP convergence (see Hydro Production Models §3)
3. fpha: Full piecewise-linear approximation via hyperplanes — most accurate

See Hydro Production Functions §4 for model selection guidelines and accuracy trade-offs.

Default Behavior: If this file is not provided or a hydro is not listed, the model uses the generation.model field from hydros.json for all stages.

Selection Modes (Tagged Union)

The selection_mode field determines how the model is chosen per stage:

Mode: stage_ranges — Explicit stage ranges (structural changes across the horizon)

{
  "$schema": "https://cobre.dev/schemas/v2/production_models.schema.json",
  "production_models": [
    {
      "hydro_id": 0,
      "selection_mode": "stage_ranges",
      "stage_ranges": [
        {
          "start_stage_id": 0,
          "end_stage_id": 24,
          "model": "fpha",
          "fpha_config": {
            "source": "computed",
            "volume_discretization_points": 7,
            "turbine_discretization_points": 15,
            "fitting_window": {
              "volume_min_hm3": null,
              "volume_max_hm3": null
            }
          }
        },
        {
          "start_stage_id": 25,
          "end_stage_id": null,
          "model": "constant_productivity"
        }
      ]
    }
  ]
}

Mode: seasonal — Model selection keyed by season index, cycling across the horizon

Each stage is mapped to its season via the stage-to-season mapping defined in stages.json (see Input Scenarios). For a monthly study, seasons 0–11 correspond to January–December. This mode is useful for studies where accuracy requirements vary cyclically (e.g., wet season uses FPHA, dry season uses linearized head).

{
  "$schema": "https://cobre.dev/schemas/v2/production_models.schema.json",
  "production_models": [
    {
      "hydro_id": 5,
      "selection_mode": "seasonal",
      "default_model": "linearized_head",
      "seasons": [
        {
          "season_id": 0,
          "model": "fpha",
          "fpha_config": {
            "source": "computed",
            "volume_discretization_points": 5,
            "turbine_discretization_points": 10
          }
        },
        {
          "season_id": 1,
          "model": "fpha",
          "fpha_config": {
            "source": "computed",
            "volume_discretization_points": 5,
            "turbine_discretization_points": 10
          }
        }
      ]
    }
  ]
}

In this example, seasons 0 and 1 (e.g., January and February — wet season) use FPHA; all other seasons fall back to default_model (linearized head).

Note: This example uses linearized_head as the default model, which restricts this hydro’s configuration to simulation only. For training, replace the default_model with constant_productivity or fpha. See Hydro Production Models §3.

Combined usage: Different hydros in the same file can use different selection modes. Stage ranges and seasonal modes can coexist across hydros but not within a single hydro.

Selection Mode Fields

Stage Range Fields

Season Fields

FPHA Configuration Fields

Use absolute bounds (volume_min_hm3, volume_max_hm3) OR percentiles, not both. Percentiles are relative to [min_storage_hm3, max_storage_hm3] from hydros.json.

Implementation note (v0.1.4): spillage_discretization_points and max_planes_per_hydro were added in v0.1.4 when the computed-source FPHA pipeline was implemented. The default for turbine_discretization_points is 5 (not 10 as originally specced); both defaults produce grids sufficient for typical reservoir configurations. All discretization counts must be >= 2; max_planes_per_hydro must be >= 1. The computed source path is fully implemented — no preprocessing step or external tool is required. Hyperplanes are fitted during the Initialization phase on rank 0 and written to output/hydro_models/fpha_hyperplanes.parquet.

Required Data by Model

¹ Used as fallback for stages without FPHA configuration.

Implementation note (v0.1.4): The "computed" source path is implemented. Fitting runs during Initialization on MPI rank 0 from hydro_geometry.parquet and the tailrace, hydraulic_losses, and efficiency fields in hydros.json. Fitted planes are exported to output/hydro_models/fpha_hyperplanes.parquet using the same 11-column schema as the input file, enabling round-trip use in subsequent runs as "precomputed" planes.

Note: For computed FPHA, the solver also uses the optional tailrace, hydraulic_losses, and efficiency fields from the hydro object in hydros.json (see Input System Entities §3). If these fields are omitted, fallback assumptions apply (no tailrace adjustment, zero losses, efficiency derived from productivity).

3. FPHA Hyperplanes (system/fpha_hyperplanes.parquet) — Optional

Format Rationale

Pre-computed coefficient table — Per-hydro tabular data with many rows of hyperplane coefficients, potentially varying by stage. Parquet for typed columnar data with efficient per-hydro filtering.

Pre-computed FPHA hyperplane coefficients for hydro production function modeling. Allows using externally-fitted planes instead of computing them at runtime. Different stages can have different plane sets per hydro (e.g., near-term fitting with more detail vs. far-term with fewer planes).

If not provided, Cobre computes hyperplanes from hydro_geometry data and the hydro object’s tailrace/losses/efficiency fields during preprocessing.

Schema

Example rows (Itaipu):

For the mathematical formulation of how these hyperplanes define the production function constraint, see Hydro Production Functions.

Validation

Cross-References

• Input System Entities — Core hydro registry (hydros.json) with optional tailrace, hydraulic losses, efficiency, and evaporation fields; pumping stations, energy contracts, and all other system elements
• Input Directory Structure — Overall case directory layout
• Input Constraints — Time-varying bounds for hydros, thermals, lines, and contracts
• Hydro Production Functions — Mathematical formulation of HPF models, FPHA constraint form, correction factor κ
• LP Formulation — How hydro variables enter the LP
• System Element Modeling — Evaporation linearization, forebay level computation
• Deferred Features — Battery storage
• Design Principles §3 — Order invariance and canonical ordering