reservoir

reservoir#

A reservoir that is part of a regulated hydropower watercourse


Input connections	plant, gate, junction, volume_constraint, cut_group, inflow_series, tunnel, river
Output connections	plant, river, gate, tunnel, cut_group, inflow_series, junction_gate, junction, creek_intake, volume_constraint
License	SHOP_OPEN
Release version	13.0.0.a

Required input #

The reservoir object is one of the fundamental building blocks of a SHOP model, and has the following mandatory input attributes:

max_vol: Maximum volume of the reservoir at the point of forced overflow.
lrl: Lowest regulated level, should correspond to zero volume stored.
hrl: Highest regulated level, should correspond to max_vol volume stored.
vol_head: The relation between reservoir volume and level (masl).
start_head / start_vol: The reservoir level at the beginning of the optimisation, either given in masl or Mm3.

The relation between volume and level is required and given by the vol_head attribute, which is a piecewise linear XY-curve. The vol_head curve should go above the point (max_vol, hrl) to describe overflow situations. The total reservoir volume before forced overflow is given by max_vol. The max_vol attribute can either represent only the active volume or the full volume of the reservoir. If only the active volume is considered, lrl will coincide with zero volume.

Reservoir level limit constraints #

The user can specify different types of reservoir limits to enforce correct physical behaviour and to enforce different physical and environmental restrictions. Figure 1 illustrates the available reservoir level limits and Table 1 gives an overview of their related inputs and outputs.


Figure 1: Overview of reservoir limit types.

Attribute	Constraint type	Penalty input	Penalty output	Objective
flow_descr [meter]		overflow_cost		nonphysical_spill_cost, physical_spill_cost
max_vol,hrl	soft	penalty_cost	penalty, endpoint_penalty	rsv_penalty, rsv_end_penalty
max_vol_constr	hard
tactical_limit_max	soft	tactical_cost_max	tactical_penalty_up, tactical_penalty	rsv_tactical_penalty
tactical_limit_min	soft	tactical_cost_min	tactical_penalty_down, tactical_penalty	rsv_tactical_penalty
min_vol_constr	hard
lrl	soft	penalty_cost	penalty, endpoint_penalty, end_penalty	rsv_penalty, rsv_end_penalty

The outer limits are typically max_vol, hrl and lrl, which represent the physical limts the system is designed for and regulated to operate within. These are soft constraints, allowing SHOP to provide a solution even in situations where the input is overspecified so that no physical solution exist. In this case, a penalty will be applied.

The min_vol_constr and max_vol_constr are time dependent operation constraints. These can, for example, be used if the system must be operated within given limits due to maintenance. However, hard constraints should be used carefully since they may cause infeasibility or non-physical behaviour in other parts of the system.

The tactical limits, tactical_limit_min and tactical_limit_max, let the user specify time dependent soft constraints at a time dependent self defined cost.

Additionally, the reservoir level can be constrained by ramping constraints, such as level_ramping_up, level_ramping_down, and the dynamic_level_limit constraint.

Overflow #

In reservoirs where overflow may occur, the vol_head curve must also contain the relevant space above the hrl and max_vol. To ensure that the spilled water is directed to the right reservoir and assigned a reasonable penalty cost, the reservoir object should be connected to a river, with the river upstream_elevation equal to the reservoir hrl. The overflow rate as a function of the reservoir level is then described by the up_head_flow_curve, and an overflow penalty can be given by setting the river flow_cost. The river can be connected to a downstream reservoir if the spillage should be directed there instead of to the ocean. This is described in more detail in the overflow example.

Previously, the gate object has been used for overflow modelling. Gate objects will be removed in SHOP 19 (2027 Q2), and so using rivers is the recommended way for future compatibility. To model overflow using gates, the upstream reservoir has to been connected to the gate using connection type SPILL. Overflow is described by the flow_descr XY-curve, where the x-values represents reservoir levels and the y-values are the overflow rates in \(m^3/s\). The first xy pair must be hrl and zero, meaning that there is no overflow at hrl. The following xy pairs must have increasing x and y values.

