API

merge(traj1::NamedTrajectory, traj2::NamedTrajectory)
merge(trajs::AbstractVector{<:NamedTrajectory})

Returns a new NamedTrajectory object by merging NamedTrajectory objects.

Merge names are used to specify which components to merge by index. If no merge names are provided, all components are merged and name collisions are not allowed. If merge names are provided, the names are merged using the data from the index provided in the merge names.

Keyword Arguments

• timestep::Symbol: The timestep symbol to use for free time problems. Default to the last trajectory.
• merge_names::Union{Nothing, NamedTuple{<:Any, <:Tuple{Vararg{Int}}}}=nothing: The names to merge by index.

add_component(traj, name::Symbol, data::AbstractVecOrMat)

Add a component to the trajectory.

Keyword arguments: - type::Symbol: The type of the component, can be :state, :control, :slack, or :global. Default is :state.

add_components(traj, comps)

Add components to the trajectory.

Keyword arguments: - type::Symbol: The type of the component, can be :state, :control, :slack, or :global. Default is :state.

add_control_derivatives(
    traj::NamedTrajectory,
    n_derivatives::Int;
    control_name::Symbol=:u,
    derivative_bounds::Union{Nothing, Tuple{Vararg{VectorBound}}}=nothing,
    zero_initial_and_final_derivative::Bool=false,
    random_init::Bool=false,
    drive_derivative_σ::Float64=0.1
)

Add control derivatives to an existing trajectory.

Takes an existing NamedTrajectory with a control variable and adds its time derivatives (e.g., u̇, ü) as new trajectory components. Can either compute derivatives using finite differences or initialize them randomly.

Arguments

• traj::NamedTrajectory: Existing trajectory with control variable
• n_derivatives::Int: Number of derivatives to add (1 for u̇, 2 for u̇ and ü, etc.)

Keyword Arguments

• control_name::Symbol=:u: Name of the control variable in the trajectory
• derivative_bounds::Union{Nothing, Tuple{Vararg{VectorBound}}}=nothing: Bounds for each derivative level (du, ddu, ...)
• zero_initial_and_final_derivative::Bool=false: Enforce zero first derivative at boundaries
• random_init::Bool=false: If true, randomly initialize derivatives instead of computing via finite differences
• drive_derivative_σ::Float64=0.1: Standard deviation for random derivative initialization (only used if random_init=true)

Returns

• NamedTrajectory: New trajectory with control derivatives added

Examples

# Add first and second derivatives computed via finite differences
traj_smooth = add_control_derivatives(
    traj, 
    2; 
    derivative_bounds=(([-2.0, -2.0], [2.0, 2.0]), ([-5.0, -5.0], [5.0, 5.0]))
)

# Add derivative with zero boundary conditions
traj_smooth = add_control_derivatives(
    traj,
    1;
    zero_initial_and_final_derivative=true
)

# Randomly initialize derivatives
traj_random = add_control_derivatives(
    traj,
    2;
    random_init=true,
    drive_derivative_σ=0.05
)

Notes

• The original trajectory is not modified; a new trajectory is returned
• When random_init=false, derivatives are computed using finite differences: du/dt ≈ Δu/Δt
• When random_init=true, derivatives are sampled from N(0, drivederivativeσ²)
• The penultimate point of each derivative is adjusted to ensure smooth transitions (finite difference mode only)
• New derivative components become part of the trajectory controls

add_suffix(obj::T, suffix::String)

Add the suffix to the symbols of the object.

get_component_names(traj::NamedTrajectory, comps::AbstractVector{<:Int})

Returns the name of the component with the given indices. If only one component is found, the name is returned as a single symbol. Else, the names are returned as a vector of symbols.

The filter requires that the components are a complete subset of the given indices, so that a partial match is excluded from the returned names.

get_components(names, ::NamedTrajectory)

Returns a NamedTuple containing the names and corresponding data matrices of the trajectory.

get_duration(::NamedTrajectory)

Returns the duration of a trajectory.

get_suffix(obj::T, suffix::String; remove::Bool=false)

Get the data with the suffix from the object. Remove the suffix if remove=true.

get_times(traj)::Vector{Float64}

Returns the times of a trajectory as a vector.

get_timesteps(::NamedTrajectory)

Returns the timesteps of a trajectory as a vector.

merge_outer(objs::AbstractVector{<:Any})

Merge objects. An error is reported if a key collision is detected.

remove_component(traj, name::Symbol)

Remove a component from the trajectory.

remove_components(traj, names::Vector{Symbol})

Remove a set of components from the trajectory.

remove_suffix(obj::T, suffix::String)

Remove the suffix from the symbols of the object.

update!(traj, datavec::AbstractVector{Float64})

Update the trajectory with a new datavec.

Keyword arguments: - type::Symbol: The type of the datavec, can be :data, :global, or :both. Default is global.

