{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Example 1: Using LAMMPS with PyLammps"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The LAMMPS Python package provides multiple interfaces. The `PyLammps` interface is a high-level abstration of the low-level `lammps` interface. `IPyLammps` further extends this interface with functions that are useful for Jupyter notebooks to enable embedding generated graphics and videos."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Prerequisites\n",
    "\n",
    "Before Running this example, make sure your Python environment can find the LAMMPS shared library (`liblammps.so`) and the LAMMPS Python package is installed. If you followed the [README](README.md) in this folder, this should already be the case. You can also find more information about how to compile LAMMPS and install the LAMMPS Python package in the [LAMMPS manual](https://docs.lammps.org/Python_install.html). There is also a dedicated [PyLammps HowTo](https://docs.lammps.org/Howto_pylammps.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating a new simulation\n",
    "\n",
    "Once the LAMMPS shared library and the LAMMPS Python package are installed, you can create a new LAMMMPS instance in your Python interpreter as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from lammps import IPyLammps\n",
    "L = IPyLammps()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With `PyLammps`/`IPyLammps` you can write LAMMPS simulations similar to the input script language. Take the following LAMMPS input script:\n",
    "\n",
    "```bash\n",
    "# 3d Lennard-Jones melt\n",
    "\n",
    "units        lj\n",
    "atom_style   atomic\n",
    "\n",
    "lattice      fcc 0.8442\n",
    "region       box block 0 4 0 4 0 4\n",
    "create_box   1 box\n",
    "create_atoms 1 box\n",
    "mass         1 1.0\n",
    "\n",
    "velocity     all create 1.44 87287 loop geom\n",
    "\n",
    "pair_style   lj/cut 2.5\n",
    "pair_coeff   1 1 1.0 1.0 2.5\n",
    "\n",
    "neighbor     0.3 bin\n",
    "neigh_modify delay 0 every 20 check no\n",
    "\n",
    "fix          1 all nve\n",
    "\n",
    "thermo       50\n",
    "```\n",
    "The equivalent can be written with `PyLammps`/`IPyLammps`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 3d Lennard-Jones melt\n",
    "\n",
    "L.units(\"lj\")\n",
    "L.atom_style(\"atomic\")\n",
    "\n",
    "L.lattice(\"fcc\", 0.8442)\n",
    "L.region(\"box\", \"block\", 0, 4, 0, 4, 0, 4)\n",
    "L.create_box(1, \"box\")\n",
    "L.create_atoms(1, \"box\")\n",
    "L.mass(1, 1.0)\n",
    "\n",
    "L.velocity(\"all\", \"create\", 1.44, 87287, \"loop geom\")\n",
    "\n",
    "L.pair_style(\"lj/cut\", 2.5)\n",
    "L.pair_coeff(1, 1, 1.0, 1.0, 2.5)\n",
    "\n",
    "L.neighbor(0.3, \"bin\")\n",
    "L.neigh_modify(\"delay\", 0, \"every\", 20, \"check no\")\n",
    "\n",
    "L.fix(\"1\", \"all\", \"nve\")\n",
    "\n",
    "L.thermo(50)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Visualizing the initial state\n",
    "\n",
    "`IPyLammps` allows you to visualize the current simulation state with the [image](https://docs.lammps.org/Python_module.html#lammps.IPyLammps.image) command. Here we use it to create an image of the initial state of the system."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "L.image(zoom=1.0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Running simulations\n",
    "\n",
    "Use the `run` command to start the simulation. In Jupyter the return value of the last command will be displayed. The `run` command will return the output of the simulation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "L.run(150)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can suppress it by adding a semicolon `;`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "L.run(100);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Visualizing the system will now show us how the atoms have moved."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "L.image(zoom=1.0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Post-processing thermo output\n",
    "\n",
    "Independent of whether or not you suppress or show the output of the `run` command, `PyLammps` will record the output. Each `run` command creates a new entry in the `L.runs` list. So far our PyLammps instance `L` executed two `run` commands:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "len(L.runs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Each entry contains information about the simulation run, including the thermo output for the printed out time steps.\n",
    "\n",
    "```bash\n",
    "# thermo output of a LAMMPS simulation run\n",
    "Step Temp E_pair E_mol TotEng Press\n",
    "       0         1.44   -6.7733681            0   -4.6218056   -5.0244179\n",
    "      50   0.70303849   -5.6796164            0    -4.629178   0.50453907\n",
    "     100   0.72628044   -5.7150774            0   -4.6299123   0.29765862\n",
    "     150   0.78441711    -5.805142            0   -4.6331125 -0.086709661\n",
    "```\n",
    "\n",
    "`PyLammps` already parses this information and makes it available as dictionaries and arrays."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "L.runs[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "L.runs[1]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example, the first run was 150 time steps, with printing out a line every 50 steps. You can access the list of time steps using `{entry}.thermo.Step`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "L.runs[0].thermo.Step"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The corresponding values of each thermo quantity are also accessed this way:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "L.runs[0].thermo.TotEng"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Together you can use this information to run post-processing on these values or even plot it using `matplotlib`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "plt.xlabel('time step')\n",
    "plt.ylabel('Total Energy')\n",
    "plt.plot(L.runs[0].thermo.Step, L.runs[0].thermo.TotEng)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.9.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}