[Metadata] Computed features, reference objective, shared initial guess

Agents: read the guide for agents in #310 first (order, difficulty, how to claim an issue, working method). The specification is in this description and in the comments below. This description was updated on 2026-11-06, after #360 and #375. Where an older comment contradicts it, the description wins: see the update comment.

Goal

Separate what is computed about a problem from what is declared in its metadata, add the declared fields the tests, the crons and the benchmarks need, and make the metadata the single source of the initial guess shared by every modeling (#151).

Part of #310, step 5. Depends on #283 (continuous problems, Problem) and #303 (statuses). Used by #304 (comparison rule), #305 (crons), #307 (documentation pages).

Work: sub-issues

Part	Issue	State
1. Reference objectives	#375	done (#380)
2. Features computed from the model	#376	free; the documentation switch waits for #311
3. Shared initial guess in the metadata (with #151)	#377	waits for #368, #369
4. Robustness of the initial guess, known local objectives	#378	free
5. Declared fields: tags, references, Corleone, reference solution, analytic objective	#379	low priority

How the tests use the metadata (since #360)

Three kinds of tests. Convergence is not a binary criterion any more.

1. Does not break. Every CI run, short: every problem in every configuration, on a small grid with a few iterations. It fails on an exception or a non-finite objective. Convergence is not checked.
2. Model equivalence. Every CI run, no solve: the modelings of a problem define the same problem (at the initial guess, and the NLP equivalence of #284). It fails when they differ. This is the important comparison between modelings.
3. Convergence. In the weekly cron, or on demand (argument convergence, label test convergence). Each problem is solved on its default grid. The report gives the solver status and the relative gap of the objective to the reference objective of the problem, for the grid and the scheme of the solve. It never fails: there is no tolerance. The cron flags what got worse since the previous run (issue cron-convergence).

So a metadata field is never a test threshold. References and known solutions say how far a solve is from them; statuses (:valid, :draft) say whether a model is finished and equivalent, not whether it converges.

Current state

• ext/MetaData/<p>.jl holds :grid_size, :parameters, :status, optionally :notes. The schema METADATA_SCHEMA (src/OptimalControlProblems.jl: required, optional, generated) is checked at load time and by test/suite/core/test_consistency.jl. An unknown field fails, so a new field must be added there.
• :reference_objective is a generated field (#375). See below.
• The documentation browser computes dimensions, cost kind (Mayer / Lagrange / Bolza), fixed or free final time and constraint counts from the ocp (docs/browser.jl, collect_problem_data).
• Initial guesses are written in each model file. In ext/OptimalControlModels/ they are mostly constants, some functions of time. JuMP models use constant start= values.

Computed, never written by hand (#376)

A function (e.g. features(:beam)) computes, when an extension is loaded: dimensions, cost kind, fixed or free initial and final times, kinds and counts of constraints (box on state / control / variable, nonlinear path, boundary). From the ocp (OptimalControl modelings), or from the keys stored in the JuMP model for problems available in JuMP only. Move the computation out of docs/browser.jl into it; the documentation (browser, status page) and CTBenchmarks read it.

Fields

Field	Content
:grid_size, :parameters	unchanged
:status, :notes	see #303; :draft = model not finished or not equivalent, never "does not converge" (#360)
:reference_objective	generated, see below (#375)
:init	see below (#377)
:tags	controlled vocabulary defined in src and checked by the tests (e.g. :hard from CTDirect#580, :analytic, :large_state) (#379)
:references	bibliographic sources of the problem (literature values of the objective, when known, go here as information) (#379)
:corleone	optional, informative: a related problem in SciML's OptimalControlBenchmarks (#308, #379)
:reference_solution	optional: analytic x(t), u(t), for convergence orders (#379)
known local objectives	see #378

:known_failures is dropped: since #360 a convergence failure is reported, never a test failure, so there is nothing to declare.

Every field is type-checked at load time and by the consistency tests.

:reference_objective (done in #375)

• One reference per scheme, at the default grid of the problem: the objective of the discretized problem, which every solve of the convergence report is compared with. The trapezoidal rule exists for every problem; the other schemes come with #369.
• Computed from the convergence tests, never typed. tools/references/update.jl reads their results (cron artifacts or a local run) and keeps the best objective among the solves that converged (every modeling, configuration and platform). It records the spread between them; above 1e-6, agreement = false means that the configurations reached different solutions (#378). Stored in ext/MetaData/references/<p>.toml, one table per scheme, with the grid, the parameters, the run and every solve. Procedure: tools/references/README.md.
• OptimalControlProblems.reference_objective(p; grid_size, scheme) returns the value, or nothing.
• The consistency tests fail when a reference no longer matches the default grid or parameters of its problem (compute it again), and when a problem :valid in one modeling only has no reference (comparison rule).
• For a problem available in one modeling only, a computed reference is a regression check, not an independent validation: the status page (#307) shows it as such.
• An analytic objective of the continuous problem, when it is known, is information with its source (#379). It is not the reference of a discretized solve: the two differ by the discretization error.
• No tolerance: the gap is reported, never tested.

Local solutions (#378)

Some problems have several local solutions (glider, cart_pendulum, and mountain_car, where Ipopt and MadNLP reach two of them). Next to the reference, a list of known local objectives per scheme and default grid, generated, not typed. The convergence report says which one a solve reached (the best known, a known local one, or a new one). A cron test solves each problem under several solver options and reports the spread: it tells whether an initial guess is robust.

:init (#377)

The initial guess of every modeling comes from the metadata, no longer from each model file:

• format (state=…, control=…, variable=…); each component a constant, a vector, or a function of t, never data on a grid;
• OptimalControl and OptimalControlScalarized: passed as is (Problem.init, #283);
• JuMP: evaluated at the nodes, with the number of controls of the scheme (N+1 for trapezoid, N for Euler and midpoint, see #284);
• overridable: beam(JuMPBackend(); init=…), and init= in solve on the OptimalControl side;
• maintainer's rule: the guess must make the solvers converge without being too close to the solution, so that the solves still exercise the iterations. Do not tune tolerances or grids first;
• the tests check that the OptimalControl guess and the JuMP start values coincide at the nodes (comparison/test_init).

Not now

:expected_structure (smooth, bang-bang, singular, state constraints) is dropped: it depends on the parameters, and doing it properly means a list of arcs and switching times. To revisit with indirect methods.

Done when

• features(:p) computed from the model; docs/browser.jl uses it (#376).
• Declared fields with type checks; consistency tests cover them (#379).
• :reference_objective for every problem, computed from the convergence tests, source stated (#375).
• Known local objectives and the robustness report (#378).
• Initial guesses read from the metadata by every modeling; no initial guess left in the model files (#377).
• Initial guess documented (#151), with how to override it (#377).