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.

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.

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:

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

Building a library — meshing and solving — is 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.