Physical overflow description#

The overflow description is a linear relaxation, hence overflow may occur in situations where it is not physically possible. SHOP includes a MIP formulation that can be used to prevent this, which can be activated using the river mip_flag, reservoir overflow_mip_flag, or universal_overflow_mip. See the overflow modelling example for further details.

Water values #

The value of stored water beyond the optimization horizon will typically come from a seasonal- or long-term model. Details on how to set the water values can be found here. Se also the individual water values example.

Reservoir schedule, slack and cut descriptions#

Reservoir schedule can be used instead of water values to impose a specific strategy on a reservoir. Since this limits the way the system can be operated, it should be used very carefully. A schedule can be set either for the end value or for specific moments throughout the optimization period. The reservoir upper_slack and lower_slack limits can be used in combination with a reservoir schedule. When upper_slack and/or lower_slack is used together with a schedule, the reservoir trajectory is bound to be within the upper_slack and lower_slack values. If only one of the slack parameters are given, the reservoir schedule will act as the missing upper/lower bound.

For further details on the use of reservoir schedule see the reservoir schedule example.

Ramping #

Ramping constraints limit how rapidly the volume or head of a reservoir can change over time, for example, to avoid excessive wear of the reservoir shores. Ramping constraints can be set individually for the up and down direction. They can be set in terms of volume with volume_ramping_up and volume_ramping_down, or in terms of level with level_ramping_up and level_ramping_down.

Other ramping constraint types include level_amplitude_ramping_limit_up, level_amplitude_ramping_limit_down, level_nonseq_ramping_limit_up and level_nonseq_ramping_limit_down, demonstrated in the amplitude and non-sequential ramping example. Complex ramping is demonstrated in the complex ramping on reservoir level example. The complex ramping types include limit_level_period_ramping_up, limit_level_period_ramping_down, average_level_rolling_ramping_up and average_level_rolling_ramping_down. The dynamic_level_limit constraint is similar to the limit period level ramping, except the difference in reservoir level is found within the same time period instead of between consecutive time periods. See the reservoir dynamic level limit example for more information about this constraint.

Examples #

References #

Modelling overflow using mixed integer programming in short-term hydropower scheduling [21]

Attributes #

latitude#

Reserved for future use. Unit: NO_UNIT.

longitude#

Reserved for future use. Unit: NO_UNIT.

max_vol#

Maximum volume of the reservoir. Unit: MM3.

lrl#

Lowest Regulation Level (meter above sea level) of the reservoir. Unit: METER.

hrl#

Highest Regulation Level (meter above sea level) of the reservoir. Unit: METER.

vol_head#

The volume (Mm3) and water level (meter above sea level) relation of the reservoir. The list should cover all feasible reservoir level values so that the volume-head conversion is always successful. Units: x: MM3 and y: METER.

head_area#

The water level (meter above sea level) and surface area (Km2) relation of the reservoir. Units: x: METER and y: KM2.

elevation_adjustment#

Adjustment for the lowest regulation level (lrl), highest regulation level (hrl), and the volume (Mm3) and water level (meter above sea level) relation of the reservoir. Unit (y): METER.

start_vol#

Reservoir start volume. If start_vol and start_head are both defined, the value of the prefer_start_vol attribute on global_settings will decide which is used. Unit: MM3.

start_head#

Reservoir start water level (meter above sea level). If start_vol and start_head are both defined, the value of the prefer_start_vol attribute on global_settings will decide which is used. Unit: METER.

inflow#

Natural inflow to reservoir. Unit (y): M3/S.

inflow_flag#

Flag determining whether the inflow to a reservoir should be used as input or calculated as output in the simulation: 0 = input; 1 = output. Unit (y): NO_UNIT.

sim_inflow_flag#

Flag determining whether inflow should be simulated to reservoir or not. Unit (y): NO_UNIT.

flow_descr#

The water level (meter above sea level) and overflow (m3/s) relation of the reservoir. Only used when a spill gate is connected, please see the overflow modelling example. Units: x: METER and y: M3/S.

