Improved Command Line with CLI11 (#179)

* First integration of CLI11 in Coreneuron
* CLI11 integrated as ubmodule
* Fixed integration tests for new CLI
* cn_parameters structure includes constructor and parse function
* Removed paths from cmdline_interface tests.
* Changed cn_par to corenrn_param to make it clearer
* Now program doesn't print empty string parameters
* More details on new CLI on README.md
* Fixed integration tests for CLI and GPU
* Added `--show` option to facilitate debugging.
* Fix a free usage when variable is created with new
* Adding CORENEURON_VERSION in engine.h and also merging engine and enginemech.h
* Use combined int version

Co-authored-by: Nicolas Cornu <[email protected]>
Co-authored-by: Pramod Kumbhar <[email protected]>
Co-authored-by: Fernando Pereira <[email protected]>

Author: 4 people

.gitmodules

@@ -1,6 +1,9 @@
 [submodule "external/mod2c"]
   path = external/mod2c
   url = https://github.com/BlueBrain/mod2c
+[submodule "external/CLI11"]
+  path = external/CLI11
+  url = https://github.com/CLIUtils/CLI11.git
 [submodule "external/nmodl"]
   path = external/nmodl
   url = https://github.com/BlueBrain/nmodl

CMake/AddCLI11Submodule.cmake

@@ -0,0 +1,23 @@
+# =============================================================================
+# Copyright (C) 2020 Blue Brain Project
+#
+# See top-level LICENSE file for details.
+# =============================================================================
+
+
+include(FindPackageHandleStandardArgs)
+find_package(FindPkgConfig QUIET)
+find_path(CLI11_PROJ NAMES CMakeLists.txt PATHS "${CORENEURON_PROJECT_SOURCE_DIR}/external/CLI11")
+find_package_handle_standard_args(CLI11 REQUIRED_VARS CLI11_PROJ)
+
+if(NOT CLI11_FOUND)
+  find_package(Git 1.8.3 QUIET)
+  if(NOT ${GIT_FOUND})
+    message(FATAL_ERROR "git not found, clone repository with --recursive")
+  endif()
+  message(STATUS "Sub-module CLI11 missing: running git submodule update --init --recursive")
+  execute_process(COMMAND ${GIT_EXECUTABLE} submodule update --init --recursive --
+                          ${CORENEURON_PROJECT_SOURCE_DIR}/external/CLI11
+                  WORKING_DIRECTORY ${CORENEURON_PROJECT_SOURCE_DIR})
+endif()
+

CMakeLists.txt

@@ -5,18 +5,19 @@
 # =============================================================================
 
 cmake_minimum_required(VERSION 3.7 FATAL_ERROR)
-project(coreneuron)
+project(coreneuron VERSION 0.18.0)
+
+# It is a bad idea having floating point versions, since macros cant handle them
+# We therefore, have version as an int, which is pretty much standard
+math(EXPR CORENEURON_VERSION_COMBINED
+  "${coreneuron_VERSION_MAJOR} * 100 + ${coreneuron_VERSION_MINOR}")
 
 # =============================================================================
 # CMake common project settings
 # =============================================================================
-set(VERSION_MAJOR "0")
-set(VERSION_MINOR "16")
-set(VERSION_PATCH "0")
 set(CMAKE_CXX_STANDARD 14)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
-set(VERSION_STRING "${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH}")
 set(CMAKE_BUILD_TYPE
         RelWithDebInfo
         CACHE STRING "Empty or one of Debug, Release, RelWithDebInfo")
@@ -46,6 +47,8 @@ include(ReleaseDebugAutoFlags)
 include(CrayPortability)
 include(SetRpath)
 include(CTest)
+include(AddCLI11Submodule)
+add_subdirectory(${CORENEURON_PROJECT_SOURCE_DIR}/external/CLI11)
 
 # =============================================================================
 # Build options

README.md

@@ -99,7 +99,7 @@ Note that the CUDA Toolkit version should be compatible with PGI compiler instal
 You have to run GPU executable with the `--gpu` or `-gpu`. Make sure to enable cell re-ordering mechanism to improve GPU performance using `--cell_permute` option (permutation types : 2 or 1):
 
 ```bash
-mpirun -n 1 ./bin/nrniv-core -d ../tests/integration/ring -mpi -e 100 --gpu --cell_permute 2
+mpirun -n 1 ./bin/nrniv-core --mpi --gpu --tstop 100 --datpath ../tests/integration/ring --cell-permute 2
 ```
 
 Note that if your model is using Random123 random number generator, you can't use same executable for CPU and GPU runs. We suggest to build separate executable for CPU and GPU simulations. This will be fixed in future releases.
@@ -132,65 +132,26 @@ cmake .. -DCMAKE_CXX_FLAGS="-O3 -g" \
 
 ## RUNNING SIMULATION:
 
-Note that the CoreNEURON simulator dependends on NEURON to build the network model: see [NEURON](https://www.neuron.yale.edu/neuron/) documentation for more information. Once you build the model using NEURON, you can launch CoreNEURON on the same or different machine by:
+Note that the CoreNEURON simulator depends on NEURON to build the network model: see [NEURON](https://www.neuron.yale.edu/neuron/) documentation for more information. Once you build the model using NEURON, you can launch CoreNEURON on the same or different machine by:
 
 ```bash
 export OMP_NUM_THREADS=2     #set appropriate value
-mpiexec -np 2 build/bin/nrniv-core -e 10 -d /path/to/model/built/by/neuron -mpi
+mpiexec -np 2 build/bin/nrniv-core --tstop 10 --datpath /path/to/model/built/by/neuron --mpi
 ```
 
 [This tutorial](https://github.com/nrnhines/ringtest) provide more information for parallel runs and performance comparison.
 
-In order to see the command line options, you can use:
+### Command Line Interface
 
-```bash
-/path/to/isntall/directory/nrniv-core --help
--b, --spikebuf ARG          Spike buffer size. (100000)
--c, --threading             Parallel threads. The default is serial threads.
--d, --datpath ARG           Path containing CoreNeuron data files. (.)
--dt, --dt ARG               Fixed time step. The default value is set by
-                            defaults.dat or is 0.025.
--e, --tstop ARG             Stop time (ms). (100)
--f, --filesdat ARG          Name for the distribution file. (files.dat)
--g, --prcellgid ARG         Output prcellstate information for the gid NUMBER.
--gpu, --gpu                 Enable use of GPUs. The default implies cpu only
-                            run.
--h, --help                  Print a usage message briefly summarizing these
-                            command-line options, then exit.
--k, --forwardskip ARG       Forwardskip to TIME
--l, --celsius ARG           Temperature in degC. The default value is set in
-                            defaults.dat or else is 34.0.
--mpi                        Enable MPI. In order to initialize MPI environment
-                            this argument must be specified.
--o, --outpath ARG           Path to place output data files. (.)
--p, --pattern ARG           Apply patternstim using the specified spike file.
--R, --cell-permute ARG      Cell permutation, 0 No; 1 optimise node adjacency; 2
-                            optimize parent adjacency. (1)
--s, --seed ARG              Initialization seed for random number generator
-                            (int).
--v, --voltage ARG           Initial voltage used for nrn_finitialize(1, v_init).
-                            If 1000, then nrn_finitialize(0,...). (-65.)
--W, --nwarp ARG             Number of warps to balance. (0)
--x, --extracon ARG          Number of extra random connections in each thread to
-                            other duplicate models (int).
---binqueue                  Use bin queue.
---checkpoint ARG            Enable checkpoint and specify directory to store
-                            related files.
---mindelay ARG              Maximum integration interval (likely reduced by
-                            minimum NetCon delay). (10)
---ms-phases ARG             Number of multisend phases, 1 or 2. (2)
---ms-subintervals ARG       Number of multisend subintervals, 1 or 2. (2)
---multisend                 Use Multisend spike exchange instead of Allgather.
---read-config ARG           Read configuration file filename.
---restore ARG               Restore simulation from provided checkpoint
-                            directory.
---show                      Print args.
---skip-mpi-finalize         Do not call mpi finalize.
---spkcompress ARG           Spike compression. Up to ARG are exchanged during
-                            MPI_Allgather. (0)
---write-config ARG          Write configuration file filename.
-```
+:warning: :warning: :warning: **In a recent update the command line interface was updated, so please update your scripts accordingly!**
+
+Some details on the new interface:
+
+The new command line interface is based on CLI11. You can find more details by running `coreneuron_exec --help`.
+
+Multiple characters options with single dash (`-gpu`, `-mpi`, `-dt`) are **not** supported anymore. All those options now require a double dash (`--gpu`, `--mpi`, `--dt`), but single characters options still support a single dash (e.g. `-g`).
 
+The format of the configuration options file has changed, regenerate them if there is any problem.
 
 ## Results
 

coreneuron/CMakeLists.txt

@@ -7,8 +7,8 @@
 # commonly included directories
 include_directories(utils/randoms
                     ${MPI_INCLUDE_PATH}
-                    ${CMAKE_CURRENT_BINARY_DIR}
-                    ${CORENEURON_PROJECT_SOURCE_DIR})
+                    ${CMAKE_BINARY_DIR}/coreneuron
+                    ${CMAKE_BINARY_DIR}/include)
 
 # put libraries (e.g. dll) in bin directory
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
@@ -20,6 +20,7 @@ file(GLOB_RECURSE CORENEURON_HEADER_FILES "*.h*")
 file(GLOB_RECURSE CORENEURON_TEMPLATE_FILES "*.ipp")
 file(GLOB CORENEURON_CODE_FILES
                   "apps/main1.cpp"
+                  "apps/corenrn_parameters.cpp"
                   "gpu/*.cpp"
                   "io/*.cpp"
                   "mechanism/*.cpp"
@@ -173,6 +174,7 @@ target_link_libraries(coreneuron
                       ${CALIPER_LIB}
                       ${CALIPER_MPI_LIB}
                       ${likwid_LIBRARIES})
+target_include_directories(coreneuron SYSTEM PRIVATE ${CORENEURON_PROJECT_SOURCE_DIR}/external/CLI11/include)
 
 target_link_libraries(corenrnmech scopmath coreneuron)
 
@@ -229,6 +231,8 @@ configure_file(${DIMPLIC_CODE_FILE} ${CMAKE_BINARY_DIR}/share/coreneuron/dimplic
 configure_file(${ENGINEMECH_CODE_FILE} ${CMAKE_BINARY_DIR}/share/coreneuron/enginemech.cpp COPYONLY)
 
 # Make headers avail to build tree
+configure_file(engine.h.in ${CMAKE_BINARY_DIR}/include/coreneuron/engine.h @ONLY)
+
 file(GLOB_RECURSE main_headers RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}" *.h *.hpp *.ispc)
 foreach(header ${main_headers})
   configure_file("${header}" "${CMAKE_BINARY_DIR}/include/coreneuron/${header}" COPYONLY)
@@ -265,8 +269,8 @@ install(TARGETS coreneuron corenrnmech ${link_cudacoreneuron}
 install(TARGETS scopmath EXPORT coreneuron DESTINATION lib)
 
 # headers and some standalone code files for nrnivmodl-core
-install(DIRECTORY .
-        DESTINATION include/coreneuron
+install(DIRECTORY ${CMAKE_BINARY_DIR}/include/coreneuron
+        DESTINATION include/
         FILES_MATCHING
         PATTERN "*.h*"
         PATTERN "*.ipp"

coreneuron/apps/coreneuron.cpp

@@ -26,7 +26,7 @@ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
 THE POSSIBILITY OF SUCH DAMAGE.
 */
 
-#include <coreneuron/enginemech.h>
+#include <coreneuron/engine.h>
 #include "coreneuron/utils/profile/profiler_interface.h"
 
 int main(int argc, char** argv) {