StarNEig Library  version v0.1-beta.1
A task-based library for solving nonsymmetric eigenvalue problems
Installation

Documentation

The user manual can be generated independently from the rest of the library.

Documentation dependencies:

  • CMake 3.3 or newer
  • Doxygen
  • Latex + pdflatex

It is recommended that a user builds the documentation in a separate build directory:

$ cd path_to_the_root_directory/
$ mkdir build_doc
$ cd build_doc/
$ cmake ../doc/
$ make

The PDF documentation is copied to build_doc/starneig_manual.pdf. The HTML documentation is available at build_doc/html directory.

Dependencies

Library dependencies:

  • Linux (not tested in Window or Mac OS X)
  • CMake 3.3 or newer
  • Portable Hardware Locality (hwloc)
  • Starpu 1.2 or 1.3 (newer versions require minor changes to src/CMakeLists.txt; SUPPORTED_STARPU)
  • BLAS (preferably a multi-threaded variant that has an option to change the thread count)
  • LAPACK
  • MPI (optional)
  • CUDA (optional)
  • ScaLAPACK (optional)

Test program and example code dependencies:

  • pkg-config
  • GNU Scientific Library (optional)
  • MAGMA (optional)

StarPU 1.2.8 installation

  1. Download StarPU 1.2.8 (or newer) from http://starpu.gforge.inria.fr/files/
  2. Unzip the package and create/enter directory starpu-1.2.8/build
  3. Configure: $ ../configure
  4. Compile: $ make
  5. Install: $ sudo make install

The default installation path is /usr/local but this can be changed during the configuration phase ($ ../configure --prefix=...). It is something necessary to append the CPATH, LIBRARY_PATH, and LD_LIBRARY_PATH environmental variables by adding the following to ~/.profile:

export CPATH=$CPATH:/usr/local/include/
export LIBRARY_PATH=$LIBRARY_PATH:/usr/local/lib/
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib/

See the StarPU handbook for further instructions: http://starpu.gforge.inria.fr/doc/html/BuildingAndInstallingStarPU.html

Configuration

It is recommended that a user builds the library in a separate build directory:

$ cd path_to_the_root_directory/
$ mkdir build
$ cd build

The library is configured with the cmake command. In most cases, it is not necessary to give this command any additional arguments:

$ cmake ../
...
-- Configuring done
-- Generating done
-- Build files have been written to: /.../build

However, the library can be customized with various options. For example, the example codes and documentation generation can be enabled by setting the STARNEIG_ENABLE_EXAMPLES and STARNEIG_ENABLE_DOCS options:

$ cmake -DSTARNEIG_ENABLE_EXAMPLES=ON -DSTARNEIG_ENABLE_DOCS=ON ../

The installation path can be changed during the configuration phase:

$ cmake -DCMAKE_INSTALL_PREFIX=/path/to/somewhere/ ../
Remarks
It may sometimes be necessary to compile CUDA source files with a different compiler than what cmake uses by default. For example, some CUDA version do not support GCC compilers that are newer than GCC 5 release series. In that case cmake can be configured to use GCC 5:
$ cmake -DCUDA_HOST_COMPILER=/usr/bin/gcc-5 -DCUDA_PROPAGATE_HOST_FLAGS=OFF ../

List of StarNEig library specific configuration options:

  • STARNEIG_ENABLE_OPTIMIZATION: Enables compiler optimizations (ON by default).
  • STARNEIG_ENABLE_EXAMPLES: Enables examples (OFF by default).
  • STARNEIG_ENABLE_DOCS: Enables documentation generation (OFF by default).
  • STARNEIG_ENABLE_TESTS: : Enables test program (ON by default).
  • STARNEIG_ENABLE_FULL_TESTS: Enables additional tests (OFF by default).
  • STARNEIG_ENABLE_REFERENCE: : Enables reference MPI implementations (OFF by default).
  • STARNEIG_DISABLE_MPI: Explicitly disables the MPI support even when the system would support it (OFF by default).
  • STARNEIG_DISABLE_CUDA: Explicitly disables the CUDA support even when the system would support it (OFF by default).
  • STARNEIG_DISABLE_BLACS: Explicitly disables the ScaLAPACK/BLACS support even when the system would support it (OFF by default).
  • STARNEIG_ENABLE_MESSAGES: Enable basic verbose messages (ON by default).
  • STARNEIG_ENABLE_VERBOSE: Enable additional verbose messages (OFF by default).
  • STARNEIG_ENABLE_SANITY_CHECKS: Enables additional satiny checks. These checks are very expensive and should not be enabled unless absolutely necessary (OFF by default).
  • STARNEIG_ENABLE_PRUNING: Enable task graph pruning (ON by default).
  • STARNEIG_ENABLE_MRM: Enable multiple linear regression performance models (OFF by default).
  • STARNEIG_ENABLE_CUDA_REORDER_WINDOW: Enable CUDA-based reorder_window codelet (OFF by default).
  • STARNEIG_ENABLE_AED_PARALLEL_HESSENBERG: Enable parallel Hessenberg reduction during AED (OFF by default).
  • STARNEIG_ENABLE_INTEGER_SCALING: Enable integer-based scaling factors (ON by default).

