Merge pull request #3172 from jhnnsnk/doc_connconcepts

Align documentation of connection management with connectivity concepts publication (v2)

doc/htmldoc/get-started_index.rst

@@ -61,9 +61,10 @@ Next steps: Create your own network model
 
          |random| Connect neurons, synapses, and devices
          ^^^
-
-         * :ref:`connection_management`: A guide to building connections in NEST
+         * :ref:`connectivity_concepts`: A guide to define network connectivity in NEST
          * :ref:`spatial_networks`: A deep dive into building 2D and 3D networks
+         * :ref:`connection_generator`: Using an external library for generating connections
+         * :ref:`synapse_spec`: Details on parameterizing synapses
 
     .. grid-item-card::
          :class-header: sd-d-flex-row sd-align-minor-center sd-bg-info sd-text-white

doc/htmldoc/installation/cmake_options.rst

@@ -313,7 +313,7 @@ follwing switch for the invocation of ``cmake``. It expects either
     -Dwith-libneurosim=[OFF|ON|</path/to/libneurosim>]
 
 For details on how to use the Connection Generator Interface, see the
-:ref:`guide on connection management <conn_builder_conngen>`.
+:ref:`guide on connection generation <connection_generator>`.
 
 .. _compile_with_python:
 

doc/htmldoc/nest_behavior/running_simulations.rst

@@ -129,7 +129,7 @@ NEST also has some models that determine the precise time of the
 threshold crossing during the interval. Please see the documentation on
 :ref:`precise spike time neurons <sim_precise_spike_times>`
 for details about neuron update in continuous time and the
-:ref:`documentation on connection management <connection_management>`
+:ref:`documentation on the connectivty concepts  <connectivity_concepts>`
 for how to set the delay when creating synapses.
 
 .. _stepped_simulations:

doc/htmldoc/networks/spatially_structured_networks.rst

@@ -1339,7 +1339,7 @@ The following table presents some query functions provided by NEST.
 +---------------------------------+-----------------------------------------------------+
 | ``nest.GetConnections()``       | Retrieve connections (all or for a given            |
 |                                 | source or target); see also                         |
-|                                 | http://www.nest-simulator.org/connection_management.|
+|                                 | :ref:`connectivity_concepts`.                       |
 +---------------------------------+-----------------------------------------------------+
 | ``nest.GetNodes()``             | Returns a NodeCollection of all elements with given |
 |                                 | properties.                                         |

doc/htmldoc/static/css/custom.css

@@ -141,6 +141,12 @@ figure.align-default {
 	outline-style: groove;
 }
 
+.center {
+
+  text-align: center;
+  font-style: italic;
+}
+
 /**************************************************************************************
  * Rules for carousel
  * ***********************************************************************************/

doc/htmldoc/synapses/connection_generator.rst

@@ -0,0 +1,53 @@
+.. _connection_generator:
+
+Connection generator interface
+------------------------------
+
+.. admonition:: Availability
+
+   This connection rule is only available if NEST was compiled with
+   :ref:`support for libneurosim <compile_with_libneurosim>`.
+
+To allow the generation of connectivity by means of an external
+library, NEST supports the connection generator interface [2]_. For
+more details on this interface, see the git repository of `libneurosim
+<https://github.com/INCF/libneurosim>`_.
+
+In contrast to the other rules for creating connections, this rule
+relies on a Connection Generator object to describe the connectivity
+pattern in a library-specific way. The connection generator is handed
+to :py:func:`.Connect` under the key ``cg`` of the connection specification
+dictionary and evaluated internally. If the connection generator
+provides values for connection weights and delays, their respective
+indices can be specified under the key ``params_map``. Alternatively,
+all synapse parameters can be specified using the synapse
+specification argument to ``Connect()``.
+
+The following listing shows an example for using CSA (`Connection Set Algebra <https://github.com/INCF/csa>`_ [1]_) in NEST via the connection generator interface and randomly connects 10% of the neurons from
+``A`` to the neurons in ``B``, each connection having a weight of
+10000.0 pA and a delay of 1.0 ms:
+
+.. code-block:: python
+
+   import csa
+
+   A = nest.Create('iaf_psc_alpha', 100)
+   B = nest.Create('iaf_psc_alpha', 100)
+
+   # Create the Connection Generator object
+   cg = csa.cset(csa.random(0.1), 10000.0, 1.0)
+
+   # Map weight and delay indices to values from cg
+   params_map = {'weight': 0, 'delay': 1}
+
+   conn_spec = {'rule': 'conngen', 'cg': cg, 'params_map': params_map}
+   nest.Connect(A, B, conn_spec)
+
+
+References
+----------
+.. [1] Djurfeldt M. The Connection-set Algebra—A Novel Formalism for the Representation of Connectivity Structure in Neuronal Network Models. Neuroinformatics. 2012; 10: 287–304. https://doi.org/10.1007/s12021-012-9146-1
+.. [2] Djurfeldt M, Davison AP and Eppler JM (2014). Efficient generation of
+       connectivity in neuronal networks from simulator-independent
+       descriptions. Front. Neuroinform.
+       https://doi.org/10.3389/fninf.2014.00043