compute

• Calculates tidal elevations at points and times

  • Can use OTIS format tidal solutions provided by Oregon State University and ESR

  • Can use Global Tide Model (GOT) solutions provided by Richard Ray at GSFC

  • Can use Finite Element Solution (FES) models provided by AVISO

• Calculates tidal currents at points and times

  • Can use OTIS format tidal solutions provided by Oregon State University and ESR

  • Can use Finite Element Solution (FES) models provided by AVISO

• Calculates long-period equilibrium tides (LPET) at points and times

  • Uses the summation of fifteen tidal spectral lines from Cartwright and Edden [11]

• Calculates radial pole load tides (LPT) at points and times

  • Following IERS Convention (2010) guidelines

• Calculates radial ocean pole load tides (OPT) at points and times

  • Following IERS Convention (2010) guidelines

• Calculates radial solid earth tides (SET) at points and times

  • Following IERS Convention (2010) guidelines

  • Using a tide potential catalog following Cartwright and Tayler [12]

• Calculates tide-generating forces (TGF) at points and times [74]

Source code

pyTMD.compute.corrections(x: ndarray, y: ndarray, delta_time: ndarray, correction: str = 'ocean', **kwargs)

Wrapper function to compute tide corrections at points and times

Parameters:

x: np.ndarray

x-coordinates

y: np.ndarray

y-coordinates

delta_time: np.ndarray

Time coordinates

correction: str, default ‘ocean’

Correction type to compute

• 'ocean': ocean tide from model constituents

• 'load': load tide from model constituents

• 'LPET': long-period equilibrium tide

• 'LPT': solid earth load pole tide

• 'OPT': ocean pole tide

• 'SET': solid earth tide

kwargs: dict

Keyword arguments for correction functions

Returns:

xarray.DataArray or xarray.Dataset

Tidal correction values evaluated at the input coordinates and times. The exact return type, dimensions, and units are those of the underlying helper function:

• correction in {'ocean', 'load'} → tide_elevations()

• correction == 'LPET' → LPET_elevations()

• correction == 'LPT' → LPT_displacements()

• correction == 'OPT' → OPT_displacements()

• correction == 'SET' → SET_displacements()

Refer to the respective helper function docstrings for details on the variable names, units, and metadata of the returned object.

pyTMD.compute.tide_elevations(x: ndarray, y: ndarray, delta_time: ndarray, directory: str | Path | None = PosixPath('/home/docs/.cache/pytmd'), model: str | None = None, definition_file: str | Path | IOBase | None = None, crop: bool = False, bounds: list | ndarray | None = None, buffer: int | float = 0, crs: str | int = 4326, epoch: list | tuple = (2000, 1, 1, 0, 0, 0), type: str | None = 'trajectory', standard: str = 'UTC', method: str = 'linear', extrapolate: bool = False, cutoff: int | float = 10.0, **kwargs)

Compute ocean or load tides at points and times from model constituents

Parameters:

x: np.ndarray

x-coordinates

y: np.ndarray

y-coordinates

delta_time: np.ndarray

Time coordinates

directory: str or NoneType, default None

working data directory for tide models

model: str or NoneType, default None

Tide model to use in correction

definition_file: str, pathlib.Path, io.IOBase or NoneType, default None

Tide model definition file for use

chunks: int, dict, str, or None, default None

Variable chunk sizes for dask (see xarray.open_dataset)

crop: bool, default False

Crop tide model data to (buffered) bounds

bounds: list, np.ndarray or NoneType, default None

Boundaries for cropping tide model data

buffer: int or float, default 0

Buffer distance for cropping tide model data

crs: int, default: 4326 (WGS84 Latitude and Longitude)

Input coordinate reference system

epoch: tuple, default (2000,1,1,0,0,0)

Time period for calculating delta times

type: str or NoneType, default ‘trajectory’

Input data type

• None: determined from input variable dimensions

• 'trajectory': drift buoys or satellite/airborne altimetry

