Skip to content

ace-jax 0.7.0

Choose a tag to compare

@jameskermode jameskermode released this 19 Nov 18:40
· 7 commits to main since this release
7918fa9

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, the ham extra). 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.npz fits a model to structures with blocks, in the DeepH file
      layout or as ace-jax cache files. --prior sets a smoothness prior: a number, evidence, loo or
      press. --validation DIR gives the errors of the fitted model.
    • aj ham predict writes the H and S blocks of structures in the DeepH layout.
    • aj ham bands gives 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.npz gives 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.HamiltonianCalculator is 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.md has 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_onsite and fit_offsite fit them on ace_jax.fit.linear;
    operators.io.save and load write and read one self-contained .npz model file.
  • Equivariant couplings. ace_jax.basis.coupling.couple_equivariant gives the coupling of features
    that transform as a vector of angular momentum L (L ≤ 6) of each parity, from ace-jax-coupling 0.3.0.
    ace_jax.basis.cg has the real Clebsch-Gordan tables.
  • Leave-one-block-out for linear fits. ace_jax.fit.linear.loo gives 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 sides Y. stats.qr_statistics and stats.gram_statistics stream
    it into one Factor or Gram for each quantity (on the host with checkpoints and MPI, or on a device).
    objective.log_evidence_qr, objective.posterior_qr and lml_host.HostQREvidence give the evidence
    and the posterior. ace_jax.uq.ard.ARDEvidence and ace_jax.uq.jackknife.press_scores_rows take any
    labelled quantities. The energy, force and virial fit uses these functions; its results are bit-identical.
  • ace_jax.eval.features has the SiteFeatures protocol for equivariant site features, and pooled_a,
    which gives the one-particle basis of a linear ACE from a radial and index arrays.
    ace_jax.eval.radial.TensorRadial is the tensor radial of a model without the model.
  • ace_jax.uq.force.ForceUQ gives the force uncertainty of a posterior for one structure. It takes the
    design rows of the model from an object such as ace_jax.fit.design.ForceDesign.
    ACECalculator(posterior=...) uses it (calc.uq); the results are the same.

Changed

  • ace_jax.fit is split by role, and uncertainty quantification is ace_jax.uq. No behaviour changes.
    ace_jax.fit.linear and ace_jax.uq are 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_root is in fit.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.embedding fit.radial.learn, fit.radial.model, fit.radial.embedding
    fit.rowcheck fit.pipeline.rowcheck
  • ace_jax.eval.product holds the A basis and its products as functions of arrays (pool_sparse,
    edge_a, product_basis, estimate_a_bytes, ...). ace_jax.eval.edge_model and ace_jax.eval.model
    still give these names. compact is in ace_jax.eval.dense, cubic_bspline_coefs in
    ace_jax.eval.radial and ace_ctilde_tree in ace_jax.eval.pace_ace; their old modules still give them.

Removed

  • ace_jax.eval.ACECalculator. Use ace_jax.ACECalculator.

Fixed

  • Hamiltonian models of several elements on a CPU. A fit or an evaluation of a model with four
    elements stopped with LLVM compilation error: Cannot allocate memory when 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.