CTFlows.jl

CTFlows.jl is the flow integration layer of the control-toolbox ecosystem. Given a dynamical system (a vector field, a Hamiltonian, a Hamiltonian vector field, or an optimal control problem), it builds a callable flow that integrates the system from any initial condition to any final time, with a pluggable ODE solver and automatic differentiation where derivatives are needed.

Who this documentation is for

This documentation is for advanced users who build flows from the data layer, write shooting methods or need control over the integration, and for developers of CTFlows and of the packages that build on it. To solve optimal control problems, start with the OptimalControl.jl documentation, which re-exports the flows described here.

CTFlows in the ecosystem

CTFlows handles integration. Modelling optimal control problems is CTModels.jl; the data layer, traits and AD primitives are CTBase.jl; the ODE integrator strategy is CTSolvers.jl; differential-geometric tools (Lie and Poisson brackets, lifts) are CTLie.jl.

Quick start

using CTFlows
using CTBase: Data
using CTFlows: Flows
using CTFlows: Trajectories
using OrdinaryDiffEqTsit5: OrdinaryDiffEqTsit5   # activates the SciML integrator

vf = Data.VectorField(x -> -x)            # ẋ = -x: autonomous, no variable
flow = Flows.Flow(vf; reltol=1e-8)

xf = flow(0.0, [1.0, 0.0], 1.0)           # point call: the state at tf
sol = flow((0.0, 1.0), [1.0, 0.0])        # trajectory call
x = Trajectories.state(sol)               # callable: x(t)
xf, x(0.5)

([0.36787944127643135, 0.0], [0.6065306592843307, 0.0])

Qualified access

CTFlows exports nothing at the package level. Every symbol lives in a submodule (CTBase.Data, CTFlows.Flows, …) and is reached through a qualified path, after using CTFlows: Submodule.

The same constructor builds a flow directly from an optimal control problem, a CTModels.Models.Model, with no Hamiltonian to write by hand: Flows.Flow(ocp) for a control-free problem, Flows.Flow(ocp, law) with a control law. See Optimal control and Control laws.

Architecture

CTFlows is a pipeline:

Data → Systems → Integrators → Flows → Trajectories

Layer	Submodule	Key types and functions
Data	CTBase.Data	VectorField, Hamiltonian, HamiltonianVectorField, PseudoHamiltonian, PseudoHamiltonianVectorField, ControlledVectorField, OpenLoop, ClosedLoop, DynClosedLoop
Configs	CTFlows.Configs	StateEndPointConfig, StateTrajectoryConfig, HamiltonianEndPointConfig, HamiltonianTrajectoryConfig, AugmentedHamiltonianEndPointConfig; output grids UniformGrid, AdaptiveGrid
Systems	CTFlows.Systems	VectorFieldSystem, HamiltonianVectorFieldSystem, HamiltonianSystem, PseudoHamiltonianSystem, PseudoHamiltonianVectorFieldSystem, ConstrainedPseudoHamiltonianSystem; accessors hamiltonian, control_law, …
Integrators	CTFlows.Integrators	SciML (from CTSolvers), build_problem, build_options
Flows	CTFlows.Flows	Flow, StateFlow, HamiltonianFlow, OptimalControlFlow, ControlledFlow
Trajectories	CTFlows.Trajectories	VectorFieldTrajectory, HamiltonianVectorFieldTrajectory, StateFlowTrajectory
Multi-phase	CTFlows.MultiPhase	MultiPhaseStateFlow, MultiPhaseHamiltonianFlow, the * operator
Plotting	CTFlows.TrajectoryPlots	build_figure, rendered by the Plots or Makie extension

The data layer lives in CTBase.Data; the ODE integrator strategy is provided by CTSolvers.Integrators and re-exported through CTFlows.Integrators.

The shortcut Flows.Flow(data; opts...) runs all the steps in one call. The explicit pipeline (build_system, SciML, build_flow) gives control over each one.

Reading paths

Advanced users, writing flows and shooting methods:

1. Getting Started: installation and a first flow.

2. Building a flow and Integrating: the constructors, the call styles, output grids, variables, integrator options.

3. Trajectories and Multi-phase flows: reading and plotting results, concatenating flows with switching times and jumps.

4. Optimal control, Control laws, Constrained flows: flows from an optimal control problem.

5. Compatibility: which state types and call styles each constructor accepts.

Developers, extending CTFlows or building on it:

1. Flows overview: the layers and their mathematical setting.

2. Extending CTFlows: the contracts a new system, flow or integrator implements.

3. GPU flows and GPU internals: device support, how it is routed, how it is tested.

4. SciML flows: the SciML extension.

5. The API reference, one page per submodule, and the internals.