Installing the library

This file contains a brief summary or the steps needed to install DeNSE on various platforms.

It is divided into:

• details on the software required to install and run DeNSE,

• specific installation procedures for Linux, MacOS, and Windows,

• details about the manual installation and additional options that can be passed to configure and install DeNSE,

• details about configuring the various paths that may be required to make your system aware of the existence of DeNSE.

The configuration and installation of DeNSE is provided by a CMake script which should provide a convenient multiplatform experience, made even easier by the automatic install scripts available on most platforms.

NB if you run against some bugs after the installation, please first have a look at the “Known errors” section, in case it is not already listed there.

Contents

• Installing the library

  • Requirements

  • Automatic installation

  • Manual installation

  • Manual installation of Boost

  • Configuring the paths (Linux and Mac)

  • Launching

  • Common errors

Requirements

Before installation, several tools must be pre-installed, including

1. A set of software and libraries

   • CMake

   • A C and C++11-compliant compiler such as GCC (4.8.1+)

   • Python (2.7 or 3.3+) and its header/development files

   • GEOS (3.5+) and its header/development files

   • Boost Geometry and Range (Boost 1.62 or higher)

   • Cython

2. Some python modules

   • setuptools

   • numpy

   • scipy

   • shapely

   • pint

3. Doxygen, Sphinx, and Breathe to compile the documentation locally

4. Optional python modules are also required to use DeNSE to full capability

   • NNGT to interface the graph libraries with DeNSE

   • networkx, igraph, or graph-tool to analyze generated networks

   • matplotlib or seaborn to plot neurons and results

   • svg.path and dxfgrabber to load SVG and DXF files to create complex environments

   • PyOpenGL to efficiently seed neurons in complex environments

   • ipython or jupyter for better interactive sessions

Automatic installation

Automatic installation files for several linux distributions are provided in the extra folder. Since these require you to have administrative rights and input your password, please check that they were not tampered with before executing them.

Using automatic install files, DeNSE should be compiled and installed directly in local system directories (in ~/.local, i.e. in your home folder). The documentation should be viewable by opening ~/.local/dense_doc/index.html with your internet browser.

Debian-based systems (Ubuntu, Mint…)

The whole procedure can be performed directly by running:

cd extra
./install_debian.sh

Note that this may require you to add running permission to it through:

chmod u+x install_debian.sh

Once this is over, go to the “Launching” part.

Otherwise, first install the required tools:

sudo apt install cmake g++ python python-dev python-pip libboost-dev libgeos++-dev

Then use pip to install the required python libraries:

pip install --user setuptools
pip install --user cython
pip install --user numpy scipy shapely pint svg.path dxfgrabber PyOpenGL

If you want to compile the documentation, also run:

sudo apt install doxygen
pip install --user sphinx breathe sphinx-bootstrap-theme

To install the optional modules run:

pip install --user networkx nngt svg.path
sudo apt install python-matplotlib python-tk

Once this is done, you can try to run the generic linux install.

Arch-based systems

The whole procedure can be performed directly by running:

cd extra
./install_arch.sh

Note that this may require you to add running permission to it through:

chmod u+x install_arch.sh

Once this is over, go to the “Launching” part.

Otherwise, first install the required tools:

sudo pacman -S cmake gcc python python-pip geos boost boost-libs

Then use pip to install the required python libraries:

pip install --user setuptools
pip install --user cython
pip install --user numpy scipy shapely pint svg.path dxfgrabber PyOpenGL

If you want to compile the documentation, also run:

sudo pacman -S doxygen python-sphinx
pip install --user breathe sphinx-bootstrap-theme

To install the optional modules run:

pip install --user networkx nngt
sudo pacman -S python-matplotlib

Once this is done, you can try to run the generic linux install.

CentOS, Fedora, and RedHat systems

Unfortunately, it seems that for most RedHat systems, the available versions of GEOS are still 3.4, which is not sufficient to build DeNSE.

In case this changes, the whole procedure could be performed directly by running:

cd extra
./install_centos.sh

Note that this may require you to add running permission to it through:

chmod u+x install_centos.sh

