RFdiffusion Documentation

RFdiffusion is an open-source method for protein structure generation. It supports both unconditional generation and conditional generation (using motifs, targets, etc.).

Key capabilities include:

• Motif Scaffolding: Building a protein around a specific functional motif.
• Unconditional protein generation: Generating novel protein structures without specific constraints.
• Symmetric unconditional generation: Generating proteins with cyclic, dihedral, or tetrahedral symmetries.
• Symmetric motif scaffolding: Scaffolding motifs within symmetric structures.
• Binder design: Designing proteins that bind to specific targets.
• Design diversification: Using 'partial diffusion' to sample around an existing design.

The backbone assessment tools require STRIDE to quantify helix, sheet, coil, and turn content. You can build it from the source using the following steps:

git clone https://github.com/heiniglab/stride
cd stride/
make stride
./stride

To use the scaffolded protein binder design (PPI) examples, you must extract the provided example scaffold files into the examples/ directory.

tar -xvf examples/ppi_scaffolds_subset.tar.gz -C examples/

To achieve significant computational speedup on NVIDIA Volta, Turing, and Ampere GPU architectures, you can enable Automatic Mixed Precision. This uses FP16 for operations while maintaining FP32 master weights and handles loss scaling automatically via a GradScaler to preserve gradient magnitudes.

To enable this, use the --amp flag when running your scripts.

To use a custom dataset, extend the DataModule class located in se3_transformer/data_loading/data_module.py.

Your custom collate function must return a tuple containing:

1. A (batched) DGLGraph object.
2. A dictionary of node features: {'degree': tensor}.
3. A dictionary of edge features: {'degree': tensor}.
4. (Optional) Precomputed bases as a dictionary.
5. Labels as a tensor.

After implementing the data module, update training.py and inference.py to utilize your new class.

RFdiffusion requires NVIDIA's implementation of SE(3)-Transformers. This setup involves creating a specific Conda environment and installing the SE3Transformer module.

Note: The provided env/SE3nv.yml supports CUDA 11.1. You may need to customize the cudatoolkit and pytorch versions in the .yml file to match your specific GPU and driver setup.

Installation steps:

1. Create the environment from the provided YAML.
2. Activate the environment.
3. Install the SE3Transformer requirements and the module itself.
4. Install the rfdiffusion module from the repository root.

Always ensure you activate the SE3nv environment before running diffusion tasks.

conda env create -f env/SE3nv.yml

conda activate SE3nv
cd env/SE3Transformer
pip install --no-cache-dir -r requirements.txt
python setup.py install
cd ../..
pip install -e .

RFdiffusion can scaffold specific segments (motifs) from a PDB file. This is controlled via the contigmap.contigs configuration:

• Motif specification: Prefix a residue range with a chain letter (e.g., A10-25 refers to residues 10 through 25 on chain A).
• Built protein: Specify a length range without a prefix (e.g., 5-15) to tell the model to build a random number of residues in that range.
• Chain breaks: Use /0 (note the space) to indicate a jump between chains.
• Fixed total length: Use contigmap.length=N-N to ensure the final scaffolded protein has a specific total length.

Example: To scaffold residues 10-25 on chain A, with 5-15 residues built N-terminally and 30-40 residues built C-terminally: 'contigmap.contigs=[5-15/A10-25/30-40]'

You must also provide the input file using inference.input_pdb=path/to/file.pdb.

To design a binder for a specific target (e.g., chain B), specify the target residues in the contig map and use ppi.hotspot_res to guide the binder to a specific interface. Using hotspots allows you to crop the target protein to speed up computation without losing interface specificity.

• Hotspot Syntax: 'ppi.hotspot_res=[ChainIDResidueIndex,ChainIDResidueIndex]' (e.g., A30,A33,A34).
• Topology Diversity: The default model generates mostly helical binders. To generate a wider variety of topologies, use the 'beta' model via inference.ckpt_override_path=models/Complex_beta_ckpt.pt.

The primary entry point for running RFdiffusion is scripts/run_inference.py. The script is governed by Hydra configurations, which allow you to override parameters from the command line. Sensible defaults are drawn directly from the model checkpoint to ensure inference matches training.

To run the script, you typically pass arguments in the format key=value. For complex arguments like lists (e.g., contigs), the entire argument must be enclosed in single quotes ('') to prevent the command line from misinterpreting special characters.

./scripts/run_inference.py

To condition binder design or monomer generation on specific topologies, you can generate secondary structure and block adjacency files from PDB structures using the make_secstruc_adj.py script.

Usage for a single PDB:

./make_secstruc_adj.py --input_pdb ./2KL8.pdb --out_dir /my/dir/for/adj_secstruct

Usage for a directory of PDBs:

./make_secstruc_adj.py --pdb_dir ./pdbs/ --out_dir /my/dir/for/adj_secstruct

To set up the SE(3)-Transformer environment, use the provided Dockerfile which extends the PyTorch 21.07 NGC container.

Requirements:

• NVIDIA Docker
• PyTorch 21.07+ NGC container
• Supported GPUs: NVIDIA Volta, Turing, or Ampere architectures.

Quick Start Steps:

1. Clone the repository and navigate to the SE3Transformer directory.
2. Build the container.
3. Run an interactive session with necessary resource limits and volume mounts for results.
4. Execute the provided training and prediction scripts.

Partial diffusion allows you to add diversity to an existing structure by partially noising and then de-noising it. This is controlled by diffuser.partial_T.

• Timesteps: The default diffuser.T is 50.
• Noise level: Higher partial_T values result in more diversity. If you previously used partial_T=80 with 200 timesteps, the equivalent for the current 50-step default is diffuser.partial_T=20.
• Constraint: When performing partial diffusion, the contigmap.contigs input must yield a string exactly the same length as the input protein.

Example: To diversify a 100aa binder (chain A) in the presence of a 150aa target (chain B): 'contigmap.contigs=[100-100/0 B1-150]' diffuser.partial_T=20