Metadata-Version: 2.4
Name: tensorpotential
Version: 0.6.1
Summary: Graph Atomic Cluster Expansion (GRACE)
Author-email: Anton Bochkarev <anton.bochkarev@rub.de>, Yury Lysogorskiy <yury.lysogorskiy@rub.de>
License: Academic Software License (ASL)
Project-URL: Homepage, https://github.com/ICAMS/grace-tensorpotential
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: tensorflow<=2.20; sys_platform == "win32" or sys_platform == "darwin"
Requires-Dist: tensorflow[and-cuda]<=2.20; sys_platform == "linux"
Requires-Dist: tf_keras
Requires-Dist: scipy
Requires-Dist: matscipy
Requires-Dist: numpy<3.0.0
Requires-Dist: sympy
Requires-Dist: pandas<3.0.0
Requires-Dist: ase
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: tqdm
Requires-Dist: requests
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: scikit-learn>=1.1
Dynamic: license-file

## What's new


### 03 September 2026: [0.6.1 Release](https://github.com/ICAMS/grace-tensorpotential/releases/tag/0.6.1)

- **Foundation models re-exported.** The distributed models were rebuilt to fix a NaN in `virial_sigma` (the uncertainty contribution to the virial). Cached models now record where they were downloaded from, and the new `grace_models update` re-downloads only the copies that are out of date.
- **Tunable uncertainty threshold.** `grace_uq build --threshold-percentile Q` puts `gamma = 1` at the Q-th percentile of the training distribution instead of the default robust outlier fence — for training sets where a large fraction of atoms reads `gamma > 1`. The artifact records which calibration was used, and `grace_uq info` reports it.
- **Bulk prediction.** A new `predict_structures` helper evaluates a whole list of structures with a single calculator instance; `grace_predict` and `grace_uq predict` now both use it.

### 07 July 2026: [0.6.0 Release](https://github.com/ICAMS/grace-tensorpotential/releases/tag/0.6.0)

- **Uncertainty estimates.** Models can now report a per-atom uncertainty score (gamma) that flags when a prediction is an extrapolation — useful for spotting unreliable regions and for active learning. Comes with a new `grace_uq` command line tool.
- **LAMMPS Kokkos support.** You can now export GRACE models for the fast Kokkos pair styles in LAMMPS. The uncertainty score can be carried along, so it's available during LAMMPS runs too.
- **Foundation models on HuggingFace** ([AMS-ICAMS-RUB/grace-foundation-models](https://huggingface.co/AMS-ICAMS-RUB/grace-foundation-models)). The released models now include uncertainty support out of the box,
-  **GRACE-3L-OMAT/OAM**. There are new, larger **3-layer models** (`GRACE-3L-OMAT-large` and `GRACE-3L-OMAT-large-ft-AM`).
- **Faster and lighter by default.** Foundation models now use fp32 precision by default, which roughly halves memory use and about doubles speed. (fp64 versions are still available under the `-fp64` name.) 
- **Better tooling.** A new `grace_dashboard` shows training curves and metrics in the browser; the `grace_models` command was reworked to list, inspect, and download models (including Kokkos weights); and training can now save and resume in the middle of an epoch.

# Important Note  

If a model was fitted with `gracemaker` version < 0.5.1, it will not be compatible with newer versions due to a format change.  
You can convert it to the new format using the following command:  

```bash
grace_utils -p seed/1/model.yaml -c seed/1/checkpoints/checkpoint.best_test_loss.index update_model
```  

This will generate new files with the "-converted" suffix, which you can replace the old files (`model.yaml` and checkpoints) with.

# GRACE - GRaph Atomic Cluster Expansion

Project GRACEmaker is a heavily modified and in large parts rewritten version of the PACEmaker software geared towards support for multi-component materials and graph architectures.

# Documentation

Please see [documentation](https://gracemaker.readthedocs.io/) for installation instructions and examples. 

# Tutorial

You can find tutorial materials [here](https://gracemaker.readthedocs.io/en/latest/gracemaker/tutorials/#tutorial-materials)

Also in a video [format](https://www.youtube.com/watch?v=rndnkiu9LGE)

# Support

Also, you may join ACE support Zulip channel for additional resources:
https://acesupport.zulipchat.com/join/xtwxu2grjbtg64m3vnhypi6p/

# Reference
Please see 
* [Y.Lysogorskiy, A. Bochkarev, R.Drautz, Graph atomic cluster expansion for foundational machine learning interatomic potentials. npj Computational Materials 12(1), 114 (2026)](https://www.nature.com/articles/s41524-026-01979-1)

```bibtex
@article{lysogorskiy2026graph,
  title={Graph atomic cluster expansion for foundational machine learning interatomic potentials},
  author={Lysogorskiy, Yury and Bochkarev, Anton and Drautz, Ralf},
  journal={npj Computational Materials},
  volume={12},
  number={1},
  pages={114},
  year={2026},
  doi={10.1038/s41524-026-01979-1},
  url={https://www.nature.com/articles/s41524-026-01979-1}
}
```

* [Anton Bochkarev, Yury Lysogorskiy, and Ralf Drautz Graph Atomic Cluster Expansion for Semilocal Interactions beyond Equivariant Message Passing. Phys. Rev. X 14, 021036 (2024)](https://journals.aps.org/prx/abstract/10.1103/PhysRevX.14.021036)

```bibtex
@article{PhysRevX.14.021036,
  title = {Graph Atomic Cluster Expansion for Semilocal Interactions beyond Equivariant Message Passing},
  author = {Bochkarev, Anton and Lysogorskiy, Yury and Drautz, Ralf},
  journal = {Phys. Rev. X},
  volume = {14},
  issue = {2},
  pages = {021036},
  numpages = {28},
  year = {2024},
  month = {Jun},
  publisher = {American Physical Society},
  doi = {10.1103/PhysRevX.14.021036},
  url = {https://link.aps.org/doi/10.1103/PhysRevX.14.021036}
}
```