Once this is over, go to the “Launching” part.

Still, if it gets updated to GEOS 3.5+, on CentOS, GEOS can be made available by getting the Fedora repositories first:

sudo yum install epel-release
sudo yum repolist

Theoretically, you can then run ./install_fedora.sh.

Otherwise, you can then install the required tools:

sudo yum install gcc gcc-c++ cmake python python-devel python-pip boost boost-devel

However, you will then have to install GEOS yourself (see geos to get the source and find out about the installation)

Then use pip to install the required python libraries:

pip install --user setuptools
pip install --user cython
pip install --user numpy scipy shapely pint svg.path dxfgrabber PyOpenGL

If you want to compile the documentation, also run:

sudo yum install doxygen python-sphinx
pip install --user breathe sphinx-bootstrap-theme

To install the optional modules run:

pip install --user networkx nngt
sudo yum install python-matplotlib

Once this is done, you can try to run the generic linux install.

Generic installation of DeNSE on Linux

If you did not already run a complete install such as “install_debian.sh” but have installed all required software, you can directly run the generic installation of DeNSE through:

cd extra
./install_linux.sh

Otherwise, you can follow the step-by-step procedure in “Manual installation”.

MacOS

The whole procedure can be performed directly by running:

cd extra
./install_macos.sh

If the automatic install fails with a message like:

curl: (35) error:XXX:SSL routines:SSL23_GET_SERVER_HELLO:tlsv1 alert protocol version

then your cURL (and probably your mac) version is too old. You can try updating it from https://curl.haxx.se/download.html, however, at that point I don’t promise anything regarding the possibility of a successful install. Once cURL is updated, try the automatic install again.

Otherwise, check that you have all the things required to install homebrew on https://docs.brew.sh/Installation.

Windows (Anaconda)

This is the “simple” way, if you are not used to UNIX-like platforms. Note that Windows install is highly experimental and might very well not work, so I would advise against wasting too much time on it if troubles arise: install VirtualBox and a random Linux version like Mint, then use DeNSE on the virtual OS.

First, you will need to install Anaconda: https://www.anaconda.com/download/. Once the installation is finished, launch Anaconda Navigator for the final installation steps, then, once it finishes, you can run the Anaconda Prompt from the startup menu.

If you have Chocolatey installed on your computer, you can directly run

choco install openssl.light; choco install miniconda3 –params=”’/AddToPath:1’”; export PATH=”/c/tools/miniconda3:/c/tools/miniconda3/Scripts:/c/tools/miniconda3/Library/bin:/c/tools/miniconda3/bin:$PATH”;

Make sure you have Visual Studio installed including Visual C++, otherwise get it from https://www.microsoft.com/en-us/download/developer-tools.aspx. Make sure you get the .NET, C++ compiler, and MSBuild in the proposed packages, (include Linux tools to get C++ for CMake)

Once in the Anaconda Prompt, run:

conda install cmake geos boost
pip install cython
pip install shapely pint PyOpenGL svg.path dxfgrabber

Then you can just run the installer via:

cd extra
install_windows.cmd

Windows (minimal)

This installation is the most “lightweight” since you “only” have to install Visual Studio on your computer (even though can already take roughly 3 Gb). However, it requires to manually set quite a number of environment variables to make everything work, so it is not recommended for standard users (see the Anaconda install below instead).

Make sure you have Visual Studio installed including Visual C++, otherwise get it from https://www.microsoft.com/en-us/download/developer-tools.aspx. Make sure you get the .NET, C++ compiler, and MSBuild in the proposed packages, (include Linux tools to get C++ for CMake) as well as the Python packages (this will automatically install Python and include it in the path, so you don’t need to do anything more).

Once VisualStudio is installed, download the latest GEOS source file (.tar.bz2) from https://trac.osgeo.org/geos. Unpack the file, then go to the “geos-X.Y.Z” folder and create a new “build” folder.

Open the VisualStudio prompt (e.g. “xAB Native Tools Command Prompt for VS 2017” in the startup menu, with AB your system config, either 64 or 86), then type:

