Skip to content

ace-jax 0.2.2

Choose a tag to compare

@jameskermode jameskermode released this 07 Oct 21:28
· 96 commits to main since this release
aebba14

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 --weights without --noise now uses one shared noise scale, so the weights set the E:F:V balance; use --noise per-quantity for the old behaviour. Saved models still load and evaluate unchanged.

  • --learn-radial results change. Radial learning now uses the QR statistics and a different optimiser, so learned radials differ from 0.2.1.

  • support_ok now flags atoms. forces_support used the wrong quantile in 0.2.0 and 0.2.1. No refit is needed.

  • --weights now 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 --weights without
    --noise change
    : use --noise per-quantity to keep the old behaviour.
    Fits without weights are unchanged. auto uses per-quantity where shared
    noise is not available (--sigma-type, joint --uq ard, --solver lstsq). config.json and fit.yaml record the resolved mode.

  • --learn-radial works 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 ard stage (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 writes gp_model.npz with the ARD posterior mean and posterior.npz;
    GPCalculator.from_file(gp_model, posterior=...) and
    aj eval --posterior serve forces_std, forces_cov, forces_q,
    forces_q_mahal and forces_group. The support flag and aj calibrate
    remain linear-only. --uq ard on 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 ard stays the recommended option
    (bench/defect_uq/results/2026-10-07_ard_gp_acceptance.md).

  • Smaller --uq ard and --uq ard-gp files. posterior.npz stores 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.npz shrinks from 1.14 GB to 0.24 GB, and ACECalculator no
    longer holds an unused 1.8 GB float64 copy on the device. An --uq ard-gp
    gp_model.npz no longer carries the full-posterior factor (1.9 GB to
    10 MB): its force uncertainty comes from posterior.npz, and on its own
    the model gives energies and forces without energy_std. Old posterior
    files load unchanged. predict_ard on a saved sandwich posterior reports
    NaN for the uncalibrated energy and virial variances.

  • Follow a running fit. aj fit writes out/progress.jsonl as it runs:
    one JSON line per stage, L-BFGS evaluation, Newton refinement and
    radial-learning round, with timings, so a script or tail -f can 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-radial round
    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 fit no 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 write model.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.json then 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_support used the wrong quantile. In 0.2.0 and 0.2.1,
    ACECalculator (and so aj eval --support) computed support_q as the
    weighted α quantile of the calibration scores instead of the 1 − α
    quantile the documentation defines (α = 1 − --ard-coverage, 0.1 by
    default). support_ok was therefore False only 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 committee on aj eval and aj calibrate
    (ACECalculator(..., shape_path="committee")): the --uq ard force
    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= and shape_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 stays raw.

  • 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 the fit.yaml key
    noise set 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_model configured 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 its ace1 basis).
    • 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-radial ties the radial stage's inner MAPs too.
      map_convergence.json records noise and tied, and the resolved
      fit.yaml records noise. It is not available with sigma_type,
      joint ARD (--uq ard --ard-mode joint refits the noise itself; use
      sequential) or --solver lstsq.
    • map_convergence.json now also records log_evidence, the log
      marginal likelihood at the MAP (every mode). Compare fits across noise
      modes by it, not by logpost: shared noise leaves out the hyperpriors
      of the two tied scales, so its logpost is not on the same footing.
  • Linear aj fit now converges the hyperparameter MAP by default, and
    every fit is checked, so refits give different (better) results.
    The
    default --opt is now lbfgs (bounded L-BFGS-B) instead of adam.

    • 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, default auto). 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.hessian would
      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 on polishes 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 converge and warns; --strict makes 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 as resolution_limited. The
      record is written to map_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 adam is still available. FitConfig
      (Python) already defaulted to opt="lbfgs", and it now polishes linear
      fits too; map_polish="off" restores the old endpoint. A resolved
      fit.yaml from an earlier run that says opt: lbfgs also polishes
      when rerun.
    • sigma_type fits (Python) still use Adam, unchecked: the fit warns
      that map_polish and strict do not apply.
  • 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