DOCSEARCHbyAlgolia
Submit Docs

Syntheseus: Framework for Retrosynthetic Planning

repository·main·Indexed 41 days ago

https://github.com/microsoft/syntheseus

A Python framework for end-to-end retrosynthetic planning that standardizes the integration of search algorithms (such as retro_star, mcts, and pdvn) and reaction models. It provides wrappers for state-of-the-art models including RetroChimera, Chemformer, and LocalRetro, and supports single-step evaluation via CLI with JSONL, CSV, and SMILES data formats.

Tokens
12.4K
Snippets
31
Records
47
Agent score
52%

What's inside Syntheseus

  1. Overview of Syntheseus

    main

    Syntheseus is a Python package designed for end-to-end retrosynthetic planning. It provides a standardized framework to combine search algorithms with reaction models.

    Key capabilities include:

    • Standardized Integration: Combines search algorithms and reaction models using a unified interface.
    • Search Algorithms: Includes implementations of common search algorithms for retrosynthesis.
    • Reaction Model Wrappers: Provides wrappers for state-of-the-art reaction models.
    • Extensibility: Exposes a simple API to plug in custom models and algorithms.
    • Benchmarking: Can be used to benchmark individual components within a retrosynthesis pipeline.

  2. Install specific Syntheseus model subsets

    main

    To reduce the environment size, you can replace the all option with a comma-separated list of specific model or utility subsets.

    Available subsets:

    • chemformer
    • graph2edits
    • local-retro
    • megan
    • mhn-react
    • retro-knn
    • retrochimera
    • root-aligned
    • viz (visualization dependencies)
    • dev (development dependencies)

    Example: Installing only LocalRetro and RootAligned

    pip install -e ".[local-retro,root-aligned]"

    If using the GitHub installation method, you should also delete the lines in environment_full.yml corresponding to the models you do not intend to use to keep the Conda environment clean.

  3. How to file issues and get help

    main

    If you encounter bugs, have feature requests, or need help using Syntheseus, you can use the following channels:

    1. GitHub Issues: Search existing issues on GitHub first to avoid duplicates. If no solution exists, file a new Issue for bugs or feature requests.
    2. Email: You can also contact the maintainers via email for questions and help.

    The project team aims to respond to all issues filed.

  4. Install Syntheseus with all extras

    main

    To install the full version of syntheseus including all reaction models and search algorithm extras, use the provided Conda environment file and install the package with the [all] extra.

    Note on Version Compatibility:

    • The full installation pins torch to version 2.2.2.
    • If you need to run models under 1.x, you must downgrade to syntheseus 0.6.0.

    For a lightweight installation containing only specific components, refer to the official installation guide.

    conda env create -f environment_full.yml
conda activate syntheseus-full

pip install "syntheseus[all]"

  5. Install Syntheseus without dependencies

    main

    If you want to manually manage dependencies for a very specific part of the project, you can install the package without any automatic dependency installation:

    pip install -e . --no-dependencies

    Refer to pyproject.toml to identify which dependencies are required for the search and reaction_prediction subpackages.

  6. Install Syntheseus (Core mode)

    main

    Use the core installation if you only need to build and benchmark your own models or search algorithms. This mode includes minimal dependencies and excludes ML libraries.

    Via pip (Latest released version)

    conda env create -f environment.yml
conda activate syntheseus
pip install syntheseus

    Via GitHub (Latest development changes)

    conda env create -f environment.yml
conda activate syntheseus
pip install -e .

  8. Select a single-step model and checkpoint

    main

    Syntheseus supports 11 single-step models. Models are categorized by the dataset they were trained on: Pistachio (recommended) or USPTO-50K.

    Recommended Models (Trained on Pistachio)

    Use these for better performance if your task aligns with the Pistachio dataset. These include:

    • RetroChimera (Default recommendation)
    • RetroChimeraEdit
    • RetroChimeraDeNovo

    Other Models (Trained on USPTO-50K)

    These models are trained on the USPTO-50K dataset and include:

    • Chemformer (Finetuned by Syntheseus)
    • GLN
    • Graph2Edits
    • LocalRetro
    • MEGAN
    • MHNreact
    • RetroKNN
    • RootAligned

    If you do not specify a checkpoint directory when loading a model, Syntheseus will automatically download the corresponding default checkpoint from the provided links and cache it locally.

    #### Recommended models (trained on Pistachio)

