Module analyze

Return a dictionary of chiral atoms, for which the key is the atom index and the value is one of the following strings: "R", "S", "ANR", "ANS", "undef".

ANR and ANS designate "chiralities" of non-chiral atoms that are important for determining the structure of the molecule (ex: cis/trans rings).

Parameters:

• structure (Structure) - Chirality of atoms within this structure will be determined.

Returns: dict

Dictionary of chiralities keyed off atom index.

Search for substructures in Structure structure matching the SMARTS pattern smarts_expression.

This function uses the mmlib implementation (mmpatty) of SMARTS matching.

See also evaluate_smarts_canvas, which uses the Canvas libraries to evaluate SMARTS patterns. This function may be deprecated in favor of the evaluate_smarts_canvas function at some point. For now, you should prefer the Canvas version when you are starting with a Canvas ChmMol object or to guarantee consistency with the generate_smiles function.

Returns a list of lists of ints. Each list of ints is a list of atom indices matching the SMARTS pattern.

Parameters:

• structure (Structure) - Structure to search for matching substructures.
• smarts_expression (str) - SMARTS string used to match substructures.
• verbose (bool) - If True, print additional progress reports from the C implementation.
• first_match_only (bool) - If False, return all matches for a given starting atom - e.g. [1, 2, 3, 4, 5, 6] and [1, 6, 5, 4, 3, 2] from atom 1 of benzene with the smarts_expression 'c1ccccc1'. If True, return only the first match found for a given starting atom. Note that setting first_match_only to True does not affect matches with different starting atoms - i.e. benzene will still return six lists of ints for 'c1ccccc1', one for each starting atom. To match only once per set of atoms, use unique_sets=True. Note also that setting first_match_only to True does not guarantee that all matching atoms will be found.
• unique_sets (bool) - If True, the returned list of matches will contain a single (arbitrary) match for any given set of atoms. If False, return the uniquely ordered matches, subject to the behavior specified by the first_match_only parameter.

Returns: list

Each value is a list of atom indices matching the SMARTS pattern.

Initialize _canvas and smiles variables. Since the canvas modules may take some time to import, before it an function loading time.

Check whether a SMARTS pattern is valid or not.

Returns: (bool, str)

The bool indicates whether the SMARTS pattern is valid, the string gives the error message if bool is False Note: the return value of this function always evaluates to True since it is a non-empty tuple.

Evaluate SMARTS patterns using the Canvas libraries.

Returns a list of lists of ints. Each list of ints is a list of atom indices matching the SMARTS pattern.

Parameters:

• structure (Structure or schrodinger.application.canvas.base.ChmMol) - Structure to search for matching substructures.
• smarts (str) - SMARTS string used to match substructures.
• stereo (enum) - Specify how to determine the stereochemistry of a ChmMol from a Structure. Can be STEREO_FROM_GEOMETRY, STEREO_FROM_ANNOTATION, STEREO_FROM_ANNOTATION_AND_GEOM, or NO_STEREO. See schrodinger.structutils.smiles.SmilesGenerator.__init__ for descriptions of these options.
• start_index (int) - Specify the start index of the atom indices returned. Defaults to Structure mode, which is 1-based. Pass in 0 for 0-based indices.
• uniqueFilter (bool) - Returns only unique sets of matching atoms, and eliminates matching the same atoms in a different order.
• allowRelativeStereo (bool) - Allows a given configuration of chirality specified to match a structure with all the chiralities flipped.
• rigourousValidationOfSource (bool) - This option validates that the stereochemical labels are correct for the structure before evaluating the SMARTS pattern containing stereo information.
• hydrogensInterchangeable (bool) - If true, given only 1 atom mapping for a structure that differs only in hydrogens.

Returns: list

Each value is a list of atom indices matching the SMARTS pattern.

Takes a structure and a SMARTS pattern and returns a list of all matching atom indices, where each element in the list is a group of atoms that match the the SMARTS pattern. The advantage of this function over evaluate_smarts_canvas is that it does a SMARTS match for each molecule in a structure rather than over the entire structure at once. SMARTS evaluation scales as N^2 with the size of the structure searched. Doing many SMARTS evaluations over small molecules will have a significant speedup over one SMARTS evaluation over a composite structure. The return value of this function is identical to the return value of the evaluate_smarts_canvas function (or evaluate_smarts function if canvas=False) with the possible exception of the order of the matches. Do not use this function if the SMARTS match can span molecules. This simply fails to match invalid SMARTS patterns and also discards any empty matches.

Additional keyword arguments are passed to the SMARTS matching function

Parameters:

• structure (structure.Structure) - the structure to search
• smarts (str) - the SMARTS pattern to match
• timing_data (dict or None) - If supplied this dict will be filled with timing data for the SMARTS finding. Data will be recorded for each molecule searched. Keys will be the number of atoms in a molecule, each value will be a list. Each item in the list will be the time in seconds it took to search a molecule with that many atoms.
• canvas (bool) - If True, use Canvas SMARTS matching, if False, use mmpatty

Returns: list

Each value is a list of atom indices matching the SMARTS pattern.

Search for multiple SMARTS substructures in Structure structure.

Return a list of lists of ints. Each list of ints is a list of atom indices matching a SMARTS pattern. The multiple SMARTS patterns are combined into one list.

Parameters:

• structure (Structure) - Structure to search for matching substructures.
• smarts_list (list) - List of SMARTS patterns to look for.
• verbose (bool) - If True, print additional progress reports from the C implementation.
• first_match_only (bool) - If False, return all matches for a given starting atom - e.g. [1, 2, 3, 4, 5, 6] and [1, 6, 5, 4, 3, 2] from atom 1 of benzene with the smarts_expression 'c1ccccc1'. If True, return only the first match found for a given starting atom. Note that setting first_match_only to True does not affect matches with different starting atoms - i.e. benzene will still return six lists of ints for 'c1ccccc1', one for each starting atom. To match only once per set of atoms, use unique_sets=True. Note also that setting first_match_only to True does not guarantee that all matching atoms will be found.
• unique_sets (bool) - If True, the returned list of matches will contain a single (arbitrary) match for any given set of atoms. If False, return the uniquely ordered matches, subject to the behavior specified by the first_match_only parameter.

Returns: list

Each value is a list of atom indices matching the SMARTS patterns.

Search for the MacroModel-style substructure expression in Structure st and return the atoms that match. For each match a list of atom indices is returned.

Parameters:

• st (Structure) - Structure to search for matching substructures.
• subs_expression (str) - MacroModel-style substructure expression to use for the search.
• first_match_only (bool) - If True, return only the first match found.

Returns: list

List of atom indices match the substructure expression.

Generate and return an atom expression for the atoms in Structure st which are listed in atom_list. The ASL expression will be as compact as possible using mol, res and atom expressions where appropriate.

Parameters:

• st (Structure) - Structure holding the ASL atoms.
• atom_list (list) - List of indices of atoms for which ASL is desired.

Returns: str

ASL compactly describing the atoms in atom_list.

Validate the given ASL expression. This is useful for validating an ASL when a structure object is not available - for example when validating a command line option. NOTE: A warning is also printed to stdout if the ASL is not valid.

Parameters:

• asl (str) - ASL expression.

Returns: bool

True if ASL is valid, False otherwise.

Search for substructures matching the ASL (Atom Specification Language) string asl_expr in Structure st.

Parameters:

• st (Structure) - Structure to search for matching substructures.
• asl_expr (str) - ASL search string.

Returns: list

List containing indices of matching atoms.

Raises:

• schrodinger.infra.mm.MmException - If the ASL expression is invalid.

Return atoms matching the ASL string asl_expr in Structure st.

Parameters:

• st (Structure) - Structure to search for matching substructures.
• asl_expr (str) - ASL search string.

Returns: generator

Generator of matching StructureAtom objects.

Raises:

• schrodinger.infra.mm.MmException - If the ASL expression is invalid.

Return the smallest set of smallest rings (SSSR) in st.

See also the schrodinger.structure.Structure.find_rings method and the schrodinger.structure.Structure.ring iterator. This method may be deprecated at some point in favor of those methods.

The return value is a list of lists of ints. Each list of ints corresponds to a ring, and the integer values are the atom indices.

Parameters:

