Documentation
Documentation
The reference: each part of Conatus described once, with the choices you make and the ones it will not make for you. To learn, start with the Tutorials.
User guide
Writing a model
Geometries
A geometry says where the problem lives: its coordinates, which directions are periodic, where the walls are and what they are called.
Spherical shells
The space between two concentric spheres, where planets and stars convect: simulations on a CPU or a GPU, rotating convection, exact adjoints and optimal perturbations, with the same model text as in a box.
Channels between two surfaces
A channel whose walls are not flat: a wavy bottom, a bump, a corrugated lid.
Equations
A model is written as on paper: unknowns, parameters, known fields and equations in text, with terms on whichever side you like.
Boundary conditions
Conditions are declared by boundary name, as on paper; Conatus decides how each one enters the discrete system and prints that decision.
Ready problems
cn.problems gives the canonical flows and model equations ready to solve, each validated against a published value.
Units and conventions
Unit systems make every change of nondimensionalisation an explicit, checked call.
User guide
Running
Simulations and time steppers
A model with dt(...) is integrated by m.simulate(...), with the resolution, the scheme and the time step written in the call.
Resolution
The resolution report says, for each unknown and each direction, whether the spectral coefficients have decayed, and how many modes a target accuracy would need.
GPU
The same model runs on an NVIDIA GPU by adding backend="cuda"; the arithmetic is double precision, as on the CPU.
Diagnostics and visualization
Eulerian, Lagrangian and mixing diagnostics computed from the fields of a run, on the CPU or the GPU.
Particles and dye of a simulation
Tracer particles and a numerical dye that live inside a native simulation: they advance with each step of sim.run, on the CPU or the GPU, and write files in the cn.io layout.
Input and output
Two kinds of HDF5 files: analysis files, which hold what you asked to see (fields, derived quantities, numbers) at a fixed cadence, and checkpoints, which hold everything needed to continue a run exactly.
The Studio
The Studio shows a running simulation as a film, from a browser or a phone, and lets you pause, checkpoint, stop or fork it; watching never changes a bit of the computation.
Pilot a run from a script or an agent
Everything the Studio shows about a run, a script can read as JSON, and the commands of the Controls sheet, a script can send (experimental, like the Studio: experimental).
For AI agents
What an AI coding agent reads before using Conatus, and the JSON interface it uses while it works.
Notebooks
In Jupyter, Conatus objects display as formatted tables and cards.
User guide
Dynamics
Eigenvalues and stability
Normal modes of a linear problem, each with its backward residual, with spurious modes removed only by a declared test.
Onset of convection
The critical Rayleigh number of Rayleigh–Bénard convection between no-slip walls, and the shape of its mode, in a few calls: from the ready linearization, then from the equations of a normal mode written by hand.
Non-modal analysis
Transient growth of a linear operator, measured in the kinetic-energy norm.
Invariant solutions
Equilibria, travelling waves and periodic orbits found by Newton–Krylov–hookstep on the flow map of your own time stepper.
Continuation and bifurcations
Branches of solutions followed through folds by pseudo-arclength, with branch points, Hopf points, cycles and codimension-two curves located on the way.
Floquet analysis
Stability of time-periodic flows by the Hill method: the Floquet exponents are eigenvalues of one large, structured problem.
Eigenvalues in a region
Every eigenvalue inside a box of the complex plane, with a count you can trust: how many there are, and which they are.
Chaos and ensembles
Lyapunov exponents with error bars, covariant Lyapunov vectors, Poincaré maps, and the fate of many trajectories integrated as one batch.
Invariant manifolds and slices
The unstable manifold of an equilibrium as a polynomial parametrization, connections between solutions, and the reduction of a continuous symmetry by a slice.
Symmetry subspaces
Computing in an invariant subspace of a symmetry group: fewer unknowns and isolated solutions, at the price of hiding what breaks the symmetry.
Adjoints and sensitivity
Exact tangent and adjoint of the discrete time stepper, adjoint eigenmodes in a declared inner product, the wavemaker and the sensitivity to the base flow.
Tangent, adjoint and optimal perturbations
FlowMap is the time-stepping map of a solver, X_0 ↦ X_N, with its exact discrete tangent (jvp) and adjoint (vjp): the same schemes, the same operators, the same linear factorizations, transposed.
Data-driven analysis
Dynamic mode decomposition and spectral proper orthogonal decomposition of snapshots, in the inner product of the physics rather than that of the array.
User guide
Trust and provenance
explain() and the Methods paragraph
Every key object says, in plain text, what it is and which numerical choices it carries, and a simulation writes the Methods paragraph of your paper from what it actually ran.
Numerical uncertainty
A number computed by a simulation (a growth rate, a mean, a value at a point) depends on the resolution and on the time step.
The run registry
cn.runs records the computations you may want to find, compare, cite or re-run later, with their numerics, code and machine.
Reproducibility and provenance
A number is only useful if you can say which code, which numerics and which machine produced it; Conatus records this when the computation runs, not afterwards.
Checking an installation
python -m conatus doctor says what your machine can run (compiled core, GPU) and, for anything missing, what to do.
Errors and what they mean
Every error says what is wrong, where, why it is refused, and what to write instead.
Experimental features
Most of Conatus is supported: its API changes only through a declared deprecation, and what the guide says about it is measured.
User guide
Expert layer
The expert layer
Under every native model there is an explicit problem that you can read, modify or write yourself: bases with their sizes, tau terms, the left and right sides of each equation.
IR and operators
The expert layer writes problems with Python objects: fields, parameters and operators that build an exact symbolic expression.
Bases and domains
In the expert layer a domain is a coordinate system with one spectral basis per coordinate, each with its size and dealiasing factor.
Tau terms by hand
In the expert layer you place the boundary terms yourself; a rank check refuses an ill-posed system before any factorisation.