Add docs for initialize! and update! (#22)

* Add docs for `initialize!` and `update!`

* Implement suggestions

Author: efaulhaber

src/neighborhood_search.jl

@@ -1,3 +1,46 @@
+abstract type AbstractNeighborhoodSearch end
+
+"""
+    initialize!(search::AbstractNeighborhoodSearch, x, y)
+
+Initialize a neighborhood search with the two coordinate arrays `x` and `y`.
+
+In general, the purpose of a neighborhood search is to find for one point in `x`
+all points in `y` whose distances to that point are smaller than the search radius.
+`x` and `y` are expected to be matrices, where the `i`-th column contains the coordinates
+of point `i`. Note that `x` and `y` can be identical.
+
+See also [`update!`](@ref).
+"""
+@inline initialize!(search::AbstractNeighborhoodSearch, x, y) = search
+
+"""
+    update!(search::AbstractNeighborhoodSearch, x, y; particles_moving = (true, true))
+
+Update an already initialized neighborhood search with the two coordinate arrays `x` and `y`.
+
+Like [`initialize!`](@ref), but reusing the existing data structures of the already
+initialized neighborhood search.
+When the points only moved a small distance since the last `update!` or `initialize!`,
+this is significantly faster than `initialize!`.
+
+Not all implementations support incremental updates.
+If incremental updates are not possible for an implementation, `update!` will fall back
+to a regular `initialize!`.
+
+Some neighborhood searches might not need to update when only `x` changed since the last
+`update!` or `initialize!` and `y` did not change. Pass `particles_moving = (true, false)`
+in this case to avoid unnecessary updates.
+The first flag in `particles_moving` indicates if points in `x` are moving.
+The second flag indicates if points in `y` are moving.
+
+See also [`initialize!`](@ref).
+"""
+@inline function update!(search::AbstractNeighborhoodSearch, x, y;
+                         particles_moving = (true, true))
+    return search
+end
+
 struct PeriodicBox{NDIMS, ELTYPE}
     min_corner :: SVector{NDIMS, ELTYPE}
     max_corner :: SVector{NDIMS, ELTYPE}

src/nhs_grid.jl

@@ -48,7 +48,7 @@ since not sorting makes our implementation a lot faster (although less paralleli
   In: Computer Graphics Forum 30.1 (2011), pages 99–112.
   [doi: 10.1111/J.1467-8659.2010.01832.X](https://doi.org/10.1111/J.1467-8659.2010.01832.X)
 """
-struct GridNeighborhoodSearch{NDIMS, ELTYPE, PB}
+struct GridNeighborhoodSearch{NDIMS, ELTYPE, PB} <: AbstractNeighborhoodSearch
     hashtable           :: Dict{NTuple{NDIMS, Int}, Vector{Int}}
     search_radius       :: ELTYPE
     empty_vector        :: Vector{Int} # Just an empty vector (used in `eachneighbor`)

src/nhs_trivial.jl

@@ -19,7 +19,7 @@ internal function `eachneighbor`.
                                 coordinates of the domain corner in positive coordinate
                                 directions.
 """
-struct TrivialNeighborhoodSearch{NDIMS, ELTYPE, EP, PB}
+struct TrivialNeighborhoodSearch{NDIMS, ELTYPE, EP, PB} <: AbstractNeighborhoodSearch
     search_radius :: ELTYPE
     eachparticle  :: EP
     periodic_box  :: PB