Wrappers<a class="headerlink" href="#module-qm_atlas.wrappers" title="Link to this heading">¶

Returns:

A dictionary of the parsed properties, keyed by their canonical names.

Raises:

RuntimeError – If the properties could not be parsed from stdout.

qm_atlas.wrappers.xtb.read_xtb_output(temp, stdout, stderr, read_json=True, read_bondorders=False, read_fukui=False)[source]¶

Reads and parses an xtb JSON output file.

Parameters:

temp (WorkDir) – WorkDir object containing the scratch directory path.
stdout (str) – Standard output from the xtb calculation.
stderr (str) – Standard error from the xtb calculation.
read_json (bool) – Whether to read the JSON output file. Defaults to True.
read_bondorders (bool) – Whether to read bond orders from the output. Defaults to False.
read_fukui (bool) – Whether to read Fukui indices from the output. Defaults to False.

Return type:

Returns:

A dictionary containing the parsed properties.

Raises:

json.JSONDecodeError – If the JSON file exists but is malformed.
RuntimeError – If the JSON file is missing and properties cannot be parsed from stdout either.

qm_atlas.wrappers.xtb.optimize_geometry(mol, conf_id, keep_files=False, scr=DEFAULT_SCR, n_cores=1, template_str=None, xtb_command_add=None, solvation_model=None, solvent=None, use_json=True, **template_kwargs)[source]¶

Optimize the geometry of a conformation using xtb.

Parameters:

mol (Mol) – RDKit molecule object with 3D coordinates for the specified conformer
conf_id (int) – ID of the conformer to optimize (typically 0 for single conformer)
keep_files (bool) – If True, keep intermediate files in scratch directory. Defaults to False. Can be useful for debugging.
scr (Path) – Scratch directory path for temporary files. Defaults to DEFAULT_SCR.
n_cores (int) – Number of CPU cores to use. Defaults to 1. Sets OMP_NUM_THREADS and other parallelization environment variables.
template_str (str | None) – Jinja2 template string for xcontrol input file. Defaults to XCONTROL_TEMPLATE_OPT.
xtb_command_add (list[str] | None) – Additional command-line arguments to pass to xtb. Defaults to None (empty list).
solvation_model (str | None) – Solvation model to use (“alpb”, “gbsa”, “cosmo” or “cpmcx”). Defaults to None (no solvation).
solvent (str | None) – Solvent name (e.g., “water”, “methanol”) if solvation_model is specified. Defaults to None.
use_json (bool) – Whether to request xtb’s --json output. If False (or if the JSON file is missing), properties are parsed from stdout. Defaults to True.
**template_kwargs – Additional keyword arguments passed to the xcontrol template (e.g., max_num_steps, optlevel, constrain, torsions_fixed, etc.)

Returns:

Numpy array of shape (n_atoms, 3) containing optimized atomic: coordinates in Angstrom units.
properties: Dictionary containing xtb properties calculated in the final single-point: calculation after geometry optimization.

Return type:

tuple[ndarray | None, dict[str, Property] | None]

Raises:

RuntimeError – If any error occurs during optimization.

qm_atlas.wrappers.xtb.get_optimization_converged(temp, stdout, stderr)[source]¶

Checks whether an xtb geometry optimization converged successfully.

Parses stdout/stderr for xtb’s convergence status messages. If neither a “converged” nor a “failed to converge” message is found, falls back to checking for the presence of the .xtboptok flag file.

Parameters:

temp (WorkDir) – WorkDir object containing the scratch directory path.
stdout (str) – Standard output from the xtb calculation.
stderr (str) – Standard error from the xtb calculation.

Returns:

True if the optimization converged, False otherwise.

Return type:

qm_atlas.wrappers.xtb.calculate_single_point(mol, conf_id, keep_files=False, scr=DEFAULT_SCR, n_cores=1, template_str=None, xtb_command_add=None, solvation_model=None, solvent=None, calculate_fukui=False, use_json=True, **template_kwargs)[source]¶

Calculate single-point properties using xtb.

Parameters:

mol (Mol) – RDKit molecule object with 3D coordinates for the specified conformer
conf_id (int) – ID of the conformer to optimize (typically 0 for single conformer)
keep_files (bool) – If True, keep intermediate files in scratch directory. Defaults to False. Can be useful for debugging.
scr (Path) – Scratch directory path for temporary files. Defaults to DEFAULT_SCR.
n_cores (int) – Number of CPU cores to use. Defaults to 1. Sets OMP_NUM_THREADS and other parallelization environment variables.
template_str (str | None) – Jinja2 template string for xcontrol input file. Defaults to XCONTROL_TEMPLATE_SP.
xtb_command_add (list[str] | None) – Additional command-line arguments to pass to xtb. Defaults to None (empty list).
solvation_model (str | None) – Solvation model to use (“alpb”, “gbsa”, “cosmo” or “cpmcx”). Defaults to None (no solvation).
solvent (str | None) – Solvent name (e.g., “water”, “methanol”) if solvation_model is specified. Defaults to None.
calculate_fukui (bool) – If True, calculate Fukui indices and include them in the output. This will add the flag –vfukui to the xtb_command_add if not already present. Defaults to False.
use_json (bool) – Whether to request xtb’s --json output. If False (or if the JSON file is missing), properties are parsed from stdout. Defaults to True.
**template_kwargs – Additional keyword arguments passed to the xcontrol template (e.g., max_num_steps, optlevel, constrain, torsions_fixed, etc.)

Returns:

Dictionary of single-point properties from xtb.

Return type:

Raises:

RuntimeError – If any error occurs during calculation.
ValueError – If solvent is not specified when solvation_model is provided.

qm_atlas.wrappers.xtb.XCONTROL_TEMPLATE_OPT¶

$chrg {{ charge | default(0) }}
$spin {{ num_unpaired_electrons | default(0) }}

$gfn
  method={{ method | default(gfn_method) | default(2) }}
  scc=true

$opt
  maxcycle={{ max_num_steps | default(500) }}
  optlevel={{ opt_level | default("normal") }} {% if constrain %}

$constrain{% if torsions_fixed %}
  all torsions=true{% endif %}{% if heavy_atom_torsions_fixed %}{% for atom_indices in dihedral_constraints %}
  dihedral: {{ atom_indices | join(",") }},auto{% endfor %}{% endif %}{% if angles_fixed %}
  all angles=true{% endif %}{% if bonds_fixed %}
  all bonds=true{% endif %}
  force constant={{ force_constant | default(0.5) }} {% endif %}

qm_atlas.wrappers.xtb.XCONTROL_TEMPLATE_SP¶

$chrg {{ charge | default(0) }}
$spin {{ num_unpaired_electrons | default(0) }}

$gfn
  method={{ method | default(gfn_method) | default(2) }}
  scc=true

qm_atlas.wrappers.xtb.DEFAULT_FORCE_CONSTANT = 0.5¶: Force constant for the $constrain block, in Hartree/rad^2 for angles and torsions and Hartree/Bohr^2 for distances. 0.5 holds a restrained torsion to a few tenths of a degree, which is what makes “the input pose was held” a checkable statement. The previous value of 0.001 dated from when the block also restrained every C/N/O/S pairwise distance, so the force constant was not the only thing holding the geometry; with the explicit dihedral: restraints it is, and 0.001 leaves a torsion almost as free as no restraint at all.

Heavy-atom torsion selection for constrained xtb optimizations.

The module aims to identify torsion angles involving only heavy atoms that are suitable to fix in constrained optimizations. It follows the logic used by xtb’s constrain_all_torsions routine, but restricts to heavy atoms only. With the atom indices found, it writes the resulting torsions as explicit dihedral: i,j,k,l,auto restraints. Like xtb it keeps a bond j-k when both central atoms have a coordination number of at least 2 (i.e. carry a substituent besides each other) and skips near-linear arrangements.

qm_atlas.wrappers.torsion_constraints.LINEAR_ANGLE_TOLERANCE_DEG = 11.46¶: Angles this close to 180° (in degrees) make a torsion ill-defined, so torsions containing them are skipped. Matches the 0.2 rad threshold xtb uses in constrain_all_torsions.

qm_atlas.wrappers.torsion_constraints.find_heavy_atom_torsions(mol, conf_id=-1, linear_angle_tolerance_deg=LINEAR_ANGLE_TOLERANCE_DEG)[source]¶

Select one heavy-atom torsion per bond that carries a torsional degree of freedom.

Follows xtb’s constrain_all_torsions logic: a bond j-k is kept when both central atoms have a heavy-atom coordination number of at least 2 (i.e. each has a heavy neighbour besides the other), and torsions with a near-linear bond angle are skipped. Unlike xtb, only heavy atoms are counted and used.

Parameters:

mol (Mol) – Molecule with connectivity and at least one conformation. The conformation is only used to reject near-linear arrangements.
conf_id (int) – Conformation used for the near-linearity check. Defaults to -1 (the first/only conformation).
linear_angle_tolerance_deg (float) – Torsions containing a bond angle within this many degrees of 180° are skipped, because the torsion is then ill-defined. Defaults to LINEAR_ANGLE_TOLERANCE_DEG.

Raises:

ValueError – If the molecule has no conformation.

Returns:

One (i, j, k, l) tuple of 0-based atom indices per selected bond, ordered by the central bond’s atom indices. j and k are the central bond’s atoms.

Return type:

list[tuple[int, int, int, int]]

Turbomole¶

qm_atlas.wrappers.turbomole.single_point.run_ridft(mol, conf_id, control_template=PREPARE_SP, basis=DEFAULT_BASIS, functional=DEFAULT_FUNCTIONAL, grid=DEFAULT_GRID, scf_conv=DEFAULT_SCF_CONV, scfiterlimit=DEFAULT_SCFITERLIMIT, ricore=DEFAULT_RICORE, use_disp=False, use_cosmo=True, klamt=True, solvent=DEFAULT_SOLVENT, scr=DEFAULT_SCR, keep_files=False, n_cores=1, name='Molecule', **kwargs)[source]¶

Runs turbomole ridft single-point calculations

Parameters:

mol (Mol) – The molecule to work with.
conf_id (int) – The ID of the conformation to work with.
control_template (str | None) – The template for the control file to use. Using a different template allows modification of all turbomole settings, beyond the ones explicitly listed. Defaults to PREPARE_SP, which is also used if control_template=None.
basis (str) – The basis set to specify in the turbomole control file. Defaults to DEFAULT_BASIS (“def2-TZVPD”).
functional (Sequence[str]) – The functional to specify for the turbomole control file. If the list has several entries, the control file will have several lines “functional …” Defaults to DEFAULT_FUNCTIONAL (“b-p”).
grid (str) – Sets grid to use for turbomole calculation. Options can be m3, m4, etc… Higher values lead to denser grids with greater computational cost. Defaults to DEFAULT_GRID (“m4”).
scf_conv (int) – SCF energy convergence criterion as exponent (10^-scf_conv). Higher values lead to tighter convergence. Defaults to DEFAULT_SCF_CONV (7).
scfiterlimit (int) – The maximum number of SCF iterations to perform. Defaults to DEFAULT_SCFITERLIMIT (500).
ricore (int | None) – RICORE memory parameter. Defaults to DEFAULT_RICORE (None).
use_disp (bool) – If True, adds dispersion corrections ($disp3 bj) to the control file. Defaults to False.
use_cosmo (bool) – Whether to use COSMO solvation model. Defaults to True.
klamt (bool) – Whether to use Klamt’s COSMO variant. Defaults to True.
solvent (str) – The solvent to use for COSMO calculations. Defaults to DEFAULT_SOLVENT (“conductor”).
scr (Path) – The scratch directory for temporary calculation files. Defaults to DEFAULT_SCR.
keep_files (bool) – Whether to keep temporary files created during the calculation. Defaults to False.
n_cores (int) – The number of CPU cores to use for the calculation. Defaults to 1.
name (str) – Filename prefix for COSMO output file (within the temp directory that is created). Defaults to “Molecule”.
**kwargs – Additional keyword arguments passed to prepare_turbomole_input().

Raises:

RuntimeError – If turbomole preparations fail, if calculations end abnormally, or if turbomole output file cannot be found.

Returns:

A dictionary with turbomole single point properties including HOMO-LUMO gap, total energy, and (if use_cosmo=True) COSMO output. Returns None if the calculation failed.

Return type:

qm_atlas.wrappers.turbomole.single_point.read_cosmo_file(scr, filename, basis)[source]¶

Reads the contents of the cosmo file and returns it as a string. Tries to fix an error in the info line of the cosmo file.

Return type:

Parameters:

scr (Path)
filename (str)
basis (str)

qm_atlas.wrappers.turbomole.single_point.check_ridft(stderr, log_file)[source]¶

Searches turbomole ridft output for signs of an error and raises an: exception if it finds one.

Parameters:

stderr (str) – The ridft output to stderr.
log_file (Path | str) – The path to the turbomole logfile.

Raises:

RuntimeError – If ridft claims it ended abnormally or did not converge.

qm_atlas.wrappers.turbomole.single_point.parse_ridft(log_file)[source]¶

Parses the output of a turbomole single point calculation

Parameters:: log_file (Path | str) – The Path to the ridft.log output file produced by turbomole.
Raises:: RuntimeError – If the output cannot be parsed or doesn’t pass consistency checks.
Returns:: A dictionary with turbomole single point properties
Return type:: dict[str, Property]

qm_atlas.wrappers.turbomole.single_point.PREPARE_SP¶

$atoms
basis ={{ basis }} {% if basis=="def2-mTZVP" %}
jbas =def2-TZVP{% else %}
jbas ={{ basis }} {% endif %}
$coord file=coord
$symmetry c1
$eht charge={{ charge }} {% if scfiterlimit %}
$scfiterlimit {{ scfiterlimit }} {% endif %}
$scfconv {{ scf_conv }} {% if ricore %}
$ricore {{ ricore }} {% endif %}
$dft
{% for func in functional %}functional {{ func }}
{% endfor %}
gridsize {{ grid }} {% if use_disp %}
$disp3 bj {% endif %}
$rij
$marij {% if use_cosmo %}
{% if klamt %}
$klamt {% endif %}
$cosmo
  epsilon={{ epsilon_value }}
rsolv = 1.30
$cosmo_atoms
$cosmo_out file={{ name }}.cosmo
$cosmo_isorad {% endif %}
$end

qm_atlas.wrappers.turbomole.single_point.DEFAULT_BASIS = 'def2-TZVPD'¶

qm_atlas.wrappers.turbomole.single_point.DEFAULT_FUNCTIONAL = ('b-p',)¶

qm_atlas.wrappers.turbomole.single_point.DEFAULT_GRID = 'm4'¶

qm_atlas.wrappers.turbomole.single_point.DEFAULT_SCF_CONV = 7¶

qm_atlas.wrappers.turbomole.single_point.DEFAULT_SCFITERLIMIT = 500¶

qm_atlas.wrappers.turbomole.single_point.DEFAULT_RICORE = None¶

qm_atlas.wrappers.turbomole.single_point.DEFAULT_SOLVENT = 'conductor'¶

qm_atlas.wrappers.turbomole.jobex.run_jobex(mol, conf_id, control_template=PREPARE_JOBEX, keep_files=False, max_num_steps=DEFAULT_STEPS, energy_conv=DEFAULT_ENERGY_CONV, scf_conv=DEFAULT_SCF_CONV, geom_conv=DEFAULT_GEOM_CONV, grid=DEFAULT_GRID, basis=DEFAULT_BASIS, functional=DEFAULT_FUNCTIONAL, use_cosmo=True, solvent=DEFAULT_SOLVENT, use_disp=False, scfiterlimit=DEFAULT_SCFITERLIMIT, keep_coords_fixed=None, log_information=True, n_cores=1, **kwargs)[source]¶

Runs the turbomole jobex script to optimize coordinates of a conformer

Parameters:

