Configuration

Dedalus provides extensive configuration options for controlling numerics, logging, parallelism, and output behavior. Configuration is managed through Python’s standard ConfigParser interface.

Configuration File Hierarchy

Dedalus examines configuration files in the following order (from lowest to highest precedence):

Package default

The default configuration in the Dedalus installation: dedalus/dedalus.cfg

User configuration

User-level settings: ~/.dedalus/dedalus.cfg

Local configuration

Project-specific settings: ./dedalus.cfg (in your working directory)

Runtime configuration

Direct modification in your Python script

Each level overrides settings from previous levels. You only need to specify options you want to change from the defaults.

Getting the Default Configuration

Export the default configuration file to your working directory:

python3 -m dedalus get_config

This creates a dedalus.cfg file with all default settings and documentation.

Runtime Configuration

Modify configuration directly in your Python script:

from dedalus.tools.config import config

# Change logging level
config['logging']['stdout_level'] = 'debug'

# Change transform library
config['transforms']['DEFAULT_LIBRARY'] = 'fftw'

# Enable profiling
config['profiling']['PROFILE_DEFAULT'] = 'True'

Runtime configuration changes must be made before importing problem-building components of Dedalus.

Configuration Sections

Logging

Control Dedalus logging behavior:

[logging]
# Available levels: {debug, info, warning, error, critical}

# Log level for non-root processes (rank > 0)
nonroot_level = warning

# Log level for stdout handler
# Use 'none' to disable
stdout_level = info

# Log level for file handler
# Use 'none' to disable
file_level = none

# Log filename base (expands to <filename>_p0.log, etc)
filename = logs/dedalus

Basic Logging
File Logging
Debug Mode
Quiet Mode

from dedalus.tools.config import config
import logging

# Console output only (default)
config['logging']['stdout_level'] = 'info'
config['logging']['file_level'] = 'none'

from dedalus.tools.config import config

# Save logs to files
config['logging']['file_level'] = 'debug'
config['logging']['filename'] = 'logs/my_simulation'
# Creates: logs/my_simulation_p0.log, logs/my_simulation_p1.log, ...

from dedalus.tools.config import config

# Verbose output for debugging
config['logging']['stdout_level'] = 'debug'
config['logging']['nonroot_level'] = 'info'  # See all ranks

from dedalus.tools.config import config

# Minimal output
config['logging']['stdout_level'] = 'warning'
config['logging']['nonroot_level'] = 'error'

Transforms

Configure spectral transforms:

[transforms]
# Default transform library (scipy, fftw)
DEFAULT_LIBRARY = fftw

# Transform multiple fields together when possible
GROUP_TRANSFORMS = False

# Apply dealiasing truncation before basis conversion
DEALIAS_BEFORE_CONVERTING = True

FFTW is strongly recommended over scipy for performance. Ensure FFTW is installed when building Dedalus.

FFTW-Specific Settings

[transforms-fftw]
# FFTW transform planning rigor
# Options: estimate, measure, patient, exhaustive
PLANNING_RIGOR = measure

FFTW Planning Rigor Explained

estimate: Fast planning, good performance
measure: Balanced planning and performance (recommended)
patient: Longer planning, better performance
exhaustive: Very long planning, best performance (rarely worth it)

The measure setting provides a good balance for most applications.

Parallelism

Configure parallel operations:

[parallelism]
# Default transpose library (fftw, mpi)
TRANSPOSE_LIBRARY = fftw

# Place MPI Barriers before each transpose call
SYNC_TRANSPOSES = False

# Transpose multiple fields together when possible
GROUP_TRANSPOSES = True

FFTW Transposes

Recommended for most systemsUses FFTW’s MPI transpose routines.

TRANSPOSE_LIBRARY = fftw

MPI Transposes

Alternative implementationUses direct MPI all-to-all communication.

TRANSPOSE_LIBRARY = mpi

FFTW Transpose Settings

[parallelism-fftw]
# Perform FFTW transposes in-place
IN_PLACE = False

# FFTW transpose planning rigor
# Options: estimate, measure, patient, exhaustive
PLANNING_RIGOR = measure

MPI Transpose Settings

[parallelism-mpi]
# Use variable-length all-to-all routine
ALLTOALLV = False

