INSTALL

                     ____       _   _ ____  _____
                    |  _ \  ___| \ | / ___|| ____|
                    | | | |/ _ \  \| \___ \|  _|
                    | |_| |  __/ |\  |___) | |___
                    |____/ \___|_| \_|____/|_____|



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.

A help for usual issues during compilation is present at the bottom of the file.


Requirements
============

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

1. A set of software and libraries
    * CMake
    * A C and C++14-compliant compiler such as GCC (6.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 (optional)

4. Optional python modules are also required to use DeNSE to full capability
    * matplotlib to plot neurons and results
    * networkx, igraph, or graph-tool to analyze generated networks
    * NNGT to interface the graph libraries with DeNSE
    * 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 <https://trac.osgeo.org/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.