Mention issue in compilation with NMODL_ENABLE_PYTHON_BINDINGS (#2552)

CONTRIBUTING.md

@@ -26,7 +26,7 @@ favor of Python. The hoc code itself is in the nrn repository and also should no
 
 There are several NEURON-related repositories hosted elsewhere which also encourage contributions. Each of these will have its own *Contributing* document.
 1. [NMODL](https://github.com/BlueBrain/nmodl) -- improved method for compiling and porting *.mod* files using *abstract syntax trees*
-1. [CoreNEURON](https://github.com/BlueBrain/CoreNeuron) -- an optimized NEURON for running on high performance computers (HPCs)
+1. [CoreNEURON](https://github.com/neuronsimulator/nrn/tree/master/src/coreneuron) -- an optimized NEURON for running on high performance computers (HPCs)
 1. [NetPyNE](https://github.com/Neurosim-lab/netpyne) -- multiscale modeling tool for developing, simulating and analyzing networks which include complex cells, potentially
 with detailed molecular-modeling.
 1. [NetPyNE-UI](https://github.com/MetaCell/NetPyNE-UI) -- graphical user interface for NetPyNE

docs/cmake_doc/options.rst

@@ -1,25 +1,72 @@
 Introduction
 ============
-The NEURON build system now uses cmake as of version 7.8 circa Nov 2019.
+The NEURON build system now uses CMake as of version 7.8 circa Nov 2019.
 The previous autotools (./configure) build system has been removed after
 8.0 release.
 
+The NEURON simulator as well as Interviews, CoreNEURON and NMODL can be installed
+together using the following instructions:
+
+1. Clone the latest version or specific release:
+
 .. code-block:: shell
 
-  git clone https://github.com/neuronsimulator/nrn nrn
-  cd nrn
-  mkdir build
-  cd build
-  cmake .. # default install to /usr/local
-  make -j
-  sudo make -j install
+   git clone https://github.com/neuronsimulator/nrn           # latest development branch
+   git clone https://github.com/neuronsimulator/nrn -b 8.0.0  # specific release version 8.0.0
+   cd nrn
+
+..
+
+   .. warning:: To build NEURON from source you either need to clone the
+   NEURON Git repository or download a source code archive that includes
+   Git submodules, such as the ``full-src-package-X.Y.Z.tar.gz`` file in
+   the `NEURON
+   releases <https://github.com/neuronsimulator/nrn/releases>`__ on
+   GitHub. The tarballs like ``Source code (tar.gz)`` or
+   ``Source code (zip)`` created by GitHub are incomplete.
+
+2. Create a build directory:
+
+.. code-block:: shell
+
+   mkdir build
+   cd build
+
+3. Run ``cmake`` with the appropriate options (see below for a list of
+   common options). A full list of options can be found in
+   ``nrn/CMakeLists.txt`` and defaults are shown in
+   ``nrn/cmake/BuildOptionDefaults.cmake``. e.g. a bare-bones
+   installation:
+
+.. code-block:: shell
+
+   cmake .. \
+    -DNRN_ENABLE_INTERVIEWS=OFF \
+    -DNRN_ENABLE_MPI=OFF \
+    -DNRN_ENABLE_RX3D=OFF \
+    -DPYTHON_EXECUTABLE=$(which python3) \
+    -DCMAKE_INSTALL_PREFIX=/path/to/install/directory
+
+4. Build the code:
 
-The ``-j`` option to make invokes a parallel make using all available cores.
-This is often very much faster than a single process make. One can add a number
-after the ``-j`` (e.g. ``make -j 6``) to specify the maximum number of processes
-to use. This can be useful if there is the possibility of running out of memory.
+.. code-block:: shell
+
+   cmake --build . --parallel 8 --target install
+
+Feel free to set the number of parallel jobs (i.e. 8) according to your
+system using the ``--parallel`` option.
+
+   .. warning:: When ``NEURON`` is installed with ``CoreNEURON`` option enabled then ``NMODL`` is also installed with the ``NMODL`` Python bindings which increase a lot the compilation complexity and memory requirements. For that purpose it’s recommended to either disable this option if the Python bindings are not needed using the ``CMake`` option ``-DNMODL_ENABLE_PYTHON_BINDINGS=OFF`` or restrict the number of parallel jobs running in parallel in the ``cmake`` command using ``cmake --parallel <number_of_parallel_jobs>``. i.e. in a machine with 8 threads do ``cmake -parallel 4``.
+
+5. Set PATH and PYTHONPATH environmental variables to use the
+   installation:
+
+.. code-block:: shell
+
+   export PATH=/path/to/install/directory/bin:$PATH
+   export PYTHONPATH=/path/to/install/directory/lib/python:$PYTHONPATH
 
-The make targets that are made available by cmake can be listed with
+The make targets that are made available by CMake can be listed with
 
 .. code-block:: shell
 
@@ -190,8 +237,8 @@ IV_ENABLE_X11_DYNAMIC_MAKE_HEADERS:BOOL=OFF
   If it is ever necessary to remake the X11 dynamic .h files, I will
   do so and push them to the https://github.com/neuronsimulator/iv respository.
 
-MPI options:
-============
+MPI options
+===========
 
 NRN_ENABLE_MPI:BOOL=ON
 ----------------------
@@ -248,8 +295,8 @@ NRN_ENABLE_MUSIC:BOOL=OFF
   only for binary distributions of NEURON (e.g. wheels) where NEURON may
   be installed and used prior to installing music.)
 
-Python options:
-===============
+Python options
+==============
 
 NRN_ENABLE_PYTHON:BOOL=ON
 -------------------------
@@ -326,8 +373,8 @@ NRN_RX3D_OPT_LEVEL:STRING=0
 
     -DNRN_RX3D_OPT_LEVEL=2
 
-CoreNEURON options:
-===================
+CoreNEURON options
+==================
 
 NRN_ENABLE_CORENEURON:BOOL=OFF
 ------------------------------
@@ -348,10 +395,23 @@ NRN_ENABLE_MOD_COMPATIBILITY:BOOL=OFF
 Other CoreNEURON options:
 -------------------------
   There are 20 or so cmake arguments specific to a CoreNEURON
-  build that are listed in https://github.com/BlueBrain/CoreNeuron/blob/master/CMakeLists.txt.
+  build that are listed in https://github.com/neuronsimulator/nrn/blob/master/src/coreneuron/CMakeLists.txt.
   The ones of particular interest that can be used on the NEURON
   CMake configure line are `CORENRN_ENABLE_NMODL` and `CORENRN_ENABLE_GPU`.
 
+NMODL options
+=============
+
+To see all the NMODL CMake options you can look in https://github.com/BlueBrain/nmodl/blob/master/CMakeLists.txt.
+
+NMODL_ENABLE_PYTHON_BINDINGS:BOOL=ON
+------------------------------------
+  Enable pybind11 based python bindings
+
+  Using this option the user can use the NMODL python package to use NMODL via python. For more information look at
+  the NMODL documentation in https://bluebrain.github.io/nmodl/html/notebooks/nmodl-python-tutorial.html.
+
+
 Occasionally useful advanced options:
 =====================================
 

docs/coreneuron/index.rst

@@ -1,7 +1,7 @@
 CoreNEURON
 ##########
 
-`CoreNEURON <https://github.com/BlueBrain/CoreNeuron>`_ is a compute engine for the NEURON simulator optimised for both memory usage and computational speed on modern CPU/GPU architectures.
+`CoreNEURON <https://github.com/neuronsimulator/nrn/blob/master/src/coreneuron>`_ is a compute engine for the NEURON simulator optimised for both memory usage and computational speed on modern CPU/GPU architectures.
 Some of its key goals are to:
 
 * Efficiently simulate large network models

docs/coreneuron/running-a-simulation.rst

@@ -28,7 +28,7 @@ that is linked to CoreNEURON (here ``x86_64`` is the architecture name
 of your system).
 
 If you see any compilation error then one of the MOD files might be incompatible with CoreNEURON.
-In this case, you should first consult the :ref:`CoreNEURON compatibility` section, and if that does not provide a clear explanation then you should `open an issue <https://github.com/BlueBrain/CoreNeuron/issues>`_ with an example of your MOD file.
+In this case, you should first consult the :ref:`CoreNEURON compatibility` section, and if that does not provide a clear explanation then you should `open an issue <https://github.com/neuronsimulator/nrn/issues>`_ with an example of your MOD file.
 
 .. _enabling_coreneuron:
 Enabling CoreNEURON

docs/install/install_instructions.md

@@ -303,80 +303,20 @@ We recommend using platform specific instructions provided in [nrn-build-ci](htt
 
 Starting with the 7.8.1 release, NEURON can be installed using the [CMake build system](https://cmake.org/).
 One of the primary advantages of a CMake-based build system is cross-platform support and integration with
-other projects like [Interviews](https://github.com/neuronsimulator/iv), [CoreNEURON](https://github.com/BlueBrain/CoreNeuron/),
+other projects like [Interviews](https://github.com/neuronsimulator/iv), [CoreNEURON](https://github.com/neuronsimulator/nrn/tree/master/src/coreneuron),
 [NMODL](https://github.com/BlueBrain/nmodl/) etc. These projects are now integrated into single a CMake-based
-build system, and they can be installed together as shown below:
+build system.
 
-1. Clone the latest version or specific release:
-
-  ```
-  git clone https://github.com/neuronsimulator/nrn           # latest development branch
-  git clone https://github.com/neuronsimulator/nrn -b 8.0.0  # specific release version 8.0.0
-  cd nrn
-  ```
-
-  > :warning: To build NEURON from source you either need to clone the NEURON Git repository or download a
-  > source code archive that includes Git submodules, such as the `full-src-package-X.Y.Z.tar.gz` file in
-  > the [NEURON releases](https://github.com/neuronsimulator/nrn/releases) on GitHub. The tarballs like
-  > `Source code (tar.gz)` or `Source code (zip)` created by GitHub are incomplete.
-
-
-2. Create a build directory:
-
-  ```
-  mkdir build
-  cd build
-  ```
-
-3. Run `cmake` with the appropriate options (see below for a list of common options). A full list of options
-can be found in `nrn/CMakeLists.txt` and defaults are shown in `nrn/cmake/BuildOptionDefaults.cmake`. e.g. a bare-bones installation:
-
-
-  ```
-  cmake .. \
-   -DNRN_ENABLE_INTERVIEWS=OFF \
-   -DNRN_ENABLE_MPI=OFF \
-   -DNRN_ENABLE_RX3D=OFF \
-   -DPYTHON_EXECUTABLE=$(which python3) \
-   -DCMAKE_INSTALL_PREFIX=/path/to/install/directory
-  ```
-
-4. Build the code:
-
-  ```
-  cmake --build . --parallel 8 --target install
-  ```
-  Feel free to set the number of parallel jobs (i.e. 8) according to your system using the `--parallel` option.
-
-5. Set PATH and PYTHONPATH environmental variables to use the installation:
-
-  ```
-  export PATH=/path/to/install/directory/bin:$PATH
-  export PYTHONPATH=/path/to/install/directory/lib/python:$PYTHONPATH
-  ```
-
-Particularly useful CMake options are (use **ON** to enable and **OFF** to disable feature):
-
-* **-DNRN\_ENABLE\_INTERVIEWS=OFF** : Disable Interviews (native GUI support)
-* **-DNRN\_ENABLE\_PYTHON=OFF** : Disable Python support
-* **-DNRN\_ENABLE\_MPI=OFF** : Disable MPI support for parallelization
-* **-DNRN\_ENABLE\_RX3D=OFF** : Disable rx3d support
-* **-DNRN\_ENABLE\_CORENEURON=ON** : Enable CoreNEURON support
-* **-DNRN\_ENABLE\_TESTS=ON** : Enable unit tests
-* **-DPYTHON\_EXECUTABLE=/python/binary/path** : Use provided Python binary to build Python interface
-* **-DCMAKE_INSTALL_PREFIX=/install/dir/path** : Location for installing
-* **-DCORENRN\_ENABLE\_NMODL=ON** : Use [NMODL](https://github.com/BlueBrain/nmodl/) instead of [MOD2C](https://github.com/BlueBrain/mod2c/) for code generation with CoreNEURON
-
-Please refer to [docs/cmake_doc/options.rst](../cmake_doc/options.rst) for more information on
-the CMake options.
+Please refer to [the CMake build system
+options](../cmake_doc/options.rst) for more information on how to
+install the project using ``CMake``.
 
 #### Optimized CPU and GPU Support using CoreNEURON
 
-NEURON now integrates [CoreNEURON library](https://github.com/BlueBrain/CoreNeuron/) for improved simulation
+NEURON now integrates [CoreNEURON library](https://github.com/neuronsimulator/nrn/blob/master/src/coreneuron) for improved simulation
 performance on modern CPU and GPU architectures. CoreNEURON is designed as a library within the NEURON simulator
 and can transparently handle all spiking network simulations including gap junction coupling with the fixed time
-step method. You can find detailed instructions [here](../coreneuron/index.rst) and
-[here](https://github.com/BlueBrain/CoreNeuron/#installation).
+step method. You can find detailed instructions [here](../coreneuron/index.rst) and [here](../cmake_doc/options.rst).
 
 #### Run integrated tests
 

src/coreneuron/README.md

@@ -1,6 +1,4 @@
-![CoreNEURON CI](https://github.com/BlueBrain/CoreNeuron/workflows/CoreNEURON%20CI/badge.svg) [![codecov](https://codecov.io/gh/BlueBrain/CoreNeuron/branch/master/graph/badge.svg?token=mguTdBx93p)](https://codecov.io/gh/BlueBrain/CoreNeuron)
-
-![CoreNEURON](docs/_static/bluebrain_coreneuron.jpg)
+![CoreNEURON](docs/coreneuron/_static/bluebrain_coreneuron.jpg)
 
 # CoreNEURON
 > Optimised simulator engine for [NEURON](https://github.com/neuronsimulator/nrn)
@@ -118,7 +116,7 @@ In order to enable CoreNEURON support, you must set the  `-coreneuron` flag. Mak
 nrnivmodl -coreneuron mod_directory
 ```
 
-If you see any compilation error then one of the mod files might be incompatible with CoreNEURON. Please [open an issue](https://github.com/BlueBrain/CoreNeuron/issues) with an example and we can help to fix it.
+If you see any compilation error then one of the mod files might be incompatible with CoreNEURON. Please [open an issue](https://github.com/neuronsimulator/nrn/issues) with an example and we can help to fix it.
 
 
 ## Running Simulations
@@ -244,7 +242,7 @@ cmake .. -DCMAKE_CXX_FLAGS="-O3 -g" \
 
 By default, OpenMP threading is enabled. You can disable it with `-DCORENRN_ENABLE_OPENMP=OFF`
 
-For other errors, please [open an issue](https://github.com/BlueBrain/CoreNeuron/issues).
+For other errors, please [open an issue](https://github.com/neuronsimulator/nrn/issues).
 
 ## Developer Build
 
@@ -274,25 +272,6 @@ cmake --build . --parallel 8
 ctest # use --parallel for speed, -R to run specific tests
 ```
 
-#### Building standalone CoreNEURON without NEURON
-
-If you want to build the standalone CoreNEURON version, first download the repository as:
-
-```
-git clone https://github.com/BlueBrain/CoreNeuron.git
-
-```
-
-Once the appropriate modules for compiler, MPI, CMake are loaded, you can build CoreNEURON with:
-
-```bash
-mkdir CoreNeuron/build && cd CoreNeuron/build
-cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/install
-cmake --build . --parallel 8 --target install
-```
-
-If you don't have MPI, you can disable the MPI dependency using the CMake option `-DNRN_ENABLE_MPI=OFF`.
-
 #### Compiling MOD files
 
 In order to compile mod files, one can use **nrnivmodl-core** as:
@@ -344,25 +323,6 @@ cmake .. -CORENRN_ENABLE_UNIT_TESTS=OFF
 
 To see all CLI options for CoreNEURON, see `./bin/nrniv-core -h`.
 
-#### Formatting CMake and C++ Code
-
-Format code with `black`, `cmake-format`, and `clang-format` tools, before creating a PR.
-It should suffice within the build folder to ...
-```
-make format-pr
-```
-
-## Run CI
-
-CoreNeuron run several CI:
-
-- Github Action: defined [here](https://github.com/BlueBrain/CoreNeuron/tree/master/.github/workflows) and is self contained
-
-- Gitlab CI: defined [here](https://github.com/BlueBrain/CoreNeuron/blob/master/.gitlab-ci.yml) and depends on [gitlab pipelines](https://bbpgitlab.epfl.ch/hpc/gitlab-pipelines) and [blueconfigs](https://bbpgitlab.epfl.ch/hpc/sim/blueconfigs)
-
-### Configure gitlab CI
-
-See the [README](https://bbpgitlab.epfl.ch/hpc/gitlab-pipelines/-/blob/main/README.md) of `gitlab pipelines` to configure build.
 
 ## Citation
 
@@ -373,9 +333,7 @@ If you would like to know more about CoreNEURON or would like to cite it, then u
 
 ## Support / Contribuition
 
-If you see any issue, feel free to [raise a ticket](https://github.com/BlueBrain/CoreNeuron/issues/new). If you would like to improve this library, see [open issues](https://github.com/BlueBrain/CoreNeuron/issues).
-
-You can see current [contributors here](https://github.com/BlueBrain/CoreNeuron/graphs/contributors).
+If you see any issue, feel free to [raise a ticket](https://github.com/neuronsimulator/nrn/issues/new). If you would like to improve this library, see [open issues](https://github.com/neuronsimulator/nrn/issues).
 
 
 ## License