Deltares Wave Toolbox package contents

series module

class deltares_wave_toolbox.series.Series(time: ndarray[tuple[Any, ...], dtype[float64]], xTime: ndarray[tuple[Any, ...], dtype[float64]])[source]

Bases: WaveHeights

The wave Series class

Contains a time series (typically) of water level elevations. Inherits from WaveHeights class.

Parameters:

  • time (NDArray[float64]) – 1D array containing time axis. The numbers in the array t must be increasing and uniformly spaced (uniform time step) [s]

  • xTime (NDArray[float64]) – 1D array containing signal values, i.e. the time series of the signal. The value xTime(i) must be the signal value at time t(i). Usually water surface elevation [m]

get_asymmetry() → tuple[float, float][source]

Compute asymmetry

As is asymmetry of the signal

Returns:

As

Return type:

float

get_bandpassfilter(fmin: float, fmax: float)[source]

get bandpassfiltered signal

Parameters:

  • fmin (lower frequency for bandpassfilter)

  • fmax (higher frequency for bandpassfilter)

Returns:

Series in series object

Return type:

series.Series

get_crossing(typeCross: str = 'down') → tuple[int, ndarray[tuple[Any, ...], dtype[float64]]][source]

Get zero crossings form time series

Determine either the zero up- or down-crossings of the time series.

Parameters:

typeCross (str, optional) – Search for up- or down-crossings, by default “down”

Returns:

nWaveint

Number of waves in the signal, where one wave corresponds to two successive zero-crossings. Wave i starts at time tCross(i), and end at time tCross(i+1) [-]

tCrossNDArray[float64]

1D array of length (nWave+1), containing the time of all zero-crossings. The time of the zero-crossings is determined by linear interpolation. Note that in case of no zero-crossing, the array tCross is empty. Note that in case of one zero-crossing, the number of waves is zero. [s]

Return type:

tuple[int, NDArray[float64]]

get_fourier_comp() → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[complex128]], bool][source]

get Fourier components from series

Returns:

fNDArray[float64]

1D array containing frequency values, for folded Fourier transform. The frequency axis runs from 0 to the Nyquist frequency. The number of elements in array f is close to half the number of elements in array xTime. To be precise, length(f) = floor(nT/2) + 1, with nT the number of elements in array xTime [Hz]

xFreqNDArray[complex128]

1D array (complex!) containing the folded Fourier coefficients of xTime. The value xFreq(i) must be the Fourier coefficient at frequency f(i). The number of elements in f and xFreq are the same.

isOddbool

logical indicating whether nT, the number of time points in xTime, is even (isOdd=False) or odd (isOdd=True)

Return type:

tuple[NDArray[float64], NDArray[complex128], bool]

get_skewness() → tuple[float, float][source]

Compute skewness

Sk is skewness of the signal

Returns:

Sk

Return type:

float

get_spectrum(nperseg: int = 256, noverlap: int = 0, nfft: int = 0, windows_type: str = 'hann', dfDesired: float = 0.01, use_dfDesired: bool = True) → Spectrum[source]

create spectrum

Parameters:

  • nperseg (int, optional) – Length of each segment, by default None

  • noverlap (int, optional) – number of points in overlap, by default None

  • nfft (int, optional) – length of fft, by default None

  • window_type (str, optional) – window type, by default “hann”

Returns:

Spectrum in spectrum object

Return type:

spectrum.Spectrum

get_spectrum_raw(dfDesired: float = 0.01) → Spectrum[source]

create spectrum with a desired frequency, but without applying segments

Parameters:

dfDesired (float, optional) – desired frequency spacing in Hertz on which the wave spectrum must be computed. If this parameter is omitted, then dfDesired = f(1) - f(0), by default 0.01 [Hz]

Returns:

Spectrum in spectrum object

Return type:

spectrum.Spectrum

max() → float[source]
mean() → float[source]
min() → float[source]
plot(savepath: str = '', plot_crossing: bool = False) → Figure[source]

Plot Series

Parameters:

  • savepath (str, optional) – path to save figure, by default “”

  • plot_crossing (bool, optional) – plot zero crossings in figure, by default False

Returns:

figure object

Return type:

figure.Figure

var() → float[source]
class deltares_wave_toolbox.series.WaveHeights(hwave: ndarray[tuple[Any, ...], dtype[float64]], twave: ndarray[tuple[Any, ...], dtype[float64]])[source]

Bases: object

The WaveHeights class

Parameters:

  • hwave (NDArray[float64]) – 1D array containing the wave heights of the individual waves [m]

  • twave (NDArray[float64]) – 1D array containing the periods of the individual waves [s]

get_H2p_Rayleigh() → float[source]

Compute 2% exceedance wave height assuming theoretical Rayleigh distribution

Returns:

H2p

Return type:

float

get_Hmax() → float64[source]

Return maximum wave height

Returns:

Hmax

Return type:

float64

get_Hrms() → float[source]

Compute root-mean-squared wave height

Returns:

Hrms

Return type:

float

get_Hs() → tuple[float, float][source]

Compute significant wave height & associated period

Hs (significant wave height) is the average of the highest 1/3 of the waves

Returns:

Hs, Ts

Return type:

tuple[float, float]

get_exceedance_waveheight(excPerc: float) → float[source]

Computes wave height with given exceedance probability

This function computes the wave height hExcPerc with given exceedance probability percentage excPerc.

Parameters:

excPerc (float) – exceedance probability percentage. excPerc = 2 means an exceedance percentage of 2%. The value of excPerc should not exceed 100, or be smaller than 0 [%]

Returns:

wave height with given exceedance probability [m]

Return type:

float

highest_waves(fracP: float) → tuple[float, float][source]

Computes wave parameters of selection largest waves

This function computes the wave height hFracP and wave period tFracP by taking the average of the fraction fracP of the highest waves. When fracP = 1/3, then hFracP is equal to the significant wave height and tFracP is equal to the significant wave period.

Parameters:

fracP (float) – fraction. Should be between 0 and 1 [-]

Returns:

hFracPfloat

average of the wave heights of the highest fracP waves [m]

tFracPfloat

average of the wave periods of the highest fracP waves [s]

Return type:

tuple[float, float]

plot_exceedance_waveheight(savepath: str = '') → Figure[source]

Plot exceedances of wave heights

Parameters:

savepath (str, optional) – path to save figure, by default “”

Returns:

figure object

Return type:

figure.Figure

plot_exceedance_waveheight_Rayleigh(savepath: str = '', normalize: bool = False, plot_BG: bool = False, water_depth: float = -1.0, cota_slope: float = 250.0, hm0: float = -1.0) → Figure[source]

Plot exceedances of wave heights compared to Rayleigh distribution

Parameters:

  • savepath (str, optional) – path to save figure, by default “”

  • normalize (bool, optional) – normalize wave heights with significant wave height (Hs), by default False

  • plot_BG (bool, optional) – include theoretical Battjes & Groenendijk (2000) distribution in plot, by default False

  • water_depth (float, optional) – water depth needed for Battjes & Groenendijk (2000), by default -1.0 [m]

  • cota_slope (float, optional) – foreshore slope needed for Battjes & Groenendijk (2000), by default 250.0 [-]

  • hm0 (float, optional) – spectral wave height needed for Battjes & Groenendijk (2000), by default -1.0 [m]

Returns:

figure object

Return type:

figure.Figure

Raises:

ValueError – Raised when plot_BG is True and Hm0 is not provided

plot_hist_waveheight(savepath: str = '') → Figure[source]

Plot Histogram of wave heights

Parameters:

savepath (str, optional) – path to save figure, by default “”

Returns:

figure object

Return type:

figure.Figure

sort() → None[source]

Sort wave heights and wave periods

Sorts the wave height and wave period. The sorting is done such that in hWaveSorted the wave heights of hWave are sorted in descending order. This same sorting is applied to tWave.

spectrum module

class deltares_wave_toolbox.spectrum.Spectrum(f: ndarray[tuple[Any, ...], dtype[float64]], sVarDens: ndarray[tuple[Any, ...], dtype[float64]], D: ndarray[tuple[Any, ...], dtype[float64]] = array([], shape=(0, 0), dtype=float64))[source]

Bases: object

The wave Spectrum class

Parameters:

  • f (NDArray[float64]) – array with frequencies

  • sVarDens (NDArray[float64]) – array with energy density

  • D (NDArray[float64], optional) – array with directions for 2D spectrum, by default np.empty((0, 0))

create_series(tstart: float, tend: float, dt: float) → Series[source]

Construct series from Spectrum with random phase

Parameters:

  • tstart (float) – Start time of time series

  • tend (float) – End time of time series

  • dt (float) – Time step

Returns:

Series class with time series

Return type:

series.Series

