Building a flow

A flow is a callable that integrates a system from an initial condition to a final time. Building one involves three steps:

Data  →  build_system  →  build_integrator  →  build_flow  →  Flow

The shortcut constructor Flows.Flow(data; opts...) collapses all three steps into one call. This page explains both paths.

---

Shortcut: Flows.Flow

The simplest way to build a flow is to pass data directly to Flows.Flow:

# From a VectorField → StateFlow
vf   = Data.VectorField(x -> -x)
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)

# From a HamiltonianVectorField → HamiltonianFlow
hvf  = Data.HamiltonianVectorField((x, p) -> (p, -x))
hflow = Flows.Flow(hvf; reltol=1e-10)

Flow
├─ system: HamiltonianVectorFieldSystem
│          └─ wraps: HamiltonianVectorField: autonomous, fixed (no variable), out-of-place
└─ integrator: SciML (reltol = 1.0e-10)

using LinearAlgebra

# From a scalar Hamiltonian (AD computes the derivatives) → HamiltonianFlow
import DifferentiationInterface, ForwardDiff
h    = Data.Hamiltonian((x, p) -> 0.5 * (dot(x, x) + dot(p, p)))
hflow_ad = Flows.Flow(h; reltol=1e-10)

Flow
├─ system: HamiltonianSystem
│          ├─ time_dependence: Autonomous
│          ├─ variable_dependence: Fixed
│          ├─ Hamiltonian: autonomous, fixed (no variable)
│          │    natural call: h(x, p)
│          │    uniform call: h(t, x, p, v)
│          └─ backend: DifferentiationInterface(ad_backend=AutoForwardDiff())
└─ integrator: SciML (reltol = 1.0e-10)

Options passed as keyword arguments are forwarded to the integrator strategy; see Integrating for the full list.

---

Explicit pipeline

The explicit form gives full control over each step.

Step 1 — Build the system

build_system wraps data into an AbstractSystem that exposes the ODE right-hand side:

# VectorField → VectorFieldSystem
sys = Systems.build_system(vf)

VectorFieldSystem
├─ wraps: VectorField: autonomous, fixed (no variable), out-of-place
└─ rhs: IPVFOoPRHS (out-of-place VF → in-place interface)

# HamiltonianVectorField → HamiltonianVectorFieldSystem
hsys = Systems.build_system(hvf)

HamiltonianVectorFieldSystem
└─ wraps: HamiltonianVectorField: autonomous, fixed (no variable), out-of-place

A system exposes:

• Systems.get_ip_rhs(sys, config) — the in-place ODE right-hand side (du, u, p, t) -> nothing

• Systems.get_oop_rhs(sys, config) — the out-of-place variant (u, p, t) -> du

• Traits.time_dependence(sys), Traits.variable_dependence(sys) — delegated from the data

Step 2 — Build the integrator

integ = Integrators.build_integrator(; reltol=1e-8, abstol=1e-8)

SciML (instance, id=:sciml)
├─ internalnorm = real_norm  [default]
├─ alg = Tsit5{typeof(OrdinaryDiffEqCore.trivial_limiter!), typeof(OrdinaryDiffEqCore.trivial_limiter!), FastBroadcast.Serial}(OrdinaryDiffEqCore.trivial_limiter!, OrdinaryDiffEqCore.trivial_limiter!, FastBroadcast.Serial())  [default]
├─ reltol = 1.0e-8  [user]
├─ save_everystep = auto  [default]
├─ abstol = 1.0e-8  [user]
├─ save_start = auto  [default]
└─ dense = auto  [default]
Tip: use describe(SciML) to see all available options.

The default integrator is SciML (backed by OrdinaryDiffEqTsit5 when loaded). See Integrating for how to choose a different algorithm.

Step 3 — Combine into a flow

flow_explicit = Flows.build_flow(sys, integ)

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)

This produces the same StateFlow as the shortcut:

typeof(flow_explicit) == typeof(flow)

true

---

Flow types

Input data	Flow type
VectorField	StateFlow
HamiltonianVectorField	HamiltonianFlow
Hamiltonian (with AD)	HamiltonianFlow
PseudoHamiltonian + DynClosedLoop law	HamiltonianFlow
ControlledVectorField + OpenLoop/ClosedLoop law	ControlledFlow
OCP (control-free)	OptimalControlFlow
OCP (with control) + DynClosedLoop law	OptimalControlFlow
OCP (with control) + OpenLoop/ClosedLoop law	ControlledFlow
OCP (with control) + u::Function	OptimalControlFlow (auto DynClosedLoop)

Both StateFlow and HamiltonianFlow are concrete subtypes of AbstractFlow. ControlledFlow is a state-flow wrapper carrying a control law (see Control laws). OptimalControlFlow wraps a HamiltonianFlow with the OCP reference (see Optimal control). Their trait parameters mirror the underlying data:

Traits.time_dependence(flow)      # Autonomous (inherited from vf)
Traits.variable_dependence(flow)  # Fixed

