• Concepts
• installation

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 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 -> Preferences -> 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 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: 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 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 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 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 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.