opendrift.models.larvalfish_extended
====================================

.. py:module:: opendrift.models.larvalfish_extended


Attributes
----------

.. autoapisummary::

   opendrift.models.larvalfish_extended.logger


Classes
-------

.. autoapisummary::

   opendrift.models.larvalfish_extended.LarvalFishExtendedElement
   opendrift.models.larvalfish_extended.LarvalFishExtended


Module Contents
---------------

.. py:data:: logger

.. py:class:: LarvalFishExtendedElement(**kwargs)

   Bases: :py:obj:`opendrift.models.oceandrift.Lagrangian3DArray`


   Extending Lagrangian3DArray with specific properties for larval fish
   and generic biological particles (e.g. phytoplankton).

   Initialises a LagrangianArray with given properties.

   Args:
       Keyword arguments (kwargs) with names corresponding to the
       OrderedDict 'variables' of the class, and corresponding values.
       The values must be ndarrays of equal length, or scalars.
       All (or none) variables must be given, unless a default value
       is specified in the OrderedDict 'variables'
       An empty object may be created by giving no input.


   .. py:attribute:: variables


.. py:class:: LarvalFishExtended(*args, **kwargs)

   Bases: :py:obj:`opendrift.models.oceandrift.OceanDrift`


   Extended biological particle trajectory model based on OpenDrift.

   Extends the base LarvalFish model with:

   - Configurable vertical behavior: depth-keeping and diel vertical
     migration (DVM) using solar elevation for day/night detection.
   - Support for both larval fish and phytoplankton particle types.
   - Multiple egg hatching methods (temperature-dependent or fixed-time).
   - Adaptive depth-band targeting with configurable band widths.

   Vertical behavior modes
   -----------------------
   - ``none``: No active vertical movement (passive drift).
   - ``depth``: Maintain a preferred depth band around ``z_pref``.
   - ``dvm``: Diel vertical migration between ``z_day`` (daytime) and
     ``z_night`` (nighttime) depths, using ``solar_elevation()`` to
     determine day/night state.

   Particle types
   --------------
   - ``larva``: Full egg/hatching/growth lifecycle. Only hatched larvae
     exhibit active vertical behavior; eggs remain passive.
   - ``phytoplankton``: All particles have active vertical behavior
     from the start. No egg/growth stages.

   Initialise OpenDriftSimulation

   Args:
       seed: integer or None. A given integer will yield identical
           random numbers drawn each simulation. Random numbers are
           e.g. used to distribute particles spatially when seeding,
           and may be used by modules (subclasses) for e.g. diffusion.
           Specifying a fixed value (default: 0) is useful for sensitivity
           tests. With seed = None, different random numbers will be drawn
           for subsequent runs, even with identical configuration/input.
       iomodule: name of module used to export data
           default: netcdf, see :py:mod:`opendrift.io` for more alternatives.
           `iomodule` is module/filename without preceeding `io_`
       loglevel: set to 0 (default) to retrieve all debug information.
           Provide a higher value (e.g. 20) to receive less output.
       logtime: if True, a time stamp is given for each logging line.
                logtime can also be given as a python time specifier
                (e.g. '%H:%M:%S')
       logfile:
           None (default) to send output to console.
           A string to send output to logfile.
           Or to get output to both terminal and file:
               [<filename.log>, logging.StreamHandler(sys.stdout)]


   .. py:attribute:: ElementType

      Any trajectory model implementation must define an ElementType.



   .. py:attribute:: required_variables

      Any trajectory model implementation must list needed variables.



   .. py:method:: _compute_band_half_width(z)

      Compute depth band half-width: clamp(dz_min, dz_rel*|z|, dz_max).



   .. py:method:: _target_into_band(z, center, half_w)

      Return target depth that moves z into [center-half_w, center+half_w].

      If z is already inside the band, returns z (no movement).



   .. py:method:: _apply_vertical_behavior()

      Apply active vertical behavior based on configured mode.

      Modes
      -----
      - ``none``: No active vertical movement.
      - ``depth``: Maintain depth band around ``z_pref``.
      - ``dvm``: Diel vertical migration between ``z_day`` and ``z_night``,
        using ``solar_elevation()`` for day/night detection.

      For larvae (particle_type='larva'), only hatched larvae (not eggs)
      exhibit active vertical behavior. Eggs remain passive.
      For phytoplankton, all particles are active.



   .. py:method:: update_fish_larvae()


   .. py:method:: update()

      Update particle state: biology, advection, mixing, vertical behavior.