# rmgpy.data.kinetics.KineticsFamily¶

class rmgpy.data.kinetics.KineticsFamily(entries=None, top=None, label='', name='', reverse='', shortDesc='', longDesc='', forwardTemplate=None, forwardRecipe=None, reverseTemplate=None, reverseRecipe=None, forbidden=None, boundaryAtoms=None)

A class for working with an RMG kinetics family: a set of reactions with similar chemistry, and therefore similar reaction rates. The attributes are:

Attribute Type Description
reverse string The name of the reverse reaction family
forwardTemplate Reaction The forward reaction template
forwardRecipe ReactionRecipe The steps to take when applying the forward reaction to a set of reactants
reverseTemplate Reaction The reverse reaction template
reverseRecipe ReactionRecipe The steps to take when applying the reverse reaction to a set of reactants
forbidden ForbiddenStructures (Optional) Forbidden product structures in either direction
ownReverse Boolean It’s its own reverse?
‘boundaryAtoms’ list Labels which define the boundaries of end groups in backbone/end families
groups KineticsGroups The set of kinetics group additivity values
rules KineticsRules The set of kinetics rate rules from RMG-Java
depositories list A set of additional depositories used to store kinetics data from various sources

There are a few reaction families that are their own reverse (hydrogen abstraction and intramolecular hydrogen migration); for these reverseTemplate and reverseRecipe will both be None.

addAtomLabelsForReaction(reaction)

Apply atom labels on a reaction using the appropriate atom labels from this this reaction family. The reaction’s reactants and products must be lists of Molecule objects. The reaction is modified to use Species objects containing the labeled molecules after this function.

addKineticsRulesFromTrainingSet(thermoDatabase=None)

For each reaction involving real reactants and products in the training set, add a rate rule for that reaction.

ancestors(node)

Returns all the ancestors of a node, climbing up the tree to the top.

applyRecipe(reactantStructures, forward=True, unique=True)

Apply the recipe for this reaction family to the list of Molecule objects reactantStructures. The atoms of the reactant structures must already be tagged with the appropriate labels. Returns a list of structures corresponding to the products after checking that the correct number of products was produced.

areSiblings(node, nodeOther)

Return True if node and nodeOther have the same parent node. Otherwise, return False. Both node and nodeOther must be Entry types with items containing Group or LogicNode types.

calculateDegeneracy(reaction)

For a reaction given in the direction in which the kinetics are defined, compute the reaction-path degeneracy.

descendTree(structure, atoms, root=None, strict=False)

Descend the tree in search of the functional group node that best matches the local structure around atoms in structure.

If root=None then uses the first matching top node.

Returns None if there is no matching root.

Set strict to True if all labels in final matched node must match that of the structure. This is used in kinetics groups to find the correct reaction template, but not generally used in other GAVs due to species generally not being prelabeled.

descendants(node)

Returns all the descendants of a node, climbing down the tree to the bottom.

estimateKineticsUsingGroupAdditivity(template, degeneracy=1)

Determine the appropriate kinetics for a reaction with the given template using group additivity.

estimateKineticsUsingRateRules(template, degeneracy=1)

Determine the appropriate kinetics for a reaction with the given template using rate rules.

extractSourceFromComments(reaction)

Returns the rate rule associated with the kinetics of a reaction by parsing the comments. Will return the template associated with the matched rate rule. Returns a tuple containing (Boolean_Is_Kinetics_From_Training_reaction, Source_Data)

For a training reaction, the Source_Data returns [Family_Label, Training_Reaction_Entry, Kinetics_In_Reverse?]

For a reaction from rate rules, the Source_Data is a tuple containing [Family_Label, {‘template’: originalTemplate,

System Message: ERROR/3 (/Users/kehang/code/rmgmaster/RMG-Py/rmgpy/data/kinetics/family.py:docstring of rmgpy.data.kinetics.KineticsFamily.extractSourceFromComments, line 10)

Unexpected indentation.
‘degeneracy’: degeneracy, ‘exact’: boolean_exact?, ‘rules’: a list of (original rate rule entry, weight in average) ‘training’: a list of (original rate rule entry associated with training entry, original training entry, weight in average) }]

System Message: WARNING/2 (/Users/kehang/code/rmgmaster/RMG-Py/rmgpy/data/kinetics/family.py:docstring of rmgpy.data.kinetics.KineticsFamily.extractSourceFromComments, line 15)

