From 9bbe9713220a8de203a2c6d46bbd5a87e5050439 Mon Sep 17 00:00:00 2001 From: Rachel Clune Date: Wed, 1 Oct 2025 15:48:02 -0700 Subject: [PATCH] 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