• 'grid': spatial grids or images

• 'time series': time series at a single point

standard: str, default ‘UTC’

Time standard of input temporal data

• 'GPS': leap seconds needed

• 'LORAN': leap seconds needed (LORAN = GPS + 9 seconds)

• 'TAI': leap seconds needed (TAI = GPS + 19 seconds)

• 'UTC': no leap seconds needed

• 'datetime': numpy datetime array in UTC

method: str = ‘linear’

Interpolation method from xarray

• 'linear': linear interpolation for regular grids

• 'nearest': nearest-neighbor interpolation

extrapolate: bool, default False

Spatially extrapolate values beyond model domain

cutoff: int or float, default 10.0

Extrapolation cutoff (kilometers)

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

Specify constituents to infer

append_node: bool, default False

Append equilibrium amplitudes for node tides

apply_flexure: bool, default False

Apply ice flexure scaling factor to height values

Only valid for models containing flexure fields

Returns:

tpred: xarray.DataArray

Predicted tide elevation (meters)

pyTMD.compute.tide_currents(x: ndarray, y: ndarray, delta_time: ndarray, directory: str | Path | None = PosixPath('/home/docs/.cache/pytmd'), model: str | None = None, definition_file: str | Path | IOBase | None = None, crop: bool = False, bounds: list | ndarray | None = None, buffer: int | float = 0, crs: str | int = 4326, epoch: list | tuple = (2000, 1, 1, 0, 0, 0), type: str | None = 'trajectory', standard: str = 'UTC', method: str = 'linear', extrapolate: bool = False, cutoff: int | float = 10.0, **kwargs)

Compute ocean tide currents at points and times from model constituents

Parameters:

x: np.ndarray

x-coordinates

y: np.ndarray

y-coordinates

delta_time: np.ndarray

Time coordinates

directory: str or NoneType, default None

Working data directory for tide models

model: str or NoneType, default None

Tide model to use in correction

definition_file: str, pathlib.Path, io.IOBase or NoneType, default None

Tide model definition file for use

chunks: int, dict, str, or None, default None

Variable chunk sizes for dask (see xarray.open_dataset)

crop: bool, default False

Crop tide model data to (buffered) bounds

bounds: list, np.ndarray or NoneType, default None

Boundaries for cropping tide model data

buffer: int or float, default 0

Buffer distance for cropping tide model data

crs: int, default: 4326 (WGS84 Latitude and Longitude)

Input coordinate system

epoch: tuple, default (2000,1,1,0,0,0)

Time period for calculating delta times

type: str or NoneType, default ‘trajectory’

Input data type

• None: determined from input variable dimensions

• 'trajectory': drift buoys or satellite/airborne altimetry

• 'grid': spatial grids or images

• 'time series': time series at a single point

standard: str, default ‘UTC’

Time standard of input temporal data

• 'GPS': leap seconds needed

• 'LORAN': leap seconds needed (LORAN = GPS + 9 seconds)

• 'TAI': leap seconds needed (TAI = GPS + 19 seconds)

• 'UTC': no leap seconds needed

• 'datetime': numpy datetime array in UTC

method: str

Interpolation method from xarray

• 'linear': linear interpolation for regular grids

• 'nearest': nearest-neighbor interpolation

extrapolate: bool, default False

Spatially extrapolate values beyond model domain

cutoff: int or float, default 10.0

Extrapolation cutoff (kilometers)

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

Specify constituents to infer

Returns:

tpred: xr.DataTree

Predicted tidal currents (cm s^-1)

• u: Zonal velocities

• v: Meridional velocities

pyTMD.compute.tide_masks(x: ndarray, y: ndarray, directory: str | Path | None = PosixPath('/home/docs/.cache/pytmd'), model: str | None = None, definition_file: str | Path | IOBase | None = None, crs: str | int = 4326, type: str | None = 'trajectory', method: str = 'linear', **kwargs)

Check if points are within a tide model domain

Parameters:

x: np.ndarray

x-coordinates

y: np.ndarray

y-coordinates

directory: str or NoneType, default None

Working data directory for tide models

model: str or NoneType, default None

Tide model to use

definition_file: str or NoneType, default None

Tide model definition file for use

crs: str or int, default: 4326 (WGS84 Latitude and Longitude)

Input coordinate system

type: str or NoneType, default ‘trajectory’

Input data type

• 'trajectory': drift buoys or satellite/airborne altimetry

• 'grid': spatial grids or images

• 'time series': time series at a single point

method: str, default ‘linear’

Interpolation method from xarray

• 'linear': linear interpolation for regular grids

• 'nearest': nearest-neighbor interpolation

Returns:

mask: xr.DataArray

Ocean tide mask

pyTMD.compute.LPET_elevations(x: ndarray, y: ndarray, delta_time: ndarray, crs: str | int = 4326, epoch: list | tuple = (2000, 1, 1, 0, 0, 0), type: str | None = 'trajectory', standard: str = 'UTC', **kwargs)

Compute long-period equilibrium tidal elevations at points and times

Parameters:

x: np.ndarray

x-coordinates

y: np.ndarray

y-coordinates

delta_time: np.ndarray

Time coordinates

crs: int, default: 4326 (WGS84 Latitude and Longitude)

Input coordinate system

epoch: tuple, default (2000,1,1,0,0,0)

Time period for calculating delta times

type: str or NoneType, default ‘trajectory’

Input data type

• None: determined from input variable dimensions

• 'trajectory': drift buoys or satellite/airborne altimetry

• 'grid': spatial grids or images

• 'time series': time series at a single point

standard: str, default ‘UTC’

Time standard of input temporal data

• 'GPS': leap seconds needed

• 'LORAN': leap seconds needed (LORAN = GPS + 9 seconds)

• 'TAI': leap seconds needed (TAI = GPS + 19 seconds)

• 'UTC': no leap seconds needed

• 'datetime': numpy datetime array in UTC

Returns:

LPET: xr.DataArray

Long-period equilibrium tide (meters)

pyTMD.compute.LPT_displacements(x: ndarray, y: ndarray, delta_time: ndarray, crs: str | int = 4326, epoch: list | tuple = (2000, 1, 1, 0, 0, 0), type: str | None = 'trajectory', standard: str = 'UTC', ellipsoid: str = 'WGS84', convention: str = '2018', variable: str | list = 'R', **kwargs)

Compute radial load pole tide displacements at points and times following IERS Convention (2010) guidelines

Parameters:

x: np.ndarray

x-coordinates

y: np.ndarray

y-coordinates

delta_time: np.ndarray

Time coordinates

crs: int, default: 4326 (WGS84 Latitude and Longitude)

Input coordinate system

epoch: tuple, default (2000,1,1,0,0,0)

Time period for calculating delta times

type: str or NoneType, default ‘trajectory’

Input data type

• None: determined from input variable dimensions

• 'trajectory': drift buoys or satellite/airborne altimetry

• 'grid': spatial grids or images

• 'time series': time series at a single point

standard: str, default ‘UTC’

Time standard of input temporal data

• 'GPS': leap seconds needed

• 'LORAN': leap seconds needed (LORAN = GPS + 9 seconds)

• 'TAI': leap seconds needed (TAI = GPS + 19 seconds)

• 'UTC': no leap seconds needed

• 'datetime': numpy datetime array in UTC

ellipsoid: str, default ‘WGS84’

Ellipsoid name for calculating Earth parameters

convention: str, default ‘2018’

IERS Mean or Secular Pole Convention

• '2003'

• '2010'

• '2015'

• '2018'

variable: str or list, default ‘R’

Output variable(s) to extract from dataset

• 'N': north displacement

• 'E': east displacement

• 'R': radial displacement

Returns:

S: xr.DataArray or xr.Dataset

Solid earth pole tide (meters)

