netsse.analys.emep.emep
=======================

.. py:function:: netsse.analys.emep.emep(Sxyn, Hn, theta, fi, k, opt=None)

   Applies the Extended Maximum Entropy Principle (EMEP) method to reconstruct the directional
   spreading function based on the cross-power spectra of measured wave-induced responses.

   .. note::
       This implementation is based on the functions EMEP in the DIWASP toolbox and EMEM in the
       WAFO toolbox.

   :param Sxyn: Real and imaginary parts of the normalised cross-power spectral density:

                ``Sxyn(f,i) = Re(Smn(f)/(Szeta(f)*Wmn(f)))`` or the imaginary (``Im(.)``) counterpart.
   :type Sxyn: ndarray of shape (nf,m*m), where nf is the number of frequencies and m is the number of sensors
   :param Hn: Matrix of the real and imaginary parts of the normalised RAO products, in the same
              order of response pairs as for ``Sxyn``:

              ``Hn(theta,f,i) = Re(Phi_m(theta,f)*conj(Phi_n(theta,f))/Wmn(f))``
              or the imaginary (``Im(.)``) counterpart.
   :type Hn: ndarray of shape (nt,nf,m*m), where nt is the number of theta values
   :param theta: Vector of wave headings.

                 .. warning::
                     The wave heading *must be* in a wrapped format, corresponding to [0,360] deg.
                     For ship responses, those headings must be the *relative* wave headings.
   :type theta: ndarray of shape (nt,)
   :param fi: Frequency vector.
   :type fi: ndarray of shape (nf,)
   :param k: List of indices corresponding to frequencies where the wave power spectral density
             is substantially greater than zero.
   :type k: array_like
   :param opt: Optional parameters controlling the EMEM calculation. Available options are:

               - 'errortol' : float, default 0.0005
                   Error tolerance for convergence.
               - 'maxiter' : int, default 25
                   Maximum number of iterations for the Newton-Raphson method.
               - 'relax' : float, default 1
                   Relaxation parameter for controlling step shape in optimization.
               - 'maxcoef' : float, default 10000
                   Maximum value for coefficients to prevent divergence.
               - 'coefabstol' : float, default 0.01
                   Coefficient absolute tolerance for convergence.
               - 'minmodelorder' : int, default 1
                   Minimum model order for AIC evaluation.
               - 'maxmodelorder' : int, default M/2 + 1
                   Maximum model order for AIC evaluation.
               - 'diradjust' : float, default 0
                   Deviation term to adjust the wave directions to other direction conventions.

                   .. warning::
                       For ship responses, a value of :math:`-\pi/2` was necessary to use:
                       ``opt = {'diradjust': numpy.pi/2}``.

               - 'message' : {0,1}
                   Display messages during the calculation.
   :type opt: dict, optional

   :returns: **D** -- Estimated directional spreading distribution matrix of shape (nt, nf).
   :rtype: ndarray

   .. seealso::

      :obj:`norm_resp`
          Normalizes the response spectra and transfer functions.

      :obj:`norm_DSF`
          Normalizes the directional spreading function.

      :obj:`netsse.analys.buoy.Shannon_MEMII_Newton`
          Reconstructs the directional spreading function based on the first four Fourier coefficients of a directional wave spectrum.

   .. rubric:: References

   1. Hashimoto, N. (1997). "Analysis of the directional wave spectra from field data."
      Advances in Coastal and Ocean Engineering, Vol.3., pp.103-143.
   2. DIWASP, a directional wave spectra toolbox for MATLAB: User Manual.
      Research Report WP-1601-DJ (V1.1), Centre for Water Research, University of Western Australia.
   3. Brodtkorb, P.A., Johannesson, P., Lindgren, G., Rychlik, I., Rydén, J. and Sö, E. (2000).
      "WAFO - a Matlab toolbox for analysis of random waves and loads", Proc. 10th Int. Offshore and
      Polar Eng. Conf., Seattle, USA, Vol III, pp. 343-350.

   .. rubric:: Example

   >>> D = emep(Sxyn, Hn, theta, fi, k, opt=None)