schrodinger.structutils.ringspear module¶

Functions and classes useful for finding ring spears. A ring spear is when a bond between two atoms external to a ring passes through the face of the ring. The bond may be a single bond or a higher-order bond, and it may be cyclic or acyclic. Thus, ring catenation is also found.

To find ring spears within a structure, use:

check_for_spears(struct)

To find ring spears where struct2 spears struct1, use:

check_for_spears(struct1, spear_struct=struct2)

To find ring spears, checking only atoms in list “atomlist” as spears, use:

check_for_spears(struct, atoms=atomlist)

Ring-finding is by far the most expensive operation, so the check_for_spears function allows rings to be passed in as schrodinger.structure._Ring objects if they are already known - or if only a subset of the structure’s rings should be used. For a 7000 atom structure with 270 rings, ring-finding took ~ 90% of the total computation time.

schrodinger.structutils.ringspear.ROUGH_CUT_DISTANCE = 4.0¶: The default distance from a ring centroid at which atoms are eliminated from spearing consideration

schrodinger.structutils.ringspear.create_pbc(pbc)¶

Convert pbc in list form to infrastructure.PBC object.

Parameters: pbc (infrastructure.PBC or list) – If periodic boundary conditions should be used, provide either an infrastructure.PBC object or the parameters to construct one.

Allowed PBC constructors:

* a, b, c : box lengths
* a, b, c, alpha, beta, gamma box : box lengths and angles
* ax, ay, az, bx, by, bz, cx, cy, cz : box vectors

Return type: schrodinger.infra.structure.PBC
Returns: an infrastructure.PBC object.

schrodinger.structutils.ringspear.create_distance_cell(struct, dist, pbc=None)¶

Create a infrastructure DistanceCell that obeys the given periodic boundary size.

Parameters

struct (schrodinger.structure.Structure) – The structure to create the distance cell for
dist (float) – The distance threshold for the distance cell
pbc (None, infrastructure.PBC, or list) – If periodic boundary conditions should be used, provide either an infrastructure.PBC object or the parameters to construct one.

Allowed PBC constructors:

* a, b, c : box lengths
* a, b, c, alpha, beta, gamma box : box lengths and angles
* ax, ay, az, bx, by, bz, cx, cy, cz : box vectors

Return type: (schrodinger.infra.structure.DistanceCell, schrodinger.infra.structure.PBC or None)
Returns: A distance cell object that obeys the given PBC conditions. Note that this is a different type of object than an mmct distance cell and has a completely different API. The second value returned is the PBC object used to create the distance cell or None if no PBC was used.
Raises: ValueError – If the pbc needs to be constructed and the parameters don’t match an available constructor

class schrodinger.structutils.ringspear.Spear(spear_indexes, ring_indexes)¶

Bases: object

Contains the atom indexes involved in a ring spear and formats the data in a user-readable string

__init__(spear_indexes, ring_indexes)¶

Create a Spear object

Parameters

spear_indexes (iterable) – The indexes of the two atoms that make the bond that spears the ring
ring_indexes (iterable) – The atom indexes of the ring that is speared

spear_indexes¶: List of atom indexes that make the spearing bond

ring_indexes¶: List of atom indexes of the speared ring

class schrodinger.structutils.ringspear.SpearRing(struct, ring_indexes, pbc=None)¶

Bases: object

Computes and holds information about a ring, and finds bonds that spear that ring.

Note: Objects of this class do not maintain pointers to either the Structure object or the _Ring object that were used to create them.

ORIG_ATOM_INDEX = 'i_matsci_orig_atom_spearring_index'¶

__init__(struct, ring_indexes, pbc=None)¶

Create a SpearRing object

Parameters

struct (schrodinger.structure.Structure) – The structure that contains this ring
ring_indexes (list) – Ring indexes
pbc (schrodinger.infra.structure.PBC) – The periodic boundary condition to use if any or None if there is no PBC to use

ring_size¶: The atom indexes of the ring atoms

pbc¶: The periodic boundary condition to use if any

centroid¶: The ring centroid and set of ring coordinates that keep the ring together even if it was originally broken across the PBC

pbc_ring_coords¶: The ring centroid and set of ring coordinates that keep the ring together even if it was originally broken across the PBC

origin_normal¶: The normal based at the ring centroid

radius¶: The largest centroid-ring atom distance

getRingCentroid(struct)¶

Get the ring centroid. Accounts for the fact that the ring might be broken across the periodic boundary condition

Parameters: struct (schrodinger.structure.Structure) – The structure that contains this ring
Return type: numpy.array, numpy.array
Returns: A 3-float numpy array giving the [X, Y, Z] coordinates of the ring centroid, and a numpy array of the XYZ coordinates of each ring atom taking into account the PBC so that the coordinates are not split by the PBC. The coordinate list is in the same order as the ring_indexes property.

getNormalsAndRadius(struct)¶

Find the average normal vector to the ring plane and compute the radius of the ring.

The average normal vector is the average of the normal vectors computed for each pair of adjacent ring atoms and the ring centroid.

The radius is defined as the largest centroid-ring atom distance

Parameters: struct (schrodinger.structure.Structure) – The structure that contains this ring
Return type: numpy.array, numpy.array, float
Returns: The average normal vector to the plane of the ring translated so its base is at the origin, the average normal vector to the plane of the ring translated so its base is at the ring centroid, the radius of the ring.

findSpears(orig_struct, atoms=None, is_ring_struct=True, distorted=False, first_only=True, cell=None, dist=4.0, return_bool=False)¶

Check for ring spears - bonds that pass through the face of the ring. It does not matter if the spearing bond is a single or multiple bond, or if it is part of another ring.

Parameters