cd C:\path\to\geos-X.Y.Z\build\
cmake .. -DCMAKE_INSTALL_PREFIX=geos_prefix
cmake --build . --config Release --target INSTALL

where``geos_prefix`` is the path where you want GEOS to be installed. This should compile and install GEOS.

Add to the PATH: - open Control Panel - go to System > Advance System Settings - this should open the System Properties window on the “Advanced” tab - click on the “Environment Variables…” button - go to “System variables”, select PATH and click “Edit…” - add the “geos_prefix” path, separated from the previous entry by a semicolumn.

To use Python and pip, you need to add their folder to the PATH. Using the MSVC install, the folders are: - C:/Program Files (xAB)/Microsoft Visual Studio/Shared/PythonXY_AB/ for Python - C:/Program Files (xAB)/Microsoft Visual Studio/Shared/PythonXY_AB/Scripts for pip

Again, AB is your system configuratio (64 or 86) and XY give the Python version. You can add them to the PATH using the previous procedure, otherwise you will have to “cd” to the directories every time you want to execute either Python or pip.

From then on, install the required python packages:

pip install --user cython
pip install --user numpy scipy pint shapely PyOpenGL svg.path dxfgrabber
pip install --user matplotlib

Same as before, you will need to add Cython to the PATH (but pip will warn you about that, giving you the path that you need to add).

Once everything is ready, go to the source folder of DeNSE, create a “build” directory, then:

cd X:/path/to/DeNSE/build
set DISTUTILS_USE_SDK 1
cmake .. -DCMAKE_INSTALL_PREFIX=X:/where/you/want/dense/to/be/installed
cmake --build . --config Release --target INSTALL

Manual installation

Note that manual installation requires that you already installed all the dependencies of DeNSE listed in “Requirements”.

Making a build directory

Open a terminal in the current folder, then type:

mkdir build
cd build

this creates a “build” directory where the files will be generated.

Once in the “build” folder, has been created and you moved to it, you must configure the installation to make it specific to your system and generate the Makefile, which will be used to compile DeNSE. This is done through CMake.

Configuring with CMake

!IMPORTANT! Before executing CMake, always make sure that the build folder is empty (i.e. that you are performing a “clean” install). This will avoid numerous problems linked to partial configurations including outdated paths, binaries, or libraries.

Once you made sure the “build” directory is empy, run:

cmake ..

Windows user may require the additional:

set DISTUTILS_USE_SDK 1

before invoking cmake.

Additional CMake options

The CMake script accepts several options to customize the installation; these options can be added after “cmake ..”, separated by spaces, and include (do not copy the quotes):

• a custom install path provided through “-DCMAKE_INSTALL_PREFIX=/your/install/path”, which MUST be provided as an absolute path; this can be necessary to install DeNSE for several Python versions or preventing unforeseen conflicts with other libraries such as NEST,

• the path to the GEOS library through “-Dwith-geos=/path/to/libgeos”,

• the deactivation of OpenMP parallelism with “-Dwith-openmp=OFF”,

• the requirement of a specific Python version through “-Dwith-python=X” or “-Dwith-python=X.Y”,

• local compilation of the documentation through “-Dwith-docs=ON”,

• any other valid CMake argument.

As an example, the following command:

cmake .. -DCMAKE_INSTALL_PREFIX=/home/me/Software/DeNSE_install -Dwith-python=3.7

will configure DeNSE to be installed in “/home/me/Software/DeNSE_install” (in bin, and lib subfolders) and set to be run using python 3.7.

Compiling

Upon proper completion of the configuration step, you should see the lines:

You can now build and install DeNSE with
  make
  make install

-- Configuring done
-- Generating done
-- Build files have been written to: /the/current/build/folder

As advised, you can now compile by running (on Linux and Mac):

make && make install

Or on Windows:

cmake --build . --config Release --target INSTALL

Depending on whether you specified a custom path or not, you can now either jump to the “Launching” section, or configure the paths.

Manual installation of Boost

First, download the latest version of Boost (or any version greater or equal to 1.62) on https://www.boost.org/users/download/.

Expand the archive, and open a terminal in the “boost_1_XY_Z/” folder. Once there, type:

