Metadata-Version: 2.1
Name: rush-py
Version: 3.2.1
Summary: Python SDK for interacting with the QDX Rush API and modules
Home-page: https://rush.qdx.co
Author: Ryan Swart
Author-email: ryan.swart@qdx.co
Requires-Python: >=3.9,<3.13
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: aiofiles (>=23.2.1,<24.0.0)
Requires-Dist: backoff (>=2.2.1,<3.0.0)
Requires-Dist: httpx (>=0.26.0,<0.27.0)
Requires-Dist: nest-asyncio (>=1.6.0,<2.0.0)
Requires-Dist: pdb-tools (>=2.5.0,<3.0.0)
Requires-Dist: pydantic (>=2.6.0,<3.0.0)
Requires-Dist: typing-extensions (>=4.9.0,<5.0.0)
Requires-Dist: websockets (>=12,<13)
Project-URL: Documentation, https://talo.github.io/rush-py
Description-Content-Type: text/markdown

# rush-py


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

# 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](https://talo.github.io/rush-py/comprehensive_guide.html).

# Install

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

``` bash
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:

``` python
import rush

client = rush.build_blocking_provider_with_functions(
    access_token=PUT_YOUR_TOKEN_HERE
)

# 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"],
    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 15:13:32,737 - rush - INFO - Not restoring by default via env
    {'26f07d72-bb16-4eb8-b23c-b620e5dd8182': (<ModuleInstanceStatus.RESOLVING: 'RESOLVING'>, 'auto3d', 1)}
    2024-05-13 15:13:35,962 - rush - INFO - Argument 0cd8539e-950b-41eb-b323-851560397cb1 is now ModuleInstanceStatus.RESOLVING
    2024-05-13 15:13:37,212 - rush - INFO - Argument 0cd8539e-950b-41eb-b323-851560397cb1 is now ModuleInstanceStatus.ADMITTED
    2024-05-13 15:13:49,235 - rush - INFO - Argument 0cd8539e-950b-41eb-b323-851560397cb1 is now ModuleInstanceStatus.DISPATCHED
    2024-05-13 15:13:55,206 - rush - INFO - Argument 0cd8539e-950b-41eb-b323-851560397cb1 is now ModuleInstanceStatus.RUNNING
    2024-05-13 15:14:28,548 - rush - INFO - Argument 0cd8539e-950b-41eb-b323-851560397cb1 is now ModuleInstanceStatus.AWAITING_UPLOAD
    objects/8f0e078f-4920-426d-8e50-6f541ea795eb
    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:

``` python
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:

``` python
client = rush.build_blocking_provider_with_functions(
    access_token=PUT_YOUR_TOKEN_HERE
)
```

    2024-05-13 15:14:56,959 - rush - INFO - Not restoring by default via env

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:

``` python
# 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:

``` python
# 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,
)
```

    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:

``` python
# 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"],
    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:

``` python
# 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:

``` python
# 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:

1.  Create a client
2.  Run the Auto3D module
3.  Check the status of the job
4.  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!