get_Hm0(fmin: float = -1.0, fmax: float = -1.0) → float[source]

Compute Hm0 of spectrum

Parameters:

  • fmin (float, optional) – Minimum frequency, by default -1.0

  • fmax (float, optional) – Maximum frequency, by default -1.0

Returns:

Hm0

Return type:

float

get_Hm0_HF(fmin: float = -1.0, fmax: float = -1.0) → float[source]

Compute Hm0 of the high frequency part of the spectrum

By default, the high frequency part is defined as frequencies above f_cutoff = 0.45 / Tm-1,0 following De Ridder et al. (2024). For JONSWAP spectra, this equals a cutoff frequency of fp/2, but is a more stable measure for spectra without a clear peak frequency.

Parameters:

  • fmin (float, optional) – Minimum frequency, by default -1.0

  • fmax (float, optional) – Maximum frequency, by default -1.0

Returns:

Hm0

Return type:

float

get_Hm0_LF(fmin: float = -1.0, fmax: float = -1.0) → float[source]

Compute Hm0 of the low frequency part of the spectrum

By default, the low frequency part is defined as frequencies below f_cutoff = 0.45 / Tm-1,0 following De Ridder et al. (2024). For JONSWAP spectra, this equals a cutoff frequency of fp/2, but is a more stable measure for spectra without a clear peak frequency.

Parameters:

  • fmin (float, optional) – Minimum frequency, by default -1.0

  • fmax (float, optional) – Maximum frequency, by default -1.0

Returns:

Hm0

Return type:

float

get_Tm01(fmin: float = -1.0, fmax: float = -1.0) → float[source]

Compute Tm01 of spectrum

Parameters:

  • fmin (float, optional) – Minimum frequency, by default -1.0

  • fmax (float, optional) – Maximum frequency, by default -1.0

Returns:

Tm01

Return type:

float

get_Tm02(fmin: float = -1.0, fmax: float = -1.0) → float[source]

Compute Tm02 of spectrum

Parameters:

  • fmin (float, optional) – Minimum frequency, by default -1.0

  • fmax (float, optional) – Maximum frequency, by default -1.0

Returns:

Tm02

Return type:

float

get_Tmm10(fmin: float = -1.0, fmax: float = -1.0) → float[source]

Compute Tm-1,0 spectral period of spectrum

Parameters:

  • fmin (float, optional) – Minimum frequency, by default -1.0

  • fmax (float, optional) – Maximum frequency, by default -1.0

Returns:

Tmm10

Return type:

float

get_Tmm10_HF(fmin: float = -1.0, fmax: float = -1.0) → float[source]

Compute Tm-1,0 spectral period for the high frequency part of the spectrum

By default, the high frequency part is defined as frequencies above f_cutoff = 0.45 / Tm-1,0 following De Ridder et al. (2024). For JONSWAP spectra, this equals a cutoff frequency of fp/2, but is a more stable measure for spectra without a clear peak frequency.

Parameters:

  • fmin (float, optional) – Minimum frequency, by default -1.0

  • fmax (float, optional) – Maximum frequency, by default -1.0

Returns:

Tmm10

Return type:

float

get_Tmm10_LF(fmin: float = -1.0, fmax: float = -1.0) → float[source]

Compute Tm-1,0 spectral period for the low frequency part of the spectrum

By default, the low frequency part is defined as frequencies below f_cutoff = 0.45 / Tm-1,0 following De Ridder et al. (2024). For JONSWAP spectra, this equals a cutoff frequency of fp/2, but is a more stable measure for spectra without a clear peak frequency.

Parameters:

  • fmin (float, optional) – Minimum frequency, by default -1.0

  • fmax (float, optional) – Maximum frequency, by default -1.0

Returns:

Tmm10

Return type:

float

get_Tp(fmin: float = -1.0, fmax: float = -1.0) → float[source]

Compute Tp (peak period) of spectrum

Parameters:

  • fmin (float, optional) – Minimum frequency, by default -1.0

  • fmax (float, optional) – Maximum frequency, by default -1.0

Returns:

Tp

Return type:

float

get_Tps(fmin: float = -1.0, fmax: float = -1.0) → float[source]

Compute Tps (smoothed peak period) of spectrum

Parameters:

  • fmin (float, optional) – Minimum frequency, by default -1.0

  • fmax (float, optional) – Maximum frequency, by default -1.0

Returns:

Tps

Return type:

float

get_s0p(fmin: float = -1.0, fmax: float = -1.0, g: float = 9.81) → float[source]

Compute s0p of the spectrum

Compute the wave steepness of the spectrum based on the deep water wave length using the peak wave period Tps.

Parameters:

  • fmin (float, optional) – Minimum frequency, by default -1.0

  • fmax (float, optional) – Maximum frequency, by default -1.0

  • g (float, optional) – gravitational acceleration constant, by default 9.81

Returns:

s0p

Return type:

float

get_smm10(fmin: float = -1.0, fmax: float = -1.0, g: float = 9.81) → float[source]

Compute sm-1,0 of the spectrum

Compute the wave steepness of the spectrum based on the deep water wave length using the spectral wave period Tm-1,0.

Parameters:

  • fmin (float, optional) – Minimum frequency, by default -1.0

  • fmax (float, optional) – Maximum frequency, by default -1.0

  • g (float, optional) – gravitational acceleration constant, by default 9.81

Returns:

smm10

Return type:

float

get_smm10_HF(fmin: float = -1.0, fmax: float = -1.0, g: float = 9.81) → float[source]

Compute sm-1,0_HF of the spectrum

Compute the wave steepness of the high frequency part of the spectrum based on the deep water wave length using the spectral wave period Tm-1,0_HF and the Hm0_HF.

Parameters:

  • fmin (float, optional) – Minimum frequency, by default -1.0

  • fmax (float, optional) – Maximum frequency, by default -1.0

  • g (float, optional) – gravitational acceleration constant, by default 9.81

Returns:

smm10_HF

Return type:

float

plot(savepath: str = '', plot_periods: bool = True, xlim: float = -999.0, xlabel: str = 'f [$Hz$]', ylabel: str = 'S [$m^2/Hz$]') → Figure[source]

Plot spectrum

Parameters:

  • savepath (str, optional) – path to save figure, by default “”

  • plot_periods (bool, optional) – show different periods in the plot, by default True

  • xlim (float, optional) – limit the extent of the x-axis (frequency), by default -999.0

  • xlabel (str, optional) – xlabel for the plot, by default “f [$Hz$]”

  • ylabel (str, optional) – ylabel for the plot, by default “f [$Hz$]”

Returns:

figure object

Return type:

figure.Figure

Subpackages

deltares_wave_toolbox.cores.core_dispersion module

deltares_wave_toolbox.cores.core_dispersion.disper(w: ndarray[tuple[Any, ...], dtype[float64]], h: float, g: float = 9.81)[source]

DISPER Solves the wave number from the linear dispersion relation

The linear dispersion relation reads:

w^2 = g * k * tanh( k * h )

where w is the radial frequency, g the gravitation acceleration constant, k the wave number, and h the water depth. The function DISPER solves for the wave number k, given the radial frequency w, the water depth h and the gravitational acceleration constant g.

water depth, units meter

Three possible options: (i) 0 < h < infinity: h is water depth, and nonlinear dispersion

relation is solved using given value for h

  1. h < 0. The shallow water dispersion relation is solved, with the actual water depth being equal to |h|

  2. h = inf. The deep water dispersion relation is solved.

This function is originally written by G. Klopman, Delft Hydraulics, 6 Dec 1994. It is stated that the relative error in k*h < 2.5e-16 for all k*h

Parameters:

  • w (NDArray[float64]) – radial frequency ( = 2 * pi / wave period), unit: rad/s.

  • h (float) – water depth, unit: meters

  • g (float, optional) – representing gravitational constant, by default 9.81

Returns:

k – wave number

Return type:

NDArray[float64]

deltares_wave_toolbox.cores.core_engine module

deltares_wave_toolbox.cores.core_engine.approx_array_index(array: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], user_value: float) → int[source]

Return index of the array value closest to user specified value.

Parameters:

  • array (ArrayLike) – array of values

  • user_value (float) – value to search for

Returns:

index value of array value closest to the user specified value

Return type:

int

deltares_wave_toolbox.cores.core_engine.convert_to_array_type(x: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) → ndarray[tuple[Any, ...], dtype[Any]][source]

Converts input to numpy array

Parameters:

x (ArrayLike) – input, convertible to array

Returns:

numpy array

Return type:

NDArray[Any]

deltares_wave_toolbox.cores.core_engine.convert_to_vector(x: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) → tuple[ndarray[tuple[Any, ...], dtype[Any]], tuple[int, int]][source]

Convert input to 1D numpy array

Parameters:

x (ArrayLike) – input, convertible to array

Returns:

x: NDArray[Any]

numpy array

xSize: tuple[int, int]

size of the numpy array

Return type:

tuple[NDArray[Any], tuple[int, int]]

deltares_wave_toolbox.cores.core_engine.is1darray(x: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) → bool[source]

Check is input is a 1D array

Parameters:

x (ArrayLike) – input, convertible to array

Returns:

True if input is a 1D array

Return type:

bool

deltares_wave_toolbox.cores.core_engine.monotonic_increasing_constant_step(x: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) → bool[source]

Check whether vector is monotonic increasing with constant step size

Parameters:

x (ArrayLike) – input vector

Returns:

True when vector is monotonic increasing with constant step size

Return type:

bool

deltares_wave_toolbox.cores.core_spectral module

deltares_wave_toolbox.cores.core_spectral.applybandfilter(f: ndarray[tuple[Any, ...], dtype[float64]], xFreq: ndarray[tuple[Any, ...], dtype[float64]], flow: float, fhigh: float)[source]
Parameters:

  • f (NDArray[float64]) – 1D array containing the frequencies

  • xFreq (NDArray[float64]) – 1D array (complex!) containing the folded Fourier coefficients of xTime. The value xFreq(i) must be the Fourier coefficient at frequency f(i). The number of elements in f and xFreq are the same.

  • flow (float) – Lower frequeny of the bandpassfilter

  • fhigh (float) – Higher frequency of the bandpassfilter

Returns:

zFreqNDArray[float64]

1D array containing the folded Fourier coefficients.

Return type:

tuple NDArray[float64]]

deltares_wave_toolbox.cores.core_spectral.bandpassfilter(t: ndarray[tuple[Any, ...], dtype[float64]], xTime: ndarray[tuple[Any, ...], dtype[float64]], flow: float, fhigh: float)[source]

Bandpassfilter Filters a signal based on a lower and higher frequency limit.

Parameters:

  • t (NDArray[float64]) – 1D array containing the time

  • xTime (NDArray[float64]) – 1D array containing signal values, i.e. the time series of the signal. The value xTime(i) must be the signal value at time t(i). Usually water surface elevation [m]

  • flow (float) – Lower frequeny of the bandpassfilter

  • fhigh (float) – Higher frequency of the bandpassfilter

Returns:

zTimeNDArray[float64]

1D array containing the filtered signal.

Return type:

tuple NDArray[float64]]

deltares_wave_toolbox.cores.core_spectral.coherence(f: ndarray[tuple[Any, ...], dtype[float64]], xFreq1: ndarray[tuple[Any, ...], dtype[complex128]], xFreq2: ndarray[tuple[Any, ...], dtype[complex128]], dfDesired: float = 0.0) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]][source]

Function to compute the coherence in spectral domain.

This function computes the coherence (magnitude-squared cohorence) of two complex spectral signal xFreq1 = xFreq1(f) and xFreq2 = xFreq2(f), given on frequency axis f. The output coh2 = coh2(f_coh2) is given on a frequency axis with frequency resolution dfDesired. Note: the coherence is real, and always between 0 and 1.

Parameters:

  • f (NDArray[float64]) – 1D array containing frequency values, for folded Fourier transform. The number of elements in array f is close to half the number of elements in array xTime. To be precise, length(f) = floor(nT/2) + 1, with nT the number of elements in array xTime [Hz]

  • xFreq1 (NDArray[complex128]) – 1D array (complex!) containing the folded Fourier coefficients of signal 1. The value xFreq(i) must be the Fourier coefficient at frequency f(i). The number of elements in f and xFreq1 are the same.

  • xFreq2 (NDArray[complex128]) – 1D array (complex!) containing the folded Fourier coefficients of signal 2. The value xFreq(i) must be the Fourier coefficient at frequency f(i). The number of elements in f and xFreq2 are the same.

  • dfDesired (float, optional) – desired frequency spacing in Hertz on which the wave spectrum must be computed. If this parameter is omitted, then dfDesired = f(1) - f(0), by default 0.0 [Hz]

Returns:

f_coh2NDArray[float64]

frequency axis of coherence. The frequency spacing is (close to) dfDesired [Hz]

coh2NDArray[float64]

coherence (magnitude-squared coherence)

Return type:

tuple[NDArray[float64], NDArray[float64]]

deltares_wave_toolbox.cores.core_spectral.compute_spectrum_freq_series(f: ndarray[tuple[Any, ...], dtype[float64]], xFreq: ndarray[tuple[Any, ...], dtype[float64]], Ntime: int, dfDesired: float = 0.0) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]][source]

Computes variance density spectrum from given complex spectrum of Fourier components

This function computes a variance density spectrum sVarDens_coarse = sVarDens_coarse(f_coarse) on a frequency axis f_coarse from a given complex spectrum xFreq = xFreq(f) of Fourier coefficients on a frequency axis f. The frequency spacing of the output spectrum is given by dfDesired.

Parameters:

  • f (NDArray[float64]) – 1D array containing frequency values, for folded Fourier transform. The number of elements in array f is close to half the number of elements in array xTime. To be precise, length(f) = floor(nT/2) + 1, with nT the number of elements in array xTime [Hz]

  • xFreq (NDArray[float64]) – wave spectrum of complex Fourier coefficients

  • dfDesired (float, optional) – desired frequency spacing in Hertz on which the wave spectrum must be computed. If this parameter is omitted, then dfDesired = f(1) - f(0), by default 0.0 [Hz]

  • Ntime (int, optional) – number of time elements in original time signal, by default 0

Returns:

f_coarseNDArray[float64]

frequency axis of computed spectrum. The frequency spacing is (close to) dfDesired [Hz]

sVarDens_coarseNDArray[float64]

band averaged variance density spectrum of the signal on new frequency axis fCoarse [m^2/Hz]

Return type:

tuple[NDArray[float64], NDArray[float64]]

Raises:

  • ValueError – Input error: input should be 1d arrays

  • ValueError – Input error: frequency input parameter must be monotonic with constant step size

  • ValueError – Input error: array sizes differ in dimension

deltares_wave_toolbox.cores.core_spectral.compute_spectrum_time_series(t: ndarray[tuple[Any, ...], dtype[float64]], xTime: ndarray[tuple[Any, ...], dtype[float64]], dfDesired: float = 0.0) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]][source]

Computes variance density spectrum from given time series

This function computes a variance density spectrum sVarDens_coarse = sVarDens_coarse(f_coarse) on a frequency axis f_coarse from a given surface elevation time series xTime = xTime(t), with time axis t. The frequency spacing of the output spectrum is given by dfDesired.

Parameters:

  • t (NDArray[float64]) – 1D array containing time axis. The numbers in the array t must be increasing and uniformly spaced (uniform time step) [s]

  • xTime (NDArray[float64]) – 1D array containing signal values, i.e. the time series of the signal. The value xTime(i) must be the signal value at time t(i). Usually water surface elevation [m]

  • dfDesired (float, optional) – desired frequency spacing in Hertz on which the wave spectrum must be computed. If this parameter is omitted, then dfDesired = f(1) - f(0), by default 0.0 [Hz]

Returns:

f_coarseNDArray[float64]

frequency axis of computed spectrum. The frequency spacing is (close to) dfDesired [Hz]

sVarDens_coarseNDArray[float64]

band averaged variance density spectrum of the signal on new frequency axis fCoarse [m^2/Hz]

Return type:

tuple[NDArray[float64], NDArray[float64]]

Example

>>> import numpy as np
>>> dt =0.1
>>> t = np.arange(0,1000+dt,dt)  # Time axis
>>> z = np.sin(t) + np.cos(2*t)  # Surface elevation data
>>> df = 0.01                    # Choose value for frequency axis
>>> [freq,varDens] = compute_spectrum_time_series(t,z,df)
deltares_wave_toolbox.cores.core_spectral.compute_spectrum_welch_wrapper(xTime: ndarray[tuple[Any, ...], dtype[float64]], dt: float, nperseg: int = 0, noverlap: int = 0, nfft: int = 0, window_type: str = 'hann') → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]][source]

Wrapper arround the Scipy Welch method

Parameters:

  • xTime (NDArray[float64]) – 1D array containing signal values, i.e. the time series of the signal. The value xTime(i) must be the signal value at time t(i). Usually water surface elevation [m]

  • dt (float) – time step of signal

  • nperseg (int, optional) – Length of each segment, by default None

  • noverlap (int, optional) – number of points in overlap, by default None

  • nfft (int, optional) – length of fft, by default None

  • window_type (str, optional) – window type, by default “hann”

Returns:

fNDArray[float64]

