Metadata-Version: 2.4
Name: rustina
Version: 0.7.2
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Dist: rdkit>=2024.3 ; extra == 'prep'
Requires-Dist: molscrub>=0.2.2 ; extra == 'prep'
Requires-Dist: meeko>=0.7.1,<0.8 ; python_full_version < '3.10' and extra == 'prep'
Requires-Dist: meeko>=0.7.1 ; python_full_version >= '3.10' and extra == 'prep'
Requires-Dist: scipy>=1.12.0 ; extra == 'prep'
Requires-Dist: gemmi>=0.6.0 ; extra == 'prep'
Requires-Dist: joblib ; extra == 'prep'
Requires-Dist: pandas ; extra == 'prep'
Provides-Extra: prep
License-File: LICENSE
Summary: CPU/GPU molecular docking with native GNINA-compatible CNN rescoring
Author: Adrien H. Cerdan
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/AdrienCerdan/rustina
Project-URL: Issues, https://github.com/AdrienCerdan/rustina/issues
Project-URL: Repository, https://github.com/AdrienCerdan/rustina

# Rustina

Linux x86-64 molecular docking in Rust, with a command-line interface and Python bindings.

| Search | Device |
| --- | --- |
| `vina` | CPU, Vina Monte Carlo/BFGS |
| `qvina2` | CPU, QuickVina2 search |
| `qvina2-race` (default) | CPU, staged QuickVina2 runs |
| `gpu` | GPU, batched Monte Carlo search through wgpu |

Every search mode supports `vina`, `vinardo`, and `ad4` scoring. Fast CNN rescoring is enabled by default; use `--skip-cnn` or `skip_cnn=True` for empirical scoring alone. GPU search requires a compatible compute adapter and reports an error when none is available.

## Build

```bash
cargo build --release --locked
python -m pip install maturin
maturin build --release --locked --out target/wheels
python -m pip install target/wheels/*.whl
```

The Python package supports Python 3.9+. Docking and scoring need no Python dependencies. Optional SMILES/SDF preparation uses `pip install 'rustina[prep]'`.

## Command line

Inputs are receptor and ligand PDBQT files. Prepare the receptor with polar hydrogens and partial charges; AD4 uses explicit polar hydrogens and charges for scoring.

```bash
target/release/rustina dock -r data/receptor.pdbqt -l data/ligand.pdbqt \
  --cx 0 --cy -5 --cz 0 --sx 12 --sy 16 --sz 12 \
  --search-mode qvina2-race --scoring vina --runs 32 --seed 42 \
  -o target/docked.pdbqt

target/release/rustina score -r data/receptor.pdbqt -l data/ligand.pdbqt \
  --scoring ad4 --cnn
```

Use `--search-mode gpu` for GPU search. `--batch DIRECTORY` docks a directory of ligands against one receptor. `dock --help` and `score --help` list the available options.

CPU search budgets are fixed by the selected mode; `--steps` and `--bfgs-iter` overrides apply to GPU search. `qvina2-race` requires at least 16 runs. A supplied seed makes CPU output reproducible across thread counts. GPU reproducibility also depends on the adapter and driver.

`pose_pool_size` caps the returned search pool in every mode; QuickVina keeps its internal 20-minimum search history. `direct_refine_candidates` limits direct receptor refinement on both CPU and GPU, with zero disabling it. GPU `bfgs_iter` sets both search and polish iteration limits; diagnostics report the actual depth and local iteration limits.

PDBQT coordinates and charges must be finite numbers, atom serials must be unique, and branch endpoints must define valid torsion axes. Multi-model input selects its first model for both parsing and redocking. Grid interpolation includes the upper faces and uses the derivative of the clamped value outside the box. AD4 maps retain distinct atom parameters; macrocycle glue pseudo-atoms contribute only to closure restraints, without affecting covalent typing or CNN densities and centers. These correctness fixes can change poses and scores relative to earlier builds.

Receptor waters can be retained (`--waters fixed`, default) or removed (`--waters strip`). Hydrated ligands containing pseudo-water `W` atoms are rejected.

## Python

```python
import rustina

poses = rustina.dock(
    "data/receptor.pdbqt", "data/ligand.pdbqt",
    cx=0, cy=-5, cz=0, sx=12, sy=16, sz=12,
    search_mode="qvina2-race", scoring="vinardo", runs=32, seed=42,
)
print(poses[0]["affinity"], poses[0]["cnn_score"])

scores = rustina.score("data/receptor.pdbqt", "data/ligand.pdbqt", scoring="ad4")
cnn = rustina.score_cnn("data/receptor.pdbqt", "data/ligand.pdbqt")
```

`screen(receptor, ligands, cx, cy, cz, sx, sy, sz, ...)` shares receptor grids across a batch and returns one result per ligand, in input order. Individual failures contain an `error` string. `prepare_ligand("CCO")` returns prepared PDBQT states when preparation extras are installed. Paths and PDBQT text are accepted by the docking and scoring APIs.

The bundled `fast` CNN is described in [docs/models.md](docs/models.md). License and model attribution are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

## Extending the core

`screening.rs` shares receptor preparation, docking, refinement, and pose ranking between the CLI and Python bindings. Search implementations live in `optimize.rs`, `qvina.rs`, and `gpu/`; empirical potentials live in `scoring.rs` and `ad4.rs`; `cnn.rs` handles fast CNN inference. Keeping new methods behind these shared boundaries makes them available to both interfaces. The retained tests check gradients, seeded results, atom typing, and CPU/GPU agreement.

[AGENTS.md](AGENTS.md) describes working in the repository. Agents have room to explore new methods, theories, and equations; [docs/validation.md](docs/validation.md) gives a starting protocol for assessing and reproducing their results.

## Checks and navigation

```bash
cargo fmt --all --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --all-targets --locked
```

Install the release wheel, then run `python -m unittest discover -s /absolute/path/to/rustina/python/tests -v` from outside the checkout. GPU tests exercise the available adapter; an absent adapter prints a skip message but is counted as passing by the Rust harness. Hardware validation requires checking that the tests actually ran on a real GPU.

Tagged releases publish one Linux x86-64 Python wheel and a CLI archive. Both are built in manylinux 2.28 and tested as installed/unpacked packages before publishing; source is available through the Git tag.

Graphify is optional navigation tooling. `scripts/setup_graphify.sh` installs it under `target/graphify`; `scripts/graphify update . --force` rebuilds the code graph under `scratch/graphify/graphify-out`. `scripts/graphify query "GPU search and scoring" --budget 1500` explores it. Generated graphs and build products are ignored by Git.