The following environmental variables can be used to configure the used libraries:

  • BLAS_LIBRARIES: BLAS library.
  • LAPACK_LIBRARIES: LAPACK library.
  • HWLOC_LIBRARIES: Portable Hardware Locality (hwloc) library.
  • MPI_LIBRARIES: C MPI library.
  • MPI_Fortran_LIBRARIES: Fortran MPI library.
  • SCALAPACK_LIBRARIES: ScaLAPACK library.
  • BLACS_LIBRARIES: BLACS library.
  • STARPU_LIBRARIES_BASE: StarPU library.
  • STARPU_LIBRARIES_MPI: StarPU-MPI library.
  • GSL_LIBRARIES: GNU Scientific Library.
  • MAGMA_LIBRARIES: MAGMA library.
  • MISC_LIBRARIES: Miscellaneous libraries.

For example, if a user has a custom build ATLAS BLAS library and a matching LAPACK library that are not detected by the build system, then the user might define BLAS_LIBRARIES=/usr/local/atlas/lib/libsatlas.so and LAPACK_LIBRARIES=/usr/local/atlas/lib/liblapack.so before calling cmake.

The following environmental variables can be used to configure include paths for the used libraries:

  • OMP_INCLUDE_PATH: OpenMP include path.
  • BLAS_INCLUDE_PATH: BLAS include path.
  • MKL_INCLUDE_PATH: MKL include path.
  • HWLOC_INCLUDE_PATH: Portable Hardware Locality (hwloc) include path.
  • MPI_INCLUDE_PATH: MPI include path.
  • STARPU_INCLUDE_PATH: StarPU include path.
  • GSL_INCLUDE_PATH: GNU Scientific Library include path.
  • MAGMA_INCLUDE_PATH: MAGMA include path.
  • MISC_INCLUDE_PATH: Miscellaneous include paths.

Compile

The library (and other components) are compiled with the make command:

$ make
Scanning dependencies of target starneig
[ 1%] Building C object src/CMakeFiles/starneig.dir/common/combined.c.o
[ 2%] Building C object src/CMakeFiles/starneig.dir/common/common.c.o
...

Test

The automated tests can be executed as follows:

$ make test
Running tests...
Test project /.../build
Start 1: simple-hessenberg
1/18 Test #1: simple-hessenberg ................... Passed 15.19 sec
Start 2: simple-hessenberg-mpi
2/18 Test #2: simple-hessenberg-mpi ............... Passed 49.59 sec
...
Start 17: simple-full-chain-generalized
17/18 Test #17: simple-full-chain-generalized ....... Passed 180.50 sec
Start 18: simple-full-chain-generalized-mpi
18/18 Test #18: simple-full-chain-generalized-mpi ... Passed 195.39 sec
100% tests passed, 0 tests failed out of 18
Total Test time (real) = 1219.47 sec

Some eigenvalue reordering related tests may randomly fail. This is more common with the generalized eigenvalue reordering problem. In all observed cases, these failures were related to ill-conditioned problems and/or a too tight failure threshold (i.e., they were false positives). The STARNEIG_ENABLE_FULL_TESTS cmake option can be used to enable additional tests.

Install

The library and the related header files are installed by executing:

$ sudo make install

This also installs starneig.pc configuration file.