fix InterRDF_s(..., density) normalization

- fix MDAnalysis#2811
  (see also MDAnalysis/pmda#120)
- add test to compare InterRDF and InterRDF_s
- add description for density option (was not documented since 0.19.0)
- updated docs for rdf
  - updated docs with equationi
  - attributes for InterRDF and InterRDF_s
  - reference equations
  - minor grammar/style fixes
  - remove ill-advised usage of InterRDF_s from docs
- update CHANGELOG

package/CHANGELOG

@@ -14,7 +14,7 @@ The rules for this file:
 
 ------------------------------------------------------------------------------
 ??/??/?? tylerjereddy, richardjgowers, IAlibay, hmacdope, orbeckst, cbouy,
-         lilyminium, daveminh, jbarnoud, yuxuanzhuang
+         lilyminium, daveminh, jbarnoud, yuxuanzhuang, VOD555
 
   * 2.0.0
 
@@ -26,11 +26,12 @@ Fixes
   * TOPParser no longer guesses elements when missing atomic number records
     (Issues #2449, #2651)
   * Testsuite does not any more matplotlib.use('agg') (#2191)
-  * In ChainReader, read_frame does not trigger change of iterating position. 
+  * In ChainReader, read_frame does not trigger change of iterating position.
     (Issue #2723, PR #2815)
   * TRZReader now checks `n_atoms` on reading. (Issue #2817, PR #2820)
   * TRZWriter now writes `n_atoms` to the file. (Issue #2817, PR #2820)
-
+  * fixed InterRDF_s function now gives correct results if density=True.
+    (Issue #2811, PR #2812)
 
 Enhancements
   * Added the RDKitParser which creates a `core.topology.Topology` object from
@@ -46,7 +47,7 @@ Enhancements
 Changes
   * deprecated NumPy type aliases have been replaced with their actual types
     (see upstream NumPy PR 14882), and our pytest configuration will raise an
-    error for any violation when testing with development NumPy builds 
+    error for any violation when testing with development NumPy builds
     (`1.20.0`)
   * Changes development status from Beta to Mature (Issue #2773)
   * Removes deprecated MDAnalysis.analysis.hole, please use

package/MDAnalysis/analysis/rdf.py

@@ -60,11 +60,9 @@
 the first minimum in :math:`g(r)`.
 
 In :class:`InterRDF_s`, we provide an option `density`. When `density` is
-``False``, it will return the RDF :math:`g_{ab}(r)`; when `density` is
-``True``, it will return the density of particle :math:`b` in a shell at
-distance :math:`r` around a :math:`a` particle, which is
-
-.. _equation-nab:
+`True`, it will return the RDF :math:`g_{ab}(r)`; when `density` is False`,
+it will return the density of particle :math:`b` in a shell at distance
+:math:`r` around a :math:`a` particle, which is
 
 .. math::
    n_{ab}(r) = \rho g_{ab}(r)
@@ -319,16 +317,9 @@ class InterRDF_s(AnalysisBase):
     range : tuple or list (optional)
           The size of the RDF [0.0, 15.0]
     density : bool (optional)
-          ``False``: calculate :math:`g_{ab}(r)`; ``True``: calculate
-          the true :ref:`single particle density<equation-nab>`
-          :math:`n_{ab}(r)`. The default is ``False``.
-
-          .. versionadded:: 1.0.1
-
-             This keyword was available since 0.19.0 but was not
-             documented. Furthermore, it had the opposite
-             meaning. Since 1.0.1 it is officially supported as
-             documented.
+          Calculate :math:`g_{ab}(r)` if set to ``True``; or calculate
+          :math:`n_{ab}(r)` if set to ``false``; the default is
+          ``True``.
 
 
     Example

testsuite/MDAnalysisTests/analysis/test_rdf_s.py

@@ -100,17 +100,15 @@ def test_cdf(rdf):
 
 
 @pytest.mark.parametrize("density, value", [
-    (None, 26551.55088100731),    # default, like False (no kwarg, see below)
-    (False, 26551.55088100731),
-    (True, 0.021915460340071267)])
+    (True, 26551.55088100731),
+    (False, 0.021915460340071267)])
 def test_density(u, sels, density, value):
     kwargs = {'density': density} if density is not None else {}
     rdf = InterRDF_s(u, sels, **kwargs).run()
     assert_almost_equal(max(rdf.rdf[0][0][0]), value)
-    if not density:
+    if density:
         s1 = u.select_atoms('name ZND and resid 289')
         s2 = u.select_atoms(
                 'name OD1 and resid 51 and sphzone 5.0 (resid 289)')
         rdf_ref = InterRDF(s1, s2).run()
         assert_almost_equal(rdf_ref.rdf, rdf.rdf[0][0][0])
-