Block quote ends without a blank line; unexpected unindent.

where TrainingReactions are ones that have created rules used in the estimate.

where Exact is a boolean of whether the rate is an exact match, Template is the reaction template used, and RateRules is a list of the rate rule entries containing the kinetics used

fillKineticsRulesByAveragingUp(verbose=False)

Fill in gaps in the kinetics rate rules by averaging child nodes recursively starting from the top level root template.

generateOldTree(entries, level)

Generate a multi-line string representation of the current tree using the old-style syntax.

generateProductTemplate(reactants0)

Generate the product structures by applying the reaction template to the top-level nodes. For reactants defined by multiple structures, only the first is used here; it is assumed to be the most generic.

generateReactions(reactants)

Generate all reactions between the provided list of one or two reactants, which should be either single Molecule objects or lists of same. Does not estimate the kinetics of these reactions at this time. Returns a list of TemplateReaction objects using Molecule objects for both reactants and products The reactions are constructed such that the forward direction is consistent with the template of this reaction family.

getBackboneRoots()

Returns: the top level backbone node in a unimolecular family.

getEndRoots()

Returns: A list of top level end nodes in a unimolecular family

getEntriesToSave()

Return a sorted list of the entries in this database that should be saved to the output file.

getKinetics(reaction, templateLabels, degeneracy=1, estimator='', returnAllKinetics=True)

Return the kinetics for the given reaction by searching the various depositories as well as generating a result using the user-specified estimator of either ‘group additivity’ or ‘rate rules’. Unlike the regular getKinetics() method, this returns a list of results, with each result comprising the kinetics, the source, and the entry. If it came from a template estimate, the source and entry will both be None. If returnAllKinetics==False, only the first (best?) matching kinetics is returned.

getKineticsForTemplate(template, degeneracy=1, method='rate rules')

Return an estimate of the kinetics for a reaction with the given template and reaction-path degeneracy. There are two possible methods to use: ‘group additivity’ (new RMG-Py behavior) and ‘rate rules’ (old RMG-Java behavior).

getKineticsFromDepository(depository, reaction, template, degeneracy)

Search the given depository in this kinetics family for kinetics for the given reaction. Returns a list of all of the matching kinetics, the corresponding entries, and True if the kinetics match the forward direction or False if they match the reverse direction.

getLabeledReactantsAndProducts(reactants, products)

Given reactants, a list of Molecule objects, and products, a list of Molecule objects, return two new lists of Molecule objects with atoms labeled: one for reactants, one for products. Returned molecules are totally new entities in memory so input molecules reactants and products won’t be affected. If RMG cannot find appropriate labels, (None, None) will be returned.

getRateRule(template)

Return the rate rule with the given template. Raises a ValueError if no corresponding entry exists.

getReactionPairs(reaction)

For a given reaction with properly-labeled Molecule objects as the reactants, return the reactant-product pairs to use when performing flux analysis.

getReactionTemplate(reaction)

For a given reaction with properly-labeled Molecule objects as the reactants, determine the most specific nodes in the tree that describe the reaction.

getReactionTemplateLabels(reaction)

Retrieve the template for the reaction and return the corresponding labels for each of the groups in the template.

getRootTemplate()

Return the root template for the reaction family. Most of the time this is the top-level nodes of the tree (as stored in the KineticsGroups object), but there are a few exceptions (e.g. R_Recombination).

getSourcesForTemplate(template)

Returns the set of rate rules and training reactions used to average this template. Note that the tree must be averaged with verbose=True for this to work.

Returns a tuple of rules, training

where rules are a list of tuples containing the [(original_entry, weight_used_in_average), ... ]

and training is a list of tuples containing the [(rate_rule_entry, training_reaction_entry, weight_used_in_average),...]

getSpecies(path)

Load the dictionary containing all of the species in a kinetics library or depository.

getTopLevelGroups(root)

Returns a list of group nodes that are the highest in the tree starting at node “root”. If “root” is a group node, then it will return a single-element list with “root”. Otherwise, for every child of root, we descend until we find no nodes with logic nodes. We then return a list of all group nodes found along the way.

getTrainingDepository()

Returns the training depository from self.depositories

hasRateRule(template)

Return True if a rate rule with the given template currently exists, or False otherwise.

isMoleculeForbidden(molecule)

Return True if the molecule is forbidden in this family, or False otherwise.

