mBuild_06_Setting_Up_Bulk_Systems.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "# mBuild Tutorial 06: Setting Up Bulk Systems\n",
    "\n",
    "This tutorial demostrates several ways in which to create bulk systems using mBuild."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As in the prior tutorials, we need to first import mbuild (here as `mb`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import mbuild as mb"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, we will import the `Alkane` class that is part of mBuild, to create a simple hexane molecule.  Note, this class is similar to the  Alkane class constructed in the prior tutorials. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mbuild.examples import Alkane\n",
    "\n",
    "hexane = Alkane(6)\n",
    "\n",
    "hexane.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To create a simple system, one could manually (or via a loop) duplicate the hexane molecule. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#first shift the hexane such that its center of mass is at the origin\n",
    "hexane.translate(-(hexane.center))\n",
    "\n",
    "box_of_hexanes = mb.Compound()\n",
    "\n",
    "#place items on a grid via a simple loop\n",
    "for i in range(0,3):\n",
    "    for j in range(0,3):\n",
    "        for k in range(0,3):\n",
    "            temp_hexane = mb.clone(hexane)\n",
    "            pos = [i, j*1.5, k]\n",
    "            temp_hexane.translate_to(pos)\n",
    "            box_of_hexanes.add(temp_hexane)\n",
    "\n",
    "box_of_hexanes.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, one can use a one of the mBuild pattern functions to define a grid of points.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "box_of_hexanes = mb.Compound()\n",
    "\n",
    "grid3d = mb.Grid3DPattern(3, 3, 3)\n",
    "\n",
    "#the pattern is defined from 0 to 1\n",
    "#thus we will scale it by 3.0 to be the same as above\n",
    "grid3d.scale(3.0)\n",
    "for position in grid3d:\n",
    "    temp_hexane = mb.clone(hexane)\n",
    "    #scale up the spacing in the y direction\n",
    "    position[1] = position[1]*1.5\n",
    "    temp_hexane.translate_to(position)\n",
    "    box_of_hexanes.add(temp_hexane)\n",
    "\n",
    "box_of_hexanes.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also use the spin command to provide a uniform tilt to the molecules or a random orientation for each molecule.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "box_of_hexanes = mb.Compound()\n",
    "\n",
    "grid3d = mb.Grid3DPattern(4, 1, 4)\n",
    "\n",
    "grid3d.scale(2.0)\n",
    "for position in grid3d:\n",
    "    temp_hexane = mb.clone(hexane)\n",
    "    temp_hexane.spin(0.5, around=[1,0,0])\n",
    "    temp_hexane.translate_to(position)\n",
    "    box_of_hexanes.add(temp_hexane)\n",
    "\n",
    "box_of_hexanes.visualize()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import random\n",
    "from numpy import pi\n",
    "box_of_hexanes = mb.Compound()\n",
    "\n",
    "grid3d = mb.Grid3DPattern(4, 1, 4)\n",
    "\n",
    "rnd = random.Random()\n",
    "rnd.seed(123)\n",
    "    \n",
    "grid3d.scale(5.0)\n",
    "for position in grid3d:\n",
    "    temp_hexane = mb.clone(hexane)\n",
    "    #randomly rotate around each of the axes\n",
    "    temp_hexane.spin(rnd.uniform(0, 2 * pi), around=[1,0,0])\n",
    "    temp_hexane.spin(rnd.uniform(0, 2 * pi), around=[0,1,0])\n",
    "    temp_hexane.spin(rnd.uniform(0, 2 * pi), around=[0,0,1])\n",
    "    temp_hexane.translate_to(position)\n",
    "    box_of_hexanes.add(temp_hexane)\n",
    "\n",
    "box_of_hexanes.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using Packmol"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In cases where it may be desirable to create randomized initial configurations, especially one of higher density, mBuild can interface with [packmol](http://www.ime.unicamp.br/~martinez/packmol) using the `fill_box` routine.\n",
    "\n",
    "Let's take a look at the docstring for the `fill_box` function. Note that several optional arguments are available including a `seed` for PACKMOL's random number generator and `overlap` to control how close any two particles may be."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "help(mb.fill_box)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, first define a box (again, note, dimensions are in nanometers) and use the `fill_box` command to create `n` copies of our hexane molecule (here set to be 10)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "box = mb.Box(lengths=[5, 5, 5])\n",
    "\n",
    "box_of_hexanes = mb.fill_box(compound=hexane, n_compounds=10, box=box)\n",
    "box_of_hexanes.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To create a system with more than a single type of molecule, we can use the solvate command. To additionally demonstrate functionality, we will create a perfluorohexane molecule, whereby hydrogen atoms are swapped with fluorine."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "perfluorohexane = Alkane(6)\n",
    "for particle in perfluorohexane.particles():\n",
    "    if particle.name == 'H':\n",
    "        particle.name = 'F'\n",
    "\n",
    "perfluorohexane.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To solvate, we can take our previously defined system (`box_of_hexanes`) and pass perfluorohexane as our solvent. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "box_of_chains = mb.solvate(solute=box_of_hexanes, solvent=perfluorohexane, n_solvent=10, box=box)\n",
    "box_of_chains.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, the `fill_box` routine can take an array of `Compounds` (note, `n_compounds` must also be an array of corresponding length). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "box_of_chains = mb.fill_box(compound=[hexane, perfluorohexane], n_compounds=[10, 10], box=box)\n",
    "box_of_chains.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "## Recap\n",
    "\n",
    "The goal of this tutorial was to demonstrate several ways that mBuild can be used to generate systems of bulk molecules.\n",
    "\n",
    "The next tutorial will teach you how to use mBuild's built-in energy minimization routine."
   ]
  },
  {
   "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.5.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}