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[arc.species.species.ARCSpecies]] = None, p_species: Optional[List[arc.species.species.ARCSpecies]] = None, ts_label: Optional[str] = None, rmg_reaction: Optional[rmgpy.reaction.Reaction] = None, ts_methods: Optional[List[str]] = None, ts_xyz_guess: Optional[list] = None, multiplicity: Optional[int] = None, charge: Optional[int] = None, reaction_dict: Optional[dict] = None, species_list: Optional[List[arc.species.species.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, optional) – A list of reactant labels corresponding to an ARCSpecies.

  • products (list, optional) – A list of product labels corresponding to an ARCSpecies.

  • r_species (list, optional) – A list of reactants ARCSpecies objects.

  • p_species (list, 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_methods (list, optional) – Methods to try for generating TS guesses. If an ARCSpecies is a TS and ts_methods is empty (passing an empty list), then xyz (user guess) must be given.

  • ts_xyz_guess (list, optional) – A list of TS XYZ user guesses, each in a string format.

  • 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

products

A list of products labels corresponding to an ARCSpecies.

Type

list

r_species

A list of reactants ARCSpecies objects.

Type

list

p_species

A list of products ARCSpecies objects.

Type

list

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_methods

Methods to try for generating TS guesses. If an ARCSpecies is a TS and ts_methods is empty (passing an empty list), then xyz (user guess) must be given.

Type

list

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() → dict[source]

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

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.

check_ts(verbose: bool = True, parameter: str = 'E0') → bool[source]

Check that the TS E0 or electronic energy is above both reactant and product wells. By default E0 is checked first. If it is not available for all species and TS, the electronic energy is checked. If the check cannot be performed, the method still returns True.

Parameters
  • verbose (bool, optional) – Whether to print logging messages.

  • parameter (str, optional) – The energy parameter to consider (‘E0’ or ‘e_elect’).

Returns

Whether the TS E0 or electronic energy is above both reactant and product wells, True if it is.

Return type

bool

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 rmgdb determine_reaction_family() function.

Parameters
  • rmg_database (RMGDatabase) – The RMG database instance.

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

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_atom_map(verbose: int = 0) → Optional[List[int]][source]

Get the atom mapping of 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. All indices are 0-indexed.

Employs the Kabsch, Hungarian, and Uno algorithms to exhaustively locate the best alignment for non-oriented, non-ordered 3D structures.

Parameters

verbose (int) – The verbosity level (0-4).

Returns: Optional[List[int]]

The atom map, entry indices correspond to reactant indices, entry values correspond to product indices.

get_mapped_product_xyz()[source]

Uses the mapping from product onto reactant to create a new ARC Species for the mapped product. For now, only functional for A <=> B reactions.

Returns

dict: Mapped product atoms in ARC dictionary format. ARCSpecies: ARCSpecies object created from mapped coordinates.

Return type

Tuple[dict, ARCSpecies]

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. :param return_format: 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) → Tuple[List[Union[arc.species.species.ARCSpecies, rmgpy.species.Species]], List[Union[arc.species.species.ARCSpecies, rmgpy.species.Species]]][source]

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

Parameters

arc (bool, optional) – Whether to return the species as ARCSpecies (True) or as RMG Species (False).

Returns

The reactants and products.

Return type

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

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_species_count(species: Optional[arc.species.species.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 consider 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[arc.species.species.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[arc.species.species.ARCSpecies]) → List[arc.species.species.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]