netsse.analys.buoy.Shannon_MEMII_Newton
=======================================

.. py:function:: netsse.analys.buoy.Shannon_MEMII_Newton(a1, a2, b1, b2, freq, theta, maxiter, tol_error, miniter=50, approx=False)

   Reconstructs the directional spreading function based on the first four Fourier
   coefficients of a directional wave spectrum.

   The function implements the Maximum Entropy Principle (Hashimoto, 1997), either via
   running the Newton local linearisation method or following the approximation method
   by Kim et al. (1994).

   :param a1: First four Fourier coefficients of the directional wave spectrum.
   :type a1: array_like of shape (Nf,)
   :param a2: First four Fourier coefficients of the directional wave spectrum.
   :type a2: array_like of shape (Nf,)
   :param b1: First four Fourier coefficients of the directional wave spectrum.
   :type b1: array_like of shape (Nf,)
   :param b2: First four Fourier coefficients of the directional wave spectrum.
   :type b2: array_like of shape (Nf,)
   :param freq: Vector of (discretized) wave frequencies [Hz].
   :type freq: array_like of shape (Nf,)
   :param theta: Vector of wave headings [deg].
   :type theta: array_like of shape (Ntheta,)
   :param maxiter: Maximum number of iterations.
   :type maxiter: int
   :param tol_error: Tolerance in the relative error.
   :type tol_error: float
   :param miniter: Minimum number of iterations.
   :type miniter: int, default 50
   :param approx: Boolean which indicates whether the approximation method should be
                  used for finding the Lagrangian multipliers.
   :type approx: bool, default False

   :returns: * **D** (*array_like of shape (Nf,Ntheta)*) -- Directional spreading function.
             * **flag** (*array_like of shape (Nf,)*) -- Boolean flag indicating unconverged frequencies
               (``flag = 0`` for unconverged)
             * **L1, L2, L3, L4** (*array_like of shape (Nf,)*) -- Optimized Lagrange multipliers.

   .. seealso::

      :obj:`cross_spec2Fourier_coef`
          Computes the Fourier coefficients from the cross-spectra of a heave-East-North wave buoy.

      :obj:`netsse.analys.emep.emep`
          Extended Maximum Entropy Principle (EMEP) method for reconstructing the directional spreading function based on the cross-power spectra of measured wave-induced responses.

   .. rubric:: References

   1. Benoit, M., Frigaard, P., & Schäffer, H. A. (1997). *Analysing Multidirectional
      Wave Spectra: A tentative classification of available methods*. Proceedings of
      the 27th IAHR Congress, San Francisco, CA, USA (pp. 131–158).
      Canadian Government Publishing.
   2. Hashimoto, N. (1997). *Analysis of the Directional Wave Spectrum from Field
      Data*. Advances in coastal and ocean engineering. 3:103-44.
   3. Kim, T., Lin, L.-H., & Wang, H. (1994). *Application of Maximum Entropy Method
      to the Real Sea Data*. In Coastal Engineering (pp. 340–355).

   .. rubric:: Example

   >>> D, flag, L1, L2, L3, L4 =
   ...     Shannon_MEMII_Newton(a1,a2,b1,b2,freq,theta,maxiter,tol_error,miniter=50,False)