Key API

This page collects the most commonly used functions of the Python API, grouped by module. It is a curated entry point — for the complete, generated documentation of every module see the API Reference (Full API Reference).

Tasks

Main entry points for individual calculation tasks. Wrappers for external programs are grouped here to provide a uniform interface. For each task, there are functions operating on a single conformation, all conformers of a molecule, or a batch of molecules. Only the functions that operate on a single molecule are listed here. This layer also has the configuration classes that select the backend and its options, these options classes are passed through to the workflows and the command-line interface.

Conformer generation

qm_atlas.tasks.conformer_generation.generate_conformers(mol, conformer_generation_options, num_cores=1, trace_dir=constants.DEFAULT_SCR, write_intermediates=False)

Main entry point for conformer generation. Dispatches to the appropriate method based on the combination_name.

Return type:

Mol | None

Parameters:

• mol (Mol)

• conformer_generation_options (ConformerGenerationOptions)

• num_cores (int)

• trace_dir (Path)

• write_intermediates (bool)

pydantic model qm_atlas.tasks.conformer_generation.ConformerGenerationOptions

Options for the generate_conformers task.

field conf_gens: list[Annotated[MacromodelOptions | OmegaOptions | MoeOptions | CorinaOptions | RdkitOptions | MacrocycleOptions, FieldInfo(annotation=NoneType, required=True, discriminator='backend')]] [Required]

List of conformer generator option objects to use. Each is a typed options object whose ‘backend’ field selects the generator.

field combination_name: Literal['joint_set', 'fallback'] = 'joint_set'

Method to combine multiple conformer generators: ‘joint_set’ or ‘fallback’

field rms_threshold: float = 0.3

RMSD threshold for deduplication of joint conformer set. Ignored if combination_name is ‘fallback’.

field rmsd_method: str = 'tradeoff'

RMSD method for deduplication of joint conformer set. Ignored if combination_name is ‘fallback’.

pydantic model qm_atlas.tasks.conformer_generation.RdkitOptions

Options for RDKit conformer generation.

field backend: Literal['rdkit'] = 'rdkit'

Conformer generator backend to use

field method: str = 'KDG'

Embedding method: ETDG, ETKDG, ETKDGv2, ETKDGv3, KDG, srETKDGv3

field max_conformers: int = 1000

Maximum number of conformers to generate

field rms_threshold: float = 0.3

RMSD threshold for deduplication

field random_seed: int = 1

Random seed for reproducibility

pydantic model qm_atlas.tasks.conformer_generation.MacromodelOptions

Options for Macromodel conformer generation.

field backend: Literal['macromodel'] = 'macromodel'

Conformer generator backend to use

field rms_threshold: float = 0.3

RMSD threshold for duplicate detection

field max_conformers: int = 1000

Maximum number of conformers to generate (0=unlimited)

field mode: str = 'MCMM'

Conformer search type: MCMM or LMCS

field force_field: int = 14

Force field: 10=MMFF94s, 14=OPLS2005, 16=OPLS4

field solvent_num: int = 1

Solvent number: 1=water, 9=octanol

field license_buffer: int = 1

Number of licenses to leave available

field license_timeout: int = 60

Timeout in minutes for waiting on license

pydantic model qm_atlas.tasks.conformer_generation.OmegaOptions

Options for OpenEye Omega conformer generation.

field backend: Literal['omega'] = 'omega'

Conformer generator backend to use

field rms_threshold: float = 0.3

RMSD threshold for duplicate detection

field max_conformers: int = 1000

Maximum number of conformers to generate

field start_from_corina: bool = False

Use CORINA to generate 3D input conformation

field n_cores: int = 1

Number of cores to use

pydantic model qm_atlas.tasks.conformer_generation.MoeOptions

Options for MOE conformer generation.

field backend: Literal['moe'] = 'moe'

Conformer generator backend to use

field rms_threshold: float = 0.3

RMSD threshold for duplicate detection

field max_conformers: int = 1000

Maximum number of conformers to generate

field mode: str = "'LowModeMD'"

Conformer search mode (wrapped in quotes for MOE)

pydantic model qm_atlas.tasks.conformer_generation.CorinaOptions

Options for CORINA conformer generation.

field backend: Literal['corina'] = 'corina'

Conformer generator backend to use

pydantic model qm_atlas.tasks.conformer_generation.MacrocycleOptions

Options for Macrocycle conformer generation.

field backend: Literal['macrocycle'] = 'macrocycle'

Conformer generator backend to use

field max_conformers: int = 1000

Maximum number of conformers to generate

field energy_cutoff: float = 30.0

Energy cutoff in kcal/mol

field rms_threshold: float = 0.3

RMS threshold in Angstroms

field num_cores: int = 1

Number of cores to use

field license_buffer: int = 1

Number of licenses to leave available

field license_timeout: int = 60

Timeout in minutes for waiting on license

Geometry optimization

qm_atlas.tasks.optimize.optimize_mol(mol, config, treat_unconverged_as_failure=True, n_cores=1, scr=DEFAULT_SCR, keep_files=False, show_progress=True)

Run geometry optimization on all conformers of a molecule in parallel.

Optimizes all conformers in a molecule using the specified driver. Conformers are processed in parallel to utilize multiple CPU cores efficiently.

Parameters:

• mol (Mol) – RDKit molecule with one or more conformers to optimize.

• config (list[XtbOptions | JobexOptions | XtbTurbomoleOptions]) – Optimization configuration(s) to try in order (each selects a backend and its options; later entries act as fallbacks).