./bootstrap.sh
sudo ./b2 install

to install the new boost version in /usr/local where Cmake can easily find it.

Configuring the paths (Linux and Mac)

If all goes well, the installation should be in directories that are included by default in the system’s path and should not require any additional work.

However, if you have performed a manual install with a custom install path, you will need to add declare this path to the system; it may also happen that the automatic install picked a non-default folder, requiring you to manually edit the system’s path to be able to launch DeNSE.

In that case, just execute:

./set_dense_vars.sh

In the unlikely event where this still does not solve the problem (even after rebooting the system) then open the “update_system_path.sh” file and copy the:

export PYTHONPATH="path_to_python_install_dir:$PYTHONPATH"
export LD_LIBRARY_PATH="path_to_lib_install_dir:$LD_LIBRARY_PATH"
export PATH="path_to_bin_install_dir:$PATH"

lines in the file, and search the web for the profile file you should put them in on your specific linux distribution (hint: this is usually ~/.bashrc, ~/.bash_profile, ~/.profile, or /etc/profile).

Note that if you compiled GEOS manually, you might have to add its installation (it is usually located in /usr/local/lib with the manual installation).

Launching

Once DeNSE is installed, you can test that it works correctly by launching it into a Python terminal.

Linux and MacOs

Open a terminal and run:

python

(or ipython), then in the following console, input:

import dense as ds

If the command runs fine, then congratulations, you’re done! If you get an error saying “ImportError: No module named dense”, then go back up to the section on “Configuring the paths”.

To run scripts saved in a python file (e.g. in the examples), run:

python the_script_name.py

Windows

• Minimal install:

  • to run interactively, either install ipython (pip install –user ipython) or start Python (Python or Python Idle in the statup menu)

  • to run a script, open a prompt (preferably a Visual Studio one) and type “python the_script_name.py”

• Anaconda:

  • open the anaconda prompt and type “ipython” to run interactively,

  • otherwise type “python the_script_name.py”.

Common errors

On configure (cmake)

• Any random error message: make sure you did not forget to empty the build folder before reexecuting cmake/make!

• CMake Error at /usr/share/cmake-3.5/Modules/FindBoost.cmake:1677 (message): Unable to find the requested Boost libraries. Boost version: 1.62.0 Boost include path: /usr/local/include Detected version of Boost is too old. Requested version was 1.63 (or newer).

  • this means that you should upgrade your version of boost; for old Linux distributions, manuall install is described in the “Manual Boost installation” section.

• CMake Error at src/cmake_install.cmake:42 (file): file INSTALL cannot copy file “/path/to/DeNSE/build/src/growth” to “/usr/local/bin/growth”.

  • on some CMake versions, the path variable is not properly initialized to its default value and CMake tries to install it to the administrator path. Just clear the build folder and run the configuration and compilation again.

During the install (make/make install)

• Any random error message: Make sure you did not forget to empty the build folder before reexecuting cmake/make!

• Linker error LNK1112 (conflict between module and target machine type)

  • on Windows, this usually means that you are not compiling with the correct version of MSVC. Check that (on a 64-bit platform, you are using the x64 version, or the x86 on a 32-bit platform). If everything is correct, add “-DCMAKE_GENERATOR_PLATFORM=xAB”, where AB is either 64 or 86, to force the correct compiler.

• ModuleNotFoundError: No module named 'dense.environment' For git users, an inability to import _pygrowth from a missing environment module means that the environment submodule has not been initialized with git. To do so, run git submodule init, then git submodule update.

Upon execution of a script

• Script runs into Assertion failed: (!static_cast<bool>("should never be reached")).

  • This is due to a bug in Shapely (#553_) and can be fixed by installing it without its binaries: pip install --no-binary shapely, shapely (note that you first have to uninstall it before reinstalling it).

• Segmentation fault at the end of the script, after all the code has run:

  • This often seems to be a matplotlib bug for which the fix is unknown, but it does not worry us too much because, as mentioned, all the code is executed properly…

  • Alternatively, for people importing NNGT and with NEST installed, it can be caused by an error in the finalize function of NEST, so again, nothing to worry about.