atomworks 3.0.0

atomworks is an open-source platform that maximizes research velocity for biomolecular modeling tasks. Much like how Torchvision enables rapid prototyping within the vision domain, and Torchaudio within the audio domain, AtomWorks aims to accelerate development and experimentation within biomolecular modeling.

Upgrading to 3.0? See the migration guide.

If you're looking for the models themselves (e.g., RF3, RFD3, MPNN) that integrate with AtomWorks rather than the underlying framework, check out Foundry

💡 Note: Start with the AtomWorks examples or the model-building tutorial.

AtomWorks is composed of two symbiotic libraries:

• atomworks.io: A universal Python toolkit for parsing, cleaning, manipulating, and converting biological data (structures, sequences, small molecules). Built on the biotite API, it seamlessly loads and exports between standard formats like mmCIF, PDB, FASTA, SMILES, MOL, and more. Broadly useful for anyone who works with structural data for biomolecules.
• atomworks.ml: Advanced dataset featurization and sampling for deep learning workflows that uses atomworks.io as its structural backbone. We provide a comprehensive, pre-built and well-tested set of Transforms for common tasks that can be easily composed into full deep-learning pipelines; users may also create their own Transforms for custom operations.

For more detail on the motivation for and applications of AtomWorks, please see the preprint.

AtomWorks is built atop biotite: We are grateful to the Biotite developers for maintaining such a high-quality and flexible toolkit, and hope that our package will prove a helpful addition to the broader biotite community.

atomworks.io

A general-purpose Python toolkit for cleaning, standardizing, and manipulating biomolecular structure files, built on Biotite.

atomworks.io lets you:

• Parse, convert, and clean any common biological file (structure or sequence). For example, identifying and removing leaving groups, correcting bond order after nucleophilic addition, fixing charges, parsing covalent geometries, and appropriate treatment of structures with multiple occupancies and ligands at symmetry centers
• Transform all data to a consistent AtomArray representation for further analysis or machine learning applications, regardless of initial source
• Model missing atoms (those implied by the sequence but not represented in the coordinates) and initialize entity- and instance-level annotations (see the glossary for more detail on our composable naming conventions)

We have found atomworks.io to be generally useful to a broad bioinformatics and protein design audience; in many cases, atomworks.io can replace bespoke scripts and manual curation, enabling researchers to spend more time testing hypothesis and less time juggling dozens of tools and dependencies.

atomworks.ml

Modular, component-based library for dataset featurization within biomolecular deep learning workflows

atomworks.ml provides:

• A library of pre-built, well-tested Transforms that can be slotted into novel pipelines
• An extensible framework, integrated with atomworks.io, to write Transforms for arbitrary use cases
• Pre-built datasets and samplers suitable for most model training scenarios

Transforms consume and return dictionaries containing structural data, annotations and features. Biotite's AtomArray provides their shared atom-level representation.

We have found that atomworks.ml dramatically reduces the overhead of starting, and completing, many ML projects; research topics that once took months now achieve signal within weeks if not days, accelerating the pace of innovation.

When to use atomworks.io vs atomworks.ml?

• Use atomworks.io when you:

  • Need to parse/clean/convert between biological file formats (mmCIF, PDB, FASTA, etc.)
  • Want a unified structural representation to plug into any downstream analysis or modeling
  • Need structural operations like adding missing atoms, filtering ligands/solvents, or assembly generation

• Use atomworks.ml when you:

  • Need to featurize entire datasets for deep learning
  • Want ready-made sampling and batching utilities for training pipelines
  • Already use atomworks.io and want a seamless bridge to ML-ready feature engineering

Installation

AtomWorks requires Python 3.11 or newer. Pip installs its dependencies automatically.

pip install atomworks # base installation version without torch (for only atomworks.io)
pip install "atomworks[ml]" # with torch and ML dependencies (for atomworks.io plus atomworks.ml)
pip install "atomworks[dev]" # with development dependencies
pip install "atomworks[openbabel]" # with [Open Babel](https://openbabel.org/) and its dependencies
pip install "atomworks[ml,openbabel,dev]" # ML, Open Babel, and development tools

Running multiple of these installations will just add to the installed dependencies and will not install multiple installations of atomworks.

If you are using uv for package management, you can install atomworks with:

uv pip install "atomworks[ml,openbabel,dev]"

To install the AtomWorks 3.0 release branch before it is published on PyPI:

pip install "atomworks[ml] @ git+https://github.com/RosettaCommons/atomworks.git@release/atomworks-3-0"

For more advanced setup options (including how to run workflows via apptainers) see the full documentation.

Getting started

This section contains information for how to get atomworks set up and a quick guide for using some of the features of atomworks.io to parse PDB files. To learn more about the features in atomworks.io and atomworks.ml, see the external documentation.

To parse a pdb file (parse = load, clean, annotate relevant metadata such as entities, molecules, etc) you can use the parse function:

Note: To run the code in this section you will need to download the 3nez.cif.gz file yourself. See the examples for how to download files from the PDB within a Python script.

from atomworks.io import parse
from atomworks.io.config import ParseConfig
from biotite.structure import AtomArrayStack

result = parse("3nez.cif.gz", config=ParseConfig.from_preset("rcsb"))

asym_unit: AtomArrayStack = result["asym_unit"]
assemblies: dict[str, AtomArrayStack] = result["assemblies"]

for chain_id, info in result["chain_info"].items():
    print(chain_id, info["processed_entity_canonical_sequence"])

The output of parse includes:

• chain_info — Sequences/metadata for each chain
• ligand_info — Ligand annotation & metrics
• asym_unit — Structure (AtomArrayStack)
• assemblies — Built biological assemblies (each are their own AtomArrayStack)
• metadata — Experimental and source information

See usage examples for more examples of the use of parse(). All of the provided examples make use of this method. See API reference documentation for more information on this method.

For minimal processing, use the same parser with the minimal preset:

from atomworks.io import parse
from biotite.structure import AtomArray

atom_array: AtomArray = parse("3nez.cif.gz", config="minimal")["asym_unit"][0]

Contribution

We welcome improvements!

Please see the contributors guide in the full documentation for contribution guidelines.

Acknowledgments

We thank Hope Woods and Rachel Clune from the Rosetta Commons for their partnership and collaboration on the codebase, documentation, tutorials, and examples.

Citation

If you make use of AtomWorks in your research, please cite:

N. Corley*, S. Mathis*, R. Krishna*, M. S. Bauer, T. R. Thompson, W. Ahern, M. W. Kazman, R. I. Brent, K. Didi, A. Kubaney, L. McHugh, A. Nagle, A. Favor, M. Kshirsagar, P. Sturmfels, Y. Li, J. Butcher, B. Qiang, L. L. Schaaf, R. Mitra, K. Campbell, O. Zhang, R. Weissman, I. R. Humphreys, Q. Cong, H. Jiang, J. Funk, S. Sonthalia, P. Lio, D. Baker, F. DiMaio, "Accelerating Biomolecular Modeling with AtomWorks and RF3," bioRxiv, August 2025. doi: 10.1101/2025.08.14.670328

If you use bibtex, here's the GoogleScholar formatted citation:

@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},
  pages={2025--08},
  year={2025},
  publisher={Cold Spring Harbor Laboratory}
}