arc.main¶

ARC’s main module. To run ARC through its API, first make an instance of the ARC class, then call the .execute() method. For example:

arc = ARC(project='ArcDemo', species=[spc0, spc1, spc2])
arc.execute()

Where spc0, spc1, and spc2 in the above example are ARCSpecies objects.

class arc.main.ARC(adaptive_levels: Optional[dict] = None, allow_nonisomorphic_2d: bool = False, arkane_level_of_theory: Optional[Union[str, dict, Level]] = None, bac_type: Optional[str] = 'p', bath_gas: Optional[str] = None, calc_freq_factor: bool = True, compare_to_rmg: bool = True, composite_method: Optional[Union[str, dict, Level]] = None, compute_rates: bool = True, compute_thermo: bool = True, compute_transport: bool = False, conformer_level: Optional[Union[str, dict, Level]] = None, dont_gen_confs: Optional[List[str]] = None, e_confs: float = 5.0, ess_settings: Optional[Dict[str, Union[str, List[str]]]] = None, freq_level: Optional[Union[str, dict, Level]] = None, freq_scale_factor: Optional[float] = None, irc_level: Optional[Union[str, dict, Level]] = None, keep_checks: bool = False, kinetics_adapter: str = 'Arkane', job_memory: Optional[int] = None, job_types: Optional[Dict[str, bool]] = None, level_of_theory: str = '', max_job_time: Optional[float] = None, n_confs: int = 10, opt_level: Optional[Union[str, dict, Level]] = None, orbitals_level: Optional[Union[str, dict, Level]] = None, output: Optional[dict] = None, output_multi_spc: Optional[dict] = None, project: Optional[str] = None, project_directory: Optional[str] = None, reactions: Optional[List[Union[ARCReaction, Reaction]]] = None, running_jobs: Optional[dict] = None, scan_level: Optional[Union[str, dict, Level]] = None, sp_level: Optional[Union[str, dict, Level]] = None, species: Optional[List[Union[ARCSpecies, Species]]] = None, specific_job_type: str = '', T_min: Optional[Tuple[float, str]] = None, T_max: Optional[Tuple[float, str]] = None, T_count: int = 50, thermo_adapter: str = 'Arkane', three_params: bool = True, trsh_ess_jobs: bool = True, ts_adapters: Optional[List[str]] = None, ts_guess_level: Optional[Union[str, dict, Level]] = None, verbose=20, report_e_elect: Optional[bool] = False, skip_nmd: Optional[bool] = False)[source]¶

The main ARC class.

Parameters:

project (str, optional) – The project’s name. Used for naming the working directory.
species (list, optional) – Entries are ARCSpecies objects.
reactions (list, optional) – A list of ARCReaction objects.
level_of_theory (str, optional) – A shortcut representing either sp//geometry levels or a composite method. e.g., ‘CBS-QB3’, ‘CCSD(T)-F12a/aug-cc-pVTZ//B3LYP/6-311++G(3df,3pd)’… Notice that this argument does NOT support levels with slashes in the name. e.g., ‘ZINDO/2’, ‘DLPNO-MP2-F12/D’ For these cases, use the dictionary-type job-specific level of theory arguments instead (e.g., opt_level).
composite_method (str, dict, Level, optional) – Composite method.
conformer_level (str, dict, Level, optional) – Level of theory for conformer searches.
opt_level (str, dict, Level, optional) – Level of theory for geometry optimization.
freq_level (str, dict, Level, optional) – Level of theory for frequency calculations.
sp_level (str, dict, Level, optional) – Level of theory for single point calculations.
scan_level (str, dict, Level, optional) – Level of theory for rotor scans.
ts_guess_level (str, dict, Level, optional) – Level of theory for comparisons of TS guesses between different methods.
irc_level (str, dict, Level, optional) – The level of theory to use for IRC calculations.
orbitals_level (str, dict, Level, optional) – Level of theory for molecular orbitals calculations.
bac_type (str, optional) – The bond additivity correction type. ‘p’ for Petersson- or ‘m’ for Melius-type BAC. Default: ‘p’. None to not use BAC.
job_types (dict, optional) – A dictionary of job types to execute. Keys are job types, values are boolean.
arkane_level_of_theory (Union[dict, Level, str], optional) –
The Arkane level of theory to use for AEC and BAC.

