12. Moving objects

*In ComFLOW it is possible to insert moving objects into the flow domain that moves with a prescribed motion or moves interactively with the fluid. ComFLOW has the possibility to compute the motion of an object in a few different ways. These ways and necessary input files are described in this chapter. For complete examples have a look in the section ‘Examples’ of this documentation. *

Note

Warning: it is recommended to always let at least two cells separate the moving body from any fixed body. Once fixed and moving solids enter the same grid cell, the fixed solid can no longer be distinguished from the moving solid. In this case all solid in this cell will be considered as ‘moving’. Upon collision of fixed and moving objects a warning message is produced after which it is possible to continue the simulation.

12.1. Getting started

One or more objects can be included in the simulation. The properties of a moving object have to be specified in a special INI file, which is described in Section 12.6. The moving objects are listed in the XML key(s) /comflow/coupling/moving_objects/object[*]/. The following example inserts two moving objects for which the properties are stored in the files ${INPUT}/movingobject1.ini and ${INPUT}/movingobject2.ini.

<coupling>
    <moving_objects interaction_method="quasi_simultaneous">
        <object name="movingobject1" ini_file="${INPUT}/movingobject1.ini"/>
        <object name="movingobject2" ini_file="${INPUT}/movingobject2.ini"/>
    </moving_objects>
</coupling>

If ComFLOW detects the presence of moving objects, the solution algorithm is automatically adjusted. Various motion types are available, such as constant and accelerated motion, sinusoidal motion, custom time traces and interactive motion.

In order to distinguish moving and fixed parts of the geometry, an extra parameter is introduced in ${INPUT}/geometry.in to distinguish between moving and fixed building blocks. This is explained in Chapter 5. An intermediate file is created by GEODEF and stored at the location ${INTERMEDIATE}/geomoving.in. This file contains information for every cell if it is (partly) a fixed geometry, a moving geometry or completely open for fluid flow.

12.2. Conventions and notations

12.2.1. Position of the object

When defining motion of an object, it is very important to be consistent about the axis system and meaning of positive rotation angles. The coordinate system is right-handed. When the bow of a ship is pointing towards the positive x-axis, the positive angles are defined as follows:

  • positive roll means that the starboard side of the ship is going down,
  • positive pitch means that the bow of the ship is going down,
  • positive yaw means that the bow of the ship is turning to port side.

In mathematical notation, the transformation matrix is given as a product of the three rotation matrices that describe rotation around the three coordinate axes. The general rotation matrices for rotations around the x-, y- and z- axis are given by

\[\begin{split}R_x(\alpha) = \left( \begin{array}{ccc} 1 & 0 & 0 \\ 0 & \cos \alpha & -\sin \alpha \\ 0 & \sin \alpha & \cos \alpha \end{array} \right)\end{split}\]
\[\begin{split}R_y(\beta) = \left( \begin{array}{ccc} \cos \beta & 0 & \sin \beta \\ 0 & 1 & 0 \\ -\sin \beta & 0 & \cos \beta \end{array} \right)\end{split}\]
\[\begin{split}R_z(\gamma) = \left( \begin{array}{ccc} \cos \gamma & -\sin \gamma & 0 \\ \sin \gamma & \cos \gamma & 0 \\ 0 & 0 & 1 \end{array} \right)\end{split}\]

The matrix for general rotation, which is defined to be first yaw, then pitch, then roll, is then given by

\[\begin{split}\small \begin{multline} R(\alpha,\beta,\gamma) = R_x(\alpha)~R_y(\beta)~R_z(\gamma)=\\ \left(\!\!\!\! \begin{array}{ccc} \cos\beta \cos\gamma & -\cos \beta \sin \gamma & \sin \beta \\ \cos\gamma \sin\alpha \sin \beta + \cos \alpha \sin \gamma & \cos\alpha \cos\gamma - \sin \alpha \sin \beta \sin \gamma & -\cos\beta \sin\alpha \\ -\cos\alpha \cos \gamma \sin \beta + \sin \alpha \sin \gamma & \cos \gamma \sin \alpha + \cos \alpha \sin \beta \sin \gamma & \cos \alpha \cos \beta \end{array}\!\!\!\! \right) \end{multline}\end{split}\]

Any point on the object can be rotated around the center of gravity (CG) using

\[x = CG + R(\alpha,\beta,\gamma) (x_0-CG_0)\]

12.2.2. Pointwise velocities

The three velocity components of a point \(x_P\) in the object are given by \(u_{COM} + \omega \times x_P\), where \(u_{COM}=(u_{COM},v_{COM},w_{COM})\) contains the three linear velocity components and \(\omega\) is the angular velocity vector. When this is written out, the following formulas express the velocity components of the object at point \(x_P = (x_P,y_P,z_P)\):

