DOC: Added manybody example

docs/calculators/index.rst

@@ -2,3 +2,7 @@ Interatomic potentials
 ======================
 
 `matscipy` implements a select set of interatomic potentials as ASE calculators.
+
+.. toctree::
+
+   manybody

docs/calculators/manybody.ipynb

@@ -0,0 +1,141 @@
+{
+ "cells": [
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Many-body potentials\n",
+    "\n",
+    "`matscipy` implements support for generic manybody potentials. The class `matscipy.calculators.manybody.Manybody` implements the functional form\n",
+    "\n",
+    "$$\n",
+    "  U\n",
+    "  =\n",
+    "  \\frac{1}{2}\n",
+    "  \\sum_{\\substack{ij\\\\ i\\neq j}}\n",
+    "  U_2(r^2_{ij}) + U_\\text{m}(r^2_{ij}, \\xi_{ij})\n",
+    "$$\n",
+    "\n",
+    "with\n",
+    "\n",
+    "$$\n",
+    "  \\xi_{ij} \n",
+    "  = \n",
+    "  \\sum_{\\substack{k\\\\ k\\neq i,j}} \n",
+    "  \\Xi(r^2_{ij}, r^2_{ik}, r^2_{jk})\n",
+    "$$\n",
+    "\n",
+    "as described, e.g. by [Müser et al.](https://doi.org/10.1080/23746149.2022.2093129) and [Grießer et al.](https://doi.org/10.48550/arXiv.2302.08754). On top of energies and forces, the calculator can compute second derivatives (with respect to positions and strain degrees of freedom). Explicit functional forms of $U_2$, $U_\\text{m}$ and $\\Xi$ are implemented for a number of potential."
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Kumagai potential\n",
+    "\n",
+    "The following example compute the elastic constants of a small representation of amorphous silicon using the potential by [Kumagai et al.](https://doi.org/10.1016/j.commatsci.2006.07.013)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 23,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Cohesive energy = -4.415832408778078 eV\n",
+      "Young's modulus = 170.88211399586595 GPa\n",
+      "Poisson number = 0.21150737791390495\n"
+     ]
+    }
+   ],
+   "source": [
+    "import numpy as np\n",
+    "\n",
+    "from ase.io import read\n",
+    "from ase.units import GPa\n",
+    "\n",
+    "from matscipy.elasticity import elastic_moduli, full_3x3x3x3_to_Voigt_6x6\n",
+    "from matscipy.calculators.manybody import Manybody\n",
+    "from matscipy.calculators.manybody.explicit_forms import Kumagai\n",
+    "from matscipy.calculators.manybody.explicit_forms.kumagai import Kumagai_Comp_Mat_Sci_39_Si\n",
+    "\n",
+    "# Load a disordered configuration (amorphous silicon)\n",
+    "a = read('../../tests/aSi.cfg')\n",
+    "\n",
+    "# Construct calculator\n",
+    "calc = Manybody(**Kumagai(Kumagai_Comp_Mat_Sci_39_Si))\n",
+    "a.calc = calc\n",
+    "\n",
+    "# Total energy\n",
+    "print(f'Cohesive energy = {a.get_potential_energy() / len(a)} eV/atom')\n",
+    "\n",
+    "# Born elastic constants (without nonaffine displacements)\n",
+    "C = calc.get_born_elastic_constants(a)\n",
+    "\n",
+    "# Get isotropic elastic moduli\n",
+    "E, nu, G, B, K = elastic_moduli(full_3x3x3x3_to_Voigt_6x6(C))\n",
+    "\n",
+    "print(f\"Young's modulus = {E.mean() / GPa} GPa\")\n",
+    "print(f\"Poisson number = {(nu + np.eye(3)).sum()/6}\")"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Other many-body potentials\n",
+    "\n",
+    "To runs the same code with [Stillinger-Weber](https://doi.org/10.1103/PhysRevB.31.5262), replace the calculator by"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 24,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from matscipy.calculators.manybody.explicit_forms import StillingerWeber\n",
+    "from matscipy.calculators.manybody.explicit_forms.stillinger_weber import Stillinger_Weber_PRB_31_5262_Si\n",
+    "\n",
+    "calc = Manybody(**StillingerWeber(Stillinger_Weber_PRB_31_5262_Si))"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Other examples of potentials that are implemented are [Tersoff](https://doi.org/10.1103/PhysRevB.39.5566), [Brenner](https://doi.org/10.1103/PhysRevB.42.9458) (without the lookup tables), [Erhart-Albe](https://doi.org/10.1103/PhysRevB.71.035211) and others. Second derivatives are supported for all of these."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.6"
+  },
+  "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}