schrodinger.structutils.transform module¶

Manipulate atom coordinates with matrix operations.

Provides array methods to translate and rotate atoms in a structure.Structure. The coin of the realm is a four by four numpy array. The first 3x3 is a rotation matrix, the last 3x1 is translation matrix, and the 4th row is a spectator row.

All angles are in radians.

[[ 1. 0. 0. 0.]
[ 0. 1. 0. 0.] [ 0. 0. 1. 0.] [ 0. 0. 0. 1.]] # spectator row

The elements in the last row are spectators and don’t contribute to atomic coordinate changes.

schrodinger.structutils.transform.get_vector_magnitude(a)¶: Returns magnitute of a specified vector (numpy array)

schrodinger.structutils.transform.get_normalized_vector(vector)¶: Returns normalized version of the specified vector (numpy array)

schrodinger.structutils.transform.get_angle_between_vectors(a, b)¶: Return angle between 2 vectors

schrodinger.structutils.transform.translate_structure(st: Structure, x: float = 0.0, y: float = 0.0, z: float = 0.0, atom_index_list: list[int] | None = None, transform_coord_props: tuple[tuple[str, str, str], ...] | None = None) → None¶

Translate the atom coordinates along the Cartesian x, y, and z axes.

Parameters:

st – the structure to translate.
x – distance, in angstroms, to translate along the x-axis.
y – distance, in angstroms, to translate along the y-axis.
z – distance, in angstroms, to translate along the z-axis.
atom_index_list – 1-based indices of the atoms to transform. If not specified then all atoms in the structure are transformed; if empty, none are transformed.
transform_coord_props – optional tuple of atom-property name triples naming additional (x, y, z) coordinate data to transform along with the atoms. See transform_structure for details.

schrodinger.structutils.transform.rotate_structure(st: Structure, x_angle: float = 0, y_angle: float = 0, z_angle: float = 0, rot_center: list[float] | None = None, atom_index_list: list[int] | None = None, transform_coord_props: tuple[tuple[str, str, str], ...] | None = None) → None¶

Rotate the structure about the x axis, then y axis, then z axis.

Parameters:

st – the structure to rotate.
x_angle – angle, in radians, about x to right-hand rotate.
y_angle – angle, in radians, about y to right-hand rotate.
z_angle – angle, in radians, about z to right-hand rotate.
rot_center – Cartesian (x, y, z) center of rotation. Rotation happens about the origin (0, 0, 0) by default.
atom_index_list – 1-based indices of the atoms to transform. If not specified then all atoms in the structure are transformed; if empty, none are transformed.
transform_coord_props – optional tuple of atom-property name triples naming additional (x, y, z) coordinate data to transform along with the atoms. See transform_structure for details.

schrodinger.structutils.transform.transform_atom_coordinates(coords: ndarray, matrix: ndarray) → ndarray¶

Transform a single atom coordinate using a 4x4 transformation matrix.

Only one coordinate is transformed: coords is resized to the homogeneous 4-element form, so anything past the first three values is discarded. Use transform_structure to transform the coordinates of a whole structure.

Parameters:

coords – a single (x, y, z) coordinate.
matrix – 4x4 transformation matrix.

Returns:

the transformed (x, y, z) coordinate.

schrodinger.structutils.transform.transform_structure(st: Structure, matrix: numpy.ndarray, atom_index_list: list[int] | None = None, transform_coord_props: tuple[tuple[str, str, str], ...] | None = None) → None¶

Transform atom coordinates of the structure using a 4x4 transformation matrix. An optional list of atom numbers defining a subset of atoms for transformation may be specified.

Parameters:

st – the structure to transform.
matrix – 4x4 transformation matrix.
atom_index_list – 1-based indices of the atoms to transform. If not specified then all atoms in the structure are transformed; if empty, none are transformed.
transform_coord_props – optional tuple of atom-property name triples naming additional (x, y, z) coordinate data stored on atoms (e.g. FEP reference coordinates). For each triple, any atom in atom_index_list that has all three properties set has those coordinates transformed by the same matrix and written back. Atoms without the triple are left untouched (no properties are created); an atom with a partial triple raises ValueError. Defaults to None, transforming only atomic and alternate coordinates.

Raises:

ValueError – if an atom has a partial transform_coord_props triple.

schrodinger.structutils.transform.get_centroid(st, atom_list: list = None)¶

Returns the structure’s centroid. If specified, this can be limited to a subset of atoms.

NOTE: Periodic boundary conditions (PBC) are NOT honored.

Parameters:

st (Structure) – structure
atom_list (list(int)) – 1-based atom indices

Returns:

centroid given as 4-element array [x, y, z, 0.0]

Return type:

numpy.array(float)

See schrodinger/geometry/centroid.h

schrodinger.structutils.transform.translate_atom_to_origin(struct: Structure, atom: _StructureAtom, origin: list[float] | None = None, transform_coord_props: tuple[tuple[str, str, str], ...] | None = None) → None¶

Translate the structure so the given atom is at the origin.

Parameters:

struct – the structure to modify.
atom – the atom that will be at the origin after translation.
origin – the point the atom should end up at; the origin if not given.
transform_coord_props – optional tuple of atom-property name triples naming additional (x, y, z) coordinate data to translate along with the atoms. See transform_structure for details.

