Installing Dedalus

Dedalus is a Python 3 package that includes custom C-extensions (compiled with Cython) and that relies on MPI, FFTW (linked to MPI), HDF5, and a basic scientific-Python stack: numpy, scipy, mpi4py (linked to the same MPI), and h5py.

We recommend using conda to build a Python environment with all the necessary prerequisites, as described in the conda instructions below. This procedure can be easily customized to link to existing MPI/FFTW/HDF5 libraries, which may be preferable when installing Dedalus on a cluster.

Once you have the necessary C dependencies (MPI, FFTW+MPI, and HDF5), as well as Python 3, you should be able to install Dedalus from PyPI or build it from source.

Installing the Dedalus package

Once the necessary C dependencies and Python 3 are present, Dedalus can be installed from PyPI or built from source using pip.

Note: the instructions in this section assume the pip3 command is hitting the right Python 3 installation. You can check this by making sure that which pip3 and which python3 reside in the same location. If not, you may need to use pip or python3 -m pip instead of pip3 in the following commands.

Installing from PyPI

We currently only provide Dedalus on PyPI as a source distribution so that the Cython extensions are properly linked to your FFTW/MPI libraries at build-time. To install Dedalus from PyPI, first set the FFTW_PATH and MPI_PATH environment variables to the prefix paths for FFTW/MPI and then install using pip:

export FFTW_PATH=/path/to/your/fftw_prefix
export MPI_PATH=/path/to/your/mpi_prefix
pip3 install dedalus

Building from source

Alternately, to build the lastest version of Dedalus from source: clone the repository, set FFTW/MPI paths, and install using pip:

git clone https://github.com/DedalusProject/dedalus
cd dedalus
export FFTW_PATH=/path/to/your/fftw_prefix
export MPI_PATH=/path/to/your/mpi_prefix

pip3 install .

Updating Dedalus

If Dedalus was installed using the conda script or manually from PyPI, it can be updated pip:

pip3 install --upgrade dedalus

Note: any custom FFTW/MPI paths set in the conda script or during the original installation will also need to be exported for the update command to work.

If Dedalus was built from source, it can be updated by first pulling new changes from the source repository, and then reinstalling with pip:

cd /path/to/dedalus/repo
git pull
export FFTW_PATH=/path/to/your/fftw_prefix
export MPI_PATH=/path/to/your/mpi_prefix
pip3 install --upgrade --force-reinstall .

Uninstalling Dedalus

If Dedalus was installed using pip, it can be uninstalled using:

pip3 uninstall dedalus

Alternative installation procedures

Note: We recommend installing Dedalus using conda, as described above. These alternative procedures may be out-of-date and are provided for historical reference and expert use.

Installation script

This all-in-one installation script will build an isolated stack containing a Python installation and the other dependencies needed to run Dedalus. In most cases, the script can be modified to link with system installations of FFTW, MPI, and linear algebra libraries.

You can get the installation script from this link, or download it using:

wget https://raw.githubusercontent.com/DedalusProject/dedalus/master/docs/install.sh

and execute it using:

bash install.sh

The installation script has been tested on a number of Linux distributions and OS X. If you run into trouble using the script, please get in touch on the user list.