# Gyre

> Gyre is a differentiable, high-order computational fluid dynamics capability: the flow discipline that a multidisciplinary design optimization framework wraps.

Documentation of gyre 0.4.0 (revision ceb1f4b0be). Every page is available as Markdown at the paths below (math in LaTeX). The Markdown is expanded: generated reference tables, verification results and chart data are written out as text and tables, each with the exact commit, date and device of the run that produced it and a note when that revision is not the one this site was built from. Pages are written at four depth levels: L1 Essentials (what it is and why it matters); L2 Practice (how to use it); L3 Mechanics (how it works: algorithms and architecture); L4 Theory (derivations, proofs and numerical analysis). The level after each title is the page's base level; passages at another level start with [LN Name].

Machine-readable indexes: [site-manifest.json](site-manifest.json), [search-index.json](search-index.json), [llms-full.txt](llms-full.txt); verification records: data/verification/<study-id>.json (study ids under verification.studies in the manifest). The service API is described at /api/docs (OpenAPI: /api/openapi.json).

## Overview

- [Overview](overview/index.md) (L1): What Gyre is, where it sits in a design-optimization stack, how it is put together, and what it does not do.
- [What Gyre is](overview/what-is-gyre.md) (L1): Gyre is a differentiable high-order flow solver delivered as a service. It gives a design-optimization framework what it needs from an aerodynamics discipline — converged flows, outputs, coupling fields and exact derivatives — and deliberately nothing more.
- [Architecture at a glance](overview/architecture.md) (L1): A case specification flows through one pipeline — mesh, discretization, discipline — that every interface shares. The service wraps that pipeline in isolated worker processes and exposes it to programs, people and agents.
- [Capabilities and limits](overview/capabilities-and-limits.md) (L1): What Gyre does, how well each part is verified, and what it does not do yet. Read this before planning work on top of it.

## User Guide

- [User Guide](guide/index.md) (L2): How to install Gyre, describe a case, bring your own mesh, run it from the command line, the service or Python, obtain gradients and error estimates, wire it into an MDO framework or an agent, and deploy it.
- [Getting started](guide/getting-started.md) (L1): Install Gyre, run a preset from the command line, read the result, and start the service. The first solve of the first preset takes about a minute on a four-core CPU, most of it compilation.
- [Cases](guide/cases.md) (L2): A case specification is one document describing mesh, flow conditions, discretization, solver controls and reference quantities. Presets cover common configurations; dotted-path overrides adapt them; the same document works in the CLI, the API, pipelines and agent tools.
- [Mesh files](guide/meshes.md) (L2): A case can take its mesh from a file instead of a built-in generator: Gmsh MSH 2.2 or 4.1 (ASCII) with quadrilaterals or hexahedra, or Gyre's own NPZ arrays. This page shows how to produce such a file, how its boundary groups become boundary conditions, what the reader checks, and how a mesh reaches a service.
- [Service API](guide/service.md) (L2): The REST API offers two ways to compute — batch jobs for one-off analyses and warm sessions for design loops — plus a mesh store for uploaded mesh files, case validation, progress streams, artefacts and metrics. Responses are JSON, except /metrics (Prometheus text), artefact downloads and the ?stream=true event stream; every error carries a type, a message and a hint.
- [Gradients and error estimates](guide/gradients.md) (L2): Request total derivatives of any scalar output with respect to flow parameters and surface shape from the CLI, a job, a session or Python. One adjoint solve per output; an adjoint-based error estimate costs one more linear solve.
- [Integrating with an MDO framework](guide/mdo-integration.md) (L2): Gyre presents itself as an implicit discipline — inputs, a state, a residual, outputs — with exact matrix-free derivative products. This page maps that contract onto the concepts MDO frameworks use and shows the three ways to connect.
- [Agent interface (MCP)](guide/agents.md) (L2): Gyre exposes its capabilities to AI agents through the Model Context Protocol. An agent can discover cases, upload meshes, run analyses, let the solver choose the polynomial degree for a target accuracy, obtain exact gradients and error estimates, and read this documentation — through tools designed to be self-correcting.
- [Pipelines](guide/pipelines.md) (L2): Chain analyses into reproducible workflows with a small YAML vocabulary. Stages are cached by content, so re-running a pipeline recomputes only what changed.
- [Deployment](guide/deployment.md) (L2): A deployment is one process tree serving the API, the agent endpoint and the documentation for its own revision, bound to all interfaces so that tailnet machines can reach it. Deploy natively, as a container, or under systemd.
- [Python API](guide/python-api.md) (L2): Use Gyre as a library — build a case, drive the discipline, access the discretization and its differentiable kernels directly.
- [Troubleshooting](guide/troubleshooting.md) (L1): What to do when a solve does not converge — every reason the solver can report, what it means and which control to change — and the first-run and service symptoms most often met.

