Retrosynthetic Planning
The Make half of design-make-test-analyse, and the check that a proposed molecule is more than a
picture. AiZynthFinder runs Monte Carlo tree search over reaction templates until every leaf of a
route is something you can buy.
Tool: AiZynthFinder 4.4.1, MIT.
pip install aizynthfinder — Python 3.10–3.12 only, it will not install on 3.13. Then
download_public_data <dir> for models and a ZINC stock (several GB). CPU is sufficient.
Checked against: 4.4.1, December 2025.
Read references/aizynthfinder-setup.md before your first run,
references/synthesizability-scores.md when triaging more
molecules than you can search, and references/route-quality.md
before acting on a route — that one is judgement, not syntax.
The two scripts
| Script | Answers |
|---|
aizynth_config.py | What does the config look like, and are the model files really there? |
route_report.py | What fraction is makeable, in how many steps, from what? |
The stock file is the answer
This is the thing to get right. A target is solved when every leaf of a route is in your stock
file — so "solved" is a statement about the stock at least as much as about the molecule.
| Stock | Solved fraction |
|---|
| small in-house inventory | low; reflects what you can start today |
| ZINC (the default download) | moderate; a public baseline |
| eMolecules / commercial | high |
| Enamine building blocks | high; what a REAL-space campaign should use |
A solved fraction quoted without naming the stock is meaningless — the same molecule is solved
against eMolecules and unsolved against a cupboard. route_report.py says so on every run.
Configuration changed at version 4
Version 3 took bare lists of file paths; version 4 takes typed blocks. Every tutorial older than
2024 shows the incompatible form, and the resulting error is unhelpful.
python skills/retrosynthesis/scripts/aizynth_config.py config \
--model uspto_model.onnx --templates uspto_templates.csv.gz \
--filter-model uspto_filter_model.onnx --stock zinc:zinc_stock.hdf5 > config.yml
python skills/retrosynthesis/scripts/aizynth_config.py check --config config.yml
expansion:
uspto:
type: template-based
model: uspto_model.onnx
template: uspto_templates.csv.gz
check verifies every referenced file exists, because AiZynthFinder discovers a missing model
after the run starts. It also warns when a config looks like the version-3 form.
Always set a filter policy. Without one the search proposes reactions the expansion model
likes but that do not work, and the solved fraction stops measuring anything.
Budget before you start
time_limit is per target. At the 120 s default, ten molecules is twenty minutes and ten
thousand is nearly two weeks. Use aizynthcli --nproc 8 to parallelise across targets.
Reading the result
python skills/retrosynthesis/scripts/route_report.py summary --output out.json.gz
python skills/retrosynthesis/scripts/route_report.py routes --output out.json.gz
# 1/1 solved (100.0%)
targets 1
solved 1
median_steps 2
target route steps starting_materials leaves_in_stock score
TARGET 0 2 3 3 0.95
Step count matters more than existence — yields multiply, so five steps at 70% is 17% overall, and
past about six steps a route is rarely run as written. route_report.py flags those.
blocks counts how many routes share each starting material. If twenty targets converge on three
intermediates, the campaign is cheap; that is a different and more useful fact than the solved
fraction.
Unsolved does not mean unmakeable
It means no route was found within the time and depth limits, using these templates, terminating
in this stock. Four distinct fixes, and working out which applies is the useful step: raise the
time limit, raise max_transforms, broaden the stock — or accept that the chemistry is not in
USPTO templates.
That last case is systematic. Template models only know reactions in their training corpus, so
novel methodology, photoredox, electrochemistry, and enzymatic steps are largely invisible.
Four ways this misleads
- A solved route is a proposal, not a validated synthesis. The templates come from reactions
that worked on other substrates; nothing here knows your chemoselectivity or protecting-group
needs.
- Convergent beats linear at equal step count. Overall yield depends on the longest linear
sequence, so read the tree shape, not just its depth.
- Where the disconnections sit matters more than step count for a series. A route that
decorates late gives analogues from a common intermediate; one that installs the variable group
first needs a full resynthesis each time.
- Pre-filtering with RAscore inflates the solved fraction, because RAscore is trained to
predict AiZynthFinder's own verdict. Fine as a pipeline, misleading as a statistic — report the
pre-filter.
Triage at scale
Route search is seconds to minutes per molecule; scores are microseconds. For a generated library:
SAscore or RAscore across everything, full search on the survivors, and a chemist reading the
routes for the handful you will actually order. The honest hierarchy is
SAscore < RAscore < route search < a chemist's opinion < the compound in a vial, and each step
right is more expensive and more real.
Composing with the rest of the bundle
generative-design → here: the essential check, since nothing in a REINVENT objective knows
what can be made. Better still, add SAscore as a scoring component during the run.chemical-space → alongside: if it is already purchasable, you do not need a route.medchem → before: no point routing molecules that fail structural alerts.admet-prediction → alongside: makeable and developable are different filters.
Reporting results honestly
Name the stock, always. Give solved fraction and median step count — 90% solved at nine steps
is worse than 60% at three. State the time and depth limits, since unsolved is partly a statement
about them. And say plainly that a proposed route is a hypothesis no chemist has yet reviewed.