refactor: split src into submodules, keeping the public API (#413)

docs/api_reference.jl

@@ -2,8 +2,9 @@
 # OptimalControlProblems API Reference Manager
 #
 # One CTBase automatic_reference_documentation call per documented page (SITE1, SITE2).
-# Keep the file lists in sync with src/ and ext/ when files are added, removed, or
-# renamed, otherwise docstrings silently drop out of the reference.
+# The files of the package are read from `src/<Submodule>/`; keep the lists of the
+# extensions in sync with ext/ when files are added, removed, or renamed, otherwise
+# docstrings silently drop out of the reference.
 #
 # The problem functions (`beam`, `chain`, …) are left out: each problem has its own page.
 # ==============================================================================
@@ -21,10 +22,28 @@ function generate_api_reference(src_dir::String, ext_dir::String)
     ext(files...) = [abspath(joinpath(ext_dir, f)) for f in files]
 
     EXCLUDE_SYMBOLS = vcat(
-        Symbol[:include, :eval], collect(OptimalControlProblems.PROBLEM_NAMES)
+        Symbol[:include, :eval], collect(OptimalControlProblems.Metadata.PROBLEM_NAMES)
     )
 
-    package_files = src("OptimalControlProblems.jl", "problem.jl", "solutions.jl")
+    # The package and its submodules (#413), each with the files of its directory
+    # `src/<Name>/`: both lists are read from the package, never written here. The public API
+    # of a submodule is what it exports (the package re-exports part of it).
+    O = OptimalControlProblems
+    submodules = sort!(
+        [
+            m for m in (getfield(O, n) for n in names(O; all=true)) if
+            m isa Module && m !== O && parentmodule(m) === O
+        ];
+        by=nameof,
+    )
+    files_of(m) = sort!([
+        abspath(f) for f in readdir(joinpath(src_dir, string(nameof(m))); join=true) if
+        endswith(f, ".jl")
+    ])
+    package_modules = Any[
+        O => src("OptimalControlProblems.jl");
+        [m => files_of(m) for m in submodules]
+    ]
 
     # ── Extensions: their methods extend the package functions, and what is their own is
     #    private, so they appear in the Internals page only (loaded conditionally) ──
@@ -49,7 +68,7 @@ function generate_api_reference(src_dir::String, ext_dir::String)
     # ── Public page: the package ──────────────────────────────────────────────
     pages = Any[reference_documentation(;
         subdirectory="api",
-        primary_modules=[OptimalControlProblems => package_files],
+        primary_modules=package_modules,
         exclude=EXCLUDE_SYMBOLS,
         public=true,
         private=false,
@@ -59,7 +78,7 @@ function generate_api_reference(src_dir::String, ext_dir::String)
     ),]
 
     # ── Internals: all private symbols in one page, sections by module ────────
-    internals_modules = Any[OptimalControlProblems => package_files]
+    internals_modules = Any[package_modules...]
     for entry in loaded_extensions
         push!(internals_modules, entry.mod => entry.cfg.files)
     end

docs/modelings.jl

@@ -1,5 +1,5 @@
 # Documentation adapters: what the documentation needs to know about each modeling. One entry
-# per modeling of `OptimalControlProblems.MODELING_SPECS`, the single place where a modeling is
+# per modeling of `OptimalControlProblems.Modelings.MODELING_SPECS`, the single place where a modeling is
 # named; the page generators loop over the modelings and never name one.
 #
 # - `title`: display name;
@@ -76,14 +76,14 @@ const ADAPTERS = Dict{Symbol,NamedTuple}(
 )
 
 # A modeling without an adapter would be missing from every page: fail the build instead.
-for spec in OptimalControlProblems.MODELING_SPECS
+for spec in OptimalControlProblems.Modelings.MODELING_SPECS
     haskey(ADAPTERS, spec.name) ||
         error("No documentation adapter for the modeling $(spec.name) in docs/modelings.jl")
 end
 
 """The modelings, in the order of the modeling table, as `(spec, adapter)` pairs."""
 modelings() =
-    [(spec, ADAPTERS[spec.name]) for spec in OptimalControlProblems.MODELING_SPECS]
+    [(spec, ADAPTERS[spec.name]) for spec in OptimalControlProblems.Modelings.MODELING_SPECS]
 
 """The modelings in which `problem` exists, whatever its status there."""
 function modelings(problem::Symbol)

docs/problems.jl

@@ -34,7 +34,7 @@ function gap_string(g::Real)
     return @sprintf("%.1e", g)
 end
 
-relative_gap(a, b) = OCP._relative_gap(a, b)
+relative_gap(a, b) = OCP.References._relative_gap(a, b)
 
 function objective_range(values)
     lo, hi = extrema(values)

docs/results.jl

@@ -138,7 +138,7 @@ function publish_results!(results::SolveResults)
         end
         data = Dict(
             "problem" => string(problem),
-            "fingerprint" => OCP._fingerprint(problem),
+            "fingerprint" => OCP.Catalogue._fingerprint(problem),
             "entries" => entries,
         )
         write(joinpath(RESULTS_PUBLIC, "$(problem).json"), JSON.json(data))
@@ -238,7 +238,7 @@ version of the problem: same fingerprint) or `:stale`.
 function freshness(problem::Symbol, modeling::Symbol)
     entries = convergence_entries(problem, modeling)
     isempty(entries) && return :missing
