Metadata-Version: 2.4
Name: rc-foundry
Version: 0.1.12
Summary: Shared utilities and training infrastructure for biomolecular structure prediction models.
Author-email: Institute for Protein Design <contact@ipd.uw.edu>
License: BSD 3-Clause License
        
        Copyright (c) 2025, Institute for Protein Design, University of Washington
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        * Redistributions of source code must retain the above copyright notice, this
          list of conditions and the following disclaimer.
        
        * Redistributions in binary form must reproduce the above copyright notice,
          this list of conditions and the following disclaimer in the documentation
          and/or other materials provided with the distribution.
        
        * Neither the name of the copyright holder nor the names of its
          contributors may be used to endorse or promote products derived from
          this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE.md
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: <3.13,>=3.12
Requires-Dist: assertpy
Requires-Dist: atomworks[ml]>=2.1.1
Requires-Dist: beartype<1,>=0.18.0
Requires-Dist: dm-tree<1,>=0.1.6
Requires-Dist: einops<1,>=0.8.0
Requires-Dist: einx<1,>=0.1.0
Requires-Dist: environs<12,>=11.0.0
Requires-Dist: hydra-core<1.4,>=1.3.0
Requires-Dist: ipykernel>=6.31.0
Requires-Dist: jaxtyping<1,>=0.2.17
Requires-Dist: lightning>=2.5.0
Requires-Dist: loralib>=0.1.1
Requires-Dist: opt-einsum<4,>=3.4.0
Requires-Dist: pandas
Requires-Dist: rich>=13.9.4
Requires-Dist: rootutils<1.1,>=1.0.7
Requires-Dist: toolz
Requires-Dist: torch<3,>=2.2.0
Requires-Dist: typer<1,>=0.20.0
Requires-Dist: wandb<1,>=0.15.10
Requires-Dist: zstandard
Provides-Extra: all
Requires-Dist: cuequivariance-ops-cu12>=0.6.1; (sys_platform == 'linux') and extra == 'all'
Requires-Dist: cuequivariance-ops-torch-cu12>=0.6.1; (sys_platform == 'linux') and extra == 'all'
Requires-Dist: cuequivariance-torch>=0.6.1; (sys_platform == 'linux') and extra == 'all'
Requires-Dist: pydantic>=2.8; extra == 'all'
Provides-Extra: dev
Requires-Dist: assertpy; extra == 'dev'
Requires-Dist: atomworks[dev,ml,openbabel]>=2.1.1; extra == 'dev'
Requires-Dist: debugpy<2,>=1.8.5; extra == 'dev'
Requires-Dist: ipdb; extra == 'dev'
Requires-Dist: ipykernel<7,>=6.29.4; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest-benchmark<6,>=5.0.0; extra == 'dev'
Requires-Dist: pytest-cov<5,>=4.1.0; extra == 'dev'
Requires-Dist: pytest-dotenv<1,>=0.5.2; extra == 'dev'
Requires-Dist: pytest-testmon<3,>=2.1.1; extra == 'dev'
Requires-Dist: pytest-xdist<4,>=3.6.1; extra == 'dev'
Requires-Dist: pytest<9,>=8.2.0; extra == 'dev'
Requires-Dist: ruff==0.8.3; extra == 'dev'
Provides-Extra: rf3
Requires-Dist: cuequivariance-ops-cu12>=0.6.1; (sys_platform == 'linux') and extra == 'rf3'
Requires-Dist: cuequivariance-ops-torch-cu12>=0.6.1; (sys_platform == 'linux') and extra == 'rf3'
Requires-Dist: cuequivariance-torch>=0.6.1; (sys_platform == 'linux') and extra == 'rf3'
Provides-Extra: rfd3
Requires-Dist: pydantic>=2.8; extra == 'rfd3'
Description-Content-Type: text/markdown

# Protein design with Foundry

Foundry provides tooling and infrastructure for using and training all classes of models for protein design, including design (RFD3), inverse folding (ProteinMPNN) and protein folding (RF3).

