<h1 align="center">
<img src="https://raw.githubusercontent.com/metatensor/metatrain/refs/heads/main/docs/src/logo/metatrain-horizontal-dark.svg" alt="Metatensor logo" width="600"/>
</h1>
<h4 align="center">
[](https://github.com/metatensor/metatrain/actions?query=branch%3Amain)
[](https://metatensor.github.io/metatrain)
[](https://codecov.io/gh/metatensor/metatrain)
</h4>
<!-- marker-introduction -->
`metatrain` is a command line interface (CLI) to **train** and **evaluate** atomistic
models of various architectures. It features a common `yaml` option inputs to configure
training and evaluation. Trained models are exported as standalone files that can be
used directly in various molecular dynamics (MD) engines (e.g. `LAMMPS`, `i-PI`, `ASE`
...) using the [metatomic](https://docs.metatensor.org/metatomic) interface.
The idea behind `metatrain` is to have a general hub that provides a homogeneous
environment and user interface, transforming every ML architecture into an end-to-end
model that can be connected to an MD engine. Any custom architecture compatible with
[TorchScript](https://pytorch.org/docs/stable/jit.html) can be integrated into
`metatrain`, gaining automatic access to a training and evaluation interface, as well as
compatibility with various MD engines.
> **Note**: `metatrain` does not provide mathematical functionalities *per se*, but
> relies on external models that implement the various architectures.
<!-- marker-architectures -->
# List of Implemented Architectures
Currently `metatrain` supports the following architectures for building an atomistic
model:
| Name | Description |
|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| GAP | Sparse Gaussian Approximation Potential (GAP) using Smooth Overlap of Atomic Positions (SOAP). |
| PET | Point Edge Transformer (PET), interatomic machine learning potential |
| NanoPET *(deprecated)* | Re-implementation of the original PET with slightly improved training and evaluation speed |
| SOAP BPNN | A Behler-Parrinello neural network with SOAP features |
| FlashMD | An architecture for the direct prediction of molecular dynamics |
<!-- marker-documentation -->
# Documentation
For details, tutorials, and examples, please visit our
[documentation](https://metatensor.github.io/metatrain/latest/).
<!-- marker-installation -->
# Installation
Install `metatrain` with pip:
```bash
pip install metatrain
```
Install specific models by specifying the model name. For example, to install the SOAP-BPNN model:
```bash
pip install metatrain[soap-bpnn]
```
We also offer a conda installation:
```bash
conda install -c conda-forge metatrain
```
> ⚠️ The conda installation does not install model-specific dependencies and will only
> work for architectures without optional dependencies such as PET.
After installation, you can use mtt from the command line to train your models!
<!-- marker-quickstart -->
# Quickstart
To train a model, use the following command:
```bash
mtt train options.yaml
```
Where options.yaml is a configuration file specifying training options. For example, the
following configuration trains a *SOAP-BPNN* model on the QM9 dataset:
```yaml
# architecture used to train the model
architecture:
name: soap_bpnn
training:
num_epochs: 5 # a very short training run
# Mandatory section defining the parameters for system and target data of the training set
training_set:
systems: "qm9_reduced_100.xyz" # file where the positions are stored
targets:
energy:
key: "U0" # name of the target value
unit: "eV" # unit of the target value
test_set: 0.1 # 10% of the training_set are randomly split for test
validation_set: 0.1 # 10% of the training_set are randomly split for validation
```
<!-- marker-shell -->
# Shell Completion
`metatrain` comes with completion definitions for its commands for bash and zsh. You
must manually configure your shell to enable completion support.
To make the completions available, source the definitions in your shell’s startup file
(e.g., `~/.bash_profile`, `~/.zshrc`, or `~/.profile`):
```bash
source $(mtt --shell-completion)
```
<!-- marker-issues -->
# Having problems or ideas?
Having a problem with metatrain? Please let us know by submitting an issue.
Submit new features or bug fixes through a pull request.
<!-- marker-contributing -->
# Contributors
Thanks goes to all people who make metatrain possible:
[](https://github.com/metatensor/metatrain/graphs/contributors)
# Citing metatrain
If you found ``metatrain`` useful, you can cite its pre-print
(<https://doi.org/10.48550/arXiv.2508.15704>) as
```
@misc{metatrain,
title = {Metatensor and Metatomic: Foundational Libraries for Interoperable Atomistic
Machine Learning},
shorttitle = {Metatensor and Metatomic},
author = {Bigi, Filippo and Abbott, Joseph W. and Loche, Philip and Mazitov, Arslan
and Tisi, Davide and Langer, Marcel F. and Goscinski, Alexander and Pegolo, Paolo
and Chong, Sanggyu and Goswami, Rohit and Chorna, Sofiia and Kellner, Matthias and
Ceriotti, Michele and Fraux, Guillaume},
year = {2025},
month = aug,
publisher = {arXiv},
doi = {10.48550/arXiv.2508.15704},
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "metatrain",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "machine learning, molecular modeling",
"author": "metatrain developers",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9a/22/cd9952fcaec347a9283cc3ba308ebee3aadf409d32812e05e82ce04ceb1a/metatrain-2025.11.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">\n <img src=\"https://raw.githubusercontent.com/metatensor/metatrain/refs/heads/main/docs/src/logo/metatrain-horizontal-dark.svg\" alt=\"Metatensor logo\" width=\"600\"/>\n</h1>\n\n<h4 align=\"center\">\n\n[](https://github.com/metatensor/metatrain/actions?query=branch%3Amain)\n[](https://metatensor.github.io/metatrain)\n[](https://codecov.io/gh/metatensor/metatrain)\n</h4>\n\n<!-- marker-introduction -->\n\n`metatrain` is a command line interface (CLI) to **train** and **evaluate** atomistic\nmodels of various architectures. It features a common `yaml` option inputs to configure\ntraining and evaluation. Trained models are exported as standalone files that can be\nused directly in various molecular dynamics (MD) engines (e.g. `LAMMPS`, `i-PI`, `ASE`\n...) using the [metatomic](https://docs.metatensor.org/metatomic) interface.\n\nThe idea behind `metatrain` is to have a general hub that provides a homogeneous\nenvironment and user interface, transforming every ML architecture into an end-to-end\nmodel that can be connected to an MD engine. Any custom architecture compatible with\n[TorchScript](https://pytorch.org/docs/stable/jit.html) can be integrated into\n`metatrain`, gaining automatic access to a training and evaluation interface, as well as\ncompatibility with various MD engines.\n\n> **Note**: `metatrain` does not provide mathematical functionalities *per se*, but\n> relies on external models that implement the various architectures.\n\n<!-- marker-architectures -->\n\n# List of Implemented Architectures\n\nCurrently `metatrain` supports the following architectures for building an atomistic\nmodel:\n\n| Name | Description |\n|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------|\n| GAP | Sparse Gaussian Approximation Potential (GAP) using Smooth Overlap of Atomic Positions (SOAP). |\n| PET | Point Edge Transformer (PET), interatomic machine learning potential |\n| NanoPET *(deprecated)* | Re-implementation of the original PET with slightly improved training and evaluation speed |\n| SOAP BPNN | A Behler-Parrinello neural network with SOAP features |\n| FlashMD | An architecture for the direct prediction of molecular dynamics |\n\n<!-- marker-documentation -->\n\n# Documentation\n\nFor details, tutorials, and examples, please visit our\n[documentation](https://metatensor.github.io/metatrain/latest/).\n\n<!-- marker-installation -->\n\n# Installation\n\nInstall `metatrain` with pip:\n\n```bash\npip install metatrain\n```\n\nInstall specific models by specifying the model name. For example, to install the SOAP-BPNN model:\n\n```bash\npip install metatrain[soap-bpnn]\n```\n\nWe also offer a conda installation:\n\n```bash\nconda install -c conda-forge metatrain\n```\n\n> \u26a0\ufe0f The conda installation does not install model-specific dependencies and will only\n> work for architectures without optional dependencies such as PET.\n\nAfter installation, you can use mtt from the command line to train your models!\n\n<!-- marker-quickstart -->\n\n# Quickstart\n\nTo train a model, use the following command:\n\n```bash\nmtt train options.yaml\n```\n\nWhere options.yaml is a configuration file specifying training options. For example, the\nfollowing configuration trains a *SOAP-BPNN* model on the QM9 dataset:\n\n```yaml\n# architecture used to train the model\narchitecture:\n name: soap_bpnn\ntraining:\n num_epochs: 5 # a very short training run\n\n# Mandatory section defining the parameters for system and target data of the training set\ntraining_set:\n systems: \"qm9_reduced_100.xyz\" # file where the positions are stored\n targets:\n energy:\n key: \"U0\" # name of the target value\n unit: \"eV\" # unit of the target value\n\ntest_set: 0.1 # 10% of the training_set are randomly split for test\nvalidation_set: 0.1 # 10% of the training_set are randomly split for validation\n```\n\n<!-- marker-shell -->\n\n# Shell Completion\n\n`metatrain` comes with completion definitions for its commands for bash and zsh. You\nmust manually configure your shell to enable completion support.\n\nTo make the completions available, source the definitions in your shell\u2019s startup file\n(e.g., `~/.bash_profile`, `~/.zshrc`, or `~/.profile`):\n\n```bash\nsource $(mtt --shell-completion)\n```\n\n<!-- marker-issues -->\n\n# Having problems or ideas?\n\nHaving a problem with metatrain? Please let us know by submitting an issue.\n\nSubmit new features or bug fixes through a pull request.\n\n<!-- marker-contributing -->\n\n# Contributors\n\nThanks goes to all people who make metatrain possible:\n\n[](https://github.com/metatensor/metatrain/graphs/contributors)\n\n# Citing metatrain\n\nIf you found ``metatrain`` useful, you can cite its pre-print\n(<https://doi.org/10.48550/arXiv.2508.15704>) as\n\n```\n@misc{metatrain,\ntitle = {Metatensor and Metatomic: Foundational Libraries for Interoperable Atomistic\nMachine Learning},\nshorttitle = {Metatensor and Metatomic},\nauthor = {Bigi, Filippo and Abbott, Joseph W. and Loche, Philip and Mazitov, Arslan\nand Tisi, Davide and Langer, Marcel F. and Goscinski, Alexander and Pegolo, Paolo\nand Chong, Sanggyu and Goswami, Rohit and Chorna, Sofiia and Kellner, Matthias and\nCeriotti, Michele and Fraux, Guillaume},\nyear = {2025},\nmonth = aug,\npublisher = {arXiv},\ndoi = {10.48550/arXiv.2508.15704},\n}\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Training and evaluating machine learning models for atomistic systems.",
"version": "2025.11",
"project_urls": {
"changelog": "https://metatensor.github.io/metatrain/latest/dev-docs/changelog.html",
"documentation": "https://metatensor.github.io/metatrain",
"homepage": "https://metatensor.github.io/metatrain",
"issues": "https://github.com/metatensor/metatrain/issues",
"repository": "https://github.com/metatensor/metatrain"
},
"split_keywords": [
"machine learning",
" molecular modeling"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3f87479deeffe709e33832b0733da4a42bb832788def9a1b2cf889c34077da2b",
"md5": "9f84df8caf3aea1e003b88294343fcd3",
"sha256": "2cf770b21ede10753b2edd8a3fea30d3729fa9b043222b5bb549348cc9d0e643"
},
"downloads": -1,
"filename": "metatrain-2025.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9f84df8caf3aea1e003b88294343fcd3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 20351445,
"upload_time": "2025-10-21T09:28:36",
"upload_time_iso_8601": "2025-10-21T09:28:36.340883Z",
"url": "https://files.pythonhosted.org/packages/3f/87/479deeffe709e33832b0733da4a42bb832788def9a1b2cf889c34077da2b/metatrain-2025.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9a22cd9952fcaec347a9283cc3ba308ebee3aadf409d32812e05e82ce04ceb1a",
"md5": "0954fe5fbd1e278086262321068020fa",
"sha256": "4c1a78feb359885f29d659f97ccf0e0676892ba1aa120cf58d0c7a0442161255"
},
"downloads": -1,
"filename": "metatrain-2025.11.tar.gz",
"has_sig": false,
"md5_digest": "0954fe5fbd1e278086262321068020fa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 20293038,
"upload_time": "2025-10-21T09:28:39",
"upload_time_iso_8601": "2025-10-21T09:28:39.687712Z",
"url": "https://files.pythonhosted.org/packages/9a/22/cd9952fcaec347a9283cc3ba308ebee3aadf409d32812e05e82ce04ceb1a/metatrain-2025.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 09:28:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "metatensor",
"github_project": "metatrain",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "metatrain"
}
JSON
