The ARC troubleshooting (“trsh”) module

arc.job.trsh.determine_ess_status(output_path: str, species_label: str, job_type: str, software: str = None)[source]

Determine the reason that caused an ESS job to crash, assign error keywords for troubleshooting.

  • output_path (str) – The path to the ESS output file.

  • species_label (str) – The species label.

  • job_type (str) – The job type (e.g., ‘opt, ‘freq’, ‘ts’, ‘sp’).

  • software (str, optional) – The ESS software.

Returns: Tuple[str, list, str, str]
  • The status. Either ‘done’ or ‘errored’.

  • The standardized error keywords.

  • A description of the error.

  • The parsed line from the ESS output file indicating the error.

arc.job.trsh.scan_quality_check(label: str, pivots: list, energies: list, scan_res: float = 8.0, used_methods: Optional[list] = None, log_file: Optional[str] = None, species: Optional[arc.species.species.ARCSpecies] = None, preserve_params: Optional[list] = None, trajectory: Optional[list] = None, original_xyz: Optional[dict] = None) → Tuple[bool, str, str, dict][source]

Checks the scan’s quality:

  1. Based on intermediate conformers if available:

    • whether the initial and final points are consistent

    • whether it is relatively “smooth”

  2. Based on the PES curve (if intermediate conformers are unavailable):

    • whether the initial and final points are consistent

    • whether it is relatively “smooth”

  3. Common:

    • whether the optimized geometry indeed represents the minimum energy conformer (for a non-TS species)

    • whether the barrier height is reasonable

  4. Based on requested parameters to preserve:

    • whether specified atom distances to preserve criteria aren’t violated

  • label (str) – The species label.

  • pivots (list) – The rotor pivots.

  • energies (list) – The scan energies in kJ/mol.

  • scan_res (float, optional) – The scan resolution in degrees.

  • used_methods (list, optional) – Troubleshooting methods already tried out.

  • log_file (str, optional) – The path to the output file.

  • species (ARCSpecies, optional) – The ARCSpecies this scan is related to.

  • preserve_params (list, optional) – Entries are length 2 lists of atom indices (1-indexed) between which the distance as well as a torsion dihedral angle with these atoms as its pivots must be preserved throughout the scan to a tolerance.

  • trajectory (list, optional) – Entries are Cartesian coordinates along the scan trajectory.

  • original_xyz (dict, optional) – The optimized coordinated for the species.

Returns: Tuple[bool, str, str, dict]
  • Whether to invalidate this rotor, True to invalidate.

  • Reason for invalidating this rotor.

  • Error or warning message.

  • Troubleshooting methods to apply, including conformational changes.

arc.job.trsh.trsh_conformer_isomorphism(software: str, ess_trsh_methods: list = None) → str[source]

Troubleshoot conformer optimization for a species that failed isomorphic test in determine_most_stable_conformer by specifying a “good” level of theory.

  • software (str) – The ESS used.

  • ess_trsh_methods (list, optional) – The troubleshooting methods tried for this job.


TrshError – If the requested ess_trsh_methods is not supported.

Returns: str

The level of theory to troubleshoot at.

arc.job.trsh.trsh_ess_job(label: str, level_of_theory: Union[arc.level.Level, dict, str], server: str, job_status: dict, job_type: str, software: str, fine: bool, memory_gb: float, num_heavy_atoms: int, cpu_cores: int, ess_trsh_methods: list, available_ess: list = None, is_h: bool = False) → tuple[source]

Troubleshoot issues related to the electronic structure software, such as convergence.

  • label (str) – The species label.

  • level_of_theory (Union[Level, dict, str]) – The original level of theory dictionary of the problematic job.

  • server (str) – The server used for this job.

  • job_status (dict) – The ESS job status dictionary with standardized error keywords as generated using the determine_ess_status function.

  • job_type (str) – The original job type.

  • software (str) – The ESS software.

  • fine (bool) – Whether the job used an ultrafine grid, True if it did.

  • memory_gb (float) – The memory in GB used for the job.

  • num_heavy_atoms (int) – Number of heavy atoms in a molecule.

  • cpu_cores (int) – The total number of cpu cores requested for a job.

  • ess_trsh_methods (list) – The troubleshooting methods tried for this job.

  • available_ess (list, optional) – Entries are string representations of available ESS.

  • is_h (bool) – Whether the species is a hydrogen atom (or its isotope). e.g., H, D, T.

Returns: tuple
  • output_errors (list): Errors to report.

  • ess_trsh_methods (list): The updated troubleshooting methods tried for this job.

  • remove_checkfile (bool): Whether to remove the checkfile from the job, True to remove.

  • level_of_theory (Level): The new level of theory dictionary to use.

  • software (str, optional): The new ESS software to use.

  • job_type (str): The new job type to use.

  • fine (bool): whether the new job should use a fine grid, True if it should.

  • trsh_keyword (str): The troubleshooting keyword to use.

  • memory (float): The new memory in GB to use for the job.

  • shift (str): The shift to use (only in Molpro).

  • cpus (int): The total number of cpu cores requested for a job.

  • couldnt_trsh (bool): Whether a troubleshooting solution was found. True if it was not found.

arc.job.trsh.trsh_job_on_server(server: str, job_name: str, job_id: Union[int, str], job_server_status: str, remote_path: str, server_nodes: list = None)[source]

Troubleshoot server errors.

  • server (str) – The server name.

  • job_name (str) – The job’s name (e.g., ‘opt_a103’).

  • job_id (int, str) – The job’s ID on the server.

  • job_server_status (str) – The job server status (either ‘initializing’, ‘running’, ‘errored’, or ‘done’).

  • remote_path (str) – The remote path to the job folder.

  • server_nodes (list, optional) – The nodes already tried on this server for this jobs.

Returns: Tuple[str, bool]
  • The new node on the server (or None).

  • Whether to re-run the job, True to rerun.

arc.job.trsh.trsh_negative_freq(label: str, log_file: str, neg_freqs_trshed: list = None, job_types: list = None)[source]

Troubleshooting cases where non-TS species have negative frequencies. We take +/-1.1 displacements, generating several new initial geometries.

  • label (str) – The species label.

  • log_file (str) – The frequency job log file.

  • neg_freqs_trshed (list, optional) – A list of negative frequencies the species was troubleshooted for.

  • job_types (list, optional) – The job types used for ARC, e.g., [‘opt’, ‘rotors’].

Returns: Tuple[list, list, list, list]
  • The current troubleshooted negative frequencies.

  • The new conformers to try optimizing.

  • Errors to report.

  • Warnings to report.


TrshError – If a negative frequency could not be determined.

arc.job.trsh.trsh_scan_job(label: str, scan_res: Union[int, float], scan: list, scan_list: list, methods: dict, log_file: Optional[str] = None) → Tuple[str, int][source]

Troubleshooting rotor scans. Using the following methods:

  1. freeze specific internal coordinates identified by scan_quality_check()

  2. freeze all torsions other than the rotor to be scanned

  3. increasing the scan resolution

  • label (str) – The species label.

  • scan_res (int or float) – The scan resolution in degrees.

  • scan (list) – The four atom indices representing the torsion to be troubleshooted.

  • scan_list (list) – Entries are the four-atom scan lists (1-indexed) of all torsions (without duplicate pivots) in this species.

  • methods (dict) –

    The troubleshooting method/s to try. Example:

    {'inc_res': None,
     'freeze': 'all' or [[1, 2, 3, 4], ...]}

  • log_file (str, optional) – The related output file path.

  • TrshError

    1. scan is not included in the scan_list 2. Freeze method includes an invalid internal coordinates. 3. Freeze method does not provide any solution.

  • InputError – Invalid methods input.

Returns: Tuple[str, int]
  • The scan troubleshooting keywords to be appended to the Gaussian input file.

  • The new scan resolution in degrees.

arc.job.trsh.trsh_special_rotor(special_rotor: list, problematic_ic: list, special_type: str = 'scan') → list[source]

Troubleshoot special rotor cases given all problematic torsional internal coordinates. Special rotors include rotor to be scanned and rotor already frozen. For example: If scan = [1, 2, 3, 4], scan_quality_check() might find [1, 2, 3, 5] problematic. However, we cannot simply freeze [1, 2, 3, 5] which definitely makes the scan failed. trsh_special_rotor() helps figure out the internal coordinates we need to actually freeze to troubleshoot the scan.

  • special_rotor (list) – A list of four atoms indicating the special torsion

  • problematic_ic (list) – A list of torsions identified as problematic by check_scan_quality. This list will be pruned.

  • special_type – Indicate the type of the special rotor. Either scan for the rotor to be scanned or frozen for the rotor were frozen in the previous job

Returns: list

A list of internal coordinates to be frozen