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) – System to be fitted, in any form supported by MolSysMT.

  • selection (str, list, tuple or numpy.ndarray, default 'all') – All atoms that will be physically moved by the fitted transformation. This is usually a superset of selection_fit (e.g., all atoms in a chain, while fitting is done on C-alpha only).

  • selection_fit (str, list, tuple or numpy.ndarray, default 'atom_type!="H"') – Subset of atoms used to compute the optimal superposition (heavy atoms by default). Must resolve to the same number of atoms as reference_selection_fit.

  • structure_indices ('all' or array-like, default 'all') – Frame indices of the query system to fit.

  • reference_molecular_system (molecular system or None, default None) – Reference system. When None, molecular_system itself is used.

  • reference_selection_fit (str, list, tuple or numpy.ndarray or None, default None) – Atoms in the reference used to compute the superposition. When None, the same expression as selection_fit is applied to the reference.

  • reference_structure_index (int, default 0) – Single frame index in the reference system to fit to.

  • to_form (str or None, default None) – Convert the output to the specified MolSysMT form before returning. When None, the same form as the input is kept.

  • in_place (bool, default False) – If True the molecular system is modified in-place and None is returned. If False a new copy is returned with the fitted coordinates.

  • syntax (str, default 'MolSysMT') – Selection syntax used for all selections.

  • engine ({'MolSysMT'}, default 'MolSysMT') – Backend used for the Kabsch rotation computation.

  • parallel (bool or str, optional) – Parallel mode override: True | False | ‘auto’.

  • num_threads (int, optional) – Number of threads override.

  • skip_digestion (bool, default False) – Whether to skip argument digestion (for internal use on trusted hot paths).

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 Fitting by least RMSD.

Added in version 1.0.0.

On this page