Gyredocs
Depth Practice
API

Gyre/Overview

Architecture at a glance

In one minuteA 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.

Written at L1 Essentials goes to L3 Mechanics 470 words Markdown

Gyre has three layers. The numerical core turns a state and a geometry into residuals and outputs, differentiably. The discipline adds solvers and exposes the contract an MDO framework expects. The service makes the discipline reachable — by HTTP, by pipeline, by agent — and serves the documentation you are reading.

Interfaces Discipline layer Numerical core (JAX) CLIgyre run / verify REST APIjobs · sessions · SSE MCPagent tools PipelinesYAML DAG · cache Documentationbuilt per revision CaseSpec → Casepresets · overrides · digest FlowDisciplinesolve · outputs · products Newton–KrylovFGMRES · p-multigrid Adjoint / errortotals · estimates Mesh + metricscurved quads/hexesdeformation Split-form DGSEMflux differencingSBP operators Physics kernelsEC fluxes · RiemannBR2 viscous · RANS (SA) Boundary conditionsadjoint consistent Functionalsforces · loadsfrom residual fluxes
Every interface reaches the numerical core through the same discipline layer.
  1. A case specification (CaseSpec: mesh generator or mesh file, flow conditions, discretization, solver controls, reference quantities) arrives as a preset name with overrides or as a full document. Its canonical JSON is hashed (for a mesh file, with the file’s contents in place of its name); the digest identifies the analysis in job, session and result records, and the service’s result cache is keyed by that JSON together with the requested gradients, error estimates and order selection, the contents of a mesh file and a fingerprint of the code.
  2. Case builds the curved mesh, or reads it from a file, the Discretization (operators, index tables, boundary conditions) and a FlowDiscipline.
  3. The discipline converges the flow with the Newton–Krylov solver, evaluates outputs, and on request solves adjoint or direct linear systems for derivatives and error estimates. With an order selection (adapt) this step is repeated at rising polynomial degree until the estimated error of one output meets a tolerance.
  4. The runner collects everything into one self-describing result record: outputs, convergence history, gradients, surface distributions, timings and provenance (version, commit, device).
Clients (tailnet) programsbrowsersAI agents API process (asyncio, CPU only) /api/v1 · /mcp · / (docs) job queue · result cache session registry · idle reaper metrics · optional bearer token never runs solver kernels job worker processone per job · own JAX runtime · CPU or GPU session processwarm compiled solver · command loop over a pipe on-disk storerequest · status · events · artefacts
Solver work is isolated in subprocesses; the API process stays responsive and device-free.
  • Jobs are one-shot analyses. Each runs in a fresh subprocess, so a crash or an out-of-memory condition cannot take the service down, the device is chosen per job, and cancelling is a process termination. Progress is appended to an event log and streamed as Server-Sent Events.
  • Sessions are long-lived solver processes for design loops: kernels stay compiled, every solve is warm-started from the last state, and derivative products are available between evaluations.
  • The store is plain files — inspectable, restart-safe, and the source of truth for the result cache. Mesh files that clients upload are kept in the same data directory, in the mesh store; a case refers to them by name, and no request makes the service open a path of its own choosing.

tools/deploy.py up refuses a port that is already served, builds this site from the working tree, stamps it with the commit, starts the service on all interfaces, and smoke-tests docs, API, a real solver job (which bypasses the result cache) and the MCP endpoint through the tailnet address. The footer of every page shows which deployment is serving it.

    ↑ ↓ moveEnter open[ ] change depthResults show section and depth level