pyTMD.compute.OPT_displacements(x: ndarray, y: ndarray, delta_time: ndarray, crs: str | int = 4326, epoch: list | tuple = (2000, 1, 1, 0, 0, 0), type: str | None = 'trajectory', standard: str = 'UTC', ellipsoid: str = 'WGS84', convention: str = '2018', method: str = 'linear', variable: str | list = 'R', **kwargs)

Compute radial ocean pole tide displacements at points and times following IERS Convention (2010) guidelines

Parameters:

x: np.ndarray

x-coordinates

y: np.ndarray

y-coordinates

delta_time: np.ndarray

Time coordinates

crs: str | int, default: 4326 (WGS84 Latitude and Longitude)

Input coordinate system

epoch: tuple, default (2000,1,1,0,0,0)

Time period for calculating delta times

type: str or NoneType, default ‘trajectory’

Input data type

• None: determined from input variable dimensions

• 'trajectory': drift buoys or satellite/airborne altimetry

• 'grid': spatial grids or images

• 'time series': time series at a single point

standard: str, default ‘UTC’

Time standard of input temporal data

• 'GPS': leap seconds needed

• 'LORAN': leap seconds needed (LORAN = GPS + 9 seconds)

• 'TAI': leap seconds needed (TAI = GPS + 19 seconds)

• 'UTC': no leap seconds needed

• 'datetime': numpy datetime array in UTC

ellipsoid: str, default ‘WGS84’

Ellipsoid name for calculating Earth parameters

convention: str, default ‘2018’

IERS Mean or Secular Pole Convention

• '2003'

• '2010'

• '2015'

• '2018'

method: str

Interpolation method from xarray

• 'linear': linear interpolation for regular grids

• 'nearest': nearest-neighbor interpolation

variable: str or list, default ‘R’

Output variable(s) to extract from dataset

• 'N': north displacement

• 'E': east displacement

• 'R': radial displacement

Returns:

U: xr.DataArray or xr.Dataset

Ocean pole tide (meters)

pyTMD.compute.SET_displacements(x: ndarray, y: ndarray, delta_time: ndarray, method: str = 'ephemerides', **kwargs)

Compute solid Earth tidal elevations (body tides) at points and times

Parameters:

x: np.ndarray

x-coordinates

y: np.ndarray

y-coordinates

delta_time: np.ndarray

Time coordinates

method: str, default ‘ephemerides’

Method for calculating solid earth tidal elevations

• 'ephemerides': following Petit and Luzum [56]

• 'catalog': using tide potential catalogs

pyTMD.compute._ephemerides_SET(x: ndarray, y: ndarray, delta_time: ndarray, crs: str | int = 4326, epoch: list | tuple = (2000, 1, 1, 0, 0, 0), type: str | None = 'trajectory', standard: str = 'UTC', ellipsoid: str = 'WGS84', tide_system: str = 'tide_free', ephemerides: str = 'Montenbruck', variable: str | list = 'R', **kwargs)

Compute solid Earth tidal elevations at points and times following IERS Convention (2010) guidelines

Parameters:

x: np.ndarray

x-coordinates

y: np.ndarray

y-coordinates

delta_time: np.ndarray

Time coordinates

crs: int, default: 4326 (WGS84 Latitude and Longitude)

Input coordinate system

epoch: tuple, default (2000,1,1,0,0,0)

Time period for calculating delta times

type: str or NoneType, default ‘trajectory’

Input data type

• None: determined from input variable dimensions

• 'trajectory': drift buoys or satellite/airborne altimetry

• 'grid': spatial grids or images

• 'time series': time series at a single point

standard: str, default ‘UTC’

Time standard of input temporal data

• 'GPS': leap seconds needed

• 'LORAN': leap seconds needed (LORAN = GPS + 9 seconds)

• 'TAI': leap seconds needed (TAI = GPS + 19 seconds)

• 'UTC': no leap seconds needed

• 'datetime': numpy datetime array in UTC

