Repository navigation
ace-jax 0.2.2
Upgrading from 0.2.1.
-
Refits give different results; refit to get them. The linear hyperparameter MAP is now converged by default (L-BFGS and a Newton refinement, checked), and the linear evidence and posterior are computed by QR. A fit that passes
--weightswithout--noisenow uses one shared noise scale, so the weights set the E:F:V balance; use--noise per-quantityfor the old behaviour. Saved models still load and evaluate unchanged. -
--learn-radialresults change. Radial learning now uses the QR statistics and a different optimiser, so learned radials differ from 0.2.1. -
support_oknow flags atoms.forces_supportused the wrong quantile in 0.2.0 and 0.2.1. No refit is needed. -
--weightsnow sets the E:F:V balance by default.aj fit --noise
takes a new default,auto: shared noise (one σ for every weighted row,
as ACEpotentials' BLR) when you give--weights(or weight factors), and
per-quantity noise otherwise. Before, the default was always per-quantity,
where each learned σ cancels its quantity's weight at a converged MAP, so
explicit weights had no effect (#64). Fits that pass--weightswithout
--noisechange: use--noise per-quantityto keep the old behaviour.
Fits without weights are unchanged.autouses per-quantity where shared
noise is not available (--sigma-type, joint--uq ard,--solver lstsq).config.jsonandfit.yamlrecord the resolved mode. -
--learn-radialworks on large bases. Radial learning computed its
objective, the hyperparameter re-fit and the candidate scores from the Gram
matrix, whose condition number is the square of the design's. On Si order
4, degree 16, that Gram had negative computed eigenvalues: the objective was
NaN once σ_c passed e^5, and the fit failed after six hours. All three now
use the QR statistics, as the main fit does. The objective is summed
directly as the residual at a QR-solved readout, and its gradient is exact
at that readout. On o4d16 at the fit's hyperparameters (where the Gram form
is NaN) the gradient agrees with finite differences to 5e-5. Each round is
now a SciPy L-BFGS-B run, because the QR pass runs on the host on CPUs. -
Calibrated force uncertainty on the GP arm:
aj fit --uq ard-gp
(experimental). The--uq ardstage (evidence fit, PRESS jackknife
shape, per-group rms and conformal scales) now also runs on the hybrid
ACE + GP model, over the joint design [B | k(B, B_M)] at the MAP
hyperparameters. The GP block gets one ARD scale on its prior K_MM. The
fit writesgp_model.npzwith the ARD posterior mean andposterior.npz;
GPCalculator.from_file(gp_model, posterior=...)and
aj eval --posteriorserveforces_std,forces_cov,forces_q,
forces_q_mahalandforces_group. The support flag andaj calibrate
remain linear-only.--uq ardon the linear model is unchanged.
Experimental: on the Cantor benchmark it lifts crack-tip coverage (0.902
against 0.893 for--uq ard) but ranks errors slightly less well
(Spearman ρ 0.006–0.009 lower), so--uq ardstays the recommended option
(bench/defect_uq/results/2026-10-07_ard_gp_acceptance.md). -
Smaller
--uq ardand--uq ard-gpfiles.posterior.npzstores the
L x L Cholesky factor only for--ard-variance kappa, which reads it, and
then packed (its lower triangle). The default sandwich shape serves forces
from its shape factor alone. On the Cantor basis (L = 15 035) a
posterior.npzshrinks from 1.14 GB to 0.24 GB, andACECalculatorno
longer holds an unused 1.8 GB float64 copy on the device. An--uq ard-gp
gp_model.npzno longer carries the full-posterior factor (1.9 GB to
10 MB): its force uncertainty comes fromposterior.npz, and on its own
the model gives energies and forces withoutenergy_std. Old posterior
files load unchanged.predict_ardon a saved sandwich posterior reports
NaN for the uncalibrated energy and virial variances. -
Follow a running fit.
aj fitwritesout/progress.jsonlas it runs:
one JSON line per stage, L-BFGS evaluation, Newton refinement and
radial-learning round, with timings, so a script ortail -fcan track a
long fit. Its standard output is now line-buffered, so a log written to a
file is current, not empty until the fit ends. The--learn-radialround
line now gives the objective's change within the round and the evidence
(LML) after the hyperparameters are re-fitted. The objective alone could
rise from one round to the next while the radials improved, because each
round re-weights it with the re-fitted noise. -
aj fitno longer repeats its statistics pass. A linear fit streamed
the training set three times: once for the evidence, again for the
predictions, and again to writemodel.npz. Prediction and the model file
now reuse the fit's QR statistics and its MAP posterior, which are bit for
bit what the extra passes computed. The GP and Cholesky fits reuse their
cached linear Gram and the MAP posterior. Each configuration's neighbour list
is built once, not twice. Without--test, the test dataset is the training
dataset, not a second copy of it (config.jsonthen has
"test_is_train": true). Results are unchanged, bit for bit.
FitConfig(predict_stats="auto")gives the command-line behaviour. -
Faster QR statistics on large bases. The linear fit's QR evidence
merged every batch into its triangular factors, about L^3 work per batch
and quantity. It now buffers the nonzero rows of many batches and merges
once per approximately L rows, without forming Q. At basis size 5477
(Si order 4, degree 20) one pass needs 5e13 instead of 1.2e15
floating-point operations: on a 32-core CPU the merges take an estimated
~13 min instead of ~5 h. Results agree with per-batch merging to roundoff,
not bit for bit. -
Faster, smaller fits on large bases: the A2B coupling is sparse on the
fitting path. Models now hold A2B as its nonzeros only (it is 0.025-2%
occupied), and the fit's design rows and their Jacobian use them directly.
At basis size 5456 (Si order 4, degree 20) one 224-atom batch of rows takes
1.9 s instead of 88 s on a 32-core CPU, and the 2.6 GiB dense A2B (held
2-3 times) is gone. Results equal the dense contraction to roundoff, not
bit for bit.load(..., a2b_sparse=False)keeps the dense form. -
Fixed: linear fits ran out of memory on large bases.
aj fit --m-per-species 0(and--learn-radial) no longer computes the
site-feature tensor of the whole training set, which only the GP arm reads.
At basis size 5456 on 154k atoms that tensor alone was 7.2 GiB of GPU
memory. Linear fit results are unchanged, bit for bit. -
Fixed:
forces_supportused the wrong quantile. In 0.2.0 and 0.2.1,
ACECalculator(and soaj eval --support) computedsupport_qas the
weighted α quantile of the calibration scores instead of the 1 − α
quantile the documentation defines (α = 1 −--ard-coverage, 0.1 by
default).support_okwas thereforeFalseonly when an atom's own weight
exceeded 90 % of the pool, so the flag almost never fired. It now flags
atoms at the documented level. No refit is needed: the posterior is
unchanged. Force uncertainties (forces_std,forces_q,forces_cov)
were not affected. -
--shape-path committeeonaj evalandaj calibrate
(ACECalculator(..., shape_path="committee")): the--uq ardforce
uncertainty without the whole cell's force design rows. The shape is
evaluated as the forces of a linear ACE model with one coefficient vector
per column of the shape factor, so memory scales with that factor's rank
instead of the basis size. Values equal the default path to roundoff. It
is for cells much larger than 3–4k atoms, where the default path is better.
shape_tau=andshape_rank=truncate the factor: the ranking of atoms
survives but coverage does not, since the scales are fitted at full rank. -
aj fit --uq ard --ard-support-features normalised: the support
reference on the unit-norm site descriptor plus log-norm channels per body
order, so atoms losing neighbours (a descriptor shrinking towards zero)
stay visible to the support classifier. The default staysraw. -
aj fit --noise shared: one noise scale for the energy, force and
virial rows, as in ACEpotentials' BLR, so the E:F:V weights set the
balance. The default stays--noise per-quantity(σ_E, σ_F and σ_V
learned separately).FitConfig(noise="shared")and thefit.yamlkey
noiseset it too.- Why: with three free noise scales, each cancels its quantity's weight
at a converged MAP, so weights such as ACEpotentials' E 30 / F 1 / V 1
stop mattering. Force rows far outnumber energy rows, so the evidence
then pushes σ_E up and underweights the energies. On GAP-18 silicon
(linear, order 4, degree 12, ACEpotentials' weights) per-quantity noise
learns σ_E = 2.7 against σ_F = 0.10 and gives 28.2 meV/atom and
0.125 eV/Å on the test set; shared noise (σ = 0.137) gives 10.6 meV/atom
and 0.144 eV/Å. ACEpotentials' BLR on a like-for-like basis (an
ace_modelconfigured as ace-jax builds it) gives 10.2 meV/atom,
0.135 eV/Å and 70 meV/atom in the virial (9.9 meV/atom and 0.132 eV/Å
on itsace1basis). - Use it whenever the weights are meant to set the balance, as in
ACEpotentials. On Si_tiny the shared-noise evidence optimum reproduces
ACEpotentials' own BLR fit (acefit!, default weights) to 4×10⁻⁷ in the
coefficients; per-quantity noise ends 55% away. - It is a tie, not a second objective: σ_E and σ_V copy σ_F (which keeps
its hyperprior), so the L-BFGS MAP, the Newton polish, the convergence
check and the Laplace, VI and NUTS rungs see one noise coordinate.
--learn-radialties the radial stage's inner MAPs too.
map_convergence.jsonrecordsnoiseandtied, and the resolved
fit.yamlrecordsnoise. It is not available withsigma_type,
joint ARD (--uq ard --ard-mode jointrefits the noise itself; use
sequential) or--solver lstsq. map_convergence.jsonnow also recordslog_evidence, the log
marginal likelihood at the MAP (every mode). Compare fits across noise
modes by it, not bylogpost: shared noise leaves out the hyperpriors
of the two tied scales, so itslogpostis not on the same footing.
- Why: with three free noise scales, each cancels its quantity's weight
-
Linear
aj fitnow converges the hyperparameter MAP by default, and
every fit is checked, so refits give different (better) results. The
default--optis nowlbfgs(bounded L-BFGS-B) instead ofadam.- The old default, 500 Adam steps, moved each log-hyperparameter at most
about 5 units from the prior mean, so fits on large data were not
converged, and nothing said so. On GAP-18 silicon (linear o4d12,
measured on a 0.2.0 basis) its log-posterior was −1.04×10⁷ against
+1.92×10⁵ at the optimum, σ_E was 100× too small, and the test force
RMSE was 0.345 eV/Å against 0.163 at the converged MAP. L-BFGS took
63 evaluations (0.2 s on an RTX 4000 Ada) to reach it. - Linear fits on the cached-Gram LML then take a Newton polish to a
stationary point (--map-polish, defaultauto). Its Hessian is
exact. It is built one column at a time, one Hessian-vector product per
free hyperparameter, which needs about 2.3× the gradient's memory
(515 MB against 225 MB at 2,053 basis functions).jax.hessianwould
need about 10× (2.2 GB). - GP fits (
--m-per-species> 0) are not polished by default, since one
GP gradient took about 70 s on GAP-18 Si (o3d12, 100 inducing sites).
They are checked and warned. A line-search stop of L-BFGS-B
(ABNORMAL) now restarts it once, for at most 50 evaluations.
--map-polish onpolishes a GP fit, at one Hessian-vector product per
free hyperparameter per Newton step. On the GP arm each product is a
forward-over-reverse pass through the streamed objective, so a polish
can take hours at large scale. - The check. The fit estimates what one more Newton step would gain
in log-posterior. If that exceeds 10⁻³ nats, it logs
WARNING: MAP did not convergeand warns;--strictmakes that an
error (MapNotConverged). The estimate costs no extra evaluation: it
uses the polish Hessian, or else L-BFGS-B's own limited-memory
inverse-Hessian estimate. That estimate is approximate, so on a GP fit
the gain is too. A polished fit whose log-posterior is too noisy to
resolve the last 10⁻³ nats can pass on a roundoff floor of at most
0.1 nats, and only when every gradient component is within 10× its
measured roundoff; it is then recorded asresolution_limited. The
record is written tomap_convergence.json. - Laplace rung. It now holds hyperparameters that sit on their box
bound at the MAP fixed. A converged MAP can run a noise scale to its
bound, where the Hessian is singular. - Old run files.
--opt adamis still available.FitConfig
(Python) already defaulted toopt="lbfgs", and it now polishes linear
fits too;map_polish="off"restores the old endpoint. A resolved
fit.yamlfrom an earlier run that saysopt: lbfgsalso polishes
when rerun. sigma_typefits (Python) still use Adam, unchecked: the fit warns
thatmap_polishandstrictdo not apply.
- The old default, 500 Adam steps, moved each log-hyperparameter at most
-
Changed: the linear fit's evidence and posterior are computed by QR. The
evidence fit factored the normal equations G + Λ by Cholesky, which squares the
condition number of the design. Fits that nearly interpolate their data (smooth
labels from a reference model, a well-matched basis) drive the noise level to its
floor and the prior towards flat, and there the Cholesky lost accuracy without
failing: on the repository's own Si fixture the saved weights were off by about
0.1%, and on a 685-function Si basis the evidence was off by 7%. In the worst
cases it returned NaN and wrote a model of NaN weights (the GaAs fit of the
bring-your-own-data tutorial). The linear arm (--m-per-species 0) now
compresses each quantity's design rows by QR once and evaluates the evidence,
its gradient, the predictions and the saved readout from one QR factorisation,
at the condition number of the design rather than its square. Where the
Cholesky was accurate the results agree to roundoff. An evidence evaluation costs
about 6× the Cholesky's (a few seconds per fit at a few hundred functions, more
at several thousand);--lml-solver cholesky(FitConfig(lml_solver=...))
restores the old path. The GP arm still uses the Cholesky, now falling back to
QR when it fails. -
Fixed: a model with non-finite weights is never written. A failed solve now
raises instead of saving NaN weights.
What's Changed
- Record the bit-exact pipeline goldens on lestrade by @jameskermode in #62
- Converge the hyperparameter MAP by default: L-BFGS + exact HVP Newton polish, checked by @jameskermode in #63
- Parallel docs CI, and tutorials consistent with post-#57 fits by @jameskermode in #59
- Linear evidence and posterior by QR; goldens recorded on lestrade by @jameskermode in #61
- Simplify user docs toward ASD-STE100 by @jameskermode in #65
- test(ard): hold the exponent transfer to its wiring, not a fixture value (fixes main CI) by @jameskermode in #68
- aj fit --noise shared: one noise scale for E, F and V rows (ACEfit BLR) by @jameskermode in #67
- Force UQ vs CALM: support-quantile fix, normalised support features, committee shape path, bond-scan and precision results by @jameskermode in #66
- Linear fits do not materialise the site-feature tensor by @jameskermode in #69
- Julia parity covers the basis builder; post mortem of #57 by @jameskermode in #70
- Sparse A2B on the fitting path (o4d20 rows 88.5 s → 1.9 s) by @jameskermode in #72
- Batched QR merges for the linear evidence statistics (o4d20 pass 71 → 9 min) by @jameskermode in #73
- perf(fit): reuse the fit's statistics in prediction and export; one neighbour list per config by @jameskermode in #74
- ci: refresh .test_durations to rebalance the test shards by @jameskermode in #76
- perf(fit): MAP polish takes the linear arm's kernel Hessian columns from the hyperprior by @jameskermode in #75
- feat(fit): progress.jsonl and a live log for running fits; comparable radial-round progress by @jameskermode in #78
- Calibrated force UQ on the GP arm: --uq ard-gp (experimental); GP-discrepancy Phase 0 report by @jameskermode in #77
- fix(fit): radial learning on QR statistics; the objective summed directly by @jameskermode in #79
- perf(fit): compile the device QR statistics pass once, not per call by @jameskermode in #81
- --noise auto: --weights sets the E:F:V balance by default by @jameskermode in #80
Full Changelog: v0.2.1...v0.2.2