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.

Copyright Schrodinger, LLC. All rights reserved.

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