Metadata-Version: 2.4
Name: bionemo-ir
Version: 0.2.0rc1
Summary: BioNeMo Inference Runtime: GPU accelerated framework for protein folding
Author: NVIDIA-BioNeMo team
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime
Project-URL: Documentation, https://docs.nvidia.com/bionemo/inference-runtime
Project-URL: Changelog, https://docs.nvidia.com/bionemo/inference-runtime/latest/release-notes/overview
Project-URL: Repository, https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime
Project-URL: Issues, https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/issues
Requires-Python: <4.0,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: LICENSES/BSD-2-Clause.txt
License-File: LICENSES/BSD-3-Clause.txt
License-File: LICENSES/Biopython-License-Agreement.txt
License-File: LICENSES/MIT.txt
License-File: LICENSES/MPL-2.0.txt
Requires-Dist: cuda-python>=13
Requires-Dist: torch>=2.11
Requires-Dist: cuequivariance==0.11.1
Requires-Dist: cuequivariance-ops-cu13==0.11.1
Requires-Dist: cuequivariance-ops-torch-cu13==0.11.1
Requires-Dist: triton<3.7.1,>=3.6.0
Requires-Dist: biopython>=1.87
Requires-Dist: ray[data,serve]==2.56.1
Requires-Dist: urllib3>=2.8.0
Requires-Dist: virtualenv>=21.14.5
Requires-Dist: uvloop==0.21.0
Requires-Dist: modelcif==1.6
Requires-Dist: rdkit==2025.9.6
Requires-Dist: nvidia-cutlass-dsl[cu13]==4.5.2
Requires-Dist: nvidia-cudnn-frontend==1.23.0
Requires-Dist: apache-tvm-ffi<0.2,>=0.1.6
Requires-Dist: biotite==1.6.0
Requires-Dist: datasets==4.8.4
Requires-Dist: huggingface_hub<2,>=0.25
Requires-Dist: PyYAML>=6.0.3
Requires-Dist: lru-dict==1.4.1
Requires-Dist: kalign-python==3.6.0
Requires-Dist: scipy==1.13.1
Requires-Dist: gemmi==0.6.5
Requires-Dist: einops>=0.8
Requires-Dist: pydantic<3,>=2
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file


<div align="center">

# BioNeMo Inference Runtime

Easy, fast, and memory-efficient structure prediction inference

GPU-accelerated inference for protein, nucleic-acid, and ligand structure
prediction models — from FASTA/MSA to PDB/mmCIF.

[![Documentation][docs-badge]][docs-site] [![License][license-badge]][license]
[![CUDA][cuda-badge]][cuda-downloads] [![PyTorch][torch-badge]][pytorch]
[![PyPI][pypi-badge]][pypi]

