swiift.lib.att
==============

.. py:module:: swiift.lib.att

.. autoapi-nested-parse::

   Attenuation parametrisations
   ============================

   We model forcing waves as the superposition of damped sine functions,
   which can be written

   .. math::

       \eta(x) = \Im\Big[\sum_j \hat{a}_j \exp\big(\hat{k}_jx\big)\Big],

   with :math:`\hat{a}_j,\ \hat{k}_j` respectively the complex amplitude and
   wavenumber associated with wavemode :math:`j`.
   The non-negative imaginary parts of these wavenumbers,
   :math:`\alpha_j := \Im \hat{k}_j`, correspond to spatial attenuation rates.

   This module exposes **parametrisations** of the attenuation rates, which are
   functions implementing existing attenuation schemes.
   Alternatively, it exposes an interface for users to define attenuation
   **specifications** in order to express their own schemes.

   Parametrisations
   ----------------
   :py:func:`no_attenuation` -- No attenuation.

   :py:func:`parameterisation_01` -- Derived from :cite:t:`att-Sutherland2019`.

   :py:func:`parameterisation_yu2022` -- Implements :cite:t:`att-Yu2022`.

   Specification
   -------------
   TODO

   Bibliography
   ------------
   .. bibliography::
       :keyprefix: att-



Classes
-------

.. autoapisummary::

   swiift.lib.att.AttenuationParameterisation


Functions
---------

.. autoapisummary::

   swiift.lib.att.no_attenuation
   swiift.lib.att.parameterisation_01
   swiift.lib.att.parameterisation_yu2022


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

.. py:function:: no_attenuation()

   No attenuation.

   Waves propagate indifinitely, as if the ice cover is perfectly elastic and
   the fluid perfectly inviscid.

   :returns: Amplitude attenuation, in m^-1
   :rtype: typing.Literal[0]

   .. rubric:: Notes

   The attenuation is defined as:

   .. math::

       \alpha_j = 0 \forall j.


.. py:function:: parameterisation_01(thickness, wavenumbers)

   Parametrised attenuation for individual wave modes.

   This parametrisation is a simplified form of that of
   :cite:t:`att-Sutherland2019`.

   :param thickness: Ice thickness, in m
   :type thickness: float
   :param wavenumbers: Propagating wavenumbers, in rad m^-1.
   :type wavenumbers: np.ndarray

   :returns: Amplitude attenuation, in m^-1.
   :rtype: np.ndarray

   .. rubric:: Notes

   The attenuation is defined as:

   .. math::

       \alpha_j = \frac{1}{4} {k_j}^2 h.


.. py:function:: parameterisation_yu2022(thickness, gravity, angular_frequencies)

   Parametrised attenuation for individual wave modes.

   This parametrisation is issued from :cite:t:`att-Yu2022`.

   :param thickness: Ice thickness, in m.
   :type thickness: float
   :param gravity: Acceleration of gravity, in m s^-2.
   :type gravity: float
   :param angular_frequencies: Angular frequencies, in rad s^-1.
   :type angular_frequencies: np.ndarray

   :returns: Amplitude attenuation rates, in m^-1.
   :rtype: np.ndarray

   .. rubric:: Notes

   The attenuation is defined as:

   .. math::

       \alpha_j = 0.108 \frac{1}{h}\Bigg(\omega\sqrt{\frac{h}{g}}\Bigg)^{4.46}

   where the prefactor and exponents were obtained by a best fit to
   available data :cite:p:`att-Yu2022`.

   .. version-added:: 0.16.0


.. py:class:: AttenuationParameterisation(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   Unique IDs for attenuation parametrisations.

   .. attribute:: NO

      

      :type: defer to `no_attenuation`.

   .. attribute:: PARAM_01

      

      :type: defer to `parameterisation_01`.

   .. attribute:: PARAM_YU_2022

      

      :type: defer to `parameterisation_yu2022`.