schrodinger.application.matsci.reaction_workflow_utils module

Utilities for reaction workflows.

Copyright Schrodinger, LLC. All rights reserved.

class schrodinger.application.matsci.reaction_workflow_utils.TempData(temp_start, temp_step, temp_n)

Bases: tuple

temp_n

Alias for field number 2

temp_start

Alias for field number 0

temp_step

Alias for field number 1

class schrodinger.application.matsci.reaction_workflow_utils.PressData(press_start, press_step, press_n)

Bases: tuple

press_n

Alias for field number 2

press_start

Alias for field number 0

press_step

Alias for field number 1

class schrodinger.application.matsci.reaction_workflow_utils.ReactProdTS(name, other_name)

Bases: tuple

name

Alias for field number 0

other_name

Alias for field number 1

class schrodinger.application.matsci.reaction_workflow_utils.SameTypeGSTS(name, other_name)

Bases: tuple

name

Alias for field number 0

other_name

Alias for field number 1

class schrodinger.application.matsci.reaction_workflow_utils.DfCustomRateColumns(TS_Sibling, Other_Sibling, Temperature_K, Pressure_atm, Energy_Property, Energy_Barrier_kcal_per_mol, TS_Partition_F, Other_Partition_F, Rate_Constant, Rate_Constant_Type, Rate_Constant_Units)

Bases: tuple

Energy_Barrier_kcal_per_mol

Alias for field number 5

Energy_Property

Alias for field number 4

Other_Partition_F

Alias for field number 7

Other_Sibling

Alias for field number 1

Pressure_atm

Alias for field number 3

Rate_Constant

Alias for field number 8

Rate_Constant_Type

Alias for field number 9

Rate_Constant_Units

Alias for field number 10

TS_Partition_F

Alias for field number 6

TS_Sibling

Alias for field number 0

Temperature_K

Alias for field number 2

class schrodinger.application.matsci.reaction_workflow_utils.DfCustomEqColumns(Sibling, Other_Sibling, Temperature_K, Pressure_atm, Energy_Barrier_kcal_per_mol, Energy_Property, Keq)

Bases: tuple

Energy_Barrier_kcal_per_mol

Alias for field number 4

Energy_Property

Alias for field number 5

Keq

Alias for field number 6

Other_Sibling

Alias for field number 1

Pressure_atm

Alias for field number 3

Sibling

Alias for field number 0

Temperature_K

Alias for field number 2

class schrodinger.application.matsci.reaction_workflow_utils.MmodEnergyKeys(absolute, relative)

Bases: tuple

absolute

Alias for field number 0

relative

Alias for field number 1

class schrodinger.application.matsci.reaction_workflow_utils.EnergyAnalysisProperty(sibling_group, conformer_groups, representative_conformers, temperature, pressure, energy_key, property_key, avg_property_key, atom_idx, ensemble, include_x_terms, only_lowest_energy)

Bases: tuple

atom_idx

Alias for field number 8

avg_property_key

Alias for field number 7

conformer_groups

Alias for field number 1

energy_key

Alias for field number 5

ensemble

Alias for field number 9

include_x_terms

Alias for field number 10

only_lowest_energy

Alias for field number 11

pressure

Alias for field number 4

property_key

Alias for field number 6

representative_conformers

Alias for field number 2

sibling_group

Alias for field number 0

temperature

Alias for field number 3

class schrodinger.application.matsci.reaction_workflow_utils.JaguarKeyStructPropData(jaguar_key, struct_prop, default)

Bases: tuple

default

Alias for field number 2

jaguar_key

Alias for field number 0

struct_prop

Alias for field number 1

schrodinger.application.matsci.reaction_workflow_utils.zip_once(file_name, adir)

Create a zip file by the given name of the given directory. Use cache to prevent doing it multiple times on possible sequential calls.

Parameters:

  • file_name (str) – the zip file name

  • adir (str) – the directory to zip

schrodinger.application.matsci.reaction_workflow_utils.add_jaguar_keywords_parser_argument(parser, default=None)

Add a FLAG_JAGUAR_KEYWORDS argument to the parser.

Parameters:

  • parser (argparse.ArgumentParser) – the parser to add this argument to

  • default (dict or None) – the default Jaguar keywords, if not given DEFAULT_JAGUAR_KEYWORDS is used

schrodinger.application.matsci.reaction_workflow_utils.add_ts_jaguar_keywords_parser_argument(parser)

Add a FLAG_TS_JAGUAR_KEYWORDS argument to the parser.

Parameters:

parser (argparse.ArgumentParser) – the parser to add this argument to

schrodinger.application.matsci.reaction_workflow_utils.log(msg, **kwargs)

Add a message to the log file

Parameters:

msg (str) – The message to log

Additional keyword arguments are passed to the textlogger.log_msg function

schrodinger.application.matsci.reaction_workflow_utils.get_mmod_energy_key(ffld_name=None)

Returns the corresponding MacroModel energy key for the given forcefield. If no forcefield is given and the license is available, it defaults to S-OPLS. If no forcefield is given and the license is NOT available, it defaults to OPLS2005.

Parameters:

ffld_name (str) – The forcefield to get the energy key for. If None, defaults to the latest forcefield available given your licenses.

Return str energy_key:

The MacroModel suffix key for the default forcefield. Units are in kJ/mol

schrodinger.application.matsci.reaction_workflow_utils.get_mmod_rel_energy_key(ffld_name=None)

Returns the corresponding MacroModel relative energy key for the given forcefield. If no forcefield is given and the license is available, it defaults to S-OPLS. If no forcefield is given and the license is NOT available, it defaults to OPLS2005.

Parameters:

ffld_name (str) – The forcefield to get the energy key for. If None, defaults to the latest forcefield available given your licenses.

Return str energy_key:

The MacroModel suffix key for the default forcefield.

schrodinger.application.matsci.reaction_workflow_utils.get_mmod_energy_keys(ffld_name=None)

Returns the corresponding MacroModel energy key for the given forcefield. If no forcefield is given and the license is available, it defaults to S-OPLS. If no forcefield is given and the license is NOT available, it defaults to OPLS2005.

Parameters:

ffld_name (str) – The forcefield to get the energy key for. If None, defaults to the latest forcefield available given your licenses.

Return namedtuple energy_keys:

A named two-tuple where the first element (with a key of absolute) is the MacroModel suffix for the absolute energy (in kJ/mol), and the second element (with a key of relative) is the MacroModel suffix for the relative energy.

class schrodinger.application.matsci.reaction_workflow_utils.DF_RATE_TYPE

Bases: Enum

DEFAULT = 'default'
LNQ = 'lnq'
ANH_LNQ = 'anharmonic_lnq'
schrodinger.application.matsci.reaction_workflow_utils.get_reactions_data(sts)

Given conformers dictionary return list of reactions.

Parameters:

sts (list[structure.Structure]) – List of structures

Return type:

list

Returns:

contains ReactProdTS (TS, Int) and/or SameTypeGSTS (Int, Int) or (TS, TS)

schrodinger.application.matsci.reaction_workflow_utils.add_remove_props(sts, prop, add_props)

Set additional properties equal to the original property from input structures, original property will be deleted.

Parameters:

  • sts (list[structure.Structure]) – List of structures to be modified

  • prop (str) – Value of this property will be used, the property will be deleted

  • add_props (list[str]) – List of properties to be added to the structure

schrodinger.application.matsci.reaction_workflow_utils.set_extra_energy_props(sts, extra_stages_file, press_data, temp_data)

Set temp/pressure dependent extra properties in the input structures based on the original properties.

Parameters:

  • sts (list[structure.Structure]) – List of structures to be modified

  • extra_stages_file (str) – Extra stage file name

  • press_data (PressData) – Pressure data

  • temp_data (TempData) – Temperature data

Return type:

set[str]

Returns:

Set of extra energy properties

schrodinger.application.matsci.reaction_workflow_utils.get_pressures_temps(press_data, temp_data)

Get list of pressures and temepratures from input data.

Parameters:
Return type:

list[float], list[float]

Returns:

List of pressures, list of temperatures

schrodinger.application.matsci.reaction_workflow_utils.set_gas_phase_zpe_props(sts, press_data, temp_data, stage_idx)

Set temp/pressure dependent gas phase + ZPE property in the input structures based on the original property

Parameters:

  • sts (list[structure.Structure]) – List of structures to be modified

  • press_data (PressData) – Pressure data

  • temp_data (TempData) – Temperature data

  • stage_idx (int) – Stage index

schrodinger.application.matsci.reaction_workflow_utils.get_eprop_data(eprop)

Get conversion factor to kcal/mol, temperature in K, pressure in atm, from energy property

Parameters:

eprop (str) – Energy property

Return type:

float, float, float

Returns:

conversion factor to kcal/mol, temperature in K, pressure in atm

schrodinger.application.matsci.reaction_workflow_utils.validate_energy_property_names(energy_property_names)

Validate the energy property names.

Parameters:

energy_property_names (list) – the energy property names to validate

Raises:

ValueError – if there is an issue

schrodinger.application.matsci.reaction_workflow_utils.add_custom_eq_rows(name, other_name, energy, other_energy, eprop, dframe)

Add data with kEQ to the dataframe

Parameters:

  • name (str) – Sibling name

  • other_name (str) – Other sibling name

  • energy (float) – energy for sibling name, see eprop for units

  • other_energy (float) – energy for other sibling name, see eprop for units

  • eprop (str) – Energy property

  • dframe (pandas.DataFrame) – Input dataframe

Return type:

pandas.DataFrame

Returns:

Updated dataframe

schrodinger.application.matsci.reaction_workflow_utils.add_custom_rate_rows(ts_name, name, ts_energy, energy, ts_lnq, lnq, ifreq, eprop, dframe, wigner_tunnel_corr=False)

Add data with custom rates to the dataframe

Parameters:

  • ts_name (str) – the TS name

  • name (str) – the intermediate name

  • ts_energy (float) – the TS energy, see eprop for units

  • energy (float) – the intermediate energy, see eprop for units

  • ts_lnq (float) – the TS lnQ

  • lnq (float) – the intermediate lnQ

  • ifreq (float) – Lowest negative frequency to compute rate with partition function, in 1/cm

  • eprop (str) – Energy property

  • dframe (pandas.DataFrame) – Input dataframe

  • wigner_tunnel_corr (bool) – whether to include the Wigner tunneling correction when computing rate constant(s)

Return type:

pandas.DataFrame

Returns:

Updated dataframe

schrodinger.application.matsci.reaction_workflow_utils.set_temp_press_props(sts, press_data, temp_data, extra_stages_file=None)

Set temperature and pressure dependent properties.

Parameters:

  • sts (list[schrodinger.structure.Structure]) – the structures on which to set the properties

  • press_data (PressData) – pressure data

  • temp_data (TempData) – temperature data

  • extra_stages_file (str or None) – extra stage file name or None if there isn’t one

Return type:

set[str]

Returns:

the property keys set

schrodinger.application.matsci.reaction_workflow_utils.get_custom_keq_rates(out_mae, press_data, temp_data, extra_stages_file=None, compute_rates=True, wigner_tunnel_corr=False, logger=None)

Given output mae file, write custom equilibrium constants and optionally custom rates to CSV dataframes.

Parameters:

  • out_mae (str) – Output file name

  • press_data (PressData) – Pressure data

  • temp_data (TempData) – Temperature data

  • extra_stages_file (str or None) – Extra stage file name or None

  • compute_rates (bool) – Whether to compute rates or only equilibrium constants

  • wigner_tunnel_corr (bool) – whether to include the Wigner tunneling correction when computing rate constant(s)

  • logger (logging.Logger or None) – output logger or None if there isn’t one

Raises:

ReactionWorkflowException – if there is an issue

schrodinger.application.matsci.reaction_workflow_utils.get_keq(energy, temp)

Get k_equilibrium given energy and temperature.

Parameters:

  • energy (float) – energy in kcal/mol

  • temp (float) – Temperature in Kelvin

Return type:

float

Returns:

k_equilibrium

schrodinger.application.matsci.reaction_workflow_utils.get_custom_rate(energy, temp, dlnq=None, ifreq=None, wigner_tunnel_corr=False)

Get custom rate.

Parameters:

  • energy (float) – Energy in kcal/mol (!)

  • temp – Temperature in K

  • lnq (None or float) – lnQ to compute rate with partition function, unitless

  • ifreq (None or float) – Lowest negative frequency to compute rate with partition function, in 1/cm

  • wigner_tunnel_corr (bool) – whether to include the Wigner tunneling correction when computing rate constant(s)

Return type:

float

Returns:

Rate in 1/s

schrodinger.application.matsci.reaction_workflow_utils.get_present_props(en_starter, properties, stage_idx=None)

Get all properties with a certain starter and optionally stage index

Parameters:

  • en_starter (str) – Property must start with this

  • properties (list[str]) – List of properties

  • stage_idx (None or int) – Stage index

Return type:

list[str]

Returns:

List of matching properties

schrodinger.application.matsci.reaction_workflow_utils.get_present_props_from_sts(sts, prefix, stage_idx=None)

Get properties that start with prefix and end with stage index (if provided). Check if pressure/temperature is present. Ensure that all the structures have at least the same list of properties

Parameters:

  • sts (list[structure.Structure]) – List of structures

  • prefix (str) – Property must start with this

  • stage_idx (None or int) – Stage index

Return type:

set[str]

Returns:

Set of properties

schrodinger.application.matsci.reaction_workflow_utils.get_lnq_key(eprop)

Return the lnQ key.

Parameters:

e_prop (str) – Energy property

Return type:

str

Returns:

the lnQ key

schrodinger.application.matsci.reaction_workflow_utils.get_restrain_atom_idxs(st)

Return a list of indices of restrain atoms in the given structure.

Parameters:

st (schrodinger.structure.Structure) – the structure

Return type:

list

Returns:

contains indices of restrain atoms

schrodinger.application.matsci.reaction_workflow_utils.get_prevent_chirality_flip_idxs(st)

Return a list of atom indices (1-based) for which to prevent chirality flipping in MacroModel.

Parameters:

st (schrodinger.structure.Structure) – the structure

Return type:

list

Returns:

list of atom indices (1-based) for which to prevent chirality flipping in MacroModel

schrodinger.application.matsci.reaction_workflow_utils.get_idx_groups(text)

Get index groups from the given string.

Parameters:

text (str) – the string

Raise:

InvalidInput if there is a formatting issue

Return type:

list

Returns:

contains list of indices

schrodinger.application.matsci.reaction_workflow_utils.get_restrain_distance_idxs(st)

Return a list of lists of indices of restrain distances in the given structure.

Parameters:

st (schrodinger.structure.Structure) – the structure

Return type:

list

Returns:

contains lists of restrain distances

schrodinger.application.matsci.reaction_workflow_utils.get_restrain_angle_idxs(st)

Return a list of lists of indices of restrain angles in the given structure.

Parameters:

st (schrodinger.structure.Structure) – the structure

Return type:

list

Returns:

contains lists of restrain angles

schrodinger.application.matsci.reaction_workflow_utils.get_restrain_dihedral_idxs(st)

Return a list of lists of indices of restrain dihedrals in the given structure.

Parameters:

st (schrodinger.structure.Structure) – the structure

Return type:

list

Returns:

contains lists of restrain dihedrals

schrodinger.application.matsci.reaction_workflow_utils.get_jaguar_keywords_list(jaguar_keywords_dict)

Return the Jaguar keywords list from the given dict.

Parameters:

jaguar_keywords_dict (dict) – the Jaguar keywords dict

Return type:

list

Returns:

the Jaguar keywords list

schrodinger.application.matsci.reaction_workflow_utils.type_cast_jaguar_keywords(jaguar_keywords, reserved_keys={'ifreq', 'igeopt', 'itrvec', 'molchg', 'multip', 'nhesref', 'npress', 'ntemp', 'press', 'press_step', 'tmpini', 'tmpstp'}, exception_type=<class 'argparse.ArgumentTypeError'>)

Type cast the Jaguar keywords.

Parameters:

  • jaguar_keywords (str or unicode or list) – the Jaguar keywords, a whitespace delimited string of ‘<key>=<value>’ tokens or a list of such tokens

  • reserved_keys (set) – contains reserved Jaguar keys

  • exception_type (type) – the exception type to raise if invalid

Return type:

dict

Returns:

the Jaguar keywords

schrodinger.application.matsci.reaction_workflow_utils.check_ff_assignment(sts, ffld_name=None)

Check the assignment of the given force field to the given structures.

Parameters:

  • sts (list) – contains schrodinger.structure.Structure

  • ffld_name (str) – the force field name.

Raises:

ValueError – if invalid

schrodinger.application.matsci.reaction_workflow_utils.get_molecular_weight(st, idxs=None, decimal=None)

Return the molecular weight (amu) taken over the given atom indices in the given structure.

Parameters:

  • st (schrodinger.structure.Structure) – the structure

  • idxs (list) – the atom indices

  • decimal (None or int) – an optional number of decimal places to which to round the weight

Return type:

float

Returns:

the molecular weight (amu)

schrodinger.application.matsci.reaction_workflow_utils.check_centroid_rep(st)

Check the centroid representation of the given structure.

Parameters:

st (schrodinger.structure.Structure) – the structure

Raises:

ValueError – if invalid

schrodinger.application.matsci.reaction_workflow_utils.check_conformers(conformers, conformers_group_hash)

Check conformers. If the given structures are conformers then their atom numberings are all changed in place so that they are equivalent to that of the first of the given conformers.

Parameters:

  • conformers (list) – contains schrodinger.structure.Structure of conformers

  • conformers_group_hash (str) – a group hash

Raises:

ValueError – if invalid

schrodinger.application.matsci.reaction_workflow_utils.check_reaction_wf_structures(rxn_sts, ffld_name=None, mass_conserved=False, keep_atoms_only=False, out_rep=False)

Check the given reaction workflow structues.

Parameters:

  • rxn_sts (str or list) – the reaction workflow structures, a file name or list of schrodinger.structure.Structure

  • ffld_name (str) – the force field name to use when optionally checking its assignment to the given structures

  • mass_conserved (bool) – check that mass is conserved (see also keep_atoms_only kwarg)

  • keep_atoms_only (bool) – specifies that only keep atoms be considered when checking if mass is conserved (see also mass_conserved kwarg)

  • out_rep (bool) – check the output representation of haptic ligands

Raises:

ValueError – if invalid

schrodinger.application.matsci.reaction_workflow_utils.type_cast_reaction_wf_input(reaction_wf_input, exception_type=<class 'argparse.ArgumentTypeError'>, mass_conserved=False, out_rep=False)

Type cast the reaction workflow input.

Parameters:

  • reaction_wf_input (str or unicode or list) – the reaction workflow input, a file name or list of schrodinger.structure.Structure

  • exception_type (type) – the exception type to raise if invalid

  • mass_conserved (bool) – check that mass is conserved

  • out_rep (bool) – check the output representation of haptic ligands

Return type:

str or list

Returns:

the reaction workflow input, a file name or list of schrodinger.structure.Structure

schrodinger.application.matsci.reaction_workflow_utils.bin_structures_by_property(sts, key='s_matsci_Reaction_Workflow_Conformers_Group', inner_key=None)

Return a dictionary of structures binned by a property with the given key. If inner_key is provided then return a dictionary of dictionaries of structures with the inner dictionaries keyed by inner_key and outer dictionaries keyed by key.

Parameters:

  • sts (list) – the structures

  • key (str) – the key for the property by which to bin

  • inner_key (str) – additionally bin by this inner_key

Return type:

dict or dict of dict

Returns:

dictionary where keys are properties and values are lists of structures or dictionary of dictionaries where the outer dictionary is keyed by key and inner dictionary is keyed by inner_key and values of the inner dictionary are lists of structures

schrodinger.application.matsci.reaction_workflow_utils.append_unique_conformers(sts, unique_sts, rmsd_thresh=0.1, n_conformers=None)

Append any unique conformers found in the given structures to the given unique structures.

Parameters:

  • sts (list) – schrodinger.structure.Structure candidate conformers

  • unique_sts (list) – schrodinger.structure.Structure unique conformers

  • rmsd_thresh (float) – the maximum allowable RMSD (Ang.) between two structures before they can be considered different conformers

  • n_conformers (int or None) – number of sought conformers or None if there isn’t one

schrodinger.application.matsci.reaction_workflow_utils.get_conformers(sts, n_conformers, pp_rel_energy_thresh=None, rmsd_thresh=0.1, ffld_name=None, energy_key=None)

Return either (1) at most the given number of conformers or (2) all conformers with relative energies less than the given value. If (2) then an attempt is made to return at least the given number of conformers even if that means having relative energies larger than the given value.

Parameters:

  • sts (list) – schrodinger.structure.Structure conformers

  • n_conformers (int) – either the maximum number of conformers if pp_rel_energy_thresh is None or a target minimum number of conformers if pp_rel_energy_thresh is given

  • pp_rel_energy_thresh (None or float) – relative energy threshold, if None then only the n_conformers lowest energy conformers are returned, units are in kJ/mol if there is no energy key given otherwise the same units as energy_key

  • rmsd_thresh (float) – the maximum allowable RMSD (Ang.) between two structures before they can be considered different conformers

  • ffld_name (str or None) – the name of the force field to use for the search, if None, then defaults to the latest forcefield available, not used if energy key is given

  • energy_key (str or None) – the energy key to use for selecting conformers, takes precedence over ffld_name

Return type:

list

Returns:

schrodinger.structure.Structure conformers

Postprocess a conformational search. Rewrite the given out *mae file so that the conformers in it have properly updated properties.

Parameters:

  • conformer (structure.Structure) – a representative conformer that seeded the search being postprocessed

  • out_mae_path (str) – the file path to the out *mae file containing the conformers

  • ffld_name (str) – the name of the force field to use for the search. If None, then defaults to the latest forcefield available.

  • csearch_engine (str) – the engine to use for conformational search, either module constant parserutils.MACROMODEL or parserutils.CREST

schrodinger.application.matsci.reaction_workflow_utils.write_com_file(in_mae_fn, out_mae_fn, com_fn, restrain_idxs=None, seed=1234, ffld_name=None, rel_energy_thresh=50.0, rmsd_thresh=0.1, ref_com_fn=None, prevent_chirality_flip_idxs=None, csearch_method='Monte Carlo Multiple Minimum')

Write a MacroModel .com file.

Parameters:

  • in_mae_fn (str) – the input .mae file name

  • out_mae_fn (str) – the output .mae file name

  • com_fn (str) – the input .com file name

  • restrain_idxs (list) – indices to restrain

  • seed (int) – seed for random number generator

  • ffld_name (str) – the force field name

  • rel_energy_thresh (float) – relative energy threshold in kJ/mol, structures with energies (relative to that of the global minimum structure) greater than this value are not considered conformers, used in MacroModel

  • rmsd_thresh (float) – the maximum allowable RMSD (Ang.) between two structures before they can be considered different conformers

  • ref_com_fn (None or str) – if given then use the settings in this file for the search rather than the default settings

  • prevent_chirality_flip_idxs (list or None) – list of atom indices (1-based) for which to prevent chirality flipping in MacroModel, an empty list allows all chirality flipping, or None for MacroModel’s default behavior

  • csearch_method (str) – either module constant MCMM or LMCS

schrodinger.application.matsci.reaction_workflow_utils.add_macromodel_csearch(conformers, job_dj, restrain_idxs=None, seed=1234, launch_dir=None, base_name=None, ffld_name=None, rel_energy_thresh=50.0, rmsd_thresh=0.1, ref_com_fn=None, max_retries=0)

Perform a restrained MacroModel conformational search seeded with the given conformers.

Parameters:

  • conformers (list) – schrodinger.structure.Structure conformers used to seed the search

  • job_dj (queue.JobDJ) – add the job to this queue

  • restrain_idxs (list) – indices to restrain

  • seed (int) – seed for random number generator

  • launch_dir (str) – a launch subdirectory to use for the job

  • base_name (str) – a base name to use for file and job naming

  • ffld_name (str) – the force field name

  • rel_energy_thresh (float) – relative energy threshold in kJ/mol, structures with energies (relative to that of the global minimum structure) greater than this value are not considered conformers, used in MacroModel

  • rmsd_thresh (float) – the maximum allowable RMSD (Ang.) between two structures before they can be considered different conformers

  • ref_com_fn (None or str) – if given then use the settings in this file for the search rather than the default settings

  • max_retries (int) – maximum number of times to try relaunching subjobs

schrodinger.application.matsci.reaction_workflow_utils.get_all_eta_atom_idxs(st)

Return all eta atom indices.

Parameters:

st (schrodinger.structure.Structure) – the structure

Return type:

set(int)

Returns:

all eta atom indices

schrodinger.application.matsci.reaction_workflow_utils.get_crest_auto_restrain_atom_idxs(st, metal_index=None)

Automatically determine the restrain atom indices for Crest and return them.

Parameters:

  • st (schrodinger.structure.Structure) – the structure

  • metal_index (int or None) – index of the metal atom used to create restraints for complexes, if None and the structure has a single metal atom then that index will automatically be used

Return type:

set(int)

Returns:

restrain atom indices

schrodinger.application.matsci.reaction_workflow_utils.add_crest_csearch(conformer, job_dj, crest_cmd=None, restrain_idxs=None, metal_index=None, launch_dir=None, base_name=None, max_retries=0, tpp=1)

Perform a restrained Crest conformational search.

Parameters:

  • conformer (schrodinger.structure.Structure) – the conformer

  • job_dj (queue.JobDJ) – add the job to this queue

  • crest_cmd (list[str] or None) – command line flags to pass to Crest

  • restrain_idxs (list) – indices to restrain

  • metal_index (int or None) – index of the metal atom used to create restraints for complexes, if None and the structure has a single metal atom then that index will automatically be used

  • launch_dir (str) – a launch subdirectory to use for the job

  • base_name (str) – a base name to use for file and job naming

  • max_retries (int) – maximum number of times to try relaunching subjobs

  • tpp (int) – the number of threads to use for Crest subjobs, i.e. -TPP (threads-per-process)

schrodinger.application.matsci.reaction_workflow_utils.get_int_tuples_from_str_property(st, key, separator=';')

Return a list of tuples of integers from the given string structure property.

Parameters:

  • st (schrodinger.structure.Structure) – the structure

  • key (str) – the property key

  • separator (str) – the tuple separator used for the given property

Return type:

list

Returns:

contains tuples of integers

schrodinger.application.matsci.reaction_workflow_utils.representative_conformers(sibling_conformers_dict, specific_sibling_group=None)

Generator over representative conformers.

Parameters:

  • sibling_conformers_dict (dict) – dictionary of dictionaries where the outer dictionary is keyed by sibling and inner dictionary is keyed by conformer and values of the inner dictionary are lists of structures

  • specific_sibling_group (str or None) – if not None then restrict conformers to be generated only over this sibling group

Return type:

tuple

Returns:

the sibling and conformer group names and the representative conformer or None if one doesn’t exist

class schrodinger.application.matsci.reaction_workflow_utils.RepresentativeConformersMixin

Bases: object

representativeConformers(sibling_conformers_dict=None, specific_sibling_group=None)

Generator over representative conformers.

Parameters:

  • sibling_conformers_dict (dict or None) – dictionary of dictionaries where the outer dictionary is keyed by sibling and inner dictionary is keyed by conformer and values of the inner dictionary are lists of structures, if None then the class attr is used

  • specific_sibling_group (str or None) – if not None then restrict conformers to be generated only over this sibling group

Return type:

tuple

Returns:

the sibling and conformer group names and the representative conformer

schrodinger.application.matsci.reaction_workflow_utils.get_rxnwf_graph(file_path=None, sts=None, sibling_conformers_dict=None)

Return a reaction workflow graph.

Parameters:

  • file_path (str or None) – the path to the reaction workflow file or None if other input is given

  • sts (list[schrodinger.structure.Structure] or None) – the reaction workflow structures or None if other input is given

  • sibling_conformers_dict (dict or None) – dictionary of dictionaries where the outer dictionary is keyed by sibling group name and the inner dictionary is keyed by conformer group name and the values of the inner dictionary are lists of schrodinger.structure.Structure or None if other input is given

Return type:

RxnNetworkGraph

Returns:

the reaction workflow graph

exception schrodinger.application.matsci.reaction_workflow_utils.ReactionWorkflowFileException

Bases: Exception

class schrodinger.application.matsci.reaction_workflow_utils.ReactionWorkflowFile(rxn_sts, ffld_name=None, mass_conserved=False, keep_atoms_only=False, out_rep=False)

Bases: object

Manage a reaction workflow file.

__init__(rxn_sts, ffld_name=None, mass_conserved=False, keep_atoms_only=False, out_rep=False)
Parameters:

  • rxn_sts (str or list[schrodinger.structure.Structure]) – the reaction workflow structures, a reaction workflow file path or list of reaction workflow schrodinger.structure.Structure

  • ffld_name (str or None) – if given then check that this force field can be applied to all reaction workflow structures

  • mass_conserved (bool) – check that mass is conserved for each sibling group in the reaction workflow (see also keep_atoms_only)

  • keep_atoms_only (bool) – specifies that only keep atoms be considered when checking if mass is conserved (see also mass_conserved)

  • out_rep (bool) – check the output representation of haptic ligands

Raises:

ReactionWorkflowFileException – if there is an issue

getReactantsConformersDict()

Return the reactants conformers dictionary.

Return type:

dict

Returns:

keys are conformer group names, values are lists of schrodinger.structure.Structure

class schrodinger.application.matsci.reaction_workflow_utils.UniqueGeomMixin

Bases: object

Manage uniqueifying structures by geometry.

class schrodinger.application.matsci.reaction_workflow_utils.ReactionWorkflowEnergyAnalysis(rxn_sts, energy_keys, dedup_geom_eps=0.25, ffld_name=None, mass_conserved=False, keep_atoms_only=False, out_rep=False)

Bases: ReactionWorkflowFile, UniqueGeomMixin

Manage a reaction workflow energy analysis.

__init__(rxn_sts, energy_keys, dedup_geom_eps=0.25, ffld_name=None, mass_conserved=False, keep_atoms_only=False, out_rep=False)
Parameters:

  • rxn_sts (str or list[schrodinger.structure.Structure]) – the reaction workflow structures, a reaction workflow file path or list of reaction workflow schrodinger.structure.Structure

  • energy_keys (list) – structure property energy keys to consider, if it is temperature dependent then include the temperature (K) as a number followed by ‘K’ in the key and the corresponding energy must be in supported units (au, kcal/mol, eV, kJ/mol) and must be present in the key as ‘(<units>)’

  • dedup_geom_eps (float) – reduce the number of calculations by deduplicating the input structures based on geometry, using this threshold in Ang., and only calculating the representatives, a value of zero means no deduplicating

  • ffld_name (str or None) – if given then check that this force field can be applied to all reaction workflow structures

  • mass_conserved (bool) – check that mass is conserved for each sibling group in the reaction workflow (see also keep_atoms_only)

  • keep_atoms_only (bool) – specifies that only keep atoms be considered when checking if mass is conserved (see also mass_conserved)

  • out_rep (bool) – check the output representation of haptic ligands

Raises:

ReactionWorkflowException – if there is an issue

getUnitsData(prop)

Get conversion factor to kcal/mol, pressure and temperature from a property, saving the data into a dict.

Parameters:

prop (str) – Property to use

Return type:

float or None, float or None, float or None

Returns:

Conversion to kcal/mol, pressure, temperature

static getHeader(energy_key)

Return a header for the given energy key.

Parameters:

energy_key (str) – structure property energy key

Return type:

str

Returns:

the header

static getTemperature(energy_key)

Return the temperature (K) for the given energy key.

Parameters:

energy_key (str) – structure property energy key

Return type:

float, None

Returns:

the temperature (K) if there is one

static getPressure(energy_key)

Return the pressure (atm) for the given energy key.

Parameters:

energy_key (str) – structure property energy key

Return type:

float, None

Returns:

the pressure (atm) if there is one

static getUnits(energy_key)

Return the units for the given energy key.

Parameters:

energy_key (str) – structure property energy key

Return type:

str, None

Returns:

the units if there is one

static getKcalPerMolConversion(energy_key)

Return the kcal/mol conversion factor for the given energy key.

Parameters:

energy_key (str) – structure property energy key

Return type:

float, None

Returns:

the kcal/mol conversion factor if there is one

static getEnergyPropertyValues(sts, energy_key, include_x_terms=False, property_key=None, atom_idx=None)

Return energy and property value pairs for the given structures.

Parameters:

  • sts (list[schrodinger.structure.Structure]) – a collection of conformers, if including cross terms then it is a single conformer from each structure type in the sibling group, otherwise it is all conformers for a given structure type

  • energy_key (str) – the energy key

  • include_x_terms (bool) – whether to include cross terms

  • property_key (str or None) – the relevant property key, if not specified it is the same as the energy key

  • atom_idx (int or None) – if an integer then the given property key is for an atomic property and this is the atom index, if None then the given property key is a structure property

Return type:

list[tuple]

Returns:

energy and property value pairs for the given structures

getPropertyEnsemble(conformers_dict, energy_key, conversion, temp, do_boltzmann, include_x_terms=False, only_lowest_energy=False, property_key=None, atom_idx=None)

Return an ensemble of properties for the given conformers dictionary of siblings and given energy key.

Parameters:

  • conformers_dict (dict) – keys are conformer group names, values are lists of structure.Structure

  • energy_key (str) – the relevant energy key

  • conversion (float) – the energy conversion factor to kcal/mol

  • temp (float) – the temperature in K

  • do_boltzmann (bool) – if True perform a Boltzmann average, otherwise an algebraic average

  • include_x_terms (bool) – whether to include cross terms in the conformational averaging

  • only_lowest_energy (bool) – use only the lowest energy conformer rather than averaging over conformers

  • property_key (str) – the relevant property key, if not specified it is the same as the energy key

  • atom_idx (int or None) – if an integer then the given property key is for an atomic property and this is the atom index, if None then the given property key is a structure property

Raises:

ReactionWorkflowException – if there is an issue

Return type:

list

Returns:

ensemble of properties

getProperties(include_x_terms=False, only_lowest_energy=False, property_key=None, atomic=False, temps=None)

Return the properties.

Parameters:

  • include_x_terms (bool) – whether to include cross terms

  • only_lowest_energy (bool) – use only the lowest energy conformer rather than averaging over conformers

  • property_key (str) – the property key, if not specified energy energy keys are used

  • atomic (bool) – if True then the given property key is an atomic property, otherwise is a structure property

  • temps (list) – temperatures in K, only used for temperature independent energy and property keys

Raises:

ReactionWorkflowException – if there is an issue

Return type:

list[EnergyAnalysisProperty]

Returns:

the properties

getConfAvgRelEnergies(include_x_terms=True, only_lowest_energy=False)

Return the conformationally averaged energies relative to that of the reactants.

Parameters:

  • include_x_terms (bool) – whether to include cross terms in the conformational averaging

  • only_lowest_energy (bool) – use only the lowest energy conformer rather than averaging over conformers

Raises:

ReactionWorkflowException – if there is an issue

Return type:

dict

Returns:

keys are sibling group names, values are dicts with energy keys as keys and energy values as values

setGraphEnergies()

Set energies on the reaction workflow graph.

writeDataFiles()

Write data files.

schrodinger.application.matsci.reaction_workflow_utils.get_stage_idx(astr, is_filename=False)

Return the stage index from the given string, can be a filename.

Parameters:

  • astr (str) – the string

  • is_filename (bool) – Whether astr is filename or not

Return type:

int

Returns:

the stage index

schrodinger.application.matsci.reaction_workflow_utils.check_TS_vetting(out_file)

Return False if TS vetting failed in the given Jaguar out file.

Parameters:

out_file (str) – Jaguar out file

Return type:

bool

Returns:

False if TS vetting failed

schrodinger.application.matsci.reaction_workflow_utils.get_sub_host_str(obj, sub_host_attr, n_procs_attr)

Return the command line -HOST argument for using a subhost.

Parameters:

  • obj (object) – the object, possibly having the given attributes defined

  • sub_host_attr (str) – the attribute for the subhost

  • n_procs_attr (str) – the attribute for the number of processors

exception schrodinger.application.matsci.reaction_workflow_utils.ConformationalSearchException

Bases: Exception

class schrodinger.application.matsci.reaction_workflow_utils.ConformationalSearchMixin

Bases: object

Manage a MacroModel conformational search.

static genEtaRotamers(sibling_conformers_dict, only_rings=True, n_rotamers=None, metal_index=None)

Generate eta-rotamers.

Parameters:

  • sibling_conformers_dict (dict) – dictionary of dictionaries where the outer dictionary is keyed by sibling and inner dictionary is keyed by conformer and values of the inner dictionary are lists of structures

  • only_rings (bool) – if True then only allow rotation of eta-bound rings, if False then also allow rotation of ligands where the eta-bound motif is acyclic, for example ethene, etc.

  • n_rotamers (int or None) – the number of rotamers per ligand, if None then it is determined as twice the number of ring atoms

  • metal_index (int or None) – index of the metal atom around which to generate eta-rotamers, if None and the structure has a single metal atom then that index will automatically be used

Return type:

dict, dict

Returns:

dictionary of dictionaries where the outer dictionary is keyed by sibling and inner dictionary is keyed by conformer and values of the inner dictionary are lists of structures, for eta-complexes incoming conformers have been replaced with all possible rotamers, another dictionary mapping the structure titles of generated rotamers to the structure title of the structure from which they were generated

createConformers(sts)

Create the conformers.

Parameters:

sts (list) – contains schrodinger.structure.Structure, the structures for which to create conformers, each unique type of structure should have a unique conformer group structure property keyed by CONFORMERS_GROUP_KEY, structures sharing the same CONFORMERS_GROUP_KEY should be conformers of the same structure and are used to seed the conformational search, an additional optional SIBLING_GROUP_KEY can be used to distinguish related groups of conformers, atoms marked with the property RESTRAINED_ATOM_KEY will be restrained

Raises:

ConformationalSearchException – if there is an issue

exception schrodinger.application.matsci.reaction_workflow_utils.JMSWFException

Bases: Exception

class schrodinger.application.matsci.reaction_workflow_utils.JMSWFMixin

Bases: RepresentativeConformersMixin

Manage a Jaguar multistage workflow.

zipJMSWFOnce()

Create a jmswf zip file. Use cache to prevent doing it multiple times on possible sequential calls.

runJMSWF(restrain_atoms=True, restrain_internals=True)

Run the Jaguar multistage workflow.

Parameters:

  • restrain_atoms (bool) – whether to restrain the cartesian coordinates of atoms marked with the RESTRAINED_ATOM_KEY atom property

  • restrain_internals (bool) – whether to restrain the internal coordinates of structures marked with the RESTRAINED_DISTANCES_KEY, RESTRAINED_ANGLES_KEY, and/or RESTRAINED_DIHEDRALS_KEY structure properties

Raises:

JMSWFException – if there is an issue

prepareJMSWFOutput()

Prepare Jaguar multistage workflow output.

checkJMSWFOutputs(out_files)

Raises JMSWFException if any of the given Jaguar out files should be treated as a failure.

Parameters:

out_files (list) – contains Jaguar output files

Raises:

JMSWFException – if any of the given Jaguar out files should be treated as a failure

setRepresentatives()

Associated with each structure is output data from potentially multiple Jaguar multistage workflow stages. Pick representative structures to carry the data for all stages.

Raises:

JMSWFException – if there is an issue

checkRepresentatives()

Check representatives.

Raises:

JMSWFException – if there is an issue

finalizeJMSWFOutput()

Finalize the Jaguar multistage workflow output.

Return type:

str

Returns:

the Jaguar multistage workflow output file

getFreqStageIdxs()

Return the stage indices of frequency stages.

Return type:

tuple[int]

Returns:

the stage indices

class schrodinger.application.matsci.reaction_workflow_utils.DescriptorsMixin

Bases: object

Manage running descriptors.

DEFAULT_JOB_NAME = 'automatic_reaction_workflow'
getJaguarFlags(jaguar)

Return Jaguar flags.

Parameters:

jaguar (bool) – whether to run Jaguar descriptors

Return type:

list

Returns:

the Jaguar flags

getMoldesFlags(mopac)

Return moldescriptors flags.

Parameters:

mopac (bool) – whether to run Mopac descriptors

Return type:

list

Returns:

the moldescriptors flags

runDescriptors(files, jaguar=True, mopac=False)

Run descriptors.

Parameters:

  • files (list) – the files on which to run descriptors

  • jaguar (bool) – whether to run Jaguar descriptors

  • mopac (bool) – whether to run Mopac descriptors

Return type:

list

Returns:

The output file paths. The returned list will be the same length as the input files list.

schrodinger.application.matsci.reaction_workflow_utils.has_transition_state(rxnwf_file_path=None, rxnwf_sts=None)

Return True if the reaction workflow features a transition state, False otherwise.

Return type:

bool

Returns:

True if the reaction workflow features a transition state, False otherwise

schrodinger.application.matsci.reaction_workflow_utils.get_rep_stage_idx(rxnwf_file_path=None, rxnwf_sts=None, has_ts=None)

Return the representative stage index.

Parameters:

  • rxnwf_file_path (str or None) – the path to a reaction workflow file or None if other input has been provided

  • rxnwf_sts (list[schrodinger.structure.Structure] or None) – reaction workflow structures or None if other input has been provided

  • has_ts (bool or None) – True if it is known that there is at least a single transition state, False if it is known that there is no transition state, if None it will be determined from the other input

Return type:

int

Returns:

the representative stage index

exception schrodinger.application.matsci.reaction_workflow_utils.ReactionWorkflowException

Bases: Exception

class schrodinger.application.matsci.reaction_workflow_utils.ReactionWorkflow(reaction_wf_input_sts, dedup_geom_eps=0.25, csearch_engine='Macromodel', skip_eta_rotamers=False, metal_index=None, ffld_name=None, com_fn=None, seed=1234, n_conformers=5, pp_rel_energy_thresh=None, return_csearch_files=False, qm_selection=False, only_rings=True, n_rotamers=None, mopac=False, xtb=False, jaguar_keywords={'basis': 'LACVP**', 'dftname': 'B3LYP'}, ts_jaguar_keywords=None, temp_data=None, press_data=None, return_jaguar_files=False, anharm=False, return_anharm_files=False, anharm_max_freq=300, anharm_factor_data=None, rate_constants=False, return_rate_constant_files=False, custom_rate_constants=False, wigner_tunnel_corr=False, extra_stages_file=None, max_i_freq=0, out_rep=None, n_jmswf_subjobs=1, subhost=None, tpp=1, logger=None, max_retries=0)

Bases: ConformationalSearchMixin, JMSWFMixin, UniqueGeomMixin

Manage a reaction workflow.

__init__(reaction_wf_input_sts, dedup_geom_eps=0.25, csearch_engine='Macromodel', skip_eta_rotamers=False, metal_index=None, ffld_name=None, com_fn=None, seed=1234, n_conformers=5, pp_rel_energy_thresh=None, return_csearch_files=False, qm_selection=False, only_rings=True, n_rotamers=None, mopac=False, xtb=False, jaguar_keywords={'basis': 'LACVP**', 'dftname': 'B3LYP'}, ts_jaguar_keywords=None, temp_data=None, press_data=None, return_jaguar_files=False, anharm=False, return_anharm_files=False, anharm_max_freq=300, anharm_factor_data=None, rate_constants=False, return_rate_constant_files=False, custom_rate_constants=False, wigner_tunnel_corr=False, extra_stages_file=None, max_i_freq=0, out_rep=None, n_jmswf_subjobs=1, subhost=None, tpp=1, logger=None, max_retries=0)

Create an instance.

Parameters:

  • reaction_wf_input_sts (list) – reaction workflow input structures

  • dedup_geom_eps (float) – reduce the number of calculations by deduplicating the input structures based on geometry, using this threshold in Ang., and only calculating the representatives, a value of zero means no deduplicating

  • csearch_engine (str) – the engine to use for conformational search, either module constant parserutils.MACROMODEL or parserutils.CREST

  • skip_eta_rotamers (bool) – skip eta rotamers generation if true

  • metal_index (int or None) – index of the metal atom around which to generate eta-rotamers, if None and the structure has a single metal atom then that index will automatically be used

  • ffld_name (str) – the name of the force field to use (e.g., OPLS2005 or S-OPLS)

  • com_fn (None or str) – if given then use the settings in this file for the search rather than the default settings

  • seed (int) – seed for random number generator

  • n_conformers (int) – number of conformers to search for

  • pp_rel_energy_thresh (None or float) – relative energy threshold in kJ/mol, if None then only the n_conformers lowest energy conformers are returned

  • return_csearch_files (bool) – whether to return all output files from the conformational search subjobs

  • qm_selection (bool) – if True then the selection of conformers uses quantum energies as opposed to classical energies

  • only_rings (bool) – if True then only allow rotation of eta-bound rings, if False then also allow rotation of ligands where the eta-bound motif is acyclic, for example ethene, etc.

  • n_rotamers (int or None) – the number of rotamers per ligand, if None then it is determined as twice the number of ring atoms

  • mopac (bool) – run Mopac geometry optimizations and frequencies on each conformer

  • xtb (bool) – run xTB geometry optimizations on each conformer

  • jaguar_keywords (dict) – Jaguar keywords

  • ts_jaguar_keywords (dict or None) – Jaguar keywords for transistion state searches, if None then jaguar_keywords is used

  • temp_data (TempData) – the temperature data for thermochemical properties

  • press_data (PressData) – the pressure data for thermochemical properties

  • return_jaguar_files (bool) – whether to return all output files from the Jaguar subjobs

  • anharm (bool) – whether to run the anharmonic workflow

  • return_anharm_files (bool) – whether to return all output files from the anharmonic workflow

  • anharm_max_freq (float) – anharmonic potentials are created for normal modes with harmonic frequencies less than this value in wavenumbers (cm^-1)

  • anharm_factor_data (anharmonic.SeqData or None) – unitless factor data for factors that multiply a normal mode displacement, if None then the defaults are used, the number of points is in the positive direction only, excluding zero and the negative direction, for example using a value of 4 in turn means 2 * 4 + 1 = 9 points total

  • rate_constants (bool) – whether to report rate constant(s) for the rate determining step of the reaction using canonical transition state theory

  • return_rate_constant_files (bool) – whether to return all output files from the rate constant subjobs

  • custom_rate_constants (bool) – whether to compute custom rate constants

  • wigner_tunnel_corr (bool) – whether to include the Wigner tunneling correction when computing rate constant(s)

  • extra_stages_file (str) – the name of a file containing extra stages for a Jaguar Multistage Workflow subjob that will be performed on all output structures from the reaction workflow, the first of these extra stages is always skipped so as to allow analysis to potentially be the first extra stage

  • max_i_freq (float) – tolerate small imaginary frequencies less than this value in wavenumbers (cm^-1)

  • out_rep – if a string then must be either module constant parserutils.CENTROID or parserutils.ETA, if None then do nothing

  • n_jmswf_subjobs (int) – the maximum number of simultaneous Jaguar multistage workflow subjobs

  • subhost (str) – the host to use for subjobs

  • tpp (int) – the number of threads to use for Jaguar subjobs, i.e. -TPP (threads-per-process)

  • logger (logging.Logger or None) – output logger or None if there isn’t one

  • max_retries (int) – maximum number of times to try relaunching subjobs

validateAnharmonic()

Validate anharmonic.

Raises:

ReactionWorkflowException – if there is an issue

validateSubhost()

Validate subhost.

Raises:

ReactionWorkflowException – if there is an issue

validate()

Validate.

Raises:

ReactionWorkflowException – if there is an issue

runQMConformerSelection()

Run the QM conformer selection.

Raises:

ReactionWorkflowException – if there is an issue

runAnharmonic()

Run the anharmonic workflow.

processAnharmonic()

Process the anharmonic workflow.

Raises:

ReactionWorkflowException – if there is an issue

runCTST()

Run canonical transition state theory calculations to determine rate constant(s) for the rate determining step of the reaction.

prepareCTSTOutput()

Prepare CTST output.

Raises:

ReactionWorkflowException – if there is an issue

exportEnergyDiagrams()

Export the energy diagrams if the parents file exists.

Return type:

(str, str) or None

Returns:

the energy level diagrams in pdf format, the total free energy at STP energy level diagram in png format or None otherwise

static writeTOFFile(rxnwfea, logger=None)

Write a file containing the turn over frequencies.

Parameters:

  • rxnwfea (ReactionWorkflowEnergyAnalysis) – the reaction workflow energy analysis instance that manages all computed energies of all sibling and conformer groups

  • logger (logging.Logger or None) – the logger if there is one

run()

Run the reaction workflow.

Raises:

ReactionWorkflowException – if there is an issue

schrodinger.application.matsci.reaction_workflow_utils.get_sites(sites)

Return the reference and novel sites.

Parameters:

sites (list) – contains for each site a list of data [from_idx, to_idx, hash_idx] with an optional fourth item structure_idx and an optional fifth item reaction_workflow_utils.REFERENCE or reaction_workflow_utils.NOVEL module constants

Raises:

ReactionWorkflowException – if there is an issue

Return type:

list, list

Returns:

the reference and novel sites, each containing rxnwfeu.Site

schrodinger.application.matsci.reaction_workflow_utils.validate_auto_reaction_workflow_files(reaction_wf_input, novel_rxnwf_file=None, mass_conserved=False, sites=None, out_rep=False)

Validate auto reaction workflow input files.

Parameters:

  • reaction_wf_input (str) – reference reaction workflow file name

  • novel_rxnwf_file (str or None) – if there is one the novel reaction workflow file name

  • mass_conserved (bool) – check that mass is conserved

  • sites (list) – contains for each site a list of data [from_idx, to_idx, hash_idx] with an optional fourth item structure_idx and an optional fifth item reaction_workflow_utils.REFERENCE or reaction_workflow_utils.NOVEL module constants

  • out_rep (bool) – check the output representation of haptic ligands

Raises:

ReactionWorkflowException – if there is an issue

schrodinger.application.matsci.reaction_workflow_utils.validate_custom_rate_with_extra_stages(options)

Validate that if custom rates are requested and extra stages file is present, custom property has one of the known energy units

Parameters:

options (SimpleNamespace) – Options

Raises:

ReactionWorkflowException – if custom property has no known unit

schrodinger.application.matsci.reaction_workflow_utils.validate_crest_options(csearch_engine, skip_eta_rotamers, reaction_wf_input_sts, validate_platform=True)

Validate Crest options.

Parameters:

  • csearch_engine (str) – the engine to use for conformational search, either module constant parserutils.MACROMODEL or parserutils.CREST

  • skip_eta_rotamers (bool) – skip eta rotamers generation if true

  • reaction_wf_input_sts (list) – reaction workflow input structures

  • validate_platform (bool) – if True then validate the platform

Raises:

ReactionWorkflowException – if there is an issue

schrodinger.application.matsci.reaction_workflow_utils.has_keep_and_superpose_atoms(input_st)

Return True if the given structure has at least a single keep atom and a single superpose atom.

Parameters:

input_st (structure.Structure) – the structure

Return type:

bool

Returns:

True if the structure has at least a single keep atom and a single superpose atom

schrodinger.application.matsci.reaction_workflow_utils.validate_auto_reaction_workflow_options(reaction_wf_input, novel_rxnwf_file=None, n_conformers=5, jaguar_keywords=None, ts_jaguar_keywords=None, ffld_name='S-OPLS')

Validate auto reaction workflow options.

Parameters:

  • reaction_wf_input (str) – reference reaction workflow file name

  • novel_rxnwf_file (str or None) – if there is one the novel reaction workflow file name

  • n_conformers (int) – number of conformers to search for

  • jaguar_keywords (str or None) – whitespace separated Jaguar <key>=<value> tokens, if None then use the defaults

  • ts_jaguar_keywords (str or None) – whitespace separated Jaguar <key>=<value> tokens for transition state searches

  • ffld_name (str) – the name of the force field to use (e.g., OPLS2005 or S-OPLS)

Raises:

ReactionWorkflowException – if there is an issue

schrodinger.application.matsci.reaction_workflow_utils.validate_all_auto_reaction_workflow_options(reaction_wf_input, novel_rxnwf_file=None, mass_conserved=False, sites=None, n_conformers=5, jaguar_keywords=None, ts_jaguar_keywords=None, ffld_name='S-OPLS')

Validate all auto reaction workflow options or raise ReactionWorkflowException error.

Parameters:

  • reaction_wf_input (str) – reference reaction workflow file name

  • novel_rxnwf_file (str) – the reaction workflow file containing the single novel structure

  • mass_conserved (bool) – True if mass is conserved else false

  • sites (list) – contains for each site a list of data [from_idx, to_idx, hash_idx] with an optional fourth item structure_idx and an optional fifth item reaction_workflow_utils.REFERENCE or reaction_workflow_utils.NOVEL module constants

  • n_conformers (int) – number of conformers to search for

  • jaguar_keywords (str) – whitespace separated Jaguar <key>=<value> tokens, if None then use the defaults

  • ts_jaguar_keywords (str or None) – whitespace separated Jaguar <key>=<value> tokens for transition state searches, if None then jaguar_keywords is used

  • ffld_name (str) – the name of the force field to use (e.g., OPLS2005 or S-OPLS)

Raises:

rxnwfu.ReactionWorkflowException – if there is an issue

schrodinger.application.matsci.reaction_workflow_utils.validate_options(options)

Validate options.

Parameters:

options (SimpleNamespace) – the options

Raises:

rxnwfu.ReactionWorkflowException – if there is an issue

schrodinger.application.matsci.reaction_workflow_utils.get_sibling_ownership_information(file_path=None, sts=None)

Get the parents and children information of sibling groups from a structure file or a list of structures

Parameters:

  • file_path (str) – The path to the structure file to read

  • sts (iterable) – The structures to get information from, if file_path is not provided

Raises:

ReactionWorkflowException – if there is an issue with the inputs

Return type:

dict, dict

Returns:

first dict maps each sibling group to its parents, second dict maps each sibling group to its children

schrodinger.application.matsci.reaction_workflow_utils.bin_by_geometry(sts, eps=0.25)

Return a dictionary of structures binned by common geometry.

Parameters:

  • sts (list[schrodinger.structure.Structure]) – the structures

  • eps (float) – the RMSD precision in Angstrom that controls the size of the clusters, see sklearn.cluster.DBSCAN documentation for more details

Return type:

dict

Returns:

keys are representative structures from each geometry bin, values are lists of other structures in the same geometry bin

schrodinger.application.matsci.reaction_workflow_utils.get_orig_title(title, unique_geom_dict)

Return the original title of the given title.

Parameters:

  • title (str) – the title

  • unique_geom_dict (dict) – keys are original titles, values are structures in the same geometry bin, with the representative structure at index 0

Return type:

str, str

Returns:

the original title and the extension

schrodinger.application.matsci.reaction_workflow_utils.get_unique_geom_title(title, unique_geom_dict)

Return the title of the unique geometry representative for the given title.

Parameters:

  • title (str) – the title

  • unique_geom_dict (dict) – keys are original titles, values are structures in the same geometry bin, with the representative structure at index 0

Return type:

str

Returns:

the title of the representative

schrodinger.application.matsci.reaction_workflow_utils.get_titles_of_duplicates(title, unique_geom_dict)

Return the structure titles of structures represented by a unique structure with the given structure title.

Parameters:

  • title (str) – the structure title of the unique representative structure

  • unique_geom_dict (dict) – keys are original titles, values are structures in the same geometry bin, with the representative structure at index 0

Return type:

list[str]

Returns:

the titles of the duplicate structures

schrodinger.application.matsci.reaction_workflow_utils.get_file_names_of_duplicates(file_name, unique_geom_dict)

Return duplicate file names from the given representative file name. Files are named by structure title.

Parameters:

  • file_name (str) – the representative file name

  • unique_geom_dict (dict) – keys are original titles, values are structures in the same geometry bin, with the representative structure at index 0

Return type:

list[str]

Returns:

the duplicate file names

schrodinger.application.matsci.reaction_workflow_utils.get_energy_db_term(rxnwf_file_path=None, rxnwf_sts=None, tstart=298.15, tstep=10.0, ntemp=1, pstart=1.0, pstep=1.0, npress=1, anharm=False, extra_stages_file=False, **kwargs)

Get a dict containing all the energy term generated by reaction workflow

Parameters:

  • rxnwf_file_path (str or None) – the path to a reaction workflow file

  • rxnwf_sts (list[schrodinger.structure.Structure] or None) – reaction workflow structures

  • tstart (float) – the starting temperature (K)

  • tstep (float) – the step size of the temperature (K)

  • ntemp (int) – the number of temperature points

  • pstart (float) – the starting pressure (atm)

  • pstep (float) – the step size of the pressure (atm)

  • npress (int) – the number of pressure points

  • anharm (bool) – True if anharmonic calculation is performed else False

  • extra_stages_file (string) – name of stage file

Rtype energy_term_dict:

dict

Returns:

dictionary of energy keys.

class schrodinger.application.matsci.reaction_workflow_utils.SiblingNode(name, axes)

Bases: object

Contains parent-child information for a sibling group as well as features for creating an energy diagram

LINE_LENGTH = 1
X_GAP = 0.5
__init__(name, axes)
Parameters:

  • name (str) – The name of the sibling group

  • axes (matplotlib.axes.Axes) – The plot’s axes object

addToPlot(y_val, energy, text_offset)

Add this sibling group to the plot

Parameters:

  • y_val (float) – The y-value of the sibling on the plot

  • energy (float) – The energy to show on the label

  • text_offset (float) – The offset for showing the label above horizontal lines

class schrodinger.application.matsci.reaction_workflow_utils.EnergyDiagramPlotter(json_path, csv_path, logger=None)

Bases: object

Class for exporting energy level diagrams

TOTAL_FREE_ENERGY = 'Total_Free_Energy'
TEXT_OFFSET_DIVISOR = 50
VERTICAL_SPACING_DIVISOR = 23
PDF_FILE_ENDING = '_e_diagrams.pdf'
PNG_FILE_ENDING = '_std_e_diagram.png'
__init__(json_path, csv_path, logger=None)
Parameters:

  • json_path (str) – Path to _conf_avg_wo_x_rel_parents.json file

  • csv_path (str) – Path to _conf_avg_wo_x_rel_reactants.csv file

static exportEnergyDiagrams(logger=None)

Export the energy diagrams if the parents file exists.

Parameters:

logger (logging.Logger or None) – output logger or None if there isn’t one

Return type:

(str, str) or None

Returns:

the energy level diagrams in pdf format, the total free energy at STP energy level diagram in png format or None otherwise

run()

Export the energy level diagrams.

Return type:

str, str

Returns:

the energy level diagrams in pdf format, the total free energy at STP energy level diagram in png format

findTotalEnergyProp()

Find the Total Free Energy property with temperature and pressure closest to 298.15 K and 1.0 atm

getSibling(name)

Get an existing sibling or create a new one and return it

Parameters:

name (str) – The name of the sibling

Return type:

SiblingNode

Returns:

A SiblingNode object

parseSiblings()

Read the siblings and parent child info from json file and find the generation of each sibling

setColors()

Set colors for paths that have one parent and one child for all nodes, excluding the reactant

findGenerations()

Determine the generations of the siblings

Each child’s generation is the largest generation of its parents, plus 1 which means that if we have the following ownerships: 1 -> 2 -> 3 -> 4 1 -> 5 -> 4 “4” will be a 4th generation and “5” will be a 2nd generation, so the plot will look like this: 1 – 2 – 3 – 4 1 – 5 ——- 4 as opposed to 1 ——- 5 – 4

findSameGenerationIndices()

Find groups of csv indices that belong to the same generation

plotDiagram(prop)

Plot the energy diagram for the passed property

adjustLabels()

Adjust the size of labels. If a label’s width is large enough to overlap with a neighbour’s label, reduce the font and redraw

getAdjustedYValues(prop)

Adjust the y values so that there is enough gap between all consecutive values in the same generation so there is no overlap.

Parameters:

prop (str) – The property to adjust values for

Return type:

numpy.array

Returns:

The adjusted Y values as a numpy array

schrodinger.application.matsci.reaction_workflow_utils.flatten_sibling_conformers(sibling_conformers_dict)

Return a list of structures from the given sibling conformers dictionary.

Parameters:

sibling_conformers_dict (dict) – dictionary of dictionaries where the outer dictionary is keyed by sibling and inner dictionary is keyed by conformer and values of the inner dictionary are lists of structures

Return type:

list[schrodinger.structure.Structure]

Returns:

the structures

schrodinger.application.matsci.reaction_workflow_utils.get_out_rep(sts)

Return the output representation of haptic ligands.

Parameters:

sts (list[schrodinger.structure.Structure]) – the structures to search

Raises:

ValueError – if there are conflicting output representations, if the output representation is unknown

Return type:

str or None

Returns:

the output representation, either module constant parserutils.CENTROID or parserutils.ETA, if None then none was found

schrodinger.application.matsci.reaction_workflow_utils.get_check_min_jaguar_keywords(st, set_freq=True, jaguar_keywords=None)

Return the check minimum Jaguar keywords.

Parameters:

  • st (schrodinger.structure.Structure) – the structure

  • set_freq (bool) – if True then this is a frequency job

  • jaguar_keywords (dict) – Jaguar keywords

Return type:

dict

Returns:

the check minimum Jaguar keywords

exception schrodinger.application.matsci.reaction_workflow_utils.QMConformerSelectionException

Bases: Exception

class schrodinger.application.matsci.reaction_workflow_utils.QMConformerSelection(sibling_conformers_dict, qm_selection=True, n_conformers=5, pp_rel_energy_thresh=None, rmsd_thresh=0.1, base_name='qm_conformer_selection', host=None, tpp=1, return_files=False, logger=None, max_retries=0)

Bases: object

Manage selecting conformers from QM geometry optimizations.

__init__(sibling_conformers_dict, qm_selection=True, n_conformers=5, pp_rel_energy_thresh=None, rmsd_thresh=0.1, base_name='qm_conformer_selection', host=None, tpp=1, return_files=False, logger=None, max_retries=0)
Parameters:

  • sibling_conformers_dict (dict) – dictionary of dictionaries where the outer dictionary is keyed by sibling and inner dictionary is keyed by conformer and values of the inner dictionary are lists of structures

  • qm_selection (bool) – if True then select conformers from all geometry optimized structures using the selection criteria specified using n_conformers, pp_rel_energy_thresh, and rmsd_thresh, otherwise select all geometry optimized structures as conformers

  • n_conformers (int) – either the maximum number of conformers if pp_rel_energy_thresh is None or a target minimum number of conformers if pp_rel_energy_thresh is given

  • pp_rel_energy_thresh (None or float) – relative energy threshold, if None then only the n_conformers lowest energy conformers are returned, units are in kJ/mol

  • rmsd_thresh (float) – the maximum allowable RMSD (Ang.) between two structures before they can be considered different conformers

  • base_name (str) – the base name used to name the launch directory as well as input and output files

  • host (str or None) – the host string to use to create the queue, for example ‘<host>:<n>’, where <host> is the host and <n> is the number of simultaneous subjobs, if None then it will be determined automatically by job control from the toplevel -HOST

  • tpp (int) – the number of threads to use for subjobs, i.e. -TPP (threads-per-process)

  • return_files (bool) – whether to zip and return all output files

  • logger (logging.Logger or None) – output logger or None if there isn’t one

  • max_retries (int) – maximum number of times to try relaunching subjobs

writeInput(launch_dir, in_mae_file)

Write the input.

Parameters:

  • launch_dir (str) – the launch directory

  • in_mae_file (str) – the input file name

checkJob(launch_dir, out_mae_file)

Check the job.

Parameters:

  • launch_dir (str) – the launch directory

  • out_mae_file (str) – the output file name

Raises:

QMConformerSelectionException – if there is an issue

selectConformers(sts)

Select representative conformers from the given geometry optimized structures.

Parameters:

sts (list[schrodinger.structure.Structure]) – all conformers

Return type:

list

Returns:

representative conformers

run()

Run the QM conformer selection.

class schrodinger.application.matsci.reaction_workflow_utils.MopacConformerSelection(*args, method='PM6', **kwargs)

Bases: QMConformerSelection

ENERGY_KEY = 'r_mopac_MOPAC_Total_Energy_EV'
CONVERSION = 96.48533212331012
NAME = 'Mopac'
__init__(*args, method='PM6', **kwargs)

See parent class.

Parameters:

method (str) – the Mopac method

runJob(launch_dir, in_mae_file)

Run the Mopac geometry optimization.

Parameters:

  • launch_dir (str) – the Mopac launch directory

  • in_mae_file (str) – the Mopac input file name

Return type:

str

Returns:

the Mopac output file name

class schrodinger.application.matsci.reaction_workflow_utils.JMSWFConformerSelection(*args, jaguar_keywords={'basis': 'LACVP**', 'dftname': 'B3LYP'}, max_i_freq=0, write_output_files=True, **kwargs)

Bases: QMConformerSelection, JMSWFMixin

ENERGY_KEY = 'r_j_Gas_Phase_Energy_stage_1'
CONVERSION = 2625.499639479825
NAME = 'JMSWF'
__init__(*args, jaguar_keywords={'basis': 'LACVP**', 'dftname': 'B3LYP'}, max_i_freq=0, write_output_files=True, **kwargs)

See parent class.

Parameters:

  • jaguar_keywords (dict) – Jaguar keywords

  • max_i_freq (float) – tolerate small imaginary frequencies less than this value in wavenumbers (cm^-1)

  • write_output_files (bool) – whether to write output files

runJob(launch_dir, in_mae_file)

Run the JMSWF geometry optimization.

Parameters:

  • launch_dir (str) – the JMSWF launch directory

  • in_mae_file (str) – the JMSWF input file name

Raises:

QMConformerSelectionException – if there is an issue

Return type:

str

Returns:

the JMSWF output file name

class schrodinger.application.matsci.reaction_workflow_utils.XtbConformerSelection(*args, **kwargs)

Bases: JMSWFConformerSelection

NAME = 'xTB'
__init__(*args, **kwargs)

See parent class.

exception schrodinger.application.matsci.reaction_workflow_utils.RxnNetworkGraphException

Bases: Exception

class schrodinger.application.matsci.reaction_workflow_utils.RxnNetworkGraph(graph, transition_state_names=None)

Bases: object

Manage a reaction network graph.

__init__(graph, transition_state_names=None)
Parameters:

  • graph (networkx.DiGraph) – a graph of the reaction network which is a collection of named nodes and their connectivity

  • transition_state_names (list[str] or None) – the names of the graph nodes that are transition states or None if there aren’t any

validate()

Validate the graph.

Raises:

RxnNetworkGraphException – if there is an issue

validateRateConstants()

Check if rate constants can be calculated.

Raises:

RxnNetworkGraphException – if there is an issue

validateTOFs()

Check if turn over frequencies can be calculated.

Raises:

RxnNetworkGraphException – if there is an issue

getReactantNames()

Return the names of the graph nodes that are reactants.

Return type:

list[str]

Returns:

the names of the graph nodes that are reactants

getProductNames()

Return the names of the graph nodes that are products.

Return type:

list[str]

Returns:

the names of the graph nodes that are products

getConnectedTransitionStateTriples()

Return a list of connected transition state triples.

Return type:

list[tuple]

Returns:

connected transition state triples, where each tuple is a triple of node names, the second name is the name of a transition state while the first and third names are those of preceeding and succeeding nodes, if either of those doesn’t exist then the value will be None

getBranchDivergentNames()

Return the names of the graph nodes that start a branch.

Return type:

list[str]

Returns:

the names of the graph nodes that start a branch

getBranchConvergentNames()

Return the names of the graph nodes that end a branch.

Return type:

list[str]

Returns:

the names of the graph nodes that end a branch

getIntermediateNames()

Return the names of the graph nodes that are intermediates.

Return type:

list[str]

Returns:

the names of the graph nodes that are intermediates

getTransitionStateNames()

Return the names of the graph nodes that are transition states.

Return type:

list[str]

Returns:

the names of the graph nodes that are transition states

isForward(initial_name, final_name)

Return True if the given node names are ordered in the forward direction of the reaction network and False otherwise as is the case if they are ordered in the reverse direction or if it is unknown due to branching.

Parameters:

  • initial_name (str) – the name of the initial node

  • final_name (str) – the name of the final node

Return type:

bool

Returns:

True if the given node names are ordered in the forward direction of the reaction network and False otherwise as is the case if they are ordered in the reverse direction or if it is unknown due to branching

getOrderedNodeNames()

Return an ordered list of node names.

Return type:

list[str]

Returns:

an ordered list of node names

exception schrodinger.application.matsci.reaction_workflow_utils.EnergeticSpanException

Bases: Exception

class schrodinger.application.matsci.reaction_workflow_utils.EnergeticSpan(graph)

Bases: object

Manage application of the energetic span model.

__init__(graph)
Parameters:

graph (RxnNetworkGraph) – the reaction network graph

validate()

Validate.

Raises:

EnergeticSpanException – if there is an issue

getDeltaE(initial_name, final_name, energies)

Return the difference in energy between two nodes.

Parameters:

  • initial_name (str) – the name of the initial node

  • final_name (str) – the name of the final node

  • energies (dict[str]=float) – keys are node names and values are energies in kcal/mol

Return type:

float

Returns:

the energy difference in kcal/mol

getDeltaERxn(energies)

Return the reaction energy.

Parameters:

energies (dict[str]=float) – keys are node names and values are energies in kcal/mol

Raises:

EnergeticSpanException – if there is an issue

Return type:

float

Returns:

the reaction energy in kcal/mol

getResistance(temperature, energies)

Return the resistance.

Parameters:

  • temperature (float) – the temperature in K

  • energies (dict[str]=float) – keys are node names and values are energies in kcal/mol

Return type:

float

Returns:

the resistance, which is unitless

getVoltage(temperature, energies)

Return the voltage.

Parameters:

  • temperature (float) – the temperature in K

  • energies (dict[str]=float) – keys are node names and values are energies in kcal/mol

Return type:

float

Returns:

the voltage in 1/s

getSOSTOF(energies, temperature)

Return the turn over frequency using the full sum-over-states.

Parameters:

  • energies (dict[str]=float) – keys are node names and values are energies in kcal/mol

  • temperature (float) – the temperature in K

Return type:

float

Returns:

the turn over frequency in 1/s

getEnergeticSpans(energies)

Return the energetic spans.

Parameters:

energies (dict[str]=float) – keys are node names and values are energies in kcal/mol

Return type:

list[tuple]

Returns:

the energetic spans as a list of triples, the first item is the intermediate name, the second item is the transition state name, and the third item is the energetic span in kcal/mol

getDeterminingStates(energies)

Return the determining states and their energetic span.

Parameters:

energies (dict[str]=float) – keys are node names and values are energies in kcal/mol

Return type:

str, str, float

Returns:

the determining intermediate, determining transition state, and their energetic span in kcal/mol

getDeterminingStatesTOF(energetic_span, temperature)

Return the turn over frequency using the determining states.

Parameters:

  • energetic_span (float) – the energetic span in kcal/mol

  • temperature (float) – the temperature in K

Return type:

float

Returns:

the turn over frequency in 1/s

schrodinger.application.matsci.reaction_workflow_utils.copy_to_autorxnwf_file(ofname)

Create an auto-rxnwf compatible copy of the file with the given file name.

Parameters:

ofname (str) – the original file name

Return type:

str

Returns:

the auto-rxnwf compatible file name

class schrodinger.application.matsci.reaction_workflow_utils.EnumerateSwap(reference_rxnwf_file, novel_rxnwf_file=None, rgroup_files=None, reference_sites=None, novel_sites=None, force_hetero_substitution=False, require_identical_bonds=False, logger=None)

Bases: EnumerateSwapMixin

Manage enumeration and swapping.

__init__(reference_rxnwf_file, novel_rxnwf_file=None, rgroup_files=None, reference_sites=None, novel_sites=None, force_hetero_substitution=False, require_identical_bonds=False, logger=None)

Create an instance.

Parameters:

  • reference_rxnwf_file (str) – the reaction workflow file containing the reference structures

  • novel_rxnwf)file – the reaction workflow file containing the single novel structure

  • rgroup_files (dict) – keys are hash_idx (see sites), values are file names

  • reference_sites (list) – contains Site for the reference structures

  • novel_sites (list) – contains Site for the novel structure

  • force_hetero_substitution (bool) – if True then for hetero-eumeration do not additionally include homo-enumeration results

  • require_identical_bonds (bool) – whether to require that bonds to be created must exist in both novel and reference structures and be of the same bond order

  • logger (logging.Logger or None) – output logger or None if there isn’t one

run()

Run it.

Raises:

InvalidInput – if there is an issue

Return type:

set

Returns:

all reaction workflow input files

schrodinger.application.matsci.reaction_workflow_utils.enumerate_swap(reference_rxnwf_file, novel_rxnwf_file=None, rgroup_files=None, reference_sites=None, novel_sites=None, force_hetero_substitution=False)

Return all reaction workflow files created by R-group enumerating the given reference and novel structures and swapping reference fragments for novel fragments.

Parameters:

  • reference_rxnwf_file (str) – the reaction workflow file containing the reference structures

  • novel_rxnwf)file – the reaction workflow file containing the single novel structure

  • rgroup_files (dict) – keys are hash_idx (see sites), values are file names

  • reference_sites (list) – contains Site for the reference structures

  • novel_sites (list) – contains Site for the novel structure

  • force_hetero_substitution (bool) – if True then for hetero-eumeration do not additionally include homo-enumeration results

Return type:

set

Returns:

all reaction workflow input files