From 07077ff98a94263a08739811659e770914ec4695 Mon Sep 17 00:00:00 2001 From: Ali Cetin Date: Tue, 15 Apr 2025 10:38:13 +0200 Subject: [PATCH 1/6] expand doc --- docs/user_guide/standardized_spectra.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/user_guide/standardized_spectra.rst b/docs/user_guide/standardized_spectra.rst index 85c94e63..b87ccb14 100644 --- a/docs/user_guide/standardized_spectra.rst +++ b/docs/user_guide/standardized_spectra.rst @@ -338,3 +338,18 @@ according to: where :math:`s` is a spreading coefficient, and :math:`\Gamma` is the Gamma function. + +In addition, the spreading functions may be used to determine discrete direction +bins with equal energy. + +.. code:: python + + import waveresponse as wr + + + spread_fun = wr.CosineFullSpreading(s=2, degrees=True) + discrete_dirs = spread_fun.discrete_directions(5, direction_offset=0.0) + + +The discrete directions may be used to spread 1-D 'non-directional' wave +spectrum into waves with equal energy. \ No newline at end of file From 2f9d086a847fc056e2df1573de9858b835237068 Mon Sep 17 00:00:00 2001 From: Ali Cetin Date: Tue, 15 Apr 2025 10:47:12 +0200 Subject: [PATCH 2/6] some update --- docs/user_guide/standardized_spectra.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user_guide/standardized_spectra.rst b/docs/user_guide/standardized_spectra.rst index b87ccb14..f443ef86 100644 --- a/docs/user_guide/standardized_spectra.rst +++ b/docs/user_guide/standardized_spectra.rst @@ -339,8 +339,8 @@ according to: where :math:`s` is a spreading coefficient, and :math:`\Gamma` is the Gamma function. -In addition, the spreading functions may be used to determine discrete direction -bins with equal energy. +In addition, the spreading functions in ``waveresponse`` cand determine discrete +direction bins with equal energy: .. code:: python @@ -351,5 +351,5 @@ bins with equal energy. discrete_dirs = spread_fun.discrete_directions(5, direction_offset=0.0) -The discrete directions may be used to spread 1-D 'non-directional' wave -spectrum into waves with equal energy. \ No newline at end of file +which may be used to spread 1-D 'non-directional' wave spectrum into waves +with equal energy. \ No newline at end of file From 8560a0cb84b6655bd6589f7a940581d00cc72d67 Mon Sep 17 00:00:00 2001 From: Ali Cetin Date: Tue, 15 Apr 2025 10:49:33 +0200 Subject: [PATCH 3/6] add bin to api --- docs/api_ref/index.rst | 2 ++ src/waveresponse/_core.py | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/api_ref/index.rst b/docs/api_ref/index.rst index 7f9041cd..0fb33a8a 100644 --- a/docs/api_ref/index.rst +++ b/docs/api_ref/index.rst @@ -19,6 +19,7 @@ functions and methods. complex_to_polar CosineFullSpreading CosineHalfSpreading + DirectionalBinSpectrum DirectionalSpectrum Grid JONSWAP @@ -33,6 +34,7 @@ functions and methods. rigid_transform_heave rigid_transform_surge rigid_transform_sway + WaveBinSpectrum WaveSpectrum diff --git a/src/waveresponse/_core.py b/src/waveresponse/_core.py index 537e6281..d11839ec 100644 --- a/src/waveresponse/_core.py +++ b/src/waveresponse/_core.py @@ -1833,7 +1833,7 @@ class DirectionalBinSpectrum(_SpectrumMixin, Grid): """ Directional binned spectrum. - The ``DirectionalBinSpectrum`` class extends the :class:`~waveresponse.BinGrid` + The ``DirectionalBinSpectrum`` class extends the :class:`~waveresponse.Grid` class and represents a two-dimensional frequency/wave-direction grid. The spectrum values represent spectral density as a function of frequency, binned by direction. From 6fd7533e15e2880db05071ee056606e9e5cd81b4 Mon Sep 17 00:00:00 2001 From: Ali Cetin Date: Tue, 15 Apr 2025 10:53:25 +0200 Subject: [PATCH 4/6] minor --- docs/user_guide/calculate_response.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/user_guide/calculate_response.rst b/docs/user_guide/calculate_response.rst index 4df8da0d..35c2eca8 100644 --- a/docs/user_guide/calculate_response.rst +++ b/docs/user_guide/calculate_response.rst @@ -109,8 +109,7 @@ and provides useful spectrum operations, such as: .. math:: S_x(\omega, \theta) = H_x(\omega, \theta)H_x^{*}(\omega, \theta) S_{\zeta}(\omega, \theta) - To obtain the one-dimentional spectrum (which is what you would measure with - a sensor), you need to integrate over direction: + To obtain the one-dimentional spectrum, you need to integrate over direction: .. math:: S_x(\omega) = \int S_x(\omega, \theta) d\theta From b30b0b07aeacca90cf2178a9a5abba65a22c6d5e Mon Sep 17 00:00:00 2001 From: Ali Cetin Date: Tue, 15 Apr 2025 11:08:56 +0200 Subject: [PATCH 5/6] add directionalbinspec --- .../directional_bin_spectrum.rst | 97 +++++++++++++++++++ docs/user_guide/concepts_utils/index.rst | 1 + 2 files changed, 98 insertions(+) create mode 100644 docs/user_guide/concepts_utils/directional_bin_spectrum.rst diff --git a/docs/user_guide/concepts_utils/directional_bin_spectrum.rst b/docs/user_guide/concepts_utils/directional_bin_spectrum.rst new file mode 100644 index 00000000..816089f6 --- /dev/null +++ b/docs/user_guide/concepts_utils/directional_bin_spectrum.rst @@ -0,0 +1,97 @@ +DirectionalBinSpectrum +====================== +The :class:`~waveresponse.DirectionalBinSpectrum` class provides an interface for +handling 2-D directional spectra. :class:`~waveresponse.DirectionalBinSpectrum` +extends :class:`~waveresponse.Grid`, and contains spectrum density as a function +of frequency, binned by direction. + +.. math:: + \sum_{i=0}^n{S_i(\omega, \delta\left(\theta - \theta_i\right))} + +The :class:`~waveresponse.DirectionalBinSpectrum` is initialized with a frequency +list (1-D array), a direction list (1-D array) and corresponding spectrum +density values, binned by direction (2-D array). + +.. code-block:: python + + import numpy as np + from waveresponse as wr + + + freq = np.linspace(0.0, 1.0, 50) + dirs = np.linspace(0.0, 360.0, endpoint=False) + vals = np.random.random((len(freq), len(dirs))) + + spectrum = wr.DirectionalBinSpectrum( + freq, + dirs, + vals, + freq_hz=True, + degrees=True, + clockwise=False, + waves_coming_from=False, + ) + +The :class:`~waveresponse.DirectionalBinSpectrum` class extends the :class:`~waveresponse.Grid` +class with the following: + +Calculate the variance (i.e., integral) and standard deviation of the spectrum: + +.. code-block:: python + + # Variance + var = spectrum.var() + + # Standard deviation + std = spectrum.std() + +Integrate (or sum) over one of the axes to obtain a one-dimentional spectrum. +You can specify whether to integrate over the frequency axis (``axis=0``), or +sum over the direction axis (``axis=1``), by setting the appropriate `axis` parameter. + +.. code-block:: python + + # "Non-directional" spectrum + spectrum_nondir = spectrum.spectrum1d(axis=1) + + # Directional "histogram" + spectrum_dir = spectrum.spectrum1d(axis=0) + +Calculate spectral moments by calling the :meth:`~waveresponse.DirectionalBinSpectrum.moment` +method with the desired order, `n`. + +.. code-block:: python + + # Zeroth-order moment + m0 = spectrum.moment(0) + + # First-order moment + m1 = spectrum.moment(1) + + # Second-order moment + m2 = spectrum.moment(2) + + # Etc. + +Calculate the mean zero-crossing period, Tz: + +.. code-block:: python + + spectrum.tz + +Calculate extreme values using the :meth:`~waveresponse.DirectionalSpectrum.extreme` +method. The method takes three arguments: the duration of the process (in seconds), +the quantile, ``q``, and a boolean flag, ``absmax``, determining whether to compute absolute +value extremes (or only consider the maxima (`default`)). + +.. code-block:: python + + duration = 3 * 3600 # 3 hours + + # Extreme maximum + mpm = spectrum.extreme(duration, q=0.37) # most probable maximum (MPM) + q90 = spectrum.extreme(duration, q=0.90) # 90-th quantile + + # Extreme absolute value maximum (i.e., minima are taken into account) + mpm = spectrum.extreme(duration, q=0.37, absmax=True) # most probable maximum (MPM) + q90 = spectrum.extreme(duration, q=0.90, absmax=True) # 90-th quantile diff --git a/docs/user_guide/concepts_utils/index.rst b/docs/user_guide/concepts_utils/index.rst index 45f5e554..2ac596cd 100644 --- a/docs/user_guide/concepts_utils/index.rst +++ b/docs/user_guide/concepts_utils/index.rst @@ -11,5 +11,6 @@ This section will introduce concepts and utilites that are useful when working w grid rao + directional_bin_spectrum directional_spectrum wave_spectrum From e1cae6f70ed4f40718cf6e5ea8e99fec689a2ceb Mon Sep 17 00:00:00 2001 From: Ali Cetin Date: Tue, 15 Apr 2025 11:16:49 +0200 Subject: [PATCH 6/6] update doc --- docs/user_guide/concepts_utils/index.rst | 1 + .../concepts_utils/wave_bin_spectrum.rst | 61 +++++++++++++++++++ 2 files changed, 62 insertions(+) create mode 100644 docs/user_guide/concepts_utils/wave_bin_spectrum.rst diff --git a/docs/user_guide/concepts_utils/index.rst b/docs/user_guide/concepts_utils/index.rst index 2ac596cd..3cdc77f7 100644 --- a/docs/user_guide/concepts_utils/index.rst +++ b/docs/user_guide/concepts_utils/index.rst @@ -13,4 +13,5 @@ This section will introduce concepts and utilites that are useful when working w rao directional_bin_spectrum directional_spectrum + wave_bin_spectrum wave_spectrum diff --git a/docs/user_guide/concepts_utils/wave_bin_spectrum.rst b/docs/user_guide/concepts_utils/wave_bin_spectrum.rst new file mode 100644 index 00000000..8c6f0be9 --- /dev/null +++ b/docs/user_guide/concepts_utils/wave_bin_spectrum.rst @@ -0,0 +1,61 @@ +WaveBinSpectrum +=============== +The :class:`~waveresponse.WaveBinSpectrum` class provides an interface for handling +2-D directional wave spectra. :class:`~waveresponse.WaveSpectrum` extends +:class:`~waveresponse.DirectionalBinSpectrum`, and contains spectrum density as a function +of frequency, binned by direction. + +.. math:: + \sum_{i=0}^n{S_{\zeta, i}(\omega, \delta\left(\theta - \theta_i\right))} + +The :class:`~waveresponse.WaveSpectrum` is initialized with a frequency +list (1-D array), a direction list (1-D array) and corresponding spectrum +density values, binned by direction (2-D array). + +.. code-block:: python + + import numpy as np + import waveresponse as wr + + + freq = np.linspace(0.0, 1.0, 50) + dirs = np.linspace(0.0, 360.0, endpoint=False) + vals = np.random.random((len(freq), len(dirs))) + + wave = wr.WaveBinSpectrum( + freq, + dirs, + vals, + freq_hz=True, + degrees=True, + clockwise=False, + waves_coming_from=False, + ) + + +The :class:`~waveresponse.WaveBinSpectrum` class extends the +:class:`~waveresponse.DirectionalBinSpectrum` class with the following: + +Calculate the significant wave height, Hs: + +.. code-block:: python + + wave.hs + +Calculate the wave peak period, Tp: + +.. code-block:: python + + wave.tp + +Calculate the wave peak direction: + +.. code-block:: python + + wave.dirp() + +Calculate the mean wave direction: + +.. code-block:: + + wave.dirm()