pynavaltoolbox Documentation
Welcome to pynavaltoolbox’s documentation!
pynavaltoolbox is a Python package for naval engineering tools and utilities, providing hydrostatic and stability calculations for ship hulls.
Overview
pynavaltoolbox provides a comprehensive set of tools for naval architecture and marine engineering applications. The package enables:
Loading and manipulating hull geometries from STL and VTK files
Modeling fluid tanks with fill levels and free surface effects
Computing hydrostatic properties (displacement, centers, metacentric heights)
Calculating stability curves (GZ and KN curves) with free surface corrections
Visualizing hull geometries with waterplane
Features
Hull Geometry Management: Load, transform, scale, and export hull meshes
Tank Modeling: Define tanks from files, dimensions, or hull intersections
Free Surface Effects: Calculate FSM and corrections for partially filled tanks
Hydrostatic Calculations: Displacement, buoyancy centers, waterplane properties, GM dry/wet
Stability Analysis: GZ curves, KN curves with free surface corrections
Equilibrium Solver: Find equilibrium draft and trim for a given loading condition
Visualization: Save hull views and interactive 3D visualization
Type hints for better IDE support
NumPy-style docstrings for comprehensive documentation
Quick Example
from pynavaltoolbox import Hull, Vessel
from pynavaltoolbox.hydrostatics import HydrostaticsCalculator
from pynavaltoolbox.stability import StabilityCalculator
# Load a hull geometry
hull_geom = Hull("path/to/hull.stl")
# Create a vessel
vessel = Vessel(hull_geom)
# Calculate hydrostatics at a specific draft
hydro = HydrostaticsCalculator(vessel)
state = hydro.calculate_at_draft(draft=5.0, trim=0, heel=0)
print(f"Displacement: {state.displacement_mass:.0f} kg")
print(f"LCB: {state.lcb:.2f} m")
print(f"KMt: {state.kmt:.2f} m")
# Calculate GZ curve
stability = StabilityCalculator(vessel)
gz_curve = stability.calculate_gz_curve(
displacement_mass=state.displacement_mass,
cog=(state.lcb, 0.0, 6.0), # LCG, TCG, VCG
heels=list(range(0, 91, 5))
)
print(f"Max GZ: {gz_curve.get_max_gz():.2f} m at {gz_curve.get_angle_of_max_gz():.0f}°")