Pipelines

A reference that is the whole value keeps its type (number, boolean, list); inside a longer string it is formatted as text.

An assert stage takes a non-empty checks list. A check is {value, name} (the name is optional) with at least one of the criteria min, max, abs_max and equals. Unknown keys, a check without a criterion and a missing or empty checks list are rejected when the pipeline is loaded, before any stage runs. min, max and abs_max compare numbers: a value that is not a number (null from a diverged solve, a string, a list) or a criterion that is not a number fails the check, and the check result says why in reason. equals compares values of any type. A failed gate ends the stage with PipelineError: gate failed: […].

A solve stage takes case, overrides, gradients, error_estimate, require_converged (default true: the stage fails if the solve does not converge) and adapt:

  - id: accurate
    uses: solve
    with:
      case: bump_euler
      overrides: {discretization.order: 1}
      adapt: {output: cd, tolerance: 1.0e-4, max_order: 4}
  - id: accuracy-gate
    uses: assert
    with:
      checks:
        - {name: tolerance met, value: "${stages.accurate.outputs.adaptation.met}", equals: true}

adapt selects the polynomial degree by the estimated error of output (max_order defaults to 5). Unknown keys, a missing output or tolerance and a value that is not a mapping are errors before the solve. The stage does not fail when the solve converged but the tolerance was not met at max_order; adaptation.met is then false, which is what the gate above tests. met is true only for a finite estimate whose adjoint solve converged, and the selection ends at the first degree that does not converge; the level records in adaptation.levels are described under Service.

Keys marked required have no default; a stage without them fails when it runs. case is a preset name, the path of a specification file, or an inline specification (through the service: a preset name or an inline specification only). overrides is a mapping of dotted paths, as with gyre run --set.

solve — one analysis (the files of gyre run -o are written to the stage directory).

sweep — one warm-started solve per value, in one solver process.

order_study — the same case at several polynomial degrees, each solved from scratch.

verify — the verification suite.

docs — build the documentation site.

shell — a command on the host (not startable through the service unless the operator sets GYRE_PIPELINES_ALLOW_SHELL=1).

assert — a gate.

report — a Markdown and JSON summary (report.md, report.json in the stage directory).

  - id: degrees
    uses: order_study
    with: {case: bump_euler, orders: [1, 2, 3], error_estimate: [cd]}
  - id: studies
    uses: verify
    with: {suite: quick, only: [free_stream, entropy_conservation], output: var/verification}
  - id: site
    uses: docs
    needs: [studies]
    with: {output: site, verification: var/verification}
  - id: lint
    uses: shell
    with: {run: ".venv/bin/ruff check src tests", timeout: 600}

In a sweep, outputs may name the field output f_surface and gradients_wrt the shape input x_surface; the rows then hold the loads and the shape derivatives (d<output>/dx_surface) as lists. Slopes exist for scalar outputs only. Unknown names in outputs or gradients_wrt are rejected before the first solve, as is gradients_wrt together with outputs that contain no scalar output. gradients_wrt accepts alpha_deg (column d<output>/dalpha_deg, the derivative per degree), like the solve stage’s gradients.wrt. A point that does not converge reports the outputs of its failed iterate (null where they are not finite) and null in every derivative column; derivatives are computed for converged points only.

Each run writes var/pipelines/<name>/pipeline.json (status of every stage, keys, timings) and, per stage, stage.json, a log (compute and shell stages), and whatever artefacts the stage produces (a solve stage leaves the same files as gyre run -o). -o selects another directory than var/pipelines.

pipeline.json is replaced by the next run of the pipeline; use --record FILE for a per-run copy. A stage whose execution fails writes stage.json with status: failed. var/pipelines/<name>/ also contains a .lock file, which serialises the runs of the pipeline in that directory. See Pipelines and provenance for the caching rules.