Installation

Overview

Dedalus is a Python 3 package with custom C-extensions (compiled with Cython) that relies on MPI, FFTW, HDF5, and a scientific Python stack. This guide covers multiple installation methods to suit different environments.

The conda installation is recommended for most users, especially on laptops and workstations. For HPC clusters, you may want to link against existing optimized MPI/FFTW libraries.

System Requirements

Python Requirements

Python: 3.9 or later
Required packages:
- numpy >= 1.20.0
- scipy >= 1.4.0
- mpi4py >= 2.0.0
- h5py >= 3.0.0
- matplotlib >= 3.7.0
- cython, numexpr, docopt, pytest

C Library Dependencies

MPI: Any MPI implementation (OpenMPI, MPICH, Intel MPI, etc.)
FFTW3: Fast Fourier Transform library with MPI support
HDF5: Hierarchical Data Format library
BLAS/LAPACK: For linear algebra operations

For optimal performance, you must disable threading by setting OMP_NUM_THREADS=1 before running Dedalus. This prevents thread conflicts and can improve performance by orders of magnitude.

Installation Methods

Conda (Recommended)
Custom Conda
From PyPI
From Source

Full-Stack Conda Installation

This is the easiest and recommended method for laptops, workstations, and many cluster environments.

Install Conda

If you don’t have conda installed, we recommend miniforge:

# Download and install miniforge
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
bash Miniforge3-Linux-x86_64.sh

Create and Activate Environment

Create a new conda environment for Dedalus:

# Create new environment
conda create -n dedalus3

# Activate the environment
conda activate dedalus3

Configure for Apple Silicon (Mac Only)

Apple Silicon users only: There are currently upstream issues preventing native arm64 support. Use Rosetta emulation:

# Macs with Apple Silicon only!
conda config --env --set subdir osx-64

Disable Threading (Strongly Recommended)

Configure the environment to disable threading for optimal performance:

# Disable threading for maximum performance
conda env config vars set OMP_NUM_THREADS=1
conda env config vars set NUMEXPR_MAX_THREADS=1

Deactivate and reactivate the environment for these changes to take effect.

Install Dedalus

Install Dedalus and all dependencies from conda-forge:

# Install from conda-forge
conda install -c conda-forge dedalus

Test Installation

Verify the installation works correctly:

# Test the installation
python3 -m dedalus test

Custom Conda Installation

Use this method when you want to link against custom MPI/FFTW/HDF5 libraries for better cluster performance.

Install Conda

If you don’t have conda installed, get miniforge.

Download Build Script

Download the custom installation script:

curl https://raw.githubusercontent.com/DedalusProject/dedalus_conda/master/conda_install_dedalus3.sh \
  --output conda_install_dedalus3.sh

Configure Build Options

Edit the script to customize:

Environment name
Custom MPI/FFTW/HDF5 library paths
OpenBLAS vs MKL for numpy/scipy
Threading settings

# Open and edit the script
vim conda_install_dedalus3.sh

Run Build Script

Execute the installation script:

conda activate base
bash conda_install_dedalus3.sh

Test Installation

Verify everything works:

conda activate dedalus3  # or your custom name
python3 -m dedalus test

Installing from PyPI

Install Dedalus from the Python Package Index when you have existing MPI/FFTW installations.

You must have MPI, FFTW3, and HDF5 already installed on your system.

Install Build Dependencies

Install required Python build tools:

pip3 install --upgrade cython numpy setuptools wheel

Set Library Paths

Export environment variables pointing to your MPI and FFTW installations:

export MPI_PATH=/path/to/your/mpi_prefix
export FFTW_PATH=/path/to/your/fftw_prefix

Install Dedalus

Install using pip with mpicc as the compiler:

CC=mpicc pip3 install --no-cache --no-build-isolation dedalus

The --no-build-isolation flag is required to properly link against your MPI libraries.

Building from Source

Build the latest development version from the GitHub repository.

Install Build Dependencies

Ensure you have the necessary tools:

pip3 install --upgrade cython numpy setuptools wheel

Set Library Paths

Export paths to your MPI and FFTW installations:

export MPI_PATH=/path/to/your/mpi_prefix
export FFTW_PATH=/path/to/your/fftw_prefix

Clone Repository

Clone the Dedalus repository:

git clone -b master https://github.com/DedalusProject/dedalus
cd dedalus

Build and Install