• st (Structure) - Structure holding rings.
• sort (bool) - If True, sort the atoms in each ring by connectivity so that the atoms that are bonded appear next to each other in the list.

Returns: list

Each value is a list corresponding to the atom indices of a ring.

Return True if all hydrogens are present in Structure st, False otherwise.

Since all modern force fields require hydrogens, this is a good check to make sure that a structure is ready for force field calculations. This function is implemented by checking to see if the structure can be used as-is in a calculation with OPLS2003.

Parameters:

• st (Structure) - Structure to be tested.

Returns: bool

Are all hydrogens are present?

Return a SMILES string for st.

For more options, see the schrodinger.structutils.smiles.SmilesGenerator class.

Parameters:

• st (Structure) - Structure for which SMILES string is desired.
• unique (bool) - If True, generate unique (canonical) SMILES.
• stereo (str constant) - Specify the source of stereochemical information. The value should be one of the following module level constants:
  • STEREO_FROM_ANNOTATION_AND_GEOM - Derive stereochemistry from pre-existing mmstereo properties, but use the 3D coordinates when no annotation is present.
  • STEREO_FROM_ANNOTATION - Derive stereochemistry from pre-existing mmstereo properties. (This is faster than using geometry, and is useful when structures are known to be 2D).
  • STEREO_FROM_GEOMETRY - Derive stereochemistry from the 3D geometry only. (Slower, but robust to structural changes in the molecule.)
  • NO_STEREO - Don't include stereochemistry.

  (default: STEREO_FROM_ANNOTATION_AND_GEOM)

Returns: str

SMILES string representing st.

Return a SMARTS pattern for atoms atom_subset in Structure st. If no atom subset list is given then all atoms in st will be used. This function uses Canvas library to generate smarts.

Parameters:

• st (Structure) - Structure containing atom_subset.
• atom_subset (list) - A list of atom indices (or _StructureAtom objects) to generate the SMARTS pattern for. (default: all atoms)
• check_connectivity (bool) - If True, check for whether the atoms given are connected and raise a ValueError if they are not. SMARTS generation will give bogus results for unconnected atoms.
• include_hydrogens (bool) - Whether to always include hydrogens in the generated SMARTS pattern. By default, SMARTS patterns do not contain hydrogens, except for cases where they are needed to avoid ambiguity.
• honor_maestro_prefs (bool) - Whether to honor the Maestro's SMARTS prefs. Valid only when running inside Maestro.

Returns: str

SMARTS string representing atom_subset.

Return True if atom1-atom2 represents an H-bond where either atom1 or atom2 is the acceptor heavy atom, and the other atom is the donor hydrogen.

NOTE: If you are searching for hbonds, it is almost certainly preferable to use hbond.get_hydrogen_bonds(st1, st2).

To match as hydrogen bond,

1. the atom1-atom2 distance must be less than or equal to 'distance_max',
2. the N-H..X angle must be at least 'donor_angle', and
3. the H..X-Y angle must be at least 'acceptor_angle'.

Parameters:

