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.
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).
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:
For each molecule, the script runs the following steps in order:
Parse SMILES via Chem.MolFromSmiles.
Add hydrogens (Chem.AddHs) -- skipped with --no-hs.
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.
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.
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.
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.
Written only when at least one SMILES was skipped.
Columns: idx, smiles, error.
Agent Checklist
When using this skill for users:
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
Quote SMILES containing special shell characters (brackets/parentheses):
Example: --smiles "[C@@H](O)(F)Cl"
For CSV workflows, verify column names:
--smiles-col for the SMILES column
--name-col (optional) for molecule identifiers to embed in SDF/XYZ headers
Check the [INFO] Done: summary line for the 3D/2D/skip breakdown.
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).
Always capture absolute output paths:
Look for [RESULT] ...=/abs/path in stdout.
If debugging is needed, enable full traceback:
RDKIT_CONF_HELPER_TRACE=1 uv run <skill_path>/scripts/rdkit_conf_helper.py ...
GPUMD integration
RDKit conformer generation can produce initial molecular geometries for
Packmol packing or as starting structures for GPUMD molecular simulations.
XYZ output can be converted to GPUMD model.xyz format via dpdata or ASE.
