Gradients and error estimates

• Outputs (of): any scalar functional — cl, cd, cm, cx, cy, heat (viscous), entropy_error, kinetic_energy, total_entropy. The load field f_surface is differentiated through adjoint_product / tangent_product with a seed.
• Inputs (wrt): mach, alpha (radians), re, gamma, pr, any boundary datum present in the case, and x_surface. The CLI, jobs and sessions also accept alpha_deg and return that derivative per degree.
• Mode: adjoint (one solve per output), direct (one per scalar input; no x_surface), or auto.

{"derivatives": {"cl": {"alpha": 7.7383, "mach": 0.23041},
                 "cd": {"alpha": 0.011770, "mach": 7.908e-05}},
 "info": {"mode": "adjoint",
          "linear_solves": [{"output": "cl", "iterations": 51, "reduction": 7.09e-11, "converged": true},
                            {"output": "cd", "iterations": 50, "reduction": 7.18e-11, "converged": true}],
          "wall_time": 127.6, "residual_norm": 7.06e-13}}

This is the gradients section of the result of the unmodified preset naca0012_euler (--gradients --of cl,cd --wrt alpha,mach), recorded at revision 5ee1cdc on the CPU and shortened to the digits shown. alpha derivatives are per radian. The wall_time of that record includes compiling the adjoint kernels on a busy machine; it says nothing about the cost of a warm adjoint solve. residual_norm is the nonlinear residual of the state the derivative was taken at: check it when gradients look noisy. The outputs themselves are defined under Outputs and functionals.

An error estimate builds the $p+1$ discretization and solves one transposed linear system there. The first call compiles the enriched hierarchy (the dominant cost on small cases); the linear solve itself is comparable to one adjoint solve at the higher degree.

Every interface reports the selection as adaptation: output, tolerance, met, order, value, corrected, error and levels, one record per degree tried. Everything else in the result — outputs, gradients, error estimates, fields, the case summary — is that of the final degree.

• gyre run prints one line per degree (order P: N DOF, cd = …, estimated error … (target …), or order P: N DOF, did not converge (reason); -q suppresses them). Its JSON summary lists per level order, degrees_of_freedom, converged and error; the complete level records are in result.json with -o <dir>. The exit status is 0 when the solve converged and the tolerance was met, 2 when it did not converge, and 3 when it converged but the tolerance was not met at --max-order. A request that cannot start (the output is not a scalar output of the case, --max-order is below the case’s order or above 8, the case has order 0) ends with a message and exit status 1 before any flow is solved. --max-order without --target-error is an error.
• Jobs validate adapt when the request arrives: unknown keys, a tolerance that is not positive or a max_order outside 1 to 8 are a 422 ValidationError; a case of order 0 or a max_order below discretization.order is a 422 InvalidCase. An adapt.output that is not a scalar output of the case is a 422 UnknownName that lists the scalar outputs; nothing is queued. The job’s event log shows every degree in turn (a case event, the iteration events of its solve and one adapt event with the level record), result_summary.adaptation carries the selection without levels, and adapt is part of the result-cache key.
• Pipeline solve stages put adaptation into the stage outputs. The stage fails when the solve does not converge, but not when the tolerance was not met: gate on adaptation.met as in the example if the pipeline needs the accuracy.
• adaptive_order also returns case, the solved Case of the final degree. With run_case, adapt cannot be combined with case=, and keys other than output, tolerance and max_order raise ValueError.

For each degree, starting at the case’s own: solve, estimate the error of the chosen output relative to the next degree, and stop when the magnitude of the estimate is at or below the tolerance, when max_order is reached, or when a degree does not converge. From the second degree on, the solve starts from the interpolated solution of the previous degree, directly in the Newton regime. If that fails, the same degree is tried again from the interpolated solution with the full pseudo-transient continuation (skipped when the interpolated state is not admissible, for example a negative pressure next to a shock), and then from the free stream; only then does the degree count as failed.

met is true only for a finite estimate whose adjoint solve converged. When met is false, order, value, corrected and error are those of the last degree that converged; if the starting degree itself did not converge they are null and the result reports converged: false like any failed solve. An explicit multigrid schedule in solver.levels belongs to the degree the case was written for; at another degree $p$ it becomes $p$ followed by the listed degrees below $p$.

This is uniform enrichment on a fixed mesh. It controls the discretization error of one analysis and nothing else: the per-element indicators of the estimate are not used, the mesh is not adapted, and no input of the case is changed. The cost is that of every degree tried, each with its own compilation and one error estimate at the degree above.

Run it once at the baseline design to pick the degree the objective actually needs, and again when the design has moved far (for example, when a shock appears). Between those points, keep the degree fixed: changing the discretization changes the discrete objective, and an optimizer should not see that as a change of the design.