Skip to content

Constraint Files

This page documents the constraints/ files that override entity bounds per stage and block (thermal, hydro, hydro unit group, line, pumping, contract and NCS bounds) and the files that define generic constraints: generic_constraints.json, generic_constraint_bounds.parquet and generic_parameters.json. The other case files, including the penalty overrides that share the constraints/ directory, are listed in the Case Format overview.

All bounds Parquet files use sparse storage: only (entity_id, stage_id) pairs that differ from the base entity-level value need rows. Absent rows use the entity-level value unchanged.


Methodology: Equipment-Specific Formulations

Stage-varying generation and cost overrides for thermal plants.

NameTypeRequiredDefaultUnitsDescription
thermal_idInt32Yes——Thermal plant ID
stage_idInt32Yes——Stage ID
min_generation_mwFloat64No—MWMinimum generation override (MW)
max_generation_mwFloat64No—MWMaximum generation override (MW)
cost_per_mwhFloat64No—USD/MWhDispatch cost override (USD/MWh): for the stage on a row with a null block_id, for that block on a row with one
block_idInt32 (nullable)No——Zero-based block index within the stage, selecting one block’s min_generation_mw/max_generation_mw/cost_per_mwh override. null applies at the stage level. Any block_id on a thermal declaring anticipated_config is rejected at validation.

cost_per_mwh is block-eligible, like contract_bounds.price_per_mwh. Each column resolves on its own for each block: the value on the block’s row, else the value on the stage row, else the plant’s value in system/thermals.json (thermals[].cost_per_mwh for the cost). A null value falls through to the next level; an explicit 0.0 is kept.

Validation:

  • Every override value must be finite; cost_per_mwh must be >= 0.

Methodology: System Element Modeling Overview

Stage-varying operational bound overrides for hydro plants.

NameTypeRequiredDefaultUnitsDescription
hydro_idInt32Yes——Hydro plant ID
stage_idInt32Yes——Stage ID
min_turbined_m3sFloat64No—m³/sPlant-level minimum turbined flow (m³/s). Where it exceeds the sum of the unit groups’ resolved minima, it binds on the plant’s total turbined flow, a shortfall charged once at the plant’s penalty; a lower value leaves the groups’ minima binding, and setup warns about it. It is dropped, not charged, where the plant cannot produce, for example at a block where it has no turbine capacity (Plant Minimum and Maximum)
max_turbined_m3sFloat64No—m³/sMaximum turbined flow (m³/s). Caps every bus’s share, and, on a plant whose unit groups sit on several buses, the plant’s total where it is below the sum of the buses’ capacities
min_storage_hm3Float64No—hm³Minimum reservoir storage (hm³)
max_storage_hm3Float64No—hm³Maximum reservoir storage (hm³)
min_outflow_m3sFloat64No—m³/sMinimum total outflow (m³/s)
max_outflow_m3sFloat64No—m³/sMaximum total outflow (m³/s)
min_generation_mwFloat64No—MWPlant-level minimum generation (MW). Where it exceeds the sum of the unit groups’ resolved minima, it binds on the plant’s total generation, a shortfall charged once at the plant’s penalty; a lower value leaves the groups’ minima binding, and setup warns about it. It is dropped, not charged, where the plant cannot produce, for example at a block where it has no turbine capacity (Plant Minimum and Maximum)
max_generation_mwFloat64No—MWMaximum generation (MW). Caps every bus’s share, and, on a plant whose unit groups sit on several buses, the plant’s total where it is below the sum of the buses’ capacities
max_diversion_m3sFloat64No—m³/sMaximum diversion flow (m³/s); a positive value requires a declared diversion channel
min_diversion_m3sFloat64No—m³/sMinimum diversion flow (m³/s); a positive value requires a declared diversion channel
min_spillage_m3sFloat64No—m³/sMinimum spillage flow (m³/s)
max_spillage_m3sFloat64No—m³/sMaximum spillage flow (m³/s); >= min_spillage_m3s
filling_min_rate_m3sFloat64No—m³/sFilling minimum-rate override (m³/s)
water_withdrawal_m3sFloat64No—m³/sWater withdrawal (m³/s)
block_idInt32 (nullable)No——Zero-based block index within the stage, selecting one block’s turbined/outflow/generation/diversion/spillage override. null applies at the stage level. A non-null min_storage_hm3/max_storage_hm3/filling_min_rate_m3s/water_withdrawal_m3s value on the same row is rejected at validation — those four stay stage-level only, with no per-block variant.

