Workflows

Main Entry Points

These are the primary workflow functions that most users should use:

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)[source]

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

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)[source]

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

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)[source]

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]

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

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]

Detailed Module Documentation

qm_atlas.workflows.fast_conformers.reindex_conformers(molobj)[source]

Renumber the conformer ids of molobj to 0..N-1, keeping their order.

Both ppqm helpers used in this module address conformers by position where rdkit expects an id: chembridge.get_sasa iterates range(GetNumConformers()) and passes each counter as confIdx, and chembridge.molobj_select_conformers is called here with the positional indices that filters produces but looks them up with GetConformer(id=...). Both are correct only while ids and positions coincide.

They stop coinciding after optimize_mol(), which drops conformers whose optimization failed and keeps the ids of the survivors - four conformers with one failure leave ids 0, 2, 3, and the next SASA call raises ValueError: Bad Conformer Id. Calling this after every optimization restores the invariant those helpers rely on.

Parameters:

molobj (Mol) – Molecule whose conformers should be renumbered.

Returns:

molobj itself when the ids are already contiguous, otherwise a

copy carrying the same conformers in the same order with ids 0..N-1.

Return type:

Mol

qm_atlas.workflows.fast_conformers.get_conformer_shapes(molobj)[source]

Get a list of descriptors for each conformer, namely;

  • SASA

  • Dipole moment

Note: recoss clusters on - dipole moment (xtb) - hydrogen-acceptor moment (COSMO) - hydrogen-donor moment (COSMO) - Solvent accessible surface Area (COSMO)

Return type:

ndarray

Parameters:

molobj (Mol)

qm_atlas.workflows.fast_conformers.filter_molobj_shapes(molobj, pick_n=1)[source]

Filter conformers by shape descriptors, keeping one representative per cluster.

Computes SASA and dipole moment for each conformer, clusters them using the combined IsolationForest -> DBSCAN -> KMeans search, and picks one conformer per cluster.

Parameters:

  • molobj (Mol) – Input molecule with at least one conformer.

  • pick_n (int) – How many conformers per cluster. Defaults to 1.

Returns:

Molecule containing N conformer per shape cluster.

Return type:

Mol

qm_atlas.workflows.fast_conformers.fast_conformer_filtering(molobj, optimization_config=DEFAULT_OPTIMIZATION_CONFIG, show_progress=False, n_cores=1, scr=constants.DEFAULT_SCR)[source]

Given pre-generated conformers, filter them using shape descriptors and xTB optimization.

Applies two rounds of shape-based filtering (SASA + dipole moment) around a geometry optimization step:

  1. First filter: clusters conformers by shape descriptors and picks one representative per cluster to reduce the set before optimization.

  2. xTB optimization: relaxes the filtered set using optimization_config and collects per-conformer energies.

  3. Second filter: re-clusters the optimized conformers by shape. Within each cluster the lowest-energy conformer is kept. If fewer than 10 conformers remain and shape variance is very low (SASA std < 5.0 Å**2, dipole std < 1.0 D), all are treated as one cluster.

Parameters:

  • molobj (Mol) – Input molecule with at least 2 conformers.

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

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

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

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

Returns:

Molecule with a reduced, shape-diverse set of xTB-optimized conformers. Each conformer is the lowest-energy representative of its shape cluster.

Return type:

Mol

qm_atlas.workflows.fast_conformers.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)[source]

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

qm_atlas.workflows.fast_conformers.FAST_DEFAULT_OPTIONS = ConformerGenerationOptions(conf_gens=[OmegaOptions(backend='omega', rms_threshold=0.3, max_conformers=1000, start_from_corina=True, n_cores=1), RdkitOptions(backend='rdkit', method='KDG', max_conformers=1000, rms_threshold=0.3, random_seed=1)], combination_name='fallback', rms_threshold=0.3, rmsd_method='tradeoff')
qm_atlas.workflows.fast_conformers.DEFAULT_OPTIMIZATION_CONFIG: list[Annotated[XtbOptions | JobexOptions | XtbTurbomoleOptions, FieldInfo(annotation=NoneType, required=True, discriminator='backend')]] = [XtbOptions(backend='xtb', max_num_steps=100, method='2', opt_level='normal', solvation_model='alpb', solvent='water', constrain=False, torsions_fixed=False, heavy_atom_torsions_fixed=True, angles_fixed=False, bonds_fixed=False, force_constant=0.5), XtbOptions(backend='xtb', max_num_steps=200, method='0', opt_level='normal', solvation_model='alpb', solvent='water', constrain=False, torsions_fixed=False, heavy_atom_torsions_fixed=True, angles_fixed=False, bonds_fixed=False, force_constant=0.5), XtbOptions(backend='xtb', max_num_steps=500, method='2', opt_level='lax', solvation_model='alpb', solvent='water', constrain=False, torsions_fixed=False, heavy_atom_torsions_fixed=True, angles_fixed=False, bonds_fixed=False, force_constant=0.5)]
qm_atlas.workflows.fast_conformers.DEFAULT_FINAL_OPTIMIZATION_CONFIG: list[Annotated[XtbOptions | JobexOptions | XtbTurbomoleOptions, FieldInfo(annotation=NoneType, required=True, discriminator='backend')]] = []

