\documentclass[a4paper,12pt]{report}

\usepackage[margin=1in]{geometry}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{amsmath,amssymb}
\usepackage{graphicx}
\usepackage{listings}

\usepackage[round]{natbib}
\usepackage{hyperref}
% Fix double links created by natbib
\makeatletter
\renewcommand\hyper@natlinkbreak[2]{#1}
\makeatother

\usepackage{makeidx}
\usepackage{url}
\usepackage{longtable}
\usepackage{tabularx}
\usepackage[nottoc]{tocbibind}
\usepackage[table]{xcolor}

\usepackage{fancyhdr}
\pagestyle{fancyplain}
% chapter mark, only needed for twosided print
\renewcommand{\chaptermark}[1]{\markboth{#1}{}}
% section mark
\renewcommand{\sectionmark}[1]{\markright{\thesection\ #1}}

\lhead[\fancyplain{}{\bfseries\thepage}]%    [even]{odd}
      {\fancyplain{}{\bfseries\rightmark}}
\chead[\fancyplain{}{}]{\fancyplain{}{}}
\rhead[\fancyplain{}{\bfseries\leftmark}]%
      {\fancyplain{}{\bfseries\thepage}}

\usepackage{mathpazo}
\usepackage{helvet}

\graphicspath{{user_manual_figures/}{../../extras/logos/}}

% \scriptfig{file}{rel.width}{shortcap}{caption}
\newcommand{\scriptfig}[4]{%
\begin{figure}
\centerline{\includegraphics[width=#2\linewidth]{#1}}
\caption[#3]{#4}
\label{fig:#1}
\end{figure}%
}

\makeindex

\definecolor{lstcolor}{gray}{0.9}
\lstset{% Settings for the listing package
  language=Python,
  numbers=none,
  basicstyle=\small,
  showstringspaces=false,
  lineskip=2pt,
  escapechar=!,
  backgroundcolor=\color{lstcolor},
  morekeywords={Create,SetStatus,GetStatus,Connect,
     GetNodes,GetLeaves,
     ConvergentConnect,DivergentConnect,
     Simulate,RandomConvergentConnect,
     RandomDivergentConnect,CopyModel,
     SetKernelStatus,PrintNetwork,SetDefaults,
   voltage_trace,raster_plot,ResetKernel,GetConnections,
   CreateLayer,ConnectLayers,GetPosition,GetLayer,
   GetElement,FindNearestElement,Displacement,Distance,
   DumpLayerNodes,DumpLayerConnections,FindCenterElement,
   GetTargetNodes,GetTargetPositions,PlotTargets,PlotKernel,PlotLayer,Install},
  rangeprefix=\#\{\ ,
  rangesuffix=\ \#\},
  includerangemarker=false}

\renewcommand{\abstractname}{About the Topology Module}

\title{NEST Topology User Manual}
\author{Hans Ekkehard Plesser\\[1ex]
Håkon Enger\\[1ex]
\normalsize Department of Mathematical Sciences and Technology\\\normalsize Norwegian University of Life Sciences\\
\normalsize 1432 Ås, Norway}
\date{NEST 2.2 (r9977 or later)\\[8cm]
\centerline{\includegraphics{nest-initiative-logo}}}


\begin{document}

\maketitle

\begin{abstract}
  This user manual gives a short introduction to the use of the
  Topology Module for the NEST Neural Simulation Tool.

  Rüdiger Kupper wrote a first topology library for NEST many years
  ago entirly in SLI (actually, it pre-dates the NEST kernel).  Kittel
  Austvoll and Hans Ekkehard Plesser designed and wrote a completely
  new Topology library in 2007/8. That library has been available with
  the NEST 1.9.x pre-releases since.

  For NEST 2.0, Håkon Enger and Hans Ekkehard Plesser re-factored
  parts of the Topology library code, improved and extended the PyNEST
  interface for the Topology library, fixed bugs and added tests.

  For NEST 2.2, Håkon Enger rewrote most of the Topology library code,
  thereby improving performance considerably.

  This User Manual describes the NEST 2.2 version of the NEST Topology
  Library. Please see Chapter~\ref{sec:changes} for a summary of changes.

  We plan further improvements to the Topology Module in the future, 
  which may include changes to the API to remove some of the remaining
  inconsistencies and provide a cleaner user interface.

  \vspace*{\fill}{\centerline{\footnotesize{Copyright \copyright{} 2010 The NEST Initiative}}}
\end{abstract}

\tableofcontents

\chapter{Introduction}\label{sec:intro}

The Topology Module provides the NEST simulator\footnote{NEST is
  available under an open source license at
\url{www.nest-initiative.org}.}
\citep{Gewa:2007(1430)} with a convenient interface for creating
layers of neurons placed in space and connecting neurons in such
layers with probabilities and properties depending on the relative
placement of neurons.  This permits the creation of complex networks
with spatial structure.

This user manual provides an introdcution to the functionality
provided by the Topology Module. It is based exclusively on the
PyNEST, the Python interface to NEST \citep{Eppl:2008(12)}. NEST users
using the SLI interface should be able to map instructions to
corresponding SLI code. This manual is not meant as a comprehensive
reference manual. Please consult the online documentation in PyNEST
for details; where appropriate, that documentation also points to
relevant SLI documentation.

This manual describes the Topology Module included with NEST~2.2, code
revision 9977 or later.  This version differs from older ones in some
important aspects as detailed in Section~\ref{sec:changes}. In our
experience, though, most scripts using the Topology Module can be
ported to the new version with minimal changes.

In the next chapter of this manual, we introduce Topology layers,
which place neurons in space. In Chapter~\ref{sec:connections} we then
describe how to connect layers with each other, before discussing in
Chapter~\ref{sec:inspection} how you can inspect and visualize
Topology networks. Chapter~\ref{ch:extending} deals with the more advanced
topic of extending the Topology module with custom kernel functions and
masks provided by C++ classes in an extension module.

You will find the Python scripts used in the examples in this manual 
 in the NEST
source code directory under \lstinline!topology/doc/user_manual_scripts!.

\section{Limitations and Disclaimer}\label{sec:limitations}

\begin{description}
\item[Undocumented features] The Topology Module provides a number of undocumented features, which
you may discover by browsing the code. These features are highly
experimental and should \emph{not be used for simulations}, as they
have not been validated.
\end{description}




\chapter{Layers}\label{sec:layers}

The Topology Module (just Topology for short in the remainder of this
document) organizes neuronal networks in \emph{layers}\index{layer}. We will first
illustrate how Topology places elements in simple layers, where each
element is a single model neuron. Layers with composite elements are
discussed in the following section.

We will illustrate the definition and use of layers using examples.

Topology distinguishes between two classes of layers:
\begin{description}
\item[grid-based layers] in which each element is placed at a location in
  a regular grid;
\item[free layers] in which elements can be placed arbitrarily in the plane.
\end{description}
Grid-based layers allow for more efficient connection-generation under
certain circumstances.

\section{Grid-based Layers}\label{sec:gridbased}

\subsection{A very simple layer}\label{sec:verysimple}

We create a first, grid-based simple layer\index{grid-based layer} 
with the following commands:
%
\lstinputlisting[linerange=layer1-end]{user_manual_scripts/layers.py}
\scriptfig{layer1}{0.5}{Simple grid-based layer}%
{Simple grid-based layer centered about the origin. Blue circles mark
layer elements, the thin square the extent of the layer. Row and
column indices are shown in the right and top margins, respectively.}
%
The layer is shown in Fig.~\ref{fig:layer1}. Note the following
properties:
\begin{itemize}
\item The layer has five \emph{rows}\index{row} and five
  \emph{columns}\index{columns}.
\item The \lstinline!'elements'! entry of the dictionary passed to
  \lstinline!CreateLayer! determines the
  \emph{elements}\index{element} of the layer. In this case, the layer
  contains \lstinline!iaf_neuron!s.
\item The \emph{center}\index{center} of the layer is at the origin of
  the coordinate system, $(0,0)$. 
\item The \emph{extent}\index{extent} or size of the layer is $1\times
  1$. This is the default size for layers. The extent is marked by the
  thin square in Fig.~\ref{fig:layer1}.
\item The \emph{grid spacing}\index{grid spacing} of the layer is 
\begin{equation}\label{eq:dx_dy_extent}\begin{split}
dx &= \frac{\text{x-extent}}{\text{number of columns}} \\
dy &= \frac{\text{y-extent}}{\text{number of rows}} 
\end{split}\end{equation}
In the layer shown, we have $dx=dy=0.2$, but the grid spacing may differ
in x- and y-direction.
\item Layer elements are spaced by the grid spacing and are arranged
  symmetrically about the center. 
\item The outermost layer elements are placed $dx/2$ and $dy/2$ from
  the borders of the extent.
\item Element \emph{positions}\index{position} in the coordinate
  system are given by $(x,y)$ pairs. The \emph{coordinate
    system}\index{coordinate system} follows that standard
  mathematical convention that the $x$-axis runs from left to right
  and the $y$-axis from bottom to top.
\item Each element of a grid-based layer has a \emph{row- and
    column-index} \index{index} in addition to its
  $(x,y)$-coordinates. Indices are shown in the top and right margin
  of Fig.~\ref{fig:layer1}. Note that row-indices follow matrix
  convention, i.e., run from top to bottom. Following pythonic
  conventions, indices run from 0. 
\end{itemize}

\textbf{Note}: The \textbf{definition of the extent has changed} from
NEST~1.9 to NEST~2.0. In NEST~1.9, the outermost elements of the layer
were placed on the limits of the extent. When working with periodic
boundary conditions (see Sec.~\ref{sec:periodic}), Topology then
silently padded the layer with half a grid spacing on all sides, to
ensure that nodes at opposite edges did not coincide.

\subsection{Setting the extent}\label{sec:setextent}

Layers have a default extent of $1\times 1$. 
You can specify a different extent of a layer, i.e., its size in $x$- and
$y$-direction by adding and \lstinline!'extent'! entry to the
dictionary passed to \lstinline!CreateLayer!:
%
\lstinputlisting[linerange=layer2-end]{user_manual_scripts/layers.py}
\scriptfig{layer2}{0.8}{Layer with non-standard extent}%
{Same layer as in Fig.~\ref{fig:layer1}, but with different extent.}
%
The resulting layer is shown in Fig.~\ref{fig:layer2}. The extent is
always a two-element tuple of floats. In this example, we have grid
spacings $dx=0.4$ and $dy=0.1$. Changing the extent does not affect
grid indices.

\subsection{Setting the center}\label{sec:setcenter}

Layers are centered about the origin $(0,0)$ by default. This can be
changed through the \lstinline!'center'!\index{center} entry in the dictionary
specifying the layer. The following code creates layers centered about
$(0,0)$, $(-1,1)$, and $(1.5,0.5)$, respectively:
%
\lstinputlisting[linerange=layer3-end]{user_manual_scripts/layers.py}
\scriptfig{layer3}{0.8}{Layers with different centers}%
{Three layers centered, respectively, about $(0,0)$ (blue), $(-1,-1)$
  (green), and $(1.5,0.5)$ (red).}
%
The center is given as a two-element tuple of floats.
Changing the center does not affect grid indices: For each of the
three layers in Fig.~\ref{fig:layer3}, grid indices run from 0 to 4
through columns and rows, respectively, even though elements in these
three layers have different positions in the gobal coordinate system.

\subsection{Constructing a layer: an example}\label{sec:fixedlayerexample}

To see how to construct a layer, consider the following example: 
\begin{itemize}
\item a layer with $n_r$ rows and $n_c$ columns;
\item spacing between nodes is $d$ in $x$- and $y$-directions;
\item the left edge of the extent shall be at $x=0$;
\item the extent shall be centered about $y=0$.
\end{itemize}
From Eq.~\ref{eq:dx_dy_extent}, we see that the extent of the layer
must be $(n_c d, n_r d)$. We now need to find the coordinates $(c_x,
c_y)$ of the center of the layer. To place the left edge of the extent
at $x=0$, we must place the center of the layer at $c_x=n_c d / 2$
along the $x$-axis, i.e., half the extent width to the right of
$x=0$. Since the layer is to be centered about $y=0$, we have
$c_y=0$. Thus, the center coordinates are $(n_c d/2, 0)$. The layer is
created with the following code and shown in Fig.~\ref{fig:layer3a}:
%
\lstinputlisting[linerange=layer3a-end]{user_manual_scripts/layers.py}
\scriptfig{layer3a}{0.5}{Layer construction example}%
{Layer with $n_c=5$ rows and $n_r=3$ columns, spacing $d=0.1$ and the
  left edge of the extent at $x=0$, centered about the $y$-axis. The
  cross marks the point on the extent placed at the origin $(0,0)$,
the circle the center of the layer.}
%


\section{Free layers}\label{sec:freelayer}

\emph{Free layers}\index{free layer} do not restrict node positions to
a grid, but allow free placement within the extent. To this end, the
user needs to specify the positions of all nodes explicitly. The
following code creates a layer of 50 \lstinline!iaf_neurons! uniformly
distributed in a layer with extent $1\times 1$, i.e., spanning the
square $[-0.5,0.5]\times[-0.5,0.5]$:
%
\lstinputlisting[linerange=layer4-end]{user_manual_scripts/layers.py}
\scriptfig{layer4}{0.5}{Layer with freely spaced elements.}%
{A free layer with 50 elements uniformly distributed in an extent of
size $1\times 1$.}
%
Note the following points:
\begin{itemize}
\item For free layers, element \emph{positions}\index{position} are
  specified by the \lstinline!'positions'! entry in the dictionary
  passed to \lstinline!CreateLayer!. \lstinline!'positions'! is
  mutually exclusive with \lstinline!'rows'!/\lstinline!'columns'!
  entries in the dictionary.
\item The \lstinline!'positions'! entry must be a Python
  \lstinline!list! (or \lstinline!tuple!) of element coordinates,
  i.e., of two-element tuples of floats giving the ($x$, $y$)-coordinates
  of the elements. One layer element is created per element in the
  \lstinline!'positions'! entry.
\item All layer element positions must be \emph{within} the layer's
  extent. Elements may be place on the perimeter of the extent as long
  as no periodic boundary conditions are used; see Sec.~\ref{sec:periodic}.
\item Element positions in free layers are \emph{not} shifted when
  specifying the \lstinline!'center'! of the layer. The user must make
  sure that the positions given lie within the extent when centered
  about the given center.
\end{itemize}


\section{3D layers}\label{sec:3dlayer}

Although the term ``layer'' suggests a 2-dimensional structure, the layers
in NEST may in fact be 3-dimensional\index{3D layers}.  The example from
the previous section may be easily extended with another component in the
coordinates for the positions:
%
\lstinputlisting[linerange=layer4_3d-end]{user_manual_scripts/layers.py}
\scriptfig{layer4_3d}{0.5}{3D layer with freely spaced elements.}%
{A free 3D layer with 200 elements uniformly distributed in an extent of
size $1\times 1\times 1$.}
%


\section{Periodic boundary conditions}\label{sec:periodic}

Simulations usually model systems much smaller than the biological
networks we want to study. One problem this entails is that a
significant proportion of neurons in a model network is close to the
edges of the network with fewer neighbors than nodes properly inside
the network. In the $5\times 5$-layer in Fig.~\ref{fig:layer1}, e.g.,
16 out of 25 nodes form the border of the layer.

One common approach to reducing the effect of boundaries on
simulations is to introduce \emph{periodic boundary
  conditions}\index{periodic boundary cond.}, so that the
rightmost elements on a grid are considered nearest neighbors to the
leftmost elements, and the topmost to the bottommost. The flat layer
becomes the surface of a torus. Fig.~\ref{fig:player} illustrates this
for a one-dimensional layer, which turns from a line to a ring upon
introduction of periodic boundary conditions. 

You specify periodic boundary conditions for a layer using the
dictionary entry \lstinline!edge_wrap!\index{egde\_wrap}:
%
\lstinputlisting[linerange=player-end]{user_manual_scripts/layers.py}
\scriptfig{player}{0.8}{Periodic boundary conditions.}%
{Top left: Layer with single row and five columns without periodic
  boundary conditions. Numbers above elements
  show element coordinates. Colors shifting from blue to magenta mark
  increasing distance from the element at $(-2,0)$. 
  Bottom left: Same layer, but with periodic boundary
  conditions.
  Note that the element at $(2,0)$ now is a nearest
  neighbor to the element at $(-2,0)$.
  Right: Layer with periodic boundary condition arranged on a circle
  to illustrate neighborhood relationsships.}

Note that the longest possible distance between two elements in a
layer without periodic boundary conditions is
\begin{equation*}
\sqrt{x_{\text{ext}}^2 + y_{\text{ext}}^2}
\end{equation*}
but only
\begin{equation*}
\left.\sqrt{x_{\text{ext}}^2 + y_{\text{ext}}^2}\right/ 2
\end{equation*}
for a layer with periodic boundary conditions; $x_{\text{ext}}$ and
$y_{\text{ext}}$ are the components of the extent size. 

We will discuss the consequences of periodic boundary conditions more
in Chapter~\ref{sec:connections}.

\subsection{Topology layer as NEST subnet}\label{sec:subnet}

From the perspective of NEST, a Topology layer is a special type of
\emph{subnet}\index{subnet}. From the user perspective, the following
points may be of interest:
\begin{itemize}
\item Grid-based layers have the NEST model type
  \lstinline!topology_layer_grid!\index{topology\_layer\_grid}, free
  layers the model type
  \lstinline!topology_layer_free!\index{topology\_layer\_free}.
\item The status dictionary of a layer has a \lstinline!'topology'!
  entry describing the layer properties (\lstinline!l! is the layer
  created above):
%
\lstinputlisting[linerange=layer1s-end]{user_manual_scripts/layers.py}
\lstinputlisting[linerange=layer1s.log-end.log,breaklines=true,%
                 breakatwhitespace=true]{user_manual_scripts/layers.log}
%
The \lstinline!'topology'! entry is read-only. 
\item The NEST kernel sees the elements of the layer in the same way
  as the elements of any subnet. You will notice this when printing a
  network with a Topology layer:
%
\lstinputlisting[linerange=layer1p-end]{user_manual_scripts/layers.py}
\lstinputlisting[linerange=layer1p.log-end.log]{user_manual_scripts/layers.log}
%
The $5\times 5$ layer created above appears here as a
\lstinline!topology_layer_grid! subnet of 25 \lstinline!iaf_neuron!s.
Only Topology connection and visualization functions heed the spatial
structure of the layer.
\end{itemize}

\section{Layers with composite elements}\label{sec:composite_layers}

So far, we have considered layers in which each element was a single
model neuron. Topology can also create layers with \emph{composite
  elements}\index{composite element}, i.e., layers in which each
element is a collection of model neurons, or, in
general NEST network nodes.

Construction of layers with composite elements proceeds exactly as for
layers with simple elements, except that the \lstinline!'elements'!
entry of the dictionary passed to \lstinline!CreateLayer! is a Python
list or tuple. The following code creates a $1\times 2$ layer (to keep
the output from \lstinline!PrintNetwork()! compact) in which
each element consists of one \lstinline!'iaf_cond_alpha'! and one
\lstinline!'poisson_generator'! node
%
\lstinputlisting[linerange=layer6-end]{user_manual_scripts/layers.py}
\lstinputlisting[linerange=layer6-end]{user_manual_scripts/layers.log}
%
The network consist of one \lstinline!topology_layer_grid! with four
elements: two \lstinline!iaf_cond_alpha! and two
\lstinline!poisson_generator! nodes. The identical nodes are grouped, so
that the subnet contains first one full layer of \lstinline!iaf_cond_alpha!
nodes followed by one full layer of \lstinline!poisson_generator! nodes.

You can create network elements with several nodes of each type by
following a model name with the number of nodes to be created:
%
\lstinputlisting[linerange=layer7-end]{user_manual_scripts/layers.py}
\lstinputlisting[linerange=layer7-end]{user_manual_scripts/layers.log}
%
In this case, each layer element consists of 10
\lstinline!iaf_cond_alpha! neurons, one \lstinline!poisson_generator!,
and two \lstinline!noise_generator!s. 

Note the following points:
\begin{itemize}
\item Each element of a layer has identical components.
\item All nodes within a composite element have identical positions,
  namely the position of the layer element.
\item When inspecting a layer as a subnet, the different nodes will appear
  in groups of identical nodes.
\item For grid-based layers, the function \lstinline!GetElement! returns a
  list of nodes at a given grid position. See Chapter~\ref{sec:inspection}
  for more on inspecting layers.
\item In a previous version of the topology module it was possible to
  create layers with nested, composite elements, but such nested networks
  gobble up a lot of memory for subnet constructs and provide no practical
  advantages, so this is no longer supported. See the next section for
  design recommendations for more complex layers.
\end{itemize}

\subsection{Designing layers}\label{sec:layerdesign}

A paper on a neural network model might describe the network as
follows\footnote{See \citet{Nord:2009(456)} for suggestions on how to
  describe network models.}:
\begin{quote}
The network consists of $20x20$ microcolumns placed on a regular grid
spanning $0.5^\circ\times 0.5^\circ$ of visual space. Neurons within each
microcolumn are organized into L2/3, L4, and L56
subpopulations. Each subpopulation consists of three pyramidal cells
and one interneuron. All pyramidal cells are modeled as NEST
\lstinline!iaf_neuron!s with default parameter values, while
interneurons are \lstinline!iaf_neuron!s with threshold voltage
$V_{\text{th}}=-52$mV. 
\end{quote}
How should you implement such a network using the Topology module?
The recommended approach is to create different models for the
neurons in each layer and then define the microcolumn as one
composite element:
%
\lstinputlisting[linerange=layer10-end]{user_manual_scripts/layers.py}
%
We will discuss in Chapter~\ref{sec:conn_basics} how to connect
selectively to different neuron models.


\chapter{Connections}\label{sec:connections}

The most important feature of the Topology module is the ability to
create connections\index{connection} between layers with quite some
flexibility. In this chapter, we will illustrate how to specify and
create connections. All connections are created using the
\lstinline!ConnectLayers!\index{ConnectLayers} function.


\section{Basic principles}\label{sec:conn_basics}

\subsection{Terminology}\label{sec:terminology}
We begin by introducing important terminology:
\begin{description}
\item[Connection\index{connection}] In the context of connections
  between the elements of Topology layers, we often call the set of all connections
  between pairs of network nodes created by a single call to
  \lstinline!ConnectLayers! a \emph{connection}.
\item[Connection dictionary\index{connection dictionary}] A dictionary
  specifying the properties of a connection between two layers in a call to
  \lstinline!CreateLayers!.
\item[Source\index{source}] The \emph{source} of a single connection
  is the node sending signals (usually spikes). In a projection, the
  source layer\index{source layer} is the layer from which source node
  are chosen.
\item[Target\index{target}]
The \emph{target} of a single connection
  is the node receiving signals (usually spikes). In a projection, the
  target layer\index{target layer} is the layer from which source node
  are chosen.
\item[Connection type\index{connection type}] The \emph{connection
    type} determines how nodes are selected when
  \lstinline!ConnectLayers! creates connections between layers. It is
  either \lstinline!'convergent'! or \lstinline!'divergent'!.
\item[Convergent connection\index{convergent connection}] When
  creating a \emph{convergent connection} between layers, Topology
  visits each node in the target layer in turn and selects sources for
  it in the source layer. Masks and kernels are applied to the source
  layer, and periodic boundary conditions are applied in the source
  layer, provided that the source layer has periodic boundary conditions.
\item[Divergent connection\index{divergent connection}] When creating
  a \emph{divergent connection}, Topology visits each node in the
  source layer and selects target nodes from the target layer. Masks, kernels, and
  boundary conditions are applied in the target layer.
\item[Driver\index{driver}] When connecting two layers, the
  \emph{driver} layer is the one in which each node is considered in
  turn. 
\item[Pool\index{pool}] When connecting two layers, the
  \emph{pool} layer is the one from which nodes are chosen for each
  node in the driver layer. I.e., we have\\
  \begin{tabular}{l||l|l}
  Connection type  & Driver & Pool \\\hline\hline
  convergent  & target layer & source layer \\\hline
  divergent   & source layer & target layer
  \end{tabular}
\item[Displacement\index{displacement}] The \emph{displacement}
  between a driver and a pool node is the shortest vector connecting
  the driver to the pool node, taking
  boundary conditions into accout.
\item[Distance\index{distance}] The \emph{distance} between a driver
  and a pool node is the length of their displacement.
\item[Mask\index{mask}] The \emph{mask} defines which pool nodes are
  at all considered as potential targets for each driver node. See
  Sec.~\ref{sec:conn_masks} for details.
\item[Kernel\index{kernel}] The \emph{kernel} is a function returning
  a (possibly distance- or displacment-dependent) 
  probability for creating a connection between a driver and a pool
  node. The default kernel is $1$, i.e., connections are created with
  certainty. See Sec.~\ref{sec:conn_kernels} for details.
\item[Autapse\index{autapse}] An \emph{autapse} is a synapse (connection) from a
  node onto itself. Autapses are permitted by default, but can be
  disabled by adding \lstinline!'allow_autapses': False! to the
  connection dictionary.
\item[Multapse\index{multapse}] Node A is connected to node B by a
  \emph{multapse} if there are synapses (connections) from A to
  B. Multapses are permitted by default, but can be disabled by adding
  \lstinline!'allow_multapses': False! to the connection dictionary.
\end{description}

\subsection{A minimal ConnectLayers call}\label{sec:minimalcall}
Connections between Topology layers are created by calling
\lstinline!ConnectLayers!\index{ConnectLayers} with the following arguments\footnote{You
  can also use standard NEST connection functions to connect nodes in
  Topology layers.}:
\begin{enumerate}
\item The source layer.
\item The target layer (can be identical to source layer).
\item A connection dictionary that contains at least the following entries:
\begin{description}
\item['connection\_type'] Either \lstinline!'convergent'!
  or \lstinline!'divergent'!.
\item['mask'] A mask specification as described in
  Sec.~\ref{sec:conn_masks}.
\end{description}
\end{enumerate}
Here is a simple example, cf.~\ref{fig:conn1}:
%
\lstinputlisting[linerange=conn1-end]{user_manual_scripts/connections.py}
\scriptfig{conn1}{0.9}{Minimal connection example}%
{Left: Minimal connection example from a layer onto itself using a
  rectangular mask shown as red line for the node at $(0,0)$ (marked
  light red). The targets of this node are marked with red dots. The targets
  for the node at $(4,5)$ (marked light orange) are marked with orange
  dots. This node has fewer targets since it is at the corner and many
  potential targets are beyond the layer.
Right: The effect of periodic boundary conditions\index{periodic
  boundary cond.} is seen here. Source and target layer and connection dictionary
were identical, except that periodic boundary conditions were
used. The node at $(4,5)$ now has 15 targets, too, but they are spread
across the corners of the layer. If we wrapped the layer to a torus,
they would form a $5\times 3$ rectangle centered on the node at $(4,5)$.}
%
In this example, layer \lstinline!l! is both source and target
layer. Connection type is divergent, i.e., for each node in the layer
we choose targets according to the rectangular mask centered about
each source node. Since no connection kernel is specified, we connect
to all nodes within the mask. Note the effect of normal and periodic
boundary conditions on the connections created for different nodes in
the layer, as illustrated in Fig.~\ref{fig:conn1}.


\section{Mapping source and target layers}\label{sec:mapping}

The application of masks and other functions depending on the distance
or even the displacement between nodes in the source and target layers
requires a mapping\index{mapping} of coordinate
systems\index{coordinate system} between source and target
layers. Topology applies the following \emph{coordinate mapping
  rules}\index{coordinate mapping rules}:
\begin{enumerate}
\item All layers have two-dimensional Euclidean coordinate systems.
\item No scaling or coordinate transformation can be applied between
  layers.
\item The displacement $d(D,P)$ from node $D$ in the driver layer to node $P$
  in the pool layer is measured by first mapping the position of $D$
  in the driver layer to the identical position in the pool layer and
  then computing the displacement from that position to $P$. If the
  pool layer has periodic boundary conditions, they are taken into
  account. It does not matter for displacement computations whether
  the driver layer has periodic boundary conditions.
\end{enumerate}


\section{Masks}\label{sec:conn_masks}

A mask describes which area of the pool layer shall be searched for
nodes to connect for any given node in the driver layer. We will first
describe geometrical masks defined for all layer types and then
consider grid-based masks for grid-based layers.

Note that the mask size should not exceed the size of the layer when
using periodic boundary conditions, since the mask would ``wrap
around'' in that case and pool nodes would be considered multiple
times as targets.

If none of the mask types provided in the topology library meet your need,
you may add more mask types in a NEST extension module. This is covered in
Chapter~\ref{ch:extending}.


\subsection{Masks for 2D layers}\label{sec:free_masks}

Topology currently provides three types of masks usable for 2-dimensional
free and grid-based layers. They are illustrated in Fig.~\ref{fig:conn2}.
The masks are
\begin{description}
\item[Rectangular\index{rectangular}] All nodes within a rectangular
  area are connected. The area is speficied by its lower left and
  upper right corners, measured in the same unit as element
  coordinates. Example:
\lstinputlisting[linerange=conn2r-end]{user_manual_scripts/connections.py}
\item[Circular\index{circular}] All nodes within a circle are
  connected.  The area is specified by its radius.
\lstinputlisting[linerange=conn2c-end]{user_manual_scripts/connections.py}
\item[Doughnut\index{doughnut}] All nodes between an inner and outer
  circle are connected. Note that nodes \emph{on} the inner circle are
  not connected. The area is specified by the radii of the inner and
  outer circles.
\lstinputlisting[linerange=conn2d-end]{user_manual_scripts/connections.py}
\end{description}
By default, the masks are centered about the position of the driver
node, mapped into the pool layer. You can change the location of the
mask relative to the driver node by specifying an
\lstinline!'anchor'!\index{anchor} entry in the mask dictionary. The
anchor is a 2D vector specifying the location of the mask center
relative to the driver node, as in the following examples (cf.\
Fig.~\ref{fig:conn2}, bottom row):
\lstinputlisting[linerange=conn2ro-end]{user_manual_scripts/connections.py}
\lstinputlisting[linerange=conn2co-end]{user_manual_scripts/connections.py}
\lstinputlisting[linerange=conn2do-end]{user_manual_scripts/connections.py}

\scriptfig{conn2}{0.9}{Masks for 2D layers}%
{Masks for 2D layers. For all mask types, the driver node is
  marked by a wide light-red circle, the selected pool nodes by red
  dots and the masks by red lines. Top row from left to right:
  rectangular, circular and doughnut masks centered about the driver
  node.
Bottom row from left to right: the same masks as in the top row, but
centered about $(-1.5,-1.5)$, $(-2,0)$ and $(1.5,1.5)$, respectively,
using the \lstinline!'anchor'! parameter.}


\subsection{Masks for 3D layers}\label{sec:3d_masks}

Similarly, there are two mask types that can be used for 3D layers\index{3D layers},
\begin{description}
\item[Box\index{box}] All nodes within a cuboid volume are connected. The
  area is speficied by its lower left and upper right corners, measured in
  the same unit as element coordinates. Example:
  \lstinputlisting[linerange=conn_3d_a-end]{user_manual_scripts/connections.py}
\item[Spherical\index{spherical}] All nodes within a sphere are
  connected.  The area is specified by its radius.
\lstinputlisting[linerange=conn_3d_b-end]{user_manual_scripts/connections.py}
\end{description}
As in the 2D case, you can change the location of the mask relative to the
driver node by specifying a 3D vector in the
\lstinline!'anchor'!\index{anchor} entry in the mask dictionary.

\scriptfig{conn_3d}{0.9}{Masks for 3D layers}%
{Masks for 3D layers. For all mask types, the driver node is
  marked by a wide light-red circle, the selected pool nodes by red
  dots and the masks by red lines. From left to right:
  box and spherical masks centered about the driver node.}


\subsection{Masks for grid-based layers}\label{sec:grid_masks}

Grid-based layers can be connected using rectangular \emph{grid
  masks}\index{grid mask}. For these, you specify the size of the mask
not by lower left and upper right corner coordinates, but give their
size in rows and columns, as in this example:
%
\lstinputlisting[linerange=conn3-end]{user_manual_scripts/connections.py}
% 
The resulting connections are shown in Fig.~\ref{fig:conn3}. By
default the top-left corner of a grid mask, i.e., the grid mask
element with grid index $[0,0]$\footnote{See Sec.~\ref{sec:verysimple} for the
distinction between layer coordinates and grid indices}, is aligned
with the driver node. You can change this alignment by specifying an 
 \emph{anchor}\index{anchor} for the mask:
%
\lstinputlisting[linerange=conn3c-end]{user_manual_scripts/connections.py}
% 
You can even place the anchor outside the mask:
%
\lstinputlisting[linerange=conn3x-end]{user_manual_scripts/connections.py}
% 
The resulting connection patterns are shown in Fig.~\ref{fig:conn3}.
%
\scriptfig{conn3}{0.9}{Grid masks}%
{Grid masks for connections between grid-based layers.
Left: $5\times3$ mask with default alignment at upper left corner.
Center: Same mask, but anchored to center node at grid index $[1,2]$.
Right: Same mask, but anchor to the upper left of the mask at grid
index $[-1,2]$.}
Connections specified using grid masks are generated more efficiently
than connections specified using other mask types.

Note the following:
\begin{itemize}
\item Grid-based masks are applied by considering grid indices. The
  position of nodes in physical coordinates is ignored.
\item In consequence, grid-based masks should only be used between
  layers with identical grid spacings. 
\item The semantics of the \lstinline!'anchor'! property for
grid-based masks differ
significantly for general masks described in
Sec.~\ref{sec:free_masks}. For general masks, the anchor is the center
of the mask relative to the driver node. For grid-based nodes, the
anchor determines which mask element is aligned with the driver element.
\end{itemize}


\section{Kernels}\label{sec:conn_kernels}

Many neuronal network models employ probabilistic connection
rules\index{probabilistic connection rules}. Topology supports
probabilistic connections through \emph{kernels}\index{kernel}. A
kernel is a function mapping the distance (or displacement) between a
driver and a pool node to a connection probability. Topology then
generates a connections according to this probability.

Probabilistic connections can be generated in two different ways using
Topology:
\begin{description}
\item[Free probabilistic connections\index{free probabilistic
    connections}] are the default. 
  In this case, \lstinline!ConnectLayers! considers each driver node $D$
  in turn. For each $D$, it evaluates the kernel for each
  pool node $P$ within the mask and creates a connection according to
  the resulting probability. This means in particular that \emph{each
    possible driver-pool pair is inspected exactly once} and that
  there will be \emph{at most one connection between each driver-pool pair}.
\item[Prescribed number of connections] can be obtained by specifying
  the number of connections to create per driver node. See
  Sec.~\ref{sec:prescribed_numbers} for details.
\end{description}

Available kernel functions are shown in Table~\ref{tab:kernels}. More
kernel function may be created in a NEST extension module. This is covered
in Chapter~\ref{ch:extending}.

\begin{table}
\begin{tabularx}{\linewidth}{l|p{0.2\linewidth}|X}
Name & Parameters & Function \\\hline
%
constant & & {constant $p\in[0,1]$} \\
%
\rowcolor{lstcolor}
\lstinline!uniform! & \lstinline!min!, \lstinline!max! & $p\in
[\text{min},\text{max})$ uniformly \\
%
\lstinline!normal! &
\lstinline!mean!, \lstinline!sigma!, \lstinline!min!, \lstinline!max! &
$p \in [\text{min},\text{max})$ normal with given mean and $\sigma$ \\
%
\rowcolor{lstcolor}
\lstinline!lognormal! &
\lstinline!mu!, \lstinline!sigma!, \lstinline!min!, \lstinline!max! &
$p \in [\text{min},\text{max})$ lognormal with given $\mu$ and $\sigma$ \\
%
\lstinline!linear! & \lstinline!a!, \lstinline!c! &
\begin{equation*}
p(d) = c + a d
\end{equation*}\\
%
\rowcolor{lstcolor}
\lstinline!exponential! & \lstinline!a!, \lstinline!c!, \lstinline!tau! &
\begin{equation*}
p(d) = c + a e^{-\frac{d}{\tau}}
\end{equation*}\\
%
\lstinline!gaussian! & \lstinline!p_center!, \lstinline!sigma!, \lstinline!mean!,
\lstinline!c! &
\begin{equation*}
p(d) = c + p_{\text{center}}  e^{-\frac{(d-\mu)^2}{2\sigma^2}}
\end{equation*}\\
%
\rowcolor{lstcolor}
\lstinline!gaussian2D! & \lstinline!p_center!, \lstinline!sigma_x!, 
\lstinline!sigma_y!, \lstinline!mean_x!, \lstinline!mean_y!,\lstinline!rho!
\lstinline!c! &
\begin{equation*}
p(d) = c + p_{\text{center}}
e^{-\frac{\frac{(d_x-\mu_x)^2}{\sigma_x^2}-\frac{(d_y-\mu_y)^2}{\sigma_y^2}
          +2\rho\frac{(d_x-\mu_x)(d_y-\mu_y)}{\sigma_x\sigma_y}}{2(1-\rho^2)}}
\end{equation*}\\
\end{tabularx}
\caption[Kernel functions]{Kernel functions currently available in the
  Topology module. $d$ is the distance and $(d_x,d_y)$ the
  displacement.}
\label{tab:kernels}
\end{table}

Several examples follow. They are illustrated in Fig.~\ref{fig:conn4}.
\begin{description}
\item[Constant\index{constant kernel}] The simplest kernel is a fixed connection
  probability:
\lstinputlisting[linerange=conn4cp-end]{user_manual_scripts/connections.py}
\item[Gaussian\index{Gaussian kernel}] This kernel is distance dependent. In the example,
  connection probability is 1 for $d=0$ and falls off with a
  ``standard deviation'' of $\sigma=1$:
\lstinputlisting[linerange=conn4g-end]{user_manual_scripts/connections.py} 
\item[Excentric Gaussian\index{excentric kernel}] In this example, both kernel and mask have
  been moved using anchors:
\lstinputlisting[linerange=conn4gx-end]{user_manual_scripts/connections.py} 
Note that the anchor for the kernel is specified inside the dictionary
containing the parameters for the Gaussian.
\item[Cut-off Gaussian\index{cut-off kernel}] In this example, all probabilties less than
  $0.5$ are set to zero:
\lstinputlisting[linerange=conn4cut-end]{user_manual_scripts/connections.py} 
\item[2D Gaussian\index{2D Gaussian kernel}] We conclude with an
  example using a two-dimensional Gaussian, i.e., a Gaussian with
  different widths in $x$- and $y-$ directions. This kernel depends on
  displacement, not only on distance:
\lstinputlisting[linerange=conn42d-end]{user_manual_scripts/connections.py} 
\end{description}
\scriptfig{conn4}{0.9}{Kernel functions}%
{Illustration of various kernel functions. Top left: constant kernel,
  $p=0.5$. Top center: Gaussian kernel, green dashed lines show
  $\sigma$, $2\sigma$, $3\sigma$. Top right: Same Gaussian kernel
  anchored at $(1.5,1.5)$. Bottom left: Same Gaussian kernel, but all
  $p<0.5$ treated as $p=0$. Bottom center: 2D-Gaussian.}
Note that for pool layers with periodic boundary conditions, Topology
always uses the shortest possible displacement vector from driver
to pool neuron as argument to the kernel function.


\section{Weights and delays}\label{sec:conn_wd}

The functions presented in Table~\ref{tab:kernels} can also be used to
specify distance-dependent or randomized weights and delays\index{distance-dependent
  weight}\index{distance-dependent delay}\index{randomized
  delay}\index{randomized weight}for the connections
created by \lstinline!ConnectLayers!.

Figure~\ref{fig:conn5} illustrates weights and delays generated using
these functions with the following code examples. All examples use a
``layer'' of 51 nodes placed on a line; the line is centered about
$(25,0)$, so that the leftmost node has coordinates $(0,0)$. The distance between
neighboring elements is 1. The mask is rectangular, spans the
entire layer and is centered about the driver node.
\begin{description}
\item[Linear example] \rule{0mm}{0mm}\\
\lstinputlisting[linerange=conn5lin-end]{user_manual_scripts/connections.py}
Results are shown in the top panel of Fig.~\ref{fig:conn5}.
Connection weights and delays are shown for the leftmost neuron as
driver. Weights drop linearly from $1$. From the node at $(20,0)$ on,
the cutoff sets weights to 0. There are no connections to nodes beyond
$(25,0)$ since as the mask extends only 25 units to the right of the
driver. Delays increase in a stepwise linear fashion\index{delays, stepwise}, as NEST requires
delays to be multiples of the simulation resolution. 
\item[Linear example with periodic boundary conditions\index{periodic
    boundary cond.}]\rule{0mm}{0mm}\\
\lstinputlisting[linerange=conn5linpbc-end]{user_manual_scripts/connections.py}
Results are shown in the middle panel of Fig.~\ref{fig:conn5}.
This example is identical to the previous,
  except that the (pool) layer has periodic boundary
  conditions. Therefore, the left half of the mask about the node at
  $(0,0)$ wraps back to the right half of the layer and that node
  connects to all nodes in the layer.
\item[Various functions]\rule{0mm}{0mm}\\
\lstinputlisting[linerange=conn5exp-end]{user_manual_scripts/connections.py}
\lstinputlisting[linerange=conn5gauss-end]{user_manual_scripts/connections.py}
Results are shown in the bottom panel of Fig.~\ref{fig:conn5}. It
shows linear, exponential and Gaussian weight functions for the node
at $(25,0)$.
\item[Randomized weights and delays] \rule{0mm}{0mm}\\
\lstinputlisting[linerange=conn5uniform-end]{user_manual_scripts/connections.py}
By using the \lstinline!'uniform'! function for weights or delays, one
can obtain randomized values for weights and delays, as shown by the
red circles in the bottom panel of Fig.~\ref{fig:conn5}. Weights and
delays can currently only be randomized with uniform distribution.
\end{description}
\scriptfig{conn5}{0.9}{Distance-dependent and randomized weights and
  delays}%
{Distance-dependent and randomized weights and delays. See text for details.}


\section{Periodic boundary conditions}\label{sec:conn_pbc}

Connections between layers with periodic boundary
conditions\index{periodic boundary cond.} are based
on the following principles:
\begin{itemize}
\item Periodic boundary conditions are always applied in the pool
  layer. It is irrelevant whether the driver layer has periodic
  boundary conditions or not.
\item By default, Topology does not accept masks that are wider than
  the pool layer when using periodic boundary conditions. Otherwise,
  one pool node could appear as multiple targets to the same driver
  node as the masks wraps several times around the layer. For layers
  with different extents in $x$- and $y$-directions this means that
  the maximum layer size is determined by the smaller extension.
\item Kernel, weight and delay functions always consider the shortest
  distance (displacement) between driver and pool node.
\end{itemize}
In most physical systems simulated using periodic boundary conditions,
interactions between entities are short-range. Periodic boundary
conditions are well-defined in such cases. In neuronal network models
with long-range interactions, periodic boundary conditions may not
make sense. In general, we recommend to use periodic boundary
conditions only when connection masks are significantly smaller than
the layers they are applied to.

\emph{Important changes upon NEST 2.0}: 
\begin{itemize}
\item Prior to NEST~2.0, oversized
masks were not prohibited by default and you may have created networks
with oversized masks by accident. You will now get a NEST error
message in this case. You can force Topology to accept oversized
masks\index{oversized mask}
by adding \lstinline!'allow_oversized_mask': True! to the connection
dictionary. Be sure to inspect the results, e.g., using
\lstinline!DumpLayerConnections!.
\item Distance- and displacement-dependent kernel, weight and delay
  functions did not handle periodic boundary conditions correctly
  prior to NEST~2.0.
\end{itemize}


\section{Prescribed number of connections}\label{sec:prescribed_numbers}

We have so far described how to connect layers by either connecting to
all nodes inside the mask or by considering each pool node in turn and
connecting it according to a given probability function. In both
cases, the number of connections generated depends on mask and kernel.

Many neuron models in the literature, in contrast, prescribe a certain
\emph{fan in}\index{fan in} (number of incoming connections) or
\emph{fan out}\index{fan out} (number of outgoing connections) for
each node. You can achieve this in Topology by prescribing the number
of connections\index{prescribed number of connections} for each driver
node. For convergent connections, where the target layer is the driver
layer, you thus achieve a constant fan in, for divergent connections a
constant fan out.

Connection generation now proceeds in a different way than before:
\begin{enumerate}
\item For each driver node, \lstinline!ConnectLayers! randomly selects
  a node from the mask region in the pool layer, and creates a
  connection with the probability prescribed by the kernel. This is
  repeated until the requested number of connections has been created.
\item Thus, if all nodes in the mask shall be connected with equal
  probability, you should not specify any kernel. 
\item If you specify a non-uniform kernel (e.g., Gaussian, linear,
  exponential), the connections will be distributed within the mask
  with the spatial profile given by the kernel.
\item If you prohibit multapses\index{multapse} (cf Sec.~\ref{sec:terminology}) and
  prescribe a number of connections greater than the number of pool nodes
  in the mask, \lstinline!ConnectLayers! may get stuck in an infinte
  loop and NEST will hang\index{infinite loop}\index{hang}. Keep in
  mind that the number of nodes within the mask may vary considerably
  for free layers with randomly placed nodes. 
\end{enumerate}

The following code generates a network of 1000 randomly placed nodes
and connects them with a fixed fan out of 50 outgoing connections per
node distributed with a profile linearly decaying from unit
probability to zero probability at distance $0.5$. Multiple
connections (multapses) between pairs of nodes are allowed,
self-connections (autapses) prohibited. The probability of finding a
connection at a certain distance is then given by the product of the
probabilities for finding nodes at a certain distance with the kernel
value for this distance. For the kernel and parameter values below we have
\begin{equation}
p_{\text{conn}}(d) = \frac{12}{\pi} \times 2\pi r \times (1-2r)
 = 24 r (1-2r) \qquad \text{for} \quad 0\le r < \frac{1}{2}\;.
\label{eq:ptheo}
\end{equation}
 The resulting
distribution of distances between connected nodes is shown in
Fig.~\ref{fig:conn6}.
\lstinputlisting[linerange=conn6-end]{user_manual_scripts/connections.py}
\scriptfig{conn6}{0.5}{Distribution of connection distances}%
{Distribution of distances between source and target for a network of
  1000 randomly placed nodes, a fixed fan out of 50 connections and a
  connection probability decaying linerarly from 1 to 0 at
  $d=0.5$. The red line is the expected distribution from Eq.~\ref{eq:ptheo}.}

Functions determining weight and delay as function of
distance/displacement work in just the same way as before when the
number of connections is prescribed.

\section{Connecting composite layers}\label{sec:conn_composite}

Connections between layers with composite elements\index{composite element} are based on the
following principles:
\begin{itemize}
\item All nodes within a composite element have the same
  coordinates\index{coordinates}, the coordinates of the element.
\item All nodes within a composite element are treated equally. If,
  e.g., an element of the pool layer contains three nodes and
  connection probability is 1, then connections with all three nodes
  will be created. For probabilistic connection schemes, each of the
  three nodes will be considered individually.
\item If only nodes of a given model\index{model} within each element
  shall be considered as sources or targets then this can be achieved
  by adding a \lstinline!'sources'! or \lstinline!'targets'! entry to
  the connection dictionary, which speficies the model to connect.
\end{itemize}
This is exemplified by the following code, which connects pyramidal
cells (\lstinline!pyr!) to interneurons (\lstinline!in!) with a
circular mask and uniform probablity and interneurons to pyramidal
cells with a rectangular mask unit probability.
\lstinputlisting[linerange=conn7-end]{user_manual_scripts/connections.py}


\section{Synapse models and properties}\label{sec:conn_synapse}

By default, \lstinline!ConnectLayers! creates connections using the
default synapse model\index{synapse model} in NEST,
\lstinline!static_synapse!. You can specify a different model by
adding a \lstinline!'synapse_model'! entry to the connection
dictionary, as in this example:
\lstinputlisting[linerange=conn8-end]{user_manual_scripts/connections.py}
You have to use synapse models if you want to set, e.g., the receptor
type of connections or parameters for plastic synapse models. These
can not be set in distance-dependent ways at present.


\chapter{Inspecting Layers}\label{sec:inspection}

We strongly recommend that you inspect the layers created by Topology
to be sure that node placement and connectivity indeed turned out as
expected. In this chapter, we describe some functions that NEST and
Topology provide to query and visualize networks, layers, and
connectivity.

\section{Query functions}\label{sec:queries}

The following table presents some query functions provided by NEST
(\lstinline!nest.!) and Topology (\lstinline!tp.!). For detailed
information about these functions, please see the online Python and
SLI documentation. 

\renewcommand{\arraystretch}{1.2}
\begin{longtable}{lp{0.6\linewidth}}
  \lstinline!nest.PrintNetwork()! & Print structure of network or
  subnet
  from NEST perspective. \\
  \lstinline!nest.GetConnections()! & Retrieve connections
  (all or for a given source or target); see also
  \url{http://www.nest-initiative.org/index.php/Connection_Management}. \\
  \lstinline!nest.GetNodes()! & Applied to a layer, returns GIDs of
  the layer elements. For simple layers, these are the actual model
  neurons,
  for composite layers the top-level subnets.\\
  \lstinline!nest.GetLeaves()! & Applied to a layer, returns GIDs of
  all
  actual model neurons, ignoring subnets.\\
  \lstinline!tp.GetPosition()!  &
  Return the spatial locations of nodes.\\
  \lstinline!tp.GetLayer()!  &
  Return the layer to which nodes belong.\\
  \lstinline!tp.GetElement()!  &
  Return the node(s) at the location(s) in the given grid-based layer(s).\\
  \lstinline!tp.GetTargetNodes()!  &
  Obtain targets of a list of sources in a given target layer.\\
  \lstinline!tp.GetTargetPositions()!  &
  Obtain positions of targets of a list of sources in a given target layer.\\
  \lstinline!tp.FindNearestElement()!  & Return the node(s) closest to
  the location(s) in the given
  layer(s).\\
  \lstinline!tp.FindCenterElement()!  &
  Return GID(s) of node closest to center of layer(s).\\
  \lstinline!tp.Displacement()!  & Obtain vector of lateral
  displacement between nodes, taking
  periodic boundary conditions into account. \\
  \lstinline!tp.Distance()!  & Obtain vector of lateral distances
  between nodes, taking periodic
  boundary conditions into account.\\
  \lstinline!tp.DumpLayerNodes()!  &
  Write layer element positions to file.\\
  \lstinline!tp.DumpLayerConnections()!  & Write connectivity
  information to file. This function may be very useful to check that
  Topology created the correct connection structure.
\end{longtable}

\section{Visualization functions}\label{sec:visualize}

Topology provides three functions to visualize networks:
\begin{longtable}{lp{0.6\linewidth}}
\lstinline!PlotLayer()! 
&
    Plot nodes in a layer.\\
\lstinline!PlotTargets()!
&
    Plot all targets of a node in a given layer.\\
\lstinline!PlotKernel()!
&
    Add indication of mask and kernel to plot of layer. It
    does \emph{not} wrap masks and kernels with respect to periodic
    boundary conditions. This function
    is usually called by \lstinline!PlotTargets!.
\end{longtable}

\scriptfig{vislayer}{0.7}{Example of layer visualization.}%
{$21\times21$ grid with divergent Gaussian projections onto itself. 
Blue circles mark layer elements, red circles connection targets of
the center neuron (marked by large light-red circle). The large red
circle is the mask, the dashed green lines mark $\sigma$, $2\sigma$
and $3\sigma$ of the Gaussian kernel.}

The following code shows a practical example: A $21\times21$ network
which connects to itself with divegent Gaussian connections. The
resulting graphics is shown in Fig.~\ref{fig:vislayer}. All
elements and the targets of the center neuron are shown, as well as
mask and kernel.
%
\lstinputlisting[linerange=vislayer-end]{user_manual_scripts/layers.py}


\chapter{Adding topology kernels and masks}\label{ch:extending}

\index{adding kernels and masks}
This chapter will show examples of how to extend the topology module by
adding custom kernel functions and masks. Some knowledge of the C++
programming language is needed for this. The functions will be added as a
part of an extension module which is dynamically loaded into NEST. For more
information on writing an extension module, see the section titled
\href{http://www.nest-initiative.org/index.php/Writing_an_Extension_Module}{``Writing an Extension Module''}
in the NEST Developer Manual. The basic steps required to get started are:
\begin{enumerate}
\item From the NEST source directory, copy directory examples/MyModule to
  somewhere outside the NEST source, build or install directories.
\item Change to the new location of MyModule and prepare by issuing
  \lstinline!./bootstrap.sh!
\item Leave MyModule and create a build directory for it, e.g., mmb next to
  it
\begin{lstlisting}[language=bash]
cd ..
mkdir mmb
cd mmb
\end{lstlisting}
\item Configure. The configure process uses the script \lstinline!nest-config!
  to find out where NEST is installed, where the source code resides, and
  which compiler options were used for compiling NEST. If
  \lstinline!nest-config! is not in your path, you need to provided it
  explicitly like this
\begin{lstlisting}[language=bash]
../MyModule/configure --with-nest=${NEST_INSTALL_DIR}/bin/nest-config
\end{lstlisting}
\item MyModule will then be installed to \lstinline!${NEST_INSTALL_DIR}!. This
  ensures that NEST will be able to find initializing SLI files for the
  module.  You should not use the \lstinline!--prefix! to select a different
  installation destination. If you do, you must make sure to use addpath in
  SLI before loading the module to ensure that NEST will find the SLI
  initialization file for your module.
\item Compile.
\begin{lstlisting}[language=bash]
make
make install
\end{lstlisting}
The previous command installed MyModule to the NEST installation directory, including help files generated from the source code. 
\end{enumerate}

\section{Adding kernel functions}

As an example, we will add a kernel\index{kernel} function called \lstinline!'affine2d'!,
which will be linear (actually affine) in the displacement of the nodes, on
the form
\begin{equation*}
  p(d) = a d_x + b d_y + c.
\end{equation*}
The kernel functions are provided by C++ classes subclassed from
\lstinline!nest::Parameter!. To enable subclassing, add the following lines
at the top of the file \lstinline!mymodule.h!:
\begin{lstlisting}[language=C++]
#include "topologymodule.h"
#include "parameter.h"
\end{lstlisting}
Then, add the class definition, e.g. near the bottom of the file before the
brace closing the namespace \lstinline!mynest!:
\begin{lstlisting}[language=C++]
  class Affine2DParameter: public nest::Parameter
  {
  public:
    Affine2DParameter(const DictionaryDatum& d):
      Parameter(d),
      a_(1.0),
      b_(1.0),
      c_(0.0)
      {
        updateValue<double>(d, "a", a_);
        updateValue<double>(d, "b", b_);
        updateValue<double>(d, "c", c_);
      }

    double raw_value(const nest::Position<2>& disp,
                     librandom::RngPtr&) const
      {
        return a_*disp[0] + b_*disp[1] + c_;
      }

    nest::Parameter * clone() const
      { return new Affine2DParameter(*this); }

  private:
    double a_, b_, c_;
  };
\end{lstlisting}
The class contains a constructor, which reads the value of the parameters
$a$, $b$ and $c$ from the dictionary provided by the user. The function
\lstinline!updateValue! will do nothing if the given key is not in the
dictionary, and the default values $a=b=1,\ c=0$ will be used.

The overridden method \lstinline!raw_value()! will return the actual value
of the kernel function for the displacement given as the first argument,
which is of type \lstinline!nest::Position<2>!. The template argument 2
refers to a 2-dimensional position. You can also implement a method taking
a \lstinline!nest::Position<3>! as the first argument if you want to
support 3-dimensional layers. The second argument, a random number
generator, is not used in this example.

The class also needs to have a \lstinline!clone()! method, which will return
a dynamically allocated copy of the object. We use the (default) copy
constructor to implement this.

To make the custom function available to the Topology module, you need to
register the class you have provided. To do this, add the line
\begin{lstlisting}[language=C++]
nest::TopologyModule::register_parameter<Affine2DParameter>("affine2d");
\end{lstlisting}
to the function \lstinline!MyModule::init()! in the file
\lstinline!mymodule.cpp!. Now compile and install the module by issuing
\begin{lstlisting}[language=bash]
make
make install
\end{lstlisting}
To use the function, the module must be loaded into NEST using
\lstinline!nest.Install()!. Then, the function is
available to be used in connections, e.g.
\begin{lstlisting}
nest.Install('mymodule')
l = tp.CreateLayer({'rows': 11, 'columns': 11, 'extent': [1.,1.],
                        'elements': 'iaf_neuron'})
tp.ConnectLayers(l,l,{'connection_type': 'convergent',
            'mask': {'circular': {'radius': 0.5}},
            'kernel': {'affine2d': {'a': 1.0, 'b': 2.0, 'c': 0.5}}})
\end{lstlisting}

\section{Adding masks}

The process of adding a mask\index{mask} is similar to that of adding a kernel
function. A subclass of \lstinline!nest::Mask<D>! must be defined, where
\lstinline!D! is the dimension (2 or 3). In this case we will define a
2-dimensional elliptic mask by creating a class called
\lstinline!EllipticMask!. First, we must include another header file:
\begin{lstlisting}[language=C++]
#include "mask.h"
\end{lstlisting}
Compared to the \lstinline!Parameter! class discussed in the previous
section, the \lstinline!Mask! class has a few more methods that must be
overridden:
\begin{lstlisting}[language=C++]
  class EllipticMask : public nest::Mask<2>
  {
  public:
    EllipticMask(const DictionaryDatum& d):
      rx_(1.0), ry_(1.0)
      {
        updateValue<double>(d, "r_x", rx_);
        updateValue<double>(d, "r_y", ry_);
      }

    using Mask<2>::inside;

    // returns true if point is inside the ellipse
    bool inside(const nest::Position<2> &p) const
      { return p[0]*p[0]/rx_/rx_ + p[1]*p[1]/ry_/ry_ <= 1.0; }

    // returns true if the whole box is inside the ellipse
    bool inside(const nest::Box<2> &b) const
      {
        nest::Position<2> p = b.lower_left;

        // Test if all corners are inside mask
        if (not inside(p)) return false;       // (0,0)
        p[0] = b.upper_right[0];
        if (not inside(p)) return false;       // (0,1)
        p[1] = b.upper_right[1];
        if (not inside(p)) return false;       // (1,1)
        p[0] = b.lower_left[0];
        if (not inside(p)) return false;       // (1,0)

        return true;
      }

    // returns bounding box of ellipse
    nest::Box<2> get_bbox() const
      {
        nest::Position<2> ll(-rx_,-ry_);
        nest::Position<2> ur(rx_,ry_);
        return nest::Box<2>(ll,ur);
      }

    nest::Mask<2> * clone() const
      { return new EllipticMask(*this); }

  protected:
    double_t rx_, ry_;
  };
\end{lstlisting}
The overridden methods include a test if a point is inside the mask, and
for efficiency reasons also a test if a box is fully inside the mask. We
implement the latter by testing if all the corners are inside, since our
elliptic mask is convex. We must also define a function which returns a
bounding box for the mask, i.e. a box completely surrounding the mask.

Similar to kernel functions, the mask class must be registered with the
topology module, and this is done by adding a line to the function
\lstinline!MyModule::init()! in the file \lstinline!mymodule.cpp!:
\begin{lstlisting}[language=C++]
    nest::TopologyModule::register_mask<EllipticMask>("elliptic");
\end{lstlisting}
After compiling and installing the module, the mask is available to be used
in connections, e.g.
\begin{lstlisting}
nest.Install('mymodule')
l = tp.CreateLayer({'rows': 11, 'columns': 11, 'extent': [1.,1.],
                        'elements': 'iaf_neuron'})
tp.ConnectLayers(l,l,{'connection_type': 'convergent',
            'mask': {'elliptic': {'r_x': 0.5, 'r_y': 0.25}}})
\end{lstlisting}


\chapter{Changes from Topology 2.0 to 2.2}\label{sec:changes}

This is a short summary of the most important changes in the Topology
Module from NEST version 2.0 to 2.2.

\begin{itemize}
\item Nested layers are no longer supported.
\item Subnets are no longer used inside composite layers. A call to
  GetElement for a composite layer will now return a list of GIDs for the
  nodes at the position rather than a single subnet GID.
\item Positions in layers may now be 3-dimensional.
\item The functions GetPosition, Displacement and Distance now only works
  for nodes local to the current MPI process, if used in a MPI-parallel
  simulation.
\item It is now possible to add kernel functions and masks to the Topology
  module through an extension module. Please see Chapter~\ref{ch:extending}
  for examples.
\end{itemize}

\chapter{Changes from Topology 1.9 to 2.0}\label{sec:changes2}

This is a short summary of the most important changes in the NEST
Topology Module from the 1.9-xxxx to the 2.0 version.

\begin{itemize}
\item ConnectLayer is now called ConnectLayers
\item Several other functions changed names, and there are many new
  functions. Please see Ch.~\ref{sec:inspection} for an overview.
\item All nest.topology functions now require lists of GIDs as input,
  not "naked" GIDs
\item There are a number of new functions in nest.topology, I tried to
  write good doc strings for them
\item For grid based layers (ie those with /rows and /columns), we
  have changed the definition of "extent": Previously, nodes were
  placed on the edges of the extent, so if you had an extend of 2 (in
  x-direction) and 3 nodes, these had x-coordinates -1, 0, 1. The grid
  constant was extent/(num\_nodes - 1).

  Now, we define the grid constant as extent/num\_nodes, center the
  nodes about 0 and thus add a space of half a grid constant between
  the outermost nodes and the boundary of the extent. If you want
  three nodes at -1,0,1 you thus have to set the extent to 3, i.e.,
  stretching from -1.5 to 1.5.

  The main reason for this change was that topology always added this
  padding silently when you used periodic boundary conditions
  (otherwise, neurons are the left and right edge would have been in
  identical locations, not what one wants).
\item The semantics of the \lstinline!anchor! entry for kernel
  functions has changed: the anchor now specifies the center of the
  probability distribution relative to the driver node. This is
  consistent with the semantics for free masks, see
  Sec.~\ref{sec:conn_masks} and \ref{sec:conn_kernels}.
\item Functions computing connection probabilities, weights and delays
  as functions of distance between source and target nodes now handle
  periodic boudary conditions correctly.
\item Masks with a diameter larger than the diameter of the layer they
  are applied to are now prohibited by default. This avoids multiple
  connections when masks overwrap.
\end{itemize}

\bibliographystyle{plainnat}
\bibliography{../../extras/bibliography/nest.bib}
%  \addcontentsline{toc}{chapter}{Bibliography}

\listoffigures % \addcontentsline{toc}{chapter}{List of Figures}
\listoftables  %\addcontentsline{toc}{chapter}{List of Tables}

\printindex  
%\addcontentsline{toc}{chapter}{Index}

\end{document}