\[\begin{split}\begin{eqnarray} u_{obj} & = & u_{\rm COM} + \omega_2 (z_P-z_{\rm COM}) - \omega_3 (y_P-y_{\rm COM}) \nonumber\\ v_{obj} & = & v_{\rm COM} + \omega_3 (x_P-x_{\rm COM}) - \omega_1 (z_P-z_{\rm COM}) \nonumber\\ w_{obj} & = & w_{\rm COM} + \omega_1 (y_P-y_{\rm COM}) - \omega_2 (x_P-x_{\rm COM}) \end{eqnarray}\end{split}\]

12.3. Prescribed motions

12.3.1. Constant and accelerated motion

When [motion]/type is set to constant, the object has a constant linear velocity and/or acceleration and a constant angular velocity. The constant velocity component can be specified in the key [motion]/velocity and the acceleration can be specified in the key [motion]/acceleration. Velocities consist of three linear components [m/s] and three angular velocities [deg/s].

Example:

[geometry]
identifier = 1

[motion]
type            = constant*                 ; all 6 DOF's are constant
position        = 0. 0.  0.    0. 0. 0.     ; m (x3), deg (x3)
velocity        = 0. 0. -1.    5. 0. 0.     ; m s^-1 (x3), deg s^-1 (x3)
acceleration    = 0. 0. -9.81  0. 0. 0.     ; m s^-2 (x3), deg s^-2 (x3)

In the example given above, the object will move in z-direction according to the formula \(x(t)=A\,t\,+\, B \,t^2\), where \(A=-1\) and \(B=-9.81\) and \(t\) the time in seconds. On top of this translational motion, the object is rotating around the x-axis with a constant angular velocity of 5 degrees per second.

12.3.2. Sinusoidal motion

When [motion]/type is set to sinusoidal, the object will follow a sinusoidal motion pattern around a given reference point.

[geometry]
identifier = 1

[motion]
type            = sinusoidal*                           ; all 6 DOF's are sinusoidal
position        = 0. 0. 0. 0. 0. 0.                     ; m (x3), deg (x3)
amplitude       = -1.4 -2.0 2.5 -0.035 -0.087 0.01      ; m s^-1 (x3), deg s^-1 (x3)
frequency       = 0.487 0.487 0.487 0.487 0.487 0.487   ; Hz (x6)
phase           = 319.7 291.6 1.146 151.8 236.1 308.3   ; deg (x6)

The motion is defined as follows:

\[\begin{split}\begin{eqnarray} x(t) & = & { x(0)} + { A_1}\; \cos\left(2\pi \left[f_1 t + \phi_1/360\right]\right) \nonumber\\ y(t) & = & { y(0)} + { A_2}\; \cos\left(2\pi \left[f_2 t + \phi_2/360\right]\right) \nonumber\\ z(t) & = & { z(0)} + { A_3}\; \cos\left(2\pi \left[f_3 t + \phi_3/360\right]\right) \nonumber\\ \alpha(t) & = & { \alpha(0)} + { A_4}\; \cos\left(2\pi \left[f_4 t + \phi_4/360\right]\right) \nonumber\\ \beta(t) & = & { \beta(0)} + { A_5}\; \cos\left(2\pi \left[f_5 t + \phi_5/360\right]\right) \nonumber\\ \gamma(t) & = & { \gamma(0)} + { A_6}\; \cos\left(2\pi \left[f_6 t + \phi_6/360\right]\right) \nonumber\\ \end{eqnarray}\end{split}\]

Note that the sinusoidal motion is centered around the initial position as specified in [motion]/position. The actual starting point of the motion may be adjusted by modifying the phase in [motion]/phase.

Velocities and accelerations of the object are then determined upon differentiation, for example:

\[\begin{split}\begin{equation*} u(t) = - 2\pi f_1 \; { A_1} \;\sin\left(2\pi \left[f_1 t + \phi_1/360\right]\right)\\ \end{equation*}\end{split}\]

For smooth startup of the simulation it is recommended to select an initial time (or phase shift) that corresponds with a small velocity.

12.3.3. Motion prescribed by time traces

The object’s motion can also be described in a completely general way by means of time traces. For a general motion, the time traces of (linear and angular) position and velocities are required. In principle it is possible to derive the velocities from the positions automatically, but in practice this can lead to numerical problems if the position time trace is not very smooth. Therefore, both positions and velocities should be given by the user.

The following example illustrates the basic setup for motion by time trace input:

[geometry]
identifier = 1

