DOC 02FAB ENGINE

Time, frames and determinism

Ground truth is only useful if everyone agrees on where and when it was taken. This page defines LEVIATHAN's coordinate frames and transform convention, its simulation clock, and what it guarantees when you run the same thing twice.

Coordinate frames

Figure 2.1 The three frames you meet most often. Every frame is right-handed, and every length is in metres.

Table 2.1 Coordinate frames.
Frame	Axes	Used by
World	NED: x north, y east, z down; origin at the sea surface	Vehicle pose, scene geometry, currents, normals in world coordinates
Body	FRD: x forward, y starboard, z down; origin at the centre of gravity. A vehicle's root link is its body frame	Velocities, forces, thruster and sensor mounts
Camera	OpenCV optical: x right, y down, z forward along the optical axis	All cameras, intrinsics, camera-frame normals, z-depth
Acoustic and inertial sensors	Sensor FRD: x along the boresight, y starboard, z down	Imaging sonar, side-scan, multibeam, DVL, IMU

Attitude is roll φ, pitch θ and yaw ψ, applied in ZYX order: R_world←body = R_z(ψ) R_y(θ) R_x(φ). Elevation in the sonar frame is positive downward.

The Viewport's 3D renderer uses its own display axes internally. Every value LEVIATHAN reports or exports is in the frames above.

Transform convention

A transform T_{A_B} maps a point expressed in frame B into frame A:

p_A = R_{A_B} p_B + t_{A_B} T_{A_C} = T_{A_B} T_{B_C} T_{B_A} = T_{A_B}⁻¹(1)

Composition chains on the shared index. Directions transform by the rotation alone. A sensor's pose in the world is always formed as T_{world_body} T_{body_sensor}, and the mount transform T_{link_sensor} is declared in the vehicle's document.

Simulation time

The canonical World keeps time as integers. Each physics tick has a length in whole nanoseconds, and a tick index k maps to time exactly:

t_ns(k) = t_0,ns + (k − k₀) · Δt_ns(2)

A time step must be a whole number of nanoseconds, so 0.02 s becomes exactly 20 000 000 ns. Steps that are not are refused.
Changing the step starts a new epoch at the current tick. The list of epochs is part of the state's provenance.
Seconds are derived from integers when the physics needs them, never accumulated, so long runs do not drift.
The wall clock never enters simulation time.

Sensor schedules

Each canonical sensor samples at t_n = phase + n · period, both in integer nanoseconds. A schedule belongs to the sensor and is usually declared in the vehicle's document. A sample is taken only when it falls exactly on a committed physics tick. A sample between ticks is reported as off-tick and refused, never snapped to the nearest tick or interpolated.

Capture groups

Over a time window, every scheduled sensor of every vehicle contributes its samples. Samples at the same instant form a capture group: one immutable snapshot per sensor, all taken from the same committed World state. Groups are ordered by time and members by sensor identifier, so nothing depends on the order of requests.

The canonical World

A World holds a scenario live between requests: one or more vehicles, an environment and their controllers. You create it, step it, read its state, change the current or a controller, take snapshots, and reset it. The Dashboard's World panel provides these controls, and the Viewport can follow a World live.

The World panel: Play, Step 20, Reset, Show in Viewport, Export USD and Delete buttons, a north-up track plot, the vehicle's depth, speed, position, heading and attitude, and controls to set the current. — Figure 2.2 The World panel after stepping a world for one second of simulation time. A world can also be shown in the Viewport and exported as OpenUSD.

Table 2.2 World operations and limits.
Aspect	Behaviour
Step	Advance n ticks; only the new samples are returned
Edit	Replace the vehicle, environment, sensors or controller while keeping the current pose and velocity
Snapshot	Freeze the committed state at the current tick into an immutable, hashed record
Reset	Return to the start. There is no rewind to an intermediate tick
Lifetime	Worlds live in memory and do not survive a service restart; idle worlds are released after one hour
Capacity	Up to 32 open worlds, 2,000,000 steps each
Thruster faults	Refused on a live World; available in analytic scenario runs

Determinism and identity

Canonical products are content-addressed. A snapshot, a measurement or a perception frame records a SHA-256 hash of its scientific content. Floats are canonicalised first: negative zero becomes zero, and every NaN becomes a single quiet NaN that means "missing". The hash contains no wall-clock time, request order or cache state, so equivalent inputs produce the same identity. Display products, such as an sRGB preview or a sonar display image, have separate hashes and never affect the scientific identity.

Randomness is keyed. A random draw is a pure function of stable identifiers: the root seed, the sensor, the sample index, the effect and the cell or beam. It does not come from a generator's hidden position. A sample is therefore the same whether it is produced alone, in a batch, or after a World reset. The seed enters a measurement's identity only when a random effect was actually drawn.

Table 2.3 What is guaranteed about repeatability of canonical products.
Property	Status
Same spec, seed and frame, same build and platform	Bitwise identical. Tested in-process, across processes and across hash seeds
CPU and GPU imaging sonar	Bitwise identical on the tested scenes (see Imaging sonar)
Numerical equivalence across platforms	Not established
Bitwise identity across platforms	Not claimed

On the analytic tier, each sensor draws noise from its own generator. Give a sensor a seed to make its noise sequence reproducible; unseeded noise differs between runs. GPU learning environments in single precision are not bitwise reproducible across hardware.