Documentation development

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,4 @@
+- [ ] Tag issue being addressed
+- [ ] Add [tests](https://github.com/martimunicoy/offpele/tree/master/offpele/tests)
+- [ ] Update docstrings/[documentation](https://github.com/martimunicoy/offpele/tree/master/docs), if applicable
+- [ ] Update [changelog](https://github.com/martimunicoy/offpele/blob/master/docs/releasehistory.rst)

.github/workflows/master.yml

@@ -15,17 +15,23 @@ jobs:
     steps:
     - uses: actions/checkout@v2
 
-    - name: Set up Python 3.7
-      uses: actions/setup-python@v2
+    - uses: goanpeca/setup-miniconda@v1
+      name:  Conda setup
       with:
         python-version: 3.7
+        activate-environment: standard
+        environment-file: devtools/envs/standard.yaml
+        auto-activate-base: false
 
     - name: Install dependencies
+      shell: bash -l {0}
       run: |
         python -m pip install --upgrade pip
+        python -m pip install --no-deps -v .
         if [ -f docs/requirements.txt ]; then pip install -r docs/requirements.txt; fi
 
     - name: Build sphinx documentation
+      shell: bash -l {0}
       run: |
         cd docs/
         make github

.github/workflows/test.yml

@@ -54,4 +54,6 @@ jobs:
         pytest -r fE --tb=short --cov=offpele --cov-config=setup.cfg offpele/
 
     - name: Codecov
-      uses: codecov/codecov-action@v1
+      shell: bash -l {0}
+      run: |
+        codecov --token=${{ secrets.CODECOV_TOKEN }}

README.md

@@ -1,10 +1,10 @@
 | **About** | [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.6%2C%203.7-blue.svg)](https://martimunicoy.github.io/offpele) [![Release](https://img.shields.io/github/release/martimunicoy/offpele.svg?include_prereleases)](https://github.com/martimunicoy/offpele/releases/) |
 | :------ | :------- |
 | **Status** | [![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/martimunicoy/offpele.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/martimunicoy/offpele/context:python) [![Test](https://github.com/martimunicoy/offpele/workflows/Test/badge.svg)](https://github.com/martimunicoy/offpele/actions?query=workflow%3ATest) [![codecov](https://codecov.io/gh/martimunicoy/offpele/branch/master/graph/badge.svg)](https://codecov.io/gh/martimunicoy/offpele) |
-
+| **Installation** | [![Conda](https://img.shields.io/conda/v/martimunicoy/offpele.svg)](https://anaconda.org/martimunicoy/offpele) [![PyPI](https://img.shields.io/pypi/v/offpele)](https://pypi.org/project/offpele/) |
 
 # Open Force Field to PELE
-The `offpele` (Open Force Field to PELE) is a Python package that builds PELE-compatible force field templates using the Open Force Field toolkit.
+The `offpele` (Open Force Field to PELE) is a Python package that builds [PELE](https://pele.bsc.es/pele.wt)-compatible force field templates using the [Open Force Field toolkit](https://github.com/openforcefield/openforcefield).
 
 ## Documentation
 The documentation for the `offpele` package is available at [GitHub Pages](https://martimunicoy.github.io/offpele).

docs/charge.rst

@@ -0,0 +1,20 @@
+.. _charge ::
+
+Charge methods
+==============
+
+This module provides different methods to calculate partial charges
+for PELE.
+
+.. currentmodule:: offpele.charge
+
+Primary objects
+---------------
+
+.. autosummary::
+    :nosignatures:
+    :toctree: api/autogenerated
+    :template: class.rst
+
+    Am1bccCalculator
+    GasteigerCalculator

docs/conf.py

@@ -30,7 +30,8 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'm2r',
-              'sphinx.ext.napoleon', 'sphinx.ext.viewcode', ]
+              'sphinx.ext.napoleon', 'sphinx.ext.viewcode', 'sphinx.ext.todo',
+              'sphinx.ext.mathjax',]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/index.rst

@@ -13,6 +13,7 @@ User guide
   :maxdepth: 1
 
   installation
+  releasehistory
 
 
 API documentation
@@ -24,3 +25,4 @@ API documentation
   topology
   template
   solvent
+  charge

docs/installation.rst

@@ -3,11 +3,81 @@
 Installation
 ************
 
-Installing via PyPI
-===================
+Installing via `conda`
+======================
+The more straightforward way to install `offpele` along with the required
+dependencies is through the `conda <http://www.continuum.io/blog/conda>`_
+package manager.
 
-It can be easily install through PyPI with the following command:
+First, you need to install the
+`miniconda <http://conda.pydata.org/miniconda.html>`_ distribution, which is
+the minimal installation of the Anaconda Python package.
+
+To install the Python 3 version on ``linux`` (on ``bash`` systems):
+
+.. code-block:: bash
+
+   $ wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
+   $ bash ./Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda3
+
+It can also be installed on ``osx`` with:
+
+.. code-block:: bash
+
+   $ curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh -O
+   $ bash ./Miniconda3-latest-MacOSX-x86_64.sh -b -p $HOME/miniconda3
+
+Once installed, the bases environment of `conda` can be loaded with
+the following commands:
+
+.. code-block:: bash
+
+   $ source ~/miniconda3/etc/profile.d/conda.sh
+   $ conda activate base
+
+You can also create a custom conda environment to handle offpele:
+
+.. code-block:: bash
+
+   $ conda create --name offpele_env
+
+which can be activated and deactivated with the two commands from below:
+
+.. code-block:: bash
+
+   $ conda activate offpele_env
+   $ conda deactivate
+
+To install de dependencies of offpele, the following `conda` channels need
+to be added and updated:
+
+.. code-block:: bash
+
+   $ conda config --add channels omnia --add channels conda-forge --add channels martimunicoy
+   $ conda update --all
+
+Finally, you can install the latest stable build of `offpele`
+
+.. code-block:: bash
+
+   $ conda install offpele
+
+
+Installing via `PyPI`
+=====================
+
+`offpele` can also be installed through `PyPI <https://pypi.org>`_
+with the following command:
 
 .. code-block:: bash
 
    $ pip install offpele
+
+However, with `PyPI` some of the required dependencies of `offpele` are not
+installed and have to be installed manually such as:
+
+- Open Force Field Toolkit
+- RDKit
+- AmberTools
+
+For this reason, the installation through `conda` is recommended.

docs/releasehistory.rst

@@ -0,0 +1,36 @@
+Release History
+===============
+
+Releases follow the ``major.minor.micro`` scheme recommended by `PEP440 <https://www.python.org/dev/peps/pep-0440/#final-releases>`_, where
+
+* ``major`` increments denote a change that may break API compatibility with previous ``major`` releases
+* ``minor`` increments add features but do not break API compatibility
+* ``micro`` increments represent bugfix releases or improvements in documentation
+
+0.3.0 - Current development
+-------------------------
+
+This is still a preliminary version of the Open Force Field to PELE package. It includes some new features and improvements in documentation and unit testing.
+
+New features
+""""""""""""
+- `PR #15 <https://github.com/martimunicoy/offpele/pull/15>`_: Adds a new method (Antechamber's gasteiger) to calculate partial charges.
+
+Tests added
+"""""""""""
+- `PR #15 <https://github.com/martimunicoy/offpele/pull/15>`_: Adds tests ensuring that the run_offpele call from main and the partial charge calculators work as expected.
+
+
+0.2.0
+-----
+
+This is a preliminary version of the Open Force Field to PELE package.
+
+New features
+""""""""""""
+
+A first implementation of the package that allows to:
+
+- Build a rotamer library for a small molecule using RDKit's API
+- Build a template with the Molecular Mechanics' parameters for a small molecule using the Open Force Field Toolkit
+- Assign the OBC implicit solvent parameters to a small molecule using the Open Force Field Toolkit

offpele/charge/__init__.py

@@ -0,0 +1 @@
+from .charges import Am1bccCalculator, GasteigerCalculator

offpele/charge/charges.py

@@ -0,0 +1,74 @@
+"""
+This module handles all classes and functions related with partial charge
+calculators.
+"""
+
+
+from offpele.utils.toolkits import AmberToolkitWrapper
+
+
+class _PartialChargesCalculator(object):
+    """
+    Base class for partial charges calculators.
+    """
+
+    _name = None
+    _amber_toolkit = AmberToolkitWrapper()
+
+    def __init__(self, molecule):
+        """
+        It initiates a PartialChargesCalculator object.
+
+        Parameters
+        ----------
+        molecule : An offpele.topology.Molecule
+            The partial charges of this Molecule object will be calculated
+        """
+        self._molecule = molecule
+
+    @property
+    def molecule(self):
+        """
+        The offpele's Molecule.
+
+        Returns
+        -------
+        molecule : an offpele.topology.Molecule
+            The offpele's Molecule object
+        """
+        return self._molecule
+
+    @property
+    def name(self):
+        return self._name
+
+    def get_partial_charges(self):
+        """
+        It returns the partial charges that correspond to the molecule's
+        atoms.
+
+        Returns
+        -------
+        charges : simtk.unit.Quantity
+            The array of partial charges
+        """
+
+        return self._amber_toolkit.compute_partial_charges(self.molecule,
+                                                           method=self.name)
+
+
+class Am1bccCalculator(_PartialChargesCalculator):
+    """
+    Implementation of the AM1-BCC partial charges calculator (using RDKit).
+    """
+
+    _name = 'am1bcc'
+
+
+class GasteigerCalculator(_PartialChargesCalculator):
+    """
+    Implementation of the gasteiger partial charges calculator (using
+    RDKit).
+    """
+
+    _name = 'gasteiger'

offpele/main.py

@@ -18,6 +18,7 @@
 
 DEFAULT_OFF_FORCEFIELD = 'openff_unconstrained-1.2.0.offxml'
 DEFAULT_RESOLUTION = int(30)
+DEFAULT_CHARGES_METHOD = 'am1bcc'
 IMPACT_TEMPLATE_PATH = 'DataLocal/Templates/OFF/Parsley/HeteroAtoms/'
 ROTAMER_LIBRARY_PATH = 'DataLocal/LigandRotamerLibs/'
 SOLVENT_TEMPLATE_PATH = 'DataLocal/OBC/'
@@ -52,6 +53,9 @@ def parse_args():
     parser.add_argument('--as_DataLocal', dest='as_datalocal',
                         help="Output will be saved following PELE's DataLocal "
                         + "hierarchy", action='store_true')
+    parser.add_argument('-c', '--charges_method', metavar="NAME",
+                        type=str, help="The name of the method to use to "
+                        + "compute charges", default=DEFAULT_CHARGES_METHOD)
 
     parser.set_defaults(as_datalocal=False)
     parser.set_defaults(with_solvent=False)
@@ -112,8 +116,9 @@ def handle_output_paths(molecule, output, as_datalocal):
 
 
 def run_offpele(pdb_file, forcefield=DEFAULT_OFF_FORCEFIELD,
-                  resolution=DEFAULT_RESOLUTION, output=None,
-                  with_solvent=False, as_datalocal=False,):
+                resolution=DEFAULT_RESOLUTION,
+                charges_method=DEFAULT_CHARGES_METHOD,
+                output=None, with_solvent=False, as_datalocal=False):
     """
     It runs offpele.
 
@@ -125,6 +130,9 @@ def run_offpele(pdb_file, forcefield=DEFAULT_OFF_FORCEFIELD,
         The name of an OpenForceField's forcefield
     resolution : float
         The resolution in degrees for the rotamer library
+    charges_method : str
+        The name of the method to use to compute partial charges. Default
+        is 'am1bcc'
     output : str
         Path where output files will be saved
     with_solvent : bool
@@ -141,6 +149,7 @@ def run_offpele(pdb_file, forcefield=DEFAULT_OFF_FORCEFIELD,
     print(' - PDB to parameterize: {}'.format(pdb_file))
     print(' - Force field: {}'.format(forcefield))
     print(' - Rotamer library resolution: {}'.format(resolution))
+    print(' - Charges method: {}'.format(charges_method))
     print(' - Output path: {}'.format(output))
     print(' - Write solvent parameters: {}'.format(with_solvent))
     print(' - DataLocal-like output: {}'.format(as_datalocal))
@@ -177,20 +186,21 @@ def run_offpele(pdb_file, forcefield=DEFAULT_OFF_FORCEFIELD,
 
 def main():
     """
-    It reads the command-line arguments and calls offpele.
+    It reads the command-line arguments and runs offpele.
 
     Examples
     --------
 
     From the command-line:
 
     >>> python main.py molecule.pdb -f openff_unconstrained-1.1.1.offxml -r 30
-        -o output_path/ --with_solvent --as_DataLocal
+        -o output_path/ --with_solvent --as_DataLocal -c gasteiger
 
     """
     args = parse_args()
-    run_offpele(args.pdb_file, args.forcefield, args.resolution, args.output,
-                  args.with_solvent, args.as_datalocal)
+    run_offpele(args.pdb_file, args.forcefield, args.resolution,
+                args.charges_method, args.output, args.with_solvent,
+                args.as_datalocal, )
 
 
 if __name__ == '__main__':