Documentation

.github/workflows/documentation_workflow.yml

@@ -13,7 +13,7 @@ jobs:
       - uses: actions/setup-python@v5
       - name: Install dependencies
         run: |
-          pip install sphinx sphinx_mdinclude furo sphinx-copybutton sphinx-new-tab-link
+          pip install sphinx sphinx_mdinclude furo sphinx-copybutton #sphinx-new-tab-link
       - name: Sphinx build
         run: |
           sphinx-build -M html doc/source/ doc/build/

README.md

@@ -31,10 +31,10 @@ More detailed information about how to run, install, and use RFdiffusion2 can be
     - [LigandMPNN outputs](readme_link.html#ligandmpnn_outputs)
 -->
 
-## Setup
-<a id="setup"></a>
+## Set-up
+<a id="set-up"></a>
 
-If these setup instructions do not work for your system see the [Installation Guide](installation.html) for troubleshooting issues with the
+If these set-up instructions do not work for your system see the [Installation Guide](https://rosettacommons.github.io/RFdiffusion2/installation.html) for troubleshooting issues with the
 provided image and alternative instructions for how to install RFdiffusion2 from source. 
 
 1. **Clone the repo.**

doc/source/conf.py

@@ -64,7 +64,7 @@
 napoleon_use_ivar = True
 
 templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'overview.md', 'usage/run_inference_example.md', 'usage/other_pipeline_example.md']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'overview.md', 'usage/run_inference_example.md', 'usage/other_pipeline_example.md', 'usage/configuration_options.md', 'usage/usage.rst']
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
@@ -79,7 +79,7 @@
     "light_css_variables": {
         "color-brand-primary": "#F68A33", # Rosetta Teal
         "color-brand-content": "#37939B", # Rosetta Orange
-        "color-admonition-background": "#FB35D6", # Rosetta light orange
+        #"color-admonition-background": "#CCE8E8", # Rosetta light orange
         "font-stack": "Open Sans, sans-serif",
         "font-stack--headings": "Open Sans, sans-serif",
         "color-background-hover": "#DCE8E8ff",
@@ -90,7 +90,7 @@
     "dark_css_variables": {
         "color-brand-primary": "#37939B", # Rosetta teal
         "color-brand-content": "#F68A33", # Rosetta orange
-        "color-admonition-background": "#FB35D6", # Rosetta light orange
+        #"color-admonition-background": "#20565B", # Rosetta light orange
         "font-stack": "Open Sans, sans-serif",
         "font-stack--headings": "Open Sans, sans-serif",
         "color-brand-visited": "#37939B",

doc/source/index.rst

@@ -15,17 +15,12 @@ Welcome to the Official Documentation for `RFdiffusion2 <https://github.com/Rose
    readme_link.rst
    license_link.rst
    installation.md
-   usage/usage.md
-   usage/configuration_options.md
-   usage/ori_tokens.md
+   usage/ori_tokens.rst
 
 .. toctree::
    :maxdepth: 1
    :hidden:
 
-..   usage/other_pipeline_example.md
-..   usage/run_inference_example.md
-
 .. Indices and tables
 .. ==================
 .. 

doc/source/overview.md

@@ -2,7 +2,7 @@ Overview
 ========
 
 Introduced in [Atom level enzyme active site scaffolding using RFdiffusion2](https://www.biorxiv.org/content/10.1101/2025.04.09.648075v1), RFdiffusion2 expands on the enzyme scaffolding capabilities of diffusion-based protein design by giving researchers finer control over enzyme active sites. 
-The original [RFdiffusion](https://github.com/RosettaCommons/RFdiffusion) could generate enzyme scaffolds, but the geometry of the active site could only the specified at the residue level - no atomic or rotamer information could be directly provided. 
+The original [RFdiffusion](https://github.com/RosettaCommons/RFdiffusion) could generate enzyme scaffolds, but the geometry of the active site could only be specified at the residue level - no atomic or rotamer information could be directly provided. 
 Although defining hotspot residues provided a way for protein designers to control scaffold-ligand interactions, they offered  limited flexibility for the placement of the catalytic residues in the final design. 
 
 RFdiffusion2 addresses these limitations by: 
@@ -12,4 +12,4 @@ RFdiffusion2 addresses these limitations by:
 
 To learn how to run RFdiffusion2 using an [Apptainer](https://apptainer.org/) image, see the [READEME](readme_link.html). 
 
-> **NOTE:** The current rendition of RFdiffusion2 makes it particularly useful for enzyme scaffolding, but for many other applications RFdiffusion (the original) will be easier to use and may provide comparable or better results. 
+> **NOTE:** The current rendition of RFdiffusion2 makes it particularly useful for enzyme scaffolding and it has increased backbone flexibility compared to RFdiffusion. However, for binder design it is recommended to use the original RFdiffusion. 

doc/source/usage/configuration_options.md

@@ -1 +1,12 @@
 ## Configuration Options
+
+This table only has the options shown in the `rf_diffusion/configs/inference/base.yml` and `rf_diffusion/configs/inference/aa.yml` files, as they are the most recommended for use by the developers. 
+There are many other configuration (.yml) files in the `configs` directory, the options in them are not guaranteed to work. 
+If you would like to create your own configuration file, which can be useful if you routinely use settings that are not the default, see the **Creating Your Own Config File** section, below. 
+
+
+
+### Creating Your Own Config File
+<a id="custom_configs"></a>
+
+Here's some info on configurations!

doc/source/usage/ori_tokens.rst

@@ -0,0 +1,73 @@
+ORI Tokens
+==========
+
+ORI tokens define the center of mass for the designed portion of the enzyme scaffold. It allows for control over the active site and transition
+state orientation relative to the protein core. In binder design, the ORI token defines the center of mass of the binder relative to the target protein.
+
+.. warning:: 
+
+    ORI tokens are only used in RFdiffusion2 and are not compatible with the original RFdiffusion.
+    You must specify an ORI token when using RFdiffusion2
+
+How to Add ORI Tokens to Your Input PDB
+---------------------------------------
+First add a ``HETATM`` to your PDB file:
+
+.. code-block:: none
+
+    HETATM 6700 ORI ORI z 1 9.450 95.149 43.231 0.00 0.00 z ORI
+
+Let's break down what each of these fields mean:
+
+* ``HETATM``: This indicates that the line describes a non-standard atom.
+* ``6700``: This is the atom serial number. You can choose any unique number that does not conflict with existing atom numbers in your PDB file.
+* ``ORI``: This is the atom name. It should be set to ``ORI`` to indicate that this atom represents the ORI token.
+* ``ORI``: This is the residue name. It should also be set to ``ORI``.
+* ``z``: This is the chain identifier. You can choose any single character (letter or number) that does not conflict with existing chain IDs in your PDB file.
+* ``1``: This is the residue sequence number. You can choose any number that does not conflict with existing residue numbers in your PDB file.
+* ``9.450 95.149 43.231``: These are the X, Y, and Z coordinates of the ORI token in Angstroms. Set these to the desired position for the ORI token.
+* ``0.00 0.00``: These are the occupancy and temperature factor values. They can be set to ``0.00`` for the ORI token.
+* ``z``: This is the element symbol. It can be set to any character, as it is not relevant for the ORI token.
+* ``ORI``: This is the charge. It can be set to any value, as it is not relevant for the ORI token.
+
+For an example of this you can take a look at ``rf_diffusion/benchmark/input/mcsa_41/M0584_1ldm.pdb``, which is used in the demo discussed in the README.
+The last line of this file is the ORI token. 
+
+.. note::
+    You can also add the ORI token using PyMOL by running the following command in the PyMOL command line:
+
+    .. code-block::
+
+        cmd.delete("molecule1");cmd.pseudoatom(object="molecule1", pos=[-1,3,2], elem="ORI", name="ORI", vdw=1.5, hetatm=True, chain='z', segi='z', resn="ORI"); cmd.show("sphere", "molecule1");
+
+Once you have added this line to your PDB file, you can move it using `PyMOL <https://www.pymol.org/>`_ or other protein visualization software.
+
+For PyMOL, you can easily move the ORI token by selecting it (clicking on the sphere that represents the ORI token) and using the `"move" <https://pymolwiki.org/index.php/Move>`_ command or by dragging it with the mouse.
+To drag the ``HETATM`` with the mouse, select the atom by clicking on it, then go to A (action) -> drag coordinates: 
+
+.. figure:: /_static/images/drag_action.png
+    :width: 90%
+    :alt: Selecting the 'drag coordinates' option from the Action menu in PyMOL
+
+    Selecting the menu option that will allow you to drag only the ORI token in PyMOL.
+
+If you are using a three-button mouse, you can hold shift and right-click on the ``HETATM`` to drag it in and out of the screen. 
+To translate the atom in and out of the screen, hold shift while center-clicking and dragging. 
+
+.. figure:: /_static/images/moving_ori.gif
+    :alt: Moving the ORI token in PyMOL by clicking and dragging it with the mouse
+
+    Moving the ORI token in PyMOL by clicking and dragging it with the mouse.
+
+
+Recommendations for ORI Token Placement
+---------------------------------------
+ORI tokens specify the center of mass of the designed region of the protein, but how do you determine where that should be? 
+
+One method of doing this is to estimate where the center of mass of the designed region should be relative to your input structure and then generate several ORI tokens (20-30) in a sphere around that area. 
+Whether you want to homogeneously or randomly sample different locations within that sphere and how far apart you want the different ORI tokens to be will depend on your specific design problem.
+If you have the computational resources, you can generate several designs for each ORI token placement and then filter the results. 
+
+
+
+

doc/source/usage/other_pipeline_example.md

@@ -1,4 +1,4 @@
 ## Using the pipelines.py script
 
-
+<!-- This example is to explain how to modify or create your own json/yml files to work with the pipelines.py file-->
 

doc/source/usage/run_inference_example.md

@@ -1,3 +1,5 @@
 ## Using run_inference.py
 
+<!-- This document is meant to give an example of using the run_inference script, should be similar to the RFdiffusion examples-->
+
 While the pipelines.py script is powerful, you can also run 

envs/cuda121_env.yml

@@ -12,6 +12,6 @@ dependencies:
   - conda-forge::openbabel=3.1.1
   - pytorch=2.4
   - pytorch-cuda=12.1
-  - pyrosetta
+  - pyrosetta 
   - pip:
      - -r requirements_cuda121.txt

envs/cuda124_env.yml

@@ -14,6 +14,6 @@ dependencies:
   - dgl
   - pytorch=2.4.0
   - pytorch-cuda=12.4
-  - pyrosetta
+  - pyrosetta 
   - pip:
      - -r requirements_cuda124.txt

envs/requirements_cuda121.txt

@@ -58,7 +58,7 @@ RestrictedPython
 ruff==0.6.2
 scipy==1.13.1
 seaborn==0.13.2
-submitit
+submitit 
 sympy==1.13.2
 tmtools
 tqdm==4.65.0