User guide

Each part of Conatus described once, with the choices you make and the ones Conatus will not make for you.

The tutorials follow one problem from start to finish; this guide is organised by task. Every snippet runs against the current version of the library.

Writing a model

Writing a model

• Geometries
• Spherical shells
• Channels between two surfaces
• Equations
• Boundary conditions
• Ready problems
• Units and conventions

• Geometries: boxes, channels, disks, annuli, pipes, spheres, balls and shells, with their named boundaries.

• Channels between two surfaces: channels between two surfaces (wavy walls, bumps): the map, the chain rule, convergence and limits.

• Spherical shells: spherical shells: simulation on a CPU or a GPU, rotating convection, adjoints, and what Conatus checks for you.

• Equations: unknowns, parameters, known fields and equations as text; which terms are implicit.

• Boundary conditions: conditions by boundary name, how Conatus places them, and what it refuses.

• Ready problems: canonical flows ready to solve, each with its published reference.

• Units and conventions: unit systems and study presets; every conversion is a call.

Running

Running

• Simulations and time steppers
• Resolution
• GPU
• Diagnostics and visualization
• Particles and dye of a simulation
• Input and output
• The Studio
• Pilot a run from a script or an agent
• For AI agents
• Notebooks

• Simulations and time steppers: simulate, the schemes, start-up, choosing dt.

• Resolution: spectral tails per unknown and direction, and how many modes you need.

• GPU: the same model on a GPU, and what runs there.

• Diagnostics and visualization: vorticity, vortex criteria, particles, dye and mixing.

• Particles and dye of a simulation: tracers and a dye inside a simulation (sim.particles, m.dye, sim.dye).

• Input and output: snapshots and checkpoints in HDF5, and a run split over several jobs.

• The Studio: watch a run as a film from a browser or a phone, and control it.

• Pilot a run from a script or an agent: follow and pilot a run from a script or an AI agent (JSON, tokens, audit).

• For AI agents: what an AI agent reads first (AGENTS.md), and python -m conatus agent: the library’s facts and a dry run of a script, in JSON.

• Notebooks: rich display in Jupyter.

Dynamics

Dynamics

• Dynamics

• Dynamics: eigenvalues, non-modal growth, invariant solutions, continuation and bifurcations, Floquet and Lyapunov analysis, adjoints, symmetry subspaces.

Trust and provenance

Trust and provenance

• explain() and the Methods paragraph
• Numerical uncertainty
• The run registry
• Reproducibility and provenance
• Checking an installation
• Errors and what they mean
• Experimental features

• explain() and the Methods paragraph: explain() on every key object, and the Methods paragraph of your paper.

• Numerical uncertainty: a computed number with its error estimate, and the error of a time average.

• The run registry: record, query, compare and reproduce runs.

• Reproducibility and provenance: the provenance record and what is deterministic.

• Checking an installation: what your installation can run.

• Errors and what they mean: how to read an error message.

• Experimental features: what is shipped but not promised, and the warning that says so.

Coming from Dedalus

Coming from Dedalus

• Coming from Dedalus

• Coming from Dedalus: the same problem side by side, what you stop writing, and importing a Dedalus script.

Expert layer

Expert layer

• The expert layer
• IR and operators
• Bases and domains
• Tau terms by hand

• The expert layer: the explicit problem under every model, and when to write it yourself.

• IR and operators: fields, operators, problem classes, linearisation and adjoints.

• Bases and domains: bases, dealiasing, curvilinear domains and symmetry subspaces.

• Tau terms by hand: tau terms written by hand, and the rank report.