Merge branch 'master' into jelic/test_313

.gitlab-ci.yml

@@ -148,19 +148,6 @@ spack_setup:
     # BLUECONFIGS_BRANCH does not correspond to a Spack package called blueconfigs
     SPACK_SETUP_IGNORE_PACKAGE_VARIABLES: BLUECONFIGS
 
-simulation_stack:
-  stage: .pre
-  # Take advantage of GitHub PR description parsing in the spack_setup job.
-  needs: [spack_setup]
-  trigger:
-    branch: $BLUECONFIGS_BRANCH
-    project: hpc/sim/blueconfigs
-    # NEURON CI status depends on the BlueConfigs CI status.
-    strategy: depend
-  variables:
-    GITLAB_PIPELINES_BRANCH: $GITLAB_PIPELINES_BRANCH
-    SPACK_ENV_FILE_URL: $SPACK_SETUP_COMMIT_MAPPING_URL
-
 # Performance seems to be terrible when we get too many jobs on a single node.
 .build:
   extends: [.spack_build]

CMakeLists.txt

@@ -85,6 +85,13 @@ option(
   NRN_ENABLE_PERFORMANCE_TESTS
   "Enable tests that measure performance. These are known to be unreliable when run on busy/oversubscribed machines such as CI runners."
   ${NRN_ENABLE_PERFORMANCE_TESTS_DEFAULT})
