From 5fd38f6f966baf61191b8b331d2ea76611b1ff50 Mon Sep 17 00:00:00 2001 From: Pramod Kumbhar Date: Tue, 19 Jan 2021 14:59:46 +0100 Subject: [PATCH] Update and cleanup documentation (#463) * Update and cleanup documentation * remove unnecessary info from README * remove .gitreview from gerrit * CREDIT.txt is no longer required * added .gitignore * update mod2c to master * address review - do not add editor specific files --- .gitignore | 13 +++++++++++++ .gitreview | 6 ------ CREDIT.txt | 52 -------------------------------------------------- README.md | 46 +++++++++++++++++--------------------------- external/mod2c | 2 +- 5 files changed, 31 insertions(+), 88 deletions(-) create mode 100644 .gitignore delete mode 100644 .gitreview delete mode 100644 CREDIT.txt diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..e6c1ba624 --- /dev/null +++ b/.gitignore @@ -0,0 +1,13 @@ +cmake-build-debug* +*build* +spconfig.* +*~ +.DS_Store +*.swp +*.srctrl* + +# HPC coding conventions +.clang-format +.clang-tidy +.cmake-format.yaml +.pre-commit-config.yaml diff --git a/.gitreview b/.gitreview deleted file mode 100644 index 704c40dd1..000000000 --- a/.gitreview +++ /dev/null @@ -1,6 +0,0 @@ -[gerrit] -host=bbpcode.epfl.ch -port=22 -project=sim/coreneuron -defaultbranch=master -defaultremote=origin diff --git a/CREDIT.txt b/CREDIT.txt deleted file mode 100644 index d0774fc4f..000000000 --- a/CREDIT.txt +++ /dev/null @@ -1,52 +0,0 @@ -This file lists the most important contributors to the CoreNeuron project. -It is sorted by name and formatted to allow easy grepping and beautification -by scripts. The fields are: name (N), email (E), description (D). - -N: Francesco Casalegno -E: Francesco.Casalegno@epfl.ch -D: Linear algebra and error estimation - -N: Francesco Cremonesi -E: Francesco.Cremonesi@epfl.ch -D: Linear algebra and error estimation - -N: Fabien Delalondre -E: Fabien.Delalondre@epfl.ch -D: User interface extension and unit testing - -N: Adrien Devresse -E: Adrien.Devresse@epfl.ch -D: Build system support - -N: Timothee Ewart -E: Timothee.Ewart@epfl.ch -D: Performance analysis and optimization - -N: Michael Hines -E: Michael.Hines@yale.edu -D: All parts of the software - -N: James King -E: JamesGonzalo.King@epfl.ch -D: Simulation engine and validation - -N: Pramod Kumbhar -E: Pramod.Kumbhar@epfl.ch -D: All parts of the software - -N: Bruno Magalhaes -E: Bruno.Magalhaes@epfl.ch -D: Simulation toolchain - -N: Aleksandr Ovcharenko -E: Aleksandr.Ovcharenko@epfl.ch -D: All parts of the software - -N: Judit Planas -E: Judit.Planas@epfl.ch -D: Performance analysis and I/O - -N: Stuart Yates -E: Sam.Yates@epfl.ch -D: Linear algebra and error estimation - diff --git a/README.md b/README.md index beb1dc728..c169d7961 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,17 @@ -[![Build Status](https://travis-ci.org/BlueBrain/CoreNeuron.svg?branch=master)](https://travis-ci.org/BlueBrain/CoreNeuron) +[![Build Status](https://travis-ci.org/BlueBrain/CoreNeuron.svg?branch=master)](https://travis-ci.org/BlueBrain/CoreNeuron) ![CoreNEURON CI](https://github.com/BlueBrain/CoreNeuron/workflows/CoreNEURON%20CI/badge.svg) # CoreNEURON -> Optimised simulator engine for [NEURON](https://www.neuron.yale.edu/neuron/) +> Optimised simulator engine for [NEURON](https://github.com/neuronsimulator/nrn) CoreNEURON is a compute engine for the [NEURON](https://www.neuron.yale.edu/neuron/) simulator optimised for both memory usage and computational speed. Its goal is to simulate large cell networks with small memory footprint and optimal performance. -## Features / Compatibility +## NEURON Models Compatibility 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**. In order to run a NEURON model with CoreNEURON: * MOD files should be THREADSAFE * If random number generator is used then Random123 should be used instead of MCellRan4 -* POINTER variables need to be converted to BBCOREPOINTER ([details here](http://bluebrain.github.io/CoreNeuron/index.html)) +* POINTER variables need to be converted to BBCOREPOINTER ([details here](docs/userdoc/MemoryManagement/bbcorepointer.md)) ## Dependencies * [CMake 3.7+](https://cmake.org) @@ -41,7 +41,8 @@ CoreNEURON is now integrated into the development version of the NEURON simulato 3. Load software dependencies - Currently CoreNEURON relies on compiler auto-vectorisation and hence we advise to use one of Intel, Cray, or PGI compilers to ensure vectorized code is generated. This constraint will be removed in the near future with the integration of the [NMODL](https://github.com/BlueBrain/nmodl) project. + Currently CoreNEURON relies on compiler auto-vectorisation and hence we advise to use one of Intel, Cray, or PGI compilers to ensure vectorized code is generated. These compilers are able to vectorize the code better than **GCC** or **Clang**, achieving the best possible performance gains. Note that Intel compiler can be installed by downloading [oneAPI HPC Toolkit](https://software.intel.com/content/www/us/en/develop/tools/oneapi/hpc-toolkit.html). CoreNEURON supports GPU execution using **OpenACC** programming model. Currently the best supported compiler for the **OpenACC** backend is **PGI** (available via [NVIDIA-HPC-SDK](https://developer.nvidia.com/hpc-sdk)) and this is the recommended one for compilation. + HPC systems often use a module system to select software. For example, you can load the compiler, cmake, and python dependencies using module as follows: @@ -63,6 +64,8 @@ Note that if you are building on Cray system with the GNU toolchain, you have to -DNRN_ENABLE_INTERVIEWS=OFF \ -DNRN_ENABLE_RX3D=OFF \ -DCMAKE_INSTALL_PREFIX=$HOME/install + -DCMAKE_C_COMPILER=icc \ + -DCMAKE_CXX_COMPILER=icpc ``` 4. If you would like to enable GPU support with OpenACC, make sure to use `-DCORENRN_ENABLE_GPU=ON` option and use the PGI/NVIDIA HPC SDK compilers with CUDA. For example, @@ -227,20 +230,11 @@ cmake .. -DCMAKE_CXX_FLAGS="-O3 -g" \ By default, OpenMP threading is enabled. You can disable it with `-DCORENRN_ENABLE_OPENMP=OFF` -#### GPU enabled build is failing with inlining related errors, what to do? - -If there are large functions / procedures in the MOD file that are not inlined by the compiler, you may need to pass additional C++ flags to PGI compiler. You can try following CXX flags: - -``` --DCMAKE_CXX_FLAGS="-O2 -Minline=size:1000,levels:100,totalsize:40000,maxsize:4000" -``` - For other errors, please [open an issue](https://github.com/BlueBrain/CoreNeuron/issues). - ## Developer Build -##### Building standalone CoreNEURON +#### Building standalone CoreNEURON without NEURON If you want to build the standalone CoreNEURON version, first download the repository as: @@ -263,7 +257,7 @@ If you don't have MPI, you can disable the MPI dependency using the CMake option make test ``` -##### Compiling MOD files +#### Compiling MOD files In order to compile mod files, one can use **nrnivmodl-core** as: @@ -273,7 +267,7 @@ In order to compile mod files, one can use **nrnivmodl-core** as: This will create a `special-core` executable under `` directory. -##### Building with GPU support +#### Building with GPU support CoreNEURON has support for GPUs using the OpenACC programming model when enabled with `-DCORENRN_ENABLE_GPU=ON`. Below are the steps to compile with PGI compiler: @@ -284,12 +278,6 @@ cmake .. -DCORENRN_ENABLE_GPU=ON -DCMAKE_INSTALL_PREFIX=$HOME/install -DCMAKE_C_ make -j && make install ``` -Note that the CUDA Toolkit version should be compatible with the PGI compiler installed on your system. Otherwise, you have to add extra C/C++ flags. For example, if we are using CUDA Toolkit 9.0 installation but PGI default target is CUDA 8.0 then we have to add : - -```bash --DCMAKE_C_FLAGS:STRING="-O2 -ta=tesla:cuda9.0" -DCMAKE_CXX_FLAGS:STRING="-O2 -ta=tesla:cuda9.0" -``` - You have to run GPU executable with the `--gpu` flag. Make sure to enable cell re-ordering mechanism to improve GPU performance using `--cell_permute` option (permutation types : 2 or 1): ```bash @@ -299,7 +287,7 @@ mpirun -n 1 ./bin/nrniv-core --mpi --gpu --tstop 100 --datpath ../tests/integrat Note: If your model is using Random123 random number generator, you cannot use the same executable for CPU and GPU runs. We suggest to install separate NEURON with CoreNEURON for CPU and GPU simulations. This will be fixed in future releases. -##### Running tests with SLURM +#### Running tests with SLURM If you have a different mpi launcher (than `mpirun`), you can specify it during cmake configuration as: @@ -316,11 +304,11 @@ You can disable tests using with options: cmake .. -CORENRN_ENABLE_UNIT_TESTS=OFF ``` -##### CLI Options +#### CLI Options To see all CLI options for CoreNEURON, see `./bin/nrniv-core -h`. -##### Formatting CMake and C++ Code +#### Formatting CMake and C++ Code In order to format code with `cmake-format` and `clang-format` tools, before creating a PR, enable below CMake options: @@ -336,14 +324,14 @@ make cmake-format make clang-format ``` -### Citation +## Citation If you would like to know more about CoreNEURON or would like to cite it, then use the following paper: * Pramod Kumbhar, Michael Hines, Jeremy Fouriaux, Aleksandr Ovcharenko, James King, Fabien Delalondre and Felix Schürmann. CoreNEURON : An Optimized Compute Engine for the NEURON Simulator ([doi.org/10.3389/fninf.2019.00063](https://doi.org/10.3389/fninf.2019.00063)) -### Support / Contribuition +## 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). @@ -352,7 +340,7 @@ You can see current [contributors here](https://github.com/BlueBrain/CoreNeuron/ ## License * See LICENSE.txt -* See [NEURON](https://www.neuron.yale.edu/neuron/) +* See [NEURON](https://github.com/neuronsimulator/nrn) ## Funding diff --git a/external/mod2c b/external/mod2c index f8629baf3..92d62cc78 160000 --- a/external/mod2c +++ b/external/mod2c @@ -1 +1 @@ -Subproject commit f8629baf3cfe247410612688077caf5a84f036fa +Subproject commit 92d62cc780ec09acde0524246cb34403bcf03fb3