CTFlows.jl

Appearance

Public API ​

This page lists exported symbols of CTFlows.Trajectories.

From CTFlows.Trajectories ​

CTFlows.Trajectories [Module] ​

CTFlows.Trajectories Module
julia
Trajectories

Trajectory types and trajectory building for CTFlows.

This module provides:

  • AbstractIntegrationResult: Abstraction for raw ODE integration results

  • VectorFieldTrajectory: Trajectory type wrapping integration results

  • build_trajectory: Trajectory building functions for different configuration types

  • final_state, times, evaluate_at: Semantic accessors for integration results

  • state, time_grid: Semantic accessors for VectorFieldTrajectory

  • Trajectories.plot: plotting for trajectories via the Plots extension (a RecipesBase.plot method; not re-exported — call it qualified or load Plots)

See also: CTSolvers.Integrators.AbstractIntegrationResult, CTFlows.Trajectories.VectorFieldTrajectory, CTFlows.Trajectories.build_trajectory.

AbstractHamiltonianVectorFieldTrajectory [Abstract Type] ​

CTFlows.Trajectories.AbstractHamiltonianVectorFieldTrajectory Type
julia
abstract type AbstractHamiltonianVectorFieldTrajectory

Abstract supertype for Hamiltonian vector field solution containers.

This type defines the interface for all solution types that wrap ODE integration results for Hamiltonian systems.

See also: CTFlows.Trajectories.HamiltonianVectorFieldTrajectory, CTSolvers.Integrators.AbstractIntegrationResult.

AbstractVectorFieldTrajectory [Abstract Type] ​

CTFlows.Trajectories.AbstractVectorFieldTrajectory Type
julia
abstract type AbstractVectorFieldTrajectory

Abstract supertype for vector field solution containers.

This type defines the interface for all solution types that wrap ODE integration results.

See also: CTFlows.Trajectories.VectorFieldTrajectory, CTSolvers.Integrators.AbstractIntegrationResult.

ControlProjection [Struct] ​

CTFlows.Trajectories.ControlProjection Type
julia
struct ControlProjection{T<:CTFlows.Trajectories.VectorFieldTrajectory, L, V, C} <: Function

Callable struct returning the reconstructed control of a CTFlows.Trajectories.StateFlowTrajectory: ControlProjection(sol)(t) = law(t, x(t), v). A functor (not a closure); the state coercion is precomputed.

CostateProjection [Struct] ​

CTFlows.Trajectories.CostateProjection Type
julia
struct CostateProjection{R<:CTSolvers.Integrators.AbstractIntegrationResult, X0} <: Function

Callable struct returning the costate component of a HamiltonianVectorFieldTrajectory.

CostateProjection(result, x0)(t) is equivalent to sol(t)[2]. It wraps the inner integration result and x0 (not the trajectory itself), so it is constructed once at trajectory construction and stored, and the costate(sol) accessor returns it without rebuilding a functor on every call.

HamiltonianVectorFieldTrajectory [Struct] ​

CTFlows.Trajectories.HamiltonianVectorFieldTrajectory Type
julia
struct HamiltonianVectorFieldTrajectory{X0, R<:CTSolvers.Integrators.AbstractIntegrationResult, V, SP, CP} <: CTFlows.Trajectories.AbstractHamiltonianVectorFieldTrajectory

Container for the integration result from a HamiltonianTrajectoryConfig integration.

This type wraps the integration result returned by integrators and provides semantic accessors for time grids, state functions, and costate functions.

Fields

  • result: The integration result object (subtype of AbstractIntegrationResult).

Accessors

  • times(sol): Get the time grid (alias: time_grid(sol))

  • state(sol): Get the solution as a callable state function x(t)

  • costate(sol): Get the solution as a callable costate function p(t)

  • sol(t): Evaluate the solution at time t, returning tuple (x(t), p(t))

Example

julia
using CTFlows.Trajectories

sol = HamiltonianVectorFieldTrajectory(result)
ts = times(sol)           # or time_grid(sol)
x = state(sol)            # callable state function x(t)
p = costate(sol)          # callable costate function p(t)
x(0.5), p(0.5)           # evaluate at t = 0.5
x0, p0 = sol(0.0)        # returns tuple (x(0), p(0))

See also: CTSolvers.Integrators.AbstractIntegrationResult, CTFlows.Trajectories.AbstractHamiltonianVectorFieldTrajectory.

StateFlowTrajectory [Struct] ​