mol (Mol) – The molecule to work with.
conf_id (int) – The ID of the conformation to work with.
control_template (str) – The template defining the turbomole control file; this sets the functional, basis set etc. Defaults to PREPARE_JOBEX.
keep_files (bool) – Whether to keep the intermediate files produced by turbomole. Defaults to False.
max_num_steps (int) – The maximum number of optimization steps to perform. Defaults to DEFAULT_STEPS (100).
energy_conv (int) – Sets geometry iteration energy convergence threshold to 10.**(-energy_conv). Higher values lead to tighter convergence. Defaults to DEFAULT_ENERGY_CONV, note that the turbomole jobex default is 6.
scf_conv (int) – Sets scf energy convergence threshold to 10.**(-scf_conv). Higher values lead to tighter convergence. scf_conv should be at least as tight as geom_conv, otherwise geometry iterations will have trouble converging. Defaults to DEFAULT_SCF_CONV.
geom_conv (int) – Sets coordinate change convergence threshold to 10.**(-geom_conv). Higher values lead to tighter convergence. This value should be set higher for geometries to be used in IR or VCD spectra calculations to avoid inaccurate intensities and negative frequencies. Defaults to DEFAULT_GEOM_CONV, which is also the turbomole default.
grid (str) – Sets grid to use for turbomole calculation. Options can be m3, m4, etc… or 3, 4, etc… Higher values lead to denser grids with greater computational cost; denser grids are necessary for some calculations, but the error for the default is typically small relative to DFT error in general. Defaults to DEFAULT_GRID.
basis (str) – The basis set to specify in the turbomole control file. Defaults to DEFAULT_BASIS.
functional (Sequence[str]) – The functional to specify for the turbomole control file. If the list has several entries, the control file will have several lines “functional …” Defaults to DEFAULT_FUNCTIONAL.
use_cosmo (bool) – Whether to use COSMO solvation model. Defaults to True.
solvent (str) – The solvent to use for COSMO calculations. Defaults to DEFAULT_SOLVENT (“conductor”).
use_disp (bool) – If True, adds dispersion corrections ($disp3 bj) to the control file. Defaults to False.
scfiterlimit (int) – The maximum number of SCF iterations to perform. Defaults to DEFAULT_SCFITERLIMIT.
keep_coords_fixed (list[int] | str | None) – List of atom indices, for which the positions should be kept fixed during the geometry optimization. Defaults to None (all positions can be modified). Additionally, you may use the string “heavy_atoms” to indicate that only the hydrogen positions may be adapted.
log_information (bool) – Whether to log information about the settings used for the run. Defaults to True.
n_cores (int) – The number of CPU cores to use for the calculation. Defaults to 1.
**kwargs – Additional keyword arguments passed to prepare_turbomole_input().

Raises:

RuntimeError – If the calculation fails or turbomole ends abnormally.

Returns:

A tuple containing:

new_coords: A numpy array of shape (num_atoms, 3) with optimized atom coordinates, or None if optimization failed.
opt_results: A dictionary with optimization results including convergence status, or None if optimization failed.

Return type:

tuple[ndarray | None, dict[str, Property] | None]

qm_atlas.wrappers.turbomole.jobex.check_jobex(temp, stdout, stderr)[source]¶

Checks if a turbomole jobex job failed. Raises a RuntimeError in case it failed.

Parameters:

temp (WorkDir) – The directory the job was run in
stdout (str) – The stdout output of the job
stderr (str) – The output of stderr

Raises:

RuntimeError – If the job has failed.

Returns:

Whether the jobex optimization converged.

Return type:

qm_atlas.wrappers.turbomole.jobex.log_debug_information(stdout, stderr)[source]¶

Logs debug information from the turbomole jobex run.

Parameters:

stdout (str | None) – The stdout output from the jobex run.
stderr (str | None) – The stderr output from the jobex run.

qm_atlas.wrappers.turbomole.jobex.parse_coord(coord_file, expected_atom_labels=None, keep_coords_fixed=None)[source]¶

parses coordinates from a turbomole coord file.

Parameters:

coord_file (Path) – Path to a turbomole coord file
expected_atom_labels (list[str] | None) – The list of element symbol corresponding to the expected indexing of the molecule. If provided, this is used as a cross-check. Defaults to None, in this case no checking of the indexing is performed.
keep_coords_fixed (list[int] | None) – List of atom indices, for which the positions should be kept fixed during the geometry optimization.

Raises:

RuntimeError – If the checking of the order of element symbols fails

Returns:

An array of shape (n_atoms, 3) listing the coordinates of the nuclei.

Return type:

ndarray

qm_atlas.wrappers.turbomole.jobex.PREPARE_JOBEX¶

$atoms
basis= {{ basis }}
$coord file=coord
$symmetry c1
$eht charge={{ charge }} {% if scfiterlimit %}
$scfiterlimit {{ scfiterlimit }} {% endif %}
$dft
{% for func in functional %}functional {{ func }}
{% endfor %}gridsize {{ grid }}
{% if use_disp %}$disp3 bj {% endif %}
$scfconv {{ scf_conv }}
$rij
$marij {% if use_cosmo %}
$cosmo
  epsilon={{ epsilon_value }} {% endif %}
$grad file=gradient
$end

qm_atlas.wrappers.turbomole.jobex.DEFAULT_BASIS = 'def2-TZVP'¶

qm_atlas.wrappers.turbomole.jobex.DEFAULT_FUNCTIONAL = ('b-p',)¶

qm_atlas.wrappers.turbomole.jobex.DEFAULT_STEPS = 100¶

qm_atlas.wrappers.turbomole.jobex.DEFAULT_ENERGY_CONV = 7¶

qm_atlas.wrappers.turbomole.jobex.DEFAULT_SCF_CONV = 7¶

qm_atlas.wrappers.turbomole.jobex.DEFAULT_GEOM_CONV = 3¶

qm_atlas.wrappers.turbomole.jobex.DEFAULT_GRID = 'm4'¶

qm_atlas.wrappers.turbomole.jobex.DEFAULT_SCFITERLIMIT = 500¶

qm_atlas.wrappers.turbomole.jobex.DEFAULT_SOLVENT = 'conductor'¶

qm_atlas.wrappers.turbomole.xtb_opt.run_xtb_tm_optimization(mol, conf_id, keep_files=False, scr=DEFAULT_SCR, n_cores=1, tm_control_template=jobex.PREPARE_JOBEX, xtb_command_add=None, xcontrol_template=XCONTROL_TEMPLATE_CSTR, scf_conv=7, grid='m4', basis=jobex.DEFAULT_BASIS, functional=jobex.DEFAULT_FUNCTIONAL, use_disp=True, scfiterlimit=None, use_cosmo=True, solvent='conductor', max_num_steps=DEFAULT_XTB_TM_STEPS, opt_level=DEFAULT_OPT_LEVEL, constrain=False, torsions_fixed=False, heavy_atom_torsions_fixed=True, angles_fixed=False, bonds_fixed=False, force_constant=xtb.DEFAULT_FORCE_CONSTANT, **kwargs)[source]¶

Optimize molecule geometry using xtb-driven turbomole DFT calculations.

Uses xtb to drive the geometry optimization while turbomole calculates the gradients at the DFT level. This combines the efficiency of xtb’s optimizer with the accuracy of DFT gradients.

Parameters:

mol (Mol) – RDKit molecule object with 3D coordinates for the specified conformer
conf_id (int) – ID of the conformer to optimize (typically 0 for single conformer)
keep_files (bool) – If True, keep intermediate files in scratch directory. Defaults to False.
scr (Path) – Scratch directory path for temporary files. Defaults to DEFAULT_SCR.
n_cores (int) –

Number of CPU cores to use. Defaults to 1. Sets OMP_NUM_THREADS
and other parallelization environment variables.
tm_control_template (str) – Jinja2 template string for turbomole control file. Defaults to PREPARE_JOBEX.
xtb_command_add (list[str] | None) – Additional command-line arguments to pass to xtb. Defaults to None (empty list).
xcontrol_template (str | None) – Jinja2 template string for xtb xcontrol input file. Defaults to XCONTROL_TEMPLATE_CSTR.
scf_conv (int) – SCF energy convergence threshold as 10**(-scf_conv). Defaults to 7.
grid (str) – Grid size for turbomole DFT calculation (m3, m4, etc.). Defaults to “m4”.
basis (str) – Basis set for turbomole calculation. Defaults to “def2-TZVP”.
functional (Sequence[str]) – DFT functional(s) for turbomole. Defaults to (“b-p”,).
use_disp (bool) – If True, adds dispersion correction ($disp3 bj). Defaults to True.
scfiterlimit (int | None) – Maximum number of SCF iterations. Defaults to None (not set).
use_cosmo (bool) – If True, uses the COSMO implicit solvent model. Defaults to True.
solvent (str) – Implicit solvent model. Defaults to “conductor”.
max_num_steps (int) – Maximum number of optimization steps. Defaults to DEFAULT_XTB_TM_STEPS (100).
opt_level (str) – Optimization level for xtb (e.g., “loose”, “normal”, “tight”). Defaults to DEFAULT_OPT_LEVEL (“normal”).
constrain (bool) – Master switch: if True, applies the geometry constraints selected by the boolean flags below. Defaults to False.
torsions_fixed (bool) – Fix all torsions via xtb’s global all torsions switch (only applies if constrain). Defaults to False.
heavy_atom_torsions_fixed (bool) – Fix heavy-atom torsions by writing one explicit dihedral: i,j,k,l,auto restraint per heavy-atom torsion, leaving bonds and angles free (only applies if constrain). Defaults to True.
angles_fixed (bool) – Fix all bond angles via xtb’s global all angles switch (only applies if constrain). Defaults to False.
bonds_fixed (bool) – Fix all bond lengths via xtb’s global all bonds switch (only applies if constrain). Defaults to False.
force_constant (float) – Force constant for constraints. Defaults to DEFAULT_FORCE_CONSTANT (0.5).
**kwargs – Additional keyword arguments passed to turbomole control template and the template for the xcontrol file. Note that the filling of templates can handle keyword arguments that are not used in the templates.

Returns:

Numpy array of shape (n_atoms, 3) containing optimized atomic: coordinates in Angstrom units. Returns None if optimization failed.
properties:: Dictionary containing optimization properties (convergence status, etc.). Returns None if optimization failed.

Return type:

tuple[ndarray | None, dict[str, Any] | None]

Raises:

RuntimeError – If xtb-turbomole calculation fails.
ValueError – If optimized atom symbols don’t match input molecule

qm_atlas.wrappers.turbomole.xtb_opt.check_xtb_tm_optimization(stdout, stderr, conf_id)[source]¶

Checks whether an xtb-driven turbomole geometry optimization finished successfully.: Raises a RuntimeError in case it failed.

Parameters:

stdout (str | None) – The standard output from the xtb-driven turbomole optimization.
stderr (str | None) – The standard error output from the optimization.
conf_id (int) – The ID of the conformation that was considered. Needed for logging.

Raises:

RuntimeError – If the job has failed.

qm_atlas.wrappers.turbomole.xtb_opt.XCONTROL_TEMPLATE_CSTR¶

$chrg {{ charge | default(0) }}
$spin {{ num_unpaired_electrons | default(0) }}

$opt
  maxcycle={{ max_num_steps | default(100) }}
  optlevel={{ opt_level | default("normal") }} {% if constrain %}

$constrain{% if torsions_fixed %}
  all torsions=true{% endif %}{% if heavy_atom_torsions_fixed %}{% for atom_indices in dihedral_constraints %}
  dihedral: {{ atom_indices | join(",") }},auto{% endfor %}{% endif %}{% if angles_fixed %}
  all angles=true{% endif %}{% if bonds_fixed %}
  all bonds=true{% endif %}
  force constant={{ force_constant | default(0.5) }} {% endif %}

qm_atlas.wrappers.turbomole.xtb_opt.DEFAULT_XTB_TM_STEPS = 100¶

qm_atlas.wrappers.turbomole.xtb_opt.DEFAULT_OPT_LEVEL = 'normal'¶

qm_atlas.wrappers.turbomole.freeh.calculate_freeh(mol, conf_id, control_template=PREPARE_FREEH, freeh_settings=FREEH_SETTINGS, keep_files=False, basis=DEFAULT_BASIS, functional=DEFAULT_FUNCTIONAL, grid=DEFAULT_GRID, scf_conv=DEFAULT_SCF_CONV, scfiterlimit=DEFAULT_SCFITERLIMIT, scfdamp=DEFAULT_SCFDAMP, ricore=DEFAULT_RICORE, use_disp=False, use_cosmo=False, klamt=True, solvent=DEFAULT_SOLVENT, n_cores=1, **kwargs)[source]¶

Calculates energy, entropy, enthalpy and chemical potential using turbomole: for a given set of conditions.

Parameters:

mol (Mol) – The molecule to work with.
conf_id (int) – The ID of the conformation to work with.
control_template (str | None) – The template for the control file to use. Cf. e.g. PREPARE_NMR for an example. Using a different control file allows to modify the turbomole runs (e.g. different functionals or basis sets). The function will render variables called “charge” and “epsilon_value”. Defaults to PREPARE_FREEH.
freeh_settings (str) – A string specifying the conditions for the freeh calculation. Defaults to FREEH_SETTINGS.
keep_files (bool) – Whether to use a keep all files created in the process of the calculation. Defaults to False.
basis (str) – The basis set to specify in the turbomole control file. Defaults to “def2-TZVP”.
functional (Sequence[str]) – The functional to specify for the turbomole control file. If the list has several entries, the control file will have several lines “functional …” Defaults to [“b3-lyp”].
grid (str) – Sets grid to use for turbomole calculation. Options can be m3, m4, etc… Defaults to “m3”.
scf_conv (int) – SCF energy convergence criterion as exponent (10^-scf_conv). Higher values lead to tighter convergence. Defaults to 7.
scfiterlimit (int) – The maximum number of SCF iterations to perform. Defaults to 200.
scfdamp (str) – SCF damping parameters. Defaults to “start=0.300 step=0.050 min=0.100”.
ricore (int | None) – RICORE memory parameter. Defaults to None.
use_disp (bool) – If True, adds dispersion corrections ($disp3 bj) to the control file. Defaults to False.
use_cosmo (bool) – Whether to use COSMO solvation model. Defaults to False.
klamt (bool) – Whether to use Klamt’s COSMO variant. Defaults to True.
solvent (str) – The solvent to use for COSMO calculations. Defaults to “conductor”.
n_cores (int) – The number of CPU cores to use for the calculation. Defaults to 1.
**kwargs – Additional keyword arguments to be passed to the function prepare_turbomole_input(), cf. the respective docstring for more details

Raises:

RuntimeError – If turbomole preparations fail, turbomole calculations end abnormally, or turbomole output file can’t be found.

Returns:

A dictionary containing the chemical potential, energy, entropy and enthalpy at the conditions specified in freeh_settings.

Return type:

qm_atlas.wrappers.turbomole.freeh.parse_freeh(freeh_output)[source]¶

Extracts the chemical potential, energy, entropy and enthalpy from the output: file of a turbomole freeh calculation.

Parameters:: freeh_output (Path) – Path to the turbomole freeh output file
Returns:: A dictionary mapping the keywords to the respective result.
Return type:: dict[str, Property]

qm_atlas.wrappers.turbomole.freeh.PREPARE_FREEH¶

$atoms
basis ={{ basis }} {% if basis=="def2-mTZVP" %}
jbas =def2-TZVP{% else %}
jbas ={{ basis }} {% endif %}
$coord file=coord
$symmetry c1
$eht charge={{ charge }} {% if scfiterlimit %}
$scfiterlimit {{ scfiterlimit }} {% endif %} {% if scfdamp %}
$scfdamp {{ scfdamp }}{% endif %}
$scfconv {{ scf_conv }} {% if ricore %}
$ricore {{ ricore }} {% endif %}
$dft
{% for func in functional %}functional {{ func }}
{% endfor %}
gridsize {{ grid }} {% if use_disp %}
$disp3 bj {% endif %}
$rij
$marij {% if use_cosmo %}
{% if klamt %}
$klamt {% endif %}
$cosmo
  epsilon={{ epsilon_value }} {% endif %}
$end

qm_atlas.wrappers.turbomole.freeh.FREEH_SETTINGS¶

0.97
tstart=298.15 tend=298.15 numt=1 pstart=0.1 pend=0.1 nump=1
q

qm_atlas.wrappers.turbomole.fukui.calculate_fukui(mol, conf_id, control_template=PREPARE_FUKUI, charge_schemes=None, keep_files=False, basis=DEFAULT_BASIS, functional=DEFAULT_FUNCTIONAL, grid=DEFAULT_GRID, scf_conv=DEFAULT_SCF_CONV, scfiterlimit=DEFAULT_SCFITERLIMIT, scfdamp=DEFAULT_SCFDAMP, ricore=DEFAULT_RICORE, use_disp=False, use_cosmo=True, klamt=False, solvent=DEFAULT_SOLVENT, n_cores=1, **kwargs)[source]¶

Calculates Fukui indices for all atoms in a conformer using turbomole.

Parameters:

