Skip to content

Penalty Files

This page documents penalties.json, which holds the global penalty cost defaults, and the four constraints/penalty_overrides_*.parquet files, which override individual defaults for one entity at one stage. The overrides share the constraints/ directory with the bounds files on Constraint Files. The File summary maps every case file to its page, and Conventions states the rules shared by all of them.

All penalty override files use sparse storage. Only rows for (entity_id, stage_id) pairs where the penalty differs from the entity-level or global default are required. Every override value must be finite. turbined_cost (hydro) and curtailment_cost (non-controllable source) must be >= 0.0, as their penalties.json defaults; every other override value must be strictly positive (> 0.0).


Methodology: Penalty System

Global penalty cost defaults used when no entity-level override is present. All four sections are required. Every required scalar cost must be strictly positive (> 0.0), with two exceptions validated >= 0.0: the hydro turbined_cost regularization cost (a 0.0 turbined cost — no turbine-flow penalty — is valid) and non_controllable_source.curtailment_cost (a 0.0 cost makes curtailment free). The optional costs, hydro.inflow_nonnegativity_cost and the four directional evaporation and withdrawal costs, are read without a range check. The deficit segments must be non-empty, with costs strictly increasing and the last segment’s depth_mw set to null (unbounded).

NameTypeRequiredDefaultUnitsDescription
busobjectYes——Bus penalty defaults.
bus.deficit_segmentsarrayYes——Piecewise-linear deficit cost tiers
bus.deficit_segments[].depth_mwnumber | nullNo—MWSegment depth (MW); null for the final unbounded segment
bus.deficit_segments[].costnumberYes—USD/MWhCost per MWh of deficit in this tier (USD/MWh)
bus.excess_costnumberYes—USD/MWhCost per MWh of excess injection (USD/MWh)
lineobjectYes——Line penalty defaults.
line.exchange_costnumberYes—USD/MWhCost per MWh of inter-bus exchange flow (USD/MWh)
hydroobjectYes——Hydro penalty defaults.
hydro.spillage_costnumberYes—USD/(m³/s·h)Spillage penalty
hydro.turbined_costnumberYes—USD/(m³/s·h)Turbined flow regularization cost (applied to every hydro)
hydro.diversion_costnumberYes—USD/(m³/s·h)Diversion flow penalty
hydro.storage_violation_below_costnumberYes—USD/hm³Storage below-minimum violation penalty
hydro.filling_target_violation_costnumberYes—USD/hm³Filling target violation penalty
hydro.turbined_violation_below_costnumberYes—USD/(m³/s·h)Turbined flow below-minimum violation penalty
hydro.outflow_violation_below_costnumberYes—USD/(m³/s·h)Total outflow below-minimum violation penalty
hydro.outflow_violation_above_costnumberYes—USD/(m³/s·h)Total outflow above-maximum violation penalty
hydro.generation_violation_below_costnumberYes—USD/MWhGeneration below-minimum violation penalty
hydro.fpha_violation_costnumberYes—USD/MWhFPHA plane violation penalty: the price of generation above an FPHA plane, per MW and hour
hydro.evaporation_violation_costnumberYes—USD/(m³/s·h)Symmetric evaporation violation penalty
hydro.evaporation_violation_pos_costnumber | nullNo—USD/(m³/s·h)Optional over-evaporation override; supersedes evaporation_violation_cost for the positive direction. Omitted = symmetric value
hydro.evaporation_violation_neg_costnumber | nullNo—USD/(m³/s·h)Optional under-evaporation override; supersedes evaporation_violation_cost for the negative direction. Omitted = symmetric value
hydro.water_withdrawal_violation_costnumberYes—USD/(m³/s·h)Symmetric water withdrawal violation penalty
hydro.water_withdrawal_violation_pos_costnumber | nullNo—USD/(m³/s·h)Optional over-withdrawal override; supersedes water_withdrawal_violation_cost for the positive direction. Omitted = symmetric value
hydro.water_withdrawal_violation_neg_costnumber | nullNo—USD/(m³/s·h)Optional under-withdrawal override; supersedes water_withdrawal_violation_cost for the negative direction. Omitted = symmetric value
hydro.inflow_nonnegativity_costnumber | nullNo—USD/(m³/s·h)Optional cost of the inflow correction under the penalty and truncation_with_penalty methods, unused under truncation and none. Omitted = default 1000.0
non_controllable_sourceobjectYes——Non-controllable source penalty defaults.
non_controllable_source.curtailment_costnumberYes—USD/MWhCurtailment penalty (USD/MWh); >= 0.0

