Added documentation for the find_rcv_ids machinery

Author: JordiManyer

.gitignore

@@ -9,6 +9,7 @@ LocalPreferences.toml
 docs/build/
 tmp/
 docs/src/examples.md
+docs/src/jacobi_tutorial.md
 
 HPCG/src/results/
 

docs/src/reference/backends.md

@@ -5,6 +5,7 @@
 ```@autodocs
 Modules = [PartitionedArrays]
 Pages = ["mpi_array.jl"]
+Filter = t -> string(t) != "find_rcv_ids_ibarrier"
 ```
 
 ## Debug

docs/src/reference/primitives.md

@@ -8,6 +8,7 @@ gather
 gather!
 allocate_gather
 ```
+
 ## Scatter
 
 ```@docs
@@ -45,7 +46,8 @@ ExchangeGraph(snd)
 exchange
 exchange!
 allocate_exchange
+default_find_rcv_ids
+set_default_find_rcv_ids
+find_rcv_ids_gather_scatter
+find_rcv_ids_ibarrier
 ```
-
-
-

src/PartitionedArrays.jl

@@ -58,6 +58,7 @@ export ExchangeGraph
 export exchange
 export exchange!
 export allocate_exchange
+export default_find_rcv_ids
 export find_rcv_ids_gather_scatter
 export setup_non_blocking_reduction
 export non_blocking_reduction

src/mpi_array.jl

@@ -671,8 +671,12 @@ function default_find_rcv_ids(::MPIArray)
 end
 
 """
- Implements Alg. 2 in https://dl.acm.org/doi/10.1145/1837853.1693476
- The algorithm's complexity is claimed to be O(log(p))
+    find_rcv_ids_ibarrier(snd_ids::MPIArray)
+
+Finds the `rcv` side of an `ExchangeGraph` out of the `snd` side information.
+
+This strategy implements Alg. 2 in https://dl.acm.org/doi/10.1145/1837853.1693476.
+The algorithm's complexity is claimed to be O(log(p)).
 """
 function find_rcv_ids_ibarrier(snd_ids::MPIArray{<:AbstractVector{T}}) where T
     comm = snd_ids.comm

src/preferences.jl

@@ -5,9 +5,9 @@
 Sets the default algorithm to discover communication neighbors. The available algorithms are:
 
 - `gather_scatter`: Gathers neighbors in a single processor, builds the communications graph 
-  and then scatters the information back to all processors.
+  and then scatters the information back to all processors. See [`find_rcv_ids_gather_scatter`](@ref).
 
-- `ibarrier`: Implements Alg. 2 in https://dl.acm.org/doi/10.1145/1837853.1693476
+- `ibarrier`: Implements Alg. 2 in https://dl.acm.org/doi/10.1145/1837853.1693476. See [`find_rcv_ids_ibarrier`](@ref).
 
 Feature only available in Julia 1.6 and later due to restrictions from `Preferences.jl`.
 """

src/primitives.jl

@@ -762,6 +762,13 @@ function Base.show(io::IO,k::MIME"text/plain",data::ExchangeGraph)
     println(io,typeof(data)," with $(length(data.snd)) nodes")
 end
 
+"""
+    default_find_rcv_ids(::AbstractArray)
+
+Provides a default function to find the `rcv` side of an
+`ExchangeGraph` out of the `snd` side information.
+Its behaviour can be statically changed using [`set_default_find_rcv_ids`](@ref).
+"""
 function default_find_rcv_ids(::AbstractArray)
     find_rcv_ids_gather_scatter
 end 
@@ -779,10 +786,11 @@ are set to `snd`. Otherwise, either the optional `neighbors` or
 `neighbors` is also an `ExchangeGraph`
 that contains a super set of the outgoing and incoming neighbors
 associated with `snd`. It is used to find the incoming neighbors `rcv`
-efficiently. If `neighbors` are not provided, then `find_rcv_ids` 
+efficiently. If `neighbors` are not provided, then `find_rcv_ids`
 is used (either the user-provided or a default one).
 `find_rcv_ids` is a function that implements an algorithm to find the 
-rcv side of the exchange graph out of the snd side information.
+rcv side of the exchange graph out of the snd side information. It 
+defaults to [`default_find_rcv_ids`](@ref).
 """
 function ExchangeGraph(snd;
                        rcv=nothing,
@@ -836,8 +844,14 @@ function ExchangeGraph_impl_with_find_rcv_ids(snd_ids::AbstractArray,find_rcv_id
     ExchangeGraph(snd_ids,rcv_ids)
 end
 
-# This strategy gathers the communication graph into one process
-# and then scatters back the receivers
+"""
+    find_rcv_ids_gather_scatter(snd_ids::AbstractArray)
+
+Finds the `rcv` side of an `ExchangeGraph` out of the `snd` side information.
+
+This strategy gathers the communication graph into one process
+and then scatters back the receivers.
+"""
 function find_rcv_ids_gather_scatter(snd_ids::AbstractArray)
     snd_ids_main = gather(snd_ids)
     rcv_ids_main = map(snd_ids_main) do snd_ids_main