docs/tutorials/tutorial_monolayer.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Monolayer: Complex hierarchies, patterns, tiling and writing to files\n",
    "---------------------------------------------------------------\n",
    "\n",
    "__Note__: mBuild expects all distance units to be in nanometers.\n",
    "\n",
    "In this example, we'll cover assembling more complex hierarchies of components using patterns, tiling and how to output systems to files. To illustrate these concepts, let's build an alkane monolayer on a crystalline substrate.\n",
    "\n",
    "First, let's build our monomers and functionalized them with a silane group which we can then attach to the substrate. The `Alkane` example uses the `polymer` tool to combine `CH2` and `CH3` repeat units. You also have the option to cap the front and back of the chain or to leave a `CH2` group with a dangling port. The `Silane` compound is a Si(OH)<sub>2</sub> group with two ports facing out from the central Si. Lastly, we combine `alkane` with `silane` and add a label to `AlkylSilane` which points to, `silane['down']`. This allows us to reference it later using `AlkylSilane['down']` rather than `AlkylSilane['silane']['down']`.\n",
    "\n",
    "__Note:__ In `Compounds` with multiple `Ports`, by convention, we try to label every `Port` successively as 'up', 'down', 'left', 'right', 'front', 'back' which should roughly correspond to their relative orientations. This is a bit tricky to enforce because the system is so flexible so use your best judgement and try to be consistent! The more components we collect in our library with the same labeling conventions, the easier it becomes to build ever more complex structures."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import mbuild as mb\n",
    "\n",
    "from mbuild.examples import Alkane\n",
    "from mbuild.lib.moieties import Silane\n",
    "\n",
    "\n",
    "class AlkylSilane(mb.Compound):\n",
    "    \"\"\"A silane functionalized alkane chain with one Port. \"\"\"\n",
    "    def __init__(self, chain_length):\n",
    "        super(AlkylSilane, self).__init__()\n",
    "\n",
    "        alkane = Alkane(chain_length, cap_end=False)\n",
    "        self.add(alkane, 'alkane')\n",
    "        silane = Silane()\n",
    "        self.add(silane, 'silane')\n",
    "        mb.force_overlap(self['alkane'], self['alkane']['down'], self['silane']['up'])\n",
    "\n",
    "        # Hoist silane port to AlkylSilane level.\n",
    "        self.add(silane['down'], 'down', containment=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "AlkylSilane(5).visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's create a substrate to which we can later attach our monomers:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import mbuild as mb\n",
    "from mbuild.lib.surfaces import Betacristobalite\n",
    "\n",
    "surface = Betacristobalite()\n",
    "tiled_surface = mb.lib.recipes.TiledCompound(surface, n_tiles=(2, 1, 1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we've imported a beta-cristobalite surface from our component library. The `TiledCompound` tool allows you replicate any `Compound` in the x-, y-\n",
    "and z-directions by any number of times - 2, 1 and 1 for our case.\n",
    "\n",
    "Next, let's create our monomer and a hydrogen atom that we'll place on unoccupied surface sites:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mbuild.lib.atoms import H\n",
    "alkylsilane = AlkylSilane(chain_length=10)\n",
    "hydrogen = H()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then we need to tell mBuild how to arrange the chains on the surface. This is accomplished with the \"pattern\" tools. Every pattern is just a collection of points. There are all kinds of patterns like spherical, 2D, regular, irregular etc. When you use the `apply_pattern` command, you effectively superimpose the pattern onto the host compound, mBuild figures out what the closest ports are to the pattern points and then attaches copies of the guest onto the binding sites identified by the pattern:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pattern = mb.Grid2DPattern(8, 8)  # Evenly spaced, 2D grid of points.\n",
    "\n",
    "# Attach chains to specified binding sites. Other sites get a hydrogen.\n",
    "chains, hydrogens = pattern.apply_to_compound(host=tiled_surface, guest=alkylsilane, backfill=hydrogen)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Also note the `backfill` optional argument which allows you to place a different compound on any unused ports. In this case we want to backfill with hydrogen atoms on every port without a chain.\n",
    "\n",
    "\n",
    "And that's it! Check out `examples.alkane_monolayer` for the fully wrapped class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "monolayer = mb.Compound([tiled_surface, chains, hydrogens])\n",
    "monolayer.visualize() # Warning: may be slow in IPython notebooks"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Save as .mol2 file\n",
    "monolayer.save('monolayer.mol2', overwrite=True)"
   ]
  }
 ],
 "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.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}