DOC: Add references

Author: vegard-solum-4ss

docs/user_guide/standardized_spectra.rst

@@ -129,6 +129,12 @@ where,
 The index, :math:`j = 1, 2`, represents the lower frequency component (i.e., swell)
 and higher frequency component (i.e., wind) respectively.
 
+.. note::
+
+    The Ochi-Hubble spectrum is implemented according to the `orinal paper <https://icce-ojs-tamu.tdl.org/icce/article/view/3066/2731>`_
+    by M. K. Ochi and E. N. Hubble published in 1976. Refer to this paper for full implementation
+    details.
+
 The :class:`~waveresponse.OchiHubble` class provides functionality for generating a 1-D
 Ochi-Hubble spectrum component given three parameters (i.e., :math:`H_s`, :math:`T_p`
 and :math:`q`). The total spectrum is obtained by adding together the two wave components.

src/waveresponse/_core.py

@@ -37,6 +37,7 @@ def complex_to_polar(complex_vals, phase_degrees=False):
         Amplitudes.
     phase : array
         Phase angles.
+
     """
     complex_vals = np.asarray_chkfinite(complex_vals)
     amp = np.abs(complex_vals)
@@ -1428,6 +1429,17 @@ def moment(self, n, freq_hz=None):
         -------
         float :
             Spectral moment.
+
+        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.
+
         """
         f, spectrum = self.spectrum1d(axis=1, freq_hz=freq_hz)
         m_n = trapz((f**n) * spectrum, f)
@@ -1440,9 +1452,20 @@ def tz(self):
 
         Calculated from the zeroth- and second-order spectral moments according to:
 
-            ``tz = sqrt(m0 / m2)``
+        ``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.
+
         """
         m0 = self.moment(0, freq_hz=True)
         m2 = self.moment(2, freq_hz=True)
@@ -1479,6 +1502,15 @@ def extreme(self, t, q=0.37):
             the process amplitudes will be below the returned value with a given
             probability.
 
+        Notes
+        -----
+        The extreme values are calculated according to Equation (1.46) in reference [1]_.
+
+        References
+        ----------
+        .. [1] A. Naess and T. Moan, (2013), "Stochastic dynamics of marine structures",
+           Cambridge University Press.
+
         """
         q = np.asarray_chkfinite(q)
         return self.std() * np.sqrt(2.0 * np.log((t / self.tz) / np.log(1.0 / q)))
@@ -1495,7 +1527,17 @@ def hs(self):
 
         Calculated from the zeroth-order spectral moment according to:
 
-            ``hs = 4.0 * sqrt(m0)``
+        ``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.
         """
         m0 = self.moment(0)
         return 4.0 * np.sqrt(m0)
@@ -1731,6 +1773,17 @@ class CosineHalfSpreading(BaseSpreading):
     degrees : bool
         If directions passed to the spreading function will be given in 'degrees'.
         If ``False``, 'radians' is assumed.
+
+    Notes
+    -----
+    The spreading function is implemented according to reference [1]_.
+
+    References
+    ----------
+    .. [1] U. S. Army Engineer Waterways Experiment Station, Coastal Engineering Research
+       Center. (1985, June). "Directional wave spectra using cosine-squared and cosine 2s
+       spreading functions". Retrieved January 31, 2023, from
+       https://apps.dtic.mil/sti/pdfs/ADA591687.pdf.
     """
 
     def __init__(self, s=1, degrees=False):
@@ -1775,6 +1828,17 @@ class CosineFullSpreading(BaseSpreading):
     degrees : bool
         If directions passed to the spreading function will be given in 'degrees'.
         If ``False``, 'radians' is assumed.
+
+    Notes
+    -----
+    The spreading function is implemented according to reference [1]_.
+
+    References
+    ----------
+    .. [1] U. S. Army Engineer Waterways Experiment Station, Coastal Engineering Research
+       Center. (1985, June). "Directional wave spectra using cosine-squared and cosine 2s
+       spreading functions". Retrieved January 31, 2023, from
+       https://apps.dtic.mil/sti/pdfs/ADA591687.pdf.
     """
 
     def __init__(self, s=1, degrees=False):

src/waveresponse/_standardized1d.py

@@ -92,6 +92,17 @@ class BasePMSpectrum(BaseSpectrum1d):
     ModifiedPiersonMoskowitz : Modified Pierson-Moskowitz wave spectrum.
     JONSWAP : JONSWAP wave spectrum.
     OchiHubble : Ochi-Hubble (three-parameter) wave spectrum.
+
+    Notes
+    -----
+    Pierson-Moskowitz type of spectra are implemented according to Equation (8.14)
+    in reference [1]_.
+
+    References
+    ----------
+    .. [1] A. Naess and T. Moan, (2013), "Stochastic dynamics of marine structures",
+        Cambridge University Press.
+
     """
 
     def __call__(self, A, B, freq_hz=None):
@@ -157,6 +168,17 @@ class ModifiedPiersonMoskowitz(BasePMSpectrum):
     --------
     JONSWAP : JONSWAP wave spectrum.
     OchiHubble : Ochi-Hubble (three-parameter) wave spectrum.
+
+    Notes
+    -----
+    The modified Pierson-Moskowitz spectrum is implemented according to Section 8.2.2
+    in reference [1]_.
+
+    References
+    ----------
+    .. [1] A. Naess and T. Moan, (2013), "Stochastic dynamics of marine structures",
+        Cambridge University Press.
+
     """
 
     def __call__(self, hs, tp, freq_hz=None):
@@ -332,6 +354,13 @@ class OchiHubble(BaseSpectrum1d):
     -----
     The special case ``q=1`` corresponds to the modified Pierson-Moskowitz spectrum.
 
+    The Ochi-Hubble spectrum is implemented as described in reference [1]_.
+
+    References
+    ----------
+    .. [1] Ochi M K and Hubble E N, 1976. "Six-parameter wave spectra", Proc 15th
+       Coastal Engineering Conference, 301-328.
+
     See Also
     --------
     ModifiedPiersonMoskowitz : Modified Pierson-Moskowitz wave spectrum.

tests/test_core.py

@@ -73,7 +73,6 @@ def rao(freq_dirs):
 
 @pytest.fixture
 def rao_for_mirroring():
-
     freq = np.linspace(0, 1.0, 3)
     dirs = np.linspace(0, 180, 3, endpoint=True)
     vals = np.array(
@@ -141,7 +140,6 @@ def test_sort():
 
 
 class Test__robust_modulus:
-
     params_robust_modulus = [
         (2.5, 2.0, 0.5),
         (2.0, 2.0, 0.0),
@@ -656,7 +654,6 @@ def test_mirror_twise(self, mask_bounds, sym_plane_order, dof):
 
 
 class Test__check_foldable:
-
     check_foldable_valid = [
         (
             np.linspace(
@@ -1408,7 +1405,6 @@ def test_interpolate_single_coordinate(self):
         np.testing.assert_array_almost_equal(vals_out, vals_expect)
 
     def test_interpolate_fill_value(self):
-
         freq = np.array([0, 1, 2])
         dirs = np.array([0, 90, 180, 270])
         vals = np.array(
@@ -1433,7 +1429,6 @@ def test_interpolate_fill_value(self):
         np.testing.assert_array_almost_equal(vals_out, vals_expect)
 
     def test_interpolate_fill_value_None(self):
-
         freq = np.array([0, 1, 2])
         dirs = np.array([0, 90, 180, 270])
         vals = np.array(