netsse.analys.sawb.genspecres
=============================

.. py:function:: netsse.analys.sawb.genspecres(Rxy, Hxy, freq, beta, opt=None)

   Computes an estimate of the point wave spectrum using a generalised version of the
   spectral-residual method from Brodtkorb et al. (2017) and Nielsen et al. (2018).

   The cross-spectra from any number of responses are used as input.
   Using the motion transfer functions of the vessel, the wave spectrum is estimated
   through iteration.

   .. warning::
       Long-crested wave conditions are assumed in this sea state estimation method. The present
       version of the algorithm does not allow to distinguish waves coming from port and starboard
       sides.


   :param Rxy: The response cross-spectra.

               .. note::
                   The phase of the complex-valued response spectra is not important in this
                   implementation, and the amplitude (absolute value) alone can be provided without this affecting the estimation results.
   :type Rxy: array_like of shape (Nresp,Nfreq)
   :param Hxy: The RAO products for the ship, provided in the same order of response pairs as for the
               response cross-spectra `Rxy`.

               .. note::
                   The phase of the complex-valued transfer functions is not important in this
                   implementation, and the amplitude alone can be provided without this affecting
                   the estimation results.
   :type Hxy: array_like of shape (Nresp,Nbeta,Nfreq)
   :param freq: The frequencies of the response spectra and the transfer functions (should
                match).
   :type freq: array_like of shape (Nfreq,)
   :param beta: The discretized heading angles [deg] at which the transfer functions
                are known.

                .. tip::
                    For a port-starboard symmetric ship, directions from 0 deg to 180
                    deg only can be considered to lower the computational cost.
   :type beta: array_like of shape (Nbeta,)
   :param opt: Optional parameters controlling the SSE calculation. Available options are:

               - 'maxiter' : int, or array_like of shape (`Nresp`,)
                   Maximum number of iterations (default: 50).
               - 'tolCoef' : float, or array_like of shape (`Nresp`,)
                   Tolerance coefficient (default: 0.1).
               - 'gainFact' : float, or array_like of shape (`Nresp`,)
                   Gain factor, as a fraction of the maximum gain value (default: 0.5).
               - 'weights' : float, or array_like of shape (`Nresp`,)
                   Weights given to each response in the calculation of the final spectrum estimate
                   (default: equal weight for each response, i.e. wij = 1/`Nresp`).

               .. note::
                   `array_like` entries of the dictionary can be input for a response-specific option.
                   In such case, the array elements must be provided in the same order as for the response
                   spectra.
   :type opt: dict, optional

   :returns: * **S_wave** (*array_like of shape (Nfreq,)*) -- The estimated 1-D wave spectrum.
             * **beta_est** (*float*) -- The estimated relative wave heading [degrees].
             * **num_it** (*array_like of shape (Nresp,)*) -- The average number of iterations used per heading angle, for the individual
               response pairs.

   .. rubric:: References

   1. Brodtkorb, A. H., Nielsen, U. D., & Sørensen, A. J. (2018). Online wave estimation
      using vessel motion measurements. IFAC-PapersOnLine, 51(29), 244–249.
      https://doi.org/10.1016/j.ifacol.2018.09.510
   2. Brodtkorb, A. H., Nielsen, U. D., & Sørensen, A. J. (2018). Sea state estimation using
      vessel response in dynamic positioning. Applied Ocean Research, 70, 76–86.
      https://doi.org/10.1016/j.apor.2017.09.005
   3. Nielsen, U. D., Brodtkorb, A. H., & Sørensen, A. J. (2018). A brute-force spectral approach
      for wave estimation using measured vessel motions. Marine Structures, 60, 101–121.
      https://doi.org/10.1016/j.marstruc.2018.03.011
   4. Brodtkorb, A. H., & Nielsen, U. D. (2023). Automatic sea state estimation with online trust
      measure based on ship response measurements. Control Engineering Practice, 130.
      https://doi.org/10.1016/j.conengprac.2022.105375

   .. rubric:: Example

   >>> S_wave, beta_est, num_it = genspecres(Rxy, Hxy, freq, beta, opt=None)