{"id":49378774,"url":"https://github.com/RosettaCommons/atomworks","last_synced_at":"2026-05-14T14:01:56.287Z","repository":{"id":310543718,"uuid":"1037693767","full_name":"RosettaCommons/atomworks","owner":"RosettaCommons","description":"A generalized computational framework for biomolecular modeling.","archived":false,"fork":false,"pushed_at":"2026-04-07T17:29:32.000Z","size":160755,"stargazers_count":408,"open_issues_count":24,"forks_count":41,"subscribers_count":13,"default_branch":"production","last_synced_at":"2026-04-07T19:18:41.688Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://rosettacommons.github.io/atomworks/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RosettaCommons.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-14T01:25:27.000Z","updated_at":"2026-04-07T17:26:29.000Z","dependencies_parsed_at":"2025-09-25T22:39:34.707Z","dependency_job_id":null,"html_url":"https://github.com/RosettaCommons/atomworks","commit_stats":null,"previous_names":["rosettacommons/atomworks"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/RosettaCommons/atomworks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RosettaCommons%2Fatomworks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RosettaCommons%2Fatomworks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RosettaCommons%2Fatomworks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RosettaCommons%2Fatomworks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RosettaCommons","download_url":"https://codeload.github.com/RosettaCommons/atomworks/tar.gz/refs/heads/production","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RosettaCommons%2Fatomworks/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33028203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-28T04:00:26.991Z","updated_at":"2026-05-14T14:01:56.261Z","avatar_url":"https://github.com/RosettaCommons.png","language":"Python","funding_links":[],"categories":["3. End-to-End Structural Modeling \u003ca name=\"3\"\u003e\u003c/a\u003e"],"sub_categories":["3.2 Generative modeling of protein–ligand complexes and equilibrium ensembles \u003ca name=\"3.2\"\u003e\u003c/a\u003e"],"readme":"[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![PyPI version](https://img.shields.io/pypi/v/atomworks.svg)](https://pypi.org/project/atomworks/)\n[![Python versions](https://img.shields.io/pypi/pyversions/atomworks.svg)](https://pypi.org/project/atomworks/)\n[![Documentation Status](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://rosettacommons.github.io/atomworks/latest/)\n[![License: BSD 3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/_static/atomworks_logo_color.svg\" width=\"450\" alt=\"atomworks logo\"\u003e\n\u003c/div\u003e\n\n**atomworks** is an open-source platform that maximizes research velocity for biomolecular modeling tasks. Much like how [Torchvision](https://docs.pytorch.org/vision/stable/index.html) enables rapid prototyping within the vision domain, and [Torchaudio](https://docs.pytorch.org/audio/main/) within the audio domain, AtomWorks aims to accelerate development and experimentation within biomolecular modeling.\n\n\u003e **⚠️ Notice:** We are currently finalizing some cleanup work within our repositories. Please expect the APIs (e.g., function and class names, inputs and outputs) to stabilize within the next one week. Thank you for your patience!\n\nIf you're looking for the models themselves (e.g., RF3, RFD3, MPNN) that integrate with AtomWorks rather than the underlying framework, check out [Foundry](https://github.com/RosettaCommons/foundry)\n\n\u003e **💡 Note:** Not sure where to start? We've made some [examples in the AtomWorks documentation](https://rosettacommons.github.io/atomworks/latest/auto_examples/index.html) that work through several helpful scenarios; a full tutorial is under construction!\n\nAtomWorks is composed of two symbiotic libraries:\n\n- `atomworks.io`: A universal Python toolkit for parsing, cleaning, manipulating, and converting biological data (structures, sequences, small molecules). Built on the [biotite](https://www.biotite-python.org/) 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.\n- `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.\n\nFor more detail on the motivation for and applications of AtomWorks, please see the [preprint](https://doi.org/10.1101/2025.08.14.670328). \n\nAtomWorks is built atop [biotite](https://www.biotite-python.org/): 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.\n\n---\n\n## atomworks.io\n\n\u003e *A general-purpose Python toolkit for cleaning, standardizing, and manipulating with biomolecular structure files - built atop [biotite](https://www.biotite-python.org/):\n\n**atomworks.io** lets you:\n\n- 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\n- Transform all data to a consistent `AtomArray` representation for further analysis or machine learning applications, regardless of initial source\n- Model missing atoms (those implied by the sequence but not represented in the coordinates) and initialize entity- and instance-level annotations (see the [glossary](https://rosettacommons.github.io/atomworks/latest/glossary.html) for more detail on our composable naming conventions)\n\nWe 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.\n\n---\n\n## atomworks.ml\n\n\u003e *Modular, component-based library for dataset featurization within biomolecular deep learning workflows*\n\n**atomworks.ml** provides:\n\n- A library of pre-built, well-tested `Transforms` that can be slotted into novel pipelines\n- An extensible framework, integrated with `atomworks.io`, to write `Transforms` for arbitrary use cases\n- Pre-built datasets and samplers suitable for most model training scenarios\n\nWithin the AtomWorks paradigm, the output of each `Transform` is not an opaque dictionary with model-specific tensors but instead an updated version of our atom-level structural representation (Biotite's `AtomArray`). Operations within – and between – pipelines thus maintain a common vocabulary of inputs and outputs.\n\nWe 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.\n\n---\n\n## When to use `atomworks.io` vs `atomworks.ml`?\n\n- Use `atomworks.io` when you:\n  - Need to parse/clean/convert between biological file formats (mmCIF, PDB, FASTA, etc.)\n  - Want a unified structural representation to plug into any downstream analysis or modeling\n  - Need structural operations like adding missing atoms, filtering ligands/solvents, or assembly generation\n\n- Use `atomworks.ml` when you:\n  - Need to featurize entire datasets for deep learning\n  - Want ready-made sampling and batching utilities for training pipelines\n  - Already use `atomworks.io` and want a seamless bridge to ML-ready feature engineering\n\n---\n\n## Installation\n\u003e Note: AtomWorks requires Python \u003e= 3.11 and [`dotenv`](https://pypi.org/project/python-dotenv/#file-format)\n\n```shell\npip install atomworks # base installation version without torch (for only atomworks.io)\npip install \"atomworks[ml]\" # with torch and ML dependencies (for atomworks.io plus atomworks.ml)\npip install \"atomworks[dev]\" # with development dependencies\npip install \"atomworks[openbabel]\" # with [Open Babel](https://openbabel.org/) and its dependencies\npip install \"atomworks[ml,openbabel,dev]\" # with all dependencies\n```\n*Running multiple of these installations will just add to the installed dependencies and will not install multiple installations of atomworks.*\n\nIf you are using [uv](https://docs.astral.sh/uv/reference/policies/versioning/) for package management, you can install atomworks with:\n\n```shell\nuv pip install \"atomworks[ml,openbabel,dev]\"\n```\n\nFor more advanced setup options (including how to run workflows via apptainers) see the [full documentation](https://rosettacommons.github.io/atomworks/latest/index.html).\n\n---\n\n## Getting started\n\nThis 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](https://rosettacommons.github.io/atomworks/latest/). \n\nTo parse a pdb file (parse = load, clean, annotate relevant metadata such as entities, molecules, etc) you can use the `parse` function:\n\n\u003e Note: To run the code in this section you will need to download the 3nez.cif.gz file yourself. See the [examples](https://rosettacommons.github.io/atomworks/latest/auto_examples/index.html) for how to download files from the PDB within a Python script. \n\n```python\n\nfrom atomworks.io.parser import parse\nfrom biotite.structure import AtomArrayStack\n\nresult = parse(filename=\"3nez.cif.gz\")\n\nasym_unit: AtomArrayStack = result[\"asym_unit\"]\nassemblies: dict[str, AtomArrayStack] = result[\"assemblies\"]\n\nfor chain_id, info in result[\"chain_info\"].items():\n    print(chain_id, info[\"processed_entity_canonical_sequence\"])\n\n```\n\nThe output of `parse` includes:\n\n- **chain_info** — Sequences/metadata for each chain\n- **ligand_info** — Ligand annotation \u0026 metrics\n- **asym_unit** — Structure (`AtomArrayStack`)\n- **assemblies** — Built biological assemblies (each are their own `AtomArrayStack`)\n- **metadata** — Experimental and source information\n\nSee [usage examples](https://rosettacommons.github.io/atomworks/latest/auto_examples/index.html) for more examples of the use of `parse()`. All of the provided examples make use of this method. \nSee [API reference documentation](https://rosettacommons.github.io/atomworks/latest/io/parser.html) for more information on this method.\n\nIf you just want to load a file, you can use the `load_any` function:\n\n```python\nfrom atomworks.io.utils.io_utils import load_any\nfrom biotite.structure import AtomArray\n\natom_array: AtomArray = load_any(\"3nez.cif.gz\", model=1)  # model=1 means that we want to load the model 1 (i.e. the first model) rather than a stack of all models in the file\n```\n\n---\n\n## Contribution\n\nWe welcome improvements!\n\nPlease see the [contributors guide in the full documentation](https://rosettacommons.github.io/atomworks/latest/contributor_guide.html) for contribution guidelines.\n\n## Acknowledgments\n\nWe thank Hope Woods and Rachel Clune from the Rosetta Commons for their partnership and collaboration on the codebase, documentation, tutorials, and examples.\n\n## Citation\n\nIf you make use of AtomWorks in your research, please cite:\n\n\u003e 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,\n\u003e \"Accelerating Biomolecular Modeling with AtomWorks and RF3,\" bioRxiv, August 2025. doi: [10.1101/2025.08.14.670328](https://doi.org/10.1101/2025.08.14.670328)\n\nIf you use bibtex, here's the GoogleScholar formatted citation:\n\n```bibtex\n@article{corley2025accelerating,\n  title={Accelerating Biomolecular Modeling with AtomWorks and RF3},\n  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},\n  journal={bioRxiv},\n  pages={2025--08},\n  year={2025},\n  publisher={Cold Spring Harbor Laboratory}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRosettaCommons%2Fatomworks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRosettaCommons%2Fatomworks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRosettaCommons%2Fatomworks/lists"}