Docs: Cell kind and description (#1227)

* Modify `cell kind` concept docs.
* Add `cell description` concept docs.
* Reorder the docs so that the recipe, cell kind and description, interconnectivity, hardware management, domain decomposition, and simulation are consecutive. Then start the more detailed cable cell docs. 

doc/concepts/cell.rst

@@ -20,90 +20,148 @@ Cells interact with each other via spike exchange and gap junctions.
                                                                 For example, the 7th synapse on cell 42.
     ========================  ================================  ===========================================================
 
+Cell interactions via :ref:`connections <modelconnections>` and :ref:`gap junctions <modelgapjunctions>` occur
+between **source**, **target** and **gap junction site** locations on a cell. Connections are formed from sources
+to targets. Gap junctions are formed between two gap junction sites. An example of a source on a
+:ref:`cable cell<modelcablecell>` is a :ref:`threshold detector <cable-threshold-detectors>` (spike detector);
+an example of a target on a cable cell is a :ref:`synapse <cable-synapses>`.
 
-Each cell has a global identifier :gen:`gid`, which is used to refer to cells in :ref:`recipes <modelrecipe>`.
-To describe or refer to cell-to-cell interactions, the following object types need to be enumerated:
+Each cell has a global identifier :gen:`gid`, and each **source**, **target** and **gap junction site** has a
+global identifier :gen:`cell_member`. These are used to refer to them in :ref:`recipes <modelrecipe>`.
 
-1. **Sources**
-2. **Targets**
-3. **Gap Junction Sites**
+A cell can have multiple sources, targets and gap junction site objects. Each object is ordered relative to other
+objects of the same type on that cell. The unique :gen:`cell_member` (:gen:`gid`, :gen:`index`) identifies an object
+according to the :gen:`gid` of the cell it is placed on, and its :gen:`index` on the cell enumerated according to the
+order of insertion on the cell relative to other objects of the same type.
 
-Cells interact with other cells via :ref:`connections <modelconnections>` or
-:ref:`gap junctions <modelgapjunctions>`. Connections are formed from **sources** to **targets**. Gap junctions
-are formed between two **gap junction sites**.
+The :gen:`gid` of a cell is used to determine its cell :ref:`kind <modelcellkind>` and
+:ref:`description <modelcelldesc>` in the :ref:`recipe <modelrecipe>`. The :gen:`cell_member` of a source,
+target or gap junction site is used to form :ref:`connections <modelconnections>` and
+:ref:`gap junctions <modelgapjunctions>` in the recipe.
 
-A cell can have multiple sources, targets and gap junction site objects. Each object has a local :gen:`index`
-relative to other objects of the same type on that cell.
-A unique (:gen:`gid`, :gen:`index`) pair defined by a :gen:`cell_member` can be used to uniquely identify
-objects on a cell in a global model.
 
 
-.. _model_cell_kinds:
+.. _modelcellkind:
 
-Cell kinds
-----------
+Cell kind
+---------
 
 .. table:: The 4 types of cell supported by Arbor
 
     ========================  ===========================================================
     Cell Kind                 Description
     ========================  ===========================================================
-    **cable**                 Cell with morphology described by branching
-                              1D cable segments and user configurable mechanisms.
-    **lif**                   Single-compartment no-mechanism leaky integrate-and-fire
-                              neuron.
-    **spiking**               Proxy cell that generates spikes from a user-supplied
-                              time sequence.
-    **benchmark**             Proxy cell used for benchmarking (developer use only).
+    **Cable cell**            Cell with morphology and user configurable dynamics.
+    **LIF cell**              Leaky integrate-and-fire neuron.
+    **Spiking cell**          Proxy cell that generates spikes.
+    **Benchmark cell**        Proxy cell used for benchmarking (developer use only).
     ========================  ===========================================================
 
-.. _model_cable_cell:
+.. _modelcablecell:
 1. **Cable Cells**
 
-   Cable cells are morphologically-detailed cells represented as branching linear 1D segments. They can be coupled
-   to other cell types via the following mechanisms:
+   Cable cells are morphologically-detailed cells. They can be coupled to other cells via the following
+   mechanisms:
 
-   1. Spike exchange over a **connection** with fixed latency.
+   1. Spike exchange over a :ref:`connection <modelconnections>` with fixed latency.
       Cable cells can *receive* spikes from any kind of cell, and can be a *source* of spikes
-      cells that have target sites (i.e. *cable* and *lif* cells).
-   2. Direct electrical coupling between two cable cells via **gap junctions**.
+      to cells that have target sites (i.e. *cable* and *lif* cells).
+   2. Direct electrical coupling between two cable cells via :ref:`gap junctions <modelgapjunctions>`.
 
-   Key concepts:
+.. _modellifcell:
+2. **LIF Cells**
+
+   LIF cells are single-compartment leaky integrate and fire neurons. They are typically used to simulate
+   point-neuron networks.
+
+   LIF cells can only interact with other cells via spike exchange over a
+   :ref:`connection <modelconnections>` where they can receive spikes from any kind of cell, and can
+   be a *source* of spikes to cells that have target sites (i.e. *cable* and *lif* cells).
+
+.. _modelspikecell:
+3. **Spiking Cells**
+
+   Spiking cells act as spike sources from user-specified values inserted via a `schedule description`.
+   They are typically used as stimuli in a network of more complex cells.
+
+   Spiking Cells can only interact with other cells via spike exchange over a
+   :ref:`connection <modelconnections>` where they be a *source* of spikes to cells that have target sites
+   (i.e. *cable* and *lif* cells), but they can not *receive* spikes.
+
+.. _modelbenchcell:
+4. **Benchmark Cells**
 
-   * **Morphology**: The morphology of a cable cell is composed of a branching tree of one-dimensional line segments.
-     Strictly speaking, Arbor represents a morphology is an *acyclic directed graph*, with the soma at the root.
-   * **Detectors**: Spike detectors generate spikes when the voltage at location on the cell
-     passes a threshold. Detectors act as **sources** of :ref:`connections <modelconnections>`.
-   * **Synapses**: Synapses act as **targets** of :ref:`connections <modelconnections>`.
-     A synapse is described by a synapse type (with associated parameters) and location on a cell.
-   * **Gap Junction Sites**: These refer to the sites of :ref:`gap junctions <modelgapjunctions>`.
-     They are declared by specifying a location on a branch of the cell.
+   Benchmark cells are proxy cells used for benchmarking, and used by developers to benchmark the spike
+   exchange and event delivery infrastructure.
 
-   Because cable cells are the main cell kind in Arbor and have more properties than listed here, they have a
-   :ref:`dedicated page <cablecell>`.
+.. _modelcelldesc:
+
+Cell description
+----------------
+
+The `description` of a cell is referred to in the :ref:`recipe <modelrecipe>`, and elsewhere in the docs.
+It details everything needed to build a cell. The degree of detail differs according to the cell kind.
+
+1. **Cable Cells**
+
+   The description of a cable cell can include all the following:
+
+     * :ref:`Morphology <co_morphology>`: composed of a branching tree of one-dimensional line segments.
+       Strictly speaking, Arbor represents a morphology as an *acyclic directed graph*, with the soma at
+       the root.
+     * Discretisation: specifies how to split the morphology into discrete components for the simulation.
+     * Initial membrane voltage.
+     * Initial axial resistivity.
+     * Intial membrane capacitance.
+     * Initial temperature.
+     * Initial ion internal and external concentrations.
+     * Initial ion reversal potential.
+     * Stimuli: such as current clamps; placed on specific :ref:`locations <labels-locset>` on the cell.
+     * :ref:`Density mechanisms <mechanisms-density>`: commonly used to describe ion-channel dynamics across
+       :ref:`regions <labels-region>` of the cell.
+     * :ref:`Ion reversal potential mechanisms <mechanisms-revpot>`: used to control the reversal potentials of
+       ions across regions of the cell.
+     * Synapses: implemented using :ref:`point mechanisms <mechanisms-point>` on specific locations of the cell;
+       typically act as **targets** of :ref:`connections <modelconnections>` in the recipe.
+     * Detectors: used to generate spiking events on specific locations on the cell when the voltage
+       increases above a certain threshold; typically act as **sources** of :ref:`connections <modelconnections>`.
+     * Gap junction sites: placed on a specific location on a cell and used to electrically couple the cell to
+       another gap junction site on another cell by forming a :ref:`gap junction <modelgapjunctions>`.
+
+   Most Arbor users will want to use the cable cell because it is the only cell kind that supports complex
+   morphologies and user-defined mechanisms. See the cable cell's :ref:`dedicated page <cablecell>` for more info.
+   And visit the :ref:`C++ <cppcable_cell>` and :ref:`Python <pycable_cell>` APIs to learn how to programmatically
+   provide the cable cell description in Arbor.
 
-.. _model_lif_cell:
 2. **LIF Cells**
 
-   LIF cells are single compartment leaky integrate and fire neurons with one **source** and one **target**.
-   LIF cells do not support adding additional **sources** or **targets**. They do not support **gap junctions**.
-   They are typically used to simulate point-neuron networks.
+   The description of a LIF cell is used to control the leaky integrate-and-fire dynamics:
 
-.. _model_spike_cell:
-3. **Spiking Cells**
+      * Resting potential.
+      * Reset potential.
+      * Initial value of membrane potential.
+      * Membrane potential decaying constant.
+      * Membrane capacitance.
+      * Firing threshold.
+      * Refractory period.
 
-   Spiking cells act as spike sources from values inserted via a `schedule description`.
-   They are point neurons with one built-in **source** and no **targets**.
-   They do not support adding additional **sources** or **targets**. They do not support **gap junctions**.
+   The morphology of a LIF cell is automatically modeled as a single compartment; each cell has one built-in
+   **source** and one built-in **target** which do not need to be explicitly added in the cell description.
+   LIF cells do not support adding additional **sources** or **targets** to the description. They do not support
+   **gap junctions**. They do not support adding density or point mechanisms.
 
-.. _model_bench_cell:
-4. **Benchmark Cells**
+3. **Spiking cells**
 
-   Benchmark cells are proxy cells used for benchmarking, and used by developers to benchmark the spike exchange and
-   event delivery infrastructure.
+   The description of a spiking cell controls the spiking schedule of the cell. Its morphology is
+   automatically modeled as a single compartment; each cell has one built-in **source** which does not need to
+   be explicitly added in the cell description, and no **targets**. Spiking cells do not support adding additional
+   **sources** or **targets**. They do not support **gap junctions**. They do not support adding density or
+   point mechanisms.
+
+4. **Benchmark Cells**
 
-Most Arbor users will want to use the cable cell, which is the only cell kind that supports complex morphologies
-and user-defined mechanisms. You can visit the :ref:`cable cell page <cablecell>` for more information.
+   The description of a benchmark cell is used to determine the spiking schedule of the cell and manipulate its
+   performance efficiency. This cell is mainly used by developers.
 
 API
 ---

doc/concepts/domdec.rst

@@ -6,19 +6,21 @@ Domain decomposition
 A *domain decomposition* describes the distribution of the model over the available computational resources.
 The description partitions the cells in the model as follows:
 
-    * group the cells into cell groups of the same kind of cell;
+    * group the cells into cell groups of the same :ref:`kind <modelcellkind>` of cell;
     * assign each cell group to either a CPU core or GPU on a specific MPI rank.
 
 The number of cells in each cell group depends on different factors, including the type of the cell, and whether the
 cell group will run on a CPU core or the GPU. The domain decomposition is solely responsible for describing the distribution
 of cells across cell groups and domains.
 
+The domain decomposition can be built manually by the modeler, or an automatic load balancer can be used.
+
 
 Load balancers
 --------------
 
-A *load balancer* generates the domain decomposition using the model recipe and a description of the available computational
-resources on which the model will run described by an execution context.
+A *load balancer* generates the domain decomposition using the model :ref:`recipe <modelrecipe>` and a description of
+the available computational resources on which the model will run described by an :ref:`execution context <modelcontext>`.
 Currently Arbor provides one load balancer and more will be added over time.
 
 API

doc/concepts/hardware.rst

@@ -19,6 +19,8 @@ An *allocation* enumerates the computational resources to be used for a simulati
    applications/libraries.
 
 
+.. _modelcontext:
+
 Execution context
 -----------------
 

doc/concepts/index.rst

 .. _modelintro:
 
 Concepts
-====================
+========
 
 To learn how to use Arbor, it is helpful to understand some of its concepts.
 
@@ -21,25 +21,38 @@ The python front-end further abstracts away some of these steps for single cell
 describe the cell and simulation; and the details of the recipe and computational resources construction are
 handled under the hood. Generally speaking though, these 3 steps are the building blocks of an Arbor application.
 
-:ref:`Recipes <modelrecipe>` represent a set of neuron constructions and connections with *mechanisms* specifying ion channel and synapse dynamics in a cell-oriented manner. This has the advantage that cell data can be initiated in parallel.
+:ref:`Recipes <modelrecipe>` represent a set of neuron constructions and connections with *mechanisms* specifying
+ion channel and synapse dynamics in a cell-oriented manner. This has the advantage that cell data can be initiated
+in parallel.
 
-A cell represents the smallest unit of computation and forms the smallest unit of work distributed across processes. Arbor has built-in support for different :ref:`cell types <modelcells>`, which can be extended by adding new cell types to the C++ cell group interface.
+A cell represents the smallest unit of computation and forms the smallest unit of work distributed across processes.
+Arbor has built-in support for different :ref:`cell types <modelcells>`, which can be extended by adding new cell
+types to the C++ cell group interface.
 
-:ref:`modelsimulation` manage the instantiation of the model and the scheduling of spike exchange as well as the integration for each cell group. A cell group represents a collection of cells of the same type computed together on the GPU or CPU. The partitioning into cell groups is provided by :ref:`modeldomdec` which describes the distribution of the model over the locally available computational resources.
+:ref:`modelsimulation` manage the instantiation of the model and the scheduling of spike exchange as well as the
+integration for each cell group. A cell group represents a collection of cells of the same type computed together
+on the GPU or CPU. The partitioning into cell groups is provided by :ref:`modeldomdec` which describes the distribution
+of the model over the locally available computational resources.
 
-In order to visualize the result of detected spikes a spike recorder can be used and to analyse Arbor's performance a meter manager is available.
+In order to visualize the result of detected spikes a spike recorder can be used, and to analyse Arbor's performance a
+meter manager is available.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Arbor concepts:
+   :caption: From recipe to simulation:
 
    recipe
    cell
-   cable_cell
-   morphology
-   labels
-   mechanisms
    interconnectivity
    hardware
    domdec
    simulation
+
+.. toctree::
+   :maxdepth: 2
+   :caption: The cable cell:
+
+   cable_cell
+   morphology
+   labels
+   mechanisms

doc/concepts/interconnectivity.rst

@@ -11,19 +11,25 @@ Connections only capture the propagation delay and attenuation associated with s
 connectivity: the biophysical modelling of the chemical synapses themselves is the
 responsibility of the target cell model.
 
-Connection sites and gap junction sites are defined on locations on cells (more on cells :ref:`here <modelcells>`). A recipe lets you define which sites are connected to which.
+Connection sites and gap junction sites are defined on locations on cells as part of the
+:ref:`cell description <modelcelldesc>`.
+A recipe lets you define which sites are connected to which.
 
 .. _modelconnections:
 
 Connections
 -----------
 
-Connections implement chemical synapses between **source** and **target** cells and are characterized by having a transmission delay.
+Connections implement chemical synapses between **source** and **target** cells and are characterized
+by having a transmission delay.
 
 Connections in Arbor are defined in two steps:
 
-1. Create **Source** and **Target** on two cells: a source defined on one cell, and a target defined on another.
-2. Declare the connection in the :ref:`recipe <modelrecipe>`: with a source and target identified using :gen:`cell_member`, a connection delay and a connection weight.
+1. Create **source** and **target** on two separate cells as part of their
+   :ref:`cell descriptions <modelcelldesc>` in the :ref:`recipe <modelrecipe>`. Sources typically
+   generate spiking events. Targets are typically synapses with associated biophysical model descriptions.
+2. Declare the connection in the recipe: with the source and target identified using :gen:`cell_member`,
+   a connection delay and a connection weight. The connection should be declared on the target cell.
 
 .. _modelgapjunctions:
 
@@ -35,11 +41,10 @@ They are modeled as a conductance between two **gap junction sites** on two cell
 
 Similarly to `Connections`, Gap Junctions in Arbor are defined in two steps:
 
-1. A **gap junction site** is created on each of the two cells.
-   These locations need to be declared on the :ref:`cell <modelcells>`.
-2. Gap Junction instantiation in the :ref:`recipe <modelrecipe>`: The **gap junction sites** are indexed using :gen:`cell_member`
-   because a single cell may have more than one gap junction site.
-   A gap junction is instantiated by providing two **gap junction sites'** and a conductance in μS.
+1. Create a **gap junction site** on two separate cells as part of their
+   :ref:`cell descriptions <modelcelldesc>` in the :ref:`recipe <modelrecipe>`.
+2. Declare the Gap Junction in the recipe: with two **gap junction sites** identified using :gen:`cell_member`
+   and a conductance in μS.
 
    .. Note::
       Only cable cells support gap junctions as of now.

doc/concepts/recipe.rst

@@ -26,7 +26,7 @@ three cells:
      attached, with the intention of triggering some spikes. All of the preceding info:
      the morphology, dynamics, spike detector and current clamp are what is refered to in
      Arbor as the **description** of the cell.
-   | ``Cell 0`` should be modeled as a :ref:`cable cell<model_cable_cell>`,
+   | ``Cell 0`` should be modeled as a :ref:`cable cell<modelcablecell>`,
      (because cable cells allow complex dynamics such as ``hh``). This is refered to as
      the **kind** of the cell.
    | It's quite expensive to build cable cells, so we don't want to do this too often.
@@ -58,6 +58,10 @@ a spike should be observed on ``cell 2`` after some delay. To monitor
 the voltage on ``cell 2`` and record the spike, a **probe** can be set up
 on ``cell 2``. All this information is also registered via the recipe.
 
+There are additional docs on :ref:`cell kinds <modelcellkind>`;
+:ref:`cell descriptions <modelcelldesc>`; :ref:`network connections <modelconnections>`;
+:ref:`gap junction connections <modelgapjunctions>`; :ref:`probes <modelprobes>`
+
 The recipe is used to distribute the model across machines and is used in the simulation.
 Technical details of the recipe class are presented in the  :ref:`Python <pyrecipe>` and
 :ref:`C++ <cpprecipe>` APIs.
@@ -67,7 +71,7 @@ Are recipes always neccessary?
 
 Yes. However, we provide a python :class:`single_cell_model <py_single_cell_model>`
 that abstracts away the details of a recipe for simulations of  single, stand-alone
-:ref:`cable cells<model_cable_cell>`, which absolves the users from having to create the
+:ref:`cable cells<modelcablecell>`, which absolves the users from having to create the
 recipe themselves. This is possible because the number of cells, spike targets, spike sources
 and gap junction sites is fixed and known, as well as the fact that there can be no connections
 or gap junctions on a single cell. The single cell model is able to fill out the details of the

doc/concepts/simulation.rst

@@ -2,28 +2,31 @@
 
 Simulations
 ===========
-A simulation is the executable form of a model and is used to interact with and monitor the model state. In the simulation the neuron model is initiated and the spike exchange and the integration for each cell group are scheduled.
+A simulation is the executable form of a model and is used to interact with and monitor the model state.
+In the simulation the neuron model is initiated and the spike exchange and the integration for each cell
+group are scheduled.
 
 From recipe to simulation
 -------------------------
 
 To build a simulation the following are needed:
 
-    * A recipe that describes the cells and connections in the model.
-    * A context used to execute the simulation.
-
-The workflow to build a simulation is to first generate a domain decomposition that describes the distribution of the model over the local and distributed hardware resources (see :ref:`modeldomdec`), then build the simulation from the recipe, the domain decomposition and the execution context. Optionally experimental inputs  that can change between model runs, such as external spike trains, can be injected.
-
-The recipe describes the model, the domain decomposition describes how the cells in the model are assigned to hardware resources and the context is used to execute the simulation.
+    * A :ref:`recipe <modelrecipe>` that describes the cells and connections in the model.
+    * A :ref:`domain decomposition <modeldomdec>` that describes the distribution of the
+      model over the local and distributed :ref:`hardware resources <modelhardware>`.
+    * An :ref:`execution context <modelcontext>` used to execute the simulation.
 
 Simulation execution and interaction
 ------------------------------------
 
 Simulations provide an interface for executing and interacting with the model:
 
-    * The simulation is executed/ *run* by advancing the model state from the current simulation time to another with maximum time step size.
+    * The simulation is executed/*run* by advancing the model state from the current simulation time to another
+      with maximum time step size.
     * The model state can be *reset* to its initial state before the simulation was started.
-    * *Sampling* of the simulation state can be performed during execution with samplers and probes (e.g. compartment voltage and current) and spike output with the total number of spikes generated since either construction or reset.
+    * *Sampling* of the simulation state can be performed during execution with samplers and probes (e.g.
+      compartment voltage and current) and spike output with the total number of spikes generated since either
+      construction or reset.
 
 API
 ---