Skip to content

Commit

Permalink
finish doc updates and fix typos, equations, etc
Browse files Browse the repository at this point in the history
  • Loading branch information
@akeeste
akeeste committed May 31, 2023
1 parent 4ae6d27 commit dd42c99
Showing 1 changed file with 37 additions and 36 deletions.
73 changes: 37 additions & 36 deletions docs/_include/added_mass.rst
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
.. _dev-added-mass:

Theoretical Implementation
^^^^^^^^^^^^^^^^^^^^^^^^^^

Added mass is a special multi-directional fluid dynamic phenomenon that most
physics software cannot account for well.
Modeling difficulties arise because the added mass force is proportional to acceleration.
Expand Down Expand Up @@ -30,47 +33,48 @@ In this case, the adjusted body mass matrix is defined as the sum of the transla
A_{6,1} & A_{6,2} & A_{6,3} & I_{3,1} + A_{6,4} & I_{3,2} + A_{6,5} & I_{3,3} + A_{6,6} \\
\end{bmatrix}

This formulation is desirable because it removes the acceleration dependence from the right hand side of the equation.
Without this treatment, the acceleration creates an unsolvable algebraic loop.
This formulation is desirable because it removes the acceleration dependence from the right hand side of the governing equation.
Without this treatment, the acceleration causes an unsolvable algebraic loop.
There are alternative approximations to solve the algebraic loop, but simulation robustness and stability become increasingly difficult.

The core issue with this combined mass formulation is that Simscape Multibody, and most other physics software, do not allow a generic body to have a degree-of-freedom specific mass.
For example, a rigid body can't have one mass for surge motion and another mass for heave motion.
Simscape rigid bodies are only allowed to have one translational mass, a 1x3 moment of inertia matrix, and 1x3 product of inertia matrix.
Simscape rigid bodies only have one translational mass, a 1x3 moment of inertia matrix, and 1x3 product of inertia matrix.

WEC-Sim's Implemenation
^^^^^^^^^^^^^^^^^^^^^^^

Due to this limitation, WEC-Sim cannot combine the mass and added mass on the left-hand side of the equation of motion (as shown above).
Due to this limitation, WEC-Sim cannot combine the body mass and added mass on the left-hand side of the equation of motion (as shown above).
The algebaric loop can be solved by predicting the acceleration at the current time step, and using that to calculate the added mass force.
But this method can cause numerical instabilities.
Instead, WEC-Sim decreases the added mass force magnitude by moving *some* components of added mass into the body mass, while a modified added mass force is calculated with the remainder of the added mass coefficients.

There is a 1-1 mapping between the body's inertia tensor and rotational added mass coefficients.
These added mass coefficients are entirely lumped with the body inertia.
These added mass coefficients are entirely lumped with the body's inertia.
Additionally, the surge-surge (1,1), sway-sway (2,2), heave-heave (3,3) added mass coefficients correspond to the translational mass of the body, but must be treated identically.

WEC-Sim implements this added mass treatment using a modified added mass matrix and modified body mass matrix:
WEC-Sim implements this added mass treatment using both a modified added mass matrix and a modified body mass matrix:

.. math::

M\ddot{X_i} &= \Sigma F(t,\omega) - A\ddot{X_i} \\
(M+dMass)\ddot{X_i} &= \Sigma F(t,\omega) - (A-dMass)\ddot{X_i} \\
M_{adjusted}\ddot{X_i} &= \Sigma F(t,\omega) - A_adjusted\ddot{X_i} \\
M_{adjusted}\ddot{X_i} &= \Sigma F(t,\omega) - A_{adjusted}\ddot{X_i} \\

where :math:`dMass` is the difference in added mass and is defined as:
where :math:`dMass` is the change in added mass and defined as:

.. math::

