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.

​
Prerequisites

Before installing Dedalus, ensure you have:
  • Conda or Miniconda installed and available in your shell
  • Base environment activated: The installation scripts must run from the conda base environment
  • Bash shell: The custom build scripts require bash
If you don’t have conda installed, download Miniforge (recommended) or Miniconda.

​
Fast Install (conda-forge)

The quickest way to get started is using the conda-forge package:
1

Create Environment

Create a new conda environment for Dedalus v2:
conda create -y -n dedalus2
conda activate dedalus2
2

Install Dedalus

Install Dedalus from conda-forge:
conda install -y -c conda-forge dedalus
3

Configure Threading

Set threading environment variables:
conda env config vars set OMP_NUM_THREADS=1
conda env config vars set NUMEXPR_MAX_THREADS=1
Then reactivate the environment:
conda deactivate
conda activate dedalus2
4

Verify Installation

Test your installation:
python3 -m dedalus test
You should see test output indicating successful execution.
This method installs Dedalus v2 with OpenMPI and parallel HDF5 support. It’s suitable for laptops, workstations, and clusters that don’t require custom library linking.

​
Custom Build Installation

For advanced use cases requiring custom MPI, FFTW, or HDF5 libraries:
1

Download Build Scripts

Clone or download the build scripts repository:
git clone https://github.com/DedalusProject/conda_builds_dedalus.git
cd conda_builds_dedalus
2

Activate Base Environment

Ensure you’re in the conda base environment:
conda activate base
3

Run Installation Script

For Dedalus v2 (stable):
bash conda_install_dedalus2.sh
Or for Dedalus v3 (development):
bash conda_install_dedalus3.sh
The script will:
  • Create a new conda environment (dedalus2 or dedalus3)
  • Install all dependencies from conda-forge
  • Build and install Dedalus with MPI support
  • Configure threading variables automatically
4

Activate and Test

After installation completes:
conda activate dedalus2  # or dedalus3
python3 -m dedalus test
The custom build scripts must be run from the conda base environment. The script will exit with an error if this requirement is not met.

​
Platform-Specific Notes

​
Linux

On Linux systems, both conda-forge and custom builds work without additional configuration: 
# Standard installation works on most Linux distributions
bash conda_install_dedalus2.sh

​
macOS (Intel)

On Intel-based Macs, the standard installation process works: 
# Works on x86_64 macOS
bash conda_install_dedalus2.sh

​
macOS (Apple Silicon)

Apple Silicon Macs use x86_64 emulation by default to avoid numerical errors: 
# Automatically uses x86_64 emulation via Rosetta 2
bash conda_install_dedalus2.sh
The scripts detect Apple Silicon automatically and configure the environment for x86_64 emulation. To use native ARM64 builds (not recommended), edit the script and set:
APPLE_SILICON_BUILD_ARM=1

​
Verifying Your Installation

After installation, verify that key components are working:

​
Check Dedalus Version

python3 -c "import dedalus; print(dedalus.__version__)"

​
Check MPI

python3 -c "from mpi4py import MPI; print(f'MPI processes: {MPI.COMM_WORLD.size}')"

​
Check Parallel HDF5

python3 -c "import h5py; print(f'Parallel HDF5: {h5py.get_config().mpi}')"

​
Run Test Suite

Run the comprehensive test suite: 
python3 -m dedalus test
The test suite may take several minutes to complete. All tests should pass on a fresh installation.

​
Running Your First Simulation

Once installed, you can run Dedalus simulations. Here’s a minimal example: 
import numpy as np
import dedalus.public as d3

# Create a 1D domain
xcoord = d3.Coordinate('x')
dist = d3.Distributor(xcoord, dtype=np.float64)
xbasis = d3.RealFourier(xcoord, size=256, bounds=(0, 2*np.pi))

# Define a field
u = dist.Field(name='u', bases=xbasis)

# Set initial condition
x = dist.local_grid(xbasis)
u['g'] = np.sin(x)

print(f"Field u created with shape: {u['g'].shape}")
Save this as test_dedalus.py and run: 
python3 test_dedalus.py

​
Running Parallel Simulations

Dedalus leverages MPI for parallel execution: 
# Run on 4 MPI processes
mpiexec -n 4 python3 your_simulation.py
When running MPI jobs, ensure OMP_NUM_THREADS=1 to prevent thread-based parallelism from interfering with MPI-based parallelism. This is set automatically by the installation scripts.

​
Troubleshooting

​
Import Errors

If you encounter import errors: 
# Ensure the environment is activated
conda activate dedalus2

# Check Python is using the correct environment
which python3

​
MPI Errors

If you see MPI-related errors:
  • Ensure you’re running via mpiexec for multi-process jobs
  • Check that mpi4py is installed: python3 -c "import mpi4py"
  • Verify MPI compiler: which mpicc

​
Test Failures

If tests fail:
  • Check threading variables: echo $OMP_NUM_THREADS (should be 1)
  • Verify clean environment: echo $PYTHONPATH (should be empty)
  • Try reinstalling in a fresh environment

​
Next Steps

Installation Methods

Learn about different installation approaches and when to use each

Dedalus Documentation

Explore the official Dedalus documentation for tutorials and examples

Build docs developers (and LLMs) love

Get started for freeTalk to us