DOC 01GETTING STARTED
System architecture
LEVIATHAN is a desktop application in front of a local simulation service. Inside the service, three tiers share the same physics. The analytic tier is fast and broad, the canonical World produces reproducible ground truth, and the GPU tier runs batched environments for learning.
The desktop application
The application has five workspaces, described in Application and workspaces. It renders the 3D scene, the Dashboard panels and the Hull and Hardware tools in the window. Every physical quantity it shows comes from the simulation service. The toolbar's connection indicator reports whether the service is reachable.
When the application starts, it launches the simulation service on the local machine, or reuses one that is already running. A packaged build carries its own service, so no separate Python environment is needed to use it. Sign-in with an Azarel account is configurable per installation. An installation may require it, or allow you to continue without an account.
The simulation service
The simulation service holds the FAB Engine and exposes it over local HTTP, with about 440 endpoints. The application uses the same endpoints that scripts and external tools can call. Requests are synchronous and bounded by declared limits. For example, a perception frame is limited to 65,536 pixels and a dataset request to 16 frames. Each capabilities endpoint reports its own limits.
The three tiers
Analytic tier
The analytic tier answers "what happens if I run this scenario". A request describes a vehicle, an environment, a controller and a sensor suite. The service integrates the dynamics and returns the full trajectory and sensor log. Most Dashboard panels, the Hull workspace and the hydrographic tools work here. Time is a floating-point step dt, and models trade generality for speed in clearly stated ways.
Canonical World
The canonical World answers "what exactly did each sensor see at this instant". A World is built from a scene document. You step it on an integer-nanosecond timeline, and it can hold several vehicles. At any tick you can take an immutable snapshot of the whole state. Sensor measurements, camera frames and ground-truth products are computed from snapshots, never from live state. Their identities are hashes of their scientific content, so the same inputs and seed always give the same result. See Time, frames and determinism.
World vehicles reuse the analytic tier's dynamics and environment models. They accept these controllers: passive, constant wrench, constant thrust, a PD depth and heading autopilot, PID station keeping, waypoint following and trajectory tracking. A controller can act on true state or on the localization estimate built from the vehicle's canonical sensors.
GPU tier
The GPU tier steps many copies of a vehicle at once for reinforcement learning. Its batched dynamics are tested against the analytic model: in double precision on the CPU they agree to within 10−9 over randomised rollouts. In single precision on a GPU the tolerance is looser, because reduction order and precision differ. The canonical imaging sonar also has a GPU backend, and it is bit-identical to the CPU reference.
The tiers share physics but not state. The reinforcement-learning environments run on the analytic and GPU tiers with their own task and scene descriptions. They do not run on the canonical World, and a World vehicle cannot be driven by a trained policy. Ground-truth products, canonical sensor measurements and the localization estimator all run on the canonical World, the one tier where sensing, estimation and control are joined.
The stack, layer by layer
From the world up to hardware, each layer of LEVIATHAN is a Python package in the simulation service, or the desktop application itself.
| Layer | What it holds | Packages | Status |
|---|---|---|---|
| World and environment | Scene documents, the canonical World and its state, integer-ns time, sensor schedules, vehicle catalogue, scene and material content | world, scene | Implemented |
| Physics and hydrodynamics | FAB dynamics, environment and ocean models, analytic sensors, scenario rollouts, hydrodynamics from geometry, GPU-batched backend | physics | Implemented |
| Rendering and optics | Underwater image formation, mesh ray casting, GPU sonar and raster paths | render | Implemented |
| Sensors | Canonical camera, sonar, DVL and IMU measurements; canonical pressure, magnetometer and USBL; sensor packets and the sensor rig | perception, sensors | Implemented |
| Perception | Ground truth, datasets and exports; perception algorithms, evaluators and benchmarks | perception | Ground truth implemented; algorithms graded per capability |
| Localization | Error-state Kalman filter, packet driver, runtime and estimate-driven control; the older analytic navigation EKF | localization, nav | Validated in simulation |
| Mapping and navigation | Hydrographic processing, marine navigation calculations, helm arbitration, COLREGs; no map estimation | api (domain modules), physics | Hydrography implemented; no SLAM |
| Control | Autopilot, station keeping, waypoint following, trajectory tracking, thruster allocation | physics | Implemented |
| Learning and evaluation | Learning environments and trainers, task-composition library, KRAKEN stage-attributed evaluation, benchmarks, run launcher | rl, marinelab, kraken, sim, eval | Implemented; training runs from scripts or projects |
| Hardware and interfaces | Harness design and checks, firmware generation, ROS 2 and LCM adapters, ArduSub SITL and MAVLink, replay, OpenUSD | hardware, adapters, replay, usd | Design tools and emulation implemented; bridges need external software |
| Development tooling | Projects and the Code workspace backend, accounts | projects, accounts | Implemented |
| Application | Electron desktop shell, React interface, three.js Viewport, RP2040 emulator | webapp | Implemented |
Service and API organisation
- One server. A single FastAPI application serves everything on the local machine. It starts with the desktop application, or on its own as the serve command.
- Domain modules. Each area registers its own routes: World, perception frame, motion, tracks, cross-modal, temporal, localization, scene, charts, tide, CUBE, navigation, COLREGs, propagation, accounts, hardware and others. The Code workspace's file, terminal and language-server endpoints are a separate router under /api/editor.
- Capabilities first. Perception and World areas publish a capabilities endpoint that states their schemas, limits and what is not modelled, so clients learn the contract from the service itself.
- Access control. When an installation requires sign-in, a gate refuses the API to unauthenticated callers, and live channels authenticate too. See Accounts and sign-in.
- Errors and limits. Requests are synchronous and bounded. Non-finite numbers are returned as null rather than breaking a response.
Live channels
| Channel | Purpose |
|---|---|
| Live stream | Pushes vehicle telemetry to the application at a requested rate, for example from an ArduSub SITL session |
| Terminal | Streams integrated-terminal sessions to the Code workspace |
| Language servers | Bridges editor language servers to the Code workspace |
| Remote device gateway | A registered device publishes frames with its token; LEVIATHAN relays them to the clients watching that device. See Hardware |
Within the application, the Viewport publishes its vehicle's live state to the Dashboard, so Dashboard panels follow the Viewport by default.
Data flow for ground truth
Extending LEVIATHAN
- Custom vehicles. Import URDF, SDFormat or MJCF, or upload a CAD hull. LEVIATHAN derives hydrodynamic coefficients from the geometry. See Vehicles.
- Scenes. Open and export scenes as OpenUSD from the Viewport's Scene menu. Stonefish .scn scenario files can be imported through the service.
- Agents. The service can also run as a Model Context Protocol server, so an LLM agent can drive simulations through the same operations the application uses.