Use of STAMOD

The main purpose of STAMOD is to read and check the system description from SYSFIL and to write those data to a direct access file, INIFIL, which will be used in DYNMOD and OUTMOD. This file contains a complete system description, definition of the environment to be applied and the initial positions for dynamic simulation.

 I->  STAMOD main menu
 I
 I      1 : Read system description file
 I      2 : Read initial condition file
 I      3 : Modify/present system
 I      4 : Print static condition
 I      5 : Equilibrium calculation
 I      6 : Eigen value calculation
 I      7 : Mooring system optimization
 I      8 : Write initial condition file
 I      9 : Write file for visualisation
 I     99 : Terminate
 I
 I->  Select option >

1. Read system description file

The SYSFIL is an ASCII file containing a complete description of the system to be analysed. For a brief description of the sys-file layout and file syntax, see System Description File. A detailed description of the file contents is given in Appendix A.

The SYSFIL is read twice, the first time only to find dimensioning parameters for the work array, the second time to put all data into the work array.

If an error occurs, messages will be written both on the print file and in some cases also on the terminal. Error messages on the print file are found by searching for the string * ERROR from the beginning of the file. If a non-fatal error is encountered, reading of SYSFIL will continue until the maximum number of errors are found.

If errors are found during the first scan of SYSFIL and the print file does not give any meaningful indications on the problem, the amount of output to the printfile can be increased by the MAIS-command @ FILE 5.

1.1. Symmetry codes

Wind force coefficients, current force coefficients, wave drift force coefficients and transfer functions are given as functions of directions relative to the body.

In the calculations, extrapolation on directions are not allowed. In order to avoid problems with program termination due to attempted extrapolation, it is advised that both 0 degrees and 360 degrees should be represented in the range of directions on the input file.

If symmetry codes are used, this will automatically be taken care of. For example, if symmetry code is 2 and the directions 20 degrees and 70 degrees are specified, they will be mirrored to -20, 20, 70, 110, 160, 200, 250, 290, 340 and 380 degrees.

NB: It is strongly advised that values are specified for the symmetry lines. For the example above, 0 deg and 90 deg should also be included as input.

2. Read initial condition file

An INIFIL that has been written by STAMOD during the present or a previous run may be read. If no changes have been made to the system as defined on SYSFIL, this is an alternative which is much faster than reading SYSFIL.

3. Modify / Present system

The menu for system modification is:

 I->  STAMOD modify/present system
 I
 I      0 : Return
 I      1 : Select environment
 I      2 : Initial positions
 I      3 : Eliminate degrees of freedom
 I      4 : Positioning system
 I      5 : Restoring force (incl. environmental forces)
 I      6 : Dynamic positioning
 I
 I->  Select option >

3.1. Select environment

Several regular and irregular wave conditions, current conditions and wind conditions may be defined on SYSFIL (or INIFIL). The default wave condition will be the present condition. If no condition has been selected, the first one defined on SYSFIL will be the default. Waves, current and wind can be removed individually.

3.2. Initial positions

New initial positions for all bodies may be specified. Present positions will be default.

3.3. Eliminate degrees of freedom

3.3.1. Eliminate local degrees of freedom

Elimination of degrees of freedom is implemented by setting the corresponding local acceleration components to zero during time domain simulation (DYNMOD) and equilibrium iteration (STAMOD, when using "Transient" algorithm).

3.3.2. Eliminate global degrees of freedom

This option only affect the static equilibrium calculation if the Newton-Raphson method is used. It does not affect the dynamic analysis.

Elimination of global degrees of freedom is implemented by excluding the desired translations/rotations about the axes of the XGB coordinate system when computing the equilibrium position.

For user-friendlyness purpose, when restraining the rotational degrees of freedom, the following combinations are not unavailable:

  • restraining rotation about X-axis only

  • restraining rotation about the Y-axis only

Those limitations are implemented to avoid confusing the user since for example, a rotation about Y-axis combined with a rotation about the Z-axis can actually trigger a change in roll angle (although the rotation about the X-axis is locked). Restraining the rotation about the Z-axis only is made available since it is directly equal to the yaw angle of a body; the result is thus easier to understand for the user.

3.4. Positioning system

The initial tension may be changed. This is done by moving the anchor position. Print of positioning element locations and plot/print of line characteristics are available. It is also possible to get the line profile printed at the prs-xxx.lis file. To obtain this, the parameter ICPRO in data group CATENARY SYSTEM DATA has to be set to 1. In addition, the user has to give the macro file command @RESU 5 before command 9 : Write file for visualization is given.

3.5. Restoring forces

The horizontal restoring force for translation in any direction or rotation may be specified. Output is presented on plots and tables.

3.6. Dynamic positioning

The following data may be modified:

  • Reference position and heading, including the point on the body to be positioned

  • Start value on bias forces that are not measured. If static forces have been calculated, the default values will be updated.

  • Kalman filter data or PID controller data

4. Print static condition

Initial positions for all bodies will be written to the terminal (standard output) and, if selected also to the print file.

Static forces acting on bodies are written to the terminal and optionally to the print file. The following forces are presented:

  • Average wave drift force calculated for the present heading, including wave-current interaction if specified

  • Wind force (linear interpolation between directions)

  • Current drag force based on linear and quadratic current coefficients (linear interpolation between directions)

  • Munk moment caused by current velocity and different magnitude of added mass specified in individual degree of freedom

  • Positioning element forces

  • Thruster forces

  • Coupling element forces

  • Forces from general line systems

  • Hydrostatic stiffness force

  • Gravity and buoyancy forces, also including small volume hydrodynamic force with wave particle velocities and accelerations set to zero. The forces contain contributions from current, gravity force and any static soil reaction forces.

  • Gravity forces due to time dependent added mass at time zero

  • Gravity and buoyancy force on slender elements and fixed body elements

  • Current drag forces acting on slender elements and fixed body elements

  • Specified forces at time equal to zero

  • External forces, i.e. forces from any special force subroutines linked into the program

If a dynamic positioning system is defined, thrust demand will be calculated according to the thrust demand equation.

5. Equilibrium calculation

The user can choose between two different algorithm in order to compute the equilibrium position of the system: transient method or Newton-Raphson method.

5.1. Transient method

This method is the most robust method, especially in case of systems with several bodies, and/or with strong non-linearities (like fenders, DP systems, …). It is recommended to use the "transient" method as the default method.

The following parameters are specified interactively:

  • \(\mathrm {T}\): Typical (maximum) natural period

  • \(\mathrm {\delta x}\): Position tolerance

  • \(\mathrm {\delta \alpha }\): Direction tolerance

  • \(\mathrm {\delta t}\): Time step

From position and direction tolerances, the following tolerances for velocities and acceleration are calculated:

  • \(\mathrm {\omega =2\pi /T}\)

  • \(\mathrm {\delta \dot {x}=\omega \delta x}\)

  • \(\mathrm {\delta \dot {\alpha }=\omega \delta \alpha }\)

  • \(\mathrm {\delta \ddot {x}=\omega ^2\delta x}\)

  • \(\mathrm {\delta \ddot {\alpha }=\omega ^2\delta \alpha }\)

By default, critical damping for each degree of freedom can be calculated:

\[c_i=2M_i\omega ,\quad i=1,6\]

where \(\mathrm {M_i}\) are the diagonal elements of the total mass matrix.

The equilibrium condition is found by stepping the equations of motion. The following force models will be included (if they are defined):

  • "Critical damping" force

  • Modified retardation function force, \(\mathrm {F_{ij}=4\Delta t\:h_{ij}(0)\dot {x}_j}\)

  • Hydrostatic stiffness force

  • Linear damping force

  • Quadratic damping force

  • Wind force (linear interpolation between directions)

  • Linear and quadratic current drag force (linear interpolation between directions)

  • Average wave drift force. The force will be calculated for the instantaneous heading the first and last time step. For other steps, corrections for instantaneous heading are done using first derivatives.

  • Small volume hydrodynamic force, wave particle velocities are set to zero.

  • Coupling element forces

  • Specified forces for t = 0.

  • Positioning element forces

  • Thruster forces.

If a dynamic positioning system is defined, the thruster forces are calculated from the thruster allocation algorithm described in the Theory Manual. The thrust demand is

\[F_{d,i}=\delta x_iG_{il}F_{wi,i}F_{wa,i}F_{cu,i}F_{li,i}F_{co,i}\:,\quad i=1,2,6\]

where

  • \(\mathrm {\delta x_i}\): Positioning error in local coordinate system

  • \(\mathrm {G_{il}}\): Position and heading gains in linear controller matrix

  • \(\mathrm {F_{wi}}\): Static wind force

  • \(\mathrm {F_{wa}}\): Static wave drift force

  • \(\mathrm {F_{cu}}\): Current force

  • \(\mathrm {F_{li}}\): Positioning element force

  • \(\mathrm {F_{co}}\): Coupling force

The equations of motion are stepped the specified number of steps with the modified Euler algorithm. At the last step, relative position and direction "errors" are calculated as:

\[\displaystyle \varepsilon _1=\mathrm {max}( |\frac{\dot {x_i}}{\delta \dot {x}}|,|\frac{\ddot {x_i}}{\delta \ddot {x}}| ),\quad i=1,2,3\]

\(\displaystyle \varepsilon _2=\mathrm {max}( |\frac{\dot {x_i}}{\delta \dot {\alpha }}|,|\frac{\ddot {x_i}}{\delta \ddot {\alpha }}| ),\quad i=4,5,6\)

"Equilibrium position" is found when both \(\mathrm {\varepsilon _1}\) and \(\mathrm {\varepsilon _2}\) are less than 1.