• treat_unconverged_as_failure (bool) – If True, treats unconverged optimizations as failures and attempts the next fallback configuration. Defaults to True.

• n_cores (int) – Number of CPU cores to use for parallel processing. Defaults to 1 (sequential).

• scr (Path) – Path to the scratch directory for temporary files. Defaults to DEFAULT_SCR.

• keep_files (bool) – If True, keeps intermediate files generated during optimization. Defaults to False.

• show_progress (bool) – If True, displays a progress bar. Defaults to True.

Returns:

New molecule with optimized conformers. Failed conformers

are either removed or kept with original coordinates, depending on keep_failures setting.

Return type:

tuple[Mol, list[dict[str, Property]]]

Raises:

ValueError – If an invalid driver is specified.

Examples

>>> mol = Chem.MolFromSmiles("CCO")
>>> mol = Chem.AddHs(mol)
>>> AllChem.EmbedMultipleConfs(mol, 5)
>>> opt_mol = optimize_mol(mol, config=[XtbTurbomoleOptions()], n_cores=4)

pydantic model qm_atlas.tasks.optimize.XtbOptions

Options specific to the xtb optimization driver.

field backend: Literal['xtb'] = 'xtb'

Optimization backend to use

field max_num_steps: int = 100

Maximum number of optimization steps for xtb

Constraints:

• ge = 1

field method: str = '2'

xtb method to use, e.g. ‘2’ for GFN2-xTB, ‘1’ for GFN1-xTB, ‘0’ for GFN0-xTB

field opt_level: Literal['crude', 'sloppy', 'loose', 'lax', 'normal', 'tight', 'verytight', 'extreme'] = 'normal'

xtb optimization level

field solvation_model: str | None = 'alpb'

solvation model for xtb (e.g. ‘alpb’, ‘gbsa’, ‘cosmo’, or None for gas phase)

field solvent: str | None = 'water'

Solvent to use if a solvation model is specified

field constrain: bool = False

Master switch: whether to apply any geometry constraints during optimization

field torsions_fixed: bool = False

Fix all torsions via xtb’s global ‘all torsions’ switch (only applies if constrain=True)

field heavy_atom_torsions_fixed: bool = True

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=True)

field angles_fixed: bool = False

Fix all angles via xtb’s global ‘all angles’ switch (only applies if constrain=True)

field bonds_fixed: bool = False

Fix all bonds via xtb’s global ‘all bonds’ switch (only applies if constrain=True)

field force_constant: float = 0.5

Force constant for constraints in xtb optimization (in Hartree/rad^2 for angles or torsions, Hartree/Bohr^2 for distances)

pydantic model qm_atlas.tasks.optimize.JobexOptions

Options specific to the Turbomole jobex optimization driver.

field backend: Literal['jobex'] = 'jobex'

Optimization backend to use

field max_num_steps: int = 100

Maximum number of optimization steps for jobex

Constraints:

• ge = 1

field energy_conv: int = 7

Sets geometry iteration energy convergence threshold to 10.**(-energy_conv). Higher values lead to tigher convergence.

field geom_conv: int = 3

Sets coordinate change convergence threshold to 10.**(-geom_conv). Higher values lead to tighter convergence.

field functional: list[str] = ['b-p']

Functional for geometry optimization (e.g., ‘b-p’ for BP86)

field basis: str = 'def2-TZVP'

Basis set for geometry optimization

field scf_conv: int = 7

Sets scf energy convergence threshold to 10.**(-scf_conv), should be at least as tight as geom_conv, otherwise geometry iterations will have trouble converging.

field scfiterlimit: int = 500

The maximum number of SCF iterations to perform.

field use_disp: bool = False

Whether to add dispersion correction ($disp3 bj) in jobex optimization

field use_cosmo: bool = True

Whether to use the COSMO implicit solvent model

field solvent: str = 'conductor'

Solvent environment (conductor, water, etc.). Only used if use_cosmo is True. Translates to an epsilon value in turbomole.

pydantic model qm_atlas.tasks.optimize.XtbTurbomoleOptions

Options specific to the xtb-driven Turbomole optimization driver.

field backend: Literal['xtb_turbomole'] = 'xtb_turbomole'

Optimization backend to use

field max_num_steps: int = 100

Maximum number of optimization steps for jobex

Constraints:

• ge = 1

field opt_level: Literal['crude', 'sloppy', 'loose', 'lax', 'normal', 'tight', 'verytight', 'extreme'] = 'normal'

xtb optimization level

field functional: list[str] = ['b-p']

Functional for geometry optimization (e.g., ‘b-p’ for BP86)

field basis: str = 'def2-TZVP'

Basis set for geometry optimization

field scf_conv: int = 7

Sets scf energy convergence threshold to 10.**(-scf_conv), should be at least as tight as geom_conv, otherwise geometry iterations will have trouble converging.

field scfiterlimit: int = 500

The maximum number of SCF iterations to perform.

field use_disp: bool = False

Whether to add dispersion correction ($disp3 bj) in jobex optimization

field use_cosmo: bool = True

Whether to use the COSMO implicit solvent model

field solvent: str = 'conductor'

Solvent environment (conductor, water, etc.). Only used if use_cosmo is True. Translates to an epsilon value in turbomole.

field constrain: bool = False

Master switch: whether to apply any geometry constraints during optimization

field torsions_fixed: bool = False

Fix all torsions via xtb’s global ‘all torsions’ switch (only applies if constrain=True)

field heavy_atom_torsions_fixed: bool = True

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=True)

field angles_fixed: bool = False

