Metadata-Version: 2.3
Name: rush-py
Version: 6.7.0
Summary: Python client for QDX's Rush platform
Keywords: computational-chemistry,quantum-chemistry,HPC,molecular-modeling,protein-folding,EXESS,NN-xTB,PBSA
Author: Sean Laguna
Author-email: Sean Laguna <seanlaguna@qdx.co>
License: Apache-2.0
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: System :: Distributed Computing
Requires-Dist: gql~=4.0
Requires-Dist: h5py~=3.14
Requires-Dist: rdkit~=2025.9.2
Requires-Dist: matplotlib~=3.10
Requires-Dist: networkx~=3.6
Requires-Dist: requests~=2.32
Requires-Dist: requests-toolbelt~=1.0
Requires-Dist: zstandard~=0.23
Requires-Python: >=3.12
Project-URL: Homepage, https://rush.cloud
Project-URL: Documentation, https://talo.github.io/rush-py
Project-URL: Source, https://github.com/talo/rush-py
Project-URL: Issues, https://github.com/talo/rush-py/issues
Description-Content-Type: text/markdown

# rush-py: Rush Python Client

## Installation

Install from PyPI:
```bash
pip install rush-py
```

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

### Using in Your Project

Add to your `pyproject.toml`:
```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

```python
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("..."))`.

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

# For chelpg, charges are extracted from the HDF5 output and returned as a list
output_info, charges = exess.chelpg(topology_path, 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.chelpg)
help(exess.qmmm)
```

See the [docs](https://talo.github.io/rush-py) for more information!

## Development

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

### With `pip` + `venv`
```bash
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`
```bash
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.
