|
Size: 17820
Comment:
|
Size: 91
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 5: | Line 5: |
<<TableOfContents()>> == 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 [[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 <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 <pre>zlib1g-dev</pre> or the package <pre>lib64z1-dev</pre> ===== !! 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) <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 <pre>don't know how to make <pbuilds/toolbox/gcc-4/debug-object(c-scanner)@3334>input.cpp<br />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<br />git config credential.username <GIT_USERNAME><br />git config user.name <GIT_USERNAME><br />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]]. |