Doc: convert all doc/*.rst files to .md

doc/faq.md

@@ -2,44 +2,56 @@
 
 ## Applications: Can I use FluidSim for
 
-:::\{admonition} Wall bounded / multiphase / reactive flows ...? Maybe. The
-built-in {mod}`solvers <fluidsim.solvers>` excels solving within periodic domains
-with pseudospectral solvers. However, FluidSim is a framework, and this allows
-FluidSim to interface with third-party solvers. See for instance
-{mod}`fluidsim.base.basilisk`, {mod}`fluidsim.base.dedalus` and
-[snek5000](https://snek5000.readthedocs.io). :::
+:::{admonition} Wall bounded / multiphase / reactive flows ...?
+
+Maybe. The built-in {mod}`solvers <fluidsim.solvers>` excels solving within
+periodic domains with pseudospectral solvers. However, FluidSim is a framework,
+and this allows FluidSim to interface with third-party solvers. See for
+instance {mod}`fluidsim.base.basilisk`, {mod}`fluidsim.base.dedalus` and
+[snek5000](https://snek5000.readthedocs.io).
+
+:::
 
 ## Troubleshooting installation issues
 
 Make sure you read the [installation guide](install) carefully.
 
-:::\{admonition} Permission denied while running `pip install fluidsim` from PyPI
+:::{admonition} Permission denied while running `pip install fluidsim` from PyPI
+
 or `make develop` inside the repository. This means you are probably using the
 Python bundled with the system and as a user you are restricted from installing
-packages into it. If this is so, create a [virtual environment]. :::
+packages into it. If this is so, create a [virtual environment].
+
+:::
+
+:::{admonition} *No module named pip* or `distutils.errors.DistutilsError`
 
-:::\{admonition} *No module named pip* or `distutils.errors.DistutilsError`
 Package manager `pip` was not installed into your environment or is too old. The
 following commands should help:
 
-```
+```sh
 python -m ensurepip
 python -m pip install --upgrade pip setuptools wheel
 ```
 
 :::
 
-:::\{admonition} System freezes or becomes unresponsive as fluidsim starts to
-build extensions By default `pythran` extensions try to use `gcc` and this is a
+:::{admonition} System freezes or becomes unresponsive as fluidsim starts to build extensions
+
+By default `pythran` extensions try to use `gcc` and this is a
 CPU and memory intensive compilation. Instead `pythran` can be configured to use
 `clang`. See {ref}`pythranrc` for more details.
 
 Additionally to reduce the load during installation is to configure certain
-{ref}`build specific environment variables <env_vars>`. :::
+{ref}`build specific environment variables <env-vars>`.
+:::
+
+:::{admonition} `ModuleNotFoundError: No module named 'fluidsim_core. ...`
 
-:::\{admonition} `ModuleNotFoundError: No module named 'fluidsim_core. ...`
 FluidSim depends on {mod}`fluidsim_core` and both follow the same versioning. Make
 sure the versions match if you had used `pip install` or `conda install`. For
-developers, `make develop` should install both as editable installations. :::
+developers, `make develop` should install both as editable installations.
+
+:::
 
 [virtual environment]: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment

doc/install.md

@@ -0,0 +1,274 @@
+# 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](http://fluiddyn.readthedocs.org/en/latest/install.html).
+
+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:
+
+```sh
+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:
+
+```sh
+conda install fluidsim
+```
+
+For parallel simulations using MPI, let's create a dedicated environment:
+
+```sh
+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:
+
+```sh
+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](http://fluidfft.readthedocs.io) for pseudospectral solvers. Fluidsim
+and fluidfft can be both installed with the command:
+
+```sh
+pip install fluidsim[fft]
+```
+
+Moreover, fluidfft builds can also be tweaked so you could have a look at
+[fluidfft documentation](http://fluidfft.readthedocs.io/en/latest/install.html).
+
+(env-vars)=
+
+## 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`:
+
+```sh
+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 in `fluidfft` (default: `mpicxx`)
+  - `CC`: command to generate object files in `fluidsim`
+  - `LDSHARED`: command to link and generate shared libraries in `fluidsim`
+  - `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:
+
+```sh
+wget https://foss.heptapod.net/fluiddyn/fluidsim/-/raw/branch/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`:
+
+  ```sh
+  export FLUIDSIM_PATH=$HOME/Data
+  ```
+
+- `FLUIDDYN_PATH_SCRATCH`: working directory (can be useful on some clusters).
+
+## 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:
+
+```sh
+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.
+
+(pythranrc)=
+
+## About using Pythran to compile functions
+
+We choose to use the Python compiler
+[Pythran](https://github.com/serge-sans-paille/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](https://pythran.readthedocs.io)):
+
+```bash
+[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:
+
+```bash
+[compiler]
+CXX=clang++
+CC=clang
+```
+
+:::
+
+## MPI simulations and mpi4py!
+
+Fluidsim can use [mpi4py](http://mpi4py.scipy.org) (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:
+
+```sh
+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:
+
+```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](http://docs.h5py.org/en/latest/build.html) 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:
+
+```sh
+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](https://foss.heptapod.net/fluiddyn/fluidsim) in
+Heptapod. Download the source with something like:
+
+```sh
+hg clone https://foss.heptapod.net/fluiddyn/fluidsim
+```
+
+If you are new with Mercurial and Heptapod, you can also read
+[this short tutorial](http://fluiddyn.readthedocs.org/en/latest/mercurial_heptapod.html).
+
+For particular installation setup, copy the default configuration file to
+`site.cfg`:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+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.