Stability Module

The Stability module provides tools for calculating ship stability characteristics, including GZ curves (righting lever curves) and KN curves (cross curves of stability).

Main Classes

StabilityCalculator

class pynavaltoolbox.stability.StabilityCalculator(hull: Hull, water_density: float = 1025.0, shell_thickness: float = 0.0)[source]

Bases: HydrostaticsCalculator

Calculator for stability analysis (KN and GZ curves). Inherits from HydrostaticsCalculator to reuse core calculations.

calculate_kn_curve(displacement_mass: float, heels: List[float]) → StabilityCurve[source]

Calculates the KN curve (Cross Curves of Stability) for a given displacement.

KN is the righting lever assuming VCG (KG) = 0. GZ = KN - KG * sin(heel)

The calculation assumes “free trim”, meaning the vessel is allowed to find its equilibrium trim and draft at each heel angle.

Parameters:

displacement_mass – Displacement in kg.
heels – List of heel angles in degrees to calculate.

Returns:

StabilityCurve object containing KN values.

calculate_gz_curve(displacement_mass: float, cog: Tuple[float, float, float], heels: List[float]) → StabilityCurve[source]

Calculates the GZ curve for a specific loading condition.

Parameters:

displacement_mass – Displacement in kg.
cog – Center of Gravity (LCG, TCG, VCG) in meters.
heels – List of heel angles in degrees.

Returns:

StabilityCurve object.

StabilityCurve

class pynavaltoolbox.stability.StabilityCurve(displacement_mass: float, points: List[StabilityPoint])[source]

Bases: object

Represents a complete stability curve (GZ or KN).

displacement_mass: float

points: List[StabilityPoint]

property heels: ndarray: Array of heel angles.

property gz_values: ndarray: Array of GZ values.

property kn_values: ndarray: Array of KN values.

get_max_gz() → float[source]: Returns the maximum GZ value.

get_angle_of_max_gz() → float[source]: Returns the angle where GZ is maximum.

get_range_of_stability() → float[source]: Returns the range of positive stability (angle where GZ becomes negative). Assumes curve starts at 0.

__init__(displacement_mass: float, points: List[StabilityPoint]) → None

StabilityPoint

class pynavaltoolbox.stability.StabilityPoint(heel: float, draft: float, trim: float, kn: float, gz: float)[source]

Bases: object

Represents a single point on a stability curve.

heel: float

draft: float

trim: float

kn: float

gz: float

__init__(heel: float, draft: float, trim: float, kn: float, gz: float) → None

Concepts

GZ Curve (Righting Lever Curve)

The GZ curve shows the righting lever (GZ) as a function of heel angle. It is fundamental for assessing intact stability:

GZ = KN - KG × sin(heel)
Maximum GZ: The peak value indicates reserve stability
Angle of Maximum GZ: Typically between 30° and 50° for stable vessels
Range of Stability: The angle where GZ becomes negative (vessel capsizes)

KN Curve (Cross Curves of Stability)

KN curves are calculated assuming KG = 0 (i.e., center of gravity at keel). They are useful for generating stability data across multiple loading conditions:

GZ = KN - KG × sin(heel)
KN values depend only on hull geometry and displacement
Different loading conditions can be evaluated by applying different KG values

Example Usage

Calculating a GZ Curve

from pynavaltoolbox import Hull
from pynavaltoolbox.stability import StabilityCalculator

hull = Hull("hull.stl")
stability = StabilityCalculator(hull, water_density=1025.0)

# Calculate GZ curve
gz_curve = stability.calculate_gz_curve(
    displacement_mass=5000000.0,
    cog=(70.0, 0.0, 10.0),  # LCG, TCG, VCG
    heels=list(range(0, 91, 5))  # 0° to 90° in 5° steps
)

# Analyze results
print(f"Maximum GZ: {gz_curve.get_max_gz():.3f} m")
print(f"Angle of Max GZ: {gz_curve.get_angle_of_max_gz():.1f}°")
print(f"Range of Stability: {gz_curve.get_range_of_stability():.1f}°")

# Access data arrays for plotting
import matplotlib.pyplot as plt
plt.plot(gz_curve.heels, gz_curve.gz_values)
plt.xlabel("Heel Angle (degrees)")
plt.ylabel("GZ (m)")
plt.title("GZ Curve")
plt.grid(True)
plt.show()

Calculating KN Curves

# Calculate KN curve at a specific displacement
kn_curve = stability.calculate_kn_curve(
    displacement_mass=5000000.0,
    heels=[0, 10, 20, 30, 45, 60, 75, 90]
)

# Print KN values
for point in kn_curve.points:
    print(f"Heel: {point.heel}°, KN: {point.kn:.3f} m")

# Calculate GZ for different KG values
kg_values = [8.0, 10.0, 12.0]
for kg in kg_values:
    gz_at_30 = kn_curve.points[3].kn - kg * np.sin(np.radians(30))
    print(f"KG = {kg} m: GZ at 30° = {gz_at_30:.3f} m")