CTFlows.Trajectories.StateFlowTrajectory Type
julia
struct StateFlowTrajectory{T<:CTFlows.Trajectories.VectorFieldTrajectory, L, V, O, C, M, SP, CP} <: CTFlows.Trajectories.AbstractVectorFieldTrajectory

Trajectory of a controlled dynamical system, as produced by an OpenLoop or ClosedLoop control flow. It carries the state trajectory together with the control law, from which the control is reconstructed along the trajectory. There is no costate (the underlying flow is a state flow) and no objective.

Fields

  • traj::T: the underlying state trajectory (a CTFlows.Trajectories.VectorFieldTrajectory).

  • law::L: the control law (OpenLoop or ClosedLoop).

  • variable::V: the variable threaded through the flow call (or Core.NotProvided).

  • objective::O: the objective value (Mayer + Lagrange with the reconstructed control) when the trajectory was built from an OCP, or nothing (e.g. from Flow(fc, law)).

  • state_coerce::C: the state coercion (only for a 1-D state, identity otherwise), precomputed once so the state/control projections never test a length at run time.

  • ocp::M: the OCP model the controlled flow was built from — the source of the component names (state/control) and the time name for plotting — or nothing (e.g. from Flow(fc, law)).

Accessors

  • state(sol): callable state function x(t).

  • control(sol): callable control function u(t) = law(t, x(t), v).

  • objective(sol): the objective value (errors if unavailable).

  • times(sol) / time_grid(sol): the time grid.

  • sol(t): the state at time t.

  • costate(sol): errors — a controlled state trajectory has no costate.

See also: CTFlows.Trajectories.VectorFieldTrajectory, CTFlows.Trajectories.state, CTFlows.Trajectories.control.

StateProjection [Struct] ​

CTFlows.Trajectories.StateProjection Type
julia
struct StateProjection{R<:CTSolvers.Integrators.AbstractIntegrationResult, X0} <: Function

Callable struct returning the state component of a HamiltonianVectorFieldTrajectory.

StateProjection(result, x0)(t) is equivalent to sol(t)[1]. It wraps the inner integration result and x0 (not the trajectory itself), so it is constructed once at trajectory construction and stored, and the state(sol) accessor returns it without rebuilding a functor on every call.

VectorFieldTrajectory [Struct] ​

CTFlows.Trajectories.VectorFieldTrajectory Type
julia
struct VectorFieldTrajectory{R<:CTSolvers.Integrators.AbstractIntegrationResult, V} <: CTFlows.Trajectories.AbstractVectorFieldTrajectory

Container for the integration result from a StateTrajectoryConfig integration.

This type wraps the integration result returned by integrators and provides semantic accessors for time grids and state functions.

Fields

  • result: The integration result object (subtype of AbstractIntegrationResult).

  • variable: The variable value threaded through the flow call, or Core.NotProvided when the flow carries no variable.

Accessors

  • times(sol): Get the time grid (alias: time_grid(sol))

  • state(sol): Get the solution as a callable state function

  • sol(t): Evaluate the solution at time t (equivalent to state(sol)(t))

Example

julia
using CTFlows.Trajectories

sol = VectorFieldTrajectory(result)
ts = times(sol)           # or time_grid(sol)
x = state(sol)            # callable state function
x(0.5)                    # evaluate at t = 0.5

See also: CTSolvers.Integrators.AbstractIntegrationResult, CTFlows.Trajectories.AbstractVectorFieldTrajectory.

build_trajectory [Function] ​

CTFlows.Trajectories.build_trajectory Function
julia
build_trajectory(
    ::Type{CTBase.Traits.EndPointMode},
    ::Type{CTBase.Traits.StateDynamics},
    config::CTFlows.Configs.AbstractConfig,
    result::CTSolvers.Integrators.AbstractIntegrationResult
) -> Any
build_trajectory(
    ::Type{CTBase.Traits.EndPointMode},
    ::Type{CTBase.Traits.StateDynamics},
    config::CTFlows.Configs.AbstractConfig,
    result::CTSolvers.Integrators.AbstractIntegrationResult,
    variable
) -> Any

Default implementation for scalar point configs — return the final state.

For scalar configurations (initial_state <: Number), unwraps the length-1 vector that was introduced by scalar-promotion at ODE problem construction time.

This uses compile-time dispatch on the initial state type to avoid runtime type tests.

Arguments

  • ::Type{Traits.EndPointMode}: The point mode trait type.

  • ::Type{Traits.StateDynamics}: The state content trait type.

  • initial_state::Number: The scalar initial state.

  • result::Integrators.AbstractIntegrationResult: The integration result.

Returns

  • Number: The unwrapped scalar final state.

