tide-prediction 1.0.0

Tide prediction library

tide-prediction

Tidal prediction library for French Atlantic and English Channel ports. Computes high/low water times, heights, tidal coefficients, and full height curves — all from a fast Rust core exposed via Python bindings.

Disclaimer

This library is provided AS IS, without warranty of any kind. It is not intended for navigation, maritime safety, or any use where inaccurate predictions could cause harm to persons, property, or the environment. Predictions are produced from a simplified 13-constituent harmonic model and do not account for meteorological effects (storm surge, wind, barometric pressure) or exceptional astronomical events. Typical residual RMSE is 0.10–0.25 m; local error may be larger.

For official tidal predictions in France, refer to the SHOM. The author disclaims all liability arising from the use of this software. By using this library you do so at your own risk and sole responsibility.

Installation

pip install tide-prediction

The package is imported as import tide (not tide_prediction).

Quick start

import tide

# Predict a full day
pred = tide.predict_day("FR-BREST", "2024-06-15")

from datetime import datetime, timezone

for e in pred.extremes:
    kind = "HW" if e.is_high_water else "LW"
    coef = f"  coef={e.coefficient}" if e.coefficient else ""
    dt = datetime.fromtimestamp(e.time, tz=timezone.utc).strftime("%H:%M")
    print(f"{kind}  {dt}  {e.height:.2f} m{coef}")

# HW  00:26  4.83 m  coef=39
# LW  06:41  2.40 m
# HW  13:07  4.80 m  coef=42
# LW  19:07  2.61 m

API

tide.predict_day(port_id, date) → DayPrediction

Returns high/low water extremes and a 10-minute height curve for a single day.

• port_id — port identifier (e.g. "FR-BREST")
• date — date string "YYYY-MM-DD" (UTC)

tide.predict_range(port_id, from_date, to_date) → list[DayPrediction]

Same as predict_day over a date range (inclusive).

tide.height_at(port_id, timestamp) → float

Instantaneous water height in metres at a given Unix UTC timestamp.

from datetime import datetime, timezone

ts = int(datetime(2024, 6, 15, 12, 0, tzinfo=timezone.utc).timestamp())
h = tide.height_at("FR-BREST", ts)
print(f"{h:.3f} m")  # 4.607 m

Port discovery

# List all available ports
ports = tide.list_ports()

# Search by name
results = tide.search_ports("saint")

# Get a specific port
port = tide.get_port("FR-BREST")
print(port.name, port.latitude, port.longitude)

Data model

DayPrediction
├── port_id        str
├── date           str          "YYYY-MM-DD"
├── extremes       list[TidalExtreme]
│   ├── time           int      Unix timestamp UTC
│   ├── height         float    metres
│   ├── is_high_water  bool
│   └── coefficient    int|None 20–120, Atlantic/Channel HW only
└── heights        list[HeightPoint]
    ├── timestamp   int          every 10 minutes
    └── height      float        metres

Available ports

ID	Port	Calibration
FR-BREST	Brest (coefficient reference)	REFMAR
FR-PORT-TUDY	Port Tudy (Île de Groix)	REFMAR
FR-CONCARNEAU	Concarneau	REFMAR
FR-SAINT-NAZAIRE	Saint-Nazaire	REFMAR
FR-LA-ROCHELLE	La Rochelle — La Pallice	REFMAR
FR-ROSCOFF	Roscoff	REFMAR
FR-SAINT-MALO	Saint-Malo	REFMAR
FR-CHERBOURG	Cherbourg	REFMAR
FR-LE-HAVRE	Le Havre	REFMAR
FR-DIEPPE	Dieppe	REFMAR
FR-DUNKERQUE	Dunkerque	REFMAR
FR-BAYONNE	Boucau-Bayonne	REFMAR
FR-ARCACHON	Arcachon	REFMAR
FR-PORT-NAVALO	Port-Navalo (Golfe du Morbihan)	SHOM SPM
FR-ARRADON	Arradon (Golfe du Morbihan)	SHOM SPM
FR-AURAY	Auray — Saint-Goustan	SHOM SPM
FR-ETEL	Entrée rivière d'Étel	SHOM SPM

Tidal coefficients

Coefficients (20–120) are computed for Atlantic and English Channel high waters relative to the Brest reference tidal range, following the French SHOM convention. They are only available for high water (is_high_water = True) at ports on the Atlantic/Channel coast.

Requirements

• Python ≥ 3.8
• Currently tested on Linux x86-64 (manylinux). macOS and Windows wheels may be added in future releases.