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. A modeler selects an NLP backend and carries its validated options; it does not build anything itself. The NLP model and the problem-level solution are produced by Optimization.build_model / Optimization.build_solution, implemented by the package providing the problem (e.g. CTDirect) for each concrete (problem, modeler) pair. The generic NotImplemented stubs of this contract live in this module.

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

ADNLP [Struct]

CTSolvers.Modelers.ADNLP Type

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

Modeler selecting ADNLPModels as the NLP backend.

The NLP model is built with ADNLPModels.jl (automatic differentiation) by the package providing the problem (e.g. CTDirect). The options configure timing information, AD backend selection, memory optimization, and model identification.

Parameterized Types

The modeler supports parameterization for execution backend:

• ADNLP{Strategies.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{Strategies.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

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

• show_time::Bool: Enable timing information for model building

• matrix_free::Bool: Enable matrix-free mode

• name::String: Model name for identification

Options without a default are not passed to ADNLPModels unless set, so ADNLPModels' own defaults apply.

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{Strategies.CPU}()

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

Invalid Usage

# GPU is NOT supported - rejected by the type parameter bound (TypeError)
modeler = Modelers.ADNLP{Strategies.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

• TypeError: If Strategies.GPU or another unsupported parameter is specified (the type parameter is bounded by Strategies.CPU)

• CTBase.Exceptions.IncorrectArgument: If option validation fails

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

See also

• Strategies.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, :manual (:enzyme and :zygote require Enzyme / Zygote to be loaded)

• 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/

AbstractNLPModeler [Abstract Type]

CTSolvers.Modelers.AbstractNLPModeler Type

abstract type AbstractNLPModeler <: CTBase.Strategies.AbstractStrategy

Abstract base type for all modeler strategies.

A modeler selects the NLP backend used for an Optimization.AbstractOptimizationProblem and carries its validated options. It does not build anything itself: the NLP model and the problem-level solution are built by Optimization.build_model / Optimization.build_solution, implemented by the package providing the problem for each concrete (problem, modeler) pair.

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

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

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

Modeler selecting ExaModels as the NLP backend.

The NLP model is built with ExaModels.jl, on CPU or GPU and with a configurable floating-point type, by the package providing the problem (e.g. CTDirect).

Parameterized Types

The modeler supports parameterization for execution backend:

• Exa{Strategies.CPU}: CPU execution (default)

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

Constructors

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

# Explicit parameter specification
Modelers.Exa{Strategies.CPU}(; mode::Symbol=:strict, kwargs...)
Modelers.Exa{Strategies.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{Strategies.CPU}()

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

Type Specification

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

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

A Float32 model is accepted by MadNLP only, with a tolerance reachable in single precision (e.g. tol = 1e-5): Ipopt, MadNCL and Uno have no method for it. On the GPU, MadNLP runs but may not converge (see probe/README.md).

Backend Configuration

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

# GPU backend (default for Exa{GPU})
modeler = Modelers.Exa{Strategies.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{Strategies.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

• 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

• Strategies.CPU, Strategies.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 (a warning is issued if it is not 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/exanauts/ExaModels.jl

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