Dedalus: symbolic spectral PDEs for people who study fluid dynamics

A spectral solver built by people who study fluids

Dedalus describes itself as a flexible framework for solving partial differential equations using modern spectral methods, and the repository says the code is open source and developed by a team of researchers studying astrophysical, geophysical and biological fluid dynamics. That provenance explains the shape of the tool. It is not a general purpose numerics library with a solver API, and it is not aimed at people who want a black box answer. It is aimed at someone with a differential equation in hand, a geometry in mind, and a need for solutions that stay accurate over many orders of magnitude. The listed developers are given by name on the project homepage, and the package is published on PyPI and tracked through a conda-forge feedstock, with the source itself written primarily in Python and the project documentation hosted on Read the Docs.

Writing the equation, not the operator matrix

The interface is the reason to look at this project. Instead of assembling a differentiation matrix and applying boundary conditions by hand, you enter equations symbolically and the framework handles the discretization. The README gives the incompressible hydrodynamics case in a ball as the example, and the whole model fits in four lines:

problem.add_equation("div(u) + tau_p = 0")
problem.add_equation("dt(u) - nu*lap(u) + grad(p) + lift(tau_u) = - u@grad(u)")
problem.add_equation("u(r=1) = 0")
problem.add_equation("integ(p) = 0")

The last two lines are the interesting part. The penultimate one states a boundary condition on the surface of the ball, and the final one fixes the pressure gauge so the solution is unique. The tau terms and the lift are the machinery the documentation dedicates its own pages to, describing a method for enforcing boundary conditions rather than using penalty terms. The multiplication written as u@grad(u) is a hint that the framework can act on products of fields, which is what makes a nonlinear term practical to write this way.

Sparse discretizations on balls, spheres, shells and disks

The numerical claim in the README is specific: the algorithms produce sparse and spectrally accurate discretizations of PDEs on simple domains, and the list of those domains is wide. Cartesian domains of any dimension are supported, along with disks, annuli, spheres, spherical shells and balls. The examples directory is the best evidence of what that means in practice, because it is a set of runnable cases rather than a claim. It contains an eigenvalue problem in a disk for pipe flow, a rotating convection case in a shell, a Lane-Emden problem on a ball, an ensemble of Rayleigh-Benard simulations in two dimensions, centrifugal convection in an annulus, internally heated convection in a ball, libration in a disk, shallow water on a sphere and convection in a shell, alongside one-dimensional cases such as the KdV-Burgers equation and a string wave problem. Two initial value problems and one boundary value problem are labelled as such in the example names, which suggests the examples deliberately cover the different problem classes rather than repeating one template.

Compiled solvers and automatic MPI parallelism

The systems that come out of the discretization are solved with compiled libraries, and the README states that they are automatically parallelized using MPI. That combination is what separates Dedalus from a research prototype: the equation you write symbolically is turned into a sparse linear system that is handed to compiled code, and the domain decomposition across processes happens without the user writing a parallel script. The build setup backs this up. The project is compiled with Cython, and the pyproject.toml lists the build requirements as:

requires = ["cython >= 3.0.5",
            "mpi4py >= 2.0.0",
            "numpy >= 1.20.0",
            "setuptools",
            "wheel"]

So a source install is not a pure Python install. You need a Cython toolchain, an MPI implementation, numpy and, at build time, FFTW, which the setup script treats as a separately located library rather than something it fetches.

How the setup script finds MPI and FFTW on your machine

The build script documents four environment variables, and the first two are the ones that matter when a library is installed somewhere unusual:

MPI_PATH
FFTW_PATH
FFTW_STATIC
CYTHON_PROFILE

MPI_PATH is described as the path to the MPI installation prefix and FFTW_PATH as the path to the FFTW installation prefix. The script also accepts the alternative names with a PREFIX suffix, so an environment can provide either form. If nothing is set, it falls back to searching a list of likely places, and that list is instructive about the systems the project expects:

places = [os.getenv("CONDA_PREFIX"),
          "/usr/lib/openmpi", # MPI under Ubuntu
          "/usr",
          "/usr/local",
          os.path.expanduser("~/build")]

A conda environment is checked first, then the common openmpi path on Ubuntu, then the system prefixes, and finally a build folder in the home directory. FFTW_STATIC is a binary flag for static linking and CYTHON_PROFILE a flag for enabling profiling inside the Cython modules, which is what you want when you are chasing performance rather than correctness.

Where Dedalus is the wrong tool

Several constraints come out of the build and the licence. The first is operational. Because the package needs MPI, FFTW and a Cython toolchain at build time, a machine without them cannot install it from source, and the documentation does not describe a pure Python fallback path or a wheel that bundles those libraries. The second is legal rather than technical, but it is concrete: the project is distributed under GPL-3.0, so embedding it in a product you distribute carries the obligations that licence implies, and the repository also ships a CITATION.cff file, which tells you the project expects academic citation as well. The third is scope. The documentation concentrates on incompressible flows with the tau method on geometric domains, and nothing in the project documentation describes adaptive mesh refinement, a GPU execution path, or a solver for an unstructured mesh. A project with a complicated geometry, or with a need to run on a machine that has no MPI, is outside what this framework is built to do.

Against writing your own finite difference solver

The realistic alternative is not another package but writing the solver yourself, which is what most numerical work starts with. In that approach you choose a grid, build the differentiation matrices yourself, apply boundary conditions as stencils at the edges, and assemble the linear system. You keep full control of the scheme and can match it to a textbook, but you also inherit the parts of the work that are pure plumbing: geometric grids on a sphere or an annulus, the awkwardness of a pressure gauge, and a parallel decomposition. Dedalus moves exactly that plumbing into the framework, and adds a domain library that covers the geometries fluid dynamics problems actually use. The cost of that move is a dependency on a compiled stack and on a framework's own conventions, including the tau and lift terms you have to learn in order to read its examples. The size of the codebase is the other tell: the repository has a dedalus package, a docs tree, an examples directory, a pyproject.toml and a setup.py, and it ships a CITATION.cff and a CONTRIBUTING.md, which is what a research software project looks like. On maintenance, the repository is not archived and the last push was on 2026-10-07, while the recent releases are v3.0.5 on 2026-01-21, v3.0.4 on 2025-09-04 and v3.0.3 on 2024-09-07, so the project sits in a 3.0.x line that is still receiving work in the 3.x series.

Editorial conclusion

Adopt Dedalus when you are a computational scientist who needs spectrally accurate solutions on a ball, sphere, shell, annulus or disk, and you want to write the equation rather than the operator matrix. Do not adopt it for a quick script on a laptop without an MPI toolchain, and do not plan to ship it inside a closed source product, because the project is licensed GPL-3.0. Before you commit, read the tau method and gauge condition pages linked from the project documentation, then confirm that the examples directory covers a problem close to yours and that the fftw and mpi libraries are where the setup script expects them, since it searches CONDA_PREFIX, /usr/lib/openmpi, /usr, /usr/local and a build directory in your home folder.

Frequently asked questions

Official sources

1. DedalusProject/dedalus on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases