Session1-MoSDeF_Tutorial/Intro_to_MoSDeF.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "# Introduction to MoSDeF\n",
    "\n",
    "This tutorial is designed to introduce you to the primary goal of mBuild - to create complex molecular systems in a flexible fashion that allows system structure to be easily changed. \n",
    "\n",
    "You will learn about the hierarchical data structure of mBuild `Compounds` and will have the ability to play around with some pre-built mBuild classes to observe how system structure can be changed by providing a few simple top-level variables."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "### Hierarchical design approach\n",
    "\n",
    "mBuild uses a [composite design pattern](https://en.wikipedia.org/wiki/Composite_pattern) to approach the creation of complex molecular systems. This has the following features:\n",
    "* Molecules have a tree-like hierarchy (as shown below)\n",
    "* All components in the hierarchy have a common data structure (an mBuild `Compound`)\n",
    "* The lowest level of the hierarchy (the 'leaves') are referred to as `Particles` and are usually individual atoms\n",
    "* Atomic positions are stored _only_ at the **`Particle`** level; higher level components can compute properties based on contained `Particles`\n",
    "\n",
    "Below is an example of an mBuild molecule hierarchy for an alkylsilane monolayer attached to a crystalline silica surface.\n",
    "<img src=\"../images/hierarchical_design_image.png\" alt=\"Drawing\" style=\"width: 700px;\"/>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Primer on using Jupyter notebooks\n",
    "\n",
    "A more detailed introduction to Jupyter Notebooks can be found [here](Intro_to_Jupyter.ipynb)\n",
    "\n",
    "[Jupyter notebooks](https://jupyter-notebook.readthedocs.io/en/stable/) provide an interactive environment for \"developing, documenting, and executing code\". Several languages are supported; however here we will be using Python. \n",
    "\n",
    "Jupyter notebooks feature two primary types of cells:\n",
    "1. Markdown cells, like this cell, which contain explanatory text\n",
    "2. Code cells, that can be executed by either clicking on the \"run cell\" icon or by hitting <kbd>SHIFT</kbd> + <kbd>RET</kbd>.\n",
    "\n",
    "Cells do not have to be executed in order (however the cells in this tutorial are designed to be executed sequentially), and the order in which cells have been executed is recorded by the bracketed number to the left of the code cell (e.g. [ 1 ]). When a cell is executed you will first see an asterisk (i.e. [ * ]) which means that the cell is still running. When the asterisk is replaced by a number this means the execution has completed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Importing mBuild\n",
    "\n",
    "To use mBuild we need to import the mBuild package, which is available through both the [Anaconda](https://anaconda.org/mosdef/mbuild) and [pip](https://pypi.python.org/pypi/mbuild/0.7.2) package managers. mBuild can also be downloaded from source, which is hosted on [Github](https://github.com/mosdef-hub/mbuild)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import mbuild as mb"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Examples\n",
    "\n",
    "Here, we'll explore some examples of mBuild `Compound` classes that have been pre-defined. Each have several variables that can be manipulated to modify the system of interest."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "mBuild is designed using the [object-oriented programming (OOP)](https://en.wikipedia.org/wiki/Object-oriented_programming) design paradigm. We will refer to common terms used in this paradigm, which have been defined below.\n",
    "\n",
    "### Key Object-Oriented Terms\n",
    "\n",
    "* **Class**\n",
    "    - code that contains the definitions for the data format and operations on the data\n",
    "* **Object**\n",
    "    - specific instances of a class, with its own individual data\n",
    "* **Instantiation**\n",
    "    - creation of an object from a class definition\n",
    "\n",
    "### Alkanes\n",
    "\n",
    "The `Alkane` example class allows one to create an alkane chain with a chain length (number of carbons) specified by the `n` argument.\n",
    "\n",
    "First, we will import the `Alkane` class and use Python's `help` function to inspect the class constructor, which will reveal the arguments we are able to provide during instantiation (creation of the object) to customize our `Compound`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mbuild.examples import Alkane\n",
    "\n",
    "help(Alkane.__init__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We see that there are three arguments we can provide when creating an `Alkane`, specifying the chain length and also whether or not we want to cap either end of the chain with a methyl group. Note that each of these arguments possesses a default value, and instantiating an `Alkane` without additional arguments will yield a propane chain.\n",
    "\n",
    "However, here we'll pass `n=4` to our `Alkane` creation to yield an alkane with four carbons, i.e. butane.\n",
    "\n",
    "The `visualize` method can be used to visualize our molecule interactively within the notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "butane = Alkane(n=4)\n",
    "butane.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We are not restricted to just creating butane by using the `Alkane` class, however. By having the chain length as a tunable argument, we can easily create chains of any length. Here we'll simply change `n=4` to `n=10` to yield a decane molecule."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "decane = Alkane(n=10)\n",
    "decane.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By providing arguments when instantiating a `Compound`, this allow us to tune the underlying chemistry and structure, it becomes easy to create systems that span wide parameter spaces by altering a few top-level variables. This allows mBuild to become a valuable tool for screening-type studies.\n",
    "\n",
    "We'll demonstrate this behavior once more by passing the `cap_end=False` argument to the instatiation of our decane chain. This will leave a `Port` on one end of the chain. You will learn more about `Port`s in a later tutorial, but briefly, these are what allow us to connect `Compound`s together. By leaving an open `Port` on the end of the alkane chain, we could now, e.g. make copies of the chain and functionalize a surface with them (as you will see in the following examples)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "decane = Alkane(n=10, cap_end=False)\n",
    "decane.visualize(show_ports=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Alkylsilane monolayers\n",
    "\n",
    "The `AlkaneMonolayer` class constructs an alkylsilane monolayer on crystalline silica.  The `pattern` argument can be used to define where chains are placed on the surface. The `tile_x` and `tile_y` arguments can be used to replicate the surface in the $x$ and $y$ dimensions. And the `chain_length` argument can be used to tune the length of the alkylsilane chains.\n",
    "\n",
    "First, we'll import the class and take a look at its constructor."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mbuild.examples import AlkaneMonolayer\n",
    "\n",
    "help(AlkaneMonolayer.__init__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we'll create a couple of different systems by varying the arguments we provide upon instantiation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "monolayer = AlkaneMonolayer(pattern=mb.Grid2DPattern(n=5, m=5), tile_x=1, tile_y=1, chain_length=20)\n",
    "monolayer.visualize()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "monolayer = AlkaneMonolayer(pattern=mb.Random2DPattern(n=100), tile_x=2, tile_y=3, chain_length=5)\n",
    "monolayer.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Tethered nanospheres\n",
    "\n",
    "The TetheredNanosphere (`Tnp`) class is more abstract than the previous two classes, and defines a nanoparticle constructed of uniformly spaced beads representing arbitrary polymer tethers. The `ball_radius` class can be used to tune the size of the nanoparticle. While the `n_chains` and `chain_length` arguments can be used to tune the number and length of the polymer tethers.\n",
    "\n",
    "Again, we'll first import the class and view the constructor."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mbuild.examples.tnp.tnp import Tnp\n",
    "\n",
    "help(Tnp.__init__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we will create a couple variations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "tnp = Tnp(ball_radius=10, n_chains=4, chain_length=10)\n",
    "tnp.visualize()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tnp = Tnp(ball_radius=5, n_chains=20, chain_length=5)\n",
    "tnp.visualize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Recap\n",
    "\n",
    "The goal of this tutorial was to demonstrate how with mBuild classes the chemistry of complex molecular systems can be easily tuned. In the following lessons, you will learn how to construct these classes so that you can begin using mBuild in your own research!"
   ]
  }
 ],
 "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
}