First, ensure that you have a recent Python installed, since Fluidsim requires Python >= 3.9. Some issues regarding the installation of Python and Python packages are discussed in the main documentation of the project.
We strongly advice to install Fluidsim in a virtual environment. See the
official guide [Install packages in a virtual environment using pip and
venv](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/).
Fluidsim can be installed without compilation with pip
:
pip install pip -U
pip install fluidsim
However, fluidsim requires fluidfft for pseudospectral solvers. Fluidsim, fluidfft and pyfftw can be both installed without compilation with the command:
pip install "fluidsim[fft]"
Fluidsim has 3 sets of optional dependencies, which can be installed with commands
like pip install "fluidsim[fft]"
or pip install "fluidsim[fft,mpi]"
:
-
fft
: mainly for pseudo spectral solvers using the Fourier basis. -
mpi
: for parallel computing using MPI.Installations with MPI support with pip (`pip install fluidsim[mpi]`) trigger local compilation of at least [mpi4py].
-
test
: for testing Fluidsim (can be done without the repository).
Fluidfft works with pluggins to compute FFTs with different methods (see the fluidfft documentation). For example, to install Fluidfft plugins using the FFTW library, one can run (but it will trigger compilation):
-
For sequential simulations:
pip install "fluidsim[test,fft]" "fluidfft[fftw]"
-
For parallel simulations using MPI:
pip install "fluidsim[test,fft]" "fluidfft[fftw,fftwmpi,mpi-with-fftw]"
One can run Fluidsim test suite with
pytest --pyargs fluidsim
or for parallel simulations
mpirun -np 2 pytest --pyargs fluidsim -vx
We recommend installing conda
and mamba
(using the conda-forge channel) with
the miniforge installer.
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 fluidsim "h5py[build=mpi*]" \
fluidfft-mpi_with_fftw fluidfft-fftwmpi
The environment can then be activated with conda activate env-fluidsim
.
To be able to run Fluidsim test suite in conda environments, one has to install
manually few pytest extensions with
```sh
pip install pytest-allclose pytest-mock
```
Other more exotic methods can also be used. In particular, we have examples for:
Fluidsim is sensitive to 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_fluidsim
-
FLUIDDYN_PATH_SCRATCH
: working directory (can be useful on some clusters).
Fluidsim uses Fluidfft to compute Fourier transforms. Have a look at the fluidfft documentation.
Fluidsim can use mpi4py (which depends on a MPI implementation) for parallel simulations.
If the system has multiple MPI libraries, it is advised to explicitly mention the
MPI command. For instance to use Intel MPI:
```sh
CC=mpiicc pip install mpi4py --no-binary mpi4py
```
FluidSim is able to use h5py built with MPI support.
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:
```bash
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:
```bash
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](https://docs.h5py.org/en/latest/build.html) for more
details.