Merge branch 'master' into jelic/remove_pkg_resources

.bbp-project.yaml

@@ -5,6 +5,7 @@ tools:
       match:
       - ext/.*
       - src/language/templates/*
+      - test/usecases/*/*
   ClangTidy:
     enable: true
     option: ''

.github/workflows/nmodl-ci.yml

@@ -127,6 +127,7 @@ jobs:
           fi
           cmake_args+=(-DCMAKE_CXX_COMPILER=${CXX} \
                        -DCMAKE_CXX_COMPILER_LAUNCHER=ccache)
+          cmake_args+=(-DNMODL_ENABLE_BACKWARD=On)
           cmake .. "${cmake_args[@]}"
         env:
           INSTALL_DIR: ${{ runner.workspace }}/install

.gitmodules

@@ -22,3 +22,9 @@
 [submodule "ext/catch2"]
 	path = ext/catch2
 	url = https://github.com/catchorg/Catch2.git
+[submodule "ext/backward"]
+	path = ext/backward
+	url = https://github.com/bombela/backward-cpp.git
+[submodule "test/usecases/references"]
+	path = test/usecases/references
+	url = https://github.com/BlueBrain/nmodl-references.git

CMakeLists.txt

@@ -21,6 +21,7 @@ option(NMODL_ENABLE_PYTHON_BINDINGS "Enable pybind11 based python bindings" ON)
 option(NMODL_ENABLE_TESTS "Enable build of tests" ON)
 option(NMODL_ENABLE_USECASES
        "If building tests, additionally enable build of usecase tests. Requires neuron." OFF)
+option(NMODL_ENABLE_BACKWARD "Use backward, enables blame." OFF)
 set(NMODL_EXTRA_CXX_FLAGS
     ""
     CACHE STRING "Add extra compile flags for NMODL sources")
@@ -131,6 +132,10 @@ if(NMODL_3RDPARTY_USE_SPDLOG)
 endif()
 cpp_cc_git_submodule(spdlog BUILD PACKAGE spdlog REQUIRED)
 
+if(NMODL_ENABLE_BACKWARD)
+  cpp_cc_git_submodule(backward BUILD PACKAGE backward REQUIRED)
+endif()
+
 # =============================================================================
 # Format & execute ipynb notebooks in place (pip install nbconvert clean-ipynb)
 # =============================================================================

CONTRIBUTING.rst

@@ -165,6 +165,33 @@ The HPC coding conventions formatter installs any dependencies into a Python
 virtual environment.
 
 
+Updating Golden References
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Run
+
+.. code:: bash
+
+   cmake --build <build-dir> --target generate_references
+
+to regenerate the golden references. They are saved in a submodule
+``tests/usecases/references``, which points to ``BlueBrain/nmodl-references``.
+
+Create a PR for the changes to the references and update the SHA in the NMODL
+repo. It might be useful to change to SSH authentication:
+
+.. code:: bash
+
+   git remote set-url origin ssh://git@github.com/BlueBrain/nmodl-references
+
+(from inside ``tests/usecases/references``).
+
+Remember the rules of submodules: They're checked out on a specific commit,
+i.e. detached HEAD. If you want to modify the submodule, it's usual best to
+checkout ``main`` from then on the submodule will behave much like a Git repo
+that happens to be located inside a Git repo.
+
+
 Validate the Python package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

azure-pipelines.yml

@@ -141,8 +141,8 @@ stages:
       displayName: 'Build Neuron and Run Integration Tests'
   - job: 'osx11'
     pool:
-      vmImage: 'macOS-11'
-    displayName: 'MacOS (11), AppleClang 12.0'
+      vmImage: 'macOS-12'
+    displayName: 'MacOS (12), AppleClang 14.0'
     steps:
     - checkout: self
       submodules: True

docs/conf.py

@@ -185,6 +185,10 @@
     (master_doc, "nmodl.tex", "nmodl Documentation", "BlueBrain HPC team", "manual")
 ]
 
+imgmath_image_format = 'svg'
+imgmath_embed = True
+imgmath_font_size = 14
+
 
 # -- Options for manual page output ---------------------------------------
 

docs/contents/currents.rst

@@ -0,0 +1,61 @@
+Currents
+========
+
+Current refer to the part of the membrane currents due to mechanisms. Meaning
+the represent the rate at which charge crosses the membrane, e.g. due to ions
+passing through ion channels. In Figure 1 we show the electrical circuit for a
+couple of segments near a branch point. The effect of the capacitor (when
+present) is handled by NEURON internally. In MOD files we compute the current
+represented by the white box, labeled ``I``. This total current is the sum of
+one current per mechanism. The current per mechanism in turn is the sum of
+non-specific currents and ion currents, see Figure 2.
+
+
+.. figure:: ../images/currents_circuit.svg
+
+   Figure 1: Wiring diagram of four segments near a branch point. The circuit for computing the total trans-membrane current. For nodes representing a segment with non-zero aread the circuit for total trans-membrane current consists of a capacitor and currents due to mechanisms (labelled ``I``). The nodes with zero-area, the there's no capacitor, but point-processes, can still introduce current at that point.
+
+
+.. figure:: ../images/currents_types.svg
+
+   Figure 2: A detailed view of the the current ``I`` due to mechanisms. The current ``I`` is the sum of one total current per mechanism, illustrated as boxes of different colors. For each mechanism the total current consists of nonspecific currents (``i1``) and ion currents (``ina`` and ``ica``), illustrated only in the light yellow box.
+
+
+There's a total current, required by the cable equation, which is discussed
+here. The rate at which ions cross the membrane, called ion currents, can be
+computed for individual ions, separately. Please check the documentation on
+Ions.
+
+
+NMODL Keywords
+--------------
+
+NONSPECIFIC_CURRENT
+~~~~~~~~~~~~~~~~~~~
+
+A nonspecific current is how an additive current contribution is expressed that's not accociated with any specific ion. It has the following syntax
+
+.. code-block::
+
+   NEURON {
+       NONSPECIFIC_CURRENT <name>
+   }
+
+We'll assume the name is ``i1``.
+
+Since it needs to be assigned a value in the MOD file, it needs to also be listed in the ``ASSIGNED`` block, e.g. as follows (units show are for a density mechanism).
+
+.. code-block::
+
+   ASSIGNED {
+       <name> (mA/cm2)
+   }
+
+The nonspecific current is local to the mechanism and can be stored as a
+regular range variable.
+
+The generated code must ensure the following:
+
+1. The total current contribution is updated by ``i1``.
+2. Continue with the remaining current related computations, such as the finite
+   difference for computing ``dI/dv``.

docs/contents/ions.rst

@@ -107,3 +107,10 @@ This optimization is implemented in NMODL. It can be activated on the CLI via
    nmodl ... codegen --opt-ionvar-copy
 
 
+Special Case: zero-area nodes
+-----------------------------
+
+Ions are not defined for nodes that represent a segment with zero area. This
+means point processes can't use ions at nodes with surface zero-area.
+Therefore, this should be asserted in generated code. It also allows converting
+ion currents to ion current densities by dividing by the area.