aizynthfinder-retrosynthesis

Files (1)

• SKILL.md

SKILL.md (first lines)

# AiZynthFinder Retrosynthesis

## Overview

AiZynthFinder performs computer-aided synthesis planning (CASP): a search algorithm — Monte Carlo tree search by default — recursively disconnects a target molecule into precursors, guided by a neural expansion policy that ranks known reaction templates. The search terminates when all precursors are found in a *stock* (a set of purchasable building blocks) or the maximum depth is reached. Output is a ranked set of reaction trees plus per-target statistics (`is_solved`, step count, precursors in/out of stock).

Version covered: **4.4.1** (Python 3.10–3.12). The v4 config format differs substantially from v2/v3 as described in the 2020 paper — never copy a config from an old blog post without translating it.

## When to Use

- Planning a synthesis route for a designed or purchased target molecule
- Screening a compound library for synthesizability before committing to make-on-demand
- Finding purchasable precursors or building blocks that lead to a scaffold
- Ranking design ideas by route length and by how many precursors fall outside a catalogue
- Enumerating the first retro step only — plausible disconnections without a full tree
- Testing whether a specific bond can be made disconnection-aware (`break_bonds`) in a route
- Comparing solve rate across two building-block catalogues for the same target set
- Use `torchdrug` instead when training a retrosynthesis model rather than running route search
- For forward reaction barriers and transition states use `neb-irc-activation-energy`; for drawing the resulting scheme use `rdkit-chemdraw-cdxml`

## Prerequisites

- **Python packages**: `aizynthfinder` (4.4.x), `rdkit`, `pandas`
- **Data requirements**: a stock file (InChIKeys), a trained expansion policy (ONNX model + template CSV), optionally a filter policy
- **Environment**: Python 3.10–3.12. Default runtime is `onnxruntime`; TensorFlow is not needed unless serving remote models or loading legacy `.hdf5` Keras models.

Check before installing — `aizynthcli`, `download_public_data`, and `smiles2stock` ship with the package and may already be on PATH inside a pixi/conda env. Inside a pixi project, invoke them as `pixi run aizynthcli ...`.

```bash
command -v aizynthcli || {
  conda create "python>=3.10,<3.13" -n aizynth-env -y
  conda activate aizynth-env
  python -m pip install "aizynthfinder[all]"
}
```

`[all]` adds molbloom (bloom-filter stocks), pymongo, route-distances (route clustering), scipy, and timeout-decorator. Drop it for a lighter install; add `[tf]` only for TF-serving or `.hdf5` models.

## Quick Start

```python
from aizynthfinder.aizynthfinder import AiZynthFinder

finder = AiZynthFinder(configfile="config.yml")
finder.stock.select("zinc")
finder.expansion_policy.select("uspto")

finder.target_smiles = "Cc1cccc(c1N(CC(=O)Nc2ccc(cc2)c3ncon3)C(=O)C4CCS(=O)(=O)CC4)C"
finder.tree_search()
finder.build_routes()                    # required before touching finder.routes

stats = finder.extract_statistics()
print(f"solved={stats['is_solved']} steps={stats['number_of_steps']} "
      f"routes={stats['number_of_routes']} time={stats['search_time']:.1f}s")
finder.routes[0]["image"].save("route_top.png")
```

## Workflow

### Step 1: Get the Models and Stock

`download_public_data` fetches the public USPTO models and the ZINC stock subset (several hundred MB, from zenodo.org and figshare.com) and writes a ready-to-use `config.yml`.

```bash
# Skip if the folder already holds the models — this is a large download.
test -f my_folder/config.yml || download_public_data my_folder

ls my_folder
# uspto_model.onnx              uspto_templates.csv.gz
# uspto_ringbreaker_model.onnx  uspto_ringbreaker_templates.csv.gz
# uspto_filter_model.onnx       zinc_stock.hdf5
# config.yml
```

### Step 2: Write or Adjust config.yml

The list short-cut means "template-based strategy, model first, templates second, defaults elsewhere". The same short-cut works for a single `filter` model path and a single `stock` file path.

```yaml
# config.yml — minimal
expansion:
  uspto:
    - uspto_model.onnx
    - uspto_templates.csv.gz
stock:
  zinc: zinc_stock.hdf5
```

```yaml
# config.yml — explicit form, the settings that matter in practice
search:
  algorithm: mcts
  algorithm_config:
    C: 1.4
    use_prior: True
    prune_cycles_in_search: True
    search_rewards: ["state score"]
  max_transforms: 6
  iteration_limit: 100
  time_limit: 120
  return_first: false
  exclude_target_from_stock: True
expansion:
  uspto:
    type: template-based
    model: uspto_model.onnx
    template: uspto_templates.csv.gz
    template_column: retro_template
    cutoff_cumulative: 0.995
    cutoff_number: 50
    use_rdchiral: True
filter:
  uspto:
    type: quick-filter
    model: uspto_filter_model.onnx
    filter_cutoff: 0.05
stock:
  zinc:
    type: inchiset

From FridrichMethod/awesome-skills, MIT.

More from FridrichMethod/awesome-skills