Loading Conditions
==================

Classes for managing mass inventories and tank fill overrides to define operational profiles.

MassCategory
------------

   .. py:class:: MassCategory

      Category of a mass item.

      .. py:staticmethod:: lightship()

         Creates a Lightship category.

      .. py:staticmethod:: deadweight()

         Creates a Deadweight category.

      .. py:staticmethod:: other()

         Creates an Other category (default).


MassItem
--------

   .. py:class:: MassItem(name, mass, cog, category=None)

      A single mass item with name, mass, position, and optional category.

      :param name: Identifier for the mass item.
      :param mass: Mass in kg.
      :param cog: Center of gravity (lcg, tcg, vcg) in meters.
      :param category: Optional MassCategory (default: Other).

      .. py:method:: __init__(name, mass, cog, category=None)

         Creates a MassItem.

   **Properties**

   .. py:attribute:: name
      :type: str
      :no-index:

   .. py:attribute:: mass
      :type: float

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

   .. py:attribute:: category
      :type: MassCategory

LoadingCondition
----------------

   .. py:class:: LoadingCondition(name)

      A complete loading condition with mass items and tank fill overrides.

      :param name: Name of the loading condition.

      .. py:method:: __init__(name)

         Creates a LoadingCondition.

   **Properties**

   .. py:attribute:: name
      :type: str
      :no-index:

      Name of the loading condition.

   **Mass Management**

   .. py:method:: add_mass(item)

      Add a MassItem.

      :param item: A MassItem instance.

   .. py:method:: add_mass_simple(name, mass, cog, category=None)

      Add a mass item by parameters (convenience).

      :param name: Identifier for the mass item.
      :param mass: Mass in kg.
      :param cog: Center of gravity (lcg, tcg, vcg) in meters.
      :param category: Optional MassCategory (default: Other).

   .. py:method:: remove_mass(name)

      Remove a mass item by name. 

      :param name: Name of the mass.
      :returns: True if found and removed.
      :rtype: bool

   .. py:method:: get_masses()

      Returns all mass items.

      :rtype: list[MassItem]

   .. py:method:: num_masses()

      Returns the number of mass items.

      :rtype: int

   **Tank Fill Overrides**

   .. py:method:: set_tank_fill(tank_name, fill_level)

      Set a tank fill override by fill level (0.0 to 1.0).

   .. py:method:: set_tank_fill_percent(tank_name, fill_percent)

      Set a tank fill override by percentage (0 to 100).

   .. py:method:: remove_tank_fill(tank_name)

      Remove a tank fill override.

      :returns: True if found and removed.
      :rtype: bool

   .. py:method:: num_tank_overrides()

      Returns the number of tank fill overrides.

      :rtype: int

   .. py:method:: get_tank_fills()

      Returns tank fill overrides as a dictionary.

      :returns: {name: fill_level}
      :rtype: dict[str, float]

   **Application & Calculation**

   .. py:method:: apply(vessel)

      Apply tank fill overrides to the vessel's tanks. Only tanks listed in overrides are modified. Other tanks keep their current fill level.

      :param vessel: Vessel instance.

   .. py:method:: total_displacement(vessel)

      Returns the total displacement (masses + tank fluid masses) in kg. Must be called after apply().

      :param vessel: Vessel instance.
      :rtype: float

   .. py:method:: total_cog(vessel)

      Returns the combined center of gravity in meters. Must be called after apply().

      :param vessel: Vessel instance.
      :returns: (lcg, tcg, vcg)
      :rtype: tuple[float, float, float]

   .. py:method:: resolve(vessel)

      Returns (total_displacement, (lcg, tcg, vcg)) in a single call. Must be called after apply().

      :param vessel: Vessel instance.
      :rtype: tuple[float, tuple[float, float, float]]

   .. py:method:: item_displacement()

      Returns the displacement of mass items only (excluding tank fluids) in kg.

      :rtype: float

   .. py:method:: item_cog()

      Returns the center of gravity of mass items only (lcg, tcg, vcg) in meters.

      :rtype: tuple[float, float, float]

   .. py:method:: resolve_items()

      Returns (item_displacement, (lcg, tcg, vcg)) in a single call. Use this for stability calculations to avoid double-counting tank masses.
      
      .. note::
         It is highly recommended to use the convenience methods directly on the calculators: :py:meth:`~navaltoolbox.StabilityCalculator.gz_curve_from_loading` and :py:meth:`~navaltoolbox.HydrostaticsCalculator.from_loading`. These methods automatically handle the save/restore process for tank configurations.

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

   **Serialization and Copying**

   .. py:method:: to_json()

      Serialize to JSON string.

      :rtype: str

   .. py:staticmethod:: from_json(json_str)

      Deserialize from JSON string.

      :rtype: LoadingCondition

   .. py:method:: save_json(path)

      Save to JSON file.

   .. py:staticmethod:: load_json(path)

      Load from JSON file.

   .. py:staticmethod:: from_csv(csv_str)

      Deserialize from CSV string. A unified CSV format is used to handle both Mass Items and Tank Fill Overrides.

      **CSV Format Example:**

      .. code-block:: csv

         Type,Name,Mass,LCG,TCG,VCG,Category,FillPercent
         Mass,Lightship,5000000.0,45.0,0.0,4.5,Lightship,
         Mass,Crew,3000.0,35.0,0.0,8.0,Other,
         Tank,FO_1P,,,,,,95.0

      :rtype: LoadingCondition

   .. py:staticmethod:: load_csv(path)

      Load from CSV file. Uses the same unified format as ``from_csv``.

      :rtype: LoadingCondition

   .. py:method:: copy(name=None)

      Create a copy, optionally with a new name.

      :param name: New name
      :rtype: LoadingCondition