End-to-end in ~10 minutes: install, run a screen, inspect a hit, ship a shortlist.
No ML, no black boxes. Every number in every output has a physics
derivation or a cited empirical formula — see MISSION.md.
CellSim ships a single conda environment covering everything from RDKit to xTB to Vina to PoseBusters.
# Install mambaforge first if you don't have conda.
# (macOS: brew install miniforge)
# (Linux: see https://github.com/conda-forge/miniforge#install)
# From the CellSim repo root:
mamba env create -f environment.yml # ~5 min
conda activate cellsimThe conda activate cellsim step sets AMBERHOME, which is
required for AM1-BCC partial charges. A bare python … invocation
without the activate will silently fail at charge assignment — see
cellsim/chem/README.md for diagnostics.
Everything below assumes conda activate cellsim has been run.
CellSim ships the streptavidin–biotin cocrystal (PDB 1STP) and a tiny 5-compound validation batch (biotin + 4 non-binder drugs). Run a full screen:
./scripts/cellsim dock \
--smi benchmarks/dock/1stp_batch_5.smi \
--receptor benchmarks/dock/1stp.pdb \
--out-csv /tmp/run/report.csv \
--mc 4 --profile-top-k 3 \
--crystal-pdb benchmarks/dock/1stp.pdb --crystal-resname BTNWhat happens:
- Pocket detection. If you hadn't given
--center/--box, fpocket would auto-find the binding site. (Here we skip because we do know the site from the crystal.) - Per-compound: RDKit embed → OpenFF Sage parameters → AM1-BCC
charges → Vina docks 4 seeds for the
--mc 4Monte-Carlo. - PoseBusters grades pocket fit + geometry per pose.
- ADMET: Lipinski / QED / logS / TPSA computed alongside.
- Ranks, writes
/tmp/run/report.csv, then generates/tmp/run/profile_01_biotin_TRUE_BINDER.png(and top 2 + 3).
Expected stdout:
RANK NAME TRIAGE ΔG(kcal) K_d POCKET STRAIN Ro5 QED logS
1 biotin_TRUE_BINDER follow_up -7.44 3.5 µM ✓ acceptable ✓ 0.49 -1.53
2 ibuprofen_negative follow_up -7.36 4.1 µM ✓ acceptable ✓ 0.82 -3.09
3 aspirin_negative deprioritise -6.66 13.0 µM ✓ acceptable ✓ 0.55 -1.99
4 acetaminophen_negative deprioritise -6.31 23.8 µM ✓ good ✓ 0.59 -1.97
5 caffeine_negative drop -5.48 95.7 µM ✓ good ✓ 0.54 -0.87
Next steps
--------------------------------------------------
• Send 2 follow_up compound(s) to wet lab.
• 2 deprioritise compound(s): ignore unless scaffold-important;
if they matter, rescore with FEP before triage.
• 1 drop compound(s): too weak / non-physical pose / known-bad
ADMET. Do not synthesise.
The two follow_up compounds are biotin (the real binder, Vina
ΔG = −7.44 kcal/mol) and ibuprofen. Vina saturates on the
extreme-tight streptavidin pocket, compressing every plausible
binder into the same ~−7 kcal/mol range — so ibuprofen is a
documented Vina false positive on this particular target, not
a CellSim bug. TUTORIAL §8 explains the Vina-target-family
reliability story; the honest biologist workflow on a
saturation-prone target is to treat rank-1 as the real hit and
rescore the rest with FEP.
The Next steps block is the paste-ready wet-lab handoff
summary. If a batch has zero follow_up or review compounds,
CellSim prints a warning pointing at the target-class reliability
table (§8) so biologists can check whether the receptor is in
Vina's comfort zone before blaming their library.
To produce a hand-to-wet-lab shortlist containing only compounds
worth chemists' time (follow_up + review verdicts), add
--shortlist-csv:
./scripts/cellsim dock ... --out-csv run/full.csv \
--shortlist-csv run/shortlist.csvThe shortlist has the same columns as the full CSV but filters
out deprioritise and drop rows, so you can paste it straight
into a wet-lab handoff meeting.
You can also regenerate a shortlist from any existing CSV later (useful for merging several runs or re-filtering with custom verdicts):
./scripts/cellsim shortlist run/full.csv --out run/shortlist.csv
# or: keep only 'follow_up' rows
./scripts/cellsim shortlist run/full.csv --out run/tight.csv \
--verdicts follow_upWhenever cellsim dock writes a CSV via --out-csv, it also
writes two companion files next to it, automatically:
<name>.triage.png— the 4-panel dashboard (shown below)<name>.md— a markdown-table summary of the top 10 rows plus a Next-steps block. Paste directly into Benchling / eLabFTW / Obsidian / any markdown-capable lab notebook. To regenerate from an existing CSV:
./scripts/cellsim triage-png run/report.csv --out run/triage.pngPanels: stacked verdict bar, ΔG scatter faceted by verdict, pose-trust (strain band) counts, and safety-filter pass rates (Ro5 / hERG / Ames). Paste-into-meeting ready.
The TRIAGE column is the one-decision column for wet-lab
handoff. Four verdicts:
| verdict | what to do |
|---|---|
follow_up |
strong ΔG, trustworthy pose, ADMET clean — synthesise |
review |
strong ΔG but one flag (strain / pocket / hERG / Ames) needs a chemist's eye |
deprioritise |
borderline ΔG or a flag on a borderline hit — skip unless scaffold-important |
drop |
too weak (ΔG > −6), non-physical pose, ≥3 Ro5 violations, or high-risk Ames |
The CSV carries a triage_reason column with a paste-ready
string ("ΔG -7.23 borderline", "suspicious pose strain; hERG alert"). Biologist reads one column, not five booleans.
The STRAIN column bands the UFF-ensemble strain ratio of the
top pose (Buttenschoen 2024 Chem Sci 15:3130): good / acceptable
/ suspicious / reject. A reject here force-drops the
compound regardless of ΔG because the pose isn't physical.
For one compound, cellsim dock-one renders the Vina pose into
a dashboard with the binding pocket, the ranked-pose ΔG bars
coloured by crystal-RMSD if a reference is available, and the
strain readout in the title line:
./scripts/cellsim dock-one \
--receptor benchmarks/dock/1stp.pdb \
--ligand-smiles "OC(=O)CCCC[C@@H]1SC[C@@H]2NC(=O)N[C@H]12" \
--center 11.12,1.68,-10.75 --box 20,20,20 \
--exhaustiveness 16 --num-modes 3 \
--save /tmp/biotin_dock.pngTitle line shows the top-1 ΔG, K_d, seed/exhaustiveness, and the strain badge (UFF-ensemble ratio + kcal/mol) so you see pose trust and affinity together.
Open /tmp/run/profile_01_biotin_TRUE_BINDER.png and you'll see
six panels on one page:
| Panel | What it tells you |
|---|---|
| 3D + charges (top-left) | Atom positions with Mulliken charges (blue = electron-rich, red = electron-poor). Spot the nucleophiles / electrophiles by eye. |
| SoM prediction (top-mid) | Red atom = predicted primary CYP3A4 metabolism site. Orange = top-3. Tells you where metabolism will clear this drug. |
| Text datasheet (top-right) | Full ADMET + electronic summary. Your compound's MW, logP, HBA/HBD, rotb, QED, HOMO/LUMO. |
| HOMO/LUMO bar (bottom-left) | Electronic gap → reactivity/stability cue. |
| BDE chart (bottom-mid) | Top-10 bonds by dissociation energy. Low BDE = easier to abstract = CYP hotspot. |
| Ro5 / QED callouts (bottom-right) | Big green/red "is this drug-like?" glance. |
One page → one compound triage decision.
Drop a receptor PDB and a SMILES file into the repo:
cat > /tmp/my_compounds.smi <<'EOF'
CC(=O)OC1=CC=CC=C1C(=O)O aspirin
CC(C)CC1=CC=C(C=C1)C(C)C(=O)O ibuprofen
Oc1ccc(/C=C/C(=O)O)cc1 p-coumaric_acid
EOF
./scripts/cellsim dock \
--smi /tmp/my_compounds.smi \
--receptor path/to/your_target.pdb \
--out-csv /tmp/my_screen/report.csv \
--mc 8 --profile-top-k 10 \
--refine-posesYou can also pipe SMILES from stdin — useful for filtering a large library on the fly:
grep '^CC' /path/to/chembl.smi | ./scripts/cellsim dock \
--smi - --receptor 1STPSDF input works out of the box — just pass a .sdf / .mol /
.sd file to --smi and CellSim uses each record's _Name
title property as the compound name:
./scripts/cellsim dock --smi compounds.sdf --receptor target.pdbA bundled 5-compound demo SDF is available for a zero-friction first run:
./scripts/cellsim dock \
--smi benchmarks/chembl/demo.sdf --receptor 1STP \
--out-csv /tmp/demo/run.csv \
--shortlist-csv /tmp/demo/short.csv
# auto-fetches 1STP from RCSB on first run, caches it, and
# prints the triage table + next-steps for all five compounds.No ChemDraw-to-SMILES conversion step needed; biologists who export directly from synthesis-workflow tools pipe the SDF straight in.
PDB-ID receptors. If --receptor looks like a 4-character
PDB code rather than an existing file, CellSim auto-downloads
it from RCSB and caches it under data/receptors/:
./scripts/cellsim dock --smi compounds.sdf --receptor 1STP
# [batch] receptor '1STP' looks like a PDB ID; fetching https://...
# [batch] wrote data/receptors/1stp.pdb (115.1 KB)Handy for "I want to see if my library hits PDB 3PTB" without a separate fetch step.
No --center? fpocket auto-detects the binding site from receptor
geometry.
--mc 8 runs 8 Vina seeds per compound → honest ΔG mean ± 95% CI
in the CSV.
--refine-poses runs OpenMM ligand-only minimisation on each pose
→ PoseBusters geometry_ok flag is meaningful downstream.
--profile-top-k 10 auto-generates the per-compound dashboard
PNGs for your top 10 hits.
Add --cache /tmp/my_screen/cache.sqlite (or any path) to store the
expensive Vina and AM1-BCC results content-addressed by the
(ligand, receptor, search box, exhaustiveness, seed) tuple. The
second run of an identical batch reads every compound from cache
instead of recomputing — ~1000× per-compound Vina speedup, ~19×
end-to-end on a small screen (larger wins on bigger libraries).
Safe to delete the SQLite file any time to invalidate; automatic on force-field bumps since the FF version is baked into the cache key.
Add --export-poses-dir DIR and CellSim writes DIR/<compound>.sdf
(RDKit V2000 with ΔG / K_d / crystal-RMSD / pocket_ok as SDF
properties) and DIR/<compound>.pdb (MODEL-separated with REMARK
annotations) for every successfully docked compound:
cellsim dock --smi compounds.smi --receptor target.pdb \
--export-poses-dir run/poses --out-csv run/report.csvThen in PyMOL: File → Open → run/poses/top_hit.sdf.
The CYP SoM predictor tells a biologist where a drug is likely to get oxidised in the liver, which is a direct proxy for its half- life and clearance. xTB BDE picks the reactive site in ~s per compound; for high-stakes calls, DFT B3LYP/def2-SVP rescoring flips the ranking when xTB disagrees:
cellsim som "CC(=O)OC1=CC=CC=C1C(=O)O" # xTB only, <1 s
cellsim som "CC(=O)OC1=CC=CC=C1C(=O)O" --dft-verify 3 # +DFT, ~60 s
cellsim som-validate benchmarks/quantum/cyp3a4_som_validation.yaml \
--dft-verify 3 # compares top-1 against literature sitesSee benchmarks/quantum/cyp3a4_som_validation.yaml for a
literature-cited 3-drug validation set; the SMARTS in
known_som_smarts encodes the experimentally reported primary
metabolism site per compound.
One compound vs many receptors — in-silico off-target toxicity triage. CellSim auto-detects each receptor's binding site via fpocket and reports a ΔG per target plus the selectivity ΔΔG between the intended target and the strongest off-target:
cellsim off-target \
--ligand-smiles "OC(=O)CCCC[C@@H]1SC[C@@H]2NC(=O)N[C@H]12" \
--receptors "streptavidin=1stp.pdb,trypsin=3ptb.pdb,EGFR=1m17.pdb" \
--cache offtarget.sqlite \
--out-csv offtarget.csvReads "biotin binds streptavidin at −7.4 kcal/mol, everything else is weaker, selectivity margin is 1.4 kcal/mol". The convention in pharma is ΔΔG ≥ 3 kcal/mol = "good selectivity" (~200× K_d gap).
Want just the ADMET for one SMILES?
./scripts/cellsim admet "CC(=O)OC1=CC=CC=C1C(=O)O"
# [OK] ADMET C9H8O4 MW=180.2 logP=+1.31 TPSA=63.6 HBA=3 HBD=1
# rotb=2 Ro5 ✓ QED=0.55 logS=-1.99 (soluble)xTB electronic structure?
./scripts/cellsim xtb "CC(=O)OC1=CC=CC=C1C(=O)O"
# [OK] xtb GFN2-xTB … HOMO=-11.38 LUMO=-7.87 gap=3.51 eV µ=2.39 DCYP3A4 site-of-metabolism?
./scripts/cellsim som "CC12CCC3C(C1CCC2=O)CCC4=CC(=O)CCC34C"
# [OK] SoM CYP3A4 testosterone … 26 candidates
# rank= 1 C(idx=5) BDE= 118.7 kcal/mol
# rank= 2 C(idx=4) BDE= 120.6 kcal/mol
# rank= 3 C(idx=12) BDE= 123.9 kcal/molFull drug profile PNG in one shot:
./scripts/cellsim profile testosterone \
--smiles "CC12CCC3C(C1CCC2=O)CCC4=CC(=O)CCC34C" \
--save testosterone.pngMonte-Carlo ΔG estimate for one compound against one target:
./scripts/cellsim uq-mc \
--receptor benchmarks/dock/1stp.pdb \
--ligand-smiles "OC(=O)CCCC[C@@H]1SC[C@@H]2NC(=O)N[C@H]12" \
--center 11.12,1.68,-10.75 --box 20,20,20 \
--n 16 --workers 4
# ΔG = -7.42 ± 0.03 kcal/mol 95 % CI [-7.45, -7.38]Sobol sensitivity — which Vina knob moves ΔG most?
./scripts/cellsim uq-sobol \
--receptor benchmarks/dock/1stp.pdb \
--ligand-smiles "OC(=O)CCCC[C@@H]1SC[C@@H]2NC(=O)N[C@H]12" \
--center 11.12,1.68,-10.75 --box 20,20,20 \
--n-base 32 --workers 8
# Reports S1 / ST + 95% CI per input over 256 runs.| Column | Meaning |
|---|---|
rank |
Rank within successful compounds (best ΔG = 1). |
triage |
Synthesised verdict: follow_up / review / deprioritise / drop. One decision column for wet-lab handoff. |
triage_reason |
Paste-ready explanation (e.g. "ΔG -7.23 borderline", "high mutagenicity (Ames SMARTS hit)"). |
dG_kcalmol |
Vina top-pose ΔG, kcal/mol. More negative = tighter. |
dG_kJmol |
Same in SI. |
Kd_nM |
Implied K_d = exp(ΔG / RT). |
Kd_human |
Auto-formatted ("3.5 µM", "12 nM", …). |
dG_mean_kcalmol |
(if --mc N) MC mean ΔG over N seeds. |
dG_std_kcalmol |
MC standard deviation. |
dG_ci95_lo / dG_ci95_hi |
95 % CI from sample percentiles. |
crystal_rmsd_A |
(if --crystal-*) top-pose RMSD vs crystal HETATM ligand in Å. |
pocket_ok |
PoseBusters: pose placed in pocket, no protein clashes. Triage signal. |
geometry_ok |
PoseBusters: bonds/angles/chirality all sane. Required for FEP. |
pb_all_ok |
All PoseBusters tests pass including RMSD ≤ 2 Å. |
strain_band |
UFF-ensemble strain ratio band (good / acceptable / suspicious / reject) — Buttenschoen 2024 Chem Sci. |
strain_kcalmol |
Absolute strain energy = E(bound) − E(relaxed) for the docked top pose. |
strain_ratio |
E(bound) / E(ensemble_avg). Ratio > 7 means the pose is almost certainly non-physical. |
MW, logP, TPSA, HBA, HBD, rotb |
Lipinski Ro5 inputs + PSA. |
ro5_pass / ro5_violations |
Rule-of-five flag. |
QED |
Bickerton 2012 drug-likeness score in [0,1]. |
logS |
ESOL log solubility (mol/L). Higher = more soluble. |
solubility |
Qualitative bucket (highly / moderately / slightly / insoluble). |
CellSim replaces the triage stage of wet-lab pharma work, not the confirmation stage. Match your target to the table below before trusting a ΔG / hit-list.
| Target class | Evidence | Typical accuracy |
|---|---|---|
| Serine proteases (trypsin, thrombin-like S1 pocket) | benchmarks/dock/trypsin_calibration.yaml |
MAE 0.9 kcal/mol on the absolute scale |
| Rigid pocket, wide K_d spread (nM → mM) | generalisable from the above | Pearson > 0.6 typical |
| Target class | Evidence | What to do instead |
|---|---|---|
| Ultra-tight binders (streptavidin/biotin and analogues) | benchmarks/dock/streptavidin_calibration.yaml — 4 compounds spanning 12 kcal/mol; predictions span 0.3 kcal/mol, Spearman ~0.4, MAE 6.7 |
Vina saturates near −7 kcal/mol and can neither score nor rank these. Use FEP. |
| Kinase ATP sites (EGFR, Abl, CDK, …) | benchmarks/dock/egfr_calibration.yaml — Spearman −0.49 on 6 EGFR inhibitors |
Use Vina for pose/pocket-fit sanity only; rescore with alchemical FEP via benchmarks/fep/binding_egfr.yaml → cellsim fep-binding bench --sample (Kendall τ gate) |
| Anything where the strain ratio > 3 on top pose | strain_band = suspicious / reject in the batch CSV |
Don't trust the ΔG; strain means Vina contorted the ligand |
| Compounds with > 15 rotatable bonds | Vina's degrees-of-freedom scaling | Flag for refinement (--refine-poses + MD rescoring) |
| Metal-coordinating inhibitors (imidazole/pyridine on Zn/Fe targets) | Vina has no metal term | Use our pocket-geometric post-filter (cf. ketoconazole in cyp-inhibit); raw ΔG is under-scored |
- Protein-protein interactions / allosteric sites — Vina was trained on small-molecule ATP-competitive binding; shallow protein-protein interfaces give meaningless ΔG.
- Covalent inhibitors — no covalent-bond scoring in this stack. Meeko prep will silently strip the warhead.
- Membrane-embedded receptors (GPCRs, ion channels) — Layer 1.5 (Martini 3 bilayer) is scaffold-only.
For every compound, the batch CSV's triage verdict already
bakes these rules in:
- a pose with
strain_band = rejectis automatically markeddropregardless of ΔG; - a
suspiciousstrain on a strong ΔG routes toreview; - kinase ranking failure isn't auto-detected yet (no public
target-family labels), so for kinase hit-lists, treat the
triagecolumn as pose-trust only and re-rank by external orthogonal evidence.
Every prediction carries provenance. Every CellSim release runs
the full smoke gate in CI — see
.github/workflows/smoke.yml and
the "Validation that runs on every PR" section of
README.md. On every PR:
- Layer 1.1 chem smoke (10 canonical drugs end-to-end).
- Layer 1.2 short MD on aspirin + 1UBQ.
- Layer 1.3 re-dock gate on 1STP biotin; 3-cocrystal mini-bench.
- Layer 1.4 xTB + SoM smoke.
- Layer 1.6 MC-dock smoke.
A regression on any of the ~11 smoke gates blocks merge.
-
No Campaign-2 cellular biology. The Layer-2 pathway simulation (HeLa p53/MDM2/cisplatin etc.) lives under
OLD/as a frozen pre-restart snapshot. Campaign 2 resumes once Campaign 1 closes (seeROADMAP.md). -
No ML predictions. If you want a neural scorer, use a different tool; CellSim is deliberately physics-only (see
MISSION.md§"No black-box / no AI surrogates"). -
Vina ΔG is triage-grade; alchemical FEP is shipped for rigorous binding. Layer 1.3's Milestone A (hydration ΔG via
compute_hydration_dg) and Milestone B (binding ΔG via DDM,compute_absolute_binding_dg+compute_relative_binding_ddg) are both callable end-to-end:# Pre-flight: every YAML in benchmarks/fep/ validates <10 s cellsim bench-all # Binding ΔG on one compound (scaffold in seconds, --sample # for real MD which needs GPU) cellsim fep-binding dg "c1ccc(Nc2ncnc3ccccc23)cc1" \ benchmarks/dock/1m17.pdb # Batch a YAML with wall-time estimate + GPU detection cellsim fep-binding bench benchmarks/fep/binding_egfr.yaml \ --sample --out-csv egfr.csv --resume # Verdict: PASS / FAIL / partial + parity PNG cellsim fep-report egfr.csv --yaml benchmarks/fep/binding_egfr.yaml
The sampled Milestone A numbers on the FreeSolv-12 gate are currently running on an M5 Max; Milestone B sampled runs on streptavidin-biotin + the EGFR 6-compound series follow.
-
No membrane proteins yet. GPCRs / ion channels in a bilayer need Layer 1.5 Martini 3, scaffold-only at the moment.
./scripts/cellsim help— subcommand index../scripts/cellsim <subcommand> --help— per-subcommand args.MISSION.md— discipline + non-AI ground rules.ROADMAP.md— Campaign-1 layer status.docs/campaign1_scope.md— exit criteria for each layer.- Run into a confusing error? Open an issue with the commit SHA
(
git rev-parse HEAD) + the stderr.

