[Metadata] Reference objectives per scheme, computed by a script

Agents: read the guide for agents in #310 first. Specification: this description, #306 and its comments.

Sub-issue of #306, part 1 of 5. Independent.

Scope

:reference_objective in the metadata: one entry per scheme at the default grid of the problem (value, source = :computed, grid_size, the configurations that converged and their objectives, their agreement, package versions); optionally an analytic value of the continuous problem with its source, shown as information only.
Computed entries are generated by scripts/reference_objectives.jl into one file per problem (ext/MetaData/references/<p>.toml), never edited by hand. Reference = best objective among the configurations of TestConfigs.CONFIGS that converged (tolerance 1e-8); a disagreement between configurations (local minima) is written and printed, not hidden.
Convergence report ([Tests] Report convergence instead of testing it; keep hard checks for breakage and model equivalence #360): gap of each solve to the entry of its grid and scheme; no entry, no gap.
Consistency tests: type of the field; every :valid problem has a reference; comparison rule (a problem valid in one modeling only needs a reference).

Every problem has a computed trapezoid reference; the PR shows the agreement table.
A cron run shows the gap column filled.
READMEs say how to (re)compute the references.

Taken by an agent; draft PR to follow.

docs: how the reference objectives are computed and when to compute t…

feat: reference objectives of every problem (trapezoidal rule, defaul…

Merge pull request #380 from control-toolbox/feat/375-reference-objec…

Done in #380 (merged).

What was done

Reference objective per scheme at the default grid, for all 22 problems (trapezoidal rule): ext/MetaData/references/<problem>.toml, generated by tools/references/update.jl from the results of the convergence tests (cron artifacts or local test/reports), never edited by hand. Value = best converged objective; the spread between configurations is recorded, agreement = false above 1e-6.
OptimalControlProblems.reference_objective(problem; grid_size, scheme); generated metadata field :reference_objective.
Convergence report: grid size and scheme columns, objective at full precision, gap to the reference.
Consistency tests: a reference that no longer matches the default grid or parameters fails; the comparison rule fails for a problem without any reference.
Procedure: tools/references/README.md.

Left to others

[Cron] Robustness of the initial guess and known local objectives #378: the three disagreements found by the first computation, all split by solver: mountain_car (two local solutions, Ipopt 102.3976 vs MadNLP 102.3810), jackson and rocket (MadNLP 1.5e-6 and 1.7e-6 above Ipopt). Details in feat: reference objectives per scheme, computed from the convergence tests (#375) #380 (comment).
[Metadata] Declared fields: tags, references, Corleone, reference solution #379: analytic values with their source (none sourced yet).
Other schemes: compute again once [Dev] JuMP models for Euler, implicit Euler and midpoint #369 adds them to the convergence tests.

🤖 Generated with Claude Code