Note

This argument is a Level type, not a LevelOfTheory type. This argument will only affect AEC/BAC, not the frequency scaling factor.
T_min (tuple, optional) – The minimum temperature for kinetics computations, e.g., (500, 'K').
T_max (tuple, optional) – The maximum temperature for kinetics computations, e.g., (3000, 'K').
T_count (int, optional) – The number of temperature points between T_min and T_max.
verbose (int, optional) – The logging level to use.
project_directory (str, optional) – The path to the project directory.
max_job_time (float, optional) – The maximal allowed job time on the server in hours (can be fractional).
allow_nonisomorphic_2d (bool, optional) – Whether to optimize species even if they do not have a 3D conformer that is isomorphic to the 2D graph representation.
job_memory (int, optional) – The total allocated job memory in GB (14 by default to be lower than 90% * 16 GB).
ess_settings (dict, optional) – A dictionary of available ESS (keys) and a corresponding server list (values).
bath_gas (str, optional) – A bath gas. Currently used in OneDMin to calc L-J parameters. Allowed values are He, Ne, Ar, Kr, H2, N2, O2.

adaptive_levels (dict, optional) –

A dictionary of levels of theory for ranges of the number of heavy atoms in the molecule. Keys are tuples of (min_num_atoms, max_num_atoms), values are dictionaries. Keys of the sub-dictionaries are tuples of job types, values are levels of theory (str, dict or Level). Job types not defined in adaptive levels will have non-adaptive (regular) levels. Example:

adaptive_levels = {(1, 5):      {('opt', 'freq'): 'wb97xd/6-311+g(2d,2p)',
                                 'sp': 'ccsd(t)-f12/aug-cc-pvtz-f12'},
                   (6, 15):     {('opt', 'freq'): 'b3lyp/cbsb7',
                                 'sp': 'dlpno-ccsd(t)/def2-tzvp'},
                   (16, 30):    {('opt', 'freq'): 'b3lyp/6-31g(d,p)',
                                 'sp': 'wb97xd/6-311+g(2d,2p)'},
                   (31, 'inf'): {('opt', 'freq'): 'b3lyp/6-31g(d,p)',
                                 'sp': 'b3lyp/6-311+g(d,p)'}}

freq_scale_factor (float, optional) – The harmonic frequencies scaling factor. Could be automatically determined if not available in Arkane and not provided by the user.
calc_freq_factor (bool, optional) – Whether to calculate the frequencies scaling factor using Truhlar’s method if it was not given by the user and could not be determined by Arkane. True to calculate, False to use user input / Arkane’s value / Arkane’s default.
n_confs (int, optional) – The number of lowest force field conformers to consider.
e_confs (float, optional) – The energy threshold in kJ/mol above the lowest energy conformer below which force field conformers are considered.
keep_checks (bool, optional) – Whether to keep ESS checkfiles when ARC terminates. True to keep, default is False.
dont_gen_confs (list, optional) – A list of species labels for which conformer generation should be avoided if xyz is given.
compare_to_rmg (bool, optional) – If True data calculated from the RMG-database will be calculated and included on the parity plot.
compute_thermo (bool, optional) – Whether to compute thermodynamic properties for converged species.
compute_rates (bool, optional) – Whether to compute rate coefficients for converged reactions.
compute_transport (bool, optional) – Whether to compute transport properties for converged species.
specific_job_type (str, optional) – A specific job type to execute. Legal strings are job types (keys of job_types dict).
thermo_adapter (str, optional) – The statmech software to use for thermodynamic property calculations. Default: ‘Arkane’.
kinetics_adapter (str, optional) – The statmech software to use for kinetic rate coefficient calculations. Default: ‘Arkane’.
three_params (bool, optional) – Compute rate coefficients using the modified three-parameter Arrhenius equation format (True, default) or classical two-parameter Arrhenius equation format (False).
trsh_ess_jobs (bool, optional) – Whether to attempt troubleshooting failed ESS jobs. Default is True.
output (dict, optional) – Output dictionary with status and final QM file paths for all species. Only used for restarting.
output_multi_spc (dict, optional) – Output dictionary with status and final QM file paths for the multi species. Only used for restarting.
running_jobs (dict, optional) – A dictionary of jobs submitted in a precious ARC instance, used for restarting.
ts_adapters (list, optional) – Entries represent different TS adapters.
report_e_elect (bool, optional) – Whether to report electronic energy. Default is False.
skip_nmd (bool, optional) – Whether to skip normal mode displacement check. Default is False.

project¶

The project’s name. Used for naming the working directory.

Type:: str

project_directory¶

The path to the project directory.

Type:: str

species¶

A list of ARCSpecies objects.

Type:: list

reactions¶

A list of ARCReaction objects.

Type:: list

level_of_theory¶

A shortcut representing either sp//geometry levels or a composite method.

Type:: str

composite_method¶

Composite method.

Type:: Level

conformer_level¶

Level of theory for conformer searches.

Type:: Level

opt_level¶

Level of theory for geometry optimization.

Type:: Level

freq_level¶

Level of theory for frequency calculations.

Type:: Level

sp_level¶

Level of theory for single point calculations.

Type:: Level

scan_level¶

Level of theory for rotor scans.

Type:: Level

ts_guess_level¶

Level of theory for comparisons of TS guesses between different methods.

Type:: Level

irc_level¶

The level of theory to use for IRC calculations.

Type:: Level

orbitals_level¶

Level of theory for molecular orbitals calculations.

Type:: Level

adaptive_levels¶

A dictionary of levels of theory for ranges of the number of heavy atoms in the molecule. Keys are tuples of (min_num_atoms, max_num_atoms), values are dictionaries. Keys of the sub-dictionaries are tuples of job types, values are levels of theory (str, dict or Level). Job types not defined in adaptive levels will have non-adaptive (regular) levels.

Type:: dict

output¶

Output dictionary with status and final QM file paths for all species. Only used for restarting, the actual object used is in the Scheduler class.

Type:: dict

output_multi_spc¶

Output dictionary with status and final QM file paths for the multi species. Only used for restarting, the actual object used is in the Scheduler class.

Type:: dict

bac_type¶

The bond additivity correction type. ‘p’ for Petersson- or ‘m’ for Melius-type BAC. None to not use BAC.

Type:: str

arkane_level_of_theory¶

The Arkane level of theory to use for AEC and BAC.

Type:: Level

freq_scale_factor¶

The harmonic frequencies scaling factor. Could be automatically determined if not available in Arkane and not provided by the user.

Type:: float

calc_freq_factor¶

Whether to calculate the frequencies scaling factor using Truhlar’s method if it was not given by the user and could not be determined by Arkane. True to calculate, False to use user input / Arkane’s value / Arkane’s default.

Type:: bool

ess_settings¶

A dictionary of available ESS (keys) and a corresponding server list (values).

Type:: dict

t0¶

Initial time when the project was spawned.

Type:: float

n_confs¶

The number of lowest force field conformers to consider.

Type:: int

e_confs¶

The energy threshold in kJ/mol above the lowest energy conformer below which force field conformers are considered.

Type:: float

execution_time¶

Overall execution time.

Type:: str

lib_long_desc¶

A multiline description of levels of theory for the outputted RMG libraries.

Type:: str

running_jobs¶

A dictionary of jobs submitted in a precious ARC instance, used for restarting.

Type:: dict

T_min¶

The minimum temperature for kinetics computations, e.g., (500, ‘K’).

Type:: tuple

T_max¶

The maximum temperature for kinetics computations, e.g., (3000, ‘K’).

Type:: tuple

T_count¶

The number of temperature points between T_min and T_max.

Type:: int

max_job_time¶

The maximal allowed job time on the server in hours (can be fractional).

Type:: float

rmg_database¶

The RMG database object.

Type:: RMGDatabase

allow_nonisomorphic_2d¶

Whether to optimize species even if they do not have a 3D conformer that is isomorphic to the 2D graph representation.

Type:: bool

memory¶

