Numpydoc temporary fix and code rendering fix (#238)

* working on updating readme

* working on updating readme

* working on updating readme

* working on updating readme

* Recreate listings from paper, add section in index

* Jupyter notebooks and small xml files

* Update README.md

Co-Authored-By: Matt Thompson <[email protected]>

* Update README.md

* Update docs/examples/ethane_box_oplsaa.ipynb

Co-Authored-By: Matt Thompson <[email protected]>

* Update docs/examples/ethane_box_oplsaa.ipynb

Co-Authored-By: Matt Thompson <[email protected]>

* Update docs/paper_examples.md

Co-Authored-By: Matt Thompson <[email protected]>

* Update docs/paper_examples.md

Co-Authored-By: Matt Thompson <[email protected]>

* Updates to readme and paper, and addition of data_structure file

* Newer versions of numpydoc and sphinx error out in certain scenarios when generating text from docstrings

* pin sphinx as well

* Update ethane_box_oplsaa.ipynb

devtools/travis-ci/create_docs.sh

@@ -17,7 +17,7 @@ set -ev
 # we assume that we're running in a virtualenv with all mbuild already installed and tested
 
 # install additional packages required for doc generation
-conda install --yes sphinx numpydoc sphinx sphinx_rtd_theme widgetsnbextension ipywidgets
+conda install --yes sphinx=1.6.7 numpydoc=0.6 sphinx sphinx_rtd_theme widgetsnbextension ipywidgets
 pip install mock
 
 pushd $DIR/../..

docs/atom-typing_options.rst

@@ -9,7 +9,7 @@ parametrized ``ParmEd`` ``Structure``. The user may pass some otions to this
 function based on a particular use case.
 
 Forcefield
---------
+----------
 
 .. autoclass:: foyer.forcefield.Forcefield
     :members:

docs/data_structures.rst

@@ -0,0 +1,10 @@
+==============
+Data Structure
+==============
+
+Forcefield
+----------
+
+.. autoclass:: foyer.forcefield.Forcefield
+    :members:
+

docs/paper_examples.rst

@@ -0,0 +1,95 @@
+Paper Examples
+~~~~~~~~~~~~~~
+
+Contained below are the toy examples from the *Usage Examples* section of the `foyer paper <https://arxiv.org/pdf/1812.06779.pdf>`__. The source code selections are listed below on this page, there are `Jupyter
+Notebooks <https://github.com/mosdef-hub/foyer/tree/master/docs/examples>`__
+where you can try these examples yourself. Note that these examples are
+meant to showcase the abilities of ``foyer`` through simple examples. If
+the user would like to examine more in-depth examples using ``foyer``
+with ``mBuild``, please refer to the `tutorial
+repository <https://github.com/mosdef-hub/mosdef_tutorials>`__.
+
+Below is *Listing 6* from the paper, a python script to fill a :math:`2x2x2 nm` 
+box with 100 ethane molecules. The system is then atomtyped using the
+OPLS-AA forcefield. There are two approaches to the same problem
+detailed below in this listing, the first approach uses the
+``forcefield_files`` function argument from
+`mBuild <https://github.com/mosdef-hub/mbuild>`__ to atomptype the
+system (using foyer under the hood). While the second approach creates a
+``foyer`` ``Forcefield`` object, which then calls its ``apply``
+function, operating on the ``mBuild`` ``Compound`` to return the
+properly atomtyped structure. Note that in all instances when using
+``foyer``, the chemical system of interest is converted into a
+``ParmEd`` ``Structure``. Even the ``mBuild`` ``Compounds``, when
+calling the ``save`` routine, are converted into a ``ParmEd``
+``Structure`` before ``foyer`` can atomtype them. The object returned by
+``foyer`` after the atomtypes have been applied are ``ParmEd``
+``Structures``. This is subject to change in later iterations of
+``foyer``.
+
+Example 1
+^^^^^^^^^
+
+.. code:: python
+    
+    import mbuild as mb
+    from mbuild.examples import Ethane
+    from foyer.tests.utils import get_fn
+    from foyer import Forcefield
+
+    """ Applying a force field while saving from mBuild """
+    # Create the chemical topology
+    ethane_fluid = mb.fill_box(compound=Ethane(), n_compounds=100, box=[2, 2, 2])
+    # Apply and save the topology
+    ethane_fluid.save("ethane-box.top", forcefield_files=get_fn("oplsaa_alkane.xml"))
+    ethane_fluid.save("ethane-box.gro")
+
+    """ Applying a force field directly with foyer """
+    # Create the chemical topology
+    ethane_fluid = mb.fill_box(compound=Ethane(), n_compounds=100, box=[2, 2, 2])
+    # Load the forcefield
+    opls_alkane = Forcefield(forcefield_files=get_fn("oplsaa_alkane.xml"))
+    # Apply the forcefield to atom-type
+    ethane_fluid = opls_alkane.apply(ethane_fluid)
+    # Save the atom-typed system
+    ethane_fluid.save("ethane-box.top", overwrite=True)
+    ethane_fluid.save("ethane-box.gro", overwrite=True)
+
+
+---------------------------------------
+
+Example 2
+^^^^^^^^^
+
+The other example listing from the text showcases the ability to create
+two separate chemical topologies and applying different forcefield files
+to each. The two parameterized systems that are generated are then
+combined into a single ``ParmEd`` ``Structure`` and saved to disk.
+
+.. code:: python
+
+    from foyer import Forcefield
+    from foyer.tests.utils import get_fn
+    import mbuild as mb
+    from mbuild.examples import Ethane
+    from mbuild.lib.atoms import H
+    from mbuild.lib.bulk_materials import AmorphousSilica
+
+    # Create a silica substrate, capping surface oxygens with hydrogen
+    silica=mb.recipes.SilicaInterface(bulk_silica=AmorphousSilica())
+    silica_substrate=mb.recipes.Monolayer(surface=silica,chains=H(),guest_port_name="up")
+    # Determine the box dimensions dictated by the silica substrate
+    box=mb.Box(mins=[0, 0,max(silica.xyz[:,2])],maxs=silica.periodicity+ [0, 0, 4])
+    # Fill the box with ethane
+    ethane_fluid=mb.fill_box(compound=Ethane(),n_compounds=200,box=box)
+    # Load the forcefields
+    opls_silica=Forcefield(forcefield_files=get_fn("oplsaa_with_silica.xml"))
+    opls_alkane=Forcefield(forcefield_files=get_fn("oplsaa_alkane.xml"))
+    # Apply the forcefields
+    silica_substrate=opls_silica.apply(silica_substrate)
+    ethane_fluid=opls_alkane.apply(ethane_fluid)
+    # Merge the two topologies
+    system=silica_substrate+ethane_fluid
+    # Save the atom-typed system
+    system.save("ethane-silica.top")
+    system.save("ethane-silica.gro")

docs/parameter_definitions.rst

@@ -0,0 +1,94 @@
+Parameter definitions
+=====================
+
+Parameter definitions within force field XMLs follow the same
+conventions as defined in the `OpenMM
+documentation <http://docs.openmm.org/7.0.0/userguide/application.html#creating-force-fields>`__.
+Currently, only certain functional forms for molecular forces are
+supported, while future developments are expected to allow Foyer to
+support any desired functional form, including reactive and tabulated
+potentials. The currently supported functional forms for molecular
+forces are:
+
+-  **Nonbonded**
+
+   -  `Lennard-Jones
+      (12-6) <http://docs.openmm.org/7.0.0/userguide/application.html#nonbondedforce>`__
+
+-  **Bonds**
+
+   -  `Harmonic <http://docs.openmm.org/7.0.0/userguide/application.html#harmonicbondforce>`__
+
+-  **Angles**
+
+   -  `Harmonic <http://docs.openmm.org/7.0.0/userguide/application.html#harmonicangleforce>`__
+
+-  **Torsions (proper)**
+
+   -  `Periodic <http://docs.openmm.org/7.0.0/userguide/application.html#periodictorsionforce>`__
+   -  `Ryckaert-Bellemans <http://docs.openmm.org/7.0.0/userguide/application.html#rbtorsionforce>`__
+
+-  **Torsions (improper)**
+
+   -  `Periodic <http://docs.openmm.org/7.0.0/userguide/application.html#periodictorsionforce>`__
+
+Definitions for each molecular force follow the OpenMM standard.
+
+Classes vs. Types
+-----------------
+
+OpenMM allows users to specify either a ```class`` or a
+``type`` <http://docs.openmm.org/7.0.0/userguide/application.html#atom-types-and-atom-classes>`__,
+to define each particle within the force definition. Here, ``type``
+refers to a specific atom type (as defined in the ``<AtomTypes>``
+section), while ``class`` refers to a more general description that can
+apply to multiple atomtypes (i.e. multiple atomtypes may share the same
+class). This aids in limiting the number of force definitions required
+in a force field XML, as many similar atom types may share force
+parameters.
+
+Assigning parameters by specificity
+-----------------------------------
+
+Foyer deviates from OpenMM’s convention when matching force definitions
+in a force field XML to instances of these forces in a molecular system.
+In OpenMM, forces are assigned according to the first matching
+definition in a force field XML, even if multiple matching definitions
+exist. In contrast, Foyer assigns force parameters based on definition
+specificity, where definitions containing more ``type`` attributes are
+considered to be more specific.
+
+**Example:**
+
+::
+
+   <RBTorsionForce>
+     <Proper class1="CT" class2="CT" class3="CT" class4="CT" c0="2.9288" c1="-1.4644" c2="0.2092" c3="-1.6736" c4="0.0" c5="0.0"/>
+     <Proper type1="opls_961" type2="opls_136" type3="opls_136" type4="opls_136" c0="-0.987424" c1="0.08363" c2="-0.08368" c3="-0.401664" c4="1.389088" c5="0.0"/>
+   </RBTorsionForce>
+
+Above, two proper torsions are defined, both describing a torsional
+force between four tetrahedral carbons. However, the first definition
+features four ``class`` attributes and zero ``type`` attributes, as this
+describes a general dihedral for all tetrahedral carbons. The second
+definition features zero ``class`` attributes and four ``type``
+attributes, and describes a more specific dihedral for the case where
+one end carbon is of type ``'opls_961'`` (a fluorinated carbon) and the
+remaining three carbons are of type ``'opls_136'`` (alkane carbons). Now
+consider we want to use a force field containing the above torsion
+definitions to assign parameters to some molecular system that features
+partially fluorinated alkanes. When assigning torsion parameters to a
+quartet of atoms where one end carbon is fluorinated (``'opls_961'``)
+and the remaining three are hydrogenated (``'opls_136'``), if using the
+OpenMM procedure for parameter assignment the more general
+``'CT-CT-CT-CT'`` torsion parameters (the first definition above) would
+be assigned because this would be the first matching definition in the
+force field XML. However, with Foyer, the second definition will be
+auto-detected as more specific, due to the greater number of ``type``
+attributes (4 vs. 0) and those parameters will be assigned instead.
+
+It should be noted that if two definitions feature the same specificity
+level (i.e. the same number of ``type`` definitions) then automatic
+detection of precedence is not possible and parameter assignment will
+follow the OpenMM procedure whereby parameters from the first matching
+force definition in the XML will be assigned.