Fix all angles via xtb’s global ‘all angles’ switch (only applies if constrain=True)

field bonds_fixed: bool = False

Fix all bonds via xtb’s global ‘all bonds’ switch (only applies if constrain=True)

field force_constant: float = 0.5

Force constant for constraints in xtb optimization (in Hartree/rad^2 for angles or torsions, Hartree/Bohr^2 for distances)

Property calculation

qm_atlas.tasks.calculate_properties.calculate_property_mol(mol, config, n_cores=1, show_progress=False, scr=DEFAULT_SCR, keep_files=False)

Calculate a molecular property for all conformers of a molecule. Uses multiprocessing if multiple CPU cores are specified.

Automatically handles conformer iteration and returns results organized by conformer.

Parameters:

• mol (Mol) – RDKit molecule with one or more conformers to calculate properties for.

• config (XtbSinglePointOptions | TurbomoleSinglePointOptions | TurbomoleFreehOptions | TurbomoleFukuiOptions | TurbomoleNmrShieldingOptions | TurbomoleVcdOptions | JaguarHydrogenAbstractionOptions | JaguarQmDescriptorsOptions) – Configuration object specifying the calculator to use and its options. The backend attribute determines which backend is used.

• n_cores (int) – Number of CPU cores to use for parallel processing. The actual number of processes spawned will be min(n_cores, total_num_conformers). Defaults to 1 (sequential processing).

• show_progress (bool) – If True, displays a progress bar during calculation. Defaults to False.

• scr (Path) – Scratch directory path for temporary calculation files. Defaults to DEFAULT_SCR.

• keep_files (bool) – If True, preserves temporary calculation files after completion. If False, cleans up temporary files. Defaults to False.

Returns:

List of property dictionaries, one for each conformer in the input molecule. Each element is either a dict of calculated Property objects or None if the calculation failed. The list length matches the number of conformers in the input molecule.

Return type:

list[dict[str, Property] | None]

Raises:

ValueError – If config.backend is not found in CALCULATOR_REGISTRY.

Examples

>>> from rdkit import Chem, AllChem
>>> mol = Chem.MolFromSmiles("CCO")
>>> mol = Chem.AddHs(mol)
>>> AllChem.EmbedMultipleConfs(mol, 3)
>>> config = XtbSinglePointOptions()
>>> all_props = calculate_property_mol(mol, config)
>>> # all_props is a list of 3 property dicts, one for each conformer
>>> energy_conf_0 = all_props[0]["energy"].get_property_value()

pydantic model qm_atlas.tasks.calculate_properties.XtbSinglePointOptions

Options for xtb.calculate_single_point (exposed CLI parameters only).

To customise the input beyond the exposed fields, supply a fully rendered template_str; unknown keyword arguments are rejected.

field backend: Literal['xtb_single_point'] = 'xtb_single_point'

Type identifier for this calculator configuration

field solvation_model: str | None = None

Solvation model (alpb, gbe, gbsa, cosmo, cpmcx)

field solvent: str | None = None

Solvent name (e.g., water, methanol)

field calculate_fukui: bool = False

Calculate Fukui indices

field xtb_command_add: list[str] | None = None

Additional command-line arguments to pass to xtb

field template_str: str | None = None

Jinja2 template for xcontrol input file (if None, uses xtb default)

field property_prefix: str | None = None

Prefix for property names. If None, defaults to a calculator-specific value

pydantic model qm_atlas.tasks.calculate_properties.TurbomoleSinglePointOptions

Options for turbomole.single_point.run_ridft.

To customise the input beyond the exposed fields, supply a fully rendered control_template; unknown keyword arguments are rejected.

field backend: Literal['turbomole_single_point'] = 'turbomole_single_point'

Type identifier for this calculator configuration

field basis: str = 'def2-TZVPD'

Basis set for the calculation

field functional: list[str] = ['b-p']

DFT functional(s) to use

field grid: str = 'm4'

Grid size for integration (e.g., m3, m4)

field scf_conv: int = 7

SCF energy convergence criterion (10^-scf_conv). Higher = tighter convergence.

field scfiterlimit: int = 500

Maximum number of SCF iterations

field ricore: int | None = None

RICORE memory parameter

field use_disp: bool = False

Whether to include dispersion corrections (D3 BJ)

field use_cosmo: bool = True

Whether to use COSMO solvation model

field klamt: bool = True

Whether to use Klamt’s COSMO variant

field solvent: str = 'conductor'

Solvent for COSMO calculations

field control_template: str | None = None

Jinja2 template for control file (if None, uses turbomole default)

field property_prefix: str | None = None

Prefix for property names. If None, defaults to tm_sp_

pydantic model qm_atlas.tasks.calculate_properties.TurbomoleFreehOptions

Options for turbomole.freeh.calculate_freeh.

To customise the input beyond the exposed fields, supply a fully rendered control_template; unknown keyword arguments are rejected.

field backend: Literal['turbomole_freeh'] = 'turbomole_freeh'

Type identifier for this calculator configuration

field basis: str = 'def2-TZVP'

Basis set for the calculation

field functional: list[str] | tuple[str, ...] = ('b3-lyp',)

DFT functional(s) to use

field grid: str = 'm3'

Grid size for integration (e.g., m3, m4)

field scf_conv: int = 7

SCF energy convergence criterion (10^-scf_conv). Higher = tighter convergence.

field scfiterlimit: int = 200

Maximum number of SCF iterations

field scfdamp: str = 'start=0.300  step=0.050  min=0.100'

SCF damping parameters

field ricore: int | None = None

