Utils

The utils.py module contains a large set of utility functions (e.g. rotation matrices etc).

mclsimpy.utils.J(eta)

6 DOF rotation matrix.

\[\begin{split}J(\eta) = \left[\begin{array}{cc}R_{zyx}(\eta) & O_{3\times 3} \\ O_{3\times 3} & T_{zyx}(\eta)\end{array} \right]\end{split}\]

Parameters:: eta (array_like) – 6x1 vessel pose vector in NED frame
Returns:: J – 6x6 rotation matrix.
Return type:: array_like

mclsimpy.utils.Rx(phi)

3DOF Rotation matrix about x-axis.

Parameters:: phi (float) – Roll angle (rad).
Returns:: Rx – 3x3 rotation matrix.
Return type:: array_like

mclsimpy.utils.Ry(theta)

3DOF Rotation matrix about y-axis.

Parameters:: theta (float) – Pitch angle (rad)
Returns:: Ry – 3x3 rotation matrix.
Return type:: array_like

mclsimpy.utils.Rz(psi)

3DOF Rotation matrix about z-axis.

Parameters:: psi (float) – Yaw angle (rad)
Returns:: Rz – 3x3 rotation matrix.
Return type:: array_like

mclsimpy.utils.Rzyx(eta)

Full roation matrix.

\[R_{zyx} = R_z(\psi)R_y(\theta)R_x(\phi)\]

Parameters:: eta (array_like) – 6x1 array of vessel pose in NED frame.
Returns:: Rzyx
Return type:: array_like

mclsimpy.utils.Smat(x)

Skew-symmetric cross-product operator matrix.

Parameters:: x (3x1-array) –
Returns:: S
Return type:: 3x3-array

mclsimpy.utils.Tzyx(eta)

Transformation matrix.

Parameters:: eta (array_like) – 6x1 vessel pose vector in NED frame.
Returns:: Tzyx – 3x3 transformation matrix
Return type:: array_like

See also

utils.read_tf, utils.read_wave_drift

mclsimpy.utils.invfreqs(h, w, nb, na, weights=None, method=0, maxiter=40)

Estimate the numerator and denominator coefficients of a transfer function from frequency response data using complex function curve fitting with quasi-linear least squares.

Parameters:

h (array_like) – The frequency response values.
w (array_like) – The frequencies (in radians/sample) corresponding to the frequency response values.
nb (int) – The order of the numerator.
na (int) – The order of the denominator.
weights (array_like, optional) – The weighting factors for the frequency response values. Default is None.

Returns:

b (ndarray) – The estimated numerator coefficients of the transfer function.
a (ndarray) – The estimated denominator coefficients of the transfer function.
success (bool) – True if the fit succeeded, False otherwise.

mclsimpy.utils.joint_identification(w, A, B, order, plot_estimate=False, method=0)

Joint identification of infinity added mass and radiation forces.

Parameters:

w (array_like) – The frequencies (in radians/sample) corresponding to the frequency response values.
A (array_like) – The frequency response values of the added mass.
B (array_like) – The frequency response values of the radiation forces.
order (int) – The order of the numerator and denominator polynomials.
plot_estimate (bool, optional) – If True, plot the estimated transfer function. Default is False.

Returns:

Ma (ndarray) – The estimated infinity added mass coefficients.
Arad (array_like) – The system matrix of the radiation forces.
Brad (array_like) – The input matrix of the radiation forces.
Crad (array_like) – The output matrix of the radiation forces.

mclsimpy.utils.pipi(theta)

Return angle in range [-pi, pi).

Parameters:: theta (float, array_like) – Angle in radians to be mapped to [-pi, pi).
Returns:: angle – Smallest signed angle in range [-pi, pi).
Return type:: float, array_like

Examples

>>> from mclsimpy.utils import pipi
>>> import numpy as np
>>> angle = 2*np.pi
>>> pipi(angle)
0.0

>>> angle = np.deg2rad(270)
>>> pipi(angle)
-1.570796

mclsimpy.utils.pipi2cont(psi, psi_prev): Lifting algorithm for angle signal.

