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[dict, arc.level.Level, str]] = None, bac_type: str = 'p', bath_gas: Optional[str] = None, calc_freq_factor: bool = True, compare_to_rmg: bool = True, composite_method: Optional[Union[dict, arc.level.Level, str]] = None, compute_rates: bool = True, compute_thermo: bool = True, compute_transport: bool = False, conformer_level: Optional[Union[dict, arc.level.Level, str]] = None, dont_gen_confs: List[str] = None, e_confs: float = 5.0, ess_settings: Dict[str, Union[str, List[str]]] = None, freq_level: Optional[Union[dict, arc.level.Level, str]] = None, freq_scale_factor: Optional[float] = None, irc_level: Optional[Union[dict, arc.level.Level, str]] = 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[dict, arc.level.Level, str]] = None, orbitals_level: Optional[Union[dict, arc.level.Level, str]] = None, output: Optional[dict] = None, project: Optional[str] = None, project_directory: Optional[str] = None, reactions: Optional[List[Union[arc.reaction.ARCReaction, rmgpy.reaction.Reaction]]] = None, running_jobs: Optional[dict] = None, scan_level: Optional[Union[dict, arc.level.Level, str]] = None, sp_level: Optional[Union[dict, arc.level.Level, str]] = None, species: Optional[List[Union[arc.species.species.ARCSpecies, rmgpy.species.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, ts_guess_level: Optional[Union[dict, arc.level.Level, str]] = None, verbose=20)[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 all Gaussian 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).

  • output (dict, optional) – Output dictionary with status and final QM file paths for all species. Only used for restarting.

  • running_jobs (dict, optional) – A dictionary of jobs submitted in a precious ARC instance, used for restarting.

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

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

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

Delete Gaussian and TeraChem checkfiles. They usually take up lots of space and are not needed after ARC terminates. Pass True to the keep_checks flag in ARC to avoid deleting check files.

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.

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.