v2026.2

Fixed

• Reduced memory usage for training runs without gradient targets.
• A restarted training run will now run only for the residual number of epochs, instead
  of the full number of epochs specified in the options.yaml file.
• Fixed overflow of atomic indices in MemmapDataset for very large datasets.
• Fixed a problem with the displayed metrics when training with mixed-stress datasets.
• Fixed edge cases affecting isolated-atom structures in PET and FlashMD.
• Architectures relying on metatrain's Scaler can now be called requesting no
  outputs. This was broken previously.

Added

• New Classifier architecture for classification tasks.
• Added support for distributed LLPR calibration.
• Added CRPS calibration for LLPR uncertainties and CRPS loss for LLPR ensembles.
• Zero-sized validation sets are now allowed.

Changed

• LLPR models will not run final evaluation after training.
• LLPR models now rely on a Cholesky decomposition for improved numerical stability.
• Omitting the cell is now allowed for MemmapDataset in cases where all systems in
  the dataset are fully non-periodic.

Removed

• Removed the deprecated.nanopet architecture.

New Contributors

• @ChaitanyaParate made their first contribution in #1003
• @sirmarcel made their first contribution in #788
• @JonathanSchmidt1 made their first contribution in #1059

Full Changelog: v2026.1...v2026.2

v2026.1

Fixed

• Uncertainty quantification is now possible on non-conservative forces.
• Fixed a small bug in the implementation of the density of states (DOS) loss function.

Added

• Metatrain now features the experimental.mace architecture.
• Most architectures now support bounds on the number of atoms in a single batch via the
  batch_bounds hyperparameter.
• The PET architecture now supports an adaptive cutoff functionality to make the
  number of neighbors more uniform across different atoms and environments.
• The PET architecture now features a temperature hyperparameter for the softmax
  operation in attention.
• The FlashMD architecture added fine-tuning capabilities similar to those of PET.

Changed

• SOAP-BPNN and MCoV now use species embeddings by default, allowing for better
  scalability and speed. The traditional SOAP-BPNN (and associated MCoV) architecture
  can be accessed by setting legacy: True
• Metatrain won't error if the validation set is smaller than the batch size.
• Composition model settings have been consolidated under the atomic_baseline
  hyperparameter.

New Contributors

• @Technici4n made their first contribution in #947

Full Changelog: v2025.12...v2026.1

v2025.12

Fixed

• Improved computational efficiency of the SOAP-BPNN architecture.
• Improved computational efficiency of DiskDataset.
• Longe-range featurizer now also works with 2D periodic boundary conditions.

Added

• An option to inherit head weights during fine-tuning
• DOS loss for training on the electronic density of states
• A method to train on mixed-stress datasets by setting stresses in non-periodic
  structures to NaN.
• Support to train target variants defined by / (i.e. energy/PBE).
  Variants can be selected as a property to be predicted by an engine as opposed to a
  base target (i.e. energy).
• The LLPR architecture now allows training LLPR ensembles by backpropagation after
  their creation from the LLPR covariance. This includes support for multi-GPU training.

Changed

• Raise an error (instead of warning) if energies gradients are direct targets and do
  not have a "non_conservative" prefix

New Contributors

• @HowWeiBin made their first contribution in #886

Full Changelog: v2025.11...v2025.12

v2025.11

Fixed

• Training speed has been improved for all neural network models.
• Multi-GPU training with multiple datasets, each with different targets, now works
  correctly.
• It is now possible to train on multiple force/stress targets without errors.

Added

• A new dataset format, MemmapDataset, allows storing data on disk in a
  memory-mapped format, improving performance compared to DiskDataset on some
  filesystems.
• FlashMD was added as a new architecture allowing long-stride molecular dynamics
  simulations. Its implementation is based on PET.

Changed

• PET model received a major update, including new default hyperparameters, a new
  transformer architecture, and a new featurizer. Please refer to the updated
  documentation for more details.
