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

Aperta
  • Qualcosa non va?
#306 6 commenti 0 reazioni 1 assegnatario Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@ocots ci sta già lavorando.

Dal 4/11/2026.

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

feature paper

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.
Lingua principale
Julia
Stelle
13
Fork
1
Merge medio
3h 20m
PR unite (30g)
27

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di control-toolbox/OptimalControlProblems.jl

Tutte le issue di control-toolbox/OptimalControlProblems.jl

Issue simili

Altre issue su Julia

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.