Skip to content

01 Getting Started

Jump to bottom
Sean L edited this page Jan 2, 2026 · 7 revisions

Rush-Py Design and Usage

Getting Access

First, if you don't have a Rush account, go create one on the Rush platform's website!

Rush Token

Once you've created your account and logged in, click the "Account" tab in the left sidebar and create or obtain your API token on the accounts page. This is your "Rush Token", and will let you authenticate your access to Rush from your rush-py scripts.

Rush Projects

You'll also need to create a project and obtain its ID. From the projects page (which is also the landing page after logging in), create a project using the "New Project" button. Enter a name for your project and click "Continue". You will now be taken to a page with a URL of the following structure: https://rush.cloud/project/{PROJECT_ID}/workspace/{WORKSPACE_ID}. This project's ID is the value at the part of the URL referenced by the {PROJECT_ID} place-holder above. Each run you do in Rush is associated with a project and will appear as part of that project when you view that project in the web interface, and runs done through rush-py are no different.

Install rush-py

Install rush-py using pip install rush-py. Note that versions prior to 6.0 have a very different design that isn't covered by these docs, so make sure you're on at least that major version!

It's also possible to install using uv, pdm, poetry, or any other tool of your choice in the expected way as it is available on PyPI.

Authenticating and Setting a Project

Use environment variables to configure access:

  • RUSH_TOKEN: Put your authentication token's value here.
  • RUSH_PROJECT: Put your project's ID here.

There's one more environment variable, which would only need to be used if requested by a QDX employee:

  • RUSH_ENDPOINT: Use this to choose which Rush server to use; if omitted, defaults to our production server at https://rush.cloud. To use a different server, you'll need to be given access to it explicitly.

Doing Your First Rush-Py Run

Background Info: Rush Modules

Rush consists of modules, which are individual programs or entrypoints for tools available on the platform. Rush-py provides one primary function for each module that allows you to call it, and it supports a complete set of inputs and outputs for each module (in most cases). In some cases, this gives you more flexiblity than the Rush web interface. The rush-py interface strives to stay as faithful as possible to the module's underlying capabilities and give you direct and transparent access to it.

Import and Call a Module

Each Rush module has a Python submodule that provides support for it. For example, import files and functions from rush_py2.exess to use functions and supporting infrastructure for the EXESS module:

from rush_py2 import exess

You can then access the function that directly wraps EXESS as expected:

from rush_py2 import exess
exess.exess("input_topology.json", collect=True)

Or the possibly more clear:

from rush_py2.exess import exess as run_exess
run_exess("input_topology.json", collect=True)

And you're done! The EXESS module has a rich set of capabilities and configuration, but by default will perform an energy calculation on the input topology molecule. To learn about QDX Topology files, check the relevant section of the wiki. TODO: Insert link here.

You can use the topolgy file for a small protein from the 1KUW structure on the PDB as the input, or for very quick runs, our topology files for benzene or ethane.

Asynchronous Runs and Collecting Runs

Rush modules can take a long time, so by default run asynchronously: the function that triggers the run will return once the run is submitted. In order to obtain the output synchronously for this same call, pass collect=True as we've done above. You can also collect the run later:

from rush_py2.client import collect_run
from rush_py2.exess import exess as run_exess
id = run_exess("input_topology.json", collect=True)
collect_run(id)

As shown, module calls return a "run ID" that can be used as above to collect any run that you've submitted.

Supplementary Entrypoints

Or, call one of the other supplementary EXESS entrypoints, built to facilitate easily use EXESS's various capabilities:

from rush_py2 import exess
exess.energy(...)
exess.interaction_energy(...)
exess.chelpg(...)
exess.optimization(...)
exess.qmmm(...)

View your run in the Rush Web Interface

On the project page in the Rush web interface, your runs will appear on the left sidebar. To get more info, you can also go to https://rush.cloud/projects/{PROJECT_ID}/runs (after replacing the {PROJECT_ID} placeholder in the URL with your actual project ID) and click on any run to get debug-level information about the run.

Clone this wiki locally