diff --git a/AGENTS.md b/AGENTS.md index db8f5cd16..746a15b6e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -86,3 +86,8 @@ plans and reports. beta is the human's choice: if the request does not say, ask; never infer it. State in the proposal the versions you apply: ct-agents, ct-conventions, and the commit of the CTActions clone `release.jl` runs from. +- **Add a problem, or a modeling of one.** Specific to this repository: follow + [`ext/README.md`](ext/README.md). Before the tests, run the linter, + `julia --project tools/lint/problems.jl `, until it reports no ❌. No ❌ does not + mean the problem is right: paste the ℹ️ checklist of its report in the pull request and + tick each box, or say why it is not ticked. diff --git a/ext/JuMPModels/balanced_field.jl b/ext/JuMPModels/balanced_field.jl index 78ed2b139..22a5a519f 100644 --- a/ext/JuMPModels/balanced_field.jl +++ b/ext/JuMPModels/balanced_field.jl @@ -52,6 +52,9 @@ function OptimalControlProblems.balanced_field( γ_tf = params[:γ_tf] α_min = params[:α_min] + v_min = params[:v_min] + h_min = params[:h_min] + tf_min = params[:tf_min] α_max_ctrl = params[:α_max_ctrl] # Constants @@ -79,12 +82,12 @@ function OptimalControlProblems.balanced_field( data = ProblemData(; state=[ Component("r"), - Component("v"; lower=1.0), - Component("h"; lower=0.0), + Component("v"; lower=v_min), + Component("h"; lower=h_min), Component("γ"), ], - control=[Component("α"; lower=0, upper=α_max_ctrl)], - variable=[Component("tf"; lower=0.1)], + control=[Component("α"; lower=α_min, upper=α_max_ctrl)], + variable=[Component("tf"; lower=tf_min)], costate=["∂r", "∂v", "∂h", "∂γ"], times=v -> (t0, v[1]), dynamics=(x, u, v, t) -> dynamics(x, u), diff --git a/ext/JuMPModels/brachistochrone.jl b/ext/JuMPModels/brachistochrone.jl index b45ee9ae0..1e63a3c56 100644 --- a/ext/JuMPModels/brachistochrone.jl +++ b/ext/JuMPModels/brachistochrone.jl @@ -38,11 +38,13 @@ function OptimalControlProblems.brachistochrone( yf = params[:yf] u_min = params[:u_min] u_max = params[:u_max] + tf_l = params[:tf_l] + tf_u = params[:tf_u] data = ProblemData(; state=[Component("px"), Component("py"), Component("v")], - control=[Component("u"; lower=-1.57, upper=1.57)], - variable=[Component("tf"; lower=0.1, upper=20.0)], + control=[Component("u"; lower=u_min, upper=u_max)], + variable=[Component("tf"; lower=tf_l, upper=tf_u)], costate=["∂px", "∂py", "∂v"], times=v -> (t0, v[1]), # Dymos formulation diff --git a/ext/JuMPModels/mountain_car.jl b/ext/JuMPModels/mountain_car.jl index d2e004cef..765924bfc 100644 --- a/ext/JuMPModels/mountain_car.jl +++ b/ext/JuMPModels/mountain_car.jl @@ -30,7 +30,6 @@ function OptimalControlProblems.mountain_car( # parameters params = parameters_data(:mountain_car, parameters) t0 = params[:t0] - tf_start = params[:tf_start] tf_min = params[:tf_min] pos_t0 = params[:pos_t0] vel_t0 = params[:vel_t0] diff --git a/ext/JuMPModels/space_shuttle.jl b/ext/JuMPModels/space_shuttle.jl index 5aaf7b364..da9c80cab 100644 --- a/ext/JuMPModels/space_shuttle.jl +++ b/ext/JuMPModels/space_shuttle.jl @@ -61,8 +61,6 @@ function OptimalControlProblems.space_shuttle( ψ_t0 = params[:ψ_t0] # for initial guess - α_s = params[:α_s] - β_s = params[:β_s] ## Final conditions, the so-called Terminal Area Energy Management (TAEM) h_tf = params[:h_tf] diff --git a/ext/MetaData/balanced_field.jl b/ext/MetaData/balanced_field.jl index 66989b79d..c1abf88bf 100644 --- a/ext/MetaData/balanced_field.jl +++ b/ext/MetaData/balanced_field.jl @@ -21,10 +21,11 @@ balanced_field_meta = OrderedDict( γ_t0=0.0, # initial flight path angle (rad) h_tf=10.668, # final altitude (35 ft in m) γ_tf=0.0873, # final flight path angle (5 degrees in rad) - v_min=0.0, - v_max=100.0, - α_min=-0.1745, # -10 degrees + v_min=1.0, + α_min=0.0, α_max_ctrl=0.2618, # 15 degrees + h_min=0.0, + tf_min=0.1, ), :parameter_info => ( t0=(unit="s", meaning="initial time, at the speed V1"), @@ -50,19 +51,11 @@ balanced_field_meta = OrderedDict( γ_t0=(unit="rad", meaning="initial flight path angle"), h_tf=(unit="m", meaning="final altitude, the screen height of 35 ft"), γ_tf=(unit="rad", meaning="final flight path angle, 5°"), - v_min=( - unit="m/s", - meaning="lower bound of the velocity (not used by the models yet, which use 1)", - ), - v_max=( - unit="m/s", - meaning="upper bound of the velocity (not used by the models yet)", - ), - α_min=( - unit="rad", - meaning="lower bound of the angle of attack (not used by the models yet, which use 0)", - ), + v_min=(unit="m/s", meaning="lower bound of the velocity"), + α_min=(unit="rad", meaning="lower bound of the angle of attack"), α_max_ctrl=(unit="rad", meaning="upper bound of the angle of attack"), + h_min=(unit="m", meaning="lower bound of the altitude"), + tf_min=(unit="s", meaning="lower bound of the final time"), ), :status => (OptimalControl=:valid, OptimalControlScalarized=:valid, JuMP=:valid), # initial guess of every modeling (#377), from the parameters diff --git a/ext/MetaData/brachistochrone.jl b/ext/MetaData/brachistochrone.jl index 09b2ecce3..9afcb58a2 100644 --- a/ext/MetaData/brachistochrone.jl +++ b/ext/MetaData/brachistochrone.jl @@ -8,8 +8,10 @@ brachistochrone_meta = OrderedDict( v0=0.0, xf=10.0, yf=5.0, - u_min=(-pi), - u_max=pi, + u_min=-1.57, + u_max=1.57, + tf_l=0.1, + tf_u=20.0, ), :parameter_info => ( g=(unit="m/s²", meaning="gravitational acceleration"), @@ -19,14 +21,10 @@ brachistochrone_meta = OrderedDict( v0=(unit="m/s", meaning="initial speed"), xf=(unit="m", meaning="final horizontal position px"), yf=(unit="m", meaning="final vertical position py"), - u_min=( - unit="rad", - meaning="lower bound of the angle u (not read by the models yet, which use −1.57)", - ), - u_max=( - unit="rad", - meaning="upper bound of the angle u (not read by the models yet, which use 1.57)", - ), + u_min=(unit="rad", meaning="lower bound of the angle u"), + u_max=(unit="rad", meaning="upper bound of the angle u"), + tf_l=(unit="s", meaning="lower bound of the final time"), + tf_u=(unit="s", meaning="upper bound of the final time"), ), :status => (OptimalControl=:valid, OptimalControlScalarized=:valid, JuMP=:valid), # initial guess of every modeling (#377), from the parameters diff --git a/ext/MetaData/references/balanced_field.toml b/ext/MetaData/references/balanced_field.toml index 5b638a266..16d52297d 100644 --- a/ext/MetaData/references/balanced_field.toml +++ b/ext/MetaData/references/balanced_field.toml @@ -5,8 +5,8 @@ [trapeze] agreement = true grid_size = 200 -parameters = "(t0 = 0.0, m = 79015.8, g = 9.80665, ρ = 1.225, S = 124.7, CD0 = 0.03, AR = 9.45, e = 0.801, CL0 = 0.5, CL_max = 2.0, h_w = 1.0, span = 35.7, α_max = 0.1745, T = 120102.0, r_t0 = 600.0, v_t0 = 70.0, h_t0 = 0.0, γ_t0 = 0.0, h_tf = 10.668, γ_tf = 0.0873, v_min = 0.0, v_max = 100.0, α_min = -0.1745, α_max_ctrl = 0.2618)" -run = "https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/42387105573 https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/42387108959 https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/42387112175 https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/42387115100" +parameters = "(t0 = 0.0, m = 79015.8, g = 9.80665, ρ = 1.225, S = 124.7, CD0 = 0.03, AR = 9.45, e = 0.801, CL0 = 0.5, CL_max = 2.0, h_w = 1.0, span = 35.7, α_max = 0.1745, T = 120102.0, r_t0 = 600.0, v_t0 = 70.0, h_t0 = 0.0, γ_t0 = 0.0, h_tf = 10.668, γ_tf = 0.0873, v_min = 1.0, α_min = 0.0, α_max_ctrl = 0.2618, h_min = 0.0, tf_min = 0.1)" +run = "https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/44015064560 https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/44235205662 https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/44455617205 https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/42387115100" source = "computed" spread = 2.4538248057585183e-9 value = 771.0114003220631 @@ -54,7 +54,7 @@ value = 771.0114003220631 [[trapeze.results]] configuration = "modeler=adnlp solver=ipopt" modeling = "OptimalControl" - objective = 771.0114003040652 + objective = 771.0114003040649 platform = "cron-OptimalControl-1.13-ubuntu-latest" [[trapeze.results]] configuration = "modeler=adnlp solver=ipopt" diff --git a/ext/MetaData/references/brachistochrone.toml b/ext/MetaData/references/brachistochrone.toml index 295eb7028..a4b9e90cb 100644 --- a/ext/MetaData/references/brachistochrone.toml +++ b/ext/MetaData/references/brachistochrone.toml @@ -5,8 +5,8 @@ [trapeze] agreement = false grid_size = 500 -parameters = "(g = 9.80665, t0 = 0.0, x0 = 0.0, y0 = 10.0, v0 = 0.0, xf = 10.0, yf = 5.0, u_min = -3.141592653589793, u_max = π)" -run = "https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/42387105573 https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/42387108959 https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/42387112175 https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/42387115100" +parameters = "(g = 9.80665, t0 = 0.0, x0 = 0.0, y0 = 10.0, v0 = 0.0, xf = 10.0, yf = 5.0, u_min = -1.57, u_max = 1.57, tf_l = 0.1, tf_u = 20.0)" +run = "https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/44015064560 https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/44235205662 https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/44455617205 https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/42387115100" source = "computed" spread = 0.02249897337664817 value = 1.802932061276909 @@ -54,7 +54,7 @@ value = 1.802932061276909 [[trapeze.results]] configuration = "modeler=adnlp solver=ipopt" modeling = "OptimalControl" - objective = 1.802932006652922 + objective = 1.8029320066529235 platform = "cron-OptimalControl-1.13-ubuntu-latest" [[trapeze.results]] configuration = "modeler=adnlp solver=ipopt" diff --git a/ext/MetaData/references/space_shuttle.toml b/ext/MetaData/references/space_shuttle.toml index 69a95156b..adf970609 100644 --- a/ext/MetaData/references/space_shuttle.toml +++ b/ext/MetaData/references/space_shuttle.toml @@ -5,8 +5,8 @@ [trapeze] agreement = true grid_size = 500 -parameters = "(t0 = 0, w = 203000.0, g₀ = 32.174, ρ₀ = 0.002378, hᵣ = 23800, Rₑ = 20902900, μ = 1.4076539e16, S = 2690, a₀ = -0.20704, a₁ = 0.029244, b₀ = 0.07854, b₁ = -0.0061592, b₂ = 0.000621408, tf_l = 1500.0, tf_u = 2500.0, h_t0 = 2.6, ϕ_t0 = 0.0, θ_t0 = 0.0, v_t0 = 2.56, γ_t0 = -0.017453292519943295, ψ_t0 = 1.5707963267948966, α_t0 = 0.0, α_s = 0.0, β_s = 0.0, h_tf = 0.8, v_tf = 0.25, γ_tf = -0.08726646259971647, h_l = 0, ϕ_l = -6.283185307179586, ϕ_u = 6.283185307179586, θ_l = -1.5533430342749532, θ_u = 1.5533430342749532, v_l = 0.0001, γ_l = -1.5533430342749532, γ_u = 1.5533430342749532, ψ_l = -6.283185307179586, ψ_u = 6.283185307179586, α_l = -1.5707963267948966, α_u = 1.5707963267948966, β_l = -1.5533430342749532, β_u = 0.017453292519943295)" -run = "https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/42387105573 https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/42387108959 https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/42387112175 https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/42387115100" +parameters = "(t0 = 0, w = 203000.0, g₀ = 32.174, ρ₀ = 0.002378, hᵣ = 23800, Rₑ = 20902900, μ = 1.4076539e16, S = 2690, a₀ = -0.20704, a₁ = 0.029244, b₀ = 0.07854, b₁ = -0.0061592, b₂ = 0.000621408, tf_l = 1500.0, tf_u = 2500.0, h_t0 = 2.6, ϕ_t0 = 0.0, θ_t0 = 0.0, v_t0 = 2.56, γ_t0 = -0.017453292519943295, ψ_t0 = 1.5707963267948966, α_s = 0.0, β_s = 0.0, h_tf = 0.8, v_tf = 0.25, γ_tf = -0.08726646259971647, h_l = 0, ϕ_l = -6.283185307179586, ϕ_u = 6.283185307179586, θ_l = -1.5533430342749532, θ_u = 1.5533430342749532, v_l = 0.0001, γ_l = -1.5533430342749532, γ_u = 1.5533430342749532, ψ_l = -6.283185307179586, ψ_u = 6.283185307179586, α_l = -1.5707963267948966, α_u = 1.5707963267948966, β_l = -1.5533430342749532, β_u = 0.017453292519943295)" +run = "https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/44015064560 https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/44235205662 https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/44455617205 https://github.com/control-toolbox/OptimalControlProblems.jl/actions/runs/42387115100" source = "computed" spread = 6.232111392599022e-10 value = -0.5958750133508789 @@ -54,7 +54,7 @@ value = -0.5958750133508789 [[trapeze.results]] configuration = "modeler=adnlp solver=ipopt" modeling = "OptimalControl" - objective = -0.5958750133627936 + objective = -0.5958750133627926 platform = "cron-OptimalControl-1.13-ubuntu-latest" [[trapeze.results]] configuration = "modeler=adnlp solver=ipopt" @@ -99,7 +99,7 @@ value = -0.5958750133508789 [[trapeze.results]] configuration = "modeler=exa solver=madnlp" modeling = "OptimalControl" - objective = -0.595875013315046 + objective = -0.5958750133150457 platform = "cron-OptimalControl-1.13-ubuntu-latest" [[trapeze.results]] configuration = "modeler=exa solver=madnlp" @@ -144,7 +144,7 @@ value = -0.5958750133508789 [[trapeze.results]] configuration = "modeler=exa solver=madnlp" modeling = "OptimalControlScalarized" - objective = -0.595875013315046 + objective = -0.5958750133150457 platform = "cron-OptimalControlScalarized-1.13-ubuntu-latest" [[trapeze.results]] configuration = "modeler=exa solver=madnlp" diff --git a/ext/MetaData/space_shuttle.jl b/ext/MetaData/space_shuttle.jl index b5c70411b..4ecb1f13c 100644 --- a/ext/MetaData/space_shuttle.jl +++ b/ext/MetaData/space_shuttle.jl @@ -25,7 +25,6 @@ space_shuttle_meta = OrderedDict( v_t0=2.56, # velocity (ft/sec) / 1e4, γ_t0=deg2rad(-1), # flight path angle (rad), ψ_t0=deg2rad(90), # azimuth (rad), - α_t0=deg2rad(0), # angle of attack (rad), ## for initial guess α_s=deg2rad(0), # angle of attack (rad) β_s=deg2rad(0), # bank angle (rad), @@ -77,10 +76,6 @@ space_shuttle_meta = OrderedDict( v_t0=(unit="10⁴ ft/s", meaning="initial velocity"), γ_t0=(unit="rad", meaning="initial flight path angle"), ψ_t0=(unit="rad", meaning="initial azimuth"), - α_t0=( - unit="rad", - meaning="initial angle of attack (not used by the models nor the initial guess)", - ), α_s=(unit="rad", meaning="angle of attack of the initial guess"), β_s=(unit="rad", meaning="bank angle of the initial guess"), h_tf=( diff --git a/ext/ModelingToolkitModels/chain.jl b/ext/ModelingToolkitModels/chain.jl index 91d128902..736a47c0f 100644 --- a/ext/ModelingToolkitModels/chain.jl +++ b/ext/ModelingToolkitModels/chain.jl @@ -11,13 +11,11 @@ Default parameters and the modeling status are available through `problem_metadata(:chain)` and `OptimalControlProblems.status(:chain)`. """ function OptimalControlProblems.chain( - ::ModelingToolkitBackend; - parameters::Union{Nothing,NamedTuple}=nothing, - init=nothing, + ::ModelingToolkitBackend; parameters::Union{Nothing,NamedTuple}=nothing, init=nothing ) OptimalControlProblems.Catalogue._warn_if_draft(:chain, :ModelingToolkit) params = OptimalControlProblems.parameters_data(:chain, parameters) - t0, tf = float(params[:t0]), float(params[:tf]) + tf = float(params[:tf]) L = float(params[:L]) a, b = float(params[:a]), float(params[:b]) x₂_t0, x₃_t0 = float(params[:x₂_t0]), float(params[:x₃_t0]) @@ -31,9 +29,7 @@ function OptimalControlProblems.chain( ModelingToolkit.@variables u(..) [input = true] eqs = [ - D(x₁(t)) ~ u(t), - D(x₂(t)) ~ x₁(t) * sqrt(1 + u(t)^2), - D(x₃(t)) ~ sqrt(1 + u(t)^2), + D(x₁(t)) ~ u(t), D(x₂(t)) ~ x₁(t) * sqrt(1 + u(t)^2), D(x₃(t)) ~ sqrt(1 + u(t)^2) ] # a Mayer cost: the final value of x₂ costs = [x₂(tf)] diff --git a/ext/ModelingToolkitModels/jackson.jl b/ext/ModelingToolkitModels/jackson.jl index 09470735d..996a7ecc3 100644 --- a/ext/ModelingToolkitModels/jackson.jl +++ b/ext/ModelingToolkitModels/jackson.jl @@ -15,7 +15,7 @@ function OptimalControlProblems.jackson( ) OptimalControlProblems.Catalogue._warn_if_draft(:jackson, :ModelingToolkit) params = OptimalControlProblems.parameters_data(:jackson, parameters) - t0, tf = float(params[:t0]), float(params[:tf]) + tf = float(params[:tf]) k1, k2, k3 = params[:k1], params[:k2], params[:k3] a_l, a_u = float(params[:a_l]), float(params[:a_u]) b_l, b_u = float(params[:b_l]), float(params[:b_u]) diff --git a/ext/OptimalControlModels/balanced_field.jl b/ext/OptimalControlModels/balanced_field.jl index 766482335..4aca6846f 100644 --- a/ext/OptimalControlModels/balanced_field.jl +++ b/ext/OptimalControlModels/balanced_field.jl @@ -40,6 +40,9 @@ function OptimalControlProblems.balanced_field( γ_tf = params[:γ_tf] α_min = params[:α_min] + v_min = params[:v_min] + h_min = params[:h_min] + tf_min = params[:tf_min] α_max_ctrl = params[:α_max_ctrl] # Constants @@ -61,10 +64,10 @@ function OptimalControlProblems.balanced_field( h(tf) == h_tf γ(tf) == γ_tf - 0 ≤ α(t) ≤ α_max_ctrl # alpha - tf ≥ 0.1 - h(t) ≥ 0 - v(t) ≥ 1.0 + α_min ≤ α(t) ≤ α_max_ctrl + tf ≥ tf_min + h(t) ≥ h_min + v(t) ≥ v_min ẋ(t) == dynamics(x(t), α(t), m, g, ρ, S, CD0, CL0, CL_max, α_max, T, b, K_nom, h_w) diff --git a/ext/OptimalControlModels/brachistochrone.jl b/ext/OptimalControlModels/brachistochrone.jl index 3e8c86245..56de19195 100644 --- a/ext/OptimalControlModels/brachistochrone.jl +++ b/ext/OptimalControlModels/brachistochrone.jl @@ -24,6 +24,8 @@ function OptimalControlProblems.brachistochrone( yf = params[:yf] u_min = params[:u_min] u_max = params[:u_max] + tf_l = params[:tf_l] + tf_u = params[:tf_u] ocp = @def begin tf ∈ R, variable @@ -32,8 +34,8 @@ function OptimalControlProblems.brachistochrone( z = (px, py, v) ∈ R³, state u ∈ R, control - -1.57 ≤ u(t) ≤ 1.57 - 0.1 ≤ tf ≤ 20.0 + u_min ≤ u(t) ≤ u_max + tf_l ≤ tf ≤ tf_u px(t0) == x0 py(t0) == y0 diff --git a/ext/OptimalControlModels/mountain_car.jl b/ext/OptimalControlModels/mountain_car.jl index 03c4e5dd3..e714161f4 100644 --- a/ext/OptimalControlModels/mountain_car.jl +++ b/ext/OptimalControlModels/mountain_car.jl @@ -18,7 +18,6 @@ function OptimalControlProblems.mountain_car( # parameters params = parameters_data(:mountain_car, parameters) t0 = params[:t0] - tf_start = params[:tf_start] tf_min = params[:tf_min] pos_t0 = params[:pos_t0] vel_t0 = params[:vel_t0] diff --git a/ext/OptimalControlModels/space_shuttle.jl b/ext/OptimalControlModels/space_shuttle.jl index c09c32ff9..86c49e903 100644 --- a/ext/OptimalControlModels/space_shuttle.jl +++ b/ext/OptimalControlModels/space_shuttle.jl @@ -49,8 +49,6 @@ function OptimalControlProblems.space_shuttle( ψ_t0 = params[:ψ_t0] # for initial guess - α_s = params[:α_s] - β_s = params[:β_s] ## Final conditions, the so-called Terminal Area Energy Management (TAEM) h_tf = params[:h_tf] diff --git a/ext/OptimalControlScalarizedModels/balanced_field.jl b/ext/OptimalControlScalarizedModels/balanced_field.jl index 9ce52f7df..ca8e81fc7 100644 --- a/ext/OptimalControlScalarizedModels/balanced_field.jl +++ b/ext/OptimalControlScalarizedModels/balanced_field.jl @@ -44,6 +44,9 @@ function OptimalControlProblems.balanced_field( γ_tf = params[:γ_tf] α_min = params[:α_min] + v_min = params[:v_min] + h_min = params[:h_min] + tf_min = params[:tf_min] α_max_ctrl = params[:α_max_ctrl] # Constants @@ -62,10 +65,10 @@ function OptimalControlProblems.balanced_field( h(tf) == h_tf γ(tf) == γ_tf - 0 ≤ α(t) ≤ α_max_ctrl - tf ≥ 0.1 - h(t) ≥ 0 - v(t) ≥ 1.0 + α_min ≤ α(t) ≤ α_max_ctrl + tf ≥ tf_min + h(t) ≥ h_min + v(t) ≥ v_min # dynamics q = 0.5 * ρ * v(t)^2 diff --git a/ext/OptimalControlScalarizedModels/brachistochrone.jl b/ext/OptimalControlScalarizedModels/brachistochrone.jl index f3798bb7e..70228e17f 100644 --- a/ext/OptimalControlScalarizedModels/brachistochrone.jl +++ b/ext/OptimalControlScalarizedModels/brachistochrone.jl @@ -28,6 +28,8 @@ function OptimalControlProblems.brachistochrone( yf = params[:yf] u_min = params[:u_min] u_max = params[:u_max] + tf_l = params[:tf_l] + tf_u = params[:tf_u] # model ocp = @def begin @@ -37,8 +39,8 @@ function OptimalControlProblems.brachistochrone( z = (px, py, v) ∈ R³, state u ∈ R, control - -1.57 ≤ u(t) ≤ 1.57 - 0.1 ≤ tf ≤ 20.0 + u_min ≤ u(t) ≤ u_max + tf_l ≤ tf ≤ tf_u z(t0) == [x0, y0, v0] diff --git a/ext/OptimalControlScalarizedModels/mountain_car.jl b/ext/OptimalControlScalarizedModels/mountain_car.jl index 715494da3..6262f1db9 100644 --- a/ext/OptimalControlScalarizedModels/mountain_car.jl +++ b/ext/OptimalControlScalarizedModels/mountain_car.jl @@ -22,7 +22,6 @@ function OptimalControlProblems.mountain_car( # parameters params = parameters_data(:mountain_car, parameters) t0 = params[:t0] - tf_start = params[:tf_start] tf_min = params[:tf_min] pos_t0 = params[:pos_t0] vel_t0 = params[:vel_t0] diff --git a/ext/OptimalControlScalarizedModels/space_shuttle.jl b/ext/OptimalControlScalarizedModels/space_shuttle.jl index 40d21a52d..be1852729 100644 --- a/ext/OptimalControlScalarizedModels/space_shuttle.jl +++ b/ext/OptimalControlScalarizedModels/space_shuttle.jl @@ -53,8 +53,6 @@ function OptimalControlProblems.space_shuttle( ψ_t0 = params[:ψ_t0] # for initial guess - α_s = params[:α_s] - β_s = params[:β_s] ## Final conditions, the so-called Terminal Area Energy Management (TAEM) h_tf = params[:h_tf] diff --git a/ext/README.md b/ext/README.md index 41d719c40..559646297 100644 --- a/ext/README.md +++ b/ext/README.md @@ -28,7 +28,10 @@ ext/ 1. **Metadata**, `MetaData/.jl`: an `OrderedDict` named `_meta` with - `:grid_size`, the default number of steps; - - `:parameters`, a `NamedTuple` of the default parameters, or `nothing`; + - `:parameters`, a `NamedTuple` of the default parameters, or `nothing`; every bound of + the problem is one of them, never a number written in a model; + - `:parameter_info`, the unit (`nothing` if none) and the meaning of each parameter, in + their order, shown on the page of the problem; - `:status`, one entry per modeling where the problem has a file, `:draft` to start with; - `:init`, the initial guess shared by every modeling, a function of the parameters returning `(state=…, control=…, variable=…)`; @@ -37,8 +40,11 @@ ext/ The schema is `METADATA_SCHEMA` in `src/Metadata/loading.jl`, checked when the package loads. -2. **Description**, `MetaData/.md`, next to the metadata: the problem in words and its mathematical - formulation, and a `### References` section with at least one entry (checked). +2. **Description**, `MetaData/.md`, next to the metadata: the problem in words, then + the sections `### Mathematical formulation`, `### Qualitative behaviour` (optional), + `### Characteristics` (what cannot be computed: the page shows the dimensions and the kinds + of constraints) and `### References`, with at least one entry. No parameters section: the + page generates it from the metadata. 3. **Models**: one file per modeling, `Models/.jl`. Copy the file of a problem with the same features (kind of cost, free times, constraints) in the same modeling: - OptimalControl: a method `OptimalControlProblems.(::OptimalControlBackend; @@ -50,13 +56,22 @@ ext/ `JuMPModels/schemes/`; - ModelingToolkit: a method that writes the continuous model with ModelingToolkit.jl (`@variables`, `Differential`, `Symbolics.Integral`, `System`) and returns `_problem(…)`. -4. **Test it**: `Pkg.test(; test_args=["problem="])` runs every test on this problem +4. **Lint it**: `julia --project tools/lint/problems.jl ` checks what the steps above + ask, the same way for every problem: the files and a status per model file, the outline and + sources of the description, `:parameter_info`, and in each model file the method and its + keywords, the draft warning, `parameters_data`, `_initial_guess`, the parameters it reads + (all used, all of the problem) and no bound written in the code (a bound is a parameter). + Its report also lists what other tools check (☑️) and what is left to check by hand (ℹ️): + no failure does not mean the problem is right. The ℹ️ list is a checklist: paste it in the + pull request and tick each box, or say why not. `test_lint` runs the linter on every + problem. +5. **Test it**: `Pkg.test(; test_args=["problem="])` runs every test on this problem only (see `test/README.md`). The consistency tests check the files and the metadata; the smoke tests that it builds and runs; the equivalence tests that two modelings give the same NLP. -5. **Valid**: once the tests pass in a modeling, set its status to `:valid`. A problem valid in +6. **Valid**: once the tests pass in a modeling, set its status to `:valid`. A problem valid in one modeling only needs a reference objective (the comparison rule, checked). -6. **Reference objective**: computed from the convergence crons by +7. **Reference objective**: computed from the convergence crons by `tools/references/update.jl` (see `tools/references/README.md`). The documentation page of the problem is generated from these files: nothing to write in diff --git a/test/suite/core/test_consistency.jl b/test/suite/core/test_consistency.jl index 64c737622..d4af7e3e1 100644 --- a/test/suite/core/test_consistency.jl +++ b/test/suite/core/test_consistency.jl @@ -51,7 +51,7 @@ function test_files() end end -"""Required and optional fields of the metadata, with their types; statuses.""" +"""Required and optional fields of the metadata, with their types; the values of the statuses.""" function test_schema() Test.@testset "metadata schema" verbose = VERBOSE begin schema = OCP.Metadata.METADATA_SCHEMA @@ -65,34 +65,9 @@ function test_schema() T = get(schema.optional, key, get(schema.generated, key, Union{})) Test.@test value isa T end - # a status is declared exactly for the modelings having a model file - statuses = data[:status] - for spec in OCP.Modelings.MODELING_SPECS - has_file = isfile(joinpath(EXT, spec.directory, "$problem.jl")) - Test.@test haskey(statuses, spec.name) == has_file - end - Test.@test all(in((:draft, :valid)), values(statuses)) - end - end -end - -""" -The unit and the meaning of every parameter (`:parameter_info`), in the order of the -parameters: the page of a problem shows them, so they are written once, in the metadata. -""" -function test_parameter_info() - Test.@testset "parameter info" verbose = VERBOSE begin - for problem in OCP.problems(; status=:all) - data = OCP.problem_metadata(problem) - info = data[:parameter_info] - parameters = data[:parameters] - Test.@test keys(info) == (isnothing(parameters) ? () : keys(parameters)) - for entry in values(info) - Test.@test entry isa NamedTuple - Test.@test keys(entry) == (:unit, :meaning) - Test.@test entry.unit isa Union{Nothing,String} - Test.@test entry.meaning isa String && !isempty(entry.meaning) - end + # a status is declared exactly for the modelings having a model file: the + # linter (`tools/lint/ProblemLint.jl`, `test_lint`) + Test.@test all(in((:draft, :valid)), values(data[:status])) end end end @@ -212,76 +187,6 @@ function test_no_handwritten_list() end end -""" -Whether the description `text` cites its sources: a heading `References` followed by at -least one list entry (#379). -""" -function cites_sources(text::AbstractString) - m = match(r"^#+ References[^\n]*\n(.*?)(?=^#|\z)"ms, text) - return !isnothing(m) && occursin(r"^\s*[-*] \S"m, m[1]) -end - -""" -The outline of a description (#449, T2): its `###` headings, in this order. The qualitative -behaviour is optional: a page whose description has none gets a placeholder -(`with_behaviour` in `docs/problems.jl`). There is no parameters section: the page generates -it from the metadata (`:parameters`, `:parameter_info`). -""" -const OUTLINE = ( - "Mathematical formulation", "Qualitative behaviour", "Characteristics", "References" -) -const REQUIRED_HEADINGS = ("Mathematical formulation", "Characteristics", "References") - -"""Whether the `###` headings of `text` follow `OUTLINE`, with every required heading.""" -function follows_outline(text::AbstractString) - headings = [m[1] for m in eachmatch(r"^### (.+?)\s*$"m, text)] - all(in(OUTLINE), headings) || return false - issorted(headings; by=h -> findfirst(==(h), OUTLINE)) || return false - allunique(headings) || return false - return all(in(headings), REQUIRED_HEADINGS) -end - -"""Every description has the same outline.""" -function test_outline() - Test.@testset "outline" verbose = VERBOSE begin - for problem in OCP.problems(; status=:all) - text = read(joinpath(EXT, "MetaData", "$problem.md"), String) - Test.@test follows_outline(text) - end - complete = "### Mathematical formulation\n### Qualitative behaviour\n### Characteristics\n### References\n" - Test.@test follows_outline(complete) - Test.@test follows_outline( - "### Mathematical formulation\n### Characteristics\n### References\n" - ) - Test.@test !follows_outline("### Characteristics\n### References\n") - # the parameters section is generated: a description has none - Test.@test !follows_outline( - "### Mathematical formulation\n### Parameters\n### Characteristics\n### References\n", - ) - Test.@test !follows_outline( - "### Mathematical formulation\n### References\n### Characteristics\n" - ) - Test.@test !follows_outline( - "### Mathematical formulation\n### Characteristics\n### References and relevance\n", - ) - end -end - -"""Every description cites its sources (#379).""" -function test_sources() - Test.@testset "sources" verbose = VERBOSE begin - for problem in OCP.problems(; status=:all) - text = read(joinpath(EXT, "MetaData", "$problem.md"), String) - Test.@test cites_sources(text) - end - Test.@test cites_sources("text\n\n### References\n\n- **A. (2000)**. *Title*.\n") - Test.@test !cites_sources("text\n\n### Formulation\n\n- an item\n") - Test.@test !cites_sources( - "text\n\n### References\n\nSee below.\n\n### Other\n\n- an item\n" - ) - end -end - """ The analytic solutions of the continuous problems (#379): a state, a control, an objective and a source for the default parameters. That they solve the problem is checked against the @@ -314,9 +219,6 @@ function test_consistency() test_comparison_rule() test_reference_objectives() test_no_handwritten_list() - test_sources() - test_parameter_info() - test_outline() test_reference_solutions() end end diff --git a/test/suite/core/test_lint.jl b/test/suite/core/test_lint.jl new file mode 100644 index 000000000..d813111d2 --- /dev/null +++ b/test/suite/core/test_lint.jl @@ -0,0 +1,238 @@ +module TestLint + +using Test: Test +using OptimalControlProblems: OptimalControlProblems + +const VERBOSE = isdefined(Main, :TestOptions) ? Main.TestOptions.VERBOSE : true +const SHOWTIMING = isdefined(Main, :TestOptions) ? Main.TestOptions.SHOWTIMING : true + +include(joinpath(pkgdir(OptimalControlProblems), "tools", "lint", "ProblemLint.jl")) +const L = ProblemLint + +# ------- an example problem, `foo`, that follows the template ------- + +const DESCRIPTION = """ +The **foo problem**. + +### Mathematical formulation + +A formulation. + +### Characteristics + +- A characteristic. + +### References + +- **A. (2000)**. *Title*. +""" + +const METADATA_TEXT = """ +foo_meta = OrderedDict( + :grid_size => 100, + :parameters => (t0=0, tf=1, x_t0=0, x_u=1, guess=0.5), + :parameter_info => (), + :status => (OptimalControl=:valid,), + :init => p -> (state=p.guess, control=0.0), +) +""" + +const MODEL = """ +\"\"\"The foo problem.\"\"\" +function OptimalControlProblems.foo( + ::OptimalControlBackend; parameters::Union{Nothing,NamedTuple}=nothing, init=nothing +) + OptimalControlProblems.Catalogue._warn_if_draft( + :foo, :OptimalControl + ) + params = parameters_data(:foo, parameters) + t0, tf = params[:t0], params[:tf] + x_t0, x_u = params[:x_t0], params[:x_u] + ocp = @def begin + t ∈ [t0, tf], time + x ∈ R, state + u ∈ R, control + x(t0) == x_t0 + x(t) ≤ x_u + ẋ(t) == u(t) + ∫(u(t)^2) → min + end + init = OptimalControlProblems.Metadata._initial_guess(:foo, params, init) + return OptimalControlProblems.Problems._problem(:foo, :OptimalControl, ocp, init, params) +end +""" + +info(names...) = NamedTuple{names}(Tuple((unit=nothing, meaning="m") for _ in names)) + +function metadata(; status=(OptimalControl=:valid,), parameter_info=:default) + parameters = (t0=0, tf=1, x_t0=0, x_u=1, guess=0.5) + data = Dict{Symbol,Any}(:grid_size => 100, :parameters => parameters, :status => status) + parameter_info === nothing || ( + data[:parameter_info] = + parameter_info === :default ? info(keys(parameters)...) : parameter_info + ) + return data +end + +function example(; model=MODEL, jump=nothing, description=DESCRIPTION, kwargs...) + return L.ProblemSource( + :foo, + metadata(; kwargs...), + METADATA_TEXT, + description, + [ + L.Model(:OptimalControl, "OptimalControlBackend", model), + L.Model(:JuMP, "JuMPBackend", jump), + ], + ) +end + +failures(src) = [r.message for r in L.checks(src) if r.status === :fail] +fails(src, needle) = any(m -> occursin(needle, m), failures(src)) + +function test_lint() + Test.@testset "problem lint" verbose = VERBOSE showtiming = SHOWTIMING begin + Test.@testset "the collection: no failure" begin + results = L.lint() + failed = filter(r -> r.status === :fail, results) + isempty(failed) || print(L.report(results)) + Test.@test isempty(failed) + end + + Test.@testset "an example that follows the template" begin + Test.@test isempty(failures(example())) + end + + Test.@testset "files and statuses" begin + Test.@test fails(example(; description=nothing), "a description") + # a status without a model file, a model file without a status + Test.@test fails( + example(; status=(OptimalControl=:valid, JuMP=:draft)), "no status for JuMP" + ) + Test.@test fails(example(; status=NamedTuple()), "a status for OptimalControl") + end + + Test.@testset "description" begin + Test.@test fails( + example(; + description=replace(DESCRIPTION, "### References" => "### Sources") + ), + "the outline", + ) + no_entry = replace(DESCRIPTION, "- **A. (2000)**. *Title*." => "See the web.") + Test.@test fails( + example(; description=no_entry), "`### References` with entries" + ) + # the outline: the order, the required headings, no parameters section + Test.@test L.follows_outline( + "### Mathematical formulation\n### Qualitative behaviour\n### Characteristics\n### References\n", + ) + Test.@test !L.follows_outline("### Characteristics\n### References\n") + Test.@test !L.follows_outline( + "### Mathematical formulation\n### Parameters\n### Characteristics\n### References\n", + ) + Test.@test !L.follows_outline( + "### Mathematical formulation\n### References\n### Characteristics\n" + ) + Test.@test L.cites_sources("text\n\n### References\n\n- **A. (2000)**. *T*.\n") + Test.@test !L.cites_sources( + "text\n\n### References\n\nSee below.\n\n### Other\n\n- an item\n" + ) + end + + Test.@testset "parameter info" begin + Test.@test fails(example(; parameter_info=nothing), "a `:parameter_info`") + Test.@test fails( + example(; parameter_info=info(:t0, :tf)), "describes exactly the parameters" + ) + bad = merge(info(:t0, :tf, :x_t0, :x_u), (guess=(unit=nothing, meaning=""),)) + Test.@test fails(example(; parameter_info=bad), "not guess") + end + + Test.@testset "template of a model" begin + for (needle, what) in ( + ("\"\"\"The foo problem.\"\"\"\n" => "", "a docstring"), + ("init=nothing" => "init", "the keyword `init=nothing`"), + (":foo, :OptimalControl\n" => ":foo, :JuMP\n", "the draft warning"), + ( + "parameters_data(:foo, parameters)" => "parameters_data(:bar, parameters)", + "the parameters", + ), + ("_initial_guess(:foo," => "initial(:foo,", "the initial guess"), + ("_problem(:foo, :OptimalControl," => "_problem(:foo, :JuMP,", "_problem"), + ) + Test.@test fails(example(; model=replace(MODEL, needle)), what) + end + # JuMP: its own keywords + jump = replace( + MODEL, + "::OptimalControlBackend; parameters" => "::JuMPBackend, args...; parameters", + ":foo, :OptimalControl\n" => ":foo, :JuMP\n", + ) + src = example(; jump, status=(OptimalControl=:valid, JuMP=:draft)) + Test.@test fails(src, "the keyword `grid_size`") + Test.@test fails(src, "the keyword `scheme`") + end + + Test.@testset "parameters of a model" begin + # read and not used + unused = replace(MODEL, "x(t) ≤ x_u" => "x(t) ≤ 1 + 0") + Test.@test fails( + example(; model=unused), "uses every parameter it reads: not x_u" + ) + # read but not a parameter of the problem + unknown = replace(MODEL, "params[:x_u]" => "params[:x_max]") + Test.@test fails(example(; model=unknown), "not x_max") + # a parameter read by nothing: neither a model nor the metadata + Test.@test fails( + example(; + model=replace( + MODEL, + "x_t0, x_u = params[:x_t0], params[:x_u]" => "x_t0, x_u = params[:x_t0], 1.0", + "x(t) ≤ x_u" => "x(t) ≤ x_u", + ), + ), + "read by a model or by the metadata", + ) + # `guess` is read by the initial guess of the metadata only: fine + Test.@test !fails(example(), "not guess") + Test.@test L.parameters_read("(; a, b) = params\nc = params[:c]") == + ["c", "a", "b"] + end + + Test.@testset "bounds written in the code" begin + Test.@test fails( + example(; model=replace(MODEL, "x(t) ≤ x_u" => "x(t) ≤ 1.5")), + "no bound written in the code", + ) + Test.@test L.literal_bounds(" -1.57 ≤ u(t) ≤ 1.57") == + ["-1.57 ≤ u(t) ≤ 1.57"] + Test.@test L.literal_bounds(" tf ≥ 0") == ["tf ≥ 0"] + Test.@test L.literal_bounds("Component(\"v\"; lower=1.0)") == + ["Component(\"v\"; lower=1.0)"] + # an index, a subscript, an exponent or a comment is not a bound + Test.@test isempty(L.literal_bounds(" x[1](t) ≥ x₁_l")) + Test.@test isempty(L.literal_bounds(" x₁(t) ≤ x1_max")) + Test.@test isempty(L.literal_bounds(" u(t)^2 ≤ u_u # at most 2")) + end + + Test.@testset "report" begin + results = L.checks(example(; model=replace(MODEL, "x(t) ≤ x_u" => "x(t) ≤ 2"))) + text = L.report(results) + Test.@test occursin("❌ 2 failure(s)", text) + Test.@test occursin("| ❌ | `foo` | model OptimalControl |", text) + # it always says what it does not check + Test.@test occursin("Checked by other tools", text) + Test.@test occursin("To check by hand, for `foo`", text) + Test.@test occursin("- [ ] the mathematical formulation", text) + Test.@test occursin("not that a problem is right", text) + Test.@test !occursin("| ✅ | `foo`", text) + Test.@test occursin("| ✅ | `foo`", L.report(results; verbose=true)) + Test.@test occursin("✅ no failure", L.report(L.checks(example()))) + end + end +end + +end # module TestLint + +test_lint() = TestLint.test_lint() diff --git a/tools/lint/ProblemLint.jl b/tools/lint/ProblemLint.jl new file mode 100644 index 000000000..c70a5b7b0 --- /dev/null +++ b/tools/lint/ProblemLint.jl @@ -0,0 +1,397 @@ +# The linter of the problems (#449, T3): what a problem must have, checked the same way for +# every problem, so that an agent or a person adding one knows what is missing. It says what +# it checks (✅/❌), what other tools check (☑️), and what is left to check by hand (ℹ️): no +# failure here does not mean that a problem is right. +# +# Used by `tools/lint/problems.jl` (the command line) and by `test/suite/core/test_lint.jl` +# (no failure allowed). The checks read the files of the problem as text and its metadata +# through the package; they are pure functions of a `ProblemSource`, which the tests build by +# hand. +module ProblemLint + +using OptimalControlProblems: OptimalControlProblems + +const OCP = OptimalControlProblems + +"""One check: `:pass` or `:fail`, the area it belongs to, and what it says.""" +struct Check + problem::Symbol + status::Symbol + area::String + message::String +end + +"""The model of a problem in one modeling: its name, backend, and file text (`nothing` when +the problem has no file in this modeling).""" +struct Model + modeling::Symbol + backend::String + text::Union{Nothing,String} +end + +"""Everything the checks read about a problem.""" +struct ProblemSource + name::Symbol + metadata::AbstractDict + metadata_text::String + description::Union{Nothing,String} + models::Vector{Model} +end + +"""The `ProblemSource` of `problem`, read from the files of the package under `root`.""" +function source(problem::Symbol; root::AbstractString=pkgdir(OCP)) + ext = joinpath(root, "ext") + read_or_nothing(path) = isfile(path) ? read(path, String) : nothing + models = [ + Model( + spec.name, + string(nameof(spec.backend)), + read_or_nothing(joinpath(ext, spec.directory, "$(problem).jl")), + ) for spec in OCP.Modelings.MODELING_SPECS + ] + return ProblemSource( + problem, + OCP.problem_metadata(problem), + read(joinpath(ext, "MetaData", "$(problem).jl"), String), + read_or_nothing(joinpath(ext, "MetaData", "$(problem).md")), + models, + ) +end + +# ------------------------------------------------------------------------------------------ +# Descriptions +# ------------------------------------------------------------------------------------------ + +""" +The outline of a description: its `###` headings, in this order. The qualitative behaviour +is optional: a page whose description has none gets a placeholder (`with_behaviour` in +`docs/problems.jl`). There is no parameters section: the page generates it from the metadata +(`:parameters`, `:parameter_info`). +""" +const OUTLINE = ( + "Mathematical formulation", "Qualitative behaviour", "Characteristics", "References" +) +const REQUIRED_HEADINGS = ("Mathematical formulation", "Characteristics", "References") + +"""Whether the `###` headings of `text` follow `OUTLINE`, with every required heading.""" +function follows_outline(text::AbstractString) + headings = [m[1] for m in eachmatch(r"^### (.+?)\s*$"m, text)] + all(in(OUTLINE), headings) || return false + issorted(headings; by=h -> findfirst(==(h), OUTLINE)) || return false + allunique(headings) || return false + return all(in(headings), REQUIRED_HEADINGS) +end + +""" +Whether the description `text` cites its sources: a heading `References` followed by at +least one list entry (#379). +""" +function cites_sources(text::AbstractString) + m = match(r"^#+ References[^\n]*\n(.*?)(?=^#|\z)"ms, text) + return !isnothing(m) && occursin(r"^\s*[-*] \S"m, m[1]) +end + +# ------------------------------------------------------------------------------------------ +# Models +# ------------------------------------------------------------------------------------------ + +""" +The template of a model file, by modeling (`ext/README.md`, "Add a problem"): what every +file of the modeling contains, as `(what, regex)` pairs; `P` stands for the problem, `M` for +the modeling, `B` for its backend type. +""" +function template(modeling::Symbol, problem::Symbol, backend::AbstractString) + p = string(problem) + m = string(modeling) + items = [ + ("a docstring first", r"\A\"\"\""), + ( + "the method `OptimalControlProblems.$p(::$backend; …)`", + Regex("function OptimalControlProblems\\.$p\\(\\s*::$backend\\b"), + ), + ( + "the keyword `parameters::Union{Nothing,NamedTuple}=nothing`", + r"parameters::Union\{Nothing,NamedTuple\}=nothing", + ), + ("the keyword `init=nothing`", r"\binit=nothing"), + ( + "the draft warning `_warn_if_draft(:$p, :$m)`", + Regex("_warn_if_draft\\(\\s*:$p,\\s*:$m\\s*\\)"), + ), + ( + "the parameters `parameters_data(:$p, parameters)`", + Regex("parameters_data\\(\\s*:$p,\\s*parameters\\s*\\)"), + ), + ( + "the initial guess of the metadata `_initial_guess(:$p, …)` (#377)", + Regex("_initial_guess\\(\\s*:$p\\s*,"), + ), + ] + if modeling in (:OptimalControl, :OptimalControlScalarized) + push!( + items, + ( + "the returned `Problems._problem(:$p, :$m, …)`", + Regex("_problem\\(\\s*:$p,\\s*:$m\\s*,"), + ), + ) + elseif modeling === :JuMP + push!( + items, + ("the keyword `grid_size`", Regex("grid_size::Int=grid_size_data\\(:$p\\)")), + ) + push!(items, ("the keyword `scheme`", r"scheme::Symbol=:trapeze")) + end + return items +end + +"""The names a model file reads from the parameters: `params[:x]` and `(; x, y) = params`.""" +function parameters_read(text::AbstractString) + names = [m[1] for m in eachmatch(r"params\[:([^\]\s]+)\]", text)] + for m in eachmatch(r"\(;\s*([^)]*?)\)\s*=\s*params\b", text) + append!(names, strip.(split(m[1], ','))) + end + return unique!(filter!(!isempty, String.(names))) +end + +"""How many times `name` appears in `text` as a whole name, `p.name` included (the initial +guess of the metadata reads `p.name`), not as `:name`.""" +function occurrences(name::AbstractString, text::AbstractString) + return count( + _ -> true, eachmatch(Regex("(? s"\\\1") + +"""The code of a line, without its comment.""" +code(line) = first(split(line, '#'; limit=2)) + +""" +The lines of `text` that bound something with a number written in the code: a constraint +(`≤`, `≥`, `<=`, `>=`) or a `lower=`, `upper=`, `bounds=` with a numeric literal. A bound is +a parameter of the problem, so that a user can change it and the page shows it. +""" +function literal_bounds(text::AbstractString) + found = String[] + for line in split(text, '\n') + c = code(line) + occursin(r"≤|≥|<=|>=|\blower\s*=|\bupper\s*=|\bbounds\s*=", c) || continue + occursin(r"(?", text) + isnothing(i) && continue + k = findnext('(', text, last(i)) + depth = 0 + while k <= lastindex(text) + text[k] == '(' && (depth += 1) + text[k] == ')' && (depth -= 1) + depth == 0 && break + k = nextind(text, k) + end + text = text[1:prevind(text, first(i))] * text[nextind(text, k):end] + end + return text +end + +# ------------------------------------------------------------------------------------------ +# Checks +# ------------------------------------------------------------------------------------------ + +"""Every check of the problem `src`, in order: files, description, metadata, models.""" +function checks(src::ProblemSource) + results = Check[] + p = src.name + add(ok, area, message) = push!(results, Check(p, ok ? :pass : :fail, area, message)) + + # files: the description, and a status for each modeling with a file, only for those + add(!isnothing(src.description), "files", "a description `ext/MetaData/$p.md`") + statuses = src.metadata[:status] + for model in src.models + has_file = !isnothing(model.text) + declared = haskey(statuses, model.modeling) + add( + has_file == declared, + "files", + if has_file + "a status for $(model.modeling), which has a model file" + else + "no status for $(model.modeling), which has no model file" + end, + ) + end + add( + any(m -> !isnothing(m.text), src.models), + "files", + "a model in one modeling at least", + ) + + # the description: one outline, sources + if !isnothing(src.description) + add( + follows_outline(src.description), + "description", + "the outline: $(join(OUTLINE, ", ")) (qualitative behaviour optional)", + ) + add( + cites_sources(src.description), "description", "a `### References` with entries" + ) + end + + # the metadata: the unit and meaning of every parameter + parameters = src.metadata[:parameters] + names = isnothing(parameters) ? String[] : String.(collect(keys(parameters))) + info = get(src.metadata, :parameter_info, nothing) + if isnothing(info) + add(false, "parameters", "a `:parameter_info`") + else + add( + String.(collect(keys(info))) == names, + "parameters", + "`:parameter_info` describes exactly the parameters, in their order", + ) + bad = [ + String(k) for (k, e) in pairs(info) if !( + e isa NamedTuple && + keys(e) == (:unit, :meaning) && + e.unit isa Union{Nothing,String} && + e.meaning isa String && + !isempty(e.meaning) + ) + ] + add( + isempty(bad), + "parameters", + "every entry of `:parameter_info` is `(unit, meaning)`" * + (isempty(bad) ? "" : ": not $(join(bad, ", "))"), + ) + end + + # the models: the template, the parameters they read, no bound written in the code + read_somewhere = Set{String}() + for model in src.models + isnothing(model.text) && continue + text = model.text + where = "model $(model.modeling)" + for (what, regex) in template(model.modeling, p, model.backend) + add(occursin(regex, text), where, what) + end + read = parameters_read(text) + union!(read_somewhere, read) + unknown = setdiff(read, names) + add( + isempty(unknown), + where, + "reads parameters of the problem only" * + (isempty(unknown) ? "" : ": not $(join(unknown, ", "))"), + ) + unused = [n for n in read if occurrences(n, text) <= 1] + add( + isempty(unused), + where, + "uses every parameter it reads" * + (isempty(unused) ? "" : ": not $(join(unused, ", "))"), + ) + bounds = literal_bounds(text) + add( + isempty(bounds), + where, + "no bound written in the code" * + (isempty(bounds) ? "" : ": $(join(("`$b`" for b in bounds), ", "))"), + ) + end + init_code = metadata_code(src.metadata_text) + unread = [n for n in names if !(n in read_somewhere) && occurrences(n, init_code) == 0] + add( + isempty(unread), + "parameters", + "every parameter is read by a model or by the metadata (initial guess, solution)" * + (isempty(unread) ? "" : ": not $(join(unread, ", "))"), + ) + return results +end + +"""The checks of `problems` (every problem of the collection by default).""" +function lint(problems=OCP.problems(; status=:all); root::AbstractString=pkgdir(OCP)) + return reduce(vcat, (checks(source(p; root)) for p in problems); init=Check[]) +end + +# ------------------------------------------------------------------------------------------ +# Report +# ------------------------------------------------------------------------------------------ + +"""What other tools check (☑️), with the tool: the linter does not repeat it.""" +const ELSEWHERE = ( + "the types of the metadata fields" => "the package, when it loads (`src/Metadata/loading.jl`), and `test_schema`", + "the files of `ext/`: one metadata file and one description per problem, nothing else" => "`test_files` (`test/suite/core/test_consistency.jl`)", + "a `:valid` problem has a reference (another `:valid` modeling or a reference objective)" => "`test_comparison_rule`", + "the names of the components, the dynamics, the cost and the constraints agree between the modelings of a problem, where it is `:valid` in two" => "the tests of each modeling (`test_features`, the continuous comparison, `test/common/continuous.jl`)", + "the NLP of JuMP and that of CTDirect agree" => "the comparison cron (#441)", + "the problem is solved, and to the reference objective" => "the convergence crons (#360), reported, not tested", +) + +"""What no tool checks (ℹ️): left to the person who writes or reviews the problem.""" +const MANUAL = ( + "the mathematical formulation of the description is the one of the models", + "the meaning and the unit of each parameter (`:parameter_info`) are right", + "the sources of the description are those of the problem and its values", + "the qualitative behaviour and the characteristics of the description are true", + "the signs of the costates and of the duals (`rules/signs.md`, #326, #430)", +) + +""" +The report of `results` in Markdown: a line per problem, the failures, what other tools +check and what is left to check by hand, as a checklist for the pull request. With +`verbose`, every check. +""" +function report(results::Vector{Check}; verbose::Bool=false) + io = IOBuffer() + problems = unique(r.problem for r in results) + failed = filter(r -> r.status === :fail, results) + println( + io, + "## Problem lint — $(length(problems)) problem(s), $(length(results)) checks: ", + isempty(failed) ? "✅ no failure" : "❌ $(length(failed)) failure(s)", + "\n", + ) + println(io, "| Problem | ✅ | ❌ |\n| --- | --- | --- |") + for p in problems + mine = filter(r -> r.problem === p, results) + n = count(r -> r.status === :fail, mine) + println(io, "| `$p` | $(length(mine) - n) | $(n == 0 ? "" : n) |") + end + shown = verbose ? results : failed + if !isempty(shown) + println(io, "\n### ", verbose ? "Checks" : "Failures", "\n") + println(io, "| | Problem | Area | Check |\n| --- | --- | --- | --- |") + for r in shown + mark = r.status === :pass ? "✅" : "❌" + println(io, "| $mark | `$(r.problem)` | $(r.area) | $(r.message) |") + end + end + println(io, "\n### ☑️ Checked by other tools, not by this linter\n") + for (what, tool) in ELSEWHERE + println(io, "- ", what, ": ", tool, ".") + end + names = join(("`$p`" for p in problems), ", ") + println(io, "\n### ℹ️ To check by hand, for $names\n") + println(io, "To paste in the pull request, each box ticked or the reason why not:\n") + for what in MANUAL + println(io, "- [ ] ", what, ".") + end + println( + io, + "\nNo failure means that the automatic checks above pass, not that a problem is ", + "right: the points checked by other tools and by hand are not covered here.", + ) + return String(take!(io)) +end + +end # module ProblemLint diff --git a/tools/lint/problems.jl b/tools/lint/problems.jl new file mode 100644 index 000000000..b125c3805 --- /dev/null +++ b/tools/lint/problems.jl @@ -0,0 +1,23 @@ +# The linter of the problems (#449): what a problem must have, checked for every problem. +# +# julia --project tools/lint/problems.jl # every problem +# julia --project tools/lint/problems.jl beam chain # some problems +# julia --project tools/lint/problems.jl --verbose beam # every check, not only failures +# +# Prints a Markdown report: the checks of the linter (✅/❌), what other tools check (☑️) and +# what is left to check by hand (ℹ️). Exits with 1 when a check fails. The checks are in +# `ProblemLint.jl`; `test/suite/core/test_lint.jl` runs them on the collection and on +# examples. +using OptimalControlProblems: OptimalControlProblems + +include(joinpath(@__DIR__, "ProblemLint.jl")) + +verbose = "--verbose" in ARGS +names = Symbol.(filter(!=("--verbose"), ARGS)) +problems = isempty(names) ? OptimalControlProblems.problems(; status=:all) : names +unknown = setdiff(problems, OptimalControlProblems.problems(; status=:all)) +isempty(unknown) || error("unknown problems: $(join(unknown, ", "))") + +results = ProblemLint.lint(problems) +print(ProblemLint.report(results; verbose)) +exit(any(r -> r.status === :fail, results) ? 1 : 0)