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 fordist (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 ringring_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 usingpbc
. 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) ofpbc
. Pre-creating the cell for a structure and passing it to this method for all rings saves significant time. See also thepbc
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 bondatom2 (
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 spearingspear_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