pyTMD 2.1.8__tar.gz → 2.2.0__tar.gz

{pytmd-2.1.8 → pytmd-2.2.0}/CITATION.cff

@@ -36,8 +36,8 @@ url: 'https://pytmd.readthedocs.io'
 repository: 'https://pypi.org/project/pyTMD'
 repository-artifact: 'https://anaconda.org/conda-forge/pytmd'
 doi: "10.5281/zenodo.5555395"
-version: "2.1.8"
-date-released: "2024-11-07"
+version: "2.2.0"
+date-released: "2024-12-20"
 keywords:
   - Ocean Tides
   - Load Tides

{pytmd-2.1.8 → pytmd-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyTMD
-Version: 2.1.8
+Version: 2.2.0
 Summary: Python-based tidal prediction software for estimating ocean, load, solid Earth and pole tides
 Author: Tyler Sutterley
 Author-email: tsutterl@uw.edu
@@ -65,6 +65,7 @@ Requires-Dist: myst-nb; extra == "doc"
 Requires-Dist: numpydoc; extra == "doc"
 Requires-Dist: sphinx; extra == "doc"
 Requires-Dist: sphinx-argparse>=0.4; extra == "doc"
+Requires-Dist: sphinxcontrib-bibtex; extra == "doc"
 Requires-Dist: sphinx-design; extra == "doc"
 Requires-Dist: sphinx_rtd_theme; extra == "doc"
 Provides-Extra: all

{pytmd-2.1.8 → pytmd-2.2.0}/pyTMD/__init__.py

@@ -16,6 +16,7 @@ import pyTMD.astro
 import pyTMD.compute
 import pyTMD.ellipse
 import pyTMD.interpolate
+import pyTMD.math
 import pyTMD.predict
 import pyTMD.spatial
 import pyTMD.tools
@@ -23,7 +24,6 @@ import pyTMD.utilities
 import pyTMD.version
 from pyTMD import io
 from pyTMD import solve
-from pyTMD.check_points import check_points
 from pyTMD.crs import (
     crs,
     datum,
@@ -31,6 +31,7 @@ from pyTMD.crs import (
 )
 
 # Deprecated functions
+from pyTMD.check_points import check_points
 from pyTMD.compute_tide_corrections import (
     compute_corrections,
     compute_tide_corrections,

{pytmd-2.1.8 → pytmd-2.2.0}/pyTMD/arguments.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 arguments.py
-Written by Tyler Sutterley (11/2024)
+Written by Tyler Sutterley (12/2024)
 Calculates the nodal corrections for tidal constituents
 Modification of ARGUMENTS fortran subroutine by Richard Ray 03/1999
 
@@ -27,6 +27,7 @@ PYTHON DEPENDENCIES:
 
 PROGRAM DEPENDENCIES:
     astro.py: computes the basic astronomical mean longitudes
+    math.py: Special functions of mathematical physics
 
 REFERENCES:
     A. T. Doodson and H. Warburg, "Admiralty Manual of Tides", HMSO, (1941).
@@ -38,7 +39,10 @@ REFERENCES:
         Ocean Tides", Journal of Atmospheric and Oceanic Technology, (2002).
 
 UPDATE HISTORY:
+    Updated 12/2024: added function to calculate tidal aliasing periods
     Updated 11/2024: allow variable case for Doodson number formalisms
+        fix species in constituent parameters for complex tides
+        move body tide Love/Shida numbers from predict module
     Updated 10/2024: can convert Doodson numbers formatted as strings
         update Doodson number conversions to follow Cartwright X=10 convention
         add function to parse Cartwright/Tayler/Edden tables
@@ -89,9 +93,11 @@ __all__ = [
     "doodson_number",
     "nodal",
     "frequency",
+    "aliasing_period",
     "_arguments_table",
     "_minor_table",
     "_constituent_parameters",
+    "_love_numbers",
     "_parse_tide_potential_table",
     "_to_doodson_number",
     "_to_extended_doodson",
@@ -106,7 +112,7 @@ def arguments(
     ):
     """
     Calculates the nodal corrections for tidal constituents
-    [1]_ [2]_ [3]_ [4]_
+    :cite:p:`Doodson:1941td` :cite:p:`Schureman:1958ty` :cite:p:`Foreman:1989dt` :cite:p:`Egbert:2002ge`
 
     Parameters
     ----------
@@ -133,23 +139,6 @@ def arguments(
         nodal factor correction
     G: np.ndarray
         phase correction in degrees
-
-    References
-    ----------
-    .. [1] A. T. Doodson and H. D. Warburg, "Admiralty Manual of Tides",
-        HMSO, London, (1941).
-    .. [2] P. Schureman, "Manual of Harmonic Analysis and Prediction of Tides,"
-        *US Coast and Geodetic Survey*, Special Publication, 98, (1958).
-    .. [3] M. G. G. Foreman and R. F. Henry, "The harmonic analysis of tidal
-        model time series," *Advances in Water Resources*, 12(3), 109--120,
-        (1989). `doi: 10.1016/0309-1708(89)90017-1
-        <https://doi.org/10.1016/0309-1708(89)90017-1>`_
-    .. [4] G. D. Egbert and S. Y. Erofeeva, "Efficient Inverse Modeling of
-        Barotropic Ocean Tides," *Journal of Atmospheric and Oceanic
-        Technology*, 19(2), 183--204, (2002).
-        `doi: 10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2`__
-
-    .. __: https://doi.org/10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2
     """
     # set default keyword arguments
     kwargs.setdefault('deltat', 0.0)
@@ -189,7 +178,9 @@ def minor_arguments(
     ):
     """
     Calculates the nodal corrections for minor tidal constituents
-    in order to infer their values [1]_ [2]_ [3]_ [4]_
+    in order to infer their values :cite:p:`Doodson:1941td` :cite:p:`Schureman:1958ty`
+    :cite:p:`Foreman:1989dt` :cite:p:`Egbert:2002ge`
+
 
     Parameters
     ----------
@@ -208,23 +199,6 @@ def minor_arguments(
         nodal factor correction
     G: np.ndarray
         phase correction in degrees
-
-    References
-    ----------
-    .. [1] A. T. Doodson and H. D. Warburg, "Admiralty Manual of Tides",
-        HMSO, London, (1941).
-    .. [2] P. Schureman, "Manual of Harmonic Analysis and Prediction of Tides,"
-        *US Coast and Geodetic Survey*, Special Publication, 98, (1958).
-    .. [3] M. G. G. Foreman and R. F. Henry, "The harmonic analysis of tidal
-        model time series," *Advances in Water Resources*, 12(3), 109--120,
-        (1989). `doi: 10.1016/0309-1708(89)90017-1
-        <https://doi.org/10.1016/0309-1708(89)90017-1>`_
-    .. [4] G. D. Egbert and S. Y. Erofeeva, "Efficient Inverse Modeling of
-        Barotropic Ocean Tides," *Journal of Atmospheric and Oceanic
-        Technology*, 19(2), 183--204, (2002).
-        `doi: 10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2`__
-
-    .. __: https://doi.org/10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2
     """
     # set default keyword arguments
     kwargs.setdefault('deltat', 0.0)
@@ -358,7 +332,8 @@ def coefficients_table(
         **kwargs
     ):
     """
-    Doodson table coefficients for tidal constituents [1]_ [2]_
+    Doodson table coefficients for tidal constituents
+    :cite:p:`Doodson:1921kt` :cite:p:`Doodson:1941td`
 
     Parameters
     ----------
@@ -373,16 +348,6 @@ def coefficients_table(
     -------
     coef: np.ndarray
         Doodson coefficients (Cartwright numbers) for each constituent
-
-    References
-    ----------
-    .. [1] A. T. Doodson and H. Lamb, "The harmonic development of
-        the tide-generating potential", *Proceedings of the Royal Society
-        of London. Series A, Containing Papers of a Mathematical and
-        Physical Character*, 100(704), 305--329, (1921).
-        `doi: 10.1098/rspa.1921.0088 <https://doi.org/10.1098/rspa.1921.0088>`_
-    .. [2] A. T. Doodson and H. D. Warburg, "Admiralty Manual of Tides",
-        HMSO, London, (1941).
     """
     # set default keyword arguments
     kwargs.setdefault('corrections', 'OTIS')
@@ -431,7 +396,7 @@ def doodson_number(
     ):
     """
     Calculates the Doodson or Cartwright number for
-    tidal constituents [1]_
+    tidal constituents :cite:p:`Doodson:1921kt`
 
     Parameters
     ----------
@@ -452,14 +417,6 @@ def doodson_number(
     -------
     numbers: float, np.ndarray or dict
         Doodson or Cartwright number for each constituent
-
-    References
-    ----------
-    .. [1] A. T. Doodson and H. Lamb, "The harmonic development of
-        the tide-generating potential", *Proceedings of the Royal Society
-        of London. Series A, Containing Papers of a Mathematical and
-        Physical Character*, 100(704), 305--329, (1921).
-        `doi: 10.1098/rspa.1921.0088 <https://doi.org/10.1098/rspa.1921.0088>`_
     """
     # set default keyword arguments
     kwargs.setdefault('corrections', 'OTIS')
@@ -524,7 +481,7 @@ def nodal(
     ):
     """
     Calculates the nodal corrections for tidal constituents
-    [1]_ [2]_ [3]_ [4]_
+    :cite:p:`Doodson:1941td` :cite:p:`Schureman:1958ty` :cite:p:`Foreman:1989dt` :cite:p:`Ray:1999vm`
 
     Calculates factors for compound tides using recursion
 
@@ -551,20 +508,6 @@ def nodal(
         nodal factor correction
     u: np.ndarray
         nodal angle correction
-
-    References
-    ----------
-    .. [1] A. T. Doodson and H. D. Warburg, "Admiralty Manual of Tides",
-        HMSO, London, (1941).
-    .. [2] P. Schureman, "Manual of Harmonic Analysis and Prediction of Tides,"
-        *US Coast and Geodetic Survey*, Special Publication, 98, (1958).
-    .. [3] M. G. G. Foreman and R. F. Henry, "The harmonic analysis of tidal
-        model time series," *Advances in Water Resources*, 12(3), 109--120,
-        (1989). `doi: 10.1016/0309-1708(89)90017-1
-        <https://doi.org/10.1016/0309-1708(89)90017-1>`_
-    .. [4] R. D. Ray, "A global ocean tide model from
-        Topex/Poseidon altimetry: GOT99.2",
-        NASA Goddard Space Flight Center, TM-1999-209478, (1999).
     """
     # set default keyword arguments
     kwargs.setdefault('corrections', 'OTIS')
@@ -1228,7 +1171,7 @@ def frequency(
         **kwargs
     ):
     """
-    Calculates the angular frequency for tidal constituents [1]_
+    Calculates the angular frequency for tidal constituents :cite:p:`Ray:1999vm`
 
     Parameters
     ----------
@@ -1247,12 +1190,6 @@ def frequency(
     -------
     omega: np.ndarray
         angular frequency in radians per second
-
-    References
-    ----------
-    .. [1] R. D. Ray, "A global ocean tide model from
-        Topex/Poseidon altimetry: GOT99.2",
-        NASA Goddard Space Flight Center, TM-1999-209478, (1999).
     """
     # set default keyword arguments
     kwargs.setdefault('corrections', 'OTIS')
@@ -1284,9 +1221,48 @@ def frequency(
     omega = 2.0*np.pi*fd/360.0
     return omega
 
+def aliasing_period(
+        constituents: list | np.ndarray,
+        sampling: float | np.ndarray,
+        **kwargs
+    ):
+    """
+    Calculates the tidal aliasing for a repeat period
+
+    Parameters
+    ----------
+    constituents: list
+        tidal constituent IDs
+    sampling: float
+        sampling repeat period in seconds
+    corrections: str, default 'OTIS'
+        use nodal corrections from OTIS, FES or GOT models
+    M1: str, default 'perth5'
+        coefficients to use for M1 tides
+
+                - ``'Doodson'``
+                - ``'Ray'``
+                - ``'perth5'``
+
+    Returns
+    -------
+    period: np.ndarray
+        tidal aliasing period in seconds
+    """
+    # get the angular frequency for tidal constituents
+    omega = frequency(constituents, **kwargs)
+    # convert to cycles per second
+    f = omega/(2.0*np.pi)
+    # calculate the sampling frequency
+    fs = 1.0/sampling
+    # calculate the aliasing period
+    period = 1.0/pyTMD.math.aliasing(f, fs)
+    # reutrn the aliasing period
+    return period
+
 def _arguments_table(**kwargs):
     """
-    Arguments table for tidal constituents [1]_ [2]_
+    Arguments table for tidal constituents :cite:p:`Doodson:1921kt` :cite:p:`Doodson:1941td`
 
     Parameters
     ----------
@@ -1297,16 +1273,6 @@ def _arguments_table(**kwargs):
     -------
     coef: np.ndarray
         Doodson coefficients (Cartwright numbers) for each constituent
-
-    References
-    ----------
-    .. [1] A. T. Doodson and H. Lamb, "The harmonic development of
-        the tide-generating potential", *Proceedings of the Royal Society
-        of London. Series A, Containing Papers of a Mathematical and
-        Physical Character*, 100(704), 305--329, (1921).
-        `doi: 10.1098/rspa.1921.0088 <https://doi.org/10.1098/rspa.1921.0088>`_
-    .. [2] A. T. Doodson and H. D. Warburg, "Admiralty Manual of Tides",
-        HMSO, London, (1941).
     """
     # set default keyword arguments
     kwargs.setdefault('corrections', 'OTIS')
@@ -1333,22 +1299,12 @@ def _arguments_table(**kwargs):
 
 def _minor_table(**kwargs):
     """
-    Arguments table for minor tidal constituents [1]_ [2]_
+    Arguments table for minor tidal constituents :cite:p:`Doodson:1921kt` :cite:p:`Doodson:1941td`
 
     Returns
     -------
     coef: np.ndarray
         Doodson coefficients (Cartwright numbers) for each constituent
-
-    References
-    ----------
-    .. [1] A. T. Doodson and H. Lamb, "The harmonic development of
-        the tide-generating potential", *Proceedings of the Royal Society
-        of London. Series A, Containing Papers of a Mathematical and
-        Physical Character*, 100(704), 305--329, (1921).
-        `doi: 10.1098/rspa.1921.0088 <https://doi.org/10.1098/rspa.1921.0088>`_
-    .. [2] A. T. Doodson and H. D. Warburg, "Admiralty Manual of Tides",
-        HMSO, London, (1941).
     """
     # modified Doodson coefficients for constituents
     # using 7 index variables: tau, s, h, p, n, pp, k
@@ -1368,7 +1324,7 @@ def _minor_table(**kwargs):
 
 def _constituent_parameters(c: str, **kwargs):
     """
-    Loads parameters for a given tidal constituent
+    Loads parameters for a given tidal constituent :cite:p:`Egbert:2002ge`
 
     Parameters
     ----------
@@ -1389,15 +1345,6 @@ def _constituent_parameters(c: str, **kwargs):
         load love number of tidal constituent
     species: float
         spherical harmonic dependence of quadrupole potential
-
-    References
-    ----------
-    .. [1] G. D. Egbert and S. Y. Erofeeva, "Efficient Inverse Modeling of
-        Barotropic Ocean Tides," *Journal of Atmospheric and Oceanic
-        Technology*, 19(2), 183--204, (2002).
-        `doi: 10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2`__
-
-    .. __: https://doi.org/10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2
     """
     # default keyword arguments
     kwargs.setdefault('raise_error', False)
@@ -1408,7 +1355,7 @@ def _constituent_parameters(c: str, **kwargs):
         'msf', 'sa', 'mt', '2q1']
     # species type (spherical harmonic dependence of quadrupole potential)
     _species = np.array([2, 2, 1, 1, 2, 1, 2, 1, 2, 2, 2, 2, 2, 1, 1,
-        1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1])
+        1, 1, 0, 0, 0, 4, 4, 4, 6, 8, 3, 6, 2, 3, 0, 0, 0, 1])
     # Load Love numbers
     # alpha = correction factor for first order load tides
     _alpha = np.array([0.693, 0.693, 0.736, 0.695, 0.693, 0.706, 0.693,
@@ -1419,7 +1366,7 @@ def _constituent_parameters(c: str, **kwargs):
     _omega = np.array([1.405189e-04, 1.454441e-04, 7.292117e-05, 6.759774e-05,
         1.378797e-04, 7.252295e-05, 1.458423e-04, 6.495854e-05, 1.352405e-04,
         1.355937e-04, 1.382329e-04, 1.431581e-04, 1.452450e-04, 7.556036e-05,
-        7.028195e-05, 7.824458e-05, 6.531174e-05, 0.053234e-04, 0.026392e-04,
+        7.025945e-05, 7.824458e-05, 6.531174e-05, 0.053234e-04, 0.026392e-04,
         0.003982e-04, 2.810377e-04, 2.859630e-04, 2.783984e-04, 4.215566e-04,
         5.620755e-04, 2.134402e-04, 4.363323e-04, 1.503693e-04, 2.081166e-04,
         4.925200e-06, 1.990970e-07, 7.962619e-06, 6.231934e-05])
@@ -1428,10 +1375,10 @@ def _constituent_parameters(c: str, **kwargs):
     # the forcing for that constituent is zero on the Greenwich meridian
     _phase = np.array([1.731557546, 0.000000000, 0.173003674, 1.558553872,
         6.050721243, 6.110181633, 3.487600001, 5.877717569, 4.086699633,
-        3.463115091, 5.427136701, 0.553986502, 0.052841931, 2.137025284,
-        2.436575100, 1.929046130, 5.254133027, 1.756042456, 1.964021610,
+        3.463115091, 5.427136701, 0.553986502, 0.050398470, 2.137025284,
+        2.436575000, 1.929046130, 5.254133027, 1.756042456, 1.964021610,
         3.487600001, 3.463115091, 1.731557546, 1.499093481, 5.194672637,
-        6.926230184, 1.904561220, 0.000000000, 4.551627762, 3.809122439,
+        6.926230184, 1.904561220, 0.000000000, 4.551627762, 3.290111417,
         4.551627762, 6.232786837, 3.720064066, 3.91369596])
     # amplitudes of equilibrium tide in meters
     # _amplitude = np.array([0.242334,0.112743,0.141565,0.100661,0.046397,
@@ -1461,13 +1408,94 @@ def _constituent_parameters(c: str, **kwargs):
     # return the values for the constituent
     return (amplitude, phase, omega, alpha, species)
 
+def _love_numbers(
+        omega: np.ndarray,
+        model: str = 'PREM'
+    ):
+    """
+    Compute the body tide Love/Shida numbers for a given
+    frequency :cite:p:`Wahr:1981ea` :cite:p:`Wahr:1981if` :cite:p:`Mathews:1995go`
+
+    Parameters
+    ----------
+    omega: np.ndarray
+        angular frequency (radians per second)
+    model: str, default 'PREM'
+        Earth model to use for Love numbers
+
+            - '1066A'
+            - 'PEM-C'
+            - 'C2'
+            - 'PREM'
+
+    Returns
+    -------
+    h2: float
+        Degree-2 Love number of vertical displacement
+    k2: float
+        Degree-2 Love number of gravitational potential
+    l2: float
+        Degree-2 Love (Shida) number of horizontal displacement
+    """
+    # free core nutation frequencies (cycles per sidereal day) and
+    # Love number parameters from Wahr (1981) table 6
+    # and Mathews et al. (1995) table 3
+    if (model == '1066A'):
+        fcn = 1.0021714
+        h0, h1 = np.array([6.03e-1, -2.46e-3])
+        k0, k1 = np.array([2.98e-1, -1.23e-3])
+        l0, l1 = np.array([8.42e-2, 7.81e-5])
+    elif (model == 'PEM-C'):
+        fcn = 1.0021771
+        h0, h1 = np.array([6.02e-1, -2.46e-3])
+        k0, k1 = np.array([2.98e-1, -1.24e-3])
+        l0, l1 = np.array([8.39e-2, 7.69e-5])
+    elif (model == 'C2'):
+        fcn = 1.0021844
+        h0, h1 = np.array([6.02e-1, -2.45e-3])
+        k0, k1 = np.array([2.98e-1, -1.23e-3])
+        l0, l1 = np.array([8.46e-2, 7.58e-5])
+    elif (model == 'PREM'):
+        fcn = 1.0023214
+        h0, h1 = np.array([5.994e-1, -2.532e-3])
+        k0, k1 = np.array([2.962e-1, -1.271e-3])
+        l0, l1 = np.array([8.378e-2, 7.932e-5])
+    else:
+        raise ValueError(f'Unknown Earth model: {model}')
+    # Love numbers for different frequency bands
+    if (omega > 1e-4):
+        # tides in the semi-diurnal band
+        h2 = 0.609
+        k2 = 0.302
+        l2 = 0.0852
+    elif (omega < 2e-5):
+        # tides in the long period band
+        h2 = 0.606
+        k2 = 0.299
+        l2 = 0.0840
+    else:
+        # use resonance formula for tides in the diurnal band
+        # frequency of the o1 tides (radians/second)
+        omega_o1, = frequency('o1')
+        # frequency of free core nutation (radians/second)
+        omega_fcn = fcn*7292115e-11
+        # Love numbers for frequency using equation 4.18 of Wahr (1981)
+        # (simplification to use only the free core nutation term)
+        ratio = (omega - omega_o1)/(omega_fcn - omega)
+        h2 = h0 + h1*ratio
+        k2 = k0 + k1*ratio
+        l2 = l0 + l1*ratio
+    # return the Love numbers for frequency
+    return (h2, k2, l2)
+
 # Cartwright and Tayler (1971) table with 3rd-degree values
 _ct1971_table_5 = get_data_path(['data','ct1971_tab5.txt'])
 # Cartwright and Edden (1973) table with updated values
 _ce1973_table_1 = get_data_path(['data','ce1973_tab1.txt'])
 
 def _parse_tide_potential_table(table: str | pathlib.Path):
-    """Parse tables of tide-generating potential from [1]_ and [2]_
+    """Parse tables of tide-generating potential from
+    :cite:p:`Cartwright:1971iz` and :cite:p:`Cartwright:1973em`
 
     Parameters
     ----------
@@ -1478,19 +1506,6 @@ def _parse_tide_potential_table(table: str | pathlib.Path):
     -------
     CTE: float
         Cartwright-Tayler-Edden table values
-
-    References
-    ----------
-    .. [1] D. E. Cartwright and R. J. Tayler,
-        "New Computations of the Tide-generating Potential,"
-        *Geophysical Journal of the Royal Astronomical Society*,
-        23(1), 45--73. (1971). `doi: 10.1111/j.1365-246X.1971.tb01803.x
-        <https://doi.org/10.1111/j.1365-246X.1971.tb01803.x>`_
-    .. [2] D. E. Cartwright and A. C. Edden,
-        "Corrected Tables of Tidal Harmonics,"
-        *Geophysical Journal of the Royal Astronomical Society*,
-        33(3), 253--264, (1973). `doi: 10.1111/j.1365-246X.1973.tb03420.x
-        <https://doi.org/10.1111/j.1365-246X.1973.tb03420.x>`_
     """
     # verify table path
     table = pathlib.Path(table).expanduser().absolute()