Hydrostatics Module

The Hydrostatics module provides tools for calculating hydrostatic properties of hull geometries, including displacement, buoyancy centers, waterplane properties, and metacentric heights.

Main Classes

HydrostaticsCalculator

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

Bases: object

Calculates hydrostatic properties for hull geometries.

hull: The Hull object to analyze.

water_density: Density of water in kg/m³.

shell_thickness: Shell thickness in meters (adds to submerged volume).

__init__(hull: Hull, water_density: float = 1025.0, shell_thickness: float = 0.0)[source]

Initialize the hydrostatics calculator.

Parameters:

hull – The Hull object.
water_density – Density of water in kg/m³ (default: 1025 for seawater).
shell_thickness – Shell thickness in meters (default: 0 for no shell). Adds volume to account for water displaced by shell thickness.

calculate_at_draft(draft: float, trim: float = 0, heel: float = 0, vcg: float = 0) → HydrostaticState[source]

Calculates hydrostatics for a fixed draft, trim, and heel.

Parameters:

draft – Draft at the reference point in meters.
trim – Trim angle in degrees (positive = bow down).
heel – Heel angle in degrees (positive = starboard down).
vcg – Vertical Center of Gravity (KG) in meters.

Returns:

HydrostaticState object with all calculated properties.

find_equilibrium(displacement_mass: float, center_of_gravity: Tuple[float, float, float], initial_draft: float | None = None) → HydrostaticState[source]

Finds the equilibrium position for a given displacement and CoG.

Parameters:

displacement_mass – Target displacement mass in kg.
center_of_gravity – (LCG, TCG, VCG) in meters.
initial_draft – Initial guess for draft. If None, estimated from bounds.

Returns:

HydrostaticState at equilibrium.

HydrostaticState

class pynavaltoolbox.hydrostatics.HydrostaticState(draft: float, trim: float = 0.0, heel: float = 0.0, displacement_volume: float = 0.0, displacement_mass: float = 0.0, lcb: float = 0.0, tcb: float = 0.0, vcb: float = 0.0, lcg: float = 0.0, tcg: float = 0.0, vcg: float = 0.0, waterplane_area: float = 0.0, wetted_surface_area: float = 0.0, midship_area: float = 0.0, cm: float = 0.0, lcf: float = 0.0, los: float = 0.0, cb: float = 0.0, cp: float = 0.0, draft_ap: float = 0.0, draft_fp: float = 0.0, kmt: float = 0.0, kml: float = 0.0, bmt: float = 0.0, bml: float = 0.0, lwl: float = 0.0, bwl: float = 0.0, stiffness_matrix: ndarray | None = None)[source]

Bases: object

Stores all hydrostatic properties for a specific loading condition.

draft

Draft at the reference point (typically amidships) in meters.

Type:: float

trim

Trim angle in degrees (positive = bow down).

Type:: float

heel

Heel angle in degrees (positive = starboard down).

Type:: float

displacement_volume

Displaced volume in m³.

Type:: float

displacement_mass

Displaced mass in kg.

Type:: float

lcb

Longitudinal Center of Buoyancy in meters.

Type:: float

tcb

Transverse Center of Buoyancy in meters.

Type:: float

vcb

Vertical Center of Buoyancy (KB) in meters.

Type:: float

lcg

Longitudinal Center of Gravity in meters.

Type:: float

tcg

Transverse Center of Gravity in meters.

Type:: float

vcg

Vertical Center of Gravity (KG) in meters.

Type:: float

waterplane_area

Waterplane area in m².

Type:: float

lcf

Longitudinal Center of Flotation in meters.

Type:: float

kmt

Transverse Metacentric Height (KM transverse) in meters.

Type:: float

kml

Longitudinal Metacentric Height (KM longitudinal) in meters.

Type:: float

bmt

Transverse Metacentric Radius (BM transverse) in meters.

Type:: float

bml

