--- title: Getting started summary: 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. section: guide order: 1 level: 1 audience: [CFD practitioners, MDO integrators] keywords: [install, quickstart, CLI, first run] --- ## Install ```bash git clone 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. **[L2 Practice] Requirements** 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. **[L2 Practice] What was written** | 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 | **[L2 Practice] Change the case** 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](cases.md). ## 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](gradients.md)). `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](../theory/outputs-and-functionals.md). **[L2 Practice] Let the solver choose the degree** ```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](service.md#jobs-one-shot-analyses). 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](meshes.md) and the [worked example](../examples/imported-mesh.md). ## 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` | **[L2 Practice] Where next** * [Troubleshooting](troubleshooting.md) — when a solve does not converge, and first-run problems. * [Mesh files](meshes.md) — 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](service.md) — jobs and warm sessions over HTTP. * [MDO integration](mdo-integration.md) — the discipline contract. * [Agent interface](agents.md) — driving Gyre from an AI agent. * [Examples](../examples/naca0012-euler.md) — worked cases. **[L3 Mechanics] Choosing the device** `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.