molsysmt.structure.get_principal_axes#

molsysmt.structure.get_principal_axes(molecular_system, selection='all', structure_indices='all', weights=None, principal_axes_type='inertia', syntax='MolSysMT', engine='MolSysMT', use_gpu=None, skip_digestion=False)[source]#

Computing principal axes for a selection of atoms.

Parameters:

  • molecular_system (molecular system) – Molecular system in any supported MolSysMT format.

  • selection (str, list, tuple, or numpy.ndarray, default='all') – Selection string or boolean/integer array specifying elements.

  • structure_indices (int, list, tuple, or numpy.ndarray, default='all') – Structure indices (0-based) to include or process.

  • weights (numpy.ndarray, list, or tuple, default=None) – Atomic mass weights array for center calculation.

  • principal_axes_type ({'inertia', 'geometric'}, default='inertia') – Definition used to calculate the principal axes.

  • syntax (str, default='MolSysMT') – Selection syntax used to evaluate selection (e.g., ‘MolSysMT’, ‘MDTraj’).

  • engine (str, default='MolSysMT') – Backend used to perform the calculation.

  • use_gpu (bool, default=None) – Whether to perform computation using GPU acceleration.

  • skip_digestion (bool, default=False) – Whether to skip MolSysMT’s internal argument digestion mechanism.

Returns:

(axes, moments) where axes has shape (n_structures, 3, 3) and moments has shape (n_structures, 3). Moments are geometric variances or inertia moments, depending on principal_axes_type.

Return type:

tuple

Raises:

  • ArgumentError – If the atom or frame selection is empty, or weights are invalid.

  • ArgumentLengthError – If the number of weights does not match the selected atoms.

  • NotImplementedMethodError – If the engine is unsupported.

Notes

Axes are returned as rows, ordered by ascending eigenvalue, and form a right-handed orthonormal basis. Individual axis signs are mathematically arbitrary. Degenerate eigenvalues define a subspace rather than unique individual axes.

See also

molsysmt.structure.align_principal_axes()

Align coordinates to a target principal-axis basis.

molsysmt.structure.get_center()

Compute geometric or weighted centers.

Examples

>>> import molsysmt as msm
>>> molsys = msm.systems['alanine dipeptide']['alanine_dipeptide.h5msm']
>>> axes, moments = msm.structure.get_principal_axes(
...     molsys, structure_indices=0, weights='masses'
... )
>>> axes.shape, moments.shape
((1, 3, 3), (1, 3))
>>> round(float(np.linalg.det(axes[0])), 12)
1.0

Tutorial with more examples

See Get principal axes.

Added in version 1.0.0.

On this page