Merge pull request #54 from RosettaCommons/fix/readmes

Fixes: Turn off prevalidation by default, update README with new files

Author: Ubiquinone-dot

.github/workflows/lint_trunk.yaml .github/workflows/lint_production.yaml.github/workflows/lint_trunk.yaml renamed to .github/workflows/lint_production.yaml

@@ -1,10 +1,10 @@
-name: lint_trunk
+name: lint_production
 
 on:
   push:
-    branches: [main, trunk, wip/for-release, wip/remove-chemdata]
+    branches: [main, production, wip/for-release, wip/remove-chemdata]
   pull_request:
-    branches: [main, trunk, wip/for-release, wip/remove-chemdata]
+    branches: [main, production, wip/for-release, wip/remove-chemdata]
   pull_request_target:
     types: [ready_for_review]
   workflow_dispatch:
@@ -23,14 +23,15 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
-          python-version: "3.11"
+          python-version: "3.12"
           cache: 'pip'
-      - name: Extract ruff version from requirements.txt
+      - name: Extract ruff version from pyproject.toml
         run: |
-          echo "RUFF_VERSION=$(grep 'ruff==' pyproject.toml | sed 's/.*ruff==\(.*\)/\1/')" >> $GITHUB_ENV
+          echo "RUFF_VERSION=$(grep 'ruff==' pyproject.toml \
+            | sed -E 's/.*ruff==([^",]+).*/\1/')" >> "$GITHUB_ENV"
       - name: Install ruff
         run: pip install ruff==${{ env.RUFF_VERSION }}
       - name: Ruff format
-        run: ruff format --diff src tests scripts notebooks
+        run: ruff format --diff src models tests
       - name: Ruff check
-        run: ruff check src tests scripts notebooks
+        run: ruff check src models tests

models/rfd3/README.md

@@ -25,15 +25,22 @@ This sets `FOUNDRY_CHECKPOINTS_DIR` and will in future look for checkpoints in t
 
 To run inference (with foundry installed in your environment, or RFD3 & Foundry src in PYTHONPATH):
 ```bash
-rfd3 design out_dir=logs/inference_outs/demo/0 inputs=models/rfd3/docs/demo.json skip_existing=False dump_trajectories=True
+rfd3 design out_dir=logs/inference_outs/demo/0 inputs=models/rfd3/docs/demo.json skip_existing=False dump_trajectories=True prevalidate_inputs=True
 ```
 
-Additional unecessary args here are added:
+Additional unnecessary args here are added:
 - Including dumping and aligning trajectory structures can be useful for debugging your setup or making cool gifs.
 - Printing the config and dumping trajectories are turned off by default, but turned on here for verbosity
-- Only `out_dir` and `inputs` are required
+- `prevalidate_inputs` will check that your inputs are valid before running inference. Helpful if your json has a number of different configs you want to debug / double check are valid before loading the checkpoints.
+- Only `out_dir` and `inputs` are required. The output directory will automatically be created. 
 
-The output directory will automatically be created.
+
+There are various interesting ways you can use RFD3 beyond Atom14 design as it's trained on a large array of different tasks.
+For example, you can fix sequence and not structure (prediction-type task), fix the backbone and unfix the sequence (MPNN-type inverse folding) or unfix the sidechains only (PLACER/ChemNet-style):
+
+<p align="center">
+  <img src="docs/.assets/conditioning.png" alt="Conditioning options for RFD3">
+</p>
 
 For full details on how to specify inputs, see the [input specification documentation](./docs/input.md). You can also see `foundry/models/rfd3/configs/inference_engine/rfdiffusion3.yaml` for even more options.
 

models/rfd3/configs/inference_engine/rfdiffusion3.yaml

@@ -61,5 +61,5 @@ global_prefix: null
 dump_prediction_metadata_json: True
 dump_trajectories: False
 align_trajectory_structures: False
-prevalidate_inputs: True
+prevalidate_inputs: False
 low_memory_mode: False # False for standard mode, True for memory efficient tokenization mode

models/rfd3/docs/.assets/conditioning.png

@@ -1,46 +1,39 @@
 # RFdiffusion3 — Input specification (dialect **2**)
 
-> **TL;DR**  
-> Inputs are now defined with a single `InputSpecification` class.  
-> Selections like “what’s fixed?”, “what’s sequence-free?”, “which atoms are donors/acceptors?” are all expressed with the same **InputSelection** mini-language.  
-> Everything is reproducibly logged back out alongside your generation.
-
 ---
 
-- [What changed (high level)](#what-changed-high-level)
+## Contents
 - [Quick start](#quick-start)
+- [InputSpecification fields](#inputspecification-fields)
 - [The `InputSelection` mini-language](#the-inputselection-mini-language)
-- [Full schema: `InputSpecification`](#full-schema-inputspecification)
-- [Common recipes (cookbook)](#common-recipes-cookbook)
+- [Unindexing specifics](#unindexing-specifics)
 - [Partial diffusion](#partial-diffusion)
-- [Symmetry](#symmetry)
-- [Origin (`ori_token`) and initialization](#origin-ori_token-and-initialization)
-- [Validation & error messages](#validation--error-messages)
-- [Metadata & logging](#metadata--logging)
-- [Legacy configs (dialect=1) & migration guide](#legacy-configs-dialect1--migration-guide)
-- [Multi-example files](#multi-example-files)
+- [Debugging recommendations](#debugging-recommendations)
 - [FAQ / gotchas](#faq--gotchas)
 
 ---
 
-## How it works (high level)
+## Quick start
 
-- **Unified selections.** All per-residue/atom choices now use **InputSelection**:
-  - You can pass `true`/`false`, a **contig string** (`"A1-10,B5-8"`), or a **dictionary** (`{"A1-10": "ALL", "B5": "N,CA,C,O"}`).
-  - Selection fields include: `select_fixed_atoms`, `select_unfixed_sequence`, `select_buried`, `select_partially_buried`, `select_exposed`, `select_hbond_donor`, `select_hbond_acceptor`, `select_hotspots`.
-- **Clearer unindexing.** For **unindexed** motifs you typically either fix `"ALL"` atoms or explicitly choose subsets such as `"TIP"`/`"BKBN"`/explicit atom lists via a **dictionary** (see examples).  
-  When using `unindex`, only **the atoms you mark as fixed** are carried over from the input.
-- **Reproducibility.** The exact specification and the **sampled contig** are logged back into the output JSON. We also log useful counts (atoms, residues, chains).
-- **Safer parsing.** You’ll now get early, informative errors if:
-  - You pass unknown keys,
-  - A selection doesn’t match any atoms,
-  - Indexed and unindexed motifs overlap,
-  - Mutually exclusive selections overlap (e.g., two RASA bins for the same atom).
-- **Backwards compatible.** Add `"dialect": 1` to keep your old configs running while you migrate. (Deprecated.)
+JSON inputs take the following top-level structure;
+```json
+{
+    "spec-1": {  // First design configuration
+      "input": "<path/to/pdb>",
+      "contig": "50-80,/0,A1-100",  // Diffuses length 50-80 monomer in chain A & selects indices A1 -> A100 in input pdb to have fixed coordinates and sequences  
+      "select_unfixed_sequence": "A20-35", // Converts selected indices in input to have unfixed sequence (inputs become atom14).
+      "ligand": "HAX,OAA",  // Selects ligands HAX and OAA based on res name in the input
+    },
+    "spec-2": {
+      // ... args for the second (independent) configuration for design. 
+    }
+}
+```
 
----
+## InputSpecification fields
+
+Below is a table of all of the inputs that the `InputSpecification` accepts. Use these fields to describe what RFdiffusion3 should do with your inputs.
 
-## InputSpecification
 
 | Field                                                          | Type              | Description                                                           |
 | -------------------------------------------------------------- | ----------------- | --------------------------------------------------------------------- |
@@ -67,118 +60,110 @@
 | `partial_t`                                                    | `float?`          | Noise (Å) for partial diffusion, enables partial diffusion            |
 
 
-## Quick start
-
-### Minimal JSON example
-
-```json
-{
-    "": {
-    "input": "path/to/template.pdb",
-    "contig": "A1-80",
-    "length": "150-180",
-    "select_fixed_atoms": true,
-    "select_unfixed_sequence": "A20-35",
-    "ligand": "HAX,OAA",
-    "dialect": 2
-    }   
-}
-```
-### Mininmal YAML example
-```
-input: path/to/template.pdb
-contig: A1-80
-length: 150-180
-select_fixed_atoms: true
-select_unfixed_sequence: A20-35
-ligand: HAX,OAA
-dialect: 2
-
-```
-
-### Python API
-```
-from rfd3.inference.input_parsing import create_atom_array_from_design_specification
-
-atom_array, metadata = create_atom_array_from_design_specification(
-    input="path/to/template.pdb",
-    contig="A1-80",
-    length="150-180",
-    select_fixed_atoms=True,
-    select_unfixed_sequence="A20-35",
-    dialect=2,
-)
-```
+A few notes on the above:
+- **Unified selections.** All per-residue/atom choices now use **InputSelection**:
+  - You can pass `true`/`false`, a **contig string** (`"A1-10,B5-8"`), or a **dictionary** (`{"A1-10": "ALL", "B5": "N,CA,C,O"}`).
+  - Selection fields include: `select_fixed_atoms`, `select_unfixed_sequence`, `select_buried`, `select_partially_buried`, `select_exposed`, `select_hbond_donor`, `select_hbond_acceptor`, `select_hotspots`.
+- **Clearer unindexing.** For **unindexed** motifs you typically either fix `"ALL"` atoms or explicitly choose subsets such as `"TIP"`/`"BKBN"`/explicit atom lists via a **dictionary** (see examples).  
+  When using `unindex`, only **the atoms you mark as fixed** are carried over from the input.
+- **Reproducibility.** The exact specification and the **sampled contig** are logged back into the output JSON. We also log useful counts (atoms, residues, chains).
+- **Safer parsing.** You’ll now get early, informative errors if:
+  - You pass unknown keys,
+  - A selection doesn’t match any atoms,
+  - Indexed and unindexed motifs overlap,
+  - Mutually exclusive selections overlap (e.g., two RASA bins for the same atom).
+- **Backwards compatible.** Add `"dialect": 1` to keep your old configs running while you migrate. (Deprecated.)
 
+---
 ## The InputSelection mini-language
 
-Fields which are specified as `InputSelection` are fields which can take either: `Bool, List, Dict`.
-Dictionaries are the most expressive and can also take special :
+Fields marked as `InputSelection` accept either a boolean, a contig-style string, or a dictionary. Dictionaries are the most expressive and can also use shorthand values like `ALL`, `TIP`, or `BKBN`:
 ```yaml
 select_fixed_atoms:
-  A1-2: BKBN
+  A1-2: BKBN # equivalent to 'N,CA,C,O'
   A3: N,CA,C,O,CB  # specific atoms by atom name
   B5-7: ALL # Selects all atoms within B5,B6 and B7
-  B10: TIP  # selects common tipatom for residue (constants.py)
+  B10: TIP  # selects common tip atom for residue (constants.py)
   LIG: ''  # selects no atoms (i.e. unfixes the atoms for ligands named `LIG`)
 ```
 
-[Diagram]
+<p align="center">
+  <img src=".assets/input_selection.png" alt="InputSelection language for foundry">
+</p>
 
 ## Unindexing specifics
 
 `unindex` marks motif tokens whose relative sequence placement is unknown to the model (useful for scaffolding around active sites, etc.).
 Use a string to list the unindexed components and where breaks occur.
 Use a dictionary if you want to fix specific atoms of those residues; atoms not fixed are not copied from the input (they will be diffused).
-Breaks between unindexed components follow the contig conventions you’re used to. For example:
-
-`"A244,A274,A320,A329,A375"`
+Breaks between unindexed components follow the contig conventions you’re used to. For example: `"A244,A274,A320,A329,A375"` lists multiple unindexed components; internal “breakpoints” are inferred and logged. (Offset syntax like A11-12 or A11,0,A12 still ties residues.)
+You can specify consecutive residues as e.g. `A11-12` (instead of `A11,A12`), this will tie the two components together in sequence (or at least it leaks to the model that residues are together in sequence). 
+Similarly, you can specify manually any number of residues that offsets two components, e.g. `A11,0,A12` (0 sequence offset, equivalent to just `A11-12`), or `A11,3,A12` (3-residue separation).
+From our initial tests this only leads to a slight bias in the model, but newer models may show better adherence!
+
+## Partial Diffusion
+To enable partial diffusion, you can pass `partial_t` with any example. This sets the *noise level* in *angstroms* for the sampler:
+- The `specification.partial_t` argument can be specified from JSON or the command line.
+- Partial diffusion will fix/unfix ligands and nucleic acids as normal, by default it will fix non-protein components and they must be specified explicitly.
+- By default, the ca-aligned `ca_rmsd_to_input` will be logged.
+- Currently, partial diffusion subsets the inference schedule based on the partial_t, so `inference_sampler.num_timesteps` will affect how many steps are used but it is not equal to the number of steps used.
+
+In the following example, RFD3 will noise out by 15 angstroms and constrain atoms of three residues. In this output one of the 8 diffusion outputs swapped its sequence index by one residue:
+```json
+{
+    "partial_diffusion": {
+        "input": "paper_examples/7v11.cif", 
+        "ligand": "OQO", 
+        "partial_t": 15.0,
+        "unindex": "A431,A572-573",
+        "select_fixed_atoms": {
+            "A431": "TIP",
+            "A572": "BKBN",
+            "A573": "BKBN"
+        }
+    }
+}
+```
+Below is an example of what the output should look like (diffusion outputs in teal, original native in navajo white):
+<p align="center">
+  <img src=".assets/partial_diff.png" alt="Partial diffusion" width=650>
+</p>
 
-lists multiple unindexed components; internal “breakpoints” are inferred and logged. (Offset syntax like A11-12 or A11,0,A12 still ties residues.)
+## Debugging recommendations
+- For unindexed scaffolding, you can use the option `cleanup_guideposts=False` to keep the models' outputs for the guideposts. The guideposts are saved as separate chains based on whether their relative indices were leaked to the model: e.g. for `unindex=A11-12,A22`, you should see `A11` and `A12` indexed together on one chain and `A22` on its own chain, indicating the model was provided with the fact that `A11` and `A12` are immediately next to one another in sequence but their distance to `A22` is unknown.
+- To see the full 14 diffused virtual atoms you can use `cleanup_virtual_atoms=False`. Default is to discard them for the sake of downstream processing.
+- To see the trajectories, you can use `dump_trajectories=True`. This can be useful if the outputs look strange but the config is correct, or if you want to make cool gifs of course! Trajectories do not have sequence labels and contain virtual atoms.
 
-# Appendix
 ## FAQ / gotchas
 <details>
-  <summary><b>Do I need select_fixed_atoms & select_unfixed_sequence every time?</b></summary>
-
-  No. Defaults apply when input present.
+  <details>
+  <summary><b>Can I guide on secondary structure?</b></summary>
+  Currently no - in future models we may do so, however, you can use `is_non_loopy: true` to make fewer loops. We find this produces a lot more helices and fewer loops (and less sheets).
   </details>
 
-<details>
   <summary><b>Do I need select_fixed_atoms & select_unfixed_sequence every time?</b></summary>
-
+  
   No. Defaults apply when input present.
   </details>
 
   <details>
-  <summary><b>What does "ALL" vs "TIP" in unindex mean?</b></summary>
-
-  - **`ALL`** → copy full residue
-  - **`TIP`** → fix only sidechain tip atoms
-  </details>
-
-  <details>
-  <summary><b>Can selections overlap?</b></summary>
-
-  Only certain ones (fixed vs unfixed) may; RASA & donor/acceptor cannot.
-  </details>
-
-  <details>
-  <summary><b>How to fix backbone but redesign sidechains?</b></summary>
+  <summary><b>Why "Input provided but unused"?</b></summary>
 
-  `redesign_motif_sidechains: true`
+  This indicates you gave an input pdb / cif (not `input: null`) but no contig, unindex, ligand or partial_t.
   </details>
 
   <details>
-  <summary><b>Why "Input provided but unused"?</b></summary>
+  <summary><b>What do the logged bfactors mean?</b></summary>
 
-  You gave input but no contig, unindex, or partial_t.
+  The sequence head from RFD3 logs its confidence for each token in the output structure, you can run `spectrum b` in `pymol` to see it. It usually doesn't mean anything but can give you some idea if the model has gone vastly distribution if the entropy is high (uncertain assignment of sequence).
   </details>
+</details>
 
-## Shorthand atoms for easy specification
-Keyword	Expands to
-BKBN	N, CA, C, O
-TIP	Residue-specific “tip” atoms
-ALL	All atoms of each residue
+Let us know if you have any additional questions, we'd be happy to answer them!
 
+## Further examples of InputSelection syntax
 
+Below is a reference for more examples of different ways you can specify inputs to select from your pdb in configs; we hope the community can find use in this flexible system for future models!
+<p align="center">
+  <img src=".assets/input_selection_large.png" alt="Input selection syntax" width=650>
+</p>