API

API#

Tide evaluation#

This function evaluates the tidal height at a given time and location. The location is given as a tuple of latitude and longitude in degrees. The time is given as numpy datetime64 array. The tidal height is returned as a numpy array of the same length as the time array. The tidal height is given in the same units as the tidal model.

pyfes.evaluate_tide(tidal_model: AbstractTidalModelComplex128 | AbstractTidalModelComplex64, date: VectorDateTime64, longitude: VectorFloat64, latitude: VectorFloat64, *, settings: Settings | None = None, num_threads: int = 0) → tuple[VectorFloat64, VectorFloat64, VectorInt8]#

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. See Settings for more details.
num_threads – Number of threads to use for the calculation. If 0, all available threads are used.

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)

A flag indicating if the tide is correctly estimated or not. Possible values are

1

The tide is correctly estimated.

2

The tide is extrapolated with the nearest mesh point.

4

The tide is extrapolated using a linear interpolation with two surrounding grid points.

8

The tide is extrapolated using a linear interpolation with three surrounding grid points.

16

The tide is undefined because the position is outside the domain of the tidal model or the numerical model is undefined for the requested spatial position.

Note

The flag value 2, 4 or 8 are only possible if the tidal model used is a Cartesian grid.

Configuration file#

This function provides a way to load the tidal model from a configuration file. For more information on the configuration file format, see the configuration file format section.

pyfes.config.load(path: str | PathLike) → dict[str, AbstractTidalModelComplex64 | AbstractTidalModelComplex128]#

Load a configuration file into memory.

Parameters:: path – Path to the configuration file to be loaded into memory
Returns:: A dictionary defining the configuration of the processing to be performed. The dictionary contains the tidal models to be used. The key is the type of the tidal model (e.g. tide, radial) and the value is the tidal model.

Configuration classes#

The configuration classes are used to store the configuration of the tidal model.

class pyfes.config.Common(latitude: str = 'lat', longitude: str = 'lon', tidal_type: str = 'tide', dynamic: list[str] = <factory>)#

Bases: object

Common configuration for all the objects.

dynamic: list[str]#: The list of the waves to be considered as part of the given altlas (evaluated dynamically from the model). The wave declared in this list will be considered as part of the model components and will be disabled from the admittance calculation and and in the long-period equilibrium wave calculation routine (lpe_minus_n_waves).

property dynamic_constituents: list[Constituent]#: Return the list of dynamic constituents.

latitude: str = 'lat'#: The name of the latitude variable.

longitude: str = 'lon'#: The name of the longitude variable.

tidal_type: str = 'tide'#: Tidal type.

class pyfes.config.Cartesian(latitude: str = 'lat', longitude: str = 'lon', tidal_type: str = 'tide', dynamic: list[str] = <factory>, amplitude: str = 'amplitude', paths: dict[str, str] = <factory>, phase: str = 'phase', epsilon: float = 1e-06)#

Bases: Common

Configuration for the Cartesian model.

amplitude: str = 'amplitude'#: The name of the amplitude variable.

epsilon: float = 1e-06#: The tolerance used to determine if the longitude axis is circular.

load() → AbstractTidalModelComplex64 | AbstractTidalModelComplex128#: Load the tidal model defined by the configuration.

paths: dict[str, str]#: The list of the NetCDF files to use.

phase: str = 'phase'#: The name of the phase variable.

class pyfes.config.LGP(latitude: str = 'lat', longitude: str = 'lon', tidal_type: str = 'tide', dynamic: list[str] = <factory>, amplitude: str = '{constituent}_amplitude', constituents: list[str] = <factory>, codes: str = 'codes', max_distance: float = 0.0, path: str = '', phase: str = '{constituent}_phase', triangle: str = 'triangle', type: str = 'lgp1')#

Bases: Common

Configuration for the LGP model.

amplitude: str = '{constituent}_amplitude'#: The pattern of the variable containing the amplitudes.

codes: str = 'codes'#: The name of the variable containing the LGP codes.

constituents: list[str]#: List of the tidal constituents to use.

load() → AbstractTidalModelComplex64 | AbstractTidalModelComplex128#: Load the tidal model defined by the configuration.

max_distance: float = 0.0#: Max distance allowed to extrapolate.

path: str = ''#: The path to the NetCDF file to use.

phase: str = '{constituent}_phase'#: The pattern of the variable containing the phases.

triangle: str = 'triangle'#: The name of the variable containing the vertices of the triangles.

type: str = 'lgp1'#: Type of LGP discretization to use. Allowed values are lgp1 and lgp2.

Settings#

The settings are used to control the behavior of the tidal evaluation.

class pyfes.Settings(*, astronomic_formulae: ~pyfes.core.Formulae = <Formulae.kSchuremanOrder1: 0>, time_tolerance: float = 0.0, excluded: list[str] | None = None)#

Bases: Settings

Tide prediction settings.

Parameters:

astronomic_formulae – Astronomic formulae used to evaluate the astronomic arguments for a given date. Default is pyfes.Formulae.kSchuremanOrder1.
time_tolerance – time_tolerance The time in seconds during which astronomical angles are considered constant. The default value is 0 seconds, indicating that astronomical angles do not remain constant with time.
excluded – The list of tidal constituents to be excluded from the model. Constituents included in this list will be processed through admittance calculations and in the long-period equilibrium wave calculation routine (lpe_minus_n_waves).

Note

The parameter time_tolerance allows for the adjustment of astronomical angle calculations. When its value is set to zero, the angles will be recalculated each time the date changes. Otherwise, they will be considered valid as long as the time difference between the last evaluation and the current date is within the specified tolerance.

