Installation Guide
Using Concepts at the TU Berlin
You can have a usage access to Concepts following
this link.
Using Concepts on your own machine
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
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
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:
cd /scratch/kersten ; git clone https://gitlab.math.ethz.ch/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.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
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 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 MacPorts on http://www.macports.org and install it.
- In a terminal, type
sudo port selfupdate
- Install gcc (tested with version 4.9.3) typing in a terminal
sudo port 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
tar jxvf flex-2.5.39.tar.bz2
- Configure the flex library (depending on the version of gcc you've installed)
cd flex-2.5.39 ; ./configure --prefix=$HOME/flex-build CC="gcc-mp-4.9" CXX="gcc-mp-4.9"
- Edit manually the files Makefile.am and Makefile.in . In these two files, remove all entries
--no-undefined
- Install flex
make distclean ; ./configure --prefix=$HOME/flex-build CC="gcc-mp-4.9" CXX="gcc-mp-4.9" ; make ; make install
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
Installation of the boost.numpy package
There are two ways to obtain the
boost.numpy
package:
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=.
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-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
should contain at least -fPIC
,
should contain at least -fPIC -std=c++11
and
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
cd $(CONCEPTS_DEV)
bjam
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 <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
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
.
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:
cd /scratch/kersten ; git clone https://gitlab.math.ethz.ch/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.