Add tools for working with local grids

[jipolanco]

This PR mainly defines a localgrid(::Pencil, coords_global) function that takes the coordinates (xs, ys, ...) of the global grid, and returns an object that contains the coordinates of the subdomain associated to the current MPI process.

For example:

using MPI
using PencilArrays

MPI.Init()
comm = MPI.COMM_WORLD
perm = Permutation(2, 3, 1)  # optional permutations are transparently taken care of

Nx, Ny, Nz = (60, 110, 210)
pen = Pencil((Nx, Ny, Nz), comm; permute = perm)

# Global domain coordinates
xs = range(0, 1; length = Nx)
ys = range(0, 1; length = Ny)
zs = [n^2 for n = 1:dims[3]]

# Create local grid
grid = localgrid(pen, (xs, ys, zs))

# The components can be obtained as (grid.x, grid.y, ...) for broadcasting:
u = PencilArray{Float64}(undef, pen)
@. u = grid.x * grid.y + grid.z

# Alternatively (useful when working with higher dimensions):
@. u = grid[1] * grid[2] + grid[3]

# Indexing and iteration also work:
for I ∈ eachindex(grid)
    x, y, z = grid[I]
    u[I] = x * y + z
end

# This is probably faster:
for (n, xyz) ∈ enumerate(grid)
    x, y, z = xyz
    u[n] = x * y + z
end

Things to do:

• [x] add documentation,
• [x] add benchmarks,

For later:

• [ ] make grid[i, j, ...] return SVector instead of tuple?
• [ ] allow broadcasting using the whole grid, as in us ⋅ grid (here us may be a StructArray of PencilArrays...),
• [ ] make grid.x .+ grid.y return a PencilArray?

[codecov-commenter]

Codecov Report

Merging #45 (84eac15) into master (56e51b8) will increase coverage by 0.04%. The diff coverage is 96.80%.

@@            Coverage Diff             @@
##           master      #45      +/-   ##
==========================================
+ Coverage   96.61%   96.66%   +0.04%     
==========================================
  Files          18       21       +3     
  Lines        1065     1141      +76     
==========================================
+ Hits         1029     1103      +74     
- Misses         36       38       +2     

Impacted Files	Coverage Δ
src/cartesian_indices.jl	100.00% <ø> (+4.44%)	:arrow_up:
src/arrays.jl	93.22% <80.00%> (-0.70%)	:arrow_down:
src/PermutedIndices/PermutedIndices.jl	94.28% <94.28%> (ø)
src/LocalGrids/rectilinear.jl	98.68% <98.68%> (ø)
src/LocalGrids/LocalGrids.jl	100.00% <100.00%> (ø)
src/Pencils/Pencils.jl	100.00% <100.00%> (ø)
src/PencilIO/hdf5.jl	92.50% <0.00%> (-0.13%)	:arrow_down:
src/PencilIO/mpi_io.jl	96.12% <0.00%> (-0.08%)	:arrow_down:
src/Pencils/MPITopologies.jl	97.40% <0.00%> (-0.07%)	:arrow_down:
... and 3 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 56e51b8...84eac15. Read the comment docs.