[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.

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).

Current state

• metadata(:p) holds :grid_size and :parameters (ext/MetaData/<p>.jl, an OrderedDict); types checked at load time (METADATA_INFOS, METADATA_TYPES in src/OptimalControlProblems.jl).
• The documentation browser already computes dimensions, cost kind (Mayer / Lagrange / Bolza), fixed or free final time and constraint counts from the ocp (docs/browser.jl:742-767, collect_problem_data).
• Initial guesses are written in each model file: in ext/OptimalControlModels/ mostly constants (xinit = [0.1, 0.1]), one function of time, and one defined on the grid (xinit = [[…] for i in 0:N]), which cannot exist for a continuous problem; JuMP models use constant start= values.

Computed, never written by hand

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.

Declared fields

Field	Content
:grid_size, :parameters	unchanged
:status, :notes	see #303
:known_failures	see #305
:reference_objective	see below
:init	see below
:tags	controlled vocabulary defined in src and checked by the tests (e.g. :hard from CTDirect#580, :analytic, :large_state)
:references	bibliographic sources of the problem (literature values of the objective, when known, go here as information)
:corleone	name of the matching problem in Corleone's OptimalControlBenchmarks, and whether the formulation is the same (#308)
:reference_solution	optional: analytic x(t), u(t), for convergence orders

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

:reference_objective

Entries (value, source, grid_size, scheme, …), with a priority order:

1. Analytic value, when it exists: source = :analytic, grid_size = nothing, with the reference where it is derived.
2. Otherwise, computed by us on a fine grid: source = :computed, with the configuration used (grid size, scheme, modeler, solver, tolerances) and the package versions. A script (e.g. scripts/reference_objective.jl) computes and writes these entries, so they are never typed by hand; it is rerun when a problem or its parameters change.

The source is always stated, in the metadata and in the documentation. For a problem available in one modeling only, a :computed reference is a regression check (it detects changes), not an independent validation: the status page (#307) shows it as such.

Tolerance: to decide later, from the first cron results (#305). Until then the crons report the relative gap to the reference without failing on it.

:init

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;
• rewrite the grid-defined guess as a function of t, and check the problem still converges;
• the tests check that the OptimalControl guess and the JuMP start values coincide at the nodes (today 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.
• Declared fields above with type checks; consistency tests cover them.
• :reference_objective for every problem: analytic where it exists, otherwise computed by the script, source stated.
• Initial guesses read from the metadata by every modeling; no initial guess left in the model files; the grid-defined one rewritten.
• Initial guess documented (#151), with how to override it.