netsse.simul.ship_resp.simul_ship_resp
======================================

.. py:function:: netsse.simul.ship_resp.simul_ship_resp(S2D, freq_wave, betas_wave, U=0, RespStr='Waves', max_threads=0, freq_TRF=[0], betas_TRF=0, TRF_amps=0, TRF_phases=0, NoTs=10, fs=10, T=30 * 60, Nomega=500, AddNoise=False, snr=20)

   Generates several time histories of the waves encountered by a ship and,
   optionally, the wave-induced vessel motion responses (heave, roll, pitch).

   A 2D wave spectrum must be given as input. If ship response is to be simulated
   too, then the wave-to-motion transfer functions of the vessel must also be
   provided.

   :param S2D: 2-D wave spectrum characterizing the sea state [m^2.s.s/rad].
   :type S2D: array_like of shape (Nf_wave,Nmu)
   :param freq_wave: Vector of wave frequencies [Hz] in which the wave spectrum is expressed.
   :type freq_wave: array_like of shape (Nf_wave,)
   :param betas_wave: Vector of the `relative` wave headings [deg] for the wave spectrum.

                      .. note::
                          The relative wave headings are defined as:
                          0 deg: following sea; 90 deg: beam waves from port side;
                          180 deg: head sea; 270 deg: beam waves from starboard side.
   :type betas_wave: array_like of shape (Nmu,)
   :param U: Vessel speed [m/s].
   :type U: float, default 0
   :param RespStr: Use ``'Motions'`` if vessel motions in waves are also to be simulated
                   (in addition to the waves). Otherwise, use ``'Waves'`` and only the wave
                   surface elevation will be simulated. The default is ``'Waves'``.
   :type RespStr: {'Waves','Motions'}, optional
   :param max_threads: Indicates to maximum number of threads to be used to parallelize the
                       execution.

                       .. attention::
                           A large value for ``max_threads`` should only be used if the program
                           is run on a high-performance computer. The code execution risks
                           crashing otherwise.
   :type max_threads: int, default 0
   :param freq_TRF: Vector of wave frequencies [Hz] in which the transfer functions are
                    expressed.
   :type freq_TRF: array_like of shape (Nf_TRF,), default [0,]
   :param betas_TRF: Vector of the relative wave headings [deg] indicating the direction of
                     propagation of the energy (relative to vessel heading) for the transfer
                     functions.
   :type betas_TRF: array_like of shape (Nbeta,), default 0
   :param TRF_amps: The amplitude of the transfer functions for heave, roll, and pitch,
                    respectively. The default is 0.
   :type TRF_amps: array_like of shape (Nf_TRF, Nbeta, 3), optional
   :param TRF_phases: The phase of the transfer functions for heave, roll, and pitch,
                      respectively. The default is 0.
   :type TRF_phases: array_like of shape (Nf_TRF, Nbeta), optional
   :param NoTs: Number of time series to be generated.
   :type NoTs: int, default 10
   :param fs: Sampling frequency [Hz] for the generated time histories.
   :type fs: float, default 10
   :param T: Duration [s] of the time histories. The default is 30*60 = 1800 s.
   :type T: float, optional
   :param Nomega: Number of wave components used for each direction to generate the time
                  histories.
   :type Nomega: int, default 500

   :returns: * **time** (*array_like of shape (T*fs,).*) -- Vector of time [s].
             * **wavet** (*array_like of shape (NoTs,T*fs).*) -- Wave elevation [m] time series.
             * **heavet, rollt, pitcht** (*array_like of shape (NoTs,T*fs).*) -- Heave, roll and pitch time series.

               .. note::
                   ``heavet``, ``rollt``, ``pitcht`` are returned if and only if
                   RespStr = ``'Motions'``

   :param AddNoise: A boolean that indicates whether random noise (Gaussian white noise)
                    is added to be added the motion time histories.
   :type AddNoise: bool, default False
   :param snr: The signal-to-noise ratio to be used for addition of noise.
   :type snr: float, default 20

   .. seealso::

      :obj:`sum_components`
          Performs the summation of the sine components to simulate in the time domain the encountered wave elevation or the wave-induced responses on a ship.

   .. rubric:: Example

   >>> # Wave simulations
   >>> time, wavet =
   ...     simul_ship_resp(S2D,freq_wave,betas_wave,U,'Waves',0,NoTs=10,fs=10,T=30*60,
   ...                     Nomega=500,AddNoise=True,snr=20)
   >>> # Motion simulations
   >>> time, wavet, heavet, rollt, pitcht =
   ...     simul_ship_resp(S2D,freq_wave,betas_wave,U,'Motions',0,freq_TRF,betas_TRF,
   ...                     TRF_amps,TRF_phases,NoTs,fs,T,Nomega,AddNoise=True,snr=20)