3-DOF model
This page summarizes the 3-DOF horizontal-plane model implemented in MarineSystemsSim.jl and how it maps to the main API functions.
Equation form
We follow the standard Fossen 3-DOF surface craft model in surge–sway–yaw:
\[\mathbf{M} \dot{\boldsymbol{\nu}} + \mathbf{C}(\boldsymbol{\nu}) \boldsymbol{\nu} + \mathbf{D}(\boldsymbol{\nu}) \boldsymbol{\nu} = \boldsymbol{\tau},\]
with
- body-fixed velocity vector $\boldsymbol{\nu} = [u, v, r]^T$,
- generalized forces/moments $\boldsymbol{\tau} = [\tau_x, \tau_y, \tau_\psi]^T$,
- constant inertia matrix $\mathbf{M} = \mathbf{M}_{RB} + \mathbf{M}_A$,
- Coriolis/centripetal term $\mathbf{C}(\boldsymbol{\nu})\, \boldsymbol{\nu}$,
- linear + quadratic hydrodynamic damping $\mathbf{D}(\boldsymbol{\nu})\, \boldsymbol{\nu}$.
The kinematics relate body-fixed velocities to Earth-fixed pose $\boldsymbol{\eta} = [x, y, \psi]^T$ via
\[\dot{\boldsymbol{\eta}} = \mathbf{R}(\psi)\, \boldsymbol{\nu}.\]
The full state is
\[\mathbf{X} = [x, y, \psi, u, v, r]^T.\]
Parameters and mass matrix
The rigid-body parameters and hydrodynamic coefficients are stored in RigidBody3DOF, QuadraticDamping3DOF, HydroParams3DOF and VesselParams3DOF. The assembled inertia and damping are cached in Vessel3DOF, which is the 3-DOF implementation of AbstractVesselModel. The inertia matrix is constructed by mass_matrix and stored (together with its inverse) inside the Vessel3DOF model.
You typically build a model via
Vessel3DOF(params)when you already haveVesselParams3DOF, orbuild_vessel3dof_fossenwhen starting from Fossen-style manoeuvring derivatives.
Rigid-body mass
For a surface vessel with mass m, yaw inertia Iz and centre of gravity at (x_G, 0) in the body-fixed frame, the rigid-body mass matrix is
\[\mathbf{M}_{RB} = \begin{bmatrix} m & 0 & 0 \\ 0 & m & m x_G \\ 0 & m x_G & I_z \end{bmatrix}.\]
This is assembled internally from RigidBody3DOF by a private helper and used by mass_matrix.
Added mass
The added-mass matrix $\mathbf{M}_A$ is stored directly inside HydroParams3DOF. When constructed via hydroparams_fossen3dof it has the simplified Fossen 3-DOF structure
\[\mathbf{M}_A = \begin{bmatrix} - X_{\dot{u}} & 0 & 0 \\ 0 & - Y_{\dot{v}} & - Y_{\dot{r}} \\ 0 & - Y_{\dot{r}} & - N_{\dot{r}} \end{bmatrix},\]
where $X_{\dot{u}}, Y_{\dot{v}}, Y_{\dot{r}}, N_{\dot{r}}$ are the usual Fossen added-mass derivatives.
The total inertia matrix is
\[\mathbf{M} = \mathbf{M}_{RB} + \mathbf{M}_A,\]
and is constructed by mass_matrix and cached in Vessel3DOF.
Coriolis and centripetal terms
The Coriolis/centripetal contribution is modeled as
\[\mathbf{C}(\boldsymbol{\nu}) \, \boldsymbol{\nu} = \bigl( \mathbf{C}_{RB}(\boldsymbol{\nu}) + \mathbf{C}_A(\boldsymbol{\nu}) \bigr)\, \boldsymbol{\nu},\]
with rigid-body and added-mass parts following Fossen’s 3-DOF expressions. Both matrices are constructed internally from the parameters and satisfy
\[\boldsymbol{\nu}^T \mathbf{C}_{RB}(\boldsymbol{\nu}) \, \boldsymbol{\nu} = 0, \qquad \boldsymbol{\nu}^T \mathbf{C}_A(\boldsymbol{\nu}) \, \boldsymbol{\nu} = 0,\]
so that they do not create or dissipate energy.
The product $\mathbf{C}(\boldsymbol{\nu}) , \boldsymbol{\nu}$ is provided by coriolis_forces.
Hydrodynamic damping
Hydrodynamic damping is represented as a linear part plus a diagonal quadratic part:
\[\mathbf{D}(\boldsymbol{\nu}) \, \boldsymbol{\nu} = \mathbf{D}_{\text{lin}} \boldsymbol{\nu} + \mathbf{D}_{\text{n}}(\boldsymbol{\nu}) \, \boldsymbol{\nu}.\]
Linear damping
The physical linear damping matrix (\mathbf{D}_{\text{lin}}) is stored directly in HydroParams3DOF and cached in Vessel3DOF. It is used exactly as it appears in the equations:
\[\mathbf{D}_{\text{lin}} \boldsymbol{\nu}.\]
When hydroparams_fossen3dof is used, (\mathbf{D}{\text{lin}}) is constructed from the Fossen derivatives Xu, Xv, Xr, \dots$ as
\[\mathbf{D}_{\text{lin}} = - \begin{bmatrix} X_u & X_v & X_r \\ Y_u & Y_v & Y_r \\ N_u & N_v & N_r \end{bmatrix}.\]
Here the derivatives are given in Fossen’s convention (typically non-positive for drag), while $\mathbf{D}_{\text{lin}}$ itself is a physical damping matrix that appears in the equation $\mathbf{D}(\boldsymbol{\nu})\, \boldsymbol{\nu}$.
Quadratic damping
The quadratic damping coefficients are stored in QuadraticDamping3DOF, holding the entries $X_{uu}, Y_{vv}, N_{rr}$. For a given velocity $\boldsymbol{\nu} = [u, v, r]^T$, the diagonal quadratic matrix is
\[\mathbf{D}_{\text{n}}(\boldsymbol{\nu}) = - \operatorname{diag}\bigl( X_{uu} |u|, Y_{vv} |v|, N_{rr} |r| \bigr),\]
so that the total damping becomes
\[\mathbf{D}(\boldsymbol{\nu}) = \mathbf{D}_{\text{lin}} + \mathbf{D}_{\text{n}}(\boldsymbol{\nu}).\]
The product $\mathbf{D}(\boldsymbol{\nu}) \, \boldsymbol{\nu}$ is computed by damping_forces.
Kinematics
The 3-DOF kinematics in the horizontal plane are
\[\dot{\boldsymbol{\eta}} = \mathbf{R}(\psi)\, \boldsymbol{\nu},\]
where $\mathbf{R}(\psi)$ is the rotation from body-fixed to Earth-fixed frame.
rotation_body_to_earth returns the $3 \times 3$ rotation matrix $\mathbf{R}(\psi)$, and kinematics computes $\dot{\boldsymbol{\eta}}$ for a given pose and velocity.
rotation_body_to_earth(ψ)returns the3×3rotation matrix $\mathbf{R}(\psi)$,kinematics(η, ν)computes $\dot{\boldsymbol{\eta}}$ for a given pose and velocity.
Full state dynamics
Combining kinematics and dynamics, the full state derivative is
\[\dot{\mathbf{X}} = [\dot{x}, \dot{y}, \dot{\psi}, \dot{u}, \dot{v}, \dot{r}]^T,\]
where
\[\dot{\boldsymbol{\eta}} = \mathbf{R}(\psi)\, \boldsymbol{\nu}, \qquad \dot{\boldsymbol{\nu}} = \mathbf{M}^{-1} \bigl( \boldsymbol{\tau} - \mathbf{C}(\boldsymbol{\nu}) \boldsymbol{\nu} - \mathbf{D}(\boldsymbol{\nu}) \boldsymbol{\nu} \bigr).\]
The body dynamics are computed by body_dynamics, and the full state derivative by vessel_dynamics, which splits the state into $\eta$ and $\nu$, applies the kinematics and dynamics, and returns the combined 6-element derivative.
body_dynamicscomputes (\dot{\boldsymbol{\nu}}),vessel_dynamicssplitsXinto(η, ν), computesη̇andν̇, and returns the full 6-element state derivative.
These functions are designed to be used directly with differential equation solvers and automatic differentiation, with Vessel3DOF as the concrete 3-DOF model type.