Private API

struct ADNLPModelBuilder{T<:Function} <: CTModels.AbstractModelBuilder

Builder for constructing ADNLPModels-based NLP models from an AbstractOptimizationProblem.

Fields

• f::T: A callable that builds the ADNLPModel when invoked.

Concrete implementations are typically returned by high-level optimisation modelling interfaces and are not created directly by users.

See also: ExaModelBuilder, AbstractModelBuilder.

struct ADNLPModeler{Vals, Srcs} <: CTModels.AbstractOptimizationModeler

Concrete AbstractOptimizationModeler based on ADNLPModels.jl.

ADNLPModeler implements the AbstractOCPTool options interface: it stores options_values and options_sources, defines an _option_specs specialisation describing its options, and is constructed via _build_ocp_tool_options.

Fields

• options_values::Vals: Named tuple of current option values.
• options_sources::Srcs: Named tuple indicating source of each option (:ct_default or :user).

See also: ExaModeler, AbstractOptimizationModeler.

struct ADNLPSolutionBuilder{T<:Function} <: CTModels.AbstractOCPSolutionBuilder

Solution builder for ADNLPModels-based solvers.

Converts NLP execution statistics into an optimal control solution.

Fields

• f::T: A callable that builds the OCP solution from NLP stats.

See also: ExaSolutionBuilder, AbstractOCPSolutionBuilder.

struct ExaModelBuilder{T<:Function} <: CTModels.AbstractModelBuilder

Builder for constructing ExaModels-based NLP models from an AbstractOptimizationProblem.

Fields

• f::T: A callable that builds the ExaModel when invoked.

See also: ADNLPModelBuilder, AbstractModelBuilder.

struct ExaModeler{BaseType<:AbstractFloat, Vals, Srcs} <: CTModels.AbstractOptimizationModeler

Concrete AbstractOptimizationModeler based on ExaModels.jl.

Like ADNLPModeler, this type follows the AbstractOCPTool options interface and is configured via _build_ocp_tool_options. It additionally fixes a BaseType<:AbstractFloat parameter that controls the floating-point type of the underlying ExaModel.

Fields

• options_values::Vals: Named tuple of current option values.
• options_sources::Srcs: Named tuple indicating source of each option (:ct_default or :user).

Type Parameters

• BaseType<:AbstractFloat: Floating-point type for the ExaModel (e.g., Float64).

See also: ADNLPModeler, AbstractOptimizationModeler.

struct ExaSolutionBuilder{T<:Function} <: CTModels.AbstractOCPSolutionBuilder

Solution builder for ExaModels-based solvers.

Converts NLP execution statistics into an optimal control solution.

Fields

• f::T: A callable that builds the OCP solution from NLP stats.

See also: ADNLPSolutionBuilder, AbstractOCPSolutionBuilder.

Tuple of all registered modeler types.

Currently contains (ADNLPModeler, ExaModeler).

__adnlp_model_backend() -> Symbol

Return the default automatic differentiation backend for ADNLPModeler.

Default is :optimized.

__adnlp_model_show_time() -> Bool

Return the default value for the show_time option of ADNLPModeler.

Default is false.

__exa_model_backend()

Return the default execution backend for ExaModeler.

Default is nothing (CPU).

__exa_model_base_type() -> Type{Float64}

Return the default floating-point type for ExaModeler.

Default is Float64.

_build_ocp_tool_options(
    ::Type{T<:CTModels.AbstractOCPTool};
    strict_keys,
    kwargs...
) -> Tuple{NamedTuple, NamedTuple}

Build a normalized pair of option values and sources for a concrete AbstractOCPTool subtype.

This helper is typically used in the keyword-only constructor of a tool type, for example MyTool(; kwargs...) = MyTool(_build_ocp_tool_options(MyTool; kwargs...)...).

Arguments

• ::Type{T}: concrete subtype of AbstractOCPTool.
• strict_keys::Bool: if true, unknown option keys are rejected with a detailed error; if false, unknown keys are accepted.
• kwargs...: user-supplied option values.

Returns

A pair (values, sources) where:

• values::NamedTuple: effective option values after merging tool defaults (from default_options) with the user keywords.
• sources::NamedTuple: for each option name, either :ct_default or :user indicating whether the value comes from the tool defaults or from user input.

_filter_options(nt::NamedTuple, exclude) -> NamedTuple

Filter a NamedTuple by excluding specified keys.

_modeler_type_from_symbol(sym::Symbol) -> UnionAll

Look up a modeler type from its symbol identifier.

Throws CTBase.IncorrectArgument if the symbol is unknown.

_option_sources(tool::CTModels.AbstractOCPTool) -> Any

Return the option sources (:ct_default or :user) for a tool instance.

_option_specs(
    x::Type{T<:CTModels.AbstractOCPTool}
) -> @NamedTuple{show_time::CTModels.OptionSpec, backend::CTModels.OptionSpec}

Return the option metadata specification for a concrete AbstractOCPTool subtype.

Concrete tools typically specialize this method on their own type and return a NamedTuple whose fields correspond to option names and whose values are OptionSpec instances.

The default implementation returns missing, meaning that no option metadata is available for the given tool type.

_option_specs(
    x::CTModels.AbstractOCPTool
) -> Union{Missing, @NamedTuple{show_time::CTModels.OptionSpec, backend::CTModels.OptionSpec}, @NamedTuple{base_type::CTModels.OptionSpec, minimize::CTModels.OptionSpec, backend::CTModels.OptionSpec}}

Convenience overload to accept tool instances.

_option_specs(
    _::Type{<:CTModels.ADNLPModeler}
) -> @NamedTuple{show_time::CTModels.OptionSpec, backend::CTModels.OptionSpec}

Return the option specifications for ADNLPModeler.

Defines options: show_time (Bool) and backend (Symbol).

_option_specs(
    _::Type{<:CTModels.ExaModeler}
) -> @NamedTuple{base_type::CTModels.OptionSpec, minimize::CTModels.OptionSpec, backend::CTModels.OptionSpec}

Return the option specifications for ExaModeler.

Defines options: base_type, minimize, and backend.

_options_values(tool::CTModels.AbstractOCPTool) -> Any

Return the current option values for a tool instance.

_show_options(tool_type::Type{<:CTModels.AbstractOCPTool})

Print a human-readable listing of options and their metadata for a tool type.

_show_options(x::CTModels.AbstractOCPTool)

Convenience overload for tool instances.

_string_distance(
    a::AbstractString,
    b::AbstractString
) -> Int64

Compute the Levenshtein distance between two strings.

Used for suggesting similar option names when a typo is detected.

_suggest_option_keys(
    key::Symbol,
    tool_type::Type{<:CTModels.AbstractOCPTool};
    max_suggestions
) -> Vector{Symbol}

Suggest up to max_suggestions closest option keys for a tool type.

Used to provide helpful error messages when an unknown option is specified.

_suggest_option_keys(
    key::Symbol,
    x::CTModels.AbstractOCPTool;
    max_suggestions
) -> Vector{Symbol}

Convenience overload for tool instances.

_unknown_option_error(
    key::Symbol,
    tool_type::Type{<:CTModels.AbstractOCPTool},
    context::AbstractString
)

Generate and throw an error for an unknown option key with suggestions.

_validate_option_kwargs(
    user_nt::NamedTuple,
    tool_type::Type{<:CTModels.AbstractOCPTool};
    strict_keys
)

Validate user-supplied keyword options against tool metadata.

If strict_keys is true, unknown keys trigger an error. If false, unknown keys are accepted and only known keys are type-checked.

_validate_option_kwargs(
    user_nt::NamedTuple,
    x::CTModels.AbstractOCPTool;
    strict_keys
)

Convenience overload for tool instances.

build_model(
    prob::CTModels.AbstractOptimizationProblem,
    initial_guess,
    modeler::CTModels.AbstractOptimizationModeler
) -> Any

Build an NLP model from an optimisation problem using the specified modeler.

Arguments

• prob::AbstractOptimizationProblem: The optimisation problem.
• initial_guess: Initial guess for the NLP solver.
• modeler::AbstractOptimizationModeler: The modeler (e.g., ADNLPModeler, ExaModeler).

Returns

• An NLP model suitable for the chosen backend.

build_modeler_from_symbol(sym::Symbol; kwargs...) -> Any

Construct a modeler from its symbol identifier.

Arguments

• sym::Symbol: The modeler symbol (:adnlp or :exa).
• kwargs...: Options to pass to the modeler constructor.

Returns

• An instance of the corresponding modeler type.

Example

julia> using CTModels

julia> modeler = CTModels.build_modeler_from_symbol(:adnlp)

build_solution(
    ocp::CTModels.Model,
    T::Vector{Float64},
    X::Union{Function, Matrix{Float64}},
    U::Union{Function, Matrix{Float64}},
    v::Vector{Float64},
    P::Union{Function, Matrix{Float64}};
    objective,
    iterations,
    constraints_violation,
    message,
    status,
    successful,
    path_constraints_dual,
    boundary_constraints_dual,
    state_constraints_lb_dual,
    state_constraints_ub_dual,
    control_constraints_lb_dual,
    control_constraints_ub_dual,
    variable_constraints_lb_dual,
    variable_constraints_ub_dual,
    infos
)

Build a solution from the optimal control problem, the time grid, the state, control, variable, and dual variables.

Arguments

• ocp::Model: the optimal control problem.
• T::Vector{Float64}: the time grid.
• X::Matrix{Float64}: the state trajectory.
• U::Matrix{Float64}: the control trajectory.
• v::Vector{Float64}: the variable trajectory.
• P::Matrix{Float64}: the costate trajectory.
• objective::Float64: the objective value.
• iterations::Int: the number of iterations.
• constraints_violation::Float64: the constraints violation.
• message::String: the message associated to the status criterion.
• status::Symbol: the status criterion.
• successful::Bool: the successful status.
• path_constraints_dual::Matrix{Float64}: the dual of the path constraints.
• boundary_constraints_dual::Vector{Float64}: the dual of the boundary constraints.
• state_constraints_lb_dual::Matrix{Float64}: the lower bound dual of the state constraints.
• state_constraints_ub_dual::Matrix{Float64}: the upper bound dual of the state constraints.
• control_constraints_lb_dual::Matrix{Float64}: the lower bound dual of the control constraints.
• control_constraints_ub_dual::Matrix{Float64}: the upper bound dual of the control constraints.
• variable_constraints_lb_dual::Vector{Float64}: the lower bound dual of the variable constraints.
• variable_constraints_ub_dual::Vector{Float64}: the upper bound dual of the variable constraints.
• infos::Dict{Symbol,Any}: additional solver information dictionary.

Returns

• sol::Solution: the optimal control solution.

build_solution(
    prob::CTModels.AbstractOptimizationProblem,
    model_solution,
    modeler::CTModels.AbstractOptimizationModeler
) -> Any

Build a solution from NLP execution statistics using the specified modeler.

Arguments

• prob::AbstractOptimizationProblem: The optimisation problem.
• model_solution: NLP solver output (execution statistics).
• modeler::AbstractOptimizationModeler: The modeler used for building.

Returns

• A solution object appropriate for the problem type.

default_options(
    tool_type::Type{<:CTModels.AbstractOCPTool}
) -> NamedTuple

Return a NamedTuple of default option values for a tool type.

Only options with non-missing defaults are included.

default_options(x::CTModels.AbstractOCPTool) -> NamedTuple

Convenience overload for tool instances.

get_adnlp_model_builder(
    prob::CTModels.AbstractOptimizationProblem
) -> Any