![Speedup against input size on H100](https://raw.githubusercontent.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/main/docs/assets/speedup-vs-residues.png)

</div>

## About

BioNeMo Inference Runtime (BioIR) is NVIDIA's library for structure-prediction
inference. A five-stage GPU pipeline turns AlphaFold-lineage and all-atom models
into PDB/mmCIF with confidence scores. Models stay ordinary `nn.Module`s — no
TensorRT engine build.

## Disclaimer

BioIR is in a Beta state, may not be fully functional, may contain errors or
design flaws, and may be changed at any time without notice. We appreciate your
feedback to improve and iterate on our products.

## Getting Started

### Prerequisites

- **Linux, x86_64 or aarch64**, with an NVIDIA GPU. The wheels are
  `manylinux_2_34`, so the host needs glibc 2.34 or newer — Ubuntu 22.04, RHEL 9
  or later.
- **Driver 580 or newer.** The dev image carries a CUDA 13.2 build of PyTorch.
  An older driver runs it only through the forward-compatibility shim, which we
  have measured hanging and crashing part-way through a run rather than merely
  running slowly — results taken on one are discarded, not corrected.
- **Python 3.12.** The released wheels are tagged `cp312`, so pip finds no
  matching build on a newer interpreter.
- **Docker** and the **NVIDIA Container Toolkit**, to build from source in the
  dev container. Installing the wheel needs neither.

PyTorch and the CUDA math libraries arrive as wheel dependencies, or in
`nvcr.io/nvidia/pytorch:26.05-py3` when you use the container. Building the
extension from source outside a container needs a C++17 compiler and CUDA
headers as well — [`docs/dev.md`][dev-prerequisites].

[dev-prerequisites]: https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/dev.md#prerequisites-for-bioir-development-workflow

### Supported GPUs

BioIR runs on the Ampere, Ada Lovelace, Hopper, and Blackwell GPUs listed in the
[support matrix](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/ref/support-matrix.md#gpus). The doc also shows which
fused kernels apply to each architecture. [Benchmarks](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/ref/benchmark.md)
page shows detailed speedup, memory, and accuracy for these GPUs: H200, H100,
A100, L40S, GB200, and GB300.

### Install

BioIR is published on PyPI, one wheel per CPU architecture:

```bash
pip install bionemo-ir
```

The wheel ships the kernels precompiled, so nothing in the install builds CUDA
and running it needs only the driver's `libcuda.so.1`. That is the whole install
if you are calling BioIR from your own code — the container below is for working
on BioIR itself. [`docs/install.md`](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/install.md) covers the environment
setup and the requirements in full.

### Build from source

Configure [SSH authentication with GitHub][github-ssh], then clone the
repository and fetch its submodules and LFS objects.

```bash
git lfs install &&
  GIT_LFS_SKIP_SMUDGE=0 \
    git clone --recurse-submodules \
    git@github.com:NVIDIA-BioNeMo/BioNeMo-Inference-Runtime.git &&
  cd BioNeMo-Inference-Runtime
```

On a host with the required compiler and CUDA headers, uv provisions the pinned
Python and exact dependency set, builds the editable extension, and runs tools
inside that environment:

```bash
uv sync --locked
uv run --locked scripts/fetch_weights.sh --model boltz-2
uv run --locked python examples/folding/run_demo.py --output-dir output
```

The supported container workflow remains available when the host is not
configured:

```bash
docker/dev.sh
```

Then run inside its shell:

```bash
uv lock --check
uv pip install --no-deps -e .
scripts/fetch_weights.sh --model boltz-2
python examples/folding/run_demo.py --output-dir output
```

Checkpoints come from their upstream publishers and need no NVIDIA credentials;
anything that cannot be fetched is skipped, and the tests needing it skip too.
Running `uv run --locked scripts/run_tests.sh` on the host, or
`scripts/run_tests.sh` in the container, stages weights and runs the suite the
way CI does.

See [`docs/dev.md`](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/dev.md#prerequisites-for-bioir-development-workflow)
for the host prerequisites, environment details and wheel build.
[`docs/ref/docker-images.md`](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/ref/docker-images.md) covers the images and
what `docker/dev.sh` mounts.

## Documentation

BioIR documentation lives under [`docs/`](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/tree/main/docs/) and is published with Fern:

- [Overview](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/overview.mdx) — what BioIR is and how to start
- [Installation](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/install.md) — requirements and release-wheel installation
- [Quickstart](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/quickstart.md) — run a serial Boltz-2 prediction
- [Ray multi-GPU inference](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/ray.md) — scale independent requests across
  visible GPUs
- [Accelerate a custom model](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/advanced/accelerate-custom-model.md) — swap
  BioIR modules into your own PyTorch model
- [Port a data pipeline](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/advanced/port-data-pipeline.md) — run a new model
  family through `build_processor`
- [Validate a ported pipeline](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/advanced/validate-data-pipeline.md) —
  feature equivalence and end-to-end accuracy against upstream
- [Developer guide](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/dev.md) — build, test, stage weights, contribute
- [API reference](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/ref/api.md) — `build_processor`, model constructors,
  inputs/outputs
- [Architecture](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/ref/architecture.md) — five-stage pipeline and runtime
  design
- [Config architecture](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/ref/config.md) — model `BaseConfig` tree and
  pipeline stage configs
- [Support matrix](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/ref/support-matrix.md) — models, GPUs, and fused kernels
- [Token padding](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/ref/token-padding.md) — what BioIR pads to a multiple
  of 8 tokens, and why it runs faster
- [Benchmarks](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/ref/benchmark.md) — measured speedup and memory against OSS
  PyTorch
- [Model weights](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/ref/model-weights.md) — checkpoint resolution and staging
- [Docker images](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/ref/docker-images.md) — development and runtime images
- [Coding guidelines](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/coding.md) — style, naming, and tooling
- [Folding example](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/examples/folding/README.md) — runnable `build_processor`
  demo

## Benchmarks

### Methodology

Folding benchmarks over a bench set the shipped
[`rebuild_dataset.py`](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/tree/main/.agents/skills/bench-perf-oss/dataset/) builds from RCSB
and NVIDIA's MSA Search NIM — there is no dataset release to download.
Template-bearing samples included: both sides load every bundled MSA and attach
every listed template.

- One GPU, serial, one structure per forward call.
- Time only GPU-synchronized `model.forward()`. Featurization, transfers,
  postprocessing, writing, and scoring stay outside the window.
- Discard one warmup forward, then report one measured forward per sample.
- BioIR runs its default optimized config, which captures CUDA graphs of each
  model's trunk recycle, diffusion step, and confidence Pairformer for inputs
  up to 1024 tokens. The results below, measured 2026-09-08, used a CUDA graph
  on the diffusion module only.
- OSS runs its own inference script: eager always, plus `torch.compile` when it
  passes a dynamic-shape probe.
- Runtime knobs match on both sides — 200 sampling steps, 3 or 5 diffusion
  samples, and per-model recycling.
- Score written structures with OpenStructure lDDT and DockQ. Speedup is
  `OSS forward / BioIR forward`; above 1 favors BioIR.
- Future work will add additional Blackwell-optimized kernels.

### Results

<!-- BEGIN generated: benchmark summary -->

| Model                           | H100          | H200          |
| ------------------------------- | ------------- | ------------- |
| Boltz-2                         | 1.78x / 2.65x | 1.74x / 2.54x |
| OpenFold3                       | 1.55x / 2.02x | 1.54x / 2.03x |
| OpenFold2 / AlphaFold2 monomer  | 2.55x / 2.60x | 2.61x / 2.66x |
| OpenFold2 / AlphaFold2 multimer | 2.66x / 2.77x | 2.61x / 2.75x |
| Protenix                        | — / 1.87x     | — / 1.84x     |

Geomean speedup, `vs OSS torch.compile / vs OSS PyTorch eager`; above 1 favours
BioIR. Protenix has no `torch.compile` path. Fourteen GPUs, per-model accuracy
and peak memory, and how to reproduce any of it:
[`docs/ref/benchmark.md`](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/ref/benchmark.md).

<!-- END generated: benchmark summary -->

The [`bench-perf-oss` agent skill](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/.agents/skills/bench-perf-oss/SKILL.md) has
the full gates, environment isolation, result schema, and charting protocol.

[github-ssh]:
  https://docs.github.com/en/authentication/connecting-to-github-with-ssh

## Contributing

We welcome contributions. See [`contributing.md`](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/contributing.md) for
policy and [`docs/dev.md`](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/dev.md) for the development workflow.

## Citation

If you use BioIR in your research, please cite it via
[`CITATION.cff`](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/CITATION.cff).

## Contact / Support

- Bugs and feature requests:
  [GitHub Issues](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/issues/new/choose)
- Usage questions:
  [GitHub Discussions](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/discussions)
- Security vulnerabilities: see [`SECURITY.md`](https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/docs/SECURITY.md) — do **not**
  file a public issue

## License

NVIDIA-authored BioIR code is licensed under the [Apache License 2.0][license].
Distribution compliance material is available here:

- [Third-party notices and attributions][third-party-notices]
- [Full third-party license texts][third-party-licenses]
- [Gemmi 0.6.5 corresponding source][gemmi-source], licensed under MPL-2.0 or
  LGPL-3.0-or-later; BioIR distributes it under the MPL-2.0 option

[gemmi-source]: https://github.com/project-gemmi/gemmi/tree/v0.6.5
[cuda-badge]:
https://img.shields.io/badge/CUDA-13.2-76B900.svg?style=flat&logo=nvidia&logoColor=white
[cuda-downloads]: https://developer.nvidia.com/cuda-downloads
[docs-badge]:
  https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat
[docs-site]: https://docs.nvidia.com/bionemo/inference-runtime/
[license]: https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/LICENSE
[license-badge]:
  https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat
[pypi]: https://pypi.org/project/bionemo-ir/
[pypi-badge]: https://img.shields.io/pypi/v/bionemo-ir.svg?style=flat&label=PyPI
[pytorch]: https://pytorch.org/
[torch-badge]:
https://img.shields.io/badge/PyTorch-%3E%3D2.11-EE4C2C.svg?style=flat&logo=pytorch&logoColor=white
[third-party-licenses]: https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/LICENSES
[third-party-notices]: https://github.com/NVIDIA-BioNeMo/BioNeMo-Inference-Runtime/blob/main/THIRD_PARTY_NOTICES.md
