rt4-roll-period

Amplitude-aware roll-period GM correction and reporting for ship stability workflows. The package corrects the systematic amplitude bias of the standard small-angle approximation (which under-estimates GM for finite-amplitude rolls in the linear-GZ regime) and selects the richest available method from vessel GZ tables, validated wall-sided correction, or a linear-GZ fallback.

Publication Status

This repository is being prepared as an open technical reference implementation. It is not class-approved software, a loading computer, a substitute for a statutory stability booklet, or a replacement for professional naval architecture review.

The Problem

During a ship inclining experiment, the standard formula:

GM = (C * B / T_obs)^2

implicitly assumes the roll period is independent of amplitude, which is only true in the small-angle limit. The observed period T_obs is longer than the small-amplitude natural period T0 (finite-amplitude pendulum effect), so plugging T_obs into the formula systematically under-estimates GM in the linear-GZ regime. At 20-degree amplitude this is ~1.54%; the practitioner reads a GM smaller than the ship actually has, which is conservative on stability margin but pessimistic on permitted loading. Wall-sided hull effects can shift the bias in the opposite direction; both corrections are exposed by the library.

The Solution

The exact formula (classical Bernoulli/Euler mechanics, 1749):

T = T0 * (2/pi) * K(sin^2(phi_max/2))

where K(m) is the complete elliptic integral of the first kind. This corrects the amplitude dependence exactly for the linear GZ model.

Result: RT4 mean GM error = 0.000 mm vs small-angle's 20.72 mm at 20-degree amplitude.

Install

pip install rt4-roll-period

Quick Start

from rt4_roll_period import (
    roll_period_exact,
    recover_gm_rt4,
    recover_gm_wall_sided,
    gm_correction_factor,
    load_gz_table_csv,
    assess_gz_table_quality,
    build_roll_period_report,
    roll_period_gz_table_ratio,
)

# Exact roll period at 20-degree amplitude
T0 = 15.0  # small-angle period (seconds)
T_exact = roll_period_exact(phi_max_deg=20.0, T0=T0)
# T_exact = 15.117... (longer than T0 due to nonlinearity)

# Recover corrected GM from observed roll period
GM_corrected = recover_gm_rt4(
    T_obs=14.8,        # observed period (s)
    phi_max_deg=18.0,   # observed max roll amplitude (deg)
    C=0.797,            # vessel C-factor
    B=28.0,             # beam (m)
)

# Amplitude correction factor: GM_small_angle / GM_true
factor = gm_correction_factor(phi_max_deg=20.0)
# factor = 0.9847... (small-angle estimate is ~1.54% smaller than true GM)
# Recover true GM by dividing the small-angle estimate by this factor.

# Wall-sided correction when BM is known and the case is inside
# the validated envelope: phi <= 30 deg, BM/GM <= 4
GM_wall = recover_gm_wall_sided(
    T_obs=14.8,
    phi_max_deg=18.0,
    C=0.797,
    B=28.0,
    BM=3.0,
)

# Vessel-specific GZ curve workflow from a CSV table:
# angle_deg,GZ_m
angle_deg, gz_m = load_gz_table_csv("stability_curve.csv")
quality = assess_gz_table_quality(angle_deg, gz_m, phi_max_deg=20.0)
ratio = roll_period_gz_table_ratio(angle_deg, gz_m, phi_max_deg=20.0)
# ratio is T/T0 for the supplied righting-arm curve

# Practitioner workflow: selects arbitrary-GZ, wall-sided, or linear fallback
report = build_roll_period_report(
    T_obs=14.8,
    phi_max_deg=18.0,
    C=0.797,
    B=28.0,
    gz_csv_path="stability_curve.csv",
)

API Reference

Core Functions

Vessel Helpers

GZ Models

Analysis Tables

Limitations

The K(m) formula is exact for the linear GZ model (GZ = GM * sin(phi), pure pendulum). For the wall-sided hull model (GZ = sin(phi) * (GM + BM/2 * tan^2(phi))), the linear K(m) correction is not exact and can be materially wrong at high BM/GM ratios and large amplitudes.

The wall-sided interpolation functions are validated for the primary product envelope:

0 <= phi_max_deg <= 30
0 <= BM/GM <= 4

Inside that envelope, numerical validation found wall-sided GM recovery max error below 0.1% on midpoint test cases. Outside that envelope, use direct numerical integration or an actual vessel GZ curve workflow rather than extrapolating the interpolation table.

For full generality with arbitrary GZ curves, use roll_period_gz_table_ratio() for angle_deg,GZ_m tables or roll_period_gz_numerical() for custom callables. The table API estimates the initial GM from a low-angle slope fit, so sparse or digitized curves should carry uncertainty labels.

Sensitivity checks support 5-degree table spacing as a practical minimum and 2.5-degree spacing as preferred for highly curved GZ curves or near-limit amplitudes. Use assess_gz_table_quality() to surface warnings for coarse spacing, sparse low-angle data, near-vanishing-stability amplitudes, and digitized-curve uncertainty.

Mathematical Background

The roll equation of motion for a ship with linear restoring moment:

I * phi'' + W * GM * sin(phi) = 0

has the exact period solution involving the complete elliptic integral of the first kind K(m):

T = 4 * sqrt(I / (W * GM)) * K(sin^2(phi_max / 2))
  = T0 * (2/pi) * K(sin^2(phi_max / 2))

where T0 = 2pisqrt(I/(W*GM)) is the small-angle period. This result is due to Bernoulli (1749) and is classical mechanics, not novel research.

The key insight for inclining experiments: when T_obs is measured at finite amplitude phi_max, T_obs > T0 (the finite-amplitude period is always longer than the small-amplitude limit). Plugging T_obs into the small-angle formula GM = (C*B/T)^2 therefore over-states the period that "should" appear in the formula and under-states GM. The exact correction is:

GM_true = GM_small_angle * [2 * K(sin^2(phi_max / 2)) / pi]^2
        = GM_small_angle / gm_correction_factor(phi_max)

gm_correction_factor returns [pi / (2*K(m))]^2 <= 1, i.e. the ratio GM_small_angle / GM_true. Divide the small-angle estimate by this factor (or multiply by [2K/pi]^2) to recover the true GM.

Citation

Paper forthcoming. For now:

@software{rt4_roll_period,
  title = {rt4-roll-period: Amplitude-Aware Roll-Period GM Correction and Reporting},
  author = {R4RPI},
  year = {2026},
  version = {1.1.2},
  url = {https://github.com/resonant4/rt4-roll-period},
  license = {MIT}
}

License

MIT. See LICENSE.