1D array containing frequency values, for folded Fourier transform. The number of elements in array f is close to half the number of elements in array xTime. To be precise, length(f) = floor(nT/2) + 1, with nT the number of elements in array xTime [Hz]

sVarDensNDArray[float64]

1D array containing variance density spectrum of the signal [m^2/Hz]

Return type:

tuple[NDArray[float64], NDArray[float64]]

deltares_wave_toolbox.cores.core_spectral.freq2time(xFreq: ndarray[tuple[Any, ...], dtype[complex128]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Transforms (unfolded) discrete Fourier transform back to time signal

This function transforms a given discrete and unfolded Fourier transform xFreq (in general a complex quantity!) back to time domain. Note that the input Fourier transform xFreq must be unfolded. A given folded Fourier transform can be unfolded using the function unfoldspectrum.

Parameters:

xFreq (NDArray[complex128]) – 1D array (complex!) containing the folded Fourier coefficients of xTime. The value xFreq(i) must be the Fourier coefficient at frequency f(i). The number of elements in f and xFreq are the same.

Returns:

1D array containing signal values, i.e. the time series of the signal. The value xTime(i) must be the signal value at time t(i). Usually water surface elevation [m]

Return type:

NDArray[float64]

Raises:

ValueError – Input error: input should be 1d arrays

Example

>>> import numpy as np
>>> # --- Create time signal
>>> dt =0.1   # s
>>> t = np.arange(0,100)*dt  # Time axis
>>> a1 = 0.5; w1 = 2*np.pi/5; phi1 = 0.35  # Wave component 1
>>> a2 = 0.7; w2 = 2*np.pi/6; phi2 = 0.96  # Wave component 2
>>> y = a1*np.cos(w1*t+phi1) + a2*np.cos(w2*t+phi2)
>>> # --- Compute discrete Fourier transform
>>> f,yFreq = time2freq(t,y)
>>> # --- Return to time domain
>>> yTime = freq2time(yFreq)  # yTime must be identical to y
deltares_wave_toolbox.cores.core_spectral.frequency_averaging(f: ndarray[tuple[Any, ...], dtype[float64]], sVarDens: ndarray[tuple[Any, ...], dtype[float64]], dfDesired: float = 0.0) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]][source]

Band averaging of given variance density spectrum

This function performs a band averaging on a given variance density spectrum sVarDens = sVarDens(f) on a frequency axis f onto a coarser frequency axis with frequency spacing dfDesired.

Parameters:

  • f (NDArray[float64]) – 1D array containing frequency values, for folded Fourier transform. The number of elements in array f is close to half the number of elements in array xTime. To be precise, length(f) = floor(nT/2) + 1, with nT the number of elements in array xTime [Hz]

  • sVarDens (NDArray[float64]) – 1D array containing variance density spectrum of the signal [m^2/Hz]

  • dfDesired (float, optional) – desired frequency spacing in Hertz on which the wave spectrum must be computed. If this parameter is omitted, then dfDesired = f(1) - f(0), by default 0.0 [Hz]

Returns:

f_coarseNDArray[float64]

frequency axis of computed spectrum. The frequency spacing is (close to) dfDesired [Hz]

sVarDens_coarseNDArray[float64]

band averaged variance density spectrum of the signal on frequency axis f_coarse [m^2/Hz]

Return type:

tuple[NDArray[float64], NDArray[float64]]

Raises:

ValueError – frequency_averaging: Input error: input should be 1d arrays

Example

>>> import numpy as np
>>> df        = 0.01 #Hz
>>> f         = np.arange(0,100)*df
>>> sVarDens  = np.random.normal(loc=1, scale=2, size=len(f))
>>> dfDesired = 0.02
>>> f_coarse,sVarDens_coarse = frequency_averaging(f,sVarDens,dfDesired)
deltares_wave_toolbox.cores.core_spectral.spectrum2timeseries(f: ndarray[tuple[Any, ...], dtype[float64]], sVarDens: ndarray[tuple[Any, ...], dtype[float64]], tInit: float, tEnd: float, dt: float, seed: int = -1) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]][source]

Generates a timeseries based on a given spectrum.

This function synthesises a time series xTime = xTime(t) satisfying a given 1D variance density spectrum sVarDens = sVarDens(f). The time axis is specified by the user as well, starting at time tInit, ending at time tEnd, with a uniform time step equal to dt. The random phase method is used to synthetise the time series.

Parameters:

  • f (NDArray[float64]) – 1D array containing frequency values, for folded Fourier transform. The number of elements in array f is close to half the number of elements in array xTime. To be precise, length(f) = floor(nT/2) + 1, with nT the number of elements in array xTime [Hz]

  • sVarDens (NDArray[float64]) – 1D array containing variance density spectrum of the signal [m^2/Hz]

  • tInit (float) – initial time of time axis. [s]

  • tEnd (float) – end time of time axis. [s]

  • dt (float) – time step of time axis. [s]

  • seed (int, optional) – Seed for random phases, by default -1

Returns:

tNDArray[float64]

time axis of computed spectrum. The time spacing is (close to) dt [s]

xTimeNDArray[float64]

time series of water level elevation [m]

Return type:

tuple[NDArray[float64], NDArray[float64]]

Raises:

  • ValueError – Input error: input should be 1d arrays

  • ValueError – Input error: array sizes differ in dimension

deltares_wave_toolbox.cores.core_spectral.spectrum2timeseries_object(f: ndarray[tuple[Any, ...], dtype[float64]], sVarDens: ndarray[tuple[Any, ...], dtype[float64]], tInit: float, tEnd: float, dt: float, seed: int = -1) → Series[source]

Generates a timeseries based on a given spectrum.

This function synthesises a time series xTime = xTime(t) satisfying a given 1D variance density spectrum sVarDens = sVarDens(f). The time axis is specified by the user as well, starting at time tInit, ending at time tEnd, with a uniform time step equal to dt. The random phase method is used to synthetise the time series.

Parameters:

  • f (NDArray[float64]) – 1D array containing frequency values, for folded Fourier transform. The number of elements in array f is close to half the number of elements in array xTime. To be precise, length(f) = floor(nT/2) + 1, with nT the number of elements in array xTime [Hz]

  • sVarDens (NDArray[float64]) – 1D array containing variance density spectrum of the signal [m^2/Hz]

  • tInit (float) – initial time of time axis. [s]

  • tEnd (float) – end time of time axis. [s]

  • dt (float) – time step of time axis. [s]

  • seed (int, optional) – Seed for random phases, by default -1

Returns:

Series object containing the time series of water level elevation

Return type:

series.Series

deltares_wave_toolbox.cores.core_spectral.time2freq(t: ndarray[tuple[Any, ...], dtype[float64]], xTime: ndarray[tuple[Any, ...], dtype[float64]]) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[complex128]]][source]

Computes the discrete Fourier transform coefficients (on unfolded frequency axis) of a given of time signal

This function computes the Fourier coefficients xFreq (in general complex quantities!) on frequency axis f (hence, xFreq = xFreq(f)), from a given time signal Xtime on time axis t (hence, xTime = xTime(t)).

The Fourier transform is not folded. This means, that the number of elements in arrays f and xFreq is identical to nT (nT: the number of elements in arrays t and xTime). Note that the Fourier coefficients in xFreq have a complex conjugate symmetry around the Nyquist frequency. Transforming the signal xFreq = xFreq(f) back to time domain can be done with the function freq2time

Parameters:

  • t (NDArray[float64]) – 1D real array containing time values. The numbers in the array t must be increasing and uniformly spaced (uniform time step). The initial time t(1) can be any value (so it is not obligatory to have t(1) = 0)

  • xTime (NDArray[float64]) – 1D array containing signal values, i.e. the time series of the signal. The value xTime(i) must be the signal value at time t(i). Usually water surface elevation [m]

Returns:

fNDArray[float64]

1D array containing frequency values, for folded Fourier transform. The number of elements in array f is close to half the number of elements in array xTime. To be precise, length(f) = floor(nT/2) + 1, with nT the number of elements in array xTime [Hz]

xFreqNDArray[complex128]

1D array (complex!) containing the unfolded Fourier coefficients of xTime. The value xFreq(i) must be the Fourier coefficient at frequency f(i). The number of elements in f and xFreq are the same. This number is the same as the number of elements in t and xTime.

Return type:

tuple[NDArray[float64], NDArray[complex128]]

Raises:

  • ValueError – Input error: input should be 1d arrays

  • ValueError – Input error: time input parameter must be monotonic with constant step size

  • ValueError – Input error: array sizes differ in dimension

Example

>>> import numpy as np
>>> # --- Create time signal
>>> dt =0.1 # s
>>> t = np.arange(0,100)*dt  # Time axis
>>> a1 = 0.5; w1 = 2*np.pi/5; phi1 = 0.35  # Wave component 1
>>> a2 = 0.7; w2 = 2*np.pi/6; phi2 = 0.96  # Wave component 2
>>> y = a1*np.cos(w1*t+phi1) + a2*np.cos(w2*t+phi2)
>>> # --- Compute discrete Fourier transform
>>> f,yFreq = time2freq(t,y)
deltares_wave_toolbox.cores.core_spectral.time2freq_nyquist(t: ndarray[tuple[Any, ...], dtype[float64]], xTime: ndarray[tuple[Any, ...], dtype[float64]]) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[complex128]], bool][source]

Computes the discrete Fourier transform coefficients (on folded frequency axis) of a given of time signal

This function computes the Fourier coefficients xFreq (in general complex quantities!) on frequency axis f (hence, xFreq = xFreq(f)), from a given time signal Xtime on time axis t (hence, xTime = xTime(t)).

The Fourier transform is folded. This means, that the number of elements in arrays f and xFreq is identical to floor(nT/2) + 1 (nT: the number of elements in arrays t and xTime). This means that the the Fourier coefficients are computed up to the Nyquist frequency. Transforming the signal xFreq = xFreq(f) back to time domain can be done using first the function unfoldspectrum and after that the function freq2time. Parameter isOdd=1 if nT is odd, and isOdd=0 if nT is even.

Parameters:

  • t (NDArray[float64]) – 1D array containing time axis. The numbers in the array t must be increasing and uniformly spaced (uniform time step) [s]

  • xTime (NDArray[float64]) – 1D array containing signal values, i.e. the time series of the signal. The value x(i) must be the signal value at time t(i). Usually water surface elevation [m]

Returns:

fNDArray[float64]

1D array containing frequency values, for folded Fourier transform. The frequency axis runs from 0 to the Nyquist frequency. The number of elements in array f is close to half the number of elements in array xTime. To be precise, length(f) = floor(nT/2) + 1, with nT the number of elements in array xTime [Hz]

xFreqNDArray[complex128]

1D array (complex!) containing the folded Fourier coefficients of xTime. The value xFreq(i) must be the Fourier coefficient at frequency f(i). The number of elements in f and xFreq are the same.

isOddbool

logical indicating whether nT, the number of time points in xTime, is even (isOdd=False) or odd (isOdd=True)

Return type:

tuple[NDArray[float64], NDArray[complex128], bool]

Raises:

  • ValueError – Input error: input should be 1d arrays

  • ValueError – Input error: time input parameter must be monotonic with constant step size

  • ValueError – Input error: array sizes differ in dimension

Example

>>> import numpy as np
>>> dt        = 0.1 #Hz
>>> t         = np.arange(0,100)*dt
>>> a1 = 0.5; w1 = 2*np.pi/5; phi1 = 0.35;  # Wave component 1
>>> a2 = 0.7; w2 = 2*np.pi/6; phi2 = 0.96;  # Wave component 2
>>> y = a1*np.cos(w1*t+phi1) + a2*np.cos(w2*t+phi2)
>>> print(t)
>>> print(y)
>>> # --- Compute discrete Fourier transform
>>> f,yFreq,isOdd = time2freq_nyquist(t,y);
deltares_wave_toolbox.cores.core_spectral.unfold_spectrum(f: ndarray[tuple[Any, ...], dtype[float64]], xFreq: ndarray[tuple[Any, ...], dtype[complex128]], isOdd: bool) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[complex128]]][source]

Unfolds a folded discrete Fourier transform

This function unfolds a folded discrete Fourier transform xFreq that is given at frequency axis f. Note that this frequency axis goes up to the Nyquist frequency. Parameter isOdd indicates whether the underlying original time signal - of which xFreq is the discrete Fourier transform - has even (isOdd=0) or odd (isOdd=1) time points.

The unfolded discrete Fourier xFreqTot, at frequency axis fTot, can be inverted back to time domain using function freq2time

Parameters:

  • f (NDArray[float64]) – 1D array containing frequency values, for folded Fourier transform. The number of elements in array f is close to half the number of elements in array xTime. To be precise, length(f) = floor(nT/2) + 1, with nT the number of elements in array xTime [Hz]

  • xFreq (NDArray[complex128]) – 1D array (complex!) containing the folded Fourier coefficients of xTime. The value xFreq(i) must be the Fourier coefficient at frequency f(i). The number of elements in f and xFreq are the same.

  • isOdd (bool) – logical indicating whether nT, the number of time points in original time series, is even (isOdd=False) or odd (isOdd=True)

Returns:

fTotNDArray[float64]

1D array containing frequency values, for unfolded Fourier transform. The frequency axis runs from 0 to twice the Nyquist frequency. Array fTot contains as many elements as the original time series. [Hz]

xFreqTotNDArray[complex128]

1D array (complex!) containing the unfolded Fourier coefficients of original time series. The value xFreqTot(i) must be the Fourier coefficient at frequency fTot(i). The number of elements in fTot and xFreqTot are the same.

Return type:

tuple[NDArray[float64], NDArray[complex128]]

Raises:

ValueError – Input error: input should be 1d arrays

Example

>>> import numpy as np
>>> dt            = 0.1 # s
>>> t             = np.arange(0,100) *dt  # Time axis
>>> a1 = 0.5; w1  = 2*np.pi/5; phi1 = 0.35  # Wave component 1
>>> a2 = 0.7; w2  = 2*np.pi/6; phi2 = 0.96  # Wave component 2
>>> y = a1*np.cos(w1*t+phi1) + a2*np.cos(w2*t+phi2)
>>> # --- Compute folded discrete Fourier transform
>>> f,yFreq,isOdd = time2freq_nyquist(t,y);
>>> # --- Unfold the discrete Fourier transform
>>> fTot,yFreqTot = unfold_spectrum(f,yFreq,isOdd)
>>> # --- Return to time domain
>>> yTime         = freq2time(yFreqTot)  # yTime must be identical to y

deltares_wave_toolbox.cores.core_time module

deltares_wave_toolbox.cores.core_time.determine_params_individual_waves(tCross: ndarray[tuple[Any, ...], dtype[float64]], t: ndarray[tuple[Any, ...], dtype[float64]], xTime: ndarray[tuple[Any, ...], dtype[float64]]) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]][source]

Determines parameters per individual wave

This function determines several wave properties (wave period, wave height, crest amplitude, trough amplitude, and the time at which the maximum crest and trough amplitudes occur) of all individual waves in a wave train. The wave train is given by time series xTime = xTime(t), and the zero-crossings occur at time levels given in tCross

Parameters:

  • tCross (NDArray[float64]) – 1D array of length (nWave+1), containing the time of all zero-crossings. The time of the zero-crossings is determined by linear interpolation. Note that in case of no zero-crossing, the array tCross is empty. Note that in case of one zero-crossing, the number of waves is zero. [s]

  • t (NDArray[float64]) – 1D array containing time axis. The numbers in the array t must be increasing and uniformly spaced (uniform time step) [s]

  • xTime (NDArray[float64]) – 1D array containing signal values, i.e. the time series of the signal. The value xTime(i) must be the signal value at time t(i). Usually water surface elevation [m]

Returns:

tWaveNDArray[float64]

1D array containing the periods of the individual waves [s]

hWaveNDArray[float64]

1D array containing the wave heights of the individual waves [m]

aCrestNDArray[float64]

1D array containing the maximum amplitude of the crests of the individual waves [m]

aTroughNDArray[float64]

1D array containing the maximum amplitude of the troughs of the individual waves [m]

tCrestNDArray[float64]

1D array containing the time at which maximum crest amplitude of the individual waves occurs [s]

tTroughNDArray[float64]

1D array containing the time at which maximum trough amplitude of the individual waves occurs [s]

Return type:

tuple[ NDArray[float64], NDArray[float64], NDArray[float64], NDArray[float64], NDArray[float64], NDArray[float64], ]

Notes

  • All these arrays have a length equal to nWave, which is the number of waves in the wave train

  • The values of aTrough are always smaller than zero

  • hWave = aCrest - aTrough

Raises:

  • ValueError – Input error: Input arrays tCross is not 1D

  • ValueError – Input error: Input arrays t is not 1D

  • ValueError – Input error: Input arrays x is not 1D

  • ValueError – Length of input arrays t and x not identical

deltares_wave_toolbox.cores.core_time.determine_zero_crossing(t: ndarray[tuple[Any, ...], dtype[float64]], xTime: ndarray[tuple[Any, ...], dtype[float64]], typeCross: str = 'down') → tuple[int, ndarray[tuple[Any, ...], dtype[float64]]][source]

Determines zero-crossings (number and positions) of signal.

This function determines the zero-crossings of a given time signal xTime = xTime(t). Here, t stands for time, and xTime for a given signal (for example, time series of measured surface elevation). The type of zero-crossing can be either up-crossing or down-crossing.

