mec-vibrations-calcs 0.1.0

Vibration Analysis Tools

Mechanical Vibration Tools

Introduction

The idea for this project originated in a Machine Dynamics course, where the goal was to visualize the frequency-response functions of single-degree-of-freedom systems. Having already implemented several utility routines, I decided to package and share them.

This library is organized into two main modules—one for single-degree-of-freedom (1-DOF) systems and another for multi-degree-of-freedom (n-DOF) systems. It ranges from simple functions such as:

• get_natural_frequency(mass, stiffness): accepts two parameters and returns the natural frequency of a 1-DOF system,

to more advanced routines like:

• get_natural_modes_of_vibration(mode_shapes, natural_frequencies, coefficients, phases): accepts four parameters and returns the time-dependent contribution of each mode in an n-DOF system’s response.

This README will be structured to first explain the two main modules: n_dof_calc.py and one_dof_calc.py, and finally showcase some possibilities using the Matplotlib library.

---

one_dof_calc.py

This module provides a collection of functions to analyze the dynamic behavior of single-degree-of-freedom (1-DOF) systems in vibration mechanics.
It includes methods for calculating natural frequencies, damping ratios, frequency response functions, and time-domain responses.

---

Functions Overview

Frequency and Time Properties

• get_natural_frequency(keq, meq) → Returns the natural frequency of the system.
• get_period(natural_frequency) → Returns the natural period of vibration.

Damping and Resonance

• get_dumping_ratio(ceq, meq, w_n) → Computes the damping ratio.
• get_log_decrement(dumping_ratio) → Returns the logarithmic decrement.
• get_resonance_frequency(w_natural, epsilon) → Computes the resonance frequency.

Frequency Response Functions

• get_recept(meq, ceq, keq, omega) → Returns the receptance.
• get_real_recept(meq, ceq, keq, omega) → Real part of the receptance.
• get_imaginary_recept(meq, ceq, keq, omega) → Imaginary part of the receptance.
• get_mobility(meq, ceq, keq, omega) → Returns the mobility.
• get_real_mobility(meq, ceq, keq, omega) → Real part of the mobility.
• get_imaginary_mobility(meq, ceq, keq, omega) → Imaginary part of the mobility.
• get_acelerance(meq, ceq, keq, omega) → Returns the accelerance.
• get_real_acelerance(meq, ceq, keq, omega) → Real part of the accelerance.
• get_imaginary_acelerance(meq, ceq, keq, omega) → Imaginary part of the accelerance.

🔹 Time Response

• get_natural_response(natural_frequency, dumping_ratio, init_deloc, init_vel, time)
  Returns the free vibration response depending on damping ratio (underdamped, critically damped, overdamped).

• get_transitory_response_HE(...) → Transient response under harmonic excitation.

• get_permanent_response_HE(...) → Steady-state response under harmonic excitation.

• get_total_response_HE(...) → Total response (transient + permanent).

🔹 Harmonic Excitation Analysis

• get_amplitute_factor_HE(natural_frequency, dumping_ratio, omega) → Amplitude factor for harmonic excitation.
• get_force_transmissibility_HE(natural_frequency, dumping_ratio, omega) → Force transmissibility.

---

Example Usage

import matplotlib.pyplot as plt
from src.mec_vibrations_calcs.one_dof_calc import *

# Values for time
omega = np.linspace(0.1, 10, 100000)

# Sistem Parameters
m = 15  # mass
k = 15000  # stiffness constant
c1 = 9.48  # Dumping for system 1
c2 = 0  # # Dumping for system 2

# Natural Frequency
wn = get_natural_frequency(k, m)

# Dumping ratio System 1
eps1 = get_dumping_ratio(c1, m, wn)

# Dumping ratio System 2
eps2 = get_dumping_ratio(c2, m, wn)

# System response 1
nat_resp1 = get_natural_response(wn, eps1, 0.0001, 5, omega)

# System response 1
nat_resp2 = get_natural_response(wn, eps2, 0.5, 0, omega)

# Graphics

plt.figure(figsize=(10, 6))
plt.plot(omega, nat_resp1, label=f'Natural Response for system with dumping ratio = 0.08', color='blue', alpha=0.8)
plt.plot(omega, nat_resp2, label=f'Natural Response for system with dumping ratio = 0.05', color='green', alpha=0.6)
plt.xlabel('$t$')
plt.ylabel('$x(t)$')
plt.title('Natural response for vibration systems')
plt.grid(True)
plt.axhline(0, color='gray', linewidth=0.5)
plt.axvline(0, color='gray', linewidth=0.5)
plt.legend(loc='upper right')
plt.tight_layout()
plt.show()

---

n_dof_calc.py

This module provides functions to perform modal analysis of mechanical vibration systems with n degrees of freedom (n-DOF).
It allows the calculation of natural frequencies, mode shapes, normalized modal vectors, modal coefficients, phases, and time responses.

---

Functions Overview

get_natural_frequencies(K, M)

Computes the natural frequencies of the system.

• Input: stiffness matrix K, mass matrix M
• Output: sorted array of natural frequencies

get_modes_shapes(K, M)

Computes the mode shapes of the system.

