netsse.analys.emep ================== .. py:module:: netsse.analys.emep .. autoapi-nested-parse:: Python implementation of the **EMEP** algorithm, used for analyzing directional wave spectra from field data. .. dropdown:: Copyright (C) 2023-2026 Technical University of Denmark, R.E.G. Mounet :color: primary :icon: law *This code is part of the NetSSE software.* NetSSE is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. NetSSE is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/. To credit the author, users are encouraged to use below reference: .. code-block:: text Mounet, R. E. G., & Nielsen, U. D. NetSSE: An open-source Python package for network-based sea state estimation from ships, buoys, and other observation platforms (version 2.2). Technical University of Denmark, GitLab. February 2026. https://doi.org/10.11583/DTU.26379811. *Last updated on 20-02-2026 by R.E.G. Mounet* Functions --------- .. autoapisummary:: netsse.analys.emep.emep netsse.analys.emep.norm_DSF netsse.analys.emep.norm_resp Module Contents --------------- .. py:function:: 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:: :py:obj:`norm_resp` Normalizes the response spectra and transfer functions. :py:obj:`norm_DSF` Normalizes the directional spreading function. :py: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) .. py:function:: norm_DSF(D, theta) Normalizes the directional spreading function. The function ensures that the output has a unit integral over wave directions. :param D: Directional spreading function. :type D: array_like of shape (nt,nf) :param theta: Vector of wave directions. :type theta: array_like of shape (nt,) :returns: **Dn** -- Normalized spreading function. :rtype: array_like of shape (nt,nf) .. rubric:: Example >>> Dn = norm_DSF(D, theta) .. py:function:: norm_resp(Rxy_ReIm, TRF, S1D, f, mn=None, ReIm=None, Na=None, axy=None) Normalizes the response spectra and transfer functions for application of the EMEP method. .. note:: The normalization factors are found in Bendat & Piersol (2010). :param Rxy_ReIm: Response spectra as a function of frequency ``f``, considering `Nxy` pairs of responses. :type Rxy_ReIm: array_like of shape (Nfreq,Nxy) :param TRF: Transfer functions for `Nresp` different responses, as functions of wave direction and frequency ``f``. :type TRF: Multidimensional array of shape (Nresp,Ntheta,Nfreq) :param S1D: 1-D wave spectrum, as a function of frequency ``f``. :type S1D: array_like of shape (Nfreq,) :param f: Vector of wave frequencies. :type f: array_like of shape (Nfreq,) :param mn: Definition of the considered responses in ``Rxy_ReIm``. Elements in ``mn`` correspond to the indices of the pairs of responses along the first dimension of ``TRF``, i.e., from 0 to `Nresp`-1. Default is ``None``; in that case, the response pairs are ordered in the following order (illustrated for `Nresp = 3`): ``Rxy_ReIm = [Re(R00),Re(R11),Re(R22),Re(R01),Re(R02),Re(R12),Im(R01),Im(R02),Im(R12)]`` ``mn = [[0, 0], [1, 1], [2, 2], [0, 1], [0, 2], [1, 2], [0, 1], [0, 2], [1, 2]]`` :type mn: array_like of shape (Nxy,2), optional :param ReIm: Vector indicating whether the real part (``'R'``) or imaginary part (``'I'``) of the response cross-spectrum is considered in ``Rxy_ReIm``. Default is ``None``; in that case, the real and imaginary parts of the response pairs are ordered in the order shown above, thus: ``ReIm = ['R', 'R', 'R', 'R', 'R', 'R', 'I', 'I', 'I']`` :type ReIm: array_like of shape (Nxy,) or (Nxy,1), optional :param Na: Number of the ensembled average for computation of the response spectra variance. Default is ``None``, for which case ``Na = 1``. :type Na: str, or array_like of shape (Nxy,), optional :param axy: Additional weights (must be positive). Any weight greater than zero increases the importance given to a corresponding pair of responses in the EMEP method. Default is ``None``, for which case the weights are set to zero. :type axy: array_like of shape (Nxy,), optional :returns: * **Rxy_ReIm_n** (*array_like of shape (Nfreq,Nxy)*) -- Normalized version of the response spectra. * **Hn** (*array_like of shape (Ntheta,Nfreq,Nxy)*) -- Normalized version of the real and imaginary parts of the product of the transfer functions for pairs of responses. The real and imaginary parts for the pairs of responses are output in the same order as ``Rxy_ReIm``. .. seealso:: :py:obj:`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 Bendat, J. S., & Piersol, A. G. (2010). Random Data: Analysis and Measurement Procedures. In Measurement Science and Technology (Vol. 11, Issue 12). Wiley. https://doi.org/10.1002/9781118032428 .. rubric:: Example >>> Rxy_ReIm_n, Hn = norm_resp(Rxy_ReIm,TRF,S1D,f,mn=None,ReIm=None,Na=None,axy=None)