rdkit-conf · v1.0 · 2026-03-24 · sha256 a4863177305c387b
rdkit-conf v1.0A
Immutable. This exact content is served forever at /api/v1/blob/a4863177305c387b.
---
name: rdkit-conf
description: >
A standardized CLI wrapper for RDKit 3D/2D conformer generation that samples multiple
conformers per molecule (ETKDGv3, default 10), optimizes each with a force field
(MMFF94s/UFF), keeps the lowest-energy conformer, automatically falls back to 2D layout
on total embedding failure with a printed warning, and writes results to SDF or XYZ format.
USE WHEN you need to generate 3D (or 2D fallback) molecular geometries from SMILES
datasets (.csv/.smi) for downstream tasks such as docking, visualization, or
3D-descriptor computation.
compatibility: Requires uv. Dependencies (rdkit, pandas) are declared as PEP 723 inline script metadata and are installed automatically when the script is invoked with `uv run <script_path>` (do NOT use `uv run python <script_path>` -- that bypasses the inline metadata and will not install dependencies automatically).
metadata:
author: luzitian
version: '1.0'
repository: https://github.com/rdkit/rdkit
---
# RDKit Conformer Generation
This skill provides practical command patterns for **RDKit 3D/2D conformer generation**
using the standardized CLI wrapper: `<skill_path>/scripts/rdkit_conf_helper.py`.
Key behaviors (important for Agents):
- The script prints **environment detection** (Python/RDKit/Pandas) by default.
- **Multi-conformer sampling**: embeds `--num-confs` conformers (default 10) per molecule
via `EmbedMultipleConfs`, optimizes each with the chosen force field, and keeps the
**lowest-energy** one. Set `--num-confs 1` to revert to single-conformer behavior.
- **2D fallback**: if all 3D embedding attempts fail, `Compute2DCoords` is used instead
and a `[WARN]` line is printed to stderr for that molecule.
- Bad/illegal SMILES are **skipped entirely** and logged to `*.skipped.csv` (no crash).
- Molecules that fell back to 2D are **additionally logged** to `*.fallback.csv`.
- Each run ends with a summary line and **absolute output paths**:
- `[INFO] Done: <N_3d> 3D, <N_2d> 2D-fallback, <N_skip> skipped (total input: <N>)`
- `[RESULT] conf_sdf=/abs/path.sdf`
- `[RESULT] conf_xyz=/abs/path.xyz`
- `[RESULT] fallback_csv=/abs/path.fallback.csv` (only if any 2D fallbacks occurred)
- `[RESULT] skipped_csv=/abs/path.skipped.csv` (only if any SMILES were skipped)
## Quick Start
Check CLI help:
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py --help
uv run <skill_path>/scripts/rdkit_conf_helper.py conf --help
```
Disable environment printing (optional):
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py --no-env conf --smiles "CCO" --output out.sdf
```
## Core Tasks
### 1) Generate 3D conformers (SDF output, default)
Single SMILES:
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py conf \
--smiles "CCO" \
--output /tmp/CCO.sdf
```
Single SMILES with a custom molecule name:
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py conf \
--smiles "c1ccccc1" \
--name benzene \
--output /tmp/benzene.sdf
```
From CSV (default SMILES column: `smiles`):
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py conf \
--file data.csv \
--smiles-col smiles \
--output data.sdf
```
From CSV with a name column:
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py conf \
--file data.csv \
--smiles-col smiles \
--name-col compound_id \
--output data.sdf
```
From SMI (second token per line is used as name automatically):
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py conf \
--file molecules.smi \
--output molecules.sdf
```
### 2) Control conformer sampling count
Default (10 conformers sampled, lowest-energy kept):
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py conf \
--file data.csv --output data.sdf
```
Single conformer (fastest, least thorough):
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py conf \
--file data.csv --num-confs 1 --output data.sdf
```
Increase sampling for flexible or macrocyclic molecules:
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py conf \
--file data.csv --num-confs 50 --output data.sdf
```
### 3) Choose force-field minimization
MMFF94s (default, falls back to UFF if unavailable):
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py conf \
--file data.csv --ff mmff94s --output data.mmff.sdf
```
UFF (universal force field):
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py conf \
--file data.csv --ff uff --output data.uff.sdf
```
Skip force-field optimization (raw ETKDG geometry only):
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py conf \
--file data.csv --ff none --output data.etkdg_raw.sdf
```
### 4) XYZ output
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py conf \
--file data.csv \
--format xyz \
--output data.xyz
```
### 5) Tuning embedding for difficult molecules
Large or macrocyclic molecules sometimes fail standard ETKDG; try random initial coordinates:
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py conf \
--file macrocycles.csv \
--use-random-coords \
--max-attempts 500 \
--output macrocycles.sdf
```
Use a different random seed (reproducibility):
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py conf \
--file data.csv --seed 123 --output data.seed123.sdf
```
Non-deterministic embedding (seed = -1):
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py conf \
--file data.csv --seed -1 --output data.sdf
```
### 6) Suppress hydrogen addition
By default explicit H atoms are added before embedding for more accurate 3D geometry.
Use `--no-hs` to keep the molecule as-is (heavy atoms only):
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py conf \
--file data.csv --no-hs --output data.noh.sdf
```
### 7) Custom log file paths
```bash
uv run <skill_path>/scripts/rdkit_conf_helper.py conf \
--file data.csv \
--output data.sdf \
--error-log logs/skipped.csv \
--fallback-log logs/used_2d.csv
```
______________________________________________________________________
## 3D Embedding Pipeline Details
For each molecule, the script runs the following steps in order:
1. **Parse SMILES** via `Chem.MolFromSmiles`.
1. **Add hydrogens** (`Chem.AddHs`) -- skipped with `--no-hs`.
1. **Multi-conformer 3D embedding** (`EmbedMultipleConfs`, `--num-confs` candidates,
default 10): tries ETKDGv3, then ETKDGv2, then ETDG, then ETDG+`useRandomCoords`
as a fallback chain until at least one conformer is embedded.
1. **Force-field minimization** (if `--ff` is not `none`): each successfully embedded
conformer is individually optimized. MMFF94s transparently falls back to UFF if
parameters are unavailable for that molecule.
1. **Lowest-energy selection**: the conformer with the minimum post-optimization energy
is retained; all others are discarded. If `--ff none`, the first embedded conformer
is kept without energy ranking.
1. **2D fallback** (if all 3D attempts yield zero conformers): generates a flat 2D layout
via `Compute2DCoords` (Z=0 for all atoms), prints a `[WARN]` to stderr, and records
the molecule in the fallback log.
______________________________________________________________________
## Output Format Notes
**SDF output (`--format sdf`, default):**
- Standard V2000 multi-molecule SDF, one conformer per molecule.
- Molecule name (from `--name`, `--name-col`, or auto-generated `mol_<i>`) is
written to the SDF header line.
- Compatible with most cheminformatics tools (RDKit, OpenBabel, Schrodinger, etc.).
**XYZ output (`--format xyz`):**
- Concatenated XYZ blocks (element, x, y, z per atom).
- Molecule name is written as the comment line (second line of each block).
- Coordinates are in Angstroms.
- Note: if `--no-hs` is used, hydrogen atoms are absent from the XYZ.
**Fallback log (`*.fallback.csv`):**
- Written only when at least one molecule fell back to 2D.
- Columns: `idx`, `smiles`, `name`, `dim` (always 2), `ff` (always `2d_fallback`), `note`.
**Skipped log (`*.skipped.csv`):**
- Written only when at least one SMILES was skipped.
- Columns: `idx`, `smiles`, `error`.
______________________________________________________________________
## Agent Checklist
When using this skill for users:
1. Confirm input format:
- `.csv` requires a SMILES column (default `smiles`)
- `.smi` uses the first token per line as SMILES, second token (if present) as name
1. Quote SMILES containing special shell characters (brackets/parentheses):
- Example: `--smiles "[C@@H](O)(F)Cl"`
1. For CSV workflows, verify column names:
- `--smiles-col` for the SMILES column
- `--name-col` (optional) for molecule identifiers to embed in SDF/XYZ headers
1. Check the `[INFO] Done:` summary line for the 3D/2D/skip breakdown.
1. If 2D fallbacks occurred, inspect `*.fallback.csv`:
- Consider `--use-random-coords` or `--max-attempts` tuning for the affected SMILES.
- 2D conformers have Z=0 and are not suitable for 3D-based applications (docking, 3D QSAR).
1. Always capture absolute output paths:
- Look for `[RESULT] ...=/abs/path` in stdout.
1. If debugging is needed, enable full traceback:
- `RDKIT_CONF_HELPER_TRACE=1 uv run <skill_path>/scripts/rdkit_conf_helper.py ...`
## References
- RDKit conformer generation guide: https://www.rdkit.org/docs/GettingStartedInPython.html#working-with-3d-molecules
- ETKDG paper: Riniker & Landrum, J. Chem. Inf. Model. 2015, 55, 2562
- ETKDGv3: Wang et al., J. Chem. Inf. Model. 2020, 60, 2044