Metadata-Version: 2.4
Name: tide-prediction
Version: 1.2.1
Requires-Dist: pytest ; extra == 'dev'
Provides-Extra: dev
Summary: Tide prediction library
Author: Frédéric Pidancier
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://gitlab.com/pidancier-projects/plong-e/tide
Project-URL: Source, https://gitlab.com/pidancier-projects/plong-e/tide

# 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](https://maree.shom.fr/). 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

```bash
pip install tide-prediction
```

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

## Quick start

```python
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.

```python
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

```python
# 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 5 yr |
| `FR-PORT-TUDY` | Port Tudy (Île de Groix) | REFMAR 5 yr |
| `FR-CONCARNEAU` | Concarneau | REFMAR 5 yr |
| `FR-SAINT-NAZAIRE` | Saint-Nazaire | REFMAR 5 yr |
| `FR-LA-ROCHELLE` | La Rochelle — La Pallice | REFMAR 5 yr |
| `FR-ROSCOFF` | Roscoff | REFMAR 5 yr |
| `FR-SAINT-MALO` | Saint-Malo | REFMAR 5 yr |
| `FR-CHERBOURG` | Cherbourg | REFMAR 5 yr |
| `FR-LE-HAVRE` | Le Havre | REFMAR 5 yr |
| `FR-DIEPPE` | Dieppe | REFMAR 5 yr |
| `FR-DUNKERQUE` | Dunkerque | REFMAR 5 yr |
| `FR-BAYONNE` | Boucau-Bayonne | REFMAR 5 yr |
| `FR-ARCACHON` | Arcachon | REFMAR 5 yr |
| `FR-PORT-NAVALO` | Port-Navalo (Golfe du Morbihan) | SHOM SPM 3 yr |
| `FR-ARRADON` | Arradon (Golfe du Morbihan) | SHOM SPM 3 yr |
| `FR-AURAY` | Auray — Saint-Goustan | SHOM SPM 3 yr |
| `FR-ETEL` | Entrée rivière d'Étel | SHOM SPM 3 yr |

## 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.

