amplify_motion#

PySeismoSoil.helper_site_response.amplify_motion(input_motion: ndarray, transfer_function_single_sided: tuple[numpy.ndarray, numpy.ndarray], taper: bool = False, extrap_tf: bool = True, deconv: bool = False, show_fig: bool = False, dpi: int = 100, return_fig_obj: bool = False) → tuple[numpy.ndarray, matplotlib.figure.Figure | None, matplotlib.axes._axes.Axes | None][source]#

Amplify (or de-amplify) ground motions in the frequency domain. The mathematical process behind this function is as follows:

  1. INPUT = fft(input)

  2. OUTPUT = INPUT * TRANS_FUNC

  3. output = ifft(OUTPUT)

Parameters:

  • input_motion (np.ndarray) – Input ground motion to be amplified. 2D numpy array of two columns.

  • transfer_function_single_sided (tuple[np.ndarray, np.ndarray]) –

    Complex-valued transfer function in frequency domain. It should be a two-element tuple, whose 0-th element is the frequency array, and the last element can be one of two options:

    1. A complex-valued transformation, which should be a 1D complex numpy array

    2. A tuple of (amplitude, phase) which represents the complex numbers. amplitude and phase both need to be 1D arrays and real-valued.

    The transfer function only needs to be “single-sided” (see note below.)

  • taper (bool) – Whether to taper the input acceleration (using Tukey taper).

  • extrap_tf (bool) – Whether to extrapolate the transfer function if its frequency range does not reach the frequency range implied by the input motion.

  • deconv (bool) – If False, a regular amplification is performed; otherwise, the transfer function is “deducted” from the input motion (“deconvolution”).

  • show_fig (bool) – Whether to show an illustration of how the calculation is carried out.

  • dpi (int) – Desired DPI for the figures; only effective when show_fig is True.

  • return_fig_obj (bool) – Whether to return figure and axis objects to the caller.

Returns:

  • response (np.ndarray) – The resultant ground motion in time domain. In the same format as input_motion.

  • fig (Figure | None) – The figure object being created or being passed into this function.

  • ax (Axes | None) – The axes object being created or being passed into this function.

Raises:

  • TypeError – The type/value of the input parameter is incorrect

  • ValueError – Incorrect frequency range

Note

“Single sided”:

For example, the sampling time interval of input_motion is 0.01 sec, then the Nyquist frequency is 50 Hz. Therefore, the transfer function needs to contain information at least up to the Nyquist frequency, i.e., at least 0-50 Hz, and anything above 50 Hz will not affect the input motion at all.