diff --git a/README.md b/README.md
index 0e1ae01d..39c0143e 100644
--- a/README.md
+++ b/README.md
@@ -8,9 +8,7 @@
[](https://psiresp.readthedocs.io/en/latest/?badge=latest)
[](https://lgtm.com/projects/g/lilyminium/psiresp/context:python)
[](https://badge.fury.io/py/psiresp)
-
-
-[](https://www.mdanalysis.org)
+[](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
index bea59248..31271429 100644
--- 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
new file mode 100644
index 00000000..25a4aa15
--- /dev/null
+++ 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
new file mode 100644
index 00000000..2fe76e7a
--- /dev/null
+++ b/docs/source/bibliography.bib
@@ -0,0 +1,232 @@
+
+@article{malde2011,
+ title = {An {Automated} {Force} {Field} {Topology} {Builder} ({ATB}) and {Repository}: {Version} 1.0},
+ volume = {7},
+ issn = {1549-9618, 1549-9626},
+ shorttitle = {An {Automated} {Force} {Field} {Topology} {Builder} ({ATB}) and {Repository}},
+ url = {https://pubs.acs.org/doi/10.1021/ct200196m},
+ doi = {10.1021/ct200196m},
+ abstract = {The Automated force field Topology Builder (ATB, http://compbio.biosci.uq.edu.au/atb) is a Web-accessible server that can provide topologies and parameters for a wide range of molecules appropriate for use in molecular simulations, computational drug design, and X-ray refinement. The ATB has three primary functions: (1) to act as a repository for molecules that have been parametrized as part of the GROMOS family of force fields, (2) to act as a repository for pre-equilibrated systems for use as starting configurations in molecular dynamics simulations (solvent mixtures, lipid systems pre-equilibrated to adopt a specific phase, etc.), and (3) to generate force field descriptions of novel molecules compatible with the GROMOS family of force fields in a variety of formats (GROMOS, GROMACS, and CNS). Force field descriptions of novel molecules are derived using a multistep process in which results from quantum mechanical (QM) calculations are combined with a knowledge-based approach to ensure compatibility (as far as possible) with a specific parameter set of the GROMOS force field. The ATB has several unique features: (1) It requires that the user stipulate the protonation and tautomeric states of the molecule. (2) The symmetry of the molecule is analyzed to ensure that equivalent atoms are assigned identical parameters. (3) Charge groups are assigned automatically. (4) Where the assignment of a given parameter is ambiguous, a range of possible alternatives is provided. The ATB also provides several validation tools to assist the user to assess the degree to which the topology generated may be appropriate for a given task. In addition to detailing the steps involved in generating a force field topology compatible with a specific GROMOS parameter set (GROMOS 53A6), the challenges involved in the automatic generation of force field parameters for atomic simulations in general are discussed.},
+ language = {en},
+ number = {12},
+ urldate = {2019-05-29},
+ journal = {Journal of Chemical Theory and Computation},
+ author = {Malde, Alpeshkumar K. and Zuo, Le and Breeze, Matthew and Stroet, Martin and Poger, David and Nair, Pramod C. and Oostenbrink, Chris and Mark, Alan E.},
+ month = dec,
+ year = {2011},
+ note = {00000},
+ keywords = {Must-cite, ATB},
+ pages = {4026--4037},
+ file = {Malde_2011_An_Automated_Force_Field_Topology_Builder_(ATB)_and_Repository_-_Version_1.0.pdf:/Users/lily/OneDrive - Australian National University/Papers/Malde_2011_An_Automated_Force_Field_Topology_Builder_(ATB)_and_Repository_-_Version_1.0.pdf:application/pdf},
+}
+
+
+@article{cieplak1995,
+ title = {Application of the multimolecule and multiconformational {RESP} methodology to biopolymers: {Charge} derivation for {DNA}, {RNA}, and proteins},
+ volume = {16},
+ issn = {0192-8651, 1096-987X},
+ shorttitle = {Application of the multimolecule and multiconformational {RESP} methodology to biopolymers},
+ url = {http://doi.wiley.com/10.1002/jcc.540161106},
+ doi = {10.1002/jcc.540161106},
+ language = {en},
+ number = {11},
+ urldate = {2019-08-06},
+ journal = {Journal of Computational Chemistry},
+ author = {Cieplak, Piotr and Cornell, Wendy D. and Bayly, Christopher and Kollman, Peter A.},
+ month = nov,
+ year = {1995},
+ note = {00876},
+ keywords = {RESP},
+ pages = {1357--1377},
+ file = {Cieplak_1995_Application_of_the_multimolecule_and_multiconformational_RESP_methodology_to_biopolymers_-_Charge.pdf:/Users/lily/OneDrive - Australian National University/Papers/Cieplak_1995_Application_of_the_multimolecule_and_multiconformational_RESP_methodology_to_biopolymers_-_Charge.pdf:application/pdf},
+}
+
+@article{cornell1993,
+ title = {Application of {RESP} charges to calculate conformational energies, hydrogen bond energies, and free energies of solvation},
+ volume = {115},
+ issn = {0002-7863, 1520-5126},
+ url = {http://pubs.acs.org/doi/abs/10.1021/ja00074a030},
+ doi = {10.1021/ja00074a030},
+ abstract = {We apply a new restrained electrostatic potential fit charge model (two-stage RESP) to conformational analysis and the calculation of intermolecular interactions. Specifically, we study conformational energies in butane, methyl ethyl thioether, three simple alcohols, three simple amines, and 1,2-ethanediol as a function of charge model (two-stage RESP vs standard ESP) and 1-4 electrostatic scale factor. We demonstrate that the two-stage RESP model with a 1-4 electrostatic scale factor of —1/1.2 is a very good model, as evaluated by comparison with high-level ab initio calculations. For methanol and /V-methylacetamide interactions with TIP3P water, the two-stage RESP model leads to hydrogen bonds only slightly weaker than found with the standard ESP changes. In tests on DNA base pairs, the two-stage RESP model leads to hydrogen bonds which are {\textasciitilde} 1 kcal/mol weaker than those calculated with the standard ESP charges but closer in magnitude to the best current available ab initio calculations. Furthermore, the two-stage RESP charges, unlike the standard ESP charges, reproduce the result that Hoogsteen hydrogen bonding is stronger than Watson-Crick hydrogen bonding for adenine-thymine base pairs. The free energies of solvation of both methanol and f/ww-iV-methylacetamide were also calculated for the standard ESP and two-stage RESP models and both were in good agreement with experiment. We have combined the use of two-stage RESP charges with multiple conformational fitting—recently employed using standard ESP charges as described by Reynolds, et al. (J. Am. Chem. Soc. 1992, 114, 9075)—in studies of conformationally dependent dipole moments and energies of propylamine. We find that the combination of these approaches is synergistic in leading to useful charge distributions for molecular simulations. Two-stage RESP charges thus reproduce both intermolecular and intramolecular energies and structures quite well, making this charge model a critical advancement in the development of a general force field for modeling biological macromolecules and their ligands, both in the gas phase and in solution.},
+ language = {en},
+ number = {21},
+ urldate = {2019-08-06},
+ journal = {Journal of the American Chemical Society},
+ author = {Cornell, Wendy D. and Cieplak, Piotr and Bayly, Christopher I. and Kollman, Peter A.},
+ month = oct,
+ year = {1993},
+ note = {01110},
+ keywords = {RESP},
+ pages = {9620--9631},
+ file = {Cornell_1993_Application_of_RESP_charges_to_calculate_conformational_energies,_hydrogen_bond_energies,_and_free.pdf:/Users/lily/OneDrive - Australian National University/Papers/Cornell_1993_Application_of_RESP_charges_to_calculate_conformational_energies,_hydrogen_bond_energies,_and_free.pdf:application/pdf},
+}
+
+@article{bayly1993,
+ title = {A well-behaved electrostatic potential based method using charge restraints for deriving atomic charges: the {RESP} model},
+ volume = {97},
+ issn = {0022-3654, 1541-5740},
+ shorttitle = {A well-behaved electrostatic potential based method using charge restraints for deriving atomic charges},
+ url = {http://pubs.acs.org/doi/abs/10.1021/j100142a004},
+ doi = {10.1021/j100142a004},
+ language = {en},
+ number = {40},
+ urldate = {2019-08-06},
+ journal = {The Journal of Physical Chemistry},
+ author = {Bayly, Christopher I. and Cieplak, Piotr and Cornell, Wendy and Kollman, Peter A.},
+ month = oct,
+ year = {1993},
+ note = {04975},
+ keywords = {RESP},
+ pages = {10269--10280},
+ file = {Bayly_1993_A_well-behaved_electrostatic_potential_based_method_using_charge_restraints_for_deriving_atomic.pdf:/Users/lily/OneDrive - Australian National University/Papers/Bayly_1993_A_well-behaved_electrostatic_potential_based_method_using_charge_restraints_for_deriving_atomic.pdf:application/pdf},
+}
+
+@article{dupradeau2010,
+ title = {The {R}.{E}.{D}. tools: advances in {RESP} and {ESP} charge derivation and force field library building},
+ volume = {12},
+ issn = {1463-9076, 1463-9084},
+ shorttitle = {The {R}.{E}.{D}. tools},
+ url = {http://xlink.rsc.org/?DOI=c0cp00111b},
+ doi = {10.1039/c0cp00111b},
+ language = {en},
+ number = {28},
+ urldate = {2019-08-06},
+ journal = {Physical Chemistry Chemical Physics},
+ author = {Dupradeau, François-Yves and Pigache, Adrien and Zaffran, Thomas and Savineau, Corentin and Lelong, Rodolphe and Grivel, Nicolas and Lelong, Dimitri and Rosanski, Wilfried and Cieplak, Piotr},
+ year = {2010},
+ note = {00595},
+ keywords = {RESP, RED},
+ pages = {7821},
+ file = {Dupradeau_2010_The_R.E.D._tools_-_advances_in_RESP_and_ESP_charge_derivation_and_force_field_library_building.pdf:/Users/lily/OneDrive - Australian National University/Papers/Dupradeau_2010_The_R.E.D._tools_-_advances_in_RESP_and_ESP_charge_derivation_and_force_field_library_building.pdf:application/pdf},
+}
+
+@article{dupradeau2007,
+ title = {R.{E}.{DD}.{B}.: {A} database for {RESP} and {ESP} atomic charges, and force field libraries},
+ volume = {36},
+ issn = {0305-1048, 1362-4962},
+ shorttitle = {R.{E}.{DD}.{B}.},
+ url = {https://academic.oup.com/nar/article-lookup/doi/10.1093/nar/gkm887},
+ doi = {10.1093/nar/gkm887},
+ abstract = {The web-based RESP ESP charge DataBase (R.E.DD.B., http://q4md-forcefieldtools.org/REDDB) is a free and new source of RESP and ESP atomic charge values and force field libraries for model systems and/or small molecules. R.E.DD.B. stores highly effective and reproducible charge values and molecular structures in the Tripos mol2 file format, information about the charge derivation procedure, scripts to integrate the charges and molecular topology in the most common molecular dynamics packages. Moreover, R.E.DD.B. allows users to freely store and distribute RESP or ESP charges and force field libraries to the scientific community, via a web interface. The first version of R.E.DD.B., released in January 2006, contains force field libraries for molecules as well as molecular fragments for standard residues and their analogs (amino acids, monosaccharides, nucleotides and ligands), hence covering a vast area of relevant biological applications.},
+ language = {en},
+ number = {Database},
+ urldate = {2019-08-06},
+ journal = {Nucleic Acids Research},
+ author = {Dupradeau, F.-Y. and Cezard, C. and Lelong, R. and Stanislawiak, E. and Pecher, J. and Delepine, J. C. and Cieplak, P.},
+ month = dec,
+ year = {2007},
+ note = {00081},
+ keywords = {RESP, RED},
+ pages = {D360--D367},
+ file = {Dupradeau_2007_R.E.DD.B._-_A_database_for_RESP_and_ESP_atomic_charges,_and_force_field_libraries.pdf:/Users/lily/OneDrive - Australian National University/Papers/Dupradeau_2007_R.E.DD.B._-_A_database_for_RESP_and_ESP_atomic_charges,_and_force_field_libraries.pdf:application/pdf},
+}
+
+@article{schauperl2020,
+ title = {Non-bonded force field model with advanced restrained electrostatic potential charges ({RESP2})},
+ volume = {3},
+ copyright = {2020 The Author(s)},
+ issn = {2399-3669},
+ url = {https://www.nature.com/articles/s42004-020-0291-4},
+ doi = {10.1038/s42004-020-0291-4},
+ abstract = {The restrained electrostatic potential (RESP) is a widely used method for assigning partial charges to organic molecules for molecular dynamics simulations, but it imperfectly accounts for self-polarization in solution. Here, RESP is updated by co-optimizing the polarity of the charges it generates, along with atomic Lennard-Jones parameters, to yield an improved model of non-bonded interactions.},
+ language = {en},
+ number = {1},
+ urldate = {2020-05-13},
+ journal = {Communications Chemistry},
+ author = {Schauperl, Michael and Nerenberg, Paul S. and Jang, Hyesu and Wang, Lee-Ping and Bayly, Christopher I. and Mobley, David L. and Gilson, Michael K.},
+ month = apr,
+ year = {2020},
+ note = {00000
+Number: 1
+Publisher: Nature Publishing Group},
+ pages = {1--11},
+ file = {Snapshot:/Users/lily/Zotero/storage/Q8ULS29F/s42004-020-0291-4.html:text/html;Full Text PDF:/Users/lily/Zotero/storage/MCPLH9GL/Schauperl et al. - 2020 - Non-bonded force field model with advanced restrai.pdf:application/pdf},
+}
+
+@article{alenaizan2020,
+ title = {Python implementation of the restrained electrostatic potential charge model},
+ volume = {120},
+ copyright = {© 2019 Wiley Periodicals, Inc.},
+ issn = {1097-461X},
+ url = {http://onlinelibrary.wiley.com/doi/abs/10.1002/qua.26035},
+ doi = {10.1002/qua.26035},
+ abstract = {The restrained electrostatic potential (RESP) charge model is widely used in molecular dynamics simulations, especially for the AMBER and GAFF force fields. We have implemented the RESP scheme using the accessible and widely used Python language and the NumPy numerical library. This article provides a programming-oriented introduction to the RESP scheme and highlights some of the features of NumPy that are useful in scientific computing.},
+ language = {en},
+ number = {2},
+ urldate = {2020-05-01},
+ journal = {International Journal of Quantum Chemistry},
+ author = {Alenaizan, Asem and Burns, Lori A. and Sherrill, C. David},
+ year = {2020},
+ note = {00000
+\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1002/qua.26035},
+ keywords = {RESP},
+ pages = {e26035},
+ file = {Full Text PDF:/Users/lily/Zotero/storage/QCGEERRQ/Alenaizan et al. - 2020 - Python implementation of the restrained electrosta.pdf:application/pdf;Snapshot:/Users/lily/Zotero/storage/B2P252VB/qua.html:text/html},
+}
+
+@article{singh1984,
+ title = {An approach to computing electrostatic charges for molecules},
+ volume = {5},
+ copyright = {Copyright © 1984 John Wiley \& Sons, Inc.},
+ issn = {1096-987X},
+ url = {http://onlinelibrary.wiley.com/doi/abs/10.1002/jcc.540050204},
+ doi = {10.1002/jcc.540050204},
+ abstract = {We present an approach for deriving net atomic charges from ab initio quantum mechanical calculations using a least squares fit of the quantum mechanically calculated electrostatic potential to that of the partial charge model. Our computational approach is similar to those presented by Momany [J. Phys. Chem., 82, 592 (1978)], Smit, Derissen, and van Duijneveldt [Mol. Phys., 37, 521 (1979)], and Cox and Williams [J. Comput. Chem., 2, 304 (1981)], but differs in the approach to choosing the positions for evaluating the potential. In this article, we present applications to the molecules H2O, CH3OH, (CH3)2O, H2CO, NH3, (CH3O)2PO, deoxyribose, ribose, adenine, 9-CH3 adenine, thymine, 1-CH3 thymine, guanine, 9-CH3 guanine, cytosine, 1-CH3 cytosine, uracil, and 1-CH3 uracil. We also address the question of inclusion of “lone pairs,” their location and charge.},
+ language = {en},
+ number = {2},
+ urldate = {2020-05-11},
+ journal = {Journal of Computational Chemistry},
+ author = {Singh, U. Chandra and Kollman, Peter A.},
+ year = {1984},
+ note = {00000
+\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1002/jcc.540050204},
+ keywords = {RESP, ESP, partial charges},
+ pages = {129--145},
+ file = {Singh_1984_An_approach_to_computing_electrostatic_charges_for_molecules.pdf:/Users/lily/OneDrive - Australian National University/Papers/Singh_1984_An_approach_to_computing_electrostatic_charges_for_molecules2.pdf:application/pdf;Singh_1984_An_approach_to_computing_electrostatic_charges_for_molecules.pdf:/Users/lily/OneDrive - Australian National University/Papers/Singh_1984_An_approach_to_computing_electrostatic_charges_for_molecules.pdf:application/pdf;Snapshot:/Users/lily/Zotero/storage/9H5327AH/jcc.html:text/html},
+}
+
+
+@article{connolly1983,
+ title = {Analytical molecular surface calculation},
+ volume = {16},
+ issn = {1600-5767},
+ url = {http://onlinelibrary.wiley.com/doi/abs/10.1107/S0021889883010985},
+ doi = {https://doi.org/10.1107/S0021889883010985},
+ abstract = {A computer algorithm is presented for calculating the part of the van der Waals surface of molecule that is accessible to solvent. The solvent molecule is modeled by a sphere. This sphere is, in effect, rolled over the molecule to generate a smooth outer-surface contour. This surface contour is made up of pieces of spheres and tori that join at circular arcs. The spheres, tori and arcs are defined by analytical expressions in terms of the atomic coordinates, van der Waals radii and the probe radius. The area of each surface piece may be calculated analytically and the surface may be displayed on either vector or raster computer-graphics systems. These methods are useful for studying the structure and interactions of proteins and nucleic acids.},
+ language = {en},
+ number = {5},
+ urldate = {2021-04-05},
+ journal = {Journal of Applied Crystallography},
+ author = {Connolly, M. L.},
+ year = {1983},
+ note = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1107/S0021889883010985},
+ pages = {548--558},
+ file = {Full Text PDF:/Users/lily/Zotero/storage/USRVLP5U/Connolly - 1983 - Analytical molecular surface calculation.pdf:application/pdf;Snapshot:/Users/lily/Zotero/storage/GA5D5F2C/S0021889883010985.html:text/html},
+}
+
+@misc{rdkit,
+ title = {{RDKit}: {Open}-source cheminformatics},
+ url = {rdkit.org},
+ author = {Landrum, Gregory},
+ note = {https://doi.org/10.5281/zenodo.4107869},
+}
+
+@article{psi4,
+ title = {Psi4: an open-source ab initio electronic structure program},
+ volume = {2},
+ copyright = {Copyright © 2011 John Wiley \& Sons, Ltd.},
+ issn = {1759-0884},
+ shorttitle = {Psi4},
+ url = {http://onlinelibrary.wiley.com/doi/abs/10.1002/wcms.93},
+ doi = {https://doi.org/10.1002/wcms.93},
+ abstract = {The Psi4 program is a new approach to modern quantum chemistry, encompassing Hartree–Fock and density-functional theory to configuration interaction and coupled cluster. The program is written entirely in C++ and relies on a new infrastructure that has been designed to permit high-efficiency computations of both standard and emerging electronic structure methods on conventional and high-performance parallel computer architectures. Psi4 offers flexible user input built on the Python scripting language that enables both new and experienced users to make full use of the program's capabilities, and even to implement new functionality with moderate effort. To maximize its impact and usefulness, Psi4 is available through an open-source license to the entire scientific community. © 2011 John Wiley \& Sons, Ltd. This article is categorized under: Software {\textgreater} Quantum Chemistry},
+ language = {en},
+ number = {4},
+ urldate = {2021-04-05},
+ journal = {WIREs Computational Molecular Science},
+ author = {Turney, Justin M. and Simmonett, Andrew C. and Parrish, Robert M. and Hohenstein, Edward G. and Evangelista, Francesco A. and Fermann, Justin T. and Mintz, Benjamin J. and Burns, Lori A. and Wilke, Jeremiah J. and Abrams, Micah L. and Russ, Nicholas J. and Leininger, Matthew L. and Janssen, Curtis L. and Seidl, Edward T. and Allen, Wesley D. and Schaefer, Henry F. and King, Rollin A. and Valeev, Edward F. and Sherrill, C. David and Crawford, T. Daniel},
+ year = {2012},
+ note = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1002/wcms.93},
+ pages = {556--565},
+ file = {Full Text PDF:/Users/lily/Zotero/storage/S33QBJYB/Turney et al. - 2012 - Psi4 an open-source ab initio electronic structur.pdf:application/pdf;Snapshot:/Users/lily/Zotero/storage/TLLP89PW/wcms.html:text/html},
+}
diff --git a/docs/source/conf.py b/docs/source/conf.py
index da8d4a9e..8cc54351 100644
--- 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
new file mode 100644
index 00000000..71f4853b
--- /dev/null
+++ 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
index 2bc06c60..b6dcb7a0 100644
--- 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
\ No newline at end of file
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index 3cb51705..65e8a4a8 100644
--- 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 `_
+ * `geomeTRIC `_
+ * `qcelemental `_
+ * `qcengine `_
+ * `qcfractal `_
+ * `rdkit `_
+ * `numpy `_
+ * `scipy `_
+ * `pydantic `_
+
+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.
\ No newline at end of file
diff --git a/docs/source/references.rst b/docs/source/references.rst
index 28059324..80191582 100644
--- a/docs/source/references.rst
+++ b/docs/source/references.rst
@@ -6,7 +6,11 @@
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:
@@ -14,7 +18,7 @@ References good
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::
\ No newline at end of file
+.. bibliography:: bibliography.bib
+ :all:
\ No newline at end of file
diff --git a/docs/source/resp.rst b/docs/source/resp.rst
index 4171f3a5..801765fe 100644
--- a/docs/source/resp.rst
+++ b/docs/source/resp.rst
@@ -1,6 +1,10 @@
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:
@@ -8,10 +12,75 @@ 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
\ No newline at end of file
+#. 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
index ea127974..2b67c572 100644
--- 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