Repository navigation
Releases
ace-jax 0.7.2
Highlights. The C++ and CUDA kernels for linear ACE are faster for models of correlation order 4. For
the silicon model o4d20, LAMMPS is 3 times faster on an A100 (0.75 to 0.25 µs/atom-step in float64) and on
128 CPU cores (1.53 to 0.49). On the A100, this model is now the lowest-cost model that reaches the accuracy
target of the silicon benchmark. aj export --format symmetrix writes a model for the Symmetrix pair style.
Upgrading from 0.7.1. Saved models and the output files are unchanged. No setting is necessary to get
the speed-up in ACECalculator, BatchCalculator and JAX-MD. Export a LAMMPS bundle again to get the
speed-up in LAMMPS. Energies and forces of the kernels agree with 0.7.1 to roundoff, with one exception:
on a GPU, a model with analytic radials now uses those radials and not a table, so its forces change by
the error of the table (approximately 1e-8 of the largest force). Set ACEJAX_FFI_RADIAL=table to get the
table, and ACEJAX_FFI_FORM=dag to get the product basis of 0.7.1. The CUDA kernel compiles again on first
use.
Changed
- Faster product basis in the C++ and CUDA kernels (#182). For correlation order 4, the kernels now
calculate the product basis from coupled pairs of one-particle functions, and no longer from one node for
each product. The silicon model o4d20 has 68,335 nodes in the old form and 1,879 pair values in the new
form. The kernels select the form by operation count: the new form from o4d12 on the silicon ladder,
and the old form for order 3 and for orders above 4. LAMMPS on 128 cores of an EPYC 7742 (4,096 Si
atoms): o4d20 goes from 1.53 to 0.49 µs/atom-step in float64, and from 1.09 to 0.35 in mixed precision.
calc.ffiand the bundle'sace_jax.ffirecord the form (form) and the radial (radial). - The CUDA kernel uses analytic radials (#182). For a model with a polynomial radial basis that is not
splined (maximum l of 8), the CUDA kernel calculates the radial functions and the harmonics in registers,
with no radial table. On an A100 with 32,768 Si atoms in LAMMPS, in µs/atom-step, float64 then float32:
o4d20 goes from 0.75 to 0.25 and from 0.45 to 0.15; o4d16 from 0.19 to 0.11 and from 0.13 to 0.07; o3d8
from 0.043 to 0.036 and from 0.043 to 0.028. Models with learned (splined) radials keep the table. The
kernel also does not sort the atoms by species when the model has one species. - The benchmark page and its cost-accuracy figure show the new timings (
docs/user/benchmarks.md).
Added
- Export to Symmetrix (#182).
aj export --format symmetrixand
ace_jax.export.symmetrix.export_symmetrixwrite a linear ACE model as the JSON file that the
symmetrix/acepair style of Symmetrix reads. ace-jax calls the
converter of the installed Symmetrix package and has no copy of the format. The command stops with a
message if the installed Symmetrix has no converter for ace-jax models. See
docs/user/howto/lammps.md.
ace-jax 0.7.1
Highlights. Two corrections to Hamiltonian models. The features of the atoms near a bond are now
smooth at the bond midpoint, which makes the blocks of a perfect crystal obey its symmetry and decreases
the errors. A prior that --prior evidence, loo or press selects can no longer be weaker than no prior.
Upgrading from 0.7.0. A Hamiltonian model file from 0.7.0 loads and gives the same predictions as
before. Fit the model again to get the corrections. Potentials are not affected.
Fixed
- Hamiltonian models: the features of the atoms near a bond are smooth at the bond midpoint. These
features use spherical harmonics about the midpoint of the bond, and a harmonic with l > 0 has no value
at the origin. Thus the features changed abruptly when an atom was near the midpoint, and bonds of a
perfect crystal that are equivalent by symmetry got different blocks (up to 2.5 meV for bulk gold) when
an atom was exactly at the midpoint. The features now userho = sqrt(x^2 + a^2)for an atom atx
from the midpoint: the radial variable isrho - aand the harmonics are regular solid harmonics of
x / rho. The new setting isBondBasis.env_core(a, 1 Å by default). This also decreases the
errors: for bulk gold with the default basis and 4 training structures, the band error decreases from
3.0 meV to 2.1 meV. A model file from 0.7.0 gives the same predictions as before; fit the model again
to get the correction. --prior evidence,looandpresscannot give a weaker prior than--prior none. For a pair of
species with few bonds in the training set, the fit can go through the data exactly, and the prior
that the evidence selected was then many orders of magnitude weaker than the ridge of a fit with no
prior. Coefficients of 1e13 were the result (Ti-Ti blocks of a Ti-doped half-Heusler), with no message.
The fit now adds the ridge to the selected prior.- A fit of a Hamiltonian model on a CPU releases compiled programs also while it assembles the rows of
large structures (see 0.7.0, "Hamiltonian models of several elements on a CPU").
Added
ace_jax.eval.harmonics.regular_solid_harmonicsgives the solid harmonics as polynomials, with exact
values and derivatives at the origin.
ace-jax 0.7.0
Highlights. ace-jax can now fit and use Hamiltonian models: linear ACE models of the Hamiltonian
matrix H and the overlap matrix S of a structure in a basis of atomic orbitals, fitted to DFT matrices in
closed form from a small number of structures. aj ham fit, aj ham predict and aj ham bands are the
commands, and HamiltonianCalculator is the ASE calculator. This part is new, and its commands, options
and model file can change in the next releases. The fitting and uncertainty code is in a new package
structure, with no change of behaviour.
Upgrading from 0.6.0. Saved potentials and the output files are unchanged, and the results of fits are
bit-identical. The dependency ace-jax-coupling is now 0.3.0. Modules that moved in ace_jax.fit still
import under their old names, with a DeprecationWarning, until 0.8. Hamiltonian models need the new
ham extra: pip install "ace-jax[ham]".
Added
- Hamiltonian models (
ace_jax.ham, thehamextra). A model predicts the blocks of H and S between
the orbitals of each atom and of each pair of atoms. The fit is linear least squares, with no training
loop.aj ham fit --data DIR --out model.npzfits a model to structures with blocks, in the DeepH file
layout or as ace-jax cache files.--priorsets a smoothness prior: a number,evidence,looor
press.--validation DIRgives the errors of the fitted model.aj ham predictwrites the H and S blocks of structures in the DeepH layout.aj ham bandsgives the bands on a high-symmetry path and the density of states, as arrays and as a
figure, with the bands of the reference if the structure has blocks.aj eval --model model.npzgives the errors of a Hamiltonian model: the blocks, the bands at a common
energy zero and from the Fermi level of each spectrum, the Fermi level, the band energy and the
density of states (ace_jax.ham.metrics).ace_jax.ham.calculator.HamiltonianCalculatoris an ASE calculator: eigenvalues, Fermi level, H and S
blocks, and the band energy with its forces and stress. The band energy is not a total energy.- Collinear spin is two Hamiltonian channels (
H_up,H_dn). There is no spin-orbit coupling. docs/user/howto/hamiltonians.mdhas the procedure and an example on bulk gold.
ace_jax.operators: equivariant block models of operators in a basis of atomic orbitals, which the
Hamiltonian models use.fit_onsiteandfit_offsitefit them onace_jax.fit.linear;
operators.io.saveandloadwrite and read one self-contained.npzmodel file.- Equivariant couplings.
ace_jax.basis.coupling.couple_equivariantgives the coupling of features
that transform as a vector of angular momentum L (L ≤ 6) of each parity, fromace-jax-coupling0.3.0.
ace_jax.basis.cghas the real Clebsch-Gordan tables. - Leave-one-block-out for linear fits.
ace_jax.fit.linear.loogives the residuals of a Bayesian
linear fit with one block of rows left out, in closed form, for many right-hand sides. - A generic linear fit,
ace_jax.fit.linear. A row generator gives(Phi, Y, w)for each quantity of
a batch, with one or more right-hand sidesY.stats.qr_statisticsandstats.gram_statisticsstream
it into oneFactororGramfor each quantity (on the host with checkpoints and MPI, or on a device).
objective.log_evidence_qr,objective.posterior_qrandlml_host.HostQREvidencegive the evidence
and the posterior.ace_jax.uq.ard.ARDEvidenceandace_jax.uq.jackknife.press_scores_rowstake any
labelled quantities. The energy, force and virial fit uses these functions; its results are bit-identical. ace_jax.eval.featureshas theSiteFeaturesprotocol for equivariant site features, andpooled_a,
which gives the one-particle basis of a linear ACE from a radial and index arrays.
ace_jax.eval.radial.TensorRadialis the tensor radial of a model without the model.ace_jax.uq.force.ForceUQgives the force uncertainty of a posterior for one structure. It takes the
design rows of the model from an object such asace_jax.fit.design.ForceDesign.
ACECalculator(posterior=...)uses it (calc.uq); the results are the same.
Changed
-
ace_jax.fitis split by role, and uncertainty quantification isace_jax.uq. No behaviour changes.
ace_jax.fit.linearandace_jax.uqare generic: they take rows of any quantities and know no model.
ace_jax.fit.{stats, objective, solve, ard, jackknife}keep their names and are the energy, force and
virial fit on top of them. Modules that moved still import under the old name, with a
DeprecationWarning, until 0.8; names with a leading underscore do not.
docs/dev/specs/2026-11-17-package-structure-design.md.Before Now fit.{lml_host, lml_svd, prior_root, block_lbfgs, newton, multistart, varpro, progress}fit.linear.*(prior_root.prior_rootis infit.ard)fit.{conformal, pops, support, clusters}uq.*fit.{kernels, inducing, ladder, predict, feature, density, hostcache, loo, sharding}fit.gp.*fit.radial_learn,fit.radial_model,fit.embeddingfit.radial.learn,fit.radial.model,fit.radial.embeddingfit.rowcheckfit.pipeline.rowcheck -
ace_jax.eval.productholds the A basis and its products as functions of arrays (pool_sparse,
edge_a,product_basis,estimate_a_bytes, ...).ace_jax.eval.edge_modelandace_jax.eval.model
still give these names.compactis inace_jax.eval.dense,cubic_bspline_coefsin
ace_jax.eval.radialandace_ctilde_treeinace_jax.eval.pace_ace; their old modules still give them.
Removed
ace_jax.eval.ACECalculator. Useace_jax.ACECalculator.
Fixed
- Hamiltonian models of several elements on a CPU. A fit or an evaluation of a model with four
elements stopped withLLVM compilation error: Cannot allocate memorywhen memory was free: the
compiled programs of the process reached the limit of the kernel on memory mappings
(vm.max_map_count). ace-jax now releases compiled programs before that limit.
ace-jax 0.6.0
Highlights. The C++ kernel for linear ACE on CPUs needs no compiler on Linux and on macOS (arm64): the
wheels for these platforms now include it compiled. The C++ and CUDA kernels are faster (approximately 2x
for LAMMPS on CPUs, and up to 1.7x in float64 or 2.4x in float32 on an A100), and they have an optional
mixed-precision mode. The documentation says which papers to cite.
Upgrading from 0.5.3. Saved models and the output files are unchanged. On Linux and on macOS (arm64),
ffi=True and ffi="auto" now use the kernel that the wheel includes (x86-64-v3 on x86_64), not a kernel
compiled on your machine with -march=native. In our tests the two have the same speed, to 5%. To compile
the kernel on your machine as before, set ACEJAX_FFI_FLAGS="-O3 -march=native". On a machine with no
compiler, ffi="auto" used the JAX model before, and now uses the kernel.
Added
- Platform wheels with the compiled C++ kernel. The ace-jax wheels for Linux (x86_64 and aarch64) and
for macOS (arm64) now include the compiled CPU kernel, soACECalculator(ffi=True)orffi="auto",
BatchCalculator, JAX-MD and CPU LAMMPS bundles need no C++ compiler there, and there is no compile on
first use. Before,ffi="auto"used the slower JAX model on a machine without a compiler. The x86_64
kernel uses AVX2 (x86-64-v3): within 5% of-march=nativeon a Xeon Silver 4216 and 2% on an EPYC 7742;
CPUs without AVX2 get a baseline build. Other platforms take the pure wheel and compile the kernel on
first use, as before. To compile with your own flags, setACEJAX_FFI_FLAGS(for example
-O3 -march=native);ACEJAX_FFI_PREBUILT=0turns the included kernel off.aj nativereports which
kernel is in use. The CUDA kernel is still compiled on first use.docs/dev/kernel-wheels.md. - Mixed precision for the kernels (
ffi_precision="mixed",aj export --ffi-precision mixed; off by
default). The C++ and CUDA kernels for linear ACE can calculate the product basis in float32 and all
other quantities in float64. For the silicon model o4d20, LAMMPS on 128 cores is 1.4 times faster and an
A100 is 1.4 times faster. Smaller models gain less, and order-3 models gain nothing. Forces differ from
float64 by approximately 0.05 meV/Å for o4d20. The energy has noise of approximately 0.1 meV in 200
atoms, so optimisers with an energy line search can fail: use a force-only optimiser. See
docs/user/howto/precision.md. - Citations.
CITATION.cffand the "Licence and citation" page give the papers to cite: the atomic
cluster expansion and ACEpotentials for all use, and the papers for the calibrated force uncertainty
(--uq ard), POPS, species-embedded bases and PACE.yacemodels when you use them. (#153)
Changed
- Faster C++ and CUDA kernels (#157). The C++ kernel takes four sites and four neighbours at a time in
SIMD lanes. The CUDA kernel's product-basis pass gathers instead of scattering, so it has no atomic adds
and is deterministic. LAMMPS on 128 cores of an EPYC 7742 (4,096 Si atoms) is 2.0 to 2.4 times faster
(o4d20: 3.52 to 1.52 µs/atom-step). On an A100 (32,768 Si atoms), o4d20 goes from 1.23 to 0.75 µs/atom-step
in float64 and from 1.08 to 0.44 in float32; the order-3 models change little. - The
nativeextra's matscipy-neighbours has binary wheels from version 1.1, so installing the extra needs
no compiler on Linux, macOS (arm64) and Windows. The wheels are for CPUs: a neighbour list built on the GPU
needs matscipy-neighbours compiled with CUDA (docs/user/installation.md). (#161)
Fixed
- Fast species-embedded basis build.
aj basis --embeddingandbuild_embedding_modelwith the default
ace1block rule enumerated the full categorical body set for all S elements and then kept only the
z' = 1 channel, a 1/S fraction of the radial indices. The search now enters only those indices. The basis
is unchanged (same bodies, same order). For S = 12, order 4, degree 14 the spec takes 1.7 s instead of
hours; the cost no longer grows with S.
Testing
- The lock takes matscipy-neighbours 1.1.0 (the
nativeextra; its floor stays>=1.0). A test that
compared three evaluations of one structure bitwise now allows 16 ulp: on a GPU the order of a sum can
change between calls. - The
gpuCI job also runstests/test_calc_jit.py, with matscipy-neighbours built with its CUDA backend,
so the neighbour list built on the GPU is tested.
ace-jax 0.5.3
Highlights. Large linear fits are much faster. The training statistics are approximately 6x faster per
batch and can be spread over the nodes of a cluster with MPI. The MAP can use one SVD (shared noise), and on
the CPU each QR evidence step is 8-20x cheaper. A new how-to, docs/user/howto/large-fits.md, shows the
workflow.
Upgrading from 0.5.2. Saved models and the output files are unchanged. A linear fit can give
hyperparameters and coefficients that differ from 0.5.2 at round-off level (approximately 1e-9 relative in
theta on the pipeline goldens): the QR factors are merged and the evidence is evaluated in a different order.
Added
- MAP by one SVD (
aj fit --lml-solver svd). With shared noise, the linear arm's evidence and its
gradient are computed from one SVD of the merged QR factor scaled by the prior, so each MAP evaluation
costs O(L) instead of a QR of the whole system. It is as accurate as the QR form, and the posterior and
the saved model are computed as before. For approximately L = 50,000 this replaces about a day of MAP
evaluations with one decomposition. Jointly fitted reference energies (--e0 lsq) are supported. At the
MAP the QR evidence is evaluated once as a check; if the two disagree, the MAP continues on the QR form.
Independent noises and float32 rows use the QR form, with a warning. (#143) - MPI-sharded training statistics (
aj fit --mpi, the new[mpi]extra: mpi4py). Run undersrunor
mpirunwith one rank per node. Each rank streams every N-th batch into its own QR factors. A binary tree
merges the factors onto rank 0, which runs the rest of the fit. The statistics pass is limited by memory
bandwidth, so it scales with nodes, not with ranks on one node. It works with--checkpoint. (#142) - Two-job large fits (
aj fit --stats-only, needs--checkpoint DIR): stop after the training statistics.
With--mpi, rank 0 also saves the merged factors as one serial checkpoint, so the same command without
--mpiand--stats-only, as a dependent one-node job, runs only the MAP and the N statistics nodes are
released. Seedocs/user/howto/large-fits.md. (#142) aj fit --uq ard --ard-prior fixed(FitConfig.ard_prior = "fixed") runs the calibrated per-atom force
stage on the BLR posterior: the hold-out fits, the transfer fit and the served posterior keep the MAP's
own prior (a_k = -2 log sigma_c for every body order) instead of fitting the ARD scales by evidence. The
served mean is the--uq blrfit's. Needs--ard-solver qr(the default for--uq ard): the BLR prior
can sit below the evidence fit's floor.ard.jsonrecords"prior"and whether the prior is below the
floor. The default,fit, is unchanged. (#145)
Changed
- Faster training statistics (#146). The design rows scatter every centre species in one pass instead of
one masked pass per species (11.5 s to 1.7 s per batch at L = 47,000, the same rows bit for bit), and the
host QR merges use LAPACKtpqrt, which keeps R triangular (approximately 5x faster at L = 8,000). - Faster MAP for large linear fits on the CPU. The QR evidence is now evaluated with its structure on the
host: triangular merges of the per-quantity factors, one triangular inverse, and the gradient and exact
Hessian in the four scales written out, instead of a dense QR of the stacked matrix with autodiff through it.
Same evidence to roundoff; less memory. GPU statistics keep the dense form (objective.QR_EVAL). (#147)
Fixed
- SVD MAP for L > 46,340 (#148). SciPy's LAPACK uses 32-bit indices and refused the full SVD; such fits now
use NumPy's 64-bit-index LAPACK (divide and conquer). An L = 47,448 fit then completed. - MAP refinement stopped short (#146). The Newton refinement now accepts a full Newton step that halves the
projected gradient without raising the objective beyond its round-off, where the line search failed on that
round-off.
ace-jax 0.5.2
Highlights. POPS uncertainty (aj fit --uq pops) is numerically defined on fits that nearly
interpolate their data, and its defaults follow the reference package POPSRegression. Fits can be
resumed after an interruption.
Upgrading from 0.5.1. Saved models and posteriors are unchanged. An aj fit --uq pops run can give
a different, narrower POPS box than in 0.5.1:
- The box is built from the rows at or above the median leverage (
FitConfig.pops_leverage_pct = 50,
POPSRegression'sleverage_percentiledefault). 0.5.1 used every row, and on the silicon
accuracy-cost fits the low-leverage rows made the box unphysical. Setpops_leverage_pct=0in
Python for the 0.5.1 behaviour. - The ridge selection stops at a relative ridge of
1e-10(predict.POPS_MIN_RIDGE). The 0.5.1 grid
went down to1e-14, where the box is set by round-off.
Fixed
- POPS numerics (#141). On the silicon o3d12 fit (condition number 5e16, with sigma_c on its
bound), the Cholesky of the ridge system was not finite. The BLR mean, the test predictions and every
ridge-selection score were then NaN, and the selection silently returned the first grid value.- The POPS mean now falls back, with a warning, to the streamed QR (
solve.posterior_qr). The QR
does not square the condition number. - Ridge selection raises
FloatingPointErrorwhen every score of a quantity is non-finite. POPS_MIN_RIDGE = 1e-10: below it the box is set by the round-off of the eigendecomposition. Four
equivalent evaluations of one box at1e-14gave bulk-energy spreads from 1.6 to 78 meV/atom. A
smaller ridge warns, and the default grid stops at it.- The default leverage cut is 50 % (see Upgrading). With the same rows, mean, ridge and cut,
POPSRegression's own hypercube step agrees with a stable evaluation of the port.
- The POPS mean now falls back, with a warning, to the streamed QR (
Added
- Resumable fits (
aj fit --checkpoint DIR,--checkpoint-every MIN, default 45). The training
statistics pass saves its QR factors to DIR at that interval, and the MAP saves its best
hyperparameters after each evaluation. Run the same command again to resume. A complete statistics pass
is kept, so a fit stopped later does not repeat it. The statistics checkpoint applies on the CPU
backend. It needs 8 L^2 bytes per quantity on disk (approximately 9 GB at L = 20,000).
ace-jax 0.5.1
Highlights. ARD force uncertainty is reliable on fits that nearly
interpolate their data. The evidence is now computed by QR, so the prior
scales no longer stop at a numerical floor, and a fit whose scales all reach
the floor stops with an error.
Upgrading from 0.5.0. Saved models and posteriors are unchanged. An
aj fit --uq ard run can give a different, more accurate posterior than in
0.5.0, because the prior scales are now fitted past the old floor. Use
--ard-solver cholesky --ard-cond-max 1e14 for the 0.5.0 behaviour.
Fixed
- ARD evidence by QR (#137, issue #136). The sequential ARD evidence, its
gradient and Hessian, and the posterior come from a QR factor whose
condition number is the square root of that of the scaled system. The prior
floor is lowered to a condition number of 1e22 forqr(1e14 for
cholesky). On the silicon accuracy-cost fits the 0.5.0 evidence stopped
every prior scale on the floor and gave a less accurate posterior than the
BLR fit; with QR, o3d12's test energy RMSE is 15.8 meV/atom (0.5.0: 22.0),
equal to the BLR fit.- New options:
--ard-solver {auto,qr,cholesky}(auto:qrfor
--uq ard,choleskyfor--uq ard-gp),--ard-cond-max, and
--ard-allow-degenerate. - A fit where every prior scale ends on the floor, with the gradient
pointing below it, is degenerate: the stage warns and stops unless
--ard-allow-degenerateis set.ard.jsonandmetrics.csvrecord
ard_degenerate.
- New options:
- Large MAP fits (#135). The QR statistics are passed to the compiled
evidence, gradient and Hessian-vector product as arguments, not embedded as
constants. This removes a second copy of the statistics (43 GB at 42,324
coefficients) and a lowering error above 2^32 elements.
Changed
- PACE radial functions (#134) are implemented from a specification of
the published equations (docs/dev/pace-radial-spec.md), not from ML-PACE's
source. Public names and model output are unchanged. - Licence notes for the PACE reference tools, and sources cited for
pace_radial(#132). - Shorter test suite and refreshed test durations (#129, #131, #133); macOS
arm64 CI on macos-15 (#138).
ace-jax 0.5.0
Highlights. Linear ACE runs on CUDA GPUs with a CUDA kernel: in LAMMPS,
in the ASE calculator and in batches. In LAMMPS on an A100 it is 2.9 to 8.0
times faster than the compiled JAX program, and linear ACE o4d20 costs 1.23
µs/atom-step. The C++ kernel is now the default for CPU LAMMPS bundles, and
it also runs in the ASE calculator and in JAX-MD. BatchCalculator evaluates
many small structures in a few compiled calls, and batched MD runs with
JAX-MD. Learned radials are approximately 3 times faster.
Upgrading from 0.4.1. Saved models are unchanged.
- A CPU bundle of a linear ACE model now uses the C++ kernel by default.
LAMMPS then needsLAMMPS_JAX_FFI_HANDLERS, whichaj exportprints.
Export with--no-ffi(ffi=False) for the previous bundle, which needs no
variable. aj fit --learn-radialruns 300 steps by default (was 40), with a new gate
score, so the same command gives a different fit. Set--radial-steps 40
for the previous number of steps.- The
fast-neighboursextra is nownative. The old name works until the
next release but one. - For an NVIDIA driver 580 or later, the
cuda13extra installsnvccfor
the CUDA kernel. With thecudaextra, load a CUDA toolkit or module.
Changed
- Learned radials: longer runs and a force-aware gate.
--radial-steps
now defaults to 300 (was 40), and the new--radial-reprofile-every
(default 100; was fixed at 10) sets how often the hyperparameters are fitted
again. The gate score now weights energies and forces as the learning
objective does, so the force errors count. The previous score was a mean
for each quantity, so the energies decided it. The fit log and
radial_info.jsongive the polynomial span that is used. - Learned radials are approximately 3 times faster. The residual pass uses the
model's own energies and forces at the coefficients, not the full design
rows. The hyperparameters are fitted again by L-BFGS, not by 300 Adam steps.
The L-BFGS fit is also better converged. - A
cuda13extra. For an NVIDIA driver 580 or later, it installs
jax[cuda13]and NVIDIA'snvccwheel, which compiles the CUDA kernel. The
cudaextra is unchanged (jax[cuda12]): the kernel then uses thenvccof
a CUDA toolkit or module. - The radial table is sized to an accuracy.
radial_table=True(and the
C++ and CUDA kernels, which turn it on) now uses 4000 intervals or more: enough for
an error of 1e-9 in the radial values. Most models keep 4000 intervals. A
species-embedded SiGe model gets 11585, and its force error goes from
2.7e-7 to 1.4e-8 of the largest force, at the same speed. The search stops
when more intervals give no smaller error in the derivative of the table:
past that point, float64 noise in the sampled radial grows with the number
of intervals. A float sets another tolerance; an int still sets the number
of intervals. fast-neighboursis nownative. Thenativeextra installs the same
packages;fast-neighboursremains as an alias until the next release but one.- The C++ kernel is the default for CPU bundles.
export_lammpsand
aj exporttakeffi="auto": a CPU bundle of a linear ACE model (categorical
or species embedding) uses the kernel when it is float64, lean, has the
matrix layout, lammps-jax is 0.2.1 or later and a C++17 compiler compiles
the kernel. Otherwise the bundle uses the XLA program,aj exportprints the
reason, and the bundle records it asace_jax.ffi_reason. A missing compiler
no longer stops the export.--ffi(ffi=True) requires the kernel and
--no-ffi(ffi=False) turns it off. GPU bundles are unchanged. - Faster GPU compiles for single-species ACE models. The analytic radial
is now a matrix multiply when the model has one species. For batched MD on
an A100, the compile now takes approximately 5 seconds, not 10 minutes.
Multi-species models are unchanged.
Added
-
A CUDA kernel for linear ACE. On a CUDA GPU,
ffi=Trueruns a CUDA
kernel in float64 or float32: inACECalculator,BatchCalculator, and
LAMMPS bundles (export_lammps(ffi=True),aj export --ffi). It supports
categorical models with any number of species and species-embedded models.
On an RTX 4000 Ada with 4096 Si atoms, it is 3.4 to 4.8 times faster than
the XLA program in float64, and 2.7 to 3.4 times faster in float32. In
LAMMPS on an A100 with 32,768 Si atoms, it is 2.9 to 8.0 times faster in
float64 (o3d8 to o4d20) and 2.3 to 5.3 times in float32; linear ACE o4d20
costs 1.23 µs/atom-step, against 2.42 with patched ML-PACE.nvcccompiles
it the first time;aj native --buildcompiles it before use. -
Batched evaluation.
ace_jax.batch.BatchCalculator(model).calculate(structures)
gives the energy, forces and stress of many structures in a small number of
compiled calls: structures of similar size are padded into one batch, and
the neighbour lists of a batch are made in one step. It accepts the
evaluation options ofACECalculatorand agrees with it to roundoff. On a
GPU, 1024 Si cells of 2 or 8 atoms are 35 to 72 times faster than
ACECalculatorone structure per call, 64-atom cells 6 to 11 times. On a
CPU it needs the C++ kernel (ffi=True): 25 to 35 times for 2 and 8
atoms, 3.5 times for 64 (with matscipy-neighbours' batched build; 19 to 52
and 2.4 times without it).aj evaluses it when no posterior or GP model is
given. Guide: "Evaluate many structures". -
Batched MD and relaxation with JAX-MD. JAX-MD's integrators and
optimisers run over a batch of structures withjax.vmap:
BatchCalculator.neighbour_lists(structures, skin)gives the padded batch
and its neighbour lists (any cell size, rebuilt byupdatewhen an atom
moves skin / 2),BatchCalculator.energy_fn()the energy of one structure,
andace_jax.batch.initial_momenta,zero_paddingandtemperaturekeep
the padding atoms out of the dynamics and the temperatures. Withffi=True
the C++ kernel runs underjax.vmap(the batch becomes one threaded kernel
call): on 32 cores, MD of 64 Si cells of 8 or 64 atoms is 37 to 48 times
faster than with the JAX model.BatchNeighbours.update_fn()rebuilds the
lists inside the compiled loop (one batched build, underlax.cond).
Giveinitial_momentathe positions'dtypefor a float32 batch.
On an A100, batches of 64 to 216 atom cells are 18 to 21 and 8.5 to 9 times
faster thanACECalculator; a GPU call holds up to 262144 atoms
(max_batch_atoms), approximately 1 GB in float64 for the Si model. -
The C++ kernel in the JAX-MD adapter.
jaxmd.potential(..., ffi=True)
runs the kernel on a CPU: 10 to 18 times faster MD than the JAX model for
216 to 1728 Si atoms on 32 cores. The adapter and the batched path now share
one energy core, so the batched path also compacts the neighbour slots
(BatchNeighbours.energy_fn), evaluates rows in blocks, and gives NaN, not a
truncated list, when a structure outgrows its neighbour lists. -
The C++ kernel in the ASE calculator.
ACECalculator(..., ffi=True)
calculates energy, forces and stress of a linear ACE model with the C++
kernel on CPUs, on all cores (XLA's thread pool;ffi_threadssets fewer).
On 32 cores it is approximately 17 times faster than the JAX model at 1,700
to 4,100 atoms (linear ACE o4d20). It uses the calculator's neighbour lists
and skin, and the radial table.ffi="auto"uses it when possible and gives
the reason incalc.ffi_reasonwhen not. The default stays the JAX model,
which also gives derivatives with respect to the coefficients and second
derivatives; the kernel gives position derivatives only. -
aj export --print-env BUNDLEfor kernel bundles. It prints the
LAMMPS_JAX_FFI_HANDLERSline on the machine that runs LAMMPS. If the kernel
library is not on that machine, the command compiles it there. -
The
nativeextra andaj native.pip install "ace-jax[native]"
installs the C++ neighbour list (matscipy-neighbours). Its compiler also
builds the C++ kernel.aj nativeshows the compiler, flags, CPU, kernel
cache and neighbour list;aj native --buildcompiles the kernel now (on a
cluster: on a compute node).
Fixed
ACECalculatorno longer fails on a structure with no cell (a cluster with
a zero cell): ASE'sget_volumeraised. The stress needs a non-zero volume.- Skin-list rebuilds on the CPU were slow. Matching each edge to its reverse
(two sorts over every skin edge) took approximately 90% of a rebuild: 93 of
106 ms at 4,096 atoms. The match only helps on a GPU, so the CPU now uses the
scatter force assembly, which is as fast. A rebuild of 4,096 atoms now takes
14 ms with thenativeextra (was 102 ms) and 159 ms without it
(was 249 ms).
ace-jax 0.4.1
Highlights. Linear ACE runs in LAMMPS on CPUs with a C++ kernel, 10 to 23
times faster than the compiled JAX program: aj export --platform cpu --ffi.
The Performance page has an interactive accuracy-cost figure, and the
benchmark adds GRACE. Long MAP fits and large --learn-radial fits on a GPU no
longer stall or run out of memory.
Upgrading from 0.4.0. Saved models and bundles are unchanged.
- The
lammpsextra requires lammps-jax 0.2.1 or later. For the C++ kernel,
build the lammps-jax LAMMPS plugin at 0.2.1 or later as well. - A MAP fit can stop its Newton polish sooner (see Fixed). Its parameters agree
with 0.4.0 to approximately 1e-7.
Added
- A C++ kernel for linear ACE in CPU LAMMPS bundles.
export_lammps(..., platform="cpu", ffi=True)andaj export --platform cpu --ffiput one XLA FFI custom call in the bundle in place of the compiled JAX
program (ace_jax.eval.ffi). Positions and the LAMMPS neighbour list go in;
atom energies and forces come out.- On a 128-core node (Sulis, 4,096 Si atoms, one MPI rank per core) it is 10 to 23
times faster than the XLA bundle; linear ACE o4d20 costs 3.29 µs/atom-step
(ML-PACE: 5.31). - It needs a linear ACE model, float64 and the matrix layout. It tabulates
the radial basis in r: energies agree with the calculator to approximately
1e-12 relative, and forces to 1.5e-8 of the largest force. - The export compiles the kernel on first use with your C++17 compiler
($CXX,c++,g++orclang++; flags-O3 -march=native, or
--ffi-flags/ACEJAX_FFI_FLAGS) and keeps it in a cache
(~/.cache/ace-jax/ffi, orACEJAX_FFI_CACHE). The bundle records it as
ace_jax.ffi, andaj exportprints theLAMMPS_JAX_FFI_HANDLERSvalue
that lets LAMMPS load it. Run LAMMPS withnewton on. jax.gradandjax.vjpwith respect to positions work through the
kernel's energy function.- See "CPU kernel" in Export a model to LAMMPS.
- On a 128-core node (Sulis, 4,096 Si atoms, one MPI rank per core) it is 10 to 23
Changed
- The
lammpsextra requires lammps-jax 0.2.1. Its LAMMPS plugin
registers custom calls for the CPU, which the C++ kernel needs. - Dense rows run in blocks of 4,096 on the GPU (
energy_forces_virial_dense
withoutchunk; 16,384 elsewhere, unchanged). Linear ACE o4d20 with 32,768
atoms on an A100 uses 1.12 GB for the program, against 4.06 GB before. LAMMPS
bundles andace_jax.jaxmdsize their own blocks and are unchanged.
Fixed
- The MAP Newton polish could step for hours. With the gradient floor, it
kept stepping while each step gained less than the evidence's roundoff
(observed: 10 hours at o4d20). It now stops after three such steps in a row
and reportsstalled. The ARD evidence polish is unchanged. --learn-radialran out of GPU memory at large bases. Each radial round
kept the compiled constants of its hyperparameter re-fit (about 0.7 GB at
o4d20), until an A100 ran out. They are now released after each round, at
approximately 11% more time per round.
Benchmarks
- The Performance page has an interactive version of the accuracy-cost figure:
presets, a legend that shows and hides families, and the code of each timing
on hover. - GRACE-1L and GRACE-FS (gracemaker) are in the silicon benchmark. GRACE-1L
reaches the target only at its largest size, at 4 to 27 times the cost of
linear ACE or MACE c16L0. - The figure shows linear ACE with and without the C++ kernel. All figures
come from one CPU and one GPU cost file, built by the reproduce block of
docs/dev/accuracy-cost-results.md. - A GPU memory report (
docs/dev/gpu-memory-results.md): linear ACE o4d20 runs
4.4 million atoms on one A100-40GB.
ace-jax 0.4.0
Highlights. float32 is now a real float32 calculation in LAMMPS bundles
and calculators, and a new page tells you when it is safe. The linear fit can
calculate its design rows in float32 (--row-precision float32). MD runs on
the device with JAX-MD (ace_jax.jaxmd). Larger models use the DAG product
basis automatically. aj fit fits linear ACE by default.
Upgrading from 0.3.0. Saved models are unchanged.
aj fitwithout--m-per-speciesnow fits linear ACE (it was the hybrid
ACE + GP model). Give--m-per-species> 0 for the hybrid model.- A float32 bundle or calculator made with 0.3.0 from a model loaded under
x64 calculated in float64. Export it again for the float32 speed. - Models with 4,000 or more chain-form multiplications per atom use the DAG
product basis. Results agree with 0.3.0 to round-off. Setaa_dag=None
for the 0.3.0 form.
Fixed
- float32 export and calculators calculated in float64. With x64 enabled,
export_lammps(dtype="float32"),aj export --dtype float32and
ACECalculator(dtype=float32)on a model already loaded traced a float64
program. Only the inputs and outputs were float32, so there was no speed-up.
The model is now converted to float32 after the lean form and the splines
are made in float64 (ace_jax.eval.with_dtype). - float32 spline tables lost the precision of their derivatives. Splined
and learned radials and radial tables in float32 had a relative derivative
error of up to 5e-2. The tables are now kept in a local difference form,
made in float64: 8e-7. - The design rows of a fit are calculated at the highest matmul precision.
TF32 on an A100 corrupted float32 force rows.
Changed
- The recursive (DAG) product basis is automatic.
ACECalculatorand
export_lammpsdefault toaa_dag="auto". It uses the DAG for models with
4,000 or more chain-form multiplications per atom, and the chain form for
smaller models. Results below the threshold are unchanged. Larger models run
1.2-2.7x faster on a CPU node and 1.1-1.8x faster on an A100 (linear ACE
o4d20: 2.7x and 1.8x).calc.aa_dagand the bundle'sace_jax.aa_daggive
the form used. Setaa_dag=Nonefor the chain form. aj fitfits linear ACE by default. The default of--m-per-species
is now 0 (it was 500). The hybrid ACE + GP model is experimental. To use
it, give--m-per-species> 0. The GP options (--kernel,--no-bump,
--density,--pca-d,--embedding) without--m-per-species> 0 are
now an error.FitConfigin Python is not changed: setarmexplicitly.
Added
- float32 design rows for the linear fit.
aj fit --row-precision float32(FitConfig.row_precision) calculates the design rows, and on a GPU
the QR merges, in float32. The evidence, the MAP and the posterior stay in
float64. A silicon o4d16 fit took 169 s instead of 265 s on an RTX A4500,
with the RMSE within 1%. The GP arm and--learn-radialrefuse it.
--row-checkis an optional stability check of the result. - The float32 error of a model.
ace_jax.calc.precision.precision_check
compares float32 with float64 on a structure.export_lammps(..., precision_structure=atoms)andaj export --dtype float32 --structure
record it in the bundle and warn above 0.1 meV/atom or a relative force
error of 1e-4. - A new page, "Choose float64 or float32" (
howto/precision), gives the
speed-up by GPU (2.1-4.5x on an RTX A4500, 1.3-1.5x on an A100), the errors,
and which tasks can use float32. Energy line searches fail in float32: use
a force-only optimiser, for example ASEODE12r. - MD with JAX-MD (
ace_jax.jaxmd, the newjaxmdextra).
jaxmd.potentialgives the energy and forces of a model to the
integrators of JAX-MD. The neighbour list, the model and the integrator
then run on the device in one compiled program. The energy is the energy
ofACECalculatorwith the same options.Ksets the slots for each
atom. If an atom has more neighbours thanK, the energy and forces are
NaN, andoverflowtells you. The model runs in blocks of atoms of the
size thatexport_lammpsselects, so the memory is approximately that of a
LAMMPS bundle. See Run MD with JAX-MD. write_yace(model, path, summed=True)writes one A basis for all
neighbour species, as ace-jax evaluates the model. The default writes each
product once for each neighbour species. The summed form has far fewer
products for multi-element models: 849 instead of 15,021 for a
three-element embedded model at order 3. ML-PACE reads it only with the
summed_neighbour_Aaddition. ace-jax does not read summed files.
Testing
- The
pace-parityCI job builds ML-PACE from
jameskermode/lammps-user-pace(ICAMS/lammps-user-pace#31): the
v.2025.12.4.p1release plus tabulated radials, recursive-evaluator
speed-ups andsummed_neighbour_A.
tests/test_pace_mlpace_yace.pyevaluates four multi-element exports with
ML-PACE, expanded and summed, and compares them with ace-jax.
LAMMPS export
- Bundle row blocks are sized to an element target scaled by the memory of
the target GPU. o4d16 runs up to 2.65x faster on an RTX A4500. - lammps-jax is on PyPI. Install it with the new
lammpsextra:
pip install "ace-jax[lammps]". The CI tests the export with lammps-jax
0.2.0. - lammps-jax excludes jaxlib 0.10.2, because its GPU scatter-add is
approximately 4x slower. With thelammpsextra, Python 3.11 gets jax
0.10.1. - The bundle no longer writes
ace_jax.platform. lammps-jax 0.2.0 reads the
platformkey from anywhere in the bundle. Read the platform from
export_info.platform.
Benchmarks
-
The silicon accuracy-cost figure adds linear ACE run by ML-PACE with the
speed-ups proposed upstream (ICAMS/lammps-user-pace#31 on the CPU, and
prototypepace/kkkernels inpace_ref/faston the A100). Against stock
ML-PACE on the same node it is 1.5-1.8x faster on the CPU and 1.1-1.7x
faster on the A100 (o4d20: 2.89 against 5.31 µs/atom-step on 128 cores,
2.42 against 4.13 on the A100). -
The silicon accuracy-cost benchmark adds linear ACE run by ACEpotentials.jl
on the CPU: eachaj fitmodel rebuilt as an ACEpotentialsace_model
(bench/scaling/julia/build_trim_acejax.jl, gated to 1e-10 against ace-jax),
compiled withjuliac --trim(ACEpotentials PR 309) and run in LAMMPS. It is
the fastest CPU code for linear ACE up to o4d14, ties ML-PACE at o4d16 and is
2x slower than ML-PACE at o4d20 (bench/accuracy_cost/build_trim.py,
envs/sulis-cpu-trim.sbatch). -
The benchmark adds NEP (NEP4, trained with GPUMD). On the CPU it runs in
LAMMPS withpair_style nepin float64. On the A100 it runs in GPUMD in mixed
precision, and the figure labels these points. NEP is the cheapest family on
the A100. On the CPU, PACE reaches the same force error at a lower cost. Its
force error stops at approximately 0.10 eV/Å, the published NEP
result for this dataset, and it does not reach the QoI target
(bench/accuracy_cost/fit_nep.py).