Skip to main content

build platforms latest-release-date license download Binder

PyFES - Ocean Tide Prediction Software

PyFES is a Python library for predicting ocean tides anywhere on Earth. Using global tidal atlases such as FES2022 and GOT5.6, it evaluates tidal heights and currents through harmonic analysis -- the same scientific method developed by Lord Kelvin over 150 years ago.

Features

  • Tidal height prediction at any coastal or oceanic location from global atlases (FES2022, GOT5.6, etc.)
  • Tidal current computation for marine navigation and oceanographic studies
  • Harmonic analysis to extract tidal constituents from observed sea-level time series
  • Prediction from known constituents without requiring a tidal atlas
  • Long-period equilibrium tide computation from Cartwright-Tayler-Edden spectral tables
  • Multiple tidal model formats: regular Cartesian grids and unstructured finite-element meshes (LGP1/LGP2)
  • Dual prediction engines supporting both Darwin (FES) and Doodson (GOT) harmonic notation systems
  • Configurable inference modes (zero, linear, spline, Fourier) for minor constituent estimation

Try It -- No Installation Required

Launch interactive notebooks in Binder to explore examples including tidal prediction, harmonic analysis, interpolation techniques, and engine comparison. Everything runs in the cloud.

Installation

From conda-forge

conda install -c conda-forge pyfes

From source

PyFES requires a C++14 compiler and CMake:

git clone https://github.com/CNES/aviso-fes.git
cd aviso-fes
pip install -e .

Quick Start

Predicting tides from a tidal atlas

Create a YAML configuration file describing your tidal model:

engine: darwin
tide:
  cartesian:
    paths:
      M2: ${FES_DATA}/M2_tide.nc
      S2: ${FES_DATA}/S2_tide.nc
      K1: ${FES_DATA}/K1_tide.nc
      O1: ${FES_DATA}/O1_tide.nc

Then load and predict:

import numpy as np
import pyfes

config = pyfes.config.load('ocean_tide.yaml')

dates = np.arange(
    np.datetime64('2024-01-01'),
    np.datetime64('2024-01-02'),
    np.timedelta64(1, 'h'),
)
lons = np.full(dates.shape, -7.688)
lats = np.full(dates.shape, 59.195)

tide, lp, flags = pyfes.evaluate_tide(
    config.models['tide'],
    dates,
    lons,
    lats,
    settings=config.settings,
)
total_tide = tide + lp  # in the same units as the tidal atlas

Predicting from known constituents

constituents = {
    'M2': (205.1, 109.0),  # (amplitude_cm, phase_deg)
    'S2': (74.9, 148.3),
    'K1': (6.4, 75.1),
    'O1': (6.6, 327.9),
}

tide, lp = pyfes.evaluate_tide_from_constituents(
    constituents,
    dates,
    latitude=48.38,
)

Prediction Engines

PyFES provides two prediction engines to support different tidal atlas formats:

Feature FES/Darwin PERTH/Doodson
YAML key engine: darwin engine: perth
Notation Darwin notation Doodson numbers
Constituents 105 80
Nodal corrections Individual Schureman factors Individual (group modulations optional)
Default inference SPLINE LINEAR
Compatible atlases FES2014, FES2022 GOT4.10, GOT5.5, GOT5.6

Both engines share the same high-level API and support the same set of configurable inference types. The choice depends on your tidal atlas format: FES atlases use the Darwin engine, while GOT atlases use the PERTH engine.

See the Prediction Engines documentation for a detailed comparison and usage guidance.

Tidal Constituents

PyFES provides two catalogues of tidal constituents, one for each prediction engine. Every constituent is characterised by its name, angular speed, and XDO notation encoding.

  • Darwin catalogue -- 105 constituents used by the FES/Darwin engine. See the full list.
  • Doodson catalogue -- 80 constituents used by the PERTH/Doodson engine. See the full list.

About FES2022

This package is the fully revised version of the FES2022 distribution, including both the PyFES prediction software and access to the FES2022 tides databases. FES2022 represents the state-of-the-art in global tidal modeling, with improved accuracy especially for satellite altimetry applications.

A full technical description is available in the FES2022 handbook and the scientific paper (Lyard et al. 2024).

Operational Use

PyFES (release 2026.3.1) is the tidal correction component embedded in the SWOT KaRIn ground segment for Level-2 product generation. It is also being extended to integrate Richard Ray's GOT model (via the Perth engine) for upcoming SWOT product versions, so that the same code path produces both FES- and GOT-based corrections in the operational pipeline.

Documentation

The complete documentation is available on GitHub Pages, including:

C++ API

This library provides a C++ API for high-performance tide prediction. The C++ part of the library is documented using Doxygen. You can generate the documentation by running doxygen in the docs directory after installing Doxygen.

Legacy C Version

For users requiring the original C implementation, the legacy version remains available on its own branch. The reference version used to compute the FES2022b tidal solution is 2.9.7.

Note: The legacy C version is archived and will not receive further updates. For new projects, we recommend using the current Python version or the C++ library.
Please note: The C++ library does not include a reader for the tidal databases -- you will need to implement your own reader to access them.

Credits

When using FES2022, please mention: FES2022 was produced by LEGOS, NOVELTIS and CLS Ocean and Climate Division; the project was funded by CNES. It is distributed by AVISO, with support from CNES (http://www.aviso.altimetry.fr/)

The PERTH engine is a C++ port of the original Fortran PERTH5 library by Richard Ray (NASA GSFC). The integration into pyfes was developed under CNES funding to support tidal correction for SWOT (Surface Water and Ocean Topography) altimetry products.

PyFES focuses on high-performance tidal prediction from FES atlases (Darwin engine) and GOT atlases (Perth engine), including loaders for FES2022's unstructured native grid. For a broader pure-Python tide-modeling toolbox covering OTIS, IERS pole tides, ocean and solid-Earth tides, and tide-generating force computations -- complementary to the FES / GOT scope covered here -- see pyTMD by Tyler Sutterley (NASA GSFC).

References

  • Lyard, F., Carrere, L., Fouchet, E., Cancet, M., Greenberg, D., Dibarboure, G., and Picot, N.: FES2022 a step towards a SWOT-compliant tidal correction, Submitted to J. Geophy. Res., in review, 2025

  • Lyard, F. H., Allain, D. J., Cancet, M., Carrere, L., and Picot, N.: FES2014 global ocean tide atlas: design and performance, Ocean Sci., 17, 615-649, https://doi.org/10.5194/os-17-615-2021, 2021.

  • Carrere L., F. Lyard, M. Cancet, A. Guillot, N. Picot: FES 2014, a new tidal model - Validation results and perspectives for improvements, presentation to ESA Living Planet Conference, Prague 2016.

Contact

Questions, suggestions, or need support? Reach out to the AVISO team: aviso@altimetry.fr

Metadata

Release files for pyfes 2026.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyfes 2026.10.0
File Size Uploaded Provenance Actions
pyfes-2026.10.0.tar.gz 1.4 MB With provenance Details for pyfes-2026.10.0.tar.gz

Release files / pyfes-2026.10.0.tar.gz

Download URL pyfes-2026.10.0.tar.gz
Size 1.4 MB
Tags Source
SHA-256 checksum
How to use checksums
8b72970f2b9e16cd4e0d504279b3848b17d85e532afeecf9d5f0574185b9337c
BLAKE2b-256 checksum
How to use checksums
5f34516482ddbb43e5ad2351ba22b09097ef5ddd28cc1a67892a02805b79c221
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.

Transparency log

Security for pyfes 2026.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

1 file in this release has been uploaded with provenance metadata.

Attestation for pyfes-2026.10.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page