ASKCOS

A web application for computer-aided synthesis planning.

Requirement

Hardware

• CPU: x86, >= 4 cores. Mac with ARM CPUs (Apple Silicon) are currently not supported.
• RAM: >= 32 GB.
• GPU (only required for model retraining): >= 8 GB GPU RAM.

Software

• OS: Ubuntu (>= 20.04) recommended.
• docker (>= version 20). See Install docker.
• CUDA (only required for model retraining): >= 11.3.
• python: >= 3.6 with pyyaml and requests (both pip installable). pytest is required for optional API tests.
• git and make.
• ssh access set up for gitlab.com. See Add an SSH key to Gitlab.

Please note that >= 32 GB of RAM is highly recommended for the full deployment of ASKCOS. If memory size is a constraint, please check out 04-Deployment for customizing a local deployment (e.g., backend only, or minimalist deployment to use only the retrosynthesis functionality).

Getting started

$ mkdir ASKCOSv2
$ cd ASKCOSv2
$ git clone git@gitlab.com:mlpds_mit/askcosv2/askcos2_core.git
$ cd askcos2_core
$ make deploy

The setup phase will then run automatically, e.g., cloning the repos for backend modules, building docker images, seeding databases. After setup, the web app will be started with the Graphical User Interface accessible at the host ip address, e.g., 0.0.0.0. Simply type this address in your browser, and the welcome page will appear. CONTINUE AS GUEST to explore ASKCOS. Signup or login is not required for using most modules.

Signup or login is however required to use the retrosynthesis planning functionality, including certain parts of the Interactive Path Planner (IPP) and the Tree Builder. This is by design, as any planning result is linked to a user account. Any attempt(s) to use the IPP or the Tree Builder without login will result in re-direction back to the welcome/login page. The signup process is simple; type in a username and a password, click SIGN UP, and it's done. Accounts are stored locally on the server that you are logged in to.

The web app is written in Vue.js, which communicates with the backend. The core piece of the backend, the API Gateway, is written in FastAPI, with its own interactive documentation accessible at http://0.0.0.0:9100/docs.

Updating ASKCOS deployment (since 2024.10)

Updating is much easier otherwise, if no seeding or re-seeding is needed.

$ cd askcos2_core
$ make stop
$ git pull
$ mv .env .env_backup
$ make update

In general, we recommend removing (by renaming) the old .env, and reinitializing it with the latest .env.example which was done as part of make update. This is because there might be update to the configurable environment variables.

Updating ASKCOS deployment (from version earlier than 2024.10)

For the 2024.10 release, we did some refactor to the pre-computation stage, and updated some .mar files for retro/{augmented_transformer,graph2smiles}. Therefore, the instruction below is slightly longer for updating ASKCOS to 2024.10.

First, stop the running services from under askcos2_core

$ cd askcos2_core
$ make stop

Then pull the latest askcos2_core and re-seed the reactions collection. This is needed to use the newly added exact_match strategy for one-step retro.

$ git pull
$ bash deploy.sh generate-deployment-scripts
$ bash deploy.sh get-images
$ bash deploy.sh seed-db --reactions default

Delete some old models; the newer version will be automatically downloaded as part of the make update later.

$ rm -r ../retro/augmented_transformer/mars/USPTO_FULL.mar
$ rm -r ../retro/augmented_transformer/mars/pistachio_23Q3.mar
$ rm -r ../retro/graph2smiles/mars/USPTO_FULL.mar
$ rm -r ../retro/graph2smiles/mars/pistachio_23Q3.mar

Lastly, update the deployment with

$ mv .env .env_backup
$ make update

[Optional] API Tests

Once all ASKCOS services have been started, the API tests can be run with

$ cd askcos2_core
$ V2_HOST=http://0.0.0.0 V2_PORT=9100 make test

The runtime variables HOST and PORT should be replaced with the actual host name/ip and port, if different from the above default. Note that the tests for certain modules have been turned off because it can take a very long time to run.

Latest release note

[2024.01 Release Notes](01 2024.01 Release Note)