Getting started

Install#

bash

git clone <repository> gyre && cd gyre
make bootstrap          # creates .venv with uv

The commands on this page call the program by its path, .venv/bin/gyre. After source .venv/bin/activate plain gyre works too.

scripts/bootstrap.sh detects two host properties and adapts: CPUs without AVX2 get jax < 0.12 (newer wheels abort at import on such processors), and hosts with an NVIDIA GPU get the CUDA-enabled JAX build.

Python 3.11 or newer, a C toolchain is not needed. Dependencies: JAX, NumPy, SciPy, pydantic, PyYAML; for the service FastAPI, uvicorn, httpx, sse-starlette and the MCP SDK (2.0 or newer); for the documentation Jinja2, Markdown and Pygments; for the OpenMDAO adapter OpenMDAO (extra mdo). Everything is declared in pyproject.toml (pip install -e ".[all]" works too; all includes the mdo extra).

Run a case#

bash

.venv/bin/gyre presets
.venv/bin/gyre run naca0012_euler -o runs/first

text

case naca0012_euler [e418…]: 256 elements, p = 2, 9216 DOF, levels [2, 1, 0]
  step   0  |R| = 3.663e-01  CFL = 5.0e+00  krylov =   2
  …
  step  15  |R| = 4.569e-11  CFL = 4.6e+07  krylov =  14
{
  "converged": true,
  "outputs": {"cd": 0.000949, "cl": 0.278767, "cm": -0.002021, …}
}

The first run of a new mesh size or polynomial degree compiles its kernels, and nothing is printed while that happens: after the case … line the program is silent until step 0. A persistent cache (~/.cache/gyre/jit) shortens later runs of the same configuration.

`gyre run naca0012_euler -o DIR`	Wall time	of which `timing.solve`
first run, empty compilation cache	51 s	40 s
second run, cache filled	27 s	20 s
a later run on the same machine under heavy load (load average 32 to 39 on four cores), cache state not controlled	386 s	351 s

Measured once each on a four-core Intel i7-3770K (no AVX2, 16 GB), CPU device, with the working tree that followed revision 5ee1cdc. The load of the machine was not recorded for the first run; the second ran while the machine was shared with other work (load average about 4). The third row shows how much the time depends on what else the machine is doing: the same command took more than six minutes while about nine times as many processes as cores were runnable. Read the first two rows as what a mostly free machine of this class gives, not as a guarantee. timing.solve includes the compilation that happens inside the solve.

File	Content
`result.json`	spec, outputs, convergence history, surface $c_p$ , timings, provenance
`solution.npz`	checkpoint of the state with the spec that produced it
`flow.vtu`	sub-sampled solution for ParaView/VisIt
`field.json`	compact field sample for the browser viewer

Overrides are dotted paths into the case specification:

bash

.venv/bin/gyre run naca0012_euler --set flow.mach=0.6 --set flow.alpha_deg=1.5 \
                                  --set discretization.order=3 --set mesh.params.n_surf=48
.venv/bin/gyre run my_case.yaml       # or a full specification file
.venv/bin/gyre schema                 # every field, with types and defaults

See Cases.

Gradients and error estimates#

bash

.venv/bin/gyre run naca0012_euler --gradients --of cl,cd --wrt alpha,mach --error cd

adds total derivatives from the discrete adjoint and an adjoint-based estimate of the discretization error of cd (details).

alpha is the angle of attack in radians, so --wrt alpha gives derivatives per radian. --wrt alpha_deg gives the same derivative per degree (smaller by the factor π/180 ≈ 1/57.3) under the name alpha_deg. The case field flow.alpha_deg is always in degrees. What cl, cd, cm and the other outputs mean is defined under Outputs and functionals.

bash

.venv/bin/gyre run bump_euler --set discretization.order=1 --target-error cd=1e-4 --max-order 4

--target-error OUTPUT=TOL raises the polynomial degree, starting at the case’s order, until the estimated error of OUTPUT is at most TOL (absolute) or --max-order (default 5) is reached. One line is printed per degree tried (-q suppresses them):

text

order P: N DOF, OUTPUT = value, estimated error E (target TOL)
order P: N DOF, did not converge (reason)

The second form is the line of a degree whose solve did not converge; the selection ends there, with the last degree that converged as its result. The tolerance counts as met only by a finite estimate whose adjoint solve converged. The fields of adaptation and of its level records are described under Service.

The JSON summary gains adaptation (output, tolerance, met, order, value, corrected, error, and per degree order, degrees_of_freedom, converged, error); outputs, gradients and artefacts are those of the final degree, and result.json (with -o) has the complete level records. The exit status is 0 if the tolerance was met, 3 if the solve converged but the tolerance was not met at --max-order, 2 if the solve did not converge. A request that cannot work (a tolerance that is not a positive number, --max-order without --target-error, below 1 or below the case’s order, an unknown output) ends with a message and status 1 before any flow is solved.

Your own mesh#

bash

.venv/bin/gyre mesh info my_mesh.msh  # is the file usable? which boundary groups?
.venv/bin/gyre run my_case.yaml       # mesh: {generator: file, params: {path: my_mesh.msh}}

A case can read a Gmsh mesh of quadrilaterals or hexahedra instead of using a generator; see Mesh files and the worked example.

Start the service#

bash

make deploy        # builds the docs for this revision, starts the service, smoke-tests it
# or, without the deployment record:
.venv/bin/gyre serve --host 0.0.0.0 --port 8600

Then, from any machine on the tailnet:


documentation	`http://HOST:8600/`
API explorer	`http://HOST:8600/api/docs`
deployment identity	`http://HOST:8600/api/v1/info`
agents (MCP)	`http://HOST:8600/mcp`

Troubleshooting — when a solve does not converge, and first-run problems.
Mesh files — geometries beyond the built-in generators.
examples/quickstart.py — the same first run from Python, with gradients and an error estimate (.venv/bin/python examples/quickstart.py).
Service API — jobs and warm sessions over HTTP.
MDO integration — the discipline contract.
Agent interface — driving Gyre from an AI agent.
Examples — worked cases.

GYRE_DEVICE=cpu|gpu|auto selects the device for a process (default auto: GPU if JAX finds one). For problems below a few tens of thousands of degrees of freedom the CPU is usually faster end-to-end because compilation dominates; the service makes this choice per job. GYRE_JIT_CACHE=off disables the persistent compilation cache.