• atom1 (_StructureAtom) - First atom.
• atom2 (_StructureAtom) - Second atom (either from the same or a different Structure.
• distance_max (float) - Maximum accepted atom1-atom2 H-bond distance. (default: 2.5A)
• donor_angle (float) - Minimum accepted N-H..X angle. (default: 120 degrees)
• acceptor_angle (float) - Minimum accepted H..X-Y angle. (default: 90 degrees)
• honor_pbc (bool) - Honor Periodic Boundary Conditions, if defined as properties in the structure, and if both atoms are from the same CT. Default is True.

Returns: bool

Does atom1-atom2 count as an H-bond under the criteria provided?

Generate crystal mates for the input Structure st.

Return a list of structures that represent the crystal mates. (Note that the first item in the list represents the identity transformation and as such will be identical to the input structure.)

All crystal mates within radius of the input structure are generated.

The crystal parameters can be specified as parameters to this function or can be standard PDB properties of the input structure. If the structure was read from a PDB file then these crystal properties will usually be present.

The group_radius is used in the crystal mates calculation to determine whether a symmetric element is in contact with the ASU. There should be little reason to change the default value of 14.0.

Parameters:

• st (Structure) - Structure for which crystal mates will be generated.
• radius (float) - Distance within which to generate crystal mates.
• space_group (str) - Space group of the crystal. If None, uses st's s_pdb_PDB_CRYST1_Space_Group.
• a (float) - Crystal 'a' length. If None, uses st's s_pdb_PDB_CRYST1_a.
• b (float) - Crystal 'b' length. If None, uses st's s_pdb_PDB_CRYST1_b.
• c (float) - Crystal 'c' length. If None, uses st's s_pdb_PDB_CRYST1_c.
• alpha (float) - Crystal 'alpha' angle. If None, uses st's s_pdb_PDB_CRYST1_alpha.
• beta (float) - Crystal 'beta' angle. If None, uses st's s_pdb_PDB_CRYST1_beta.
• gamma (float) - Crystal 'gamma' angle. If None, uses st's s_pdb_PDB_CRYST1_gamma.
• group_radius (float) - Used to determine whether a symmetric element is in contact with the ASU. There should be little reason to change the default value of 14.0.

Returns: list

list of Structure objects that represent the crystal mates. (Note that the first item in the list represents the identity transformation and as such will be identical to the input structure.)

Search the specified structure for overlapping atoms. Returns a list of (atom1index, atom2index) tuples.

Parameters:

• st (Structure) - Structure to search for overlapping atoms
• ignore_hydrogens - Whether to ignore hydrogens.
• ignore_waters - Whether to ignore waters.
• dist_threshold - Atoms are considered overlapping if their centers are within this distance of each other.

Returns: list

Each value is a tuple containing the indices of overlapping atoms.

Return a string for the molecular formula in Hill notation for the st. The structure must contain only one molecule.

Parameters:

• st (Structure) - Find the molecular formula for this structure. Must contain only one molecule.

Returns: str

The molecular formula for st.

Return True if specified bond is rotatable, False otherwise.

A bond is considered rotatable if all of the following are true...

1. It is a single bond.
2. It is not adjacent to a triple bond.
3. It is not in a ring.
4. Neither atom is a hydrogen or other terminal atom.
5. Neither atom is a carbon or nitrogen with three hydrogens attached.

Parameters:

• bond (structure.StructureBond) - bond to test for rotatability.
• rings (list) - List of ring atom index lists. As an optimization, provide the (sorted) rings list from the find_rings function if you already have it. Otherwise, an SSSR calculation will be done.

Returns: bool

Is the bond rotatable?

Return an iterator for rotatable bonds (atomnum1, atomnum2) in the structure.

See the is_bond_rotatable function description for which bonds are considered rotatable.

Parameters:

• st (Structure) - The structure to search for rotatable bonds.
• rings (list) - List of ring atom index lists. As an optimization, provide the (sorted) rings list from the find_rings function if you already have it. Otherwise, an SSSR calculation will be done.
• max_size (int) - If specified, yield only rings that have up to this number of bonds. Use this option to exclude large rings; e.g. those in macrocycle-like molecules.

Returns: iterator of tuples

yields tuples of atom index pairs describing a rotatable bond in st.

Return the number of rotatable bonds in the Structure st. The count does not include trivial rotors such as terminal methyls, or rotors within rings.

Parameters:

• st (Structure) - The structure to search for rotatable bonds.
• rings (list of lists of ints) - List of ring atom index lists. As an optimization, provide the (sorted) rings list from the find_rings function if you already have it. Otherwise, an SSSR calculation will be done.
• max_size (int) - If specified, yield only rings that have up to this number of bonds. Use this option to exclude large rings; e.g. those in macrocycle-like molecules.

Returns: int

The number of rotatable bonds in st.

Iterate over hydrogen bond between the atoms specified by the atom_set and the other atoms in st. Each yielded item is a tuple of (atom-index-1, atom-index-2).

NOTE: This function has been updated to simply act as a wrapper to hbond.get_hydrogen_bonds to ensure that hbonds are determined consistently.

Parameters:

• st (Structure) - The structure to search for H-bonds.
• atoms (list of int or None) - A list of atom indices (or _StructureAtom objects) to analyze. If not specified, then all H-bonds present in the structure are returned.

Returns: list of (_StructureAtom, _StructureAtom)

list of (donor atom object, acceptor atom object) for each hydrogen bond identified.

Calculate the the number of hydrogen bonds in st.

If atoms is specified, only consider interactions between atoms indexes in the list and atoms outside the list.

NOTE: This function is now simply a wrapper to the more flexible schrodinger.structutils.interactions.hbond.get_num_hbonds.

Parameters:

• st (Structure) - The structure to search for H-bond.
• atoms (list) - A list of atom indices (or _StructureAtom objects) to count the number of H-bond to.

Returns: int

Number of H-bonds between atoms and other atoms in st.

Find atoms in the structure that are equivalent. For example, all three hydrogens on a methyl group are equivalent.

Returns a list, each value of which is a list of atoms that are equivalent.

Parameters:

• st (Structure) - The structure to search for equivalent atoms.
• span_molecules (bool) - If True, don't consider molecules to be separate entities. If False, constructs global equivalence classes for all atoms in a ct, but will never return an equivalence class across molecules.

Returns: list

Each value is a list of indices of equivalent atoms.

Calculate the solvent-accessible surface area (SASA) for the whole structure, or an atom subset, and returns a list of floats.

Parameters:

• st (Structure) - Structure for which SASA is desired.
• atoms (list) - List of atom indices or of _StructureAtom objects for the atoms to count. If None, calculates SASA for all atoms. (default: None)
• cutoff (float) - Atoms within this distance of atoms will be considered for occlusion. Requires atoms to be specified. (default: 8.0A)
• probe_radius (float) - Probe radius, in units of angstroms, of the solvent molecule. (default: 1.4A)
• resolution (float) - Resolution to use. Decreasing this number will yield better results, increasing it will speed up the calculation. NOTE: This is NOT the same option as Maestro's surface resolution, which uses a different algorithm to calculate the surface area. (default: 0.2)
• exclude_water (bool) - If set to True then explicitly exclude waters in the method. This option is only works when 'atoms' argument is passed. (default: False)

Returns: list

A list of solvent accessible surface area of selected atoms in st.

Calculate the solvent-accessible surface area (SASA) for the whole structure, or an atom subset, and then group them by residue.

Parameters:

• st (Structure) - Structure for which SASA is desired.
• atoms (list) - List of atom indices or of _StructureAtom objects for the atoms to count. If None, calculates SASA for all atoms. (default: None)
• cutoff (float) - Atoms within this distance of atoms will be considered for occlusion. Requires atoms to be specified. (default: 8.0A)
• probe_radius (float) - Probe radius, in units of angstroms, of the solvent molecule. (default: 1.4A)
• resolution (float) - Resolution to use. Decreasing this number will yield better results, increasing it will speed up the calculation. NOTE: This is NOT the same option as Maestro's surface resolution, which uses a different algorithm to calculate the surface area. (default: 0.2)
• exclude_water (bool) - If set to True then explicitly exclude waters in the method. This option is only works when 'atoms' argument is passed. (default: False)

Returns: list

a list of solvent accessible surface area of residues (ordered by connectivity) within st.

Calculate the solvent-accessible surface area (SASA) for the whole structure, or an atom subset.

Parameters:

• st (Structure) - Structure for which SASA is desired.
• atoms (list) - List of atom indices or of _StructureAtom objects for the atoms to count. If None, calculates SASA for all atoms. (default: None)
• cutoff (float) - Atoms within this distance of atoms will be considered for occlusion. Requires atoms to be specified. (default: 8.0A)
• probe_radius (float) - Probe radius, in units of angstroms, of the solvent molecule. (default: 1.4A)
• resolution (float) - Resolution to use. Decreasing this number will yield better results, increasing it will speed up the calculation. NOTE: This is NOT the same option as Maestro's surface resolution, which uses a different algorithm to calculate the surface area. (default: 0.2)
• exclude_water (bool) - If set to True then explicitly exclude waters in the method. This option is only works when 'atoms' argument is passed. (default: False)
• exclude_atoms (list) - aid of atoms that you don't want in SASA caluclation useful for FEP-type systems where a second 'image' of a molecules is present

Returns: float

The solvent accessible surface area of the selected atoms within st.

Simple function interface for AslLigandSearcher class.

Parameters:

• st (Structure) - Structure to search.

Returns: list

a list of Ligand instances for putative ligands within st.

Get the x, y, z coordinates for the center of mass. This can be limited to a subset of atoms. NOTE: Periodic boundary conditions (PBC) are NOT honored.

Parameters:

• st (Structure) - The structure used for calculating COM.
• atom_indices (List) - List of atom indices. Limit calculations to supplied atoms. If None, performs calculations on all atoms. (Default: None)

Returns: numpy array

x, y, and z coordinates for the center of mass

Raises:

• ValueError - If the atom_indices is neither a list nor None. Also if an empty list is passed in.

Calculate the principal moments of inertia for a list of atoms. This is calculated with respect to the x, y, and z coordinates of the atom's center of mass.

Parameters:

• struct (Structure) - If given the moments will be calculated for the entire structure. This overrides any atoms given with the atoms keyword. Either atoms or structure must be given.
• atoms (list) - list of schrodinger.structure._StructureAtom objects. Atom objects to compute the tensor for. Either atoms or structure must be given.
• massless (bool) - True of the calculations should be independent of the atomic masses (all mass=1), False (default) if atomic mass should be used.

Returns: tuple

A tuple of (eigenvalues, eigenvectors) of the inertial tensor. The eigenvalues are the principle moments of inertia and are a list of length 3 floats. The eigenvectors are a list of lists, each inner list is a list of length 3 floats.

Find the shortest path of bonded atoms that connects atom1 to atom2

The conversion of this routine to use networkx rather than scipy resulted in a dramatic reduction in both time and memory usage.

Parameters:

• struct (schrodinger.structure.Structure) - The structure containing the atoms index1 and index2
• index1 (int) - The index of the first atom in the path
• index2 (int) - The index of the second atom in the path

Returns: list

A list of atoms that connect atom index1 to atom index2 along the shortest bond path. Index1 will be the first item in the list and index2 will be the last. The second item in the list will be bonded to index1, the third will be bonded to the second, etc. If index1 == index2, a single item list is returned: [index1]

Raises:

• ValueError - if index1 and index2 are not part of the same molecule
• MemoryError - if the system is too large

Calculate the average structure between the given conformers.

Parameters:

• sts (Iterable of structure.Structure objects) - Structures to average

Returns: structure.Structure

Average structure

Find the maximum substructure that is common between all specified CTs. If any of the structures matches the substructure SMARTS more than once, then all matches are reported - that is why output a "triple" list. Outer list represents input structure, next list represents matches, and inner list is list of atom indices for that match. It's up to the calling code to decide which of the multiple matches to use (one method is to use the one whose center-of-mass is closest to the COM of the whole ligand). NOTE: This function becomes exponentioally slow with larger number of structures. Recommened maximum around 30 structures.

Parameters:

• sts (Iterable of structure.Structure objects) - Structures to average
• atomTyping (int) - Atom typing scheme to use. For list of available schemes, see $SCHRODINGER/utilities/canvasMCS -h

Returns: List of list of list of ints

Substructure atoms from each structure. Outer list represents input structures - in order of input; middle list represents matches, inner list represents atom indices for that match.

Find the maximum common substructures for each pair of the given CTs. NOTE: This function becomes exponentioally slow with larger number of structures. Recommened maximum around 30 structures.

Parameters:

• sts (Iterable of structure.Structure objects) - Structures to average
• atomTyping (int) - Atom typing scheme to use. For list of available schemes, see $SCHRODINGER/utilities/canvasMCS -h

Returns: List of int lists

Substructure atoms from each structure

Groups the atoms by molecule connectivity. Returns a list of atom groups. Each group is a list of atoms that are in the same "molecule" - that are bonded to each other, counting only atoms in specified list. If multiple atoms are in the same molecule, but are separated by atoms that are not in the list (e.g. 2 covalent ligands bound to same protein), they will be grouped separately.

Parameters:

• st (structure.Structure) - Structure that atoms are from.
• atoms (list of ints) - List of atom indices that are to be grouped.

Return a set of property names that are common to all selected structures.

Parameters:

• sts (Iterable of structure.Structure objects) - Structures to analyze

Returns: list of str

List of property data names