add model card: Academic Software License (ASL) + repo/usage docs

README.md

@@ -0,0 +1,58 @@
+---
+license: other
+license_name: academic-software-license
+license_link: https://github.com/ICAMS/grace-tensorpotential/blob/master/LICENSE.md
+library_name: tensorpotential
+tags:
+  - grace
+  - interatomic-potential
+  - molecular-dynamics
+  - machine-learning-potential
+  - materials-science
+---
+
+# GRACE foundation models
+
+This repository distributes **GRACE** (Graph Atomic Cluster Expansion) machine-learning
+interatomic potentials — foundation models fitted with
+[GRACEmaker / tensorpotential](https://github.com/ICAMS/grace-tensorpotential).
+
+## License
+
+**All GRACE models distributed in this repository are released under the Academic Software
+License (ASL).** By downloading or using any model from this repository you agree to the terms
+of the ASL: <https://github.com/ICAMS/grace-tensorpotential/blob/master/LICENSE.md>
+
+## Contents
+
+Each model is provided as two `.tar.gz` archives:
+
+- `models/<model>-model.tar.gz` — the deployable TensorFlow `SavedModel` directory
+  (used by the ASE `TPCalculator`). UQ-enabled models embed an uncertainty head, and many
+  archives also bundle `kokkos.npz` for LAMMPS-Kokkos deployment.
+- `checkpoints/<model>-checkpoint.tar.gz` — the training checkpoint
+  (`model.yaml`, `checkpoint.index`, `checkpoint.data-*`, and `gmm_artifacts.npz` for UQ models).
+
+## Usage
+
+These models are normally fetched automatically by the `tensorpotential` / GRACEmaker
+tooling (`grace_models`, `TPCalculator`, foundation-model presets). They can also be
+downloaded directly, e.g.:
+
+```python
+from huggingface_hub import hf_hub_download
+path = hf_hub_download(
+    repo_id="AMS-ICAMS-RUB/grace-foundation-models",
+    filename="models/GRACE-2L-OMAT-large-base-model.tar.gz",
+    revision="kk",  # immutable tag; "main" is the moving tip
+)
+```
+
+## Versioning
+
+Revisions are pinned via immutable git tags so downloads are reproducible:
+
+- **`uq-v1`** — the initial set of UQ-augmented OMAT foundation models.
+- **`kk`** — model archives that additionally bundle the LAMMPS-Kokkos export (`kokkos.npz`).
+
+`main` always points at the latest revision.