Rdkit

RDKit

What this library is for

RDKit is the standard open-source cheminformatics toolkit for molecule parsing, molecular graph operations, fingerprints, descriptors, substructure matching, reaction handling, conformer generation, standardization, and 2D/3D molecular depictions. Its core object is a chemically perceived Mol.

When to use this vs. alternatives

• Use RDKit for SMILES/SMARTS/SDF/MOL workflows, molecular descriptors, fingerprints, similarity search, substructure search, reactions, stereochemistry, standardization, and conformer generation.
• Use OpenMM for molecular simulation after chemistry preparation has produced a force-field-ready topology/coordinates; RDKit is not an MD engine.
• Use pymatgen for inorganic/periodic materials structures and phase-stability analysis; RDKit's molecule graph model is not a replacement for periodic crystallographic analysis.
• Use ASE when coordinates are ready for an atomistic calculator workflow. Convert carefully and validate atom order, coordinates, charge, spin, and bonding assumptions.
• Do not parse SMILES with regexes or manipulate atom/bond tables by hand unless the user is explicitly developing a new cheminformatics algorithm.

Canonical workflow

Start from sanitized molecules, check failures explicitly, then use RDKit's graph-aware operations for descriptors, fingerprints, similarity, substructure search, or conformers.

from rdkit import Chem, DataStructs
from rdkit.Chem import AllChem, Descriptors, Draw, rdFingerprintGenerator

smiles = ["c1ccccc1C(=O)O", "CCOC(=O)c1ccccc1", "bad_smiles"]
mols = []
for smi in smiles:
    mol = Chem.MolFromSmiles(smi)
    if mol is None:
        print("failed_to_parse", smi)
        continue
    mols.append(mol)

for mol in mols:
    print(Chem.MolToSmiles(mol), Descriptors.MolWt(mol), Descriptors.MolLogP(mol))

pattern = Chem.MolFromSmarts("c1ccccc1")
hits = [mol for mol in mols if mol.HasSubstructMatch(pattern)]

fpgen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048)
fps = [fpgen.GetFingerprint(mol) for mol in mols]
print(DataStructs.TanimotoSimilarity(fps[0], fps[1]))

mol3d = Chem.AddHs(mols[0])
AllChem.EmbedMolecule(mol3d, AllChem.ETKDGv3())
AllChem.MMFFOptimizeMolecule(mol3d)

Draw.MolsToGridImage(mols, legends=[Chem.MolToSmiles(m) for m in mols])

For deeper examples, read:

• Getting started: https://www.rdkit.org/docs/GettingStartedInPython.html
• Cookbook: https://www.rdkit.org/docs/Cookbook.html
• RDKit Book: https://www.rdkit.org/docs/RDKit_Book.html
• Python API reference: https://www.rdkit.org/docs/api-docs.html

Key conventions and gotchas

• Chem.MolFromSmiles() returns None on parse or sanitization failure. Always check before passing molecules into descriptor, fingerprint, or drawing code.
• Sanitization assigns valence, aromaticity, conjugation, hybridization, rings, and related chemistry perception. sanitize=False is an advanced escape hatch; many RDKit functions will be unreliable until partial or full sanitization is performed deliberately.
• RDKit is strict about allowed valences by default. Explicit valence, kekulization, and aromaticity failures often indicate bad input chemistry, missing charges, or a representation outside RDKit's default model.
• Hydrogens are often implicit. Add explicit hydrogens before 3D embedding, force-field optimization, many charge workflows, or export to tools that need explicit atoms; remove them only when the downstream representation expects it.
• Stereochemistry is representation-sensitive. Preserve isomeric SMILES, assign/check stereochemistry when it matters, and do not assume all non-tetrahedral stereochemistry is fully represented.
• MolToSmiles() canonicalizes by default and can change atom order in the text representation. Keep atom indices and properties on the Mol, not in a parallel SMILES string table.
• SDF suppliers can return None records for bad molecules. Filter records and keep source identifiers so failures are auditable.

Anti-patterns

• Do not regex-parse SMILES for atoms, rings, branches, charges, or aromaticity. Use Mol, SMARTS, substructure matching, and RDKit atom/bond APIs.
• Do not ignore None molecules and let downstream descriptor code fail with a confusing attribute error. Report failed inputs and, if useful, diagnose with DetectChemistryProblems().
• Do not disable sanitization just to make errors disappear. If you must read an unusual molecule, use sanitize=False, inspect chemistry problems, run partial sanitization deliberately, and document the assumptions.
• Do not generate 3D conformers without hydrogens and force-field cleanup unless the user explicitly wants raw distance-geometry coordinates.
• Do not treat fingerprint similarity as chemical truth. State the fingerprint, radius, bit length/count representation, and similarity metric.
• Do not mix RDKit molecules with pymatgen/ASE/OpenMM objects without validating atom order, coordinates, formal charge, stereochemistry, and bond perception.

Diagnostic checks

Before trusting outputs, the agent should:

• Count and report parse failures from SMILES/SDF/MOL inputs.
• Canonicalize or standardize molecules only when the workflow calls for it, and record the chosen standardization steps.
• For descriptor/fingerprint tables, include molecule identifiers and note the RDKit version, fingerprint type, radius, size, and chirality setting.
• For substructure searches, test the SMARTS on positive and negative examples and verify whether chirality/query features are intended.
• For conformers, report whether hydrogens were added, the embedding method, force field, convergence status, and number of conformers retained.
• For stereochemistry-sensitive work, compare isomeric SMILES before and after transformations.

Pointers to deeper material

• Documentation: https://www.rdkit.org/docs/
• Getting started: https://www.rdkit.org/docs/GettingStartedInPython.html
• Cookbook: https://www.rdkit.org/docs/Cookbook.html
• RDKit Book: https://www.rdkit.org/docs/RDKit_Book.html
• FAQ: https://github.com/rdkit/rdkit/wiki/FrequentlyAskedQuestions
• Source repository: https://github.com/rdkit/rdkit
• Paper: Landrum, "RDKit: Open-source cheminformatics". https://www.rdkit.org/