overflow_mip_flag#

Flag determining whether the binary variables should be used to prevent non-physical spill. Unit (y): NO_UNIT.

overflow_cost#

Overflow cost for the reservoir. Unit (y): NOK/MM3.

overflow_cost_flag#

Flag determining whether overflow cost for this reservoir should be included in the optimization model. Unit (y): NO_UNIT.

min_vol_constr#

Time-dependent minimum volume limit for the reservoir. Unit (y): MM3.

min_vol_constr_flag#

Flag determining whether the time-dependent minimum volume limit for the reservoir should be included in the optimization model. Unit (y): NO_UNIT.

max_vol_constr#

Time-dependent maximum volume limit for the reservoir. Unit (y): MM3.

max_vol_constr_flag#

Flag determining whether the time-dependent maximum volume limit for the reservoir should be included in the optimization model. Unit (y): NO_UNIT.

min_head_constr#

Time-dependent minimum water level limit for the reservoir. The min_vol_constr attribute is preferred if it is present for the same reservoir. Unit (y): METER.

min_head_constr_flag#

Flag determining whether the time-dependent minimum water level limit for the reservoir should be included in the optimization model. Unit (y): NO_UNIT.

max_head_constr#

Time-dependent maximum water level limit for the reservoir. The max_vol_constr attribute is preferred if it is present for the same reservoir. Unit (y): METER.

max_head_constr_flag#

Flag determining whether the time-dependent maximum water level limit for the reservoir should be included in the optimization model. Unit (y): NO_UNIT.

tactical_limit_min#

Tactical (soft) minimum volume limit for the reservoir. Unit (y): MM3.

tactical_limit_min_flag#

Flag determining whether the tactical minimum volume limit should be included in the optimization model. Unit (y): NO_UNIT.

tactical_cost_min#

Given penalty cost for violating the tactical minimum volume limit for the reservoir. Unit (y): NOK/MM3H.

tactical_cost_min_flag#

Flag determining whether the penalty cost for violating the tactical minimum volume limit should be included in the optimization model. Unit (y): NO_UNIT.

tactical_limit_max#

Tactical (soft) maximum volume limit for the reservoir. Unit (y): MM3.

tactical_limit_max_flag#

Flag determining whether the tactical maximum volume limit should be included in the optimization model. Unit (y): NO_UNIT.

tactical_cost_max#

Given penalty cost for violating the tactical maximum volume limit for the reservoir. Unit (y): NOK/MM3H.

tactical_cost_max_flag#

Flag determining whether the penalty cost for violating the tactical maximum volume limit should be included in the optimization model. Unit (y): NO_UNIT.

tactical_level_limit_min#

Tactical minimum level limit for the reservoir. Unit (y): METER.

tactical_level_limit_max#

Tactical maximum level limit for the reservoir. Unit (y): METER.

upper_slack#

Used to expand the upper reservoir limit when running with an active reservoir schedule so that the volume can be between the schedule and upper_slack. Unit (y): MM3.

lower_slack#

Used to expand the lower reservoir limit when running with an active reservoir schedule so that the volume can be between the schedule and lower_slack. Unit (y): MM3.

schedule#

Reservoir volume schedule used to specify the volume of the reservoir in each time step. Must be combined with a schedule_flag to be active. Unit (y): MM3.

schedule_flag#

Flag determining whether the reservoir volume schedule should be included in the optimization model: 0 = no schedule; 1 = the endpoint interval upper_slack and lower_slack is valid; 2 = reservoir volume schedule is valid anywhere during the optimization period. Unit (y): NO_UNIT.

sim_volume_schedule#

Reservoir volume schedule used in the SHOP simulator when simulating reservoir inflow with the /inflow command option. The sim_volume_schedule takes precedence over the sim_level_schedule if both are defined. If neither attribute is defined, the storage attribute (result from the optimization) is used. Unit (y): MM3.

sim_level_schedule#

