schrodinger.application.matsci.fragments module¶

Classes and functions to help with workflows that fragment multiple reactions such as the bond dissociation and adsorption energy workflows.

schrodinger.application.matsci.fragments.split_spin_state(spinstate)¶

Split a spin state such as ‘S1’ into (‘S’, 1)

Parameters: spinstate (str) – The string to split - should be in the form of a single first letter followed by an integer
Return type: (str, int)
Returns: The leading string character and the following int

schrodinger.application.matsci.fragments.spin_multiplicity(struct, charge=0)¶

Return the multiplicity of the given structure with the given charge. Structures will either be singlets (even number of electrons) or doublets (odd number). No attempt is made to determine multiplicity beyond that.

Parameters

struct (structure.Structure) – The structure to check
charge (int) – The charge on the structure

Return type

int

Returns

1 if there is an even number of electrons, 2 if it is odd

schrodinger.application.matsci.fragments.label_bond(bond, value)¶

Add a label to a bond that will show in the workspace

Parameters

bond (structure._StructureBond) – The bond to label
value (float) – The value to label the bond with

schrodinger.application.matsci.fragments.set_pt_subgroup_info(struct, name, collapsed=True)¶

Set the properties on the structure to have it incorporate in the proper subgroup

Parameters

struct (schrodinger.structure.Structure) – The structure to set the properties one
name (str) – The name of the subgroup
collapsed (bool) – Whether the subgroup should be collapsed

class schrodinger.application.matsci.fragments.LoggerUser(*args, logger=None, **kwargs)¶

Bases: object

Mixin for classes that need to use a logger

__init__(*args, logger=None, **kwargs)¶

Create the LoggerUser

Parameters: logger (log.logger) – The logger to use

log(msg, **kwargs)¶

Log a message

Parameters: msg (str) – The message to log

Additional keyword arguments are passed to the textlogger.log_msg function

class schrodinger.application.matsci.fragments.BondEnergies¶

Bases: object

Keep track of a set of bond energies

__init__()¶: Create a BondEnergies instance

storeIfLowestEnergy(etype, energy)¶

Check an energy to see if it is the lowest energy of this type, and store it if it is

Parameters

etype (str) – The type of energy (an energy property name)
energy (float) – The energy to store if it is the lowest of this type

getEnergy(etype)¶

Get the lowest energy associated with the given type

Parameters: etype (str) – The type of energy (an energy property name)
Return type: float or numpy.inf
Returns: The lowest energy found for the given type. numpy.inf is returned if no energy of that type is found

getEnergies()¶

Get an iterator of all energy type/energy combinations

Return type: iterator
Returns: Each item is (energy type, energy)

hasFreeEnergy()¶

Check if free energies exist

Return type: bool
Returns: Whether free energy has been recorded

class schrodinger.application.matsci.fragments.BreakingBond(struct, bond, preserve_order=False)¶

Bases: object

Defines and tracks the information for a bond that breaks

__init__(struct, bond, preserve_order=False)¶

Create a BreakingBond object

Parameters

struct (schrodinger.structure.Structure) – The structure containing the breaking bond
bond (schrodinger.structure._StructureBond) – The bond that will be broken
preserve_order (bool) – Preserve the found order of fragments. If False, fragments will be sorted based on SMILES string.

getFragments(struct, bond)¶

Define the two fragments that will be created when the bond breaks

Parameters

struct (schrodinger.structure.Structure) – The structure containing the breaking bond
bond (schrodinger.structure._StructureBond) – The bond that will be broken

Return type

list

Returns

Each item of the list is a Fragment object defining one of the fragments that is created by breaking the bond - or each item is None if the bond is actually part of a macrocycle.

class schrodinger.application.matsci.fragments.Fragment(struct, indexes, targets)¶

Bases: object

A fragment of a structure that will be created after dissociation

__init__(struct, indexes, targets)¶

Create a Fragment object

Parameters

struct (schrodinger.structure.Structure) – The structure containing the fragment
indexes (list) – The list of atom indexes in struct to include in the fragment
targets (list) – The atom index(es) in struct that are part of this fragment and that are directly involved in the dissociation