RICORE memory parameter

field use_disp: bool = False

Whether to include dispersion corrections (D3 BJ)

field use_cosmo: bool = False

Whether to use COSMO solvation model

field klamt: bool = True

Whether to use Klamt’s COSMO variant

field solvent: str = 'conductor'

Solvent for COSMO calculations

field freeh_settings: str = '\n0.97\ntstart=298.15 tend=298.15 numt=1 pstart=0.1 pend=0.1 nump=1\nq\n'

Settings string specifying temperature, pressure conditions for freeh

field control_template: str | None = None

Jinja2 template for control file (if None, uses turbomole default)

field property_prefix: str | None = None

Prefix for property names. If None, defaults to tm_freeh_

pydantic model qm_atlas.tasks.calculate_properties.TurbomoleFukuiOptions

Options for turbomole.fukui.calculate_fukui.

To customise the input beyond the exposed fields, supply a fully rendered control_template; unknown keyword arguments are rejected.

field backend: Literal['turbomole_fukui_indices'] = 'turbomole_fukui_indices'

Type identifier for this calculator configuration

field basis: str = 'def2-SV(P)'

Basis set for the calculation

field functional: list[str] | tuple[str, ...] = ('pbe',)

DFT functional(s) to use

field grid: str = 'm3'

Grid size for integration (e.g., m3, m4)

field scf_conv: int = 7

SCF energy convergence criterion (10^-scf_conv). Higher = tighter convergence.

field scfiterlimit: int = 100

Maximum number of SCF iterations

field scfdamp: str = 'start=2.000  step=0.050  min=0.100'

SCF damping parameters

field ricore: int | None = None

RICORE memory parameter

field use_disp: bool = False

Whether to include dispersion corrections (D3 BJ)

field use_cosmo: bool = False

Whether to use COSMO solvation model

field klamt: bool = True

Whether to use Klamt’s COSMO variant

field solvent: str = 'conductor'

Solvent for COSMO calculations

field charge_schemes: list[str] | None = None

Charge schemes to use (nbo, mulliken, loewdin, paboon). If None, all are used.

field control_template: str | None = None

Jinja2 template for control file (if None, uses turbomole default)

field property_prefix: str | None = None

Prefix for property names. If None, defaults to tm_fukui_

pydantic model qm_atlas.tasks.calculate_properties.TurbomoleNmrShieldingOptions

Options for turbomole.nmr_shielding.calculate_nmr_shieldings (exposed CLI parameters only).

To customise the input beyond the exposed fields, supply a fully rendered control_template; unknown keyword arguments are rejected.

field backend: Literal['turbomole_nmr_shielding'] = 'turbomole_nmr_shielding'

Type identifier for this calculator configuration

field basis: str = 'def2-TZVP'

Basis set for the calculation

field functional: list[str] | tuple[str, ...] = ('xcfun set-gga', 'xcfun kt3 1.0')

DFT functional(s) to use

field grid: str = '3'

Grid size for integration (e.g., 3, 4, m3, m4)

field scf_conv: int = 7

SCF energy convergence criterion (10^-scf_conv). Higher = tighter convergence.

field scfiterlimit: int = 200

Maximum number of SCF iterations

field ricore: int | None = None

RICORE memory parameter

field use_disp: bool = False

Whether to include dispersion corrections (D3 BJ)

field use_cosmo: bool = False

Whether to use COSMO solvation model

field klamt: bool = True

Whether to use Klamt’s COSMO variant

field solvent: str = 'conductor'

Solvent for COSMO calculations

field control_template: str | None = None

Jinja2 template for control file (if None, uses turbomole default)

field property_prefix: str | None = None

Prefix for property names. If None, defaults to tm_nmr_shieldings_

pydantic model qm_atlas.tasks.calculate_properties.TurbomoleVcdOptions

Options for turbomole.vcd.calculate_vcd (exposed CLI parameters only).

To customise the input beyond the exposed fields, supply a fully rendered control_template; unknown keyword arguments are rejected.

field backend: Literal['turbomole_vcd'] = 'turbomole_vcd'

Type identifier for this calculator configuration

field basis: str = 'def2-SVP'

Basis set for the calculation

field functional: list[str] | tuple[str, ...] = ('b3-lyp',)

DFT functional(s) to use

field grid: str = '4'

Grid size for integration (numeric format like 3, 4, 5)

field scf_conv: int = 8

SCF energy convergence criterion (10^-scf_conv). Higher = tighter convergence.

field scfiterlimit: int = 500

Maximum number of SCF iterations

field ricore: int | None = None

RICORE memory parameter

field use_disp: bool = False

Whether to include dispersion corrections (D3 BJ)

field use_cosmo: bool = False

Whether to use COSMO solvation model

field klamt: bool = True

Whether to use Klamt’s COSMO variant

field solvent: str = 'conductor'

Solvent for COSMO calculations

field control_template: str | None = None

Jinja2 template for control file (if None, uses turbomole default)

field property_prefix: str | None = None

Prefix for property names. If None, defaults to tm_vcd_

pydantic model qm_atlas.tasks.calculate_properties.JaguarHydrogenAbstractionOptions

Options for jaguar.bond_dissociation.get_hydrogen_abstraction_energies.

Note: Internal parameters like keep_files, scr, and n_cores are not exposed via CLI.

field backend: Literal['jaguar_h_abstraction_energies'] = 'jaguar_h_abstraction_energies'

Type identifier for this calculator configuration

field atom_idcs: list[int] | str = 'C'

