Anatomy of a Script File.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Anatomy of an MD simulation script File\n",
    "Recall there are many packages available to perform MD simulations often with different features and meant to support different system types. A few of the common codes include:\n",
    "* [LAMMPS](http://LAMMPS.sandia.gov)\n",
    "* [GROMACS](http://gromacs.org)\n",
    "* [HOOMD-Blue](http://glotzerlab.engin.umich.edu/hoomd-blue/)\n",
    "* [NAMD](https://www-s.ks.uiuc.edu/Research/namd/)\n",
    "* [DLPoly](https://www.scd.stfc.ac.uk/Pages/DL_POLY.aspx)\n",
    "* [CHARMM](https://www.charmm.org)\n",
    "* [AMBER](https://ambermd.org)\n",
    "* [OPENMM](https://openmm.org)\n",
    "* [NWChem](https://www.nwchem-sw.org)\n",
    "* [BOSS](http://zarbi.chem.yale.edu/software.html)\n",
    "* [Tinker](https://tinkertools.org)\n",
    "     \n",
    "### Basic components of most script/control files\n",
    "In general, MD simulation engines require the same basic information to be passed to the code, even if the format varies.  We can roughly break these inputs up into four main categories.\n",
    "\n",
    "#### system initialization \n",
    ">definition of the box size, how many particles, particle types, particle initial positions, what particles are bonded to each other, the periodicity, and other system context information.  Typically, this involves providing the name of an data file that defines the system configuration\n",
    "\n",
    "#### interaction definition \n",
    ">the functional and associated parameters form describing how different species interact with each other, cell/neighborlist information.\n",
    "\n",
    "#### integrator setup\n",
    ">what algorithm will we use to advance particles in time, time step of integration, thermodynamic state point (i.e., T and/or P).\n",
    "\n",
    "#### runtime parameters \n",
    ">total simulation time, frequency of writing thermodynamic quantities and/or system configuration data, etc.\n",
    "\n",
    "\n",
    "\n",
    "### Challenges\n",
    "In general, each simulation engines employs its own unique syntax and file format for defining the inputs to the code.  While there is a growing trend of providing Python interfaces for the software, there still is not a uniform syntax or API for initializing simulations.  \n",
    "\n",
    "For example, LAMMPS uses its own custom scripting language to define the simulation inputs, as well as their own novel file format for defining the configuration of the system. \n",
    "\n",
    "For example, HOOMD-Blue and OpenMM allow users to define the inputs and interact with the software using Python.  However, despite both codes using Python, their APIs are not interchangeable; that is, a HOOMD-Blue python script could not be used to setup and perform a OpenMM simulation. The codes also utilize different file formats for defining the system configuration.\n",
    "\n",
    "Tools such as GROMACS and NAMD rely upon a different approach altogether, using a control files (files that define keys and their associated values) to define simulation run parameters and methods, rather than scripts.  \n",
    "\n",
    "OpenMM is somewhat unique in that it provides routines to read not only their file format, but also AMBER, GROMACS, and CHARMM data files that contain configurations and force field information. However, a user must still write their own script file (support is not provided to automatically convert, e.g., a GROMACS .mdp control files).\n",
    "\n",
    "Overall, this means that switching between different simulation engines is often non-trivial, requiring users to generate new data files and scripts for each code they may wish to use.  As will be discussed later, the [MosDeF](mosdef.org) toolkit has been developed to help address some of these issues in terms of making it easier to generate parameterized data files for different simulation engines and ensuring that such files are accurate.  \n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example HOOMD-Blue script file\n",
    "The code below is example python script for HOOMD-Blue to perform a basic LJ simulation. This example is adapted from the tutorial found on in [HOOMD-Blue documentation](https://hoomd-blue.readthedocs.io/en/v3.2.0/tutorial/01-Introducing-Molecular-Dynamics/01-Molecular-Dynamics-Simulations.html) which provides a detailed examination of the structure of the script file. Note, the simulation configuration is defined in the file 'lj.gsd' which was created using the [mBuild library](mbuild.mosdef.org), which will be discussed in more detail later in the cybercamp. \n",
    "\n",
    "Because HOOMD-Blue has a Python interface and the code is readily available via conda, we can run this script directly from the notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hoomd\n",
    "import gsd.hoomd\n",
    "\n",
    "\n",
    "cpu = hoomd.device.CPU()\n",
    "sim = hoomd.Simulation(device=cpu, seed=1)\n",
    "\n",
    "#########################\n",
    "# system initialization\n",
    "#########################\n",
    "\n",
    "sim.create_state_from_gsd(filename='datafiles/lj.gsd')\n",
    "sim.state.thermalize_particle_momenta(filter=hoomd.filter.All(), kT=1.5)\n",
    "\n",
    "#########################\n",
    "# interaction definition\n",
    "#########################\n",
    "\n",
    "cell = hoomd.md.nlist.Cell(buffer=1.0)\n",
    "lj = hoomd.md.pair.LJ(nlist=cell)\n",
    "lj.params[('LJ', 'LJ')] = dict(epsilon=1, sigma=1)\n",
    "lj.r_cut[('LJ', 'LJ')] = 2.5\n",
    "\n",
    "#########################\n",
    "# integrator setup\n",
    "#########################\n",
    "\n",
    "nvt = hoomd.md.methods.NVT(kT=1.5, filter=hoomd.filter.All(), tau=1.0)\n",
    "integrator = hoomd.md.Integrator(dt=0.005)\n",
    "integrator.forces.append(lj)\n",
    "integrator.methods.append(nvt)\n",
    "sim.operations.integrator = integrator\n",
    "\n",
    "#########################\n",
    "# runtime parameters\n",
    "#########################\n",
    "\n",
    "log_traj = hoomd.logging.Logger()\n",
    "gsd_traj = hoomd.write.GSD(filename='trajectory.gsd',\n",
    "                             trigger=hoomd.trigger.Periodic(5000),\n",
    "                             mode='wb',\n",
    "                             filter=hoomd.filter.All(),\n",
    "                             log=log_traj)\n",
    "sim.operations.writers.append(gsd_traj)\n",
    "\n",
    "thermodynamic_properties = hoomd.md.compute.ThermodynamicQuantities(filter=hoomd.filter.All())\n",
    "sim.operations.computes.append(thermodynamic_properties)\n",
    "\n",
    "log_thermo = hoomd.logging.Logger()\n",
    "log_thermo.add(thermodynamic_properties)\n",
    "gsd_thermo = hoomd.write.GSD(filename='thermo.gsd',\n",
    "                             trigger=hoomd.trigger.Periodic(100),\n",
    "                             mode='wb',\n",
    "                             filter=hoomd.filter.Null(),\n",
    "                             log=log_thermo)\n",
    "sim.operations.writers.append(gsd_thermo)\n",
    "\n",
    "\n",
    "sim.run(50000)\n",
    "\n",
    "hoomd.write.GSD.write(state=sim.state, filename='final.gsd', mode='wb')\n",
    "print(\"simulation complete\")\n",
    "\n",
    "#delete the instances we defined ensure writers are closed\n",
    "del sim, gsd_thermo, gsd_traj, thermodynamic_properties, log_thermo, log_traj\n",
    "del integrator, nvt, lj, cell, cpu"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With the simulation completed, we can examine various thermodynamic properties that have been saved to the thermo.gsd file.  Below we will loop over each frame in the trajectory and to create two arrays\n",
    "* ```time``` which contains the simulation time step\n",
    "* ```pe``` which contains the system potential energy "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "thermo_log = gsd.hoomd.open('thermo.gsd', 'rb')\n",
    "\n",
    "time = []\n",
    "pe = []\n",
    "for frame in thermo_log:\n",
    "    time.append(frame.configuration.step)\n",
    "    pe.append(frame.log['md/compute/ThermodynamicQuantities/potential_energy'][0])\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib\n",
    "import matplotlib.pyplot as plt\n",
    "matplotlib.style.use('default')\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.plot(time, pe)\n",
    "plt.ylabel('potential energy')\n",
    "plt.xlabel('timestep')\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can quickly render a short movie of the trajectory using the Fresnel package.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from fresnel_render import render\n",
    "from fresnel_render import render_movie\n",
    "\n",
    "traj_log = gsd.hoomd.open('trajectory.gsd', 'rb')\n",
    "\n",
    "render_movie(traj_log)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example LAMMPS input files\n",
    "\n",
    "Below is an example of a LAMMPS input script file for performing a simple Lennard Jones simulation. Here, each of the commands associated with  the four main categories are labeled. The code below performs effectively the same simulation as the HOOMD-Blue example. For more information on LAMMPS input script files, see the official [documentation](https://docs.lammps.org/Commands_structure.html). \n",
    "\n",
    "\n",
    "```\n",
    "#########################\n",
    "# system initialization\n",
    "#########################\n",
    "\n",
    "units lj\n",
    "atom_style full\n",
    "dimension 3\n",
    "boundary p p p\n",
    "read_data datafiles/data.lj.txt\n",
    "\n",
    "#########################\n",
    "# interaction definition\n",
    "#########################\n",
    "\n",
    "pair_style lj/cut 2.5\n",
    "pair_coeff * * 1.0 1.0\n",
    "neighbor 1.0 bin\n",
    "neigh_modify  check yes\n",
    "\n",
    "#########################\n",
    "# integrator setup\n",
    "#########################\n",
    "\n",
    "fix 1 all nvt temp 1.5 1.5 1.0\n",
    "timestep 0.005\n",
    "\n",
    "#########################\n",
    "# runtime parameters\n",
    "#########################\n",
    "\n",
    "thermo 100\n",
    "dump dump_traj all custom 5000 trajectory.lammpstrj id type  x  y  z\n",
    "run 50000\n",
    "\n",
    "write_restart final.restart\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The code above loads in the system configuration (particle coordinates, box size, bonded connections, etc.) from an external file, here 'data.lj.txt'.  Rules for formatting the data file can found in the [LAMMPS documentation about the read_data command](https://docs.lammps.org/read_data.html).  The first 30 lines of the configuration input file are shown below. I note, this input final was generated using the [mbuild library](http://mbuild.mosdef.org), which will ne discussed in detail later in the cybercamp."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!cat datafiles/data.lj.lammps | head -n 30"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Exercises\n",
    "As we saw in the example of the ball falling, if we use too large of a timestep (dt), we miss important details.  In the ball falling example, we were not being able to precisely identify when the ball contacts the ground.  For an MD simulation, the same type of issue can occur if the timestep is too large; typically, this means that particles move too close together, resulting in in extremely larger forces between particles in the system causing system failure (i.e., the system to \"blow up\").   The code below plots the LJ interaction as a function of distance (showing both the energy, `U` and force, `F`), where we can see the force grows very rapidly as the separation reduces below the value of sigma (here, $\\sigma= 1$).  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "epsilon = 1.0\n",
    "sigma = 1.0\n",
    "\n",
    "r_min = 0.6\n",
    "r_max = 3.0\n",
    "steps = 1000\n",
    "r_step = (r_max-r_min)/steps\n",
    "\n",
    "U = np.zeros(steps)\n",
    "F = np.zeros(steps)\n",
    "r  = np.zeros(steps)\n",
    "for i in range (0, steps):\n",
    "        \n",
    "        r[i] = r_min + r_step*i\n",
    "        U[i] = 4*epsilon*((sigma/r[i])**12 - (sigma/r[i])**6)\n",
    "        F[i] = 48*(epsilon/sigma)*((sigma/r[i])**13 - 0.5*(sigma/r[i])**7)\n",
    "\n",
    "        \n",
    "plt.plot(r, U, c='blue', label='U(r)')\n",
    "plt.plot(r, F, c='red', label='F(r)')\n",
    "\n",
    "plt.ylabel('U(r) or F(r)')\n",
    "plt.xlabel('r')\n",
    "plt.ylim(-3, 10)\n",
    "plt.legend(loc='upper right')\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise 1\n",
    "\n",
    "Modify the timestep (e.g., increasing it from 0.005 to 0.0075, 0.01, 0.0125, 0.015, etc.) in the code below.  At what value do you observe a failure? While there are other factors to consider when setting the timestep, ensuring the simulation doesn't blow up is the minimal criteria that should be applied.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hoomd\n",
    "import gsd.hoomd\n",
    "\n",
    "\n",
    "cpu = hoomd.device.CPU()\n",
    "sim = hoomd.Simulation(device=cpu, seed=1)\n",
    "\n",
    "#########################\n",
    "# system initialization\n",
    "#########################\n",
    "\n",
    "sim.create_state_from_gsd(filename='datafiles/lj.gsd')\n",
    "sim.state.thermalize_particle_momenta(filter=hoomd.filter.All(), kT=1.5)\n",
    "\n",
    "#########################\n",
    "# interaction definition\n",
    "#########################\n",
    "\n",
    "cell = hoomd.md.nlist.Cell(buffer=1.0)\n",
    "lj = hoomd.md.pair.LJ(nlist=cell)\n",
    "lj.params[('LJ', 'LJ')] = dict(epsilon=1, sigma=1)\n",
    "lj.r_cut[('LJ', 'LJ')] = 2.5\n",
    "\n",
    "#########################\n",
    "# integrator setup\n",
    "#########################\n",
    "\n",
    "nvt = hoomd.md.methods.NVT(kT=0.8, filter=hoomd.filter.All(), tau=1.0)\n",
    "integrator = hoomd.md.Integrator(dt=0.005)\n",
    "integrator.forces.append(lj)\n",
    "integrator.methods.append(nvt)\n",
    "sim.operations.integrator = integrator\n",
    "\n",
    "#########################\n",
    "# runtime parameters\n",
    "#########################\n",
    "\n",
    "log_traj = hoomd.logging.Logger()\n",
    "gsd_traj = hoomd.write.GSD(filename='trajectory.gsd',\n",
    "                             trigger=hoomd.trigger.Periodic(5000),\n",
    "                             mode='wb',\n",
    "                             filter=hoomd.filter.All(),\n",
    "                             log=log_traj)\n",
    "sim.operations.writers.append(gsd_traj)\n",
    "\n",
    "thermodynamic_properties = hoomd.md.compute.ThermodynamicQuantities(filter=hoomd.filter.All())\n",
    "sim.operations.computes.append(thermodynamic_properties)\n",
    "\n",
    "log_thermo = hoomd.logging.Logger()\n",
    "log_thermo.add(thermodynamic_properties)\n",
    "gsd_thermo = hoomd.write.GSD(filename='thermo.gsd',\n",
    "                             trigger=hoomd.trigger.Periodic(100),\n",
    "                             mode='wb',\n",
    "                             filter=hoomd.filter.Null(),\n",
    "                             log=log_thermo)\n",
    "sim.operations.writers.append(gsd_thermo)\n",
    "\n",
    "\n",
    "sim.run(10000)\n",
    "print(\"simulation complete\")\n",
    "#delete the instances we defined ensure writers are closed\n",
    "del sim, gsd_thermo, gsd_traj, thermodynamic_properties, log_thermo, log_traj\n",
    "del integrator, nvt, lj, cell, cpu"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise 2\n",
    "\n",
    "Using the same code you used to adjust the timestep, reset the timestep to 0.005. Change the temperature of the simulation to be 0.8 and  plot the potential energy as well (using the code provided below).  Based upon potential energy, was the simulation run time sufficient to reach a steady state? If not, adjust the time and rerun. \n",
    "\n",
    "\n",
    "Compare the mean potential energy at the end of the simulation to T=1.5.   What do you think is the cause of the difference?\n",
    "\n",
    "Render the movie of the trajectory below. How does this visually compare to the temperature of 1.5, previously examined above? "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "thermo_log = gsd.hoomd.open('thermo.gsd', 'rb')\n",
    "\n",
    "time = []\n",
    "pe = []\n",
    "for frame in thermo_log:\n",
    "    time.append(frame.configuration.step)\n",
    "    pe.append(frame.log['md/compute/ThermodynamicQuantities/potential_energy'][0])\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.plot(time, pe)\n",
    "plt.ylabel('potential energy')\n",
    "plt.xlabel('timestep')\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "traj_log = gsd.hoomd.open('trajectory.gsd', 'rb')\n",
    "\n",
    "render_movie(traj_log)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}