API Reference

This section provides detailed documentation for all modules, classes, and functions in the time_domain_modal_estimation package.

• Complex Exponential Algorithm Module
  • build_toeplitz_matrix()
  • solve_polynomial_coefficients()
  • find_system_poles()
  • poles_to_modal_frequencies()
  • build_vandermonde_matrix()
  • solve_mode_shapes()
  • complex_exponential_algorithm()
  • reconstruct_response()
  • Main Function
  • Helper Functions
• Eigensystem Realization Algorithm Module
  • build_hankel_matrix()
  • eigensystem_realization_algorithm()
  • generate_impulse_response()
  • stabilization_diagram()
  • Main Function
  • Helper Functions

Main Module

Time Domain Modal Estimation

A Python package for extracting modal parameters from time-domain response data. Implements techniques such as the Complex Exponential Algorithm (CEA) and Eigensystem Realization Algorithm (ERA).

time_domain_modal_estimation.complex_exponential_algorithm(y, dt, n_modes, t_start=None)

Complete Complex Exponential Algorithm (CEA) implementation.

Parameters:

• y (np.ndarray) – Response time series data

• dt (float) – Time step (sampling interval)

• n_modes (int) – Number of modes to estimate

• t_start (float, optional) – Starting time (default: 0)

Returns:

results – Dictionary containing: - ‘frequencies’: Natural frequencies (Hz) - ‘damping_ratios’: Damping ratios (fraction of critical) - ‘mode_shapes’: Mode shape coefficients - ‘poles’: System poles z_k - ‘lambda’: Modal frequencies λ_k (complex)

Return type:

dict

Notes

Implements the CEA algorithm from equations 7-13: 1. Build Toeplitz matrix (eq 7) 2. Solve for polynomial coefficients (eq 11) 3. Find poles (eq 8) 4. Convert to modal frequencies (eq 9-10) 5. Build Λ matrix (eq 12) 6. Solve for mode shapes (eq 13)

References

Fahey, S. O’F., & Pratt, J. (1998). Time domain modal estimation techniques. Experimental Techniques, 22(6), 45-49.

time_domain_modal_estimation.build_toeplitz_matrix(y, n)

Build Toeplitz matrix from response data (Equation 7).

Parameters:

• y (np.ndarray) – Response time series data of length N

• n (int) – Number of modes to estimate (order of the system)

Return type:

Tuple[ndarray, ndarray]

Returns:

• Y (np.ndarray) – Toeplitz matrix of shape (N-2n, 2n)

• y_target (np.ndarray) – Target vector of length (N-2n)

Notes

From eq (7), the Toeplitz matrix structure is: Y = [y1 y2 … y2n+1 ]

[y2 y3 … y2n+2 ] [… … … … ] [yN-2n yN-2n+1 … yN-1 ]

And we solve: Y * α = -yN

time_domain_modal_estimation.solve_polynomial_coefficients(Y, y_target)

Solve for polynomial coefficients using least squares (Equation 11).

Parameters:

• Y (np.ndarray) – Toeplitz matrix

• y_target (np.ndarray) – Target vector

Returns:

alpha – Polynomial coefficients [α0, α1, …, α_{2n-1}]

Return type:

np.ndarray

time_domain_modal_estimation.find_system_poles(alpha)

Find system poles from characteristic polynomial (Equation 8).

Parameters:

alpha (np.ndarray) – Polynomial coefficients [α0, α1, …, α_{2n-1}]

Returns:

z_k – System poles (roots of characteristic polynomial)

Return type:

np.ndarray

Notes

From eq (8): Π(z - z_k) = 0 We solve: z^{2n} + α_{2n-1}*z^{2n-1} + … + α_1*z + α_0 = 0

time_domain_modal_estimation.poles_to_modal_frequencies(z_k, dt)

Convert poles to modal frequencies (Equations 9 and 10).

Parameters:

• z_k (np.ndarray) – System poles

• dt (float) – Time step (sampling interval)

Returns:

lambda_k – Modal frequencies (complex, with real = damping, imag = frequency)

Return type:

np.ndarray

Notes

From eq (9): λ_k = (1/(2π*Δt)) * ln(z_k) [in Hz] From eq (10): λ_k = (1/Δt) * ln(z_k) [in rad/s]

We use eq (10) for rad/s convention.

time_domain_modal_estimation.build_vandermonde_matrix(lambda_k, t)

Build Vandermonde-like matrix Λ (Equation 12).

Parameters:

• lambda_k (np.ndarray) – Modal frequencies [λ_1, λ_2, …, λ_n]

• t (np.ndarray) – Time vector

Returns:

Lambda – Matrix with exp[λ_k * t_j] entries

Return type:

np.ndarray

Notes

From eq (12): Λ_{1,N} = [exp[λ_1*t_1] exp[λ_1*t_2] … exp[λ_1*t_N]]

[exp[λ_2*t_1] exp[λ_2*t_2] … exp[λ_2*t_N]] [ … … … … ] [exp[λ_n*t_1] exp[λ_n*t_2] … exp[λ_n*t_N]]