Atom indices (list of int) or element symbol(s) (‘C’, ‘N’, ‘C,N’)

field geo_opt_settings: dict[str, str] | None = None

Settings for geometry optimization (e.g., {‘dftname’: ‘b3lyp’, ‘basis’: ‘lacvp*’})

field single_point_settings: dict[str, str] | None = None

Settings for single point energy calculations

field jaguar_options: dict[str, str] | None = None

Additional jaguar command-line options

field license_buffer: int = 40

Number of licenses to keep in reserve

field license_timeout: int = 2880

Timeout for license acquisition in minutes (default: 2 days)

field property_prefix: str | None = None

Prefix for property names. If None, defaults to ‘jaguar_h_abstraction_energies’

pydantic model qm_atlas.tasks.calculate_properties.JaguarQmDescriptorsOptions

Options for jaguar.qm_descriptors.calculate_descriptors (exposed CLI parameters only).

Note: Internal parameters like keep_files, scr, and n_cores are not exposed via CLI.

field backend: Literal['jaguar_properties'] = 'jaguar_properties'

Type identifier for this calculator configuration

field properties: list[str] | tuple[str, ...] = ('fukui', 'lowdin', 'nmr')

Properties to calculate (choices: fukui, lowdin, nmr)

field basis: str = 'LACVP*'

Basis set for the calculation

field functional: list[str] | tuple[str, ...] = ('b3lyp-d3',)

DFT functional(s) to use

field jaguar_options: dict[str, str] | None = None

Additional jaguar command-line options

field license_buffer: int = 40

Number of licenses to keep in reserve

field license_timeout: int = 2880

Timeout for license acquisition in minutes (default: 2 days)

field property_prefix: str | None = None

Prefix for property names. If None, defaults to jaguar_

COSMO properties

qm_atlas.tasks.cosmo_properties.run_cosmo_calculation(conformer_cosmo_files, config, scr=DEFAULT_SCR, keep_files=False, n_cores=1)

Dispatch to the COSMO calculator selected by config.backend (see CALCULATOR_REGISTRY) and return its named properties.

Return type:

dict[str, ScalarProperty] | list[dict[str, ScalarProperty]]

Parameters:

• conformer_cosmo_files (list[Path])

• config (Annotated[CosmoLogPConfig | CosmoDeltaGConfig | CosmoDescriptorsConfig | CosmoPsaConfig | CosmoPermConfig, FieldInfo(annotation=NoneType, required=True, discriminator='backend')])

• scr (Path)

• keep_files (bool)

• n_cores (int)

pydantic model qm_atlas.tasks.cosmo_properties.CosmoLogPConfig

field backend: Literal['cosmo_logp'] = 'cosmo_logp'

Type identifier for this COSMO calculation

field is_woctanol: bool = True

Whether to calculate logP for wet octanol, i.e taking into account the presence of water in the octanol phase. If False, logP is calculated for pure octanol.

field solvent_names: list[str] [Optional]

Names of the solvents to use for the COSMO calculation. The first solvent in the list will be used as the reference solvent for the logP calculation (e.g. water for logP).

field eq_phases: bool = False

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.

field property_prefix: str | None = None

Prefix for property names. If None, defaults to cosmo_logp_

field level: Literal['bp-tzvpd', 'bp-tzvp', 'bp-tzvp', 'dmol3-pbe'] = 'bp-tzvpd'

Level of theory to use for the COSMO calculation.

field temperature_Celsius: float = 25.0

Temperature in Celsius to use for the COSMO calculation. Default is 25.0 °C.

field solvents_dirs: list[Path] [Optional]

Additional directories to find the .cosmo files for the solvents. By default, only the cosmotherm database is used.

field use_config_cosmo_dir: bool = True

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.

pydantic model qm_atlas.tasks.cosmo_properties.CosmoDeltaGConfig

field backend: Literal['cosmo_delta_g'] = 'cosmo_delta_g'

Type identifier for this COSMO calculation

field solvent_name: str = 'h2o'

Name of the solvent to use for the COSMO calculation, e.g. ‘h2o’ for water, ‘self’ can be used the compound itself as solvent.

field property_prefix: str | None = None

Prefix for property names. If None, defaults to cosmo_delta_g_

field level: Literal['bp-tzvpd', 'bp-tzvp', 'bp-tzvp', 'dmol3-pbe'] = 'bp-tzvpd'

Level of theory to use for the COSMO calculation.

field temperature_Celsius: float = 25.0

Temperature in Celsius to use for the COSMO calculation. Default is 25.0 °C.

field solvents_dirs: list[Path] [Optional]

Additional directories to find the .cosmo files for the solvents. By default, only the cosmotherm database is used.

field use_config_cosmo_dir: bool = True

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.

pydantic model qm_atlas.tasks.cosmo_properties.CosmoDescriptorsConfig

field backend: Literal['cosmo_descriptors'] = 'cosmo_descriptors'

Type identifier for this COSMO calculation

field solvent_name: str = 'h2o'

Name of the solvent to use for the COSMO calculation, e.g. ‘h2o’ for water.

field property_prefix: str | None = None

Prefix for property names. If None, defaults to cosmo_

field level: Literal['bp-tzvpd', 'bp-tzvp', 'bp-tzvp', 'dmol3-pbe'] = 'bp-tzvpd'

Level of theory to use for the COSMO calculation.

field temperature_Celsius: float = 25.0

Temperature in Celsius to use for the COSMO calculation. Default is 25.0 °C.

field solvents_dirs: list[Path] [Optional]

Additional directories to find the .cosmo files for the solvents. By default, only the cosmotherm database is used.

