Script Configuration Options

Overview

Both conda_install_dedalus2.sh and conda_install_dedalus3.sh share the same configuration options. These options are defined as shell variables at the top of each script and control the installation behavior, dependencies, and environment configuration.

Configuration Variables

Environment Options

CONDA_ENV

string

default:"dedalus2"

required

Name of the conda environment to create or update.Default values:

dedalus2 for v2 script
dedalus3 for v3 script

Example:

CONDA_ENV="my_dedalus_env"

CONDA_YES

integer

default:"1"

Skip conda prompts by automatically confirming all operations.Values:

1: Skip prompts (pass -y flag to conda)
0: Prompt for confirmation

Example:

CONDA_YES=0  # Prompt before each installation step

CONDA_QUIET

integer

default:"1"

Suppress verbose conda output during installation.Values:

1: Quiet output (pass -q flag to conda)
0: Verbose output

Example:

CONDA_QUIET=0  # Show detailed conda output

MPI Configuration

INSTALL_MPI

integer

default:"1"

Control whether to install OpenMPI from conda or use a custom MPI installation.Values:

1: Install OpenMPI from conda-forge
0: Use custom MPI (requires MPI_PATH to be set)

Conda installation includes:

conda-forge compilers
OpenMPI library
openmpi-mpicc wrapper
mpi4py Python bindings

Example:

INSTALL_MPI=1  # Use conda OpenMPI

MPI_PATH

string

Path to custom MPI installation prefix. Required when INSTALL_MPI=0.The path should point to the MPI installation root directory containing bin/, lib/, and include/ subdirectories.Example:

INSTALL_MPI=0
export MPI_PATH=/usr/local/openmpi-4.1.4

The script will add ${MPI_PATH}/bin to PATH and use it to build mpi4py.

When using custom MPI, ensure the MPI compiler wrappers (mpicc, mpicxx, mpifort) are in ${MPI_PATH}/bin.

FFTW Configuration

INSTALL_FFTW

integer

default:"1"

Control whether to install FFTW from conda or use a custom FFTW installation.Values:

1: Install FFTW from conda-forge
0: Use custom FFTW (requires FFTW_PATH to be set)

Conda installation: The script installs FFTW with OpenMPI support using --no-deps to avoid pulling unnecessary dependencies:

conda install --no-deps "fftw=*=*openmpi*"

Example:

INSTALL_FFTW=1  # Use conda FFTW

FFTW_PATH

string

Path to custom FFTW installation prefix. Required when INSTALL_FFTW=0.The path should point to the FFTW installation root directory containing lib/ and include/ subdirectories.Example:

INSTALL_FFTW=0
export FFTW_PATH=/usr/local/fftw-3.3.10

FFTW from conda is built with OpenMPI support and may not work correctly with custom MPIs that are not OpenMPI-compatible.

HDF5 Configuration

INSTALL_HDF5

integer

default:"1"

Control whether to install HDF5 from conda or use a custom HDF5 installation.Values:

1: Install HDF5 from conda-forge
0: Use custom HDF5 (requires HDF5_DIR to be set)

Conda installation behavior:

If INSTALL_MPI=1: Installs parallel HDF5 (hdf5=*=mpi*, h5py=*=mpi*)
If INSTALL_MPI=0: Installs serial HDF5 (hdf5=*=nompi*, h5py=*=nompi*)

Example:

INSTALL_HDF5=1  # Use conda HDF5

HDF5_DIR

string

Path to custom HDF5 installation prefix. Required when INSTALL_HDF5=0.The path should point to the HDF5 installation root directory containing lib/ and include/ subdirectories.Example:

INSTALL_HDF5=0
export HDF5_DIR=/usr/local/hdf5-1.14.0
export HDF5_MPI="ON"  # If HDF5 has parallel support

HDF5_MPI

string

Indicate whether custom HDF5 installation has parallel (MPI) support. Only relevant when INSTALL_HDF5=0.Values:

"ON": HDF5 built with parallel/MPI support
Not set or "OFF": HDF5 built without MPI support

Impact on h5py installation:

If HDF5_MPI="ON": Builds h5py with CC=mpicc for parallel support
Otherwise: Builds h5py without MPI support

Example:

INSTALL_HDF5=0
export HDF5_DIR=/opt/hdf5-parallel
export HDF5_MPI="ON"

HDF5 from conda will only have parallel support if MPI is also installed from conda (INSTALL_MPI=1).

BLAS Configuration

BLAS

string

default:"openblas"

required

Choose the BLAS/LAPACK implementation for numpy and scipy.Values:

"openblas": Use OpenBLAS (open-source, generally good performance)
"mkl": Use Intel Math Kernel Library (optimized for Intel CPUs)

Effects:OpenBLAS:

Installs libblas=*=*openblas
Sets FFTW_STATIC=0 (dynamic linking)
On Apple Silicon with arm64 builds, pins libopenblas<0.3.20 to avoid ggev errors

MKL:

Installs libblas=*=*mkl
Sets FFTW_STATIC=1 (static linking to avoid symbol conflicts)
May provide better performance on Intel processors

Example:

BLAS="openblas"  # Use OpenBLAS

BLAS="mkl"  # Use Intel MKL

Python Configuration

PYTHON_VERSION

string

default:"3.12"

Python version to install in the conda environment.Supported versions: Any Python 3.x version supported by conda-forge (typically 3.8+).Example:

PYTHON_VERSION="3.11"  # Install Python 3.11

PYTHON_VERSION="3.10"  # Install Python 3.10

Dedalus requires Python 3.8 or newer. Check the Dedalus documentation for specific version requirements.

Apple Silicon Configuration

APPLE_SILICON_BUILD_ARM

integer

default:"0"

Control architecture for Apple Silicon (M1/M2/M3) Macs.Values:

0: Use x86_64 packages via Rosetta 2 emulation (osx-64)
1: Use native arm64 packages (osx-arm64)

Behavior:This flag only has an effect on Apple Silicon machines (Darwin + arm64). On all other platforms, it is automatically set to 0.x86_64 mode (default):

Better compatibility with scientific libraries
Uses Rosetta 2 translation (minimal performance impact)
Sets CONDA_SUBDIR=osx-64

arm64 mode:

Native Apple Silicon performance
May have compatibility issues with some packages
Automatically pins libopenblas<0.3.20 when using OpenBLAS to avoid numerical errors

Example:

APPLE_SILICON_BUILD_ARM=0  # Use x86_64 (recommended)

APPLE_SILICON_BUILD_ARM=1  # Use native arm64

Native arm64 builds may exhibit numerical errors in certain linear algebra operations, particularly with OpenBLAS versions >= 0.3.20. The x86_64 mode via Rosetta 2 is recommended for production work.

Example Configurations

Standard Installation with Conda Packages

# Use all conda-forge packages with OpenBLAS
CONDA_ENV="dedalus2"
CONDA_YES=1
CONDA_QUIET=1
INSTALL_MPI=1
INSTALL_FFTW=1
INSTALL_HDF5=1
BLAS="openblas"
PYTHON_VERSION="3.12"
APPLE_SILICON_BUILD_ARM=0

Custom MPI with Conda FFTW and HDF5

# Use custom OpenMPI, conda FFTW and HDF5
CONDA_ENV="dedalus_custom_mpi"
CONDA_YES=1
CONDA_QUIET=1
INSTALL_MPI=0
export MPI_PATH=/usr/local/openmpi
INSTALL_FFTW=1
INSTALL_HDF5=1
BLAS="openblas"
PYTHON_VERSION="3.12"
APPLE_SILICON_BUILD_ARM=0

When using custom MPI with conda FFTW, ensure your MPI is OpenMPI-compatible since conda FFTW is built with OpenMPI.

Fully Custom Dependencies

# Use all custom MPI, FFTW, and HDF5
CONDA_ENV="dedalus_custom"
CONDA_YES=1
CONDA_QUIET=0  # Show detailed output for debugging
INSTALL_MPI=0
export MPI_PATH=/opt/custom/openmpi-4.1.5
INSTALL_FFTW=0
export FFTW_PATH=/opt/custom/fftw-3.3.10
INSTALL_HDF5=0
export HDF5_DIR=/opt/custom/hdf5-1.14.0
export HDF5_MPI="ON"
BLAS="openblas"
PYTHON_VERSION="3.11"
APPLE_SILICON_BUILD_ARM=0

Intel MKL Configuration

# Use Intel MKL for BLAS
CONDA_ENV="dedalus_mkl"
CONDA_YES=1
CONDA_QUIET=1
INSTALL_MPI=1
INSTALL_FFTW=1
INSTALL_HDF5=1
BLAS="mkl"  # Use Intel MKL
PYTHON_VERSION="3.12"
APPLE_SILICON_BUILD_ARM=0

When using MKL, the script automatically sets FFTW_STATIC=1 to statically link FFTW, avoiding symbol conflicts between MKL and FFTW.

Apple Silicon Native Build

# Native arm64 build on Apple Silicon
CONDA_ENV="dedalus_arm64"
CONDA_YES=1
CONDA_QUIET=1
INSTALL_MPI=1
INSTALL_FFTW=1
INSTALL_HDF5=1
BLAS="openblas"
PYTHON_VERSION="3.12"
APPLE_SILICON_BUILD_ARM=1  # Use native arm64

Verbose Installation for Debugging

# Show all prompts and output for troubleshooting
CONDA_ENV="dedalus_debug"
CONDA_YES=0  # Prompt before each step
CONDA_QUIET=0  # Show verbose output
INSTALL_MPI=1
INSTALL_FFTW=1
INSTALL_HDF5=1
BLAS="openblas"
PYTHON_VERSION="3.12"
APPLE_SILICON_BUILD_ARM=0

Environment Variables Set by Script

In addition to the configuration options, the script sets several environment variables during installation:

During Installation

PYTHONNOUSERSITE

string

default:"1"

Prevents Python from adding user site-packages directory to sys.path.

export PYTHONNOUSERSITE=1

PYTHONPATH

string

Unset to ensure a clean Python environment without interference from system packages.

unset PYTHONPATH

FFTW_STATIC

