Standardize use of num_neighbors universally (resolves #196)

cpp/locality/AABBQuery.h

@@ -59,7 +59,7 @@ class AABBQuery : public NeighborQuery
         }
         else if (args.mode == QueryArgs::nearest)
         {
-            return query(query_points, n_query_points, args.num_neigh, args.r_max, args.scale, args.exclude_ii);
+            return query(query_points, n_query_points, args.num_neighbors, args.r_max, args.scale, args.exclude_ii);
         }
         else
         {
@@ -115,8 +115,8 @@ class AABBQuery : public NeighborQuery
         }
         else if (args.mode == QueryArgs::nearest)
         {
-            if (args.num_neigh == QueryArgs::DEFAULT_NUM_NEIGH)
-                throw std::runtime_error("You must set num_neigh in the query arguments when performing number of neighbor queries.");
+            if (args.num_neighbors == QueryArgs::DEFAULT_NUM_NEIGHBORS)
+                throw std::runtime_error("You must set num_neighbors in the query arguments when performing number of neighbor queries.");
             if (args.scale == QueryArgs::DEFAULT_SCALE)
             {
                 args.scale = float(1.1);

cpp/locality/NeighborComputeFunctional.h

@@ -116,7 +116,7 @@ class NeighborQueryNeighborIterator : public NeighborIterator
         // the number of neighbors to look for.
         if(qargs.exclude_ii && (qargs.mode == QueryArgs::QueryType::nearest))
         {
-            ++m_qargs.num_neigh;
+            ++m_qargs.num_neighbors;
         }
 
         // check if nq is a pointer to a RawPoints object
@@ -309,7 +309,7 @@ void loopOverNeighborQuery(const NeighborQuery* neighbor_query, const vec3<float
     // the number of neighbors to look for.
     if(qargs.exclude_ii && (qargs.mode == QueryArgs::QueryType::nearest))
     {
-        ++qargs.num_neigh;
+        ++qargs.num_neighbors;
     }
     // if nlist does not exist, check if neighbor_query is an actual NeighborQuery
     std::shared_ptr<NeighborQueryIterator> iter;

cpp/locality/NeighborQuery.cc

@@ -8,7 +8,7 @@ namespace freud { namespace locality {
 const NeighborBond NeighborQueryIterator::ITERATOR_TERMINATOR(-1, -1, 0);
 
 const QueryArgs::QueryType QueryArgs::DEFAULT_MODE(QueryArgs::none);
-const unsigned int QueryArgs::DEFAULT_NUM_NEIGH(0xffffffff);
+const unsigned int QueryArgs::DEFAULT_NUM_NEIGHBORS(0xffffffff);
 const float QueryArgs::DEFAULT_R_MAX(-1.0);
 const float QueryArgs::DEFAULT_SCALE(-1.0);
 const bool QueryArgs::DEFAULT_EXCLUDE_II(false);

cpp/locality/NeighborQuery.h

@@ -31,7 +31,7 @@ struct QueryArgs
     //! Default constructor.
     /*! We set default values for all parameters here.
      */
-    QueryArgs() : mode(DEFAULT_MODE), num_neigh(DEFAULT_NUM_NEIGH), r_max(DEFAULT_R_MAX),
+    QueryArgs() : mode(DEFAULT_MODE), num_neighbors(DEFAULT_NUM_NEIGHBORS), r_max(DEFAULT_R_MAX),
                   scale(DEFAULT_SCALE), exclude_ii(DEFAULT_EXCLUDE_II) {}
 
     //! Enumeration for types of queries.
@@ -43,14 +43,14 @@ struct QueryArgs
     };
 
     QueryType mode; //! Whether to perform a ball or k-nearest neighbor query.
-    unsigned int num_neigh;         //! The number of nearest neighbors to find.
+    unsigned int num_neighbors;         //! The number of nearest neighbors to find.
     float r_max;     //! The cutoff distance within which to find neighbors
     float scale; //! The scale factor to use when performing repeated ball queries to find a specified number
                  //! of nearest neighbors.
     bool exclude_ii; //! If true, exclude self-neighbors.
 
     static const QueryType DEFAULT_MODE;                //!< Default mode.
-    static const unsigned int DEFAULT_NUM_NEIGH;        //!< Default number of neighbors.
+    static const unsigned int DEFAULT_NUM_NEIGHBORS;        //!< Default number of neighbors.
     static const float DEFAULT_R_MAX;                   //!< Default query distance.
     static const float DEFAULT_SCALE;                   //!< Default scaling parameter for AABB nearest neighbor queries.
     static const bool DEFAULT_EXCLUDE_II;               //!< Default for whether or not to include self-neighbors.
@@ -102,7 +102,7 @@ class NeighborQuery
         }
         else if (args.mode == QueryArgs::nearest)
         {
-            return this->query(query_points, n_query_points, args.num_neigh, args.exclude_ii);
+            return this->query(query_points, n_query_points, args.num_neighbors, args.exclude_ii);
         }
         else
         {
@@ -167,8 +167,8 @@ class NeighborQuery
         }
         else if (args.mode == QueryArgs::nearest)
         {
-            if (args.num_neigh == QueryArgs::DEFAULT_NUM_NEIGH)
-                throw std::runtime_error("You must set num_neigh in the query arguments when performing number of neighbor queries.");
+            if (args.num_neighbors == QueryArgs::DEFAULT_NUM_NEIGHBORS)
+                throw std::runtime_error("You must set num_neighbors in the query arguments when performing number of neighbor queries.");
         }
     }
 
@@ -183,7 +183,7 @@ class NeighborQuery
         // Infer mode if possible.
         if (args.mode == QueryArgs::none)
         {
-            if (args.num_neigh != QueryArgs::DEFAULT_NUM_NEIGH)
+            if (args.num_neighbors != QueryArgs::DEFAULT_NUM_NEIGHBORS)
             {
                 args.mode = QueryArgs::nearest;
             }

freud/_locality.pxd

@@ -25,7 +25,7 @@ cdef extern from "NeighborQuery.h" namespace "freud::locality":
 
     cdef cppclass QueryArgs:
         QueryType mode
-        int num_neigh
+        int num_neighbors
         float r_max
         float scale
         bool exclude_ii

freud/density.pyx

@@ -865,8 +865,9 @@ cdef class RDF(Compute):
         cdef freud.locality.NlistptrWrapper nlistptr = nq_nlist[1]
 
         cdef freud.locality._QueryArgs qargs = \
-            freud.locality._QueryArgs.from_dict(query_args if query_args else
-                    self.get_default_query_args(query_points is None))
+            freud.locality._QueryArgs.from_dict(
+                query_args if query_args else
+                self.get_default_query_args(query_points is None))
         points = nq.points
 
         if query_points is None:

freud/environment.pyx

@@ -116,7 +116,7 @@ cdef class BondOrder(Compute):
 
     """  # noqa: E501
     cdef freud._environment.BondOrder * thisptr
-    cdef num_neigh
+    cdef num_neighbors
     cdef r_max
     cdef n_bins_t
     cdef n_bins_p
@@ -130,7 +130,7 @@ cdef class BondOrder(Compute):
         self.thisptr = new freud._environment.BondOrder(
             r_max, num_neighbors, n_bins_t, n_bins_p)
         self.r_max = r_max
-        self.num_neigh = num_neighbors
+        self.num_neighbors = num_neighbors
         self.n_bins_t = n_bins_t
         self.n_bins_p = n_bins_p
 
@@ -175,7 +175,7 @@ cdef class BondOrder(Compute):
         cdef freud.locality.NlistptrWrapper nlistptr = nq_nlist[1]
 
         cdef freud.locality._QueryArgs qargs = freud.locality._QueryArgs(
-            mode="nearest", num_neigh=self.num_neigh,
+            mode="nearest", num_neighbors=self.num_neighbors,
             r_max=self.r_max, exclude_ii=exclude_ii)
         points = nq.points
 
@@ -300,12 +300,11 @@ cdef class BondOrder(Compute):
 
     def __repr__(self):
         return ("freud.environment.{cls}(r_max={r_max}, "
-                "num_neighbors={num_neigh}, n_bins_t={n_bins_t}, "
-                "n_bins_p={n_bins_p})").format(cls=type(self).__name__,
-                                               r_max=self.r_max,
-                                               num_neigh=self.num_neigh,
-                                               n_bins_t=self.n_bins_t,
-                                               n_bins_p=self.n_bins_p)
+                "num_neighbors={num_neighbors}, n_bins_t={n_bins_t}, "
+                "n_bins_p={n_bins_p})").format(
+                    cls=type(self).__name__, r_max=self.r_max,
+                    num_neighbors=self.num_neighbors, n_bins_t=self.n_bins_t,
+                    n_bins_p=self.n_bins_p)
 
     def __str__(self):
         return repr(self)
@@ -340,18 +339,20 @@ cdef class LocalDescriptors(Compute):
             A reference to the last computed spherical harmonic array.
         num_particles (unsigned int):
             The number of points passed to the last call to :meth:`~.compute`.
-        num_neighbors (unsigned int):
-            The number of neighbors used by the last call to compute. Bounded
-            from above by the number of reference points multiplied by the
-            lower of the num_neighbors arguments passed to the last compute
-            call or the constructor.
+        num_sphs (unsigned int):
+            The last number of spherical harmonics computed. This is equal to
+            the number of bonds in the last computation, which is bounded from
+            above by the number of reference points multiplied by the lower of
+            the num_neighbors arguments passed to the last compute call or the
+            constructor (the reason it's a bound and not an equality is because
+            there may not be enough neighbors for every particle).
         l_max (unsigned int):
             The maximum spherical harmonic :math:`l` to calculate for.
         r_max (float):
             The cutoff radius.
     """  # noqa: E501
     cdef freud._environment.LocalDescriptors * thisptr
-    cdef num_neigh
+    cdef num_neighbors
     cdef r_max
     cdef lmax
     cdef negative_m
@@ -363,7 +364,7 @@ cdef class LocalDescriptors(Compute):
     def __cinit__(self, num_neighbors, lmax, r_max, negative_m=True):
         self.thisptr = new freud._environment.LocalDescriptors(
             lmax, negative_m)
-        self.num_neigh = num_neighbors
+        self.num_neighbors = num_neighbors
         self.r_max = r_max
         self.lmax = lmax
         self.negative_m = negative_m
@@ -438,10 +439,10 @@ cdef class LocalDescriptors(Compute):
 
         l_mode = self.known_modes[mode]
 
-        self.num_neigh = num_neighbors
+        self.num_neighbors = num_neighbors
 
         defaulted_nlist = freud.locality.make_default_nlist_nn(
-            b, points, query_points, self.num_neigh, nlist,
+            b, points, query_points, self.num_neighbors, nlist,
             exclude_ii, self.r_max)
         cdef freud.locality.NeighborList nlist_ = defaulted_nlist[0]
 
@@ -470,21 +471,20 @@ cdef class LocalDescriptors(Compute):
         return self.thisptr.getNPoints()
 
     @Compute._computed_property()
-    def num_neighbors(self):
+    def num_sphs(self):
         return self.thisptr.getNSphs()
 
     @property
     def l_max(self):
         return self.thisptr.getLMax()
 
     def __repr__(self):
-        return ("freud.environment.{cls}(num_neighbors={num_neigh}, "
+        return ("freud.environment.{cls}(num_neighbors={num_neighbors}, "
                 "lmax={lmax}, r_max={r_max}, "
-                "negative_m={negative_m})").format(cls=type(self).__name__,
-                                                   num_neigh=self.num_neigh,
-                                                   lmax=self.lmax,
-                                                   r_max=self.r_max,
-                                                   negative_m=self.negative_m)
+                "negative_m={negative_m})").format(
+                    cls=type(self).__name__, num_neighbors=self.num_neighbors,
+                    lmax=self.lmax, r_max=self.r_max,
+                    negative_m=self.negative_m)
 
     def __str__(self):
         return repr(self)
@@ -518,7 +518,7 @@ cdef class MatchEnv(Compute):
     """  # noqa: E501
     cdef freud._environment.MatchEnv * thisptr
     cdef r_max
-    cdef num_neigh
+    cdef num_neighbors
     cdef m_box
 
     def __cinit__(self, box, r_max, num_neighbors):
@@ -528,7 +528,7 @@ cdef class MatchEnv(Compute):
             dereference(b.thisptr), r_max, num_neighbors)
 
         self.r_max = r_max
-        self.num_neigh = num_neighbors
+        self.num_neighbors = num_neighbors
         self.m_box = box
 
     def __dealloc__(self):
@@ -592,12 +592,12 @@ cdef class MatchEnv(Compute):
             env_nlist_ = defaulted_env_nlist[0]
         else:
             defaulted_nlist = freud.locality.make_default_nlist_nn(
-                self.m_box, points, points, self.num_neigh, nlist,
+                self.m_box, points, points, self.num_neighbors, nlist,
                 True, self.r_max)
             nlist_ = defaulted_nlist[0]
 
             defaulted_env_nlist = freud.locality.make_default_nlist_nn(
-                self.m_box, points, points, self.num_neigh, env_nlist,
+                self.m_box, points, points, self.num_neighbors, env_nlist,
                 True, self.r_max)
             env_nlist_ = defaulted_env_nlist[0]
 
@@ -642,7 +642,7 @@ cdef class MatchEnv(Compute):
 
         defaulted_nlist = freud.locality.make_default_nlist_nn(
             self.m_box, points, points,
-            self.num_neigh, nlist, True, self.r_max)
+            self.num_neighbors, nlist, True, self.r_max)
         cdef freud.locality.NeighborList nlist_ = defaulted_nlist[0]
 
         self.thisptr.matchMotif(
@@ -686,7 +686,7 @@ cdef class MatchEnv(Compute):
 
         defaulted_nlist = freud.locality.make_default_nlist_nn(
             self.m_box, points, points,
-            self.num_neigh, nlist, True, self.r_max)
+            self.num_neighbors, nlist, True, self.r_max)
         cdef freud.locality.NeighborList nlist_ = defaulted_nlist[0]
 
         cdef vector[float] min_rmsd_vec = self.thisptr.minRMSDMotif(
@@ -835,7 +835,7 @@ cdef class MatchEnv(Compute):
         return ("freud.environment.{cls}(box={box}, "
                 "r_max={r}, num_neighbors={k})").format(
                     cls=type(self).__name__, box=self.m_box.__repr__(),
-                    r=self.r_max, k=self.num_neigh)
+                    r=self.r_max, k=self.num_neighbors)
 
     def __str__(self):
         return repr(self)
@@ -905,14 +905,14 @@ cdef class AngularSeparation(Compute):
             strict_cut=True
     """  # noqa: E501
     cdef freud._environment.AngularSeparation * thisptr
-    cdef unsigned int num_neigh
+    cdef unsigned int num_neighbors
     cdef float r_max
     cdef freud.locality.NeighborList nlist_
 
     def __cinit__(self, float r_max, unsigned int num_neighbors):
         self.thisptr = new freud._environment.AngularSeparation()
         self.r_max = r_max
-        self.num_neigh = num_neighbors
+        self.num_neighbors = num_neighbors
 
     def __dealloc__(self):
         del self.thisptr
@@ -975,7 +975,7 @@ cdef class AngularSeparation(Compute):
             equiv_orientations, shape=(None, 4))
 
         defaulted_nlist = freud.locality.make_default_nlist_nn(
-            b, points, query_points, self.num_neigh,
+            b, points, query_points, self.num_neighbors,
             nlist, exclude_ii, self.r_max)
         self.nlist_ = defaulted_nlist[0].copy()
 
@@ -1077,7 +1077,7 @@ cdef class AngularSeparation(Compute):
 
     def __repr__(self):
         return "freud.environment.{cls}(r_max={r}, num_neighbors={n})".format(
-            cls=type(self).__name__, r=self.r_max, n=self.num_neigh)
+            cls=type(self).__name__, r=self.r_max, n=self.num_neighbors)
 
     def __str__(self):
         return repr(self)
@@ -1115,13 +1115,13 @@ cdef class LocalBondProjection(Compute):
     """  # noqa: E501
     cdef freud._environment.LocalBondProjection * thisptr
     cdef float r_max
-    cdef unsigned int num_neigh
+    cdef unsigned int num_neighbors
     cdef freud.locality.NeighborList nlist_
 
     def __cinit__(self, r_max, num_neighbors):
         self.thisptr = new freud._environment.LocalBondProjection()
         self.r_max = r_max
-        self.num_neigh = int(num_neighbors)
+        self.num_neighbors = int(num_neighbors)
 
     def __dealloc__(self):
         del self.thisptr
@@ -1183,7 +1183,7 @@ cdef class LocalBondProjection(Compute):
         proj_vecs = freud.common.convert_array(proj_vecs, shape=(None, 3))
 
         defaulted_nlist = freud.locality.make_default_nlist_nn(
-            box, points, query_points, self.num_neigh, nlist,
+            box, points, query_points, self.num_neighbors, nlist,
             exclude_ii, self.r_max)
         self.nlist_ = defaulted_nlist[0].copy()
 
@@ -1248,9 +1248,9 @@ cdef class LocalBondProjection(Compute):
 
     def __repr__(self):
         return ("freud.environment.{cls}(r_max={r_max}, "
-                "num_neighbors={num_neigh})").format(cls=type(self).__name__,
-                                                     r_max=self.r_max,
-                                                     num_neigh=self.num_neigh)
+                "num_neighbors={num_neighbors})").format(
+                    cls=type(self).__name__, r_max=self.r_max,
+                    num_neighbors=self.num_neighbors)
 
     def __str__(self):
         return repr(self)