Installation
    

Getting started

The compiler

Seldon is supposed to be fully compliant with the C++ standard. Therefore, it can be compiled by GNU GCC (>=3.0) and by the Intel C++ compiler icc. No tests were conducted with proprietary compilers under Unix, but the compliance with the C++ standard should ensure portability.

Installation

Download the source code (seldon.tar.bz2). Uncompress the file, i.e. under Unix: tar jxvf Seldon.tar.bz2. This will create a directory SELDON in which you will find Seldon. You may also download the matrices (mat_seldon.tar.bz2) used in the tests.

Installation of CBlas

If you want to use the interface with Blas, you also need to have Blas (of course) and CBlas (C interface to the Blas) installed. Seldon uses CBlas to ensure portability of the interface.

Blas is usually installed. If not, you may refer to the dedicated documentation. As for CBlas, download it at http://www.netlib.org/blas/, expand it (e.g. tar -zxvf cblas.tgz), and compile it (e.g. make). The installation is then complete.

Tests

First compile and run test.cpp which is an example provided with Seldon (in the directory test/program). For example:

cd test/program
g++ -I../.. simple_test.cpp && ./a.out

This should return:

Seldon: compilation test
Vector: 0       1       2
Vector: 0       1       2       19

In test.cpp, the first line includes Seldon through SeldonLib.hxx. SeldonLib.hxx is the only file to be included and it is located in the directory SELDON expanded from the downloaded file (see section Installation). If you compile your own code on top of Seldon, just provide the path to seldon to the compiler, e.g.:

g++ -I/path/to/seldon your_code.cpp && ./a.out

A second test is provided: test_Blas.cpp. If Blas and CBlas are properly installed and the library file of CBlas is located in [CBlas-library] (e.g. [CBlas-directory]/lib/LINUX/cblas_LINUX.a), the compilation line should be:

g++ -I../.. test_Blas.cpp [CBlas-library] -lblas -lgfortran && ./a.out

This should return:

Seldon: compilation test with Blas
...

With a lot of lines testing different functions of Blas. If Cblas is already installed in your system or if you installed it by using apt install on linux or fink on mac, you may type the following compilation line:

g++ -I../.. test_Blas.cpp -lcblas -lblas -lgfortran && ./a.out

For older versions of gcc, -lg2c or -lgfortran may be needed. If you are using old intel compiler icc, -lifcore may be needed.

Header files

The file SeldonLib.hxx includes a complete version of Seldon with the following files:

Therefore, it is recommended to include this file. If you want a lighter version of Seldon, you can include only Seldon.hxx for example, you will not have the interface with iterative or direct solvers, the support of distributed matrices, etc. The other advantage in including SeldonLib.hxx is that the same file is included if you want to use or not a compiled version of Seldon, which is the topic of the next section.

Compiled library

A Makefile is proposed for Linux (the file Makefile.LINUX), you can copy this file:

cp Makefile.LINUX Makefile

In this Makefile, you specify the source file to compile in the line beginning with LSTBIN. The name of the executable is located in the line beginning with BIN. Here, the executable is written in the file test/test.x and after compilation the file is automatically moved (through command mv) to the main directory of Seldon. This trick is used to force the compilation even if the source file has not been modified (but another source file of Seldon). In the first part of the Makefile, you inform which external libraries you want to use (e.g. Blas/Lapack, Mumps, Pardiso, Pastix, Arpack, Feast, Anasazi, Cholmod). In the variables CHE_ARPACK, CHEMUMPS_SEQ, CHE_SCOTCH, you specify the folder where each library has been installed. The variable EXTERNAL is usually a folder that contains all external libraries. In the section beginning with

ifeq($(USE_BLAS),YES)

you have to specify how you want to link Blas, the most efficient option is usually to link with MKL library.

In the Makefile, you have at the beginning the line:

OPTIMIZATION := YES

It means that your code will be compiled in optimization mode (with SELDON_DEBUG_LEVEL_1, such that a few checks are performed) with the option -O3. If you have a segmentation fault, or if you want to check that your function is safe, you can set:

OPTIMIZATION := NO

In this case, the code will be compiled in debug mode (with SELDON_DEBUG_LEVEL 4 that induces a lot of checks) with the option -g. As a result, the execution will be particularly slow. For these two modes of compilation (YES or NO), all the files of Seldon are included (.cxx files as well), such that the compilation time can be very large because it will recompile all the functions you need. If you change only a line of your source file, all the functions needed will be recompiled each time you type make. If you want to produce a compiled library of Seldon such that only functions that are modified are recompiled, you can select the following mode: 

OPTIMIZATION := FAST

A library with Seldon functions will be generated in the folder lib (such as libseldon_Sopt.a) in optimized mode. If STATIC_COMPILATION has been set to YES, a static library is generated. If you set STATIC_COMPILATION to NO in the makefile, a dynamic library is generated (libseldon_Sopt.so). In that case, you will need to update the variable LD_LIBRARY_PATH such that he finds where the library is. If FAST has been selected, only header files are included (.cxx are not included), each .cxx file is compiled (by instantiation of templates) to produce object files (in the folder lib/Compil/Seldon). You can accelerate the compilation by typing:

make -j8

In that case, if your machine has 8 cores, it will compile eight .cpp files at the same time efficiently. This mode of compilation is tricky because it can generate undefined references if you instantiate a class or a function for a set of template parameters not planned. In case of undefined references, you can add the new instantiation in one of cpp files contained in the folder lib/Compil/Seldon. A last mode of compilation is:

OPTIMIZATION := TEST

In that case, the compilation of all cpp files and the main source file is performed in debug mode (with flag SELDON_DEBUG_LEVEL_4 and option -g), leading to a slow execution.