Installation

Requirements

Python 3.9, 3.10, 3.11, or 3.12
NumPy ≥ 1.24
SciPy ≥ 1.10
Matplotlib ≥ 3.7

Standard install

pip install pyserep

This installs the core library with all required dependencies.

Optional: HDF5 matrix loading

If your FE matrices are stored in HDF5 format (h5, hdf5), install the extra dependency:

pip install pyserep[io-extra]

Development install

To install from source with all development tools (test suite, linter, documentation builder):

git clone https://github.com/YourOrg/pyserep.git
cd pyserep
pip install -e ".[dev]"

Verify the installation

make smoke

or:

import pyserep
print(pyserep.__version__)

from pyserep import spring_chain, solve_eigenproblem
K, M = spring_chain(n=100)
freqs, phi = solve_eigenproblem(K, M, n_modes=10, verbose=False)
print(f"First 3 natural frequencies: {freqs[:3].round(2)} Hz")

Matrix file formats

pyserep reads structural matrices in the following formats without any additional dependencies:

Extension	Format	Source
`.mtx`, `.mm`	Matrix Market	Ansys `/AUX2`, Abaqus, etc.
`.npz`	SciPy sparse NPZ	`scipy.sparse.save_npz`
`.npy`	NumPy dense array	`numpy.save`
`.csv`	Dense CSV	Any spreadsheet/text tool
`.h5`, ``.hdf5``\| HDF5 sparse		Requires `pip install h5py`

Ansys DOF numbering

Ansys exports matrices with DOFs numbered as:

DOF_index = (node_number − 1) × 3 + direction
direction: 0=UX, 1=UY, 2=UZ

Use the built-in helper:

from pyserep import ansys_dof, dof_to_ansys

dof = ansys_dof(1001, 0)   # Node 1001, UX → DOF 3000
node, direction = dof_to_ansys(3000)   # → (1001, 0)

Symmetric matrix requirement

Warning

pyserep requires real symmetric K and M matrices.

Matrix	Requirement
K	Real, symmetric, positive semi-definite
M	Real, symmetric, positive definite

Asymmetric matrices will not raise an immediate error in all code paths but will produce incorrect eigenvalues and FRF results.

Validate before running the pipeline:

from pyserep import load_matrices, check_symmetric_pd

K, M = load_matrices("K.mtx", "M.mtx")
report = check_symmetric_pd(K, M)
print(report["message"])

Fix near-symmetric matrices (numerical noise from FE export):

from pyserep import enforce_symmetry
K = enforce_symmetry(K)   # K ← 0.5*(K + Kᵀ)
M = enforce_symmetry(M)

Not supported: Non-symmetric systems (gyroscopic, aerodynamic stiffness, follower forces). These are planned for v4.0.