Public API

This page lists exported symbols of CTSolvers.Integrators.

---

From CTSolvers.Integrators

CTSolvers.Integrators [Module]

CTSolvers.Integrators Module

Integrators

ODE integrator strategies for the Control Toolbox.

This module provides concrete integrator strategies that integrate ODE problems through a unified CommonSolve.solve(prob, integrator) interface. It mirrors the Solvers module: the strategy types and contract stubs live here, the backend interfaces live in ext/.

Integrator Types

• Integrators.SciML - SciML ODE integrator (requires OrdinaryDiffEqTsit5/OrdinaryDiffEq/DifferentialEquations)

Architecture

• Types and contract: Defined in src/Integrators/ (this module).

• Backend interfaces: Implemented in ext/ as minimal extensions.

• Strategy contract: All integrators implement AbstractStrategy.

Example

using CTSolvers
using OrdinaryDiffEqTsit5      # Load backend extension
using CommonSolve

integ = Integrators.SciML(alg=Tsit5())

# `prob` is an external SciMLBase.ODEProblem
result = solve(prob, integ)
final = Integrators.final_state(result)

See also: AbstractIntegrator, Integrators.SciML.

AbstractIntegrationResult [Abstract Type]

CTSolvers.Integrators.AbstractIntegrationResult Type

abstract type AbstractIntegrationResult

Abstract supertype for integration results produced by integrators.

This abstraction decouples the consumer (e.g. a trajectory layer) from the concrete types of the underlying ODE solvers (e.g. SciML). Integrators must produce a subtype of AbstractIntegrationResult which provides semantic accessors.

Interface Requirements

Subtypes must implement:

• final_state(r::SubType): Return the final state vector.

• times(r::SubType): Return the vector of time points.

• evaluate_at(r::SubType, t::Real): Evaluate the continuous solution at time t.

• status(r::SubType): Return the termination status as a Symbol.

• successful(r::SubType): Return whether the integration succeeded.

See also: CTSolvers.Integrators.final_state, CTSolvers.Integrators.times, CTSolvers.Integrators.evaluate_at, CTSolvers.Integrators.status, CTSolvers.Integrators.successful.

AbstractIntegrator [Abstract Type]

CTSolvers.Integrators.AbstractIntegrator Type

abstract type AbstractIntegrator <: CTBase.Strategies.AbstractStrategy

Abstract strategy for solving ODE Cauchy problems.

An AbstractIntegrator is a strategy that integrates an ODE problem over a time span. It inherits the CTBase.Strategies strategy contract:

Type-Level Contract (Static Metadata)

Methods defined on the type that describe what the integrator can do:

• Strategies.id(::Type{<:S}) → Symbol: Unique identifier for routing and introspection.

• Strategies.metadata(::Type{<:S}) → StrategyMetadata: Option specifications and validation rules.

Instance-Level Contract (Configured State)

Methods defined on instances that provide the actual configuration:

• Strategies.options(s::S) → StrategyOptions: Current option values with provenance tracking.

Concrete Implementation

Concrete integrators implement, typically in a backend extension:

• CommonSolve.solve(prob, integrator::S; options, unsafe): integrate the (external) ODE problem prob with the resolved options, returning an CTSolvers.Integrators.AbstractIntegrationResult.

• CTSolvers.Integrators.merge: concatenate a sequence of integration results (multi-phase trajectories).

The cached per-call option dictionaries are exposed through the CTSolvers.Integrators.options_point / CTSolvers.Integrators.options_trajectory accessors.

See also: CTSolvers.Integrators.SciML, CTSolvers.Integrators.AbstractIntegrationResult.

AbstractSciMLIntegrator [Abstract Type]

CTSolvers.Integrators.AbstractSciMLIntegrator Type

abstract type AbstractSciMLIntegrator <: CTSolvers.Integrators.AbstractIntegrator

Abstract supertype for SciML-based ODE integrator strategies.

This type defines the interface for all integrator strategies that use SciML solvers. Concrete subtypes should store strategy options and implement the required contract methods.

Interface Requirements

Subtypes must implement:

• CTBase.Strategies.id(::Type{<:SubType}): Return unique identifier.

• CTBase.Strategies.description(::Type{<:SubType}): Return description.

• CTBase.Strategies.metadata(::Type{<:SubType}): Return option metadata.

See also: CTSolvers.Integrators.SciML, CTSolvers.Integrators.SciMLTag.

SciML [Struct]

CTSolvers.Integrators.SciML Type

struct SciML{P<:Union{CTBase.Strategies.CPU, CTBase.Strategies.GPU}, O<:CTBase.Strategies.StrategyOptions, OP<:Dict{Symbol, Any}, OT<:Dict{Symbol, Any}} <: CTSolvers.Integrators.AbstractSciMLIntegrator