dMass &= \begin{bmatrix}
\alpha Y & 0 & 0 & 0 & 0 & 0 \\
0 & \alpha Y & 0 & 0 & 0 & 0 \\
0 & 0 & \alpha Y & 0 & 0 & 0 \\
0 & 0 & 0 & A{4,4} & -A{5,4} & -A{6,4} \\
0 & 0 & 0 & A{5,4} & A{5,5} & -A{6,5} \\
0 & 0 & 0 & A{6,4} & A{6,5} & A{6,6} \\
\end{bmatrix}

\alpha Y & 0 & 0 & 0 & 0 & 0 \\
0 & \alpha Y & 0 & 0 & 0 & 0 \\
0 & 0 & \alpha Y & 0 & 0 & 0 \\
0 & 0 & 0 & A{4,4} & -A{5,4} & -A{6,4} \\
0 & 0 & 0 & A{5,4} & A{5,5} & -A{6,5} \\
0 & 0 & 0 & A{6,4} & A{6,5} & A{6,6} \\
\end{bmatrix} \\
Y &= (A_{1,1} + A_{2,2} + A_{3,3}) \\

\alpha = body(iBod).adjMassFactor
\alpha &= body(iBod).adjMassFactor

The resultant definition of the body mass matrix and added mass matrix are then:

Expand All @@ -80,50 +84,47 @@ The resultant definition of the body mass matrix and added mass matrix are then:
m + \alpha Y & 0 & 0 & 0 & 0 & 0 \\
0 & m + \alpha Y & 0 & 0 & 0 & 0 \\
0 & 0 & m + \alpha Y & 0 & 0 & 0 \\
0 & 0 & 0 & I_{4,4} + A{4,4} & -(I_{5,4} + A{5,4}) & -(I_{6,4} + A{6,4}) \\
0 & 0 & 0 & I_{5,4} + A{5,4} & I_{5,5} + A{5,5} & -(I_{6,5} + A{6,5}) \\
0 & 0 & 0 & I_{6,4} + A{6,4} & I_{6,5} + A{6,5} & I_{6,6} + A{6,6} \\
\end{bmatrix}

0 & 0 & 0 & I_{4,4} + A_{4,4} & -(I_{5,4} + A_{5,4}) & -(I_{6,4} + A_{6,4}) \\
0 & 0 & 0 & I_{5,4} + A_{5,4} & I_{5,5} + A_{5,5} & -(I_{6,5} + A_{6,5}) \\
0 & 0 & 0 & I_{6,4} + A_{6,4} & I_{6,5} + A_{6,5} & I_{6,6} + A_{6,6} \\
\end{bmatrix} \\
A_{adjusted} &= \begin{bmatrix}
A_{1,1} - \alpha Y & A_{1,2} & A_{1,3} & A_{1,4} & A_{1,5} & A_{1,6} \\
A_{2,1} & A_{2,2} - \alpha Y & A_{2,3} & A_{2,4} & A_{2,5} & A_{2,6} \\
A_{3,1} & A_{3,2} & A_{3,3} - \alpha Y & A_{3,4} & A_{3,5} & A_{3,6} \\
A_{4,1} & A_{4,2} & A_{4,3} & 0 & A_{4,5} + A{5,4} & A_{4,6} + A{6,4} \\
A_{5,1} & A_{5,2} & A_{5,3} & 0 & 0 & A_{5,6} + A{6,5} \\
A_{4,1} & A_{4,2} & A_{4,3} & 0 & A_{4,5} + A_{5,4} & A_{4,6} + A_{6,4} \\
A_{5,1} & A_{5,2} & A_{5,3} & 0 & 0 & A_{5,6} + A_{6,5} \\
A_{6,1} & A_{6,2} & A_{6,3} & 0 & 0 & 0 \\
\end{bmatrix}
\end{bmatrix}

