From a69e8bf8422b7f67de842790bd5e6302664725e1 Mon Sep 17 00:00:00 2001 From: Philip Loche Date: Wed, 10 Dec 2025 08:39:52 +0100 Subject: [PATCH 1/3] Add GROMACS simulation engine --- docs/src/_prolog.rst | 5 + docs/src/engines/gromacs.rst | 216 ++++++++++++++++++++++ docs/src/engines/index.rst | 9 + docs/src/index.rst | 12 +- docs/src/outputs/energy.rst | 8 + docs/static/images/logo-gromacs-large.svg | 192 +++++++++++++++++++ docs/static/images/logo-gromacs.svg | 130 +++++++++++++ 7 files changed, 566 insertions(+), 6 deletions(-) create mode 100644 docs/src/engines/gromacs.rst create mode 100644 docs/static/images/logo-gromacs-large.svg create mode 100644 docs/static/images/logo-gromacs.svg diff --git a/docs/src/_prolog.rst b/docs/src/_prolog.rst index 26ae83f1..729cd0b7 100644 --- a/docs/src/_prolog.rst +++ b/docs/src/_prolog.rst @@ -68,6 +68,11 @@ :align: middle :alt: eOn +.. |gromacs-logo| image:: /../static/images/logo-gromacs-large.* + :height: 60px + :align: middle + :alt: GROMACS + .. |ipi-logo| image:: /../static/images/logo-ipi.* :height: 60px :align: middle diff --git a/docs/src/engines/gromacs.rst b/docs/src/engines/gromacs.rst new file mode 100644 index 00000000..59d003be --- /dev/null +++ b/docs/src/engines/gromacs.rst @@ -0,0 +1,216 @@ +.. _engine-gromacs: + +GROMACS +======= + +.. list-table:: + :header-rows: 1 + + * - Official website + - How is metatomic supported? + * - https://www.gromacs.org + - In a separate `fork `_ + +Supported model outputs +^^^^^^^^^^^^^^^^^^^^^^^ + +The :ref:`energy ` is supported in the custom metatomic module in +GROMACS. The module allows running molecular dynamics simulations on the full system or +on a subgroup (ML/MM) with interatomic potentials in the metatomic format. + +How to install the code +^^^^^^^^^^^^^^^^^^^^^^^ + +Building from sources +--------------------- + +The code is available in a custom fork of GROMACS, and you can get it with + +.. code-block:: bash + + git clone https://github.com/metatensor/gromacs gromacs-metatomic + cd gromacs-metatomic + +You'll need to provide some of the code dependencies yourself. There are +multiple ways to go about it, here we detail a fully manual installation, an +installation using ``conda`` and an installation using ``pip``. + +Option 1: dependencies from ``conda`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All the dependencies of the code are available on ``conda``, you can install +them with + +.. code-block:: bash + + # create an environment (you can also re-use an existing one) + conda create -n gromacs-metatomic + conda activate gromacs-metatomic + + conda install -c metatensor -c conda-forge libmetatomic-torch + + # Store this information to configure cmake down the line + CMAKE_PREFIX_PATH="$CONDA_PREFIX" + + +Option 2: dependencies from ``pip`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All the dependencies of the code are also available on ``PyPI``, you can install +them with + +.. code-block:: bash + + # (optional) create an environment with your preferred method + ... + + python -m pip install metatomic-torch + + # on linux, if you don't have a GPU available, you should force the use of + # CPU-only torch instead + python -m pip install --extra-index-url=https://download.pytorch.org/whl/cpu metatomic-torch + + # Get the information to configure cmake down the line + TORCH_PREFIX=$(python -c "import torch; print(torch.utils.cmake_prefix_path)") + MTS_PREFIX=$(python -c "import metatensor; print(metatensor.utils.cmake_prefix_path)") + MTS_TORCH_PREFIX=$(python -c "import metatensor.torch; print(metatensor.torch.utils.cmake_prefix_path)") + MTA_TORCH_PREFIX=$(python -c "import metatomic.torch; print(metatomic.torch.utils.cmake_prefix_path)") + + CMAKE_PREFIX_PATH="$TORCH_PREFIX;$MTS_PREFIX;$MTS_TORCH_PREFIX;$MTA_TORCH_PREFIX" + + +Option 3: manual dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You'll need to build or download the the C++ version of ``libtorch``. You can +download it from https://pytorch.org/get-started/locally/, using the C++ +language selector. Once you have it downloaded, extract the archive somewhere, +and record the path: + +.. code-block:: bash + + # point this to the path where you extracted the C++ libtorch + TORCH_PREFIX= + +For the other dependencies, you'll either need to install them yourself +following the links below, or let ``cmake`` download and build the latest +compatible versions: + +- :external+metatensor:ref:`metatensor ` +- :external+metatensor:ref:`metatensor-torch ` +- :ref:`metatomic-torch ` + +If you want to provide these yourself, you'll need to also record the +corresponding installation paths: + +.. code-block:: bash + + MTS_PREFIX= + MTS_TORCH_PREFIX= + MTA_TORCH_PREFIX= + +And finally you can store this information to configure cmake down the line: + +.. code-block:: bash + + CMAKE_PREFIX_PATH="$TORCH_PREFIX;$MTS_PREFIX;$MTS_TORCH_PREFIX;$MTA_TORCH_PREFIX" + +Building the code +~~~~~~~~~~~~~~~~~ + +After installing the dependencies with one of the options above, you can +configure the build with: + +.. code-block:: bash + + mkdir build && cd build + + # you can add more options here to enable other packages. + cmake .. \ + -DCMAKE_PREFIX_PATH="$CMAKE_PREFIX_PATH" \ + -DTorch_DIR=$TORCH_PREFIX \ + -DGMX_METATOMIC=ON \ + -DDOWNLOAD_VESIN=ON + + cmake --build . --parallel 4 # or `make -jX` + + # optionally install the code on your machine. You can also directly use + # the `lmp` binary in `gromacs-metatomic/build/lmp` without installation + cmake --build . --target install # or `make install` + +How to use the code +^^^^^^^^^^^^^^^^^^^ + +.. note:: + + Here we assume you already have an exported model that you want to use in + your simulations. Please see :ref:`this tutorial + ` to learn how to manually create and export a + model; or use a tool like `metatrain`_ to create a model based on existing + architectures and your own dataset. + + .. _metatrain: https://github.com/metatensor/metatrain + +After building and optionally installing the code, you can now use metatomic module in +your GROMACS MDP files! Below are the reference documentation + +.. code-block:: shell + + pair_style metatomic model_path ... keyword values ... + +* ``model_path`` = path to the file containing the exported metatomic model +* ``keyword`` = **device** or **extensions** or **check_consistency** + + .. parsed-literal:: + + **metatomic-active** yes or no + set this to yes to activate the metatomic potential, or no to disable it. + **metatomic-input_group** + name of the input group to use for the metatomic potential. To couple the whole + system use "System". + **metatomic-model** + path to the file containing the exported metatomic model. + **metatomic-device** cpu or cuda + device to use to run the model. If not given, the best available device + will be used. + +Sample input file +----------------- + +Below is a example input file for an ML/MM simulation of an alanin dipeptide in water, +using a metatomic model for the peptide and a classical force field for the water +molecules. For a detailed example we refer to the `chapter in the atomistic cookbook +`_. + +.. code-block:: ini + + ; Run control + integrator = md + dt = 0.0005 + nsteps = 500 + + ; Output control + nstxout = 10 + nstvout = 10 + nstenergy = 10 + nstcalcenergy = 10 + nstlog = 10 + + ; Neighborsearching + cutoff-scheme = Verlet + pbc = xyz + + ; Electrostatics + coulombtype = PME + + ; Temperature coupling + tcoupl = v-rescale + tc-grps = water protein ; two coupling groups - more accurate + tau-t = 2.0 2.0 ; time constant, in ps + ref-t = 300 300 + + ; Metatomic interface + metatomic-active = yes + metatomic-input-group = protein ; the group on which ML forces are applied + metatomic-modelfile = model.pt ; path to the model file + metatomic-device = cpu ; device to run the model on (cpu or cuda) diff --git a/docs/src/engines/index.rst b/docs/src/engines/index.rst index dabda0d6..94bb73c4 100644 --- a/docs/src/engines/index.rst +++ b/docs/src/engines/index.rst @@ -46,6 +46,14 @@ add it here! :width: 150px :align: center + .. grid-item-card:: GROMACS + :link: engine-gromacs + :link-type: ref + + .. image:: /../static/images/logo-gromacs.* + :width: 150px + :align: center + .. grid-item-card:: i-PI :link: engine-ipi :link-type: ref @@ -86,6 +94,7 @@ add it here! ase chemiscope eon + gromacs ipi lammps plumed diff --git a/docs/src/index.rst b/docs/src/index.rst index d41b2501..955faa84 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -6,12 +6,12 @@ :class: only-dark sd-mb-4 :width: 600px -``metatomic`` is a library that defines a common interface between atomistic -machine learning models, and atomistic simulation engines. Our main goal is to -define and train models once, and then be able to re-use them across many -different simulation engines (such as LAMMPS, PLUMED, *etc.*). We strive to -achieve this goal without imposing any structure on the model itself, and to -allow any model architecture to be used. +``metatomic`` is a library that defines a common interface between atomistic machine +learning models, and atomistic simulation engines. Our main goal is to define and train +models once, and then be able to re-use them across many different simulation engines +(such as LAMMPS, GROMACS, PLUMED, *etc.*). We strive to achieve this goal without +imposing any structure on the model itself, and to allow any model architecture to be +used. This library focuses on exporting and importing fully working, already trained models. If you want to train existing architectures with new data or re-use diff --git a/docs/src/outputs/energy.rst b/docs/src/outputs/energy.rst index e16bf3e2..7892c8e9 100644 --- a/docs/src/outputs/energy.rst +++ b/docs/src/outputs/energy.rst @@ -52,6 +52,14 @@ The following simulation engines can use the ``"energy"`` output: |ase-logo| + .. grid-item-card:: + :text-align: center + :padding: 1 + :link: engine-lammps + :link-type: ref + + |gromacs-logo| + .. grid-item-card:: :text-align: center :padding: 1 diff --git a/docs/static/images/logo-gromacs-large.svg b/docs/static/images/logo-gromacs-large.svg new file mode 100644 index 00000000..96d075cd --- /dev/null +++ b/docs/static/images/logo-gromacs-large.svg @@ -0,0 +1,192 @@ + +image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/static/images/logo-gromacs.svg b/docs/static/images/logo-gromacs.svg new file mode 100644 index 00000000..a902d69d --- /dev/null +++ b/docs/static/images/logo-gromacs.svg @@ -0,0 +1,130 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + From 1ecf28288933f55396b71ea26bb5bc52404796b9 Mon Sep 17 00:00:00 2001 From: Philip Loche Date: Wed, 10 Dec 2025 22:32:28 +0100 Subject: [PATCH 2/3] Update energy.rst Co-authored-by: Guillaume Fraux --- docs/src/outputs/energy.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/outputs/energy.rst b/docs/src/outputs/energy.rst index 7892c8e9..de7a97f6 100644 --- a/docs/src/outputs/energy.rst +++ b/docs/src/outputs/energy.rst @@ -55,7 +55,7 @@ The following simulation engines can use the ``"energy"`` output: .. grid-item-card:: :text-align: center :padding: 1 - :link: engine-lammps + :link: engine-gromacs :link-type: ref |gromacs-logo| From 1f52f3cdc3e7681cfe3e16284ddf05088978f52a Mon Sep 17 00:00:00 2001 From: Philip Loche Date: Tue, 13 Jan 2026 11:00:24 +0100 Subject: [PATCH 3/3] Update instructions --- docs/src/engines/gromacs.rst | 54 +++++++++++++++++++++++------------ docs/src/outputs/energy.rst | 14 ++++----- docs/src/outputs/variants.rst | 18 ++++++++---- 3 files changed, 55 insertions(+), 31 deletions(-) diff --git a/docs/src/engines/gromacs.rst b/docs/src/engines/gromacs.rst index 59d003be..36b3e5dd 100644 --- a/docs/src/engines/gromacs.rst +++ b/docs/src/engines/gromacs.rst @@ -125,19 +125,25 @@ configure the build with: mkdir build && cd build - # you can add more options here to enable other packages. + # you can add more options here. cmake .. \ - -DCMAKE_PREFIX_PATH="$CMAKE_PREFIX_PATH" \ - -DTorch_DIR=$TORCH_PREFIX \ - -DGMX_METATOMIC=ON \ - -DDOWNLOAD_VESIN=ON + -DCMAKE_PREFIX_PATH="$CMAKE_PREFIX_PATH" \ + -DTorch_DIR=$TORCH_PREFIX \ + -DGMX_METATOMIC=AUTO cmake --build . --parallel 4 # or `make -jX` # optionally install the code on your machine. You can also directly use - # the `lmp` binary in `gromacs-metatomic/build/lmp` without installation + # the `gmx` binary in `gromacs-metatomic/build/bin/gmx` without installation cmake --build . --target install # or `make install` +By default, ``cmake`` will try to find the ``metatensor`` and ``metatomic`` +libraries on your system and use them. If it can not find the libraries, it will +download and build them as part of the main GROMACS build. You can control this +behavior by adding ``-DDOWNLOAD_METATENSOR=ON`` and ``-DDOWNLOAD_METATOMIC=ON`` +to the ``cmake`` options to always force a download; or prevent any download by +setting these options to ``OFF``. + How to use the code ^^^^^^^^^^^^^^^^^^^ @@ -151,28 +157,38 @@ How to use the code .. _metatrain: https://github.com/metatensor/metatrain -After building and optionally installing the code, you can now use metatomic module in -your GROMACS MDP files! Below are the reference documentation - -.. code-block:: shell - - pair_style metatomic model_path ... keyword values ... - -* ``model_path`` = path to the file containing the exported metatomic model -* ``keyword`` = **device** or **extensions** or **check_consistency** +After building and optionally installing the code, you can now use metatomic +module in your GROMACS molecular dynamics parameter (MDP) files! Below are the +reference options .. parsed-literal:: **metatomic-active** yes or no set this to yes to activate the metatomic potential, or no to disable it. - **metatomic-input_group** + **metatomic-input-group** name of the input group to use for the metatomic potential. To couple the whole system use "System". - **metatomic-model** + **metatomic-model** path to the file containing the exported metatomic model. + **metatomic-extensions** + path to a directory containing TorchScript extensions as shared libraries. If + the model uses extensions, we will try to load them from this directory first **metatomic-device** cpu or cuda - device to use to run the model. If not given, the best available device - will be used. + device to use to run the model. If not given, the best available device will be + used. + **metatomic-check-consistency** yes or no + if yes, the code will check that the model is consistent with the system + topology at the start of the simulation. This can help catch errors due to + mismatched atom ordering between the model and the system, but it comes at a + performance cost. + **metatomic-variant** no or + specifies which variant of the model outputs should be uses for making + predictions. Defaults to no variant. + +.. note:: + + The device can also be overridden at runtime by setting the environment + variable ``GMX_METATOMIC_DEVICE`` to a value. Sample input file ----------------- diff --git a/docs/src/outputs/energy.rst b/docs/src/outputs/energy.rst index de7a97f6..a8f8fa93 100644 --- a/docs/src/outputs/energy.rst +++ b/docs/src/outputs/energy.rst @@ -55,27 +55,27 @@ The following simulation engines can use the ``"energy"`` output: .. grid-item-card:: :text-align: center :padding: 1 - :link: engine-gromacs + :link: engine-eon :link-type: ref - |gromacs-logo| + |eon-logo| + |eon-logo-dark| .. grid-item-card:: :text-align: center :padding: 1 - :link: engine-ipi + :link: engine-gromacs :link-type: ref - |ipi-logo| + |gromacs-logo| .. grid-item-card:: :text-align: center :padding: 1 - :link: engine-eon + :link: engine-ipi :link-type: ref - |eon-logo| - |eon-logo-dark| + |ipi-logo| .. grid-item-card:: :text-align: center diff --git a/docs/src/outputs/variants.rst b/docs/src/outputs/variants.rst index 10816e19..89a14eb8 100644 --- a/docs/src/outputs/variants.rst +++ b/docs/src/outputs/variants.rst @@ -40,10 +40,19 @@ The following simulation engines can use variants for all their supported output .. grid-item-card:: :text-align: center :padding: 1 - :link: engine-lammps + :link: engine-eon :link-type: ref - |lammps-logo| + |eon-logo| + |eon-logo-dark| + + .. grid-item-card:: + :text-align: center + :padding: 1 + :link: engine-gromacs + :link-type: ref + + |gromacs-logo| .. grid-item-card:: :text-align: center @@ -56,8 +65,7 @@ The following simulation engines can use variants for all their supported output .. grid-item-card:: :text-align: center :padding: 1 - :link: engine-eon + :link: engine-lammps :link-type: ref - |eon-logo| - |eon-logo-dark| + |lammps-logo|