Reservoir water level schedule used in the SHOP simulator when simulating reservoir inflow with the /inflow command option. The sim_volume_schedule takes precedence over the sim_level_schedule if both are defined. If neither attribute is defined, the storage attribute (result from the optimization) is used. Unit (y): METER.

volume_ramping_up#

Maximum limit for increase in reservoir volume per hour. Unit (y): MM3/HOUR.

volume_ramping_down#

Maximum limit for decrease in reservoir volume per hour. Unit (y): MM3/HOUR.

level_ramping_up#

Maximum limit for increase in reservoir level per hour. Unit (y): METER/HOUR.

level_ramping_down#

Maximum limit for decrease in reservoir level per hour. Unit (y): METER/HOUR.

water_value_input#

The input water value description of water values referred to the sea. Can be a single constant value, a water value table (xy), or cut coefficients for a single or multiple price nodes. In the case of price dependent cut coefficients, the reference value of each xy in the xy_array should be the relevant price level. Units: x: MM3 and y: NOK/MM3.

energy_value_input#

The input local energy value of the reservoir which will be converted to a global water value internally. Unit: NOK/MWH.

peak_volume_cost_curve#

A piece-wise constant increasing cost which is applied to the highest reservoir volume reached in the optimization horizon. Units: x: MM3 and y: NOK/MM3.

flood_volume_cost_curve#

A piece-wise constant increasing cost curve which is used to penalize the reservoir volume level in each hour of the optimzation. Units: x: MM3 and y: NOK/MM3.

evaporation_rate#

Evaporation rate of water from the reservoir. Unit (y): METER/HOUR.

level_rolling_ramping_penalty_cost#

The penalty cost for breaking any rolling ramping constraint applied to the reservoir level. Unit (y): NOK/METER.

level_period_ramping_penalty_cost#

The penalty cost for breaking any period ramping constraint applied to the reservoir level. Unit (y): NOK/METER.

average_level_rolling_ramping_up#

Input to specify rolling ramping constraints that constrain the reservoir level upwards from the average reservoir level in a rolling time window. The x-values represent the length of the rolling time window and the y-values specify the number of meters the reservoir level can increase above the average rolling level. Each (x, y) point in each xy curve represents a rolling ramping constraint. Units: x: MINUTE and y: METER.

average_level_rolling_ramping_down#

Input to specify rolling ramping constraints that constrain the reservoir level downwards from the average reservoir level in a rolling time window. The x-values represent the length of the rolling time window and the y-values specify the number of meters the reservoir level can decrease below the average rolling level. Each (x, y) point in each xy curve represents a rolling ramping constraint. Units: x: MINUTE and y: METER.

limit_level_rolling_ramping_up#

Input to specify rolling ramping constraints that constrain the reservoir level upwards from the minimal reservoir level in a rolling time window. The x-values represent the length of the rolling time window and the y-values specify the number of meters the reservoir level can increase above the minimal rolling level. Each (x, y) point in each xy curve represents a rolling ramping constraint. Units: x: MINUTE and y: METER.

limit_level_rolling_ramping_down#

Input to specify rolling ramping constraints that constrain the reservoir level downwards from the maximal reservoir level in a rolling time window. The x-values represent the length of the rolling time window and the y-values specify the number of meters the reservoir level can decrease below the maximal rolling level. Each (x, y) point in each xy curve represents a rolling ramping constraint. Units: x: MINUTE and y: METER.

average_level_period_ramping_up#

Input to specify period ramping constraints that constrain the reservoir level upwards from the average reservoir level in a fixed time window. The x-values represent the length of the fixed time window and the y-values specify the number of meters the reservoir level can increase above the average level in the previous fixed time period. Each (x, y) point in each xy curve represents a period ramping constraint. Units: x: MINUTE and y: METER.

average_level_period_ramping_down#

Input to specify period ramping constraints that constrain the reservoir level downwards from the average reservoir level in a fixed time window. The x-values represent the length of the fixed time window and the y-values specify the number of meters the reservoir level can decrease below the average level in the previous fixed time period. Each (x, y) point in each xy curve represents a period ramping constraint. Units: x: MINUTE and y: METER.

limit_level_period_ramping_up#

Input to specify period ramping constraints that constrain the reservoir level upwards from the minimal reservoir level in a fixed time window. The x-values represent the length of the fixed time window and the y-values specify the number of meters the reservoir level can increase above the minimal level in the previous fixed time period. Each (x, y) point in each xy curve represents a period ramping constraint. Units: x: MINUTE and y: METER.

limit_level_period_ramping_down#

Input to specify period ramping constraints that constrain the reservoir level downwards from the maximal reservoir level in a fixed time window. The x-values represent the length of the fixed time window and the y-values specify the number of meters the reservoir level can decrease below the maximal level in the previous fixed time period. Each (x, y) point in each xy curve represents a period ramping constraint. Units: x: MINUTE and y: METER.

historical_level#

The reservoir level for times before the optimization start. The input start volume or start level of the reservoir will override any value in this time series that corresponds to the start time of the optimization, values inside the optimization horizon are ignored. The datatype of this attribute changed from xy to txy in version 15.3.1.0. Unit (y): METER.

average_level_period_ramping_up_offset#

The y-values must be the same as the period lengths used in the average_level_period_ramping_up attribute, while the strings are timestamps that specify when the first whole ramping period starts for each of the average ramping up period constraints. Units: s: STRING and y: MINUTE.

average_level_period_ramping_down_offset#

The y-values must be the same as the period lengths used in the average_level_period_ramping_down attribute, while the strings are timestamps that specify when the first whole ramping period starts for each of the average ramping down period constraints. Units: s: STRING and y: MINUTE.

limit_level_period_ramping_up_offset#

The y-values must be the same as the period lengths used in the limit_level_period_ramping_up attribute, while the strings are timestamps that specify when the first whole ramping period starts for each of the limit ramping up period constraints. Units: s: STRING and y: MINUTE.

limit_level_period_ramping_down_offset#

The y-values must be the same as the period lengths used in the limit_level_period_ramping_down attribute, while the strings are timestamps that specify when the first whole ramping period starts for each of the limit ramping up period constraints. Units: s: STRING and y: MINUTE.

volume_nonseq_ramping_limit_up#

Limit volume ramping between two non-sequential time steps. Start time is given by time T, duration by X and ramping by Y. Units: x: MINUTE and y: MM3.

volume_nonseq_ramping_limit_down#

Limit volume ramping between two non-sequential time steps. Start time is given by time T, duration by X and ramping by Y. Units: x: MINUTE and y: MM3.

volume_amplitude_ramping_limit_up#

Limit volume ramping between in time interval. Start time is given by time T, duration by X and ramping by Y. Units: x: MINUTE and y: MM3.

volume_amplitude_ramping_limit_down#

Limit volume ramping between in time interval. Start time is given by time T, duration by X and ramping by Y. Units: x: MINUTE and y: MM3.

level_nonseq_ramping_limit_up#

Limit level ramping between two non-sequential time steps. Start time is given by time T, duration by X and ramping by Y. Units: x: MINUTE and y: METER.

level_nonseq_ramping_limit_down#

Limit level ramping between two non-sequential time steps. Start time is given by time T, duration by X and ramping by Y. Units: x: MINUTE and y: METER.

level_amplitude_ramping_limit_up#

Limit level ramping between in time interval. Start time is given by time T, duration by X and ramping by Y. Units: x: MINUTE and y: METER.

level_amplitude_ramping_limit_down#

Limit level ramping between in time interval. Start time is given by time T, duration by X and ramping by Y. Units: x: MINUTE and y: METER.

dynamic_level_limit#

Input to specify the maximum difference between the max and min reservoir level within given time periods. The x-values represent the length of the fixed time period and the y-values specify the max difference in reservoir level within that time period. Units: x: MINUTE and y: METER.

dynamic_level_limit_offset#

The y-values must be the same as the period lengths used in the dynamic_level_limit attribute, while the strings are timestamps that specify when the first whole dynamic level limit period starts for each of the dynamic level limit constraints. Units: s: STRING and y: MINUTE.

