franken 0.5.0

Franken fine-tuning scheme for ML potentials

Franken

Introduction

Franken is an open-source library that can be used to enhance the accuracy of atomistic foundation models. It can be used for molecular dynamics simulations, and has a focus on computational efficiency.

franken features include:

• Supports fine-tuning for a variety of foundation models (MACE, SevenNet, SchNet)
• Automatic hyperparameter tuning simplifies the adaptation procedure, for an out-of-the-box user experience.
• Several random-feature approximations to common kernels (e.g. Gaussian, polynomial) are available to flexibly fine-tune any foundation model.
• Support for running within LAMMPS molecular dynamics, as well as with ASE.

For detailed information and benchmarks please check our paper Fast and Fourier Features for Transfer Learning of Interatomic Potentials.

Documentation

A full documentation including several examples is available: https://franken.readthedocs.io/index.html. The paper also contains a comprehensive description of the methods behind franken.

Install

To install the latest release of franken, you can simply do:

pip install franken

Several optional dependencies can be specified, to install packages required for certain operations:

• cuda includes packages which speed up training on GPUs (note that franken will work on GPUs even without these dependencies thanks to pytorch).
• fairchem, mace, sevenn install the necessary dependencies to use a specific backbone. Note that Fairchem v2 introduced breaking changes, so use v1 for SchNet support.
• docs and develop are only needed if you wish to build the documentation, or work on extending the library.

They can be installed for example by running

pip install franken[mace,cuda]

For more details read the relevant documentation page

Quickstart

Train

You can directly run franken.autotune to get started with the franken library.

franken.autotune \
    --train-path train.xyz \
    --val-path val.xyz \
    --backbone=mace --mace.path-or-id "mace_mp/small" --mace.interaction-block 2 \
    --rf=ms-gaussian --ms-gaussian.num-rf 4096 --ms-gaussian.length-scale-num 5\
    --ms-gaussian.length-scale-low 1  --ms-gaussian.length-scale-high 32 \
    --force-weight=0.99 \
    --l2-penalty="(-10, -6, 5, log)" \
    --metrics energy_MAE forces_MAE \
    --jac-chunk-size "auto"

For more details you can check out the autotune tutorial or the getting started notebook.

Inference/MD

The trained model can be used as a ASE (Atomistic Simulations Environment) calculator for easy inference.

from franken.calculators import FrankenCalculator
calc = FrankenCalculator('best_model.ckpt', device='cuda:0')
atoms.calc = calc

See the MD tutorial for a complete example about running molecular dynamics, while for deploying it to LAMMPS see the dedicated page.

Citing

If you find this library useful, please cite our work using the folowing bibtex entry:

@article{novelli2025fast,
  title={Fast and Fourier features for transfer learning of interatomic potentials},
  author={Novelli, Pietro and Meanti, Giacomo and Buigues, Pedro J and Rosasco, Lorenzo and Parrinello, Michele and Pontil, Massimiliano and Bonati, Luigi},
  journal={npj Computational Materials},
  volume={11},
  number={1},
  pages={293},
  year={2025},
  publisher={Nature Publishing Group UK London}
}