getSMILESForFrag()¶

Get the smiles string and list of targets for this fragment. Note that this SMILES string will have an addition At atom at the point of dissociation. This is done to increase the robustness of the unique SMILES method. Without it, I have found that a benzene ring radical can have different unique SMILES strings depending on what atom the SMILES is on. Since we never generate a structure from these SMILES strings, the extra atom isn’t an issue.

Return type: (str, list) or (None, [])
Returns: (SMILES, list_of_targets). The SMILES string is the SMILES string for this fragment with an At atom at the dissociation point(s). Each item in list_of_targets is the atom index of a target atom (atom at the point of dissociation) using the atom index numbering in frag. (None, []) is returned if the SMILES string fails to generate.

class schrodinger.application.matsci.fragments.UniqueTracker(struct, keydict, key, options, basename='fragment', targets=None, parent_indexes=None, charge=None, mult=None, tddft=False, vertical=False, write_input_ok=True, **kwargs)¶

Bases: schrodinger.application.matsci.fragments.LoggerUser

Tracks the information for, and creates the Jaguar job for, a unique fragment. Since the same fragment may be generated by multiple dissociations, we use this class to track each unique fragment.

__init__(struct, keydict, key, options, basename='fragment', targets=None, parent_indexes=None, charge=None, mult=None, tddft=False, vertical=False, write_input_ok=True, **kwargs)¶

Create a UniqueTracker object

Parameters

struct (schrodinger.structure.Structure) – The structure containing the leaving ligand
keydict (dict) – The dictionary containing the base set of keywords
key (str) – a unique identifier for this unique fragment
options (argparse.Namespace) – The command line options
basename (str) – The base name to use for files for this fragment. Will be used as the fragment_type and combined with key to form the file base names.
targets (list) – The atom indexes in struct that are at the dissociation point
parent_indexes (list) – The atom indexes with the parent atom numbering for the atoms in struct. Note this will only be valid for one specific reaction, so must be overwritten in any NonUniqueTracker objects that track this instance.
charge (int) – The charge of the fragment - will be used with the molchg keyword
mult (int) – The multiplicity of the fragment - will be used with the multip keyword
tddft (str) – The state to compute via TD-DFT. Should be a spin-state string like S1, T2, etc. Only singlet (S) and triplet (T) states are supported.
vertical (bool) – True if this is tracking an object that should not have its geometry optimized. If vertical is True, writing the Jaguar input file is delayed and must be triggered manually later by a call to setVerticalStructure.
write_input_ok (bool) – If True, write the input files for this fragment. If False, do not.

addBondEnergy(index1, index2, etype, energy)¶

Add a computed bond dissociation energy for the given energy type. The energy will not be added if a lower energy has already been found for this bond and energy type.

Parameters

index1 (int or schrodigner.structure._StructureAtom) – The index of the first atom in the bond (or the atom object)
index2 (int or schrodigner.structure._StructureAtom) – The index of the second atom in the bond (or the atom object)
etype (str) – The type of energy to add - typically an energy property name
energy (float) – The bond dissociation energy for that bond

getWeakestBonds(etype='r_matsci_Bond_Dissociation_Energy_(kcal/mol)')¶

Get the bond with the lowest energy for the given energy type

Parameters: etype (str) – The energy type to use. Should be consistent with the etype parameter passed in to addBondEnergy
Return type: list, float
Returns: Each item of the list is a (int, int) tuple that gives the atom indexes involved the bond with the lowest energy. More than one item in the list indicates that more than one bond shares that energy. The energy is the energy of those bonds. The list will be empty and the energy will be None if there are no BDE’s defined for this Reactant.

updateVerticalStructure(parent_structure)¶

Grab the structure for these atoms from the parent structure and write out the Jaguar input file

Parameters: parent_structure (schrodinger.structure.Structure) – The parent structure to extract the fragment structure from

writeInput(struct)¶

Write an input file using the given structure

Parameters: struct (schrodinger.structure.Structure) – The structure to write to the input file