Interface method for AbstractOptimizationProblem.

Concrete problem types that support the ADNLPModels back-end must specialize this function to return the ADNLPModelBuilder used to construct the corresponding NLP model. The default implementation throws CTBase.NotImplemented.

get_adnlp_model_builder(
    prob::CTModels.DiscretizedOptimalControlProblem
) -> Any

Retrieve the ADNLPModels model builder from a discretised problem.

Throws ArgumentError if no :adnlp backend is registered.

get_adnlp_solution_builder(
    prob::CTModels.AbstractOptimizationProblem
) -> Any

Interface method for AbstractOptimizationProblem.

Concrete problem types that support ADNLPModels must specialize this function to return the ADNLPSolutionBuilder used to convert NLP solutions into the desired representation. The default implementation throws CTBase.NotImplemented.

get_adnlp_solution_builder(
    prob::CTModels.DiscretizedOptimalControlProblem
) -> Any

Retrieve the ADNLPModels solution builder from a discretised problem.

Throws ArgumentError if no :adnlp backend is registered.

get_exa_model_builder(
    prob::CTModels.AbstractOptimizationProblem
) -> Any

Interface method for AbstractOptimizationProblem.

Concrete problem types that support the ExaModels back-end must specialize this function to return the ExaModelBuilder used to construct the corresponding NLP model. The default implementation throws CTBase.NotImplemented.

get_exa_model_builder(
    prob::CTModels.DiscretizedOptimalControlProblem
) -> Any

Retrieve the ExaModels model builder from a discretised problem.

Throws ArgumentError if no :exa backend is registered.

get_exa_solution_builder(
    prob::CTModels.AbstractOptimizationProblem
) -> Any

Interface method for AbstractOptimizationProblem.

Concrete problem types that support ExaModels must specialize this function to return the ExaSolutionBuilder used to convert NLP solutions into the desired representation. The default implementation throws CTBase.NotImplemented.

get_exa_solution_builder(
    prob::CTModels.DiscretizedOptimalControlProblem
) -> Any

Retrieve the ExaModels solution builder from a discretised problem.

Throws ArgumentError if no :exa backend is registered.

get_option_default(
    tool::CTModels.AbstractOCPTool,
    key::Symbol
) -> Any

Get the default value of an option for a tool instance.

Throws an error if the option is unknown.

get_option_source(
    tool::CTModels.AbstractOCPTool,
    key::Symbol
) -> Any

Get the source (:ct_default or :user) of an option value.

Throws an error if the option is unknown.

get_option_value(
    tool::CTModels.AbstractOCPTool,
    key::Symbol
) -> Any

Get the current value of an option for a tool instance.

Throws an error if the option is unknown or has no value.

get_symbol(tool::CTModels.AbstractOCPTool) -> Symbol

Return a short Symbol identifying the package or implementation used by a given AbstractOCPTool.

Concrete tool types are expected to specialize this method on their own type, for example get_symbol(::Type{<:MyTool}) = :mytool.

get_symbol(_::Type{T<:CTModels.AbstractOCPTool}) -> Symbol

Default implementation that throws CTBase.NotImplemented.

Concrete tool types must specialize this method.

get_symbol(_::Type{<:CTModels.ADNLPModeler}) -> Symbol

Return the symbol identifier for ADNLPModeler.

Returns :adnlp.

get_symbol(_::Type{<:CTModels.ExaModeler}) -> Symbol

Return the symbol identifier for ExaModeler.

Returns :exa.

is_an_option_key(
    key::Symbol,
    tool_type::Type{<:CTModels.AbstractOCPTool}
) -> Union{Missing, Bool}

Check if key is a valid option key for the given tool type.

Returns missing if no option metadata is available.

is_an_option_key(
    key::Symbol,
    x::CTModels.AbstractOCPTool
) -> Union{Missing, Bool}

Convenience overload for tool instances.

modeler_symbols() -> Tuple{Vararg{Symbol}}

