diff --git a/doc/cpp/cable_cell.rst b/doc/cpp/cable_cell.rst index 0a8b43666fc34877138b0596d6da77214b5f925c..ea800af33547f1ee834d9d74394987061e433bf3 100644 --- a/doc/cpp/cable_cell.rst +++ b/doc/cpp/cable_cell.rst @@ -257,6 +257,8 @@ assign them to the :cpp:expr:`default_parameters` field of the global properties object returned in the recipe. +.. _cppcablecell-revpot: + Reversal potential dynamics --------------------------- diff --git a/doc/fileformat/nmodl.rst b/doc/fileformat/nmodl.rst index 961ce25c842bfa06e668fec757a5385f2c125134..51d5f378465fedcebe059f7d14067633f765b1fa 100644 --- a/doc/fileformat/nmodl.rst +++ b/doc/fileformat/nmodl.rst @@ -48,7 +48,7 @@ Ions they need to be passed as arguments. * If ``Xi`` or ``Xo`` (internal and external concentrations) are written in the NMODL mechanism they need to be declared as ``STATE`` variables and their initial - values have to be set in the mechanism. + values have to be set in the ``INITIAL`` block in the mechanism. Special variables ----------------- @@ -113,4 +113,52 @@ Arbor-specific features * Arbor allows a gap-junction mechanism to access the membrane potential at the peer site of a gap-junction connection as well as the local site. The peer membrane potential is made available through the ``v_peer`` variable while the local membrane potential - is available through ``v``, as usual. \ No newline at end of file + is available through ``v``, as usual. + +Nernst +------ +Many mechanisms make use of the reversal potential of an ion (``eX`` for ion ``X``). +A popular equation for determining the reversal potential during the simulation is +the `Nernst equation <https://en.wikipedia.org/wiki/Nernst_equation>`_. +Both Arbor and NEURON make use of ``nernst``. Arbor implements it as a mechanism and +NEURON implements it as a built-in method. However, the conditions for using the +``nernst`` equation to change the reversal potential of an ion differ between the +two simulators. + +1. In Arbor, the reversal potential of an ion remains equal to its initial value (which +has to be set by the user) over the entire course of the simulation, unless another +mechanism which alters that reversal potential (such as ``nernst``) is explicitly selected +for the entire cell. (see :ref:`cppcablecell-revpot` for details). + +.. NOTE: + This means that a user cannot indicate to use ``nernst`` to calculate the reversal + potential on some regions of the cell, while other regions of the cell have a constant + reversal potential. It's either applied on the entire cell or not at all. This differs + from NEURON's policy. + +2. In NEURON, there is a rule which is evaluated (under the hood) per section of a given +cell to determine whether or not the reversal potential of an ion remains constant or is +calculated using ``nernst``. The rule is documented +`here <https://neuron.yale.edu/neuron/static/new_doc/modelspec/programmatic/ions.html>`_ +and can be summarized as follows: + + Examining all mechansims on a given section, if the internal or external concentration of + an ion is **written**, and its reversal potential is **read but not written**, then the + nernst equation is used **continuously** during the simulation to update the reversal + potential of the ion. + And if the internal or external concentration of an ion is **read**, and its reversal + potential is **read but not written**, then the nernst equation is used **once** at the + beginning of the simulation to caluclate the reversal potential of the ion, and then + remains constant. + Otherwise, the reversal potential is set by the user and remains constant. + +One of the main consequences of this difference in behavior is that in Arbor, a mechanism +modifying the reversal potential (for example ``nernst``) can only be applied (for a given ion) +at a global level on a given cell. While in Neuron, different mechanisms can be used for +calculating the reversal potential of an ion on different parts of the morphology. +This is due to the different methods Arbor and NEURON use for discretising the morphology. +(A ``region`` in Arbor may include part of a CV, where as in NEURON, a ``section``can only +contain full ``segments``). + +Modelers are encouraged to verify the expected behavior of the reversal potentials of ions +as it can lead to vastly different model behavior.