Parameters:

  • t (NDArray[float64]) – 1D array containing time axis. The numbers in the array t must be increasing and uniformly spaced (uniform time step) [s]

  • xTime (NDArray[float64]) – 1D array containing signal values, i.e. the time series of the signal. The value xxTime(i) must be the signal value at time t(i). Usually water surface elevation [m]

  • typeCross (str, optional) – Search for up- or down-crossings, by default “down”

Returns:

nWaveint

Number of waves in the signal, where one wave corresponds to two successive zero-crossings. Wave i starts at time tCross(i), and end at time tCross(i+1) [-]

tCrossNDArray[float64]

1D array of length (nWave+1), containing the time of all zero-crossings. The time of the zero-crossings is determined by linear interpolation. Note that in case of no zero-crossing, the array tCross is empty. Note that in case of one zero-crossing, the number of waves is zero. [s]

Return type:

tuple[int, NDArray[float64]]

Raises:

  • ValueError – Input error: Input arrays t is not 1D

  • ValueError – Input error: Input arrays x is not 1D

  • ValueError – Input error: Input arrays t and x have different length

  • ValueError – Input error: Wrong input argument for typeCross

deltares_wave_toolbox.cores.core_time.exceedance_wave_height(hWaveSorted: ndarray[tuple[Any, ...], dtype[float64]], excPerc: float) → float[source]

Computes wave height with given exceedance probability

This function computes the wave height hExcPerc with given exceedance probability percentage excPerc.

Parameters:

  • hWaveSorted (NDArray[float64]) – 1D array containing wave heights of the individual waves, sorted in descending order [m]

  • excPerc (float) – exceedance probability percentage. excPerc = 2 means an exceedance percentage of 2%. The value of excPerc should not exceed 100, or be smaller than 0 [%]

Returns:

hExcPercfloat

wave height with given exceedance probability [m]

Return type:

float

Raises:

  • ValueError – Input error: Input arrays hWaveSorted is not 1D

  • ValueError – Input error: Input parameter excPerc should be between 0 and 100

  • ValueError – Input error:Input array hWaveSorted is not correctly sorted

Example

>>> import numpy as np
>>> hWaveSorted = [7.1, 6.0, 5.8, 4.4, 3.1, 2.2, 1.4]
>>> [hExcPerc_33perc] = exceedance_wave_height(hWaveSorted,33)
deltares_wave_toolbox.cores.core_time.highest_waves_params(hWaveSorted: ndarray[tuple[Any, ...], dtype[float64]], tWaveSorted: ndarray[tuple[Any, ...], dtype[float64]], fracP: float) → tuple[float, float][source]

Computes wave parameters of selection largest waves

This function computes the wave height hFracP and wave period tFracP by taking the average of the fraction fracP of the highest waves. When fracP = 1/3, then hFracP is equal to the significant wave height and tFracP is equal to the significant wave period.

Parameters:

  • hWaveSorted (NDArray[float64]) – 1D array containing wave heights of the individual waves, sorted in descending order [m]

  • tWaveSorted (NDArray[float64]) –

    1D array containing wave periods of the individual waves, using the same sorting (re-arranging) as

    applied to hWave [s]

  • fracP (float) – fraction. Should be between 0 and 1 [-]

Returns:

hFracPfloat

average of the wave heights of the highest fracP waves [m]

tFracPfloat

average of the wave periods of the highest fracP waves [s]

Return type:

tuple[float, float]

Raises:

  • ValueError – Input error: Input arrays hWaveSorted is not 1D

  • ValueError – Input error: Input arrays tWaveSorted is not 1D

  • ValueError – Input arrays tWaveSorted and hWaveSorted have different length

  • ValueError – Input error: Input parameter fracP should be between 0 and 1

  • ValueError – Input error:Input array hWaveSorted is not correctly sorted

Example

>>> import numpy as np
>>> hWaveSorted = [7.1, 6.0, 5.8, 4.4, 3.1, 2.2, 1.4]
>>> tWaveSorted = [5.1, 3.2, 3.7, 0.0, 2.0, 3.0, 1.1]
>>> [Hsig,Tsig] = highest_waves_params(hWaveSorted,tWaveSorted,1/3)
deltares_wave_toolbox.cores.core_time.sort_wave_params(hWave: ndarray[tuple[Any, ...], dtype[float64]], tWave: ndarray[tuple[Any, ...], dtype[float64]]) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]][source]

Sorts the wave height and wave period

This functions sorts the wave heights and wave periods in arrays hWave and tWave, and stores them in arrays hWaveSorted and tWaveSorted. The sorting is done such that in hWaveSorted the wave heights of hWave are sorted in descending order. This same sorting is applied to tWave, with the result in tWaveSorted. This means that hWaveSorted(i) and hWaveSorted(i) correspond to the wave height and wave period of the same wave.

Parameters:

  • hWave (NDArray[float64]) – 1D array containing the wave heights of the individual waves [m]

  • tWave (NDArray[float64]) – 1D array containing the periods of the individual waves [s]

Returns:

hWaveSortedNDArray[float64]

1D array containing wave heights of the individual waves, sorted in descending order [m]

tWaveSortedNDArray[float64]

1D array containing wave periods of the individual waves, using the same sorting (re-arranging) as applied to hWave [s]

Return type:

tuple[NDArray[float64], NDArray[float64]]

Raises:

  • ValueError – Input error, Input arrays hWave is not 1D

  • ValueError – Input error, Input array tWave is not 1D

  • ValueError – Input arrays hWave and tWave have different length

Example

>>> import numpy as np
>>> hWave = np.asrange([2,4,3])
>>> tWave = np.asrange([6,7,8])
>>> # Then we get:
>>> [hWaveSorted, tWaveSorted] = sort_wave_params(hWave,tWave)
>>> #hWaveSorted = np.asrange([4,3,2])
>>> #tWaveSorted = np.asrange([7,8,6])  (and not: tWaveSorted = [8 7 6])

deltares_wave_toolbox.cores.core_wave_decomposition module

deltares_wave_toolbox.cores.core_wave_decomposition.decompose_linear_ZS(t: ndarray[tuple[Any, ...], dtype[float64]], xTime: ndarray[tuple[Any, ...], dtype[float64]], h: ndarray[tuple[Any, ...], dtype[float64]], x_loc: ndarray[tuple[Any, ...], dtype[float64]], w_loc: ndarray[tuple[Any, ...], dtype[float64]], detLim: float = 0.125) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]][source]

decompose_linear_ZS Separation of incident and reflected waves using Zelt & Skjelbreia’s method.

This function performs the separation of incident and reflected waves according to the Zelt & Skjelbreia’s procedure. Time series of wave signals xTime(Ntime,Nloc) at locations x_loc(Nloc) need to be provided. All wave gauges are assigned a weight w_loc(Nloc). Waves can only propagate in the positive x-direction (incoming wave) and the negative x-direction (reflected wave). The water depth h is assumed to be uniform. Time series of the incident and reflected wave in location x_loc(1) are provided as output of this function.

For Nloc = 2 and w_loc = [1 1], this reduces to Goda’s and Suzuki’s method. For Nloc = 3 and w_loc = [1 1 1], this reduces to Mansard-Funke method.

Parameters:

  • t – 1D real array containing Ntime time values. The numbers in the array t must be increasing and uniformly spaced (uniform time step). The initial time t(1) can be any value (so it is not obligatory to have t(1) = 0). Units: seconds

  • xTime – real array of size [Ntime,Nloc] containing the time series of the surface elevation in locations x_loc. Units: meters

  • h – depth, in meters. Assumed to be uniform

  • x_loc – 1D real array with Nloc entries indicating the locations where the time signals are measured.

  • w_loc – 1D real array with Nloc entries indicating the weights of the signals. The values of w_loc must be between zero and 1.

  • detLim –

    Optional parameter, with default value 0.125. This parameter, which is essentially borrowed from the Mansard-Funke function, indicates the value of the matrix determinantabove which the Mansard-Funke procedure is applied. When thedeterminant is below the value detLim, a more crude splitting procedure is applied. The value of detLim must be small and positive. Parameter detLim is related to the parameter denominator in the Auke-Process input. The relation reads:

    denominator = 9 - 4 * detLim.

    Hence, for detLim = 0.125, we get denominator = 8.5 (default value in Auke-Process).

Returns:

  • xTime1In – 1D real array containing time signal of incident wave (i.e. propagating in positive x-direction), in location x_loc(1)

  • xTime1Re – 1D real array containing time signal of reflected wave (i.e. propagating in negative x-direction), in location x_loc(1)

  • Remark –

    • The wave signals must be ordered such that x_loc(1) < x_loc(2) < ….

    • Nloc must be two or larger

    • The sum of the weights w_loc must be two or larger

  • Syntax – xTime1In,xTime1Re = decompose_linear_ZS(t,xTime,h,x_loc,w_loc,detLim)

