arc.common

This module contains functions which are shared across multiple ARC modules. As such, it should not import any other ARC module (specifically ones that use the logger defined here) to avoid circular imports.

VERSION is the full ARC version, using semantic versioning.

arc.common.almost_equal_coords(xyz1: dict, xyz2: dict, rtol: float = 1e-05, atol: float = 1e-08) → bool[source]

A helper function for checking whether two xyz’s are almost equal.

Parameters
  • xyz1 (dict) – Cartesian coordinates.

  • xyz2 (dict) – Cartesian coordinates.

  • rtol (float, optional) – The relative tolerance parameter.

  • atol (float, optional) – The absolute tolerance parameter.

Returns: bool

True if they are almost equal, False otherwise.

arc.common.almost_equal_coords_lists(xyz1: dict, xyz2: dict, rtol: float = 1e-05, atol: float = 1e-08) → bool[source]

A helper function for checking two lists of xyz’s has at least one entry in each that is almost equal. Useful for comparing xyz’s in unit tests.

Parameters
  • xyz1 (list, dict) – Either a dict-format xyz, or a list of them.

  • xyz2 (list, dict) – Either a dict-format xyz, or a list of them.

  • rtol (float, optional) – The relative tolerance parameter.

  • atol (float, optional) – The absolute tolerance parameter.

Returns: bool

Whether at least one entry in each input xyz’s is almost equal to an entry in the other xyz.

arc.common.almost_equal_lists(iter1: Union[list, tuple, numpy.ndarray], iter2: Union[list, tuple, numpy.ndarray], rtol: float = 1e-05, atol: float = 1e-08) → bool[source]

A helper function for checking whether two iterables are almost equal.

Parameters
  • iter1 (list, tuple, np.array) – An iterable.

  • iter2 (list, tuple, np.array) – An iterable.

  • rtol (float, optional) – The relative tolerance parameter.

  • atol (float, optional) – The absolute tolerance parameter.

Returns: bool

True if they are almost equal, False otherwise.

arc.common.check_ess_settings(ess_settings: Optional[dict] = None) → dict[source]

A helper function to convert servers in the ess_settings dict to lists Assists in troubleshooting job and trying a different server Also check ESS and servers.

Parameters

ess_settings (dict, optional) – ARC’s ESS settings dictionary.

Returns: dict

An updated ARC ESS dictionary.

arc.common.check_torsion_change(torsions: pandas.core.frame.DataFrame, index_1: Union[int, str], index_2: Union[int, str], threshold: Union[float, int] = 20.0, delta: Union[float, int] = 0.0) → pandas.core.frame.DataFrame[source]

Compare two sets of torsions (in DataFrame) and check if any entry has a difference larger than threshold. The output is a DataFrame consisting of True/False, indicating which torsions changed significantly.

Parameters
  • torsions (pd.DataFrame) – A DataFrame consisting of multiple sets of torsions.

  • index_1 (Union[int, str]) – The index of the first conformer.

  • index_2 (Union[int, str]) – The index of the second conformer.

  • threshold (Union[float, int]) – The threshold used to determine the difference significance.

  • delta (Union[float, int]) – A known difference between torsion pairs, delta = tor[index_1] - tor[index_2]. E.g.,for the torsions to be scanned, the differences are equal to the scan resolution.

Returns: pd.DataFrame

A DataFrame consisting of True/False, indicating which torsions changed significantly. True for significant change.

arc.common.colliding_atoms(xyz: dict, threshold: float = 0.55) → bool[source]

Check whether atoms are too close to each other. A default threshold of 55% the covalent radii of two atoms is used. For example: - C-O collide at 55% * 1.42 A = 0.781 A - N-N collide at 55% * 1.42 A = 0.781 A - C-N collide at 55% * 1.47 A = 0.808 A - C-H collide at 55% * 1.07 A = 0.588 A

Parameters
  • xyz (dict) – The Cartesian coordinates.

  • threshold (float, optional) – The collision threshold to use.

Returns: bool

True if they are colliding, False otherwise.

arc.common.convert_list_index_0_to_1(_list: Union[list, tuple], direction: int = 1) → Union[list, tuple][source]

Convert a list from 0-indexed to 1-indexed, or vice versa. Ensures positive values in the resulting list.

Parameters
  • _list (list) – The list to be converted.

  • direction (int, optional) – Either 1 or -1 to convert 0-indexed to 1-indexed or vice versa, respectively.

Raises

ValueError – If the new list contains negative values.

Returns

The converted indices.

Return type

Union[list, tuple]

arc.common.determine_ess(log_file: str) → str[source]

Determine the ESS to which the log file belongs.

Parameters

log_file (str) – The ESS log file path.

Returns: str

The ESS log class from Arkane.

arc.common.determine_symmetry(xyz: dict) → Tuple[int, int][source]

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

Parameters

xyz (dict) – The 3D coordinates.

Returns: Tuple[int, int]
  • The external symmetry number.

  • 1 if no chiral centers are present, 2 if chiral centers are present.

arc.common.determine_top_group_indices(mol, atom1, atom2, index=1) → Tuple[list, bool][source]

Determine the indices of a “top group” in a molecule. The top is defined as all atoms connected to atom2, including atom2, excluding the direction of atom1. Two atom_list_to_explore are used so the list the loop iterates through isn’t changed within the loop.

Parameters
  • mol (Molecule) – The Molecule object to explore.

  • atom1 (Atom) – The pivotal atom in mol.

  • atom2 (Atom) – The beginning of the top relative to atom1 in mol.

  • index (bool, optional) – Whether to return 1-index or 0-index conventions. 1 for 1-index.

Returns: Tuple[list, bool]
  • The indices of the atoms in the top (either 0-index or 1-index, as requested).

  • Whether the top has heavy atoms (is not just a hydrogen atom). True if it has heavy atoms.

arc.common.estimate_orca_mem_cpu_requirement(num_heavy_atoms: int, server: str = '', consider_server_limits: bool = False) → Tuple[int, float][source]

Estimates memory and cpu requirements for an Orca job.

Parameters
  • num_heavy_atoms (int) – The number of heavy atoms in the species.

  • server (str) – The name of the server where Orca runs.

  • consider_server_limits (bool) – Try to give realistic estimations.

Returns: Tuple[int, float]:
  • The amount of total memory (MB)

  • The number of cpu cores required for the Orca job for a given species.

arc.common.extremum_list(lst: list, return_min: bool = True) → Optional[int][source]

A helper function for finding the extremum (either minimum or maximum) of a list of numbers (int/float) where some of the entries might be None.

Parameters
  • lst (list) – The list.

  • return_min (bool, optional) – Whether to return the minimum or the maximum. True for minimum, False for maximum, True by default.

Returns: int

The entry with the minimal/maximal value.

arc.common.get_angle_in_180_range(angle: float, round_to: Optional[int] = 2) → float[source]

Get the corresponding angle in the -180 to +180 degree range.

Parameters
  • angle (float) – An angle in degrees.

  • round_to (int, optional) – The number of decimal figures to round the result to. None to not round. Default: 2.

Returns

The corresponding angle in the -180 to +180 degree range.

Return type

float

arc.common.get_atom_radius(symbol: str) → float[source]

Get the atom covalent radius of an atom in Angstroms.

Parameters

symbol (str) – The atomic symbol.

Raises

TypeError – If symbol is of wrong type.

Returns: float

The atomic covalent radius (None if not found).

arc.common.get_close_tuple(key_1: Tuple[Union[float, str], ], keys: List[Tuple[Union[float, str], ]], tolerance: float = 0.05, raise_error: bool = False) → Optional[Tuple[Union[float, str], ]][source]

Get a key from a list of keys close in value to the given key. Even if just one of the items in the key has a close match, use the close value.

Parameters
  • key_1 (Tuple[Union[float, str], Union[float, str]]) – The key used for the search.

  • keys (List[Tuple[Union[float, str], Union[float, str]]]) – The list of keys to search within.

  • tolerance (float, optional) – The tolerance within which keys are determined to be close.

  • raise_error (bool, optional) – Whether to raise a ValueError if a close key wasn’t found.

Raises
  • ValueError – If a key in keys has a different length than key_1.

  • ValueError – If a close key was not found and raise_error is True.

Returns

A key from the keys list close in value to the given key.

Return type

Optional[Tuple[Union[float, str], ..]]

arc.common.get_git_branch(path: Optional[str] = None) → str[source]

Get the git branch to be logged.

Parameters

path (str, optional) – The path to check.

Returns: str

The git branch name.

arc.common.get_git_commit(path: Optional[str] = None) → Tuple[str, str][source]

Get the recent git commit to be logged.

Note

Returns empty strings if hash and date cannot be determined.

Parameters

path (str, optional) – The path to check.

Returns: tuple

The git HEAD commit hash and the git HEAD commit date, each as a string.

arc.common.get_logger()[source]

Get the ARC logger (avoid having multiple entries of the logger).

