Docs rfd3 adv enzyme tutorial

models/rfd3/docs/common_issues.md

@@ -0,0 +1,21 @@
+# Common Issues
+
+## Contents
+
+## Ligand Code Conflicts with the CCD
+### Issue Description
+The [chemical component dictionary (CCD)](https://www.wwpdb.org/data/ccd) has assigned codes to all small molecule and residues that appear in the [PDB](https://www.rcsb.org/). RFD3 (via [AtomWorks](https://github.com/RosettaCommons/atomworks)) can match these codes to their conformational structues in the CCD. However, and especially for enzyme design problems, the ligand structure you are using may be a transition state structure and will purposefully not match what is in the CCD. If this happens you will see several warning messages before the inference run crashes: 
+```{bash}
+WARNING:atomworks.ml:Atom ZN1 not found in conformer for residue TSA ...
+WARNING:atomworks.ml:Atom P1 not found in conformer for residue TSA ...
+WARNING:atomworks.ml:Atom N1 not found in conformer for residue TSA ...
+... (many more "Atom not found" warnings) ...
+
+ValueError: Transforms failed at stage `CreateDesignReferenceFeatures`:
+could not broadcast input array from shape (16,3) into shape (53,3)
+```
+
+The shape mismatch error is how you know this particular issue is occuring. 
+
+### Solution
+You need to give your ligand a name that does not match any in the CCD. We recommend adding a colon or semicolon to the three-letter code, for example `L:G`. These characters render the code invalid for the CCD, so RFD3 will not try to match it to a known structure and instead use the structure from your PDB directly. You will need to update this label in both your input PDB/CIF file and your input JSON/YAML file. 

models/rfd3/docs/design_areas/enzyme_design_tips.md

@@ -0,0 +1,2 @@
+# Tips for Designing Enzymes with RFdiffusion3
+

models/rfd3/docs/index.rst

@@ -6,6 +6,14 @@ study ligand-protein interactions, create nucleic acid-protein interfaces, and
 design *de novo* enzymes. It is designed to be highly flexible and 
 user-friendly, making it suitable for a wide range of applications in computational biology and biochemistry.
 
+New to RFD3?
+------------
+If you haven't installed RFD3 yet, take a look at the `RFD3 README <https://github.com/RosettaCommons/foundry/blob/production/models/rfd3/README.md#getting-started>`_ or, if you are on a UNIX system, see the :doc:`tutorials/RFdiffusion3_installation_tutorial` .
+
+Once you have everything installed, check out one of our Introductory Tutorials, listed below. 
+
+.. _rfd3_general:
+
 General
 -------
 .. toctree::
@@ -14,7 +22,20 @@ General
    tutorials/RFdiffusion3_installation_tutorial.md
    intro_inference_calculations.md
    input.md
+   output.md
+   common_issues.md
+
+.. _rfd3_design_tips:
+
+RFD3 Design Tips
+----------------
+.. toctree::
+   :maxdepth: 1
+
    designability_vs_diversity.md
+   design_areas/enzyme_design_tips.md
+
+.. _rfd3_introductory_tutorials:
 
 Introductory Tutorials
 ----------------------
@@ -28,6 +49,8 @@ with the capabilities of RFD3 for specific design tasks.
    tutorials/enzyme_design_tutorial.md
    tutorials/na_binder_tutorial.md
 
+.. _rfd3_intermediate_tutorials:
+
 Intermediate Tutorials
 ----------------------
 These intermediate tutorials cover more complex topics related
@@ -39,6 +62,19 @@ RFD3, we recommend starting with the introductory tutorials before moving on to
 
    tutorials/intermediate_enzyme_design_tutorial.md
 
+.. _rfd3_advanced_tutorials:
+
+Advanced Tutorials
+------------------
+The advanced RFdiffusion3 tutorials focus on more complex design tasks and provide in-depth explanations of the underlying principles and techniques used in RFD3. These tutorials assume some knowledge of the use of PyMOL (or other visualization software) and basic RFdiffusion3 concepts that are described in the introductory and intermediate tutorials.
+
+.. toctree::
+   :maxdepth: 1
+
+   tutorials/advanced_enzyme_design_tutorial.md
+
+.. _rfd3_examples:
+
 Examples
 --------
 The following examples demonstrate how to use RFD3 for various design

models/rfd3/docs/input.md

@@ -22,6 +22,7 @@ This document outlines the various input settings and configurations you can use
   - [Partial Diffusion](#partial-diffusion)
   - [CIF Parser Options](#cif-parser-options)
   - [Select Fixed Atoms](#select-fixed-atoms)
+  - [Ligand Chain Assignment](#ligand-chain-assignment)
 - [Debugging recommendations](#debugging-recommendations)
 - [FAQ / Gotchas](#faq--gotchas)
 
@@ -126,6 +127,7 @@ Below is a table of all of the inputs that the `InputSpecification` accepts. Use
 | `unindex`                                                      | `InputSelection`  | (Can only pass a contig string or dictionary.) Unindexed motif components, the specified residues can be anywhere in the final sequence. See [Unindexing Specifics](#unindexing-specifics) for more information. |
 | `length`                                                       | `str`             | Total design length constraint; `"min-max"` or int for specified length.                   |
 | `ligand`                                                       | `str`             | Ligand(s) by chemical component name (from [RSCB PDB](https://www.rcsb.org/)) or index. |
+| `allow_ligand_on_existing_chain`                                | `bool`            | Default `False`. If `True`, suppresses the error raised when a `ligand` shares a chain ID with a chain already present in the built structure (and permits multiple ligand residues to sit on the same chain). See [Ligand Chain Assignment](#ligand-chain-assignment) for more information. Use with caution — chain ID is leaked to the model, so collisions are a meaningful deviation from convention. |
 | `cif_parser_args`                                              | `dict`            | Optional args to CIF loader. See [CIF parser options](#cif-parser-options) for more information. |
 | `extra`                                                        | `dict`            | Extra metadata (e.g., logs). Current options include `sampled_contig`. |
 | `dialect`                                                      | `int`             | `2`=new (default), `1`=legacy, Learn more about the legacy parsing system by looking at [input_parsing.py](https://github.com/RosettaCommons/foundry/blob/production/models/rfd3/src/rfd3/inference/input_parsing.py).|
@@ -284,6 +286,13 @@ The `select_fixed_atoms` input setting can take a boolean, dictionary or contig
 - Contig string: See the [Contig Strings](#contig-strings) section for formatting. Specifying a contig string for this setting allows for the specification of several components to fix in 3D space. This string should only reference residues from the input. Chain breaks are irrelevant for this setting. 
 - Dictionary: Allows for the specification of specific atoms within the residue to be fixed in 3D space. For example, `{"A1": "N,CA,C,O,CB,CG", "A2-10": "BKBN"}` fixes backbone and CB for residues 1 and 2, and all atoms for residues 3-10 in chain A.
 
+(ligand-chain-assignment)=
+### Ligand Chain Assignment
+By default (`allow_ligand_on_existing_chain: false`), RFD3 validates the chain ID(s) assigned to any `ligand` you request against the chains already present in the built structure (i.e. those coming from `contig`/`unindex`/designed regions). This matters because chain ID is leaked to the model, so an unexpected chain collision is a meaningful deviation from convention and often indicates a misconfigured `ligand` or `contig` string. With the default behavior:
+- An error is raised if a requested ligand's chain ID overlaps with a chain ID already used in the built structure.
+- An error is raised if multiple ligand residues are placed on the same chain — each ligand residue must occupy its own chain.
+- Ligand `res_id` values are reset to start from `1` per chain, matching the convention used in AlphaFold3 output CIF files.
+
 (debugging-recommendations)=
 ## 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.