Polish the doc related to the adq-patch (#776)

* Polish the doc related to the adq-patch

* Fix default value

* Slight modifications of the adequacy patch doc

Co-authored-by: PPlessiez <[email protected]>

docs/reference-guide/05-output_files.md

@@ -123,6 +123,7 @@ The area files that belong to the « values » class display **122** fields corr
 | AVL. DTG | Available dispatchable thermal generation (sum of av. power over all plants) |
 | DTG. MRG | Disp. Ther. Gen. (AVL DTG – sum of all dispatched thermal generation) |
 | MAX. MRG | Maximum margin: operational margin obtained if the hydro storage energy of the week were used to maximise margins instead of minimizing costs |
+| DENS | Domestic Energy Not Supplied: the difference between the local production capabilities of an area and its local load[^DENS] |
 | NP COST | Non-proportional costs of the dispatchable plants (start-up and fixed costs) |
 | NODU | Number of Dispatched Units [^13] |
 | Profit | Net profit of the cluster in euros ((MRG. PRICE - marginal cost of the cluster) * production of the cluster)  |
@@ -244,6 +245,8 @@ Alike Input data, output results can be filtered so as to include only items tha
 
 [^13]: NODU and NP Cost do not appear in "Adequacy" results since these variables are irrelevant in that context
 
+[^DENS]: Please note that this output variable is only available in the economy mode, when the adequacy patch is activated (see [Adequacy Patch](14-adequacy-patch.md))
+
 [^14]: This description applies to both « MC synthesis » files and "Year-by-Year" files, with some simplifications in the latter case
 
 [^agg]: This output is only available if the parameter "renewable generation modelling" is set to "cluster" in the input of the simulation

docs/reference-guide/08-miscellaneous.md

@@ -565,60 +565,4 @@ The Renewable window can be filled out with the different renewable clusters ins
 
 [^19]: If the playlist is full, these years have numbers # (k-1)B+1 ,…., #kB
 
-[^20]: Described in the note "Optimization Problems Formulation"
-
-##  Adequacy Patch calculation
-
-**Foreword** 
-
-The operational algorithm of Euphémia market coupling implements "de-optimization" rules in order to fix the sharing of “Energy Not Served” (ENS) between the market areas when there is any (in a way to ensure a certain fairness in the sharing of this ENS): this is what we call the adequacy patch. The requirement of fairness rules in the sharing of ENS within Antares studies increased with the introduction of flow-based modelling. Previously, this problem was mainly solved with the hurdle cost mechanism (small costs on interconnections) limiting exports from areas where ENS was encountered. However, implicit rules in Antares for sharing ENS, even outside the Flow-Based domain, are not fully satisfactory, even with hurdle costs, because they prioritize the treatment of ENS in countries directly connected to countries with margins, to the detriment of more distant countries. In a context of decommissioning of coal and nuclear plants in France and in Europe, cases of simultaneous ENS over the domain will increase. Consequently, the need of adequacy patch to share fairly this ENS is arising. 
-
-It should be noted that, in this release, the implementation covers only one of the three main features of the ‘curtailment sharing and minimization’ principles in EUPHEMIA, namely: 
-
-1. Local matching constraint.
-
-2. The implemented solution does not yet consider secondary problem of sharing of curtailment by the quadratic term. 
-
-3. The implemented solution does not yet consider the feature in EUPHEMIA, related to ‘minimization of curtailment’ in the primal problem which includes an extra penalty term directly in the global objective function in EUPHEMIA by a term multiplied with a large M pre-factor in the total welfare. 
-
-**Inclusion of the local matching rule** 
-
-The rule implemented is what we call the « Local Matching » rule:  
-
-- This rule consists in satisfying ENS <= DENS (Domestic Energy not Served) for all selected areas. 
-- An area cannot export more than its local margin.
-
-This means that an area which can serve local demand with local generation, should never have ENS. 
-
-**Notes**
-
-- The local matching rule is only part of the economic mode of Antares (Not the Adequacy or Draft mode); 
-
-- DENS outputs of Antares, for all selected areas, are available in the General values tab, as year-by-year and synthetic results. All the statistic values for it are calculated as well (min, max, mean, standard deviation). For the areas not selected, the output DENS is set to 0. 
-
-**Specifications of the evolution concerning the optimization problem** 
-
-To get the DENS to constrain the ENS variations of each area, it needs to be calculated through a first iteration. During this first iteration, the usual optimization problem is slightly modified before being solved. The objective of this first iteration is to get the ENS of each area to represent its DENS. In order to achieve this, links between areas are forced to have a capacity of 0. To ensure that customizable models will still work using this new feature. To do so, different categories are created for the areas, enabling different behaviours as needed. The different categories are: 
-
-- "0": The area is a virtual area, 
-- "1": The area is a physical area not included in the adequacy patch domain, 
-- "2": The area is a physical area included in the adequacy patch domain. 
-
-In the list of physical nodes, should be included also the "hub" node introduced for the Flow-based modelling (this one should be declared by the user in its list of physical nodes). 
-
-In the first iteration, the following link capacities in the following direction will be set to 0: 
-
-- node "2" <-> node "2" 
-- node "2" -> node "1" 
-- node "1" -> node "2": optional/user defined (default 0), 
-- node "1" <-> node "1": optional/user defined (default 0). 
-
-Once the first iteration is completed, we have access to the DENS value: 
-- DENS = ENS
- (when link capacities between physical nodes are set to 0 (iteration 1)). 
-
-During the second iteration, all link capacities between physical nodes are set to the values given by input data (as it is done in actual Antares version). The only change is that the upper bound of the ENS on specified areas is now constrained by the DENS found during the first iteration. This is introduced in the optimization problem for physical nodes that are declared in the adequacy patch domain (nodes declared as "2"):  
-
-- ENS <= DENS 
- (on each selected area). 
-
+[^20]: Described in the note "Optimization Problems Formulation" 

docs/reference-guide/13-file-format.md

@@ -3,16 +3,28 @@ This is a list of all recent changes that came with new Antares Simulator featur
 
 ## v8.3.0
 ### Input
-In file **settings/generaldata.ini**, add section `adequacy patch`, with keys
+In file **settings/generaldata.ini**, add section `adequacy patch`, with properties
 
 * `include-adq-patch` [bool]. Default value = `false`
 * `set-to-null-ntc-from-physical-out-to-physical-in-for-first-step` [bool]. Default value = `true`
 * `set-to-null-ntc-between-physical-out-for-first-step` [bool]. Default value = `true`
 
-In existing section `optimization`, add key `include-split-exported-mps` [bool]. Default value = `false`
+In existing section `optimization`, add property `include-split-exported-mps` [bool]. Default value = `false`
 
 Add variables `DENS` and `Profit by plant`, which may be used for thematic trimming, see file **settings/generaldata.ini**, section `variables selection`.
 
+For each area, add a new file **input/areas/<area>/adequacy_patch.ini** containing a single section `adequacy-patch`. This section contains a single property `adequacy-patch-mode`, that can take values
+
+* `outside`
+* `inside`
+* `virtual`
+
+Example
+```
+[adequacy-patch]
+adequacy-patch-mode = outside
+```
+
 ### Output
 * If `include-adq-patch` is set to `true`, add column `DENS` in files **values-<period>.txt** (mc-all & mc-ind)
 * Add `Profit by plant` column in files **details-<period>.txt** (mc-all & mc-ind)

docs/reference-guide/14-adequacy-patch.md

@@ -0,0 +1,60 @@
+# Adequacy Patch calculation
+
+## Foreword
+
+The operational algorithm of Euphémia market coupling implements "de-optimization" rules in order to fix the sharing of “Energy Not Served” (ENS) between the market areas when there is any (in a way to ensure a certain fairness in the sharing of this ENS): this is what we call the adequacy patch.  
+The requirement of fairness rules in the sharing of ENS within Antares studies increased with the introduction of flow-based modelling. Previously, this problem was mainly solved with the hurdle cost mechanism (small costs on interconnections) limiting exports from areas where ENS was encountered. However, implicit rules in Antares for sharing ENS, even outside the Flow-Based domain, are not fully satisfactory, even with hurdle costs, because they prioritize the treatment of ENS in countries directly connected to countries with margins, to the detriment of more distant countries. In a context of decommissioning of coal and nuclear plants in France and in Europe, cases of simultaneous ENS over the domain will increase. Consequently, the need of adequacy patch to share fairly this ENS is arising.
+
+It should be noted that, in the current implementation of the patch within Antares, the implementation covers only one of the three main features of the ‘curtailment sharing and minimization’ principles in EUPHEMIA, namely:
+
+1. Local matching constraint.
+
+2. The implemented solution does not yet consider secondary problem of sharing of curtailment by the quadratic term.
+
+3. The implemented solution does not yet consider the feature in EUPHEMIA, related to ‘minimization of curtailment’ in the primal problem which includes an extra penalty term directly in the global objective function in EUPHEMIA by multiplying the maximum curtailment ratio with a large M pre-factor in the total welfare.
+
+## Local matching rule
+
+The rule implemented is called the « Local Matching » rule:
+
+- This rule consists in satisfying **ENS \\(\leq\\) DENS** (Domestic Energy not Served) for all physical areas inside the adequacy patch.
+- It specifies that an area cannot export more than its local margin.
+
+This means that an area which can serve local demand with local generation, should never have ENS.
+
+_**Notes**_
+
+- _The local matching rule is only part of the economic mode of Antares (Not the Adequacy or Draft mode);_
+- _DENS outputs of Antares, for all selected areas, are available in the General values tab, as year-by-year and synthetic results. All the statistic values for it are calculated as well (min, max, mean, standard deviation). For the areas not part of the patch, the output DENS is set to 0._
+
+### Specifications of the evolution concerning the optimization problem
+
+To calculate the DENS used to constrain the ENS variations of each area, a first iteration is performed. During this first iteration, the usual optimization problem is slightly modified before being solved. The objective of this first iteration is to get an ENS of each area which will represent its DENS. In order to achieve this, links between areas are forced to have a capacity of 0. To ensure that customizable models will still work using this new feature, different categories are created for the areas, enabling different behaviours as needed. The different categories are:
+
+- "virtual": The area is a virtual area,
+- "physical outside": The area is a physical area not included in the adequacy patch domain,
+- "physical inside": The area is a physical area included in the adequacy patch domain.
+
+In case Flow-Based is represented in the study, the "hub" node introduced for the Flow-based modelling should also be included in the list of physical areas (this one should be declared by the user in its list of physical nodes).
+
+#### First iteration
+
+In the first iteration, the following link capacities in the following direction will be set to 0 MW:
+
+- node "physical inside" <-> node "physical inside"
+- node "physical inside" -> node "physical outside"
+- node "physical outside" -> node "physical inside": optional/user defined (default `true`),
+- node "physical outside" <-> node "physical outside": optional/user defined (default `true`).
+
+Once the first iteration is completed, we have access to the DENS value, which represents the ability of an area to fulfil its local load thanks to its local production capacities:
+- DENS = ENS for each physical area inside the adequacy patch perimeter
+
+#### Second iteration
+
+During the second iteration, all link capacities between physical nodes are set to the values provided as input data (as it is done in the current Antares version). The only change compared to a simulation without the adequacy patch is that the upper bound of the ENS on the areas included in the patch is now constrained by the DENS found during the first iteration. This is introduced in the optimization problem for physical areas that are declared in the adequacy patch domain (areas declared as "physical inside"):
+
+- ENS <= DENS
+ (for all physical areas inside the adequacy patch).
+
+## Curtailment sharing rule
+The curtailment sharing rule will be implemented in Antares Simulator 8.4. It will include an hourly post-processing phase.

mkdocs.yml

@@ -41,6 +41,7 @@ nav:
     - 'Miscellaneous': 'reference-guide/08-miscellaneous.md'
     - 'System requirements': 'reference-guide/09-system_requirements.md'
     - 'Command line': 'reference-guide/10-command_line.md'
+    - 'Adequacy patch (v8.3.0+)': 'reference-guide/14-adequacy-patch.md'
     - 'File format changes': 'reference-guide/13-file-format.md'
     - 'Attribution notices': 'reference-guide/12-attribution_notices.md'
   - 'Optimisation problem' : 'reference-guide/11-modeling.md'