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
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -215,3 +215,4 @@ __marimo__/
# User-supplied example alignments
/examples/**/*.a3m
/examples/**/*.aligned.pqt
/examples/ligand-dissociation/msas/
24 changes: 14 additions & 10 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,23 +58,23 @@ file-grouped workers, then all `cpu_compile` tests run with real compilation.
`task test-gpu` retains the complete GPU selection. Run the comprehensive local
suite before delivering code changes, and GPU checks when GPU behavior changes.
Compiler checks need Python development headers and a C++ compiler; a skip is
not evidence that compilation passed. See `docs/testing.md` for the coverage
split and environment setup. Markdown-only changes skip CI, and a newer run
cancels an older run for the same branch or pull request.
not evidence that compilation passed. Markdown-only changes skip CI, and a newer
run cancels an older run for the same branch or pull request.

## Architecture

**rgi_toolkit** — Restraint-Guided Inference (RGI): inject distance + ligand
conformer + RMSD restraints into a structure-prediction diffusion loop via gradient
optimization. Shared by **eight** integrations — boltz / protenix / chai-lab / openfold-3 /
esmfold2 / opendde / rf3 (torch) and alphafold3 (jax), covering 10 model variants (boltz1+boltz2 and
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
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 —
4 restraint types × 7 predictors, each with a `run.sh` — so reuse those fixtures instead of
authoring new ones.
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,
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 @@ -216,8 +216,12 @@ Design = **3 layers + autodiff + static shapes + GPU-complete optimization**:

- `_cuda_graph.py` records straight-line ATen regions and compiles them into native
CUDA IF/WHILE graphs. `_cuda_graph_ops.py` adapts the existing shared CG algorithm;
do not fork Strong Wolfe or Armijo formulas. `_cuda_lbfgs.py` follows PyTorch 2.8
do not fork Strong Wolfe or Armijo formulas. `_cuda_lbfgs.py` follows the installed PyTorch
L-BFGS, including its evaluation budget and first-iteration boundary cases.
PyTorch 2.13 bounds each line search by the remaining evaluation budget (2.8: 25);
`_torch_lbfgs.BOUNDED_LINE_SEARCH` applies the same bound to the graph and eager
CUDA paths. Native graph control is enabled only for PyTorch 2.8 and 2.13 with
CUDA >= 12.8; other releases (e.g. 2.12) use the ordinary optimizer.
- `_cuda_minimize.py` supports all restraint families, batches, gates, custom
closures, and mixed centroid maps within explicit memory/runtime limits. Complete
pair sums must preserve every chemistry/topology exclusion and every new trial
Expand Down Expand Up @@ -395,7 +399,7 @@ inert — to run AF3 restraints on CPU, run the whole process on the JAX CPU pla

#### Framework adapters

(`{boltz,protenix,chai,openfold3,esmfold2,opendde,rf3,alphafold3}/adapter.py` —
(`{boltz,protenix,chai,openfold3,esmfold2,opendde,rf3,bioemu2,alphafold3}/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 Down
14 changes: 5 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,7 @@ The backends below refer to the local predictor integrations.
| **Chai-1** | chai-lab | PyTorch | [Chai-1](docs/chai-lab_restr.md) |
| **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) |

Each guide covers installation, input configuration and the prediction command.
The [documentation index](docs/README.md) also summarizes where each predictor
Expand Down Expand Up @@ -147,9 +148,9 @@ 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. Solver behavior and
termination diagnostics are documented in the
[implementation specification](docs/SPEC.md#optimizers).
restraint optimizer on CPU. JAX uses its selected device. Optimizer settings and
convergence criteria are described in the
[configuration reference](docs/config.md#top-level-keys).

## Python API

Expand All @@ -172,8 +173,6 @@ 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()`.
See the [public API lifecycle](docs/SPEC.md#public-lifecycle) and
[adapter contracts](docs/SPEC.md#atom-and-array-contracts) for the complete interface.

## Output

Expand All @@ -194,10 +193,8 @@ the preview notebook also includes `rgi_report.json`. See the
| Restraints, atom selections and defaults | [Configuration reference](docs/config.md) |
| Browser-based prediction | [Colab notebooks](docs/colabfold.md) |
| Example systems and run commands | [Examples](examples/README.md) |
| API, energy definitions and optimizer contracts | [Implementation specification](docs/SPEC.md) |
| Benchmark protocols and analysis | [Benchmark guide](benchmark/README.md) |
| Common problems | [FAQ](docs/FAQ.md) |
| Test coverage and environment setup | [Testing](docs/testing.md) |

## Agent Skills

Expand Down Expand Up @@ -235,8 +232,7 @@ 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. See [Testing](docs/testing.md)
for coverage, compiler requirements and environment setup.
environment. Run GPU checks on a GPU compute node.

## Citation

Expand Down
3 changes: 1 addition & 2 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@
Use the tool-specific guide for installation, config placement, and the run command. Use the
shared [`restraints_config` reference](config.md) for restraint semantics and defaults. See the
[FAQ](FAQ.md) for common failure modes and troubleshooting guidance.
The [implementation specification](SPEC.md) describes the toolkit's API, mathematical
contracts, optimizer algorithms, and verification against independent implementations.

## Tool guides

Expand All @@ -21,6 +19,7 @@ Guides are available for the following predictor integrations.
| Chai-1 | PyTorch | Top-level sidecar YAML passed with `--restraints-config-path` | [Chai-1](chai-lab_restr.md) |
| 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) |

## Recommended workflow

Expand Down
Loading
Loading