Merge pull request #608 from janhahne/gap_junction_docu

Added gap junction Markdown documentation

extras/userdoc/md/documentation/documentation.md

@@ -14,6 +14,7 @@
 -   [Parallel Computing](parallel-computing.md)
 -   [Scheduling and simulation flow](scheduling-and-simulation-flow.md)
 -   [Simulations with precise spike times](simulations-with-precise-spike-times.md)
+-   [Simulations with gap junctions](simulations-with-gap-junctions.md)
 -   [Using NEST with MUSIC](using-nest-with-music.md)
 -   [Using NEST with the SLI interpreter](an-introduction-to-sli.md)
 -   [NEST/SLI Quick Reference](quickref.md)
@@ -56,6 +57,8 @@
 -   [brunel_alpha_numpy](py_samples/brunel_alpha_numpy.md)
 -   [if_curve](py_samples/if_curve.md)
 -   [sinusoidal_gamma_generator](py_samples/sinusoidal_gamma_generator.md)
+-   [gap_junctions_two_neurons](py_samples/gap_junctions_two_neurons.md)
+-   [gap_junctions_inhibitory_network](py_samples/gap_junctions_inhibitory_network.md)
 
 ## Further Reading
 

extras/userdoc/md/documentation/simulations-with-gap-junctions.md

