Multisynaptic conns

doc/source/user_documentation.rst

@@ -376,10 +376,9 @@ Each item of the ``connParams`` ordered dictionary consists of a key and value.
 * **sec** (optional) - Name of target section on the postsynaptic neuron (e.g. ``'soma'``) 
 	If omitted, defaults to 'soma' if it exists, otherwise to the first section in the cell sections list.
 
-	If ``synsPerConn`` > 1, and a list of sections or sectionList is specified, synapses will be distributed uniformly along the specified section(s), taking into account the length of each section.
-
-	If ``synsPerConn`` == 1, and list of sections or sectionList is specified, synapses (one per presynaptic cell) will be placed in sections randomly selected from the list. To enforce using always the first section from the list set ``cfg.connRandomSecFromList = False``.
+	Can be defined as a name of a single section, a list of sections, e.g. ``['soma', 'dend']``, or key from **secList** dictionary of post-synaptic cellParams.
 
+	If specified as a list, can be handled in different ways - see :ref:`Multisynapse connections<multisynapse_conn>` for more details.
 
 * **loc** (optional) - Location of target synaptic mechanism (e.g. ``0.3``)
 	If omitted, defaults to 0.5.
@@ -390,16 +389,14 @@ Each item of the ``connParams`` ordered dictionary consists of a key and value.
 
 	If you have both a list of ``synMechs`` and ``synsPerConn`` > 1, you can have a 2D list for each synapse of each synMech (e.g. for two synMechs and ``synsPerConn`` = 3: ``[[0.2, 0.3, 0.5], [0.5, 0.6, 0.7]]``)
 
-	If ``synsPerConn`` == 1, and a list of ``loc``s is specified, synapses (one per presynaptic cell) will be placed in locations randomly selected from the list (note that the random section and location will go hand in hand, i.e. the same random index is used for both). 
-
-	.. The above only applies for a single target section, ``sec``. If a list of target sections is specified, the ``loc`` value has no effect, and synapses will be distributed uniformly along the specified section(s), taking into account the length of each section. To enforce using always the first location from the list set ``cfg.connRandomSecFromList = False``.
+	In these multisynapse scenarios, additional parameters become available - see :ref:`Multisynapse connections<multisynapse_conn>` for more details.
 
 
 * **synMech** (optional) - Label (or list of labels) of target synaptic mechanism(s) on the postsynaptic neuron (e.g. ``'AMPA'`` or ``['AMPA', 'NMDA']``)
 
 	If omitted, employs first synaptic mechanism in the cell's synaptic mechanisms list.
 
-	If you have a list, a separate connection is created to each synMech; and a list of weights, delays and/or locs can be provided.  
+	When using a list of synaptic mechanisms, a separate connection is created for each mechanism. You can optionally provide corresponding lists of weights, delays, and/or locations. See :ref:`Multisynapse connections<multisynapse_conn>` for more details.
 
 * **synsPerConn** (optional) - Number of individual synaptic connections (*synapses*) per cell-to-cell connection (*connection*)
 
@@ -409,11 +406,10 @@ Each item of the ``connParams`` ordered dictionary consists of a key and value.
 
 	The weights, delays and/or locs for each synapse can be specified as a list, or a single value can be used for all.
 
-	When ``synsPerConn`` > 1 and a single section is specified, the locations of synapses can be specified as a list in ``loc``.
+	When ``synsPerConn`` > 1 and a *single section* is specified, the locations of synapses can be specified as a list in ``loc``. If a *list of target sections* is specified, ``loc`` should be omitted, and synapses will be distributed uniformly along the specified section(s), taking into account the length of each section. See :ref:`Multisynapse connections<multisynapse_conn>` for more details.
 
-	When ``synsPerConn`` > 1, if ``loc`` is a single value or omitted, or if a list of target sections is specified, synapses will be distributed uniformly along the specified section(s), taking into account the length of each section.
+	If you have a list of ``synMechs``, you can have single ``synsPerConn`` value for all, or a list of values, one per synaptic mechanism in the list.
 
