-
Notifications
You must be signed in to change notification settings - Fork 19
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This PR adds an initial static documentation built using Material for MkDocs. The docs are built automatically using GitHub Actions and deployed to microsoft.github.io/syntheseus/. This first version is a combination of content we had in `README.md` (which is changed here to be very minimalistic, linking to the docs for further information) and the pre-existing `docs/cli/eval_single_step.md`. In future PRs we can extend the docs with documentation for the search CLI, as well as an API reference and tutorials.
- Loading branch information
Showing
8 changed files
with
174 additions
and
66 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| name: Docs | ||
|
|
||
| on: | ||
| push: | ||
| branches: [ main ] | ||
| workflow_dispatch: | ||
|
|
||
| permissions: | ||
| contents: write | ||
|
|
||
| jobs: | ||
| deploy: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| - name: Configure Git Credentials | ||
| run: | | ||
| git config user.name github-actions[bot] | ||
| git config user.email 41898282+github-actions[bot]@users.noreply.github.com | ||
| - uses: actions/setup-python@v4 | ||
| with: | ||
| python-version: 3.x | ||
| - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV | ||
| - uses: actions/cache@v3 | ||
| with: | ||
| key: mkdocs-material-${{ env.cache_id }} | ||
| path: .cache | ||
| restore-keys: | | ||
| mkdocs-material- | ||
| - run: pip install mkdocs-material | ||
| - run: mkdocs gh-deploy --force |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes
File renamed without changes
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| <figure markdown> | ||
| {width="450"} | ||
| <figcaption><h3>Navigating the labyrinth of synthesis planning</h3></figcaption> | ||
| </figure> | ||
|
|
||
| --- | ||
|
|
||
| [](https://github.com/microsoft/syntheseus/actions/workflows/ci.yml) | ||
| [](https://www.python.org/downloads/) | ||
| [](https://github.com/ambv/black) | ||
| [](https://github.com/microsoft/syntheseus/blob/main/LICENSE) | ||
|
|
||
| Syntheseus is a package for end-to-end retrosynthetic planning. | ||
|
|
||
| - ⚒️ Combines search algorithms and reaction models in a standardized way | ||
| - 🧭 Includes implementations of common search algorithms | ||
| - 🧪 Includes wrappers for state-of-the-art reaction models | ||
| - ⚙️ Exposes a simple API to plug in custom models and algorithms | ||
| - 📈 Can be used to benchmark components of a retrosynthesis pipeline |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,54 @@ | ||
| We support two installation modes: | ||
|
|
||
| - *core installation* allows you to build and benchmark your own models or search algorithms | ||
| - *full installation* also allows you to perform end-to-end search using the supported models | ||
|
|
||
| === "Core installation" | ||
|
|
||
| ```bash | ||
| conda env create -f environment.yml | ||
| conda activate syntheseus | ||
|
|
||
| pip install -e . | ||
| ``` | ||
|
|
||
| === "Full installation" | ||
|
|
||
| ```bash | ||
| conda env create -f environment_full.yml | ||
| conda activate syntheseus-full | ||
|
|
||
| pip install -e ".[all]" | ||
| ``` | ||
|
|
||
| Core installation includes only minimal dependencies (no ML libraries), while full installation includes all supported models and also dependencies for visualization/development. | ||
|
|
||
| Instructions above assume you already cloned the repository via | ||
|
|
||
| ```bash | ||
| git clone https://github.com/microsoft/syntheseus.git | ||
| cd syntheseus | ||
| ``` | ||
|
|
||
| Note that `environment_full.yml` pins the CUDA version (to 11.3) for reproducibility. | ||
| If you want to use a different one, make sure to edit the environment file accordingly. | ||
|
|
||
| ??? info "Setting up GLN" | ||
|
|
||
| We also support GLN, but it requires a specialized environment and is thus not installed via `pip`. | ||
| See [here](https://github.com/microsoft/syntheseus/blob/main/syntheseus/reaction_prediction/environment_gln/Dockerfile) for a Docker environment necessary for running GLN. | ||
|
|
||
| ## Reducing the number of dependencies | ||
|
|
||
| To keep the environment smaller, you can replace the `all` option with a comma-separated subset of `{chemformer,local-retro,megan,mhn-react,retro-knn,root-aligned,viz,dev}` (`viz` and `dev` correspond to visualization and development dependencies, respectively). | ||
| For example, `pip install -e ".[local-retro,root-aligned]"` installs only LocalRetro and RootAligned. | ||
| If installing a subset of models, you can also delete the lines in `environment_full.yml` marked with names of models you do not wish to use. | ||
|
|
||
| If you only want to use a very specific part of `syntheseus`, you could also install it without dependencies: | ||
|
|
||
| ```bash | ||
| pip install -e . --no-dependencies | ||
| ``` | ||
|
|
||
| You then would need to manually install a subset of dependencies that are required for a particular functionality you want to access. | ||
| See `pyproject.toml` for a list of dependencies tied to the `search` and `reaction_prediction` subpackages. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| Syntheseus currently supports 7 established single-step models. For convenience, for each model we also include a checkpoint trained on USPTO-50K. | ||
|
|
||
| | Model checkpoint link | Source | | ||
| |----------------------------------------------------------------|--------| | ||
| | [Chemformer](https://figshare.com/ndownloader/files/42009888) | finetuned by us starting from checkpoint released by authors | | ||
| | [GLN](https://figshare.com/ndownloader/files/42012720) | released by authors | | ||
| | [LocalRetro](https://figshare.com/ndownloader/files/42012729) | trained by us | | ||
| | [MEGAN](https://figshare.com/ndownloader/files/42012732) | trained by us | | ||
| | [MHNreact](https://figshare.com/ndownloader/files/42012777) | trained by us | | ||
| | [RetroKNN](https://figshare.com/ndownloader/files/42012786) | trained by us | | ||
| | [RootAligned](https://figshare.com/ndownloader/files/42012792) | released by authors | | ||
|
|
||
| ??? note "More advanced datasets" | ||
|
|
||
| The USPTO-50K dataset is well-established but relatively small. Advanced users may prefer to retrain their models of interest on a larger dataset, such as USPTO-FULL or Pistachio. To do that, please follow the instructions in the original model repositories. | ||
|
|
||
| In `reaction_prediction/cli/eval.py` a forward model can be used for computing back-translation (round-trip) accuracy. | ||
| See [here](https://figshare.com/ndownloader/files/42012708) for a Chemformer checkpoint finetuned for forward prediction on USPTO-50K. As for the backward direction, pretrained weights released by original authors were used as a starting point. | ||
|
|
||
| ??? info "Licenses" | ||
| All checkpoints were produced in a way that involved external model repositories, hence may be affected by the exact license each model was released with. | ||
| For more details about a particular model see the top of the corresponding model wrapper file in `reaction_prediction/inference/`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| site_name: Syntheseus | ||
|
|
||
| repo_name: microsoft/syntheseus | ||
| repo_url: https://github.com/microsoft/syntheseus | ||
| edit_uri: edit/main/docs/ | ||
|
|
||
| theme: | ||
| name: material | ||
| palette: | ||
| - media: "(prefers-color-scheme: light)" | ||
| scheme: default | ||
| primary: black | ||
| accent: red | ||
| toggle: | ||
| icon: material/toggle-switch | ||
| name: "Switch to dark mode" | ||
| - media: "(prefers-color-scheme: dark)" | ||
| scheme: slate | ||
| primary: black | ||
| accent: red | ||
| toggle: | ||
| icon: material/toggle-switch-off-outline | ||
| name: "Switch to light mode" | ||
| features: | ||
| - content.code.copy | ||
| - navigation.tabs | ||
|
|
||
| nav: | ||
| - Get Started: | ||
| - Overview: index.md | ||
| - Installation: installation.md | ||
| - Single-Step Models: single_step.md | ||
| - CLI: | ||
| - Single-Step Evaluation: cli/eval_single_step.md | ||
|
|
||
| markdown_extensions: | ||
| - admonition | ||
| - attr_list | ||
| - md_in_html | ||
| - pymdownx.details | ||
| - pymdownx.superfences | ||
| - pymdownx.tabbed: | ||
| alternate_style: true |