arc.common.get_number_with_ordinal_indicator(number: int) → str[source]

Returns the number as a string with the ordinal indicator.

Parameters

number (int) – An integer for which the ordinal indicator will be determined.

Returns: str

The number with the respective ordinal indicator.

arc.common.get_ordered_intersection_of_two_lists(l1: list, l2: list, order_by_first_list: Optional[bool] = True, return_unique: Optional[bool] = True) → list[source]

Find the intersection of two lists by order.

Examples

  • l1 = [1, 2, 3, 3, 5, 6], l2 = [6, 3, 5, 5, 1], order_by_first_list = True, return_unique = True -> [1, 3, 5, 6] unique values in the intersection of l1 and l2, order following value’s first appearance in l1

  • l1 = [1, 2, 3, 3, 5, 6], l2 = [6, 3, 5, 5, 1], order_by_first_list = True, return_unique = False -> [1, 3, 3, 5, 6] unique values in the intersection of l1 and l2, order following value’s first appearance in l1

  • l1 = [1, 2, 3, 3, 5, 6], l2 = [6, 3, 5, 5, 1], order_by_first_list = False, return_unique = True -> [6, 3, 5, 1] unique values in the intersection of l1 and l2, order following value’s first appearance in l2

  • l1 = [1, 2, 3, 3, 5, 6], l2 = [6, 3, 5, 5, 1], order_by_first_list = False, return_unique = False -> [6, 3, 5, 5, 1] unique values in the intersection of l1 and l2, order following value’s first appearance in l2