ellipsoid: str, default ‘WGS84’

Ellipsoid name for calculating Earth parameters

tide_system: str, default ‘tide_free’

Permanent tide system for the output solid Earth tide

• 'tide_free': no permanent direct and indirect tidal potentials

• 'mean_tide': permanent tidal potentials (direct and indirect)

ephemerides: str, default ‘Montenbruck’

Method for calculating lunar and solar ephemerides

• 'Kubo': Kubo [35]

• 'Meeus': Meeus [45]

• 'Montenbruck': Montenbruck [48]

• 'JPL': computed ephemerides from JPL kernels

variable: str or list, default ‘R’

Output variable(s) to extract from dataset

• 'N': north displacement

• 'E': east displacement

• 'R': radial displacement

kwargs: dict, optional

Additional keyword arguments to pass to the prediction function

Returns:

SE: xr.DataArray or xr.Dataset

Solid Earth tide (meters)

pyTMD.compute._catalog_SET(x: ndarray, y: ndarray, delta_time: ndarray, crs: str | int = 4326, epoch: list | tuple = (2000, 1, 1, 0, 0, 0), type: str | None = 'trajectory', standard: str = 'UTC', catalog: str = 'CTE1973', tide_system: str = 'tide_free', ephemerides: str = 'IERS', include_planets: bool = False, variable: str | list = 'R', **kwargs)

Compute solid Earth tidal elevations at points and times using a tide-potential catalog following Cartwright and Tayler [12]

Parameters:

x: np.ndarray

x-coordinates

y: np.ndarray

y-coordinates

delta_time: np.ndarray

Time coordinates

crs: int, default: 4326 (WGS84 Latitude and Longitude)

Input coordinate system

epoch: tuple, default (2000,1,1,0,0,0)

Time period for calculating delta times

type: str or NoneType, default ‘trajectory’

Input data type

• None: determined from input variable dimensions

• 'trajectory': drift buoys or satellite/airborne altimetry

• 'grid': spatial grids or images

• 'time series': time series at a single point

standard: str, default ‘UTC’

Time standard of input temporal data

• 'GPS': leap seconds needed

• 'LORAN': leap seconds needed (LORAN = GPS + 9 seconds)

• 'TAI': leap seconds needed (TAI = GPS + 19 seconds)

• 'UTC': no leap seconds needed

• 'datetime': numpy datetime array in UTC

catalog: str, default ‘CTE1973’

Name of the tide potential catalog

• 'CTE1973': Cartwright and Edden [11]

• 'HW1995': Hartmann and Wenzel [27]

• 'T1987': Tamura [74]

• 'W1990': Woodworth updates to 'CTE1973'

tide_system: str, default ‘tide_free’

Permanent tide system for the output solid Earth tide

• 'tide_free': no permanent direct and indirect tidal potentials

• 'mean_tide': permanent tidal potentials (direct and indirect)

ephemerides: str, default ‘IERS’

Method for calculating astronomical mean longitudes

• 'Cartwright': use coefficients from David Cartwright

• 'Meeus': use coefficients from Meeus Astronomical Algorithms

• 'ASTRO5': use Meeus Astronomical coefficients from ASTRO5

• 'IERS': convert from IERS Delaunay arguments

include_planets: bool, default False

Include tide potentials from planetary bodies

variable: str | list, default ‘R’

Output variable(s) to extract from dataset

• 'N': north displacement

• 'E': east displacement

• 'R': radial displacement

kwargs: dict, optional

Additional keyword arguments to pass to the prediction function

Returns:

SE: xr.DataArray or xr.Dataset

Solid Earth tide (meters)

pyTMD.compute.TG_forces(x: ndarray, y: ndarray, delta_time: ndarray, h: float | ndarray = 0.0, crs: str | int = 4326, epoch: list | tuple = (2000, 1, 1, 0, 0, 0), type: str | None = 'trajectory', standard: str = 'UTC', ellipsoid: str = 'WGS84', ephemerides: str = 'Montenbruck', variable: str | list = 'R', **kwargs)