@@ -0,0 +1,107 @@
+# Simulations with gap junctions
+
+**Note:** This documentation describes the usage of gap junctions in NEST 2.12.
+A documentation for NEST 2.10 can be found in
+[Hahne et al. 2016](http://link.springer.com/chapter/10.1007/978-3-319-50862-7_4).
+It is however recommended to use NEST 2.12 (or later), 
+due to several improvements in terms of usability. 
+
+## Introduction
+
+Simulations with gap junctions are supported by the Hodgin-Huxley neuron model `hh_psc_alpha_gap`.
+The synapse model to create a gap-junction connection is named `gap_junction`. 
+Unlike chemical synapses gap junctions are bidirectional connections. 
+In order to create **one** accurate gap-junction connection 
+**two** NEST connections are required:
+For each created connection a second connection with the exact same parameters 
+in the opposite direction is required.
+NEST provides the possibility to create both connections with a single call to `nest.Connect`
+via the `make_symmetric` flag (default value: `False`) of the connection dictionary:
+
+```python
+import nest
+
+a = nest.Create('hh_psc_alpha_gap')
+b = nest.Create('hh_psc_alpha_gap')
+# Create gap junction between neurons a and b
+nest.Connect(a, b, {'rule': 'one_to_one', 'make_symmetric': True}, 
+                   {'model': 'gap_junction', 'weight': 0.5})
+```
+In this case the reverse connection is created internally. In order to prevent the 
+creation of incomplete or non-symmetrical gap junctions the creation of gap junctions 
+is restricted to
+
+- `one_to_one` connections with `'make_symmetric': True`
+- `all_to_all` connections with equal source and target populations and default or scalar parameters 
+
+## Create random connections
+
+NEST random connection rules like `fixed_total_number`, `fixed_indegree` etc. cannot be 
+employed for the creation of gap junctions.
+Therefore random connections have to be created on the Python level with e.g. the `random` 
+module of the Python Standard Library:
+
+```python
+import nest
+import random
+import numpy as np
+
+# total number of neurons
+n_neuron = 100
+
+# total number of gap junctions
+n_gap_junction = 3000
+
+n = nest.Create('hh_psc_alpha_gap', n_neuron)
+
+random.seed(0)
+
+# draw n_gap_junction pairs of random samples from the list of all
+# neurons and reshaped data into two corresponding lists of neurons
+m = np.transpose(
+    [random.sample(n, 2) for _ in range(n_gap_junction)])
+
+# connect obtained lists of neurons both ways
+nest.Connect(m[0], m[1],
+             {'rule': 'one_to_one', 'make_symmetric': True},
+             {'model': 'gap_junction', 'weight': 0.5})
+```
+As each gap junction contributes to the total number of gap-junction 
+connections of two neurons, it is hardly possible to create 
+networks with a fixed number of gap junctions per neuron. 
+With the above script it is however possible to control the approximate 
+number of gap junctions per neuron. E.g. if one desires 
+`gap_per_neuron = 60` the total number of gap junctions should be 
+chosen as `n_gap_junction = n_neuron * gap_per_neuron / 2`.
+
+**Note:** The (necessary) drawback of creating the random connections 
+on the Python level is the serialization of the connection procedure in 
+terms of computation time and memory in distributed simulations. 
+Each compute node participating in the simulation needs to draw the identical
+full set of random numbers and temporarily represent the total connectivity 
+in variable `m`.
+Therefore it is advisable to use the internal random connection rules of NEST
+for the creation of connections whenever possible. 
+For more details see
+[Hahne et al. 2016](http://link.springer.com/chapter/10.1007/978-3-319-50862-7_4).
+
+
+## Adjust settings of iterative solution scheme
+For simulations with gap junctions NEST uses an iterative solution scheme 
+based on a numerical method called Jacobi waveform relaxation.
+The default settings of the iterative method are based on numerical results, 
+benchmarks and previous experience with gap-junction simulations 
+(see [Hahne et al. 2015](http://journal.frontiersin.org/article/10.3389/fninf.2015.00022/full)) 
+and should only be changed with proper knowledge of the method.
+In general the following parameters can be set via kernel parameters:
+
+```python
+nest.SetKernelStatus({'use_wfr': True,
+                      'wfr_comm_interval': 1.0,
+                      'wfr_tol': 0.0001,
+                      'wfr_max_iterations': 15,
+                      'wfr_interpolation_order': 3})
+```
+
+For a detailed description of the parameters and their function 
+see ([Hahne et al. 2016](https://arxiv.org/abs/1610.09990), Table 2).

pynest/examples/gap_junctions_inhibitory_network.py

@@ -20,6 +20,8 @@
 # along with NEST.  If not, see <http://www.gnu.org/licenses/>.
 
 """
+Gap Junctions: Inhibitory network example
+------------------
 This is the inhibitory network used as test case 2 (see figure 9 and 10) in
 
     Hahne, J., Helias, M., Kunkel, S., Igarashi, J.,
@@ -54,9 +56,8 @@
 stepsize = 0.05
 simtime = 501.
 
-"""
-Set gap weight here
-"""
+
+#Set gap weight here
 gap_weight = 0.32
 
 random.seed(1)

pynest/examples/gap_junctions_two_neurons.py

@@ -20,6 +20,8 @@
 # along with NEST.  If not, see <http://www.gnu.org/licenses/>.
 
 """
+Gap Junctions: Two neurons example
+------------------
 This is a simple example of two hh_psc_alpha_gap neurons connected
 by a gap-junction. Please note that gap junctions are two-way connections:
 In order to create an accurate gap-junction connection between two
@@ -55,14 +57,13 @@
 nest.Connect(vm, neuron, 'all_to_all')
 
 """
-Use 'all_to_all' to connect neurons.
-This is equivalent to:
-nest.Connect([neuron[0]],[neuron[1]],
-             {'rule': 'one_to_one', 'make_symmetric': True},
-             {'model': 'gap_junction', 'weight': 0.5})
+Use the 'make_symmetric' flag to connect
+neuron[0] -> neuron[1] and neuron[1] -> neuron[0]
+with a single call to nest.Connect in order to create
+an accurate gap junction between both neurons
 """
-nest.Connect(neuron, neuron,
-             {'rule': 'all_to_all', 'autapses': False},
+nest.Connect([neuron[0]], [neuron[1]],
+             {'rule': 'one_to_one', 'make_symmetric': True},
              {'model': 'gap_junction', 'weight': 0.5})
 
 nest.Simulate(351.)