From 393f8f0f64b293d19b553553f50335cc24c7fa46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jason=20Mar=C3=A9chal?= <45510813+JasonMarechal25@users.noreply.github.com> Date: Thu, 22 Aug 2024 14:30:45 +0200 Subject: [PATCH] Update documentation (#902) --- .../install_from_sources/0-INSTALL.md | 11 +- .../1-Development-requirements.md | 23 +-- .../2-Dependencies-install.md | 141 ++++++------------ .../install_from_sources/3-Build.md | 7 +- .../install_from_sources/4-Tests.md | 43 +++--- docs/user-guide/get-started/installation.md | 16 +- mkdocs.yml | 2 +- 7 files changed, 100 insertions(+), 143 deletions(-) diff --git a/docs/developer-guide/install_from_sources/0-INSTALL.md b/docs/developer-guide/install_from_sources/0-INSTALL.md index e2d04c1ed..d172d94db 100644 --- a/docs/developer-guide/install_from_sources/0-INSTALL.md +++ b/docs/developer-guide/install_from_sources/0-INSTALL.md @@ -7,7 +7,6 @@ This software suite has been tested under: * Ubuntu 20.04 [![Status][ubuntu_system_svg]][ubuntu_system_link] * Microsoft Windows with Visual Studio 2019 (64-bit) [![Status][windows_vcpkg_svg]][windows_vcpkg_link] -* Centos 7 [![Status][centos_system_svg]][centos_system_link] Antares-Xpansion is built using CMake. @@ -22,10 +21,8 @@ Follow this [link][Doxygen_Code_Documentation] for Doxygen code documentation. - [UI creation](5-ui-creation.md) - [Installer creation](6-Installer-creation.md) -[ubuntu_system_svg]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/ubuntu-system-deps-build.yml/badge.svg -[ubuntu_system_link]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/ubuntu-system-deps-build.yml -[windows_vcpkg_svg]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/windows-vcpkg-deps-build.yml/badge.svg -[windows_vcpkg_link]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/windows-vcpkg-deps-build.yml -[centos_system_svg]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/centos7-system-deps-build.yml/badge.svg -[centos_system_link]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/centos7-system-deps-build.yml +[ubuntu_system_svg]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/ubuntu-system-deps-build.yml/badge.svg?query=branch%3Adevelop +[ubuntu_system_link]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/ubuntu-system-deps-build.yml?query=branch%3Adevelop +[windows_vcpkg_svg]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/windows-vcpkg-deps-build.yml/badge.svg?query=branch%3Adevelop +[windows_vcpkg_link]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/windows-vcpkg-deps-build.yml?query=branch%3Adevelop [Doxygen_Code_Documentation]: https://antaressimulatorteam.github.io/antares-xpansion/annotated.html \ No newline at end of file diff --git a/docs/developer-guide/install_from_sources/1-Development-requirements.md b/docs/developer-guide/install_from_sources/1-Development-requirements.md index 0df308b52..c06698f85 100644 --- a/docs/developer-guide/install_from_sources/1-Development-requirements.md +++ b/docs/developer-guide/install_from_sources/1-Development-requirements.md @@ -1,13 +1,13 @@ # Development requirements ## [C++ version](#c++-version) -The compilation of Antares-Xpansion requires C++17 support in order to use [execution policy](https://en.cppreference.com/w/cpp/algorithm/execution_policy_tag_t). +The compilation of Antares-Xpansion requires C++20. === "Windows" - Compilation is tested on MSVC 2019. + Compilation is tested on Visual Studio 17 2022. -=== "Centos" +=== "Centos" :warning: CentOS is considered EoL (end of life) and is not supported anymore. We recommend using a more recent distribution like Oracle Linux 8 By default, GCC version of Centos7 is 4.8.5. Some external repositories must be enabled: @@ -17,12 +17,6 @@ The compilation of Antares-Xpansion requires C++17 support in order to use [exe sudo yum install centos-release-scl ``` - === "Centos 8 (PowerTools)" - ``` - sudo yum install dnf-plugins-core - sudo yum config-manager --set-enabled PowerTools - ``` - You can then use a more recent version of GCC by enabling `devtoolset-10`: ``` sudo yum install devtoolset-10 @@ -35,7 +29,7 @@ The compilation of Antares-Xpansion requires C++17 support in order to use [exe === "Ubuntu" ``` - sudo apt install build-essential + sudo apt install build-essential gcc10 g++10 ``` ## [CMake version](#cmake-version) CMake 3.x must be used. @@ -49,11 +43,20 @@ CMake 3.x must be used. sudo yum install epel-release sudo yum install cmake3 ``` +Or + ``` + python -m pip install cmake + ``` + === "Ubuntu" ``` sudo apt install cmake ``` +Or +``` +python -m pip install cmake +``` ## [Python version](#python-version) Python 3.x must be used. diff --git a/docs/developer-guide/install_from_sources/2-Dependencies-install.md b/docs/developer-guide/install_from_sources/2-Dependencies-install.md index 53a4c69fc..20fc20000 100644 --- a/docs/developer-guide/install_from_sources/2-Dependencies-install.md +++ b/docs/developer-guide/install_from_sources/2-Dependencies-install.md @@ -4,104 +4,61 @@ Antares-Xpansion depends on several mandatory libraries: - [JsonCpp](https://github.com/open-source-parsers/jsoncpp), - [Google Test](https://github.com/google/googletest), -- [OR-Tools](https://github.com/AntaresSimulatorTeam/or-tools/tree/rte_dev_sirius), - [Boost](https://www.boost.org/) : MPI serialization (only for MPI benders compilation), program-options, - [Doxygen](https://www.doxygen.nl/index.html) for documentation generation, - [GraphViz](https://graphviz.org/) for Doxygen use. +- [Antares Simulator](https://github.com/AntaresSimulatorTeam/Antares_Simulator) for Antares simulation. -This section describes the install procedures for the third-party open source libraries used by Antares-Xpansion. -The install procedure can be done: +This section describes the installation procedures for the third-party open source libraries used by Antares-Xpansion. +The installation procedure can be done: - By using a package manager, - By compiling the sources after cloning the official git repository. -## Install with a package manager - -=== "Windows (VCPKG)" - - For Windows we use [vcpkg](https://github.com/microsoft/vcpkg) to download and compile the libraries. `vcpkg` is available as a submodule in Antares-Xpansion. - - 1. You must install the corresponding [vcpkg-triplet](https://vcpkg.readthedocs.io/en/latest/users/integration/#triplet-selection) depending on the Antares version and libraries load: - - - ``x64-windows`` : 64 bits version with dynamic libraries load, - - ``x86-windows`` : 32 bits version with dynamic libraries load, - - ``x64-windows-static`` : 64 bits version with static libraries load, - - ``x86-windows-static`` : 32 bits version with static libraries load. - - The chosen vcpkg-triplet will be named `` in this document. - - 2. Init submodule and install vcpkg: - - ``` - git submodule update --init vcpkg - cd vcpkg - .\bootstrap-vcpkg.bat - ``` - - All vcpkg command further described must be run from the vcpkg folder. This folder will be named `` later in this document. - - - 3. Install dependencies: - ``` - cd vcpkg - vcpkg install jsoncpp gtest boost-mpi boost-program-options --triplet - ``` - - !!! Note - Boost-mpi compilation depends on MSMPI redistributable package. Please follow VCPKG procedure : - ``` - Please install the MSMPI redistributable package before trying to install this port. - The appropriate installer has been downloaded to: - /downloads/msmpisetup-10.0.12498.exe - ``` - -=== "Centos (yum)" - - ``` - sudo yum install - sudo yum install environment-modules jsoncpp-devel gtest-devel openmpi-devel boost-openmpi-devel boost-program-options doxygen graphviz redhat-lsb-core - sudo yum install libuuid-devel - ``` - -=== "Ubuntu (apt-get)" - - ``` - sudo apt-get install lsb-release libjsoncpp-dev libgtest-dev libboost-mpi-dev doxygen graphviz libboost-program-options-dev - sudo apt-get install unzip uuid-dev - ``` - !!! Note - Depending on Ubuntu version you might need to compile google test : - ``` - cd /usr/src/googletest/ - sudo cmake . - sudo cmake --build . --target install - ``` - -## Automatic libraries compilation from git - -[Antares dependencies compilation repository](https://github.com/AntaresSimulatorTeam/antares-deps) is used as a git submodule for automatic libraries compilation from git. - -ALL dependencies can be built at configure time using the option `-DBUILD_ALL=ON` (`OFF` by default), see [here](3-Build.md#configure). For a list of available option see [Antares dependencies compilation repository](https://github.com/AntaresSimulatorTeam/antares-deps). - -Some dependencies cannot be installed with a package manager. They can be built at configure step with a `cmake` option : `-DBUILD_not_system=ON` (`ON` by default): - -!!! warning - `boost-mpi` is not compiled with this repository. On windows, VCPKG use is mandatory or you must compile `boost-mpi` by yourself. - -### Defining dependency install directory - -When using multiple directories for Antares development with multiple branches it can be useful to have a common dependency install directory. - -Dependencies install directory can be specified with `-DDEPS_INSTALL_DIR`. By default, the install directory is `/../rte-antares-deps-`. - -!!! Note - `DEPS_INSTALL_DIR` is added to `CMAKE_PREFIX_PATH`. - -### Pre-compiled libraries download : release version only -You can download pre-compiled `antares-deps` archive from the [Antares dependencies compilation repository][antares-deps-url]. Only release versions are available. - -!!! Note - For windows, you must you use a MSVC version compatible with the MSVC version used in GitHub Action. - -[antares-deps-url]: https://github.com/AntaresSimulatorTeam/antares-deps/releases/tag/v2.0.0-rc2 +## Install with a VCPKG package manager +This is the preferred method for installing dependencies. +Dependencies are described in the `vcpkg.json` file. + +### Configure VCPKG + +``` +git submodule update --init vcpkg +cd vcpkg +./bootstrap-vcpkg.sh -disableMetrics +# Or for windows +.\bootstrap-vcpkg.bat -disableMetrics +``` + +### Installing dependencies + +Dependencies can be installed with the following command but is not the prefered method + +``` +#Repository root +./vcpkg/vcpkg install +``` + +The preferred method is to install and update dependencies at configure time with cmake like in the following example: + +``` +#Repository root +cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake +cmake --build build +``` + +#### Runtime dependency + +When running Antares-Xpansion in parallel, mpirun is used. It is installed through VCPKG but needs to be added to the PATH. + +``` +export PATH=$PATH:/installed//tools/openmpi/bin +``` + +Alternatively you can install openmpi yourself + +## Other dependencies +- Antares Simulator: either build it from source, download precompiled binaries or use the next method + +## Automatic Antares Simulator build +If Antares Simulator is not installed, it will be automatically downloaded and built by the build system. \ No newline at end of file diff --git a/docs/developer-guide/install_from_sources/3-Build.md b/docs/developer-guide/install_from_sources/3-Build.md index fb2af8cb3..e8ae1218d 100644 --- a/docs/developer-guide/install_from_sources/3-Build.md +++ b/docs/developer-guide/install_from_sources/3-Build.md @@ -21,12 +21,12 @@ git submodule update --init antares-deps === "Centos" ``` - cmake3 -B _build -S . -DCMAKE_BUILD_TYPE=Release + cmake3 -B _build -S . -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-linux-release ``` === "Ubuntu" ``` - cmake -B _build -S . -DCMAKE_BUILD_TYPE=Release + cmake -B _build -S . -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-linux-release ``` Here is a list of available CMake configure options: @@ -37,12 +37,11 @@ Here is a list of available CMake configure options: |`DBUILD_antares_solver`|`ON`|Enable build of antares-solver.| |`BUILD_not_system`|`ON`|Enable build of external librairies not available on system package manager.| |`BUILD_ALL`|`OFF`|Enable build of ALL external librairies.| -|`DEPS_INSTALL_DIR`|`../rte-antares-deps-`|Define dependencies install directory.| |`BUILD_TESTING`|`OFF`|Enable test build.| |`BUILD_UI`|`OFF`|Enable UI build.| |`ALLOW_RUN_AS_ROOT`|`OFF`|allow mpi to run as root for centOs docker.| -Additionnal options for Windows: +Additionnal vcpkg options: |Option |Description | |:-------|-------| diff --git a/docs/developer-guide/install_from_sources/4-Tests.md b/docs/developer-guide/install_from_sources/4-Tests.md index 218464b86..23f13b5a8 100644 --- a/docs/developer-guide/install_from_sources/4-Tests.md +++ b/docs/developer-guide/install_from_sources/4-Tests.md @@ -9,27 +9,28 @@ ctest -C Release --output-on-failure All tests are associated to a label and multiple labels can be defined. You can choose which tests to execute when launching `ctest`. The list of available labels is the following: -| Name | Label | Description | -|:-----------------------------|-----|--------------------------------------------------------------------------------| -| `unit_logger` | `unit` | Unit test for logger use. | -| `unit_launcher` | `unit` | Unit test Antares-Xpansion python launcher. | -| `unit_solver` | `unit` | Unit test of multisolver interface(COIN only). | -| `unit_lpnamer` | `unit` | Unit test of lpnamer. | -| `unit_sensitivity` | `unit` | Unit test for sensitivity analysis. | -| `output_writer` | `unit` | Unit test for the output writer. | -| `helpers_test` | `unit` | Unit test for helpers (json reader, AntaresVersionProvider). | -| `lpnamer_end_to_end` | `lpnamer` `end_to_end` | End-to-end tests for lpnamer. | -| `examples_short_sequential` | `short` `short_sequential` `end_to_end` | Non-parallel end-to-end tests using benders algorithm on antares studies (short duration). | -| `examples_short_mpi` | `short` `short_mpi` `end_to_end` | Parallel end-to-end tests using benders algorithm on antares studies (short duration). | -| `examples_short_benders_by_batch_mpi` | `short` `short_mpi` `end_to_end` `benders_by_batch` | Parallel end-to-end tests using benders by batch algorithm on antares studies (short duration). | -| `examples_medium_sequential` | `medium` `medium_sequential` `end_to_end` | Non-parallel end-to-end tests using benders algorithm on antares studies (medium duration). | -| `examples_medium_mpi` | `medium` `medium_mpi` `end_to_end` | Parallel end-to-end tests using benders algorithm on antares studies (medium duration). | -| `examples_medium_benders_by_batch_mpi` | `medium` `medium_mpi` `end_to_end` `benders_by_batch` | Parallel end-to-end tests using benders by batch algorithm on antares studies (medium duration). | -| `examples_long_sequential` | `long` `long_sequential` `end_to_end` | Non-parallel end-to-end tests using benders algorithm on antares studies (long duration). | -| `examples_long_mpi` | `long` `long_mpi` `end_to_end` | Parallel end-to-end tests using benders algorithm on antares studies (long duration). | -| `mpibenders` | `benders`, `benders-mpi` `end_to_end` | End-to-end tests for benders mpi optimization. | -| `sequential` | `benders` `benders-sequential` `end_to_end` | End-to-end tests for benders sequential optimization. | -| `merge_mps` | `benders` `merge-mps` `end_to_end` | End-to-end tests for merge mps optimization. | +| Name | Label | Description | +|:---------------------------------------|-------------------------------------------------------|--------------------------------------------------------------------------------------------------| +| `unit_logger` | `unit` | Unit test for logger use. | +| `unit_launcher` | `unit` | Unit test Antares-Xpansion python launcher. | +| `unit_solver` | `unit` | Unit test of multisolver interface(COIN only). | +| `unit_lpnamer` | `unit` | Unit test of lpnamer. | +| `unit_sensitivity` | `unit` | Unit test for sensitivity analysis. | +| `output_writer` | `unit` | Unit test for the output writer. | +| `helpers_test` | `unit` | Unit test for helpers (json reader, AntaresVersionProvider). | +| `full_run_tests` | `unit` | Unit tests for the full run executable | +| `lpnamer_end_to_end` | `lpnamer` `end_to_end` | End-to-end tests for lpnamer. | +| `examples_short_sequential` | `short` `short_sequential` `end_to_end` | Non-parallel end-to-end tests using benders algorithm on antares studies (short duration). | +| `examples_short_mpi` | `short` `short_mpi` `end_to_end` | Parallel end-to-end tests using benders algorithm on antares studies (short duration). | +| `examples_short_benders_by_batch_mpi` | `short` `short_mpi` `end_to_end` `benders_by_batch` | Parallel end-to-end tests using benders by batch algorithm on antares studies (short duration). | +| `examples_medium_sequential` | `medium` `medium_sequential` `end_to_end` | Non-parallel end-to-end tests using benders algorithm on antares studies (medium duration). | +| `examples_medium_mpi` | `medium` `medium_mpi` `end_to_end` | Parallel end-to-end tests using benders algorithm on antares studies (medium duration). | +| `examples_medium_benders_by_batch_mpi` | `medium` `medium_mpi` `end_to_end` `benders_by_batch` | Parallel end-to-end tests using benders by batch algorithm on antares studies (medium duration). | +| `examples_long_sequential` | `long` `long_sequential` `end_to_end` | Non-parallel end-to-end tests using benders algorithm on antares studies (long duration). | +| `examples_long_mpi` | `long` `long_mpi` `end_to_end` | Parallel end-to-end tests using benders algorithm on antares studies (long duration). | +| `mpibenders` | `benders`, `benders-mpi` `end_to_end` | End-to-end tests for benders mpi optimization. | +| `sequential` | `benders` `benders-sequential` `end_to_end` | End-to-end tests for benders sequential optimization. | +| `merge_mps` | `benders` `merge-mps` `end_to_end` | End-to-end tests for merge mps optimization. | !!! Note Use `ctest -N` to see all available tests. diff --git a/docs/user-guide/get-started/installation.md b/docs/user-guide/get-started/installation.md index 72a59f5ab..9f81f2236 100644 --- a/docs/user-guide/get-started/installation.md +++ b/docs/user-guide/get-started/installation.md @@ -28,12 +28,12 @@ antares-xpansion-launcher.exe -i examples\SmallTestFiveCandidates See [Launch the optimization](launching-optimization.md) for more details on how to launch the software. -[ubuntu_system_svg]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/ubuntu-release.yml/badge.svg?query=branch%3Adevelop -[ubuntu_system_link]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/ubuntu-release.yml?query=branch%3Adevelop -[windows_vcpkg_svg]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/windows-vcpkg.yml/badge.svg?query=branch%3Adevelop -[windows_vcpkg_link]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/windows-vcpkg.yml?query=branch%3Adevelop -[centos_system_svg]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/centos-release.yml/badge.svg?query=branch%3Adevelop -[centos_system_link]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/centos-release.yml?query=branch%3Adevelop -[oracle_svg]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/ol8-release.yml/badge.svg?query=branch%3Adevelop -[oracle_link]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/ol8-release.yml?query=branch%3Adevelop +[ubuntu_system_svg]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/build_ubuntu.yml/badge.svg?query=branch%3Adevelop +[ubuntu_system_link]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/build_ubuntu.yml?query=branch%3Adevelop +[windows_vcpkg_svg]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/build_windows.yml/badge.svg?query=branch%3Adevelop +[windows_vcpkg_link]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/build_windows.yml?query=branch%3Adevelop +[centos_system_svg]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/build_centos7.yml/badge.svg?query=branch%3Adevelop +[centos_system_link]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/build_centos7.yml?query=branch%3Adevelop +[oracle_svg]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/build_oracle8.yml/badge.svg?query=branch%3Adevelop +[oracle_link]: https://github.com/AntaresSimulatorTeam/antares-xpansion/actions/workflows/build_oracle8.yml?query=branch%3Adevelop [antares_xpansion_release_url]: https://github.com/AntaresSimulatorTeam/antares-xpansion/releases \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 5deebaebc..e6f326749 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -94,4 +94,4 @@ markdown_extensions: - pymdownx.tabbed - footnotes -copyright: Copyright © 2007 - 2023 RTE \ No newline at end of file +copyright: Copyright © 2007 - 2024 RTE \ No newline at end of file