M3GNet: Universal ML Potential
******************************

MLPotential M3GNet Cohesive energy D3 dispersion engine addon

**Note**: This tutorial requires AMS2023 or later.

**This tutorial will teach you how to**:

* Download and install the **M3GNet-UP-2022 machine learning (ML)
  potential** [1] for the entire periodic table, especially suitable
  for organic and inorganic crystal materials. M3GNet-UP-2022 was
  fitted to PBE reference data.

* Use the **D3 Dispersion Engine Addon** to add Grimme's D3 dispersion
  to the energy, forces, and stress tensors.

* Calculate the cohesive energy (heat of sublimation) of the molecular
  naphthalene crystal.

[image]

See also:

  * MLPotential documentation

  * Machine Learning Thermochemistry

  * Crystals and Surfaces

Note:

  M3GNet can also be applied to inorganic crystals like metals and
  metal oxides.


Install M3GNet
==============

First, make sure to install the M3GNet package inside AMS.

   Open the package manager: **SCM → Packages**
   Find **MG3Net** and (if you have not yet installed it) click **Install**
 [image]


Cohesive energy
===============

To calculate the cohesive energy of solid naphthalene, you need to
calculate the energy of

* a single naphthalene molecule in the gasphase

* the naphthalene crystal

The naphthalene crystal unit cell contains two naphthalene molecules,
so ultimately we want to calculate the reaction energy

   E_{\textrm{coh}} = \frac{ 2 E_{\textrm{gas}} - E_{\textrm{crystal}}
   }{2}


Gasphase naphthalene
====================

   Open AMSinput: **SCM → New input**
   Switch to ML potential: [image: ADFPanel][image] → [image: MLPotentialPanel][image]
   Set the **Task** to **Geometry Optimization**
   Set the **Model** to **M3GNet → M3GNet-UP-2022** (UP = Universal Potential)
   **File → Import system** and select "naphthalene_gas.xyz"
 [image]

To add D3(BJ) dispersion corrections:

   Go to **Details → Engine Add-ons**
   Under **D3 Dispersion**, tick **Yes**

Note:

  In previous AMS versions, the engine addons could be found on the
  Details → Expert AMS panel.

[image]

If you have a CUDA-enabled GPU, then you can go to the **Details →
Technical** panel and set **Device** to **cuda:0**. However, for a
small system like naphthalene, running on a GPU does not provide
significant speedup (in practice, the D3 dispersion calculation is
about as computationally expensive as the M3GNet calculation).

[image]

Then save and run the job:

   1. Select **File → Save** and name it, e.g., "naphthalene_gas.ams"
   2. Click on **File → Run**


Crystalline naphthalene
=======================

Set up crystalline naphthalene exactly as the gasphase calculation,
with two exceptions:

   Import "naphthalene_crystal.xyz" instead
   On the **Details → GeometryOptimization** panel, set **Optimize lattice → Yes**.
 [image]

   Make sure the D3Dispersion is set as before

Some of the molecules cross the periodic boundaries, so that the atoms
in the same molecule are shown on different sides of the unit cell.
This can be confusing. AMSinput offers two ways to make the
visualization easier:

   Set **View → Periodic → Periodic View Type → View Outside**
   Click on [image: PeriodicViewTool][image] to toggle on/off periodic view

This shows some periodic replicas of atoms that are "just outside" the
unit cell, but does not change any atomic positions.

[image]

Alternatively, you can move the atoms so that all molecules are shown
intact (thus placing some atoms outside the unit cell):

   Set **Edit → Crystal → Map Molecules Complete**
 [image]

It is up to you if you prefer to have the molecules split across the
unit cell or not. It makes no difference to the calculation.

Now save with a new name and run the job:

   1. Select **File → Save** and name it, e.g., "naphthalene_crystal.ams"
   2. Click on **File → Run**


Lattice optimization results
============================

The easiest way to get the optimized lattice parameters is to generate
a spreadsheet report:

   Select the finished job in AMSjobs
   **Tools → Build Spreadsheet... → Do it**

The optimized cell lengths and angles are shown on the left-hand side.

[image]

Note:

  If you open then spreadsheet with **LibreOffice**, you may have to
  press **shift+ctrl+f9** to evaluate formulas

You can also view the optimized structure in AMSmovie.


Calculate cohesive energy
=========================

Collect the energies from the gasphase and crystal calculations,
either from a spreadsheet as above or by scrolling down towards the
end of the .out file (**SCM → Output**).

See also: 10 Ways to Get the Energy and Other Properties

You should get E_gas = -4.41213477 Ha and E_crystal = -8.89238031 Ha,
giving E_coh = 0.03406 Ha = **89 kJ/mol**.

This compares well to PBE-TS numbers (TS is a different type of
dispersion correction) reported by Al-Saidi et al  [2]:

+-----------------------------------+-----------------------------------+-----------------------------------+
| property                          | PBE-TS [2]                        | M3GNet-D3(BJ)                     |
+-----------------------------------+-----------------------------------+-----------------------------------+
| E_coh (kJ/mol)                    | 95                                | 89                                |
+-----------------------------------+-----------------------------------+-----------------------------------+
| a (Å)                             | 8.01                              | 7.99                              |
+-----------------------------------+-----------------------------------+-----------------------------------+
| b (Å)                             | 5.90                              | 6.02                              |
+-----------------------------------+-----------------------------------+-----------------------------------+
| c (Å)                             | 8.62                              | 8.59                              |
+-----------------------------------+-----------------------------------+-----------------------------------+

Tip:

  M3GNet is also suitable for inorganic crystals like metals and metal
  oxides.


M3GNet in Python with PLAMS
===========================

See the M3GNet example in the Python Examples documentation.


References
==========

[1] C. Chen, S. P. Ong. Nature Computational Science 2, 718–728
    (2022). arXiv.2202.02450.

[2] W.A. Al-Saidi, V.K. Voora, K.D. Joradan. DOI: 10.1021/ct200618b
