---
title: "User Guide"
summary: "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."
section: guide
order: 0
level: 2
keywords: [guide]
---
<!-- gyre docs: expanded Markdown of guide/index.md (generated tables, verification numbers and chart data are written out). Base level of this page: L2 Practice; passages at another level are bracketed by 'begin level N' / 'end level N' comments and start with [LN Name]. Built from revision ceb1f4b0be. -->

Task-oriented pages. Each starts with the shortest path to a result and unfolds options, behaviour and rationale as you raise the depth dial.

- [Getting started](getting-started.md) (L1 Essentials): 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](cases.md) (L2 Practice): 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](meshes.md) (L2 Practice): 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](service.md) (L2 Practice): 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](gradients.md) (L2 Practice): 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](mdo-integration.md) (L2 Practice): 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)](agents.md) (L2 Practice): 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](pipelines.md) (L2 Practice): 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](deployment.md) (L2 Practice): 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](python-api.md) (L2 Practice): Use Gyre as a library — build a case, drive the discipline, access the discretization and its differentiable kernels directly.
- [Troubleshooting](troubleshooting.md) (L1 Essentials): 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.