From 9bbe9713220a8de203a2c6d46bbd5a87e5050439 Mon Sep 17 00:00:00 2001 From: Rachel Clune Date: Wed, 1 Oct 2025 15:48:02 -0700 Subject: [PATCH 1/2] Add and restructure documentation for RFdiffusion2 Introduces new documentation files including installation instructions, overview, and links to README and license. Updates Sphinx configuration to include sphinx-copybutton and reorganizes index.rst for improved navigation. The GitHub workflow now installs sphinx-copybutton. README updated with a link to the documentation site. --- .github/workflows/documentation_workflow.yml | 54 +++---- README.md | 2 + doc/source/conf.py | 4 +- doc/source/index.rst | 37 ++--- doc/source/installation.md | 150 +++++++++++++++++++ doc/source/license_link.rst | 3 + doc/source/overview.md | 4 + doc/source/readme_link.rst | 3 + 8 files changed, 210 insertions(+), 47 deletions(-) create mode 100644 doc/source/installation.md create mode 100644 doc/source/license_link.rst create mode 100644 doc/source/overview.md create mode 100644 doc/source/readme_link.rst diff --git a/.github/workflows/documentation_workflow.yml b/.github/workflows/documentation_workflow.yml index eae2493..df9f246 100644 --- a/.github/workflows/documentation_workflow.yml +++ b/.github/workflows/documentation_workflow.yml @@ -1,27 +1,27 @@ -name: documentation - -on: [push, pull_request, workflow_dispatch] - -permissions: - contents: write - -jobs: - docs: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 - - name: Install dependencies - run: | - pip install sphinx sphinx_mdinclude furo - - name: Sphinx build - run: | - sphinx-build -M html doc/source/ doc/build/ - - name: Deploy to GitHub Pages - uses: peaceiris/actions-gh-pages@v3 - if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }} - with: - publish_branch: gh-pages - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: doc/build/html - force_orphan: true +name: documentation + +on: [push, pull_request, workflow_dispatch] + +permissions: + contents: write + +jobs: + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + - name: Install dependencies + run: | + pip install sphinx sphinx_mdinclude furo sphinx-copybutton + - name: Sphinx build + run: | + sphinx-build -M html doc/source/ doc/build/ + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }} + with: + publish_branch: gh-pages + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: doc/build/html + force_orphan: true diff --git a/README.md b/README.md index 2418f4b..bdcab50 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,8 @@ Open source code for RFdiffusion2 as described in the following pre-print. } ``` +More detailed information about how to run, install, and use RFdiffusion2 can be found [here](https://rosettacommons.github.io/RFdiffusion2/). + ## Set-up 1. **Clone the repo.** diff --git a/doc/source/conf.py b/doc/source/conf.py index 44f943d..a3c8c28 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -19,8 +19,8 @@ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx_mdinclude', - #'myst_parser', # to use markdown instead of ReST' - + #'myst_parser', # to use markdown instead of ReST + 'sphinx_copybutton', ] #myst_enable_extensions = ["colon_fence"] # see https://mystmd.org/guide/syntax-overview for more information diff --git a/doc/source/index.rst b/doc/source/index.rst index 5b27424..e46481b 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -3,24 +3,25 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to the Official Documentation for RFdiffusion2! -======================================================= +Welcome to the Official Documentation for `RFdiffusion2 `_! +=========================================================================================================== +.. mdinclude:: overview.md .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Contents: - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - -.. include:: new.rst - -.. include:: modules.rst - -.. mdinclude:: ../../README.md - - + + Overview + readme_link.rst + license_link.rst + installation.md + +.. Indices and tables +.. ================== +.. +.. * :ref:`genindex` +.. * :ref:`modindex` +.. * :ref:`search` +.. +.. .. include:: new.rst +.. .. include:: modules.rst diff --git a/doc/source/installation.md b/doc/source/installation.md new file mode 100644 index 0000000..cd6fed4 --- /dev/null +++ b/doc/source/installation.md @@ -0,0 +1,150 @@ +# Installing RFdiffusion2 + +## Apptainer Image (Recommended) +There is an Apptainer image provided in the RFdiffusion2 repository, it is located at `RFdiffusion2/rf_diffusion/exec/bakerlab_rf_diffusion_aa.sif`. This file can be run with either Apptainer or Singularity, if you have any issues using it please [create an issue](https://github.com/RosettaCommons/RFdiffusion2/issues). An example of how to use this image is given in the [README](readme_link.html#inference). + +If you need to generate your own image, the `.spec` file used to generate the given `.sif` file can be found at `RFdiffusion2/rf_diffusion/exec/rf_diffusion_aa.spec`. + +## Installation from Source +Some of the dependencies listed below will vary based on your system, especially the version of CUDA available on your cluster. +You will likely need to change some of the versions of the tools below to successfully install RFdiffusion2. +The instructions below are for CUDA 12.4 and PyTorch 2.4. +For some useful troubleshooting tips, see the [Troubleshooting](#troubleshooting) section below. + +1. Create a conda environment using [miniforge](https://github.com/conda-forge/miniforge) and activate it +1. Point to the correct [NVIDIA-CUDA channel](https://anaconda.org/nvidia/cuda/labels), and install [PyTorch](https://pytorch.org/), Python 3.11, and [pip](https://pip.pypa.io/en/latest/) based on what is available on your system: + ``` + conda install --yes \ + -c nvidia/label/cuda-12.4.0 \ + -c https://conda.rosettacommons.org \ + -c pytorch \ + -c dglteam/label/th24_cu124 \ + python==3.11 \ + pip \ + numpy"<2" \ + matplotlib \ + jupyterlab \ + conda-forge::openbabel==3.1.1 \ + cuda \ + pytorch==2.4 \ + pytorch-cuda==12.4 \ + pyrosetta + ``` + > **REMEMBER:** You will need to change your CUDA version based on what is available on your system. This will need to be changed in the + > NVIDIA channel, the dglteam channel, the pytorch version, and the pytorch-cuda version. + +1. Use pip to install several Python libraries: + ``` + pip install \ + hydra-core==1.3.1 \ + ml-collections==0.1.1 \ + addict==2.4.0 \ + assertpy==1.1.0 \ + biopython==1.83 \ + colorlog \ + compact-json \ + cython==3.0.0 \ + cytoolz==0.12.3 \ + debugpy==1.8.5 \ + deepdiff==6.3.0 \ + dm-tree==0.1.8 \ + e3nn==0.5.1 \ + einops==0.7.0 \ + executing==2.0.0 \ + fastparquet==2024.5.0 \ + fire==0.6.0 \ + GPUtil==1.4.0 \ + icecream==2.1.3 \ + ipdb==0.13.11 \ + ipykernel==6.29.5 \ + ipython==8.27.0 \ + ipywidgets \ + mdtraj==1.10.0 \ + numba \ + omegaconf==2.3.0 \ + opt_einsum==3.3.0 \ + pandas==1.5.0 \ + plotly==5.16.1 \ + pre-commit==3.7.1 \ + py3Dmol==2.2.1 \ + pyarrow==17.0.0 \ + pydantic \ + pyrsistent==0.19.3 \ + pytest-benchmark \ + pytest-cov==4.1.0 \ + pytest-dotenv==0.5.2 \ + pytest==8.2.0 \ + rdkit==2024.3.5 \ + RestrictedPython \ + ruff==0.6.2 \ + scipy==1.13.1 \ + seaborn==0.13.2 \ + sympy==1.13.2 \ + tmtools \ + tqdm==4.65.0 \ + typer==0.12.5 \ + wandb==0.13.10 + ``` +1. Install [Biotite](https://www.biotite-python.org/latest/index.html) and several libraries related to PyTorch, and [pylibcugraphops](https://pypi.org/project/pylibcugraphops-cu12/): + ``` + pip install biotite + pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.4.0+cu124.html + pip install -U -i https://pypi.anaconda.org/rapidsai-wheels-nightly/simple "pylibcugraphops-cu12>=24.6.0a24" + ``` + > **REMEMBER:** You will need to change the link for installing the PyTorch-related libraries (the second line in the code block above) to have it match your PyTorch and CUDA versions. +1. Install a version of [TorchData](https://pypi.org/project/torchdata/#what-is-torchdata) that still has DataPipes: + ``` + pip install torchdata==0.9.0 + ``` +1. Install a version of the [Deep Graph Library](https://www.dgl.ai/pages/start.html) based on the version of PyTorch and CUDA you are using: + ``` + conda install -c dglteam/label/th24_cu124 dgl + ``` + > **REMEMBER:** You will need to change the conda channel to the correct version of PyTorch (`th24` in the line above) and CUDA (`cu124` in the line above). Use the [Deep Graph Library's Installation guide](https://www.dgl.ai/pages/start.html) to determine the correct conda or pip command. +1. Set your `PYTHONPATH` environment variable: + ``` + export PYTHONPATH=$PYTHONPATH:/path/to/RFdiffusion2 + ``` + +.. _troubleshooting: + +### Troubleshooting +Ran into an installation issue not covered here? [Create a new issue!](https://github.com/RosettaCommons/RFdiffusion2/issues) + + +
+How to determine the highest available CUDA version on your system + +The `nvidia-smi` command will print out information about the available GPUs you can access on your cluster. +The first line in the result will look something like: +``` ++---------------------------------------------------------------------------------------+ +| NVIDIA-SMI 535.230.02 Driver Version: 535.230.02 CUDA Version: 12.2 | +|-----------------------------------------+----------------------+----------------------+ +``` +Here, this means that this system can only support up to CUDA 12.2. However, if you look at the possible [PyTorch versions](https://pytorch.org/get-started/previous-versions/) +and [Deep Graph Library versions](https://www.dgl.ai/pages/start.html) on their installation pages, you'll notice that they don't +have versions for 12.2, so in this situation you would need to change the installation instructions to work with CUDA 12.1. +
+ +
+Cannot find DGL C++ graphbolt library at... + +Seeing this error likely means that the version of the Deep Graph Library (DGL) that you have installed does not match +the corresponding version of PyTorch your system is finding. Double check that you installed the correct versions of +these tools and ensure that your system does not have a different version of PyTorch it is finding. + +It might also be useful to `ls` in the given directory to see what version of the DGL libraries you have installed. +For example, if your error says it is looking for `graphbolt/libgraphbolt_pytorch_2.4.0.so` it means your system is +using Pytorch version 2.4.0. Meanwhile if you `ls` in the directory you might see that you only have `libgraphbolt_pytorch_2.1.2.so` +meaning that the version of DGL you downloaded was only mean to work with PyTorch versions up to 2.1.2. +
+ +
+No module named 'torchdata.datapipes' + +Newer versions of TorchData have stopped supporting their DataPipes tools. You will need to downgrade the version of TorchData +you have installed to one at or below version 0.9.0. You can learn more about this change on [TorchData's PyPI page](https://pypi.org/project/torchdata/). +
+ + diff --git a/doc/source/license_link.rst b/doc/source/license_link.rst new file mode 100644 index 0000000..b1aa414 --- /dev/null +++ b/doc/source/license_link.rst @@ -0,0 +1,3 @@ +LICENSE +####### +.. mdinclude:: ../../LICENSE.md \ No newline at end of file diff --git a/doc/source/overview.md b/doc/source/overview.md new file mode 100644 index 0000000..542cf96 --- /dev/null +++ b/doc/source/overview.md @@ -0,0 +1,4 @@ +Overview +======== + +RFdiffusion2 is a \ No newline at end of file diff --git a/doc/source/readme_link.rst b/doc/source/readme_link.rst new file mode 100644 index 0000000..51e8148 --- /dev/null +++ b/doc/source/readme_link.rst @@ -0,0 +1,3 @@ +README +###### +.. mdinclude:: ../../README.md \ No newline at end of file From bc1092ee2f9298effccd6aef52b98b28e4de9749 Mon Sep 17 00:00:00 2001 From: Rachel Clune Date: Thu, 2 Oct 2025 21:01:39 -0700 Subject: [PATCH 2/2] Add sphinx-new-tab-link and update documentation overview Added the sphinx-new-tab-link extension to the Sphinx build process and configuration. Updated overview.md with a detailed explanation of RFdiffusion2's capabilities and differences from the original RFdiffusion, and excluded overview.md from Sphinx build patterns. --- .github/workflows/documentation_workflow.yml | 2 +- doc/source/conf.py | 3 ++- doc/source/overview.md | 13 ++++++++++++- 3 files changed, 15 insertions(+), 3 deletions(-) diff --git a/.github/workflows/documentation_workflow.yml b/.github/workflows/documentation_workflow.yml index df9f246..e818c24 100644 --- a/.github/workflows/documentation_workflow.yml +++ b/.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 + pip install sphinx sphinx_mdinclude furo sphinx-copybutton sphinx-new-tab-link - name: Sphinx build run: | sphinx-build -M html doc/source/ doc/build/ diff --git a/doc/source/conf.py b/doc/source/conf.py index a3c8c28..ed800ef 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -21,6 +21,7 @@ 'sphinx_mdinclude', #'myst_parser', # to use markdown instead of ReST 'sphinx_copybutton', + 'sphinx_new_tab_link', ] #myst_enable_extensions = ["colon_fence"] # see https://mystmd.org/guide/syntax-overview for more information @@ -63,7 +64,7 @@ napoleon_use_ivar = True templates_path = ['_templates'] -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'overview.md'] # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output diff --git a/doc/source/overview.md b/doc/source/overview.md index 542cf96..6ae3088 100644 --- a/doc/source/overview.md +++ b/doc/source/overview.md @@ -1,4 +1,15 @@ Overview ======== -RFdiffusion2 is a \ No newline at end of file +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. +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: +- Allowing active sites to be defined at the atomic level, avoiding the need for costly inverse rotamer sampling. +- Supporting scaffolding of disconnected groups of atoms, including residues with unknown sequence indices, to increase design flexibility. +- Introducing the ORI (origin) token, which specifies the desired center of mass of the scaffold. This feature enables greater control over active-site placement and transition-state orientation relative to the protein core. + +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. \ No newline at end of file