In this case, it’s important to consider that the tidal evaluation may vary slightly, within an epsilon range, for the same period when calculated using a different number of threads. This is because the period will be divided differently based on the number of threads, resulting in variations in the way angles are updated depending on the number of threads used.

Astronomic angles#

class pyfes.astronomic_angle.AstronomicAngle(formulae: ~pyfes.core.Formulae = <Formulae.kSchuremanOrder1: 0>)#

Bases: AstronomicAngle

Initialize some astronomic data useful for nodal corrections.

In tidal work the only celestial bodies that need to be considered are the moon and sun. Although every other celestial body whose gravitational influence reaches the Earth create a theoretical tide producing force, the greater distance or smaller size of such body renders negligible any effect of this force upon the tides of the Earth. In deriving mathematical expressions for the tide-producing forces of the moon and sun, the principal factors to be taken into consideration are the rotation of the earth, the volution of the moon around the earth, the revolution of the earth around the sun, the inclination of the moon’s orbit to the earth’s equator, and the obliquity of the ecliptic.

Parameters:: formulae – Astronomic formulae used to evaluate the astronomic arguments for a given date. Default is pyfes.Formulae.kSchuremanOrder1.

update(date: datetime | None = None) → None#

Update the astronomic angles.

Parameters:: date – Date for which the astronomic angles are computed. If None, the current date is used.

Tidal constituents#

pyfes.constituents.known() → list[str]#

Return the list of known constituents by this library.

Returns:: List of constituent names.

pyfes.constituents.name(constituent: pyfes.core.Constituent) → str#

Return the name of a constituent.

Parameters:: constituent – Constituent enum value.
Returns:: Constituent name.

pyfes.constituents.parse(name: str) → pyfes.core.Constituent#

Parse a constituent name.

Parameters:: name – Constituent name. Search is not case sensitive. So “M1” and “m1” are equivalent.
Returns:: Constituent enum value.

Constituents Analysis#

class pyfes.wave_table.WaveTable#

Bases: WaveTable

Properties of tidal constituents.

compute_nodal_modulations(dates: list[datetime.datetime] | VectorDateTime64, leap_seconds: VectorUInt16, formulae: Formulae = <Formulae.kSchuremanOrder1: 0>) → tuple[VectorFloat64, VectorFloat64]#

Compute nodal modulations for amplitude and phase.

Parameters:

dates – Dates for which the nodal modulations are computed.
leap_seconds – Leap seconds for the dates provided.
formulae – Astronomic formulae used to evaluate the astronomic arguments for a given date. Default is pyfes.Formulae.kSchuremanOrder1.

Returns:

The nodal modulations for amplitude and phase.

freq() → VectorFloat64#: Gets the waves frequencies in radians per seconds.

static harmonic_analysis(h: VectorFloat64, f: VectorFloat64, vu: VectorFloat64) → VectorComplex128#

Harmonic Analysis. 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) \times 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,

\(w_{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 Shureman in 1958, and many non-linear waves. Tidal constants and astronomical arguments are now derived from this software, incorporating legacy data from FES2014. A comprehensive definition of waves can also be found in Shureman (1958). This spectrum is the most commonly used for harmonic analysis due to 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.

class pyfes.wave_table.WaveDict#

Bases: WaveTable

Manages the tidal wave table as a dictionary.

freq() → dict[str, float]#: Gets the waves frequencies in radians per seconds.

harmonic_analysis(h: VectorFloat64, f: VectorFloat64, vu: VectorFloat64) → dict[str, VectorComplex128]#

Harmonic Analysis.

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:

A mapping between the wave name and its complex number representing it.

Leap Seconds#

pyfes.get_leap_seconds(utc: VectorDateTime64 | datetime.datetime | numpy.datetime64, sorter: VectorInt64 | None = None) → VectorUInt16#

Return the UTC-TAI difference for the given UTC times.

Parameters:

utc – The UTC times.
sorter – The indices which would sort the utc array. If not given, the utc array is sorted internally.

Returns:

The UTC-TAI difference for the given UTC times.

Type hints#

Type aliases.

pyfes.typing.VectorInt8#: A vector of numpy.int8.

pyfes.typing.VectorUInt8#: A vector of numpy.uint8.

pyfes.typing.VectorUInt16#: A vector of numpy.uint16.

pyfes.typing.VectorInt64#: A vector of numpy.int64.

pyfes.typing.VectorFloat64#: A vector of numpy.float64.

pyfes.typing.VectorComplex64#: A vector of numpy.complex64.

pyfes.typing.VectorComplex128#: A vector of numpy.complex128.

pyfes.typing.VectorDateTime64#: A vector of numpy.datetime64.

pyfes.typing.MatrixInt32#: A matrix of numpy.int32.

pyfes.typing.MatrixFloat64#: A matrix of numpy.float64.

pyfes.typing.NDArrayStructured#: A numpy array whose data type is a composition of simpler data types organised as a sequence of named fields.

1	The tide is correctly estimated.
2	The tide is extrapolated with the nearest mesh point.
4	The tide is extrapolated using a linear interpolation with two surrounding grid points.
8	The tide is extrapolated using a linear interpolation with three surrounding grid points.
16	The tide is undefined because the position is outside the domain of the tidal model or the numerical model is undefined for the requested spatial position.

API

Contents

API#

Tide evaluation#

Configuration file#

Configuration classes#

Settings#

Astronomic angles#

Tidal constituents#

Constituents Analysis#

Leap Seconds#

Type hints#