More work.

Author: athas

main.tex

@@ -572,6 +572,71 @@ \section{Array Operations}
 functional languages, they have implicitly parallel semantics, and
 some restrictions to preserve those semantics.
 
+In addition to the array combinators, there are constructs for
+\textit{constructing} arrays.  We already demonstrated literal arrays.
+Additionally, there is \texttt{iota}, which creates an array of a
+range of integers starting from zero:
+
+\begin{lstlisting}
+iota 10 == [0,1,2,3,4,5,6,7,8,9]
+\end{lstlisting}
+
+The name \texttt{iota} comes from APL, one of the earliest array
+programming languages, and is supposed to be mnemonic for creating
+\textit{index spaces} of arrays.  Put another way, \texttt{iota n}
+produces an array of valid indices into an array of size \texttt{n}.
+
+The \texttt{replicate} construct is used to create an array of some
+size, with all elements having the same given value:
+
+\begin{lstlisting}
+replicate 3 42 == [42,42,42]
+\end{lstlisting}
+
+We can use \texttt{concat} to combine several arrays:
+
+\begin{lstlisting}
+concat (iota 2) ([1,2,3]) (replicate 4 1) ==
+  [0,1,1,2,3,1,1,1,1i32]
+\end{lstlisting}
+
+Note that the parentheses around the literal array are necessary - if
+they were not present, this expression would be parsed as an attempt
+to index the expression \texttt{iota 2} using \texttt{[1,2,3]} as the
+indices.  This would of course result in a type error.
+
+We can use \texttt{zip} to transform $n$ arrays to a single array of
+$n$-tuples:
+
+\begin{lstlisting}
+zip [1,2,3] [true,false,true] [7.0,8.0,9.0] ==
+  [(1,true,7.0),(2,false,8.0),(3,true,9.0)]
+\end{lstlisting}
+
+That the input arrays may have different types.  We can use
+\texttt{unzip} to perform the inverse transformation:
+
+\begin{lstlisting}
+unzip [(1,true,7.0),(2,false,8.0),(3,true,9.0)] ==
+  ([1,2,3], [true,false,true], [7.0,8.0,9.0])
+\end{lstlisting}
+
+Be aware that \texttt{zip} requires all of the input arrays to have
+the same size.  Transforming between arrays of tuples and tuples of
+arrays is common in Futhark programs, as many array operations accept
+only one array as input.  Due to a clever implementation technique,
+\texttt{zip} and \texttt{unzip} also have no runtime cost (no copying
+or allocation whatsoever), so you should not shy away from using them
+out of efficiency concerns.\footnote{This is enabled via storing all
+  arrays in ``unzipped'' form.  That is, at runtime, arrays of tuples
+  do not exist, but have always been decomposed into multiple arrays.
+  This is a common practice for high-performance computing, usually
+  called ``structs of arrays'' versus ``arrays of structs'', and
+  serves to permit memory access patterns more friendly to vectorised
+  operations.}
+
+\subsection{Map}
+
 The simplest SOAC is probably \texttt{map}.  It takes two arguments: a
 function and an array.  The function argument can be a function name,
 or an anonymous function using \texttt{fn} syntax.  The function is
@@ -613,6 +678,33 @@ \section{Array Operations}
 map (+) [1,2,3] [4,5,6] == [5,7,9]
 \end{lstlisting}
 
+Be careful when writing \texttt{map} expressions where the function
+returns an array.  Futhark requires regular arrays, so a map with
+\texttt{iota} is unlikely to go well:
+
+\begin{lstlisting}
+map (fn n => iota n) ns
+\end{lstlisting}
+
+Unless the array \texttt{ns} consisted of identical values, the
+program would fail at runtime.
+
+We can use \texttt{map} and \texttt{iota} to duplicate many other
+language constructs.  For example, if we have two arrays
+\texttt{xs:[n]int} and \texttt{ys:[m]int}---that is, two integer
+arrays of sizes \texttt{n} and \texttt{m}---we can concatenate them
+using:
+
+\lstinputlisting[firstline=2]{src/concat_with_map.fut}
+
+However, it is not a good idea to write code like this, as it hinders
+the compiler from using high-level properties to do optimisation.
+Using \texttt{map}s over \texttt{iota}s with explicit indexing is
+usually only necessary when solving complicated irregular problems
+that cannot be represented directly.
+
+\subsection{Scan and Reduce}
+
 While \texttt{map} is an array transformer, the \texttt{reduce} SOAC
 is an array aggregator: it uses some function of type \texttt{t -> t
   -> t} to combine the elements of an array of type \texttt{[]t} to a
@@ -678,6 +770,37 @@ \section{Array Operations}
 Several examples are discussed in
 Chapter~\ref{chap:parallel-algorithms}.
 
