diff --git a/doc/concepts/cable_cell.rst b/doc/concepts/cable_cell.rst
index b54d8ab9903230d86674c4dfdaa0da8eba8f1301..7042c1973aecdc0c788d74426e1ea36523187c00 100644
--- a/doc/concepts/cable_cell.rst
+++ b/doc/concepts/cable_cell.rst
@@ -3,8 +3,8 @@
Cable cells
===========
-An Arbor *cable cell* is a full description of a cell with morphology and cell
-dynamics like ion species and their properties, ion
+An Arbor *cable cell* is a full :ref:`description <modelcelldesc>` of a cell
+with morphology and cell dynamics like ion species and their properties, ion
channels, synapses, gap junction sites, stimuli and spike detectors.
Cable cells are constructed from three components:
@@ -41,7 +41,7 @@ Once constructed, the cable cell can be queried for specific information about t
.. _cablecell-decoration:
Decoration
-----------------
+----------
The distribution and placement of dynamics on a cable cell is called the *decor* of a cell.
A decor is composed of individual *decorations*, which associate a property or dynamic process
@@ -114,8 +114,8 @@ will override any cell-local or global definition on that region.
.. _cablecell-properties:
-Cable properties
-~~~~~~~~~~~~~~~~
+1. Cable properties
+~~~~~~~~~~~~~~~~~~~
There are four cable properties that must be defined everywhere on a cell:
@@ -149,8 +149,8 @@ specialised on specific regions.
.. _cablecell-density-mechs:
-Density mechanisms
-~~~~~~~~~~~~~~~~~~~~~~
+3. Density mechanisms
+~~~~~~~~~~~~~~~~~~~~~
Regions can have density mechanisms defined over their extents.
Density mechanisms are :ref:`NMODL mechanisms <nmodl>`
@@ -203,8 +203,8 @@ Take for example a mechanism passive leaky dynamics:
.. _cablecell-ions:
-Ion species
-~~~~~~~~~~~
+4. Ion species
+~~~~~~~~~~~~~~
Arbor allows arbitrary ion species to be defined, to extend the default
calcium, potassium and sodium ion species.
@@ -303,32 +303,32 @@ and are assigned to specific locations.
.. _cablecell-synapses:
-Connection sites
-~~~~~~~~~~~~~~~~
+1. Connection sites
+~~~~~~~~~~~~~~~~~~~
Connections (synapses) are instances of NMODL POINT mechanisms. See also :ref:`modelconnections`.
.. _cablecell-gj-sites:
-Gap junction sites
-~~~~~~~~~~~~~~~~~~
+2. Gap junction sites
+~~~~~~~~~~~~~~~~~~~~~
See :ref:`modelgapjunctions`.
.. _cablecell-threshold-detectors:
-Threshold detectors (spike detectors).
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+3. Threshold detectors (spike detectors).
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _cablecell-stimuli:
-Stimuli
-~~~~~~~~
+4. Stimuli
+~~~~~~~~~~
.. _cablecell-probes:
-Probes
-~~~~~~
+5. Probes
+~~~~~~~~~
.. _cablecell-cv-policies:
diff --git a/doc/concepts/labels.rst b/doc/concepts/labels.rst
index 2487ebaa917db359f33a7522d254818f8bfb1e8e..a9a2d4589acfe08379383d476ed12c6b07107724 100644
--- a/doc/concepts/labels.rst
+++ b/doc/concepts/labels.rst
@@ -1,7 +1,7 @@
.. _labels:
-Cell labels
-===========
+Cable cell labels
+=================
Arbor provides a domain specific language (DSL) for describing regions and
locations on morphologies, and a dictionary for associating these descriptions
@@ -44,12 +44,12 @@ tapers from 4 μm to 0.4 μm attached to the proximal end of the soma; and the s
axon proper with constant radius 0.4 μm.
Label types
-------------
+-----------
.. _labels-locset:
Locsets
-~~~~~~~~~~~
+~~~~~~~
A *locset* is a set of locations on a morphology, specifically a *multiset*,
which may contain multiple instances of the same location, for example:
@@ -72,7 +72,7 @@ which may contain multiple instances of the same location, for example:
.. _labels-region:
Regions
-~~~~~~~~~~~~
+~~~~~~~
A *region* is a subset of a morphology's cable segments, for example:
@@ -157,7 +157,7 @@ describes the region of all parts of a cell with either tag 3 or tag 4 and radiu
.. _labels-expr-docs:
Expression syntax
-~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~
The DSL uses `s-expressions <https://en.wikipedia.org/wiki/S-expression>`_, which are composed of the following basic types:
@@ -201,7 +201,7 @@ dendritic tree where the radius first is less than or equal to 0.2 μm.
Locset expressions
-~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~
.. figure:: ../gen-images/label_branch.svg
:width: 800
@@ -348,7 +348,7 @@ Locset expressions
(join (location 1 0.5) (location 2 0.1) (location 1 0.2) (location 1 0.5) (location 4 0))
Region expressions
-~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~
.. label:: (nil)
@@ -570,20 +570,21 @@ Region expressions
Two regions (left and middle) and their intersection (right).
-.. _labels-concretise:
+.. _labels-thingify:
-Concretisation
-----------------
+Thingification
+--------------
-When a region or locset expression is applied to a cell morphology it is
-*concretised*. Concretising a locset will return a set of *locations* on the
-morphology, and concretising a region will return a list of unbranched *cables*
-on the morphology.
+When a region or locset expression is applied to a cell morphology, it is represented
+as a list of unbranched *cables* or a set of *locations* on the morphology.
+This process is called ``thingify`` in arbor, because it turns the abstract description
+of a region or a loscet into an actual 'thing' when it is applied to a real morphology.
.. note::
Applying an expression to different morphologies may give different
- concretised results.
+ thingified results.
+.. _labels-locations:
Locations
~~~~~~~~~
@@ -599,8 +600,9 @@ Examples of locations, :ref:`expressed using the DSL <labels-location-def>`, inc
* The end of branch 5 ``(location 5 1)``.
* One quarter of the way along branch 5 ``(location 5 0.25)``.
+.. _labels-cables:
Cables
-~~~~~~~~~
+~~~~~~
An unbranched *cable* is a tuple of the form ``(branch, prox, dist)``,
where ``branch`` is the branch id, and ``0 ≤ prox ≤ dist ≤ 1`` define the relative position
@@ -631,6 +633,22 @@ also be valid expressions in the region DSL; creating a label ``"(tag 1)"`` will
lead to confusion.
Labels are stored with their associated expressions as key-value pairs in *label dictionaries*.
+Label dictionaries are then used to create a cable-cell along with the :ref:`morphology <co_morphology>`
+and a :ref:`decor <cablecell-decoration>`. The decorations can be painted or placed on
+the regions or locsets defined in the label dictionary by referring to their labels.
+
+.. code-block:: python
+ :caption: Example of a lable dictionary in python:
+
+ arbor.label_dict({
+ 'soma': '(tag 1)', # soma is every cable with tag 1 in the morphology.
+ 'axon': '(tag 2)', # axon is every cable with tag 2 in the morphology.
+ 'dend': '(tag 3)', # dend is every cable with tab 3 in the morphology
+ 'root': '(root)', # typically the start of the soma is at the root of the cell.
+ 'stim_site': '(location 0 0.5)', # site for the stimulus, in the middle of branch 0.
+ 'axon_end': '(restrict (terminal) (region "axon"))'} # end of the axon.
+ })
+
API
diff --git a/doc/concepts/mechanisms.rst b/doc/concepts/mechanisms.rst
index f8072c14b53643da6c54d19201b6eac2a9229f15..e507443090c2d7af47befa0ba0b564695ff5d2d4 100644
--- a/doc/concepts/mechanisms.rst
+++ b/doc/concepts/mechanisms.rst
@@ -1,7 +1,7 @@
.. _mechanisms:
-Cell mechanisms
-===============
+Cable cell mechanisms
+=====================
Mechanisms describe biophysical processes such as ion channels and synapses.
Mechanisms are assigned to regions and locations on a cell morphology
@@ -9,8 +9,15 @@ through the process of :ref:`decoration <cablecell-decoration>`.
Mechanisms are described using a dialect of the :ref:`NMODL <nmodl>` domain
specific language that is similarly used in `NEURON <https://neuron.yale.edu/neuron/>`_.
+Arbor supports mechanism descriptions using the NMODL language through our ``modcc``
+compiler. ``modcc`` supports many of NMODL's features but there are a few
+additional `guidelines <https://github.com/arbor-sim/arbor/wiki/Arbor's-NMODL-guidlines>`_
+for users who wish to compile their own mechanisms for Arbor. Unfortunately, out-of-tree
+mechanism building is not yet supported in Arbor. However, we have many built-in mechanisms
+that can be used, which are oragnized in *mechanism catalogues*.
+
Mechanism catalogues
-----------------------
+--------------------
A *mechanism catalogue* is a collection of mechanisms that maintains:
@@ -19,7 +26,14 @@ A *mechanism catalogue* is a collection of mechanisms that maintains:
global parameters, ion bindings, and implementations.
3. A map for looking up a concrete mechanism implementation on a target hardware back end.
-Derived mechanisms will always have a different name to the mechanism from which they are derived. This name is given explicitly when the derivation is constructed, or implicitly when a mechanism is :ref:`requested <mechanisms-name-note>` with a name of the form ``"mech/param=value,..."``. In this instance, if a mechanism of that name does not already exist in the catalogue, it will be implicitly derived from an existing mechanism ``"mech"`` with global parameters and ion bindings set according to the assignments following the slash. If the mechanism ``"mech"`` depends upon only a single ion, the name of that ion can be omitted in the assignments: ``"mech/oldion=newion"`` and ``"mech/newion"`` are equivalent derivations.
+Derived mechanisms will always have a different name to the mechanism from which they are derived.
+This name is given explicitly when the derivation is constructed, or implicitly when a mechanism
+is :ref:`requested <mechanisms-name-note>` with a name of the form ``"mech/param=value,..."``.
+In this instance, if a mechanism of that name does not already exist in the catalogue, it will be
+implicitly derived from an existing mechanism ``"mech"`` with global parameters and ion bindings
+set according to the assignments following the slash. If the mechanism ``"mech"`` depends upon
+only a single ion, the name of that ion can be omitted in the assignments:
+``"mech/oldion=newion"`` and ``"mech/newion"`` are equivalent derivations.
Catalogues provide an interface for querying mechanism metadata, which includes the following information:
@@ -27,10 +41,18 @@ Catalogues provide an interface for querying mechanism metadata, which includes
* Global parameter names, units, and default values.
* Range parameter names, units, and default values.
* State variable names, units and default values.
-* Ion dependencies: for each ion used by the mechanism, information on whether the mechanism writes to its internal or external concentration or to its reversal potential value, and whether it reads or asserts the ionic charge.
+* Ion dependencies: for each ion used by the mechanism, information on whether the mechanism writes
+ to its internal or external concentration or to its reversal potential value, and whether it reads
+ or asserts the ionic charge.
+
+Arbor provides a default catalogue of mechanisms as well as two other catalogues containing the sets of common mechanisms
+used by the `Allen Institute <https://alleninstitute.org/>`_ and the `Blue Brain Project <https://portal.bluebrain.epfl.ch/>`_.
+(Find the NMODL decsriptions of the `default mechanisms <https://github.com/arbor-sim/arbor/tree/master/mechanisms/default>`_,
+the `Allen institute mechanisms <https://github.com/arbor-sim/arbor/tree/master/mechanisms/allen>`_ and
+the `BBP mechanisms <https://github.com/arbor-sim/arbor/tree/master/mechanisms/bbp>`_ at the provided links.)
-Default mechanisms
-''''''''''''''''''
+Default catalogue
+'''''''''''''''''
Arbor provides a default catalogue with the following mechanisms:
@@ -103,9 +125,9 @@ computing ionic reversal potentials.
Density mechanisms
''''''''''''''''''''''
-Density mechanisms are :ref:`NMODL mechanisms <nmodl>`
-which describe biophysical processes that are distributed in space, but whose behaviour
-is defined purely by the state of the cell and the process at any given point.
+Density mechanisms describe biophysical processes that are distributed in space,
+but whose behaviour is defined purely by the state of the cell and the process
+at any given point.
Density mechanisms are commonly used to describe ion channel dynamics,
for example the ``hh`` and ``pas`` mechanisms provided by NEURON and Arbor,
diff --git a/doc/concepts/morphology.rst b/doc/concepts/morphology.rst
index 6d73c1d7704629706cc4579697d934e77dd081b5..769c5c95424d852858db840cc6eee7920b5e6358 100644
--- a/doc/concepts/morphology.rst
+++ b/doc/concepts/morphology.rst
@@ -1,15 +1,16 @@
.. _morph:
-Cell morphology
-===============
+Cable cell morphology
+=====================
A cell's *morphology* describes both its geometry and branching structure.
Morphologies in Arbor are modelled as a set of one dimensional cables of variable radius,
-joined together to form a tree.
+joined together to form a tree. Only :ref:`cable cells <modelcablecell>` support custom
+morphologies in Arbor.
-The building blocks of morphology tree are points and segments.
-A *point* is a three-dimensional location and a radius, used to mark the centre and radius
-of the cable.
+The building blocks of a morphology tree are points and segments.
+A *point* is a three-dimensional location and a radius, used to mark the cross-sectional
+centre and radius of the cable.
.. csv-table::
:widths: 10, 10, 30
@@ -140,11 +141,11 @@ uses 4 segments to model the soma.
.. _morph-morphology:
-Geometry
---------
+Morphology
+----------
-A *morphology* describes the geometry of a cell as unbranched cables with variable radius
-, and their associated tree structure.
+A *morphology* describes the geometry of a cell as unbranched cables with variable radius,
+and their associated tree structure.
Every segment tree can be used to generate a unique morphology, which derives and enumerates
*branches* from the segments.
The branches of a morphology are unbranched cables, composed of one or more segments, where:
@@ -183,7 +184,7 @@ which is illustrated along with its branches below.
:align: center
The code used to generate this morphology is in the :class:`segment_tree<arbor.segment_tree>`
- documentation :ref:`below <morph-label-seg-code>`.
+ :ref:`python documentation <morph-label-seg-code>`.
The first branch contains the soma and the first two segments of the dendritic tree.
There are four more branches in the dendritic tree, and one representing the two
@@ -271,6 +272,18 @@ multiple soma and dendrite segments in branch 0.
ion channels, by using referring to all parts of the cell with
:ref:`tag 1 <labels-expressions>`.
+.. Note::
+ This representation of the cell morphology in terms of *branches* is what
+ Arbor uses to create a :ref:`cable cell <cablecell>`, and it is how Arbor
+ view's the cell's geometry and refers to it internally.
+ :ref:`Regions <labels-region>` and :ref:`locsets <labels-locset>` formed
+ on the cell, are eventually represented either as
+ :ref:`subsets of branches <labels-cables>` of the morphology, or exact
+ :ref:`locations on branches <labels-locations>` of the morphology.
+
+ Once the morphology is formed from a segment tree, the specific segments
+ are no longer of much use for the user and it is better to think of the
+ cell structure as Arbor does: in terms of branches.
Examples
~~~~~~~~~~~~~~~
@@ -492,8 +505,11 @@ SWC
Arbor supports reading morphologies described using the
`SWC <http://www.neuronland.org/NLMorphologyConverter/MorphologyFormats/SWC/Spec.html>`_ file format.
-SWC files may contain comments, which are stored as metadata. A blank line anywhere in the file is
-interpreted as end of data. The description of the morphology is encoded as a list of samples with an id,
+
+SWC files may contain comments, which are stored as metadata. And a blank line anywhere in the file is
+interpreted as end of data.
+
+The description of the morphology is encoded as a list of samples with an id,
an `x,y,z` location in space, a radius, a tag and a parent id. Arbor parses these samples, performs some checks,
then generates a morphology according to one of three possible interpretations.
@@ -575,6 +591,45 @@ interpreter:
* To create a segment with a certain tag, that is to be attached to the soma, we need at least 2 samples with that
tag.
+NeuroML
+~~~~~~~
+
+Arbor offers limited support for models described in `NeuroML version 2 <https://neuroml.org/neuromlv2>`_.
+This is not built by default (see :ref:`NeuroML support <install-neuroml>` for instructions on how
+to build arbor with NeuroML).
+
+Once support is enabled, Arbor is able to parse and check the validity of morphologies described in NeuroML files,
+and present the encoded data to the user. This is more than a simple a `segment tree`.
+
+NeuroML can encode in the same file multiple top-level morphologies, as well as cells:
+
+.. code:: XML
+
+ <neuroml xmlns="http://www.neuroml.org/schema/neuroml2">
+ <morphology id="m1">
+ <segment id="seg-0">
+ <proximal x="1" y="1" z="1" diameter="1"/>
+ <distal x="2" y="2" z="2" diameter="2"/>
+ </segment>
+ <segmentGroup id="group-0">
+ <member segment="1"/>
+ </segmentGroup>
+ </morphology>
+ <morphology id="m2"/>
+ <cell id="c1" morphology="m1"/>
+ <cell id="c2">
+ <morphology id="m3"/>
+ </cell>
+ </neuroml>
+
+The above NeuroML description defines 2 top-level morphologies ``m1`` and ``m2`` (empty); a cell ``c1`` that uses
+morphology ``m1``; and a cell ``c2`` that uses an internally defined (empty) morphology ``m3``.
+
+Arbor can query the cells and morphologies using their ids and return all the associated morphological data for each.
+The morphological data includes the actual morphology as well as the named segments and groups of the morphology.
+For example, the above ``m1`` morphology has one named segment ``seg-0`` and one named group ``group-0`` that are
+both represented using Arbor's :ref:`region expressions <labels-expressions>`.
+
API
---
diff --git a/doc/python/labels.rst b/doc/python/labels.rst
index d4aa13c9bac142fc5ed838eb5e3743e37bcd75ad..37492a2a6f08209272a7b570ca7fd77d598c52a5 100644
--- a/doc/python/labels.rst
+++ b/doc/python/labels.rst
@@ -115,7 +115,7 @@ two labels refer to one another:
.. note::
In the example above there will be no error when the label dictionary is defined.
Instead, there will be an error later when the label dictionary is applied to
- a morphology, and the cyclic dependency is detected when concretising the locations
+ a morphology, and the cyclic dependency is detected when thingifying the locations
in the locsets and the cable segments in the regions.