All models within Foundry rely on [AtomWorks](https://github.com/RosettaCommons/atomworks) - a unified framework for manipulating and processing biomolecular structures - for both training and inference. 


> [!NOTE]
> We have a slack now! Join for updates and to get your questions answered [here](https://join.slack.com/t/proteinmodelfoundry/shared_invite/zt-3pj032444-jC8MRqsV8nhpKX0PGowQ4A).

## Getting Started
### Quickstart guide
**Installation**
```bash
pip install "rc-foundry[all]"
```

**Intel XPU Installation**

For Intel XPU devices, install PyTorch with XPU support first, then install Foundry.
```bash
pip install torch --index-url https://download.pytorch.org/whl/xpu
pip install "rc-foundry[all]"
```
> [!NOTE]
> Use `pip` (not `uv`) for XPU installs since UV re-resolves dependencies and may replace your XPU torch with the standard PyPI version.

**Downloading weights** Models can be downloaded to a target folder with:
```
foundry install base-models --checkpoint-dir <path/to/ckpt/dir>
```
where `checkpoint-dir` will be `~/.foundry/checkpoints` by default. Foundry always searches `~/.foundry/checkpoints` plus any colon-separated entries in `$FOUNDRY_CHECKPOINT_DIRS` during inference or subsequent commands to find checkpoints. `base-models` installs the latest RFD3, RF3 and MPNN variants - you can also download all of the models supported (including multiple checkpoints of RF3) with `all`, or by listing the models sequentially (e.g. `foundry install rfd3 rf3 ...`).
To list the registry of available checkpoints:
```
foundry list-available
```
To check what you already have downloaded (searches `~/.foundry/checkpoints` plus `$FOUNDRY_CHECKPOINT_DIRS` if set):
```
foundry list-installed
```

>*See `examples/all.ipynb` for how to run each model and design proteins end-to-end in a notebook.*

### Docker Image

There is an official [Foundry image](https://hub.docker.com/r/rosettacommons/foundry) maintained by the [Rosetta Commons](https://rosettacommons.org/). The default image comes with the model weights for the available models, but you can use the `slim` tag to either use pre-exiting model weights or use the image to download the available model weights. 

For more information and example syntax, see the [Overview on DockerHub](https://hub.docker.com/r/rosettacommons/foundry).

The recipe to create the Docker image can be found in `foundry/examples/docker` and can be used as a "blue-print" for creating your own images. 

### Google Colab
For an interactive Google Colab notebook walking through a basic design pipeline with RFD3, MPNN, and RF3, please see the [IPD Design Pipeline Tutorial](https://colab.research.google.com/drive/1ZwIMV3n9h0ZOnIXX0GyKUuoiahgifBxh?usp=sharing).

### RFdiffusion3 (RFD3)

[RFdiffusion3](https://www.biorxiv.org/content/10.1101/2025.09.18.676967v2) is an all-atom generative model capable of designing protein structures under complex constraints. 

<div align="center">
  <img src="docs/_static/cover.png" alt="RFdiffusion3 generation trajectory." width="700">
</div>

> *See [models/rfd3/README.md](models/rfd3/README.md) for complete documentation.*

### RosettaFold3 (RF3)

[RF3](https://doi.org/10.1101/2025.08.14.670328) is a structure prediction neural network that narrows the gap between closed-source AF-3 and open-source alternatives.

<div align="center">
  <img src="docs/_static/prot_dna.png" alt="Protein-DNA complex prediction" width="400">
</div>

> *See [models/rf3/README.md](models/rf3/README.md) for complete documentation.*

### ProteinMPNN
[ProteinMPNN](https://www.science.org/doi/10.1126/science.add2187) and [LigandMPNN](https://www.nature.com/articles/s41592-025-02626-1) are lightweight inverse-folding models which can be use to design diverse sequences for backbones under constrained conditions.

> *See [models/mpnn/README.md](models/mpnn/README.md) for complete documentation.*

---

## Development

### Code Organization

**Strict dependency flow:** `foundry` → `atomworks`

- **atomworks**: Structure I/O, preprocessing, featurization
- **foundry**: Model architectures, training, inference endpoints
- **models/\<model\>:** Released models.

#### For Core Developers (Multiple Packages)

Install both `foundry` and models in editable mode for development:

```bash
uv pip install -e '.[all,dev]'
```

This approach allows you to:
- Modify `foundry` shared utilities and see changes immediately
- Work on specific models without installing all models
- Add new models as independent packages in `models/`

> [!NOTE]
> Running tests is not currently supported, test files may be missing.

### Adding New Models

To add a new model:

1. Create `models/<model_name>/` directory with its own `pyproject.toml`
2. Add `foundry` as a dependency
3. Implement model-specific code in `models/<model_name>/src/`
4. Users can install with: `uv pip install -e ./models/<model_name>`

### Pre-commit Formatting

We ship a `.pre-commit-config.yaml` that runs `make format` (via `ruff format`) before each commit. Enable it once per clone:

```bash
pip install pre-commit  # if not already installed
pre-commit install
```

After installation the hook automatically formats the repo whenever you `git commit`. Use `pre-commit run --all-files` to apply it manually.

## Citation

If you use this repository code or data in your work, please cite the relavant work as below:

```bibtex
@article{corley2025accelerating,
  title={Accelerating biomolecular modeling with atomworks and rf3},
  author={Corley, Nathaniel and Mathis, Simon and Krishna, Rohith and Bauer, Magnus S and Thompson, Tuscan R and Ahern, Woody and Kazman, Maxwell W and Brent, Rafael I and Didi, Kieran and Kubaney, Andrew and others},
  journal={bioRxiv},
  year={2025}
}

@article {butcher2025_rfdiffusion3,
    author = {Butcher, Jasper and Krishna, Rohith and Mitra, Raktim and Brent, Rafael Isaac and Li, Yanjing and Corley, Nathaniel and Kim, Paul T and Funk, Jonathan and Mathis, Simon Valentin and Salike, Saman and Muraishi, Aiko and Eisenach, Helen and Thompson, Tuscan Rock and Chen, Jie and Politanska, Yuliya and Sehgal, Enisha and Coventry, Brian and Zhang, Odin and Qiang, Bo and Didi, Kieran and Kazman, Maxwell and DiMaio, Frank and Baker, David},
    title = {De novo Design of All-atom Biomolecular Interactions with RFdiffusion3},
    elocation-id = {2025.09.18.676967},
    year = {2025},
    doi = {10.1101/2025.09.18.676967},
    publisher = {Cold Spring Harbor Laboratory},
    URL = {https://www.biorxiv.org/content/early/2025/11/19/2025.09.18.676967},
    eprint = {https://www.biorxiv.org/content/early/2025/11/19/2025.09.18.676967.full.pdf},
    journal = {bioRxiv}
}

@article{dauparas2022robust,
  title={Robust deep learning--based protein sequence design using ProteinMPNN},
  author={Dauparas, Justas and Anishchenko, Ivan and Bennett, Nathaniel and Bai, Hua and Ragotte, Robert J and Milles, Lukas F and Wicky, Basile IM and Courbet, Alexis and de Haas, Rob J and Bethel, Neville and others},
  journal={Science},
  volume={378},
  number={6615},
  pages={49--56},
  year={2022},
  publisher={American Association for the Advancement of Science}
}

@article{dauparas2025atomic,
  title={Atomic context-conditioned protein sequence design using LigandMPNN},
  author={Dauparas, Justas and Lee, Gyu Rie and Pecoraro, Robert and An, Linna and Anishchenko, Ivan and Glasscock, Cameron and Baker, David},
  journal={Nature Methods},
  pages={1--7},
  year={2025},
  publisher={Nature Publishing Group US New York}
}
```
## Acknowledgments
We thank Rachel Clune and Hope Woods from the RosettaCommons for their collaboration on the codebase, documentation, tutorials and examples. 