mol (Mol) – The molecule to work with.
conf_id (int) – The ID of the conformation to work with.
control_template (str | None) – The template for the control file to use. Cf. e.g. PREPARE_FUKUI for an example. Using a different control file allows to modify the turbomole runs (e.g. different functionals or basis sets). The function will render variables called “charge” and “epsilon_value”. Defaults to PREPARE_FUKUI.
charge_schemes (list | None) – The charge schemes to use the list can contain the turbomole charge schemes nbo, mulliken, loewdin, paboon. Defaults to all of them, see get_charge_schemes().
keep_files (bool) – Whether to use a keep all files created in the process of the calculation. Defaults to False.
basis (str) – The basis set to specify in the turbomole control file. Defaults to “def2-SV(P)”.
functional (Sequence[str]) – The functional to specify for the turbomole control file. If the list has several entries, the control file will have several lines “functional …” Defaults to [“pbe”].
grid (str) – Sets grid to use for turbomole calculation. Options can be m3, m4, etc… Defaults to “m3”.
scf_conv (int) – SCF energy convergence criterion as exponent (10^-scf_conv). Higher values lead to tighter convergence. Defaults to 7.
scfiterlimit (int) – The maximum number of SCF iterations to perform. Defaults to 100.
scfdamp (str) – SCF damping parameters. Defaults to “start=2.000 step=0.050 min=0.100”.
ricore (int | None) – RICORE memory parameter. Defaults to None.
use_disp (bool) – If True, adds dispersion corrections ($disp3 bj) to the control file. Defaults to False.
use_cosmo (bool) – Whether to use COSMO solvation model. Defaults to False.
klamt (bool) – Whether to use Klamt’s COSMO variant. Defaults to False.
solvent (str) – The solvent to use for COSMO calculations. Defaults to “conductor”.
n_cores (int) – The number of CPU cores to use for the calculation. Defaults to 1.
**kwargs – Additional keyword arguments passed to prepare_turbomole_input().

Raises:

RuntimeError – If turbomole preparations fail or if calculations end abnormally, or turbomole output file can’t be found.

Returns:

A dictionary mapping a keyword to the respective fukui indices. For each of the arrays, array[idx] is the value of the respective fukui index for the atom with index idx. The dictionary also contains some scalar properties related to ionization such as the ionization potential or electron affinity.

Return type:

qm_atlas.wrappers.turbomole.fukui.check_fukui(log_file, cwd)[source]¶

Searches turbomole Fukui output for signs of an error and raises an: exception if it finds one.

Parameters:

log_file (Path) – The Fukui output file
cwd (Path) – The directory the turbomole calculations were performed in

Raises:

RuntimeError – If the turbomole Fukui script did not converge

qm_atlas.wrappers.turbomole.fukui.get_charge_schemes()[source]¶

returns the available charge schemes.

Return type:: list[str]

qm_atlas.wrappers.turbomole.fukui.parse_fukui(fukui_output, mol, charge_schemes=None, tolerance=1.0e-2)[source]¶

Parses the output of a turbomole Fukui run

Parameters:

fukui_output (Path) – The Path to the output file produced by turbomole.
mol (Mol) – The molecule that was used, used for consistency checks.
charge_schemes (list | None) – The charge schemes to use. The list can contain the turbomole charge schemes nbo, mulliken, loewdin, paboon. Defaults to all of them, see get_charge_schemes
tolerance (float) – The tolerance to use when checking if the fukui indices sum up to 1. Defaults to 0.01.

Raises:

RuntimeError – If the output cannot be parsed or doesn’t pass consistency checks.

Returns:

A dictionary with keys of the form {type}_{charge_scheme} where the type covers nucleophilic, electrophilic and radical Fukui functions and the charge schemes are the ones requested. All values are lists following the rdkit indexing of the atoms in the molecule.

Return type:

qm_atlas.wrappers.turbomole.fukui.extract_charges_fukui(fukui_output, num_atoms, charge_schemes=None)[source]¶

Extracts partial charges from the output of a turbomole Fukui run

Parameters:

fukui_output (Path) – The Path to the output file produced by turbomole.
num_atoms (int) – The number of atoms of the molecule, used for consistency checks.
charge_schemes (list | None) – The charge schemes to use. The list can contain the turbomole charge schemes nbo, mulliken, loewdin, paboon. Defaults to all of them, see get_charge_schemes

Returns:

A dictionary with keys of the form charge_{scheme} where the charge schemes are the ones requested. All values are lists following the rdkit indexing of the atoms in the molecule.

Return type:

qm_atlas.wrappers.turbomole.fukui.extract_energies_fukui(fukui_output)[source]¶

extracts different ionization energies from the output of a turbomole Fukui run.

Parameters:: fukui_output (Path) – The Path to the output file produced by turbomole.
Returns:: A dictionary describing the different ionization energies. Contains the keys ionization_potential [eV], electron_affinity [eV], hardness [eV], electronegativity [eV], electrophilicity [eV].
Return type:: dict[str, ScalarProperty]

qm_atlas.wrappers.turbomole.fukui.PREPARE_FUKUI¶

$atoms
basis={{ basis }} {% if basis=="def2-mTZVP" %}
jbas=def2-TZVP{% else %}
jbas={{ basis }} {% endif %}
$coord file=coord
$symmetry c1
$eht charge={{ charge }} {% if scfiterlimit %}
$scfiterlimit {{ scfiterlimit }} {% endif %} {% if scfdamp %}
$scfdamp   {{ scfdamp }}{% endif %}
$scfconv {{ scf_conv }} {% if ricore %}
$ricore {{ ricore }} {% endif %}
$dft
{% for func in functional %}  functional {{ func }}
{% endfor %}
  gridsize {{ grid }} {% if use_disp %}
$disp3 bj {% endif %}
$rij
$marij {% if use_cosmo %}
$cosmo {% if klamt %}
  $klamt {% endif %}
  epsilon={{ epsilon_value }} {% endif %}
$end

Turbomole wrapper for NMR Shielding calculation

qm_atlas.wrappers.turbomole.nmr_shielding.calculate_nmr_shieldings(mol, conf_id, control_template=PREPARE_NMR, keep_files=False, basis=DEFAULT_BASIS, functional=DEFAULT_FUNCTIONAL, grid=DEFAULT_GRID, scf_conv=DEFAULT_SCF_CONV, scfiterlimit=DEFAULT_SCFITERLIMIT, ricore=DEFAULT_RICORE, use_disp=False, use_cosmo=True, klamt=False, solvent='water', n_cores=1, **kwargs)[source]¶

Calculates isotropic nmr shieldings for all atoms in a conformer using turbomole.

Parameters:

mol (Mol) – The molecule to work with.
conf_id (int) – The ID of the conformation to work with.
control_template (str | None) – The template for the control file to use. Cf. e.g. PREPARE_NMR for an example. Using a different control file allows to modify the turbomole runs (e.g. different functionals or basis sets). The function will render variables called “charge” and “epsilon_value”. Defaults to PREPARE_NMR.
keep_files (bool) – Whether to use a keep all files created in the process of the calculation. Defaults to False.
basis (str) – The basis set to specify in the turbomole control file. Defaults to “def2-TZVP”.
functional (Sequence[str]) – The functional to specify for the turbomole control file. If the list has several entries, the control file will have several lines “functional …” Defaults to [“xcfun set-gga”, “xcfun kt3 1.0”].
grid (str) – Sets grid to use for turbomole calculation. Options can be 3, 4, m3, m4, etc… Defaults to “3”.
scf_conv (int) – SCF energy convergence criterion as exponent (10^-scf_conv). Higher values lead to tighter convergence. Defaults to 7.
scfiterlimit (int) – The maximum number of SCF iterations to perform. Defaults to 200.
ricore (int | None) – RICORE memory parameter. Defaults to None.
use_disp (bool) – If True, adds dispersion corrections ($disp3 bj) to the control file. Defaults to False.
use_cosmo (bool) – Whether to use COSMO solvation model. Defaults to True.
klamt (bool) – Whether to use Klamt’s COSMO variant. Defaults to False.
solvent (str) – The solvent to use for COSMO calculations. Defaults to “water”.
n_cores (int) – The number of CPU cores to use for the calculation. Defaults to 1.
**kwargs – cf. the docstring of prepare_turbomole_input() for more keyword arguments.

Raises:

RuntimeError – If turbomole preparations fail, turbomole calculations end abnormally, or turbomole output file can’t be found.

Returns:

A dictionary mapping a single key to an atom-based property. nmr_shieldings[idx] is the isotropic nmr shielding (trace of the nmr shielding tensor) for the atom with index idx in the molecule.

Return type:

qm_atlas.wrappers.turbomole.nmr_shielding.parse_nmr_isotropic(turbomole_output_file, mol)[source]¶

Parses the isotropic nmr shifts from a turbomole output file.

Parameters:

turbomole_output_file (Path) – The Path to the output file produced by turbomole.
mol (Mol) – The molecule the shieldings are computed for (defines atom ordering).

Raises:

RuntimeError – If the file does not exist at the specified location.

Returns:

nmr_shieldings[idx] is the isotropic nmr shielding (trace of the nmr shielding tensor) for the atom with index idx in the molecule.

Return type:

ndarray

qm_atlas.wrappers.turbomole.nmr_shielding.PREPARE_NMR¶

$atoms
basis={{ basis }} {% if basis=="def2-mTZVP" %}
jbas=def2-TZVP{% else %}
jbas={{ basis }} {% endif %}
$coord file=coord
$symmetry c1
$eht charge={{ charge }} {% if scfiterlimit %}
$scfiterlimit {{ scfiterlimit }} {% endif %}
$scfconv {{ scf_conv }} {% if ricore %}
$ricore {{ ricore }} {% endif %}
$dft
{% for func in functional %}functional {{ func }}
{% endfor %}
gridsize {{ grid }} {% if use_disp %}
$disp3 bj {% endif %}
$rij
$marij {% if use_cosmo %}
$cosmo {% if klamt %}
  $klamt {% endif %}
  epsilon={{ epsilon_value }} {% endif %}
$nmr dft shielding constants file=shielding
$end

qm_atlas.wrappers.turbomole.vcd.calculate_vcd(mol, conf_id, basis=DEFAULT_BASIS, functional=DEFAULT_FUNCTIONAL, grid=DEFAULT_GRID, scf_conv=DEFAULT_SCF_CONV, scfiterlimit=DEFAULT_SCFITERLIMIT, scfdamp=DEFAULT_SCFDAMP, ricore=DEFAULT_RICORE, use_disp=False, use_cosmo=True, klamt=False, solvent=DEFAULT_SOLVENT, control_template=PREPARE_VCD, keep_files=False, n_cores=1, **kwargs)[source]¶

Calculates IR & VCD (vibrational circular dichroism) spectra using turbomole: for a given set of conditions. VCD is typically used to distinguish enantiomers, which have spectra that are mirror images. Note that IR & VCD should be run on geometries that are converged to tighter thresholds (energy 8, gcart 4 for turbomole jobex). Note that turbomole VCD can’t use turbomole’s mgrids, so “gridsize 4” is the default rather than m4.

Parameters:

mol (Mol) – The molecule to work with.
conf_id (int) – The ID of the conformation to work with.
basis (str) – The basis set to specify in the turbomole control file. Defaults to “def2-SVP”.
functional (Sequence[str]) – The functional to specify for the turbomole control file. If the list has several entries, the control file will have several lines “functional …” Defaults to (“b3-lyp”, ).
grid (str) – Sets grid to use for turbomole calculation (numeric format like 4, 5, etc). Defaults to “4”.
scf_conv (int) – Sets scf energy convergence threshold to 10.**(-scf_conv). Higher values lead to tigher convergence. Defaults to 8.
scfiterlimit (int) – The maximum number of SCF iterations to perform. Defaults to 500.
scfdamp (str) – The SCF damping settings written to the control file. Defaults to DEFAULT_SCFDAMP.
ricore (int | None) – RICORE memory parameter. Defaults to None.
use_disp (bool) – If set, this will add a line $disp3 bj to the control file. Defaults to False.
use_cosmo (bool) – Whether to use COSMO solvation model. Defaults to True.
klamt (bool) – Whether to use Klamt’s COSMO variant. Defaults to False.
solvent (str) – The solvent to use for COSMO calculations. Defaults to “conductor”.
control_template (str | None) – The template for the control file to use. Cf. e.g. PREPARE_NMR for an example. Using a different control file allows to modify the turbomole runs (e.g. different functionals or basis sets). The function will render variables called “charge” and “epsilon_value”. Defaults to PREPARE_VCD.
keep_files (bool) – Whether to use a keep all files created in the process of the calculation. Defaults to False.
n_cores (int) – The number of CPU cores to use for the calculation. Defaults to 1.
**kwargs – Additional keyword arguments passed to prepare_turbomole_input().

Raises:

RuntimeError – If turbomole preparations fail (cannot be turned off) If turbomole calculations end abnormally, or turbomole output file can’t be found.

Returns:

A dictionary containing the IR and VCD spectra energies and intensities

Return type:

dict[str, TensorProperty] | None

qm_atlas.wrappers.turbomole.vcd.parse_vcd(out_file, log_file)[source]¶

Extracts the IR and VCD spectrum from a vcd calculation exspectrum file output.

Parameters:

out_file (Path) – Path to the turbomole vcd vibspectrum output file.
log_file (Path) – Path to the vcd log file (used for error reporting).

Returns:

A dictionary mapping the keywords to the respective result.

Return type:

dict[str, TensorProperty] | None

qm_atlas.wrappers.turbomole.vcd.PREPARE_VCD¶

$atoms
basis={{ basis }} {% if basis=="def2-mTZVP" %}
jbas=def2-TZVP{% else %}
jbas={{ basis }} {% endif %}
$coord file=coord
$symmetry c1
$eht charge={{ charge }} {% if scfiterlimit %}
$scfiterlimit {{ scfiterlimit }} {% endif %} {% if scfdamp %}
$scfdamp   {{ scfdamp }}{% endif %}
$scfconv {{ scf_conv }} {% if ricore %}
$ricore {{ ricore }} {% endif %}
$dft
{% for func in functional %}functional {{ func }}
{% endfor %}gridsize {{ grid }} {% if use_disp %}
$disp3 bj {% endif %}
$rij
$marij {% if use_cosmo %}
$cosmo {% if klamt %}
  $klamt {% endif %}
  epsilon={{ epsilon_value }} {% endif %}
$end

qm_atlas.wrappers.turbomole.utils.prepare_turbomole_input(mol, template_str, conf_id=-1, use_cosmo=True, solvent='conductor', keep_coords_fixed=None, scr=DEFAULT_SCR, keep_files=False, **template_kwargs)[source]¶

Creates a directory for the turbomole input and creates the necessary control and coord files.

Parameters:

mol (Mol) – The molecule to work with.
template_str (str) – The template for the control file to use. Cf. e.g. PREPARE_NMR for an example. Using a different control file allows to modify the turbomole runs (e.g. different functionals or basis sets). The function will render variables called “charge” and “epsilon_value”.
conf_id (int) – The ID of the conformation to work with.
use_cosmo (bool) – If set False, it toggles the line “$cosmo” in the turbomole control file. Defaults to True.
solvent (str) – The implicit solvent model to use. Translates to an epsilon value in turbomole. Defaults to “conductor”, other solvents are available if they have been added to SOLVENT_TO_EPS
keep_coords_fixed (list[int] | None) – List of atom indices, for which the positions should be kept fixed during the geometry optimization. Defaults to None, i.e. all positions can be modified.
scr (Path) – A scratch directory to use for the turbomole calculations. Defaults to to DEFAULT_SCR, defined in qm_atlas.constants
keep_files (bool) – Whether to keep all files created in the process of the calculation. Defaults to False.
**template_kwargs – Additional keyword arguments used to fill out the template.

Raises:

RuntimeError – If turbomole preparations fail.
ValueError – If an unknown solvent is provided.

Returns:

A scratch directory for the turbomole calculations.

Return type:

WorkDir

qm_atlas.wrappers.turbomole.utils.fix_coordinates(coord_str, keep_coords_fixed)[source]¶

Adapts the turbomole coord file to inform turbomole on atoms positions which: are supposed to be kept fixed (in a geometry optimization).

Parameters:

coord_str (str) – The contents of the turbomole coord file, as a string
keep_coords_fixed (list[int]) – indices of the atoms which are supposed to be kept fixed

Returns:

The adapted coord file.

Return type:

qm_atlas.wrappers.turbomole.utils.get_turbomole_version()[source]¶

Return the installed Turbomole (major, minor) version.

Parsed from the TURBODIR path of the configured turbomole environment (e.g. .../Turbomole/8.0 -> (8, 0)). Returns None if it cannot be determined.

Return type:: tuple[int, int] | None

