Skip to content

Hydro Model Artifacts

training/hydro_models.json summarizes the production and evaporation models in use.

The hydro_models/ directory holds the three files that follow training/hydro_models.json. Each is written only when it has rows — fitted FPHA planes, evaporation models, or, with exports.fpha_deviation_points set to true, deviation points — and the directory is absent when none is written.


Aggregated production- and evaporation-model counts, per-hydro detail for every plant that uses an FPHA production model, and the list of plants with no turbine capacity (a computed-FPHA plant, or a precomputed one with no hyperplane rows). The file also lists the hydros whose turbining is frozen at some study stage, or whose turbined-flow or generation minimum the LP does not charge. Always written.

Methodology: Hydro Production Function Models

Top-level object:

NameTypeNullableUnitsDescription
n_constantintegerNo—Number of hydro plants with constant productivity at every stage: plants whose production-model entries select no FPHA model, and plants with no turbine capacity (a computed-FPHA plant, or a precomputed one with no hyperplane rows), modelled with zero productivity and listed in no_turbine_capacity.
n_fphaintegerNo—Number of hydro plants with precomputed or computed FPHA hyperplanes in at least one production-model entry; a plant with no turbine capacity (a computed-FPHA plant, or a precomputed one with no hyperplane rows) is counted in n_constant instead.
total_planesintegerNo—Sum of n_planes over fpha_details: each FPHA plant’s hyperplanes at the first study stage.
fpha_detailsarrayNo—Per-hydro detail for each plant counted in n_fpha (see below).
no_turbine_capacityarrayNo—Plants that request FPHA (a computed-FPHA plant, or a precomputed one with no hyperplane rows) whose declared max_turbined_m3s or max_generation_mw gives them no turbine capacity, ascending by hydro_id; always present ([] when none); each is also counted in n_constant (see below).
frozen_turbiningarrayNo—Hydros with a (hydro, bus) cell without turbine capacity at some block of a study stage, or with a minimum the LP does not charge (Plant Minimum and Maximum), ascending by hydro_id; always present ([] when none) (see below).
n_evaporationintegerNo—Number of hydro plants with a linearized evaporation model.
n_no_evaporationintegerNo—Number of hydro plants with no evaporation model.
n_user_supplied_refintegerNo—Number of evaporation plants that used user-supplied reference volumes.
n_default_midpoint_refintegerNo—Number of evaporation plants that used the default midpoint reference.

fpha_details[] fields:

NameTypeNullableUnitsDescription
fpha_details[].hydro_idintegerNo—Entity identifier of the hydro plant.
fpha_details[].namestringNo—Human-readable name of the hydro plant.
fpha_details[].sourcestringNo—Origin of the plant’s hyperplanes: "precomputed_hyperplanes" or "computed_from_geometry".
fpha_details[].n_planesintegerNo—Number of the plant’s hyperplanes at the first study stage (0 when that stage uses constant productivity).

no_turbine_capacity[] fields:

NameTypeNullableUnitsDescription
no_turbine_capacity[].hydro_idintegerNo—Entity identifier of the hydro plant.
no_turbine_capacity[].namestringNo—Human-readable name of the hydro plant.

frozen_turbining[] fields:

NameTypeNullableUnitsDescription
frozen_turbining[].hydro_idintegerNo—Entity identifier of the hydro plant.
frozen_turbining[].namestringNo—Human-readable name of the hydro plant.
frozen_turbining[].no_capacity_stage_idsarrayNo—Integer study stage ids, ascending, where no (hydro, bus) cell of the plant has turbine capacity at any block.
frozen_turbining[].partial_capacity_stage_idsarrayNo—Integer study stage ids, ascending and disjoint from no_capacity_stage_ids, where some, but not every, (cell, block) has turbine capacity.
frozen_turbining[].dropped_floorsarrayNo—Minima the LP does not charge (see below).

frozen_turbining[].dropped_floors[] fields:

NameTypeNullableUnitsDescription
frozen_turbining[].dropped_floors[].stage_idintegerNo—Study stage id.
frozen_turbining[].dropped_floors[].block_idintegerNo—Block id within the stage.
frozen_turbining[].dropped_floors[].floorstringNo—The dropped minimum: "min_turbined_m3s" or "min_generation_mw".
frozen_turbining[].dropped_floors[].levelstringNo—Whether the minimum is the plant’s own or a unit group’s: "plant" or "unit_group".
frozen_turbining[].dropped_floors[].hydro_unit_group_idintegerYes—Unit group id; null exactly when level is "plant".
frozen_turbining[].dropped_floors[].bus_idintegerYes—The unit group’s bus; null exactly when level is "plant".
frozen_turbining[].dropped_floors[].valuenumberNom³/s or MWResolved minimum, always > 0, in the unit of floor.
frozen_turbining[].dropped_floors[].reasonstringNo—"no_capacity" (the plant or the unit group has no turbine capacity at the block) or "commissioning" (the plant is PreFilling or Filling at the stage).

