arc.job.trsh

The ARC troubleshooting (“trsh”) module

arc.job.trsh.determine_ess_status(output_path: str, species_label: str, job_type: str, job_log: Optional[str] = None, software: Optional[str] = None) → Tuple[str, List[str], str, str][source]

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

Parameters:

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

  • job_log (str, optional) – The path to the server job log file (not the ESS output file) or its content.

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

Returns: Tuple[str, List[str], 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.determine_job_log_memory_issues(job_log: Optional[str] = None) → Tuple[List[str], str, str][source]

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

Parameters:

job_log (str, optional) – The path to the server job log file (not the ESS output file) or its content.

Returns: Tuple[List[str], str, str]

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

Parameters:

  • 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: Optional[list] = None) → Optional[str][source]

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

Parameters:

  • software (str) – The ESS used.

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

Raises:

TrshError – If the requested ess_trsh_methods is not supported.

Returns: Optional[str]

The level of theory to troubleshoot at.

arc.job.trsh.trsh_ess_job(label: str, level_of_theory: Union[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, is_h: bool = False) → tuple[source]

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

Parameters:

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

  • 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: Optional[list] = None)[source]

Troubleshoot server errors.

Parameters:

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

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_job_queue(server: str, job_name: str, max_time: int = 24, attempted_queues: Optional[list] = None) → Tuple[dict, bool][source]
A function to troubleshoot job queue issues. This function will attempt to determine if the user has provided a queue that provides more time than the walltime failed queue.

If not, it will attempt to determine if there are any other queues available on the server that provide more time than the walltime failed queue.

Parameters:

  • server (str) – Name of the server

  • job_name (str) – Name of the job

  • max_time (int, optional) – The max time that the current queue that the job failed on provied. Defaults to 24, measured in hours.

  • attempted_queues (list, optional) – Any queues that have already been attempted to run the job on. Defaults to None.

Returns:

A dictionary of the available queues and a boolean indicating if the function was successful.

Return type:

Tuple[dict, bool]

arc.job.trsh.trsh_keyword_cartesian(job_status, ess_trsh_methods, job_type, trsh_keyword: list, couldnt_trsh: bool) → Tuple[List, List, bool][source]

Check if the job requires change of cartesian coordinate

arc.job.trsh.trsh_keyword_checkfile(job_status, ess_trsh_methods, couldnt_trsh) → Tuple[bool, List, bool][source]

Check if the job requires removal of checkfile

arc.job.trsh.trsh_keyword_intaccuracy(ess_trsh_methods, trsh_keyword, couldnt_trsh) → Tuple[List, List, bool][source]

Check if the job requires change of 2 electron integral accuracy

arc.job.trsh.trsh_keyword_nosymm(job_status, ess_trsh_methods, trsh_keyword, couldnt_trsh) → Tuple[List, List, bool][source]

Check if the job requires change of nosymm

arc.job.trsh.trsh_keyword_scf(job_status, ess_trsh_methods, trsh_keyword, couldnt_trsh) → Tuple[List, List, bool][source]

Check if the job requires change of scf

arc.job.trsh.trsh_keyword_unconverged(job_status, ess_trsh_methods, trsh_keyword, couldnt_trsh, fine) → Tuple[List, List, bool, bool][source]

Check if the job requires change of scf

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

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

Parameters:

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

Raises:

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

Parameters:

  • label (str) – The species label.

  • scan_res (int, 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.

Raises:

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

Parameters:

  • 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