Leviathan Engine

High‑performance C++ simulation core for large swarms. Leviathan advances agent states using physics and environment models, accepts actions from Gossamer, and logs outputs for Maneuver.Map to orchestrate, visualize, and analyze experiments.

How It Fits With Gossamer + Maneuver.Map

• Leviathan: physics, environment, agent state, scalable stepping, logging.
• Gossamer: provides action policies (e.g., flocking) and metrics; used via Python bindings.
• Maneuver.Map: controls runs, tunes parameters, stores data (e.g., GCS), and serves 3D visualization and APIs.

Features

• Fast agent stepping with configurable physics and boundary conditions.
• Environment fields: none, uniform vector, central inverse‑square (gravity‑like); configurable latency placeholder.
• Deterministic seeding for reproducible initial conditions (seed).
• CSV logging with frequency and path; optional Parquet part files if Arrow/Parquet available at build (or convert via utility).
• Python bindings via pybind11; simple LeviathanEnv for Python integration.

Build & Run (Local)

mkdir -p build && cd build
cmake .. && make -j
./leviathan_sim 1000

Minimal config example (key: value per line):

dt: 0.1
num_agents: 200
bound: 1000
output_path: ./output/leviathan_output.csv
output_frequency: 10
field_type: none   # or uniform | central
field_vx: 0.0
field_vy: 0.0
field_vz: 0.0
field_strength: 0.0
seed: 123
output_format: csv  # or parquet (requires Arrow/Parquet at build)

Output Schema

• CSV columns: timestamp,agent_id,position_x,position_y,position_z
• Parquet: if output_format: parquet, the engine writes part files under <output_path>.parts/part-<step>.parquet for each logged step.
• CSV→Parquet conversion also available: python scripts/csv_to_parquet.py path/to/leviathan_output.csv

Python Integration

• Bindings module name: leviathan
• Python environment wrapper: leviathan_env.py with reset(), step(actions), compute_metrics()
• Used by Maneuver.Map runner and Gossamer’s LeviathanInterface to couple actions to physics.

Docker

• See Dockerfile for a Cloud‑ready build of core + bindings. The Maneuver.Map Orchestrator image builds Leviathan and serves APIs.

Typical Research Workflow

1. Define agent logic in Gossamer (policies, metrics).
2. Configure Leviathan (environment, agents, output format and frequency).
3. Run simulation locally or via orchestrator; log CSV/Parquet.
4. Visualize and analyze in Maneuver.Map.

Configuration Reference

These keys configure Leviathan when invoked directly or via the orchestrator’s engine client (mapped into a config map of strings).

Core

• dt: Simulation time step in seconds. Controls integration fidelity and stability.
• num_agents: Number of agents to simulate. Impacts memory and per‑step cost linearly.
• bound: Half‑extent of the cubic domain (−bound…+bound). Used for simple boundary conditions and some algorithms’ normalization.
• seed: Deterministic seed for initial conditions; set for reproducibility.

Output

• output_path: Path to CSV (e.g., ./output/leviathan_output.csv). When output_format=parquet, part files are written to output_path + ".parts".
• output_frequency: Write rows every N steps. Larger N → fewer frames, smaller files.
• output_format: csv (default) or parquet (requires Arrow/Parquet at build). Parquet writes one part-<step>.parquet per logged step.

Environment field

• field_type: none | uniform | central (inverse‑square, gravity‑like toward origin).
• field_vx, field_vy, field_vz: Components for uniform field (magnitude/direction).
• field_strength: Strength scalar for central or uniform fields.
• comm_latency_ms: Placeholder modeling of communication latency in the environment (if compiled into the build; used by higher‑level behaviors).

Output Details

• CSV schema (engine default): timestamp,agent_id,position_x,position_y,position_z.
• Parquet schema (if enabled): same columns as CSV; emitted in parts under <output_path>.parts/.
• Maneuver.Map may extend the schema when orchestrating (CSV includes additional columns like role,soc,aoi,density,pheromone and emits Parquet parts by default). The viewer selects and streams only the columns it needs.

Performance Notes

• Use higher output_frequency to reduce I/O when stepping many agents.
• Prefer Parquet for downstream slicing/streaming in Maneuver.Map; predicate pushdown prunes time ranges and columns server‑side.
• For very large num_agents, ensure the surrounding container has sufficient memory; simulation cost scales roughly linearly with agent count per step.