string

Automatically set based on BLAS choice:

0 for OpenBLAS (dynamic linking)
1 for MKL (static linking)

export FFTW_STATIC=0  # or 1

PATH

string

When using custom MPI, the script prepends ${MPI_PATH}/bin to PATH:

export PATH=${MPI_PATH}/bin:${PATH}

string

default:"mpicc"

Set to mpicc when installing mpi4py, h5py, and Dedalus to ensure proper MPI linking:

CC=mpicc pip install ...

CONDA_SUBDIR

string

On Apple Silicon with APPLE_SILICON_BUILD_ARM=0, sets architecture to x86_64:

CONDA_SUBDIR=osx-64 conda create ...

Persistent Environment Variables

These are saved to the conda environment and active whenever the environment is activated:

OMP_NUM_THREADS

string

default:"1"

Disables OpenMP threading by default to avoid oversubscription in MPI jobs.

conda env config vars set OMP_NUM_THREADS=1

NUMEXPR_MAX_THREADS

string

default:"1"

Limits NumExpr threads to prevent performance issues with MPI.

conda env config vars set NUMEXPR_MAX_THREADS=1

Validation and Error Checking

The scripts perform several validation checks before installation:

Required Environment Check

if [ "${CONDA_DEFAULT_ENV}" != "base" ]; then
    echo "ERROR: Conda base environment must be activated"
    exit 1
fi

Custom Path Validation

When using custom installations (INSTALL_*=0), the corresponding path variable must be set:

if [ ${INSTALL_MPI} -ne 1 ]; then
    if [ -z ${MPI_PATH} ]; then
        echo "ERROR: MPI_PATH must be set"
        exit 1
    fi
fi

Similar checks are performed for FFTW_PATH and HDF5_DIR.

Platform Detection

if [ $(uname -s) == "Darwin" ] && [ $(uname -m) == "arm64" ]; then
    ON_APPLE_SILICON=1
else
    ON_APPLE_SILICON=0
    APPLE_SILICON_BUILD_ARM=0
fi

BLAS Validation

case "${BLAS}" in
    "openblas") ... ;;
    "mkl") ... ;;
    *)
        echo "ERROR: BLAS must be 'openblas' or 'mkl'"
        exit 1
    ;;
esac

Modifying Options

To customize the installation, edit the configuration section at the top of the script before running it:

Download Script

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

Edit Configuration

Open the script in a text editor and modify the options section (lines 10-43):

nano conda_install_dedalus2.sh

Make Executable

chmod +x conda_install_dedalus2.sh

Run Script

conda activate base
./conda_install_dedalus2.sh

Alternatively, you can set environment variables before running the script:

# Set environment variables
export CONDA_ENV="my_custom_env"
export PYTHON_VERSION="3.11"
export BLAS="mkl"

# Run script (note: internal script variables won't be affected)
# Edit the script directly for this approach

Environment variables set before running the script only affect variables explicitly exported in the script (like MPI_PATH, FFTW_PATH, HDF5_DIR). Internal script variables must be edited within the script file itself.

Get Started

Build Scripts

Configuration

Advanced

Script Configuration Options

Overview

Configuration Variables

Environment Options

MPI Configuration

FFTW Configuration

HDF5 Configuration

BLAS Configuration

Python Configuration

Apple Silicon Configuration

Example Configurations

Standard Installation with Conda Packages

Custom MPI with Conda FFTW and HDF5

Fully Custom Dependencies

Intel MKL Configuration

Apple Silicon Native Build

Verbose Installation for Debugging

Environment Variables Set by Script

During Installation

Persistent Environment Variables

Validation and Error Checking

Required Environment Check

Custom Path Validation

Platform Detection

BLAS Validation

Modifying Options

Build docs developers (and LLMs) love

Get Started

Build Scripts

Configuration

Advanced

Documentation Index

​Overview

​Configuration Variables

​Environment Options

​MPI Configuration

​FFTW Configuration

​HDF5 Configuration

​BLAS Configuration

​Python Configuration

​Apple Silicon Configuration

​Example Configurations

​Standard Installation with Conda Packages

​Custom MPI with Conda FFTW and HDF5

​Fully Custom Dependencies

​Intel MKL Configuration

​Apple Silicon Native Build

​Verbose Installation for Debugging

​Environment Variables Set by Script

​During Installation

​Persistent Environment Variables

​Validation and Error Checking

​Required Environment Check

​Custom Path Validation

​Platform Detection

​BLAS Validation

​Modifying Options

Build docs developers (and LLMs) love

Overview

Configuration Variables

Environment Options

MPI Configuration

FFTW Configuration

HDF5 Configuration

BLAS Configuration

Python Configuration

Apple Silicon Configuration

Example Configurations

Standard Installation with Conda Packages

Custom MPI with Conda FFTW and HDF5

Fully Custom Dependencies

Intel MKL Configuration

Apple Silicon Native Build

Verbose Installation for Debugging

Environment Variables Set by Script

During Installation

Persistent Environment Variables

Validation and Error Checking

Required Environment Check

Custom Path Validation

Platform Detection

BLAS Validation

Modifying Options