Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DedalusProject/dedalus_conda/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The conda_install_dedalus2.sh script automates the installation of Dedalus v2, a spectral PDE solver framework, using conda package management. The script creates an isolated conda environment with all necessary dependencies including MPI, FFTW, HDF5, and scientific Python libraries.

​
What It Does

The script performs the following operations:
  1. Validates that the conda base environment is active
  2. Checks configuration requirements (custom library paths if not using conda packages)
  3. Creates or updates a conda environment (default: dedalus2)
  4. Configures conda-forge as the primary package channel
  5. Installs Python and build tools (pip, wheel, setuptools, cython)
  6. Installs BLAS libraries (OpenBLAS or MKL) with numpy and scipy
  7. Installs MPI implementation (OpenMPI from conda or custom)
  8. Installs FFTW library (from conda or custom)
  9. Installs HDF5 and h5py (with parallel support if using MPI)
  10. Installs additional dependencies (docopt, matplotlib)
  11. Installs Dedalus v2 from PyPI via pip
  12. Configures threading environment variables

​
Prerequisites

1

Install Conda

Install Miniconda or Anaconda distribution. Download from:
2

Activate Base Environment

The script must be run with the conda base environment active:
conda activate base
3

Custom Libraries (Optional)

If using custom MPI, FFTW, or HDF5 installations instead of conda packages, ensure these libraries are properly installed and accessible on your system.
The script requires the conda base environment to be active. It will exit with an error if run from any other environment.

​
Usage

​
Basic Installation

For a standard installation with all dependencies from conda: 
# Download the script
wget https://raw.githubusercontent.com/DedalusProject/dedalus/master/conda_install_dedalus2.sh

# Make it executable
chmod +x conda_install_dedalus2.sh

# Activate conda base environment
conda activate base

# Run the script
./conda_install_dedalus2.sh

​
Custom Configuration

Edit the script before running to customize the installation: 
# Modify at the top of the script
CONDA_ENV="my_dedalus_env"

​
Configuration Options

See the Script Options page for detailed documentation of all configurable parameters.

​
Key Options Summary

  • CONDA_ENV: Name of the conda environment (default: dedalus2)
  • INSTALL_MPI: Install OpenMPI from conda (1) or use custom (0)
  • INSTALL_FFTW: Install FFTW from conda (1) or use custom (0)
  • INSTALL_HDF5: Install HDF5 from conda (1) or use custom (0)
  • BLAS: BLAS library choice: openblas or mkl
  • PYTHON_VERSION: Python version to install (default: 3.12)
  • APPLE_SILICON_BUILD_ARM: Native arm64 on Apple Silicon (default: 0)

​
Platform-Specific Behavior

​
Apple Silicon (M1/M2/M3)

By default, the script installs x86_64 packages via Rosetta 2 emulation on Apple Silicon Macs: 
# Default behavior on Apple Silicon
APPLE_SILICON_BUILD_ARM=0  # Uses osx-64 architecture
This provides better compatibility with scientific computing libraries. To use native arm64 builds: 
APPLE_SILICON_BUILD_ARM=1  # Uses osx-arm64 architecture
Native arm64 builds may exhibit numerical errors with certain OpenBLAS versions. The script automatically pins libopenblas<0.3.20 when using arm64 builds to avoid known issues with the ggev function.

​
Linux

On Linux systems, the script uses the native architecture (typically linux-64).

​
Installation Flow

1

Environment Setup

The script sources conda configuration and sets Python environment variables:
  • PYTHONNOUSERSITE=1: Prevents conda from looking in ~/.local
  • Unsets PYTHONPATH: Ensures clean environment
2

Environment Creation

Creates a new conda environment or warns if it already exists. On Apple Silicon with APPLE_SILICON_BUILD_ARM=0, sets the environment to use osx-64 packages.
3

Channel Configuration

Adds conda-forge as a channel and sets strict channel priority to ensure consistent package sources.
4

Base Python Stack

Installs Python with essential build tools (pip, wheel, setuptools, cython).
5

BLAS and Scientific Python

Installs either OpenBLAS or MKL along with numpy and scipy. Sets FFTW_STATIC based on BLAS choice:
  • OpenBLAS: Dynamic FFTW linking
  • MKL: Static FFTW linking to avoid symbol conflicts
6

MPI Installation

If INSTALL_MPI=1: Installs conda-forge compilers, OpenMPI, and mpi4py.If INSTALL_MPI=0: Adds custom MPI to PATH and installs mpi4py via pip.
7

FFTW Installation

If INSTALL_FFTW=1: Installs FFTW from conda-forge with OpenMPI support.If INSTALL_FFTW=0: Uses custom FFTW specified in FFTW_PATH.
8

HDF5 Installation

If INSTALL_HDF5=1: Installs HDF5 and h5py from conda-forge. Uses parallel versions if MPI is installed from conda.If INSTALL_HDF5=0: Installs h5py via pip, building against custom HDF5. Sets CC=mpicc for parallel builds.
9

Additional Dependencies

Installs docopt and matplotlib from conda-forge.
10

Dedalus Installation

Installs Dedalus v2 from PyPI using pip with CC=mpicc for proper MPI linking.
11

Threading Configuration

Sets environment variables to disable threading by default:
  • OMP_NUM_THREADS=1
  • NUMEXPR_MAX_THREADS=1

​
Environment Variables Set

The script configures the following environment variables in the conda environment:
​
OMP_NUM_THREADS
string
default:"1"
OpenMP thread count. Set to 1 to disable threading by default.
​
NUMEXPR_MAX_THREADS
string
default:"1"
NumExpr maximum thread count. Set to 1 to disable threading by default.
​
PYTHONNOUSERSITE
string
default:"1"
Prevents Python from adding user site-packages to sys.path during installation.
​
FFTW_STATIC
string
Controls FFTW linking mode:
  • 0: Dynamic linking (with OpenBLAS)
  • 1: Static linking (with MKL to avoid symbol conflicts)

​
Activating the Environment

After installation completes: 
# Activate the environment
conda activate dedalus2

# Verify installation
python -c "import dedalus; print(dedalus.__version__)"

# Test MPI functionality
mpiexec -n 4 python -c "from mpi4py import MPI; print(f'Rank {MPI.COMM_WORLD.rank}')"

​
Troubleshooting

​
Environment Already Exists

If the conda environment already exists, the script will prompt: 
WARNING: Conda environment 'dedalus2' already exists
Proceed ([y]/n)?
Respond with y to continue installation into the existing environment, or n to abort.

​
Custom Library Path Errors

If using custom MPI, FFTW, or HDF5 installations: 
ERROR: MPI_PATH must be set
ERROR: FFTW_PATH must be set
ERROR: HDF5_DIR must be set
Ensure the corresponding environment variables are exported before running the script.

​
Base Environment Not Active

ERROR: Conda base environment must be activated
Run conda activate base before executing the script.

​
Differences from Dedalus v3 Script

The main difference between v2 and v3 scripts is the Dedalus installation source:
  • v2 script: Installs dedalus==2.* from PyPI
  • v3 script: Installs from the development branch on GitHub
All other configuration options and installation steps are identical.

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us