:py:mod:`gnome.environment.waves`
=================================

.. py:module:: gnome.environment.waves

.. autoapi-nested-parse::

   The waves environment object.

   Computes the wave height and percent wave breaking

   Uses the same approach as ADIOS 2

   (code ported from old MATLAB prototype code)



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

Classes
~~~~~~~

.. autoapisummary::

   gnome.environment.waves.Waves




Attributes
~~~~~~~~~~

.. autoapisummary::

   gnome.environment.waves.g


.. py:data:: g

   

.. py:class:: Waves(wind=None, water=None, **kwargs)


   Bases: :py:obj:`gnome.environment.environment.Environment`

   class to compute the wave height for a time series

   At the moment, it only does a single point, non spatially
   variable, but may be extended in the future

   wind and water must be set before running the model; however, these
   can be set after object construction

   :param wind: A wind object to get the wind speed.
                This should be a moving average wind object.
   :type wind: A Wind type, or equivelent

   :param water: water properties, specifically fetch and wave height
   :type water: environment.Water object.

   .. note:: must take ``**kwargs`` since base class supports more inputs like
       'name'. The new_from_dict() alternate constructor will invoke
       __init__ will arguments that supported by baseclass

   .. py:property:: data_start

      The Waves object doesn't directly manage a time series of data,
      so it will not have a data range itself.  But it depends upon
      a Wind and a Water object.  The Water won't have a data range
      either, but the Wind will.
      So its data range will be that of the Wind it is associated with.


   .. py:property:: data_stop


   .. py:attribute:: _ref_as
      :value: 'waves'

      

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

      

   .. py:attribute:: _schema

      

   .. py:method:: validate()

      All pygnome objects should be able to validate themselves. Many
      py_gnome objects reference other objects like wind, water, waves. These
      may not be defined when object is created so they can be None at
      construction time; however, they should reference valid objects
      when running in the model. If make_default_refs is True, then object
      is valid because the model will set these up at runtime. To raise
      an exception for missing references at runtime, directly call
      validate_refs(level='error')

      'wind', 'water', 'waves' attributes also have special meaning. An
      object containing this attribute references the corresponding object.

      Logs warnings:

      :returns: a tuple of length two containing:
          (a list of messages that were logged, isvalid bool)
          If any references are missing and make_default_refs is False,
          object is not valid

      .. note: validate() only logs warnings since it designed to be used
          to validate before running model. To log these as errors during
          model run, invoke validate_refs() directly.


   .. py:method:: get_value(points, time)

      return the rms wave height, peak period and percent wave breaking
      at a given time. Does not currently support location-variable waves.

      :param time: the time you want the wave data for
      :type time: datetime.datetime object

      :returns: wave_height, peak_period, whitecap_fraction,
                dissipation_energy

      Units:
        wave_height: meters (RMS height)
        peak_period: seconds
        whitecap_fraction: unit-less fraction
        dissipation_energy: not sure!! # fixme!


   .. py:method:: get_wind_speed(points, model_time, coord_sys='r', fill_value=1.0)

      Wrapper for the weatherers so they can extrapolate


   .. py:method:: get_emulsification_wind(points, time)

      Return the right wind for the wave climate

      If a wave height was specified, then you need the greater of the
      real or pseudo wind.

      If not, then you need the actual wind.

      The idea here is that if there is a low wind, but the user specified
      waves, we really want emulsification that makes sense for the waves.
      But if the actual wind is stronger than that for the wave height give,
      we should use the actual wind.

      fixme: I'm not sure this is right -- if we stick with the wave energy
             given by the user for dispersion, why not for emulsification?


   .. py:method:: compute_H(U)


   .. py:method:: pseudo_wind(H)


   .. py:method:: whitecap_fraction(U)


   .. py:method:: mean_wave_period(U)


   .. py:method:: peak_wave_period(points, time)

      :param time: the time you want the wave data for
      :type time: datetime.datetime object

      :returns: peak wave period (s)


   .. py:method:: dissipative_wave_energy(H)


   .. py:method:: energy_dissipation_rate(H, U)

      c_ub = 100 = dimensionless empirical coefficient to correct
      for non-Law-of-the-Wall results (Umlauf and Burchard, 2003)

      u_c = water friction velocity (m/s)
      sqrt(rho_air / rho_w) * u_a ~ .03 * u_a
      u_a = air friction velocity (m/s)
      z_0 = surface roughness (m) (Taylor and Yelland)
      c_p = peak wave speed for Pierson-Moskowitz spectrum
      w_p = peak angular frequency for Pierson-Moskowitz spectrum (1/s)

      TODO: This implementation should be in a utility function.
      It should not be part of the Waves management object itself.