Public API

This page lists exported symbols of CTFlows.Integrators.

From `CTFlows.Integrators`

`CTFlows.Integrators` [Module]

CTFlows.Integrators — Module

Integrators

ODE integrator strategy types for CTFlows.

This module defines the AbstractIntegrator type which inherits from CTBase.Strategies.AbstractStrategy.

`AbstractIntegrationResult` [Abstract Type]

CTFlows.Integrators.AbstractIntegrationResult — Type

abstract type AbstractIntegrationResult

Abstract supertype for integration results produced by integrators.

This abstraction decouples the Trajectories 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.

`AbstractIntegrator` [Abstract Type]

CTFlows.Integrators.AbstractIntegrator — Type

abstract type AbstractIntegrator <: CTBase.Strategies.AbstractStrategy

Abstract strategy for solving ODE Cauchy problems.

An AbstractIntegrator is a strategy that solves an ODE problem over a time span.

This type inherits the CTBase.Strategies strategy contract:

Type-Level Contract (Static Metadata)

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

id(::Type{<:S}) → Symbol: Unique identifier for routing and introspection
metadata(::Type{<:S}) → StrategyMetadata: Option specifications and validation rules

Instance-Level Contract (Configured State)

Methods defined on instances that provide the actual configuration:

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

Concrete Implementation

All subtypes must implement three named functions:

build_problem(integrator::AbstractIntegrator, system::CTFlows.Systems.AbstractSystem, config::CTFlows.Configs.AbstractConfig; variable, cache): Build the ODE problem representation from a system and configuration.
build_options(integrator::AbstractIntegrator, config::Union{CTFlows.Configs.AbstractConfig, Nothing}): Build solver options dict for the given configuration.
solve_problem(integrator::AbstractIntegrator, prob, options::Dict{Symbol,Any}): Solve the given ODE problem with resolved options (tspan is embedded in prob).

Additionally, for multi-phase trajectory support, subtypes should implement:

merge(segments::AbstractVector{<:CTFlows.Integrators.AbstractIntegrationResult}): Merge a sequence of integration results into a single result (used for concatenating multi-phase trajectories).

Throws

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

`AbstractSciMLIntegrator` [Abstract Type]

CTFlows.Integrators.AbstractSciMLIntegrator — Type

abstract type AbstractSciMLIntegrator <: CTFlows.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

Example

julia> using CTFlows.Integrators

julia> SciML <: AbstractSciMLIntegrator
true

`SciML` [Struct]

CTFlows.Integrators.SciML — Type

struct SciML{O<:CTBase.Strategies.StrategyOptions, OP<:Dict{Symbol, Any}, OT<:Dict{Symbol, Any}} <: CTFlows.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 callable) is provided by the CTFlowsSciMLIntegrator package extension; this file declares the type and stubs that throw ExtensionError until the extension is loaded.

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 StateEndPointConfig.
options_trajectory::Dict{Symbol, Any}: Pre-computed options for StateTrajectoryConfig.

`SciMLTag` [Struct]

CTFlows.Integrators.SciMLTag — Type

struct SciMLTag <: CTBase.Core.AbstractTag

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

`Tsit5Tag` [Struct]

CTFlows.Integrators.Tsit5Tag — Type

struct Tsit5Tag <: CTBase.Core.AbstractTag

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

`build_integrator` [Function]

CTFlows.Integrators.build_integrator — Function

