diff --git a/doc/concepts/cell.rst b/doc/concepts/cell.rst
index b9440000ae1b89f7bd44a447ac0a75db2a07e190..c60ece393b54bcf5255f06af31c72b44cc8845c0 100644
--- a/doc/concepts/cell.rst
+++ b/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
---
diff --git a/doc/concepts/domdec.rst b/doc/concepts/domdec.rst
index a98b1b75116ac0b4337eecbfdcb0e994e92f08d2..137b502df5ec3f7fe0f64bb38755b2bc5165781f 100644
--- a/doc/concepts/domdec.rst
+++ b/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
diff --git a/doc/concepts/hardware.rst b/doc/concepts/hardware.rst
index 4aea89e622b7a8810d69f5e9bf11bc6893db1e30..46832078539111e9002d66da9a5652538b34b6d8 100644
--- a/doc/concepts/hardware.rst
+++ b/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
-----------------
diff --git a/doc/concepts/index.rst b/doc/concepts/index.rst
index 8c4399749b5ffe30a9dc0a482806c948ddf8f7e3..4f9391c01512b82ce14898efe3d21086bcd384fe 100644
--- a/doc/concepts/index.rst
+++ b/doc/concepts/index.rst
@@ -1,7 +1,7 @@
.. _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
diff --git a/doc/concepts/interconnectivity.rst b/doc/concepts/interconnectivity.rst
index a45c8019b2fb6c155a937fb7057fec38dc374dba..4e746349c7c2c88dacd7f4924523dca7a78907a7 100644
--- a/doc/concepts/interconnectivity.rst
+++ b/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.
diff --git a/doc/concepts/recipe.rst b/doc/concepts/recipe.rst
index 7548c9246630632a8c195b6a486fd8644eb7a22a..8223f321e3ee2987a23f8d9cab79855a9252222d 100644
--- a/doc/concepts/recipe.rst
+++ b/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
diff --git a/doc/concepts/simulation.rst b/doc/concepts/simulation.rst
index f5d288420e744a8e1eb6a559e5c07bbe68644639..abce937b20be8fb7b3f38cb81c58c4f098651bf2 100644
--- a/doc/concepts/simulation.rst
+++ b/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
---