Foyer_03_Creating_Force_field_Files.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "# Foyer Tutorial 03: Creating Forcefield Files\n",
    "This tutorial focuses on how to create force field files form scratch."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Forcefield Template\n",
    "\n",
    "To aid in the creation and dissemination of forcefields, we have create a template, hosted as a github repository. https://github.com/mosdef-hub/forcefield_template\n",
    "\n",
    "### Importing the Template\n",
    "To use the template, users should make a copy in their own workspace. This can be accomplished in numerous ways, such as downloading the source, creating a new repository, and adding the files to that repository.  Alternatively, users that wish to use services such as github.com, bitbucket.org, or other similar sites, can take advantage of the import function these typically provide.  \n",
    "\n",
    "For example, on github.com, the import function (https://github.com/new/import) allows users to enter the URL for a repository they wish to copy. Thus, by providing the link (https://github.com/mosdef-hub/forcefield_template), a user can easily create a new copy in their own workspace."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Anatomy of the Template\n",
    "\n",
    "The template provides a framework to aid in the setup, validation, and dissemination of force field files.  We will examine each of these files/folders here:\n",
    "\n",
    "#### forcefield_template.xml\n",
    "This file includes a few sample inputs for each of the key sections of our extension to the OpenMM XML file format. This file can be renamed and modified to include relevant atom types and parameters. \n",
    "\n",
    "#### test_molecules\n",
    "This folder is designed to hold already atom-typed molecules, for which the force field file will be validated against, as .mol2 files.  By default it includes 8 test molecules that the atom-types provided in forcefield_template.xml were validated against.  Note, the MOL2 atom_type field (column 6) is assumed to specify the atomtype.\n",
    "\n",
    "#### test_atomtyping.py\n",
    "This script performs automated testing of the force field file, comparing the output generated to that of the known molecules in the test_molecules folder.  This relies upon pytest and can be executed using the following command:\n",
    "\n",
    "`py.test -v --tb=line` \n",
    "\n",
    "#### README.md\n",
    "This file is a readme file that github will parse and display on the front page of the repository.  Currently, this includes instructions of the basic usage, but should be modified to provide a clear desciption of the force field, the test molecules included, and the source (i.e., references) for the parameters included in a force field file. \n",
    "\n",
    "Note, the force field template is ever evolving.  Planned improvements:\n",
    "- Script to automatically generate the readme file from the force field file and an associated XML metadata file. \n",
    "- Scripts to further help aid in the development of force fields (e.g., more clear identification of missing atom types and suggestions of SMARTS string for missing atom-types)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example repositories\n",
    "Several repositories have been created that make use of this template:\n",
    "- https://github.com/chrisiacovella/oplsaa_perfluoroalkanes\n",
    "- https://github.com/summeraz/OPLSaa_alkylsilanes\n",
    "- https://github.com/mosdef-hub/forcefield_perfluoroethers"
   ]
  },
  {
   "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.7.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}