molsysmt.structure.rotate#

molsysmt.structure.rotate(molecular_system, rotation=None, rotation_center=None, selection='all', structure_indices='all', syntax='MolSysMT', in_place=False, skip_digestion=False)[source]#

Rotate atomic coordinates of a selection by a given rotation.

The rotation is applied frame-by-frame. If a rotation_center is provided, the coordinates are first translated so that the center sits at the origin, rotated, then translated back.

Two rotation representations are accepted:

  • Array-like matrices of shape (3, 3), (n_structures, 3, 3), or (n_structures, n_atoms, 3, 3).

  • An object providing an apply(coordinates) method, such as scipy.spatial.transform.Rotation. SciPy is not required.

Parameters:

  • molecular_system (molecular system) – Input system in any form supported by MolSysMT.

  • rotation (array-like or rotation-like object) –

    Rotation to apply.

    • array-like of shape (n_structures, 3, 3): different rotation per frame, same rotation for all atoms within a frame.

    • array-like of shape (3, 3): single rotation broadcast to all frames.

    • array-like of shape (n_structures, n_atoms, 3, 3): one rotation per atom and frame.

    • rotation-like object: its apply method is used for every frame.

  • rotation_center (quantity or None, default None) – Centre of rotation as a PyUnitWizard length quantity of shape (n_structures, 1, 3) or (1, 1, 3). When provided, coordinates are shifted to the origin before rotation and shifted back afterwards. When None, the rotation is applied around the global origin.

  • selection (str, list, tuple or numpy.ndarray, default 'all') – Atoms whose coordinates are rotated.

  • structure_indices ('all' or array-like, default 'all') – Frame indices over which the rotation is applied.

  • syntax (str, default 'MolSysMT') – Selection syntax used when selection is a string.

  • 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 rotated coordinates.

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

Returns:

A new molecular system with the rotated coordinates when in_place=False; None when in_place=True.

Return type:

molecular system or None

Raises:

  • ArgumentError – If a matrix has an invalid shape, non-finite values, is not orthonormal, or has a determinant other than +1.

  • NotImplementedMethodError – If rotation is not a supported type.

  • StructuralInconsistencyError – If the number of per-frame or per-atom matrices cannot be broadcast to the selected coordinates.

Notes

MolSysMT uses active proper rotations on row-vector coordinates. Distances and handedness are therefore preserved.

See also

molsysmt.structure.translate()

Translate selected coordinates.

molsysmt.structure.least_rmsd_fit()

Estimate and apply a least-RMSD rigid transformation.

Examples

>>> import molsysmt as msm
>>> coordinates = msm.pyunitwizard.quantity([[[1.0, 0.0, 0.0]]], 'nm')
>>> rotation = [[0.0, -1.0, 0.0], [1.0, 0.0, 0.0], [0.0, 0.0, 1.0]]
>>> rotated = msm.structure.rotate(coordinates, rotation=rotation)
>>> msm.pyunitwizard.get_value(rotated, to_unit='nm').round(12).tolist()
[[[0.0, 1.0, 0.0]]]

Tutorial with more examples

See Rotating coordinates.

Added in version 1.0.0.

On this page