diff --git a/doc/concepts/cell.rst b/doc/concepts/cell.rst
index 5f9865bfd8d138b0d9976fd4e55af0c6f7c443e1..b9440000ae1b89f7bd44a447ac0a75db2a07e190 100644
--- a/doc/concepts/cell.rst
+++ b/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
diff --git a/doc/concepts/recipe.rst b/doc/concepts/recipe.rst
index 05ff1285c158b074a60ab83cac9853ab5f4a5650..a3c091246c7b62f564f3bbbbca0ca3997d51607c 100644
--- a/doc/concepts/recipe.rst
+++ b/doc/concepts/recipe.rst
@@ -1,23 +1,81 @@
.. _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: