laboratoire-de-chemoinformatique/synplanner/synplanner-usage

SynPlanner usage

READ references/tasks.md FIRST

Before exploring the repository, before grepping the source, before writing a line of code — read `references/tasks.md`, sitting next to this file.

It maps around thirty tasks to the exact API pieces each one needs, in order, with links to a worked notebook and the reference page. This file gives the rules. That one gives the sequences, and no sequence is repeated here.

Skipping it means reconstructing from the source what is already written down — which is where the time goes, and where wrong answers come from. Read it first even when the task looks simple.

What SynPlanner is

SynPlanner is a high-level reaction processing toolbox for retrosynthesis. It orchestrates chython-synplan (also known as chython, formerly CGRtools) — a pure-Python chemoinformatics engine with capabilities comparable to RDKit — for reaction data curation, retrosynthetic planning, and analysis of synthetic routes.

When to use something else

SynPlanner is for retrosynthesis and reaction-level work. It does not need to be in the loop for plain molecule handling.

chython is already installed as SynPlanner's engine and covers most of what RDKit does. For molecule-level work that never touches a reaction or a route, use from chython import ... directly rather than going through SynPlanner. Do not reach for RDKit just because the task looks like ordinary cheminformatics — chython is already there.

Use RDKit only where chython genuinely lacks the capability. SynPlanner itself does exactly this for synthetic-accessibility scoring and molecular descriptors — see synplan/chem/rdkit_utils.py.

Do not overcorrect. "Prefer chython" is not "never RDKit" — when chython does not have the function, reach for RDKit and say so, rather than hand-rolling it.

A library is not a route

synplan.chem.synthon is a port of Synt-On and answers a different question from planning: what can be built from a catalogue, not how to make one molecule. Asked for a synthesis, plan. Asked for a library, for analogues, or for what a catalogue reaches, fragment and enumerate. Do not reach for Tree to enumerate, and do not hand back a fragmentation pathway as a route — it names no reaction and no conditions.

The one crossing point is synthon_priority_rules(), which hands the disconnections to the ordinary MCTS search. Python-only, and it needs use_priority=True in the search config or the rules are ignored in silence.

Build the synthon stock before using it. synthon_fragment and synthon_enumerate read synthons, not building blocks: run bb_classifying then bb_synthonizing over the catalogue first. Pointing them at a raw building-block file is the usual reason nothing comes back, and it does not raise.

Do not oversell what the disconnections cover. Half the ring rules were authored in this repository and no chemist has signed them off, ten more are held out, and the pipeline discards stereochemistry — every enumerated ring is racemic. Say so when you hand over a library. references/tasks.md has the specifics.

Installing

Python >=3.10,<3.15. Use a virtual environment and choose the user's workflow:

The base install includes pandas for ChemFrame and general analysis and needs no Torch. Curation adds Torch, Chytorch's reaction mapper, and SciPy; training adds Torch/PyG, Lightning, AdaBelief, JupyterLab, widgets, and the ONNX exporter. Combine curation and training for data-to-model work. Launch tutorial notebooks with jupyter lab. For curation or atom-mapping tutorials, install SynPlanner[curation,training] or SynPlanner[all]. Install a selected tracking backend directly, e.g. pip install wandb or pip install mlflow; there are no logger-specific SynPlanner extras.

From a source clone, use --no-dev for a user environment:

uv sync --no-dev                       # chemistry and ONNX planning
uv sync --no-dev --extra training --extra cpu
uv sync --extra cpu                    # contributors: includes the dev group
docker build --platform linux/amd64 -t synplan:cli -f cli.Dockerfile .

Docker is the most reproducible and the fallback when a platform gives trouble. Check the result with synplan --version.

Two things the install does not give you

1. Data and model weights are not bundled.

synplan download_preset --preset synplanner-gps --save_to synplan_data

Fetches from HuggingFace and prints a key: path map. Those paths are what synplan planning consumes. For a preset entry ending in .ckpt, the downloader prefers a same-name .onnx file in the same remote folder when available. Use the printed path or the returned paths["ranking_policy"]; do not hardcode the checkpoint suffix. If no ONNX counterpart exists, it downloads the checkpoint, which needs SynPlanner[cpu] (or a CUDA extra), or can be exported using SynPlanner[training]. download_all_data still exists but is deprecated — do not use it.

2. `configs/*.yaml` are not installed by pip. They live only in the git repository. Either clone it, or fetch the one you need:

curl -O https://raw.githubusercontent.com/Laboratoire-de-Chemoinformatique/SynPlanner/main/configs/planning_standard.yaml

