Skip to main content

ace-jax

PyPI Docs Tests License: MIT

Build, fit and evaluate Atomic Cluster Expansion (ACE) interatomic potentials in Python with JAX, on CPU or GPU. One pip install gives all of these functions.

Documentation: https://acesuit.github.io/ace-jax/. It contains the installation, a quickstart, tutorials, how-to guides, and the CLI and API reference.

What it does

  • Build a basis and fit it with one command. aj fit --order 3 --max-degree 10 --train train.xyz --out fit builds the symmetry-adapted ACE basis and fits it. The fit.yaml file that it writes runs the fit again.
  • Bayesian fits. Linear ACE uses Bayesian linear regression. The fit selects the energy, force and virial noise levels and the prior scale by maximising the evidence, so you do not set weights by hand.
    • An experimental hybrid ACE + Gaussian-process model (--m-per-species > 0) adds a calibrated set of uncertainty approximations (MAP, Laplace, Pathfinder, VI, NUTS). Most fits use the linear model, the default.
    • The linear model has POPS and ARD uncertainties.
    • ARD gives a conformally calibrated per-atom force uncertainty (forces_std, forces_q, a 3x3 forces_cov). aj calibrate recalibrates it on new labelled cells.
    • The fit can also learn the radial basis (--learn-radial).
  • Fast evaluation. ACECalculator and GPCalculator are ASE calculators, fast enough for molecular dynamics. GP and ARD models also predict energy_std and forces_std. export_lammps deploys a model to LAMMPS with lammps-jax. On CPUs, linear ACE runs in LAMMPS as a C++ kernel (aj export --platform cpu).
  • PACE potentials. ace-jax loads, evaluates and writes pacemaker .yace files.
  • Data in, data out. Training data is extended XYZ or a list of ase.Atoms. ace-jax converts stress labels to virials. aj eval writes predictions as extended XYZ, with an RMSE table for each configuration type.

Install

pip install ace-jax

Extras: "ace-jax[cuda]" (CUDA 12 JAX), "ace-jax[cuda13]" (CUDA 13 JAX and nvcc for the GPU kernel; NVIDIA driver 580 or later), "ace-jax[gp]" (the Pathfinder rung), "ace-jax[native]" (C++ code on CPUs: a neighbour list and the kernel), "ace-jax[lammps]" (LAMMPS export with lammps-jax) and "ace-jax[jaxmd]" (MD with JAX-MD).

To build a new basis, ace-jax needs the ace-jax-coupling wheel. This core dependency is available for Linux x86_64 and aarch64, macOS arm64 and Windows x64. On other platforms, fit and evaluate from an existing basis file. See Installation.

Quickstart

Fit a linear ACE model to labelled data, check it on a test set, and evaluate it:

aj fit --order 3 --max-degree 10 --train train.xyz --test test.xyz \
    --e0 lsq --opt lbfgs --out fit
aj eval --model fit/model.npz --data test.xyz --out predictions.xyz

Use the fitted model from Python:

import jax
jax.config.update("jax_enable_x64", True)

from ase.build import bulk
from ace_jax import ACECalculator

atoms = bulk("Si", "diamond", a=5.43, cubic=True)
atoms.calc = ACECalculator("fit/model.npz")
print(atoms.get_potential_energy(), atoms.get_forces())

The Quickstart runs this on a small silicon dataset. The tutorials are notebooks that run on a laptop CPU. Some of them come from the MLIP School 2026. For coding agents, skills/ace-jax/SKILL.md is a compact usage guide.

Performance and validation

Fits agree with the ACEfit design matrix and least-squares solution to 1e-8. PACE evaluation agrees with the ML-PACE C++ code and python-ace. CI checks both. The throughput benchmarks against LAMMPS ML-PACE are in docs/dev/benchmarks.md.

Citing

If you use ace-jax in published work, cite these papers:

Cite these papers also, if you use the related functions:

CITATION.cff has the full references. Licence and citation also lists the software and models that ace-jax uses.

