Installation

Shenfun has a few dependencies

that are mostly straight-forward to install, or already installed in most Python environments. The first two are usually most troublesome. Basically, for mpi4py you need to have a working MPI installation, whereas FFTW is available on most high performance computer systems. If you are using conda, then all you need to install a fully functional shenfun, with all the above dependencies, is

conda install -c conda-forge shenfun

You probably want to install into a fresh environment, though, which can be achieved with

conda create --name shenfun -c conda-forge shenfun
conda activate shenfun

Note that this gives you shenfun with default settings. This means that you will probably get the openmpi backend, and it is also likely that conda-forge chooses numpy with the mkl backend. Unfortunately, the mkl python package makes adjustments to the FFTW library and hard to resolve bugs may arise. For this reason it is advisable to make sure that mkl is not installed. This can be achieved with, e.g.,

conda create --name shenfun -c conda-forge shenfun mpich nomkl

Note that the nomkl package makes sure that numpy is installed without mkl, whereas mpich here chooses this backend over openmpi.

If you do not use conda, then you need to make sure that MPI and FFTW are installed by some other means. You can then install any version of shenfun hosted on pypi using pip

pip install shenfun

whereas the following will install the latest version from github

pip install git+https://github.com/spectralDNS/shenfun.git@master

You can also build shenfun yourselves from the top directory, after cloning or forking

pip install .

or using conda-build with the recipes in folder conf/conda

conda build -c conda-forge -c spectralDNS conf/conda
conda create --name shenfun -c conda-forge -c spectralDNS shenfun --use-local
conda activate shenfun

Optimization

Shenfun contains a few routines (essentially linear algebra solvers and matrix vector products) that are difficult to vectorize with numpy, and for this reason they have been implemented in either (or both of) Numba or Cython. The user may choose which implementation to use through the environment variable SHENFUN_OPTIMIZATION. The default is to use cython, but it is possible to enable either one by making the appropriate choice in the active terminal

export SHENFUN_OPTIMIZATION={CYTHON,NUMBA}

Additional dependencies

For storing and retrieving data you need either HDF5 or netCDF4, compiled with support for MPI (see Post processing). HDF5 is already available with parallel support on conda-forge and, if it was not installed at the same time as shenfun, it can be installed (with the mpich backend for MPI) as

conda install -c conda-forge h5py=*=mpi_mpich_*

A parallel version of netCDF4 cannot be found on the conda-forge channel, but a precompiled version has been made available for python 2.7, 3.6 and 3.7 on the spectralDNS channel, for both osx and linux

conda install -c spectralDNS netcdf4-parallel

Note that parallel HDF5 and NetCDF4 often are available as modules on supercomputers. Otherwise, see the respective packages for how to install with support for MPI.

Test installation

After installing (from source) it may be a good idea to run all the tests located in the tests folder. The tests are run with pytest from the main directory of the source code

python -m pytest tests/

However, note that for conda you need to install pytest into the correct environment as well. A common mistake is to run a version of pytest that has already been installed in a different conda environment, perhaps using a different Python version.

The tests are run automatically on every commit to github, see

https://travis-ci.org/spectralDNS/shenfun.svg?branch=master https://circleci.com/gh/spectralDNS/shenfun.svg?style=svg