dynamic_level_limit_penalty_cost#

The penalty cost for breaking the dynamic reservoir level limits. Unit (y): NOK/METER.

storage#

Resulting reservoir volume, includes both the start volume and the final end volume in the optimization. Unit (y): MM3.

sim_storage#

Simulated reservoir volume. Unit (y): MM3.

head#

Resulting reservoir water level (meter above sea level), calculated by converting the volume of the reservoir with the vol_head_curve. Unit (y): METER.

area#

Resulting reservoir surface area (km2), used to calculate evaporation. Unit (y): KM2.

sim_head#

Simulated reservoir water level (meter above sea level). Unit (y): METER.

sim_inflow#

Simulated inflow to the reservoir that is calculated when the SHOP simulator is used to calculate inflow with the /inflow command option. Unit (y): M3/S.

sim_water_surplus#

Simulated reservoir volume that has been subtracted from the simulation to maintain the reservoir below the maximal volume defined in the vol_head curve. Similar to reservoir penalty from the optimization. Unit (y): MM3.

sim_water_deficit#

Simulated reservoir volume that has been added from the simulation to maintain the reservoir above 0 Mm3. Similar to reservoir penalty from the optimization. Unit (y): MM3.

endpoint_penalty#

Resulting penalty when the maximum or minimum volume limit for the reservoir at the end of the optimization period is violated. Unit (y): MM3.

penalty#

Resulting penalty when the maximum or minimum volume limit for the reservoir during the optimization period is violated. Unit (y): MM3.

tactical_penalty_up#

Resulting penalty when the tactical maximum volume limit for the reservoir is violated. Unit (y): MM3.

tactical_penalty_down#

Resulting penalty when the tactical minimum volume limit for the reservoir is violated. Unit (y): MM3.

end_penalty#

Resulting penalty cost when the maximum or minimum volume limit for the reservoir at the end of the optimization period is violated. Unit (y): NOK.

penalty_nok#

Resulting penalty cost when the maximum or minimum volume limit for the reservoir during the optimization period is violated. Unit (y): NOK.

tactical_penalty#

Resulting penalty cost when the tactical maximum or minimum volume limit for the reservoir is violated. Unit (y): NOK.

water_value_global_result#

Marginal cost of 1 Mm3 of the water in the reservoir calculated using the sum of the best efficiency point of all cascaded plants below this reservoir. Unit (y): NOK/MM3.

water_value_local_result#

Marginal cost of 1 Mm3 of the water discharged from the reservoir through the downstream plant. Unit (y): NOK/MM3.

energy_value_local_result#

Marginal cost of 1 MWh power that generated from the water in the reservoir through the downstream plant. Unit (y): NOK/MWH.

end_value#

Value of reservoir contents at the end of the optimization period. Unit (y): NOK.

change_in_end_value#

Relative change in value of reservoir contents between the start and the end of the optimization horizon. Unit (y): NOK.

vow_in_transit#

Value of delayed water on its way to this reservoir after the end of the optimization period. Unit (y): NOK.

calc_global_water_value#

The resulting global water value of the reservoir after the local energy value has been converted internally based on the energy_conversion_factor reservoir attribute. Unit: NOK/MM3.

energy_conversion_factor#

The calculated conversion factor between MWh and Mm3 based on the first plant below the reservoir and initial start head. Unit: MWH/MM3.

water_value_cut_result#

The resulting output water value cut coefficients when SHOP is used to create cuts. Units: x: MM3 and y: NOK/MM3.

added_to_network#

Flag determining whether the model has determined that this reservoir is part of a tunnel network. Unit: NO_UNIT.

network_no#

Network identification number set by the model to indicate which tunnel network this reservoir is part of. Unit: NO_UNIT.

peak_volume_penalty#

The peak volume penalty incurred for the reservoir, zero in all time steps except for when the reservoir volume peak occurs. Unit (y): NOK.

flood_volume_penalty#

The penalty incurred for the reservoir based on the optimized reservoir volume and the flood_volume_cost_curve. Unit (y): NOK.