diff --git a/.github/workflows/build-userguide.yml b/.github/workflows/build-userguide.yml index b71d474d37..599fdbd663 100644 --- a/.github/workflows/build-userguide.yml +++ b/.github/workflows/build-userguide.yml @@ -6,6 +6,10 @@ on: push: branches: - release/* + - feature/* + - features/* + - fix/* + - issue-* - doc/* - dependabot/* workflow_call: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 453988c19c..ba7010934b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,7 +15,7 @@ Antares Simulator team will be pleased to have developers join our project. 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/build/0-Introduction.md). +or [its sources](docs/developer-guide/0-Introduction.md). ### Branch names Currently, CI is run only for specific branch names: diff --git a/NEWS.md b/NEWS.md index f24a4c7442..9d36d912f2 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ Antares Changelog ================= -Please refer to [docs/CHANGELOG.md](docs/CHANGELOG.md) +Please refer to [docs/developer-guide/CHANGELOG.md](docs/developer-guide/CHANGELOG.md) diff --git a/README.md b/README.md index 235b8e954c..df15f52b86 100644 --- a/README.md +++ b/README.md @@ -29,14 +29,14 @@ In May 2018, RTE decided to release the project under the GPLv3 license. In January 2024, RTE, as the exclusive copyright owner, decided to switch from the GPLv3 to the MPLv2 license, starting with the 9.0 version of Antares Simulator. -The GUI is deprecated in favor of [Antares Web](https://github.com/AntaresSimulatorTeam/AntaREST). +The GUI is deprecated in favor of [Antares Web](https://antares-web.readthedocs.io). # Links: - Antares website: https://antares-simulator.org - RTE web site : http://www.rte-france.com/ - Doxygen code documentation: https://antaressimulatorteam.github.io/Antares_Simulator/doxygen -- Antares Web: https://github.com/AntaresSimulatorTeam/AntaREST +- Antares Web: https://antares-web.readthedocs.io # Installation @@ -49,7 +49,7 @@ This software suite has been tested under: Antares Simulator is built using CMake. For installation instructions, please visit the [documentation website](https://antares-simulator.readthedocs.io/) -or [its sources](docs/build/0-Introduction.md). +or [its sources](docs/developer-guide/0-Introduction.md). # Source Code Content diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..49c350d844 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,114 @@ +# Antares_Simulator documentation sources + +This directory contains the source files for building the *Antares Simulator* [documentation website](https://antares-simulator.readthedocs.io/), +the PDF user guides that are published in every [release](https://github.com/AntaresSimulatorTeam/Antares_Simulator/releases), +as well as the [Doxygen documentation](https://antaressimulatorteam.github.io/Antares_Simulator/doxygen/). + +Please help us keep this documentation alive: +- If you find that something is missing, outdated, or some mistake, report it in a [new issue](https://github.com/AntaresSimulatorTeam/Antares_Simulator/issues/new) + or, better yet, open a [pull request](https://github.com/AntaresSimulatorTeam/Antares_Simulator/compare)! +- If you add a new feature, change a parameter, change something in the technical workflow, etc., update these + sources in the same pull request. Pull requests that do not update the documentation when needed will not be approved. + +## Contents of this directory + +As noted above, these sources serve two purposes: +1. Building the website +2. Building the PDF user guide +3. Building the Doxygen documentation + +While most of the source code is common, some code is specific. + +### Building the website +The website is hosted on [readthedocs](https://readthedocs.org/). The build workflow requires a configuration file which +is currently at the root of the project: [readthedocs.yml](../readthedocs.yml). This platform presents many advantages, +thanks to its workflow of automatic branch/tag building & publication: +- Multiple versions are activated: you can browse different versions of the documentation for different releases of *Antares Simulator* +- Pull requests are built automatically and the built status is reported in the PR's checks (`docs/readthedocs.org:antares-simulator`). + You can preview the built website inside this check (just click on `Details`), thus making it easier for reviewers to review changes of the docs. + +HTML content of the website is built automatically from source files written in [Markdown](https://fr.wikipedia.org/wiki/Markdown), +using [mkdocs](https://www.mkdocs.org/). +The mkdocs configuration file is [mkdocs.yml](../mkdocs.yml), at the root of the project. +It contains all customization options for the website (for example, the theme used is [mkdocs-material](https://squidfunk.github.io/mkdocs-material/)). +Here is the most common cases when you'll need to tweak this file: +- When you add a new page (written in Markdown), it is invisible by default. In order to make it visible, you have to + add it to the navigation list of the website in mkdocs.yml (`nav` section). +- If you want to customize the theme's behaviour, you will probably have to change the mkdocs.yml file (refer to the + used theme's documentation first) +- If you want to customize mkdoc's behaviour, add plugins, css, etc., you need to change this file (refer to the + [mkdocs doc](https://www.mkdocs.org/user-guide/) first) + +Sometimes, the possibilities offered by mkdocs & the used theme can be limiting. Mkdocs offers the possibility to use +custom html & css code. Currently, two methods are used: +- Custom CSS: the [extra.css](stylesheets/extra.css) files contains custom CSS classes (read more about this [here](https://squidfunk.github.io/mkdocs-material/customization/#additional-css)). + Feel free to add classes to it if you find it necessary. +- HTML overrides: the [overrides](overrides) directory contains HTML files that override objects inherited from mkdocs + or its theme (read more about this [here](https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme)). + You can use this method when other, lighter methods (i.e. tweaking mkdocs.yml & CSS styles) are not enough. + +When modifying the website content, you can easily preview the result on your PC by navigating to the root of the +project and running: +```bash +mkdocs serve +``` +Then click on the produced link (most likely `http://127.0.0.1:8000/`) to open the website in your browser. +As long as this process is running, updating any doc file automatically regenerates the website and refreshed the browser. + +### Building the PDF user guide +In every *Antares Simulator* [release](https://github.com/AntaresSimulatorTeam/Antares_Simulator/releases), +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 +[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: +- 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) + file should be updated** in the same way mkdocs.yml is, in order to keep the navigation tree of the PDF document + synchronized with the navigation tree of the mkdocs website. + +When modifying the user guide content, you can easily preview the resulting PDF on your PC by navigating to the +root of the project and running: +```bash +cd docs/pdf-doc-generation-with-sphinx +bash create_pdf_doc.sh reference-guide.pdf +``` +Sphinx will create a `reference-guide.pdf` file in `docs/pdf-doc-generation-with-sphinx`. + +### Doxygen +[//]: # (TODO) +We strive to enrich code documentation as it evolves. The doxygen doc is generated automatically each time the develop +branch is updated. It is hosted [here](https://antaressimulatorteam.github.io/Antares_Simulator/doxygen), and can also +be generated locally with the follow command at the root of the project: + +**doxygen-executable** docs/Doxyfile + +If you'd like the same rendering as the one published checkout [doxygen-awesome-css](https://github.com/jothepro/doxygen-awesome-css) +and do this step before: +```bash +git clone https://github.com/jothepro/doxygen-awesome-css.git +cd doxygen-awesome-css +git checkout v2.2.1 +git apply ../docs/antares-simulator-doxygen.patch +``` + +## Extra considerations + +Like mentioned above, the same source material is used to automatically generate three different formats (mkdocs website, +PDF, doxygen website). When writing pages that have to be published in more than one format, please make sure the +syntax you are using is compatible with all the target formats. +Here is a **non-exhaustive** list of points to watch out for: +- When you add a page, make sure you add it to all target supports. For instance, adding a page to the mkdocs website + requires creating a `nav` entry in the [mkdocs.yml](../mkdocs.yml) file, while adding it to the Sphinx PDF requires + adding an extra entry to an existing index.md file, and, sometimes, creating an extra index.md file (to add a section). +- Do not use non-standard characters (such as emojis) in the user guide, as they cannot be rendered by LaTeX + in PDF. diff --git a/docs/build/0-Introduction.md b/docs/developer-guide/0-Overview.md similarity index 99% rename from docs/build/0-Introduction.md rename to docs/developer-guide/0-Overview.md index f6c3cdb998..139f23d552 100644 --- a/docs/build/0-Introduction.md +++ b/docs/developer-guide/0-Overview.md @@ -3,7 +3,7 @@ hide: - toc --- -# Introduction +# Overview *ANTARES* is developed mainly in **C++** diff --git a/docs/build/1-Development-requirements.md b/docs/developer-guide/1-Development-requirements.md similarity index 100% rename from docs/build/1-Development-requirements.md rename to docs/developer-guide/1-Development-requirements.md diff --git a/docs/build/2-Dependencies-install.md b/docs/developer-guide/2-Dependencies-install.md similarity index 100% rename from docs/build/2-Dependencies-install.md rename to docs/developer-guide/2-Dependencies-install.md diff --git a/docs/build/3-Build.md b/docs/developer-guide/3-Build.md similarity index 94% rename from docs/build/3-Build.md rename to docs/developer-guide/3-Build.md index 9b9f946ab7..14f7ccdbe3 100644 --- a/docs/build/3-Build.md +++ b/docs/developer-guide/3-Build.md @@ -42,10 +42,10 @@ Here is a list of mandatory or optional CMake configuration options: | Option | Mandatory | Description | Expected value | Default value | |:----------------------|-----------|----------------------------------------------------------------------------------|----------------------------------------|-----------------------------------------------------------| -| `CMAKE_C_COMPILER` | **yes** | Select C compiler | `gcc_-10` | | +| `CMAKE_C_COMPILER` | **yes** | Select C compiler | `gcc_-10` | | | `CMAKE_CXX_COMPILER` | **yes** | Select C++ compiler | `g++-10` | | | `CMAKE_BUILD_TYPE` | **yes** | Define build type | `Release` / `Debug` / `RelWithDebInfo` | | -| `BUILD_UI` | no | Enable or disable Antares Simulator UI compilation | `ON` / `OFF` | `ON` | +| `BUILD_UI` | no | Enable or disable Antares Simulator UI[^1] compilation | `ON` / `OFF` | `ON` | | `BUILD_ALL` | no | Enable build of ALL external libraries | `ON` / `OFF` | `OFF` | | `DEPS_INSTALL_DIR` | no | Define dependencies libraries install directory | absolute path to an existing directory | `/../rte-antares-deps-` | | `USE_PRECOMPILED_EXT` | no | This option must be set if you use wxWidget as precompiled external library | `ON` / `OFF` | `OFF` | @@ -91,3 +91,5 @@ Additional options for Windows: The final GUI file can be executed at `_build/ui/simulator/antares-X.Y-ui-simulator` + +[^1]: GUI support has been dropped in favor of [Antares Web](https://antares-web.readthedocs.io) \ No newline at end of file diff --git a/docs/build/4-Tests-dev.md b/docs/developer-guide/4-Tests-dev.md similarity index 97% rename from docs/build/4-Tests-dev.md rename to docs/developer-guide/4-Tests-dev.md index 970cc729f1..f7db7e353f 100644 --- a/docs/build/4-Tests-dev.md +++ b/docs/developer-guide/4-Tests-dev.md @@ -57,6 +57,9 @@ In the future, CentOS 7 should be included as well. Every study contains a `check-config.json` file that configures the test. Here is its content. ### Contents +[//]: # (TODO) +_**This section is under construction**_ + #### name The name of the test. Not really important, and currently not used. @@ -65,14 +68,12 @@ The list of checks that the test should conduct on the results. Contains one `output_compare` and one `integrity_compare` json objects. ##### output-compare -Either an empty json object (`{}`), or ?? TODO ##### integrity-compare -Either `null`, or ?? TODO ### Full example ```json -TODO + ``` ## Workflow diff --git a/docs/build/4-Tests-user.md b/docs/developer-guide/4-Tests-user.md similarity index 100% rename from docs/build/4-Tests-user.md rename to docs/developer-guide/4-Tests-user.md diff --git a/docs/build/5-Installer-creation.md b/docs/developer-guide/5-Installer-creation.md similarity index 100% rename from docs/build/5-Installer-creation.md rename to docs/developer-guide/5-Installer-creation.md diff --git a/docs/CHANGELOG.md b/docs/developer-guide/CHANGELOG.md similarity index 100% rename from docs/CHANGELOG.md rename to docs/developer-guide/CHANGELOG.md diff --git a/docs/build/continuous-integration.md b/docs/developer-guide/continuous-integration.md similarity index 62% rename from docs/build/continuous-integration.md rename to docs/developer-guide/continuous-integration.md index fc8b14c26b..6414c531a6 100644 --- a/docs/build/continuous-integration.md +++ b/docs/developer-guide/continuous-integration.md @@ -3,23 +3,16 @@ Here is a description of workflows with their associated status. -## Primary build & release workflows +## Build & release workflows -| OS | .yml | Description | Status | -|:-----------------|---------------------------------|-----------------------------------------------------------------------------------------|------------------------------------------------------| -| Ubuntu | `ubuntu.yml` | Builds Antares Simulator | [![Status][ubuntu_ci_svg]][ubuntu_ci_link] | -| Windows | `windows-vcpkg.yml` | Builds Antares Simulator | [![Status][windows_ci_svg]][windows_ci_link] | -| Centos7 | `centos7.yml` | Builds Antares Simulator | [![Status][centos_ci_svg]][centos_ci_link] | -| OracleLinux8 | `oracle8.yml` | Builds Antares Simulator | [![Status][oraclelinux_ci_svg]][oraclelinux_ci_link] | -| - | `build-userguide.yml` | Generates PDF user guide from material in `docs/reference-guide` (uses Sphinx) | [![Status][userguide_svg]][userguide_link] | -| All of the above | `new_release.yml` | When a release is created, runs the aforementioned workflows and publishes their assets | [![Status][new_release_svg]][new_release_link] | - -## Secondary build workflows - -| OS | .yml | Description | Status | -|:-----------------|---------------------------------|-----------------------------------------------------------------------------------------|------------------------------------------------------------| -| Ubuntu | `ubuntu-system-deps-build.yml` | Builds Antares Simulator's dependencies | [![Status][ubuntu_deps_build_svg]][ubuntu_deps_build_link] | -| Centos7 | `centos7-system-deps-build.yml` | Builds Antares Simulator's dependencies | [![Status][centos_deps_build_svg]][centos_deps_build_link] | +| OS | .yml | Description | Status | +|:-----------------|-----------------------|-----------------------------------------------------------------------------------------|------------------------------------------------------| +| Ubuntu | `ubuntu.yml` | Builds Antares Simulator | [![Status][ubuntu_ci_svg]][ubuntu_ci_link] | +| Windows | `windows-vcpkg.yml` | Builds Antares Simulator | [![Status][windows_ci_svg]][windows_ci_link] | +| Centos7 | `centos7.yml` | Builds Antares Simulator | [![Status][centos_ci_svg]][centos_ci_link] | +| OracleLinux8 | `oracle8.yml` | Builds Antares Simulator | [![Status][oraclelinux_ci_svg]][oraclelinux_ci_link] | +| - | `build-userguide.yml` | Generates PDF user guide from material in `docs/user-guide` (uses Sphinx) | [![Status][userguide_svg]][userguide_link] | +| All of the above | `new_release.yml` | When a release is created, runs the aforementioned workflows and publishes their assets | [![Status][new_release_svg]][new_release_link] | ## Additional workflows @@ -39,18 +32,12 @@ Here is a description of workflows with their associated status. [ubuntu_ci_svg]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/workflows/Ubuntu%20CI%20(push%20and/or%20release)/badge.svg [ubuntu_ci_link]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/actions?query=workflow%3A"Ubuntu%20CI%20(push%20and/or%20release)" -[ubuntu_deps_build_svg]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/workflows/Ubuntu%20CI%20(deps.%20compilation)/badge.svg -[ubuntu_deps_build_link]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/actions?query=workflow%3A"Ubuntu%20CI%20(deps.%20compilation)" - [windows_ci_only_svg]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/workflows/Windows%20CI%20(pre-compiled%20only)/badge.svg [windows_ci_only_link]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/actions?query=workflow%3A"Windows%20CI%20(pre-compiled%20only)" [windows_ci_svg]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/workflows/Windows%20CI%20(VCPKG%20and%20pre-compiled)/badge.svg [windows_ci_link]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/actions?query=workflow%3A"Windows%20CI%20(VCPKG%20and%20pre-compiled)" -[centos_deps_build_svg]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/workflows/Centos7%20CI%20(deps.%20compilation)/badge.svg -[centos_deps_build_link]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/actions?query=workflow%3A"Centos7%20CI%20(deps.%20compilation)" - [centos_ci_svg]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/workflows/Centos7%20CI%20(push%20and/or%20release)/badge.svg [centos_ci_link]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/actions?query=workflow%3A"Centos7%20CI%20(push%20and/or%20release)" diff --git a/docs/build/ortools-integration.md b/docs/developer-guide/ortools-integration.md similarity index 66% rename from docs/build/ortools-integration.md rename to docs/developer-guide/ortools-integration.md index 84c08d9a66..4c0b4b8d8d 100644 --- a/docs/build/ortools-integration.md +++ b/docs/developer-guide/ortools-integration.md @@ -9,6 +9,7 @@ It is compatible with most of existing open-source & commercial solvers. These are the solver names and enum, defined in the [OR-Tools API](https://github.com/google/or-tools/blob/stable/ortools/linear_solver/linear_solver.cc). ### Linear optimization + | OR-Tools solver name | Enum | Usage | Website | |:---------------------|---------------------------|-------------|--------------------------------------------------------------------------------------------------------------------| | `clp` | CLP_LINEAR_PROGRAMMING | Free-to-use | [https://github.com/coin-or/Clp](https://github.com/coin-or/Clp) | @@ -24,31 +25,35 @@ These are the solver names and enum, defined in the [OR-Tools API](https://githu [^1]: SIRIUS solver is only supported in [RTE's builds](https://github.com/rte-france/or-tools-rte/releases) of OR-Tools. ### Mixed real integer optimization -| OR-Tools solver name | Enum | Usage | Website | -|:---------------------|------------------------------------|-------------|------------------------------------------------------------------------------------------------------------| -| `scip` | SCIP_MIXED_INTEGER_PROGRAMMING | Free-to-use | [https://www.scipopt.org](https://www.scipopt.org) | -| `glpk` | GLPK_MIXED_INTEGER_PROGRAMMING | Free-to-use | [https://www.gnu.org/software/glpk](https://www.gnu.org/software/glpk) | -| `cbc` | CBC_MIXED_INTEGER_PROGRAMMING | Free-to-use | [https://github.com/coin-or/Cbc](https://github.com/coin-or/Cbc) | -| `highs` | HIGHS_MIXED_INTEGER_PROGRAMMING | Free-to-use | [https://highs.dev](https://highs.dev) | -| `sirius` [^1] | SIRIUS_MIXED_INTEGER_PROGRAMMING | Free-to-use | [https://github.com/rte-france/sirius-solver](https://github.com/rte-france/sirius-solver) | -| `gurobi` | GUROBI_MIXED_INTEGER_PROGRAMMING | Commercial | [https://www.gurobi.com](https://www.gurobi.com) | -| `cplex` | CPLEX_MIXED_INTEGER_PROGRAMMING | Commercial | [https://www.ibm.com/fr-fr/analytics/cplex-optimizer](https://www.ibm.com/fr-fr/analytics/cplex-optimizer) | -| `xpress` | XPRESS_MIXED_INTEGER_PROGRAMMING | Commercial | [https://www.fico.com/en/products/fico-xpress-solver](https://www.fico.com/en/products/fico-xpress-solver) | + +| OR-Tools solver name | Enum | Usage | Website | +|:---------------------|----------------------------------|-------------|------------------------------------------------------------------------------------------------------------| +| `scip` | SCIP_MIXED_INTEGER_PROGRAMMING | Free-to-use | [https://www.scipopt.org](https://www.scipopt.org) | +| `glpk` | GLPK_MIXED_INTEGER_PROGRAMMING | Free-to-use | [https://www.gnu.org/software/glpk](https://www.gnu.org/software/glpk) | +| `cbc` | CBC_MIXED_INTEGER_PROGRAMMING | Free-to-use | [https://github.com/coin-or/Cbc](https://github.com/coin-or/Cbc) | +| `highs` | HIGHS_MIXED_INTEGER_PROGRAMMING | Free-to-use | [https://highs.dev](https://highs.dev) | +| `gurobi` | GUROBI_MIXED_INTEGER_PROGRAMMING | Commercial | [https://www.gurobi.com](https://www.gurobi.com) | +| `cplex` | CPLEX_MIXED_INTEGER_PROGRAMMING | Commercial | [https://www.ibm.com/fr-fr/analytics/cplex-optimizer](https://www.ibm.com/fr-fr/analytics/cplex-optimizer) | +| `xpress` | XPRESS_MIXED_INTEGER_PROGRAMMING | Commercial | [https://www.fico.com/en/products/fico-xpress-solver](https://www.fico.com/en/products/fico-xpress-solver) | ### Constraint optimization -| OR-Tools solver name | Enum | Usage | Optimization type | -|:---------------------|-------------------------------------|-------------|-------------------| -| `bop` | BOP_INTEGER_PROGRAMMING | Free-to-use | Boolean | -| `sat` | SAT_INTEGER_PROGRAMMING | Free-to-use | Boolean integer | -| `knapsack` | KNAPSACK_MIXED_INTEGER_PROGRAMMING | Free-to-use | | + +| OR-Tools solver name | Enum | Usage | Optimization type | +|:---------------------|------------------------------------|-------------|-------------------| +| `bop` | BOP_INTEGER_PROGRAMMING | Free-to-use | Boolean | +| `sat` | SAT_INTEGER_PROGRAMMING | Free-to-use | Boolean integer | +| `knapsack` | KNAPSACK_MIXED_INTEGER_PROGRAMMING | Free-to-use | | ## Integration in Antares Simulator + *Antares Simulator* needs 2 types of solvers: + * A linear solver * A mixed real integer solver While the OR-Tools interface allows using multiple solvers, Antares restricts this usage. -The *Antares Simulator* user can select the solvers using the `ortools-solver` command-line option. Here are the allowed values: +The *Antares Simulator* user can select the solvers using the `ortools-solver` command-line option. Here are the allowed +values: | `ortools-solver` | Linear solver | Mixed real integer solver | |:-------------------|--------------------------------|----------------------------------| diff --git a/docs/index.md b/docs/index.md index 0a69f61b1b..19cce2d41e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -42,7 +42,7 @@ In May 2018, RTE decided to release the project under the GPLv3 license. In January 2024, RTE, as the exclusive copyright owner, decided to switch from the GPLv3 to the MPLv2 license, starting with the 9.0 version of Antares Simulator. -The GUI is deprecated in favor of [Antares Web](https://github.com/AntaresSimulatorTeam/AntaREST). +The GUI is deprecated in favor of [Antares Web](https://antares-web.readthedocs.io). ### Links - Antares ecosystem: [https://antares-doc.readthedocs.io](https://antares-doc.readthedocs.io) diff --git a/docs/pdf-doc-generation-with-sphinx/create_pdf_doc.sh b/docs/pdf-doc-generation-with-sphinx/create_pdf_doc.sh index 49ad7a10e1..a3f8a51f10 100644 --- a/docs/pdf-doc-generation-with-sphinx/create_pdf_doc.sh +++ b/docs/pdf-doc-generation-with-sphinx/create_pdf_doc.sh @@ -1,11 +1,11 @@ #!/bin/bash # copy reference guide md files and assets -cp -r ../reference-guide source/ +cp -r ../user-guide source/ cp -r ../assets/ source/ # change style for inline latex math \\( -> $ and \\) -> $ -find source/reference-guide/ -type f -name "*.md" -exec sed -i 's=\\\\)=$=g ; s=\\\\(=$=g' {} \; +find source/user-guide/ -type f -name "*.md" -exec sed -i 's=\\\\)=$=g ; s=\\\\(=$=g' {} \; # actually make the pdf sphinx-build -M latexpdf source build mv build/latex/antaressimulatoruserguide.pdf "./${1}" # clean -rm -rf source/reference-guide source/assets build +rm -rf source/user-guide source/assets build diff --git a/docs/pdf-doc-generation-with-sphinx/source/index.rst b/docs/pdf-doc-generation-with-sphinx/source/index.rst index cbe461bc64..f9409643d7 100644 --- a/docs/pdf-doc-generation-with-sphinx/source/index.rst +++ b/docs/pdf-doc-generation-with-sphinx/source/index.rst @@ -5,4 +5,4 @@ Welcome to Antares Simulator User Guide'! :maxdepth: 2 :caption: Contents - reference-guide/* + user-guide/00-index.md diff --git a/docs/reference-guide/01-introduction.md b/docs/reference-guide/01-introduction.md deleted file mode 100644 index 160ee6694f..0000000000 --- a/docs/reference-guide/01-introduction.md +++ /dev/null @@ -1,99 +0,0 @@ -# Introduction - -This document describes all the main features of the **Antares\_Simulator** package, version 8.6. - -It gives useful general information regarding the way data are handled and processed, -as well as how the Graphic User Interface (GUI) works. To keep this documentation -as compact as possible, many redundant details (how to mouse-select, etc.) are omitted. - -Real-life use of the software involves a learning curve process that cannot be supported by a -simple reference guide. In order to be able to address this basic issue, two kinds of resources may be used: - -- The examples' library, which is meant as a self-teaching way to learn how to use the software. -It is enhanced in parallel to the development of new features. -The content of this library may depend on the type of installation package it comes from -(general public or members of the users' club). - -- The [https://antares-simulator.org](https://antares-simulator.org/) website - -If you notice an issue in the documentation, please report it on [github.com](https://github.com/AntaresSimulatorTeam/Antares_Simulator/issues/new/choose). - -# General content of Antares\_Simulator sessions - -A typical **Antares\_Simulator** [^1] session involves different steps that are usually run in sequence, -either automatically or with some degree of man-in-the-loop control, depending on the kind of study to perform. - -These steps most often involve: - -1. GUI session dedicated to the initialization or to the updating of various input data sections -(time-series of many kinds, grid topology, generating fleet description, etc.) - -2. GUI session dedicated to the definition of simulation contexts -(definition of the number and consistency of the "Monte-Carlo years" to simulate) - -3. Simulation session producing actual numeric scenarios following the directives defined in (2) - -4. Optimization session aiming at solving all the optimization problems associated with -each of the scenarios produced in (3) - -5. GUI session dedicated to the exploitation of the detailed results yielded by (4) - -The scope of this document is to give a detailed description of the software involved in -step (1) to (5) mostly based on a functional approach, leaving thereby aside a significant -part of the mathematical content involved in several of these steps. -[^2] The following picture gives a functional view of all that is involved in steps (1) to (5). - -![Antares_Process](Antares_Process.png) - -The number and the size of the individual problems to solve (typically, a least-cost hydro-thermal power schedule and -unit commitment, with an hourly resolution and throughout a week, over a large interconnected system) make -optimization sessions often computer-intensive. - -Depending on user-defined results accuracy requirements, various practical options allow to simplify either -the formulation of the problems or their resolution. - -In terms of power studies, the different fields of application Antares has been designed for are the following: - -- **Generation adequacy problems:** -- **Transmission project profitability:** - -The common rationale of the modeling used in all of these studies is, whenever it is possible, -to decompose the general issue (representation of the system behavior throughout many years, -with a time step of one hour) into a series of standardized smaller problems. - -In Antares, the "elementary" optimization problem resulting from this approach is that of the minimization of -the overall system operation cost over a week, taking into account all proportional and -non-proportional generation costs, as well as transmission charges and "external" costs such as -that of the unsupplied energy (generation shortage) or, conversely, that of the spilled energy (generation excess). -In this light, carrying out generation adequacy studies or transmission projects studies means formulating and -solving a series of a great many week-long operation problems (one for each week of each Monte-Carlo year), -assumed to be independent to some extent (note that, however, issues such as the management of hydro resources –or -possibly other kinds of energy storage facilities– may bring a significant coupling between the successive problems, -which needs to be addressed properly). - -### Generation adequacy problems -Adequacy problems aim to study the need for new generating plants to keep the security of -supply above a given critical threshold. - -What is most important in these studies is to survey a great number of scenarios that represent well enough -the random factors that may affect the balance between load and generation. Economic parameters do not play -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" -simulation mode. - -### Transmission project profitability -Transmission project profitability studies the savings brought by a specific reinforcement of the grid, -in terms of decrease of the overall system generation cost (using an assumption of fair and perfect market) and/or -improvement of the security of supply (reduction of the loss-of-load expectation). - -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" simulation mode. - - - -[^1]: For simplicity's sake, the _**Antares\_Simulator**_ 8.6 application will as of now be simply denoted "Antares". - -[^2]: A detailed expression of the basic mathematical problem solved in the red box of the following figure can be found in the document "Optimization problems formulation". diff --git a/docs/reference-guide/02-data_organization.md b/docs/reference-guide/02-data_organization.md deleted file mode 100644 index b5be3e71e9..0000000000 --- a/docs/reference-guide/02-data_organization.md +++ /dev/null @@ -1,69 +0,0 @@ -# Data organization - -In Antares, all input and output data regarding a given study are located within a folder named after the study -and which should preferably be stored within a dedicated library of studies -(for instance: `C/.../A_name_for_an_Antares_lib/Study-number-one`). - -The software has been designed so that all input data may be handled (initialized, updated, deleted) through -the simulator's GUI. Likewise, all results in the output data can be displayed and analyzed within the simulator: -its standard GUI is actually meant to be able to provide, on a stand-alone basis, all the features required to access -input and output in a user-friendly way. - -In addition to that, the Antares simulator may come [^3] with or without functional extensions that provide additional -ways to handle input and output data. - -These extensions take the form of companion applications whose documentation is independent of that of the main simulator. -For information regarding these tools (*Antares Data Organizer*, *AntaresViz* R packages, …) please refer to -the specific relevant documents. - -Besides, a point of notice is that most of Antares files belong to either ".txt" or ".csv" type: -as an alternative to the standard GUI, they can therefore be viewed and updated by many applications -(Windows Notepad, Excel, etc.). However, this is not recommended since handling data this way may result in fatal -data corruption (e.g. as a consequence of accidental insertion of special characters). - -Direct access to input or output data files should therefore be reserved to experienced users. - -The input data contained in the study folder describe the whole state of development of the interconnected power system -(namely: grid, load and generating plants of every kind) for a given future year. - -As already stated, all of these data may be reviewed, updated, deleted through the GUI, whose commands and windows -are described in Sections 3 and 4. - -Once the input data is ready for calculation purposes, an Antares session may start and involve any or all of -the following steps: historical time-series analysis, stochastic times-series generation, -(full) adequacy simulation and economic simulation. - -The results of the session are stored within the output section of the study folder. -The results obtained in the different sessions are stored side by side and tagged. -The identification tag has two components: a user-defined session name and the time at which the session was launched. - -Particular cases are: - -1. The outputs of the Antares time-series analyzer are not printed in the general output files but kept within -the input files structure (the reason being that they are input data for the Antares time - series generators). -The associated data may nonetheless be accessed to be reviewed, updated and deleted at any time through the GUI. - -2. Some specific input data may be located outside the study folder: this is the case for the historical times-series -to be processed by the time-series analyzer, which may be stored either within the "user" subfolder of the -study or anywhere else (for instance, on a remote "historical data" or "Meteorological data" server). - -3. The study folder contains a specific subfolder named "user", whose status is particular: Antares is not allowed -to delete any files within it (yet files may be updated on the user's requirement). As a consequence, -the "user" subfolder is unaffected by the "clean study" command (see [Commands](03-commands.md)). -This subfolder is therefore a -"private" user space, where all kinds of information can be stored without any kind of interference with Antares. -Note that on using the "save as" command (described further below), the choice is given to make or not a copy of -this subfolder. - -4. The times-series analyzer requires the use of a temporary directory in which intermediate files are created -in the course of the analysis and deleted in the end, unless the user wishes to keep them for further examination. -Its location is user-defined and should usually be the "user" subfolder if files are to be kept, otherwise any -proper temporary space such as `C..../Temp`. - -5. The outputs of the Antares Kirchhoff's constraints generator are not printed in the general output files -but kept within the input files structure, the reason being that they are input data for the proper Antares simulation. -The associated data (so-called binding constraints bearing in their name the prefix "@UTO-") may nonetheless -be accessed to be reviewed, updated and deleted at any time through the GUI. - - -[^3]: Many various graphic extensions (under the form of programs written in the R language) are available at: [https://cran.r-project.org/web/packages/antaresViz/index.html](https://cran.r-project.org/web/packages/antaresViz/index.html) diff --git a/docs/reference-guide/03-commands.md b/docs/reference-guide/03-commands.md deleted file mode 100644 index 9b42c4d7fd..0000000000 --- a/docs/reference-guide/03-commands.md +++ /dev/null @@ -1,292 +0,0 @@ -# Commands - -The Antares GUI gives access to a general menu of commands whose name and meanings are described hereafter. - -## File - -- **New** Create a new empty study to be defined entirely from scratch (network topology, interconnections -ratings, thermal power plants list, fuel costs, hydro inflows stats, wind speed stats, load profiles ,etc.) - -- **Open** Load in memory data located in a specified Antares study folder. Once loaded, these data may be reviewed, -updated, deleted, and simulations may be performed. If "open" is performed while a study was already opened, the former study will be automatically closed. - -- **Quick Open** Same action as open, with a direct access to the recently opened studies - -- **Save** Save the current state of the study, if necessary by replacing original files by updated ones. -After using this command the original study is no longer available, though some original files may be kept until -the "clean" command is used (see "clean" command ) - -- **Save as** Save the current state of the study under a different name and / or location. -Using this command does not affect the original study. When "saving as", the user may choose whether -he/she prefers to save input and output data or only input data. Note that Antares does not perform "autosave": -Therefore, the actions performed on the input data during an Antares session (adding an interconnection, -removing a plant, etc.) will have no effect until either "save" or "save as" have been used - -- **Export Map** Save a picture of the current map as a PNG, JPEG or SVG file. Default background color and -storage location can be changed - -- **Open in Windows Explorer** Open the folder containing the study in a standard Windows Explorer window - -- **Clean** Remove all junk files that may remain in the study folder if the Antares session has involved lots -of sequences such as "create area – add plant –save –rename area – save - rename plant ..." -(Antares performs only low level auto-clean for the sake of GUI's efficiency) - -- **Close** Close the study folder. If no "save" or "save as" commands have been performed, -all the modifications made on the input data during the Antares session will be ignored - -- **Quit** Exit from Antares - -## Edit - -- **Copy** Prepare a copy of elements selected on the current system map. -The command is available only if the current active tab (whose name appears at the top line of the subcommand menu) -is actually that of the System maps. - -- **Paste** Paste elements previously prepared for copy. The command is available only if the current -active tab (whose name appears at the top line of the subcommand menu) is actually that of the System maps. -Note that copy/paste may be performed either within the same map or between two different maps, attached to -the same study or to different studies. To achieve that, launch one instance of Antares to open the "origin" study, -select elements on the map and perform copy, launch another instance of Antares to open the destination study, -perform paste. Copied elements are stored in an Antares clipboard that remains available for subsequent (multiple) -paste as long as the system map is used as active window. - -- **Paste Special** Same as Paste, with a comprehensive set of parameterized actions (skip, merge, update, import) -that can be defined for each data cluster copied in the clipboard. This gives a high level of flexibility for -carrying out complex copy/paste actions. - -- **Reverse** The elements currently selected on the system map are no longer selected and are replaced by -those not selected beforehand. - -- **Unselect All** Unselect all elements currently selected on the system map. - -- **Select All** Select all elements on the system map. - -## Input - -- **Name of the study** Give a reference name to the study. The default name is identical to that of -the study's folder but the user may modify it. The default name of a new study is "no title" - -- **Author(s)** Set the study's author(s) name. Default value is "memory" - -The other "input" subcommands here below are used to move from one active window to another. -Note that the availability of the __Wind__, __Solar__, and __Renewable__ subcommands depend on the advanced -parameter *"Renewable Generation modeling"* described in [miscellaneous](08-miscellaneous.md). - -- **System Maps** -- **Simulation** -- **User's Notes** -- **Load** -- **Solar** -- **Wind** -- **Renewable** -- **Hydro** -- **Thermal** -- **Misc. Gen.** -- **Reserves/DSM** -- **Links** -- **Binding constraints** -- **Economic opt.** - -## Output - -**\\** - -For each simulation run for which results have been generated, open a GUI for displaying results. -Results may be viewed by multiple selections made on a number of parameters. Note that, since all simulations do -not include all kinds of results (depending on user's choices), some parameters are not always visible. -Parameters stand as follows: - -- Antares area (node) -- Antares interconnection (link) -- Class of Monte-Carlo results : - - Monte-Carlo synthesis (throughout all years simulated) - - Year-by-Year (detailed results for one specific year) -- Category of Monte-Carlo results : - - General values (operating cost, generation breakdown, ...) - - Thermal plants (detailed thermal generation breakdown) - - Renewable generation (per cluster) - - Record years (for each Antares variable, identification of the Monte-Carlo year for which lowest and highest values were encountered) - -- Span of Monte-Carlo results : - - _Hourly_ - - _Daily_ - - _Weekly_ - - _Monthly_ - - _Annual_ - -The interface provides a user-friendly way for the comparison of results between multiple simulations -(e.g. "before" and "after" commissioning of a new plant or interconnection): - -- Use "new tab" button and choose a first set of simulation results -- Use again "new tab" and choose a second set of simulation results - -The results window will be automatically split so as to show the two series of results in parallel. -To the right of the "new tab" button, a symbolic (icon) button gives further means to compare results on a -split window (average, differences, minimum, maximum and sum). - -Besides, when the simulation results contain the "year-by-year" class, it is possible to carry out an -extraction query on any given specific variable (e.g. "monthly amounts of CO2 tons emitted") throughout -all available years of simulation. - -The results of such queries are automatically stored within the output file structures, so as to -be available at very short notice if they have to be examined later in another session (extractions may require -a significant computer time when there are many Monte-Carlo years to process). - -- **Open in Windows Explorer** This command displays the list of available simulation results and allows -browsing through the output files structure. The content of these files may be reviewed by tools such as Excel. -File structures are detailed in [Output Files](05-output_files.md). - -## Run - -- **Monte Carlo Simulation** Runs either an economy simulation or an adequacy simulation -depending on the values of the parameters set in the "simulation" active window (see [Simulation window](04-active_windows.md#simulation)). -If hardware resources and simulation settings allow it, simulations benefit from full multi-threading -(see [System requirements](09-system_requirements.md)) - -- **Time-series Generators** Runs any or all of the Antares stochastic time-series generators, -depending on the values of the parameters set in the "simulation" active window (see [Simulation window](04-active_windows.md#simulation)), and -each cluster's "Generate TS" parameter (see [Thermal window](04-active_windows.md#thermal)) - -- **Time-series Analyzer** Runs the Antares historical time-series analyzer. -The parameters of this module are defined by a specific active window, available only on launching the analyzer -(see [Time-series analysis and generation](06-time_series_analysis_and_generation.md)) - -- **Kirchhoff's Constraints Generator** Runs the Antares Kirchhoff's Constraints Generator. -The parameters of this module are defined by a specific active window, available only on launching the KCG -(see [Kirchhoff Constraints Generator](07-kirchhoffs_constraint_generator.md)) - -## Configure - -- **Thematic Trimming** Opens a window in which a choice can be made regarding the individual output status of -the variables defined in [Output Files](05-output_files.md). Each computed variable can either be stored as part of -the Output data to produce at the end of the simulation, or trimmed from it. In the latter case, the variable is regularly computed but the printing stage is skipped. Thematic Trimming does not reduce computation time but can bring some benefits on total runtime (smaller files to write). Thematic Trimming can save large amounts of storage space in simulations where only a handful of variables are of interest. - -- **Geographic Trimming** Opens an auxiliary window that allows multiple selection of the results to store at -the end of a simulation: Choice of areas, interconnections, temporal aggregations (hourly, daily, etc.). -Note that in addition to this feature, alternative access to the function is available -(see [Active windows](04-active_windows.md), "output profile"). Geographic Trimming does not reduce actual computation -time but can bring some benefits on total runtime (fewer files to write). Geographic Trimming can save large -amounts of storage space in simulations where only a few Areas and Links are of interest. - -- **Regional Districts** Allows selecting a set of areas to bundle them together in a "district". -These are used in the course of simulations to aggregate results over several areas. -They can be given almost any name (a "@" prefix is automatically added by Antares). -Bypassing the GUI is possible (see [Miscellaneous](08-miscellaneous.md)). - -- **MC Scenario builder** For each Monte-Carlo year of the simulation defined in the "Simulation" window, -this command allows to state, for each kind of time-series, whether it should be randomly drawn from -the available set (be it ready-made or Antares-generated) _**OR**_ should take a user-defined value -(in the former case, the default "rand" value should be kept; in the latter, the value should be the reference number of the time-series to use). Multiple simulation profiles can be defined and archived. The default active profile gives the "rand" status for all time-series in all areas (full probabilistic simulation). - - Regarding Hydro time-series, the scenario builder gives, in addition to the assignment of a specific number to use for the inflows time-series, the ability to define the initial reservoir level to use for each MC year, also hydro max power scenario builder is available to support time-series for Maximum Generation and Maximum Pumping because the number of TS's for ROR, Hydro Storage and Minimum Generation can be different than the number of TS's for Maximum Generation and Maximum Pumping. - -- **MC Scenario playlist** For each Monte-Carlo year of the simulation defined in the "Simulation" active window, -this command allows to state whether a MC year prepared for the simulation should be actually simulated or not. -This feature allows, for instance, to refine a previous simulation by excluding a small number of "raw" MC years -whose detailed analysis may have shown that they were not physically realistic. A different typical use 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” $W_i$ in the simulation (default value: 1). The expectation and standard deviation of all random variables will then be computed as if the scenarios simulated were sampled from a probability density function in which MC year i is given the probability - - $$\frac{W_{i}}{\sum_{j=1,...,N}{W_{j}}}$$ - -- **Optimization preferences** Defines a set of options related to the optimization core used in the simulations. -The set of preferences is study-specific; it can be changed at any time and saved along with study data. -Options refer to objects (binding constraints, etc.) that are presented in subsequent sections of this document. -The values set in this menu overlay the local parameters but do not change their value: for instance, if the LOCAL -parameter "set to infinite" is activated for some interconnections, and if the GLOBAL preference regarding transmission -capacities is "set to null", the simulation will be carried out as if there were no longer any grid BUT the local -values will remain untouched. If the preference is afterwards set to "local values", the interconnections will be -given back their regular capacities (infinite for those being set on "set to infinite"). - - - _Binding constraints (include / ignore)_ - - _Hurdle costs (include / ignore)_ - - _Transmission capacities (local values / set to null / set to infinite)_ - - _Min Up/down time of thermal plants (include / ignore)_ - - _Day-ahead reserve (include / ignore)_ - - _Primary reserve (include / ignore)_ - - _Strategic reserve (include / ignore)_ - - _Spinning reserve (include / ignore)_ - - _Export mps (false/true)_ - - _Simplex optimization range [^4] (day / week)_ - - _Unfeasible problems behavior (Error Dry/ Error Verbose/ Warning Dry/ Warning Verbose_ - -- **Adequacy Patch** Auxiliary window [Options] Defines a set of options related to the adequacy patch. -The set of preferences is study-specific; it can be changed at any time and saved along with study data. -Auxiliary window [Areas] Opens a window in which a choice can be made regarding the individual area adequacy patch mode. - -- _Enable Adequacy patch (false / true)_ -- _NTC from physical areas outside to physical areas inside adequacy patch (set to null / local values)_ -- _NTC between physical areas outside adequacy patch (set to null / local values)_ -- _Price taking order (DENS / Load)_ -- _Include hurdle cost in CSR optimization (false / true)_ -- _Check CSR cost function value prior and after CSR (false / true)_ -- _Thresholds:_ - - _Initiate curtailment sharing rule_ - - _Display local maching rule violations_ - - _Relax CSR variable boundaries_ - -- **Advanced parameters** Advanced Parameters allow to adjust the simulation behavior regarding issues -that are more numerical than physical. The set of parameters is study-specific and can be updated at any time. - - - Seeds for random number generation - - Time-series draws (MC scenario builder) - - Wind time-series generation - - Solar time-series generation - - Hydro time - series generation - - Load time - series generation - - Thermal time-series generation - - Noise on thermal plants costs - - Noise on unsupplied energy costs - - Noise on spilled energy costs - - Noise on virtual hydro cost - - Initial hydro reservoir levels - - Spatial time-series correlation - - Numeric Quality : load `[standard | high]` - - Numeric Quality : wind `[standard | high]` - - Numeric Quality : solar `[standard | high]` - - Other preferences - - Reservoir Level Initialization `[cold start | hot start]` - - Hydro Heuristic policy `[accomodate rule curves | maximize generation]` - - Hydro Pricing mode `[fast|accurate]` - - Power fluctuations `[free modulations | minimize excursions | minimize ramping]` - - Shedding policy `[shave peaks | minimize duration]` - - District marginal prices : `[average | weighed]` - - Day-ahead reserve management `[global | local]` - - Unit commitment mode `[fast | accurate]` - - Simulation cores `[minimum | low | medium | high | maximum]` - - Renewable Generation modeling `[aggregated | cluster]` - -## Tools - -- **Study manager** Launches the "study manager" external package (Please refer to dedicated documentation -for this package) - -- **Resources monitor** Indicates the amounts of RAM and disk space currently used and those required for a simulation -in the available modes (see [System requirements](09-system_requirements.md)). -Note that the "disk requirement" amount does not include the footprint of the specific "mps" files that may have -to be written aside from the regular output (see previous § "optimization preferences"). -Besides, the resources monitor shows the number of CPU cores available on the machine Antares is running on. - -- **Configure the temporary folder** Defines the location that will be used by Antares to store the temporary files of -the MC simulators. This location is used behind the scene by some Antares Simulator components (for instance scenario -builder or time-series analyzer). The default setting is the system temporary folder. - -## Window - -- **Toggle full window** Uses the whole window for display - -- **Inspector** Opens a window that gives general information on the study and allow quick browsing -through various area- or interconnection-related parameters. The Inspector window displays the content of the -Antares clipboard, e.g. areas and interconnections selected on the current study map. If the "Geographic Trimming" -option of the general simulation dashboard has the value "custom", the filtering parameters can be defined within -the Inspector window. Besides, areas currently selected, displayed in the Inspector window, -can be bundled into an "output district" by using the Configure/district command previously described - -- **Log viewer** Displays the log files regarding every Antares session performed on the study - - -[^4]:_Weekly optimization performs a more refined unit commitment, especially when the level selected in the "advanced parameters" menu is "accurate"._ - - diff --git a/docs/reference-guide/04-active_windows.md b/docs/reference-guide/04-active_windows.md deleted file mode 100644 index 40abdc3574..0000000000 --- a/docs/reference-guide/04-active_windows.md +++ /dev/null @@ -1,848 +0,0 @@ - -# Active windows - -Data can be reviewed, updated, deleted by selecting different possible active windows whose list and content -are described hereafter. On launching Antares, the default active window is "System Maps". - -__DISCLAIMER: this section sometimes refers to the original interfaces of Antares-Simulator, which are deprecated. Please refer to the [AntaresWeb online documentation](https://antares-web.readthedocs.io/en/latest/) for the description of the current interface.__ - -## System Maps - -This window is used to define the general structure of the system, i.e. the list of areas and that of the interconnections. Only the area's names, location and the topology of the grid are defined at this stage. Different colors may be assigned to different areas. These colors may later be used as sorting options in most windows. They are useful to edit data in a fashion that has a geographic meaning (which the lexicographic order may not have). This window displays copy/paste/select all icons equivalent to the relevant EDIT menu commands. - -The top left side of the window shows a "mouse status" field with three icons. These icons (one for nodes, one for links and one for binding constraints) indicate whether a selection made on the map with the mouse will involve or not the related elements. When a copy/paste action is considered, this allows for instance to copy any combination of nodes, links and binding constraints. Status can be changed by toggling the icons. Default is "on" for the three icons. Two 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 Reference Guide". - -## Simulation - -The main simulation window is divided up in two parts. On the left side are the general parameters while the right side is devoted to the time-series management. - -These two parts are detailed hereafter. - -### LEFT PART: General parameters - -- **Simulation** - - - _Mode:_ Economy, Adequacy [^5] - - _First day:_ First day of the simulation (e.g. 8 for a simulation beginning on the second week of the first - month of the year) - - _Last day:_ Last day of the simulation (e.g. 28 for a simulation ending on the fourth week of the first month - of the year) [^6] - -- **Calendar** - - - _Horizon:_ Reference year (static tag, not used in the calculations) - - - _Year:_ Actual month by which the Time-series begin (Jan to Dec, Oct to Sep, etc.) - - - _Leap Year:_ (Yes/No) indicates whether February has 28 or 29 days - - - _Week:_ In economy or adequacy simulations, indicates the frame (Mon- Sun, Sat-Fri, etc.) to use for - the edition of weekly results - - - _1st January:_ First day of the year (Mon, Tue, etc.) - -- **Monte-Carlo scenarios** - - - _Number:_ Number of MC years that should be prepared for the simulation (not always the same as the - Number of MC years actually simulated, see "selection mode" below) - - - _Building mode_: - - **Automatic** For all years to simulate, all time-series will be drawn at random - - **Custom** The simulation will be carried out on a mix of deterministic and probabilistic conditions, - with some time-series randomly drawn and others set to user-defined values. This option allows setting - up detailed "what if" simulations that may help to understand the phenomena at work and quantify various kinds of risk indicators. To set up the simulation profile, choose in the main menu: Configure/ MC scenario builder - - **Derated** All time-series will be replaced by their general average and the number of MC years - is set to 1. If the TS are ready-made or Antares-generated but are not to be stored in the INPUT folder, - no time-series will be written over the original ones (if any). If the time-series are built by Antares - and if it is specified that they should be stored in the INPUT, a single average-out time series will be stored - instead of the whole set. - - - _Selection mode_: - - **Automatic** All prepared MC years will actually be simulated. - - - **Custom** The years to simulate are defined in a list. To set up this list, choose in the main menu: - Configure/ MC scenario playlist [^7]. - -- **Output profile** - - - Simulation synthesis: - - **True** Synthetic results will be stored in a directory: - `Study_name/OUTPUT/simu_tag/Economy/mc-all` - - **False** No general synthesis will be printed out - - - Year-by-Year: - - **False** No individual results will be printed out - - **True** For each simulated year, detailed results will be printed out in an individual directory: - `Study_name/OUTPUT/simu_tag/Economy/mc-i-number - - - Geographic Trimming: - - **None** Storage of results for all areas, geographic districts, interconnections as well as all time spans - (hourly, daily, etc.) - - **Custom** Storage of the results selected with the "Geographic Trimming" command of the "Configure" - option available in the main menu. - Filters on areas, interconnections and time spans may also be defined as follows: - - On the map, select area(s) and/or interconnection(s) - - Open the inspector module (Main menu, Windows) - - Set adequate parameters in the "output print status" group - - - Thematic Trimming: - - **None** Storage, for the geographic selection defined previously, - of all variables defined in [Output Files](05-output_files.md) for Areas and Links. - - **Custom** Storage, for the geographic selection defined previously, of the variables selected with - the "Thematic Trimming" command of the "Configure" option available in the main menu. - - - MC Scenarios: - - **False** No storage of the time-series numbers (either randomly drawn or user-defined) used to - set up the simulation - - **True** A specific OUTPUT folder will be created to store all the time-series numbers drawn when - - preparing the MC years. - -### RIGHT PART: Time-series management - -For the different kinds of time-series that Antares manages in a non-deterministic way (load, thermal generation, hydro power, hydro max power, wind power, solar power or renewable depending on the option chosen): - -1. **Choice of the kind of time-series to use** -Either « ready-made » or «stochastic » (i.e. Antares-generated), defined by setting the value to either "on" or "off". Exception is hydro max power that can only be « ready-made ». Note that for Thermal time-series, the cluster-wise parameter may overrule this global parameter (see Thermal window description below). - -2. **For stochastic TS only**: - - **Number** Number of TS to generate - - - **Refresh** (Yes /No) ndicates whether a periodic renewal of TS should be performed or not - - - **Refresh span** Number of MC years at the end of which the renewal will be performed (if so required) - - - **Seasonal correlation** ("monthly" or "annual") Indicates whether the spatial correlation matrices to use are defined month by month or if a single annual matrix for the whole year should rather be used (see [Time-series analysis and generation](06-time_series_analysis_and_generation.md)) - - - **Store in input** - - **Yes** the generated time-series will be stored in the INPUT in replacement of the original ones (wherever they may come from) - - No: the original time-series will be kept as they were - - - **Store in output** - - **Yes**: the generated times-series will be stored as part of the simulation results - - **No**: no storage of the generated time-series in the results directories - -3. **General rules for building up the MC years** - - **Intra-modal**: - - **Yes** For each mode, the same number should be used for all locations (or 1 where there is only one TS), but this number may differ from one mode to another. For instance, solar power TS = 12 for all areas, while wind power TS number = 7 for all areas. - - **No** Independent draws - - **Inter-modal**: - - **Yes** For all modes, the same number should be used but may depend on the location (for instance, solar and wind power TS = 3 for area 1, 8 for area 2, 4 for area 3, etc.) - - **No** Independent draws - -A full meteorological correlation (for each MC year, one single number for all modes and areas) is, from a theoretical standpoint, accessible by activating "intra-modal" and " inter-modal" for all but the "thermal" kind of time-series. The availability of an underlying comprehensive multi-dimensional Meteorological data base of ready-made time-series is the crux of the matter when it comes to using this configuration. - -## User's Notes - -A built-in notepad for recording comments regarding the study. Such comments typically help to track successive input data updates (upgrading such interconnection, removing such plant, etc.). Another simple use is to register what has been stored in the "user" subfolder and why. Such notes may prove useful to sort and interpret the results of multiple simulations carried out at different times on various configurations of the power system. - -## Load - -_[Documentation of the AntaresWeb interface for this section](https://antares-web.readthedocs.io/en/latest/user-guide/study/areas/02-load/)_ - -This window is used to handle all input data regarding load. In Antares load should include transmission losses. It should preferably not include the power absorbed by pumped storage power plants. If it does, the user should neither use the "PSP" array (see window "Misc. Gen") nor the explicit modeling of PSP plants - -The user may pick any area appearing in the list and is then given access to different tabs: - -- The "time-series" tab display the "ready-made" 8760-hour time-series available for simulation purposes. These data may come from any origin outside Antares, or be data formerly generated by the Antares time-series stochastic generator, stored as input data on the user's request. Different ways to update data are : - - - direct typing - - - copy/paste a selected field to/from the clipboard - - - load/save all the time-series from/to a file (usually located in the "user" subfolder) - - - Apply different functions (+,-, \*, /,etc.) to the existing (possibly filtered) values - (e.g. simulate a 2% growth rate by choosing "multiply-all-by-1.02") - - - Handle the whole (unfiltered) existing dataset to either - - - Change the number of columns (function name: resize) - - Adjust the values associated with the current first day of the year (function name: shift rows) - - Versatile "Filter" functions allow quick access to user-specified sections of data -(e.g. display only the load expected in the Wednesdays of January, at 09:00, for time-series #12 to #19). Hourly load is expressed in round numbers and in MW. If a smaller unit has to be used, the user should define accordingly ALL the data of the study (size of thermal plants, interconnection capacities, etc.) - - - _Note that:_ - - - _If the "intra-modal correlated draw" option has not been selected in the_ **simulation** _window, - MC adequacy or economy simulations can take place even if the number of time-series is not the same - in all areas (e.g. 2 , 5 , 1 , 45 ,...)_ - - _If the "intra-modal correlated draws" option has been selected in the_ **simulation** _window, - every area should have either one single time-series or the same given number (e.g. 25 , 25 , 1 , 25...)_ - - - The "spatial correlation" tab gives access to the inter-area correlation matrices that will be used - by the stochastic generator if it is activated. Different sub-tabs are available for the definition of 12 monthly - correlation matrices and of an overall annual correlation matrix. - A matrix A must meet three conditions to be a valid correlation matrix: - - $$\forall i,\ \forall j,\ {A_{ii} = 100; -100 \le A_{ij} \le 100}; A\ symmetric; A\ positive\ semi\mbox{-}definite$$ - - 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 sub-tabs whose content is presented in - [Time-series analysis and generation](06-time_series_analysis_and_generation.md). - - - The "digest" tab displays for all areas a short account of the local data - -## Thermal - -_[Documentation of the AntaresWeb interface for this section](https://antares-web.readthedocs.io/en/latest/user-guide/study/areas/03-thermals/)_ - -This window is used to handle all input data regarding thermal dispatchable power. - -The user may pick any area appearing in the area list and is then given access to the list of thermal plants -clusters defined for the area (e.g. "CCG 300 MW", "coal 600", etc.). Once a given cluster has been selected, -a choice can be made between different tabs: - -- The "time-series" tab displays the "ready-made" 8760-hour time-series available for simulation purposes. -These data may come from any origin outside Antares, or be data formerly generated by the Antares time-series -stochastic generator, stored as input data on the user's request. Different ways to update data are : - - - direct typing - - copy/paste a selected field to/from the clipboard - - load/save all the time-series from/to a file (usually located in the "user" subfolder) - - Apply different functions (+,-, \*, /,etc.) to the existing (possibly filtered) values (e.g. simulate a - 2% growth rate by choosing "multiply-all-by-1.02") - - Handle the whole (unfiltered) existing dataset to either - - - Change the number of columns (function name: resize) - - Adjust the values associated with the current first day of the year (function name: shift rows) - - Versatile "Filter" functions allow quick access to user-specified sections of data (e.g. display only -the generation expected on Sundays at midnight, for all time-series). - - Hourly thermal generation is expressed in round numbers and in MW. If a smaller unit has to be used, the user should define accordingly ALL the data of the study (Wind generation, interconnection capacities, load, hydro generation, solar, etc.) - - - _Note that:_ - - - _If the "intra-modal correlated draws" option has not been selected in the_ **simulation** _window, - MC adequacy or economy simulations can take place even if the number of time-series is not the same in all - areas (e.g. 2, 5, 1, 45,etc.)_ - - - _If the "intra-modal correlated draws" option has been selected in the_ **simulation** _window, - every area should have either one single time-series or the same given number (e.g. 25, 25, 1, 25, etc.). - Note that, unlike the other time-series (load, hydro, etc.), which depend on meteorological conditions and - are therefore inter-area-correlated, the thermal plants time-series should usually be considered as uncorrelated. - Using the "correlated draws" feature makes sense only in the event of having to play predefined scenarios - (outside regular MC scope)_ - - -- The "TS generator" tab is used to set the parameters of the stochastic generator. -These parameters are defined at the daily scale and are namely, for each day: the average duration of -forced outages (beginning on that day), the forced outage rate, the duration of planned outages (beginning on that day), -the planned outage rate, planned outages minimum and maximum numbers. -Durations are expressed in days and rates belong to [0 , 1]. - - -- The "Common" tab is used to define the cluster's techno-economic characteristics : - - - Name - - Fuel used - - Location (Area) - - Activity status - - false: not yet commissioned, moth-balled, etc. - - true : the plant may generate - - Number of units - - Nominal capacity - - Full Must-run status - - false: above a partial "must-run level" (that may exist or not, see infra) plants - will be dispatched on the basis of their market bids. - - true: plants will generate at their maximum capacity, regardless of market conditions - - Minimum stable power (MW) - - Minimum Up time (hours) - - Minimum Down time (hours) - - Default contribution to the spinning reserve (% of nominal capacity) - - tons of different pollutant types (CO2, SO2, etc.) emitted per electric MWh - - 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)](06-time_series_analysis_and_generation.md#time-series-generation-thermal) - - Volatility (planned): a parameter between 0 and 1, see section [Time-series generation (thermal)](06-time_series_analysis_and_generation.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: - - Force generation: TS for this cluster will be generated - - Force no generation: TS for this cluster will not be generated - - Use global parameter: Will use the parameter for the study (the one in the [Simulation Window](#simulation)). - - Fixed cost (No-Load heat cost) (€ / hour of operation ) - - Start-up cost (€/start-up) - - Market bid (€/MWh) - - Random spread on the market bid (€/MWh) - - Variable Operation&Maintenance cost (€/MWh, only used if **Cost generation** is set to **use cost timeseries**) - - Seasonal marginal cost variations (gas more expensive in winter, ...) - - Seasonal market bid modulations (assets costs charging strategy ) - - Nominal capacity modulations (seasonal thermodynamic efficiencies, special over-generation allowances, etc.). These modulations are taken into account during the generation of available power time-series - - Minimal generation commitment (partial must-run level) set for the cluster - - - _Note that:_ - - - _The **optimal dispatch plan** as well as **locational marginal prices** are based on **market bids**, - while the assessment of the **operating costs** associated with this optimum are based on **cost parameters**. - (In standard "perfect" market modeling, there is no difference of approaches because market - bids are equal to marginal costs)_ - - - _Note that:_ - - - _If `Cost generation` is set to `Set manually` Marginal and Market bid costs (€/MWh) are specified directly in `Common` tab and have the same value for all time-series and hours._ - - _If `Cost generation` is set to `Use cost timeseries` Marginal and Market bid costs (€/MWh) are calculated separately for all the time-series and hours using the following equation:_ - _Marginal_Cost[€/MWh] = Market_Bid_Cost[€/MWh] = (Fuel_Cost[€/GJ] * 3.6 * 100 / Efficiency[%]) + CO2_emission_factor[tons/MWh] * C02_cost[€/tons] + Variable_O&M_cost[€/MWh]_ - _where Efficiency[%], CO2_emission_factor[tons/MWh] and Variable_O&M_cost[€/MWh] are specified in the `Common` tab under operating costs and parameters, while Fuel_Cost[€/GJ] and C02_cost[€/tons] are provided as time-series in separate tabs._ - - -## Storages - -_[Documentation of the AntaresWeb interface for this section](https://antares-web.readthedocs.io/en/latest/user-guide/study/areas/08-st-storages/)_ - -This window is used to create and edit short-term storage objects. An individual short-term storage component is defined as an object with the following characteristics: - -- Storage managed with a filling level which is identical at the start and end of each Antares optimization window; -- Rule curves that frame permissible storage levels hour by hour - the admissible range is a coefficient comprised between 0 and 1; -- Time-series of hourly modulation of the maximum injection and withdrawal power; -- Time-series of natural inflows (case of an open-cycle PSP). - -The user may pick any area appearing in the area list and is then given access to the list of short-term storages defined for the area. Once a given storage has been selected, the following characteristics can be set: - -- General characteristics of the storage: - - Name - - Group: the type of storage, based on a predefined list of storages ("PSP_open", "PSP_closed", "Pondage", "Battery", "Other1", "Other2", ..., "Other5") - - Withdrawal (MW): the maximum withdrawal power for the storage - withdrawal refers to the flow from the storage to the power system - - Injection (MW): the maximum injection power for the storage - withdrawal refers to the flow from the power system to the storage - - Stock (MWh): the capacity of the storage in MWh - - Efficiency (%): the energy efficiency of the storage, i.e. the ratio for a given volume between the energy taken from the system to be injected into the storage and the energy returned to the system during its withdrawal. This efficiency factor is applied when injecting energy into the storage. - - Initial level (%): the imposed initial filling rate of the storage at the beginning of each optimisation period. - - Initial level optimal: if the parameter is activated, the "Initial level" parameter is ignored and the initial storage level is optimized by Antares for each optimization period to minimize its objective function. - _Note: setting this parameter to "True" implies that there is no guarantee that the initial storage level of week N is the same as the final storage level of week N-1. However, the final level of week N is always equal to the initial level of the same week N plus/minus the injections/withdrawals occuring at the last hour of week N._ - -- "Injections/withdrawal capacities": a hourly time-series of modulation factors of the injection and withdrawal capacity for each hour (between 0 and 1), reflecting a lower availability of the structures during certain periods. At a given hour, the overall injection/withdrawal capacities of the storage are the product of this modulation factor by the "Withdrawal" and "Injection" parameters in the General data. - -- "Rule curves": a hourly time-series of rule curves (between 0 and 1), which are the lower and upper limits of the storage level imposed at each hour. - -- "Inflows": a hourly time-series of inflows filling the storage (in MWh). The values can be negative, corresponding to withdrawals imposed on the storage for other uses. - -## Hydro - -_[Documentation of the AntaresWeb interface for this section](https://antares-web.readthedocs.io/en/latest/user-guide/study/areas/05-hydro/)_ - -This section of the AntaresWeb interface for this section is meant to handle all input data regarding hydro power, -as well as any other kind of energy storage system of any size (from a small battery to a large -conventional hydro-storage reservoir with or without pumping facilities, etc.): Hydro power being -historically the first and largest form of power storage, it stood to reason that it should play in -Antares the role of a "generic template" for all forms of storable power. This versatility, however, -comes at the price of a comparatively more complex data organization than for other objects, -which explains the comparatively long length of this chapter. - -In the main Window, the user may pick any area appearing in the list and is then given access to different tabs: - -- The "time-series" tab displays the "ready-made" time-series already available for simulation purposes. There are five categories of time-series (displayed in five different subtabs): the Run of River (ROR) time-series, the Storage power (SP) time-series, the Minimum Generation power, the Maximum Generation power and the Maximum Pumping Power. - - ROR time-series are defined at the hourly scale; each of the 8760 values represents the ROR power expected at a given hour, expressed in round number and in MW. The SP time-series are defined at the daily scale; each of the 365 values represents an overall SP energy expected in the day, expressed in round number and in MWh. These natural inflows are considered to be storable into a reservoir for later use. The Minimum Generation time-series are defined at the hourly scale; each of the 8760 values represents the Minimum Generation power expected at a given hour expressed in round number and in MW. The Maximum Generation time-series are defined at the hourly scale; each of the 8760 values represents the Maximum Generation power expected at a given hour expressed in round number and in MW. The Maximum Pumping time-series are defined at the hourly scale; each of the 8760 values represents the Maximum Pumping power expected at a given hour expressed in round number and in MW. - - ROR time-series and SP time-series may come from any origin outside Antares, or may have been formerly generated by the Antares time-series stochastic generator and stored as input data on the user's request. Minimum Generation, Maximum Generation and Maximum Pumping may come from any origin outside Antares, but they can not be generated by the Antares time-series stochastic generator. Different ways to update data are: - - - direct typing - - copy/paste a selected field to/from the clipboard - - load/save all the time-series from/to a file (usually located in the "user" subfolder) - - Apply different functions (+,-, \*, /,etc.) to the existing (possibly filtered) values - (e.g. simulate a 2% growth rate by choosing "multiply-all-by-1.02") - - Handle the whole (unfiltered) existing dataset to either - - - Change the number of columns (function name: resize) - - Adjust the values associated with the current first day of the year (function name: shift rows) - - - _Note that:_ - - - _For a given area, the number of ROR time-series, SP times-series and Minimum Generation **must** be identical_ - - _For a given area, the number of Maximum Generation and Maximum Pumping **must** be identical_ - - _If the "intra-modal correlated draws" option was not selected in the_ **simulation** _window, - MC adequacy or economy simulations can take place even if the number of hydro time-series is not the same - in all areas (e.g. 2 , 5 , 1 , 45 ,...)_ - - _If the "intra-modal correlated draws" option was selected in the_ **simulation** _window, every - area should have either one single time-series or the same given number (e.g. 25 , 25 , 1 , 25...)_ - - -- The "spatial correlation" tab gives access to an annual inter-area correlation matrix that will be used by the stochastic generator if it is activated. Correlations are expressed in percentages, hence to be valid this matrix must be symmetric, p.s.d, with a main diagonal of 100s and all terms lying between (-100 ,+100) - - -- The "Allocation" tab gives access to an annual inter-area allocation matrix A(i,j) that may be used during a heuristic hydro pre-allocation process, regardless of whether the stochastic time-series generator is used or not. This matrix describes the weights that are given to the loads of areas (i) in the definition of the monthly and weekly hydro storage generation profiles of areas (j). The way this is done in detailed in [Miscellaneous](08-miscellaneous.md). - - -- The "local data" tab is used to set up the parameters of the stochastic generator_ **AND** _to define techno-economic characteristics of the hydro system that are used in Economy and Adequacy optimizations. For the purpose of versatility (use of the hydro section to model storage facilities quite different in size and nature), this "local tab" is itself divided up into four different subtabs whose list follows and which are further described: - - - Inflow Structure - - Reservoir Levels and water value - - Daily Power and Energy Credits - - Management options - -**Inflow Structure** - -This tab contains all the local parameters used for the stochastic generation of hydro time-series. These are namely: - -- The expectations, standard deviations, minimum and maximum values of monthly energies (expressed in MWh), monthly shares of Run of River within the overall hydro monthly inflow. -- The average correlation between the energy of a month and that of the next month (inter-monthly correlation). -- The average daily pattern of inflows within each month. Each day is given a relative "weight" in the month. If all days are given the same weight, daily energy time-series will be obtained by dividing the monthly energy in equal days. If not, the ratio between two daily energies will be equal to that of the daily weights in the pattern array. - -Overall hydro energy is broken down into two parts: Run of River- ROR and storage -STOR - -ROR energy has to be used on the spot, as it belongs to the general "must-run" energy category. - -STOR energy can be stored for use at a later time. The way how stored energy may actually be used depends -on the options chosen in the "management options" Tab and of the values of the parameters defined in the other Tabs. - -**Reservoir Levels and Water Values** - -Reservoir levels (left side) - -On the left side are defined 365 values for the minimum, average and maximum levels set for the reservoir -at the beginning of each day, expressed in percentage of the overall reservoir volume. The lower and upper level -time-series form a pair of so-called lower and upper "reservoir rule curves" - -Depending on the set of parameters chosen in the "management options" Tab, these rule curves may be used in -different ways in the course of both heuristic seasonal hydro pre-allocation process and subsequent weekly -optimal hydro-thermal unit-commitment and dispatch process. - -Water values (right side) - -On the right side is a table of marginal values for the stored energy, which depends on the date (365 days) and -of the reservoir level (101 round percentage values ranging from 0% to 100%). These values may have different origins; -they theoretically should be obtained by a comprehensive (dual) stochastic dynamic programming study carried out over -the whole dataset and dealing simultaneously with all reservoirs. - -Depending on the set options chosen in the "management options" Tab, these values may be used or not in the course of -the weekly optimal hydro-thermal unit-commitment and dispatch process. - -**Daily Power and Energy Credits** - -Standard credits (Bottom part) - -The bottom part displays two daily time-series (365 values) defined for energy generation/storage -(hydro turbines or hydro pumps). Both arrays represents the maximum daily energy (either generated or stored). - -For the sake of clarity, maximum daily energies are expressed as a number of hours at maximum power and these values -are used along with the Maximum Generation and Maximum Pumping TS's to calculate daily mean energy. - -Credit modulation (Upper part) - -The upper part displays two level-dependent (101 round percentage values ranging from 0% to 100%) time-series -of modulation coefficients defined for either generating or storing (pumping). - -These modulations, which can take any positive value, may (depending on the options chosen in the management -options Tab) be used to increase (value >1) or to decrease (value <1) the standard credits defined previously -for the maximum daily power and energies. - -**Management Options** - -This Tab is a general dashboard for the definition of how storage units, whatever their size or nature, should be managed. -It includes 15 parameters (out of which 7 are booleans) presented hereafter: - -- "Follow load" (y|n): defines whether an "ideal" seasonal generation profile should somehow follow the load OR an -"ideal" seasonal generation profile should remain as close as possible to the natural inflows -(i.e. instant generation whenever possible) - -- "Inter-daily breakdown" and "Inter-monthly breakdown" : parameters used in the assessment, through a -heuristic process, of an "ideal" seasonal generation profile, if the use of such a profile is required -(the heuristic itself is presented in [Miscellaneous](08-miscellaneous.md)) - -- "Intra-daily modulation": parameter which represents, for the storage power, the maximum authorized value for -the ratio of the daily peak to the average power generated throughout the day. This parameter is meant to allow -simulating different hydro management strategies. Extreme cases are : 1 : generated power should be constant throughout -the day 24 : use of the whole daily energy in one single hour is allowed - -- "Reservoir management" `y|n`: defines whether the storage should be explicitly modeled or not. - - Choosing "No" implies that available data allow or require that, regardless of the reservoir characteristics: - - - The whole amount of STOR energy of each month MUST be used during this month (no long-term storage) - - - The actual daily generation should follow, during the month, an "ideal" profile defined by the heuristic defined in [Miscellaneous](08-miscellaneous.md) - - Choosing "Yes" implies that available data allow or require explicit modeling of the storage facility, -regardless of whether a pre-allocation heuristic is used or not. - -- "Reservoir capacity": size of the storage facility, in MWh - -- "Initialize reservoir level on the 1st of": date at which the reservoir level should be initialized by a random draw. The "initial level" is assumed to follow a "beta" variable with expectation "average level", upper bound U=max level, lower bound L= min level, standard deviation = (1/3) (U-L) - -- "Use Heuristic Target" (y|n): defines whether an "ideal" seasonal generation profile should be heuristically determined or not. - - Choosing "No" implies that available data allow or require that full confidence should be put in water values determined upstream (through [dual] stochastic dynamic programming) OR that there are no "natural inflows" to the storage facility (battery or PSP, etc.) - - Choosing "Yes" implies that available data allow or require the definition of an "ideal" generation profile, that can be used to complement –or replace– the economic signal given by water values AND that there are "natural inflows" on which a generation heuristic can be based. - -- "Power-to-Level modulations (y|n)": defines whether the standard maximum daily energy and power credit should be or not multiplied by level-dependent modulation coefficients. - -- "Hard bounds on rule curves (y|n)": states whether, beyond the preliminary heuristic stage (if any), lower and upper reservoir rule curves should still be taken into account as constraints in the hydro-thermal unit commitment and dispatch problems. - -- "Use leeway (y|n)", lower bound L, upper bound U: states whether the heuristic hydro ideal target (**HIT**) should be followed exactly or not. - - Choosing "No" implies that, in optimization problems, the hydro energy generated throughout the time interval will be subject to an equality constraint, which may include short-term pumping cycles independent of water value: sum{ 1,t,T} (hydro(t)) – sum{1,t,T} (r. pump(t))= **HIT* - - Choosing "Yes", with bounds L and U, implies that, in optimization problems, the hydro energy generated throughout the time span will be subject to inequality constraints: L_*__HIT__ _<=sum{1,t,T} (hydro(t)) <= U\*_**HIT* - - Independently, short- or long-term pumping may also take place if deemed profitable in the light of water values. - - - "Use Water Value (y|n)": states whether the energy taken from / stored into the reservoir should be given the reference value defined in the ad hoc table OR should be given a zero value. - - - "Pumping Efficiency Ratio": setting the value to r means that, for the purpose of storing 1 gravitational MWh, pumps will have to use (1/r) electrical MWh. - -## Wind - -_[Documentation of the AntaresWeb interface for this section](https://antares-web.readthedocs.io/en/latest/user-guide/study/areas/06-wind/)_ - -This window is used to handle all input data regarding Wind power. -This window is only accessible when the advanced parameter Renewable Generation modeling is set to "Aggregated". - -The user may pick any area appearing in the list and is then given access to different tabs: - -- The "time-series" tab display the "ready-made" 8760-hour time-series already available for simulation purposes. These data may come from any origin outside Antares, or be data formerly generated by the Antares time-series stochastic generator, stored as input data on user's request. Different ways to update data are : - - - direct typing - - copy/paste a selected field to/from the clipboard - - load/save all the time-series from/to a file (usually located in the "user" subfolder) - - Apply different functions (+,-, \*, /,etc.) to the existing (possibly filtered) values (e.g. simulate a 2% growth rate by choosing "multiply-all-by-1.02") - - Handle the whole (unfiltered) existing dataset to either - - Change the number of columns (function name: resize) - - Adjust the values associated with the current first day of the year (function name: shift rows) - - Versatile "Filter" functions allow quick access to user-specified sections of data (e.g. display only the wind generation expected between 17:00 and 21:00 in February, for time-series 1 to 100). - - Hourly wind generation is expressed in round numbers and in MW. If a smaller unit has to be used, the user should define accordingly ALL the data of the study (size of thermal plants, interconnection capacities, load, etc.) - - - _Note that:_ - - - _If the "intra-modal correlated draws" option has not been selected in the_ **simulation** _window, MC adequacy or economy simulations can take place even if the number of time-series is not the same in all areas (e.g. 2, 5, 1,45, ...)_ - - - _If the "intra-modal correlated draws" option has been selected in the_ **simulation** _window, every area should have either one single time-series or the same given number (e.g. 25, 25, 1, 25, ...)_ - -- The "spatial correlation" tab gives access to the inter-area correlation matrices that will be used by the stochastic generator if it is activated. Different sub-tabs are available for the definition of 12 monthly correlation matrices and an overall annual correlation matrix. - - A matrix A must meet three conditions to be a valid correlation matrix: - - $$\forall i,\ \forall j,\ {A_{ii} = 100; -100 \le A_{ij} \le 100}; A\ symmetric; A\ positive\ semi\mbox{-}definite$$ - - 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](06-time_series_analysis_and_generation.md). - -- The "digest" tab displays for all areas a short account of the local data - - -## Solar - -_[Documentation of the AntaresWeb interface for this section](https://antares-web.readthedocs.io/en/latest/user-guide/study/areas/07-solar/)_ - -This window is used to handle all input data regarding Solar power. Both thermal solar generation and PV solar generation are assumed to be bundled in this data section. -_This window is only accessible when the advanced parameter Renewable Generation modeling is set to "aggregated”._ - -The user may pick any area appearing in the list and is then given access to different tabs: - -- The "time-series" tab display the "ready-made" 8760-hour time-series available for simulation purposes. These data may come from any origin outside Antares, or be data formerly generated by the Antares time-series stochastic generator, stored as input data on the user's request. Different ways to update data are : - - - direct typing - - copy/paste a selected field to/from the clipboard - - load/save all the time-series from/to a file (usually located in the "user" subfolder) - - Apply different functions (+,-, \*, /,etc.) to the existing (possibly filtered) values (e.g. simulate a 2% growth rate by choosing "multiply-all-by-1.02") - - Handle the whole (unfiltered) existing dataset to either - - - Change the number of columns (function name: resize) - - Adjust the values associated with the current first day of the year (function name: shift rows) - - Versatile "Filter" functions allow quick access to user-specified sections of data (e.g. display only the solar power expected in August at noon, for all time-series). - - Hourly solar power is expressed in round numbers and in MW. If a smaller unit has to be used, the user should define accordingly ALL the data of the study (size of thermal plants, interconnection capacities, etc.) - - - _Note that:_ - - - _If the "intra-modal correlated draws" option was not selected in the_ **simulation** _window, MC adequacy or economy simulations can take place even if the number of time-series is not the same in all areas (e.g. 2 , 5 , 1 , 45 ,...)_ - - - _If the "intra-modal correlated draws" option was selected in the_ **simulation** _window, every area should have either one single time-series or the same given number (e.g. 25 , 25 , 1 , 25...)_ - -- The "spatial correlation" tab gives access to the inter-area correlation matrices that will be used by the stochastic generator if it is activated. Different sub-tabs are available for the definition of 12 monthly correlation matrices and of an overall annual correlation matrix. - - A matrix A must meet three conditions to be a valid correlation matrix: - - $$\forall i,\ \forall j,\ {A_{ii} = 100; -100 \le A_{ij} \le 100}; A\ symmetric; A\ positive\ semi\mbox{-}definite$$ - - 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](06-time_series_analysis_and_generation.md). - -- The "digest" tab displays for all areas a short account of the local data - - -## Renewable - -_[Documentation of the AntaresWeb interface for this section](https://antares-web.readthedocs.io/en/latest/user-guide/study/areas/04-renewables/)_ - -This window is used to handle all input data regarding renewable generation. -_This window is only accessible when the advanced parameter Renewable Generation modeling is set to "cluster” (default value)._ - -The user may pick any area appearing in the area list and is then given access to the list of renewable clusters defined for the area (e.g. "Onshore Wind Farm 200MW", "Solar Rooftop 50MW", etc.). Once a given cluster has been selected, a choice can be made between different tabs: - -- The "time-series" tab displays the "ready-made" 8760-hour time-series available for simulation purposes. These data may come from any origin outside Antares, or be data formerly generated by the Antares time-series stochastic generator, stored as input data on the user's request. Different ways to update data are : - - - direct typing - - copy/paste a selected field to/from the clipboard - - load/save all the time-series from/to a file (usually located in the "user" subfolder) - - Apply different functions (+,-, \*, /,etc.) to the existing (possibly filtered) values (e.g. simulate a 2% growth rate by choosing "multiply-all-by-1.02") - - Handle the whole (unfiltered) existing dataset to either - - - Change the number of columns (function name: resize) - - Adjust the values associated with the current first day of the year (function name: shift rows) - - Versatile "Filter" functions allow quick access to user-specified sections of data (e.g. display only the generation expected on Sundays at midnight, for all time-series). - - Hourly thermal generation is expressed in round numbers and in MW. If a smaller unit has to be used, the user should define accordingly ALL the data of the study (Wind generation, interconnection capacities, load, hydro generation, solar, etc.) - - - _Note that:_ - - - _If the "intra-modal correlated draws" option has not been selected in the_ **simulation** _window, MC adequacy or economy simulations can take place even if the number of time-series is not the same in all areas (e.g. 2, 5, 1, 45,etc.)_ - - - _If the "intra-modal correlated draws" option has been selected in the_ **simulation** _window, every area should have either one single time-series or the same given number (e.g. 25, 25, 1, 25, etc.). Note that, unlike the other time-series (load, hydro, etc.), which depend on meteorological conditions and are therefore inter-area-correlated, the thermal plants time-series should usually be considered as uncorrelated. Using the "correlated draws" feature makes sense only in the event of having to play predefined scenarios (outside regular MC scope)_ - - -- The "TS generator" tab is not accessible for this version. - - -- The "Common" tab is used to define the cluster's techno-economic characteristics : - - - Name - - Group: The group can be any one of the following: Wind Onshore, Wind Offshore, Solar Thermal, Solar PV, Solar Rooftop, Other RES 1, Other RES 2, Other RES 3, or Other RES 4. If not specified, the renewable cluster will be part of the group Other RES 1. - - Location (Area) - - Timeseries mode: - - Power generation means that the unit of the timeseries is in MW - - Production factor means that the unit of the timeseries is in p.u. (between 0 and 1, 1 meaning the full installed capacity) - - Activity status - - false: not yet commissioned, moth-balled, etc. - - true: the cluster may generate - - Number of units - - Nominal capacity (in MW per unit) - - -## Misc. Gen. - -_[Documentation of the AntaresWeb interface for this section](https://antares-web.readthedocs.io/en/latest/user-guide/study/areas/10-misc-gen/)_ - -This window is used to handle all input data regarding miscellaneous non dispatchable generation. - -On picking any area in the primary list, the user gets direct access to all data regarding the area, which amount to **8** ready-made 8760-hour time-series (expressed in MW): - -- CHP generation - -- Bio Mass generation - -- Bio-gas generation - -- Waste generation - -- Geothermal generation - -- Any other kind of non-dispatchable generation - -- A predefined time-series for the operation of Pumped Storage Power plants, if they are not explicitly modeled. A positive value is considered as an output (generating) to the grid, a negative value is an input (pumping) to the station. - - Note that the sum of the 8760 values must be negative, since the pumping to generating efficiency is lower than 1. The user may also use only the negative values (prescribed pumping), while transferring at the same time the matching generating credit on the regular hydro storage energy credit. - -- ROW balance: the balance with the rest of the world. A negative value is an export to ROW, a positive value is an import from ROW. These values acts as boundary conditions for the model. Different ways to update data are: - - - direct typing - - copy/paste a selected field to/from the clipboard - - load/save all the time-series from/to a file (usually located in the "user" subfolder) - - Apply different functions (+,-, \*, /,etc.) to the existing (possibly filtered) values (e.g. simulate a 2% growth rate by choosing "multiply-all-by-1.02") - - Handle the whole (unfiltered) existing dataset to either - - - Change the number of columns (function name: resize) - - Adjust the values associated with the current first day of the year (function name: shift rows) - -## Reserves / DSM - -_[Documentation of the AntaresWeb interface for this section](https://antares-web.readthedocs.io/en/latest/user-guide/study/areas/09-reserves/)_ - -This window is used to handle all input data regarding reserves and the potential of "smart" load management (when not modeled using "fake" thermal dispatchable plants). On picking any area in the primary list, the user gets direct access to all data regarding the area, which amount to **four** ready-made 8760-hour time-series (expressed in MW). Those reserves are available in either "adequacy" or "economy" simulations: - -- Day-ahead reserve: power accounted for in setting up the optimal unit-commitment and schedule of the following day(s), which must consider possible forecasting errors or last-minute incidents. If the optimization range is of one day, the reserve will be actually seen as "day-ahead". If the optimization range is of one week, the need for reserve will be interpreted as "week-ahead". (Adequacy and Economy simulations) - -- DSM: power (decrease or increase) to add to the load. A negative value is a load decrease, a positive value is a load increase. Note that an efficient demand side management scheme may result in a negative overall sum (All simulation modes). - -## Links - -This window is used to handle all input data regarding the interconnections. On picking any interconnection in the primary list, the user gets direct access to all data regarding the link, which are five annual parameters, a set of six ready-made 8760-hour time-series, and a flexible number of ready-made 8760-hour time-series corresponding to the capacities of the links. - -- The five parameters, used in economy or adequacy simulations are displayed in the "Parameters" and in the "Transmission capacities" tab. They are namely: - - - "Hurdle cost": set by the user to state whether (linear) transmission fees should be taken into account or not in economy and adequacy simulations - - "Transmission capacities": set by the user to state whether the capacities to consider are those indicated in 8760-hour arrays or if zero or infinite values should be used instead (actual values / set to zero / set to infinite) - - "Asset type": set by the user to state whether the link is either an AC component (subject to Kirchhoff's laws), a DC component, or another type of asset - - "Account for loop flows": set by the KCG [^9] to include (or not) passive loop flows in the formulation of the constraints enforcing Kirchhoff's laws - - "Account for PST": set by the KCG to include (or not) the settings of phase-shifting transformers in the formulation of the constraints enforcing Kirchhoff's laws - -- The "Parameters" tab displays six 8760-hour times-series, which are: - - - Hurdle cost direct: an upstream-to-downstream transmission fee, in €/MWh - - - Hurdle cost indirect: a downstream-to-upstream transmission fee, in €/MWh - - - Impedance: used in economy simulations to give a physical meaning to raw outputs, when no binding constraints have been defined to enforce Kirchhoff's laws (see "Output" section, variable "Flow Quad") OR used by the Kirchhoff's constraint generator to build up proper flow constraints (AC flow computed with the classical "DC approximation"). Since voltage levels are not explicitly defined and handled within Antares, all impedances are assumed to be scaled to some reference $ U_{ref} $ - - - 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](07-kirchhoffs_constraint_generator.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](07-kirchhoffs_constraint_generator.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} $ - - -- The "Transmission capacities" tab displays "ready-made" 8760-hour time-series already available for simulation purposes. -In this tab, the table "Direct" describes the upstream-to-downstream capacity, in MW, and the table "Indirect" describes the downstream-to-upstream capacity, in MW. - _Please note that Time-Series analysis and generation is not available for capacity Time-Series._ - Different ways to update data are : - - direct typing - - copy/paste a selected field to/from the clipboard - - load/save all the time-series from/to a file (usually located in the "user" subfolder) - - Apply different functions (+,-, *, /,etc.) to the existing (possibly filtered) values (e.g. simulate a 2% growth rate by choosing "multiply-all-by-1.02") - - Handle the whole (unfiltered) existing dataset to either: - - - Change the number of columns (function name: resize) - - Adjust the values associated with the current first day of the year (function name: shift rows) - - Versatile "Filter" functions allow quick access to user-specified sections of data (e.g. display only the generation expected on Sundays at midnight, for all time-series). - -- _Note that:_ - - - _For a given link, the number of Time-Series for the direct and indirect capacity must be equal. Otherwise, an issue will be raised when launching a simulation_ - - - _If the "intra-modal correlated draws" option was not selected in the_ **simulation** _window, MC adequacy or economy simulations can take place even if the number of time-series for direct/indirect capacity is not the same for all links (e.g. 2 , 5 , 1 , 45 ,...)_ - - - _If the "intra-modal correlated draws" option was selected in the_ **simulation** _window, every link should have either one single time-series for both the direct and indirect capacity, or the same given number of time-series (e.g. 25 , 25 , 1 , 25...)_ - -## Binding constraints - -This section of the AntaresWeb interface for this section is used to handle all data regarding special constraints that one may wish to include in the formulation of the optimization problems to solve. - -The set of tabs described hereafter provides for that purpose all the means required to define arbitrary linear constraints on any subset of continuous variables involved in the modeling of the power system. - -Since no limitation is set on the number and content of the constraints that may be defined that way, it is the user's sole responsibility to make sure that these so-called "binding constraints" are realistic and meaningful, be it from a technical or economic standpoint. - -A typical situation in which this feature proves useful is, for instance, encountered when data at hand regarding the grid include an estimate of the impedances of the interconnections. - -In such cases, assuming that: - -- $Z_l$ denotes the impedance of interconnections $l=1, L$ -- A preliminary study of the graph modeling the grid has shown that it can be described by a set of independent meshes $c=1, C$(cycle basis of the graph) - -Then the DC flow approximation may be implemented, for each time-step of the simulation, by a set of C binding constraints between AC flows $F_l$: - -$$ 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](07-kirchhoffs_constraint_generator.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]. - -More generally, Antares allows to define three categories of binding constraints between transmission flows and/or power generated from generating units: - -- "hourly" binding constraints, which are applied to instant power (transmitted and/or generated) - -- "daily" binding constraints, that are applied to daily energies. This class makes more sense for commercial modeling (say: imports and exports from/to such and such area should be comprised between such and such lower bound and upper bound). Daily binding constraints are also commonly used to model specific facilities, such as pumped storage units operated on a daily cycle - -- "weekly" binding constraints, that are applied to weekly energies. Like the previous ones, these constraints may be used to model commercial contracts or various phenomena, such as the operation of a pumped storage power plant operated on a weekly cycle. - -The Binding Constraints section of the AntaresWeb interface for this section involves six main tabs described hereafter: - -- **TAB "summary"** -Creation, edition or removal of a binding constraint. A binding constraint is here defined by four macroscopic attributes that can be set by the edit command: - - - Name (caption) - - Time-range (hourly, daily, weekly) - - Numerical type (equality, bounded above, below, on both sides) - - Status (active /enabled or inactive/disabled) - -- **TAB "weights"** -Definition of the coefficients given to each flow variable or generation variable in the formulation of the constraints. Two sub-tabs make it possible to handle the coefficients associated with transmission assets (links) and those associated with generation assets (thermal clusters). In both cases: - - - The lines of the tables show only the components (links or clusters) that are visible on the current map - - The columns of the tables show only the constraints that do not have non-zero weights attached to components that are nor visible on the current map - -- **TAB "offsets"** -Definition of the time-lag (in hours) assigned to each flow variable or generation variable in the formulation of the constraints. Two sub-tabs make it possible to handle the offsets associated with transmission assets (links) and those associated with generation assets (thermal clusters). In both cases: - - - The lines of the tables show only the components (links or clusters) that are visible on the current map - - The columns of the tables show only the constraints that do not have non-zero weights attached to components that are nor visible on the current map - -- **TAB "="** -Definition of the right-hand side of equality constraints. This RHS has either 8760 values (hourly constraints) or 365 values (daily or weekly constraints). Depending on the range actually chosen for the simplex optimization (see section **Configure** of the main menu), the weekly constraints RHS will either be represented by the sum of seven daily terms or by a set of seven daily terms (weekly constraint downgraded to daily status). - -- **TAB ">"** -Definition of the right-hand side of "bounded below" and "bounded on both sides" inequality constraints. This RHS has either 8760 values (hourly constraints) or 365 values (daily or weekly constraints). Depending on the range actually chosen for the simplex optimization (see section **Configure** of the main menu), the weekly constraints RHS will either be represented by the sum of seven daily terms or by a set of seven daily terms (weekly constraint downgraded to daily status). - -- **TAB "<"** -Definition of the right-hand side of "bounded above" and "bounded on both sides" inequality constraints. This RHS has either 8760 values (hourly constraints) or 365 values (daily or weekly constraints). Depending on the range actually chosen for the simplex optimization (see section **Configure** of the main menu), the weekly constraints RHS will either be represented by the sum of seven daily terms or by a set of seven daily terms (weekly constraint downgraded to daily status). - -_NOTE: The right-hand side of a binding constraint can be set to "inf" (for "bounded above" constraints) or "-inf" (for "bounded below" constraints) for any timestamp. In that case, the constraint will be ignored by the solver for this timestamp. Please note that it is the user's responsibility to ensure that these values are set in a consistent way._ - -**WARNING:** When some clusters are defined as being in must-run ("must-run" parameter set to "True"), these clusters are automatically removed from the binding constraints in order to avoid potential incompatibilities between these constraints and the power output imposed to the must-run clusters. The clusters which are removed from binding constraints are visible in the "Summary" tab, in which they are multiplied by N/As in the binding constraints. -In case a binding constraint only contains must-run clusters, it will be ignored in the simulation and subsequently identified as "Skipped" in the summary tab. -Please note that in the specific context of the adequacy simulation mode (in which all thermal clusters are considered as being fully must-run), **all thermal clusters will consequently be de-activated from the binding constraints**. This can lead to incorrect adequacy indicators in Antares studies containing binding constraints. - - -When defining binding constraints between (hourly) power, daily or weekly (energy) flows, special attention should be paid to potential conflicts between them or with the "basic" problem constraints. Lack of caution may result in situations for which the optimization has no solution. Consider for instance a case in which three variables X1, X2, X3 (whatever they physical meaning) are involved in the following binding constraints: - -$$X1 + X2 > 5$$ - -$$X2 < -3$$ - -$$X3 > 0$$ - -$$X1 + X3 < 7$$ - -These commitments are obviously impossible to meet and, if the economic simulator is run on a dataset including such a set of constraints, it will produce an infeasibility analysis that looks like the following. -``` -[solver][notic] Solver: Starting infeasibility analysis... -[solver][error] The following constraints are suspicious (first = most suspicious) -[solver][error] Hydro reservoir constraint at area 'Germany' at hour 124 -[solver][error] Hydro reservoir constraint at area 'Germany' at hour 128 -[solver][error] Hydro reservoir constraint at area 'Germany' at hour 137 -[solver][error] Hydro reservoir constraint at area 'Germany' at hour 140 -[solver][error] Hydro reservoir constraint at area 'Germany' at hour 133 -[solver][error] Hydro reservoir constraint at area 'Germany' at hour 139 -[solver][error] Hydro reservoir constraint at area 'Germany' at hour 136 -[solver][error] Hydro reservoir constraint at area 'Germany' at hour 130 -[solver][error] Hydro reservoir constraint at area 'Germany' at hour 142 -[solver][error] Hydro reservoir constraint at area 'Germany' at hour 123 -``` - -This report should help you identify constraints that generate infeasible linear optimization problems such what is presented above. - -The advanced preference "Unfeasible Problems Behavior" gives to the user the ability to choose between four different strategies regarding these situations. - -## Economic Opt. - -This window is used to set the value of a number of area-related parameters that, aside from the costs of each generating plant, define the optimal solution that Antares has to find in economic simulations. These parameters are namely, for each area of the system: - -- The value of the unsupplied energy (also commonly denoted Value Of Lost Load,VOLL) , in €/MWh. This value should usually be set much higher than the cost of the most expensive generating plant of the area - -- The random spread within which the nominal unsupplied energy value is assumed to vary - -- The value of the spilled energy, in € /MWh. This value reflects the specific penalty that should be added to the economic function for each wasted MWh, if any. Note that even if this value is set to zero no energy will be shed needlessly - -- The random spread within which the nominal unsupplied energy value is assumed to vary - -- Three parameters named "shedding status" and related to different kinds of generation. If the system cannot be balanced without shedding some generation, these parameters give control on how each kind of generation ("Non dispatchable power","Dispatchable hydropower" and "Other dispatchable generating plants") should contribute to the shedding. Depending on the value chosen for the status, the generation can or cannot be shed to find a solution to the load/generation balance problem. Note that enforcing a negative status for all types of plants may lead to simulations scenarios for which there are no mathematical solutions. - -On running the economic simulator, such situations produce an infeasibility diagnosis. - - -## Miscellaneous - -In all previous windows showing Input data, the content can be filtered so as to reflect only items that are associated with Areas and Links defined as "visible" in a particular map. In that regard, binding constraints are considered as visible if and only if all of their non-zero weight associated objects are visible on the map. - - -[^5]: "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" simulations are faster and require only technical input data. Their results are limited to adequacy indicators. - -[^6]: In Economy an Adequacy simulations, these should be chosen so as to make the simulation span a round number of weeks. If not, the simulation span will be truncated: for instance, (1, 365) will be interpreted as (1, 364), i.e. 52 weeks (the last day of the last month will not be simulated). - -[^7]: changing the number of MC years will reset the playlist to its default values - -[^9]: KCG : Kirchhoff's constraints generator (see section 7) - -[^10]: A typical case is given by the "Flow-Based" framework today implemented in a large portion of the European electricity market. diff --git a/docs/reference-guide/05-output_files.md b/docs/reference-guide/05-output_files.md deleted file mode 100644 index 54fea6acce..0000000000 --- a/docs/reference-guide/05-output_files.md +++ /dev/null @@ -1,213 +0,0 @@ -# Output files - -The general file organization is the same for Economy and Adequacy simulations. - -Economy and Adequacy results may be displayed in the GUI ( "Output" in main menu) - -**Economy:** - -| OUTPUT/Simu id/economy/mc-all/ | | | | -|----------------------------------|---------------|-----------------|---------------------------------------| -| |/grid/... | | contains a summary file "digest.txt" | -| |/areas/name/...| | contains area-related results | -| |/links / name/...| | contains interconnection-related results | -| |/mc-ind /year_number| | | -| | |/areas/name/...| contains area-related results| -| | |/links/name/...| contains interconnection-related results| - -_("mc-all" files contain synthetic results over all years, "year-number" files contain results for a single year)_ -_The variables present in each file are detailed in the following sections._ -_In "Economy" simulations, all variables have a techno-economic meaning._ - -**Adequacy:** - -| OUTPUT/Simu id/adequacy/mc-all/ | | | | -|----------------------------------|---------------|-----------------|---------------------------------------| -| |/grid/... | | contains a summary file "digest.txt" | -| |/areas/name/...| | contains area-related results | -| |/links / name/...| | contains interconnection-related results | -| |/mc-ind /year_number| | | -| | |/areas/name/...| contains area-related results| -| | |/links/name/...| contains interconnection-related results| - -_("mc-all" files contain synthetic results over all years, "year-number" files contain results for a single year)_ -_The variables present in each file bear exactly the same name as in Economy simulations but do not have the same values._ -_The only variables that have a techno-economic meaning are the "Adequacy" indicators (unsupplied energy,LOLD,LOLP)_ - -**IMPORTANT** Adequacy and Economy files look the same but their content are specific - -In "Economy" and "Adequacy" simulations, the optimization ignores the "primary" and "strategic" reserves (however, it may include the [other] spinning and day-ahead reserves, depending on the settings made in "optimization preferences"). - -In "Adequacy" simulations, all dispatchable thermal units are given the "must-run" status (hence, they will generate at Pmax, regardless of the demand). As a consequence the only variables that are actually meaningful are the adequacy indicators (unsupplied energy, LOLD,LOLP), that may depend on assumptions made regarding the economic values of Unsupplied and spilled energies, and on hurdle costs on interconnections. -In the specific case where binding constraints are present in the study, **all thermal clusters will consequently be de-activated from the binding constraints**. This can lead to incorrect adequacy indicators in Antares studies containing binding constraints in "Adequacy" simulations. - -As a consequence, both "Adequacy" and "Economy" simulations yield the same values for the adequacy indicators under the following conditions: if hurdle costs on interconnections are higher than the difference between the maximum VOLL and the minimum VOLL assigned to the different areas of the system, and if no binding constraint is altered due to the fact that they contain clusters in must-run. - -The files and their content are hereafter described. - -## Economy and Adequacy, area results [^11] - -**25** files resulting from the combination of the following attributes: -**[values | id | details | details-res | details-STstorage] X [hourly | daily | weekly | monthly | annual]** - -- The second attribute defines the time span over which the results are assessed: hourly detail, daily bundle, weekly bundle, monthly bundle, annual bundle. - -- The first attribute defines the nature of the results presented in the file : - -**Values** Values of different variables (price, load, overall generation issued from coal, etc.), the list of which is common to all areas of the interconnected system. Files of type "values" have therefore the same size for all areas. -These results appear under the label "general values" in the output GUI. - -**details** Values regarding the different dispatchable thermal generating plants of each area (e.g. "older 300 MW coal from the south coast"). The sizes of these files differ from one area to another. -These results appear under the label "thermal plants" in the output GUI. - -**details-res** Values regarding the different renewable clusters of each area. The sizes of these files differ from one area to another. -These results appear under the label "Ren. clusters" in the output GUI. - -**details-STstorage** Values regarding the different short-term storages of each area. The sizes of these files differ from one area to another. -These results appear under the label "ST storages" in the output GUI. - -**id** Identifier (number) of the Monte-Carlo years for which were observed the extreme values of the different variables presented in the « values » files -These results appear under the label "record years" in the output GUI - -The area files that belong to the "values" class display fields corresponding to the expectation, standard deviation, minimal and maximal values of the variables whose list is given hereafter. - -| variables | description | -|-----------|-------------| -| OV.COST | Overall cost = operating cost + unsupplied cost+ spilled cost+ hydro cost | -| OP.COST | Operating cost = Proportional costs + Non- proportional costs | -| MRG. PRICE | LMP : overall economic effect of a local 1MW load increase | -| CO2, NH3, SO2, ... EMIS. | Amount emitted by all dispatchable thermal plants for the following types of pollutants: CO2, SO2, NH3, NOX, PM2\_5, PM5, PM10, NMVOC, OP1, OP2, OP3, OP4, OP5 EMIS. | -| BALANCE | Overall Import/export balance of the area (positive value : export) | -| ROW BAL | Import/export with areas outside the modeled system (positive value: import) [^12] | -| PSP | User-defined settings for pumping and subsequent generating | -| MISC. NDG | Miscellaneous non dispatchable generation | -| LOAD | Demand (including DSM potential if relevant) | -| H.ROR | Hydro generation, Run-of-river share | -| WIND | Wind generation (only when using aggregated _Renewable generation modeling_)| -| SOLAR | Solar generation (thermal and PV) (only when using aggregated _Renewable generation modeling_)| -| NUCLEAR | Overall generation of nuclear clusters | -| LIGNITE | Overall generation of dispatchable thermal clusters burning brown coal | -| COAL | Overall generation of dispatchable thermal clusters burning hard coal | -| GAS | Overall generation of dispatchable thermal clusters burning gas | -| OIL | Overall generation of dispatchable thermal clusters using petroleum products | -| MIX.FUEL | Overall gen. of disp. thermal clusters using a mix of the previous fuels | -| MISC.DTG | Overall gen. of disp. thermal clusters using other fuels | -| MISC.DTG 2 | Overall gen. of disp. thermal clusters using other fuels | -| MISC.DTG 3 | Overall gen. of disp. thermal clusters using other fuels | -| MISC.DTG 4 | Overall gen. of disp. thermal clusters using other fuels | -| WIND OFFSHORE | Wind Offshore generation (only when using clustered _Renewable generation modeling_) | -| WIND ONSHORE | Wind Onshore generation (only when using clustered _Renewable generation modeling_) | -| SOLAR CONCRT. | Concentrated Solar Thermal generation (only when using clustered _Renewable generation modeling_) | -| SOLAR PV | Solar Photovoltaic generation (only when using clustered _Renewable generation modeling_) | -| SOLAR ROOFT | Rooftop Solar generation (only when using clustered _Renewable generation modeling_) | -| RENW. 1 | Overall generation of other Renewable clusters (only when using clustered _Renewable generation modeling_) | -| RENW. 2 | Overall generation of other Renewable clusters (only when using clustered _Renewable generation modeling_) | -| RENW. 3 | Overall generation of other Renewable clusters (only when using clustered _Renewable generation modeling_) | -| RENW. 4 | Overall generation of other Renewable clusters (only when using clustered _Renewable generation modeling_) | -| H.STOR | Power generated from energy storage units (typically: Hydro reservoir) | -| H.PUMP | Power absorbed by energy storage units (typically: PSP pumps consumption) | -| H.LEV | Energy level remaining in storage units (percentage of reservoir size) | -| H.INFL | External input to the energy storage units (typically: natural inflows) | -| H.OVFL | Wasted natural inflow overflowing from an already full energy storage unit | -| H.VAL | Marginal value of stored energy (typically: shadow water value) | -| H.COST | Expenses /Income brought by energy storage actions (H.STOR,H.PUMP) | -| UNSP. ENRG | Unsupplied energy: adequacy indicator (Expected Energy Not Served–EENS) | -| SPIL. ENRG | Spilled energy (energy produced that cannot be used and has to be wasted) | -| LOLD | Loss of load duration: adequacy indicator (length of shortfalls) | -| LOLP | Loss of Load probability: adequacy indicator (probability of at least one hour of shortfall within the considered period, without normalization by the duration of the considered period) | -| AVL. DTG | Available dispatchable thermal generation (sum of av. power over all plants) | -| DTG. MRG | Disp. Ther. Gen. (AVL DTG – sum of all dispatched thermal generation) | -| MAX. MRG | Maximum margin: operational margin obtained if the hydro storage energy of the week were used to maximise margins instead of minimizing costs | -| DENS | Domestic Energy Not Supplied: the difference between the local production capabilities of an area and its local load[^adqp] | -| LMR. VIOL | Local Matching Rule Violation after the Antares Simulation as defined by the adequacy patch[^adqp] | -| SPIL. ENRG. CSR | Spilled Energy after the Curtailment Sharing Rule step of the dequacy patch[^adqp] | -| _injection |Injection of energy from the area into each short-term storage group| -| _withdrawal |Withdrawal of energy from each short-term storage group into the area| -| _level |Average level of each short-term storage group| -| NP COST | Non-proportional costs of the dispatchable plants (start-up and fixed costs) | -| NODU | Number of Dispatched Units [^13] | -| Profit | Net profit of the cluster in euros ((MRG. PRICE - marginal cost of the cluster) * (dispatchable production of the cluster)[^15] | -| ,P-injection |Injection of energy from the area into the short-term storage| -| ,P-withdrawal |Withdrawal of energy the short-term storage into the area| -| ,Levels |Level of the short-term storage| - -_Note: The net profit is computed on full precision values for MRG. PRICE. The user may obtain slightly different results applying the given formula because MRG. PRICE values are rounded to 10^-2._ - -## Economy and Adequacy, interconnection results [^14] -**10** files resulting from the combination of the following attributes: -**[values | id] X [hourly | daily | weekly | monthly | annual]** - -- The second attribute defines the period of time over which the results are assessed: hourly detail, daily bundle, weekly bundle, monthly bundle, annual bundle. -- The first attribute defines the nature of the results presented in the file. - - -**values** values of different variables (flow, congestion rent) the list of which is common to all interconnections. The files of type "values" have therefore the same size everywhere -These results appear under the label "general values" in the output GUI. - -**id** identifier (number) of the Monte-Carlo years for which were observed the extreme values of the different variables presented in the « values » files. -These results appear under the label "record years" in the output GUI. - - -The area files that belong to the « values » class display **28** fields corresponding to the expectation, standard deviation, minimal and maximal values of the variables whose list is given hereafter. - -| variables | description | -|-----------|-------------| -| FLOW LIN. | Flow (signed + from upstream to downstream) assessed by the linear optimization. These flows follow Kirchhoff's law only if these laws have been explicitly enforced by the means of suitable binding constraints | -| UCAP | Used capacity: absolute value of FLOW LIN. This indicator may be of interest to differentiate the behavior of interconnectors showing low average flows: in some cases this may indicate that the line is little used, while in others this may be the outcome of high symmetric flows | -| LOOP FLOW | Flow circulating through the grid when all areas have a zero import/export balance. This flow, to be put down to the simplification of the real grid, is not subject to hurdle costs in the course of the optimization | -| FLOW QUAD. | Flow computed anew, starting from the linear optimum, by minimizing a quadratic function equivalent to an amount of Joule losses, while staying within the transmission capacity limits. This calculation uses for this purpose the impedances found in the "Links" Input data. If congestions occur on the grid, these results are not equivalent to those of a DC load flow| -| CONG. FEE ALG | Algebraic congestion rent = linear flow \* (downstream price – upstream price) | -| CONG. FEE ABS | Absolute congestion rent = linear flow\* abs(downstream price–upstream price) | -| MARG. COST | Decrease of the system's overall cost that would be brought by the optimal use of an additional 1 MW transmission capacity (in both directions) | -| CONG PROB + | Up>Dwn Congestion probability = (NC+) / (total number of MC years) with:
NC+ = number of years during which the interconnection was congested in the Up>Dwn way for **any** length of time within the time frame relevant with the file| -| CONG PROB - | Dwn>Up Congestion probability = (NC-) / (total number of MC years) with:
NC- = number of years during which the interconnection was congested in the Dwn>Up way for **any** length of time within the time frame relevant with the file| -| HURD. COST | Contribution of the flows to the overall economic function through the "hurdles costs" component. For each hour:
`if (FLOW.LIN –LOOP FLOW) > 0 `
`HURD. COST = (hourly direct hurdle cost) * (FLOW LIN.)`
`else HURD.COST = (hourly indirect hurdle cost) * (-1) * (FLOW LIN.)`| - -## Economy and Adequacy, other results - -Depending on the options chosen in the main simulation window, the output folders may also include either, both or none of the following sections: - -| OUTPUT/Simu id/ts-numbers/ | | | -|------------------------------|--------------------|--------------------------------| -| |/Load | /area names/... | -| |/Thermal | /area names/... | -| |/Hydro | /area names/... | -| |/Wind[^agg] | /area names/... | -| |/Solar[^agg] | /area names/... | -| |/Renewables[^ren] | /area names/... | -| |/NTC | /area names/... | - -These files contain, for each kind of time-series, the number drawn (randomly or not) in each Monte-Carlo year (files are present if "output profile / MC scenarios" was set to "true"). - -| OUTPUT/Simu id/ts-generator/ | | | -|------------------------------|--------------------|--------------------------------| -| |/Load | /batch number/area names/... | -| |/Hydro | /batch number/area names/... | -| |/Wind[^agg] | /batch number/area names/... | -| |/Solar[^agg] | /batch number/area names/... | - - -These files contain, for each kind of Antares-generated time-series, copies of the whole set of time-series generated. Batch numbers depend on the values set for the "refresh span" parameters of the stochastic generators (files are present if "store in output" was set to "true"). - -## Miscellaneous - -Alike Input data, output results can be filtered so as to include only items that are associated with Areas and Links defined as "visible" in the current map. In addition, the output filtering dialog box makes it possible to filter according to two special categories (**Districts** and **Unknown**) that are not related to standard maps: - -- **Districts** displays only results obtained for spatial aggregates -- **Unknown** displays only results attached to Areas or Links that no longer exist in the Input dataset (i.e. study has changed since the last simulation) - -[^11]: This description applies to both « MC synthesis » files and "Year-by-Year" files, with some simplifications in the latter case - -[^12]: Value identical to that defined under the same name in the "Misc Gen" input section. - -[^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](14-adequacy-patch.md)) - -[^14]: This description applies to both « MC synthesis » files and "Year-by-Year" files, with some simplifications in the latter case - -[^agg]: This output is only available if the parameter "renewable generation modelling" is set to "cluster" in the input of the simulation - -[^ren]: This output is only available if the parameter "renewable generation modelling" is set to "aggregated" in the input of the simulation - -[^15]: dispatchable production = power generation above min gen = (power generation) - (min gen modulation)*units*capacity diff --git a/docs/reference-guide/08-miscellaneous.md b/docs/reference-guide/08-miscellaneous.md deleted file mode 100644 index c76c3b25f9..0000000000 --- a/docs/reference-guide/08-miscellaneous.md +++ /dev/null @@ -1,559 +0,0 @@ -# Miscellaneous - -## 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_ | - - -## The heuristic for seasonal hydro pre-allocation - - -This heuristic, first introduced in broad terms in [Active windows](04-active_windows.md), chapter "hydro", is fully detailed in this paragraph. - -Basically, the seasonal hydro pre-allocation process comprises two stages carried out two times -(first time: monthly scale; second time: daily scale). - -- Stage 1: Definition of an allocation ideal modulation profile, which may be based (or not) on local and/or - remote load profiles. -- Stage 2: Mitigation of the previous raw profile to obtain a feasible hydro ideal target, - compatible as much as possible with reservoir rule curves. - -The description given hereafter makes use of the following local notations, -not be confused with those of the document "optimization problem formulation" -(dedicated to the optimal hydro-thermal unit-commitment and dispatch problem): - -- $Z$ Number of Areas (zones $z$) in the system -- $M_{zh}$ Hourly time-series of cumulated must-generation of all kinds for zone $z$ -- $M_{zd}$ Daily time-series of cumulated must-generation of all kinds for zone $z$ (sum of $M_{zh}$) -- $M_{zm}$ Monthly time-series of cumulated must-generation of all kinds for zone $z$ (sum of $M_{zh}$) -- $M_{z.}$ Either $M_{zd}$ or $M_{zm}$, relevant time index "." is defined by the context -- $L_{z.}$ Time-series of "natural" load for zone $z$ -- $A$ Inter-area hydro-allocation matrix (dimension_ $x Z$ ) $A_{uv}$ is a weight given to the load -of area $u$ in the definition of the monthly and daily primary hydro generation target of area $v$ - Extreme cases are: - - - **A is the identity matrix** - The hydro storage energy monthly and weekly profiles of each zone $z$ depend only on the local demand and - must-run generation in $z$ - - **A has a main diagonal of zeroes** - The hydro storage energy monthly and weekly profiles of each zone $z$ do not depend at all on the local - demand and must-run generation in $z$ -- $L_{z.}^+$ Time-series of "net" load for zone $z$, defined as: $L{z.}^+ = L{z.} - M{z.}$ -- $L_{z.}$ Time-series of "weighted" load for zone $z$, defined as:_ $L_{z.} = A^t L_{z.}^+$ - -All following parameters are related to the generic zone $z$: - -- $\alpha$ "inter-monthly generation breakdown" parameter - -- $\beta$ "inter-daily generation breakdown" parameter - -- $j$ "follow-load" parameter - -- $\mu$ "reservoir-management" parameter - -- $S$ Reservoir size - -- $\overline{S_d}$ Reservoir maximum level at the end of day d, expressed as a fraction of $S$ (rule curve) - -- $\underline{S_d}$ Reservoir minimum level at the end of day d, expressed as a fraction of $S$ (rule curve) - -- $S_0$ Reservoir initial level at the beginning of the first day of the "hydro-year" - -- $I_d$ Natural inflow of energy to the reservoir during day d - -- $I_m$ Natural inflow of energy to the reservoir during month m (sum of $I_d$ - -- $\overline{W_d}$ Maximum energy that can be generated on day d (standard credit) - - All following variables, defined for both stages, are related to the generic zone: - -- $S_d^k$ Reservoir level at the end of day d, at the end of stage k of pre-allocation - -- $S_m^k$ Reservoir level at the end of month m, at the end of stage k of pre-allocation - -- $O_d^k$ Overflow from the reservoir on day d, at the end of stage k of pre-allocation (inflow in excess to an already full reservoir) - -- $W_d^k$ Energy to generate on day d, at the end of stage k of pre-allocation - -- $W_m^k$ Energy to generate on month m, at the end of stage k of pre-allocation - - -Following variables and parameters are local to linear optimization problems $M$ & $D(m)$ -solved within the heuristic. For the sake of clarity, the same generic index is used for all time steps, -knowing that in $M$ there are 12 monthly time-steps, while in $D(m)t$ there are from 28 to 31 daily -time-steps. Costs $\gamma_{Var}$ given to these variables are chosen to enforce a logical hierarchy -of penalties (letting the reservoir overflow is worse than violating rule curves, which is worse than deviating -from the generation objective assessed in stage 1, etc.) - -- $Y$ Generation deficit at the end of the period, as compared to the objective aimed at - -- $O_t$ Overflow from the reservoir on time step $t$ - -- $G_t, \overline{G_t}$ Optimal generation and maximum generation on time step $t$ - -- $T_t$ Generation objective assessed in the first stage, for time step t ( $W_m^1$ or $W_d^1$) - -- $S_t, \overline{S_t}, \underline{S_t}$ Optimal stock level, maximum level, minimum level at the end of time step $t$ - -- $I_t$ Natural inflow on time step $t$ - -- $D_t$ Deviation (absolute difference) between target reached and initial aim - -- $\Delta$ Maximum deviation throughout the period - -- $V_t^+$ Amplitude of the violation of the upper rule curve at time step $t$ - -- $V_t^-$ Amplitude of the violation of the lower rule curve at time step $t$ - -- $Y$ Maximum violation of lower rule curve throughout the period - - -**General heuristic for each zone** - -_Begin_ - -$$if (not.\mu) : \{ S \leftarrow \infty ; \underline{S_d} \leftarrow 0; \overline{S_d}; S_0 \leftarrow S/2 \}$$ - -_M1:_ - -$$if (j \text{ and } \mu) : \text{for } m\in [1, 12]: W_m^1 \leftarrow \frac{L_m^{\alpha}.(\sum_{m}{I_m})}{(\sum_{m}{L_m^{\alpha}})}$$ - -$$else: \text{for } m\in [1, 12]: \{W_m^1 \leftarrow I_m\}$$ - - -_M2:_ - -$$\text{for } m\in [1, 12]: W_m^2 \leftarrow \text{Solution of linear problem M}$$ - -_D1:_ - -$$if (j): \text{for } d\in [1, 31]: W_d^1 \leftarrow \frac{L_d^{\beta}. (W_m^2)}{(\sum_{d\in m}{L_d^{\beta}})}$$ - -$$else: \text{for } d\in [1, 31]: W_d^1 \leftarrow \frac{I_d . (W_m^2)} {(\sum_{d\in m}{I_d})}$$ - -_D2:_ - -$$\text{for } m \in [1, 12]: W_{d\in m}^2 \leftarrow \text{Solution of linear problem D(m)}$$ - -_End_ - -Note: In the formulation of the optimal hydro-thermal unit-commitment and dispatch problem (see dedicated document), the reference hydro energy __HIT__ used to set the right hand sides of hydro- constraints depends on the value chosen for the optimization preference "simplex range" and is defined as follows: - -- Daily : for each day **d** of week $\omega$ : $HIT = W_d^2$ -- Weekly : for week $\omega$: $HIT = \sum_{d\in \omega}{W_d^2}$ - -**Optimization problem M** - -$$\min_{G_t, S_t, ...}{\gamma_{\Delta}\Delta + \gamma_Y Y + \sum_{t}{(\gamma_D D_t + \gamma_{V+} V_t^+ + \gamma_{V-} V_t^-)}}$$ - -s.t - -$$S_t \geq 0$$ - -$$S_t \leq S$$ - -$S_t + G_t - S_{t-1} = I_t$ (see note [^monthly_allocation]) - -$$\sum_{t}{G_t} = \sum_{t}{T_t}$$ - -$$G_t - D_t \leq T_t$$ - -$$G_t + D_t \geq T_t$$ - -$$V_t^- + S_t \geq \underline{S_t}$$ - -$$V_t^+ - S_t \geq -\overline{S_t}$$ - -$$Y - V_t^- \geq 0$$ - - -**Optimization problems $D(m)$** - -$$\min_{G_t, S_t, ...}{\gamma_{\Delta}\Delta + \gamma_Y Y + \sum_{t}{(\gamma_D D_t + \gamma_{V-} V_t^- + \gamma_{O} O_t + \gamma_S S_t)}}$$ -s.t - -$$S_t \geq 0$$ - -$$S_t \leq S$$ - -$$G_t \geq 0$$ - -$$G_t \leq \overline{G_t}$$ - -$S_t + G_t + O_t - S_{t-1} = I_t$ (see note [^daily_allocation]) - -$\sum_{t}{G_t + Y} = \sum_{t}{T_t} + Y_{m-1}$ (value of Y previously found in solving **$D(m-1)$**) - -$$G_t - D_t \leq T_t$$ - -$$G_t + D_t \geq T_t$$ - -$$\Delta - D_t \geq 0$$ - -$$V_t^- + S_t \geq \underline{S_t}$$ - -$$Y - V_t^- \geq 0$$ - -## Conventions regarding colors and names - -- Names for areas, thermal plants, etc. - Name length should not exceed 256 characters. - Characters must belong to: - { A-Z , a-z , 0-9 , - , \_ , ( , ) , & , comma , space } - - -- Colors: - After being entered in the GUI, some numeric fields can see their color change. The meaning of that is: - - Turn to red: invalid value. Saving the study in this state is possible, but the field will have to be corrected at some point in the future. Should the simulator be launched on the dataset, it will detect an error and stop. - - - Turn to orange: value is valid, though unusual (user may want to double-check data). - - -- Abbreviations : - - Fields requiring to be filled out with "YES" or "NO" can alternatively accept "Y" , "1" or "N" , "0" - - Fields requiring to be filled out with "ON" or " OFF" can alternatively accept "true", "1" or "false", "0" - - Fields requiring to be filled out with "annual" or "monthly" can alternatively accept "a" or "m" - - Fields requiring to be filled out with: "Raw" ,"Detrended"," Beta", "Normal", "Uniform", " Gamma", " Weibull" can alternatively accept: "R", "D", " B", "N", "U", "G", "W" - - -## Definition of regional districts - -Typical uses of the "district" feature are: - -1) On a large system, define an "all system" zone to get an overall synthesis on all the system nodes - -2) In a study involving different countries modeled by different regions, define "country" macro-nodes to aggregate regional results to the national level. - -3) In a study using some specific modeling such as PSP modeling with fake nodes, define a local cluster involving all the relevant real and fake nodes to simplify the edition of results. - -Hereafter is described the process to follow to bypass the GUI for the definition of districts.
-It is based on the edition of a special "sets.ini" file. - -**IMPORTANT :** -- 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** : Use Notepad (or equivalent) - -**WHERE TO FIND / STORE THE FILE** : INPUT/areas/sets.ini - -**PRINCIPLE:** - -The file is divided in consecutive sections, one for each district to define. - -A section contains: - -a) A header line that gives its name to the district. The header syntax is: `[district_name]` - To avoid confusion with the real area names, the results regarding this macro-area will later be found in the OUTPUT files under a name bearing the prefix "@", i.e. `@district_name` - -b) A list of parametrized building rules to be processed in their apparition order. - The different elementary rules are: - += area\_name : add the area "area\_name" to the district
- -= area\_name : remove the area "area\_name" from the district
- apply-filter = add-all : add all areas to the district
- apply-filter = remove-all : remove all areas (clear the district) - -c) A special "output" parameter that defines whether the results for the district will actually be computed or not -(this latter option allows inactivating parts of the sets.ini without altering the file). - The syntax is: `output=false` or `output= true`. - -**EXAMPLES OF SETS.INI FILES** - -a) File defining a single district named "set1" involving three areas named "area1, area3, area42": - -```ini -[set1] -+ = area1 -+ = area3
-+ = area42 -output = true -``` - -b) File defining a district gathering all areas but five: - -```ini -[most of the system] -apply-filter = add-al -- = country -- = neighbour -- = fake antenna 1 -- = region -- = region 3 -output = true -``` -c) File defining two districts, the current simulation will ignore the second one: - -```ini -[All countries] -apply-filter= add-all -output=true - - -[All but one] -apply-filter = add-all --= special region 12 -output=false -``` - -## The Annual System Cost Output file - -In addition to the general files introduced in [Output Files](05-output_files.md), the Output folder of each economic or adequacy simulation includes, at its root, a file "Annual\_System\_Cost.txt" It presents the metrics of a global Monte-Carlo variable further denoted ASC. - -The value of ASC for any given simulated year is defined as the sum, over all areas and links, of the annual values of the area-variable "OV.COST" and of the link-variable "HURD. COST". - -The metrics displayed in the "Annual system cost" file take the form of four values: - -- Expectation EASC - -- Standard deviation SASC - -- Minimum LASC - -- Maximum UASC - -As with all other random variables displayed in the Antares Output section, the computed standard deviation of the variable can be used to give a measure of the confidence interval attached to the estimate of the expectation. For a number of Monte-Carlo years N, the law of large numbers states for instance that there is a 95 % probability for the actual expectation of ASC to lie within the interval: - -
**EASC +/- 1.96 (SASC / sqrt(N))**
- -There is also a 99.8 % probability that it lies within the interval: - -
**EASC +/- 3 (SASC / sqrt(N))**
- -## The "export mps" optimization preference - -This preference can be set either on "false" or "true". Choosing either value does not influence the way calculations are carried out, nor does it change their results. - -The effect of this preference is that, if the "true" value is selected, 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 preference "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 preference "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 - -Besides, each economic problem generally demands 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, it is possible that, on special occasions (very small files), the files attached to the two optimization rounds begin to be printed within the same second. In that case, an additional suffix is added before the mps or txt extension. - -**Note that:** - -- _The disk space used to store mps file is not included in the disk resources assessment displayed in the resources monitor menu._ - -- _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._ - -## The "Unfeasible Problems Behavior" optimization preference - -This preference can take any of the four values: - -Error Dry, Error Verbose, Warning Dry, Warning Verbose - -If "Error Dry" or "Error Verbose" 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 Verbose" 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 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 are printed regarding the faulty problem(s). With "Verbose" options, the full expression of the faulty problem(s) is printed in the standard "mps" format, thus allowing further analysis of the infeasibility issue. - -## The "Reservoir Level Initialization" advanced parameter - -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 hydro-power storage resources to consider in each specific Monte-Carlo year (see [Active windows](04-active_windows.md)). - -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 (see [Active Windows](04-active_windows)) 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 [System requirements](09-system_requirements)) must be set so as 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._ - -## The "Hydro Heuristic policy" advanced parameter - -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. - -## The "Hydro Pricing mode" advanced parameter - -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](05-output_files.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](05-output_files.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. - -## The "Unit Commitment mode" advanced parameter - -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](Standard_Implementation.png) - -![Antares_Implementation](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. - -## The "Renewable Generation modeling" advanced parameter - -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. - -[^monthly_allocation]: In the first equation, $S_{t-1}$ is either the initial stock $S_0$ or the final stock of the previous year (hydro hot start) - -[^daily_allocation]: In the first equation, $S_{t-1}$ is either the initial stock used in M or the final stock of the previous month ($D(m-1)$ - -[^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/reference-guide/09-system_requirements.md b/docs/reference-guide/09-system_requirements.md deleted file mode 100644 index ebe54419a5..0000000000 --- a/docs/reference-guide/09-system_requirements.md +++ /dev/null @@ -1,87 +0,0 @@ -# System requirements - -## Operating system - -Antares\_Simulator code is cross-platform (Windows/Linux/Unix) and installation packages for various versions of these OS are available at: [_https://antares-simulator.org_](https://antares-simulator.org/) - -## Hard drive disk - -Installed alone, the Antares simulator does not require a lot of HDD space (less than 1 GB). Installation packages including companion tools (study manager, graph editor) are however significantly heavier. The proper storage of data (i.e. both Input and Output folders of Antares studies) may require a large amount of space. The disk footprint of any individual study mainly depends on: - -- The size of the power system modeled (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 afterwards -- The activation of output filters (Geographic Trimming and / or Thematic Trimming) -- The number of Monte-Carlo years involved in the simulation session (if the storage of detailed year-by-year results is requested) -- The status of the "export mps" optimization preference - -At any moment, the amount of disk resources required for a simulation is accessible through the Tools/resources monitor menu. - -## Memory - -The amount of RAM required for a simulation depends on: - -- The size of the power system modeled (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 (adequacy, economy with "fast" or "accurate" unit commitment) -- The execution mode (default or parallel) - -At any moment, the amount of RAM resources required for a simulation is accessible through the Tools/resources monitor menu. - -## Multi-threading - -The GUI of Antares and all I/O operations on Input / Output files automatically benefit from full multi-threading on the local machine's CPU cores. Multi-threading is also available on the proper calculation side, on a user-defined basis. - -Provided that hardware resources are large enough, this mode may reduce significantly the overall runtime of heavy simulations. - -To benefit from multi-threading, the simulation must be run in the following context: - -- In the "run" window, the option "parallel" must be selected - [^21] -- The simulation mode must be either "Adequacy" or "Economy" - -When the "parallel" solver option is used, each Monte-Carlo year is dispatched as 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 " **simulation cores**" 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. - -**Simulation Cores:** - -| _Machine_
_Size [^22]_ | _Minimum_ | _Low_ | _Medium_ | _Large_ | _Maximum_ | -|:---:|:---:|:---:|:---:|:---:|:---:| -| _1_ | 1 | 1 | 1 | 1 | 1 | -| _2_ | 1 | 1 | 1 | 2 | 2 | -| _3_ | 1 | 2 | 2 | 2 | 3 | -| _4_ | 1 | 2 | 2 | 3 | 4 | -| _5_ | 1 | 2 | 3 | 4 | 5 | -| _6_ | 1 | 2 | 3 | 4 | 6 | -| _7_ | 1 | 2 | 3 | 5 | 7 | -| _8_ | 1 | 2 | 4 | 6 | 8 | -| _9_ | 1 | 3 | 5 | 7 | 8 | -| _10_ | 1 | 3 | 5 | 8 | 9 | -| _11_ | 1 | 3 | 6 | 8 | 10 | -| _12_ | 1 | 3 | 6 | 9 | 11 | -| _S > 12_ | 1 | Ceil(S/4) | Ceil(S/2) | Ceil(3S/4) | S-1 | -**
CPU allowances in parallel mode
** - -**Note**: The number of independent threads actually launched by Antares in parallel mode may appear smaller than that shown in the table above. In this case, the resources monitor menu and the dashboard displayed on starting the simulation indicates: - -simulation cores: **nn** reduced to **pp** - -**nn** is the regular allowance and **pp** is the practical value that the solver has to work with. Allowance reduction may occur if the built-in Time-Series generators are activated, their "refresh" status is set to "Yes" and the values given to the "refresh span" parameters are not appropriate (parallel execution demand that refresh operations do not take place within a bundle of parallel years). Optimal use of the "parallel" execution mode is obtained when all activated built-in time –series generators are set up in either of the two following ways: -- Refresh status : **No** -- Refresh status : **Yes**, refresh span = **Ki \* (CPU allowance)** , with **Ki >= 1** - -Examples of reduction from an initial allowance of 12 cores are given hereafter. The reduced allowance is the size of the **smallest** bundle of parallel years between two consecutive "refresh" (it indicates the slowest point of the simulation [^23]). Note that RAM requirements displayed in the resources monitor are, contrariwise, assessed on the basis on the **largest** bundle of parallel years encountered in the simulation). - -![Reduced_Allowance](Reduced_Allowance.png) - -The Table indicates either the refresh status (No) or the refresh span (the associated refresh status "yes" is implicit). - - -[^21]: Options « default » do not perform multi-threaded optimizations - -[^22]: This hardware characteristic, independent from Antares general parameters and from study parameters, can be checked with the Resources monitor tool ([Commands](03-commands.md)) - -[^23]: When the number of MC years to run is smaller than the allowance, the parallel run includes all of these years in a single bundle and there is no "reduced allowance" message - -[^24]: - The smallest bundle in this case is the ninth (year number 97 to year number 100).The first 8 bundles involve 12 MC years each. - diff --git a/docs/reference-guide/15-executable_kirchhoffs_constraint_generator.md b/docs/reference-guide/15-executable_kirchhoffs_constraint_generator.md deleted file mode 100644 index 6d39d5ea76..0000000000 --- a/docs/reference-guide/15-executable_kirchhoffs_constraint_generator.md +++ /dev/null @@ -1,33 +0,0 @@ -# Executable Kirchhoff's Constraint Generator - -The kirchhoff constraint generator is a standalone tool used to automatically create kirchhoff constraints. For more details about this process read: - -[7-kirchhoffs_constraint_generator.md](https://github.com/AntaresSimulatorTeam/Antares_Simulator/blob/develop/docs/reference-guide/07-kirchhoffs_constraint_generator.md) - -The binary is located in Antares_Simulator/bin/ - ---- - -## Usage - -**./antares-8.3-kirchhoff-constraints-builder** [study_path] [option_file_path] - -## Options - -**study_path**: the path of the study, mandatory - -**option_file_path**: Optional. The path of the **constraintbuilder.ini** file. It's normally located in *study_path/settings/*. If not provided the constraint builder will take the default values, which are defined at the end of cbuilder.h. - -Those values were used to fill the GUI default values, and then the GUI created the file. That's why it's optional since only the default values are guaranteed to work. - -## Results - -New constraints generated this way will be stored in *input/bindingconstraints/* with the name uto_0001.txt, with incrementing numbers. The file *bindingconstraints.ini* located in the same directory will be updated accordingly. - -## Study components needed - -The study only needs to include the following components to generate kirchhoff constraints: - -- Areas (contains links) -- Binding Constraints -- version number \ No newline at end of file diff --git a/docs/reference-guide/15-output-variables.md b/docs/reference-guide/15-output-variables.md deleted file mode 100644 index e482646fa8..0000000000 --- a/docs/reference-guide/15-output-variables.md +++ /dev/null @@ -1,15 +0,0 @@ -# New output variables - -| Version | Variable(s) introduced | Files | Enabled by default | -|---|---|---|---| -| 8.0 | none | | | -| 8.1 | WIND OFFSHORE, WIND ONSHORE, SOLAR CONCRT., SOLAR PV, SOLAR ROOFT, RENW. 1, RENW. 2, RENW. 3, RENW. 4 | values-*.txt | yes | -| 8.1 | MISC. DTG 2, MISC. DTG 3, MISC. DTG 4 | values-*.txt | yes | -| 8.2 | none | | | -| 8.3 | DENS | values-*.txt | no | -| 8.3 | Profit by plant | details-*.txt | yes | -| 8.4 | BC. MARG. COST | binding-constraints-*.txt | no | -| 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 | diff --git a/docs/reference-guide/17-v91.md b/docs/reference-guide/17-v91.md deleted file mode 100644 index 100008f26d..0000000000 --- a/docs/reference-guide/17-v91.md +++ /dev/null @@ -1,3 +0,0 @@ -## Logic changes for hydro (Antares Simulator 9.1.0) - -![Logic changes](logic-hydro-maxP.png "Logic changes") \ No newline at end of file diff --git a/docs/reference-guide/Antares_Process.png b/docs/reference-guide/Antares_Process.png deleted file mode 100644 index 60500cd411..0000000000 Binary files a/docs/reference-guide/Antares_Process.png and /dev/null differ diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index c292b0a0a5..a4abde6c67 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -15,4 +15,8 @@ } [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; } \ No newline at end of file diff --git a/docs/user-guide/00-index.md b/docs/user-guide/00-index.md new file mode 100644 index 0000000000..892cf400b5 --- /dev/null +++ b/docs/user-guide/00-index.md @@ -0,0 +1,13 @@ +[//]: # (Index used by Sphinx to generate correct PDF tree) + +```{toctree} +:hidden: +01-overview.md +02-install.md +03-getting_started.md +solver/00-index.md +ts-analyzer-generator/00-index.md +other-features/00-index.md +04-migration-guides.md +05-attribution-notices.md +``` \ No newline at end of file diff --git a/docs/user-guide/01-overview.md b/docs/user-guide/01-overview.md new file mode 100644 index 0000000000..ddc3b03c60 --- /dev/null +++ b/docs/user-guide/01-overview.md @@ -0,0 +1,76 @@ +# Overview + +This user guide describes all the main features of the *Antares Simulator*[^1] package. +[^1]: For simplicity's sake, the *Antares Simulator* application will be simply denoted *Antares*. + +It gives useful general information regarding the way data are handled and processed. +Since the *Antares* GUI support has been dropped (in favor of [Antares Web](https://antares-web.readthedocs.io)), +all its documentation has been removed. If you are still using an old version of *Antares* GUI, you can still find +its documentation in the assets of the release, or by browsing older versions of the documentation website. + +Real-life use of the software involves a learning curve process that cannot be supported by a +simple user guide. In order to be able to address this basic issue, two kinds of resources may be used: + +- The ["examples"](https://github.com/AntaresSimulatorTeam/Antares_Simulator_Examples) library, which is meant + as a self-teaching way to learn how to use the software. It is regularly enriched with the software's new features. + The contents of this library depend on the installation package it comes from (public version vs. users' club version). +- The [https://antares-simulator.org](https://antares-simulator.org/) website + +If you notice an issue in the documentation, please report it on [github.com](https://github.com/AntaresSimulatorTeam/Antares_Simulator/issues/new/choose). + +## Applications + +In terms of power studies, the fields of application *Antares* has been designed for are: + +- **Generation adequacy problems** +- **Transmission project profitability** + +### Generation adequacy problems +**Adequacy** problems aim to study the need for new generating plants to keep the security of +supply above a given critical threshold. + +What is most important in these studies is to survey a great number of scenarios that represent well enough +the random factors that may affect the balance between load and generation. Economic parameters do not play +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. + +### Transmission project profitability +[//]: # (TODO: explain what "fair and perfect market" means) +**Transmission project profitability** studies the savings brought by a specific reinforcement of the grid, +in terms of decrease of the overall system generation cost (using an assumption of a fair and perfect market) +and/or improvement of the security of supply (reduction of the loss-of-load expectation). + +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. + +## Performance considerations +Typically, *Antares* has to solve a least-cost hydro-thermal power schedule and unit commitment problem, with an hourly +resolution and throughout a week, over a large interconnected system. +The large number and the size of the individual problems to solve often make optimization sessions computer-intensive. + +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) + +[//]: # (TODO: list in [^2] the other parameters that have impact on performance) + +*Antares* has been designed to handle [adequacy and profitability problems](#applications). + +The common rationale of the modeling used in all of these studies is, whenever it is possible, +to divide the overall problem (representation of the system behavior throughout many years, +with a time step of one hour) into a series of standardized, smaller problems. + +In *Antares*, the "elementary" optimization problem resulting from this approach is that of the minimization of +the **whole power system**'s operational cost over **one week**, taking into account all proportional and +non-proportional generation costs, as well as transmission charges and "external" costs such as +that of the un-supplied energy (generation shortage) or, conversely, that of the spilled energy (generation excess). +In other words, adequacy and profitability studies are carried out by solving a series of a large number of week-long +operation problems (one for each week of each Monte-Carlo year), assumed to be independent to some extent. +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). diff --git a/docs/user-guide/02-install.md b/docs/user-guide/02-install.md new file mode 100644 index 0000000000..ffa1c75c37 --- /dev/null +++ b/docs/user-guide/02-install.md @@ -0,0 +1,53 @@ +# Installation + +## System requirements + +### Operating system +*Antares* code is cross-platform. Our releases target a few specific operating systems: + +- Windows 10/11 +- CentOS 7.9 +- Ubuntu 20.04 +- OracleServer 8.9 +- OracleLinux 8 + +If you use any other Windows/Linux/Unix OS, you can still use *Antares*, although you will have to build it from sources +(see next section). + +### Hard drive disk + +Installed alone, the Antares simulator does not require a lot of HDD space (less than 1 GB). Installation packages including companion tools (study manager, graph editor) are however significantly heavier. The proper storage of data (i.e. both Input and Output folders of Antares studies) may require a large amount of space. The disk footprint of any individual study mainly depends on: + +- 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)). +- The activation of output filters + (see [thematic-trimming](18-parameters.md#thematic-trimming) and [geographic-trimming](18-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 + +If you encounter space issues, consider tweaking the aforementioned parameters or reducing your study size. + +### Memory + +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) +- 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. + +## Instructions + +- **Windows 10/11**: download & run installation packages, or executables, available at + [*https://antares-simulator.org*](https://antares-simulator.org/) + or on [GitHub](https://github.com/AntaresSimulatorTeam/Antares_Simulator/releases). +- **CentOS 7.9**: download & run installation packages, or executables, available on [GitHub](https://github.com/AntaresSimulatorTeam/Antares_Simulator/releases). +- **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 diff --git a/docs/user-guide/03-getting_started.md b/docs/user-guide/03-getting_started.md new file mode 100644 index 0000000000..6ceab3315b --- /dev/null +++ b/docs/user-guide/03-getting_started.md @@ -0,0 +1,77 @@ +# Getting started + +## Organizing your data + +### General information + +In Antares, all input and output data of a given study are located within a folder named after the study +and which should preferably be stored within a dedicated library of studies +(for instance: `C/.../A_name_for_an_Antares_lib/Study-number-one`). + +Note that most of the *Antares* input and output files are either in ".txt" or ".csv" format. Although you may very well +modify them in your favorite text editor, you are not advised to do so, since handling data this way may result in fatal +data corruption (e.g. as a consequence of accidental insertion of special characters). Only manipulate raw input and +output data directly if you are an experienced *Antares* user. +Instead, we advise you to use [Antares Web](https://antares-web.readthedocs.io) or [Antares Extensions](#using-extensions). + +The input data contained in the study folder describe the whole state of development of the interconnected power system +(namely: grid, load and generating plants of every kind) for a given future year. + +Once the input data is ready for calculation purposes, an Antares session may start and involve any or all of +the following steps: historical time-series analysis, stochastic times-series generation, +(full) adequacy simulation and economic simulation. + +The results of the session are stored within the **input or the output** section of the study folder (depending on the session +type, refer to the documentation of the different features for more information). +The results obtained in the different sessions are stored side by side and tagged. +The identification tag has two components: a user-defined session name and the time at which the session was launched. + +Particular cases: +- Some specific input data may be located outside the study folder (this is the case for some inputs of + the [time-series analyzer](other-features/analyzer.md), for example). +- If the study folder contains a specific subfolder named "user", then this folder will have a special status: *Antares* + will consider it as a "private" user space, and avoid deleting any files in it (but files may be updated if the user requires it). + As a consequence, the user is free to store any kind of information in this directory without the risk of it being + modified by *Antares*. + +### Using extensions + +The Antares simulator may be delivered with or without functional extensions that provide additional +ways to handle input and output data. +Many various extensions (programs written in R language) are available: + +- [AntaresEditObject](https://cran.r-project.org/web/packages/antaresEditObject) +- [AntaresRead](https://cran.r-project.org/web/packages/antaresRead) +- [AntaresViz](https://cran.r-project.org/web/packages/antaresViz) + +These extensions take the form of companion applications that are independent of the main simulator. +For information regarding these tools, please refer to the relevant documents. + +## Usual workflow of an *Antares* session + +A typical *Antares* session involves different steps that are usually run in sequence, +either automatically or with some degree of man-in-the-loop control, depending on the kind of study to perform. + +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)).* + *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), + running a simulation to produce actual numeric scenarios, following the directives defined in (2). + *In this step, the [ts-generator](ts-generator/01-overview.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.md) tool should be used.* +5. Exploiting the detailed [results](solver/03-outputs.md) yielded by (4). + *In this step, we recommend using [Antares Web](https://antares-web.readthedocs.io) + or [Antares Extensions](#using-extensions).* + +The scope of this user guide is to give a detailed description of the *Antares Simulator* software involved in +steps (1) to (5) mostly based on a functional approach, leaving thereby aside a significant +part of the mathematical content involved in several of these steps. +The following picture gives a functional view of all that is involved in steps (1) to (5). + +![Antares_Process](img/Antares_Process.jpg) diff --git a/docs/reference-guide/13-file-format.md b/docs/user-guide/04-migration-guides.md similarity index 99% rename from docs/reference-guide/13-file-format.md rename to docs/user-guide/04-migration-guides.md index 6a319d3b16..2fda042306 100644 --- a/docs/reference-guide/13-file-format.md +++ b/docs/user-guide/04-migration-guides.md @@ -1,4 +1,4 @@ -# Study format changes +# Migration guides This is a list of all recent changes that came with new Antares Simulator features. The main goal of this document is to lower the costs of changing existing interfaces, both GUI and scripts. ## v9.1.0 ### Input @@ -10,7 +10,7 @@ Regarding Hydro time-series, the scenario builder allows the user to choose, for - initial level (prefix "hl") This implies that, inside one of the previous categories, the number of available time series is the same -* [Logic changes](17-v91.md) +![Logic changes](img/logic-hydro-maxP.png "Logic changes") #### Short term storage groups STS groups in input are now "dynamic" : group names are no longer fixed by code, user is free to define these groups. diff --git a/docs/reference-guide/12-attribution_notices.md b/docs/user-guide/05-attribution_notices.md similarity index 66% rename from docs/reference-guide/12-attribution_notices.md rename to docs/user-guide/05-attribution_notices.md index 8e152fa154..082f56c490 100644 --- a/docs/reference-guide/12-attribution_notices.md +++ b/docs/user-guide/05-attribution_notices.md @@ -4,17 +4,22 @@ **Copyright 2007-2024, RTE (https://www.rte-france.com) - Authors: The Antares\_Simulator Team** -This file is part of Antares-Simulator, Adequacy and Performance assessment for interconnected energy networks. +This user guide is part of *Antares\_Simulator: Adequacy and Performance assessment for interconnected energy networks*. -Antares\_Simulator is free software: you can redistribute it and/or modify it under the terms of the Mozilla Public Licence 2.0 as published by the Mozilla Foundation, either version 2 of the License, or (at your option) any later version. +Antares\_Simulator is free software: you can redistribute it and/or modify it under the terms of the Mozilla Public +Licence 2.0 as published by the Mozilla Foundation, either version 2 of the License, or (at your option) any later version. -There are special exceptions to the terms and conditions of the license as they are applied to this software. View the full text of the exceptions in file COPYING.txt in the directory of a distribution of the software in source form. +There are special exceptions to the terms and conditions of the license as they are applied to this software. +View the full text of the exceptions in file COPYING.txt in the directory of a distribution of the software in source form. -Antares\_Simulator is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the Mozilla Public Licence 2.0 for more details. +Antares\_Simulator is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the +implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the Mozilla Public Licence 2.0 for more details. -You should have received a copy of the Mozilla Public Licence 2.0 along with Antares\_Simulator. If not, see <[https://opensource.org/license/mpl-2-0/](https://opensource.org/license/mpl-2-0/) >. +You should have received a copy of the Mozilla Public Licence 2.0 along with Antares\_Simulator. +If not, see [https://opensource.org/license/mpl-2-0/](https://opensource.org/license/mpl-2-0/). -**Antares\_Simulator 8.3 uses external libraries and makes extensive use of the following persons' or companies code. Source and binary forms of these programs are distributed along with Antares\_Simulator with NO WARRANTY:** +**Antares\_Simulator 8.3 uses external libraries and makes extensive use of the following persons' or companies code. +Source and binary forms of these programs are distributed along with Antares\_Simulator with NO WARRANTY:** - Wxwidgets 3.1.3 Copyright (c) 1998-2017 The wxWidget Team [https://github.com/wxWidgets/wxWidgets.git](https://github.com/wxWidgets/wxWidgets.git) diff --git a/docs/user-guide/99_to_be_classified.md b/docs/user-guide/99_to_be_classified.md new file mode 100644 index 0000000000..88e9456a08 --- /dev/null +++ b/docs/user-guide/99_to_be_classified.md @@ -0,0 +1,41 @@ +# Active windows + +[//]: # (TODO: fetch important content & remove this page) + +## Simulation + +The main simulation window is divided up in two parts. On the left side are the general parameters while the right side is devoted to the time-series management. + +These two parts are detailed hereafter. + + +### RIGHT PART: Time-series management + +For the different kinds of time-series that Antares manages in a non-deterministic way (load, thermal generation, +hydro power, hydro max power, wind power, solar power or renewable depending on the option chosen): + +1. **Choice of the kind of time-series to use** +Either « ready-made » or «stochastic » (i.e. Antares-generated), defined by setting the value to either "on" or "off". +2. Exception is hydro max power that can only be « ready-made ». Note that for Thermal time-series, the cluster-wise +3. parameter may overrule this global parameter (see Thermal window description below). + +2. **For stochastic TS only**: + + - **Seasonal correlation** ("monthly" or "annual") Indicates whether the spatial correlation matrices to use are + defined month by month or if a single annual matrix for the whole year should rather be used (see [Time-series analysis and generation](06-time_series_analysis_and_generation.md)) + + - **Store in output** + - **Yes**: the generated times-series will be stored as part of the simulation results + - **No**: no storage of the generated time-series in the results directories + +3. **General rules for building up the MC years** + - **Intra-modal**: + - **Yes** For each mode, the same number should be used for all locations (or 1 where there is only one TS), + but this number may differ from one mode to another. For instance, solar power TS = 12 for all areas, while wind power TS number = 7 for all areas. + - **No** Independent draws + - **Inter-modal**: + - **Yes** For all modes, the same number should be used but may depend on the location (for instance, solar + and wind power TS = 3 for area 1, 8 for area 2, 4 for area 3, etc.) + - **No** Independent draws + + diff --git a/docs/user-guide/img/Antares_Process.jpg b/docs/user-guide/img/Antares_Process.jpg new file mode 100644 index 0000000000..8aca6a99d3 Binary files /dev/null and b/docs/user-guide/img/Antares_Process.jpg differ diff --git a/docs/reference-guide/logic-hydro-maxP.drawio b/docs/user-guide/img/logic-hydro-maxP.drawio similarity index 100% rename from docs/reference-guide/logic-hydro-maxP.drawio rename to docs/user-guide/img/logic-hydro-maxP.drawio diff --git a/docs/reference-guide/logic-hydro-maxP.png b/docs/user-guide/img/logic-hydro-maxP.png similarity index 100% rename from docs/reference-guide/logic-hydro-maxP.png rename to docs/user-guide/img/logic-hydro-maxP.png diff --git a/docs/reference-guide/logic-hydro-maxP.svg b/docs/user-guide/img/logic-hydro-maxP.svg similarity index 100% rename from docs/reference-guide/logic-hydro-maxP.svg rename to docs/user-guide/img/logic-hydro-maxP.svg diff --git a/docs/reference-guide/migration.drawio b/docs/user-guide/img/migration.drawio similarity index 100% rename from docs/reference-guide/migration.drawio rename to docs/user-guide/img/migration.drawio diff --git a/docs/reference-guide/migration.png b/docs/user-guide/img/migration.png similarity index 100% rename from docs/reference-guide/migration.png rename to docs/user-guide/img/migration.png diff --git a/docs/reference-guide/migration.py b/docs/user-guide/img/migration.py similarity index 100% rename from docs/reference-guide/migration.py rename to docs/user-guide/img/migration.py diff --git a/docs/reference-guide/migration.svg b/docs/user-guide/img/migration.svg similarity index 100% rename from docs/reference-guide/migration.svg rename to docs/user-guide/img/migration.svg diff --git a/docs/user-guide/other-features/00-index.md b/docs/user-guide/other-features/00-index.md new file mode 100644 index 0000000000..6ed7aeb500 --- /dev/null +++ b/docs/user-guide/other-features/00-index.md @@ -0,0 +1,15 @@ +[//]: # (Index used by Sphinx to generate correct PDF tree) +# Other features + +```{toctree} +:hidden: +analyzer.md +batchrun.md +config.md +kirchhoff-constraints-builder.md +study-cleaner.md +study-finder.md +study-updater.md +vacuum.md +ybyaggregator.md +``` \ No newline at end of file diff --git a/docs/user-guide/other-features/analyzer.md b/docs/user-guide/other-features/analyzer.md new file mode 100644 index 0000000000..877b423332 --- /dev/null +++ b/docs/user-guide/other-features/analyzer.md @@ -0,0 +1,13 @@ +--- +hide: + - toc +--- + +# Time-Series Analyzer + +--- +> _**WARNING:**_ this feature is deprecated and will be removed in a future release. If you are still using it, +> please [get in touch](https://github.com/AntaresSimulatorTeam/Antares_Simulator/issues) with us. +--- + +**Executable**: antares-analyzer (currently released for Windows & Ubuntu only) \ No newline at end of file diff --git a/docs/user-guide/other-features/batchrun.md b/docs/user-guide/other-features/batchrun.md new file mode 100644 index 0000000000..eb6c4ead58 --- /dev/null +++ b/docs/user-guide/other-features/batchrun.md @@ -0,0 +1,53 @@ +--- +hide: + - toc +--- + +# Batch Runner + +--- +> _**WARNING:**_ this feature is deprecated and will be removed in a future release. If you are still using it, +> please [get in touch](https://github.com/AntaresSimulatorTeam/Antares_Simulator/issues) with us. +--- + +**Executable**: antares-batchrun (currently released for Windows & Ubuntu only) + +- Studies + +| command | meaning | +|:------------------|:------------------------------------------------------------------------| +| -i, --input=VALUE | The input folder, where to look for studies on which to run simulations | + +- Simulation mode + +| command | meaning | +|:------------|:------------------------------------------| +| --expansion | Force the simulation(s) in expansion mode | +| --economy | Force the simulation(s) in economy mode | +| --adequacy | Force the simulation(s) in adequacy mode | + +- Parameters + +| command | meaning | +|:-----------------|:-----------------------------------------------------| +| -n, --name=VALUE | Set the name of the new simulation outputs | +| -y, --year=VALUE | Override the number of MC years | +| -f, --force | Ignore all warnings at loading | +| --no-output | Do not write the results in the output folder | +| --year-by-year | Force the writing of the result output for each year | + +- Optimization + +| command | meaning | +|:-----------------|:------------------------------------------------| +| --no-ts-import | Do not import timeseries into the input folder. | +| --no-constraints | Ignore all binding constraints | + +- Extras + +| command | meaning | +|:-----------------------|:---------------------------------------------------------| +| --solver=VALUE | Specify the antares-solver location | +| --parallel | Enable the parallel computation of MC years | +| --force-parallel=VALUE | Override the max number of years computed simultaneously | +| --verbose | Display detailed logs for each simulation to run | \ No newline at end of file diff --git a/docs/user-guide/other-features/config.md b/docs/user-guide/other-features/config.md new file mode 100644 index 0000000000..b9acd22cca --- /dev/null +++ b/docs/user-guide/other-features/config.md @@ -0,0 +1,19 @@ +--- +hide: + - toc +--- + +# Config Checker + +--- +> _**WARNING:**_ this feature is deprecated and will be removed in a future release. If you are still using it, +> please [get in touch](https://github.com/AntaresSimulatorTeam/Antares_Simulator/issues) with us. +--- + +**Executable**: antares-config (currently released for Windows & Ubuntu only) + +| command | meaning | +|:--------------|:--------------------------------| +| -p, --print | Print the current configuration | +| -v, --version | Print the version and exit | +| -h, --help | Display this help and exit | \ No newline at end of file diff --git a/docs/reference-guide/07-kirchhoffs_constraint_generator.md b/docs/user-guide/other-features/kirchhoff-constraints-builder.md similarity index 67% rename from docs/reference-guide/07-kirchhoffs_constraint_generator.md rename to docs/user-guide/other-features/kirchhoff-constraints-builder.md index 3c2aad392b..e0c11c66b8 100644 --- a/docs/reference-guide/07-kirchhoffs_constraint_generator.md +++ b/docs/user-guide/other-features/kirchhoff-constraints-builder.md @@ -1,6 +1,15 @@ -# Kirchhoff's Constraint Generator +# Kirchhoff's constraint generator -Binding Constraints introduced in [Active windows](04-active_windows.md) can take many forms (hourly, daily, weekly), involve flows or thermal generated power, etc. Sets of binding constraints of special interest are those which can be used to model and enforce Kirchhoff's second law on the AC flows. +--- +> _**WARNING:**_ this feature is deprecated and will be removed in a future release. If you are still using it, +> please [get in touch](https://github.com/AntaresSimulatorTeam/Antares_Simulator/issues) with us. +--- + +**Executable**: antares-kirchhoff-constraints-builder (currently released for Windows & Ubuntu only) + +## Principles + +Binding Constraints can take many forms (hourly, daily, weekly), involve flows or thermal generated power, etc. Sets of binding constraints of special interest are those which can be used to model and enforce Kirchhoff's second law on the AC flows. In other words, it is possible to make Antares work as a genuine DC OPF, provided that consistent binding constraints are written down for each cycle belonging to any cycle basis of the graph made out from all AC components of the power system (V vertices, E edges). @@ -47,3 +56,43 @@ In addition to the previous functionalities, the KCG's GUI also includes the fol [^15]: The number of spanning trees is equal to the absolute value of any cofactor of the graph incidence matrix [^16]: Mehlhorn K., Michail D. (2005) _Implementing Minimum Cycle Basis Algorithms_. In: Experimental and Efficient Algorithms. WEA 2005. Lecture Notes in Computer Science, vol 3503. + +## Command-line instructions + +The kirchhoff constraint generator is a standalone tool used to automatically create kirchhoff constraints. For more details about this process read: + +[7-kirchhoffs_constraint_generator.md](https://github.com/AntaresSimulatorTeam/Antares_Simulator/blob/develop/docs/reference-guide/07-kirchhoffs_constraint_generator.md) + +The binary is located in Antares_Simulator/bin/ + +--- + +### Usage + +```bash +./antares-kirchhoff-constraints-builder [study_path] [option_file_path] +``` + +### Options + +**study_path**: the path of the study, mandatory + +**option_file_path**: Optional. The path of the **constraintbuilder.ini** file. It's normally located in *study_path/settings/*. If not provided the constraint builder will take the default values, which are defined at the end of cbuilder.h. + +Those values were used to fill the GUI default values, and then the GUI created the file. That's why it's optional since only the default values are guaranteed to work. + +### Results + +New constraints generated this way will be stored in *input/bindingconstraints/* with the name uto_0001.txt, +with incrementing numbers. The file *bindingconstraints.ini* located in the same directory will be updated accordingly. +> *Note*: the outputs of the Kirchhoff's constraints generator are not printed in the general output files +> but kept within the input files structure, the reason being that they are input data for the proper Antares simulation. +> The associated data, the so-called binding constraints, bear in their name the prefix "@UTO-". + +### Study components needed + +The study only needs to include the following components to generate kirchhoff constraints: + +- Areas (contains links) +- Binding Constraints +- version number \ No newline at end of file diff --git a/docs/user-guide/other-features/study-cleaner.md b/docs/user-guide/other-features/study-cleaner.md new file mode 100644 index 0000000000..ad2049afc6 --- /dev/null +++ b/docs/user-guide/other-features/study-cleaner.md @@ -0,0 +1,26 @@ +--- +hide: + - toc +--- + +# Study Cleaner + +--- +> _**WARNING:**_ this feature is deprecated and will be removed in a future release. If you are still using it, +> please [get in touch](https://github.com/AntaresSimulatorTeam/Antares_Simulator/issues) with us. +--- + +**Executable**: antares-study-cleaner (currently released for Windows & Ubuntu only) + +| command | meaning | +|:------------------|:------------------------------------------| +| -i, --input=VALUE | An input folder where to look for studies | +| --dry | List the folder only and do nothing | +| --mrproper | Suppress the outputs and logs files | +| -v, --version | Print the version and exit | +| -h, --help | Display this help and exit | + + +#### Note about the "user" subdirectory +*Antares* is not allowed to delete any files from the "user" subdirectory of the study directory. +As a consequence, the "user" subdirectory is unaffected by the Study Cleaner. \ No newline at end of file diff --git a/docs/user-guide/other-features/study-finder.md b/docs/user-guide/other-features/study-finder.md new file mode 100644 index 0000000000..d7e21a09f8 --- /dev/null +++ b/docs/user-guide/other-features/study-finder.md @@ -0,0 +1,21 @@ +--- +hide: + - toc +--- + +# Study Finder + +--- +> _**WARNING:**_ this feature is deprecated and will be removed in a future release. If you are still using it, +> please [get in touch](https://github.com/AntaresSimulatorTeam/Antares_Simulator/issues) with us. +--- + +**Executable**: antares-study-finder (currently released for Windows & Ubuntu only) + +| command | meaning | +|:------------------|:---------------------------------------------------------------------------------------------------------------------| +| -i, --input=VALUE | Add an input folder where to look for studies.
When no input folder is given, the current working dir is used. | +| -e, --extra | Print the version of the study | +| --csv | Print in a CSV format (semicolon) | +| -v, --version | Print the version and exit | +| -h, --help | Display this help and exit | \ No newline at end of file diff --git a/docs/user-guide/other-features/study-updater.md b/docs/user-guide/other-features/study-updater.md new file mode 100644 index 0000000000..0f6bafd87b --- /dev/null +++ b/docs/user-guide/other-features/study-updater.md @@ -0,0 +1,24 @@ +--- +hide: + - toc +--- + +# Study Updater + +--- +> _**WARNING:**_ this feature is deprecated and will be removed in a future release. If you are still using it, +> please [get in touch](https://github.com/AntaresSimulatorTeam/Antares_Simulator/issues) with us. +--- + +**Executable**: antares-study-updater (currently released for Windows & Ubuntu only) + + +| command | meaning | +|:------------------------------|:---------------------------------------------------------------------------| +| -i, --input=VALUE | Add an input folder where to look for studies. This argument is mandatory. | +| -c, --clean | Clean all studies found | +| --remove-generated-timeseries | Remove time-series which will be regenerated by the ts-generators | +| -d, --dry | List the study folders which may be upgraded and do nothing else | +| --force-readonly | Force read-only mode for all studies found | +| -v, --version | Print the version and exit | +| -h, --help | Display this help and exit | \ No newline at end of file diff --git a/docs/user-guide/other-features/ui-simulator.md b/docs/user-guide/other-features/ui-simulator.md new file mode 100644 index 0000000000..f79bab5c42 --- /dev/null +++ b/docs/user-guide/other-features/ui-simulator.md @@ -0,0 +1,17 @@ +--- +hide: + - toc +--- + +# GUI + +--- +> _**WARNING:**_ this feature is deprecated and will be removed in a future release. If you are still using it, +> please [get in touch](https://github.com/AntaresSimulatorTeam/Antares_Simulator/issues) with us. +--- + +**Executable**: antares-study-ui-simulator (currently released for Windows & Ubuntu only) + +#### Deprecation notice +The old *Antares* GUI has been deprecated in favor of [Antares Web](https://antares-web.readthedocs.io). +We strongly advise you to use *Antares Web*, and report to their development team any missing feature. diff --git a/docs/user-guide/other-features/vacuum.md b/docs/user-guide/other-features/vacuum.md new file mode 100644 index 0000000000..42af2f9f25 --- /dev/null +++ b/docs/user-guide/other-features/vacuum.md @@ -0,0 +1,13 @@ +--- +hide: + - toc +--- + +# Vacuum + +--- +> _**WARNING:**_ this feature is deprecated and will be removed in a future release. If you are still using it, +> please [get in touch](https://github.com/AntaresSimulatorTeam/Antares_Simulator/issues) with us. +--- + +**Executable**: antares-vacuum (currently released for Windows & Ubuntu only) diff --git a/docs/user-guide/other-features/ybyaggregator.md b/docs/user-guide/other-features/ybyaggregator.md new file mode 100644 index 0000000000..0ca3630116 --- /dev/null +++ b/docs/user-guide/other-features/ybyaggregator.md @@ -0,0 +1,13 @@ +--- +hide: + - toc +--- + +# Year-by-Year Aggregator + +--- +> _**WARNING:**_ this feature is deprecated and will be removed in a future release. If you are still using it, +> please [get in touch](https://github.com/AntaresSimulatorTeam/Antares_Simulator/issues) with us. +--- + +**Executable**: antares-ybyaggregator (currently released for Windows & Ubuntu only) diff --git a/docs/user-guide/solver/00-index.md b/docs/user-guide/solver/00-index.md new file mode 100644 index 0000000000..d9a519183b --- /dev/null +++ b/docs/user-guide/solver/00-index.md @@ -0,0 +1,17 @@ +[//]: # (Index used by Sphinx to generate correct PDF tree) +# Solver + +```{toctree} +:hidden: + +01-overview.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 +optional-features/00-index.md +09-appendix.md +``` diff --git a/docs/user-guide/solver/01-overview.md b/docs/user-guide/solver/01-overview.md new file mode 100644 index 0000000000..d620960a25 --- /dev/null +++ b/docs/user-guide/solver/01-overview.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/02-inputs.md new file mode 100644 index 0000000000..cf3768b7d2 --- /dev/null +++ b/docs/user-guide/solver/02-inputs.md @@ -0,0 +1,829 @@ +# Input files + +[//]: # (TODO: update this page, list all input files) +_**This section is under construction**_ + +- **System Maps** +- **Simulation** +- **User's Notes** +- **Load** +- **Solar** +- **Wind** +- **Renewable** +- **Hydro** +- **Thermal** +- **Misc. Gen.** +- **Reserves/DSM** +- **Links** +- **Binding constraints** +- **Economic opt.** + +## Conventions regarding names + +- Names for areas, thermal plants, etc. + Name length should not exceed 256 characters. + Characters must belong to: + { A-Z , a-z , 0-9 , - , \_ , ( , ) , & , comma , space } + +- Abbreviations : + - Fields requiring to be filled out with "YES" or "NO" can alternatively accept "Y" , "1" or "N" , "0" + - Fields requiring to be filled out with "ON" or " OFF" can alternatively accept "true", "1" or "false", "0" + - Fields requiring to be filled out with "annual" or "monthly" can alternatively accept "a" or "m" + - Fields requiring to be filled out with: "Raw" ,"Detrended"," Beta", "Normal", "Uniform", " Gamma", " Weibull" can alternatively accept: "R", "D", " B", "N", "U", "G", "W" + + +## Definition of regional districts + +Typical uses of the "district" feature are: + +1) On a large system, define an "all system" zone to get an overall synthesis on all the system nodes + +2) In a study involving different countries modeled by different regions, define "country" macro-nodes to aggregate regional results to the national level. + +3) In a study using some specific modeling such as PSP modeling with fake nodes, define a local cluster involving all the relevant real and fake nodes to simplify the edition of results. + +Hereafter is described the process to follow to bypass the GUI for the definition of districts.
+It is based on the edition of a special "sets.ini" file. + +**IMPORTANT :** +- 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). + +**WHERE TO FIND / STORE THE FILE** : INPUT/areas/sets.ini + +**PRINCIPLE:** + +The file is divided in consecutive sections, one for each district to define. + +A section contains: + +a) A header line that gives its name to the district. The header syntax is: `[district_name]` +To avoid confusion with the real area names, the results regarding this macro-area will later be found in the OUTPUT files under a name bearing the prefix "@", i.e. `@district_name` + +b) A list of parametrized building rules to be processed in their apparition order. +The different elementary rules are: ++= area\_name : add the area "area\_name" to the district
+-= area\_name : remove the area "area\_name" from the district
+apply-filter = add-all : add all areas to the district
+apply-filter = remove-all : remove all areas (clear the district) + +c) A special "output" parameter that defines whether the results for the district will actually be computed or not +(this latter option allows inactivating parts of the sets.ini without altering the file). +The syntax is: `output=false` or `output= true`. + +**EXAMPLES OF SETS.INI FILES** + +a) File defining a single district named "set1" involving three areas named "area1, area3, area42": + +```ini +[set1] ++ = area1 ++ = area3
++ = area42 +output = true +``` + +b) File defining a district gathering all areas but five: + +```ini +[most of the system] +apply-filter = add-al +- = country +- = neighbour +- = fake antenna 1 +- = region +- = region 3 +output = true +``` +c) File defining two districts, the current simulation will ignore the second one: + +```ini +[All countries] +apply-filter= add-all +output=true + + +[All but one] +apply-filter = add-all +-= special region 12 +output=false +``` + +## Load + +_[Documentation of the AntaresWeb interface for this section](https://antares-web.readthedocs.io/en/latest/user-guide/study/areas/02-load/)_ + +This window is used to handle all input data regarding load. In Antares load should include transmission losses. It should preferably not include the power absorbed by pumped storage power plants. If it does, the user should neither use the "PSP" array (see window "Misc. Gen") nor the explicit modeling of PSP plants + +The user may pick any area appearing in the list and is then given access to different tabs: + +- The "time-series" tab display the "ready-made" 8760-hour time-series available for simulation purposes. These data may come from any origin outside Antares, or be data formerly generated by the Antares time-series stochastic generator, stored as input data on the user's request. Different ways to update data are : + + - direct typing + + - copy/paste a selected field to/from the clipboard + + - load/save all the time-series from/to a file (usually located in the "user" subfolder) + + - Apply different functions (+,-, \*, /,etc.) to the existing (possibly filtered) values + (e.g. simulate a 2% growth rate by choosing "multiply-all-by-1.02") + + - Handle the whole (unfiltered) existing dataset to either + + - Change the number of columns (function name: resize) + - Adjust the values associated with the current first day of the year (function name: shift rows) + + Versatile "Filter" functions allow quick access to user-specified sections of data + (e.g. display only the load expected in the Wednesdays of January, at 09:00, for time-series #12 to #19). Hourly load is expressed in round numbers and in MW. If a smaller unit has to be used, the user should define accordingly ALL the data of the study (size of thermal plants, interconnection capacities, etc.) + + - _Note that:_ + + - _If the "intra-modal correlated draw" option has not been selected in the_ **simulation** _window, + MC adequacy or economy simulations can take place even if the number of time-series is not the same + in all areas (e.g. 2 , 5 , 1 , 45 ,...)_ + - _If the "intra-modal correlated draws" option has been selected in the_ **simulation** _window, + every area should have either one single time-series or the same given number (e.g. 25 , 25 , 1 , 25...)_ + + - The "spatial correlation" tab gives access to the inter-area correlation matrices that will be used + by the stochastic generator if it is activated. Different sub-tabs are available for the definition of 12 monthly + correlation matrices and of an overall annual correlation matrix. + A matrix A must meet three conditions to be a valid correlation matrix: + + $$\forall i,\ \forall j,\ {A_{ii} = 100; -100 \le A_{ij} \le 100}; A\ symmetric; A\ positive\ semi\mbox{-}definite$$ + + 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 sub-tabs whose content is presented in + [Time-series analysis and generation](../ts-generator/01-overview.md). + + - The "digest" tab displays for all areas a short account of the local data + +## Thermal + +_[Documentation of the AntaresWeb interface for this section](https://antares-web.readthedocs.io/en/latest/user-guide/study/areas/03-thermals/)_ + +This window is used to handle all input data regarding thermal dispatchable power. + +The user may pick any area appearing in the area list and is then given access to the list of thermal plants +clusters defined for the area (e.g. "CCG 300 MW", "coal 600", etc.). Once a given cluster has been selected, +a choice can be made between different tabs: + +- The "time-series" tab displays the "ready-made" 8760-hour time-series available for simulation purposes. + These data may come from any origin outside Antares, or be data formerly generated by the Antares time-series + stochastic generator, stored as input data on the user's request. Different ways to update data are : + + - direct typing + - copy/paste a selected field to/from the clipboard + - load/save all the time-series from/to a file (usually located in the "user" subfolder) + - Apply different functions (+,-, \*, /,etc.) to the existing (possibly filtered) values (e.g. simulate a + 2% growth rate by choosing "multiply-all-by-1.02") + - Handle the whole (unfiltered) existing dataset to either + + - Change the number of columns (function name: resize) + - Adjust the values associated with the current first day of the year (function name: shift rows) + + Versatile "Filter" functions allow quick access to user-specified sections of data (e.g. display only + the generation expected on Sundays at midnight, for all time-series). + + Hourly thermal generation is expressed in round numbers and in MW. If a smaller unit has to be used, the user should define accordingly ALL the data of the study (Wind generation, interconnection capacities, load, hydro generation, solar, etc.) + + - _Note that:_ + + - _If the "intra-modal correlated draws" option has not been selected in the_ **simulation** _window, + MC adequacy or economy simulations can take place even if the number of time-series is not the same in all + areas (e.g. 2, 5, 1, 45,etc.)_ + + - _If the "intra-modal correlated draws" option has been selected in the_ **simulation** _window, + every area should have either one single time-series or the same given number (e.g. 25, 25, 1, 25, etc.). + Note that, unlike the other time-series (load, hydro, etc.), which depend on meteorological conditions and + are therefore inter-area-correlated, the thermal plants time-series should usually be considered as uncorrelated. + Using the "correlated draws" feature makes sense only in the event of having to play predefined scenarios + (outside regular MC scope)_ + + +- The "TS generator" tab is used to set the parameters of the stochastic generator. + These parameters are defined at the daily scale and are namely, for each day: the average duration of + forced outages (beginning on that day), the forced outage rate, the duration of planned outages (beginning on that day), + the planned outage rate, planned outages minimum and maximum numbers. + Durations are expressed in days and rates belong to [0 , 1]. + + +- The "Common" tab is used to define the cluster's techno-economic characteristics : + + - Name + - Fuel used + - Location (Area) + - Activity status + - false: not yet commissioned, moth-balled, etc. + - true : the plant may generate + - Number of units + - Nominal capacity + - Full Must-run status + - false: above a partial "must-run level" (that may exist or not, see infra) plants + will be dispatched on the basis of their market bids. + - true: plants will generate at their maximum capacity, regardless of market conditions + - Minimum stable power (MW) + - Minimum Up time (hours) + - Minimum Down time (hours) + - Default contribution to the spinning reserve (% of nominal capacity) + - tons of different pollutant types (CO2, SO2, etc.) emitted per electric MWh + - 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) + - 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: + - Force generation: TS for this cluster will be generated + - Force no generation: TS for this cluster will not be generated + - Use global parameter: Will use the parameter for the study (the one in the [Simulation Window](#simulation)). + - Fixed cost (No-Load heat cost) (€ / hour of operation ) + - Start-up cost (€/start-up) + - Market bid (€/MWh) + - Random spread on the market bid (€/MWh) + - Variable Operation&Maintenance cost (€/MWh, only used if **Cost generation** is set to **use cost timeseries**) + - Seasonal marginal cost variations (gas more expensive in winter, ...) + - Seasonal market bid modulations (assets costs charging strategy ) + - Nominal capacity modulations (seasonal thermodynamic efficiencies, special over-generation allowances, etc.). These modulations are taken into account during the generation of available power time-series + - Minimal generation commitment (partial must-run level) set for the cluster + + - _Note that:_ + + - _The **optimal dispatch plan** as well as **locational marginal prices** are based on **market bids**, + while the assessment of the **operating costs** associated with this optimum are based on **cost parameters**. + (In standard "perfect" market modeling, there is no difference of approaches because market + bids are equal to marginal costs)_ + + - _Note that:_ + + - _If `Cost generation` is set to `Set manually` Marginal and Market bid costs (€/MWh) are specified directly in `Common` tab and have the same value for all time-series and hours._ + - _If `Cost generation` is set to `Use cost timeseries` Marginal and Market bid costs (€/MWh) are calculated separately for all the time-series and hours using the following equation:_ + _Marginal_Cost[€/MWh] = Market_Bid_Cost[€/MWh] = (Fuel_Cost[€/GJ] * 3.6 * 100 / Efficiency[%]) + CO2_emission_factor[tons/MWh] * C02_cost[€/tons] + Variable_O&M_cost[€/MWh]_ + _where Efficiency[%], CO2_emission_factor[tons/MWh] and Variable_O&M_cost[€/MWh] are specified in the `Common` tab under operating costs and parameters, while Fuel_Cost[€/GJ] and C02_cost[€/tons] are provided as time-series in separate tabs._ + + +## Storages + +_[Documentation of the AntaresWeb interface for this section](https://antares-web.readthedocs.io/en/latest/user-guide/study/areas/08-st-storages/)_ + +This window is used to create and edit short-term storage objects. An individual short-term storage component is defined as an object with the following characteristics: + +- Storage managed with a filling level which is identical at the start and end of each Antares optimization window; +- Rule curves that frame permissible storage levels hour by hour - the admissible range is a coefficient comprised between 0 and 1; +- Time-series of hourly modulation of the maximum injection and withdrawal power; +- Time-series of natural inflows (case of an open-cycle PSP). + +The user may pick any area appearing in the area list and is then given access to the list of short-term storages defined for the area. Once a given storage has been selected, the following characteristics can be set: + +- General characteristics of the storage: + - Name + - Group: the type of storage, based on a predefined list of storages ("PSP_open", "PSP_closed", "Pondage", "Battery", "Other1", "Other2", ..., "Other5") + - Withdrawal (MW): the maximum withdrawal power for the storage - withdrawal refers to the flow from the storage to the power system + - Injection (MW): the maximum injection power for the storage - withdrawal refers to the flow from the power system to the storage + - Stock (MWh): the capacity of the storage in MWh + - Efficiency (%): the energy efficiency of the storage, i.e. the ratio for a given volume between the energy taken from the system to be injected into the storage and the energy returned to the system during its withdrawal. This efficiency factor is applied when injecting energy into the storage. + - Initial level (%): the imposed initial filling rate of the storage at the beginning of each optimisation period. + - Initial level optimal: if the parameter is activated, the "Initial level" parameter is ignored and the initial storage level is optimized by Antares for each optimization period to minimize its objective function. + _Note: setting this parameter to "True" implies that there is no guarantee that the initial storage level of week N is the same as the final storage level of week N-1. However, the final level of week N is always equal to the initial level of the same week N plus/minus the injections/withdrawals occuring at the last hour of week N._ + +- "Injections/withdrawal capacities": a hourly time-series of modulation factors of the injection and withdrawal capacity for each hour (between 0 and 1), reflecting a lower availability of the structures during certain periods. At a given hour, the overall injection/withdrawal capacities of the storage are the product of this modulation factor by the "Withdrawal" and "Injection" parameters in the General data. + +- "Rule curves": a hourly time-series of rule curves (between 0 and 1), which are the lower and upper limits of the storage level imposed at each hour. + +- "Inflows": a hourly time-series of inflows filling the storage (in MWh). The values can be negative, corresponding to withdrawals imposed on the storage for other uses. + +## Hydro + +_[Documentation of the AntaresWeb interface for this section](https://antares-web.readthedocs.io/en/latest/user-guide/study/areas/05-hydro/)_ + +This section of the AntaresWeb interface for this section is meant to handle all input data regarding hydro power, +as well as any other kind of energy storage system of any size (from a small battery to a large +conventional hydro-storage reservoir with or without pumping facilities, etc.): Hydro power being +historically the first and largest form of power storage, it stood to reason that it should play in +Antares the role of a "generic template" for all forms of storable power. This versatility, however, +comes at the price of a comparatively more complex data organization than for other objects, +which explains the comparatively long length of this chapter. + +In the main Window, the user may pick any area appearing in the list and is then given access to different tabs: + +- The "time-series" tab displays the "ready-made" time-series already available for simulation purposes. There are five categories of time-series (displayed in five different subtabs): the Run of River (ROR) time-series, the Storage power (SP) time-series, the Minimum Generation power, the Maximum Generation power and the Maximum Pumping Power. + + ROR time-series are defined at the hourly scale; each of the 8760 values represents the ROR power expected at a given hour, expressed in round number and in MW. The SP time-series are defined at the daily scale; each of the 365 values represents an overall SP energy expected in the day, expressed in round number and in MWh. These natural inflows are considered to be storable into a reservoir for later use. The Minimum Generation time-series are defined at the hourly scale; each of the 8760 values represents the Minimum Generation power expected at a given hour expressed in round number and in MW. The Maximum Generation time-series are defined at the hourly scale; each of the 8760 values represents the Maximum Generation power expected at a given hour expressed in round number and in MW. The Maximum Pumping time-series are defined at the hourly scale; each of the 8760 values represents the Maximum Pumping power expected at a given hour expressed in round number and in MW. + + ROR time-series and SP time-series may come from any origin outside Antares, or may have been formerly generated by the Antares time-series stochastic generator and stored as input data on the user's request. Minimum Generation, Maximum Generation and Maximum Pumping may come from any origin outside Antares, but they can not be generated by the Antares time-series stochastic generator. Different ways to update data are: + + - direct typing + - copy/paste a selected field to/from the clipboard + - load/save all the time-series from/to a file (usually located in the "user" subfolder) + - Apply different functions (+,-, \*, /,etc.) to the existing (possibly filtered) values + (e.g. simulate a 2% growth rate by choosing "multiply-all-by-1.02") + - Handle the whole (unfiltered) existing dataset to either + + - Change the number of columns (function name: resize) + - Adjust the values associated with the current first day of the year (function name: shift rows) + + - _Note that:_ + + - _For a given area, the number of ROR time-series, SP times-series and Minimum Generation **must** be identical_ + - _For a given area, the number of Maximum Generation and Maximum Pumping **must** be identical_ + - _If the "intra-modal correlated draws" option was not selected in the_ **simulation** _window, + MC adequacy or economy simulations can take place even if the number of hydro time-series is not the same + in all areas (e.g. 2 , 5 , 1 , 45 ,...)_ + - _If the "intra-modal correlated draws" option was selected in the_ **simulation** _window, every + area should have either one single time-series or the same given number (e.g. 25 , 25 , 1 , 25...)_ + + +- The "spatial correlation" tab gives access to an annual inter-area correlation matrix that will be used by the stochastic generator if it is activated. Correlations are expressed in percentages, hence to be valid this matrix must be symmetric, p.s.d, with a main diagonal of 100s and all terms lying between (-100 ,+100) + + +- The "Allocation" tab gives access to an annual inter-area allocation matrix A(i,j) that may be used during a heuristic hydro pre-allocation process, regardless of whether the stochastic time-series generator is used or not. This matrix describes the weights that are given to the loads of areas (i) in the definition of the monthly and weekly hydro storage generation profiles of areas (j). The way this is done in detailed in [Heuristics](06-hydro-heuristics.md#seasonal-hydro-pre-allocation). + + +- The "local data" tab is used to set up the parameters of the stochastic generator_ **AND** _to define techno-economic characteristics of the hydro system that are used in Economy and Adequacy optimizations. For the purpose of versatility (use of the hydro section to model storage facilities quite different in size and nature), this "local tab" is itself divided up into four different subtabs whose list follows and which are further described: + + - Inflow Structure + - Reservoir Levels and water value + - Daily Power and Energy Credits + - Management options + +**Inflow Structure** + +This tab contains all the local parameters used for the stochastic generation of hydro time-series. These are namely: + +- The expectations, standard deviations, minimum and maximum values of monthly energies (expressed in MWh), monthly shares of Run of River within the overall hydro monthly inflow. +- The average correlation between the energy of a month and that of the next month (inter-monthly correlation). +- The average daily pattern of inflows within each month. Each day is given a relative "weight" in the month. If all days are given the same weight, daily energy time-series will be obtained by dividing the monthly energy in equal days. If not, the ratio between two daily energies will be equal to that of the daily weights in the pattern array. + +Overall hydro energy is broken down into two parts: Run of River- ROR and storage -STOR + +ROR energy has to be used on the spot, as it belongs to the general "must-run" energy category. + +STOR energy can be stored for use at a later time. The way how stored energy may actually be used depends +on the options chosen in the "management options" Tab and of the values of the parameters defined in the other Tabs. + +**Reservoir Levels and Water Values** + +Reservoir levels (left side) + +On the left side are defined 365 values for the minimum, average and maximum levels set for the reservoir +at the beginning of each day, expressed in percentage of the overall reservoir volume. The lower and upper level +time-series form a pair of so-called lower and upper "reservoir rule curves" + +Depending on the set of parameters chosen in the "management options" Tab, these rule curves may be used in +different ways in the course of both heuristic seasonal hydro pre-allocation process and subsequent weekly +optimal hydro-thermal unit-commitment and dispatch process. + +Water values (right side) + +On the right side is a table of marginal values for the stored energy, which depends on the date (365 days) and +of the reservoir level (101 round percentage values ranging from 0% to 100%). These values may have different origins; +they theoretically should be obtained by a comprehensive (dual) stochastic dynamic programming study carried out over +the whole dataset and dealing simultaneously with all reservoirs. + +Depending on the set options chosen in the "management options" Tab, these values may be used or not in the course of +the weekly optimal hydro-thermal unit-commitment and dispatch process. + +**Daily Power and Energy Credits** + +Standard credits (Bottom part) + +The bottom part displays two daily time-series (365 values) defined for energy generation/storage +(hydro turbines or hydro pumps). Both arrays represents the maximum daily energy (either generated or stored). + +For the sake of clarity, maximum daily energies are expressed as a number of hours at maximum power and these values +are used along with the Maximum Generation and Maximum Pumping TS's to calculate daily mean energy. + +Credit modulation (Upper part) + +The upper part displays two level-dependent (101 round percentage values ranging from 0% to 100%) time-series +of modulation coefficients defined for either generating or storing (pumping). + +These modulations, which can take any positive value, may (depending on the options chosen in the management +options Tab) be used to increase (value >1) or to decrease (value <1) the standard credits defined previously +for the maximum daily power and energies. + +**Management Options** + +This Tab is a general dashboard for the definition of how storage units, whatever their size or nature, should be managed. +It includes 15 parameters (out of which 7 are booleans) presented hereafter: + +- "Follow load" (y|n): defines whether an "ideal" seasonal generation profile should somehow follow the load OR an + "ideal" seasonal generation profile should remain as close as possible to the natural inflows + (i.e. instant generation whenever possible) + +- "Inter-daily breakdown" and "Inter-monthly breakdown" : parameters used in the assessment, through a + heuristic process, of an "ideal" seasonal generation profile, if the use of such a profile is required + (the heuristic itself is presented in [Heuristics](06-hydro-heuristics.md#seasonal-hydro-pre-allocation)) + +- "Intra-daily modulation": parameter which represents, for the storage power, the maximum authorized value for + the ratio of the daily peak to the average power generated throughout the day. This parameter is meant to allow + simulating different hydro management strategies. Extreme cases are : 1 : generated power should be constant throughout + the day 24 : use of the whole daily energy in one single hour is allowed + +- "Reservoir management" `y|n`: defines whether the storage should be explicitly modeled or not. + + Choosing "No" implies that available data allow or require that, regardless of the reservoir characteristics: + + - The whole amount of STOR energy of each month MUST be used during this month (no long-term storage) + + - The actual daily generation should follow, during the month, an "ideal" profile defined by the heuristic defined in [Heuristics](06-hydro-heuristics.md#seasonal-hydro-pre-allocation) + + Choosing "Yes" implies that available data allow or require explicit modeling of the storage facility, + regardless of whether a pre-allocation heuristic is used or not. + +- "Reservoir capacity": size of the storage facility, in MWh + +- "Initialize reservoir level on the 1st of": date at which the reservoir level should be initialized by a random draw. The "initial level" is assumed to follow a "beta" variable with expectation "average level", upper bound U=max level, lower bound L= min level, standard deviation = (1/3) (U-L) + +- "Use Heuristic Target" (y|n): defines whether an "ideal" seasonal generation profile should be heuristically determined or not. + + Choosing "No" implies that available data allow or require that full confidence should be put in water values determined upstream (through [dual] stochastic dynamic programming) OR that there are no "natural inflows" to the storage facility (battery or PSP, etc.) + + Choosing "Yes" implies that available data allow or require the definition of an "ideal" generation profile, that can be used to complement –or replace– the economic signal given by water values AND that there are "natural inflows" on which a generation heuristic can be based. + +- "Power-to-Level modulations (y|n)": defines whether the standard maximum daily energy and power credit should be or not multiplied by level-dependent modulation coefficients. + +- "Hard bounds on rule curves (y|n)": states whether, beyond the preliminary heuristic stage (if any), lower and upper reservoir rule curves should still be taken into account as constraints in the hydro-thermal unit commitment and dispatch problems. + +- "Use leeway (y|n)", lower bound L, upper bound U: states whether the heuristic hydro ideal target (**HIT**) should be followed exactly or not. + + Choosing "No" implies that, in optimization problems, the hydro energy generated throughout the time interval will be subject to an equality constraint, which may include short-term pumping cycles independent of water value: sum{ 1,t,T} (hydro(t)) – sum{1,t,T} (r. pump(t))= **HIT* + + Choosing "Yes", with bounds L and U, implies that, in optimization problems, the hydro energy generated throughout the time span will be subject to inequality constraints: L_*__HIT__ _<=sum{1,t,T} (hydro(t)) <= U\*_**HIT* + + Independently, short- or long-term pumping may also take place if deemed profitable in the light of water values. + + - "Use Water Value (y|n)": states whether the energy taken from / stored into the reservoir should be given the reference value defined in the ad hoc table OR should be given a zero value. + + - "Pumping Efficiency Ratio": setting the value to r means that, for the purpose of storing 1 gravitational MWh, pumps will have to use (1/r) electrical MWh. + +## Wind + +_[Documentation of the AntaresWeb interface for this section](https://antares-web.readthedocs.io/en/latest/user-guide/study/areas/06-wind/)_ + +This window is used to handle all input data regarding Wind power. +This window is only accessible when the advanced parameter Renewable Generation modeling is set to "Aggregated". + +The user may pick any area appearing in the list and is then given access to different tabs: + +- The "time-series" tab display the "ready-made" 8760-hour time-series already available for simulation purposes. These data may come from any origin outside Antares, or be data formerly generated by the Antares time-series stochastic generator, stored as input data on user's request. Different ways to update data are : + + - direct typing + - copy/paste a selected field to/from the clipboard + - load/save all the time-series from/to a file (usually located in the "user" subfolder) + - Apply different functions (+,-, \*, /,etc.) to the existing (possibly filtered) values (e.g. simulate a 2% growth rate by choosing "multiply-all-by-1.02") + - Handle the whole (unfiltered) existing dataset to either + - Change the number of columns (function name: resize) + - Adjust the values associated with the current first day of the year (function name: shift rows) + + Versatile "Filter" functions allow quick access to user-specified sections of data (e.g. display only the wind generation expected between 17:00 and 21:00 in February, for time-series 1 to 100). + + Hourly wind generation is expressed in round numbers and in MW. If a smaller unit has to be used, the user should define accordingly ALL the data of the study (size of thermal plants, interconnection capacities, load, etc.) + + - _Note that:_ + + - _If the "intra-modal correlated draws" option has not been selected in the_ **simulation** _window, MC adequacy or economy simulations can take place even if the number of time-series is not the same in all areas (e.g. 2, 5, 1,45, ...)_ + + - _If the "intra-modal correlated draws" option has been selected in the_ **simulation** _window, every area should have either one single time-series or the same given number (e.g. 25, 25, 1, 25, ...)_ + +- The "spatial correlation" tab gives access to the inter-area correlation matrices that will be used by the stochastic generator if it is activated. Different sub-tabs are available for the definition of 12 monthly correlation matrices and an overall annual correlation matrix. + + A matrix A must meet three conditions to be a valid correlation matrix: + + $$\forall i,\ \forall j,\ {A_{ii} = 100; -100 \le A_{ij} \le 100}; A\ symmetric; A\ positive\ semi\mbox{-}definite$$ + + 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 "digest" tab displays for all areas a short account of the local data + + +## Solar + +_[Documentation of the AntaresWeb interface for this section](https://antares-web.readthedocs.io/en/latest/user-guide/study/areas/07-solar/)_ + +This window is used to handle all input data regarding Solar power. Both thermal solar generation and PV solar generation are assumed to be bundled in this data section. +_This window is only accessible when the advanced parameter Renewable Generation modeling is set to "aggregated”._ + +The user may pick any area appearing in the list and is then given access to different tabs: + +- The "time-series" tab display the "ready-made" 8760-hour time-series available for simulation purposes. These data may come from any origin outside Antares, or be data formerly generated by the Antares time-series stochastic generator, stored as input data on the user's request. Different ways to update data are : + + - direct typing + - copy/paste a selected field to/from the clipboard + - load/save all the time-series from/to a file (usually located in the "user" subfolder) + - Apply different functions (+,-, \*, /,etc.) to the existing (possibly filtered) values (e.g. simulate a 2% growth rate by choosing "multiply-all-by-1.02") + - Handle the whole (unfiltered) existing dataset to either + + - Change the number of columns (function name: resize) + - Adjust the values associated with the current first day of the year (function name: shift rows) + + Versatile "Filter" functions allow quick access to user-specified sections of data (e.g. display only the solar power expected in August at noon, for all time-series). + + Hourly solar power is expressed in round numbers and in MW. If a smaller unit has to be used, the user should define accordingly ALL the data of the study (size of thermal plants, interconnection capacities, etc.) + + - _Note that:_ + + - _If the "intra-modal correlated draws" option was not selected in the_ **simulation** _window, MC adequacy or economy simulations can take place even if the number of time-series is not the same in all areas (e.g. 2 , 5 , 1 , 45 ,...)_ + + - _If the "intra-modal correlated draws" option was selected in the_ **simulation** _window, every area should have either one single time-series or the same given number (e.g. 25 , 25 , 1 , 25...)_ + +- The "spatial correlation" tab gives access to the inter-area correlation matrices that will be used by the stochastic generator if it is activated. Different sub-tabs are available for the definition of 12 monthly correlation matrices and of an overall annual correlation matrix. + + A matrix A must meet three conditions to be a valid correlation matrix: + + $$\forall i,\ \forall j,\ {A_{ii} = 100; -100 \le A_{ij} \le 100}; A\ symmetric; A\ positive\ semi\mbox{-}definite$$ + + 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 "digest" tab displays for all areas a short account of the local data + + +## Renewable + +_[Documentation of the AntaresWeb interface for this section](https://antares-web.readthedocs.io/en/latest/user-guide/study/areas/04-renewables/)_ + +This window is used to handle all input data regarding renewable generation. +_This window is only accessible when the advanced parameter Renewable Generation modeling is set to "cluster” (default value)._ + +The user may pick any area appearing in the area list and is then given access to the list of renewable clusters defined for the area (e.g. "Onshore Wind Farm 200MW", "Solar Rooftop 50MW", etc.). Once a given cluster has been selected, a choice can be made between different tabs: + +- The "time-series" tab displays the "ready-made" 8760-hour time-series available for simulation purposes. These data may come from any origin outside Antares, or be data formerly generated by the Antares time-series stochastic generator, stored as input data on the user's request. Different ways to update data are : + + - direct typing + - copy/paste a selected field to/from the clipboard + - load/save all the time-series from/to a file (usually located in the "user" subfolder) + - Apply different functions (+,-, \*, /,etc.) to the existing (possibly filtered) values (e.g. simulate a 2% growth rate by choosing "multiply-all-by-1.02") + - Handle the whole (unfiltered) existing dataset to either + + - Change the number of columns (function name: resize) + - Adjust the values associated with the current first day of the year (function name: shift rows) + + Versatile "Filter" functions allow quick access to user-specified sections of data (e.g. display only the generation expected on Sundays at midnight, for all time-series). + + Hourly thermal generation is expressed in round numbers and in MW. If a smaller unit has to be used, the user should define accordingly ALL the data of the study (Wind generation, interconnection capacities, load, hydro generation, solar, etc.) + + - _Note that:_ + + - _If the "intra-modal correlated draws" option has not been selected in the_ **simulation** _window, MC adequacy or economy simulations can take place even if the number of time-series is not the same in all areas (e.g. 2, 5, 1, 45,etc.)_ + + - _If the "intra-modal correlated draws" option has been selected in the_ **simulation** _window, every area should have either one single time-series or the same given number (e.g. 25, 25, 1, 25, etc.). Note that, unlike the other time-series (load, hydro, etc.), which depend on meteorological conditions and are therefore inter-area-correlated, the thermal plants time-series should usually be considered as uncorrelated. Using the "correlated draws" feature makes sense only in the event of having to play predefined scenarios (outside regular MC scope)_ + + +- The "TS generator" tab is not accessible for this version. + + +- The "Common" tab is used to define the cluster's techno-economic characteristics : + + - Name + - Group: The group can be any one of the following: Wind Onshore, Wind Offshore, Solar Thermal, Solar PV, Solar Rooftop, Other RES 1, Other RES 2, Other RES 3, or Other RES 4. If not specified, the renewable cluster will be part of the group Other RES 1. + - Location (Area) + - Timeseries mode: + - Power generation means that the unit of the timeseries is in MW + - Production factor means that the unit of the timeseries is in p.u. (between 0 and 1, 1 meaning the full installed capacity) + - Activity status + - false: not yet commissioned, moth-balled, etc. + - true: the cluster may generate + - Number of units + - Nominal capacity (in MW per unit) + + +## Misc. Gen. + +_[Documentation of the AntaresWeb interface for this section](https://antares-web.readthedocs.io/en/latest/user-guide/study/areas/10-misc-gen/)_ + +This window is used to handle all input data regarding miscellaneous non dispatchable generation. + +On picking any area in the primary list, the user gets direct access to all data regarding the area, which amount to **8** ready-made 8760-hour time-series (expressed in MW): + +- CHP generation + +- Bio Mass generation + +- Bio-gas generation + +- Waste generation + +- Geothermal generation + +- Any other kind of non-dispatchable generation + +- A predefined time-series for the operation of Pumped Storage Power plants, if they are not explicitly modeled. A positive value is considered as an output (generating) to the grid, a negative value is an input (pumping) to the station. + + Note that the sum of the 8760 values must be negative, since the pumping to generating efficiency is lower than 1. The user may also use only the negative values (prescribed pumping), while transferring at the same time the matching generating credit on the regular hydro storage energy credit. + +- ROW balance: the balance with the rest of the world. A negative value is an export to ROW, a positive value is an import from ROW. These values acts as boundary conditions for the model. Different ways to update data are: + + - direct typing + - copy/paste a selected field to/from the clipboard + - load/save all the time-series from/to a file (usually located in the "user" subfolder) + - Apply different functions (+,-, \*, /,etc.) to the existing (possibly filtered) values (e.g. simulate a 2% growth rate by choosing "multiply-all-by-1.02") + - Handle the whole (unfiltered) existing dataset to either + + - Change the number of columns (function name: resize) + - Adjust the values associated with the current first day of the year (function name: shift rows) + +## Reserves / DSM + +_[Documentation of the AntaresWeb interface for this section](https://antares-web.readthedocs.io/en/latest/user-guide/study/areas/09-reserves/)_ + +This window is used to handle all input data regarding reserves and the potential of "smart" load management (when not modeled using "fake" thermal dispatchable plants). On picking any area in the primary list, the user gets direct access to all data regarding the area, which amount to **four** ready-made 8760-hour time-series (expressed in MW). Those reserves are available in either "adequacy" or "economy" simulations: + +- Day-ahead reserve: power accounted for in setting up the optimal unit-commitment and schedule of the following day(s), which must consider possible forecasting errors or last-minute incidents. If the optimization range is of one day, the reserve will be actually seen as "day-ahead". If the optimization range is of one week, the need for reserve will be interpreted as "week-ahead". (Adequacy and Economy simulations) + +- DSM: power (decrease or increase) to add to the load. A negative value is a load decrease, a positive value is a load increase. Note that an efficient demand side management scheme may result in a negative overall sum (All simulation modes). + +## Links + +This window is used to handle all input data regarding the interconnections. On picking any interconnection in the primary list, the user gets direct access to all data regarding the link, which are five annual parameters, a set of six ready-made 8760-hour time-series, and a flexible number of ready-made 8760-hour time-series corresponding to the capacities of the links. + +- The five parameters, used in economy or adequacy simulations are displayed in the "Parameters" and in the "Transmission capacities" tab. They are namely: + + - "Hurdle cost": set by the user to state whether (linear) transmission fees should be taken into account or not in economy and adequacy simulations + - "Transmission capacities": set by the user to state whether the capacities to consider are those indicated in 8760-hour arrays or if zero or infinite values should be used instead (actual values / set to zero / set to infinite) + - "Asset type": set by the user to state whether the link is either an AC component (subject to Kirchhoff's laws), a DC component, or another type of asset + - "Account for loop flows": set by the KCG [^9] to include (or not) passive loop flows in the formulation of the constraints enforcing Kirchhoff's laws + - "Account for PST": set by the KCG to include (or not) the settings of phase-shifting transformers in the formulation of the constraints enforcing Kirchhoff's laws + +- The "Parameters" tab displays six 8760-hour times-series, which are: + + - Hurdle cost direct: an upstream-to-downstream transmission fee, in €/MWh + + - Hurdle cost indirect: a downstream-to-upstream transmission fee, in €/MWh + + - Impedance: used in economy simulations to give a physical meaning to raw outputs, when no binding constraints have been defined to enforce Kirchhoff's laws (see "Output" section, variable "Flow Quad") OR used by the Kirchhoff's constraint generator to build up proper flow constraints (AC flow computed with the classical "DC approximation"). Since voltage levels are not explicitly defined and handled within Antares, all impedances are assumed to be scaled to some reference $ U_{ref} $ + + - 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 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} $ + + +- The "Transmission capacities" tab displays "ready-made" 8760-hour time-series already available for simulation purposes. + In this tab, the table "Direct" describes the upstream-to-downstream capacity, in MW, and the table "Indirect" describes the downstream-to-upstream capacity, in MW. + _Please note that Time-Series analysis and generation is not available for capacity Time-Series._ + Different ways to update data are : + - direct typing + - copy/paste a selected field to/from the clipboard + - load/save all the time-series from/to a file (usually located in the "user" subfolder) + - Apply different functions (+,-, *, /,etc.) to the existing (possibly filtered) values (e.g. simulate a 2% growth rate by choosing "multiply-all-by-1.02") + - Handle the whole (unfiltered) existing dataset to either: + + - Change the number of columns (function name: resize) + - Adjust the values associated with the current first day of the year (function name: shift rows) + + Versatile "Filter" functions allow quick access to user-specified sections of data (e.g. display only the generation expected on Sundays at midnight, for all time-series). + +- _Note that:_ + + - _For a given link, the number of Time-Series for the direct and indirect capacity must be equal. Otherwise, an issue will be raised when launching a simulation_ + + - _If the "intra-modal correlated draws" option was not selected in the_ **simulation** _window, MC adequacy or economy simulations can take place even if the number of time-series for direct/indirect capacity is not the same for all links (e.g. 2 , 5 , 1 , 45 ,...)_ + + - _If the "intra-modal correlated draws" option was selected in the_ **simulation** _window, every link should have either one single time-series for both the direct and indirect capacity, or the same given number of time-series (e.g. 25 , 25 , 1 , 25...)_ + +## Binding constraints + +This section of the AntaresWeb interface for this section is used to handle all data regarding special constraints that one may wish to include in the formulation of the optimization problems to solve. + +The set of tabs described hereafter provides for that purpose all the means required to define arbitrary linear constraints on any subset of continuous variables involved in the modeling of the power system. + +Since no limitation is set on the number and content of the constraints that may be defined that way, it is the user's sole responsibility to make sure that these so-called "binding constraints" are realistic and meaningful, be it from a technical or economic standpoint. + +A typical situation in which this feature proves useful is, for instance, encountered when data at hand regarding the grid include an estimate of the impedances of the interconnections. + +In such cases, assuming that: + +- $Z_l$ denotes the impedance of interconnections $l=1, L$ +- A preliminary study of the graph modeling the grid has shown that it can be described by a set of independent meshes $c=1, C$(cycle basis of the graph) + +Then the DC flow approximation may be implemented, for each time-step of the simulation, by a set of C binding constraints between AC flows $F_l$: + +$$ 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)._ + +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]. + +More generally, Antares allows to define three categories of binding constraints between transmission flows and/or power generated from generating units: + +- "hourly" binding constraints, which are applied to instant power (transmitted and/or generated) + +- "daily" binding constraints, that are applied to daily energies. This class makes more sense for commercial modeling (say: imports and exports from/to such and such area should be comprised between such and such lower bound and upper bound). Daily binding constraints are also commonly used to model specific facilities, such as pumped storage units operated on a daily cycle + +- "weekly" binding constraints, that are applied to weekly energies. Like the previous ones, these constraints may be used to model commercial contracts or various phenomena, such as the operation of a pumped storage power plant operated on a weekly cycle. + +The Binding Constraints section of the AntaresWeb interface for this section involves six main tabs described hereafter: + +- **TAB "summary"** + Creation, edition or removal of a binding constraint. A binding constraint is here defined by four macroscopic attributes that can be set by the edit command: + + - Name (caption) + - Time-range (hourly, daily, weekly) + - Numerical type (equality, bounded above, below, on both sides) + - Status (active /enabled or inactive/disabled) + +- **TAB "weights"** + Definition of the coefficients given to each flow variable or generation variable in the formulation of the constraints. Two sub-tabs make it possible to handle the coefficients associated with transmission assets (links) and those associated with generation assets (thermal clusters). In both cases: + + - The lines of the tables show only the components (links or clusters) that are visible on the current map + - The columns of the tables show only the constraints that do not have non-zero weights attached to components that are nor visible on the current map + +- **TAB "offsets"** + Definition of the time-lag (in hours) assigned to each flow variable or generation variable in the formulation of the constraints. Two sub-tabs make it possible to handle the offsets associated with transmission assets (links) and those associated with generation assets (thermal clusters). In both cases: + + - The lines of the tables show only the components (links or clusters) that are visible on the current map + - The columns of the tables show only the constraints that do not have non-zero weights attached to components that are nor visible on the current map + +- **TAB "="** + Definition of the right-hand side of equality constraints. This RHS has either 8760 values (hourly constraints) or 365 values (daily or weekly constraints). Depending on the range actually chosen for the simplex optimization (see section **Configure** of the main menu), the weekly constraints RHS will either be represented by the sum of seven daily terms or by a set of seven daily terms (weekly constraint downgraded to daily status). + +- **TAB ">"** + Definition of the right-hand side of "bounded below" and "bounded on both sides" inequality constraints. This RHS has either 8760 values (hourly constraints) or 365 values (daily or weekly constraints). Depending on the range actually chosen for the simplex optimization (see section **Configure** of the main menu), the weekly constraints RHS will either be represented by the sum of seven daily terms or by a set of seven daily terms (weekly constraint downgraded to daily status). + +- **TAB "<"** + Definition of the right-hand side of "bounded above" and "bounded on both sides" inequality constraints. This RHS has either 8760 values (hourly constraints) or 365 values (daily or weekly constraints). Depending on the range actually chosen for the simplex optimization (see section **Configure** of the main menu), the weekly constraints RHS will either be represented by the sum of seven daily terms or by a set of seven daily terms (weekly constraint downgraded to daily status). + +_NOTE: The right-hand side of a binding constraint can be set to "inf" (for "bounded above" constraints) or "-inf" (for "bounded below" constraints) for any timestamp. In that case, the constraint will be ignored by the solver for this timestamp. Please note that it is the user's responsibility to ensure that these values are set in a consistent way._ + +**WARNING:** When some clusters are defined as being in must-run ("must-run" parameter set to "True"), these clusters are automatically removed from the binding constraints in order to avoid potential incompatibilities between these constraints and the power output imposed to the must-run clusters. The clusters which are removed from binding constraints are visible in the "Summary" tab, in which they are multiplied by N/As in the binding constraints. +In case a binding constraint only contains must-run clusters, it will be ignored in the simulation and subsequently identified as "Skipped" in the summary tab. +Please note that in the specific context of the adequacy simulation mode (in which all thermal clusters are considered as being fully must-run), **all thermal clusters will consequently be de-activated from the binding constraints**. This can lead to incorrect adequacy indicators in Antares studies containing binding constraints. + + +When defining binding constraints between (hourly) power, daily or weekly (energy) flows, special attention should be paid to potential conflicts between them or with the "basic" problem constraints. Lack of caution may result in situations for which the optimization has no solution. Consider for instance a case in which three variables X1, X2, X3 (whatever they physical meaning) are involved in the following binding constraints: + +$$X1 + X2 > 5$$ + +$$X2 < -3$$ + +$$X3 > 0$$ + +$$X1 + X3 < 7$$ + +These commitments are obviously impossible to meet and, if the economic simulator is run on a dataset including such a set of constraints, it will produce an infeasibility analysis that looks like the following. +``` +[solver][notic] Solver: Starting infeasibility analysis... +[solver][error] The following constraints are suspicious (first = most suspicious) +[solver][error] Hydro reservoir constraint at area 'Germany' at hour 124 +[solver][error] Hydro reservoir constraint at area 'Germany' at hour 128 +[solver][error] Hydro reservoir constraint at area 'Germany' at hour 137 +[solver][error] Hydro reservoir constraint at area 'Germany' at hour 140 +[solver][error] Hydro reservoir constraint at area 'Germany' at hour 133 +[solver][error] Hydro reservoir constraint at area 'Germany' at hour 139 +[solver][error] Hydro reservoir constraint at area 'Germany' at hour 136 +[solver][error] Hydro reservoir constraint at area 'Germany' at hour 130 +[solver][error] Hydro reservoir constraint at area 'Germany' at hour 142 +[solver][error] Hydro reservoir constraint at area 'Germany' at hour 123 +``` + +This report should help you identify constraints that generate infeasible linear optimization problems such what is presented above. + +The advanced preference "Unfeasible Problems Behavior" gives to the user the ability to choose between four different strategies regarding these situations. + +## Economic Opt. + +This window is used to set the value of a number of area-related parameters that, aside from the costs of each generating plant, define the optimal solution that Antares has to find in economic simulations. These parameters are namely, for each area of the system: + +- The value of the unsupplied energy (also commonly denoted Value Of Lost Load,VOLL) , in €/MWh. This value should usually be set much higher than the cost of the most expensive generating plant of the area + +- The random spread within which the nominal unsupplied energy value is assumed to vary + +- The value of the spilled energy, in € /MWh. This value reflects the specific penalty that should be added to the economic function for each wasted MWh, if any. Note that even if this value is set to zero no energy will be shed needlessly + +- The random spread within which the nominal unsupplied energy value is assumed to vary + +- Three parameters named "shedding status" and related to different kinds of generation. If the system cannot be balanced without shedding some generation, these parameters give control on how each kind of generation ("Non dispatchable power","Dispatchable hydropower" and "Other dispatchable generating plants") should contribute to the shedding. Depending on the value chosen for the status, the generation can or cannot be shed to find a solution to the load/generation balance problem. Note that enforcing a negative status for all types of plants may lead to simulations scenarios for which there are no mathematical solutions. + +On running the economic simulator, such situations produce an infeasibility diagnosis. + +[^9]: KCG : Kirchhoff's constraints generator (see section 7) + +[^10]: A typical case is given by the "Flow-Based" framework today implemented in a large portion of the European electricity market. + +## System Maps + +This window is used to define the general structure of the system, i.e. the list of areas and that of the interconnections. +Only the area's names, location and the topology of the grid are defined at this stage. Different colors may be assigned +to different areas. These colors may later be used as sorting options in most windows. They are useful to edit data in a +fashion that has a geographic meaning (which the lexicographic order may not have). This window displays copy/paste/select +all icons equivalent to the relevant EDIT menu commands. + +The top left side of the window shows a "mouse status" field with three icons. These icons (one for nodes, one for links +and one for binding constraints) indicate whether a selection made on the map with the mouse will involve or not the +related elements. When a copy/paste action is considered, this allows for instance to copy any combination of nodes, +links and binding constraints. Status can be changed by toggling the icons. Default is "on" for the three icons. Two +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". diff --git a/docs/user-guide/solver/03-outputs.md b/docs/user-guide/solver/03-outputs.md new file mode 100644 index 0000000000..cd79b2fdb4 --- /dev/null +++ b/docs/user-guide/solver/03-outputs.md @@ -0,0 +1,256 @@ +# Output files + +[//]: # (TODO: update this page, list all output files) +_**This section is under construction**_ + +The general file organization is the same for Economy and Adequacy simulations. +**\\** + +**Economy:** + +| OUTPUT/Simu id/economy/mc-all/ | | | | +|--------------------------------|----------------------|-----------------|------------------------------------------| +| | /grid/... | | contains a summary file "digest.txt" | +| | /areas/name/... | | contains area-related results | +| | /links / name/... | | contains interconnection-related results | +| | /mc-ind /year_number | | | +| | | /areas/name/... | contains area-related results | +| | | /links/name/... | contains interconnection-related results | + +_("mc-all" files contain synthetic results over all years, "year-number" files contain results for a single year)_ +_The variables present in each file are detailed in the following sections._ +_In "Economy" simulations, all variables have a techno-economic meaning._ + +**Adequacy:** + +| OUTPUT/Simu id/adequacy/mc-all/ | | | | +|---------------------------------|----------------------|-----------------|------------------------------------------| +| | /grid/... | | contains a summary file "digest.txt" | +| | /areas/name/... | | contains area-related results | +| | /links / name/... | | contains interconnection-related results | +| | /mc-ind /year_number | | | +| | | /areas/name/... | contains area-related results | +| | | /links/name/... | contains interconnection-related results | + +_("mc-all" files contain synthetic results over all years, "year-number" files contain results for a single year)_ +_The variables present in each file bear exactly the same name as in Economy simulations but do not have the same values._ +_The only variables that have a techno-economic meaning are the "Adequacy" indicators (unsupplied energy,LOLD,LOLP)_ + +**IMPORTANT** Adequacy and Economy files look the same but their content are specific + +In "Economy" and "Adequacy" simulations, the optimization ignores the "primary" and "strategic" reserves (however, it may include the [other] spinning and day-ahead reserves, depending on the settings made in "optimization preferences"). + +In "Adequacy" simulations, all dispatchable thermal units are given the "must-run" status (hence, they will generate at Pmax, regardless of the demand). As a consequence the only variables that are actually meaningful are the adequacy indicators (unsupplied energy, LOLD,LOLP), that may depend on assumptions made regarding the economic values of Unsupplied and spilled energies, and on hurdle costs on interconnections. +In the specific case where binding constraints are present in the study, **all thermal clusters will consequently be de-activated from the binding constraints**. This can lead to incorrect adequacy indicators in Antares studies containing binding constraints in "Adequacy" simulations. + +As a consequence, both "Adequacy" and "Economy" simulations yield the same values for the adequacy indicators under the following conditions: if hurdle costs on interconnections are higher than the difference between the maximum VOLL and the minimum VOLL assigned to the different areas of the system, and if no binding constraint is altered due to the fact that they contain clusters in must-run. + +The files and their content are hereafter described. + +## Economy and Adequacy, area results [^11] + +**25** files resulting from the combination of the following attributes: +**[values | id | details | details-res | details-STstorage] X [hourly | daily | weekly | monthly | annual]** + +- The second attribute defines the time span over which the results are assessed: hourly detail, daily bundle, weekly bundle, monthly bundle, annual bundle. + +- The first attribute defines the nature of the results presented in the file : + +**Values** Values of different variables (price, load, overall generation issued from coal, etc.), the list of which is common to all areas of the interconnected system. Files of type "values" have therefore the same size for all areas. +These results appear under the label "general values" in the output GUI. + +**details** Values regarding the different dispatchable thermal generating plants of each area (e.g. "older 300 MW coal from the south coast"). The sizes of these files differ from one area to another. +These results appear under the label "thermal plants" in the output GUI. + +**details-res** Values regarding the different renewable clusters of each area. The sizes of these files differ from one area to another. +These results appear under the label "Ren. clusters" in the output GUI. + +**details-STstorage** Values regarding the different short-term storages of each area. The sizes of these files differ from one area to another. +These results appear under the label "ST storages" in the output GUI. + +**id** Identifier (number) of the Monte-Carlo years for which were observed the extreme values of the different variables presented in the « values » files +These results appear under the label "record years" in the output GUI + +The area files that belong to the "values" class display fields corresponding to the expectation, standard deviation, minimal and maximal values of the variables whose list is given hereafter. + +| variables | description | +|----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| OV.COST | Overall cost = operating cost + unsupplied cost+ spilled cost+ hydro cost | +| OP.COST | Operating cost = Proportional costs + Non- proportional costs | +| MRG. PRICE | LMP : overall economic effect of a local 1MW load increase | +| CO2, NH3, SO2, ... EMIS. | Amount emitted by all dispatchable thermal plants for the following types of pollutants: CO2, SO2, NH3, NOX, PM2\_5, PM5, PM10, NMVOC, OP1, OP2, OP3, OP4, OP5 EMIS. | +| BALANCE | Overall Import/export balance of the area (positive value : export) | +| ROW BAL | Import/export with areas outside the modeled system (positive value: import) [^12] | +| PSP | User-defined settings for pumping and subsequent generating | +| MISC. NDG | Miscellaneous non dispatchable generation | +| LOAD | Demand (including DSM potential if relevant) | +| H.ROR | Hydro generation, Run-of-river share | +| WIND | Wind generation (only when using aggregated _Renewable generation modeling_) | +| SOLAR | Solar generation (thermal and PV) (only when using aggregated _Renewable generation modeling_) | +| NUCLEAR | Overall generation of nuclear clusters | +| LIGNITE | Overall generation of dispatchable thermal clusters burning brown coal | +| COAL | Overall generation of dispatchable thermal clusters burning hard coal | +| GAS | Overall generation of dispatchable thermal clusters burning gas | +| OIL | Overall generation of dispatchable thermal clusters using petroleum products | +| MIX.FUEL | Overall gen. of disp. thermal clusters using a mix of the previous fuels | +| MISC.DTG | Overall gen. of disp. thermal clusters using other fuels | +| MISC.DTG 2 | Overall gen. of disp. thermal clusters using other fuels | +| MISC.DTG 3 | Overall gen. of disp. thermal clusters using other fuels | +| MISC.DTG 4 | Overall gen. of disp. thermal clusters using other fuels | +| WIND OFFSHORE | Wind Offshore generation (only when using clustered _Renewable generation modeling_) | +| WIND ONSHORE | Wind Onshore generation (only when using clustered _Renewable generation modeling_) | +| SOLAR CONCRT. | Concentrated Solar Thermal generation (only when using clustered _Renewable generation modeling_) | +| SOLAR PV | Solar Photovoltaic generation (only when using clustered _Renewable generation modeling_) | +| SOLAR ROOFT | Rooftop Solar generation (only when using clustered _Renewable generation modeling_) | +| RENW. 1 | Overall generation of other Renewable clusters (only when using clustered _Renewable generation modeling_) | +| RENW. 2 | Overall generation of other Renewable clusters (only when using clustered _Renewable generation modeling_) | +| RENW. 3 | Overall generation of other Renewable clusters (only when using clustered _Renewable generation modeling_) | +| RENW. 4 | Overall generation of other Renewable clusters (only when using clustered _Renewable generation modeling_) | +| H.STOR | Power generated from energy storage units (typically: Hydro reservoir) | +| H.PUMP | Power absorbed by energy storage units (typically: PSP pumps consumption) | +| H.LEV | Energy level remaining in storage units (percentage of reservoir size) | +| H.INFL | External input to the energy storage units (typically: natural inflows) | +| H.OVFL | Wasted natural inflow overflowing from an already full energy storage unit | +| H.VAL | Marginal value of stored energy (typically: shadow water value) | +| H.COST | Expenses /Income brought by energy storage actions (H.STOR,H.PUMP) | +| UNSP. ENRG | Unsupplied energy: adequacy indicator (Expected Energy Not Served–EENS) | +| SPIL. ENRG | Spilled energy (energy produced that cannot be used and has to be wasted) | +| LOLD | Loss of load duration: adequacy indicator (length of shortfalls) | +| LOLP | Loss of Load probability: adequacy indicator (probability of at least one hour of shortfall within the considered period, without normalization by the duration of the considered period) | +| AVL. DTG | Available dispatchable thermal generation (sum of av. power over all plants) | +| DTG. MRG | Disp. Ther. Gen. (AVL DTG – sum of all dispatched thermal generation) | +| MAX. MRG | Maximum margin: operational margin obtained if the hydro storage energy of the week were used to maximise margins instead of minimizing costs | +| DENS | Domestic Energy Not Supplied: the difference between the local production capabilities of an area and its local load[^adqp] | +| LMR. VIOL | Local Matching Rule Violation after the Antares Simulation as defined by the adequacy patch[^adqp] | +| SPIL. ENRG. CSR | Spilled Energy after the Curtailment Sharing Rule step of the dequacy patch[^adqp] | +| _injection | Injection of energy from the area into each short-term storage group | +| _withdrawal | Withdrawal of energy from each short-term storage group into the area | +| _level | Average level of each short-term storage group | +| NP COST | Non-proportional costs of the dispatchable plants (start-up and fixed costs) | +| NODU | Number of Dispatched Units [^13] | +| Profit | Net profit of the cluster in euros ((MRG. PRICE - marginal cost of the cluster) * (dispatchable production of the cluster)[^15] | +| ,P-injection | Injection of energy from the area into the short-term storage | +| ,P-withdrawal | Withdrawal of energy the short-term storage into the area | +| ,Levels | Level of the short-term storage | + +_Note: The net profit is computed on full precision values for MRG. PRICE. The user may obtain slightly different results applying the given formula because MRG. PRICE values are rounded to 10^-2._ + +## Economy and Adequacy, interconnection results [^14] +**10** files resulting from the combination of the following attributes: +**[values | id] X [hourly | daily | weekly | monthly | annual]** + +- The second attribute defines the period of time over which the results are assessed: hourly detail, daily bundle, weekly bundle, monthly bundle, annual bundle. +- The first attribute defines the nature of the results presented in the file. + + +**values** values of different variables (flow, congestion rent) the list of which is common to all interconnections. The files of type "values" have therefore the same size everywhere +These results appear under the label "general values" in the output GUI. + +**id** identifier (number) of the Monte-Carlo years for which were observed the extreme values of the different variables presented in the « values » files. +These results appear under the label "record years" in the output GUI. + + +The area files that belong to the « values » class display **28** fields corresponding to the expectation, standard deviation, minimal and maximal values of the variables whose list is given hereafter. + +| variables | description | +|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| FLOW LIN. | Flow (signed + from upstream to downstream) assessed by the linear optimization. These flows follow Kirchhoff's law only if these laws have been explicitly enforced by the means of suitable binding constraints | +| UCAP | Used capacity: absolute value of FLOW LIN. This indicator may be of interest to differentiate the behavior of interconnectors showing low average flows: in some cases this may indicate that the line is little used, while in others this may be the outcome of high symmetric flows | +| LOOP FLOW | Flow circulating through the grid when all areas have a zero import/export balance. This flow, to be put down to the simplification of the real grid, is not subject to hurdle costs in the course of the optimization | +| FLOW QUAD. | Flow computed anew, starting from the linear optimum, by minimizing a quadratic function equivalent to an amount of Joule losses, while staying within the transmission capacity limits. This calculation uses for this purpose the impedances found in the "Links" Input data. If congestions occur on the grid, these results are not equivalent to those of a DC load flow | +| CONG. FEE ALG | Algebraic congestion rent = linear flow \* (downstream price – upstream price) | +| CONG. FEE ABS | Absolute congestion rent = linear flow\* abs(downstream price–upstream price) | +| MARG. COST | Decrease of the system's overall cost that would be brought by the optimal use of an additional 1 MW transmission capacity (in both directions) | +| CONG PROB + | Up>Dwn Congestion probability = (NC+) / (total number of MC years) with:
NC+ = number of years during which the interconnection was congested in the Up>Dwn way for **any** length of time within the time frame relevant with the file | +| CONG PROB - | Dwn>Up Congestion probability = (NC-) / (total number of MC years) with:
NC- = number of years during which the interconnection was congested in the Dwn>Up way for **any** length of time within the time frame relevant with the file | +| HURD. COST | Contribution of the flows to the overall economic function through the "hurdles costs" component. For each hour:
`if (FLOW.LIN –LOOP FLOW) > 0 `
`HURD. COST = (hourly direct hurdle cost) * (FLOW LIN.)`
`else HURD.COST = (hourly indirect hurdle cost) * (-1) * (FLOW LIN.)` | + +## Economy and Adequacy, other results + +Depending on the options chosen in the main simulation window, the output folders may also include either, both or none of the following sections: + +| OUTPUT/Simu id/ts-numbers/ | | | +|----------------------------|-------------------|------------------| +| | /Load | /area names/... | +| | /Thermal | /area names/... | +| | /Hydro | /area names/... | +| | /Wind[^agg] | /area names/... | +| | /Solar[^agg] | /area names/... | +| | /Renewables[^ren] | /area names/... | +| | /NTC | /area names/... | + +These files contain, for each kind of time-series, the number drawn (randomly or not) in each Monte-Carlo year (files are present if "output profile / MC scenarios" was set to "true"). + +| OUTPUT/Simu id/ts-generator/ | | | +|------------------------------|--------------|------------------------------| +| | /Load | /batch number/area names/... | +| | /Hydro | /batch number/area names/... | +| | /Wind[^agg] | /batch number/area names/... | +| | /Solar[^agg] | /batch number/area names/... | + + +These files contain, for each kind of Antares-generated time-series, copies of the whole set of time-series generated. Batch numbers depend on the values set for the "refresh span" parameters of the stochastic generators (files are present if "store in output" was set to "true"). + +## Miscellaneous + +Alike Input data, output results can be filtered so as to include only items that are associated with Areas and Links defined as "visible" in the current map. In addition, the output filtering dialog box makes it possible to filter according to two special categories (**Districts** and **Unknown**) that are not related to standard maps: + +- **Districts** displays only results obtained for spatial aggregates +- **Unknown** displays only results attached to Areas or Links that no longer exist in the Input dataset (i.e. study has changed since the last simulation) + +[^11]: This description applies to both « MC synthesis » files and "Year-by-Year" files, with some simplifications in the latter case + +[^12]: Value identical to that defined under the same name in the "Misc Gen" input section. + +[^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)) + +[^14]: This description applies to both « MC synthesis » files and "Year-by-Year" files, with some simplifications in the latter case + +[^agg]: This output is only available if the parameter "renewable generation modelling" is set to "cluster" in the input of the simulation + +[^ren]: This output is only available if the parameter "renewable generation modelling" is set to "aggregated" in the input of the simulation + +[^15]: dispatchable production = power generation above min gen = (power generation) - (min gen modulation)*units*capacity + +### The Annual System Cost Output file + +In addition to the general files introduced in [Output Files](03-outputs.md), the Output folder of each economic or adequacy simulation includes, at its root, a file "Annual\_System\_Cost.txt" It presents the metrics of a global Monte-Carlo variable further denoted ASC. + +The value of ASC for any given simulated year is defined as the sum, over all areas and links, of the annual values of the area-variable "OV.COST" and of the link-variable "HURD. COST". + +The metrics displayed in the "Annual system cost" file take the form of four values: + +- Expectation EASC + +- Standard deviation SASC + +- Minimum LASC + +- Maximum UASC + +As with all other random variables displayed in the Antares Output section, the computed standard deviation of the variable can be used to give a measure of the confidence interval attached to the estimate of the expectation. For a number of Monte-Carlo years N, the law of large numbers states for instance that there is a 95 % probability for the actual expectation of ASC to lie within the interval: + +
**EASC +/- 1.96 (SASC / sqrt(N))**
+ +There is also a 99.8 % probability that it lies within the interval: + +
**EASC +/- 3 (SASC / sqrt(N))**
+ +### Changelog +Here is a list of new output variables in recent versions: + +| Version | Variable(s) introduced | Files | Enabled by default | +|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------|--------------------| +| 8.0 | none | | | +| 8.1 | WIND OFFSHORE, WIND ONSHORE, SOLAR CONCRT., SOLAR PV, SOLAR ROOFT, RENW. 1, RENW. 2, RENW. 3, RENW. 4 | values-*.txt | yes | +| 8.1 | MISC. DTG 2, MISC. DTG 3, MISC. DTG 4 | values-*.txt | yes | +| 8.2 | none | | | +| 8.3 | DENS | values-*.txt | no | +| 8.3 | Profit by plant | details-*.txt | yes | +| 8.4 | BC. MARG. COST | binding-constraints-*.txt | no | +| 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 | diff --git a/docs/user-guide/solver/04-parameters.md b/docs/user-guide/solver/04-parameters.md new file mode 100644 index 0000000000..7c0515c420 --- /dev/null +++ b/docs/user-guide/solver/04-parameters.md @@ -0,0 +1,844 @@ +# Parameters + +[//]: # (TODO: complete this page) +_**This section is under construction**_ + +An *Antares* study contains a global parameter file named `generaldata.ini`. + +--- +## General parameters +These parameters are listed under the `[general]` section in the `.ini` file. + +--- +### Study mode + +--- +#### mode +[//]: # (TODO: verify if required, remove default value) +[//]: # (TODO: add details 'expansion' behavior) +- **Expected value:** one of the following (case-insensitive): + - `economy` or `economic` + - `adequacy` + - `expansion` +- **Required:** **yes** +- **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 + *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 + 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. + +--- +### Study horizon + +--- +#### horizon +[//]: # (TODO: verify if required, remove default value) +- **Expected value:** year (string) +- **Required:** **yes** +- **Default value:** empty string +- **Usage:** the horizon of the study (static tag, not used in the calculations) + +--- + +### Calendar parameters + +--- +#### nbyears +[//]: # (TODO: verify if required, verify default value) +- **Expected value:** unsigned integer +- **Required:** **yes** +- **Default value:** +- **Usage:** number of Monte-Carlo (MC) years that should be prepared for the simulation (not always the same as the + MC years actually simulated, which are defined by [user-playlist](#user-playlist) and [playlist parameters](#playlist-parameters)). + +--- +#### simulation.start +[//]: # (TODO: verify if required, verify default value) +[//]: # (TODO: verify if index 8 should be replaced by 7 in example -starts at 1 or at 0 ?-) +- **Expected value:** unsigned integer +- **Required:** **yes** +- **Default value:** 0 +- **Usage:** index of first day to include in study (>= 0) (e.g. 8 for a simulation beginning on the + second week of the first month of the year) + +--- +#### simulation.end +[//]: # (TODO: verify if required, verify default value) +[//]: # (TODO: verify if index starts at 1 or at 0 for example) +- **Expected value:** unsigned integer +- **Required:** **yes** +- **Default value:** 365 +- **Usage:** index of last day to include in study (<= 365) (e.g. 28 for a simulation ending on the fourth week + of the first month of the year) + +> _**Note:**_ +> In Economy an Adequacy [simulation modes](#mode), simulation start & end must be chosen to make the simulation span a +> round number of weeks. If not, the simulation span will be truncated: for instance, (1, 365) will be interpreted as +> (1, 364), i.e. 52 weeks (the last day of the last month will not be simulated). + +--- +#### january.1st +[//]: # (TODO: verify default value) +- **Expected value:** string carrying an integer between 0 and 6, or one of (case-insensitive): `monday`/`lundi`, + `tuesday`/`mardi`, `wednesday`/`mercredi`, `thursday`/`jeudi`, `friday`/`vendredi`, `saturday`/`samedi`, + `sunday`/`dimanche`. +- **Required:** no +- **Default value:** `monday` +- **Usage:** this parameter should indicate the day-of-week of january 1st of the given [year](#horizon). + +--- +#### first-month-in-year +[//]: # (TODO: verify if required, remove default value) +- **Expected value:** one of the following string (case-insensitive): `jan`/`january`, `feb`/`february`, `mar`/`march`, + `apr`/`april`, `may`, `jun`/`june`, `jul`/`july`, `aug`/`august`, `sep`/`september`, `oct`/`october`, + `nov`/`november`, `dec`/`december`. +- **Required:** **yes** +- **Default value:** +- **Usage:** this is the first month in the input time-series, of the studied [year](#horizon). + +--- +#### first.weekday +- **Expected value:** string carrying an integer between 0 and 6, or one of (case-insensitive): `monday`/`lundi`, + `tuesday`/`mardi`, `wednesday`/`mercredi`, `thursday`/`jeudi`, `friday`/`vendredi`, `saturday`/`samedi`, + `sunday`/`dimanche`. +- **Required:** no +- **Default value:** `monday` +- **Usage:** in economy or adequacy simulations, indicates the frame (Mon-Sun, Sat-Fri, etc.) to use for the edition + of weekly results. + +--- +#### leapyear +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `false` +- **Usage:** indicates if the studied [year](#horizon) is a leap-year. + +--- +### Additional parameters + +--- +#### year-by-year +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `false` +- **Usage:** + - `false`: no individual results will be printed out + - `true`: for each simulated year, detailed results will be printed out in an individual directory: + `Study_name/OUTPUT/simu_tag/Economy/mc-i-number + +--- +#### derated +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `false` +- **Usage:** if set to `true`, all time-series will be replaced by their general average and the number of MC years + set to 1. If the TS are ready-made or Antares-generated but are not to be stored in the INPUT folder, + no time-series will be written over the original ones (if any). If the time-series are built by Antares + and if it is specified that they should be stored in the INPUT, a single average-out time series will be stored + instead of the whole set. + +> _**WARNING:**_ this parameter cannot be used with parameter [custom-scenario](#custom-scenario) + +--- +#### custom-scenario +[//]: # (TODO: add specific link to "scenario builder") +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `false` +- **Usage:** + - `false`: for all years to simulate, all time-series will be drawn at random + - `true`: the simulation will be carried out on a mix of deterministic and probabilistic conditions, + with some time-series randomly drawn and others set to user-defined values. This option allows setting + up detailed "what if" simulations that may help to understand the phenomena at work and quantify various kinds + of risk indicators. To set up the simulation profile, use the [scenario builder](02-inputs.md). + +> _**WARNING:**_ this parameter cannot be used with parameter [derated](#derated) +> _**WARNING:**_ if set to `true`, parameter [active-rules-scenario](#active-rules-scenario) must be set + +--- +#### user-playlist +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `false` +- **Usage:** + - `false`: all prepared Monte-Carlo (MC) years will actually be simulated. + - `true`: the years to simulate are defined in a list. To set up this list, use the [playlist parameters](#playlist-parameters). + This feature allows, for instance, to refine a previous simulation by excluding a small number of "raw" MC years + 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) + +> _**WARNING:**_ this parameter cannot be used with parameter [derated](#derated) + +--- +#### thematic-trimming +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `false` +- **Usage:** set to `true` in order to select a specific subset of the optimization variables to print in the [output files](03-outputs.md), + using a thematic filter. Use the [variables selection parameters](#variables-selection-parameters) to define the filter. + Thematic Trimming does not reduce computation time, but can bring some benefits on total runtime (smaller files to + write). It can save a lot of disk space in simulations where only a few variables are of interest. + +--- +#### geographic-trimming +[//]: # (TODO: verify usage) +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `false` +- **Usage:** + Allows to select the results to store at the end of a simulation: choice of areas, interconnections, temporal + aggregations (hourly, daily, etc.). + Geographic Trimming does not reduce computation time, but can bring some benefits on total runtime (fewer files to + write). It can save a lot of disk space in simulations where only a few Areas and Links are of interest. + - **None** Storage of results for all areas, geographic districts, interconnections as well as all time spans + (hourly, daily, etc.) + - **Custom** Storage of the results selected with the "Geographic Trimming" command of the "Configure" + option available in the main menu. + Filters on areas, interconnections and time spans may also be defined as follows: + - On the map, select area(s) and/or interconnection(s) + - Open the inspector module (Main menu, Windows) + - Set adequate parameters in the "output print status" group + +--- +#### active-rules-scenario +[//]: # (TODO: add usage details) +- **Expected value:** undefined, or `default ruleset` (case-insensitive) +- **Required:** no, unless [custom-scenario](#custom-scenario) is set to `true` +- **Default value:** undefined +- **Usage:** defines how scenarios are built. Only one supported value for now: + - `default ruleset` + +--- +### Pre-processor parameters + +--- +#### readonly +[//]: # (TODO: add usage details) +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `false` +- **Usage:** sets the study to read-only mode + +--- +## Output parameters +These parameters are listed under the `[output]` section in the `.ini` file. + +--- +#### synthesis +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `true` +- **Usage:** + - `true`: synthetic results will be stored in a directory: `Study_name/OUTPUT/simu_tag/Economy/mc-all` + - `false`: no general synthesis will be printed out + +--- +#### storenewset +[//]: # (TODO: verify usage) +[//]: # (TODO: link to specific output folder when it is documented in Outputs doc) +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `false` +- **Usage:** + - `false`: no storage of the time-series numbers (either randomly drawn or user-defined) used to set up the simulation. + - `true`: a [specific output folder](03-outputs.md) will be created to store all the time-series numbers drawn + when preparing the Monte-Carlo years. + +--- +#### hydro-debug +[//]: # (TODO: document this parameter) +_**This section is under construction**_ + +- **Expected value:** +- **Required:** **yes** +- **Default value:** +- **Usage:** + +--- +#### result-format +[//]: # (TODO: document this parameter) +_**This section is under construction**_ + +- **Expected value:** +- **Required:** **yes** +- **Default value:** +- **Usage:** + +--- +#### archives +[//]: # (TODO: fill default value) +- **Expected value:** comma-seperated list of 0 to N elements among the following (case-insensitive): + `load`, `wind`, `hydro`, `thermal`, `solar`, `renewables`, `ntc`, `max-power` +- **Required:** no +- **Default value:** +- **Usage:** if [storenewset](#storenewset) is set to `true`, this parameter selects those of them that should be + written in the [output files](03-outputs.md). + +--- +## Optimization parameters +[//]: # (TODO: add link to "local parameter values" documentation) +Options related to the optimization core used in the simulations. +This set of parameters is study-specific; it can be changed at any time and saved along with study data. +The values set in this file take precedence over the local parameter values. For instance, if the LOCAL +parameter "set to infinite" is activated for some interconnections, and if the GLOBAL preference regarding transmission +capacities is "set to null", the simulation will be carried out as if there were no longer any grid BUT the local +values will remain untouched. If the preference is afterward set to "local values", the interconnections will be +given back their regular capacities (infinite for those being set on "set to infinite"). +These parameters are listed under the `[optimization]` section in the `.ini` file. + +--- +#### simplex-range +- **Expected value:** `day` or `week` +- **Required:** no +- **Default value:** `week` +- **Usage:** the simplex optimization range. + In the formulation of the optimal hydro-thermal unit-commitment and dispatch problem (see dedicated document), + the reference hydro energy $HIT$ used to set the right hand sides of hydro- constraints depends on the value + chosen for this parameter, and is defined as follows: + - `day`: for each day **d** of week $\omega$ : $HIT = W_d^2$ + - `week`: for week $\omega$: $HIT = \sum_{d\in \omega}{W_d^2}$ + Weekly optimization performs a more refined unit commitment, especially when [unit-commitment-mode](#unit-commitment-mode) + is set to `accurate`. + +> More information here: [The heuristic for seasonal hydro pre-allocation](06-hydro-heuristics.md#seasonal-hydro-pre-allocation) + +--- +#### transmission-capacities +- **Expected value:** one of the following (case-insensitive): + - `local-values` + - `null-for-all-links` + - `infinite-for-all-links` + - `infinite-for-physical-links` + - `null-for-physical-links` +- **Required:** no +- **Default value:** `local-values` +- **Usage:** allows the user to override the transmission capacities on links. + - `local-values`: use the local property for all links, including physical links (no override) + - `null-for-all-links`: override all transmission capacities with 0 + - `infinite-for-all-links`: override all transmission capacities with $\inf$ + - `infinite-for-physical-links`: override transmission capacities with $\inf$ on **physical links only** + - `null-for-physical-links`: override transmission capacities with 0 on **physical links only** + +--- +#### link-type +[//]: # (TODO: document this parameter, seems to belong to another category) +_**This section is under construction**_ + +- **Expected value:** +- **Required:** **yes** +- **Default value:** +- **Usage:** + +> _**WARNING:**_ this parameter is ignored since version 8.5.2 + +--- +#### include-constraints +[//]: # (TODO: add link to binding constraints doc) +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `true` +- **Usage:** set this parameter to `true` if you want to activate binding constraints in the study. + +--- +#### include-hurdlecosts +[//]: # (TODO: document usage) +_**This section is under construction**_ + +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `true` +- **Usage:** + +--- +#### include-loopflowfee +[//]: # (TODO: document this parameter, seems to be deprecated) +_**This section is under construction**_ + +- **Expected value:** +- **Required:** **yes** +- **Default value:** +- **Usage:** + +--- +#### include-tc-minstablepower +[//]: # (TODO: add link to contraints doc) +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `true` +- **Usage:** set this parameter to `true` if you want to activate, for thermal units, the constraint of minimum stable power + +--- +#### include-tc-min-ud-time +[//]: # (TODO: add link to contraints doc) +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `true` +- **Usage:** set this parameter to `true` if you want to activate, for thermal units, the constraint of minimum start-up time + +--- +#### include-dayahead +[//]: # (TODO: add details + link to contraints doc) +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `true` +- **Usage:** set this parameter to `true` if you want to activate day-ahead reserve constraints + +--- +#### include-strategicreserve +[//]: # (TODO: add details + link to contraints doc) +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `true` +- **Usage:** set this parameter to `true` if you want to activate strategic reserve constraints + +--- +#### include-spinningreserve +[//]: # (TODO: add details + link to contraints doc) +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `true` +- **Usage:** set this parameter to `true` if you want to activate spinning reserve constraints + +--- +#### include-primaryreserve +[//]: # (TODO: add details + link to contraints doc) +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `true` +- **Usage:** set this parameter to `true` if you want to activate primary reserve constraints + +--- +#### include-exportmps +[//]: # (TODO: in usage paragraph, add links to relevant doc of "first step" and "second step" of optimization) +- **Expected value:** one of the following (case-insensitive): + - `none` or `false` + - `optim-1` + - `optim-2` + - `both-optims` or `true` +- **Required:** no +- **Default value:** `none/false` +- **Usage:** use this parameter if you want to export the optimization problems in [MPS format](https://en.wikipedia.org/wiki/MPS_(format)): + - `none` or `false`: do not export any MPS + - `optim-1`: export MPS for firt step of the optimization + - `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). + +--- +#### include-split-exported-mps +[//]: # (TODO: document this parameter, seems to belong to another category) +_**This section is under construction**_ + +- **Expected value:** +- **Required:** **yes** +- **Default value:** +- **Usage:** + +> _**WARNING:**_ this parameter is deprecated but is still needed for testing old studies + +--- +#### include-exportstructure +[//]: # (TODO: add link to AntaresXpansion) +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `false` +- **Usage:** set to `true` to activate writing the [MPS](#include-exportmps) using the *AntaresXpansion* specific format + +--- +#### include-unfeasible-problem-behavior +- **Expected value:** one of the following (case-sensitive): + - `WARNING_DRY` + - `WARNING_MPS` + - `ERROR_DRY` + - `ERROR_MPS` +- **Required:** no +- **Default value:** `ERROR_MPS` +- **Usage:** defines the behavior of the simulator in case of an unfeasible problem. + - `WARNING_DRY`: continue simulation + - `WARNING_MPS`: continue simulation, but export the MPS of the unfeasible problem + - `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). + +--- +#### solver-parameters +[//]: # (TODO: document this parameter) +_**This section is under construction**_ + +- **Expected value:** +- **Required:** **yes** +- **Default value:** +- **Usage:** + +--- +## Adequacy-patch parameters +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. + +--- +#### include-adq-patch +- **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. + +--- +#### set-to-null-ntc-from-physical-out-to-physical-in-for-first-step +[//]: # (TODO: usage is not clear) +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `true` +- **Usage:** Transmission capacities from physical areas outside adequacy patch (area type 1) to physical areas + inside adequacy patch (area type 2). NTC is set to null (if true) only in the first step of adequacy patch local matching rule. + NTC from physical areas outside to physical areas inside adequacy patch (set to null / local values) + +--- +#### set-to-null-ntc-between-physical-out-for-first-step +[//]: # (TODO: usage is not clear) +- **Expected value:** `true` or `false` +- **Required:** no +- **Default value:** `true` +- **Usage:** Transmission capacities between physical areas outside adequacy patch (area type 1). + NTC is set to null (if true) only in the first step of adequacy patch local matching rule. + NTC between physical areas outside adequacy patch (set to null / local values) + +--- +#### price-taking-order +[//]: # (TODO: document this parameter) +_**This section is under construction**_ + +- **Expected value:** +- **Required:** **yes** +- **Default value:** +- **Usage:** Price taking order (DENS / Load) + +--- +#### include-hurdle-cost-csr +[//]: # (TODO: document this parameter) +_**This section is under construction**_ + +- **Expected value:** +- **Required:** **yes** +- **Default value:** +- **Usage:** Include hurdle cost in CSR optimization (false / true) + +--- +#### check-csr-cost-function +[//]: # (TODO: document this parameter) +_**This section is under construction**_ + +- **Expected value:** +- **Required:** **yes** +- **Default value:** +- **Usage:** Check CSR cost function value prior and after CSR (false / true) + +--- +#### enable-first-step +[//]: # (TODO: document this parameter) +_**This section is under construction**_ + +- **Expected value:** +- **Required:** **yes** +- **Default value:** +- **Usage:** + +--- +#### threshold-initiate-curtailment-sharing-rule +[//]: # (TODO: document this parameter) +_**This section is under construction**_ + +- **Expected value:** +- **Required:** **yes** +- **Default value:** +- **Usage:** + +--- +#### threshold-display-local-matching-rule-violations +[//]: # (TODO: document this parameter) +_**This section is under construction**_ + +- **Expected value:** +- **Required:** **yes** +- **Default value:** +- **Usage:** + +--- +#### threshold-csr-variable-bounds-relaxation +[//]: # (TODO: document this parameter) +_**This section is under construction**_ + +- **Expected value:** +- **Required:** **yes** +- **Default value:** +- **Usage:** + +--- +## Other parameters +These parameters are listed under the `[other preferences]` section in the `.ini` file. + +--- +#### initial-reservoir-levels +[//]: # (TODO: complete the usage paragraph) +- **Expected value:** one of the following (case-insensitive): + - `cold start` + - `hot start` +- **Required:** no +- **Default value:** `cold start` +- **Usage:** initial reservoir levels: + - `cold start` + - `hot start` + +> _**Note:**_ You can find more information on this parameter [here](09-appendix.md#details-on-the-initial-reservoir-levels-parameter). + +--- +#### hydro-heuristic-policy +[//]: # (TODO: complete the usage paragraph) +- **Expected value:** one of the following (case-insensitive): + - `accommodate rule curves` + - `maximize generation` +- **Required:** no +- **Default value:** `accommodate rule curves` +- **Usage:** hydraulic heuristic policy: + - `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). + +--- +#### hydro-pricing-mode +[//]: # (TODO: complete the usage paragraph) +- **Expected value:** one of the following (case-insensitive): + - `fast` + - `accurate` +- **Required:** no +- **Default value:** `fast` +- **Usage:** + - `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). + +--- +#### power-fluctuations +[//]: # (TODO: complete the usage paragraph) +- **Expected value:** one of the following (case-insensitive): + - `minimize ramping` + - `free modulations` + - `minimize excursions` +- **Required:** no +- **Default value:** `free modulations` +- **Usage:** + - `minimize ramping` + - `free modulations` + - `minimize excursions` + +--- +#### shedding-policy +[//]: # (TODO: complete the usage paragraph) +- **Expected value:** one of the following (case-insensitive): + - `shave peaks` + - `minimize duration` +- **Required:** no +- **Default value:** `shave peaks` +- **Usage:** power shedding policy: + - `shave peaks`: + - `minimize duration`: + +--- +#### unit-commitment-mode +[//]: # (TODO: complete the usage paragraph by adding details & links to relevant UC doc) +- **Expected value:** one of the following (case-insensitive): + - `fast` + - `accurate` + - `milp` +- **Required:** no +- **Default value:** `fast` +- **Usage:** choose the mode in which Antares resolves the unit-commitment problem: + - `fast`: Heuristic in which 2 LP problems are solved. No explicit modelling for the number of ON/OFF units. + - `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). + +--- +#### number-of-cores-mode +- **Expected value:** one of the following (case-insensitive): + - `minimum` + - `low` + - `medium` + - `high` + - `maximum` +- **Required:** no +- **Default value:** `medium` +- **Usage:** use this parameter to configure [multi-threading](optional-features/multi-threading.md). + +--- +#### renewable-generation-modelling +[//]: # (TODO: complete the usage paragraph) +- **Expected value:** one of the following (case-insensitive): + - `aggregated` + - `clusters` +- **Required:** no +- **Default value:** `aggregated` +- **Usage:** + - `aggregated` + - `clusters` + +> _**Note:**_ You can find more information on this parameter [here](09-appendix.md#details-on-the-renewable-generation-modelling-parameter). + +--- +#### day-ahead-reserve-management +[//]: # (TODO: document this parameter, doesn't seem to belong to this category) +- **Expected value:** +- **Required:** **yes** +- **Default value:** +- **Usage:** + +> _**WARNING:**_ this parameter is ignored since version 8.4 + +--- +## Advanced parameters +Advanced Parameters allow to adjust the simulation behavior regarding issues +that are more numerical than physical. The set of parameters is study-specific and can be updated at any time. +These parameters are listed under the `[advanced parameters]` section in the `.ini` file. + +--- +#### accuracy-on-correlation +[//]: # (TODO: complete the usage paragraph) +- **Expected value:** comma-seperated list of 0 to N elements among the following (case-insensitive): + `load`, `wind`, `hydro`, `thermal`, `solar`, `renewables`, `ntc`, `max-power` +- **Required:** no +- **Default value:** empty +- **Usage:** + +--- +#### adequacy-block-size +[//]: # (TODO: document this parameter, seems to belong to another category) +_**This section is under construction**_ + +- **Expected value:** +- **Required:** **yes** +- **Default value:** +- **Usage:** + +> _**WARNING:**_ this parameter is ignored since version 8.5 + +--- +## Seeds - Mersenne Twister parameters +These parameters are listed under the `[seeds - Mersenne Twister]` section in the `.ini` file. +They allow the user to set the seeds of random number generators, in order to ensure the results are repeatable. + +--- +#### seed-tsnumbers +- **Expected value:** unsigned integer +- **Required:** **yes** +- **Usage:** fixes the seed for the random [Monte-Carlo years](#nbyears) selection. + +--- +#### seed-unsupplied-energy-costs +- **Expected value:** unsigned integer +- **Required:** **yes** +- **Usage:** fixes the seed for the random noise generation on unsupplied energy costs. + +--- +#### seed-spilled-energy-costs +[//]: # (TODO: verify if required, if not, add default value) +- **Expected value:** unsigned integer +- **Required:** **yes** +- **Usage:** fixes the seed for the random noise generation on spilled energy costs. + +--- +#### seed-thermal-costs +- **Expected value:** unsigned integer +- **Required:** **yes** +- **Usage:** fixes the seed for the random noise generation on thermal plants' costs. + +--- +#### seed-hydro-costs +- **Expected value:** unsigned integer +- **Required:** **yes** +- **Usage:** fixes the seed for the random noise generation on hydraulic plants' costs. + +--- +#### seed-initial-reservoir-levels +[//]: # (TODO: complete the usage paragraph) +- **Expected value:** unsigned integer +- **Required:** **yes** +- **Usage:** + +--- +## Playlist parameters +These parameters are listed under the `[playlist]` section in the `.ini` file. +They are **required** if [user-playlist](#user-playlist) is set to `true`. + +--- +#### playlist_reset +[//]: # (TODO: complete the usage paragraph) +- **Expected value:** `true` or `false` +- **Required:** **yes**, if [user-playlist](#user-playlist) is set to `true`. +- **Usage:** + +--- +#### playlist_year +- **Expected value:** `+ =` or `- =`, followed by a positive integer (example: `playlist_year + = 5`) +- **Required:** **yes**, if [user-playlist](#user-playlist) is set to `true`. +- **Usage:** + - for every Monte-Carlo year that you want the Antares Simulator to **study**, add the parameter entry + `playlist_year + = i`, where `i` is the index of the year. + - for every Monte-Carlo year that you want the Antares Simulator to **skip**, add the parameter entry + `playlist_year - = i`, where `i` is the index of the year. + +--- +#### playlist_year_weight +[//]: # (TODO: document this parameter) +_**This section is under construction**_ + +- **Expected value:** +- **Required:** **yes** +- **Default value:** +- **Usage:** +Each MC year i=1, …, N can be given a relative “weight” $W_i$ in the simulation (default value: 1). +The expectation and standard deviation of all random variables will then be computed as if the scenarios simulated were +sampled from a probability density function in which MC year i is given the probability +$$\frac{W_{i}}{\sum_{j=1,...,N}{W_{j}}}$$ + +--- +## Variables selection parameters +These parameters are listed under the `[variables selection]` section in the `.ini` file. +They are **required** if [thematic-trimming](#thematic-trimming) is set to `true`. + +--- +#### selected_vars_reset +[//]: # (TODO: complete the usage paragraph) +- **Expected value:** `true` or `false` +- **Required:** **yes**, if [thematic-trimming](#thematic-trimming) is set to `true`. +- **Usage:** + +--- +#### select_var +- **Expected value:** `+ =` or `- =`, followed by a string (example: `select_var + = LOAD`) +- **Required:** **yes**, if [thematic-trimming](#thematic-trimming) is set to `true`. +- **Usage:** + - for every optimization variable that you want the Antares Simulator to **export** in the outputs, add the + parameter entry `select_var + = VAR`, where `VAR` is the name of the variable. + - for every optimization variable that you want the Antares Simulator to **omit** from the outputs, add the + parameter entry `select_var - = VAR`, where `VAR` is the name of the variable. + +> _**WARNING:**_ this parameter is intended for use by expert users that know the name of the optimization variables created +> under-the-hood by Antares Simulator. + +--- +## Model-wise parameters +[//]: # (TODO: link to model-wise parameters documentation) +_**This section is under construction**_ diff --git a/docs/optimisation/01-modeling.md b/docs/user-guide/solver/05-model.md similarity index 61% rename from docs/optimisation/01-modeling.md rename to docs/user-guide/solver/05-model.md index 8c01c4e2c3..29816befd2 100644 --- a/docs/optimisation/01-modeling.md +++ b/docs/user-guide/solver/05-model.md @@ -1,10 +1,10 @@ -# Formulation of the optimisation problems +# Optimization model -**_Antares\_Simulator Modeling and Optimization_** +[//]: # (TODO: update this page) +_**This section is under construction**_ **Document available on : [https://antares-simulator.org](https://antares-simulator.org/)** - ## Introduction The purpose of this document is to give every user of the **Antares\_Simulator** model (regardless of its version number), a detailed and comprehensive formulation of the main optimization problems solved by the application's inner optimization engine. @@ -31,7 +31,7 @@ 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](Antares_Process.png) +![Antares_Process](../img/Antares_Process.jpg) 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. @@ -80,22 +80,22 @@ The next sections of this document develop the following subjects: ### General notations -| Notation | Explanation | -| ------------ | ------------- | -| $k \in K$ | optimization periods (weeks) over which $P$ and $P^k$ are defined (omitted for simplicity) | -| $t \in T$ | individual time steps of any optimization period $ k\in K$ (hours of the week) | -| $G(N,L)$ | undirected graph of the power system (connected) | -| $n \in N$ | vertices of $G$, $N$ is an ordered set | -| $l \in L$ | edges of $G$ | -| $A$ | incidence matrix of $G$, dimension $N\times L$ | -| $g$ | spanning tree of $G$ | -| $C_g$ | cycle basis associated with $g$, dimension $L\times (L+1-N)$ | -| $L_n^+\subset L$ | set of edges for which $n$ is the upstream vertex | -| $L_n^-\subset L$ | set of edges for which $n$ is the downstream vertex | -| $u_l \in N$ | vertex upstream from $l$ | -| $d_l \in N$ | vertex downstream from $l$ | -| $u \cdot v$ | inner product of vectors $u$ and $v$ | -| $u_\uparrow^p$ | vector resulting from the permutation on $u \in \mathbb{R}^s$ : $ u\_\uparrow^p(i)=u(i+p\, \mathrm{mod}\,s)$ | +| Notation | Explanation | +|-----------------------|---------------------------------------------------------------------------------------------------------------------| +| $k \in K$ | optimization periods (weeks) over which $P$ and $P^k$ are defined (omitted for simplicity) | +| $t \in T$ | individual time steps of any optimization period $ k\in K$ (hours of the week) | +| $G(N,L)$ | undirected graph of the power system (connected) | +| $n \in N$ | vertices of $G$, $N$ is an ordered set | +| $l \in L$ | edges of $G$ | +| $A$ | incidence matrix of $G$, dimension $N\times L$ | +| $g$ | spanning tree of $G$ | +| $C_g$ | cycle basis associated with $g$, dimension $L\times (L+1-N)$ | +| $L_n^+\subset L$ | set of edges for which $n$ is the upstream vertex | +| $L_n^-\subset L$ | set of edges for which $n$ is the downstream vertex | +| $u_l \in N$ | vertex upstream from $l$ | +| $d_l \in N$ | vertex downstream from $l$ | +| $u \cdot v$ | inner product of vectors $u$ and $v$ | +| $u_\uparrow^p$ | vector resulting from the permutation on $u \in \mathbb{R}^s$ : $ u\_\uparrow^p(i)=u(i+p\, \mathrm{mod}\,s)$ | Problems $P^k$ and $P$ call for the definition of many parameters and variables further described. @@ -109,74 +109,74 @@ Note: Almost all variables of the system are defined twice (one value per state) ### Grid -| Notation | Explanation | -| ------------ | ------------- | -| $C_l^+ \in \mathbb{R}^T_+$ | initial transmission capacity from $u_l$ to $d_l$ (variable of $P$ and $P^k$) | -| $ \overline{C}\_l^+ \in \mathbb{R}^T\_+ $ | maximum transmission capacity from $u_l$ to $d_l$ (variable of $P$, not used in $P^k$) | -| $C_l^- \in \mathbb{R}^T_+$ | initial transmission capacity from $d_l$ to $u_l$ (variable of $P$ and $P^k$) | -| $ \overline{C}^{-}\_l\in \mathbb{R}^T\_{+} $ | maximum transmission capacity from $d_l$ to $u_l$ (variable of $P$, not used in $P^k$) | -| $\Psi_l \in \mathbb{R}_+$ | weekly cost of a maximum capacity investment | -| $x_l \in [0,1]$ | transmission capacity investment level | -| $F_l^+ \in \mathbb{R}^T_+$ | power flow through $l$, from $u_l$ to $d_l$ | -| $F_l^- \in \mathbb{R}^T_+$ | power flow through $l$, from $d_l$ to $u_l$ | -| $F_l\in \mathbb{R}^T$ | total power flow through $l$, $F_l=F_l^+-F_l^-$ | -| $\tilde{F}_t \in \mathbb{R}^T$ | system flow snapshot at time $t$ | -| $\gamma_l^+\in \mathbb{R}^T$ | transmission cost through $l$, from $u_l$ to $d_l$. Proportional to the power flow | -| $\gamma_l^-\in \mathbb{R}^T$ | transmission cost through $l$, from $d_l$ to $u_l$. Proportional to the power flow | -| $Z_l \in \mathbb{R}\_+$ | overall impedance of $l$ | +| Notation | Explanation | +|------------------------------------------------|---------------------------------------------------------------------------------------------------------| +| $C_l^+ \in \mathbb{R}^T_+$ | initial transmission capacity from $u_l$ to $d_l$ (variable of $P$ and $P^k$) | +| $ \overline{C}\_l^+ \in \mathbb{R}^T\_+ $ | maximum transmission capacity from $u_l$ to $d_l$ (variable of $P$, not used in $P^k$) | +| $C_l^- \in \mathbb{R}^T_+$ | initial transmission capacity from $d_l$ to $u_l$ (variable of $P$ and $P^k$) | +| $ \overline{C}^{-}\_l\in \mathbb{R}^T\_{+} $ | maximum transmission capacity from $d_l$ to $u_l$ (variable of $P$, not used in $P^k$) | +| $\Psi_l \in \mathbb{R}_+$ | weekly cost of a maximum capacity investment | +| $x_l \in [0,1]$ | transmission capacity investment level | +| $F_l^+ \in \mathbb{R}^T_+$ | power flow through $l$, from $u_l$ to $d_l$ | +| $F_l^- \in \mathbb{R}^T_+$ | power flow through $l$, from $d_l$ to $u_l$ | +| $F_l\in \mathbb{R}^T$ | total power flow through $l$, $F_l=F_l^+-F_l^-$ | +| $\tilde{F}_t \in \mathbb{R}^T$ | system flow snapshot at time $t$ | +| $\gamma_l^+\in \mathbb{R}^T$ | transmission cost through $l$, from $u_l$ to $d_l$. Proportional to the power flow | +| $\gamma_l^-\in \mathbb{R}^T$ | transmission cost through $l$, from $d_l$ to $u_l$. Proportional to the power flow | +| $Z_l \in \mathbb{R}\_+$ | overall impedance of $l$ | ### Thermal units -| Notation | Explanation | -| ------------ | ------------- | -| $\theta \in \Theta_n$ | thermal clusters (sets of identical units) installed in node $n$ | -| $\Theta$ | set of all thermal clusters of the power system $\Theta = \cup_{n\in N} \Theta_n$ | -| $\overline{P}\_\theta \in \mathbb{R}^T_+$ | maximum power output from cluster $\theta$, depends on units availability | -| $\underline{P}\_\theta \in \mathbb{R}^T_+$ | mimimum power output from cluster $\theta$, units availability allowing | -| $P_\theta \in \mathbb{R}^T_+$ | power output from cluster $\theta$ | -| $\chi_\theta \in \mathbb{R}^T$ | variable production cost from cluster $\theta$ | -| $\sigma_\theta^+ \in \mathbb{R}^T$ | startup cost of a single unit in cluster $\theta$ | -| $\tau_\theta \in \mathbb{R}^T$ | running unit in $\theta$ : cost independent from output level (aka NoLoadHeatCost) | -| $l_\theta \in \mathbb{R}_+$ | unit in $\theta$ : minimum stable power output when running | -| $u_\theta \in \mathbb{R}_+$ | unit in $\theta$ : maximum net power output when running | -| $\Delta_\theta^+ \in \lbrace 1,\dots, \|T\|\rbrace$ | unit in $\theta$ : minumum on time when running | -| $\Delta_\theta^- \in \lbrace 1,\dots, \|T\|\rbrace$ | unit in $\theta$ : minumum off time when not running | -| $\Delta_\theta = \max(\Delta_\theta^-, \Delta_\theta^+) $ | duration above which both state changes are allowed | -| $M_\theta \in \mathbb{N}^T$ | number of running units in cluster $\theta$ | -| $\overline{M}_\theta \in \mathbb{N}^T$ | maximum number of running units in cluster $\theta$ | -| $\underline{M}_\theta \in \mathbb{N}^T$ | minimum number of running units in cluster $\theta$ | -| $M_\theta^+ \in \mathbb{N}^T$ | number of units in cluster changing from state off to state on in cluster $\theta$ | -| $M_\theta^- \in \mathbb{N}^T$ | number of units in cluster changing from state on to state off in cluster $\theta$ | -| $M_\theta^{--} \in \mathbb{N}^T$ | number of units in cluster changing from state on to state outage cluster $\theta$ | +| Notation | Explanation | +|----------------------------------------------------------------|-----------------------------------------------------------------------------------------| +| $\theta \in \Theta_n$ | thermal clusters (sets of identical units) installed in node $n$ | +| $\Theta$ | set of all thermal clusters of the power system $\Theta = \cup_{n\in N} \Theta_n$ | +| $\overline{P}\_\theta \in \mathbb{R}^T_+$ | maximum power output from cluster $\theta$, depends on units availability | +| $\underline{P}\_\theta \in \mathbb{R}^T_+$ | mimimum power output from cluster $\theta$, units availability allowing | +| $P_\theta \in \mathbb{R}^T_+$ | power output from cluster $\theta$ | +| $\chi_\theta \in \mathbb{R}^T$ | power output from cluster $\theta$ | +| $\sigma_\theta^+ \in \mathbb{R}^T$ | startup cost of a single unit in cluster $\theta$ | +| $\tau_\theta \in \mathbb{R}^T$ | running unit in $\theta$ : cost independent from output level (aka NoLoadHeatCost) | +| $l_\theta \in \mathbb{R}_+$ | unit in $\theta$ : minimum stable power output when running | +| $u_\theta \in \mathbb{R}_+$ | unit in $\theta$ : maximum net power output when running | +| $\Delta_\theta^+ \in \lbrace 1,\dots, \|T\|\rbrace$ | unit in $\theta$ : minumum on time when running | +| $\Delta_\theta^- \in \lbrace 1,\dots, \|T\|\rbrace$ | unit in $\theta$ : minumum off time when not running | +| $\Delta_\theta = \max(\Delta_\theta^-, \Delta_\theta^+) $ | duration above which both state changes are allowed | +| $M_\theta \in \mathbb{N}^T$ | number of running units in cluster $\theta$ | +| $\overline{M}_\theta \in \mathbb{N}^T$ | maximum number of running units in cluster $\theta$ | +| $\underline{M}_\theta \in \mathbb{N}^T$ | minimum number of running units in cluster $\theta$ | +| $M_\theta^+ \in \mathbb{N}^T$ | number of units in cluster changing from state off to state on in cluster $\theta$ | +| $M_\theta^- \in \mathbb{N}^T$ | number of units in cluster changing from state on to state off in cluster $\theta$ | +| $M_\theta^{--} \in \mathbb{N}^T$ | number of units in cluster changing from state on to state outage cluster $\theta$ | ### Reservoir-type hydropower units (or other power storage facilities) -| Notation | Explanation | -| ------------ | ------------- -| $\lambda \in \Lambda_n$ | reservoirs connected to node $n$ | -| $\Sigma_\lambda \in \mathbb{R}_+$ | size of reservoir $\lambda$ : amount of energy that can be stored in $\lambda$ | -| $Q\in \mathbb{N}$ | number of discrete levels defined in reservoir | -| $\overline{W}\_\lambda \in \mathbb{R}_+$ | maximum energy output from $\lambda$ throughout the optimization period | -| $\underline{W}\_\lambda \in \mathbb{R}_+$ | minimum energy output from $\lambda$ throughout the optimization period | -| $\overline{H}\_\lambda \in \mathbb{R}_+^T$ | maximum power output from reservoir $\lambda$. Note : $\sum_{t\in T} \overline{H}\_{\lambda\_t} \geq \underline{W}\_\lambda$ | -| $\underline{H}\_\lambda \in \mathbb{R}_+^T$ | minimum power output from reservoir $\lambda$. Note : $\sum_{t\in T} \underline{H}\_{\lambda\_t} \leq \overline{W}\_\lambda$ | -| $H\_\lambda \in \mathbb{R}_+^T$ | power output from reservoir $\lambda$ | -| $r\_\lambda \in \mathbb{R}_+$ | maximum ratio between output power daily peak and daily average ($1 \leq r\_\lambda \leq 24$) | -| $\varepsilon\_\lambda \in \mathbb{R}$ | reference water value associated with the reservoir's initial state (date, level) | $\eta\_\lambda \in \mathbb{R}^Q$ | reference water value associated with the reservoir's final state (date)
if _hydro pricing option := fast_ then : $\eta\_\lambda \leftarrow 0$
if _hydro pricing option := accurate_ then : $v_\lambda \leftarrow 0$ | -| $\epsilon\_\lambda^1 \in \mathbb{R}$ | penalty fee on hydro generation variations (dispatch smoothing effect)
if _hydro power fluctuations option := free modulations_ then $\epsilon_\lambda^1 \leftarrow O $| -| $\epsilon\_\lambda^2 \in \mathbb{R}$ | penalty fee on hydro generation maximum varition (dispatch smoothing effect)
if _hydro power fluctuations option := free modulations_ then $\epsilon_\lambda^2 \leftarrow O $| -| $\omega\_\lambda \in \mathbb{R}$ | overflow value (value of energy impossible to store in reservoir $\lambda$ | | -| $\varepsilon^*\_\lambda \in \mathbb{R}$ | random component added to the water value (dispatch smoothing effect) | -| $\eta\_\lambda \in \mathbb{R}^Q$ | reference water value associated with the reservoir's final state (date) | -| $\rho\_\lambda \in \mathbb{R}_+$ | efficiency ratio of pumping units (or equivalent devices) available in reservoir $\lambda$ | -| $\overline{\Pi}\_\lambda \in \mathbb{R}_+^T$ | maximum power absorbed by pumps of reservoir $\lambda$ | -| $\Pi\_\lambda \in \mathbb{R}_+^T$ | power absorbed by pumps of reservoir $\lambda$ | -| $I\_\lambda \in \mathbb{R}^T_+$ | natural power inflow to reservoir $\lambda$ | -| $O\_\lambda \in \mathbb{R}_+^T$ | power overflowing from reservoir $\lambda$ : part of inflow that cannot be stored | -| $\overline{R}\_\lambda \in \mathbb{R}_+^T$ | upper bound of the admissible level in reservoir $\lambda$ | -| $\underline{R}\_\lambda \in \mathbb{R}_+^T$ | lower bound of the admissible level in reservoir $\lambda$ | -| $R\_\lambda \in \mathbb{R}^T_+$ | stored energy level in reservoir $\lambda$ | -| $\mathfrak{R}\_{\lambda_q} \in \mathbb{R}_+$ | filling level of reservoir layer $q$ at time $T$ (end of the week) | +| Notation | Explanation | +|---------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| $\lambda \in \Lambda_n$ | reservoirs connected to node $n$ | +| $\Sigma_\lambda \in \mathbb{R}_+$ | size of reservoir $\lambda$ : amount of energy that can be stored in $\lambda$ | +| $Q\in \mathbb{N}$ | number of discrete levels defined in reservoir | +| $\overline{W}\_\lambda \in \mathbb{R}_+$ | maximum energy output from $\lambda$ throughout the optimization period | +| $\underline{W}\_\lambda \in \mathbb{R}_+$ | minimum energy output from $\lambda$ throughout the optimization period | +| $\overline{H}\_\lambda \in \mathbb{R}_+^T$ | maximum power output from reservoir $\lambda$. Note : $\sum_{t\in T} \overline{H}\_{\lambda\_t} \geq \underline{W}\_\lambda$ | +| $\underline{H}\_\lambda \in \mathbb{R}_+^T$ | minimum power output from reservoir $\lambda$. Note : $\sum_{t\in T} \underline{H}\_{\lambda\_t} \leq \overline{W}\_\lambda$ | +| $H\_\lambda \in \mathbb{R}_+^T$ | power output from reservoir $\lambda$ | +| $r\_\lambda \in \mathbb{R}_+$ | maximum ratio between output power daily peak and daily average ($1 \leq r\_\lambda \leq 24$) | +| $\varepsilon\_\lambda \in \mathbb{R}$ | reference water value associated with the reservoir's initial state (date, level) | $\eta\_\lambda \in \mathbb{R}^Q$ | reference water value associated with the reservoir's final state (date)
if _hydro pricing option := fast_ then : $\eta\_\lambda \leftarrow 0$
if _hydro pricing option := accurate_ then : $v_\lambda \leftarrow 0$ | +| $\epsilon\_\lambda^1 \in \mathbb{R}$ | penalty fee on hydro generation variations (dispatch smoothing effect)
if _hydro power fluctuations option := free modulations_ then $\epsilon_\lambda^1 \leftarrow O $ | +| $\epsilon\_\lambda^2 \in \mathbb{R}$ | penalty fee on hydro generation maximum varition (dispatch smoothing effect)
if _hydro power fluctuations option := free modulations_ then $\epsilon_\lambda^2 \leftarrow O $ | +| $\omega\_\lambda \in \mathbb{R}$ | overflow value (value of energy impossible to store in reservoir $\lambda$ | | +| $\varepsilon^*\_\lambda \in \mathbb{R}$ | random component added to the water value (dispatch smoothing effect) | +| $\eta\_\lambda \in \mathbb{R}^Q$ | reference water value associated with the reservoir's final state (date) | +| $\rho\_\lambda \in \mathbb{R}_+$ | efficiency ratio of pumping units (or equivalent devices) available in reservoir $\lambda$ | +| $\overline{\Pi}\_\lambda \in \mathbb{R}_+^T$ | maximum power absorbed by pumps of reservoir $\lambda$ | +| $\Pi\_\lambda \in \mathbb{R}_+^T$ | power absorbed by pumps of reservoir $\lambda$ | +| $I\_\lambda \in \mathbb{R}^T_+$ | natural power inflow to reservoir $\lambda$ | +| $O\_\lambda \in \mathbb{R}_+^T$ | power overflowing from reservoir $\lambda$ : part of inflow that cannot be stored | +| $\overline{R}\_\lambda \in \mathbb{R}_+^T$ | upper bound of the admissible level in reservoir $\lambda$ | +| $\underline{R}\_\lambda \in \mathbb{R}_+^T$ | lower bound of the admissible level in reservoir $\lambda$ | +| $R\_\lambda \in \mathbb{R}^T_+$ | stored energy level in reservoir $\lambda$ | +| $\mathfrak{R}\_{\lambda_q} \in \mathbb{R}_+$ | filling level of reservoir layer $q$ at time $T$ (end of the week) | ### Binding constraints @@ -192,29 +192,28 @@ $\mathrm{size}=\frac{T}{168}=1$ : applicable to lower and upper bounds of constr Generic notations for binding constraints : -| Notation | Explanation | -| ------------ | ------------- | -| $e \in E$ | set of all grid interconnections and thermal clusters. $E = L \cup \Theta$ | -| $b \in B$ | binding constraints | -| $B_h \subset B$ | subset of $B$ containing the binding constraints between hourly powers | -| $B_d \subset B$ | subset of $B$ containing the binding constraints between daily energies | -| $B_w \subset B$ | subset of $B$ containing the binding constraints between weekly energies | -| $\alpha_e^b \in \mathbb{R}$ | weight of $e$ (flow within $e$ or output from $e$) in the expression of constraint $b$ | -| $o_e^b \in \mathbb{N}$ | time offset of $e$ (flow within $e$ or output from $e$) in the expression of constraint $b$ | -| $u^b \in \mathbb{R}^{\mathrm{size}}$ | upper bound of binding constraint $b$ | -| $l^b \in \mathbb{R}^{\mathrm{size}}$ | lower bound of binding constraint $b$ | +| Notation | Explanation | +|-------------------------------------------|--------------------------------------------------------------------------------------------------------------| +| $e \in E$ | set of all grid interconnections and thermal clusters. $E = L \cup \Theta$ | +| $b \in B$ | binding constraints | +| $B_h \subset B$ | subset of $B$ containing the binding constraints between hourly powers | +| $B_d \subset B$ | subset of $B$ containing the binding constraints between daily energies | +| $B_w \subset B$ | subset of $B$ containing the binding constraints between weekly energies | +| $\alpha_e^b \in \mathbb{R}$ | weight of $e$ (flow within $e$ or output from $e$) in the expression of constraint $b$ | +| $o_e^b \in \mathbb{N}$ | time offset of $e$ (flow within $e$ or output from $e$) in the expression of constraint $b$ | +| $u^b \in \mathbb{R}^{\mathrm{size}}$ | upper bound of binding constraint $b$ | +| $l^b \in \mathbb{R}^{\mathrm{size}}$ | lower bound of binding constraint $b$ | ### Demand, security uplift, unsupplied and spilled energies -| Notation | Explanation | -| ------------ | ------------- | +| Notation | Explanation | +|-------------------------------|------------------------------------------------------------------------------------| | $D_n \in \mathbb{R}^T$ | net power demand expressed in node $n$, including must-run generation | | $S_n \in \mathbb{R}^T_+$ | demand security uplift to be faced in node $n$, by activation of security reserves | | $\delta_n^+ \in \mathbb{R}^T$ | normative unsupplied energy value in node $n$. Value of lost load - VOLL | -| $G_n^+ \in \mathbb{R}^T_+$ | unsupplied power in the nominal state | +| $G_n^+ \in \mathbb{R}^T_+$ | unsupplied power in the nominal state | | $\delta_n^- \in \mathbb{R}^T$ | normative spilled energy value in node $n$ (value of wasted energy) | -| $G_n^- \in \mathbb{R}^T_+$ | spilled power in the nominal state | - +| $G_n^- \in \mathbb{R}^T_+$ | spilled power in the nominal state | ## Formulation of problem $\mathcal{P}^k$ @@ -222,7 +221,7 @@ Superscript k is implicit in all subsequent notations of this section (omitted f ## Objective $$ - \min\_{M\_\theta \in \mathrm{Argmin} \Omega\_{\mathrm{unit com}}}(\Omega\_{\mathrm{dispatch}}) +\min\_{M\_\theta \in \mathrm{Argmin} \Omega\_{\mathrm{unit com}}}(\Omega\_{\mathrm{dispatch}}) $$ @@ -345,7 +344,7 @@ $$ Reservoir level evolution depends on generating power, pumping power, pumping efficiency, natural inflows and overflows $$ - (14)(a) \forall n \in N, \forall \lambda \in \Lambda\_n, \forall t \in T, R_{\lambda_t} - R_{\lambda_{t-1}} = \rho_\lambda \Pi_{\lambda_t} - H_{\lambda_t} + I_{\lambda_t} - O_{\lambda_t} +(14)(a) \forall n \in N, \forall \lambda \in \Lambda\_n, \forall t \in T, R_{\lambda_t} - R_{\lambda_{t-1}} = \rho_\lambda \Pi_{\lambda_t} - H_{\lambda_t} + I_{\lambda_t} - O_{\lambda_t} $$ $$ @@ -373,24 +372,24 @@ $$ The number of running units is bounded $$ - (17) \forall n \in N, \forall \theta \in \Theta\_n, \underline{M_\theta} \leq M_\theta \leq \overline{M_\theta} +(17) \forall n \in N, \forall \theta \in \Theta\_n, \underline{M_\theta} \leq M_\theta \leq \overline{M_\theta} $$ Power output remains within limits set by minimum stable power and maximum capacity thresholds $$ - (18) \forall n \in N, \forall \theta \in \Theta\_n, l_\theta M_\theta \leq M_\theta \leq u_\theta M_\theta +(18) \forall n \in N, \forall \theta \in \Theta\_n, l_\theta M_\theta \leq M_\theta \leq u_\theta M_\theta $$ Minimum running and not-running durations contribute to the unit-commitment plan. Note that this modeling requires[^9] that one at least of the following conditions is met: $\Delta_\theta^- \leq \Delta_\theta^+$ or $\overline{M}_\theta \leq 1_T$ $$ - (19) \forall n \in N, \forall \theta \in \Theta\_n, \forall t \in T, M_{\theta_t} = M_{\theta_{t-1}} + M_{\theta_t}^+ - M_{\theta_t}^- +(19) \forall n \in N, \forall \theta \in \Theta\_n, \forall t \in T, M_{\theta_t} = M_{\theta_{t-1}} + M_{\theta_t}^+ - M_{\theta_t}^- $$ $$ - (20) \forall n \in N, \forall \theta \in \Theta\_n, \forall t \in T, {M_\theta^{- -}}_t \leq {M _ \theta^{-}}_t +(20) \forall n \in N, \forall \theta \in \Theta\_n, \forall t \in T, {M_\theta^{- -}}_t \leq {M _ \theta^{-}}_t $$ $$ @@ -398,11 +397,11 @@ $$ $$ $$ -(22) \forall n \in N, \forall \theta \in \Theta\_n, \forall t \in T, M_{\theta_ t} \geq \sum_{k=t+1-\Delta_\theta^+}^{k=t}(M_{\theta_k}^+ - {M_\theta^{- -}}_k) +(22) \forall n \in N, \forall \theta \in \Theta\_n, \forall t \in T, M_{\theta_ t} \geq \sum_{k=t+1-\Delta_\theta^+}^{k=t}(M_{\theta_k}^+ - {M_\theta^{- -}}_k) $$ $$ - (23) \forall n \in N, \forall \theta \in \Theta\_n, \forall t \in T, M_{\theta_t} \leq \overline{M}\_{\theta_{t - \Delta_\theta^-}} + \sum_{k=t+1-\Delta_\theta^+}^{k=t} \max(0, \overline{M}\_{\theta_k} - \overline{M}\_{\theta_{k-1}}) - \sum_{k=t+1-\Delta_\theta^+}^{k=t}(M_{\theta_k}^-) +(23) \forall n \in N, \forall \theta \in \Theta\_n, \forall t \in T, M_{\theta_t} \leq \overline{M}\_{\theta_{t - \Delta_\theta^-}} + \sum_{k=t+1-\Delta_\theta^+}^{k=t} \max(0, \overline{M}\_{\theta_k} - \overline{M}\_{\theta_{k-1}}) - \sum_{k=t+1-\Delta_\theta^+}^{k=t}(M_{\theta_k}^-) $$ ### Constraints related to the uplifted system state (activation of security reserves) @@ -413,7 +412,7 @@ Besides, in the expression of constraints , all occurrences of are replaced by $ ## Antares as a SCOPF ("flow-based model") -When problems $\mathcal{P}^k$ do not include any instance of so-called ";binding constraints"; and if no market pools are defined, the flows within the grid are only committed to meet the bounds set on the initial transmission capacities, potentially reinforced by investments (problem ).In other words, there are no electrical laws enforcing any particular pattern on the flows, even though hurdles costs and may influence flow directions through an economic signal. +When problems $\mathcal{P}^k$ do not include any instance of so-called "binding constraints" and if no market pools are defined, the flows within the grid are only committed to meet the bounds set on the initial transmission capacities, potentially reinforced by investments (problem ).In other words, there are no electrical laws enforcing any particular pattern on the flows, even though hurdles costs and may influence flow directions through an economic signal. In the general case, such a raw backbone model is a very simplified representation of a real power system whose topology and consistency are much more complex. While the full detailed modeling of the system within Antares is most often out of the question, it may happen that additional data and/or observations can be incorporated in the problems solved by the software. @@ -445,12 +444,12 @@ $$ In cases where the power system is equipped with phase-shifting transformers whose ratings are known, ad hoc classical power studies can be carried out to identify the minimum and maximum flow deviations and phase-shift that each component may induce on the grid. The following additional notations are in order: -| Notation | Explanation | -| ------------ | ------------- | -| $\Pi\_{l}^{+shift} \in \mathbb{R}\_{+}$ | Maximum positive shifting ability of a device equipping link $l$| -| $\Pi^{+shift} \in \mathbb{R}^{L}$ | Snapshots formed by all positive synchronous deviations $\Pi\_{l}^{+shift} \in \mathbb{R}\_{+}$ | -| $\Pi\_{l}^{+shift} \in \mathbb{R}\_{-}$ | Maximum negative shifting ability of a device equipping link $l$| -| $\Pi^{-shift} \in \mathbb{R}^{L}$ | Snapshots formed by all negative synchronous deviations $\Pi\_{l}^{-shift} \in \mathbb{R}\_{-}$ | +| Notation | Explanation | +|-----------------------------------------|-------------------------------------------------------------------------------------------------| +| $\Pi\_{l}^{+shift} \in \mathbb{R}\_{+}$ | Maximum positive shifting ability of a device equipping link $l$ | +| $\Pi^{+shift} \in \mathbb{R}^{L}$ | Snapshots formed by all positive synchronous deviations $\Pi\_{l}^{+shift} \in \mathbb{R}\_{+}$ | +| $\Pi\_{l}^{+shift} \in \mathbb{R}\_{-}$ | Maximum negative shifting ability of a device equipping link $l$ | +| $\Pi^{-shift} \in \mathbb{R}^{L}$ | Snapshots formed by all negative synchronous deviations $\Pi\_{l}^{-shift} \in \mathbb{R}\_{-}$ | The enhancement of the model with a representation of the phase-shifting components of the real system then requires to re-formulate as follows the binding constraints defined in 7.2: @@ -462,12 +461,12 @@ $$ When the power system graph contains edges that represent DC components, additional notations need be defined: -| Notation | Explanation | -| ------------ | ------------- | -|$L^* \subset L$ | subset of edges representing AC components| -|$G^*(N,L^*)$ | subgraph of $G(N,L)$ | -|$g^*$ | spanning tree of $G^*(N,L^*)$ | -|$C^*_{g^*}$ | cycle matric of $G^*(N,L^*)$ associated with $g^*$ | +| Notation | Explanation | +|-----------------------|---------------------------------------------------------------------------------------------------------------------| +| $L^* \subset L$ | subset of edges representing AC components | +| $G^*(N,L^*)$ | subgraph of $G(N,L)$ | +| $g^*$ | spanning tree of $G^*(N,L^*)$ | +| $C^*_{g^*}$ | cycle matric of $G^*(N,L^*)$ associated with $g^*$ | The proper modeling of the system then requires that all "load flow" constraints defined previously be formulated using notations $(L^*, G^*(N,L^*), C^*\_{g^*})$ instead of $(L, G(N,L), C_{g})$. @@ -475,13 +474,13 @@ The proper modeling of the system then requires that all "load flow" constraints It is assumed here that upstream power system classical calculations on the detailed system are assumed to have provided appropriate estimates for line outage distribution factors (LODFs) for all components involved in the contingency situations to consider. The following additional notations can therefore be introduced: -| Notation | Explanation | -| ------------ | ------------- | -|$O \subset PL$ | set of situations (single or multiple outages) considered in the contingency analysis| -|$Q \in O$ | situation (incident) considered in the contingency analysis| -|${}^Qp_l^m \in [-1,1]$ | LODFs from component $m$ (involved in $Q$) on component $l$ if $Q$ occurs | -| $\underline{F}_l^Q \in \mathbb{R}^T$ | lower bound of the power flow through $l$ if $Q$ occurs | -| $\overline{F}_l^Q \in \mathbb{R}^T$ | upper bound of the power flow through $l$ if $Q$ occurs | +| Notation | Explanation | +|--------------------------------------|---------------------------------------------------------------------------------------------------------------------| +| $O \subset PL$ | set of situations (single or multiple outages) considered in the contingency analysis | +| $Q \in O$ | situation (incident) considered in the contingency analysis | +| ${}^Qp_l^m \in [-1,1]$ | LODFs from component $m$ (involved in $Q$) on component $l$ if $Q$ occurs | +| $\underline{F}_l^Q \in \mathbb{R}^T$ | lower bound of the power flow through $l$ if $Q$ occurs | +| $\overline{F}_l^Q \in \mathbb{R}^T$ | upper bound of the power flow through $l$ if $Q$ occurs | The implementation of security rules for the chosen situations requires the following $|L||O|$ additional binding constraints: @@ -513,22 +512,23 @@ 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](Random_Parameters.png) +![Random_Parameters](img/Random_Parameters.png) -| Random Epsilons | Minimum absolute value | Maximum absolute value | -| ------------| ------------| ------------| -|N_THERMAL|$5 \cdot 10^{-4} €/MWh$|$6 \cdot 10^{-4} €/MWh$| -|N_UNSUPPLIED|$5 \cdot 10^{-4} €/MWh$|$6 \cdot 10^{-4} €/MWh$| -|N_SPILLAGE|$5 \cdot 10^{-4} €/MWh$|$6 \cdot 10^{-4} €/MWh$| -|N_HYDRO|$5 \cdot 10^{-4} €/MWh$|$10 \cdot 10^{-4} €/MWh$| +| Random Epsilons | Minimum absolute value | Maximum absolute value | +|-----------------|-------------------------|--------------------------| +| N_THERMAL | $5 \cdot 10^{-4}$ €/MWh | $6 \cdot 10^{-4}$ €/MWh | +| N_UNSUPPLIED | $5 \cdot 10^{-4}$ €/MWh | $6 \cdot 10^{-4}$ €/MWh | +| N_SPILLAGE | $5 \cdot 10^{-4}$ €/MWh | $6 \cdot 10^{-4}$ €/MWh | +| N_HYDRO | $5 \cdot 10^{-4}$ €/MWh | $10 \cdot 10^{-4}$ €/MWh | -It can be noted that, in absolute value, all random epsilons are smaller than the lower bound of the (non-zero) actual costs that can be defined through the user interface (CLB – cost lower bound : $5 \cdot 10^{-3} €/MWh$) +It can be noted that, in absolute value, all random epsilons are smaller than the lower bound of the (non-zero) actual +costs that can be defined through the user interface (CLB – cost lower bound : $5 \cdot 10^{-3}$ €/MWh) -[^1]: Reference guide , section « optimization preferences : "export mps problems" +[^1]: User guide , section « optimization preferences : "export mps problems" [^2]: For the sake of simplicity, the **Antares\_Simulator** application will be further denoted « Antares » -[^3]: See «hydro» sections of the General Reference Guide ("hydro" standing as a generic name for all types of energy storage facilities) +[^3]: See «hydro» sections of the General User guide ("hydro" standing as a generic name for all types of energy storage facilities) Copyright © RTE 2007-2023 – Version 8.6.0 diff --git a/docs/user-guide/solver/06-hydro-heuristics.md b/docs/user-guide/solver/06-hydro-heuristics.md new file mode 100644 index 0000000000..4d4de31f48 --- /dev/null +++ b/docs/user-guide/solver/06-hydro-heuristics.md @@ -0,0 +1,193 @@ +# Hydro heuristics + +_**This section is under construction**_ + +## Seasonal hydro pre-allocation + +Basically, the seasonal hydro pre-allocation process comprises two stages carried out two times +(first time: monthly scale; second time: daily scale). + +- Stage 1: Definition of an allocation ideal modulation profile, which may be based (or not) on local and/or + remote load profiles. +- Stage 2: Mitigation of the previous raw profile to obtain a feasible hydro ideal target, + compatible as much as possible with reservoir rule curves. + +The description given hereafter makes use of the following local notations, +not be confused with those of the document "optimization problem formulation" +(dedicated to the optimal hydro-thermal unit-commitment and dispatch problem): + +- $Z$ Number of Areas (zones $z$) in the system +- $M_{zh}$ Hourly time-series of cumulated must-generation of all kinds for zone $z$ +- $M_{zd}$ Daily time-series of cumulated must-generation of all kinds for zone $z$ (sum of $M_{zh}$) +- $M_{zm}$ Monthly time-series of cumulated must-generation of all kinds for zone $z$ (sum of $M_{zh}$) +- $M_{z.}$ Either $M_{zd}$ or $M_{zm}$, relevant time index "." is defined by the context +- $L_{z.}$ Time-series of "natural" load for zone $z$ +- $A$ Inter-area hydro-allocation matrix (dimension_ $x Z$ ) $A_{uv}$ is a weight given to the load + of area $u$ in the definition of the monthly and daily primary hydro generation target of area $v$ + Extreme cases are: + + - **A is the identity matrix** + The hydro storage energy monthly and weekly profiles of each zone $z$ depend only on the local demand and + must-run generation in $z$ + - **A has a main diagonal of zeroes** + The hydro storage energy monthly and weekly profiles of each zone $z$ do not depend at all on the local + demand and must-run generation in $z$ +- $L_{z.}^+$ Time-series of "net" load for zone $z$, defined as: $L{z.}^+ = L{z.} - M{z.}$ +- $L_{z.}$ Time-series of "weighted" load for zone $z$, defined as:_ $L_{z.} = A^t L_{z.}^+$ + +All following parameters are related to the generic zone $z$: + +- $\alpha$ "inter-monthly generation breakdown" parameter + +- $\beta$ "inter-daily generation breakdown" parameter + +- $j$ "follow-load" parameter + +- $\mu$ "reservoir-management" parameter + +- $S$ Reservoir size + +- $\overline{S_d}$ Reservoir maximum level at the end of day d, expressed as a fraction of $S$ (rule curve) + +- $\underline{S_d}$ Reservoir minimum level at the end of day d, expressed as a fraction of $S$ (rule curve) + +- $S_0$ Reservoir initial level at the beginning of the first day of the "hydro-year" + +- $I_d$ Natural inflow of energy to the reservoir during day d + +- $I_m$ Natural inflow of energy to the reservoir during month m (sum of $I_d$ + +- $\overline{W_d}$ Maximum energy that can be generated on day d (standard credit) + + All following variables, defined for both stages, are related to the generic zone: + +- $S_d^k$ Reservoir level at the end of day d, at the end of stage k of pre-allocation + +- $S_m^k$ Reservoir level at the end of month m, at the end of stage k of pre-allocation + +- $O_d^k$ Overflow from the reservoir on day d, at the end of stage k of pre-allocation (inflow in excess to an already full reservoir) + +- $W_d^k$ Energy to generate on day d, at the end of stage k of pre-allocation + +- $W_m^k$ Energy to generate on month m, at the end of stage k of pre-allocation + + +Following variables and parameters are local to linear optimization problems $M$ & $D(Tm)$ +solved within the heuristic. For the sake of clarity, the same generic index is used for all time steps, +knowing that in $M$ there are 12 monthly time-steps, while in $D(m)t$ there are from 28 to 31 daily +time-steps. Costs $\gamma_{Var}$ given to these variables are chosen to enforce a logical hierarchy +of penalties (letting the reservoir overflow is worse than violating rule curves, which is worse than deviating +from the generation objective assessed in stage 1, etc.) + +- $Y$ Generation deficit at the end of the period, as compared to the objective aimed at + +- $O_t$ Overflow from the reservoir on time step $t$ + +- $G_t, \overline{G_t}$ Optimal generation and maximum generation on time step $t$ + +- $T_t$ Generation objective assessed in the first stage, for time step t ( $W_m^1$ or $W_d^1$) + +- $S_t, \overline{S_t}, \underline{S_t}$ Optimal stock level, maximum level, minimum level at the end of time step $t$ + +- $I_t$ Natural inflow on time step $t$ + +- $D_t$ Deviation (absolute difference) between target reached and initial aim + +- $\Delta$ Maximum deviation throughout the period + +- $V_t^+$ Amplitude of the violation of the upper rule curve at time step $t$ + +- $V_t^-$ Amplitude of the violation of the lower rule curve at time step $t$ + +- $Y$ Maximum violation of lower rule curve throughout the period + + +**General heuristic for each zone** + +_Begin_ + +$$if (not.\mu) : \{ S \leftarrow \infty ; \underline{S_d} \leftarrow 0; \overline{S_d}; S_0 \leftarrow S/2 \}$$ + +_M1:_ + +$$if (j \text{ and } \mu) : \text{for } m\in [1, 12]: W_m^1 \leftarrow \frac{L_m^{\alpha}.(\sum_{m}{I_m})}{(\sum_{m}{L_m^{\alpha}})}$$ + +$$else: \text{for } m\in [1, 12]: \{W_m^1 \leftarrow I_m\}$$ + + +_M2:_ + +$$\text{for } m\in [1, 12]: W_m^2 \leftarrow \text{Solution of linear problem M}$$ + +_D1:_ + +$$if (j): \text{for } d\in [1, 31]: W_d^1 \leftarrow \frac{L_d^{\beta}. (W_m^2)}{(\sum_{d\in m}{L_d^{\beta}})}$$ + +$$else: \text{for } d\in [1, 31]: W_d^1 \leftarrow \frac{I_d . (W_m^2)} {(\sum_{d\in m}{I_d})}$$ + +_D2:_ + +$$\text{for } m \in [1, 12]: W_{d\in m}^2 \leftarrow \text{Solution of linear problem D(m)}$$ + +_End_ + +Note: In the formulation of the optimal hydro-thermal unit-commitment and dispatch problem (see dedicated document), the reference hydro energy __HIT__ used to set the right hand sides of hydro- constraints depends on the value chosen for the optimization preference "simplex range" and is defined as follows: + +- Daily : for each day **d** of week $\omega$ : $HIT = W_d^2$ +- Weekly : for week $\omega$: $HIT = \sum_{d\in \omega}{W_d^2}$ + +**Optimization problem M** + +$$\min_{G_t, S_t, ...}{\gamma_{\Delta}\Delta + \gamma_Y Y + \sum_{t}{(\gamma_D D_t + \gamma_{V+} V_t^+ + \gamma_{V-} V_t^-)}}$$ + +s.t + +$$S_t \geq 0$$ + +$$S_t \leq S$$ + +$S_t + G_t - S_{t-1} = I_t$ (see note [^monthly_allocation]) + +$$\sum_{t}{G_t} = \sum_{t}{T_t}$$ + +$$G_t - D_t \leq T_t$$ + +$$G_t + D_t \geq T_t$$ + +$$V_t^- + S_t \geq \underline{S_t}$$ + +$$V_t^+ - S_t \geq -\overline{S_t}$$ + +$$Y - V_t^- \geq 0$$ + + +**Optimization problems $D(m)$** + +$$\min_{G_t, S_t, ...}{\gamma_{\Delta}\Delta + \gamma_Y Y + \sum_{t}{(\gamma_D D_t + \gamma_{V-} V_t^- + \gamma_{O} O_t + \gamma_S S_t)}}$$ +s.t + +$$S_t \geq 0$$ + +$$S_t \leq S$$ + +$$G_t \geq 0$$ + +$$G_t \leq \overline{G_t}$$ + +$S_t + G_t + O_t - S_{t-1} = I_t$ (see note [^daily_allocation]) + +$\sum_{t}{G_t + Y} = \sum_{t}{T_t} + Y_{m-1}$ (value of Y previously found in solving **$D(m-1)$**) + +$$G_t - D_t \leq T_t$$ + +$$G_t + D_t \geq T_t$$ + +$$\Delta - D_t \geq 0$$ + +$$V_t^- + S_t \geq \underline{S_t}$$ + +$$Y - V_t^- \geq 0$$ + +[^monthly_allocation]: In the first equation, $S_{t-1}$ is either the initial stock $S_0$ or the final stock of the previous year (hydro hot start) + +[^daily_allocation]: In the first equation, $S_{t-1}$ is either the initial stock used in M or the final stock of the previous month ($D(m-1)$) diff --git a/docs/optimisation/02-thermal-heuristic.md b/docs/user-guide/solver/07-thermal-heuristic.md similarity index 100% rename from docs/optimisation/02-thermal-heuristic.md rename to docs/user-guide/solver/07-thermal-heuristic.md diff --git a/docs/user-guide/solver/08-command-line.md b/docs/user-guide/solver/08-command-line.md new file mode 100644 index 0000000000..3dc39a6999 --- /dev/null +++ b/docs/user-guide/solver/08-command-line.md @@ -0,0 +1,56 @@ +--- +hide: + - toc +--- + +# Command-line instructions + +**Executable**: antares-solver + +## 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` | + +## 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 | + +## Optimization + +| command | usage | +|:-------------------------|:-------------------------------------------------------------------------------------------------------------------| +| --optimization-range | Force the [simplex optimization range](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 | +| -s, --named-mps-problems | Export named MPS, weekly or daily optimal UC+dispatch linear | +| --solver-logs | Print solver logs | + +## Misc. + +| command | usage | +|:----------------|:-----------------------------------------------------------------| +| --progress | Display the progress of each task | +| -p, --pid=VALUE | Specify the file where to write the process ID | +| --list-solvers | Display a list of LP solvers available through OR-Tools and exit | +| -v, --version | Print the version of the solver and exit | +| -h, --help | Display this help and exit | \ No newline at end of file diff --git a/docs/user-guide/solver/09-appendix.md b/docs/user-guide/solver/09-appendix.md new file mode 100644 index 0000000000..3ab1b49f6d --- /dev/null +++ b/docs/user-guide/solver/09-appendix.md @@ -0,0 +1,217 @@ +# 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 +[//]: # (TODO: update this paragraph) +_**This section is under construction**_ + +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/reference-guide/Antares_Implementation.png b/docs/user-guide/solver/img/Antares_Implementation.png similarity index 100% rename from docs/reference-guide/Antares_Implementation.png rename to docs/user-guide/solver/img/Antares_Implementation.png diff --git a/docs/optimisation/Antares_Process.png b/docs/user-guide/solver/img/Antares_Process.png similarity index 100% rename from docs/optimisation/Antares_Process.png rename to docs/user-guide/solver/img/Antares_Process.png diff --git a/docs/optimisation/Random_Parameters.png b/docs/user-guide/solver/img/Random_Parameters.png similarity index 100% rename from docs/optimisation/Random_Parameters.png rename to docs/user-guide/solver/img/Random_Parameters.png diff --git a/docs/reference-guide/Standard_Implementation.png b/docs/user-guide/solver/img/Standard_Implementation.png similarity index 100% rename from docs/reference-guide/Standard_Implementation.png rename to docs/user-guide/solver/img/Standard_Implementation.png diff --git a/docs/optimisation/global_diagram.png b/docs/user-guide/solver/img/global_diagram.png similarity index 100% rename from docs/optimisation/global_diagram.png rename to docs/user-guide/solver/img/global_diagram.png diff --git a/docs/optimisation/thermal_heuristic_fast_step_2.png b/docs/user-guide/solver/img/thermal_heuristic_fast_step_2.png similarity index 100% rename from docs/optimisation/thermal_heuristic_fast_step_2.png rename to docs/user-guide/solver/img/thermal_heuristic_fast_step_2.png diff --git a/docs/optimisation/thermal_smoothing_heuristic.png b/docs/user-guide/solver/img/thermal_smoothing_heuristic.png similarity index 100% rename from docs/optimisation/thermal_smoothing_heuristic.png rename to docs/user-guide/solver/img/thermal_smoothing_heuristic.png diff --git a/docs/user-guide/solver/optional-features/00-index.md b/docs/user-guide/solver/optional-features/00-index.md new file mode 100644 index 0000000000..ff5deced5b --- /dev/null +++ b/docs/user-guide/solver/optional-features/00-index.md @@ -0,0 +1,9 @@ +[//]: # (Index used by Sphinx to generate correct PDF tree) +# Optional features + +```{toctree} +:hidden: +multi-threading.md +adequacy-patch.md +xpress.md +``` \ No newline at end of file diff --git a/docs/reference-guide/Reduced_Allowance.png b/docs/user-guide/solver/optional-features/Reduced_Allowance.png similarity index 100% rename from docs/reference-guide/Reduced_Allowance.png rename to docs/user-guide/solver/optional-features/Reduced_Allowance.png diff --git a/docs/reference-guide/14-adequacy-patch.md b/docs/user-guide/solver/optional-features/adequacy-patch.md similarity index 61% rename from docs/reference-guide/14-adequacy-patch.md rename to docs/user-guide/solver/optional-features/adequacy-patch.md index 0a77074e0d..b92a07a8eb 100644 --- a/docs/reference-guide/14-adequacy-patch.md +++ b/docs/user-guide/solver/optional-features/adequacy-patch.md @@ -1,8 +1,12 @@ # Adequacy Patch calculation +(available since v8.3.0) + +[//]: # (TODO: update this page if needed) +_**This section is under construction**_ ## Foreword -The operational algorithm of Euphémia market coupling implements "de-optimization" rules in order to fix the sharing of “Energy Not Served” (ENS) between the market areas when there is any (in a way to ensure a certain fairness in the sharing of this ENS): this is what we call the adequacy patch. +The operational algorithm of Euphémia market coupling implements "de-optimization" rules in order to fix the sharing of "Energy Not Served" (ENS) between the market areas when there is any (in a way to ensure a certain fairness in the sharing of this ENS): this is what we call the adequacy patch. The requirement of fairness rules in the sharing of ENS within Antares studies increased with the introduction of flow-based modelling. Previously, this problem was mainly solved with the hurdle cost mechanism (small costs on interconnections) limiting exports from areas where ENS was encountered. However, implicit rules in Antares for sharing ENS, even outside the Flow-Based domain, are not fully satisfactory, even with hurdle costs, because they prioritize the treatment of ENS in countries directly connected to countries with margins, to the detriment of more distant countries. In a context of decommissioning of coal and nuclear plants in France and in Europe, cases of simultaneous ENS over the domain will increase. Consequently, the need of adequacy patch to share fairly this ENS is arising. It should be noted that, in the current implementation of the patch within Antares, the implementation covers only one of the three main features of the ‘curtailment sharing and minimization’ principles in EUPHEMIA, namely: @@ -53,7 +57,7 @@ Once the first iteration is completed, we have access to the DENS value, which r During the second iteration, all link capacities between physical nodes are set to the values provided as input data (as it is done in the current Antares version). The only change compared to a simulation without the adequacy patch is that the upper bound of the ENS on the areas included in the patch is now constrained by the DENS found during the first iteration. This is introduced in the optimization problem for physical areas that are declared in the adequacy patch domain (areas declared as "physical inside"): -- ENS $\le$ DENS +- ENS $\leq$ DENS (for all physical areas inside the adequacy patch). ## Curtailment sharing rule (Antares Simulator 8.5) @@ -65,7 +69,7 @@ The idea is that when countries on the network have positive DENS, they should h - PTOs are the DENS of the country - PTOs are the Load of the country -The considered countries are only nodes “2” (areas defined as physical areas inside the adequacy patch), the problem to be solved is an hourly problem. Precisely, the hourly problem to be solved concerns only hours for which of the sum of the ENS in all nodes “2” is exceeding a user-defined threshold. If it is not the case, all the treatments described below should be ignored for this hour and the algorithm should then consider the next hour. So, at that step, we will solve the CSR quadratic optimization problem on a reduced domain, limited to nodes “2” and the links that exist between these nodes 2. +The considered countries are only nodes "2" (areas defined as physical areas inside the adequacy patch), the problem to be solved is an hourly problem. Precisely, the hourly problem to be solved concerns only hours for which of the sum of the ENS in all nodes "2" is exceeding a user-defined threshold. If it is not the case, all the treatments described below should be ignored for this hour and the algorithm should then consider the next hour. So, at that step, we will solve the CSR quadratic optimization problem on a reduced domain, limited to nodes "2" and the links that exist between these nodes 2. _**Notes**_ @@ -73,117 +77,117 @@ _**Notes**_ _**Convention**_: -- _A is any node of type “2” in the network, an area that is defined as a physical area inside the adequacy patch. Each variable/parameter/constraint applied on A is implicitly applied to any node of type "2”;_ -- _B represents any node of type "2” linked to A;_ +- _A is any node of type "2" in the network, an area that is defined as a physical area inside the adequacy patch. Each variable/parameter/constraint applied on A is implicitly applied to any node of type "2";_ +- _B represents any node of type "2" linked to A;_ - _A is alphabetically before B, therefore their link in Antares would be called A/B. Furthermore, regarding the flow on this link (variable that contains the algebraic value of the power flow between the 2 nodes to be optimized):_ - _if the flow value is positive, the power flow goes from node A to node B, it is an export for node A and an import for node B;_ - _if the flow value is negative, the power flow goes from node B to node A, it is an import for node A and an export for node B._ ### Variable definitions -- Flows over links variables (3 set of variables: “Flow”, “Flow_direct” and “Flow_indirect"): -Inside the optimization problem, the “flow” variable is actually split in 2 positive variables for the resolution. It is required in order to write some constraints. We define the 2 positive variables, “Flow_direct” and “Flow_indirect” with this simple relation: +- Flows over links variables (3 set of variables: "Flow", "Flow_direct" and "Flow_indirect"): +Inside the optimization problem, the "flow" variable is actually split in 2 positive variables for the resolution. It is required in order to write some constraints. We define the 2 positive variables, "Flow_direct" and "Flow_indirect" with this simple relation: Flow = Flow_direct – Flow_indirect -- “net_position” variable: -“net_position (node A)” is the balance between node A and all other nodes “2” connected to node A. +- "net_position" variable: +"net_position (node A)" is the balance between node A and all other nodes "2" connected to node A. -- “ENS” variable: -“ENS (node A)” contains the ENS to be optimized for that node. +- "ENS" variable: +"ENS (node A)" contains the ENS to be optimized for that node. -- “Spillage” variable: -“Spillage (node A)” contains the Spillage to be optimized for that node. +- "Spillage" variable: +"Spillage (node A)" contains the Spillage to be optimized for that node. ### Parameter definitions -- “net_position_init” parameter: -The “net_position_init (node A)” parameter value is the value of the “net_position” calculated from the output of the Antares calculation for node A, considering results we get from the Antares calculation at the end of Local matching rule optimization. +- "net_position_init" parameter: +The "net_position_init (node A)" parameter value is the value of the "net_position" calculated from the output of the Antares calculation for node A, considering results we get from the Antares calculation at the end of Local matching rule optimization. -- “ENS_init” parameter: -The “ENS_init (node A)” parameter value is the value of the “ENS” obtained from the output of the Antares calculation for node A at the end of Local matching rule optimization. +- "ENS_init" parameter: +The "ENS_init (node A)" parameter value is the value of the "ENS" obtained from the output of the Antares calculation for node A at the end of Local matching rule optimization. -- “DENS_new” parameter: The “DENS_new (node A)” parameter value is an update of the value of the “DENS” parameter which takes into account the result of Antares calculation (therefore different than the one estimated in Local matching rule optimization). +- "DENS_new" parameter: The "DENS_new (node A)" parameter value is an update of the value of the "DENS" parameter which takes into account the result of Antares calculation (therefore different from the one estimated in Local matching rule optimization). -- “Spillage_init” parameter: -The “Spillage_init (node A)” parameter value is the value of the “Spillage” obtained from the output of the Antares calculation for node A at the end of Local matching rule optimization. +- "Spillage_init" parameter: +The "Spillage_init (node A)" parameter value is the value of the "Spillage" obtained from the output of the Antares calculation for node A at the end of Local matching rule optimization. -- “Hurdle cost” parameter on links: +- "Hurdle cost" parameter on links: This parameter, fixed on links, is kept from the Antares optimization problem. -Like “flows” we can split “Hurdle cost” in “Hurdle_cost_direct” and “Hurdle_cost_indirect” +Like "flows" we can split "Hurdle cost" in "Hurdle_cost_direct" and "Hurdle_cost_indirect" ### Constraints and relations between variables -- **Constraints on “Flows”, “Flow_direct” and “Flow_indirect” variables:** -These variables should have exactly the same constraints than the ones considered in the Antares problem: +- **Constraints on "Flows", "Flow_direct" and "Flow_indirect" variables:** +These variables should have exactly the same constraints as the ones considered in the Antares problem: - NTC constrains (independent lower and upper bounds for each link). - Flowbased binding constraints to be extracted from the hourly binding constraint list. -- **Relation between “Flows” over links and “net_position” on nodes:** -The value of “net_position (node A)” is deduced from “flow” variable as follows: +- **Relation between "Flows" over links and "net_position" on nodes:** +The value of "net_position (node A)" is deduced from "flow" variable as follows: - - net_position (node A) = $\sum$ algebraic “Flows” over links involving node A + - net_position (node A) = $\sum$ algebraic "Flows" over links involving node A Remember that: - - a “Flow” that goes from another node “2” to node A is an import for node A and should be counted positively - - a “Flow” that goes from node A to another node “2” is an export for node A and should be counted negatively. + - a "Flow" that goes from another node "2" to node A is an import for node A and should be counted positively + - a "Flow" that goes from node A to another node "2" is an export for node A and should be counted negatively. -- **The detailed formulation for calculating the value of “net_position (node A)” is, for all “nodes 2 upstream” and all “nodes 2 downstream”:** +- **The detailed formulation for calculating the value of "net_position (node A)" is, for all "nodes 2 upstream" and all "nodes 2 downstream":** - net_position (node A) = $\sum$ flow_direct (node 2 upstream -> node A) + $\sum$ flow_indirect (node A <- node 2 downstream) - $\sum$ flow_indirect (node 2 upstream <- node A) - $\sum$ flow_direct (node A -> node 2 downstream) Considering that: - - “Node 2 upstream” is any node “2” which name in alphabetic order is before node A - - “Node 2 downstream” is any node “2” which name in alphabetic order is after node A + - "Node 2 upstream" is any node "2" which name in alphabetic order is before node A + - "Node 2 downstream" is any node "2" which name in alphabetic order is after node A - **Formula for calculating DENS_new parameter:** - DENS_new (node A) = max [ 0; ENS_init (node A) + net_position_init (node A) - DTG.MRG (node A)] - Depending on the parameter in the GUI that includes or not possible imports from nodes “1” to nodes “2” in the DENS calculation, we should modify this formula. Precisely, it is when “NTC from physical areas outside to physical areas inside adequacy patch” is set to null then the formulation such be modified as follows: + Depending on the parameter in the GUI that includes or not possible imports from nodes "1" to nodes "2" in the DENS calculation, we should modify this formula. Precisely, it is when "NTC from physical areas outside to physical areas inside adequacy patch" is set to null then the formulation such be modified as follows: - DENS_new (node A) = max [ 0; ENS_init (node A) + net_position_init (node A) + $\sum$ flows (node 1 -> node A) - DTG.MRG (node A)] - The detailed formulation for calculating the last term is, for all “nodes 1 upstream” and all “nodes 1 downstream”: + The detailed formulation for calculating the last term is, for all "nodes 1 upstream" and all "nodes 1 downstream": - $\sum$ flows (node 1 -> node A) = $\sum$ flow_direct (node 1 upstream -> node A) + $\sum$ flow_indirect (node A <- node 1 downstream) Considering that: - - “Node 1 upstream” is any node “1” which name in alphabetic order is before node A - - “Node 1 downstream” is any node “1” which name in alphabetic order is after node A + - "Node 1 upstream" is any node "1" which name in alphabetic order is before node A + - "Node 1 downstream" is any node "1" which name in alphabetic order is after node A - The consideration of a correct DENS_new as presented above should ensure that the Local Matching Approach is respected, (node A) can’t be "Exporting” and having ENS after CSR. + The consideration of a correct DENS_new as presented above should ensure that the Local Matching Approach is respected, (node A) can’t be "Exporting" and having ENS after CSR. - **Relation induced by node balancing conservation:** - ENS (node A) + net_position (node A) – spillage (node A) = ENS_init (node A) + net_position_init (node A) – spillage_init (node A) - Actually, this simplified formulation takes into account that these variables are the only ones we are allowed to update by this optimization (power generation for all nodes and power flows between other nodes than nodes “2” will not be modified). + Actually, this simplified formulation takes into account that these variables are the only ones we are allowed to update by this optimization (power generation for all nodes and power flows between other nodes than nodes "2" will not be modified). - **Constraint induced by Local matching rule:** - - ENS (node A) $\le DENS_{new}(node~A)$ + - ENS (node A) $\leq DENS_{new}(node~A)$ - **Positivity constraints:** - - ENS (node A) $\ge$ 0 - - spillage (node A) $\ge$ 0 + - ENS (node A) $\geq$ 0 + - spillage (node A) $\geq$ 0 _**Notes**_ -- _“Spillage” variable and “Spillage_init” parameter have been introduced only to deal with some situations for which “Flowbased” constraints, combining with adequacy patch rules, lead to an increase of Total ENS over the different nodes “2”. Such increase of Total ENS could happen for 2 reasons:_ +- _"Spillage" variable and "Spillage_init" parameter have been introduced only to deal with some situations for which "Flowbased" constraints, combining with adequacy patch rules, lead to an increase of Total ENS over the different nodes "2". Such increase of Total ENS could happen for 2 reasons:_ - _We have new violations of Local Matching rule and the optimal solution found by Antares is no longer a valid solution, regards to this rule;_ - _The curtailment sharing rule target is to minimize $\sum$(ENS$^2$/PTO) and such objective is not exactly equivalent than minimizing Total ENS._ - _As a matter of fact, if we sum over all nodes “2” the relation induced by node balancing conservation, as the sum of all “net_position” is null, it leads to:_ + _As a matter of fact, if we sum over all nodes "2" the relation induced by node balancing conservation, as the sum of all "net_position" is null, it leads to:_ - - _Total ENS – Total Spillage = Total ENS_init – Total Spillage_init, over all nodes “2”_ + - _Total ENS – Total Spillage = Total ENS_init – Total Spillage_init, over all nodes "2"_ - _So, an increase of Total ENS will necessarily leads to the same increase of Total Spillage._ + _So, an increase of Total ENS will necessarily lead to the same increase of Total Spillage._ -- _Spillage results after curtailment sharing rule quadratic optimization are presented in the separate column inside Antares output, titled “SPIL. ENRG. CSR” so the user has access to the spillage results both prior to and after CSR optimization._ -- _In order to avoid solver issues, lower and upper boundaries of the ENS and Spillage variables can be relaxed using GUI option “Relax CSR variable boundaries”. Following relaxations can be imposed:_ - - $-10^{-m} \le ENS(node~A) \le DENS_{new} (node~A) + 10^{-m}$ - - $-10^{-m} \le spillage(node~A) \le + \infty$ +- _Spillage results after curtailment sharing rule quadratic optimization are presented in the separate column inside Antares output, titled "SPIL. ENRG. CSR" so the user has access to the spillage results both prior to and after CSR optimization._ +- _In order to avoid solver issues, lower and upper boundaries of the ENS and Spillage variables can be relaxed using GUI option "Relax CSR variable boundaries". Following relaxations can be imposed:_ + - $-10^{-m} \leq ENS(node~A) \leq DENS_{new} (node~A) + 10^{-m}$ + - $-10^{-m} \leq spillage(node~A) \leq + \infty$ Where $m$ is an integer defined by the user. @@ -191,18 +195,18 @@ _**Notes**_ - Minimize $\left[ \sum\frac{ENS^2}{PTO} + \sum \frac{1}{M} \left( hurdle cost direct \times flow direct \right) + \sum \frac{1}{M} \left( hurdle cost indirect \times flow_ indirect \right) \right]$ -The 2 latest terms are introduced to minimize loop flows in the considering domain, and $M$ is the highest curtailment cost between a links's origin and destination nodes, used to adapt the scale of hurdle costs to this new objective (in practice, those tend to be the same for all nodes, typically 3000€/MW or 10000€/MW). -In order to assess the quality of the CSR solution additional verification can be imposed by activating GUI option “Check CSR cost function value prior and after CSR optimization”. Values of the objective function prior to and after quadratic optimization will be calculated and compared. If the objective function value after the quadratic optimization has decreased, the new CSR solution will be accepted and presented in the Antares output. However, if after quadratic optimization the objective function value has increased (or stayed the same), LMR solution will be adopted as the final one and warning will be logged out with the appropriate information (year, hour cost prior to quad optimization, cost after quadratic optimization). +The 2 latest terms are introduced to minimize loop flows in the considering domain, and $M$ is the highest curtailment cost between a link's origin and destination nodes, used to adapt the scale of hurdle costs to this new objective (in practice, those tend to be the same for all nodes, typically 3000€/MW or 10000€/MW). +In order to assess the quality of the CSR solution additional verification can be imposed by activating GUI option "Check CSR cost function value prior and after CSR optimization". Values of the objective function prior to and after quadratic optimization will be calculated and compared. If the objective function value after the quadratic optimization has decreased, the new CSR solution will be accepted and presented in the Antares output. However, if after quadratic optimization the objective function value has increased (or stayed the same), LMR solution will be adopted as the final one and warning will be logged out with the appropriate information (year, hour cost prior to quad optimization, cost after quadratic optimization). - $QUAD 0 = \left[ \sum \frac{ENS init^2}{PTO} + \sum \frac{1}{M} \left( hurdle cost direct \times flow direct init \right) + \sum \frac{1}{M} \left( hurdle cost indirect \times flow indirect init \right) \right]$ - $QUAD 1 = \left[ \sum \frac{ENS final^2}{PTO} + \sum \frac{1}{M} \left( hurdle cost direct \times flow direct final \right) + \sum \frac{1}{M} \left( hurdle cost indirect \times flow indirect final \right) \right]$ If: -- $QUAD 0 \le QUAD 1$ -(CSR does not improve QUAD) then the “_init” solution is kept and the CSR solution is hence disregarded. +- $QUAD 0 \leq QUAD 1$ +(CSR does not improve QUAD) then the "_init" solution is kept and the CSR solution is hence disregarded. - $QUAD 0 > QUAD 1$ -(CSR does improve QUAD) then the “CSR” solution is kept as final result updating the “_init” solution as stated above. +(CSR does improve QUAD) then the "CSR" solution is kept as final result updating the "_init" solution as stated above. ### Post-optimization process @@ -210,15 +214,15 @@ For the CSR triggered hours, if after quadratic optimization, area inside adequa - ENS (node A) > 0 -following adjustments will be performed. Available dispatchable margin “DTG MRG” will be used to compensate for the residual unsupplied energy ENS: +following adjustments will be performed. Available dispatchable margin "DTG MRG" will be used to compensate for the residual unsupplied energy ENS: - ENS (node A) = max[0.0, ENS (node A) - DTG.MRG (node A)] -Remaining dispatchable margin after above-described post-optimisation calculation is stored inside new column “DTG MRG CSR” +Remaining dispatchable margin after above-described post-optimisation calculation is stored inside new column "DTG MRG CSR" - DTG.MRG.CSR (node A) = max[0.0, DTG.MRG (node A) - ENS (node A)] -Note that for all the hours for which curtailment sharing rule was not triggered, as well as for the hours for which curtailment sharing rule was triggered but after quadratic optimization ENS (node A) is equal to zero, DTG.MRG.CSR (node A) will be equal to DTG.MRG (node A). For the curtailment sharing rule triggered hours, if after quadratic optimization and above-described post calculation process, area inside adequacy patch still experiences unsupplied energy, marginal price “MRG.PRICE” will be aligned with the price cap in the model (set to Unsupplied Energy Cost in the results). +Note that for all the hours for which curtailment sharing rule was not triggered, as well as for the hours for which curtailment sharing rule was triggered but after quadratic optimization ENS (node A) is equal to zero, DTG.MRG.CSR (node A) will be equal to DTG.MRG (node A). For the curtailment sharing rule triggered hours, if after quadratic optimization and above-described post calculation process, area inside adequacy patch still experiences unsupplied energy, marginal price "MRG.PRICE" will be aligned with the price cap in the model (set to Unsupplied Energy Cost in the results). - MRG.PRICE (node A) = Unsupplied Energy Cost (node A) diff --git a/docs/user-guide/solver/optional-features/multi-threading.md b/docs/user-guide/solver/optional-features/multi-threading.md new file mode 100644 index 0000000000..c2c13bee46 --- /dev/null +++ b/docs/user-guide/solver/optional-features/multi-threading.md @@ -0,0 +1,62 @@ +--- +hide: + - toc +--- + +# Multi-threading + +[//]: # (TODO: update this page if needed) +_**This section is under construction**_ + +Multi-threading is also available on the proper calculation side, on a user-defined basis. + +Provided that hardware resources are large enough, this mode may reduce significantly the overall runtime of heavy simulations. + +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` + +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. +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. + +| _Available CPU Cores_ | _Minimum_ | _Low_ | _Medium_ | _Large_ | _Maximum_ | +|:---------------------:|:---------:|:---------:|:---------:|:----------:|:---------:| +| _1_ | 1 | 1 | 1 | 1 | 1 | +| _2_ | 1 | 1 | 1 | 2 | 2 | +| _3_ | 1 | 2 | 2 | 2 | 3 | +| _4_ | 1 | 2 | 2 | 3 | 4 | +| _5_ | 1 | 2 | 3 | 4 | 5 | +| _6_ | 1 | 2 | 3 | 4 | 6 | +| _7_ | 1 | 2 | 3 | 5 | 7 | +| _8_ | 1 | 2 | 4 | 6 | 8 | +| _9_ | 1 | 3 | 5 | 7 | 8 | +| _10_ | 1 | 3 | 5 | 8 | 9 | +| _11_ | 1 | 3 | 6 | 8 | 10 | +| _12_ | 1 | 3 | 6 | 9 | 11 | +| _S > 12_ | 1 | Ceil(S/4) | Ceil(S/2) | Ceil(3S/4) | S-1 | + +**Note**: The number of independent threads actually launched by Antares in parallel mode may appear smaller than that shown in the table above. In this case, the resources monitor menu and the dashboard displayed on starting the simulation indicates: + +simulation cores: **nn** reduced to **pp** + +**nn** is the regular allowance and **pp** is the practical value that the solver has to work with. Allowance reduction may occur if the built-in Time-Series generators are activated, their "refresh" status is set to "Yes" and the values given to the "refresh span" parameters are not appropriate (parallel execution demand that refresh operations do not take place within a bundle of parallel years). Optimal use of the "parallel" execution mode is obtained when all activated built-in time –series generators are set up in either of the two following ways: +- Refresh status : **No** +- Refresh status : **Yes**, refresh span = **Ki \* (CPU allowance)** , with **Ki >= 1** + +Examples of reduction from an initial allowance of 12 cores are given hereafter. The reduced allowance is the size of the **smallest** bundle of parallel years between two consecutive "refresh" (it indicates the slowest point of the simulation [^23]). Note that RAM requirements displayed in the resources monitor are, contrariwise, assessed on the basis on the **largest** bundle of parallel years encountered in the simulation). + +![Reduced_Allowance](Reduced_Allowance.png) + +The Table indicates either the refresh status (No) or the refresh span (the associated refresh status "yes" is implicit). + + + +[^23]: When the number of MC years to run is smaller than the allowance, the parallel run includes all of these years in a single bundle and there is no "reduced allowance" message + +[^24]: +The smallest bundle in this case is the ninth (year number 97 to year number 100).The first 8 bundles involve 12 MC years each. diff --git a/docs/reference-guide/16-xpress.md b/docs/user-guide/solver/optional-features/xpress.md similarity index 94% rename from docs/reference-guide/16-xpress.md rename to docs/user-guide/solver/optional-features/xpress.md index 591e086fbe..961ad83b50 100644 --- a/docs/reference-guide/16-xpress.md +++ b/docs/user-guide/solver/optional-features/xpress.md @@ -1,4 +1,7 @@ -# Usage with FICO® Xpress Optimization +# Usage with FICO® Xpress Optimizer + +[//]: # (TODO: update this page if needed) +_**This section is under construction**_ ## Introduction The FICO Xpress optimizer is a commercial optimization solver for linear programming (LP), mixed integer linear programming (MILP), convex quadratic programming (QP), convex quadratically constrained quadratic programming (QCQP), second-order cone programming (SOCP) and their mixed integer counterparts. diff --git a/docs/user-guide/ts-generator/00-index.md b/docs/user-guide/ts-generator/00-index.md new file mode 100644 index 0000000000..264054542c --- /dev/null +++ b/docs/user-guide/ts-generator/00-index.md @@ -0,0 +1,12 @@ +[//]: # (Index used by Sphinx to generate correct PDF tree) +# Time-series generator + +```{toctree} +:hidden: +01-overview.md +02-inputs.md +03-outputs.md +04-parameters.md +05-algorithm.md +06-command-line.md +``` \ No newline at end of file diff --git a/docs/user-guide/ts-generator/01-overview.md b/docs/user-guide/ts-generator/01-overview.md new file mode 100644 index 0000000000..e77bab6872 --- /dev/null +++ b/docs/user-guide/ts-generator/01-overview.md @@ -0,0 +1,9 @@ +# Overview + +_**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 +(such as renewable energy production time-series) +and put them automatically inside the *Antares* [solver](../solver/02-inputs.md)'s input directory. diff --git a/docs/user-guide/ts-generator/02-inputs.md b/docs/user-guide/ts-generator/02-inputs.md new file mode 100644 index 0000000000..66cac87646 --- /dev/null +++ b/docs/user-guide/ts-generator/02-inputs.md @@ -0,0 +1,7 @@ +# Input files + +_**This section is under construction**_ + +> _**Note:**_ Some specific input data may be located outside the study folder: this is the case for the historical +> times-series to be processed by the time-series analyzer, which may be stored either within the "user" subfolder of +> the study or anywhere else (for instance, on a remote "historical data" or "Meteorological data" server). \ No newline at end of file diff --git a/docs/user-guide/ts-generator/03-outputs.md b/docs/user-guide/ts-generator/03-outputs.md new file mode 100644 index 0000000000..5336711567 --- /dev/null +++ b/docs/user-guide/ts-generator/03-outputs.md @@ -0,0 +1,27 @@ +# Output files + +_**This section is under construction**_ + +1. The outputs of the Antares time-series analyzer are not printed in the general output files but kept within + the input files structure (the reason being that they are input data for the Antares time - series generators). + The associated data may nonetheless be accessed to be reviewed, updated and deleted at any time through the GUI. +2. The times-series analyzer requires the use of a temporary directory in which intermediate files are created + in the course of the analysis and deleted in the end, unless the user wishes to keep them for further examination. + Its location is user-defined and should usually be the "user" subfolder if files are to be kept, otherwise any + proper temporary space such as `C..../Temp`. + +## Scenario mapping file +"scenariobuilder.dat" + +**MC Scenario builder** For each Monte-Carlo year of the simulation defined in the "Simulation" window, +this command allows to state, for each kind of time-series, whether it should be randomly drawn from +the available set (be it ready-made or Antares-generated) _**OR**_ should take a user-defined value +(in the former case, the default "rand" value should be kept; in the latter, the value should be the reference number +of the time-series to use). Multiple simulation profiles can be defined and archived. +The default active profile gives the "rand" status for all time-series in all areas (full probabilistic simulation). + +Regarding Hydro time-series, the scenario builder gives, in addition to the assignment of a specific number to use +for the inflows time-series, the ability to define the initial reservoir level to use for each MC year, also hydro +max power scenario builder is available to support time-series for Maximum Generation and Maximum Pumping because +the number of TS's for ROR, Hydro Storage and Minimum Generation can be different than the number of TS's for +Maximum Generation and Maximum Pumping. \ No newline at end of file diff --git a/docs/user-guide/ts-generator/04-parameters.md b/docs/user-guide/ts-generator/04-parameters.md new file mode 100644 index 0000000000..2fac490989 --- /dev/null +++ b/docs/user-guide/ts-generator/04-parameters.md @@ -0,0 +1,210 @@ +# Parameters + +_**This section is under construction**_ + +[//]: # (TODO: check that these parameters are not used in the solver.) +[//]: # (If they are used by the solver -but only in case some TS are generated-, keep them here but add cross mentions to them) + +--- +## General parameters +These parameters are listed under the `[general]` section in the `.ini` file. + +--- +### Time-series parameters + +--- +#### generate +- **Expected value:** comma-seperated list of 0 to N elements among the following (case-insensitive): + `load`, `wind`, `hydro`, `thermal`, `solar`, `renewables`, `max-power` (ex: `generate = load, hydro, wind`) +- **Required:** no +- **Default value:** empty +- **Usage:** if left empty, all the time-series will be imported from input files. Else, the time-series + listed in this parameter will be generated randomly by the simulator. + +> _**WARNING:**_ time-series generation is not available for transmission capacities (NTC) + +--- +#### nbtimeseriesload +- **Expected value:** unsigned integer +- **Required:** no +- **Default value:** 1 +- **Usage:** if `load` time-series are [automatically generated](#generate), this parameter sets the number of different + time-series to generate. + +--- +#### nbtimeserieshydro +- **Expected value:** unsigned integer +- **Required:** no +- **Default value:** 1 +- **Usage:** if `hydro` time-series are [automatically generated](#generate), this parameter sets the number of different + time-series to generate. + +--- +#### nbtimeserieswind +- **Expected value:** unsigned integer +- **Required:** no +- **Default value:** 1 +- **Usage:** if `wind` time-series are [automatically generated](#generate), this parameter sets the number of different + time-series to generate. + +--- +#### nbtimeseriesthermal +- **Expected value:** unsigned integer +- **Required:** no +- **Default value:** 1 +- **Usage:** if `thermal` time-series are [automatically generated](#generate), this parameter sets the number of different + time-series to generate. + +--- +#### nbtimeseriessolar +- **Expected value:** unsigned integer +- **Required:** no +- **Default value:** 1 +- **Usage:** if `solar` time-series are [automatically generated](#generate), this parameter sets the number of different + time-series to generate. + +--- +#### refreshtimeseries +[//]: # (TODO: verify usage) +- **Expected value:** comma-seperated list of 0 to N elements among the following (case-insensitive): + `load`, `wind`, `hydro`, `thermal`, `solar`, `renewables`, `max-power` +- **Required:** no +- **Default value:** empty +- **Usage:** if some time-series are [automatically generated](#generate), this parameter selects those of them that have + to be periodically renewed in run-time + +> _**WARNING:**_ time-series refresh is not available for transmission capacities (NTC) + +--- +#### intra-modal +[//]: # (TODO: verify usage) +- **Expected value:** comma-seperated list of 0 to N elements among the following (case-insensitive): + `load`, `wind`, `hydro`, `thermal`, `solar`, `renewables`, `ntc`, `max-power` +- **Required:** no +- **Default value:** empty +- **Usage:** if some time-series are [automatically generated](#generate), this parameter selects those of them that are + correlated, i.e. for which the same time-series should be used together in a given scenario. + +> _**WARNING:**_ inter-modal correlation is not available for transmission capacities (NTC) +> _**WARNING:**_ this is the historical correlation mode + +--- +#### inter-modal +[//]: # (TODO: document this parameter) +_**This section is under construction**_ +- **Expected value:** +- **Required:** **yes** +- **Default value:** +- **Usage:** + +> _**Note:**_ +> A full meteorological correlation (for each MC year) is, from a theoretical standpoint, achievable by activating +> "intramodal" and "intermodal" for all but the `thermal` kind of time-series. The availability of an underlying +> comprehensive multidimensional meteorological database of ready-made time-series is the crux of the matter when it +> comes to using this configuration. + +--- +#### improveunitsstartup +[//]: # (TODO: document this parameter -seems deprecated-) +_**This section is under construction**_ +- **Expected value:** +- **Required:** **yes** +- **Default value:** +- **Usage:** + +--- +#### refreshintervalload +- **Expected value:** strictly positive integer +- **Required:** no +- **Default value:** 100 +- **Usage:** if `load` time-series are automatically [generated](#generate) and [refreshed](#refreshtimeseries), this + parameter sets their refresh interval (in number of Monte-Carlo years). + +--- +#### refreshintervalhydro +- **Expected value:** strictly positive integer +- **Required:** no +- **Default value:** 100 +- **Usage:** if `hydro` time-series are automatically [generated](#generate) and [refreshed](#refreshtimeseries), this + parameter sets their refresh interval (in number of Monte-Carlo years). + +--- +#### refreshintervalwind +- **Expected value:** strictly positive integer +- **Required:** no +- **Default value:** 100 +- **Usage:** if `wind` time-series are automatically [generated](#generate) and [refreshed](#refreshtimeseries), this + parameter sets their refresh interval (in number of Monte-Carlo years). + +--- +#### refreshintervalthermal +- **Expected value:** strictly positive integer +- **Required:** no +- **Default value:** 100 +- **Usage:** if `thermal` time-series are automatically [generated](#generate) and [refreshed](#refreshtimeseries), this + parameter sets their refresh interval (in number of Monte-Carlo years). + +--- +#### refreshintervalsolar +- **Expected value:** strictly positive integer +- **Required:** no +- **Default value:** 100 +- **Usage:** if `solar` time-series are automatically [generated](#generate) and [refreshed](#refreshtimeseries), this + parameter sets their refresh interval (in number of Monte-Carlo years). + + +--- +## Input parameters +These parameters are listed under the `[input]` section in the `.ini` file. + +--- +#### import +- **Expected value:** comma-seperated list of 0 to N elements among the following (case-insensitive): + `load`, `wind`, `hydro`, `thermal`, `solar`, `renewables`, `ntc`, `max-power` +- **Required:** no +- **Default value:** empty +- **Usage:** if some time-series are [automatically generated](#generate), this parameter selects those of them that + 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. + +--- +## Seeds - Mersenne Twister parameters +These parameters are listed under the `[seeds - Mersenne Twister]` section in the `.ini` file. +They allow the user to set the seeds of random number generators, in order to ensure the results are repeatable. + +--- +#### seed-tsgen-load +- **Expected value:** unsigned integer +- **Required:** **yes** +- **Usage:** if `load` time-series are [automatically generated](#generate), this parameter fixes the seed for its + random generator. + +--- +#### seed-tsgen-hydro +- **Expected value:** unsigned integer +- **Required:** **yes** +- **Usage:** if `hydro` time-series are [automatically generated](#generate), this parameter fixes the seed for its + random generator. + +--- +#### seed-tsgen-wind +- **Expected value:** unsigned integer +- **Required:** **yes** +- **Usage:** if `wind` time-series are [automatically generated](#generate), this parameter fixes the seed for its + random generator. + +--- +#### seed-tsgen-thermal +- **Expected value:** unsigned integer +- **Required:** **yes** +- **Usage:** if `thermal` time-series are [automatically generated](#generate), this parameter fixes the seed for its + random generator. + +--- +#### seed-tsgen-solar +- **Expected value:** unsigned integer +- **Required:** **yes** +- **Usage:** if `solar` time-series are [automatically generated](#generate), this parameter fixes the seed for its + random generator. \ No newline at end of file diff --git a/docs/reference-guide/06-time_series_analysis_and_generation.md b/docs/user-guide/ts-generator/05-algorithm.md similarity index 87% rename from docs/reference-guide/06-time_series_analysis_and_generation.md rename to docs/user-guide/ts-generator/05-algorithm.md index f0fbbfa640..85afee3ca9 100644 --- a/docs/reference-guide/06-time_series_analysis_and_generation.md +++ b/docs/user-guide/ts-generator/05-algorithm.md @@ -1,4 +1,6 @@ -# Time-series analysis and generation +# Algorithm + +_**This section is under construction**_ ## General @@ -11,7 +13,7 @@ The different categories of time-series call for wholly different generation pro - For Hydro-power, the generator works out monthly time-series of energies, based on the assumption that they can be modeled by Log Normal variables with known correlations through space and time. So as to keep the model simple, for an interconnected system made of N areas, the user defines, along with the N expectations and N standard deviations of the monthly energies, the N X N correlation matrix R(n,m) of the logs of the annual hydro energies between the areas n,m, and the N average auto-correlations r(k) between one month and the next in each area k. The correlation **C(n,i,m,j)** between the logs of hydro energies in area **n**, month **i** and area **m**, month **j** is taken to be $$C(n,i,m,j) = R(n,m)*\sqrt{(r(n) \cdot r(m))^{|j-i|}}$$ - + This most simplified model asks for considerably fewer data than a comprehensive 12N X 12N time-space matrix. Note that if R is positive semi-definite but C is not, matrix C is automatically transformed into a fitting p.s.d matrix and the data generation keeps going on (however, the log report will show a warning message). If the primary matrix R is not p.s.d, data are considered as corrupted, the generation stops and a fatal error message will be displayed in the log report @@ -60,7 +62,7 @@ In the expressions of expectation and variance, $\Gamma(x)$ is the standard Eule $$\Phi(\theta, \mu, h)\ =\ {1\over A}\ *\ \sum_{i=0, \mu}{\ \sum_{j=h, h+\mu}{e^{-\theta|j-i|}}}$$ -**with** +**with** $$A=\mu + 2 \sum_{i=1, \mu; j=1, \mu; j > i}{e^{-\theta(j-i)}}$$ @@ -71,9 +73,9 @@ The section of the GUI specific to the generation of wind, solar and load time-s 1. **Spatial correlation matrices that are located within the "spatial correlation" tab of each path "Wind|Solar|Load / <area\_name>"** - This tab contains a workspace for the description of 12 monthly spatial correlation matrices $\Xi$ and one annual correlation matrix. For the stochastic generators to work properly, these matrices must meet the usual requirements (matrices must be p.s.d, symmetric, with all terms between -100 and +100, and a main diagonal made of 100s). If this is not the case, generators will emit an infeasibility diagnosis. Matrices can be either set up manually OR automatically filled out by the time-series analyzer (see next paragraph). - - Depending on the choices made in the main "simulation" window, the matrices used will be either the 12 monthly matrices or the annual matrix. Whether to use the first or the second option depends on the quality of the statistical data at hand: with high quality data (for instance, that derived from the analysis of a very large pool of historical data), use of monthly correlations is recommended because monthly differences between matrices have a physical meaning ; with less robust data (derived from a handful of historical data,…), use of the single annual correlation matrix should be preferred because it smooths out the numeric noise which impairs the monthly matrices. + This tab contains a workspace for the description of 12 monthly spatial correlation matrices $\Xi$ and one annual correlation matrix. For the stochastic generators to work properly, these matrices must meet the usual requirements (matrices must be p.s.d, symmetric, with all terms between -100 and +100, and a main diagonal made of 100s). If this is not the case, generators will emit an infeasibility diagnosis. Matrices can be either set up manually OR automatically filled out by the time-series analyzer (see next paragraph). + + Depending on the choices made in the main "simulation" window, the matrices used will be either the 12 monthly matrices or the annual matrix. Whether to use the first or the second option depends on the quality of the statistical data at hand: with high quality data (for instance, that derived from the analysis of a very large pool of historical data), use of monthly correlations is recommended because monthly differences between matrices have a physical meaning ; with less robust data (derived from a handful of historical data,…), use of the single annual correlation matrix should be preferred because it smooths out the numeric noise which impairs the monthly matrices. 2. **Four parameters and four subtabs that are located within the "local" tab of each path "Wind|Solar|Load / <area\_name>"** @@ -98,17 +100,17 @@ The section of the GUI specific to the generation of wind, solar and load time-s **FOUR SUBTABS** - Subtab "Coefficients" - A twelve-month table of values for the primary parameters $\alpha$, $\beta$, $\gamma$, $\delta$, $\theta$, $\mu$
- This table may be either filled out manually or automatically (use of the time-series analyzer) + A twelve-month table of values for the primary parameters $\alpha$, $\beta$, $\gamma$, $\delta$, $\theta$, $\mu$
+ This table may be either filled out manually or automatically (use of the time-series analyzer) - Subtab "Translation" - Contains an 8760-hour array T to add to the time-series generated, prior or after scaling. This array can be either filled out manually or by the time-series analyzer. + Contains an 8760-hour array T to add to the time-series generated, prior or after scaling. This array can be either filled out manually or by the time-series analyzer. - Subtab "Daily profile" - A 24\*12 table of hourly / monthly coefficients K(hm) that are used to modulate the values of the stationary stochastic process by which the actual process is approximated. This table can be either filled out manually or by the time-series analyzer. + A 24\*12 table of hourly / monthly coefficients K(hm) that are used to modulate the values of the stationary stochastic process by which the actual process is approximated. This table can be either filled out manually or by the time-series analyzer. - Subtab "Conversion" - A table of 2 \* N values (with 1<=N<=50) that is used to turn the initial time-series produced by the generators (for instance, wind speeds) into final data (for instance, wind power). The transfer function (speed to power, etc.) is approximated by N discrete points whose abscises X(N) an ordinates Y(N) are given by the table. + A table of 2 \* N values (with 1<=N<=50) that is used to turn the initial time-series produced by the generators (for instance, wind speeds) into final data (for instance, wind power). The transfer function (speed to power, etc.) is approximated by N discrete points whose abscises X(N) an ordinates Y(N) are given by the table. ## Time-series analysis (load, wind, solar) @@ -192,8 +194,8 @@ The primary TS analyzer window shows two tabs: ## Time-series generation (thermal) The thermal time-series generation will only be launched: - - On thermal clusters that have the Generated TS parameter set to “Force generation” - - And, when in the Simulation window, the Stochastic TS parameter for Thermal is set to "On”, on the thermal clusters that have the Generated TS parameter set to "Use global parameter". +- On thermal clusters that have the Generated TS parameter set to “Force generation” +- And, when in the Simulation window, the Stochastic TS parameter for Thermal is set to "On”, on the thermal clusters that have the Generated TS parameter set to "Use global parameter". The stochastic generator for time-series of available dispatchable power generation works, for each plant of each set (cluster), with the following parameters: @@ -357,23 +359,23 @@ Different ways can be considered to work out values for FOR,POR,FOD,POD from his With the following notations: - D(w) = Overall cumulated statistical observation time available for week (w) - for instance, for w = 1= first week of January : D(w) = 3500 days coming from 10 years of observation of 50 identical plants + for instance, for w = 1= first week of January : D(w) = 3500 days coming from 10 years of observation of 50 identical plants - Df(w) = Within D(w), overall time spent in forced outages, either beginning during week w or before (for instance , Df(1) = 163 days) - Dp(w) = Within D(w), overall time spent in planned outages, either beginning during week w or before (for instance, Dp(1) = 22 days) - Kf(w) = Number of forced outages beginning during week (w) - (for instance, Kf(1) = 26) + (for instance, Kf(1) = 26) - Kp(w) = Number of planned outages beginning during week (w) - (for instance, Kp(1) = 3) + (for instance, Kp(1) = 3) - FOT(w) = Overall cumulated time (expressed in days) spent in forced outages beginning during week (w) (for instance, FOT(1)= 260) - Note that if outages last more than one week FOT(w) necessarily includes days from weeks w+1, w+2,… + Note that if outages last more than one week FOT(w) necessarily includes days from weeks w+1, w+2,… - POT(w) = Overall cumulated time (expressed in days) spent in planned outages beginning during week (w) (for instance, POT(1) = 84) - Note that if outages last more than one week POT(w) necessarily includes days from weeks w+1, w+2,… + Note that if outages last more than one week POT(w) necessarily includes days from weeks w+1, w+2,… The following formulas can be used : @@ -412,16 +414,16 @@ In both cases, assuming that a large number of historical time-series of energie - **M'(n)** = time-series of K-1 elements obtained by deleting the first element of the time-series Log(M(n)) - **M''(n)** = time-series of K-1 elements obtained by deleting the last element of the time-series Log(M(n)) - Assess the correlation **IMC(n)** between the random variables **M'(n)** and **M''(n)**. This value (lying in [-1,1]) should be used to fill out the field "inter-monthly correlation value" of the "local data" tab in the "hydro" active window. + Assess the correlation **IMC(n)** between the random variables **M'(n)** and **M''(n)**. This value (lying in [-1,1]) should be used to fill out the field "inter-monthly correlation value" of the "local data" tab in the "hydro" active window. 3. For each area n, build up 12 monthly energy time-series derived from the original array **M(n)** by extracting from **M(n)** the values related to each month of the year (**M1(n)**= time-series of energies in January,…, **M12(n)** = time-series of energies in December.) - Assess the expectations and standard deviations of the 12 random variables **M1(n)** ,…, **M12(n)**. These values should be used to fill out the fields "expectation" and "std deviation" of the "local data" tab in the "hydro" active window. + Assess the expectations and standard deviations of the 12 random variables **M1(n)** ,…, **M12(n)**. These values should be used to fill out the fields "expectation" and "std deviation" of the "local data" tab in the "hydro" active window. - Aside from expectation and standard deviations, minimum and maximum bounds can be freely set on the monthly overall energies (ROR + HS). Whether to assess these bounds by examination of historical data or on the basis of other considerations depends on the context of the studies to carry out. + Aside from expectation and standard deviations, minimum and maximum bounds can be freely set on the monthly overall energies (ROR + HS). Whether to assess these bounds by examination of historical data or on the basis of other considerations depends on the context of the studies to carry out. 4. For each area n, extract from the 12 monthly overall energy time-series **M1(n) ,…, M12(n)** the contribution of the 12 monthly time-series of ROR energies **R1(n),…, R12(n)**. - Assess the expectations of the 12 random variables **R1(n)/M1(n),…., R12(n)/M12(n)** . These values should be used to fill out the fields "ROR share" of the "local data" tab in the "hydro" active window. + Assess the expectations of the 12 random variables **R1(n)/M1(n),…., R12(n)/M12(n)** . These values should be used to fill out the fields "ROR share" of the "local data" tab in the "hydro" active window. -[^decay]: Obtained by the generation of purely exponentially autocorrelated values (parameter $\theta$ ) followed by a moving average transformation (parameter $\mu$ ). $\theta$ and $\mu$ should be carefully chosen so as to accommodate at best the experimental data at hand. If meaningful historical data are available, this identification may be directly made using the Antares time-series analyzer. \ No newline at end of file +[^decay]: Obtained by the generation of purely exponentially autocorrelated values (parameter $\theta$ ) followed by a moving average transformation (parameter $\mu$ ). $\theta$ and $\mu$ should be carefully chosen so as to accommodate at best the experimental data at hand. If meaningful historical data are available, this identification may be directly made using the Antares time-series analyzer. diff --git a/docs/user-guide/ts-generator/06-command-line.md b/docs/user-guide/ts-generator/06-command-line.md new file mode 100644 index 0000000000..68ba48017f --- /dev/null +++ b/docs/user-guide/ts-generator/06-command-line.md @@ -0,0 +1,12 @@ +--- +hide: + - toc +--- + +# Command-line instructions + +| command | meaning | +|:----------------|:------------------------------------------------------------------------------------------------------------------------| +| --all-thermal | Generate TS for all thermal clusters | +| --thermal=VALUE | Generate TS for a list of area IDs and thermal clusters IDs, example: `--thermal="area1ID.clusterID;area2ID.clusterID"` | +| -h, --help | Display this help and exit | diff --git a/mkdocs.yml b/mkdocs.yml index bda8c2a598..23187934c1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,8 +12,8 @@ theme: features: - navigation.instant - navigation.top - - navigation.expand - content.tabs.link + # - navigation.expand # - navigation.sections # - header.autohide # - toc.separate @@ -31,36 +31,57 @@ theme: nav: - 'Home': 'index.md' - - 'Reference guide': - - 'Introduction': 'reference-guide/01-introduction.md' - - 'Data organization': 'reference-guide/02-data_organization.md' - - 'Commands': 'reference-guide/03-commands.md' - - 'Active windows': 'reference-guide/04-active_windows.md' - - 'Output files': 'reference-guide/05-output_files.md' - - 'Time-Series analysis and generation': 'reference-guide/06-time_series_analysis_and_generation.md' - - 'Kirchhoff''s constraint generator': 'reference-guide/07-kirchhoffs_constraint_generator.md' - - 'Miscellaneous': 'reference-guide/08-miscellaneous.md' - - 'System requirements': 'reference-guide/09-system_requirements.md' - - 'Command line': 'reference-guide/10-command_line.md' - - 'Adequacy patch (v8.3.0+)': 'reference-guide/14-adequacy-patch.md' - - 'File format changes': 'reference-guide/13-file-format.md' - - 'Attribution notices': 'reference-guide/12-attribution_notices.md' - - 'Optimisation': - - 'Optimisation problem' : 'optimisation/01-modeling.md' - - 'Thermal heuristic': 'optimisation/02-thermal-heuristic.md' - - 'Build': - - 'Introduction': 'build/0-Introduction.md' - - 'Development requirements': 'build/1-Development-requirements.md' - - 'Dependencies install': 'build/2-Dependencies-install.md' - - 'Build': 'build/3-Build.md' - - 'Tests (user)': 'build/4-Tests-user.md' - - 'Tests (developer)' : 'build/4-Tests-dev.md' - - 'Installer creation': 'build/5-Installer-creation.md' - - 'Continuous Integration' : 'build/continuous-integration.md' - - 'OR-tools integration' : 'build/ortools-integration.md' - - 'Changelog': 'CHANGELOG.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' + - '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' + - 'Continuous Integration': 'developer-guide/continuous-integration.md' + - 'OR-tools integration': 'developer-guide/ortools-integration.md' + - 'Changelog': 'developer-guide/CHANGELOG.md' - 'External links': - - 'Antares ecosystem' : 'https://antares-doc.readthedocs.io' + - 'Antares ecosystem': 'https://antares-doc.readthedocs.io' - 'Antares website': 'https://antares-simulator.org' - 'RTE website': 'http://www.rte-france.com/' diff --git a/src/cmake/changelog.cmake b/src/cmake/changelog.cmake index 5f62c40077..1164af0ed1 100644 --- a/src/cmake/changelog.cmake +++ b/src/cmake/changelog.cmake @@ -1,4 +1,4 @@ # Copy the changelog -file(READ "../docs/CHANGELOG.md" changelog_content) +file(READ "../docs/developer-guide/CHANGELOG.md" changelog_content) file(WRITE "distrib/changelog.txt" "${changelog_content}")