SG++
Linux (GCC/Clang/ICC)

This page contains instructions for compiling and using SG++ with GCC, Clang or ICC under Linux.

For brevity, we assume you want to compile with GCC; the compiler can be changed easily, however.

# Dependencies

## Required

The following software is required in order to build SG++:

## Recommended

The following software is recommended for core functionality:

• Boost.Test for compiling and running the unit tests. You can also skip the unit tests, but this is not recommended.
• SWIG (≥ 3.0), if you want to use SG++ within Python, Java, or MATLAB. SWIG creates bindings from C/C++ functions in order to make them available as a Python module or prepare them to be called from Java code.
• Python development headers are needed, if you want to compile the Python bindings.
• NumPy for Python 2.7 is needed, if you want to run the Python tests/examples.
• Java Development Kit (JDK), if you want to compile the Java bindings.
• Doxygen is required to create and compile the documentation, which you are reading right now. It is also required to automatically annotate the Python bindings generated by SWIG with docstrings.

## Optional

The following software can be installed for full functionality:

## Installation

On a recent Ubuntu system (≥ 14.04 LTS), you can install most dependencies by installing the following packages:

• GCC: g++
• Clang: clang on Ubuntu ≥ 16.04. On the LLVM download page, there are binaries for many other systems, including older Ubuntu versions.
• SCons: scons
• Boost.Test: libboost-test-dev
• SWIG: swig3.0 on Ubuntu ≥ 14.10. For Ubuntu 14.04 LTS, download the SWIG 3.0 .deb file here.
• Python development headers: libpython-dev
• NumPy: python-numpy
• Java: openjdk-7-jdk or openjdk-8-jdk on Ubuntu ≥ 15.10
• Doxygen: doxygen
• Dot: graphviz
• GSL: libgsl-dev

# Compilation with SCons

Compilation of the C++ libraries is done with SCons. Execute

scons -j <number of cores>


in the main folder to compile SG++ with GCC. For configuration (including other compilers) and optimization, see below.

If SCons does not seem to find external dependencies even if they are installed, you might want to clear the SCons cache before trying again:

rm -r .sconf_temp .sconsign.dblite


To obtain help on parameters for compilation, type

scons --help


After compilation, all unit-tests (located in the tests-folder of each module) are executed, if Boost.Test is installed. There are also some tests written in Python, but the majority is written with Boost.Test.

When the build is finished, the shared libraries are installed in lib/sgpp. If you use it, add this directory to your LD_LIBRARY_PATH. Instructions are also displayed at the end of the build.

## Configuration

SCons uses the file SConstruct. This file contains all information for compiling SGpp. If you just execute scons, the default compilation with GCC for SSE3 instruction set is selected. The compiler can be changed using COMPILER=clang or COMPILER=intel, e.g. To use other instruction sets, use ARCH=avx, etc.

You are able to compile different SG++ modules independently. However, you should take into account the dependencies between the modules to avoid "undefined symbol" errors: When using them, depending on the dependencies, other modules might have to be included, too. The currently available modules are (see the Modules page):

• SG_BASE: basic functionality
• SG_DATADRIVEN: operations on data
• SG_SOLVER: classes for solving the systems of equations
• SG_PDE: partial differential equations
• SG_FINANCE: financial module
• SG_PARALLEL: classes for parallel computing
• SG_COMBIGRID: combigrid classes
• SG_OPTIMIZATION: optimization of objective functions

Also, there are two switches for supported high-level back-ends:

• SG_PYTHON: Python bindings
• SG_JAVA: Java bindings

For example, the command

scons SG_OPTIMIZATION=0


will compile all modules except optimization.

Additionally, you can pass some specific flags to the compiler using the CPPFLAGS environment variable:

scons CPPFLAGS='-g -O0'


## Python Bindings

The Python bindings are important, because some unit tests are written in Python. By default, the Python bindings are built, too. If not, then some prerequisites are missing (see Dependencies).

By default, the Python bindings will be annotated with Python docstrings, if Doxygen is installed. Disabling this feature, which is recommended if you have to recompile the whole codebase frequently, is done by setting PYDOC=0 in the SCons command line.

