Service API

With adapt the service chooses the polynomial degree: starting at discretization.order it raises the degree, warm-starting each level from the previous one, until the adjoint-based error estimate of one output is within a tolerance.

curl -s $API/jobs -H 'content-type: application/json' -d '{
  "case": "bump_euler",
  "overrides": {"discretization.order": 1},
  "adapt": {"output": "cd", "tolerance": 1e-4, "max_order": 4}
}'

The result is that of the final degree (spec, case, outputs, gradients, error_estimate, artefacts) and has an adaptation section: {output, tolerance, met, order, value, corrected, error, levels}, where levels has one record per degree tried. Check met: a job whose tolerance was not reached at max_order is still succeeded, with the result of the highest degree that converged. The job record carries requested.adapt and result_summary.adaptation (without levels). The event log shows every degree in turn: a case event, the iteration events of its solve (each with order), and one adapt event (the level record) that closes it; the last case event is that of the result. timing.solve is the wall time of the whole selection and timing.setup is 0.

A degree whose solve fails from the interpolated lower-degree solution is tried again before it counts as failed: from the same guess with the full continuation (skipped when the guess is not an admissible state), then from the free stream. Each further attempt is an adapt_retry event with order, reason (why the previous attempt failed) and start (interpolated or free_stream).

A degree whose flow solve did not converge has order, degrees_of_freedom, converged: false, the solver’s reason and wall_time only.

met is true only when the estimate is a finite number, its adjoint solve converged and its absolute value is at most tolerance; an estimate below the tolerance from an adjoint solve that did not converge does not end the selection. The selection also ends at the first degree whose flow solve does not converge, below max_order too: met is false and order, value, corrected and error are those of the last degree that converged. If the starting degree itself does not converge, these four are null and the result has converged: false.

Unknown keys and invalid values are a 422 ValidationError. A selection that cannot start — discretization.order is 0, or max_order is below discretization.order — is a 422 InvalidCase. An output that the case does not have is found by the worker: the job fails.

queued → running → succeeded | failed | cancelled, plus interrupted for jobs that were active when the service restarted. A job identical to an earlier successful one is answered immediately from the cache with cached_from naming the original; pass "use_cache": false to force a new run. The cache key is the specification, the gradient, error-estimate and adapt requests (an omitted max_order equals 5), the contents of a mesh file the case names, and the code (version, revision and a hash of the package sources): a result computed by different code, for example before an upgrade on the same data directory, is not reused, and replacing a stored mesh under the same name is a cache miss. On a cache hit device is the device of the original run. A job that ran but did not converge is succeeded with "converged": false — check the flag. Its outputs are those of the iterate the solve ended at, and it has no gradients or error_estimate: the result and the job’s result_summary carry skipped, which names each requested section that is missing with the reason. Non-finite values (a diverged solve) are reported as null in job records, results, events and session replies.

The last five rows go through one generic route, POST /sessions/{id}/{command}, which passes any command of the solver process through (- and _ are the same in the name); GET /sessions/{id} lists the commands a session supports.

One command runs at a time per session. The first evaluate compiles kernels; later ones are warm-started and typically need a handful of Newton steps. Idle sessions close after 30 minutes; at most four are open at once by default.

alpha_deg is accepted wherever alpha (radians) is: in evaluate inputs and in the wrt of /gradients, /adjoint and job gradients. The derivative is returned under the name asked for, per degree for alpha_deg. With wrt omitted the result has alpha (radians) only, and /state and the session interface list alpha. Non-finite or non-numeric inputs are refused with 422.

If an evaluation does not converge, the reply has converged: false with the outputs and residual of the iterate the solve ended at, and the session keeps its last converged state as the warm start of the next evaluation. Until an evaluation converges again, /gradients, /adjoint, /error-estimate, /distributions and /field answer 422 RuntimeError; the last two do so before the first evaluation as well. converged of /state is true when a state exists and the last evaluation converged.

case is a preset name or a CaseSpec object, for jobs, sessions and validation alike; a string is never read as a file path (file specifications are a CLI and Python feature). A case on a mesh file names a mesh of the mesh store. A session reads that mesh once, when it starts: it keeps running on it, and reports the digest of that moment, if the mesh is replaced or deleted afterwards.

• A name matches ^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}\.(msh|npz)$. Anything else, including a name with directories, is a 422 InvalidMeshName on every mesh route and in mesh.params.path of a case; nothing is opened or written.
• The upload is read and validated in full. A file the reader cannot use is a 422 InvalidMesh with the reader’s message and is not stored; a mesh already stored under the name is unchanged.
• A case that names a mesh which is not stored is a 404 UnknownMesh, at validation, job submission and session creation; the hint names the PUT to make. A case whose discretization.boundaries does not give a condition for every boundary group of the mesh, or names a group the mesh does not have, is a 422 InvalidCase.
• An upload above GYRE_MESH_MAX_BYTES (64 MiB by default) is a 413 MeshTooLarge; a full store is a 507 MeshStoreFull (limits).
• A file that was placed in the store’s directory by hand and that the reader rejects is listed by GET /meshes as {"name", "error"} and answered 422 InvalidMesh by GET /meshes/{name}.

Session command errors carry the exception class name as type; classes other than the three listed are answered with 500. An exception raised while a new session builds its case is a 422 with the class name as type; its hint, like that of a start-up Timeout, points to POST /cases/validate, since there is no session to inspect. Case errors are reported by POST /cases/validate and, identically, when a job or session is submitted. The error object inside a failed job record is {"type", "message"} without a hint; the traceback of a worker exception is the error.txt artefact.

gyre.client.GyreClient wraps the job, session, mesh, preset, validation and info endpoints (submit, job, wait, run, result, events, artifact, cancel, session, meshes, upload_mesh, mesh, delete_mesh, presets, validate, info) and raises GyreError carrying the status and the structured error. submit(..., adapt={"output": "cd", "tolerance": 1e-4}) and run(..., adapt=...) send an order selection; upload_mesh(path, name=None) stores a local file under its own name unless name is given. Pipelines, metrics and schemas are reached with plain HTTP. See MDO integration for RemoteDiscipline.