Flows

The CTFlows.Flows submodule is the central abstraction of CTFlows. A flow is a callable object that integrates a dynamical system over a time interval: you hand it an initial condition and a final time, and it returns the result.

CTFlows builds flows through a four-layer pipeline:

Data → Systems → Integrators → Flows → Trajectories

Each layer has a single responsibility. The arrows show the build order, not a data dependency: Systems and Integrators are constructed independently — one from Data, the other from integrator options — and only meet when build_flow(system, integrator) combines them into a Flow (see Building a flow):

Layer	Submodule	What it produces
Data	CTBase.Data	Typed function wrappers (VectorField, Hamiltonian, HamiltonianVectorField)
Systems	Systems	ODE right-hand side + traits (VectorFieldSystem, HamiltonianSystem, …)
Integrators	Integrators	ODE solver strategy (SciML)
Flows	Flows	Callable integration object (StateFlow, HamiltonianFlow, OptimalControlFlow, ControlledFlow)
Trajectories	Trajectories	Result container with semantic accessors (state, costate, control, time_grid)

Reading order

Page	Topic	Key types
Building a flow	Assembling the pipeline	build_system, build_flow, Flow
Integrating	Calling a flow, configuration objects, integrator options	StateEndPointConfig, StateTrajectoryConfig
Trajectories	Reading the result	state, costate, time_grid, plot
Multi-phase flows	Concatenating flows with switching times	MultiPhaseStateFlow, *
Optimal control	Flows from optimal control problems	OptimalControlFlow, Flow(ocp)
Control laws	Flows with control laws	ControlledFlow, Flow(ocp, law), OpenLoop, ClosedLoop, DynClosedLoop
Constrained flows	Path-constraint terms on Flow(ocp, law)	constraint, multiplier, hamiltonian_type
SciML flows	Flows from SciML functions and problems	Flow(::ODEFunction), Flow(::ODEProblem), SciMLProblemFlow

The data layer (wrapping functions as VectorField, Hamiltonian, HamiltonianVectorField) and the trait system (Autonomous, Fixed, InPlace, …) live in CTBase — see CTBase.Data and CTBase.Traits in the CTBase documentation. Likewise, the ODE solver strategy (SciML) is not implemented in CTFlows: it is provided by CTSolvers.Integrators and re-exported through CTFlows.Integrators — see SciML integrator internals for the split between the two packages.

Qualified access

CTFlows exports nothing at the package level. Bring submodules into scope explicitly:

using CTFlows
using CTFlows.Flows        # StateFlow, HamiltonianFlow, Flow, build_flow
using CTBase.Data          # VectorField, Hamiltonian, HamiltonianVectorField
using CTFlows.Systems      # build_system
using CTFlows.Integrators  # SciML, build_integrator
using CTFlows.Trajectories # VectorFieldTrajectory, state, time_grid
using CTBase.Traits        # Autonomous, NonAutonomous, Fixed, NonFixed, InPlace, OutOfPlace
using CTFlows.Configs      # StateEndPointConfig, StateTrajectoryConfig, …
import OrdinaryDiffEqTsit5 # activates the SciML extension

Minimal end-to-end example

The fastest path from a function to an integrated trajectory:

# 1. Wrap the dynamics as a VectorField
#    The function x -> -x is autonomous (no t) and fixed (no variable parameter)
vf = Data.VectorField(x -> -x)

VectorField: autonomous, fixed (no variable), out-of-place
  natural call: f(x)
  uniform call: f(t, x, v)

# 2. Build the flow directly from the data (shortcut constructor)
flow = Flows.Flow(vf; reltol=1e-8, abstol=1e-8)

Flow
├─ system: VectorFieldSystem
│          ├─ wraps: VectorField: autonomous, fixed (no variable), out-of-place
│          └─ rhs: IPVFOoPRHS (out-of-place VF → in-place interface)
└─ integrator: SciML (abstol = 1.0e-8, reltol = 1.0e-8)

# 3a. Point integration: final state only
xf = flow(0.0, [1.0, 0.0], 1.0)

2-element Vector{Float64}:
 0.36787944127643124
 0.0

# 3b. Trajectory integration: full time history
sol = flow((0.0, 1.0), [1.0, 0.0])

VectorFieldTrajectory
├─ result: SciMLIntegrationResult
├─ tspan: (0.0, 1.0)
├─ time points: 16
└─ final state: [0.36787944127643124, 0.0]

# 4. Read the result
ts = Trajectories.time_grid(sol)   # vector of time points
x  = Trajectories.state(sol)       # callable: x(t) → state at time t
x(0.5)                          # interpolate at t = 0.5

2-element Vector{Float64}:
 0.6065306592843308
 0.0

The shortcut Flows.Flow(vf; opts...) hides steps 2–3 of the pipeline (build_system → build_integrator → build_flow). See Building a flow for the explicit form.

Mathematical setting

We work on a state space  .

• A vector field is a map    (or with time and/or variable arguments).

• A Hamiltonian is a scalar map   ,   defined on the cotangent bundle.

• A Hamiltonian vector field is the map    ,   .

Which extra arguments appear (, ) is encoded by the trait system — see CTBase.Traits.

An optimal control problem adds a control  , dynamics  , and a Mayer/Lagrange cost to minimise (or maximise). Its pseudo-Hamiltonian       (  ,    for :min/:max) still carries the control explicitly. Two routes turn it into a genuine Hamiltonian that a flow can integrate:

• Control-free: no control at all — reduces directly to . This is Flow(ocp) — see Optimal control.

• With a control law: a feedback (or ) closes the loop,  . This is Flow(ocp, law) / Flow(h̃, law) — see Control laws.

See also

• Building a flow — the shortcut and explicit pipeline, plus the flow getters.

• Integrating — call styles, variable parameters, and integrator options.

• Trajectories — the result containers, their accessors, and plotting.

• Optimal control, Control laws — flows from an OCP, with or without a control law.

• CTBase.Data, CTBase.Traits — the data and trait layers (in CTBase).

• CTSolvers.Integrators — the ODE integrator strategy (in CTSolvers).