Matrix Construction

Control how linear systems are assembled:

[matrix construction]
# Put BC rows at the top of the matrix
BC_TOP = False

# Put tau columns at the left of the matrix
TAU_LEFT = False

# Interleave component modes
INTERLEAVE_COMPONENTS = False

# Store expanded LHS matrices
# Speeds up IVP matrix factorization at the expense of extra memory
STORE_EXPANDED_MATRICES = False

Set STORE_EXPANDED_MATRICES = True if you have sufficient memory and want faster timestepping at the cost of higher memory usage.

Linear Algebra

Configure matrix solvers:

[linear algebra]
# Default sparse matrix solver for single solves
MATRIX_SOLVER = SuperLUColamdSpsolve

# Default sparse matrix factorizer for repeated solves
MATRIX_FACTORIZER = SuperLUColamdFactorizedTranspose

# Split CSR matvecs vector-by-vector
SPLIT_CSR_MATVECS = False

# Revert to old sparsetools code for CSR matvecs
OLD_CSR_MATVECS = False

The default solvers work well for most problems. Only change these if you’re experiencing solver issues or have specific performance requirements.

Memory

Control memory usage and caching:

[memory]
# Store output fields for all operators
STORE_OUTPUTS = True

# Cache operator evaluation for repeated use in expression graph
STORE_LAST_DEFAULT = True

Disabling STORE_OUTPUTS or STORE_LAST_DEFAULT will reduce memory usage but may significantly slow down simulations.

Analysis

Configure output file handlers:

[analysis]
# Default filehandler mode (overwrite, append)
FILEHANDLER_MODE_DEFAULT = overwrite

# Default filehandler parallel output method (gather, virtual, mpio)
FILEHANDLER_PARALLEL_DEFAULT = virtual

# Force filehandlers to touch a tmp file on each node
# This works around NFS caching issues
FILEHANDLER_TOUCH_TMPFILE = False

overwrite (default)
append

FILEHANDLER_MODE_DEFAULT = overwrite

Each simulation run deletes previous output and starts fresh.

FILEHANDLER_MODE_DEFAULT = append

Continue writing to existing output files. Useful for restarting simulations.

See Output Format for details on parallel I/O modes.

Profiling

Enable performance profiling:

[profiling]
# Default profile setting for solvers
# This saves accumulated profiling data using cProfile
PROFILE_DEFAULT = False

# Default parallel profile setting for solvers
# This saves per-process and accumulated profiling data
PARALLEL_PROFILE_DEFAULT = False

# Profile directory base (expands to <PROFILE_DIRECTORY>/runtime.prof, etc)
PROFILE_DIRECTORY = profiles

Enable profiling for performance analysis:

from dedalus.tools.config import config

config['profiling']['PROFILE_DEFAULT'] = 'True'
config['profiling']['PROFILE_DIRECTORY'] = 'my_profiles'

# After simulation, analyze with:
# python -m cProfile -s cumulative my_profiles/runtime.prof

Complete Configuration File

Here’s a complete example configuration file:

dedalus.cfg

[logging]
nonroot_level = warning
stdout_level = info
file_level = none
filename = logs/dedalus

[transforms]
DEFAULT_LIBRARY = fftw
GROUP_TRANSFORMS = False
DEALIAS_BEFORE_CONVERTING = True

[transforms-fftw]
PLANNING_RIGOR = measure

[parallelism]
TRANSPOSE_LIBRARY = fftw
SYNC_TRANSPOSES = False
GROUP_TRANSPOSES = True

[parallelism-fftw]
IN_PLACE = False
PLANNING_RIGOR = measure

[parallelism-mpi]
ALLTOALLV = False

[matrix construction]
BC_TOP = False
TAU_LEFT = False
INTERLEAVE_COMPONENTS = False
STORE_EXPANDED_MATRICES = False

[linear algebra]
MATRIX_SOLVER = SuperLUColamdSpsolve
MATRIX_FACTORIZER = SuperLUColamdFactorizedTranspose
SPLIT_CSR_MATVECS = False
OLD_CSR_MATVECS = False

[memory]
STORE_OUTPUTS = True
STORE_LAST_DEFAULT = True