When the build is finished, the Python bindings are installed in lib/pysgpp. If you use them, add the lib directory to your PYTHONPATH. Alternatively, you can install the bindings into your local site-packages directory:

python setup.py install --user


Instructions are also displayed at the end of the build.

In Python, you can import the library and print its contents via

1 import pysgpp
2 dir(pysgpp)

## Java Bindings

By default, the Java bindings are built, too. If not, then the JDK is missing (see Dependencies).

## Eclipse and SCons

Create a Makefile project and change the project properties as follows:

• PropertiesC/C++ BuildBuilder Settings: Disable Use default build command and set Build command to scons.
• PropertiesC/C++ BuildBehaviour: Set Build (Incremental build) to, e.g., -j 2 and Clean to -c.

# Using SG++

In this section, we show how SG++ can be used as a library in other programs. For C++, this includes compilation, linking, and execution of the program using SG++. We also show how to use SG++ from the other supported languages (Python, Java, and MATLAB). As an example application, we consider the tutorial.cpp (Start Here) from the directory base/examples; however, the instructions can be analogously applied to other programs.

Note that all examples, including tutorial.cpp (Start Here), are automatically built after each SCons run. Therefore, the following steps are not necessary to compile the examples; rather, the intent is to show the steps to build an application using SG++.

In the following, the current directory is always base/examples and /PATH_TO_SGPP refers to the absolute path of the SG++ directory. We assume that SG++ or its bindings have been successfully built before.

## C++

First, compile the program while supplying the include paths of the relevant modules:

g++ tutorial.cpp \
-c -std=c++11 -fopenmp \
-I/PATH_TO_SGPP/base/src \
-o tutorial.o


Then, link the program by indicating the SG++ library path and the modules you want to link against:

g++ tutorial.o \
-fopenmp \
-L/PATH_TO_SGPP/lib/sgpp \
-lsgppbase \
-o tutorial


To run the program, note that you have to set the LD_LIBRARY_PATH environment variable to include the SG++ library path:

export LD_LIBRARY_PATH="/PATH_TO_SGPP/lib/sgpp:$LD_LIBRARY_PATH" ./tutorial  ## Python The Python bindings pysgpp can be used either by setting the PYTHONPATH environment variable to include the lib directory, i.e. export PYTHONPATH="/PATH_TO_SGPP/lib:$PYTHONPATH"


or by installing pysgpp in the local site-packages folder:

python setup.py install --user


To run your Python program, don't forget to update the LD_LIBRARY_PATH environment variable in any case:

export LD_LIBRARY_PATH="/PATH_TO_SGPP/lib/sgpp:$LD_LIBRARY_PATH" python tutorial.py  ## Java Java programs using the Java bindings jsgpp have to be compiled in this way: javac -cp .:/PATH_TO_SGPP/lib/jsgpp/jsgpp.jar tutorial.java  When running Java programs, you have to augment LD_LIBRARY_PATH not only by the SG++ library path, but also by a path specific for jsgpp: export LD_LIBRARY_PATH="/PATH_TO_SGPP/lib/sgpp:/PATH_TO_SGPP/lib/jsgpp:$LD_LIBRARY_PATH"
java -cp .:/PATH_TO_SGPP/lib/jsgpp/jsgpp.jar tutorial


## MATLAB

MATLAB can use SG++ in three ways.

### Via Binaries

The recommended way is to download the binaries for use with MATLAB that are listed at Downloads and Version History. For instructions, please see the MATLAB binaries page.

### Via MEX Interface

If the binaries don't work for you, then it is possible to write and compile a MEX interface yourself (similar to the interface that the binaries would provide). This means that you have to write a C++ program interacting with SG++ directly in C++ and converting input and output arguments from and to MATLAB's data structures. The parameters to be passed to MATLAB's mex function which compiles the program are largely the same as for plain C++. Alternatively, you can link and compile by yourself:

g++ your_mex_program.cpp \
-c -std=c++11 -fopenmp -fPIC \
-Wall -Wextra \
-I/PATH_TO_MATLAB/extern/include \
-I/PATH_TO_SGPP/base/src \
-o your_mex_program.o
g++ your_mex_program.o \
-shared -fopenmp \
-L/PATH_TO_MATLAB/bin/glnxa64 \
-L/PATH_TO_SGPP/lib/sgpp \
-lmex \
-lsgppbase \
-o your_mex_program.mexa64


Of course, you have to add include paths and library switches for each module that your_mex_program uses.

### Via jsgpp

The third way of using SG++ from within MATLAB is jsgpp, i.e., using the Java library of SG++ and import it to MATLAB. Before we can use these methods in MATLAB, we have to add /PATH_TO_SGPP/lib/jsgpp to the librarypath.txt file of MATLAB. (Hint: Typing matlabroot in MATLAB returns the path of your MATLAB installation.) Open the file /PATH_TO_MATLAB/toolbox/local/librarypath.txt in a text editor and add the line

/PATH_TO_SGPP/lib/jsgpp


at the end of the file.

Now we can start MATLAB. However, we have to set the environment variables LD_LIBRARY_PATH and LD_PRELOAD before:

export LD_LIBRARY_PATH="/PATH_TO_SGPP/lib/sgpp:/PATH_TO_SGPP/lib/jsgpp:$LD_LIBRARY_PATH" export LD_PRELOAD="/usr/lib/x86_64-linux-gnu/libstdc++.so.6:$LD_PRELOAD"
matlab


The variable LD_LIBRARY_PATH has to be set to allow MATLAB to find the shared libraries (see above). However, this does not suffice: MATLAB ships its own version of libstdc++ (usually in /PATH_TO_MATLAB/sys/os/glnxa64) and prepends its location to MATLAB's internal LD_LIBRARY_PATH. Since this version of libstdc++ is most likely incompatible with the version used to compile SG++, you will get errors like this when executing SG++ programs in MATLAB:

Error using tutorial (line 5)
Java exception occurred:
PATH_TO_MATLAB/bin/glnxa64/libstdc++.so.6: version


To work around this issue, set the LD_PRELOAD variable to load the correct version libstdc++ before calling MATLAB. You can find the correct version by examining the output of

ldd /PATH_TO_SGPP/lib/jsgpp/libjsgpp.so


and searching for a line containing libstdc++. On 64-bit Ubuntu systems, it can be located in /usr/lib/x86_64-linux-gnu/libstdc++.so.6, but it can differ on other systems.

When starting MATLAB, make sure that the Java version of MATLAB's internal Java Runtime Environment (check with version -java in MATLAB) is newer than that of the Java you built jsgpp with (check with java -version in a terminal). Sometimes, you have to force MATLAB to use your installed JDK by using the MATLAB_JAVA environment variable:

export MATLAB_JAVA="/PATH_TO_JDK/jre"


(e.g., MATLAB_JAVA="/usr/lib/jvm/java-7-openjdk-amd64/jre"). You can get errors like this otherwise:

Undefined variable "sgpp" or class "sgpp.LoadJSGPPLib.loadJSGPPLib".


Keep in mind that, however, MATLAB seems not to be compatible with Java 8 yet.

After starting MATLAB, we have to add the jsgpp.jar file to MATLAB's class path with the command

javaaddpath('/PATH_TO_SGPP/lib/jsgpp/jsgpp.jar');


sgpp.LoadJSGPPLib.loadJSGPPLib();


You should now be able to use SG++ in MATLAB.

For an example, look at base/examples/tutorial.m. However, note that the example was written for the MATLAB SG++ binaries explained above. Therefore, you likely have to change some calls especially to static methods like sgpp.createOperationEval, which are now located at sgpp.jsgpp.*.

### Hints

• Use
javaclasspath();
to see the loaded jar files (upper part static, lower part dynamic; our jsgpp.jar should be in the latter part).
• Write
import sgpp.*
in MATLAB to not have to write sgpp. in front of every method.
• Call
methods('sgpp.Classname')
to see all methods of the class "Classname" (e.g. Grid).
• The methods itself can also be called like Java methods in the MATLAB command window, e.g.:
dataVector = sgpp.DataVector(10)
dataVector.setAll(0)
dataVector`