+\subsection{Filtering}
+
+We have seen \texttt{map}, which permits us to change all the elements
+of an array.  We have seen \texttt{reduce}, which lets us collapse all
+the elements of an array.  But we still need something that lets us
+remove some, but not all, of the elements of an array.  This SOAC is
+\texttt{filter}, which behaves much like a filter in any other
+functional language:
+
+\begin{lstlisting}
+filter (<3) [1,5,2,3,4] == [1,2]
+\end{lstlisting}
+
+The use of \texttt{filter} is mostly straightforward, but there are
+some patterns that may appear subtle at first glance.  For example,
+how do we find the \textit{indices} of all nonzero entries in an array
+of integers?  Finding the values is simple enough:
+
+\begin{lstlisting}
+filter (fn x => x != 0) [0,5,2,0,1] ==
+  [5,2,1]
+\end{lstlisting}
+
+But what are the corresponding indices?  We can solve this using a
+combination of \texttt{zip}, \texttt{filter}, and \texttt{unzip}:
+
+\lstinputlisting[firstline=2]{src/indices_of_nonzero.fut}
+
+Be aware that \texttt{filter} is a somewhat expensive SOAC,
+corresponding roughly to a \texttt{scan} plus a \texttt{map}.
+
 \section{Sequential Loops}
 \label{sec:sequential-loops}
 

src/concat_with_map.fut

@@ -0,0 +1,3 @@
+fun main (xs: [n]int) (ys: [m]int): []int =
+  map (fn i => if i < n then xs[i] else ys[i-n])
+      (iota (n+m))

src/indices_of_nonzero.fut

@@ -0,0 +1,5 @@
+fun indices_of_nonzero(xs: [n]int): []int =
+  let xs_and_is = zip xs (iota n)
+  let xs_and_is' = filter (fn (x,_) => x != 0) xs_and_is
+  let (_, is') = unzip xs_and_is'
+  in is'

src/visualise.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python
+#
+# A generic visualiser for a Futhark program, using Pygame.  You can
+# use this to quickly test out things by modifying the
+# visualize_model.fut program, or use it as a starting point for a new
+# visualization.
+
+import visualise_model
+
+import numpy
+import pygame
+import time
+import sys
+
+preferred_size = (1000,1000) # Set to None for full-screen.
+
+# Pygame initialisation.
+pygame.init()
+pygame.display.set_caption('Generic Visualization')
+if preferred_size != None:
+    width, height = preferred_size
+else:
+    width = screen.get_width()
+    height = screen.get_height()
+size = (width, height)
+print size
+screen = pygame.display.set_mode(size)
+surface = pygame.Surface(size)
+font = pygame.font.Font(None, 36)
+pygame.key.set_repeat(500, 50)
+
+# Utility function for printing text.
+def showText(what, where):
+    text = font.render(what, 1, (100, 100, 255))
+    screen.blit(text, where)
+
+# Create a class instance corresponding to the Futhark program.  This
+# object exposes three methods (corresponding to entry points in the
+# Futhark program):
+#
+#  * 'initial_state', which returns some state.
+#
+#  * 'advance', which takes as argument a state, an integer
+#    representing some setting, and returns a new state.
+#
+#  * 'render', which takes as arguments the size of the viewport, the
+#    state, the setting, and returns an array of pixel data to be
+#    blitted to the screen.
+#
+# If you create new programs whose state is a tuple, you will need to
+# modify these to accept more parameters.
+model = visualise_model.visualise_model()
+
+state = model.initial_state()
+
+# This variable is modified on the Python side in response to keyboard input.
+setting = 10
+
+def render(model_time):
+    start = time.time()
+    # The .get() is necessary to retrieve a CPU-side Numpy array, as
+    # expected by the blit_array() method we use below.  It is likely
+    # that most of the time is spent copying this array back to main
+    # memory (only to then push it back to the GPU for rendering...).
+    frame = model.render(width, height, state, setting).get()
+    end = time.time()
+    render_time = (end - start) * 1000
+
+    pygame.surfarray.blit_array(surface, frame)
+    screen.blit(surface, (0, 0))
+
+    message = "Advancing took %.2fms; rendering took %.2fms (state setting: %d)" % (model_time, render_time, setting)
+    showText(message, (10,10))
+
+    pygame.display.flip()
+
+while True:
+    # First, advance the state of our model.  Measure how long that takes.
+    start = time.time()
+    state = model.advance(state, setting)
+    end = time.time()
+
+    # Then visualise it.
+    render((end - start) * 1000)
+
+    # Now wait for and handle events.
+    for event in pygame.event.get():
+        if event.type == pygame.QUIT:
+            # Our window was closed.
+            sys.exit()
+        elif event.type == pygame.KEYDOWN:
+            if event.key == pygame.K_UP:
+                setting += 1
+            if event.key == pygame.K_DOWN:
+                setting -= 1