ENH: add RAO phase conventions (#55)

Author: vegard-solum-4ss

docs/user_guide/concepts_utils/rao.rst

@@ -51,6 +51,7 @@ Alternatively, you can construct an :class:`~waveresponse.RAO` object using ampl
         amp,
         phase,
         phase_degrees=False,
+        phase_leading=True,
         freq_hz=True,
         degrees=True,
     )

src/waveresponse/_core.py

@@ -49,10 +49,18 @@ def polar_to_complex(amp, phase, phase_degrees=False):
     """
     Convert polar coordinates (i.e., amplitude and phase) to complex numbers.
 
+    Given as:
+
+        ``A * exp(j * phi)``
+
+    where, ``A`` is the amplitude and ``phi`` is the phase.
+
     Parameters
     ----------
-    complex_vals : array-like
-        Complex number values.
+    amp : array-like
+        Amplitude values.
+    phase : array-like
+        Phase angle values.
     phase_degrees : bool
         Whether the phase angles are given in 'degrees'. If ``False``, 'radians'
         is assumed.
@@ -71,7 +79,7 @@ def polar_to_complex(amp, phase, phase_degrees=False):
     if amp.shape != phase.shape:
         raise ValueError()
 
-    return amp * (np.cos(phase) + 1j * np.sin(phase))
+    return amp * np.exp(1j * phase)
 
 
 def _check_is_similar(*grids, exact_type=True):
@@ -963,6 +971,7 @@ def __init__(
             waves_coming_from=waves_coming_from,
         )
         self._phase_degrees = False
+        self._phase_leading = True
 
     @classmethod
     def from_amp_phase(
@@ -972,6 +981,7 @@ def from_amp_phase(
         amp,
         phase,
         phase_degrees=False,
+        phase_leading=True,
         freq_hz=True,
         degrees=True,
         clockwise=True,
@@ -999,6 +1009,13 @@ def from_amp_phase(
         phase_degrees : bool
             If the RAO phase values are given in 'degrees'. If ``False``, 'radians'
             is assumed.
+        phase_leading : bool
+            Whether the phase values follow the 'leading' convention (``True``)
+            or the 'lagging' convention (``False``). Mathematically, an RAO with
+            phase lead convention is expressed as a complex number of the form
+            ``A * exp(j * phi)``, where ``A`` represents the amplitude and ``phi``
+            represents the phase angle. Whereas an RAO with phase lag convention
+            is expressed as ``A * exp(-j * phi)``.
         freq_hz : bool
             If frequency is given in 'Hz'. If ``False``, 'rad/s' is assumed.
         degrees : bool
@@ -1025,6 +1042,9 @@ def from_amp_phase(
         that are folded about a symmetry plane.
 
         """
+        if not phase_leading:
+            phase = -np.asarray_chkfinite(phase)
+
         rao_complex = polar_to_complex(amp, phase, phase_degrees=phase_degrees)
 
         rao = cls(
@@ -1037,6 +1057,7 @@ def from_amp_phase(
             waves_coming_from=waves_coming_from,
         )
         rao._phase_degrees = phase_degrees
+        rao._phase_leading = phase_leading
         return rao
 
     def differentiate(self, n=1):
@@ -1057,7 +1078,9 @@ def differentiate(self, n=1):
         new._vals = new._vals * ((1j * new._freq.reshape(-1, 1)) ** n)
         return new
 
-    def to_amp_phase(self, phase_degrees=None, freq_hz=None, degrees=None):
+    def to_amp_phase(
+        self, phase_degrees=None, phase_leading=None, freq_hz=None, degrees=None
+    ):
         """
         Return the RAO as amplitude and phase values.
 
@@ -1066,6 +1089,15 @@ def to_amp_phase(self, phase_degrees=None, freq_hz=None, degrees=None):
         phase_degrees : bool
             If phase values should be returned in 'degrees'. If ``False``, 'radians'
             is used. Defaults to original units used during initialization or ``False``.
+        phase_leading : bool
+            Whether the phase values should follow the 'leading' convention (``True``)
+            or the 'lagging' convention (``False``). If ``None``, it defaults to
+            the convention given during initialization, or the lagging convention
+            if no convention was specified during initialization. Mathematically,
+            an RAO with phase lead convention is expressed as a complex number of
+            the form ``A * exp(j * phi)``, where ``A`` represents the amplitude and
+            ``phi`` represents the phase angle. Whereas an RAO with phase lag convention
+            is expressed as ``A * exp(-j * phi)``.
         freq_hz : bool
             If frequencies should be returned in 'Hz'. If ``False``, 'rad/s' is used.
             Defaults to original units used during initialization.
@@ -1092,9 +1124,19 @@ def to_amp_phase(self, phase_degrees=None, freq_hz=None, degrees=None):
             degrees = self._degrees
         if phase_degrees is None:
             phase_degrees = self._phase_degrees
+        if phase_leading is None:
+            phase_leading = self._phase_leading
 
         freq, dirs, vals = self.grid(freq_hz=freq_hz, degrees=degrees)
-        vals_amp, vals_phase = complex_to_polar(vals, phase_degrees=phase_degrees)
+        vals_amp, vals_phase = complex_to_polar(vals, phase_degrees=False)
+
+        if not phase_leading:
+            vals_phase = -vals_phase
+            vals_phase = np.where(np.isclose(vals_phase, -np.pi), np.pi, vals_phase)
+
+        if phase_degrees:
+            vals_phase = (180.0 / np.pi) * vals_phase
+
         return freq, dirs, vals_amp, vals_phase
 
     def __repr__(self):

tests/test_core.py

@@ -2018,6 +2018,7 @@ def test__init__(self):
         assert rao._freq_hz is True
         assert rao._degrees is True
         assert rao._phase_degrees is False
+        assert rao._phase_leading is True
 
     def test_from_grid(self):
         freq = np.linspace(0, 1.0, 10)
@@ -2069,6 +2070,7 @@ def test_from_amp_phase_rad(self):
             amp_in,
             phase_in,
             phase_degrees=False,
+            phase_leading=True,
             freq_hz=True,
             degrees=True,
             clockwise=True,
@@ -2087,6 +2089,7 @@ def test_from_amp_phase_rad(self):
         assert rao._freq_hz is True
         assert rao._degrees is True
         assert rao._phase_degrees is False
+        assert rao._phase_leading is True
 
     def test_from_amp_phase_deg(self):
         freq_in = np.array([0, 1, 2])
@@ -2131,6 +2134,44 @@ def test_from_amp_phase_deg(self):
         assert rao._freq_hz is True
         assert rao._degrees is True
         assert rao._phase_degrees is True
+        assert rao._phase_leading is True
+
+    def test_from_amp_phase_lagging(self):
+        freq_in = np.array([0, 1, 2])
+        dirs_in = np.array([0, 45, 90, 135])
+        amp_in = np.array(
+            [
+                [1, 2, 3, 4],
+                [1, 2, 3, 4],
+                [1, 2, 3, 4],
+            ]
+        )
+        phase_in = np.array(
+            [
+                [0.1, 0.2, 0.3, 0.4],
+                [0.1, 0.2, 0.3, 0.4],
+                [0.1, 0.2, 0.3, 0.4],
+            ]
+        )
+        rao = RAO.from_amp_phase(
+            freq_in,
+            dirs_in,
+            amp_in,
+            phase_in,
+            phase_degrees=False,
+            phase_leading=False,
+            freq_hz=True,
+            degrees=True,
+            clockwise=True,
+            waves_coming_from=True,
+        )
+
+        vals_expect = amp_in * np.exp(-1j * phase_in)
+
+        np.testing.assert_array_almost_equal(rao._freq, 2.0 * np.pi * freq_in)
+        np.testing.assert_array_almost_equal(rao._dirs, (np.pi / 180.0) * dirs_in)
+        np.testing.assert_array_almost_equal(rao._vals, vals_expect)
+        assert rao._phase_leading is False
 
     def test__mul__(self, rao):
         rao_squared = rao * rao
@@ -2480,6 +2521,53 @@ def test_to_amp_phase_None(self):
         np.testing.assert_array_almost_equal(amp_out, amp_expect)
         np.testing.assert_array_almost_equal(phase_out, phase_expect)
 
+    def test_to_amp_phase_lagging(self):
+        freq_in = np.array([0, 1, 2])
+        dirs_in = np.array([0, 1, 2])
+        vals_in = np.array(
+            [
+                [1.0 + 0.0j, 0.0 + 1.0j, -1.0 + 0.0j],
+                [1.0 + 0.0j, 0.0 + 1.0j, -1.0 + 0.0j],
+                [1.0 + 0.0j, 0.0 + 1.0j, -1.0 + 0.0j],
+            ]
+        )
+
+        rao = RAO(
+            freq_in,
+            dirs_in,
+            vals_in,
+            freq_hz=True,
+            degrees=True,
+            clockwise=True,
+            waves_coming_from=True,
+        )
+
+        freq_out, dirs_out, amp_out, phase_out = rao.to_amp_phase(
+            freq_hz=True, degrees=True, phase_degrees=True, phase_leading=False
+        )
+
+        freq_expect = np.array([0, 1, 2])
+        dirs_expect = np.array([0, 1, 2])
+        amp_expect = np.array(
+            [
+                [1.0, 1.0, 1.0],
+                [1.0, 1.0, 1.0],
+                [1.0, 1.0, 1.0],
+            ]
+        )
+        phase_expect = np.array(
+            [
+                [0.0, -90.0, 180.0],
+                [0.0, -90.0, 180.0],
+                [0.0, -90.0, 180.0],
+            ]
+        )
+
+        np.testing.assert_array_almost_equal(freq_out, freq_expect)
+        np.testing.assert_array_almost_equal(dirs_out, dirs_expect)
+        np.testing.assert_array_almost_equal(amp_out, amp_expect)
+        np.testing.assert_array_almost_equal(phase_out, phase_expect)
+
     def test__repr__(self, rao):
         assert str(rao) == "RAO"