Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 15 additions & 6 deletions .claude/skills/implement-rgi/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,7 @@ description: >-
Integrate Restraint-Guided Inference (RGI) into a diffusion-based structure
predictor using rgi_toolkit. Use when adding or porting guided sampling,
distance, group-angle, group-dihedral, ligand-conformer, VdW, RMSD, or custom
restraints to boltz, protenix, OpenDDE, chai-lab, openfold-3, esmfold2, AlphaFold3, or
a similar sampler. Implement only the framework adapter, sampling-loop hooks,
restraints to a structure predictor. Implement only the framework adapter, sampling-loop hooks,
and restraints_config pass-through; do not duplicate energy, optimization,
config, or selection logic in the tool.
---
Expand Down Expand Up @@ -66,7 +65,7 @@ tools drift out of parity. If you find yourself writing a restraint dataclass,
an energy term, or an atom-selection parser in the tool, stop and use the
rgi_toolkit one instead.

## Implementation — 3 steps
## Implementation

### Step 1 — Install (the backend is inferred, not configured)

Expand All @@ -89,7 +88,7 @@ mechanism when available. It is a deliberate placement choice, and both options
identically at runtime because the rgi_toolkit adapter protocol is duck-typed (no base
class, no registration):

- **In rgi_toolkit** (`rgi_toolkit/<tool>/adapter.py`) — the convention all seven existing tools
- **In rgi_toolkit** (`rgi_toolkit/<tool>/adapter.py`) — the convention all eleven existing integrations
follow; centralizes parity-critical code in one repo (one place to review the `resid`
convention / a protocol tweak). Needs the adapter to be framework-free (plain dict/array
in), so any irreducibly framework-coupled step (CCD/SMILES mol resolution, atom-name
Expand Down Expand Up @@ -168,7 +167,8 @@ reference for "how small this should be."

## Framework selection

- **PyTorch (eager loop)** — boltz, protenix, OpenDDE, chai-lab, openfold-3, esmfold2. The
- **PyTorch (eager loop)** — boltz, protenix, OpenDDE, chai-lab, openfold-3, esmfold2,
RF3, BioEmu2, and Mol-1. The
adapter lives in `rgi_toolkit/<tool>/adapter.py` (it receives a plain dict/array and
imports no framework code — **except boltz**, whose feats arrive as native torch
tensors so its adapter imports torch, read at batch 0). Call `minimize` each step.
Expand All @@ -177,12 +177,21 @@ reference for "how small this should be."
(openfold-3 → take geometry from the reference-conformer feature), or real coords
but no bonds (chai → perceive connectivity), or an over-broad ligand flag (use the
entity type, not biotite `hetero`). See pitfalls 10–12.
- **JAX (JIT / lax.scan)** — alphafold3. The framework-free adapter ALSO lives in
- **JAX (JIT / lax.scan)** — AlphaFold3 and IntelliFold v2. The framework-free adapter ALSO lives in
rgi_toolkit (`rgi_toolkit/alphafold3/adapter.py`), like the torch tools; only a thin
**in-tool shim** (`alphafold3_restr/.../restraints/adapter.py` `build_af3_adapter`)
does the one alphafold3-coupled step — resolve each ligand's CCD/SMILES RDKit mol +
read `fold_input` — then constructs the rgi_toolkit adapter from plain data. Build the
spec outside the scan; inject the pure `get_minimizer()` closure inside.
IntelliFold follows the same split through `intellifold.rgi.build_restraints`
and `rgi_toolkit/intellifold/adapter.py`.

These are eleven integrations; Boltz-1/Boltz-2 and Protenix v1/v2 share adapters.
ESMFold2's sampling hook lives in `esm_restr/esm/models/esmfold2/layers.py`.
`processor.py` builds the restraint state; `model.py` and `experimental.py`
forward it to the sampler in the same directory.
The integration no longer requires `transformers_restr` or copying hooks into
an installed `transformers` package.

Details, code, and the non-obvious traps (torch `inference_mode`, jax line
search collapsing atoms, coordinate reshape) are in
Expand Down
14 changes: 10 additions & 4 deletions .claude/skills/implement-rgi/references/adapter-protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,16 +45,16 @@ spells out the trade-off and requires a structured question when the client supp
one): in rgi_toolkit (the convention below) or in the tool's own codebase (rgi_toolkit left
unedited, the tool owns the adapter and may import its framework freely — at the cost of
having to track protocol drift). Both work — the protocol is duck-typed (no base class,
no registration). The existing seven all chose rgi_toolkit:
no registration). The existing eleven integrations all chose rgi_toolkit:

**All seven adapters live in `rgi_toolkit/<tool>/adapter.py`** — the project keeps them
**All eleven adapters live in `rgi_toolkit/<tool>/adapter.py`** — the project keeps them
together so a cross-tool invariant (the `resid` convention, a protocol tweak) is
reviewed in one place. They receive plain dict/array data and import no framework
code, EXCEPT boltz, whose feats arrive as native torch tensors so its adapter imports
torch (read at batch 0).

- **PyTorch tool**: drop the adapter straight into `rgi_toolkit/<tool>/adapter.py`.
- **JAX tool (AF3)**: the framework-free adapter ALSO lives in rgi_toolkit
- **JAX tools (AF3 and IntelliFold)**: the framework-free adapter ALSO lives in rgi_toolkit
(`rgi_toolkit/alphafold3/adapter.py`). Only the irreducibly framework-coupled step —
resolving each ligand's CCD/SMILES RDKit mol and reading `fold_input` — stays in a
thin **in-tool shim** (`alphafold3_restr/.../restraints/adapter.py`
Expand All @@ -63,6 +63,8 @@ torch (read at batch 0).
mapping, atom-name decode, leaving-atom subset, `iter_atoms` / `iter_ligand_confs`)
is the framework-free rgi_toolkit adapter. The split keeps the dependency direction
clean (rgi_toolkit imports no alphafold3) while still centralizing the adapter logic.
IntelliFold uses `intellifold.rgi.build_restraints` for this shim and
`rgi_toolkit/intellifold/adapter.py` for its adapter.

## Worked example 1 — boltz (reads a feats dict, batch 0)

Expand Down Expand Up @@ -143,14 +145,18 @@ is rgi_toolkit.

## Full source

The seven complete adapters are the ground truth:
The eleven adapters are the ground truth:
- `RGI-toolkit/src/rgi_toolkit/boltz/adapter.py` — feats dict + exposed `ligand_mols`
- `RGI-toolkit/src/rgi_toolkit/protenix/adapter.py` — biotite AtomArray (real bonds + coords)
- `RGI-toolkit/src/rgi_toolkit/chai/adapter.py` — reference conformer; prefers the source SMILES (`_mol_from_smiles`, real bond orders), falling back to `build_ligand_mol(perceive_bonds=True)` when none is supplied
- `RGI-toolkit/src/rgi_toolkit/openfold3/adapter.py` — AtomArray with zeroed coords → geometry from `ref_pos`; ligand by `molecule_type_id`
- `RGI-toolkit/src/rgi_toolkit/esmfold2/adapter.py` — one token/atom; intra-ligand bonds + orders from `token_bonds` / `ligand_bond_orders` (CCD or SMILES)
- `RGI-toolkit/src/rgi_toolkit/alphafold3/adapter.py` — framework-free (JAX), fed by the in-tool shim `<af3>/src/alphafold3/model/restraints/adapter.py` (`build_af3_adapter` = CCD/SMILES mol resolution + `fold_input` read)
- `RGI-toolkit/src/rgi_toolkit/opendde/adapter.py` — OpenDDE AtomArray metadata + pre-expansion token mapping + `ref_pos`; ligand identity from `mol_type`
- `RGI-toolkit/src/rgi_toolkit/rf3/adapter.py` — AtomArray metadata, final atom-to-token mapping, reference positions, and source ligand chemistry
- `RGI-toolkit/src/rgi_toolkit/bioemu2/adapter.py` — topology and reference coordinates supplied by the BioEmu2 shim
- `RGI-toolkit/src/rgi_toolkit/mol1/adapter.py` — shared Protenix chemistry with Mol-1's per-chain atom-to-token mapping
- `RGI-toolkit/src/rgi_toolkit/intellifold/adapter.py` — shared AF3 layout with CCD/SMILES molecules supplied by `intellifold.rgi.build_restraints`

The chai and openfold3 adapters are worth reading specifically for the "tool exposes
an incomplete ligand picture" cases (pitfalls 10–12).
14 changes: 12 additions & 2 deletions .claude/skills/implement-rgi/references/framework-notes.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
# Framework notes

## PyTorch (eager loop) — boltz, protenix, OpenDDE, chai-lab, openfold-3, esmfold2
## PyTorch (eager loop)

Boltz, Protenix, OpenDDE, Chai-1, OpenFold-3, ESMFold2, RF3, BioEmu2, and Mol-1
use the PyTorch path.

- **autograd under `inference_mode`**: predict loops often run inside
`torch.inference_mode()`, where autograd backward fails with "element does not
Expand All @@ -17,13 +20,20 @@
(a per-step radius search). `mode` defaults to **`both`** (run them together); both now run
on **torch AND jax**, so a JAX tool gets the full VdW too.

## JAX (JIT / `lax.scan`) — AlphaFold3
ESMFold2's native implementation is under `esm_restr/esm/models/esmfold2/`:
`processor.py` builds the restraint state, `model.py` and `experimental.py`
forward it, and `layers.py` applies the sampling hook. The old `transformers_restr` model
implementation and installed-package copy workaround are no longer needed.

## JAX (JIT / `lax.scan`) — AlphaFold3 and IntelliFold v2

- **adapter placement**: the framework-free adapter lives in rgi_toolkit
(`rgi_toolkit/alphafold3/adapter.py`), like the torch tools; only a thin in-tool shim
(`alphafold3_restr/.../restraints/adapter.py` `build_af3_adapter`) does the one
alphafold3-coupled step — CCD/SMILES mol resolution + `fold_input` read — and feeds
the rgi_toolkit adapter plain data.
IntelliFold uses the same arrangement through `intellifold.rgi.build_restraints`
and `rgi_toolkit/intellifold/adapter.py`.
- **no Python callbacks in the scan**: build the spec outside the scan (numpy, at
build time) and inject `get_minimizer()`'s pure closure inside. Never call the
Python `minimize` per step in a compiled loop.
Expand Down
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -216,3 +216,7 @@ __marimo__/
/examples/**/*.a3m
/examples/**/*.aligned.pqt
/examples/ligand-dissociation/msas/

# Generated predictor inputs after MSA and template preprocessing
/examples/**/*-update-msa.json
/examples/**/*-final-updated.json
26 changes: 16 additions & 10 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,15 +65,16 @@ run cancels an older run for the same branch or pull request.

**rgi_toolkit** — Restraint-Guided Inference (RGI): inject distance + ligand
conformer + RMSD restraints into a structure-prediction diffusion loop via gradient
optimization. Shared by **nine** integrations — boltz / protenix / chai-lab / openfold-3 /
esmfold2 / opendde / rf3 / bioemu2 (torch) and alphafold3 (jax), covering 11 model variants (boltz1+boltz2 and
optimization. Shared by **eleven** integrations — boltz / protenix / chai-lab / openfold-3 /
esmfold2 / opendde / rf3 / bioemu2 / mol1 (torch) and alphafold3 / intellifold (jax),
covering 13 model variants (boltz1+boltz2 and
protenix v1+v2 each share one adapter). The end-to-end guide for integrating a new tool is the
`implement-rgi` skill, shared from `.claude/skills/` to `.agents/skills/` (alongside
`generate-rgi-config` for authoring a config, `sync-upstream`, `create-github-release`).
Per-tool as-built integration write-ups live in `docs/<tool>.md` (one per tool); the shared
config + selection-DSL surface is `docs/config.md`. `examples/` holds ready-to-run samples
organized by restraint type and predictor:
distance, angle, RMSD, custom, and MDM2-p53 ligand dissociation for nine predictors,
distance, angle, RMSD, custom, and MDM2-p53 ligand dissociation for eleven predictors,
each with a `run.sh`. Reuse those fixtures instead of authoring new ones.

Design = **3 layers + autodiff + static shapes + GPU-complete optimization**:
Expand Down Expand Up @@ -379,7 +380,7 @@ prior spec/optimizer up front so a reused instance is safe) →
`minimize(coords, step, sigma)` → `finalize(coords, step)`. Always construct a fresh
instance per structure (the old `get_instance()`/`reset()` singleton shim was removed). The
backend is **inferred from invocation, NOT a config key**: `get_minimizer()` →
jax (only AF3 calls it); `minimize(coords)` → jax if `coords` is a jax array, else
jax (used by AF3 and IntelliFold); `minimize(coords)` → jax if `coords` is a jax array, else
torch (numpy/torch coords both take the torch path). Resolution is lazy — `setup`
leaves `self._backend = None` and builds the optimizer on the first
`minimize`/`get_minimizer` (`_ensure_backend` raises if one instance is invoked under
Expand All @@ -394,12 +395,12 @@ when `gpu:true`), NOT the backend, so `gpu:false` runs the torch optimizer on CP
(moving GPU coords to CPU and back). There is no numpy optimizer (numpy is the energy
reference only); a leftover `backend:` config key raises with a migration hint.
torch/jax imported lazily. JAX tools inside `lax.scan` grab the pure minimizer via
`get_minimizer()` instead of calling `minimize` per step (so for AF3 the `gpu` flag is
inert — to run AF3 restraints on CPU, run the whole process on the JAX CPU platform).
`get_minimizer()` instead of calling `minimize` per step. The `gpu` flag is inert
for AF3 and IntelliFold; run the whole process on the JAX CPU platform to use CPU.

#### Framework adapters

