refactor(DOCP): dispatch-based contract, no builders/callables

ext/CTSolversIpopt.jl

@@ -8,6 +8,7 @@ module CTSolversIpopt
 
 import DocStringExtensions: TYPEDSIGNATURES
 import CTSolvers.Solvers
+import CommonSolve
 import CTBase.Strategies
 import CTBase.Options
 import CTBase.Core
@@ -591,8 +592,8 @@ Solve an NLP problem using Ipopt.
 # Returns
 - `SolverCore.GenericExecutionStats`: Solver execution statistics
 """
-function (solver::Solvers.Ipopt)(
-    nlp::NLPModels.AbstractNLPModel; display::Bool=true
+function CommonSolve.solve(
+    nlp::NLPModels.AbstractNLPModel, solver::Solvers.Ipopt; display::Bool=true
 )::SolverCore.GenericExecutionStats
     options = Strategies.options_dict(solver)
     options[:print_level] = display ? options[:print_level] : 0

ext/CTSolversKnitro.jl

@@ -8,6 +8,7 @@ module CTSolversKnitro
 
 import DocStringExtensions: TYPEDSIGNATURES
 import CTSolvers.Solvers
+import CommonSolve
 import CTBase.Strategies
 import CTBase.Options
 import CTBase.Exceptions
@@ -244,8 +245,8 @@ Solve an NLP problem using Knitro.
 # Returns
 - `SolverCore.GenericExecutionStats`: Solver execution statistics
 """
