Project Concepts

Installation guide

=== 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 to the users and in between them we have the mailing list: ["https://lists.math.ethz.ch/sympa/info/concepts-users"]

==== 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 [:People:Kersten].

If you have obtained the access details login into gitlab, the graphical user interface to git, at [:https://gitlab.math.ethz.ch/users/sign_in]] and contact [[People:Kersten] again to be added to the project.

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

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: <pre>cd /scratch/kersten ; git clone https://gitlab.math.ethz.ch/concepts/Concepts-Dev.git</pre> A new subdirectory Concepts-Dev is created, in which the library is downloaded.
Define locally the git environment variables <pre>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</pre> 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: <pre>export EDITOR=/usr/bin/nano export LC_ALL=en_US.UTF-8 export LANG=en_US.UTF-8 export LANGUAGE=en_US.UTF-8</pre> 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

<pre> cd $(CONCEPTS_DEV) ./configure </pre>

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

<pre>export CONCEPTS_DEV="/scratch/kersten/Concepts-Dev" export LD_LIBRARY_PATH="$CONCEPTS_DEV/libconcepts:$LD_LIBRARY_PATH"</pre>

then reload the configuration using

<pre>source ~/.profile</pre>

if your using e.g. bash on Ubuntu.

=== Pre-setup environment

The Concepts library requires the GCC compiler (version >= 4.7.x) 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 th 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

<pre>gcc gfortran g++</pre>

using the packet manager if you want to use the gcc compiler, and install the packages

<pre>clang libclang-common-dev</pre>

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 <pre>sudo xcodebuild -license</pre>
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 -> Preferences -> Downloads). You'll need them to compile any program using command-line tools. At this point, typing in a terminal the command <pre>gcc -v</pre> should give a result.
Retrieve MacPorts on ["http://www.macports.org"] and install it.
In a terminal, type <pre>sudo port selfupdate</pre>
Install gcc (tested with version 4.9.3) typing in a terminal <pre>sudo port install gcc49</pre> The associated command is gcc-mp-4.9 so that the instruction <pre>gcc-mp-4.9 -v</pre> 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 <pre>libboost-tools-dev</pre>

===== !! Direct installation

=====

The manual installation holds as follow:

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

==== Installation of bison and flex

====

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

=====

For the Linux distributions Debian or Ubuntu install the package <pre>flex bison libfl-dev</pre>

===== !! Direct installation

=====

The manual installation holds as follow:

Install the latex tools typing in a terminal <pre>sudo port install texlive</pre>
Download the archive at ["http://sourceforge.net/projects/flex/files/"], tested with file <pre>flex-2.5.39.tar.bz2</pre>
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

<pre>python2.7-dev libpython2.7 libboost-python-dev python-numpy python-scipy scons python-matplotlib</pre>

===== !! 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<pre>cd $(CONCEPTS_DEV)/python/boostnumpy/

scons install --install-sandbox=. </pre>

This instruction will create the header files in the folder =/usr/local/include= and the libraries in the folder =/usr/local/lib=.
Using the latest version<pre>git clone https://github.com/ndarray/Boost.Numpy.git

cd Boost.Numpy git clone https://github.com/classner/SConsChecks.git scons install --install-sandbox=.</pre>

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

==== !! 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 <pre>PYTHON_VERSION = 2.7 ;</pre>As well, you might have to setup the variable PYTHON_INCLPATH, e.g. <pre>PYTHON_INCLPATH = /usr/include/python2.7 ;</pre>
- In =~/.profile= file, you have to add the path to the CIG mesh generator and the Concepts library using <pre>export PYTHONPATH="/scratch/kersten/Concepts-Dev/python/cig/:/scratch/kersten/Concepts-Dev/python:$PYTHONPATH"</pre>then reload the configuration using <pre>source ~/.profile</pre>
- If you update your boost python version, then boost.numpy has to be recompiled manually. To do so, type <pre>cd /path/to/boostnumpy ; rm -rf libs/numpy/src/*.so usr ; scons install --install-sandbox=.</pre>

=== 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

<pre>/scratch/kersten/Concepts-Dev</pre>

then Concepts searches for the !SuperLU library in

<pre>/usr/lib /usr/lib64 /scratch/kersten/SuperLU</pre>

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

or the package

===== !! 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 <pre>sudo ln -s libz.so.3 libz.so </pre> 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

<pre>openmpi-bin openmpi-common libopenmpi-dev</pre>

If you are also using the Python version of Concepts, install the additional package

<pre>python-mpi4py</pre>

===== Direct solver

=====

You can install one of the sparse solvers MUMPS, Umfpack, !SuperLU (by order of preference). Furthermore information can be found [:InstallationGuideDirectSolver: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 [:InstallationGuideEigenvalueSolver: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 [:InstallationGuideExtraLibraries: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 <pre>boost-build /path/to/share/boost-build/src/kernel ;</pre> For example, if you installed bjam manually into the folder =$(BJAM)=, then this line becomes <pre>boost-build $(BJAM)/share/boost-build/src/kernel ;</pre> 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) 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

<pre>don't know how to make <pbuilds/toolbox/gcc-4/debug-object(c-scanner)@3334>input.cpp don't know how to make <pbuilds/toolbox/gcc-4/debug-object(c-scanner)@3329>lexer.c</pre>

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

<pre>undefined reference to `zbesh_wrap'</pre>

or a similar error during the compilation, you should add the line

<pre><library>/site-config//gfortran</pre>

in the file =$(CONCEPTS_DEV)/Jamfile= just after the line requirements <hardcode-dll-paths>true.

== Write your first application

==
- In Gitlab, fork the repository https://gitlab.math.ethz.ch/concepts/Concepts-App into your own workspace, e.g. https://gitlab.math.ethz.ch/schmidtk/Concepts-App.
- Still in Gitlab, edit your repository (e.g. https://gitlab.math.ethz.ch/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: <pre>cd /scratch/kersten ; git clone https://gitlab.math.ethz.ch/schmidtk/app-kersten.git</pre>
- Define locally the git environment variables <pre>cd app-kersten git config credential.username <GIT_USERNAME> git config user.name <GIT_USERNAME> git config user.email <MY_EMAILADDRESS></pre> 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: <pre>./configure $(CONCEPTS_DEV) ; bjam</pre>
- That's it.

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