field use_config_cosmo_dir: bool = True

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.

pydantic model qm_atlas.tasks.cosmo_properties.CosmoPsaConfig

field backend: Literal['cosmo_psa'] = 'cosmo_psa'

Type identifier for this COSMO calculation

field smoothen: bool = True

Whether to smoothen the sigma charge density before calculating the PSA. Smoothing is done according to eq. 11 in J. Phys. Chem. A 1998, 102, 5074-5085, https://doi.org/10.1021/jp980017s

field on_charges: bool = False

Whether to calculate the PSA based on the charge density (sigma) or the charge. If False, the PSA is calculated based on the charge density, if True, it is calculated based on the charge.

field lower_limit: float = -0.01

Lower limit for the charge density (sigma) to consider a surface segment as polar. Should be adapted from the default value if on_charges is True.

field upper_limit: float = 0.01

Upper limit for the charge density (sigma) to consider a surface segment as polar. Should be adapted from the default value if on_charges is True.

field property_prefix: str | None = None

Prefix for property names. If None, defaults to cosmo_psa_

Protonation

qm_atlas.tasks.protonation.run_protonation(mol, config, scr, keep_files=False)

Run a protonation backend on mol and return the unified result.

Parameters:

• mol (Mol) – Parent molecule.

• config (ProtonationOptions) – Backend-specific configuration (a concrete ProtonationOptions subclass).

• scr (Path) – Scratch directory for backend intermediates.

• keep_files (bool) – Whether to keep the backend intermediate files. Used for debugging. Defaults to False.

Return type:

ProtonationResult

Returns:

ProtonationResult with the protomers produced by the backend and, where supported, the pKa transitions linking them.

pydantic model qm_atlas.tasks.protonation.MokaBlabberConfig

Generate protonation states with MoKa’s blabber_sd tool.

field backend: Literal['moka_blabber'] = 'moka_blabber'

field ph: str = '7.4'

pH passed to blabber’s –pH flag. Accepts a single value, a range (e.g. ‘6-10’), or a comma-separated list (e.g. ‘6,7-10’).

field abundance_threshold: float | None = None

Only protomers with an abundance above this threshold (percent) are kept. Forwarded to blabber’s -t flag when set; further filtering is applied on the returned ABUNDANCE property.

field remove_zero_charged: bool = False

If True, drop neutral protomers from the blabber output.

pydantic model qm_atlas.tasks.protonation.MokaIonicSpeciesConfig

Enumerate ionic species using MoKa pKa prediction.

Uses qm_atlas.wrappers.moka.process.generate_ionic_species().

field backend: Literal['moka_ionic_species'] = 'moka_ionic_species'

pydantic model qm_atlas.tasks.protonation.MokaSingleChargeConfig

Enumerate singly-charged ions using MoKa pKa prediction.

Uses qm_atlas.wrappers.moka.process.generate_single_charge_ions().

field backend: Literal['moka_single_charge'] = 'moka_single_charge'

Tautomers

qm_atlas.tasks.tautomer_generation.generate_tautomers(molobj, scr)

Generate tautomers for a molecule using unicon.

Runs unicon, appends the original molecule, then deduplicates by canonical SMILES so the returned list contains only structurally distinct tautomers.

Parameters:

• molobj (Mol) – Input molecule (should already be neutralized).

• scr (Path) – Scratch directory for unicon intermediate files.

Return type:

list[Mol]

Returns:

List of unique tautomer Mol objects (always includes the original).

Raises:

ValueError – If the deduplicated tautomer list is empty.

Workflows

High-level entry points that combine several tasks into a complete calculation.

ReSCoSS conformers

qm_atlas.workflows.generate_rescoss_conformers(mol, conformer_generation_options=RESCOSS_DEFAULT_CONF_GENS, expand_conformers=True, xtb_optimization_config=XTB_OPTIMIZATION_CONFIG, rmsd_threshold=RMSD_THRESHOLD, solvents_dirs=None, use_config_cosmo_dir=True, num_clusters=DEFAULT_NUM_CLUSTERS, num_per_cluster=DEFAULT_NUM_PER_CLUSTER, final_optimization_config=DEFAULT_FINAL_OPTIMIZATION_CONFIG, final_rmsd_threshold=RMSD_THRESHOLD / 5, scr=constants.DEFAULT_SCR, write_intermediates=False, trace_dir=constants.DEFAULT_SCR, keep_files=False, n_cores=1)

The ReSCoSS conformer workflow. Generates a list of conformers that aims to represent relevant conformations in different solvents. See Reference [1] for a detailed description. Here is a brief summary of the steps the workflow takes:

1. Initial force-field based conformer generation.

2. xtb-level geometry optimization of all obtained structures.

3. Deduplication of the conformers after xtb-level geometry optimization

   based on their RMSD.

4. Single-Point Calculations (B97-3c/mTZVP) and subsequent extraction of

   cosmotherm properties in 10 different solvents.

5. k-means clustering based on the cosmotherm properties in water.

6. From each cluster, keep all conformers with the lowest N energies

   in any of the 10 solvents (and discard all others).

7. DFT-level geometry optimization (default BP86/TZVP, can be changed).

Parameters:

• mol (Mol) – The molecule to work on.

• conformer_generation_options (ConformerGenerationOptions) – Specifies which conformer generators to use for the initial conformer expansion. Defaults to RESCOSS_DEFAULT_CONF_GENS, which uses a combination of macromodel, omega, moe, and rdkit.

