Deprecated functionality

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 is scheduled for removal from the SHOP code.

Deprecated objects

The following objects are deprecated and will be removed in a future SHOP version:

Object type	Scheduled for removal	Recommended modelling approach
junction	v19.0.0, Q3 2027	Replace a junction with two or more tunnel objects, see the junction and junction_gate example.
junction_gate	v19.0.0, Q3 2027	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	v19.0.0, Q3 2027	Replace a creek_intake with a small reservoir object connected to a tunnel object, see the creek modelling example for best practices.
gate	v19.0.0, Q3 2027	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_head_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_head_ref_up_flow_curve or delta_head_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	Scheduled for removal	Recommended modelling approach
MULTI_OBJECT_DATA	v19.0.0, Q3 2027	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	v19.0.0, Q3 2027	The old MARKET structure should be modelled using the new market object available in the API and in the ASCII format
PLANT_OUTLET	v19.0.0, Q3 2027	The PLANT_OUTLET structure can be replaced by modelling a tunnel network below the plants
STARTRES	v19.0.0, Q3 2027	The STARTRES structure can be replaced by setting the start_vol or start_head for each reservoir object as a regular double value in the ASCII file
INITIAL_STATE	v19.0.0, Q3 2027	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	v19.0.0, Q3 2027	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	Scheduled for removal	Recommended modelling approach
generator	prod_area	v19.0.0, Q3 2027	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	v19.0.0, Q3 2027	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	v19.0.0, Q3 2027	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	v19.0.0, Q3 2027	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	v19.0.0, Q3 2027	The river object should be used to model all forms of time delay. See the advanced time delay example for more information
market	load	v19.0.0, Q3 2027	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	v19.0.0, Q3 2027	The busbar object should be used to model the load, and reports power_deficit, and power_excess
market	prod_area	v19.0.0, Q3 2027	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	v19.0.0, Q3 2027	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).

In addition to removing the attributes in the table above, all reservoir and river attributes including 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.

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

BestProfit command changes

In addition, 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.

Renaming commands

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

Current command name	New command name	Scheduled for renaming
start sim	start optimization	v19.0.0, Q3 2027
start shopsim	start simulation	v19.0.0, Q3 2027

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