update!(traj, name::Symbol, data::AbstractMatrix{Float64})

Update a component of the trajectory.

update_bound!(traj, name, new_bound)

Update the bound of a component of the trajectory.

getproperty(slice::KnotPoint, symb::Symbol)

Returns the component of the knot point with name symb (as a view) or the property of the knot point with name symb.

setproperty!(slice::KnotPoint, symb::Symbol, val::Any)

Dispatches setting properties of knot points as either setting a component or a property via update! or setfield!, respectively.

update!(slice::KnotPoint, symb::Symbol, data::AbstractVector{Float64})

Update a component of the knot point.

rand(
    ::Type{NamedTrajectory},
    N::Int;
    timestep_value::Float64=1.0,
    timestep_name::Symbol=:Δt,
    timestep::Union{Float64,Symbol}=free_time ? timestep_name : timestep_value,
    state_dim::Int=3,
    control_dim::Int=2
)

Create a random NamedTrajectory with N knot points, a state variable x of dimension state_dim, and a control variable u of dimension control_dim. The time step is a symbol timestep_name and the time step value is timestep_value.

NamedTrajectory{R <: Real}

Container for trajectory optimization problems, which includes the trajectory data, bounds dimensions, initial and final conditions, goal states, and components.

This struct is designed to hold trajectory data in a named format, allowing for easy access to knot points by Symbol.

NamedTrajectory is designed to make allocation-free access easy to write. The data can be updated after construction, but the fields cannot.

NamedTrajectory(component_data, global_components_data)

Construct a NamedTrajectory from component data and global component data

NamedTrajectory(component_data)

Construct a NamedTrajectory from component data.

NamedTrajectory(component_data::NamedTuple, timestep; kwargs...)

Construct a NamedTrajectory from mixed Matrix/Vector component data.

NamedTrajectory(data, traj)

Construct a NamedTrajectory from an existing NamedTrajectory.

NamedTrajectory(data, components; kwargs...)

Construct a NamedTrajectory from a data matrix and components.

NamedTrajectory(datavec, components, N)

Construct a named trajectory from a data vector, components, and knot points.

get_bounds_from_dims(bounds, dims; dtype=Float64)

Process bounds from allowed types using dims and convert to dtype.

inspect_dims_pairs(dims_pairs, bounds, initial, final, goal)

Check for proper formatting of trajectory components.

inspect_names(names, controls, initial, final, goal, bounds)

Check for missing names in the trajectory components.

KnotPoint constructor

derivative(X::AbstractMatrix, Δt::AbstractVecOrMat)
derivative(X::AbstractMatrix, Δt::Float64)

Compute the derivative of the data matrix X.

integral(X::AbstractMatrix, Δt::AbstractVector)
integral(X::AbstractMatrix, Δt::Float64)

Compute the integral of the data matrix X.

trajectory_interpolation(
    traj::NamedTrajectory,
    times::AbstractVector;
    interpolations::NamedTuple=NamedTuple(zip(traj.names, fill(:linear, length(traj.names))))
)

Interpolate a NamedTrajectory at specified time points.

Arguments

• traj::NamedTrajectory: The trajectory to interpolate.
• times::AbstractVector: The time points at which to interpolate the trajectory.

Keyword Arguments

• interpolations::NamedTuple: A named tuple specifying the interpolation method for each component. Supported methods are :constant, :linear, and :spline. Defaults to :linear for all components.

Returns

• NamedTrajectory: A new trajectory with interpolated values at the specified times.

Notes

• Components not specified in interpolations will be dropped from the returned trajectory.
• The timestep component is automatically included with linear interpolation if not specified.
• Spline interpolation requires derivative components (e.g., du for component u).

Examples

# Linear interpolation at new time points
new_times = [0.0, 0.5, 1.0, 1.5, 2.0]
new_traj = trajectory_interpolation(traj, new_times)

# Mix of interpolation methods
interpolations = (x = :linear, u = :spline, Δt = :linear)
new_traj = trajectory_interpolation(traj, new_times; interpolations=interpolations)

trajectory_interpolation(
    traj::NamedTrajectory,
    T::Int;
    kwargs...
)

Interpolate a NamedTrajectory to a new number of time steps.

Arguments

• traj::NamedTrajectory: The trajectory to interpolate.
• T::Int: The number of time steps in the interpolated trajectory.

Keyword Arguments

• kwargs...: Additional keyword arguments passed to the main trajectory_interpolation method.

Returns

• NamedTrajectory: A new trajectory with T time steps, evenly spaced between the original start and end times.

Examples

# Interpolate to 100 time steps
new_traj = trajectory_interpolation(traj, 100)

# With custom interpolation methods
new_traj = trajectory_interpolation(traj, 100; interpolations=(x=:spline, u=:linear))