diff --git a/.github/workflows/build-userguide.yml b/.github/workflows/build-userguide.yml index 599fdbd663..a12c034072 100644 --- a/.github/workflows/build-userguide.yml +++ b/.github/workflows/build-userguide.yml @@ -75,4 +75,3 @@ jobs: tag: ${{ github.event.inputs.release_tag }} run: | gh release upload "$tag" ${{ env.PDF_PATH }} - diff --git a/docs/README.md b/docs/README.md index 49c350d844..c2774db3c2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -60,19 +60,19 @@ 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. @@ -80,9 +80,9 @@ When modifying the user guide content, you can easily preview the resulting PDF 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) diff --git a/docs/developer-guide/6-Contributing.md b/docs/developer-guide/6-Contributing.md index 977a2860b8..cae411dbdb 100644 --- a/docs/developer-guide/6-Contributing.md +++ b/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 diff --git a/docs/developer-guide/Architecture/Dynamic-modeler-architecture.md b/docs/developer-guide/Architecture/Dynamic-modeler-architecture.md new file mode 100644 index 0000000000..17ce09800e --- /dev/null +++ b/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 parameters ++ map variables ++ map constraints ++ map 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 fields +} +PortType "1" *-- "1:N" PortField + +class PortField { ++ string id +} + +class Expression { ++ string textualRepresentation ++ Node nodeRepresentation +} + +class ModelLibrary { ++ string id ++ map models +} +ModelLibrary "1" *-- "1:N" Model + +class ModelLibraryRepository { ++ map 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 parameters ++ map variables ++ map constraints ++ map ports +} + +class Component { ++ string id ++ Model model ++ string scenarioGroup ++ map 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 components ++ vector portConnections +} +System "1" *-- "1:N" Component +System "1" *-- "0:N" PortConnection + +@enduml +``` \ No newline at end of file diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index a4abde6c67..1b6449c19a 100644 --- a/docs/stylesheets/extra.css +++ b/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; diff --git a/docs/user-guide/01-overview.md b/docs/user-guide/01-overview.md index ddc3b03c60..6482a1df56 100644 --- a/docs/user-guide/01-overview.md +++ b/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). \ No newline at end of file diff --git a/docs/user-guide/02-install.md b/docs/user-guide/02-install.md index ffa1c75c37..c72c3e8da0 100644 --- a/docs/user-guide/02-install.md +++ b/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) \ No newline at end of file +- Any other Windows/Linux/Unix OS: refer to our website to see how to [build *Antares* from sources](../developer-guide/3-Build.md) diff --git a/docs/user-guide/03-getting_started.md b/docs/user-guide/03-getting_started.md index ba4ca923a8..6930298a40 100644 --- a/docs/user-guide/03-getting_started.md +++ b/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).* diff --git a/docs/user-guide/solver/00-index.md b/docs/user-guide/solver/00-index.md index 4ef21bd614..ad9273f951 100644 --- a/docs/user-guide/solver/00-index.md +++ b/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 ``` diff --git a/docs/user-guide/solver/01-overview-solver.md b/docs/user-guide/solver/01-overview-solver.md index d620960a25..6457b65bcc 100644 --- a/docs/user-guide/solver/01-overview-solver.md +++ b/docs/user-guide/solver/01-overview-solver.md @@ -2,63 +2,20 @@ _**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)**
- 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):**
- 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". -
- 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. -
- 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_ | \ No newline at end of file +The *Solver* is *Antares Simulator*'s main feature. +It covers modelling & solving the adequacy optimization problem. + +As of 2024, the modelling feature is being overhauled to allow more flexibility in the definition of physical models. + +- The existing modeler will still be maintained for a few years, you can find its + documentation under the ["static modeler" section](static-modeler/01-overview-static-modeler). +- The new modeler will be gradually enriched to cover all existing features, you can find its + documentation under the ["dynamic modeler" section](dynamic-modeler/01-overview-dynamic-modeler). +- It will be possible, for a few transitional years, to define "hybrid" studies, + mixing [static models](static-modeler/05-model.md) with [dynamic models](dynamic-modeler/05-model.md). This is + documented [here](dynamic-modeler/08-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). diff --git a/docs/user-guide/solver/08-command-line.md b/docs/user-guide/solver/02-command-line.md similarity index 73% rename from docs/user-guide/solver/08-command-line.md rename to docs/user-guide/solver/02-command-line.md index 8ef88dfd23..346e9cfdfc 100644 --- a/docs/user-guide/solver/08-command-line.md +++ b/docs/user-guide/solver/02-command-line.md @@ -9,36 +9,36 @@ hide: ## Simulation -| command | usage | -|:-----------------------|:-----------------------------------------------------------------------------------------------------------------------------------| -| -i, --input | Study folder | -| --expansion | Force the simulation in [expansion](04-parameters.md#mode) mode | -| --economy | Force the simulation in [economy](04-parameters.md#mode) mode | -| --adequacy | Force the simulation in [adequacy](04-parameters.md#mode) mode | -| --parallel | Enable [parallel](optional-features/multi-threading.md) computation of MC years | -| --force-parallel=VALUE | Override the max number of years computed [simultaneously](optional-features/multi-threading.md) | -| --use-ortools | Use the [OR-Tools](https://developers.google.com/optimization) modelling library (under the hood) | -| --ortools-solver=VALUE | The solver to use (only available if use-ortools is activated). Possible values are: `sirius` (default), `coin`, `xpress`, `scip` | +| command | usage | +|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------| +| -i, --input | Study folder | +| --expansion | Force the simulation in [expansion](static-modeler/04-parameters.md#mode) mode | +| --economy | Force the simulation in [economy](static-modeler/04-parameters.md#mode) mode | +| --adequacy | Force the simulation in [adequacy](static-modeler/04-parameters.md#mode) mode | +| --parallel | Enable [parallel](optional-features/multi-threading.md) computation of MC years | +| --force-parallel=VALUE | Override the max number of years computed [simultaneously](optional-features/multi-threading.md) | +| --use-ortools | Use the [OR-Tools](https://developers.google.com/optimization) modelling library (under the hood) | +| --ortools-solver=VALUE | The solver to use (only available if use-ortools is activated). Possible values are: `sirius` (default), `coin`, `xpress`, `scip` | ## Parameters -| command | usage | -|:-------------------------|:--------------------------------------------------------------------------------------------------| -| -n, --name=VALUE | Set the name of the new simulation | -| -g, --generators-only | Run the time-series generators only | -| -c, --comment-file=VALUE | Specify the file to copy as comments of the simulation | -| -f, --force | Ignore all warnings at loading | -| --no-output | Do not write the results in the output folder | -| -y, --year=VALUE | Override the [number of MC years](04-parameters.md#nbyears) | -| --year-by-year | Force the [writing the result output for each year](04-parameters.md#year-by-year) (economy only) | -| --derated | Force the [derated](04-parameters.md#derated) mode | -| -z, --zip-output | Write the results into a single zip archive | +| command | usage | +|:-------------------------|:----------------------------------------------------------------------------------------------------------------| +| -n, --name=VALUE | Set the name of the new simulation | +| -g, --generators-only | Run the time-series generators only | +| -c, --comment-file=VALUE | Specify the file to copy as comments of the simulation | +| -f, --force | Ignore all warnings at loading | +| --no-output | Do not write the results in the output folder | +| -y, --year=VALUE | Override the [number of MC years](static-modeler/04-parameters.md#nbyears) | +| --year-by-year | Force the [writing the result output for each year](static-modeler/04-parameters.md#year-by-year) (economy only) | +| --derated | Force the [derated](static-modeler/04-parameters.md#derated) mode | +| -z, --zip-output | Write the results into a single zip archive | ## Optimization | command | usage | |:-------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| --optimization-range | Force the [simplex optimization range](04-parameters.md#simplex-range) ('day' or 'week') | +| --optimization-range | Force the [simplex optimization range](static-modeler/04-parameters.md#simplex-range) ('day' or 'week') | | --no-constraints | Ignore all binding constraints | | --no-ts-import | Do not import timeseries into the input folder (this option may be useful for running old studies without upgrade) | | -m, --mps-export | Export anonymous MPS, weekly or daily optimal UC+dispatch linear (MPS will be named if the problem is infeasible) | diff --git a/docs/user-guide/solver/03-appendix.md b/docs/user-guide/solver/03-appendix.md new file mode 100644 index 0000000000..90dc6ca020 --- /dev/null +++ b/docs/user-guide/solver/03-appendix.md @@ -0,0 +1,315 @@ +# Appendix + +[//]: # (TODO: the contents of this page may be dispatched in opther pages) + +## Details on the "include-exportmps" parameter + +[//]: # (TODO: specify where the MPS files are written) + +This [parameter](static-modeler/04-parameters.md#include-exportmps) does not influence the way calculations are carried +out, +nor does it change their results. +The effect of this preference is that, if the parameter is activated, *Antares* will produce and store in the +simulation output folder two files for every linear problem solved in the whole simulation. + +- The first file ("problem" file) contains a standardized description of the mathematical problem solved by *Antares'* + built-in linear solver. The format standard used in this file is known as "MPS". +- The second file ("criterion" file) contains the value of the optimal (minimum) value found for the objective function + of the optimization problem (overall system cost throughout a day or a week). + +All commercial as well as open-source linear solvers are able to process MPS files. As a consequence, tests aiming at +comparing *Antares* solver with other commercial solutions can be easily carried out: all that has to be done is to +submit the MPS problem to the solver at hand and measure its performances (calculation time, criterion value) +with those of *Antares*. + +Note that this kind of comparison brings no information regarding the quality of the physical modelling on which the +simulation is based. It is useful, however, to gather evidence on mathematical grounds. + +File names are structured as follows: + +- When the optimization parameter [simplex-range](static-modeler/04-parameters.md#simplex-range) is set on `week`: + Problem-MC year-week number-date-time.mps + Criterion-MC year-week number-date-time.txt +- When the optimization parameter [simplex-range](static-modeler/04-parameters.md#simplex-range) is set on `day`: + Problem-MC year-week number-date-time-day number.mps + Criterion-MC year-week number-date-time-day number.txt + +[//]: # (TODO: add link to "two successive optimization problems" doc) +Besides, each economic problem generally needs to be solved through two successive optimization problems. +Files related to these two problems will bear almost the same name, the only difference being the "time" suffix. +The files related to the second optimization (final *Antares* results) are those that bear the latest tag. + +Finally, in some rare cases where the problems to solve are small and fast, the files attached to the two optimization +rounds may begin to be printed within the same second. In these cases, an additional suffix is added before the mps or +txt extension. + +> _**Note:**_ The extra runtime and disk space resulting from the activation of the "mps" option may be quite +> significant. +> This option should therefore be used only when a comparison of results with those of other solvers is actually +> intended. + +## Details on the "include-unfeasible-problem-behavior" parameter + +This [parameter](static-modeler/04-parameters.md#include-unfeasible-problem-behavior) can take one of the four values: +`ERROR_DRY`, `ERROR_MPS`, `WARNING_DRY`, `WARNING_MPS` + +If `ERROR_DRY` or `ERROR_MPS` is selected, the simulation will stop right after encountering the first mathematically +unfeasible optimization (daily or weekly) problem. No output will be produced beyond this point. +Should the dataset contain several unfeasible problems (i.e. regarding different weeks of different MC years), +it is possible that successive runs of the same simulation stop at different points (if parallel computation is used, +the triggering problem may differ from one run to the other). + +If `WARNING_DRY` or `WARNING_MPS` is selected, the simulation will skip all mathematically unfeasible optimization +(daily or weekly) problems encountered, fill out all results regarding these problems with zeroes and then resume the +simulation. The hydro reservoir levels used for resuming the simulation are those reached at the end of the last +successful week. + +With `..._DRY` options, no specific data is printed regarding the faulty problem(s). +With `..._MPS` options, the full expression of the faulty problem(s) is printed in the standard "MPS" format, +thus allowing further analysis of the infeasibility issue. + +## Details on the "initial-reservoir-levels" parameter + +**(DEPRECATED since 9.2)** + +### version 9.2: The reservoir level is now always determined with cold start behavior. + +This parameter can take the two values "cold start" or "hot start". [default: cold start]. Simulations results may in +some circumstances be heavily impacted by this setting, hence proper attention should be paid to its meaning before +considering changing the default value. + +**General:** + +This parameter is meant to define the initial reservoir levels that should be used, in each system area, when processing +data related to the hydropower storage resources to consider in each specific Monte-Carlo year. + +As a consequence, Areas which fall in either of the two following categories are not impacted by the value of the +parameter: + +- No hydro-storage capability installed +- Hydro-storage capability installed, but the "reservoir management" option is set to "False" + +Areas that have some hydro-storage capability installed and for which explicit reservoir management is required are +concerned by the parameter. The developments that follow concern only this category of Areas. + +**Cold Start:** + +On starting the simulation of a new Monte-Carlo year, the reservoir level to consider in each Area on the first day of +the initialization month is randomly drawn between the extreme levels defined for the Area on that day. + +More precisely: + +- The value is drawn according to the probability distribution function of a "Beta" random variable, whose four internal + parameters are set so as to adopt the following behavior: + Lower bound: Minimum reservoir level. + Upper bound: Maximum reservoir level + Expectation: Average reservoir level + Standard Deviation: (1/3) (Upper bound-Lower bound) + +- The random number generator used for that purpose works with a dedicated seed that ensures that results can be + reproduced + [^17] from one run to another, regardless of the simulation runtime mode (sequential or parallel) + and regardless of the number of Monte-Carlo years to be simulated [^18]. + +**Hot Start:** + +On starting the simulation of a new Monte-Carlo year, the reservoir level to consider in each Area on the first day of +the initialization month is set to the value reached at the end of the previous simulated year, if three conditions are +met: + +- The simulation calendar is defined throughout the whole year, and the simulation starts on the day chosen for + initializing the reservoir levels of all Areas. + +- The Monte-Carlo year considered is not the first to simulate, or does not belong to the first batch of years to be + simulated in parallel. In sequential runtime mode, that means that year #N may start with the level reached at the end + of year #(N-1). In parallel runtime mode, if the simulation is carried out with batches of B years over as many CPU + cores, years of the k-th batch + [^19] may start with the ending levels of the years processed in the (k-1)-th batch. + +- The parallelization context (see [Multi-threading](optional-features/multi-threading.md)) must be set to ensure that + the M Monte-Carlo years to simulate will be processed in a round number of K consecutive batches of B years in + parallel (i.e. M = K\*B and all time-series refresh intervals are exact multiple of B). + +The first year of the simulation, and more generally years belonging to the first simulation batch in parallel mode, are +initialized as they would be in the cold start option. + +**Note that:** + +- _Depending on the hydro management options used, the amount of hydro-storage energy generated throughout the year may + either match closely the overall amount of natural inflows of the same year, or differ to a lesser or greater extent. + In the case of a close match, the ending reservoir level will be similar to the starting level. If the energy + generated exceeds the inflows (either natural or pumped), the ending level will be lower than the starting level (and + conversely, be higher if generation does not reach the inflow credit). Using the "hot start" option allows to take + this phenomenon into account in a very realistic fashion, since the consequences of hydro decisions taken at any time + have a decisive influence on the system's long term future._ + +- _When using the reservoir level "hot start" option, comparisons between different simulations make sense only if they + rely on the exact same options, i.e. either sequential mode or parallel mode over the same number of CPU cores._ + +- _More generally, it has to be pointed out that the "hydro-storage" model implemented in Antares can be used to model " + storable" resources quite different from actual hydro reserves: batteries, gas subterraneous stocks, etc._ + +## Details on the "hydro-heuristic-policy" parameter + +[//]: # (TODO: update this paragraph) +_**This section is under construction**_ + +This parameter can take the two values "Accommodate rule curves" or "Maximize +generation". [default: Accommodate rule curves]. + +**General:** + +This parameter is meant to define how the reservoir level should be managed throughout the year, either with emphasis +put on the respect of rule curves or on the maximization of the use of natural inflows. + +**Accommodate rule curves:** + +Upper and lower rule curves are accommodated in both monthly and daily heuristic stages (described page 58). In the +second stage, violations of the lower rule curve are avoided as much as possible (penalty cost on $\Psi$. higher than +penalty cost on Y). This policy may result in a restriction of the overall yearly energy generated from the natural +inflows. + +**Maximize generation:** + +Upper and lower rule curves are accommodated in both monthly and daily heuristic stages (described page 58). In the +second stage, incomplete use of natural inflows is avoided as much as possible (penalty cost on Y higher than penalty +cost on $\Psi$). This policy may result in violations of the lower rule curve. + +## Details on the "hydro-pricing-mode" parameter + +[//]: # (TODO: update this paragraph) +_**This section is under construction**_ + +This parameter can take the two values "fast" or "accurate". [default: fast]. + +Simulations carried out in "accurate" mode yield results that are theoretically optimal as far as the techno-economic +modelling of hydro (or equivalent) energy reserves is concerned. It may, however, require noticeably longer computation +time than the simpler "fast" mode. + +Simulations carried out in "fast" mode are less demanding in computer resources. From a qualitative standpoint, they are +expected to lead to somewhat more intensive (less cautious) use of stored energy. + +**General:** + +This parameter is meant to define how the reservoir level difference between the beginning and the end of an +optimization week should be reflected in the hydro economic signal (water value) used in the computation of optimal +hourly generated /pumped power during this week. + +**Fast:** + +The water value is taken to remain about the same throughout the week, and a constant value equal to that found at the +date and for the level at which the week_ **begins** _is used in the course of the optimization. A value interpolated +from the reference table for the exact level reached at each time step within the week is used ex-post in the assessment +of the variable "H.COST" (positive for generation, negative for pumping) defined +in [Output Files](static-modeler/03-outputs.md). This +option should be reserved to simulations in which computation resources are an issue or to simulations in which +level-dependent water value variations throughout a week are known to be small. + +**Accurate:** + +The water value is considered as variable throughout the week. As a consequence, a different cost is used for each " +layer" of the stock from/to which energy can be withdrawn/injected, in an internal hydro merit-order involving the 100 +tabulated water-values found at the date at which the week **ends**. A value interpolated from the reference table for +the exact level reached at each time step within the week is used ex-post in the assessment of the variable "H.COST" ( +positive for generation, negative for pumping) defined in [Output Files](static-modeler/03-outputs.md). This option +should be used if +computation resources are not an issue and if level-dependent water value variations throughout a week must be accounted +for. + +## Details on the "unit-commitment-mode" parameter + +[//]: # (TODO: update this paragraph) +_**This section is under construction**_ + +This parameter can take the two values "fast" or "accurate". [default: fast]. + +Simulations carried out in "accurate" mode yield results that are expected to be close to the theoretical optimum as far +as the techno-economic modelling of thermal units is concerned. They may, however, require much longer computation time +than the simpler "fast" mode. + +Simulations carried out in "fast" mode are less demanding in computer resources. From a qualitative standpoint, they are +expected to lead to a more costly use of thermal energy. This potential bias is partly due to the fact that in this +mode, start-up costs do not participate as such to the optimization process but are simply added ex post. + +**General:** + +In its native form [^20], the weekly optimization problem belongs to the MILP (Mixed Integer Linear Program) class. The +Integer variables reflect, for each time step, the operational status (running or not) of each thermal unit. Besides, +the amount of power generated from each unit can be described as a so-called semi-continuous variable (its value is +either 0 or some point within the interval [Pmin , Pmax]). Finally, the periods during which each unit is either +generating or not cannot be shorter than minimal (on- and off-) thresholds depending on its technology. + +The Unit Commitment mode parameter defines two different ways to address the issue of the mathematical resolution of +this problem. In both cases, two successive so-called "relaxed" LP global optimizations are carried out. In-between +those two LPs, a number of local IP (unit commitment of each thermal cluster) are carried out. + +Besides, dynamic thermal constraints (minimum on- and off- time durations) are formulated on time-indices rolling over +the week; this simplification brings the ability to run a simulation over a short period of time, such as one single +week extracted from a whole year, while avoiding the downside (data management complexity, increased runtime) of a +standard implementation based on longer simulations tiled over each other (illustration below). + +![Standard_Implementation](img/Standard_Implementation.png) + +![Antares_Implementation](img/Antares_Implementation.png) + +**Fast:** + +In the first optimization stage, integrity constraints are removed from the problem and replaced by simpler continuous +constraints. + +For each thermal cluster, the intermediate IP looks simply for an efficient unit-commitment compatible with the +operational status obtained in the first stage, with the additional condition (more stringent than what is actually +required) that on- and off- periods should be exact multiple of the higher of the two thresholds specified in the +dataset. + +In the second optimization stage, the unit commitment set by the intermediate IPs is considered as a context to use in a +new comprehensive optimal hydro-thermal schedule assessment. The amount of day-ahead (spinning) reserve, if any, is +added to the demand considered in the first stage and subtracted in the second stage. Start-up costs as well as No-Load +Heat costs are assessed in accordance with the unit-commitment determined in the first stage and are added ex post. + +**Accurate:** + +In the first optimization stage, integrity constraints are properly relaxed. Integer variables describing the start-up +process of each unit are given relevant start-up costs, and variables attached to running units are given No-Load Heat +costs (if any), regardless of their generation output level. Fuel costs / Market bids are attached to variables +representing the generation output levels. + +For each thermal cluster, the intermediate IP looks for a unit-commitment compatible with the integrity constraints in +the immediate neighborhood of the relaxed solution obtained in the first stage. In this process, the dynamic +thresholds (min on-time, min off-time) are set to their exact values, without any additional constraint. + +In the second optimization stage, the unit commitment set by the intermediate IP is considered as a context to use in a +new comprehensive optimal hydro-thermal schedule assessment. The amount of day-ahead (spinning) reserve, if any, is +added to the demand considered in the first stage and subtracted in the second stage. + +## Details on the "renewable-generation-modelling" parameter + +[//]: # (TODO: update this paragraph) +_**This section is under construction**_ + +This parameter can take the two values “aggregated” or “cluster”. For a new study, it will default to cluster. For a +legacy (Antares version <8.1.0) study it will default to aggregated. + +If the parameter is set to “aggregated”, the user will have access to the Wind & Solar windows, but not the Renewable +window. When the parameter is set to “cluster”, the Renewable window will be available, but not the Wind nor the Solar +windows. The data stored in the windows that are not available will always be conserved. However, only Renewable data ( +and not the wind and solar data) will be considered for the calculations when the parameter is set to “cluster”. And +only the wind and solar data (and not the renewable data) will be considered for the calculations when the parameter is +set to “aggregated”. + +The Renewable window can be filled out with the different renewable clusters inside each node. Each renewable cluster +needs to have a group specified or will default to the «Other RES 1» group. Production Timeseries can be filled out much +like the Thermal production ones. Note that unlike thermal clusters, negative production values are allowed. The +Renewable window is described in more details in the “4. Active Windows” section. In the Simulation window, only +“Ready-made” timeseries can be selected for renewables for now. This should be modified in a future release. The MC +scenario builder for Renewables works the same way as for Thermal Clusters. + +[^17]: As long as the System's list of Areas does not change + +[^18]:E.g. : if three playlists A,B,C are defined over 1000 years (A: years 1 to 1000, B: years 1 to 100, C: Years +13,42,57,112), initial reservoir levels in each Area are identical in the playlists' intersection (years 13,42,57) + +[^19]: If the playlist is full, these years have numbers # (k-1)B+1 ,…., #kB + +[^20]: Described in the note "Optimization Problems Formulation" + diff --git a/docs/user-guide/solver/09-appendix.md b/docs/user-guide/solver/09-appendix.md deleted file mode 100644 index 1f8e24673d..0000000000 --- a/docs/user-guide/solver/09-appendix.md +++ /dev/null @@ -1,217 +0,0 @@ -# Appendix - -[//]: # (TODO: the contents of this page may be dispatched in opther pages) - -## Details on the "include-exportmps" parameter -[//]: # (TODO: specify where the MPS files are written) - -This [parameter](04-parameters.md#include-exportmps) does not influence the way calculations are carried out, -nor does it change their results. -The effect of this preference is that, if the parameter is activated, *Antares* will produce and store in the -simulation output folder two files for every linear problem solved in the whole simulation. - -- The first file ("problem" file) contains a standardized description of the mathematical problem solved by *Antares'* - built-in linear solver. The format standard used in this file is known as "MPS". -- The second file ("criterion" file) contains the value of the optimal (minimum) value found for the objective function - of the optimization problem (overall system cost throughout a day or a week). - -All commercial as well as open-source linear solvers are able to process MPS files. As a consequence, tests aiming at -comparing *Antares* solver with other commercial solutions can be easily carried out: all that has to be done is to -submit the MPS problem to the solver at hand and measure its performances (calculation time, criterion value) -with those of *Antares*. - -Note that this kind of comparison brings no information regarding the quality of the physical modelling on which the -simulation is based. It is useful, however, to gather evidence on mathematical grounds. - -File names are structured as follows: -- When the optimization parameter [simplex-range](04-parameters.md#simplex-range) is set on `week`: - Problem-MC year-week number-date-time.mps - Criterion-MC year-week number-date-time.txt -- When the optimization parameter [simplex-range](04-parameters.md#simplex-range) is set on `day`: - Problem-MC year-week number-date-time-day number.mps - Criterion-MC year-week number-date-time-day number.txt - - -[//]: # (TODO: add link to "two successive optimization problems" doc) -Besides, each economic problem generally needs to be solved through two successive optimization problems. -Files related to these two problems will bear almost the same name, the only difference being the "time" suffix. -The files related to the second optimization (final *Antares* results) are those that bear the latest tag. - -Finally, in some rare cases where the problems to solve are small and fast, the files attached to the two optimization -rounds may begin to be printed within the same second. In these cases, an additional suffix is added before the mps or -txt extension. - -> _**Note:**_ The extra runtime and disk space resulting from the activation of the "mps" option may be quite significant. -> This option should therefore be used only when a comparison of results with those of other solvers is actually intended. - -## Details on the "include-unfeasible-problem-behavior" parameter - -This [parameter](04-parameters.md#include-unfeasible-problem-behavior) can take one of the four values: -`ERROR_DRY`, `ERROR_MPS`, `WARNING_DRY`, `WARNING_MPS` - -If `ERROR_DRY` or `ERROR_MPS` is selected, the simulation will stop right after encountering the first mathematically -unfeasible optimization (daily or weekly) problem. No output will be produced beyond this point. -Should the dataset contain several unfeasible problems (i.e. regarding different weeks of different MC years), -it is possible that successive runs of the same simulation stop at different points (if parallel computation is used, -the triggering problem may differ from one run to the other). - -If `WARNING_DRY` or `WARNING_MPS` is selected, the simulation will skip all mathematically unfeasible optimization -(daily or weekly) problems encountered, fill out all results regarding these problems with zeroes and then resume the -simulation. The hydro reservoir levels used for resuming the simulation are those reached at the end of the last successful week. - -With `..._DRY` options, no specific data is printed regarding the faulty problem(s). -With `..._MPS` options, the full expression of the faulty problem(s) is printed in the standard "MPS" format, -thus allowing further analysis of the infeasibility issue. - - -## Details on the "initial-reservoir-levels" parameter (DEPRECATED since 9.2) - -### version 9.2: The reservoir level is now always determined with cold start behavior. - -This parameter can take the two values "cold start" or "hot start". [default: cold start]. Simulations results may in some circumstances be heavily impacted by this setting, hence proper attention should be paid to its meaning before considering changing the default value. - -**General:** - -This parameter is meant to define the initial reservoir levels that should be used, in each system area, when processing -data related to the hydropower storage resources to consider in each specific Monte-Carlo year. - -As a consequence, Areas which fall in either of the two following categories are not impacted by the value of the parameter: -- No hydro-storage capability installed -- Hydro-storage capability installed, but the "reservoir management" option is set to "False" - -Areas that have some hydro-storage capability installed and for which explicit reservoir management is required are concerned by the parameter. The developments that follow concern only this category of Areas. - -**Cold Start:** - -On starting the simulation of a new Monte-Carlo year, the reservoir level to consider in each Area on the first day of -the initialization month is randomly drawn between the extreme levels defined for the Area on that day. - -More precisely: - -- The value is drawn according to the probability distribution function of a "Beta" random variable, whose four internal parameters are set so as to adopt the following behavior: - Lower bound: Minimum reservoir level. - Upper bound: Maximum reservoir level - Expectation: Average reservoir level - Standard Deviation: (1/3) (Upper bound-Lower bound) - -- The random number generator used for that purpose works with a dedicated seed that ensures that results can be reproduced - [^17] from one run to another, regardless of the simulation runtime mode (sequential or parallel) - and regardless of the number of Monte-Carlo years to be simulated [^18]. - -**Hot Start:** - -On starting the simulation of a new Monte-Carlo year, the reservoir level to consider in each Area on the first day of the initialization month is set to the value reached at the end of the previous simulated year, if three conditions are met: - -- The simulation calendar is defined throughout the whole year, and the simulation starts on the day chosen for initializing the reservoir levels of all Areas. - -- The Monte-Carlo year considered is not the first to simulate, or does not belong to the first batch of years to be simulated in parallel. In sequential runtime mode, that means that year #N may start with the level reached at the end of year #(N-1). In parallel runtime mode, if the simulation is carried out with batches of B years over as many CPU cores, years of the k-th batch - [^19] may start with the ending levels of the years processed in the (k-1)-th batch. - -- The parallelization context (see [Multi-threading](optional-features/multi-threading.md)) must be set to ensure that the M Monte-Carlo years to simulate will be processed in a round number of K consecutive batches of B years in parallel (i.e. M = K\*B and all time-series refresh intervals are exact multiple of B). - -The first year of the simulation, and more generally years belonging to the first simulation batch in parallel mode, are initialized as they would be in the cold start option. - -**Note that:** - -- _Depending on the hydro management options used, the amount of hydro-storage energy generated throughout the year may either match closely the overall amount of natural inflows of the same year, or differ to a lesser or greater extent. In the case of a close match, the ending reservoir level will be similar to the starting level. If the energy generated exceeds the inflows (either natural or pumped), the ending level will be lower than the starting level (and conversely, be higher if generation does not reach the inflow credit). Using the "hot start" option allows to take this phenomenon into account in a very realistic fashion, since the consequences of hydro decisions taken at any time have a decisive influence on the system's long term future._ - -- _When using the reservoir level "hot start" option, comparisons between different simulations make sense only if they rely on the exact same options, i.e. either sequential mode or parallel mode over the same number of CPU cores._ - -- _More generally, it has to be pointed out that the "hydro-storage" model implemented in Antares can be used to model "storable" resources quite different from actual hydro reserves: batteries, gas subterraneous stocks, etc._ - -## Details on the "hydro-heuristic-policy" parameter -[//]: # (TODO: update this paragraph) -_**This section is under construction**_ - -This parameter can take the two values "Accommodate rule curves" or "Maximize generation". [default: Accommodate rule curves]. - -**General:** - -This parameter is meant to define how the reservoir level should be managed throughout the year, either with emphasis put on the respect of rule curves or on the maximization of the use of natural inflows. - -**Accommodate rule curves:** - -Upper and lower rule curves are accommodated in both monthly and daily heuristic stages (described page 58). In the second stage, violations of the lower rule curve are avoided as much as possible (penalty cost on $\Psi$. higher than penalty cost on Y). This policy may result in a restriction of the overall yearly energy generated from the natural inflows. - -**Maximize generation:** - -Upper and lower rule curves are accommodated in both monthly and daily heuristic stages (described page 58). In the second stage, incomplete use of natural inflows is avoided as much as possible (penalty cost on Y higher than penalty cost on $\Psi$). This policy may result in violations of the lower rule curve. - -## Details on the "hydro-pricing-mode" parameter -[//]: # (TODO: update this paragraph) -_**This section is under construction**_ - -This parameter can take the two values "fast" or "accurate". [default: fast]. - -Simulations carried out in "accurate" mode yield results that are theoretically optimal as far as the techno-economic modelling of hydro (or equivalent) energy reserves is concerned. It may, however, require noticeably longer computation time than the simpler "fast" mode. - -Simulations carried out in "fast" mode are less demanding in computer resources. From a qualitative standpoint, they are expected to lead to somewhat more intensive (less cautious) use of stored energy. - -**General:** - -This parameter is meant to define how the reservoir level difference between the beginning and the end of an optimization week should be reflected in the hydro economic signal (water value) used in the computation of optimal hourly generated /pumped power during this week. - -**Fast:** - -The water value is taken to remain about the same throughout the week, and a constant value equal to that found at the date and for the level at which the week_ **begins** _is used in the course of the optimization. A value interpolated from the reference table for the exact level reached at each time step within the week is used ex-post in the assessment of the variable "H.COST" (positive for generation, negative for pumping) defined in [Output Files](03-outputs.md). This option should be reserved to simulations in which computation resources are an issue or to simulations in which level-dependent water value variations throughout a week are known to be small. - -**Accurate:** - -The water value is considered as variable throughout the week. As a consequence, a different cost is used for each "layer" of the stock from/to which energy can be withdrawn/injected, in an internal hydro merit-order involving the 100 tabulated water-values found at the date at which the week **ends**. A value interpolated from the reference table for the exact level reached at each time step within the week is used ex-post in the assessment of the variable "H.COST" (positive for generation, negative for pumping) defined in [Output Files](03-outputs.md). This option should be used if computation resources are not an issue and if level-dependent water value variations throughout a week must be accounted for. - -## Details on the "unit-commitment-mode" parameter -[//]: # (TODO: update this paragraph) -_**This section is under construction**_ - -This parameter can take the two values "fast" or "accurate". [default: fast]. - -Simulations carried out in "accurate" mode yield results that are expected to be close to the theoretical optimum as far as the techno-economic modelling of thermal units is concerned. They may, however, require much longer computation time than the simpler "fast" mode. - -Simulations carried out in "fast" mode are less demanding in computer resources. From a qualitative standpoint, they are expected to lead to a more costly use of thermal energy. This potential bias is partly due to the fact that in this mode, start-up costs do not participate as such to the optimization process but are simply added ex post. - -**General:** - -In its native form [^20], the weekly optimization problem belongs to the MILP (Mixed Integer Linear Program) class. The Integer variables reflect, for each time step, the operational status (running or not) of each thermal unit. Besides, the amount of power generated from each unit can be described as a so-called semi-continuous variable (its value is either 0 or some point within the interval [Pmin , Pmax]). Finally, the periods during which each unit is either generating or not cannot be shorter than minimal (on- and off-) thresholds depending on its technology. - -The Unit Commitment mode parameter defines two different ways to address the issue of the mathematical resolution of this problem. In both cases, two successive so-called "relaxed" LP global optimizations are carried out. In-between those two LPs, a number of local IP (unit commitment of each thermal cluster) are carried out. - -Besides, dynamic thermal constraints (minimum on- and off- time durations) are formulated on time-indices rolling over the week; this simplification brings the ability to run a simulation over a short period of time, such as one single week extracted from a whole year, while avoiding the downside (data management complexity, increased runtime) of a standard implementation based on longer simulations tiled over each other (illustration below). - -![Standard_Implementation](img/Standard_Implementation.png) - -![Antares_Implementation](img/Antares_Implementation.png) - -**Fast:** - -In the first optimization stage, integrity constraints are removed from the problem and replaced by simpler continuous constraints. - -For each thermal cluster, the intermediate IP looks simply for an efficient unit-commitment compatible with the operational status obtained in the first stage, with the additional condition (more stringent than what is actually required) that on- and off- periods should be exact multiple of the higher of the two thresholds specified in the dataset. - -In the second optimization stage, the unit commitment set by the intermediate IPs is considered as a context to use in a new comprehensive optimal hydro-thermal schedule assessment. The amount of day-ahead (spinning) reserve, if any, is added to the demand considered in the first stage and subtracted in the second stage. Start-up costs as well as No-Load Heat costs are assessed in accordance with the unit-commitment determined in the first stage and are added ex post. - -**Accurate:** - -In the first optimization stage, integrity constraints are properly relaxed. Integer variables describing the start-up process of each unit are given relevant start-up costs, and variables attached to running units are given No-Load Heat costs (if any), regardless of their generation output level. Fuel costs / Market bids are attached to variables representing the generation output levels. - -For each thermal cluster, the intermediate IP looks for a unit-commitment compatible with the integrity constraints in the immediate neighborhood of the relaxed solution obtained in the first stage. In this process, the dynamic thresholds (min on-time, min off-time) are set to their exact values, without any additional constraint. - -In the second optimization stage, the unit commitment set by the intermediate IP is considered as a context to use in a new comprehensive optimal hydro-thermal schedule assessment. The amount of day-ahead (spinning) reserve, if any, is added to the demand considered in the first stage and subtracted in the second stage. - -## Details on the "renewable-generation-modelling" parameter -[//]: # (TODO: update this paragraph) -_**This section is under construction**_ - -This parameter can take the two values “aggregated” or “cluster”. For a new study, it will default to cluster. For a legacy (Antares version <8.1.0) study it will default to aggregated. - -If the parameter is set to “aggregated”, the user will have access to the Wind & Solar windows, but not the Renewable window. When the parameter is set to “cluster”, the Renewable window will be available, but not the Wind nor the Solar windows. The data stored in the windows that are not available will always be conserved. However, only Renewable data (and not the wind and solar data) will be considered for the calculations when the parameter is set to “cluster”. And only the wind and solar data (and not the renewable data) will be considered for the calculations when the parameter is set to “aggregated”. - -The Renewable window can be filled out with the different renewable clusters inside each node. Each renewable cluster needs to have a group specified or will default to the «Other RES 1» group. Production Timeseries can be filled out much like the Thermal production ones. Note that unlike thermal clusters, negative production values are allowed. The Renewable window is described in more details in the “4. Active Windows” section. In the Simulation window, only “Ready-made” timeseries can be selected for renewables for now. This should be modified in a future release. The MC scenario builder for Renewables works the same way as for Thermal Clusters. - -[^17]: As long as the System's list of Areas does not change - -[^18]:E.g. : if three playlists A,B,C are defined over 1000 years (A: years 1 to 1000, B: years 1 to 100, C: Years 13,42,57,112), initial reservoir levels in each Area are identical in the playlists' intersection (years 13,42,57) - -[^19]: If the playlist is full, these years have numbers # (k-1)B+1 ,…., #kB - -[^20]: Described in the note "Optimization Problems Formulation" - diff --git a/docs/user-guide/solver/dynamic-modeler/00-index.md b/docs/user-guide/solver/dynamic-modeler/00-index.md new file mode 100644 index 0000000000..e49906698f --- /dev/null +++ b/docs/user-guide/solver/dynamic-modeler/00-index.md @@ -0,0 +1,15 @@ +[//]: # (Index used by Sphinx to generate correct PDF tree) + +# Dynamic Modeler + +```{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 +``` \ No newline at end of file diff --git a/docs/user-guide/solver/dynamic-modeler/01-overview-dynamic-modeler.md b/docs/user-guide/solver/dynamic-modeler/01-overview-dynamic-modeler.md new file mode 100644 index 0000000000..095c0a9711 --- /dev/null +++ b/docs/user-guide/solver/dynamic-modeler/01-overview-dynamic-modeler.md @@ -0,0 +1,13 @@ +# Overview + +_**Disclaimer: please note that the new Antares dynamic modeler is still under development, and that some of the +features described in this section may still be unavailable**_ + +The new Antares dynamic modeler 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. \ No newline at end of file diff --git a/docs/user-guide/solver/dynamic-modeler/02-inputs.md b/docs/user-guide/solver/dynamic-modeler/02-inputs.md new file mode 100644 index 0000000000..f0eff54ca7 --- /dev/null +++ b/docs/user-guide/solver/dynamic-modeler/02-inputs.md @@ -0,0 +1,3 @@ +# Input files + +_**This section is under construction**_ \ No newline at end of file diff --git a/docs/user-guide/solver/dynamic-modeler/03-outputs.md b/docs/user-guide/solver/dynamic-modeler/03-outputs.md new file mode 100644 index 0000000000..447b91809d --- /dev/null +++ b/docs/user-guide/solver/dynamic-modeler/03-outputs.md @@ -0,0 +1,3 @@ +# Output files + +_**This feature is under development**_ \ No newline at end of file diff --git a/docs/user-guide/solver/dynamic-modeler/04-parameters.md b/docs/user-guide/solver/dynamic-modeler/04-parameters.md new file mode 100644 index 0000000000..ce619350b6 --- /dev/null +++ b/docs/user-guide/solver/dynamic-modeler/04-parameters.md @@ -0,0 +1,3 @@ +# Parameters + +_**This feature is under development**_ diff --git a/docs/user-guide/solver/dynamic-modeler/05-model.md b/docs/user-guide/solver/dynamic-modeler/05-model.md new file mode 100644 index 0000000000..4e0d037286 --- /dev/null +++ b/docs/user-guide/solver/dynamic-modeler/05-model.md @@ -0,0 +1,78 @@ +# Optimization model + +_**This section is under construction**_ + +The new Antares dynamic modeler 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)** +- a list of [ports](#ports-and-connections) + +## Components +A “component” is a model instance: it is an object in the simulated system whose behavior is defined by a model as +described above. +It is therefore defined by: +- a unique identifier in the study +- a model that defines its behavior +- a set of values for the parameters of the model + +## Ports and connections +So far, we haven't defined any possibilities for interaction between models, or between components of a study. However, +we will need to connect these objects to each other: connect a power demand, a production cluster, or a link to a node, typically. + +- a [model](#models) defines a list of its ports, which enable components implementing this model to be connected to other components +- a port, in a model, is defined by a name and its “type”. +- a port type defines the quantities that are exposed: typically a power flow, but also, for example, a gas flow, a voltage phase, etc. + A port type can expose several quantities; these quantities are called “fields”. +- In a system, two components may be linked together by a connection between two ports of identical type (and only in this way). + +The introduction of the port concept allows the user to: +1. expose the internal quantities of a model in a standard way to the outside: for example, the object to which a + generator is connected doesn't need to know the name of the variable internal to the power flow model, it just needs + to know its name on the port type common to all the models. +2. assemble several quantities on the same interface: for example, an electrical power flow and the voltage phase, + for an AC electrical network. + + +Each model can: +1. define, with an [expression](#expressions), the value of a field exposed on one of its ports. +2. use, in any [expression](#expressions), the value of a field of one of its ports, potentially defined by another model. + +In order to obtain a mathematically solvable problems, in a system, each connection between two ports must have a +single definition for each field. + +## Expressions +The [models](#models) allow certain elements to be defined by the user, using “free” mathematical expressions: +- constraints +- variable bounds +- contribution to system cost +- definition of the value of a field exposed on a port + +Expressions can be used to reference: +- model parameters +- model variables +- model port fields + +They also enable a number of antares-specific operations using: +- temporal operators: + - shift: for example, to reference the value of a parameter or variable at the previous time step + - evaluation: reference the value of a parameter or variable at a specific time step, e.g. time step 0 +- time aggregations: for example summing a variable on an interval of time diff --git a/docs/user-guide/solver/dynamic-modeler/06-heuristics.md b/docs/user-guide/solver/dynamic-modeler/06-heuristics.md new file mode 100644 index 0000000000..d175817fc0 --- /dev/null +++ b/docs/user-guide/solver/dynamic-modeler/06-heuristics.md @@ -0,0 +1,3 @@ +# Heuristics + +_**This feature is under development**_ diff --git a/docs/user-guide/solver/dynamic-modeler/07-standard-library.md b/docs/user-guide/solver/dynamic-modeler/07-standard-library.md new file mode 100644 index 0000000000..312e587ce5 --- /dev/null +++ b/docs/user-guide/solver/dynamic-modeler/07-standard-library.md @@ -0,0 +1,3 @@ +# Standard library + +_**This feature is under development**_ diff --git a/docs/user-guide/solver/dynamic-modeler/08-hybrid-studies.md b/docs/user-guide/solver/dynamic-modeler/08-hybrid-studies.md new file mode 100644 index 0000000000..4129576d42 --- /dev/null +++ b/docs/user-guide/solver/dynamic-modeler/08-hybrid-studies.md @@ -0,0 +1,3 @@ +# Hybrid studies + +_**This feature is under development**_ diff --git a/docs/user-guide/solver/optional-features/multi-threading.md b/docs/user-guide/solver/optional-features/multi-threading.md index 5d126a6672..c48bc80a11 100644 --- a/docs/user-guide/solver/optional-features/multi-threading.md +++ b/docs/user-guide/solver/optional-features/multi-threading.md @@ -14,12 +14,12 @@ Provided that hardware resources are large enough, this mode may reduce signific To benefit from multi-threading, the simulation must be run in the following context: -- The [parallel](../08-command-line.md#simulation) option must be enabled (it is disabled by default) -- The simulation [mode](../04-parameters.md#mode) must be either `Adequacy` or `Economy` +- The [parallel](../02-command-line.md#simulation) option must be enabled (it is disabled by default) +- The simulation [mode](../static-modeler/04-parameters.md#mode) must be either `Adequacy` or `Economy` When the "parallel" solver option is used, each Monte-Carlo year is dispatched in an individual process on the available CPU cores. The number of such individual processes depends on the characteristics of the local hardware and on the value given to -the study-dependent [number-of-cores-mode](../04-parameters.md#number-of-cores-mode) advanced parameter. +the study-dependent [number-of-cores-mode](../static-modeler/04-parameters.md#number-of-cores-mode) advanced parameter. This parameter can take five different values (Minimum, Low, Medium, High, Maximum). The number of independent processes resulting from the combination (local hardware + study settings) is given in the following table, which shows the CPU allowances granted in the different configurations. diff --git a/docs/user-guide/solver/static-modeler/00-index.md b/docs/user-guide/solver/static-modeler/00-index.md new file mode 100644 index 0000000000..1b8d1f07e3 --- /dev/null +++ b/docs/user-guide/solver/static-modeler/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 +``` \ No newline at end of file diff --git a/docs/user-guide/solver/static-modeler/01-overview-static-modeler.md b/docs/user-guide/solver/static-modeler/01-overview-static-modeler.md new file mode 100644 index 0000000000..728296c45e --- /dev/null +++ b/docs/user-guide/solver/static-modeler/01-overview-static-modeler.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)**
+ 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):**
+ 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". +
+ 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. +
+ 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_ | \ No newline at end of file diff --git a/docs/user-guide/solver/02-inputs.md b/docs/user-guide/solver/static-modeler/02-inputs.md similarity index 98% rename from docs/user-guide/solver/02-inputs.md rename to docs/user-guide/solver/static-modeler/02-inputs.md index 659208d135..a2f6c5f003 100644 --- a/docs/user-guide/solver/02-inputs.md +++ b/docs/user-guide/solver/static-modeler/02-inputs.md @@ -49,7 +49,7 @@ It is based on the edition of a special "sets.ini" file. - Make sure that the sets.ini file is ready for use before opening the Antares study. Attempts to update the sets.ini file while the study is opened will not be effective. - Definition of meaningless districts (references to nodes that do not exist,…) will generate warnings in the GUI log files. -**HOW TO UPDATE / CREATE the file** : using any text editor, or, better yet, [using Antares extensions](../03-getting_started.md#using-extensions). +**HOW TO UPDATE / CREATE the file** : using any text editor, or, better yet, [using Antares extensions](../../03-getting_started.md#using-extensions). **WHERE TO FIND / STORE THE FILE** : INPUT/areas/sets.ini @@ -157,7 +157,7 @@ The user may pick any area appearing in the list and is then given access to dif - The "local data" tab is used to set the parameters of the stochastic generator. These parameters are presented in four sub-tabs whose content is presented in - [Time-series analysis and generation](../ts-generator/01-overview-tsgenerator.md). + [Time-series analysis and generation](../../ts-generator/01-overview-tsgenerator.md). - The "digest" tab displays for all areas a short account of the local data @@ -233,8 +233,8 @@ a choice can be made between different tabs: - Fuel efficiency (%) - Cost generation [Set manually / Use cost timeseries] - Marginal operating cost (€/MWh) - - Volatility (forced): a parameter between 0 and 1, see section [Time-series generation (thermal)](../ts-generator/05-algorithm.md#time-series-generation-thermal) - - Volatility (planned): a parameter between 0 and 1, see section [Time-series generation (thermal)](../ts-generator/05-algorithm.md#time-series-generation-thermal) + - Volatility (forced): a parameter between 0 and 1, see section [Time-series generation (thermal)](../../ts-generator/05-algorithm.md#time-series-generation-thermal) + - Volatility (planned): a parameter between 0 and 1, see section [Time-series generation (thermal)](../../ts-generator/05-algorithm.md#time-series-generation-thermal) - Law (forced): Probabilistic law used for the generation of the forced outage time-series, can be set to either uniform or geometric - Law (planned): Probabilistic law used for the generation of the planned outage time-series, can be set to either uniform or geometric - Generate TS: Parameter to specify the behavior of this cluster for TS generation. **This cluster-wise parameter takes priority over the study-wide one.** It can hold three values: @@ -499,7 +499,7 @@ The user may pick any area appearing in the list and is then given access to dif When given invalid matrices, the TS generator emits an infeasibility diagnosis -- The "local data" tab is used to set the parameters of the stochastic generator. These parameters are presented in four subtabs whose content is presented in [Time-series analysis and generation](../ts-generator/04-parameters.md). +- The "local data" tab is used to set the parameters of the stochastic generator. These parameters are presented in four subtabs whose content is presented in [Time-series analysis and generation](../../ts-generator/04-parameters.md). - The "digest" tab displays for all areas a short account of the local data @@ -542,7 +542,7 @@ The user may pick any area appearing in the list and is then given access to dif When given invalid matrices, the TS generator emits an infeasibility diagnosis -- The "local data" tab is used to set the parameters of the stochastic generator. These parameters are presented in four subtabs whose content is presented in [Time-series analysis and generation](../ts-generator/04-parameters.md). +- The "local data" tab is used to set the parameters of the stochastic generator. These parameters are presented in four subtabs whose content is presented in [Time-series analysis and generation](../../ts-generator/04-parameters.md). - The "digest" tab displays for all areas a short account of the local data @@ -663,9 +663,9 @@ This window is used to handle all input data regarding the interconnections. On - Loop flow: amount of power flowing circularly though the grid when all "nodes" are perfectly balanced (no import and no export). Such loop flows may be expected on any "simplified" grid in which large regions (or even countries) are modeled by a small number of "macro" nodes, and should accordingly be accounted for. - - PST min (denoted $Y^-$ in [Kirchhoff Constraints Generator](../other-features/kirchhoff-constraints-builder.md)): lower bound of phase-shifting that can be reached by a PST installed on the link, if any (note : the effect of the active loop flow generated by the PST may be superimposed to that of the passive loop flow) + - PST min (denoted $Y^-$ in [Kirchhoff Constraints Generator](../../other-features/kirchhoff-constraints-builder.md)): lower bound of phase-shifting that can be reached by a PST installed on the link, if any (note : the effect of the active loop flow generated by the PST may be superimposed to that of the passive loop flow) - - PST max (denoted $Y^+$ in [Kirchhoff Constraints Generator](../other-features/kirchhoff-constraints-builder.md)): upper bound of phase-shifting that can be reached by a PST installed on the link, if any (note : the effect of the active loop flow generated by the PST may be superimposed to that of the passive loop flow) + - PST max (denoted $Y^+$ in [Kirchhoff Constraints Generator](../../other-features/kirchhoff-constraints-builder.md)): upper bound of phase-shifting that can be reached by a PST installed on the link, if any (note : the effect of the active loop flow generated by the PST may be superimposed to that of the passive loop flow) For the sake of simplicity and homogeneity with the convention used for impedance, PST settings are assumed to be expressed in $ rad/U^2_{ref} $ @@ -712,7 +712,7 @@ Then the DC flow approximation may be implemented, for each time-step of the sim $$ c= 1, ..., C : \sum_{i \in C}{sign(l,c)F_lZ_l = 0}$$ -_Note that such specific binding constraints can be automatically generated within Antares by using the auxiliary module "Kirchhoff's Constraints Generator" further described in [Kirchhoff Constraints Generator](../other-features/kirchhoff-constraints-builder.md)._ +_Note that such specific binding constraints can be automatically generated within Antares by using the auxiliary module "Kirchhoff's Constraints Generator" further described in [Kirchhoff Constraints Generator](../../other-features/kirchhoff-constraints-builder.md)._ Aside from such sets of constraints, which may help to give realistic geographic patterns to the flows, completely different sets of constraints may be also defined, such as those set up by the market organization, which may define precise perimeters for valid commercial flows [^10]. @@ -827,4 +827,4 @@ links and binding constraints. Status can be changed by toggling the icons. Defa other purely graphic icons/buttons (no action on data) allow respectively to center the map on a given set of (x , y) coordinates, and to prune the "empty" space around the current map. Multiple additional maps may be defined by using the cross-shaped button located top right. A detailed presentation of all system map editor features can be found in -the document "System Map Editor User guide". +the document "System Map Editor User guide". \ No newline at end of file diff --git a/docs/user-guide/solver/03-outputs.md b/docs/user-guide/solver/static-modeler/03-outputs.md similarity index 99% rename from docs/user-guide/solver/03-outputs.md rename to docs/user-guide/solver/static-modeler/03-outputs.md index 367340cc3e..e6ec1f0222 100644 --- a/docs/user-guide/solver/03-outputs.md +++ b/docs/user-guide/solver/static-modeler/03-outputs.md @@ -205,7 +205,7 @@ 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 -[^adqp]: Please note that this output variable is only available in the economy mode, when the adequacy patch is activated (see [Adequacy Patch](optional-features/adequacy-patch.md)) +[^adqp]: Please note that this output variable is only available in the economy mode, when the adequacy patch is activated (see [Adequacy Patch](../optional-features/adequacy-patch.md)) [^14]: This description applies to both « MC synthesis » files and "Year-by-Year" files, with some simplifications in the latter case @@ -254,4 +254,4 @@ Here is a list of new output variables in recent versions: | 8.5 | LMR VIOL., SPIL. ENRG. CSR, DTG MRG CSR | values-*.txt | no | | 8.6 | PSP_open_injection, PSP_open_withdrawal, PSP_open_level, PSP_closed_injection, PSP_closed_withdrawal, PSP_closed_level, Pondage_injection, Pondage_withdrawal, Pondage_level, Battery_injection, Battery_withdrawal, Battery_level, Other1_injection, Other1_withdrawal, Other1_level, Other2_injection, Other2_withdrawal, Other2_level, Other3_injection, Other3_withdrawal, Other3_level, Other4_injection, Other4_withdrawal, Other4_level, Other5_injection, Other5_withdrawal, Other5_level | values-*.txt | yes | | 8.6 | STS inj by plant, STS withdrawal by plant, STS lvl by plant | details-STstorage-*.txt | yes | -| 8.6 | CO2 EMIS., NH3 EMIS., SO2 EMIS., NOX EMIS., PM2_5 EMIS., PM5 EMIS., PM10 EMIS., NMVOC EMIS., OP1 EMIS., OP2 EMIS., OP3 EMIS., OP4 EMIS., OP5 EMIS. | values-*.txt | yes | +| 8.6 | CO2 EMIS., NH3 EMIS., SO2 EMIS., NOX EMIS., PM2_5 EMIS., PM5 EMIS., PM10 EMIS., NMVOC EMIS., OP1 EMIS., OP2 EMIS., OP3 EMIS., OP4 EMIS., OP5 EMIS. | values-*.txt | yes | \ No newline at end of file diff --git a/docs/user-guide/solver/04-parameters.md b/docs/user-guide/solver/static-modeler/04-parameters.md similarity index 96% rename from docs/user-guide/solver/04-parameters.md rename to docs/user-guide/solver/static-modeler/04-parameters.md index 5ca79193a0..aad7e09794 100644 --- a/docs/user-guide/solver/04-parameters.md +++ b/docs/user-guide/solver/static-modeler/04-parameters.md @@ -24,11 +24,11 @@ These parameters are listed under the `[general]` section in the `.ini` file. - **Default value:** `economy` - **Usage:** this parameter sets the study mode for Antares - `economy/economic`: Antares simulator will try to ensure balance between load and generation, while minimizing the - economical cost of the grid's operation (more on this [here](../01-overview.md#transmission-project-profitability)). "Economy" simulations make a full use of + economical cost of the grid's operation (more on this [here](../../01-overview.md#transmission-project-profitability)). "Economy" simulations make a full use of *Antares* optimization capabilities. They require economic as well as technical input data and may demand a lot of computer resources. - `adequacy`: in this mode, all power plants' operational cost is considered zero. Antares' only objective is to ensure - balance between load and generation (more on this [here](../01-overview.md#generation-adequacy-problems)). "Adequacy" simulations are faster and require only + balance between load and generation (more on this [here](../../01-overview.md#generation-adequacy-problems)). "Adequacy" simulations are faster and require only technical input data. Their results are limited to adequacy indicators. - `expansion`: Antares simulator will optimize the investments on the grid, minimizing both investments and operational costs. @@ -173,7 +173,7 @@ These parameters are listed under the `[general]` section in the `.ini` file. whose detailed analysis may have shown that they were not physically realistic. A different typical use case consists in replaying only a small number of years of specific interest (for instance, years in the course of which Min or Max values of a given variable were encountered in a previous simulation). - In addition, each MC year i=1, …, N can be given a relative [weight](#playlistyearweight) + In addition, each MC year i=1, …, N can be given a relative [weight](#playlist_year_weight) > _**WARNING:**_ this parameter cannot be used with parameter [derated](#derated) @@ -431,7 +431,7 @@ _**This section is under construction**_ - `optim-2`: export MPS for second step of the optimization - `both-optims` or `true`: export MPS for both steps of the optimization -> _**Note:**_ You can find more information on this parameter [here](09-appendix.md#details-on-the-include-exportmps-parameter). +> _**Note:**_ You can find more information on this parameter [here](../03-appendix.md#details-on-the-include-exportmps-parameter). --- #### include-split-exported-mps @@ -468,7 +468,7 @@ _**This section is under construction**_ - `ERROR_DRY`: stop simulation - `ERROR_MPS`: stop simulation, and export the MPS of the unfeasible problem -> _**Note:**_ You can find more information on this parameter [here](09-appendix.md#details-on-the-include-unfeasible-problem-behavior-parameter). +> _**Note:**_ You can find more information on this parameter [here](../03-appendix.md#details-on-the-include-unfeasible-problem-behavior-parameter). --- #### solver-parameters @@ -482,7 +482,7 @@ _**This section is under construction**_ --- ## Adequacy-patch parameters -Defines a set of options related to the [adequacy patch](optional-features/adequacy-patch.md). +Defines a set of options related to the [adequacy patch](../optional-features/adequacy-patch.md). The set of preferences is study-specific; it can be changed at any time and saved along with study data. These parameters are listed under the `[adequacy patch]` section in the `.ini` file. @@ -491,7 +491,7 @@ These parameters are listed under the `[adequacy patch]` section in the `.ini` f - **Expected value:** `true` or `false` - **Required:** no - **Default value:** `false` -- **Usage:** set this parameter to `true` if you want to enable the [Adequacy Patch](optional-features/adequacy-patch.md) algorithm. +- **Usage:** set this parameter to `true` if you want to enable the [Adequacy Patch](../optional-features/adequacy-patch.md) algorithm. --- #### set-to-null-ntc-from-physical-out-to-physical-in-for-first-step @@ -578,7 +578,7 @@ These parameters are listed under the `[other preferences]` section in the `.ini - `cold start` - `hot start` -> _**Note:**_ You can find more information on this parameter [here](09-appendix.md#details-on-the-initial-reservoir-levels-parameter). +> _**Note:**_ You can find more information on this parameter [here](../03-appendix.md#details-on-the-initial-reservoir-levels-parameter). --- #### hydro-heuristic-policy @@ -592,7 +592,7 @@ These parameters are listed under the `[other preferences]` section in the `.ini - `accommodate rule curves` - `maximize generation` -> _**Note:**_ You can find more information on this parameter [here](09-appendix.md#details-on-the-hydro-heuristic-policy-parameter). +> _**Note:**_ You can find more information on this parameter [here](../03-appendix.md#details-on-the-hydro-heuristic-policy-parameter). --- #### hydro-pricing-mode @@ -606,7 +606,7 @@ These parameters are listed under the `[other preferences]` section in the `.ini - `fast` - `accurate`: Note that this mode is significantly slower than the `fast` mode. -> _**Note:**_ You can find more information on this parameter [here](09-appendix.md#details-on-the-hydro-pricing-mode-parameter). +> _**Note:**_ You can find more information on this parameter [here](../03-appendix.md#details-on-the-hydro-pricing-mode-parameter). --- #### power-fluctuations @@ -648,7 +648,7 @@ These parameters are listed under the `[other preferences]` section in the `.ini - `accurate`: Heuristic in which 2 LP problems are solved. Explicit modelling for the number of ON/OFF units. Slower than `fast`. - `milp`: A single MILP problem is solved, with explicit modelling for the number of ON/OFF units. Slower than `accurate`. -> _**Note:**_ You can find more information on this parameter [here](09-appendix.md#details-on-the-unit-commitment-mode-parameter). +> _**Note:**_ You can find more information on this parameter [here](../03-appendix.md#details-on-the-unit-commitment-mode-parameter). --- #### number-of-cores-mode @@ -660,7 +660,7 @@ These parameters are listed under the `[other preferences]` section in the `.ini - `maximum` - **Required:** no - **Default value:** `medium` -- **Usage:** use this parameter to configure [multi-threading](optional-features/multi-threading.md). +- **Usage:** use this parameter to configure [multi-threading](../optional-features/multi-threading.md). --- #### renewable-generation-modelling @@ -674,7 +674,7 @@ These parameters are listed under the `[other preferences]` section in the `.ini - `aggregated` - `clusters` -> _**Note:**_ You can find more information on this parameter [here](09-appendix.md#details-on-the-renewable-generation-modelling-parameter). +> _**Note:**_ You can find more information on this parameter [here](../03-appendix.md#details-on-the-renewable-generation-modelling-parameter). --- #### day-ahead-reserve-management @@ -822,4 +822,4 @@ They are **required** if [thematic-trimming](#thematic-trimming) is set to `true --- ## Model-wise parameters [//]: # (TODO: link to model-wise parameters documentation) -_**This section is under construction**_ +_**This section is under construction**_ \ No newline at end of file diff --git a/docs/user-guide/solver/05-model.md b/docs/user-guide/solver/static-modeler/05-model.md similarity index 98% rename from docs/user-guide/solver/05-model.md rename to docs/user-guide/solver/static-modeler/05-model.md index 9f37c2ac9a..b05bb39509 100644 --- a/docs/user-guide/solver/05-model.md +++ b/docs/user-guide/solver/static-modeler/05-model.md @@ -31,9 +31,13 @@ The scope of this document is exclusively devoted to step (4). Note that equival The following picture gives a functional view of all that is involved in steps (1) to (5). In this illustration, Step (4), whose goal is to solve the problems introduced in this document, is materialized by the red box. -![Antares_Process](../img/Antares_Process.jpg) +![Antares_Process](../img/Antares_Process.png) -The number and the size of the individual problems to solve (a least-cost hydro-thermal unit-commitment and power schedule, with an hourly resolution and throughout a week, over a large interconnected system) make optimization sessions often computer-intensive. Note that the content of the blue "hydro energy manager" box appearing on the previous figure, whose purpose is to deal with energy storage issues at the seasonal scale, is not detailed in the present document but in the ["Miscellaneous"](../reference-guide/08-miscellaneous.md#the-heuristic-for-seasonal-hydro-pre-allocation) section. +The number and the size of the individual problems to solve (a least-cost hydro-thermal unit-commitment and power +schedule, with an hourly resolution and throughout a week, over a large interconnected system) make optimization +sessions often computer-intensive. Note that the content of the blue "hydro energy manager" box appearing on the +previous figure, whose purpose is to deal with energy storage issues at the seasonal scale, is not detailed in the +present document but in [this section](06-hydro-heuristics.md#seasonal-hydro-pre-allocation). Depending on user-defined results accuracy requirements, various practical options allow to simplify either the formulation of the weekly UC & dispatch problems (e.g. do not account for constraints associated with operational reserves) or their resolution (i.e. find, for the native MILP, an approximate solution based on two successive LPs). For the sake of simplicity and clarity, the way these options are used to revise the primary problem formulation is not detailed hereafter. Likewise, many simplifications are introduced to keep notations as light as possible. This is why, for instance, the overall sum of load, wind power generation, solar power generation, run of the river generation, and all other kinds of so-called "must-run" generation is simply denoted "load" in the present document. @@ -560,7 +564,7 @@ Finally, upstream of the proper optimization, there is a last set of hydro-relat The following diagram summarizes the situation regarding both random and epsilon numbers defined and used within Antares. They are meant to build up, along with the regular description of the power system (physical limits and standard costs), an optimization framework that is up to the complex tasks at hand: balanced Monte- Carlo draws, reproducible simulations exploring the whole span of optimal operating configurations. -![Random_Parameters](img/Random_Parameters.png) +![Random_Parameters](../img/Random_Parameters.png) | Random Epsilons | Minimum absolute value | Maximum absolute value | |-----------------|-------------------------|--------------------------| @@ -604,4 +608,4 @@ Last Rev : M. Doquet - 25 JAN 2023 [^alike]: Consider for instance a case where a fleet of ten exactly identical plants, in a highly symmetric system, is expected to generate an overall amount of power roughly equivalent to the nominal capacity of two of them. Simulations results indicating that this power should exclusively be provided by a specific pair of units (the other eight remaining always idle, throughout all Monte Carlo scenarios), would appear heavily biased, though not mathematically wrong. -[^costs]: These random noises affect only cost-related parameters and not RHS parameters (such perturbations, which have not been implemented so far, might bring some benefits as regards degeneracy). It can also be noted that, in the special case of hydro, the random noise is present in the problem formulation given in this document, with notation $\epsilon_\lambda^0$. +[^costs]: These random noises affect only cost-related parameters and not RHS parameters (such perturbations, which have not been implemented so far, might bring some benefits as regards degeneracy). It can also be noted that, in the special case of hydro, the random noise is present in the problem formulation given in this document, with notation $\epsilon_\lambda^0$. \ No newline at end of file diff --git a/docs/user-guide/solver/06-hydro-heuristics.md b/docs/user-guide/solver/static-modeler/06-hydro-heuristics.md similarity index 100% rename from docs/user-guide/solver/06-hydro-heuristics.md rename to docs/user-guide/solver/static-modeler/06-hydro-heuristics.md diff --git a/docs/user-guide/solver/07-thermal-heuristic.md b/docs/user-guide/solver/static-modeler/07-thermal-heuristic.md similarity index 85% rename from docs/user-guide/solver/07-thermal-heuristic.md rename to docs/user-guide/solver/static-modeler/07-thermal-heuristic.md index 372ceb8bed..e43dbf0b77 100644 --- a/docs/user-guide/solver/07-thermal-heuristic.md +++ b/docs/user-guide/solver/static-modeler/07-thermal-heuristic.md @@ -12,7 +12,7 @@ Please note that this content is only relevant in case the user chooses a linear The linearised resolution of the weekly adequacy problem[^1] is summarized in the diagram below: -![Global diagram](img/global_diagram.png){ .add-padding-and-white-bg } +![Global diagram](../img/global_diagram.png){ .add-padding-and-white-bg } The general principle of the linear resolution is that two iterations of the weekly optimisation problem will be solved: - A first resolution in which integer variables are either linearised, or completely removed, depending on the "unit commitment mode" chosen (step 1). @@ -35,33 +35,33 @@ The way steps 1 and 2 are performed depends on a parameter set by the user in th ### Fast mode #### Step 1: first problem resolution -The general idea of the fast mode is to completely remove the constraints and costs involving integers (the $M_\theta$, $M_\theta^+$ and $M_\theta^-$ variables) in step 1. This means that the first resolution of the weekly problem does not consider constraints (17) to (23) in the [optimisation problem formulation](01-modeling.md). Constraint (16) related to the minimum/maximum output of the thermal cluster is kept. In addition, costs related to integer variables (start-up and hourly fixed costs) are not included in the objective function. +The general idea of the fast mode is to completely remove the constraints and costs involving integers (the $M_\theta$, $M_\theta^+$ and $M_\theta^-$ variables) in step 1. This means that the first resolution of the weekly problem does not consider constraints (17) to (23) in the [optimisation problem formulation](05-model.md). Constraint (16) related to the minimum/maximum output of the thermal cluster is kept. In addition, costs related to integer variables (start-up and hourly fixed costs) are not included in the objective function. The first resolution of the problem is then run, and provides hourly power outputs for each thermal cluster $P_{\theta,t}^{optim1}$. At each hour, an initial value of the NODU of each cluster in then calculated: $M_{\theta,t}^{guide}$ = $ceil(\frac{P_{\theta,t}^{optim1}}{\overline{P_{\theta} } }) $. #### Step 2: fast mode heuristic In step 2, for each cluster, a parameter $\Delta_{adjust,\theta} = max(\Delta_\theta^+, \Delta_\theta^-)$ is then calculated, which is the maximum of the minimum on and off durations. Hence, they are approximated to be of the same duration. For each week and each thermal cluster, the week is then divided in intervals of length $\Delta_{adjust,\theta}$. The week is supposed to be cyclic (hour 1 is the timestep followin hour 168), just like in the weekly optimization problem solved by Antares. Within each interval, the NODU of the cluster is increased to the maximum value of $M_{\theta, t}^{guide}$ during this period. This process is run several time by shifting the intervals timestep by timestep until all the possible week splits have been performed. Finally, the solution which minimizes the number of adjustments of the NODU is used as the solution of step 2 $M_{\theta,t}^{heuristic}$. -![Step 2 of the "fast" thermal mode](img/thermal_heuristic_fast_step_2.png){ .add-padding-and-white-bg } +![Step 2 of the "fast" thermal mode](../img/thermal_heuristic_fast_step_2.png){ .add-padding-and-white-bg }

Illustration of step 2 of the fast mode, with $\Delta_{adjust,\theta}$ equal to 2. Here, both solutions are acceptable as they involve 3 NODU adjustments.

#### Step 3: second resolution -Finally, the result of the heuristic $M_{\theta,t}^{heuristic}$ is converted into a lower bound of the power output of each thermal cluster in step 3: $P_{\theta,t}^{min}=\underline{P_\theta}*M_{\theta,t}^{heuristic}$. The second resolution of the problem is then run considering this lower bound, and still excluding integer variables and constraints (17) to (23) of the [optimisation problem formulation](01-modeling.md). In particular, this means that startup and fixed costs are not considered in the formulation of the optimisation problem in any of the two resolutions. However, they are added ex-post and visible in the output variables. +Finally, the result of the heuristic $M_{\theta,t}^{heuristic}$ is converted into a lower bound of the power output of each thermal cluster in step 3: $P_{\theta,t}^{min}=\underline{P_\theta}*M_{\theta,t}^{heuristic}$. The second resolution of the problem is then run considering this lower bound, and still excluding integer variables and constraints (17) to (23) of the [optimisation problem formulation](05-model.md). In particular, this means that startup and fixed costs are not considered in the formulation of the optimisation problem in any of the two resolutions. However, they are added ex-post and visible in the output variables. ### Accurate mode #### Step 1: first problem resolution -The accurate mode aims at taking into account integer variables in both resolutions of the optimisation problem (steps 1 and 3), but considering them as continuous variables in step 1, and fixing them as parameters in step 3. Contrary to the fast mode, constraints (17) to (23) of the [optimisation problem formulation](01-modeling.md) are taken into account in both resolutions, as well as the start-up and fixed costs in the objective function, but the integer variables $M_\theta$ are considered continuous. +The accurate mode aims at taking into account integer variables in both resolutions of the optimisation problem (steps 1 and 3), but considering them as continuous variables in step 1, and fixing them as parameters in step 3. Contrary to the fast mode, constraints (17) to (23) of the [optimisation problem formulation](05-model.md) are taken into account in both resolutions, as well as the start-up and fixed costs in the objective function, but the integer variables $M_\theta$ are considered continuous. The first resolution of the problem is then run. As an output, the integer NODU for each thermal cluster is calculed by rounding up the continuous NODUs which are the output of this resolution: $M_{\theta,t}^{guide}=ceil(M_{\theta,t}^{optim1})$. The variables counting the number of units being started-up or shut-down at any time step $M_{\theta,t}^{+}$ and $M_{\theta,t}^{-}$ are also calculated at that stage. #### Step 2: accurate mode heuristic -Step 2 of the accurate mode starts by checking for each cluster and for each week whether any constraint of minimum time up or down (constraints (22) and (23) of the [weekly optimisation problem](01-modeling.md)) is violated. If no constraint is violated for a given thermal cluster at a given week, no further action is performed and the output variable of this step $M_{\theta,t}^{heuristic}=M_{\theta,t}^{guide}$. +Step 2 of the accurate mode starts by checking for each cluster and for each week whether any constraint of minimum time up or down (constraints (22) and (23) of the [weekly optimisation problem](05-model.md)) is violated. If no constraint is violated for a given thermal cluster at a given week, no further action is performed and the output variable of this step $M_{\theta,t}^{heuristic}=M_{\theta,t}^{guide}$. For a given cluster and a given week, if any of these constraints is violated, a small optimisation problem is run, which aims at minimizing the changes to the NODU of the cluster while respecting constraints (22) and (23). The output of this optimisation problem is then $M_{\theta,t}^{heuristic}$. #### Step 3: second resolution -Finally, the output of step 2 $M_{\theta,t}^{heuristic}$ is converted into a lower bound of the NODU of each thermal cluster for the second resolution: $M_{\theta,t} \geq M_{\theta,t}^{heuristic}$. The second resolution of the problem is then run considering this lower bound, and still including integer variables (as continuous variables) and constraints (17) to (23) of the [optimisation problem formulation](01-modeling.md), and start-up and fixed costs in the objective function. +Finally, the output of step 2 $M_{\theta,t}^{heuristic}$ is converted into a lower bound of the NODU of each thermal cluster for the second resolution: $M_{\theta,t} \geq M_{\theta,t}^{heuristic}$. The second resolution of the problem is then run considering this lower bound, and still including integer variables (as continuous variables) and constraints (17) to (23) of the [optimisation problem formulation](05-model.md), and start-up and fixed costs in the objective function. ## Annual smoothing heuristic (step 4) @@ -77,7 +77,7 @@ with $\sigma_\theta^+$ the startup cost of a unit of cluster $\theta$, and ${\ta The smoothing heuristic may then choose to increase the NODU in certain clusters when it identifies that a shut-down/start-up sequence lasted shorter than duration d. The new NODU cannot exceed the maximum accepted NODU to respect the production plan, which is equal to $floor(\frac{P_\theta}{\underline{P_\theta}})$. -![Step 4: smoothing heuristic](img/thermal_smoothing_heuristic.png). +![Step 4: smoothing heuristic](../img/thermal_smoothing_heuristic.png). -[^1]: The formulation of the weekly optimization problem is described in the ["Formulation of the optimisation problems"](01-modeling.md) section. \ No newline at end of file +[^1]: The formulation of the weekly optimization problem is described in the ["Formulation of the optimisation problems"](05-model.md) section. \ No newline at end of file diff --git a/docs/user-guide/ts-generator/01-overview-tsgenerator.md b/docs/user-guide/ts-generator/01-overview-tsgenerator.md index e77bab6872..67349f7654 100644 --- a/docs/user-guide/ts-generator/01-overview-tsgenerator.md +++ b/docs/user-guide/ts-generator/01-overview-tsgenerator.md @@ -4,6 +4,6 @@ _**This section is under construction**_ The Time-Series Generator tool is intended to be used before running an *Antares* simulation if you do not dispose of all the needed input data. -This tool can be used to generate automatically [any or all](04-parameters.md) stochastic input data +This tool can be used to generate automatically [any or all](../solver/static-modeler/04-parameters.md) stochastic input data (such as renewable energy production time-series) -and put them automatically inside the *Antares* [solver](../solver/02-inputs.md)'s input directory. +and put them automatically inside the *Antares* [solver](../solver/static-modeler/02-inputs.md)'s input directory. diff --git a/docs/user-guide/ts-generator/04-parameters.md b/docs/user-guide/ts-generator/04-parameters.md index debe1465cc..6da36c8ece 100644 --- a/docs/user-guide/ts-generator/04-parameters.md +++ b/docs/user-guide/ts-generator/04-parameters.md @@ -167,7 +167,7 @@ These parameters are listed under the `[input]` section in the `.ini` file. should be exported into the input files (in replacement of the original ones). > _**Note:**_ -> you can also use [archives](../solver/04-parameters.md#archives) to store the time-series in the output folder. +> you can also use [archives](../solver/static-modeler/04-parameters.md#archives) to store the time-series in the output folder. --- ## Seeds - Mersenne Twister parameters diff --git a/mkdocs.yml b/mkdocs.yml index 129404222e..14b203357d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,77 +19,94 @@ theme: # - toc.separate palette: - media: "(prefers-color-scheme: light)" - scheme: antares + scheme: default toggle: - icon: material/toggle-switch-off-outline + icon: material/toggle-switch name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" scheme: slate toggle: - icon: material/toggle-switch + icon: material/toggle-switch-off-outline name: Switch to light mode nav: - 'Home': 'index.md' - 'User guide': - - 'Overview': 'user-guide/01-overview.md' - - 'Installation': 'user-guide/02-install.md' - - 'Getting started': 'user-guide/03-getting_started.md' - - 'Solver': - - 'Overview': 'user-guide/solver/01-overview.md' - - 'Input files': 'user-guide/solver/02-inputs.md' - - 'Output files': 'user-guide/solver/03-outputs.md' - - 'Parameters': 'user-guide/solver/04-parameters.md' - - 'Optimization model': 'user-guide/solver/05-model.md' - - 'Hydro heuristics': 'user-guide/solver/06-hydro-heuristics.md' - - 'Thermal heuristics': 'user-guide/solver/07-thermal-heuristic.md' - - 'Command-line instructions': 'user-guide/solver/08-command-line.md' - - 'Optional features': - - 'Multi-threading': 'user-guide/solver/optional-features/multi-threading.md' - - 'Adequacy patch': 'user-guide/solver/optional-features/adequacy-patch.md' - - 'Usage with FICO® Xpress Optimizer': 'user-guide/solver/optional-features/xpress.md' - - 'Appendix': 'user-guide/solver/09-appendix.md' - - 'Time-series generation': - - 'Overview': 'user-guide/ts-generator/01-overview.md' - - 'Input files': 'user-guide/ts-generator/02-inputs.md' - - 'Output files': 'user-guide/ts-generator/03-outputs.md' - - 'Parameters': 'user-guide/ts-generator/04-parameters.md' - - 'Algorithm': 'user-guide/ts-generator/05-algorithm.md' - - 'Command-line instructions': 'user-guide/ts-generator/06-command-line.md' - - 'Other features': - - 'Batch Runner': 'user-guide/other-features/batchrun.md' - - 'Config Checker': 'user-guide/other-features/config.md' - - 'GUI': 'user-guide/other-features/ui-simulator.md' - - 'Kirchhoff''s constraint generator': 'user-guide/other-features/kirchhoff-constraints-builder.md' - - 'Study Cleaner': 'user-guide/other-features/study-cleaner.md' - - 'Study Finder': 'user-guide/other-features/study-finder.md' - - 'Study Updater': 'user-guide/other-features/study-updater.md' - - 'Time-Series Analyzer': 'user-guide/other-features/analyzer.md' - - 'Vacuum': 'user-guide/other-features/vacuum.md' - - 'Year-by-Year Aggregator': 'user-guide/other-features/ybyaggregator.md' - - 'Migration guides': 'user-guide/04-migration-guides.md' - - 'Attribution notices': 'user-guide/05-attribution_notices.md' + - 'Overview': 'user-guide/01-overview.md' + - 'Installation': 'user-guide/02-install.md' + - 'Getting started': 'user-guide/03-getting_started.md' + - 'Solver': + - 'Overview': 'user-guide/solver/01-overview-solver.md' + - 'Static Modeler': + - 'Overview': 'user-guide/solver/static-modeler/01-overview-static-modeler.md' + - 'Input files': 'user-guide/solver/static-modeler/02-inputs.md' + - 'Output files': 'user-guide/solver/static-modeler/03-outputs.md' + - 'Parameters': 'user-guide/solver/static-modeler/04-parameters.md' + - 'Optimization model': 'user-guide/solver/static-modeler/05-model.md' + - 'Hydro heuristics': 'user-guide/solver/static-modeler/06-hydro-heuristics.md' + - 'Thermal heuristics': 'user-guide/solver/static-modeler/07-thermal-heuristic.md' + - 'Dynamic Modeler': + - 'Overview': 'user-guide/solver/dynamic-modeler/01-overview-dynamic-modeler.md' + - 'Input files': 'user-guide/solver/dynamic-modeler/02-inputs.md' + - 'Output files': 'user-guide/solver/dynamic-modeler/03-outputs.md' + - 'Parameters': 'user-guide/solver/dynamic-modeler/04-parameters.md' + - 'Optimization model': 'user-guide/solver/dynamic-modeler/05-model.md' + - 'Heuristics': 'user-guide/solver/dynamic-modeler/06-heuristics.md' + - 'Standard library': 'user-guide/solver/dynamic-modeler/07-standard-library.md' + - 'Hybrid studies': 'user-guide/solver/dynamic-modeler/08-hybrid-studies.md' + - 'Command-line instructions': 'user-guide/solver/02-command-line.md' + - 'Optional features': + - 'Multi-threading': 'user-guide/solver/optional-features/multi-threading.md' + - 'Adequacy patch': 'user-guide/solver/optional-features/adequacy-patch.md' + - 'Usage with FICO® Xpress Optimizer': 'user-guide/solver/optional-features/xpress.md' + - 'Appendix': 'user-guide/solver/03-appendix.md' + - 'Time-series generation': + - 'Overview': 'user-guide/ts-generator/01-overview-tsgenerator.md' + - 'Input files': 'user-guide/ts-generator/02-inputs.md' + - 'Output files': 'user-guide/ts-generator/03-outputs.md' + - 'Parameters': 'user-guide/ts-generator/04-parameters.md' + - 'Algorithm': 'user-guide/ts-generator/05-algorithm.md' + - 'Command-line instructions': 'user-guide/ts-generator/06-command-line.md' + - 'Other features': + - 'Batch Runner': 'user-guide/other-features/batchrun.md' + - 'Config Checker': 'user-guide/other-features/config.md' + - 'GUI': 'user-guide/other-features/ui-simulator.md' + - 'Kirchhoff''s constraint generator': 'user-guide/other-features/kirchhoff-constraints-builder.md' + - 'Study Cleaner': 'user-guide/other-features/study-cleaner.md' + - 'Study Finder': 'user-guide/other-features/study-finder.md' + - 'Study Updater': 'user-guide/other-features/study-updater.md' + - 'Time-Series Analyzer': 'user-guide/other-features/analyzer.md' + - 'Vacuum': 'user-guide/other-features/vacuum.md' + - 'Year-by-Year Aggregator': 'user-guide/other-features/ybyaggregator.md' + - 'Migration guides': 'user-guide/04-migration-guides.md' + - 'Attribution notices': 'user-guide/05-attribution_notices.md' - 'Developer guide': - - 'Overview': 'developer-guide/0-Overview.md' - - 'Development requirements': 'developer-guide/1-Development-requirements.md' - - 'Dependencies install': 'developer-guide/2-Dependencies-install.md' - - 'Build': 'developer-guide/3-Build.md' - - 'Tests (user)': 'developer-guide/4-Tests-user.md' - - 'Tests (developer)': 'developer-guide/4-Tests-dev.md' - - 'Installer creation': 'developer-guide/5-Installer-creation.md' - - 'Contributing': 'developer-guide/6-Contributing.md' - - 'Continuous Integration': 'developer-guide/continuous-integration.md' - - 'OR-tools integration': 'developer-guide/ortools-integration.md' - - 'Changelog': 'developer-guide/CHANGELOG.md' + - 'Overview': 'developer-guide/0-Overview.md' + - 'Development requirements': 'developer-guide/1-Development-requirements.md' + - 'Dependencies install': 'developer-guide/2-Dependencies-install.md' + - 'Build': 'developer-guide/3-Build.md' + - 'Tests (user)': 'developer-guide/4-Tests-user.md' + - 'Tests (developer)': 'developer-guide/4-Tests-dev.md' + - 'Installer creation': 'developer-guide/5-Installer-creation.md' + - 'Contributing': 'developer-guide/6-Contributing.md' + - 'Continuous Integration': 'developer-guide/continuous-integration.md' + - 'OR-tools integration': 'developer-guide/ortools-integration.md' + - 'Changelog': 'developer-guide/CHANGELOG.md' + - 'Software architecture': + - 'Dynamic modeler architecture' : 'developer-guide/Architecture/Dynamic-modeler-architecture.md' - 'External links': - - 'Antares ecosystem': 'https://antares-doc.readthedocs.io' - - 'Antares website': 'https://antares-simulator.org' - - 'RTE website': 'http://www.rte-france.com/' + - 'Antares ecosystem': 'https://antares-doc.readthedocs.io' + - 'Antares website': 'https://antares-simulator.org' + - 'RTE website': 'http://www.rte-france.com/' - 'Contact': 'https://github.com/AntaresSimulatorTeam/Antares_Simulator/issues/new?template=support_request.md' plugins: - search + - plantuml: + puml_url: https://www.plantuml.com/plantuml/ + puml_keyword: plantuml extra_css: - stylesheets/extra.css @@ -107,7 +124,7 @@ markdown_extensions: permalink: true toc_depth: 3 - pymdownx.emoji: - emoji_index: !!python/name:materialx.emoji.twemoji + emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:materialx.emoji.to_svg - admonition - pymdownx.details diff --git a/requirements-doc.txt b/requirements-doc.txt index 80491f6f5b..0ceaecb6b0 100644 --- a/requirements-doc.txt +++ b/requirements-doc.txt @@ -2,3 +2,4 @@ mkdocs mkdocs-material sphinx myst-parser +mkdocs_puml \ No newline at end of file