= Installation guide =

<<TableOfContents()>>

== Download - How to get access ? ==


We have a public licence version for everybody who is interested to use the library. For those who are interested to contribute to the library or need latest changes in a collaboration project we provide access to the developers version.

For the communication in between them we have the Git server.

=== Download of a public licence version ===

We will provide in short time a version of the Concepts library under GPL licence at this place.

=== Download of the developers version ===

Access to the current developing version of Concepts is offered via the version management system Git and using Gitlab under request. For this contact [[Kersten]].

If you have obtained the access details login into Gitlab, the graphical user interface to Git, at [[https://git-ce.rwth-aachen.de/users/sign_in]] and contact [[Kersten]] again to be added to the project.

Then, once you have been added to the project, proceed as follows.

   * Add your public RSA key on the page [[https://git-ce.rwth-aachen.de/profile/keys]]
   * Create a local directory to download the library to and in which you will write your own applications, ''e.g.'', {{{/scratch/kersten}}}.
   * Check out the directory into the local directory - the line containing the git command should be copied ''as it'': {{{cd /scratch/kersten ; git clone git@git-ce.rwth-aachen.de:concepts/concepts-dev.git}}} A new subdirectory {{{Concepts-Dev}}} is created, in which the library is downloaded.
   * Define locally the git environment variables 
   {{{
cd Concepts-Dev
git config credential.username <GIT_USERNAME>;
git config user.name <GIT_USERNAME>;
git config user.email <MY_EMAILADDRESS>;
git config push.default current
   }}} where {{{<GIT_USERNAME>}}} is your git user name, and {{{<MY_EMAILADDRESS>}}} is your eMail address. With these environment variables the username is never asked again and the identity for pushing code is set.
   * Set up your {{{~/.profile}}} file and add at the end of this file: 
   {{{
export EDITOR=/usr/bin/nano
export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8
export LANGUAGE=en_US.UTF-8
   }}} The executable defined by the {{{EDITOR}}} environment variable is the program called when you commit and have to enter the commit message.
   * In this following of this installation guide we call {{{$(CONCEPTS_DEV)}}} the path you installed the Concepts library, here {{{/scratch/kersten/Concepts-Dev}}}.

=== First run: creation of the configuration files ===

Run the configuration script

{{{
cd $(CONCEPTS_DEV) 
./configure
}}}

that will generate the files {{{boost-build.jam}}}, {{{boost-build-modules.jam}}}, {{{Jamfile}}} and {{{project-root.jam}}}. You also have to add the path to the (future) Concepts library writing in your {{{~/.profile}}} file

{{{
export CONCEPTS_DEV="/scratch/kersten/Concepts-Dev"
export LD_LIBRARY_PATH="$CONCEPTS_DEV/libconcepts:$LD_LIBRARY_PATH"
}}}

then reload the configuration using {{{source ~/.profile}}}, if your using ''e.g.'' bash on Ubuntu.


== Pre-setup environment ==

The Concepts library requires the GCC compiler (version >= 4.8.1) or the LLVM compiler (version >= 3.4.x) with the support of the C++-11 standard. 
If this compiler is not natively available on your system, you have to preset the environment to be able to use it.

=== Pre-setup environment (Linux) ===

Make sure that you have administrative rights or ask your system administrator to do so. For the Linux distributions Debian or Ubuntu install the packages
{{{gcc gfortran g++}}} using the packet manager if you want to use the {{{gcc}}} compiler, and install the packages {{{clang libclang-common-dev}}}
using the packet manager if you want to use the {{{clang}}} compiler.

=== Pre-setup environment (MAC OS X System) ===

Make sure that you have administrative rights or ask your system administrator to do so.
   * Install XCode (using [[https://developer.apple.com/technologies/ Mac App Store]])
   * Run the license agreement typing in a terminal {{{sudo xcodebuild -license}}}
   * Run the XCode program - it will setup components. Make sure that you install "Command Line Tools" (you can still install in Xcode by going to Xcode -&gt; Preferences -&gt; Downloads). You'll need them to compile any program using command-line tools. At this point, typing in a terminal the command {{{gcc -v}}} should give a result.
   * Retrieve Brew on [[https://brew.sh/index]] and install it.
   * Install gcc (tested with version 4.9.3) typing in a terminal {{{brew install gcc49}}} The associated command is gcc-mp-4.9 so that the instruction {{{gcc-mp-4.9 -v}}}} should give a result. The same occurs for the commands g++-mp-4.9 and gfortran-mp-4.9.

=== Pre-setup environment (Windows 10 System, 64-bits version) ===

Make sure that you have administrative rights or ask your system administrator to do so. Install [[https://msdn.microsoft.com/en-us/commandline/wsl/install_guide|Bash on Ubuntu on Windows]] then follow the Linux-related instructions. If you cannot manage to download the Ubuntu app from the Windows store, one possible solution is to run the {{{Powershell}}}  program as an administrator and type {{{lxrun /install}}}.

== Installation of tools for compilation ==

There are two others tools that are used during the compilation process: [[http://www.boost.org/doc/tools/build/index.html|Boost Build]] and the coupled Bison and Flex compilers.

=== Installation of bjam ===

{{{bjam}}} is the tool used for the compilation process.

==== Installing packages in Debian, Ubuntu or Redhat ====

For the Linux distributions Debian or Ubuntu install the package {{{libboost-tools-dev}}}

==== Direct installation ====

The manual installation holds as follow:
   * Download the latest release (current version: 2014.10) |{{{wget https://github.com/boostorg/build/releases/download/2014.10/boost-build-2014-10.tar.bz2}}}
   * Unzip the archive typing {{{tar jxvf boost-build-2014-10.tar.bz2}}}
   * Install bjam {{{cd boost-build ; sh ./bootstrap.sh ; ./b2 install --prefix=/where/I/put/boost-build-dir}}}
   * In {{{~/.profile}}} file, you have to add the path to bjam {{{export PATH="/where/I/put/boost-build-dir/bin:$PATH"}}} then reload the configuration using {{{source ~/.profile}}}

=== Installation of bison and flex ===

==== Installing packages in Debian, Ubuntu or Redhat ====

For the Linux distributions Debian or Ubuntu install the package 
{{{flex bison libfl-dev}}}

==== Direct installation ====

The manual installation holds as follow:
   * Install the latex tools typing in a terminal {{{sudo port install texlive}}}
   * Download the archive at [[http://sourceforge.net/projects/flex/files/]], tested with file {{{flex-2.5.39.tar.bz2}}}
   * Unzip the archive <pre>tar jxvf flex-2.5.39.tar.bz2</pre>
   * Configure the flex library (depending on the version of gcc you've installed) <pre>cd flex-2.5.39 ; ./configure --prefix=$HOME/flex-build CC="gcc-mp-4.9" CXX="gcc-mp-4.9"</pre>
   * Edit manually the files Makefile.am and Makefile.in . In these two files, remove all entries <pre>--no-undefined</pre>
   * Install flex <pre>make distclean ; ./configure --prefix=$HOME/flex-build CC="gcc-mp-4.9" CXX="gcc-mp-4.9" ; make ; make install</pre>

If you encounters issues with bison and/or flex, you can disable then using {{{USE_DUMMY=yes;}}} in your configuration file.

'''Remark''' while using {{{USE_DUMMY=yes;}}}, there might be issues into loading .cig files.

=== Installation of python ===

If you want to compile the Python version of Concepts, or if you want to use the CIG mesh generator, you have to install the {{{python}}} (version 2.x) interpreter and subsequent libraries. This program can be installed using your package manager.

==== Installing packages in Debian ====

For the Linux distributions Debian or Ubuntu install the package {{{python2.7-dev libpython2.7 libboost-python-dev python-numpy python-scipy scons python-matplotlib}}}


==== Manual installation ====

   * Download python here at [[https://www.python.org/downloads/]] and follow the installation instructions.
   * Download numpy here at [[http://www.scipy.org/scipylib/download.html]] and follow the installation instructions.

==== Installation of the boost.numpy package ====

There are two ways to obtain the {{{boost.numpy}}} package:
   * Using the embedded version
   {{{
cd $(CONCEPTS_DEV)/python/boostnumpy/
scons install --install-sandbox=.
   }}}
   This instruction will create the header files in the folder {{{$(CONCEPTS_DEV)/python/boostnumpy/usr/local/include}}}
   and the libraries in the folder {{{$(CONCEPTS_DEV)/python/boostnumpy/usr/local/lib}}}.

   * Using the latest version
   {{{
git clone https://github.com/ndarray/Boost.Numpy.git
cd Boost.Numpy
git clone https://github.com/classner/SConsChecks.git
scons install --install-sandbox=.
   }}}

In both cases, you will have to set up the {{{boost-build-modules.jam}}}
{{{
modules.poke : BOOSTNUMPY_PATH        : /path/to/boostnumpy/usr/local/lib ;
modules.poke : BOOSTNUMPY_INCLPATH    : /path/to/boostnumpy/usr/local/include ;
}}}

=== Remarks ===

   * Since the default Python library name is not {{{libpython.*}}}, you have to set up the environment variable {{{PYTHON_VERSION}}} in your {{{boost-build-modules.jam}}} file. For example, if your Python library name is {{{libpython2.7.so}}}, then you have to set {{{PYTHON_VERSION = 2.7 ;}}}As well, you might have to setup the variable {{{PYTHON_INCLPATH}}}, ''e.g.'' {{{PYTHON_INCLPATH = /usr/include/python2.7 ;}}}
   * In {{{~/.profile}}} file, you have to add the path to the CIG mesh generator and the Concepts library using {{{export PYTHONPATH="/scratch/kersten/Concepts-Dev/python/cig/:/scratch/kersten/Concepts-Dev/python:$PYTHONPATH"}}} then reload the configuration using {{{source ~/.profile}}}
   * If you update your boost python version, then boost.numpy has to be recompiled manually. To do so, type {{{cd /path/to/boostnumpy ; rm -rf libs/numpy/src/*.so usr ; scons install --install-sandbox=.}}}
   * With recent version of Boost.Numpy, you might need to add the line {{{modules.poke : BOOSTNUMPY_NEW_NAMESPACE : yes ;}}} in the generated file {{{boost-build-modules.jam}}}.

== Installation of external libraries ==

The standard path for the libraries is either {{{/usr/lib}}}, {{{/usr/lib64}}}, or a directory parallel to the Concepts path {{{$(CONCEPTS_DEV)}}}. For example, if the Concepts path is
{{{/scratch/kersten/Concepts-Dev}}} then Concepts searches for the SuperLU library in
{{{
/usr/lib
/usr/lib64
/scratch/kersten/SuperLU
}}}

To specify individual pathes, edit {{{$(CONCEPTS_DEV)/boost-build-modules.jam}}}.

On MAC OS X system, the additional path {{{/opt/local/lib}}} is added to the standard path list.

=== Required packages ===

The following external libraries '''have to''' be installed into the system path.
   * gfortran library ({{{libgfortran}}}). If your system cannot install this library, you should use {{{libg2c}}} library instead.
   * Realtime Extensions library ({{{librt}}})
   * C Math library ({{{libm}}})

The following external libraries '''have to''' be installed
   * BLAS library ({{{libblas}}})
   * Lapack library ({{{liblapack}}})


=== Additional packages ===

==== Compression library zlib ====

===== Installing packages in Debian =====

For the Linux distributions Debian or Ubuntu install the package {{{zlib1g-dev}}} or the package {{{lib64z1-dev}}}

===== Remarks =====

The installed library must have the name {{{libz.so}}}. If the filename has a suffix of the version number, ''e.g.'' it reads {{{libz.so.3}}}, you need to create a symbolic link by executing {{{sudo ln -s libz.so.3 libz.so}}} in the directory where the library is located.

==== Parallel compiler mpi ====

===== Installing packages in Debian =====

For the Linux distributions Debian or Ubuntu install the packages {{{openmpi-bin openmpi-common libopenmpi-dev}}}.

If you are also using the Python version of Concepts, install the additional package {{{python-mpi4py}}}.

==== Direct solver ====

You can install one of the sparse solvers MUMPS, Umfpack, SuperLU (by order of preference). Furthermore information can be found [[Concepts/installationSolvers|following this link]].

'''Remark''': if you plan to use Concepts to solve sparse (un)symmetric linear systems that involve complex numbers, installation of one of the sparse solvers is required. 

==== Eigenvalue solver ====

You can install one of the eigenvalue solvers Arpack, Trilinos, Jdbsym (by order of preference). Furthermore information can be found [[Concepts/installationEigen|following this link]].

'''Remark''': the shift-and-invert method used by the Arpack eigenvalue solver calls implicitely either the MUMPS direct solver or the SuperLU direct solver, depending on which solver is installed. 

==== Optional libraries ====

These libraries are not required if you want to use Concepts, but add several features used for particular problems. Furthermore information can be found [[Concepts/installationExtra|following this link]].

== Compilation of the Concepts library ==

   * Edit the file {{{boost-build.jam}}} to give the link to the boost-build kernel folder, that contains the file {{{bootstrap.jam}}}, setting the last line of this file to {{{boost-build /path/to/share/boost-build/src/kernel ;}}} For example, if you installed {{{bjam}}} manually into the folder {{{$(BJAM)}}}, then this line becomes {{{boost-build $(BJAM)/share/boost-build/src/kernel ;}}}
   '''Remark''' If you installed {{{bjam}}} using the package manager on Debian or Ubuntu, you don't need to touch this file.

   * Edit the file {{{boost-build-modules.jam}}} to give the library and include paths to the different libraries you use. In addition, you can specify if you want to activate or deactivate the detection of some libraries.

   * Edit the file {{{project-root.jam}}} to give several information about the compiler and the output, namely
      * The compiler that will be used with the associated compiler options. Note that {{{<cflags>}}} should contain at least {{{-fPIC}}}, {{{<cxxflags>}}} should contain at least {{{-fPIC -std=c++11}}} and {{{<ldflags>}}} should contain at least {{{-lstdc++ -lm}}}
      * The output folder that will contain Concepts libraries and binaries. If you're using the public version of Concepts, this folder will be {{{builds}}}. If you're using the Git-controlled version of Concepts, this folder will be {{{builds_$(NAME_OF_THE_GIT_BRANCH)$}}}, ''e.g.'' {{{builds_master_}}}.


   * Edit the Jamfile to set up the flags on the parts of the code you want to compile. You should modify only the {{{yes-no}}} flags.

   * Compile the library using <pre>cd $(CONCEPTS_DEV) <br />bjam </pre> where you can use the following options
      * {{{-jn}}} to compile using {{{n}}} threads (useful on multi-core machines),
      * {{{-a}}} to recompile even targets that are up-to-date,
      * {{{-q}}} (especially when you're testing the code you wrote) to stop the compilation on the first error found,
      * {{{-dn}}} to have more debugging information. (The default behaviour corresponds to the flag {{{-d1}}}. With the flag {{{-d2}}} you can see which commands and arguments are invoked behind each file compiled.)

=== Errors during compilation ===


'''Remark''' If you get the error
{{{
don't know how to make &lt;pbuilds/toolbox/gcc-4/debug-object(c-scanner)@3334&gt;input.cpp<br />don't know how to make &lt;pbuilds/toolbox/gcc-4/debug-object(c-scanner)@3329&gt;lexer.c
}}}
during the compilation, the reason is that you're using a too old version of {{{bjam}}} (''e.g.'' the verions 2011.12). We should recommend you to upgrade your version of bjam. Alternatively, you can let the first compilation run until {{{bjam}}} tried to create the {{{libconceptstoolbox}}} library, stop it, and re-run it.

'''Remark''' If you get the error 
{{{
undefined reference to `zbesh_wrap'
}}}
or a similar error during the compilation, you should add the line  
{{{<library>/site-config//gfortran}}}
in the file {{{$(CONCEPTS_DEV)/Jamfile}}} just after the line {{{requirements <hardcode-dll-paths>true}}}.

= Documentation =

If you want to compile the class and examples documentation, you have to install Doxygen.


== Installing packages in Debian, Ubuntu or Redhat ==

For the Linux distributions Debian or Ubuntu install the package {{{doxygen}}}. To generate formulas the package {{{texlive}}} should also be installed.

== Manual installation ==

You can get the source or binary files at [[https://www.doxygen.nl/download.html|this page]], and follow the installation instructions. A valid LaTeX installation should also be there to generate formulas.

== Documentation generation ==

Command call to generate the documentation is, in the Concepts root folder, {{{make doxygen}}}. Documentation output will be in the {{{$(CONCEPTS_DEV)/doc/doxygen}}} folder. 

I you want to generate the documentation calling the Doxygen program directly, the file you have to open inside is the file {{{$(CONCEPTS_DEV)/doc/doxygenrc_local}}}.

= Write your first application =

   * Upload your public SSH at https://git-ce.rwth-aachen.de/profile/keys .
   * In Gitlab, fork the repository https://git-ce.rwth-aachen.de/concepts/concepts-app into your own workspace, ''e.g.'' https://git-ce.rwth-aachen.de/kschmidt/concepts-app.
   * Still in Gitlab, edit your repository (''e.g.'' https://git-ce.rwth-aachen.de/kschmidt/concepts-app/edit) and rename it (''e.g.'' to {{{app-kersten}}} ). Also, you can remove the fork dependency.
   * Check out the repository into the local directory - the line containing the git command should be copied ''as it'': {{{cd /scratch/kersten ; git clone https://git-ce.rwth-aachen.de/schmidtk/app-kersten.git}}}
   * Define locally the git environment variables 
   {{{
cd app-kersten
git config credential.username <GIT_USERNAME>
git config user.name <GIT_USERNAME>
git config user.email <MY_EMAILADDRESS>
   }}} where {{{<GIT_USERNAME>}}} is your git user name, and {{{<MY_EMAILADDRESS>}}} is your eMail address. With these environment variables the username is never asked again and the identity for pushing code is set.
   * Configure the application, giving in argument the root path to the Concepts library: {{{./configure $(CONCEPTS_DEV) ; bjam}}}
   * That's it.

----
Read access to these pages for all, read-write access for members of [[ConceptsMembersGroup]].