Tanks Module
============

The Tanks module provides functionality for modeling fluid tanks in vessels,
including volume calculations, fill level management, and free surface effects.

Tank Class
----------

.. autoclass:: pynavaltoolbox.tanks.Tank
   :members:
   :undoc-members:
   :show-inheritance:
   :special-members: __init__

TankState Dataclass
-------------------

.. autoclass:: pynavaltoolbox.tanks.TankState
   :members:
   :undoc-members:

Creating Tanks
--------------

There are three ways to create a Tank:

From STL/VTK File
~~~~~~~~~~~~~~~~~

.. code-block:: python

   from pynavaltoolbox.tanks import Tank

   # Load tank geometry from a file
   tank = Tank(
       "tank_geometry.stl",
       fluid_density=850.0,    # Fuel oil density
       fill_level=0.5,         # 50% filled
       name="FuelTank1"
   )

From Box Dimensions
~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from pynavaltoolbox.tanks import Tank

   # Create a rectangular tank from dimensions
   tank = Tank.from_box(
       x_min=10.0, x_max=20.0,   # 10m long
       y_min=-3.0, y_max=3.0,    # 6m wide  
       z_min=0.0, z_max=4.0,     # 4m tall
       fluid_density=1025.0,     # Seawater ballast
       fill_level=0.75,          # 75% filled
       name="BallastTank1"
   )

From Hull Intersection
~~~~~~~~~~~~~~~~~~~~~~

Create tanks that follow the shape of the hull (e.g., double-bottom tanks):

.. code-block:: python

   from pynavaltoolbox import Hull
   from pynavaltoolbox.tanks import Tank

   hull = Hull("ship.stl")

   # Create a double-bottom tank that follows the hull shape
   tank = Tank.from_box_hull_intersection(
       hull,
       x_min=20.0, x_max=40.0,   # Section of hull
       y_min=-10.0, y_max=10.0,  # Full beam
       z_min=0.0, z_max=1.5,     # 1.5m from keel
       fluid_density=1025.0,
       name="DoubleFond1"
   )

Managing Fill Level
-------------------

.. code-block:: python

   # Set fill level in different units
   tank.set_fill_level(75, unit='percent')     # 75%
   tank.set_fill_level(0.5, unit='fraction')   # 50%
   tank.set_fill_level(100.0, unit='m³')       # 100 cubic meters

   # Get current fill state
   print(f"Fill: {tank.fill_percent:.1f}%")
   print(f"Volume: {tank.fill_volume:.2f} m³")
   print(f"Mass: {tank.fluid_mass:.0f} kg")

Free Surface Effects
--------------------

Tanks with free surfaces cause a virtual rise in the center of gravity,
reducing stability. The module calculates free surface moments (FSM) and
free surface corrections (FSC):

.. code-block:: python

   # Get free surface properties
   I_t = tank.free_surface_moment_t      # Transverse moment (m⁴)
   I_l = tank.free_surface_moment_l      # Longitudinal moment (m⁴)
   fsc_t = tank.free_surface_correction_t  # GG' correction (m⁴)
   fsc_l = tank.free_surface_correction_l  # GG' correction (m⁴)

   # Get complete tank state
   state = tank.get_state()
   print(f"CoG: {state.center_of_gravity}")
   print(f"FSC transverse: {state.free_surface_correction_t:.2f} m⁴")

Integration with Vessel
-----------------------

Tanks can be added to a Vessel for combined calculations:

.. code-block:: python

   from pynavaltoolbox import Vessel, Hull
   from pynavaltoolbox.tanks import Tank

   hull = Hull("ship.stl")
   
   # Create tanks
   fuel = Tank.from_box(
       x_min=30.0, x_max=40.0,
       y_min=-5.0, y_max=5.0,
       z_min=2.0, z_max=6.0,
       fluid_density=850.0,
       name="Fuel"
   )
   fuel.set_fill_level(60, unit='percent')

   ballast = Tank.from_box(
       x_min=10.0, x_max=30.0,
       y_min=-8.0, y_max=8.0,
       z_min=0.0, z_max=2.0,
       fluid_density=1025.0,
       name="Ballast"
   )
   ballast.set_fill_level(50, unit='percent')

   # Create vessel with tanks
   vessel = Vessel(hull, tanks=[fuel, ballast])

   # Get combined tank properties
   total_mass = vessel.get_total_tanks_mass()
   combined_cog = vessel.get_tanks_center_of_gravity()
   fsm_t, fsm_l = vessel.get_total_free_surface_moment()
   fsc_t, fsc_l = vessel.get_total_free_surface_correction()