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

Apple Silicon Macs (M1, M2, M3) can run code in two modes: native arm64 or x86_64 via Rosetta 2 emulation. The build scripts provide a configuration option to choose between these modes.

​
Configuration Option

​
APPLE_SILICON_BUILD_ARM

​
APPLE_SILICON_BUILD_ARM
integer
default:"0"
Controls whether to build native arm64 packages on Apple Silicon.Valid values:
  • 0 - Build x86_64 packages using Rosetta 2 (default, more stable)
  • 1 - Build native arm64 packages
Note: Only relevant on Apple Silicon machines. Automatically set to 0 on other platforms.

​
Build Modes

By default, the build uses x86_64 packages that run via Rosetta 2 emulation.
APPLE_SILICON_BUILD_ARM=0

​
Build Process

From the build script:
conda_install_dedalus3.sh
echo "Building new conda environment '${CONDA_ENV}'"
if [ ${ON_APPLE_SILICON} -eq 1 ] && [ ${APPLE_SILICON_BUILD_ARM} -eq 0 ]
then
    CONDA_SUBDIR=osx-64 conda create "${CARGS[@]}"
    conda activate ${CONDA_ENV}
    conda config --env --set subdir osx-64
The environment is configured to use osx-64 (x86_64) packages:
  • Sets CONDA_SUBDIR=osx-64 during creation
  • Configures the environment to maintain subdir osx-64
  • All packages are x86_64 and run via Rosetta 2

​
Advantages

  • More stable: Better tested package ecosystem
  • Fewer bugs: Avoids arm64-specific issues
  • Recommended default: As noted in the script comments
  • Good performance: Rosetta 2 is efficient for most workloads
This is the recommended mode for Apple Silicon. The x86_64 packages via Rosetta 2 provide better stability with minimal performance impact.

​
Platform Detection

The build script automatically detects Apple Silicon:
conda_install_dedalus3.sh
# Unset arm build flag unless on Apple Silicon
if [ $(uname -s) == "Darwin" ] && [ $(uname -m) == "arm64" ]
then
    ON_APPLE_SILICON=1
else
    ON_APPLE_SILICON=0
    APPLE_SILICON_BUILD_ARM=0
fi
  • Checks for Darwin (macOS) and arm64 architecture
  • Sets ON_APPLE_SILICON=1 if both conditions are true
  • Forces APPLE_SILICON_BUILD_ARM=0 on non-Apple Silicon platforms
The APPLE_SILICON_BUILD_ARM option is automatically disabled on Intel Macs, Linux, and Windows. It only has an effect on Apple Silicon hardware.

​
Choosing Your Build Mode

For most users, stick with the default x86_64 mode: 
# Recommended configuration for Apple Silicon
APPLE_SILICON_BUILD_ARM=0
BLAS="openblas"
This provides:
  • Maximum stability
  • Well-tested package ecosystem
  • Minimal configuration needed
  • Good performance via Rosetta 2

​
When to Use arm64 Mode

Consider native arm64 if:
  • You need maximum performance
  • You’re comfortable troubleshooting platform issues
  • Your workloads are CPU-intensive
  • You want better power efficiency
# Native arm64 configuration
APPLE_SILICON_BUILD_ARM=1
BLAS="openblas"
# OpenBLAS will be automatically pinned to <0.3.20

​
Complete Configuration Examples

# Default, stable configuration
CONDA_ENV="dedalus3"
PYTHON_VERSION="3.12"

INSTALL_MPI=1
INSTALL_FFTW=1
INSTALL_HDF5=1

BLAS="openblas"

# Use x86_64 via Rosetta 2
APPLE_SILICON_BUILD_ARM=0

​
Checking Your Architecture

After installation, verify which architecture you’re using: 
# Check system architecture
uname -m
# arm64 = Apple Silicon hardware

# Check Python architecture
conda activate dedalus3
python3 -c "import platform; print(platform.machine())"
# x86_64 = Rosetta 2 emulation
# arm64 = Native Apple Silicon

# Check conda environment subdirectory
conda config --show subdir
# osx-64 = x86_64 packages
# osx-arm64 = arm64 packages

​
GitHub Actions Testing

The GitHub Actions workflows test x86_64 mode on macOS:
test_conda_builds.yml
- os: macos-latest
  label: osx-64
The CI only tests osx-64 (x86_64), reflecting that this is the recommended configuration.

​
Known Issues and Workarounds

​
OpenBLAS ggev Errors (arm64)

Issue: OpenBLAS >= 0.3.20 causes errors in generalized eigenvalue problems Workaround: Automatically applied by the build script 
if [ ${APPLE_SILICON_BUILD_ARM} -eq 1 ]
then
    conda install "${CARGS[@]}" "libopenblas<0.3.20"
fi

​
Package Availability (arm64)

Issue: Some packages may not be available for arm64 Workaround: Use x86_64 mode 
APPLE_SILICON_BUILD_ARM=0

​
Performance Testing

To compare performance between modes: 
# Run your simulation in both environments
time python3 your_simulation.py

# Compare:
# - Wall time
# - CPU efficiency
# - Results correctness

​
Migration Guide

​
From x86_64 to arm64

If you want to try native arm64: 
# Create new environment with arm64
CONDA_ENV="dedalus3_arm64"
APPLE_SILICON_BUILD_ARM=1
bash conda_install_dedalus3.sh

# Test thoroughly
conda activate dedalus3_arm64
python3 -m dedalus test

# Run your existing simulations
python3 your_simulation.py

# Compare results with x86_64 version

​
From arm64 to x86_64

If experiencing issues with arm64: 
# Create new x86_64 environment
CONDA_ENV="dedalus3_x86"
APPLE_SILICON_BUILD_ARM=0
bash conda_install_dedalus3.sh

# Should be more stable
conda activate dedalus3_x86
python3 -m dedalus test

​
Recommendations Summary

For most users on Apple Silicon:
APPLE_SILICON_BUILD_ARM=0  # Use x86_64 via Rosetta 2
BLAS="openblas"
This provides the best balance of stability and performance.
If using native arm64:
APPLE_SILICON_BUILD_ARM=1
BLAS="openblas"  # Will be pinned to <0.3.20
Be aware of the OpenBLAS version limitation and test thoroughly.

Build docs developers (and LLMs) love

Get started for freeTalk to us