arc.reaction¶

A module for representing a reaction.

class arc.reaction.ARCReaction(label: str = '', reactants: Optional[List[str]] = None, products: Optional[List[str]] = None, r_species: Optional[List[ARCSpecies]] = None, p_species: Optional[List[ARCSpecies]] = None, ts_label: Optional[str] = None, rmg_reaction: Optional[Reaction] = None, ts_xyz_guess: Optional[list] = None, xyz: Optional[list] = None, multiplicity: Optional[int] = None, charge: Optional[int] = None, reaction_dict: Optional[dict] = None, species_list: Optional[List[ARCSpecies]] = None, preserve_param_in_scan: Optional[list] = None)[source]¶

A class for representing a chemical reaction.

Either give reactants and products (just list of labels corresponding to ARCSpecies), a reaction label, or an RMG Reaction object. If the reactants and products in the RMG Reaction aren’t ARCSpecies, they will be created.

The ARCReaction object stores the labels corresponding to the reactants, products and TS ARCSpecies objects as self.reactants, self.products, and self.ts_label, respectively.

Parameters:

label (str, optional) – The reaction’s label in the format r1 + r2 <=> p1 + p2 (or unimolecular on either side, as appropriate).
reactants (List[str], optional) – A list of reactant labels corresponding to an ARCSpecies.
products (List[str], optional) – A list of product labels corresponding to an ARCSpecies.
r_species (List[ARCSpecies], optional) – A list of reactants ARCSpecies objects.
p_species (List[ARCSpecies], optional) – A list of products ARCSpecies objects.
ts_label (str, optional) – The ARCSpecies label of the respective TS.
rmg_reaction (Reaction, optional) – An RMG Reaction class.
ts_xyz_guess (list, optional) – A list of TS XYZ user guesses, each in a string format.
xyz (list, optional) – Identical to ts_xyz_guess, used as a shortcut.
multiplicity (int, optional) – The reaction surface multiplicity. A trivial guess will be made unless provided.
charge (int, optional) – The reaction surface charge.
reaction_dict (dict, optional) – A dictionary to create this object from (used when restarting ARC).
species_list (list, optional) – A list of ARCSpecies entries for matching reactants and products to existing species.
preserve_param_in_scan (list, optional) – Entries are length two iterables of atom indices (1-indexed) between which distances and dihedrals of these pivots must be preserved. Used for identification of rotors which break a TS.

label¶

The reaction’s label in the format r1 + r2 <=> p1 + p2 (or unimolecular on either side, as appropriate).

Type:: str

family¶

The RMG kinetic family, if applicable.

Type:: KineticsFamily

family_own_reverse¶

Whether the RMG family is its own reverse.

Type:: bool

reactants¶

A list of reactants labels corresponding to an ARCSpecies.

Type:: List[str]

products¶

A list of products labels corresponding to an ARCSpecies.

Type:: List[str]

r_species¶

A list of reactants ARCSpecies objects.

Type:: List[ARCSpecies]

p_species¶

A list of products ARCSpecies objects.

Type:: List[ARCSpecies]

ts_species¶

The ARCSpecies corresponding to the reaction’s TS.

Type:: ARCSpecies

dh_rxn298¶

The heat of reaction at 298K.

Type:: float

kinetics¶

The high pressure limit rate coefficient calculated by ARC.

Type:: Arrhenius

rmg_kinetics¶

The kinetics generated by RMG, for reality-check.

Type:: Arrhenius

rmg_reaction¶

An RMG Reaction class.

Type:: Reaction

rmg_reactions¶

A list of RMG Reaction objects with RMG rates for comparisons.

Type:: list

long_kinetic_description¶

A description for the species entry in the thermo library outputted.

Type:: str

ts_xyz_guess¶

A list of TS XYZ user guesses, each in a string format.

Type:: list

multiplicity¶

The reaction surface multiplicity. A trivial guess will be made unless provided.

Type:: int

charge¶

The reaction surface charge.

Type:: int

index¶

An auto-generated index associating the ARCReaction object with the corresponding TS ARCSpecies object.

Type:: int

ts_label¶

The ARCSpecies label of the respective TS.

Type:: str

preserve_param_in_scan¶

Entries are length two iterables of atom indices (1-indexed) between which distances and dihedrals of these pivots must be preserved.

Type:: list

atom_map¶

An atom map, mapping the reactant atoms to the product atoms. I.e., an atom map of [0, 2, 1] means that reactant atom 0 matches product atom 0, reactant atom 1 matches product atom 2, and reactant atom 2 matches product atom 1.

Type:: List[int]

done_opt_r_n_p¶

Whether the optimization of all reactants and products is complete.

Type:: bool

arc_species_from_rmg_reaction()[source]¶: A helper function for generating the ARC Species (.r_species and .p_species) from the RMG Reaction object

as_dict(reset_atom_ids: bool = False) → dict[source]¶

A helper function for dumping this object as a dictionary in a YAML file for restarting ARC.

Parameters:: reset_atom_ids (bool, optional) – Whether to reset the atom IDs in the .mol Molecule attribute of reactant and product species. Useful when copying the object to avoid duplicate atom IDs between different object instances.
Returns:: The dictionary representation of the object instance.
Return type:: dict

property atom_map¶: The reactants to products atom map

property charge¶: The net electric charge of the reaction PES

check_atom_balance(ts_xyz: Optional[dict] = None, raise_error: bool = True) → bool[source]¶

Check atom balance between reactants, TSs, and product wells.

Parameters:

ts_xyz (Optional[dict]) – An alternative TS xyz to check. If unspecified, user guesses and the ts_species will be checked.
raise_error (bool, optional) – Whether to raise an error if an imbalance is found.

Raises:

ReactionError – If not all wells and TSs are atom balanced. The exception is not raised if raise_error is False.

Returns:

Whether all wells and TSs are atom balanced.

Return type:

bool

check_attributes()[source]¶: Check that the Reaction object is defined correctly

check_done_opt_r_n_p()[source]¶: Check whether the final_xyz attributes of all r_species and p_species are populated, and flag self.done_opt_r_n_p as True if they are. Useful to know when to spawn TS search jobs.

copy()[source]¶

Get a copy of this object instance.

Returns:: A copy of this object instance.
Return type:: ARCReaction

copy_e0_values(other_rxn: Optional[ARCReaction])[source]¶

Copy the E0 values from another reaction object instance for the TS and for all species if they have corresponding labels.

Parameters:: other_rxn (ARCReaction) – An ARCReaction object instance from which E0 values will be copied.

determine_family(rmg_database: RMGDatabase, save_order: bool = True)[source]¶

Determine the RMG family. Populates the .family, and .family_own_reverse attributes. A wrapper for the rmgdb determine_reaction_family() function.

Parameters:

rmg_database (RMGDatabase) – The RMGDatabase object instance.
save_order (bool, optional) – Whether to retain atomic order of the RMG reaction object instance.

flip_reaction()[source]¶

Get a copy of this object instance with flipped reactants and products.

Returns:: A copy of this object instance with flipped reactants and products.
Return type:: ARCReaction

from_dict(reaction_dict: dict, species_list: Optional[list] = None)[source]¶: A helper function for loading this object from a dictionary in a YAML file for restarting ARC.

get_bonds() → Tuple[list, list][source]¶

Get the connectivity of the reactants and products.

Returns:: A length-2 tuple is which entries represent reactants and product information, respectively. Each entry is a list of tuples, each represents a bond and contains sorted atom indices.
Return type:: Tuple[List[Tuple[int, int]]]

get_element_mass() → List[float][source]¶

Get the mass of all elements of a reaction. Uses the atom order of the reactants.

Returns:: The masses of all elements in the reactants.
Return type:: List[float]

get_expected_changing_bonds(r_label_dict: Dict[str, int]) → Tuple[Optional[List[Tuple[int, int]]], Optional[List[Tuple[int, int]]]][source]¶

Get the expected forming and breaking bonds from the RMG reaction template.

Parameters:: r_label_dict (Dict[str, int]) – The RMG reaction atom labels and corresponding atom indices of atoms in a TemplateReaction.
Returns:: A list of tuples of atom indices representing breaking and forming bonds.
Return type:: Tuple[List[Tuple[int, int]], List[Tuple[int, int]]]