CTBase.Traits.Fixed

AbstractSystem contract

Any concrete system must implement:

• get_ip_rhs(system, config) — returns the in-place ODE function (du, u, p, t) -> nothing

• get_oop_rhs(system, config) — returns the out-of-place ODE function (u, p, t) -> du

Hamiltonian systems supporting variable-costate integration additionally implement get_ip_rhs_augmented(system, config). Eager systems (e.g. VectorFieldSystem) ignore config and return pre-computed closures; lazy systems (e.g. HamiltonianSystem) read the initial conditions from config to build type-specific closures.

Traits are propagated automatically from the data layer:

• Traits.time_dependence(system)

• Traits.variable_dependence(system)

AbstractFlow contract

Any concrete flow must implement:

• system(flow) — the associated AbstractSystem

• integrator(flow) — the associated AbstractIntegrator

Flows.system(flow)      # the VectorFieldSystem wrapped by this StateFlow

VectorFieldSystem
├─ wraps: VectorField: autonomous, fixed (no variable), out-of-place
└─ rhs: IPVFOoPRHS (out-of-place VF → in-place interface)

Flows.integrator(flow)  # the SciML integrator strategy

SciML (instance, id=:sciml)
├─ internalnorm = real_norm  [default]
├─ alg = Tsit5{typeof(OrdinaryDiffEqCore.trivial_limiter!), typeof(OrdinaryDiffEqCore.trivial_limiter!), FastBroadcast.Serial}(OrdinaryDiffEqCore.trivial_limiter!, OrdinaryDiffEqCore.trivial_limiter!, FastBroadcast.Serial())  [default]
├─ reltol = 1.0e-8  [user]
├─ save_everystep = auto  [default]
├─ abstol = 1.0e-8  [user]
├─ save_start = auto  [default]
└─ dense = auto  [default]
Tip: use describe(SciML) to see all available options.

Calling a flow delegates through _invoke_flow which builds the ODE problem, solves it, and wraps the result — see Integrating.

---

Flow getters

Every flow answers a small, uniform set of getters. Which ones are meaningful depends on how the flow was built; calling an inapplicable getter raises a clear IncorrectArgument.

Getter	Available on	Returns
system(f) / integrator(f)	all flows	the wrapped AbstractSystem / AbstractIntegrator
vector_field(f)	all flows	the integrated vector field (for a Hamiltonian flow, — an alias of hamiltonian_vector_field)
hamiltonian_vector_field(f)	Hamiltonian flows
hamiltonian(f)	Hamiltonian flows	the scalar
hamiltonian_gradient(f) / variable_gradient(f)	Hamiltonian flows	functors /
pseudo_hamiltonian(f) / control_law(f)	flows built with a control law	/ the feedback
pseudo_hamiltonian_gradient(f) / pseudo_variable_gradient(f)	flows built with a control law	functors of

The Hamiltonian getters are shown executed on Integrating, the pseudo-Hamiltonian ones on Control laws. This page covers the vector-field getters.

Vector field

Systems.vector_field(f) is the uniform entry point across flow kinds — for a HamiltonianFlow it returns the (symplectic) Hamiltonian vector field   , an alias of hamiltonian_vector_field(f); for a state Flow it returns the underlying AbstractVectorField integrated by the flow:

# State flow → the underlying VectorField
Flows.vector_field(flow)

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

# HamiltonianVectorField-backed flow → X_H (vector_field is an alias)
hvf_back = Flows.hamiltonian_vector_field(hflow)
Flows.vector_field(hflow) === hvf_back

true

For an AD-backed flow (built from Hamiltonian), the getter materialises the vector field on demand:

hvf_ad = Flows.hamiltonian_vector_field(hflow_ad)

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

hamiltonian_vector_field (and therefore vector_field) also covers flows built from a pseudo-Hamiltonian or an OCP together with a control law — the Hamiltonian is then a CTBase.Data.ComposedHamiltonian (:total mode) or reconstructed from a PseudoHamiltonianSystem (:partial mode); see Control laws.

---

See also

• CTFlows.Flows.Flow, CTFlows.Flows.StateFlow, CTFlows.Flows.HamiltonianFlow — concrete flow types.

• CTFlows.Flows.build_flow, CTFlows.Systems.build_system, CTSolvers.Integrators.build_integrator — pipeline builders.

• CTFlows.Flows.AbstractFlow, CTFlows.Flows.AbstractStateFlow, CTFlows.Flows.AbstractHamiltonianFlow — abstract supertypes.

• CTFlows.Flows.system, CTFlows.Flows.integrator — flow accessors.

• CTFlows.Systems.AbstractSystem, CTFlows.Systems.get_ip_rhs, CTFlows.Systems.get_oop_rhs — system contract.

• CTFlows.Systems.vector_field, CTFlows.Flows.hamiltonian_vector_field — vector field getters (state and Hamiltonian flows).