Compute tide-generating forces at points and times following Hartmann and Wenzel [27], Tamura [74]

Parameters:

x: np.ndarray

x-coordinates

y: np.ndarray

y-coordinates

delta_time: np.ndarray

Time coordinates

h: float or np.ndarray, default 0.0

Height of the point above the ellipsoid (meters)

crs: int, default: 4326 (WGS84 Latitude and Longitude)

Input coordinate system

epoch: tuple, default (2000,1,1,0,0,0)

Time period for calculating delta times

type: str or NoneType, default ‘trajectory’

Input data type

• None: determined from input variable dimensions

• 'trajectory': drift buoys or satellite/airborne altimetry

• 'grid': spatial grids or images

• 'time series': time series at a single point

standard: str, default ‘UTC’

Time standard of input temporal data

• 'GPS': leap seconds needed

• 'LORAN': leap seconds needed (LORAN = GPS + 9 seconds)

• 'TAI': leap seconds needed (TAI = GPS + 19 seconds)

• 'UTC': no leap seconds needed

• 'datetime': numpy datetime array in UTC

ellipsoid: str, default ‘WGS84’

Ellipsoid name for calculating Earth parameters

ephemerides: str, default ‘Montenbruck’

Method for calculating lunar and solar ephemerides

• 'Kubo': Kubo [35]

• 'Meeus': Meeus [45]

• 'Montenbruck': Montenbruck [48]

• 'JPL': computed ephemerides from JPL kernels

variable: str | list, default ‘R’

Output variable(s) to extract from dataset

• 'N': generating force in the north direction

• 'E': generating force in the east direction

• 'R': generating force in the radial direction

kwargs: dict, optional

Additional keyword arguments to pass to the prediction function

Returns:

TGF: xr.DataArray or xr.Dataset

Tide-generating forces (m s^-2)

pyTMD.compute.GT_accelerations(x: ndarray, y: ndarray, delta_time: ndarray, h: float | ndarray = 0.0, crs: str | int = 4326, epoch: list | tuple = (2000, 1, 1, 0, 0, 0), type: str | None = 'trajectory', standard: str = 'UTC', ellipsoid: str = 'WGS84', ephemerides: str = 'Montenbruck', **kwargs)

Compute the estimated gravity tides at points and times following Hartmann and Wenzel [27], Tamura [74]

Parameters:

x: np.ndarray

x-coordinates

y: np.ndarray

y-coordinates

delta_time: np.ndarray

Time coordinates

h: float or np.ndarray, default 0.0

Height of the point above the ellipsoid (meters)

crs: int, default: 4326 (WGS84 Latitude and Longitude)

Input coordinate system

epoch: tuple, default (2000,1,1,0,0,0)

Time period for calculating delta times

type: str or NoneType, default ‘trajectory’

Input data type

• None: determined from input variable dimensions

• 'trajectory': drift buoys or satellite/airborne altimetry

• 'grid': spatial grids or images

• 'time series': time series at a single point

standard: str, default ‘UTC’

Time standard of input temporal data

• 'GPS': leap seconds needed

• 'LORAN': leap seconds needed (LORAN = GPS + 9 seconds)

• 'TAI': leap seconds needed (TAI = GPS + 19 seconds)

• 'UTC': no leap seconds needed

• 'datetime': numpy datetime array in UTC

ellipsoid: str, default ‘WGS84’

Ellipsoid name for calculating Earth parameters

ephemerides: str, default ‘Montenbruck’

Method for calculating lunar and solar ephemerides

• 'Kubo': Kubo [35]

• 'Meeus': Meeus [45]

• 'Montenbruck': Montenbruck [48]

• 'JPL': computed ephemerides from JPL kernels

kwargs: dict, optional

Additional keyword arguments to pass to the prediction function

Returns:

G: xr.DataArray or xr.Dataset

Estimated gravity tides (m s^-2)