:py:mod:`gnome.spills.substance`
================================

.. py:module:: gnome.spills.substance

.. autoapi-nested-parse::

   The substance is an abstraction for the various types of
   "things" one might model with pyGNOME.

   The role of a substance is to:

    - Define what data is carried with the elements

    - Provide a way to initialize the elements

    - Optionally, provide tools to support computation during the run

      - for example, GnomeOil can compute changes in density, etc of
        the elements as the model runs.



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

Classes
~~~~~~~

.. autoapisummary::

   gnome.spills.substance.Substance
   gnome.spills.substance.NonWeatheringSubstance
   gnome.spills.substance.SubsurfaceSubstance




.. py:class:: Substance(windage_range=None, windage_persist=None, standard_density=1000.0, *args, **kwargs)


   Bases: :py:obj:`gnome.gnomeobject.GnomeId`

   A class for assigning a unique ID for an object

   :param windage_range: Range of windages for the substance (leeway).
                         Default: (.01, .04)
   :type windage_range: tuple of values between 0 and 1

   :param windage_persist=900: persistence of windage settings in seconds. -1
                               or Inf means infinite.
   :type windage_persist: integer seconds.

   :param standard_density=1000.0: The density of the substance, used to convert
                                   mass to/from volume
   :type standard_density: float in units of kg/m^3


   .. py:property:: all_array_types

      Fixme: should the initializers be what holds the array types?
              don't we know that this should have already?


   .. py:property:: is_weatherable


   .. py:property:: windage_range


   .. py:property:: windage_persist


   .. py:attribute:: _schema

      

   .. py:attribute:: _ref_as
      :value: 'substance'

      

   .. py:method:: get_initializer_by_name(name)

      get first initializer in list whose name matches 'name' 


   .. py:method:: has_initializer(name)

      Returns True if an initializer is present in the list which sets the
      data_array corresponding with 'name', otherwise returns False


   .. py:method:: initialize_LEs(to_rel, arrs, environment=None)

      :param to_rel - number of new LEs to initialize
      :param arrs - dict-like of data arrays representing LEs


   .. py:method:: _pick_water(environment)


   .. py:method:: density_at_temp(temp=273.15)

      For non-weathering substance, we just return the standard density.


   .. py:method:: _attach_default_refs(ref_dict)

      !!!IMPORTANT!!!
      If this object requires default references (self._req_refs exists),
      this function will use the name of the references as keys into a
      reference dictionary to get a list of satisfactory references (objects
      that have obj._ref_as == self._req_refs). It will then attach the
      first object in the reference list to that attribute on this object.

      This behavior can be overridden if the object needs more specific
      attachment behavior than simply 'first in line'

      In addition, this function SHOULD BE EXTENDED if this object should
      provide default references to any contained child objects. When doing
      so, please be careful to respect already existing references. The
      reference attachment system should only act if the requested reference
      'is None' when the function is invoked.
      See Model._attach_default_refs() for an example.



.. py:class:: NonWeatheringSubstance(windage_range=None, windage_persist=None, standard_density=1000.0, *args, **kwargs)


   Bases: :py:obj:`Substance`

   A class for assigning a unique ID for an object

   :param windage_range: Range of windages for the substance (leeway).
                         Default: (.01, .04)
   :type windage_range: tuple of values between 0 and 1

   :param windage_persist=900: persistence of windage settings in seconds. -1
                               or Inf means infinite.
   :type windage_persist: integer seconds.

   :param standard_density=1000.0: The density of the substance, used to convert
                                   mass to/from volume
   :type standard_density: float in units of kg/m^3


   .. py:property:: is_weatherable


   .. py:attribute:: _schema

      The simplest substance that can be used with the model

      It can not be weathered, but does have basic properties for transport:

      Windage, density, etc.


   .. py:method:: initialize_LEs(to_rel, arrs, environment=None)

      :param to_rel - number of new LEs to initialize
      :param arrs - dict-like of data arrays representing LEs



.. py:class:: SubsurfaceSubstance(distribution, *args, **kwargs)


   Bases: :py:obj:`NonWeatheringSubstance`

   Substance that can be used subsurface

   key feature is that it initializes rise velocity from a distribution

   Note: this should probably be part of a Release Object, not a Substance.

   :param distribution='UniformDistribution': which distribution to use
   :type distribution: Distribution Object

   Note: distribution should return values in m/s

   See gnome.utilities.distributions for details