| Model checkpoint link                                          | Source                                   |
|----------------------------------------------------------------|------------------------------------------|
| [RetroChimera](https://figfigure.com/ndownloader/files/59468882) | trained by us                            |
| [RetroChimeraEdit](https://figfigure.com/ndownloader/files/61362964) | trained by us                            |
| [RetroChimeraDeNovo](https://figfigure.com/ndownloader/files/61360657) | trained by us                            |

#### Other models (trained on USPTO-50K)

| Model checkpoint link                                          | Source                                   |
|----------------------------------------------------------------|------------------------------------------|
| [Chemformer](https://figfigure.com/ndownloader/files/42009888)  | finetuned by us starting from checkpoint |
| [GLN](https://figfigure.com/ndownloader/files/45882867)         | released by authors                       |
| [Graph2Edits](https://figfigure.com/ndownloader/files/44194301) | released by authors                       |
| [LocalRetro](https://figfigure.com/ndownloader/files/42287319)  | trained by us                             |
| [MEGAN](https://figfigure.com/ndownloader/files/42012732)       | trained by us                             |
| [MHNreact](https://figfigure.com/ndownloader/files/42012777)    | trained by us                             |
| [RetroKNN](https://figfigure.com/ndownloader/files/45662430)     | trained by us                             |
| [RootAligned](https://figfigure.com/ndownloader/files/42012792) | released by authors                       |

  9. Run a search using the Syntheseus CLI

    main

    Use the syntheseus search command to perform a retrosynthetic search. You must provide a file containing search targets (SMILES) and a file containing the inventory of purchasable molecules (SMILES).

    Both input files must be plain SMILES files with one molecule per line.

    Required and common arguments:

    • search_targets_file: Path to the SMILES file containing the molecules you want to find routes for.
    • inventory_smiles_file: Path to the SMILES file containing the list of available/purchasable molecules.
    • model_class: The class name of the model to use.
    • model_dir: The directory containing the model checkpoint. (Note: You can omit this if using a natively supported single-step model to use the default checkpoint).
    • time_limit_s: The number of seconds allocated per target molecule.
    syntheseus search \
    search_targets_file=[SMILES_FILE_WITH_SEARCH_TARGETS] \
    inventory_smiles_file=[SMILES_FILE_WITH_PURCHASABLE_MOLECULES] \
    model_class=[MODEL_CLASS] \
    model_dir=[MODEL_DIR] \
    time_limit_s=[NUMBER_OF_SECONDS_PER_TARGET]

  10. Install Syntheseus (Full mode)

    main

    Use the full installation to perform end-to-end search using all supported models. This mode includes all ML models and dependencies for visualization and development.

    Note: environment_full.yml pins the CUDA version to 11.3 for reproducibility. If you require a different CUDA version, you must edit the environment file before running the commands.

    Via pip (Latest released version)

    conda env create -f environment_full.yml
conda activate syntheseus-full
pip install "syntheseus[all]"

    Via GitHub (Latest development changes)

    conda env create -f environment_full.yml
conda activate syntheseus-full
pip install -e ".[all]"

  11. Filter backward model proposals with a forward model

    main

    You can optionally filter the proposals generated by the backward reaction model using a forward reaction model. This is configured via the forward_filter option.

    Configuration Keys:

    • model_class: The class of the forward model to use.
    • top_k: The number of top forward predictions to check the proposed product against.
    • filter_kwargs: Additional keyword arguments passed to the ForwardReactionFilterModel.

  12. Configure the Syntheseus model cache directory

    main

    Syntheseus automatically downloads and caches default model checkpoints to disk if no checkpoint directory is provided during model loading.

    By default, the cache is stored at $HOME/.cache/torch/syntheseus. You can change this location by setting the SYNTHESEUS_CACHE_DIR environment variable.

    export SYNTHESEUS_CACHE_DIR="/your/custom/path"