Public API

Optimization module.

This module defines the abstract optimization problem interface (AbstractOptimizationProblem) together with the builder pattern used by modelers:

• model builders construct backend NLP models from an initial guess
• solution builders convert solver statistics into domain-level solutions

The functions build_model and build_solution provide a backend-agnostic API delegating the actual work to the selected modeler strategy.

struct ADNLPModelBuilder{T<:Function} <: CTSolvers.Optimization.AbstractModelBuilder

Builder for constructing ADNLPModels-based NLP models.

This is a callable object that wraps a function for building ADNLPModels. The wrapped function should accept an initial guess and keyword arguments.

Fields

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

Example

builder = ADNLPModelBuilder(build_adnlp_model)
nlp = builder(initial_guess; show_time=false, backend=:optimized)

struct ADNLPSolutionBuilder{T<:Function} <: CTSolvers.Optimization.AbstractOCPSolutionBuilder

Builder for constructing OCP solutions from ADNLP solver results.

This is a callable object that wraps a function for converting NLP solver statistics into optimal control solutions.

Fields

• f::T: A callable that builds the solution when invoked

Example

builder = ADNLPSolutionBuilder(build_adnlp_solution)
sol = builder(nlp_stats)

abstract type AbstractBuilder

Abstract base type for all builders in the optimization system.

This provides a common interface for model builders and solution builders that work with optimization problems.

abstract type AbstractModelBuilder <: CTSolvers.Optimization.AbstractBuilder

Abstract base type for builders that construct NLP back-end models from an AbstractOptimizationProblem.

Concrete subtypes are callable objects that encapsulate the logic for building a model for a specific NLP back-end.

abstract type AbstractOCPSolutionBuilder <: CTSolvers.Optimization.AbstractSolutionBuilder

Abstract base type for builders that transform NLP solutions into OCP solutions.

Concrete implementations should define the exact call signature and behavior for specific solution types.

abstract type AbstractOptimizationProblem

Abstract base type for optimization problems.

This is a general type that represents any optimization problem, not necessarily tied to optimal control. Subtypes can represent various problem formulations including discretized optimal control problems, general NLP problems, etc.

Subtypes are typically paired with AbstractModelBuilder and AbstractSolutionBuilder implementations that know how to construct and interpret NLP back-end models and solutions.

Example

struct MyOptimizationProblem <: AbstractOptimizationProblem
    objective::Function
    constraints::Vector{Function}
end

abstract type AbstractSolutionBuilder <: CTSolvers.Optimization.AbstractBuilder

Abstract base type for builders that transform NLP solutions into other representations (for example, solutions of an optimal control problem).

Subtypes are callable objects that convert NLP solver results into problem-specific solution formats.

struct ExaModelBuilder{T<:Function} <: CTSolvers.Optimization.AbstractModelBuilder

Builder for constructing ExaModels-based NLP models.

This is a callable object that wraps a function for building ExaModels. The wrapped function should accept a base type, initial guess, and keyword arguments.

Fields

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

Example

builder = ExaModelBuilder(build_exa_model)
nlp = builder(Float64, initial_guess; backend=nothing, minimize=true)

struct ExaSolutionBuilder{T<:Function} <: CTSolvers.Optimization.AbstractOCPSolutionBuilder

Builder for constructing OCP solutions from ExaModels solver results.

This is a callable object that wraps a function for converting NLP solver statistics into optimal control solutions.

Fields

• f::T: A callable that builds the solution when invoked

Example

builder = ExaSolutionBuilder(build_exa_solution)
sol = builder(nlp_stats)

build_model(prob, initial_guess, modeler) -> Any

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

This is a general function that works with any AbstractOptimizationProblem. The modeler handles the conversion to the specific NLP backend.

Arguments

• prob::AbstractOptimizationProblem: The optimization problem
• initial_guess: Initial guess for the NLP solver
• modeler: The modeler strategy (e.g., Modelers.ADNLP, Modelers.Exa)

Returns

• An NLP model suitable for the chosen backend

Example

modeler = Modelers.ADNLP(show_time=false)
nlp = build_model(prob, initial_guess, modeler)

See also: build_solution

build_solution(prob, model_solution, modeler) -> Any

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

This is a general function that works with any AbstractOptimizationProblem. The modeler handles the conversion from NLP solution to problem-specific solution.

Arguments

• prob::AbstractOptimizationProblem: The optimization problem
• model_solution: NLP solver output (execution statistics)
• modeler: The modeler strategy used for building

Returns

• A solution object appropriate for the problem type

Example

sol = build_solution(prob, nlp_stats, modeler)

See also: build_model

extract_solver_infos(
    nlp_solution::SolverCore.AbstractExecutionStats
) -> Tuple{Any, Any, Any, String, Any, Union{Missing, Bool}}

Retrieve convergence information from an NLP solution.

This function extracts standardized solver information from NLP solver execution statistics. It returns a 6-element tuple that can be used to construct solver metadata for optimal control solutions.

Arguments

• nlp_solution::SolverCore.AbstractExecutionStats: A solver execution statistics object.

Returns

A 6-element tuple (objective, iterations, constraints_violation, message, status, successful):

• objective::Float64: The final objective value
• iterations::Int: Number of iterations performed
• constraints_violation::Float64: Maximum constraint violation (primal feasibility)
• message::String: Solver identifier string (e.g., "Ipopt/generic")
• status::Symbol: Termination status (e.g., :first_order, :acceptable)
• successful::Bool: Whether the solver converged successfully

Example