[motion]
type    = timetrace*                            ; time trace for all 6 DOF's
file    = ${INPUT}/motiondata_for_object1.in    ; location of the time trace file
angles  = degrees                               ; angles in degrees or radians

The input file for the motion time trace must provide ASCII tabular data consisting of 13 columns:

  • column 1: time instants [s]
  • columns 2-4: x-, y- and z- coordinate of the rotation point [m]
  • columns 5-7: rotation angles of the object: roll, pitch and yaw [deg | rad]
  • columns 8-10: linear velocities of the rotation point in x-, y- and z- direction [m/s]
  • columns 11-13: angular velocities around the rotation point [deg/s | rad/s]

Please take care that the maximum simulation time does not exceed the maximum time of the time trace.

12.4. Interactive body motion

ComFLOW also has the possibility to simulate fully interactive body motion. A 6-DOF rigid-body model is solved simultaneously with the flow equations which allows for fast solution. Spring, damping and inertia forces may be specified to further customize the object (motion) properties.

The following example illustrates the setup of a fully interactively moving object:

[geometry]
identifier  = 1
origin      = 10. 0. 0.                     ; m (x3)

[motion]
type        = interactive*                  ; all 6 DOF's are interactive
position    = 0. 0. -0.5  0. 5. 23.         ; m (x3), deg (x3)
velocity    = 0. 0.  0.   0. 0.  0.         ; m s^-1 (x3), deg s^-1 (x3)

[inertia]
mass        = 80754e3                       ; kg
J11         = 43.6                          ; m (radius of inertia for roll)
J22         = 46.2                          ; m (radius of inertia for pitch)
J33         = 46.2                          ; m (radius of inertia for yaw)

[forcing]
file        = ${INPUT}/external_force1.in   ; file with time trace of external force

[spring]
linear      =                               ; N m^-1 (x3), Nm deg^-1 (x3)
quadratic   =                               ; N m^-2 (x3), Nm deg^-2 (x3)
pretension  =                               ; N (x3), Nm (x3)
equilibrium =                               ; m (x3), deg (x3)
;;file      = ${INPUT}/spring.in            ; file with legacy input (deprecated)

[damping]
linear      =                               ; Ns m^-1 (x3), Ns deg^-1 (x3)
quadratic   =                               ; Ns^2 m^-2 (x3), Ns^2 deg^-2 (x3)
;;file      = ${INPUT}/damping.in           ; file with legacy input (deprecated)

The section [inertia] describes the mass and inertia properties of the object and must always be specified. Other sections such as [forcing], [spring] and [damping] are optional.

12.4.1. Forcing

The file for external forces as specified in [forcing]/file contains a time trace of external forces for each of the 6DOF’s. These can for example be used to give the object a push at the start of the simulation and perform a decay test. The file contains 7 columns:

  • column 1: \(t [s]\)
  • column 2: \(Fx [N]\)
  • column 3: \(Fy [N]\)
  • column 4: \(Fz [N]\)
  • column 5: \(Mx [Nm]\)
  • column 6: \(My [Nm]\)
  • column 7: \(Mz [Nm]\)

The maximum time in this file should be larger than or equal to the ComFLOW simulation time. An example, with initial heave force to simulate a heave decay, is as follows:

0.   0. 0. 4000.E3 0. 0. 0.
2.   0. 0. 4000.E3 0. 0. 0.
2.1  0. 0. 0.      0. 0. 0.
100. 0. 0. 0.      0. 0. 0.

12.4.2. Spring

For backwards compatibility it is still possible to provide the spring properties in a separate input file at the location specified by [spring]/file. This file contains the pretension and (6x6) stiffness matrices (linear C_1, quadratic C_2 and cubic C_3) of a possible mooring system. This file is optional. The mooring force is computed as

\[F_{moor} = \mbox{Pretension} - {C_1}{\bf x}-{C_2}{{\bf x}^2}-{C_3}{{\bf x}^3},\]

where \({\bf x}\) is the motion vector of the body containing the three translations of the center of mass and the three rotations, \({\bf x}^2\) is the element-wise square of the motion vector, etc. This file contains 19 lines:

  • line 1: pretension forces and moments at the center of mass (6 numbers):

    \[Fx [N], Fy [N], Fz [N], Mx [Nm], My [Nm], Mz [Nm]\]

  • lines 2-7: linear spring matrix C_1 (1 row per line)

  • lines 8-13: quadratic spring matrix C_2 (1 row per line)

  • lines 14-19: cubic spring matrix C_3 (1 row per line)

An example is as follows:

0.       0.       -360.0E6 0.       0.       0.
1339.0E3 0.       0.       0.       0.       0.
0.       1339.0E3 0.       0.       0.       0.
0.       0.       1064.0E6 0.       0.       0.
0.       0.       0.       1.37E12  0.       0.
0.       0.       0.       0.       1.37E12  0.
0.       0.       0.       0.       0.       4659649.0E3
0.       0.       0.       0.       0.       0.
0.       0.       0.       0.       0.       0.
0.       0.       0.       0.       0.       0.
0.       0.       0.       0.       0.       0.
0.       0.       0.       0.       0.       0.
0.       0.       0.       0.       0.       0.
0.       0.       0.       0.       0.       0.
0.       0.       0.       0.       0.       0.
0.       0.       0.       0.       0.       0.
0.       0.       0.       0.       0.       0.
0.       0.       0.       0.       0.       0.
0.       0.       0.       0.       0.       0.

It should be noted that the weight of the body (Mass x g), the buoyancy force (computed by ComFLOW) and the mooring pretension should be in balance, to avoid large accelerations at the start of the ComFLOW simulation.

12.4.3. Damping

For backwards compatibility it is still possible to provide the spring properties in a separate input file at the location specified by [damping]/file. This file contains additional linear and quadratic damping coefficients for all 6 motion modes. The file has 6 lines:

  • line 1: linear damping \([Ns/m]\) and quadratic damping \([Ns^2/m^2]\) for surge
  • line 2: linear damping \([Ns/m]\) and quadratic damping \([Ns^2/m^2]\) for sway
  • line 3: linear damping \([Ns/m]\) and quadratic damping \([Ns^2/m^2]\) for heave
  • line 4: linear damping \([Nms/rad]\) and quadratic damping \([Nms^2/rad^2]\) for roll
  • line 5: linear damping \([Nms/rad]\) and quadratic damping \([Nms^2/rad^2]\) for pitch
  • line 6: linear damping \([Nms/rad]\) and quadratic damping \([Nms^2/rad^2]\) for yaw

An example is as follows:

100.0E3 0.
100.0E3 0.
0.      0.
1000.E3 10000.E3
0.      0.
0.      0.

12.4.4. Symmetry planes

A moving body can be positioned at any symmetry plane. In this case the forces acting on the object are symmetrically continued and forces normal to the symmetry plane are assumed to be equal to zero.

12.5. Output files

12.5.1. motion####.bin

For each object included in the simulation a file ${OUTPUT}/motion####.bin is generated, which monitors the linear and angular motions. This file contains binary tabular data consisting of 7 columns. All values are stored as 64-bits floating point values. The following MATLAB code reads the contents of the file into a 7-column array:

numcol = 7;

fid = fopen(fnm,'r');
if fid==-1
    error('File %s not found',fnm);
end
dat = fread(fid,Inf,'float64');
fclose(fid);

dat = reshape(dat,[numcol,numel(dat)/numcol])';

12.5.2. interactive_motion####.dat

More detailed output, including fluid and external forces, is stored in the ASCII output files ${OUTPUT}/interactive_motion####.dat. Unlike their names suggest, these files are also stored for non-interactive motion. The contents consists of 25 columns:

  • column 1: time [s]
  • columns 2-4: linear forces exerted by the fluid [N]
  • columns 5-7: angular forces exerted by the fluid [Nm]
  • columns 8-10: external linear forcing [N]
  • columns 11-13: external angular forcing [Nm]
  • columns 14-16: linear position [m]
  • columns 17-19: angular position [deg]
  • columns 20-22: linear velocity [m s^-1]
  • columns 23-25: angular velocity [deg s^-1]

Note that in this file angles and angular velocities are in [deg] and [deg/s] instead of [rad] and [rad/s]. The ComFLOW forces contain the fluid forces and the weight of the body. The forces in columns 8-13 contain the spring, damping and external forces.

12.5.3. Output frame

By default the motion data is stored with respect to the motion reference frame (a.k.a. “ship-fixed-t0”) as described in the input [motion]/reference. When including multiple moving objects or when using sub-objects with moving reference frames it may in some cases be more practical to store all motions with respect to the earth-fixed frame. This can be realized by setting the XML option /comflow/output/motion/@earth_fixed="true".

12.6. The INI input format

In this section all settings for moving objects are listed. Each section allows to specify a reference frame in which the variables of that section are expressed. This is necessary to distinguish between the input coordinates (provided in geometry.in), simulation coordinates (earth-fixed inertial frame) or object coordinates (frame moving with the ship). The details are specified per section.

12.6.1. [geometry]

