Foyer_00_Getting_Started.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "# Foyer Tutorial 00: Getting Started\n",
    "\n",
    "This tutorial focuses on the basic structure of the XML-formatted Foyer force field file."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Classical Force fields\n",
    "Classical force fields, which describe the interaction between atoms, typically contain numerous fitting parameters, allowing them to be tuned to describe the behavior of atoms in various chemical environments.  For example, consider carbon in various local bonded environments: \n",
    "- As a terminal methyl group in an alkane, i.e., C-CH3\n",
    "- As a terminal fluorinated methyl group, i.e., C-CF3\n",
    "- As a terminal group in an alkene, i.e., C=CH2\n",
    "\n",
    "Even though the element does not change (i.e., we are dealing with carbon in each case), the force field fitting parameters (e.g., Lennard-Jones epsilon and partial charges) will be different in most force fields.  As such, force field databases may contain 10s or 100s of parameters for a given element, where each set of parameters is referred to as an 'atom-type', defining the element in a different chemical context.\n",
    "\n",
    "Properly determining the correct set of parameters for a given element (i.e., identifying which atom-type should be used), can be a difficult and error-prone task, but essential for the final results of a simulation to be correct.   \n",
    "\n",
    "Foyer has been developed as both a scheme to encode these rules for atom-typing along with a software that evaluates these rules. Here we will first focus on the scheme to encode rules and the associated file format. \n",
    "\n",
    "### Foyer XML format\n",
    "\n",
    "Foyer force fields are defined within an XML file that contains both the 'rules' required for atomtyping as well as the force field parameters within a single file. The Foyer XML format is an extension of the [OpenMM forcefield XML format](http://docs.openmm.org/7.0.0/userguide/application.html#creating-force-fields). The only differences reside in the `AtomTypes` section, where several additional attributes are available (which we will examine in a moment) that allow for atomtyping.\n",
    "\n",
    "Let us examine the basic structure of a Foyer XML file."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### AtomTypes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! sed -n 34,40p utils/OPLSaa_perfluoroalkanes.xml"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `AtomTypes` section of the Foyer XML is similar to that used for OpenMM forcefield XMLs; however, each `Type` in Foyer XML supports four additional attributes not found in OpenMM:\n",
    "* `def` - SMARTS string describing the chemical substructure of this atomtype (Follow [this link](https://github.com/mosdef-hub/foyer/blob/master/docs/smarts.md) for more on SMARTS-based atomtyping using Foyer.)\n",
    "* `desc` - Brief description of the atomtype\n",
    "* `doi` - DOI reference for parameters associated with this atomtype\n",
    "* `overrides` - One or more atomtypes to 'override', providing precedence to this atomtype\n",
    "\n",
    "[SMARTS](http://www.daylight.com/dayhtml/doc/theory/theory.smarts.html), which is used to define usage of a given atom-type, is a language for describing chemical structures and substructures.  This chemical context effectively defines the 'rules' for when an atomtype should apply.  For example, for atom_type `opls_961`, the SMARTS string,  `def=\"[C;X4](F)(F)(F)(C)\"`, states that this atom-type should be used when:\n",
    "- your element is carbon and has 4 neighbors, i.e., `[C;X4]`\n",
    "- three neighbors are F, i.e., `(F)(F)(F)`\n",
    "- one neighbor is C, i.e., `(C)`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Forcefield parameters\n",
    "\n",
    "The remaining sections of the Foyer XML are currently the same as defined in the OpenMM format and feature both bonded and nonbonded forcefield parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! sed -n 41,62p utils/OPLSaa_perfluoroalkanes.xml"
   ]
  },
  {
   "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
}