(cut-standard)= # Cut file standards Using cuts is a common way of defining the end [water value function](water-value-descriptions) for the hydropower system in SHOP. SHOP can parse two different text file formats for cuts, which is based on the output cut files produced by the [Prodrisk](https://prodrisk.sintef.energy) and [EOPS](https://ltm.sintef.energy) models developed by SINTEF. Dumping a SHOP model that includes cuts to [ASCII](ascii-data), [JSON](json-standard), or [YAML](yaml-standard) files will store the cut information using the [](cut_group) and [](inflow_series) objects and the [](reservoir:water_value_input) attribute of the connected [reservoirs](reservoir). The cut_group will have connections to the reservoirs and inflow_series that are present in the cut file, and reading in multiple cut files will generate multiple cut_group objects. Note that the text files specified in this document can be read into SHOP with the `read_ascii_file` function in [](pyshop). (module-rsv-coupling-files)= ## Coupling modules and reservoirs The long-term models use an aggregated "module" description that contains a reservoir and a plant object. The cuts information is given on module level, and a mapping between module number in the long-term model and the reservoir name in SHOP is therefore needed. There are two equivalent formats of these coupling files: (namelist)= ### NAMELIST A text file starting with the keyword `NAMELIST` will be interpreted as a cut coupling file. The structure is shown below: NAMELIST -1 In the following example, Reservoir1 corresponds to module 8001 in the long-term model, Reservoir2 and Reservoir3 are aggregated in module 8002 while Reservoir4 corresponds to module 8003. NAMELIST Reservoir1 8001 Reservoir2 8002 Reservoir3 8002 Reservoir4 8003 -1 (namelist-icc)= ### NAMELIST_ICC A text file that starts with the keyword `NAMELIST_ICC` will also be interpreted as a cut coupling file. The structure is shown below: NAMELIST_ICC , , , -1 The number may be one of the following. - 0, Comment line, line ignored. (In addition lines started by #, blank lines and lines started with unknown numbers are also treated as comments.) - 2, The value is a module number. - 3, The value is a name belonging to the most recently read module number. The name is assumed to contain no blanks. The same example provided for the [NAMELIST](namelist) format is repeated here in the `NAMELIST_ICC` format: #Object_type NAMELIST_ICC 0, Example of a namelist. #Reservoir1 is module 8001 2, 8001 3, Reservoir1 #In the SHOP_WATER_VALUE data, Reservoir2 and Reservoir3 are aggregated in module 8002 2, 8002 3, Reservoir2 3, Reservoir3 #Reservoir4 is module 8003 2, 8003 3, Reservoir4 -1 ## Cuts that are independent of price For regular cuts that don't depend on the price, the `SHOP_WATER_VALUES` structure is used. The module numbers are connected to SHOP reservoirs through the data parsed in either the [NAMELIST](namelist) or [NAMELIST-ICC](namelist-icc) data formats, which must be read **before** the SHOP_WATER_VALUES file. SHOP_WATER_VALUES #Start set block #Start cut block 1 #End cut block 1 #Start cut block 2 : #One cut block for each cut : #End block #End block 1 #Start set block 2 : #One set block for each area/watercourse : #End set block N -1 The following example sets 11 cuts for one watercourse with 3 reservoirs. #Object_type SHOP_WATER_VALUES #Number_of_cuts Number_of_reservoirs 3 11 #Cut_number Future_cost_in_1000_NOK 1 553312.1 #Water values for eleven reservoirs in 0.01 NOK/M3 28.5524 16.16501 30.05662 27.31609 18.33097 31.69323 18.33097 23.42278 23.42282 18.18101 0.553201 #Reservoir levels for eleven reservoirs in % 52.02749 56.55629 47.51908 50.97015 48.0 55.62481 49.70543 56.47799 60.0 65.08929 0.0 #Cut_number Future_cost_in_1000_NOK 2 570255.6 #Water values for eleven reservoirs in 0.01 NOK/M3 28.39524 16.06559 29.71364 27.1114 18.07443 31.32807 18.07443 21.75594 21.75604 17.91683 0.526877 #Reservoir levels for eleven reservoirs in % 59.36426 59.85431 56.94656 57.70149 57.82609 59.23583 57.78295 59.84277 62.5 78.75 56.66 #Cut_number Future_cost_in_1000_NOK 3 577362.1 #Water values for eleven reservoirs in 0.01 NOK/M3 27.75463 15.46218 29.55889 27.048 17.98072 31.18911 17.98072 21.38204 21.3822 17.81284 0.525238 #Reservoir levels for eleven reservoirs in % 63.43642 61.74834 60.57252 60.1194 61.56522 60.74695 60.75969 61.32076 67.5 95.0 81.94 #Water conversion factors kwh/m3 0.662361 0.841444 0.587607 0.428571 0.0 0.729769 0.0 0.0 0.607639 0.985663 2.79412E-02 #Module numbers 7811 7810 7814 7815 7906 7818 7903 7911 7813 7812 7809 -1 (price-dependent-cut-file)= ## Price-dependent cuts Using a text input file starting with the `SHOP_EXT_WATER_VALUES` structure is used for reading in price- and inflow-dependent cut data in to SHOP. A coupling file using either the [NAMELIST](namelist) or [NAMELIST-ICC](namelist-icc) data formats must be read before reading the `SHOP_EXT_WATER_VALUES` structure. In addition, a [cut order file](cut-order-file) must be read in before the `SHOP_EXT_WATER_VALUES` to correctly map the cut coefficients of the reservoirs and the [](inflow_series) objects. - The first column is the price level in 0.01 NOK/kWh the cut is generated for. - Second column is the expected future value of the cut in 1000 NOK. - Third column is the number of modules in the cut, n_mod. - The next columns are n_mod pairs of cut coefficients in 0.01 NOK/M3 and reference volume in % for each module. - The following column is the number of inflow series in the cut, n_inflow. - The final n_inflow columns are the inflow coefficients for each inflow series. The example below shows cuts for two price levels, three modules and three inflow series #Object_type SHOP_EXT_WATER_VALUES #Price Future_value n_mod coeff_mod1 ref_mod1 coeff_mod2 ref_mod2 coeff_mod3 ref_mod3 n_inflow coeff_inflow1 coeff_inflow2 coeff_inflow3 13.5 1505341.2 3 37.4 4.1 37.4 0.007 51.0 1.1 3 0.0 0.0 0.0 13.5 1505690.3 3 76.1 0.2 55.5 0.08 91.9 0.8 3 0.0 0.0 0.0 15.9 1518310.1 3 44.2 4.1 44.2 0.007 59.4 1.1 3 0.0 0.0 0.0 15.9 1518738.0 3 84.7 0.2 59.8 0.08 100.7 0.8 3 0.0 0.0 0.0 (cut-order-file)= ### Cut order file A text file starting with the keyword `CUTORDER` is used for defining the order of modules and inflow series in the [price-dependent cut file](price-dependent-cut-file). A [cut coupling file](module-rsv-coupling-files) must be read first to connect module numbers with reservoir names in SHOP. The cut order file consists of four columns: - The first column is the order of the module. 0 means that no cut data is given for this module. - The second column is the number of the module. - The third column is the order of the regulated inflow series for the module. - The fourth column is the order of the unregulated inflow series for the module. The example below shows that cut coefficients are given for modules 8001, 8002 and 8003 in that order. No cut coefficients are given for module 8000. Modules 8001 and 8002 both share the first inflow series, while 8003 has the second inflow series. The inflow series for module 8000 is the last one in the cut file. #Object_type CUTORDER 1 8001 1 1 2 8002 1 1 3 8003 2 2 0 8000 3 3