pyTMD 2.2.4__tar.gz → 2.2.5__tar.gz

{pytmd-2.2.4 → pytmd-2.2.5}/.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.5}/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.5"
+date-released: "2025-06-23"
 keywords:
   - Ocean Tides
   - Load Tides

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyTMD
-Version: 2.2.4
+Version: 2.2.5
 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.5}/pyTMD/compute.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 compute.py
-Written by Tyler Sutterley (12/2024)
+Written by Tyler Sutterley (05/2025)
 Calculates tidal elevations for correcting elevation or imagery data
 Calculates tidal currents at locations and times
 
@@ -62,6 +62,7 @@ PROGRAM DEPENDENCIES:
     interpolate.py: interpolation routines for spatial data
 
 UPDATE HISTORY:
+    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 +90,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 +231,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 +299,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 +370,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 +400,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 +415,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 +429,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 +463,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 +529,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 +603,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 +632,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 +647,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 +661,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,

{pytmd-2.2.4 → pytmd-2.2.5}/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.5/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.5}/pyTMD/io/OTIS.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 OTIS.py
-Written by Tyler Sutterley (12/2024)
+Written by Tyler Sutterley (05/2025)
 
 Reads files for a tidal model and makes initial calculations to run tide program
 Includes functions to extract tidal harmonic constants from OTIS tide models for
@@ -36,6 +36,8 @@ OPTIONS:
         ATLAS: reading a global solution with localized solutions
         TMD3: combined global or local netCDF4 solution
         OTIS: combined global or local solution
+    constituents: list or None, default None
+        Specify constituents to read from model
     apply_flexure: apply ice flexure scaling factor to constituents
 
 OUTPUTS:
@@ -58,6 +60,7 @@ PROGRAM DEPENDENCIES:
     interpolate.py: interpolation routines for spatial data
 
 UPDATE HISTORY:
+    Updated 05/2025: added option to select constituents to read from model
     Updated 12/2024: released version of TMD3 has different variable names
     Updated 11/2024: expose buffer distance for cropping tide model data
     Updated 10/2024: save latitude and longitude to output constituent object
@@ -210,6 +213,8 @@ def extract_constants(
             - ``'ATLAS'``: reading a global solution with localized solutions
             - ``'OTIS'``: combined global or local solution
             - ``'TMD3'``: combined global or local netCDF4 solution
+    constituents: list or None, default None
+        Specify constituents to read from model
     crop: bool, default False
         Crop tide model data to (buffered) bounds
     bounds: list or NoneType, default None
@@ -245,6 +250,7 @@ def extract_constants(
     # set default keyword arguments
     kwargs.setdefault('type', 'z')
     kwargs.setdefault('grid', 'OTIS')
+    kwargs.setdefault('constituents', None)
     kwargs.setdefault('crop', False)
     kwargs.setdefault('bounds', None)
     kwargs.setdefault('buffer', None)
@@ -394,12 +400,19 @@ def extract_constants(
     elif kwargs['type'] in ('z','V','U'):
         unit_conv = 1.0
 
-    # read and interpolate each constituent
+    # read list of constituents
     if isinstance(model_file,list):
-        constituents = [read_constituents(m)[0].pop() for m in model_file]
-        nc = len(constituents)
+        cons = [read_constituents(m)[0].pop() for m in model_file]
+        nc = len(cons)
     else:
-        constituents,nc = read_constituents(model_file, grid=kwargs['grid'])
+        cons,nc = read_constituents(model_file, grid=kwargs['grid'])
+    # reduce number of constituents
+    if kwargs['constituents'] is not None:
+        # verify that constituents is a list
+        if isinstance(kwargs['constituents'], str):
+            kwargs['constituents'] = [kwargs['constituents']]
+        # number of constituents to read
+        nc = len(kwargs['constituents'])
 
     # number of output data points
     npts = len(D)
@@ -407,8 +420,17 @@ def extract_constants(
     amplitude.mask = np.zeros((npts,nc), dtype=bool)
     ph = np.ma.zeros((npts,nc))
     ph.mask = np.zeros((npts,nc), dtype=bool)
+    constituents = []
     # read and interpolate each constituent
-    for i,c in enumerate(constituents):
+    for j in range(nc):
+        # if reading a specific constituent
+        if (kwargs['constituents'] is not None):
+            c = kwargs['constituents'][j]
+        else:
+            c = cons[j]
+        # find index of constituent in list
+        i = cons.index(c)
+        # read constituent for type
         if (kwargs['type'] == 'z'):
             # read z constituent from elevation file
             if (kwargs['grid'] == 'ATLAS'):
@@ -503,13 +525,15 @@ def extract_constants(
                 is_geographic=is_geographic)
         # convert units
         # amplitude and phase of the constituent
-        amplitude.data[:,i] = np.abs(hci.data)/unit_conv
-        amplitude.mask[:,i] = np.copy(hci.mask)
-        ph.data[:,i] = np.arctan2(-np.imag(hci), np.real(hci))
-        ph.mask[:,i] = np.copy(hci.mask)
+        amplitude.data[:,j] = np.abs(hci.data)/unit_conv
+        amplitude.mask[:,j] = np.copy(hci.mask)
+        ph.data[:,j] = np.arctan2(-np.imag(hci), np.real(hci))
+        ph.mask[:,j] = np.copy(hci.mask)
         # update mask to invalidate points outside model domain
-        ph.mask[:,i] |= invalid
-        amplitude.mask[:,i] |= invalid
+        ph.mask[:,j] |= invalid
+        amplitude.mask[:,j] |= invalid
+        # append constituent to list
+        constituents.append(c)
 
     # convert phase to degrees
     phase = ph*180.0/np.pi
@@ -552,6 +576,8 @@ def read_constants(
             - ``'ATLAS'``: reading a global solution with localized solutions
             - ``'OTIS'``: combined global or local solution
             - ``'TMD3'``: combined global or local netCDF4 solution
+    constituents: list or None, default None
+        Specify constituents to read from model
     crop: bool, default False
         Crop tide model data to (buffered) bounds
     bounds: list or NoneType, default None
@@ -569,6 +595,7 @@ def read_constants(
     # set default keyword arguments
     kwargs.setdefault('type', 'z')
     kwargs.setdefault('grid', 'OTIS')
+    kwargs.setdefault('constituents', None)
     kwargs.setdefault('crop', False)
     kwargs.setdefault('bounds', None)
     kwargs.setdefault('buffer', 0)
@@ -664,18 +691,34 @@ def read_constants(
     gridx, gridy = np.meshgrid(xi, yi)
     lon, lat = crs.transform(gridx, gridy, direction='INVERSE')
 
-    # read each constituent
+    # read list of constituents
     if isinstance(model_file, list):
         cons = [read_constituents(m)[0].pop() for m in model_file]
+        nc = len(cons)
     else:
-        cons,_ = read_constituents(model_file, grid=kwargs['grid'])
+        cons,nc = read_constituents(model_file, grid=kwargs['grid'])
+    # reduce number of constituents
+    if kwargs['constituents'] is not None:
+        # verify that constituents is a list
+        if isinstance(kwargs['constituents'], str):
+            kwargs['constituents'] = [kwargs['constituents']]
+        # number of constituents to read
+        nc = len(kwargs['constituents'])
+
     # save output constituents and coordinate reference system
     constituents = pyTMD.io.constituents(x=xi, y=yi,
         bathymetry=bathymetry.data, mask=mask, crs=crs,
         longitude=lon, latitude=lat)
 
     # read each model constituent
-    for i,c in enumerate(cons):
+    for j in range(nc):
+        # if reading a specific constituent
+        if (kwargs['constituents'] is not None):
+            c = kwargs['constituents'][j]
+        else:
+            c = cons[j]
+        # find index of constituent in list
+        i = cons.index(c)
         if (kwargs['type'] == 'z'):
             # read constituent from elevation file
             if (kwargs['grid'] == 'ATLAS'):