(prodrisk_cpar)=
# Control data in prodrisk.CPAR
The file prodrisk.CPAR contains control parameters for Prodrisk. The file format allows a keyword followed by a parameter and some optional comment. One does not have to specify values for all parameters, non-defined parameters will get default values. All possible control parameters are shown in the table below.

|Parameter name | API attribute |
|---------------|--------------|
|staiter	|[max_iterations](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#max-iterations)|
|miniter	|[min_iterations](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#min-iterations)|
|staiter1	|[max_iterations_first_run](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#max-iterations-first-run)|
|miniter1	|[min_iterations_first_run](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#min-iterations-first-run)|
|fkonv	    |[convergence_criteria](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#convergence-criteria)|
|stor	|[inf](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#inf)|
|alfastor	|[alfa_max](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#alfa-max)|
|ctank	|[water_ration_cost](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#water-ration-cost)|
|cforb_styr	|[bypass_cost](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#bypass-cost)|
|cflom_styr	|[overflow_cost](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#overflow-cost)|
|tommax	|[max_relaxation_iterations](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#max-relaxation-iterations)|
|haldkut	|[max_cuts_created](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#max-cuts-created)|
|str_magbr 	|[reservoir_soft_restriction_cost](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#reservoir-soft-restriction-cost)|
|antbru1	|[first_relaxation_parameter](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#first-relaxation-parameter)|
|slette_frekv	|[second_relaxation_parameter](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#second-relaxation-parameter)|
|slette_tol 	|[relaxation_tolerance](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#relaxation-tolerance)|
|juke_aggr_pravsn  	|[aggregated_price_period_start_week](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#aggregated-price-period-start-week)|
|jsekv_startuke	|[sequential_price_period_start_week](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#sequential-price-period-start-week)|
|jsekv_sluttuke   	|[sequential_price_period_end_week](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#sequential-price-period-end-week)|
|pqvalg	|[use_input_pq_curve](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#use-input-pq-curve)|
|magbal	|[reservoir_balance_option](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#reservoir-balance-option)|
|framsomsluttsim	|[forward_model_option](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#forward-model-option)|
|prisscenstrategi	|[price_scenario_option](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#price-scenario-option)|
|nodeprisprofil  	|[node_price_profile](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#node-price-profile)|
|suppress_seq_res	|[suppress_seq_res](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#suppress-seq-res)|
|use_reserve_up	    |[use_reserve_up](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#use-reserve-up)|
|use_reserve_down   |[use_reserve_down](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#use-reserve-down)|
|resstoy	|See [inflow_model](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#inflow-model)|
|lognormal_inflow|See [inflow_model](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#inflow-model)|
|n_kmeans       |[n_kmeans](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#n-kmeans)|
|read_inflow_h5 |[read_lognormal_model](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#read-inflow-h5)|
|n_gen_forward  |[n_generated_scenarios](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#n-generated-scenarios)|
|n_sample_forward  |[n_sample_scenarios](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#n-sample-scenarios)|
|gen_inflow_forw_type|[generated_inflow_type](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#generated-inflow-type)|
|last_iter_gen_forw  |[last_iteration_generated_scenarios](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#last-iteration-generated-scenarios)|
|min_iter_no_gen_forw|[min_iterations_without_generated_scenarios](https://docs.prodrisk.sintef.energy/objects/setting/setting.html#min-iterations-without-generated-scenarios)|

A description of each control parameter is provided below. We have divided the control parameters into 6 groups of convergence control, penalty values, solution procedure, inflow model, time resolution and miscellaneous features.

## Convergence control
**staiter        50,                               < Max. no. of iterations in final strategy computation**

**miniter       5,                                 < Min. no. of iterations in final strategy computation**

If Prodrisk is run twice to produce head-coefficients, STAITER and MINITER give the number of main iterations in the final run. The algorithm will run at least MINITER and at most STAITER main iterations in the final run. In large watercourses, 50 iterations may be too little to stabilize reservoir trajectories, but may be sufficient to stabilize the economical result.  

**staiter1       50,                              < Max. no. of iterations in initial strategy computation**

**miniter1      5,                                 < Min. no. of iterations in initial strategy computation**

If Prodrisk is run twice to produce head-coefficients, STAITER1 and MINITER1 give the number of main iterations in the initial run. The algorithm will run at least MINITER1 and at most STAITER1 main iterations in the initial run.

**fkonv 3.00,                                                    < Convergence criterion**

This convergence criterion examines the weighted deviation in all reservoirs in all weeks for all simulated scenarios. The deviation is calculated as the sum of all absolute deviations for all reservoirs divided by the sum of all maximum reservoirs, measured in energy. The convergence criterion is in percentage.

## Penalty values
The penalty values specified in prodrisk.CPAR can be seen as basic default values. A much finer control on penalty values is allowed by using the file straff.CPAR, see Penalty values.

**ctank      100.0 + highest market price,        <Cost for violating min. constraint**

Prodrisk has penalty variables for violating minimum constraints on reservoir levels and water release. The opportunity to violate constraints ensures that the model will always find a feasible solution. The standard cost is given by CTANK, and Prodrisk uses 2*CTANK to penalize negative reservoir levels. Although the model will use penalty variables whenever there is not sufficient water to meet the constraints, the water balances will still be correct. CTANK has the same unit as the market prices.

CTANK should be higher than all market prices than can occur in order to avoid that the model violates constraints to increase the profit. Prodrisk calulates a minimum value that is 10 higher than the highest market price encountered in the input data (max[price series, preference curve, water value]) to guarantee that the value is higher and then uses a default value with is 100 higher than this minimum value if no value is set. Avoid setting CTANK too high, as this can cause numerical problems.

CTANK will be replaced by penalty variables defined in the optional input file straff.CPAR. The exception is the penalty associated with negative reservoir level, which is always associated with CTANK.

**cforb_styr  0.10E-2,                                 <Cost of bypassing in simulation**

CFORB_STYR is the cost assigned to use of bypass in the forward simulation. CFORB_STYR has the same unit as the market prices.

**cflom_styr  0.20E-2,                                  <Cost of spilling in simulation**

CFLOM_STYR is the cost assigned to use of spillage in the forward simulation. This cost will prevent the model spilling water unless when other water routes can be used. CFLOM_STYR has the same unit as the market prices.

**str_magbr    5.00,                            < Cost of violating constraint on max. reservoir of type 1**

This parameter serves two purposes.

If there exists maximal reservoir constraints of type 1 (soft constraints), STR_MAGBR is the cost of violating these constraints. STR_MAGBR has the same monetary unit as for the market price, but is per m3, e.g., øre/m3. STR_MAGBR will be overridden by any values for CMamax defined in the file straff.CPAR for the specified reservoirs and time periods.
Reservoirs flagged as ‘buffer reservoirs’ are assigned a reservoir guideline curve. Operation deviating from the guideline curve will be penalized using STR_MAGBR. STR_MAGBR will be overridden by any values for CStyrbuf defined in the file straff.CPAR for the specified reservoirs and time periods.

## Solution procedure
Prodrisk solves a vast number of LP problems. Each LP problem is solved by relaxation; cuts for a given week and price point are first checked, and only the most violated cuts are added to the LP problem. In order to exploit the effect of warm start, the LP problem is kept in memory when solving similarly structured problems. Thus, as long as the LP problem is not rebuilt and cold-started, the number of embedded cuts grows.

The parameters ANTBRU1, TOMMAX, SLETTE_FREKV and SLETTE_TOL described below all relates to the relaxation procedure. One can experiment with these parameters to find the combination that gives the best performance for a given system, but is generally recommended to keep the default values.

**antbru1        1,                                  < Parameter in relaxation process**

Prodrisk checks if any of the available cuts for a given week and price point are violated, and then adds the ANTBRU1 most violated cut(s). 

**tommax          100,                              < Max. no of iterations in relaxation process**

Maximum number of iterations in the LP relaxation procedure.

**slette_frekv         30,                   < Parameter in relaxation process**

**slette_tol 0.20,                            < Tolerance in relaxation process**

When SLETTE_FREKV decision problems have been solved since last cold-start or removal of cuts, all cuts that are not binding (using a margin of SLETTE_TOL) will be removed from the LP problem in memory. Removing cuts may lead to additional iterations to reach convergence, but the workload in each iteration will be reduced.

**haldkut        500,                             < Max. no of cuts to store**

HALDKUT is the maximum number of cuts to be stored for each decision stage (week) and price node in the algorithm. Increasing HALDKUT will increase memory use and to some extent also the computation time. Decreasing HALDKUT might impact the convergence properties. Previous experimentation has shown that a value in the range 500-1000 has provided satisfactory performance.

**stor               0.10E+21,                      < Unlimited**

This value is used as an upper bound for variables with unlimited upper bound. CPLEX recognizes the default value as +∞. Setting this value too high may give numerical problems, depending on the LP solver being used.

**alfastor      0.10E+16,                           < Upper bound on expected profit function**

The variable representing future expected profit (α) has a separate upper bound ALFASTOR.

Logically –STOR < α < STOR, but Prodrisk uses –ALFASTOR < α < ALFASTOR to avoid numerical problems.

## Inflow Model
**lognormal_inflow          1,                      < use lognormal inflow model>**

Decides whether the lognormal inflow model should be used. If LOGNORMAL_INFLOW == 0, or if there is no license for lognormal inflow model available, then the value of RESSTOY decides which inflow model to use. For more information about the inflow models, see [Inflow models used in Prodrisk](../../inflow/inflow_model/inflow_model.md).

**n_kmeans                  10000,                  < Number of samples used in k-means algorithm>**

N_KMEANS is the number of samples to be used in the k-means clustering algorithm that is part of the lognormal inflow model. A higher number can give a higher precision in the inflow model, and a higher number of inflow series can require a higher number of samples. The number of clusters (K) is the same as the number of noise, and is decided by the parameters **NPRBRUK** and **NRSTKOM** from the file [tilsigsddp.CPAR](../../inflow/inflow_model/control_tilsigsddp_cpar.md).

**read_inflow_h5            0,                      < Use lognormal inflow model saved in H5 file>**

If a high number of samples is used in the k-means algorithm (N_KMEANS >= 100 000), then the preprocessing time can be long. Therefore it may be desired to read the inflow model from the previous run, which is saved in the H5 file *lognormalInflowModel*. The file is not meant to be provided by the user, only generated by Prodrisk in a previous run.

**resstoy                    0,                     < Type of inflow model if lognormal is not used**

RESTTOY defines the type of inflow model to be used in the backward recursion if LOGNORMAL_INFLOW is set to zero or if there is no license for lognormal inflow model. The default choice (0) is a model based on principal components. If one wants to use the residual-based inflow model, RESSTOY should be set to 1.

**n_gen_forward             0,                      < Number of generated scenarios used in the optimization>**

N_GEN_FORWARD decides whether to include additional generated scenarios in the forward simulation (and in the backward simulation). Inflow series for the scenarios are generated using the [inflow model](../../inflow/inflow_model/inflow_model.md) decided by the parameters LOGNORMAL_INFLOW and RESSTOY. Price series are drawn from the [price model](../../price/price_model/price_model.md).

If the additional inflow scenarios are used, the parameter *gen_inflow_forw_type* should be set and it is possible to decide that for the last iterations, only the historical inflow scenarios should be used. See [Including generated scenarios in the optimization](../../inflow/inflow_model/generated_scenarios.md) for more information.

**n_sample_forward             1000,                      < Number of sampled inflow scenarios to generate percentiles or extremes from>**

N_SAMPLE_FORWARD decides the number of inflow samples used when generating percentiles or extreme inflow series for the generated scenarios. This parameter is only relevant if n_gen_forward > 0,
and if gen_inflow_forw_type = 1 or 2. See [Including generated scenarios in the optimization](../../inflow/inflow_model/generated_scenarios.md) for more information.

**gen_inflow_forw_type            0,                      < Decides configuration of generated inflow scenarios>**

This parameter controls the sampling of generated inflow scenarios. The alternatives are:

- 0 - random inflow scenarios are used
- 1 - percentiles of the inflow scenarios are used
- 2 - extreme values of the inflow scenarios are used

The parameter is only relevant if N_GEN_FORWARD > 0. See [Including generated scenarios in the optimization](../../inflow/inflow_model/generated_scenarios.md) for more information.


**last_iter_gen_forw       1000,                 < Last iteration to use generated inflow scenarios in forward simulation>**

If this parameter is set, it indicates the last iteration where the generated scenarios should be used. If N_GEN_FORWARD == 0, the value of LAST_ITER_GEN_FORW is irrelevant.

**min_iter_no_gen_forw     10,                   < Minimum iterations without generated scenarios in forward simulation>**

This parameter decides the minimum number of iterations that should be run without generated scenarios at the end of the optimization. This means that although convergence is reached before the last iteration where generated scenarios should be used, there will still be a minimum number of iterations left with only historical scenarios. If this number is set to 0, only convergence and LAST_ITER_GEN_FORW decides. 

## Time resolution
**juke_aggr_pravsn   9999,            < First week aggregating load periods**

Aggregation of load periods mean running the model with weekly time resolution. The default value gives no aggregation. If one sets JUKE_AGGR_PRAVSN to 53, load periods will be aggregated to weekly time resolution from week 53 and to the end of the scheduling period.

**jsekv_startuke     1,                    <First week with sequential load periods**

JSEKV_STARTUKE indicates the first week that should be run with sequential load periods, provided that the use of sequential load periods has been specified by the user. This choice allows the user to run with coarser time resolution until JSEKV_STARTUKE.

**jsekv_sluttuke     9999,              <Last week with sequential load periods**

JSEKV_SLUTTUKE indicates the last week that should be run with sequential load periods, provided that the use of sequential load periods has been specified by the user. The default value ensures use of sequential load periods the entire scheduling period, if desired. I JSEKV_SLUTTUKE is set to 53 while JUKE_AGGR_PRAVSN takes its default value, accumulated load periods are used from week 53 and to the end of the scheduling period. JUKE_AGGR_PRAVSN overrides JSEKV_SLUTTUKE if these conflict.

**magbal                      1,                     <Reservoir balances within the week**

The default value sets the model to run with as many reservoir balances within the week as there are load periods.

If sequential load periods are desired (option –SEKV on the command line), the number of reservoir balances will always equal the number of load periods, independent of MagBal.
In weeks with weekly time resolution (i.e., week number greater or equal to JUKE_AGGR_PRAVSN), there will be one reservoir balance per week.
If accumulated load periods are used, the default is as many reservoir balances as there are accumulated load periods. If MagBal is set to 0, there will be one reservoir balance per week in the weeks with accumulated load periods.
## Miscellaneous features
**pqvalg                      1,                     <PQ-curve in final simulation[^1]**

The PQ-curve should be concave during a standard Prodrisk iteration (forward simulation and backward recursion). That is, the first PQ-segment has the highest efficiency, and the subsequent segments have equal or lower efficiencies than the previous one. If a non-concave PQ-curve is defined by the user, Prodrisk establishes a concave approximation for this purpose by removing non-concave points on the curve. During the final simulation, the default choice is to use the original PQ-curve when finding the total production. In case the original PQ-curve does not have successive lower efficiency with higher discharge, the total production will typically be lower than if we used the concave approximation. If PQValg is set to 0, Prodrisk will use the concave approximation in the final simulation.

**framsomsluttsim              1,         <Type of forward pass**

This parameter defines if the forward simulation should be made similar to the final simulation. This will allow using a non-convex PQ-curve in the forward iterations (if PQValg is set to 1) and allow for head-dependent maximum discharge.

**prisscenstrategi            0,         <Use of price scenarios in backward recursion**

For users defining several price scenarios per inflow scenario, one can in the backward recursion only create cuts for price scenario 1 for all inflow scenarios (default choice), or for the combination of all price scenarios and inflow scenarios (setting PriceScenStrategi to 1). The latter choice will increase the computation time significantly, but will provide more precise computations.

**nodeprisprofil            0,         <1 – Use price profile distributed on price nodes, 0 – Use traditional, uniform price profile**

Enables the node dependent price profile, see [Node dependent price profile](../../price/node_dependent_price_profile/node_dependent_price_profile.md)

**use_reserve_up              0,         <Use up regulation reserve market functionality**   

When set to 1, use_reserve_up indicates that Prodrisk should run with reserves in the up regulation market. For more information about the functionality, see [reserve markets](../../extra_functionality/reserve_markets/reserve_markets.md).

**use_reserve_down            0,         <Use down regulation reserve market functionality**   

When set to 1, use_reserve_down indicates that Prodrisk should run with reserves in the down regulation market. For more information about the functionality, see [reserve markets](../../extra_functionality/reserve_markets/reserve_markets.md).

[^1]: Have introduced choice **2** by non-convex PQ curve.