synplan planning --config is required and has no built-in default.

When a GPU matters

Only two workflows benefit from a GPU: reaction mapping (reaction_mapping) and network training (ranking_policy_training, filtering_policy_training, mhn_network_tuning, value_network_tuning). Everything else — planning, data curation, rule extraction, route analysis — runs on CPU, which is the typical case.

With uv in a source clone, choose one backend: cpu, cu126, or cu128. Combine it with the workflow extra; all includes workflows, not a backend:

uv sync --no-dev --extra curation --extra cu128   # GPU atom mapping
uv sync --no-dev --extra training --extra cu126  # GPU training
uv sync --no-dev --extra all --extra cu128       # all workflows

The backend indexes are configured for uv; pip install 'SynPlanner[cu128]' alone does not select the CUDA wheel index. For a pip installation, select the Torch build through the PyTorch package index. If the user needs GPU setup, read Selecting a PyTorch build and run the install yourself. Do not hand the user a link and stop.

chython is not RDKit

Default to SynPlanner-native output.

Ask which the user wants up front only when one of these is true:

• their existing code imports rdkit
• results will be compared against external data
• the output feeds another tool

Otherwise assume native and do not interrupt. When every step is complete, ask once whether to verify RDKit compatibility of the final result.

Never compare SMILES strings across engines. Canonical SMILES from chython differ from canonical SMILES from RDKit for the same molecule. To compare molecules, either parse both through the same engine and compare the resulting objects, or compare InChI.

Choose the stock format deliberately. Legacy SMILES/SDF/CSV/TSV stocks are canonical-SMILES sets. A vendor-priced JSON catalogue is a different public workflow: prepare it with standardize_building_blocks, load it with load_building_block_catalogue, and pass that one immutable catalogue to both the rollout evaluator and Tree. Its MCTS identity is the first 14 characters of a Chython Standard InChIKey, so stereo, isotope and protonation differences are intentionally collapsed. Full keys and stereo are metadata, not a claim of stereo-aware planning. The task index gives the preparation and costing sequence.

When the user needs RDKit objects at the boundary, use synplan.chem.rdkit_compat rather than converting by hand:

Requires rdkit to be installed.

Write the least code possible

Before writing code, check whether SynPlanner already does the task. Stop at the first rung that holds:

1. A CLI command. Run synplan --help. The CLI covers the full pipeline —

see the table below.

1. A documented module. Anything under docs/api_reference/. Note that

synplan.Tree is the only symbol exported at top level.

1. Other functions inside SynPlanner.
2. chython directly. Last resort, only when SynPlanner does not cover it.

The ladder shortens the code, never the checking. Reimplementing something that already exists is the common failure here — not writing too much code. Look before you write.

A worked example of that failure: asked for a table of rules or synthons with each one drawn, the reflex is to loop depict() into HTML or build a DataFrame by hand. rules_frame, synthons_frame and ChemFrame already do it, and the hand-rolled version reads rules.json directly and so misses that a ring rule must be shown in its hand-authored reagent form. See "Show rules, synthons or any chython objects as a table" in references/tasks.md.

The reverse failure is as bad: do not force a rung that does not fit. Three SynPlanner calls chained into a workaround is worse than one honest chython call.

synplan --help lists every command. The CLI covers the whole pipeline — ORD import, curation, rule extraction, training, planning, clustering — so check it before writing Python, and prefer it for long-running work.

How to use references/tasks.md

Also published here if you are working without the repository.

1. Scan the bold titles for the one matching the request. They are phrased the

way users ask — "find a synthesis route for a molecule", "clean a reaction dataset", "compare two sets of routes", "nothing was found".

1. Read that entry. It names the functions and the order to call them in.
2. Follow its links only if you need running code or the reasoning behind a

parameter.

1. Check the combinations section first — most real requests are a chain of two

or three entries, not one.

Do not write your own route-tree walker. Recursing over the route structure to count depth or collect precursors is the most common reinvention here, and every one of those traversals already exists — extract_routes, export_tree_to_json, compose_all_route_cgrs and the rest are listed in tasks.md under "Working with routes".

Use a config from configs/, do not write YAML from scratch

One shipped config per task lives in configs/ in the repository — ls it. Copy the closest and edit it; they are small, and reading one takes less time than getting a hand-written config subtly wrong.

Start with the defaults, then adjust when the data says to

The shipped configs are tuned for large public datasets. On a smaller or different corpus a stage can legitimately return nothing — standardization rejecting every reaction, rule extraction writing a file with only a header, planning finding no routes. None of these raise an error.