Enzyme Design Tutorial

models/rfd3/README.md

@@ -170,7 +170,7 @@ further optimization!
 
 In `models/rfd3/configs/datasets/design_base.yaml` there's the shared configs for all datasets under `global_transform_args`. The dials that control the conditioning described above go under `training_conditions`, where for example `tipatom` - a specific preset conditioning sampler which more frequently fixes few tokens with few atoms - and others can be found.
 
-**Training with WandB:** We strongly recommend tracking your runs via wandb. To use it, simply have your WANDB_API_KEY set and use the wandb logger. For more details see [here](wandb.ai)
+**Training with WandB:** We strongly recommend tracking your runs via wandb. To use it, simply have your WANDB_API_KEY set and use the wandb logger. For more details see [here](https://wandb.ai/site/)
 
 # Appendix
 

models/rfd3/docs/enzyme_design_tutorial.md

@@ -0,0 +1,177 @@
+# Enzyme Design in RFdiffusion3
+
+## Before We Get Started...
+This tutorial does not cover installing RFD3. If you need to install this model, see the [README](https://github.com/RosettaCommons/foundry/tree/production/models/rfd3) for installation instructions. You will need to remember the path to the directory where you stored your checkpoint files, if you did not store them in the default location.
+
+```{note}
+You will need to clone the repository to access the tutorial files. Using the `pip` commands to install the model does not automatically download the files in the repository to your system.
+```
+
+Make sure you have activated any environment(s) you used to install RFD3.
+
+RFD3 runs best on GPUs. It is suggested to follow this tutorial on an interactive GPU node if you have access to one.
+
+You will need the file `1euv_lig.pdb`. This is provided in [`foundry/models/rfd3/docs/enzyme_tutorial_files/`](enzyme_tutorial_files/1euv_lig.pdb). You can clone the [`foundry`](https://github.com/RosettaCommons/foundry) repository to easily access files related to this tutorial. 
+
+<!-- Lastly, we will be visualizing the outputs of the calculations presented in the tutorial using [PyMOL](https://pymol.org/). The visualization steps are completely optional, but if you would like to follow along you will need to have PyMOL installed.--> 
+
+(enzyme-learning-objectives)=
+## Learning Objectives
+In this tutorial, we will use RFdiffusion3 to design cysteine hydrolases, similar to what is described in [*De novo* design of All-atom Biomolecular Interactions with RFdiffusion3](https://www.biorxiv.org/content/10.1101/2025.09.18.676967v2). This will allow us to explore the constraint options useful in enzyme design tasks. 
+
+(enzyme-setup)=
+## Setup
+Create a directory named `rfd3_enzyme_tutorial` and `cd` into it:
+```bash
+mkdir rfd3_enzyme_tutorial && cd rfd3_enzyme_tutorial
+```
+This is where you will be storing the files related to this tutorial. 
+
+If you would like to compare your outputs against those generated by the authors of this tutorial, you can find pre-generated output files in `foundry/models/rfd3/docs/enzyme_tutorial_files/outputs.zip`.
+
+There is also a pre-made JSON file available in `foundry/models/rfd3/docs/enzyme_tutorial_files`. We recommend following the tutorial to create this file yourself to better understand the RFD3 options that are relevant to enzyme design. 
+
+(enzyme-creating-the-json-file)=
+## Creating the JSON file
+In the next few sections we will be briefly describing the settings we will be using for this example enzyme design project. If you would like more information about the options discussed here or information about the other options that are available, see the [input specification](input.md) documentation.
+
+1. Using your editor of choice, open a new file called `rfd3_enzyme_tutorial.json`. This is where we will be storing the options we will use to constrain our enzyme design. 
+1. This is a JSON file, so all of the options contained in it need to be encapsulated in curly braces ({}). Go ahead and add a pair of these to your file.
+1. Like all designs you will create using RFD3, we need to start by giving our calculation a name. It should be short, but descriptive, so let's call it `cys_1euv_lig`. Add this name in quotes to your file and place a colon and another pair of curly brackets after this. Your file should now look like: 
+    ```json
+    {
+        "cys_1euv_lig":{
+
+        }
+    }
+    ```
+    All of the other settings discussed here will go inside the inner curly brackets.
+1. Next we need to specify the structure file (PDB, CIF, etc.) that contains information about any input structures related to our calculation: 
+    ```json
+    "input": "path/to/1euv_lig.pdb",
+    ```
+1. The identifier representing the ligand in our PDB file needs to be listed so that RFD3 knows to treat this molecule differently:
+    ```json
+    "ligand": "l:g",
+    ```
+    ```{note}
+    The ligand used in this tutorial is not a real molecule. Placing a colon (:) in your ligand name ensures that it does not match a molecule in the [Chemical Component Database](https://www.wwpdb.org/data/ccd). If you are running a calculation that uses a real ligand, feel free to use its actual chemical identifier. 
+    ```
+1. Add an option to `unindex` the residues in the input file. These residues were determined to be important for the enzymatic activity we are trying to create and design a protein around. However, we don't know where in our designed structure we want these enzymes to be, making this option incredibly useful for enzyme design:
+    ```json
+    "unindex": "A514,A531,A574,A579-581",
+    ```
+    ```{important}
+    Choosing the residues to use in your enzyme design comes from knowledge of your system, literature searches, etc. The only guidance we will give on this topic is to try several combinations of the residues you think are important for your enzyme design. Too many and you might overconstrain your system, too few and you are less likely to obtain useful designs. 
+    ```
+1. We will use the `length` option to tell RFD3 how long we want our designed proteins to be: 
+    ```json
+    "length": "100-200",
+    ```
+1. To define where our protein should be centered, we will give RFD3 an 'ori token'. This specifies the *ori*gin (center of mass) of the designed portion of our output structure:
+    ```json
+    "ori_token": [0,1,0],
+    ```
+    ```{figure} ./.assets/enzyme_tutorial/enzyme_ori_token.png
+    :width: 60%
+
+    Image of the input structure with the ORI token in the center, visualized as a white sphere.
+    ```
+    ```{important}
+    In this example the ori token is placed close to the center of our input structure. When designing your own enzyme scaffolds, this may not be the best placement depending on your design goals. See the [RFdiffusion2 paper](https://www.nature.com/articles/s41592-025-02975-x) for more information about how ORI tokens impact the results of diffusion calculations.
+    ```
+1. Even though we do not care where our residues end up in our final protein sequence, we want their geometries (or at least some of their atoms) to remain in the same place spatially so that their relationships to the ligand stay the same. For this we use `select_fixed_atoms`:
+    ```json
+    "select_fixed_atoms": {
+        "A514":"NE2,CE1,ND1,CD2,CG,CB",  
+        "A531":"OD1,CG,OD2,CB", 
+        "A574":"NE2,CD,OE1,CG", 
+        "A579":"C,O,CA,N", 
+        "A580":"SG,CB,CA,N,C,O", 
+        "A581":"C,O,CA,N"
+    },
+    ```
+    For residue A514 (histidine), A531 (aspartic acid), and A574 (glutamine) the side chain is fixed, for residue 580 (cysteine) the entire residue is fixed, and for A579 (aspartic acid) and A581 (glycine) the backbones are fixed. The ligand is automatically held in place. 
+
+    ```{figure} ./.assets/enzyme_tutorial/select_fixed_atoms.png
+    :width: 60%
+
+    Image of the starting structure where the fixed atoms have been highlighted in purple. 
+    ```
+1. RFD3 allows for RASA conditioning to control how exposed or buried different portions of your input are relative to the designed protein.
+    ```json
+    "select_buried": {
+        "l:g": "O1,C8,O3,C4,C5,C23,C24,C25,C26,C27"
+    },
+    "select_exposed": {
+        "l:g": "C2,C22,C19,C18,C17,C20,C16,C15,O21,O14,C13,C12"
+    },
+    ```
+    As the names of the options suggest, RFD3 will do its best to bury atoms that were passed to the `select_buried` option and expose the atoms passed to the `select_exposed` option. 
+
+    ```{figure} ./.assets/enzyme_tutorial/RASA_ligand.png
+    :width: 60%
+
+    Image of the ligand where the exposed portion is colored blue and the buried portion is colored red. 
+    ```
+
+    There is a third option for RASA conditioning which was not used here,`select_partially_buried`, that you might find useful for your protein design tasks.
+1. Next we're also going to unfix the *sequence* for residues A579 and A581. For this design, we know where we want the backbones for the residues next to A580 (the cysteine), but their exact identity and index does not matter. This is where the option `select_unfixed_sequence` becomes useful. 
+    ```json
+    "select_unfixed_sequence": "A579,A581",
+    ```
+    ```{note}
+    These residues have fixed portions in the `select_fixed_atoms` setting, but the atoms chosen are **only the backbone atoms**. If you are using both of these settings in your designs it is important to not fix any of the side chain atoms to allow for the identity of the residue to actually change. 
+    ```
+1. Save your file and close it. Your files should be similar to what is stored in `outputs.zip`.
+
+(enzyme-running-rfd3)=
+## Running RFD3
+To actually run RFD3 you need to know:
+- the directory you want the outputs to be stored in
+- the path to the JSON (or YAML) file that stores the specific settings for the calculation
+- the location of your checkpoint files
+
+Once you have these three things you can run something like this from the command line:
+```bash
+rfd3 design out_dir=enzyme_tutorial_outputs/0 inputs=rfd3_enzyme_tutorial.json ckpt_path=/path/to/your/checkpoint/files/rfd3_latest.ckpt 
+```
+Your output files will be placed in a new directory `enzyme_tutorial_outputs/0`.  Your output files will be named `enzyme_tutorial_cys_1euv_lig_0_model_n.cif.gz` where `n` is the number of the design. `enzyme_tutorial` comes from the name of the JSON file and `cys_1euv_lig` comes from the name you gave your calculation in the JSON file.
+
+```{note}
+You may see several warning messages when you run RFD3, these should not interfere with the calculation. 
+```
+
+(enzyme-analyzing-the-outputs)=
+## Analyzing the Outputs
+You should end up with 8 designs, numbered 0-7, each with its own `.cif.gz` and `.json` file. If you want to adjust the number, add the configuration option `diffusion_batch_size` to your `rfd3 design` command.
+
+The JSON file has many details about your diffusion run, including the options in the YAML file you created. The compressed CIF file contains information about the final diffused structure that you can easily visualize with tools like PyMOL. 
+
+Your results should look something like this: 
+```{figure} ./.assets/enzyme_tutorial/example_output_fixed_ori.png
+:width: 60%
+
+Example output for the enzyme scaffold design. The input structure is in green and the output structure is light pink. The residues that had some of their atoms fixed are highlighted in purple. The ORI token is shown as a white sphere. 
+```
+
+You'll notice:
+- The fixed atoms have stayed in place, once the structures have been aligned to the ligand
+- The index of the original residues has changed (easy to tell in this example because we have held their coordinates fixed, you can see the mapping in the output JSON file.)
+- The structures are all the same length, which is between 100 and 200 residues long. (All designs in the same batch will have the same length. Set the batch size to 1 if you want to design proteins with all different lengths.)
+
+Changing the view slightly lets us see that our RASA conditioning was also followed: 
+```{figure} ./.assets/enzyme_tutorial/RASA_output.png
+:width: 60%
+
+You can see that the portion of the ligand that was specified as exposed (blue) is much less buried in the designed protein than the portion of the ligand that was specified as buried (red).
+```
+
+## Conclusion
+You have now set up an RFD3 calculation and successfully ran the inference code for an enzyme design problem. While the options discussed here are particularly useful in enzyme design projects, RFD3 has many more that you can explore by looking at (input.m).
+
+(enzyme-references)=
+## References and Further Reading
+- For more information on the different inference settings in RFD3, see [input.md](input.md)
+- The calculation presented here was used to benchmark RFdiffusion2, for more information see [Atom-level enzyme active site scaffolding using RFdiffusion2](https://www.nature.com/articles/s41592-025-02975-x)
+- A more thorough discussion of the settings and configuration options in RFD3 can be found [here](intro_inference_calculations.md)

models/rfd3/docs/enzyme_tutorial_files/1euv_lig.pdb

@@ -0,0 +1,92 @@
+ATOM      2  N   HIS A 514       3.231   1.208  -1.240  1.00 19.42      A    N  
+ATOM      3  CA  HIS A 514       1.911   1.858  -1.146  1.00 18.23      A    C  
+ATOM      4  C   HIS A 514       1.410   2.170  -2.547  1.00 16.65      A    C  
+ATOM      5  O   HIS A 514       2.223   2.219  -3.470  1.00 18.87      A    O  
+ATOM      6  CB  HIS A 514       2.084   3.200  -0.401  1.00 18.92      A    C  
+ATOM      7  CG  HIS A 514       0.793   3.885  -0.097  1.00 19.11      A    C  
+ATOM      8  CD2 HIS A 514       0.480   5.175  -0.343  1.00 19.33      A    C  
+ATOM      9  ND1 HIS A 514      -0.281   3.307   0.570  1.00 19.64      A    N  
+ATOM     10  CE1 HIS A 514      -1.232   4.247   0.679  1.00 20.67      A    C  
+ATOM     11  NE2 HIS A 514      -0.784   5.363   0.136  1.00 18.73      A    N  
+ATOM     12  N   ASP A 531      -4.991   9.875  -2.283  1.00 18.01      A    N  
+ATOM     13  CA  ASP A 531      -4.198   8.868  -1.542  1.00 17.65      A    C  
+ATOM     14  C   ASP A 531      -5.028   8.515  -0.313  1.00 17.93      A    C  
+ATOM     15  O   ASP A 531      -5.344   9.384   0.513  1.00 19.21      A    O  
+ATOM     16  CB  ASP A 531      -2.843   9.512  -1.268  1.00 18.96      A    C  
+ATOM     17  CG  ASP A 531      -1.823   8.638  -0.562  1.00 19.66      A    C  
+ATOM     18  OD1 ASP A 531      -2.229   7.763   0.218  1.00 20.25      A    O  
+ATOM     19  OD2 ASP A 531      -0.605   8.900  -0.780  1.00 19.95      A    O1-
+ATOM     20  N   GLN A 574      -7.907   4.613   4.461  1.00 20.37      A    N  
+ATOM     21  CA  GLN A 574      -7.953   3.179   4.855  1.00 21.00      A    C  
+ATOM     22  C   GLN A 574      -7.671   3.054   6.344  1.00 21.03      A    C  
+ATOM     23  O   GLN A 574      -6.759   3.718   6.872  1.00 20.78      A    O  
+ATOM     24  CB  GLN A 574      -6.902   2.474   3.981  1.00 21.23      A    C  
+ATOM     25  CG  GLN A 574      -5.460   2.863   4.335  1.00 22.92      A    C  
+ATOM     26  CD  GLN A 574      -4.523   2.355   3.261  1.00 23.64      A    C  
+ATOM     27  NE2 GLN A 574      -3.727   1.344   3.595  1.00 24.35      A    N  
+ATOM     28  OE1 GLN A 574      -4.554   2.817   2.125  1.00 23.51      A    O  
+ATOM     29  N   ASP A 579      -4.972  -2.251   2.419  1.00 16.24      A    N  
+ATOM     30  CA  ASP A 579      -6.009  -1.965   1.401  1.00 15.40      A    C  
+ATOM     31  C   ASP A 579      -5.673  -0.876   0.414  1.00 15.59      A    C  
+ATOM     32  O   ASP A 579      -6.577  -0.537  -0.384  1.00 16.28      A    O  
+ATOM     33  CB  ASP A 579      -7.339  -1.639   2.096  1.00 16.76      A    C  
+ATOM     34  CG  ASP A 579      -8.180  -2.869   2.367  1.00 18.53      A    C  
+ATOM     35  OD1 ASP A 579      -8.022  -3.926   1.704  1.00 18.83      A    O  
+ATOM     36  OD2 ASP A 579      -9.038  -2.793   3.279  1.00 20.44      A    O1-
+ATOM     37  N   CYS A 580      -4.482  -0.303   0.456  1.00 14.58      A    N  
+ATOM     38  CA  CYS A 580      -4.229   0.856  -0.451  1.00 14.75      A    C  
+ATOM     39  C   CYS A 580      -4.592   0.525  -1.890  1.00 15.30      A    C  
+ATOM     40  O   CYS A 580      -5.133   1.439  -2.570  1.00 15.92      A    O  
+ATOM     41  CB  CYS A 580      -2.811   1.409  -0.381  1.00 16.92      A    C  
+ATOM     42  SG  CYS A 580      -1.587   0.078  -0.708  1.00 15.01      A    S  
+ATOM     43  N   GLY A 581      -4.214  -0.616  -2.427  1.00 15.26      A    N  
+ATOM     44  CA  GLY A 581      -4.496  -0.901  -3.873  1.00 15.15      A    C  
+ATOM     45  C   GLY A 581      -6.031  -0.979  -4.060  1.00 12.80      A    C  
+ATOM     46  O   GLY A 581      -6.496  -0.558  -5.161  1.00 16.14      A    O  
+TER   
+HETATM   47  C2  l:g B   1       0.721   0.361   2.697  1.00  0.00      B    C  
+HETATM   48  O3  l:g B   1      -2.014  -0.494   1.873  1.00  0.00      B    O
+HETATM   49  C4  l:g B   1      -0.420  -1.974   0.850  1.00  0.00      B    C  
+HETATM   50  C5  l:g B   1       0.633  -2.135  -0.222  1.00  0.00      B    C  
+HETATM   51  C8  l:g B   1      -0.950  -0.521   0.955  1.00  0.00      B    C  
+HETATM   52  C12 l:g B   1       1.587  -0.654   3.148  1.00  0.00      B    C  
+HETATM   53  C13 l:g B   1       2.184  -0.571   4.411  1.00  0.00      B    C  
+HETATM   54  O14 l:g B   1       2.997  -1.544   4.811  1.00  0.00      B    O  
+HETATM   55  C15 l:g B   1       3.599  -1.534   5.994  1.00  0.00      B    C  
+HETATM   56  C16 l:g B   1       3.396  -0.477   6.884  1.00  0.00      B    C  
+HETATM   57  C17 l:g B   1       2.549   0.578   6.518  1.00  0.00      B    C  
+HETATM   58  C18 l:g B   1       1.924   0.537   5.251  1.00  0.00      B    C  
+HETATM   59  C19 l:g B   1       1.061   1.550   4.794  1.00  0.00      B    C  
+HETATM   60  C20 l:g B   1       2.333   1.717   7.480  1.00  0.00      B    C  
+HETATM   61  O21 l:g B   1       4.358  -2.487   6.314  1.00  0.00      B    O  
+HETATM   62  C22 l:g B   1       0.472   1.457   3.531  1.00  0.00      B    C  
+HETATM   63  C23 l:g B   1       0.259  -2.375  -1.555  1.00  0.00      B    C  
+HETATM   64  C24 l:g B   1       1.235  -2.502  -2.549  1.00  0.00      B    C  
+HETATM   65  C25 l:g B   1       2.589  -2.391  -2.220  1.00  0.00      B    C  
+HETATM   66  C26 l:g B   1       2.969  -2.152  -0.897  1.00  0.00      B    C  
+HETATM   67  C27 l:g B   1       1.997  -2.024   0.100  1.00  0.00      B    C  
+HETATM   68  O1  l:g B   1       0.085   0.352   1.440  1.00  0.00      B    O  
+CONECT   42   51
+CONECT   47   52   62   68
+CONECT   48   51
+CONECT   49   50   51
+CONECT   50   49   63   67
+CONECT   51   42   48   49   68
+CONECT   52   47   53
+CONECT   53   52   54   58
+CONECT   54   53   55
+CONECT   55   54   56   61
+CONECT   56   55   57
+CONECT   57   56   58   60
+CONECT   58   53   57   59
+CONECT   59   58   62
+CONECT   60   57
+CONECT   61   55
+CONECT   62   47   59
+CONECT   63   50   64
+CONECT   64   63   65
+CONECT   65   64   66
+CONECT   66   65   67
+CONECT   67   50   66
+CONECT   68   47   51
+END

models/rfd3/docs/enzyme_tutorial_files/rfd3_enzyme_tutorial.json

@@ -0,0 +1,24 @@
+{
+    "1euv": {
+        "input": "./1euv_lig.pdb", 
+        "ligand": "l:g",        
+        "unindex": "A514,A531,A574,A579-581",         
+        "length": "100-200",
+        "ori_token": [0, 1, 0],  
+        "select_fixed_atoms": {
+            "A514":"NE2,CE1,ND1,CD2,CG,CB",  
+            "A531":"OD1,CG,OD2,CB",                              
+            "A574":"NE2,CD,OE1,CG", 
+            "A579":"C,O,CA,N", 
+            "A580":"SG,CB,CA,N,C,O", 
+            "A581":"C,O,CA,N"
+        },
+        "select_buried": {
+            "l:g": "O1,C8,O3,C4,C5,C23,C24,C25,C26,C27"
+        },
+        "select_exposed": {
+            "l:g": "C2,C22,C19,C18,C17,C20,C16,C15,O21,O14,C13,C12"
+        },
+        "select_unfixed_sequence": "A579,A581"
+    }
+}

models/rfd3/docs/index.rst

@@ -20,6 +20,7 @@ Tutorials
    :maxdepth: 1
 
    ppi_design_tutorial.md
+   enzyme_design_tutorial.md
 
 Examples
 --------