Prediction Engines

Prediction Engines#

PyFES implements two prediction engines that differ in their constituent notation and approach to nodal corrections. Both engines implement the same fundamental harmonic method and share the same inference modes, astronomic formulae, and prediction functions.

The choice of engine is determined by the tidal atlas family (FES or GOT).

Engine Comparison#

Feature

FES/Darwin

PERTH/Doodson

YAML key

engine: darwin

engine: perth

Settings class

FESSettings

PerthSettings

Notation

Darwin notation

Doodson numbers

Constituents

105

80

Nodal corrections

Individual Schureman factors

Individual (group modulations optional)

Default inference

SPLINE

LINEAR

Default formulae

SCHUREMAN_ORDER_1

IERS

Long-period equilibrium tide

Computed by default

Not computed by default

Compatible atlases

FES2014, FES2022

GOT4.10, GOT5.5, GOT5.6

FES/Darwin Engine#

The Darwin engine uses the harmonic notation system developed by Sir George Darwin and refined by Paul Schureman. Each constituent is identified by a traditional name (e.g., \(M_2\), \(S_2\), \(K_1\)) derived from the underlying astronomical forcing.

Constituent Notation#

In Darwin notation, each constituent’s tidal argument is expressed as a linear combination of the fundamental variables:

\[V_k = n_1 \tau + n_2 s + n_3 h + n_4 p + n_5 N' + n_6 p_1\]

where the integer coefficients \(n_i\) are specific to each constituent. For the full derivation, see Harmonic Development and the Doodson Classification.

Nodal Corrections#

The Darwin engine applies individual Schureman nodal corrections to each constituent. The amplitude factor \(f_k\) and phase correction \(u_k\) are computed from the auxiliary astronomical angles (obliquity \(I\), longitude of the lunar node \(N\), etc.) using Schureman’s formulas 73–80 and 215–235. For example:

\[f(M_2) = \frac{\cos^4(I/2)}{0.9154}, \qquad u(M_2) = 2\xi - 2\nu\]

For the complete set of nodal correction formulas, see Nodal Corrections: Amplitude and Phase Modulations.

Default Settings#

settings = pyfes.FESSettings()
# Defaults:
#   engine_type = DARWIN
#   inference_type = SPLINE
#   astronomic_formulae = SCHUREMAN_ORDER_1
#   group_modulations = False
#   compute_long_period_equilibrium = True

Constituent List#

The Darwin engine supports 105 tidal constituents. See DARWIN for the complete list with frequencies and XDO notation.

PERTH/Doodson Engine#

The PERTH engine uses the systematic Doodson number classification developed by Arthur Doodson in 1921. It was implemented by Dr. Richard Ray at NASA Goddard Space Flight Center for the GOT (Goddard Ocean Tide) model series. The engine bundled with PyFES is a C++ port of the original Fortran PERTH5 library by Richard Ray; the integration was developed under CNES funding to support tidal correction for SWOT (Surface Water and Ocean Topography) altimetry products.

Doodson Number Classification#

Each constituent is assigned a six-digit number encoding its fundamental variables coefficients with an offset of +5:

\[\text{Doodson number} = (n_1)(n_2+5)(n_3+5).(n_4+5)(n_5+5)(n_6+5)\]

For example, \(M_2\) has coefficients (2, 0, 0, 0, 0, 0) and is encoded as 255.555. See Harmonic Development and the Doodson Classification for the derivation and worked examples.

The XDO notation provides an equivalent alphabetical encoding used internally by PyFES.

Group Modulations#

The PERTH engine supports group modulations, an alternative to individual nodal corrections. In this approach, closely related constituents within a tidal group are modulated together rather than individually. This can be enabled or disabled through the settings:

settings = pyfes.PerthSettings().with_group_modulations(True)

When group modulations are disabled, the engine applies R. Ray’s individual nodal corrections, which differ slightly from the Schureman formulas of the Darwin engine (see Nodal Corrections: Amplitude and Phase Modulations).

Default Settings#

settings = pyfes.PerthSettings()
# Defaults:
#   engine_type = DOODSON
#   inference_type = LINEAR
#   astronomic_formulae = IERS
#   group_modulations = False
#   compute_long_period_equilibrium = False

Constituent List#

The PERTH/Doodson engine supports 80 tidal constituents. See DOODSON for the complete list with frequencies and XDO notation.

Choosing an Engine#

The engine choice depends on your tidal atlas:

  • FES atlases (FES2014, FES2022): use engine: darwin.

  • GOT atlases (GOT4.10, GOT5.5, GOT5.6): use engine: perth.

The engine key of the YAML file (default darwin) selects the settings object returned by pyfes.config.load(): FESSettings for darwin and PerthSettings for perth. The engine actually used by evaluate_tide() is the one carried by its settings argument, so always pass settings=config.settings (or settings derived from it). If settings is omitted, the Darwin engine with the FES defaults is used, whatever the YAML file says.

In the API, the two engines are identified by EngineType: DARWIN (engine: darwin, FESSettings) and DOODSON (engine: perth, PerthSettings). All other settings (inference mode, formulae, parallelism) are independent of the engine choice and can be configured freely with either engine. See Inference Modes and Astronomic Formulae.