deltares_wave_toolbox.cores.core_wave_decomposition.decompose_linear_ZS_series(Series_objects: list[Series], h: ndarray[tuple[Any, ...], dtype[float64]], x_loc: ndarray[tuple[Any, ...], dtype[float64]], w_loc: ndarray[tuple[Any, ...], dtype[float64]], detLim: float = 0.125)[source]

Separation of incident and reflected waves using the Zelt & Skjelbreia (1992) method.

This is a wrapper function for the decompose_linear_ZS function, made compatible with the Series class from the Deltares Wave Toolbox.

This function performs the separation of incident and reflected waves according to the Zelt & Skjelbreia (1992) procedure. Time series of wave signals xTime(Ntime,Nloc) at locations x_loc(Nloc) need to be provided. All wave gauges are assigned a weight w_loc(Nloc). Waves can only propagate in the positive x-direction (incoming wave) and the negative x-direction (reflected wave). The water depth h is assumed to be uniform. Time series of the incident and reflected wave in location x_loc(1) are provided as output of this function.

For Nloc = 2 and w_loc = [1 1], this reduces to Goda’s and Suzuki’s method. For Nloc = 3 and w_loc = [1 1 1], this reduces to Mansard-Funke method.

Parameters:

  • Series_objects (list[series.Series]) – List of Series objects containing the time series of the surface elevation in locations x_loc.

  • h (NDArray[float64]) – depth, in meters. Assumed to be uniform

  • x_loc (NDArray[float64]) – 1D real array with Nloc entries indicating the locations where the time signals are measured.

  • w_loc (NDArray[float64]) – 1D real array with Nloc entries indicating the weights of the signals. The values of w_loc must be between zero and 1.

  • detLim (float, optional) –

    Optional parameter, by default 0.125

    This parameter, which is essentially borrowed from the Mansard-Funke function, indicates the value of the matrix determinantabove which the Mansard-Funke procedure is applied. When thedeterminant is below the value detLim, a more crude splitting procedure is applied. The value of detLim must be small and positive. Parameter detLim is related to the parameter denominator in the Auke-Process input. The relation reads:

    denominator = 9 - 4 * detLim

Returns:

  • xTime1In – 1D real array containing time signal of incident wave (i.e. propagating in positive x-direction), in location x_loc(1)

  • xTime1Re – 1D real array containing time signal of reflected wave (i.e. propagating in negative x-direction), in location x_loc(1)

deltares_wave_toolbox.cores.core_wavefunctions module

deltares_wave_toolbox.cores.core_wavefunctions.compute_BattjesGroenendijk_wave_height_distribution(hm0: float, nwave: int, water_depth: float, cota_slope: float = 250.0, tolerance: float = 1e-05) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]][source]

Computes wave height distribution following Battjes and Groenendijk (2000)

Wave height distribution for sloping, shallow bottoms, as proposed by Battjes and Groenendijk (2000).

Parameters:

  • hm0 (float) – spectral wave height [m]

  • nwave (int) – number of waves [-]

  • water_depth (float) – water depth [m]

  • cota_slope (float, optional) – cotangent of the bottom slope [-], by default 250.0

  • tolerance (float, optional) – tolerance for convergence of transition wave height [-], by default 1e-5

Returns:

hWave_BGNDArray[float64]

theoretical Battjes & Groenendijk (2000) wave height distribution [m]

Pexceedance_BGNDArray[float64]

theoretical Battjes & Groenendijk (2000) wave height exceedance probability [-]

Return type:

tuple[NDArray[float64], NDArray[float64]]

Example

>>> Hm0 = 2.0
>>> nwave = 700
>>> water_depth = 4.5
>>> cota_slope = 50
>>> tolerance = 1e-5
>>> hwave_BG, Pexceedance_BG = compute_BattjesGroenendijk_wave_height_distribution(Hm0, nwave, water_depth,
    cota_slope=cota_slope, tolerance=tolerance)
deltares_wave_toolbox.cores.core_wavefunctions.compute_moment(f: ndarray[tuple[Any, ...], dtype[float64]], sVarDens: ndarray[tuple[Any, ...], dtype[float64]], m: int, fmin: float = -1.0, fmax: float = -1.0) → float[source]

Computes the spectral moment

This function computes the m’th order spectral moment of variance density spectrum S=S(f), with f the frequency axis, over frequency domain [fmin,fmax].

It is required that fmin >= f_in(1).

It is not required to have fmax <= f_in(end). So it ok to have fmax = Inf. If fmax>f(end), then the moment consists of the summation of two parts: (1) Integration of (f_in^m * S), with given S, over [fmin,f(end)] (2) Exact integration of (f^m * S_lim) over [f(end),fmax], where S_lim is a high-frequency f^(-5) tail. Typically, in such cases one puts fmax = Inf.

Parameters:

  • f (NDArray[float64]) – 1D array containing frequency values. The numbers in the array f must be increasing and uniformly spaced (uniform frequency step). [Hz]

  • sVarDens (NDArray[float64]) – 1D array containing variance density spectrum of the signal [m^2/Hz]

  • m (int) – order of moment

  • fmin (float, optional) – lower bound of the moment integral [Hz], by default -1.0

  • fmax (float, optional) – upper bound of the moment integral [Hz], by default -1.0

Returns:

the computed moment

Return type:

float

Raises:

  • ValueError – Input error: input should be 1d arrays

  • ValueError – Input error: frequency input parameter must be monotonic with constant step size

  • ValueError – Input error: array sizes differ in dimension

Example

>>> import numpy as np
>>> f = np.arange(0,1,0.1)
>>> Tp = 5.0
>>> Hm0 = 1.0
>>> fmin =0.01
>>> fmax =1
>>> sPM = create_spectrum_piersonmoskowitz(f,1/Tp,Hm0)
>>> m_1 = compute_moment(f,sPM,-1)
>>> m0  = compute_moment(f,sPM,0)
>>> m1  = compute_moment(f,sPM,1)
>>> m2  = compute_moment(f,sPM,2)
deltares_wave_toolbox.cores.core_wavefunctions.compute_spectrum_params(f: ndarray[tuple[Any, ...], dtype[float64]], sVarDens: ndarray[tuple[Any, ...], dtype[float64]], fmin: float = -1.0, fmax: float = -1.0) → tuple[float, float, float, float, float, float][source]

Computes spectral parameters of given spectrum

This function computes several spectral wave parameters of a given 1D spectrum

Parameters:

  • f (NDArray[float64]) – 1D array containing frequency values. The numbers in the array f must be increasing and uniformly spaced (uniform frequency step). [Hz]

  • sVarDens (NDArray[float64]) – 1D array containing variance density spectrum of the signal [m^2/Hz]

  • fmin (float, optional) – lower bound of the moment integral [Hz], by default -1.0

  • fmax (float, optional) – upper bound of the moment integral [Hz], by default -1.0

Returns:

Hm0float

spectral wave height [m]

Tpfloat

peak period [s]

Tpsfloat

smoothed peak period [s]

Tmm10float

wave period based on (-1) and (0) moments [s]

Tm01float

wave period based on (0) and (1) moments [s]

Tm02float

wave period based on (0) and (2) moments [s]

Return type:

tuple[float, float, float, float, float, float]

Raises:

  • ValueError – Input error: input should be 1d arrays

  • ValueError – Input error: frequency input parameter must be monotonic with constant step size

  • ValueError – Input error: array sizes differ in dimension

Example

>>> import numpy as np
>>> f = np.arange(0,1,0.1)
>>> Tp = 5.0
>>> Hm0 = 1.0
>>> fmin =0.01
>>> fmax =1.0
>>> sPM = create_spectrum_piersonmoskowitz(f,1/Tp,Hm0)
>>> [Hm0,Tp,Tps,Tmm10,Tm01,Tm02] = compute_spectrum_params(f,sPM,fmin,fmax)
deltares_wave_toolbox.cores.core_wavefunctions.compute_tps(f: ndarray[tuple[Any, ...], dtype[float64]], sVarDens: ndarray[tuple[Any, ...], dtype[float64]]) → float[source]

Computes smoothed peak period.

This function computes the smoothed peak period Tps, by means of quadratic interpolation, of a given variance density spectrum S = S(f).

Parameters:

  • f (NDArray[float64]) – 1D array containing frequency values. The numbers in the array f must be increasing and uniformly spaced (uniform frequency step). [Hz]

  • sVarDens (NDArray[float64]) – 1D array containing variance density spectrum of the signal [m^2/Hz]

