K-Dense-AI/scientific-agent-skills / skills/rdkit
rdkit
VerifiedCheminformatics toolkit for fine-grained molecular control. SMILES/SDF parsing, descriptors (MW, LogP, TPSA), fingerprints, substructure search, 2D/3D generation, similarity, reactions. For standard workflows with simpler interface, use datamol (wrapper around RDKit). Use rdkit for advanced control, custom sanitization, specialized algorithms.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.7 KB |
| references/api_reference.md | markdown | 18.4 KB |
| references/core_capabilities.md | markdown | 17.6 KB |
| references/descriptors_reference.md | markdown | 12.4 KB |
| references/review.md | markdown | 5.3 KB |
| references/smarts_patterns.md | markdown | 7.8 KB |
| references/workflows_and_best_practices.md | markdown | 8.3 KB |
| scripts/_common.py | script | 2.6 KB |
| scripts/molecular_properties.py | script | 7.1 KB |
| scripts/similarity_search.py | script | 10.3 KB |
| scripts/substructure_filter.py | script | 12.7 KB |
references/core_capabilities.md
View on GitHub# RDKit Core Capabilities
The twelve capability areas in full, with worked code: molecular I/O and creation,
sanitization and validation, analysis and properties, descriptors, fingerprints and
similarity, substructure searching with SMARTS, chemical reactions, 2D/3D coordinate
generation, visualization, molecular modification, hashes and standardization, and
pharmacophore and 3D features.
Code fragments with undefined inputs such as `mol1`, paths, or atom IDs are
illustrative templates. The checked, self-contained examples and coverage are
listed in [review.md](review.md).
## Core Capabilities
### 1. Molecular I/O and Creation
**Reading Molecules:**
Read molecular structures from various formats:
```python
from rdkit import Chem
# From SMILES strings
mol = Chem.MolFromSmiles('Cc1ccccc1') # Returns Mol object or None
# From MOL files
mol = Chem.MolFromMolFile('path/to/file.mol')
# From MOL blocks (string data)
mol = Chem.MolFromMolBlock(mol_block_string)
# From InChI
mol = Chem.MolFromInchi('InChI=1S/C6H6/c1-2-4-6-5-3-1/h1-6H')
```
**Writing Molecules:**
Convert molecules to text representations:
```python
# To canonical SMILES
smiles = Chem.MolToSmiles(mol)
# To MOL block
mol_block = Chem.MolToMolBlock(mol)
# To InChI
inchi = Chem.MolToInchi(mol)
```
**Batch Processing:**
For processing multiple molecules, use Supplier/Writer objects:
```python
# Read SDF files
suppl = Chem.SDMolSupplier('molecules.sdf')
for mol in suppl:
if mol is not None: # Check for parsing errors
# Process molecule
pass
# Read SMILES files
suppl = Chem.SmilesMolSupplier('molecules.smi', titleLine=False)
smiles_mols = [m for m in suppl if m is not None] # iterate, do not use list(suppl)
# For large files or compressed data
import gzip
with gzip.open('molecules.sdf.gz') as f:
suppl = Chem.ForwardSDMolSupplier(f)
for mol in suppl:
# Process molecule
pass
# Multithreaded processing for large datasets
suppl = Chem.MultithreadedSDMolSupplier('molecules.sdf')
# Write molecules to SDF
writer = Chem.SDWriter('output.sdf')
for mol in molecules:
writer.write(mol)
writer.close()
```
**Important Notes:**
- Tested 2026.03.6 behavior: `list(SmilesMolSupplier(...))` on a fresh supplier
can return an empty list because of length-hint interaction. A comprehension or
ordinary iteration reads the records correctly; the bundled reader uses source
lines directly.
- Multithreaded suppliers are still marked experimental upstream; they may
reorder results. Save `GetLastRecordId()` at each iteration.
- Many molecular parse failures return `None`; missing files, wrong argument types,
and some sanitization errors raise exceptions. Empty SMILES gives a zero-atom Mol; reject it for these workflows.
- Always check for `None` before processing molecules
- Molecules are automatically sanitized on import (validates valence, perceives aromaticity)
### 2. Molecular Sanitization and Validation
RDKit automatically sanitizes molecules during parsing, checking supported valences and assigning graph properties such as aromaticity.
This is not a chemical plausibility, stability, or synthetic-feasibility proof.
**Sanitization Control:**
```python
# Disable automatic sanitization
mol = Chem.MolFromSmiles('C1=CC=CC=C1', sanitize=False)
# Manual sanitization
Chem.SanitizeMol(mol)
# Detect problems before sanitization
problems = Chem.DetectChemistryProblems(mol)
for problem in problems:
print(problem.GetType(), problem.Message())
# Partial sanitization (skip specific steps)
Chem.SanitizeMol(mol, sanitizeOps=Chem.SANITIZE_ALL ^ Chem.SANITIZE_PROPERTIES)
```
**Common Sanitization Issues:**
- Atoms with explicit valence exceeding maximum allowed will raise exceptions
- Invalid aromatic rings will cause kekulization errors
- Radical electrons may not be properly assigned without explicit specification
### 3. Molecular Analysis and Properties
**Accessing Molecular Structure:**
```python
# Iterate atoms and bonds
for atom in mol.GetAtoms():
print(atom.GetSymbol(), atom.GetIdx(), atom.GetDegree())
for bond in mol.GetBonds():
print(bond.GetBeginAtomIdx(), bond.GetEndAtomIdx(), bond.GetBondType())
# Ring information
ring_info = mol.GetRingInfo()
ring_info.NumRings()
ring_info.AtomRings() # Returns tuples of atom indices
# Check if atom is in ring
atom = mol.GetAtomWithIdx(0)
atom.IsInRing()
atom.IsInRingSize(6) # Check for 6-membered rings
# Find the symmetrized SSSR (can contain more rings than the minimal SSSR)
from rdkit.Chem import GetSymmSSSR
rings = GetSymmSSSR(mol)
```
**Stereochemistry:**
```python
# Find chiral centers
from rdkit.Chem import FindMolChiralCenters
chiral_centers = FindMolChiralCenters(mol, includeUnassigned=True,
useLegacyImplementation=False)
# Returns list of (atom_idx, chirality) tuples
# Assign stereochemistry from existing 3D coordinates; this may overwrite tags
from rdkit.Chem import AssignStereochemistryFrom3D
AssignStereochemistryFrom3D(mol)
# Check bond stereochemistry
bond = mol.GetBondWithIdx(0)
stereo = bond.GetStereo() # STEREONONE, STEREOZ, STEREOE, etc.
```
**Fragment Analysis:**
```python
# Get disconnected fragments
frags = Chem.GetMolFrags(mol, asMols=True)
# Fragment on specific bonds
from rdkit.Chem import FragmentOnBonds
frag_mol = FragmentOnBonds(mol, [bond_idx1, bond_idx2])
# Extract Murcko scaffold (not a ring-system count)
from rdkit.Chem.Scaffolds import MurckoScaffold
scaffold = MurckoScaffold.GetScaffoldForMol(mol)
```
### 4. Molecular Descriptors and Properties
**Basic Descriptors:**
```python
from rdkit.Chem import Descriptors
# Molecular weight
mw = Descriptors.MolWt(mol)
exact_mw = Descriptors.ExactMolWt(mol)
# LogP (lipophilicity)
logp = Descriptors.MolLogP(mol)
# Topological polar surface area
tpsa = Descriptors.TPSA(mol)
# Number of hydrogen bond donors/acceptors
hbd = Descriptors.NumHDonors(mol)
hba = Descriptors.NumHAcceptors(mol)
# Number of rotatable bonds
rot_bonds = Descriptors.NumRotatableBonds(mol)
# Number of aromatic rings
aromatic_rings = Descriptors.NumAromaticRings(mol)
```
**Batch Descriptor Calculation:**
```python
# Calculate all descriptors at once
all_descriptors = Descriptors.CalcMolDescriptors(mol)
# Returns dictionary: {'MolWt': 180.16, 'MolLogP': 1.23, ...}
# Get list of available descriptor names
descriptor_names = [desc[0] for desc in Descriptors._descList]
```
**Lipinski's Rule of Five:**
```python
# Check drug-likeness
mw = Descriptors.MolWt(mol) <= 500
logp = Descriptors.MolLogP(mol) <= 5
hbd = Descriptors.NumHDonors(mol) <= 5
hba = Descriptors.NumHAcceptors(mol) <= 10
is_drug_like = mw and logp and hbd and hba
```
### 5. Fingerprints and Molecular Similarity
**Fingerprint Types:**
```python
from rdkit.Chem import rdFingerprintGenerator
from rdkit.Chem import MACCSkeys
# RDKit topological fingerprint
rdk_gen = rdFingerprintGenerator.GetRDKitFPGenerator(minPath=1, maxPath=7, fpSize=2048)
fp = rdk_gen.GetFingerprint(mol)
# Morgan fingerprints (circular fingerprints, similar to ECFP)
# Modern API using rdFingerprintGenerator
morgan_gen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048)
fp = morgan_gen.GetFingerprint(mol)
# Count-based fingerprint
fp_count = morgan_gen.GetCountFingerprint(mol)
# MACCS keys: 167-bit vector, 166 keys and unused bit 0
fp = MACCSkeys.GenMACCSKeys(mol)
# Atom pair fingerprints
ap_gen = rdFingerprintGenerator.GetAtomPairGenerator()
fp = ap_gen.GetFingerprint(mol)
# Topological torsion fingerprints
tt_gen = rdFingerprintGenerator.GetTopologicalTorsionGenerator()
fp = tt_gen.GetFingerprint(mol)
# Avalon fingerprints (if available)
from rdkit.Avalon import pyAvalonTools
fp = pyAvalonTools.GetAvalonFP(mol)
```
**Similarity Calculation:**
```python
from rdkit import DataStructs
from rdkit.Chem import rdFingerprintGenerator
# Generate fingerprints using generator
mfpgen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048)
fp1 = mfpgen.GetFingerprint(mol1)
fp2 = mfpgen.GetFingerprint(mol2)
# Calculate Tanimoto similarity
similarity = DataStructs.TanimotoSimilarity(fp1, fp2)
# Calculate similarity for multiple molecules
fps = [mfpgen.GetFingerprint(m) for m in [mol2, mol3, mol4]]
similarities = DataStructs.BulkTanimotoSimilarity(fp1, fps)
# Other similarity metrics
dice = DataStructs.DiceSimilarity(fp1, fp2)
cosine = DataStructs.CosineSimilarity(fp1, fp2)
```
**Clustering and Diversity:**
```python
# Butina clustering based on fingerprint similarity
from rdkit.ML.Cluster import Butina
# Calculate distance matrix
dists = []
mfpgen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048)
fps = [mfpgen.GetFingerprint(mol) for mol in mols]
for i in range(len(fps)):
sims = DataStructs.BulkTanimotoSimilarity(fps[i], fps[:i])
dists.extend([1-sim for sim in sims])
# Cluster with distance cutoff
clusters = Butina.ClusterData(dists, len(fps), distThresh=0.3, isDistData=True)
```
### 6. Substructure Searching and SMARTS
**Basic Substructure Matching:**
```python
# Define query using SMARTS
query = Chem.MolFromSmarts('[#6]1:[#6]:[#6]:[#6]:[#6]:[#6]:1') # Benzene ring
# Check if molecule contains substructure
has_match = mol.HasSubstructMatch(query)
# Get all matches (returns tuple of tuples with atom indices)
matches = mol.GetSubstructMatches(query)
# Get only first match
match = mol.GetSubstructMatch(query)
```
**Common SMARTS Patterns:**
```python
# Primary alcohols
primary_alcohol = Chem.MolFromSmarts('[CH2][OH1]')
# Carboxylic acids
carboxylic_acid = Chem.MolFromSmarts('C(=O)[OH]')
# Amides
amide = Chem.MolFromSmarts('C(=O)N')
# Aromatic heterocycles
aromatic_n = Chem.MolFromSmarts('[nR]') # Aromatic nitrogen in ring
# Atoms whose smallest ring has at least 12 atoms
macrocycle = Chem.MolFromSmarts('[r{12-}]')
```
**Matching Rules:**
- Unspecified properties in query match any value in target
- Hydrogen count, explicit H atoms, aromaticity, and charge are query-specific.
Stereo is ignored by default; set `useChirality=True` for specified query stereo.
- Charged query atom won't match uncharged target atom
- Aromatic query atom won't match aliphatic target atom (unless query is generic)
### 7. Chemical Reactions
**Reaction SMARTS:**
```python
from rdkit.Chem import AllChem
# Define reaction using SMARTS: reactants >> products
rxn = AllChem.ReactionFromSmarts('[C:1]=[O:2]>>[C:1][O:2]') # Carbonyl bond-order transform
# Apply reaction to molecules
reactants = (mol1,)
products = rxn.RunReactants(reactants)
# Products is tuple of tuples (one tuple per product set)
for product_set in products:
for product in product_set:
# Sanitize product
Chem.SanitizeMol(product)
```
**Reaction Features:**
- Atom mapping preserves specific atoms between reactants and products
- Dummy atoms in products are replaced by corresponding reactant atoms
- "Any" bonds inherit bond order from reactants
- Stereo handling depends on mapped atoms and reaction stereo annotations; test
representative stereoisomers. Products are unsanitized and may duplicate across
matches. `RunReactants(..., maxProducts=1000)` defaults to a cap; hitting it may
mean truncation. A graph transform does not predict reagents, yield, feasibility,
selectivity, or a balanced experimental reaction.
**Reaction Similarity:**
```python
# Generate reaction fingerprints
fp = AllChem.CreateDifferenceFingerprintForReaction(rxn)
# Compare reactions
similarity = DataStructs.TanimotoSimilarity(fp1, fp2)
```
### 8. 2D and 3D Coordinate Generation
**2D Coordinate Generation:**
```python
from rdkit.Chem import AllChem
# Depict a copy: Compute2DCoords clears existing conformers by default
depiction = Chem.Mol(mol)
AllChem.Compute2DCoords(depiction)
# Align molecule to template structure
template = Chem.MolFromSmiles('c1ccccc1')
AllChem.Compute2DCoords(template)
AllChem.GenerateDepictionMatching2DStructure(mol, template)
```
**3D Coordinate Generation and Conformers:**
```python
from rdkit import Chem
from rdkit.Chem import AllChem
mol3d = Chem.AddHs(Chem.MolFromSmiles('CCCO'))
params = AllChem.ETKDGv3()
params.randomSeed = 42
params.numThreads = 1
params.trackFailures = True
conf_ids = list(AllChem.EmbedMultipleConfs(mol3d, numConfs=5, params=params))
if not conf_ids:
raise RuntimeError(f"Embedding failed: {params.GetFailureCounts()}")
if not AllChem.MMFFHasAllMoleculeParams(mol3d):
raise ValueError("MMFF parameters unavailable for this chemistry")
results = AllChem.MMFFOptimizeMoleculeConfs(mol3d, numThreads=1, maxIters=500)
# Conformer IDs are identifiers, not necessarily dense list positions.
energies = {cid: energy for cid, (status, energy) in zip(conf_ids, results)
if status == 0}
if not energies:
raise RuntimeError("No converged MMFF conformer")
best_id = min(energies, key=energies.get)
print(best_id, energies[best_id]) # energy in kcal/mol; coordinates in angstrom
```
Single-conformer optimization returns 0 for convergence, 1 for an iteration limit;
MMFF additionally returns -1 if setup fails. UFF needs its own
`UFFHasAllMoleculeParams` check. Do not silently switch force fields and compare
energies. These are local force-field energies, not free energies, conformer
populations, binding affinities, or guarantees of global minima. For RMSD,
`AllChem.GetConformerRMS(mol, id1, id2)` aligns and mutates conformers by default;
use a copy when retaining original coordinates. RMSD is in angstrom and depends
on atom mapping, H inclusion, and symmetry treatment.
**Constrained Embedding:**
```python
# Embed with part of molecule constrained to specific coordinates
embedded = AllChem.ConstrainedEmbed(mol, core_mol) # core must have 3D coordinates
```
### 9. Molecular Visualization
**Basic Drawing:**
```python
from rdkit.Chem import Draw
# Draw single molecule to PIL image
img = Draw.MolToImage(mol, size=(300, 300))
img.save('molecule.png')
# Draw to file directly
Draw.MolToFile(mol, 'molecule.png')
# Draw multiple molecules in grid
mols = [mol1, mol2, mol3, mol4]
img = Draw.MolsToGridImage(mols, molsPerRow=2, subImgSize=(200, 200))
```
**Highlighting Substructures:**
```python
# Highlight substructure match
query = Chem.MolFromSmarts('c1ccccc1')
match = mol.GetSubstructMatch(query)
img = Draw.MolToImage(mol, highlightAtoms=match)
# Custom highlight colors
highlight_colors = {atom_idx: (1, 0, 0) for atom_idx in match} # Red
img = Draw.MolToImage(mol, highlightAtoms=match,
highlightAtomColors=highlight_colors)
```
**Customizing Visualization:**
```python
from rdkit.Chem.Draw import rdMolDraw2D
# Create drawer with custom options
drawer = rdMolDraw2D.MolDraw2DCairo(300, 300)
opts = drawer.drawOptions()
# Customize options
opts.addAtomIndices = True
opts.addStereoAnnotation = True
opts.bondLineWidth = 2
# Draw molecule
drawer.DrawMolecule(mol)
drawer.FinishDrawing()
# Save to file
with open('molecule.png', 'wb') as f:
f.write(drawer.GetDrawingText())
```
**Jupyter Notebook Integration:**
```python
# Enable inline display in Jupyter
from rdkit.Chem.Draw import IPythonConsole
# Customize default display
IPythonConsole.ipython_useSVG = True # Use SVG instead of PNG
IPythonConsole.molSize = (300, 300) # Default size
# Molecules now display automatically
mol # Shows molecule image
```
**Visualizing Fingerprint Bits:**
```python
# Show what molecular features a fingerprint bit represents
from rdkit.Chem import Draw
from rdkit.Chem import rdFingerprintGenerator
# For Morgan fingerprints
additional_output = rdFingerprintGenerator.AdditionalOutput()
additional_output.AllocateBitInfoMap()
morgan_gen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048)
fp = morgan_gen.GetFingerprint(mol, additionalOutput=additional_output)
bit_info = additional_output.GetBitInfoMap()
# Draw environment for specific bit
img = Draw.DrawMorganBit(mol, bit_id, bit_info)
```
### 10. Molecular Modification
**Adding/Removing Hydrogens:**
```python
# Add explicit hydrogens
mol_h = Chem.AddHs(mol)
# Remove explicit hydrogens
mol = Chem.RemoveHs(mol_h)
```
**Kekulization and Aromaticity:**
```python
# Convert aromatic bonds to alternating single/double
Chem.Kekulize(mol)
# Set aromaticity
Chem.SetAromaticity(mol)
```
**Replacing Substructures:**
```python
# Replace substructure with another structure
query = Chem.MolFromSmarts('c1ccccc1') # Benzene
replacement = Chem.MolFromSmiles('C1CCCCC1') # Cyclohexane
new_mol = Chem.ReplaceSubstructs(mol, query, replacement)[0]
```
**Neutralizing Charges:**
```python
# Remove formal charges by adding/removing hydrogens
from rdkit.Chem.MolStandardize import rdMolStandardize
# Using Uncharger
uncharger = rdMolStandardize.Uncharger()
mol_neutral = uncharger.uncharge(mol)
```
### 11. Working with Molecular Hashes and Standardization
**Molecular Hashing:**
```python
from rdkit.Chem import rdMolHash
# Generate Murcko scaffold hash
scaffold_hash = rdMolHash.MolHash(mol, rdMolHash.HashFunction.MurckoScaffold)
# Canonical SMILES hash
canonical_hash = rdMolHash.MolHash(mol, rdMolHash.HashFunction.CanonicalSmiles)
# Regioisomer abstraction (not a general stereo-removal operation)
regio_hash = rdMolHash.MolHash(mol, rdMolHash.HashFunction.Regioisomer)
```
**Randomized SMILES:**
```python
# Generate random SMILES representations (for data augmentation)
from rdkit.Chem import MolToRandomSmilesVect
random_smiles = MolToRandomSmilesVect(mol, numSmiles=10, randomSeed=42)
```
### 12. Pharmacophore and 3D Features
**Pharmacophore Features:**
```python
from rdkit.Chem import ChemicalFeatures
from rdkit import RDConfig
import os
# Load feature factory
fdef_path = os.path.join(RDConfig.RDDataDir, 'BaseFeatures.fdef')
factory = ChemicalFeatures.BuildFeatureFactory(fdef_path)
# Get pharmacophore features
features = factory.GetFeaturesForMol(mol)
for feat in features:
print(feat.GetFamily(), feat.GetType(), feat.GetAtomIds())
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |