Update README.md
Browse files
README.md
CHANGED
|
@@ -1,3 +1,91 @@
|
|
| 1 |
-
---
|
| 2 |
-
license:
|
| 3 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
license: cc-by-nc-4.0
|
| 3 |
+
tags:
|
| 4 |
+
- molecular-dynamics
|
| 5 |
+
- biomolecular-trajectories
|
| 6 |
+
- diffusion
|
| 7 |
+
- protein
|
| 8 |
+
- protein-ligand
|
| 9 |
+
- alphafold3
|
| 10 |
+
library_name: protenix
|
| 11 |
+
---
|
| 12 |
+
|
| 13 |
+
# BioKinema: Physically Grounded Generative Modeling of All-Atom Biomolecular Dynamics
|
| 14 |
+
|
| 15 |
+
[](https://www.biorxiv.org/content/10.64898/2026.02.15.705956v1)
|
| 16 |
+
[](https://github.com/IDEA-XL/BioKinema/blob/main/LICENSE)
|
| 17 |
+
[](https://github.com/IDEA-XL/BioKinema/blob/main/DATA_LICENSE)
|
| 18 |
+
[](https://github.com/IDEA-XL/BioKinema)
|
| 19 |
+
|
| 20 |
+
## Introduction
|
| 21 |
+
|
| 22 |
+
**BioKinema** is a physically grounded generative model that predicts continuous-time, all-atom biomolecular trajectories at a fraction of the cost of traditional molecular dynamics (MD) simulations. It is built on top of [Protenix](https://github.com/bytedance/Protenix) (ByteDance's AlphaFold 3 reproduction) and extends it with a temporal-attention mechanism derived from Langevin dynamics, so a single model can roll out MD-like trajectories at arbitrary, possibly non-uniform frame intervals.
|
| 23 |
+
|
| 24 |
+
The temporal-attention bias follows a stretched-exponential decay `B_ij = -λ |t_i - t_j|^β`, where `λ` is a per-head learnable decay (ALiBi-initialised) and `β` is a fixed time-scaling exponent selected per model variant.
|
| 25 |
+
|
| 26 |
+
> This HuggingFace repository hosts the released **weights** and processed **data**. For installation, inference, training, the data pipeline, and the manuscript benchmark code, see the [BioKinema GitHub repository](https://github.com/IDEA-XL/BioKinema).
|
| 27 |
+
|
| 28 |
+
## Repository Contents
|
| 29 |
+
|
| 30 |
+
| File | Description | Size |
|
| 31 |
+
|------|-------------|------|
|
| 32 |
+
| `BioKinema_atlas+misato+mdposit_sqrt.pt` | **`sqrt`** checkpoint (EMA). For protein–ligand complexes and **short-time** MD. Trained on Atlas + MISATO + MDposit with `β = 0.5`. | ~3.9 GB |
|
| 33 |
+
| `BioKinema_CATH+octapeptide_beta0.25.pt` | **`beta=0.25`** checkpoint (EMA). For **long-time, single-chain** protein MD. Trained on MSR (CATH / MegaSim / octapeptides) with `β = 0.25`; adds a TICA-dynamics loss. | ~3.9 GB |
|
| 34 |
+
| `biokinema_codec_bundle.tar` | Processed MISATO / MDposit / unbinding data in a lossless compressed codec (one template bioassembly per trajectory + a stacked-coordinate array). Used by `sqrt` training. | ~41 GB |
|
| 35 |
+
|
| 36 |
+
### Which Checkpoint to Use
|
| 37 |
+
|
| 38 |
+
- **Complexes / protein–ligand, or short MD** → `BioKinema_atlas+misato+mdposit_sqrt.pt` (run with `β = 0.5`).
|
| 39 |
+
- **Long single-chain protein MD / kinetics** → `BioKinema_CATH+octapeptide_beta0.25.pt` (run with `β = 0.25`).
|
| 40 |
+
|
| 41 |
+
The exponent `β` **must match the checkpoint** at inference time (pass it via `--beta`).
|
| 42 |
+
|
| 43 |
+
## Usage
|
| 44 |
+
|
| 45 |
+
Clone the [BioKinema repository](https://github.com/IDEA-XL/BioKinema), install the environment, then run inference:
|
| 46 |
+
|
| 47 |
+
```bash
|
| 48 |
+
bash inference.sh \
|
| 49 |
+
--checkpoint_path ./checkpoints/BioKinema_atlas+misato+mdposit_sqrt.pt \
|
| 50 |
+
--dump_dir ./output \
|
| 51 |
+
--input_file ./experiments/atlas_benchmark/init_frames/7lp1_A_R1_0.cif \
|
| 52 |
+
--beta 0.5
|
| 53 |
+
```
|
| 54 |
+
|
| 55 |
+
DDP checkpoints (with a `module.` prefix) are handled automatically by the inference runner.
|
| 56 |
+
|
| 57 |
+
### Codec Bundle
|
| 58 |
+
|
| 59 |
+
```bash
|
| 60 |
+
tar -xf biokinema_codec_bundle.tar -C $BIOKINEMA_UNBINDING_ROOT
|
| 61 |
+
# -> $BIOKINEMA_UNBINDING_ROOT/{misato_codec,mdposit_codec,unbinding_codec}
|
| 62 |
+
```
|
| 63 |
+
|
| 64 |
+
Point each dataset's `bioassembly_dict_dir` at the corresponding `*_codec/` directory; the data loader auto-detects and decompresses on the fly.
|
| 65 |
+
|
| 66 |
+
## Training Data
|
| 67 |
+
|
| 68 |
+
- **Atlas** — public ATLAS MD database (preprocessing scripts shipped in the code repository).
|
| 69 |
+
- **MSR (CATH / Octapeptides / MegaSim)** — Zenodo: `10.5281/zenodo.15629740`, `10.5281/zenodo.15641199`, `10.5281/zenodo.15641184`.
|
| 70 |
+
- **MISATO / MDposit / unbinding** — released here as the compressed codec bundle above.
|
| 71 |
+
|
| 72 |
+
## Citation
|
| 73 |
+
|
| 74 |
+
```bibtex
|
| 75 |
+
@article{feng2026physically,
|
| 76 |
+
title={Physically Grounded Generative Modeling of All-Atom Biomolecular Dynamics},
|
| 77 |
+
author={Feng, Bin and Zhang, Jiying and Zhang, Xinni and Zhang, Ming and Barth, Patrick and Liu, Zijing and Li, Yu},
|
| 78 |
+
journal={bioRxiv},
|
| 79 |
+
pages={2026--02},
|
| 80 |
+
year={2026},
|
| 81 |
+
publisher={Cold Spring Harbor Laboratory}
|
| 82 |
+
}
|
| 83 |
+
```
|
| 84 |
+
|
| 85 |
+
## Acknowledgements
|
| 86 |
+
|
| 87 |
+
This project was built based on [Protenix](https://github.com/bytedance/Protenix), an open-source biomolecular structure prediction framework developed by ByteDance.
|
| 88 |
+
|
| 89 |
+
## Contact
|
| 90 |
+
|
| 91 |
+
For questions or collaborations, please open an issue or contact us at [fengbin@idea.edu.cn](mailto:fengbin@idea.edu.cn).
|