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.

Copyright Schrodinger, LLC. All rights reserved.

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
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

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

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

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