diffUV

A differentiable 6-DOF underwater vehicle dynamics, with tooling for system identification, estimation, and control.

The core library provides symbolic kinematics and dynamics derived from Fossen's formulations. All major terms are represented as CasADi expressions, enabling analytic derivatives (gradients, Jacobians, Hessians) for optimization, estimation, and control workflows.

Scope and modeling assumptions

• Low-speed regime: less than 2 m/s, lift forces neglected.
• Symmetry: port-starboard and fore-aft symmetry; CG in symmetry planes.
• Hydrodynamic decoupling: symmetric 6-DOF motions treated independently.
• Below wave zone: wave disturbances are negligible.

Capabilities and implementation status

• Symbolic kinematics and dynamics (body, NED, quaternion).
• Forward and inverse dynamics.
• Added mass, damping, Coriolis/centripetal, and restoring force models.
• System identification utilities (CVXPY-based estimator).
• EKF and nonlinear PID helpers.
• CasADi code generation for C++/MATLAB/Python.
• Gymnasium environment and RL training script.
• JIT support.

Core library usage

from diffUV import dyn_body, dyned_eul, kin
uv_dyn = dyn_body()
uv_dyned = dyned_eul()

inertia_mat = uv_dyn.body_inertia_matrix()
coriolis_mat = uv_dyn.body_coriolis_centripetal_matrix()
restoring_vec = uv_dyn.body_restoring_vector()
dampn_mat = uv_dyn.body_damping_matrix()

v_dot = uv_dyn.body_forward_dynamics()

CasADi integration

Symbolic differentiation

from casadi import jacobian
accel_jacobian = jacobian(v_dot, uv_dyn.body_state_vector)

Code generation

import os
from casadi import Function
from diffUV.utils.symbols import *

I_o = vertcat(I_x, I_y, I_z, I_xz)  # rigid body inertia wrt body origin
decoupled_added_m = vertcat(X_du, Y_dv, Z_dw, K_dp, M_dq, N_dr)  # added mass in diagonals
coupled_added_m = vertcat(X_dq, Y_dp, N_dp, M_du, K_dv)  # effective added mass in non diagonals

M_func = Function('M_b', [m, I_o, z_g, decoupled_added_m, coupled_added_m], [inertia_mat])
M_func.generate("M_b.c")
os.system("gcc -fPIC -shared M_b.c -o libM_b.so")

System identification

The core implementation is in diffUV/system_id.py (MarineVehicleEstimator). The estimator formulates a convex fit in CVXPY with physical constraints; MOSEK is used by default, but can be replaced in the solver call.

Data requirements (vehicle log)

The identification notebook expects a single CSV with the following columns:

• timestamp
• imu_roll_unwrap, imu_pitch_unwrap, imu_yaw_unwrap
• imu_ang_vel_x, imu_ang_vel_y, imu_ang_vel_z
• dvl_speed_x, dvl_speed_y, dvl_speed_z
• depth_from_pressure2
• base_x_force, base_y_force, base_z_force
• base_x_torque, base_y_torque, base_z_torque

References

Fossen, T.I. (2011) Handbook of Marine Craft Hydrodynamics and Motion Control. John Wiley & Sons, Inc., Chichester, UK. https://doi.org/10.1002/9781119994138