rush-py: Rush Python Client

Installation

Install from PyPI:

pip install rush-py

If you manage dependencies with uv, add it to your project (updates pyproject.toml and uv.lock):

uv add rush-py

Using in Your Project

Add to your pyproject.toml:

[project]
dependencies = [
    "rush-py",
]

Rush Setup

Use environment variables to configure access:

• RUSH_TOKEN: Put your token's value here
• RUSH_PROJECT: Put your project's UUID value here; can find it in the URL once selecting a project in the Rush UI
• RUSH_ENDPOINT: Use this to choose between staging and prod; if omitted, defaults to prod

You can also put RUSH_TOKEN and RUSH_PROJECT in a .env file instead of exporting them in every terminal session. rush-py looks for a .env file in the current working directory first, then falls back to ~/.rush/.env. Environment variables always take priority over .env values.

# .env
RUSH_TOKEN=your-token-here
RUSH_PROJECT=your-project-id-here

Quick Start

from pathlib import Path

from rush import exess
from rush.client import collect_run

topology_path = Path.cwd() / "thrombin_1c_t.json"

# For energy, the only mandatory argument is the Topology
result = exess.energy(topology_path, collect=True)
exess.save_energy_outputs(result)

Outputs are saved under <workspace_dir>/<PROJECT_ID>/ (default: current working directory). To customize the workspace location, call rush.client.set_opts(workspace_dir=Path("...")).

# For interaction_energy, second argument is reference fragment
result = exess.interaction_energy(topology_path, 1, collect=True)

# Use export keywords to obtain additional information
result = exess.energy(
    topology_path,
    frag_keywords=None,  # MBE is not supported for CHELPG charges
    export_keywords=exess.ExportKeywords(export_chelpg_charges=True),
    collect=True,
)

# QMMM requires Residues too
md_topology_path = "./6a5j_t.json"
md_residues_path = "./6a5j_r.json"
# Without `collect=True`, the run takes place asynchronously, and a run ID is returned
id = exess.qmmm(
    md_topology_path,
    md_residues_path,
    n_timesteps=500,
    qm_fragments=[0],
    free_atoms=[0],
)
# The output for qmmm is a geometries json; can swap into a Topology's geometry field
result = collect_run(id)

# Get the full list of parameters and default arguments for a function
help(exess.energy)
help(exess.interaction_energy)
help(exess.qmmm)

See the docs for more information!

Development

You can develop this project using pip + venv, or uv.

With pip + venv

git clone git@github.com:talo/rush-py.git
cd rush-py
python -m venv .venv
source .venv/bin/activate
pip install -e .

With uv

git clone git@github.com:talo/rush-py.git
cd rush-py
uv sync
source .venv/bin/activate

See the Terms of Service for use of the underlying Rush software at https://qdx.co/terms.