arc.species.species

A module for representing stationary points (chemical species and transition states). If the species is a transition state (TS), its ts_guesses attribute will have one or more TSGuess objects.

class arc.species.species.ARCSpecies(adjlist: str = '', bdes: Optional[list] = None, bond_corrections: Optional[dict] = None, charge: Optional[int] = None, checkfile: Optional[str] = None, compute_thermo: Optional[bool] = None, consider_all_diastereomers: bool = True, directed_rotors: Optional[dict] = None, e0_only: bool = False, external_symmetry: Optional[int] = None, fragments: Optional[List[List[int]]] = None, force_field: str = 'MMFF94s', inchi: str = '', is_ts: bool = False, label: Optional[str] = None, mol: Optional[rmgpy.molecule.molecule.Molecule] = None, multiplicity: Optional[int] = None, number_of_radicals: Optional[int] = None, occ: Optional[int] = None, optical_isomers: Optional[int] = None, preserve_param_in_scan: Optional[list] = None, rmg_species: Optional[rmgpy.species.Species] = None, run_time: Optional[datetime.timedelta] = None, rxn_label: Optional[str] = None, rxn_index: Optional[int] = None, smiles: str = '', species_dict: Optional[dict] = None, ts_methods: Optional[List[str]] = None, ts_number: Optional[int] = None, xyz: Optional[Union[list, dict, str]] = None, yml_path: Optional[str] = None)[source]

A class for representing stationary points.

Structures (rotors_dict is initialized in conformers.find_internal_rotors; pivots/scan/top values are 1-indexed)::
rotors_dict: {0: {‘pivots’: List[int], # 1-indexed

‘top’: List[int], # 1-indexed ‘scan’: List[int], # 1-indexed ‘torsion’: List[int], # 0-indexed ‘number_of_running_jobs’: int, ‘success’: bool, ‘invalidation_reason’: str, ‘times_dihedral_set’: int, ‘scan_path’: <path to scan output file>, ‘max_e’: float, # relative to the minimum energy, in kJ/mol, ‘symmetry’: int, ‘dimensions’: int, ‘original_dihedrals’: list, ‘cont_indices’: list, ‘directed_scan_type’: str, ‘directed_scan’: dict, # keys: tuples of dihedrals as strings,

# values: dicts of energy, xyz, is_isomorphic, trsh

}

1: {}, …

}

