Rustina

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

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

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.

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

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. License and model attribution are in 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 describes working in the repository. Agents have room to explore new methods, theories, and equations; docs/validation.md gives a starting protocol for assessing and reproducing their results.

Checks and navigation

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.