\(\newcommand{\AA}{\text{Å}}\)

lmodea_k.NormalModes

class NormalModes(H: NDArray[floating], crystal: Crystal, wavevector: NDArray[floating] | None = None, convert_phase: bool = False, asr: bool = False, rot_axis: str | None = None, generalized: bool = True, allow_negative: bool = False, matrix_type: str = 'dynamical', freq_min: float | None = None)

Solve normal modes from a dynamical matrix or Hessian.

By default this class reproduces the generalized eigenproblem workflow used by the command-line entry point:

• convert a dynamical matrix to a Cartesian Hessian when required;

• optionally apply the acoustic sum rule at the Gamma point;

• solve H L = M L K using eigh(H, M);

• apply phase conversion to eigenvectors for non-Gamma wavevectors;

• optionally raise on true negative eigenvalues (imaginary modes) at any wavevector, including Gamma.

A wavevector of None is treated as the Gamma point, which is the natural setting for molecular (finite) systems. The legacy mass-weighted diagonalisation path is still available through the generalized=False option.

__init__(H: NDArray[floating], crystal: Crystal, wavevector: NDArray[floating] | None = None, convert_phase: bool = False, asr: bool = False, rot_axis: str | None = None, generalized: bool = True, allow_negative: bool = False, matrix_type: str = 'dynamical', freq_min: float | None = None)

Parameters:

• H ((3N, 3N) array) – Input matrix. If matrix_type='dynamical' this is treated as a dynamical matrix and converted to a Cartesian Hessian before solving. If matrix_type='hessian' it is used directly as the Hessian.

• crystal (Crystal) – Crystal object from which masses, fractional coordinates, and Cartesian coordinates are obtained.

• wavevector ((3,) array, optional) – Reduced wavevector for phase conversion. If None (default), the system is treated as being at the Gamma point, appropriate for molecular (finite) systems. None is normalized to [0, 0, 0] at construction, so self.wavevector is always a concrete (3,) array.

• convert_phase (bool, default False) – Whether to phase-shift eigenvectors for non-Γ wavevectors.

• asr (bool, default False) – Apply the acoustic sum rule before diagonalisation at Gamma.

• rot_axis ({"x","y","z","all",None}, optional) – Rotation axis for ASR rotational mode removal.

• generalized (bool, default True) – If True, solve the generalized eigenproblem H L = M L K. If False, diagonalise the dynamical matrix (mass-weighted Hessian).

• allow_negative (bool, default False) – If True, permit true negative eigenvalues (imaginary modes) at any wavevector, including Gamma. Eigenvalues with magnitude at or below freq_min (converted to eigenvalues internally) are treated as near-zero and are always permitted (they are handled by eigenvalue clamping). Otherwise raise a ValueError if any eigenvalue is smaller than the negative of the converted threshold.

• matrix_type ({"dynamical", "hessian"}, default "dynamical") – Whether the input matrix is a dynamical matrix or a Hessian.

• freq_min (float, optional) – Minimum frequency threshold in cm⁻¹, used to prevent singularities in downstream analyses. The threshold is converted internally to eigenvalue units (Hartree/bohr²/amu) via lmodea_k.utils.constants.freq_to_eigval(). Eigenvalues with magnitude below this value (the K→0 band, e.g. acoustic modes at Gamma) are clamped up to this minimum when eigenvalues_clamped() is used, while true negative eigenvalues (more negative than the converted threshold) are preserved. This parameter also defines the true-negative threshold used by the allow_negative check. If None, no clamping or threshold checking is applied.

Methods

__init__(H, crystal[, wavevector, ...])	param H: Input matrix. If matrix_type='dynamical' this is treated as a
get_hessian([freq_min])	Get the Cartesian Hessian, optionally with eigenvalue clamping applied.
reconstruct_hessian(K, L, masses)	Reconstruct the Cartesian Hessian from eigenvalues and eigenvectors.
summary([n])	Print the first n frequencies for inspection.

Attributes

dynmat_eigenvalues	Eigenvalues from the dynamical-matrix diagonalisation, shape (3N,).
dynmat_eigenvectors	Eigenvectors from the dynamical-matrix diagonalisation, shape (3N, 3N).
eigenvalues	Eigenvalues from the generalized eigenproblem H L = M L K, shape (3N,).
eigenvalues_clamped	Eigenvalues with the near-zero K→0 band clamped, shape (3N,).
eigenvectors	Eigenvectors from the generalized eigenproblem H L = M L K, shape (3N, 3N).
frequencies	Frequencies in cm⁻¹ (negative for imaginary modes), shape (3N,).
hessian	Cartesian Hessian used in the solve, shape (3N, 3N).