mBuild_02_Reusing_Components.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "# mBuild Tutorial 02: Reusing Components\n",
    "\n",
    "This tutorial demonstrates how to create reusable components in mBuild, through definition of custom classes that inherit from the mbuild `Compound` class."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As in the prior tutorials, we need to first import mbuild (here as `mb`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import warnings\n",
    "warnings.filterwarnings('ignore')\n",
    "\n",
    "import mbuild as mb"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It would be quite tedious to have to perform each of the steps in prior tutorial (i.e. defining the particle positions and bonds) every time we wanted to create a new CH2 `Compound`. Fortunately, this problem is easily solved by wrapping these routines together into a class.\n",
    "\n",
    "Here, we'll create a class for our CH2 moiety using the same commands we used in prior tutorial so that we can easily reuse this piece when constructing more complex molecules."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "class CH2(mb.Compound):\n",
    "    def __init__(self):\n",
    "        super(CH2, self).__init__()\n",
    "        \n",
    "        carbon = mb.Particle(pos=[0.0, 0.0, 0.0], name='C')\n",
    "        hydrogen = mb.Particle(pos=[0.1, 0.0, 0.0], name='H')\n",
    "        hydrogen2 = mb.Particle(pos=[-0.1, 0.0, 0.0], name='H')\n",
    "        self.add([carbon, hydrogen, hydrogen2])\n",
    "        self.add_bond((carbon, hydrogen))\n",
    "        self.add_bond((carbon, hydrogen2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we can see, our class definition contains the same commands we just used in the prior tutorial the create the ch2 `Compound`; however, we have replaced `ch2` with `self` so that these commands will be performed on any instance of our `CH2` class. Additionally, since we want our class instance to be an mBuild `Compound`, we specify that our `CH2` class should inherit from `mb.Compound`.\n",
    "\n",
    "Now we'll create an instance of our `CH2` class and visualize it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/3dmoljs_load.v0": "<div id=\"3dmolviewer_16234422255500019\"  style=\"position: relative; width: 640px; height: 480px\">\n        <p id=\"3dmolwarning_16234422255500019\" style=\"background-color:#ffcccc;color:black\">You appear to be running in JupyterLab (or JavaScript failed to load for some other reason).  You need to install the 3dmol extension: <br>\n        <tt>jupyter labextension install jupyterlab_3dmol</tt></p>\n        </div>\n<script>\n\nvar loadScriptAsync = function(uri){\n  return new Promise((resolve, reject) => {\n    var tag = document.createElement('script');\n    tag.src = uri;\n    tag.async = true;\n    tag.onload = () => {\n      resolve();\n    };\n  var firstScriptTag = document.getElementsByTagName('script')[0];\n  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);\n});\n};\n\nif(typeof $3Dmolpromise === 'undefined') {\n$3Dmolpromise = null;\n  $3Dmolpromise = loadScriptAsync('https://3dmol.org/build/3Dmol.js');\n}\n\nvar viewer_16234422255500019 = null;\nvar warn = document.getElementById(\"3dmolwarning_16234422255500019\");\nif(warn) {\n    warn.parentNode.removeChild(warn);\n}\n$3Dmolpromise.then(function() {\nviewer_16234422255500019 = $3Dmol.createViewer($(\"#3dmolviewer_16234422255500019\"),{backgroundColor:\"white\"});\nviewer_16234422255500019.zoomTo();\n\tviewer_16234422255500019.addModel(\"@<TRIPOS>MOLECULE\\nRES\\n3 2 1 0 1\\nSMALL\\nNO_CHARGES\\n@<TRIPOS>CRYSIN\\n    7.0000    15.0000    15.0000    90.0000    90.0000    90.0000  1  1\\n@<TRIPOS>ATOM\\n       1 C            0.0000     0.0000     0.0000 C             1 RES     \\n       2 H            1.0000     0.0000     0.0000 H             1 RES     \\n       3 H           -1.0000     0.0000     0.0000 H             1 RES     \\n@<TRIPOS>BOND\\n       1        1        2 1\\n       2        3        1 1\\n@<TRIPOS>SUBSTRUCTURE\\n       1 RES             1 RESIDUE    0 **** ROOT      0\\n\",\"mol2\");\n\tviewer_16234422255500019.setStyle({\"stick\": {\"radius\": 0.2, \"color\": \"grey\"}, \"sphere\": {\"scale\": 0.3, \"colorscheme\": {}}});\n\tviewer_16234422255500019.zoomTo();\nviewer_16234422255500019.render();\n});\n</script>",
      "text/html": [
       "<div id=\"3dmolviewer_16234422255500019\"  style=\"position: relative; width: 640px; height: 480px\">\n",
       "        <p id=\"3dmolwarning_16234422255500019\" style=\"background-color:#ffcccc;color:black\">You appear to be running in JupyterLab (or JavaScript failed to load for some other reason).  You need to install the 3dmol extension: <br>\n",
       "        <tt>jupyter labextension install jupyterlab_3dmol</tt></p>\n",
       "        </div>\n",
       "<script>\n",
       "\n",
       "var loadScriptAsync = function(uri){\n",
       "  return new Promise((resolve, reject) => {\n",
       "    var tag = document.createElement('script');\n",
       "    tag.src = uri;\n",
       "    tag.async = true;\n",
       "    tag.onload = () => {\n",
       "      resolve();\n",
       "    };\n",
       "  var firstScriptTag = document.getElementsByTagName('script')[0];\n",
       "  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);\n",
       "});\n",
       "};\n",
       "\n",
       "if(typeof $3Dmolpromise === 'undefined') {\n",
       "$3Dmolpromise = null;\n",
       "  $3Dmolpromise = loadScriptAsync('https://3dmol.org/build/3Dmol.js');\n",
       "}\n",
       "\n",
       "var viewer_16234422255500019 = null;\n",
       "var warn = document.getElementById(\"3dmolwarning_16234422255500019\");\n",
       "if(warn) {\n",
       "    warn.parentNode.removeChild(warn);\n",
       "}\n",
       "$3Dmolpromise.then(function() {\n",
       "viewer_16234422255500019 = $3Dmol.createViewer($(\"#3dmolviewer_16234422255500019\"),{backgroundColor:\"white\"});\n",
       "viewer_16234422255500019.zoomTo();\n",
       "\tviewer_16234422255500019.addModel(\"@<TRIPOS>MOLECULE\\nRES\\n3 2 1 0 1\\nSMALL\\nNO_CHARGES\\n@<TRIPOS>CRYSIN\\n    7.0000    15.0000    15.0000    90.0000    90.0000    90.0000  1  1\\n@<TRIPOS>ATOM\\n       1 C            0.0000     0.0000     0.0000 C             1 RES     \\n       2 H            1.0000     0.0000     0.0000 H             1 RES     \\n       3 H           -1.0000     0.0000     0.0000 H             1 RES     \\n@<TRIPOS>BOND\\n       1        1        2 1\\n       2        3        1 1\\n@<TRIPOS>SUBSTRUCTURE\\n       1 RES             1 RESIDUE    0 **** ROOT      0\\n\",\"mol2\");\n",
       "\tviewer_16234422255500019.setStyle({\"stick\": {\"radius\": 0.2, \"color\": \"grey\"}, \"sphere\": {\"scale\": 0.3, \"colorscheme\": {}}});\n",
       "\tviewer_16234422255500019.zoomTo();\n",
       "viewer_16234422255500019.render();\n",
       "});\n",
       "</script>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "<py3Dmol.view at 0x7fe26877a7f0>"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ch2 = CH2()\n",
    "ch2.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Because we have inherited from `mb.Compound`, our `CH2` class has access to all of the attributes and methods of `Compound`. We can thus perform actions such as querying the particles contained within our `CH2` instance."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<C pos=([0. 0. 0.]), 0 bonds, id: 140610392133536>,\n",
       " <H pos=([0.1 0.  0. ]), 0 bonds, id: 140610392133008>,\n",
       " <H pos=([-0.1  0.   0. ]), 0 bonds, id: 140610392132912>]"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(ch2.particles())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also rename our `CH2` if we would like."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<myCH2 3 particles, non-periodic, 2 bonds, id: 140610392133440>"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ch2.name = 'myCH2'\n",
    "ch2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "While there are instances where creating `Compounds` particle-by-particle is useful, this process can become a bit tedious. It's much easier to create `Compounds` by loading pre-assembled building blocks. These can easily be created using software such as [Avogadro](https://avogadro.cc/).\n",
    "\n",
    "The `load` function can generate mBuild `Compounds` from a variety of common file formats (e.g. PDB, MOL2) that contain particle positions and bonds. Under the hood, mBuild uses readers from the [MDTraj package](http://mdtraj.org). Users are referred to the [MDTraj source](https://github.com/mdtraj/mdtraj/blob/b05b4637aaeda95fdf284a57ee2a37bc8e453ea1/mdtraj/core/trajectory.py#L77-L79) for a list of acceptable file formats. [Several additional formats](http://mdtraj.org/1.9.0/load_functions.html#format-specific-loading-functions) are also supported, but require an additional `topology` argument be specified.\n",
    "\n",
    "Let's take a look at the docstring for the `load` function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function load in module mbuild.conversion:\n",
      "\n",
      "load(filename_or_object, relative_to_module=None, compound=None, coords_only=False, rigid=False, smiles=False, infer_hierarchy=True, backend=None, ignore_box_warn=False, **kwargs)\n",
      "    Load a file or an existing topology into an mbuild Compound.\n",
      "    \n",
      "    Files are read using the MDTraj package unless the `use_parmed` argument is\n",
      "    specified as True.\n",
      "    Please refer to http://mdtraj.org/1.8.0/load_functions.html for formats\n",
      "    supported by MDTraj and https://parmed.github.io/ParmEd/html/readwrite.html\n",
      "    for formats supported by ParmEd.\n",
      "    \n",
      "    Parameters\n",
      "    ----------\n",
      "    filename_or_object : str, mdtraj.Trajectory, parmed.Structure,\n",
      "            mbuild.Compound, pybel.Molecule,\n",
      "        Name of the file or topology from which to load atom and bond\n",
      "        information.\n",
      "    relative_to_module : str, optional, default=None\n",
      "        Instead of looking in the current working directory, look for the file\n",
      "        where this module is defined. This is typically used in Compound\n",
      "        classes that will be instantiated from a different directory (such as\n",
      "        the Compounds located in mbuild.lib).\n",
      "    compound : mb.Compound, optional, default=None\n",
      "        Existing compound to load atom and bond information into. New structure\n",
      "        will be added to the existing compound as a sub compound.\n",
      "    coords_only : bool, optional, default=False\n",
      "        Only load the coordinates into an existing compound.\n",
      "    rigid : bool, optional, default=False\n",
      "        Treat the compound as a rigid body\n",
      "    backend : str, optional, default=None\n",
      "        Backend used to load structure from file or string. If not specified, a\n",
      "        default backend (extension specific) will be used.\n",
      "    smiles: bool, optional, default=False\n",
      "        Use RDKit or OpenBabel to parse filename as a SMILES string or file\n",
      "        containing a SMILES string. If this is set to True, `rdkit` is the\n",
      "        default backend.\n",
      "    infer_hierarchy : bool, optional, default=True\n",
      "        If True, infer hierarchy from chains and residues\n",
      "    ignore_box_warn : bool, optional, default=False\n",
      "        If True, ignore warning if no box is present. Defaults to True when\n",
      "        loading from SMILES\n",
      "    **kwargs : keyword arguments\n",
      "        Key word arguments passed to mdTraj, RDKit, or pybel for loading.\n",
      "    \n",
      "    Returns\n",
      "    -------\n",
      "    compound : mb.Compound\n",
      "    \n",
      "    Notes\n",
      "    -----\n",
      "    If `smiles` is `True`, either `rdkit` (default) or `pybel` can be used, but\n",
      "    RDkit is the only option of these that allows the user to specify a random\n",
      "    number seed to reproducibly generate the same starting structure. This is\n",
      "    NOT possible with `openbabel`, use `rdkit` if you need control over starting\n",
      "    structure's position (recommended).\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(mb.load)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we'll use `load` to again create a CH2 `Compound`, this time by loading from a PDB structure file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "class CH2(mb.Compound):\n",
    "    def __init__(self):\n",
    "        super(CH2, self).__init__()\n",
    "        \n",
    "        mb.load('utils/ch2.pdb', compound=self)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that by providing the `compound=self` argument to `mb.load` we will be loading the atom and bond information contained within our PDB file directly into our `CH2` class instance.\n",
    "\n",
    "**Note:** mBuild does not infer bonds (although you can achieve this with the [`generate_bonds`](http://mosdef-hub.github.io/mbuild/data_structures.html#mbuild.compound.Compound.generate_bonds) method). All bonds must be explicitly defined in your code or in a structure input file.\n",
    "\n",
    "If we take a look at an instance of this new `CH2` class, we will see that we get a similar result to when we constructed the `Compound` manually and that both particle positions and bond information have been loaded successfully."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/3dmoljs_load.v0": "<div id=\"3dmolviewer_1623442225779368\"  style=\"position: relative; width: 640px; height: 480px\">\n        <p id=\"3dmolwarning_1623442225779368\" style=\"background-color:#ffcccc;color:black\">You appear to be running in JupyterLab (or JavaScript failed to load for some other reason).  You need to install the 3dmol extension: <br>\n        <tt>jupyter labextension install jupyterlab_3dmol</tt></p>\n        </div>\n<script>\n\nvar loadScriptAsync = function(uri){\n  return new Promise((resolve, reject) => {\n    var tag = document.createElement('script');\n    tag.src = uri;\n    tag.async = true;\n    tag.onload = () => {\n      resolve();\n    };\n  var firstScriptTag = document.getElementsByTagName('script')[0];\n  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);\n});\n};\n\nif(typeof $3Dmolpromise === 'undefined') {\n$3Dmolpromise = null;\n  $3Dmolpromise = loadScriptAsync('https://3dmol.org/build/3Dmol.js');\n}\n\nvar viewer_1623442225779368 = null;\nvar warn = document.getElementById(\"3dmolwarning_1623442225779368\");\nif(warn) {\n    warn.parentNode.removeChild(warn);\n}\n$3Dmolpromise.then(function() {\nviewer_1623442225779368 = $3Dmol.createViewer($(\"#3dmolviewer_1623442225779368\"),{backgroundColor:\"white\"});\nviewer_1623442225779368.zoomTo();\n\tviewer_1623442225779368.addModel(\"@<TRIPOS>MOLECULE\\nRES\\n3 2 1 0 1\\nSMALL\\nNO_CHARGES\\n@<TRIPOS>CRYSIN\\n    7.2000    15.0000    15.0000    90.0000    90.0000    90.0000  1  1\\n@<TRIPOS>ATOM\\n       1 C            0.0000     0.0000     0.0000 C             1 RES     \\n       2 H           -1.1000     0.0000     0.0000 H             1 RES     \\n       3 H            1.1000     0.0000     0.0000 H             1 RES     \\n@<TRIPOS>BOND\\n       1        1        2 1\\n       2        3        1 1\\n@<TRIPOS>SUBSTRUCTURE\\n       1 RES             1 RESIDUE    0 **** ROOT      0\\n\",\"mol2\");\n\tviewer_1623442225779368.setStyle({\"stick\": {\"radius\": 0.2, \"color\": \"grey\"}, \"sphere\": {\"scale\": 0.3, \"colorscheme\": {}}});\n\tviewer_1623442225779368.zoomTo();\nviewer_1623442225779368.render();\n});\n</script>",
      "text/html": [
       "<div id=\"3dmolviewer_1623442225779368\"  style=\"position: relative; width: 640px; height: 480px\">\n",
       "        <p id=\"3dmolwarning_1623442225779368\" style=\"background-color:#ffcccc;color:black\">You appear to be running in JupyterLab (or JavaScript failed to load for some other reason).  You need to install the 3dmol extension: <br>\n",
       "        <tt>jupyter labextension install jupyterlab_3dmol</tt></p>\n",
       "        </div>\n",
       "<script>\n",
       "\n",
       "var loadScriptAsync = function(uri){\n",
       "  return new Promise((resolve, reject) => {\n",
       "    var tag = document.createElement('script');\n",
       "    tag.src = uri;\n",
       "    tag.async = true;\n",
       "    tag.onload = () => {\n",
       "      resolve();\n",
       "    };\n",
       "  var firstScriptTag = document.getElementsByTagName('script')[0];\n",
       "  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);\n",
       "});\n",
       "};\n",
       "\n",
       "if(typeof $3Dmolpromise === 'undefined') {\n",
       "$3Dmolpromise = null;\n",
       "  $3Dmolpromise = loadScriptAsync('https://3dmol.org/build/3Dmol.js');\n",
       "}\n",
       "\n",
       "var viewer_1623442225779368 = null;\n",
       "var warn = document.getElementById(\"3dmolwarning_1623442225779368\");\n",
       "if(warn) {\n",
       "    warn.parentNode.removeChild(warn);\n",
       "}\n",
       "$3Dmolpromise.then(function() {\n",
       "viewer_1623442225779368 = $3Dmol.createViewer($(\"#3dmolviewer_1623442225779368\"),{backgroundColor:\"white\"});\n",
       "viewer_1623442225779368.zoomTo();\n",
       "\tviewer_1623442225779368.addModel(\"@<TRIPOS>MOLECULE\\nRES\\n3 2 1 0 1\\nSMALL\\nNO_CHARGES\\n@<TRIPOS>CRYSIN\\n    7.2000    15.0000    15.0000    90.0000    90.0000    90.0000  1  1\\n@<TRIPOS>ATOM\\n       1 C            0.0000     0.0000     0.0000 C             1 RES     \\n       2 H           -1.1000     0.0000     0.0000 H             1 RES     \\n       3 H            1.1000     0.0000     0.0000 H             1 RES     \\n@<TRIPOS>BOND\\n       1        1        2 1\\n       2        3        1 1\\n@<TRIPOS>SUBSTRUCTURE\\n       1 RES             1 RESIDUE    0 **** ROOT      0\\n\",\"mol2\");\n",
       "\tviewer_1623442225779368.setStyle({\"stick\": {\"radius\": 0.2, \"color\": \"grey\"}, \"sphere\": {\"scale\": 0.3, \"colorscheme\": {}}});\n",
       "\tviewer_1623442225779368.zoomTo();\n",
       "viewer_1623442225779368.render();\n",
       "});\n",
       "</script>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "<py3Dmol.view at 0x7fe2687d0b50>"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ch2 = CH2()\n",
    "ch2.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "## Recap\n",
    "\n",
    "The goal of this tutorial was to demonstrate how routines for creating mBuild `Compounds` can be wrapped into classes, allowing for reusability. We also found that we can load information from structure files such as PDB or MOL2 to create `Compounds`.\n",
    "\n",
    "The next tutorial will demonstrate how another of mBuild's base classes, the `Port` class, can be used to create connections (bonds) between `Compounds` and move them in space."
   ]
  }
 ],
 "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.8.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}