qm_atlas.wrappers.turbomole.utils.check_tmol_generic(stderr, log_file, prog_name)[source]¶

Searches the output of a turbomole program for signs of an error and raises an: exception if it finds one.

Parameters:

stderr (str) – The output to stderr.
log_file (Path) – The path to the turbomole logfile.
prog_name (str) – The name of the program that is checked, used for logging.

Raises:

RuntimeError – If the program claims it ended abnormally.

qm_atlas.wrappers.turbomole.utils.seek_match(input_lines, match_str, line_splits)[source]¶

Find matching string in file lines, and grab strings in specified subsequent lines

This function is sufficient for parsing many non-tabular values in QM output files

Args:

input_lines (List):: file read into lines and stripped of

characters

match_str (Str):
string to find among lines

line_splits (List of tuples):
first element in pair specifies how many lines after match_str line, second element specifies index of line.split() to append to values

Returns:

values (List):: List of parsed values

qm_atlas.wrappers.turbomole.utils.extract_energy(cosmo_output, unit='kcal/mol')[source]¶

extracts the (epsilon=infinity) energy from a .cosmo file.

Parameters:

cosmo_output (str) – The content of a cosmo file as a string.
unit (str) – The unit to use. Defaults to “kcal/mol”, other option is “Hartree” or “a.u.”, resolving to the same unit (Hartree).

Raises:

ValueError – If the unit is not recognized.

Returns:

The energy noted in the cosmo file for Total energy + OC corr.

Return type:

float

qm_atlas.wrappers.turbomole.utils.extract_converged(mol, cosmo_outputs)[source]¶

extracts converged runs for single-point calculations on all conformers of: a molecule.

Parameters:

mol (Mol) – The molecule
cosmo_outputs (list[str]) – The output of the single-point calculations

Returns:

A copy of the molecule with thse conformers removed, which correspond to: unconverged single-point calculations.
converged_outputs (list[str]):: The cosmo outputs of the converged runs.
unconverged_idcs (set[int]):: The conformer indices for which the calculaton failed to converge.

Return type:

tuple[Mol, list[str], set[int]]

COSMOtherm¶

class qm_atlas.wrappers.cosmotherm.interface.CosmoPaths(license_dir, ctd_dir, ctd_file, database_dir)[source]¶

Parameters:

license_dir (Path)
ctd_dir (Path)
ctd_file (str)
database_dir (Path)

license_dir: Path¶

ctd_dir: Path¶

ctd_file: str¶

database_dir: Path¶

qm_atlas.wrappers.cosmotherm.interface.get_cosmo_paths(cosmotherm_dir=None, level='bp-tzvpd', cosmo_database=None, cmd=None)[source]¶

Retrieves the paths for COSMOtherm related files and directories.

Parameters:

cosmotherm_dir (Path | None) – Path to the COSMOtherm directory. If not provided, the function will try to find it using the COSMOTHERMDIR environment variable. Defaults to None.
level (str) – The level of theory to use for COSMOtherm calculations. Defaults to “bp-tzvpd”.
cosmo_database (Path | None) – Path to the COSMOtherm database directory. If not provided, the function will use the default database directory in the COSMOtherm directory. Defaults to None.
cmd (str | None) – Explicit path to the cosmotherm executable. If not provided, it is resolved from the environment/config. Defaults to None.

Raises:

ValueError – If the provided level of theory is not recognized.
RuntimeError – If the COSMOtherm directory or the COSMOtherm database directory cannot be found.

Returns:

A dataclass containing the paths to the license directory, CTD directory, CTD file, and database directory.

Return type:

CosmoPaths

qm_atlas.wrappers.cosmotherm.interface.setup_cosmotherm(conformers, action_lines, command_lines=None, comment_line=DEFAULT_COMMENT, scr=DEFAULT_SCR, keep_files=False, conformer_format='.cosmo', conformer_names=None, additional_properties_list=None)[source]¶

Sets up the COSMOtherm calculation by writing the input files.

Parameters:

conformers (list[list[str | Path]]) – List of conformers for each compound. Each conformer can be a path to a file or a string representing the contents of a .cosmo file.
action_lines (list[str]) – List of action lines to be included in the input file.
command_lines (list[str] | None) – List of command lines to be included in the input file. Defaults to None.
comment_line (str) – Comment line to be included in the input file. Defaults to DEFAULT_COMMENT.
scr (Path) – Path to the scratch directory where the input files will be written. Defaults to DEFAULT_SCR.
keep_files (bool) – Whether to keep the input files after the calculation. Defaults to False.
conformer_format (str) – Format of the conformer files. Defaults to “.cosmo”.
conformer_names (list[str] | None) – List of names for the conformers. Defaults to None.
additional_properties_list (list[str] | None) – Extra per-compound property lines appended to each compound’s input block (e.g. “DGfus=0” to mark a liquid). Defaults to None.

Raises:

ValueError – If more than two command lines are provided.

Returns:

A tuple containing the path to the temporary directory and the path to the input file.

Return type:

tuple[WorkDir, Path]

qm_atlas.wrappers.cosmotherm.interface.write_conformers(conformers, scr=DEFAULT_SCR, conformer_format='.cosmo', conformer_names=None, additional_properties_list=None)[source]¶

Writes the conformers to the specified directory and returns a list of input lines for each conformer.

Parameters:

conformers (list[list[str | Path]]) – List of conformers for each compound. Each conformer can be a path to a file or a string representing the contents of a .cosmo file.
scr (Path) – Path to the directory where the conformer files will be written. Defaults to DEFAULT_SCR.
conformer_format (str) – Format of the conformer files. Defaults to “.cosmo”.
conformer_names (Sequence[str | None] | None) – List of names for the conformers. Defaults to None.
additional_properties_list (list[str] | None) – Extra per-compound property lines appended to each compound’s input block (e.g. “DGfus=0” to mark a liquid). Defaults to None.

Raises:

RuntimeError – If the lengths of conformer_names and conformers, or additional_properties_list and conformers, do not match.

Returns:

List of input lines for each conformer.

Return type:

list[str]

qm_atlas.wrappers.cosmotherm.interface.write_conformer(conformer, name, scr=DEFAULT_SCR, conformer_format='.cosmo')[source]¶

Writes a single conformer to a file and returns the path to the file.

Parameters:

conformer (str | Path) – The conformer to write. Can be a path to a file or a string representing the contents of a .cosmo file.
name (str) – Name of the conformer.
scr (Path) – Path to the directory where the conformer file will be written. Defaults to DEFAULT_SCR.
conformer_format (str) – Format of the conformer file. Defaults to “.cosmo”.

Raises:

ValueError – If the provided conformer file format is not recognized, or if the provided conformer file does not exist.

Returns:

Path to the written conformer file.

Return type:

Path

qm_atlas.wrappers.cosmotherm.interface.run_cosmotherm(input_file, n_cores=1, cmd=None)[source]¶

Runs the COSMOtherm program with the given input file.

Parameters:

input_file (Path) – The path to the input file for COSMOtherm.
n_cores (int) – The number of cores to use for the COSMOtherm calculation. Defaults to 1.
cmd (str | None) – The command to run COSMOtherm. Defaults to None (infer command from config).

Raises:

ValueError – If the COSMOtherm command is not found in the system’s PATH.

Returns:

True if the COSMOtherm calculation was successful and the expected output file was produced, False otherwise.

Return type:

qm_atlas.wrappers.cosmotherm.interface.log_output(stdxx, identifier)[source]¶

Logs the output from a COSMOtherm call.

Parameters:

stdxx (str | None) – The output (either stdout or stderr) from the COSMOtherm call. If None, the function will return True.
identifier (str) – A string identifier to indicate whether the output is stdout or stderr.

Returns:

False if there is output to log (i.e., stdxx is not None and not empty), True otherwise.

Return type:

qm_atlas.wrappers.cosmotherm.interface.read_errors_output(filename)[source]¶

extracts errors from a cosmotherm .out file

Return type:: list[str]
Parameters:: filename (Path)

qm_atlas.wrappers.cosmotherm.interface.read_cosmotherm_output(file, table_start_patterns=DEFAULT_TABLE_START_PATTERNS, multi_solvent=False)[source]¶

Reads the COSMOtherm output (.tab) file and extracts data tables.

Parameters:

file (Path) – The path to the COSMOtherm output file.
table_start_patterns (Sequence[str]) – A sequence of strings that mark the start of a data table in the output file. Defaults to (“Nr Compound”,).
multi_solvent (bool) – A flag indicating whether the output file includes data for solvent mixtures. If True, the function will use a different method to parse the data tables. Defaults to False.

Returns:

A list of pandas DataFrames, each representing a data table in the COSMOtherm output file.

Return type:

list[DataFrame]

qm_atlas.wrappers.cosmotherm.interface.read_table(table_lines, multi_solvent=False)[source]¶

Reads a table in the cosmother output (.tab) file.

Parameters:

table_lines (list[str]) – The lines in the output file that contain the table.
multi_solvent (bool) – If True, parse the wider mixture-solubility layout that uses a two-space column delimiter. Defaults to False.

Returns:

The cosmotherm output table.

Return type:

qm_atlas.wrappers.cosmotherm.interface.fix_header_line(header_line)[source]¶

assures all headers in the cosmotherm table output are separated by two spaces by making some explicit replacements.

Return type:: str
Parameters:: header_line (str)

qm_atlas.wrappers.cosmotherm.interface.fix_line(line)[source]¶

adapts a line in the cosmotherm output file. Replace an integer followed by one space by the same integer followed by two spaces.

Return type:: str
Parameters:: line (str)

qm_atlas.wrappers.cosmotherm.interface.calculate_cosmotherm(conformers, action_lines, command_lines=None, comment_line=DEFAULT_COMMENT, scr=DEFAULT_SCR, keep_files=False, cmd=None, n_cores=1, output_reader=read_cosmotherm_output, conformer_names=None, additional_properties_list=None, conformer_format='.cosmo', **reader_kwargs)[source]¶

Sets up and runs a COSMOtherm calculation, then reads the output and returns the data tables. This function combines the setup, execution, and output reading of a COSMOtherm calculation, it is not specialized to any specific type of calculation.

Parameters:

conformers (list[list[str | Path]]) – List of conformers for each compound. Each conformer can be a path to a .cosmo file or a string with the contents of a .cosmo file.
action_lines (list[str]) – List of action lines to be included in the input file.
command_lines (list[str] | None) – List of command lines to be included in the input file. Defaults to None.
comment_line (str) – Comment line to be included in the input file. Defaults to DEFAULT_COMMENT.
scr (Path) – Path to the scratch directory where the input files will be written. Defaults to DEFAULT_SCR.
keep_files (bool) – Whether to keep the input files after the calculation. Defaults to False.
cmd (str | None) – The command to run COSMOtherm. Defaults to None (infer command from config).
n_cores (int) – The number of cores to use for the COSMOtherm calculation. Defaults to 1.
output_reader (Callable[[Path], list[DataFrame]]) – A function to read the COSMOtherm output. Defaults to read_cosmotherm_output, check there for the signature of the function.
conformer_names (list[str] | None) – List of names for the conformers. Defaults to None.
additional_properties_list (list[str] | None) – Extra per-compound property lines appended to each compound’s input block (e.g. “DGfus=0” to mark a liquid). Defaults to None.
conformer_format (str) – Format of the conformer files. Defaults to “.cosmo”, allowed formats are listed in CONFORMER_FORMATS.
**reader_kwargs – Additional keyword arguments forwarded to output_reader (e.g. table_start_patterns or multi_solvent).

Returns:

A list of pandas DataFrames, each representing a data table in the COSMOtherm output file.

Return type:

list[DataFrame]

qm_atlas.wrappers.cosmotherm.cosmo_tasks.calculate_logp(compound_conformers, level='bp-tzvpd', is_woctanol=True, options=None, solvent_names=('h2o', '1-octanol'), temperature_Celsius=25.0, solvents_dirs=None, eq_phases=False, use_config_cosmo_dir=True, **kwargs)[source]¶

This function calculates the logP of a compound using Cosmotherm.

Parameters:

compound_conformers (list[str | Path]) – List of compound conformers, either specifying the path to the file or providing the contents as a string. In the latter case, the file must be a .cosmo file, otherwise it can be any file that cosmotherm accepts.
level (str) – Level of theory. Defaults to “bp-tzvpd”. Other allowed options are “bp-tzvp”, “bp-svp” and “dmol3-pbe”.
is_woctanol (bool) – Whether the logP calculation is for water-octanol. Defaults to True. The value has an effect on the settings for the calculation. If it is set True and the options argument is not provided, the default settings for water-octanol logP calculation are used. These take into account that there is some octanol in the water and vice-versa.
options (CosmoSettings | None) – Settings for the Cosmo task. Defaults to None, in which case default options are used, these are different for water-octanol and any other mixture.
solvent_names (tuple[str, str]) – List of two solvents, specified by their names. Corresponding .cosmo files must be found in the database, either the standard cosmotherm one or an additional, user-provided one. Defaults to [“h2o”, “1-octanol”].
temperature_Celsius (float) – Temperature (in Celsius) at which the calculation is run. Defaults to 25.0.
solvents_dirs (list[Path] | None) – Additional directories to find the .cosmo files for the solvents. Defaults to None, i.e. just relying on the cosmotherm database.
eq_phases (bool) – Cosmotherm option for logp calculations: Compute the phase equilibrium between the given two solvents. For water-octanol, the default options have an experimentally determined phase equilibrium, so this option is not needed. Default to False.
use_config_cosmo_dir (bool) – Whether to prepend the solvent directories from the software configuration file to the user-provided solvents_dirs. If False, only the user-provided directories are used. Defaults to True.
**kwargs – Additional keyword arguments for the output reader.

Returns:

A dictionary mapping a single key to a scalar property. The key is “cosmo_logp” and the value is the calculated logP value of the compound.

Return type:

qm_atlas.wrappers.cosmotherm.cosmo_tasks.calculate_delta_g(compound_conformers, level='bp-tzvpd', options=DG_SETTINGS, solvent_name='h2o', temperature_Celsius=25.0, solvents_dirs=None, use_config_cosmo_dir=True, **kwargs)[source]¶

This function calculates the free energy of solvation (delta G) of a compound using Cosmotherm.

Parameters:

compound_conformers (list[str | Path]) – List of compound conformers, either specifying the path to the file or providing the contents as a string. In the latter case, the file must be a .cosmo file, otherwise it can be any file that cosmotherm accepts.
level (str) – Level of theory. Defaults to “bp-tzvpd”. Other allowed options are “bp-tzvp”, “bp-svp” and “dmol3-pbe”.
options (CosmoSettings) – Settings for the Cosmo task. Defaults to DG_SETTINGS.
solvent_name (str) – The solvent, specified by its name. Corresponding .cosmo file must be found in the database, either the standard cosmotherm one or an additional, user-provided one. There is an option to consider the case of the compound dissolved in itself, i.e. self-solvation. In this case, the solvent name should be set to “self”. The default is “h2o”.
temperature_Celsius (float) – Temperature (in Celsius) at which the calculation is run. Defaults to 25.0.
solvents_dirs (list[Path] | None) – Additional directories to find the .cosmo file for the solvent. Defaults to None, i.e. just relying on the cosmotherm database.
use_config_cosmo_dir (bool) – Whether to prepend the solvent directories from the software configuration file to the user-provided solvents_dirs. If False, only the user-provided directories are used. Defaults to True.
**kwargs – Additional keyword arguments for the output reader.

Returns:

A dictionary mapping a single key to a scalar property. The key is “cosmo_delta_g” and the value is the calculated free energy of solvation (delta G) of the compound in kcal/mol.

Return type:

qm_atlas.wrappers.cosmotherm.cosmo_tasks.calculate_descriptors_df(compound_conformers, level='bp-tzvpd', options=DESCRIPTORS_SETTINGS, solvent_name='h2o', temperature_Celsius=25.0, solvents_dirs=None, use_config_cosmo_dir=True, **kwargs)[source]¶

This function calculates the Cosmotherm descriptors of a compound.

Parameters:

