arc.species.conformers

A module for (non-TS) species conformer generation

Note

variables that contain atom indices such as torsions and tops are 1-indexed, while atoms in Molecules are 0-indexed.

conformers is a list of dictionaries, each with the following keys:

{'xyz': <dict>,
 'index': <int>,
 'FF energy': <float>,
 'source': <str>,
 'torsion_dihedrals': {<torsion tuple 0>: angle 0,
                       <torsion tuple 1>: angle 1,
 }

Module workflow:

generate_conformers
    generate_force_field_conformers
        get_force_field_energies, rdkit_force_field or openbabel_force_field_on_rdkit_conformers,
        determine_dihedrals
    deduce_new_conformers
        get_torsion_angles, determine_torsion_symmetry, determine_torsion_sampling_points,
        change_dihedrals_and_force_field_it
    get_lowest_confs
arc.species.conformers.change_dihedrals_and_force_field_it(label, mol, xyz, torsions, new_dihedrals, optimize=True, force_field='MMFF94s')[source]

Change dihedrals of specified torsions according to the new dihedrals specified, and get FF energies.

Example:

torsions = [(1, 2, 3, 4), (9, 4, 7, 1)]
new_dihedrals = [[90, 120], [90, 300], [180, 270], [30, 270]]

This will calculate the energy of the original conformer (defined using xyz). We iterate through new_dihedrals. The torsions are set accordingly and the energy and xyz of the newly generated conformer are kept. We assume that each list entry in new_dihedrals is of the length of the torsions list (2 in the example).

Parameters
  • label (str) – The species’ label.

  • mol (Molecule) – The RMG molecule with the connectivity information.

  • xyz (dict) – The base 3D geometry to be changed.

  • torsions (list) – Entries are torsion tuples for which the dihedral will be changed relative to xyz.

  • new_dihedrals (list) – Entries are same size lists of dihedral angles (floats) corresponding to the torsions.

  • optimize (bool, optional) – Whether to optimize the coordinates using FF. True to optimize.

  • force_field (str, optional) – The type of force field to use.

Returns

  • The conformer FF energies corresponding to the list of dihedrals.

  • The conformer xyz geometries corresponding to the list of dihedrals.

Return type

Tuple[list, list]

arc.species.conformers.check_special_non_rotor_cases(mol, top1, top2)[source]

Check whether one of the tops correspond to a special case which does not have a torsional mode. Checking for R-[C,N]#[N,[CH],[C]] groups, such as: in cyano groups (R-C#N`), C#C groups (R-C#CH or R-C#[C]), and azide groups: (R-N#N).

Parameters
  • mol (Molecule) – The RMG molecule.

  • top1 (list) – Entries are atom indices (1-indexed) on one side of the torsion, inc. one of the pivotal atoms.

  • top2 (list) – Entries are atom indices (1-indexed) on the other side of the torsion, inc. the other pivotal atom.

Returns

True if this is indeed a special case which should not be treated as a torsional mode.

Return type

bool

arc.species.conformers.chirality_dict_to_tuple(chirality_dict)[source]

A helper function for using the chirality dictionary of a conformer as a key in the enantiomers_dict by converting it to a tuple deterministically.

Parameters

chirality_dict (dict) – The chirality dictionary of a conformer.

Raises

ConformerError – If the chirality values are wrong.

Returns

A deterministic tuple representation of the chirality dictionary.

Return type

tuple

arc.species.conformers.conformers_combinations_by_lowest_conformer(label, mol, base_xyz, multiple_tors, multiple_sampling_points, len_conformers=- 1, force_field='MMFF94s', max_combination_iterations=25, torsion_angles=None, multiple_sampling_points_dict=None, wells_dict=None, de_threshold=None, plot_path=False, symmetries=None)[source]

Iteratively modify dihedrals in the lowest conformer (each iteration deduces a new lowest conformer), until convergence.

Parameters
  • label (str) – The species’ label.

  • mol (Molecule) – The RMG molecule with the connectivity information.

  • base_xyz (dict) – The base 3D geometry to be changed.

  • multiple_tors (list) – Entries are torsion tuples of non-symmetric torsions.

  • multiple_sampling_points (list) – Entries are lists of dihedral angles (sampling points), respectively correspond to torsions in multiple_tors.

  • len_conformers (int, optional) – The length of the existing conformers list (for consecutive numbering).

  • de_threshold (float, optional) – An energy threshold (in kJ/mol) above which wells in a torsion will not be considered.

  • force_field (str, optional) – The type of force field to use.

  • max_combination_iterations (int, optional) – The max num of times to iteratively search for the lowest conformer.

  • torsion_angles (dict, optional) – The torsion angles. Keys are torsion tuples, values are lists of all corresponding angles from conformers.

  • multiple_sampling_points_dict (dict, optional) – Keys are torsion tuples, values are respective sampling points.

  • wells_dict (dict, optional) – Keys are torsion tuples, values are well dictionaries.

  • plot_path (str, optional) – A folder path in which the plot will be saved. If None, the plot will not be shown (nor saved).

  • symmetries (dict, optional) – Keys are tuples scan indices (1-indexed), values are internal rotation symmetry numbers (sigma).

Returns

New conformer combinations, entries are conformer dictionaries.

Return type

list

arc.species.conformers.deduce_new_conformers(label, conformers, torsions, tops, mol_list, smeared_scan_res=None, plot_path=None, combination_threshold=1000, force_field='MMFF94s', max_combination_iterations=25, diastereomers=None, de_threshold=None)[source]

By knowing the existing torsion wells, get the geometries of all important conformers. Validate that atoms don’t collide in the generated conformers (don’t consider ones where they do).

Parameters
  • label (str) – The species’ label.

  • conformers (list) – Entries are conformer dictionaries.

  • torsions (list) – A list of all possible torsion angles in the molecule, each torsion angles list is sorted.

  • tops (list) – A list of tops corresponding to torsions.

  • mol_list (list) – A list of RMG Molecule objects.

  • smeared_scan_res (float, optional) – The resolution (in degrees) for scanning smeared wells.

  • plot_path (str, optional) – A folder path in which the plot will be saved. If None, the plot will not be shown (nor saved).

  • combination_threshold (int, optional) – A threshold below which all combinations will be generated.

  • force_field (str, optional) – The type of force field to use.

  • max_combination_iterations (int, optional) – The max num of times to iteratively search for the lowest conformer.

  • diastereomers (list, optional) – Entries are xyz’s in a dictionary format or conformer structures representing specific diastereomers to keep.

  • de_threshold (float, optional) – An energy threshold (in kJ/mol) above which wells in a torsion will not be considered.

Returns

  • The deduced conformers.

  • Keys are torsion tuples.

Return type

Tuple[list, dict]

arc.species.conformers.determine_chirality(conformers, label, mol, force=False)[source]

Determines the Cahn–Ingold–Prelog (CIP) chirality (R or S) of atoms in the conformer, as well as the CIP chirality of double bonds (E or Z).

Parameters
  • conformers (list) – Entries are conformer dictionaries.

  • label (str) – The species’ label.

  • mol (RMG Molecule or RDKit RDMol) – The molecule object with connectivity and bond order information.

  • force (bool, optional) – Whether to override data, True to override, default is False.

Returns

Conformer dictionaries with updated with ‘chirality’. conformer['chirality'] is a dictionary.

Keys are either a 1-length tuple of atom indices (for chiral atom centers) or a 2-length tuple of atom indices (for chiral double bonds), values are either ‘R’ or ‘S’ for chiral atom centers (or ‘NR’ or ‘NS’ for chiral nitrogen centers), or ‘E’ or ‘Z’ for chiral double bonds. All atom indices are 0-indexed.

Return type

list

arc.species.conformers.determine_dihedrals(conformers, torsions)[source]

For each conformer in conformers determine the respective dihedrals.

Parameters
  • conformers (list) – Entries are conformer dictionaries.

  • torsions (list) – All possible torsions in the molecule.

Returns

Entries are conformer dictionaries.

Return type

list

arc.species.conformers.determine_number_of_conformers_to_generate(label: str, heavy_atoms: int, torsion_num: int, mol: Optional[rmgpy.molecule.molecule.Molecule] = None, xyz: Optional[dict] = None, minimalist: bool = False) → Tuple[int, int][source]

Determine the number of conformers to generate using molecular mechanics.

Parameters
  • label (str) – The species’ label.

  • heavy_atoms (int) – The number of heavy atoms in the molecule.

  • torsion_num (int) – The number of potential torsions in the molecule.

  • mol (Molecule, optional) – The RMG Molecule object.

  • xyz (dict, optional) – The xyz coordinates.

  • minimalist (bool, optional) – Whether to return a small number of conformers, useful when this is just a guess before fitting a force field. True to be minimalistic.

Raises

ConformerError – If the number of conformers to generate cannot be determined.

Returns

  • The number of conformers to generate.

  • The number of chiral centers.

Return type

Tuple[int, int]

arc.species.conformers.determine_rotors(mol_list)[source]

Determine possible unique rotors in the species to be treated as hindered rotors.

Parameters

mol_list (list) – Localized structures (Molecule objects) by which all rotors will be determined.

Returns

  • A list of indices of scan pivots.

  • A list of indices of top atoms (including one of the pivotal atoms) corresponding to the torsions.

Return type

Tuple[list, list]

arc.species.conformers.determine_smallest_atom_index_in_scan(atom1: rmgpy.molecule.molecule.Atom, atom2: rmgpy.molecule.molecule.Atom, mol: rmgpy.molecule.molecule.Molecule) → int[source]

Determine the smallest atom index in mol connected to atom1 which is not atom2. Returns a heavy atom if available, otherwise a hydrogen atom. Useful for deterministically determining the indices of four atom in a scan. This function assumes there ARE additional atoms connected to atom1, and that atom2 is not a hydrogen atom.

Parameters
  • atom1 (Atom) – The atom who’s neighbors will be searched.

  • atom2 (Atom) – An atom connected to atom1 to exclude (a pivotal atom).

  • mol (Molecule) – The molecule to process.

Returns

The smallest atom index (1-indexed) connected to atom1 which is not atom2.

Return type

int

arc.species.conformers.determine_torsion_sampling_points(label, torsion_angles, smeared_scan_res=None, symmetry=1)[source]

Determine how many points to consider in each well of a torsion for conformer combinations.

Parameters
  • label (str) – The species’ label.

  • torsion_angles (list) – Well angles in the torsion.

  • smeared_scan_res (float, optional) – The resolution (in degrees) for scanning smeared wells.

  • symmetry (int, optional) – The torsion symmetry number.

Returns

  • Sampling points for the torsion.

  • Each entry is a well dictionary with the keys start_idx, end_idx, start_angle, end_angle, angles.

Return type

Tuple[list, list]

arc.species.conformers.determine_torsion_symmetry(label, top1, mol_list, torsion_scan)[source]

Check whether a torsion is symmetric. If a torsion well is “well defined” and not smeared, it could be symmetric. Check the groups attached to the rotor pivots to determine whether it is indeed symmetric We don’t care about the actual rotor symmetry number here, since we plan to just use the first well (they’re all the same).

Parameters
  • label (str) – The species’ label.

  • top1 (list) – A list of atom indices on one side of the torsion, including the pivotal atom.

  • mol_list (list) – A list of molecules.

  • torsion_scan (list) – The angles corresponding to this torsion from all conformers.

Returns

The rotor symmetry number.

Return type

int

arc.species.conformers.determine_well_width_tolerance(mean_width)[source]

Determine the tolerance by which well widths are determined to be nearly equal.

Fitted to a polynomial trend line for the following data of (mean, tolerance) pairs:

(100, 0.11), (60, 0.13), (50, 0.15), (25, 0.25), (5, 0.50), (1, 0.59)
Parameters

mean_width (float) – The mean well width in degrees.

Returns

The tolerance.

Return type

float

arc.species.conformers.embed_rdkit(label, mol, num_confs=None, xyz=None)[source]

Generate unoptimized conformers in RDKit. If xyz is not given, random conformers will be generated.

Parameters
  • label (str) – The species’ label.

  • mol (RMG Molecule or RDKit RDMol) – The molecule object with connectivity and bond order information.

  • num_confs (int, optional) – The number of random 3D conformations to generate.

  • xyz (dict, optional) – The 3D coordinates.

Returns

An RDKIt molecule with embedded conformers.

Return type

RDMol

arc.species.conformers.find_internal_rotors(mol)[source]

Locates the sets of indices corresponding to every internal rotor (1-indexed).

Parameters

mol (Molecule) – The molecule for which rotors will be determined.

Returns

Entries are rotor dictionaries with the four-atom scan coordinates, the pivots, and the smallest top.

Return type

list

arc.species.conformers.generate_all_combinations(label, mol, base_xyz, multiple_tors, multiple_sampling_points, len_conformers=- 1, torsions=None, force_field='MMFF94s')[source]

Generate all combinations of torsion wells from a base conformer.

Parameters
  • label (str) – The species’ label.

  • mol (Molecule) – The RMG molecule with the connectivity information.

  • base_xyz (dict) – The base 3D geometry to be changed.

  • multiple_tors (list) – Entries are torsion tuples of non-symmetric torsions.

  • multiple_sampling_points (list) – Entries are lists of dihedral angles (sampling points), respectively correspond to torsions in multiple_tors.

  • len_conformers (int, optional) – The length of the existing conformers list (for consecutive numbering).

  • force_field (str, optional) – The type of force field to use.

  • torsions (list, optional) – A list of all possible torsions in the molecule. Will be determined if not given.

Returns

New conformer combinations, entries are conformer dictionaries.

Return type

list

arc.species.conformers.generate_conformer_combinations(label, mol, base_xyz, hypothetical_num_comb, multiple_tors, multiple_sampling_points, combination_threshold=1000, len_conformers=- 1, force_field='MMFF94s', max_combination_iterations=25, plot_path=None, torsion_angles=None, multiple_sampling_points_dict=None, wells_dict=None, de_threshold=None, symmetries=None)[source]

Call either conformers_combinations_by_lowest_conformer() or generate_all_combinations(), according to the hypothetical_num_comb.

Parameters
  • label (str) – The species’ label.

  • mol (Molecule) – The RMG molecule with the connectivity information.

  • base_xyz (dict) – The base 3D geometry to be changed.

  • hypothetical_num_comb (int) – The number of combinations that could be generated by changing dihedrals, considering symmetry but not considering atom collisions.

  • combination_threshold (int, optional) – A threshold below which all combinations will be generated.

  • multiple_tors (list) – Entries are torsion tuples of non-symmetric torsions.

  • multiple_sampling_points (list) – Entries are lists of dihedral angles (sampling points), respectively correspond to torsions in multiple_tors.

  • len_conformers (int, optional) – The length of the existing conformers list (for consecutive numbering).

  • de_threshold (float, optional) – An energy threshold (in kJ/mol) above which wells in a torsion will not be considered.

  • force_field (str, optional) – The type of force field to use.

  • max_combination_iterations (int, optional) – The max num of times to iteratively search for the lowest conformer.

  • torsion_angles (dict, optional) – The torsion angles. Keys are torsion tuples, values are lists of all corresponding angles from conformers.

  • multiple_sampling_points_dict (dict, optional) – Keys are torsion tuples, values are respective sampling points.

  • wells_dict (dict, optional) – Keys are torsion tuples, values are well dictionaries.

  • plot_path (str, optional) – A folder path in which the plot will be saved. If None, the plot will not be shown (nor saved).

  • symmetries (dict, optional) – Keys are tuples scan indices (1-indexed), values are internal rotation symmetry numbers (sigma).

Returns

New conformer combinations, entries are conformer dictionaries.

Return type

list

arc.species.conformers.generate_conformers(mol_list: Union[List[rmgpy.molecule.molecule.Molecule], rmgpy.molecule.molecule.Molecule], label, xyzs=None, torsions=None, tops=None, charge=0, multiplicity=None, num_confs_to_generate=None, n_confs=10, e_confs=5.0, de_threshold=None, smeared_scan_res=None, combination_threshold=None, force_field='MMFF94s', max_combination_iterations=None, diastereomers=None, return_all_conformers=False, plot_path=None, print_logs=True) → Optional[Union[list, Tuple[list, list]]][source]

Generate conformers for (non-TS) species starting from a list of RMG Molecules. (resonance structures are assumed to have already been generated and included in the molecule list)

Parameters
  • mol_list (Union[List[Molecule], Molecule]) – Molecule objects to consider (or Molecule, resonance structures will be generated).

  • label (str) – The species’ label.

  • xyzs (list) – A list of user guess xyzs that will also be taken into account, each in a dict format.

  • torsions (list, optional) – A list of all possible torsions in the molecule. Will be determined if not given.

  • tops (list, optional) – A list of tops corresponding to torsions. Will be determined if not given.

  • charge (int, optional) – The species charge. Used to perceive a molecule from xyz.

  • multiplicity (int, optional) – The species multiplicity. Used to perceive a molecule from xyz.

  • num_confs_to_generate (int, optional) – The number of conformers to generate (can be determined automatically)

  • n_confs (int, optional) – The number of conformers to return.

  • e_confs (float, optional) – The energy threshold in kJ/mol above the lowest energy conformer below which all (unique) generated conformers will be returned.

  • de_threshold (float, optional) – Energy threshold (in kJ/mol) above which wells will not be considered.

  • smeared_scan_res (float, optional) – The resolution (in degrees) for scanning smeared wells.

  • combination_threshold (int, optional) – A threshold below which all combinations will be generated.

  • force_field (str, optional) – The type of force field to use (MMFF94, MMFF94s, UFF, GAFF, fit). ‘fit’ will first run MMFF94, than fit a custom Amber FF to the species.

  • max_combination_iterations (int, optional) – The maximum number of times to iteratively search for the lowest conformer.

  • diastereomers (list, optional) – Entries are xyz’s in a dictionary format or conformer structures representing specific diastereomers to keep.

  • return_all_conformers (bool, optional) – Whether to return the full conformers list of conformer dictionaries In addition to the lowest conformers list. Tru to return it.

  • plot_path (str, optional) – A folder path in which the plot will be saved. If None, the plot will not be shown (nor saved).

  • print_logs (bool, optional) – Whether define a logger so logs are also printed to stdout. Useful when run outside of ARC. True to print.

Raises
  • ConformerError – If something goes wrong.

  • TypeError – If xyzs has entries of a wrong type.

Returns

Lowest conformers.

Return type

list

arc.species.conformers.generate_force_field_conformers(label, mol_list, torsion_num, charge, multiplicity, xyzs=None, num_confs=None, force_field='MMFF94s')[source]

Generate conformers using RDKit and OpenBabel and optimize them using a force field Also consider user guesses in xyzs.

Parameters
  • label (str) – The species’ label.

  • mol_list (list) – Entries are Molecule objects representing resonance structures of a chemical species.

  • xyzs (list, optional) – Entries are xyz coordinates in dict format, given as initial guesses.

  • torsion_num (int) – The number of torsions identified in the molecule.

  • charge (int) – The net charge of the species.

  • multiplicity (int) – The species spin multiplicity.

  • num_confs (int, optional) – The number of conformers to generate.

  • force_field (str, optional) – The type of force field to use.

Raises

ConformerError – If xyzs is given and it is not a list, or its entries are not strings.

Returns

Entries are conformer dictionaries.

Return type

list

arc.species.conformers.generate_monoatomic_conformer(symbol)[source]

Generate a conformer for a monoatomic species.

Parameters

symbol (str) – The atomic symbol.

Returns

The monoatomic conformer.

Return type

dict

arc.species.conformers.get_force_field_energies(label: str, mol: rmgpy.molecule.molecule.Molecule, num_confs: int = None, xyz: dict = None, force_field: str = 'MMFF94s', optimize: bool = True, try_ob: bool = True, suppress_warning: bool = False) → Tuple[list, list][source]

Determine force field energies using RDKit. If num_confs is given, random 3D geometries will be generated. If xyz is given, it will be directly used instead. The coordinates are returned in the order of atoms in mol.

Parameters
  • label (str) – The species’ label.

  • mol (Molecule) – The RMG molecule object with connectivity and bond order information.

  • num_confs (int, optional) – The number of random 3D conformations to generate.

  • xyz (dict, optional) – The 3D coordinates guess.

  • force_field (str, optional) – The type of force field to use.

  • optimize (bool, optional) – Whether to first optimize the conformer using FF. True to optimize.

  • try_ob (bool, optional) – Whether to try OpenBabel if RDKit fails. True to try, True by default.

  • suppress_warning (bool, optional) – Wheter to suppress warning of using OpenBabel. True to suppress, False by default.

Raises

ConformerError – If conformers could not be generated.

Returns

  • Entries are xyz coordinates, each in a dict format.

  • Entries are the FF energies (in kJ/mol).

Return type

Tuple[list, list]

arc.species.conformers.get_lowest_confs(label: str, confs: Union[dict, list], n: int = 10, e: float = 5.0, energy: str = 'FF energy') → list[source]

Get the most stable conformer.

Parameters
  • label (str) – The species’ label.

  • confs (dict, list) – Entries are either conformer dictionaries or a length two list of xyz coordinates and energy

  • n (int, optional) – Number of lowest conformers to return.

  • e (float, optional) – The energy threshold above the lowest energy conformer in kJ/mol below which all conformers will be returned.

  • energy (str, optional) – The energy attribute to search by. Currently only ‘FF energy’ is supported.

Raises

ConformerError – If n < 1, e < 0, both n and e are None, or if no conformers are given.

Returns

Conformer dictionaries.

Return type

list

arc.species.conformers.get_lowest_diastereomers(label, mol, conformers, diastereomers=None)[source]

Get the 2^(n-1) diastereomers with the lowest energy (where n is the number of chiral centers in the molecule). We exclude enantiomers (mirror images where ALL chiral centers simultaneously invert). If a specific diastereomer is given (in an xyz dict form), then only the lowest conformer with the same chirality will be returned.

Parameters
  • label (str) – The species’ label.

  • mol (Molecule) – The 2D graph representation of the molecule.

  • conformers (list) – Entries are conformer dictionaries.

  • diastereomers (list, optional) – Entries are xyz’s in a dictionary format or conformer structures representing specific diastereomers to keep.

Raises

ConformerError – If diastereomers is not None and is of wrong type, or if conformers with the requested chirality combination could not be generated.

Returns

Entries are lowest energy diastereomeric conformer dictionaries to consider.

Return type

list

arc.species.conformers.get_number_of_chiral_centers(label, mol, conformer=None, xyz=None, just_get_the_number=True)[source]

Determine the number of chiral centers by type. Either conformer or xyz must be given.

Parameters
  • label (str) – The species label.

  • mol (Molecule) – The RMG Molecule object.

  • conformer (dict, optional) – A conformer dictionary.

  • xyz (dict, optional) – The xyz coordinates.

  • just_get_the_number (bool, optional) – Return the number of chiral centers regardless of their type.

Raises

InputError – If neither conformer nor xyz were given.

Returns

Keys are types of chiral sites (‘C’ for carbon, ‘N’ for nitrogen, ‘D’ for double bond), values are the number of chiral centers of each type. If just_get_the_number is True, just returns the number of chiral centers (integer).

Return type

Optional[dict, int]

arc.species.conformers.get_top_element_count(mol, top)[source]

Returns the element count for the molecule considering only the atom indices in top.

Parameters
  • mol (Molecule) – The molecule to consider.

  • top (list) – The atom indices to consider.

Returns

The element count, keys are tuples of (element symbol, isotope number), values are counts.

Return type

dict

arc.species.conformers.get_torsion_angles(label, conformers, torsions)[source]

Populate each torsion pivots with all available angles from the generated conformers.

Parameters
  • label (str) – The species’ label.

  • conformers (list) – The conformers from which to extract the angles.

  • torsions (list) – The torsions to consider.

Returns

The torsion angles. Keys are torsion tuples, values are lists of all corresponding angles from conformers.

Return type

dict

arc.species.conformers.get_wells(label, angles, blank=20)[source]

Determine the distinct wells from a list of angles.

Parameters
  • label (str) – The species’ label.

  • angles (list) – The angles in the torsion.

  • blank (int, optional) – The blank space between wells.

Returns

Entry are well dicts with keys: start_idx, end_idx, start_angle, end_angle, angles.

Return type

list

arc.species.conformers.identify_chiral_nitrogen_centers(mol)[source]

Identify the atom indices corresponding to a chiral nitrogen centers in a molecule (umbrella modes).

Parameters

mol (Molecule) – The molecule to be analyzed.

Raises

TypeError – If mol is of wrong type.

Returns

Atom numbers (0-indexed) representing chiral nitrogen centers in the molecule (umbrella modes).

Return type

list

arc.species.conformers.initialize_log(verbose=20)[source]

Set up a simple logger for stdout printing (not saving into as log file).

Parameters

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

arc.species.conformers.inverse_chirality_symbol(symbol)[source]

Inverses a chirality symbol, e.g., the ‘R’ character to ‘S’, or ‘NS’ to ‘NR’. Note that chiral double bonds (‘E’ and ‘Z’) must not be inversed (they are not mirror images of each other).

Parameters

symbol (str) – The chirality symbol.

Raises

InputError – If symbol could not be recognized.

Returns

The inverse chirality symbol.

Return type

str

arc.species.conformers.mix_rdkit_and_openbabel_force_field(label, mol, num_confs=None, xyz=None, force_field='GAFF', try_ob=False)[source]

Optimize conformers using a force field (GAFF, MMFF94s, MMFF94, UFF, Ghemical) Use RDKit to generate the random conformers (OpenBabel isn’t good enough), but use OpenBabel to optimize them (RDKit doesn’t have GAFF).

Parameters
  • label (str) – The species’ label.

  • mol (Molecule, optional) – The RMG molecule object with connectivity and bond order information.

  • num_confs (int, optional) – The number of random 3D conformations to generate.

  • xyz (string or list, optional) – The 3D coordinates in either a string or an array format.

  • force_field (str, optional) – The type of force field to use.

  • try_ob (bool, optional) – Whether to try OpenBabel if RDKit fails. True to try, False by default.

Returns

  • Entries are optimized xyz’s in a list format.

  • Entries are float numbers representing the energies in kJ/mol.

Return type

Tuple[list, list]

arc.species.conformers.openbabel_force_field(label, mol, num_confs=None, xyz=None, force_field='GAFF', method='diverse')[source]

Optimize conformers using a force field (GAFF, MMFF94s, MMFF94, UFF, Ghemical).

Parameters
  • label (str) – The species’ label.

  • mol (Molecule, optional) – The RMG molecule object with connectivity and bond order information.

  • num_confs (int, optional) – The number of random 3D conformations to generate.

  • xyz (dict, optional) – The 3D coordinates.

  • force_field (str, optional) – The type of force field to use.

  • method (str, optional) – The conformer searching method to use in OpenBabel. For method description, see http://openbabel.org/dev-api/group__conformer.shtml

Returns

  • Entries are optimized xyz’s in a list format.

  • Entries are float numbers representing the energies in kJ/mol.

Return type

Tuple[list, list]

arc.species.conformers.openbabel_force_field_on_rdkit_conformers(label, rd_mol, force_field='MMFF94s', optimize=True)[source]

Optimize RDKit conformers by OpenBabel using a force field (MMFF94 or MMFF94s are recommended). This is a fall back method when RDKit fails to generate force field optimized conformers.

Parameters
  • label (str) – The species’ label.

  • rd_mol (RDKit RDMol) – The RDKit molecule with embedded conformers to optimize.

  • force_field (str, optional) – The type of force field to use.

  • optimize (bool, optional) – Whether to first optimize the conformer using FF. True to optimize.

Returns

  • Entries are optimized xyz’s in a dictionary format.

  • Entries are float numbers representing the energies (in kJ/mol).

Return type

Tuple[list, list]

arc.species.conformers.prune_enantiomers_dict(label, enantiomers_dict)[source]

A helper function for screening out enantiomers from the enantiomers_dict, leaving only diastereomers (so removing all exact mirror images). Note that double bond chiralities ‘E’ and ‘Z’ are not mirror images of each other, and are not pruned out.

Parameters
  • label (str) – The species’ label.

  • enantiomers_dict (dict) – Keys are chirality tuples, values are conformer structures.

Returns

The pruned enantiomers_dict.

Return type

dict

arc.species.conformers.rdkit_force_field(label, rd_mol, force_field='MMFF94s', optimize=True)[source]

Optimize RDKit conformers using a force field (MMFF94 or MMFF94s are recommended).

Parameters
  • label (str) – The species’ label.

  • rd_mol (RDKit RDMol) – The RDKit molecule with embedded conformers to optimize.

  • force_field (str, optional) – The type of force field to use.

  • optimize (bool, optional) – Whether to first optimize the conformer using FF. True to optimize.

Returns

  • Entries are optimized xyz’s in a dictionary format.

  • Entries are float numbers representing the energies.

Return type

Tuple[list, list]

arc.species.conformers.read_rdkit_embedded_conformer_i(rd_mol, i, rd_index_map=None)[source]

Read coordinates from RDKit conformers.

Parameters
  • rd_mol (RDKit RDMol) – The RDKit molecule with embedded conformers to optimize.

  • i (int) – The conformer index from rd_mol to read.

  • rd_index_map (list, optional) – An atom map dictionary to reorder the xyz. Keys are rdkit atom indices, values are RMG mol atom indices.

Returns

xyz coordinates.

Return type

dict

arc.species.conformers.read_rdkit_embedded_conformers(label, rd_mol, i=None, rd_index_map=None)[source]

Read coordinates from RDKit conformers.

Parameters
  • label (str) – The species’ label.

  • rd_mol (RDKit RDMol) – The RDKit molecule with embedded conformers to optimize.

  • i (int, optional) – The conformer index from rd_mol to read. If None, all will be read,

  • rd_index_map (list, optional) – An atom map dictionary to reorder the xyz. Requires mol to not be None.

Returns

Entries are xyz coordinate dicts.

Return type

list

arc.species.conformers.replace_n_with_c_in_mol(mol, chiral_nitrogen_centers)[source]

Replace nitrogen atoms (pre-identified as chiral centers) with carbon atoms, replacing the lone electron pair (assuming just one exists) with a hydrogen or a halogen atom, preserving any radical electrons on the nitrogen atom.

Parameters
  • mol (Molecule) – The molecule to be analyzed.

  • chiral_nitrogen_centers (list) – The 0-index of chiral (umbrella mode) nitrogen atoms in the molecule.

Raises

ConformerError – If any of the atoms indicated by chiral_nitrogen_centers could not be a chiral nitrogen atom.

Returns

  • A copy of the molecule with replaced N atoms.

  • Elements inserted in addition to the C atom, ordered as in chiral_nitrogen_centers.

Return type

Tuple[Molecule, list]

arc.species.conformers.replace_n_with_c_in_xyz(label, mol, xyz, chiral_nitrogen_centers, elements_to_insert)[source]

Replace nitrogen atoms (pre-identified as chiral centers) with carbon atoms, replacing the lone electron pair (assuming just one exists) with a hydrogen or a halogen atom.

Parameters
  • label (str) – The species label.

  • mol (Molecule) – The respective molecule object.

  • xyz (dict) – The 3D coordinates to process.

  • chiral_nitrogen_centers (list) – The 0-index of chiral (umbrella mode) nitrogen atoms in the molecule.

  • elements_to_insert (list) – The element (H/F/Cl/I) to insert in addition to C per nitrogen center.

Returns

The coordinates with replaced N atoms.

Return type

dict

arc.species.conformers.to_group(mol, atom_indices)[source]

This method converts a defined part of a Molecule into a Group.

Parameters
  • mol (Molecule) – The base molecule.

  • atom_indices (list) – 0-indexed atom indices corresponding to atoms in mol to be included in the group.

Returns

A group consisting of the desired atoms in mol.

Return type

Group

arc.species.conformers.translate_group(mol, xyz, pivot, anchor, vector)[source]

Translate a group (a set of atoms from the pivot towards the anchor and onwards) by changing its pivot -> anchor vector to the desired new vector. Keep the relative distances between the group’s atoms constant, as well as the distance between the anchor and the vector atoms.

Parameters
  • mol (Molecule) – The 2D graph representation of the molecule.

  • xyz (dict) – The 3D coordinates of the molecule with the same atom order as in mol.

  • pivot (int) – The 0-index of the pivotal atom around which groups are to be translated.

  • anchor (int) – The 0-index of an anchor atom. The group is defined from the pivot atom to the anchor atom, including all other atoms in the molecule connected to the anchor. The pivot and anchor atoms should not have another path connecting them such as a ring.

  • vector (list) – The new vector by which the group will be translated.

Returns

The translated coordinates.

Return type

dict

arc.species.conformers.translate_groups(label, mol, xyz, pivot)[source]

Exchange between two groups in a molecule. The groups cannot share a ring with the pivotal atom. The function does not change the atom order, just the coordinates of atoms. If the pivotal atom has exactly one lone pair, consider it as well as a dummy atom in translations.

Parameters
  • label (str) – The species’ label.

  • mol (Molecule) – The 2D graph representation of the molecule.

  • xyz (dict) – A string-format 3d coordinates of the molecule with the same atom order as in mol.

  • pivot (int) – The 0-index of the pivotal atom around which groups are to be translated.

Returns

The translated coordinates.

Return type

dict

arc.species.conformers.update_mol(mol)[source]

Update atom types, multiplicity, and atom charges in the molecule.

Parameters

mol (Molecule) – The molecule to update.

Returns

the updated molecule.

Return type

Molecule