get_number_of_atoms_in_reaction_zone() → Optional[int][source]¶

Get the number of atoms that participate in the reaction zone according to the reaction’s RMG recipe.

Returns:: The number of atoms that participate in the reaction zone.
Return type:: int

get_products_xyz(return_format='str') → Union[dict, str][source]¶

Get a combined string/dict representation of the cartesian coordinates of all product species. The resulting coordinates are ordered as the reactants using an atom map.

Parameters:: return_format (str) – Either 'dict' to return a dict format or 'str' to return a string format. Default: 'str'.

Returns: Union[dict, str]: The combined cartesian coordinates.

get_reactants_and_products(arc: bool = True, return_copies: bool = True) → Tuple[List[Union[ARCSpecies, Species]], List[Union[ARCSpecies, Species]]][source]¶

Get a list of reactant and product species including duplicate species, if any. The species could either be ARCSpecies or RMGSpecies object instance.

Parameters:

arc (bool, optional) – Whether to return the species as ARCSpecies (True) or as RMG Species (False).
return_copies (bool, optional) – Whether to return unique object instances using the copy() method.

Returns:

The reactants and products.

Return type:

Tuple[List[Union[ARCSpecies, Species]], List[Union[ARCSpecies, Species]]]

get_reactants_xyz(return_format='str') → Union[dict, str][source]¶

Get a combined string/dict representation of the cartesian coordinates of all reactant species.

Parameters:: return_format (str) – Either 'dict' to return a dict format or 'str' to return a string format. Default: 'str'.

Returns: Union[dict, str]: The combined cartesian coordinates.

get_rxn_charge()[source]¶: A helper function for determining the surface charge

get_rxn_multiplicity()[source]¶: A helper function for determining the surface multiplicity

get_rxn_smiles() → Optional[str][source]¶

returns the reaction smiles of the reaction.

Raises:: ValueError – If any of the species (reactants or products) has no SMILES (or could not be generated for some reason).

Returns: string: The reaction SMILES

get_single_mapped_product_xyz() → Optional[ARCSpecies][source]¶

Get a copy of the product species with mapped cartesian coordinates of a reaction with a single product.

Returns:: The corresponding ARCSpecies object with mapped coordinates.
Return type:: Optional[ARCSpecies]

get_species_count(species: Optional[ARCSpecies] = None, label: Optional[str] = None, well: int = 0) → int[source]¶

Get the number of times a species participates in the reactants or products well. Either species or label must be given.

Parameters:

species (ARCSpecies, optional) – The species to check.
label (str, optional) – The species label.
well (int, optional) – Either 0 or 1 for the reactants or products well, respectively.

Returns:

The number of occurrences of this species in the respective well.

Return type:

Optional[int]

is_isomerization()[source]¶

Determine whether this is an isomerization reaction.

Returns:: Whether this is an isomerization reaction.
Return type:: bool

property multiplicity¶: The electron spin multiplicity of the reaction PES

remove_dup_species()[source]¶: Make sure each species is considered only once in reactants, products, r_species, and p_species. The same species in the reactants/products is considered through get_species_count().

rmg_reaction_from_arc_species()[source]¶: A helper function for generating the RMG Reaction object from ARCSpecies Used for determining the family.

rmg_reaction_from_str(reaction_string: str)[source]¶: A helper function for regenerating the RMG Reaction object from a string representation

rmg_reaction_to_str() → str[source]¶: A helper function for dumping the RMG Reaction object as a string for the YAML restart dictionary

set_label_reactants_products(species_list: Optional[List[ARCSpecies]] = None)[source]¶: A helper function for settings the label, reactants, and products attributes for a Reaction

arc.reaction.remove_dup_species(species_list: List[ARCSpecies]) → List[ARCSpecies][source]¶

Remove duplicate species from a species list. Used when assigning r_species and p_species.

Parameters:: species_list (List[ARCSpecies]) – The species list to process.
Returns:: A list of species without duplicates.
Return type:: List[ARCSpecies]