See also: CTSolvers.Integrators.AbstractIntegrationResult, CTBase.Traits.EndPointMode, CTBase.Traits.StateDynamics.

julia
build_trajectory(
    ::Type{CTBase.Traits.TrajectoryMode},
    ::Type{CTBase.Traits.StateDynamics},
    config::CTFlows.Configs.AbstractConfig,
    result::CTSolvers.Integrators.AbstractIntegrationResult
) -> CTFlows.Trajectories.VectorFieldTrajectory{R, CTBase.Core.NotProvidedType} where R<:CTSolvers.Integrators.AbstractIntegrationResult
build_trajectory(
    ::Type{CTBase.Traits.TrajectoryMode},
    ::Type{CTBase.Traits.StateDynamics},
    config::CTFlows.Configs.AbstractConfig,
    result::CTSolvers.Integrators.AbstractIntegrationResult,
    variable
) -> CTFlows.Trajectories.VectorFieldTrajectory

Default implementation for trajectory configs — wrap the integration result in a VectorFieldTrajectory for future extensibility.

Arguments

  • ::Type{Traits.TrajectoryMode}: The trajectory mode trait type.

  • ::Type{Traits.StateDynamics}: The state content trait type.

  • initial_state: The initial state.

  • result::Integrators.AbstractIntegrationResult: The integration result.

Returns

  • VectorFieldTrajectory: The wrapped integration result.

See also: CTSolvers.Integrators.AbstractIntegrationResult, CTFlows.Trajectories.VectorFieldTrajectory, CTBase.Traits.TrajectoryMode, CTBase.Traits.StateDynamics.

julia
build_trajectory(
    ::Type{CTBase.Traits.EndPointMode},
    ::Type{CTBase.Traits.HamiltonianDynamics},
    config::CTFlows.Configs.AbstractConfig,
    result::CTSolvers.Integrators.AbstractIntegrationResult
) -> Tuple{Any, Any}
build_trajectory(
    ::Type{CTBase.Traits.EndPointMode},
    ::Type{CTBase.Traits.HamiltonianDynamics},
    config::CTFlows.Configs.AbstractConfig,
    result::CTSolvers.Integrators.AbstractIntegrationResult,
    variable
) -> Tuple{Any, Any}

Build a solution for Hamiltonian point configs.

Returns the final state and costate as a tuple (xf, pf), dispatching on the type of the initial state to handle scalar, vector, and matrix cases.

Arguments

  • ::Type{Traits.EndPointMode}: The point mode trait type.

  • ::Type{Traits.HamiltonianDynamics}: The Hamiltonian content trait type.

  • initial_state: The initial state (scalar, vector, or matrix).

  • result::Integrators.AbstractIntegrationResult: The integration result.

Returns

  • Tuple: The final state and costate. Type depends on initial_state:

    • Tuple{Number, Number} for scalar inputs

    • Tuple{AbstractVector, AbstractVector} for vector inputs

    • Tuple{AbstractMatrix, AbstractMatrix} for matrix inputs

See also: CTSolvers.Integrators.AbstractIntegrationResult, CTBase.Traits.EndPointMode, CTBase.Traits.HamiltonianDynamics.

julia
build_trajectory(
    ::Type{CTBase.Traits.TrajectoryMode},
    ::Type{CTBase.Traits.HamiltonianDynamics},
    config::CTFlows.Configs.AbstractConfig,
    result::CTSolvers.Integrators.AbstractIntegrationResult
) -> CTFlows.Trajectories.HamiltonianVectorFieldTrajectory{_A, var"#s179", CTBase.Core.NotProvidedType, CTFlows.Trajectories.StateProjection{R, _A1}, CTFlows.Trajectories.CostateProjection{R1, _A2}} where {_A, var"#s179"<:CTSolvers.Integrators.AbstractIntegrationResult, R<:CTSolvers.Integrators.AbstractIntegrationResult, _A1, R1<:CTSolvers.Integrators.AbstractIntegrationResult, _A2}
build_trajectory(
    ::Type{CTBase.Traits.TrajectoryMode},
    ::Type{CTBase.Traits.HamiltonianDynamics},
    config::CTFlows.Configs.AbstractConfig,
    result::CTSolvers.Integrators.AbstractIntegrationResult,
    variable
) -> CTFlows.Trajectories.HamiltonianVectorFieldTrajectory{_A, var"#s179", _B, CTFlows.Trajectories.StateProjection{R, _A1}, CTFlows.Trajectories.CostateProjection{R1, _A2}} where {_A, var"#s179"<:CTSolvers.Integrators.AbstractIntegrationResult, _B, R<:CTSolvers.Integrators.AbstractIntegrationResult, _A1, R1<:CTSolvers.Integrators.AbstractIntegrationResult, _A2}