Implements the ReSCoSS conformer workflow described in:

[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

qm_atlas.workflows.rescoss_conformers.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)[source]

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

qm_atlas.workflows.rescoss_conformers.get_cosmo_descriptors(solvent_name, cosmo_outputs, solvents_dirs=None, use_config_cosmo_dir=True, scr=constants.DEFAULT_SCR, keep_files=False)[source]

Helper function to calculate conformer cosmo descriptors for a given solvent.

Parameters:

  • solvent_name (str) – The name of the solvent

  • cosmo_outputs (list[str]) – The cosmo outputs for the conformers.

  • solvents_dirs (list[Path] | None) – The directory (or list of directories) in which the solvent cosmo file is located. Defaults to the COSMO solvents directories (TZVP) from config.

  • use_config_cosmo_dir (bool) – If True, also include the COSMO solvents directory configured via the software config. Defaults to True.

  • scr (Path) – The scratch directory to use for the calculation. Defaults to DEFAULT_SCR.

  • keep_files (bool) – whether to keep the generated files. Defaults to False.

Returns:

A dataframe containing the descriptors for the solvent.

Return type:

DataFrame

qm_atlas.workflows.rescoss_conformers.select_from_clusters(label_to_idcs, solvent_energies, num_per_cluster=3)[source]
For all supplied clusters, the code selects all indices corresponding

to the N conformers with lowest energy in each of the solvents for which the energy is supplied.

Parameters:

  • label_to_idcs (list[ndarray]) – A list of numpy arrays. label_to_idcs[cluster_idx] contains the indices of all conformers belonging to the cluster with index cluster_idx.

  • solvent_energies (dict[str, ndarray]) – A dictionary mapping solvent names to the energies of all conformers in these solvents. For each solvent, solvent_energies[solvent_name][idx] is the energy of the conformer with index idx in the specified solvent.

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

Returns:

A set of all conformer indices selected. Note that we could in principle select, for each cluster, N * (number of solvents) indices. However, the indices typically overlap and we select much fewer.

Return type:

set[int]

qm_atlas.workflows.rescoss_conformers.RESCOSS_DEFAULT_CONF_GENS = ConformerGenerationOptions(conf_gens=[MacromodelOptions(backend='macromodel', rms_threshold=0.3, max_conformers=0, mode='MCMM', force_field=16, solvent_num=1, license_buffer=1, license_timeout=60), MacromodelOptions(backend='macromodel', rms_threshold=0.3, max_conformers=0, mode='MCMM', force_field=16, solvent_num=9, license_buffer=1, license_timeout=60), MacromodelOptions(backend='macromodel', rms_threshold=0.3, max_conformers=0, mode='MCMM', force_field=14, solvent_num=1, license_buffer=1, license_timeout=60), OmegaOptions(backend='omega', rms_threshold=0.5, max_conformers=1000, start_from_corina=True, n_cores=1), MoeOptions(backend='moe', rms_threshold=0.5, max_conformers=1000, mode="'LowModeMD'"), RdkitOptions(backend='rdkit', method='KDG', max_conformers=1000, rms_threshold=0.3, random_seed=1)], combination_name='joint_set', rms_threshold=0.3, rmsd_method='tradeoff')
qm_atlas.workflows.rescoss_conformers.XTB_OPTIMIZATION_CONFIG: list[Annotated[XtbOptions | JobexOptions | XtbTurbomoleOptions, FieldInfo(annotation=NoneType, required=True, discriminator='backend')]] = [XtbOptions(backend='xtb', max_num_steps=100, method='2', opt_level='normal', solvation_model='alpb', solvent='water', constrain=False, torsions_fixed=False, heavy_atom_torsions_fixed=True, angles_fixed=False, bonds_fixed=False, force_constant=0.5)]
qm_atlas.workflows.rescoss_conformers.DEFAULT_FINAL_OPTIMIZATION_CONFIG: list[Annotated[XtbOptions | JobexOptions | XtbTurbomoleOptions, FieldInfo(annotation=NoneType, required=True, discriminator='backend')]] = [XtbTurbomoleOptions(backend='xtb_turbomole', max_num_steps=100, opt_level='normal', functional=['b-p'], basis='def2-TZVP', scf_conv=7, scfiterlimit=500, use_disp=False, use_cosmo=True, solvent='conductor', constrain=False, torsions_fixed=False, heavy_atom_torsions_fixed=True, angles_fixed=False, bonds_fixed=False, force_constant=0.5)]
qm_atlas.workflows.rescoss_conformers.RMSD_THRESHOLD = 0.3
qm_atlas.workflows.rescoss_conformers.DEFAULT_NUM_CLUSTERS = 3
qm_atlas.workflows.rescoss_conformers.DEFAULT_NUM_PER_CLUSTER = 3
qm_atlas.workflows.score_tautomers.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)[source]

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]

