Installation
FluidSim is part of the FluidDyn project and requires Python >= 3.6. Some issues regarding the installation of Python and Python packages are discussed in the main documentation of the project.
We don’t upload wheels on PyPI, so the simplest and fastest procedure is to
use conda
(no compilation needed). Alternatively, one can compile fluidsim
and fluidfft using pip
.
Installing the conda-forge packages with conda or mamba
The fluidsim packages are in the conda-forge channels, so if it is not already done, one needs to add it:
conda config --add channels conda-forge
If you just want to run sequential simulations and/or analyze the results of simulations, you can just install the fluidsim package:
conda install fluidsim
For parallel simulations using MPI, let’s create a dedicated environment:
conda create -n env_fluidsim ipython fluidsim "fluidfft[build=mpi*]" "h5py[build=mpi*]"
The environment can then be activated with conda activate env_fluidsim
.
Build/install using pip
We recommend installing with a recent version of pip so you might want to
run pip install pip -U
before anything (if you use conda, conda update
pip
). Then, fluidsim can be installed with:
pip install fluidsim
However, one have to note that (i) fluidsim builds are sensible to environment variables (see below) and (ii) fluidsim can optionally use fluidfft for pseudospectral solvers. Fluidsim and fluidfft can be both installed with the command:
pip install fluidsim[fft]
Moreover, fluidfft builds can also be tweaked so you could have a look at fluidfft documentation.
Environment variables and build configuration
Build time configuration
FLUIDDYN_NUM_PROCS_BUILD
Fluidsim binaries are builds in parallel. This speedups the build process a lot
on most computers. However, it can be a very bad idea on computers with not
enough memory. If you encounter problems, you can force the number of processes
used during the build using the environment variable
FLUIDDYN_NUM_PROCS_BUILD
:
export FLUIDDYN_NUM_PROCS_BUILD=2
Customize compilers to build extensions, if the defaults do not work for you, either using the environment variables:
MPICXX
: for Cython extensions influidfft
(default:mpicxx
)CC
: command to generate object files influidsim
LDSHARED
: command to link and generate shared libraries influidsim
CARCH
: to cross compile (default:native
)
DISABLE_PYTHRAN
disables compilation with Pythran at build time.FLUIDSIM_TRANSONIC_BACKEND
“pythran” by default, it can be set to “python”, “numba” or “cython”.
You can also configure the installation of fluidsim by creating the file
~/.fluidsim-site.cfg
(or site.cfg
in the repo directory) and modify it
to fit your requirements before the installation with pip:
wget https://foss.heptapod.net/fluiddyn/fluidsim/raw/default/site.cfg.default -O ~/.fluidsim-site.cfg
Runtime configuration
Fluidsim is also sensitive to the environment variables:
FLUIDSIM_PATH
: path where the simulation results are saved.In Unix systems, you can for example put this line in your
~/.bashrc
:export FLUIDSIM_PATH=$HOME/Data
FLUIDDYN_PATH_SCRATCH
: working directory (can be useful on some clusters).TRANSONIC_COMPILE_JIT
: set this variable to force JIT compilation usingtransonic
while running tests. This is not necessary, but could be useful for troubleshooting if simulations freeze. For example:TRANSONIC_COMPILE_JIT=1 fluidsim-test -m fluidsim.solvers.sw1l
Warning about re-installing fluidsim and fluidfft with new build options
If fluidsim has already been installed and you want to recompile with new configuration values, you need to really recompile fluidsim and not just reinstall an already produced wheel. To do this, use:
pip install fluidsim --no-binary fluidsim -v
-v
toggles the verbose mode of pip so that we see the compilation log and
can check that everything goes well.
About using Pythran to compile functions
We choose to use the Python compiler Pythran for some functions of the operators. Our microbenchmarks show that the performances are as good as what we are able to get with Fortran or C++!
But it implies that building Fluidsim requires a C++11 compiler (for example GCC 4.9 or clang).
Note
If you don’t want to use Pythran and C++ to speedup Fluidsim, you can use the
environment variable DISABLE_PYTHRAN
.
Warning
To reach good performance, we advice to try to put in the file
~/.pythranrc
the lines (it seems to work well on Linux, see the Pythran
documentation):
[pythran]
complex_hook = True
Warning
The compilation of C++ files produced by Pythran can be long and can consume
a lot of memory. If you encounter any problems, you can try to use clang (for
example with conda install clangdev
) and to enable its use in the file
~/.pythranrc
with:
[compiler]
CXX=clang++
CC=clang
MPI simulations and mpi4py!
Fluidsim can use mpi4py (which depends on a MPI implementation) for MPI simulations.
Warning
If the system has multiple MPI libraries, it is adviced to explicitly mention the MPI command. For instance to use Intel MPI:
CC=mpiicc pip install mpi4py --no-binary mpi4py
About h5py and HDF5_MPI
FluidSim is able to use h5py built with MPI support.
Warning
Prebuilt installations (for e.g. via h5py wheels) lacks MPI support. Most of the time, this is what you want. However, you can install h5py from source and link it to a hdf5 built with MPI support, as follows:
$ CC="mpicc" HDF5_MPI="ON" HDF5_DIR=/path/to/parallel-hdf5 pip install --no-deps --no-binary=h5py h5py
$ python -c 'import h5py; h5py.run_tests()'
In some cases you need to set C_INCLUDE_PATH variable before h5py installation. For example on Debian stretch:
$ export C_INCLUDE_PATH=/usr/include/openmpi/
$ CC="mpicc" HDF5_MPI="ON" HDF5_DIR=/path/to/parallel-hdf5 pip install --no-deps --no-binary=h5py h5py
See the h5py documentation for more details.
Installing from the repository
Note
A good base to install Fluidsim from source can be to create and activate a conda environment with:
conda create -y -n env-fluidsim -c conda-forge "fluidfft=*=*openmpi*" pythran clangdev mako
conda activate env-fluidsim
For fluidsim, we use the revision control software Mercurial and the main repository is hosted here in Heptapod. Download the source with something like:
hg clone https://foss.heptapod.net/fluiddyn/fluidsim
If you are new with Mercurial and Heptapod, you can also read this short tutorial.
For particular installation setup, copy the default configuration file to
site.cfg
:
cp site.cfg.default site.cfg
and modify it to fit your requirements.
Build/install in development mode, by running from the top-level directory:
cd lib && pip install -e .; cd ..
pip install -e .
Note
To install from source in a conda environment, it is actually necessary to
disable the isolated build by running the command pip install -e .
--no-build-isolation
.
To install Fluidsim with all optional dependencies and all capacities:
pip install -e .[full]
Run the tests!
You can run some unit tests by running make tests
(shortcut for
fluidsim-test -v
) or make tests_mpi
(shortcut for mpirun -np 2
fluidsim-test -v
). Alternatively, you can also run pytest
from the root
directory or from any of the source directories.