compound_conformers (list[str | Path]) – List of compound conformers, either specifying the path to the file or providing the contents as a string. In the latter case, the file must be a .cosmo file, otherwise it can be any file that cosmotherm accepts.
level (str) – Level of theory. Defaults to “bp-tzvpd”. Other allowed options are “bp-tzvp”, “bp-svp” and “dmol3-pbe”.
options (CosmoSettings) – Settings for the Cosmo task. Defaults to DESCRIPTORS_SETTINGS.
solvent_name (str) – The solvent, specified by its name. Corresponding .cosmo file must be found in the database, either the standard cosmotherm one or an additional, user-provided one. Defaults to “h2o”.
temperature_Celsius (float) – Temperature (in Celsius) at which the calculation is run. Defaults to 25.0.
solvents_dirs (list[Path] | None) – Additional directories to find the .cosmo file for the solvent. Defaults to None, i.e. just relying on the cosmotherm database.
use_config_cosmo_dir (bool) – Whether to prepend the solvent directories from the software configuration file to the user-provided solvents_dirs. If False, only the user-provided directories are used. Defaults to True.
**kwargs – Additional keyword arguments for the output reader.

Returns:

A DataFrame containing the calculated descriptors of the compound.

Return type:

qm_atlas.wrappers.cosmotherm.cosmo_tasks.calculate_descriptors(compound_conformers, level='bp-tzvpd', options=DESCRIPTORS_SETTINGS, solvent_name='h2o', temperature_Celsius=25.0, solvents_dirs=None, use_config_cosmo_dir=True, **kwargs)[source]¶

This function calculates the Cosmotherm descriptors of a compound.

Parameters:

compound_conformers (list[str | Path]) – List of compound conformers, either specifying the path to the file or providing the contents as a string. In the latter case, the file must be a .cosmo file, otherwise it can be any file that cosmotherm accepts.
level (str) – Level of theory. Defaults to “bp-tzvpd”. Other allowed options are “bp-tzvp”, “bp-svp” and “dmol3-pbe”.
options (CosmoSettings) – Settings for the Cosmo task. Defaults to DESCRIPTORS_SETTINGS.
solvent_name (str) – The solvent, specified by its name. Corresponding .cosmo file must be found in the database, either the standard cosmotherm one or an additional, user-provided one. Defaults to “h2o”.
temperature_Celsius (float) – Temperature (in Celsius) at which the calculation is run. Defaults to 25.0.
solvents_dirs (list[Path] | None) – Additional directories to find the .cosmo file for the solvent. Defaults to None, i.e. just relying on the cosmotherm database.
use_config_cosmo_dir (bool) – Whether to prepend the solvent directories from the software configuration file to the user-provided solvents_dirs. If False, only the user-provided directories are used. Defaults to True.
**kwargs – Additional keyword arguments for the output reader.

Returns:

A list of dictionaries, each containing the calculated descriptors of a compound conformer. The list follows the order of the input compound conformers. Each dictionary maps descriptor names to their corresponding scalar property values.

Return type:

list[dict[str, ScalarProperty]]

qm_atlas.wrappers.cosmotherm.cosmo_tasks.calculate_pka(parent_conformers, child_conformers, form, level='bp-tzvpd', options=PKA_SETTINGS, solvent_name='h2o', temperature_Celsius=25.0, solvents_dirs=None, use_config_cosmo_dir=True, **kwargs)[source]¶

This function calculates the pK of a compound using Cosmotherm.

Parameters:

parent_conformers (list[str | Path]) – List of parent compound conformers, either specifying the path to the file or providing the contents as a string. In the latter case, the file must be a .cosmo file, otherwise it can be any file that cosmotherm accepts.
child_conformers (list[str | Path]) – List of child compound conformers, either specifying the path to the file or providing the contents as a string. In the latter case, the file must be a .cosmo file, otherwise it can be any file that cosmotherm accepts.
form (str) – The form used for the calculation, either “ACID” or “BASE”. Note that if the form is “ACID”, the child conformers should have charge difference -1 to the parent conformers, and if the form is “BASE”, the child conformers should have charge difference +1.
level (str) – Level of theory. Defaults to “bp-tzvpd”. Other allowed options are “bp-tzvp”, “bp-svp” and “dmol3-pbe”.
options (CosmoSettings) – Settings for the Cosmo task. Defaults to PK_SETTINGS.
solvent_name (str) – The solvent, specified by its name. Corresponding .cosmo file must be found in the database, either the standard cosmotherm one or an additional, user-provided one. Defaults to “h2o”.
temperature_Celsius (float) – Temperature (in Celsius) at which the calculation is run. Defaults to 25.0.
solvents_dirs (list[Path] | None) – Additional directories to find the .cosmo file for the solvent. Defaults to None, i.e. just relying on the cosmotherm database.
use_config_cosmo_dir (bool) – Whether to prepend the solvent directories from the software configuration file to the user-provided solvents_dirs. If False, only the user-provided directories are used. Defaults to True.
**kwargs – Additional keyword arguments for the output reader.

Raises:

ValueError – If the form is not “ACID” or “BASE” or if the solvent is not available. For pKa calculations, only selected solvents are available.

Returns:

The calculated pK value of the compound.

Return type:

float

qm_atlas.wrappers.cosmotherm.cosmo_tasks.calculate_cosmoperm(compound_conformers, level='bp-tzvpd', micelle_file=None, micelle_name='dmpc', temperature_Celsius=37.0, pH=7.4, options=COSMO_PERM_SETTINGS, solvents_dirs=None, use_config_cosmo_dir=True, **kwargs)[source]¶

This function calculates the permeability of a compound using COSMOperm.

Parameters:

compound_conformers (list[str | Path]) – List of compound conformers, either specifying the path to the file or providing the contents as a string. In the latter case, the file must be a .cosmo file, otherwise it can be any file that cosmotherm accepts.
level (str) – Level of theory. Defaults to “bp-tzvpd”. Other allowed options are “bp-tzvp”, “bp-svp” and “dmol3-pbe”.
micelle_file (Path | None) – Path to a custom micelle file (.mic). If provided, this overrides micelle_name. Defaults to None (use micelle_name instead).
micelle_name (str) – Name of the micelle to use for the calculation (e.g., ‘dmpc’). The system will look for ‘COSMOmic-{micelle_name}.mic’ in the database. Only used if micelle_file is None. Defaults to “dmpc”. Other micelle names preloaded in COSMOtherm are: “dppc”, “popc”, “SDS”.
temperature_Celsius (float) – Temperature in Celsius for the calculation. Defaults to 37.0.
pH (float) – pH value for the calculation. Defaults to 7.4.
options (CosmoSettings) – Settings for the COSMOperm task. Defaults to COSMO_PERM_SETTINGS.
solvents_dirs (list[Path] | None) – Additional directories to find the .cosmo files (currently unused for COSMOperm). Defaults to None.
use_config_cosmo_dir (bool) – Whether to use the cosmo directory from the software configuration. Defaults to True.
**kwargs – Additional keyword arguments for the output reader.

Returns:

The calculated logPerm (cm/s) value of the compound.

Return type:

Raises:

ValueError – If the micelle file is not found in the database.

qm_atlas.wrappers.cosmotherm.cosmo_tasks.DG_SETTINGS = CosmoSettings(action_lines=['henry=1 tc={temperature_Celsius} GSOLV'], command_lines=['unit notempty ehfile wtln'], comment_line='!! dG solv calculation !!')¶

list[str], comment_line: str)

Type:: CosmoSettings(action_lines
Type:: list[str], command_lines

qm_atlas.wrappers.cosmotherm.cosmo_tasks.DESCRIPTORS_SETTINGS = CosmoSettings(action_lines=['x_pure=1 tc={temperature_Celsius} ctab wconf'], command_lines=['unit notempty ehfile wtln pri2 pri1 dipoleref=cop'], comment_line='!! mixture calculation !!')¶

list[str], comment_line: str)

Type:: CosmoSettings(action_lines
Type:: list[str], command_lines

Extract charge/area to get PSA from *.cosmo files

References

[1]: J. Phys. Chem. A 1998, 102, 5074-5085, https://doi.org/10.1021/jp980017s

[2]: P. Ertl, Private Communication

qm_atlas.wrappers.cosmotherm.cpsa.cosmo_to_df(file)[source]¶

Parse a .cosmo file’s surface-segment table into a DataFrame.

Return type:: DataFrame
Parameters:: file (Path)

qm_atlas.wrappers.cosmotherm.cpsa.dist_mat(coord)[source]¶

Return the pairwise Euclidean distance matrix for a set of coordinates.

Return type:: ndarray
Parameters:: coord (ndarray)

qm_atlas.wrappers.cosmotherm.cpsa.average_sigma_density_and_charges(coord, area, sigma, charge)[source]¶

Average sigma charge density.

Averaging is done according to eq. 11 in Reference [1]: J. Phys. Chem. A 1998, 102, 5074-5085, https://doi.org/10.1021/jp980017s

Return type:

tuple[ndarray, ndarray]

Parameters:

coord (ndarray)
area (ndarray)
sigma (ndarray)
charge (ndarray)

qm_atlas.wrappers.cosmotherm.cpsa.extract_sigma_density_and_charges(file, smoothen=True)[source]¶

Extract (optionally smoothed) sigma density and atomic charges from a .cosmo file.

Return type:

tuple[ndarray, ndarray]

Parameters:

file (Path)
smoothen (bool)

qm_atlas.wrappers.cosmotherm.cpsa.extract_psa(sigma, charge, area, lower_limit=MLIMIT, upper_limit=PLIMIT, on_charges=False)[source]¶

Compute the polar surface area from sigma (or charge) values outside the given limits.

Return type:

float

Parameters:

sigma (ndarray)
charge (ndarray)
area (ndarray)
lower_limit (float)
upper_limit (float)
on_charges (bool)

qm_atlas.wrappers.cosmotherm.cpsa.extract_psa_from_cosmo_file(file, smoothen=True, lower_limit=MLIMIT, upper_limit=PLIMIT, on_charges=False)[source]¶

Extract the polar surface area (PSA) from a COSMO file.

The smoothening of the sigma and charge values is done according to eq. 11 in Reference [1], the code is an extension of a previous implementation by P. Ertl (private communication).

Parameters:

file (Path) – Path to the COSMO file.
smoothen (bool) – Whether to smoothen the sigma and charge values. Defaults to True.
lower_limit (float) – Lower limit for the PSA calculation. Defaults to MLIMIT.
upper_limit (float) – Upper limit for the PSA calculation. Defaults to PLIMIT.
on_charges (bool) – Whether to calculate PSA based on charges instead of sigma. Defaults to False. Note that the thresholds should be adapted accordingly.

Returns:

Dictionary containing the PSA value.

Return type:

References

[1]: A. Klamt, V. Jonas, T. Bürger, J. C. W. Lohrenz, “Refinement and Parametrization of COSMO-RS”, J. Phys. Chem. A 1998, 102, 5074-5085, https://doi.org/10.1021/jp980017s

qm_atlas.wrappers.cosmotherm.cpsa.MLIMIT = -0.01¶

qm_atlas.wrappers.cosmotherm.cpsa.PLIMIT = 0.01¶

qm_atlas.wrappers.cosmotherm.cosmo_utils.get_default_command_line(cosmo_paths)[source]¶

Return the default cosmotherm command line for the given cosmo paths.

Parameters:: cosmo_paths (CosmoPaths)

class qm_atlas.wrappers.cosmotherm.cosmo_utils.CosmoSettings(action_lines, command_lines, comment_line)[source]¶

Parameters:

action_lines (list[str])
command_lines (list[str])
comment_line (str)

action_lines: list[str]¶

command_lines: list[str]¶

comment_line: str¶

get_command_lines(cosmo_paths)[source]¶

Return type:: list[str]
Parameters:: cosmo_paths (CosmoPaths)

qm_atlas.wrappers.cosmotherm.cosmo_utils.get_databases(cosmo_paths, level='bp-tzvpd', other_databases=None, use_config_cosmo_dir=True)[source]¶

joins the default cosmo database with other databases if provided. In the returned list,: other_databases comes first, then cosmo databases from the software config, and last the ones included with the cosmotherm installation.

Parameters:

cosmo_paths (CosmoPaths) – The paths of the cosmotherm module.
level (str) – The level of theory, used to locate the configured solvent directories. Defaults to “bp-tzvpd”.
other_databases (list[Path] | None) – The paths to other databases. Defaults to None.
use_config_cosmo_dir (bool) – Whether to prepend the cosmo databases from the software config. Defaults to True.

Returns:

The paths to the databases to use.

Return type:

tuple[Path, ...]

qm_atlas.wrappers.cosmotherm.cosmo_utils.get_all_cosmo_files(cosmo_dirs, max_depth=1)[source]¶

collects all cosmo files in a collection of dictionaries and stores them as: a dictionary mapping the name of the file to the path.

Parameters:

cosmo_dirs (tuple[Path, ...]) – The directories to search
max_depth (int) – How many levels of subdirectories to consider. Defaults to 1.

Returns:

a dictionary mapping the name of the file to the path

Return type:

dict[str, Path]

qm_atlas.wrappers.cosmotherm.cosmo_utils.find_cosmo_files(cosmo_dirs, compound_name, search_depth=1, fail_on_error=False)[source]¶

Searches for .cosmo files for a given compound in specified directories.

Parameters:

cosmo_dirs (tuple[Path, ...]) – The directories to search for .cosmo files.
compound_name (str) – The name of the compound to search for.
search_depth (int) – How many levels of subdirectories to consider. Defaults to 1.
fail_on_error (bool) – If True, raises an error when no .cosmo file is found for the compound. Defaults to False.

Raises:

ValueError – If no .cosmo file is found for the compound and fail_on_error is True.

Returns:

A list of Paths to the .cosmo files found for the compound.

Return type:

list[Path]

qm_atlas.wrappers.cosmotherm.cosmo_utils.check_input_conformers(compound_conformers, strict_input=True)[source]¶

Validate that compound_conformers are non-empty and in a cosmotherm-accepted format.

Return type:

None

Parameters:

compound_conformers (list[str | Path])
strict_input (bool)

qm_atlas.wrappers.cosmotherm.cosmo_cocrystal.screen_cocrystals(compound_conformers, coformers, level='bp-tzvpd', options=COCRYSTAL_SETTINGS, coformers_dirs=None, temperature_Celsius=25.0, stoichiometry=(1, 1), f_fit=False, f_fit_cof=True, f_fit_sol=False, pZWI=False, n_cores=1, use_config_cosmo_dir=True, **kwargs)[source]¶

This function performs a cocrystal screening using Cosmotherm, calculating values such as the excess enthalpy of the mixture. The method and example applications are described in reference [1].

Parameters:

compound_conformers (list[str | Path]) – List of compound conformers, either specifying the path to the file or providing the contents as a string. In the latter case, the file must be a .cosmo file, otherwise it can be any file that cosmotherm accepts.
coformers (list[str]) – List of coformers, specified by their names. Corresponding .cosmo files must be found in the database, either the standard cosmotherm one or an additional, user-provided one.
level (str) – Level of theory. Defaults to “bp-tzvpd”.
options (CosmoSettings) – Settings for the Cosmo task. Defaults to COCRYSTAL_SETTINGS.
coformers_dirs (list[Path] | None) – Additional directories to find the .cosmo files for the coformers. Defaults to None, i.e. just relying on the cosmotherm database. If additional directories are considered, the cosmotherm database is searched first, the the coformers_dirs.
temperature_Celsius (float) – Temperature for the calculation in °C. Defaults to 25.
stoichiometry (tuple[int, int]) – Stoichiometry of the cocrystal. Will be used for all cocrystals in the screening. Defaults to (1, 1).
f_fit (bool | tuple[float, float, float]) – Add the key ‘f_fit’ to the cosmotherm action line. This will lead to additionally calculating a fitted function for a heuristic expression. Set to True to use the default cosmotherm parameters, provide a tuple to set the parameters. Defaults to False.
f_fit_cof (bool | tuple[float, float]) – Add the key ‘f_fit_cof’ to the cosmotherm action line. This will lead to additionally calculating a fitted function for a heuristic expression. Set to True to use the default cosmotherm parameters, provide a tuple to set the parameters. Defaults to True.
f_fit_sol (bool | tuple[float, float, float]) – Add the key ‘f_fit_sol’ to the cosmotherm action line. This will lead to additionally calculating a fitted function for a heuristic expression. Set to True to use the default cosmotherm parameters, provide a tuple to set the parameters. Defaults to False.
pZWI (bool) – Add the key ‘pZWI’ to the cosmotherm action line. This is suggested if either the API or the coformer is zwitterionic (punish zwittterions). Defaults to False.
n_cores (int) – Number of cores to use for the calculation. Defaults to 1.
use_config_cosmo_dir (bool) – Whether to prepend the solvent directories from the software configuration file to the user-provided coformers_dirs. If False, only the user-provided directories are used. Defaults to True.
**kwargs – Additional keyword arguments for the output reader.

Returns:

A DataFrame containing the results of the cocrystal screening.

Return type:

References

[1] Loschen, C. & Klamt, A. Solubility prediction, solvate and cocrystal screening as tools for rational crystal engineering. J. Pharm. Pharmacol. 67, 803-811 (2015). https://doi.org/10.1111/jphp.12376

qm_atlas.wrappers.cosmotherm.cosmo_cocrystal.COCRYSTAL_SETTINGS = CosmoSettings(action_lines=None, command_lines=['unit notempty ehfile wtln'], comment_line='!! cocrystal screening !!')¶

list[str], comment_line: str)