-    current = OCP._fingerprint(problem)
+    current = OCP.Catalogue._fingerprint(problem)
     return all(e -> get(e, "fingerprint", "") == current, entries) ? :current : :stale
 end
 

ext/JuMPModels/balanced_field.jl

@@ -25,7 +25,7 @@ function OptimalControlProblems.balanced_field(
     init=nothing,
     kwargs...,
 )
-    OptimalControlProblems._warn_if_draft(:balanced_field, :JuMP)
+    OptimalControlProblems.Catalogue._warn_if_draft(:balanced_field, :JuMP)
 
     # parameters
     params = parameters_data(:balanced_field, parameters)
@@ -99,6 +99,6 @@ function OptimalControlProblems.balanced_field(
         ],
     )
     # initial guess: from the metadata (#377), unless given
-    init = OptimalControlProblems._initial_guess(:balanced_field, params, init)
+    init = OptimalControlProblems.Metadata._initial_guess(:balanced_field, params, init)
     return build(data, grid_size, scheme, ordering, args...; init=init, kwargs...)
 end

ext/JuMPModels/beam.jl

@@ -25,7 +25,7 @@ function OptimalControlProblems.beam(
     init=nothing,
     kwargs...,
 )
-    OptimalControlProblems._warn_if_draft(:beam, :JuMP)
+    OptimalControlProblems.Catalogue._warn_if_draft(:beam, :JuMP)
 
     # parameters
     params = parameters_data(:beam, parameters)
@@ -55,6 +55,6 @@ function OptimalControlProblems.beam(
         ],
     )
     # initial guess: from the metadata (#377), unless given
-    init = OptimalControlProblems._initial_guess(:beam, params, init)
+    init = OptimalControlProblems.Metadata._initial_guess(:beam, params, init)
     return build(data, grid_size, scheme, ordering, args...; init=init, kwargs...)
 end

ext/JuMPModels/bioreactor.jl

@@ -25,7 +25,7 @@ function OptimalControlProblems.bioreactor(
     init=nothing,
     kwargs...,
 )
-    OptimalControlProblems._warn_if_draft(:bioreactor, :JuMP)
+    OptimalControlProblems.Catalogue._warn_if_draft(:bioreactor, :JuMP)
 
     # parameters
     params = parameters_data(:bioreactor, parameters)
@@ -83,6 +83,6 @@ function OptimalControlProblems.bioreactor(
         ],
     )
     # initial guess: from the metadata (#377), unless given
