schrodinger.application.matsci.clusterstruct module¶
Functions to aid in pulling dimers or clusters of nearest neighbors from a larger structure. Also functions for replacing atoms in neighboring molecules with partial charges for Jaguar calculations.
Copyright Schrodinger, LLC. All rights reserved.
-
class
schrodinger.application.matsci.clusterstruct.
Neighbor
(home_atom, neighbor_atom, dsq)¶ Bases:
tuple
-
__contains__
¶ Return key in self.
-
__init__
¶ Initialize self. See help(type(self)) for accurate signature.
-
__len__
¶ Return len(self).
-
count
(value) → integer -- return number of occurrences of value¶
-
dsq
¶ Alias for field number 2
-
home_atom
¶ Alias for field number 0
-
index
(value[, start[, stop]]) → integer -- return first index of value.¶ Raises ValueError if the value is not present.
-
neighbor_atom
¶ Alias for field number 1
-
-
class
schrodinger.application.matsci.clusterstruct.
SpeciesData
(struct, smiles)¶ Bases:
object
Tracks information about each chemically distinct molecule in a system
-
__init__
(struct, smiles)¶ Create a SpeciesData instance
Parameters: - struct (
schrodinger.structure.Structure
) – The structure of this species - smiles (str) – The unique smiles string for this species
- struct (
-
addMember
(stindex, molnumber)¶ Add a new member of this species
Parameters: - stindex (int) – The structure index this member comes from. It is up to the calling code to generate and make use of this value.
- molnumber (int) – The molecule number in the structure that is a member of this species
-
isMember
(stindex, molnumber)¶ Check if a molecule is a member of this species
Parameters: - stindex (int) – The structure index this molecule comes from.
- molnumber (int) – The molecule number that is being checked
-
addCharges
(struct, prop='r_j_ESP_Charges')¶ Add atomic charge information to this SpeciesData object (does not actually add the charges as properties to structures). The element and charge for every atom are stored as a tuple in the charges list. The element is stored to help ensure that any future structure the charges are applied to has the same atom ordering as struct.
Parameters: - struct (
schrodinger.structure.Structure
) – The structure of this species. Used to determine the element of each atom and the charge of each atom. - prop (str) – The property name to use to obtain charges from each atom in struct
- struct (
-
getSampleStructure
(struct_iterator)¶ Get a sample structure for this species
Parameters: struct_iterator (iterable) – An iterable of schrodinger.structure.Structure
objects used to create this SpeciesData objectReturn type: schrodinger.structure.Structure
Returns: A structure object representing a molecule of this species
-
-
schrodinger.application.matsci.clusterstruct.
create_pbc
(struct)¶ Create an infrastructure PBC
Parameters: struct ( schrodinger.structure.Structure
) – The input structure, should have the Chorus box properties setReturn type: schrodinger.infra.structure.PBC
Returns: The infrastructure PBC created from the Chorus box properties Raises: ValueError – If the Chorus box properties are not set
-
schrodinger.application.matsci.clusterstruct.
create_distance_cell
(struct, distance, pbc=None)¶ Create an infrastructure Distance Cell. If struct has the Chorus box properties, the Distance Cell will be PBC-aware.
Parameters: - struct (
schrodinger.structure.Structure
) – The input structure, may have the Chorus box properties - distance (float) – The cutoff for finding nearest neighbor atoms
- pbc (
schrodinger.infra.structure.PBC
) – The infrastructure PBC for this structure. If not provided, an attempt will be made to create one from the Chorus box properties set on the structure - if this attempt fails, a non-PBC DistanceCell will be created.
Return type: schrodinger.infra.structure.DistanceCell
, pbcReturns: An infrastructure Distance Cell that accounts for the PBC, and the pbc used to create it. If no pbc was used, pbc=None. If the pbc was passed in, the same pbc is passed out unchanged.
- struct (
-
schrodinger.application.matsci.clusterstruct.
get_extracted_atom_index
(atom_indexes, index)¶ Get the index of the atom that has atom.index = index in a new structure that would be created by extracting the atoms in atom_indexes
Parameters: - atom_indexes (list of int) – The atom indexes that will be extracted to form a new structure
- index (int) – The atom index of the atom of interest
Return type: int or None
Returns: The new index of the atom in the extracted structure, or None if index is not found in atom_indexes
-
class
schrodinger.application.matsci.clusterstruct.
Dimer
(stindex, mol1, mol2, neighbor_info, pbc=None)¶ Bases:
object
Class to hold and process a pair of neighboring molecules.
-
__init__
(stindex, mol1, mol2, neighbor_info, pbc=None)¶ Create a Dimer object
Parameters: - stindex (int) – The index of the structure this dimer comes from
- mol1 (int) – The molecule number in the structure of the first molecule in this dimer
- mol2 (int) – The molecule number in the structure of the second molecule in this dimer
- neighbor_info (
Neighbor
) – The Neighbor information for this dimer - pbc (
schrodinger.infra.structure.PBC
) – The PBC object to use for this dimer, if any
-
evaluateSpeciesCriterion
(crit_species, crit, species)¶ Check whether this dimer meets the species criterion - sets the meets_species_criterion property.
Parameters: - crit_species (
SpeciesData
or None) – The species the criterion applies to. Use None if there are no criteria - the dimer will be marked as meeting all criteria - crit (str) – The criterion - should be one of the constants NO_MOLS, ONE_ONLY_MOL, AT_LEAST_ONE_MOL, TWO_MOLS
- species (dict) – The dictionary containing information for all species.
Keys are unique SMILES strings for a species, values are
SpeciesData
for the species with that SMILES string.
- crit_species (
-
getPairStructure
(struct)¶ Create the dimer structure
Parameters: struct ( schrodinger.structure.Structure
) – The structure containing the dimer moleculesReturn type: schrodinger.structure.Structure
Returns: The structure object for the dimer
-
getClusterStructure
(struct, cell=None, distance=None, heavy_only=False)¶ Get a structure that is the dimer surrounded by all nearest neighbor molecules. The dimer and all molecules are positioned at their nearest neighbor images to the original position of the first molecule in the dimer.
Parameters: - struct (
schrodinger.structure.Structure
) – The structure containing this Dimer and all neighbor molecules - cell (
schrodinger.infra.structure.DistanceCell
) – The DistanceCell to use when finding nearest neighbors. If not given, will be calculated based on struct and distance. Either cell or distance must be given. - distance (float) – The distance to use when creating a new distance cell if needed. Either cell or distance must be given.
- heavy_only (bool) – Use only heavy atom distances when finding the cluster
Return type: Returns: The structure of the dimer with nearest neighbor molecules. The dimer molecules appear first in the cluster.
- struct (
-
getPeriodicPairStructure
(struct)¶ Create a dimer structure for a pair of molecules that takes into account the periodic boundary condition.
If | represents a cell boundary, and …. represents some long distance, imagine two molecules X and Y on opposite sides of the cell.
Y|X….Y|X
We need to extract coordinates for Y that represent the Y|X case, not the X….Y case.
Parameters: struct ( schrodinger.structure.Structure
) – The structure containing the dimer moleculesReturn type: schrodinger.structure.Structure
Returns: The structure object for the dimer
-
getNonPeriodicPairStructure
(struct)¶ Create a dimer structure for a pair of molecules in a non-periodic system
Parameters: struct ( schrodinger.structure.Structure
) – The structure containing the dimer moleculesReturn type: schrodinger.structure.Structure
Returns: The structure object for the dimer
-
-
schrodinger.application.matsci.clusterstruct.
find_atoms_closest_to_atoms
(struct, atoms, cell, only_greater=False, heavy_only=False)¶ Find all the atoms that are within a certain distance of the provided atoms, returning information about those atoms.
Parameters: - struct (
schrodinger.structure.Structure
) – The structure object containing the atoms to search - atoms (list of int or
schrodinger.structure._StructureAtom
) – The list of atoms to find atoms near. Can be atom objects or integer indexes. If this list contains hydrogen atoms, they will still be used even if heavy_only=True. - cell (
schrodinger.infra.structure.DistanceCell
) – The distance cell to use for finding nearby atoms - only_greater (bool) – Whether to only find nearby atoms in molecules with indexes greater than the molecule they are close to
- heavy_only (bool) – Return only heavy atoms that are close to the given atoms. This parameter only affects atoms found, it has no effect on the list of atoms provided in the atoms parameter.
Return type: dict
Returns: Dictionary with keys that are molecule numbers and values that are a list of
Neighbor
objects for each atom in that molecule that is nearby one of the atoms in the atoms list. Atoms that are nearby multiple atoms in the atoms list will appear multiple times, once for each atom it is nearby.- struct (
-
schrodinger.application.matsci.clusterstruct.
find_molecules_closest_to_atoms
(struct, atoms, cell, only_greater=False, heavy_only=False)¶ Find all the molecules that are within a certain distance of the provided atoms, returning information about those molecules
Parameters: - struct (
schrodinger.structure.Structure
) – The structure object containing the atoms to search - atoms (list of int or
schrodinger.structure._StructureAtom
) – The list of atoms to find molecules near. Can be atom objects or integer indexes. This list of atoms is not affected by the heavy_only paramter, it may contain H atoms and those atoms will be used. - cell (
schrodinger.infra.structure.DistanceCell
) – The distance cell to use for finding nearby molecules - only_greater (bool) – Whether to only find nearby molecules with indexes greather than the molecule they are close to
- heavy_only (bool) – Use only heavy atoms when finding close molecules. This only affects the found molecules and has no effect on the provided atom list in atoms
Return type: dict
Returns: Dictionary with keys that are molecule numbers and values are
Neighbor
objects for the atom in that molecule that is closest to one of the atoms in the atoms list- struct (
-
schrodinger.application.matsci.clusterstruct.
get_dimers_with_molecule
(struct, molecule, cell, pbc=None, only_greater=False, struct_index=0, heavy_only=False)¶ Get a Dimer object for every molecule within a given distance of the provided molecule
Parameters: - struct (
schrodinger.structure.Structure
) – The structure object containing the molecules to search - molecule (
schrodinger.structure._Molecule
) – The molecule to find dimers of - cell (
schrodinger.infra.structure.DistanceCell
) – The distance cell to use for finding nearby molecules - pbc (
schrodinger.infra.structure.PBC
) – The PBC object used to create the distance cell - only_greater (bool) – Whether to only find Dimers with molecules that have indexes greather than the provided molecule
- struct_index (int) – An index for the structure that is providing these dimers. This is passed to the Dimer class and can be used by calling routines to track Dimers from different structures.
- heavy_only (bool) – Use only heavy atoms when determining dimers
Return type: list of
Dimer
Returns: A
Dimer
object for each dimer that molecule forms- struct (
-
schrodinger.application.matsci.clusterstruct.
get_dimers_in_structure
(struct, cell=None, pbc=None, distance=None, struct_index=0, heavy_only=False)¶ Get a Dimer object for every dimer in struct
Parameters: - struct (
schrodinger.structure.Structure
) – The structure object containing the dimers to find - cell (
schrodinger.infra.structure.DistanceCell
) – The distance cell to use for finding dimers - pbc (
schrodinger.infra.structure.PBC
) – The PBC object used to create the distance cell - distance (float) – The distance to use in creating a distance cell if none is provided
- struct_index (int) – An index for the structure that is providing these dimers. This is passed to the Dimer class and can be used by calling routines to track Dimers from different structures.
- heavy_only (bool) – Use only heavy atoms when determining dimers
Return type: list of
Dimer
Returns: A
Dimer
object for each dimer that molecule formsRaises: RuntimeError – If neither cell nor distance are provided
- struct (
-
schrodinger.application.matsci.clusterstruct.
move_atoms_next_to_atom
(pbc, struct1, home_atom, struct2, neighbor_atom, moving_indexes=None)¶ Move a structure to be at the PBC image that is closest to home_atom. The atoms in the structure are moved as a single group so that they maintain their coordinates relative to each other.
Note: The difference between the method in this function and the pbc.getNearestImages() method for finding atom locations is that this function is guaranteed to move all atoms with the same vector. getNearestImages() is not and can potentially split groups of atoms into different images.
Parameters: - pbc (
schrodinger.infra.structure.PBC
) – The PBC object used to find images - struct1 (
schrodinger.structure.Structure
) – The structure object containing the home atom - home_atom (
schrodinger.structure._StructureAtom
) – The atom to move the atoms next to - struct2 (
schrodinger.structure.Structure
) – The structure object to move, should contain neighbor_atom. May be the same as struct1. - neighbor_atom (
schrodinger.structure._StructureAtom
) – The atom in struct2 that should be used to determine the movement vector - moving_indexes (list of int) – If None, all of struct2 will be moved. Otherwise, onl the atom indexes in this list will be moved.
- pbc (
-
schrodinger.application.matsci.clusterstruct.
contract_by_molecule
(struct, pbc=None, anchors=None)¶ Contract each molecule in a structure so that all the atoms within a given molecule are at the same PBC image. In this case, “same PBC image” means that the molecule has chemically correct coordinates even if the PBC is removed. Thus, it will turn |-- --| into | –|– where | = pbc wall, - = atoms
Algorithm: Starting at an arbitrary atom (or the anchor atom if provided, #1, contract (move to nearest image) all atoms bound to #1. Keep a list of all atoms contracted. Pick an atom that has been contracted and repeat, adding its neighbors to the list of contracted atoms. Continue until the list of contracted atoms has been exhausted. If all atoms in the structure have been contracted, then work is complete. If some atoms in the structure have not been contracted, this means that there is more than one molecule. Pick an arbitrary new uncontracted atom and return to the top of the Algorithm. Repeat this outer loop until all atoms have been contracted. This algorithm ensures that atoms are always being moved next to an atom they are bonded to rather than an atom that is nearby due to the PBC. It does NOT in any way move molecules near each other except by coincidence.
Parameters: - struct (
schrodinger.structure.Structure
) – The structure to modify - pbc (
schrodinger.infra.structure.PBC
) – The PBC to use in determining images - anchors (list) – List of atom indexes that should not be moved and that all other atoms should be contracted towards. Note that the use of anchors means that not all atoms will be moved to the same image if more than one anchor comes from the same molecule and the anchors are not in the same image.
Raises: IndexError – If an anchor index is not an atom index in struct
- struct (
-
schrodinger.application.matsci.clusterstruct.
contract_structure
(struct, pbc=None, cell=None, distance=10.0, contract_on_atoms=None, also_keep_stationary=False)¶ Contract a structure so that the entire structure has chemically sensible coordinates even if the PBC is removed - i.e. it uses only a single PBC image and would be suitable for a Jaguar calculation for instance. This involves two steps: 1) contracting each molecule so that the molecule itself is in a single image and then 2) contracting all molecules together so that they are all in the same image. In step 2 molecules close to a core set of atoms will be moved in such a way that preserves their closest possible approach to the core atoms. For computational speed optimization, molecules outside the specified cell/distance will be moved so that an arbitrary atom in the molecule is as close as possible to an arbitrary atom in the core. To avoid this, pass in a cell or distance that uses a large-enough distance that all molecules will fall inside that distance.
Parameters: - struct (
schrodinger.structure.Structure
) – The structure to modify - pbc (
schrodinger.infra.structure.PBC
) – The PBC to use in determining images - cell (
schrodinger.infra.structure.DistanceCell
) – The distance cell to use for finding closest approaches - distance (float) – The distance to use for finding closest approaches if cell is not provided
- contract_on_atoms (list of int) – List of atom indexes that form the core that all other molecules will be contracted towards in step 2. If not provided, the first molecule will be used. Note that these molecules might still move as part of the Step 1 process.
- also_keep_stationary (bool) – If contract_on_atoms is provided, setting this flag to True will ensure that these atoms do not move during the Step 1 contraction by molecule.
- struct (
-
schrodinger.application.matsci.clusterstruct.
create_dimer_structures
(struct, atoms, pbc=None, nearest_neighbors=None, cell=None, distance=None)¶ Create structures for each dimer that the atoms in the atoms list form
Parameters: - struct (
schrodinger.structure.Structure
) – The structure containing the dimers - atoms (list of int) – The atom indexes to find dimers for
- pbc (
schrodinger.infra.structure.PBC
) – The PBC to use in determining images - nearest_neighbors (dict) – Dictionary with keys that are molecule numbers and
values are
Neighbor
objects for the atom in that molecule that is closest to one of the atoms in the atoms list. Such a dictionary is provided by find_molecules_closest_to_atoms. - cell (
schrodinger.infra.structure.DistanceCell
) – The distance cell to use for finding dimers. Either distance or cell must be provided if nearest_neighbors is not provided. - distance (float) – The intermolecular distance to use for finding dimers if cell is not provided. Either distance or cell must be provided if nearest_neighbors is not provided.
Return type: list
Returns: A list of
schrodinger.structure.Structure
objects, one for each dimer foundRaises: RuntimeError – If none of nearest_neighbors, cell nor distance are provided
- struct (
-
schrodinger.application.matsci.clusterstruct.
create_nearest_neighbor_cluster
(struct, atoms, cell, pbc=None, heavy_only=False)¶ Return a structure that has the given atoms surrounded by their nearest neighbor molecules
Parameters: - struct (
schrodinger.structure.Structure
) – The input structure - atoms (list of int) – The atom indexes that will form the center of the cluster
- cell (
schrodinger.infra.structure.DistanceCell
) – The DistanceCell to use when finding nearest neighbors - pbc (
schrodinger.infra.structure.PBC
) – The PBC to use when finding nearest images if one should be used - heavy_only (bool) – Use only heavy atom distances when finding the cluster
Return type: Returns: A cluster that has the given atoms at the center and all nearest neighbors surrounding them. The given atoms appear first in the structure.
- struct (
-
schrodinger.application.matsci.clusterstruct.
create_non_pbc_cluster
(struct, molnumbers)¶ Create a cluster of the given molecules
Parameters: - struct (
schrodinger.structure.Structure
) – The structure to extract molecules from - molnumbers (list of int) – The molecule numbers of the molecules to extract
Return type: Returns: A cluster of molecules
- struct (
-
schrodinger.application.matsci.clusterstruct.
get_all_atoms_marked_as_neighbors
(struct)¶ Return a list of all atom objects in struct that are marked as neighbors
Parameters: struct ( schrodinger.structure.Structure
) – The structure to extract atoms fromReturn type: list Returns: A list of all atom objects marked with the NEIGHBOR_ATOM_PROP property
-
schrodinger.application.matsci.clusterstruct.
add_neighbor_charges_to_jaginput
(struct, qprop, jfile)¶ Add point charges that represent neighboring atoms to an existing jaguar input file. A point charge will be written for every atom that has the NEIGHBOR_ATOM_PROP set to True. The charges are added in a &pointch section.
Parameters: - struct (
schrodinger.structure.Structure
) – The structure to extract charges from - qprop (str) – The atom property to use as for the charge values
- jfile (str) – The path to the Jaguar input file
- struct (
-
schrodinger.application.matsci.clusterstruct.
set_neighbor_atoms_basis_set
(struct, basis, jfile)¶ Set all atoms marked as neighbors with the NEIGHBOR_ATOM_PROP property to use the provided basis set. The basis set is specified in an &atomic section.
Parameters: - struct (
schrodinger.structure.Structure
) – The structure to extract charges from - basis (str) – The basis set to use for neighbor atoms
- jfile (str) – The path to the Jaguar input file
- struct (
-
schrodinger.application.matsci.clusterstruct.
find_species
(structs)¶ Find all chemically distinct (as determined via unique SMILES strings) species in the given structures
Parameters: structs (list of schrodinger.structure.Structure
) – The structures to find species inReturn type: dict Returns: Keys are unique SMILES strings, values are SpeciesData objects for the species with that SMILES string
-
schrodinger.application.matsci.clusterstruct.
compute_esp_charges
(structs, basis, species=None, tpp=None, logger=None, quiet=False, opt=False)¶ Compute ESP charges for a representative example of each species found in structs.
Parameters: - structs (list of
schrodinger.structure.Structure
) – The structures to find species in to compute the charges of - basis (str) – The basis set to use when computing charges
- species (dict) – Keys are unique SMILES strings, values are SpeciesData objects for the species with that SMILES string. If not provided, will be computed.
- tpp (int) – The number of threads per Jaguar job. If not provided, -TPP will not be included in the Jaguar command - the job will run serially.
- logger (
logging.Logger
) – The logger to use, if any. If not provided and quiet=False, messages will be printed to the terminal - quiet (bool) – If True, do not print or log any messages.
- opt (bool) – Whether to perform a geometry optimization before computing charges
Return type: dict, list
Returns: Dict is the species - either those provided or those computed. List is the names of jobs that failed.
- structs (list of
-
schrodinger.application.matsci.clusterstruct.
populate_with_charges
(structs, species, prop='r_matsci_ESP_Charges')¶ For every molecule in structs, add an atom property that contains the previously computed charges for the species it belongs to.
This method expects the list of structs to be the same as the list that species was computed from.
Parameters: - structs (list of
schrodinger.structure.Structure
) – The structures to find species in to compute the charges of - species (dict) – Keys are unique SMILES strings, values are SpeciesData objects for the species with that SMILES string.
- prop (str) – The atom property to set with the new charge
Raises: RuntimeError – If things don’t match up, such as structs being shorter than expected, there being a different number of molecules in a given structure, the atoms not being in expected order in a molecule, or a molecule having a different number of atoms than expected.
- structs (list of
-
schrodinger.application.matsci.clusterstruct.
compute_and_populate_charges
(structs, basis, tpp=None, logger=None, quiet=False, species=None, opt=False)¶ Determine the unique chemical species of each molecule in structs, compute the ESP charges with Jaguar for each species and then apply those charges as atom properties to each atom in structs.
Parameters: - structs (list of
schrodinger.structure.Structure
) – The structures to find species in to compute the charges of - basis (str) – The basis set to use when computing charges
- tpp (int) – The number of threads per Jaguar job
- logger (
logging.Logger
) – The logger to use, if any. If not provided and quiet=False, messages will be printed to the terminal - quiet (bool) – If True, do not print or log any messages.
- species (dict) – Keys are unique SMILES strings, values are SpeciesData objects for the species with that SMILES string. If not passed in, will be determined automatically. Must correspond to the structures in structs.
- opt (bool) – Whether to perform a geometry optimization before computing charges
Return type: dict, list, str
Returns: Dict is the species computed. List is the names of ESP jobs that failed. str is any error message that occurred during the assignment of computed ESP charges to atoms in structs. If quiet=False, the names of failed jobs and msg will have already been logged.
- structs (list of