CONTRIBUTING

Contributing to foundry

This contributor’s guide is a non-exhaustive list of best practices for contributing to the foundry source code, adding a model, and/or contributing to the foundry documentation. These recommendations are a mixture of industry standards and expectations for this specific repository.

Table of Contents

Code Contributions

Code Organization

There is a strict dependency flow of Foundry -> AtomWorks. All models within Foundry use AtomWorks for manipulating and processing biomolecular structures, in both training and inference.

Here is an overview of how this system is structured:

  • AtomWorks: I/O, preprocessing structures, data featurization

  • Foundry: Model architectures, training, inference endpoints

  • models/<model>: Released models that use the structure provided by Foundry and AtomWorks

Installing Foundry in Editable Mode

Install both foundry and models in editable mode for development:

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/

As You Code

  1. Reduce cognitive overhead:

    1. Pick meaningful, descriptive variable names.
    2. Write docstrings and comments. All docstrings should be written using in the Google-format.
    3. Follow PEP8 (Style Guide for Python Code) whenever possible
    4. Follow PEP20 (The Zen of Python) whenever possible.

  2. Write tests. Tests for the Foundry source code can be found in foundry/tests, tests for individual models will be in their respective directories.

    Note

    Running tests is not currently supported, test files may be missing.

As You Commit

Foundry comes with a .pre-commit-config.yaml that runs make format (via ruff format) before each commit, enable it once per clone:

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

Once it is successfully installed, it will automatically format the repo whenever you run git commit, but you can apply it manually via pre-commit run --all-files.

Even with this, there are a few things to keep in mind to make sure your commits are easily reviewable:

  1. Keep commits as “one logical unit.” This means that each commit should be a set of related changes that accomplish one task, fix one bug, or implement one feature. Using an editor like VS Code or using GitHub Desktop can help you stage related changes together.

  2. Adhere to semantic commit conventions.

  3. Submit a draft PR so people know you are working on this & can provide advice/feedback early on.

As you Finalize a PR

  1. To make a PR merge your branch to production. The maintainers will review your PR.

  2. Keep overall PR under <400 LOC (lines of code) (Rule of thumb: 500 LOC takes about 1h to review).

Adding a Model

To be able to add new models as independent packages, make sure to install foundry and its models in ‘editable’ mode:

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

Once you have done this you can follow these steps to incorporate your model into the repository:

  1. Create a 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 this new model via uv pip install -e ./models/<model_name>

Documentation Contributions

The external Foundry documentation is built using Sphinx and GitHub Pages.

To build the documentation you need to have the dependencies listed in foundry/docs/docs_requirements.txt installed, which can be easily done via

uv pip install -r docs/docs_requirements.txt

To build the documentation, navigate to the docs directory and run:

make html

If you are new to Sphinx, please refer to the Sphinx documentation for guidance on writing and formatting documentation. The documentation for Foundry uses MyST_parser so that documentation pages can be written in Markdown or ReStructured Text.

Organization

The docs/source directory contains the documentation about the Foundry source code. The index.rst file located here is the landing page for the documentation.

Each model has its own docs folder (foundry/models/<model_name>/docs). The foundry/docs/source/models directory contains symlinks to these individual docs folders, this is necessary to allow Sphinx to see the model-specific documentation. If you are adding documentation for a new model, you will need to make a similar symlink:

  1. Make a docs directory in foundry/models/<model_name>

  2. From the foundry/docs/source/models directory run

    ln -s ../../../models/<model_name>/docs <model_name>

Each of the model documentation directories have their own index.md file that organizes that model’s documentation.