Repository navigation
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.