Rdkit

rdkit

RDKit is the cheminformatics toolkit: a molecule is a graph (Chem.Mol), written as SMILES, queried with SMARTS, given coordinates by distance geometry. Tools: $RDKIT_PYTHON (the pinned venv, with numpy and pandas), harness_rdkit on PYTHONPATH (build, embed, write, compare), $RDKIT_TOOLCHAIN/verdict.py (the pane header). Never install another RDKit.

Build, write, verdict

"$RDKIT_PYTHON" molecules/hello.py                        # runs the script → out/<name>.sdf and the rest
"$RDKIT_PYTHON" "$RDKIT_TOOLCHAIN/verdict.py"             # judges the newest molecule → pane header
"$RDKIT_PYTHON" "$RDKIT_TOOLCHAIN/harness_rdkit.py" design "CCO" ethanol   # the same, without a script

from harness_rdkit import design, mol_from_smiles, embed_conformers, embed_3d, write_outputs, properties, similarity, substructure

design("CC(C)Cc1ccc(cc1)C(C)C(=O)O", "ibuprofen")         # parse → 10 conformers → minimise → describe → write
design("CC(C)(O)Cc1ccc(C(C)C(=O)O)cc1", "ibuprofen_oh", parent="ibuprofen")   # an analogue: name its parent

mol = mol_from_smiles("CN1C=NC2=C1C(=O)N(C)C(=O)N2C", "caffeine")   # the steps, when work happens between
confs = embed_conformers(mol, n=10, seed=7)               # ETKDGv3 + MMFF94, deduplicated, lowest first, aligned
write_outputs(confs, "caffeine", parent=False)            # False: not an analogue of anything here

What design/write_outputs write to out/, and what each is for:

The pane shows the molecule while it is being made (out/.progress.json: embedding, minimising, describing); never write these files by hand. properties(mol) returns the properties without writing; depict(mol, path) the PNG alone; describe(mol, name) the record and SVG without writing. read_smi("molecules/series.smi") reads a SMILES name list, table(mols) turns molecules into rows for pandas.DataFrame.

Parents. An analogue is compared with its parent: the maximum common substructure, the atoms that changed (+O, −C +O), the property deltas, a 2D depiction drawn on the parent's core and a 3D pose superposed on it. Pass parent="<name already designed>" (or a SMILES) whenever you make an analogue; left out, the parent is inferred as the earlier molecule this one is the smallest edit of, and parent=False says there is none. Design the lead first, then its analogues, so the series reads in order.

A shape the user kept

The pane can scan a non-ring single bond with native MMFF94, with the other internal coordinates fixed. The user chooses four connected atoms, moves along the energy curve, and keeps a pose and note in out/torsions/<id>/. This is a rigid, vacuum, single-bond experiment, not a geometry optimization or a free-energy calculation. Do not infer populations, kinetics, activity or binding. The input must have explicit hydrogen atoms, 3D coordinates, 4–200 atoms, one connected component and MMFF94 parameters. It uses 10°, 15° or 30° spacing and never silently falls back to UFF.

When continuing the user's experiment, read study.json for the method, selected angle, atom indices, full-precision coordinates and note. Load selected.sdf with Chem.SDMolSupplier(path, removeHs=False)[0], then author the requested follow-up under a new name. Keep the original study unchanged. source.mol is the exact input conformer; scan.sdf contains every sampled angle; energies.csv gives absolute and within-scan relative energies in kcal/mol. study.zip includes these files and standalone reproduce.py/harness_torsion.py; the recorded RDKit version is required to verify the calculation. JSON coordinates preserve full precision; MOL/SDF exchange files round them to four decimals. Unsaved pane scans are not files: ask the user to Keep study only when their chosen pose or note is needed for the next step.

SMILES, the parts that matter

• Atoms are bare symbols; lowercase is aromatic (c1ccccc1 benzene). Bonds: - single (implicit), = double, # triple, / \ around a double bond for E/Z.
• Branches in parentheses: CC(C)C isobutane. Rings close on matching digits: C1CCCCC1 cyclohexane, c1ccc2ccccc2c1 naphthalene. Reuse a digit once it is closed.
• Brackets for anything not a default: charge [NH4+], [O-]; isotope [13C]; explicit H [nH] — pyrrole is c1cc[nH]c1, and forgetting the H is the commonest SMILES error there is.
• Stereo: [C@H] / [C@@H] at a centre, F/C=C/F trans. Write it when it matters; RDKit will not guess, and an unspecified centre silently becomes a racemate.
• Dot separates components: a salt is CC(=O)[O-].[Na+], and most calculations want the parent only.

Useful anchors: water O, ethanol CCO, benzene c1ccccc1, phenol Oc1ccccc1, aspirin CC(=O)Oc1ccccc1C(=O)O, paracetamol CC(=O)Nc1ccc(O)cc1, caffeine CN1C=NC2=C1C(=O)N(C)C(=O)N2C, ibuprofen CC(C)Cc1ccc(cc1)C(C)C(=O)O, naproxen COc1ccc2cc(ccc2c1)C(C)C(=O)O, glucose OC[C@H]1OC(O)[C@H](O)[C@@H](O)[C@@H]1O, penicillin G core CC1(C)S[C@@H]2[C@H](NC(=O)Cc3ccccc3)C(=O)N2[C@H]1C(=O)O.

SMARTS, for finding things

SMARTS is SMILES plus queries: [#6] any carbon, [C,N] either, [!c] not aromatic carbon, [R2] in two rings, [X3] three connections, [OX2H] a hydroxyl oxygen, * anything, ~ any bond.

substructure(mol, "[OX2H]")                  # hydroxyls → ((3,), (7,))
substructure(mol, "c1ccccc1")                # benzene rings
substructure(mol, "[CX3](=O)[OX2H1]")        # carboxylic acid

Groups worth keeping: carboxylic acid [CX3](=O)[OX2H1], amide [NX3][CX3](=[OX1]), primary amine [NX3;H2;!$(NC=O)], sulfonamide [SX4](=[OX1])(=[OX1])([NX3]), nitro [N+](=O)[O-], halogen [F,Cl,Br,I].