Wave System

Wave System#

The wave system is composed of two main objects:

  • WaveInterface represents a single tidal constituent, giving access to its Doodson number, Darwin name, angular speed, type, and the current nodal factors f and u.

  • WaveTableInterface holds the complete catalogue of constituents for a given engine and provides bulk operations: computing nodal corrections, running harmonic analysis, and selecting waves that meet Rayleigh separation criteria.

A wave table is created with pyfes.wave_table_factory():

wt = pyfes.wave_table_factory(pyfes.EngineType.DARWIN)

WaveInterface#

class pyfes.WaveInterface#

Tidal wave interface.

compute_nodal_corrections(self: pyfes.core.WaveInterface, angles: pyfes.core.AstronomicAngle, group_modulations: bool = False) → None#

Compute the nodal corrections for the wave.

Parameters:

  • angles – Astronomical angles used to compute nodal corrections.

  • group_modulations – If true, applies group modulations to nodal corrections.

property corrected_tide#

The tide value after applying the nodal corrections.

doodson_numbers(self: pyfes.core.WaveInterface) → Annotated[numpy.typing.NDArray[numpy.int8], '[7, 1]']#

Get the Doodson number of the wave.

property f#

The nodal correction for amplitude.

frequency(self: pyfes.core.WaveInterface, unit: pyfes.core.FrequencyUnit = <FrequencyUnit.RADIAN_PER_HOUR: 0>) → float#

Get the frequency of the tidal wave.

Parameters:

unit – The frequency unit. Default is radians per hour.

Returns:

The frequency of the tidal wave.

property is_modeled#

Whether the tide is provided by the model.

property latex_name#

The LaTeX name of the tidal wave.

property name#

The name of the tidal wave.

property period#

The period of the wave in hours.

set_nodal_corrections(self: pyfes.core.WaveInterface, f: SupportsFloat, u: SupportsFloat, v: SupportsFloat, unit: pyfes.core.AngleUnit) → None#

Set the nodal corrections directly.

Parameters:

  • f – Nodal correction for amplitude.

  • u – Nodal correction for phase.

  • v – Greenwich argument.

  • unit – The angular unit of the nodal corrections.

property tide#

The tide value.

property type#

The type of tidal wave.

property u#

The nodal correction for phase, in radians.

property v#

The Greenwich argument, in radians.

property vu#

The sum of the Greenwich argument and the nodal phase correction, in radians.

xdo_alphabetical(self: pyfes.core.WaveInterface) → str#

Get the XDO alphabetical representation of the wave.

xdo_numerical(self: pyfes.core.WaveInterface) → str#

Get the XDO numerical representation of the wave.

WaveTableInterface#

class pyfes.WaveTableInterface#

Tidal wave table interface.

compute_nodal_corrections(self: pyfes.core.WaveTableInterface, angles: pyfes.core.AstronomicAngle, group_modulations: bool = False) → None#

Compute the nodal corrections for all constituents in the table.

Parameters:

  • angles – Astronomical angles used to compute nodal corrections.

  • group_modulations – If true, applies group modulations to nodal corrections.

compute_nodal_modulations(self: pyfes.core.WaveTableInterface, epoch: numpy.ndarray, formulae: pyfes.core.Formulae = <Formulae.SCHUREMAN_ORDER_1: 0>, group_modulations: bool = False) → tuple[Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]'], Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]']]#

Compute nodal modulations for amplitude and phase.

Parameters:

  • epoch – Desired UTC time as a numpy array of datetime64.

  • formulae – Formulae used to compute the astronomic angles.

  • group_modulations – If true, applies group modulations to nodal corrections.

Returns:

A tuple containing the nodal correction for amplitude and the sum of the Greenwich argument and the nodal phase correction.

property constituents#

The list of constituent names in the table.

generate_markdown_table(self: pyfes.core.WaveTableInterface, ascending: bool = True) → str#

Generate a markdown table summarizing the constituents handled by the wave table.

Parameters:

ascending – If true (default), sort the table by ascending frequency; otherwise, sort by descending frequency.

Returns:

A string containing the markdown table.

static harmonic_analysis(h: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], f: Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]'], vu: Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]']) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']#

Harmonic analysis of the tide.

The harmonic analysis method consists in expressing the ocean tidal variations as a sum of independent constituents accordingly to the tidal potential spectrum. Then the sea surface elevation at a point \((x, y)\) and time \((t)\) can be expressed as a linear sum as follow:

\[S_{ap} = S_{0}(x, y) + \sum_{k=0}^n f_{k}(t)S_{k}(x, y) imes \cos [\omega_{k}t + v_{k}(t) + u_{k}(t) - G_{k}(x,y)]\]
where:

  • \((n)\) is the number of constituents,

  • \(S_{0}(x, y)\) is the mean sea level,

  • \(S_{k}(x, y)\) is the amplitude of the constituent of index \((k)\),

  • \(G_{k}(x, y)\) is the phase lag relative to Greenwich time,

  • \(\omega_{k}\) is the angular frequency of the constituent of index \((k)\),

  • \(v_{k}\) is the astronomical argument at time \((t)\),

  • \(f_{k}(t)\) is the nodal correction coefficient applied to the amplitude of the constituent of index \((k)\),

  • \(u_{k}(t)\) is the nodal correction coefficient applied to the phase of the constituent of index \((k)\).