.. Note::
:math:`A_{4,5} + A{5,4}`, etc should be equal to zero, but numerical differences in the added mass coefficients are preserved.
We should see that :math:`A_{4,5} + A_{5,4} = A_{4,6} + A_{6,4} = A_{5,6} + A_{6,5} = 0`, but there may be numerical differences in the added mass coefficients which are preserved.

Though the components of added mass and body mass are varied, the total system is unchanged.
This manipulation does not affect the governing equation of motion, only its implementation.
Though the components of added mass and body mass are manipulated in WEC-Sim, the total system is unchanged.
This manipulation does not affect the governing equations of motion, only the implementation.

The fraction of translational added mass that is moved into the body mass is determined by ``body(iBod).adjMassFactor``, whose default value is :math:`2.0`.
This weighting factor can be changed in the ``wecSimInuptFile`` to create the most robust simulation possible.
To see its effects, set ``body(iB).adjMassFactor = 0`` and see how simulations become unstable.
Advanced users may change this weighting factor in the ``wecSimInuptFile`` to create the most robust simulation possible.
To see its effects, set ``body(iB).adjMassFactor = 0`` and see if simulations become unstable.

This manipulation does not move all added mass components.
WEC-Sim still contains an algebraic loop due to the acceleration dependence of the remaining added mass force from :math:`A_{adjusted}`, and components of the Morison Element force.
WEC-Sim solves the algebraic loop using a `Simulink Transport Delay <https://www.mathworks.com/help/simulink/slref/transportdelay.html>`_ with a very small time delay (``1e-8``).
This blocks extrapolates the previous acceleration by ``1e-8`` seconds.
The small extraplation solves the algebraic loop but prevents large errors that arise when extrapolating the acceleration over a time step.
This blocks extrapolates the previous acceleration by ``1e-8`` seconds, which results in a known acceleration for the added mass force.
The small extraplation solves the algebraic loop but prevents large errors that arise when extrapolating the acceleration over an entire time step.
This will convert the algebraic loop equation of motion to a solvable one:

.. math::

M_{adjusted}\ddot{X_i} &= \Sigma F(t,\omega) - A_{adjusted}\ddot{X}_{i - (1 + 10^{-8}/dt)} \\

The acceleration used for the added mass is now known: a ``1e-8`` second extrapolation of acceleration at the previous time step (:math:`i-1`).

This implementation should not affect a user's modeling workflow.
WEC-Sim handles the manipulation and restoration of the mass and forces in the bodyClass functions ``adjustMassMatrix()`` called by ``initializeWecSim`` and ``restoreMassMatrix``, ``storeForceAddedMass`` called by ``postProcessWecSim``.
However viewing ``body.mass, body.inertia, body,inertiaProducts, body.hydroForce.fAddedMass`` between calls to ``initializeWecSim`` and ``postProcessWecSim`` will not show the input file definitions.
Users can get the manipulated mass matrix, added mass coefficients, added mass force and total force from ``body.hydroForce.storage`` after the simulation.
However, in the rare case that a user wants to manipulate the added mass force *during* a simulation, the change in mass, :math:`dMass` above, must be taken into account. Refer to how ``body.calculateForceAddedMass()`` calculates the entire added mass force in WEC-Sim post-processing.

.. Note:: If applying the method in ``body.calculateForceAddedMass()`` *during* the simulation, the negative of ``dMass`` must be taken: :math:`dMass = -dMass`. This must be accounted for because the definitions of mass, inertia, etc and their stored values are flipped between teh simulation and post-processing.
.. Note:: If applying the method in ``body.calculateForceAddedMass()`` *during* the simulation, the negative of ``dMass`` must be taken: :math:`dMass = -dMass`. This must be accounted for because the definitions of mass, inertia, etc and their stored values are flipped between simulation and post-processing.

.. Note::
Depending on the wave formulation used, :math:`A` can either be a function of wave frequency :math:`A(\omega)`, or equal to the added mass at infinite wave frequency :math:`A_{\infty}`

0 comments on commit dd42c99

Please sign in to comment.