add spike source docs. (#1939)

Document use and care of spike detectors.

doc/concepts/decor.rst

@@ -356,6 +356,28 @@ A point mechanism (synapse) can form the target of a :term:`connection` on a cel
 2. Threshold detectors (spike detectors).
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Spike detectors have a dual use: they can be used to record spike times, but are also used in propagating signals
+between cells. An example where we're interested in when a threshold of ``-10 mV`` is reached:
+
+.. code-block:: Python
+
+    # Placing a spike detector might look like this.
+    decor = arbor.decor()
+    decor.place('"root"', arbor.spike_detector(-10), "my_spike_detector")
+
+    # At this point, "my_spike_detector" could be connected to another cell,
+    # and it would transmit events upon the voltage crossing the threshold.
+
+    # Just printing those spike times goes as follows.
+    sim = arbor.simulation(...)
+    sim.record(arbor.spike_recording.all)
+    sim.run(...)
+    print("spikes:")
+    for sp in sim.spikes():
+        print(" ", sp)
+
+See also :term:`spike detector`.
+
 .. _cablecell-gj-mechs:
 
 3. Gap junction connection sites
@@ -424,6 +446,7 @@ constant stimuli and constant amplitude stimuli restricted to a fixed time inter
 5. Probes
 ~~~~~~~~~
 
+See :ref:`probesample`.
 
 API
 ---

doc/concepts/interconnectivity.rst

@@ -39,6 +39,19 @@ A recipe lets you define which sites are connected to which.
    action potential
       Spikes travel over :term:`connections <connection>`. In a synapse, they generate an event.
 
+   spike detector
+      :ref:`Placed <cablecell-place>` on a cell. Possible source of a connection.
+      Detects crossing of a fixed threshold and generates corresponding events.
+      Also used to :ref:`record spikes <>` for analysis. See :ref:`here
+      <cablecell-threshold-detectors>` for more information.
+
+   spike source cell
+      Artificial cell to generate spikes on a given schedule, see :ref:`spike cell <spikecell>`.
+
+   recording
+      By default, spikes are used for communication, but not stored for analysis,
+      however, :ref:`simulation <modelsimulation>` objects can be instructed to record spikes.
+
    event
       In a synapse :term:`spikes <spike>` generate events, which constitute stimulation of the synapse
       mechanism and the transmission of a signal. A synapse may receive events directly from an

doc/concepts/labels.rst

@@ -866,4 +866,4 @@ API
 ---
 
 * :ref:`Python <pylabels>`
-* *TODO*: C++ documentation.
+* :ref:`C++ <cpplabels>`

doc/concepts/mechanisms.rst

@@ -267,4 +267,4 @@ API
 ---
 
 * :ref:`Python <py_mechanisms>`
-* *TODO* C++ documentation.
+* :ref:`C++ <cpp_mechanisms>`

doc/concepts/probe_sample.rst

@@ -58,6 +58,12 @@ Definitions
         An object representing a series of monotonically increasing points in time, used for determining
         sample times (see :ref:`pyrecipe`).
 
+Spiking
+*******
+
+Spike detectors have a dual use: they can be used to record spike times, but are also used in propagating signals
+between cells. See also :term:`spike detector` and :ref:`cablecell-threshold-detectors`.
+
 
 API
 ---

doc/concepts/simulation.rst

@@ -20,6 +20,15 @@ To build a simulation the following is needed:
   not given, the default context will be used, which allocates one thread, one
   process (MPI task), and no GPU.
 
+Configuring data extraction
+---------------------------
+
+Two kinds of data extraction can be set up:
+1. certain state variables can be :ref:`sampled <probesample>` by attaching a
+   sampler to a probe.
+2. spikes can be recorded by either a callback (C++) or a preset recording model
+   (Python), see the API docs linked below.
+
 Simulation execution and interaction
 ------------------------------------
 

doc/python/simulation.rst

@@ -214,7 +214,8 @@ over the local and distributed hardware resources (see :ref:`pydomdec`). Then, t
 Recording spikes
 ----------------
 
-By default, spikes are not recorded. Recording is enabled with the
+Spikes are generated by various sources, including detectors and spike source
+cells, but by default, spikes are not recorded. Recording is enabled with the
 :py:func:`simulation.record` method, which takes a single argument instructing
 the simulation object to record no spikes, all locally generated spikes, or all
 spikes generated by any MPI rank.