The total allocated job memory in GB (14 by default to be lower than 90% * 16 GB).

Type:: int

job_types¶

A dictionary of job types to execute. Keys are job types, values are boolean.

Type:: dict

specific_job_type¶

A specific job type to execute. Legal strings are job types (keys of job_types dict).

Type:: str

bath_gas¶

A bath gas. Currently used in OneDMin to calc L-J parameters. Allowed values are He, Ne, Ar, Kr, H2, N2, O2.

Type:: str

keep_checks¶

Whether to keep all Gaussian checkfiles when ARC terminates. True to keep, default is False.

Type:: bool

dont_gen_confs¶

A list of species labels for which conformer generation should be avoided if xyz is given.

Type:: list

compare_to_rmg¶

If True data calculated from the RMG-database will be calculated and included on the parity plot.

Type:: bool

compute_thermo¶

Whether to compute thermodynamic properties for converged species.

Type:: bool

compute_rates¶

Whether to compute rate coefficients for converged reactions.

Type:: bool

compute_transport¶

Whether to compute transport properties for converged species.

Type:: bool

thermo_adapter¶

The statmech software to use for thermodynamic property calculations.

Type:: str

kinetics_adapter¶

The statmech software to use for kinetic rate coefficient calculations.

Type:: str

fine_only¶

If self.job_types['fine'] and not self.job_types['opt'] ARC will not run optimization jobs without fine=True

Type:: bool

three_params¶

Compute rate coefficients using the modified three-parameter Arrhenius equation format (True) or classical two-parameter Arrhenius equation format (False).

Type:: bool

trsh_ess_jobs¶

Whether to attempt troubleshooting failed ESS jobs. Default is True.

Type:: bool

ts_adapters¶

Entries represent different TS adapters.

Type:: list

report_e_elect¶

Whether to report electronic energy.

Type:: bool

skip_nmd¶

Whether to skip normal mode displacement check.

Type:: bool

add_hydrogen_for_bde()[source]¶: Make sure ARC has a hydrogen species labeled as ‘H’ for the final processing of bde jobs (if not, create one).

as_dict() → dict[source]¶: A helper function for dumping this object as a dictionary in a YAML file for restarting ARC.

backup_restart()[source]¶: Make a backup copy of the restart file if it exists (but don’t save an updated one just yet)

check_arkane_level_of_theory()[source]¶: Check that the level of theory has AEC in Arkane.

check_freq_scaling_factor()[source]¶: Check that the harmonic frequencies scaling factor is known, otherwise, and if calc_freq_factor is set to True, spawn a calculation for it using Truhlar’s method.

check_project_name()[source]¶: Check the validity of the project name.

delete_leftovers()[source]¶: Delete leftover files, e.g., files created by the Symmetry program.

determine_ess_settings(diagnostics=False)[source]¶: Determine where each ESS is available, locally (in running on a server) and/or on remote servers. if diagnostics is True, this method will not raise errors, and will print its findings.

determine_unique_species_labels()[source]¶

Determine unique species labels.

Raises:: ValueError – If a non-unique species is found.

execute() → dict[source]¶

Execute ARC.

Returns: dict: Status dictionary indicating which species converged successfully.

process_level_of_theory()[source]¶: Process the level_of_theory argument, and populate respective job level of theory arguments as needed.

save_project_info_file()[source]¶: Save a project info file.

set_levels_of_theory()[source]¶: Set all levels of theory by job type to be Level types.

standardize_output_paths()[source]¶: Standardize the paths in the output dictionary.

summary() → dict[source]¶

Report status and data of all species / reactions.

Returns: dict: Status dictionary indicating which species converged successfully.

write_input_file(path=None)[source]¶

Save the current attributes as an ARC input file.

Parameters:: path (str, optional) – The full path for the generated input file.

class arc.main.StatmechEnum(value)[source]¶: The supported statmech software adapters. The available adapters are a finite set.

arc.main.process_adaptive_levels(adaptive_levels: Optional[dict]) → Optional[dict][source]¶

Process the adaptive_levels argument.

Parameters:: adaptive_levels (dict) – The adaptive levels dictionary.

Returns: dict: The processed adaptive levels dictionary.