+option(NRN_ENABLE_DIGEST
+       "Provides nrn_digest function for debugging cross platform floating result differences."
+       ${NRN_ENABLE_DIGEST_DEFAULT})
+option(
+  NRN_ENABLE_ARCH_INDEP_EXP_POW
+  "Provides use_exp_pow_precision(style) function so that exp and pow produce same results on all platforms"
+  ${NRN_ENABLE_ARCH_INDEP_EXP_POW_DEFAULT})
 # This can be helpful in very specific CI build configurations, where ccache is used *and* different
 # CI builds are built under different directories.
 option(NRN_AVOID_ABSOLUTE_PATHS
@@ -1056,6 +1063,10 @@ if(NRN_ENABLE_PROFILING)
     message(STATUS "  Caliper     | ${caliper_DIR}")
   endif()
 endif()
+if(NRN_ENABLE_DIGEST OR NRN_ARCH_INDEP_EXP_POW)
+  message(STATUS "NRN_ENABLE_DIGEST | ${NRN_ENABLE_DIGEST}")
+  message(STATUS "NRN_ENABLE_ARCH_INDEP_EXP_POW | ${NRN_ENABLE_ARCH_INDEP_EXP_POW}")
+endif()
 message(STATUS "--------------+--------------------------------------------------------------")
 message(STATUS " See documentation : https://www.neuron.yale.edu/neuron/")
 message(STATUS "--------------+--------------------------------------------------------------")

cmake/BuildOptionDefaults.cmake

@@ -29,6 +29,8 @@ set(NRN_AVOID_ABSOLUTE_PATHS_DEFAULT OFF)
 set(NRN_NMODL_CXX_FLAGS_DEFAULT "-O0")
 set(NRN_SANITIZERS_DEFAULT "")
 set(NRN_ENABLE_MATH_OPT_DEFAULT OFF)
+set(NRN_ENABLE_DIGEST_DEFAULT OFF)
+set(NRN_ENABLE_ARCH_INDEP_EXP_POW_DEFAULT OFF)
 
 # Some distributions may set the prefix. To avoid errors, unset it
 set(NRN_PYTHON_DYNAMIC_DEFAULT "")

cmake/Coverage.cmake

@@ -34,7 +34,7 @@ if(NRN_ENABLE_COVERAGE)
   if(NOT BUILD_TYPE_UPPER STREQUAL "DEBUG")
     message(WARNING "Using CMAKE_BUILD_TYPE=Debug is recommended with NRN_ENABLE_COVERAGE")
   endif()
-  set(NRN_COVERAGE_FLAGS_UNQUOTED --coverage -fno-inline)
+  set(NRN_COVERAGE_FLAGS_UNQUOTED --coverage -fno-inline -fprofile-update=atomic)
   string(JOIN " " NRN_COVERAGE_FLAGS ${NRN_COVERAGE_FLAGS_UNQUOTED})
   set(NRN_COVERAGE_LINK_FLAGS --coverage)
 

cmake/NeuronFileLists.cmake

@@ -21,6 +21,7 @@ set(HEADER_FILES_TO_INSTALL
     nrnoc/md1redef.h
     nrnoc/md2redef.h
     nrnoc/membdef.h
+    nrnoc/ion_semantics.h
     nrnoc/membfunc.h
     nrnoc/multicore.h
     nrnoc/multisplit.h

cmake_nrnconf.h.in

@@ -1,5 +1,12 @@
 #pragma once
 
+/* Define to one if want to debug using sha1 hashes of data */
+#cmakedefine01 NRN_ENABLE_DIGEST
+
+/* Define to one if want to allow selection of architecture independent */
+/* 53 bit double precision of exp and pow from mpfr */
+#cmakedefine01 NRN_ENABLE_ARCH_INDEP_EXP_POW
+
 /* Define if building universal (internal helper macro) */
 #cmakedefine AC_APPLE_UNIVERSAL_BUILD @AC_APPLE_UNIVERSAL_BUILD@
 

docs/cmake_doc/options.rst

@@ -674,3 +674,23 @@ NRN_ENABLE_MATH_OPT:BOOL=OFF
 
   Note: Compilers like Intel, NVHPC, Cray etc enable such optimisations
   by default.
+
+NRN_ENABLE_DIGEST:BOOL=OFF
+------------------------------
+  Provides \ :func:`nrn_digest` function for debugging cross platform floating
+  result differences.
+
+  Requires libcrypto
+
+NRN_ENABLE_ARCH_INDEP_EXP_POW:BOOL=OFF
+---------------------------------
+  Provides \ :func:`use_exp_pow_precision` function so that exp and pow produce
+  same results on all platforms.
+
+  Requires mpfr (multiple precision floating-point computation). eg.
+  ``sudo apt install libmpfr-dev``
+
+  To get platform independent floating point results with clang,
+  also consider using
+  ``-DCMAKE_C_FLAGS="-ffp-contract=off" -DCMAKE_CXX_FLAGS="-ffp-contract=off"``
+  or, alternatively, ``"-fp-model=strict``

docs/install/mac_pkg.md

@@ -162,7 +162,7 @@ generally only for the architecture indicated by ```uname -m```. That is
 ok for openmpi but since the various python libraries are linked against
 during build to create the version specific neuron modules, those python
 installers also have to be universal. Fortunately, universal python versions
-can be found at [python.org](http://python.org/Downloads/macOS) at least for
+can be found at [python.org](https://www.python.org/downloads/macos) at least for
 (as of 2022-01-01) python3.8, python3.9, and python3.10.
 
 - ```xcode-select --install```:

docs/install/python_wheels.md

@@ -171,6 +171,8 @@ bash packaging/python/build_wheels.bash linux 3* coreneuron
 ```
 Where we are passing `3*` to build the wheels with `CoreNEURON` support for all python 3 versions.
 
+You can also control the level of parallelization used for the build using the `NRN_PARALLEL_BUILDS` env variable (default: 4).
+
 ### macOS
 As mentioned above, for macOS all dependencies have to be available on a system. You have to then clone NEURON repository and execute:
 

docs/python/programming/internals.rst

@@ -261,3 +261,115 @@ Miscellaneous
         the variable from its interpreter name. Not needed by or useful for the user; returns 1.0 on
         success.
 
+----
+
+Debugging
+~~~~~~~~~~~
+
+.. function:: nrn_digest
+
+    Syntax:
+        ``h.nrn_digest()``
+
+        ``h.nrn_digest(tid, i)``
+
+        ``h.nrn_digest(tid, i, "abort")``
+
+        ``h.nrn_digest(filename)``
+
+    Description:
+        Available when configured with the cmake option ``-DNRN_ENABLE_DIGEST=ON``
+
+        If the same simulation gives different results on different machines,
+        this function can help isolate the statement that generates the
+        first difference during the simulation.
+        I think :meth:`ParallelContext.prcellstate` is generally better, but in rare
+        situations, nrn_digest can be very helpful.
+
+        The first three forms begin digest gathering. The last form
+        prints the gathered digest information to the filename.
+        With just the two ``tid, i`` arguments, the i gathered item of the
+        tid thread is printed (for single thread simulations, use ``tid = 0``),
+        to the terminal as well as the individual values of the array
+        for that digest item. With the third ``"abort"`` argument, the
+        ith gathered item is printed and ``abort()`` is called (dropping
+        into gdb if that is being used so that one can observe the backtrace).
+
+        Lines are inserted into the digest by calling the C function declared
+        in ``src/oc/nrndigest.h``.
+            ``void nrn_digest_dbl_array(const char* msg, int tid, double t, double* array, size_t sz);``
+        at the moment, such lines are present in ``src/nrncvode/occvode.cpp``
+        to instrument the cvode callbacks that compute ``y' = f(y, t)`` and the
+        approximate jacobian matrix solver ``M*x = b``. I.e in part
+
+        .. code-block::
+
+            #include "nrndigest.h"
+            ...
+            void Cvode::fun_thread(neuron::model_sorted_token const& sorted_token,
+                       double tt,
+                       double* y,
+                       double* ydot,
+                       NrnThread* nt) {
+                CvodeThreadData& z = CTD(nt->id);
+            #if NRN_DIGEST
+                if (nrn_digest_) {
+                    nrn_digest_dbl_array("y", nt->id, tt, y, z.nvsize_);
+                }
+            #endif
+            ...
+            #if NRN_DIGEST
+                if (nrn_digest_ && ydot) {
+                    nrn_digest_dbl_array("ydot", nt->id, tt, ydot, z.nvsize_);
+                }
+            #endif
+
+        Note: when manually adding such lines, the conditional compilation and
+        nrn\_digest\_ test are not needed. The arguments to
+        ``nrn_digest_dbl_array`` determine the line added to the digest.
+        The 5th arg is the size of the 4th arg double array. The double array
+        is processed by SHA1 and the first 16 hex digits are appended to the line.
+        An example of the first few lines of output in a digest file is
+        .. code-block::
+
+            tid=0 size=1344
+            y 0 0 0 e1f6a372856b45e6
+            y 0 1 0 e1f6a372856b45e6
+            ydot 0 2 0 523c9694c335e458
+            y 0 3 4.7121609153871379e-09 fabb4bc469447404
+            ydot 0 4 4.7121609153871379e-09 60bcff174645fc29
+
+        The first line is thread id and number of lines for that thread.
+        Other thread groups, if any, follow the end of each thread group.
+        The digest lines consist of thread id, line identifier (start from 0
+        for each group), double value of the 3rd arg, hash of the array.
+
+----
+
+.. function:: use_exp_pow_precision
+
+    Syntax:
+        ``h.use_exp_pow_precision(istyle)``
+
+    Description:
+        Works when configured with the cmake option
+        ``-DNRN_ENABLE_ARCH_INDEP_EXP_POW=ON`` and otherwise does nothing.
+
+        * istyle = 1
+            All calls to :func:`exp` and :func:`pow` as well as their use
+            internally, in mod files, and by cvode, are computed on mac, linux,
+            windows so that double precision floating point results are
+            cross platform consistent. (Makes use of a
+            multiple precision floating-point computation library.)
+
+        * istyle = 2
+            exp and pow are rounded to 32 bits of mantissa
+
+        * istyle = 0
+            Default.
+            exp and pow calcualted natively (cross platform values can have
+            round off error differences.)
+
+            When using clang (eg. on a mac) cross platform floating point
+            identity is often attainable with  C and C++ flag option
+            ``"-ffp-contract=off"``.

setup.py

@@ -247,7 +247,12 @@ def _run_cmake(self, ext):
         if self.cmake_defs:
             cmake_args += ["-D" + opt for opt in self.cmake_defs.split(",")]
 
-        build_args = ["--config", cfg, "--", "-j4"]  # , 'VERBOSE=1']
+        build_args = [
+            "--config",
+            cfg,
+            "--",
+            f"-j{os.environ.get('NRN_PARALLEL_BUILDS', 4)}",
+        ]
 
         env = os.environ.copy()
         env["CXXFLAGS"] = "{} -DVERSION_INFO='{}'".format(
@@ -495,7 +500,7 @@ def setup_package():
         name=package_name,
         package_dir={"": NRN_PY_ROOT},
         packages=py_packages,
-        package_data={"neuron": ["*.dat"]},
+        package_data={"neuron": ["*.dat", "tests/*.json"]},
         ext_modules=extensions,
         scripts=[
             os.path.join(NRN_PY_SCRIPTS, f)