Parameters
  • l1 (list) – The first list.

  • l2 (list) – The second list.

  • (bool (order_by_first_list) – Whether to order the output list using the order of the values in the first list.

  • optional – Whether to order the output list using the order of the values in the first list.

  • return_unique (bool, optional) – Whether to return only unique values in the intersection of two lists.

Returns: list

An ordered list of the intersection of two input lists.

arc.common.get_ordinal_indicator(number: int) → str[source]

Returns the ordinal indicator for an integer.

Parameters

number (int) – An integer for which the ordinal indicator will be determined.

Returns: str

The integer’s ordinal indicator.

arc.common.get_single_bond_length(symbol1: str, symbol2: str) → float[source]

Get the an approximate for a single bond length between two elements.

Parameters
  • symbol1 (str) – Symbol 1.

  • symbol2 (str) – Symbol 2.

Returns: float

The estimated single bond length in Angstrom.

arc.common.globalize_path(string: str, project_directory: str) → str[source]

Rebase an absolute file path on the current project path. Useful when restarting an ARC project in a different folder or on a different machine.

Parameters
  • string (str) – A string containing a path to rebase.

  • project_directory (str) – The current project directory to rebase upon.

Returns: str

A string with the rebased path.

arc.common.globalize_paths(file_path: str, project_directory: str) → str[source]

Rebase all file paths in the contents of the given file on the current project path. Useful when restarting an ARC project in a different folder or on a different machine.

Parameters
  • file_path (str) – A path to the file to check. The contents of this file will be changed and saved as a different file.

  • project_directory (str) – The current project directory to rebase upon.

Returns: str

A path to the respective file with rebased absolute file paths.

arc.common.initialize_job_types(job_types: dict, specific_job_type: str = '') → dict[source]

A helper function for initializing job_types. Returns the comprehensive (default values for missing job types) job types for ARC.

Parameters
  • job_types (dict) – Keys are job types, values are booleans of whether or not to consider this job type.

  • specific_job_type (str) – Specific job type to execute. Legal strings are job types (keys of job_types dict).

Returns: dict

An updated (comprehensive) job type dictionary.

arc.common.initialize_log(log_file: str, project: str, project_directory: Optional[str] = None, verbose: int = 20) → None[source]

Set up a logger for ARC.

Parameters
  • log_file (str) – The log file name.

  • project (str) – A name for the project.

  • project_directory (str, optional) – The path to the project directory.

  • verbose (int, optional) – Specify the amount of log text seen.

arc.common.is_notebook() → bool[source]

Check whether ARC was called from an IPython notebook.

Returns: bool

True if ARC was called from a notebook, False otherwise.

arc.common.is_same_pivot(torsion1: Union[list, str], torsion2: Union[list, str]) → Optional[bool][source]

Check if two torsions have the same pivots.

Parameters
  • torsion1 (Union[list, str]) – The four atom indices representing the first torsion.

  • (Union (torsion2) – [list, str]): The four atom indices representing the second torsion.

Returns: Optional[bool]

True if two torsions share the same pivots.

arc.common.is_same_sequence_sublist(child_list: list, parent_list: list) → bool[source]

Check if the parent list has a sublist which is identical to the child list including the sequence. .. rubric:: Examples

  • child_list = [1,2,3], parent_list=[5,1,2,3,9] -> True

  • child_list = [1,2,3], parent_list=[5,6,1,3,9] -> False

Parameters
  • child_list (list) – The child list (the pattern to search in the parent list).

  • parent_list (list) – The parent list.

Returns: bool

True if the sublist is in the parent list.

arc.common.is_str_float(value: Optional[str]) → bool[source]

Check whether a string can be converted to a floating number.

Parameters

value (str) – The string to check.

Returns: bool

True if it can, False otherwise.

arc.common.is_str_int(value: Optional[str]) → bool[source]

Check whether a string can be converted to an integer.

Parameters

value (str) – The string to check.

Returns: bool

True if it can, False otherwise.

arc.common.key_by_val(dictionary: dict, value: Any) → Any[source]

A helper function for getting a key from a dictionary corresponding to a certain value. Does not check for value unicity.

Parameters
  • dictionary (dict) – The dictionary.

  • value – The value.

Raises

ValueError – If the value could not be found in the dictionary.

Returns: Any

The key.

Output a footer for the log.

Parameters
  • execution_time (str) – The overall execution time for ARC.

  • level – The desired logging level.

arc.common.log_header(project: str, level: int = 20) → None[source]

Output a header containing identifying information about ARC to the log.

Parameters
  • project (str) – The ARC project name to be logged in the header.

  • level – The desired logging level.

arc.common.read_yaml_file(path: str, project_directory: Optional[str] = None) → Union[dict, list][source]

Read a YAML file (usually an input / restart file, but also conformers file) and return the parameters as python variables.

Parameters
  • path (str) – The YAML file path to read.

  • project_directory (str, optional) – The current project directory to rebase upon.

Returns: Union[dict, list]

The content read from the file.

arc.common.save_yaml_file(path: str, content: Union[list, dict]) → None[source]

Save a YAML file (usually an input / restart file, but also conformers file).

Parameters
  • path (str) – The YAML file path to save.

  • content (list, dict) – The content to save.

arc.common.sort_two_lists_by_the_first(list1: List[Optional[Union[float, int]]], list2: List[Optional[Union[float, int]]]) → Tuple[List[Union[float, int]], List[Union[float, int]]][source]

Sort two lists in increasing order by the values of the first list. Ignoring None entries from list1 and their respective entries in list2. The function was written in this format rather the more pytonic zip(*sorted(zip(list1, list2))) style to accommodate for dictionaries as entries of list2, otherwise a TypeError: '<' not supported between instances of 'dict' and 'dict' error is raised.

Parameters
  • list1 (list, tuple) – Entries are floats or ints (could also be None).

  • list2 (list, tuple) – Entries could be anything.

Raises

InputError – If types are wrong, or lists are not the same length.

Returns: Tuple[list, list]
  • Sorted values from list1, ignoring None entries.

  • Respective entries from list2.

arc.common.string_representer(dumper, data)[source]

Add a custom string representer to use block literals for multiline strings.

arc.common.time_lapse(t0) → str[source]

A helper function returning the elapsed time since t0.

Parameters

t0 (time.pyi) – The initial time the count starts from.

Returns: str

A “D HH:MM:SS” formatted time difference between now and t0.

arc.common.timedelta_from_str(time_str: str)[source]

Get a datetime.timedelta object from its str() representation

Parameters

time_str (str) – The string representation of a datetime.timedelta object.

Returns

The corresponding timedelta object.

Return type

datetime.timedelta

arc.common.to_yaml(py_content: Union[list, dict]) → str[source]

Convert a Python list or dictionary to a YAML string format.

Parameters

py_content (list, dict) – The Python content to save.

Returns: str

The corresponding YAML representation.

arc.common.torsions_to_scans(descriptor: Optional[List[List[int]]], direction: int = 1) → Optional[List[List[int]]][source]

Convert torsions to scans or vice versa. In ARC we define a torsion as a list of four atoms with 0-indices. We define a scan as a list of four atoms with 1-indices. This function converts one format to the other.

Parameters
  • descriptor (list) – The torsions or scans list.

  • direction (int, optional) – 1: Convert torsions to scans; -1: Convert scans to torsions.

Returns

The converted indices.

Return type

Optional[List[List[int]]]