formalization of an API (#2357)

* initial partial API

* nrnpy_set_pr_etal should be extern C

* nrn_call_function leaves results on stack

* segments, properties

* including hocdec.h to try to avoid Datum errors on some systems

* sectionlist and allsec hoc_Item getters

* symbol and object introspection

* symbol table getting and interating

* object ref, push

* Renamed files to avoid having two nrnapi.h files.

On some systems (most? but not the one I used for everything else),
some files tried to include the wrong nrnapi.h during the
"make install" phase.

* neuronapi.cpp no longer uses its .h, that is now a header for 3rd party tools

* switched to enum for stack types

* needed typedefs for C to be happy

* test: sections.c

* clang-format

* replaced hoc_Item with new synonym nrn_Item

* netcon example shows no need for dlsym

* support for .so files in addition to .dylib

* removed an excess const

We'll still treat the pointer as const, but the user has no reason to care.

* Add Robert's API tests to CTest (#2365)

* build + run tests

* fixups

* different fixup

* add -rdynamic

* bugfix flagged by ASan

* fix to header file name of api

* hh_sim and sections work with handles
don't have quantitative identity with the old hh_sim results, but very
close.

* rename stack_types_t per @olupton

* replace param_handle with param

* working vclamp

* unified API property functions

* getters use const args

* forgot to commit sections

* vector_capacity now on const obj

* Several improvements

 - C/C++ api header included in implementation
 - signatures made compatible
 - public nrn_Item defined as inheriting from hoc_Item
 - dropped overlapping definitions. types are both fw declarations and
   opaque types

* Make tests link against nrniv_lib, no dlopen

* Address sonar lint reservations

* Make comparisons be part of the test and account for fp innacuraciesa

* Tests to find ref files

* api: Make tests resilient to accumulated errors

* Use in-test ref result, depending on NRN_ENABLE_CORENEURON

* Use free for allocated c strings

* Dont alloc Section Item to heap as its not used.

NOTE: It seems that Sections are never freed. However we are
lacking API to free Sections and Symbols in general.

* Address intel compiler complain

* Free memb_func[].dparam_semantics

* Switch dparam_semantics to unique_ptr (no raw!)

* Memb_list to do its memory management

* Memb_list to be aware of its potential "view" condition and not free

* Back pdata free

* nrn_init to better initialize mpi

* Addressed a number of warnings, inc avoidiing potential double free

* Addressed sonarcloud issues

* fix the merge with master

* Fix test/api/netcon.cpp after merge with master

  - after RANDOM construct (#2627) was merged,
    netstim.mod uses Random123 by default
  - before this, netstim was using scoprand by default
    and reference results were from the same
  - now, explicitly use Random123 in the test and update
    reference results

* fix warning [-Wimplicit-exception-spec-mismatch]

---------

Co-authored-by: Olli Lupton <oliver.lupton@epfl.ch>
Co-authored-by: Fernando Pereira <fernando.pereira@epfl.ch>
Co-authored-by: Pramod Kumbhar <pramod.s.kumbhar@gmail.com>
Co-authored-by: Nicolas Cornu <nicolas.cornu@epfl.ch>
Co-authored-by: Michael Hines <michael.hines@yale.edu>

CMakeLists.txt

@@ -590,7 +590,11 @@ endfunction()
 set(NRN_RUN_FROM_BUILD_DIR_ENV "NEURONHOME=${PROJECT_BINARY_DIR}/share/nrn"
                                "NRNHOME=${PROJECT_BINARY_DIR}")
 prepend_to_var(PATH "${PROJECT_BINARY_DIR}/bin")
-prepend_to_var(LD_LIBRARY_PATH "${PROJECT_BINARY_DIR}/lib")
+if(APPLE)
+  prepend_to_var(DYLD_LIBRARY_PATH "${PROJECT_BINARY_DIR}/lib")
+else()
+  prepend_to_var(LD_LIBRARY_PATH "${PROJECT_BINARY_DIR}/lib")
+endif()
 if(NRN_ENABLE_CORENEURON)
   list(APPEND NRN_RUN_FROM_BUILD_DIR_ENV "CORENRNHOME=${PROJECT_BINARY_DIR}")
 endif()

cmake/NeuronFileLists.cmake

@@ -14,6 +14,7 @@ set(HEADER_FILES_TO_INSTALL
     gnu/nrnran123.h
     nrniv/backtrace_utils.h
     nrniv/bbsavestate.h
+    nrniv/neuronapi.h
     nrnmpi/nrnmpidec.h
     nrnoc/cabvars.h
     nrnoc/md1redef.h
@@ -221,6 +222,7 @@ set(NRNIV_FILE_LIST
     netpar.cpp
     nmodlrandom.cpp
     nonlinz.cpp
+    neuronapi.cpp
     nrncore_write.cpp
     nrncore_write/callbacks/nrncore_callbacks.cpp
     nrncore_write/data/cell_group.cpp

src/ivoc/ivocmain.cpp

@@ -231,6 +231,7 @@ extern void hoc_nrnmpi_init();
 #if NRNMPI_DYNAMICLOAD
 extern void nrnmpi_stubs();
 extern std::string nrnmpi_load();
+void nrnmpi_load_or_exit();
 #endif
 
 // some things are defined in libraries earlier than they are used so...
@@ -805,3 +806,28 @@ int run_til_stdin() {
 }
 void hoc_notify_value() {}
 #endif
+
+
+/// A top-level initialization of MPI given argc and argv.
+/// Sets stubs, load dyn lib, and initializes
+std::tuple<int, const char**> nrn_mpi_setup(int argc, const char** argv) {
+#if defined(AUTO_DLOPEN_NRNMECH) && AUTO_DLOPEN_NRNMECH == 0
+    extern int nrn_noauto_dlopen_nrnmech;
+    nrn_noauto_dlopen_nrnmech = 1;
+#endif
+
+#if NRNMPI
+#if NRNMPI_DYNAMICLOAD
+    nrnmpi_stubs();
+    for (int i = 1; i < argc; ++i) {
+        if (strcmp("-mpi", argv[i]) == 0) {
+            nrnmpi_load_or_exit();
+            break;
+        }
+    }
+#endif                                           // NRNMPI_DYNAMICLOAD
+    auto argv_ptr = const_cast<char***>(&argv);  // safe if individual strings not modified
+    nrnmpi_init(1, &argc, argv_ptr);             // may change argc and argv
+#endif                                           // NRNMPI
+    return {argc, argv};
+}

src/neuron/cache/mechanism_range.hpp

@@ -15,7 +15,7 @@ namespace neuron::cache {
 template <typename Callable>
 void indices_to_cache(short type, Callable callable) {
     auto const pdata_size = nrn_prop_dparam_size_[type];
-    auto* const dparam_semantics = memb_func[type].dparam_semantics;
+    auto* const dparam_semantics = memb_func[type].dparam_semantics.get();
     for (int field = pdata_size - 1; field >= 0; --field) {
         // Check if the field-th dparam of this mechanism type is an ion variable. See
         // hoc_register_dparam_semantics.