4,577
edits
m (Text replacement - "</source>" to "</syntaxhighlight>") |
m (Text replacement - "<source" to "<syntaxhighlight") |
||
Line 1: | Line 1: | ||
{{Built-in|Stencil|⌺}} is a primitive [[dyadic operator]] that applies its left [[operand]] to (possibly overlapping) rectangular views of the right argument [[array]]. The [[shape]] and movement of the rectangular views are dictated by the right operand. It was introduced to [[Dyalog APL]] in version 16.0 and is also known as tessellation, moving window, [[wikipedia:stencil code|stencil code]] or cut. The operator can be used for computations involving the immediate neighbours of items in an array and has applications in image processing (particularly [[wikipedia:convolution (computer science)|convolution]]), artificial [[neural networks]] and, most famously, [[wikipedia:cellular automaton|cellular automata]]. The operator derives from a subset (specifically, case 3) of the functionality of [[J]]'s [[Cut]] operator (< | {{Built-in|Stencil|⌺}} is a primitive [[dyadic operator]] that applies its left [[operand]] to (possibly overlapping) rectangular views of the right argument [[array]]. The [[shape]] and movement of the rectangular views are dictated by the right operand. It was introduced to [[Dyalog APL]] in version 16.0 and is also known as tessellation, moving window, [[wikipedia:stencil code|stencil code]] or cut. The operator can be used for computations involving the immediate neighbours of items in an array and has applications in image processing (particularly [[wikipedia:convolution (computer science)|convolution]]), artificial [[neural networks]] and, most famously, [[wikipedia:cellular automaton|cellular automata]]. The operator derives from a subset (specifically, case 3) of the functionality of [[J]]'s [[Cut]] operator (<syntaxhighlight lang=j inline>;.3</syntaxhighlight>),<ref>[[Eugene McDonnell]]: [https://www.jsoftware.com/papers/eem/life1.htm Life: Nasty, Brutish, and Short]. [[APL88]]. </ref> which in turn originates in the 3-cut mentioned in [[A Dictionary of APL]]<ref>[[Ken Iverson]]: [https://www.jsoftware.com/papers/APLDictionary.htm A Dictionary of APL]. [[APL Quote Quad]], Volume 18, Number 1, 1987-09.</ref> | ||
== Description == | == Description == | ||
For a call < | For a call <syntaxhighlight lang=apl inline>f⌺s</syntaxhighlight> the right operand <syntaxhighlight lang=apl inline>s</syntaxhighlight> can in general be a two-row [[matrix]] of strictly positive integers, where the first row describes the dimensions of the rectangles that will be passed to <syntaxhighlight lang=apl inline>f</syntaxhighlight> and the second row describes the movement along the different [[axis|axes]]. When using stencil <syntaxhighlight lang=apl inline>(f⌺s)Y</syntaxhighlight> the right operand <syntaxhighlight lang=apl inline>s</syntaxhighlight> in general has <syntaxhighlight lang=apl inline>≢⍴Y</syntaxhighlight> columns. If it has fewer, the rectangles are cut out of the [[major cell]]s of the <syntaxhighlight lang=apl inline>(≢⍴Y) - ≢1⌷s</syntaxhighlight> axis of <syntaxhighlight lang=apl inline>Y</syntaxhighlight>. If <syntaxhighlight lang=apl inline>s</syntaxhighlight> is a vector or scalar it describes only the size of the rectangles and the movement defaults to 1. Rectangles are centred on [[element]]s of <syntaxhighlight lang=apl inline>Y</syntaxhighlight> whose [[index|indices]] differ by the movements in <syntaxhighlight lang=apl inline>s</syntaxhighlight> (defaulting to 1), starting with the first element in [[ravel order]]. For a matrix, this is the top left. For even window sizes, the centring is instead on the space between elements or [[cell]]s. Along the edges of the [[argument]] array, the windows are thus subject to be padded with [[fill element]]s. | ||
The number of fill elements in along each axis is given as a vector left argument on each call of < | The number of fill elements in along each axis is given as a vector left argument on each call of <syntaxhighlight lang=apl inline>f</syntaxhighlight> for the respective [[subarray]]. This is designed such that [[Drop]] (<syntaxhighlight lang=apl inline>↓</syntaxhighlight>) can take the left and right arguments to remove padding: | ||
< | <syntaxhighlight lang=apl> | ||
({⊂⍵}⌺3 3)3 4⍴⍳12 | ({⊂⍵}⌺3 3)3 4⍴⍳12 | ||
┌──────┬───────┬────────┬───────┐ | ┌──────┬───────┬────────┬───────┐ | ||
Line 46: | Line 46: | ||
With a default movement in every direction of 1, the rectangles are centred on neighbouring elements of the array. Here, we simply enclose each neighbourhood: | With a default movement in every direction of 1, the rectangles are centred on neighbouring elements of the array. Here, we simply enclose each neighbourhood: | ||
< | <syntaxhighlight lang=apl> | ||
{⊂⍵}⌺3 3⊢3 3⍴⍳9 | {⊂⍵}⌺3 3⊢3 3⍴⍳9 | ||
┌─────┬─────┬─────┐ | ┌─────┬─────┬─────┐ | ||
Line 63: | Line 63: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
In the following example, each neighbourhood is immediately [[ravel]]led and [[sum]]med: | In the following example, each neighbourhood is immediately [[ravel]]led and [[sum]]med: | ||
< | <syntaxhighlight lang=apl> | ||
{+/,⍵}⌺3 3⊢3 3⍴⍳9 | {+/,⍵}⌺3 3⊢3 3⍴⍳9 | ||
12 21 16 27 45 33 24 39 28 | 12 21 16 27 45 33 24 39 28 | ||
</syntaxhighlight> | </syntaxhighlight> | ||
If the number of columns in the right operand to stencil does not match the rank of the right argument, the windowing is applied on the major cells: | If the number of columns in the right operand to stencil does not match the rank of the right argument, the windowing is applied on the major cells: | ||
< | <syntaxhighlight lang=apl> | ||
{⊂⍵}⌺(⍪2 2)⊢10 6⍴⍳100 | {⊂⍵}⌺(⍪2 2)⊢10 6⍴⍳100 | ||
┌──────────────┬─────────────────┬─────────────────┬─────────────────┬─────────────────┐ | ┌──────────────┬─────────────────┬─────────────────┬─────────────────┬─────────────────┐ | ||
Line 76: | Line 76: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Stencil allows for a very succinct expression of a [[dfn]] that calculates the next iteration in [[Conway's Game of Life]] (on a rectangle bound by zeros). Inspired by an algorithm from [[Arthur Whitney]] written in [[K]] and adapted to APL by Jay Foad: | Stencil allows for a very succinct expression of a [[dfn]] that calculates the next iteration in [[Conway's Game of Life]] (on a rectangle bound by zeros). Inspired by an algorithm from [[Arthur Whitney]] written in [[K]] and adapted to APL by Jay Foad: | ||
< | <syntaxhighlight lang=apl> | ||
⎕IO←0 | ⎕IO←0 | ||
life ← {3=s-⍵∧4=s←{+/,⍵}⌺3 3⊢⍵} | life ← {3=s-⍵∧4=s←{+/,⍵}⌺3 3⊢⍵} |