SG++
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
OSX (GCC/ICC)

This page contains instructions for compiling and using SG++ with GCC or ICC under Mac OSX.

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

Overview

Dependencies

Required

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

  • GCC (≥ 4.8)
  • SCons (≥ 2.3) is required for building (build system). SCons is written in Python 2.7, which is therefore needed by SG++ as well.

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

For some of the above applications, binaries for Mac OSX are available. Most packages would need to be installed by hand. To simplify this, package management is recomended. We will relly on the commonly used on Homebrew for package management in the following .

In order for things to work propperly, you should keep to the order proposed below:

  • Install the Java JDK from the Oracle webpage
  • python 2.7 is already part of Mac OSX
  • Install GCC brew install gcc
  • SCons: brew install scons
  • SWIG: brew install swig
  • Doxygen: brew install doxygen –with-graphviz
  • Dot: brew install graphviz
  • NumPy: use the python package manager PIP pip install numpy
  • Boost: Here comes the tricky part. In order for boost to be compatible with C++11 headers, we have to compile the Boost package using GCC. First export HOMEBREW_CC=gcc-5 and export HOMEBREW_CXX=g++-5 (may differ from which version your GCC actually is), then install boost using brew install boost –c++11
  • Add export JAVA_HOME="$(/usr/libexec/java_home -v 1.8)" in your ~/.bash_profile. Note that the version has to correspond to an installed version.

Compilation with SCons

Apple has installed a prehistoric version of GCC on your Mac. But it is there and it will cause you trouble, because scons thinks this is the GCC you want to use. You need to tell it the correct paths. Do so by appending

CC=/usr/local/bin/gcc-5 CC=/usr/local/bin/g++-5 

to EVERY SINGLE CALL of scons (again name of the executable may be different for newer versions). Do this even when calling the help function. Else scons will complain it can't find any c++11 compilers. 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 DYLD_FALLBACK_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 (with CC and CXX specified as above) , the default compilation with GCC for SSE3 instruction set is selected. The compiler can be changed using 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).

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 DYLD_FALLBACK_LIBRARY_PATH ="/PATH_TO_SGPP/lib/sgpp:$DYLD_FALLBACK_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 DYLD_FALLBACK_LIBRARY_PATH environment variable in any case:

export DYLD_FALLBACK_LIBRARY_PATH ="/PATH_TO_SGPP/lib/sgpp:$DYLD_FALLBACK_LIBRARY_PATH "
python tutorial.py

Misc

Other options as specified in the linux tutorial may work in Mac OSX but have not been tested so far. Share your success stories and issues with us to make this documentation more complete.