Contributing

See CONTRIBUTING.md for the development setup, tests and the reference-parity jobs. See the changelog for releases. ace-jax has the MIT licence and is part of ACEsuit.

Metadata

Release files for ace-jax 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ace-jax 0.6.0
File Size Uploaded Provenance Actions
ace_jax-0.6.0.tar.gz 433.9 kB With provenance Details for ace_jax-0.6.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for ace-jax 0.6.0
File Actions
ace_jax-0.6.0-py3-none-manylinux_2_28_x86_64.whl Python 3 none Linux glibc 2.28+ x86-64 Details for ace_jax-0.6.0-py3-none-manylinux_2_28_x86_64.whl
ace_jax-0.6.0-py3-none-manylinux_2_28_aarch64.whl Python 3 none Linux glibc 2.28+ ARM64 Details for ace_jax-0.6.0-py3-none-manylinux_2_28_aarch64.whl
ace_jax-0.6.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for ace_jax-0.6.0-py3-none-macosx_11_0_arm64.whl
ace_jax-0.6.0-py3-none-any.whl Python 3 none any Details for ace_jax-0.6.0-py3-none-any.whl

Total release size: 4.4 MB

Release files / ace_jax-0.6.0.tar.gz

Download URL ace_jax-0.6.0.tar.gz
Size 433.9 kB
Tags Source
SHA-256 checksum
How to use checksums
095d7bb1ce609b822dcf67a9a50cee38fcc403f5e6a8ed033f306c87f68cd314
BLAKE2b-256 checksum
How to use checksums
8c864102d4b2eb3b78170ae45ffc6ee4e870ef94ca75702c00b8669350eebdb9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / ace_jax-0.6.0-py3-none-manylinux_2_28_x86_64.whl

Download URL ace_jax-0.6.0-py3-none-manylinux_2_28_x86_64.whl
Size 1.8 MB
Tags Linux glibc 2.28+ x86-64 Python 3
SHA-256 checksum
How to use checksums
7e57fc8c3baaed4023b80cedccd196e1014a455f3ee5deb5ec1bfd21c3b046fb
BLAKE2b-256 checksum
How to use checksums
f5005db3d39bd33d1bcf9746e516b14c8e50b263258c3754bdb7aa0dff48c345
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / ace_jax-0.6.0-py3-none-manylinux_2_28_aarch64.whl

Download URL ace_jax-0.6.0-py3-none-manylinux_2_28_aarch64.whl
Size 1.1 MB
Tags Linux glibc 2.28+ ARM64 Python 3
SHA-256 checksum
How to use checksums
b1f938840d9ccb37f7927eb05bf4af137fb24f95e8a5dad32603de7a2adc999a
BLAKE2b-256 checksum
How to use checksums
14ecadf16e8c7837e1047333de53b9d15e5e641e0cf4a922727393bf3edae756
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / ace_jax-0.6.0-py3-none-macosx_11_0_arm64.whl

Download URL ace_jax-0.6.0-py3-none-macosx_11_0_arm64.whl
Size 535.3 kB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
2f3d7221fa4f5e34c1915982c2c47ca22b421fa95fe4d20997e84941a8a1b1f4
BLAKE2b-256 checksum
How to use checksums
1e76fe7eb1ec7bfa73d26a73b54c302f9f9b6bcaea9ed3daa608b1ce8a212949
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / ace_jax-0.6.0-py3-none-any.whl

Download URL ace_jax-0.6.0-py3-none-any.whl
Size 483.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1e5a33a53b0a5f3363764378bf5c0709d858effb759f2d5890623f4c04ac6f2e
BLAKE2b-256 checksum
How to use checksums
1956d99e0d38a42fe62129c6966016765a3cd05ad5fd0872f0bdd7954be40fae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for ace-jax 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 5 files in this release have been uploaded with provenance metadata.

Select from 5 files

Attestation for ace_jax-0.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page