Doc updates (#2119)

- Fix interconnectivity markup
- Add missing probes (related to ion diffusion)
- Add missing mechanisms documentation present in the default mech cat.

doc/concepts/interconnectivity.rst

@@ -184,11 +184,11 @@ call to ``simulation::run(T, dt)`` is given a value for ``T`` that is not an
 integer multiple of the epoch length.
 
 Before the start of each ``epoch``, a control message must be exchanged between
- Arbor and the coupled simulation. The control message is transferred by use
- ``MPI_Allreduce(6)`` with operation ``MPI_SUMM`` on a byte buffer of length
- ``ARB_REMOTE_MESSAGE_LENGTH``. All processes begin with a buffer of zeroes, the
- process with ``rank`` equal to ``ARB_REMOTE_ROOT`` on both sides of the
- intercommunicator writes a payload comprising
+Arbor and the coupled simulation. The control message is transferred by use
+``MPI_Allreduce(6)`` with operation ``MPI_SUMM`` on a byte buffer of length
+``ARB_REMOTE_MESSAGE_LENGTH``. All processes begin with a buffer of zeroes, the
+process with ``rank`` equal to ``ARB_REMOTE_ROOT`` on both sides of the
+intercommunicator writes a payload comprising
 
 1. A single byte magic number
 2. A three byte version number
@@ -227,10 +227,10 @@ the result as a ``ctrl_messge``. Handling the message is left to the
 participating package.
 
 **Important** This is a synchronous protocol which means an unannounced
- termination of either side of the coupled simulators can lead to the other
- getting stuck on a blocking call to MPI. This unlikely to cause issues in
- scenarios where both sides are launched as a single job (eg via ``SLURM``), but
- might do so where unrelated jobs are used.
+termination of either side of the coupled simulators can lead to the other
+getting stuck on a blocking call to MPI. This unlikely to cause issues in
+scenarios where both sides are launched as a single job (eg via ``SLURM``), but
+might do so where unrelated jobs are used.
 
 Tying It All Together
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/concepts/mechanisms.rst

@@ -56,21 +56,44 @@ the `BBP mechanisms <https://github.com/arbor-sim/arbor/tree/master/mechanisms/b
 Built-in Catalogues
 '''''''''''''''''''
 
-Arbor provides the ``default_catalogue`` with the following mechanisms:
+Arbor comes with a number of built-in catalogues. The sources (in :ref:`formatnmodl` format)
+are located in the ``mechanisms`` `subdirectory of the Arbor source <https://github.com/arbor-sim/arbor/tree/master/mechanisms>`_.
+You may need to consult these source files to learn about the parameters and features of the mechanism.
+
+The ``default_catalogue`` comes with the following mechanisms:
 
 * *pas*: Leaky current (:ref:`density mechanism <mechanisms-density>`).
 * *hh*: Classic Hodgkin-Huxley dynamics (:ref:`density mechanism
   <mechanisms-density>`).
-* *nernst*: Calculate reversal potential for an ionic species using the Nernst
-  equation (:ref:`reversal potential mechanism <mechanisms-revpot>`). **NB**
-  This is not meant to be used directly
 * *expsyn*: Synapse with discontinuous change in conductance at an event
   followed by an exponential decay (:ref:`point mechanism <mechanisms-point>`).
 * *exp2syn*: Bi-exponential conductance synapse described by two time constants:
   rise and decay (:ref:`point mechanism <mechanisms-point>`).
 * *gj*: Linear gap-junction mechanism with constant conductance (:ref:`junction mechanism <mechanisms-junction>`).
 
-With the exception of *nernst*, these mechanisms are the same as those available in NEURON.
+These mechanisms are the same as those available in NEURON. Arbor-specific mechanisms in the default catalogue are:
+
+* *nernst*: Calculate reversal potential for an ionic species using the Nernst
+  equation (:ref:`reversal potential mechanism <mechanisms-revpot>`). **NB**
+  This is not meant to be used directly
+* *inject*: Inject (signalling) ions, e.g. Ca++ (:ref:`point mechanism
+  <mechanisms-point>`).
+* *decay*: Exponential decay of ions (:ref:`density mechanism
+  <mechanisms-density>`).
+* *expsyn_cur*: Exponential current-based synapse (:ref:`point mechanism
+  <mechanisms-point>`).
+* *expsyn_stdp*: Exponential synapse with online STDP (:ref:`point mechanism
+  <mechanisms-point>`).
+* *kamt*: K-A current for Mitral Cells (Wang et al 1996) (:ref:`density mechanism
+  <mechanisms-density>`).
+* *kdrmt*: K-DR current for Mitral Cells (Wang et al 1996) (:ref:`density mechanism
+  <mechanisms-density>`).
+* *nax*: Na current for axon. No slow inact. (M.Migliore Jul. 1997) (:ref:`density mechanism
+  <mechanisms-density>`).
+* *v_clamp*: Writing directly to the membrane voltage. Breaks the cable model, so use with caution 
+  (:ref:`See NMODL documentation <formatnmodl_voltageproc>`).
+* *v_limit*: Limit directly the membrane voltage. Breaks the cable model, so use with caution 
+  (:ref:`See NMODL documentation <formatnmodl_voltageproc>`).
 
 Two catalogues are provided that collect mechanisms associated with specific projects and model databases:
 

doc/cpp/probe_sample.rst

@@ -258,6 +258,26 @@ Ionic external concentration of ion across components of the cell.
    the unbranched component for the corresponding sample value.
 
 
+Ionic diffusion concrentration.
+
+.. code::
+
+    struct cable_probe_ion_diff_concentration {
+        locset locations;
+        std::string ion;
+    };
+
+Diffusive ionic concentration of the given ``ion`` at the
+sites specified by ``locations``.
+
+.. code::
+
+    struct cable_probe_ion_diff_concentration_cell {
+        std::string ion;
+    };
+
+Ionic diffusion concrentration attributed to a particular ``ion`` across CVs of the cell.
+
 
 Mechanism state
 ^^^^^^^^^^^^^^^

doc/fileformat/nmodl.rst

@@ -178,6 +178,8 @@ Arbor-specific features
   tanh(x)             hyperbolic tangent                        :math:`tanh(x)`
   ==================  ========================================  =========
 
+.. _formatnmodl_voltageproc:
+
 Voltage Processes
 -----------------
 

doc/python/probe_sample.rst

@@ -298,6 +298,22 @@ Ionic external concentration
 
    Kind: :term:`vector probe`.
 
+Ionic diffusion concrentration
+   .. py:function:: cable_probe_ion_diff_concentration_cell(ion)
+
+   Diffusive ionic concentration of the given ``ion`` for each cable in each CV.
+
+   Metadata: the explicit :class:`location` of the sample site.
+
+   Kind: :term:`vector probe`.
+
+   .. py:function:: cable_probe_ion_diff_concentration(where, ion)
+
+   Diffusive ionic concentration of the given ``ion`` at the
+   sites specified by the location expression string ``where``.
+
+   Metadata: the list of corresponding :class:`cable` objects.
+
 LIF Cell probing
 ================