Generic Constraints
Generic constraints are written in an authoring language: three input
files, one output, and a grammar (named @expressions, inline relational
right-hand sides, interval bounds). This page is the authority for that
language. For the per-file field tables, see
Constraint Files; for the LP
formulation these constraints desugar into, see
LP Formulation §10.
For the entity view of this page, see Generic constraints.
File set
Seção intitulada “File set”| File | Role |
|---|---|
constraints/generic_constraints.json | Declares the constraints, each a linear expression over the variable catalog with an optional inline bound and a slack setting, and the named expressions they share; field table: Constraint Files. |
constraints/generic_constraint_bounds.parquet | The activation grid: one row per constraint, stage and optional block the constraint is active for, carrying the nullable lower and upper bound endpoints (the parquet base); field table: Constraint Files. |
constraints/generic_parameters.json | Declares the named scalar parameters that constraint expressions, inline bound endpoints and other named expressions reference by @name; field table: Constraint Files. |
generic_constraints/resolved_echo.parquet (output) | The fully-resolved, desugared form of every generic constraint the solver actually built — one row per (constraint, stage, block, term). Written whenever the study has generic constraints; the directory is entirely absent otherwise. |
Interval and shape derivation
Seção intitulada “Interval and shape derivation”A bound’s shape is derived purely from which of bound_lower/bound_upper
are present, after the parquet base and any inline affine remainder (below)
have been folded together:
bound_lower | bound_upper | Derived shape |
|---|---|---|
| present | absent | floor |
| absent | present | cap |
| present | present, different | band |
| present | present, bit-identical | equality |
| absent | absent | rejected (see the activation grid) |
The equal-vs-different check is an exact bit-for-bit comparison of the two
values, never a tolerance — a very narrow but distinct band stays band, not
equality.
For example, one constraint with both endpoints on its bounds row derives the
band shape:
{ "constraints": [ { "id": 1, "name": "southeast_hydro_band", "expression": "hydro_generation(10) + hydro_generation(11)", "slack": { "enabled": true, "penalty": 5000.0, "penalty_basis": "per_hour" } } ]}| constraint_id | stage_id | block_id | bound_lower | bound_upper |
|---|---|---|---|---|
| 1 | 0 | null | 35.0 | 100.0 |
The two endpoints differ, so the row derives band.
The bounds file’s numeric base and the constraint’s inline affine remainder
compose additively on the same endpoint rather than conflicting:
resolved = base + remainder when both are present on that endpoint, or
either alone when only one is. The fold runs per (stage, block), since the
remainder may itself resolve a stage/block-varying named parameter (a
per_stage_block kind, or an expression kind that reads one — see
generic_parameters.json
below).
A load-time inversion check (bound_upper < bound_lower) only fires when both
endpoints are statically resolvable — a constant-only remainder, or none
at all. A remainder carrying a live @param term makes the endpoint
stage-varying, so its inversion is left to LP infeasibility at solve time
rather than a combinatorial pre-solve check across every stage and block.
The activation grid
Seção intitulada “The activation grid”generic_constraint_bounds.parquet is the activation grid — there is no
separate enable flag. A constraint is active at (stage, block) if and only
if a row exists for it there.
- A reference with no rows is rejected. A constraint whose only bound
endpoints come from an inline affine remainder, but which has zero rows in
the bounds parquet, fails referential validation:
InvalidReference, “declares a bound reference but has no activation rows in generic_constraint_bounds.parquet: the reference would apply to nothing.” The parquet still decides where the constraint applies, even when it supplies none of the bound value. A constraint with no inline affine remainder and no rows is not an error; it applies to nothing. - A both-null row is legal only when a reference fills a side. A row with
bound_lower = nullandbound_upper = nullis accepted when the constraint’s ownbound_lower_affine/bound_upper_affinesupplies at least one endpoint — the row’s only job is then to activate that cell; the value comes entirely from the remainder (as in the security-curve example). A both-null row on a constraint with no affine remainder on either side isInvalidValue: “has neither bound_lower nor bound_upper: at least one endpoint is required.” - A degenerate equal band is accepted, an inverted one is not.
bound_upper == bound_lowerderives toequalityand is fine;bound_upper < bound_lower(checked only when both are statically resolvable, per above) isInvalidValue: “an inverted interval is not allowed.” block_id = nullapplies to every block of the stage. When every variable the constraint keeps is stage-level (hydro_storage,hydro_storage_initial,hydro_storage_final,hydro_useful_volume_initial,hydro_useful_volume_final,hydro_evaporation,anticipated_decisionor a stage volume) and no coefficient or bound of the constraint resolves to a per-block value, this collapses to a single stage-level LP row rather than one row per block. Aper_hourslack on that row is priced by the stage’s total hours, and aper_unitslack is charged once (Penalty basis). Aper_stage_block-kind parameter, or anexpression-kind parameter that reads one, anywhere in the constraint’s coefficients or affine remainder suppresses that collapse even when every variable is stage-level, since one collapsed row would otherwise resolve one arbitrary block’s value and silently lose the per-block variation. A variable whose coefficient folds to exactly zero is dropped before this test (Inline relational RHS), so0 * thermal_generation(0)does not hold the row per block. Full row-materialization derivation: LP Formulation §10.- A constraint with a stage-volume term is one row per stage. Each of its
bounds rows has
block_id = null, a row with ablock_idis refused, and the constraint is always the single stage-level row above (Stage volumes).
Expression grammar
Seção intitulada “Expression grammar”An expression string follows the grammar below; whitespace between tokens is
ignored and every name is case-sensitive.
relation ::= sum ( ( "<=" | ">=" | "==" ) sum )?sum ::= product ( ( "+" | "-" ) product )*product ::= unary ( ( "*" | "/" ) unary )*unary ::= ( "+" | "-" ) unary | operandoperand ::= number | "@" name | variable | "(" sum ")"variable ::= var_name "(" integer ( "," integer )? ( "," "bus" "=" integer )? ")" | "line_exchange" "(" bus_pair ")"bus_pair ::= "source_bus" "=" integer "," "target_bus" "=" integer | "target_bus" "=" integer "," "source_bus" "=" integernumber ::= digits with at most one ".", then an optional exponent ("e" or "E", an optional sign, digits)integer ::= a non-negative whole numbername ::= a letter or "_", then letters, digits or "_"A unary sign binds tightest, * and / bind tighter than + and -, and
every binary operator is left-associative. A number carries no sign: -3 is
a unary minus applied to 3, and a sign may stand on any term
(hydro_generation(0) + -thermal_generation(0)).
The productions do not show these rules:
- The expression is linear in LP variables. Every operand is either a
constant (a
number, a scalar parameter, or arithmetic over them) or a linear form (avariable, a named expression, or arithmetic that keeps one). A constant may multiply a linear form on either side (2 * hydro_generation(0)andhydro_generation(0) * 2are the same term), and a linear form may be divided by a constant (hydro_generation(0) / 2). A product of two linear forms (hydro_storage(0) * thermal_generation(0)) and a division by one (10 / hydro_storage(0)) are rejected. - A constant must be finite. A constant built from numbers alone that
divides by zero (
hydro_generation(0) / (1 - 1)) or is not finite is rejected when the case loads. A constant that reads a parameter is evaluated for every stage and block when the study is set up; a value that is not finite there stops setup withGenericConstraintValidationError, naming the constraint, the coefficient or bound, the stage and the block. - An expression holds at most one relational operator, outside
parentheses. With one, constants may stand on either side, inside a group
included, and move to the bound
(Inline relational RHS). Without one, the
expression is the left-hand side alone and must have no constant part:
hydro_generation(0) + 5is rejected, and the bound goes ingeneric_constraint_bounds.parquet. - Nesting is capped at 256 levels, counting each open parenthesis and each unary sign on the path to a term.
var_nameis one of the names in the variable catalog. Onlyhydro_turbinedandhydro_generationtakebus=;hydro_storage,hydro_withdrawalandanticipated_decisiontake no block argument; onlyline_exchangetakes abus_pair.- Write
@directly against its name (@name, never@ name). How an@namereads (a scalar parameter or a named expression) is stated under The@namegrammar. - Give at most one positional block argument: a second one, equal or not, is rejected when the case loads
(Error Codes —
SchemaViolation). - A named-expression definition in
expressionstakes no relational operator and reads at least one LP variable.
For example, a constant group, a coefficient after its variable, a division by a constant and a sign on a later term may all stand in one constraint:
{ "constraints": [ { "id": 1, "name": "c1", "expression": "hydro_generation(0) * 0.5 + -thermal_generation(0) / 2 <= 2 * (thermal_generation(1) + 5)", "slack": { "enabled": false } } ]}Not supported
Seção intitulada “Not supported”Each construct below is rejected when the case loads, reported as
SchemaViolation.
A product of two LP variables. No linear rewrite exists; bound each variable on its own, or scale one by a parameter.
{ "constraints": [ { "id": 1, "name": "c1", "expression": "hydro_generation(0) * thermal_generation(0) <= 30", "slack": { "enabled": false } } ]}A division by an LP variable.
{ "constraints": [ { "id": 1, "name": "c1", "expression": "30 / hydro_generation(0) <= 2", "slack": { "enabled": false } } ]}A constant part without a relational operator. Write
hydro_generation(0) <= 25, or put the bound in the bounds file.
{ "constraints": [ { "id": 1, "name": "c1", "expression": "hydro_generation(0) + 5", "slack": { "enabled": false } } ]}A bare < or >. Write <= or >=.
{ "constraints": [ { "id": 1, "name": "c1", "expression": "hydro_generation(0) < 30", "slack": { "enabled": false } } ]}Two relational operators. Give both endpoints in the bounds file, or write two constraints.
{ "constraints": [ { "id": 1, "name": "c1", "expression": "10 <= hydro_generation(0) <= 30", "slack": { "enabled": false } } ]}A name in another case. Write hydro_generation(0).
{ "constraints": [ { "id": 1, "name": "c1", "expression": "Hydro_generation(0)", "slack": { "enabled": false } } ]}A second positional block argument on one variable, equal or not.
{ "constraints": [ { "id": 1, "name": "c1", "expression": "thermal_generation(0, 0, 1) <= 10", "slack": { "enabled": false } } ]}Variable catalog
Seção intitulada “Variable catalog”An expression can name any of the 29 variables below. The reference
grammar is var_name(entity_id[, block_id][, bus=bus_id]) — an optional
positional block argument, then an optional named bus= selector, in that
order (f(id), f(id, block), f(id, bus=b), f(id, block, bus=b) all
parse).
| Variable | Block arg | bus= | Notes |
|---|---|---|---|
hydro_storage(id) | No | No | Stage-level stock |
hydro_withdrawal(id) | No | No | Stage-level |
hydro_outflow_volume(id) | No | No | Stage volume in hm³ of the plant’s turbined plus spilled flow (stage volumes) |
hydro_diversion_volume(id) | No | No | Stage volume in hm³ of the plant’s diverted flow (stage volumes) |
pumping_volume(id) | No | No | Stage volume in hm³ of the station’s pumped flow (stage volumes) |
hydro_evaporation(id[, block]) | Yes | No | One stage-level quantity on a parallel stage, one per block on a chronological stage; some references are rejected on their block argument — see block references |
hydro_inflow(id[, block]) | Yes | No | The plant’s inflow in the block (hydro_inflow); a bound with no block_id expands to one row per block; a hydro_inflow term never collapses to a stage-level row, and a term with no block argument reads the block of its row |
hydro_storage_initial(id[, block]) | Yes (boundary) | No | With a block k, the storage at the start of block k; with no block, the stage’s initial storage |
hydro_storage_final(id[, block]) | Yes (boundary) | No | With a block k, the storage at the end of block k; with no block, the stage’s final storage (the hydro_storage value) |
hydro_useful_volume_initial(id[, block]) | Yes (boundary) | No | Same column and block semantics as hydro_storage_initial; stands for storage − reservoir.min_storage_hm3 (see below) |
hydro_useful_volume_final(id[, block]) | Yes (boundary) | No | Same column and block semantics as hydro_storage_final; stands for storage − reservoir.min_storage_hm3 (see below) |
hydro_turbined(id[, block][, bus=]) | Yes | Yes | bus= selects one (hydro, bus) cell; omitted sums over the plant’s cells |
hydro_spillage(id[, block]) | Yes | No | |
hydro_diversion(id[, block]) | Yes | No | |
hydro_outflow(id[, block]) | Yes | No | Derived alias for turbined + spillage, not an independent LP column |
hydro_generation(id[, block][, bus=]) | Yes | Yes | Same bus= semantics as hydro_turbined |
thermal_generation(id[, block]) | Yes | No | |
line_direct(id[, block]) | Yes | No | Forward flow only |
line_reverse(id[, block]) | Yes | No | Reverse flow only |
line_exchange(id[, block]) | Yes | No | Net flow (direct − reverse); also addressable by bus pair, below |
bus_deficit(id[, block]) | Yes | No | |
bus_excess(id[, block]) | Yes | No | |
pumping_flow(id[, block]) | Yes | No | |
pumping_power(id[, block]) | Yes | No | |
contract_import(id[, block]) | Yes | No | |
contract_export(id[, block]) | Yes | No | |
non_controllable_generation(id[, block]) | Yes | No | |
non_controllable_curtailment(id[, block]) | Yes | No | |
anticipated_decision(id) | No (rejected if given) | No | Stage-level scalar commitment column of a thermal that declares anticipated_config; no block index at all — use anticipated_decision(N) |
Only hydro_turbined and hydro_generation accept bus=; any other
variable rejects it as “does not accept a bus selector.” A (hydro, bus) cell
is the part of a plant on one bus: a plant has one cell per distinct bus among
its unit groups, and bus=
must name one of those buses.
A hydro_withdrawal, non_controllable_generation or
non_controllable_curtailment term is accepted when the case loads but adds no
coefficient to the LP row. A contract_import or contract_export term adds a
coefficient only when the named contract exists and has that direction, a
hydro_evaporation term only on a stage where the plant has an evaporation
model and is not PreFilling, and a hydro_generation term on a plant with an
FPHA model only on a stage where the plant is neither PreFilling nor Filling; in
these cases the term’s quantity is zero. The resolved echo
still lists every such term.
A constraint whose every term adds no coefficient leaves a row with no LP variable from its terms: without a slack the LP is infeasible when the bound excludes zero, and the row has no effect otherwise; with a slack, the slack absorbs the excluded amount at the constraint’s slack penalty. When only some terms add no coefficient, the bound applies to the remaining terms alone.
Useful-volume bound fold. A term c * hydro_useful_volume_initial(h) or
c * hydro_useful_volume_final(h) is built on plant h’s storage column, and
c × min_storage_hm3 of plant h — the physical minimum from
reservoir.min_storage_hm3, never a hydro_bounds per-stage override — is
added to every resolved bound endpoint of the constraint, once per such term
(c being the term’s fully resolved coefficient, so a @name coefficient
contributes its resolved value). A negative c lowers the endpoints by the
same rule. The constraint therefore reads as a quantity above dead storage while
the LP column keeps the absolute storage value; no extra LP variable is
created, and the folded endpoints are visible in
the resolved echo.
hydro_evaporation block references
Seção intitulada “hydro_evaporation block references”With h a hydro id and K the number of blocks the stage declares, the
generic-constraint check rejects a hydro_evaporation reference that the
stage’s block_mode cannot
expose:
- On a parallel stage with two or more blocks,
hydro_evaporation(h)andhydro_evaporation(h, 0)address the one stage-level evaporation, and a block from 1 toK - 1is rejected. - On a chronological stage with more than one block, a block is required:
hydro_evaporation(h)is rejected. - On a stage with one block, on either stage mode,
hydro_evaporation(h)andhydro_evaporation(h, 0)both address the single block. - A block at or beyond
Kis rejected on every stage, for an evaporation or a storage reference. - The same check rejects a
hydro_storage_initial,hydro_storage_final,hydro_useful_volume_initialorhydro_useful_volume_finalreference that names an interior block boundary, one between two blocks, on a parallel stage.
hydro_evaporation(h) parallel: the stage-level evaporation; chronological with K > 1: rejectedhydro_evaporation(h, 1) parallel: rejected; chronological with K > 1: block 1The check runs only for a (constraint, stage) pair that has a row in
generic_constraint_bounds.parquet. Each rejection is a BusinessRuleViolation;
the messages are quoted in
Error Codes — Per-block generic-constraint references.
For any reference not covered above, the block argument is not checked when the
case loads: keep it below K on every stage where the constraint is active. A
block at or beyond K is accepted, and the term can then land on a
column outside that entity’s own blocks. novomodelo validate and novomodelo run stop with an
index-out-of-bounds panic when the block addresses past the last column of the
stage LP, and for a block at or beyond K on a hydro_inflow term of a plant
that receives water through an upstream travel_time_hours arc, directly or through an upstream PreFilling plant that has such an arc.
hydro_inflow
Seção intitulada “hydro_inflow”A hydro_inflow term reads the plant’s inflow in the block, a rate in m³/s, made
of:
- the plant’s local inflow;
- under the
truncationandtruncation_with_penaltymethods ofmodeling.inflow_non_negativity, the inflow non-negativity slack that corrects a negative local inflow; - the flows diverted into it;
- the upstream releases credited to the block by travel time;
- the share of the in-transit volume maturing at the stage that arrives in the block, as a rate;
- the water of upstream PreFilling plants passing through: the local inflow of each, its truncation slack under the same two methods, the flows diverted into it, the releases of its upstream plants, and its maturing in-transit volume, as a rate.
It excludes pumping, the inflow non-negativity slack under the penalty
method, the plant’s own outflows, evaporation and withdrawal. On a parallel stage only the duration-weighted stage
total matches the water balance; the split across blocks is a convention. For a plant that is PreFilling at the stage, the plant’s inflow enters the
water-balance row of its nearest downstream plant that is not PreFilling, so the
term equals no row’s own inflow.
The local inflows are constants of each solve, computed before it from the PAR(p)
model: a hydro_inflow term with coefficient c subtracts c times each local
inflow it reads from every finite bound of its row, and the other terms of the
list enter the row as columns
(PAR(p) Folding §2).
Definition: LP Formulation — Hydro Inflow.
line_exchange(source_bus=, target_bus=)
Seção intitulada “line_exchange(source_bus=, target_bus=)”Besides the direct-id form (line_exchange(id[, block])), line_exchange
alone also accepts an endpoint-bus-pair form in place of the positional
line id:
line_exchange(source_bus=3, target_bus=7)source_bus= and target_bus= may appear in either order, but both are
required, and this form takes no block argument — it always resolves to
block_id: None. Novomodelo resolves the (source_bus, target_bus) pair against a
line-topology index built from every declared line’s (source_bus_id, target_bus_id) pair and its reverse:
- If the pair matches a line’s declared direction, the term’s orientation
is forward (scale
+1.0). - If the pair is reversed relative to the line’s declared direction, the
orientation folds
-1.0into the term’s scale — so an author never needs to know which way a given line happened to be declared.
The pair form reads exactly the line that the direct-id form reads, with the
orientation sign applied. When two lines connect the same pair of buses, the
pair identifies no single line, and the case is rejected whenever it has a
constraints/generic_constraints.json file, even if no expression uses the
pair form (Authoring errors).
Stage volumes
Seção intitulada “Stage volumes”hydro_outflow_volume(h), hydro_diversion_volume(h) and pumping_volume(y)
each read a volume in hm³ over the whole stage: a flow in m³/s in each block,
times the block’s flow-to-volume conversion (0.0036 × the block’s hours), summed
over the stage’s blocks. The flow is the plant’s turbined plus spilled flow
(the hydro_outflow sum, over every (hydro, bus) cell of the plant), the
plant’s diverted flow, or the station’s pumped flow. A coefficient on one of
these terms multiplies hm³.
A constraint with a stage-volume term is one stage-level LP row at each stage where it is active, and none of its parts varies by block:
- Every other term is a stage volume,
hydro_storage, or ahydro_storage_initial,hydro_storage_final,hydro_useful_volume_initialorhydro_useful_volume_finalterm without a block argument. Any other variable beside a stage volume is refused, whether the expression writes it or a named expression brings it in. - No coefficient or bound reads a
per_stage_blockparameter, directly or throughexpressionparameters. - Every row of the constraint in
generic_constraint_bounds.parquethas a nullblock_id.
Each refusal is a
BusinessRuleViolation.
The row’s quantity is an amount in hm³, so Penalty basis gives
per_unit for its slack.
For example, a cap on the volume hydro 0 releases and diverts over each stage:
{ "constraints": [ { "id": 1, "name": "release_cap", "expression": "hydro_outflow_volume(0) + hydro_diversion_volume(0) <= 5000", "slack": { "enabled": true, "penalty": 10.0, "penalty_basis": "per_unit" } } ]}A flow beside a stage volume is refused:
{ "constraints": [ { "id": 1, "name": "release_vs_flow", "expression": "hydro_outflow_volume(0) - hydro_turbined(1) <= 0", "slack": { "enabled": false } } ]}The @name grammar
Seção intitulada “The @name grammar”Two authoring roles share one namespace: scalar parameters (declared in
constraints/generic_parameters.json) and named expressions (declared in the
constraints file’s own optional top-level expressions array and shared by
every constraint). Declaring the same name in both is rejected: “name … is
declared as both a scalar parameter and a
named expression; the “@name” namespace is shared.”
Resolution. An @name reads as whatever its name is declared as. A scalar
parameter is a constant, resolved per stage and block from
generic_parameters.json; a named expression is a linear form, its body
substituted where it is referenced. Either may stand anywhere an operand may,
under the linearity rule of the expression grammar:
@p * hydro_storage(0), hydro_storage(0) * @p, @p * @q * hydro_storage(0),
@p * (hydro_storage(0) + hydro_storage(1)), @p * @name and @name / @p are
all linear, while @name * hydro_storage(0) and @name * @other multiply two
linear forms and are rejected, with a message that names the named expression.
An @name declared in neither file is rejected: unknown name "@x": no scalar parameter or named expression with this name was declared.
A parameter may scale a named expression:
{ "expressions": [ { "name": "stored", "expression": "hydro_useful_volume_final(0)" } ], "constraints": [ { "id": 1, "name": "c0", "expression": "@rho_int * @stored >= 0.3 * @emax", "slack": { "enabled": false } } ]}Bodies. A named-expression body takes no relational operator and reads at
least one LP variable; a formula over parameters alone belongs in
generic_parameters.json as an expression parameter,
and the rejection says so. A body may carry a constant part
(hydro_generation(0) + 5): the constant belongs to the side of the relation
the reference stands on and moves to the bound with the other constants
(Inline relational RHS), and a constraint without a
relational operator that references such a body is rejected. A body is checked
where it is declared, so a fault in its own source (an unknown variable, a
division by zero) is reported at expressions[i].expression even when no
constraint references it.
Composition. A named expression may reference another named expression; composition resolves transitively, with each reference’s scale distributed into every substituted term:
{ "expressions": [ { "name": "base", "expression": "hydro_generation(0)" }, { "name": "inner", "expression": "3.0 * @base" }, { "name": "outer", "expression": "@inner + hydro_generation(1)" } ], "constraints": [ { "id": 1, "name": "c0", "expression": "2.0 * @outer", "slack": { "enabled": false } } ]}2.0 * @outer inlines to 6.0 * hydro_generation(0) + 2.0 * hydro_generation(1).
Cycle detection. A reference cycle among named expressions, including an
expression that references itself, is rejected before any constraint is built,
even when no constraint uses those expressions; the message names the cycle
(a -> b -> a).
Expansion budget. Expanding the named expressions a constraint references
is refused once the coefficients and constant it builds would hold more than
100,000 arithmetic operations in total, a bound far above any authored
constraint. It catches an exponential reference pattern, such as a doubling
chain @e_k = @e_{k-1} + @e_{k-1} over a parameter-scaled term, before it
grows. Literal coefficients fold as they combine, so the same chain over a
literal coefficient stays one term. Declaring such a chain is not itself an
error: the budget applies only where a constraint expands it.
Grouping. A parenthesized group scaled by a constant — a literal, a
parameter or a product of them (2.0 * (@fnese - hydro_generation(2)),
@p * (hydro_generation(0) + 5)) — distributes that constant into every inner
term and into the group’s own constant, to any depth up to the
nesting cap. Dividing a group by a constant divides
each of them.
Inline relational RHS
Seção intitulada “Inline relational RHS”An expression carries at most one relational operator (Expression grammar); for a range, give both endpoints in the bounds file or write two constraints.
- No operator:
expressionis the flat one-sided LHS; the interval comes entirely from the parquet base / affine-remainder mechanism described above. The expression has no constant part, its own or a named body’s. - One operator: every variable term on the right moves to the left with
its sign flipped. The constant parts of the two sides fold into one affine
remainder, the right side’s constant minus the left side’s, which may read
scalar parameters. The operator assigns it:
<=to the upper endpoint,>=to the lower,==to both (an identical remainder on each side).
In both cases the terms on one variable, wherever they stand, combine into one
coefficient, and a variable whose combined coefficient folds to exactly 0.0
(0 * hydro_generation(0), or hydro_generation(0) - hydro_generation(0)) is
dropped; it adds no LP coefficient, is not listed in the
resolved echo, and does not hold the row per block
(the activation grid). A coefficient that reads a
parameter keeps its term whatever value the parameter resolves to.
When the LP row is built, the terms that land on one LP column — two
references that name it differently, such as hydro_storage(h) and
hydro_storage_final(h), thermal_generation(j) and thermal_generation(j, k)
on block k’s row, or hydro_turbined(h) and hydro_generation(h) of a
constant-productivity plant — are summed into one coefficient for that column,
and a column whose coefficients sum to exactly 0.0 gets no entry. The
resolved echo still lists each term.
A named expression on the right-hand side inlines into the merged LHS as variable terms; only its constant part, if it has one, joins the remainder:
{ "expressions": [ { "name": "fnese", "expression": "hydro_generation(10) + hydro_generation(11)" } ], "constraints": [ { "id": 1, "name": "c0", "expression": "hydro_generation(0) >= @fnese", "slack": { "enabled": false } } ]}folds all three hydro_generation terms onto the merged LHS and assigns an
explicit zero-constant lower bound — an all-variable RHS still supplies an
affine bound, never “no bound.”
generic_parameters.json: the parameter kinds
Seção intitulada “generic_parameters.json: the parameter kinds”The file’s top-level JSON key is "scalar_parameters" (an array). The field table lists
the field each kind fills. Each entry carries its own kind’s payload field and
no other: a field that belongs to another kind (for example values on a
constant) stops the load.
kind | Value semantics |
|---|---|
constant | One value for every stage |
per_stage | Explicit value per study stage; stage_ids must be a contiguous range from 0, one per study stage |
seasonal | One value per season; stages inherit their season’s value; season_ids must be unique, and every season a study stage falls in needs a value |
computed | Derived from hydro geometry/operational data at LP-build time — one of thirteen hydro-derived tags (e.g. equivalent_productivity); see Constraint Files |
per_stage_block | Explicit value per (stage_id, block_id) pair; each pair unique, and every block of every study stage covered |
expression | A formula over other parameters of the file, evaluated per stage, and per block when a parameter it reads varies by block |
For editor validation with the vendored
generic_parameters.schema.json, see
JSON Schemas.
per_stage_block is the mechanism that makes a generic-constraint bound (or
coefficient) genuinely block-varying — and, per
the activation grid above, referencing one in a
coefficient or an affine remainder suppresses the stage-level row collapse.
expression parameters
Seção intitulada “expression parameters”An expression parameter’s expression reads other parameters of the same
file by @name, declared before or after it, with numbers, +, -, *, /,
unary signs and parentheses. A constraint reads it like any other parameter:
{ "scalar_parameters": [ { "id": 1, "name": "rho_int", "kind": "computed", "computed_spec": { "tag": "integrated_accumulated_productivity", "hydro_id": 0 } }, { "id": 2, "name": "emax", "kind": "computed", "computed_spec": { "tag": "max_stored_energy", "hydro_id": 0 } }, { "id": 3, "name": "security_floor", "kind": "expression", "expression": "0.3 * @emax" } ]}These are rejected when the case loads: an LP variable, a named expression of
generic_constraints.json, an unknown @name or a relational operator in the
formula; a constant part that divides by zero or is not finite; a reference
cycle among expression parameters; and an expression entry without an
expression field. The formula is evaluated for every stage and block when the
study is set up, and a value that is not finite stops setup, naming the
parameter, the stage and the block. A parameter that reads a per_stage_block
parameter, directly or through another expression parameter, varies by block
like it. The stored-energy pairing check (rule 51, under
Authoring errors) follows an expression parameter to the
computed tags it reads.
Two-sided slack
Seção intitulada “Two-sided slack”Slack config (slack.enabled, slack.penalty, slack.penalty_basis) is
declared once per constraint and applies uniformly to every row the activation
grid produces for it. slack is required on every constraint. With
enabled: true, penalty must be greater than zero and penalty_basis must
be given (Penalty basis); with enabled: false, neither may
be set (Authoring errors). How many LP columns the slack
adds is a property of the row’s own resolved endpoint pair, never a
constraint-level label:
| Row shape | Slack columns |
|---|---|
| Disabled | Zero |
One-sided (floor/cap) | One (s⁺) |
Two-sided (band/equality) | Two (s⁺ then s⁻) |
A two-sided bound needs slack in both directions to relax either endpoint independently — one column cannot represent “went below the floor” and “went above the cap” at once.
Cost charges both. Both columns are priced at the same cost per unit of
violation, set by the penalty basis: violating either
direction costs the same, and the LP can never let a +5 on one side and a
-5 on the other net to a free violation.
The reported value nets them. In the simulation violations output, a
one-sided row reports the raw (non-negative) slack primal. A two-sided row
instead reports the signed net s⁺ − s⁻ (which may be negative) —
deliberately different from the cost, which always sums s⁺ + s⁻. In
practice both slacks are rarely simultaneously nonzero at an LP vertex, so the
net is the more legible number for a results reader while the sum remains the
correct charge.
Penalty basis
Seção intitulada “Penalty basis”An enabled slack must declare penalty_basis. It states what one unit of
violation of the row is, and so how penalty turns into an objective cost:
penalty_basis | Cost of one unit of violation | Use for a row in |
|---|---|---|
per_hour | penalty × hours, the hours the row spans | MW, m³/s |
per_unit | penalty, whatever the stage length | MWh, hm³ |
The hours a row spans are the stage’s total hours for a stage-level row and
the block’s hours for a per-block row. A per_hour floor of 100 MW missed by
10 MW on a 744-hour stage costs penalty × 10 × 744. A per_unit floor of
300 hm³ missed by 10 hm³ costs penalty × 10 on a week and on a month alike.
per_unit is charged once per violated row. A row that
the activation grid materializes per block, for
example a storage row whose bound comes from a per_stage_block parameter, is
one constraint per block, and each violated block row is charged.
The basis is declared, never inferred from the expression: a stored volume can also be written with flow terms, as hours-weighted turbined and spilled flow, and the penalty’s meaning must not change when a term is added or removed. Pick the basis from the unit of the row, not from the variables in it.
The slack_cost of
simulation/violations/generic/
prices each row’s slack at the same cost per unit the LP charges it.
The resolved echo
Seção intitulada “The resolved echo”generic_constraints/resolved_echo.parquet is written at the output root
(<out>/generic_constraints/) whenever the study declares any generic constraints; for a study with
none, the generic_constraints/ directory does not exist at all.
One row is emitted per resolved LHS term per active (constraint, stage, block) cell, in canonical (constraint, stage, block, term) order — declaration-order
invariant, so the same case always echoes the same rows in the same order. A
term-less (constant-only) constraint contributes a single placeholder row
whose per-term columns are all null.
| Name | Type | Nullable | Units | Description |
|---|---|---|---|---|
stage_id | Int32 | No | — | Study stage id |
block_id | Int32 | Yes | — | Null on a collapsed stage-level row |
constraint_id | Int32 | No | — | Generic constraint id |
constraint_name | Utf8 | No | — | Generic constraint name |
term_index | Int32 | Yes | — | Position in the resolved LHS; null on the term-less placeholder row |
variable_kind | Utf8 | Yes | — | Variable name (e.g. "thermal_generation"); null on the placeholder |
variable | Utf8 | Yes | — | Rendered variable label (e.g. "thermal_generation(id=3, block=all)"); null on the placeholder |
coefficient | Float64 | Yes | — | Fully resolved numeric coefficient (resolve(coefficient, stage, block) * scale); null on the placeholder |
bound_lower | Float64 | Yes | — | Lower interval endpoint after folding — including each useful-volume term’s coef × min_storage_hm3 shift; null when unbounded below |
bound_upper | Float64 | Yes | — | Upper interval endpoint after folding — including each useful-volume term’s coef × min_storage_hm3 shift; null when unbounded above |
derived_shape | Utf8 | No | — | The same floor/cap/band/equality label as above — never an authored sense |
slack_enabled | Boolean | No | — | Whether the constraint carries a slack term |
slack_penalty | Float64 | Yes | — | Slack penalty, charged as slack_penalty_basis states; null when slack is disabled |
slack_penalty_basis | Utf8 | Yes | — | per_hour or per_unit (Penalty basis); null when slack is disabled |
The echo is the place to observe a folded bound: the input
constraints/generic_constraint_bounds.parquet shows the pre-fold value. For
example, a floor hydro_useful_volume_final(0) >= 20 on a plant whose
reservoir.min_storage_hm3 is 100 echoes bound_lower = 120.0
(20 + 1 × 100) with variable = "hydro_useful_volume_final(id=0, block=all)".
This is the fully desugared form: every named-expression reference is
already inlined into flat terms, every inline relational RHS has already
normalized into the bound_lower/bound_upper pair, and every @name
coefficient or bound has already resolved to its numeric value at that
(stage, block). It is the term list the LP row is built from: each
coefficient is the term’s own, before the LP maps the term onto its columns
(a hydro_generation term of a constant-productivity plant lands on its
turbined columns times the productivity) and sums the terms that land on one
column (Inline relational RHS). The echo also lists
the terms that add no coefficient (see the note under the
variable catalog) and a term with an out-of-range block
(block references). It is the tool for
auditing an authored expression against the LP that was actually built.
Worked example: a security curve
Seção intitulada “Worked example: a security curve”A security curve keeps plant h’s end-of-stage stored energy above a fraction
p of its maximum, stated in energy terms with the useful-range mean
productivity of
Hydro Production Function Models §4.3:
@rho_int * hydro_useful_volume_final(h) >= p * @emax.
constraints/generic_parameters.json declares the two computed parameters for
hydro 0:
{ "scalar_parameters": [ { "id": 1, "name": "rho_int", "kind": "computed", "computed_spec": { "tag": "integrated_accumulated_productivity", "hydro_id": 0 } }, { "id": 2, "name": "emax", "kind": "computed", "computed_spec": { "tag": "max_stored_energy", "hydro_id": 0 } } ]}constraints/generic_constraints.json states the curve for p = 0.3:
{ "constraints": [ { "id": 1, "name": "security_curve_h0", "expression": "@rho_int * hydro_useful_volume_final(0) >= 0.3 * @emax", "slack": { "enabled": true, "penalty": 5000.0, "penalty_basis": "per_unit" } } ]}The inline RHS carries the whole bound, but the constraint still needs
activation rows in constraints/generic_constraint_bounds.parquet — one
row per active stage, with both bounds null; without them the constraint is
never built (the activation grid):
| constraint_id | stage_id | block_id | bound_lower | bound_upper |
|---|---|---|---|---|
| 1 | 0 | null | null | null |
| 1 | 1 | null | null | null |
| … | … | … | … | … |
Why it cancels. integrated_accumulated_productivity and
max_stored_energy are evaluated by the same useful-range mean evaluator and
in the same raw unit, so @emax is exactly @rho_int times the useful
volume; hydro_useful_volume_final reads storage above the physical minimum,
the same range @emax spans. Pairing max_stored_energy with another
productivity tag of the same unit, such as the reference-point
accumulated_productivity or the plant-only
integrated_equivalent_productivity, does not cancel and raises a
SemanticAmbiguity warning.
The row is an amount, a stored energy, so its slack is priced per_unit: the
penalty is a price per unit of missed stored energy on every stage, whatever
its length.
What the echo shows. On a plant with reservoir.min_storage_hm3 = 100,
reservoir.max_storage_hm3 = 1000, specific_productivity_mw_per_m3s_per_m = 0.0088
and a three-row volume-height-area geometry table (100, 500 and 1000 hm³),
the stage-0 resolved echo row reads coefficient = 2.8136,
bound_lower = 1041.02 and
variable = "hydro_useful_volume_final(id=0, block=all)": the RHS
0.3 × 2532.2 (0.3 × @emax, where @emax = 2.8136 × (1000 − 100)) plus the
useful-volume fold 2.8136 × 100 (@rho_int × min_storage_hm3).
Writing the same curve by hand on hydro_storage_final(h), with the dead-volume
energy @rho_int × min_storage_hm3 pre-folded into the bound (on the same plant,
bound_lower = 1041.02 on @rho_int * hydro_storage_final(0)) is equivalent.
The same curve in MWh. max_stored_energy and the productivity tags are in
the raw unit MW/(m³/s)·hm³. Their MWh forms, max_stored_energy_mwh and
integrated_accumulated_productivity_mwh_per_hm3, are the raw values times
10⁶/3600, so the curve states its amounts in MWh with no stage duration on
either side, and a per_unit penalty is a price per MWh:
{ "scalar_parameters": [ { "id": 1, "name": "rho_int_mwh", "kind": "computed", "computed_spec": { "tag": "integrated_accumulated_productivity_mwh_per_hm3", "hydro_id": 0 } }, { "id": 2, "name": "emax_mwh", "kind": "computed", "computed_spec": { "tag": "max_stored_energy_mwh", "hydro_id": 0 } } ]}with the expression @rho_int_mwh * hydro_useful_volume_final(0) >= 0.3 * @emax_mwh.
Use one family throughout a constraint: a constraint that mixes raw-unit and
MWh tags, among the stored-energy and productivity tags, raises the same warning.
Authoring errors
Seção intitulada “Authoring errors”The failure modes below are the ones an author is most likely to hit while
writing this grammar; see Error Codes for the
exhaustive catalog and resolutions — it is not repeated here. The Kind column
names each failure’s kind; on an error line, novomodelo validate prints it in
brackets, as in error: [SchemaViolation] ….
| Situation | Kind |
|---|---|
An unknown variable name, including a catalog name written in another case (Hydro_generation(0)) | SchemaViolation |
An @name declared as neither a scalar parameter nor a named expression, a product of two LP-variable terms or a division by one, a constant built from numbers that divides by zero or is not finite, nesting deeper than 256 levels, or any construct under Not supported | SchemaViolation |
| A named-expression body with a relational operator, or one that reads no LP variable | SchemaViolation |
bus= on a variable other than hydro_turbined and hydro_generation, or a block argument on hydro_storage, hydro_withdrawal, a stage volume or anticipated_decision, or a second positional block argument (hydro_turbined(5, 0, 1)) | SchemaViolation |
A duplicate constraint id, or a duplicate parameter id or name | SchemaViolation |
| A name declared both as a scalar parameter and as a named expression | SchemaViolation |
| A reference cycle among named expressions, a self-reference included | SchemaViolation |
A key the constraint entry does not declare (for example sense) | ParseError |
A constraint entry with no slack object | ParseError |
slack.enabled: true with no penalty, a penalty of zero or less, or no penalty_basis; or slack.enabled: false with penalty or penalty_basis set | SchemaViolation |
A penalty_basis other than per_hour or per_unit | ParseError |
A parameter entry with a payload field of another kind (values on a constant), or without its own | SchemaViolation |
An expression parameter whose formula reads an LP variable, a named expression or an unknown name, holds a relational operator, or divides by zero; or a reference cycle among expression parameters | SchemaViolation |
A coefficient, bound or expression parameter that resolves to a value that is not finite at some stage and block | GenericConstraintValidationError |
A term naming an entity id the case does not declare (hydro_generation(7) with no hydro 7) | InvalidReference |
bus= naming a bus on which the plant has no unit group | InvalidReference |
anticipated_decision(N) where thermal N has no anticipated_config | BusinessRuleViolation |
line_exchange(source_bus=, target_bus=) naming two buses that no line connects | SchemaViolation |
Two lines connecting the same pair of buses, in either direction, in a case that has constraints/generic_constraints.json, whether or not an expression uses the bus-pair form | SchemaViolation |
| Constraint declares a bound reference but has no activation rows | InvalidReference |
| A bounds row with neither endpoint, and no affine remainder to fill one | InvalidValue |
Inverted interval (bound_upper < bound_lower, both statically resolvable) | InvalidValue |
A bounds row whose block_id is not a block of its stage | BusinessRuleViolation |
Beside a stage-volume term, a term that is not a stage volume, hydro_storage, or a hydro_storage_* or hydro_useful_volume_* term without a block argument | BusinessRuleViolation |
A per_stage_block parameter that a coefficient or bound of a constraint with a stage-volume term reads, directly or through expression parameters | BusinessRuleViolation |
A bounds row with a block_id for a constraint with a stage-volume term | BusinessRuleViolation |
| An evaporation or storage reference naming a block that its stage does not have (block references) | BusinessRuleViolation |
The same bound column (bound_lower or bound_upper) set twice for one (constraint_id, stage_id, block_id) — a bound_lower row and a bound_upper row for the same triple are distinct keys and legal | DuplicateId |
A contract_import or contract_export term naming no declared contract | UnusedEntity — warning, the case still validates |
A max_stored_energy(h) or max_stored_energy_mwh(h) tag beside a productivity tag of the same unit for the same hydro other than its matching one (integrated_accumulated_productivity, or integrated_accumulated_productivity_mwh_per_hm3 for the MWh tag), or raw-unit and MWh tags, among the stored-energy and productivity tags, in one constraint, read directly or through expression parameters | SemanticAmbiguity — warning, the case still validates |
See also
Seção intitulada “See also”- LP Formulation §10 — the math formulation these constraints desugar into.
- Constraint Files — field tables for the three input files.
- Error Codes — the exhaustive
LoadError/ErrorKindcatalog. - JSON Schemas — vendored
generic_constraints.schema.jsonandgeneric_parameters.schema.jsonfor editor integration.