Example:

{
"$schema": "https://docs.modelossetoreletrico.org.br/schemas/penalties.schema.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,
"fpha_violation_cost": 85000.0,
"evaporation_violation_cost": 5000.0,
"water_withdrawal_violation_cost": 1000.0
},
"non_controllable_source": { "curtailment_cost": 0.005 }
}

Methodology: Penalty System

NameTypeRequiredDefaultUnitsDescription
bus_idInt32Yes——Bus ID
stage_idInt32Yes——Stage ID
excess_costFloat64No—USD/MWhExcess injection cost override (USD/MWh)

Note: Bus deficit segments are not stage-varying. Only excess_cost can be overridden per stage for buses.


Methodology: Penalty System

NameTypeRequiredDefaultUnitsDescription
line_idInt32Yes——Transmission line ID
stage_idInt32Yes——Stage ID
exchange_costFloat64No—USD/MWhExchange flow cost override (USD/MWh)

Methodology: Penalty System

NameTypeRequiredDefaultUnitsDescription
hydro_idInt32Yes——Hydro plant ID
stage_idInt32Yes——Stage ID
spillage_costFloat64No—USD/(m³/s·h)Spillage penalty override (USD/(m³/s·h))
turbined_costFloat64No—USD/(m³/s·h)Turbined cost override (USD/(m³/s·h)); >= 0.0
diversion_costFloat64No—USD/(m³/s·h)Diversion penalty override (USD/(m³/s·h))
storage_violation_below_costFloat64No—USD/hm³Storage below-minimum violation override (USD/hm³)
filling_target_violation_costFloat64No—USD/hm³Filling target violation override (USD/hm³)
turbined_violation_below_costFloat64No—USD/(m³/s·h)Turbined below-minimum violation override (USD/(m³/s·h))
outflow_violation_below_costFloat64No—USD/(m³/s·h)Outflow below-minimum violation override (USD/(m³/s·h))
outflow_violation_above_costFloat64No—USD/(m³/s·h)Outflow above-maximum violation override (USD/(m³/s·h))
generation_violation_below_costFloat64No—USD/MWhGeneration below-minimum violation override (USD/MWh)
fpha_violation_costFloat64No—USD/MWhFPHA plane violation override (USD/MWh)
evaporation_violation_costFloat64No—USD/(m³/s·h)Symmetric evaporation violation override (USD/(m³/s·h)). The stage value also sets the stage’s two directional evaporation costs, except a direction the row sets in its own column. See Directional evaporation and withdrawal costs.
evaporation_violation_pos_costFloat64No—USD/(m³/s·h)Over-evaporation violation override, evaporation above the target (USD/(m³/s·h))
evaporation_violation_neg_costFloat64No—USD/(m³/s·h)Under-evaporation violation override, evaporation below the target (USD/(m³/s·h))
water_withdrawal_violation_costFloat64No—USD/(m³/s·h)Symmetric water withdrawal violation override (USD/(m³/s·h)). The stage value also sets the stage’s two directional withdrawal costs, except a direction the row sets in its own column. See Directional evaporation and withdrawal costs.
water_withdrawal_violation_pos_costFloat64No—USD/(m³/s·h)Water withdrawal violation override, over-delivery (USD/(m³/s·h))
water_withdrawal_violation_neg_costFloat64No—USD/(m³/s·h)Water withdrawal violation override, under-delivery (USD/(m³/s·h))
inflow_nonnegativity_costFloat64No—USD/(m³/s·h)Inflow non-negativity penalty override (USD/(m³/s·h)); used under the penalty and truncation_with_penalty methods

Methodology: Penalty System

NameTypeRequiredDefaultUnitsDescription
ncs_idInt32Yes——Non-controllable source ID
stage_idInt32Yes——Stage ID
curtailment_costFloat64No—USD/MWhCurtailment penalty override (USD/MWh); >= 0.0