Type:: CosmoSettings(action_lines
Type:: list[str], command_lines

class qm_atlas.wrappers.cosmotherm.cosmo_solubility.ReferenceSolubility(value, solvent_names, temperature, mass_fractions=None, solubility_unit='c')[source]¶

class to hold data about measured solubility in a solvent or solvent mixture.

Parameters:

value (float)
solvent_names (list[str])
temperature (float)
mass_fractions (None | list[float])
solubility_unit (str)

value: float¶

solvent_names: list[str]¶

temperature: float¶

mass_fractions: None | list[float] = None¶

solubility_unit: str = 'c'¶

class qm_atlas.wrappers.cosmotherm.cosmo_solubility.SolventInputTable(cosmo_dirs)[source]¶

A class to handle the input solvents provided to cosmotherm solubility calculations. While the API is not handled here, it is assumed that the first compound to input is the API, such that the first solvent has the second position in the list of input structures.

Parameters:: cosmo_dirs (tuple[Path, ...])

name_to_cosmo_files: dict[str, list[Path]]¶

name_to_position: dict[str, int]¶

add_solvents(solvent_names)[source]¶

Parameters:: solvent_names (list[str])

finish_setup()[source]¶

get_cosmo_files(name)[source]¶

Parameters:: name (str)

get_position(name)[source]¶

Parameters:: name (str)

iterate_solvents()[source]¶

get_concentration_string(solvent_names, mass_fractions)[source]¶

Return type:

Parameters:

solvent_names (list[str])
mass_fractions (list[float])

get_reference_string(references)[source]¶

Parameters:: references (list[ReferenceSolubility])

get_solubility_action_line(solvent_names, cosmo_key, references, temperature, output_units)[source]¶

Parameters:

solvent_names (list[str])
cosmo_key (str)
references (list[ReferenceSolubility])
temperature (float)
output_units (str)

get_solubility_action_line_mixture(solvent_names, cosmo_key, references, temperature, output_units, num_steps_binary=NUM_STEPS_BINARY_MIXTURE, num_steps_ternary=NUM_STEPS_TERNARY_MIXTURE, optimize=False)[source]¶

Parameters:

solvent_names (list[str])
cosmo_key (str)
references (list[ReferenceSolubility])
temperature (float)
output_units (str)
num_steps_binary (int)
num_steps_ternary (int)
optimize (bool)

qm_atlas.wrappers.cosmotherm.cosmo_solubility.calculate_solubility(compound_conformers, solvent_names, melting_temperature_C=None, melting_enthalpy_kJ_per_mol=None, level='bp-tzvpd', references=None, options=SOLUBILITY_SETTINGS, solvents_dirs=None, temperature=25.0, output_units='wsolout_c lsolout_gl', n_cores=1, use_config_cosmo_dir=True, **kwargs)[source]¶

This function calculates the solubility of compounds in pure solvents using Cosmotherm. The method and example applications are described in reference [1].

Parameters:

compound_conformers (list[str | Path]) – List of compound conformers, either specifying the path to the file or providing the contents as a string. In the latter case, the file must be a .cosmo file, otherwise it can be any file that cosmotherm accepts.
solvent_names (list[str]) – List of solvents, specified by their names. Corresponding .cosmo files must be found in the database, either the standard cosmotherm one or an additional, user-provided one.
melting_temperature_C (float | None) – The experimental melting temperature of the compound in degree Celsius. This can be used to determine the heat of fusion. Defaults to None, in this case no information on the melting temperature is passed to cosmotherm.
melting_enthalpy_kJ_per_mol (float | None) – The experimental melting enthalpy of the compound. This can be used to determine the heat of fusion. Defaults to None, in this case no information on the melting enthalpy is passed to cosmotherm.
level (str) – Level of theory. Defaults to “bp-tzvpd”.
references (list[ReferenceSolubility] | None) – List of reference solubilities. Defaults to None.
options (CosmoSettings) – Settings for the Cosmo task. Defaults to SOLUBILITY_SETTINGS.
solvents_dirs (list[Path] | None) – Additional directories to find the .cosmo files for the solvents. Defaults to None, i.e. just relying on the cosmotherm database. If additional directories are considered, the cosmotherm database is searched first, the the solvents_dirs.
temperature (float) – Temperature for the calculation in °C. Defaults to 25.
output_units (str) – Units for the output. Defaults to “wsolout_c lsolout_gl”. Check the cosmotherm documentation to see which strings can be used.
n_cores (int) – Number of cores to use for the calculation. Defaults to 1.
use_config_cosmo_dir (bool) – Whether to prepend the solvent directories from the software configuration file to the user-provided solvents_dirs. If False, only the user-provided directories are used. Defaults to True.
**kwargs – Additional keyword arguments for the output reader.

Returns:

A DataFrame containing the results of the solubility calculation.

Return type:

References

qm_atlas.wrappers.cosmotherm.cosmo_solubility.calculate_solubility_mixture(compound_conformers, solvent_combinations, melting_temperature_C=None, melting_enthalpy_kJ_per_mol=None, level='bp-tzvpd', references=None, options=SOLUBILITY_SETTINGS, solvents_dirs=None, temperature=25.0, output_units='wsolout_c lsolout_gl', num_steps_binary=NUM_STEPS_BINARY_MIXTURE, num_steps_ternary=NUM_STEPS_TERNARY_MIXTURE, optimize=False, n_cores=1, use_config_cosmo_dir=True, **kwargs)[source]¶

This function calculates the solubility of compounds in binary or ternary mixtures of solvents using Cosmotherm. For each solvent combination, it goes through equally spaced mixture ratios (in terms of mass fractions). The number of steps for this spacing can be controlled via the arguments num_steps_binary and num_steps ternary. The method and example applications are described in reference [1].

Parameters:

compound_conformers (list[str | Path]) – List of compound conformers, either specifying the path to the file or providing the contents as a string. In the latter case, the file must be a .cosmo file, otherwise it can be any file that cosmotherm accepts.
solvent_combinations (list[list[str]]) – List of solvent combinations, each combination is a list of solvents, specified by their names. Corresponding .cosmo files must be found in the database, either the standard cosmotherm one or an additional, user-provided one.
melting_temperature_C (float | None) – The experimental melting temperature of the compound in degree Celsius. This can be used to determine the heat of fusion. Defaults to None, in this case no information on the melting temperature is passed to cosmotherm.
melting_enthalpy_kJ_per_mol (float | None) – The experimental melting enthalpy of the compound. This can be used to determine the heat of fusion. Defaults to None, in this case no information on the melting enthalpy is passed to cosmotherm.
level (str) – Level of theory. Defaults to “bp-tzvpd”.
references (list[ReferenceSolubility] | None) – List of reference solubilities. Defaults to None.
options (CosmoSettings) – Settings for the Cosmo task. Defaults to SOLUBILITY_SETTINGS.
solvents_dirs (list[Path] | None) – Additional directories to find the .cosmo files for the solvents. Defaults to None, i.e. just relying on the cosmotherm database. If additional directories are considered, the cosmotherm database is searched first, the the solvents_dirs.
temperature (float) – Temperature for the calculation in °C. Defaults to 25.
output_units (str) – Units for the output. Defaults to “wsolout_c lsolout_gl”. Check the cosmotherm documentation to see which strings can be used.
num_steps_binary (int) – Number of steps for binary mixtures. Defaults to NUM_STEPS_BINARY_MIXTURE.
num_steps_ternary (int) – Number of steps for ternary mixtures. Defaults to NUM_STEPS_TERNARY_MIXTURE.
optimize (bool) – Whether to ask cosmotherm to ptimize the mixture ratios. Note that in this case no mixture ratios will be screened. Defaults to False.
n_cores (int) – Number of cores to use for the calculation. Defaults to 1.
use_config_cosmo_dir (bool) – Whether to prepend the solvent directories from the software configuration file to the user-provided solvents_dirs. If False, only the user-provided directories are used. Defaults to True.
**kwargs – Additional keyword arguments for the output reader.

Returns:

A DataFrame containing the results of the solubility calculation.

Return type:

References

qm_atlas.wrappers.cosmotherm.cosmo_solubility.extract_molar_weights(sol_df)[source]¶

Extracts molar weights of pure solvents from the output dataframe of a: Cosmotherm solubility calculation for multiple solvents. The molar weights are read from those rows where a pure solvent is used.

Parameters:: sol_df (DataFrame) – The output dataframe of a solubility calculation
Returns:: Mapping solvent names to their molar weights
Return type:: dict[str, float]

qm_atlas.wrappers.cosmotherm.cosmo_solubility.parse_solvent_row(row_entry)[source]¶

Parses a row entry from a Cosmotherm solubility calculation output. The row entry has the form “solvent_1 solvent_2 X ={ frac_1 frac_2 }” for a binary mixture, but ternatry mixtures or pure solvents are handled as well.

Parameters:: row_entry (str) – A single solvent row from the cosmotherm solubility output.
Returns:: A list of solvent names list[float]: The corresponding molar fractions
Return type:: tuple[list[str], list[float]]

qm_atlas.wrappers.cosmotherm.cosmo_solubility.calculate_mass_fractions(molar_fractions, molar_weights)[source]¶

Converts molar fractions to mass fractions given the molar weights of the components.

Parameters:

molar_fractions (list[float]) – Molar fractions of the components
molar_weights (list[float]) – Molar weights of the components

Returns:

Mass fractions of the components

Return type:

list[float]

qm_atlas.wrappers.cosmotherm.cosmo_solubility.parse_solubility_data(sol_df, num_solvents=2)[source]¶

Parses the output dataframe of a cosmotherm solubility calculation to obtain: a more readable version for binary or ternary mixtures. The cosmotherm solvent row has the form “solvent_1 solvent_2 X ={ frac_1 frac_2 }” this is converted to two (or more) additional columns containing the names, molar fractions and mass fractions of the mixtures.

Parameters:

sol_df (DataFrame) – The output dataframe of a solubility calculation
num_solvents (int) – The maximum number of pure solvents in the mixtures. Defaults to 2.

Raises:

ValueError – If there are more solvents in a mixture than the specified maximum.

Returns:

The parsed dataframe

Return type:

qm_atlas.wrappers.cosmotherm.cosmo_solubility.SOLUBILITY_SETTINGS = CosmoSettings(action_lines=[], command_lines=['unit notempty ehfile wtln'], comment_line='!! solubility calculation !!')¶

list[str], comment_line: str)

