🌀 Conatus

Spectral PDEs and dynamical systems, from equations written as on paper.

Write the geometry, the unknowns and the equations as text. Conatus builds the spectral discretisation, then lets you simulate the model or take apart its dynamics.

Website · Tutorials · Install

Kelvin-Helmholtz billows rolling up in a shear layer, with a passive dye, computed with Conatus (web/gallery/kelvin_helmholtz.py; the linear stability of the same layer: examples/shear/kelvin_helmholtz.py).

What it does

You describe a problem the way you would on a blackboard. Conatus picks the bases, places the boundary conditions, splits implicit and explicit terms, and then tells you what it did: explain() prints every numerical choice, so nothing happens behind your back.

From one model you can:

• 🌊 Simulate it in time, on CPU or on an NVIDIA GPU (beta).
• 📈 Find its eigenvalues, each with its residual, adjoint modes, and a check that a finer resolution finds the same mode again.
• ⚡ Measure non-modal growth: optimal perturbations and transient amplification.
• 🔁 Study periodic problems with Floquet and Hill spectra.
• 🎯 Converge invariant solutions (equilibria, periodic orbits) with Newton-Krylov.
• 🧭 Follow branches with continuation and locate bifurcations.
• 🌪️ Quantify chaos with Lyapunov spectra and covariant vectors.

📐 Stability: where does convection start?

Rayleigh-Bénard onset between rigid plates. The normal-mode problem, written as on paper (from tutorial 0):

import conatus as cn
from conatus.expert import critical

onset = cn.Model(cn.Box(z=cn.walls(-0.5, 0.5)), name="convection onset", Ra=1700.0, k=3.1, Pr=1)
onset.scalar("w"), onset.scalar("theta")       # w(z), theta(z) times exp(i k x + s t)
onset.eigenvalue("s", growth="real")
onset.define("L(f) = dz(dz(f)) - k**2*f")
onset.equations("""
    momentum: s*L(w) = Pr*L(L(w)) - Pr*Ra*k**2*theta
    heat:     s*theta = w + L(theta)
""")
onset.at("walls", "w = 0", "dz(w) = 0", "theta = 0")

P = onset.parametric(N=32, over=("Ra", "k"), drift=48, drift_tol=1e-6)   # modes confirmed at N=48
crit = critical(P, "Ra", bracket=(1500, 2000), over={"k": (2.8, 3.4)}, xtol=1e-9)
print(f"Ra_c = {crit.value:.4f}   k_c = {crit.over['k']:.5f}")

Ra_c = 1707.7618   k_c = 3.11632

The classical value (Reid & Harris, 1958) is Ra_c = 1707.762 at k_c = 3.117.

🌡️ Simulation: the same convection, in time

import numpy as np
import conatus as cn

box = cn.Box(x=cn.periodic(2.0), z=cn.walls(-0.5, 0.5))
m = cn.Model(box, name="Rayleigh-Benard 2D", Ra=2500, Pr=1)
u, p, T = m.velocity("u"), m.pressure("p"), m.scalar("T")
m.equations("""
    momentum:   dt(u) + grad(p) - Pr*lap(u) = Pr*Ra*T*ez - u·grad(u)
    continuity: div(u) = 0
    heat:       dt(T) - lap(T) = -u·grad(T)
""")
m.at("bottom", u=0, T=+0.5)
m.at("top", u=0, T=-0.5)

sim = m.simulate(N=(32, 24), scheme="RK443", dt=5e-4)    # backend="cuda" on a GPU (beta)
sim.initial(T=lambda x, z: -z + 1e-6 * np.cos(np.pi * x) * np.cos(np.pi * z))
sim.run(until=0.8)
print(sim.explain())

The small perturbation grows at the rate of the leading eigenvalue of the linearised model (σ = 5.5425 at Ra = 2500), then saturates into rolls that carry the same heat flux through both plates.

📦 Install

pip install conatus==0.1.1   # CPU wheel, compiled core included, no compiler needed
python -m conatus doctor     # what this machine can run, and what is missing

GPU (beta). For an NVIDIA A100 or L40S class card with a driver that supports CUDA 12.9. The CUDA wheel is not on PyPI: it is attached to the v0.1.1 release, one per Python; for CPython 3.12, with CuPy:

pip install "conatus[gpu] @ https://github.com/rubendahan/conatus/releases/download/v0.1.1/conatus-0.1.1+cu12-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl"
python -m conatus doctor                                      # says whether the CUDA core sees a GPU

From source. pip install . with LAPACK and BLAS available. Details on the install page.

🎬 Studio and AI agents (experimental)

Watch a run live in your browser: declare what to show with sim.watch("my_run", film={"T": cn.view("T")}), then start the local Studio, which reads the same spool directory:

pip install "conatus[studio]"
python -m conatus.studio.hub serve --local --port 8765   # open http://localhost:8765/login

The one-session login token goes to a private file whose path is printed. On a cluster, run it in a batch job and open an ssh tunnel (see the Studio guide).

For AI coding agents, python -m conatus agent answers in JSON (versions, devices, the names of the API), python -m conatus agent check run.py dry-runs a script, and AGENTS.md is the page to give them.

📚 Learn more

• The website has the tutorials, the user guide, the API reference and the maths behind each method.
• examples/ holds ready-to-run cases: convection, shear flows, patterns, bifurcations.

⚠️ Good to know

• CPU speed. The CPU path is a NumPy reference implementation. It is great for eigenvalue problems, small grids and setting a run up, but slower than established CPU codes on large grids. The speed comes from the GPU path, which is still in beta.
• One GPU. 0.1.1 runs a simulation on one CPU process or one GPU. No multi-GPU or MPI yet.
• Young API. The 0.1 interface can still change. Any change comes with a deprecation warning and a line in the changelog.

📄 License

BSD-3-Clause, see LICENSE. Bundled third-party components and their licences are listed in THIRD_PARTY_NOTICES.md, with the full texts in licenses/. To cite Conatus, see CITATION.cff.

Made by Ruben Dahan.