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. To make sure that shenfun is is installed with mpich instead do
conda create --name shenfun -c conda-forge shenfun mpich
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
Note that a common approach is to install shenfun from conda-forge to
get all the dependencies, and then build a local version by (after cloning or
forking to a local folder) running from the top directory
pip install .
or
python setup.py build_ext -i
This is required to build all the Cython dependencies locally.
Configuration¶
Shenfun comes with a few configuration options that can be found in the config.py file. If you want to make your own modifications to this configuration, there are two options. Either create a file shenfun.yaml in the local directory where you run your shenfun solver, or put a shenfun.yaml file in the home directory ~/.shenfun/shenfun.yaml. If a configuration file in found in either of these to locations, the settings there will overload the original. The local configuration file will be the last to be read. To generate a baseline configuration file you can run the dumpconfig function
from shenfun.config import dumpconfig
dumpconfig()
This will place a configuration file by default here: ~/.shenfun/shenfun.yaml, that you can then choose to modify. If you want a local file instead, then run dumpconfig(path=’.’). The yaml file looks and works like a dictionary. At the time of writing the configuration looks like
bases:
jacobi:
mode: numpy
basisvectors: normal
fftw:
dct:
planner_effort: FFTW_MEASURE
threads: 1
dlt:
planner_effort: FFTW_MEASURE
threads: 1
dst:
planner_effort: FFTW_MEASURE
threads: 1
fft:
planner_effort: FFTW_MEASURE
threads: 1
ifft:
planner_effort: FFTW_MEASURE
threads: 1
irfft:
planner_effort: FFTW_MEASURE
threads: 1
rfft:
planner_effort: FFTW_MEASURE
threads: 1
matrix:
block:
assemble: csc
permc_spec: COLAMD
use_scipy: true
sparse:
diags: csc
matvec: csr
permc_spec: COLAMD
solve: csc
optimization:
mode: cython
verbose: false
transforms:
kind:
chebyshev: fast
chebyshevu: fast
fourier: fast
hermite: vandermonde
jacobi: recursive
laguerre: vandermonde
legendre: recursive
ultraspherical: recursive
The basisvectors can be used to choose covariant instead of normal basis vectors. The matrix options decide which scipy sparse format to use for the sparse computations that make use of them. The optimization can be either cython or numba, which is used to speed up some routines. The fftw setting allows to tweak the planning or the use of threads for FFTs. The bases configuration for jacobi can set mode to mpmath to enable the use of mpmath for some routines instead of numpy.
Additional dependencies¶
For storing and retrieving data you need either HDF5 or netCDF4, compiled with support for MPI (see Postprocessing). Both HDF5 and netCDF4 are already available with parallel support on conda-forge, and, if they were not installed at the same time as shenfun, they can be installed as
conda install -c conda-forge h5py=*=mpi* netcdf4=*=mpi*
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.
Some of the plots in the Demos are created using the matplotlib library. Matplotlib is not a required dependency, but it may be easily installed from conda using
conda install matplotlib
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
