Merge pull request #4 from RosettaCommons/documentation

README update and minor environment fix

Author: andrewfavor95

CONTRIBUTING.md

@@ -1,7 +1,40 @@
 # Contributing to RFDpoly
+Thank you for helping RFDpoly grow! Please follow the
+guidelines below to ensure the consistency of the code
+and documentation quality.
+
+To contribute to RFDpoly - either through code or 
+documentation contributions - please fork the repository,
+make changes, and create a pull request (PR). The pull 
+request should have `main` as the base branch.
+
+If your PR is a result of an Issue or Discussion, make
+sure to mention it in your description. 
+
+## Issues vs. Discussions
+An issue should be opened if there is an issue with the 
+code or there is a request for a new feature. 
+
+The Discussions section should be used to answer questions
+about best practices, usage, etc. 
 
 ## Code Contributions
 
+### Code Style and Quality
+When contributing to the code base, please adhere to the [PEP8 style guide](https://peps.python.org/pep-0008/).
+
+### Tests
+Please write tests for any contributed code or append to 
+existing tests.
+
+Existing tests can be found in `rf_diffusion/test_inference_commands.py`
+
+### Approving and Merging Pull Requests
+Currently only the original developers and the Devel Team 
+at Rosetta Commons can approve and merge pull requests. PRs
+will be merged via a merge commit, so all commits from the 
+feature branch will be added to the base branch.
+
 ## Documentation Contributions
 
 To preview the changes you made to the documentation before making a Pull Request you will need to

README.md

@@ -12,52 +12,40 @@ This repository contains the code for the [associated preprint](https://www.bior
   publisher={Cold Spring Harbor Laboratory}
 }
 ```
+## Documentation
+More information and documentation can be found [here](https://rosettacommons.github.io/RFDpoly/).
 
-You can clone this repository using git, then inference can be run when you have downloaded model weights and the necessary apptainer to run (see below).
-
-To download model weights:
-  * [click here for the best RNA-design weights](https://files.ipd.uw.edu/pub/2025_RFDpoly/train_session2024-07-08_1720455712_BFF_3.00.pt)
-  * [click here for the best general multi-polymer weights](https://files.ipd.uw.edu/pub/2025_RFDpoly/train_session2024-06-27_1719522052_BFF_7.00.pt)
-
-This software runs using apptainers. To download the associated apptainer `.sif` file, [click here](https://files.ipd.uw.edu/pub/2025_RFDpoly/SE3nv.sif)
-Equivalent setup instructions for conda are in progress.
-
-Once you have these files, you can follow the [design tutorial](https://github.com/RosettaCommons/RFDpoly/blob/main/RFDpoly_tutorial.pdf) to see various design tasks and the associated documentation/syntax.
+## Installation and setup
 
-Contact [email protected] if you have trouble accessing files or hit any bugs.
+### 1. Clone the repository 
+```bash
+git clone [email protected]:RosettaCommons/RFDpoly.git
+```
 
+### 2. Set environment variables and create directories 
 
+*This section is not necessary for running RFDpoly,
+but te example commands below use these environment
+variables.*
 
 
+Set relevant paths for installation and then create the directories the paths point to:
 
-## Installation and setup
+```bash
+# Feel free to change the exact names of the directories
+RFDPOLY_DIR=/path/to/RFDpoly
+WEIGHTS_DIR=/path/to/RFDpoly/weights
 
-1. Set relevant paths for installation and navigate to directory for setup (change accordingly given your filesystem and choice of storage location):
-```Bash
-# Where you choose to install things (CHANGE THESE):
-RFDPOLY_DIR=~/git/RFDpoly_paper_version
-WEIGHTS_DIR=~/git/RFDpoly_paper_version/weights
-ENV_DIR=~/git/RFDpoly_paper_version/exec
-
-# Wherever you want to run some design jobs (ALSO CHANGE THIS):
-DESIGN_DIR=~/git/RFDpoly_paper_version/design_jobs
+# path for where to put the Apptainer .sif file
+ENV_DIR=/path/to/RFDpoly/exec
 
 # Make the directories
 mkdir -p $RFDPOLY_DIR
 mkdir -p $WEIGHTS_DIR
 mkdir -p $ENV_DIR
-mkdir -p $DESIGN_DIR
-
-```
-
-2. Navigate to the directory where you want to set up the repo, and clone it:
-```Bash
-cd $RFDPOLY_DIR
-git clone [email protected]:RosettaCommons/RFDpoly.git
-
 ```
 
-3. Navigate to the directory where you want to save model weights, download them, and set path variable for weights of your choice:
+### 3. Navigate to the directory where you want to save model weights, download them, and set path variable for weights of your choice:
 ```Bash
 # Download model weights:
 cd $WEIGHTS_DIR
@@ -68,64 +56,72 @@ curl -O https://files.ipd.uw.edu/pub/2025_RFDpoly/train_session2024-06-27_171952
 curl -O https://files.ipd.uw.edu/pub/2025_RFDpoly/train_session2024-07-08_1720455712_BFF_3.00.pt
 
 # Set weights path (replace with your choice of weights):
-MODEL_WEIGHTS_PATH=$WEIGHTS_DIR/train_session2024-07-08_1720455712_BFF_3.00.pt
-export RFDPOLY_CKPT_PATH="$MODEL_WEIGHTS_PATH"
-
+export RFDPOLY_CKPT_PATH=\$WEIGHTS_DIR/train_session2024-07-08_1720455712_BFF_3.00.pt
 ```
 
-4. Setting up the environment:
-Navigate to the directory where you want to apptainer file, download it, and set path variable:
+### 4. Setting up the environment:
+Navigate to the directory where you want to [Apptainer](https://apptainer.org/) file, download it, and set path variable:
 ```Bash
 cd $ENV_DIR
 curl -O https://files.ipd.uw.edu/pub/2025_RFDpoly/SE3nv.sif
 APPTAINER_PATH=$ENV_DIR/SE3nv.sif
-
 ```
+Downloading the `.sif` file may take several minutes. 
+
+You can find alternative installation instructions in the
+[external documentation](https://rosettacommons.github.io/RFDpoly/).
+
+## Basic Use Case Example: Testing Your Setup
 
-Equivalent python environments can be set up using conda, or an environment manager of your choice.
-All dependencies and packages are specified in the files found in `rf_diffusion/environment` (see `environment.yml` and `SE3nv.spec`) 
+In this example, RFDpoly will create a single design
+with three chains:
+1. A DNA chain with 33 segments
+2. An RNA chain with 33 segments
+3. A protein chain with 75 residues
+
+Make a directory to store the outputs of the demo and store 
+it in the `DESIGN_DIR` environment variable:
+```bash
+export DESIGN_DIR=/path/to/your/output/directory
+```
 
-## Testing that everything works (the *DEMO*):
-Change directory to run from within the RFDpoly directory useful for filepath searches if you are not providing an input pdb), and run example inference script.
-Be sure to specify your desired output directory with `$DESIGN_DIR`.
 ```Bash
 cd $DESIGN_DIR/
 
-$APPTAINER_PATH $RFDPOLY_DIR/RFDpoly/rf_diffusion/run_inference.py --config-name=multi_polymer \
+apptainer run --nv $APPTAINER_PATH $RFDPOLY_DIR/rf_diffusion/run_inference.py --config-name=multi_polymer \
 diffuser.T=50 \
-inference.ckpt_path=$MODEL_WEIGHTS_PATH \
+inference.ckpt_path=$RFDPOLY_CKPT_PATH \
 inference.num_designs=1 \
 contigmap.contigs=[\'33\ 33\ 75\'] \
 contigmap.polymer_chains=[\'dna\',\'rna\',\'protein\'] \
 inference.output_prefix=$DESIGN_DIR/test_outputs/basic_uncond_test01
-
 ```
 The initial run will take a little while to precompute the IGSO3 cache, but subsequent runs will be more direct and quick.
 
 
 if that throws errors, then try:
-```
-$APPTAINER_PATH $RFDPOLY_DIR/RFDpoly/rf_diffusion/run_inference.py --config-name=multi_polymer \
+```bash
+cd $DESIGN_DIR
+
+apptainer run --nv $APPTAINER_PATH $RFDPOLY_DIR/rf_diffusion/run_inference.py --config-name=multi_polymer \
 diffuser.T=50 \
-inference.ckpt_path=$MODEL_WEIGHTS_PATH \
-inference.input_pdb=$RFDPOLY_DIR/RFDpoly/rf_diffusion/test_data/DBP035.pdb \
-inference.num_designs=3 \
+inference.ckpt_path=$RFDPOLY_CKPT_PATH \
+inference.input_pdb=$RFDPOLY_DIR/rf_diffusion/test_data/DBP035.pdb \
+inference.num_designs=1 \
 contigmap.contigs=[\'33\ 33\ 75\'] \
 contigmap.polymer_chains=[\'dna\',\'rna\',\'protein\'] \
 inference.output_prefix=$DESIGN_DIR/test_outputs/basic_uncond_test01
-
-
 ```
+
 explanation: model initialization searches for an input pdb filepath, even if you aren't performing motif scaffolding. Providing a (real) dummy filepath will fix this is the default search paths are unsuccessful.
 
-**Expected output:** a three chain .pdb file, containing a complex of DNA (chain A), RNA (chain B), and protein (chain C).
 **NOTE:** using the `--config-name=multi_polymer` specification is the best way to ensure that all settings work together as expected, and are consistent with the behavior reported in the manuscript.
 
 ## If the example (demo) command above works, proceed to exploration of the full [design tutorial](https://github.com/RosettaCommons/RFDpoly/blob/main/RFDpoly_tutorial.pdf).
 The full design tutorial contains many inference commands for the types of designs reported in the RFDpoly paper.
-The design tutorial also is intented to provide documentation, and explain arguments in the context of their use-cases.
-
+The design tutorial is intended to provide documentation, and explain arguments in the context of their use-cases.
 
+Contact **[email protected]** if you have trouble accessing files or hit any bugs.
 
 # Additional Software Policy checklist items:
 ## System requirements
@@ -134,10 +130,8 @@ The design tutorial also is intented to provide documentation, and explain argum
   - Primary workflow: Linux host with [Apptainer](https://apptainer.org/) ≥ 1.1 (or Singularity equivalent). The bundled container image runs Ubuntu 22.04.2 LTS.
   - Alternative workflow: macOS 13+/Windows 11 via Conda (CPU only unless you install CUDA-capable PyTorch wheels).
 - **Software dependencies**
-  - Apptainer runtime to execute `SE3nv.sif`.
   - For native/Conda installs: Python 3.10, PyTorch 1.13.1, CUDA 11.7 toolchain (if using an NVIDIA GPU), PyRosetta 2023.09+, DGL 1.0.1, e3nn 0.5.1, hydra-core 1.3.2, and the packages listed in `rf_diffusion/environment/environment.yml`.
   - **NOTE:** All dependencies are specified in `rf_diffusion/environment/`, such that users can set up an equivalent working environment on any operating system.
-  - Downloaded assets: model checkpoints (`*.pt`, ~2.3 GB each) and the container image (`SE3nv.sif`, ~8 GB).
 - **Tested configurations**
   - Ubuntu 22.04 host with Apptainer 1.1.9, NVIDIA driver ≥ 515, CUDA 11.7 runtime.
   - PyTorch 1.13.1+cu117, Python 3.10.8, PyRosetta 2023.09 inside the container.

docs/source/conf.py

@@ -32,7 +32,7 @@
 
 html_theme_options = {
     "sidebar_hide_name":False,
-    "announcement": "<em>THIS DOCUMENTATION IS CURRENTLY UNDER CONSTRUCTION</em>",
+    #"announcement": "<em>THIS DOCUMENTATION IS CURRENTLY UNDER CONSTRUCTION</em>",
     "light_css_variables": {
         "color-brand-primary": "#F68A33", # Rosetta Teal
         "color-brand-content": "#37939B", # Rosetta Orange

docs/source/contributing_link.rst

@@ -0,0 +1,5 @@
+CONTRIBUTING to RFDpoly
+=======================                                                                                        
+
+.. include:: ../../CONTRIBUTING.md
+   :parser: myst_parser.sphinx_

docs/source/index.rst

@@ -6,12 +6,15 @@
 RFDpoly documentation
 =====================
 
-Add your content using ``reStructuredText`` syntax. See the
-`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
-documentation for details.
+.. include:: readme_link.rst
 
 
 .. toctree::
-   :maxdepth: 2
+   :titlesonly:
    :caption: Contents:
 
+   readme_link.rst<self>
+   license_link.rst
+   contributing_link.rst
+   installation_guide.md
+

docs/source/installation_guide.md

@@ -0,0 +1,92 @@
+# Installation Guide
+
+## Using the Apptainer Image
+If possible, we highly recommend using the provided apptainer image which can be obtained via:
+```bash
+curl -O https://files.ipd.uw.edu/pub/2025_RFDpoly/SE3nv.sif
+```
+
+Here is an example for how to use this image to run RFDpoly: 
+```bash
+apptainer run --nv /path/to/SE3nv.sif /path/to/RFDpoly/rf_diffusion/run_inference.py --config-name=multi_polymer \
+diffuser.T=50 \
+inference.ckpt_path=/path/to/train_session2024-07-08_1720455712_BFF_3.00.pt \
+inference.num_designs=1 \
+contigmap.contigs=[\'33\ 33\ 75\'] \
+contigmap.polymer_chains=[\'dna\',\'rna\',\'protein\'] \
+inference.output_prefix=/path/to/your/output/directory/basic_uncond_test01
+```
+
+If you see an error when attempting to run this related to
+a lack of an input file, try adding this option:
+```bash
+inference.input_pdb=/path/to/RFDpoly/rf_diffusion/test_data/DBP035.pdb
+```
+
+## Creating a Conda Environment
+
+### Linux: 
+If the apptainer image is not compatible with your system
+or you are doing development with RFDpoly, you can create
+a [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) or [mamba](https://mamba.readthedocs.io/en/latest/user_guide/mamba.html) environment with a provided `environment.yml` file: 
+
+```bash
+conda env create -f /path/to/RFDpoly/rf_diffusion/environment/environment.yml
+conda activate RFDpoly_env
+pip install /path/to/RFDpoly/rf_diffusion/RF2-allatom/rf2aa/SE3Transformer
+```
+The last command installs a slightly modified version of 
+se3-transformer. If installing this package does not work,
+you can try installing [`se3-transformer-pytorch`](https://pypi.org/project/se3-transformer-pytorch/) instead,
+but we do not guarantee that your results will be exactly
+the same. 
+
+You can test your installation by running: 
+```bash
+python /path/to/RFDpoly/rf_diffusion/run_inference.py \
+--config-name=multi_polymer \
+diffuser.T=50 \
+inference.ckpt_path=/path/to/RFDpoly/weights/train_session2024-07-08_1720455712_BFF_3.00.pt \
+inference.num_designs=1 \
+contigmap.contigs=[\'33\ 33\ 75\'] \
+contigmap.polymer_chains=[\'dna\',\'rna\',\'protein\'] \
+inference.output_prefix=./basic_uncond_test01
+```
+
+If using the `environment.yml` file does not work, please
+create an issue. Or, if you modified the `.yml` file to 
+work for your system, make a pull request to add it to 
+the `rf_diffusion/environment` folder. 
+
+### MacOS
+If the apptainer image is not compatible with your system
+or you are doing development with RFDpoly, you can create
+a [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) or [mamba](https://mamba.readthedocs.io/en/latest/user_guide/mamba.html) environment with a provided `macos_environment.yml` file: 
+
+```bash
+conda env create -f /path/to/RFDpoly/rf_diffusion/environment/macos_environment.yml
+conda activate RFDpoly_env
+pip install /path/to/RFDpoly/rf_diffusion/RF2-allatom/rf2aa/SE3Transformer
+```
+The last command installs a slightly modified version of 
+se3-transformer. If installing this package does not work,
+you can try installing [`se3-transformer-pytorch`](https://pypi.org/project/se3-transformer-pytorch/) instead,
+but we do not guarantee that your results will be exactly
+the same. 
+
+You can test your installation by running: 
+```bash
+python /path/to/RFDpoly/rf_diffusion/run_inference.py \
+--config-name=multi_polymer \
+diffuser.T=50 \
+inference.ckpt_path=/path/to/RFDpoly/weights/train_session2024-07-08_1720455712_BFF_3.00.pt \
+inference.num_designs=1 \
+contigmap.contigs=[\'33\ 33\ 75\'] \
+contigmap.polymer_chains=[\'dna\',\'rna\',\'protein\'] \
+inference.output_prefix=./basic_uncond_test01
+```
+
+If using the `macos_environment.yml` file does not work, 
+please create an issue. Or, if you modified the `.yml` file 
+to work for your system, make a pull request to add it to 
+the `rf_diffusion/environment` folder. 

docs/source/license_link.rst

@@ -0,0 +1,5 @@
+LICENSE
+=======                                                                                                 
+
+.. include:: ../../LICENSE.md
+   :parser: myst_parser.sphinx_

docs/source/readme_link.rst

@@ -0,0 +1,6 @@
+README
+======                                                                                                 
+
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
+