Return a tuple of symbols for all registered modelers.

Returns (:adnlp, :exa).

nlp_model(
    prob::CTModels.DiscretizedOptimalControlProblem,
    initial_guess,
    modeler::CTModels.AbstractOptimizationModeler
) -> NLPModels.AbstractNLPModel

Build an NLP model from a discretised optimal control problem.

Arguments

• prob::DiscretizedOptimalControlProblem: The discretised OCP.
• initial_guess: Initial guess for the NLP solver.
• modeler::AbstractOptimizationModeler: The modeler to use.

Returns

• NLPModels.AbstractNLPModel: The NLP model.

ocp_model(
    prob::CTModels.DiscretizedOptimalControlProblem
) -> CTModels.AbstractModel

Return the original optimal control problem from a discretised problem.

Arguments

• prob::DiscretizedOptimalControlProblem: The discretised problem.

Returns

• The underlying Model (optimal control problem).

ocp_solution(
    docp::CTModels.DiscretizedOptimalControlProblem,
    model_solution::SolverCore.AbstractExecutionStats,
    modeler::CTModels.AbstractOptimizationModeler
) -> CTModels.AbstractSolution

Build an optimal control solution from NLP execution statistics.

Arguments

• docp::DiscretizedOptimalControlProblem: The discretised OCP.
• model_solution::SolverCore.AbstractExecutionStats: NLP solver output.
• modeler::AbstractOptimizationModeler: The modeler used.

Returns

• AbstractOptimalControlSolution: The OCP solution.

option_default(
    key::Symbol,
    tool_type::Type{<:CTModels.AbstractOCPTool}
) -> Any

Return the default value for an option key.

Returns missing if the key is unknown or no default is specified.

option_default(
    key::Symbol,
    x::CTModels.AbstractOCPTool
) -> Any

Convenience overload for tool instances.

option_description(
    key::Symbol,
    tool_type::Type{<:CTModels.AbstractOCPTool}
) -> Any

Return the description for an option key.

Returns missing if the key is unknown or no description is available.

option_description(
    key::Symbol,
    x::CTModels.AbstractOCPTool
) -> Any

Convenience overload for tool instances.

option_type(
    key::Symbol,
    tool_type::Type{<:CTModels.AbstractOCPTool}
) -> Any

Return the expected type for an option key.

Returns missing if the key is unknown or no type is specified.

option_type(key::Symbol, x::CTModels.AbstractOCPTool) -> Any

Convenience overload for tool instances.

options_keys(
    tool_type::Type{<:CTModels.AbstractOCPTool}
) -> Union{Missing, Tuple{Symbol, Symbol}, Tuple{Symbol, Symbol, Symbol}}

Return the list of known option keys for a tool type.

Returns missing if no option metadata is available.

options_keys(
    x::CTModels.AbstractOCPTool
) -> Union{Missing, Tuple{Symbol, Symbol}, Tuple{Symbol, Symbol, Symbol}}

Convenience overload for tool instances.

registered_modeler_types() -> Tuple{UnionAll, UnionAll}

Return the tuple of all registered modeler types.

show_options(tool_type::Type{<:CTModels.AbstractOCPTool})

Display available options for a tool type.

Prints option names, types, and descriptions to stdout.

show_options(x::CTModels.AbstractOCPTool)

Convenience overload for tool instances.

tool_package_name(
    tool::CTModels.AbstractOCPTool
) -> Union{Missing, String}

Return the package name associated with a tool instance.

tool_package_name(
    _::Type{T<:CTModels.AbstractOCPTool}
) -> String

Return the package name for a tool type.

Default implementation returns missing.

tool_package_name(
    _::Type{<:CTModels.ADNLPModeler}
) -> String

Return the package name for ADNLPModeler.

Returns "ADNLPModels".

tool_package_name(_::Type{<:CTModels.ExaModeler}) -> String

Return the package name for ExaModeler.

Returns "ExaModels".