Skip to content

Commit

Permalink
Update documentation (#902)
Browse files Browse the repository at this point in the history
  • Loading branch information
@JasonMarechal25
JasonMarechal25 authored Aug 22, 2024
1 parent e337e7b commit 393f8f0
Show file tree
Hide file tree
Showing 7 changed files with 100 additions and 143 deletions.
11 changes: 4 additions & 7 deletions docs/developer-guide/install_from_sources/0-INSTALL.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
23 changes: 13 additions & 10 deletions docs/developer-guide/install_from_sources/1-Development-requirements.md
View file
Original file line number Diff line number Diff line change
@@ -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:

Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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.
Expand Down
141 changes: 49 additions & 92 deletions docs/developer-guide/install_from_sources/2-Dependencies-install.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<vcpkg-triplet>` 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 `<vcpkg_root>` later in this document.


3. Install dependencies:
```
cd vcpkg
vcpkg install jsoncpp gtest boost-mpi boost-program-options --triplet <vcpkg-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:
<vcpkg_root>/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 `<antares_xpansion_checkout_dir>/../rte-antares-deps-<build_type>`.

!!! 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:<path_to_vcpkg>/installed/<triplet>/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.
7 changes: 3 additions & 4 deletions docs/developer-guide/install_from_sources/3-Build.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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-<CMAKE_BUILD_TYPE>`|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 |
|:-------|-------|
Expand Down
43 changes: 22 additions & 21 deletions docs/developer-guide/install_from_sources/4-Tests.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading

0 comments on commit 393f8f0

Please sign in to comment.