Stability Module
================

The Stability module provides tools for calculating ship stability characteristics,
including GZ curves (righting lever curves) and KN curves (cross curves of stability).

Main Classes
------------

StabilityCalculator
~~~~~~~~~~~~~~~~~~~

.. autoclass:: pynavaltoolbox.stability.StabilityCalculator
   :members:
   :undoc-members:
   :show-inheritance:
   :special-members: __init__

StabilityCurve
~~~~~~~~~~~~~~

.. autoclass:: pynavaltoolbox.stability.StabilityCurve
   :members:
   :undoc-members:
   :show-inheritance:

StabilityPoint
~~~~~~~~~~~~~~

.. autoclass:: pynavaltoolbox.stability.StabilityPoint
   :members:
   :undoc-members:
   :show-inheritance:

Concepts
--------

GZ Curve (Righting Lever Curve)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The GZ curve shows the righting lever (GZ) as a function of heel angle.
It is fundamental for assessing intact stability:

* **GZ** = KN - KG × sin(heel)
* **Maximum GZ**: The peak value indicates reserve stability
* **Angle of Maximum GZ**: Typically between 30° and 50° for stable vessels
* **Range of Stability**: The angle where GZ becomes negative (vessel capsizes)

KN Curve (Cross Curves of Stability)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

KN curves are calculated assuming KG = 0 (i.e., center of gravity at keel).
They are useful for generating stability data across multiple loading conditions:

* GZ = KN - KG × sin(heel)
* KN values depend only on hull geometry and displacement
* Different loading conditions can be evaluated by applying different KG values

Example Usage
-------------

Calculating a GZ Curve
~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from pynavaltoolbox import Hull, Vessel
   from pynavaltoolbox.stability import StabilityCalculator

   hull_geom = Hull("hull.stl")
   vessel = Vessel(hull_geom)
   
   stability = StabilityCalculator(vessel, water_density=1025.0)

   # Calculate GZ curve
   gz_curve = stability.calculate_gz_curve(
       displacement_mass=5000000.0,
       cog=(70.0, 0.0, 10.0),  # LCG, TCG, VCG
       heels=list(range(0, 91, 5))  # 0° to 90° in 5° steps
   )

   # Analyze results
   print(f"Maximum GZ: {gz_curve.get_max_gz():.3f} m")
   print(f"Angle of Max GZ: {gz_curve.get_angle_of_max_gz():.1f}°")
   print(f"Range of Stability: {gz_curve.get_range_of_stability():.1f}°")

   # Access data arrays for plotting
   import matplotlib.pyplot as plt
   plt.plot(gz_curve.heels, gz_curve.gz_values)
   plt.xlabel("Heel Angle (degrees)")
   plt.ylabel("GZ (m)")
   plt.title("GZ Curve")
   plt.grid(True)
   plt.show()

Calculating KN Curves
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   # Calculate KN curve at a specific displacement
   kn_curve = stability.calculate_kn_curve(
       displacement_mass=5000000.0,
       heels=[0, 10, 20, 30, 45, 60, 75, 90]
   )

   # Print KN values
   for point in kn_curve.points:
       print(f"Heel: {point.heel}°, KN: {point.kn:.3f} m")

   # Calculate GZ for different KG values
   kg_values = [8.0, 10.0, 12.0]
   for kg in kg_values:
       gz_at_30 = kn_curve.points[3].kn - kg * np.sin(np.radians(30))
       print(f"KG = {kg} m: GZ at 30° = {gz_at_30:.3f} m")