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.

​
Installation Errors

​
Conda Base Environment Not Activated

Error Message:
ERROR: Conda base environment must be activated
Cause: The build script checks that you’re running from the conda base environment before creating a new Dedalus environment.Solution:
1
Activate the Base Environment
2
conda activate base
3
Verify Activation
4
echo $CONDA_DEFAULT_ENV
# Should output: base
5
Run the Script Again
6
bash conda_install_dedalus3.sh
If you’re not in any conda environment, you may need to initialize conda first:
conda init bash  # or zsh, fish, etc.
# Restart your shell
conda activate base

​
Missing Custom Library Paths

Error Message:
ERROR: MPI_PATH must be set
Cause: You set INSTALL_MPI=0 to use a custom MPI installation, but didn’t provide the path to your MPI.Solution:Edit the script configuration at the top:
INSTALL_MPI=0
export MPI_PATH=/path/to/your/mpi  # Add this line
The MPI_PATH should be the prefix directory containing bin/mpicc.Find Your MPI Path:
# Find mpicc location
which mpicc
# Output example: /usr/local/mpi/bin/mpicc
# MPI_PATH is: /usr/local/mpi

# Or check environment modules
module show openmpi
# Look for PREFIX or PATH variables
Error Message:
ERROR: FFTW_PATH must be set
Solution:Edit the script:
INSTALL_FFTW=0
export FFTW_PATH=/path/to/your/fftw
Find Your FFTW Path:
# Search for FFTW libraries
find /usr/local -name "libfftw3.so" 2>/dev/null
find /opt -name "libfftw3.so" 2>/dev/null

# Check module files
module show fftw
Error Message:
ERROR: HDF5_DIR must be set
Solution:
INSTALL_HDF5=0
export HDF5_DIR=/path/to/your/hdf5
export HDF5_MPI="ON"  # If parallel HDF5, otherwise omit
Find Your HDF5 Path:
# Check for h5pcc (parallel) or h5cc (serial)
which h5pcc
# Or search for libraries
find /usr/local -name "libhdf5.so" 2>/dev/null

​
Compiler and Linking Issues

Error During Installation:
mpicc: command not found
error: command 'mpicc' failed
Cause: The custom MPI’s compiler is not in your PATH.Solutions:
1
Verify MPI_PATH
2
Check that your MPI_PATH is correct:
3
ls ${MPI_PATH}/bin/mpicc
# Should show the mpicc binary
4
Load Environment Modules
5
If using environment modules:
6
module load openmpi  # or intel-mpi, mpich, etc.
module list  # Verify it's loaded
7
Manually Add to PATH
8
Before running the script:
9
export PATH=/path/to/mpi/bin:$PATH
which mpicc  # Verify it's found
Error During pip Install:
ld: library not found for -lfftw3
ld: library not found for -lhdf5
Cause: The linker cannot find your custom libraries.Solution:Set library paths before running the script:Linux:
export LD_LIBRARY_PATH=/path/to/fftw/lib:/path/to/hdf5/lib:/path/to/mpi/lib:$LD_LIBRARY_PATH
macOS:
export DYLD_LIBRARY_PATH=/path/to/fftw/lib:/path/to/hdf5/lib:/path/to/mpi/lib:$DYLD_LIBRARY_PATH
Persistent Solution:Add to your ~/.bashrc or ~/.zshrc:
if [ -d "/path/to/custom/libs" ]; then
    export LD_LIBRARY_PATH="/path/to/custom/libs/lib:$LD_LIBRARY_PATH"
fi
Error:
fatal error: Python.h: No such file or directory
Cause: Python development headers are missing (unlikely in conda, but possible with system Python).Solution:Ensure you’re using the conda Python:
conda activate dedalus3
which python3
# Should show: /path/to/conda/envs/dedalus3/bin/python3

# Reinstall Python if needed
conda install -y python=${PYTHON_VERSION}

​
Runtime Errors

​
Test Suite Failures

Error:
python3 -m dedalus test
# Various test failures or import errors
Common Causes and Solutions:
1
Import Errors
2
If you see ImportError or ModuleNotFoundError:
3
# Ensure environment is activated
conda activate dedalus3

# Verify dedalus is installed
python3 -c "import dedalus; print(dedalus.__version__)"

# Check for conflicting packages
conda list | grep dedalus
4
MPI Errors
5
If tests hang or show MPI errors:
6
# Check MPI is working
mpiexec -n 2 python3 -c "from mpi4py import MPI; print(MPI.COMM_WORLD.Get_rank())"

# Verify threading is disabled (important!)
conda activate dedalus3
echo $OMP_NUM_THREADS  # Should be 1
echo $NUMEXPR_MAX_THREADS  # Should be 1
7
Numerical Errors
8
If tests fail with numerical accuracy issues:
9
  • May indicate BLAS/LAPACK issues
  • On Apple Silicon with arm64, try x86_64 build instead
  • Check FFTW and BLAS libraries are compatible
    • Error:
    mpiexec -n 4 python3 script.py
Segmentation fault (core dumped)
    Common Causes:
    1. MPI Version Mismatch
      • All components (mpi4py, h5py, FFTW, Dedalus) must use the same MPI
      • Verify with: 
        python3 -c "import mpi4py; print(mpi4py.get_config())"