The a priori analysis spectrum includes the most important astronomical constituents in the Darwin development, completed by Schureman in 1958, and many non-linear waves. The definition of tidal constants and astronomical arguments is taken from FES2014 tidal prediction software and a complete definition of waves is also available in Schureman (1958). This spectrum is the most commonly used for harmonic analysis due the simplification given by the nodal correction concept (\((f)\) and \((u)\) coefficients above) which allows dealing with slow motions of the lunar ascending node and reducing the number of constituents in the tidal spectrum. More details about this harmonic analysis method can be found in Ponchaut et al. 1999.

Parameters:

  • h – Sea level.

  • f – Nodal correction coefficient applied to the amplitude of the constituents analyzed.

  • vu – Astronomical argument at time \((t)\) + the nodal correction coefficient applied to the phase of the constituents analyzed.

Returns:

The complex number representing the different reconstructed waves.

select_waves_for_analysis(self: pyfes.core.WaveTableInterface, duration: SupportsFloat, rayleigh_criterion: SupportsFloat = 1.0) → list[str]#

Select tidal waves that can be resolved from a record of a given duration based on the Rayleigh criterion.

Converts the record duration to hours, computes the minimum angular separation \(2\pi C_R / T\) then iterates over the wave table, rejecting waves too close to \(DC\) or closer than the Rayleigh limit to any already - selected wave.

Parameters:

  • duration – Duration of the time series analyzed in seconds.

  • rayleigh_criterion – The Rayleigh criterion factor (C_R) to determine the minimum frequency. Default is 1.0, which corresponds to the classical Rayleigh criterion.

Returns:

List of selected tidal wave names.

set_modeled_constituents(self: pyfes.core.WaveTableInterface, names: collections.abc.Sequence[str]) → None#

Set the list of constituents that are modeled by the wave table.

Parameters:

names – List of constituent names.

set_tide(self: pyfes.core.WaveTableInterface, name: str, value: complex) → None#

Set the tide of a constituent.

Parameters:

  • name – The constituent name.

  • value – The tide value.

sort_by_frequency(self: pyfes.core.WaveTableInterface, ascending: bool = True) → list[str]#

Returns the constituents sorted by frequency.

Parameters:

ascending – If True (default), sort by ascending frequency; otherwise, sort by descending frequency.

Returns:

List of constituent names sorted by frequency.

tide_from_mapping(self: pyfes.core.WaveTableInterface, epoch: object, wave: typing.Annotated[numpy.typing.NDArray[numpy.complex128], "[m, n]"], formulae: pyfes.core.Formulae = <Formulae.SCHUREMAN_ORDER_1: 0>, group_modulations: bool = False, num_threads: typing.SupportsInt = 0) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]']#

Calculate the tide for a given date from a grid describing the properties of tidal waves over an area.

Parameters:

  • epoch – Desired UTC time as a datetime.datetime.

  • wave – Tidal wave properties computed by an harmonic analysis.

  • formulae – Formulae used to compute the astronomic angles.

  • group_modulations – If true, applies group modulations to nodal corrections.

  • num_threads – Number of threads to use for the computation. If 0, the number of threads is automatically determined.

Returns:

The tide at the given time for each grid point.

tide_from_tide_series(self: pyfes.core.WaveTableInterface, epoch: numpy.ndarray, wave: typing.Annotated[numpy.typing.NDArray[numpy.complex128], "[m, 1]"], formulae: pyfes.core.Formulae = <Formulae.SCHUREMAN_ORDER_1: 0>, group_modulations: bool = False) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']#

Calculate the tide of a given time series.

Parameters:

  • epoch – Desired UTC time as a numpy array of datetime64.

  • wave – Tidal wave properties computed by an harmonic analysis.

  • formulae – Formulae used to compute the astronomic angles.

  • group_modulations – If true, applies group modulations to nodal corrections.

Returns:

The tide at the given times.

waves(self: pyfes.core.WaveTableInterface) → list#

Return a list of waves in the table.

Factory#

pyfes.wave_table_factory(engine_type: pyfes.core.EngineType = <EngineType.DARWIN: 0>, constituents: collections.abc.Sequence[str] | None = None) → pyfes.core.WaveTableInterface#

Factory function to create a wave table based on the specified engine type.

Parameters:

  • engine_type – The engine type for the tidal constituent notation system.

  • constituents – Optional list of constituent names to include in the wave table. If not provided, all known constituents for the engine type are included.

Returns:

A wave table instance.

Contents