[ocots]

Closes #379. Part 5 of #306. Conventions: ct-conventions v0.10.0, ct-agents v0.4.0.

Scope, as agreed in #379

Of the declared fields listed in #306, only what is not a judgment and can be checked:

• :reference_solution (optional): the analytic solution of the continuous problem.
• Sources: every description cites them. They stay in ext/Descriptions/<p>.md, the single place; no :references field that would duplicate them.

Dropped: :tags (:hard is a judgment; :large_state or :analytic are computable, from features or from :reference_solution); :corleone (we write our own problems, #308: a pointer to a SciML problem that differs from ours, unchecked, would suggest an equivalence that does not hold). A descriptive structure (singular arcs, boundary arcs, stiffness, turnpike), characteristics rather than judgments, is for later.

Design

• ext/MetaData/<p>.jl: :reference_solution => p -> …, a function of the parameters, like :init ([Metadata] Shared initial guess in the metadata, read by every modeling #377). It returns (state=t -> …, control=t -> …, objective=…, source=…), or nothing for the parameters the solution is not known for.
• src/solutions.jl: the analytic solutions. _bryson_denham_solution (Bryson, Denham & Dreyfus 1963, https://doi.org/10.2514/3.2107), shared by beam (cost ∫u², J = 8/(9ℓ) = 8.889) and bryson_denham (cost ½∫u², J = 4/(9ℓ) = 4): ẋ₁ = x₂, ẋ₂ = u on [0, 1], x(0) = (0, 1), x(1) = (0, -1), x₁ ≤ ℓ, known for ℓ ≤ 1/6 (boundary arc on [3ℓ, 1 − 3ℓ]).
• METADATA_SCHEMA.optional gains reference_solution=Function.
• OptimalControlProblems.reference_solution_data(problem, parameters=nothing), not exported.
• The objective of a discretized problem differs from the analytic one by the discretization error; the reference objective ([Metadata] Reference objectives per scheme, computed by a script #375) stays the reference of the convergence report.

Tests

• test/suite/OptimalControl/test_reference_solution.jl: the solution solves the model. At the analytic point, on the trapezoidal discretization of the OptimalControl model, the constraint violation and the gap of the objective to the analytic one vanish with the step at order 2 (from 100 to 400 steps, divided by at least 10). Generic: every problem with a :reference_solution, all its constraints. Shown failing on a wrong objective (bryson_denham with weight 1): the gap does not decrease.
• core: reference_solution_data with and without parameters, nothing for a problem without one; _bryson_denham_solution: values, junctions, nothing outside its domain (no boundary arc, other horizon or boundary conditions, lower bound above 0).
• core, consistency: every description has a References section with at least one entry (cites_sources, with positive and negative cases); the reference solutions have a state, a control, a finite objective and a source.
• NLPModels added to the test/suite/OptimalControl environment.

Local: core 739 passed; OptimalControl reference solution 4 passed.

Documentation

docs/src/problems-introduction.md: the analytic solution, with an example; the problem_metadata docstring lists the field.

🤖 Generated with Claude Code