Add new solver documentation (#2473)

Signed-off-by: Peter Mitri <[email protected]>

.github/workflows/build-userguide.yml

@@ -75,4 +75,3 @@ jobs:
         tag: ${{ github.event.inputs.release_tag }}
       run: |
         gh release upload "$tag" ${{ env.PDF_PATH }}      
-

docs/README.md

@@ -60,29 +60,29 @@ In every *Antares Simulator* [release](https://github.com/AntaresSimulatorTeam/A
 the user guide is printed to a PDF file and published in the assets. This document can be downloaded by users who 
 want to install *Antares Simulator* and be able to consult its documentation off-line.  
 
-In practice, the PDF is generated automatically from Markdown files under [reference-guide](./user-guide) by 
+In practice, the PDF is generated automatically from Markdown files under [user-guide](./user-guide) by 
 [Sphinx](https://www.sphinx-doc.org/) (using LaTeX). The script for this generation is in [pdf-doc-generation-with-sphinx/create_pdf_doc.sh](./pdf-doc-generation-with-sphinx/create_pdf_doc.sh); 
 it is automatically run by a GitHub [action](../.github/workflows/build-userguide.yml) during every release, and for 
 each pull request (in order to verify that the PDF builds).  
 
 While the source material used for the PDF user guide are the same as the ones used for the mkdocs website (i.e. 
-Markdown files under `reference-guide`), some extra source files are needed:
+Markdown files under `user-guide`), some extra source files are needed:
 - As for all Sphinx projects, this one needs a configuration file: [conf.py](./pdf-doc-generation-with-sphinx/source/conf.py). 
   This file allows you to customize the Sphinx build, in the same way mkdoks.yml allows you to customize mkdocs build. 
 - Sphinx navigation is built iteratively, using "index" files that refer to each other. The top-most index file is 
   [pdf-doc-generation-with-sphinx/source/index.rst](./pdf-doc-generation-with-sphinx/source/index.rst). It points to 
-  [reference-guide/00-index.md](user-guide/00-index.md), which in turns points to other pages or indexes, 
-  defining the whole navigation tree of the documentation. **This [reference-guide/00-index.md](user-guide/00-index.md) 
+  [user-guide/00-index.md](user-guide/00-index.md), which in turns points to other pages or indexes, 
+  defining the whole navigation tree of the documentation. **This [user-guide/00-index.md](user-guide/00-index.md) 
   file should be updated** in the same way mkdocs.yml is, in order to keep the navigation tree of the PDF document 
   synchronized with the navigation tree of the mkdocs website.
 
 When modifying the user guide content, you can easily preview the resulting PDF on your PC by navigating to the 
 root of the project and running:
 ```bash
 cd docs/pdf-doc-generation-with-sphinx
-bash create_pdf_doc.sh reference-guide.pdf
+bash create_pdf_doc.sh user-guide.pdf
 ```
-Sphinx will create a `reference-guide.pdf` file in `docs/pdf-doc-generation-with-sphinx`.
+Sphinx will create a `user-guide.pdf` file in `docs/pdf-doc-generation-with-sphinx`.
 
 ### Doxygen
 [//]: # (TODO)

docs/developer-guide/6-Contributing.md

@@ -2,7 +2,7 @@
 
 In general, [Google's coding standard](https://google.github.io/styleguide/cppguide.html) is used, and we strongly encourage to read it.
 
-You can find all the steps needed to build & install Antares Simulator in the [documentation website](https://antares-simulator.readthedocs.io/) or [its sources](docs/developer-guide/0-Introduction.md).
+You can find all the steps needed to build & install Antares Simulator in the [documentation website](https://antares-simulator.readthedocs.io/) or [its sources](https://github.com/AntaresSimulatorTeam/Antares_Simulator).
 
 Below are our specific (but not all!) exceptions to the Google's coding standard:
 
@@ -19,7 +19,7 @@ Below are our specific (but not all!) exceptions to the Google's coding standard
 Naming and formatting
 
 - We ALWAYS use 4 spaces indent and don't use tabs.
-- We don't have strict limits on line width, but keep it reasonable to fit on the screen. The advised width is that written in the [src/.clang-format](src/.clang-format) file (currently 100).
+- We don't have strict limits on line width, but keep it reasonable to fit on the screen. The advised width is that written in the [src/.clang-format](https://github.com/AntaresSimulatorTeam/Antares_Simulator/blob/develop/src/.clang-format) file (currently 100).
 - Doxygen-style comments can be used.
 - Use left-to-right order for variables/params: `const string& s` (reference to the const string).
 - In one line `if`, `for`, `while` we use brackets.
@@ -74,7 +74,7 @@ The description should be short but proportional to the length or complexity of
 When a pull request is opened, please set it to draft if it is still being worked on or not ready for review.
 
 If your Pull Request changes a part of the code that is [documented](https://antares-simulator.readthedocs.io/), 
-please update the documentation also, in the ["docs"](docs) directory.
+please update the documentation also, in the ["docs"](https://github.com/AntaresSimulatorTeam/Antares_Simulator/tree/develop/docs) directory.
 
 ## ClangFormat
 
@@ -85,7 +85,7 @@ To automatically format a file, install `clang-format` and run:
 
 clang-format 18.1.3 is the reference version, but any 18.x version should work as well. We strongly advise that you configure your IDE / text editor to automatically format code according to the clang-format style. Non-conforming code can't be merged to the develop branch.
 
-You may also use script [src/format-code.sh](src/format-code.sh) to format all the code. Generated code (ANTLR, etc.) won't be automatically formatted.
+You may also use script [src/format-code.sh](https://github.com/AntaresSimulatorTeam/Antares_Simulator/blob/develop/src/format-code.sh) to format all the code. Generated code (ANTLR, etc.) won't be automatically formatted.
 
 ## Formatting Example/Guide/Reference
 

docs/developer-guide/Architecture/Dynamic-modeler-architecture.md

@@ -0,0 +1,131 @@
+# Dynamic modeler architecture
+
+## Models
+(for details about these concepts, see [this page](../../user-guide/solver/dynamic-modeler/05-model.md))
+
+```plantuml
+@startuml
+
+class Model {
++ string id
++ Expression objective
++ map<string, Parameter> parameters
++ map<string, Variable> variables
++ map<string, Constraint> constraints
++ map<string, Port> ports
+}
+Model "1" *-- "0:N" Parameter
+Model "1" *-- "0:N" Variable
+Model "1" *-- "0:N" Constraint
+Model "1" *-- "0:N" Port
+Model --> Expression
+
+class Parameter {
++ string id
++ ValueType type
++ bool timeDependent
++ bool scenarioDependent
+}
+Parameter "N" *-- "1" ValueType
+
+enum ValueType {
+FLOAT
+INTEGER
+BOOL
+}
+
+class Variable {
++ string id
++ ValueType type
++ Expression lowerBound
++ Expression upperBound
+}
+Variable "N" *-- "1" ValueType
+Variable --> Expression
+
+class Constraint {
++ string id
++ Expression expression
+}
+Constraint --> Expression
+
+class Port {
++ string id
++ PortType type
+}
+Port "N" *-- "1" PortType
+
+class PortType {
++ id
++ vector<PortField> fields
+}
+PortType "1" *-- "1:N" PortField
+
+class PortField {
++ string id
+}
+
+class Expression {
++ string textualRepresentation
++ Node nodeRepresentation
+}
+
+class ModelLibrary {
++ string id
++ map<string, Model> models
+}
+ModelLibrary "1" *-- "1:N" Model
+
+class ModelLibraryRepository {
++ map<string, ModelLibrary> modelLibraries
+}
+ModelLibraryRepository "1" *-- "0:N" ModelLibrary
+
+@enduml
+```
+
+## Components
+(for details about these concepts, see [this page](../../user-guide/solver/dynamic-modeler/05-model.md))
+
+```plantuml
+@startuml
+
+class Model {
++ string id
++ Expression objective
++ map<string, Parameter> parameters
++ map<string, Variable> variables
++ map<string, Constraint> constraints
++ map<string, Port> ports
+}
+
+class Component {
++ string id
++ Model model
++ string scenarioGroup
++ map<string, Expression> parameterValues
+}
+Component "0:N" *-- "1" Model
+Component --> Expression
+
+class Expression {
++ string textualRepresentation
++ Node nodeRepresentation
+}
+
+class PortConnection {
++ string component1Id
++ string port1Id
++ string component2Id
++ string port2Id
+}
+
+class System {
++ map<string, Component> components
++ vector<PortConnection> portConnections
+}
+System "1" *-- "1:N" Component
+System "1" *-- "0:N" PortConnection
+
+@enduml
+```

docs/stylesheets/extra.css

@@ -1,21 +1,29 @@
-[data-md-color-scheme="antares"] {
-    --md-primary-fg-color:        #002a5e;
+[data-md-color-scheme="default"] {
+    --md-primary-fg-color: #002a5e;
     --md-primary-fg-color--light: #00a3ca;
-    --md-primary-fg-color--dark:  #112446;
-    --md-typeset-a-color:  #00a3ca; /* text link color*/
+    --md-primary-fg-color--dark: #112446;
+    --md-typeset-a-color: #00a3ca; /* text link color*/
     --md-accent-fg-color: #ff9800; /* link color on hover*/
 }
+
 [data-md-color-scheme="slate"] {
     --md-hue: 213; /* [0, 360] */
-    --md-accent-fg-color: #ff9800;
+    --md-primary-fg-color: #002a5e;
+    --md-primary-fg-color--light: #00a3ca;
+    --md-primary-fg-color--dark: #112446;
+    --md-typeset-a-color: #00a3ca; /* text link color*/
+    --md-accent-fg-color: #ff9800; /* link color on hover*/
 }
+
 /* Use this class for images with transparent background, it will add padding and a white background in dark mode */
 .add-padding-and-white-bg {
     padding: 20px;
 }
+
 [data-md-color-scheme="slate"] .add-padding-and-white-bg {
     background-color: whitesmoke;
 }
+
 /* De-activate mkdocs' default h5 styling, which puts the h5 header in upper case */
 .md-typeset h5 {
     text-transform: none;

docs/user-guide/01-overview.md

@@ -34,7 +34,7 @@ the random factors that may affect the balance between load and generation. Econ
 as much a critical role as they do in the other kinds of studies since the stakes are mainly to know if and
 when supply security is likely to be jeopardized (detailed costs incurred in more ordinary conditions are of
 comparatively lower importance). In these studies, the default *Antares* option to use is the
-[`adequacy`](18-parameters.md#mode) simulation mode.
+[`adequacy`](solver/static-modeler/04-parameters.md#mode) simulation mode.
 
 ### Transmission project profitability
 [//]: # (TODO: explain what "fair and perfect market" means)
@@ -45,7 +45,7 @@ and/or improvement of the security of supply (reduction of the loss-of-load expe
 In these studies, economic parameters and the physical modeling of the dynamic constraints bearing on
 the generating units are of paramount importance. Though a thorough survey of many "Monte-Carlo years"
 is still required, the number of scenarios to simulate is not as large as in generation adequacy studies.
-In these studies, the default *Antares* option to use is the [`economy`](18-parameters.md#mode) simulation mode.
+In these studies, the default *Antares* option to use is the [`economy`](solver/static-modeler/04-parameters.md#mode) simulation mode.
 
 ## Performance considerations
 Typically, *Antares* has to solve a least-cost hydro-thermal power schedule and unit commitment problem, with an hourly 
@@ -54,7 +54,7 @@ The large number and the size of the individual problems to solve often make opt
 
 Depending on user-defined results accuracy requirements, various practical options[^2] allow to simplify either
 the formulation of the problems, or their resolution.
-[^2]: See [hydro-pricing-mode](solver/04-parameters.md#hydro-pricing-mode), [unit-commitment-mode](solver/04-parameters.md#unit-commitment-mode)
+[^2]: See [hydro-pricing-mode](solver/static-modeler/04-parameters.md#hydro-pricing-mode), [unit-commitment-mode](solver/static-modeler/04-parameters.md#unit-commitment-mode)
 
 [//]: # (TODO: list in [^2] the other parameters that have impact on performance)
 
@@ -73,4 +73,4 @@ operation problems (one for each week of each Monte-Carlo year), assumed to be i
 Note that, however, dependency issues such as the management of hydro stock (or any other kind of energy storage
 facility) may bring a significant coupling between the successive problems, which needs to be addressed properly[^3].
 
-[^3]: See how *Antares* addresses stock dependency between successive problems [here](solver/06-hydro-heuristics.md#seasonal-hydro-pre-allocation).
+[^3]: See how *Antares* addresses stock dependency between successive problems [here](solver/static-modeler/06-hydro-heuristics.md#seasonal-hydro-pre-allocation).

docs/user-guide/02-install.md

@@ -20,12 +20,12 @@ Installed alone, the Antares simulator does not require a lot of HDD space (less
 
 - The size of the power system model (number of Areas, Links, Thermal clusters, etc.)
 - The number of ready-made Time-Series and the number of Time-Series to be generated at runtime and stored afterward
-  (see [these parameters](18-parameters.md#time-series-parameters)).
+  (see [these parameters](ts-generator/04-parameters.md#time-series-parameters)).
 - The activation of output filters
-  (see [thematic-trimming](18-parameters.md#thematic-trimming) and [geographic-trimming](18-parameters.md#geographic-trimming) parameters).
+  (see [thematic-trimming](solver/static-modeler/04-parameters.md#thematic-trimming) and [geographic-trimming](solver/static-modeler/04-parameters.md#geographic-trimming) parameters).
 - The number of Monte-Carlo years involved in the simulation session, if the storage of detailed
-  [year-by-year results](18-parameters.md#year-by-year) is activated
-- Whether [MPS export](18-parameters.md#include-exportmps) is activated
+  [year-by-year results](solver/static-modeler/04-parameters.md#year-by-year) is activated
+- Whether [MPS export](solver/static-modeler/04-parameters.md#include-exportmps) is activated
 
 If you encounter space issues, consider tweaking the aforementioned parameters or reducing your study size.
 
@@ -35,8 +35,8 @@ The amount of RAM required for a simulation depends on:
 
 - The size of the power system model (number of Areas, Links, Thermal clusters, etc.)
 - The number of ready-made Time-Series and that of Time-Series to be generated at runtime
-- The simulation [mode](18-parameters.md#mode)
-- The [unit commitment resolution mode](18-parameters.md#unit-commitment-mode)
+- The simulation [mode](solver/static-modeler/04-parameters.md#mode)
+- The [unit commitment resolution mode](solver/static-modeler/04-parameters.md#unit-commitment-mode)
 - If the [multi-threading](solver/optional-features/multi-threading.md) option is used
 
 If you encounter memory issues, consider tweaking the aforementioned parameters or reducing your study size. 
@@ -50,4 +50,4 @@ If you encounter memory issues, consider tweaking the aforementioned parameters
 - **Ubuntu 20.04**: download & run executables, available on [GitHub](https://github.com/AntaresSimulatorTeam/Antares_Simulator/releases).
 - **OracleServer 8.9**: download & run installation packages, or executables, available on [GitHub](https://github.com/AntaresSimulatorTeam/Antares_Simulator/releases).
 - **OracleLinux 8**: download & run executables, available on [GitHub](https://github.com/AntaresSimulatorTeam/Antares_Simulator/releases).
-- Any other Windows/Linux/Unix OS: refer to our website to see how to [build *Antares* from sources](../developer-guide/3-Build.md)
+- Any other Windows/Linux/Unix OS: refer to our website to see how to [build *Antares* from sources](../developer-guide/3-Build.md)

docs/user-guide/03-getting_started.md

@@ -56,16 +56,16 @@ These steps most often involve:
 
 1. Initializing or updating the input data (time-series, grid topology, fleet description, etc.).  
    *In this step, the user is expected to provide all the input data they have, except the time-series that are 
-   supposed to be [automatically generated](18-parameters.md#generate) by *Antares* (see step (3)).*  
+   supposed to be [automatically generated](solver/static-modeler/04-parameters.md#generate) by *Antares* (see step (3)).*  
    *As stated above, it is highly recommended to use robust tools to produce input data, such as [Antares Web](https://antares-web.readthedocs.io) 
    or [Antares Extensions](#using-extensions).*   
 2. Defining the simulation contexts (definition of the "Monte-Carlo years" to simulate)
-3. *(Optional)* If some time-series are supposed to be [automatically generated](18-parameters.md#generate), 
+3. *(Optional)* If some time-series are supposed to be [automatically generated](solver/static-modeler/04-parameters.md#generate), 
    running a simulation to produce actual numeric scenarios, following the directives defined in (2).  
    *In this step, the [ts-generator](ts-generator/01-overview-tsgenerator.md) tool should be used.*
 4. Running the optimization, to solve all the optimization problems associated with each of the scenarios produced in (3).  
    *In this step, the main [solver](solver/01-overview-solver.md) tool should be used.*
-5. Exploiting the detailed [results](solver/03-outputs.md) yielded by (4).  
+5. Exploiting the detailed [results](solver/static-modeler/03-outputs.md) yielded by (4).  
    *In this step, we recommend using [Antares Web](https://antares-web.readthedocs.io) 
    or [Antares Extensions](#using-extensions).*
 

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

@@ -1,17 +1,13 @@
 [//]: # (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
+static-modeler/00-index.md
+dynamic-modeler/00-index.md
+02-command-line.md
 optional-features/00-index.md
-09-appendix.md
+03-appendix.md
 ```