rush-py

Python SDK for the QDX Rush quantum computational chemistry workflow management system

Quickstart

This guide will walk you through executing a basic job using Rush, by demonstrating how to generate 3D small molecule conformers. For a deeper dive and an example of a full end-to-end in silico protocol, see the Comprehensive Guide.

Install

First, install the following modules via the command-line (we require Python ≥ 3.9):

pip install rush-py

Full Code

One of the simplest things you can do with Rush is generate 3D small molecule conformers from SMILES using the Auto3D module. We will break down how to do this step-by-step, but lets start with the full code:

import rush

client = rush.build_blocking_provider_with_functions(
    access_token=PUT_YOUR_TOKEN_HERE
    # for example, if your token is 00000000-dddd-cccc-0000-11111111,
    # then you should put access_token="00000000-dddd-cccc-0000-11111111"
    # (including the double quotes)
)

# setup an SMI file that contains the SMILES string of our ligand
ligand_smi_filename = client.workspace / "ligand.smi"
ligand_smi_filename.write_text("CN1C=NC2=C1C(=O)N(C(=O)N2C)C 1")

# run Auto3D which will give us 3 conformers of our ligand
# in the SDF format and the QDXF format
ligand_sdf_handle, ligand_qdxf_handle = client.auto3d(
    ligand_smi_filename,  # the filename that stores our ligand
    "smi",  # the format of the file
    {
        "k": 3,  # number of conformers to generate
        "use_gpu": True,  # use GPU for faster compute
    },
    tags=[
        "your_job_name"
    ],  # Add your own identifiers to keep track of your simulations,
    # separated by , e.g. tags=["small ligands", "smiles"]
    resources={
        "gpus": 1,  # the number of GPUs to use
        "storage": 5,  # the amount of storage to use
        "storage_units": "MB",  # the units of storage (here we are using megabytes)
    },
)

# print the status of all jobs
print(client.status())

# download the results (this will block until the Auto3D job has completed)
ligand_sdf = ligand_sdf_handle.download()
ligand_qdxf = ligand_qdxf_handle.download()

print(ligand_sdf)  # print the path to the downloaded SDF file

print(
    ligand_sdf.read_text()[0:100]
)  # print the first 100 characters of the SDF version of the result
print(
    ligand_qdxf.read_text()[0:100]
)  # print the first 100 characters of the the QDXF version of the result

2024-05-13 17:14:09,904 - rush - INFO - Not restoring by default via env
{'e2ba6f4c-5aa2-4b15-9da2-24d754e59acd': (<ModuleInstanceStatus.RESOLVING: 'RESOLVING'>, 'auto3d', 1)}
2024-05-13 17:14:13,311 - rush - INFO - Argument 60dad20e-a065-4e80-8631-a5d91ca9666c is now ModuleInstanceStatus.RESOLVING
2024-05-13 17:14:15,815 - rush - INFO - Argument 60dad20e-a065-4e80-8631-a5d91ca9666c is now ModuleInstanceStatus.ADMITTED
2024-05-13 17:14:28,962 - rush - INFO - Argument 60dad20e-a065-4e80-8631-a5d91ca9666c is now ModuleInstanceStatus.DISPATCHED
2024-05-13 17:14:34,853 - rush - INFO - Argument 60dad20e-a065-4e80-8631-a5d91ca9666c is now ModuleInstanceStatus.RUNNING
2024-05-13 17:15:07,769 - rush - INFO - Argument 60dad20e-a065-4e80-8631-a5d91ca9666c is now ModuleInstanceStatus.AWAITING_UPLOAD
objects/96568f2e-1708-4d54-8fed-3646101f48e9
1
     RDKit          3D

 24 25  0  0  0  0  0  0  0  0999 V2000
   -1.9595   -2.3573    0.7656 C  