-
 * **weight** (optional) - Strength of synaptic connection (e.g. ``0.01``)
 	Associated with a change in conductance, but has different meaning and scale depending on the synaptic mechanism and cell model.
 
@@ -535,6 +531,105 @@ Here is an example of connectivity rules:
 	    'delay': [5, 10],                             # different delays for each of 3 synapses per synMech 
 	    'loc': [[0.1, 0.5, 0.7], [0.3, 0.4, 0.5]]}    # different locations for each of the 6 synapses
 
+.. _multisynapse_conn:
+
+**Connectivity Rules with Multiple Synapses per Connection**
+
+By default, there is only one synapse created per connection. However, multiple synapses can be created targeting each post-synaptic cell. This can be achieved by setting ``synsPerConn`` to a value greater than 1, or by defining ``synMech`` as a list, or both.
+
+* Setting ``synsPerConn`` >= 1 with ``synMech`` as a single value
+	If ``synsPerConn`` is > 1, then for each connection, this number of synapses will be created. The weights and delays can be specified as lists, or a single value can be used for all. ``loc`` should be a list, a single value is not accepted. If ``loc`` is omitted, a uniform distribution is used (i.e., synapses are placed at equal distances along the section).
+
+	.. code-block:: python
+
+		netParams.connParams['PYR->PYR'] = {
+			'preConds': {'pop': 'src'}, 'postConds': {'pop': 'dst'},
+			'synsPerConn': 2,
+			'weight': [0.1, 0.2], # individual weights for each synapse
+			'delay': 0.1, # single delay for all synapses
+			'loc': [0.5, 1.0] # individual locations for each synapse
+		}
+		# This will create 2 synapses: one with weight 0.1, delay 0.1, and loc 0.5
+		# and another with weight 0.2, delay 0.1, and loc 1.0.
+
+	When ``synsPerConn`` > 1 and a *single* section is specified, all synapses will be created there, and the locations of synapses can be specified as a list in ``loc`` (one per synapse, e.g., if ``synsPerConn`` = 3: ``[0.4, 0.5, 0.7]``).
+
+	If a *list of sections* is specified (either explicitly or as a key from `secLists`), synapses will be distributed uniformly along the specified section(s), taking into account the length of each section. (E.g., if you provide 'soma' and 'dend' with lengths 10 and 20 respectively, and ``synsPerConn`` = 5, the following sections and locations will be as shown in the figure below). Providing location explicitly is not possible in this case.
+
+	.. image:: figs/multisyn_0.png
+		:width: 50%
+		:align: center
+
+	The behavior above is due to the ``distributeSynsUniformly`` flag, which is True by default. Alternatively, if it is set to False (and ``connRandomSecFromList`` is True, which is default value), a random section will be picked from the sections list for each synapse. The ``loc`` value should also be a list, and the values will be picked from it randomly and independently from section choice. If the length of sections or locations list is greater or equal to ``synsPerConn``, random choice is guaranteed to be without replacement. If ``loc`` is omitted, the value for each synapse is randomly sampled from uniform[0, 1]. 
+
+	To enforce a deterministic way of picking ``sec`` and ``loc``, set ``connRandomSecFromList`` to False (N-th synapse then gets N-th section and N-th loc from their respective lists, or if ``loc`` is a single value, it is used for all synapses). Make sure that lists of sections and locations both have the length equal to ``synsPerConn``.
+
+	If ``synsPerConn`` == 1, and a list of sections is specified, synapses (one per presynaptic cell) will be placed in sections randomly selected from the list. If ``loc`` is also a list, locations will be picked randomly (note that the random section and location will go hand in hand, i.e., the same random index is used for both).
+
+* Setting ``synMech`` as a list
+	If ``synMech`` is a list, then for each mechanism in the list, a synapse will be created. The weights, delays, and locs can be specified as lists of the same length as ``synMech``, or a single value can be used for all.
+
+	.. code-block:: python
+
+		netParams.connParams['PYR->PYR'] = {
+			'preConds': {'pop': 'src'}, 'postConds': {'pop': 'dst'},
+			'synMech': ['AMPA', 'GABA'],
+			'weight': [0.1, 0.2], # individual weights for each synapse
+			'delay': 0.1, # single delay for all synapses
+		}
+		# This will create 2 synapses: one with AMPA synMech and weight 0.1
+		# and another with GABA synMech and weight 0.2. Both will have the same delay of 0.1.
+
+
+	However, for the sections, no such one-to-one correspondence to ``synMech`` elements applies. Instead, contents of ``secs`` are repeated for each synapse.
+
+	.. code-block:: python
+
+		netParams.connParams['PYR->PYR'] = {
+			'preConds': {'pop': 'src'}, 'postConds': {'pop': 'dst'},
+			'synMech': ['AMPA', 'GABA'],
+			'sec': ['soma', 'dend']
+		}
+		# Both AMPA and GABA synapses will span 'soma' and 'dend' sections
+
+	If you want to have different sections, separate connectivity rules (``connParams`` entries) should be defined for each synaptic mechanism.
+
+* Both ``synMech`` as a list and ``synsPerConn`` > 1
+	If you have both a N-element list of ``synMechs`` and ``synsPerConn`` > 1, weights and delays can still be specified as a single value for all synapses, as a list of length N (each value corresponding to ``synMech`` list index), or a 2D list with outer dimension N (corresponding to ``synMechs``) and inner dimension corresponding to ``synsPerConn``.
+
+	.. image:: figs/multisyn_1.png
+		:width: 35%
+		:align: right
+
+	.. code-block:: python
+
+		netParams.connParams['PYR->PYR'] = {
+			'preConds': {'pop': 'src'}, 'postConds': {'pop': 'dst'},
+			'synMech': ['AMPA', 'GABA'],
+			'sec': 'dend',
+			'synsPerConn': [2, 1],
+			'loc': [[0.5, 0.75], [0.3]],
+			'distributeSynsUniformly': False,
+		}
+
+	Note that ``synsPerConn`` itself can be a list, so that each ``synMech`` can correspond to a distinct number of synapses.
+
+* Usage with **'connList'**
+	If, in addition, you are using **'connList'**-based connectivity (explicit list of connections between individual pre- and post-synaptic cells), then the weights, delays, locs, secs are lists that can be described by up to 3-dimensional lists. The outer dimension now corresponds to the length of ``connList`` (i.e., number of cell-to-cell connections). Then the same logic as above applies to each element of this outer list.
+
+	.. code-block:: python
+
+		netParams.connParams['PYR->PYR'] = {
+			'preConds': {'pop': 'src'}, 'postConds': {'pop': 'dst'},
+			'connList': [[0,0], [1,0]],
+			'synMech': ['AMPA', 'GABA'],
+			'synsPerConn': 3,
+			'weight': [[[1, 2, 3], [4, 5, 6]], # first conn: AMPA, GABA, 3 synsPerConn each
+					[[7, 8, 9], [10, 11, 12]]],  # second conn: AMPA, GABA (...)
+
+			'delay': [[0.1, 0.2], # first conn: AMPA, GABA, same for all syns in synsPerConn
+					[0.3, 0.4]],  # second conn: AMPA, GABA (...)
+		}
 
 .. _function_string:
 
@@ -2268,7 +2363,7 @@ connections from the sensory to the motor population.
 inspyred allows customization of the various components of the
 evolutionary algorithm, including:
 
--   a selector that determines which sets of parameter values become
+-  a selector that determines which sets of parameter values become
    parents and thus which parameter values will be used to form the next
    generation in the evolutionary iteration,
 -  a variator that determines how each current iteration of parameter