CTSolvers.jl

Appearance

Public API ​

This page lists exported symbols of CTSolvers.Modelers.

From CTSolvers.Modelers ​

CTSolvers.Modelers [Module] ​

CTSolvers.Modelers Module

Modelers module.

This module defines AbstractNLPModeler and concrete modeler strategies such as ADNLP and Exa. Modelers are strategies that:

  • Build NLP backend models from an Optimization.AbstractOptimizationProblem and an initial guess.

  • Build problem-specific solution objects from solver execution statistics.

Modelers implement the Strategies.AbstractStrategy contract and participate in orchestration and option routing.

ADNLP [Struct] ​

CTSolvers.Modelers.ADNLP Type
julia
struct ADNLP{P<:CTBase.Strategies.CPU} <: CTSolvers.Modelers.AbstractNLPModeler

Modeler for building ADNLPModels from discretized optimal control problems.

This modeler uses the ADNLPModels.jl package to create NLP models with automatic differentiation support. It provides configurable options for timing information, AD backend selection, memory optimization, and model identification.

Parameterized Types

The modeler supports parameterization for execution backend:

  • ADNLP{CPU}: CPU execution (default and only supported parameter)

Note: Unlike Exa, MadNLP, and MadNCL, this modeler only supports CPU execution. GPU execution is not available for ADNLP.

Constructors

julia
# Default constructor (CPU)
Modelers.ADNLP(; mode::Symbol=:strict, kwargs...)

# Explicit parameter specification (only CPU supported)
Modelers.ADNLP{CPU}(; mode::Symbol=:strict, kwargs...)

Arguments

  • mode::Symbol=:strict: Validation mode (:strict or :permissive)

    • :strict (default): Rejects unknown options with detailed error message

    • :permissive: Accepts unknown options with warning, stores with :user source

  • kwargs...: Modeler options (see Options section)

Parameter Behavior

CPU Parameter (Default)

The CPU parameter indicates standard CPU-based execution:

  • Uses CPU-optimized automatic differentiation backends

  • No GPU acceleration available

  • Compatible with all standard Julia environments

  • Default AD backend: :optimized

Options

Basic Options

  • show_time::Bool: Enable timing information for model building (default: false)

  • backend::Symbol: AD backend to use (default: :optimized)

  • matrix_free::Bool: Enable matrix-free mode (default: false)

  • name::String: Model name for identification (default: "CTSolvers-ADNLP")

Advanced Backend Overrides (expert users)

Each backend option accepts nothing (use default), a Type{<:ADBackend} (constructed by ADNLPModels), or an ADBackend instance (used directly).

  • gradient_backend: Override backend for gradient computation

  • hprod_backend: Override backend for Hessian-vector product

  • jprod_backend: Override backend for Jacobian-vector product

  • jtprod_backend: Override backend for transpose Jacobian-vector product

  • jacobian_backend: Override backend for Jacobian matrix computation

  • hessian_backend: Override backend for Hessian matrix computation

  • ghjvprod_backend: Override backend for g^T ∇²c(x)v computation

Examples

Basic Usage

julia
# Default modeler (CPU)
modeler = Modelers.ADNLP()

# Explicit CPU specification
modeler = Modelers.ADNLP{CPU}()

# With custom options
modeler = Modelers.ADNLP(
    backend=:optimized,
    matrix_free=true,
    name="MyOptimizationProblem"
)

Invalid Usage

julia
# GPU is NOT supported - will throw IncorrectArgument
modeler = Modelers.ADNLP{GPU}()  # ❌ Error!

Advanced Backend Configuration

julia
# Override with nothing (use default)
modeler = Modelers.ADNLP(
    gradient_backend=nothing,
    hessian_backend=nothing
)

# Override with a Type (ADNLPModels constructs it)
modeler = Modelers.ADNLP(
    gradient_backend=ADNLPModels.ForwardDiffADGradient
)

# Override with an instance (used directly)
modeler = Modelers.ADNLP(
    gradient_backend=ADNLPModels.ForwardDiffADGradient()
)

Validation Modes

julia
# Strict mode (default) - rejects unknown options
modeler = Modelers.ADNLP(backend=:optimized)

# Permissive mode - accepts unknown options with warning
modeler = Modelers.ADNLP(
    backend=:optimized,
    custom_option=123;
    mode=:permissive
)

Throws

  • CTBase.Exceptions.IncorrectArgument: If GPU or other unsupported parameter is specified

  • CTBase.Exceptions.IncorrectArgument: If option validation fails

  • CTBase.Exceptions.IncorrectArgument: If invalid mode is provided

See also

  • CPU: CPU parameter type

  • Modelers.Exa: Alternative modeler using ExaModels (supports GPU)

  • Optimization.build_model: Build a backend NLP model from a problem and a modeler

  • Optimization.build_solution: Build a problem-level solution from execution statistics

Notes

  • The backend option supports: :default, :optimized, :generic, :enzyme, :zygote

  • Advanced backend overrides are for expert users only

  • Matrix-free mode reduces memory usage but may increase computation time

  • Model name is used for identification in solver output

References

AbstractNLPModeler [Abstract Type] ​

CTSolvers.Modelers.AbstractNLPModeler Type
julia
abstract type AbstractNLPModeler <: CTBase.Strategies.AbstractStrategy

Abstract base type for all modeler strategies.

Modeler strategies are responsible for converting discretized optimization problems (Optimization.AbstractOptimizationProblem) into NLP backend models. They implement the Strategies.AbstractStrategy contract together with named model- and solution-building methods.

Implementation Requirements

All concrete modeler strategies must:

  • Implement the Strategies.AbstractStrategy contract

  • Have the package providing the problem implement, by multiple dispatch:

    • Optimization.build_model(prob, initial_guess, modeler) returning a Optimization.BuiltModel

    • Optimization.build_solution(built::Optimization.BuiltModel, nlp_solution, modeler)

Example

julia
struct MyModeler <: AbstractNLPModeler
    options::Strategies.StrategyOptions
end

Strategies.id(::Type{<:MyModeler}) = :my_modeler

# In the package providing the concrete problem type:
function Optimization.build_model(prob::MyProblem, initial_guess, modeler::MyModeler)
    # Build NLP model from problem and initial guess
    nlp = ...
    return Optimization.BuiltModel(prob, nlp, Optimization.NoCache())
end

function Optimization.build_solution(built::Optimization.BuiltModel{<:MyProblem}, nlp_solution, ::MyModeler)
    # Reconstruct the problem-level solution from built and nlp_solution
    return solution
end

See also: Strategies.AbstractStrategy, Optimization.build_model, Optimization.build_solution

Exa [Struct] ​

CTSolvers.Modelers.Exa Type
julia
struct Exa{P<:Union{CTBase.Strategies.CPU, CTBase.Strategies.GPU}} <: CTSolvers.Modelers.AbstractNLPModeler

Modeler for building ExaModels from discretized optimal control problems.

This modeler uses the ExaModels.jl package to create NLP models with support for various execution backends (CPU, GPU) and floating-point types.

Parameterized Types

The modeler supports parameterization for execution backend:

  • Exa{CPU}: CPU execution (default)

  • Exa{GPU}: GPU execution (requires CUDA.jl)

Constructors

julia
# Default constructor (CPU)
Modelers.Exa(; mode::Symbol=:strict, kwargs...)

# Explicit parameter specification
Modelers.Exa{CPU}(; mode::Symbol=:strict, kwargs...)
Modelers.Exa{GPU}(; mode::Symbol=:strict, kwargs...)

Arguments

  • mode::Symbol=:strict: Validation mode (:strict or :permissive)

    • :strict (default): Rejects unknown options with detailed error message

    • :permissive: Accepts unknown options with warning, stores with :user source

  • kwargs...: Modeler options (see Options section)

Options

Basic Options

  • base_type::Type{<:AbstractFloat}: Floating-point type (default: Float64)

  • backend: Execution backend (default depends on parameter: nothing for CPU, CUDA backend for GPU)

Examples

Basic Usage

julia
# Default modeler (Float64, CPU)
modeler = Modelers.Exa()

# Explicit CPU modeler
modeler = Modelers.Exa{CPU}()

# GPU modeler (requires CUDA.jl)
modeler = Modelers.Exa{GPU}()

Type Specification

julia
# Single precision
modeler = Modelers.Exa(base_type=Float32)

# Double precision (default)
modeler = Modelers.Exa(base_type=Float64)

Backend Configuration

julia
# CPU backend (default for Exa{CPU})
modeler = Modelers.Exa{CPU}(backend=nothing)

# GPU backend (default for Exa{GPU})
modeler = Modelers.Exa{GPU}()  # Uses CUDA backend automatically

Validation Modes

julia
# Strict mode (default) - rejects unknown options
modeler = Modelers.Exa(base_type=Float64)

# Permissive mode - accepts unknown options with warning
modeler = Modelers.Exa(
    base_type=Float64,
    custom_option=123;
    mode=:permissive
)

Complete Configuration

julia
# Full configuration with type and backend
modeler = Modelers.Exa{GPU}(
    base_type=Float32;
    mode=:permissive
)

Throws

  • CTBase.Exceptions.IncorrectArgument: If option validation fails

  • CTBase.Exceptions.IncorrectArgument: If invalid mode is provided

  • CTBase.Exceptions.ExtensionError: If GPU backend requested but CUDA not available

See also

  • Modelers.ADNLP: Alternative modeler using ADNLPModels

  • build_model: Build model from problem and modeler

  • solve!: Solve optimization problem

  • CPU, GPU: Strategy parameters

Notes

  • The base_type option affects the precision of all computations

  • CPU backend (backend=nothing) is always available

  • GPU backends require CUDA.jl to be loaded and functional

  • ExaModels.jl provides efficient GPU acceleration for large problems

  • Default backend is automatically selected based on the parameter type

References