v0.3.17

MACE v0.3.17 Release Notes

MACE v0.3.17 adds magnetic models, an opt-in polarizability and Fukui functions for PolarMACE, the MACE-MDP calculator, and faster stress and lower memory on large systems. It also raises the minimum versions to Python 3.11 and PyTorch 2.5, and it is the first release that warns about the options MACE v1.0 removes or replaces.

⚠️ Breaking changes

• Python 3.11 or newer is required. Python 3.9 and 3.10 are no longer supported. Python 3.14 is now supported and tested. (#1520, #1759)
• PyTorch 2.5 or newer is required. The previous torch>=1.12 was not true: the core path already needed 2.4. CI now tests the 2.5 floor explicitly. (#1759)
• MACECalculator(warmup=...) is removed. The parameter was accepted and did nothing. Passing it now raises a TypeError. (#1689)
• IPEX support is removed. Intel retired the extension in favour of native XPU support in PyTorch 2.8 and later. (#1522)
• The cueq-cuda-11 extra is removed. Its kernel wheels stopped at 0.5.1 and no longer matched the frontend. Use cueq-cuda-12 on a CUDA 11 host, or the new cueq-cuda-13 extra. Match the extra to torch.version.cuda.
• cuEquivariance convolution fusion is off by default during training, because it regressed badly on variable-shape batches. Inference keeps it on. Use --cueq_conv_fusion=True to opt back in. (#1702)

🔬 Models

MagneticMACE

Added MagneticMACE, a family of spin-informed models for collinear and non-collinear magnetic moments, with an ASE MagneticMACECalculator. Select it with --model=MagneticScaleShiftMACE. New flags cover magnetic forces (--compute_magforces, --magforces_weight, --magmom_key, --magforces_key), the magnetic radial basis (--num_mag_radial_basis, --m_max, --max_m_ell) and magnetic moment augmentation (--data_aug_magmom, --data_aug_magmom_mode). Requires the magnetic extra (sphericart-torch>=2.0). (#1244, #1731)

TimeReversalSymmetrizedMACE wraps any magnetic model and makes it exactly invariant under reversing all magnetic moments. It needs no retraining: load a checkpoint and wrap it.

from mace.modules import TimeReversalSymmetrizedMACE

model = TimeReversalSymmetrizedMACE(base_model)                # one batched forward pass
model = TimeReversalSymmetrizedMACE(base_model, batched=False) # lower peak memory

(#1664)

PolarMACE polarizability

PolarMACE can now return the polarizability tensor on request. Two definitions are available, from the derivative of the dipole (default) or the second derivative of the energy with respect to the field. PolarMACE is not variational, so the two differ and both are exposed. A plain energy call is unchanged.

alpha = calc.get_polarizability(atoms, method="dipole")  # or method="energy"

The field is read from atoms.info["external_field"] and defaults to zero. (#1755)

PolarMACE Fukui functions and density cubes

• The calculator returns per-atom Fukui functions for PolarMACE models in results["fukui_functions"], with shape (num_atoms, 2).
• The new mace_polar_density_cube command writes MACE-Polar charge densities to Gaussian cube files, with a quality report.
• atoms.get_dipole_moment() now works with mace_polar. (#1700)

Other model changes

• A MACE type model can now use the non-linear interaction block as its first layer. (#1394)
• AtomicDielectricMACE supports enable_cueq=True. (#1439)
• Fixed an iteration order bug in the weights of the symmetric contraction. (#1622)
• Each interaction block's avg_num_neighbors is now a checkpointed buffer, so it follows dtype and device conversions. Older checkpoints still load and still export to LAMMPS. (#1538, #1645)

🏗️ Foundation models

MACE-MDP

Added mace_mdp, a calculator for MACE-MDP, which predicts dipoles and polarizabilities of organic molecules and condensed phases. It does not predict energies or forces. Fine-tuning these models uses --finetune_dipoles_polarizabilities. (#1439)

from mace.calculators import mace_mdp

atoms.calc = mace_mdp(device="cuda")

Model downloads

• A failed or interrupted download no longer poisons the cache. (#1629)
• An HTML error page is rejected before it is cached as a model. (#1712)

⚡ Performance

• Stress is up to 80% faster for single-structure batches, the usual case in MD. Measured on large Cu, Si and Fe systems. (#1498)
• Up to 2.6x less memory in PolarMACE. SparseUvuTensorProduct no longer builds a [B, mul1, mul2] outer product. On a 16 GB T4, polar-1-s with cuEquivariance now fits 4380 atoms instead of 1914. (#1711)
• Fixed device detection for cuEquivariance convolution fusion. (#1641)

🎯 Training and fine-tuning

• Fine-tuning supports additional arbitrary embeddings. Matching embeddings are copied from the foundation model and new ones are initialised small. (#1420)
• New --warmup_steps_schedulefree for linear LR warmup with the ScheduleFree optimizer.
• Multi-head result plots show only each head's own test set, labelled with the head name. (#1445)
• Dataset logging counts labels instead of summing weights, so non-unit weights no longer inflate the counts. (#1477)
• Pseudolabelled replay data is usable, and refused with a clear error when it is not. (#1649)
• --foundation_model_readout controls the readout transfer again. (#1676)
• --multi_processed_test works. (#1693)
• A wrong batch size fails where it is set instead of deep inside training. (#1648)
• All parameters are registered in optimizer groups explicitly. (#1529)
• LoRA merging handles e3nn linears with a bias. (#1677)
• Multi-GPU and multi-node training on Intel XPU clusters is fixed. (#1522, #1624)
• CPU DDP and several broken console entry points are fixed. (#1511)
• DataLoader workers start correctly on Python 3.14, where forkserver became the default. (#1759)

🐛 Bug fixes

Neighbour lists and stress

• The stress of a graph with no periodic direction is now zero. It used to be divided by an invented padding volume. A batch mixing molecules and crystals keeps the crystals' stress. (#1684)
• Non-periodic and partially periodic cells get a correct search box. Aperiodic neighbour lists no longer depend on where the molecule sits, and the box is orthogonal to the periodic lattice vectors. (#1533, #1726, #1727)

Calculators

• Committee models scale their spread by the square of the unit conversion, read stress from the right member, and report stress and dipole spread in Voigt-6. (#1629, #1656, #1679)
• make_alpha_positive applies to isotropic polarizabilities. (#1615)
• The per-atom outputs of the LES calculator no longer carry padding. (#1616)
• The magnetic calculator scopes its dtype instead of setting it globally, and the process default dtype is restored after any change. (#1627, #1659)
• SCF-wrapped magnetic models answer for the model they wrap and refuse hessians. (#1625, #1626)

LAMMPS

• ML-IAP results are written back through the coupling LAMMPS actually has, so non-KOKKOS builds work. (#1644)
• A failed compiled export now says so. (#1697)

Data and CLIs

• mace_eval_configs handles ragged structure sets and a dtype that disagrees with the checkpoint. (#1654)
• LMDBDataset honours the CLI key specification, and HDF5 test sets use the right keys. (#1516, #1620)
• Fixed head matching, r_max reporting and the magmom cache. (#1624)
• mace_plot_train works again. (#1668, #1686)

📢 Towards MACE v1.0

MACE v1.0 is a rewrite and does not carry every option of the 0.3.x line. Options, commands, classes and output keys that v1.0 removes or replaces now raise a FutureWarning when you use them. Nothing changes about what they do in 0.3.x. To see the whole list:

python -m mace.tools.deprecation

Every message starts with MACE v1.0, so one filter silences all of them:

import warnings
warnings.filterwarnings("ignore", message="MACE v1.0", category=FutureWarning)

(#1715, #1721)

The README links to the rewrite and its board, and the new CONTRIBUTING.md says which changes belong in v0.3 and which in v1. (#1699)

🧪 Testing and CI

• The test suite is reorganised by what each test needs (unit, workflows, backends, extensions, foundations, integrations). Missing optional dependencies skip locally but fail in CI. (#1515, #1514)
• Golden references pin the numerics of the published foundation models, the dipole, dielectric, polar, magnetic and LES families, and the cueq and oeq kernels, so a change that moves an energy fails the PR.
• A functionality inventory and checker record which flag, class and CLI each test covers.
• GPU tests run on NVIDIA and AMD hardware at MPCDF, including OpenEquivariance. (#1546)
• Coverage is uploaded to Coveralls, with per-file floors on the core modules. (#1631, #1661)
• graph_longrange is installed from PyPI (>=0.4.4) for the polar extra. (#1718, #1751)

🙏 Contributors

Thanks to everyone who contributed to this release:
@aacostadiaz, @arnon-1, @alinelena, @alvarovm, @CheukHinHoJerry, @CompRhys, @darthjaja6, @ElliottKasoar, @ilyes319, @joehart2001, @lollcat, @LOGO127, @Nilsgoe, @rwkeane, @steffen-wedig, @SunZichen-2004, @theochemtheo, @vue1999, @williamdavie, @WillBaldwin0, @zhubonan, and @AbrarFaiyad for the multi-GPU XPU fix.

Full changelog: v0.3.16...v0.3.17