Longitudinal Metacentric Radius (BM longitudinal) in meters.

Type:: float

lwl

Length on Waterline in meters.

Type:: float

bwl

Beam on Waterline in meters.

Type:: float

wetted_surface_area

Wetted surface area in m².

Type:: float

midship_area

Midship section area in m².

Type:: float

cm

Midship section coefficient.

Type:: float

stiffness_matrix

6x6 restoring force/moment matrix.

Type:: numpy.ndarray | None

draft: float

trim: float = 0.0

heel: float = 0.0

displacement_volume: float = 0.0

displacement_mass: float = 0.0

lcb: float = 0.0

tcb: float = 0.0

vcb: float = 0.0

lcg: float = 0.0

tcg: float = 0.0

vcg: float = 0.0

waterplane_area: float = 0.0

wetted_surface_area: float = 0.0

midship_area: float = 0.0

cm: float = 0.0

lcf: float = 0.0

los: float = 0.0

cb: float = 0.0

cp: float = 0.0

draft_ap: float = 0.0

draft_fp: float = 0.0

kmt: float = 0.0

kml: float = 0.0

bmt: float = 0.0

bml: float = 0.0

lwl: float = 0.0

bwl: float = 0.0

stiffness_matrix: ndarray | None = None

__post_init__()[source]: Initialize stiffness matrix if not provided.

__init__(draft: float, trim: float = 0.0, heel: float = 0.0, displacement_volume: float = 0.0, displacement_mass: float = 0.0, lcb: float = 0.0, tcb: float = 0.0, vcb: float = 0.0, lcg: float = 0.0, tcg: float = 0.0, vcg: float = 0.0, waterplane_area: float = 0.0, wetted_surface_area: float = 0.0, midship_area: float = 0.0, cm: float = 0.0, lcf: float = 0.0, los: float = 0.0, cb: float = 0.0, cp: float = 0.0, draft_ap: float = 0.0, draft_fp: float = 0.0, kmt: float = 0.0, kml: float = 0.0, bmt: float = 0.0, bml: float = 0.0, lwl: float = 0.0, bwl: float = 0.0, stiffness_matrix: ndarray | None = None) → None

HullVisualizer

class pynavaltoolbox.hydrostatics.HullVisualizer(hull: Hull)[source]

Bases: object

Provides visualization capabilities for hull geometries.

hull: The Hull object to visualize.

__init__(hull: Hull)[source]

Initialize the visualizer.

Parameters:: hull – The Hull object to visualize.

save_view(filename: str, view_type: str = 'iso', show_waterline: bool = True, draft: float | None = None, trim: float = 0, heel: float = 0) → None[source]

Saves a screenshot of the hull from a specified viewpoint.

Parameters:

filename – Output filename (should end with .png, .jpg, etc.).
view_type – View type - ‘iso’, ‘side’, ‘front’, ‘rear’, ‘top’.
show_waterline – Whether to show the waterplane.
draft – Draft level for waterplane visualization.
trim – Trim angle in degrees.
heel – Heel angle in degrees.

show() → None[source]

Opens an interactive VTK window to view and manipulate the hull.

The window allows rotation, zooming, and panning with mouse controls.

Utility Functions

The tools submodule provides low-level utility functions:

Hydrostatic calculation tools.

This module provides utility functions for hydrostatic calculations, including volume and surface area computations.

pynavaltoolbox.hydrostatics.tools.calculate_submerged_properties(polydata: vtkPolyData, surface_function: Callable[[float, float], float], surface_type: str = 'planar', draft: float = 0.0, **kwargs) → Tuple[float, ndarray, float, Tuple[float, float, float, float, float, float]][source]

Calculate submerged volume, center of buoyancy, and wetted surface area.

This is a generic function that can handle different types of free surfaces: - Planar surface (calm water) - Sinusoidal surface (waves) - Custom surface defined by a function

Parameters:

polydata – The hull geometry as vtkPolyData.
surface_function – Function f(x, y) -> z defining the free surface. For planar: lambda x, y: draft. For sinusoidal: lambda x, y: draft + A*sin(k*x + phi).
surface_type – Type of surface (‘planar’, ‘sinusoidal’, ‘custom’).
draft – Reference draft level (used for planar surfaces).
**kwargs – Additional parameters (e.g., wave amplitude, wavelength).

Returns:

volume: Submerged volume in m³. center_of_buoyancy: numpy array [x, y, z] in meters. wetted_surface_area: Wetted surface area in m². bounds: (xmin, xmax, ymin, ymax, zmin, zmax) of submerged part.

Return type:

Tuple of (volume, center_of_buoyancy, wetted_surface_area, bounds) where

pynavaltoolbox.hydrostatics.tools.calculate_shell_volume(wetted_area: float, thickness: float) → float[source]

Calculate the volume of the shell based on wetted surface area and thickness.

This is an approximation assuming the shell follows the outer surface. For thin shells, Volume ≈ Area × Thickness

Parameters:

wetted_area – Wetted surface area in m².
thickness – Shell thickness in meters.

Returns:

Shell volume in m³.

pynavaltoolbox.hydrostatics.tools.calculate_waterplane_geometric_properties(waterline_polydata: vtkPolyData) → Tuple[float, ndarray, float, float][source]

Calculate geometric properties of the waterplane (Area, Centroid, I_t, I_l).

Uses Green’s theorem for polygon properties. Assumes the waterplane is in the XY plane (or parallel to it).

Parameters:: waterline_polydata – vtkPolyData containing the waterline contour(s).
Returns:: Tuple (Area, Centroid, I_t, I_l, lwl, bwl) - Area: Waterplane area in m² - Centroid: Cylinder center [x, y, z] (z is from input data) - I_t: Transverse moment of inertia (about longitudinal axis through centroid) in m^4 - I_l: Longitudinal moment of inertia (about transverse axis through centroid) in m^4 - lwl: Length on waterline in m - bwl: Beam on waterline in m

pynavaltoolbox.hydrostatics.tools.calculate_section_area(hull_polydata: vtkPolyData, x_location: float, draft: float) → float[source]

Calculate the submerged area of a transverse section at x_location.

Parameters:

hull_polydata – Hull geometry.
x_location – Longitudinal position of the section.
draft – Waterline Z-coordinate (area is calculated below this).

Returns:

Area in m².

Example Usage

Calculating Hydrostatics at a Draft

from pynavaltoolbox import Hull
from pynavaltoolbox.hydrostatics import HydrostaticsCalculator

hull = Hull("hull.stl")
calc = HydrostaticsCalculator(hull, water_density=1025.0)

# Calculate at specific draft
state = calc.calculate_at_draft(draft=5.0, trim=0, heel=0)

print(f"Displacement: {state.displacement_mass:.0f} kg")
print(f"Volume: {state.displacement_volume:.2f} m³")
print(f"LCB: {state.lcb:.2f} m")
print(f"KB: {state.vcb:.2f} m")
print(f"KMt: {state.kmt:.2f} m")
print(f"BMt: {state.bmt:.2f} m")

Finding Equilibrium

# Find equilibrium for given displacement and CoG
equilibrium = calc.find_equilibrium(
    displacement_mass=5000000.0,
    center_of_gravity=(70.0, 0.0, 10.0),
    initial_draft=5.0  # Optional starting guess
)

print(f"Draft: {equilibrium.draft:.2f} m")
print(f"Trim: {equilibrium.trim:.2f}°")

Visualizing the Hull

from pynavaltoolbox.hydrostatics import HullVisualizer

visualizer = HullVisualizer(hull)

# Save images from different views
visualizer.save_view("hull_side.png", view_type="side", draft=5.0)
visualizer.save_view("hull_iso.png", view_type="iso", draft=5.0)

# Interactive visualization
visualizer.show()