This repository contains a number of tools from the Open Forcefield Consortium for the development and use of modern molecular mechanics forcefields based on direct chemical perception and parameterized with rigorous statistical methods.
This repository hosts tools that we have committed to stably maintain throughout their lifetimes:
- The SMIRKS Native Open Force Field (SMIRNOFF) direct chemical perception forcefield specification language
- Tools for direct chemical environment perception and manipulation
We currently support Python 2.7, 3.5 and 3.6.
We recommend the miniconda Python distribution.
To install miniconda on osx with bash, this is:
wget https://repo.continuum.io/miniconda/Miniconda3-latest-MacOSX-x86_64.sh
bash Miniconda3-latest-MacOSX-x86_64.sh -b -p $HOME/miniconda3
export PATH="$HOME/miniconda3/bin:${PATH}"These tools currently require the OpenEye toolkit (which requires a license that is free for academics indenting to rapidly release results into the public domain):
pip install -i https://pypi.anaconda.org/OpenEye/simple OpenEye-toolkitsInstall openforcefield tools via conda:
conda install --yes -c conda-forge -c omnia openforcefieldThis repository houses the SMIRNOFF SMIRKS-based force field format, along with classes to parameterize OpenMM systems given SMIRNOFF .offxml format files.
The SMIRNOFF force field format is documented here.
The SMIRNOFF forcefield format is available in sample form under data/forcefield, and is handled by forcefield.py.
An example comparing SMIRNOFF versus AMBER energies for the parm@frosst forcefield is provided under
examples/SMIRNOFF_comparison, where two scripts can compare energies for a single molecule or for the entire AlkEthOH set.
Note that two forcefields are currently available in this format, Frosst_AlkEthOH.offxml,
the parm@frosst forcefield as it should have been for this set, and Frosst_AlkEthOH_parmAtFrosst.offxml,
the forcefield as it was actually implemented (containing several bugs as noted in the file itself).
It can also be of interest to know what SMIRNOFF parameters would be applied to particular molecules. Utility functionality for this is provided under forcefield_labeler.py, which has generally similar structure to forcefield.py but instead of providing OpenMM systems with parameters, it can be applied to specific molecules and returns information about what parameters would be applied.
The SMIRNOFF ForceField class is essentially a drop-in replacement for the OpenMM ForceField class, with the additional requirement that an OpenEye OEMol-compatible object must also be provided to allow for chemical environment perception (and optionally charges).
For example, if we have an OEMol named mol, we can create an OpenMM System object with the following code:
# Import the SMIRNOFF forcefield engine and some useful tools
from openforcefield.typing.engines.smirnoff import ForceField
from openforcefield.utils import read_molecules, get_data_filename, generateTopologyFromOEMol
# read in molecule from file in openforcefield/data/molecules/
mols = read_molecules('benzene.mol2')
# Get positions and topology in OpenMM-compatible format
topology = generateTopologyFromOEMol(mols[0])
# Load a SMIRNOFF small molecule forcefield for alkanes, ethers, and alcohols
FF_filename = get_data_filename('forcefield/Frosst_AlkEthOH_parmAtFrosst.offxml')
forcefield = ForceField(FF_filename)
# Create the OpenMM system, additionally specifying a list of OEMol objects for the unique molecules in the system
system = forcefield.createSystem(topology, mols)See examples/SMIRNOFF_simulation/ for a complete example of how SMIRNOFF can be used for small molecule vacuum simulations, and examples/mixedFF_structure for how to set up a system which uses an AMBER forcefield (in this case, AMBER99SB-ILDN) for a protein in combination with SMIRNOFF for a small molecules. Via ParmEd, this can be translated into GROMACS, AMBER, or CHARMM formats for use elsewhere (and additional formats via InterMol).
For an especially complete worked example, see complete setup of a host-guest simulation in water with SMIRNOFF, including docking, 2D and 3D visualization, etc., in examples/host_guest_simulation/smirnoff_host_guest.ipynb (Jupyter notebook).
See Chemical-starting-points.md for answers to a variety of common problems, such as:
- Why do I need to provide molecules corresponding to the components of my system, or a Topology with bond orders?
- Can I use an AMBER (or GROMACS) topology/coordinate file as a starting point for applying a SMIRNOFF force field?
- What about starting from a PDB file?
ChemicalEnvironments are a python class used to parse and manipulate SMIRKS strings.
They were created with the goal of being able to automatically sample over chemical perceptions space.
Someday they will be used to generate SMIRKS patterns for SMIRKS Native-Open Force Fields parameters.
These are initiated with SMIRKS strings for single molecules fragements* and then the information is stored for each atom and bond in the initial fragment.
* NOTE SMIRKS can be used to show how a reaction would happen between fragments in different molecules. This is done with '.' between molecules and '>>' to indicate a reaction. Chemical Environments can only parse SMIRKS strings for fragments of a single molecule.
from openforcefield.typing.chemistry import environment
smirks = "[#6X3,#7:1]~;@[#8;r:2]~;@[#6X3,#7:3]"
angle = environment.AngleChemicalEnvironment(smirks = smirks)
print(angle.asSMIRKS())
# "[#6X3,#7:1]~;@[#8;r:2]~;@[#6X3,#7:3]"
# add a new atom
atom3 = angle.selectAtom(3)
alpha_ORtypes = [('#8', ['X2'])]
alpha_bondANDtypes = ['!@']
alpha = angle.addAtom(atom3, bondANDtypes = alpha_bondANDtypes, newORtypes = alpha_ORtypes)
print(alpha.asSMIRKS()) # smirks for atom only
# "[#8X2H1;R0]"
print(angle.asSMIRKS())
# "[#6X3,#7:1]~;@[#8;r:2]~;@[#6X3,#7:3]~;!@[#8X2]"If you are not familiar with the SMIRKS language, take a look at these Daylight resources:
For more detailed examples see README and using_environment.ipynb in examples/chemicalEnvironments/
examples/- some examples - look here to get started; see especiallyhost_guest_simulationfor a detailed worked example of SMIRNOFF simulation of host-guest binding.openforcefield/- openforcefield toolsdevtools/- continuous integration and packaging scripts and utilitiesutilities/- utilities; scripts to convert parm@frosst modifiedfrcmodfiles to SMIRNOFF XMLoe_license.txt.enc- encrypted OpenEye license for continuous integration testing.travis.yml- travis-ci continuous integration fileThe-SMIRNOFF-force-field-format.md- specifications for the SMIRNOFF force field formatChemical-starting-points.md- discussion of appropriate starting points for applying a SMIRNOFF force field to a system