Publish AMARO2 model card; checkpoints on the way

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/social-preview-fig-amaro2.webp filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,148 @@
+---
+datasets:
+- compsciencelab/mdCATH
+tags:
+- neural-network-potential
+- coarse-grained
+- molecular-dynamics
+- computational-biophysics
+- force-field
+- tensornet
+- arxiv:2610.37606
+---
+# AMARO v2.0
+
+![AMARO protein–ligand illustration with molecular graph nodes and feature vectors](assets/social-preview-fig-amaro2.webp)
+
+> **Checkpoints on the way — the weights are still packing their bags.** 🧳
+> The paper and code are ready to explore; the three checkpoint files will land here soon.
+
+This repository, [compsciencelab/AMARO2](https://huggingface.co/compsciencelab/AMARO2),
+will host all three AMARO v2 neural network potential checkpoints. Once available,
+use `amaro_v2.ckpt` for the final model. The original AMARO v1 release is hosted
+separately at [compsciencelab/AMARO](https://huggingface.co/compsciencelab/AMARO).
+
+AMARO v2 is a coarse-grained potential that retains heavy atoms and treats
+solvent implicitly. Hydrogen-aware bead types and total-charge conditioning
+provide a shared representation for proteins, drug-like molecules, and their
+complexes. The model and training procedure are described in the preprint
+[*A unified coarse-grained neural network potential for the dynamics of
+biomolecular complexes*](https://arxiv.org/pdf/2610.37606v1)
+by Antonio Mirarchi, Stephen E. Farr, Adria Perez,
+and Gianni De Fabritiis.
+
+**Code and installation:** [compsciencelab/amaro](https://github.com/compsciencelab/amaro).
+See the [system preparation guide](https://github.com/compsciencelab/amaro/tree/main/system-prepare)
+and [OpenMM simulation guide](https://github.com/compsciencelab/amaro/tree/main/openmm-pythonforce)
+for preparing inputs and running the model.
+
+## Planned checkpoint release
+
+The checkpoint files and `v2.0` release tag are not available yet.
+
+| Revision | Checkpoints | Representation |
+| --- | --- | --- |
+| `v2.0` | `amaro_v2_sm.ckpt`, `amaro_v2_p.ckpt`, `amaro_v2.ckpt` | Extended no-hydrogen (NOH) solute mapping |
+
+Once the checkpoints are published, use a release tag or full commit SHA for
+reproducible downloads. `main` follows the latest model card and can change
+between releases.
+
+## AMARO v2 training stages
+
+The three planned files are checkpoints from successive stages of the same training
+sequence. Each stage continues training from the preceding stage:
+
+| Stage | Checkpoint | Training data used at this stage | Role |
+| --- | --- | --- | --- |
+| 1: small molecules | `amaro_v2_sm.ckpt` | In-house AceFF small-molecule dataset with quantum-mechanical force labels | AMARO v2.0 (SM) in the preprint |
+| 2: proteins | `amaro_v2_p.ckpt` | Protein conformations from mdCATH, with molecular-mechanics force labels | Intermediate checkpoint after protein training |
+| 3: protein–ligand complexes | `amaro_v2.ckpt` | Acellera HoloSet protein–ligand conformations, with molecular-mechanics force labels | Final AMARO v2.0 model in the preprint |
+
+Use `amaro_v2.ckpt` to reproduce the final model evaluated for biomolecular
+complex dynamics. Use `amaro_v2_sm.ckpt` for the preprint's small-molecule-stage
+comparisons, and `amaro_v2_p.ckpt` for comparisons with the intermediate protein
+stage. The final model does not uniformly improve every property: the preprint
+reports lower small-molecule force errors and closer local-geometry distributions
+for the SM checkpoint, while the final model is more robust at the tested MD
+time steps. No separate validation claim is made here for the protein checkpoint.
+
+### Inputs and outputs
+
+AMARO v2 uses NOH species IDs, which encode retained elements and, where
+applicable, the number of hydrogens mapped to each heavy atom. The preprint
+describes 26 solute bead types across 18 elements: the original 12 protein types
+plus B, F, Si, P, Cl, Br, I, Na, K, Ca, Mg, Co, Cu, and Zn.
+Solvent and counterions are omitted from the training representation.
+
+Use the exact species IDs and bead ordering from the v2 preparation utilities.
+Do not replace species IDs with ordinary atomic numbers. The original v1
+12-type mapping does not cover the full v2 solute representation. For proteins
+and complexes, the preprint assigns protonation states and total charge at
+pH 7.45; the supplied charge must match the prepared system.
+
+The inference interface takes species IDs, Cartesian positions, and molecular
+charge, with optional batch assignments and periodic box vectors where supported
+by the runner. The model predicts an effective potential; forces are its negative
+position gradient. Use the AMARO v2 TorchMD-Net source and system preparation
+utilities from the accompanying code release. The dataset classes used during
+training are not required for inference.
+
+Use positions in angstroms, effective potential values in kcal/mol, and forces
+in kcal/mol/angstrom, consistent with the preprint's training objective and cutoff
+and the OpenMM PythonForce runner. Force-only training does not calibrate an
+absolute energy reference. The Scalar output head does not use Coulomb cutoff
+or reaction-field options.
+
+## Download (coming soon)
+
+The commands below will work after the checkpoints and `v2.0` tag are published.
+Install the Hub client with `python -m pip install huggingface_hub`, then download
+one checkpoint into the code repository's `ckpts/` directory:
+
+```python
+from huggingface_hub import hf_hub_download
+
+checkpoint = hf_hub_download(
+    repo_id="compsciencelab/AMARO2",
+    filename="amaro_v2.ckpt",
+    revision="v2.0",
+    local_dir="ckpts",
+)
+```
+
+Select another v2 variant by changing `filename`. For now, `SHA256SUMS` covers
+this model card and its figure. The checkpoint release will also include
+checksums for the three checkpoint files at the same revision.
+
+To download all three training stages:
+
+```bash
+hf download compsciencelab/AMARO2 \
+  amaro_v2_sm.ckpt amaro_v2_p.ckpt amaro_v2.ckpt \
+  --revision v2.0 --local-dir ckpts
+```
+
+## License
+
+AMARO v2 checkpoint licensing is pending author confirmation. The preprint
+does not specify a checkpoint license. Licensing of the original v1 release
+does not establish licensing for these v2 checkpoints.
+
+## Citation
+
+For AMARO v2, cite the
+[preprint (arXiv:2610.37606v1)](https://arxiv.org/pdf/2610.37606v1):
+
+```bibtex
+@unpublished{mirarchi2026amarov2,
+  title = {A unified coarse-grained neural network potential for the dynamics of biomolecular complexes},
+  author = {Mirarchi, Antonio and Farr, Stephen E. and Perez, Adria and De Fabritiis, Gianni},
+  year = {2026},
+  eprint = {2610.37606},
+  archivePrefix = {arXiv},
+  primaryClass = {q-bio.BM},
+  url = {https://arxiv.org/pdf/2610.37606v1},
+  note = {Version 1}
+}
+```

SHA256SUMS

@@ -0,0 +1,2 @@
+cffa64c268873c1994abfa5c9609a6e3a7d3ad5977fe266a4255da03183bd754  README.md
+1851f74f78f57a5e644036278c9f75e8509238edabb53a5e280c9f0e8c70f7a5  assets/social-preview-fig-amaro2.webp