pyTMD 2.2.4__tar.gz → 2.2.6__tar.gz

{pytmd-2.2.4 → pytmd-2.2.6}/.gitignore

@@ -42,6 +42,8 @@ wheels/
 *.egg
 .pytest_cache
 pythonenv*/
+venv/
+*build-commands.txt
 setup-miniconda-patched-environment.yml
 # OS generated files #
 ######################

{pytmd-2.2.4 → pytmd-2.2.6}/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.2.4"
-date-released: "2025-05-07"
+version: "2.2.6"
+date-released: "2025-07-24"
 keywords:
   - Ocean Tides
   - Load Tides

{pytmd-2.2.4 → pytmd-2.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyTMD
-Version: 2.2.4
+Version: 2.2.6
 Summary: Python-based tidal prediction software for estimating ocean, load, solid Earth and pole tides
 Author: Tyler Sutterley
 Author-email: tsutterl@uw.edu

{pytmd-2.2.4 → pytmd-2.2.6}/pyTMD/astro.py

@@ -49,7 +49,7 @@ UPDATE HISTORY:
     Updated 08/2020: change time variable names to not overwrite functions
     Updated 07/2020: added function docstrings
     Updated 07/2018: added option ASTRO5 to use coefficients from Richard Ray
-        for use with the GSFC Global Ocean Tides (GOT) model
+        for use with the Goddard Ocean Tides (GOT) model
         added longitude of solar perigee (Ps) as an additional output
     Updated 09/2017: added option MEEUS to use additional coefficients
         from Meeus Astronomical Algorithms to calculate mean longitudes
@@ -503,7 +503,7 @@ def mean_obliquity(MJD: np.ndarray):
     return atr*polynomial_sum(epsilon0, T)
 
 def equation_of_time(MJD: np.ndarray):
-    """Approximate calcuation of the difference between apparent and
+    """Approximate calculation of the difference between apparent and
     mean solar times :cite:p:`Meeus:1991vh,Urban:2013vl`
 
     Parameters
@@ -975,7 +975,7 @@ def _icrs_rotation_matrix(
         include_polar_motion: bool = True
     ):
     """
-    Rotation matrix for tranforming from the
+    Rotation matrix for transforming from the
     International Celestial Reference System (ICRS)
     to the International Terrestrial Reference System (ITRS)
     :cite:p:`Capitaine:2003fx,Capitaine:2003fw,Petit:2010tp`

{pytmd-2.2.4 → pytmd-2.2.6}/pyTMD/compute.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 compute.py
-Written by Tyler Sutterley (12/2024)
+Written by Tyler Sutterley (07/2025)
 Calculates tidal elevations for correcting elevation or imagery data
 Calculates tidal currents at locations and times
 
@@ -62,6 +62,8 @@ PROGRAM DEPENDENCIES:
     interpolate.py: interpolation routines for spatial data
 
 UPDATE HISTORY:
+    Updated 07/2025: mask mean pole values prior to valid epoch of convention
+    Updated 05/2025: added option to select constituents to read from model
     Updated 12/2024: moved check points function as compute.tide_masks
     Updated 11/2024: expose buffer distance for cropping tide model data
     Updated 10/2024: compute delta times based on corrections type
@@ -89,7 +91,7 @@ UPDATE HISTORY:
     Updated 06/2024: use np.clongdouble instead of np.longcomplex
     Updated 04/2024: use wrapper to importlib for optional dependencies
     Updated 02/2024: changed class name for ellipsoid parameters to datum
-    Updated 01/2024: made the inferrence of minor constituents an option
+    Updated 01/2024: made the inference of minor constituents an option
         refactored lunisolar ephemerides functions
         renamed module to compute and added tidal currents function
     Updated 12/2023: use new crs class for coordinate reprojection
@@ -230,6 +232,7 @@ def tide_elevations(
         EXTRAPOLATE: bool = False,
         CUTOFF: int | float = 10.0,
         CORRECTIONS: str | None = None,
+        CONSTITUENTS: list | None = None,
         INFER_MINOR: bool = True,
         MINOR_CONSTITUENTS: list | None = None,
         APPEND_NODE: bool = False,
@@ -297,6 +300,8 @@ def tide_elevations(
         Set to ``np.inf`` to extrapolate for all points
     CORRECTIONS: str or None, default None
         Nodal correction type, default based on model
+    CONSTITUENTS: list or None, default None
+        Specify constituents to read from model
     INFER_MINOR: bool, default True
         Infer the height values for minor tidal constituents
     MINOR_CONSTITUENTS: list or None, default None
@@ -366,7 +371,8 @@ def tide_elevations(
     nt = len(ts)
 
     # read tidal constants and interpolate to grid points
-    amp, ph, c = model.extract_constants(lon, lat, type=model.type,
+    amp, ph, c = model.extract_constants(lon, lat,
+        type=model.type, constituents=CONSTITUENTS,
         crop=CROP, bounds=BOUNDS, buffer=BUFFER, method=METHOD,
         extrapolate=EXTRAPOLATE, cutoff=CUTOFF,
         append_node=APPEND_NODE, apply_flexure=APPLY_FLEXURE)
@@ -395,7 +401,7 @@ def tide_elevations(
         for i in range(nt):
             TIDE = pyTMD.predict.map(ts.tide[i], hc, c,
                 deltat=deltat[i], corrections=nodal_corrections)
-            # calculate values for minor constituents by inferrence
+            # calculate values for minor constituents by inference
             if INFER_MINOR:
                 MINOR = pyTMD.predict.infer_minor(ts.tide[i], hc, c,
                     deltat=deltat[i], corrections=nodal_corrections,
@@ -410,7 +416,7 @@ def tide_elevations(
         tide.mask = np.any(hc.mask,axis=1)
         tide.data[:] = pyTMD.predict.drift(ts.tide, hc, c,
             deltat=deltat, corrections=nodal_corrections)
-        # calculate values for minor constituents by inferrence
+        # calculate values for minor constituents by inference
         if INFER_MINOR:
             minor = pyTMD.predict.infer_minor(ts.tide, hc, c,
                 deltat=deltat, corrections=nodal_corrections,
@@ -424,7 +430,7 @@ def tide_elevations(
             HC = hc[s,None,:]
             TIDE = pyTMD.predict.time_series(ts.tide, HC, c,
                 deltat=deltat, corrections=nodal_corrections)
-            # calculate values for minor constituents by inferrence
+            # calculate values for minor constituents by inference
             if INFER_MINOR:
                 MINOR = pyTMD.predict.infer_minor(ts.tide, HC, c,
                     deltat=deltat, corrections=nodal_corrections,
@@ -458,6 +464,7 @@ def tide_currents(
         EXTRAPOLATE: bool = False,
         CUTOFF: int | float = 10.0,
         CORRECTIONS: str | None = None,
+        CONSTITUENTS: list | None = None,
         INFER_MINOR: bool = True,
         MINOR_CONSTITUENTS: list | None = None,
         FILL_VALUE: float = np.nan,
@@ -523,6 +530,8 @@ def tide_currents(
         Set to ``np.inf`` to extrapolate for all points
     CORRECTIONS: str or None, default None
         Nodal correction type, default based on model
+    CONSTITUENTS: list or None, default None
+        Specify constituents to read from model
     INFER_MINOR: bool, default True
         Infer the height values for minor tidal constituents
     MINOR_CONSTITUENTS: list or None, default None
@@ -595,7 +604,8 @@ def tide_currents(
     # iterate over u and v currents
     for t in model.type:
         # read tidal constants and interpolate to grid points
-        amp, ph, c = model.extract_constants(lon, lat, type=t,
+        amp, ph, c = model.extract_constants(lon, lat,
+            type=t, constituents=CONSTITUENTS,
             crop=CROP, bounds=BOUNDS, buffer=BUFFER, method=METHOD,
             extrapolate=EXTRAPOLATE, cutoff=CUTOFF)
         # calculate complex phase in radians for Euler's
@@ -623,7 +633,7 @@ def tide_currents(
             for i in range(nt):
                 TIDE = pyTMD.predict.map(ts.tide[i], hc, c,
                     deltat=deltat[i], corrections=nodal_corrections)
-                # calculate values for minor constituents by inferrence
+                # calculate values for minor constituents by inference
                 if INFER_MINOR:
                     MINOR = pyTMD.predict.infer_minor(ts.tide[i], hc, c,
                         deltat=deltat[i], corrections=nodal_corrections,
@@ -638,7 +648,7 @@ def tide_currents(
             tide[t].mask = np.any(hc.mask,axis=1)
             tide[t].data[:] = pyTMD.predict.drift(ts.tide, hc, c,
                 deltat=deltat, corrections=nodal_corrections)
-            # calculate values for minor constituents by inferrence
+            # calculate values for minor constituents by inference
             if INFER_MINOR:
                 minor = pyTMD.predict.infer_minor(ts.tide, hc, c,
                     deltat=deltat, corrections=nodal_corrections,
@@ -652,7 +662,7 @@ def tide_currents(
                 HC = hc[s,None,:]
                 TIDE = pyTMD.predict.time_series(ts.tide, HC, c,
                     deltat=deltat, corrections=nodal_corrections)
-                # calculate values for minor constituents by inferrence
+                # calculate values for minor constituents by inference
                 if INFER_MINOR:
                     MINOR = pyTMD.predict.infer_minor(ts.tide, HC, c,
                         deltat=deltat, corrections=nodal_corrections,
@@ -1055,9 +1065,10 @@ def LPT_displacements(
             )
             # calculate components of load pole tides
             S = np.einsum('ti...,tji...->tj...', dxi, R)
+            smask = np.reshape(np.any(dxi.mask, axis=1), (ny,nx))
             # reshape to output dimensions
             Srad.data[:,:,i] = np.reshape(S[:,2], (ny,nx))
-            Srad.mask[:,:,i] = np.isnan(Srad.data[:,:,i])
+            Srad.mask[:,:,i] = np.isnan(Srad.data[:,:,i]) | smask
     elif (TYPE == 'drift'):
         # calculate load pole tides in cartesian coordinates
         XYZ = np.c_[X, Y, Z]
@@ -1071,10 +1082,11 @@ def LPT_displacements(
         )
         # calculate components of load pole tides
         S = np.einsum('ti...,tji...->tj...', dxi, R)
+        smask = np.any(dxi.mask, axis=1)
         # reshape to output dimensions
         Srad = np.ma.zeros((nt), fill_value=FILL_VALUE)
         Srad.data[:] = S[:,2].copy()
-        Srad.mask = np.isnan(Srad.data)
+        Srad.mask = np.isnan(Srad.data) | smask
     elif (TYPE == 'time series'):
         nstation = len(x)
         Srad = np.ma.zeros((nstation,nt), fill_value=FILL_VALUE)
@@ -1093,9 +1105,10 @@ def LPT_displacements(
             )
             # calculate components of load pole tides
             S = np.einsum('ti...,ji...->tj...', dxi, R[s,:,:])
+            smask = np.any(dxi.mask, axis=1)
             # reshape to output dimensions
             Srad.data[s,:] = S[:,2].copy()
-            Srad.mask[s,:] = np.isnan(Srad.data[s,:])
+            Srad.mask[s,:] = np.isnan(Srad.data[s,:]) | smask
 
     # replace invalid data with fill values
     Srad.data[Srad.mask] = Srad.fill_value
@@ -1279,9 +1292,10 @@ def OPT_displacements(
             )
             # calculate components of ocean pole tides
             U = np.einsum('ti...,tji...->tj...', dxi, Rinv)
+            umask = np.reshape(np.any(dxi.mask, axis=1), (ny,nx))
             # reshape to output dimensions
             Urad.data[:,:,i] = np.reshape(U[:,2], (ny,nx))
-            Urad.mask[:,:,i] = np.isnan(Urad.data[:,:,i])
+            Urad.mask[:,:,i] = np.isnan(Urad.data[:,:,i]) | umask
     elif (TYPE == 'drift'):
         # calculate ocean pole tides in cartesian coordinates
         XYZ = np.c_[X, Y, Z]
@@ -1297,10 +1311,11 @@ def OPT_displacements(
         )
         # calculate components of ocean pole tides
         U = np.einsum('ti...,tji...->tj...', dxi, Rinv)
+        umask = np.any(dxi.mask, axis=1)
         # convert to masked array
         Urad = np.ma.zeros((nt), fill_value=FILL_VALUE)
         Urad.data[:] = U[:,2].copy()
-        Urad.mask = np.isnan(Urad.data)
+        Urad.mask = np.isnan(Urad.data) | umask
     elif (TYPE == 'time series'):
         nstation = len(x)
         Urad = np.ma.zeros((nstation,nt), fill_value=FILL_VALUE)
@@ -1322,9 +1337,10 @@ def OPT_displacements(
             )
             # calculate components of ocean pole tides
             U = np.einsum('ti...,ji...->tj...', dxi, Rinv[s,:,:])
+            umask = np.any(dxi.mask, axis=1)
             # reshape to output dimensions
             Urad.data[s,:] = U[:,2].copy()
-            Urad.mask[s,:] = np.isnan(Urad.data[s,:])
+            Urad.mask[s,:] = np.isnan(Urad.data[s,:]) | umask
 
     # replace invalid data with fill values
     Urad.data[Urad.mask] = Urad.fill_value

{pytmd-2.2.4 → pytmd-2.2.6}/pyTMD/compute_tide_corrections.py

@@ -59,7 +59,7 @@ PROGRAM DEPENDENCIES:
     interpolate.py: interpolation routines for spatial data
 
 UPDATE HISTORY:
-    Updated 01/2024: made the inferrence of minor constituents an option
+    Updated 01/2024: made the inference of minor constituents an option
         refactored lunisolar ephemerides functions
         deprecated in favor of refactored compute.py module
     Updated 12/2023: use new crs class for coordinate reprojection

{pytmd-2.2.4 → pytmd-2.2.6}/pyTMD/crs.py

@@ -189,7 +189,7 @@ class crs:
         PROJECTION: int, str or dict
             Coordinate Reference System
         """
-        # coordinate reference system dictoinary
+        # coordinate reference system dictionary
         try:
             CRS = pyproj.CRS.from_user_input(PROJECTION)
         except (ValueError, pyproj.exceptions.CRSError):

pytmd-2.2.6/pyTMD/ellipse.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python
+u"""
+ellipse.py
+Written by Tyler Sutterley (05/2025)
+Expresses the amplitudes and phases for the u and v components in terms of
+    four ellipse parameters using Foreman's formula
+
+CALLING SEQUENCE:
+    umajor,uminor,uincl,uphase = pyTMD.ellipse.ellipse(u,v)
+
+INPUTS:
+    u: zonal current (EW)
+    v: meridional current (NS)
+
+OUTPUTS:
+    major: amplitude of the semimajor semi-axis
+    minor: amplitude of the semiminor semi-axis
+    incl: angle of inclination of the northern semimajor semi-axis
+    phase: phase lag of the maximum current behind the maximum tidal potential
+        of the individual constituent
+
+REFERENCE:
+    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).
+        https://doi.org/10.1016/0309-1708(89)90017-1
+
+UPDATE HISTORY:
+    Updated 06/2025: added function to calculate x and y coordinates of ellipse
+    Updated 01/2024: added inverse function to get currents from parameters
+        use complex algebra to calculate tidal ellipse parameters
+    Updated 09/2023: renamed to ellipse.py (from tidal_ellipse.py)
+    Updated 03/2023: add basic variable typing to function inputs
+    Updated 04/2022: updated docstrings to numpy documentation format
+    Written 07/2020
+"""
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = [
+    "ellipse",
+    "inverse",
+    "_xy"
+]
+
+def ellipse(u: np.ndarray, v: np.ndarray):
+    """
+    Expresses the amplitudes and phases for the u and v components in terms of
+    four ellipse parameters using Foreman's formula :cite:p:`Foreman:1989dt`
+
+    Parameters
+    ----------
+    u: np.ndarray
+        zonal current (EW)
+    v: np.ndarray
+        meridional current (NS)
+
+    Returns
+    -------
+    major: np.ndarray
+        amplitude of the semi-major axis
+    minor: np.ndarray
+        amplitude of the semi-minor axis
+    incl: np.ndarray
+        angle of inclination of the northern semi-major axis
+    phase: np.ndarray
+        phase lag of the maximum current behind the maximum tidal potential
+    """
+    # validate inputs
+    u = np.atleast_1d(u)
+    v = np.atleast_1d(v)
+    # wp, wm: complex radius of positively and negatively rotating vectors
+    wp = (u + 1j*v)/2.0
+    wm = np.conj(u - 1j*v)/2.0
+    # ap, am: amplitudes of positively and negatively rotating vectors
+    ap = np.abs(wp)
+    am = np.abs(wm)
+    # ep, em: phases of positively and negatively rotating vectors
+    ep = np.angle(wp, deg=True)
+    em = np.angle(wm, deg=True)
+    # determine the amplitudes of the semimajor and semiminor axes
+    # using Foreman's formula
+    major = (ap + am)
+    minor = (ap - am)
+    # determine the inclination and phase using Foreman's formula
+    incl = (em + ep)/2.0
+    phase = (em - ep)/2.0
+    # adjust orientation of ellipse
+    k = (incl//180.0)
+    incl -= 180.0*k
+    phase += 180.0*k
+    phase = np.mod(phase, 360.0)
+    # return values
+    return (major, minor, incl, phase)
+
+def inverse(
+        major: np.ndarray,
+        minor: np.ndarray,
+        incl: np.ndarray,
+        phase: np.ndarray
+    ):
+    """
+    Calculates currents u, v using the four tidal ellipse
+    parameters from Foreman's formula :cite:p:`Foreman:1989dt`
+
+    Parameters
+    ----------
+    major: np.ndarray
+        amplitude of the semi-major axis
+    minor: np.ndarray
+        amplitude of the semi-minor axis
+    incl: np.ndarray
+        angle of inclination of the northern semi-major axis
+    phase: np.ndarray
+        phase lag of the maximum current behind the maximum tidal potential
+
+    Returns
+    -------
+    u: np.ndarray
+        zonal current (EW)
+    v: np.ndarray
+        meridional current (NS)
+    """
+    # validate inputs
+    major = np.atleast_1d(major)
+    minor = np.atleast_1d(minor)
+    # convert inclination and phase to radians
+    incl = np.atleast_1d(incl)*np.pi/180.0
+    phase = np.atleast_1d(phase)*np.pi/180.0
+    # ep, em: phases of positively and negatively rotating vectors
+    ep = (incl - phase)
+    em = (incl + phase)
+    # ap, am: amplitudes of positively and negatively rotating vectors
+    ap = (major + minor)/2.0
+    am = (major - minor)/2.0
+    # wp, wm: complex radius of positively and negatively rotating vectors
+    wp = ap * np.exp(1j*ep)
+    wm = am * np.exp(1j*em)
+    # calculate complex currents
+    u = wp + np.conj(wm)
+    v = -1j*(wp - np.conj(wm))
+    # return values
+    return (u, v)
+
+def _xy(
+        major: float | np.ndarray,
+        minor: float | np.ndarray,
+        incl: float | np.ndarray,
+        **kwargs
+    ):
+    """
+    Calculates the x and y coordinates of the tidal ellipse
+
+    Parameters
+    ----------
+    major: np.ndarray
+        amplitude of the semi-major axis
+    minor: np.ndarray
+        amplitude of the semi-minor axis
+    incl: np.ndarray
+        angle of inclination of the northern semi-major axis
+    phase: np.ndarray or None, default None
+        phase lag of the maximum current behind the maximum tidal potential
+    xy: tuple, default (0.0, 0.0)
+        center of the ellipse (x, y)
+    N: int or None, default None
+        number of points to calculate along the ellipse
+
+    Returns
+    -------
+    x: np.ndarray
+        x coordinates of the tidal ellipse
+    y: np.ndarray
+        y coordinates of the tidal ellipse
+    """
+    # set default number of points
+    kwargs.setdefault('phase', None)
+    kwargs.setdefault('xy', (0.0, 0.0))
+    kwargs.setdefault('N', 1000)
+    # validate inputs
+    phi = incl*np.pi/180.0
+    # calculate the angle of the ellipse
+    if kwargs['phase'] is not None:
+        # use the phase lag and inclination
+        th  = (kwargs['phase'] + incl)*np.pi/180.0 
+    else:
+        # use a full rotation
+        th = np.linspace(0, 2*np.pi, kwargs['N'])
+    # calculate x and y coordinates
+    x = kwargs['xy'][0] + \
+        major*np.cos(th)*np.cos(phi) - \
+        minor*np.sin(th)*np.sin(phi)
+    y = kwargs['xy'][1] + \
+        major*np.cos(th)*np.sin(phi) + \
+        minor*np.sin(th)*np.cos(phi)
+    return (x, y)

{pytmd-2.2.4 → pytmd-2.2.6}/pyTMD/io/GOT.py

@@ -3,10 +3,10 @@ u"""
 GOT.py
 Written by Tyler Sutterley (11/2024)
 
-Reads files for Richard Ray's Global Ocean Tide (GOT) models and makes initial
-    calculations to run the tide program
-Includes functions to extract tidal harmonic constants out of a tidal model for
-    given locations
+Reads files for Richard Ray's Goddard Ocean Tide (GOT) models and makes
+    initial calculations to run the tide program
+Includes functions to extract tidal harmonic constants out of a tidal
+    model for given locations
 
 INPUTS:
     ilon: longitude to interpolate
@@ -123,7 +123,7 @@ def extract_constants(
         **kwargs
     ):
     """
-    Reads files for Richard Ray's Global Ocean Tide (GOT) models
+    Reads files for Richard Ray's Goddard Ocean Tide (GOT) models
 
     Makes initial calculations to run the tide program
 
@@ -315,7 +315,7 @@ def read_constants(
         **kwargs
     ):
     """
-    Reads files for Richard Ray's Global Ocean Tide (GOT) models
+    Reads files for Richard Ray's Goddard Ocean Tide (GOT) models
 
     Parameters
     ----------
@@ -540,7 +540,7 @@ def read_ascii_file(
         **kwargs
     ):
     """
-    Read Richard Ray's Global Ocean Tide (GOT) model file
+    Read Richard Ray's Goddard Ocean Tide (GOT) model file
 
     Parameters
     ----------
@@ -625,7 +625,7 @@ def read_netcdf_file(
         **kwargs
     ):
     """
-    Read Richard Ray's Global Ocean Tide (GOT) netCDF4 model file
+    Read Richard Ray's Goddard Ocean Tide (GOT) netCDF4 model file
 
     Parameters
     ----------