molsysmt.structure.least_rmsd_fit#

molsysmt.structure.least_rmsd_fit(molecular_system=None, selection='all', selection_fit='atom_type!="H"', structure_indices='all', reference_molecular_system=None, reference_selection_fit=None, reference_structure_index=0, to_form=None, in_place=False, syntax='MolSysMT', engine='MolSysMT', parallel=None, num_threads=None, use_gpu=None, gpu_backend=None, precision=None, skip_digestion=False)[source]#

Superpose a molecular system onto a reference using the Kabsch least-RMSD algorithm.

The optimal rotation matrix and translation vector that minimise the RMSD between selection_fit atoms and their counterparts in the reference are computed via the Kabsch algorithm. The resulting rigid-body transformation is then applied to the broader selection (which may include more atoms than selection_fit).

Parameters:

  • molecular_system (molecular system, default=None) – Molecular system in any supported MolSysMT format.

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

  • selection_fit (str, list, tuple, or numpy.ndarray, default='atom_type!="H"') – Atoms from the input system used to determine the rigid fit.

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

  • reference_molecular_system (molecular system or None, default=None) – Reference molecular system; None uses the input molecular system.

  • reference_selection_fit (str, list, tuple, or numpy.ndarray, or None, default=None) – Reference atoms paired with selection_fit during fitting.

  • reference_structure_index (int, default=0) – Zero-based structure index selected from the reference system.

  • to_form (str, list of str, or None, default=None) – Target molecular-system form; None preserves or infers the input form.

  • in_place (bool, default=False) – Whether to modify the input molecular system in place.

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

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

  • parallel (bool or None, default=None) – Whether to use CPU parallelism, or None to use the configured default.

  • num_threads (int or None, default=None) – Number of CPU worker threads, or None to use the configured default.

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

  • gpu_backend (str or None, default=None) – GPU array backend, or None to use the configured backend.

  • precision ({'single', 'double'} or None, default=None) – Floating-point precision, or None to use the configured precision.

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

Returns:

A new molecular system with the fitted coordinates (optionally converted to to_form) when in_place=False; None when in_place=True.

Return type:

molecular system or None

Raises:

  • NotImplementedMethodError – If an unsupported engine is requested.

  • StructuralInconsistencyError – If the number of atoms resolved by selection_fit and reference_selection_fit differ, or if either fit selection is collinear and therefore cannot define a unique three-dimensional rigid transformation.

Notes

A unique three-dimensional rotation requires at least three non-collinear fit atoms in both systems. A fit based on one atom, two atoms, or collinear atoms is rejected instead of returning an arbitrary rotation.

See also

molsysmt.structure.get_rmsd()

Compute RMSD without changing coordinates.

molsysmt.structure.rotate()

Apply an explicit proper rotation.

Examples

>>> import molsysmt as msm
>>> molsys = msm.convert(
...     msm.systems['pentalanine']['traj_pentalanine.h5msm'],
...     structure_indices=[0, 1],
... )
>>> fitted = msm.structure.least_rmsd_fit(
...     molsys, selection_fit='atom_type!="H"', structure_indices=[0, 1],
...     reference_structure_index=0, use_gpu=False
... )
>>> msm.get(fitted, element='system', n_structures=True)
2

Tutorial with more examples

See Least RMSD fit.

Added in version 1.0.0.

On this page