Prediction Functions#

These are the three entry points for computing tides. Each function accepts arrays of epochs, longitudes, and latitudes and returns Eigen-style vectors with the predicted heights.

evaluate_tide interpolates harmonic constants from a gridded tidal model, while evaluate_tide_from_constituents works directly from user-supplied amplitudes and phase lags (e.g. from a tide-gauge harmonic analysis). evaluate_equilibrium_long_period provides the long-period equilibrium tide from the Cartwright-Tayler-Edden tables.

pyfes.evaluate_tide(tidal_model: TidalModelInterfaceComplex128 | TidalModelInterfaceComplex64, date: ndarray[Any, dtype[ScalarType_co]], longitude: ndarray[Any, dtype[ScalarType_co]], latitude: ndarray[Any, dtype[ScalarType_co]], *, settings: Settings | None = None) → tuple[ndarray[Any, dtype[ScalarType_co]], ndarray[Any, dtype[ScalarType_co]], ndarray[Any, dtype[ScalarType_co]]]#

Compute the tide at the given location and time.

Parameters:

tidal_model – Tidal models used to interpolate the modeled waves.
date – Date of the tide calculation.
longitude – Longitude in degrees for the position at which the tide is calculated.
latitude – Latitude in degrees for the position at which the tide is calculated.
settings – Settings used for the tide calculation. Using FESSettings runs the Darwin prediction engine and PerthSettings runs the PERTH prediction engine.

Returns:

The height of the diurnal and semi-diurnal constituents of the tidal spectrum (same unit as the tidal model, typically cm)
The height of the long period wave constituents of the tidal spectrum (same unit as the tidal model, typically cm)
The quality flag indicating the reliability of the tide calculation at the given position:
- 0: the tide is undefined (no model data available at the given position).
- Positive values: the tide is interpolated at the given position using N data points (where N is the number of data points used for the interpolation).
- Negative values: the tide is extrapolated at the given position using -N data points (where N is the number of data points used for the extrapolation).

Example

>>> import pyfes
>>> import numpy as np
>>> # 1. Load the model (requires a config file)
>>> model = pyfes.config.load('path/to/config.yaml')
>>> # 2. Define space and time
>>> dates = np.array(['2025-01-01T12:00:00'], dtype='datetime64[us]')
>>> lons = np.array([0.0])
>>> lats = np.array([45.0])
>>> # 3. Compute tide
>>> tide, lp, flags = pyfes.evaluate_tide(model, dates, lons, lats)
>>> total_height = tide + lp

Note

Computed height of the diurnal and semi-diurnal constituents is set to nan if no data is available at the given position. The long period wave constituents is always computed because this value does not depend on model data.

Warning

If Settings.compute_long_period_equilibrium returns true, the tidal model must use centimeters. The long period equilibrium is computed in centimeters and is added to the model tide; mixing units would make the result inconsistent.

pyfes.evaluate_tide_from_constituents(constituents: Mapping[str, tuple[float, float]], date: ndarray[Any, dtype[ScalarType_co]], latitude: float, *, settings: Settings | None = None) → tuple[ndarray[Any, dtype[ScalarType_co]], ndarray[Any, dtype[ScalarType_co]]]#

Compute the tide from known tidal constituents.

Unlike evaluate_tide() which interpolates constituents from a tidal model, this function computes the tidal prediction directly from a list of tidal constituents whose properties (amplitude and phase) are known. This is typically used for tide gauge analysis and prediction, where the constituents have been previously determined from harmonic analysis of observed sea level data.

Parameters:

constituents – Dictionary mapping tidal constituents to their (amplitude, phase) properties. Amplitude is in metric units and phase is in degrees.
date – Date of the tide calculation.
latitude – Latitude in degrees for the position.
settings – Settings used for the tide calculation. Using FESSettings runs the Darwin prediction engine, and PerthSettings runs the PERTH prediction engine. The default value is None, which corresponds to the default settings for FES models.

Returns:

The height of the diurnal and semi-diurnal constituents of the tidal spectrum (cm)
The height of the long period wave constituents of the tidal spectrum (cm)

Example

>>> import pyfes
>>> import numpy as np
>>> # Define constituents from harmonic analysis
>>> constituents = {
...     'M2': (50.0, 120.0),  # 50cm amplitude, 120° phase
...     'S2': (20.0, 90.0),  # 20cm amplitude, 90° phase
...     'K1': (15.0, 45.0),  # 15cm amplitude, 45° phase
... }
>>> # Calculate tide at a specific location over time
>>> dates = np.arange(
...     np.datetime64('2024-01-01'),
...     np.datetime64('2024-01-02'),
...     np.timedelta64(1, 'h'),
... )
>>> tide, lp = pyfes.evaluate_tide_from_constituents(
...     constituents, dates, 48.0
... )

Note

The constituents dictionary should map each pyfes.Constituent to a tuple of (amplitude, phase). The amplitude and phase values are typically obtained from prior harmonic analysis of observed tide gauge data.

Warning

pyfes.evaluate_equilibrium_long_period(date: ndarray[Any, dtype[ScalarType_co]], latitude: ndarray[Any, dtype[ScalarType_co]], *, constituents: list[str] | None = None, settings: FESSettings | None = None) → ndarray[Any, dtype[ScalarType_co]]#

Compute the long-period equilibrium ocean tides.

This calculates the geometric tidal potential (the “theoretical” tide) created by the attraction of the Moon and Sun over long periods (fortnightly, monthly, semi-annual, etc.). It sums the spectral lines from the Cartwright-Tayler-Edden tables.

Use this function if you need the purely astronomic long-period component independent of a specific tidal atlas.

Parameters:

date – Date of the tide calculation.
latitude – Latitude in degrees for the position at which the tide is calculated.
constituents – List of constituents to remove from the inferred table of long period waves. If None, all constituents are included in the calculation.
settings – Settings used for the tide calculation. See Settings for more details.

Returns:

The height of the long period wave constituents of the tidal spectrum (cm).

Example

>>> import pyfes
>>> import numpy as np
>>> dates = np.array(['2025-01-01'], dtype='datetime64[us]')
>>> lats = np.array([45.0])
>>> # Calculate full LP tide
>>> lp_tide = pyfes.evaluate_equilibrium_long_period(dates, lats)

References

Cartwright & Tayler, Geophys. J. R.A.S., 23, 45, 1971.
Cartwright & Edden, Geophys. J. R.A.S., 33, 253, 1973.
Tamura Y., Bull. d’information des marees terrestres, Vol. 99, 1987.

Prediction Functions

Contents

Prediction Functions#