Returns:

smoothed peak period [s]

Return type:

float

Raises:

  • ValueError – Input error: input should be 1d arrays

  • ValueError – Input error: frequency input parameter must be monotonic with constant step size

  • ValueError – Input error: array sizes differ in dimension

Example

>>> import numpy as np
>>> f=np.arange(0,2,0.01)
>>> Tp = 5.0
>>> hm0 =1.0
>>> sPM = create_spectrum_piersonmoskowitz(f,1/Tp,hm0)
>>> Tps = compute_tps(f,sPM)
deltares_wave_toolbox.cores.core_wavefunctions.create_spectrum_jonswap(f: ndarray[tuple[Any, ...], dtype[float64]], fp: float, hm0: float, gammaPeak: float = 3.3, l_fmax: float = 0.0) → ndarray[tuple[Any, ...], dtype[float64]][source]

Creates a Jonswap spectrum

This function creates the Jonswap variance density spectrum, based on a given frequency axis, wave height, peak frequency and peak enhancement factor. Literature: Hasselman, K., e.a. (1973), Erga”nzungsheft zur Deutschen Hydrographischen Zeitschrift, Reihe A(8), No. 12

For l_fmax = 0, the sVarDens is such that integration from f(1) to f(end) leads exactly to the given Hm0. For l_fmax = 1, integration from [f(end},inf] is computed using a (-5)-power law. This also means that integration from f(1) to f(end) leads to a slightly smaller value for the wave height than the prescribed Hm0.

Parameters:

  • f (NDArray[float64]) – 1D array containing frequency values. The numbers in the array f must be increasing and uniformly spaced (uniform frequency step). [Hz]

  • fp (float) – peak frequency. [Hz]

  • hm0 (float) – spectral wave height [m]

  • gammaPeak (float, optional) – peak enhancement factor, by default 3.3

  • l_fmax (float, optional) – The imposed spectral wave height Hm0 holds for the frequency range [f(1),f(end)] (l_fmax = 0, default) or for the frequency range [f(1),inf] (l_fmax = 1)., by default 0

Returns:

1D array containing variance density [m^2/Hz]

Return type:

NDArray[float64]

Raises:

  • ValueError – Input error: Input array f is not 1D

  • ValueError – Input error:Argument l_fmax must be either 0 or 1

Example

>>> import numpy as np
>>> f=np.arange(0,2,0.1)
>>> Tp = 5.0
>>> hm0 =1.5
>>> S = create_spectrum_jonswap(f,1/Tp,hm0,3.3)
deltares_wave_toolbox.cores.core_wavefunctions.create_spectrum_object_jonswap(f: ndarray[tuple[Any, ...], dtype[float64]], fp: float, hm0: float, gammaPeak: float = 3.3, l_fmax: float = 0.0) → Spectrum[source]

Creates a Jonswap spectrum object

This function creates the Jonswap variance density spectrum, based on a given frequency axis, wave height, peak frequency and peak enhancement factor.

Literature: Hasselman, K., e.a. (1973), Erga”nzungsheft zur Deutschen Hydrographischen Zeitschrift, Reihe A(8), No. 12

For l_fmax = 0, the sVarDens is such that integration from f(1) to f(end) leads exactly to the given Hm0. For l_fmax = 1, integration from [f(end},inf] is computed using a (-5)-power law. This also means that integration from f(1) to f(end) leads to a slightly smaller value for the wave height than the prescribed Hm0.

Parameters:

  • f (NDArray[float64]) – 1D array containing frequency values. The numbers in the array f must be increasing and uniformly spaced (uniform frequency step). [Hz]

  • fp (float) – peak frequency. [Hz]

  • hm0 (float) – spectral wave height [m]

  • gammaPeak (float, optional) – peak enhancement factor, by default 3.3

  • l_fmax (float, optional) – The imposed spectral wave height Hm0 holds for the frequency range [f(1),f(end)] (l_fmax = 0, default) or for the frequency range [f(1),inf] (l_fmax = 1), by default 0

Returns:

Spectrum object

Return type:

spectrum.Spectrum

deltares_wave_toolbox.cores.core_wavefunctions.create_spectrum_object_piersonmoskowitz(f: ndarray[tuple[Any, ...], dtype[float64]], fp: float, hm0: float, gammaPeak: float = 1.0, l_fmax: float = 0) → Spectrum[source]

Creates a Pierson-Moskowitz spectrum object

This function creates the Pierson-Moskowitz variance density spectrum, based on agiven frequency axis, wave height and peak frequency. The Pierson-Moskowitz spectrum is identical to the Jonswap spectrum with a peak enhancement factor equal to 1. Furthermore, the Pierson-Moskowitz spectrum, the Bretschneider spectrum and the ITTC spectrum are all three identical.

Literature: Pierson, W.J. and L. Moskowitz (1964). A proposed spectral form for fully developed wind seas based on the similarity theory of S.A. Kitaigorodskii. Journal of Geophysical Research,Vol. 69, No. 24, pg. 5181 - 5190.

For l_fmax = 0, the sVarDens is such that integration from f(1) to f(end) leads exactly to the given Hm0. For l_fmax = 1, integration from [f(end},inf] is computed using a (-5)-power law. This also means that integration from f(1) to f(end) leads to a slightly smaller value for the wave height than the prescribed Hm0.

Parameters:

  • f (NDArray[float64]) – 1D array containing frequency values. The numbers in the array f must be increasing and uniformly spaced (uniform frequency step). [Hz]

  • fp (float) – peak frequency. [Hz]

  • hm0 (float) – spectral wave height [m]

  • gammaPeak (float, optional) – peak enhancement factor, by default 1.0

  • l_fmax (float, optional) – The imposed spectral wave height Hm0 holds for the frequency range [f(1),f(end)] (l_fmax = 0, default) or for the frequency range [f(1),inf] (l_fmax = 1), by default 0

Returns:

Spectrum object

Return type:

spectrum.Spectrum

deltares_wave_toolbox.cores.core_wavefunctions.create_spectrum_piersonmoskowitz(f: ndarray[tuple[Any, ...], dtype[float64]], fp: float, hm0: float, gammaPeak: float = 1.0, l_fmax: float = 0.0) → ndarray[tuple[Any, ...], dtype[float64]][source]

Creates a Pierson-Moskowitz spectrum

This function creates the Pierson-Moskowitz variance density spectrum, based on agiven frequency axis, wave height and peak frequency. The Pierson-Moskowitz spectrum is identical to the Jonswap spectrum with a peak enhancement factor equal to 1. Furthermore, the Pierson-Moskowitz spectrum, the Bretschneider spectrum and the ITTC spectrum are all three identical.

Literature: Pierson, W.J. and L. Moskowitz (1964). A proposed spectral form for fully developed wind seas based on the similarity theory of S.A. Kitaigorodskii. Journal of Geophysical Research,Vol. 69, No. 24, pg. 5181 - 5190.

For l_fmax = 0, the sVarDens is such that integration from f(1) to f(end) leads exactly to the given Hm0. For l_fmax = 1, integration from [f(end},inf] is computed using a (-5)-power law. This also means that integration from f(1) to f(end) leads to a slightly smaller value for the wave height than the prescribed Hm0.

Parameters:

  • f (NDArray[float64]) – 1D array containing frequency values. The numbers in the array f must be increasing and uniformly spaced (uniform frequency step). [Hz]

  • fp (float) – peak frequency. [Hz]

  • hm0 (float) – spectral wave height [m]

  • gammaPeak (float, optional) – peak enhancement factor, by default 1.0

  • l_fmax (float, optional) – The imposed spectral wave height Hm0 holds for the frequency range [f(1),f(end)] (l_fmax = 0, default) or for the frequency range [f(1),inf] (l_fmax = 1), by default 0

Returns:

1D array containing variance density [m^2/Hz]

Return type:

NDArray[float64]

Example

>>> import numpy as np
>>> f=np.arange(0,2,0.01)
>>> Tp = 5.0
>>> hm0 =1.5
>>> Spm = create_spectrum_piersonmoskowitz(f,1/Tp,hm0)
deltares_wave_toolbox.cores.core_wavefunctions.tpd(f: ndarray[tuple[Any, ...], dtype[float64]], sVarDens: ndarray[tuple[Any, ...], dtype[float64]]) → float[source]

Function which calculates the spectral period (s)

For definition of TpD: transition from peak wave period to spectral period for the design of placed block revetments

Parameters:

  • f (NDArray[float64]) – 1D array containing frequency values. The numbers in the array f must be increasing and uniformly spaced (uniform frequency step). [Hz]

  • sVarDens (NDArray[float64]) – 1D array containing variance density spectrum of the signal [m^2/Hz]

Returns:

spectral period [s]

Return type:

float