[analysis]
FILEHANDLER_MODE_DEFAULT = overwrite
FILEHANDLER_PARALLEL_DEFAULT = virtual
FILEHANDLER_TOUCH_TMPFILE = False

[profiling]
PROFILE_DEFAULT = False
PARALLEL_PROFILE_DEFAULT = False
PROFILE_DIRECTORY = profiles

Common Configuration Patterns

High-Performance Setup

from dedalus.tools.config import config

# Optimize for speed
config['transforms']['DEFAULT_LIBRARY'] = 'fftw'
config['parallelism']['TRANSPOSE_LIBRARY'] = 'fftw'
config['parallelism']['GROUP_TRANSPOSES'] = 'True'
config['matrix construction']['STORE_EXPANDED_MATRICES'] = 'True'  # If memory allows
config['logging']['stdout_level'] = 'warning'  # Reduce I/O overhead

Debugging Setup

from dedalus.tools.config import config

# Detailed logging for debugging
config['logging']['stdout_level'] = 'debug'
config['logging']['nonroot_level'] = 'info'
config['logging']['file_level'] = 'debug'
config['logging']['filename'] = 'logs/debug'
config['profiling']['PROFILE_DEFAULT'] = 'True'

Memory-Constrained Setup

from dedalus.tools.config import config

# Reduce memory usage
config['matrix construction']['STORE_EXPANDED_MATRICES'] = 'False'
config['memory']['STORE_OUTPUTS'] = 'False'  # Warning: May slow down
config['analysis']['FILEHANDLER_PARALLEL_DEFAULT'] = 'gather'  # Less disk space

Environment Variables

Some settings are also controlled by environment variables:

# Disable threading (critical for performance!)
export OMP_NUM_THREADS=1
export NUMEXPR_MAX_THREADS=1

# MPI settings
export OMPI_MCA_mpi_warn_on_fork=0  # Suppress OpenMPI fork warnings

# HDF5 settings
export HDF5_USE_FILE_LOCKING=FALSE  # Disable file locking on some filesystems

See Performance Tips for more on environment configuration.

Checking Current Configuration

Inspect current configuration at runtime:

from dedalus.tools.config import config
import logging

logger = logging.getLogger(__name__)

# Print specific setting
logger.info(f"Transform library: {config['transforms']['DEFAULT_LIBRARY']}")
logger.info(f"Transpose library: {config['parallelism']['TRANSPOSE_LIBRARY']}")

# Print all settings in a section
for key, value in config['logging'].items():
    logger.info(f"{key} = {value}")

Get Started

Core Concepts

Advanced Topics

Examples

Configuration File Hierarchy

Getting the Default Configuration

Runtime Configuration

Configuration Sections

Logging

Transforms

FFTW-Specific Settings

Parallelism

FFTW Transposes

MPI Transposes

FFTW Transpose Settings

MPI Transpose Settings

Matrix Construction

Linear Algebra

Memory

Analysis

Profiling

Complete Configuration File

Common Configuration Patterns

High-Performance Setup

Debugging Setup

Memory-Constrained Setup

Environment Variables

Checking Current Configuration

See Also

Build docs developers (and LLMs) love

Get Started

Core Concepts

Advanced Topics

Examples

​Configuration File Hierarchy

​Getting the Default Configuration

​Runtime Configuration

​Configuration Sections

​Logging

​Transforms

​FFTW-Specific Settings

​Parallelism

FFTW Transposes

MPI Transposes

​FFTW Transpose Settings

​MPI Transpose Settings

​Matrix Construction

​Linear Algebra

​Memory

​Analysis

​Profiling

​Complete Configuration File

​Common Configuration Patterns

​High-Performance Setup

​Debugging Setup

​Memory-Constrained Setup

​Environment Variables

​Checking Current Configuration

​See Also

Build docs developers (and LLMs) love

Configuration File Hierarchy

Getting the Default Configuration

Runtime Configuration

Configuration Sections

Logging

Transforms

FFTW-Specific Settings

Parallelism

FFTW Transpose Settings

MPI Transpose Settings

Matrix Construction

Linear Algebra

Memory

Analysis

Profiling

Complete Configuration File

Common Configuration Patterns

High-Performance Setup

Debugging Setup

Memory-Constrained Setup

Environment Variables

Checking Current Configuration

See Also