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.

class schrodinger.application.matsci.clusterstruct.Neighbor(home_atom, neighbor_atom, dsq)¶

Bases: tuple

__contains__(key, /)¶: Return key in self.

__len__()¶: Return len(self).

count(value, /)¶: Return number of occurrences of value.

dsq¶: Alias for field number 2

home_atom¶: Alias for field number 0

index(value, start=0, stop=9223372036854775807, /)¶

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(smiles=None, group_name=None)¶

Bases: object

Tracks information about each chemically distinct molecule in a system

TYPE_LABEL = 'Mols'¶

__init__(smiles=None, group_name=None)¶

Create a SpeciesData instance

Parameters

smiles (str or None) – The unique smiles string for this species
group_name (str or None) – The user-facing name of the species

__len__()¶

Return type: int
Returns: The number of molecules of this species

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

getSampleIndices()¶

Get the st and mol indices of a sample

Return type: tuple
Returns: Tuple of (st_index, mol_index)

getSampleMolNumber()¶

Get a sample molecule number for the species. Assumes that all members belong to a single structure.

Return int: A sample molecule index of this species

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 object
Return type: schrodinger.structure.Structure
Returns: A structure object representing a molecule of this species

getAllAtomIds(struct)¶

Get all atom ids belonging to this species in the passed structure. Assumes that all members belong to a single structure.

Parameters: struct (structure.Structure) – The structure to get atom ids in
Return list(int): List of atom ids

getExampleMemberTag()¶

Get an additional tag that gets an example molecule number for this species

Return type: str
Returns: The tag for this species

class schrodinger.application.matsci.clusterstruct.AtomGroupData(smiles=None, group_name=None)¶

Bases: schrodinger.application.matsci.clusterstruct.SpeciesData

Tracks information about each group of atoms in the system

TYPE_LABEL = '#'¶

addMember(stindex, atom_ids)¶

Add a new member of this species

Parameters

stindex (int) – The structure index this member comes from.
atom_ids (list) – The list of atom indices in the structure that are member of this species

isMember(stindex, atom_ids)¶

Check if passed atom ids are member of the species

Parameters

stindex (int) – The structure index this member comes from.
atom_ids (list) – The list of atom indices to check in the structure that are member of this species

Returns

Whether the passed atom ids are member

Return type

bool

getSampleIndices()¶

Get the st and atom indices of a sample

Return type: tuple
Returns: Tuple of (st_index, atom_indices)

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 object
Return type: schrodinger.structure.Structure
Returns: A structure object representing a molecule of this species

getExampleMemberTag()¶

Get an additional tag that gets an example atom number for this species

Return type: str
Returns: The tag for this species

__init__(smiles=None, group_name=None)¶

Create a SpeciesData instance

Parameters

smiles (str or None) – The unique smiles string for this species
group_name (str or None) – The user-facing name of the species

__len__()¶

Return type: int
Returns: The number of molecules of this species

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

getAllAtomIds(struct)¶

Get all atom ids belonging to this species in the passed structure. Assumes that all members belong to a single structure.

Parameters: struct (structure.Structure) – The structure to get atom ids in
Return list(int): List of atom ids

getSampleMolNumber()¶

Get a sample molecule number for the species. Assumes that all members belong to a single structure.

Return int: A sample molecule index 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 set
Return 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, pbc

Returns

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. The distance cell has a size property that gives the distance it was created with.

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.

getPairStructure(struct)¶

Create the dimer structure

Parameters: struct (schrodinger.structure.Structure) – The structure containing the dimer molecules
Return type: schrodinger.structure.Structure
Returns: The structure object for the dimer

getClusterStructure(struct, cell=None, distance=None, heavy_only=False, by_com=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
by_com (bool) – If True, use center of masses when determining distance

Return type

schrodinger.structure.Structure

Returns

The structure of the dimer with nearest neighbor molecules. The dimer molecules appear first in the cluster.

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 molecules
Return 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 molecules
Return type: schrodinger.structure.Structure
Returns: The structure object for the dimer

class schrodinger.application.matsci.clusterstruct.ComInfo(tracker, struct, cell)¶

Bases: tuple

__contains__(key, /)¶: Return key in self.

__len__()¶: Return len(self).

cell¶: Alias for field number 2

count(value, /)¶: Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)¶

Return first index of value.

Raises ValueError if the value is not present.

struct¶: Alias for field number 1

tracker¶: Alias for field number 0

class schrodinger.application.matsci.clusterstruct.COMTracker(atom_struct)¶

Bases: object

When using the center of mass to measure between molecules, we do the following: - Create a new structure without any atoms except for a single atom at each molecule’s center of mass (a “COM structure”) - Use this COM structure for all measurements/clustering - Once the dimers/clusters have been determined using the center of mass atoms, use the positions of the center of mass atoms to place the original molecules at the new center of mass positions.

The key to the COM structure is that center of mass atoms have the same atom index as the molecule index of the molecule in the atom structure they represent, and their position indicates the new position of the of the corresponding atomistic molecule.

This class manages the COM structure and various manipulations

ORIGINAL_MOLNUM_PROP = 'i_matsci_original_molecule_number'¶

__init__(atom_struct)¶

Create a COMTracker object

Parameters: atom_struct (schrodinger.structure.Structure) – The atom structure that the COM structure will mimic

addCOMAtoms()¶: Add an atom to the COM structure at the center of mass of each molecule in the atom structure

createMimic(struct)¶

Create an empty structure object with the same title and properties as struct

Parameters: struct (schrodinger.structure.Structure) – The structure to create a mimic of
Return type: schrodinger.structure.Structure
Returns: An empty structure with the same title and properties as the input structure

convertCOMToAtomCluster(com_cluster)¶

Given a structure with center of mass atoms, create a new structure with the original molecules located at their corresponding center of mass

Parameters: com_cluster (schrodinger.structure.Structure) – The COM structure to create atomistic structure of
Return type: schrodinger.structure.Structure
Returns: An atomistic structure with molecules located at the same positions as the center of mass atoms in com_cluster

schrodinger.application.matsci.clusterstruct.create_center_of_mass_info(struct, distance)¶

Create information needed for clustering by center of mass

Parameters

struct (structure.Structure) – The atomistic structure to use to find center of masses
distance (float) – The distance for the distance cell to create

Return type

ComInfo

Returns

Center of mass info - a tracker, structure and distance cell

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.

schrodinger.application.matsci.clusterstruct.find_molecules_closest_to_atoms(struct, atoms, cell, only_greater=False, heavy_only=False, by_com=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
by_com (bool or ComInfo) – If True, create the info needed to find neighbors by center of mass instead of atom distance. If ComInfo, this is the pre-calculated data to use for center of mass distance. If False, do not find neighbors by center of mass. heavy_only is ignored if by_com is not False.

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

schrodinger.application.matsci.clusterstruct.get_dimers_with_molecule(struct, molecule, cell, pbc=None, only_greater=False, struct_index=0, heavy_only=False, by_com=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
by_com (bool or ComInfo) – If True, create the info needed to find neighbors by center of mass instead of atom distance. If ComInfo, this is the pre-calculated data to use for center of mass distance. If False, do not find neighbors by center of mass. heavy_only is ignored if by_com is not False.

Return type

list of Dimer

Returns

A Dimer object for each dimer that molecule forms

schrodinger.application.matsci.clusterstruct.get_dimers_in_structure(struct, cell=None, pbc=None, distance=None, struct_index=0, heavy_only=False, by_com=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
by_com (bool or ComInfo) – If True, create the info needed to find neighbors by center of mass instead of atom distance. If ComInfo, this is the pre-calculated data to use for center of mass distance. If False, do not find neighbors by center of mass. heavy_only is ignored if by_com is not False.

Return type

list of Dimer

Returns

A Dimer object for each dimer that molecule forms

Raises

RuntimeError – If neither cell nor distance are provided

schrodinger.application.matsci.clusterstruct.move_atoms_next_to_xyz(pbc, home_point, struct, moving_point, moving_indexes=None)¶

Move a structure to be at the PBC image that is closest to xyz. 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
home_point (list[float]) – The position to move the atoms next to
struct (schrodinger.structure.Structure) – The structure object to move
moving_point (list[float]) – The vector by which struct is moved is the vector that moves moving_point to its image closest to home_point.
moving_indexes (list of int) – If None, all of struct will be moved. Otherwise, only the atom indexes in this list will be moved.

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

If no PBC exists, no action will be taken.

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

schrodinger.application.matsci.clusterstruct.find_molecule_fragments(struct, mol_indices)¶

Create a graph representing fragments of the molecule that are connected with non-periodic bonds, and find all periodic bonds in the molecule

Parameters

struct (structure.Structure) – The input structure
mol_indices (list) – The atom indices for the molecule

Return type

networkx.Graph, list

Returns

Tuple of networkx.Graph containing connected mol fragments, and a list containing atom indices of periodic pairs

schrodinger.application.matsci.clusterstruct.contract_by_molecule2(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

If no PBC exists, no action will be taken.

The difference between this function and contract_by_molecule is that: 1. This function doesn’t move anything if the molecule is already whole. For instance, it doesn’t unravel slabs 2. This function assembles the fragments from the center out, yielding better results for more complicated cases like a slab split into 5 fragments

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

ValueError – If something goes wrong in the code. We should never have multiple components that are all anchored. Anchored components should be connected before moving components.

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.

schrodinger.application.matsci.clusterstruct.contract_structure2(struct, pbc=None, cell=None, distance=10.0, contract_on_atoms=None, also_keep_stationary=False, mol_nums=None)¶

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 is done by: 1) Contracting each molecule so that the molecule itself is in a single image. 2) Finding atoms close to “contract_on_atoms” and moving them close, then finding atoms that are close to the newly moved atoms and moving them close, and so on until no new atoms are found. 3) If any molecules remain, they are moved to be close to the centroid of the contracted molecules in step 2.

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.
mol_nums (iterable or None) – If supplied, only move these molecules in steps 2 and 3. NOTE: contract_by_molecule is unaffected by this.

schrodinger.application.matsci.clusterstruct.contract_structure_pfx(struct, contract_on_atoms=None)¶

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 calls desmond periodic fix module (pfx) (unlike other similar functions that are native Python). If no contract on atoms are set, this function behaves like contract_by_molecule functions, meaning that it doesn’t try to cluster around any atoms.

Parameters

struct (schrodinger.structure.Structure) – The structure to modify
contract_on_atoms (list[int] or None) – List of atom indexes that form the core that all other molecules will be contracted towards in step 2.

schrodinger.application.matsci.clusterstruct.contract_slab_z(struct, layer_thickness=4)¶

Unwrap a normal surface in the Z direction so that the entire surface is a single group on one side of the PBC rather than split across the top and bottom of the PBC.

Parameters

struct (structure.Structure) – Structure to be modified
layer_thickness (float) – The thickness of the layer (Angstroms) of atoms to move to a new image at each iteration. This value should be small enough that it is smaller than any anticipated vacuum gap in the cell.

Return type

str or None

Returns

If not successful, return error message

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 found

Raises

RuntimeError – If none of nearest_neighbors, cell nor distance are provided

schrodinger.application.matsci.clusterstruct.create_nearest_neighbor_cluster(struct, atoms, cell, pbc=None, heavy_only=False, by_com=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
by_com (bool or ComInfo) – If True, create the info needed to find neighbors by center of mass instead of atom distance. If ComInfo, this is the pre-calculated data to use for center of mass distance. If False, do not find neighbors by center of mass. heavy_only is ignored if by_com is not False.

Return type

schrodinger.structure.Structure

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.

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

schrodinger.structure.Structure

Returns

A cluster of molecules

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 from
Return 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. If qprop is ESP_ARGPARSE_VALUE, ESP_CHARGE_PROP will be used instead. This allows restart jobs to use previously-computed charges without recomputing them.
jfile (str) – The path to the Jaguar input file

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

schrodinger.application.matsci.clusterstruct.find_mol_species_from_rdmol(patterns)¶

Finds unique molecule species.

Parameters: patterns (list(schrodinger.application.matsci.rdpattern.Pattern)) – The list of pattern to calculate species from.
Returns: dict
Return type: dictionary where the key is the unique smiles for each species and value is the species data

schrodinger.application.matsci.clusterstruct.find_res_species(patterns)¶

Finds unique residue species.

Parameters: patterns (list(schrodinger.application.matsci.rdpattern.Pattern)) – The list of pattern to calculate species from.
Returns: dict
Return type: dictionary where the key is the unique smarts for each species and value is the species data

schrodinger.application.matsci.clusterstruct.find_species(structs, naming_function=None)¶

Find all chemically distinct species in the given structures, as determined via unique SMILES strings or unique names.

If naming_function is supplied, species are grouped using names, unless the function returns None, in which case the code falls back to using SMILES.

Parameters

structs (list of schrodinger.structure.Structure) – The structures to find species in
naming_function (callable or None) – The function to call to get a name for each molecule. Should take a structure._Molecule object as argument and return a string

Return type

dict

Returns

Keys are unique SMILES strings or group names for species, values are SpeciesData objects for that species

schrodinger.application.matsci.clusterstruct.get_species_display_names(species)¶

Create a dictionary mapping the display name of species to the species

Parameters: species (iterable) – The species to get display names for
Return type: dict
Returns: dictionary containing species display names and species objects

schrodinger.application.matsci.clusterstruct.get_species_from_mol(all_species, mol_id)¶

Get the species that mol_id belongs to. Assumes that all members belong to a single structure.

Parameters

all_species (iterable) – All species to look in
mol_id (int) – The mol id to get the species for

Raises

RuntimeError – If the mol_id doesn’t belong to any of the passed species

Return type

SpeciesData

Returns

The species that contains mol_id

schrodinger.application.matsci.clusterstruct.get_example_mol_tag(species_data)¶

Get an additional tag that gets an example molecule number for this species

Parameters: species_data (SpeciesData) – The data for this species
Return type: str
Returns: The tag for this species

schrodinger.application.matsci.clusterstruct.get_base_esp_jobname()¶

Get the base name that will be used for esp jobs

Return type: str
Returns: The base name for esp jobs

schrodinger.application.matsci.clusterstruct.get_species_masses(struct, **kwargs)¶

Calculate the mass of each species in a Desmond system.

Parameters

struct (schrodinger.structure.Structure) – Structure to get masses of
kwargs – Keyword arguments to be use when converting the structure into an RDKit Pattern for analysis.

Return type

dict(str=float)

Returns

dictionary whose keys are the species’s chemical formulae and whose values are the total mass of that species (in Daltons)

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 or None) – The basis set to use when computing charges. None will use the default Jaguar basis set.
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.

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.

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 or None) – The basis set to use when computing charges. None will use the default Jaguar basis set.
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.

schrodinger.application.matsci.clusterstruct.get_cluster_atom_ids(distance_cell, xyz)¶

Get ids of atoms surrounding xyz coordinate

Parameters

distance_cell (infra.structure.DistanceCell) – The distance cell
xyz (list) – The coordinates of the point to get the cluster around

Return type

list

Returns

List of atom ids