{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# HTMD Membrane Builder - Making membrane building easy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Molecular dynamics simulations can be used to study biological membranes or even systems of proteins embedded in membranes. Such examples include the well-known GPCR proteins which are of high medical interest. Setting up a membrane simulation however can be quite challenging as they require tightly-packed pre-equilibrated membranes of different lipid compositions of different dimensions which are not always readily available.\n",
    "\n",
    "Tools such as CHARMM-GUI already exist which provide the functionality for creating such membranes with great flexibility, they cannot however be used programmatically or in a batch manner.\n",
    "\n",
    "HTMD provides a membrane builder tool which can be used to easily and quickly create a bilayer lipid membrane with a single command."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Quick example"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from htmd.membranebuilder.build_membrane import listLipids, buildMembrane\n",
    "\n",
    "# List all available lipids\n",
    "listLipids()\n",
    "# Define the dimensions of the membrane in the x and y axis in units of Angstrom\n",
    "dimensions = [50, 100]\n",
    "# Define the upper and lower layer lipid composition and ratio\n",
    "ratioupper = {'popc': 10, 'chl1': 3}\n",
    "ratiolower = {'popc': 8, 'chl1': 2}\n",
    "# Build the membrane\n",
    "memb = buildMembrane(dimensions, ratioupper, ratiolower)\n",
    "# Visualize the membrane\n",
    "memb.view()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Detailed explanation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from htmd.membranebuilder.build_membrane import listLipids, buildMembrane"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "MembraneBuilder provides two public functions:\n",
    "\n",
    " * listLipids: This function lists all lipids currently available in the lipids directory. New lipid PDB structures can be added to the listed directory and will be automatically picked up by the function.\n",
    " * buildMembrane: The main function which creates, minimizes and equilibrates the membrane."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "listLipids()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see this function lists the location of the single-lipid PDB files used to construct the membrane as well as a lipid CSV database file which will be discussed in the next section."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To build a membrane, the user needs to specify:\n",
    "\n",
    " 1. The dimensions of the membrane in the X and Y plane in units of Angstroms\n",
    " 2. The lipid composition of the upper and lower (on the Z axis) lipid layers. The key of the dictionary is the name of the lipid and the value associated with each lipid is the relative ratio of that lipid. The ratios don't need to sum to one as shown in the example where the ratio of `popc` to `chl1` in the upper layer is ten to three."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dimensions = [50, 100]\n",
    "ratioupper = {'popc': 10, 'chl1': 3}\n",
    "ratiolower = {'popc': 8, 'chl1': 2}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The membrane can then be built according to the specifications and viewed once completed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "memb = buildMembrane(dimensions, ratioupper, ratiolower)\n",
    "memb.view()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adding new lipids"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The MembraneBuilder is fully extensible for new lipid types. What is needed is only a PDB of a single lipid oriented along the Z-axis and ideally in an extended conformation, as well as some information about it. The extended conformation of the lipids helps with the initial lipid placement to avoid clashes and will therefore produce faster better membranes. During equilibration the lipids will then have time to adopt different conformations."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you might have noticed, `listLipids()` prints the available lipids as well as the path to a database comma-separated file. If we inspect this file we will find following contents:\n",
    "\n",
    "```\n",
    "Name,APL,Head,Thickness\n",
    "popc,68.3,P,36.7\n",
    "pope,58.8,P,36.7\n",
    "chl1,40.0,O3,36.7\n",
    "...\n",
    "```\n",
    "\n",
    "To add a new lipid to MembraneBuilder you therefore need to:\n",
    " 1. make a subfolder in the folder indicated by `listLipids()` with the name of the lipid, containing one or more PDB conformations of your lipid as separate PDB files\n",
    " 2. Include information about the lipid in the CSV database (`lipiddb.csv`). The information needed is:\n",
    "  1. The area-per-lipid (APL) in Angstroms\n",
    "  2. The name of the lipid head atom. The head atom is necessary to a) rotate the lipid around it's head in the Z-axis to reduce clashes and b) determine the position of the lipids on the Z-axis based on the membrane thickness.\n",
    "  3. The thickness of a lipid membrane of this type to determine at what negative and positize Z-axis positions to place the head of the lipid\n",
    "\n",
    "This information can be obtained either from publications or from the CHARMM-GUI lipid library which provides a large amount of lipids in varying conformations. \n",
    "  \n",
    "In the following figure you can see the extended POPC lipid oriented along the Z-axis with the tail pointing in the negative Z direction, as well as the lipid head P atom."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![](http://pub.htmd.org/tutorials/MembraneBuilder/download.png)"
   ]
  }
 ],
 "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.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}