Documentation | Examples | Colab guide | Paper
RGI-toolkit applies Restraint-Guided Inference (RGI) to diffusion-based
biomolecular structure predictors. Define geometric restraints on selected atoms
or atom groups, then optimize their coordinates during prediction with a shared
PyTorch or JAX engine.
At each active diffusion step, the predictor applies:
Denoising prediction → Restraint minimization → Coordinate update
Try RGI in Google Colab, or use one of the supported predictor integrations locally.
- Control distances, angles and dihedrals between selected atom groups.
- Restrain ligand geometry with bond, angle, chiral, cis/trans and VdW terms.
- Guide structures toward one or more PDB/mmCIF references with superposed RMSD restraints.
- Define custom differentiable energies as expressions over named atom selections.
- Combine restraint types, adjust weights and set activation windows during denoising.
- Use the same configuration and atom-selection syntax across PyTorch and JAX integrations.
The configuration reference describes each restraint type, its targets, penalties and defaults.
For local prediction, follow the installation guide for your
chosen predictor. Each integration installs rgi-toolkit
as a dependency and provides the model-specific inference command.
The shared engine requires Python 3.12 or later and a PyTorch or JAX backend;
model weights and GPU requirements are covered in each predictor's guide.
Clone this repository to use the example inputs or develop the shared engine:
git clone https://github.com/cddlab/rgi_toolkit.git
cd rgi_toolkitSee Development for the engine's development environment.
The following example uses Boltz-2 to guide QBP toward an interdomain centroid distance of 25 Å. Install the Boltz integration, activate its environment, and run from this repository's root on a GPU compute node:
boltz predict examples/distance/boltz-2/qbp_25.00.yaml \
--model boltz2 --use_msa_server --seed 0 \
--out_dir examples/distance/boltz-2/outThe input file contains both the protein sequence and its restraints_config.
The command fetches an MSA from the server and writes results under the selected
output directory.
The bundled examples cover five categories across eleven predictor integrations:
| Example | System | Restraint |
|---|---|---|
| Distance | QBP | Interdomain centroid distance of 25 Å |
| Angle | ADK | NMP–CORE–LID centroid angle of 72.85° |
| RMSD | QBP | RMSD targets of 2.65 Å to both open and closed references |
| Custom energy | DgoT | Difference between two domain distances of 0.8 Å |
| Ligand dissociation | MDM2–p53 | Chain-centroid distance of 30 Å |
Each category includes a run.sh for Boltz-2, Protenix v2, AlphaFold3, OpenFold-3,
Chai-1, ESMFold2, OpenDDE, RF3, BioEmu2, Mol-1 and IntelliFold v2. RF3 examples
are included here, such as the RF3 distance example.
See the example guide for predictor-specific environments,
MSA inputs, reference structures and run commands.
RGI is available in the upstream ColabFold notebooks. The forms support distance, conformer, angle, custom and RMSD restraints, including multiple restraints and native atom selections.
- Open a notebook below and choose an RGI-supported model.
- Enter your molecules in Input sequences.
- Enable use_rgi in the RGI form and fill in the restraints you need.
- Select Runtime → Run all.
| Notebook | Use case |
|---|---|
| ColabFold2 preview | Choose among the RGI-supported preview models |
| AlphaFold3 / OpenFold3 | AlphaFold3, OpenBind-0 and OpenFold3 |
| Boltz-1 | Native Boltz-1 inference |
Leave use_rgi off for vanilla prediction. See the Colab guide
for supported models, form examples, reference uploads and result downloads.
The backends below refer to the local predictor integrations.
| Model | Integration | Backend | Guide |
|---|---|---|---|
| Boltz-1 | boltz | PyTorch | Boltz-1 |
| Boltz-2 | boltz | PyTorch | Boltz-2 |
| AlphaFold3 | alphafold3 | JAX | AlphaFold3 |
| Protenix v1 | protenix | PyTorch | Protenix v1 |
| Protenix v2 | protenix | PyTorch | Protenix v2 |
| ESMFold2 | esmfold2 | PyTorch | ESMFold2 |
| OpenFold-3 | openfold-3 | PyTorch | OpenFold-3 |
| Chai-1 | chai-lab | PyTorch | Chai-1 |
| OpenDDE v1 | opendde | PyTorch | OpenDDE |
| RF3 | foundry | PyTorch | RF3 |
| BioEmu2 | bioemu2 | PyTorch | BioEmu2 |
| Mol-1 | mol1 | PyTorch | Mol-1 |
| IntelliFold v2 | intellifold | JAX | IntelliFold |
Each guide covers installation, input configuration and the prediction command.
The documentation index also summarizes where each predictor
accepts restraints_config.
For a protein chain A with at least 50 residues, this block targets a centroid distance of 25 Å between two residue groups:
restraints_config:
verbose: true
distance_restraints_config:
- atom_selection1: chain A and resid 1 to 10
atom_selection2: chain A and resid 40 to 50
harmonic:
target_distance: 25.0Place the block in your predictor's input as described in its integration guide. Residue selections use per-chain, 1-based ordinals; qualify them with a chain. The atom-selection guide covers atom names, residue ranges, molecule types and boolean expressions.
Use start_sigma and stop_sigma on each restraint entry, or on the shared
conformer block, to control its activation window. Conformer restraints also
require a per-ligand opt-in in the predictor's input. See the
configuration reference for penalty shapes, weights, reference
groups and custom expressions.
The default optimizer is nonlinear conjugate gradient with a strong-Wolfe line
search; Armijo and L-BFGS are also available. For PyTorch, gpu: false runs the
restraint optimizer on CPU. JAX uses its selected device. Optimizer settings and
convergence criteria are described in the
configuration reference.
Predictor integrations construct one CombinedRestraints instance per structure,
prepare its restraints, and call it after each denoising prediction:
from rgi_toolkit.combined import CombinedRestraints
restraints = CombinedRestraints()
restraints.setup(adapter, nbatch=multiplicity, config=restraints_config)
# Inside the predictor's denoising loop.
coords = restraints.minimize(coords, step, sigma)
# After sampling, emit optional per-term diagnostics.
restraints.finalize(coords, step)Here, adapter, multiplicity, coords, step and sigma come from the
predictor, and restraints_config is the configuration dictionary. JAX integrations
inside lax.scan use the pure closure returned by get_minimizer().
The selected predictor writes the predicted structures and confidence metrics.
With verbose: true, RGI logs the built restraint counts at setup and per-term
energies at finalization. Check the counts and selected atoms to confirm that the
requested restraints were applied.
Colab result archives include the effective input and restraint configuration;
the preview notebook also includes rgi_report.json. See the
Colab guide for details.
| Topic | Guide |
|---|---|
| Predictor setup and input formats | Integration guides |
| Restraints, atom selections and defaults | Configuration reference |
| Browser-based prediction | Colab notebooks |
| Example systems and run commands | Examples |
| Benchmark protocols and analysis | Benchmark guide |
| Common problems | FAQ |
Bundled skills live in .claude/skills/ and are shared with
Codex through .agents/skills/.
| Skill | Purpose |
|---|---|
| generate-rgi-config | Create and validate restraint configurations |
| implement-rgi | Add RGI to a predictor's sampling loop |
| sync-upstream | Update supported integration forks from upstream |
| create-github-release | Prepare version tags and GitHub releases |
Check the FAQ for common restraint and runtime issues, or open an issue with the predictor, configuration and relevant logs.
Prepare the engine's development environment from the repository root:
uv sync --extra torch --extra jax --extra notebooktask lint # Check style.
task format # Format and fix style.
task test-ci # Run the short CI selection.
task test-local # Run CPU regressions and real compilation checks.
task test-gpu # Run the complete GPU selection.
task test # Alias for test-local.Test tasks use an activated environment when present and otherwise use the project environment. Run GPU checks on a GPU compute node.
If you use RGI-toolkit, please cite:
Hori, T., Moriwaki, Y. & Ishitani, R. (2026). RGI-Toolkit: Differentiable Restraints for Controllable Biomolecular Structure Prediction. bioRxiv, preprint. doi:10.64898/2026.10.05.756905.
@article{hori2026rgi,
author = {Hori, Tatsuki and Moriwaki, Yoshitaka and Ishitani, Ryuichiro},
title = {{RGI-Toolkit}: Differentiable Restraints for Controllable Biomolecular Structure Prediction},
journal = {bioRxiv},
year = {2026},
doi = {10.64898/2026.10.05.756905},
url = {https://www.biorxiv.org/content/10.64898/2026.10.05.756905},
note = {Preprint}
}MIT License. Third-party notices are included in the license file.