build_integrator(
;
    kwargs...
) -> CTFlows.Integrators.SciML{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

CTFlows.Integrators.SciML: The configured integrator.

Example

using CTFlows.Integrators

integrator = Integrators.build_integrator(reltol=1e-8, alg=Tsit5())

`build_problem` [Function]

CTFlows.Integrators.build_problem — Function

build_problem(
    integrator::CTFlows.Integrators.AbstractIntegrator,
    system::CTFlows.Systems.AbstractSystem,
    config::CTFlows.Configs.AbstractConfig;
    variable,
    cache
)

Build the ODE problem representation from a system and configuration.

Arguments

integrator::AbstractIntegrator: The integrator strategy.
system::CTFlows.Systems.AbstractSystem: The system to build a problem for.
config::CTFlows.Configs.AbstractConfig: The integration configuration.
variable: The variable parameter value (required for NonFixed systems).
cache: The cache for Hamiltonian systems (returns nothing for WithoutAD).

Returns

The ODE problem representation (type varies by concrete integrator).

Throws

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

build_problem(
    ::CTFlows.Integrators.SciML,
    system::CTFlows.Systems.AbstractSystem,
    config::CTFlows.Configs.AbstractConfig;
    variable
)

Build an ODEProblem from a system and a non-augmented configuration.

Dispatches between in-place and out-of-place RHS based on the mutability of the initial condition:

If ismutable(u0) is true, uses Systems.get_ip_rhs(system, config) with signature (du, u, p, t) -> nothing.
If ismutable(u0) is false (e.g., StaticArrays.SVector), uses Systems.get_oop_rhs(system, config) with signature (u, p, t) -> du.

Covers both state systems (AbstractStateSystem) and non-augmented Hamiltonian systems (AbstractHamiltonianSystem with AbstractHamiltonianConfig).

Arguments

integ::SciML: The SciML integrator strategy.
system::Systems.AbstractSystem: The system to build an ODE problem for.
config::Configs.AbstractConfig: The configuration containing initial condition and time span.
variable: Variable parameter for non-fixed systems.

Returns

SciMLBase.ODEProblem: The ODE problem ready for integration.

Throws

CTBase.Exceptions.PreconditionError: If the system dynamics trait is incompatible with the config type.

build_problem(
    ::CTFlows.Integrators.SciML,
    system::CTFlows.Systems.AbstractSystem,
    config::CTFlows.Configs.AbstractAugmentedHamiltonianConfig;
    variable
)

Build an ODEProblem for augmented Hamiltonian systems.

Uses the augmented RHS that computes state, costate, and variable costate derivatives. Always uses the in-place path since pv0 = zeros(...) guarantees mutability.

Arguments

integ::SciML: The SciML integrator strategy.
system::Systems.AbstractSystem: The Hamiltonian system.
config::Configs.AbstractAugmentedHamiltonianConfig: The augmented Hamiltonian configuration.
variable: Variable parameter for the augmented system.

Returns

SciMLBase.ODEProblem: The ODE problem with augmented RHS.

Throws

CTBase.Exceptions.PreconditionError: If the system dynamics trait is incompatible with the config type.

Notes

Only in-place path is implemented; pv0 = zeros(...) guarantees mutability by construction.
TODO: Add out-of-place path for SVector support in the future.

`build_sciml_integrator` [Function]

CTFlows.Integrators.build_sciml_integrator — Function

build_sciml_integrator(
    ::Type{<:CTBase.Core.AbstractTag};
    kwargs...
) -> CTFlows.Integrators.SciML{CTBase.Strategies.StrategyOptions{NT}, Dict{Symbol, Any}, Dict{Symbol, Any}} where NT<:NamedTuple

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

build_sciml_integrator(
    ::Type{CTFlows.Integrators.SciMLTag};
    mode,
    kwargs...
) -> CTFlows.Integrators.SciML{CTBase.Strategies.StrategyOptions{NT}, Dict{Symbol, Any}, Dict{Symbol, Any}} where NT<:NamedTuple

Build a SciML integrator with validated options and pre-computed config-specific options.

This function constructs a SciML integrator with automatic resolution of config-dependent options. Options in _AUTO_OPTION_KEYS support the :auto sentinel value, which is resolved based on the configuration type used during integration:

For StateEndPointConfig (e.g., flow(t0, x0, tf)): options set to false to minimize memory since only the final state is needed
For StateTrajectoryConfig (e.g., flow((t0, tf), x0)): options set to true to enable full trajectory storage and interpolation

The resolved options are pre-computed and cached in the integrator for performance, avoiding repeated resolution during integration.

Arguments

::Type{CTFlows.Integrators.SciMLTag}: The SciML integrator tag type.
mode::Symbol: Validation mode for strategy options (:strict or :permissive).
kwargs...: User-provided option values. Explicit true/false values override automatic :auto resolution.

Returns

CTFlows.Integrators.SciML: Parametric SciML integrator with cached options_point and options_trajectory fields.

Notes

The :auto sentinel is defined in option metadata as Union{Bool, Symbol} with default :auto.
Pre-computation happens at construction time, not during integration.
Config-specific options are returned by Integrators.build_options based on dispatch on the configuration type.

`evaluate_at` [Function]

CTFlows.Integrators.evaluate_at — Function

evaluate_at(
    r::CTFlows.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.

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

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

Arguments

r::SciMLIntegrationResult: The integration result.
t::Real: The time at which to evaluate the solution.

Returns

The state vector at time t.

`final_state` [Function]

CTFlows.Integrators.final_state — Function

final_state(
    r::CTFlows.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.

final_state(
    sol::CTFlows.Trajectories.VectorFieldTrajectory
) -> Any

Return the final state from the solution by delegating to the integration result.

Arguments

sol::VectorFieldTrajectory: The vector field solution.

Returns

The final state from the integration result.

final_state(
    sol::CTFlows.Trajectories.HamiltonianVectorFieldTrajectory
) -> Tuple{Any, Any}

Return the raw final ODE state vector [xf; pf] from the integration result.

Delegates directly to the underlying integration result without splitting. Callers that need the split form should use _ham_split_solution explicitly.

Arguments

sol::HamiltonianVectorFieldTrajectory: The Hamiltonian vector field solution.

Returns

AbstractVector: The concatenated final state [xf; pf].

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

Return the final state vector from the SciML ODE solution.

Arguments

r::SciMLIntegrationResult: The integration result.

Returns

The final state vector.

`merge` [Function]

CTFlows.Integrators.merge — Function

merge(
    segments::AbstractArray{T<:CTFlows.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 should implement this method for their specific result types.

Arguments

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

Returns

A single AbstractIntegrationResult representing the merged trajectory.

Throws

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

merge(
    segments::AbstractVector{<:CTFlows.Trajectories.VectorFieldTrajectory}
) -> CTFlows.Trajectories.VectorFieldTrajectory

Merge a sequence of VectorFieldTrajectory objects into a single VectorFieldTrajectory.

This extracts the internal integration results, merges them, and wraps the result in a new VectorFieldTrajectory.

Arguments

segments::AbstractVector{<:VectorFieldTrajectory}: Sequence of vector field solutions to merge.

Returns

VectorFieldTrajectory: A merged vector field solution containing the merged integration result.

merge(
    segments::AbstractVector{<:CTFlows.Trajectories.HamiltonianVectorFieldTrajectory}
) -> CTFlows.Trajectories.HamiltonianVectorFieldTrajectory

Merge a sequence of HamiltonianVectorFieldTrajectory objects into a single HamiltonianVectorFieldTrajectory.

This extracts the internal integration results, merges them, and wraps the result in a new HamiltonianVectorFieldTrajectory.

Arguments

segments::AbstractVector{<:HamiltonianVectorFieldTrajectory}: Sequence of Hamiltonian vector field solutions to merge.

Returns

HamiltonianVectorFieldTrajectory: A merged Hamiltonian vector field solution containing the merged integration result.

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

Merge a sequence of SciML ODE solutions into a single solution. This allows concatenation of trajectories from multiple phases.

`solve_problem` [Function]

CTFlows.Integrators.solve_problem — Function

solve_problem(
    integrator::CTFlows.Integrators.AbstractIntegrator,
    prob,
    options::Dict{Symbol};
    unsafe
) -> CTFlowsSciMLIntegrator.SciMLIntegrationResult

Solve the given ODE problem with resolved options.

Arguments

integrator::AbstractIntegrator: The integrator strategy.
prob: The ODE problem to solve (type varies by concrete integrator; tspan is embedded).
options::Dict{Symbol,Any}: Resolved solver options (typically from build_options).
unsafe=Common.__unsafe(): If true, bypass ODE solver retcode checking; if false, throw SolverFailure on integration failure.

Returns

The ODE integration result, as a subtype of CTFlows.Integrators.AbstractIntegrationResult.

Throws

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

solve_problem(
    ::CTFlows.Integrators.SciML,
    prob::SciMLBase.AbstractODEProblem,
    options::Dict{Symbol};
    unsafe
) -> CTFlowsSciMLIntegrator.SciMLIntegrationResult

Solve an ODEProblem using resolved options. Returns a SciMLIntegrationResult wrapping the raw ODESolution.

Arguments

integ::Integrators.SciML: The SciML integrator strategy.
prob::SciMLBase.AbstractODEProblem: The ODE problem to solve.
options::Dict{Symbol,Any}: Resolved solver options (typically from build_options).
unsafe=Common.__unsafe(): If true, bypass ODE solver retcode checking; if false, throw SolverFailure on integration failure.

Returns

SciMLIntegrationResult: The integration result wrapping the SciML ODE solution.

Throws

CTBase.Exceptions.SolverFailure: If the ODE solver returns an unsuccessful retcode and unsafe=false.

`times` [Function]

CTFlows.Integrators.times — Function

times(
    r::CTFlows.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.

times(
    sol::CTFlows.Trajectories.VectorFieldTrajectory
) -> Any

Return the vector of time points from the solution.

Delegates to Integrators.times(sol.result).

Arguments

sol::VectorFieldTrajectory: The vector field solution.

Returns

AbstractVector: The vector of time points.

times(
    sol::CTFlows.Trajectories.HamiltonianVectorFieldTrajectory
) -> Any

Return the vector of time points from the solution.

Delegates to Integrators.times(sol.result).

Arguments

sol::HamiltonianVectorFieldTrajectory: The Hamiltonian vector field solution.

Returns

AbstractVector: The vector of time points.

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

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

Arguments

r::SciMLIntegrationResult: The integration result.

Returns

Vector of time points.