Stability
=========

Classes for stability analysis and GZ curve calculations.

StabilityCalculator
-------------------

.. py:class:: StabilityCalculator(vessel, water_density=1025.0)

   Calculator for stability analysis (GZ curves).

   :param vessel: The vessel to calculate stability for
   :param water_density: Water density in kg/m³

   .. method:: gz_curve(displacement_mass: float, cog: tuple[float, float, float], heels: list[float], tank_options: TankOptions | None = None, fixed_trim: float | None = None) -> StabilityCurve

      Calculate the GZ curve for a given loading condition.

      :param displacement_mass: Target displacement in kg.
      :param cog: Center of gravity (lcg, tcg, vcg) tuple in meters.
      :param heels: List of heel angles in degrees.
      :param tank_options: Optional :class:`~navaltoolbox.hydrostatics.TankOptions` to configure tank mass and free surface moment inclusion.
      :param fixed_trim: Optional fixed trim in degrees. If None, calculates free trim.
      :return: A :class:`StabilityCurve` object.

   .. py:method:: kn_curve(displacements, heels, lcg=0.0, tcg=0.0, fixed_trim=None)

      Calculates KN curves (Righting Lever from Keel) for multiple displacements.

      Returns one curve per displacement (cross-curves of stability).

      :param displacements: List of target displacements in kg
      :param heels: List of heel angles in degrees
      :param lcg: Longitudinal Center of Gravity (m)
      :param tcg: Transverse Center of Gravity (m)
      :param fixed_trim: Optional fixed trim in degrees. If None, calculates free trim.
      :returns: List of StabilityCurve objects

   .. method:: complete_stability(displacement_mass: float, cog: tuple[float, float, float], heels: list[float], tank_options: TankOptions | None = None, fixed_trim: float | None = None) -> CompleteStabilityResult

      Calculate complete stability analysis for a loading condition.
      
      This method combines hydrostatic calculations (at equilibrium), GZ curve generation, 
      and wind heeling analysis (if silhouettes are present).

      :param displacement_mass: Target displacement in kg.
      :param cog: Center of gravity (lcg, tcg, vcg) tuple in meters.
      :param heels: List of heel angles in degrees.
      :param tank_options: Optional :class:`~navaltoolbox.hydrostatics.TankOptions` to configure tank mass and free surface moment inclusion.
      :param fixed_trim: Optional fixed trim in degrees. If None, calculates free trim.
      :return: A :class:`CompleteStabilityResult` object containing all analysis data.

CompleteStabilityResult
-----------------------

.. py:class:: CompleteStabilityResult

   Complete stability calculation result combining hydrostatics, GZ curve, and wind data.

   .. py:attribute:: hydrostatics
      :type: HydrostaticState

      Hydrostatic state at equilibrium (draft, trim, GM0, etc.).

   .. py:attribute:: gz_curve
      :type: StabilityCurve

      GZ stability curve for the loading condition.

   .. py:attribute:: wind_data
      :type: WindHeelingData or None

      Wind heeling data (if silhouettes are defined).

   .. py:attribute:: displacement
      :type: float

      Displacement mass in kg.

   .. py:attribute:: cog
      :type: tuple[float, float, float]

      Center of gravity (LCG, TCG, VCG).

   .. py:attribute:: gm0
      :type: float or None

      Initial transverse metacentric height (GM0) with free surface correction.

   .. py:attribute:: gm0_dry
      :type: float or None

      Initial transverse metacentric height without free surface correction.

   .. py:attribute:: max_gz
      :type: float or None

      Maximum GZ value on the curve.

   .. py:attribute:: heel_at_max_gz
      :type: float or None

      Heel angle at maximum GZ.

   .. py:method:: has_wind_data()

      Returns True if wind heeling data is available.

      :rtype: bool

StabilityCurve
--------------

.. py:class:: StabilityCurve

   A complete GZ stability curve.

   .. py:method:: heels()

      Returns the heel angles.

      :rtype: list[float]

   .. py:method:: values()

      Returns the GZ values.

      :rtype: list[float]

   .. py:method:: points()

      Returns the points as a list of tuples (heel, draft, trim, gz).

      :rtype: list[tuple[float, float, float, float]]

   .. py:method:: get_stability_points()

      Returns a list of StabilityPoint objects with detailed information.
      
      Each StabilityPoint has:
      
      - ``heel``: Heel angle in degrees
      - ``draft``: Draft at equilibrium (m)
      - ``trim``: Trim angle in degrees
      - ``gz``: GZ value (m) (alias value)
      - ``value``: GZ or KN value (m)
      - ``cog``: Total physical Center of Gravity (LCG, TCG, VCG)
      - ``vessel_cog``: Vessel Center of Gravity (LCG, TCG, VCG)
      - ``is_flooding``: True if any opening is submerged
      - ``flooded_openings``: List of flooded opening names
      - ``freeboard``: Minimum deck edge freeboard (m) or None

      :rtype: list[StabilityPoint]

   .. py:attribute:: displacement
      :type: float

      Displacement in kg.

WindHeelingData
---------------

.. py:class:: WindHeelingData

   Wind heeling data from silhouette calculations.

   Used for wind heeling moment calculations per IMO 2008 IS Code (MSC.267).

   .. py:attribute:: emerged_area
      :type: float

      Total emerged lateral area above waterline (m²).

   .. py:attribute:: emerged_centroid
      :type: tuple[float, float]

      Centroid of emerged area (x, z) in meters.

   .. py:attribute:: wind_lever_arm
      :type: float

      Lever arm from waterline to centroid z coordinate (m).

   .. py:attribute:: waterline_z
      :type: float

      Waterline Z at which calculations were performed.