Skip to Content
ToolchainManeuver Map

Maneuver.Map

Maneuver.Map orchestrates multi-generation experiments, tunes Gossamer parameters (Optuna TPE / CMA-ES by default, legacy GA available for ablation), runs Leviathan simulations, writes data to GCS, and renders a performant 3D view in the browser.

Run locally

# Backend (FastAPI orchestrator)
python3 -m venv .venv && source .venv/bin/activate
pip install -r maneuver-map/backend/requirements.txt
# Route through the in-process Leviathan binding to skip HTTP-per-step:
export ENGINE_MODE=inprocess
uvicorn app.main:app --app-dir maneuver-map/backend --reload --port 8000
 
# UI (Vite + React)
cd maneuver-map/frontend-react && npm install && npm run dev

Minimal experiment request

curl -X POST http://localhost:8000/experiments -H 'Content-Type: application/json' -d '{
  "name": "smoke",
  "steps": 500,
  "num_agents": 500,
  "dt": 0.1,
  "algorithm": "flocking",
  "seed_base": 42
}'
# → { "status": "scheduled", "exp_id": "…" }

View the run in the UI, or load it for analysis via the notebook templates .

Cite this tool

@software{arboria2026maneuvermap,
  title  = {Maneuver.Map: orchestration and visualization for large-scale swarm experiments},
  author = {{Arboria Labs}},
  year   = {2026},
  url    = {https://www.arborialabs.com/tools/maneuver_map}
}

How It Fits With Gossamer + Leviathan

  • Drives Leviathan over HTTP or in-process pybind (ENGINE_MODE=inprocess); the in-process path skips a full HTTP round-trip per step and is what we use for million-step rollouts.
  • Calls Gossamer policies (gossamer.algorithms.coordination.{dmb, tfaco, iccd, hma}) for per-step actions; the runner is pure orchestration, with no policy logic of its own.
  • Writes Parquet parts (and CSV for compatibility) plus an experiment.json carrying a full provenance block — git hashes, wheel SHAs, lockfile hash, hardware fingerprint, and the deterministic seed tree (exp_seed → gen_seed → candidate_seed → repeat_seed).
  • Streams /frames from Parquet via pyarrow.dataset predicate pushdown, with column pruning + decimation server-side.
  • Uploads completed runs to GCS at gs://<bucket>/<prefix>/<exp_id>/.

Typical Workflow

  1. Schedule an experiment via POST /experiments (Web UI, curl, or a notebook).
  2. Orchestrator runs each generation: Gossamer emits actions, Leviathan advances physics, the runner writes Parquet parts and updates experiment.json (with provenance, seed tree, and progress).
  3. Visualize in the React UI (Three.js scrubber) backed by the /frames API, or stream via SSE from /events/experiments.
  4. Analyze post-hoc with the Jupyter notebook templates in maneuver-map/notebooks/ — load_experiment, phase_diagram, order_parameter_timeseries, interaction_graph, criticality. Each takes an exp_id and reads from local DATA_DIR or gs:// transparently.
  5. Reproduce by replaying any exp_id: the seed tree + provenance block guarantee byte-identical metrics on the same hardware.
# Backend (FastAPI orchestrator)
cd maneuver-map/backend
pip install -r requirements.txt
cp .env.example .env
export ENGINE_MODE=inprocess          # or set ENGINE_URL for the HTTP path
uvicorn app.main:app --reload         # http://127.0.0.1:8000
 
# UI (Vite + React)
cd ../frontend-react
npm install && npm run dev
 
# Quickstart CLI: render an interactive HTML from a CSV output
pip install -r requirements.txt
python viz.py /path/to/leviathan_output.csv --out swarm.html

Cloud Storage Integration

  • Set DEFAULT_GCS_BUCKET and DEFAULT_GCS_PREFIX env vars on the backend for automatic upload of every completed experiment.
  • Or provide gcs_bucket / gcs_prefix per request in POST /experiments for one-off destinations. Token expansion: {yyyy}, {mm}, {dd}, {name}.

API Quick Reference

  • GET /health, GET /estimate?steps=&num_agents=&generations=
  • POST /experiments — body fields:
    • Run shape: name, resume_exp_id (optional), steps, num_agents, dt, generations, output_frequency, seed.
    • Output: output_mode ("both" | "csv" | "parquet" | "none", default both), checkpoint_every_steps.
    • Algorithm: algorithm (flocking | iccd | dmb | tf_aco | dmb_tf_aco | hma_market), flock_params, algo_params (per-algorithm sub-tree).
    • Tuning: optimize (bool); optimize_backend ("optuna" | "ga", default "optuna"); optimize_sampler ("tpe" | "cmaes"); optimize_trials, population_size, eval_steps, parallelism, early_stopping_*, repeats.
    • Environment: environment_preset or target_body; SPICE fields start_utc, duration_sec, spice_kernels[], ephem_center, ephem_frame, ephem_abcorr, ephem_step_sec.
    • Storage: gcs_bucket, gcs_prefix.
  • POST /experiments/sweep — Cartesian, Sobol, or Latin-hypercube designs:
    • design: "cartesian" | "sobol" | "lhs" (default cartesian).
    • axes (Cartesian) or ranges={path: [lo, hi]} + n_samples (Sobol/LHS, requires scipy>=1.11).
  • GET /experiments, GET /experiments/{exp_id} — returns the full experiment.json including the provenance block.
  • GET /events/experiments — SSE stream of progress updates.
  • GET /frames?exp_id=&gen_index=&start=&end=&stride=&max_points=&color_attr= — server-side decimation; optional color_attr (soc, density, pheromone, role, etc.).
  • POST /jobs/run — invoke Cloud Run Jobs for batch evaluation.

Scheduler Parameters

Use the Schedule Experiment modal in the UI to launch runs. Below is what each input controls and how it maps to the backend.

Core Settings

  • Name: Label for the run; stored in experiment.json as name and used when uploading to GCS.
  • Steps: Total simulation steps per generation (steps). Higher values produce longer runs and more frames.
  • Agents: Number of simulated agents/particles (num_agents). Affects compute cost roughly linearly.
  • dt: Physics time step in seconds (dt). Smaller dt means finer integration; increases step count for a fixed real time.
  • Generations: How many full runs to execute sequentially (generations). Each generation has its own gen-XXX output directory.
  • Output freq: Write frames every N steps (output_frequency). Lower values write more frames and larger outputs; higher values decimate output.

Algorithm

  • Algorithm: Selects the control policy used during the simulation (algorithm). Options:
    • flocking: Baseline boids-like control using Gossamer flocking metrics.
    • iccd: Intent-aware communications + contact delay simplification. Adds agent attributes like AoI and SoC.
    • dmb: Density‑Modulated Boids; adapts flock weights based on local density.
    • tf_aco: Terrain/Field Ant Colony Optimization; coverage-biased motion using a pheromone grid.
    • dmb_tf_aco: Hybrid of DMB and TF‑ACO.
    • hma_market: Macro‑micro construction logistics; uses role/task structures (haulers, printers, micro agents).
  • Algorithm params (JSON): Merged into the request to configure algorithm components. Common keys include:
    • flock_params: { alignment_weight, cohesion_weight, separation_weight, neighbor_radius, separation_distance, max_speed } — base weights and limits.
    • dmb: { alpha, beta, d0, d1, neighbor_radius, separation_distance, max_speed } — schedules weights vs. density.
    • tfaco: { grid_resolution, pheromone_evap_lambda, deposit_rate, heuristic_weight, max_grid } — pheromone grid and exploration.
    • iccd: { initial_aoi, relay_rotation } — AoI baseline and relay rotation behavior.
    • dtn: { contact_density, bandwidth_kbps, one_way_delay_sec, custody_transfer } — simplified delay‑tolerant network.
    • energy: { soc_wh } — initial state of charge wh per agent.
    • agents: e.g., { micro: { count }, macro: { haulers, printers } } — agent role counts for HMA.
    • depots: { count } — number of depots for HMA logistics.
    • hma: role/task tunables (if any) used by HMA flows.
    • obstacles: { field: true, strength, range, count } — optional potential‑field repulsion for hazard avoidance.

Effects during the run:

  • flocking weights drive accelerations directly each step.
  • dmb computes global/approximate density and adjusts weights on the fly.
  • tf_aco constructs a pheromone grid over X‑Y; agents bias motion toward low‑pheromone cells with evaporation.
  • iccd and dtn add per‑agent attributes (AoI, SoC, density) and simple communications effects.
  • hma assigns roles and simple depot→printer flows, accumulating printed material metrics.

Parameter Sweeps

  • Sweeps (JSON): Submits a Cartesian sweep of parameters to /experiments/sweep. Keys can be dotted paths into the request, e.g. { "dmb.neighbor_radius": [100,300,500] }. The backend schedules one run per combination in the background.

Environment & Ephemerides

  • Environment preset: Predefined environment that may set a domain bound and optional SPICE fields (e.g., mars, ceres).
  • Target body: Body name for ephemerides (target_body).
  • Start UTC: Start of the ephemerides window (start_utc, ISO8601 UTC).
  • Duration (sec): Duration of ephemerides window (duration_sec).
  • Kernel URIs: Comma‑separated SPICE kernel URIs/paths (spice_kernels) — supports gs://.
  • Center: Reference center (ephem_center, e.g., SUN).
  • Frame: Reference frame (ephem_frame, e.g., J2000).
  • Aberrations: Corrections (ephem_abcorr, e.g., NONE, LT+S).
  • Step (sec): Sampling step for ephemerides (ephem_step_sec).

When provided, ephemerides are computed and embedded in experiment.json under environment.meta.ephemerides, and the visualization can overlay them. The environment bound may be suggested from the max radius.

Optimization (tuner)

  • Optimize: Toggles the parameter-search pass before the final canonical run (optimize=true). Default tuner backend is Optuna; the legacy GA is preserved for ablation.
  • Backend (optimize_backend): "optuna" (default) or "ga".
  • Sampler (optimize_sampler, Optuna only): "tpe" (Tree-structured Parzen Estimator) or "cmaes" (covariance-matrix adaptation). Hyperband pruning is enabled automatically.
  • Trials (optimize_trials): for Optuna, total trial budget. Defaults to generations × population_size.
  • Population / eval steps / parallelism: same meaning as before; population_size doubles as Optuna’s per-step concurrency.

GA-mode internals (optimize_backend="ga" only): selection_fraction 0.5, mutation_rate 0.3, crossover_rate 0.7, early_stopping_patience 3, early_stopping_delta 1e-6, repeats 1.

The earlier fitness bug — the GA tuner ignored its own score_objective and returned avg_energy — is fixed; both backends now respect the configured objective.

Sweep designs

  • Cartesian (design="cartesian", default): one run per combination in axes.
  • Sobol (design="sobol"): low-discrepancy quasi-random over ranges={path: [lo, hi]} and n_samples. Best for space-filling designs.
  • Latin hypercube (design="lhs"): same shape, stratified sampling. Both Sobol and LHS require scipy>=1.11.

Output, provenance & reproducibility

  • Frames are written every output_frequency steps as Parquet parts (with a CSV mirror); use output_mode="none" for metrics-only runs (the canonical mode for sweeps).
  • experiment.json carries the full provenance block — git describe, wheel SHAs for Gossamer + Leviathan, pip freeze hash, hardware fingerprint, and the deterministic seed tree (exp_seed → gen_seed → candidate_seed → repeat_seed). Two runs at the same seed produce byte-identical metrics.
  • If DEFAULT_GCS_BUCKET / DEFAULT_GCS_PREFIX are set on the backend, completed runs upload automatically. The UI can list recent GCS runs and hydrate them for local viewing.

Analysis notebooks

Five Jupyter templates ship under maneuver-map/notebooks/:

  • load_experiment.py — pull any exp_id (local or gs://) into pandas/xarray.
  • phase_diagram.py — render the (density × noise) phase map used by the DMB paper.
  • order_parameter_timeseries.py — ψ vs time, with bootstrap CIs and partition-event overlays.
  • interaction_graph.py — draw the radius graph as an overlay on the 3D scatter for a chosen frame.
  • criticality.py — susceptibility, Binder cumulant, correlation length, and finite-size scaling fits.

Each template accepts --exp_id and reads from DATA_DIR or GCS transparently; running them against the canonical paper exp_ids regenerates the headline figures.

Last updated on
Gossamer Threaded Intelligence