netsse.analys.dsa.trans_2Dmat_DSA
=================================

.. py:function:: netsse.analys.dsa.trans_2Dmat_DSA(freq_in, beta, U, freq_out=None, unit_freq='rad/s', unit_beta='deg', conv='from', max_freq=None, nu23=(1 + 2**(1 / 2)) / 2, transform='abs2enc', weighting='uniform', highfreq_matching=True)

   Computes the transformation matrices for applying the Doppler shift approximation (DSA) at the given forward speed and for the given frequency and direction discretizations.

   .. note::
       This implementation uses the derivations presented in Mounet et al. (2025a,b).

   :param freq_in: Input frequencies.
   :type freq_in: array_like of shape (NfreqIN,)
   :param beta: Relative wave heading angles.
   :type beta: array_like of shape (Nbeta,)
   :param U: Forward speed of the observer [m/s].
   :type U: float
   :param freq_out: Output frequencies. If None, it is set to freq_in.
   :type freq_out: array_like of shape (NfreqOUT), optional
   :param unit_freq: Unit of the frequencies:

                     - 'rad/s' :
                         The variables ``freq_in`` and ``freq_out`` denote the angular frequencies in radians
                         per second. The default is 'rad/s'.
                     - 'Hz' :
                         Frequencies are in Hertz.
   :type unit_freq: {'rad/s','Hz'}, optional
   :param unit_beta: Unit of the relative wave heading angles ``beta`` ('deg' or 'rad'). Default is 'deg'.
   :type unit_beta: {'deg','rad'}, optional
   :param conv: The convention that is used to express the direction ``beta`` of wave spectrum:

                - 'from' :
                    The naval architecture convention, indicating where the waves are COMING FROM.
                - 'to' :
                    The oceanographic convention, indicating where the waves are GOING TO.
                    The default is "from" direction.
   :type conv: {'from','to'}, optional
   :param max_freq: Cut-off frequency. If None, it is set to the maximum of ``freq_in``.
   :type max_freq: float, optional
   :param nu23: Threshold parameter for the DSA. Default is :math:`(1+\sqrt{2})/2`.
   :type nu23: float, optional
   :param transform: Type of transformation ('abs2enc' or 'enc2abs'). Default is 'abs2enc'.
   :type transform: str, optional
   :param weighting: Weighting method to use:

                     - 'uniform' :
                         Equal weight is given to all frequencies in the range [0,om0m] in the cost function.
                         This is the default option. It is introduced in Mounet et al. (2025a).
                     - 'tripvalpb' :
                         Same as ``'uniform'`` weighting, but the ``om0m`` is set to a value of
                         :math:`(1+\sqrt{2})/(2\tau)` when :math:`\nu>\nu_{23}`. This ensures the DSA features
                         an optimal accuracy in the range of frequencies where the triple-value problem occurs.
                         This idea is introduced in Mounet et al. (2025b).
                     - 'lowfreq' :
                         A decreasing (affine) weighting function is applied to frequencies in the range
                         [0,om0m], such that low frequencies are given more importance in the cost function.
                         This option is not recommended for general use.
   :type weighting: {'uniform','tripvalpb','lowfreq'}, optional
   :param highfreq_matching: If ``True``, the convex form of the DSA is overriden to become exact beyond the point where
                             the DSA and the exact Doppler shift intersect each other in Region III of the mapping.
                             If ``False``, the DSA is kept unchanged otherwise. Default is True.
   :type highfreq_matching: bool, optional

   :returns: * **Omega_in_fromout** (*ndarray of shape (NfreqOUT,Nbeta)*) -- Approximated input frequencies as a function of the target frequencies and wave directions.
             * **C** (*ndarray of shape (NfreqOUT*Nbeta,NfreqIN*Nbeta)*) -- Linear interpolation matrix.
             * **D_wave** (*ndarray of shape (NfreqOUT*Nbeta,NfreqOUT*Nbeta)*) -- 2D-to-2D transformation matrix for wave spectra.
             * **S** (*ndarray of shape (NfreqOUT,NfreqOUT*Nbeta)*) -- 2D-to-1D summation matrix.

   .. seealso::

      :py:obj:`polynom_DSA`
          Computes the polynomial approximation of the Doppler Shift.

   .. rubric:: References

   1. Mounet, R.E.G., Nielsen, U.D., and Takami, T. (2025a). "Doppler Shift Approximation in
      Seakeeping Problems: A New Formulation for Ships Advancing at Any Forward Speed." In:
      Proceedings of the 16th International Symposium on Practical Design of Ships and Other
      Floating Structures (PRADS 2025), Ann Arbor, MI, USA. (Accepted).
   2. Mounet, R.E.G., Nielsen, U.D., and Takami, T. (2025b). "Approximating the Doppler Shift in
      Sea-Wave Spectra Observed from an Advancing Floating Platform." Applied Mathematical
      Modelling. (Submitted).

   .. rubric:: Example

   >>> _, C, D, S = trans_2Dmat_DSA(
   ...     freq_in, beta, U, freq_out, unit_freq='Hz', unit_beta='deg', conv='from', max_freq=0.3,
   ...     nu23=2, transform='abs2enc', weighting="uniform", highfreq_matching=True)