obj, iter, viol, msg, stat, success = extract_solver_infos(nlp_solution)

get_adnlp_model_builder(
    prob::CTSolvers.Optimization.AbstractOptimizationProblem
) -> CTSolvers.Optimization.AbstractModelBuilder

Get the ADNLPModels model builder for an optimization problem.

This is part of the AbstractOptimizationProblem contract. Concrete problem types must implement this method to provide a builder that constructs ADNLPModels from the problem.

Arguments

• prob::AbstractOptimizationProblem: The optimization problem

Returns

• AbstractModelBuilder: A callable builder that constructs ADNLPModels

Throws

• CTBase.Exceptions.NotImplemented: If the problem type does not support the ADNLPModels backend

Example

builder = get_adnlp_model_builder(prob)
nlp = builder(initial_guess; show_time=false, backend=:optimized)

See also: get_exa_model_builder, build_model

get_adnlp_model_builder(
    prob::CTSolvers.DOCP.DiscretizedModel
) -> CTSolvers.Optimization.AbstractModelBuilder

Get the ADNLPModels model builder from a DiscretizedModel.

This implements the Optimization.AbstractOptimizationProblem contract.

Arguments

• prob::DiscretizedModel: The discretized problem

Returns

• AbstractModelBuilder: The ADNLP model builder

Example

builder = Optimization.get_adnlp_model_builder(docp)
nlp = builder(initial_guess)

See also: Optimization.get_exa_model_builder

get_adnlp_solution_builder(
    prob::CTSolvers.Optimization.AbstractOptimizationProblem
) -> CTSolvers.Optimization.AbstractSolutionBuilder

Get the ADNLPModels solution builder for an optimization problem.

This is part of the AbstractOptimizationProblem contract. Concrete problem types must implement this method to provide a builder that converts NLP solver results into problem-specific solutions.

Arguments

• prob::AbstractOptimizationProblem: The optimization problem

Returns

• AbstractSolutionBuilder: A callable builder that constructs solutions from NLP results

Throws

• CTBase.Exceptions.NotImplemented: If the problem type does not support the ADNLPModels backend

Example

builder = get_adnlp_solution_builder(prob)
sol = builder(nlp_stats)

See also: get_exa_solution_builder, build_solution

get_adnlp_solution_builder(
    prob::CTSolvers.DOCP.DiscretizedModel
) -> CTSolvers.Optimization.AbstractSolutionBuilder

Get the ADNLPModels solution builder from a DiscretizedModel.

This implements the Optimization.AbstractOptimizationProblem contract.

Arguments

• prob::DiscretizedModel: The discretized problem

Returns

• AbstractSolutionBuilder: The ADNLP solution builder

Example

builder = Optimization.get_adnlp_solution_builder(docp)
sol = builder(nlp_stats)

See also: Optimization.get_exa_solution_builder

get_exa_model_builder(
    prob::CTSolvers.Optimization.AbstractOptimizationProblem
) -> CTSolvers.Optimization.AbstractModelBuilder

Get the ExaModels model builder for an optimization problem.

This is part of the AbstractOptimizationProblem contract. Concrete problem types must implement this method to provide a builder that constructs ExaModels from the problem.

Arguments

• prob::AbstractOptimizationProblem: The optimization problem

Returns

• AbstractModelBuilder: A callable builder that constructs ExaModels

Throws

• CTBase.Exceptions.NotImplemented: If the problem type does not support the ExaModels backend

Example

builder = get_exa_model_builder(prob)
nlp = builder(Float64, initial_guess; backend=nothing, minimize=true)

See also: get_adnlp_model_builder, build_model

get_exa_model_builder(
    prob::CTSolvers.DOCP.DiscretizedModel
) -> CTSolvers.Optimization.AbstractModelBuilder

Get the ExaModels model builder from a DiscretizedModel.

This implements the Optimization.AbstractOptimizationProblem contract.

Arguments

• prob::DiscretizedModel: The discretized problem

Returns

• AbstractModelBuilder: The ExaModel builder

Example

builder = Optimization.get_exa_model_builder(docp)
nlp = builder(Float64, initial_guess)

See also: Optimization.get_adnlp_model_builder

get_exa_solution_builder(
    prob::CTSolvers.Optimization.AbstractOptimizationProblem
) -> CTSolvers.Optimization.AbstractSolutionBuilder

Get the ExaModels solution builder for an optimization problem.

This is part of the AbstractOptimizationProblem contract. Concrete problem types must implement this method to provide a builder that converts NLP solver results into problem-specific solutions.

Arguments

• prob::AbstractOptimizationProblem: The optimization problem

Returns

• AbstractSolutionBuilder: A callable builder that constructs solutions from NLP results

Throws

• CTBase.Exceptions.NotImplemented: If the problem type does not support the ExaModels backend

Example

builder = get_exa_solution_builder(prob)
sol = builder(nlp_stats)

See also: get_adnlp_solution_builder, build_solution

get_exa_solution_builder(
    prob::CTSolvers.DOCP.DiscretizedModel
) -> CTSolvers.Optimization.AbstractSolutionBuilder

Get the ExaModels solution builder from a DiscretizedModel.

This implements the Optimization.AbstractOptimizationProblem contract.

Arguments

• prob::DiscretizedModel: The discretized problem

Returns

• AbstractSolutionBuilder: The ExaModel solution builder

Example

builder = Optimization.get_exa_solution_builder(docp)
sol = builder(nlp_stats)

See also: Optimization.get_adnlp_solution_builder