Deprecated functionality and planned changes

SHOP is an old program that has been under active development since the middle of the 1990s. From time to time it is necessary to remove deprecated functionality to keep the code base maintainable. This page lists functionality that is deprecated and scheduled for removal from the SHOP code, and also displays command and name changes.

SHOP 18.0.0 – Q2 2026

Name changes

• All reservoir and river attributes that include the word ‘head’ will be renamed to use the word ‘level’ instead, such as changing vol_head to vol_level. The old attribute names will still work as aliases for the new attributes, but dumping the model to YAML/JSON/ASCII will use the new attribute names. The old names will also not be used in the documentation any more. Full list of old names:

  • reservoir:

    • head

    • sim_head

    • start_head

    • vol_head

    • head_area

    • max_head_constr

    • max_head_constr_flag

    • min_head_constr

    • min_head_constr_flag

  • river:

    • up_head_flow_curve

    • delta_head_ref_up_flow_curve

    • delta_head_ref_down_flow_curve

• The objective attributes startup_costs and sim_startup_costs are renamed to start_stop_costs and sim_start_stop_costs to reflect that stop costs are also part of the calculations. The old attribute names will still function as aliases.

• The TXY/txy attribute datatype is renamed to timeseries throughout the documentation and in displayed warnings/errors. For backwards compatibility, pyshop, pybind and the SHOP Server REST API will still display “txy” when querying the datatype.

• The field data_func_name in the ObjectTypeInfoSchema of the SHOP Server Model will be renamed to alias.

• The info key dataFuncName is renamed to alias in GetValidAttributeInfoKeys() in pybind.

• An additional point has been added to several reservoir and battery attributes to reflect that they are momentary values at a specific point in time, similar to the storage attribute that has T+1 points. The values in input attributes like max_vol_constr will be applied for the volume at the specified time stamp instead of at the end of that time step (earlier behaviour). Output attributes will have an additional point and the values may be shifted by one time step compared to earlier versions. The change has been made for the following attributes:

  • reservoir input attributes:

    • sim_volume_schedule

    • sim_level_schedule

    • min_vol_constr

    • min_level_constr

    • min_vol_constr_flag

    • min_level_constr_flag

    • max_vol_constr

    • max_level_constr

    • max_vol_constr_flag

    • max_level_constr_flag

    • tactical_limit_min

    • tactical_level_limit_min

    • tactical_cost_min

    • tactical_limit_min_flag

    • tactical_cost_min_flag

    • tactical_limit_max

    • tactical_level_limit_max

    • tactical_cost_max

    • tactical_limit_max_flag

    • tactical_cost_max_flag

  • reservoir output attributes:

    • area

    • end_value

    • change_in_end_value

    • vow_in_transit

    • penalty

    • penalty_nok

    • end_penalty

    • endpoint_penalty

    • tactical_penalty_down

    • tactical_penalty_up

    • tactical_penalty

    • peak_volume_penalty

    • flood_volume_penalty

    • sim_water_surplus

    • sim_water_deficit

  • battery input attributes:

    • max_energy_constraint

    • min_energy_constraint

BestProfit command changes

The command print bp_curves will result in an error if the command create bp_curves has not been called before the print bp_curves command. In addition, the options

• “market_ref_mc”,

• “no_vertical_step”,

• “operation,

• “comb_upload”, and

• “production”

will be removed from the print bp_curves command, as they are only used when the BP curves are created. Similarly, the “discharge” command will be removed from the create bp_curves command since it is only used when writing the BP curves to file.

C API change

The function

• ShopGetAttributeDatatype() will return std::string instead of const char*, and the time series attribute datatype will now return “timeseries” instead of the old “txy” name.

• ShopGetAttributeDataFuncName will be renamed to ShopGetAttributeAlias.

SHOP 19.0.0 – Q3 2027

Deprecated objects

The following objects are deprecated and will be removed in SHOP 19:

Object type	Recommended modelling approach
junction	Replace a junction with two or more tunnel objects, see the junction and junction_gate example.
junction_gate	Replace a junction_gate with two or more tunnel objects. One or more of the tunnels should include a gate description to allow the tunnel to be closed, see the junction and junction_gate example. The interlock_constraint object can also be used to limit the number of tunnels that can be open or closed simultaneously
creek_intake	Replace a creek_intake with a small reservoir object connected to a tunnel object, see the creek modelling example for best practices.
gate	A gate should be replaced with either a tunnel object or a river object, depending on what the gate was used to model. See the Replacing gate objects section below for more details

Replacing gate objects

• Bypass gates and other gates that model a controllable release of water without any reservoir level dependency should be modelled as a minimal river object that only contain upstream_elevation and (potentially) a cost of releasing water.

• Spill gates and gates that define an upstream flow function table should also be modelled as a river object with an up_level_flow_curve and (potentially) a cost of releasing water. Spill rivers are explained in more detail in the overflow example.

• Gates that connect two reservoirs and use a deltameter flow function table that describe the flow between the reservoirs based on both upstream and downstream levels could either be modelled as a river object with a delta_level_ref_up_flow_curve or delta_level_ref_down_flow_curve curve, or as a tunnel object with a loss_factor. Using a tunnel to model the flow between the reservoirs will always assume that the relationship between the level difference and flow is described by the function: \(\Delta h = \alpha\cdot|q|q\). This means that explicit flow tables cannot be used with a tunnel modelling. The river object can use the specific tables in a similar way to the old gate object, but the modelling is typically more prone to errors in the linearization of the tables.

Note that the gate object required special information when connecting them to reservoirs as either spill or bypass gates. This is not necessary with the tunnel and river modelling.

Deprecated ASCII structures

The SHOP ASCII format contains old structures that are no longer needed due to the existence of the API. The following specialized ASCII structures will be removed in a future SHOP version:

ASCII structure	Recommended modelling approach
MULTI_OBJECT_DATA	The MULTI_OBJECT_DATA structure that only exists in the ASCII format will be removed as it is not possible to map directly to the API. The various constraints have been moved to other objects, mostly the discharge_group and production_group objects
MARKET	The old MARKET structure should be modelled using the new market object available in the API and in the ASCII format
PLANT_OUTLET	The PLANT_OUTLET structure can be replaced by modelling a tunnel network below the plants
STARTRES	The STARTRES structure can be replaced by setting the start_vol or start_level for each reservoir object as a regular double value in the ASCII file
INITIAL_STATE	The INITIAL_STATE structure can be replaced by setting the initial_state or initial_state for each generator and pump object as a regular int value in the ASCII file
NETWORK	The old NETWORK structure should be modelled using the new busbar object available in the API and in the ASCII format

Deprecated attributes

The following object attributes will be removed in a future SHOP version:

Object type	Attribute name	Recommended modelling approach
generator	prod_area	The busbar object should be used to model multiple load areas with ac_line or dc_line objects connecting the busbars together. See the power flow example for grid modelling. Each generator can be connected to a specific busbar.
plant	prod_area	The busbar object should be used to model multiple load areas with ac_line or dc_line objects connecting the busbars together. See the power flow example for grid modelling. Each generator and pump can be connected to a specific busbar.
plant	prod_area_flag	The busbar object should be used to model multiple load areas with ac_line or dc_line objects connecting the busbars together. See the power flow example for grid modelling. Each generator and pump can be connected to a specific busbar.
plant	time_delay	The river object should be used to model all forms of time delay. See the advanced time delay example for more information
plant	shape_discharge	The river object should be used to model all forms of time delay. See the advanced time delay example for more information
market	load	The busbar object should be used to model the load, while the market object only models the prices and volumes traded in the market. See the battery example for a simple illustration.
market	load_penalty	The busbar object should be used to model the load, and reports power_deficit, and power_excess
market	prod_area	The busbar object should be used to model multiple load areas with ac_line or dc_line objects connecting the busbars together. See the power flow example for grid modelling.
market	reserve_obligation_penalty	The reserve_group object is already used to model the reserve capacity obligation (such as frr_up_obligation), and already reports the violation of the obligation (such as frr_up_violation).

Deprecated commands

The effect of the following commands have already been removed from the SHOP code and will be deleted in SHOP v19.0.0 in Q3 of 2027:

• expand window

• individual penalty

• individual endpenalty

• set presim

• set overflow_cut_description

• set epsilon

• set tuning

• set mix_cut_vv

• data

• lose_spill

• set sim_schedule_correction

• set headopt_feedback

• set newgate

• set password

Renaming commands

The following commands will be renamed, though the old name will still function as an alias:

Current command name	New command name
start sim	start optimization
start shopsim	start simulation

The documentation and API will only use the new command names after they have been renamed.

Name changes

• The TXY/txy attribute will be named timeseries also in pyshop, pybind and the SHOP Server REST API when querying datatype.