schrodinger.structutils.transform.translate_center_to_origin(st: Structure, origin: list[float] | None = None, transform_coord_props: tuple[tuple[str, str, str], ...] | None = None) → None¶

Translate the structure’s center to the origin.

The difference between this function and translate_centroid_to_origin is that the centroid is the average of all atoms, whereas the center is the middle of the atoms. The centroid can be very far from the center for structures with a high percent of the atoms located in one region of space and a few atoms very far away.

Parameters:

st – the structure to modify.
origin – coordinates (x, y, z) of the new origin; the origin if not given.
transform_coord_props – optional tuple of atom-property name triples naming additional (x, y, z) coordinate data to translate along with the atoms. See transform_structure for details.

schrodinger.structutils.transform.translate_centroid_to_origin(st: Structure, atom_list: list[int] | None = None, transform_coord_props: tuple[tuple[str, str, str], ...] | None = None) → None¶

Translate the structure’s centroid to the origin.

Parameters:

st – the structure to modify.
atom_list – 1-based atom indices. If provided, the centroid of the atoms in this list is translated to the origin.
transform_coord_props – optional tuple of atom-property name triples naming additional (x, y, z) coordinate data to transform along with the atoms. See transform_structure for details.

schrodinger.structutils.transform.translate_to_origin(st: Structure, atom_list: list[int] | None = None, transform_coord_props: tuple[tuple[str, str, str], ...] | None = None) → None¶

Translate the structure’s centroid to the origin.

Parameters:

st – the structure to modify.
atom_list – 1-based atom indices. If provided, the centroid of the atoms in this list is translated to the origin.
transform_coord_props – optional tuple of atom-property name triples naming additional (x, y, z) coordinate data to transform along with the atoms. See transform_structure for details.

schrodinger.structutils.transform.get_translation_matrix(trans)¶

Returns a 4x4 numpy array representing a translation matrix from a 3-element list.

trans (list): 3-element list (x,y,z).

schrodinger.structutils.transform.get_rotation_matrix(axis, angle)¶

Returns a 4x4 numpy array representing a right-handed rotation matrix about the specified axis running through the origin by some angle

axis (vector): Normalized (unit) vector for the axis around which to rotate. Can be one of predefined axis: X_AXIS, Y_AXIS, Z_AXIS, or arbitrary axis.
angle (float): Angle, in radians, about which to rotate the structure about the axis.

schrodinger.structutils.transform.get_rotation_matrix_from_eulers(phi, theta, psi)¶

Returns a 4x4 numpy array representing a rotation matrix generated from a list of Euler angles. The angles of rotation (phi, theta and psi) are applied in order, and are defined as:

phi: Angle to rotate by about Z axis [0 to 2pi in radians]
theta: Angle to rotate by about X’ axis [0 to 2pi in radians]
psi: Angle to rotate by about Z’ axis [0 to 2pi in radians]

schrodinger.structutils.transform.get_coords_array_from_list(coords_list)¶

Returns coordinates as a 4-element numpy array: (x,y,z,0.0).

coords_list (list or array): 3 elements: x, y, z.

schrodinger.structutils.transform.get_alignment_matrix(a_vector, b_vector)¶

Returns a Numpy 4x4 rotation matrix that will align a_vector onto b_vector.

a_vector (array) numpy array of vector coordinates (x, y, z)

b_vector (array) numpy array of vector coordinates (x, y, z)

schrodinger.structutils.transform.get_superposition_matrix(from_coords: ndarray, to_coords: ndarray) → ndarray¶

Returns a 4x4 numpy array representing the rigid transformation that best superimposes from_coords onto to_coords.

The two coordinate sets must be the same length and in corresponding order: row i of from_coords is fit onto row i of to_coords. The result is the proper rotation and translation minimizing the sum of squared deviations (the Kabsch fit); the coordinates are neither scaled nor reflected, so if the two sets are related by an exact rigid move that move is recovered exactly.

This is the N-point counterpart to get_alignment_matrix, which aligns a single vector onto another. Unlike schrodinger.structutils.rmsd.get_super_transformation_matrix, it operates on raw coordinates rather than structures and atom index lists.

The fit is only as well determined as the coordinates allow: a single point gives a pure translation, and two points leave the rotation about the axis joining them arbitrary. In both cases the returned matrix still maps the given coordinates onto their targets.

Parameters:

from_coords – Nx3 (x, y, z) coordinates to be moved.
to_coords – Nx3 (x, y, z) coordinates to move onto.

Returns:

the 4x4 transformation matrix, suitable for transform_structure or transform_atom_coordinates.

Raises:

ValueError – if the coordinate sets differ in shape or are empty.

schrodinger.structutils.transform.get_reflection_matrix(reflect_axis, axis_origin=None)¶

Returns a 4x4 Numpy matrix which will reflect all points through a mirror plane (defined by a unit vector normal to that plane and a point in the plane).

reflect_axis (array, len 3) Normalized (unit) vector defining the mirror plane

axis_origin (array, len 3) point which lies in the mirror plane, if None, origin will be used