Metadata-Version: 2.4
Name: tide-prediction
Version: 0.1.0
Requires-Dist: pytest ; extra == 'dev'
Provides-Extra: dev
Summary: Tide prediction library
Author: Gael Systems
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.

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