mclsimpy.utils.plot_raos(raos, freqs, plot_polar=True, rao_type='motion', wave_angle=0, figsize=(16, 8))

Plot the force or motion RAOs.

The RAOs should be complex.

Parameters:

raos (array_like) – Array of motion RAOs for k dofs, n freqs, m headings, and j velocities.
freqs (array_like) – Array of frequencies for which the RAOs are computed.
rao_type (string (default = "motion")) – Type of RAO. Either “motion” or “force”. Defaults to “motion”
plot_polar (bool (default = True)) – Either plot the RAOs in polar- or cartesian coordinates. Defaults to polar.
wave_angle (int (default = 0)) – Index of the relative incident wave anlge. Defaults to 0, which should correspond to following sea.
figsize (tuple (default = (16, 8))) – Size of the plot. Defaults to (16, 8).

mclsimpy.utils.polar_to_complex(amp, theta)

Polar coordinate to complex value.

The complex value is calculated from the polar coordinates as

\[z = A (\cos(\theta) + j\sin(\theta))\]

Parameters:

amp (float) – Amplitude/radius of polar value.
theta (float) – Angle in radians.

Returns:

complex_value – Complex value.

Return type:

complex

Examples

>>> from mclsimpy.utils import polar_to_complex
>>> amp, theta = 1.0, 0.0
>>> polar_to_complex(amp, theta)
(1 + 0j)

>>> amp, theta = 1.0, np.pi
>>> polar_to_complex(amp, theta)
(-1 + 0j)

mclsimpy.utils.power_spectral_density(timeseries, fs, freq_hz=False, nperseg=2048)

Compute the Power Spectral Density (PSD) of a timeseries.

The PSD is calculated using scipy.signals.welch

Parameters:

timerseries (array_like) – Timeseries array.
fs (int) – Sampling frequency
freq_hz (bool (optional)) – Calculate the PSD in [hz]. Defaults to False.
nperseg (float (optional)) – Number of points per segments used in the scipy.signal.welch function.

Returns:

f (array_like) – Frequencies in PSD. Returned as [rad/s] if freq_hz=False.
PSD (array_like) – PSD of timeseries. Returned as [unit/(rad/s)] if freq_hz=False

mclsimpy.utils.quat2eul(w, x, y, z): Returns the ZYX roll-pitch-yaw angles from a quaternion.

mclsimpy.utils.read_hydrod(filepath)

Read hydrodynamic coefficients from Veres output file.

The function reads the hydrodynamic coefficients from a Veres output file. The coefficients are transformed from the CG to CO and from the Veres axis system to the mclsimpy axis system.

Parameters:

filepath (string) – Path to the Veres output file.

Returns:

Mrb_co (array_like) – Mass matrix in CO.
A_co (array_like) – Added mass matrix in CO.
B_co (array_like) – Damping matrix in CO.
C_co (array_like) – Restoring matrix in CO.
Bv44_linear (array_like) – Linearized damping matrix.
Bv44_nonlin (array_like) – Non-linear damping matrix.
Bv44_linearized (array_like) – Linearized damping matrix.
nabla (float) – Added mass ratio.
rhow (float) – Water density.
lpp (float) – Length between perpendicular

mclsimpy.utils.read_tf(file_path, tf_type='motion')

Read VERES transfer function output.

The function reads data from veres input files. - Motion RAOs are found in ‘.re1’ - Force RAOs are found in ‘.re8’

The RAOs are converted from the global coordinate system in VERES, which is defined as: x-axis positive to stern, y-axis postive to stbd, and z-axis positive up, to the body frame used on mclsimpy.

Parameters:

file_path (string) – The path to the .re1 or .re8 file.
tf_type (string (default='motion')) – Type of transfer function. Can be either force or motion RAO. If type = ‘motion’, the input file should be .re1, else the expected file is .re8 for force RAO.

Returns:

rho_w (float) – Water density
g (float) – Gravitational acceleration
freqs (array_like) – Array of n frequencies in [rad/s] for which the RAOs are calculated.
headings (array_like) – Array of m headings in [rad] for which the RAOs are calculated.
velocities (array_like) – Array of j velocities [m/s] for which the RAOs are calculated.
rao_complex (array_like) – Array of complex RAOs with dimension (6, n, m, j). Using dtype=np.complex128.
rao_amp (array_like) – Array of RAO amplitudes [m/m] with dimension (6, n, m, j).
rao_phase (array_like) – Array of RAO phase [rad] with dimension (6, n, m, j).

