diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1bf30fdfc4..ad0d7dccaa 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/docs/cmake_doc/options.rst b/docs/cmake_doc/options.rst index 523bacd85e..2a28c84348 100644 --- a/docs/cmake_doc/options.rst +++ b/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 `__ 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 ``. 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: ===================================== diff --git a/docs/coreneuron/_static/bluebrain_coreneuron.jpg b/docs/coreneuron/_static/bluebrain_coreneuron.jpg new file mode 100644 index 0000000000..e169cb1e02 Binary files /dev/null and b/docs/coreneuron/_static/bluebrain_coreneuron.jpg differ diff --git a/docs/coreneuron/index.rst b/docs/coreneuron/index.rst index 53757ca533..6ec92f6ae1 100644 --- a/docs/coreneuron/index.rst +++ b/docs/coreneuron/index.rst @@ -1,7 +1,7 @@ CoreNEURON ########## -`CoreNEURON `_ is a compute engine for the NEURON simulator optimised for both memory usage and computational speed on modern CPU/GPU architectures. +`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 diff --git a/docs/coreneuron/running-a-simulation.rst b/docs/coreneuron/running-a-simulation.rst index 04b3d9b7c8..19d006ba4c 100644 --- a/docs/coreneuron/running-a-simulation.rst +++ b/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 `_ 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 `_ with an example of your MOD file. .. _enabling_coreneuron: Enabling CoreNEURON diff --git a/docs/install/install_instructions.md b/docs/install/install_instructions.md index 12e04af581..7c154c20f2 100644 --- a/docs/install/install_instructions.md +++ b/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 diff --git a/src/coreneuron/README.md b/src/coreneuron/README.md index 55aca88b90..b5d1bee5a3 100644 --- a/src/coreneuron/README.md +++ b/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