Add new solver documentation

Signed-off-by: Peter Mitri <peter.mitri@rte-france.com>

docs/user-guide/solver/00-index.md

@@ -1,17 +1,14 @@
 [//]: # (Index used by Sphinx to generate correct PDF tree)
+
 # Solver
 
 ```{toctree}
 :hidden:
 
 01-overview-solver.md
-02-inputs.md
-03-outputs.md
-04-parameters.md
-05-model.md
-06-hydro-heuristics.md
-07-thermal-heuristic.md
-08-command-line.md
+legacy-solver/00-index.md
+new-solver/00-index.md
+02-command-line.md
 optional-features/00-index.md
-09-appendix.md
+03-appendix.md
 ```

docs/user-guide/solver/01-overview-solver.md

@@ -4,61 +4,17 @@ _**This section is under construction**_
 
 The *Solver* is *Antares Simulator*'s main feature.
 
-**Monte Carlo Simulation** Runs either an economy simulation or an adequacy simulation
-depending on the values of the [parameters](04-parameters.md).
-If hardware resources and simulation settings allow it, simulations can benefit from [multi-threading](optional-features/multi-threading.md).
-
-
-## Antares at one glance
-
-This section gives a summary of the whole simulation process followed by Antares in Economy simulations (Adequacy being simplified variant of it):
-
-1. Load or Generate [stochastic generators] Time-series of every kind for all system areas
-
-2. For each Monte-Carlo year, pick up at random or not [scenario builder] one time-series of each kind for each area/link
-
-3. For each area and each reservoir:
-
-    1. Split up the annual overall hydro storage inflows into monthly hydro storage generation, taking into account reservoir constraints, hydro management policy and operation conditions (demand, must-run generation, etc.) [heuristic + optimizer]
-
-    2. For every day of each month, break down the monthly hydro energy into daily blocks, taking into account hydro management policy and operation conditions (demand, must-run generation, etc.) [heuristic + optimizer]. Aggregate daily blocks back into weekly hydro storage energy credits (used if the final optimization is run with full weekly 168-hour span)
-
-    3. For each week of the year (daily/weekly hydro energy credits are now known in every area), run a three-stage 168-hour optimization cycle (or seven 24-hour optimizations, if the optimization preference is set to "daily"). This aim of this cycle is to minimize the sum of all costs throughout the optimization period. This sum may include regular proportional fuel costs, start-up and no-load heat costs, unsupplied and spilled energy costs, and hurdle costs on interconnection. The solution has to respect minimum and maximum limits on the power output of each plant, minimum up and down durations, as well as interconnection capacity limits and "binding constraints" at large (which may be technical – e.g. DC flow rules – or commercial – e.g. contracts). Note that an accurate resolution of this problem requires mixed integer linear programming (because of dynamic constraints on thermal units). A simplified implementation of this approach is used when the advanced parameter "Unit commitment" is set on "accurate". This high quality option may imply long calculation times. This is why, when "Unit commitment" is set on "fast", Antares makes further simplifications that save a lot of time (starting costs are not taken into account within the optimization step but are simply added afterwards, units within a thermal cluster are subject to starting up/shutting down constraints more stringent than the minimum up/down durations). In both cases, the general optimization sequence is as follows:
-
-       i. Minimization of the overall system cost throughout the week in a continuous relaxed linear optimization. Prior to the optimization, an 8760-hourly vector of operating reserve R3 (see next section) may be added to the load vector (this will lead in step (ii) to identify plants that would not be called if there were no reserve requirements. Their actual output will be that found in step (iii), wherein the load used in the computations takes back its original value)
-
-       ii. So as to accommodate the schedule resulting from (i), search for integer values of the on/off variables that satisfy the dynamic constraints with the smallest possible cost increase.
-
-       iii. Take into account the integer variables found in (ii) and solve again the optimal schedule problem for the week.
-
-## Operating reserves modeling
-
-Many definitions may be encountered regarding the different operating reserves (spinning / non-spinning, fast / delayed, primary-secondary-tertiary, frequency containment reserve – frequency restoration reserve – replacement reserve, etc.).
-
-Besides, all of them need not be modeled with the same level of accuracy in a simulator such as Antares. Furthermore, the best way to use the concept is not always quite the same in pure Adequacy studies and in Economy studies.
-
-Several classes of reserves may therefore be used in Antares; how to use them at best depend on the kind and quality of operational data at hand, and on the aim of the studies to carry out; though all kinds of reserves may always be defined in the INPUT dataset, the set of reserves that will effectively be used depends on the kind of simulations to run. Note that any or all classes of reserves may be ignored in a given simulation (without being removed from the INPUT dataset) by setting the matching "optimization preference" to "ignore reserve X":
-
-- **Pre-allocated reserve on dispatchable thermal plants (R0)** <br/>
-  This reserve (which corresponds to the parameter "spinning" attached to the thermal plants) is expressed as a percentage of the nominal capacity of the plants. It is simply used as a derating parameter: for instance, a 1000 MW plant with a 2.5% spinning parameter will not be able to generate more than 975 MW. It is important to notice that, if the plant is not scheduled on, it will NOT contribute to the spinning reserve (to be effectively available, the 25 MW of reserve would need the plant to be started). This first class of reserve is available for **Adequacy** as well as for **Economy**.
-
-- **Day-ahead reserve (R3):** <br/>
-  This reserve is available in **Adequacy** and **Economy** simulations, with the following meaning:
-  "For any day D, to be able to accommodate last-minute random variations of the expected demand and/or generation (as they were seen from day D -1), a certain amount of power (R3) should be ready to be available at short notice".
-  <br/>
-  In actual operating terms, R3 is a complex (spinning/non-spinning) mix as well as (hydro/thermal) mix. It may involve or not part of the primary and secondary power/frequency regulation reserves. R3 may represent as much as the overall amount of frequency containment reserve, frequency restoration reserve and replacement reserve required for operation on day D, as seen from day D-1.
-  <br/>
-  In the simulations, R3 is construed as a "virtual" increase of the load to serve, which influences the optimal unit commitment and dispatch (because of minimum stable power levels and minimum On / Down times).
-
-**IMPORTANT:**
-
-The optimization makes sure that, should the need arise, reserve R3 will actually be available where it is needed **BUT** there is no commitment regarding whether this service should be provided by an increase of local generation, a decrease of exports or even an increase of imports: the optimizer will choose the mix leading to the minimal cost for the system.
-
-Note that this "standard" feature of Antares makes it possible to assess the potential value of keeping some headroom in interconnections for the purpose of transferring operating reserves, when "remote" reserves are less expensive than domestic ones.
-
-The table below gives an overview of the different reserves available in Antares
-
-|      | _Economy_ | _Adequacy_ |
-|------|-----------|------------|
-| _R0_ | _Yes_     | _Yes_      |
-| _R3_ | _Yes_     | _Yes_      |
+As of 2024, this feature is being overhauled to allow more flexibility in the definition of physical models.
+
+- The existing solver will still be maintained for a few years, you can find its
+  documentation under the ["legacy solver" section](legacy-solver/01-overview-legacy-solver.md).
+- The new solver will be gradually enriched to cover all existing features, you can find its
+  documentation under the ["new solver" section](new-solver/01-overview-new-solver.md).
+- It will be possible, for a few transitional years, to define "hybrid" studies,
+  mixing [legacy models](legacy-solver/05-model.md) with [new models](new-solver/05-model.md). This is
+  documented [here](new-solver/07-hybrid-studies.md).
+
+As a consequence, you will be able to use the solver with three types of studies: legacy studies, new studies, and
+hybrid studies.  
+All these possibilities are offered by the same "antares-solver" executable ; it is able to adapt to the different input
+files. Its usage is documented [here](02-command-line.md).

docs/user-guide/solver/legacy-solver/00-index.md

@@ -0,0 +1,14 @@
+[//]: # (Index used by Sphinx to generate correct PDF tree)
+
+# Legacy Solver
+
+```{toctree}
+:hidden:
+01-overview-legacy-solver.md
+02-inputs.md
+03-outputs.md
+04-parameters.md
+05-model.md
+06-hydro-heuristics.md
+07-thermal-heuristic.md
+```

docs/user-guide/solver/legacy-solver/01-overview-legacy-solver.md

@@ -0,0 +1,64 @@
+# Overview
+
+_**This section is under construction**_
+
+The *Solver* is *Antares Simulator*'s main feature.
+
+**Monte Carlo Simulation** Runs either an economy simulation or an adequacy simulation
+depending on the values of the [parameters](04-parameters.md).
+If hardware resources and simulation settings allow it, simulations can benefit from [multi-threading](optional-features/multi-threading.md).
+
+
+## Antares at one glance
+
+This section gives a summary of the whole simulation process followed by Antares in Economy simulations (Adequacy being simplified variant of it):
+
+1. Load or Generate [stochastic generators] Time-series of every kind for all system areas
+
+2. For each Monte-Carlo year, pick up at random or not [scenario builder] one time-series of each kind for each area/link
+
+3. For each area and each reservoir:
+
+    1. Split up the annual overall hydro storage inflows into monthly hydro storage generation, taking into account reservoir constraints, hydro management policy and operation conditions (demand, must-run generation, etc.) [heuristic + optimizer]
+
+    2. For every day of each month, break down the monthly hydro energy into daily blocks, taking into account hydro management policy and operation conditions (demand, must-run generation, etc.) [heuristic + optimizer]. Aggregate daily blocks back into weekly hydro storage energy credits (used if the final optimization is run with full weekly 168-hour span)
+
+    3. For each week of the year (daily/weekly hydro energy credits are now known in every area), run a three-stage 168-hour optimization cycle (or seven 24-hour optimizations, if the optimization preference is set to "daily"). This aim of this cycle is to minimize the sum of all costs throughout the optimization period. This sum may include regular proportional fuel costs, start-up and no-load heat costs, unsupplied and spilled energy costs, and hurdle costs on interconnection. The solution has to respect minimum and maximum limits on the power output of each plant, minimum up and down durations, as well as interconnection capacity limits and "binding constraints" at large (which may be technical – e.g. DC flow rules – or commercial – e.g. contracts). Note that an accurate resolution of this problem requires mixed integer linear programming (because of dynamic constraints on thermal units). A simplified implementation of this approach is used when the advanced parameter "Unit commitment" is set on "accurate". This high quality option may imply long calculation times. This is why, when "Unit commitment" is set on "fast", Antares makes further simplifications that save a lot of time (starting costs are not taken into account within the optimization step but are simply added afterwards, units within a thermal cluster are subject to starting up/shutting down constraints more stringent than the minimum up/down durations). In both cases, the general optimization sequence is as follows:
+
+       i. Minimization of the overall system cost throughout the week in a continuous relaxed linear optimization. Prior to the optimization, an 8760-hourly vector of operating reserve R3 (see next section) may be added to the load vector (this will lead in step (ii) to identify plants that would not be called if there were no reserve requirements. Their actual output will be that found in step (iii), wherein the load used in the computations takes back its original value)
+
+       ii. So as to accommodate the schedule resulting from (i), search for integer values of the on/off variables that satisfy the dynamic constraints with the smallest possible cost increase.
+
+       iii. Take into account the integer variables found in (ii) and solve again the optimal schedule problem for the week.
+
+## Operating reserves modeling
+
+Many definitions may be encountered regarding the different operating reserves (spinning / non-spinning, fast / delayed, primary-secondary-tertiary, frequency containment reserve – frequency restoration reserve – replacement reserve, etc.).
+
+Besides, all of them need not be modeled with the same level of accuracy in a simulator such as Antares. Furthermore, the best way to use the concept is not always quite the same in pure Adequacy studies and in Economy studies.
+
+Several classes of reserves may therefore be used in Antares; how to use them at best depend on the kind and quality of operational data at hand, and on the aim of the studies to carry out; though all kinds of reserves may always be defined in the INPUT dataset, the set of reserves that will effectively be used depends on the kind of simulations to run. Note that any or all classes of reserves may be ignored in a given simulation (without being removed from the INPUT dataset) by setting the matching "optimization preference" to "ignore reserve X":
+
+- **Pre-allocated reserve on dispatchable thermal plants (R0)** <br/>
+  This reserve (which corresponds to the parameter "spinning" attached to the thermal plants) is expressed as a percentage of the nominal capacity of the plants. It is simply used as a derating parameter: for instance, a 1000 MW plant with a 2.5% spinning parameter will not be able to generate more than 975 MW. It is important to notice that, if the plant is not scheduled on, it will NOT contribute to the spinning reserve (to be effectively available, the 25 MW of reserve would need the plant to be started). This first class of reserve is available for **Adequacy** as well as for **Economy**.
+
+- **Day-ahead reserve (R3):** <br/>
+  This reserve is available in **Adequacy** and **Economy** simulations, with the following meaning:
+  "For any day D, to be able to accommodate last-minute random variations of the expected demand and/or generation (as they were seen from day D -1), a certain amount of power (R3) should be ready to be available at short notice".
+  <br/>
+  In actual operating terms, R3 is a complex (spinning/non-spinning) mix as well as (hydro/thermal) mix. It may involve or not part of the primary and secondary power/frequency regulation reserves. R3 may represent as much as the overall amount of frequency containment reserve, frequency restoration reserve and replacement reserve required for operation on day D, as seen from day D-1.
+  <br/>
+  In the simulations, R3 is construed as a "virtual" increase of the load to serve, which influences the optimal unit commitment and dispatch (because of minimum stable power levels and minimum On / Down times).
+
+**IMPORTANT:**
+
+The optimization makes sure that, should the need arise, reserve R3 will actually be available where it is needed **BUT** there is no commitment regarding whether this service should be provided by an increase of local generation, a decrease of exports or even an increase of imports: the optimizer will choose the mix leading to the minimal cost for the system.
+
+Note that this "standard" feature of Antares makes it possible to assess the potential value of keeping some headroom in interconnections for the purpose of transferring operating reserves, when "remote" reserves are less expensive than domestic ones.
+
+The table below gives an overview of the different reserves available in Antares
+
+|      | _Economy_ | _Adequacy_ |
+|------|-----------|------------|
+| _R0_ | _Yes_     | _Yes_      |
+| _R3_ | _Yes_     | _Yes_      |

docs/user-guide/solver/new-solver/00-index.md

@@ -0,0 +1,15 @@
+[//]: # (Index used by Sphinx to generate correct PDF tree)
+
+# New Solver
+
+```{toctree}
+:hidden:
+01-overview-new-solver.md
+02-inputs.md
+03-outputs.md
+04-parameters.md
+05-model.md
+06-heuristics.md
+07-standard-library.md
+08-hybrid-studies.md
+```

docs/user-guide/solver/new-solver/01-overview-new-solver.md

@@ -0,0 +1,12 @@
+# Overview
+
+_**Disclaimer: please note that the new Antares solver is still under development, and that some of the features
+described in this section may still be unavailable**_
+
+The new Antares solver allows more flexibility in the definition of physical models used in the simulation. By doing so,
+it allows the users to conduct complex studies leveraging advanced physical models with highly customizable behavior.
+
+All this is achieved by allowing the user to define the MIP variables and constraints behind every physical model
+instantiated in their energy system.  
+Of course, Antares is also delivered with a riche set of [standard models]() that can be used out-of-the-box, and that
+can cover a large scope of everyday studies.

docs/user-guide/solver/new-solver/02-inputs.md

@@ -0,0 +1,3 @@
+# Input files
+
+_**This section is under construction**_

docs/user-guide/solver/new-solver/03-outputs.md

@@ -0,0 +1,3 @@
+# Output files
+
+_**This feature is under development**_

docs/user-guide/solver/new-solver/04-parameters.md

@@ -0,0 +1,3 @@
+# Parameters
+
+_**This feature is under development**_

docs/user-guide/solver/new-solver/05-model.md

@@ -0,0 +1,34 @@
+# Optimization model
+
+_**This section is under construction**_
+
+The new Antares optimization model is all about giving the user the power to define the mathematical model of every
+physical element in the system. Elements of this model are described in this section.
+
+## Models
+
+A model defines the behavior of an element in the simulated system. Several elements can have the same behavior, and
+therefore the same model.
+For example, a "FlexibleLoad" model can define the behavior of a flexible demand.
+
+The basic attributes of a model are:
+
+- a list of parameters: these are the input data required by the model.  
+  For example: the nominal power of the groups in a thermal cluster, the value of a load, etc.  
+  A parameter can be time-step-dependent or not, and scenario-dependent or not.
+- a list of potentially bounded variables: these are the quantities whose values the simulation will have to define.
+  For example: the power produced by a thermal cluster, or the level of a stock.
+- a list of constraints: these are equations that link parameters and model variables.
+  For example, for a battery, we might have an equation of the following type:  
+  level[t] - level[t-1] - efficiency * injection + withdrawal = inflows
+- a contribution to system cost, defined on the basis of model parameters and variables.  
+  For example, for a thermal cluster, the contribution might look like this:  
+  time_sum(cost * generation)
+
+```puml
+@startuml
+class Model {
++ List<Parameter> parameters
+}
+@enduml
+```

docs/user-guide/solver/new-solver/06-heuristics.md

@@ -0,0 +1,3 @@
+# Heuristics
+
+_**This feature is under development**_

docs/user-guide/solver/new-solver/07-standard-library.md

@@ -0,0 +1,3 @@
+# Standard library
+
+_**This feature is under development**_

docs/user-guide/solver/new-solver/08-hybrid-studies.md

@@ -0,0 +1,3 @@
+# Hybrid studies
+
+_**This feature is under development**_