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

  • switching_times, phase_labels, left_limit, right_limit: the switching structure of a multi-phase trajectory (left-continuous at a switching time)

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

  • state, control, costate, objective, time_grid: methods on the CTModels.Components generics, contributed here for VectorFieldTrajectory, HamiltonianVectorFieldTrajectory and StateFlowTrajectory

  • Trajectories.plot: plotting stub for trajectories (a RecipesBase.plot method; not re-exported). Load Plots (CTFlowsPlots) or a Makie backend such as CairoMakie (CTFlowsMakie) to enable it; both dispatch through the CTFlows.TrajectoryPlots case layer

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

  • x0: The initial state, which drives the shape of the state and costate.

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

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

  • state_proj, costate_proj: The precomputed state and costate projections.

  • labels: The labels of the phases (one per phase, "" for no label), or no label at all (an empty vector), see CTFlows.Trajectories.phase_labels.

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))

  • switching_times(sol), phase_labels(sol), right_limit(sol, :state, i), right_limit(sol, :costate, i): the switching structure of a multi-phase trajectory

Example

julia
using CTFlows: Trajectories

sol = Trajectories.HamiltonianVectorFieldTrajectory(result)
ts = times(sol)           # or Trajectories.time_grid(sol)
x = Trajectories.state(sol)            # callable state function x(t)
p = Trajectories.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, X0} <: 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.

  • x0: The initial state, or Core.NotProvided when built without a config (e.g. raw plumbing/tests). Drives the "1-D = scalar" coercion (issue #357, CTFlows.Systems._coerce_state) applied by sol(t) and Integrators.final_state — a scalar or length-1-vector x0 collapses the returned state to a scalar; anything else, or Core.NotProvided, applies no coercion.

  • labels: The labels of the phases (one per phase, "" for no label), or no label at all (an empty vector), see CTFlows.Trajectories.phase_labels.

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))

  • switching_times(sol), phase_labels(sol), right_limit(sol, :state, i): the switching structure of a multi-phase trajectory

Example

julia
using CTFlows: Trajectories

sol = Trajectories.VectorFieldTrajectory(result)
ts = times(sol)           # or Trajectories.time_grid(sol)
x = Trajectories.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 state point configs — return the final state, coerced to a scalar for a 1-D state.

For scalar or length-1-vector configurations, collapses the final state to a scalar (the "1-D = scalar" convention, issue #357); vectors of length ≥ 2 and matrices are left untouched.

Arguments

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

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

  • config::Configs.AbstractConfig: The state configuration (its initial_state drives the coercion).

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

Returns

  • The final state, isa Real/Complex for a 1-D state, isa AbstractVector/ AbstractMatrix otherwise.

See also: CTFlows.Systems._coerce_state, 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.

  • config::Configs.AbstractConfig: The state configuration (its initial_state drives the "1-D = scalar" coercion applied by the resulting trajectory's accessors, issue #357).

  • 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

Return the control model (on a CTModels.Models.Model) or the control trajectory function (on a CTModels.Solutions.Solution).

See also: CTModels.Models.control_dimension, CTModels.Models.control_components.

costate [Function] ​

CTFlows.Trajectories.costate Function

Return the costate trajectory function from a CTModels.Solutions.Solution.

See also: CTModels.Components.state, CTModels.Solutions.dual.

left_limit [Function] ​

CTFlows.Trajectories.left_limit Function
julia
left_limit(
    sol::CTFlows.Trajectories.VectorFieldTrajectory,
    component::Symbol,
    i::Integer
) -> Any

Return the value of component at the i-th switching time tᵢ, before the jump: the value the trajectory itself returns at tᵢ. Same components as CTFlows.Trajectories.right_limit.

Throws

objective [Function] ​

CTFlows.Trajectories.objective Function

Return the objective model (on a CTModels.Models.Model) or the objective value (on a CTModels.Solutions.Solution).

phase_labels [Function] ​

CTFlows.Trajectories.phase_labels Function
julia
phase_labels(
    sol::Union{CTFlows.Trajectories.HamiltonianVectorFieldTrajectory, CTFlows.Trajectories.VectorFieldTrajectory}
) -> Vector{String}

Return the phase labels of a trajectory, one per phase ("" for a phase with no label); empty when no flow of the trajectory was labelled.

See also: CTFlows.Flows.label, CTFlows.Trajectories.switching_times.

right_limit [Function] ​

CTFlows.Trajectories.right_limit Function
julia
right_limit(
    sol::CTFlows.Trajectories.VectorFieldTrajectory,
    component::Symbol,
    i::Integer
) -> Any

Return the value of component just after the i-th switching time tᵢ, after a jump of the state or costate or a change of control law. The trajectory itself is left-continuous: it returns the value before, see CTFlows.Trajectories.left_limit.

component is :state for a CTFlows.Trajectories.VectorFieldTrajectory; :state or :costate for a CTFlows.Trajectories.HamiltonianVectorFieldTrajectory; :state or :control for a CTFlows.Trajectories.StateFlowTrajectory. A one-dimensional component is a scalar.

Throws

See also: CTFlows.Trajectories.switching_times.

state [Function] ​

CTFlows.Trajectories.state Function

Return the state model (on a CTModels.Models.Model) or the state trajectory function (on a CTModels.Solutions.Solution).

See also: CTModels.Models.state_dimension, CTModels.Models.state_components.

switching_times [Function] ​

CTFlows.Trajectories.switching_times Function
julia
switching_times(
    sol::Union{CTFlows.Trajectories.HamiltonianVectorFieldTrajectory, CTFlows.Trajectories.VectorFieldTrajectory}
) -> Vector{Float64}

Return the switching times of a trajectory: the times between consecutive phases of a multi-phase flow, strictly increasing; empty for a single-phase trajectory.

See also: CTFlows.Trajectories.phase_labels, CTFlows.Trajectories.right_limit.

time_grid [Function] ​

CTFlows.Trajectories.time_grid Function

Return the time grid for a component from a CTModels.Solutions.Solution.

See also: CTModels.Solutions.build_solution.

with_labels [Function] ​

CTFlows.Trajectories.with_labels Function
julia
with_labels(
    sol::CTFlows.Trajectories.VectorFieldTrajectory,
    labels::AbstractVector{<:AbstractString}
) -> CTFlows.Trajectories.VectorFieldTrajectory

Return a copy of a trajectory with the phase labels labels, one per phase (the integration result is shared). Labels that are all empty are dropped, so that an unlabelled trajectory keeps no label.

Throws