Merge pull request #3279 from jessica-mitchell/fix-gapjunctions

Update documentation on Gap Junctions

doc/htmldoc/synapses/simulations_with_gap_junctions.rst

@@ -3,14 +3,6 @@
 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 Hodgkin-Huxley
 neuron model ``hh_psc_alpha_gap``. The synapse model to create a
@@ -27,17 +19,19 @@ possibility to create both connections with a single call to
 
     import nest
 
-    a = nest.Create('hh_psc_alpha_gap')
-    b = nest.Create('hh_psc_alpha_gap')
+    a = nest.Create("hh_psc_alpha_gap")
+    b = nest.Create("hh_psc_alpha_gap")
+    gap_weight = 0.5
+    syn_dict = {"synapse_model": "gap_junction", "weight": gap_weight}
+    conn_dict = {"rule": "one_to_one", "make_symmetric": True}
     # 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})
+    nest.Connect(a, b, conn_dict, syn_dict)
 
 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``
+-  ``one_to_one`` connections with ``"make_symmetric": True``
 -  ``all_to_all`` connections with equal source and target populations
    and default or scalar parameters
 
@@ -61,25 +55,29 @@ level with e.g. the ``random`` module of the Python Standard Library:
     # total number of gap junctions
     n_gap_junction = 3000
 
-    n = nest.Create('hh_psc_alpha_gap', n_neuron)
+    gap_weight = 0.5
+    n = nest.Create("hh_psc_alpha_gap", n_neuron)
+    n_list = n.tolist()
 
     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)])
+    # draw n_gap_junction pairs of random samples
+    connections = np.random.choice(n_list, [n_gap_junction, 2])
+
+    for source_node_id, target_node_id in connections:
+        nest.Connect(
+            nest.NodeCollection([source_node_id]),
+            nest.NodeCollection([target_node_id]),
+            {"rule": "one_to_one", "make_symmetric": True},
+            {"synapse_model": "gap_junction", "weight": gap_weight},
+            )
 
-    # 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
+junctions per neuron. For example, 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``.
 
@@ -92,18 +90,16 @@ total number of gap junctions should be chosen as
   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>`__.
+  whenever possible. For more details see Hahne et al. [1]_
 
 Adjust settings of iterative solution scheme
 --------------------------------------------
 
-For simulations with gap junctions NEST uses an iterative solution
+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>`__)
+results, benchmarks, and previous experience with gap-junction
+simulations [2]_.
 and should only be changed with proper knowledge of the method. In
 general the following parameters can be set via kernel parameters:
 
@@ -116,4 +112,27 @@ general the following parameters can be set via kernel parameters:
     nest.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).
+[3]_, Table 2.
+
+.. seealso::
+
+   * :doc:`/auto_examples/gap_junctions_inhibitory_network`
+   * :doc:`/auto_examples/gap_junctions_two_neurons`
+
+References
+----------
+
+.. [1] Hahne J, et al. 2016. Including Gap Junctions into Distributed Neuronal Network Simulations.
+       In: Amunts K, Grandinetti L, Lippert T, Petkov N. (eds) Brain-Inspired Computing.
+       BrainComp 2015. Lecture  Notes in Computer Science(), vol 10087. Springer, Cham.
+       https://doi.org/10.1007/978-3-319-50862-7_4
+
+.. [2] Hahne J, Helias M, Kunkel S, Igarashi J, Bolten M, Frommer A, Diesmann M 2015.
+       A unified framework for spiking and gap-junction interactions in distributed neuronal network simulations.
+       Frontiers in Neuroinformatics. 9
+       https://www.frontiersin.org/journals/neuroinformatics/articles/10.3389/fninf.2015.00022
+
+.. [3] Hahne J, Dahmen D , Schuecker J, Frommer A, Bolten M, Helias M, Diesmann M. 2017.
+       Integration of Continuous-Time Dynamics in a Spiking Neural Network Simulator.
+       Frontiers in Neuroinformatics. 11.
+       https://www.frontiersin.org/journals/neuroinformatics/articles/10.3389/fninf.2017.00034