Multi-Agent Tracking

MultiAgentTracking

Utilities for multi-agent, multi-target coordination via time-expanded cellular sheaves.

Exports types for problem specification (TrackingEdge, TrackingProblem, BobbingTarget, ScenarioResult) and functions to build the sheaf, generate reference trajectories, solve, and extract results.

BobbingTarget

Parameters of a vertically oscillating ("bobbing") target.

Fields:

• y_fixed: fixed lateral position (m).
• z_center: mean altitude (m).
• z_amplitude: oscillation amplitude (m).
• omega: angular frequency (rad/s).

Call trajectory(bt, t_range, h, nx, nu) to materialise the stalk sequence over any integer time interval.

ScenarioResult

Bundle of trajectory data and statistics for one solved scenario.

Fields:

• label: scenario name.
• times: discrete time vector (length k+1).
• agent_trajs: Vector of (k+1) × nx state matrices, one per agent.
• target_trajs: Vector of stalk-vector sequences, one per target.
• null_dim: nullspace dimension of the restricted Laplacian.
• residual: Laplacian energy sqrt(z' * L * z).
• y_col, z_col: which columns of the state matrix correspond to the y and z coordinates used for plotting.

TrackingEdge

One agent–target tracking relationship with its own restriction maps.

Fields:

• agent_index: index of the agent in 1:n_agents.
• target_index: index of the target in 1:n_targets.
• agent_restriction: matrix applied to the agent stalk.
• target_restriction: matrix applied to the target stalk.

Using a vector of TrackingEdges (rather than a single assignment vector) allows many-to-many relationships where each pairing can use different projection matrices.

TrackingProblem

All parameters of a multi-agent, multi-target tracking problem encoded as a time-expanded cellular sheaf.

Fields:

• n_agents, n_targets: fleet sizes.
• k: horizon length; the trajectory has k+1 timesteps t = 0, …, k.
• Ad, Bd: ZOH-discretised state-space matrices (size nx × nx, nx × nu).
• agent_edges: undirected agent–agent consensus pairs (i, j).
• tracking_edges: many-to-many agent–target edges (see TrackingEdge).
• consensus_restriction: projection used for all agent–agent consensus edges.
• consensus_timesteps: timesteps at which consensus edges are added.
• tracking_timesteps: timesteps at which tracking edges are added.
• include_target_dynamics: add temporal dynamics edges between target vertices.
• consensus_weight, tracking_weight: Laplacian weights (the restriction maps are pre-scaled by their square roots).

agent_vertex(prob, i, t)

Index of agent i at timestep t in the sheaf built from prob.

build_time_expanded_tracking_sheaf(prob::TrackingProblem)

Construct the time-expanded EuclideanSheaf from a TrackingProblem.

Four edge families are added in order:

1. Agent dynamics — agent(i,t) ↔ agent(i,t+1) for every agent i and step t = 0, …, k-1, encoding x_{t+1} = Ad * x_t + Bd * u_t.
2. Target dynamics (when include_target_dynamics) — same structure for each target vertex.
3. Consensus — agent(i,t) ↔ agent(j,t) for each (i,j) in agent_edges, active at each t in consensus_timesteps.
4. Tracking — for each TrackingEdge(i, j, Ra, Rt), adds agent(i,t) ↔ target(j,t) active at each t in tracking_timesteps, using restriction maps Ra (agent side) and Rt (target side).

Restriction maps for consensus and tracking edges are pre-scaled by sqrt(consensus_weight) and sqrt(tracking_weight) respectively so that the resulting Laplacian is weight * R' * R.

extract_state_trajectories(z_harmonic, prob)

Return one (k+1) × nx matrix per agent, pre-allocated and filled directly from the harmonic-extension output (no intermediate concatenations).

generate_reference_trajectory(x0, xk, k, Ad, Bd, nx, nu)

Compute the minimum-energy trajectory from x0 to xk in k steps by harmonic extension on a single-agent dynamics sheaf.

Each stalk has dimension nx + nu. Interior control components are in general nonzero—they are the minimum-energy inputs satisfying the linear dynamics. This function is designed to produce fully-pinned target boundary data; the control components of the returned stalks do not affect the multi-agent solution once the targets are pinned as boundary vertices.

run_scenario(label, prob, boundary, times; target_trajs, y_col, z_col)

Build the sheaf from prob, run harmonic_extension, compute the Laplacian energy sqrt(z' * L * z), and return a ScenarioResult.

sheaf_laplacian_matrix_direct is used for the energy (rather than coboundary_map) because the coboundary matrix only spans vertices appearing in at least one edge; isolated target vertices (when include_target_dynamics = false) would cause a dimension mismatch.

y_col and z_col are the column indices of the y and z coordinates in the state vector; they are stored in the result for plotting. Defaults are 1 and 2, matching the planar-quadrotor model convention.

selector_matrix(indices, n)

Return the length(indices) × n row-selection matrix S such that S * v == v[indices]. Throws ArgumentError if any index is outside 1:n.

state_projection_matrix(state_indices, nx, nu)

Return a length(state_indices) × (nx + nu) matrix that selects the given state coordinates from an augmented (nx + nu)-stalk.

target_vertex(prob, j, t)

Index of target j at timestep t in the sheaf built from prob.

trajectory(bt::BobbingTarget, t_range, h, nx, nu, y_idx, z_idx, zdot_idx)

Return a Vector of length length(t_range) stalk vectors for bt.

Each stalk has dimension nx + nu. The lateral state component at y_idx is set to bt.y_fixed; the altitude component at z_idx follows a sinusoid centred at bt.z_center with amplitude bt.z_amplitude and angular frequency bt.omega; the altitude-rate component at zdot_idx is set to the analytic derivative. All other components are zero.

t_range may be any integer range, enabling evaluation over an arbitrary sub-interval without recomputing from scratch.