Skip to content
Snippets Groups Projects
Commit 0cf65a4c authored by Ben Cumming's avatar Ben Cumming Committed by Alexander Peyser
Browse files

Installation Guide (#459) 

Added an installation guide to the Read The Docs
Removed the outdated build/install information from README.md
Link from README to Read The Docs
Updated the splash page for Read The Docs
parent 7e6ea389
No related branches found
No related tags found
No related merge requests found
Expand all Hide whitespace changes
Inline Side-by-side
.travis.yml
+ 1
− 1
View file @ 0cf65a4c
......@@ -20,7 +20,7 @@ env:
- BUILD_NAME=tbb WITH_THREAD=tbb WITH_DISTRIBUTED=serial
# test mpi
- BUILD_NAME=mpi WITH_THREAD=cthread WITH_DISTRIBUTED=mpi
- BUILD_NAME=mpitbb WITH_THREAD=tbb WITH_DISTRIBUTED=mpi
- BUILD_NAME=mpitbb WITH_THREAD=tbb WITH_DISTRIBUTED=mpi
before_install:
- CC=gcc-5
......
CMakeLists.txt
+ 8
− 3
View file @ 0cf65a4c
......@@ -11,8 +11,13 @@ if ("${CMAKE_VERSION}" MATCHES "^3.[0-9].")
cmake_policy(SET CMP0023 OLD)
endif()
# save incoming CXX flags for forwarding to modcc external project
set(SAVED_CXX_FLAGS "${CMAKE_CXX_FLAGS}")
# Set release as the default build type.
# Otherwise, CMake will default to debug.
if (NOT CMAKE_BUILD_TYPE)
set(CMAKE_BUILD_TYPE release CACHE STRING "Choose the type of build." FORCE)
# Set the possible values of build type for cmake-gui
set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "debug" "release")
endif()
# compilation flags
set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake")
......@@ -205,7 +210,7 @@ endif()
#----------------------------------------------------------
# vectorization target
#----------------------------------------------------------
set(ARB_VECTORIZE_TARGET "none" CACHE STRING "CPU target for vectorization {KNL,AVX2,AVX512}")
set(ARB_VECTORIZE_TARGET "none" CACHE STRING "CPU target for vectorization {none,KNL,AVX2,AVX512}")
set_property(CACHE ARB_VECTORIZE_TARGET PROPERTY STRINGS none KNL AVX2 AVX512)
# Note: this option conflates modcc code generation options and
......
README.md
+ 5
− 220
View file @ 0cf65a4c
# Arbor Library [![Build Status](https://travis-ci.org/eth-cscs/arbor.svg?branch=master)](https://travis-ci.org/eth-cscs/arbor)
# Arbor Library
This is the repository for the Arbor library. Unfortunately we do not have thorough documentation of how-to guides.
Below are some guides for how to build the project and run the miniapp.
Contact us or submit a ticket if you have any questions or want help.
https://github.com/eth-cscs/arbor
[![Build Status](https://travis-ci.org/eth-cscs/arbor.svg?branch=master)](https://travis-ci.org/eth-cscs/arbor)
1. Basic installation
2. MPI
3. TBB
4. TBB on Cray systems
5. Targeting KNL
6. Examples of environment configuration
- Julia
## Basic installation
```bash
# clone repository
git clone git@github.com:eth-cscs/arbor.git
cd arbor/
Arbor is a library for implementing performance portable network simulations of multi-compartment neuron models.
# setup environment
# on a desktop system this is probably not required
# on a cluster this is usually required to make sure that an appropriate
# compiler is chosen.
module load gcc
module load cmake
export CC=`which gcc`
export CXX=`which g++`
# build main project (out-of-tree)
mkdir build
cd build
cmake <path to CMakeLists.txt>
make -j
# test
cd tests
./test.exe
```
## MPI
Set the `ARB_WITH_MPI` option either via the ccmake interface, or via the command line as shown below.
To ensure that CMake detects MPI correctly, you should specify the MPI wrapper for the compiler by setting the `CXX` and `CC` environment variables.
```
export CXX=mpicxx
export CC=mpicc
cmake <path to CMakeLists.txt> -DARB_WITH_MPI=ON
```
## TBB
Support for multi-threading requires Intel Threading Building Blocks (TBB).
When TBB is installed, it comes with some scripts that can be run to set up the user environment.
The scripts set the `TBB_ROOT` environment variable, which is used by the CMake configuration to find TBB.
```
cmake <path to CMakeLists.txt> -DARB_THREADING_MODEL=tbb
```
### TBB on Cray systems
TBB requires dynamic linking, which is not enabled by default in the Cray programming environment.
CMake is quite brittle, so take care to follow these step closely.
TBB provides a CMake package that will attempt to automatically download and compile TBB from within CMake.
Set the environment variable `CRAYPE_LINK_TYPE=dynamic`, to instruct the Cray PE linker to enable dynamic linking.
CMake (at least since CMake 3.6) will automatically detect the Cray programming environment, and will by default use static linking, unless the `CRAYPE_LINK_TYPE` environment variable has been set to `dynamic`.
Note, the CMake package provided by TBB is very fragile, and won't work if CMake is forced to use the `CrayLinuxEnvironment` as shown in the code below. Instead, let Cmake automatically detect the programming environment.
```
export CRAYPE_LINK_TYPE=dynamic
cmake <path-to-arbor-source> -DARB_THREADING_MODEL=tbb
# NOTE: specifying CMAKE_SYSTEM_NAME won't work, instead let CMake automatically
# detect the build environment as above.
cmake <path-to-arbor-source> -DARB_THREADING_MODEL=tbb -DCMAKE_SYSTEM_NAME=CrayLinuxEnvironment
```
```
export CRAYPE_LINK_TYPE=dynamic
```
## targeting KNL
#### build modparser without KNL environment
The source to source compiler "modparser" that generates the C++/CUDA kernels for the ion channels and synapses is in a separate repository.
By default it will be built with the same compiler and flags that are used to build the miniapp and tests.
This can cause problems if we are cross compiling, e.g. for KNL, because the modparser compiler might not be runnable on the compilation node.
You are probably best of building the software twice: Once without KNL support to create the modcc parser and next the KNL version using
the now compiled executable
Modparser requires a C++11 compiler, and has been tested on GCC, Intel, and Clang compilers
- if the default compiler on your is some ancient version of gcc you might need to load a module/set the CC and CXX environment variables.
CMake will look for the source to source compiler executable, `modcc`, in the `PATH` environment variable, and will use the version if finds instead of building its own.
So add the g++ compiled modcc to your path
e.g:
```bash
# First build a 'normal' non KNL version of the software
# Load your environment (see section 6 for detailed example)
export CC=`which gcc`; export CXX=`which g++`
# Make directory , do the configuration and build
mkdir build
cd build
cmake <path to CMakeLists.txt> -DCMAKE_BUILD_TYPE=release
make -j8
# set path and test that you can see modcc
export PATH=`pwd`/modcc:$PATH
which modcc
```
#### set up environment
- source the intel compilers
- source the TBB vars
- I have only tested with the latest stable version from on-line, not the version that comes installed sometimes with the Intel compilers.
#### build miniapp
```bash
# clone the repository and set up the submodules
git clone https://github.com/eth-cscs/arbor.git
cd arbor
# make a path for out of source build
mkdir build_knl
cd build_knl
# run cmake with all the magic flags
export CC=`which icc`
export CXX=`which icpc`
cmake <path to CMakeLists.txt> -DCMAKE_BUILD_TYPE=release -DARB_THREADING_MODEL=tbb -DARB_WITH_PROFILING=ON -DARB_VECTORIZE_TARGET=KNL
make -j
```
The flags passed into cmake are described:
- `-DCMAKE_BUILD_TYPE=release` : build in release mode with `-O3`.
- `-DARB_THREADING_MODEL=tbb` : use TBB for threading on multi-core
- `-DARB_WITH_PROFILING=ON` : use internal profilers that print profiling report at end
- `-DARB_VECTORIZE_TARGET=KNL` : generate AVX512 instructions, alternatively you can use:
- `AVX2` for Haswell & Broadwell
- `AVX` for Sandy Bridge and Ivy Bridge
Currently, the Intel compiler is required when you specify a vectorize target.
#### run tests
Run some unit tests
```bash
cd tests
./test.exe
cd ..
```
## run miniapp
The miniapp is the target for benchmarking.
First, we can run a small problem to check the build.
For the small test run, the parameters have the following meaning
- `-n 1000` : 1000 cells
- `-s 200` : 200 synapses per cell
- `-t 20` : simulated for 20ms
- `-p 0` : no file output of voltage traces
The number of cells is the number of discrete tasks that are distributed to the threads in each large time integration period.
The number of synapses per cell is the amount of computational work per cell/task.
Realistic cells have anywhere in the range of 1,000-10,000 synapses per cell.
```bash
cd miniapp
# a small run to check that everything works
./miniapp.exe -n 1000 -s 200 -t 20 -p 0
# a larger run for generating meaningful benchmarks
./miniapp.exe -n 2000 -s 2000 -t 100 -p 0
```
This generates the following profiler output (some reformatting to make the table work):
```
---------------------------------------
| small | large |
-------------|-------------------|-------------------|
total | 0.791 100.0 | 38.593 100.0 |
stepping | 0.738 93.3 | 36.978 95.8 |
matrix | 0.406 51.3 | 6.034 15.6 |
solve | 0.308 38.9 | 4.534 11.7 |
setup | 0.082 10.4 | 1.260 3.3 |
other | 0.016 2.0 | 0.240 0.6 |
state | 0.194 24.5 | 23.235 60.2 |
expsyn | 0.158 20.0 | 22.679 58.8 |
hh | 0.014 1.7 | 0.215 0.6 |
pas | 0.003 0.4 | 0.053 0.1 |
other | 0.019 2.4 | 0.287 0.7 |
current | 0.107 13.5 | 7.106 18.4 |
expsyn | 0.047 5.9 | 6.118 15.9 |
pas | 0.028 3.5 | 0.476 1.2 |
hh | 0.006 0.7 | 0.096 0.2 |
other | 0.026 3.3 | 0.415 1.1 |
events | 0.005 0.6 | 0.125 0.3 |
sampling | 0.003 0.4 | 0.051 0.1 |
other | 0.024 3.0 | 0.428 1.1 |
other | 0.053 6.7 | 1.614 4.2 |
-----------------------------------------------------
```
## Examples of environment configuration
### Julia (HBP PCP system)
``` bash
module load cmake
module load intel-ics
module load openmpi_ics/2.0.0
module load gcc/6.1.0
```
An installation guide and library documentation are available online at [Read the Docs](http://arbor.readthedocs.io/en/latest/).
[Submit a ticket](https://github.com/eth-cscs/arbor) if you have any questions or want help.
doc/index.rst
+ 33
− 4
View file @ 0cf65a4c
Arbor
=====
Arbor is a high-performance library for computationa neurscience simulations.
.. image:: https://travis-ci.org/eth-cscs/arbor.svg?branch=master
:target: https://travis-ci.org/eth-cscs/arbor
.. toctree::
:maxdepth: 1
What is Arbor?
--------------
Arbor is a high-performance library for computational neurscience simulations.
The development team is from from high-performance computing (HPC) centers:
* Swiss National Supercomputing Center (CSCS), Jülich and BSC in work package 7.5.4 of the HBP.
* Aim to prepare neuroscience users for new HPC architectures;
Arbor is designed from the ground up for **many core** architectures:
* Written in C++11 and CUDA;
* Distributed parallelism using MPI;
* Multithreading with TBB and C++11 threads;
* **Open source** and **open development**;
* Sound development practices: **unit testing**, **continuous Integration**,
and **validation**.
Features
--------
We are actively developing Arbor, improving performance and adding features.
Some key features include:
introduction
* Optimized back ends for CUDA, KNL and AVX2 intrinsics.
* Asynchronous spike exchange that overlaps compute and communication.
* Efficient sampling of voltage and current on all back ends.
* Efficient implementation of all features on GPU.
* Reporting of memory and energy consumption (when available on platform).
* An API for addition of new cell types, e.g. LIF and Poisson spike generators.
* Validation tests against numeric/analytic models and NEURON.
.. toctree::
:caption: Getting Stared:
......
doc/install.rst
+ 648
− 25
View file @ 0cf65a4c
This diff is collapsed.
doc/introduction.rst deleted 100644 → 0
+ 0
− 5
View file @ 7e6ea389
Why Arbor?
##########
The diverse ecosystem of emerging HPC computing architectures promises exciting opportunities for larger, more detailed simulations run over longer time periods.
Arbor is a library developed by the HPC community to help computational neuroscientists take advantage of such systems.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment