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.

Subtypes may also implement:

• is_dense(r::SubType): Whether evaluate_at reads a dense interpolant (default false).

• regrid(r::SubType, grid): A copy of the result on another output grid.

• merge(segments::AbstractVector{SubType}): Combine consecutive results of a multi-phase integration (see CTSolvers.Integrators.PiecewiseIntegrationResult).

See also: CTSolvers.Integrators.final_state, CTSolvers.Integrators.times, CTSolvers.Integrators.evaluate_at, CTModels.Solutions.status, CTModels.Solutions.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.

PiecewiseIntegrationResult [Struct]

CTSolvers.Integrators.PiecewiseIntegrationResult Type

struct PiecewiseIntegrationResult{V<:(AbstractVector), W<:(AbstractVector)} <: CTSolvers.Integrators.AbstractIntegrationResult

Integration result made of consecutive segments, one per phase of a multi-phase integration. Each segment keeps its own result, so evaluation inside a phase reads that phase's interpolant (dense segments stay solver-accurate).

The trajectory is left-continuous at a switching time: evaluate_at(r, tᵢ) returns the end value of the segment that finishes at tᵢ (before any jump), and any time strictly after tᵢ belongs to the next segment. The value after the jump is read with CTSolvers.Integrators.right_limit. The time grid concatenates the segments' grids and keeps a single copy of each switching time, so it is strictly monotone.

Fields

• segments::V: The per-phase results, in integration order.

• switches::W: The n - 1 switching times (end time of every segment but the last).

• grid::W: The concatenated time grid of all segments, each switching time once.

See also: CTSolvers.Integrators.merge, CTSolvers.Integrators.switching_times, CTSolvers.Integrators.AbstractIntegrationResult.

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{Strategies.CPU}: CPU execution (default);

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

SciML(...) builds a SciML{Strategies.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.

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::CTSolvers.Integrators.PiecewiseIntegrationResult,
    t::Real
) -> Any

Evaluate the segment holding time t (left-continuous at switching 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::CTSolvers.Integrators.PiecewiseIntegrationResult
) -> Any

Return the final state of the last segment.

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

Return the final state vector from the SciML ODE solution.

is_dense [Function]

CTSolvers.Integrators.is_dense Function

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

Return whether evaluate_at reads a dense (solver-accurate) interpolant at every time of the integration span.

When false, values between the stored time points are only an approximation (e.g. a linear interpolation), whose accuracy is bounded by the spacing of CTSolvers.Integrators.times rather than by the solver tolerances. Defaults to false; concrete result types that keep a dense interpolant override it.

Arguments

• r::AbstractIntegrationResult: The integration result.

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

is_dense(
    r::CTSolvers.Integrators.PiecewiseIntegrationResult
) -> Any

Return whether every segment is dense.

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

Return whether the SciML ODE solution carries a dense interpolant.

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 CTSolvers.Integrators.PiecewiseIntegrationResult. Each phase keeps its own solution and interpolant, so a dense multi-phase trajectory is as accurate as a single-phase one. A single segment is returned unchanged.

Throws

• CTBase.Exceptions.IncorrectArgument: If segments is empty.

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.

regrid [Function]

CTSolvers.Integrators.regrid Function

regrid(
    r::CTSolvers.Integrators.PiecewiseIntegrationResult,
    grid::AbstractVector{<:Real}
) -> CTSolvers.Integrators.PiecewiseIntegrationResult

Return a copy of the piecewise result whose time grid is grid; the segments (and their interpolants) are shared, and a switching time is evaluated left-continuously as before.

Throws

• CTBase.Exceptions.IncorrectArgument: If grid is not a valid output grid for the integration span.

regrid(
    r::CTSolvers.Integrators.AbstractIntegrationResult,
    grid::AbstractVector{<:Real}
) -> CTSolversSciMLIntegrator.SciMLIntegrationResult

Return a copy of the integration result whose output time grid (CTSolvers.Integrators.times) is grid. The integration is not redone: the values on the new grid are read with CTSolvers.Integrators.evaluate_at (dense interpolant when CTSolvers.Integrators.is_dense). The original result is left unchanged.

grid must hold at least two times, be strictly monotone in the integration direction and lie in the integration span. Concrete result types implement this method, typically in a backend extension.

Throws

• CTBase.Exceptions.IncorrectArgument: If grid is invalid (in the concrete methods).

• CTBase.Exceptions.NotImplemented: For a result type without a regrid method.

See also: CTSolvers.Integrators.times, CTSolvers.Integrators.PiecewiseIntegrationResult.

regrid(
    r::CTSolversSciMLIntegrator.SciMLIntegrationResult,
    grid::AbstractVector{<:Real}
) -> CTSolversSciMLIntegrator.SciMLIntegrationResult

Return a copy of the result whose output grid is grid; the ODE solution (and its interpolant) is shared, values on the grid are read with evaluate_at.

Throws

• CTBase.Exceptions.IncorrectArgument: If grid is not a valid output grid for the integration span.

right_limit [Function]

CTSolvers.Integrators.right_limit Function

right_limit(
    r::CTSolvers.Integrators.PiecewiseIntegrationResult,
    i::Integer
) -> Any

Return the value just after the i-th switching time tᵢ: the start value of segment i + 1, after any jump applied at tᵢ. CTSolvers.Integrators.evaluate_at at tᵢ returns the value before the jump, so the two give both limits at tᵢ.

"After" follows the integration order: for a backward integration, it is the limit on the smaller-time side.

Throws

• CTBase.Exceptions.IncorrectArgument: If i is not the index of a switching time (1 ≤ i ≤ n - 1 for n segments).

See also: CTSolvers.Integrators.switching_times.

status [Function]

CTSolvers.Integrators.status Function

Alias for CTModels.Solutions.status — same Function object, so Integrators.status === CTModels.Solutions.status, and extending either extends both.

successful [Function]

CTSolvers.Integrators.successful Function

Alias for CTModels.Solutions.successful — same Function object, so Integrators.successful === CTModels.Solutions.successful, and extending either extends both.

switching_times [Function]

CTSolvers.Integrators.switching_times Function

switching_times(
    r::CTSolvers.Integrators.PiecewiseIntegrationResult
) -> AbstractVector

Return the switching times of a piecewise result: the end time of every segment but the last, in integration order.

See also: CTSolvers.Integrators.right_limit.

switching_times(
    r::CTSolvers.Integrators.AbstractIntegrationResult
) -> AbstractVector

Return the switching times of a single-phase result: there are none.

See also: CTSolvers.Integrators.switching_times.

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::CTSolvers.Integrators.PiecewiseIntegrationResult
) -> AbstractVector

Return the concatenated time grid of all segments, each switching time once.

times(
    r::CTSolversSciMLIntegrator.SciMLIntegrationResult{<:Any, Nothing}
) -> Any

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

times(
    r::CTSolversSciMLIntegrator.SciMLIntegrationResult{<:Any, <:AbstractVector}
) -> AbstractVector

Return the output grid requested through saveat (the solution itself is kept dense).