diff --git a/polymers/polymers-example.ipynb b/polymers/polymers-example.ipynb
new file mode 100644
index 0000000..42a3ee5
--- /dev/null
+++ b/polymers/polymers-example.ipynb
@@ -0,0 +1,1526 @@
+{
+ "cells": [
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "Warning: importing 'simtk.openmm' is deprecated. Import 'openmm' instead.\n",
+ "RDKit WARNING: [11:43:11] Enabling RDKit 2019.09.3 jupyter extensions\n",
+ "[11:43:11] Enabling RDKit 2019.09.3 jupyter extensions\n"
+ ]
+ }
+ ],
+ "source": [
+ "import numpy as np\n",
+ "import matplotlib.pyplot as plt\n",
+ "\n",
+ "import mbuild as mb\n",
+ "from mbuild.lib.recipes.polymer import Polymer"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# The basic process for creating a polymer in mBuild\n",
+ "\n",
+ "The `Polymer` class exists in mBuild's library of recipes `mbuild/lib/recipes/polymer.py`\n",
+ "\n",
+ "In order to create polymers, mbuild Compounds of the monomer(s) and any end groups must first be created, and the necesasry mbuild Ports added to the correct atoms with the desired orientations. The compounds in mBuild's library contain structures that are essentially ready to go for building polymers. However, the ultimate goal of mBuild's polymer tool is to make it easier to build polymers from nearly any structures that are given to it whether in the form of a file or SMILES string.\n",
+ "\n",
+ "There are multiple ways to input the needed information to build a polymer. When creating a polymer instance, monomer and end group compounds can be directly passed in. This approach can be used when the compounds already contain the needed ports, there will be examples below.\n",
+ "\n",
+ "The other, much more flexible, option is to use the `add_monomer` and `add_end_groups` methods on a `Polymer` instnace.\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Building a polymer from SMILES\n",
+ "\n",
+ "In the example below, we will build up polyethylene, and add carboxylic acid end groups.\n",
+ "There are two primary bits of input required:\n",
+ "\n",
+ "1. A SMILES string of the monomer structure (and end group structure)\n",
+ "2. The indices of the hydrogen atoms that will be replaced to make room for the monomer-monomer bonding\n",
+ "\n",
+ "Step 2 will require a bit of trial and error"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "application/3dmoljs_load.v0": "
\n
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n jupyter labextension install jupyterlab_3dmol
\n
\n",
+ "text/html": [
+ "
\n",
+ "
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n",
+ " jupyter labextension install jupyterlab_3dmol
\n",
+ "
\n",
+ ""
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "# Quick example of the API and workflow\n",
+ "comp = mb.load('CC', smiles=True) # mBuild compound of the monomer unit\n",
+ "chain = Polymer()\n",
+ "\n",
+ "chain.add_monomer(compound=comp,\n",
+ " indices=[2, -2],\n",
+ " separation=.15,\n",
+ " replace=True)\n",
+ "\n",
+ "chain.add_end_groups(mb.load('C(=O)O', # Capping off this polymer with Carboxylic acid groups\n",
+ " smiles=True,\n",
+ " name='acid'), \n",
+ " index=3,\n",
+ " separation=0.15)\n",
+ "\n",
+ "chain.build(n=7, sequence='A') # After monomers and end groups are added, call the build function\n",
+ "chain.visualize(show_ports=True).show()"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "application/3dmoljs_load.v0": "
\n
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n jupyter labextension install jupyterlab_3dmol
\n
\n",
+ "text/html": [
+ "
\n",
+ "
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n",
+ " jupyter labextension install jupyterlab_3dmol
\n",
+ "
\n",
+ ""
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "# Doing the same thing, but this time without adding an end group\n",
+ "# Now, the chain is capped with hydrogens (default behavior)\n",
+ "\n",
+ "comp = mb.load('CC', smiles=True) # mBuild compound of the monomer unit\n",
+ "chain = Polymer()\n",
+ "\n",
+ "chain.add_monomer(compound=comp,\n",
+ " indices=[2, -2],\n",
+ " separation=.15,\n",
+ " replace=True)\n",
+ "\n",
+ "chain.build(n=10, sequence='A')\n",
+ "chain.visualize(show_ports=True).show()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Selecting the correct values for `indices`\n",
+ "\n",
+ "As mentioned earlier, you have to provide information about which atoms on the monomer and end group will form the bonds between repeating monomers, and between the end groups. In this case, you are specificy the index of the hydrogen atoms that will be removed.\n",
+ "\n",
+ "Above, we chose `indices = [2, -2]` for the monomer units. What would happen if we chose the \"wrong\" indices?\n",
+ "\n",
+ "The cell below shows the incorrect structures that can come about from choosing the wrong indices."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 10,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "application/3dmoljs_load.v0": "
\n
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n jupyter labextension install jupyterlab_3dmol
\n
\n",
+ "text/html": [
+ "
\n",
+ "
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n",
+ " jupyter labextension install jupyterlab_3dmol
\n",
+ "
\n",
+ ""
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "# Doing the same thing, but this time without adding an end group\n",
+ "# Now, the chain is capped with hydrogens (default behavior)\n",
+ "\n",
+ "comp = mb.load('CC', smiles=True) # mBuild compound of the monomer unit\n",
+ "chain = Polymer()\n",
+ "\n",
+ "chain.add_monomer(compound=comp,\n",
+ " indices=[-1, -2],\n",
+ " separation=.15,\n",
+ " replace=True)\n",
+ "\n",
+ "chain.build(n=10, sequence='A')\n",
+ "chain.visualize(show_ports=True).show()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Flexibility with end groups\n",
+ "- You can only add one end group, while the other is capped off with hydrogen.\n",
+ "- You can add 2 different end groups, labeled by 'head' and 'tail'\n",
+ "- Or you can leave the ends open with an available port"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 11,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "application/3dmoljs_load.v0": "
\n
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n jupyter labextension install jupyterlab_3dmol
\n
\n",
+ "text/html": [
+ "
\n",
+ "
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n",
+ " jupyter labextension install jupyterlab_3dmol
\n",
+ "
\n",
+ ""
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "# Creating and adding 2 different end groups.\n",
+ "# The add_end_groups() function has a duplicate parameter (defaulted to True)\n",
+ "# When this is true, calling add_end_group will create 2 of the same compound\n",
+ "# and the polymer is capped off with each.\n",
+ "# If you want different end groups, change Duplicate to False and call the add_end_groups() function twice\n",
+ "\n",
+ "comp = mb.load('CC', smiles=True) # mBuild compound of the monomer unit\n",
+ "chain = Polymer()\n",
+ "\n",
+ "chain.add_monomer(compound=comp,\n",
+ " indices=[2, -2],\n",
+ " separation=.15,\n",
+ " replace=True)\n",
+ "\n",
+ "chain.add_end_groups(mb.load('C(=O)O',smiles=True), # Capping off this polymer with Carboxylic acid groups\n",
+ " index=3,\n",
+ " separation=0.15,\n",
+ " duplicate=False) # Change duplicate to false\n",
+ "\n",
+ "chain.add_end_groups(mb.load('N', smiles=True),\n",
+ " index=-1, separation=0.13,\n",
+ " duplicate=False, label=\"tail\") # label this one tail\n",
+ "\n",
+ "chain.build(n=10, sequence='A')\n",
+ "chain.visualize(show_ports=True).show()"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 12,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "application/3dmoljs_load.v0": "
\n
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n jupyter labextension install jupyterlab_3dmol
\n
\n",
+ "text/html": [
+ "
\n",
+ "
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n",
+ " jupyter labextension install jupyterlab_3dmol
\n",
+ "
\n",
+ ""
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "# If you only add one end group, you can still have the other end capped off with hydrogen\n",
+ "comp = mb.load('CC', smiles=True) # mBuild compound of the monomer unit\n",
+ "chain = Polymer()\n",
+ "\n",
+ "chain.add_monomer(compound=comp,\n",
+ " indices=[2, -2],\n",
+ " separation=.15)\n",
+ "\n",
+ "chain.add_end_groups(mb.load('C(=O)O',smiles=True), # Capping off this polymer with Carboxylic acid groups\n",
+ " index=3,\n",
+ " separation=0.15,\n",
+ " duplicate=False) # Change duplicate to false\n",
+ "\n",
+ "chain.build(n=10, sequence='A')\n",
+ "chain.visualize(show_ports=True).show()"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 13,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "application/3dmoljs_load.v0": "
\n
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n jupyter labextension install jupyterlab_3dmol
\n
\n",
+ "text/html": [
+ "
\n",
+ "
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n",
+ " jupyter labextension install jupyterlab_3dmol
\n",
+ "
\n",
+ ""
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "#Or to leave the ends of the polymer open with ports, change the add_hydrogens parameter in build() to False\n",
+ "# This would still work when adding only one end group, then leaving the other end open.\n",
+ "\n",
+ "comp = mb.load('CC', smiles=True) # mBuild compound of the monomer unit\n",
+ "chain = Polymer()\n",
+ "chain.add_monomer(compound=comp,\n",
+ " indices=[2, -2],\n",
+ " separation=.15,\n",
+ " replace=True)\n",
+ "\n",
+ "chain.build(n=10, sequence='A', add_hydrogens=False)\n",
+ "chain.visualize(show_ports=True).show()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Here is an example building up a Nylon polymer"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 54,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "application/3dmoljs_load.v0": "
\n
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n jupyter labextension install jupyterlab_3dmol
\n
\n",
+ "text/html": [
+ "
\n",
+ "
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n",
+ " jupyter labextension install jupyterlab_3dmol
\n",
+ "
\n",
+ ""
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "nylon = mb.load(\"NCCCCCCNOC(=O)CCCCC(=O)O\", smiles=True)\n",
+ "chain = Polymer()\n",
+ "\n",
+ "chain.add_monomer(compound=nylon, indices=[-23, -1], separation=.15)\n",
+ "chain.build(n=4, sequence='A')\n",
+ "chain.visualize().show()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Here's an example with a more complicated monomer and a little more detail into what's going on \n",
+ "\n",
+ "SMILES strings for Poly-ether-ether-ketone (PEEK) \n",
+ "\n",
+ "One has para linkages, the other has meta \n",
+ "\n",
+ "Goal is to build up a polymer with alternating PARA-META monomers "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 15,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "application/3dmoljs_load.v0": "
\n
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n jupyter labextension install jupyterlab_3dmol
\n
\n",
+ "text/html": [
+ "
\n",
+ "
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n",
+ " jupyter labextension install jupyterlab_3dmol
\n",
+ "
\n",
+ ""
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "peek_para = mb.load(\"Oc1ccc(Oc2ccc(C(=O)c3ccccc3)cc2)cc1\", smiles=True)\n",
+ "peek_meta = mb.load(\"Oc1cc(Oc2ccc(C(=O)c3ccccc3)cc2)ccc1\", smiles=True)\n",
+ "peek_polymer = Polymer()\n",
+ "\n",
+ "peek_polymer.add_monomer(compound=peek_para,\n",
+ " indices = [22, 29],\n",
+ " separation = 0.1376,\n",
+ " replace=True\n",
+ " )\n",
+ "\n",
+ "peek_polymer.add_monomer(compound=peek_meta,\n",
+ " indices = [22, 28],\n",
+ " separation = 0.1376,\n",
+ " replace=True\n",
+ " )\n",
+ "\n",
+ "peek_polymer.build(n=3, sequence=\"AB\")\n",
+ "peek_polymer.visualize().show()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## A look at what is actually happening with each of the class methods \n",
+ "\n",
+ "The `add_monomer` and `add_end_group` functions are handling the creation of ports. \n",
+ "\n",
+ "The key is in the `bond_indices` and `replace` parameters.\n",
+ "`bond_indices` points to the hydrogen atoms that are occupying the polymer bonding site and \n",
+ "`replace` says to remove those atoms, and replace them with a port\n",
+ "\n",
+ "When the port is created, it defaults to using the orientation that already existed between the hydrogen atom and the atom it was bonded to. "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 16,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Before passing the compound into add_monomer()\n"
+ ]
+ },
+ {
+ "data": {
+ "application/3dmoljs_load.v0": "
\n
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n jupyter labextension install jupyterlab_3dmol
\n
\n",
+ "text/html": [
+ "
\n",
+ "
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n",
+ " jupyter labextension install jupyterlab_3dmol
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n jupyter labextension install jupyterlab_3dmol
\n
\n",
+ "text/html": [
+ "
\n",
+ "
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n",
+ " jupyter labextension install jupyterlab_3dmol
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n jupyter labextension install jupyterlab_3dmol
\n
\n",
+ "text/html": [
+ "
\n",
+ "
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n",
+ " jupyter labextension install jupyterlab_3dmol
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n jupyter labextension install jupyterlab_3dmol
\n
\n",
+ "text/html": [
+ "
\n",
+ "
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n",
+ " jupyter labextension install jupyterlab_3dmol
\n",
+ "
\n",
+ ""
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "# Same thing with the end group\n",
+ "ca = mb.load('C(=O)O', smiles=True)\n",
+ "print('Before passing the compound into add_end_groups()')\n",
+ "ca.visualize(show_ports=True).show()\n",
+ "\n",
+ "peek_polymer.add_end_groups(ca,\n",
+ " index=3,\n",
+ " separation=0.13,\n",
+ " replace=True)\n",
+ "\n",
+ "# ca[3] is the hydrogen bonded to the carbon atom\n",
+ "\n",
+ "print('After passing the compound into add_end_groups()')\n",
+ "peek_polymer.end_groups[0].visualize(show_ports=True).show()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Not using the add_monomer and add_end_group functions\n",
+ "- So far, the examples call these functions everytime to create a polymer, but they are optional\n",
+ "- These functions basically handle the creation of ports.\n",
+ "- If you have a compound where the ports already exist, or you want to add them yourself you can pass them into the polymer class instance, and go straight to the build() function.\n",
+ "- However, you can use both approaches for the same polymer. Passing in compounds when initializing a polymer, and then adding to self.monomers or self.end_groups with the add functions."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 26,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "application/3dmoljs_load.v0": "
\n
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n jupyter labextension install jupyterlab_3dmol
\n
\n",
+ "text/html": [
+ "
\n",
+ "
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n",
+ " jupyter labextension install jupyterlab_3dmol
\n",
+ "
\n",
+ ""
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "# In this example, we're using a CH2 compound from mBuild's library. This compound already has ports created\n",
+ "# So, we can skip the add_monomer method and go straight to build.\n",
+ "from mbuild.lib.moieties.ch2 import CH2\n",
+ "\n",
+ "chain = Polymer(monomers=[CH2()])\n",
+ "chain.build(n=10, add_hydrogens=True)\n",
+ "chain.visualize().show()"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 19,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "application/3dmoljs_load.v0": "
\n
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n jupyter labextension install jupyterlab_3dmol
\n
\n",
+ "text/html": [
+ "
\n",
+ "
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n",
+ " jupyter labextension install jupyterlab_3dmol
\n",
+ "
\n",
+ ""
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "# You can combine passing in compounds, and using the available \n",
+ "# add_end_group and add_monomer functions\n",
+ "\n",
+ "chain = Polymer(monomers=[CH2()])\n",
+ "chain.add_monomer(mb.load('c1ccccc1', smiles=True), indices=[-1, -4])\n",
+ "chain.add_end_groups(mb.load('C(=O)O',smiles=True), # Capping off this polymer with Carboxylic acid groups\n",
+ " index=3,\n",
+ " separation=0.15,\n",
+ " duplicate=False)\n",
+ "chain.build(n=5,sequence='AB', add_hydrogens=True)\n",
+ "chain.visualize().show()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Some more use case examples\n",
+ "\n",
+ "- Creating regio-regular backbone\n",
+ "- Creating a poly disperse system\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 56,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "application/3dmoljs_load.v0": "
\n
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n jupyter labextension install jupyterlab_3dmol
\n
\n",
+ "text/html": [
+ "
\n",
+ "
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n",
+ " jupyter labextension install jupyterlab_3dmol
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n jupyter labextension install jupyterlab_3dmol
\n
\n",
+ "text/html": [
+ "
\n",
+ "
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n",
+ " jupyter labextension install jupyterlab_3dmol
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n jupyter labextension install jupyterlab_3dmol
\n
\n",
+ "text/html": [
+ "
\n",
+ "
You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension: \n",
+ " jupyter labextension install jupyterlab_3dmol