Forces & Propulsion (Xdyn)

Forces & Propulsion Types (Xdyn)

Xdyn is the default physics engine behind LOTUSim's dynamics. You can use it to build a vessel's behaviour from a list of forces you declare in its model.yml file, under external forces (passive/environmental forces) and controlled forces (propulsion and control surfaces you can command at runtime).

This page lists what's available and what each type does. For full parameters and math behind each model, see the Xdyn User Guide.

---

Forces Available

Declared under a body's external forces: section.

Force	What it does
gravity	Basic weight force. Used by every vessel model.
basic buoyancy	Simple buoyancy from a fixed submerged volume, no hull mesh integration needed. Used by BlueROV2.
non-linear hydrostatic (fast)	Hydrostatic force integrated over the hull mesh, optimised for speed. The default choice across most surface/underwater models (DTMB, LRAUV, FREMM, PHA, Commando).
non-linear hydrostatic (exact)	Same as above, but prioritises precision over speed.
non-linear Froude-Krylov	Wave-induced pressure force integrated over the hull mesh. Used by DTMB and LRAUV.
diffraction	Wave diffraction force, computed from a hydrodynamic database (HDB) file. Used by LRAUV.
radiation damping	Damping force from the vessel's own motion in waves, also computed from an HDB file. Used by LRAUV.
linear damping	Damping proportional to velocity, defined via a 6×6 damping matrix. Used by DTMB, BlueROV2, Commando.
quadratic damping	Damping proportional to velocity squared. Used by DTMB, BlueROV2, FREMM, PHA.
resistance curve	Calm-water resistance as a lookup table (speed → resistance). Used by DTMB.

Related but separate: environmental conditions like waves (airy, no waves), wind (uniform wind, power law wind profile, no wind), and current (ekman current) are configured at the top of the YAML file under environment models, not per-body. See the Xdyn User Guide for details.

---

Propeller Types Available

Declared under a body's controlled forces: section, these are the actuators you send commands to at runtime.

Type	What it does
wageningen B-series	Standalone propeller model using standard B-series open-water propeller curves. Good default for individual thrusters. Used by BlueROV2 (8 thrusters) and LRAUV (single propeller).
propeller+rudder	Combined propeller + rudder unit, for vessels that steer with a rudder rather than differential thrust. Used by DTMB (port + starboard pairs).
Kt(J) & Kq(J)	Propeller model driven by your own thrust/torque coefficient curves (Kt, Kq vs. advance ratio J), instead of the built-in Wageningen B-series. Use this if you have measured or manufacturer-supplied propeller curves.
hydrodynamic polar	Lift/drag force model for control surfaces (fins, rudders), driven by angle-of-attack vs. lift/drag coefficient tables. Intended for vehicles with independent control fins.
aerodynamic polar	Same concept as hydrodynamic polar, for above-water control surfaces.
maneuvering	Maneuvering-model-based propulsion/steering force.
grpc	A custom force model served over gRPC from an external process, use this to implement propulsion logic outside xdyn itself, in any language.

Not sure which to use? If your vessel has independent thrusters (like a ROV or AUV), start with wageningen B-series. If it's a traditional single/twin-screw ship with a rudder, use propeller+rudder.

---

For the full parameter list, units, and underlying equations for any force or propeller type, see the Xdyn User Guide.