docs/tutorials/tutorial_simple_LJ.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Point Particles: Basic system initialization\n",
    "\n",
    "__Note__: mBuild expects all distance units to be in nanometers.\n",
    "\n",
    "This tutorial focuses on the usage of basic system initialization operations, as applied to simple point particle systems (i.e., generic Lennard-Jones particles rather than specific atoms). \n",
    "\n",
    "The code below defines several point particles in a cubic arrangement. Note, the color and radius associated with a Particle name can be set and passed to the visualize command.  Colors are passed in hex format (see http://www.color-hex.com/color/bfbfbf)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import mbuild as mb\n",
    "\n",
    "class MonoLJ(mb.Compound):\n",
    "    def __init__(self):\n",
    "        super(MonoLJ, self).__init__()\n",
    "        lj_particle1 = mb.Particle(name='LJ', pos=[0, 0, 0])\n",
    "        self.add(lj_particle1)\n",
    "\n",
    "        lj_particle2 = mb.Particle(name='LJ', pos=[1, 0, 0])\n",
    "        self.add(lj_particle2)\n",
    "\n",
    "        lj_particle3 = mb.Particle(name='LJ', pos=[0, 1, 0])\n",
    "        self.add(lj_particle3)\n",
    "\n",
    "        lj_particle4 = mb.Particle(name='LJ', pos=[0, 0, 1])\n",
    "        self.add(lj_particle4)\n",
    "\n",
    "        lj_particle5 = mb.Particle(name='LJ', pos=[1, 0, 1])\n",
    "        self.add(lj_particle5)\n",
    "\n",
    "        lj_particle6 = mb.Particle(name='LJ', pos=[1, 1, 0])\n",
    "        self.add(lj_particle6)\n",
    "\n",
    "        lj_particle7 = mb.Particle(name='LJ', pos=[0, 1, 1])\n",
    "        self.add(lj_particle7)\n",
    "        \n",
    "        lj_particle8 = mb.Particle(name='LJ', pos=[1, 1, 1])\n",
    "        self.add(lj_particle8)\n",
    "\n",
    "\n",
    "monoLJ = MonoLJ()\n",
    "monoLJ.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "While this would work for defining a single molecule or very small system, this would not be efficient for large systems.  Instead, the clone and translate operator can be used to facilitate automation. Below, we simply define a single prototype particle (lj_proto), which we then copy and translate about the system. \n",
    "\n",
    "Note, mBuild provides two different translate operations, \"translate\" and \"translate_to\".   \"translate\" moves a particle by adding the vector the original position, whereas \"translate_to\" move a particle to the specified location in space.  Note, \"translate_to\" maintains the internal spatial relationships of a collection of particles by first shifting the center of mass of the collection of particles to the origin, then translating to the specified location.  Since the lj_proto particle in this example starts at the origin, these two commands produce identical behavior. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import mbuild as mb\n",
    "\n",
    "class MonoLJ(mb.Compound):\n",
    "    def __init__(self):\n",
    "        super(MonoLJ, self).__init__()\n",
    "        lj_proto = mb.Particle(name='LJ', pos=[0, 0, 0])\n",
    "\n",
    "        for i in range(0,2):\n",
    "            for j in range(0,2):\n",
    "                for k in range(0,2):\n",
    "                    lj_particle = mb.clone(lj_proto)\n",
    "                    pos = [i,j,k]\n",
    "                    lj_particle.translate(pos)\n",
    "                    self.add(lj_particle)\n",
    "\n",
    "monoLJ = MonoLJ()\n",
    "monoLJ.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To simplify this process, mBuild provides several build-in patterning tools, where for example,  Grid3DPattern can be used to perform this same operation.  Grid3DPattern generates a set of points, from 0 to 1, which get stored in the variable \"pattern\".  We need only loop over the points in pattern, cloning, translating, and adding to the system.  Note, because Grid3DPattern defines points between 0 and 1, they must be scaled based on the desired system size, i.e., pattern.scale(2). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import mbuild as mb\n",
    "\n",
    "class MonoLJ(mb.Compound):\n",
    "    def __init__(self):\n",
    "        super(MonoLJ, self).__init__()\n",
    "        lj_proto = mb.Particle(name='LJ', pos=[0, 0, 0])\n",
    "\n",
    "        pattern = mb.Grid3DPattern(2, 2, 2)\n",
    "        pattern.scale(2)\n",
    "\n",
    "        for pos in pattern:\n",
    "            lj_particle = mb.clone(lj_proto)\n",
    "            lj_particle.translate(pos)\n",
    "            self.add(lj_particle)\n",
    "\n",
    "monoLJ = MonoLJ()\n",
    "monoLJ.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Larger systems can therefore be easily generated by toggling the values given to Grid3DPattern.  Other patterns can also be generated using the same basic code, such as a 2D grid pattern:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "import mbuild as mb\n",
    "\n",
    "class MonoLJ(mb.Compound):\n",
    "    def __init__(self):\n",
    "        super(MonoLJ, self).__init__()\n",
    "        lj_proto = mb.Particle(name='LJ', pos=[0, 0, 0])\n",
    "\n",
    "        pattern = mb.Grid2DPattern(5, 5)\n",
    "        pattern.scale(5)\n",
    "\n",
    "        for pos in pattern:\n",
    "            lj_particle = mb.clone(lj_proto)\n",
    "            lj_particle.translate(pos)\n",
    "            self.add(lj_particle)\n",
    "\n",
    "monoLJ = MonoLJ()\n",
    "monoLJ.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Points on a sphere can be generated using SpherePattern. Points on a disk using DisKPattern, etc. \n",
    "\n",
    "Note to show both simultaneously, we shift the x-coordinate of Particles in the sphere by -1 (i.e., pos[0]-=1.0) and +1 for the disk (i.e, pos[0]+=1.0).  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import mbuild as mb\n",
    "\n",
    "class MonoLJ(mb.Compound):\n",
    "    def __init__(self):\n",
    "        super(MonoLJ, self).__init__()\n",
    "        lj_proto = mb.Particle(name='LJ', pos=[0, 0, 0])\n",
    "        \n",
    "        pattern_sphere = mb.SpherePattern(200)\n",
    "        pattern_sphere.scale(0.5)\n",
    "        \n",
    "        for pos in pattern_sphere:\n",
    "            lj_particle = mb.clone(lj_proto)\n",
    "            pos[0]-=1.0\n",
    "            lj_particle.translate(pos)\n",
    "            self.add(lj_particle)\n",
    "        \n",
    "        pattern_disk = mb.DiskPattern(200)\n",
    "        pattern_disk.scale(0.5)\n",
    "        for pos in pattern_disk:\n",
    "            lj_particle = mb.clone(lj_proto)\n",
    "            pos[0]+=1.0\n",
    "            lj_particle.translate(pos)\n",
    "            self.add(lj_particle)\n",
    "\n",
    "monoLJ = MonoLJ()\n",
    "monoLJ.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also take advantage of the hierachical nature of mBuild to accomplish the same task more cleanly.  Below we  create a component that corresponds to the sphere (class SphereLJ), and one that corresponds to the disk (class DiskLJ), and then instantiate and shift each of these individually in the MonoLJ component."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import mbuild as mb\n",
    "\n",
    "class SphereLJ(mb.Compound):\n",
    "    def __init__(self):\n",
    "        super(SphereLJ, self).__init__()\n",
    "        lj_proto = mb.Particle(name='LJ', pos=[0, 0, 0])\n",
    "        \n",
    "        pattern_sphere = mb.SpherePattern(200)\n",
    "        pattern_sphere.scale(0.5)\n",
    "        \n",
    "        for pos in pattern_sphere:\n",
    "            lj_particle = mb.clone(lj_proto)\n",
    "            lj_particle.translate(pos)\n",
    "            self.add(lj_particle)\n",
    "\n",
    "class DiskLJ(mb.Compound):\n",
    "    def __init__(self):\n",
    "        super(DiskLJ, self).__init__()\n",
    "        lj_proto = mb.Particle(name='LJ', pos=[0, 0, 0])\n",
    "\n",
    "        pattern_disk = mb.DiskPattern(200)\n",
    "        pattern_disk.scale(0.5)\n",
    "        for pos in pattern_disk:\n",
    "            lj_particle = mb.clone(lj_proto)\n",
    "            lj_particle.translate(pos)\n",
    "            self.add(lj_particle)\n",
    "\n",
    "\n",
    "class MonoLJ(mb.Compound):\n",
    "    def __init__(self):\n",
    "        super(MonoLJ, self).__init__()\n",
    "        \n",
    "        sphere = SphereLJ();\n",
    "        pos=[-1, 0, 0]\n",
    "        sphere.translate(pos)\n",
    "        self.add(sphere)\n",
    "\n",
    "        disk = DiskLJ();\n",
    "        pos=[1, 0, 0]\n",
    "        disk.translate(pos)\n",
    "        self.add(disk)\n",
    "\n",
    "\n",
    "monoLJ = MonoLJ()\n",
    "monoLJ.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Again, since mBuild is hierarchical, the pattern functions can be used to generate large systems of any arbitary component.  For example, we can replicate the SphereLJ component on a regular array."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import mbuild as mb\n",
    "\n",
    "class SphereLJ(mb.Compound):\n",
    "    def __init__(self):\n",
    "        super(SphereLJ, self).__init__()\n",
    "        lj_proto = mb.Particle(name='LJ', pos=[0, 0, 0])\n",
    "        \n",
    "        pattern_sphere = mb.SpherePattern(13)\n",
    "        pattern_sphere.scale(0.1)\n",
    "        \n",
    "        for pos in pattern_sphere:\n",
    "            lj_particle = mb.clone(lj_proto)\n",
    "            lj_particle.translate(pos)\n",
    "            self.add(lj_particle)\n",
    "class MonoLJ(mb.Compound):\n",
    "    def __init__(self):\n",
    "        super(MonoLJ, self).__init__()\n",
    "        sphere = SphereLJ();\n",
    "\n",
    "        pattern = mb.Grid3DPattern(3, 3, 3)\n",
    "        pattern.scale(2)\n",
    "\n",
    "        for pos in pattern:\n",
    "            lj_sphere = mb.clone(sphere)\n",
    "            lj_sphere.translate_to(pos)\n",
    "            #shift the particle so the center of mass\n",
    "            #of the system is at the origin\n",
    "            lj_sphere.translate([-5,-5,-5])\n",
    "\n",
    "            self.add(lj_sphere)\n",
    "\n",
    "monoLJ = MonoLJ()\n",
    "monoLJ.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Several functions exist for rotating compounds. For example, the spin command allows a compound to be rotated, in place, about a specific axis (i.e., it considers the origin for the rotation to lie at the compound's center of mass)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "import mbuild as mb\n",
    "import random\n",
    "from numpy import pi\n",
    "\n",
    "\n",
    "class CubeLJ(mb.Compound):\n",
    "    def __init__(self):\n",
    "        super(CubeLJ, self).__init__()\n",
    "        lj_proto = mb.Particle(name='LJ', pos=[0, 0, 0])\n",
    "        \n",
    "        pattern = mb.Grid3DPattern(2, 2, 2)\n",
    "        pattern.scale(0.2)\n",
    "\n",
    "        for pos in pattern:\n",
    "            lj_particle = mb.clone(lj_proto)\n",
    "            lj_particle.translate(pos)\n",
    "            self.add(lj_particle)\n",
    "            \n",
    "class MonoLJ(mb.Compound):\n",
    "    def __init__(self):\n",
    "        super(MonoLJ, self).__init__()\n",
    "        cube_proto = CubeLJ();\n",
    "\n",
    "        pattern = mb.Grid3DPattern(3, 3, 3)\n",
    "        pattern.scale(2)\n",
    "        rnd = random.Random()\n",
    "        rnd.seed(123)\n",
    "        \n",
    "        for pos in pattern:\n",
    "            lj_cube = mb.clone(cube_proto)\n",
    "            lj_cube.translate_to(pos)\n",
    "            #shift the particle so the center of mass\n",
    "            #of the system is at the origin\n",
    "            lj_cube.translate([-5,-5,-5])\n",
    "            lj_cube.spin( rnd.uniform(0, 2 * pi), [1, 0, 0])\n",
    "            lj_cube.spin(rnd.uniform(0, 2 * pi), [0, 1, 0])\n",
    "            lj_cube.spin(rnd.uniform(0, 2 * pi), [0, 0, 1])\n",
    "\n",
    "            self.add(lj_cube)\n",
    "\n",
    "monoLJ = MonoLJ()\n",
    "monoLJ.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Configurations can be dumped to file using the save command; this takes advantage of MDTraj and supports a range of file formats (see http://MDTraj.org). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#save as xyz file\n",
    "monoLJ.save('output.xyz')\n",
    "#save as mol2\n",
    "monoLJ.save('output.mol2')"
   ]
  }
 ],
 "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.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}