Open Work / Python package

rt4-roll-period

Ships sway side to side. Surveyors time how long one full sway takes to estimate how stable the ship is. The textbook formula they use has a small consistent error baked in. This library removes it.

GitHub · PyPI · CI · Back to r4rpi.org

Moored work vessel shown with roll-amplitude ghosting, stopwatch cue, and amber period-growth curve
Visual model: timed roll observation at finite amplitude, with period growth shown as a measurement curve.

Why it matters

A 275-year footnote, finally implemented

Bernoulli's amplitude correction has been in the textbooks since 1749. This package closes that gap.

Small-craft surveyors actually rely on roll-period

Workboats, fishing vessels, traditional sail. Roll-period is their working method, not a sanity check, and their GM margins are tight. The bias compounds.

A clean reference for simulation and historical re-analysis

Sub-µm round-trip against S4 benchmarks. Useful for validating stability simulation codes and for re-processing decades of inclining records to see real trends without the systematic bias on top.

The intuition

Think of a kid on a swing. A small push gives a short, fast swing. A big push gives a long, slow swing: the period grows with amplitude. Ships do the same.

The textbook formula uses the actually-measured period as if it were the small-amplitude limit. Because T_obs > T₀ in real measurements and T sits in the denominator, the textbook returns a GM smaller than the ship actually has. The bias is small (about 1.5% at 20° amplitude) but systematic, and it pushes toward over-conservative loading. Wall-sided hull effects can push the bias the other way; the demo below shows both regimes.

Try it

Pick a vessel preset or set the inputs directly. The chart shows how period changes with amplitude for the recovered GM.

Inputs

4.0 s
15 deg
0.797
9.0 m
Advanced: wall-sided correction

Wall-sided adds a finite-beam correction on top of the linear-GZ pendulum formula. Validated for φ ≤ 30° and BM/GM ≤ 4.

3.0 m
pip install rt4-roll-period · MIT licensed

Roll period vs amplitude

Flat dashed line is what the textbook formula assumes. The amber curve is the exact linear-GZ K(m) prediction. The white dot is your observation.

Small-angle (flat) Linear-GZ K(m) Wall-sided Observation (T_obs, φ_max)
Naive GM
0.000 m
(C·B/T_obs)²
Corrected GM
0.000 m
linear K(m)
Δ (true minus naive)
0.0 mm
0.00 %
Period stretch
1.0000 ×
T(φ_max) / T₀

The maths, for those who want it

Show the formulas

The roll equation for a ship with linear restoring moment is the classic nonlinear pendulum:

I · φ̈ + W · GM · sin(φ) = 0

The exact period at amplitude φ_max involves the complete elliptic integral of the first kind K(m) with m = sin²(φ_max/2):

T(φ_max) = T₀ · (2/π) · K(m), T₀ = C·B/√GM

This result is due to Bernoulli (1749) and is classical mechanics, not novel research. The factor (2/π)·K(m) ≥ 1 grows monotonically with amplitude: the finite-amplitude period is always longer than the small-amplitude limit T₀.

Inverting to recover GM from an observed period:

T₀_recovered = T_obs · π / (2·K(m)) GM_corrected = (C·B / T₀_recovered)² = GM_small_angle · (2·K(m)/π)²

Because (2K/π)² > 1 for φ_max > 0, the corrected GM is always larger than the small-angle estimate in the linear-GZ regime.

For wall-sided hulls (GZ shape with positive curvature at large angles), the period ratio gains a multiplicative shape factor H(φ_max, BM/GM) from numerical integration of the wall-sided righting arm:

T_wall(φ_max) = T₀ · (2/π) · K(m) · H(φ_max, BM/GM)

The H grid in the package is bilinear-interpolated on a 13×13 mesh validated against numerical ground truth for φ ≤ 30° and BM/GM ≤ 4. Outside that envelope, fall back to a measured GZ table.

What's in the package

  • recover_gm_rt4(T_obs, φ, C, B): exact linear-GZ K(m) inversion, closed form via SciPy special.ellipk.
  • recover_gm_wall_sided(T_obs, φ, C, B, BM): bilinear interpolation on the 13×13 validated grid H(φ, BM/GM); iteratively solves for GM since ρ = BM/GM depends on GM.
  • build_roll_period_report(...): auto-selects the highest-fidelity method available (GZ table → wall-sided → linear), returns per-method results and envelope warnings.
  • Also exposes GZ-table workflows (roll_period_gz_numerical, PCHIP interpolation, assess_gz_table_quality) for vessels with measured righting-arm curves.

Validation (from tests/test_core.py, S4 benchmark)

Linear-GZ K(m) periodMax formula error ~211 ppm across φ ∈ [5°, 80°]. Tested at 9 amplitudes vs SciPy reference.
RT4 GM round-tripMean GM recovery error < 1 µm across 120 random cases (vs 10+ mm for the small-angle method).
Wall-sided envelopeValidated for φ ≤ 30° and BM/GM ≤ 4. Max wall-sided period error ~21.5% at the extreme corner. Outside that, fall back to a real GZ table.

Open technical reference implementation. Not class-approved software, not a loading computer, not a statutory stability booklet, not a substitute for professional naval architecture review.