TrajectoryIndexingUtils.jl

This is a super lightweight package that exports two functions: index and slice. These functions have helped to ease the burden of handling messy indexing into trajectory data vectors of the form

\[\vec Z = \text{vec}\left(z_1, z_2, \ldots, z_T\right) \in \mathbf{R}^{T \cdot d}\]

where each element $z_t$ is referred to as a knot point and normally contains state variables and control variables. In a simple situation we might have $z_t = \text{vec} (x_t, u_t) \in \mathbf{R}^{d = n+m}$, for the state $x_t \in \mathbf{R}^n$ and control $u_t \in \mathbf{R}^m$. In this case, with dim = n + m, we can use slice and index, to extract what we want from $\vec Z$ in the following way:

extract $z_t$: julia zₜ = Z⃗[slice(t, dim)]
extract $x_t$: julia xₜ = Z⃗[slice(t, 1:n, dim)]
extract $u_t$: julia uₜ = Z⃗[slice(t, (1:m) .+ n, dim)]
extract $i$-th component of $x_t$: julia xₜⁱ = Z⃗[index(t, i, dim)]
extract $j$-th component of $u_t$: julia uₜʲ = Z⃗[index(t, j + n, dim)]

With this, the user is still responsible for keeping track of the component indices for $x$ and $u$, and possibly other variables. To alleviate this nuisance, the package NamedTrajectories.jl provides a richer alternative for handling trajectory data with arbitrarily named components, please check it out!

Installation

TrajectoryIndexingUtils.jl is registered! Install in the REPL by entering pkg mode with ] and then running

pkg> add TrajectoryIndexingUtils

Methods

The `index` function

index(t::Int, dim::Int) -> zₜ[dim]
index(t::Int, pos::Int, dim::Int) -> zₜ[pos]

The `slice` function

slice(t::Int, dim::Int; stretch=0) -> zₜ[1:dim + stretch] # can be used to extract, e.g., [xₜ; xₜ₊₁], with stretch = dim
slice(t::Int, pos::Int, dim::Int) -> zₜ[1:pos]
slice(t::Int, pos1::Int, pos2::Int, dim::Int) -> zₜ[pos1:pos2]
slice(t::Int, indices::AbstractVector{Int}, dim::Int) -> zₜ[indices]
slice(ts::UnitRange{Int}, dim::Int) -> vec(zₜ for t ∈ ts)

Building Documentation

This package uses a Documenter config that is shared with many of our other repositories. To build the docs, you will need to run the docs setup script to clone and pull down the utility.

# first time only
./docs/get_docs_utils.sh   # or ./get_docs_utils.sh if cwd is in ./docs/

To build the docs pages:

julia --project=docs docs/make.jl

or editing the docs live:

julia --project=docs
> using LiveServer, Piccolo, Revise
> servedocs(skip_files=["docs/src/index.md"])

Note: servedocs needs to watch a subset of the files in the docs/ folder. If it watches files that are generated on a docs build/re-build, servedocs will continuously try to re-serve the pages.
To prevent this, ensure all generated files are included in the skip dirs or skip files args for servedocs.

For example, if we forget index.md like so:

julia --project=docs
> using LiveServer, Piccolo, Revise
> servedocs()

it will not build and serve.

"It seems that perfection is attained not when there is nothing more to add, but when there is nothing more to take away." - Antoine de Saint-Exupéry