Build a solution for Hamiltonian trajectory configs.

Wraps the integration result in a HamiltonianVectorFieldTrajectory for future extensibility.

Arguments

  • ::Type{Traits.TrajectoryMode}: The trajectory mode trait type.

  • ::Type{Traits.HamiltonianDynamics}: The Hamiltonian content trait type.

  • initial_state: The initial state.

  • result::Integrators.AbstractIntegrationResult: The integration result.

Returns

  • HamiltonianVectorFieldTrajectory: The wrapped integration result.

See also: CTSolvers.Integrators.AbstractIntegrationResult, CTFlows.Trajectories.HamiltonianVectorFieldTrajectory, CTBase.Traits.TrajectoryMode, CTBase.Traits.HamiltonianDynamics.

julia
build_trajectory(
    ::Type{CTBase.Traits.EndPointMode},
    ::Type{CTBase.Traits.AugmentedHamiltonianDynamics},
    config::CTFlows.Configs.AbstractConfig,
    result::CTSolvers.Integrators.AbstractIntegrationResult
) -> Tuple{Any, Any, Any}
build_trajectory(
    ::Type{CTBase.Traits.EndPointMode},
    ::Type{CTBase.Traits.AugmentedHamiltonianDynamics},
    config::CTFlows.Configs.AbstractConfig,
    result::CTSolvers.Integrators.AbstractIntegrationResult,
    variable
) -> Tuple{Any, Any, Any}

Build a solution for augmented Hamiltonian point configs.

Returns the final state, costate, and variable costate as a tuple (xf, pf, pvf). For Hamiltonian systems, n_p = n_x always, so the augmented state [x; p; pv] splits using only the state dimension n = length(initial_state).

Arguments

  • ::Type{Traits.EndPointMode}: The point mode trait type.

  • ::Type{Traits.AugmentedHamiltonianDynamics}: The augmented Hamiltonian content trait type.

  • initial_state: The initial state (used to determine state dimension n).

  • result::Integrators.AbstractIntegrationResult: The integration result.

Returns

  • Tuple{AbstractVector, AbstractVector, AbstractVector}: Tuple (xf, pf, pvf).

Notes

  • Uses _aug_split_solution helper to split the augmented final state.

  • Assumes n_p = n_x invariant for Hamiltonian systems.

See also: CTSolvers.Integrators.AbstractIntegrationResult, CTBase.Traits.EndPointMode, CTBase.Traits.AugmentedHamiltonianDynamics.

control [Function] ​

CTFlows.Trajectories.control Function
julia
control(
    sol::CTFlows.Trajectories.StateFlowTrajectory
) -> CTFlows.Trajectories.ControlProjection

Return the reconstructed control function u(t) = law(t, x(t), v) of a StateFlowTrajectory, as the stored CTFlows.Trajectories.ControlProjection.

Raises a CTBase.Exceptions.PreconditionError when the trajectory was built without a control law (a basic control-free Flow(ocp)), which has no control to reconstruct.

See also: CTFlows.Trajectories.state.

costate [Function] ​

CTFlows.Trajectories.costate Function
julia
costate(
    sol::CTFlows.Trajectories.HamiltonianVectorFieldTrajectory
) -> Any

Return the solution as a costate function of time p(t).

Returns a CTFlows.Trajectories.CostateProjection wrapping the solution, callable as p(t).

Arguments

  • sol::HamiltonianVectorFieldTrajectory: The Hamiltonian vector field solution.

Returns

  • CostateProjection: A callable t -> p(t) that returns the costate at time t.

Example

julia
using CTFlows.Trajectories

sol = HamiltonianVectorFieldTrajectory(result)
p = costate(sol)  # p is a callable CostateProjection
p(0.0)            # initial costate
p(0.5)            # interpolated costate at t = 0.5

See also: CTFlows.Trajectories.state, CTSolvers.Integrators.times.

julia
costate(sol::CTFlows.Trajectories.StateFlowTrajectory)

A StateFlowTrajectory has no costate — it is the trajectory of a controlled state flow (OpenLoop/ClosedLoop), not a Hamiltonian flow. Raises a PreconditionError pointing at the available getters.

See also: CTFlows.Trajectories.state, CTFlows.Trajectories.control.

objective [Function] ​

