Module admm_consensus 

Distributed formation consensus via ADMM.

A pure-Rust reproduction slice for the coordination layer of distributed MPC (in the spirit of ACLM-style consensus control): a team of agents agrees on a common formation center z while each agent settles at z + offset_i, trades off staying near its own preferred position, and respects a per-agent box constraint. The agreement is reached by the classic consensus ADMM iteration — each agent solves a tiny local problem, the team averages to a consensus, and scaled dual variables drive the per-agent residuals to zero.

Minimize sum_i (w_i/2) ||x_i - a_i||^2 subject to x_i - offset_i = z and lower_i <= x_i <= upper_i. With equal weights and no box constraints the consensus center has the closed form z* = mean(a_i - offset_i), which the solver recovers; box constraints make it iterative and is where ADMM earns its keep.

• AgentSpec is one agent’s preferred position, formation offset, weight, and box bounds.
• AdmmConfig holds the penalty rho, the iteration cap, and the residual tolerance.
• solve_formation_consensus runs (centralized) consensus ADMM and returns the agent positions, the consensus center, and the primal/dual residuals.
• solve_graph_consensus runs the decentralized edge-based variant where agents agree only with communication-graph neighbors (no global average); the convergence rate is set by the graph connectivity.
• solve_horizon_consensus is the receding-horizon variant: agents agree on a shared center trajectory over a short horizon (rather than a single static center), with a temporal smoothness penalty that couples the center across time and turns the consensus z-update into a banded linear solve.

Structs

AdmmConfig

Consensus-ADMM solver settings.

AdmmReport

Result of a consensus-ADMM solve.

AgentSpec

One agent in the formation-consensus problem.

AgentTrajectory

One agent’s planning slice in the receding-horizon (trajectory) consensus problem: a per-step reference trajectory, a constant formation offset, a cost weight, and an optional box constraint applied at every step.

GraphConsensusReport

Result of a decentralized (graph) consensus-ADMM solve.

HorizonConsensusReport

Result of a receding-horizon (trajectory) consensus-ADMM solve.

Functions

solve_formation_consensus

Solve the formation-consensus problem with consensus ADMM.

solve_graph_consensus

Solve formation consensus decentralized over a communication graph, where each agent exchanges only with its graph neighbors (no global average).

solve_horizon_consensus

Solve the receding-horizon formation-consensus problem: agents agree on a shared center trajectory z[0..H] rather than a single static center.