• expand_conformers (bool) – If False, the workflow skips force-field based conformer expansion and uses the conformers provided with the molecule. Defaults to True.

• xtb_optimization_config (list[XtbOptions | XtbTurbomoleOptions | JobexOptions]) – Configuration for xtb-level geometry optimization in step 2. Defaults to XTB_OPTIMIZATION_CONFIG.

• rmsd_threshold (float) – RMSD value below which two conformers are considered duplicates in the deduplication carried out after xtb-level geometry optimization. Defaults to RMSD_THRESHOLD.

• solvents_dirs (list[Path] | None) – Additional directories in which to look for the solvent .cosmo files used in the cosmotherm property calculations. Defaults to None, i.e. relying on the cosmotherm database and the configured directories.

• use_config_cosmo_dir (bool) – Whether to prepend the solvent directories from the software configuration file to solvents_dirs. Defaults to True.

• final_optimization_config (list[XtbOptions | XtbTurbomoleOptions | JobexOptions] | None) – Configuration for DFT-level geometry optimization in step 7. Defaults to DEFAULT_FINAL_OPTIMIZATION_CONFIG.

• final_rmsd_threshold (float) – RMSD value below which two conformers are considered duplicates in the deduplication carried out after the final DFT-level optimization. Defaults to RMSD_THRESHOLD / 5.

• num_clusters (int) – The number of clusters to use in k-means clustering based on cosmotherm properties in water. Defaults to DEFAULT_NUM_CLUSTERS.

• num_per_cluster (int) – The number of conformations to keep per cluster and solvent. Defaults to DEFAULT_NUM_PER_CLUSTER.

• scr (Path) – The scratch directory for intermediate calculations. Defaults to DEFAULT_SCR.

• write_intermediates (bool) – If True, writes sdf files with conformers at intermediate workflow steps to the trace directory. Debugging option. Defaults to False.

• trace_dir (Path) – The directory to write intermediate sdf files for debugging purposes. Defaults to DEFAULT_SCR.

• keep_files (bool) – If True, keeps intermediate files from calculations. Debugging option. Defaults to False.

• n_cores (int) – The number of available cores for parallel processing. Defaults to 1.

Returns:

The molecule with final, DFT-optimized geometries and representative conformers selected through the clustering and filtering workflow.

Return type:

Mol

References

[1] Udvarhelyi, A., Rodde, S. & Wilcken, R. ReSCoSS: a flexible quantum chemistry workflow identifying relevant solution conformers of drug-like molecules. J. Comput. Aided Mol. Des. 35, 399-415 (2021). https://doi.org/10.1007/s10822-020-00337-7

Fast conformers

qm_atlas.workflows.generate_fast_conformers(molobj, conformer_generation_options=FAST_DEFAULT_OPTIONS, expand_conformers=True, optimization_config=DEFAULT_OPTIMIZATION_CONFIG, final_optimization_config=DEFAULT_FINAL_OPTIMIZATION_CONFIG, scr=constants.DEFAULT_SCR, show_progress=False, n_cores=1, trace_dir=constants.DEFAULT_SCR, write_intermediates=False)

Generate a representative set of conformers for a molecule using a multi-stage force-field + xTB pipeline.

Workflow:

1. Conformer generation: Runs force-field based conformer generators

2. Shape filtering + xTB optimization: run fast_conformer_filtering()

3. Optional final optimization: the unique conformers are re-optimized.

Parameters:

• molobj (Mol) – Input RDKit molecule (2D or 3D; conformers are always generated from scratch).

• conformer_generation_options (ConformerGenerationOptions) – Force-field conformer generator settings. Defaults to FAST_DEFAULT_OPTIONS (OpenEye Omega, rms_threshold=0.3, max_conformers=1000, with RDKit KDG fallback).

• expand_conformers (bool) – If False, skips force-field based conformer generation and uses the conformers already present on molobj. Defaults to True.

• optimization_config (list[XtbOptions | JobexOptions | XtbTurbomoleOptions]) – Sequence of xTB optimization steps applied after the first shape filter. Defaults to DEFAULT_OPTIMIZATION_CONFIG (GFN2-xTB normal → GFN0-xTB normal → GFN2-xTB lax, all with ALPB water solvation).

• final_optimization_config (list[XtbOptions | JobexOptions | XtbTurbomoleOptions]) – Optional sequence of optimization steps applied to the final unique conformers. Pass an empty list (default, DEFAULT_FINAL_OPTIMIZATION_CONFIG) to skip this step.

• scr (Path) – Scratch directory for xTB calculations. Defaults to constants.DEFAULT_SCR.

• show_progress (bool) – Show a progress bar during optimization. Defaults to False.

• n_cores (int) – Number of CPU cores to use. Defaults to 1.

• trace_dir (Path) – Directory for intermediate SDF files written when write_intermediates=True. Defaults to constants.DEFAULT_SCR.

• write_intermediates (bool) – Write SDF files at each workflow step for debugging. Defaults to False.

Returns:

Molecule with a reduced, shape-diverse set of xTB-optimized conformers. Each conformer is the lowest-energy representative of its shape cluster (defined by SASA and dipole moment). Returns the input molobj if conformer generation fails or produces fewer than 2 conformers.

Return type:

Mol

Tautomers