A positive min_diversion_m3s or max_diversion_m3s override on a hydro that declares no diversion channel is rejected at validation — with no channel, the diversion column is pinned [0, 0]: a positive floor would be infeasible, and a positive ceiling would divert water that no plant receives. min_diversion_m3s, min_spillage_m3s, and max_spillage_m3s must each be non-negative, and a row combining min_spillage_m3s and max_spillage_m3s with min_spillage_m3s > max_spillage_m3s is rejected. See Error Codes for the full failure-mode catalog.

A plant’s own declared minima cannot exceed its unit groups’ summed minima, and its declared maxima cannot fall below their summed maxima (see system/hydros.json), so only an override in this file binds the plant’s total. A min_turbined_m3s or min_generation_mw override below the groups’ summed minima has no effect: setup prints a WARN line naming the hydro, the field, the number of affected stages and the first one, and the minima to lower are the groups’ own, in constraints/hydro_unit_group_bounds.parquet. The plant minimum’s shortfall is reported in the turbined_slack_m3s and generation_slack_mw columns of simulation/hydros/.

Validation:

  • A row’s max_turbined_m3s or max_generation_mw must not exceed the plant’s declared value.
  • A row’s max_storage_hm3 must not exceed the reservoir’s max_storage_hm3 in system/hydros.json, and its min_storage_hm3 must not lie below the reservoir’s min_storage_hm3.
  • On every study stage, the storage minimum in force must not exceed the maximum in force. Each is the value on the stage’s row, else the reservoir’s own; equal bounds are accepted. See Stage storage bounds refused at load.
  • Every override value must be finite.
  • filling_min_rate_m3s must be >= 0.

Methodology: System Element Modeling Overview

Stage-varying, optionally per-block bound overrides for a hydro plant’s declared unit groups (hydros[].unit_groups[]; see system/hydros.json). A row overrides one of a group’s four declared bounds for one (hydro_id, hydro_unit_group_id, stage_id), optionally narrowed to a single block; a group with no override row reads its declared value. Group id is unique within its plant, not necessarily dense or 0-based, and hydro_unit_group_id addresses the group by that declared id.

NameTypeRequiredDefaultUnitsDescription
hydro_idInt32Yes——Hydro plant ID
hydro_unit_group_idInt32Yes——Unit group ID (unit_groups[].id), unique within the plant
stage_idInt32Yes——Stage ID
min_turbined_m3sFloat64No—m³/sMinimum turbined flow override for this group (m³/s)
max_turbined_m3sFloat64No—m³/sMaximum turbined flow override for this group (m³/s)
min_generation_mwFloat64No—MWMinimum generation override for this group (MW)
max_generation_mwFloat64No—MWMaximum generation override for this group (MW)
block_idInt32 (nullable)No——Zero-based block index within the stage, selecting one block’s override. null applies at the stage level; all four bound columns are block-eligible.

Validation:

  • A row’s max_turbined_m3s or max_generation_mw must not exceed that group’s declared value.
  • Every override value must be finite.

Methodology: Equipment-Specific Formulations

Stage-varying, absolute-MW flow capacity overrides for transmission lines.

NameTypeRequiredDefaultUnitsDescription
line_idInt32Yes——Transmission line ID
stage_idInt32Yes——Stage ID
direct_mwFloat64No—MWDirect-flow capacity override (MW)
reverse_mwFloat64No—MWReverse-flow capacity override (MW)
block_idInt32 (nullable)No——Zero-based block index within the stage, selecting one block’s direct_mw/reverse_mw override. null applies at the stage level.

Per-block line capacity is declared here as absolute MW; direct_mw = 0.0 closes the line in the direct direction for that block, or for the stage when block_id is null (and reverse_mw = 0.0 in the reverse one).


Methodology: Equipment-Specific Formulations

Stage-varying flow bounds for pumping stations.

NameTypeRequiredDefaultUnitsDescription
pumping_station_idInt32Yes——Pumping station ID
stage_idInt32Yes——Stage ID
min_m3sFloat64No—m³/sMinimum pumping flow (m³/s)
max_m3sFloat64No—m³/sMaximum pumping flow (m³/s)
block_idInt32 (nullable)No——Zero-based block index within the stage, selecting one block’s min_m3s/max_m3s override. null applies at the stage level.

Validation:

  • Every override value must be finite and >= 0.
  • A row’s min_m3s must not exceed its max_m3s.

Methodology: Equipment-Specific Formulations

Stage-varying power and price overrides for energy contracts.

NameTypeRequiredDefaultUnitsDescription
contract_idInt32Yes——Energy contract ID
stage_idInt32Yes——Stage ID
min_mwFloat64No—MWMinimum power (MW)
max_mwFloat64No—MWMaximum power (MW)
price_per_mwhFloat64No—USD/MWhPrice override (USD/MWh)
block_idInt32 (nullable)No——Zero-based block index within the stage, selecting one block’s min_mw/max_mw/price_per_mwh override. null applies at the stage level.

price_per_mwh is block-eligible, like thermal_bounds.cost_per_mwh: a study’s simulation cost path honors a per-block contract price.


Methodology: Equipment-Specific Formulations

Stage-varying available generation bounds for non-controllable sources. Absent rows keep the entity’s declared max_generation_mw unchanged; a present row overrides that entity capacity with its per-stage available_generation_mw for the (ncs_id, stage_id) cell. The rows apply to a source with no stochastic availability model. A source with rows in scenarios/non_controllable_stats.parquet, or one that draws its availability from scenarios/external_ncs_scenarios.parquet under the external scheme, ignores its rows here: its available generation follows the model or the realizations (see Equipment-Specific Formulations §6).

NameTypeRequiredDefaultUnitsDescription
ncs_idInt32Yes——Non-controllable source ID
stage_idInt32Yes——Stage ID
available_generation_mwFloat64Yes—MWMaximum available generation for this stage (MW). Must be >= 0.

For a source these rows apply to, the per-block available generation bound in the LP is: available_mw_block = available_generation_mw * block_factor (max_generation_mw in place of available_generation_mw at a stage with no row), where block_factor comes from scenarios/non_controllable_factors.json (default 1.0 when absent).


Methodology: Generic Constraints · LP Formulation

User-defined linear constraints, added to every stage’s LP alongside the built-in constraint set. The file is optional; when absent, no generic constraints are added.

Top-level structure:

{
"constraints": [
{
"id": 1,
"name": "cap_ant_t1",
"expression": "anticipated_decision(2)",
"slack": { "enabled": false }
}
],
"expressions": [
{
"name": "total_hydro",
"expression": "hydro_generation(1) + hydro_generation(2)"
}
]
}

Per-entry fields (constraints[]):

NameTypeRequiredDefaultUnitsDescription
constraints[].idintegerYes——Constraint identifier. Must be unique within the file.
constraints[].namestringYes——Short name used in reports and log output.
constraints[].expressionstringYes——Arithmetic expression over variable references, numbers and @name references, linear in the variables (see below).
constraints[].descriptionstring | nullNo——Optional human-readable description.
constraints[].slackobjectYes——Slack variable configuration: enabled, penalty and penalty_basis.
constraints[].slack.enabledbooleanYes——Whether a slack variable is allowed.
constraints[].slack.penaltynumber | nullConditional—USD/(row unit·h) or USD/row unitPenalty per unit of violation, read under penalty_basis. Required and > 0 when enabled is true; absent when it is false.
constraints[].slack.penalty_basisstring | nullConditional——One of "per_hour", "per_unit". "per_hour" charges the penalty per hour of the row’s period: use it for a row in MW or m³/s; "per_unit" charges it once per unit of violation: use it for a row in MWh or hm³. Required when enabled is true; absent when it is false. See Penalty basis.

Named expressions (expressions[]):

NameTypeRequiredDefaultUnitsDescription
expressionsarrayNo——Named linear expressions shared by every constraint and referenced by @name. Absent means none.
expressions[].namestringYes——Name bound to the expression. Must be unique in the file and distinct from every scalar-parameter name.
expressions[].expressionstringYes——Linear expression that name stands for, written in the same grammar as constraints[].expression with no relational operator; it must read at least one LP variable.
expressions[].descriptionstring | nullNo——Optional human-readable description.

The expression grammar, the variables it can name, named expressions (@name) and how a constraint’s shape follows from its bounds are specified in Generic Constraints: Expression grammar, Variable catalog, The @name grammar, Interval and shape derivation.


Methodology: Generic Constraints · LP Formulation

Stage-varying, optionally per-block RHS bound overrides for generic constraints declared in constraints/generic_constraints.json. This table is the activation grid: a constraint is active at a given (stage[, block]) if and only if a row exists for it here, regardless of whether that row supplies any bound value itself (an inline affine remainder can supply the value instead — see below).

NameTypeRequiredDefaultUnitsDescription
constraint_idInt32Yes——Generic constraint ID
stage_idInt32Yes——Stage ID
block_idInt32 (nullable)No——Zero-based block index within the stage. null applies to all blocks of the given stage. A constraint with a stage-volume term takes null only.
bound_lowerFloat64 (nullable)No——Lower interval endpoint. null when the constraint is unbounded below at this cell.
bound_upperFloat64 (nullable)No——Upper interval endpoint. null when the constraint is unbounded above at this cell.

How the two endpoints set the shape: Interval and shape derivation. Which rows are rejected: The activation grid.


Methodology: Generic Constraints · LP Formulation

Named scalar parameters that can be referenced from generic-constraint coefficient expressions using the @name sigil. The file is optional; when absent, no parameters are loaded and any @name token that names no named expression causes a load error. An expression parameter can also read other parameters by @name.