time_domain_modal_estimation.solve_mode_shapes(Lambda, y)

Solve for mode shapes/participation factors (Equation 13).

Parameters:

• Lambda (np.ndarray) – Vandermonde matrix of shape (n, N)

• y (np.ndarray) – Response data of length N

Returns:

A – Mode shape coefficients/participation factors

Return type:

np.ndarray

Notes

From eq (13): [A_1, A_2, …, A_n]^T = Λ_{1,N}^{-1} * y

The response is modeled as: y = Λ^T * A Where Lambda is (n x N), A is (n,), and y is (N,)

Solving: A = (Λ * Λ^T)^{-1} * Λ * y Or using pseudo-inverse: A = pinv(Λ^T) * y

time_domain_modal_estimation.reconstruct_response(lambda_k, A, t)

Reconstruct the response from modal parameters.

Parameters:

• lambda_k (np.ndarray) – Modal frequencies

• A (np.ndarray) – Mode shape coefficients

• t (np.ndarray) – Time vector

Returns:

y_reconstructed – Reconstructed response

Return type:

np.ndarray

Notes

Response is: y = Λ^T @ A = Σ A_k * exp(λ_k * t)

time_domain_modal_estimation.eigensystem_realization_algorithm(Y, dt, n_modes, r=None, s=None)

Complete Eigensystem Realization Algorithm (ERA) implementation.

Parameters:

• Y (np.ndarray) – Impulse response data of shape (p, N) where p is number of outputs and N is number of time steps

• dt (float) – Time step (sampling interval)

• n_modes (int) – Number of modes to extract (model order)

• r (int, optional) – Number of block rows in Hankel matrix (default: N//2)

• s (int, optional) – Number of block columns in Hankel matrix (default: N//2)

Returns:

results – Dictionary containing: - ‘frequencies’: Natural frequencies (Hz) - ‘damping_ratios’: Damping ratios (fraction of critical) - ‘mode_shapes’: Mode shapes (complex) - ‘A’: State matrix - ‘B’: Input matrix - ‘C’: Output matrix - ‘eigenvalues’: System eigenvalues - ‘eigenvectors’: System eigenvectors - ‘singular_values’: Singular values from SVD

Return type:

dict

Notes

Implements the ERA algorithm from equations 27-35: 1. Build Hankel matrices H(0) and H(1) (eq 29-30) 2. SVD of H(0) (eq 31) 3. Construct reduced-order system matrices (eq 32-33) 4. Extract eigenvalues and eigenvectors (eq 34) 5. Compute mode shapes, poles, and amplitudes (eq 35)

References

Fahey, S. O’F., & Pratt, J. (1998). Time domain modal estimation techniques. Experimental Techniques, 22(6), 45-49.

Juang, J. N., & Pappa, R. S. (1985). An eigensystem realization algorithm. Journal of guidance, control, and dynamics, 8(5), 620-627.

time_domain_modal_estimation.build_hankel_matrix(Y, r, s, block_rows=None)

Build generalized Hankel matrix from impulse response data (Equation 29).

Parameters:

• Y (np.ndarray) – Impulse response matrix of shape (p, N) where p is number of outputs and N is number of time steps

• r (int) – Number of block rows

• s (int) – Number of block columns

• block_rows (int, optional) – Explicit number of block rows (if different from r)

Returns:

H – Hankel matrix of shape (p*r, s)

Return type:

np.ndarray

Notes

From eq (29), the Hankel matrix H_r(k-1) is: H(k-1) = [Y(k) Y(k+1) … Y(k+s-1) ]

[Y(k+1) Y(k+2) … Y(k+s) ] [ … … … … ] [Y(k+r-1) Y(k+r) … Y(k+s+r-2) ]

Each block Y(i) can be a matrix itself for multiple outputs.

time_domain_modal_estimation.generate_impulse_response(frequencies, damping_ratios, mode_shapes, t, n_outputs=1)

Generate synthetic impulse response data for testing ERA.

Parameters:

• frequencies (list) – Natural frequencies in Hz

• damping_ratios (list) – Damping ratios (fraction of critical)

• mode_shapes (list) – Mode shape amplitudes for each output

• t (np.ndarray) – Time vector

• n_outputs (int) – Number of output channels

Returns:

Y – Impulse response matrix of shape (n_outputs, len(t))

Return type:

np.ndarray

time_domain_modal_estimation.stabilization_diagram(Y, dt, max_order, r=None, s=None, freq_tol=0.01, damp_tol=0.05)

Generate stabilization diagram by running ERA at multiple model orders.

Parameters:

• Y (np.ndarray) – Impulse response data

• dt (float) – Time step

• max_order (int) – Maximum model order to test

• r (int, optional) – Hankel matrix block rows

• s (int, optional) – Hankel matrix block columns

• freq_tol (float) – Frequency tolerance for stability (default: 1%)

• damp_tol (float) – Damping tolerance for stability (default: 5%)

Returns:

diagram – Contains ‘orders’, ‘frequencies’, ‘damping_ratios’, ‘stability’

Return type:

dict