GitHub

Formations

Sheaf constructions for rigid multi-agent formations: homogeneous affine transforms and the escort-topology primitives used by the layered control architectures.

CellularSheaves.NetworkSheaves.Formations.build_escort_clique — Method
build_escort_clique(n_agents::Int, target_node::Int, radius::Float64; observers=1:n_agents, D::Int=4, affine::Bool=true)

Constructs and returns a EuclideanSheaf for an n_agents escort clique (all-to-all consensus) around target_node — a thin wrapper around build_escort_topology(:clique, ...). See that docstring for the full explanation of the geometry/topology split, D, and affine.

source
CellularSheaves.NetworkSheaves.Formations.build_escort_ring — Method
build_escort_ring(n_agents::Int, target_node::Int, radius::Float64; observers=1:n_agents, D::Int=4, affine::Bool=true)

Constructs and returns a EuclideanSheaf for an n_agents escort ring around target_node — a thin wrapper around build_escort_topology(:ring, ...). See that docstring for the full explanation of the geometry/topology split, D, and affine.

source
CellularSheaves.NetworkSheaves.Formations.build_escort_topology — Method
build_escort_topology(kind::Symbol, n_agents::Int, target_node::Int, radius::Float64;
                      observers=1:n_agents, D::Int=4, affine::Bool=true) -> EuclideanSheaf{Float64}

Constructs and returns a EuclideanSheaf (with stalk dimension D, default 4) for an n_agents escort formation around target_node.

An escort formation bundles two concerns that are mathematically independent, and this function keeps them so:

  • Geometry — where each agent sits. Regardless of kind, agent i is placed at angle 2π(i-1)/n_agents and distance radius in the plane spanned by the first two translation coordinates (this is exactly what build_escort_ring has always done).

  • Consensus topology — which pairs of agents are directly wired together by a sheaf edge. kind selects this graph:

    • :ring — cycle: agent i shares an edge with agent i % n_agents + 1. A 2-agent ring is a degenerate 2-cycle (it produces two parallel edges between the same pair of agents), but the formation is still well-defined and rigid.
    • :path — open chain: agent i shares an edge with i + 1, for i in 1:n_agents-1.
    • :star — hub-and-spoke: agent 1 shares an edge with every agent i in 2:n_agents.
    • :clique — all-to-all: every pair i < j shares an edge.

Every edge constraint has the algebraic form "agent i = centre + d_i" — a shared centre plus a per-agent translation offset — so the constraint system is globally realizable for any connected choice of kind. Consequently, for all four topologies above, the resulting sheaf's space of exact global sections is exactly D-dimensional, parameterized by the formation centre: the formation is rigid no matter which agents happen to be directly wired together. This is the property the hierarchical layered-control architecture depends on (see docs/issues/007-nested-layered-systems-design.md, §3.2).

When affine=true (default), stalks use D-1 homogeneous-affine translation coordinates plus one homogeneous row (e.g. D=4 for SE(3): 3D translation), and restriction maps are affine_translation_matrix offsets — this recovers the original SE(3) escort ring for D=4. When affine=false, stalks are D plain (non-homogeneous) Euclidean coordinates; a purely linear restriction map cannot represent a translation at all, so every restriction map is the identity (a pure consensus topology) and radius must be 0.0.

observers names which agents (local indices 1:n_agents) are pinned to target_node.

source