AMARO2 / README.md

Publish AMARO2 model card; checkpoints on the way

4d15c6b verified 1 day ago

5.38 kB

---
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)


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) biomelecular systems mapping |


## 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 |

### 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`. 

To download all three ckpts 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 to define.

## 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}
}
```

	---
	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)


	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) biomelecular systems mapping \|


	## 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 \|

	### 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`.

	To download all three ckpts 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 to define.

	## 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}
	}
	```