Install from source using pip:

CC=mpicc pip3 install --no-cache --no-build-isolation .

Quick install from GitHub without cloning:

CC=mpicc pip3 install --no-cache --no-build-isolation \
  http://github.com/dedalusproject/dedalus/zipball/master/

Verification

After installation, verify that Dedalus is working correctly:

# Run the full test suite
python3 -m dedalus test

Environment Configuration

Performance Settings

For optimal performance, always disable threading:

.bashrc / .bash_profile

# Add to your shell configuration file
export OMP_NUM_THREADS=1
export NUMEXPR_MAX_THREADS=1

Finding Library Paths

If you need to set MPI_PATH or FFTW_PATH:

# Locate MPI installation
which mpicc
# MPI_PATH is typically the parent of bin/mpicc

Updating Dedalus

Conda Installation

If installed via conda, update using:

conda activate dedalus3
conda update -c conda-forge dedalus

Pip Installation

If installed via pip from source:

# Set library paths if needed
export MPI_PATH=/path/to/mpi
export FFTW_PATH=/path/to/fftw

# Update from GitHub
CC=mpicc pip3 install --upgrade --force-reinstall --no-deps --no-cache \
  --no-build-isolation http://github.com/dedalusproject/dedalus/zipball/master/

Local Repository

If installed from a cloned repository:

cd /path/to/dedalus/repo
git pull
CC=mpicc pip3 install --upgrade --force-reinstall --no-deps \
  --no-cache --no-build-isolation .

Common Installation Issues

MPI compiler not found

Problem: CC=mpicc fails with “command not found”Solution:

Ensure MPI is installed: which mpicc
Load MPI module on clusters: module load openmpi
Install MPI via conda: conda install -c conda-forge openmpi

FFTW libraries not found

Problem: Build fails with “cannot find -lfftw3”Solution:

Set FFTW_PATH: export FFTW_PATH=/path/to/fftw
Install FFTW: conda install -c conda-forge fftw
Check library location: locate libfftw3.so

Slow performance

Problem: Dedalus runs much slower than expectedSolution:

Check threading: echo $OMP_NUM_THREADS (should be 1)
Disable threading: export OMP_NUM_THREADS=1
Verify MPI is actually being used: mpiexec -n 2 python3 script.py

Import errors

Problem: ImportError: cannot import name ...Solution:

Verify Python version: python3 --version (need 3.9+)
Check package versions: pip3 list | grep -E 'numpy|scipy|mpi4py|h5py'
Reinstall with proper isolation flags

Apple Silicon issues

Problem: Crashes or errors on M1/M2 MacsSolution:

Use x86 architecture: conda config --env --set subdir osx-64
Install Rosetta 2 if not already installed
Recreate the environment with the correct architecture

Uninstalling

To remove Dedalus:

# Remove the package
pip3 uninstall dedalus

# Or remove entire conda environment
conda env remove -n dedalus3

Get Started

Core Concepts

Advanced Topics

Examples

Overview

System Requirements

Python Requirements

C Library Dependencies

Installation Methods

Full-Stack Conda Installation

Custom Conda Installation

Installing from PyPI

Building from Source

Verification

Environment Configuration

Performance Settings

Finding Library Paths

Updating Dedalus

Conda Installation

Pip Installation

Local Repository

Common Installation Issues

Uninstalling

Next Steps

Quick Start Tutorial

Back to Introduction

Build docs developers (and LLMs) love

Get Started

Core Concepts

Advanced Topics

Examples

​Overview

​System Requirements

​Python Requirements

​C Library Dependencies

​Installation Methods

​Full-Stack Conda Installation

​Custom Conda Installation

​Installing from PyPI

​Building from Source

​Verification

​Environment Configuration

​Performance Settings

​Finding Library Paths

​Updating Dedalus

​Conda Installation

​Pip Installation

​Local Repository

​Common Installation Issues

​Uninstalling

​Next Steps

Quick Start Tutorial

Back to Introduction

Build docs developers (and LLMs) love

Overview

System Requirements

Python Requirements

C Library Dependencies

Installation Methods

Full-Stack Conda Installation

Custom Conda Installation

Installing from PyPI

Building from Source

Verification

Environment Configuration

Performance Settings

Finding Library Paths

Updating Dedalus

Conda Installation

Pip Installation

Local Repository

Common Installation Issues

Uninstalling

Next Steps