Stability#

Classes for stability analysis and GZ curve calculations.

StabilityCalculator#

class StabilityCalculator(vessel, water_density=1025.0)#

Calculator for stability analysis (GZ curves).

Parameters:

  • vessel – The vessel to calculate stability for

  • water_density – Water density in kg/m³

gz_curve(displacement_mass: float, cog: tuple[float, float, float], heels: list[float], tank_options: TankOptions | None = None, fixed_trim: float | None = None) → StabilityCurve#

Calculate the GZ curve for a given loading condition.

Parameters:

  • displacement_mass – Target displacement in kg.

  • cog – Center of gravity (lcg, tcg, vcg) tuple in meters.

  • heels – List of heel angles in degrees.

  • tank_options – Optional TankOptions to configure tank mass and free surface moment inclusion.

  • fixed_trim – Optional fixed trim in degrees. If None, calculates free trim.

Returns:

A StabilityCurve object.

kn_curve(displacements, heels, lcg=0.0, tcg=0.0, fixed_trim=None)#

Calculates KN curves (Righting Lever from Keel) for multiple displacements.

Returns one curve per displacement (cross-curves of stability).

Parameters:

  • displacements – List of target displacements in kg

  • heels – List of heel angles in degrees

  • lcg – Longitudinal Center of Gravity (m)

  • tcg – Transverse Center of Gravity (m)

  • fixed_trim – Optional fixed trim in degrees. If None, calculates free trim.

Returns:

List of StabilityCurve objects

complete_stability(displacement_mass: float, cog: tuple[float, float, float], heels: list[float], tank_options: TankOptions | None = None, fixed_trim: float | None = None) → CompleteStabilityResult#

Calculate complete stability analysis for a loading condition.

This method combines hydrostatic calculations (at equilibrium), GZ curve generation, and wind heeling analysis (if silhouettes are present).

Parameters:

  • displacement_mass – Target displacement in kg.

  • cog – Center of gravity (lcg, tcg, vcg) tuple in meters.

  • heels – List of heel angles in degrees.

  • tank_options – Optional TankOptions to configure tank mass and free surface moment inclusion.

  • fixed_trim – Optional fixed trim in degrees. If None, calculates free trim.

Returns:

A CompleteStabilityResult object containing all analysis data.

CompleteStabilityResult#

class CompleteStabilityResult#

Complete stability calculation result combining hydrostatics, GZ curve, and wind data.

hydrostatics: HydrostaticState#

Hydrostatic state at equilibrium (draft, trim, GM0, etc.).

gz_curve: StabilityCurve#

GZ stability curve for the loading condition.

wind_data: WindHeelingData or None#

Wind heeling data (if silhouettes are defined).

displacement: float#

Displacement mass in kg.

cog: tuple[float, float, float]#

Center of gravity (LCG, TCG, VCG).

gm0: float or None#

Initial transverse metacentric height (GM0) with free surface correction.

gm0_dry: float or None#

Initial transverse metacentric height without free surface correction.

max_gz: float or None#

Maximum GZ value on the curve.

heel_at_max_gz: float or None#

Heel angle at maximum GZ.

has_wind_data()#

Returns True if wind heeling data is available.

Return type:

bool

StabilityCurve#

class StabilityCurve#

A complete GZ stability curve.

heels()#

Returns the heel angles.

Return type:

list[float]

values()#

Returns the GZ values.

Return type:

list[float]

points()#

Returns the points as a list of tuples (heel, draft, trim, gz).

Return type:

list[tuple[float, float, float, float]]

get_stability_points()#

Returns a list of StabilityPoint objects with detailed information.

Each StabilityPoint has:

  • heel: Heel angle in degrees

  • draft: Draft at equilibrium (m)

  • trim: Trim angle in degrees

  • gz: GZ value (m) (alias value)

  • value: GZ or KN value (m)

  • cog: Total physical Center of Gravity (LCG, TCG, VCG)

  • vessel_cog: Vessel Center of Gravity (LCG, TCG, VCG)

  • is_flooding: True if any opening is submerged

  • flooded_openings: List of flooded opening names

  • freeboard: Minimum deck edge freeboard (m) or None

Return type:

list[StabilityPoint]

displacement: float#

Displacement in kg.

WindHeelingData#

class WindHeelingData#

Wind heeling data from silhouette calculations.

Used for wind heeling moment calculations per IMO 2008 IS Code (MSC.267).

emerged_area: float#

Total emerged lateral area above waterline (m²).

emerged_centroid: tuple[float, float]#

Centroid of emerged area (x, z) in meters.

wind_lever_arm: float#

Lever arm from waterline to centroid z coordinate (m).

waterline_z: float#

Waterline Z at which calculations were performed.