Maneuver.Map

Maneuver.Map turns a research question into a grid of runs, executes them, records what produced them, and shows you the result. It sits above Leviathan and Gossamer: it steps the engine, calls into the coordination primitive for each agent’s action, imposes the communication delay that makes the whole research programme possible, writes frames and metrics, and streams the run into a browser.

It is also where the delay lives. Neither the engine nor the coordination library knows that an agent’s view of its peers is stale. Maneuver.Map is what makes it so.

Availability. Maneuver.Map is proprietary and is not deployed publicly. This page documents its architecture and semantics. See Reproducibility and Data Availability for what we share.

Why it exists

An experiment is not a run. It is a grid of runs, each identified by its position in a parameter space, each seeded deterministically, each carrying enough metadata that a year later you can say what produced it. Getting that right is unglamorous and it is most of the work — a swept parameter that silently collapses to its last value, a seed reused across conditions, a stale binary that ships the wrong algorithm, all produce clean-looking results that mean nothing.

Maneuver.Map’s job is to make those failures loud.

The delay-coupled harness

This is the component that the delay-coordination papers rest on, and it is worth describing exactly.

At each step the runner maintains a ring of recent state frames — positions and velocities for the last delay_steps + 1 steps. The oldest frame in the ring is the delayed view: what an agent would perceive if its knowledge of its peers had to travel to it at finite speed. The coordination primitive is handed that view, not the true one, and returns an acceleration.

Delay is set either directly in steps or derived from the engine’s communication latency in milliseconds, converted using dt. Ring memory is bounded, so a pathological delay setting fails rather than exhausting the host.

Two details are load-bearing, and getting either wrong destroys the experiment.

Actuation must reference true velocity. The primitive decides on the delayed or predicted view, but the acceleration it returns is applied against the agent’s actual velocity. If actuation also uses the stale velocity, the mismatch injects energy into the system on every step, and on an unclamped engine the swarm diverges to non-finite values.

Prediction is a hook on the decision, not on the state. When a peer predictor is configured, the delayed view passes through it, is extrapolated forward by the delay horizon, and the primitive decides on the estimate. The prediction is scored against the state that actually materializes — for calibration — and never mutates ground truth.

The runner surfaces task_metrics (coordination quality $Q$ and its components), cost_metrics (bits delivered, joules spent, per-bit energy; zeros when the engine reports no communication), and prediction_metrics (calibration error against realized state) in every run summary.

Sweeps and the cell

A sweep is declared as a set of axes over the experiment specification, including nested paths into the engine configuration. The expander takes the Cartesian product and emits one fully materialized specification per cell.

Each cell is deep-copied. This is not an optimization detail. A shallow copy aliases the nested engine configuration across cells, so every swept nested axis — communication latency, for instance — silently collapses to whichever value was written last, and the resulting phase diagram is a flat line that looks like a finding. Sweep designs beyond the full grid include Sobol and Latin-hypercube sampling for higher-dimensional spaces.

Cells run as a cloud job array, one task per cell, writing into a batch folder under a readable name with a manifest that enumerates the cells. A batch is immutable once written; a reanalysis produces a new batch rather than overwriting an old one. Batch identifiers appear verbatim in each paper’s reproducibility appendix.

Engines and the fake

Three execution backends. HTTP talks to the Leviathan runtime service and is what a multi-tenant deployment uses. In-process imports the pybind11 extension directly, skipping an HTTP round-trip per step; this is what every published run used. A fake engine implements the same protocol with no physics at all, for testing orchestration logic without the C++ core.

The fake engine has one known asymmetry worth remembering: it has no energy module. An experiment that looks healthy against the fake can, on the real engine, drain agent batteries in proportion to speed squared, flip agents to faulty, and quietly turn a coordination result into an attrition result. Both delay papers disable the energy and fault modules for this reason.

Provenance and the seed tree

Every cell writes an experiment.json carrying a provenance block captured at run time: resolved package versions for the coordination and physics layers plus the scientific-Python stack; a SHA256 lockfile hash over every installed name==version pair; a hardware fingerprint (platform, Python version, architecture, CPU count, CUDA visibility); and the full seed tree.

The seed tree is deterministic and hierarchical — exp_seed → gen_seed → candidate_seed → repeat_seed — so any leaf is reproducible from the root, and two runs at the same leaf produce identical metrics.

Provenance also has fields for git describe, commit, branch, and a dirty flag. Under the production worker these are null: the engine runs in-process from a prebuilt container carrying no checkout. We do not paper over that. The lockfile hash and the pinned image digest are the reproducible identity there. Note also that provenance does not compute wheel digests at run time; where a paper pins one, it comes from the release artifact.

Tuning

Parameter search runs on Optuna  by default — a tree-structured Parzen estimator, or CMA-ES, with successive-halving pruning of unpromising trials. A legacy genetic algorithm remains available for ablation parity against older runs. Objectives are computed from the run summary, so any metric the runner surfaces can drive the search.

Data and the viewer

Runs write Parquet part files, one per logged step, with a CSV mirror for compatibility. The frame API streams those parts through Apache Arrow  with predicate pushdown on the timestep and column pruning, so scrubbing a million-row run fetches the slice requested rather than the whole file.

The browser client renders agents in 3D with server-side decimation on the timeline scrubber, live run status over server-sent events, and an overlay for scenario geometry. Presets in the interface cover the delay-coordination grids and the Vicsek anchor directly, alongside a cost estimate for a proposed run before it is scheduled.

Analysis templates load any batch and regenerate the canonical figures: phase diagrams, order-parameter timeseries, criticality and finite-size scaling, interaction-graph structure, prediction gain, and the cost frontier.

Operational notes

The worker layers Python onto a pinned, prebuilt engine base image. A change to the C++ core therefore does not reach production until the base image is rebuilt and the deployment’s substitution variables are pointed at the new tag. Likewise the coordination library is consumed as a pinned wheel: a forgotten version bump silently ships the previous build, and any new import wrapped in a try/except fails silently rather than loudly. Our build gate asserts that specific new symbols are importable, so a stale wheel breaks the build instead of zeroing a metric.

Related

Leviathan is the physics and communication substrate; Gossamer supplies the primitives, tasks, predictors, and metrics. The benchmark suite is at Arboria Swarm Benchmark.