Hydrostatics Tutorial
=====================

This tutorial covers hydrostatic calculations for ship hulls, including
displacement, buoyancy, and metacentric heights.

Introduction
------------

Hydrostatics is the study of fluids at rest. For ships, hydrostatic calculations
determine the static equilibrium conditions and initial stability characteristics.

Key hydrostatic properties include:

* **Displacement**: The weight of water displaced by the hull
* **Center of Buoyancy (B)**: The centroid of the displaced water volume
* **Waterplane Area**: The area of the hull at the waterline
* **Center of Flotation (F)**: The centroid of the waterplane
* **Metacentric Height (GM)**: A measure of initial stability

Loading a Hull
--------------

First, load your hull geometry from an STL or VTK file:

.. code-block:: python

   from pynavaltoolbox import Hull, Vessel

   # Load the hull geometry
   hull_geom = Hull("path/to/hull.stl")

   # Create a Vessel
   vessel = Vessel(hull_geom)

   # View the vessel dimension bounds
   bounds = vessel.get_bounds()
   length = bounds[1] - bounds[0]
   beam = bounds[3] - bounds[2]
   depth = bounds[5] - bounds[4]

   print(f"Length: {length:.2f} m")
   print(f"Beam: {beam:.2f} m")
   print(f"Depth: {depth:.2f} m")

Calculating Hydrostatics at a Draft
------------------------------------

The :class:`~pynavaltoolbox.hydrostatics.HydrostaticsCalculator` computes
hydrostatic properties at a given draft, trim, and heel:

.. code-block:: python

   from pynavaltoolbox.hydrostatics import HydrostaticsCalculator

   calc = HydrostaticsCalculator(vessel, water_density=1025.0)

   # Calculate at 5m draft, level trim, no heel
   state = calc.calculate_at_draft(draft=5.0, trim=0.0, heel=0.0)

   # Display results
   print("=== Hydrostatic Properties ===")
   print(f"Draft: {state.draft:.2f} m")
   print(f"Displacement: {state.displacement_mass:.0f} kg")
   print(f"Displacement Volume: {state.displacement_volume:.2f} m³")
   print()
   print("=== Centers ===")
   print(f"LCB (from AP): {state.lcb:.2f} m")
   print(f"TCB: {state.tcb:.2f} m")
   print(f"KB (VCB): {state.vcb:.2f} m")
   print(f"LCF (from AP): {state.lcf:.2f} m")
   print()
   print("=== Metacentric Heights ===")
   print(f"KMt (transverse): {state.kmt:.2f} m")
   print(f"KMl (longitudinal): {state.kml:.2f} m")
   print(f"BMt: {state.bmt:.2f} m")
   print(f"BMl: {state.bml:.2f} m")
   print()
   print("=== Waterplane Properties ===")
   print(f"Waterplane Area: {state.waterplane_area:.2f} m²")
   print(f"LWL: {state.lwl:.2f} m")
   print(f"BWL: {state.bwl:.2f} m")

Understanding the Results
-------------------------

The :class:`~pynavaltoolbox.hydrostatics.HydrostaticState` contains many properties:

.. list-table:: Hydrostatic Properties
   :header-rows: 1
   :widths: 20 15 65

   * - Property
     - Unit
     - Description
   * - displacement_volume
     - m³
     - Volume of water displaced by the submerged hull
   * - displacement_mass
     - kg
     - Mass of water displaced (= volume × density)
   * - lcb
     - m
     - Longitudinal Center of Buoyancy from AP
   * - tcb
     - m
     - Transverse Center of Buoyancy (positive = starboard)
   * - vcb (KB)
     - m
     - Vertical Center of Buoyancy from keel
   * - lcf
     - m
     - Longitudinal Center of Flotation from AP
   * - kmt
     - m
     - Height of transverse metacenter above keel
   * - kml
     - m
     - Height of longitudinal metacenter above keel
   * - bmt
     - m
     - Transverse metacentric radius (BM)
   * - bml
     - m
     - Longitudinal metacentric radius (BM)
   * - waterplane_area
     - m²
     - Area of the waterplane
   * - wetted_surface_area
     - m²
     - Wetted surface area of the hull

Finding Equilibrium
--------------------

To find the equilibrium draft and trim for a given loading condition:

.. code-block:: python

   # Define loading condition
   displacement = 5000000.0  # kg
   cog = (70.0, 0.0, 10.0)  # LCG, TCG, VCG in meters

   # Find equilibrium
   equilibrium = calc.find_equilibrium(
       displacement_mass=displacement,
       center_of_gravity=cog,
       initial_draft=5.0  # Optional starting guess
   )

   print(f"Equilibrium Draft: {equilibrium.draft:.2f} m")
   print(f"Equilibrium Trim: {equilibrium.trim:.2f}°")
   print(f"Draft at AP: {equilibrium.draft_ap:.2f} m")
   print(f"Draft at FP: {equilibrium.draft_fp:.2f} m")

The solver adjusts draft and trim until:

1. The displacement matches the target weight
2. LCB aligns with LCG (longitudinal moment = 0)

Generating Hydrostatic Tables
-----------------------------

You can generate hydrostatic tables by calculating at multiple drafts:

.. code-block:: python

   import numpy as np

   drafts = np.arange(3.0, 8.0, 0.5)

   print("Draft\tDispl(t)\tLCB\tKB\tKMt\tAw")
   print("-" * 60)

   for draft in drafts:
       state = calc.calculate_at_draft(draft=draft)
       print(f"{draft:.1f}\t{state.displacement_mass/1000:.0f}\t\t"
             f"{state.lcb:.2f}\t{state.vcb:.2f}\t"
             f"{state.kmt:.2f}\t{state.waterplane_area:.0f}")

Including Shell Thickness
-------------------------

For more accurate calculations, you can account for shell thickness:

.. code-block:: python

   # Calculator with 12mm shell thickness
   calc = HydrostaticsCalculator(
       vessel,
       water_density=1025.0,
       shell_thickness=0.012
   )

This adds volume to account for water displaced by the shell plating.

Next Steps
----------

* See :doc:`stability` for stability calculations
* See :doc:`../api/hydrostatics` for complete API reference