From d6e73aeaf5f009a0be3e24f1ecc6c52c7fd3e206 Mon Sep 17 00:00:00 2001
From: Tommy Waltmann <tomwalt@umich.edu>
Date: Mon, 26 Sep 2022 17:55:01 -0400
Subject: [PATCH 01/17] start work on adding RDF normalization modes

---
 cpp/density/RDF.cc |  6 +++---
 cpp/density/RDF.h  | 12 ++++++++++--
 freud/_density.pxd |  7 ++++++-
 freud/density.pyx  | 13 +++++++++++--
 4 files changed, 30 insertions(+), 8 deletions(-)

diff --git a/cpp/density/RDF.cc b/cpp/density/RDF.cc
index 310e18822..cafc5eefe 100644
--- a/cpp/density/RDF.cc
+++ b/cpp/density/RDF.cc
@@ -11,8 +11,8 @@
 
 namespace freud { namespace density {
 
-RDF::RDF(unsigned int bins, float r_max, float r_min, bool normalize)
-    : BondHistogramCompute(), m_normalize(normalize)
+RDF::RDF(unsigned int bins, float r_max, float r_min, NormalizationMode norm_mode)
+    : BondHistogramCompute(), m_norm_mode(norm_mode)
 {
     if (bins == 0)
     {
@@ -59,7 +59,7 @@ void RDF::reduce()
 
     // Define prefactors with appropriate types to simplify and speed later code.
     float number_density = float(m_n_query_points) / m_box.getVolume();
-    if (m_normalize)
+    if (m_norm_mode == NormalizationMode::infer)
     {
         number_density *= static_cast<float>(m_n_query_points - 1) / static_cast<float>(m_n_query_points);
     }
diff --git a/cpp/density/RDF.h b/cpp/density/RDF.h
index 50af6cbb9..407996979 100644
--- a/cpp/density/RDF.h
+++ b/cpp/density/RDF.h
@@ -16,8 +16,16 @@ namespace freud { namespace density {
 class RDF : public locality::BondHistogramCompute
 {
 public:
+
+    enum NormalizationMode
+    {
+        infer,
+        finite_size
+    };
+
     //! Constructor
-    RDF(unsigned int bins, float r_max, float r_min = 0, bool normalize = false);
+    RDF(unsigned int bins, float r_max, float r_min = 0,
+            NormalizationMode normalization_mode = NormalizationMode::infer);
 
     //! Destructor
     ~RDF() override = default;
@@ -51,7 +59,7 @@ class RDF : public locality::BondHistogramCompute
     }
 
 private:
-    bool m_normalize;                //!< Whether to enforce that the RDF should tend to 1 (instead of
+    NormalizationMode m_norm_mode;   //!< Whether to enforce that the RDF should tend to 1 (instead of
                                      //!< num_query_points/num_points).
     util::ManagedArray<float> m_pcf; //!< The computed pair correlation function.
     util::ManagedArray<float>
diff --git a/freud/_density.pxd b/freud/_density.pxd
index d2654f5d6..991926992 100644
--- a/freud/_density.pxd
+++ b/freud/_density.pxd
@@ -49,7 +49,12 @@ cdef extern from "LocalDensity.h" namespace "freud::density":
 
 cdef extern from "RDF.h" namespace "freud::density":
     cdef cppclass RDF(BondHistogramCompute):
-        RDF(float, float, float, bool) except +
+
+        ctypedef enum NormalizationMode "NormalizationMode":
+            infer "NormalizationMode::infer"
+            finite_size "NormalizationMode::finite_size"
+
+        RDF(float, float, float, NormalizationMode) except +
         const freud._box.Box & getBox() const
         void accumulate(const freud._locality.NeighborQuery*,
                         const vec3[float]*,
diff --git a/freud/density.pyx b/freud/density.pyx
index d3c58cdb5..1fd0dd214 100644
--- a/freud/density.pyx
+++ b/freud/density.pyx
@@ -610,10 +610,11 @@ cdef class RDF(_SpatialHistogram1D):
     cdef freud._density.RDF * thisptr
 
     def __cinit__(self, unsigned int bins, float r_max, float r_min=0,
-                  normalize=False):
+                  normalization_mode='infer'):
+        norm_mode = self._validate_normalization_mode(normalization_mode)
         if type(self) == RDF:
             self.thisptr = self.histptr = new freud._density.RDF(
-                bins, r_max, r_min, normalize)
+                bins, r_max, r_min, norm_mode)
 
             # r_max is left as an attribute rather than a property for now
             # since that change needs to happen at the _SpatialHistogram level
@@ -624,6 +625,14 @@ cdef class RDF(_SpatialHistogram1D):
         if type(self) == RDF:
             del self.thisptr
 
+    def _validate_normalization_mode(self, mode):
+        if mode == 'infer':
+            return freud._density.RDF.NormalizationMode.infer
+        elif mode == 'finite_size':
+            return freud._density.RDF.NormalizationMode.finite_size
+        else:
+            raise ValueError(f"invalid input {mode} for normalization_mode")
+
     def compute(self, system, query_points=None, neighbors=None,
                 reset=True):
         r"""Calculates the RDF and adds to the current RDF histogram.

From c24cc8e962156d5b8869ad37ab949aabf07fa32a Mon Sep 17 00:00:00 2001
From: Tommy Waltmann <tomwalt@umich.edu>
Date: Tue, 27 Sep 2022 09:56:35 -0400
Subject: [PATCH 02/17] compilation works now

---
 freud/_density.pxd | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/freud/_density.pxd b/freud/_density.pxd
index 991926992..7afe1b4f4 100644
--- a/freud/_density.pxd
+++ b/freud/_density.pxd
@@ -51,8 +51,8 @@ cdef extern from "RDF.h" namespace "freud::density":
     cdef cppclass RDF(BondHistogramCompute):
 
         ctypedef enum NormalizationMode "NormalizationMode":
-            infer "NormalizationMode::infer"
-            finite_size "NormalizationMode::finite_size"
+            infer "freud::density::RDF::NormalizationMode::infer"
+            finite_size "freud::density::RDF::NormalizationMode::finite_size"
 
         RDF(float, float, float, NormalizationMode) except +
         const freud._box.Box & getBox() const

From ed695f7f78004ca9bc71b5607060650d6cc3fdfb Mon Sep 17 00:00:00 2001
From: Tommy Waltmann <tomwalt@umich.edu>
Date: Tue, 27 Sep 2022 10:12:21 -0400
Subject: [PATCH 03/17] add test for new normalization modes

---
 tests/test_density_RDF.py | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/tests/test_density_RDF.py b/tests/test_density_RDF.py
index f1f7bcfcc..a3b4738e7 100644
--- a/tests/test_density_RDF.py
+++ b/tests/test_density_RDF.py
@@ -71,6 +71,19 @@ def test_invalid_rdf(self):
             freud.density.RDF(r_max=1, bins=10, r_min=2)
         with pytest.raises(ValueError):
             freud.density.RDF(r_max=1, bins=10, r_min=-1)
+        with pytest.raises(ValueError):
+            freud.density.RDF(r_max=1, bins=10, r_min=-1, normalization_mode='blah')
+
+    @pytest.mark.parametrize("mode", ['infer', 'finite_size'])
+    def test_normalization_mode(self, mode):
+        """Make sure RDF can be computed with different normalization modes."""
+        r_max = 10.0
+        bins = 10
+        num_points = 100
+        box_size = r_max * 3.1
+        sys = freud.data.make_random_system(box_size, num_points, is2D=True)
+        rdf = freud.density.RDF(r_max=r_max, bins=bins, normalization_mode=mode)
+        rdf.compute(sys)
 
     @pytest.mark.parametrize("r_min", [0, 0.1, 3.0])
     def test_random_point(self, r_min):

From 7b5bebd39b54739a6117f9264277f55ee3ccfe41 Mon Sep 17 00:00:00 2001
From: Tommy Waltmann <tomwalt@umich.edu>
Date: Tue, 27 Sep 2022 10:33:07 -0400
Subject: [PATCH 04/17] update docstrings

---
 freud/density.pyx | 37 ++++++++++++++++++++-----------------
 1 file changed, 20 insertions(+), 17 deletions(-)

diff --git a/freud/density.pyx b/freud/density.pyx
index 1fd0dd214..1bbb9724c 100644
--- a/freud/density.pyx
+++ b/freud/density.pyx
@@ -576,10 +576,17 @@ cdef class RDF(_SpatialHistogram1D):
     behavior of :math:`\lim_{r \to \infty} g(r)=1` is recovered. However, for
     very small systems the long range behavior of the radial distribution will
     instead tend to :math:`\frac{N-1}{N}`. In small systems, where this
-    deviation is noticeable, the ``normalize`` flag may be used to rescale the
-    results and force the long range behavior to 1. Note that this option will
-    have little to no effect on larger systems (for example, for systems of 100
-    particles the RDF will differ by 1%).
+    deviation is noticeable, the ``normalization_mode`` argument may be used to
+    rescale the results and force the long range behavior to 1. Note that this
+    option will have little to no effect on larger systems (for example, for
+    systems of 100 particles the RDF will differ by 1%).
+
+    .. note::
+        The ``normalization_mode`` argument should not be used if
+        :code:`query_points` is provided as a different set of points, or if
+        unusual query arguments are provided to :meth:`~.compute`, specifically
+        if :code:`exclude_ii` is set to :code:`False`. This normalization is
+        not meaningful in such cases and will simply convolute the data.
 
     .. note::
         **2D:** :class:`freud.density.RDF` properly handles 2D boxes.
@@ -593,19 +600,14 @@ cdef class RDF(_SpatialHistogram1D):
         r_min (float, optional):
             Minimum interparticle distance to include in the calculation
             (Default value = :code:`0`).
-        normalize (bool, optional):
-            Scale the RDF values by
-            :math:`\frac{N_{query\_points}}{N_{query\_points}-1}`. This
-            argument primarily exists to deal with standard RDF calculations
-            where no special ``query_points`` or ``neighbors`` are provided,
-            but where the number of ``query_points`` is small enough that the
-            long-ranged limit of :math:`g(r)` deviates significantly from
-            :math:`1`. It should not be used if :code:`query_points` is
-            provided as a different set of points, or if unusual query
-            arguments are provided to :meth:`~.compute`, specifically if
-            :code:`exclude_ii` is set to :code:`False`. This normalization is
-            not meaningful in such cases and will simply convolute the data.
-
+        normalization_mode (str, optional):
+            There are two valid string inputs for this argument. The first
+            option, ``infer``, handles the normalization as shown mathematically
+            at the beginning of this class's docstring. The other option,
+            ``finite_size``, adds an extra rescaling factor of
+            :math:`\frac{N_{query\_points}}{N_{query\_ponts} - 1}` so the RDF
+            values will tend to 1 at large :math:`r` for small systems (Default
+            value = :code:`'infer'`).
     """
     cdef freud._density.RDF * thisptr
 
@@ -626,6 +628,7 @@ cdef class RDF(_SpatialHistogram1D):
             del self.thisptr
 
     def _validate_normalization_mode(self, mode):
+        """Ensure the normalization mode is one of the approved values."""
         if mode == 'infer':
             return freud._density.RDF.NormalizationMode.infer
         elif mode == 'finite_size':

From 4f185c548feea326a5a3b39f4fe4e35b549a4e5a Mon Sep 17 00:00:00 2001
From: Tommy Waltmann <tomwalt@umich.edu>
Date: Tue, 27 Sep 2022 10:34:00 -0400
Subject: [PATCH 05/17] linting

---
 cpp/density/RDF.h         | 3 +--
 tests/test_density_RDF.py | 4 ++--
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/cpp/density/RDF.h b/cpp/density/RDF.h
index 407996979..9c364bbb4 100644
--- a/cpp/density/RDF.h
+++ b/cpp/density/RDF.h
@@ -16,7 +16,6 @@ namespace freud { namespace density {
 class RDF : public locality::BondHistogramCompute
 {
 public:
-
     enum NormalizationMode
     {
         infer,
@@ -25,7 +24,7 @@ class RDF : public locality::BondHistogramCompute
 
     //! Constructor
     RDF(unsigned int bins, float r_max, float r_min = 0,
-            NormalizationMode normalization_mode = NormalizationMode::infer);
+        NormalizationMode normalization_mode = NormalizationMode::infer);
 
     //! Destructor
     ~RDF() override = default;
diff --git a/tests/test_density_RDF.py b/tests/test_density_RDF.py
index a3b4738e7..bdfdf5e4f 100644
--- a/tests/test_density_RDF.py
+++ b/tests/test_density_RDF.py
@@ -72,9 +72,9 @@ def test_invalid_rdf(self):
         with pytest.raises(ValueError):
             freud.density.RDF(r_max=1, bins=10, r_min=-1)
         with pytest.raises(ValueError):
-            freud.density.RDF(r_max=1, bins=10, r_min=-1, normalization_mode='blah')
+            freud.density.RDF(r_max=1, bins=10, r_min=-1, normalization_mode="blah")
 
-    @pytest.mark.parametrize("mode", ['infer', 'finite_size'])
+    @pytest.mark.parametrize("mode", ["infer", "finite_size"])
     def test_normalization_mode(self, mode):
         """Make sure RDF can be computed with different normalization modes."""
         r_max = 10.0

From 1282aef9f086921feb27f0489e255dff6238c113 Mon Sep 17 00:00:00 2001
From: Tommy Waltmann <tomwalt@umich.edu>
Date: Tue, 27 Sep 2022 10:45:18 -0400
Subject: [PATCH 06/17] credits and changelog

---
 ChangeLog.md                     | 5 +++++
 doc/source/reference/credits.rst | 1 +
 2 files changed, 6 insertions(+)

diff --git a/ChangeLog.md b/ChangeLog.md
index 2f041baaa..baf1e8a4f 100644
--- a/ChangeLog.md
+++ b/ChangeLog.md
@@ -4,6 +4,11 @@ The format is based on
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v3.0.0 -- YYYY-MM-DD
+
+### Changed
+* The `normalize` argument to `freud.density.RDF` is now `normalization_mode`.
+
 ## v2.11.0 -- 2022-08-09
 
 ### Added
diff --git a/doc/source/reference/credits.rst b/doc/source/reference/credits.rst
index 81fb08b14..e63ad2bcc 100644
--- a/doc/source/reference/credits.rst
+++ b/doc/source/reference/credits.rst
@@ -332,6 +332,7 @@ Tommy Waltmann
 * ``DiffractionPattern`` now raises an error when used with non-cubic boxes.
 * Implement ``StaticStructureFactorDebye`` for 2D systems.
 * Add support for compilation with the C++17 standard.
+* Update and test the ``normalization_mode`` argument to ``freud.density.RDF`` class.
 
 Maya Martirossyan
 

From 0731b4aea716edf492ad76fca77e91a3bc724463 Mon Sep 17 00:00:00 2001
From: Tommy Waltmann <tomwalt@umich.edu>
Date: Tue, 27 Sep 2022 10:56:12 -0400
Subject: [PATCH 07/17] cpp linting

---
 cpp/density/RDF.cc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cpp/density/RDF.cc b/cpp/density/RDF.cc
index cafc5eefe..a5f4e62f1 100644
--- a/cpp/density/RDF.cc
+++ b/cpp/density/RDF.cc
@@ -11,7 +11,7 @@
 
 namespace freud { namespace density {
 
-RDF::RDF(unsigned int bins, float r_max, float r_min, NormalizationMode norm_mode)
+RDF::RDF(unsigned int bins, float r_max, float r_min, NormalizationMode normalization_mode)
     : BondHistogramCompute(), m_norm_mode(norm_mode)
 {
     if (bins == 0)

From 482ec0b4df1414d6a6490351e94e17080c824d5f Mon Sep 17 00:00:00 2001
From: Tommy Waltmann <tomwalt@umich.edu>
Date: Tue, 27 Sep 2022 10:59:55 -0400
Subject: [PATCH 08/17] fix typo

---
 cpp/density/RDF.cc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cpp/density/RDF.cc b/cpp/density/RDF.cc
index a5f4e62f1..87e9632a5 100644
--- a/cpp/density/RDF.cc
+++ b/cpp/density/RDF.cc
@@ -12,7 +12,7 @@
 namespace freud { namespace density {
 
 RDF::RDF(unsigned int bins, float r_max, float r_min, NormalizationMode normalization_mode)
-    : BondHistogramCompute(), m_norm_mode(norm_mode)
+    : BondHistogramCompute(), m_norm_mode(normalization_mode)
 {
     if (bins == 0)
     {

From f903ccc36d1e2ad42565bb1d6c0fb46f00ac3538 Mon Sep 17 00:00:00 2001
From: Tommy Waltmann <tomwalt@umich.edu>
Date: Tue, 27 Sep 2022 11:24:41 -0400
Subject: [PATCH 09/17] correct behavior

---
 cpp/density/RDF.cc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cpp/density/RDF.cc b/cpp/density/RDF.cc
index 87e9632a5..ab09fc5dd 100644
--- a/cpp/density/RDF.cc
+++ b/cpp/density/RDF.cc
@@ -59,7 +59,7 @@ void RDF::reduce()
 
     // Define prefactors with appropriate types to simplify and speed later code.
     float number_density = float(m_n_query_points) / m_box.getVolume();
-    if (m_norm_mode == NormalizationMode::infer)
+    if (m_norm_mode == NormalizationMode::finite_size)
     {
         number_density *= static_cast<float>(m_n_query_points - 1) / static_cast<float>(m_n_query_points);
     }

From b1d1d0f274706d32fcf2693c3e7994982c01098d Mon Sep 17 00:00:00 2001
From: Tommy Waltmann <tomwalt@umich.edu>
Date: Thu, 29 Sep 2022 13:13:03 -0400
Subject: [PATCH 10/17] start migration guide

---
 doc/source/conf.py                      |  2 +-
 doc/source/gettingstarted/migration.rst | 25 +++++++++++++++++++++++++
 doc/source/index.rst                    |  1 +
 3 files changed, 27 insertions(+), 1 deletion(-)
 create mode 100644 doc/source/gettingstarted/migration.rst

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 8ad6d30bb..21bfeb368 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -78,7 +78,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
diff --git a/doc/source/gettingstarted/migration.rst b/doc/source/gettingstarted/migration.rst
new file mode 100644
index 000000000..cb43e7614
--- /dev/null
+++ b/doc/source/gettingstarted/migration.rst
@@ -0,0 +1,25 @@
+.. _migration:
+
+============================
+Migration to freud Version 3
+============================
+
+Version 3 of the freud library introduces a few breaking changes to make the API
+more intuitive and facilitate future development. This guide explains how to
+alter scripts which use freud v2 APIs so they can be used with freud version 3.
+
+Overview of API Changes
+=======================
+
+.. list-table::
+    :header-rows: 1
+
+    * - Goal
+      - v2 API
+      - v3 API
+    * - Use default RDF normalization.
+      - ``freud.density.RDF(..., normalize=False)``
+      - ``freud.density.RDF(..., normalization_mode='infer')``
+    * - Normalize small system RDFs to 1.
+      - ``freud.density.RDF(..., normalize=True)``
+      - ``freud.density.RDF(..., normalization_mode='finite_size')``
diff --git a/doc/source/index.rst b/doc/source/index.rst
index cc48d6c60..19e969623 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -10,6 +10,7 @@ Table of Contents
    gettingstarted/introduction
    gettingstarted/installation
    gettingstarted/quickstart
+   gettingstarted/migration
    gettingstarted/tutorial
    gettingstarted/examples
 

From 82d9c27ccb0a5d7430151359a9ecd710b303ef53 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Thu, 29 Sep 2022 17:14:03 +0000
Subject: [PATCH 11/17] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 doc/source/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 21bfeb368..9979531ff 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -78,7 +78,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = 'en'
+language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

From d5521e0b89d9ea0630cb2a150a035bf09ad88cee Mon Sep 17 00:00:00 2001
From: Tommy Waltmann <tomwalt@umich.edu>
Date: Tue, 4 Oct 2022 10:59:25 -0400
Subject: [PATCH 12/17] update docstring for RDF class

---
 freud/density.pyx | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/freud/density.pyx b/freud/density.pyx
index 1bbb9724c..5294b88c5 100644
--- a/freud/density.pyx
+++ b/freud/density.pyx
@@ -582,11 +582,15 @@ cdef class RDF(_SpatialHistogram1D):
     systems of 100 particles the RDF will differ by 1%).
 
     .. note::
-        The ``normalization_mode`` argument should not be used if
-        :code:`query_points` is provided as a different set of points, or if
-        unusual query arguments are provided to :meth:`~.compute`, specifically
-        if :code:`exclude_ii` is set to :code:`False`. This normalization is
-        not meaningful in such cases and will simply convolute the data.
+        For correct normalization behavior when using
+        ``normalization_mode='infer'``, let the set of points be either: 1) the
+        same as the set of query points or 2) completely disjoint from the set
+        of query points.
+
+    .. note::
+        For correct normalization behavior when using
+        ``normalization_mode='finite_size'``, do not allow particles to be their
+        own neighbor.
 
     .. note::
         **2D:** :class:`freud.density.RDF` properly handles 2D boxes.

From 5eb0a355218423d422f7c09b20e7540285857c8d Mon Sep 17 00:00:00 2001
From: Tommy Waltmann <tomwalt@umich.edu>
Date: Thu, 6 Oct 2022 13:06:44 -0400
Subject: [PATCH 13/17] change from inter to exact

---
 cpp/density/RDF.h         |  5 +++--
 freud/_density.pxd        |  2 +-
 freud/density.pyx         | 10 +++++-----
 tests/test_density_RDF.py |  2 +-
 4 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/cpp/density/RDF.h b/cpp/density/RDF.h
index 9c364bbb4..fbf0b27a1 100644
--- a/cpp/density/RDF.h
+++ b/cpp/density/RDF.h
@@ -16,15 +16,16 @@ namespace freud { namespace density {
 class RDF : public locality::BondHistogramCompute
 {
 public:
+    //! Enum for each normalization mode
     enum NormalizationMode
     {
-        infer,
+        exact,
         finite_size
     };
 
     //! Constructor
     RDF(unsigned int bins, float r_max, float r_min = 0,
-        NormalizationMode normalization_mode = NormalizationMode::infer);
+        NormalizationMode normalization_mode = NormalizationMode::exact);
 
     //! Destructor
     ~RDF() override = default;
diff --git a/freud/_density.pxd b/freud/_density.pxd
index 7afe1b4f4..3eb0b55a1 100644
--- a/freud/_density.pxd
+++ b/freud/_density.pxd
@@ -51,7 +51,7 @@ cdef extern from "RDF.h" namespace "freud::density":
     cdef cppclass RDF(BondHistogramCompute):
 
         ctypedef enum NormalizationMode "NormalizationMode":
-            infer "freud::density::RDF::NormalizationMode::infer"
+            exact "freud::density::RDF::NormalizationMode::exact"
             finite_size "freud::density::RDF::NormalizationMode::finite_size"
 
         RDF(float, float, float, NormalizationMode) except +
diff --git a/freud/density.pyx b/freud/density.pyx
index 5294b88c5..0edd0a6df 100644
--- a/freud/density.pyx
+++ b/freud/density.pyx
@@ -583,7 +583,7 @@ cdef class RDF(_SpatialHistogram1D):
 
     .. note::
         For correct normalization behavior when using
-        ``normalization_mode='infer'``, let the set of points be either: 1) the
+        ``normalization_mode='exact'``, let the set of points be either: 1) the
         same as the set of query points or 2) completely disjoint from the set
         of query points.
 
@@ -606,7 +606,7 @@ cdef class RDF(_SpatialHistogram1D):
             (Default value = :code:`0`).
         normalization_mode (str, optional):
             There are two valid string inputs for this argument. The first
-            option, ``infer``, handles the normalization as shown mathematically
+            option, ``exact``, handles the normalization as shown mathematically
             at the beginning of this class's docstring. The other option,
             ``finite_size``, adds an extra rescaling factor of
             :math:`\frac{N_{query\_points}}{N_{query\_ponts} - 1}` so the RDF
@@ -616,7 +616,7 @@ cdef class RDF(_SpatialHistogram1D):
     cdef freud._density.RDF * thisptr
 
     def __cinit__(self, unsigned int bins, float r_max, float r_min=0,
-                  normalization_mode='infer'):
+                  normalization_mode='exact'):
         norm_mode = self._validate_normalization_mode(normalization_mode)
         if type(self) == RDF:
             self.thisptr = self.histptr = new freud._density.RDF(
@@ -633,8 +633,8 @@ cdef class RDF(_SpatialHistogram1D):
 
     def _validate_normalization_mode(self, mode):
         """Ensure the normalization mode is one of the approved values."""
-        if mode == 'infer':
-            return freud._density.RDF.NormalizationMode.infer
+        if mode == 'exact':
+            return freud._density.RDF.NormalizationMode.exact
         elif mode == 'finite_size':
             return freud._density.RDF.NormalizationMode.finite_size
         else:
diff --git a/tests/test_density_RDF.py b/tests/test_density_RDF.py
index bdfdf5e4f..b00e4a587 100644
--- a/tests/test_density_RDF.py
+++ b/tests/test_density_RDF.py
@@ -74,7 +74,7 @@ def test_invalid_rdf(self):
         with pytest.raises(ValueError):
             freud.density.RDF(r_max=1, bins=10, r_min=-1, normalization_mode="blah")
 
-    @pytest.mark.parametrize("mode", ["infer", "finite_size"])
+    @pytest.mark.parametrize("mode", ["exact", "finite_size"])
     def test_normalization_mode(self, mode):
         """Make sure RDF can be computed with different normalization modes."""
         r_max = 10.0

From 0913914dff00e225647eac5db1fb7843b175f162 Mon Sep 17 00:00:00 2001
From: Tommy Waltmann <53307607+tommy-waltmann@users.noreply.github.com>
Date: Thu, 6 Oct 2022 14:41:13 -0400
Subject: [PATCH 14/17] Update freud/density.pyx

Co-authored-by: Domagoj Fijan <50439291+DomFijan@users.noreply.github.com>
---
 freud/density.pyx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/freud/density.pyx b/freud/density.pyx
index 0edd0a6df..a3a112436 100644
--- a/freud/density.pyx
+++ b/freud/density.pyx
@@ -611,7 +611,7 @@ cdef class RDF(_SpatialHistogram1D):
             ``finite_size``, adds an extra rescaling factor of
             :math:`\frac{N_{query\_points}}{N_{query\_ponts} - 1}` so the RDF
             values will tend to 1 at large :math:`r` for small systems (Default
-            value = :code:`'infer'`).
+            value = :code:`'exact'`).
     """
     cdef freud._density.RDF * thisptr
 

From d6243138a9a2f4c8c756bbf4843e2aba5225c04d Mon Sep 17 00:00:00 2001
From: Tommy Waltmann <53307607+tommy-waltmann@users.noreply.github.com>
Date: Thu, 6 Oct 2022 14:41:41 -0400
Subject: [PATCH 15/17] Apply suggestions from code review

Co-authored-by: Domagoj Fijan <50439291+DomFijan@users.noreply.github.com>
---
 freud/density.pyx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/freud/density.pyx b/freud/density.pyx
index a3a112436..a07f2fd94 100644
--- a/freud/density.pyx
+++ b/freud/density.pyx
@@ -585,12 +585,12 @@ cdef class RDF(_SpatialHistogram1D):
         For correct normalization behavior when using
         ``normalization_mode='exact'``, let the set of points be either: 1) the
         same as the set of query points or 2) completely disjoint from the set
-        of query points.
+        of query points (points shouldn't contain any particles in query points).
 
     .. note::
         For correct normalization behavior when using
         ``normalization_mode='finite_size'``, do not allow particles to be their
-        own neighbor.
+        own neighbor (:code:`exclude_ii` must be set to :code:`False`).
 
     .. note::
         **2D:** :class:`freud.density.RDF` properly handles 2D boxes.

From 86fefa6a26f8377526b6f6a78ad1f4b89b765352 Mon Sep 17 00:00:00 2001
From: Tommy Waltmann <53307607+tommy-waltmann@users.noreply.github.com>
Date: Mon, 10 Oct 2022 10:42:08 -0400
Subject: [PATCH 16/17] Apply suggestions from code review

Co-authored-by: Vyas Ramasubramani <vramasub@umich.edu>
---
 doc/source/gettingstarted/migration.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/source/gettingstarted/migration.rst b/doc/source/gettingstarted/migration.rst
index cb43e7614..2fadd59bc 100644
--- a/doc/source/gettingstarted/migration.rst
+++ b/doc/source/gettingstarted/migration.rst
@@ -6,7 +6,7 @@ Migration to freud Version 3
 
 Version 3 of the freud library introduces a few breaking changes to make the API
 more intuitive and facilitate future development. This guide explains how to
-alter scripts which use freud v2 APIs so they can be used with freud version 3.
+alter scripts which use freud v2 APIs so they can be used with freud v3.
 
 Overview of API Changes
 =======================
@@ -19,7 +19,7 @@ Overview of API Changes
       - v3 API
     * - Use default RDF normalization.
       - ``freud.density.RDF(..., normalize=False)``
-      - ``freud.density.RDF(..., normalization_mode='infer')``
+      - ``freud.density.RDF(..., normalization_mode='exact')``
     * - Normalize small system RDFs to 1.
       - ``freud.density.RDF(..., normalize=True)``
       - ``freud.density.RDF(..., normalization_mode='finite_size')``

From 0f9dec873ce87ccaf07de45815c68c25c4297606 Mon Sep 17 00:00:00 2001
From: Tommy Waltmann <tomwalt@umich.edu>
Date: Mon, 10 Oct 2022 11:17:25 -0400
Subject: [PATCH 17/17] update docs for RDF module

---
 freud/density.pyx | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/freud/density.pyx b/freud/density.pyx
index a07f2fd94..120fbf139 100644
--- a/freud/density.pyx
+++ b/freud/density.pyx
@@ -582,15 +582,15 @@ cdef class RDF(_SpatialHistogram1D):
     systems of 100 particles the RDF will differ by 1%).
 
     .. note::
-        For correct normalization behavior when using
-        ``normalization_mode='exact'``, let the set of points be either: 1) the
-        same as the set of query points or 2) completely disjoint from the set
-        of query points (points shouldn't contain any particles in query points).
+        For correct normalization behavior, let the set of points be either: 1)
+        the same as the set of query points or 2) completely disjoint from the
+        set of query points (points shouldn't contain any particles in query
+        points).
 
     .. note::
         For correct normalization behavior when using
-        ``normalization_mode='finite_size'``, do not allow particles to be their
-        own neighbor (:code:`exclude_ii` must be set to :code:`False`).
+        ``normalization_mode='finite_size'``, the ``points`` _must_ be the same
+        as the ``query_points`` and ``exclude_ii`` must be set to ``False``.
 
     .. note::
         **2D:** :class:`freud.density.RDF` properly handles 2D boxes.