Metadata-Version: 2.4
Name: pylot-db
Version: 2026.8.0
Summary: Read, match and deliver hydrodynamic databases. No BEM stack required.
Author-email: Ruben de Bruin / DAVE Lab <ruben@davelab.nl>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy
Requires-Dist: xarray
Requires-Dist: mafredo>=2026.7.1
Requires-Dist: h5netcdf
Dynamic: license-file

# pylot-db

Read side of the hydrodynamic database: open a library, rank stored floating
conditions against a vessel pose, and deliver a `mafredo.Hyddb1`.

Install this if you only *use* hydrodynamic databases. It does not require
capytaine, pymeshup or DAVE.

```bash
pip install pylot-db
```

## Getting a `mafredo` database out of a stored library

A library holds many solved conditions. You do not pick one by name — you say
how the vessel is floating, and the library ranks what it has against that.

```python
import numpy as np
from pylot_db import Library

with Library.open("tanker.pylot") as library:
    ranking = library.select(
        z_origin=-11.6,      # z of the vessel origin in diffraction space [m]
        heel=0.0,            # slope, not degrees
        trim=0.004,          # slope, not degrees
        water_depth=np.inf,
        forward_speed=0.0,
    )

    if not ranking:
        raise SystemExit(ranking.reason)  # why nothing matched, in words

    best = ranking.best
    if not best.usable:
        raise SystemExit(best.reason)     # matched, but cannot produce a database

    selection = library.deliver(best, rho=1.025)   # t/m3

hyddb = selection.hyddb                   # a mafredo.Hyddb1
point = selection.application_point       # (3,) vessel-local, where forces apply
```

`hyddb` is an ordinary `mafredo.Hyddb1`, so from here it is `mafredo`'s API:

```python
hyddb.amass(omega=0.5)          # (6, 6) added mass at 0.5 rad/s
hyddb.damping(omega=0.5)        # (6, 6) radiation damping
hyddb.force(omega=0.5, wave_direction=180.0)   # (6,) complex excitation
```

Four things worth knowing before you trust a number:

- **`heel` and `trim` are slopes**, everywhere in this API. Degrees appear in
  user interfaces and nowhere else.
- **`rho` is in t/m³** and is applied on delivery. Results are stored per unit
  density, so the library itself has no density to be wrong about.
- **The delivered database always covers the full 360°** of wave direction, even
  when only 0–180° was solved, and direction means *direction of travel*.
- **`application_point` is vessel-local** and is where the forces in `hyddb`
  apply. It is not the origin, and using the wrong one is a moment error that
  looks plausible.

`ranking.candidates` is every condition that survived the hard filters, best
first, and nothing is dropped for scoring badly. When the closest match is a
poor one, that is a fact about your library, and this package's position is that
you should be able to see it rather than have it silently handled.

## What is where

| | |
|---|---|
| [`docs/api.md`](docs/api.md) | The reference: every public name, with its units |
| [`docs/README.md`](docs/README.md) | Where the specification lives and why it is not here |

Building a library — meshing and solving — is
[`pylot-bem`](https://github.com/dave-open/pylot-bem), which depends on this
package and never the reverse. A file written there opens here on a machine with
no BEM solver installed, which is the whole point of the split.

## Licence

MIT. Copyright 2026 Ruben de Bruin / DAVE Lab.
