跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
其他技能

chem-conformer-search

Generate molecular conformers with RDKit ETKDG, relax with MLIPs, and rank by energy with Boltzmann weighting.

learningmatter-mit · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add learningmatter-mit/AtomisticSkills --skill chem-conformer-search

技能说明


name: chem-conformer-search description: Generate molecular conformers with RDKit ETKDG, relax with MLIPs, and rank by energy with Boltzmann weighting. category: [chemistry]

Molecular Conformer Search & Ranking

Goal

Generate a diverse ensemble of low-energy conformers for a given molecule. The workflow combines:

  1. Stochastic sampling using RDKit's ETKDG algorithm (Experimental Torsion Distance Geometry).
  2. High-accuracy relaxation using Machine Learning Interatomic Potentials (MLIPs) to get near-DFT quality geometries and energies.
  3. 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

  1. Generation: Generate N initial conformers using RDKit's EmbedMultipleConfs with ETKDGv3.
  2. Relaxation: Optimize the geometry of each conformer using the selected MLIP (fmax = 0.01 eV/Å).
  3. 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.
  4. Ranking: Sort unique conformers by energy.
  5. 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

ArgumentDefaultDescription
--smiles-SMILES string of the molecule
--structure-Path to input structure file (alternative to SMILES)
--num_conformers50Number of initial conformers to generate with RDKit
--rms_threshold0.2RDKit pruning threshold (Å) to discard similar initial conformers
--clusteringrmsdMethod to filter conformers: rmsd, hierarchical, or kmeans
--dedup_threshold0.1Post-relaxation RMSD threshold (Å) to merge identical conformers or cut for hierarchical
--num_clusters5Number of clusters if --clustering kmeans is used
--energy_threshold0.5Max energy above global minimum (eV) to keep before RMSD comparison. Set to 0 to disable
--fmax0.01Force convergence criterion for relaxation (eV/Å)
--temperature298.15Temperature (K) for Boltzmann weighting
--model_typemaceMLIP backend (mace, matgl, fairchem)
--model_nameMACE-OFF23-smallSpecific model checkpoint to use

4. Output Files

The output directory will contain:

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