Merge remote-tracking branch 'upstream/master' into 284-docstrings

docs/contributing.rst

@@ -1,3 +1,56 @@
 Contributing
-------------
-plz help
+============
+Contributions are welcomed via `pull requests on GitHub <https://github.com/mattwthompson/topology/pulls>`_. Developers and/or
+users will review requested changes and make comments. The rest of this file will serve as a set of general guidelines
+for contributors.
+
+Features
+--------
+Implement functionality in a general and flexible fashion
+*********************************************************
+GMSO is designed to be general and flexible, not limited to single chemistries, file formats, simulation engines, or
+simulation methods. Additions to core features should attempt to provide something that is applicable to a variety of
+use-cases and not targeted at only the focus area of your research. However, some specific features targeted toward
+a limited use case may be appropriate. Speak to the developers before writing your code and they will help you make design
+choices that allow flexibility.
+
+Version control
+---------------
+
+We currently use the "standard" Pull Request model. Contributions should be implemented on feature branches of forks.
+Please try to keep the `master` branch of your fork up-to-date with the `master` branch of the main repository.
+
+Propose a single set of related changes
+****************************************
+
+Small changes are preferred over large changes. A major contribution can often be broken down into smaller PRs. Large PRs that
+affect many parts of the codebase can be harder to review and are more likely to cause merge conflicts.
+
+Source code
+-----------
+Use a consistent style
+*************************
+It is important to have a consistent style throughout the source code. The following criteria are desired:
+
+* Lines wrapped to 80 characters
+* Lines are indented with spaces
+* Lines do not end with whitespace
+* For other details, refer to `PEP8 <https://www.python.org/dev/peps/pep-0008>`_
+
+To help with the above, there are tools such as `flake8 <https://pypi.org/project/flake8/>`_ and `Black <https://github.com/psf/black>`_.
+
+Document code with comments
+****************************
+All public-facing functions should have docstrings using the numpy style. This includes concise paragraph-style description
+of what the class or function does, relevant limitations and known issues, and descriptions of arguments. Internal functions
+can have simple one-liner docstrings.
+
+
+Tests
+-----
+Write unit tests
+****************
+All new functionality in GMSO should be tested with automatic unit tests that execute in a few seconds. These tests
+should attempt to cover all options that the user can select. All or most of the added lines of source code should be
+covered by unit test(s). We currently use `pytest <https://docs.pytest.org/en/latest/>`_, which can be executed simply by calling
+`pytest` from the root directory of the package.

examples/argon/argon_lammps.ipynb

@@ -0,0 +1,162 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!conda install --file env.txt --yes"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This example requires LAMMPS. You can install it from source or conda via `conda install -c conda-forge lammps`.\n",
+    "You also need to `pip install -e` the topology/gmso package after February 14, 2020, when PR #121 was merged."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import warnings\n",
+    "warnings.filterwarnings('ignore')\n",
+    "\n",
+    "import mbuild as mb\n",
+    "import gmso\n",
+    "from gmso.external.convert_mbuild import from_mbuild\n",
+    "from gmso.formats.lammpsdata import write_lammpsdata"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Generate a small box of Argon atoms using mBuild\n",
+    "ar = mb.Compound(name='Ar')\n",
+    "\n",
+    "packed_system = mb.fill_box(\n",
+    "    compound=ar,\n",
+    "    n_compounds=329,\n",
+    "    box=mb.Box([2.5, 2.5, 2.5]),\n",
+    ")\n",
+    "\n",
+    "packed_system.visualize()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Convert system to a backend object\n",
+    "top = from_mbuild(packed_system)\n",
+    "\n",
+    "# Load force field from XML\n",
+    "ff = gmso.ForceField('ar.xml')\n",
+    "ar_type = ff.atom_types['Ar']\n",
+    "\n",
+    "# Manually set types, bypassing foyer or any atomtyping engine\n",
+    "for site in top.sites:\n",
+    "    site.atom_type = ar_type\n",
+    "\n",
+    "top.update_topology()\n",
+    "\n",
+    "# Save files to disk\n",
+    "write_lammpsdata(top, 'data.ar')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Next, we run the simulations (energy minimizaiton and then NVE MD) using LAMMPS"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!lmp_serial < in.argon"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Finally we can use use `numpy` and `matplotlib` to do some quick checks of the properties of the system"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "import numpy as np"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "data = np.loadtxt('thermo.txt')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plt.plot(data[:,0], data[:,1])\n",
+    "plt.xlabel('step')\n",
+    "plt.ylabel('Temperature (K)')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plt.plot(data[:,0], data[:,2])\n",
+    "plt.xlabel('step')\n",
+    "plt.ylabel('Potential Energy (kcal/mol)')"
+   ]
+  }
+ ],
+ "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.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

examples/argon/in.argon

@@ -0,0 +1,28 @@
+dimension           3
+units               real
+boundary            p p p
+
+atom_style          full
+pair_style          lj/cut 12
+box                 tilt large
+
+neighbor            2.0 bin
+neigh_modify        every 1 delay 1 check yes
+
+read_data           data.ar
+
+velocity            all create 100 12345
+
+minimize            0.0 0.0 100 4000
+reset_timestep      0
+
+timestep            1.0
+thermo              100
+compute             PE all pe
+
+fix                 MyNVE all nve 
+dump                NVEdump all atom 100 ar_nve.lammpstrj
+fix                 thermoprint all print 100 "$(step)  $(temp)  $(c_PE)" file thermo.txt
+
+#step1-start
+run                 100000

gmso/__init__.py

@@ -1,4 +1,5 @@
 from .core.topology import Topology
+from .core.subtopology import SubTopology
 from .core.element import Element
 from .core.box import Box
 

gmso/core/angle_type.py

@@ -8,25 +8,39 @@
 
 
 class AngleType(Potential):
-    """A Potential between 3-bonded partners.
+    """A descripton of the interaction between 3 bonded partners.
+
+    This is a subclass of the gmso.core.Potential superclass.
+
+    AngleType represents an angle type and includes the functional form
+    describing its interactions. The functional form of the potential is stored
+    as a `sympy` expression and the parameters, with units, are stored
+    explicitly.  The AtomTypes that are used to define the angle type are
+    stored as `member_types`.
 
     Parameters
     ----------
-    name : str
+    name : str, optional
+        A name uniquely representing the angle type
     expression : str or sympy.Expression
         See `Potential` documentation for more information
     parameters : dict {str, unyt.unyt_quantity}
         See `Potential` documentation for more information
     independent vars : set of str
         See `Potential` documentation for more information
-    member_types : list of gmso.AtomType.name (str)
-    gmso: gmso.core.Topology, the gmso of which this angle_type is a part of, default=None
-    set_ref: (str), the string name of the bookkeeping set in gmso class.
+    member_types : list-like of str
+        List-like of of gmso.AtomType.name defining the members of this
+        angle type
+    gmso: gmso.core.Topology, default=None
+        The Topology of which this angle_type is a part of
+    set_ref: str
+        The string name of the bookkeeping set in gmso class.
 
     Notes
     ----
     Inherits many functions from gmso.Potential:
         __eq__, _validate functions
+
     """
 
     def __init__(self,
@@ -73,7 +87,7 @@ def __repr__(self):
 
 
 def _validate_three_member_type_names(types):
-    """Ensure 3 partners are involved in AngleType"""
+    """Ensure exactly 3 partners are involved in AngleType"""
     if len(types) != 3 and len(types) != 0:
         raise GMSOError("Trying to create an AngleType "
                             "with {} constituent types".format(len(types)))

gmso/core/atom_type.py

@@ -1,4 +1,5 @@
 import warnings
+
 import unyt as u
 
 from gmso.core.potential import Potential
@@ -8,7 +9,9 @@
 
 
 class AtomType(Potential):
-    """An atom type, inheriting from the Potential class.
+    """A description of non-bonded interacitons between sites.
+
+    This is a subclass of the gmso.core.Potential superclass.
 
     AtomType represents an atom type and includes the functional form
     describing its interactions and, optionally, other properties such as mass
@@ -39,15 +42,18 @@ class AtomType(Potential):
     atomclass : str, default=''
         The class of the atomtype
     doi : str
-        Digital Object Identifier of publication where this atom type was specified
+        Digital Object Identifier of publication where this atom type was
+        specified
     desc : str
         Simple description of the atom type
     overrides : set of str
         Set of other atom types that this atom type overrides
     definition : str
         SMARTS string defining this atom type
-    topology: gmso.core.Topology, the topology of which this atom_type is a part of, default=None
-    set_ref: (str), the string name of the bookkeeping set in topology class.
+    topology: gmso.core.Topology, default=None
+        The topology of which this atom_type is a part of, default=None
+    set_ref: str
+        The string name of the bookkeeping set in gmso class.
 
     """
 
@@ -177,6 +183,7 @@ def __repr__(self):
 
 
 def _validate_charge(charge):
+    """Check to see that a charge is a unyt array of the right dimension"""
     if not isinstance(charge, u.unyt_array):
         warnings.warn("Charges are assumed to be elementary charge")
         charge *= u.elementary_charge
@@ -190,6 +197,7 @@ def _validate_charge(charge):
 
 
 def _validate_mass(mass):
+    """Check to see that a mass is a unyt array of the right dimension"""
     if not isinstance(mass, u.unyt_array):
         warnings.warn("Masses are assumed to be g/mol")
         mass *= u.gram / u.mol
@@ -203,12 +211,14 @@ def _validate_mass(mass):
 
 
 def _validate_str(val):
+    """Check to see that a string is a str type"""
     if not isinstance(val, str):
         raise ValueError("Passed value {} is not a string".format(val))
     return val
 
 
 def _validate_set(val):
+    """Check to see that a set is a set type"""
     if not isinstance(val, set):
         raise ValueError("Passed value {} is not a set".format(val))
     if not all([isinstance(char, str) for char in val]):