orig_struct (schrodinger.structure.Structure) – The structure to check if any bonds spear this ring in ring_struct.
atoms (list) – List of atom indexes to check to see if they spear this ring.
is_ring_struct (bool) – Whether orig_struct contains this ring. If True, the atoms with the same index as the indexes of this ring will not be considered for spearing calculations.
distorted (bool) – If False (default), the structure will be assumed to have reasonable bond lengths, and optimizations will be used to dramatically speed up spear-finding in large structures by eliminating atoms that cannot possibly spear this ring. If True, atom distances will not be used to optimize spear-finding - significantly increasing the time required.
first_only (bool) – Whether to return after finding the first ring spear, or whether all ring spears should be found.
cell (schrodinger.infra.structure.DistanceCell) – schrodinger.infra.structure.DistanceCell object created using pbc. cell is used for rough-cutting atoms too far away from the ring. If not provided, a cell will be created based on the value (or lack of value) of pbc. Pre-creating the cell for a structure and passing it to this method for all rings saves significant time. See also the pbc parameter.
dist (float) – The distance from the ring centroid at which atoms will be rough cut and eliminated from spearing consideration. This is only used if cell is not provided.
return_bool (bool) – If True, return bool instead of list

Return type

list or bool

Returns

If return_bool, return bool to indicate whether at least one spear exists; else return a list of found ring-spears, each item is a Spear object. An empty list is returned if no spears are found, and if first_only is True the list will be at most 1 item long.

quickWeedAtoms(struct)¶

Quickly weed out any atoms that are too far away from the ring centroid to spear the ring.

This method differs from the rough cut method, which uses a larger spherical cutoff based on the centroid. This uses a cubic cutoff, which allows the dimensions to be smaller since the sphere has to large enough to maintain sufficient distance near the edges of the ring.

This method also uses smaller distances for smaller atoms

Parameters: struct (schrodinger.structure.Structure) – The structure to modify directly be deleting atoms that are weeded out
Return type: None
Returns: Nothing is returned, the input structure is modified directly

static markAtomsBeforeSpearCheck(struct)¶

Add an atom property to all atoms with the atom’s current index. This allows the original index to be retrieved even after atom indexes have been modified via atom extraction or deletion.

Note: This is a static method

bondRingPlaneIntersection(atom1, atom2)¶

Find the point (if any) where the bond intersects the ring plane

Python code for this was originally found at https://stackoverflow.com/questions/5666222/3d-line-plane-intersection and adapted from there.

Parameters

atom1 (schrodinger.structure._StructureAtom) – The first atom in the bond
atom2 (schrodinger.structure._StructureAtom) – The second atom in the bond

Return type

numpy.array or None

Returns

The point where the bond intersect the ring plane or None if there is no intersection (bond is parallel to plane of the ring). None is also returned if the line the bond forms intersects the plane but the intersection is outside of the bond line segment itself.

schrodinger.structutils.ringspear.check_for_spears(ring_struct, spear_struct=None, atoms=None, rings=None, distorted=False, first_only=True, dist=4.0, pbc=None, max_ring_size=12, cell=None, spear_rings=None, return_bool=False)¶

Check for ring spears - rings that have bonds passing through the face of the ring.

Parameters

ring_struct (schrodinger.structure.Structure) – The structure containing the rings to check for spearing
spear_struct (schrodinger.structure.Structure) – The structure to check if any bonds spear a ring in ring_struct. If not given, ring_struct will be used - i.e. intrastructure ring spears will be searched for.
atoms (list) – List of atom indexes to check to see if they spear a ring. Should be indexes from spear_struct if spear_struct is given, otherwise indexes from ring_struct. If not given, all atoms will be checked.
rings (iterable of schrodinger.structure._Ring) – _Ring objects to check to see if they are speared. If not given, all rings in the ring_struct.ring iterator will be used. Use this parameter if you have an optimized method of finding rings in ring_struct or if they are already known.
distorted (bool) – If False (default), the structure will be assumed to have reasonable bond lengths, and optimizations will be used to dramatically speed up spear-finding in large structures by eliminating atoms that cannot possibly spear a ring. If True, atom distances will not be used to optimize spear-finding - significantly increasing the time required.
first_only (bool) – Whether to return after finding the first ring spear, or whether all ring spears should be found.
dist (float) – The distance from the centroid to use when making a first rough cut pass to eliminate atoms that are too far away from a ring to spear it. The default value is the module constant ROUGH_CUT_DISTANCE. This value is ignored if distorted is True.
pbc (None, infrastructure.PBC, or list) – If periodic boundary conditions should be used, provide either an infrastructure.PBC object or the parameters to construct one.

Allowed PBC constructors:

* a, b, c : box lengths
* a, b, c, alpha, beta, gamma box : box lengths and angles
* ax, ay, az, bx, by, bz, cx, cy, cz : box vectors

Parameters

max_ring_size (int or None) – The maximum size ring that will be checked for ring spears. The default value prevents macrocycles from being checked. Set to None to include all rings
cell (schrodinger.infra.structure.DistanceCell) – An infrastructure distance cell that has been created for use in rough-cutting atoms too far away from the ring. If not provided, a cell will be created.
spear_rings (list of SpearRing or None) – findSpears for these spear_rings, if not None. If None, create spear_rings based on rings or ring_struct.rings, and then findSpears.
return_bool (bool) – If True, return bool instead of list

Return type

list or bool

Returns

If return_bool, return bool to indicate whether at least one spear exists; else return a list of found ring-spears, each item is a Spear object. An empty list is returned if no spears are found, and if first_only is True, the list will be at most 1 item long.

Raises

ValueError – If the pbc needs to be constructed and the parameters don’t match an available constructor