dropped_floors is sorted by stage_id, block_id, level, hydro_unit_group_id, then floor. A "plant" record appears where the plant’s own minimum is positive and the plant cannot produce at the block; a "unit_group" record appears where the group’s minimum is positive and the plant cannot produce there, or the group itself has no capacity.


Fitted FPHA hyperplane coefficients for every hydro whose computed fit produced planes in the current run, with rows only for the stages that select FPHA; a plant with no turbine capacity (a computed-FPHA plant, or a precomputed one with no hyperplane rows) has none. The schema is identical to the input file system/fpha_hyperplanes.parquet: 11 columns, all with the same names, types, and nullability.

Methodology: Hydro Production Function Models

NameTypeNullableUnitsDescription
hydro_idInt32No—Hydro plant ID
stage_idInt32Yes—Stage the plane applies to. null = valid for all stages
plane_idInt32No—Plane index within this hydro (and stage)
gamma_0Float64NoMWIntercept coefficient (MW), unscaled
gamma_vFloat64NoMW/hm³Volume coefficient (MW/hm³)
gamma_qFloat64NoMW/(m³/s)Turbined flow coefficient (MW per m³/s)
gamma_sFloat64NoMW/(m³/s)Spillage coefficient (MW per m³/s)
kappaFloat64Yes—Correction factor. Defaults to 1.0 when absent or null.
valid_v_min_hm3Float64Yeshm³Volume range minimum where this plane is valid (hm³)
valid_v_max_hm3Float64Yeshm³Volume range maximum where this plane is valid (hm³)
valid_q_max_m3sFloat64Yesm³/sMaximum turbined flow where this plane is valid (m³/s)

In a written file every row carries a stage_id and kappa is 1.0; the three valid_* columns are null. The file is written atomically (via a .tmp rename), with rows in canonical hydro order, then stage and plane order; the input loader sorts them by (hydro_id, stage_id, plane_id). It can be used directly as a future source: "precomputed" input by copying it to system/fpha_hyperplanes.parquet. A plant with no turbine capacity (a computed-FPHA plant, or a precomputed one with no hyperplane rows) has no rows in the file and needs none: copied to system/, the file reloads the fit as it is, and the plant resolves to zero productivity again, listed in no_turbine_capacity; every other FPHA plant needs rows.

See Production Model Files — system/fpha_hyperplanes.parquet for the full column definitions and validity constraints.


Written when any hydro plant has an evaporation model. Contains the fitted evaporation coefficients for all plants that have evaporation, keyed by (hydro_id, stage_id). Rows with stage_id = null are per-hydro defaults.

Methodology: LP Formulation

Six columns:

NameTypeNullableUnitsDescription
hydro_idInt32No—Hydro plant identifier
stage_idInt32Yes—Stage; null = per-hydro default applicable to all stages
intercept_m3sFloat64Nom³/sEvaporation intercept coefficient (m³/s)
volume_slope_m3s_per_hm3Float64No(m³/s)/hm³Volume-dependent slope coefficient (m³/s per hm³)
reference_volume_hm3Float64Nohm³Reference volume used for linearisation (hm³)
sourceUtf8No—Derivation label (e.g. "default_midpoint" or "user_supplied")

Written only when exports.fpha_deviation_points: true is set in config.json. Contains one row per (hydro, stage, V, Q) grid point at spillage = 0, recording how closely the fitted FPHA plane set approximates the exact production function at each sample point. Opt-in because it can be large (one row per grid-point combination for each FPHA stage of a computed-FPHA plant; a stage of that plant that uses another production model has no rows).

Methodology: Hydro Production Function Models

Eight columns:

NameTypeNullableUnitsDescription
hydro_idInt32No—Hydro plant identifier
stage_idInt32Yes—Stage. Nullable in the schema; always set in written output.
vFloat64Nohm³Volume sample point (hm³)
qFloat64Nom³/sTurbined-flow sample point (m³/s)
fph_exactFloat64NoMWExact production function value at this (V, Q) point, capped at the plant’s max_generation_mw (MW)
fpha_fittedFloat64NoMWFitted FPHA approximation at this (V, Q) point (MW)
deviationFloat64NoMWSigned residual fpha_fitted − fph_exact (MW); positive = fitted cap above the exact surface
relativeFloat64No—|deviation| relative to the grid’s peak exact generation (dimensionless, ≥ 0); 0 when the grid peak ≤ 0

The values are a pure function of geometry and config — the file is reproducible when emitted and never enters the parity hash.