Add section about Spaun to documentation.

docs/conf.py

@@ -27,6 +27,7 @@
 ]
 
 default_role = 'py:obj'
+numfig = True
 
 # -- sphinx.ext.autodoc
 autoclass_content = 'both'  # class and __init__ docstrings are concatenated

docs/user_guide.rst

@@ -101,10 +101,82 @@ TODO: link to more in depth discussion of circular convolution (including
 unitary vectors etc); mention alternate binding approaches?
 
 
-Spaun
-^^^^^
-
-TODO
+An example: Spaun
+^^^^^^^^^^^^^^^^^
+
+In chapter 7 of How to build a brain, the SPA Unified Network (Spaun) model is
+presented that demonstrates how a wide variety of (about 8) cognitive tasks can
+be integrated in a single large-scale, spiking neuron model. Spaun switches
+tasks and provides all responses without any manual change in parameters from
+a programmer. Essentially, it is a fixed model that integrates perception,
+cognition, and action across several different tasks. Spaun is the most complex
+example of an SPA to date.
+
+.. figure:: spa_1.png
+   :alt: High-level depicitoin of the Spaun model.
+
+   A high-level depiction of the Spaun model, with all of the central features
+   of a general Semantic Pointer Architecture. Visual and motor hierarchies
+   provide semantics via connections to natural input (images) and output (a
+   nonlinear dynamical arm model). Central information manipulation depends on
+   syntaictic structure for several tasks. Control is largely captured by the
+   basal ganglia aciton selection elements. Memory and learning take place in
+   both basal ganglia and contex. The model itself consists of just under
+   a million spiking neurons.
+
+Let us consider how the model would perform a single run of one of the cognitive
+tasks (`see a video of Spaun running this task
+<http://nengo.ca/build-a-brain/task7>`_). This is analogous to the `Raven's
+Matrix <https://en.wikipedia.org/wiki/Raven's_Progressive_Matrices>`_ task,
+which requires people to figure out a pattern in the input, and apply that
+pattern to new input to produce novel output. For instance given the following
+input ``[1] [11] [111] [2n [22] [222] [3] [33] ?`` the expected answer is
+``333``. The input to the model first indicates which task it is going to
+preform by presenting it with an ``A`` followed by the task number (e.g. ``A 7``
+for this task). Then it is shown a series of letters and brackets and it has to
+draw the correct answer with its arm. The processing for such a task goes
+something like this:
+
+1. The image impacts the visual system, and the neurons transform the raw image
+   input (784 dimensions) to a lower dimensional (50 dimensions) Semantic
+   Pointer that preserves central visual features. This is done using a visual
+   hierarchy model (i.e., V1-V2-V4-IT) that implements a learned statistical
+   compression.
+2. The visual Semantic Pointer is mapped to a conceptual Semantic Pointer by an
+   associative memory, and stored in a working memory. Storing Semantic
+   Pointers is performed by binding them to other Semantic Pointers that are
+   used to encode the order the information is presented in (e.g. to
+   distinguish ``1 2`` from ``2 1``).
+3. In this task, the Semantic Pointers generated by consecutive sets of inputs
+   are compared with each other to infer what relationship there exists (e.g.
+   between ``1`` and ``11``; or ``22`` and ``222``).
+4. The shared transofmation across all the input is determined by averaging the
+   previously inferred relationships across all sets of inputs (so the inferred
+   relationship between ``1`` and ``11`` is averaged with that between ``22``
+   and ``222``, etc.).
+5. When the ``?`` is encountered, Spaun determines its answer by taking the
+   average relationship and applying it to the last input (i.e., ``33``) to
+   generate an internal representation of the answer.
+6. This representation is then used to drive the motor system to write out the
+   correct answer (see :numref:`spa_2`), by sending the relevant Semantic
+   Pointers to the motor system.
+7. The motor system “dereferences” the semantic pointer by going down the motor
+   hierarchy to generate appropriate control signals for a high-degree of
+   freedom physical arm model.
+
+.. _spa_2:
+
+.. figure:: spa_2.png
+   :alt: Example input and output from Spaun.
+
+   Exapmle input and output from Spaun. a) Handwritten numbers used as input.
+   b) Numbers drawn by Spaun using its arm.
+
+All of the control-like steps (e.g. “compared with”, “inferred”, and routing
+information through the system), are implemented by a biologically plausible
+basal ganglia model. This is one example of the 8 different tasks that Spaun is
+able to perform. Videos for all tasks can be found `here
+<http://nengo.ca/build-a-brain/spaunvideos/>`_.
 
 
 Introduction to Nengo SPA