Add contribution page, dependencies, and references (#44)

Fixes #34, #35, #32
lilyminium · Nov 15, 2021 · e3fd9be · e3fd9be
1 parent 3d36c11
commit e3fd9be
Show file tree

Hide file tree

Showing 11 changed files with 444 additions and 17 deletions.
diff --git a/README.md b/README.md
@@ -8,9 +8,7 @@
 [![Documentation Status](https://readthedocs.org/projects/psiresp/badge/?version=latest)](https://psiresp.readthedocs.io/en/latest/?badge=latest)
 [![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/lilyminium/psiresp.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/lilyminium/psiresp/context:python)
 [![PyPI version](https://badge.fury.io/py/psiresp.svg)](https://badge.fury.io/py/psiresp)
-
-
-[![Powered by MDAnalysis](https://img.shields.io/badge/powered%20by-MDAnalysis-orange.svg?logoWidth=16&logo=data:image/x-icon;base64,AAABAAEAEBAAAAEAIAAoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJD+XwCY/fEAkf3uAJf97wGT/a+HfHaoiIWE7n9/f+6Hh4fvgICAjwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACT/yYAlP//AJ///wCg//8JjvOchXly1oaGhv+Ghob/j4+P/39/f3IAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJH8aQCY/8wAkv2kfY+elJ6al/yVlZX7iIiI8H9/f7h/f38UAAAAAAAAAAAAAAAAAAAAAAAAAAB/f38egYF/noqAebF8gYaagnx3oFpUUtZpaWr/WFhY8zo6OmT///8BAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgICAn46Ojv+Hh4b/jouJ/4iGhfcAAADnAAAA/wAAAP8AAADIAAAAAwCj/zIAnf2VAJD/PAAAAAAAAAAAAAAAAICAgNGHh4f/gICA/4SEhP+Xl5f/AwMD/wAAAP8AAAD/AAAA/wAAAB8Aov9/ALr//wCS/Z0AAAAAAAAAAAAAAACBgYGOjo6O/4mJif+Pj4//iYmJ/wAAAOAAAAD+AAAA/wAAAP8AAABhAP7+FgCi/38Axf4fAAAAAAAAAAAAAAAAiIiID4GBgYKCgoKogoB+fYSEgZhgYGDZXl5e/m9vb/9ISEjpEBAQxw8AAFQAAAAAAAAANQAAADcAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAjo6Mb5iYmP+cnJz/jY2N95CQkO4pKSn/AAAA7gAAAP0AAAD7AAAAhgAAAAEAAAAAAAAAAACL/gsAkv2uAJX/QQAAAAB9fX3egoKC/4CAgP+NjY3/c3Nz+wAAAP8AAAD/AAAA/wAAAPUAAAAcAAAAAAAAAAAAnP4NAJL9rgCR/0YAAAAAfX19w4ODg/98fHz/i4uL/4qKivwAAAD/AAAA/wAAAP8AAAD1AAAAGwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAALGxsVyqqqr/mpqa/6mpqf9KSUn/AAAA5QAAAPkAAAD5AAAAhQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADkUFBSuZ2dn/3V1df8uLi7bAAAATgBGfyQAAAA2AAAAMwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAB0AAADoAAAA/wAAAP8AAAD/AAAAWgC3/2AAnv3eAJ/+dgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA9AAAA/wAAAP8AAAD/AAAA/wAKDzEAnP3WAKn//wCS/OgAf/8MAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIQAAANwAAADtAAAA7QAAAMAAABUMAJn9gwCe/e0Aj/2LAP//AQAAAAAAAAAA)](https://www.mdanalysis.org)
+[![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
 
 
 PsiRESP is a package for calculating atomic partial charges from
@@ -50,6 +48,7 @@ cd psiresp
 python setup.py install
 ```
 
+Please see [the Installation docs](https://psiresp.readthedocs.io/en/latest/installation.html) for more information on installation and dependencies.
 
 ### Example
 

diff --git a/devtools/conda-envs/docs_env.yaml b/devtools/conda-envs/docs_env.yaml
@@ -47,5 +47,5 @@ dependencies:
       # - nbsphinx
       # - sphinx<4.0
       - sphinx_rtd_theme
-      - sphinxcontrib-bibtex<2.0.0
+      - sphinxcontrib-bibtex
       - sphinx-sitemap
diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css
@@ -0,0 +1,3 @@
+.wy-table-responsive table td, .wy-table-responsive table th {
+    white-space: inherit;
+}
diff --git a/docs/source/bibliography.bib b/docs/source/bibliography.bib
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -58,7 +58,8 @@
     'IPython.sphinxext.ipython_console_highlighting',
     'IPython.sphinxext.ipython_directive',
     'sphinxcontrib.autodoc_pydantic',
-    'nbsphinx'
+    'nbsphinx',
+    'sphinx.ext.autosectionlabel'
 ]
 
 mathjax_path = 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML'
@@ -114,7 +115,6 @@
     'display_version': True,
     'prev_next_buttons_location': 'bottom',
     'style_external_links': False,
-    'style_nav_header_background': 'white',
     # Toc options
     'collapse_navigation': True,
     'sticky_navigation': True,
@@ -127,6 +127,8 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+html_css_files = ['css/custom.css']
+
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -220,3 +222,5 @@
 """
 
 html_js_files = []
+
+bibtex_bibfiles = ["bibliography.bib"]
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
@@ -0,0 +1,30 @@
+Contributing
+============
+
+Contributions can take many forms, such as:
+
+    * sharing bug reports or feature requests through the `Issue Tracker`_
+    * asking or answering questions, or otherwise joining in on `Discussions`_
+    * adding bug fixes, new features, or otherwise improving the code
+    * adding or improving documentation
+
+The second two options both involve making a `pull request`_ .
+
+There are many existing guides on how to make a contribution to an open
+source project on GitHub, such as the `MDAnalysis User Guide`_ .
+In short, the steps are to:
+
+    #. Fork the repository into your own account and download your fork
+    #. Create a development environment from source, following the :ref:`Installation` instructions
+    #. Create a new branch off the `master` branch with a meaningful name (e.g. ``git checkout -b fix-issue-39``)
+    #. Add your modifications to the code or documentation
+    #. Add tests if modifying the code
+    #. Commit and push changes to GitHub, and open a pull request
+
+
+
+
+.. _`Issue Tracker`: https://github.com/lilyminium/psiresp/issues
+.. _`pull request`: https://github.com/lilyminium/psiresp/pulls
+.. _`MDAnalysis User Guide`: https://userguide.mdanalysis.org/stable/contributing.html
+.. _Discussions: https://github.com/lilyminium/psiresp/discussions
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -18,19 +18,41 @@ around heavy atoms.
 
 For ease of use, PsiRESP offers pre-configured classes that correspond with
 existing popular tools such as the RESP ESP Charge Derive (R.E.D.) tools
-and the Automated Topology Builder.
+and the Automated Topology Builder. Please see :ref:`RESP` for more details
+on RESP fitting and the pre-configured classes (:ref:`Pre-configured classes`).
+
+
+----------------
+Getting involved
+----------------
+
+If you have a problem or feature request, please let us know
+at the `Issue Tracker`_ on GitHub. If you have any questions or comments,
+visit us on our `Discussions`_ board.
+
+Pull requests and other contributions are also very welcomed. Please see
+:ref:`Contributing` for more tips.
+
+
+-------
+License
+-------
+
+PsiRESP is licensed under the GNU Lesser General Public License (LGPL).
 
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
    installation
    usage
    examples/README
+   resp
    molecule
    charge_constraints
    hpc
+   contributing
    api
    references
 
@@ -43,3 +65,7 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+
+
+.. _`Issue Tracker`: https://github.com/lilyminium/psiresp/issues
+.. _Discussions: https://github.com/lilyminium/psiresp/discussions
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -15,7 +15,7 @@ If you need the latest development environment, build from source::
   conda env create -f devtools/conda-envs/environment.yaml
   conda activate psiresp
   # build the package
-  python setup.py install
+  python setup.py develop  # or python setup.py install if not creating a development environment
 
 
 To run tests::
@@ -24,3 +24,22 @@ To run tests::
   pytest . --disable-pytest-warnings
 
 
+------------
+Dependencies
+------------
+
+The core dependencies of PsiRESP are:
+
+  * `psi4 <https://psicode.org/>`_
+  * `geomeTRIC <https://github.com/leeping/geomeTRIC>`_
+  * `qcelemental <https://docs.qcarchive.molssi.org/projects/QCElemental/en/stable/>`_
+  * `qcengine <https://docs.qcarchive.molssi.org/projects/qcengine/en/stable/>`_
+  * `qcfractal <https://docs.qcarchive.molssi.org/projects/qcfractal/en/stable/>`_
+  * `rdkit <https://www.rdkit.org/>`_
+  * `numpy <https://numpy.org/>`_
+  * `scipy <https://scipy.org/>`_
+  * `pydantic <https://pydantic-docs.helpmanual.io/>`_
+
+Psi4 and RDKit are only available via ``conda``, so it is best to use ``conda``
+to create your Python environment. An environment file is provided for
+use with ``conda``, as demonstrated above.
diff --git a/docs/source/references.rst b/docs/source/references.rst
@@ -6,15 +6,19 @@
 References
 ==========
 
-References good
+PsiRESP is built on published scientific work.
+**Please cite the relevant references when using PsiRESP in published work**,
+specifically the citation in :ref:`Pre-configured classes`.
+
+PsiRESP uses the Connolly algorithm to generate molecular surfaces :cite:p:`connolly1983`.
 
 
 .. _citations-with-duecredit:
 
 Citations with Duecredit
 ========================
 
-Some citations can be genrated with duecredit_. This is installed with 
+Some citations can be automatically generated with duecredit_. This is installed with 
 the conda environment files in ``devtools/``, or can be otherwise installed 
 with:
 
@@ -42,4 +46,5 @@ Do it in the BibTeX format, using:
 Bibliography
 ============
 
-.. bibliography::
+.. bibliography:: bibliography.bib
+   :all:
diff --git a/docs/source/resp.rst b/docs/source/resp.rst
@@ -1,17 +1,86 @@
 RESP
 ====
 
+----------
+Background
+----------
+
 The electrostatic potential :math:`V` is the potential generated
 by the nuclei and electrons in a molecule.
 At any point in space :math:`r`, it is:
 
 .. math::
     V(\vec{r}) = \sum_{n=1}^{nuclei} \frac{Z_n}{|\vec{r} - \vec{R}_n|} - \int \frac{\rho(\vec{r’})}{|\vec{r} - \vec{r’}|} d\vec{r}
 
+If we generate a grid of points around the molecule and evaluate the
+potential felt at each grid point, we can set up a system of linear
+equations to determine the partial charges for the atoms in the
+molecule that would best fit the potential. Because the grid of points
+is typically generated at certain radii from each atom, forming a 
+"surface layer" around the molecule, the system of linear
+equations is commonly called "surface constraints" in the code and
+throughout the documentation.
+
+You can add your own charge constraints to the "surface constraints"
+to form an overall constraint matrix. These charge constraints can
+control what charge a group of atoms should sum to 
+(:class:`~psiresp.charge.ChargeSumConstraint`) or if one atom
+should have an equivalent charge to other atoms
+(:class:`~psiresp.charge.ChargeEquivalenceConstraint`).
+
+The equations represented by the constraint matrix
+can be solved for the charges of best fit,
+as first published by Singh and Kollman in 1984 :cite:p:`singh1984`.
+
+Commonly, a "restrained fit" is performed to derive the final charges :cite:p:`bayly1993,cornell1993,cieplak1995`.
+
+The hyperbolic restraint has the form:
+
+.. math::
+
+    \chi_{penalty} = a\sum_{n=1}^{nuclei} ((q_{n}^{2} + b^2)^{1/2} – b)
+
+
+:math:`a` defines the asymptotic limits of the penalty, and corresponds to
+:attr:`~psiresp.resp.RespOptions.resp_a1` and
+:attr:`~psiresp.resp.RespOptions.resp_a2` for the stage 1 and stage 2
+fits, respectively.
+:math:`b` defines the width of the penalty, and corresponds to
+:attr:`~psiresp.resp.RespOptions.resp_b`.
+
+If you only want a one-stage fit, the process stops here.
+In a two-stage fit, the typical charge model in AMBER and CHARMM
+force fields, the above is repeated. The difference between the
+stages is in the charge restraints. In the first stage, all charges
+are free to vary. In the second stage fit, atoms without an equivalence
+constraint are fixed (i.e. their charges remain static from stage 1).
+However, atoms within an equivalence constraint are free to vary.
+In more technical detail, this is the process for each stage:
+
+    1. All charge equivalence constraints are ignored,
+       and the charges of all atoms are free to vary.
+       This includes the hydrogens around sp3 carbons,
+       which we would expect to be symmetric or equivalent.
+    2. The charge equivalence constraints are added back in the
+       second stage. For all atoms that are *not* involved in
+       an equivalence constraint, their charges are fixed to
+       the stage 1 charges. Now the constraint matrix is only
+       solved to calculate the charges of the equivalent atoms.
+
 
+.. note::
 
+    sp3 carbons where the attached hydrogens are involved in a constraint,
+    are also not given a fixed charge in stage 2 fits, but left free to vary.
 
-The general process of computing RESP charges is as follows:
+
+
+
+---------------
+Practical steps
+---------------
+
+The general, practical process of computing RESP charges is as follows:
 
 #. Generate some number of conformers
 #. (Optional) Use Psi4 to optimize the geometry of each conformer
@@ -20,4 +89,43 @@ The general process of computing RESP charges is as follows:
 #. Generate a grid of points around each molecule
 #. Evaluate the electrostatic potential (ESP) of the molecule on the grid points
 #. (Optional) Set charge constraints
-#. Fit charges to these charge constraints and ESPs according to specified RESP options
+#. Fit charges to these charge constraints and ESPs according to specified RESP options
+
+
+All of these are handled for you under the hood with :meth:`psiresp.job.Job.run`.
+
+
+----------------------
+Pre-configured classes
+----------------------
+
+The table below gives a broad overview of the pre-configured classes.
+
+.. table:: Overview of pre-configured RESP classes
+    :widths: 30 50 20
+
+    +----------------------------------+------------------------------------+-------------------------+
+    | Class                            | Description                        | Reference               |
+    +==================================+====================================+=========================+
+    | :class:`psiresp.configs.RespA1`  | A 2-stage restrained fit           | :cite:t:`bayly1993`,    |
+    |                                  | in the gas phase at hf/6-31g*      | :cite:t:`cornell1993`,  |
+    |                                  |                                    | :cite:t:`cieplak1995`   |
+    +----------------------------------+------------------------------------+-------------------------+
+    | :class:`psiresp.configs.RespA2`  | A 1-stage restrained fit           |                         |
+    |                                  | in the gas phase at hf/6-31g*      |                         |
+    +----------------------------------+------------------------------------+-------------------------+
+    | :class:`psiresp.configs.EspA1`   | A 1-stage unrestrained fit         | :cite:t:`singh1984`     |
+    |                                  | in the gas phase at hf/6-31g*      |                         |
+    +----------------------------------+------------------------------------+-------------------------+
+    | :class:`psiresp.configs.EspA2`   | A 1-stage unrestrained fit         |                         |
+    |                                  | in the gas phase at hf/sto-3g      |                         |
+    +----------------------------------+------------------------------------+-------------------------+
+    | :class:`psiresp.configs.ATBResp` | A 2-stage restrained fit in        | :cite:t:`malde2011`     |
+    |                                  | implicit water at b3lyp/6-31g*     |                         |
+    +----------------------------------+------------------------------------+-------------------------+
+    | :class:`psiresp.configs.Resp2`   | A 2-stage restrained fit           | :cite:t:`schauperl2020` |
+    |                                  | at pw6b95/aug-cc-pV(D+d)Z,         |                         |
+    |                                  | in both vacuum and implicit water. |                         |
+    |                                  | Charges are interpolated           |                         |
+    |                                  | between the two phases.            |                         |
+    +----------------------------------+------------------------------------+-------------------------+
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
@@ -50,13 +50,14 @@ Customising RESP charge computation
 -----------------------------------
 
 Each of the aspects of computing RESP charges can be customised to correspond
-to the implementations used by :cite:p:`Bayly1993`, :cite:p:`Singh1984`,
-:cite:p:`Malde2011`, :cite:p:`Schauperl2020`, and so on. These require setting options
+to the implementations used by :cite:t:`bayly1993`, :cite:t:`singh1984`,
+:cite:t:`malde2011`, :cite:t:`schauperl2020`, and so on. These require setting options
 for grid generation, the QM computation, and the hyperbolic restraints themselves;
 please see :ref:`option_classes` for the specific options.
 
 However, for ease of use, PsiRESP also provides pre-configured classes.
-A full list is available at :ref:`preconfigured_classes`. In order to use these,
+A full list is available at :ref:`preconfigured_classes`
+as well as :ref:`Pre-configured classes`. In order to use these,
 simply replace `Job` with the particular chosen configuration:
 
 .. ipython:: python