# Franken
[](https://github.com/CSML-IIT-UCL/franken/actions/workflows/CI.yaml)
[](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">
## Documentation
A full documentation including several examples is available: [https://franken.readthedocs.io/index.html](https://franken.readthedocs.io/index.html).
For a comprehensive description of the methods behind franken, have a look at [the paper](https://arxiv.org/abs/2505.05652).
## 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.
- `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
You can directly run `franken.autotune` to get started with the `franken` library. A quick example is to fine-tune MACE-MP0 on a high-level-of-theory water dataset:
```bash
franken.autotune \
--dataset-name="water" --max-train-samples=8 \
--l2-penalty="(-10, -5, 5, log)" \
--force-weight="(0.01, 0.99, 5, linear)" \
--seed=42 \
--jac-chunk-size=64 \
--run-dir="./results" \
--backbone=mace --mace.path-or-id="MACE-L0" --mace.interaction-block=2 \
--rf=gaussian --gaussian.num-rf=512 --gaussian.length-scale="[10.0, 15.0]"
```
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).
## Citing
If you find this library useful, please cite our work using the folowing bibtex entry:
```
@misc{novelli25franken,
title={Fast and Fourier Features for Transfer Learning of Interatomic Potentials},
author={Pietro Novelli and Giacomo Meanti and Pedro J. Buigues and Lorenzo Rosasco and Michele Parrinello and Massimiliano Pontil and Luigi Bonati},
year={2025},
eprint={2505.05652},
archivePrefix={arXiv},
url={https://arxiv.org/abs/2505.05652},
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "franken",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "franken, molecular dynamics, potentials",
"author": "Giacomo Meanti, Luigi Bonati, Pedro Juan Buigues Jorro",
"author_email": "Pietro Novelli <pietronvll@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/cb/d7/1289067ca5e014489ce6bff66a6289f179b1303aea44b8e2b93d846a9a92/franken-0.4.0.tar.gz",
"platform": null,
"description": "# Franken\n\n[](https://github.com/CSML-IIT-UCL/franken/actions/workflows/CI.yaml)\n[](https://franken.readthedocs.io/)\n\n\n## Introduction\n\nFranken 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.\n\n`franken` features include:\n - 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))\n - Automatic [hyperparameter tuning](https://franken.readthedocs.io/notebooks/autotune.html) simplifies the adaptation procedure, for an out-of-the-box user experience.\n - Several random-feature approximations to common kernels (e.g. Gaussian, polynomial) are available to flexibly fine-tune any foundation model.\n - Support for running within [LAMMPS](https://www.lammps.org/) molecular dynamics, as well as with [ASE](https://wiki.fysik.dtu.dk/ase/).\n\n<img src=\"/docs/_static/diagram_part1.png\" alt=\"Franken diagram\" width=\"1000px\">\n\n## Documentation\n\nA full documentation including several examples is available: [https://franken.readthedocs.io/index.html](https://franken.readthedocs.io/index.html).\n\nFor a comprehensive description of the methods behind franken, have a look at [the paper](https://arxiv.org/abs/2505.05652).\n\n## Install\n\nTo install the latest release of `franken`, you can simply do:\n\n```bash\npip install franken\n```\n\nSeveral optional dependencies can be specified, to install packages required for certain operations:\n - `cuda` includes packages which speed up training on GPUs (note that `franken` will work on GPUs even without these dependencies thanks to pytorch).\n - `fairchem`, `mace`, `sevenn` install the necessary dependencies to use a specific backbone.\n - `docs` and `develop` are only needed if you wish to build the documentation, or work on extending the library.\n\nThey can be installed for example by running\n\n```bash\npip install franken[mace,cuda]\n```\n\nFor more details read the [relevant documentation page](https://franken.readthedocs.io/topics/installation.html)\n\n## Quickstart\n\nYou can directly run `franken.autotune` to get started with the `franken` library. A quick example is to fine-tune MACE-MP0 on a high-level-of-theory water dataset:\n\n```bash\nfranken.autotune \\\n --dataset-name=\"water\" --max-train-samples=8 \\\n --l2-penalty=\"(-10, -5, 5, log)\" \\\n --force-weight=\"(0.01, 0.99, 5, linear)\" \\\n --seed=42 \\\n --jac-chunk-size=64 \\\n --run-dir=\"./results\" \\\n --backbone=mace --mace.path-or-id=\"MACE-L0\" --mace.interaction-block=2 \\\n --rf=gaussian --gaussian.num-rf=512 --gaussian.length-scale=\"[10.0, 15.0]\"\n```\n\nFor 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).\n\n\n## Citing\n\nIf you find this library useful, please cite our work using the folowing bibtex entry:\n```\n@misc{novelli25franken,\n title={Fast and Fourier Features for Transfer Learning of Interatomic Potentials},\n author={Pietro Novelli and Giacomo Meanti and Pedro J. Buigues and Lorenzo Rosasco and Michele Parrinello and Massimiliano Pontil and Luigi Bonati},\n year={2025},\n eprint={2505.05652},\n archivePrefix={arXiv},\n url={https://arxiv.org/abs/2505.05652},\n}\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Franken fine-tuning scheme for ML potentials",
"version": "0.4.0",
"project_urls": {
"Documentation": "https://franken.readthedocs.io/",
"Homepage": "https://franken.readthedocs.io/",
"Repository": "https://github.com/CSML-IIT-UCL/franken"
},
"split_keywords": [
"franken",
" molecular dynamics",
" potentials"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f2e910d9ce5ff82a8b5e78c433d26c642337fe4e46b784b951006c1aa05a4a5a",
"md5": "19984bb24a28e2debb5b2789b5327a74",
"sha256": "6b7dcb864ba04a3c4f4911793c9a334ef8146115c6a0a6af8f3e3000e5ab310b"
},
"downloads": -1,
"filename": "franken-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "19984bb24a28e2debb5b2789b5327a74",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 115937,
"upload_time": "2025-07-31T07:26:34",
"upload_time_iso_8601": "2025-07-31T07:26:34.971750Z",
"url": "https://files.pythonhosted.org/packages/f2/e9/10d9ce5ff82a8b5e78c433d26c642337fe4e46b784b951006c1aa05a4a5a/franken-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cbd71289067ca5e014489ce6bff66a6289f179b1303aea44b8e2b93d846a9a92",
"md5": "5fe53320def79182088bc420ada66a06",
"sha256": "5c275261080a9e603fd8d6dfdf0c752c497268c871aa740a37ef3b0bf9eca98e"
},
"downloads": -1,
"filename": "franken-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "5fe53320def79182088bc420ada66a06",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 108538,
"upload_time": "2025-07-31T07:26:36",
"upload_time_iso_8601": "2025-07-31T07:26:36.385035Z",
"url": "https://files.pythonhosted.org/packages/cb/d7/1289067ca5e014489ce6bff66a6289f179b1303aea44b8e2b93d846a9a92/franken-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 07:26:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CSML-IIT-UCL",
"github_project": "franken",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "franken"
}
JSON
