WaveSpectrum#

class waveresponse.WaveSpectrum(*args, **kwargs)[source]#

Wave spectrum.

The WaveSpectrum class extends the DirectionalSpectrum class, and is a two-dimentional frequency/(wave)direction grid. The spectrum values represents spectrum density. Only real and positive values allowed.

Proper scaling is applied to ensure that the total “energy” remains constant at all times.

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. Must cover the directional range [0, 360) degrees (or [0, 2 * numpy.pi) radians).
vals (array-like (N, M)) – Spectrum density values 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.

bingrid(freq_hz=False, degrees=False, complex_convert='rectangular')[source]#

Return a copy of the spectrum’s frequency and direction coordinates, along with the corresponding binned spectrum values.

The spectrum values are interpolated and then integrated over their respective direction bins, resulting in total energy per unit frequency. This differs from the grid method, which returns the spectral density values directly without bin integration.

Parameters:

freq_hz (bool) – Whether to return frequencies in hertz (Hz). If False, angular frequency in radians per second (rad/s) is used.
degrees (bool) – Whether to return directions in degrees. If False, radians are used.
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.

Returns:

freq (ndarray, shape (N,)) – 1D array of frequency coordinates.
dirs (ndarray, shape (M,)) – 1D array of direction coordinates.
vals (ndarray, shape (N, M)) – 2D array of binned spectrum energy values (energy per unit frequency). N = len(freq), M = len(dirs).

property conjugate#: Return a copy of the object with complex conjugate values.

copy()[source]#: Return a copy of the object.

dirm(degrees=None)[source]#

Mean wave direction.

Parameters:: degrees (bool) – If mean wave direction should be returned in ‘degrees’. If False, the direction is returned in ‘radians’. Defaults to original unit used during instantiation.

dirp(degrees=None)[source]#

Wave peak direction.

Defined as the mean wave direction along the frequency corresponding to the maximum value of the ‘non-directional’ spectrum.

Parameters:: degrees (bool) – If wave peak direction should be returned in ‘degrees’. If False, the direction is returned in ‘radians’. Defaults to original unit used during initialization.

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.

extreme(t, q=0.37, absmax=False)[source]#

Compute the q-th quantile extreme value (assuming a Gaussian process). Only applicable for positive real-valued spectra.

The extreme value, x, is calculated according to:

x = sigma * sqrt(2 * ln((t / tz) / ln(1 / q)))

where sigma is the standard deviation of the process, t is the duration of the process, and q is the quantile. Setting q=0.37 yields the most probable maximum (MPM).

Parameters:

t (float) – Time/duration in seconds for which the of the process is observed.
q (float or array-like) – Quantile or sequence of quantiles to compute. Must be between 0 and 1 (inclusive).
absmax (bool) – Whether to compute absolute value extremes (i.e., taking the minima into account). If False (default), only the maxima are considered. See Notes.

Returns:

x – Extreme value(s). During the given time period, the maximum value (or absolute value maximum) of the process amplitudes will be below the returned value with the given probability.

Return type:

float or array

Notes

Computing absolute value extremes by setting absmax=True is equivalent to doubling the expected zero-crossing rate, fz = 1 / Tz.

Notes

The extreme values are calculated according to Equation (1.46) in reference [1].

References

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_grid(grid)[source]#

Construct from a Grid-like object.

Parameters:: grid (obj) – Grid object.
Returns:: Initialized object.
Return type:: cls

classmethod from_spectrum1d(freq, dirs, spectrum1d, spread_fun, dirp, freq_hz=False, degrees=False, clockwise=False, waves_coming_from=True)[source]#

Construct a 2-D ‘directional’ spectrum from a 1-D ‘non-directional’ spectrum, a spreading function and a peak direction.

The directional spectrum is constructed according to:

S(f, theta) = S(f) * D(f, theta - theta_p)

where S(f) is the non-directional spectrum, D(f, theta - theta_p) is the directional spreading function, and theta_p is the peak direction. f is the frequency coordinate, and theta is the direction coordinate.

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. Must cover the directional range [0, 360) degrees (or [0, 2 * pi) radians).
spectrum1d (array-like) – 1-D array of non-directional spectrum density values. These 1-D spectrum values will be scaled according to the spreading function, and distributed to all frequency/direction coordinates. spectrum1d must have the same length as freq.
spread_fun (callable) – Spreading function. Takes a frequency coordinate (float) and a direction coordinate (float) as input, and returns a corresponding scaling value (float).
dirp (float) – Peak direction. Direction in which the spectrum has its maximum values.
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.

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

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

Parameters:

freq_hz (bool) – If frequencies should be returned in ‘Hz’. If False, ‘rad/s’ is used.
degrees (bool) – If directions should be returned in ‘degrees’. If False, ‘radians’ is used.

Returns:

freq (array) – 1-D array of grid frequency coordinates.
dirs (array) – 1-D array of grid direction coordinates.
vals (array (N, M)) – Spectrum density values as 2-D array of shape (N, M), such that N=len(freq) and M=len(dirs).

property hs#

Significan wave height, Hs.

Calculated from the zeroth-order spectral moment according to:

hs = 4.0 * sqrt(m0)

Notes

The significant wave height is calculated according to equation (2.26) in reference [1].

References

[1] 0. M. Faltinsen, (1990), “Sea loads on ships and offshore structures”, Cambridge University Press.

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

moment(n, freq_hz=None)[source]#

Calculate spectral moment (along the frequency domain).

Parameters:

n (int) – Order of the spectral moment.
freq_hz (bool) – If frequencies in ‘Hz’ should be used. If False, ‘rad/s’ is used. Defaults to original unit used during initialization.

Returns:

Spectral moment.

Return type:

float

Notes

The spectral moment is calculated according to Equation (8.31) and (8.32) in reference [1].

References

[1] A. Naess and T. Moan, (2013), “Stochastic dynamics of marine structures”, Cambridge University Press.

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.

spectrum1d(axis=1, freq_hz=None, degrees=None)[source]#

Integrate the spectrum over a given axis.

Parameters:

axis (int) – Axis along which integration of the spectrum is done. For axis=1 (default) the spectrum is integrated over direction, resulting in the so-called ‘non-directional’ spectrum. For axis=0 the spectrum is integrated over frequency, resulting in the directional ‘distribution’ of the spectrum.
freq_hz (bool) – If frequencies should be returned in ‘Hz’. If False, ‘rad/s’ is used. This option is only relevant if axis=1. Defaults to original unit used during instantiation.
degrees (bool) – If directions should be returned in degrees. This option is only relevant if axis=0. Defaults to original unit used during instantiation.

Returns:

x (1-D array) – Spectrum bins corresponding to the specified axis. axis=1 yields frequencies, while axis=0 yields directions.
s (1-D array) – Spectrum density values, where the spectrum is integrated over the specified axis.

std()[source]#: Standard deviation of the spectrum.

property tp#

Wave peak period in ‘seconds’.

The period at which the ‘non-directional’ wave spectrum, S(f), has its maximum value.

property tz#

Mean zero-crossing period, Tz, in ‘seconds’. Only applicable for positive real-valued spectra.

Calculated from the zeroth- and second-order spectral moments according to:

tz = sqrt(m0 / m2)

where the spectral moments are calculated by integrating over frequency in Hz.

Notes

The mean zero-crossing period is calculated according to Equation (8.33) in reference [1].

References

[1] A. Naess and T. Moan, (2013), “Stochastic dynamics of marine structures”, Cambridge University Press.

var()[source]#: Variance (integral) of the spectrum.

property wave_convention#: Wave direction convention.