diff --git a/.gitignore b/.gitignore index 49efa1b..5b6f3f1 100644 --- a/.gitignore +++ b/.gitignore @@ -215,3 +215,4 @@ __marimo__/ # User-supplied example alignments /examples/**/*.a3m /examples/**/*.aligned.pqt +/examples/ligand-dissociation/msas/ diff --git a/AGENTS.md b/AGENTS.md index f02fbc4..0a9514d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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/.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**: @@ -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 @@ -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 diff --git a/README.md b/README.md index 72a1ae3..56dc969 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 diff --git a/docs/README.md b/docs/README.md index 63eb088..64a85d3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 @@ -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 diff --git a/docs/SPEC.md b/docs/SPEC.md deleted file mode 100644 index 4be5448..0000000 --- a/docs/SPEC.md +++ /dev/null @@ -1,564 +0,0 @@ -# RGI-toolkit implementation specification - -This document describes implementation contracts and verification for the -restraint types covered in the RGI-Toolkit paper. -The [configuration reference](config.md) defines accepted keys, defaults, selection -syntax, and complete examples. The [predictor guides](README.md) describe where each -host invokes RGI; the maintained [example workflows](../examples/README.md) are the -starting point for predictor runs. Pytest exercises the shared toolkit without -predictor weights; full predictor checks use those examples and exported structures. - -## Scope and architecture - -RGI corrects coordinates during a predictor's denoising loop by minimizing a scalar -restraint objective. It does not implement the predictor, a physical dynamics -integrator, or a calibrated thermodynamic energy. Weights combine quantities with -different units; reducing this objective alone does not establish structural validity. - -| Layer | Responsibility | Source | -| --- | --- | --- | -| Input and adapters | Validate config, expose atom metadata, resolve selections and reference correspondences | [`config.py`](../src/rgi_toolkit/config.py), [`atom_context.py`](../src/rgi_toolkit/atom_context.py), [`selection.py`](../src/rgi_toolkit/selection.py) | -| Specification | Derive targets and pack masked NumPy arrays with local atom indices | [`featurizer.py`](../src/rgi_toolkit/featurizer.py), [`spec.py`](../src/rgi_toolkit/spec.py) | -| Energy | Evaluate shared geometry, penalties, and activation masks through a backend facade | [`_geometry.py`](../src/rgi_toolkit/_geometry.py), [`energy/_kernels.py`](../src/rgi_toolkit/energy/_kernels.py), [`energy/_runtime.py`](../src/rgi_toolkit/energy/_runtime.py) | -| Optimization | Gather active coordinates, differentiate, minimize, and scatter the correction | [`optim/torch_optim.py`](../src/rgi_toolkit/optim/torch_optim.py), [`optim/jax_optim.py`](../src/rgi_toolkit/optim/jax_optim.py) | - -The array kernels are implemented once against `_array_ops.py`. NumPy, Torch, and -JAX energy modules are thin adapters. The `TermDef` registry in -[`energy/_terms.py`](../src/rgi_toolkit/energy/_terms.py) drives packing, dispatch, -gating, and energy breakdown of array terms. Custom and reference-dependent -closures and dynamic VdW complete the objective outside that array registry. -NumPy supplies an energy reference; optimization requires Torch or JAX. SciPy is -a development dependency used by tests, not a runtime optimizer. - -## Public lifecycle - -Construct one `CombinedRestraints` per structure. The preferred sequence is: - -```python -restraints = CombinedRestraints() -restraints.setup(adapter, nbatch=nbatch, config=restraints_config) -coords = restraints.minimize(coords, istep=step, sigma=sigma) -restraints.finalize(coords, istep=step) -``` - -`set_config(dict)` provides adapter-independent parsing and validation; -the two-call `set_config` then `setup` form is the deprecated equivalent of -`setup(config=...)`. - -`setup` clears the previous derived spec and optimizer before resolving the new -input. A successful setup leaves backend selection lazy. `is_active()` reports -whether the constructed spec has work; empty configurations leave coordinates -unchanged. `nbatch` is accepted for host compatibility; coordinate arrays determine -the actual batch shape. - -| Invocation | Backend and result | -| --- | --- | -| `minimize(torch_tensor, istep, sigma)` | Torch; updates and returns the same tensor | -| `minimize(numpy_array, istep, sigma)` | CPU Torch in float64; writes back to a writable floating array, otherwise returns the resulting array | -| `minimize(jax_array, istep, sigma)` | JAX; requires an explicit sigma and returns a new array | -| `get_minimizer()` | Selects JAX and returns pure `(coords, sigma, step) -> coords`, or `None` for an inactive spec; suitable for `jit` and `lax.scan` | - -One instance cannot switch backend after selection; a conflicting invocation -raises. `gpu: false` moves a Torch accelerator input to CPU for the correction and -copies it back. `gpu: true` uses the Torch input's device. This setting does not -select a backend or move a JAX computation. Half-precision Torch coordinates are -optimized in float32 and cast back; float32/float64 retain their working dtype. -Torch explicitly enables autograd for this correction inside host inference mode. -This API is a coordinate correction, not a promise of differentiation through the -optimizer into the predictor. - -For CG, opt in to termination diagnostics without changing coordinate semantics: - -```python -from rgi_toolkit import CGStatus - -coords, info = restraints.minimize(coords, sigma=sigma, return_info=True) -converged = info.status == CGStatus.CONVERGED -# A JAX factory fixes its output structure at construction, including inside scan. -minimize_with_info = jax_restraints.get_minimizer(return_info=True) -``` - -The two calls illustrate separate Torch/NumPy and JAX instances, respectively; -one instance still cannot switch backends. `CGInfo` is a framework-independent -named tuple and a native JAX pytree. Its scalar fields are `status`, `nit` -(accepted iterations), `nfev`, `njev`, `fun`, and `grad_norm` (infinity norm of the -gradient in the optimizer's coordinates, including the affine map below). One -record covers the **entire batch** and invocation. JAX returns traced scalar arrays; -decode the integer status on the host or compare it within JAX control flow. - -| `CGStatus` | Meaning | -| --- | --- | -| `INACTIVE` (0) | No active restraint window; no evaluations, with zero counters/value/norm | -| `CONVERGED` (1) | Initial or accepted gradient meets `gtol` | -| `MAX_ITER` (2) | The iteration budget ended before gradient convergence | -| `LINE_SEARCH_FAILED` (3) | No acceptable step for the configured line search within its budget | -| `NONFINITE` (4) | A nonfinite initial evaluation or the final failed search trial/slope | -| `NO_PROGRESS` (5) | The final failed trial cannot change representable coordinates | -| `FUNCTION_TOLERANCE` (6) | Armijo only: accepted relative energy change is below `1e-9`; the gradient has not converged | - -Failure diagnostics describe the last accepted point, or the initial evaluation -when none was accepted. Rejected trial calls still count. An initially nonfinite -value/norm remains nonfinite in the report. Empty specs retain `get_minimizer() is -None`, including with the flag; direct `minimize` reports `INACTIVE`. Re-setup -clears both JAX factories. Requesting diagnostics with L-BFGS raises `ValueError`; -its existing coordinate-only behavior is unchanged. - -`finalize` is an optional verbose diagnostic, not another minimization. It reports -ungated energies at the supplied coordinates, including custom terms and static -and dynamic VdW, without moving atoms. Its failures are reported as warnings and -do not abort inference. A zero final energy can mean a satisfied restraint; verify -construction with the setup counts. A Torch/NumPy diagnostic with dynamic VdW can -construct the optimizer and select Torch before the first `minimize`; the JAX -diagnostic evaluates directly without locking an unused instance to JAX. - -## Atom and array contracts - -The minimal adapter implements `iter_atoms()` over non-padding `AtomRecord`s. -`index` is the zero-based row in the predictor's flattened, possibly padded atom -axis. `resid` is a one-based ordinal within each chain, not an author residue -number. Atom names, normalized molecule types, residue names, and per-chain -ligand conformer opt-ins support atom selection and reference matching. - -Conformer adapters additionally expose the padded atom count, atomic numbers -(`0` for padding), and ligand reference conformers. -Each `LigandConf` maps RDKit atom order to coordinates through `global_indices`; -different molecules must have disjoint global indices. Source chemistry retains -formal charges, hydrogen counts, isotopes, and stereochemistry when a coordinate -graph is reconstructed. A coordinate-free `stereo_mol` may supply that source graph. -Biotite integrations share `_biotite_adapter.py`; framework-specific -adapters translate features rather than implementing restraint energies. - -Runtime coordinates have shape `(..., N, 3)` in Angstrom. `active_sites` stores -global rows participating in restraints. Array-term indices address this gathered -subset, so local row `i` means global row `active_sites[i]`. Noncontiguous global -rows and independent batch members are valid. All batch energies are summed into -one scalar, so solvers can share line-search decisions across a batch even though -the objective contains no cross-sample contacts. - -Restraint rows and variable-size atom groups are padded with explicit masks. The -prepared shapes remain static during minimization; padding must contribute no -energy or gradient. Reference atoms are constants, not additional prediction rows. -Atoms outside `active_sites` are unchanged. `move` controls one term's gradient: -an atom pinned by one term can still move under another term. - -Torch's prepared arrays, gate cache, custom closures, and compiled artifacts are -keyed by both device and dtype. Per-entry gate decisions use the host NumPy spec -arrays, avoiding a device-to-host read per restraint category at each diffusion -step. - -## Objective and units - -The objective sums all enabled terms and batch members; there is no common `1/2` -factor or normalization by the total number of restraints. For the four shared -penalty shapes, `E = weight * delta**2`: - -| Shape | Residual for measured value `q` | -| --- | --- | -| `harmonic` | `q - target` | -| `flat-bottomed` | `q - clip(q, lower, upper)` | -| `flat-bottomed1` | `min(q - lower, 0)` | -| `flat-bottomed2` | `max(q - upper, 0)` | - -Conformer slack instead removes a symmetric interval from a target deviation: -`delta = sign(q - target) * max(abs(q - target) - slack, 0)`. -Numerical norm floors, angular clipping, -and a small RMS regularizer keep geometry finite near singular configurations; -the exact constants and branch rules live in `_geometry.py` and `_kernels.py`. - -| Array term | Measured quantity and target | Units and penalty | Gate | -| --- | --- | --- | --- | -| `bond` | Interatomic length; reference conformer length | Angstrom; symmetric slack | Shared conformer | -| `angle` | Three-atom angle; reference conformer angle | Radians internally; symmetric slack with the linear-target branch below | Shared conformer | -| `chiral` | Signed scalar triple product about the first atom; reference target | Angstrom cubed; no division by six; symmetric slack | Shared conformer | -| `cistrans` | Ligand acyclic double-bond E/Z; reference target, period 1 | Radians; `wrap(phi - target)`, then symmetric slack | Shared conformer | -| `vdw` | Pair distance relative to the elemental radius sum | Angstrom; repulsive overlap | Shared conformer | -| `distance` | Distance between two geometric centroids; user target/bounds | Angstrom; four shared shapes | Per entry | -| `rmsd` | Proper-rotation Kabsch fit followed by RMS measurement; reference structure and user target/bounds | Angstrom; four shared shapes | Per entry | -| `group_angle` | Three centroids, vertex at group 2; user target/bounds | Radians internally; config defaults to degrees; four shared shapes | Per entry | -| `group_dihedral` | Ordered four-centroid torsion about groups 2-3 | Same angular units; harmonic deviation wraps at pi | Per entry | - -Dihedral flat intervals are ordinary ordered intervals and cannot cross the -minus-pi/pi boundary. Each term has its own user-specified weight. - -For conformer angles strictly within 0.5 degrees of a 180-degree target, the -zero-slack penalty is `2 * weight * (1 + cos(theta))`. Nonzero slack uses a chord -residual with the same angular free interval, and each bond norm in this cosine -has a 0.02 Angstrom floor. This branch does not alter standalone or custom angles. - -### Target provenance and weights - -Ligand targets come from a copy of the predictor reference relaxed by RDKit UFF, -followed by geometric measurement. Relaxation requires an aromatic or double -bond as evidence of real bond orders. Stereo validation also covers saturated -chiral molecules and can retry four deterministic ETKDG seeds. UFF can retain a -correct reference when relaxation fails. An unrecoverable reference with -incorrect source stereochemistry raises instead of enforcing the wrong isomer. -Relaxation does not mutate the source molecular graph. Bond, angle, chiral, and -cistrans weights are the user-specified linear multipliers of their squared -residuals. - -### Reference and custom restraints - -RMSD references accept mutually exclusive PDB or mmCIF paths, parsed with Gemmi -into the same atom records. Target/reference fit and calculation selections are -independent. Pairing defaults to polymer sequence alignment through Biopython; -identity pairing uses chain, per-chain residue ordinal, and normalized atom name. -Ligands/nonpolymer inputs use identity-style fallback. Atom prime spellings are -normalized, and polymer selectors do not classify ligands by atom name alone. - -Built-in geometry containing `refN and ...` is routed to a reference closure. -A configured reference fit can align its coordinates to the live prediction. -Custom entries use restricted mathematical expressions. They resolve named -selections and references during setup and create backend closures returning a -scalar, including reduction over batches. The parser permits the documented -geometry, math, and penalty vocabulary and rejects arbitrary Python evaluation. -Custom angular functions return radians. Custom `move` stops gradients through -unlisted prediction selections; reference coordinates remain fixed. Custom -centroid functions and built-in groups use ordinary mean derivatives. - -Torch custom closures prepare reference-coordinate tensors before differentiation -and compilation, avoiding NumPy conversion inside a grad transform. Evaluation casts -them to the coordinate dtype; the optimizer rebuilds closures on device/dtype changes. - -### Gradient conventions - -Gradients come from Torch/JAX autodiff. Several deliberate transformations affect -how they should be checked: - -- Array-backed and custom-formula centroid terms use ordinary mean derivatives, including - their `1/N` factor. Free-coordinate gradients agree with finite differences of - the scalar energy. An isolated distance pair gives equal translation within - each group and the displacement ratio `N2:N1`, preserving the atom-count weighted - center. Mixed distance/conformer CG applies the exact affine change of variables - described below; it does not change these energy-layer derivatives. -- Reference-anchored geometry closures retain their existing `N`-scaled prediction - centroid gradients and detached alignment transforms. These surrogate gradients are distinct from the ordinary array - and custom-formula derivatives and can fail strict Wolfe conditions. -- `move` pins the selected term's gradient without removing pinned atoms from its - measured geometry. -- Kabsch rotations are recomputed at each evaluation but - detached from autodiff. Centers remain differentiable. For a nondegenerate - least-squares fit measured on the same atoms, the envelope theorem makes this - consistent with differentiating the minimized scalar; it need not agree when - RMSD fit/calc sets differ. -- Near-exact VdW overlaps use a deterministic pair-dependent separation direction - with a straight-through derivative. Finite differences of the raw radial - function do not validate this escape rule at the singularity. - -Backend agreement, ordinary finite differences, and these movement conventions -are distinct checks. CG can stall on a surrogate direction even when its reported -energy is finite; general convergence proofs for smooth gradients do not establish -convergence for every RGI combination. - -Conformer chiral geometry uses the signed scalar triple product. An odd -permutation of the four atoms reverses its sign; proper rotations and -translations preserve it. Degenerate arrangements can have zero volume and -zero gradient. - -## Activation windows - -A restraint is active when `stop_sigma <= sigma <= start_sigma`, with both -endpoints included. Defaults are positive infinity for `start_sigma` and minus -one for `stop_sigma`. NaN bounds and empty windows are rejected at parsing. -Conformer terms share a window; distance, RMSD, group-angle, group-dihedral, -and custom/reference entries have individual windows. - -Gates multiply masks/energies; they do not rebuild the spec. If sigma exceeds all -start thresholds, minimization returns immediately. Inactive terms contribute no -update even when another term keeps the solver active. Torch's `sigma=None` -omits sigma gating, while the public call still supplies its `istep` value. The -JAX pure minimizer requires the actual schedule values. `finalize` ignores windows -so its energy reports are not necessarily the objective of the last denoising step. - -## VdW execution - -VdW is enabled at weight 1 when a conformer block is present. Its default mode -is `intermolecular`. In the protein–ligand setting, restrained ligand atoms move -against the fixed protein background. Each eligible contact contributes -`weight * min(d - scale * (r_i + r_j), 0)**2`, using RDKit elemental -`GetRvdw` radii and a default scale of 0.75. Covalent 1–2, 1–3, and 1–4 pairs are -excluded even if the corresponding geometry energies are disabled. - -A sorted cell list filters eligible contacts before filling a fixed-width sparse -buffer. Capacity overflow invokes complete pair sums in bounded chunks. Every -trial validates its cache before value/gradient evaluation. The search radius is -`max(dmax, max_contact + neighbor_skin)`, with default skin 2 Å. For fixed -partners, the cache rebuilds when maximum ligand displacement exceeds the skin. -Returning from a rejected distant trial also validates the cache. - -Rebuilds preserve the complete objective, so CG history and counters remain -valid. Background coordinates and gates stay fixed throughout one invocation. -Diagnostics and L-BFGS evaluate the same complete sums. - -## Optimizers - -Torch and JAX optimize the same configured objective. Their device and compilation -paths preserve restraint weights, activation windows, and solver tolerances. - -### Nonlinear conjugate gradient - -`method: CG` selects PR+ with `line_search: strong-wolfe` (default) or -`line_search: armijo` in three execution forms: - -| Implementation | Execution | -| --- | --- | -| `TorchRestraintOptimizer._minimize_cg` | Eager Torch autograd and a Python loop | -| `_torch_cg_gpu._cg_minimize_torch` | Functional gradient/value callable; CUDA normally uses an Inductor-compiled energy/gradient with host-controlled early exits | -| `jax_optim._cg_minimize` | Pure JAX autodiff and `lax.while_loop`, usable inside JIT/scan | - -Torch energy compilation explicitly uses `dynamic=False`: each artifact specializes -the spec and neighbor-list shapes. This also avoids automatic symbolic-shape -generalization across different structures or VdW modes. - -The CUDA fixed-background VdW objective (mode 1) replays a CUDA Graph and copies -its gradient/value outputs into independently owned tensors. CG and L-BFGS may -retain these tensors across subsequent evaluations. Graph-specific failures retry -default Inductor compilation before the existing eager fallback. Other modes, -custom closures, and CPU execution retain default compilation. - -Torch minimization disables the enclosing predictor's autocast locally and restores -it on exit. Small geometry matrix products use explicit reductions in the input -precision, so TF32 settings do not corrupt Kabsch rotations. The -predictor's global matrix-multiplication precision setting is left unchanged. - -All three forms call the shared PR+ loop in -[`optim/_cg.py`](../src/rgi_toolkit/optim/_cg.py). Armijo uses the historical -backtracking transitions in [`optim/_cg_armijo.py`](../src/rgi_toolkit/optim/_cg_armijo.py). -It starts at one on the first iteration, then `2 * max(previous_step, 2**-20)`, -bounded by the working dtype's scalar step range. Each search tries at most -20 steps, halving on rejection, and accepts sufficient decrease with `c1=1e-4`. -The historical upper limit of one is removed: ordinary mean derivatives in -large centroid/RMSD selections can require larger steps. Energy and gradients -are unchanged. A non-descent direction -restarts as `-g`; PR+ uses `dot(g, g) + 1e-12` in its denominator. The accepted -step is carried between iterations. An accepted energy change smaller than -`1e-9 * (1 + abs(previous_energy))` reports `FUNCTION_TOLERANCE`. This retains -the stopping rule of `11de8b4`; it is not a claim that the gradient converged. - -Both modes require finite values/gradients and representable coordinate movement, -and report gradient convergence only when `max(abs(g)) <= gtol`. A failed search -keeps the last accepted coordinates and terminates the invocation. There is no -per-atom displacement clipping or failed-search retry. Neighbor lists are checked -before every trial, including rejected trials. - -The remaining search details in this section describe **Strong Wolfe**, -implemented in [`optim/_cg_linesearch.py`](../src/rgi_toolkit/optim/_cg_linesearch.py). -Its reference is **SciPy 1.17.1**, specifically -[`_minimize_cg`](https://github.com/scipy/scipy/blob/v1.17.1/scipy/optimize/_optimize.py), -[Wolfe1/Wolfe2 searches](https://github.com/scipy/scipy/blob/v1.17.1/scipy/optimize/_linesearch.py), -and [`DCSRCH`/`dcstep`](https://github.com/scipy/scipy/blob/v1.17.1/scipy/optimize/_dcsrch.py). -The adapted code retains the SciPy BSD notice in [`LICENSE`](../LICENSE), -shipped in source and wheel distributions, and the MINPACK attribution in the source. -SciPy remains a pinned development oracle; runtime minimization imports no SciPy. - -For objective `f`, autodiff vector `g`, and search direction `d`: - -```text -d0 = -g0 -previous_f0 = f0 + norm(g0, 2) / 2 -alpha0 = min(1, 1.01 * 2 * (f - previous_f) / dot(g, d)) -beta = max(0, dot(g_new, g_new - g) / dot(g, g)) -d_new = -g_new + beta * d -``` - -A negative initial step guess is replaced by one, following SciPy; the applicable -step bounds then limit it. The previous accepted objective, rather than the previous -step length, supplies the next initial guess. No epsilon is added to the PR+ -denominator: a nonfinite or nonpositive squared gradient cannot start a search. - -The first search uses More--Thuente DCSRCH with its four safeguarded `dcstep` -interpolation cases. If it fails or its candidate fails the prospective PR+ -sufficient-descent check, the solver invokes SciPy's Wolfe2 bracketing/zoom -procedure. Both require strong Wolfe (`c1=1e-4`, `c2=0.4`): - -```text -f(x + alpha*d) <= f(x) + c1 * alpha * dot(g, d) -abs(dot(g_new, d)) <= -c2 * dot(g, d) -``` - -An accepted candidate additionally satisfies -`dot(g_new, d_new) <= -0.01 * dot(g_new, g_new)`, unless its gradient already meets -`gtol`. That exception bypasses only the prospective-direction check, never Wolfe. -DCSRCH permits 100 iterations and uses `xtol=1e-14`; the Wolfe2 expansion budget is -10, and its zoom loop follows SciPy's `i > 10` exhaustion rule (up to 11 trials). -The current trial's value and gradient are cached across search phases, including -different step lengths that round to identical coordinates, as in SciPy's -`ScalarFunction`. Evaluation counters count actual combined value/gradient calls, -including rejected trials. -Constants live in [`optim/_cg_config.py`](../src/rgi_toolkit/optim/_cg_config.py). - -JAX's minimizer uses [`sequential_vmap`](https://docs.jax.dev/en/latest/_autosummary/jax.custom_batching.sequential_vmap.html) -so an outer predictor `vmap` retains each -sample's conditional execution and early exits. Ordinary batched `lax.cond` -evaluates [both branches](https://docs.jax.dev/en/latest/_autosummary/jax.lax.cond.html), which would rebuild neighbours and compute complete -overflow sums even when their predicates are false. The mapped solves remain -device-side loops; no host callback is used. Tests compare their coordinates, -diagnostics and actual rebuild counts with explicit individual solves. -JAX selects between cheap scalar interpolation/update formulas with pointwise -operations so XLA can fuse them. Objective evaluations and neighbour work remain -conditional. Torch retains the same scalar branch calls through a method alias. -Both Wolfe2 bracket orientations share one zoom body, and DCSRCH and Wolfe2 each -request values and gradients at one loop site. This avoids duplicate compiled objective bodies -without changing trial order, interpolation or search budgets. - -For Strong Wolfe, only `max(abs(g)) <= gtol` reports convergence. There is no energy-change -stop or restart latch, no accepted-step doubling, and no steepest-descent retry -after failed searches. Failure returns the last accepted coordinates and terminates -that minimization, even if earlier iterations moved atoms. The next denoising -invocation starts a fresh CG search. - -Strict RGI acceptance differs from SciPy's exceptional exits: Wolfe2's unverified -last trial on iteration exhaustion is rejected, and nonfinite coordinates, values, -gradients, or a step with no representable movement cannot be accepted. Invalid -DCSRCH trials trigger Wolfe2; invalid high-bracket trials are bisected toward the -last finite lower endpoint. Scalar bounds `1e-100..1e100` are restricted to the -working dtype's representable range (upper bound at most `finfo.max / 8`). These -safeguards and different floating-point evaluation orders preclude a promise of -bitwise agreement on every objective. - -All trials stay on the straight search direction with no per-atom displacement -cap. The obsolete VdW keys `max_atom_step` and `neighbor_rebuild_interval` raise a -migration error. Ordinary centroid derivatives replace gradient-only rescaling; -the free-coordinate gradient now matches the scalar centroid energy. Pinned atoms -and frozen reference fits retain their documented semantics, so exceptional -modified objectives still need explicit termination diagnostics. - -Mixed distance/conformer objectives can be very ill-conditioned: a large group's -centroid translation is much softer than a ligand bond deformation. CG therefore -uses a fixed affine coordinate map for these objectives. For each active distance -entry, let `w` contain `+1/N1` and `-1/N2` on its free groups (accumulating overlaps; -pinned groups contribute zero), `q=w/||w||`, and `s=max(1,1/||w||)`. Define -`S=I+sum((s-1)*q*q.T)` and minimize `F(u)=E(x0+S*(u-x0))` from `u=x0`. -The same `S` acts independently on all three spatial axes. It is symmetric positive -definite even for overlapping entries. Its exact gradient is `S.T*grad(E)`; -energies, targets, weights, iteration limits and Wolfe constants are unchanged. -An isolated free pair retains the atom-count weighted center and `N2:N1` split. -The map stays fixed for the entire invocation, including neighbour rebuilds. -Distance-only objectives retain ordinary Cartesian CG. In mixed objectives, -`CGInfo.grad_norm` and SciPy comparisons use these optimizer coordinates. - -The CG state carries `f`, `g`, `d`, `dot(g,g)`, the previous objective, a validity -flag, cumulative `CGInfo`, and the trial's neighbour caches. Convergence or failure -ends the invocation. Cache rebuilds preserve search history because capacity no -longer truncates the objective. Resuming externally still requires unchanged -coordinates and the same objective. - -The mathematical references are [Polak and Ribiere (1969)](https://numdam.org/item/M2AN_1969__3_1_35_0/) -and [Gilbert and Nocedal (1992)](https://epubs.siam.org/doi/10.1137/0802003), with the -More--Thuente and bracketing algorithms documented in the pinned SciPy sources. -Their smooth-objective assumptions do not establish a convergence theorem for -RGI's sometimes modified-gradient molecular objective. - -### L-BFGS - -L-BFGS follows the backend library algorithms through CUDA and JAX cache adapters. The method -is described by [Liu and Nocedal (1989)](https://link.springer.com/article/10.1007/BF01589116). - -| Backend | Delegation and explicit RGI options | Other stopping/history settings | -| --- | --- | --- | -| Torch | `torch.optim.LBFGS` on CPU; `CudaLBFGS` on the ordinary CUDA path, based on [PyTorch 2.8.0](https://github.com/pytorch/pytorch/blob/v2.8.0/torch/optim/lbfgs.py). Both set `max_iter`, `tolerance_grad=gtol`, `line_search_fn="strong_wolfe"` | Change tolerance `1e-9`, history size 100, default `max_eval = max_iter * 5 // 4` | -| JAX | `CachedLBFGS`, derived from [`jaxopt.LBFGS`](https://jaxopt.github.io/stable/_autosummary/jaxopt.LBFGS.html), with `maxiter`, `tol=gtol`, `linesearch="zoom"`, `implicit_diff=False` | Standard zoom search; upstream history size 10 and maximum 30 line-search steps | - -CG and both L-BFGS adapters use the configured `gtol`, which defaults to `1e-5`. Torch uses -an infinity norm; JAXopt uses a Euclidean norm. Their other stopping rules differ. -`CachedLBFGS` passes the accepted VdW cache through JAXopt's auxiliary state. Every trial -still validates its displacement before evaluating energy; the library search, history -and stopping rules remain unchanged. -The ordinary CUDA adapter batches loss/slope transfers and evaluates the upstream scalar line -search on the CPU. Coordinates and history vectors stay on the GPU. Triton fuses the -two-loop recursion for at most 8192 variables and accepts device scalars for vector -updates. Larger problems or compiler failures use the ordinary recursion. History -updates, line-search conditions and stopping rules are preserved; parallel reductions -can change rounding and the trajectory of a nonconvex optimization. -JAX's former backtracking override could fail a search without moving; its library -tolerance of `1e-3` could then stop large centroid restraints far from their targets. -The shared gradient threshold does not guarantee a particular coordinate residual: -centroid derivatives decrease with group size, so large groups can meet the -threshold before their distance or angle error is negligible. -Other library defaults can change -when dependencies are updated. `uv.lock` defines the repository test environment; -predictor environments may pin other versions. Torch's source attributes its -implementation to minFunc; JAXopt documents the standard limited-memory inverse -Hessian method. RGI's use of either does not imply identical stopping rules to CG. -The independent SciPy comparison uses unbounded `L-BFGS-B`; this is a comparison -of final solutions and residuals, not a claim of identical implementations. - -## Verification contract - -The optimizer comparison modules require SciPy 1.17.1, Torch, JAX, and JAXopt on CPU; -missing dependencies fail collection rather than silently skipping a backend. -Fixtures are small, deterministic, offline, and generated in memory or pytest -temporary directories. They do not require a predictor installation. The oracle calculations in these modules do not call -RGI's geometry or energy kernels. - -[`test_optimizer_reference.py`](../tests/test_optimizer_reference.py) compares -all three CG forms and both L-BFGS backends against independent analytic/SciPy -objectives: isotropic and diagonal quadratics, a coupled quadratic with condition -number 256, Rosenbrock plus a decoupled quadratic coordinate, and an already-solved -initial point. SciPy CG and unbounded L-BFGS-B references are themselves checked -against analytic optima and gradients. Tests use float64 and at most 10,000 -iterations. For these unique solutions, the acceptance limits are: - -- Energy difference at most `1e-6 * (1 + abs(reference_energy))`. -- Coordinate maximum absolute difference at most `1e-3`. -- Independent gradient maximum absolute value below `1e-6` for CG or `1e-3` - for the existing L-BFGS settings. - -The same module checks previous-objective/state preservation across cache rebuilds, -nonfinite trial gradients, and unrepresentable updates. Separately marked GPU -tests check the compiled Torch path and JAX CG inside JIT/scan against SciPy. -[`test_cg_linesearch.py`](../tests/test_cg_linesearch.py) compares safeguarded -interpolation cases, search-phase transitions and representative accepted -trajectories with the pinned SciPy implementation, using the same tolerance and -iteration budget. It independently checks Wolfe and prospective descent. -[`test_optimizer_info.py`](../tests/test_optimizer_info.py) verifies the public -diagnostics, inactive windows, batch aggregation, reset, JAX scan output, strict -unrestricted steps, and termination/counter preservation across neighbour rebuilds. - -[`test_e2e.py`](../tests/test_e2e.py) follows config parsing, adapter selections, -spec construction, minimization, and verbose finalization. It drives Torch's -public mutation API and JAX's public minimizer inside JIT/scan, with both methods. -It checks initial as well as final energies so an incorrect coefficient cannot -hide behind a zero-valued minimum. Coverage includes all distance penalty shapes, -unequal centroid groups and move modes, noncontiguous atom rows, batch inputs, -sigma boundaries, repeated setup, group geometry, conformer geometry, -PDB/mmCIF RMSD, custom formulas, and static/dynamic VdW. Dynamic contacts -are compared with direct dense evaluation at both the energy and stationarity -levels. Their convergence fixtures use a nonbinding displacement cap; separate -fixtures prove that an infeasible cap returns failure and retains coordinates. -Nonunique geometric solutions are compared through energy, measured -geometry, rigid-group motion, and pins instead of arbitrary Cartesian equality. -Nonconvex fixtures keep starts in the same basin; these tests do not certify a -global minimum for general molecular objectives. - -| Additional contract | Existing verification | -| --- | --- | -| Backend energy/gradient agreement and fixed-fit geometry | [`test_backend_parity.py`](../tests/test_backend_parity.py), [`test_shared_geometry.py`](../tests/test_shared_geometry.py) | -| Selection grammar, atom names, reference pairing | [`test_selection.py`](../tests/test_selection.py), [`test_reference_atom_names.py`](../tests/test_reference_atom_names.py), [`test_align.py`](../tests/test_align.py), [`test_ref_config.py`](../tests/test_ref_config.py) | -| Config rejection and activation bounds | [`test_config_validation.py`](../tests/test_config_validation.py), [`test_window_params.py`](../tests/test_window_params.py) | -| Public state, adapters, and scan wrapper | [`test_combined_restraints.py`](../tests/test_combined_restraints.py), [`test_adapters_shared.py`](../tests/test_adapters_shared.py), [`test_scan_runner.py`](../tests/test_scan_runner.py) | -| Chemical targets, relaxation, stereochemistry | [`test_featurizer.py`](../tests/test_featurizer.py), [`test_conformer_chemistry.py`](../tests/test_conformer_chemistry.py), [`test_relax_force_field.py`](../tests/test_relax_force_field.py), [`test_ideal_conformer.py`](../tests/test_ideal_conformer.py) | -| Group geometry and custom move/gradient rules | [`test_group_geom_data.py`](../tests/test_group_geom_data.py), [`test_custom.py`](../tests/test_custom.py), [`test_custom_move.py`](../tests/test_custom_move.py) | -| Dtype/device caches, VdW lists, compiled objectives | [`test_optim.py`](../tests/test_optim.py) | - -Run the mandatory CPU suite and code checks with: - -```bash -uv sync --frozen --extra torch --extra jax -JAX_PLATFORMS=cpu uv run pytest -m "not gpu" -q -uv run ruff check src tests -uv run ruff format --check src tests -``` - -The existing CI installs both backend extras and executes the non-GPU suite. -GPU-marked cases require a CUDA/JAX accelerator environment and a compute-node -allocation; CPU execution of the functional CUDA loop does not validate GPU -compilation, device synchronization, or accelerator performance. Full predictor -sampling and structural/scientific validation remain separate from toolkit E2E. - -## Conformer activation - -`RestraintsConfig.conformer_config` is `None` for an absent/null block and a -dictionary for an explicit block, including `{}`. Bond, angle, chiral, cistrans, -and VdW have default weight 1. Explicit nonpositive or null weights disable a -term. Ligand opt-in remains mandatory. diff --git a/docs/alphafold3_restr.md b/docs/alphafold3_restr.md index 1add51e..cb40023 100644 --- a/docs/alphafold3_restr.md +++ b/docs/alphafold3_restr.md @@ -22,9 +22,6 @@ uv venv && source .venv/bin/activate # Python 3.12+ uv pip install -e . # compiles the C++ chem components (cmake/ninja) + pulls the rgi_toolkit engine ``` -> For co-development of the engine, override the pinned dependency with a local editable -> checkout in a SEPARATE step: `uv pip install -e ../RGI-toolkit` (sibling clone). - - **Model parameters** are not redistributable: request them via Google's form (see the repo's `WEIGHTS_TERMS_OF_USE.md`) and point `--model_dir` at them. - Run on a CUDA GPU. diff --git a/docs/bioemu2_restr.md b/docs/bioemu2_restr.md new file mode 100644 index 0000000..5be7c36 --- /dev/null +++ b/docs/bioemu2_restr.md @@ -0,0 +1,218 @@ +# BioEmu2 — Restraint-Guided Inference (RGI) + +[Documentation index](README.md) · [Configuration reference](config.md) + +BioEmu2 uses the shared PyTorch RGI engine for distance, angle, dihedral, +conformer, RMSD, custom, and other supported restraints. Configuration fields +and atom-selection syntax are described in [config.md](config.md). + +## Installation + +Install the predictor fork on its RGI branch with Linux, Python 3.12 or later, +and a supported NVIDIA GPU: + +```bash +git clone --branch rgi-integration https://github.com/cddlab/bioemu2_restr.git +cd bioemu2_restr +uv sync --extra cuda +``` + +BioEmu2 downloads its checkpoint when needed. See the +[upstream guide](https://github.com/microsoft/bioemu2) for checkpoint and GPU +requirements. Run prediction commands on a GPU compute node. + +## Configuration + +Add `restraints_config` at the root of a system YAML, beside `entities`. +For conformer restraints, also set `conformer_restraints: true` on each +participating entity. Ligand and polymer entities opt in independently; +the default is false. + +Use explicit `asym_ids` for predictable chain selections. `resid` is a +per-chain, one-based token ordinal. Standard polymer residues occupy one +token; atomized ligands and modified residues can occupy several. It is not +the reference structure's author residue number. `index` is the zero-based +row in the padded coordinate tensor; padding is excluded from selections. + +Set `start_sigma` and `stop_sigma` on each restraint entry or on the +conformer block. There is no top-level `start_sigma`. + +## Complete example (system YAML) + +Save this as `restr_example.yaml` in the predictor checkout. Like the other +predictor guides, it folds QBP with its GLN ligand and combines distance, angle, +dihedral, ligand conformer, reference RMSD, and custom restraints. The custom +expression keeps the two lobe-centroid distances equal. The run section below +downloads the QBP reference structure and uses BioEmu2's ColabFold MSA acquisition. + +```yaml +entities: + - entity_type: protein + sequence: ADKKLVVATDTAFVPFEFKQGDKYVGFDVDLWAAIAKELKLDYELKPMDFSGIIPALQTKNVDLALAGITITDERKKAIDFSDGYYKSGLLVMVKANNNDVKSVKDLDGKVVAVKSGTGSVDYAKANIKTKDLRQFPNIDNAYMELGTNRADAVLHDTPNILYFIKTAGNGQFKAVGDSLEAQQYGIAFPKGSDELRDKVNGALKTLRENGTYNEIYKKWFGTEPK + asym_ids: A + - entity_type: ligand + ccd_code: GLN + asym_ids: B + conformer_restraints: true +restraints_config: + verbose: true + gpu: true + method: CG + max_iter: 1000 + distance_restraints_config: + - atom_selection1: "chain A and ((resid 5 to 84) or (resid 186 to 224))" + atom_selection2: "chain A and (resid 90 to 180)" + start_sigma: 99999999 + stop_sigma: -1 + move: both + weight: 1.0 + harmonic: + target_distance: 25.0 + angle_restraints_config: + - atom_selection1: "chain A and (resid 5 to 84)" + atom_selection2: "chain A and (resid 90 to 180)" + atom_selection3: "chain A and (resid 186 to 224)" + start_sigma: 99999999 + stop_sigma: -1 + move: "1,3" + weight: 1.0 + harmonic: + target_angle: 90.0 + dihedral_restraints_config: + - atom_selection1: "chain A and (resid 5 to 50)" + atom_selection2: "chain A and (resid 51 to 100)" + atom_selection3: "chain A and (resid 101 to 150)" + atom_selection4: "chain A and (resid 151 to 224)" + start_sigma: 99999999 + stop_sigma: -1 + move: "1,4" + weight: 1.0 + harmonic: + target_dihedral: 180.0 + conformer_restraints_config: + start_sigma: 99999999 + stop_sigma: -1 + bond: {weight: 1.0, slack: 0.0} + angle: {weight: 1.0, slack: 0.0} + chiral: {weight: 1.0, slack: 0.0} + cistrans: {weight: 1.0, slack: 0.0} + vdw: {weight: 1.0} + rmsd_restraints_config: + - ref_pdb: rmsd_ref.pdb + harmonic: {target_rmsd: 0.0} + weight: 1.0 + start_sigma: 99999999 + stop_sigma: 1.0 + pairing: align + best_effort: true + atom_selection_ref_fit: "chain A and (resid 5 to 220)" + atom_selection_target_fit: "chain A and (resid 5 to 220)" + atom_selection_ref_calc: "chain A and (resid 90 to 180)" + atom_selection_target_calc: "chain A and (resid 90 to 180)" + custom_restraints_config: + - name: equidistant + energy: "(distance(L1, H) - distance(L2, H))**2" + selections: + L1: "chain A and (resid 5 to 84)" + L2: "chain A and (resid 186 to 224)" + H: "chain A and (resid 90 to 180)" + start_sigma: 99999999 + stop_sigma: -1 + weight: 1.0 +``` + +## Run + +Save this as `run_restr_example.sh` beside the YAML in the predictor checkout, +then run `bash run_restr_example.sh` on a GPU compute node. It downloads the +1GGG reference used by the RMSD entry into the working directory: + +```bash +#!/usr/bin/env bash +set -euo pipefail + +curl -fLsS https://files.rcsb.org/download/1GGG.pdb -o rmsd_ref.pdb + +uv run --no-sync bioemu2 predict-structure \ + --system restr_example.yaml --out out_restr_example \ + --num-samples 1 --num-steps 200 --sampler edm --seed 0 +``` + +An omitted or null `restraints_config` keeps ordinary sampling. An empty +object adds no restraint terms. Optional `config_path` references resolve +relative to the containing YAML; the runnable examples keep settings inline. + +## Runnable examples + +The same systems and restraint settings are available for the other models +in each parent directory: + +| Example | Input | Run from the RGI-toolkit checkout | +|---|---|---| +| QBP distance, 25.0 Å | [YAML](../examples/distance/bioemu2/qbp_25.00.yaml) | `bash examples/distance/bioemu2/run.sh` | +| ADK angle, 72.85° | [YAML](../examples/angle/bioemu2/adk_72.85.yaml) | `bash examples/angle/bioemu2/run.sh` | +| QBP dual-reference RMSD, 2.65/2.65 Å | [YAML](../examples/rmsd/bioemu2/qbp_2.65.yaml) | `bash examples/rmsd/bioemu2/run.sh` | +| DgoT distance difference, 0.8 Å | [YAML](../examples/custom/dist-diff/bioemu2/dgot_0.80.yaml) | `bash examples/custom/dist-diff/bioemu2/run.sh` | +| MDM2–p53 dissociation, 13.0 Å | [Input and MSA setup](../examples/ligand-dissociation/README.md) | `bash examples/ligand-dissociation/bioemu2/run.sh` | + +The first four examples use BioEmu2's ColabFold MSA acquisition. The dissociation +runner loads the supplied chain-A and chain-B A3Ms through the Python API. +All five runners use structure conditioning, one sample, 200 EDM steps, +and seed 0. + +## Python API and precomputed MSAs + +```python +from pathlib import Path + +from bioemu2 import EmuSession, System, get_msa, load_model, save_frames + +system = System.from_yaml( + "../RGI-toolkit/examples/ligand-dissociation/bioemu2/mdm2_p53_13.00.yaml" +) +msa_dir = Path("../RGI-toolkit/examples/ligand-dissociation/msas") +msa = get_msa( + system, + {"A": msa_dir / "mdm2_p53.a3m", "B": msa_dir / "p53.a3m"}, +) +session = EmuSession(system, model=load_model(), mode="structure", msa=msa) +samples = session.sample(num_samples=1, sampler="edm", seed=0) +save_frames(samples, "out_mdm2_p53") +``` + +Use `mode="equilibrium"` or `sample-equilibrium` for equilibrium conditioning. +RGI changes the sampling distribution; restrained samples are not an unbiased +equilibrium ensemble. + +## Verify results + +With `verbose: true`, check nonzero counts for distance, group angle, group +dihedral, RMSD, ligand bond/angle/chirality, and the custom expression in the +complete example. GLN has a tetrahedral center but no eligible E/Z dihedral, +so `cistrans=0` is expected even though its weight is enabled. Check that VdW +includes the ligand against the protein background. The separate dissociation +example must build one distance between chains A and B. + +Measure the requested geometry in the saved structures. Reference coordinates +and RGI distance targets use angstroms; MDTraj trajectory coordinates use +nanometers. Convert those coordinates before comparing distances. A zero +energy for an absent term does not show that a restraint ran. Configuration +validation checks the schema and selection syntax; it does not establish +successful inference or satisfaction of the final target. + +## Integration details + +The adapter lives in `rgi_toolkit.bioemu2`. The predictor fork extracts source +chemistry and attaches metadata from the exact processed structure. For +SMILES ligands, atom correspondence through InChI normalization preserves +the original bond orders, charges, and stereochemistry. CCD components retain +their named atoms and reference stereochemistry; leaving atoms absent from +the sampled structure are excluded. + +Each sampler call creates fresh restraint state. RGI minimizes the denoised +coordinates after native gradient guidance and before alignment and integration, +using the pre-churn sigma in angstroms. `edm`, `edm_gd`, and `edm_fk` support RGI. +The context-parallel path minimizes on rank zero and broadcasts coordinates; +multi-GPU validation is separate from the single-GPU examples here. +`edm_fkc` rejects RGI because its importance weights need a separate treatment +of the additional guidance. diff --git a/docs/boltz_restr.md b/docs/boltz_restr.md index 4d6d4f9..f841bfc 100644 --- a/docs/boltz_restr.md +++ b/docs/boltz_restr.md @@ -16,9 +16,6 @@ uv venv && source .venv/bin/activate # Python 3.11+ uv pip install -e ".[cuda]" # also pulls the rgi_toolkit engine (declared in pyproject) ``` -> For co-development of the engine, override the pinned dependency with a local editable -> checkout in a SEPARATE step: `uv pip install -e ../RGI-toolkit` (sibling clone). - ## Configuration boltz reads RGI from a **top-level `restraints_config:` key nested inside the input YAML** (the diff --git a/docs/chai-lab_restr.md b/docs/chai-lab_restr.md index 459fc4f..8868ae9 100644 --- a/docs/chai-lab_restr.md +++ b/docs/chai-lab_restr.md @@ -19,9 +19,6 @@ uv pip install --reinstall torch --index-url https://download.pytorch.org/whl/cu uv pip install pyyaml # chai1.py imports yaml, not a chai dep ``` -> For co-development of the engine, override the pinned dependency with a local editable -> checkout in a SEPARATE step: `uv pip install -e ../RGI-toolkit` (sibling clone). - ## Configuration chai is the **odd one out**: the file you pass to `--restraints-config-path` **IS** the diff --git a/docs/config.md b/docs/config.md index 16c9957..0cc2d79 100644 --- a/docs/config.md +++ b/docs/config.md @@ -3,15 +3,20 @@ [Documentation index](README.md) Every RGI tool is driven by one `restraints_config` dict: a YAML/JSON block -for Boltz, Protenix, Chai, AlphaFold3, OpenFold3, OpenDDE, and RF3, or a Python +for Boltz, Protenix, Chai, AlphaFold3, OpenFold3, OpenDDE, RF3, and BioEmu2, or a Python dict for ESMFold2. See each tool's guide for where to place it. -This page documents configuration for the restraint types described in the paper. +This page covers built-in geometry, conformer and RMSD restraints, and custom +expressions or Python functions, +including optional terms beyond the paper's benchmark configuration. Each documented key includes its type, default, allowed values, and meaning. Omitted keys fall back to their documented defaults. Unknown top-level keys and unknown conformer keys raise an error. Unknown keys inside individual restraint entries are logged and ignored, so check their spelling against this page. Source of truth: `src/rgi_toolkit/{config,distance_restr_data,group_geom_restr_data,ref_geom_restr_data,ref_config,featurizer,rmsd_restr_data,pdb_ref,_align,selection}.py`. +Standalone planes use `plane_restr_data.py`; polymer targets use `polymer.py`, +`monlib_geom.py`, and `_polymer_torsions.py`. Custom geometry is defined in +`custom/vocabulary.py`. ## Quick navigation @@ -21,9 +26,16 @@ check their spelling against this page. Source of truth: - [Atom-selection DSL](#atom-selection-dsl) and [penalty shapes](#penalty-shapes-shared) - [Distance](#distance_restraints_config-list), [group angle](#angle_restraints_config-list), and [group dihedral](#dihedral_restraints_config-list) +- [Group improper](#improper_restraints_config-list), [group chirality](#chiral_restraints_config-list), + and [standalone planes](#plane_restraints_config-list) - [Conformer geometry and VdW](#conformer_restraints_config-single-dict) +- [Ligand force-field selection](#ligand-force-field-selection) +- [Conformer planes and torsions](#plane-and-torsion-terms), + [polymer dictionary targets](#polymer-targets-and-monomer_library), + and [VdW modes](#van-der-waals-repulsion) - [RMSD](#rmsd_restraints_config-list) - [Custom restraints](#custom_restraints_config-list) +- [Python custom restraints](#python-functions-and-registration) ## Shape @@ -41,17 +53,21 @@ restraints_config: distance_restraints_config: [ ... ] # list angle_restraints_config: [ ... ] # list (group-centroid angle) dihedral_restraints_config: [ ... ] # list (group-centroid dihedral) - conformer_restraints_config: { ... } # single dict (ligand local geometry) + improper_restraints_config: [ ... ] # list (ordered group-centroid improper) + chiral_restraints_config: [ ... ] # list (signed group-centroid volume) + plane_restraints_config: [ ... ] # list (selected atoms, not centroids) + conformer_restraints_config: { ... } # single dict (ligand or polymer geometry) rmsd_restraints_config: [ ... ] # list - custom_restraints_config: [ ... ] # list (define your OWN restraint — see below) + custom_restraints_config: [ ... ] # list (formula or Python function) ``` A restraint type is active only if its block is present (and, for conformer terms, the term's `weight > 0`). -The documented restraint types are distance, angle, dihedral, conformer, RMSD, -and custom expressions. `custom_restraints_config` defines a differentiable loss -as a mathematical formula. +The documented restraint types are distance, angle, dihedral, improper, chiral, +plane, conformer, RMSD, and custom energies. Standalone chiral and plane entries +do not require conformer opt-in. `custom_restraints_config` defines a differentiable +loss as a mathematical formula or a Python function. ## Top-level keys @@ -101,7 +117,7 @@ the number of atoms. Tightening `gtol` does not increase `max_iter`, remove other stopping rules, or guarantee a zero loss for competing restraints or a local minimum. L-BFGS uses the backend library's line search; an explicit `line_search` key with -L-BFGS raises an error. See the [solver specification](SPEC.md#optimizers). +L-BFGS raises an error. **There is no `backend` key** — the compute backend (torch / jax) is **inferred from how the engine is invoked**, not configured: a JAX tool (AF3) grabs the pure minimizer via @@ -146,13 +162,17 @@ themselves are shared across the batch. | `distance_restraints_config` | `R` entries, padded group width `G` | `O(RG)` | `O(RG)` | Two centroids per entry; the factor 2 is constant. | | `angle_restraints_config` | `R` entries, padded group width `G` | `O(RG)` | `O(RG)` | Three group centroids plus one constant-size angle. | | `dihedral_restraints_config` | `R` entries, padded group width `G` | `O(RG)` | `O(RG)` | Four group centroids plus one constant-size torsion. | +| `improper_restraints_config`, `chiral_restraints_config` | `R` entries, padded group width `G` | `O(RG)` | `O(RG)` | Four centroids followed by an ordered torsion or scalar triple product. | +| `plane_restraints_config` | `R` entries, maximum pooled atom count `G` | `O(RG)` | `O(RG)` | One covariance and 3 x 3 eigendecomposition per plane. | | conformer `bond` | `B` bond tuples | `O(B)` | `O(B)` | Each tuple gathers two atoms. | | conformer `angle` | `A` angle tuples | `O(A)` | `O(A)` | Each tuple gathers three atoms. | | conformer `chiral` | `C` chiral tuples | `O(C)` | `O(C)` | Each tuple gathers four atoms and evaluates one scalar triple product. | | conformer `cistrans` | `T` tuples per term | `O(T)` | `O(T)` | Each tuple gathers four atoms. | +| conformer `torsion` | `T` tuples | `O(T)` | `O(T)` | Four-atom periodic torsions, separate from E/Z tuples. | +| conformer `plane` | `P` planes, padded atom count `G` | `O(PG)` | `O(PG)` | Whole atom groups and constant-size plane fits. | | `rmsd_restraints_config` | `R` entries, maximum padded fit/calc widths `F` / `C` | `O(R(F + C))` | `O(R(F + C))` | One 3 x 3 Kabsch SVD per entry; it is not `O(F^3)` or `O(C^3)`. | | built-in `refN and ...` variant | total prediction/reference group atoms `G`, reference-fit atoms `F` | `O(G + F)` per reference access | `O(G + F)` | These entries use a closure. A configured fit recomputes a 3 x 3 Kabsch transform; without a fit the `F` term is absent. | -| `custom_restraints_config` | `C_expr` = sum of the executed primitive/array costs | `O(C_expr)` | expression-dependent | Centroid geometry is linear in the selected group sizes; `kabsch` and `rmsd` are also linear because their matrix decomposition is 3 x 3. Repeated calls are recomputed, and `where`/conditional expressions evaluate **both** branches. | +| `custom_restraints_config` | `C_expr` = sum of the executed primitive/array costs | `O(C_expr)` | expression-dependent | Centroid geometry, `rg`, `plane`, `kabsch`, and `rmsd` are linear in the selected group sizes; matrix decompositions are 3 x 3. Repeated calls are recomputed, and `where`/conditional expressions evaluate **both** branches. | The table starts after atom selections and reference pairings have been resolved. That one-time setup scans the target atom records once per selection (`O(S * N_target)` for `S` selections). @@ -169,6 +189,13 @@ density, cell-list construction costs `O(B log B + L log B)` and an objective evaluation costs `O(LK)`. Overflow rows use complete background sums. A collapsed structure can require `O(LB)` work, without allocating a dense distance matrix. +Intramolecular ligand pairs are stored explicitly after covalent exclusions; +their count can grow as `O(L^2)`. Intermolecular pairs between restrained ligands +are also explicit, with `O(L_i L_j)` pairs for ligands `i` and `j`. Dynamic +active-active contacts involving restrained polymer atoms use a cell list: +ordinary-density construction is `O(N log N)` and evaluation is `O(NK)` for +`N` active atoms, with complete pair sums on overflow. + When every restraint is outside its sigma window, minimization is skipped. ## Sigma gating: `start_sigma` & `stop_sigma` @@ -184,11 +211,15 @@ window: - **Active window:** `stop_sigma <= sigma <= start_sigma`. `stop_sigma > start_sigma` is an empty window and **raises** (a silent no-op would read as "satisfied"). -Where they live: **once per `distance` / `angle` / `dihedral` / `rmsd` / `custom` entry**, and **once +Where they live: **once per standalone geometry, RMSD, or custom entry**, and **once for all conformer terms** (`conformer_restraints_config.start_sigma` / `.stop_sigma`). When `sigma` exceeds every active restraint's `start_sigma`, the whole minimization step is skipped (cheap at high noise). +Alternatively, use `start_step` / `stop_step` for an inclusive diffusion-step window +(defaults `-inf` / `+inf`). An entry or conformer block cannot specify both step and +sigma windows. Step indices depend on the predictor's sampling schedule. + The RMSD restraint's `stop_sigma` has a specific use: releasing it late (e.g. `1.0`) lets the model re-idealise geometry the restraint held distorted — the fix for a peptide bond broken at a restrained-residue / free unmodeled-tail boundary. @@ -259,7 +290,7 @@ d = \lVert c_2 - c_1 \rVert, \qquad c_k = \frac{1}{|G_k|}\sum_{a \in G_k} x_a (a plain masked-mean centroid), shaped by one of the penalty blocks below (see Penalty shapes). `harmonic` drives the distance toward $d = t$ with CG (gradient tolerance `gtol`; -see [termination semantics](SPEC.md#nonlinear-conjugate-gradient)). +see [optimizer settings](#top-level-keys)). | key | type | default | meaning | |---|---|---|---| @@ -411,11 +442,151 @@ dihedral_restraints_config: harmonic: {target_dihedral: 180.0} ``` +## `improper_restraints_config` (list) + +An improper restraint uses four ordered group centroids and the same signed-angle +calculation as `dihedral_restraints_config`. It has its own configuration and +`group_improper` energy term. It does not infer a central atom, reorder the groups, +or fit a plane; use the quartet order appropriate to the intended geometry. + +| key | type | default | meaning | +| --- | --- | --- | --- | +| `atom_selection1..4` | str | required | Four ordered groups; the angle is about the group 2–3 axis | +| `unit` | `"degrees"` / `"radians"` | `"degrees"` | Units for the target and bounds | +| one penalty block | dict | required | `harmonic: {target_improper: ...}` or `flat-bottomed{,1,2}` with `target_improper1` / `target_improper2` | +| `move` | `"all"` / int / list / comma-separated str | `[1, 4]` | Free groups; groups 2 and 3 are pinned by default | +| `weight` | float | `1.0` | Multiplier on the squared residual | +| `start_sigma` / `stop_sigma` | float | `+inf` / `-1` | Per-entry activation window; a step window may be used instead | + +Harmonic deviations wrap to `[-pi, pi]`. Flat-bottomed intervals are ordered +intervals and cannot cross the `-180°` / `+180°` boundary. For example, the +following ordered peptide quartet is driven toward an improper angle of 180°: + +```yaml +improper_restraints_config: + - atom_selection1: "chain A and resid 25 and name CA" + atom_selection2: "chain A and resid 25 and name C" + atom_selection3: "chain A and resid 25 and name O" + atom_selection4: "chain A and resid 26 and name N" + harmonic: {target_improper: 180.0} + move: all +``` + +Choose the quartet order and target together; permuting the quartet can change the +angle. Coincident or collinear groups can make its gradient ineffective, as for +the ordinary dihedral. Reference groups use the +[same syntax as dihedrals](#reference-groups-2), with up to three distinct +references. References remain fixed; omitted `move` on a reference-containing +entry frees all prediction groups. + +## `chiral_restraints_config` (list) + +This standalone restraint measures the signed scalar triple product of four +group centroids, with group 1 as the center: + +```math +V = (c_2-c_1)\cdot\big((c_3-c_1)\times(c_4-c_1)\big). +``` + +Targets are in **ų**, without division by six. The sign follows the ordered +groups, not an automatic R/S assignment. Swapping two of groups 2–4 reverses it. +This entry is independent of the automatically generated conformer `chiral` term +and requires no ligand or polymer conformer opt-in. + +| key | type | default | meaning | +| --- | --- | --- | --- | +| `atom_selection1..4` | str | required | Center followed by the three ordered neighbor groups | +| one penalty block | dict | required | `harmonic: {target_chiral: ...}` or `flat-bottomed{,1,2}` with `target_chiral1` / `target_chiral2`, all in ų | +| `move` | `"all"` / int / list / comma-separated str | all four groups | Groups that receive the term's gradient | +| `weight` | float | `1.0` | Multiplier on the squared volume residual | +| `start_sigma` / `stop_sigma` | float | `+inf` / `-1` | Per-entry activation window; a step window may be used instead | + +There is no angular conversion; supplying `unit` raises an error. The target +below illustrates a signed volume of 2.5 ų. Choose its sign and magnitude from +the intended geometry in the same atom order, and replace the example names with +atoms present in the input. + +```yaml +chiral_restraints_config: + - atom_selection1: "chain B and name C1" + atom_selection2: "chain B and name C2" + atom_selection3: "chain B and name N1" + atom_selection4: "chain B and name O1" + harmonic: {target_chiral: 2.5} +``` + +For an allowed interval, use `flat-bottomed: {target_chiral1: 2.0, +target_chiral2: 3.0}`. Bounds must be ordered. A group may instead select fixed +reference atoms with `refN and ...`, using the shared `refs` definitions. Up to +three references are allowed, at least one group must come from the prediction, +and `move` may name only prediction groups. + +## `plane_restraints_config` (list) + +Select atoms explicitly and restrain their RMS distance from their own best-fit +plane. All atoms selected by an entry's 1–4 groups are pooled into **one plane**; +they are not replaced by group centroids. Separate entries define separate +planes. With pooled coordinates `x_i`, centroid `c`, and fitted unit normal `n`, +the measured flatness is + +```math +P = \sqrt{\frac{1}{N}\sum_i\big((x_i-c)\cdot n\big)^2}. +``` + +The normal is held fixed during differentiation. Targets are in **Å**. This +standalone term has its own activation window and does not require conformer +opt-in or automatic ring perception. + +| key | type | default | meaning | +| --- | --- | --- | --- | +| `atom_selection1..N` | str | `atom_selection1` required | `1 <= N <= 4`; numbering must be contiguous | +| one penalty block | dict | `harmonic: {target_plane: 0.0}` | Optional; `flat-bottomed{,1,2}` uses `target_plane1` / `target_plane2` | +| `move` | `"all"` / int / list / comma-separated str | all groups | Free groups; other selected atoms still define the plane but receive no gradient from this term | +| `weight` | float | `1.0` | Multiplier on the squared flatness residual | +| `start_sigma` / `stop_sigma` | float | `+inf` / `-1` | Per-entry activation window; a step window may be used instead | + +Do not supply `unit`: plane targets always use Å. The pooled selection must +contain at least three atoms. Three non-collinear points already define a plane, +so at least four are needed to measure nonplanarity. Avoid collinear fitting +atoms. For a phenylalanine ring at chain A residue 25, allow up to 0.05 Å RMS +departure from planarity with: + +```yaml +plane_restraints_config: + - atom_selection1: "chain A and resid 25 and name CG CD1 CD2 CE1 CE2 CZ" + flat-bottomed2: {target_plane2: 0.05} +``` + +An entry containing `refN and ...` instead fits its plane to the **reference +atoms only** and measures the prediction atoms' RMS distance from that plane. +The usual optional fit selections first place the reference in the prediction +frame. Reference coordinates and the reference fit are fixed for differentiation; +at least one prediction group and a non-collinear reference plane are required. + +```yaml +plane_restraints_config: + - atom_selection1: "chain C and name C1 C2 C3 C4" + atom_selection2: "ref1 and chain A and resid 25 and name CG CD1 CD2 CE1 CE2 CZ" + refs: + ref1: + ref_cif: reference.cif + atom_selection_target_fit: "chain A and name CA" + atom_selection_ref_fit: "chain A and name CA" + flat-bottomed2: {target_plane2: 0.1} + move: 1 +``` + +Supply `reference.cif` with the named atoms and at least three non-collinear fit +anchors. Omitting both fit selections uses the reference's original frame. + ## `conformer_restraints_config` (single dict) -Ligand conformer restraints use a single dictionary. Set `conformer_restraints: true` -on each ligand sequence/chain object, or `conformer_restraints=True` on an -ESMFold2 `LigandInput`. Chai uses a sidecar map keyed by ligand chain ID. +Conformer restraints use one shared dictionary and per-entity opt-ins. They apply +to ligands and to protein/DNA/RNA chains when the predictor adapter supplies the +required reference coordinates. Set `conformer_restraints: true` on each +participating sequence/chain object, or use the corresponding predictor-specific +opt-in: ESMFold2's `LigandInput` accepts `conformer_restraints=True`, and Chai uses +a sidecar map keyed by chain ID. See the predictor guide for its input layout. ```yaml conformer_restraints_config: {} # Enable the five default terms at weight 1. @@ -423,18 +594,19 @@ conformer_restraints_config: {} # Enable the five default terms at weight 1. An omitted or null block disables conformer restraints. An empty or partial mapping enables bond, angle, chiral, cistrans, and VdW at weight 1 on opted-in -ligands. Set an individual term's `weight` to zero to disable it. The shared -`start_sigma` and `stop_sigma` keys control all conformer terms together. +entities. **Plane and torsion default to weight 0**, including when their +sub-blocks are empty; give them a positive `weight` to enable them. Set a term's +`weight` to zero to disable it. The shared `start_sigma` and `stop_sigma` keys +control all conformer terms together; a shared step window is also supported. ### Reference geometry -Targets are measured from the predictor's ligand reference conformer after RDKit -UFF relaxation. The source molecular graph supplies tetrahedral chirality and -acyclic double-bond E/Z labels. If the relaxed coordinates disagree with these -labels, the toolkit retries stereo-aware ETKDG embedding and UFF relaxation with -up to four deterministic seeds. If UFF changes an initially correct conformer -and all retries fail, that original conformer is retained. If no reference with -the source stereochemistry can be recovered, setup raises an error. +For ligands, targets are measured from the predictor's reference conformer after +optional force-field relaxation. RDKit UFF is the default; the +[force-field setting](#ligand-force-field-selection) selects MMFF or disables +relaxation. The source molecular graph supplies tetrahedral chirality and +acyclic double-bond E/Z labels. Stereo validation and, when necessary, +regeneration happen before the target geometry is measured. Relaxation operates on a copy. It requires evidence of real bond orders (an aromatic or double bond); stereo validation also covers saturated chiral @@ -447,7 +619,66 @@ used to evaluate predictions. | `angle` | `weight` (1.0), `slack` (0.0 rad) | Bond angles toward reference values | | `chiral` | `weight` (1.0), `slack` (0.0 ų) | Signed chiral volumes toward reference values | | `cistrans` | `weight` (1.0), `slack` (0.0 rad) | Dihedrals about acyclic double bonds toward reference E/Z geometry | -| `vdw` | `weight` (1.0), `mode` (`"intermolecular"`), `scale` (0.75), `dmax` (5.0 Å), `max_neighbors` (32), `neighbor_skin` (2.0 Å) | Intermolecular repulsion based on elemental radius sums | +| `plane` | `weight` (0.0), `slack` (0.0 Å) | Flatness of automatically generated planar atom groups | +| `torsion` | `weight` (0.0), `slack` (0.0 rad) | Periodic chi, peptide omega, and supported sp²-axis torsions | +| `vdw` | `weight` (1.0), `mode` (`"intermolecular"`), `scale` (0.75), `dmax` (5.0 Å), `max_neighbors` (32), `neighbor_skin` (2.0 Å) | Repulsion within molecules, between molecules, or both; see the mode table below | + +### Ligand force-field selection + +`conformer_restraints_config.relax_force_field` is a mapping with one supported +key, `ligand`. It selects the preparation of ligand restraint targets, not the +optimizer used during denoising. Polymer reference coordinates and monomer-library +targets are unaffected. Each ligand still needs its usual conformer opt-in. + +| `relax_force_field.ligand` | target preparation | failure policy | +| --- | --- | --- | +| `uff` (default) | RDKit UFF relaxation when the graph has an aromatic or double bond | Unavailable or failed force-field preparation falls back to the unrelaxed reference; stereo failures follow the rules below | +| `mmff94` | RDKit MMFF94 relaxation | An explicit request raises on missing parameters, invalid chemistry, force-field failure, or unrecoverable stereochemistry | +| `mmff94s` | RDKit MMFF94s relaxation | Same strict failure policy as `mmff94` | +| `none` | Skip force-field relaxation | Keep a stereo-consistent reference unchanged; source-stereo repair can still regenerate it, without force-field relaxation, or raise if repair fails | + +Values are case-insensitive. Omitting `relax_force_field`, omitting its `ligand` +key, or setting `ligand: null` selects `uff`. Use the string `none` to disable +relaxation. The whole `relax_force_field` value must be a mapping; a scalar such +as `relax_force_field: mmff94` or a null mapping is rejected. Unknown keys and +values fail during configuration parsing, even if no ligand opts in. + +```yaml +conformer_restraints_config: + relax_force_field: + ligand: mmff94s + bond: {weight: 1.0} + angle: {weight: 1.0} +``` + +To skip force-field relaxation: + +```yaml +conformer_restraints_config: + relax_force_field: {ligand: none} +``` + +Normal relaxation requires at least one aromatic or double bond as evidence of +bond orders. UFF skips this step when neither is present. An explicit MMFF +request raises instead of silently skipping, including for a genuinely saturated +ligand. MMFF also raises when RDKit lacks parameters, for example for unsupported +metal-containing molecules; it does not automatically switch to UFF. + +Both UFF and MMFF run for at most 200 iterations. RDKit return codes 0 and 1 are +accepted; code 1 means the iteration limit was reached and does not certify +convergence. Preparation uses molecule copies so MMFF typing does not change +the aromatic flags or bond orders used to build restraints. Relaxation can +change the conformer's overall shape and the detected planar groups. + +When prepared coordinates disagree with source chirality or E/Z labels, the +toolkit tries up to four deterministic stereo-aware ETKDG embeddings, applying +the selected force field to each candidate unless `ligand: none`. If UFF +changes an initially stereo-consistent reference and every retry fails, that +original reference is retained. The corresponding MMFF failure raises. If the +input reference already disagrees with the source graph and regeneration cannot +repair it, setup raises. Setting `none` does not disable source-stereo validation, +and saturated chiral ligands are also checked when the adapter supplies the +source graph. ### Energy terms @@ -461,6 +692,8 @@ the target where the loss is zero. | `angle` | Bond angle in radians | Reference bond angle | | `chiral` | `(a1-a0) dot ((a2-a0) cross (a3-a0))` | Reference signed volume, without division by six | | `cistrans` | Dihedral in radians about an acyclic double bond | Reference dihedral; the deviation wraps to `[-pi, pi]` | +| `plane` | RMS distance from the group's best-fit plane | Zero; `slack` permits a nonzero RMS departure | +| `torsion` | Four-atom dihedral in radians | Reference/dictionary target with its specified periodicity | Cumulated double bonds, such as those in allenes, are excluded from cistrans restraints because the linear endpoint does not define the required dihedral. @@ -470,10 +703,138 @@ With nonzero slack the residual is `max(2*sin((pi-theta)/2) - 2*sin(slack/2), 0)`. Bond norms in the cosine denominator have a 0.02 Å floor. Group-angle and custom-angle terms are unchanged. -### Intermolecular van der Waals repulsion +### Plane and torsion terms + +Conformer `plane` automatically selects aromatic/conjugated rings and non-ring +sp² groups that are planar in the prepared reference. Polymer and monomer-library +paths also supply residue-local and inter-residue planar groups. This differs +from `plane_restraints_config`, where the user selects the atoms explicitly. +Both measure the same best-fit-plane RMS departure. A conformer plane's penalty +is `N * weight * max(0, P - slack)**2` for a group of `N` atoms, before optional +ESD normalization; a standalone plane does not apply that atom-count factor. + +Conformer `torsion` is separate from `cistrans`: -The default `vdw.mode` is `intermolecular`. In a protein–ligand system, this -penalizes ligand contacts with the protein using +- `cistrans` preserves ligand acyclic double-bond E/Z geometry with period 1. +- `torsion` includes ligand conjugated single sp²–sp² axes, protein side-chain + chi angles, peptide omega, and supported polymer sp² axes. Ligand single + sp²–sp² axes use period 2. Polymer periods come from the dictionary or the + reference-based fallback. +- This is not a complete protein phi/psi or nucleic-acid backbone torsion model. + +For period `p`, the signed deviation is `wrap(p * (phi - phi0)) / p`. +The squared penalty then applies the symmetric `torsion.slack` interval in +**radians**. A period of 2 admits two equivalent wells per full turn. Peptide +cis/trans alternatives are selected separately for each sample from the +coordinates at the start of each minimization and remain fixed during that +invocation; the next invocation selects again. + +Enable the optional terms explicitly: + +```yaml +conformer_restraints_config: + plane: {weight: 1.0, slack: 0.02} + torsion: {weight: 1.0, slack: 0.0} +``` + +The five default terms remain enabled in this example. Active cistrans/torsion +quartets suppress conformer plane groups containing all four of their atoms, +with peptide-state conditions where needed. Consequently, enabling torsions can +reduce the number of generated planes. It does not remove standalone plane +entries or VdW topology exclusions. + +### Polymer targets and `monomer_library` + +Opted-in protein, DNA, and RNA chains can use conformer restraints on local +geometry and residue links. The adapter must provide atom identities, reference +coordinates, and the chain opt-in. Reference coordinates are residue-local: +without a dictionary, intra-residue targets come from those coordinates, while +peptide/phosphodiester link geometry uses built-in targets. Ligand force-field +relaxation does not relax polymer references. + +Set `conformer_restraints_config.monomer_library` to use the CCP4 monomer +dictionary for covered polymer residues and links. Dictionary targets replace +the corresponding reference-derived terms instead of adding a second copy. +The enabled terms can include bond lengths, angles, signed chirality, planar +groups, and the supported torsion subset described above. Plane and torsion +still require positive weights; enabling the library does not enable them. + +| `monomer_library` value | behavior | +| --- | --- | +| omitted, `null`, or `false` | Use reference/built-in targets; no library download | +| `true` | Use an automatically cached monomer library; missing geometry defaults to `fallback` | +| path string, e.g. `monomers` | Read that local library directory; no download | +| `{path: monomers, on_missing: error}` | Local library with an explicit missing-geometry policy | +| `{on_missing: error}` or `{}` | Use the automatic cache; `path` is optional | + +The mapping accepts only `path` and `on_missing`. `path`, when present, must be a +nonempty string. `on_missing` is `fallback` by default: missing dictionary +geometry is logged and available reference/built-in fallback is retained. +`on_missing: error` raises when the library loader encounters missing required +entries or geometry. + +Automatic acquisition happens only when polymer setup needs the library, not +during configuration parsing. It requires Git and network access on first use, +caches a snapshot of `MonomerLibrary/monomers` under the user's configuration +directory, and reuses it offline without automatic updates. The source revision +is logged. An explicit path always uses the supplied local directory. + +For the automatic cache: + +```yaml +conformer_restraints_config: + monomer_library: true + plane: {weight: 1.0} + torsion: {weight: 1.0} +``` + +For a locally supplied library, with optional uncertainty normalization: + +```yaml +conformer_restraints_config: + monomer_library: + path: monomers + on_missing: error + use_esd: true + plane: {weight: 1.0} + torsion: {weight: 1.0} +``` + +Both examples also require the predictor-specific opt-in on each intended +polymer chain. They do not turn on restraints for every chain automatically. + +`use_esd` is a strict boolean, default **false**, and is independent of target +selection. With `false`, the configured weights multiply squared residuals +without inverse-variance scaling. With `true`, conformer weights become +`weight / ESD**2` using dictionary ESDs where available and reference/fallback +ESDs elsewhere. This applies to all seven conformer terms, including VdW +(ESD 0.2 Å), but not to standalone or custom restraints. Plane atom-count +factors remain in effect. ESD is an estimated standard deviation, **not slack**; +it does not create a zero-penalty interval or change targets or activation windows. +Nonpositive dictionary ESDs disable the corresponding energy rows while +retaining topology exclusions. Missing geometry follows `on_missing`. + +Dictionary torsions include protein `chi*`, peptide `omega`, and `sp2_sp2*` +records, not every torsion in a component dictionary. Supported peptide +cis/trans link variants also supply their associated bond, angle, and plane +targets. Without dictionary coverage, modeled standard-residue atoms can use +the reference-based chi/omega/sp² fallback; unknown residues or missing torsion +atoms are logged and skipped. + + + +### Van der Waals repulsion + +VdW is a conformer term, so it requires a conformer block and entity opt-in. +`vdw.mode` selects which nonbonded contacts contribute: + +| mode | contacts | +| --- | --- | +| `intermolecular` (default) | Between different molecules, including ligand–protein, ligand–nucleic-acid, and ligand–ligand contacts | +| `intramolecular` | Within each opted-in ligand or polymer chain | +| `both` | Both categories | + +With the default `use_esd: false`, eligible pairs contribute ```math E = w \sum_{(i,j)} \min(0, d_{ij} - \mathrm{scale}(r_i + r_j))^2. @@ -483,24 +844,39 @@ The radii are RDKit elemental values from `Chem.GetPeriodicTable().GetRvdw(atomic_number)`. They are not adjusted for hydrogen bonds or ionic environments. Covalent 1–2, 1–3, and 1–4 pairs are excluded using topology, even when the corresponding geometry energies are -disabled. The default contact threshold is `0.75 * (r_i + r_j)`. +disabled. The default contact threshold is `0.75 * (r_i + r_j)`; this is a +quadratic penalty threshold, not a guarantee that every final distance exceeds +it. `use_esd: true` additionally scales each squared residual by `1 / 0.2**2`. ```yaml restraints_config: conformer_restraints_config: vdw: - mode: intermolecular + mode: both weight: 1.0 scale: 0.75 ``` -### Dynamic intermolecular neighbor lists +Use `mode: intramolecular` to include only within-molecule contacts. Other +conformer terms remain enabled unless their weights are set to zero. + +Intramolecular ligand pairs and pairs between restrained ligands are stored +explicitly. Contacts against atoms outside the active set use a fixed +background; contacts involving restrained polymer atoms can also have two +moving endpoints. Thus `intermolecular` includes other restrained ligands as +well as fixed protein atoms. The former name `ligand_protein` is rejected. + + + +### Dynamic VdW neighbor lists Every objective/gradient evaluation checks the neighbor cache against its own -trial coordinates, including rejected line-search trials. The protein background +trial coordinates, including rejected line-search trials. The inactive background is held fixed for one minimization invocation. The search radius is `max(dmax, max_contact + neighbor_skin)`. With a fixed background, the cache is -rebuilt when the maximum ligand displacement exceeds `neighbor_skin`. +rebuilt when the maximum moving-atom displacement exceeds `neighbor_skin`. +For two moving endpoints, the threshold is half the skin. Static ligand-pair +terms do not use this neighbor cache. `max_neighbors` controls sparse buffer capacity. Rows that exceed the capacity use complete pair sums in bounded chunks, so no eligible contacts are discarded. @@ -510,7 +886,7 @@ objective. Inactive conformer windows skip list construction. CG, L-BFGS, and energy diagnostics evaluate the same dynamic VdW objective. Rebuilds preserve the objective, conjugate direction, and counters. Exact or near-exact overlaps use a deterministic pair-dependent separation direction in -the gradient. See the [solver specification](SPEC.md#nonlinear-conjugate-gradient). +the gradient. ## `rmsd_restraints_config` (list) @@ -561,31 +937,138 @@ superpose on the backbone but measure over a pocket. Under `pairing: align`, res ## `custom_restraints_config` (list) -### Formula definition + + +### Definition paths Write a differentiable energy as a mathematical formula over named atom -selections. The same expression runs on Torch and JAX. +selections, or supply a Python function using the same geometry vocabulary. +Each entry must provide exactly one of `energy`, `fn`, or `use`. Formula and +function paths both produce Torch/JAX energy closures. -Each entry's energy (× `weight`) is added to the CG objective, gated by the usual -`start_sigma` / `stop_sigma` window. +Each entry's energy (× `weight`) is added to the optimizer objective, gated by +a sigma window or a step window. | key | type | default | meaning | |---|---|---|---| -| `energy` | str | — | the required formula (DSL) | +| `energy` | str | — | Formula in the expression DSL; mutually exclusive with `fn` and `use` | +| `fn` | callable | — | Python `energy(ctx)` function, supplied in a Python dict; mutually exclusive with `energy` and `use` | +| `use` | str | — | Name registered with `@custom_restraint("name")` in the current Python process; mutually exclusive with `energy` and `fn` | | `selections` | dict | `{}` | `name -> selection string`; use `refN and ` for a group selected from `refs.refN` | | `refs` | dict | `{}` | `refN -> {ref_pdb`\|`ref_cif, atom_selection_ref_fit, atom_selection_target_fit, pairing, best_effort}`; names are reserved as `ref1`, `ref2`, ... | | `move` | `"all"` / `"both"` / str / list[str] | `"all"` | prediction selection name(s) that receive this restraint's gradient. Omitted/`all`/`both` moves every prediction selection. Reference-backed selections are always fixed and cannot be named | | `weight` | float | `1.0` | scales the whole energy | | `name` | str | `"custom"` | label shown in the `finalize` per-term log | | `start_sigma` / `stop_sigma` | float | `+inf` / `-1` | sigma gating (as everywhere) | +| `start_step` / `stop_step` | float | `-inf` / `+inf` | inclusive diffusion-step window; cannot be combined with explicit sigma-window keys | + +### Python functions and registration + +A Python function receives a context `ctx`. Use `ctx.distance("A", "B")`, +`ctx.angle(...)`, `ctx.harmonic(...)`, and the other documented vocabulary as +methods. Selection arguments are strings: an alias from `selections`, or a raw +selection such as `"chain A and resid 1"`. The usual `refs`, `move`, `weight`, +and activation windows apply to functions as well as formulas. Return the +unweighted energy; the closure sums any batch dimensions and applies `weight`. + +The function runs once with a discovery context during setup to identify its +selections, then repeatedly during energy and gradient evaluation. Keep it +free of side effects and use `ctx` operations for coordinate-dependent work. +Python `if` on a computed geometry, `float(...)`, NumPy conversion, or +backend-specific tensor operations can break selection discovery or tracing. +Use `ctx.where(condition, a, b)` for an elementwise choice; both arguments are +evaluated, so both must be numerically defined. + +The following alternatives define the same 5 Å centroid-distance target. +`adapter` is the predictor's atom adapter; after setup, use the normal +[`minimize`/`get_minimizer` lifecycle](../README.md#python-api). + +Pass a callable directly in a Python configuration: + +```python +from rgi_toolkit import CombinedRestraints + + +def pull5(ctx): + return (ctx.distance("A", "B") - 5.0) ** 2 + + +restraints_config = { + "custom_restraints_config": [ + { + "name": "pull5", + "fn": pull5, + "selections": {"A": "chain A and resid 1", "B": "chain A and resid 2"}, + "weight": 1.0, + } + ] +} +restraints = CombinedRestraints() +restraints.setup(adapter, config=restraints_config) +``` + +For reuse from YAML/JSON, register the function in Python: + +```python +from rgi_toolkit import custom_restraint + + +@custom_restraint("pull5") +def pull5(ctx): + return (ctx.distance("A", "B") - 5.0) ** 2 +``` + +Then select it by name: + +```yaml +custom_restraints_config: + - name: pull5 + use: pull5 + selections: + A: chain A and resid 1 + B: chain A and resid 2 + weight: 1.0 +``` + +Import the module containing the decorated function before the configuration is +parsed in the same process. `use` looks up a registered name; it does not import +a module or load a Python file. A predictor CLI therefore needs application code +that performs registration. An unknown name raises during parsing. Registration +is process-wide and registering the same name again replaces its function; +resolved restraint state remains local to each `CombinedRestraints` instance. +`fn` accepts a callable object in a Python dict, not a function name serialized +as YAML/JSON. + +Alternatively, add the `pull5` function above directly to an instance **before +`setup`**: + +```python +restraints = CombinedRestraints() +restraints.add_custom( + fn=pull5, + name="pull5", + selections={"A": "chain A and resid 1", "B": "chain A and resid 2"}, + weight=1.0, +) +restraints.setup(adapter, config={}) +``` + +`add_custom()` accepts exactly one of `fn=` or `energy=`; for a formula, replace +`fn=pull5` with `energy="(distance(A,B) - 5.0)**2"`. It also accepts `selections`, +`refs`, `move`, `weight`, `name`, and the four window keys from the table above, +with the same defaults. It returns the instance for chaining. Entries added +this way persist across later `setup` calls, including calls with a new config, +and are merged with configured custom entries without being duplicated by +setup. Add each restraint once; repeated `add_custom` calls add separate terms. ### Evaluation model Each entry compiles to a closure `energy(active_coords) → scalar`. A selection name in a formula (`A`) is resolved from the entry's `selections` map to that group's atoms; a string -literal (`"chain A"`) is a raw selection. Selection names resolve to their group **centroids** at -setup (a dry run records which names the energy touches). The formula must reduce to a **scalar** (a -`sum` over any batch dimension). `move` applies stop-gradient to every unlisted prediction +literal (`"chain A"`) is a raw selection. A setup dry run records the selections used. +Each geometry function then consumes either the group's centroid or its atom-coordinate +block, as specified below. The closure sums the formula result, including any batch +dimensions, to obtain a scalar energy. `move` applies stop-gradient to every unlisted prediction selection for this custom term; another restraint may still move the same atoms. The formula is parsed safely — no `eval`, and `import` / attribute access / @@ -598,7 +1081,8 @@ energy), and **math** (elementwise / reduction helpers) — plus operators. #### Geometry -Geometry functions operate on selection **centroids**; angular results are in **radians** (note: the +Distance, angle, dihedral, improper, and chiral functions operate on selection +**centroids**. Other functions can use whole coordinate blocks. Angular results are in **radians** (note: the built-in `angle` / `dihedral` configs take *degrees*, but a custom formula is in radians). $\lVert\cdot\rVert$ is the Euclidean norm: @@ -608,14 +1092,27 @@ $\lVert\cdot\rVert$ is the Euclidean norm: | `distance(A,B)` | scalar | $\lVert c_A - c_B \rVert$ | a separation between two groups; a **difference of two distances** encodes symmetry / equidistance | | `angle(A,B,C)` | scalar (rad) | $`\arccos\big( (c_A - c_B)\cdot(c_C - c_B) / (\lVert c_A - c_B \rVert\,\lVert c_C - c_B \rVert) \big)`$, vertex $B$ | the bend of three groups about the vertex $B$ | | `dihedral(A,B,C,D)` | scalar (rad) | torsion about the B–C centroid axis, range $\pm\pi$ | the twist / handedness across four groups — a **periodic** quantity: wrap its deviation, see below | +| `improper(A,B,C,D)` | scalar (rad) | same ordered signed-angle calculation as `dihedral(A,B,C,D)` | an improper-angle formula with an explicit quartet order; wrap deviations | +| `chiral(A,B,C,D)` | scalar (ų) | $(c_B-c_A)\cdot((c_C-c_A)\times(c_D-c_A))$ | constrain signed volume around A; no division by six or automatic R/S assignment | +| `rg(A)` | scalar (Å) | $\sqrt{\frac{1}{N}\sum_i\lVert x_i-c_A\rVert^2}$ | radius of gyration of A's selected atoms, with equal atom weights rather than mass weights | +| `plane(A)` | scalar (Å) | RMS distance of A's atoms from their own best-fit plane | constrain an atom group's flatness | +| `plane(A,B)` | scalar (Å) | RMS distance of A's atoms from the best-fit plane of B | pull A onto a plane defined by B; unlike a standalone pooled plane, A does not participate in fitting B's plane | | `norm(v)` | scalar | $\lVert v \rVert$ | the length of a vector you built, e.g. `centroid(A) - centroid(B)` | | `dot(u,v)` | scalar | $u \cdot v$ | projections and cosine-like terms | | `coords(A)` | block $(k,3)$ | $A$'s atom coordinates | feed a bare selection into arithmetic with `kabsch` output (a bare name alone is a *selection identifier*, not coordinates) | | `kabsch(A,B)` | block $(k,3)$ | $A$ rigid-body-superposed onto $B$ (Kabsch) | align two moving groups, then measure the leftover per-atom deviation — see **Reference-backed selections** | | `rmsd(A,B)` | scalar | superposed RMSD of prediction selection `A` vs reference-backed selection `B` | pull a group onto an external reference; `B` must map to `refN and ` — see **Reference-backed selections** | -Most geometry consumes selection **centroids**; `coords` / `kabsch` instead flow a whole -**$(k,3)$ coordinate block**, so they compose: `centroid(kabsch(A,B))`, `norm(kabsch(A,B) - coords(B))`. +`rg` and `plane` measure whole selected atom blocks. `coords` / `kabsch` return a +**$(k,3)$ coordinate block**, so functions compose: `centroid(kabsch(A,B))`, +`norm(kabsch(A,B) - coords(B))`. These formulas use the shared geometry primitives +and their small numerical regularizers. + +`plane` differentiates with its fitted normal held fixed. In `plane(A,B)`, B's +centroid can still receive a gradient if B is a free prediction selection; use +`move: A` to pin B for that entry, or use a reference-backed B. Three non-collinear +atoms define a plane; `plane(A)` needs at least four atoms to detect departure +from coplanarity. The two-argument form does not require equal atom counts. #### Reference-backed selections and superposition A reference-backed selection is declared in the ordinary `selections` map: @@ -640,7 +1137,8 @@ stop-gradient values: they act as fixed landmarks and do not pull the fit anchor selections are omitted, the reference is used in its own coordinate frame. Reference-backed selections work with the normal geometry vocabulary: `distance(A,B)`, -`angle(A,B,C)`, `dihedral(A,B,C,D)`, `centroid(A)`, `coords(A)`, and `kabsch(A,B)`. At least one +`angle(A,B,C)`, `dihedral(A,B,C,D)`, `improper(A,B,C,D)`, `chiral(A,B,C,D)`, +`centroid(A)`, `rg(A)`, `plane(A)` / `plane(A,B)`, `coords(A)`, and `kabsch(A,B)`. At least one selection in the custom entry must come from the prediction; an all-reference expression is a constant and raises. @@ -656,14 +1154,14 @@ numpy finite-difference through the SVD, matching the built-in RMSD restraint. #### Degenerate geometry -`angle` and `dihedral` are ill-defined when the centroids collapse — +`angle`, `dihedral`, and `improper` are ill-defined when the centroids collapse — coincident centroids, a collinear A–B–C for `angle`, or a `dihedral` whose central axis runs parallel to an arm. The value stays finite but its gradient is near-zero, so the term cannot push the structure; choose groups whose centroids are distinct and non-collinear. (`distance` has no such caveat.) #### Dihedral periodicity -Wrap every `dihedral` deviation. These angles are periodic ($\phi$ and $\phi + 2\pi$ +Wrap every `dihedral` or `improper` deviation. These angles are periodic ($\phi$ and $\phi + 2\pi$ are the same geometry), so a penalty on its **deviation** must fold that deviation into $[-\pi, \pi]$ first. Write `wrap(dihedral(A,B,C,D) - t)**2` (harmonic), **not** the naïve `harmonic(dihedral(A,B,C,D), t)`: the naïve form counts $\phi = +179^\circ$ against $t = -179^\circ$ @@ -676,6 +1174,9 @@ flat-bottomed dihedral cannot). Note `t` / `centre` are in **radians** (a custom conversion, unlike the built-in `dihedral_restraints_config`). (`angle` is bounded to $[0, \pi]$ by `arccos`, so it needs no wrap.) +The same rule gives `wrap(improper(A,B,C,D) - t)**2`. `chiral` is a signed +volume and is not periodic; apply its target or bounds directly in ų. + #### Penalties These are convenience squared penalties; you may also write the algebra directly. Use @@ -718,6 +1219,9 @@ the branch that happens to be live. ### Examples +The examples below are independent patterns. Use selections present in your +input and targets appropriate to the intended geometry. + ```yaml custom_restraints_config: # symmetry: keep two inter-domain distances equal @@ -756,3 +1260,45 @@ custom_restraints_config: ref1: {ref_cif: "state1.cif", pairing: align} ref2: {ref_pdb: "state2.pdb", pairing: align} ``` + +The additional geometry functions can be used as follows. The phenyl ring +example assumes phenylalanine at chain A residue 25; the chiral target uses the +same illustrative atom order and volume as the standalone chiral example. + +```yaml +custom_restraints_config: + - name: compactness + energy: "harmonic(rg(A), 12.0)" + selections: + A: "chain A and name CA" + - name: ring_flatness + energy: "flat_bottomed2(plane(R), 0.05)" + selections: + R: "chain A and resid 25 and name CG CD1 CD2 CE1 CE2 CZ" + - name: onto_fixed_plane + energy: "harmonic(plane(L, P), 0.0)" + selections: + L: "chain C and name C1 C2 C3 C4" + P: "chain A and resid 25 and name CG CD1 CD2 CE1 CE2 CZ" + move: L + - name: peptide_improper + energy: "wrap(improper(A, B, C, D) - 3.141592653589793)**2" + selections: + A: "chain A and resid 40 and name CA" + B: "chain A and resid 40 and name C" + C: "chain A and resid 40 and name O" + D: "chain A and resid 41 and name N" + - name: signed_volume + energy: "harmonic(chiral(A, B, C, D), 2.5)" + selections: + A: "chain B and name C1" + B: "chain B and name C2" + C: "chain B and name N1" + D: "chain B and name O1" +``` + +The functions return measured geometry, not an energy on their own. Use an +appropriate penalty, weight, and activation window. For example, `rg(A)` alone +minimizes size, whereas `harmonic(rg(A), 12.0)` targets a radius of 12 Å. Likewise, +`chiral(A,B,C,D)` alone is not a restraint toward a chosen handedness; its sign +and magnitude need an explicit target or bound. diff --git a/docs/esmfold2_restr.md b/docs/esmfold2_restr.md index 495a6ec..5e668b2 100644 --- a/docs/esmfold2_restr.md +++ b/docs/esmfold2_restr.md @@ -35,18 +35,6 @@ cd esm_restr pixi install ``` -### Co-development - -Clone `RGI-toolkit` alongside `esm_restr`, then install both editably in a uv -environment. The native ESM source contains the sampling hook, so edits take -effect directly: - -```bash -uv venv --python 3.12 -uv pip install -e . -e ../RGI-toolkit -uv run --no-project python restr_example.py -``` - ## Configuration ESMFold2's API is **Pythonic**: `restraints_config` is a plain **Python dict** passed to diff --git a/docs/foundry_restr.md b/docs/foundry_restr.md index c532cca..4e45128 100644 --- a/docs/foundry_restr.md +++ b/docs/foundry_restr.md @@ -18,9 +18,6 @@ uv pip install --python .venv/bin/python --torch-backend cu128 \ uv run --no-project --python .venv/bin/python foundry install rf3 ``` -> For co-development of the engine, install a sibling checkout in a separate step: -> `uv pip install --python .venv/bin/python -e ../RGI-toolkit`. - The fork installs the shared RGI engine. RF3 supplies PyTorch, so no separate RGI backend extra is needed. `constraints-rf3.txt` pins the validated Linux CUDA dependencies. Inference requires the RF3 checkpoint and a CUDA GPU; use your @@ -200,6 +197,21 @@ adds no restraints. Each job receives its own configuration and every diffusion sample is optimized independently. Set `skip_existing=false` when comparing configurations in an output directory that already contains predictions. +## Runnable examples + +The toolkit also provides the same individual settings used by the other models: + +| Example | Input | Run from the RGI-toolkit checkout | +|---|---|---| +| QBP distance, 25.0 Å | [JSON](../examples/distance/rf3/qbp_25.00.json) | `bash examples/distance/rf3/run.sh` | +| ADK angle, 72.85° | [JSON](../examples/angle/rf3/adk_72.85.json) | `bash examples/angle/rf3/run.sh` | +| QBP dual-reference RMSD, 2.65/2.65 Å | [JSON](../examples/rmsd/rf3/qbp_2.65.json) | `bash examples/rmsd/rf3/run.sh` | +| DgoT distance difference, 0.8 Å | [JSON](../examples/custom/dist-diff/rf3/dgot_0.80.json) | `bash examples/custom/dist-diff/rf3/run.sh` | +| MDM2–p53 dissociation, 13.0 Å | [Input and MSA setup](../examples/ligand-dissociation/README.md) | `bash examples/ligand-dissociation/rf3/run.sh` | + +These runners request one sample with 50 diffusion steps and seed 0. +The dissociation inputs supply a separate unpaired A3M for each protein chain. + ## Verify results With `verbose: true`, the setup log prints `built spec: n_active=.. bonds=.. angles=.. diff --git a/docs/opendde_restr.md b/docs/opendde_restr.md index 6f281bb..53f14c3 100644 --- a/docs/opendde_restr.md +++ b/docs/opendde_restr.md @@ -18,9 +18,6 @@ uv venv --python 3.12 .venv && source .venv/bin/activate uv pip install --torch-backend cu126 -e ".[gpu]" # also pulls rgi_toolkit (declared in pyproject) ``` -> For co-development of the engine, override the declared dependency with a local editable -> checkout in a SEPARATE step: `uv pip install -e ../RGI-toolkit` (sibling clone). - OpenDDE also needs its checkpoint and common runtime data under `OPENDDE_ROOT_DIR`; follow the fork's `docs/inference_instructions.md` or run `scripts/download_opendde_data.sh`. diff --git a/docs/openfold-3_restr.md b/docs/openfold-3_restr.md index 0d7af07..63d9fce 100644 --- a/docs/openfold-3_restr.md +++ b/docs/openfold-3_restr.md @@ -20,9 +20,6 @@ printf '\n\n\nno\n' | pixi run -e openfold3-cuda12 setup_openfold # fetch mode export OPENFOLD_CACHE="$HOME/.openfold3" ``` -> For co-development of the engine, override with a local editable checkout AFTER pixi install: -> `pixi run -e openfold3-cuda12 python -m pip install -e ../RGI-toolkit` (sibling clone). - ## Configuration OpenFold reads RGI from a **`restraints_config` field per query** in the input JSON diff --git a/docs/protenix_restr.md b/docs/protenix_restr.md index d8505e3..97eb52b 100644 --- a/docs/protenix_restr.md +++ b/docs/protenix_restr.md @@ -16,9 +16,6 @@ uv venv && source .venv/bin/activate # Python 3.11+ uv pip install -e . # also pulls the rgi_toolkit engine (declared in requirements.txt) ``` -> For co-development of the engine, override the pinned dependency with a local editable -> checkout in a SEPARATE step: `uv pip install -e ../RGI-toolkit` (sibling clone). - > **Run protenix on sm_89 (e.g. RTX 4090), NOT on Blackwell (sm_120).** On Blackwell its > cuequivariance fused kernels **silently** emit all-NaN coordinates (no crash, exit 0) even for a > bare fold with no restraints. A NaN output is almost always this, not the restraint; confirm by diff --git a/docs/testing.md b/docs/testing.md deleted file mode 100644 index 5b41407..0000000 --- a/docs/testing.md +++ /dev/null @@ -1,80 +0,0 @@ -# Testing - -Prepare the CPU development environment with: - -```bash -uv sync --extra torch --extra jax -``` - -The test tasks use `uv run --active --no-sync`: an activated virtual environment -takes precedence over the project environment, and running a test does not change -installed dependencies. Commands are run from the repository root. On a cluster, -run tests in an appropriate compute allocation. - -| Command | Purpose | Coverage | -|---|---|---| -| `task test-ci` | Short CI validation, targeting about one minute of test execution | Important numerical contracts and small representative integration cases | -| `task test-local` | Comprehensive local CPU validation | Every non-GPU test, including real Torch compilation | -| `task test-gpu` | Comprehensive GPU validation | Every test marked `gpu`; requires a CUDA-enabled environment | -| `task test` | Alias for `task test-local` | Complete CPU validation | - -## Short CI selection - -GitHub Actions and `task test-ci` execute the same explicit selection in -[`tests/ci.txt`](../tests/ci.txt), using pytest's -[argument-file support](https://docs.pytest.org/en/9.0.x/how-to/usage.html#read-arguments-from-file). -Missing or renamed selected tests cause an error rather than silently reducing -coverage. The selection includes: - -- Configuration validation, defaults, selection, reference pairing, adapter atom - order and chemistry, restraint construction, and activation windows. -- NumPy/PyTorch/JAX energy agreement, autodiff versus finite differences, - Kabsch/RMSD behavior, and fixed versus moving atom groups. -- CG line-search agreement with SciPy, nonfinite-gradient handling, rejected - steps, and preservation of the last accepted coordinates. -- VdW topology exclusions, dense versus neighbor-list energies and gradients, - overflow, exact overlaps, and contact-cache validity. -- Small public-API minimizations for distance, angle, dihedral, RMSD, - ligand conformer stereochemistry, custom energies, and intermolecular VdW. - These retain independent SciPy/geometry assertions and selected JAX execution. -- CPU compilation defaults, explicit opt-out, and simulated compiler failure - fallback without changing CUDA failure state. - -Torch compilation is disabled for CI execution to avoid repeated compiler startup; -the failure-path test injects a failing artifact and does not invoke a compiler. -JAX numerical and selected JIT/minimization checks still run. Real Torch compilation -is verified locally. CI uses two file-grouped workers. CPU tasks enable JAX float64 -support explicitly so available precision does not depend on test order. -This is a curated subset, not a replacement for full validation. - -## Comprehensive local validation - -`task test-local` runs the complete CPU suite in two stages: - -1. All ordinary numerical regressions, exhaustive solver/parameter combinations, - large atom groups, and public-API end-to-end tests, using two file-grouped workers. -2. All `cpu_compile` tests with compilation enabled, including compiled energy and - gradient parity, dynamic VdW, custom restraints, CG/L-BFGS, and dtype changes. - -The two stages together include every CI case. No existing regression is deleted or weakened. -Actual compiler checks require a C++ compiler and Python development headers; -inspect skips before treating local validation as complete. - -For GPU tests, activate an existing predictor environment with CUDA-enabled -PyTorch and JAX plus the test dependencies, then run `task test-gpu` in a GPU -allocation. The development lockfile installs CPU-only PyTorch, so it is not a -GPU test environment. The task does not sync or replace an activated environment's -framework packages. GPU tests are additional to the complete CPU suite. -All compiler-heavy checks remain outside short CI. - -## Maintaining coverage - -Run `task test-local` before delivering code changes, and `task test-gpu` when GPU -behavior changes. A correctness fix should have a small representative CI regression -where practical, with broader combinations retained locally. Keep assertions and -tolerances unchanged when selecting cases. Inspect `--durations` output and keep -compiler-heavy or large-system sweeps out of the short selection. Tests that need -real CPU compilation carry `pytest.mark.cpu_compile`. - -Additional pytest options can follow `--`, for example -`task test-ci -- --durations=20` or `task test-gpu -- --collect-only -q`. diff --git a/examples/README.md b/examples/README.md index 6fcc461..8cddacb 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,8 +1,9 @@ # rgi_toolkit RGI examples -Examples of distance, angle, RMSD, and custom restraints for protein structures. -Each `//` directory contains one restraint setting and a `run.sh` for -one prediction. Each input includes its restraint settings inline. +Examples of distance, angle, RMSD, custom, and ligand-dissociation restraints. +Inputs are organized as `//`, with a `run.sh` for each model. +Each input includes its restraint settings inline. Each example type +contains one setting per model. | Directory | System | Representative restraint | |---|---|---| @@ -10,14 +11,17 @@ one prediction. Each input includes its restraint settings inline. | `angle/` | ADK, 214 residues | NMP–CORE–LID centroid angle of 72.85° | | `rmsd/` | QBP | Open/closed reference RMSD targets of 2.65/2.65 Å on 220 common Cα atoms | | `custom/dist-diff/` | DgoT, 419 residues | ΔD = D_in − D_out = 0.8 Å | +| [`ligand-dissociation/`](ligand-dissociation/README.md) | MDM2–p53 | Chain-centroid distance of 13.0 Å | -The seven predictors covered here are `boltz-2`, `protenix-v2`, `alphafold3`, -`openfold-3`, `chai`, `esmfold2`, and `opendde`. +The nine predictors covered here are `boltz-2`, `protenix-v2`, `alphafold3`, +`openfold-3`, `chai`, `esmfold2`, `opendde`, `rf3`, and `bioemu2`. ## Run ```bash bash examples/distance/boltz-2/run.sh +bash examples/distance/rf3/run.sh +bash examples/distance/bioemu2/run.sh # ESMFold2 requires the full ColabFold A3M for the selected protein. MSA_A3M=inputs/qbp.a3m bash examples/rmsd/esmfold2/run.sh @@ -31,7 +35,9 @@ sm_89 GPU in this integration. All runners request one diffusion sample. OpenFold3 and Chai also request one model/trunk sample. The restraint minimizer is CG with the default strong-Wolfe -line search and `gtol=1e-5`; `max_iter` is 1000 for RMSD and 100 otherwise. +line search and `gtol=1e-5`; `max_iter` is 1000 for RMSD and ligand +dissociation, and 100 otherwise. RF3 uses 50 diffusion steps; BioEmu2 uses +200 EDM steps with structure conditioning. ## Restraint settings @@ -67,7 +73,9 @@ For comparisons across predictors, use the same full ColabFold A3M for each protein. Reproducing a prediction also requires the same model checkpoint and seed. -Boltz-2, Protenix-v2, OpenFold3, and Chai use an MSA server. AlphaFold3 uses its +In the distance, angle, RMSD, and custom examples, Boltz-2, Protenix-v2, +OpenFold3, Chai, and BioEmu2 use an MSA server. RF3 uses the supplied sequence; +add `msa_paths` to its input to provide alignments. AlphaFold3 uses its local data pipeline and requires `MODEL_DIR` and `DB_DIR`. ESMFold2 reads the full A3M from `MSA_A3M`, checks its query against the example sequence, and uses `msa_max_depth=1024` and `msa_column_mask_rate=0.1`, with 20 recurrent @@ -83,12 +91,18 @@ To reuse a precomputed MSA, provide it through the predictor's native input: | OpenFold3 | Chain `main_msa_file_paths`; use `--use-msa-server false` | | Chai | Aligned Parquet files through `--msa-directory`; omit `--use-msa-server` | | ESMFold2 | `MSA_A3M` | +| RF3 | Job-level `msa_paths` mapping from chain IDs to A3M paths | +| BioEmu2 | `get_msa(system, {chain_id: Path(...)})` passed to `EmuSession` | -OpenDDE disables external MSA and template searches in its examples. +OpenDDE disables external MSA and template searches in the first four +example types. The [ligand-dissociation examples](ligand-dissociation/README.md) +use the same two supplied, unpaired A3Ms for all nine models, with no MSA +search. Chai converts those files to its aligned-Parquet format. ## Validation -All protein selections are qualified with `chain A`. `resid` means a per-chain +Protein selections include explicit chain IDs: `chain A` for the single-chain +systems, and `chain A` / `chain B` for MDM2–p53. `resid` means a per-chain 1-based ordinal, not the reference structure's author residue number. The [configuration guide](../docs/config.md) describes the schema and selection DSL. diff --git a/examples/angle/bioemu2/adk_72.85.yaml b/examples/angle/bioemu2/adk_72.85.yaml new file mode 100644 index 0000000..8f5d5b6 --- /dev/null +++ b/examples/angle/bioemu2/adk_72.85.yaml @@ -0,0 +1,16 @@ +entities: +- entity_type: protein + sequence: MRIILLGAPGAGKGTQAQFIMEKYGIPQISTGDMLRAAVKSGSELGKQAKDIMDAGKLVTDELVIALVKERIAQEDCRNGFLLDGFPRTIPQADAMKEAGINVDYVLEFDVPDELIVDRIVGRRVHAPSGRVYHVKFNPPKVEGKDDVTGEELTTRKDDQEETVRKRLVEYHQMTAPLIGYYSKEAEAGNTKYAKVDGTKPVAEVRADLEKILG + asym_ids: A +restraints_config: + verbose: true + gpu: true + max_iter: 100 + method: CG + angle_restraints_config: + - atom_selection1: chain A and ((resid 30 to 59)) + atom_selection2: chain A and ((resid 1 to 29) or (resid 60 to 121) or (resid 160 to 214)) + atom_selection3: chain A and ((resid 122 to 159)) + start_sigma: 99999999 + harmonic: + target_angle: 72.85 diff --git a/examples/angle/bioemu2/run.sh b/examples/angle/bioemu2/run.sh new file mode 100755 index 0000000..0e4820a --- /dev/null +++ b/examples/angle/bioemu2/run.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +WS="$(cd "$HERE/../../../.." && pwd)" +cd "$HERE" +uv run --no-project --python "$WS/bioemu2_restr/.venv/bin/python" bioemu2 predict-structure \ + --system "$HERE/adk_72.85.yaml" --out "$HERE/out" \ + --num-samples 1 --num-steps 200 --sampler edm --seed 0 diff --git a/examples/angle/rf3/adk_72.85.json b/examples/angle/rf3/adk_72.85.json new file mode 100644 index 0000000..996733f --- /dev/null +++ b/examples/angle/rf3/adk_72.85.json @@ -0,0 +1,26 @@ +{ + "name": "adk_72.85", + "components": [ + { + "seq": "MRIILLGAPGAGKGTQAQFIMEKYGIPQISTGDMLRAAVKSGSELGKQAKDIMDAGKLVTDELVIALVKERIAQEDCRNGFLLDGFPRTIPQADAMKEAGINVDYVLEFDVPDELIVDRIVGRRVHAPSGRVYHVKFNPPKVEGKDDVTGEELTTRKDDQEETVRKRLVEYHQMTAPLIGYYSKEAEAGNTKYAKVDGTKPVAEVRADLEKILG", + "chain_id": "A" + } + ], + "restraints_config": { + "verbose": true, + "gpu": true, + "max_iter": 100, + "method": "CG", + "angle_restraints_config": [ + { + "atom_selection1": "chain A and ((resid 30 to 59))", + "atom_selection2": "chain A and ((resid 1 to 29) or (resid 60 to 121) or (resid 160 to 214))", + "atom_selection3": "chain A and ((resid 122 to 159))", + "start_sigma": 99999999, + "harmonic": { + "target_angle": 72.85 + } + } + ] + } +} diff --git a/examples/angle/rf3/run.sh b/examples/angle/rf3/run.sh new file mode 100755 index 0000000..a474b68 --- /dev/null +++ b/examples/angle/rf3/run.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +WS="$(cd "$HERE/../../../.." && pwd)" +cd "$HERE" +uv run --no-project --python "$WS/foundry_restr/.venv/bin/python" rf3 fold \ + inputs="$HERE/adk_72.85.json" out_dir="$HERE/out" \ + diffusion_batch_size=1 num_steps=50 early_stopping_plddt_threshold=null seed=0 diff --git a/examples/custom/dist-diff/bioemu2/dgot_0.80.yaml b/examples/custom/dist-diff/bioemu2/dgot_0.80.yaml new file mode 100644 index 0000000..6c46eac --- /dev/null +++ b/examples/custom/dist-diff/bioemu2/dgot_0.80.yaml @@ -0,0 +1,23 @@ +entities: +- entity_type: protein + sequence: RRRYLTLVMIFITVVICYVDRANLAVASAHIQEEFGITKAEMGYVFSAFAWLYTLCQIPGGWFLDRVGSRVTYFIAIFGWSVATLFQGFATGLMSLIGLRAITGIFEAPAFPTNNRMVTSWFPEHERASAVGFYTSGQFVGLAFLTPLLIWIQEMLSWHWVFIVTGGIGIIWSLIWFKVYQPPRLTKGISKAELDYIRDGGGLVDGDAPVKKEARQPLTAKDWKLVFHRKLIGVYLGQFAVASTLWFFLTWFPNYLTQEKGITALKAGFMTTVPFLAAFVGVLLSGWVADLLVRKGFSLGFARKTPIICGLLISTCIMGANYTNDPMMIMCLMALAFFGNGFASITWSLVSSLAPMRLIGLTGGVFNFAGGLGGITVPLVVGYLAQGYGFAPALVYISAVALIGALSYILLVGDVKRVG + asym_ids: A +restraints_config: + verbose: true + gpu: true + max_iter: 100 + method: CG + custom_restraints_config: + - name: double_distres + energy: ((distance(A, B) - distance(C, D)) - 0.8)**2 + selections: + A: chain A and ((resid 1 to 17) or (resid 52 to 66) or (resid 69 to 78) or (resid 108 to 121) or (resid 125 + to 139) or (resid 168 to 178)) + B: chain A and ((resid 229 to 241) or (resid 280 to 295) or (resid 298 to 311) or (resid 341 to 354) or (resid + 358 to 371) or (resid 400 to 412)) + C: chain A and ((resid 18 to 34) or (resid 38 to 51) or (resid 79 to 87) or (resid 92 to 107) or (resid 140 + to 155) or (resid 158 to 167)) + D: chain A and ((resid 242 to 250) or (resid 265 to 279) or (resid 312 to 323) or (resid 325 to 340) or (resid + 372 to 386) or (resid 388 to 399)) + start_sigma: 99999999 + weight: 1.0 diff --git a/examples/custom/dist-diff/bioemu2/run.sh b/examples/custom/dist-diff/bioemu2/run.sh new file mode 100755 index 0000000..3b57af9 --- /dev/null +++ b/examples/custom/dist-diff/bioemu2/run.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +WS="$(cd "$HERE/../../../../.." && pwd)" +cd "$HERE" +uv run --no-project --python "$WS/bioemu2_restr/.venv/bin/python" bioemu2 predict-structure \ + --system "$HERE/dgot_0.80.yaml" --out "$HERE/out" \ + --num-samples 1 --num-steps 200 --sampler edm --seed 0 diff --git a/examples/custom/dist-diff/rf3/dgot_0.80.json b/examples/custom/dist-diff/rf3/dgot_0.80.json new file mode 100644 index 0000000..4a273af --- /dev/null +++ b/examples/custom/dist-diff/rf3/dgot_0.80.json @@ -0,0 +1,29 @@ +{ + "name": "dgot_0.80", + "components": [ + { + "seq": "RRRYLTLVMIFITVVICYVDRANLAVASAHIQEEFGITKAEMGYVFSAFAWLYTLCQIPGGWFLDRVGSRVTYFIAIFGWSVATLFQGFATGLMSLIGLRAITGIFEAPAFPTNNRMVTSWFPEHERASAVGFYTSGQFVGLAFLTPLLIWIQEMLSWHWVFIVTGGIGIIWSLIWFKVYQPPRLTKGISKAELDYIRDGGGLVDGDAPVKKEARQPLTAKDWKLVFHRKLIGVYLGQFAVASTLWFFLTWFPNYLTQEKGITALKAGFMTTVPFLAAFVGVLLSGWVADLLVRKGFSLGFARKTPIICGLLISTCIMGANYTNDPMMIMCLMALAFFGNGFASITWSLVSSLAPMRLIGLTGGVFNFAGGLGGITVPLVVGYLAQGYGFAPALVYISAVALIGALSYILLVGDVKRVG", + "chain_id": "A" + } + ], + "restraints_config": { + "verbose": true, + "gpu": true, + "max_iter": 100, + "method": "CG", + "custom_restraints_config": [ + { + "name": "double_distres", + "energy": "((distance(A, B) - distance(C, D)) - 0.8)**2", + "selections": { + "A": "chain A and ((resid 1 to 17) or (resid 52 to 66) or (resid 69 to 78) or (resid 108 to 121) or (resid 125 to 139) or (resid 168 to 178))", + "B": "chain A and ((resid 229 to 241) or (resid 280 to 295) or (resid 298 to 311) or (resid 341 to 354) or (resid 358 to 371) or (resid 400 to 412))", + "C": "chain A and ((resid 18 to 34) or (resid 38 to 51) or (resid 79 to 87) or (resid 92 to 107) or (resid 140 to 155) or (resid 158 to 167))", + "D": "chain A and ((resid 242 to 250) or (resid 265 to 279) or (resid 312 to 323) or (resid 325 to 340) or (resid 372 to 386) or (resid 388 to 399))" + }, + "start_sigma": 99999999, + "weight": 1.0 + } + ] + } +} diff --git a/examples/custom/dist-diff/rf3/run.sh b/examples/custom/dist-diff/rf3/run.sh new file mode 100755 index 0000000..9bc0990 --- /dev/null +++ b/examples/custom/dist-diff/rf3/run.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +WS="$(cd "$HERE/../../../../.." && pwd)" +cd "$HERE" +uv run --no-project --python "$WS/foundry_restr/.venv/bin/python" rf3 fold \ + inputs="$HERE/dgot_0.80.json" out_dir="$HERE/out" \ + diffusion_batch_size=1 num_steps=50 early_stopping_plddt_threshold=null seed=0 diff --git a/examples/distance/bioemu2/qbp_25.00.yaml b/examples/distance/bioemu2/qbp_25.00.yaml new file mode 100644 index 0000000..4368229 --- /dev/null +++ b/examples/distance/bioemu2/qbp_25.00.yaml @@ -0,0 +1,15 @@ +entities: +- entity_type: protein + sequence: ADKKLVVATDTAFVPFEFKQGDKYVGFDVDLWAAIAKELKLDYELKPMDFSGIIPALQTKNVDLALAGITITDERKKAIDFSDGYYKSGLLVMVKANNNDVKSVKDLDGKVVAVKSGTGSVDYAKANIKTKDLRQFPNIDNAYMELGTNRADAVLHDTPNILYFIKTAGNGQFKAVGDSLEAQQYGIAFPKGSDELRDKVNGALKTLRENGTYNEIYKKWFGTEPK + asym_ids: A +restraints_config: + verbose: true + gpu: true + max_iter: 100 + method: CG + distance_restraints_config: + - atom_selection1: chain A and ((resid 4 to 83) or (resid 185 to 223)) + atom_selection2: chain A and ((resid 89 to 179)) + start_sigma: 99999999 + harmonic: + target_distance: 25.0 diff --git a/examples/distance/bioemu2/run.sh b/examples/distance/bioemu2/run.sh new file mode 100755 index 0000000..a9cc0e6 --- /dev/null +++ b/examples/distance/bioemu2/run.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +WS="$(cd "$HERE/../../../.." && pwd)" +cd "$HERE" +uv run --no-project --python "$WS/bioemu2_restr/.venv/bin/python" bioemu2 predict-structure \ + --system "$HERE/qbp_25.00.yaml" --out "$HERE/out" \ + --num-samples 1 --num-steps 200 --sampler edm --seed 0 diff --git a/examples/distance/rf3/qbp_25.00.json b/examples/distance/rf3/qbp_25.00.json new file mode 100644 index 0000000..49d2073 --- /dev/null +++ b/examples/distance/rf3/qbp_25.00.json @@ -0,0 +1,25 @@ +{ + "name": "qbp_25.00", + "components": [ + { + "seq": "ADKKLVVATDTAFVPFEFKQGDKYVGFDVDLWAAIAKELKLDYELKPMDFSGIIPALQTKNVDLALAGITITDERKKAIDFSDGYYKSGLLVMVKANNNDVKSVKDLDGKVVAVKSGTGSVDYAKANIKTKDLRQFPNIDNAYMELGTNRADAVLHDTPNILYFIKTAGNGQFKAVGDSLEAQQYGIAFPKGSDELRDKVNGALKTLRENGTYNEIYKKWFGTEPK", + "chain_id": "A" + } + ], + "restraints_config": { + "verbose": true, + "gpu": true, + "max_iter": 100, + "method": "CG", + "distance_restraints_config": [ + { + "atom_selection1": "chain A and ((resid 4 to 83) or (resid 185 to 223))", + "atom_selection2": "chain A and ((resid 89 to 179))", + "start_sigma": 99999999, + "harmonic": { + "target_distance": 25.0 + } + } + ] + } +} diff --git a/examples/distance/rf3/run.sh b/examples/distance/rf3/run.sh new file mode 100755 index 0000000..2ce8872 --- /dev/null +++ b/examples/distance/rf3/run.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +WS="$(cd "$HERE/../../../.." && pwd)" +cd "$HERE" +uv run --no-project --python "$WS/foundry_restr/.venv/bin/python" rf3 fold \ + inputs="$HERE/qbp_25.00.json" out_dir="$HERE/out" \ + diffusion_batch_size=1 num_steps=50 early_stopping_plddt_threshold=null seed=0 diff --git a/examples/ligand-dissociation/README.md b/examples/ligand-dissociation/README.md new file mode 100644 index 0000000..5823a13 --- /dev/null +++ b/examples/ligand-dissociation/README.md @@ -0,0 +1,85 @@ +# MDM2–p53 ligand dissociation + +Each model directory contains the same two protein sequences and one harmonic +distance setting. Chain A is the 107-residue MDM2 fragment; chain B is the +17-residue p53 peptide. The distance is between the arithmetic centroids of +all atoms selected by `chain A` and `chain B`, not a closest-contact distance. +The peptide is a protein entity in every model. + +| Setting | Value | +|---|---| +| Distance target (Å) | 13.00 | +| Selections | `chain A` and `chain B` | +| Penalty | Harmonic, default weight 1, both groups movable | +| Minimizer | `CG`, `max_iter: 1000` | +| Activation | `start_sigma: 99999999` on the distance entry; active through the final step | +| Conformer restraints | Disabled | + +These sequences, the target, selections, and explicit optimizer settings follow +the 13.00 Å reference MDM2–p53 sampling input. The legacy input's top-level +`start_sigma` is placed on the distance entry for the current RGI schema. +The current engine's default CG line search applies. + +## MSA files + +Place the reference run's full, unpaired alignments at these paths: + +```text +examples/ligand-dissociation/msas/mdm2_p53.a3m +examples/ligand-dissociation/msas/p53.a3m +``` + +The first file corresponds to `out_msa/mdm2_p53.a3m` in the reference sampling +directory, and the second to `out_msa_2/p53.a3m`. Keep their query sequences +unchanged. Every runner requires both files and performs no MSA search. +The shared `prepare_msa.sh` creates copies under `msas/a3m/` with only +ColabFold's `#` metadata lines removed, for native FASTA parser compatibility. +All FASTA headers and alignment rows are preserved, and the originals are +unchanged. Alignments, converted Parquet files, and predictions are ignored by Git. + +Chai converts the unpaired rows to its aligned-Parquet format under +`msas/chai/`, without pairing keys. All predictors read the same prepared +A3M rows through their native interfaces. Model-specific MSA featurization +and sampling defaults still differ. + +## Run + +Use the matching predictor environment on a GPU compute node. As with the +other examples, the predictor forks are siblings of the RGI-toolkit checkout. +Run from the toolkit directory: + +```bash +bash examples/ligand-dissociation/boltz-2/run.sh +bash examples/ligand-dissociation/rf3/run.sh +bash examples/ligand-dissociation/bioemu2/run.sh +``` + +The runner uses the model's `mdm2_p53_13.00` configuration by default. +Outputs go to `/out//`. Each runner requests one diffusion +sample; repeat seeds separately when reproducing the reference sampling +campaign. The provided examples do not launch that full campaign. + +| Model directory | Input | Alignment input | +|---|---|---| +| `boltz-2` | YAML | Protein `msa` paths | +| `protenix-v2` | JSON job list | Protein `unpairedMsaPath` | +| `alphafold3` | JSON | `unpairedMsaPath`, empty paired MSA, no templates | +| `openfold-3` | JSON query | `main_msa_file_paths` | +| `chai` | YAML plus `mdm2_p53.fasta` | Converted aligned-Parquet directory | +| `esmfold2` | JSON consumed by `run_dissociation.py` | `MSA.from_a3m` for each protein | +| `opendde` | JSON job list | Protein `unpairedMsaPath` | +| `rf3` | JSON job | Chain-keyed `msa_paths` | +| `bioemu2` | System YAML | `get_msa` with chain-keyed paths in the runner | + +AlphaFold3 also requires `MODEL_DIR`. Its data pipeline is disabled because +both alignments are supplied. Protenix-v2 requires a supported sm_89 GPU in +this integration. RF3 uses 50 diffusion steps; BioEmu2, ESMFold2, Protenix-v2, +and OpenDDE use 200. See the [integration guides](../../docs/README.md) for +installation and the [main example guide](../README.md) for general settings. + +## Verify + +With `verbose: true`, confirm that `built spec:` reports one distance term +and that both selected chains contain atoms. Measure the chain-centroid +distance in each output and compare it with the 13.0 Å target. Schema and +input checks do not demonstrate that a sampled structure reached the target. diff --git a/examples/ligand-dissociation/alphafold3/mdm2_p53_13.00.json b/examples/ligand-dissociation/alphafold3/mdm2_p53_13.00.json new file mode 100644 index 0000000..85b4124 --- /dev/null +++ b/examples/ligand-dissociation/alphafold3/mdm2_p53_13.00.json @@ -0,0 +1,44 @@ +{ + "dialect": "alphafold3", + "version": 4, + "name": "mdm2_p53_13.00", + "modelSeeds": [ + 0 + ], + "sequences": [ + { + "protein": { + "id": "A", + "sequence": "NHISTSDQEKLVQPTPLLLSLLKSAGAQKETFTMKEVIYHLGQYIMAKQLYDEKQQHIVHCSNDPLGELFGVQEFSVKEPRRLYAMISRNLVSANVKESSEDIFGNV", + "unpairedMsaPath": "../msas/a3m/mdm2_p53.a3m", + "pairedMsa": "", + "templates": [] + } + }, + { + "protein": { + "id": "B", + "sequence": "PLSQETFSDLWKLLPEN", + "unpairedMsaPath": "../msas/a3m/p53.a3m", + "pairedMsa": "", + "templates": [] + } + } + ], + "restraints_config": { + "verbose": true, + "max_iter": 1000, + "method": "CG", + "distance_restraints_config": [ + { + "atom_selection1": "chain A", + "atom_selection2": "chain B", + "harmonic": { + "target_distance": 13.0 + }, + "start_sigma": 99999999 + } + ], + "gpu": true + } +} diff --git a/examples/ligand-dissociation/alphafold3/run.sh b/examples/ligand-dissociation/alphafold3/run.sh new file mode 100755 index 0000000..974bd9f --- /dev/null +++ b/examples/ligand-dissociation/alphafold3/run.sh @@ -0,0 +1,15 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +WS="$(cd "$HERE/../../../.." && pwd)" +cd "$HERE" +INPUT="${1:-mdm2_p53_13.00.json}" +test -f "$INPUT" +STEM="$(basename "$INPUT")" +STEM="${STEM%.*}" +OUT="out/$STEM" +bash "$HERE/../prepare_msa.sh" +MODEL_DIR="${MODEL_DIR:?set MODEL_DIR to your AF3 model-parameters directory}" +uv run --no-project --python "$WS/alphafold3_restr/.venv/bin/python" python \ + "$WS/alphafold3_restr/run_alphafold.py" --json_path="$INPUT" --output_dir="$OUT" \ + --model_dir="$MODEL_DIR" --run_data_pipeline=False --num_diffusion_samples=1 diff --git a/examples/ligand-dissociation/bioemu2/mdm2_p53_13.00.yaml b/examples/ligand-dissociation/bioemu2/mdm2_p53_13.00.yaml new file mode 100644 index 0000000..7f1f71c --- /dev/null +++ b/examples/ligand-dissociation/bioemu2/mdm2_p53_13.00.yaml @@ -0,0 +1,18 @@ +entities: +- entity_type: protein + sequence: NHISTSDQEKLVQPTPLLLSLLKSAGAQKETFTMKEVIYHLGQYIMAKQLYDEKQQHIVHCSNDPLGELFGVQEFSVKEPRRLYAMISRNLVSANVKESSEDIFGNV + asym_ids: A +- entity_type: protein + sequence: PLSQETFSDLWKLLPEN + asym_ids: B +restraints_config: + verbose: true + max_iter: 1000 + method: CG + distance_restraints_config: + - atom_selection1: chain A + atom_selection2: chain B + harmonic: + target_distance: 13.0 + start_sigma: 99999999 + gpu: true diff --git a/examples/ligand-dissociation/bioemu2/run.sh b/examples/ligand-dissociation/bioemu2/run.sh new file mode 100755 index 0000000..e6bd579 --- /dev/null +++ b/examples/ligand-dissociation/bioemu2/run.sh @@ -0,0 +1,10 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +WS="$(cd "$HERE/../../../.." && pwd)" +cd "$HERE" +INPUT="${1:-mdm2_p53_13.00.yaml}" +test -f "$INPUT" +bash "$HERE/../prepare_msa.sh" +uv run --no-project --python "$WS/bioemu2_restr/.venv/bin/python" python \ + "$HERE/run_dissociation.py" "$INPUT" diff --git a/examples/ligand-dissociation/bioemu2/run_dissociation.py b/examples/ligand-dissociation/bioemu2/run_dissociation.py new file mode 100644 index 0000000..a49de15 --- /dev/null +++ b/examples/ligand-dissociation/bioemu2/run_dissociation.py @@ -0,0 +1,30 @@ +"""Sample one MDM2-p53 structure with the supplied per-chain alignments.""" + +import argparse +from pathlib import Path + +from bioemu2 import EDMSampler, EmuSession, System, get_msa, load_model, save_frames + + +def main() -> None: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("input", type=Path) + args = parser.parse_args() + input_path = args.input.resolve() + system = System.from_yaml(input_path) + msa_dir = input_path.parent.parent / "msas/a3m" + msa = get_msa( + system, + {"A": msa_dir / "mdm2_p53.a3m", "B": msa_dir / "p53.a3m"}, + ) + session = EmuSession(system, model=load_model(), mode="structure", msa=msa) + samples = session.sample( + num_samples=1, + sampler=EDMSampler(num_steps=200, step_scale=1.5), + seed=0, + ) + save_frames(samples, input_path.parent / "out" / input_path.stem) + + +if __name__ == "__main__": + main() diff --git a/examples/ligand-dissociation/boltz-2/mdm2_p53_13.00.yaml b/examples/ligand-dissociation/boltz-2/mdm2_p53_13.00.yaml new file mode 100644 index 0000000..710a0bc --- /dev/null +++ b/examples/ligand-dissociation/boltz-2/mdm2_p53_13.00.yaml @@ -0,0 +1,20 @@ +sequences: +- protein: + id: A + sequence: NHISTSDQEKLVQPTPLLLSLLKSAGAQKETFTMKEVIYHLGQYIMAKQLYDEKQQHIVHCSNDPLGELFGVQEFSVKEPRRLYAMISRNLVSANVKESSEDIFGNV + msa: ../msas/a3m/mdm2_p53.a3m +- protein: + id: B + sequence: PLSQETFSDLWKLLPEN + msa: ../msas/a3m/p53.a3m +restraints_config: + verbose: true + max_iter: 1000 + method: CG + distance_restraints_config: + - atom_selection1: chain A + atom_selection2: chain B + harmonic: + target_distance: 13.0 + start_sigma: 99999999 + gpu: true diff --git a/examples/ligand-dissociation/boltz-2/run.sh b/examples/ligand-dissociation/boltz-2/run.sh new file mode 100755 index 0000000..00c32f4 --- /dev/null +++ b/examples/ligand-dissociation/boltz-2/run.sh @@ -0,0 +1,13 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +WS="$(cd "$HERE/../../../.." && pwd)" +cd "$HERE" +INPUT="${1:-mdm2_p53_13.00.yaml}" +test -f "$INPUT" +STEM="$(basename "$INPUT")" +STEM="${STEM%.*}" +OUT="out/$STEM" +bash "$HERE/../prepare_msa.sh" +uv run --no-project --python "$WS/boltz_restr/.venv/bin/python" boltz predict "$INPUT" \ + --out_dir "$OUT" --model boltz2 --diffusion_samples 1 --seed 0 diff --git a/examples/ligand-dissociation/chai/mdm2_p53.fasta b/examples/ligand-dissociation/chai/mdm2_p53.fasta new file mode 100644 index 0000000..ebaff7b --- /dev/null +++ b/examples/ligand-dissociation/chai/mdm2_p53.fasta @@ -0,0 +1,4 @@ +>protein|name=A +NHISTSDQEKLVQPTPLLLSLLKSAGAQKETFTMKEVIYHLGQYIMAKQLYDEKQQHIVHCSNDPLGELFGVQEFSVKEPRRLYAMISRNLVSANVKESSEDIFGNV +>protein|name=B +PLSQETFSDLWKLLPEN diff --git a/examples/ligand-dissociation/chai/mdm2_p53_13.00.yaml b/examples/ligand-dissociation/chai/mdm2_p53_13.00.yaml new file mode 100644 index 0000000..f265157 --- /dev/null +++ b/examples/ligand-dissociation/chai/mdm2_p53_13.00.yaml @@ -0,0 +1,10 @@ +verbose: true +max_iter: 1000 +method: CG +distance_restraints_config: +- atom_selection1: chain A + atom_selection2: chain B + harmonic: + target_distance: 13.0 + start_sigma: 99999999 +gpu: true diff --git a/examples/ligand-dissociation/chai/prepare_msa.py b/examples/ligand-dissociation/chai/prepare_msa.py new file mode 100644 index 0000000..21d7fb0 --- /dev/null +++ b/examples/ligand-dissociation/chai/prepare_msa.py @@ -0,0 +1,30 @@ +"""Convert the two unpaired A3Ms to Chai's aligned-Parquet input format.""" + +from pathlib import Path + +from chai_lab.data.parsing.fasta import read_fasta +from chai_lab.data.parsing.msas.aligned_pqt import ( + a3m_to_aligned_dataframe, + expected_basename, +) +from chai_lab.data.parsing.msas.data_source import MSADataSource + + +def main() -> None: + here = Path(__file__).resolve().parent + msa_dir = here.parent / "msas/a3m" + output_dir = here.parent / "msas/chai" + output_dir.mkdir(parents=True, exist_ok=True) + proteins = read_fasta(here / "mdm2_p53.fasta") + for protein, filename in zip(proteins, ["mdm2_p53.a3m", "p53.a3m"], strict=True): + path = msa_dir / filename + if read_fasta(path)[0].sequence != protein.sequence: + raise ValueError(f"The MSA query in {filename} does not match the FASTA.") + frame = a3m_to_aligned_dataframe( + path, MSADataSource.BFD_UNICLUST, insert_pairing_key=False + ) + frame.to_parquet(output_dir / expected_basename(protein.sequence), index=False) + + +if __name__ == "__main__": + main() diff --git a/examples/ligand-dissociation/chai/run.sh b/examples/ligand-dissociation/chai/run.sh new file mode 100755 index 0000000..2568b19 --- /dev/null +++ b/examples/ligand-dissociation/chai/run.sh @@ -0,0 +1,15 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +WS="$(cd "$HERE/../../../.." && pwd)" +cd "$HERE" +INPUT="${1:-mdm2_p53_13.00.yaml}" +test -f "$INPUT" +STEM="$(basename "$INPUT")" +STEM="${STEM%.*}" +OUT="out/$STEM" +bash "$HERE/../prepare_msa.sh" +uv run --no-project --python "$WS/chai-lab_restr/.venv/bin/python" python prepare_msa.py +uv run --no-project --python "$WS/chai-lab_restr/.venv/bin/python" python -m chai_lab.main fold \ + mdm2_p53.fasta "$OUT" --restraints-config-path "$INPUT" \ + --num-trunk-samples 1 --num-diffn-samples 1 --seed 0 --msa-directory ../msas/chai diff --git a/examples/ligand-dissociation/esmfold2/mdm2_p53_13.00.json b/examples/ligand-dissociation/esmfold2/mdm2_p53_13.00.json new file mode 100644 index 0000000..2d8c156 --- /dev/null +++ b/examples/ligand-dissociation/esmfold2/mdm2_p53_13.00.json @@ -0,0 +1,30 @@ +{ + "sequences": [ + { + "id": "A", + "sequence": "NHISTSDQEKLVQPTPLLLSLLKSAGAQKETFTMKEVIYHLGQYIMAKQLYDEKQQHIVHCSNDPLGELFGVQEFSVKEPRRLYAMISRNLVSANVKESSEDIFGNV", + "msa": "../msas/a3m/mdm2_p53.a3m" + }, + { + "id": "B", + "sequence": "PLSQETFSDLWKLLPEN", + "msa": "../msas/a3m/p53.a3m" + } + ], + "restraints_config": { + "verbose": true, + "max_iter": 1000, + "method": "CG", + "distance_restraints_config": [ + { + "atom_selection1": "chain A", + "atom_selection2": "chain B", + "harmonic": { + "target_distance": 13.0 + }, + "start_sigma": 99999999 + } + ], + "gpu": true + } +} diff --git a/examples/ligand-dissociation/esmfold2/run.sh b/examples/ligand-dissociation/esmfold2/run.sh new file mode 100755 index 0000000..11cfd23 --- /dev/null +++ b/examples/ligand-dissociation/esmfold2/run.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +WS="$(cd "$HERE/../../../.." && pwd)" +cd "$HERE" +INPUT="${1:-mdm2_p53_13.00.json}" +test -f "$INPUT" +bash "$HERE/../prepare_msa.sh" +PIXI="$WS/esm_restr/.pixi-bin/pixi" +[ -x "$PIXI" ] || PIXI=pixi +"$PIXI" run --manifest-path "$WS/esm_restr/pyproject.toml" python \ + "$HERE/run_dissociation.py" "$INPUT" diff --git a/examples/ligand-dissociation/esmfold2/run_dissociation.py b/examples/ligand-dissociation/esmfold2/run_dissociation.py new file mode 100644 index 0000000..8b1bbc3 --- /dev/null +++ b/examples/ligand-dissociation/esmfold2/run_dissociation.py @@ -0,0 +1,50 @@ +"""Sample one MDM2-p53 structure from an inline JSON example and local A3Ms.""" + +import argparse +import json +from pathlib import Path + +from esm.models.esmfold2 import ( + ESMFold2InputBuilder, + EsmFold2Model, + ProteinInput, + StructurePredictionInput, +) +from esm.utils.msa import MSA + + +def main() -> None: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("input", type=Path) + args = parser.parse_args() + input_path = args.input.resolve() + data = json.loads(input_path.read_text()) + proteins = [] + for chain in data["sequences"]: + msa = MSA.from_a3m( + path=str(input_path.parent / chain["msa"]), remove_insertions=True + ) + if msa.depth < 1 or msa.query != chain["sequence"]: + raise ValueError(f"The MSA query does not match chain {chain['id']}.") + proteins.append( + ProteinInput(id=chain["id"], sequence=chain["sequence"], msa=msa) + ) + model = EsmFold2Model.from_pretrained("biohub/ESMFold2", device="cuda") + model.train(False) + result = ESMFold2InputBuilder().fold( + model, + StructurePredictionInput(sequences=proteins), + num_loops=20, + num_sampling_steps=200, + seed=0, + msa_max_depth=1024, + msa_column_mask_rate=0.1, + restraints_config=data["restraints_config"], + ) + output_dir = input_path.parent / "out" / input_path.stem + output_dir.mkdir(parents=True, exist_ok=True) + (output_dir / "model.cif").write_text(result.complex.to_mmcif()) + + +if __name__ == "__main__": + main() diff --git a/examples/ligand-dissociation/opendde/mdm2_p53_13.00.json b/examples/ligand-dissociation/opendde/mdm2_p53_13.00.json new file mode 100644 index 0000000..97f924a --- /dev/null +++ b/examples/ligand-dissociation/opendde/mdm2_p53_13.00.json @@ -0,0 +1,46 @@ +[ + { + "name": "mdm2_p53_13.00", + "sequences": [ + { + "proteinChain": { + "sequence": "NHISTSDQEKLVQPTPLLLSLLKSAGAQKETFTMKEVIYHLGQYIMAKQLYDEKQQHIVHCSNDPLGELFGVQEFSVKEPRRLYAMISRNLVSANVKESSEDIFGNV", + "count": 1, + "unpairedMsaPath": "../msas/a3m/mdm2_p53.a3m", + "id": [ + "A" + ] + } + }, + { + "proteinChain": { + "sequence": "PLSQETFSDLWKLLPEN", + "count": 1, + "unpairedMsaPath": "../msas/a3m/p53.a3m", + "id": [ + "B" + ] + } + } + ], + "restraints_config": { + "verbose": true, + "max_iter": 1000, + "method": "CG", + "distance_restraints_config": [ + { + "atom_selection1": "chain A", + "atom_selection2": "chain B", + "harmonic": { + "target_distance": 13.0 + }, + "start_sigma": 99999999 + } + ], + "gpu": true + }, + "modelSeeds": [ + 0 + ] + } +] diff --git a/examples/ligand-dissociation/opendde/run.sh b/examples/ligand-dissociation/opendde/run.sh new file mode 100755 index 0000000..b6d4f47 --- /dev/null +++ b/examples/ligand-dissociation/opendde/run.sh @@ -0,0 +1,14 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +WS="$(cd "$HERE/../../../.." && pwd)" +cd "$HERE" +INPUT="${1:-mdm2_p53_13.00.json}" +test -f "$INPUT" +STEM="$(basename "$INPUT")" +STEM="${STEM%.*}" +OUT="out/$STEM" +bash "$HERE/../prepare_msa.sh" +uv run --no-project --python "$WS/OpenDDE_restr/.venv/bin/python" opendde pred \ + -i "$INPUT" -o "$OUT" -n opendde_v1 --use_msa true --use_template false \ + --use_rna_msa false --seeds 0 --sample 1 --step 200 --cycle 4 diff --git a/examples/ligand-dissociation/openfold-3/mdm2_p53_13.00.json b/examples/ligand-dissociation/openfold-3/mdm2_p53_13.00.json new file mode 100644 index 0000000..cb65dbb --- /dev/null +++ b/examples/ligand-dissociation/openfold-3/mdm2_p53_13.00.json @@ -0,0 +1,47 @@ +{ + "seeds": [ + 0 + ], + "queries": { + "mdm2_p53_13.00": { + "chains": [ + { + "molecule_type": "protein", + "chain_ids": [ + "A" + ], + "sequence": "NHISTSDQEKLVQPTPLLLSLLKSAGAQKETFTMKEVIYHLGQYIMAKQLYDEKQQHIVHCSNDPLGELFGVQEFSVKEPRRLYAMISRNLVSANVKESSEDIFGNV", + "main_msa_file_paths": [ + "../msas/a3m/mdm2_p53.a3m" + ] + }, + { + "molecule_type": "protein", + "chain_ids": [ + "B" + ], + "sequence": "PLSQETFSDLWKLLPEN", + "main_msa_file_paths": [ + "../msas/a3m/p53.a3m" + ] + } + ], + "restraints_config": { + "verbose": true, + "max_iter": 1000, + "method": "CG", + "distance_restraints_config": [ + { + "atom_selection1": "chain A", + "atom_selection2": "chain B", + "harmonic": { + "target_distance": 13.0 + }, + "start_sigma": 99999999 + } + ], + "gpu": true + } + } + } +} diff --git a/examples/ligand-dissociation/openfold-3/run.sh b/examples/ligand-dissociation/openfold-3/run.sh new file mode 100755 index 0000000..cc4158f --- /dev/null +++ b/examples/ligand-dissociation/openfold-3/run.sh @@ -0,0 +1,16 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +WS="$(cd "$HERE/../../../.." && pwd)" +cd "$HERE" +INPUT="${1:-mdm2_p53_13.00.json}" +test -f "$INPUT" +STEM="$(basename "$INPUT")" +STEM="${STEM%.*}" +OUT="out/$STEM" +bash "$HERE/../prepare_msa.sh" +PIXI="$WS/openfold-3_restr/.pixi-bin/pixi" +[ -x "$PIXI" ] || PIXI=pixi +"$PIXI" run --manifest-path "$WS/openfold-3_restr/pixi.toml" -e openfold3-cuda12 \ + run_openfold predict --query-json "$HERE/$INPUT" --output-dir "$HERE/$OUT" \ + --num-diffusion-samples 1 --use-msa-server false --use-templates false diff --git a/examples/ligand-dissociation/prepare_msa.sh b/examples/ligand-dissociation/prepare_msa.sh new file mode 100755 index 0000000..f9b593a --- /dev/null +++ b/examples/ligand-dissociation/prepare_msa.sh @@ -0,0 +1,17 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +output_dir="$HERE/msas/a3m" +for filename in mdm2_p53.a3m p53.a3m; do + if [ ! -s "$HERE/msas/$filename" ]; then + printf 'Missing MSA: %s (see README.md)\n' "$HERE/msas/$filename" >&2 + exit 1 + fi +done +mkdir -p "$output_dir" +for filename in mdm2_p53.a3m p53.a3m; do + prepared_tmp="$(mktemp "$output_dir/$filename.XXXXXX")" + # Some native FASTA parsers reject ColabFold's metadata comments. + sed '/^#/d' "$HERE/msas/$filename" > "$prepared_tmp" + mv "$prepared_tmp" "$output_dir/$filename" +done diff --git a/examples/ligand-dissociation/protenix-v2/mdm2_p53_13.00.json b/examples/ligand-dissociation/protenix-v2/mdm2_p53_13.00.json new file mode 100644 index 0000000..b376522 --- /dev/null +++ b/examples/ligand-dissociation/protenix-v2/mdm2_p53_13.00.json @@ -0,0 +1,37 @@ +[ + { + "name": "mdm2_p53_13.00", + "sequences": [ + { + "proteinChain": { + "sequence": "NHISTSDQEKLVQPTPLLLSLLKSAGAQKETFTMKEVIYHLGQYIMAKQLYDEKQQHIVHCSNDPLGELFGVQEFSVKEPRRLYAMISRNLVSANVKESSEDIFGNV", + "count": 1, + "unpairedMsaPath": "../msas/a3m/mdm2_p53.a3m" + } + }, + { + "proteinChain": { + "sequence": "PLSQETFSDLWKLLPEN", + "count": 1, + "unpairedMsaPath": "../msas/a3m/p53.a3m" + } + } + ], + "restraints_config": { + "verbose": true, + "max_iter": 1000, + "method": "CG", + "distance_restraints_config": [ + { + "atom_selection1": "chain A", + "atom_selection2": "chain B", + "harmonic": { + "target_distance": 13.0 + }, + "start_sigma": 99999999 + } + ], + "gpu": true + } + } +] diff --git a/examples/ligand-dissociation/protenix-v2/run.sh b/examples/ligand-dissociation/protenix-v2/run.sh new file mode 100755 index 0000000..0ed8a7c --- /dev/null +++ b/examples/ligand-dissociation/protenix-v2/run.sh @@ -0,0 +1,14 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +WS="$(cd "$HERE/../../../.." && pwd)" +cd "$HERE" +INPUT="${1:-mdm2_p53_13.00.json}" +test -f "$INPUT" +STEM="$(basename "$INPUT")" +STEM="${STEM%.*}" +OUT="out/$STEM" +bash "$HERE/../prepare_msa.sh" +uv run --no-project --python "$WS/protenix_restr/.venv/bin/python" protenix pred \ + -i "$INPUT" -o "$OUT" --model_name protenix-v2 --use_default_params true \ + --use_msa true --seeds 0 --step 200 --sample 1 diff --git a/examples/ligand-dissociation/rf3/mdm2_p53_13.00.json b/examples/ligand-dissociation/rf3/mdm2_p53_13.00.json new file mode 100644 index 0000000..0404e88 --- /dev/null +++ b/examples/ligand-dissociation/rf3/mdm2_p53_13.00.json @@ -0,0 +1,33 @@ +{ + "name": "mdm2_p53_13.00", + "components": [ + { + "seq": "NHISTSDQEKLVQPTPLLLSLLKSAGAQKETFTMKEVIYHLGQYIMAKQLYDEKQQHIVHCSNDPLGELFGVQEFSVKEPRRLYAMISRNLVSANVKESSEDIFGNV", + "chain_id": "A" + }, + { + "seq": "PLSQETFSDLWKLLPEN", + "chain_id": "B" + } + ], + "restraints_config": { + "verbose": true, + "max_iter": 1000, + "method": "CG", + "distance_restraints_config": [ + { + "atom_selection1": "chain A", + "atom_selection2": "chain B", + "harmonic": { + "target_distance": 13.0 + }, + "start_sigma": 99999999 + } + ], + "gpu": true + }, + "msa_paths": { + "A": "../msas/a3m/mdm2_p53.a3m", + "B": "../msas/a3m/p53.a3m" + } +} diff --git a/examples/ligand-dissociation/rf3/run.sh b/examples/ligand-dissociation/rf3/run.sh new file mode 100755 index 0000000..dfd68f7 --- /dev/null +++ b/examples/ligand-dissociation/rf3/run.sh @@ -0,0 +1,14 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +WS="$(cd "$HERE/../../../.." && pwd)" +cd "$HERE" +INPUT="${1:-mdm2_p53_13.00.json}" +test -f "$INPUT" +STEM="$(basename "$INPUT")" +STEM="${STEM%.*}" +OUT="out/$STEM" +bash "$HERE/../prepare_msa.sh" +uv run --no-project --python "$WS/foundry_restr/.venv/bin/python" rf3 fold \ + inputs="$HERE/$INPUT" out_dir="$HERE/$OUT" diffusion_batch_size=1 \ + num_steps=50 early_stopping_plddt_threshold=null seed=0 diff --git a/examples/rmsd/bioemu2/qbp_2.65.yaml b/examples/rmsd/bioemu2/qbp_2.65.yaml new file mode 100644 index 0000000..27c6f61 --- /dev/null +++ b/examples/rmsd/bioemu2/qbp_2.65.yaml @@ -0,0 +1,30 @@ +entities: +- entity_type: protein + sequence: ADKKLVVATDTAFVPFEFKQGDKYVGFDVDLWAAIAKELKLDYELKPMDFSGIIPALQTKNVDLALAGITITDERKKAIDFSDGYYKSGLLVMVKANNNDVKSVKDLDGKVVAVKSGTGSVDYAKANIKTKDLRQFPNIDNAYMELGTNRADAVLHDTPNILYFIKTAGNGQFKAVGDSLEAQQYGIAFPKGSDELRDKVNGALKTLRENGTYNEIYKKWFGTEPK + asym_ids: A +restraints_config: + verbose: true + gpu: true + max_iter: 1000 + method: CG + rmsd_restraints_config: + - ref_cif: 1GGG.cif + atom_selection_ref_fit: chain A and name CA and resid 1 to 220 + atom_selection_target_fit: chain A and name CA and resid 5 to 224 + atom_selection_ref_calc: chain A and name CA and resid 1 to 220 + atom_selection_target_calc: chain A and name CA and resid 5 to 224 + pairing: align + start_sigma: 99999999 + stop_sigma: 1.5 + harmonic: + target_rmsd: 2.65 + - ref_cif: 1WDN.cif + atom_selection_ref_fit: chain A and name CA and resid 2 to 221 + atom_selection_target_fit: chain A and name CA and resid 5 to 224 + atom_selection_ref_calc: chain A and name CA and resid 2 to 221 + atom_selection_target_calc: chain A and name CA and resid 5 to 224 + pairing: align + start_sigma: 99999999 + stop_sigma: 1.5 + harmonic: + target_rmsd: 2.65 diff --git a/examples/rmsd/bioemu2/run.sh b/examples/rmsd/bioemu2/run.sh new file mode 100755 index 0000000..c88feef --- /dev/null +++ b/examples/rmsd/bioemu2/run.sh @@ -0,0 +1,11 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +WS="$(cd "$HERE/../../../.." && pwd)" +cd "$HERE" +for pdb in 1GGG 1WDN; do + [ -s "$pdb.cif" ] || curl -fLsS "https://files.rcsb.org/download/$pdb.cif" -o "$pdb.cif" +done +uv run --no-project --python "$WS/bioemu2_restr/.venv/bin/python" bioemu2 predict-structure \ + --system "$HERE/qbp_2.65.yaml" --out "$HERE/out" \ + --num-samples 1 --num-steps 200 --sampler edm --seed 0 diff --git a/examples/rmsd/rf3/qbp_2.65.json b/examples/rmsd/rf3/qbp_2.65.json new file mode 100644 index 0000000..6cc2712 --- /dev/null +++ b/examples/rmsd/rf3/qbp_2.65.json @@ -0,0 +1,43 @@ +{ + "name": "qbp_2.65", + "components": [ + { + "seq": "ADKKLVVATDTAFVPFEFKQGDKYVGFDVDLWAAIAKELKLDYELKPMDFSGIIPALQTKNVDLALAGITITDERKKAIDFSDGYYKSGLLVMVKANNNDVKSVKDLDGKVVAVKSGTGSVDYAKANIKTKDLRQFPNIDNAYMELGTNRADAVLHDTPNILYFIKTAGNGQFKAVGDSLEAQQYGIAFPKGSDELRDKVNGALKTLRENGTYNEIYKKWFGTEPK", + "chain_id": "A" + } + ], + "restraints_config": { + "verbose": true, + "gpu": true, + "max_iter": 1000, + "method": "CG", + "rmsd_restraints_config": [ + { + "ref_cif": "1GGG.cif", + "atom_selection_ref_fit": "chain A and name CA and resid 1 to 220", + "atom_selection_target_fit": "chain A and name CA and resid 5 to 224", + "atom_selection_ref_calc": "chain A and name CA and resid 1 to 220", + "atom_selection_target_calc": "chain A and name CA and resid 5 to 224", + "pairing": "align", + "start_sigma": 99999999, + "stop_sigma": 1.5, + "harmonic": { + "target_rmsd": 2.65 + } + }, + { + "ref_cif": "1WDN.cif", + "atom_selection_ref_fit": "chain A and name CA and resid 2 to 221", + "atom_selection_target_fit": "chain A and name CA and resid 5 to 224", + "atom_selection_ref_calc": "chain A and name CA and resid 2 to 221", + "atom_selection_target_calc": "chain A and name CA and resid 5 to 224", + "pairing": "align", + "start_sigma": 99999999, + "stop_sigma": 1.5, + "harmonic": { + "target_rmsd": 2.65 + } + } + ] + } +} diff --git a/examples/rmsd/rf3/run.sh b/examples/rmsd/rf3/run.sh new file mode 100755 index 0000000..2b21ba5 --- /dev/null +++ b/examples/rmsd/rf3/run.sh @@ -0,0 +1,11 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +WS="$(cd "$HERE/../../../.." && pwd)" +cd "$HERE" +for pdb in 1GGG 1WDN; do + [ -s "$pdb.cif" ] || curl -fLsS "https://files.rcsb.org/download/$pdb.cif" -o "$pdb.cif" +done +uv run --no-project --python "$WS/foundry_restr/.venv/bin/python" rf3 fold \ + inputs="$HERE/qbp_2.65.json" out_dir="$HERE/out" \ + diffusion_batch_size=1 num_steps=50 early_stopping_plddt_threshold=null seed=0 diff --git a/pyproject.toml b/pyproject.toml index 18bf657..acc0ee4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "rgi-toolkit" -version = "0.4.6" +version = "0.4.7" description = "Restraint-Guided Inference toolkit for PyTorch/JAX-based structure prediction models" readme = "README.md" requires-python = ">=3.12" @@ -19,7 +19,7 @@ dependencies = [ # PyTorch backend; CUDA bindings enable native solver graph control flow on Linux. torch = [ "torch>=2.2", - "cuda-bindings>=12.8,<13; sys_platform == 'linux'", + "cuda-bindings>=12.8,<14; sys_platform == 'linux'", ] # JAX backend (alphafold3). Pure JAX CG by default; jaxopt for optional L-BFGS. jax = [ diff --git a/src/rgi_toolkit/bioemu2/__init__.py b/src/rgi_toolkit/bioemu2/__init__.py new file mode 100644 index 0000000..73e1854 --- /dev/null +++ b/src/rgi_toolkit/bioemu2/__init__.py @@ -0,0 +1,5 @@ +"""BioEmu2 integration without importing the predictor or a compute backend.""" + +from .adapter import BioEmu2Adapter + +__all__ = ["BioEmu2Adapter"] diff --git a/src/rgi_toolkit/bioemu2/adapter.py b/src/rgi_toolkit/bioemu2/adapter.py new file mode 100644 index 0000000..cfad52d --- /dev/null +++ b/src/rgi_toolkit/bioemu2/adapter.py @@ -0,0 +1,165 @@ +"""Adapt BioEmu2's padded atom order and reference chemistry to RGI.""" + +from __future__ import annotations + +from typing import Iterator + +import numpy as np + +from rgi_toolkit._mol_build import mol_with_reference_conformer +from rgi_toolkit.atom_context import AtomRecord, LigandConf, decode_atom_name + + +class BioEmu2Adapter: + """Receive plain arrays from one BioEmu2 structure before multiplicity expansion. + + Coordinates and reference positions are in angstroms. Each ligand source + molecule carries ``atom_name`` properties in BioEmu2's naming convention. + Padding remains in coordinate arrays but never participates in selections. + """ + + def __init__( + self, + *, + chain_ids, + atom_chain_indices, + atom_to_token_map, + atom_mask, + atom_name_codes, + residue_names, + mol_types, + elements, + ref_pos, + ref_space_uid, + conformer_chains=(), + ligand_mols=None, + ) -> None: + self._chain_ids = tuple(str(chain) for chain in chain_ids) + self._chains = np.asarray(atom_chain_indices, dtype=np.int64) + self._tokens = np.asarray(atom_to_token_map, dtype=np.int64) + self._mask = np.asarray(atom_mask, dtype=bool) + self._names = np.asarray(atom_name_codes, dtype=np.int64) + self._resnames = np.asarray(residue_names, dtype=object) + self._types = np.asarray(mol_types, dtype=object) + self._elements = np.asarray(elements, dtype=np.int64).copy() + self._positions = np.asarray(ref_pos, dtype=np.float64).copy() + self._spaces = np.asarray(ref_space_uid, dtype=np.int64).copy() + self._conformer_chains = frozenset(conformer_chains) + self._ligand_mols = dict(ligand_mols or {}) + if self._mask.ndim != 1: + raise ValueError("BioEmu2 atom_mask must be one-dimensional") + n = len(self._mask) + for name, array in ( + ("atom_chain_indices", self._chains), + ("atom_to_token_map", self._tokens), + ("residue_names", self._resnames), + ("mol_types", self._types), + ("elements", self._elements), + ("ref_space_uid", self._spaces), + ): + if array.shape != (n,): + raise ValueError(f"BioEmu2 {name} must follow the padded atom order") + if self._names.shape != (n, 4): + raise ValueError("BioEmu2 atom_name_codes must have shape (atoms, 4)") + if self._positions.shape != (n, 3): + raise ValueError("BioEmu2 ref_pos must have shape (atoms, 3)") + if not np.isfinite(self._positions[self._mask]).all(): + raise ValueError("BioEmu2 reference positions must be finite") + if len(set(self._chain_ids)) != len(self._chain_ids): + raise ValueError("BioEmu2 chain IDs must be unique") + chains = self._chains[self._mask] + if np.any(chains < 0) or np.any(chains >= len(self._chain_ids)): + raise ValueError("BioEmu2 atom chain indices do not match chain IDs") + if np.any(self._tokens[self._mask] < 0): + raise ValueError("BioEmu2 real atoms require nonnegative token indices") + if not set(self._types[self._mask]).issubset( + {None, "protein", "rna", "dna", "ligand"} + ): + raise ValueError("BioEmu2 mol_types must be normalized molecular types") + if not self._conformer_chains.issubset(self._chain_ids): + raise ValueError("BioEmu2 conformer flags refer to an unknown chain") + self._elements[~self._mask] = 0 + self._positions[~self._mask] = 0 + self._spaces[~self._mask] = -1 + + def iter_atoms(self) -> Iterator[AtomRecord]: + chain_tokens: dict[str, dict[int, int]] = {} + for index in np.flatnonzero(self._mask): + chain = self._chain_ids[self._chains[index]] + tokens = chain_tokens.setdefault(chain, {}) + token = int(self._tokens[index]) + if token not in tokens: + tokens[token] = len(tokens) + 1 + yield AtomRecord( + chain=chain, + resid=tokens[token], + index=int(index), + name=decode_atom_name(self._names[index]), + resname=self._resnames[index], + mol_type=self._types[index], + conformer_restraints=chain in self._conformer_chains, + ) + + def num_atoms(self) -> int: + return len(self._mask) + + def get_elements(self) -> np.ndarray: + return self._elements.copy() + + def get_reference_positions(self) -> np.ndarray: + return self._positions.copy() + + def get_reference_space_uid(self) -> np.ndarray: + return self._spaces.copy() + + def iter_ligand_confs(self) -> Iterator[LigandConf]: + from rdkit import Chem + + for chain_index, chain in enumerate(self._chain_ids): + indices = np.flatnonzero( + self._mask & (self._chains == chain_index) & (self._types == "ligand") + ) + if not len(indices): + continue + source = self._ligand_mols.get(chain) + if source is None: + raise ValueError( + f"BioEmu2 chain {chain}: missing source ligand chemistry" + ) + source = Chem.RemoveAllHs(Chem.Mol(source)) + source_names = [ + atom.GetProp("atom_name") if atom.HasProp("atom_name") else None + for atom in source.GetAtoms() + ] + target_names = [decode_atom_name(self._names[i]) for i in indices] + if ( + None in source_names + or None in target_names + or len(set(source_names)) != len(source_names) + or len(set(target_names)) != len(target_names) + or not set(target_names).issubset(source_names) + ): + raise ValueError(f"BioEmu2 chain {chain}: ambiguous ligand atom names") + subset = Chem.RWMol(source) + for index in reversed(range(len(source_names))): + if source_names[index] not in target_names: + subset.RemoveAtom(index) + kept_names = [name for name in source_names if name in target_names] + stereo = Chem.RenumberAtoms( + subset.GetMol(), [kept_names.index(name) for name in target_names] + ) + if [a.GetAtomicNum() for a in stereo.GetAtoms()] != self._elements[ + indices + ].tolist(): + raise ValueError( + f"BioEmu2 chain {chain}: ligand element order mismatch" + ) + stereo.RemoveAllConformers() + coords = self._positions[indices] + yield LigandConf( + mol=mol_with_reference_conformer(stereo, coords), + conf_coords=coords.copy(), + global_indices=indices, + conformer_restraints=chain in self._conformer_chains, + stereo_mol=stereo, + ) diff --git a/src/rgi_toolkit/optim/_cuda_graph.py b/src/rgi_toolkit/optim/_cuda_graph.py index f0a786a..ec638fe 100644 --- a/src/rgi_toolkit/optim/_cuda_graph.py +++ b/src/rgi_toolkit/optim/_cuda_graph.py @@ -311,8 +311,11 @@ def child(graph): else rt.cudaGraphConditionalNodeType.cudaGraphCondTypeWhile ) parameters.conditional.size = len(bodies) + # CUDA 13 promoted the edge-data variant to the unversioned API. + add_node = getattr(rt, "cudaGraphAddNode_v2", rt.cudaGraphAddNode) + edge_data = [rt.cudaGraphEdgeData() for _ in last] last[:] = [ - checked(rt.cudaGraphAddNode(native, last, len(last), parameters)) + checked(add_node(native, last, edge_data, len(last), parameters)) ] for body, body_graph in zip(bodies, parameters.conditional.phGraph_out): end = self.emit(body, body_graph, required) diff --git a/src/rgi_toolkit/optim/_cuda_lbfgs.py b/src/rgi_toolkit/optim/_cuda_lbfgs.py index 23a2007..b9fbf58 100644 --- a/src/rgi_toolkit/optim/_cuda_lbfgs.py +++ b/src/rgi_toolkit/optim/_cuda_lbfgs.py @@ -1,4 +1,4 @@ -"""CUDA control flow following PyTorch 2.8 L-BFGS and Wolfe rules. +"""CUDA control flow following the supported PyTorch L-BFGS and Wolfe rules. Algorithm derived from torch.optim.lbfgs (BSD-3-Clause, PyTorch contributors). The host adapter retains the native optimizer for unsupported CUDA environments. @@ -12,6 +12,7 @@ from torch.utils import _pytree from rgi_toolkit.optim._cuda_lbfgs_scalars import LibraryScalars +from rgi_toolkit.optim._torch_lbfgs import BOUNDED_LINE_SEARCH @triton.jit @@ -98,7 +99,7 @@ def cubic(first, second, bounds=None): ) -def wolfe(s, vg, x, direction, value, gradient, slope, step): +def wolfe(s, vg, x, direction, value, gradient, slope, step, max_ls=25): def evaluate(t): g, f = vg( s.builder.call(torch.addcmul, x, direction, t.to(x.dtype), native=True) @@ -120,7 +121,7 @@ def evaluate(t): # Expansion stops as soon as a bracket or a Wolfe point is found. def bracket_condition(state): previous, current, iteration, done, bracketed, evaluations = state - return ~done & ~bracketed & (iteration < 25) + return ~done & ~bracketed & (iteration < max_ls) def bracket_body(state): previous, current, iteration, done, bracketed, evaluations = state @@ -157,7 +158,7 @@ def expand(_): s.integer(1), ), ) - previous = choose(iteration == 25, initial, previous) + previous = choose(iteration == max_ls, initial, previous) previous = choose(done, trial, previous) low = choose(previous.f <= trial.f, previous, trial) high = choose(previous.f <= trial.f, trial, previous) @@ -165,7 +166,7 @@ def expand(_): def zoom_condition(state): low, high, iteration, done, insufficient, evaluations = state - return ~done & (iteration < 25) & ~((high.t - low.t).abs() * norm < 1e-9) + return ~done & (iteration < max_ls) & ~((high.t - low.t).abs() * norm < 1e-9) def zoom_body(state): low, high, iteration, done, insufficient, evaluations = state @@ -314,7 +315,12 @@ def update(_): ) def search(_): - result, evaluations = wolfe(s, vg, state.x, d, state.f, state.g, slope, t) + max_ls = ( + max_iter * 5 // 4 - state.evaluations if BOUNDED_LINE_SEARCH else 25 + ) + result, evaluations = wolfe( + s, vg, state.x, d, state.f, state.g, slope, t, max_ls=max_ls + ) updated = s.builder.call( torch.addcmul, state.x, d, result.t.to(x.dtype), native=True ) diff --git a/src/rgi_toolkit/optim/_cuda_minimize.py b/src/rgi_toolkit/optim/_cuda_minimize.py index 4521099..29b059f 100644 --- a/src/rgi_toolkit/optim/_cuda_minimize.py +++ b/src/rgi_toolkit/optim/_cuda_minimize.py @@ -45,11 +45,11 @@ def eligible(optimizer, coords, max_iter, conformer_in_window): pairs += n_active * n_active if pairs * batch > MAX_PAIRS: return False - # Private FX/Inductor APIs and CUDA IF/ELSE capture are validated for Torch 2.8. + # Private FX/Inductor APIs and CUDA IF/ELSE capture are validated on these releases. # Other versions keep the existing optimizer instead of assuming compatibility. version = torch.__version__.split("+")[0].split(".")[:2] cuda = (torch.version.cuda or "0.0").split(".")[:2] - return version == ["2", "8"] and tuple(map(int, cuda)) >= (12, 8) + return version in (["2", "8"], ["2", "13"]) and tuple(map(int, cuda)) >= (12, 8) class GraphSolve: diff --git a/src/rgi_toolkit/optim/_torch_lbfgs.py b/src/rgi_toolkit/optim/_torch_lbfgs.py index 33a0c01..60b05b7 100644 --- a/src/rgi_toolkit/optim/_torch_lbfgs.py +++ b/src/rgi_toolkit/optim/_torch_lbfgs.py @@ -1,7 +1,8 @@ """PyTorch L-BFGS with device-resident coefficients for CUDA vector updates. The step follows torch.optim.LBFGS (PyTorch 2.8.0, BSD-3-Clause; see LICENSE). -History, line search, stopping rules and scalar precision are unchanged. +History, line search, stopping rules and scalar precision are unchanged, including +the line-search evaluation bound of the installed PyTorch release. """ import logging @@ -13,6 +14,10 @@ from rgi_toolkit.optim._torch_cg_gpu import _COMPILE_DISABLED logger = logging.getLogger(__name__) +# PyTorch 2.13 bounds each line search by the remaining evaluation budget. +BOUNDED_LINE_SEARCH = tuple( + map(int, torch.__version__.split("+")[0].split(".")[:2]) +) >= (2, 13) _ADD = None _ADD_FAILED = False _DIRECTION_FAILED = False @@ -188,6 +193,7 @@ def obj_func(x, t, _direction): loss, _SearchGradient(flat_grad), gtd, + max_ls=max_eval - current_evals if BOUNDED_LINE_SEARCH else 25, ) flat_grad = gradient.tensor self._add_grad(t, d) diff --git a/tests/ci.txt b/tests/ci.txt index 2f3a5fe..d37cba3 100644 --- a/tests/ci.txt +++ b/tests/ci.txt @@ -1,4 +1,5 @@ tests/test_adapters_shared.py +tests/test_bioemu2_adapter.py tests/test_align.py tests/test_chai_adapter.py tests/test_config_paths.py diff --git a/tests/test_bioemu2_adapter.py b/tests/test_bioemu2_adapter.py new file mode 100644 index 0000000..f64cf6a --- /dev/null +++ b/tests/test_bioemu2_adapter.py @@ -0,0 +1,126 @@ +"""BioEmu2 atom mapping, padding and source-chemistry contracts.""" + +import subprocess +import sys + +import numpy as np +import pytest +from rdkit import Chem + +from rgi_toolkit.bioemu2 import BioEmu2Adapter + + +def _codes(names): + return [[ord(c) - 32 for c in name.ljust(4)] for name in names] + + +def adapter(**overrides): + source = Chem.MolFromSmiles("C[N+](C)(C)C") + for atom in source.GetAtoms(): + atom.SetProp("atom_name", f"{atom.GetSymbol()}{atom.GetIdx()}") + values = dict( + chain_ids=["A", "B", "L"], + atom_chain_indices=[0, 0, 0, 1, 1, 2, 2, 2, 2, 2, -1], + atom_to_token_map=[4, 4, 9, 20, 20, 35, 36, 37, 38, 39, -1], + atom_mask=[True] * 10 + [False], + atom_name_codes=_codes( + ["N", "CA", "CA", "N", "CA", "C4", "C3", "C2", "N1", "C0", ""] + ), + residue_names=["GLY", "GLY", "ALA", "MSE", "MSE"] + ["LIG"] * 5 + [None], + mol_types=["protein"] * 5 + ["ligand"] * 5 + [None], + elements=[7, 6, 6, 7, 6, 6, 6, 6, 7, 6, 99], + ref_pos=np.arange(33).reshape(11, 3) * 0.1, + ref_space_uid=[1, 1, 2, 3, 3, 4, 4, 4, 4, 4, -1], + conformer_chains=["B", "L"], + ligand_mols={"L": source}, + ) + values.update(overrides) + return BioEmu2Adapter(**values) + + +def test_padded_atom_indices_and_per_chain_token_ordinals(): + ad = adapter() + records = list(ad.iter_atoms()) + assert [record.index for record in records] == list(range(10)) + assert [record.resid for record in records] == [1, 1, 2, 1, 1, 1, 2, 3, 4, 5] + assert records[3].mol_type == "protein" and records[3].resname == "MSE" + assert records[3].conformer_restraints and not records[0].conformer_restraints + assert ad.num_atoms() == 11 + assert ad.get_elements()[-1] == 0 + assert not ad.get_reference_positions()[-1].any() + assert ad.get_reference_space_uid()[-1] == -1 + + +def test_name_mapping_preserves_charge_and_does_not_mutate_source(): + ad = adapter() + source = ad._ligand_mols["L"] + before = Chem.MolToSmiles(source) + (ligand,) = ad.iter_ligand_confs() + assert ligand.global_indices.tolist() == [5, 6, 7, 8, 9] + assert ligand.mol.GetAtomWithIdx(3).GetFormalCharge() == 1 + assert ligand.stereo_mol.GetAtomWithIdx(3).GetFormalCharge() == 1 + assert ligand.conformer_restraints + assert Chem.MolToSmiles(source) == before + np.testing.assert_equal(ligand.conf_coords, ad.get_reference_positions()[5:10]) + + +def test_named_leaving_atoms_are_removed_without_renumbering_coordinates(): + source = Chem.MolFromSmiles("CCO") + for atom, name in zip(source.GetAtoms(), ["C0", "C2", "O1"]): + atom.SetProp("atom_name", name) + ad = adapter( + atom_mask=[True] * 7 + [False] * 4, + atom_name_codes=_codes( + ["N", "CA", "CA", "N", "CA", "C2", "C0", "", "", "", ""] + ), + ligand_mols={"L": source}, + ) + (ligand,) = ad.iter_ligand_confs() + assert ligand.global_indices.tolist() == [5, 6] + assert ligand.mol.GetNumAtoms() == 2 + assert ligand.mol.GetNumBonds() == 1 + assert source.GetNumAtoms() == 3 + + +def test_no_conformer_flags_means_no_opt_in(): + ad = adapter(conformer_chains=[]) + assert not any(record.conformer_restraints for record in ad.iter_atoms()) + assert not next(ad.iter_ligand_confs()).conformer_restraints + + +def test_invalid_source_mapping_fails_instead_of_restraining_wrong_atoms(): + ad = adapter() + ad._ligand_mols["L"].GetAtomWithIdx(0).SetProp("atom_name", "missing") + with pytest.raises(ValueError, match="ambiguous ligand atom names"): + list(ad.iter_ligand_confs()) + with pytest.raises(ValueError, match="missing source ligand"): + list(adapter(ligand_mols={}).iter_ligand_confs()) + with pytest.raises(ValueError, match="element order"): + list(adapter(elements=[7, 6, 6, 7, 6, 8, 6, 6, 7, 6, 0]).iter_ligand_confs()) + + +@pytest.mark.parametrize( + "overrides", + [ + {"atom_to_token_map": [0]}, + {"atom_name_codes": np.zeros((11, 3))}, + {"ref_pos": np.full((11, 3), np.nan)}, + {"atom_chain_indices": [3] * 11}, + {"conformer_chains": ["unknown"]}, + ], +) +def test_inconsistent_metadata_is_rejected(overrides): + with pytest.raises(ValueError, match="BioEmu2"): + adapter(**overrides) + + +def test_import_does_not_load_predictor_or_compute_backends(): + subprocess.run( + [ + sys.executable, + "-c", + "import sys; import rgi_toolkit.bioemu2; " + "assert not {'torch', 'jax', 'bioemu2', 'biotite'} & sys.modules.keys()", + ], + check=True, + ) diff --git a/tests/test_config_validator.py b/tests/test_config_validator.py index 88d92cc..59adc85 100644 --- a/tests/test_config_validator.py +++ b/tests/test_config_validator.py @@ -208,22 +208,41 @@ def test_validator_checks_base_triple_and_empty_windows(validator): for path in (ROOT / "examples").glob(pattern) if path.suffix in {".json", ".yaml", ".yml", ".py"} and path.is_file() ) +PYTHON_CONFIGS = { + path: [ + ast.literal_eval(node.value) + for node in ast.parse(path.read_text(), filename=str(path)).body + if isinstance(node, ast.Assign) + and any( + isinstance(target, ast.Name) and target.id == "RESTRAINTS_CONFIG" + for target in node.targets + ) + ] + for path in EXAMPLES + if path.suffix == ".py" +} +CONFIG_EXAMPLES = [ + path for path in EXAMPLES if path.suffix != ".py" or PYTHON_CONFIGS[path] +] + + +@pytest.mark.parametrize("path", PYTHON_CONFIGS, ids=lambda p: str(p.relative_to(ROOT))) +def test_python_examples_compile_without_importing_predictors(path): + compile(path.read_text(), str(path), "exec") -@pytest.mark.parametrize("path", EXAMPLES, ids=lambda p: str(p.relative_to(ROOT))) +def test_each_example_directory_has_a_config(): + assert {path.parent for path in CONFIG_EXAMPLES} == { + path.parent for path in EXAMPLES + } + + +@pytest.mark.parametrize( + "path", CONFIG_EXAMPLES, ids=lambda p: str(p.relative_to(ROOT)) +) def test_example_configs_pass_validator(validator, path): if path.suffix == ".py": - tree = ast.parse(path.read_text()) - config = next( - ast.literal_eval(node.value) - for node in tree.body - if isinstance(node, ast.Assign) - and any( - isinstance(t, ast.Name) and t.id == "RESTRAINTS_CONFIG" - for t in node.targets - ) - ) - data = config + data = PYTHON_CONFIGS[path] else: data = validator["_load"](path) found = list(validator["_find_configs"](data)) diff --git a/tests/test_torch_lbfgs.py b/tests/test_torch_lbfgs.py index f28dd11..13f43f7 100644 --- a/tests/test_torch_lbfgs.py +++ b/tests/test_torch_lbfgs.py @@ -93,6 +93,28 @@ def closure(): torch.testing.assert_close(*outputs, atol=3e-5, rtol=0) +@pytest.mark.gpu +@pytest.mark.parametrize("max_iter", [1, 2, 3, 8]) +def test_cuda_lbfgs_matches_upstream_line_search_budget(max_iter): + initial = torch.tensor([-1.2, 1.0], dtype=torch.float64, device="cuda") + results = [] + for optimizer in (torch.optim.LBFGS, impl.CudaLBFGS): + x = initial.clone().requires_grad_() + opt = optimizer([x], max_iter=max_iter, line_search_fn="strong_wolfe") + + def closure(): + opt.zero_grad() + loss = 100 * (x[1] - x[0] ** 2) ** 2 + (1 - x[0]) ** 2 + loss.backward() + return loss + + opt.step(closure) + results.append((x.detach(), opt.state[x]["func_evals"])) + (expected, expected_evals), (actual, actual_evals) = results + assert actual_evals == expected_evals + torch.testing.assert_close(actual, expected, atol=1e-12, rtol=0) + + @pytest.mark.gpu def test_failed_cuda_kernels_use_original_updates_and_do_not_retry(monkeypatch): calls = [] diff --git a/uv.lock b/uv.lock index ae88f41..af2c49e 100644 --- a/uv.lock +++ b/uv.lock @@ -791,7 +791,7 @@ wheels = [ [[package]] name = "rgi-toolkit" -version = "0.4.6" +version = "0.4.7" source = { editable = "." } dependencies = [ { name = "biopython" }, @@ -829,7 +829,7 @@ dev = [ [package.metadata] requires-dist = [ { name = "biopython", specifier = ">=1.84" }, - { name = "cuda-bindings", marker = "sys_platform == 'linux' and extra == 'torch'", specifier = ">=12.8,<13" }, + { name = "cuda-bindings", marker = "sys_platform == 'linux' and extra == 'torch'", specifier = ">=12.8,<14" }, { name = "filelock", specifier = ">=3" }, { name = "gemmi", specifier = ">=0.6.5" }, { name = "ipython", marker = "extra == 'notebook'", specifier = ">=8" },