|
|
[[_TOC_]]
|
|
|
|
|
|
## Requirements
|
|
|
# Requirements
|
|
|
|
|
|
FargOCA installation rely on some tools and libraries. Some are mandatory:
|
|
|
* **Git**: you will need [git](https://git-scm.com/) to retrieve the code, you will need [git-lfs](https://git-lfs.github.com/) installed to run the tests and do any development work.
|
... | ... | @@ -13,13 +13,13 @@ Some are (Strongly) Recommended: |
|
|
* * **MPI**: searched by default. Any conforming MPI2 implementations should do -- Intel MPI 2017.4 and OpenMPI have been tested. If you do not have an MPI implementation or do not want to use it, you can choose to build a [sequential version](#mpi-vs-sequential-version) only.
|
|
|
* **Python**: a [Python 3.6+](https://www.python.org) with [numpy](http://www.numpy.org) and [h5py](http://www.h5py.org/) is used for post-processing scripts.
|
|
|
|
|
|
## Getting the code
|
|
|
# Getting the code
|
|
|
|
|
|
#### The current release
|
|
|
### The current release
|
|
|
|
|
|
Not available yet.
|
|
|
|
|
|
#### The current development version
|
|
|
### The current development version
|
|
|
|
|
|
A [git](https://git-scm.com) client with [git-lfs](https://git-lfs.github.com/) enabled is required. It's probably already there.
|
|
|
|
... | ... | @@ -45,9 +45,9 @@ $ git submodule update --init |
|
|
$
|
|
|
```
|
|
|
|
|
|
## Configuration
|
|
|
# Configuration
|
|
|
|
|
|
### Build directory
|
|
|
## Build directory
|
|
|
You cannot build directly in the source code directory. Here, we assume you want to build in the `build` directory, inside the distribution directory[^1]:
|
|
|
|
|
|
```
|
... | ... | @@ -58,7 +58,7 @@ You cannot build directly in the source code directory. Here, we assume you want |
|
|
[...build]$
|
|
|
```
|
|
|
|
|
|
### Running cmake
|
|
|
## Running cmake
|
|
|
|
|
|
If all the required libraries are available in standard locations, you only need to run `cmake ..` (or, in its general form `cmake <fargOCA distrib path>`:
|
|
|
|
... | ... | @@ -76,14 +76,14 @@ If all the required libraries are available in standard locations, you only need |
|
|
[alainm@pollux build]$
|
|
|
```
|
|
|
|
|
|
### MPI vs sequential version
|
|
|
## MPI vs sequential version
|
|
|
|
|
|
If you do not have MPI, or do not want to use it, you need to set the **FARGO_SEQUENTIAL_ONLY** flag
|
|
|
```
|
|
|
[alainm@pollux build]$ cmake -DFARGO_SEQUENTIAL_ONLY=ON ... <srcpath>
|
|
|
```
|
|
|
|
|
|
### Enabling the Symba7 integrator
|
|
|
## Enabling the Symba7 integrator
|
|
|
|
|
|
The *Symba7 integrator* can be used to control the evolution of the planets. It is not shipped with our distribution but can be used as a plugin. A reference paper about this integrator is:
|
|
|
[Levison and Duncan 2000](https://iopscience.iop.org/article/10.1086/301553/pdf)
|
... | ... | @@ -98,7 +98,7 @@ To enable it, you need to obtain a copy of the [symba7.tar](uploads/c86d3df52d18 |
|
|
Note that you will need to have access to *https://www.boulder.swri.edu/~hal/downloads/swift.tar.gz* from your build machine.
|
|
|
|
|
|
|
|
|
### Troubleshooting
|
|
|
## Troubleshooting
|
|
|
|
|
|
Sometime libraries are not installed in default location. In that case you need to tell cmake where to find them through configuration variable:
|
|
|
```
|
... | ... | @@ -112,12 +112,12 @@ As an example, if the C and C++ compilers are not the defaults ones (or if the e |
|
|
[alainm@pollux build]$
|
|
|
```
|
|
|
|
|
|
##### Libraries
|
|
|
#### Libraries
|
|
|
|
|
|
* **BOOST_ROOT** the root of the Boost installation (can be specified through environment variable)
|
|
|
* **HDF5_ROOT** the root of the HDF5 installation (can be specified through environment variable)
|
|
|
|
|
|
##### MPI
|
|
|
#### MPI
|
|
|
|
|
|
MPI installations can be quite exotic, especially on HPC cluster. If your installation is not automatically detected, you can try setting those variables:
|
|
|
* **MPI_C_COMPILER** the name/path of the C MPI wrapper, common names includes mpicc, mpiicc, mpiC.... If that does not work
|
... | ... | @@ -129,25 +129,25 @@ These are just provided as troubleshooting hints, please refer to your cmake doc |
|
|
|
|
|
It is also possible to [disable MPI](Developer's-corner/Distributed-vs-single-process).
|
|
|
|
|
|
##### Shared Memory Parallelism
|
|
|
#### Shared Memory Parallelism
|
|
|
Shared memory parallelism is achieved through [Kokkos](https://kokkos.org/) which is provided as a sub module.
|
|
|
###### OpenMP
|
|
|
###### CUDA
|
|
|
##### OpenMP
|
|
|
##### CUDA
|
|
|
|
|
|
https://arnon.dk/matching-sm-architectures-arch-and-gencode-for-various-nvidia-cards/
|
|
|
|
|
|
##### Python Bindings
|
|
|
#### Python Bindings
|
|
|
|
|
|
We provide Python binding to FargOCA object model trough [pybind11](https://pybind11.readthedocs.io/en/stable/index.html) and [pykokkos-base](https://github.com/kokkos/pykokkos-base). Both packages are provided as sub-modules.
|
|
|
|
|
|
###### Environment detection
|
|
|
##### Environment detection
|
|
|
|
|
|
We provide (experimental) python binding that requires the [detection the the python development environment](https://cmake.org/cmake/help/v3.0/module/FindPythonLibs.html).
|
|
|
```
|
|
|
$ cmake -DPYTHON_INCLUDE_DIR=<directory containing the python.h header> -DPYTHON_LIBRARY=<complete python library path> [...] <srcdir>
|
|
|
```
|
|
|
|
|
|
###### Weird LTO issue
|
|
|
##### Weird LTO issue
|
|
|
|
|
|
In some configuration (when gpu activation is accelerated as far as we can tell), different part of the python binding code are compiled with incompatible flags. The symptom is the following trace during the link phase
|
|
|
```
|
... | ... | @@ -159,12 +159,11 @@ tmp/ccaFaZFz.s: Assembler messages: |
|
|
|
|
|
To fix it, just disable LTO (Link Time Optimization) by setting the cmake configuration variable **ENABLE_THIN_LTO** to **Off** (```-DENABLE_THIN_LTO=Off```).
|
|
|
|
|
|
|
|
|
###### Disabling Python bindings
|
|
|
##### Disabling Python bindings
|
|
|
|
|
|
If building the Python bindings is more trouble than its worth, they can be disabled by setting **FARGO_NO_PYTHON** to **On** (```cmake -DFARGO_NO_PYTHON=On ...```),
|
|
|
|
|
|
## Compilation
|
|
|
# Compilation
|
|
|
From the build directory
|
|
|
```
|
|
|
[alainm@pollux build]$ make
|
... | ... | @@ -174,7 +173,7 @@ Now that the makefile system generated by `cmake` supports parallel build: |
|
|
[alainm@pollux build]$ make -j<nb core>
|
|
|
```
|
|
|
|
|
|
## Testing
|
|
|
# Testing
|
|
|
|
|
|
You need to have [Git LFS](https://docs.gitlab.com/ee/workflow/lfs/manage_large_binaries_with_git_lfs.html#using-git-lfs) enabled on your git client in order to retrieve the test data.
|
|
|
|
... | ... | @@ -187,7 +186,7 @@ $ |
|
|
|
|
|
It can take some time. Some script have been developed to speed up things on some clusters, see [Machine Specific Stuff](Building#machine-specific-stuff) section.
|
|
|
|
|
|
## [Machine specific stuff](User's-Guide/Installation/Machine specific stuff)
|
|
|
# [Machine specific stuff](User's-Guide/Installation/Machine specific stuff)
|
|
|
|
|
|
Tricks and cheat list for specific clusters.
|
|
|
|
... | ... | |