PET Finetuning recipe (#134)

An example of both standard and conservative fine-tuning for PET models

---------

Co-authored-by: Michele Ceriotti <michele.ceriotti@gmail.com>
Co-authored-by: Sofiia Chorna <chernaya.sofiia@gmail.com>
Co-authored-by: Sofiia Chorna <71195115+sofiia-chorna@users.noreply.github.com>

Author: 3 people

INSTALLING.rst

@@ -62,7 +62,7 @@ you should run
    pip install ipykernel # in case is not part of the environment
    
    # Create the kernel definition
-   python -m ipykernel install --user --name recipei-env-path --display-name "Python (recipe)"
+   python -m ipykernel install --user --name recipe-env-path --display-name "Python (recipe)"
    
    # You can launch Jupyter from outside the conda environment,
    # unless you also need conda-installed executables. When you open

docs/src/software/metatensor.sec

@@ -14,6 +14,8 @@ training and evaluating ML models.
 - examples/learn-tensors-with-mcov/learn-tensors-with-mcov
 - examples/pet-mad/pet-mad
 - examples/pet-mad-nc/pet-mad-nc
+- examples/pet-finetuning/pet-ft
+- examples/pet-finetuning/pet-ft-nc
 - examples/flashmd/flashmd-demo
 - examples/shiftml/shiftml-example
 - examples/hamiltonian-qm7/hamiltonian-qm7

docs/src/topics/ml-models.sec

@@ -13,6 +13,8 @@ data.
 - examples/learn-tensors-with-mcov/learn-tensors-with-mcov
 - examples/pet-mad/pet-mad
 - examples/pet-mad-nc/pet-mad-nc
+- examples/pet-finetuning/pet-ft
+- examples/pet-finetuning/pet-ft-nc
 - examples/flashmd/flashmd-demo
 - examples/shiftml/shiftml-example
 - examples/hamiltonian-qm7/hamiltonian-qm7

examples/pet-finetuning/.gitignore

@@ -0,0 +1,15 @@
+*.data
+*.pt
+*.ckpt
+log.lammps
+trajectory.xyz
+tmp*
+
+extensions/*
+
+outputs/
+data/ethanol_train.xyz
+data/ethanol_val.xyz
+data/ethanol_test.xyz
+data/ethanol_corrected.xyz
+output.xyz

examples/pet-finetuning/README.rst

@@ -0,0 +1,4 @@
+PET-MAD finetuning tutorial
+===========================
+
+An example of finetuning the PET-MAD universal machine-learning potential.

examples/pet-finetuning/c_ft_options.yaml

@@ -0,0 +1,62 @@
+seed: 42
+
+architecture:
+  name: pet
+  training:
+    num_epochs: 20
+    num_epochs_warmup: 1
+    learning_rate: 1e-4
+
+training_set:
+  systems:
+    read_from: data/ethanol_train.xyz
+    length_unit: angstrom
+  targets:
+    energy:
+      key: energy
+      unit: eV
+      forces: on
+    non_conservative_forces:
+      key: forces
+      quantity: force
+      unit: eV/A
+      type:
+        cartesian:
+          rank: 1
+      per_atom: true
+
+validation_set:
+  systems: 
+    read_from: data/ethanol_val.xyz
+    length_unit: angstrom
+  targets:
+    energy:
+      key: energy
+      unit: eV
+      forces: on
+    non_conservative_forces:
+      key: forces
+      quantity: force
+      unit: eV/A
+      type:
+        cartesian:
+          rank: 1
+      per_atom: true
+
+test_set:
+  systems: 
+    read_from: data/ethanol_test.xyz
+    length_unit: angstrom
+  targets:
+    energy:
+      key: energy
+      unit: eV
+      forces: on
+    non_conservative_forces:
+      key: forces
+      quantity: force
+      unit: eV/A
+      type:
+        cartesian:
+          rank: 1
+      per_atom: true

examples/pet-finetuning/c_ft_res.png

@@ -0,0 +1,11 @@
+channels:
+  - metatensor
+  - conda-forge
+dependencies:
+  - python=3.12
+  - pip
+  - pip:
+    - ase>=3.23
+    - metatrain[pet]>=2025.8,<2026
+    - matplotlib
+    - scikit-learn

examples/pet-finetuning/data/ethanol.xyz

@@ -0,0 +1,39 @@
+seed: 42
+
+architecture:
+  name: pet
+
+  training:
+    batch_size: 16
+    num_epochs: 50
+    num_epochs_warmup: 10
+    learning_rate: 1e-4
+    
+
+# this needs specifying based on the specific dataset
+training_set:
+  systems: 
+    read_from: "data/ethanol_train.xyz"  # path to the finetuning dataset
+    length_unit: angstrom
+  targets:
+    energy:
+      key: "energy-corrected"  # name of the target value
+      unit: "eV"
+
+validation_set:
+  systems: 
+    read_from: "data/ethanol_val.xyz"
+    length_unit: angstrom
+  targets:
+    energy:
+      key: "energy-corrected"
+      unit: "eV"
+
+test_set:
+  systems: 
+    read_from: "data/ethanol_test.xyz"
+    length_unit: angstrom
+  targets:
+    energy:
+      key: "energy-corrected"
+      unit: "eV"