Metadata-Version: 2.4
Name: franken
Version: 0.5.0
Summary: Franken fine-tuning scheme for ML potentials
Project-URL: Homepage, https://franken.readthedocs.io/
Project-URL: Documentation, https://franken.readthedocs.io/
Project-URL: Repository, https://github.com/CSML-IIT-UCL/franken
Author: Giacomo Meanti, Luigi Bonati, Pedro Juan Buigues Jorro
Author-email: Pietro Novelli <pietronvll@gmail.com>
License-Expression: MIT
License-File: LICENSE.txt
Keywords: franken,molecular dynamics,potentials
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: ase
Requires-Dist: docstring-parser
Requires-Dist: e3nn
Requires-Dist: numpy
Requires-Dist: omegaconf
Requires-Dist: psutil
Requires-Dist: requests
Requires-Dist: scipy
Requires-Dist: torch>=2.4.0
Requires-Dist: tqdm
Provides-Extra: cuda
Requires-Dist: cupy; extra == 'cuda'
Provides-Extra: develop
Requires-Dist: black~=24.0; extra == 'develop'
Requires-Dist: packaging; extra == 'develop'
Requires-Dist: pre-commit; extra == 'develop'
Requires-Dist: pytest; extra == 'develop'
Requires-Dist: ruff; extra == 'develop'
Provides-Extra: docs
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: nbsphinx; extra == 'docs'
Requires-Dist: sphinx; extra == 'docs'
Requires-Dist: sphinx-argparse; extra == 'docs'
Requires-Dist: sphinxawesome-theme; extra == 'docs'
Requires-Dist: sphinxcontrib-applehelp; extra == 'docs'
Requires-Dist: sphinxcontrib-devhelp; extra == 'docs'
Requires-Dist: sphinxcontrib-htmlhelp; extra == 'docs'
Requires-Dist: sphinxcontrib-jsmath; extra == 'docs'
Requires-Dist: sphinxcontrib-qthelp; extra == 'docs'
Requires-Dist: sphinxcontrib-serializinghtml; extra == 'docs'
Provides-Extra: fairchem
Requires-Dist: fairchem-core==1.10; extra == 'fairchem'
Provides-Extra: mace
Requires-Dist: mace-torch>=0.3.10; extra == 'mace'
Provides-Extra: sevenn
Requires-Dist: sevenn~=0.11; extra == 'sevenn'
Description-Content-Type: text/markdown

# Franken

[![Test status](https://github.com/CSML-IIT-UCL/franken/actions/workflows/CI.yaml/badge.svg)](https://github.com/CSML-IIT-UCL/franken/actions/workflows/CI.yaml)
[![Docs status](https://github.com/CSML-IIT-UCL/franken/actions/workflows/rtd.yaml/badge.svg)](https://franken.readthedocs.io/)


## 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](https://github.com/ACEsuit/mace), [SevenNet](https://github.com/MDIL-SNU/SevenNet), [SchNet](https://github.com/facebookresearch/fairchem))
 - Automatic [hyperparameter tuning](https://franken.readthedocs.io/notebooks/autotune.html) 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](https://www.lammps.org/) molecular dynamics, as well as with [ASE](https://wiki.fysik.dtu.dk/ase/).

<img src="/docs/_static/diagram_part1.png" alt="Franken diagram" width="1000px">

For detailed information and benchmarks please check our paper [*Fast and Fourier Features for Transfer Learning of Interatomic Potentials*](https://arxiv.org/abs/2505.05652).

## Documentation

A full documentation including several examples is available: [https://franken.readthedocs.io/index.html](https://franken.readthedocs.io/index.html). [The paper](https://arxiv.org/abs/2505.05652) also contains a comprehensive description of the methods behind franken.

## Install

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

```bash
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

```bash
pip install franken[mace,cuda]
```

For more details read the [relevant documentation page](https://franken.readthedocs.io/topics/installation.html)

## Quickstart

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

```bash
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](https://franken.readthedocs.io/notebooks/autotune.html) or the [getting started notebook](https://franken.readthedocs.io/notebooks/getting_started.html).

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

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

See the [MD tutorial](.https://franken.readthedocs.io/notebooks/molecular_dynamics.html) for a complete example about running molecular dynamics, while for deploying it to LAMMPS see the dedicated [page](https://franken.readthedocs.io/topics/lammps.html).

## 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}
}
```
