tide-prediction 0.1.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.

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
FR-BREST	Brest
FR-CHERBOURG	Cherbourg
FR-SAINT-MALO	Saint-Malo
FR-BORDEAUX	Bordeaux (Port de la Lune)
FR-PORT-TUDY	Port Tudy (Île de Groix)
FR-PORT-NAVALO	Port-Navalo (Golfe du Morbihan)
FR-ARRADON	Arradon (Golfe du Morbihan)
FR-AURAY	Auray (rivière d'Auray)
FR-ETEL	Étel
GB-PORTSMOUTH	Portsmouth

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.