(`{boltz,protenix,chai,openfold3,esmfold2,opendde,rf3,bioemu2,alphafold3}/adapter.py` —
(`{boltz,protenix,chai,openfold3,esmfold2,opendde,rf3,bioemu2,mol1,alphafold3,intellifold}/adapter.py` —
framework-free EXCEPT boltz, whose feats arrive as native torch tensors so its adapter
imports torch (read at batch 0); the others import no framework. AF3's CCD/SMILES mol
resolution lives in a thin in-tool shim
Expand All @@ -408,10 +409,15 @@ data): implement `iter_atoms()` (→
`AtomRecord(chain, resid, index)` for distance selection) and optionally
`num_atoms()`, `get_elements()`, `iter_ligand_confs()` (→
`LigandConf(mol, conf_coords, global_indices, stereo_mol=...)` for conformer + VdW;
`stereo_mol` is the optional source SMILES graph renumbered to coordinate order). The four tools whose
features arrive as a **biotite `AtomArray`** (protenix / openfold3 / opendde / rf3) share
`stereo_mol` is the optional source SMILES graph renumbered to coordinate order). The five tools whose
features arrive as a **biotite `AtomArray`** (protenix / openfold3 / opendde / rf3 / mol1) share
`_biotite_adapter.py` (`biotite_get_elements` / `biotite_ligand_confs`) rather than each
re-deriving elements + ligand conformers — extend that module, not the four call sites.
re-deriving elements + ligand conformers — extend that module, not the call sites.

Mol-1 reuses the Protenix adapter chemistry and derives per-chain residue ordinals
from its actual atom-to-token map. IntelliFold reuses the AF3 adapter and obtains
CCD/SMILES molecules from `intellifold.rgi.build_restraints`. Its JAX loop takes
the scan minimizer as a numeric pytree so targets remain dynamic across inputs.

RF3 receives the final atom-to-token map, reference positions and reference-space IDs
from the tool-side shim, which also normalizes AtomWorks entity types and resolves
Expand Down
11 changes: 8 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,18 +65,21 @@ The 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 four protocols across seven predictors:
The bundled examples cover five categories across eleven predictor integrations:

| Example | System | Restraint |
| --- | --- | --- |
| [Distance](examples/distance/) | QBP | Interdomain centroid distance of 25 Å |
| [Angle](examples/angle/) | ADK | NMP–CORE–LID centroid angle of 72.85° |
| [RMSD](examples/rmsd/) | QBP | RMSD targets of 2.65 Å to both open and closed references |
| [Custom energy](examples/custom/dist-diff/) | DgoT | Difference between two domain distances of 0.8 Å |
| [Ligand dissociation](examples/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](examples/distance/rf3/).
See the [example guide](examples/README.md) for predictor-specific environments,
MSA inputs, reference structures and run commands. RF3 examples are maintained in
the [Foundry integration](https://github.com/cddlab/foundry_restr/tree/rgi-integration/examples/rgi).
MSA inputs, reference structures and run commands.

## Google Colab

Expand Down Expand Up @@ -115,6 +118,8 @@ The backends below refer to the local predictor integrations.
| **OpenDDE v1** | opendde | PyTorch | [OpenDDE](docs/opendde_restr.md) |
| **RF3** | foundry | PyTorch | [RF3](docs/foundry_restr.md) |
| **BioEmu2** | bioemu2 | PyTorch | [BioEmu2](docs/bioemu2_restr.md) |
| **Mol-1** | mol1 | PyTorch | [Mol-1](docs/mol1_restr.md) |
| **IntelliFold v2** | intellifold | JAX | [IntelliFold](docs/intellifold_restr.md) |

Each guide covers installation, input configuration and the prediction command.
The [documentation index](docs/README.md) also summarizes where each predictor
Expand Down
4 changes: 3 additions & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ Guides are available for the following predictor integrations.
| OpenDDE v1 | PyTorch | `restraints_config` in each fold-input JSON object | [OpenDDE](opendde_restr.md) |
| RF3 (Foundry) | PyTorch | `restraints_config` in each input JSON job | [RF3](foundry_restr.md) |
| BioEmu2 | PyTorch | `restraints_config` in the system YAML or `System` | [BioEmu2](bioemu2_restr.md) |
| Mol-1 | PyTorch | `restraints_config` in each fold-input JSON object | [Mol-1](mol1_restr.md) |
| IntelliFold v2 | JAX | `restraints_config` in the fold-input JSON | [IntelliFold](intellifold_restr.md) |

## Recommended workflow

Expand All @@ -37,7 +39,7 @@ Guides are available for the following predictor integrations.
- Conformer terms require both `conformer_restraints_config` and a per-ligand opt-in. The opt-in
location differs by tool.
- The backend is inferred from the predictor. `gpu` selects the PyTorch device and is inert for
AlphaFold 3's JAX path.
AlphaFold 3 and IntelliFold's JAX paths.
- Config validation checks schema and selection syntax. Runtime `built spec:` counts confirm
which restraints were built; verify the selected atom identities separately against the input
structure to check that the selections match the intended atoms.
Loading
Loading