• The SOAP-BPNN and PET trainers now uses a cosine annealing learning rate scheduler
  with warm-up.
• NanoPET has been deprecated in favor of the stable PET architecture. The
  deprecated.nanopet architecture is still available for loading old checkpoints.
• The NanoPET and GAP architectures now use the new composition model, and the
  old composition model has been removed.
• The LLPR module is now a stable architecture, instead of a utility module. It can
  be trained from the command line in the same way as other architectures.
• We now require Python >= 3.10.
• The Scaler model in metatrain now calculates per-block and per-property scales.
  For atomic targets, it calculates per-element scales.

Removed

• The deprecated.pet architecture has been removed.

New Contributors

• @johannes-spies made their first contribution in #768
• @cesaremalosso made their first contribution in #771
• @HannaTuerk made their first contribution in #772
• @HaoZeke made their first contribution in #785
• @ceriottm made their first contribution in #810
• @E-Rum made their first contribution in #792

v2025.10

Fixed

• Fixed a bug with the composition model during transfer-learning

Changed

• Refactored the loss.py module to provide an easier to extend interface for custom
  loss functions.
• Updated the trainer checkpoints to account for changes in the loss-related hypers.

v2025.9.1

This is a bugfix release fixing incompatibilities with PET-MAD when updating checkpoints and exporting.

v2025.9

We’re excited to announce a brand-new release of metatrain! 🎉
This update brings fresh features, important fixes, and usability improvements.

Highlights in this release

🗂️ Checkpoint versioning — keeps your training checkpoints more stable when architectures evolve.
📊 Improved logging — clearer, more detailed training logs to better track progress.
🧩 General target training — beyond energies and forces, paving the way for exciting new applications coming soon.

Added

• Use the best model instead of the latest model for evaluation at the end of training.
• Log the best epoch when loading checkpoints.
• Allow changing the scheduler factor in PET.
• Introduce checkpoint versioning and updating.
• Added CI tests on GPU.
• Log the number of model parameters before training starts.
• Add additional logs to the checkpoints, model, and output directories at the end of
  training.
• Cache files locally and re-use them when downloading checkpoints and models from
  Hugging Face.
• extra_data is now a valid section in the options.yaml file, allowing users to
  add custom data to the training set. The data is included in the dataloader and can be
  used in custom loss functions or models.
• mtt eval can now evaluate models on a DiskDataset.

Changed

• Updated to a new general composition model.
• Updated to a new implementation of LLPR.

Fixed

• Fixed device and dtype not being set during LoRA fine-tuning in PET.
• Log messages are now shown when training with restart="auto".
• Fixed incorrect sub-section naming in the Wandb logger.

New Contributors

• @sofiia-chorna made their first contribution in #624
• @RMeli made their first contribution in #677
• @pfebrer made their first contribution in #681

Full Changelog: v2025.8.1...v2025.9

v2025.8.1

Changed

• Checkpoints for fine-tuning files are now passed from the options.yaml.

v2025.7

Changed

• Metatrain is now built on top of metatomic instead of
  metatensor.torch.atomistic. Please refer to https://docs.metatensor.org/metatomic/
  to find how to use the new models.

v2025.6

Fixed

• PET can now evaluate on single-atom structures without crashing
• The metatrain dataloader doesn't load all batches ahead of each epoch anymore

Added

• NanoPET and PET can now train on non-conservative stresses
• Users can now choose the name of the extension directory in mtt train and
  mtt export via the --extensions (or -e) option
• Update to metatensor-torch-0.7.6, adding support for torch 2.7
• PET now supports gradient clipping as a new training hyperparameter

Changed

• Training and exporting models without extensions will no longer lead to the creation
  of an empty directory for the extensions
• The SOAP-BPNN model now uses torch-spex instead of featomic as its SOAP
  backend
• PET from the previous version is now deprecated and accessible as
  deprecated.pet, while the old NativePET (experimental.nativepet) is
  now called PET (pet from training option files)
• The Angstrom character is now represented as A and not Å in the training logs