Note

The wave direction convention of VERES is different from mclsimpy. VERES use 0 deg as head sea, and 180 deg as following sea. While mclsimpy use head sea = 180 deg, and following sea = 0 deg.

mclsimpy.utils.read_wave_drift(filepath)

Read wave drift data from Veres output file.

The function reads the wave drift data from a Veres output file. The data is transformed from the Veres axis system to the mclsimpy axis system. The wave drift data is transformed to the mclsimpy axis system by applying a transformation matrix.

Parameters:: filepath (string) – Path to the Veres output file.
Returns:: drift_frc_n – Array of wave drift forces with dimension (6, nofreq, nohead, novel). The array is transformed to the mclsimpy axis system.
Return type:: array_like

mclsimpy.utils.rigid_body_transform(r, eta, in_ned=True)

Calculate the relative motion of a point r different from the COG.

The calculation assumes small angles (s.t. cos(theta)=0 and sin(theta)=theta) and is computed as:

\[s = (\eta_1, \eta_2, \eta_3)^T + (\eta_4, \eta_5, \eta_6) x (r_x, r_y, r_z)\]

Parameters:

r (array_like) – Lever arm from COG to point of interest
eta (array_like) – 6DOF vessel pose (surge, sway, heave, roll, pitch, yaw)
in_ned (bool (default = False)) – Reference frame definition of eta. If True, the vessel pose eta is assumed to be defined in the NED-frame. If False eta is assumed to be defined in body-frame.

Returns:

s – Translation vector which is the same as (delta_x, delta_y, delta_z).

Return type:

array_like

mclsimpy.utils.six2threeDOF(v)

6 to 3 DOF conversion.

Convert a 6DOF vecor or matrix to 3DOF.

Parameters:: v (array_like) – 6 DOF vector or matrix to be converted to 3DOF.
Returns:: out – Vector (3,1) or matrix (3,3) array.
Return type:: array_like

mclsimpy.utils.system_identification(w, A, B, max_order=10, method=0, plot_estimate=False)

Identify the system matrices of a linear time-invariant system.

Parameters:

w (array_like) – The frequencies (in radians/sample) corresponding to the frequency response values.
A (array_like) – The frequency response values of the added mass.
B (array_like) – The frequency response values of the radiation forces.
max_order (int, optional) – The maximum order of the numerator and denominator polynomials. Default is 10.
method (int, optional) – The method used for the identification. Default is 0.
plot_estimate (bool, optional) – If True, plot the estimated transfer function. Default is False.

Returns:

MA (ndarray) – The estimated infinity added mass coefficients.
Ar (array_like) – The system matrix of the radiation forces.
Br (array_like) – The input matrix of the radiation forces.
Cr (array_like) – The output matrix of the radiation forces.

mclsimpy.utils.three2sixDOF(v)

3 to 6 DOF conversion.

Converts a vector a matrix from 3DOF to 6DOF.

Parameters:: v (array_like) – Vector or matrix to be converted.
Returns:: out – Vector (6,1) or matrix (6, 6) array.
Return type:: array_like

mclsimpy.utils.timeit(func)

Decorator for measuring execution time of function.

Print the execution time of a function. (Mainly for debugging and analyzis purposes).

Parameters:: func (function) – Function to be timed.

Examples

>>> from mclsimpy.utils import timeit
>>> @timeit
... def loop(n):
...     for i in range(n):
...         print(i)
...
>>> loop(5)
0
1
2
3
4
Execution time of loop: 0.004

mclsimpy.utils.to_positive_angle(theta)

Map angle from [-pi, pi) to [0, 2*pi).

Parameters:: theta (array_like) – Angle in radians in [-pi, pi).
Returns:: out – Angle in [0, 2*pi).
Return type:: array_like

Note

The function does not calculate the smallest signed positive angle if the input is outside [-pi, pi).