qm_atlas.workflows.generate_tautomers(mol, energy_threshold=7, solvent_name='h2o', single_point_config=TAUTOMER_TM_SP_CONFIG, cosmo_options=cosmo_tasks.DESCRIPTORS_SETTINGS_SIMPLIFIED, solvents_dirs=None, use_config_cosmo_dir=True, conformer_generation_options=fast_conformers.FAST_DEFAULT_OPTIONS, optimization_config=fast_conformers.DEFAULT_OPTIMIZATION_CONFIG, final_optimization_config=fast_conformers.DEFAULT_FINAL_OPTIMIZATION_CONFIG, n_cores=1, scr=DEFAULT_SCR)

Enumerate the tautomers of a molecule and keep the energetically relevant ones.

Tautomers are generated with UniCon. Each tautomer is expanded into a conformer ensemble and geometry-optimized with generate_fast_conformers(), and every conformer receives a DFT single-point calculation from which COSMOtherm free energies are extracted. Each tautomer is scored by the lowest E_COSMO+dE+Mu free energy across its conformers in solvent_name. Tautomers whose free energy lies within energy_threshold of the most stable tautomer are returned.

Parameters:

• mol (Mol) – The molecule whose tautomers should be enumerated and scored.

• energy_threshold (float) – Free-energy window in kcal/mol relative to the most stable tautomer. Tautomers with a relative energy below this value are kept. Defaults to 7.

• solvent_name (str) – Name of the solvent used for the COSMOtherm free-energy evaluation. Defaults to “h2o”.

• single_point_config (TurbomoleSinglePointOptions) – Configuration for the DFT single-point calculations used to obtain the COSMOtherm properties. Defaults to TAUTOMER_TM_SP_CONFIG.

• cosmo_options (CosmoSettings) – Settings for the COSMOtherm descriptor calculation. Defaults to cosmo_tasks.DESCRIPTORS_SETTINGS_SIMPLIFIED.

• solvents_dirs (list[Path] | None) – Additional directories in which to look for the solvent .cosmo files. Defaults to None (use the COSMOtherm database and configured directories).

• use_config_cosmo_dir (bool) – Whether to prepend the solvent directories from the software configuration to solvents_dirs. Defaults to True.

• conformer_generation_options (ConformerGenerationOptions) – Force-field conformer generator settings used during conformer expansion. Defaults to FAST_DEFAULT_OPTIONS.

• optimization_config (list[XtbOptions | JobexOptions | XtbTurbomoleOptions]) – Sequence of optimization steps applied during conformer expansion. Defaults to DEFAULT_OPTIMIZATION_CONFIG.

• final_optimization_config (list[XtbOptions | JobexOptions | XtbTurbomoleOptions]) – Optional final optimization steps applied to the expanded conformers. Defaults to DEFAULT_FINAL_OPTIMIZATION_CONFIG.

• n_cores (int) – Number of CPU cores to use. Conformer expansion is parallelized over the tautomers. Defaults to 1.

• scr (Path) – Scratch directory for the calculations. Defaults to DEFAULT_SCR.

Returns:

The tautomers (as generated by UniCon) whose lowest COSMOtherm free energy lies within energy_threshold of the most stable tautomer.

Return type:

list[Mol]

Constrained optimization

qm_atlas.workflows.run_constrained_optimization(mol, n_cores=1, optimization_config=None, treat_unconverged_as_failure=False)

Run constrained optimization for a molecule with multiple configuration options.

Parameters:

• mol (Mol) – Molecule to optimize. Must have exactly one conformation.

• n_cores (int) – Number of cores to allocate for this optimization. Defaults to 1.

• optimization_config (Sequence[Sequence[XtbTurbomoleOptions | XtbOptions | JobexOptions]] | None) – List of optimization configurations to run. Each one is run separately and different molecules are returned for each. Each entry can be a sublist of configurations to try sequentially with fallback behavior. Defaults to DEFAULT_OPTIMIZATION_CONFIG (after resolving the default value of None), which corresponds to two runs with different force constants for the constraints (0.5 and 0.1).

• treat_unconverged_as_failure (bool) – Whether unconverged results should trigger fallback. Defaults to False.

Raises:

ValueError – If the input molecule does not have exactly one conformation.

Returns:

List of optimized molecules.

Return type:

list[Mol]

Wrappers

Thin interfaces to the external quantum-chemistry and cheminformatics programs. Only the main entry points that the tasks build on are listed here, grouped by program.

xtb

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)

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

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:

dict[str, Property]

Raises:

• RuntimeError – If any error occurs during calculation.

• ValueError – If solvent is not specified when solvation_model is provided.

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)

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:

dict[str, Property] | None

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)

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

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

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:

dict[str, Property] | None

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)

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:

dict[str, Property] | None

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)

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:

dict[str, Property] | None

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)

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

COSMOtherm

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)

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)

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:

dict[str, ScalarProperty]

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)

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:

dict[str, ScalarProperty]

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)

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_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)

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:

DataFrame

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)

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:

DataFrame

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_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)

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:

DataFrame

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_solubility.parse_solubility_data(sol_df, num_solvents=2)

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:

DataFrame

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)

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:

DataFrame

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.cpsa.extract_psa_from_cosmo_file(file, smoothen=True, lower_limit=MLIMIT, upper_limit=PLIMIT, on_charges=False)

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:

dict[str, ScalarProperty]

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

Jaguar

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)

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:

dict[str, AtomBasedProperty]

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)

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:

dict[str, AtomBasedProperty]

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

MoKa

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

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.process.generate_ionic_species(mol, pka_centers, lower_ph_threshold=-np.inf, upper_ph_threshold=np.inf)

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)

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

MacroModel

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

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:

Mol

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:

Mol

MOE

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

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:

Mol

OpenEye Omega

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)

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:

Mol

CORINA

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

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:

Mol

UNICON

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

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