WaveBinSpectrum#

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

Binned wave spectrum.

The WaveSpectrum class extends the DirectionalBinSpectrum class, and is a two-dimentional frequency/(wave)direction grid. The spectrum values represents spectrum density as a function of frequency, binned by direction.

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.

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

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(*args, **kwargs)[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, freq_hz=False, complex_convert='rectangular', fill_value=0.0)[source]#

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

Parameters:

freq (array-like) – 1-D array of new grid frequency coordinates. Positive and monotonically increasing.
freq_hz (bool) – If frequency is given in ‘Hz’. If False, ‘rad/s’ 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:

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.