DOC 02FAB ENGINE

FAB Engine: vehicle dynamics

FAB is LEVIATHAN's physics and sensing core. This page covers its vehicle dynamics: a six-degree-of-freedom rigid body in water, moved by thrusters, fins, buoyancy, currents and waves, and integrated with a fourth-order Runge–Kutta scheme.

State and frames

A vehicle's state is its pose η in the world frame and its velocity ν in the body frame.

η = [ x, y, z, φ, θ, ψ ]^T ν = [ u, v, w, p, q, r ]^T

Position is in metres in a north-east-down (NED) world frame. Attitude is roll, pitch and yaw in radians, in the ZYX convention. Body velocities are in the forward-starboard-down (FRD) body frame, in m/s and rad/s. The body origin is the centre of gravity. See Coordinate frames for the full set of frames.

Equations of motion

LEVIATHAN implements the marine-craft equations of motion in the form given by Fossen (Handbook of Marine Craft Hydrodynamics and Motion Control, 2011):

η̇ = J(η) ν(1)

M ν̇ + C_RB(ν) ν + C_A(ν_r) ν_r + D(ν_r) ν_r + g(η) = τ(2)

ν_r: velocity relative to the water, ν − ν_c, where ν_c is the local current in the body frame
M: rigid-body mass and inertia plus added mass, M_RB + M_A; it depends only on configuration and is inverted once
C_RB, C_A: rigid-body and added-mass Coriolis–centripetal matrices; the added-mass term uses the general form when the vehicle declares off-diagonal added mass
D: hydrodynamic damping, linear plus quadratic
g: gravity and buoyancy restoring forces and moments
τ: applied wrench from thrusters, fins and external loads

Force models

Damping

Damping is diagonal by default: on each axis D_ii = d_L,i + d_Q,i|ν_r,i|. Two optional refinements cover cases the diagonal form describes poorly.

Projected drag. The translational quadratic terms are replaced by a single term along the flow, using the area the hull presents to the flow direction. It is identical to the diagonal form for flow along a body axis, and isotropic for a sphere.
Cross-flow drag. Slender hulls such as torpedo AUVs integrate drag along the hull length, in strips. That integral replaces the sway, heave, pitch and yaw quadratic terms, so the same force is not counted twice.

Buoyancy and gravity

Weight W = mg acts at the centre of gravity, and buoyancy B = ρgV acts at the centre of buoyancy r_b. Both are rotated into the body frame. A centre of buoyancy above the centre of gravity gives a passive righting moment in roll and pitch. All built-in underwater vehicles are neutrally buoyant, B = W, with ρ = 1025 kg/m³ and g = 9.81 m/s².

Surface vessels

A vehicle with a waterplane area floats. Heave stiffness comes from the linear Froude–Krylov pressure about the instantaneous wave surface, and metacentric heights give roll and pitch righting toward the local surface normal:

F_z = −ρ g A_w (z + ζ) K = −W GM_T (φ − φ_eq) M = −W GM_L (θ − θ_eq)(3)

Here ζ is the local surface elevation, and φ_eq, θ_eq are the angles of the wave slope. This is linear theory for small angles, intended for gentle to moderate sea states. Wind acts on the above-water area through a drag law. The projected area blends between frontal and lateral with the apparent-wind angle, and an offset centre of pressure makes the vessel weathervane.

Wave loads on submerged bodies

A submerged hull in waves feels the inertial force of the accelerating water: the Froude–Krylov force on the displaced volume plus the added-mass reaction, F_i = (ρV + A_ii) a_i, rotated into the body frame. Only the force is modelled; wave-induced moments on submerged bodies are not included.

Near-seabed effect

An optional ground-effect term adds heave damping close to the seabed. Its gain falls off as exp(−(h/L)²) with clearance h, and it always opposes heave motion.

Thrusters and fins

Allocation

Each thruster has a position r_i and a unit direction d_i, and contributes the column [d_i ; r_i × d_i] to the configuration matrix T, so τ = T u. To realise a desired wrench, LEVIATHAN solves for the thruster forces with a lightly damped least-squares pseudoinverse. Directions a configuration cannot produce are dropped rather than distorting the others. Each force is then clamped to the vehicle's per-thruster limit.

Allocation can be fault-aware. Given an effectiveness factor per thruster, it shifts load to the healthy units, and a factor of zero removes a thruster entirely. Power draw is estimated from actuator-disk momentum theory: |F|^3/2 / √(2ρA) per thruster, divided by an efficiency and added to a constant hotel load.

Thruster response

Table 2.1 Thruster response models. Each one reduces to the first-order model in its linear limit.
Model	Behaviour	Parameters
First order	Force approaches the command: f ← f + (1 − e^−Δt/τ)(f_cmd − f)	tau [s]
Yoerger	First order plus a quadratic self-damping term in the force	tau [s], beta [1/(N·s)]
Bessa	Command dead-zone, first-order response and saturation, as in an ESC-driven thruster	tau [s], dead [N], fmax [N]

Control fins and wings

Fin-steered vehicles (the torpedo AUV, REMUS-100 and HUGIN presets) turn and dive with control surfaces whose lift depends on their deflection and on the flow over them. Each fin has an area, a lift slope, a zero-lift drag coefficient and a stall angle. Their force grows with speed, so a fin-steered vehicle can manoeuvre under way but cannot hold station. The glider's fixed wings turn buoyancy-driven sinking and rising into forward glide.

Integration

Each step is a classical RK4 step with the applied wrench and the current held constant over the step (zero-order hold). External wrenches that depend on the pose, such as surface hydrostatics, buoyancy-engine forces and tethers, are evaluated at every RK4 stage.

The step is fixed, not adaptive. Scenario rollouts default to 0.02 s, the GPU learning environments to 0.05 s, and the glider's slow glide profile to 0.5 s. Too large a step can make an agile vehicle diverge. Where that happens depends on the motion as well as the vehicle, so no single per-vehicle limit exists.

Vehicle parameters

A vehicle is described by the following physical parameters. Built-in values are listed on Vehicles.

Table 2.2 Vehicle parameters used by the dynamics. Six-component quantities are ordered surge, sway, heave, roll, pitch, yaw.
Parameter	Meaning	Units
Mass	Dry mass m	kg
Volume	Displaced volume V; buoyancy is ρgV	m³
Inertia	Principal moments I_xx, I_yy, I_zz about the centre of gravity	kg·m²
Centre of buoyancy	Offset of buoyancy from the centre of gravity, body frame	m
Added mass	Diagonal X_u̇ … N_ṙ, optional off-diagonal coupling	kg, kg·m²
Linear damping	Diagonal linear coefficients	N·s/m, N·m·s/rad
Quadratic damping	Diagonal quadratic coefficients	N·s²/m², N·m·s²/rad²
Thrusters	Position and direction of each unit	m, unit vector
Maximum thrust	Per-thruster force limit (none if zero)	N
Thruster time constant, dead-band	Spin-up time constant and command dead-band	s, N
Fins	Position, lift direction, area, lift slope, zero-lift drag, stall angle	m, m², 1/rad, —, rad
Cross-flow drag coefficient	Strip-theory drag coefficient for slender hulls	—
Waterplane area, metacentric heights	Surface-vessel heave stiffness and roll/pitch righting	m², m
Frontal and lateral area	Above-water areas for wind loads	m²
Propeller diameter, efficiency, hotel load	Inputs to the power estimate	m, —, W

Batched dynamics on the GPU

For reinforcement learning, the same equations are evaluated for thousands of vehicles at once as PyTorch tensors, with state arrays of shape (n, 6). The batched implementation is tested against the analytic model. Over randomised rollouts in double precision on the CPU, the worst-case difference is below 10⁻⁹. On a GPU in single precision it agrees within a looser tolerance, because the precision and summation order differ. If a vehicle needs a term the batched backend does not provide, the backend refuses the configuration instead of returning a silently different result.

Reference-checked The batched backend is compared with LEVIATHAN's own CPU implementation. That shows the two implementations agree; it is not a comparison with measured vehicle data.

Built-in controllers

Table 2.3 Controllers available to a simulated vehicle. On the canonical World they can act on true state or on the localization estimate; elsewhere they act on true state.
Controller	Description
Passive	No actuation
Constant wrench / constant thrust	A fixed body wrench, or fixed per-thruster forces
Autopilot	PD depth and heading hold
Station keeping	PID position and heading hold, with optional attitude levelling
Waypoint following	PD waypoint follower with course steering and acceptance radius
Trajectory tracking	Follows a circle, line, piecewise or lawnmower reference

Model limits

Added mass and damping are rigid-body coefficients, not a flow solution. Interaction with nearby structures is not modelled, apart from the optional near-seabed term.
Wave moments on submerged bodies are not modelled, and surface-vessel hydrostatics are linear.
Fin post-stall behaviour is a simple clamp, and the built-in stall angles are flagged in the vehicle definitions as unsourced.