Molecular Conformer Search & Ranking
Goal
Generate a diverse ensemble of low-energy conformers for a given molecule. The workflow combines:
- Stochastic sampling using RDKit's ETKDG algorithm (Experimental Torsion Distance Geometry).
- High-accuracy relaxation using Machine Learning Interatomic Potentials (MLIPs) to get near-DFT quality geometries and energies.
- Deduplication and Boltzmann weighting to identify the most relevant conformers at finite temperature.
[!IMPORTANT]
This skill is optimized for organic molecules and uses MACE-OFF23 models by default. For inorganic clusters, switch to MACE-OMAT or MatGL models.
Recommended Models
- MACE-OFF23:
MACE-OFF23-small (default), MACE-OFF23-medium — trained on organic molecules (Env: mace-agent)
- MACE-MH:
MACE-MH-1 with head omol — multi-head model with molecular head (Env: mace-agent)
- UMA:
uma-s-1p1 with head omol — general molecular model (Env: fairchem-agent)
1. Prerequisites
- Conda Environment:
mace-agent (recommended as it includes both mace and rdkit).
- Input: SMILES string or a structure file (
.xyz, .sdf, .mol2, .pdb).
2. Methodology
- Generation: Generate
N initial conformers using RDKit's EmbedMultipleConfs with ETKDGv3.
- Relaxation: Optimize the geometry of each conformer using the selected MLIP (fmax = 0.01 eV/Å).
- Deduplication/Clustering: Filter redundant conformers by simple RMSD thresholding (default), Hierarchical clustering, or K-Means clustering. Only the lowest-energy conformer in each cluster is kept.
- Ranking: Sort unique conformers by energy.
- Boltzmann Weighting: Calculate population probability $P_i$ at temperature $T$:
$$P_i = \frac{e^{-(E_i - E_{min}) / k_B T}}{\sum_j e^{-(E_j - E_{min}) / k_B T}}$$
3. Usage
Basic Usage (SMILES)
Generate 30 conformers for a molecule (e.g., aspirin) and relax with MACE-OFF23:
# Env: mace-agent
python .agents/skills/chem-conformer-search/scripts/conformer_search.py \
--smiles "CC(=O)Oc1ccccc1C(=O)O" \
--num_conformers 30 \
--output_dir research/aspirin_conformers
Advanced Usage (Structure File + Options)
# Env: mace-agent
python .agents/skills/chem-conformer-search/scripts/conformer_search.py \
--structure my_molecule.sdf \
--num_conformers 100 \
--rms_threshold 0.5 \
--dedup_threshold 0.1 \
--temperature 298.15 \
--model_type mace \
--model_name MACE-OFF23-small \
--device cuda \
--output_dir research/my_molecule_search
Key Parameters
| Argument |
Default |
Description |
--smiles |
- |
SMILES string of the molecule |
--structure |
- |
Path to input structure file (alternative to SMILES) |
--num_conformers |
50 |
Number of initial conformers to generate with RDKit |
--rms_threshold |
0.2 |
RDKit pruning threshold (Å) to discard similar initial conformers |
--clustering |
rmsd |
Method to filter conformers: rmsd, hierarchical, or kmeans |
--dedup_threshold |
0.1 |
Post-relaxation RMSD threshold (Å) to merge identical conformers or cut for hierarchical |
--num_clusters |
5 |
Number of clusters if --clustering kmeans is used |
--energy_threshold |
0.5 |
Max energy above global minimum (eV) to keep before RMSD comparison. Set to 0 to disable |
--fmax |
0.01 |
Force convergence criterion for relaxation (eV/Å) |
--temperature |
298.15 |
Temperature (K) for Boltzmann weighting |
--model_type |
mace |
MLIP backend (mace, matgl, fairchem) |
--model_name |
MACE-OFF23-small |
Specific model checkpoint to use |
4. Output Files
The output directory will contain:
conformer_results.json: A summary file containing:
- List of unique conformers with their energies, relative energies, and Boltzmann weights.
- Paths to the corresponding XYZ files.
- Metadata (model used, parameters).
conf_000.xyz, conf_001.xyz, ...: The relaxed structures of the unique conformers, sorted by energy (000 is the global minimum found).
5. Examples
See examples/aspirin for a complete example run on Acetylsalicylic acid.
6. Constraints
- Environment: Use the conda environment matching the chosen model:
mace-agent (MACE), fairchem-agent (FairChem/UMA), or matgl-agent (MatGL). All include RDKit.
- Input: Either
--smiles or --structure must be provided, but not both.
- Molecule Type: Optimized for organic molecules. For inorganic clusters, switch to
MACE-OMAT or MatGL models.
- Non-periodic: All conformers are treated as non-periodic (isolated molecules).
7. References
- Riniker, S.; Landrum, G. A., "Better Informed Distance Geometry: Using What We Know To Improve Conformation Generation", J. Chem. Inf. Model., 2015, 55, 2562. DOI
Author: Bowen Deng
Contact: GitHub @learningmatter-mit
1---2name: chem-conformer-search3description: Generate molecular conformers with RDKit ETKDG, relax with MLIPs, and rank by energy with Boltzmann weighting.4---56# Molecular Conformer Search & Ranking78## Goal910Generate a diverse ensemble of low-energy conformers for a given molecule. The workflow combines:111. **Stochastic sampling** using RDKit's ETKDG algorithm (Experimental Torsion Distance Geometry).122. **High-accuracy relaxation** using Machine Learning Interatomic Potentials (MLIPs) to get near-DFT quality geometries and energies.133. **Deduplication** and **Boltzmann weighting** to identify the most relevant conformers at finite temperature.1415> [!IMPORTANT]16> This skill is optimized for **organic molecules** and uses `MACE-OFF23` models by default. For inorganic clusters, switch to `MACE-OMAT` or `MatGL` models.1718### Recommended Models1920- **MACE-OFF23**: `MACE-OFF23-small` (default), `MACE-OFF23-medium` — trained on organic molecules (Env: `mace-agent`)21- **MACE-MH**: `MACE-MH-1` with head `omol` — multi-head model with molecular head (Env: `mace-agent`)22- **UMA**: `uma-s-1p1` with head `omol` — general molecular model (Env: `fairchem-agent`)2324## 1. Prerequisites2526- **Conda Environment**: `mace-agent` (recommended as it includes both `mace` and `rdkit`).27- **Input**: SMILES string or a structure file (`.xyz`, `.sdf`, `.mol2`, `.pdb`).2829## 2. Methodology30311. **Generation**: Generate `N` initial conformers using RDKit's `EmbedMultipleConfs` with ETKDGv3.322. **Relaxation**: Optimize the geometry of *each* conformer using the selected MLIP (fmax = 0.01 eV/Å).333. **Deduplication/Clustering**: Filter redundant conformers by simple RMSD thresholding (default), Hierarchical clustering, or K-Means clustering. Only the lowest-energy conformer in each cluster is kept.344. **Ranking**: Sort unique conformers by energy.355. **Boltzmann Weighting**: Calculate population probability $P_i$ at temperature $T$:36 $$P_i = \frac{e^{-(E_i - E_{min}) / k_B T}}{\sum_j e^{-(E_j - E_{min}) / k_B T}}$$3738## 3. Usage3940### Basic Usage (SMILES)4142Generate 30 conformers for a molecule (e.g., aspirin) and relax with MACE-OFF23:4344```bash45# Env: mace-agent46python .agents/skills/chem-conformer-search/scripts/conformer_search.py \47 --smiles "CC(=O)Oc1ccccc1C(=O)O" \48 --num_conformers 30 \49 --output_dir research/aspirin_conformers50```5152### Advanced Usage (Structure File + Options)5354```bash55# Env: mace-agent56python .agents/skills/chem-conformer-search/scripts/conformer_search.py \57 --structure my_molecule.sdf \58 --num_conformers 100 \59 --rms_threshold 0.5 \60 --dedup_threshold 0.1 \61 --temperature 298.15 \62 --model_type mace \63 --model_name MACE-OFF23-small \64 --device cuda \65 --output_dir research/my_molecule_search66```6768### Key Parameters6970| Argument | Default | Description |71|:---|:---|:---|72| `--smiles` | - | SMILES string of the molecule |73| `--structure` | - | Path to input structure file (alternative to SMILES) |74| `--num_conformers` | 50 | Number of initial conformers to generate with RDKit |75| `--rms_threshold` | 0.2 | RDKit pruning threshold (Å) to discard similar initial conformers |76| `--clustering` | `rmsd` | Method to filter conformers: `rmsd`, `hierarchical`, or `kmeans` |77| `--dedup_threshold` | 0.1 | Post-relaxation RMSD threshold (Å) to merge identical conformers or cut for hierarchical |78| `--num_clusters` | 5 | Number of clusters if `--clustering kmeans` is used |79| `--energy_threshold` | 0.5 | Max energy above global minimum (eV) to keep before RMSD comparison. Set to 0 to disable |80| `--fmax` | 0.01 | Force convergence criterion for relaxation (eV/Å) |81| `--temperature` | 298.15 | Temperature (K) for Boltzmann weighting |82| `--model_type` | `mace` | MLIP backend (`mace`, `matgl`, `fairchem`) |83| `--model_name` | `MACE-OFF23-small` | Specific model checkpoint to use |8485## 4. Output Files8687The output directory will contain:88891. **`conformer_results.json`**: A summary file containing:90 - List of unique conformers with their energies, relative energies, and Boltzmann weights.91 - Paths to the corresponding XYZ files.92 - Metadata (model used, parameters).932. **`conf_000.xyz`, `conf_001.xyz`, ...**: The relaxed structures of the unique conformers, sorted by energy (000 is the global minimum found).9495## 5. Examples9697See `examples/aspirin` for a complete example run on Acetylsalicylic acid.9899## 6. Constraints100101- **Environment**: Use the conda environment matching the chosen model: `mace-agent` (MACE), `fairchem-agent` (FairChem/UMA), or `matgl-agent` (MatGL). All include RDKit.102- **Input**: Either `--smiles` or `--structure` must be provided, but not both.103- **Molecule Type**: Optimized for organic molecules. For inorganic clusters, switch to `MACE-OMAT` or `MatGL` models.104- **Non-periodic**: All conformers are treated as non-periodic (isolated molecules).105106## 7. References107108- Riniker, S.; Landrum, G. A., "Better Informed Distance Geometry: Using What We Know To Improve Conformation Generation", *J. Chem. Inf. Model.*, 2015, 55, 2562. [DOI](https://doi.org/10.1021/acs.jcim.5b00654)109110---111112**Author:** Bowen Deng113**Contact:** [GitHub @learningmatter-mit](https://github.com/learningmatter-mit)
learningmatter-mit