• Input: stiffness matrix K, mass matrix M
• Output: mode shapes matrix (columns = modes, normalized to first element = 1)

get_normal_modal_vectors(modeShapes, M)

Computes normalized modal vectors considering the mass matrix.

• Input: mode shapes, mass matrix
• Output: normalized modal vectors

get_coef_resp_natural(normal_modal_vectors, natural_frequencies, M, desloc_init, vel_init)

Computes modal coefficients (amplitudes) from initial displacement and velocity.

• Input: modal vectors, natural frequencies, mass matrix, initial displacement, initial velocity
• Output: coefficients c[i] for each mode

get_modal_phases(normal_modal_vectors, natural_frequencies, M, desloc_init, vel_init)

Computes the phase of each mode.

• Input: same as above
• Output: phase angles (radians)

get_natural_modes_of_vibration(normal_modal_vectors, natural_frequencies, coef, phase)

Generates the modal response in time for each mode.

• Returns a function x_of_t(time) that computes the displacement of each mode at given times.
• Supports:
  • time as a scalar (float) → instantaneous response
  • time as a numpy array → full time history
  • Output format:
    The returned response is a matrix where:
    • Each row corresponds to one degree of freedom (DOF)
    • Each column corresponds to one natural mode of vibration

get_total_natural_response(natural_modes_in_time)

Computes the total system response by summing all modal contributions.

• Input: modal responses in time (2D or 3D array)

• Output: total displacement response

  The returned response is a matrix where:

  • Each row corresponds to one degree of freedom (DOF)
  • Each column corresponds to one natural mode of vibration

---

Example Usage

import matplotlib.pyplot as plt
from src.mec_vibrations_calcs.n_dof_calc import *

k = np.array([
    [1000, 0],
    [0, 5000 * 0.5 ** 2],
])
m = np.array([
    [4, 0.5],
    [0.5, 1.5 * 0.5 ** 2]
])

# Initial conditions
desloc_init = np.array([0.01, 0])
vel_init = np.array([0, 0])

# time definition for grafics
time = np.linspace(0, 3, 100000)
# time = 0.5
# print(type(time))

natural_freq = get_natural_frequencies(k, m)
# print(natural_freq)

modeShapes = get_modes_shapes(k, m)
# print(modeShapes)

normal_modeShapes_vect = get_normal_modal_vectors(modeShapes, m)
# print(normal_modeShapes_vect)

coef = get_coef_resp_natural(normal_modeShapes_vect, natural_freq, m, desloc_init, vel_init)
# print(coef.shape)

phases = get_modal_phases(normal_modeShapes_vect, natural_freq, m, desloc_init, vel_init)
# print(phases)

modeShapes_in_time = get_natural_modes_of_vibration(normal_modeShapes_vect, natural_freq, coef, phases)
# print(modeShapes_in_time(time).shape)


total_natural_response = get_total_natural_response(modeShapes_in_time(time))

print('---------------------------------------')

plt.figure(figsize=(10, 6))
plt.plot(time, modeShapes_in_time(time)[0][0], label=f'Effect of First mode of Vibration', color='blue', alpha=0.6,
         linestyle='--')
plt.plot(time, modeShapes_in_time(time)[1][0], label=f'Effect of Second mode of Vibration', color='red', alpha=0.6,
         linestyle='--')
plt.plot(time, total_natural_response[0], label=f'Total natural response of the system', color='green', alpha=0.8,
         linewidth=2)
plt.xlabel('$t$')
plt.ylabel('$x_{1}(t)$')
plt.title('First degree of freedom')
plt.grid(True)
plt.axhline(0, color='gray', linewidth=0.5)
plt.axvline(0, color='gray', linewidth=0.5)
plt.legend(loc='upper right')
plt.tight_layout()
plt.show()

plt.figure(figsize=(10, 6))
plt.plot(time, modeShapes_in_time(time)[1][0], label=f'Effect of First mode of Vibration', color='blue', alpha=0.8,
         linestyle='--')
plt.plot(time, modeShapes_in_time(time)[1][1], label=f'Effect of Second mode of Vibration', color='red', alpha=0.6,
         linestyle='--')
plt.plot(time, total_natural_response[1], label=f'Total natural response of the system', color='green',
         linewidth=2, alpha=0.8)
plt.xlabel('$t$')
plt.ylabel('$x_{1}(t)$')
plt.title('Second degree of freedom')
plt.grid(True)
plt.axhline(0, color='gray', linewidth=0.5)
plt.axvline(0, color='gray', linewidth=0.5)
plt.legend(loc='upper right')
plt.tight_layout()
plt.show()

Possibilities

1. Amplitude Factor for Harmonic Excitation

2. Permanent Response Example

3. Real Part of Receptance

4. Receptance Curve

5. Force Transmissibility

6. Natural Response – 2 DOF

7. Natural Response – 2 DOF

8. Natural Response Example – Two Dumpings

9. Natural Response Example – Two Dumpings (Variation)

---

Disclaimer

This module was developed for academic and study purposes.
I have performed some tests to validate the functions, but there is no guarantee that all results are 100% correct or suitable for every practical application.
Users are encouraged to review the calculations and validate the results before applying them to critical engineering problems.