Metadata-Version: 2.4
Name: metatrain
Version: 2025.8.1
Summary: Training and evaluating machine learning models for atomistic systems.
Author: metatrain developers
License-Expression: BSD-3-Clause
Project-URL: homepage, https://metatensor.github.io/metatrain
Project-URL: documentation, https://metatensor.github.io/metatrain
Project-URL: repository, https://github.com/metatensor/metatrain
Project-URL: issues, https://github.com/metatensor/metatrain/issues
Project-URL: changelog, https://metatensor.github.io/metatrain/latest/dev-docs/changelog.html
Keywords: machine learning,molecular modeling
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: ase
Requires-Dist: metatensor-learn<0.4,>=0.3.2
Requires-Dist: metatensor-operations<0.4,>=0.3.3
Requires-Dist: metatensor-torch<0.8,>=0.7.6
Requires-Dist: metatomic-torch<0.2,>=0.1.0
Requires-Dist: jsonschema
Requires-Dist: omegaconf
Requires-Dist: python-hostlist
Requires-Dist: vesin
Provides-Extra: soap-bpnn
Requires-Dist: torch-spex<0.2,>=0.1; extra == "soap-bpnn"
Requires-Dist: wigners; extra == "soap-bpnn"
Provides-Extra: deprecated-pet
Requires-Dist: pet-neighbors-convert; extra == "deprecated-pet"
Requires-Dist: torch_geometric; extra == "deprecated-pet"
Requires-Dist: matscipy; extra == "deprecated-pet"
Requires-Dist: scikit-learn; extra == "deprecated-pet"
Requires-Dist: pathos; extra == "deprecated-pet"
Requires-Dist: scipy; extra == "deprecated-pet"
Provides-Extra: pet
Provides-Extra: nanopet
Provides-Extra: gap
Requires-Dist: featomic-torch<0.8,>=0.7; extra == "gap"
Requires-Dist: skmatter; extra == "gap"
Requires-Dist: scipy; extra == "gap"
Dynamic: license-file

metatrain
=========

.. image:: https://raw.githubusercontent.com/metatensor/metatrain/refs/heads/main/docs/src/logo/metatrain.svg
   :width: 200 px
   :align: left

|tests| |codecov| |docs|

.. 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 metatensor_ atomistic interface.

The idea behind ``metatrain`` is to have a general hub that provide an homogeneous
environment and user interface transforms every ML architecture in an end-to-end model
that can be connected to an MD engine. Any custom architecture compatible with
TorchScript_ can be integrated in ``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.

.. _TorchScript: https://pytorch.org/docs/stable/jit.html
.. _metatensor: https://docs.metatensor.org

.. marker-architectures

List of Implemented Architectures
---------------------------------

Currently ``metatrain`` supports the following architectures for building an atomistic
model.

.. list-table::
  :widths: 34 66
  :header-rows: 1

  * - 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 (*experimental*)
    - re-implementation of the original PET with slightly improved training and
      evaluation speed
  * - PET (*deprecated*)
    - Original implementation of the PET model used for prototyping,
      now deprecated in favor of the native metatrain PET implementation.
  * - SOAP BPNN
    - A Behler-Parrinello neural network with SOAP features

.. marker-documentation

Documentation
-------------

For details, tutorials, and examples, please have a look at our
`documentation <https://metatensor.github.io/metatrain/latest/>`_.

.. marker-installation

Installation
------------

You can install ``metatrain`` with pip:

.. code-block:: bash

    pip install metatrain

In addition, specific models must be installed by specifying the model name. For
example, to install the *SOAP-BPNN* model, you can run:

.. code-block:: bash

    pip install metatrain[soap-bpnn]

We also offer a conda installation:

.. code-block:: bash

    conda install -c conda-forge metatrain

The conda installation does not install model specific dependencies and will therefore
only work for architectures without optional dependencies such as ``NanoPET`` or
``PET``.

After installation you can then use ``mtt`` from the command line to train your models!

.. marker-quickstart

Quickstart
----------

To train a model, you can use the following command:

.. code-block:: bash

    mtt train options.yaml

Where ``options.yaml`` is a configuration file that specifies the training options. For
example, the following configuration file trains a *SOAP-BPNN* model on the QM9 dataset:

.. code-block:: 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 and taken for test set
    validation_set: 0.1 # 10 % of the training_set are randomly split and for validation set

.. marker-shell

Shell Completion
----------------

``metatrain`` comes with completion definitions for its commands for ``bash`` and
``zsh``. Since it is difficult to automatically configure shell completions in a robust
manner, you must manually configure your shell to enable its completion support.

To make the completions available, source the definitions as part of your shell's
startup. Add the following to your ``~/.bash_profile``, ``~/.zshrc`` (or, if they don't
exist, ``~/.profile``):

.. code-block:: bash

  source $(mtt --shell-completion)

.. marker-issues

Having problems or ideas?
-------------------------
Having a problem with metatrain? Please let us know by `submitting an issue
<https://github.com/metatensor/metatrain/issues>`_.

Submit new features or bug fixes through a `pull request
<https://github.com/metatensor/metatrain/pulls>`_.

.. marker-contributing

Contributors
------------
Thanks goes to all people that make ``metatrain`` possible:

.. image:: https://contrib.rocks/image?repo=metatensor/metatrain
  :target: https://github.com/metatensor/metatrain/graphs/contributors

.. |tests| image:: https://img.shields.io/github/checks-status/metatensor/metatrain/main
  :alt: Github Actions Tests Job Status
  :target: https://github.com/metatensor/metatrain/actions?query=branch%3Amain

.. |codecov| image:: https://codecov.io/gh/metatensor/metatrain/branch/main/graph/badge.svg
  :alt: Code coverage
  :target: https://codecov.io/gh/metatensor/metatrain

.. |docs| image:: https://img.shields.io/badge/📚_documentation-latest-sucess
  :alt: Documentation
  :target: https://metatensor.github.io/metatrain/latest