Generic SciML ODE integrator strategy.

Wraps any SciML algorithm (e.g. Tsit5, Rodas4) through a unified CTBase.Strategies-backed option system. The full implementation (metadata, builder and solve) is provided by the CTSolversSciMLIntegrator package extension; this file declares the type and stubs that throw ExtensionError until the extension is loaded.

Parameterized on the execution device P:

• SciML{CPU}: CPU execution (default);

• SciML{GPU}: GPU execution (state on device arrays, e.g. CuArray).

SciML(...) builds a SciML{CPU} — the device parameterization is fully backward compatible with existing call sites.

To activate the extension, load any of:

• using OrdinaryDiffEqTsit5 (minimal)

• using OrdinaryDiffEq

• using DifferentialEquations

Fields

• options::CTBase.Strategies.StrategyOptions: Validated option bundle.

• options_point::Dict{Symbol, Any}: Pre-computed options for point (final-state) integration.

• options_trajectory::Dict{Symbol, Any}: Pre-computed options for trajectory integration.

SciMLTag [Struct]

CTSolvers.Integrators.SciMLTag Type

struct SciMLTag <: CTBase.Core.AbstractTag

Tag type for SciML integrator dispatch. Used to target the implementation provided by the CTSolversSciMLIntegrator package extension.

Tsit5Tag [Struct]

CTSolvers.Integrators.Tsit5Tag Type

struct Tsit5Tag <: CTBase.Core.AbstractTag

Tag type for Tsit5-specific default algorithm dispatch. Used to target the implementation provided by the CTSolversOrdinaryDiffEqTsit5 package extension.

build_integrator [Function]

CTSolvers.Integrators.build_integrator Function

build_integrator(
;
    kwargs...
) -> CTSolvers.Integrators.SciML{CTBase.Strategies.CPU, CTBase.Strategies.StrategyOptions{NT}, Dict{Symbol, Any}, Dict{Symbol, Any}} where NT<:NamedTuple

Build a SciML integrator with the given options.

Arguments

• kwargs...: Options forwarded to the SciML constructor.

Returns

• CTSolvers.Integrators.SciML: The configured integrator.

See also: CTSolvers.Integrators.SciML, CTSolvers.Integrators.build_sciml_integrator.

build_sciml_integrator [Function]

CTSolvers.Integrators.build_sciml_integrator Function

build_sciml_integrator(
    ::Type{<:CTBase.Core.AbstractTag},
    ::Type{<:CTBase.Strategies.AbstractStrategyParameter};
    kwargs...
) -> CTSolvers.Integrators.SciML{P, CTBase.Strategies.StrategyOptions{NT}, Dict{Symbol, Any}, Dict{Symbol, Any}} where {P<:Union{CTBase.Strategies.CPU, CTBase.Strategies.GPU}, NT<:NamedTuple}

Stub builder for SciML. The real implementation is provided by CTSolversSciMLIntegrator; this stub throws ExtensionError until the extension is loaded.

build_sciml_integrator(
    ::Type{CTSolvers.Integrators.SciMLTag},
    ::Type{P<:CTBase.Strategies.AbstractStrategyParameter};
    mode,
    kwargs...
) -> CTSolvers.Integrators.SciML{P, CTBase.Strategies.StrategyOptions{NT}, Dict{Symbol, Any}, Dict{Symbol, Any}} where {P<:Union{CTBase.Strategies.CPU, CTBase.Strategies.GPU}, NT<:NamedTuple}

Build a SciML integrator with validated options and pre-computed point/trajectory option dictionaries.

Options in _AUTO_OPTION_KEYS support the :auto sentinel value, resolved here into the two cached dictionaries options_point (:auto → false) and options_trajectory (:auto → true).

Arguments

• ::Type{Integrators.SciMLTag}: The SciML integrator tag type.

• ::Type{P}: The execution device parameter (CPU/GPU); threaded into the built SciML{P}.

• mode::Symbol: Validation mode for strategy options (:strict or :permissive).

• kwargs...: User-provided option values. Explicit true/false override :auto resolution.

Returns

• CTSolvers.Integrators.SciML: integrator with cached options_point/options_trajectory.

Throws

• CTBase.Exceptions.PreconditionError: If no algorithm is available (e.g. OrdinaryDiffEqTsit5 not loaded and no explicit alg).

See also: CTSolvers.Integrators.SciML.

evaluate_at [Function]

CTSolvers.Integrators.evaluate_at Function

evaluate_at(
    r::CTSolvers.Integrators.AbstractIntegrationResult,
    t::Real
) -> Any

Evaluate the integration result at a specific time t.

Arguments

• r::AbstractIntegrationResult: The integration result.