qm_atlas.workflows.score_tautomers.TAUTOMER_TM_SP_CONFIG = TurbomoleSinglePointOptions(property_prefix=None, backend='turbomole_single_point', basis='def2-mTZVP', functional=['b97-3c'], grid='m4', scf_conv=7, scfiterlimit=500, ricore=None, use_disp=False, use_cosmo=True, klamt=True, solvent='conductor', control_template=None)
qm_atlas.workflows.optimize_constrained.DEFAULT_SECOND_FORCE_CONSTANT = 0.1

The second of the two force constants the default configuration runs, so that a caller can see whether the answer depends on how tightly the pose was held. Both settings hold the restrained torsions: 0.5 to a few tenths of a degree, 0.1 to about two degrees. There is no longer any reason to go softer than this - the soft end of the old 0.5 / 0.1 / 0.01 ladder existed only to let the input geometry’s bond lengths and bond angles relax out of the restraint, and those are now unrestrained at every force constant.

qm_atlas.workflows.optimize_constrained.SETTINGS_CONSTRAINED_OPTIMIZATION_PROP = 'Settings_Constrained_Optimization'

Property under which each optimized reference conformer stores the constrained-optimization settings that produced it. A rerun compares requested settings against this to decide which (if any) still need to be computed.

qm_atlas.workflows.optimize_constrained.settings_key(config_list)[source]

Return a canonical, comparable key for one constrained-optimization config sublist.

The key is stored on every optimized reference conformer so a later rerun can tell which settings have already been computed and only run the missing ones. Keys are sorted so the comparison is independent of field ordering.

Parameters:

config_list (Sequence[XtbTurbomoleOptions | XtbOptions | JobexOptions]) – The sequence of optimization configurations that produce one result.

Returns:

A deterministic JSON string uniquely identifying the settings.

Return type:

str

qm_atlas.workflows.optimize_constrained.normalize_settings_key(raw)[source]

Return the canonical form of a settings key read from a stored property.

Re-serializes with sorted keys so keys written before this normalization (or with a different field order) still compare equal to freshly computed ones.

Parameters:

raw (str) – The raw JSON string stored in SETTINGS_CONSTRAINED_OPTIMIZATION_PROP.

Returns:

The normalized key, or the original string if it is not valid JSON.

Return type:

str

qm_atlas.workflows.optimize_constrained.optimize_fixed_mol(config_list, n_cores=1, mol=None, treat_unconverged_as_failure=False)[source]

Run constrained optimization with a list of configuration options.

Each configuration in the list is tried sequentially with fallback behavior.

Parameters:

  • config_list (Sequence[XtbTurbomoleOptions | XtbOptions | JobexOptions]) – Sequence of optimization configurations to try in order.

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

  • mol (Mol | None) – Molecule to optimize.

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

Return type:

Mol

Returns:

Optimized molecule.

qm_atlas.workflows.optimize_constrained.run_constrained_optimization(mol, n_cores=1, optimization_config=None, treat_unconverged_as_failure=False)[source]

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]

qm_atlas.workflows.optimize_constrained.DEFAULT_OPTIMIZATION_CONFIG = [[XtbTurbomoleOptions(backend='xtb_turbomole', max_num_steps=100, opt_level='normal', functional=['b-p'], basis='def2-TZVP', scf_conv=7, scfiterlimit=500, use_disp=False, use_cosmo=True, solvent='conductor', constrain=True, torsions_fixed=False, heavy_atom_torsions_fixed=True, angles_fixed=False, bonds_fixed=False, force_constant=0.5)], [XtbTurbomoleOptions(backend='xtb_turbomole', max_num_steps=100, opt_level='normal', functional=['b-p'], basis='def2-TZVP', scf_conv=7, scfiterlimit=500, use_disp=False, use_cosmo=True, solvent='conductor', constrain=True, torsions_fixed=False, heavy_atom_torsions_fixed=True, angles_fixed=False, bonds_fixed=False, force_constant=0.1)]]