Parameters
  • label (str, optional) – The species label.

  • is_ts (bool, optional) – Whether or not the species represents a transition state.

  • rmg_species (Species, optional) – An RMG Species object to be converted to an ARCSpecies object.

  • mol (Molecule, optional) – An RMG Molecule object used for BAC determination. Atom order corresponds to the order in .initial_xyz

  • xyz (list, str, dict, optional) – Entries are either string-format coordinates, file paths, or ARC’s dict format. (If there’s only one entry, it could be given directly, not in a list). The file paths could direct to either a .xyz file, ARC conformers (w/ or w/o energies), or an ESS log/input files.

  • multiplicity (int, optional) – The species’ electron spin multiplicity. Can be determined from the adjlist/smiles/xyz (If unspecified, assumed to be either a singlet or a doublet).

  • charge (int, optional) – The species’ net charge. Assumed to be 0 if unspecified.

  • smiles (str, optional) – A SMILES representation for the species 2D graph.

  • adjlist (str, optional) – An RMG adjacency list representation for the species 2D graph.

  • inchi (str, optional) – An InChI representation for the species 2D graph.

  • bond_corrections (dict, optional) – The bond additivity corrections (BAC) to be used. Determined from the structure if not directly given.

  • compute_thermo (bool, optional) – Whether to calculate thermodynamic properties for this species.

  • e0_only (bool, optional) – Whether to only run statmech (w/o thermo) to compute E0.

  • species_dict (dict, optional) – A dictionary to create this object from (used when restarting ARC).

  • yml_path (str, optional) – Path to an Arkane YAML file representing a species (for loading the object).

  • ts_methods (list, optional) – Methods to try for generating TS guesses. If Species is a TS and ts_methods is an empty list, then xyz (user guess) must be given. If ts_methods is None, it will be set to the default methods.

  • ts_number (int, optional) – An auto-generated number associating the TS ARCSpecies object with the corresponding ARCReaction object.

  • rxn_label (str, optional) – The reaction string (relevant for TSs).

  • rxn_index (int, optional) – The reaction index which is the respective key to the Scheduler rxn_dict.

  • external_symmetry (int, optional) – The external symmetry of the species (not including rotor symmetries).

  • optical_isomers (int, optional) – Whether (=2) or not (=1) the species has chiral center/s.

  • run_time (timedelta, optional) – Overall species execution time.

  • checkfile (str, optional) – The local path to the latest checkfile by Gaussian for the species.

  • number_of_radicals (int, optional) – The number of radicals (inputted by the user, ARC won’t attempt to determine it). Defaults to None. Important, e.g., if a Species is a bi-rad singlet, in which case the job should be unrestricted, but the multiplicity does not have the required information to make that decision (r vs. u).

  • force_field (str, optional) – The force field to be used for conformer screening. The default is MMFF94s. Other optional force fields are MMFF94, UFF, or GAFF (not recommended, slow). If ‘fit’ is specified for this parameter, some initial MMFF94s conformers will be generated, then force field parameters will be fitted for this molecule and conformers will be re-run with the fitted force field (recommended for drug-like species and species with many heteroatoms). Another option is specifying ‘cheap’, and the “old” RDKit embedding method will be used.

  • bdes (list, optional) – Specifying for which bonds should bond dissociation energies be calculated. Entries are bonded atom indices tuples (1-indexed). An ‘all_h’ string entry is also allowed, triggering BDE calculations for all hydrogen atoms in the molecule.

  • directed_rotors (dict) – Execute a directed internal rotation scan (i.e., a series of sp or constrained opt jobs) for the pivots of interest. The optional primary keys are: - ‘brute_force_sp’ - ‘brute_force_opt’ - ‘cont_opt’ - ‘ess’ The brute force methods will generate all the geometries in advance and submit all relevant jobs simultaneously. The continuous method will wait for the previous job to terminate, and use its geometry as the initial guess for the next job. Another set of three keys is allowed, adding _diagonal’ to each of the above keys. the secondary keys are therefore: - ‘brute_force_sp_diagonal’ - ‘brute_force_opt_diagonal’ - ‘cont_opt_diagonal’ Specifying ‘_diagonal’ will increment all the respective dihedrals together, resulting in a 1D scan instead of an ND scan. Values are nested lists. Each value is a list where the entries are either pivot lists (e.g., [1, 5]) or lists of pivot lists (e.g., [[1, 5], [6, 8]]), or a mix (e.g., [[4, 8], [[6, 9], [3, 4]]). The requested directed scan type will be executed separately for each list entry in the value. A list entry that contains only two pivots will result in a 1D scan, while a list entry with N pivots will consider all of them, and will result in an ND scan if ‘_diagonal’ is not specified. ARC will generate geometries using the ``rotor_scan_resolution` argument in settings.py Note: An ‘all’ string entry is also allowed in the value list, triggering a directed internal rotation scan for all torsions in the molecule. If ‘all’ is specified within a second level list, then all the dihedrals will be considered together. Currently ARC does not automatically identify torsions to be treated as ND, and this attribute must be specified by the user. An additional supported key is ‘ess’, in which case ARC will allow the ESS to take care of spawning the ND continuous constrained optimizations (not yet implemented).

  • consider_all_diastereomers (bool, optional) – Whether to consider all different chiralities (tetrahydral carbon centers, nitrogen inversions, and cis/trans double bonds) when generating conformers. True to consider all. If no 3D coordinates are given for the species, all diastereomers will be considered, otherwise the chirality specified by the given coordinates will be preserved.

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

  • fragments (Optional[List[List[int]]]) – Fragments represented by this species, i.e., as in a VdW well or a TS. Entries are atom index lists of all atoms in a fragment, each list represents a different fragment.

  • occ (int, optional) – The number of occupied orbitals (core + val) from a molpro CCSD sp calc.

label

The species’ label.

Type

str

original_label

The species’ label prior to modifications (removing fornidden characters).

Type

str

multiplicity

The species’ electron spin multiplicity. Can be determined from the adjlist/smiles/xyz (If unspecified, assumed to be either a singlet or a doublet).

Type

int

charge

The species’ net charge. Assumed to be 0 if unspecified.

Type

int

number_of_radicals

The number of radicals (inputted by the user, ARC won’t attempt to determine it). Defaults to None. Important, e.g., if a Species is a bi-rad singlet, in which case the job should be unrestricted, but the multiplicity does not have the required information to make that decision (r vs. u).

Type

int

e_elect

The total electronic energy (without ZPE) at the chosen sp level, in kJ/mol.

Type

float

e0

The 0 Kelvin energy (total electronic energy plus ZPE) at the chosen sp level, in kJ/mol.

Type

float

is_ts

Whether the species represents a transition state. True if it does.

Type

bool

number_of_rotors

The number of potential rotors to scan.

Type

int

rotors_dict

A dictionary of rotors. structure given below.

Type

dict

conformers

A list of selected conformers XYZs (dict format).

Type

list

conformer_energies

A list of conformers E0 (in kJ/mol).

Type

list

cheap_conformer

A string format xyz of a cheap conformer (not necessarily the best/lowest one).

Type

str

most_stable_conformer

The index of the best/lowest conformer in self.conformers.

Type

int

recent_md_conformer

A length three list containing the coordinates of the recent conformer generated by MD, the energy in kJ/mol, and the number of MD runs. Used to detect when the MD algorithm converges on a single structure.

Type

list

initial_xyz

The initial geometry guess.

Type

dict

final_xyz

The optimized species geometry.

Type

dict

_radius

The species radius in Angstrom.

Type

float

opt_level

Level of theory for geometry optimization. Saved for archiving.

Type

str

_number_of_atoms

The number of atoms in the species/TS.

Type

int

mol

An RMG Molecule object used for BAC determination. Atom order corresponds to the order in .initial_xyz

Type

Molecule

mol_list

A list of localized structures generated from ‘mol’, if possible.

Type

list

rmg_species

An RMG Species object to be converted to an ARCSpecies object.

Type

Species

bond_corrections

The bond additivity corrections (BAC) to be used. Determined from the structure if not directly given.

Type

dict

run_time

Overall species execution time.

Type

timedelta

t1

The T1 diagnostic parameter from Molpro.

Type

float

neg_freqs_trshed

A list of negative frequencies this species was troubleshooted for.

Type

list

compute_thermo

Whether to calculate thermodynamic properties for this species.

Type

bool

e0_only

Whether to only run statmech (w/o thermo) to compute E0.

Type

bool

thermo

The thermodata calculated by ARC.

Type

HeatCapacityModel

rmg_thermo

The thermodata generated by RMG for comparison.

Type

HeatCapacityModel

long_thermo_description

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

Type

str

ts_methods

Methods to try for generating TS guesses. If Species is a TS and ts_methods is an empty list, then xyz (user guess) must be given. If ts_methods is None, it will be set to the default methods.

Type

list

ts_guesses

A list of TSGuess objects for each of the specified methods.

Type

list

successful_methods

Methods used to generate a TS guess that successfully generated an XYZ guess.

Type

list

unsuccessful_methods

Methods used to generate a TS guess that were unsuccessfully.

Type

list

chosen_ts

The TSGuess index corresponding to the chosen TS conformer used for optimization.

Type

int

chosen_ts_method

The TS method that was actually used for optimization.

Type

str

ts_conf_spawned

Whether conformers were already spawned for the Species (representing a TS) based on its TSGuess objects.

Type

bool

tsg_spawned

If this species is a TS, this attribute describes whether TS guess jobs were already spawned.

Type

bool

ts_guesses_exhausted

Whether all TS guesses were tried out with no luck (True if no convergence achieved).

Type

bool

ts_number

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

Type

int

ts_report

A description of all methods used for guessing a TS and their ranking.

Type

str

rxn_label

The reaction string (relevant for TSs).

Type

str

rxn_index

The reaction index which is the respective key to the Scheduler rxn_dict.

Type

int

arkane_file

Path to the Arkane Species file generated in processor.

Type

str

yml_path

Path to an Arkane YAML file representing a species (for loading the object).

Type

str

checkfile

The local path to the latest checkfile by Gaussian for the species.

Type

str

external_symmetry

The external symmetry of the species (not including rotor symmetries).

Type

int

optical_isomers

Whether (=2) or not (=1) the species has chiral center/s.

Type

int

transport_data

A placeholder for updating transport properties after Lennard-Jones calculation (using OneDMin).

Type

TransportData

force_field

The force field to be used for conformer screening. The default is MMFF94s. Other optional force fields are MMFF94, UFF, or GAFF (not recommended, slow). If ‘fit’ is specified for this parameter, some initial MMFF94s conformers will be generated, then force field parameters will be fitted for this molecule and conformers will be re-run with the fitted force field (recommended for drug-like species and species with many heteroatoms). Another option is specifying ‘cheap’, and the “old” RDKit embedding method will be used.

Type

str

conf_is_isomorphic

Whether the lowest conformer is isomorphic with the 2D graph representation of the species. True if it is. Defaults to None. If True, an isomorphism check will be strictly enforced for the final optimized coordinates.

Type

bool

conformers_before_opt

Conformers XYZs of a species before optimization.

Type

tuple

bdes

Specifying for which bonds should bond dissociation energies be calculated. Entries are bonded atom indices tuples (1-indexed). An ‘all_h’ string entry is also allowed, triggering BDE calculations for all hydrogen atoms in the molecule.

Type

list

directed_rotors

Execute a directed internal rotation scan (i.e., a series of constrained optimizations). Data is in 3 levels of nested lists, converted from pivots to four-atom torsion indices.

Type

dict

consider_all_diastereomers

Whether to consider all different chiralities (tetrahydral carbon centers, nitrogen inversions, and cis/trans double bonds) when generating conformers. True to consider all.

Type

bool, optional

zmat

The species internal coordinates (Z Matrix).

Type

dict

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

fragments

Fragments represented by this species, i.e., as in a VdW well or a TS. Entries are atom index lists of all atoms in a fragment, each list represents a different fragment.

Type

Optional[List[List[int]]]

occ

The number of occupied orbitals (core + val) from a molpro CCSD sp calc.

Type

int

as_dict() → dict[source]

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

check_xyz_isomorphism(mol: Optional[rmgpy.molecule.molecule.Molecule] = None, xyz: Optional[dict] = None, allow_nonisomorphic_2d: Optional[bool] = False, verbose: Optional[bool] = True) → bool[source]

Check whether the perception of self.final_xyz or xyz is isomorphic with self.mol. If it is not isomorphic, compliant coordinates will be checked (equivalent to checking isomorphism without bond order information, only does not necessitates a molecule object, directly checks bond lengths).

Parameters
  • mol (Molecule, optional) – A molecule to check instead of self.mol.

  • xyz (dict, optional) – The coordinates to check instead of self.final_xyz.

  • allow_nonisomorphic_2d (bool, optional) – Whether to allow non-isomorphic representations to pass this test.

  • verbose (bool, optional) – Whether to log isomorphism findings and errors.

Returns: bool

Whether the perception of self.final_xyz is isomorphic with self.mol, True if it is.

copy()[source]

Get a copy of this object instance.

Returns

A copy of this object instance.

Return type

ARCSpecies

determine_multiplicity(smiles: str, adjlist: str, mol: Optional[rmgpy.molecule.molecule.Molecule])[source]

Determine the spin multiplicity of the species.

Parameters
  • smiles (str) – The SMILES descriptor .

  • adjlist (str) – The adjacency list descriptor.

  • mol (Molecule) – The respective RMG Molecule object.

determine_multiplicity_from_descriptors(smiles: str, adjlist: str, mol: Optional[rmgpy.molecule.molecule.Molecule])[source]

Determine the spin multiplicity of the species from the chemical descriptors.

Parameters
  • smiles (str) – The SMILES descriptor .

  • adjlist (str) – The adjacency list descriptor.

  • adjlist – The adjacency list descriptor.

  • mol (Molecule) – The respective RMG Molecule object.

determine_multiplicity_from_xyz()[source]

Determine the spin multiplicity of the species from the xyz.

determine_rotors() → None[source]

Determine possible unique rotors in the species to be treated as hindered rotors, taking into account all localized structures. The resulting rotors are saved in a {'pivots': [1, 3], 'top': [3, 7], 'scan': [2, 1, 3, 7]} format in self.rotors_dict. Also updates self.number_of_rotors.

determine_symmetry() → None[source]

Determine the external symmetry and chirality (optical isomers) of the species.

from_dict(species_dict)[source]

A helper function for loading this object from a dictionary in a YAML file for restarting ARC

from_yml_file(label: str = None)[source]

Load important species attributes such as label and final_xyz from an Arkane YAML file. Actual QM data parsing is done later when processing thermo and kinetics.

Parameters

label (str, optional) – The specie label.

Raises

ValueError – If the adjlist cannot be read.

generate_conformers(n_confs: int = 10, e_confs: float = 5, plot_path: str = None) → None[source]

Generate conformers.

Parameters
  • n_confs (int, optional) – The max number of conformers to store in the .conformers attribute that will later be DFT’ed at the conformers_level.

  • e_confs (float, optional) – The energy threshold in kJ/mol above the lowest energy conformer below which all (unique) generated conformers will be stored in the .conformers attribute.

  • plot_path (str, optional) – A folder path in which the plot will be saved. If None, the plot will not be shown (nor saved).

get_cheap_conformer()[source]

Cheaply (limiting the number of possible conformers) get a reasonable conformer, this could very well not be the best (lowest) one.

get_xyz(generate: bool = True) → Optional[dict][source]

Get the highest quality xyz the species has. If it doesn’t have any 3D information, and if generate is True, cheaply generate it. Returns None if no xyz can be retrieved nor generated.

Parameters

generate (bool, optional) – Whether to cheaply generate an FF conformer if no xyz is found. True to generate. If generate is False and the species has no xyz data, the method will return None.

Returns

The xyz coordinates.

Return type

dict

initialize_directed_rotors()[source]

Initialize self.directed_rotors, correcting the input to nested lists and to torsions instead of pivots. Also modifies self.rotors_dict to remove respective 1D rotors dicts if appropriate and adds ND rotors dicts. Principally, from this point we don’t really need self.directed_rotors, self.rotors_dict should have all relevant rotors info for the species, including directed and ND rotors.

Raises

SpeciesError – If the pivots don’t represent a dihedral in the species.

make_ts_report()[source]

A helper function to write content into the .ts_report attribute

mol_from_xyz(xyz: dict = None, get_cheap: bool = False) → None[source]

Make sure atom order in self.mol corresponds to xyz. Important for TS discovery and for identifying rotor indices. This works by generating a molecule from xyz and using the 2D structure to confirm that the perceived molecule is correct. If xyz is not given, the species xyz attribute will be used.

Parameters
  • xyz (dict, optional) – Alternative coordinates to use.

  • get_cheap (bool, optional) – Whether to generate conformers if the species has no xyz data.

property number_of_atoms

The number of atoms in the species

property number_of_heavy_atoms

The number of heavy (non hydrogen) atoms in the species

process_xyz(xyz_list: Union[list, str, dict])[source]

Process the user’s input and add either to the .conformers attribute or to .ts_guesses.

Parameters

xyz_list (list, str, dict) – Entries are either string-format, dict-format coordinates or file paths. (If there’s only one entry, it could be given directly, not in a list) The file paths could direct to either a .xyz file, ARC conformers (w/ or w/o energies), or an ESS log/input files, making this method extremely flexible. Internal coordinates (either string or dict) are also allowed and will be converted into cartesian coordinates.

property radius

Determine the largest distance from the coordinate system origin attributed to one of the molecule’s atoms in 3D space.

Returns

The radius in Angstrom.

Return type

float

scissors() → list[source]

Cut chemical bonds to create new species from the original one according to the .bdes attribute, preserving the 3D geometry other than the scissioned bond. If one of the scission-resulting species is a hydrogen atom, it will be returned last, labeled as ‘H’. Other species labels will be <original species label>_BDE_index1_index2_X, where “X” is either “A” or “B”, and the indices are 1-indexed.

Returns: list

The scission-resulting species.

set_dihedral(scan: list, deg_increment: float = None, deg_abs: float = None, count: bool = True, xyz: dict = None, chk_rotor_list: bool = True)[source]

Generated an RDKit molecule object from either self.final_xyz or xyz. Increments the current dihedral angle between atoms i, j, k, l in the scan list by ‘deg_increment` in degrees. Alternatively, specifying deg_abs will rotate to this desired dihedral. All bonded atoms are moved accordingly. The result is saved in self.initial_xyz.

Parameters
  • scan (list) – The atom indices (1-indexed) representing the dihedral.

  • deg_increment (float, optional) – The dihedral angle increment.

  • deg_abs (float, optional) – The absolute desired dihedral angle.

  • count (bool, optional) – Whether to increment the rotor’s times_dihedral_set parameter. True to increment.

  • xyz (dict, optional) – An alternative xyz to use instead of self.final_xyz.

  • chk_rotor_list (bool, optional) – Whether to check if the changing dihedral is in the rotor list.

Raises
  • InputError – If both deg_increment and deg_abs are None.

  • RotorError – If the rotor could not be identified based on the pivots.

  • TypeError – If deg_increment or deg_abs are of wrong type.

set_mol_list()[source]

Set the .mol_list attribute from self.mol by generating resonance structures, preserving atom order. The mol_list attribute is used for identifying rotors and generating conformers.

set_transport_data(lj_path: str, opt_path: str, bath_gas: str, opt_level: arc.level.Level, freq_path: Optional[str] = '', freq_level: Optional[arc.level.Level] = None)[source]

Set the species.transport_data attribute after a Lennard-Jones calculation (via OneDMin).

Parameters
  • lj_path (str) – The path to a oneDMin job output file.

  • opt_path (str) – The path to an opt job output file.

  • bath_gas (str) – The oneDMin job bath gas.

  • opt_level (Level) – The optimization level of theory.

  • freq_path (str, optional) – The path to a frequencies job output file.

  • freq_level (Level, optional) – The frequencies level of theory.

class arc.species.species.TSGuess(method: Optional[str] = None, reactants_xyz: Optional[list] = None, products_xyz: Optional[list] = None, family: Optional[str] = None, xyz: Optional[Union[dict, str]] = None, rmg_reaction: Optional[rmgpy.reaction.Reaction] = None, arc_reaction: Optional = None, ts_dict: Optional[dict] = None, energy: Optional[float] = None, project_dir: Optional[str] = None)[source]

TSGuess class

The user can define xyz directly, and the default method will be ‘User guess’. Alternatively, either ARC or the user can provide reactant/s and product/s geometries with a specified method. method could be one of the following: - QST2 (not implemented) - DEGSM (not implemented) - NEB (not implemented) - Kinbot: requires the RMG family, only works for H,C,O,S (not implemented) - AutoTST - GCN

Parameters
  • method (str, optional) – The method/source used for the xyz guess.

  • reactants_xyz (list, optional) – A list of tuples, each containing: (reactant label, reactant geometry in string format).

  • products_xyz (list, optional) – A list of tuples, each containing: (product label, product geometry in string format).

  • family (str, optional) – The RMG family that corresponds to the reaction, if applicable.

  • xyz (dict, str, optional) – The 3D coordinates guess.

  • rmg_reaction (Reaction, optional) – An RMG Reaction object.

  • arc_reaction (ARCReaction, optional) – An ARC Reaction object.

  • ts_dict (dict, optional) – A dictionary to create this object from (used when restarting ARC).

  • energy (float, optional) – Relative energy of all TS conformers in kJ/mol.

  • project_dir (str, optional) – Folder path for the project: the input file path or ARC/Projects/project-name.

initial_xyz

The 3D coordinates guess.

Type

dict

opt_xyz

The 3D coordinates after optimization at the ts_guesses level.

Type

dict

method

The method/source used for the xyz guess.

Type

str

reactants_xyz

A list of tuples, each containing: (reactant label, reactant xyz).

Type

list

products_xyz

A list of tuples, each containing: (product label, product xyz).

Type

list

family

The RMG family that corresponds to the reaction, if applicable.

Type

str

rmg_reaction

An RMG Reaction object.

Type

Reaction

arc_reaction

An ARC Reaction object.

Type

ARCReaction, optional

t0

Initial time of spawning the guess job.

Type

float

execution_time

Overall execution time for the TS guess method.

Type

str

success

Whether the TS guess method succeeded in generating an XYZ guess or not.

Type

bool

energy

Relative energy of all TS conformers in kJ/mol.

Type

float

index

An index corresponding to the conformer jobs spawned for each TSGuess object. Assigned only if self.success is True.

Type

int

project_dir

Folder path for the project: the input file path or ARC/Projects/project-name.

Type

str

as_dict() → dict[source]

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

autotst()[source]

Determine a TS guess using AutoTST for the following RMG families: Current supported families are: - H_Abstraction Near-future supported families might be: - Disproportionation - R_Addition_MultipleBond - intra_H_migration

degsm()[source]

Determine a TS guess using DEGSM

execute_ts_guess_method()[source]

Execute a TS guess method

from_dict(ts_dict: dict)[source]

A helper function for loading this object from a dictionary in a YAML file for restarting ARC

gcn()[source]

Determine a TS guess using a graph convolutional network.

Reactant and product must each be a single fragment.

kinbot()[source]

Determine a TS guess using Kinbot for RMG’s unimolecular families

neb()[source]

Determine a TS guess using NEB

process_xyz(xyz: dict)[source]

Process the user’s input. If xyz represents a file path, parse it.

Parameters

xyz (dict, str) – The coordinates in a dict/string form or a path to a file containing the coordinates.

Raises

InputError – If xyz is of wrong type.

qst2()[source]

Determine a TS guess using QST2

arc.species.species.are_coords_compliant_with_graph(xyz: dict, mol: rmgpy.molecule.molecule.Molecule) → bool[source]

Check whether the Cartesian coordinates represent the same 2D connectivity as the graph. Bond orders are not considered here, this function checks whether the coordinates represent a bond length below 120% of the single bond length of the respective elements.

Parameters
  • xyz (dict) – The Cartesian coordinates.

  • mol (Molecule) – The 2D graph connectivity information.

Returns

Whether the coordinates are compliant with the 2D connectivity graph. True if they are.

Return type

bool

arc.species.species.check_atom_balance(entry_1: Union[dict, str, rmgpy.molecule.molecule.Molecule], entry_2: Union[dict, str, rmgpy.molecule.molecule.Molecule], verbose: Optional[bool] = True) → bool[source]

Check whether the two entries are in atom balance.

Parameters
  • entry_1 (Union[dict, str, Molecule]) – Either an xyz (dict or str) or an RMG Molecule object.

  • entry_2 (Union[dict, str, Molecule]) – Either an xyz (dict or str) or an RMG Molecule object.

  • verbose (Optional[bool]) – Whether to log the differences if found.

Raises

SpeciesError – If both entries are empty.

Returns

Whether entry1 and entry2 are in atomic balance. True id they are.

Return type

bool

arc.species.species.check_label(label: str, verbose: bool = False) → Tuple[str, Optional[str]][source]

Check whether a species (or reaction) label is illegal, modify it if needed.

Parameters
  • label (str) – A label.

  • verbose (str, optional) – Whether to log errors.

Returns: Tuple[str, Optional[str]]
  • A legal label.

  • The original label if the label was modified, else None.

arc.species.species.check_xyz(xyz: dict, multiplicity: int, charge: int) → bool[source]

Checks xyz for electronic consistency with the spin multiplicity and charge.

Parameters
  • xyz (dict) – The species coordinates.

  • multiplicity (int) – The species spin multiplicity.

  • charge (int) – The species net charge.

Returns

Whether the input arguments are all in agreement. True if they are.

Return type

bool

arc.species.species.cyclic_index_i_minus_1(i: int) → int[source]

A helper function for cyclic indexing rotor scans

arc.species.species.cyclic_index_i_plus_1(i: int, length: int) → int[source]

A helper function for cyclic indexing rotor scans

arc.species.species.determine_occ(xyz, charge)[source]

Determines the number of occupied orbitals for an MRCI calculation.

Todo

arc.species.species.determine_rotor_symmetry(label: str, pivots: Union[List[int], str], rotor_path: str = '', energies: Optional[Union[list, numpy.ndarray]] = None, return_num_wells: bool = False, log: bool = True) → Tuple[int, float, Optional[int]][source]

Determine the rotor symmetry number from a potential energy scan. The worst resolution for each peak and valley is determined. The first criterion for a symmetric rotor is that the highest peak and the lowest peak must be within the worst peak resolution (and the same is checked for valleys). A second criterion for a symmetric rotor is that the highest and lowest peaks must be within 10% of the highest peak value. This is only applied if the highest peak is above 2 kJ/mol.

Parameters
  • label (str) – The species label (used for error messages).

  • pivots (list) – A list of two atom indices representing the pivots.

  • rotor_path (str) – The path to an ESS output rotor scan file.

  • energies (list, optional) – The list of energies in the scan in kJ/mol.

  • return_num_wells (bool, optional) – Whether to also return the number of wells, True to return, default is False.

  • log (bool, optional) – Whether to log info, error, and warning messages.

Raises
  • InputError – If both or none of the rotor_path and energy arguments are given,

  • or if rotor_path does not point to an existing file.

Returns

int: The symmetry number float: The highest torsional energy barrier in kJ/mol. int (optional): The number of peaks, only returned if return_len_peaks is True.

Return type

Tuple[int, float, int]

arc.species.species.determine_rotor_type(rotor_path: str) → str[source]

Determine whether this rotor should be treated as a HinderedRotor of a FreeRotor according to its maximum peak.

arc.species.species.enumerate_bonds(mol: rmgpy.molecule.molecule.Molecule) → dict[source]

A helper function for calling Molecule.enumerate_bonds. First, get the Kekulized molecule (get the Kekule version with alternating single and double bonds if the molecule is aromatic), since we don’t have implementation for aromatic bond additivity corrections.

Parameters

mol (Molecule) – The 2D graph representation of the molecule.

Returns

Keys are bond types (elements and bond order symbol), values are number of occurrences per bond type.

Return type

dict

arc.species.species.nearly_equal(a: float, b: float, sig_fig: int = 5)[source]

A helper function to determine whether two floats are nearly equal. Can be replaced by math.isclose in Py3