femlabpy.modal#

Modal-analysis tools for natural frequencies, mode shapes, and participation.

Workflow role#

This module reduces the assembled free-degree-of-freedom system, solves the generalized eigenvalue problem, expands the modes back to the full structural space, and computes participation and effective modal mass. It is the bridge between assembly and later dynamics work such as Rayleigh damping, modal superposition, and frequency-response calculations.

Public entry points#

solve_modal is the main solver and returns a ModalResult dataclass.
plot_modes gives a quick visual inspection of the extracted shapes.
The private helpers show the exact sequence used internally: free-DOF masking, system reduction, and modal participation recovery.

Functions#

`plot_modes`(T, X, phi, dof[, mode_indices, scale])	Plot mode shapes as deformed meshes.
`solve_modal`(K, M[, n_modes, C_bc, dof, sigma])	Compute the lowest natural frequencies and mode shapes.

Function Reference#

femlabpy.modal.plot_modes(T, X, phi, dof, mode_indices=None, *, scale=1.0)[source]#

Plot mode shapes as deformed meshes.

Parameters:

Tarray_like: Element topology table.
Xarray_like: Nodal coordinates, shape (nn, ndim).
phindarray, shape (ndof, n_modes): Mode shape matrix.
dofint: DOFs per node.
mode_indiceslist of int, optional: Which mode indices to plot (0-based). Defaults to first 4.
scalefloat: Displacement amplification factor.

femlabpy.modal.solve_modal(K, M, n_modes: int = 10, *, C_bc=None, dof: int = 2, sigma: float = 0.0) → ModalResult[source]#

Compute the lowest natural frequencies and mode shapes.

Parameters:

Kndarray or scipy.sparse matrix, shape (ndof, ndof): Global stiffness matrix.
Mndarray or scipy.sparse matrix, shape (ndof, ndof): Global mass matrix.
n_modesint, default 10: Number of lowest modes to compute.
C_bcarray_like, optional: Boundary condition constraint table (same format as setbc C argument). Constrained DOFs are eliminated before the eigensolve.
dofint, default 2: Degrees of freedom per node. Determines directionality for effective mass.
sigmafloat, default 0.0: Shift for the shift-and-invert solver (Lanczos). Use 0.0 to find the fundamental (lowest) modes.

Returns:

ModalResult: Dataclass containing eigenvalues, circular frequencies (rad/s), frequencies (Hz), periods (s), mass-normalized mode shapes (ndof, n_modes), participation factors, and effective modal mass vectors.

Examples

>>> from femlabpy import init, kq4e, solve_modal
>>> result = solve_modal(K, M, n_modes=5, C_bc=C, dof=2)
>>> print(result.freq_hz[:3])

Classes#

ModalResult(eigenvalues, omega, freq_hz, ...)

Container for modal analysis results.

Class Reference#

class femlabpy.modal.ModalResult(eigenvalues: ndarray, omega: ndarray, freq_hz: ndarray, period: ndarray, mode_shapes: ndarray, participation: ndarray | None = None, effective_mass: ndarray | None = None)[source]#

Bases: object

Container for modal analysis results.

Attributes:

eigenvaluesndarray, shape (n_modes,): Eigenvalues omega_i^2 (square of natural frequencies).
omegandarray, shape (n_modes,): Natural frequencies in rad/s.
freq_hzndarray, shape (n_modes,): Natural frequencies in Hz.
periodndarray, shape (n_modes,): Natural periods in seconds.
mode_shapesndarray, shape (ndof, n_modes): Mode shape vectors (columns), mass-normalized.
participationndarray, shape (n_modes, ndim) or None: Modal participation factors per direction.
effective_massndarray, shape (n_modes, ndim) or None: Effective modal mass per direction.