From d6e990d0c4cf179728b2d9c89a46429733c9e24f Mon Sep 17 00:00:00 2001
From: Nora Abi Akar <nora.abiakar@gmail.com>
Date: Mon, 29 Mar 2021 16:21:03 +0200
Subject: [PATCH] Update nmodl guidelines (#1468)
---
doc/concepts/mechanisms.rst | 2 +-
doc/fileformat/nmodl.rst | 30 +++++++++++++++++-------------
2 files changed, 18 insertions(+), 14 deletions(-)
diff --git a/doc/concepts/mechanisms.rst b/doc/concepts/mechanisms.rst
index ca36c542..4e1d45a1 100644
--- a/doc/concepts/mechanisms.rst
+++ b/doc/concepts/mechanisms.rst
@@ -11,7 +11,7 @@ specific language that is similarly used in `NEURON <https://neuron.yale.edu/neu
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>`_
+additional :ref:`guidelines <formatnmodl>`.
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*.
diff --git a/doc/fileformat/nmodl.rst b/doc/fileformat/nmodl.rst
index a6fd8701..5bc538da 100644
--- a/doc/fileformat/nmodl.rst
+++ b/doc/fileformat/nmodl.rst
@@ -9,9 +9,9 @@ which provides the mod2c compiler parses dynamics described in NMODL to
generate C code that is called from NEURON.
Arbor has an NMODL compiler, *modcc*, that generates
-optimized code in C++ and CUDA, which is optimzed for
+optimized code in C++ and CUDA, which is optimized for
the target architecture. NMODL does not have a formal specification,
-and its semantis are often
+and its semantics are often
ambiguous. To manage this, Arbor uses its own dialect of NMODL that
does not allow some constructions used in NEURON's NMODL.
@@ -22,14 +22,14 @@ does not allow some constructions used in NEURON's NMODL.
that you have about getting your NMODL files to work in Arbor.
This page is a collection of NMODL rules for Arbor. It assumes that the reader
-alreay has a working knowledge of NMODL.
+already has a working knowledge of NMODL.
Ions
-----
* Arbor recognizes ``na``, ``ca`` and ``k`` ions by default. Any new ions
- must be added explicitly in Arbor along with their default properties and
- valence (this can be done in the recipe or on a single cell model).
+ used in NMODL need to be explicitly added into Arbor along with their default
+ properties and valence (this can be done in the recipe or on a single cell model).
Simply specifying them in NMODL will not work.
* The parameters and variables of each ion referenced in a ``USEION`` statement
are available automatically to the mechanism. The exposed variables are:
@@ -51,22 +51,24 @@ Special variables
* Arbor exposes some parameters from the simulation to the NMODL mechanisms.
These include ``v``, ``diam``, ``celsius`` and ``t`` in addition to the previously
mentioned ion parameters.
-* The ``area`` is not currently exposed to NMODL.
-* Special variables should not be ``ASSIGNED`` or ``CONSTANT``, they are
+* These special variables should not be ``ASSIGNED`` or ``CONSTANT``, they are
``PARAMETER``. This is different from NEURON where a built-in variable is
declared ``ASSIGNED`` to make it accessible.
-* ``diam`` and ``celsius`` can be set from the simulation side.
-* ``v`` is a reserved variable name and can be written in NMODL.
-* If Special variables are used in a ``PROCEDURE`` or ``FUNCTION``, they need
- to be passed as arguments.
+* ``diam`` and ``celsius`` are set from the simulation side.
+* ``v`` is a reserved variable name and can be read but not written in NMODL.
* ``dt`` is not exposed to NMODL mechanisms.
+* ``area`` is not exposed to NMODL mechanisms.
+* ``NONSPECIFIC_CURRENTS`` should not be ``PARAMETER``, ``ASSIGNED`` or ``CONSTANT``.
+ They just need to be declared in the NEURON block.
-Functions and blocks
----------------------
+Functions, procedures and blocks
+--------------------------------
* ``SOLVE`` statements should be the first statement in the ``BREAKPOINT`` block.
* The return variable of ``FUNCTION`` has to always be set. ``if`` without associated
``else`` can break that if users are not careful.
+* Any non-``LOCAL`` variables used in a ``PROCEDURE`` or ``FUNCTION`` need to be passed
+ as arguments.
Unsupported features
--------------------
@@ -80,6 +82,8 @@ Unsupported features
* ``TABLE`` is not supported, calculations are exact.
* ``derivimplicit`` solving method is not supported, use ``cnexp`` instead.
* ``VERBATIM`` blocks are not supported.
+* ``LOCAL`` variables outside blocks are not supported.
+* ``INDEPENDENT`` variables are not supported.
Arbor-specific features
-----------------------
--
GitLab