Docs: concept/recipe (#1217)

* Add an example describing the content of a recipe in the recipe concepts page in the docs.
* Mention that recipes are necessary, but can be abstracted away using the python `single_cell_model` (Hasn't been documented yet).

doc/concepts/cell.rst

@@ -38,6 +38,8 @@ A unique (:gen:`gid`, :gen:`index`) pair defined by a :gen:`cell_member` can be
 objects on a cell in a global model.
 
 
+.. _model_cell_kinds:
+
 Cell kinds
 ----------
 
@@ -55,6 +57,7 @@ Cell kinds
     **benchmark**             Proxy cell used for benchmarking (developer use only).
     ========================  ===========================================================
 
+.. _model_cable_cell:
 1. **Cable Cells**
 
    Cable cells are morphologically-detailed cells represented as branching linear 1D segments. They can be coupled
@@ -79,18 +82,21 @@ Cell kinds
    Because cable cells are the main cell kind in Arbor and have more properties than listed here, they have a
    :ref:`dedicated page <cablecell>`.
 
+.. _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.
 
+.. _model_spike_cell:
 3. **Spiking Cells**
 
    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**.
 
+.. _model_bench_cell:
 4. **Benchmark Cells**
 
    Benchmark cells are proxy cells used for benchmarking, and used by developers to benchmark the spike exchange and

doc/concepts/recipe.rst

 .. _modelrecipe:
 
 Recipes
-===============
+=======
 
 An Arbor *recipe* is a description of a model. The recipe is queried during the model
 building phase to provide information about cells in the model, such as:
 
-  * the number of cells in the model;
-  * the type of a cell;
-  * a description of a cell, e.g. with soma, synapses, detectors, stimuli;
-  * the number of spike targets;
-  * the number of spike sources;
-  * the number of gap junction sites;
-  * incoming network connections from other cells terminating on a cell;
-  * gap junction connections on a cell.
-  * probes on a cell.
+  * The **number of cells** in the model.
+  * The **kind** of each cell.
+  * The **description** of each cell, e.g. with morphology, dynamics, synapses, detectors,
+    stimuli etc.
+  * The number of **spike targets**.
+  * The number of **spike sources**.
+  * The number of **gap junction sites**.
+  * Incoming **network connections** from other cells terminating on a cell.
+  * **Gap junction connections** on a cell.
+  * **Probes** on a cell.
+
+To better illustrate the content of a recipe, let's consider the following network of
+three cells:
+
+-  | ``Cell 0``: Is a single soma, with ``hh`` (Hodgkin-huxley) dynamics. In the middle
+     of the soma, a spike detector is attached, it generates a spiking event when the
+     voltage goes above 10 mV. In the same spot on the soma, a current clamp is also
+     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>`,
+     (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.
+     But when the simulation is first set up, it needs to know how cells interact with
+     one another in order to distribute the simulation over the available computational
+     resources. This is why the number of **targets**, **sources** and **gap junction sites**
+     is needed separately from the cell description: with them, the simulation can tell
+     that ``cell 0`` has 1 **spike source** (the detector), 0 **spike targets**, and 0
+     **gap junction sites**, without having to build the cell.
+-  | ``Cell 1``: Is a soma and a single dendrite, with ``passive`` dynamics everywhere.
+     It has a single synapse at the end of the dendrite and a gap junction site in the
+     middle of the soma. This is the **description** of the cell.
+     It's also a cable cell, which is its **cell kind**. It has 0 **spike sources**, 1
+     **spike target** (the synapse) and 1 **gap junction site**.
+-  | ``Cell 2``: Is a soma and a single dendrite, with ``passive`` dynamics everywhere.
+     It has a gap junction site in the middle of the soma. This is the **description**
+     of the cell. It's also a cable cell, which is its **cell kind**. It has 0
+     **spike sources**, 0 **spike targets** and 1 **gap junction site**.
+
+The total **number of cells** in the model is 3. The **kind**, **description** and
+number of **spike sources**, **spike targets** and **gap junction sites** on each cell
+is known and can be registered in the recipe. Next is the cell interaction.
+
+The model is designed such that ``cell 0`` has a spike source, ``cell 1`` has
+a spike target and gap junction site, and ``cell 2`` has a gap junction site. A
+**network connection** can be formed from ``cell 0`` to ``cell 1``; and a
+**gap junction connection** from ``cell 1`` to ``cell 2``. If ``cell 0`` spikes,
+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.
+
+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.
+
+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
+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
+recipe under the hood, and the user need only provide the cell description, and any probes they
+wish to place on the cell.
 
 Why recipes?
---------------
+------------
 
 The interface and design of Arbor recipes was motivated by the following aims: