RAO#

class waveresponse.RAO(freq, dirs, vals, freq_hz=False, degrees=False, clockwise=False, waves_coming_from=True)[source]#

Response amplitude operator (RAO).

The RAO class extends the Grid class, and is a two-dimensional frequency/(wave)direction grid. The RAO values represents a transfer function that can be used to calculate a degree-of-freedom’s response based on a 2-D wave spectrum.

Parameters:

  • freq (array-like) – 1-D array of grid frequency coordinates. Positive and monotonically increasing.

  • dirs (array-like) – 1-D array of grid direction coordinates. Positive and monotonically increasing. Should be within the directional range [0, 360) degrees (or [0, 2*pi) radians). See Notes.

  • vals (array-like (N, M)) – RAO values (complex) associated with the grid. Should be a 2-D array of shape (N, M), such that N=len(freq) and M=len(dirs).

  • freq_hz (bool) – If frequency is given in ‘Hz’. If False, ‘rad/s’ is assumed.

  • degrees (bool) – If direction is given in ‘degrees’. If False, ‘radians’ is assumed.

  • clockwise (bool) – If positive directions are defined to be ‘clockwise’ (True) or ‘counterclockwise’ (False). Clockwise means that the directions follow the right-hand rule with an axis pointing downwards.

  • waves_coming_from (bool) – If waves are ‘coming from’ the given directions. If False, ‘going towards’ convention is assumed.

Notes

If the RAO is going to be used in response calculation (where the RAO is combined with a wave spectrum to form a response spectrum), it is important that the RAO covers the full directional domain, i.e., [0, 360) degrees, with a sufficient resolution. If the RAO object only partly covers the directional domain, you can consider to use the mirror() function to ‘expand’ the RAO with values that are folded about a symmetry plane.

conjugate()[source]#

Return a copy of the object with complex conjugate values.

copy()[source]#

Return a copy of the object.

differentiate(n=1)[source]#

Return the nth derivative of the RAO.

Parameters:

n (int) – Order of differentiation.

Returns:

Differentiated RAO object.

Return type:

obj

dirs(degrees=None)[source]#

Direction coordinates.

Parameters:

degrees (bool) – If directions should be returned in ‘degrees’. If False, ‘radians’ is used. Defaults to original units used during initialization.

freq(freq_hz=None)[source]#

Frequency coordinates.

Parameters:

freq_hz (bool) – If frequencies should be returned in ‘Hz’. If False, ‘rad/s’ is used. Defaults to original units used during initialization.

classmethod from_amp_phase(freq, dirs, amp, phase, phase_degrees=False, phase_leading=True, freq_hz=True, degrees=True, clockwise=True, waves_coming_from=True)[source]#

Construct an RAO object from amplitude and phase values.

Note that the RAO is converted to, and stored as, complex values internally.

Parameters:

  • freq (array-like) – 1-D array of grid frequency coordinates. Positive and monotonically increasing.

  • dirs (array-like) – 1-D array of grid direction coordinates. Positive and monotonically increasing. Should be within the directional range [0, 360) degrees (or [0, 2*pi) radians). See Notes.

  • amp (array-like (N, M)) – RAO amplitude values associated with the grid. Should be a 2-D array of shape (N, M), such that N=len(freq) and M=len(dirs).

  • phase (array-like (N, M)) – RAO phase values associated with the grid. Should be a 2-D array of shape (N, M), such that N=len(freq) and M=len(dirs).

  • phase_degrees (bool) – If the RAO phase values are given in ‘degrees’. If False, ‘radians’ is assumed.

  • phase_leading (bool) – Whether the phase values follow the ‘leading’ convention (True) or the ‘lagging’ convention (False). Mathematically, an RAO with phase lead convention is expressed as a complex number of the form A * exp(j * phi), where A represents the amplitude and phi represents the phase angle. Whereas an RAO with phase lag convention is expressed as A * exp(-j * phi).

  • freq_hz (bool) – If frequency is given in ‘Hz’. If False, ‘rad/s’ is assumed.

  • degrees (bool) – If direction is given in ‘degrees’. If False, ‘radians’ is assumed.

  • clockwise (bool) – If positive directions are defined to be ‘clockwise’. If False, ‘counterclockwise’ is assumed.

  • waves_coming_from (bool) – If waves are ‘coming from’ the given directions. If False, ‘going towards’ convention is assumed.

Returns:

Initialized RAO object.

Return type:

obj

Notes

If the RAO is going to be used in response calculation (where the RAO is combined with a wave spectrum to form a response spectrum), it is important that the RAO covers the full directional domain, i.e., [0, 360) degrees, with a sufficient resolution. If the RAO object only partly covers the directional domain, you can consider to use the mirror() function to ‘expand’ the RAO with values that are folded about a symmetry plane.

classmethod from_grid(grid)[source]#

Construct from a Grid-like object.

Parameters:

grid (obj) – Grid object.

Returns:

Initialized object.

Return type:

cls

grid(freq_hz=None, degrees=None)[source]#

Return a copy of the object’s frequency/direction coordinates and corresponding grid values.

Parameters:

  • freq_hz (bool) – If frequencies should be returned in ‘Hz’. If False, ‘rad/s’ is used. Defaults to original units used during initialization.

  • degrees (bool) – If directions should be returned in ‘degrees’. If False, ‘radians’ is used. Defaults to original units used during initialization.

Returns:

  • freq (array) – 1-D array of grid frequency coordinates.

  • dirs (array) – 1-D array of grid direction coordinates.

  • vals (array (N, M)) – Grid values as 2-D array of shape (N, M), such that N=len(freq) and M=len(dirs).

property imag#

Return a new Grid object where all values are converted to their imaginary part.

interpolate(freq, dirs, freq_hz=False, degrees=False, complex_convert='rectangular', fill_value=0.0)[source]#

Interpolate (linear) the grid values to match the given frequency and direction coordinates.

A ‘fill value’ is used for extrapolation (i.e. freq outside the bounds of the provided 2-D grid). Directions are treated as periodic.

Parameters:

  • freq (array-like) – 1-D array of grid frequency coordinates. Positive and monotonically increasing.

  • dirs (array-like) – 1-D array of grid direction coordinates. Positive and monotonically increasing.

  • freq_hz (bool) – If frequency is given in ‘Hz’. If False, ‘rad/s’ is assumed.

  • degrees (bool) – If direction is given in ‘degrees’. If False, ‘radians’ is assumed.

  • complex_convert (str, optional) – How to convert complex number grid values before interpolating. Should be ‘rectangular’ or ‘polar’. If ‘rectangular’ (default), complex values are converted to rectangular form (i.e., real and imaginary part) before interpolating. If ‘polar’, the values are instead converted to polar form (i.e., amplitude and phase) before interpolating. The values are converted back to complex form after interpolation.

  • fill_value (float or None) – The value used for extrapolation (i.e., freq outside the bounds of the provided grid). If None, values outside the frequency domain are extrapolated via nearest-neighbor extrapolation. Note that directions are treated as periodic (and will not need extrapolation).

Returns:

Interpolated grid values.

Return type:

array

property real#

Return a new Grid object where all values are converted to their real part.

reshape(freq, dirs, freq_hz=False, degrees=False, complex_convert='rectangular', fill_value=0.0)[source]#

Reshape the grid to match the given frequency/direction coordinates. Grid values will be interpolated (linear).

Parameters:

  • freq (array-like) – 1-D array of new grid frequency coordinates. Positive and monotonically increasing.

  • dirs (array-like) – 1-D array of new grid direction coordinates. Positive and monotonically increasing. Must cover the directional range [0, 360) degrees (or [0, 2 * numpy.pi) radians).

  • freq_hz (bool) – If frequency is given in ‘Hz’. If False, ‘rad/s’ is assumed.

  • degrees (bool) – If direction is given in ‘degrees’. If False, ‘radians’ are assumed.

  • complex_convert (str, optional) – How to convert complex number grid values before interpolating. Should be ‘rectangular’ or ‘polar’. If ‘rectangular’ (default), complex values are converted to rectangular form (i.e., real and imaginary part) before interpolating. If ‘polar’, the values are instead converted to polar form (i.e., amplitude and phase) before interpolating. The values are converted back to complex form after interpolation.

  • fill_value (float or None) – The value used for extrapolation (i.e., freq outside the bounds of the provided grid). If None, values outside the frequency domain are extrapolated via nearest-neighbor extrapolation. Note that directions are treated as periodic (and will not need extrapolation).

Returns:

A copy of the object where the underlying coordinate system is reshaped.

Return type:

obj

rotate(angle, degrees=False)[source]#

Rotate the underlying grid coordinate system a given angle.

All directions are converted so that:

dirs_new = dirs_old - angle

Note that the direction of positive rotation follows the set ‘wave convention’.

Parameters:

  • angle (float) – Rotation angle.

  • degrees (bool) – Whether the rotation angle is given in ‘degrees’. If False, ‘radians’ is assumed.

Returns:

A copy of the object where the underlying coordinate system is rotated.

Return type:

obj

set_wave_convention(clockwise=True, waves_coming_from=True)[source]#

Set wave direction convention.

Directions and values will be converted (in-place) to the given convention.

Parameters:

  • clockwise (bool) – If positive directions are defined to be ‘clockwise’ (True) or ‘counterclockwise’ (False). Clockwise means that the directions follow the right-hand rule with an axis pointing downwards.

  • waves_coming_from (bool) – If waves are ‘coming from’ the given directions. If False, ‘going towards’ convention is assumed.

to_amp_phase(phase_degrees=None, phase_leading=None, freq_hz=None, degrees=None)[source]#

Return the RAO as amplitude and phase values.

Parameters:

  • phase_degrees (bool) – If phase values should be returned in ‘degrees’. If False, ‘radians’ is used. Defaults to original units used during initialization or False.

  • phase_leading (bool) – Whether the phase values should follow the ‘leading’ convention (True) or the ‘lagging’ convention (False). If None, it defaults to the convention given during initialization, or the lagging convention if no convention was specified during initialization. Mathematically, an RAO with phase lead convention is expressed as a complex number of the form A * exp(j * phi), where A represents the amplitude and phi represents the phase angle. Whereas an RAO with phase lag convention is expressed as A * exp(-j * phi).

  • freq_hz (bool) – If frequencies should be returned in ‘Hz’. If False, ‘rad/s’ is used. Defaults to original units used during initialization.

  • degrees (bool) – If directions should be returned in ‘degrees’. If False, ‘radians’ is used. Defaults to original units used during initialization.

Returns:

  • freq (array) – 1-D array of grid frequency coordinates.

  • dirs (array) – 1-D array of grid direction coordinates.

  • amp (array (N, M)) – RAO amplitude values as 2-D array of shape (N, M), such that N=len(freq) and M=len(dirs).

  • phase (array (N, M)) – RAO phase values as 2-D array of shape (N, M), such that N=len(freq) and M=len(dirs).

property wave_convention#

Wave direction convention.