Note that initial positions are updated when calculation of equilibrium is selected, even if equilibrium position is not found.

It is advised to check the equilibrium position by calculating static forces and printing new initial positions.

5.2. Newton-Raphson method

This method is generally faster when considering a system with only one body. The calculation is based on a linearized model of the system:

  • the force vector is evaluated at the position of the system

  • the stiffness matrix of the system is calculated using excursions values specified by the user

  • the position of the system is corrected according to the force vector and the stiffness matrix computed previously

  • the algorithm iterates until the values of the force vector are smaller than the force/moment tolerance values specified by the user. The corresponding position is then validated as the equilibrium position.

The system is solved using the coordinate systems XGB for each body, which allows the user to restrain "global" degrees of freedom (see Elimination of global degrees of freedom), which is often more convenient than restraining local degrees of freedom.

Multiple equilibrium calculations

This option is only available when using SIMO in SIMA.

When using the Newton-Raphson method, the user can use the option "Multiple equilibrium calculations". The user has to specify a body to analyse and a grid of roll and pitch values. For each point of the grid, SIMO will compute the equilibrium of the system, applying the roll and pitch values of the grid point to the desired body and locking its rotations about the X- and Y-axes of the XGB coordinate system. The results of each calculation (position and total force) can be found in the prs.lis file, but is not available directly in SIMA in the present version. This will be updated in a future version of SIMO/SIMA.

The grid of roll and pitch values can be given in terms of:

  • roll and pitch values

  • azimuth vector components: the azimuth vector X- and Y-components are given in the body-related coordinate system XR. The Z-component of the azimuth vector is always zero. The direction of the azimuth vector define the axis of rotation. The norm of the azimuth vector defines the magnitude of the rotation about the axis of rotation. The body is rotated about the rotation axis and the resulting roll and pitch values are used for the analysis at that grid point. The resulting yaw is ignored.

  • azimuth angle and rotation angle: the azimuth angle is the angle between the rotation axis and the X-axis of the XR coordinate system of the body. It defines the direction of the rotation axis. The body is rotated about the rotation axis and the resulting roll and pitch values are used for the analysis at that grid point. The resulting yaw is ignored.

In practice, this option can be used to quickly identify if an equilibrium position found by a static calculation is stable or unstable. For example, let’s assume that the user has run a static equilibrium calculation and found an equilibrium position with roll and pitch values of \(\mathrm {\phi }\) and \(\mathrm {\theta }\), respectively. The user can define a grid of 4 points around the equilibrium position by using the roll values \(\mathrm {{\phi -1deg,\phi +1deg}}\) and the pitch values \(\mathrm {{\theta -1deg,\theta +1deg}}\). Once the "Multiple equilibrium calculation" is run, the total force of each grid point can be found in the prs file. The restoring moments (in roll and pitch) address the stability in roll and pitch of the equilibrium position; if all the 4 points has restoring moments that tend to bring the vessel back to the equilibrium position, then the equilibrium is stable. It is unstable otherwise.

6. Eigenvalue calculation

Natural periods and eigen vectors are calculated for selected modes. The calculation is based on a linearized model of the system. Mass and stiffness matrices are calculated, and the system solved by a standard Jacobian solver. The effect of damping is not included in the analysis.

The mass matrix is built from the virtual mass matrix, including both structural and hydrodynamic mass. The frequency dependency of the latter is not accounted for in the analysis as asymptotic values are used. For bodies of type 1 (see the chapter Body Data Specifications) this means added mass at infinite frequency, while the added mass at zero frequency is used for bodies of type 2.

The secant stiffness for the user selected modes is calculated at the initial position. The user may choose to specify the secant excursion used in the calculation for each mode. The stiffness matrix is made symmetric.

For each natural period, the eigen vectors expresses the relative contribution from each mode. Translations are given in the length unit \(\mathrm{[L]}\) and rotations in degrees \(\mathrm{[deg]}\).

In the interpretation of the results, it should be kept in mind that damping is not included in the analysis. Modes that are heavily damped may thereby not be recognized in time domain simulation results.

Observe also that environmental forces are not included. Thus, the yaw motion of a turret moored or a single point moored vessel can not be checked by an eigenvalue analysis.

7. Mooring system pretension optimization

By this option it is possible to adjust line lengths (or move anchor position) in an optimal way in order to counteract average environmental forces. The sum of squared differences between pretension and actual tension in each line is minimized.

8. Write initial condition file

After all modifications have been made with the system, the initial condition must be saved. The initial condition file will be read by DYNMOD. It can also be read by STAMOD if more modifications are required.

9. Write file for visualization

A file for 3D visualisation by the stand-alone program SimVis can be written whenever the system description file has been read successfully. This means that the system can be visualized before or after equilibrium condition calculation has been made. Visualisation directly after reading the system description file can be advantageous as a preliminary control of the system geometry.