addToQueue(jobq, backend)¶

Check if output file exists and if not create a job for this fragment and add it to the queue and add its output files to the backend

Parameters

jobq (schrodinger.job.queue.JobDJ) – The queue to add the job to
backend (schrodinger.job.jobcontrol.Backend) – The job control backend, if any

getStructureWithProps()¶

Get the structure resulting from the Jaguar run including any existing properties

Return type: schrodinger.structure.Structure or None
Returns: The output structure, or None if an error occurs

getStructureWithoutProps()¶

Get the structure resulting from the Jaguar run but remove any existing properties

Return type: schrodinger.structure.Structure or None
Returns: The output structure, or None if an error occurs

superimposeOnParent(parent, struct)¶

Superimpose this fragment on its parent structure to get the orientation the same. Modifies struct directly

Parameters

parent (schrodinger.structure.Structure) – The parent structure to superimpose on - must have the same atom ordering as was used for the parent_indexes argument in the class constructor.
struct (schrodinger.structure.Structure) – The structure for this fragment

getEnergies()¶

Get the various energies from the Jaguar job. Energies will always include the SCF energy (with solvent effect if included), plus possibly the free energy, enthalpy and internal energy if frequencies were computed.

Return type: dict
Returns: Keys of the dict are a BDE energy property, values are the energy corresponding to that energy property.

write(writer)¶

Write the structure with properties to the output file

Parameters: writer (L{schrodinger.structure.StructureWriter) – The writer to use to write the output file

log(msg, **kwargs)¶

Log a message

Parameters: msg (str) – The message to log

Additional keyword arguments are passed to the textlogger.log_msg function

class schrodinger.application.matsci.fragments.NonUniqueTracker(unique_master, parent_indexes)¶

Bases: schrodinger.application.matsci.fragments.UniqueTracker

This is a placeholder for a second (or third, etc.) time a fragment is used in the reaction. Mimics the UniqueTracker job without creating any new Jaguar jobs or writing to the output file.

__init__(unique_master, parent_indexes)¶

Create a NonUniqueTracker object

Parameters

unique_master (UniqueTracker) – The UniqueTracker object this NonUniqueTracker should mimic
parent_indexes (list) – The atom indexes with the parent atom numbering for the atoms in this fragment. Note this is only be valid for the specific reaction this tracker is for, so must it overwrites the parent_indexes of the UniqueTracker this object is mimicking

updateVerticalStructure(*args)¶: Overwrite the parent method because this class doesn’t deal with structures but we want to be able to call this method safely.

addToQueue(*args, **kwargs)¶: The whole point of this class is that it doesn’t run a Jaguar job but takes the results from a different job

write(writer)¶: Don’t write anything out - we’re vaporware of the best kind

addBondEnergy(index1, index2, etype, energy)¶

Add a computed bond dissociation energy for the given energy type. The energy will not be added if a lower energy has already been found for this bond and energy type.

Parameters

index1 (int or schrodigner.structure._StructureAtom) – The index of the first atom in the bond (or the atom object)
index2 (int or schrodigner.structure._StructureAtom) – The index of the second atom in the bond (or the atom object)
etype (str) – The type of energy to add - typically an energy property name
energy (float) – The bond dissociation energy for that bond

getEnergies()¶

Get the various energies from the Jaguar job. Energies will always include the SCF energy (with solvent effect if included), plus possibly the free energy, enthalpy and internal energy if frequencies were computed.

Return type: dict
Returns: Keys of the dict are a BDE energy property, values are the energy corresponding to that energy property.

getStructureWithProps()¶

Get the structure resulting from the Jaguar run including any existing properties

Return type: schrodinger.structure.Structure or None
Returns: The output structure, or None if an error occurs

getStructureWithoutProps()¶

Get the structure resulting from the Jaguar run but remove any existing properties

Return type: schrodinger.structure.Structure or None
Returns: The output structure, or None if an error occurs

getWeakestBonds(etype='r_matsci_Bond_Dissociation_Energy_(kcal/mol)')¶

Get the bond with the lowest energy for the given energy type

Parameters: etype (str) – The energy type to use. Should be consistent with the etype parameter passed in to addBondEnergy
Return type: list, float
Returns: Each item of the list is a (int, int) tuple that gives the atom indexes involved the bond with the lowest energy. More than one item in the list indicates that more than one bond shares that energy. The energy is the energy of those bonds. The list will be empty and the energy will be None if there are no BDE’s defined for this Reactant.

log(msg, **kwargs)¶

Log a message

Parameters: msg (str) – The message to log

Additional keyword arguments are passed to the textlogger.log_msg function

superimposeOnParent(parent, struct)¶

Superimpose this fragment on its parent structure to get the orientation the same. Modifies struct directly

Parameters

parent (schrodinger.structure.Structure) – The parent structure to superimpose on - must have the same atom ordering as was used for the parent_indexes argument in the class constructor.
struct (schrodinger.structure.Structure) – The structure for this fragment

writeInput(struct)¶

Write an input file using the given structure

Parameters: struct (schrodinger.structure.Structure) – The structure to write to the input file

class schrodinger.application.matsci.fragments.Reaction(reactant_index, reactant_targets, product_trackers, **kwargs)¶

Bases: schrodinger.application.matsci.fragments.LoggerUser

Holds the information for a single dissociation reaction

__init__(reactant_index, reactant_targets, product_trackers, **kwargs)¶

Create a Reaction object

Parameters

reactant_index (str) – the key into the reactants dictionary for the reactant in this reaction
reactant_targets (list) – The atom indexes in the reactant structure that dissociate in this reaction
product_trackers (list) – Each item of this list is a UniqueTracker or NonUniqueTracker object for one of the product fragments
logger (logging.logger) – The logger to use

updateProductGeometries(reactants)¶

Update the geometry of all product fragments to have the geometry of that fragment in the reactant

Parameters: reactants (dict) – keys are reactant_index strings, values are UniqueTracker objects for that reactant

log(msg, **kwargs)¶

Log a message

Parameters: msg (str) – The message to log

Additional keyword arguments are passed to the textlogger.log_msg function

class schrodinger.application.matsci.fragments.FragmentReactor(structs, states, options, keywords=None, vertical=False, logger=None, tracker_class=<class 'schrodinger.application.matsci.fragments.UniqueTracker'>, reactant_title_base='reactant')¶

Bases: schrodinger.application.matsci.fragments.LoggerUser

Create reactions, track all reactant and fragment objects, and run jobs on all reactants and products

Reactants are turned into products by the createProductsGroup method, which must be implemented in subclasses

ALL = 'all'¶

REACTANTS = 'reactants'¶

PRODUCTS = 'products'¶

__init__(structs, states, options, keywords=None, vertical=False, logger=None, tracker_class=<class 'schrodinger.application.matsci.fragments.UniqueTracker'>, reactant_title_base='reactant')¶

Create a fragment reactor instance

Parameters

structs (list) – Each item is a reactant Structure object
states (list) – Each item is a module constant from the STATES list
options (argparse.Namespace) – The command line options
keywords (dict) – A dictionary of Jaguar keyword/value pairs
vertical (bool) – True if the products will use the reactant geometry for those atoms, False if products will be optimized
logger (logging.logger) – The logger to use
tracker_class – The class to use for tracking unique fragments
reactant_title_base – The base title for reactant structures

getAllUniqueTrackers()¶

Get all unique reactant and product trackers

Return type: list
Returns: The list has one item per unique reactant or product, the type of object is given by self.tracker_class

getReactantTrackers()¶

Get all reactant trackers

Return type: list
Returns: The list has one item per reactant, the type of object is given by self.tracker_class

getUniqueProductTrackers()¶

Get all unique product trackers

Return type: list
Returns: The list has one item per unique product, the type of object is given by self.tracker_class

preprocessInputStruct(struct)¶

Do any initial processing of an input structure before creating reactions for it.

Base class implementation does nothing

Parameters: struct (structure.Structure) – The input structure

createAllReactions()¶: Create all reactions for all structures and states

createStateReactions(struct, product_groups, state, rind, tddft)¶

Create the reactions for this structure and state

Parameters

struct (structure.Structure) – The reactant structure
product_groups (list) – Each item is a group of products
state (str) – The current state, should be one of the STATES items
rind (int) – The index for this reactant
tddft (str) – The target excited state

Return type

list

Returns

A list of Reaction objects created

getStateModifier(state, tddft)¶

Get a tag modifier based on the current state

Parameters

state (str) – The current state, should be one of the STATES items
tddft (str) – The target excited state

Return type

str

Returns

A tag modifier based on the current state

getStateChargeAndMultiplicity(state)¶

Get the charge and multiplicity for the current state

Parameters: state (str) – The current state, should be one of the STATES items
Return type: (int, int)
Returns: The charge and multiplicity for this state

createReactantTracker(struct, state, rind, tddft)¶

Create the reactant tracker for this structure and state

Parameters

struct (structure.Structure) – The reactant structure
state (str) – The current state, should be one of the STATES items
rind (int) – The index for this reactant
tddft (str) – The target excited state

Return type

(object, str, int, int)

Returns

The object is the tracker for the reactant. Object type is given by self.tracker_class. The string is the unique key for this reactant. The two ints are charge and multiplicity

createProductGroups(struct)¶

Form all the products that can be created from struct

Base class implementation does nothing

Parameters: struct (structure.Structure) – The input structure
Return type: list
Returns: Each item should be a BreakingBond or LeavingLigand object, one for each possible fragmentation

preventUnwantedReactions(potential_reactions, products, charge)¶

Modify the potential_reactions dictionary to prevent creating reactions that we would not want

Parameters

potential_reactions (dict) – keys are reaction index. This dictionary may be modified by this function to remove the key for an unwanted reaction
products (BreakingBond or LeavingLigand) – The products that will be formed
charge (int) – The overall charge of this reaction

Return type

int

Returns

The number of reactions skipped due to avoiding H+

getExistingFragmentTracker(fragment, tagged_smiles)¶

Return any tracker for this fragment with the given state and charge

Parameters

fragment (BreakingBond or LeavingLigand) – The fragment to generate tags for
tagged_smiles (str) – The smiles string for this fragment that has been modified by adding the fragment tag

Return type

object or None, int

Returns

A tracker for this fragment with the given tagged_smiles if one exists or None if no such tracker exists, and the fragment index for this fragment. Note that fragment index is always valid even if there is no tracker, and the type of tracker object returned is given by self.tracker_class.

getFragmentTags(fragment, state, index, charge)¶

Get tags for this fragment based on the state and charge

Parameters

fragment (BreakingBond or LeavingLigand) – The fragment to generate tags for
state (str) – The current state, should be one of the STATES items
index (int) – The fragment index for this fragment
charge (int) – The charge of this fragment

Return type

str, str

Returns

A tag for this fragment and the SMILES string for this fragment with the tag added

getFragmentTracker(fragment, state, index, charge=0)¶

Return a tracker for this fragment with the given state and charge

Parameters

fragment (BreakingBond or LeavingLigand) – The fragment to generate tags for
state (str) – The current state, should be one of the STATES items
index (int) – The product index for the fragment
charge (int) – The charge of this fragment

Returns

A tracker for this fragment with the given charge state. The type of object returns is given by self.tracker_class

runJobs(logfn, what='all')¶

Create all jaguar jobs and run them

Parameters

logfn (callable) – A logging function - should take a string to log and an optional timestamp argument
what (str) – A class constant (ALL, REACTANTS, PRODUCTS) that says which jobs to run

Return type

bool or None

Returns

None if no jobs were run, True if at least one job did not fail, otherwise False

writeSingleStructures(writer)¶

Write all single structures to the output file

Parameters: writer (schrodinger.structure.StructureWriter) – The structure writer to use to write structures with

log(msg, **kwargs)¶

Log a message

Parameters: msg (str) – The message to log

Additional keyword arguments are passed to the textlogger.log_msg function