-    init = OptimalControlProblems._initial_guess(:bioreactor, params, init)
+    init = OptimalControlProblems.Metadata._initial_guess(:bioreactor, params, init)
     return build(data, grid_size, scheme, ordering, args...; init=init, kwargs...)
 end

ext/JuMPModels/brachistochrone.jl

@@ -25,7 +25,7 @@ function OptimalControlProblems.brachistochrone(
     init=nothing,
     kwargs...,
 )
-    OptimalControlProblems._warn_if_draft(:brachistochrone, :JuMP)
+    OptimalControlProblems.Catalogue._warn_if_draft(:brachistochrone, :JuMP)
 
     # parameters
     params = parameters_data(:brachistochrone, parameters)
@@ -61,6 +61,6 @@ function OptimalControlProblems.brachistochrone(
         ],
     )
     # initial guess: from the metadata (#377), unless given
-    init = OptimalControlProblems._initial_guess(:brachistochrone, params, init)
+    init = OptimalControlProblems.Metadata._initial_guess(:brachistochrone, params, init)
     return build(data, grid_size, scheme, ordering, args...; init=init, kwargs...)
 end

ext/JuMPModels/bryson_denham.jl

@@ -25,7 +25,7 @@ function OptimalControlProblems.bryson_denham(
     init=nothing,
     kwargs...,
 )
-    OptimalControlProblems._warn_if_draft(:bryson_denham, :JuMP)
+    OptimalControlProblems.Catalogue._warn_if_draft(:bryson_denham, :JuMP)
     params = parameters_data(:bryson_denham, parameters)
     t0, tf = params[:t0], params[:tf]
     x1_t0, x2_t0 = params[:x1_t0], params[:x2_t0]
@@ -47,6 +47,6 @@ function OptimalControlProblems.bryson_denham(
         ],
     )
     # initial guess: from the metadata (#377), unless given
-    init = OptimalControlProblems._initial_guess(:bryson_denham, params, init)
+    init = OptimalControlProblems.Metadata._initial_guess(:bryson_denham, params, init)
     return build(data, grid_size, scheme, ordering, args...; init=init, kwargs...)
 end

ext/JuMPModels/cart_pendulum.jl

@@ -25,7 +25,7 @@ function OptimalControlProblems.cart_pendulum(
     init=nothing,
     kwargs...,
 )
-    OptimalControlProblems._warn_if_draft(:cart_pendulum, :JuMP)
+    OptimalControlProblems.Catalogue._warn_if_draft(:cart_pendulum, :JuMP)
 
     # parameters
     params = parameters_data(:cart_pendulum, parameters)
@@ -86,6 +86,6 @@ function OptimalControlProblems.cart_pendulum(
         ],
     )
     # initial guess: from the metadata (#377), unless given
-    init = OptimalControlProblems._initial_guess(:cart_pendulum, params, init)
+    init = OptimalControlProblems.Metadata._initial_guess(:cart_pendulum, params, init)
     return build(data, grid_size, scheme, ordering, args...; init=init, kwargs...)
 end

ext/JuMPModels/chain.jl

@@ -25,7 +25,7 @@ function OptimalControlProblems.chain(
     init=nothing,
     kwargs...,
 )
-    OptimalControlProblems._warn_if_draft(:chain, :JuMP)
+    OptimalControlProblems.Catalogue._warn_if_draft(:chain, :JuMP)
 
     # parameters
     params = parameters_data(:chain, parameters)
@@ -60,6 +60,6 @@ function OptimalControlProblems.chain(
         ],
     )
     # initial guess: from the metadata (#377), unless given
-    init = OptimalControlProblems._initial_guess(:chain, params, init)
+    init = OptimalControlProblems.Metadata._initial_guess(:chain, params, init)
     return build(data, grid_size, scheme, ordering, args...; init=init, kwargs...)
 end

ext/JuMPModels/dielectrophoretic_particle.jl

@@ -25,7 +25,7 @@ function OptimalControlProblems.dielectrophoretic_particle(
     init=nothing,
     kwargs...,
 )
-    OptimalControlProblems._warn_if_draft(:dielectrophoretic_particle, :JuMP)
+    OptimalControlProblems.Catalogue._warn_if_draft(:dielectrophoretic_particle, :JuMP)
 
     # parameters
     params = parameters_data(:dielectrophoretic_particle, parameters)
@@ -54,6 +54,6 @@ function OptimalControlProblems.dielectrophoretic_particle(
         ],
     )
     # initial guess: from the metadata (#377), unless given
-    init = OptimalControlProblems._initial_guess(:dielectrophoretic_particle, params, init)
+    init = OptimalControlProblems.Metadata._initial_guess(:dielectrophoretic_particle, params, init)
     return build(data, grid_size, scheme, ordering, args...; init=init, kwargs...)
 end

ext/JuMPModels/double_oscillator.jl

@@ -25,7 +25,7 @@ function OptimalControlProblems.double_oscillator(
     init=nothing,
     kwargs...,
 )
-    OptimalControlProblems._warn_if_draft(:double_oscillator, :JuMP)
+    OptimalControlProblems.Catalogue._warn_if_draft(:double_oscillator, :JuMP)
 
     # parameters
     params = parameters_data(:double_oscillator, parameters)
@@ -64,6 +64,6 @@ function OptimalControlProblems.double_oscillator(
         ],
     )
     # initial guess: from the metadata (#377), unless given
-    init = OptimalControlProblems._initial_guess(:double_oscillator, params, init)
+    init = OptimalControlProblems.Metadata._initial_guess(:double_oscillator, params, init)
     return build(data, grid_size, scheme, ordering, args...; init=init, kwargs...)
 end

ext/JuMPModels/ducted_fan.jl

@@ -25,7 +25,7 @@ function OptimalControlProblems.ducted_fan(
     init=nothing,
     kwargs...,
 )
-    OptimalControlProblems._warn_if_draft(:ducted_fan, :JuMP)
+    OptimalControlProblems.Catalogue._warn_if_draft(:ducted_fan, :JuMP)
 
     # parameters
     params = parameters_data(:ducted_fan, parameters)
@@ -103,6 +103,6 @@ function OptimalControlProblems.ducted_fan(
         ],
     )
     # initial guess: from the metadata (#377), unless given
-    init = OptimalControlProblems._initial_guess(:ducted_fan, params, init)
+    init = OptimalControlProblems.Metadata._initial_guess(:ducted_fan, params, init)
     return build(data, grid_size, scheme, ordering, args...; init=init, kwargs...)
 end

ext/JuMPModels/electric_vehicle.jl

@@ -25,7 +25,7 @@ function OptimalControlProblems.electric_vehicle(
     init=nothing,
     kwargs...,
 )
-    OptimalControlProblems._warn_if_draft(:electric_vehicle, :JuMP)
+    OptimalControlProblems.Catalogue._warn_if_draft(:electric_vehicle, :JuMP)
 
     # parameters
     params = parameters_data(:electric_vehicle, parameters)
@@ -66,6 +66,6 @@ function OptimalControlProblems.electric_vehicle(
         ],
     )
     # initial guess: from the metadata (#377), unless given
-    init = OptimalControlProblems._initial_guess(:electric_vehicle, params, init)
+    init = OptimalControlProblems.Metadata._initial_guess(:electric_vehicle, params, init)
     return build(data, grid_size, scheme, ordering, args...; init=init, kwargs...)
 end

ext/JuMPModels/glider.jl

@@ -25,7 +25,7 @@ function OptimalControlProblems.glider(
     init=nothing,
     kwargs...,
 )
