From 0d1987c5ed2f79d2983904e797370f8569248f49 Mon Sep 17 00:00:00 2001
From: Han Lu <11597940+ErbB4@users.noreply.github.com>
Date: Thu, 1 Aug 2024 10:13:40 +0200
Subject: [PATCH] type setting (#2304)
<!-- Please make sure your PR follows our [contribution
guidelines](https://github.com/arbor-sim/arbor/tree/master/doc/contrib)
and agree to the terms outlined in the [PR
procedure](https://github.com/arbor-sim/arbor/tree/master/doc/contrib/pr.rst).
-->
---------
Co-authored-by: Thorsten Hater <24411438+thorstenhater@users.noreply.github.com>
---
doc/tutorial/nmodl.rst | 68 ++++++++++++++++++++----------------------
1 file changed, 33 insertions(+), 35 deletions(-)
diff --git a/doc/tutorial/nmodl.rst b/doc/tutorial/nmodl.rst
index e14e9399..b32572bd 100644
--- a/doc/tutorial/nmodl.rst
+++ b/doc/tutorial/nmodl.rst
@@ -3,7 +3,7 @@
How to use NMODL to extend Arbor's repertoire of Ion Channels
=============================================================
-NMODL is Arbor's way of expressing ion channel dynamics which in turn can be
+NMODL is Arbor's way of expressing ion channel dynamics, which in turn can be
added to cable cells via the :ref:`decor` interface. This tutorial will guide
you through to create such an ion channel from scratch. Note that there are
already large selections of channels built into Arbor in addition to online
@@ -17,9 +17,9 @@ Introducing NMODL
NMODL is a domain specific language (DSL) for design electro-chemical dynamics
deriving from the earlier MODL language. It is used by Arbor, Neuron, and
-and CoreNeuron. Although each software has its own dialect, the core ideas are
+CoreNeuron. Although each software has its own dialect, the core ideas are
identical. Unfortunately, documentation for both NMODL and MODL is scarce and
-outdated. This tutorial aims to get you proficient in writing and adapting ion
+outdated. This tutorial aims to help you become proficient in writing and adapting ion
channels for Arbor. Note that while we focus on density mechanisms here, there
is a host of behaviours customisable in Arbor through NMODL in addition to
wholly new functionality, examples include gap junctions, synapses, and voltage
@@ -91,26 +91,26 @@ This should --- once run --- produce a plot like this:
:width: 600
:align: center
-You can find all steps in the ``python/example/hh`` directory in Arbor's source
+You can find all the steps in the ``python/example/hh`` directory in Arbor's source
code. Let's return to what just happened, it's quite a bit. First, we added our
ion channel and used ``arbor-build-catalogue`` to translate it into a form Arbor
can utilize. These collections of ion channels are --- unsurprisingly --- called
catalogues, see :ref:`mechanisms`. We pulled this into our model by loading and
-assigning to the model.
+assigning it to the model.
Next, let's look at the output graph. We observe a sudden jump in potential
during the period the current clamp is active. As Arbor's model for a single CV
-cable cell is :math:`\partial_t U_m = i_e - i_m` (for multi-CV cells we have
+cable cell is :math:`\partial_t U_m = i_e - i_m` (for multi-CV cells, we have
additional terms that can be neglected here, see :ref:`cable_cell`), this
behaviour is expected. The current clamp provides a positive :math:`i_e` and our
-ion channel model is supplying the trans-membrane current :math:`i_m = 0`. To
+ion channel model supplies the trans-membrane current :math:`i_m = 0`. To
understand the latter part, consider the channel model file we just added
.. literalinclude:: ../../python/example/hh/mod/hh02.mod
:lines: 1-4
This is the ``NEURON`` block declaring the channel's name, here ``hh02``, which
-is used when adding channels from a catalogue. Files that put ``SUFFIX`` in
+is used when channels from a catalogue. Files that put ``SUFFIX`` in
front of the name are converted to density channels, as opposed to synapses
(``POINT_PROCESS``) and gap junctions (``JUNCTION_PROCESS``). In addition to
naming the channel, we also need to set up all variables used to interface with
@@ -123,7 +123,7 @@ ion and thus can represent all ion currents we do not model explicitly as a lump
sum. When computing ``i_m`` for the cable equation above, Arbor takes the sum
over all non-specific and ion currents across all ion channels on the
current CV. We will revisit the ``NEURON`` multiple times later on, but for now
-we turn to
+we turn to:
.. literalinclude:: ../../python/example/hh/mod/hh02.mod
:lines: 6-8
@@ -131,8 +131,8 @@ we turn to
During the integration of the cable equation, Arbor will evaluate this block to
update its internal picture of the currents, i.e. to calculate ``i_m``. This
occurs at an unspecified moment of the execution and might even be done multiple
-times, so we need to take care not to depend on execution order. We are
-_expected_, yet not forced by the tooling to update all such outputs, so, again,
+times, so we need to take care not to depend on the execution order. We are
+_expected_, yet not forced by the tooling, to update all such outputs, so, again,
some care is needed.
Stepping Stone: Leak
@@ -162,13 +162,13 @@ steps are completed at the beginning of each new section:
- After each change to the NMODL file, you'll need to call ``arbor-build-catalogue cat mod``
-Keep this in mind, while we start altering the NMODL file to produce a more
-sensible current. Let's start with the current itself
+Keep this in mind while we start altering the NMODL file to produce a more
+sensible current. Let's start with the current itself:
.. literalinclude:: ../../python/example/hh/mod/hh03.mod
:lines: 11-13
-this will pull the membrane potential ``v`` towards a resting potential ``el``
+This will pull the membrane potential ``v`` towards a resting potential ``el``
since our reduced cable equation is now :math:`\partial_t U_m = i_e - g_l\cdot(U_m -
E_l)`. The membrane potential is available in NMODL as a read-only built-in
symbol ``v`` and can be used in any ion channel. However, we need a way to set
@@ -178,11 +178,11 @@ by adding a new block to the NMODL file:
.. literalinclude:: ../../python/example/hh/mod/hh03.mod
:lines: 6-10
-these parameters have an optional default value and a likewise optional unit.
+These parameters have an optional default value and a likewise optional unit.
Both are helpful to have, though. The units chosen internally by Arbor come
together such that the conductivity *must* have units ``S/cm2``. Note that there
-is neither a check nor a conversion of units, the annotation serves purely as a
-reminder to us. Now, running the example ``step-03.py`` gives us the expected
+is neither a check nor a conversion of units; the annotation serves purely as a
+reminder. Now, running the example ``step-03.py`` gives us the expected
result of the membrane potential returning to the resting value:
.. figure:: ../images/hh-03.svg
@@ -208,7 +208,7 @@ To enable this, we need to tell NMODL that each CV will have its own value of
.. literalinclude:: ../../python/example/hh/mod/hh03.mod
:lines: 1-5
-Without this addition, there would be one, global copy for each, which could be
+Without this addition, there would be one global copy for each, which could be
set by writing
.. code-block:: python
@@ -221,13 +221,12 @@ set by writing
instead. Parameters are either ``GLOBAL`` or ``RANGE``, never both. The
difference is subtle and non-existent for our single CV. The rule of thumb is
-that if you expect that a parameter varies smoothly across the neuron, make it
+that if you expect a parameter to vary smoothly across the neuron, make it
``RANGE`` and if you expect discrete, clearly delineated regions with
-discontinuous values, go for ``GLOBAL``. If in doubt, choose ``RANGE``.
-Performance-wise, ``GLOBAL`` is more efficient as ``RANGE`` parameter consume
-one memory location per CV *and* require one memory access each. ``GLOBAL``
-requires one location and access *regardless* of CV count. So, if speed is an
-issue, consider ``GLOBAL`` unless required otherwise.
+discontinuous values, go for ``GLOBAL``. Comparing the performance impact of parameters, ``GLOBAL`` is more efficient than ``RANGE``.
+While ``RANGE`` parameters consume one memory location (and access) per CV, those tagged ``GLOBAL``
+require only one location (and access) *regardless* of CV count. Thus, all things being equal, prefer ``GLOBAL``.
+
Differential Equations in NMODL
-------------------------------
@@ -266,7 +265,7 @@ this to (the end of) ``hh04.mod``:
.. literalinclude:: ../../python/example/hh/mod/hh04.mod
:lines: 49-55
-The ``FUNCTION`` constructs introduces a function which can only access its
+The ``FUNCTION`` construct introduces a function which can only access its
parameters and can have no side-effects like writing to global variables. Its
return value is set by formally assigning a value to the function's name.
Arbor provides some builtin functions like ``exprelr``, which is used here,
@@ -296,8 +295,8 @@ be tempted to add something like this to the ``BREAKPOINT`` block (notice the
il = gl*(v - el)
}
-and attempt to solving the ODE manually via Euler's method. Alas, this is
-inconvenient and cumbersome as we needed to adapted the ion channel's ``paint``
+and attempt to solve the ODE manually via Euler's method. Alas, this is
+inconvenient and cumbersome as we needed to adapt the ion channel's ``paint``
call every time we change the time step ``dt`` (assuming we pass it as a
parameter). It's also less accurate than desirable. What's more, as we don't
know the order and count of evaluation of these blocks, it's also likely to be
@@ -310,7 +309,7 @@ variable. Add this in your NMODL file
:lines: 11-12,30-37
Now we have told NMODL how to compute the derivative of ``n``. For an initial
-value problem, we also need to add its initial value and to actually *solve*
+value problem, we also need to add its initial value and actually *solve*
the ODE. This is achieved by
.. literalinclude:: ../../python/example/hh/mod/hh04.mod
@@ -353,9 +352,8 @@ reproduce ``hh05.mod`` here as a reference.
Things to take note of here is ``celsius``, which contains the temperature in
degrees Celsius. While it is listed as ``PARAMETER`` here, it is not a real
-parameter, but rather a builtin variable. Adding it to ``PARAMETER`` makes it
-available in the NMODL file. Adding the potential here, too, is not needed,
-considered good form. Using ``ASSIGNED`` over ``LOCAL`` here is again a
+parameter but rather a built-in variable. Adding it to ``PARAMETER`` makes it
+available in the NMODL file. Adding the potential here, too, is not required but is considered good form. Using ``ASSIGNED`` over ``LOCAL`` here is again a
performance consideration. While costing memory capacity and operations, the
exponentiation is expensive enough to warrant the expense. This simulation
results in:
@@ -370,7 +368,7 @@ Your own Journey
Now, you are free to either explore implementing ``ina`` on your own or to
look up how we did it in ``hh06.mod`` and ``step-06.py``.
-If you want to try it, but need a hint, here's a rough outline:
+If you want to try it but need a hint, here's a rough outline:
1. Add a declaration of the sodium ion and its variables to the ``NEURON`` block
2. Add a parameter for the conductivity
@@ -389,7 +387,7 @@ as the basis for all complex networks as simulated by Arbor or Neuron. Even
modern attempts at addressing the same problems, like NeuroML2, are translated
into NMODL. Almost all existing models are rooted in NMODL.
-We did introduce most relevant constructs here, with some notable exceptions
+We did introduce the most relevant constructs here, with some notable exceptions
like ``KINETIC`` and ``NET_RECEIVE``. We will possibly return to them in the
future. Note that NMODL is significantly more complex than we have shown here,
but these constructs can be avoided almost entirely and/or do not apply to
@@ -404,8 +402,8 @@ the exponential synapse coming with Arbor.
.. literalinclude:: ../../mechanisms/default/expsyn.mod
-The differences to density mechanisms like ``hh`` are fairly minimal on the
-surface, instead of ``SUFFIX`` we write ``POINT_PROCESS`` in front of the name.
+The differences in density mechanisms like ``hh`` are fairly minimal on the
+surface; instead of ``SUFFIX``, we write ``POINT_PROCESS`` in front of the name.
The rest can be summarised as follows: We have a non-specific current ``i``
driving the model towards the resting potential ``e``, which is proportional to
the conductivity ``g``. The conductivity ``g`` itself decays exponentially
--
GitLab