load(path, local_context=None, global_context=None, depositoryLabels=None)

Load a kinetics database from a file located at path on disk.

If depositoryLabels is a list, eg. [‘training’,’PrIMe’], then only those depositories are loaded, and they are searched in that order when generating kinetics.

If depositoryLabels is None then load ‘training’ first then everything else. If depositoryLabels is not None then load in the order specified in depositoryLabels.

loadForbidden(label, group, shortDesc='', longDesc='')

loadOld(path)

Load an old-style RMG kinetics group additivity database from the location path.

loadOldDictionary(path, pattern)

Parse an old-style RMG database dictionary located at path. An RMG dictionary is a list of key-value pairs of a one-line string key and a multi-line string value. Each record is separated by at least one empty line. Returns a dict object with the values converted to Molecule or Group objects depending on the value of pattern.

loadOldLibrary(path, numParameters, numLabels=1)

Parse an RMG database library located at path.

loadOldTemplate(path)

Load an old-style RMG reaction family template from the location path.

loadOldTree(path)

Parse an old-style RMG database tree located at path. An RMG tree is an n-ary tree representing the hierarchy of items in the dictionary.

loadRecipe(actions)

loadTemplate(reactants, products, ownReverse=False)

matchNodeToChild(parentNode, childNode)

Return True if parentNode is a parent of childNode. Otherwise, return False. Both parentNode and childNode must be Entry types with items containing Group or LogicNode types. If parentNode and childNode are identical, the function will also return False.

matchNodeToNode(node, nodeOther)

Return True if node and nodeOther are identical. Otherwise, return False. Both node and nodeOther must be Entry types with items containing Group or LogicNode types.

matchNodeToStructure(node, structure, atoms, strict=False)

Return True if the structure centered at atom matches the structure at node in the dictionary. The structure at node should have atoms with the appropriate labels because they are set on loading and never change. However, the atoms in structure may not have the correct labels, hence the atoms parameter. The atoms parameter may include extra labels, and so we only require that every labeled atom in the functional group represented by node has an equivalent labeled atom in structure.

Matching to structure is more strict than to node. All labels in structure must be found in node. However the reverse is not true, unless strict is set to True.

Attribute Description
node Either an Entry or a key in the self.entries dictionary which has a Group or LogicNode as its Entry.item
structure A Group or a Molecule
atoms Dictionary of {label: atom} in the structure. A possible dictionary is the one produced by structure.getLabeledAtoms()
strict If set to True, ensures that all the node’s atomLabels are matched by in the structure
parseOldLibrary(path, numParameters, numLabels=1)

Parse an RMG database library located at path, returning the loaded entries (rather than storing them in the database). This method does not discard duplicate entries.

removeGroup(groupToRemove)

Removes a group that is in a tree from the database. In addition to deleting from self.entries, it must also update the parent/child relationships

Returns the removed group

retrieveOriginalEntry(templateLabel)

Retrieves the original entry, be it a rule or training reaction, given the template label in the form ‘group1;group2’ or ‘group1;group2;group3’

Returns tuple in the form (RateRuleEntry, TrainingReactionEntry)

Where the TrainingReactionEntry is only present if it comes from a training reaction

retrieveTemplate(templateLabels)

Reconstruct the groups associated with the labels of the reaction template and return a list.

save(path)

Save the current database to the file at location path on disk.

saveDepository(depository, path)

Save the given kinetics family depository to the location path on disk.

saveDictionary(path)

Extract species from all entries associated with a kinetics library or depository and save them to the path given.

saveEntry(f, entry)

Write the given entry in the thermo database to the file object f.

saveGroups(path)

Save the current database to the file at location path on disk.

saveOld(path)

Save the old RMG kinetics groups to the given path on disk.

saveOldDictionary(path)

Save the current database dictionary to a text file using the old-style syntax.

saveOldLibrary(path)

Save the current database library to a text file using the old-style syntax.

saveOldTemplate(path)

Save an old-style RMG reaction family template from the location path.

saveOldTree(path)

Save the current database tree to a text file using the old-style syntax.

saveTrainingReactions(reactions, reference=None, referenceType='', shortDesc='', rank=3)

This function takes a list of reactions appends it to the training reactions file. It ignores the existence of duplicate reactions.

The rank for each new reaction’s kinetics is set to a default value of 3 unless the user specifies differently for those reactions.

For each entry, the long description is imported from the kinetics comment.