ucla-geotech-tools 1.0.2

A collection of software tools developed by the UCLA geotechnical group

auto_fchp

Return the high-pass corner frequency value that stabilizes the displacement of a ground motion record.

The high-pass corner frequency, fchp, is selected to satisfy two objectives:
    1. A polynomial is fit to the filtered displacement record, and the amplitude of the polynomial fit
    divided by the amplitude of the filtered displacement record is within a tolerance of a specified target.
    2. The amplitude of the initial portion of the displacement record before the p-wave arrival divided by
    the amplitude of the filtered displacement record is within a tolerance of a specified target.

The value of fchp is computed numerically using the Scipy package optimize.ridder(). Two initial values
of fchp are provided that bracket the root, and the Scipy package solves for the root that minimizes the
objective function. The tolerance is on the value of fchp (i.e., xtol in optimize.ridder)

A value of fchp is obtained first to satisfy objective 1. Objective 2 is optional, and if it is applied,
the value of fchp from objective 1 is checked against objective 2. If the residual from objective 2 is
less than or equal to zero, fchp is set equal to the value from objective 1. Otherwise, iterations are
performed to satisfy objective 2.

Installation

pip install ucla_geotech_tools.auto_fchp

Functions

get_fchp_sp(dt, acc, **kwargs)
"""Args:
        dt (float): time step in seconds
        acc (numpy array, dtype=float): acceleration array in L/s/s, where L is length (e.g., meters)

    Keyword Args:
        target: desired ratio of polynomial fit amplitude to displacement amplitude (default=0.02)
        tol: tolerance for fchp (default=0.001)
        poly_order: order of polynomial to fit to filtered displacement record (default=6)
        maxiter: maximum number of iterations (default=30)
        fchp_min: minimum frequency in Hz to consider for fchp (default=0.001)
        fchp_max: maximum frequency in Hz to consider for fchp (default=0.5)
        tukey_alpha: alpha parameter for scipy.signal.windows.tukey (default=0.05)
        apply_disp_ratio: flag to indicate whether to apply objective 2 (default=0)
        disp_ratio_time: duration in seconds of the initial portion of the record before the p-wave arrival (default=30)
        disp_ratio_target: target ratio of amplitude of initial portion of displacement record to amplitude of displacement record
"""
get_residual1(fchp, *args):
    """Return the residual defined as disp_fit/disp_filt - target.

    Args:
        fchp = High-pass corner frequency
        Fdisp = Numpy array containing Fourier coefficients of displacement record
        time = Numpy array containing time values
        poly_order = Order of polynomial to fit to filtered displacement
        target = Desired ratio of polynomial fit amplitude to displacement signal amplitude
        freq = Numpy array containing frequency values

    Computed variables:
        filt = Coefficients of 5th order Butterworth filter
        Fdisp_filt = Numpy array containing Fourier coefficients of filtered displacement record
        disp_filt = Numpy array containing filtered displacement record
        coef = Coefficients of polynomial fit to displacement record
        disp_fit = Numpy array containing polynomial fit ordinates at each time
    """


get_residual2(fchp, *args):
    """Return the residual defined as disp_init/disp - target.

    Args:
        fchp = High-pass corner frequency
        Fdisp = Numpy array containing Fourier coefficients of displacement record
        time = Numpy array containing time values
        disp_time = Duration of initial portion of record before p-wave arrival
        disp_target = Desired ratio of amplitude of initial portion of displacement record to amplitude of displacement record
        freq = Numpy array containing frequency values

    Computed variables:
        filt = Coefficients of 5th order Butterworth filter
        Fdisp_filt = Numpy array containing Fourier coefficients of filtered displacement record
        disp_filt = Numpy array containing filtered displacement record
    """