## Examples

- [Examples](examples/index.md) (L1): Worked cases with real output: an inviscid aerofoil, a transonic flow with shocks, a separated viscous flow, a turbulent boundary layer, a sphere in three dimensions, a case on a mesh imported from Gmsh, a warm-started polar with adjoint slopes, a coupled aero-structural adjoint, OpenMDAO, and an agent session.
- [Inviscid aerofoil](examples/naca0012-euler.md) (L1): The complete loop on one case — solve the flow over a NACA 0012, inspect the field and the surface pressure, obtain adjoint derivatives with respect to flow conditions and shape, and estimate the error of the result.
- [Transonic aerofoil](examples/transonic.md) (L2): A flow with shocks — NACA 0012 at Mach 0.8 — computed with sensor-based shock capturing, converged to machine precision, with adjoint derivatives taken through the shock.
- [Laminar cylinder](examples/cylinder-re40.md) (L1): A viscous case with separation — the steady wake of a circular cylinder at Reynolds number 40 — showing no-slip walls, skin friction and the separation point.
- [Turbulent flat plate](examples/turbulent-flat-plate.md) (L1): A Reynolds-averaged case with the Spalart–Allmaras model — the zero-pressure-gradient flat plate at a Reynolds number of five million — showing how a turbulent case is specified, what its boundary layer looks like in wall units, and that its drag can be differentiated like any other output.
- [Sphere in three dimensions](examples/sphere.md) (L1): Flow past a sphere on an unstructured mesh of curved hexahedra, inviscid and at Reynolds number 100. The same commands, outputs and derivatives as in two dimensions, with three force and three moment coefficients and a sideslip angle.
- [A mesh from Gmsh](examples/imported-mesh.md) (L1): Laminar flow past a cylinder in a channel on an unstructured mesh of cubic quadrilaterals written by Gmsh — set up from the mesh's physical groups, solved in Python and through the service, with an adjoint derivative checked against finite differences.
- [Lift polar with adjoint slopes](examples/lift-polar.md) (L2): A parameter sweep in one warm solver process, with the lift-curve slope from one adjoint solve at every point. Demonstrates warm starts and the consistency of gradients along a path.
- [Coupled aero-structural adjoint](examples/aerostructural-coupling.md) (L2): A flow coupled to an elastic skin, with the coupled derivative assembled outside Gyre from loads, displacements and reverse total products — the pattern an MDO framework uses, in sixty lines.
- [Inside OpenMDAO](examples/openmdao.md) (L2): Wrap the flow discipline as a matrix-free OpenMDAO component, in reduced space or at residual level, and let the framework assemble total derivatives in forward or reverse mode. No optimizer involved.
- [An agent at work](examples/agent-session.md) (L2): The Model Context Protocol exchange behind an agent task — "characterise this aerofoil and tell me how far to trust the drag" — shown as the raw tool calls and results.
- [A remote session called at fixed design points](examples/remote-session.md) (L2): The calls an optimizer or MDO framework running on another machine would make on a warm session of a deployment — evaluate, gradients, adjoint and tangent products, a finite-difference cross-check, checkpoint and restore — shown at three fixed design points, with no optimizer.

## Verification