-function (solver::Solvers.Knitro)(
-    nlp::NLPModels.AbstractNLPModel; display::Bool=true
+function CommonSolve.solve(
+    nlp::NLPModels.AbstractNLPModel, solver::Solvers.Knitro; display::Bool=true
 )::SolverCore.GenericExecutionStats
     options = Strategies.options_dict(solver)
     options[:outlev] = display ? options[:outlev] : 0

ext/CTSolversMadNCL.jl

@@ -8,6 +8,7 @@ module CTSolversMadNCL
 
 import DocStringExtensions: TYPEDSIGNATURES
 import CTSolvers.Solvers
+import CommonSolve
 import CTBase.Strategies
 import CTBase.Options
 import CTBase.Core
@@ -402,8 +403,8 @@ Solve an NLP problem using MadNCL.
 # Returns
 - `MadNCL.NCLStats`: MadNCL execution statistics
 """
-function (solver::Solvers.MadNCL)(
-    nlp::NLPModels.AbstractNLPModel; display::Bool=true
+function CommonSolve.solve(
+    nlp::NLPModels.AbstractNLPModel, solver::Solvers.MadNCL; display::Bool=true
 )::MadNCL.NCLStats
     options = Strategies.options_dict(solver)
     options[:print_level] = display ? options[:print_level] : MadNLP.ERROR

ext/CTSolversMadNLP.jl

@@ -9,6 +9,7 @@ module CTSolversMadNLP
 import DocStringExtensions: TYPEDSIGNATURES
 import CTSolvers.Optimization
 import CTSolvers.Solvers
+import CommonSolve
 import CTBase.Strategies
 import CTBase.Options
 import CTBase.Core
@@ -502,8 +503,8 @@ Solve an NLP problem using MadNLP.
 # Returns
 - `MadNLP.MadNLPExecutionStats`: MadNLP execution statistics
 """
-function (solver::Solvers.MadNLP)(
-    nlp::NLPModels.AbstractNLPModel; display::Bool=true
+function CommonSolve.solve(
+    nlp::NLPModels.AbstractNLPModel, solver::Solvers.MadNLP; display::Bool=true
 )::MadNLP.MadNLPExecutionStats
     options = Strategies.options_dict(solver)
     options[:print_level] = display ? options[:print_level] : MadNLP.ERROR

ext/CTSolversUno.jl

@@ -9,6 +9,7 @@ module CTSolversUno
 import DocStringExtensions: TYPEDSIGNATURES
 import CTSolvers.Optimization
 import CTSolvers.Solvers
+import CommonSolve
 import CTBase.Strategies
 import CTBase.Options
 import CTBase.Core
@@ -338,8 +339,8 @@ Solve an NLP problem using Uno.
 
 See also: [`solve_with_uno`](@ref), [`Optimization.extract_solver_infos`](@ref)
 """
-function (solver::Solvers.Uno)(
-    nlp::NLPModels.AbstractNLPModel; display::Bool=true
+function CommonSolve.solve(
+    nlp::NLPModels.AbstractNLPModel, solver::Solvers.Uno; display::Bool=true
 )::UnoSolver.UnoExecutionStats
     options = Strategies.options_dict(solver)
     options[:logger] = display ? options[:logger] : "SILENT"

src/DOCP/DOCP.jl

@@ -20,19 +20,27 @@ import DocStringExtensions: TYPEDEF, TYPEDSIGNATURES
 using NLPModels: NLPModels
 using SolverCore: SolverCore
 using CTModels: CTModels
+import CTBase.Core
+import CTBase.Exceptions
+
+# CTBase generic infrastructure
+using CTBase.Strategies
 
 # Internal CTSolvers API
 using ..CTSolvers.Optimization
 using ..CTSolvers.Modelers
 
 # Submodules
+include(joinpath(@__DIR__, "abstract_discretizer.jl"))
 include(joinpath(@__DIR__, "types.jl"))
-include(joinpath(@__DIR__, "contract_impl.jl"))
+include(joinpath(@__DIR__, "contract.jl"))
 include(joinpath(@__DIR__, "accessors.jl"))
 include(joinpath(@__DIR__, "building.jl"))
 
 # Public API
+export AbstractDiscretizer
 export DiscretizedModel
+export discretize
 export ocp_model
 export nlp_model, ocp_solution
 

src/DOCP/abstract_discretizer.jl

@@ -0,0 +1,19 @@
+# DOCP abstract discretizer
+#
+# Defines the `AbstractDiscretizer` strategy contract. Concrete discretizers
+# (collocation, direct shooting, ...) are implemented in the packages providing
+# the transcription methods (e.g. CTDirect).
+
+"""
+$(TYPEDEF)
+
+Abstract base type for all discretization strategies.
+
+Concrete subtypes implement specific transcription methods (collocation, direct
+shooting, etc.) and are defined in the package providing the method. A discretizer
+is a `Strategies.AbstractStrategy`: it carries validated options and drives
+`discretize` to turn an optimal control problem into a [`DiscretizedModel`](@ref).
+
+See also: `DiscretizedModel`, `discretize`.
+"""
+abstract type AbstractDiscretizer <: Strategies.AbstractStrategy end

src/DOCP/accessors.jl

@@ -20,4 +20,4 @@ ocp = ocp_model(docp)
 
 See also: `DiscretizedModel`
 """
-ocp_model(docp::DiscretizedModel) = docp.optimal_control_problem
+ocp_model(docp::DiscretizedModel) = docp.ocp

src/DOCP/contract.jl

@@ -0,0 +1,34 @@
+# DOCP contract
+#
+# Generic entry points implemented (by multiple dispatch) in the package that
+# provides the discretizer (e.g. CTDirect). The methods here are stubs that throw
+# `NotImplemented` so that a missing implementation fails with a clear message.
+
+"""
+$(TYPEDSIGNATURES)
+
+Discretize an optimal control problem into a [`DiscretizedModel`](@ref).
+
+# Contract
+Must be implemented in the package providing `discretizer`, dispatching on its
+concrete type, e.g. `CTSolvers.discretize(ocp, ::Collocation)` in CTDirect.
+
+# Arguments
+- `ocp::CTModels.AbstractModel`: The optimal control problem.
+- `discretizer::AbstractDiscretizer`: The discretization strategy.
+
+# Returns
+- A [`DiscretizedModel`](@ref) with a populated cache.
+
+See also: `build_model`, `build_solution`.
+"""
+function discretize(ocp::CTModels.AbstractModel, discretizer::AbstractDiscretizer)
+    throw(
+        Exceptions.NotImplemented(
+            "discretize not implemented";
+            required_method="CTSolvers.discretize(ocp, ::$(typeof(discretizer)))",
+            suggestion="Implement it in the package providing $(typeof(discretizer))",
+            context="DOCP.discretize - required method implementation",
+        ),
+    )
+end

src/DOCP/types.jl

@@ -1,47 +1,38 @@
 # DOCP types
 #
-# Defines the `DiscretizedModel` type. Builder types live in the
-# `CTSolvers.Optimization` module.
+# Defines the `DiscretizedModel` type: a thin pairing of an optimal control
+# problem with the discretizer that produced it, plus an optional backend cache.
 
 """
 $(TYPEDEF)
 
 Discretized optimal control problem ready for NLP solving.
 
-Wraps an optimal control problem together with builders for the supported NLP backends.
-This type implements the `Optimization.AbstractOptimizationProblem` contract.
+A thin pairing of an optimal control problem with the discretizer that produced
+it, plus a backend cache. The actual NLP model and OCP solution are produced by
+multiple dispatch on `(DiscretizedModel, modeler)` through the `build_model` /
+`build_solution` contract, implemented in the package providing the discretizer
+(e.g. CTDirect). This mirrors `Flow{system, integrator}` on the ODE side.
 
 # Fields
-- `optimal_control_problem::TO`: The original optimal control problem
-- `adnlp_model_builder::TAMB`: Builder for ADNLPModels
-- `exa_model_builder::TEMB`: Builder for ExaModels
-- `adnlp_solution_builder::TASB`: Builder for ADNLP solutions
-- `exa_solution_builder::TESB`: Builder for ExaModel solutions
+- `ocp::TO`: The original optimal control problem.
+- `discretizer::TD`: The discretization strategy used.
+- `cache::TC`: Backend cache (`<: CTBase.Core.AbstractCache`), opaque to CTSolvers,
+  populated by the implementing package (e.g. CTDirect's `DOCPCache`).
 
-# Example
-```julia
-# Conceptual usage pattern
-docp = DiscretizedModel(
-    ocp,
-    adnlp_model_builder,
-    exa_model_builder,
-    adnlp_solution_builder,
-    exa_solution_builder,
-)
-```
+# Type parameters
+- `TO <: CTModels.AbstractModel`
+- `TD <: AbstractDiscretizer`
+- `TC <: CTBase.Core.AbstractCache`
 
-See also: `ocp_model`, `nlp_model`, `ocp_solution`
+See also: `ocp_model`, `discretize`, `build_model`, `build_solution`.
 """
 struct DiscretizedModel{
     TO<:CTModels.AbstractModel,
-    TAMB<:AbstractModelBuilder,
-    TEMB<:AbstractModelBuilder,
-    TASB<:AbstractSolutionBuilder,
-    TESB<:AbstractSolutionBuilder,
+    TD<:AbstractDiscretizer,
+    TC<:Core.AbstractCache,
 } <: AbstractOptimizationProblem
-    optimal_control_problem::TO
-    adnlp_model_builder::TAMB
-    exa_model_builder::TEMB
-    adnlp_solution_builder::TASB
-    exa_solution_builder::TESB
+    ocp::TO
+    discretizer::TD
+    cache::TC
 end