ldd $(python3 -c "import h5py; print(h5py.__file__)") | grep mpi
    2. Threading Conflicts
      • Ensure threading is disabled: 
        export OMP_NUM_THREADS=1
export NUMEXPR_MAX_THREADS=1
    3. Oversubscription
      • Don’t run more MPI processes than CPU cores
      • Use mpiexec -n <cores> appropriately
    4. Custom Library Issues
      • Rebuild with all libraries from conda-forge to isolate the issue

    ​
    Environment Issues

    Error:
    Unsatisfiable dependencies
Conflicting packages
    Solutions:
    1
    Try a Clean Environment
    2
    conda deactivate
conda env remove -n dedalus3
# Edit script if needed
bash conda_install_dedalus3.sh
    3
    Update Conda
    4
    conda activate base
conda update -n base conda
    5
    Clear Conda Cache
    6
    conda clean --all
    7
    Check Channel Priority
    8
    The script sets strict channel priority. Verify:
    9
    conda config --show channel_priority
# Should be: strict
    Message:
    WARNING: Conda environment 'dedalus3' already exists
Proceed ([y]/n)?
    This is not an error. The script detects an existing environment.Options:
    1. Proceed (y): Updates packages in the existing environment
      • May cause conflicts if packages were manually modified
    2. Cancel (n) and remove: Start fresh 
      conda env remove -n dedalus3
bash conda_install_dedalus3.sh
    3. Change environment name: Edit CONDA_ENV in the script 
      CONDA_ENV="dedalus3_new"

    ​
    Platform-Specific Issues

    ​
    macOS

    Symptoms:
    • Test failures with numerical accuracy issues
    • ggev errors in LAPACK routines
    • Unexpected NaN or Inf values
    Cause: Some library versions have issues with arm64 architecture.Solution:Use the x86_64 build via Rosetta (default in scripts):
    APPLE_SILICON_BUILD_ARM=0  # Default, uses Rosetta
    The script automatically:
    • Creates environment with CONDA_SUBDIR=osx-64
    • Pins libopenblas<0.3.20 on arm64 if needed
    If you need native arm64:
    APPLE_SILICON_BUILD_ARM=1  # May have issues
    Error:
    dyld: Library not loaded
    Solution:Ensure DYLD_LIBRARY_PATH is set if using custom libraries:
    export DYLD_LIBRARY_PATH=/path/to/custom/libs/lib:$DYLD_LIBRARY_PATH
    On newer macOS versions, DYLD_LIBRARY_PATH may be restricted by System Integrity Protection (SIP). Using conda-forge libraries avoids this issue.

    ​
    Linux

    Symptoms:
    • MPI jobs fail to start
    • Conflicts with job scheduler (SLURM, PBS)
    • “PMI” or “PMIx” errors
    Solution:
    1. Use system MPI: 
      INSTALL_MPI=0
export MPI_PATH=/path/to/system/mpi
    2. Load correct modules: 
      module purge
module load mpi/openmpi  # or your cluster's MPI
    3. Check SLURM integration:
      • Use srun instead of mpiexec on SLURM clusters
      • Ensure MPI is compiled with SLURM support
    Error:
    version `GLIBC_2.XX' not found
    Cause: Conda packages built with newer GLIBC than your system has.Solutions:
    1. Update your system (if possible)
    2. Use older conda packages: 
      conda install "python<3.12"
    3. Use custom builds compiled on your system

    ​
    Performance Issues

    Cause: Threading is not properly disabled. Multiple OpenMP threads compete with MPI.Solution:The script sets these automatically, but verify:
    conda activate dedalus3
echo $OMP_NUM_THREADS  # Should be 1
echo $NUMEXPR_MAX_THREADS  # Should be 1
    Set manually if needed:
    conda env config vars set OMP_NUM_THREADS=1
conda env config vars set NUMEXPR_MAX_THREADS=1
conda deactivate
conda activate dedalus3
    For individual scripts:
    export OMP_NUM_THREADS=1
export NUMEXPR_MAX_THREADS=1
python3 script.py
    Error:
    MemoryError
killed
    Solutions:
    1. Reduce problem size (lower resolution, smaller domain)
    2. Use more MPI processes (distributes memory) 
      mpiexec -n 8 python3 script.py  # Instead of -n 4
    3. Monitor memory usage: 
      # Check available memory
free -h  # Linux
vm_stat  # macOS
    4. Increase system swap (last resort, slower)

    ​
    Getting Help

    If you’re still experiencing issues:
    1
    Gather Diagnostic Information
    2
    # System info
uname -a
conda --version

# Environment info
conda activate dedalus3
conda list
python3 -c "import dedalus; print(dedalus.__version__)"
python3 -c "import mpi4py; print(mpi4py.get_config())"
    3
    Check GitHub Issues
    4
    Search existing issues in the Dedalus repository and this conda builds repository.
    5
    Post Detailed Issue
    6
    Include:
    7
  • Full error message and traceback
  • Platform and conda version
  • Custom library configuration (if any)
  • Minimal reproducing example
  • Diagnostic information from above

    • Build docs developers (and LLMs) love

    Get started for freeTalk to us