Improved documentation about weights (#1620)

doc/python/interconnectivity.rst

@@ -32,9 +32,9 @@ Interconnectivity
 
     .. attribute:: weight
 
-        The weight delivered to the target synapse.
-        The weight is dimensionless, and its interpretation is specific to the type of the synapse target.
-        For example, the expsyn synapse interprets it as a conductance with units μS (micro-Siemens).
+        The weight delivered to the target synapse. It is up to the target mechanism to interpret this quantity.
+        For Arbor-supplied point processes, such as the ``expsyn`` synapse, a weight of ``1`` corresponds to an
+        increase in conductivity in the target mechanism of ``1`` μS (micro-Siemens).
 
     .. attribute:: delay
 

doc/python/recipe.rst

@@ -118,7 +118,9 @@ Event generator and schedules
 
     .. attribute:: weight
 
-        The weight of events to deliver.
+        The weight delivered to the target synapse. It is up to the target mechanism to interpret this quantity.
+        For Arbor-supplied point processes, such as the ``expsyn`` synapse, a weight of ``1`` corresponds to an
+        increase in conductivity in the target mechanism of ``1`` μS (micro-Siemens).
 
 .. class:: regular_schedule
 

doc/tutorial/network_ring.rst

@@ -44,7 +44,12 @@ These locations will form the endpoints of the connections between the cells.
 
 After we've created a basic :py:class:`arbor.decor`, step **(3)** places a synapse with an exponential decay (``'expsyn'``) on the ``'synapse_site'``.
 The synapse is given the label ``'syn'``, which is later used to form :py:class:`arbor.connection` objects terminating *at* the cell.
-Note that mechanisms can be initialized with their name; ``'expsyn'`` is short for ``arbor.mechanism('expsyn')``.
+
+.. Note::
+   Mechanisms can be initialized with their name; ``'expsyn'`` is short for ``arbor.mechanism('expsyn')``.
+   Mechanisms typically have some parameters, which can be queried (see :py:class:`arbor.mechanism_info`) and set
+   (see :py:class:`arbor.mechanism`). In particular, the ``e`` parameter of ``expsyn`` defaults to ``0``, which makes it,
+   given the typical resting potential of cell membranes of ``-70 mV``, an excitatory synapse.
 
 Step **(4)** places a spike detector at the ``'root'``. The detector is given the label ``'detector'``, which is later used to form
 :py:class:`arbor.connection` objects originating *from* the cell.
@@ -72,7 +77,8 @@ are connecting the cells **(8)**, returning a configurable number of cells **(6)
 (``make_cable_cell()`` returns the cell above).
 
 Step **(8)** creates an :py:class:`arbor.connection` between consecutive cells. If a cell has gid ``gid``, the
-previous cell has a gid ``(gid-1)%self.ncells``. The connection has a weight of 0.1 μS and a delay of 5 ms.
+previous cell has a gid ``(gid-1)%self.ncells``. The connection has a weight of 0.01 (inducing a conductance of 0.01 μS
+in the target mechanism ``expsyn``) and a delay of 5 ms.
 The first two arguments to :py:class:`arbor.connection` are the **source** and **target** of the connection.
 
 The **source** is a :py:class:`arbor.cell_global_label` object containing a cell index ``gid``, the source label
@@ -119,7 +125,7 @@ In addition to having the timestamps of spikes, we want to extract the voltage a
 
 Step **(14)** sets the probes (step **10**) to measure at a certain schedule. This is sometimes described as
 attaching a :term:`sampler` to a :term:`probe`. :py:func:`arbor.simulation.sample` expects a :term:`probe id` and the
-desired schedule (here: a recording frequency of 10 kHz). Note that the probe id is a separate index from those of
+desired schedule (here: a recording frequency of 10 kHz, or a ``dt`` of 0.1 ms). Note that the probe id is a separate index from those of
 :term:`connection` endpoints; probe ids correspond to the index of the list produced by
 :py:func:`arbor.recipe.probes` on cell ``gid``.
 

python/example/network_ring.py

@@ -87,7 +87,7 @@ class ring_recipe (arbor.recipe):
     # (8) Make a ring network. For each gid, provide a list of incoming connections.
     def connections_on(self, gid):
         src = (gid-1)%self.ncells
-        w = 0.01
+        w = 0.01 # 0.01 μS on expsyn
         d = 5
         return [arbor.connection((src,'detector'), 'syn', w, d)]
 
@@ -95,7 +95,7 @@ class ring_recipe (arbor.recipe):
     def event_generators(self, gid):
         if gid==0:
             sched = arbor.explicit_schedule([1])
-            weight = 0.1
+            weight = 0.1 # 0.1 μS on expsyn
             return [arbor.event_generator('syn', weight, sched)]
         return []