Merge pull request #35 from xhgchen/fix-docs

Fix VACF docs and enable viscosity docs
MDAnalysis · Aug 25, 2023 · d997226 · d997226
2 parents 26d390e + 4df6856
commit d997226
Show file tree

Hide file tree

Showing 9 changed files with 34 additions and 17 deletions.
diff --git a/AUTHORS.md b/AUTHORS.md
@@ -5,7 +5,7 @@ and Orion Cohen in 2023.
 
 
 All contributing authors are listed in this file below.
-The repository history at https://github.com/MDAnalysis/transport_analysis
+The repository history at https://github.com/MDAnalysis/transport-analysis
 and the CHANGELOG show individual code contributions.
 
 ## Chronological list of authors

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -4,12 +4,12 @@ We welcome all contributions to Transport Analysis!
 
 Contributions can take many forms, such as:
 
-* sharing bug reports or feature requests through the [Issue Tracker](https://github.com/MDAnalysis/transport_analysis/issues)
+* sharing bug reports or feature requests through the [Issue Tracker](https://github.com/MDAnalysis/transport-analysis/issues)
 * 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](https://github.com/MDAnalysis/transport_analysis/pulls) .
+The second two options both involve making a [pull request](https://github.com/MDAnalysis/transport-analysis/pulls) .
 
 There are many existing guides on how to make a contribution to an open
 source project on GitHub. In short, the steps are to:

diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -9,3 +9,4 @@ API Documentation
    :caption: API Reference
 
    api/velocityautocorr
+   api/viscosity
diff --git a/docs/source/api/velocityautocorr.rst b/docs/source/api/velocityautocorr.rst
@@ -1,5 +1,5 @@
-VelocityAutocorr
-================
+Velocity Autocorrelation Function
+=================================
 
  .. automodule:: transport_analysis.velocityautocorr
     :members:
diff --git a/docs/source/api/viscosity.rst b/docs/source/api/viscosity.rst
@@ -0,0 +1,5 @@
+Viscosity
+=========
+
+ .. automodule:: transport_analysis.viscosity
+    :members:
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -11,6 +11,8 @@ set of tools for computing and analyzing transport properties.
 It harnesses the power of `MDAnalysis <https://www.mdanalysis.org/>`_'s
 core `AtomGroup` and `Universe` data structures to quickly access
 trajectory data and execute complex transport property calculations.
+Unless otherwise stated, all calculations and results are in `MDAnalysis
+standard units <https://userguide.mdanalysis.org/stable/units>`_.
 
 To begin, check out the Getting Started section of the documentation.
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -41,8 +41,8 @@ doc = [
 ]
 
 # [project.urls]
-# source = "https://github.com/MDAnalysis/transport_analysis"
-# documentation = "https://transport_analysis.readthedocs.io"
+# source = "https://github.com/MDAnalysis/transport-analysis"
+# documentation = "https://transport-analysis.readthedocs.io"
 
 [tool.pytest.ini_options]
 minversion = "6.0"

diff --git a/transport_analysis/velocityautocorr.py b/transport_analysis/velocityautocorr.py
@@ -1,6 +1,6 @@
 """
-VelocityAutocorr --- :mod:`transport_analysis.analysis.VelocityAutocorr`
-========================================================================
+Velocity Autocorrelation Function --- :mod:`transport_analysis.velocityautocorr`
+================================================================================
 
 This module offers a class to efficiently calculate a velocity
 autocorrelation function (VACF). Averaging over all atoms in the atom group
@@ -20,7 +20,11 @@
 :data:`~MDAnalysis.tests.datafiles.TRJ_NCBOX` from the MDAnalysis test suite.
 To get started, execute  ::
 
-   >>> import transport_analysis as ta
+   # imports
+   >>> import MDAnalysis as mda
+   >>> from transport_analysis.velocityautocorr import VelocityAutocorr
+
+   # test data for this example
    >>> from MDAnalysis.tests.datafiles import PRM_NCBOX, TRJ_NCBOX
 
 We will calculate the VACF of an atom group of all water atoms in
@@ -32,10 +36,11 @@
 We can run the calculation using any variable of choice such as
 ``wat_vacf`` and access our results using ``wat_vacf.results.timeseries``:
 
-   >>> wat_vacf = ta.VelocityAutocorr(ag).run()
+   >>> wat_vacf = VelocityAutocorr(ag).run()
    >>> wat_vacf.results.timeseries
-   [275.62075467 -18.42008255 -23.94383428  41.41415381  -2.3164344
-   -35.66393559 -22.66874897  -3.97575003   6.57888933  -5.29065096]
+   array([275.62075467, -18.42008255, -23.94383428,  41.41415381,
+        -2.3164344 , -35.66393559, -22.66874897,  -3.97575003,
+         6.57888933,  -5.29065096])
 
 Notice that this example data is insufficient to provide a well-defined VACF.
 When working with real data, ensure that the frames are captured frequently

diff --git a/transport_analysis/viscosity.py b/transport_analysis/viscosity.py
@@ -2,8 +2,12 @@
 Viscosity --- :mod:`transport_analysis.analysis.viscosity`
 ==========================================================
 
-This module offers a class for the lightweight computation of
-viscosity via the Einstein-Helfand method.
+This module offers a class for the lightweight computation of shear
+viscosity via the Einstein-Helfand method. It outputs the "viscosity
+function," the product of viscosity and time as a function of time, from
+which the slope is taken to calculate the shear viscosity. This is
+described in eq. 5 of E M Kirova and G E Norman 2015 J. Phys.: Conf.
+Ser. 653 012106.
 
 """
 from typing import TYPE_CHECKING
@@ -21,8 +25,8 @@
 class ViscosityHelfand(AnalysisBase):
     """
     Class to calculate viscosity using the Einstein-Helfand approach.
-    Note that the slope of the viscosity function must be taken to obtain the
-    viscosity.
+    Note that the slope of the viscosity function, the product of viscosity
+    and time as a function of time, must be taken to obtain the viscosity.
 
     Parameters
     ----------