CTLie

CTLie is a foundational package of the control-toolbox ecosystem. It provides the differential-geometric operators used in geometric optimal control: the Hamiltonian lift, the Lie derivative and Lie bracket of vector fields, the Poisson bracket of Hamiltonians, and the partial time derivative. All of these are also available through a single convenience macro, @Lie.

This documentation is aimed at developers and advanced users. End users of optimal control usually reach these operators through OptimalControl.jl, whose documentation covers their use in solving problems. Here, each operator is presented with its mathematical definition, then with runnable examples — both on plain Julia Functions and on the typed objects of CTBase (VectorField, Hamiltonian) — across the trait combinations (autonomous or not, fixed or variable).

Exported operators

Unlike most control-toolbox packages, CTLie exports its user-facing API — Lift, ad, Poisson, ∂ₜ, @Lie, dg_ad_backend and dg_ad_backend! — so that geometric expressions read like the mathematics. Everything else, including the typed objects from CTBase, is accessed by qualified path (Data.VectorField, CTLie.LiftedHamiltonianFunction, …).

DeepWiki offers an interactive, AI-generated overview of this codebase. Answers may be inaccurate — use this documentation as the source of truth.

Quick start

The differential operators need an automatic-differentiation backend: load DifferentiationInterface (which activates CTBase's AD extension) and ForwardDiff (the default AD engine) next to CTLie. Without ForwardDiff, the first derivative evaluation raises a CTBase.Exceptions.ExtensionError; see Limitations & configuration to select another backend.

using CTLie
using CTBase: Data
using DifferentiationInterface: DifferentiationInterface
using ForwardDiff: ForwardDiff

Two vector fields, their Lie bracket, and the Poisson bracket of their Hamiltonian lifts:

X = Data.VectorField(x -> [x[2], 2x[1]]; is_autonomous=true)
Y = Data.VectorField(x -> [3x[2], -x[1]]; is_autonomous=true)
x0, p0 = [1.0, 2.0], [0.5, 1.0]

Z = @Lie [X, Y]                  # Lie bracket, a VectorField
Z(x0)

2-element Vector{Float64}:
   7.0
 -14.0

H = @Lie {Lift(X), Lift(Y)}      # Poisson bracket of the lifts
H(x0, p0) ≈ Lift(Z)(x0, p0)      # {H_X, H_Y} = H_[X,Y]

true

Reading order

Page	Operator	Mathematical object
Hamiltonian lift	Lift
Lie derivative & bracket	ad	and
Poisson bracket	Poisson
Partial time derivative	∂ₜ
The @Lie macro	@Lie	and
Limitations & configuration	—	constraints, AD backend

Mathematical setting

We work on a state space   and its cotangent bundle with canonical coordinates   .

• A vector field is a map   .

• A Hamiltonian is a scalar map   ,  .

The operators may additionally depend on time and on a variable parameter (a decision variable, e.g. a free final time or a design parameter). Which of these extra arguments appear is encoded by two CTBase traits, TimeDependence and VariableDependence, set with the keywords is_autonomous and is_variable. They fix the call signatures:

is_autonomous	is_variable	Vector field	Hamiltonian
true (default)	false (default)	X(x)	H(x, p)
false	false	X(t, x)	H(t, x, p)
true	true	X(x, v)	H(x, p, v)
false	true	X(t, x, v)	H(t, x, p, v)

A one-dimensional state, costate or variable is a scalar (Number), not a length-1 vector.

Notation summary

Mathematics	Julia
Hamiltonian lift	Lift(X)
Lie derivative	ad(X, f)
Lie bracket	ad(X, Y), @Lie [X, Y]
Poisson bracket	Poisson(H, G), @Lie {H, G}
Partial time derivative	∂ₜ(·)