-    OptimalControlProblems._warn_if_draft(:glider, :JuMP)
+    OptimalControlProblems.Catalogue._warn_if_draft(:glider, :JuMP)
 
     # parameters
     params = parameters_data(:glider, parameters)
@@ -87,6 +87,6 @@ function OptimalControlProblems.glider(
         ],
     )
     # initial guess: from the metadata (#377), unless given
-    init = OptimalControlProblems._initial_guess(:glider, params, init)
+    init = OptimalControlProblems.Metadata._initial_guess(:glider, params, init)
     return build(data, grid_size, scheme, ordering, args...; init=init, kwargs...)
 end

ext/JuMPModels/insurance.jl

@@ -25,7 +25,7 @@ function OptimalControlProblems.insurance(
     init=nothing,
     kwargs...,
 )
-    OptimalControlProblems._warn_if_draft(:insurance, :JuMP)
+    OptimalControlProblems.Catalogue._warn_if_draft(:insurance, :JuMP)
 
     # parameters
     params = parameters_data(:insurance, parameters)
@@ -100,6 +100,6 @@ function OptimalControlProblems.insurance(
         ],
     )
     # initial guess: from the metadata (#377), unless given
-    init = OptimalControlProblems._initial_guess(:insurance, params, init)
+    init = OptimalControlProblems.Metadata._initial_guess(:insurance, params, init)
     return build(data, grid_size, scheme, ordering, args...; init=init, kwargs...)
 end

ext/JuMPModels/jackson.jl

@@ -25,7 +25,7 @@ function OptimalControlProblems.jackson(
     init=nothing,
     kwargs...,
 )
-    OptimalControlProblems._warn_if_draft(:jackson, :JuMP)
+    OptimalControlProblems.Catalogue._warn_if_draft(:jackson, :JuMP)
 
     # parameters
     params = parameters_data(:jackson, parameters)
@@ -73,6 +73,6 @@ function OptimalControlProblems.jackson(
         ],
     )
     # initial guess: from the metadata (#377), unless given
-    init = OptimalControlProblems._initial_guess(:jackson, params, init)
+    init = OptimalControlProblems.Metadata._initial_guess(:jackson, params, init)
     return build(data, grid_size, scheme, ordering, args...; init=init, kwargs...)
 end

ext/JuMPModels/moonlander.jl

@@ -25,7 +25,7 @@ function OptimalControlProblems.moonlander(
     init=nothing,
     kwargs...,
 )
-    OptimalControlProblems._warn_if_draft(:moonlander, :JuMP)
+    OptimalControlProblems.Catalogue._warn_if_draft(:moonlander, :JuMP)
 
     # parameters
     params = parameters_data(:moonlander, parameters)
@@ -107,6 +107,6 @@ function OptimalControlProblems.moonlander(
         ],
     )
     # initial guess: from the metadata (#377), unless given
-    init = OptimalControlProblems._initial_guess(:moonlander, params, init)
+    init = OptimalControlProblems.Metadata._initial_guess(:moonlander, params, init)
     return build(data, grid_size, scheme, ordering, args...; init=init, kwargs...)
 end

ext/JuMPModels/mountain_car.jl

@@ -25,7 +25,7 @@ function OptimalControlProblems.mountain_car(
     init=nothing,
     kwargs...,
 )
-    OptimalControlProblems._warn_if_draft(:mountain_car, :JuMP)
+    OptimalControlProblems.Catalogue._warn_if_draft(:mountain_car, :JuMP)
 
     # parameters
     params = parameters_data(:mountain_car, parameters)
@@ -65,6 +65,6 @@ function OptimalControlProblems.mountain_car(
         ],
     )
     # initial guess: from the metadata (#377), unless given
-    init = OptimalControlProblems._initial_guess(:mountain_car, params, init)
+    init = OptimalControlProblems.Metadata._initial_guess(:mountain_car, params, init)
     return build(data, grid_size, scheme, ordering, args...; init=init, kwargs...)
 end