Metadata-Version: 2.3
Name: rush-py
Version: 7.0.0b2
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: numpy>=1.26,<3
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

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

# For energy, the only mandatory argument is the Topology
run = exess.energy(topology_path)

# Fetch the results for direct access
result = run.fetch()

# Save the results
paths = run.save()
```

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).fetch()

# 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)
).fetch()

# QMMM requires Residues too
topology_path = "./6a5j_t.json"
residues_path = "./6a5j_r.json"
# Without calling `.fetch()` or `.save()` the run takes place asynchronously
# and a run object is returned
run = exess.qmmm(
    topology_path=topology_path,
    residues_path=residues_path,
    n_timesteps=500,
    qm_fragments=[0],
)
# The output is a QMMMResult object that contains the geometries for each timestep,
# which can be swapped into a Topology's geometry field
result = run.fetch()

# Get the full list of parameters and default arguments for a function
help(exess.energy)
help(exess.interaction_energy)
help(exess.optimization)
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.