• t::Real: The time at which to evaluate the solution.

Throws

• CTBase.Exceptions.NotImplemented: If not implemented by the concrete type.

See also: CTSolvers.Integrators.AbstractIntegrationResult, CTSolvers.Integrators.final_state, CTSolvers.Integrators.times.

evaluate_at(
    r::CTSolversSciMLIntegrator.SciMLIntegrationResult,
    t::Real
) -> Any

Evaluate the SciML ODE solution at a specific time t using its interpolation.

final_state [Function]

CTSolvers.Integrators.final_state Function

final_state(
    r::CTSolvers.Integrators.AbstractIntegrationResult
) -> Any

Return the final state vector from the integration result.

Arguments

• r::AbstractIntegrationResult: The integration result.

Throws

• CTBase.Exceptions.NotImplemented: If not implemented by the concrete type.

See also: CTSolvers.Integrators.AbstractIntegrationResult, CTSolvers.Integrators.times, CTSolvers.Integrators.evaluate_at.

final_state(
    r::CTSolversSciMLIntegrator.SciMLIntegrationResult
) -> Any

Return the final state vector from the SciML ODE solution.

merge [Function]

CTSolvers.Integrators.merge Function

merge(
    segments::AbstractArray{T<:CTSolvers.Integrators.AbstractIntegrationResult, 1}
) -> Any

Merge a sequence of integration results into a single result.

This is used for concatenating multi-phase trajectories. Concrete integrator types implement this method for their specific result types, typically in a backend extension.

Arguments

• segments::AbstractVector{T}: Sequence of integration results to merge, where T <: AbstractIntegrationResult.

Returns

• A single CTSolvers.Integrators.AbstractIntegrationResult representing the merged trajectory.

Throws

• CTBase.Exceptions.NotImplemented: until a backend extension provides the typed method.

See also: CTSolvers.Integrators.AbstractIntegrator, CTSolvers.Integrators.AbstractIntegrationResult.

merge(
    segments::AbstractVector{<:CTSolversSciMLIntegrator.SciMLIntegrationResult}
) -> Any

Merge a sequence of SciML integration results into a single result by concatenating their time and state vectors. Used for multi-phase trajectories.

options_point [Function]

CTSolvers.Integrators.options_point Function

options_point(
    integ::CTSolvers.Integrators.SciML
) -> Dict{Symbol, Any}

Return the pre-computed option dictionary for point (final-state) integration.

See also: CTSolvers.Integrators.options_trajectory.

options_trajectory [Function]

CTSolvers.Integrators.options_trajectory Function

options_trajectory(
    integ::CTSolvers.Integrators.SciML
) -> Dict{Symbol, Any}

Return the pre-computed option dictionary for trajectory integration.

See also: CTSolvers.Integrators.options_point.

status [Function]

CTSolvers.Integrators.status Function

status(
    r::CTSolvers.Integrators.AbstractIntegrationResult
) -> Any

Return the termination status of the integration result, as a Symbol.

Arguments

• r::AbstractIntegrationResult: The integration result.

Throws

• CTBase.Exceptions.NotImplemented: If not implemented by the concrete type.

See also: CTSolvers.Integrators.AbstractIntegrationResult, CTSolvers.Integrators.successful.

status(
    r::CTSolversSciMLIntegrator.SciMLIntegrationResult
) -> Any

Return the termination status of the SciML ODE solution, as a Symbol derived from its retcode (e.g. :Success, :MaxIters).

successful [Function]

CTSolvers.Integrators.successful Function

successful(
    r::CTSolvers.Integrators.AbstractIntegrationResult
) -> Any

Return whether the integration terminated successfully.

Arguments

• r::AbstractIntegrationResult: The integration result.

Throws

• CTBase.Exceptions.NotImplemented: If not implemented by the concrete type.

See also: CTSolvers.Integrators.AbstractIntegrationResult, CTSolvers.Integrators.status.

successful(
    r::CTSolversSciMLIntegrator.SciMLIntegrationResult
) -> Any

Return whether the SciML ODE solution terminated successfully, per SciMLBase.successful_retcode.

times [Function]

CTSolvers.Integrators.times Function

times(
    r::CTSolvers.Integrators.AbstractIntegrationResult
) -> Any

Return the vector of time points from the integration result.

Arguments

• r::AbstractIntegrationResult: The integration result.

Throws

• CTBase.Exceptions.NotImplemented: If not implemented by the concrete type.

See also: CTSolvers.Integrators.AbstractIntegrationResult, CTSolvers.Integrators.final_state, CTSolvers.Integrators.evaluate_at.

times(
    r::CTSolversSciMLIntegrator.SciMLIntegrationResult
) -> Any

Return the vector of time points from the SciML ODE solution.