class rmgpy.data.kinetics.KineticsFamily(entries=None, top=None, label='', name='', reverse='', reversible=True, shortDesc='', longDesc='', forwardTemplate=None, forwardRecipe=None, reverseTemplate=None, reverseRecipe=None, forbidden=None, boundaryAtoms=None, treeDistances=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
reversible Boolean Is family reversible? (True by default)
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
treeDistances dict The default distance from parent along each tree, if not set default is 1 for every tree
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, output_with_resonance=True)

Apply atom labels on a reaction using the appropriate atom labels from this reaction family.

The reaction is modified in place containing species objects with the atoms labeled. If output_with_resonance is True, all resonance structures are generated with labels. If false, only the first resonance structure sucessfully able to map to the reaction is used. None is returned.

addEntry(parent, grp, name)

Adds a group entry with parent parent group structure grp and group name name


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

addReverseAttribute(rxn, react_non_reactive=True)

For rxn (with species’ objects) from families with ownReverse, this method adds a reverse attribute that contains the reverse reaction information (like degeneracy)

Returns True if successful and False if the reverse reaction is forbidden. Will raise a KineticsError if unsuccessful for other reasons.


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.


For a reaction with Molecule or Species objects given in the direction in which the kinetics are defined, compute the reaction-path degeneracy.

This method by default adjusts for double counting of identical reactants. This should only be adjusted once per reaction. To not adjust for identical reactants (since you will be reducing them later in the algorithm), add ignoreSameReactants= True to this method.

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.


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


fills in nodalDistance (the distance between an entry and its parent) if not already entered with the value from treeDistances associated with the tree the entry comes from

estimateKineticsUsingGroupAdditivity(template, degeneracy=1)

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

Returns just the kinetics, or None.

estimateKineticsUsingRateRules(template, degeneracy=1)

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

Returns a tuple (kinetics, entry) where entry is the database entry used to determine the kinetics only if it is an exact match, and is None if some averaging or use of a parent node took place.

evalExt(parent, ext, extname, obj=None, T=1000.0)

evaluates the objective function obj for the extension ext with name extname to the parent entry parent

extendNode(parent, thermoDatabase=None, obj=None, T=1000.0)

Constructs an extension to the group parent based on evaluation of the objective function obj

extendRegularization(node, inds, regs, typ)

Applies a regularization down the tree from a given parent node


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,
                '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)}]

where Exact is a boolean of whether the rate is an exact match, Template is the reaction template used, RateRules is a list of the rate rule entries containing the kinetics used, and TrainingReactions are ones that have created rules used in the estimate.


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.


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, products=None, prod_resonance=True)

Generate all reactions between the provided list of one, two, or three 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.

  • reactants (list) – List of Molecules to react.
  • products (list, optional) – List of Molecules or Species of desired product structures.
  • prod_resonance (bool, optional) – Flag to generate resonance structures for product checking. Defaults to True, resonance structures are compared.

List of all reactions containing Molecule objects with the specified reactants and products within this family. Degenerate reactions are returned as separate reactions.

generateTree(obj=None, thermoDatabase=None, T=1000.0)

Generate a tree by greedy optimization based on the objective function obj the optimization is done by iterating through every group and if the group has more than one training reaction associated with it a set of potential more specific extensions are generated and the extension that optimizing the objective function combination is chosen and the iteration starts over at the beginning

additionally the tree structure is simplified on the fly by removing groups that have no kinetics data associated if their parent has no kinetics data associated and they either have only one child or have two children one of which has no kinetics data and no children (its parent becomes the parent of its only relevant child node)


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


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


retrieves all training reactions whose kinetics are associated with the entry template


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

Then renumber the entry indexes so that we never have any duplicate indexes.

getExtensionEdge(parent, obj, T)

finds the set of all extension groups to parent such that 1) the extension group divides the set of reactions under parent 2) No generalization of the extension group divides the set of reactions under parent

We find this by generating all possible extensions of the initial group. Extensions that split reactions are added to the list. All extensions that do not split reactions and do not create bonds are ignored (although those that match every reaction are labeled so we don’t search them twice). Those that match all reactions and involve bond creation undergo this process again.

Principle: Say you have two elementary changes to a group ext1 and ext2 if applying ext1 and ext2 results in a split at least one of ext1 and ext2 must result in a split

Speed of this algorithm relies heavily on searching non bond creation dimensions once.

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 of

  1. the kinetics
  2. the source - this will be None if from a template estimate
  3. the entry - this will be None if from a template estimate
  4. is_forward a boolean denoting whether the matched entry is in the same direction as the inputted reaction. This will always be True if using rates rules or group additivity. This can be True or False if using a depository

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 possible RMG-Py behavior) and ‘rate rules’ (old RMG-Java behavior, and default RMG-Py behavior).

Returns a tuple (kinetics, entry): If it’s estimated via ‘rate rules’ and an exact match is found in the tree, then the entry is returned as the second element of the tuple. But if an average is used, or the ‘group additivity’ method, then the tuple returned is (kinetics, None).

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.


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


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


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


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


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


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, resonance=True)

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


retrives a list of all the kinetics objects associated with a given template


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.


Returns the training depository from self.depositories


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


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='')

Load information about a forbidden structure.


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.


Load an old-style RMG reaction family template from the location 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.


Load information about the reaction recipe.

loadTemplate(reactants, products, ownReverse=False)

Load information about the reaction template.

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.


clears groups and rules in the tree, generates an appropriate root group to start from and then reads training reactions Note this only works if a single top node (not a logic node) can be generated

regularize(regularization=<function simpleRegularization>)

Regularizes the tree according to the regularization function regularization


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


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


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


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.


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.


clears the rules and saves the family to its current location in database


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


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


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


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


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


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

saveTrainingReactions(reactions, reference=None, referenceType='', shortDesc='', longDesc='', 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.


Simplest regularization algorithm All nodes are made as specific as their descendant reactions Training reactions are assumed to not generalize For example if an particular atom at a node is Oxygen for all of its descendent reactions a reaction where it is Sulfur will never hit that node unless it is the top node even if the tree did not split on the identity of that atom

splitReactions(rxns, oldlabel, newgrp)

divides the reactions in rxns between the new group structure newgrp and the old structure with label oldlabel returns a list of reactions associated with the new group the list of reactions associated with the old group and a list of the indices of all of the reactions associated with the new group