netsse.analys.sawb.specres
==========================

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

   Computes an estimate of the sea state using the spectral-residual method
   from Brodtkorb et al. (2017) and Nielsen et al. (2018).

   The heave, roll, and pitch response cross-spectra 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.

   .. note::
       This Python code is based on a MATLAB/Simulink implementation by
       Astrid H. Brodtkorb.

   :param Rxy: The complex-valued response spectra, given as in:
               ``Rxy = [heaveheave, rollroll, pitchpitch, heaveroll, heavepitch, rollpitch]``.
   :type Rxy: array_like of shape (Nfreq,6)
   :param TRF: The transfer functions of the ship, in heave, roll, and pitch, concatenated
               along the second axis as in:
               ``TRF = [heave_TF,roll_TF,pitch_TF]``

               .. note::
                   The phase of the complex transfer functions is not important in this
                   implementation, and the amplitude alone can be provided without this affecting
                   the estimation results.
   :type TRF: array_like of shape (Nfreq,3*Nbeta)
   :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 (6,)
                   Maximum number of iterations (default: 50).
               - 'tolCoef' : float, or array_like of shape (6,)
                   Tolerance coefficient (default: 0.1).
               - 'gainFact' : float, or array_like of shape (6,)
                   Gain factor, as a fraction of the maximum gain value (default: 0.5).
               - 'weights' : float, or array_like of shape (6,)
                   Weights given to each response in the calculation of the final spectrum estimate
                   (default: equal weight for each response, i.e. wij = 1/6).

               .. 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 (6,)*) -- The average number of iterations used per heading angle, for the individual
               response pairs organised as:
               ``num_it = [it3, it4, it5, it34, it35, it45]``.

   .. 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 = specres(Rxy, TRF, freq, beta, opt=None)