Top-level structure:

{
"$schema": "https://docs.modelossetoreletrico.org.br/schemas/generic_parameters.schema.json",
"scalar_parameters": [
{
"id": 1,
"name": "rho_eq_h1",
"kind": "computed",
"computed_spec": { "tag": "equivalent_productivity", "hydro_id": 1 }
}
]
}

Per-entry fields:

NameTypeRequiredDefaultUnitsDescription
scalar_parameters[].idintegerYes——Unique parameter identifier (int32)
scalar_parameters[].namestringYes——Unique parameter name (non-empty, no leading/trailing whitespace)
scalar_parameters[].kindstringYes——One of "constant", "per_stage", "seasonal", "computed", "per_stage_block", "expression".
scalar_parameters[].valuenumber | nullConditional——Finite f64 value. Required for constant. Absent otherwise.
scalar_parameters[].valuesarray | nullConditional——Array of [index, value] pairs. Required for per_stage and seasonal.
scalar_parameters[].computed_specobject | nullConditional——{"tag": "<variant>", "hydro_id": <int>}. Required for computed.
scalar_parameters[].computed_spec.tagstringYes——One of "equivalent_productivity", "accumulated_productivity", "reference_volume", "reference_turbine", "min_storage", "max_storage", "specific_productivity", "integrated_equivalent_productivity", "integrated_accumulated_productivity", "max_stored_energy", "integrated_equivalent_productivity_mwh_per_hm3", "integrated_accumulated_productivity_mwh_per_hm3", "max_stored_energy_mwh". See the computed_spec tag values table below.
scalar_parameters[].computed_spec.hydro_idintegerYes——Hydro plant ID.
scalar_parameters[].block_valuesarray | nullConditional——Array of [stage_id, block_id, value] triples. Required for per_stage_block; each (stage_id, block_id) pair within an entry must be unique.
scalar_parameters[].expressionstring | nullConditional——Arithmetic formula over numbers and other scalar parameters (@name), with no LP variable, named expression or relational operator. Required for expression.

computed_spec tag values:

ValueDescription
equivalent_productivityEquivalent productivity ρ_eq
accumulated_productivityAccumulated cascade productivity ρ_acum
reference_volumeReference reservoir volume V_ref
reference_turbineReference turbined flow Q_ref
min_storagePhysical minimum storage reservoir.min_storage_hm3 (the plant’s stage-invariant range, not a hydro_bounds per-stage override)
max_storagePhysical maximum storage reservoir.max_storage_hm3 (the plant’s stage-invariant range, not a hydro_bounds per-stage override)
specific_productivitySpecific productivity ρ_esp
integrated_equivalent_productivityUseful-range mean equivalent productivity ρ̄_eq (forebay level averaged over the physical storage range)
integrated_accumulated_productivityρ̄_eq summed along the downstream cascade — the coefficient that pairs with max_stored_energy
max_stored_energyintegrated_accumulated_productivity × (max_storage_hm3 − min_storage_hm3) over the physical range, in MW/(m³/s)·hm³ — not MWh
integrated_equivalent_productivity_mwh_per_hm3integrated_equivalent_productivity × 10⁶/3600, in MWh/hm³
integrated_accumulated_productivity_mwh_per_hm3integrated_accumulated_productivity × 10⁶/3600, in MWh/hm³ — the coefficient that pairs with max_stored_energy_mwh
max_stored_energy_mwhmax_stored_energy × 10⁶/3600, in MWh

The productivity and stored-energy quantities these tags resolve to are defined in Hydro Production Function Models §4.

Validation:

  • 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 the six legal values, and an entry carries only the payload field of its kind (value, values, computed_spec, block_values or expression); a payload field of another kind is rejected.
  • For per_stage: values pairs must have contiguous stage_id keys starting at 0, one per study stage; duplicates, gaps and a count other than the number of study stages are rejected.
  • For seasonal: season_id keys within an entry must be unique; duplicates are rejected. Every season that a study stage falls in needs a value; a missing one stops study setup, naming the parameter and the season.
  • For computed: computed_spec must be present with a valid tag and integer hydro_id. The referenced hydro must exist in hydros.json.
  • For per_stage_block: block_values must be present, and each (stage_id, block_id) pair within an entry must be unique; duplicates are rejected. The triples must cover every block of every study stage; a missing cell, or one naming a stage or block the study does not have, stops study setup, naming the parameter and the cell.
  • For expression: expression must be present, read only numbers and other scalar parameters, and hold no relational operator; a reference cycle among expression parameters is rejected. A formula whose value is not finite at some stage and block is rejected when the study is prepared.
  • Unknown JSON fields on any entry are rejected immediately.

For what each kind means, see The parameter kinds.