CTFlows.Trajectories.objective Function
julia
objective(
    sol::CTFlows.Trajectories.StateFlowTrajectory{T<:CTFlows.Trajectories.VectorFieldTrajectory, L, V, <:Real}
) -> Real

Return the objective value of a StateFlowTrajectory (Mayer + Lagrange, with the control reconstructed from the law). Available only when the trajectory was built from an OCP (trajectory mode); otherwise a clear error is raised.

See also: CTFlows.Trajectories.state, CTFlows.Trajectories.control.

julia
objective(
    sol::CTFlows.Trajectories.StateFlowTrajectory{T<:CTFlows.Trajectories.VectorFieldTrajectory, L, V, Nothing}
)

Throw a CTBase.Exceptions.PreconditionError when the objective is not available (the trajectory was built without an OCP, e.g. from Flow(fc, law)).

See also: CTFlows.Trajectories.objective.

state [Function] ​

CTFlows.Trajectories.state Function
julia
state(
    sol::CTFlows.Trajectories.VectorFieldTrajectory
) -> CTFlows.Trajectories.VectorFieldTrajectory

Return the solution itself as a state function of time.

This is a semantic accessor that returns sol itself (which is already callable), providing a clear, self-documenting way to obtain the trajectory function.

Arguments

  • sol::VectorFieldTrajectory: The vector field solution.

Returns

  • VectorFieldTrajectory: The solution itself, which is callable as a function of time.

Example

julia
using CTFlows.Trajectories

sol = VectorFieldTrajectory(result)
x = state(sol)    # x is a function of time
x(0.0)            # initial state
x(0.5)            # interpolated state at t = 0.5
x.(0.0:0.1:1.0)   # broadcast over time grid

Notes

  • This accessor provides a foundation for uniform semantic accessors in optimal control: state(sol), costate(sol), control(sol) when extended to Hamiltonian systems.

  • No allocation occurs — returns sol directly.

See also: CTSolvers.Integrators.times, CTSolvers.Integrators.evaluate_at, CTFlows.Trajectories.time_grid.

julia
state(
    sol::CTFlows.Trajectories.HamiltonianVectorFieldTrajectory
) -> Any

Return the solution as a state function of time x(t).

Returns a CTFlows.Trajectories.StateProjection wrapping the solution, callable as x(t).

Arguments

  • sol::HamiltonianVectorFieldTrajectory: The Hamiltonian vector field solution.

Returns

  • StateProjection: A callable t -> x(t) that returns the state at time t.

Example

julia
using CTFlows.Trajectories

sol = HamiltonianVectorFieldTrajectory(result)
x = state(sol)    # x is a callable StateProjection
x(0.0)            # initial state
x(0.5)            # interpolated state at t = 0.5

See also: CTFlows.Trajectories.costate, CTSolvers.Integrators.times.

julia
state(sol::CTFlows.Trajectories.StateFlowTrajectory) -> Any

Return the state function x(t) of a StateFlowTrajectory (scalar for a 1-D state).

Returns the stored CTFlows.Trajectories.ControlledStateProjection precomputed at construction.

See also: CTFlows.Trajectories.control.

time_grid [Function] ​

CTFlows.Trajectories.time_grid Function
julia
time_grid(
    sol::CTFlows.Trajectories.VectorFieldTrajectory
) -> Any

Alias for times(sol) — returns the time grid from the solution.

This is an alternative, more explicit name for times in numerical contexts where "time grid" is the standard terminology.

Arguments

  • sol::VectorFieldTrajectory: The vector field solution.

Returns

  • AbstractVector: The vector of time points.

Example

julia
using CTFlows.Trajectories

sol = VectorFieldTrajectory(result)
tg = time_grid(sol)  # same as times(sol)

Notes

  • time_grid and times are two names for the same operation.

  • Use time_grid when "grid" terminology is clearer in context.

  • Use times for brevity in everyday use.

See also: CTSolvers.Integrators.times, CTFlows.Trajectories.state.

julia
time_grid(
    sol::CTFlows.Trajectories.HamiltonianVectorFieldTrajectory
) -> Any

Alias for times(sol) — returns the time grid from the solution.

This is an alternative, more explicit name for times in numerical contexts where "time grid" is the standard terminology.

Arguments

  • sol::HamiltonianVectorFieldTrajectory: The Hamiltonian vector field solution.

Returns

  • AbstractVector: The vector of time points.

See also: CTSolvers.Integrators.times, CTFlows.Trajectories.state.

julia
time_grid(
    sol::CTFlows.Trajectories.StateFlowTrajectory
) -> Any

Alias for times(sol) — the time grid of a StateFlowTrajectory.