Skip to Content
Our ToolsManeuver Map

Maneuver.Map

Maneuver.Map orchestrates multi‑generation experiments, evolves Gossamer parameters, runs Leviathan simulations, writes data to GCS, and renders a performant 3D view in the browser.

How It Fits With Gossamer + Leviathan

  • Controls Leviathan runs and exposes APIs for scheduling, listing, slicing frames, and visualization.
  • Uses Gossamer algorithms during runs to compute agent actions and metrics.
  • Outputs CSV/Parquet and metadata for archival and analysis.

Typical Workflow

  1. Generate data by running experiments via the orchestrator; Leviathan writes CSV (or Parquet via converter).
  2. Orchestrator Web (FastAPI):
    • Local run: 
      cd backend
pip install -r requirements.txt
# Ensure Leviathan bindings are importable and Gossamer installed
cp .env.example .env
uvicorn app.main:app --reload
# Visit http://127.0.0.1:8000
    • Docker (Cloud‑ready): 
      cd backend
docker build -t gcr.io/<PROJECT_ID>/maneuver-map-orchestrator:latest .
docker push gcr.io/<PROJECT_ID>/maneuver-map-orchestrator:latest
  3. Quickstart (CLI): Render an interactive HTML from Leviathan CSV output. 
    pip install -r requirements.txt
python viz.py /path/to/leviathan_output.csv --out swarm.html
  4. Explore Visualization:
    • React UI (Three.js) with time slider; data served by /frames API.
    • Local UI dev: 
      cd frontend-react
npm install
cp .env.example .env  # set VITE_API_BASE to orchestrator URL if needed
npm run dev

Cloud Storage Integration

  • Provide gcs_bucket and gcs_prefix in POST /experiments to upload outputs and metadata to gs://<bucket>/<prefix>/<experiment_id>/....

API Quick Reference

  • GET /health, GET /estimate
  • POST /experiments fields: name, steps, num_agents, dt, generations, output_frequency, optimize, objective, population_size, eval_steps, repeats, parallelism, early_stopping_*, environment_preset|target_body|environment_bound, start_utc, duration_sec, spice_kernels[], ephem_center, ephem_frame, ephem_abcorr, ephem_step_sec, gcs_bucket, gcs_prefix
  • GET /experiments, GET /experiments/{id}
  • GET /frames?exp_id&gen_index&start&end&stride&max_points

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 (Evolution)

  • Optimize (evolution): Enables evolutionary search before running a final best experiment (optimize=true).
  • Population: Candidates per generation (population_size).
  • Eval steps: Steps per candidate evaluation (eval_steps).
  • Parallelism: Concurrent candidate evaluations (parallelism).

Defaults used internally when not exposed in the modal:

  • selection_fraction 0.5, mutation_rate 0.3, crossover_rate 0.7, early_stopping_patience 3, early_stopping_delta 1e-6, repeats 1, seed_base 42.

Output & Storage

  • Frames are written every output_frequency steps. The orchestrator emits Parquet parts by default alongside CSV; the viewer reads via /frames which streams from Parquet when available.
  • If DEFAULT_GCS_BUCKET/PREFIX are configured on the backend, completed runs are uploaded automatically. The UI can also list recent GCS runs and hydrate them for local viewing.
Last updated on
Gossamer Threaded Intelligence