[
  {
    "topology": {
      "version": "V1",
      "symbols": [
        "C",
        "N",

Step-by-step

Import the Rush Python library

The first thing we do is import the rush Python library:

import rush

Create a Rush client

The next step is to create a client. This client will be used to interact with the Rush API. You will need to provide your Access Token to authenticate with the API. You can get your Access Token by signing up at https://rush.qdx.co and going into your account settings.

Usually, you should store your Access Token somewhere safe and not hardcode it into your scripts (e.g. in a configuration file or environment variable). For the sake of this example, we will hardcode it:

client = rush.build_blocking_provider_with_functions(
    access_token=PUT_YOUR_TOKEN_HERE  # for example, if your token is 00000000-dddd-cccc-0000-11111111,
    # then you should put access_token="00000000-dddd-cccc-0000-11111111"
    # (including the double quotes)
)

But specifying that we want a “blocking provider” we are telling Rush that whenever we interact with the API we want to wait for the response before continuing. This is useful for simple scripts that are not running lots of jobs in parallel.

Create an example SMILES file

To run Auto3D we need to specify the SMILES strings for which we want 3D conformers to be generated. These SMILES strings must be stored in a .smi file. For this example, we will use a sample file that contains the SMILES strings for one simple small molecule:

# setup an SMI file that contains the SMILES string of our ligand
ligand_smi_filename = client.workspace / "ligand.smi"
ligand_smi_filename.write_text("CN1C=NC2=C1C(=O)N(C(=O)N2C)C 1")

A small note about workspaces

By default, the client.workspace will be your current working directory, so after this code runs you should see a file in your current working directory called "ligand.smi". If you want to specify a different workspace directory, you can do so by specifying the workspace argument when building the client:

# instead of creating a client with this code
client = rush.build_blocking_provider_with_functions(
    access_token=PUT_YOUR_TOKEN_HERE
)

# you can create a client with this code, and explicitly set the workspace
client = rush.build_blocking_provider_with_functions(
    access_token=PUT_YOUR_TOKEN_HERE,
    workspace=PUT_YOUR_PREFERRED_WORKING_DIRECTORY_HERE,  # for example, if you
    # want your run data to be saved in a subfolder called job1, you should put
    # workspace = "./job1"
)

2024-05-13 15:14:59,504 - rush - INFO - Not restoring by default via env
2024-05-13 15:15:02,393 - rush - INFO - Not restoring by default via env

Run Auto3D

Now that we have our SMILES file, we can use it as input to run the Auto3D module. This will generate 3D conformers (in a variety of possible protonation states) for each SMILES string in the SMILES file:

# run Auto3D which will give us 3 conformers of our ligand
# in the SDF format and the QDXF format
ligand_sdf_handle, ligand_qdxf_handle = client.auto3d(
    ligand_smi_filename,  # the filename that stores our ligand
    "smi",  # the format of the file
    {
        "k": 3,  # number of conformers to generate
        "use_gpu": True,  # use GPU for faster compute
    },
    tags=[
        "your_job_name"
    ],  # Add your own identifiers to keep track of your simulations,
    # separated by , e.g. tags=["small ligands", "smiles"]
    resources={
        "gpus": 1,  # the number of GPUs to use
        "storage": 5,  # the amount of storage to use
        "storage_units": "MB",  # the units of storage (here we are using megabytes)
    },
)

A small note about resources

In addition to their module-specific inputs, all modules also accept the resource= parameter. This parameter specifies the computational resources that you want to use to run the module. In this example, we have asked Rush to run the Auto3D module using 1 GPU and 5 megabytes of storage space.

See the job status

Calling client.auto3d will tell Rush to run a new Auto3D job. However, it will not wait for the job to complete before continuing. This is convenient, because sometimes jobs can take a long time to run, and we might have other code we want to run in the meantime. If we want to track the status of all of our jobs, we can use the client.status function:

# print the status of all jobs
print(client.status())

{'8f835ec6-beef-4db5-bd3a-f43dd30c5c8c': (<ModuleInstanceStatus.RESOLVING: 'RESOLVING'>, 'auto3d', 1), '26f07d72-bb16-4eb8-b23c-b620e5dd8182': (<ModuleInstanceStatus.COMPLETED: 'COMPLETED'>, 'auto3d', 1)}

Download the results

After calling client.auto3d, we got back two handles: ligand_sdf_handle and ligand_qdxf_handle. These handles are references to the results of the Auto3D job. They are stored in Rush and we can access them from anywhere at any time. We can use these handles as inputs to other modules, we can download their contents, and we can even use them to check the status of the Auto3D job that we ran.

For now, we simply download the results and print them out:

# download the results (this will block until the Auto3D job has completed)
ligand_sdf = ligand_sdf_handle.download()
ligand_qdxf = ligand_qdxf_handle.download()

print(ligand_sdf.read_text()[0:100])  # print the SDF version of the result
print(ligand_qdxf.read_text()[0:100])  # print the QDXF version of the result

2024-05-13 15:15:05,826 - rush - INFO - Argument 2933987a-202a-48b5-a671-3ceb1d013f5e is now ModuleInstanceStatus.RESOLVING
2024-05-13 15:15:10,664 - rush - INFO - Argument 2933987a-202a-48b5-a671-3ceb1d013f5e is now ModuleInstanceStatus.ADMITTED
2024-05-13 15:15:22,517 - rush - INFO - Argument 2933987a-202a-48b5-a671-3ceb1d013f5e is now ModuleInstanceStatus.DISPATCHED
2024-05-13 15:15:28,547 - rush - INFO - Argument 2933987a-202a-48b5-a671-3ceb1d013f5e is now ModuleInstanceStatus.RUNNING
2024-05-13 15:16:00,749 - rush - INFO - Argument 2933987a-202a-48b5-a671-3ceb1d013f5e is now ModuleInstanceStatus.AWAITING_UPLOAD
1
     RDKit          3D

 24 25  0  0  0  0  0  0  0  0999 V2000
   -1.9595   -2.3573    0.7656 C  
[
  {
    "topology": {
      "version": "V1",
      "symbols": [
        "C",
        "N",

If you want to find the actual files, they will be in the objects directory inside your client.workspace directory. Remember, by default, the client.workspace is the current working directory.

A note about handles

For most things that we are interested in doing, we do not have to wait for the job created by client.auto3d to actually complete. We can start using ligand_sdf_handle and ligand_qdxf_handle straight away. For example, we could pass them as inputs to a molecular dynamics simulation job. This would tell Rush to automatically run the molecular dynamics simulation job as soon as the Auto3D job completes.

However, the download function is kind of special and will explicitly block our program from continuing until the Auto3D job is complete. This is because download actually fetches the contents of the handles from Rush, and to do so it needs to be sure the contents actually exists.

Next steps

In this quickstart, we generated 3D small molecule conformers from SMILES strings using the Auto3D module. We learned how to:

Create a client
Run the Auto3D module
Check the status of the job
Download the results

Checkout our other quickstarts to see how to use other modules. For example, now that we have some 3D small molecule conformers, we can run molecular dynamics simulation, quantum energy calculations, quantum geometry optimizations, docking, and much more!