The settings in this section are only used to define the geometry. By default the origin of the geometry definition is located at (0,0,0) in input coordinates, but this behavior may be overruled. It is recommended to let the origin coincide with the object’s center of mass since this prevents the need of additional coordinate transformations afterwards. The reference frame specifies the object frame in terms of input coordinates.

Property Description Units/format
origin origin of the geometry definition m (x3)
reference origin and rotation of the geometry definition m (x3), deg (x3)

12.6.2. [motion]

This input section can be used to adjust the motion reference frame (a.k.a. the “ship-fixed-t0” frame), specify the motion type (per DOF) and to specify the initial conditions. The reference frame specifies the object frame in simulation coordinates, or relative to another object if in_frame_of is defined. This is the location of the ship when all position degrees-of-freedom are zero.

Property Description Units/format
type specify the motion type per DOF, or add an asterisk to set all 6 DOF’s at once (none|constant|sinusoidal|timetrace|interactive)* or 6 times (none|constant|sinusoidal|timetrace|interactive)
reference reference frame for motion input and output m (x3), deg (x3)
position initial position of the object m (x3), deg (x3)
velocity initial velocity of the object m s^-1 (x3), deg s^-1 (x3)
amplitude amplitude of sinusoidal motion (ignored otherwise) m s^-1 (x3), deg s^-1 (x3)
frequency frequency of sinusoidal motion (ignored otherwise) Hz (x6)
phase phase shift of sinusoidal motion (ignored otherwise) deg (x6)
file location of time trace file (ignored if none of the motion types equals “timetrace”) absolute or relative path
angles time trace input based on radians or degrees (only used for time trace input) (radians|degrees)
in_Frame_of define motion frame with respect to position of another object object identifier (or 0 to disable)
prescribed_until transition time from prescribed to interactive motion specified per DOF s (x6)
elastic enable or disable elastic deformation (true|false)

12.6.3. [forcing]

This input section can be used to define external forcing. These settings are only relevant if at least one DOF is interactive. The reference frame specifies the point-of-action of external forces and their orientation in object coordinates (moving with the ship).

Property Description Units/format
file location of file with external forces absolute or relative path
reference reference frame for external forces m (x3), deg (x3)

12.6.4. [inertia]

This input section can be used to define inertia properties of the moving object. These settings are only relevant if at least one DOF is interactive. The reference frame specifies the center-of-mass and the orientation of the (principal) axes of inertia in object coordinates (moving with the ship). If principal axes are used, the inertia matrix will be diagonal.

Property Description Units/format
mass object mass kg
J11, J22, J33 radii of inertia for roll, pitch and yaw, respectively m
J12, J13, J23 off-diagonal part of the inertia matrix m
reference reference frame for inertia properties m (x3), deg (x3)

12.6.5. [spring]

This input section can be used to define a spring. These settings are only relevant if at least one DOF is interactive. The reference frame specifies the point-of-action of the resultant spring forces in object coordinates, and the orientation of the (principal) axes for spring forces and displacements. If principal axes are used, the spring matrix will be diagonal.

Property Description Units/format
linear linear properties N m^-1 (x3), Nm deg^-1 (x3)
quadratic quadratic properties N m^-2 (x3), Nm deg^-2 (x3)
equilibrium equilibrium position and rotation m (3x), deg (3x)
pretension pretension N (3x), Nm (3x)
reference reference frame for spring properties specified m (x3), deg (x3)
file deprecated location of file with spring properties absolute or relative path

12.6.6. [damping]

This input section can be used to define damping. These settings are only relevant if at least one DOF is interactive. The reference frame specifies the point-of-action of the resultant damping forces in object coordinates, and the orientation of the (principal) axes for damping forces and velocities. If principal axes are used, the damping matrix will be diagonal.

Property Description Units/format
linear linear properties Ns m^-1 (x3), Ns deg^-1 (x3)
quadratic quadratic properties Ns^2 m^-2 (x3), Ns^2 deg^-2 (x3)
reference reference frame with respect to which all damping properties are specified m (x3), deg (x3)
file deprecated location of file with damping properties absolute or relative path

12.6.7. [transform]

In this section an additional coordinate transformation can be specified, which is applied to all reference frames that have been defined in the other input sections.

Only use this section if really needed, please take into consideration the following recommendations:

  • For realigning the origin and/or orientation of the geometry definition it is recommended to adjust the properties [geometry]/{origin, reference} or, if not possible otherwise, to adjust the property [inertia]/reference.
  • For setting the initial position and orientation of the object use [motion]/position instead.
Property Description Units/format
reference reference frame m (x3), deg (x3)
exclude do not apply the transformation to the specified category; only use this advanced option if really needed (motion|forcing|inertia|spring|damping)