- [Verification](verification/index.md) (L1): Every numerical claim in this documentation is backed by an executable study. The studies run as a pipeline, write machine-readable results with provenance, and the charts and tables on these pages are rendered from those files.
- [Discrete invariants](verification/discrete-invariants.md) (L2): Summation by parts, free-stream preservation, conservation and entropy conservation are algebraic identities of the scheme. They hold to round-off, in two and three dimensions, on curved meshes.
- [Order of accuracy](verification/order-of-accuracy.md) (L2): Convergence studies with exact solutions. The design rate p + 1 is required where it is established (the advected density wave, steady manufactured solutions on Cartesian meshes, heat conduction, convection-dominated flow); elsewhere the guaranteed rate p is required and the observed rate is reported.
- [Linearisation and gradients](verification/derivatives.md) (L2): Jacobian products, preconditioner blocks, adjoint and direct total derivatives are verified against finite differences, against each other and against dense reference Jacobians. Agreement with finite differences is limited by finite-difference accuracy; adjoint and direct mode agree to the tolerance of their linear solves.
- [Solver convergence](verification/solvers.md) (L2): The pseudo-transient Newton–Krylov solver reduces the residual by ten orders from a free stream; its terminal convergence is linear at the forcing rate of the inexact Newton iteration, and p-multigrid preconditioning cuts the Krylov iteration count compared with block Jacobi alone. What those iterations cost is measured and reported without a threshold: operator applications counted from the cycle, and the wall time of each solve repeated with compiled kernels.
- [Three-dimensional flows](verification/three-dimensional.md) (L2): Flow past a sphere on an unstructured cubed-sphere mesh of curved hexahedra tests the 3-D path on a genuinely three-dimensional flow, inviscid against exact properties and laminar against accepted data, with adjoint derivatives of all six force and moment coefficients; a spanwise extrusion of the aerofoil case must reproduce the two-dimensional solution.
- [Turbulence closure](verification/turbulence.md) (L2): The Spalart–Allmaras RANS closure is verified in four steps: a manufactured solution for the order of accuracy of the coupled system, exactness of its linearisation including the wall distance, the turbulent flat plate of the NASA Turbulence Modeling Resource for the model itself, and adjoint derivatives against finite differences.
- [Discipline contract](verification/discipline-contract.md) (L2): The interface a multidisciplinary framework integrates against is itself verified. Forward and reverse products are exact transposes, the linear solves invert them, the products agree with finite differences at the solution and at a point the framework names, a stalled linear solve is never silent, and the OpenMDAO implicit component passes OpenMDAO's own derivative checks.
- [Output error estimation](verification/output-error.md) (L2): The adjoint-weighted-residual estimate predicts the change of an output between polynomial degree p and p + 1 from a single linear solve. Its effectivity is measured against the actually converged p + 1 solution.
- [Order selection](verification/order-selection.md) (L2): Output-driven order selection raises the polynomial degree until the estimated error of an output meets a tolerance. The study checks the selection rule itself, compares the estimate with solutions two degrees higher, and cross-checks every continued level against an independent solve.
- [Imported meshes](verification/imported-meshes.md) (L2): A mesh read from a Gmsh or NPZ file must behave exactly like a generated one. The study reads genuine Gmsh files, tests the node-ordering tables, the operator identities on unstructured curved meshes in 2-D and 3-D, and solves a flow with an adjoint derivative on an imported mesh.
- [Physical validation](verification/validation.md) (L2): A canonical viscous flow — the steady wake of a circular cylinder at Reynolds number 40 — is compared with the literature as a plausibility check on the physics, boundary conditions and force evaluation.

## Software Engineering

- [Software Engineering](engineering/index.md) (L1): How the capability is built: design decisions and their costs, the differentiable-programming patterns the solver relies on, code structure, the service architecture, testing, pipelines and provenance, performance, and process.
- [Design decisions](engineering/design-decisions.md) (L2): The handful of decisions that shape everything else — JAX as the kernel language, split-form DGSEM, geometry as differentiable data, split-argument residuals, one execution path, isolated worker processes — with the alternatives that were rejected.
- [Differentiable programming patterns](engineering/differentiable-programming.md) (L2): How the solver is structured so that automatic differentiation yields exact, efficient linearisations — the handful of JAX patterns the code relies on, and the pitfalls each one avoids.
- [Service architecture](engineering/service-architecture.md) (L2): The service is an asyncio API process that owns no numerical state, plus solver subprocesses of two kinds — one-shot job workers and long-lived sessions — over a file-based store that also holds the meshes clients upload. This page describes lifecycles, failure handling, caching and security.
- [Code structure](engineering/code-structure.md) (L2): A map of the package — which module owns which concept, how data is laid out in memory, and the conventions that the numerical kernels, the solver and the service share.
- [Testing strategy](engineering/testing-strategy.md) (L2): Tests are layered by what they can prove — algebraic invariants, exact derivative identities, end-to-end behaviour with real processes — and by cost. Verification studies sit above them as slower, reported evidence.
- [Pipelines and provenance](engineering/pipelines-and-provenance.md) (L2): Analyses, verification, documentation builds and deployment are stages of declarative pipelines. Stages are cached by content, run in isolation, and leave a provenance record — which is how every number in the documentation can be traced to a revision.
- [Performance](engineering/performance.md) (L2): Measured kernel throughput on CPU and GPU, the cost of derivatives relative to a residual evaluation, and where time goes in practice — compilation for small problems, Krylov iterations for large ones.
- [Development process](engineering/development-process.md) (L2): How the project is organised for contributors — human or agent: the roadmap as hand-off state, the effort ledger, commit and verification discipline, and the conventions that keep four interfaces consistent.
- [Effort ledger](engineering/effort-ledger.md) (L1): How the development time was split between core capability, verification and logistics: the measured numbers, how they are measured, and how far they can be trusted. The split does not meet the 70 / 25 / 10 target cleanly, and a large part of the record is an estimate.

## Mathematics & Numerical Methods

- [Mathematics & Numerical Methods](theory/index.md) (L1): The equations Gyre solves and the numerical methods it uses — split-form DG spectral elements, entropy-conservative fluxes, curvilinear metrics, BR2 viscous terms, the Spalart–Allmaras turbulence closure, shock capturing, the implicit solver, adjoints and output error estimation — with derivations.
- [Governing equations](theory/governing-equations.md) (L2): Gyre solves the compressible Euler and Navier–Stokes equations in conservation form, non-dimensionalised by the free stream, and uses their entropy structure as the organising principle of the discretization.
- [Split-form DG spectral elements](theory/dgsem.md) (L2): Space is discretized by a nodal discontinuous Galerkin spectral element method on Gauss–Lobatto points. Its derivative operator satisfies summation by parts, which lets the volume terms be written as differences of symmetric two-point fluxes and gives discrete conservation and entropy statements on curved meshes.
- [Two-point and interface fluxes](theory/two-point-fluxes.md) (L2): The volume terms use symmetric two-point fluxes that conserve entropy exactly; dissipation is added only at element interfaces through an upwind flux. A discrete entropy inequality is proven for the two interface fluxes built on the entropy-conservative flux (es_roe with matrix dissipation, llf with scalar dissipation); for the classical Roe flux, which is the default, and for HLLC entropy decay is measured, not proven.
- [Curvilinear elements and metric terms](theory/curvilinear-metrics.md) (L2): Elements are curved with the same polynomial technology as the solution. Metric terms are computed so that a uniform flow stays exactly uniform on any mesh, and they are evaluated inside the differentiated code so that shape derivatives come for free.
- [Viscous terms — the BR2 scheme](theory/viscous-br2.md) (L3): Viscous fluxes use the second scheme of Bassi and Rebay with lifting operators evaluated on Gauss–Lobatto nodes. The discretization is compact (face neighbours only) and symmetric, which the implicit solver and the adjoint both rely on.
- [Boundary conditions](theory/boundary-conditions.md) (L2): Boundary conditions are imposed weakly through the same numerical fluxes as interior faces. Walls use a boundary state rather than a ghost-cell Riemann problem, which keeps force functionals adjoint consistent.
- [Implicit solver](theory/implicit-solver.md) (L2): Steady states are found by pseudo-transient Newton–Krylov iteration. The Jacobian is never formed — its action comes from automatic differentiation — and it is preconditioned by p-multigrid with element-block-Jacobi smoothing whose blocks are also obtained by AD.
- [Adjoints and sensitivities](theory/adjoint-and-sensitivities.md) (L2): Gyre computes exact derivatives of outputs with respect to flow parameters and surface shape with one transposed linear solve per output. All partial derivatives come from automatic differentiation of the discrete operators, so gradients are consistent with the solver to solver tolerance.
- [Output error estimation](theory/error-estimation.md) (L3): The adjoint that provides gradients also measures how much each element's unresolved residual contaminates an output. One extra linear solve yields an error estimate, a corrected output and per-element indicators.
- [Shock capturing](theory/shock-capturing.md) (L2): Flows with shocks are stabilised by an artificial viscosity that a smoothness sensor switches on only in the elements containing a shock. The term lives inside the differentiated residual, so Newton convergence and adjoint derivatives stay exact.
- [Turbulence closure (RANS, Spalart–Allmaras)](theory/turbulence-model.md) (L2): Turbulent flows are computed with the Reynolds-averaged equations closed by the negative Spalart–Allmaras model. The model equation is one more row of the same discrete operator, so the Newton linearisation, the adjoint and the shape derivatives (including the wall distance) remain exact.
- [Outputs and functionals](theory/outputs-and-functionals.md) (L2): The definition, sign convention, normalisation and units of every output name a result can contain — force and moment coefficients, heat, the volume diagnostics, the surface load field and the surface distributions.

## Reference

- [Reference](reference/index.md) (L2): Lookup material generated from the code — case schema, command line, REST routes, agent tools — plus glossary, bibliography and the authoring guide for this site.
- [Case schema](reference/case-schema.md) (L2): Every field of the case specification with its type, default and, where the model carries one, a description — generated from the pydantic model that validates it. Fields whose description cell is empty are explained in the Cases guide.
- [Command-line reference](reference/cli.md) (L2): Every `gyre` sub-command with its options, generated from the program itself.
- [REST API reference](reference/rest-api.md) (L2): All endpoints of the service, generated from its OpenAPI description. The live, interactive version is served by every deployment at /api/docs.
- [MCP tool reference](reference/mcp-tools.md) (L2): The tools, resources and prompts the agent interface exposes, generated from the server definition.
- [Glossary](reference/glossary.md) (L1): Short definitions of the terms used across this documentation, with pointers to where each is explained.
- [Bibliography](reference/bibliography.md) (L2): The literature Gyre's methods come from, grouped by topic.
- [Authoring guide](reference/authoring.md) (L2): How to write pages for this site: front matter, the four depth levels, callouts, mathematics, code, tabs, charts, tables, status badges, the field viewer and diagrams. Every feature is shown live on this page.