stencilDist Doco

I found the first two paragraphs a little bit sparse. I offer the following which is probably a bit the other way, i.e. verbose. I am sure somebody more insightful and more experienced with stenclDist than I could make the words a little tighter. A suggestion for the first 2 paragraphs:

The stencilDist distribution is an enhanced functionality variant of the blockDist distribution. Both refer to an array partitioned into blocks, but stencilDist will internally attempt to improve performance for stencil computations by reducing the amount of certain types of inter-block communication necessary during array accesses. A stencilDist array would most commonly be used in computations based on a numerical stencil formula that might arise when solving banded linear equations by the Gauss-Seidel or Jacobi method, doing image processing, dealing with cellular automata, or solving some partial differential equations by some finite difference method. From a user's perspective, a stencilDist behaves much like blockDist in terms of reads, writes, and iteration.

Like blockDist, each of the blocks in a stencilDist array are owned by a (potentially) different locale. But where communication needs to occur between a given block and its set of immediately neighboring or adjacent blocks, the more feature-full stencilDist most likely makes it the better choice. Why? Because, for any given block, a stencilDist transparently creates a read-only cache of selected array elements from its adjacent blocks, specifically those array elements from the (thin) band of array elements just outside the edge of the given block. This documentation may refer to this cached band of array elements as either 'ghost cells' or more strictly, as 'fluff'. If the reader has a problem visualizing the concept, think of the circular lunar halo that is often seen around Earth's moon. This approach can .. (retain the rest of this paragraph) ..

Way down in the 2.3 documentation, change in two places

    ghost cache -> ghost cell cache

for consistency with other uses of the term.

... Damian

Thanks for taking the time to prepare this suggestion! I've opened a PR largely based on the text you provided, with some attempts at tightening things up a bit: Improve stencilDist documentation by benharsh · Pull Request #26472 · chapel-lang/chapel · GitHub

I'll be asking someone on the Chapel team to review just to get a second pair of eyes on things, but feel free to join in!

I did not know whether my words were sufficient improvement to warrant a change, wherher they were too loing, or whether they needed more discussion before creating the PR itself.And I have no idea about how to create a PR anyway. So thanks.

Only once I associated the words halo or thin band, or more strictly, normally thin, did the stencilDist really make sense. My 2c,

Good point, I've updated the PR to include the term "halo" and call out the difference in the documentation more clearly.

1 Like