Type:: CosmoSettings(action_lines
Type:: list[str], command_lines

qm_atlas.wrappers.cosmotherm.cosmo_solubility.NUM_STEPS_BINARY_MIXTURE = 11¶

qm_atlas.wrappers.cosmotherm.cosmo_solubility.NUM_STEPS_TERNARY_MIXTURE = 7¶

Jaguar¶

qm_atlas.wrappers.jaguar.bond_dissociation.split_dict(input_dict, chunk_size)[source]¶

Yield successive chunks of input_dict with at most chunk_size items each.

Return type:

Iterable[dict]

Parameters:

input_dict (dict)
chunk_size (int)

qm_atlas.wrappers.jaguar.bond_dissociation.get_hydrogen_abstraction_energies(mol, conf_id=0, atom_idcs='C', geo_opt_settings=None, single_point_settings=None, jaguar_options=None, n_cores=1, scr=DEFAULT_SCR, keep_files=False, license_buffer=40, license_timeout=2880)[source]¶

Calculates Hydrogen Abstraction Energies using the Jaguar script h_abstraction.py

Parameters:

mol (Mol) – The molecule to work on.
atom_idcs (list[int] | str) – The indices of the heavy atoms to abstract hydrogen atoms from. Can be a list of integers, “C” (all carbons), “N” (all nitrogens), “C,N” (both) or the key of a property set of the molecule containing these indices as a json-encoded list.
conf_id (int) – The conformer ID of the conformer to consider. Defaults to 0.
geo_opt_settings (dict[str, str] | None) – Settings for the geomtry optimization. For example, to change the functional, specify {“dftname”: “b3lyp”}, to change the basis {“basis”: “lacvp*”}, and the scf convergence criterion {“econv”: “4.0e-05”}. Defaults to None, resulting in jaguar defaults (b3lyp, lacvp*, 5.e-5 scf convergence)
single_point_settings (dict[str, str] | None) – Options for the single point energy calculations. Defaults to None, resulting in jaguar defaults.
jaguar_options (dict[str, str] | None) – Additional options to run jaguar calculations. Defaults to None.
n_cores (int) – The number of cores to use. Defaults to 1.
scr (Path) – The scratch directory to use for temporary files. Defaults to DEFAULT_SCR.
keep_files (bool) – whether to keep that scratch directory after the calculation has run. Defaults to False.
license_buffer (int) – A buffer of licenses to leave. Defaults to 40.
license_timeout (int) – How long to wait for a license (in minutes). Defaults to 2880 (2 days).

Raises:

RuntimeError – If the calculation fails or the output file cannot be found.

Returns:

A dictionary containing the calculated hydrogen abstraction energies for the specified heavy atoms, as an AtomBasedProperty object.

Return type:

qm_atlas.wrappers.jaguar.bond_dissociation.run_jaguar_hydrogen_abstraction(mol, heavy_to_hydrogen_idx, conf_id=0, geo_opt_settings=None, single_point_settings=None, jaguar_options=None, n_cores=1, scr=DEFAULT_SCR, keep_files=False, license_buffer=40, license_timeout=2880)[source]¶

Run the Jaguar h_abstraction workflow for the given heavy->hydrogen atom pairs.

Return type:

Parameters:

mol (Mol)
heavy_to_hydrogen_idx (dict[int, int])
conf_id (int)
geo_opt_settings (dict[str, str] | None)
single_point_settings (dict[str, str] | None)
jaguar_options (dict[str, str] | None)
n_cores (int)
scr (Path)
keep_files (bool)
license_buffer (int)
license_timeout (int)

qm_atlas.wrappers.jaguar.bond_dissociation.get_idx_map(mol, atom_idcs)[source]¶

Map each heavy-atom index in atom_idcs to the index of one attached hydrogen.

Return type:

dict[int, int]

Parameters:

mol (Mol)
atom_idcs (list[int])

qm_atlas.wrappers.jaguar.bond_dissociation.parse_h_abs_out(out_file, heavy_to_hydrogen_idx)[source]¶

Parse a Jaguar h_abstraction output file into a mapping of heavy-atom index to energy.

Return type:

dict[int, float]

Parameters:

out_file (Path)
heavy_to_hydrogen_idx (dict[int, int])

qm_atlas.wrappers.jaguar.qm_descriptors.calculate_descriptors(mol, conf_id, properties=DEFAULT_PROPERTIES, basis=DEFAULT_BASIS, functional=DEFAULT_FUNCTIONAL, jaguar_options=None, n_cores=1, scr=DEFAULT_SCR, keep_files=False, license_buffer=40, license_timeout=2880)[source]¶

Wrapper function for jaguar property calculations, runs the qm_descriptors.py script in jaguar. The Fukui index calculations are done according to the method described in References [1], [2].

Parameters:

mol (Mol) – The molecule to work on.
properties (Sequence[str]) – The properties to calculate, options are any combination of “fukui”, “nmr”, and “lowdin” (for Lowdin partial charges).
basis (str) – The basis set to use for the calculation. Defaults to DEFAULT_BASIS (LACVP*).
functional (Sequence[str]) – The functional to use. Defaults to DEFAULT_FUNCTIONAL (b3lyp-d3).
conf_id (int) – The conformer to consider, specify the confId for the mol. Defaults to 0.
jaguar_options (dict[str, str] | None) – Additional options for the jaguar run. Defaults to None.
n_cores (int) – How many cpus to use. Defaults to 1.
scr (Path) – A scratch directory to use. Defaults to DEFAULT_SCR.
keep_files (bool) – whether to keep that scratch directory after the calculation has run. Defaults to False.
license_buffer (int) – A buffer of licenses to leave. Defaults to 40.
license_timeout (int) – How long to wait for a license (in minutes). Defaults to 2880 (2 days).

Raises:

RuntimeError – If the calculation fails or the output file cannot be found.

Returns:

A dictionary mapping the keys for the calculated properties to the arrays holding these (atom-based) properties.

Return type:

References

[1]: Contreras, R. R.; Fuentealba, P.; Galvan, M.; Perez, P. “A direct evaluation of regional Fukui functions in molecules”, Chem. Phys. Lett. 1999, 304, 405, https://doi.org/10.1016/S0009-2614(99)00325-5

[2]: Chamorro, E.; Perez, P. “Condensed-to-atoms electronic Fukui functions within the framework of spin-polarized density-functional theory”, J. Chem. Phys. 2005, 123, 114107, https://doi.org/10.1063/1.2033689

qm_atlas.wrappers.jaguar.qm_descriptors.parse_descriptors(sdf_file, property_keys)[source]¶

Read per-atom descriptor properties from an SDF file into AtomBasedProperty objects.

Return type:

Parameters:

sdf_file (Path)
property_keys (list[str])

qm_atlas.wrappers.jaguar.qm_descriptors.DEFAULT_BASIS = 'LACVP*'¶

qm_atlas.wrappers.jaguar.qm_descriptors.DEFAULT_FUNCTIONAL = ('b3lyp-d3',)¶

qm_atlas.wrappers.jaguar.common.convert_to_mae(sdf_file)[source]¶

Convert an SDF file to Schrödinger .mae format via Jaguar’s structconvert.

Parameters:: sdf_file (Path)

qm_atlas.wrappers.jaguar.common.prepare_jaguar_input(mol, conf_id=0, scr=DEFAULT_SCR, keep_files=False)[source]¶

Write mol to a scratch directory and convert it to a Jaguar .mae input file.

Return type:

tuple[WorkDir, Path]

Parameters:

mol (Mol)
conf_id (int)
scr (Path)
keep_files (bool)

qm_atlas.wrappers.jaguar.common.extract_log_file(scr)[source]¶

Log the contents of the single .log file found in scr (for error reporting).

Return type:: None
Parameters:: scr (Path)

MoKa¶

qm_atlas.wrappers.moka.blabber.get_protonation(molobj, scr=constants.DEFAULT_SCR, filename=BLABBER_FILENAME, remove_zero_charged=False, keep_files=False, **kwargs)[source]¶

Enumerate protonation states of molobj with MoKa Blabber and return them as molecules.

Return type:

list[Mol]

Parameters:

molobj (Mol)
scr (Path)
filename (str | Path)
remove_zero_charged (bool)
keep_files (bool)

qm_atlas.wrappers.moka.blabber.get_protonation_from_sdf(sdfstr, cmd=BLABBER_CMD, scr=constants.DEFAULT_SCR, threshold=BLABBER_THRESHOLD, model=USE_DEFAULT_MODEL, ph=BLABBER_PH, use_tempfile=True, keep_files=False)[source]¶

Run MoKa Blabber on an SDF string and return the protonated species as SDF strings.

Return type:

list[str]

Parameters:

sdfstr (str)
cmd (str)
scr (Path)
threshold (int | None)
model (Path | None)
ph (float)
use_tempfile (bool)
keep_files (bool)

qm_atlas.wrappers.moka.blabber.generate_sdfs(lines)[source]¶

Generate SDF strings from lines of strings

Return type:: Iterator[str]
Parameters:: lines (list[str])

class qm_atlas.wrappers.moka.moka.PkaTypes[source]¶

ACIDIC = 'a'¶

BASIC = 'b'¶

class qm_atlas.wrappers.moka.moka.PredictedPKA(value, pka_type, atom_index, standard_deviation=None)[source]¶

Parameters:

value (float)
pka_type (str)
atom_index (int | None)
standard_deviation (float | None)

value: float¶

pka_type: str¶

atom_index: int | None¶

standard_deviation: float | None = None¶

get_moka_string()[source]¶

Return type:: str

get_moka_std()[source]¶

Return type:: float

class qm_atlas.wrappers.moka.moka.MokaPrediction(name, covalent_hydration, unstable_tautomer, num_centers, predicted_pkas)[source]¶

Parameters:

name (str)
covalent_hydration (str)
unstable_tautomer (bool | None)
num_centers (int)
predicted_pkas (list[PredictedPKA])

name: str¶

covalent_hydration: str¶

unstable_tautomer: bool | None¶

num_centers: int¶

predicted_pkas: list[PredictedPKA]¶

get_moka_line()[source]¶

Return type:: str

qm_atlas.wrappers.moka.moka.parse_moka_output(line)[source]¶

Parses a line of MoKa output and returns a MokaPrediction object.

Return type:: MokaPrediction
Parameters:: line (str)

Format is: NAME CH UT IC ( a|b PK ATOM SD [QP] ) * IC: NAME - the molecule name (may contain spaces) CH - covalent hydration flag: 0 (false) or 1 (true) UT - unstable tautomer flag: 0 (false), 1 (true) or - (not computed) IC - number of ionizable centers
Then, for each ionizable center:: a|b - type of ionizable center (acid or basic) PK - predicted pKa value ATOM - atom number SD - standard deviation of prediction QP - quality parameter (optional, older versions)

The molecule name may contain spaces. Recent MoKa versions wrap it in double quotes; older versions do not, in which case the header is located by anchoring on the ionizable-center markers.

qm_atlas.wrappers.moka.moka.get_moka_version(cmd=None)[source]¶

Get the version string of MoKa.

Return type:: str
Parameters:: cmd (str | None)

qm_atlas.wrappers.moka.moka.moka_version_is_v5(cmd=None)[source]¶

Return True if the configured MoKa executable is version 5.x.

Return type:: bool
Parameters:: cmd (str | None)

qm_atlas.wrappers.moka.moka.run_moka_sdf(sdf_file, cmd=None, model=USE_DEFAULT_MODEL, lower_ph_threshold=None, upper_ph_threshold=None)[source]¶

Run MoKa on an SDF file and return the results.

Return type:

dict[str, MokaPrediction]

Parameters:

sdf_file (Path)
cmd (str | None)
model (Path | None)
lower_ph_threshold (float | None)
upper_ph_threshold (float | None)

qm_atlas.wrappers.moka.moka.get_moka_prediction_on_batch(molecules, cmd=None, model=USE_DEFAULT_MODEL, scr=constants.DEFAULT_SCR, lower_ph_threshold=None, upper_ph_threshold=None, chunk_size=100, keep_files=False)[source]¶

Run MoKa pKa prediction on a batch of molecules.

Writes the molecules to a temporary SDF file, runs MoKa, and returns the results as a dict mapping molecule name to MokaPrediction.

Return type:

dict[str, MokaPrediction]

Parameters:

molecules (list[Mol])
cmd (str | None)
model (Path | None)
scr (Path)
lower_ph_threshold (float | None)
upper_ph_threshold (float | None)
chunk_size (int)
keep_files (bool)

qm_atlas.wrappers.moka.moka.get_moka_prediction(mol, cmd=None, model=USE_DEFAULT_MODEL, scr=constants.DEFAULT_SCR, lower_ph_threshold=None, upper_ph_threshold=None, keep_files=False)[source]¶

Run MoKa pKa prediction on a single molecule.

Parameters:

mol (Mol) – RDKit molecule to predict pKa values for.
cmd (str | None) – MoKa command to use. Defaults to the command from SOFTWARE_CONFIG.
model (Path | None) – Path to a custom MoKa model. Defaults to the model from SOFTWARE_CONFIG. Pass None to use MoKa’s built-in model.
scr (Path) – Scratch directory for temporary files.
lower_ph_threshold (float | None) – Lower pH limit for basic centers.
upper_ph_threshold (float | None) – Upper pH limit for acidic centers.
keep_files (bool) – Whether to keep the temporary files. Used for debugging. Defaults to False.

Return type:

MokaPrediction

Returns:

MokaPrediction with the predicted pKa values.

class qm_atlas.wrappers.moka.process.PkaCenter(center_type, index, pka_value, parent_name=None, child_name=None)[source]¶

Parameters:

center_type (str)
index (int)
pka_value (float)
parent_name (str | None)
child_name (str | None)

center_type: str¶

index: int¶

pka_value: float¶

parent_name: str | None = None¶

child_name: str | None = None¶

is_relevant(lower_ph, upper_ph)[source]¶

checks if the affects the ionization states to be considered for a given pH range. If the pka_value is nan, it is considered to be relevant. :param lower_ph: The lower pH value :type lower_ph: float :param upper_ph: The upper pH value :type upper_ph: float

Returns:

True if the pKa center is in the given pH range

Return type:

Parameters:

lower_ph (float)
upper_ph (float)

is_in_ph_range(lower_ph, upper_ph)[source]¶

checks if the pKa center is in the given pH range. If the pka value is nan, it is considered to be in the range. :param lower_ph: The lower pH value :type lower_ph: float :param upper_ph: The upper pH value :type upper_ph: float

Returns:

True if the pKa center is in the given pH range

Return type:

int

Parameters:

lower_ph (float)
upper_ph (float)

qm_atlas.wrappers.moka.process.get_pka_centers_from_arrays(center_types, centers, pkas)[source]¶

Get a list of PkaCenter objects from the given arrays. The arrays are expected to be of the same length.

Parameters:

center_types (Iterable[str]) – The types of the centers (“a” for acid, “b” for base)
centers (Iterable[int]) – The atom indices of the centers
pkas (Iterable[float]) – The pKa values of the centers

Returns:

A list of PkaCenter objects

Return type:

list[PkaCenter]

class qm_atlas.wrappers.moka.process.PkaCalculationInfo(compound_name)[source]¶

Parameters:: compound_name (str)

name_to_mol: dict[str, tuple[Mol, bool]]¶

pka_centers: dict[int, PkaCenter]¶

is_contained(mol)[source]¶

checks if the molecule is contained in the dictionary of compounds

Return type:: bool
Parameters:: mol (Mol)

add_compound(mol, require_conformer_expansion=True)[source]¶

adds a compound to the dictionary of compounds

Return type:

Parameters:

mol (Mol)
require_conformer_expansion (bool)

add_pka_center(pka_center, parent_compound, child_compound, require_conformer_expansion=True)[source]¶

adds a pKa center to the class

Return type:

None

Parameters:

pka_center (PkaCenter)
parent_compound (Mol)
child_compound (Mol)
require_conformer_expansion (bool)

qm_atlas.wrappers.moka.process.generate_ionic_species(mol, pka_centers, lower_ph_threshold=-np.inf, upper_ph_threshold=np.inf)[source]¶

Determine the ionic species of the molecule based on the provided pka centers. Proceeds in order of the pKa values, protonating the basic centers and deprotonating the acidic centers. The species to be generated can thus have multiple charges, each charge appearing only once.

Parameters:

mol (Mol) – The molecule to be ionized
pka_centers (list[PkaCenter]) – a list of pKa centers, each with a type, and atom index, and a pKa value.
lower_ph_threshold (float) – Only consider pKa centers relevant at or above this pH. Defaults to -inf.
upper_ph_threshold (float) – Only consider pKa centers relevant at or below this pH. Defaults to inf.

Returns:

A PkaCalculationInfo object containing the: information needed for downstream pKa calculations.

Return type:

PkaCalculationInfo

qm_atlas.wrappers.moka.process.generate_single_charge_ions(mol, pka_centers, lower_ph_threshold=-np.inf, upper_ph_threshold=np.inf)[source]¶

Determine the ionic species of the molecule based on the provided pka centers. The function (de-)protonates each center separately, generating a singly charged ion for each center. The function does not take into account the pKa values of the centers.

Parameters:

mol (Mol) – The molecule to be ionized
pka_centers (list[PkaCenter]) – a list of pKa centers, each with a type, and atom index, and a pKa value.
lower_ph_threshold (float) – Only consider pKa centers relevant at or above this pH. Defaults to -inf.
upper_ph_threshold (float) – Only consider pKa centers relevant at or below this pH. Defaults to inf.

Returns:

A PkaCalculationInfo object containing all the: information needed for downstream pKa calculations.

Return type:

PkaCalculationInfo

qm_atlas.wrappers.moka.process.get_charge_suffix(mol)[source]¶

assigns rescoss suffix to a charge: _A for charge -1, _AA for -2, _BH for +1, _BHH for +2 and so on.

Return type:: str
Parameters:: mol (Mol)

MacroModel¶

qm_atlas.wrappers.macromodel.generate_conformers(mol, license_buffer=1, license_timeout=60, scr=DEFAULT_SCR, keep_files=False, **conf_gen_kwargs)[source]¶

Generate Conformers using Macromodel.

Parameters:

mol (Mol) – The molecule to work on.
license_buffer (int) – The number of licenses to leave available. Defaults to 2.
license_timeout (int) – The number of minutes to spend waiting for a license. Defaults to 60.
scr (Path) – The scratch space to use. Defaults to DEFAULT_SCR.
keep_files (bool) – Whether to keep the temporary files. Used for debugging. Defaults to False.
**conf_gen_kwargs – Additional MacroModel conformer-search parameters forwarded to setup_mm_conf().

Raises:

RuntimeError – If the conformer generation fails or no output file is produced.

Returns:

An rdkit mol with conformers.

Return type:

qm_atlas.wrappers.macromodel.generate_macrocycle_conformers(mol, license_buffer=1, license_timeout=60, scr=DEFAULT_SCR, keep_files=False, max_conformers=1000, energy_cutoff=30.0, rms_threshold=0.3, num_cores=1, **conf_gen_kwargs)¶

Generate Conformers using Schrodinger macrocycle script.

Parameters:

mol (Mol) – The molecule to work on.
license_buffer (int) – The number of licenses to leave available. Defaults to 1.
license_timeout (int) – The number of minutes to spend waiting for a license. Defaults to 60.
scr (Path) – The scratch directory to use. Defaults to DEFAULT_SCR.
keep_files (bool) – Whether to keep the intermediate files. Defaults to False.
max_conformers (int) – The maximum number of conformers to generate. Defaults to 1000.
energy_cutoff (float) – The energy cutoff in kcal/mol. Defaults to 30.0.
rms_threshold (float) – The RMS threshold in Angstroms. Defaults to 0.3.
num_cores (int) – The number of cores to use. Defaults to 1.
**conf_gen_kwargs – Additional keyword arguments to pass to the macrocycle script. Keys and Values will be converted to command line arguments.

Raises:

RuntimeError – If the conformer generation fails or no output file is produced.

Returns:

An rdkit mol with conformers.

Return type:

qm_atlas.wrappers.macromodel.utils.log_macromodel_errors(scr)[source]¶

Scan the Macromodel log files in a scratch directory for known error indicators and log a plausible reason for a failed conformer generation.

Parameters:: scr (Path) – The scratch directory containing the Macromodel log files.
Return type:: None

qm_atlas.wrappers.macromodel.utils.convert_to_mae(sdf_file)[source]¶

Convert an SDF file to Schrödinger .mae format via MacroModel’s structconvert.

Parameters:: sdf_file (Path)

MOE¶

qm_atlas.wrappers.moe.generate_conformers(mol, scr=DEFAULT_SCR, keep_files=False, **conf_gen_kwargs)[source]¶

Generate Conformers using MOE.

Parameters:

mol (Mol) – The molecule to work on.
scr (Path) – The scratch space to use. Defaults to DEFAULT_SCR.
keep_files (bool) – Whether to keep the temporary files. Used for debugging. Defaults to False.
**conf_gen_kwargs – Additional MOE conformer-search parameters forwarded to setup_moe_conf().

Raises:

RuntimeError – If the conformer generation fails or no output file is produced.

Returns:

An rdkit mol with conformers. Returns None if an error is raised.

Return type:

OpenEye Omega¶

qm_atlas.wrappers.openeye.get_omega_command(is_macrocycle=False, software_env_manager=None)[source]¶

Determine which omega command to use based on whether the molecule contains a macrocycle.

Parameters:

is_macrocycle (bool) – Whether to use the macrocycle-specific omega command. Defaults to False.
software_env_manager – An optional environment manager; resolved from the software config when None.

Returns:

The command to execute omega.

Return type:

qm_atlas.wrappers.openeye.generate_input_mol(molobj, start_from_corina=False)[source]¶

Generate input molecule for omega conformer generation. If the input molecule has hydrogens and 3D coordinates, we use it directly. Otherwise, if start_from_corina is True, we use corina to generate 3D coordinates. If start_from_corina is False, we use rdkit to add hydrogens and generate 2D coordinates.

Parameters:

molobj (Mol) – The rdkit Mol
start_from_corina (bool) – Whether to use corina to generate a 3d input conformation. Note that corina is only used if the input is not already 3d. Defaults to False, in this case, we use rdkit to generate a 3d input conformation

Returns:

The molecule to be used as input to omega, and a boolean indicating whether the molecule is 2D (True) or 3D (False).

Return type:

tuple[Mol, bool]

qm_atlas.wrappers.openeye.generate_conformers_molobj(molobj, scr=constants.DEFAULT_SCR, keep_files=False, start_from_corina=False, max_conformers=None, rms_threshold=None, n_cores=1)[source]¶

Main Wrapper for OpenEye Omega Conformer Generation. The function will call oeomega classic or oeomega macrocycle (if appropriate) to generate conformations for the input molecule.

Parameters:

molobj (Mol) – The rdkit Mol
scr (Path) – The scratch directory to use for temporary files. Defaults to DEFAULT_SCR.
keep_files (bool) – Whether to keep the temporary files. Defaults to False. Useful for debugging.
start_from_corina (bool) – Whether to use corina to generate a 3d input conformation. Note that corina is only used if the input is not already 3d. Defaults to False, in this case, we use rdkit to generate a 3d input conformation
max_conformers (int | None) – The maximum number of conformers to generate. If None, omega’s default is used.
rms_threshold (float | None) – The RMS threshold for conformer filtering. If None, omega’s default is used.
n_cores (int) – The number of cores to use for omega. Defaults to 1.

Raises:

RuntimeError – If the omega conformer generation fails.

Returns:

The molecule with all the conformers generated by Openeye Omega.

Return type:

qm_atlas.wrappers.openeye.check_error(filename)[source]¶

Reads the log file and returns any error messages found.

Parameters:: filename (Path) – The path to the log file to be checked.
Returns:: The error messages found in the log file, prefixed with “log:”.
Return type:: str

CORINA¶

CORINA 3D structure generator command-line reference.

The text below is the verbatim CORINA command-line help, kept here for reference.

NAME
corina - 3D structure generator
(All rights Molecular Networks GmbH, www.mn-am.com)

SYNOPSIS
corina [options] [infile [outfile]]

OPTIONS
Options follow the UNIX command line convention: -o [suboption[=value],...]
I.e., options start with a `-' and are separated by spaces.
Suboptions may have values and can be concatenated by commas.
Example: corina -n f=42,t=43 < in > out

-i - Input file type and options
    t=<value> - File type (sdf, rdf, smiles, mol2, mol, ctx, mmod, mae, inchi)
    sdfi2n=<value> - Copy data item <value> to name (sdf)
    sdfi2c=<value> - Copy data item <value> to comment (sdf)
    dummies - Allow dummy atom types (smiles/sdf/mol/mol2)
    sdfict - Ignore E/Z configurations from 2D coordinates (sdf)
    expandapo - Expand attachment points "M  APO" (sdf)
    force3d - Force 3D from 2D (sdf)
    csdmol2 - Allow CSD MOL2 extensions (mol2)
    xelement - Allow extra elements (mol2)
    sc#=<value> - Read structure from column number <value> (smiles/InChI)
    scn=<value> - Read structure from column number <value> (smiles/InChI) - same as sc#
    nc#=<value> - Read name from column number <value> (smiles/InChI)
    ncn=<value> - Read name from column number <value> (smiles/InChI) - same as nc#
    cc#=<value> - Read comment from column number <value> (smiles/InChI)
    ccn=<value> - Read comment from column number <value> (smiles/InChI) - same as cc#
    sep=<value> - Provide input file column separator character (smiles/InChI)
-o - Output file type and options
    t=<value> - File type (sdf, sdf2, sdf3, rdf, rdf2, rdf3, mol, mol2, pdb,
    ctx, mmod, mae, top, par, odb, cif, dic, dyana, mopacxyz)

    a - Append output to output file
    pascom - Pass comment from input to output
    mdldb - Write additional data fields in SDFiles for MDL databases (sdf)
    mdlcompact - Write compact SDFiles (sdf)
    mdl3dparity - Add atom stereo parities (sdf)
    lname - Allow long names >80 char. (sdf)
    mdlbond4 - Write aromatic bonds as bond type "4" (sdf)
    sdfn2i=<value> - Write name into data item <value> (sdf)
    sdfc2i=<value> - Write comment into data item <value> (sdf)
    sdfs2i=<value> - Write structure (smiles/InChI)) into data item <value> (sdf)
    gold - Assign atom and bond types required by GOLD (mol/mol2)
    m2l - Add isotopic mass labels to atom names (mol/mol2)
    noccat - Suppress automatic amidinium conversion to C.cat (mol/mol2)
    fcharges - Write formal charges into the partial charge column (mol2)
    nodummies - Suppress writing of records with dummy atoms (mol/mol2)
    xelement - Allow extra elements (mol2)
    pdbatom - Write ATOM instead of HETATM keyword (pdb)
    pdbnoconect - Skip CONECT statements (pdb)
    pdbludi - Create input file for Ludi fragment database (pdb)
    pdbludilabel - Generate unique labels for Ludi fragments (pdb)
    pdbelement - Add atomic element symbol to HETATM/ATOM lines (PDB V2.3)
    resnam=<value> - Set residue name to <value> (pdb/mmod/mae/top/dic/cif/odb/dyana)
    resno=<value> - Set residue number to <value> (pdb/mmod/mae/dyana)
    keepnames - Keep any given atom names (pdb/dyana)
    typchr=<value> - Set atom type character(s) to <value> (top/par)
    dicid=<value> - Set group ID number to <value> (dic)
    novar - No variable torsions (cif)
    multor - Multiple torsions (cif)
    coplan - Set strict restraints for coplanar methoxy groups at aromatic rings (cif)
    chirvol - Set chiral volume to value "both" at flexible ring systems
    hlabel - Label hydrogen atoms separately (pdb, cif)
    xlabel - Label each atom type separately by applying extended schema [0-9;A-Z] (pdb/cif/mmod/maestro)
    flexrta - Set flexible TAs for aliphatic ring systems (size > 4, cif)
    mopackeys=<value> - Write MOPAC keywords '<value>' (mopacxyz, '<value>' to be quoted)
    mopacaddchg - Calculate and add MOPAC CHARGE keyword automatically (mopacxyz)
    mopacoptflag=<value> - Write MOPAC optimization flag <value> (mopacxyz)
    split - Split output to single structure files, number output file names consecutively
    splitn0=<value> - Split output to single structure files, number output file names consecutively with <value> leading '0's
-t - Trace
    s - Write trace output to stderr
    n - Suppress trace output
    tracefile=<value> - Set tracefile name to <value>
-n - Record number
    n=<value> - Process only record <value>
    f=<value> - Process all records from <value>
    t=<value> - Process all records to <value>
-d - CORINA driver options
    wh - Write added hydrogen atoms
    rs - Remove small fragments (counter ions, solvent molecules, etc.)
    neu - Neutralize charges of [C,S,P]-[O-], [NH+] and S=O(=O)[N-]
    maxat=<value> - Change maximum number of atoms (default 999)
    flexx - Set all parameters to interface to FlexX
    axchir - Process potential stereogenic axes for handling of axial chirality
    stergen - Generate stereo isomers
    msc=<value> - Set maximum number of processed stereo centers to <value> (-d stergen)
    msi=<value> - Set maximum number of output stereoisomers to <value> (-d stergen)
    preserve - Preserve defined stereo centers (-d stergen)
    preserverel - Preserve relative stereochemistry of defined stereo centers (-d stergen)
    chiralflag - Preserve defined stereo centers if chiral flag is set (sdf, -d stergen)
    v3000 - Permute stereo centers and groups according to SD V3000 specifications (-d stergen)
    noflapn - Do not flap pyramidal nitrogens (-d stergen)
    rc - Generate multiple ring conformations
    mc=<value> - Set maximum number of conformations to <value> (-d rc)
    de=<value> - Set energy window delta E for multiple conformations to <value> kJ/mol (-d rc)
    timeout=<value> - Set timeout for multiple conformations to <value> ms (-d rc)
    flapn - Flap pyramidal ring nitrogen in multiple conformations (-d rc)
    sc - Generate multiple ring conformations "simultaneously" (-d rc)
    symoff - Suppress symmetry check for conformations (-d rc)
    ringatom=<value> - Denote ring system for conformation analysis by atom <value> (-d rc)
    ampax - Amplify energy penalty for axial ring substituents
    planil - Force anilinic ring nitrogen atoms to planar geometry
    sanpyr - Force pyramidal geometry of sulfonamide nitrogen atoms (default: planar)
    names - Append conformer/isomer count to compound names (-d rc,stergen)
    r2d - Remove 2D records (failure cases) from the output
    wb - Write also "bad" 3D models having close contacts
    no3d - Suppress 3D generation process (file conversion only)
    ori - Orient 3D structures according to their moments of inertia
    ist - Ignore all stereo information
    i3dst - Ignore stereo information derived from 3D structure given in input file
    ow - Override wedge symbols at stereo centers that have also stereo flag set
    amide - Generate amide bonds with configuration given in input file
    3dst - Force stereo descriptors from 3D structure given in input file
    newtypes - Generate new atom types, ignore any given type and aromaticity
    errorfile=<value> - Name of a file containing all erroneous molecules (sdf/smiles/InChI)
-v - Version
-h - This help
-h <o> | all - Details for option <o> or for all options.
-m - write man page to stdout

qm_atlas.wrappers.corina.generate_conformers_molobj(mol, corina_cmd=None, corina_driveropt=CORINA_DRIVEROPT, scr=constants.DEFAULT_SCR, keep_files=False)[source]¶

Generate a 3D conformer for a molecule using CORINA.

Parameters:

mol (Mol) – The rdkit Mol to generate a conformer for.
corina_cmd (str | None) – The command to use for corina. If None, the command is resolved from the software configuration.
corina_driveropt (str) – The CORINA driver options string. Defaults to CORINA_DRIVEROPT.
scr (Path) – The scratch directory to use for temporary files. Defaults to DEFAULT_SCR.
keep_files (bool) – Whether to keep the temporary files. Defaults to False. Useful for debugging.

Raises:

RuntimeError – If the CORINA conformer generation fails.

Returns:

The molecule with the 3D conformer generated by CORINA.

Return type:

qm_atlas.wrappers.corina.CORINA_DRIVEROPT = '-d wh,stergen,noflapn,preserve,chiralflag,msc=2'¶

UniCon¶

qm_atlas.wrappers.unicon.get_tautomers(mol, scr=constants.DEFAULT_SCR, keep_files=False, return_canonical=True, cmd=None)[source]¶

Generate tautomers for a molecule using UNICON. See references [1], [2] for details on the UNICON tautomer generation algorithm.

Parameters:

mol (Mol) – The rdkit Mol to generate tautomers for.
scr (Path) – The scratch directory to use for temporary files. Defaults to DEFAULT_SCR.
keep_files (bool) – Whether to keep the temporary files. Defaults to False. Useful for debugging.
return_canonical (bool) – Whether to return canonical SMILES for the generated tautomers. Defaults to True.
cmd (str | None) – The command to use for unicon. If None, the command is resolved from the software configuration.

Raises:

RuntimeError – If the UNICON tautomer generation fails.

Returns:

A list of rdkit Mol objects representing the generated tautomers.

Return type:

list[Mol]

References

[1] Sommer, K., Friedrich, N.-O., Bietz, S., Hilbig, M., Inhester, T. & Rarey, M. UNICON: A Powerful and Easy-to-Use Compound Library Converter. J. Chem. Inf. Model. 56, 1105-1111 (2016). https://doi.org/10.1021/acs.jcim.6b00069

[2] Urbaczek, S., Kolodzik, A. & Rarey, M. The Valence State Combination Model: A Generic Framework for Handling Tautomers and Protonation States. J. Chem. Inf. Model. 54, 756-766 (2014). https://doi.org/10.1021/ci400724v

Shared utilities¶

qm_atlas.wrappers.common.write_xyz(mol, output_xyz, conf_id=-1)[source]¶

Writes an xyz file from a molecule.

Parameters:

mol (Mol) – The molecule
output_xyz (Path | str) – The xyz file to be created
conf_id (int) – The conformer ID to consider. Defaults to -1.

qm_atlas.wrappers.common.read_xyz_coordinates(xyz_file)[source]¶

Read atomic symbols and coordinates from an XYZ file.

Parses a standard XYZ format file and extracts the atomic symbols and their 3D coordinates.

Parameters:: xyz_file (Path) – Path to XYZ file to read
Returns:: A tuple (symbols, coordinates) where symbols is the list of element symbols (strings) in order of appearance and coordinates is a numpy array of shape (n_atoms, 3) with atomic coordinates in Angstrom units.
Return type:: tuple[list[str], ndarray]

Examples

>>> symbols, coords = read_xyz_coordinates("molecule.xyz")
>>> print(len(symbols))  # Number of atoms
>>> print(coords.shape)  # (n_atoms, 3)
>>> print(coords[0])  # Coordinates of first atom in Angstrom

qm_atlas.wrappers.common.run_command(command, env=None, timeout=None, cwd=None)[source]¶

Runs a shell command

Parameters:

command (str) – The command to run
env (dict[str, str] | None) – Environment variables to set. Defaults to None.
timeout (int | None) – Timeout in seconds. Defaults to None.
cwd (Path | str | None) – Working directory for the command. Defaults to None.

Raises:

RuntimeError – If the command fails or times out

Returns:

stdout and stderr from the command

Return type:

tuple[str, str]

qm_atlas.wrappers.helpers.ensure_local_job_server(software)[source]¶

Ensure the local Schrödinger job server is running, if configured.

Recent Schrödinger releases route local (sub)jobs through a per-user job server; anything that spawns Job Control subjobs (e.g. parallel Jaguar runs, macrocycle Prime-MCS sampling) fails with “Local job submission requires a locally running job server” when none is running. jsc local-server-start is idempotent and near-instant when the server is already up (~0.02 s), so we call it before every submission; this also self-heals if the server was stopped mid-run. Best-effort: if jsc is not configured or fails, we log and continue so the job’s own error surfaces.

Return type:: None
Parameters:: software (str)

qm_atlas.wrappers.helpers.check_licenses(software, feature_name, lic_cmd=None)[source]¶

Checks how many licenses are available

Parameters:

software (str) – the software whose license server to query
feature_name (str) – the feature (module) name to be searched in the output
lic_cmd (str | None) – the command to query the license server. Defaults to None.

Returns:

the number of licenses issued and the number in use.

Return type:

tuple[int, int]

qm_atlas.wrappers.helpers.wait_for_license(software, feature_name, lic_cmd=None, buffer=1, timeout=60)[source]¶

waits until a license is available

Parameters:

software (str) – The software whose license server to query.
buffer (int) – The number of licenses to leave as a buffer. Defaults to 1.
timeout (int) – The number of minutes after which to timeout. Defaults to 60.
lic_cmd (str | None) – The command to query the license server
feature_name (str) – The feature (module) name to be searched in the output

Raises:

TimeoutError – If a license did not become available in the allocated time.

returns None

qm_atlas.wrappers.helpers.read_conformers_as_mols(file)[source]¶

Reads a maegz or sdf file containing conformers of the same graph and returns them as a list of separate rdkit molecules (each with a single conformer).

Parameters:: file (Path) – The file in .sdf, .sdf.gz, .mae or .maegz format
Returns:: One rdkit molecule per conformer record in the file.
Return type:: list[Mol] | None

qm_atlas.wrappers.helpers.store_atom_map_numbers(mol)[source]¶

Store the atom map numbers in the molecule. These can be used to track: changes of atom indices after conformer generation.

Parameters:: mol (Mol) – The input molecule.
Returns:: A copy of the molecule with atom map numbers stored.
Return type:: Mol

qm_atlas.wrappers.helpers.map_conformers_onto_template(template_mol, generated_mols)[source]¶

Transfer the 3D coordinates of generated conformers back onto the original molecular graph.

Conformer generators may re-perceive the molecular graph (e.g. assign or remove a stereo center, reorder atoms). To guarantee that the graph is never changed, this function keeps the template_mol graph untouched and only copies the generated 3D coordinates onto it as new conformers.

Atoms in the generated molecules are matched to the template via atom map numbers, which must have been stored on the molecule passed to the conformer generator using store_atom_map_numbers(). If a generated atom carries no atom map number, its position is matched by atom index instead.

Parameters:

template_mol (Mol) – The molecule whose graph should be preserved. Its own conformers are ignored.
generated_mols (Iterable[Mol]) – The molecules produced by the conformer generator, each carrying a single conformer.

Returns:

A copy of template_mol carrying the generated conformers.

Return type: