Public API

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.

struct ADNLP{P<:CTSolvers.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

# 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

# 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

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

Advanced Backend Configuration

# 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

# 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

• ADNLPModels.jl: https://github.com/JuliaSmoothOptimizers/ADNLPModels.jl
• Automatic Differentiation in Julia: https://github.com/JuliaDiff/

abstract type AbstractNLPModeler <: CTSolvers.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 and provide callable interfaces for model and solution building.

Implementation Requirements

All concrete modeler strategies must:

• Implement the Strategies.AbstractStrategy contract
• Implement (modeler)(prob::Optimization.AbstractOptimizationProblem, initial_guess)
• Implement (modeler)(prob::Optimization.AbstractOptimizationProblem, stats::SolverCore.AbstractExecutionStats)

Example

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

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

function (modeler::MyModeler)(
    prob::Optimization.AbstractOptimizationProblem,
    initial_guess
)
    # Build NLP model from problem and initial guess
    return nlp_model
end

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

struct Exa{P<:Union{CTSolvers.Strategies.CPU, CTSolvers.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

# 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

# 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

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

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

Backend Configuration

# 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

# 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

# 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

• ExaModels.jl: https://github.com/JuliaSmoothOptimizers/ExaModels.jl
• KernelAbstractions.jl: https://github.com/JuliaGPU/KernelAbstractions.jl