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 pipeline of five layers:

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, PseudoHamiltonian, PseudoHamiltonianVectorField, ControlledVectorField) and control laws (OpenLoop, ClosedLoop, DynClosedLoop)
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, objective)

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, MultiPhaseHamiltonianFlow, *
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
GPU flows	Running a flow on a device	method=:gpu, CuArray states, the GPU contract

The data layer 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_problem, build_options
using CTFlows: Trajectories # VectorFieldTrajectory, state, time_grid
using CTBase: Traits        # Autonomous, Fixed, InPlace, …
using CTFlows: Configs      # StateEndPointConfig, StateTrajectoryConfig, …
using OrdinaryDiffEqTsit5: OrdinaryDiffEqTsit5 # activates the SciML extension

A first flow

Getting Started builds, integrates and reads a first flow step by step. The shortcut Flows.Flow(data; opts...) runs the whole pipeline in one call; Building a flow shows each step (build_system, the SciML integrator, build_flow) explicitly.

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