:py:mod:`gnome.weatherers.dissolution`
======================================

.. py:module:: gnome.weatherers.dissolution

.. autoapi-nested-parse::

   model dissolution process



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

Classes
~~~~~~~

.. autoapisummary::

   gnome.weatherers.dissolution.Dissolution



Functions
~~~~~~~~~

.. autoapisummary::

   gnome.weatherers.dissolution.printoptions



Attributes
~~~~~~~~~~

.. autoapisummary::

   gnome.weatherers.dissolution.pp


.. py:data:: pp

   

.. py:function:: printoptions(*args, **kwargs)


.. py:class:: Dissolution(waves=None, wind=None, **kwargs)


   Bases: :py:obj:`gnome.weatherers.Weatherer`

   Dissolution is still under development and not recommended for use.

   :param waves: waves object for obtaining wave_height, etc. at a
                 given time

   .. py:attribute:: _schema

      

   .. py:attribute:: _ref_as
      :value: 'dissolution'

      

   .. py:attribute:: _req_refs
      :value: ['waves', 'wind']

      

   .. py:method:: prepare_for_model_run(sc)

      Add dissolution key to mass_balance if it doesn't exist.
      - Assumes all spills have the same type of oil
      - let's only define this the first time


   .. py:method:: prepare_for_model_step(sc, time_step, model_time)

      Set/update arrays used by dispersion module for this timestep


   .. py:method:: initialize_data(sc, num_released)

      initialize the newly released portions of our data arrays:

      If on is False, then arrays should not be included
      - dont' initialize


   .. py:method:: _initialize_k_ow(sc, num_released)

      Initialize the molar averaged oil/water partition coefficient.

      Actually, there is nothing to do to initialize our partition
      coefficient, as it is recalculated in dissolve_oil()


   .. py:method:: dissolve_oil(data, substance, **kwargs)

      Here is where we calculate the dissolved oil.
      We will outline the steps as we go along, but off the top of
      my head:

      - recalculate the partition coefficient (K_ow)

      - droplet distribution per LE should be calculated by the
        natural dispersion process and saved in the data arrays before
        the dissolution weathering process.

      - for each LE:

          .. note::
              right now the natural dispersion process only
              calculates a single average droplet size. But we still
              treat it as an iterable.

          - for each droplet size category:

              - calculate the water phase transfer velocity (k_w)

              - calculate the mass xfer rate coefficient (beta)

              - calculate the water column time fraction (f_wc)

              - calculate the mass dissolved during refloat period

          - calculate the mass dissolved from the slick during the
            calm period.

      - the mass dissolved in the water column and the slick is summed
        per mass fraction (should only be aromatic fractions)

      - the sum of dissolved masses are compared to the existing mass
        fractions and adjusted to make sure we don't dissolve more
        mass than exists in the mass fractions.


   .. py:method:: oil_avg_density(masses, densities)


   .. py:method:: oil_total_volume(masses, densities)


   .. py:method:: state_variable(masses, densities, arom_mask)


   .. py:method:: beta_coeff(k_w, K_ow, v_inert)


   .. py:method:: water_column_time_fraction(points, model_time, water_phase_xfer_velocity)


   .. py:method:: calm_between_wave_breaks(points, model_time, time_step, time_spent_in_wc=0.0)


   .. py:method:: oil_concentration(masses, densities)


   .. py:method:: droplet_subsurface_mass_xfer_rate(droplet_avg_size, k_w, oil_concentrations, partition_coeffs, arom_mask, total_volumes)

      Here we are implementing something similar to equations

      - 1.26: this should estimate the mass xfer rate in kg/s

              .. note::
                  For this equation to work, we need to estimate
                  the total surface area of all droplets, not just
                  a single one

      - 1.27: this should estimate the mass xfer rate per unit area in kg/(m^2 * s)
      - 1.28: combines equations 1.26 and 1.27
      - 1.29: estimates the surface area of a single droplet.

      We return the mass xfer rate in units (kg/s)

      .. note::
          The Cohen equation (eq. 1.1, 1.27), I believe, is actually
          expressed in kg/(m^2 * hr).  So we need to convert our
          time units.

      .. note::
          for now, we are receiving a single average droplet size,
          which we assume will account for 100% of the oil volume.
          In the future we will need to work with something like::
              [(drop_size, vol_fraction, k_w_drop),
               ...
              ]

          This is because each droplet bin will represent a fraction
          of the total oil volume (or mass?), and will have its own
          distinct rise velocity.
          oil_concentrations and partition coefficients will be the
          same regardless of droplet size.


   .. py:method:: slick_subsurface_mass_xfer_rate(points, model_time, oil_concentration, partition_coeff, slick_area, arom_mask)

      Here we are implementing something similar to equation 1.21
      of our dissolution document.

      The Cohen equation (eq. 1.1), I believe, is actually expressed
      in kg/(m^2 * hr).  So we need to convert our time units.

      We return the mass xfer rate in units (kg/s)


   .. py:method:: weather_elements(sc, time_step, model_time)

      weather elements over time_step