:py:mod:`opendrift.elements`
============================

.. py:module:: opendrift.elements

.. autoapi-nested-parse::

   elements - LagrangianArray
   ==========================

   This module defines the fundamental class 'LagrangianArray'

   The LagrangianArray class holds a dictionary (OrderedDict) defining the variables (properties) of an element.

   The variables are defined by:

       * name
       * dtype (typically numpy.float32)

   and optionally:

       * unit (following udunits convention)
       * standard_name (to support output files compliant with CF convention)
       * default (default value, e.g. 0 for depth)

   The values for these variables are given through the constructor, and are stored as named attributes of the created object:

   .. code::

       from elements import LagrangianArray
       l = LagrangianArray(lon=[5, 6, 7], lat=[60, 60, 60], depth=10)
       print (l.lat)
       [ 60.  60.  60.]

   The input values are arrays, where a single element is simply a special case of LagrangianArray with length 1.

   New element types can be created by subclassing the LagrangianArray class and adding more variables through method `add_variables`.

   Example for Larvae:

   .. code::

       class Larvae(LagrangianArray):
           variables = LagrangianArray.add_variables({'length': {'dtype': np.float32, 'unit': 'mm'}})

   New modules may easily be created from a template (template_elements.py).
   Multiple inheritance is supported:

   .. code::

       class CodLarvae(Larvae):
           "Extending Larvae with variables relevant for cod larvae."

           variables = Larvae.add_variables(
               {'CodLarvaeProperty1':
                   {'dtype': np.float32}})


       class HalibutLarvae(Larvae):
           "Extending Larvae with variables relevant for halibut larvae."

           variables = Larvae.add_variables(
               {'HalibutLarvaeProperty1':
                   {'dtype': np.float32}})


   Example CodLarvae:

   .. code::

       l = CodLarvae(lon=[5, 6, 7], lat=[60, 60, 60], CodLarvaeProperty1=[1], length=10)
       l.length
       10



Submodules
----------
.. toctree::
   :titlesonly:
   :maxdepth: 1

   elements/index.rst
   passivetracer/index.rst


Package Contents
----------------

Classes
~~~~~~~

.. autoapisummary::

   opendrift.elements.LagrangianArray




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


   A generic array-like class for Lagrangian particle tracking.

   A LagrangianArray is a generic class keeping the values of given
   properties ('variables') of a collection of particles at a given time.
   Values are stored as named attributes (similar to recarray) which are
   ndarrays (1D, vectors) with one value for each particle, or as scalars
   for values shared among all particles.

   This is an Abstract Base Class, meaning that only subclasses can be used.
   Subclasses will add specific variables for specific purposes (particle
   types, e.g. oil, fish eggs...) to the core variables described below.

   Attributes:

       variables: An OrderedDict where keys are names of the
           variables/properties of the current object. The values
           of the OrderedDict are dictionaries with names such as
           'dtype', 'unit', 'standard_name' (CF), 'default' etc.
           All variable names will be added dynamically as attributes of
           the object after initialisation. These attributes will be
           numpy ndarrays of same length, or scalars. The core variables
           are:

               - ID: an integer identifying each particle.
               - status: 0 for active particles and a positive integer when deactivated
               - lon: longitude (np.float32)
               - lat: latitude (np.float32)
               - z: vertical position of the particle in m, positive upwards (above sea surface)

   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:method:: add_variables(new_variables)
      :classmethod:

      Method used by subclasses to add specific properties/variables.


   .. py:method:: extend(other)

      Add elements from another object.


   .. py:method:: move_elements(other, indices)

      Remove elements with given indices, and append to another object.
      NB: indices is boolean array, not real indices!


   .. py:method:: __len__()


   .. py:method:: __repr__()

      Return repr(self).