Integrated Singular Value Decomposition (iSVD)

Information

This library is a C implementation of the Integrated Singular Value Decomposition (iSVD), which is an parallel algorithm for computing low-rank approximate singular value decomposition of large size matrices.

Git

• https://github.com/emfomy/isvd

Documentation

• Download isvd-#.#.#-docs.zip from https://github.com/emfomy/isvd/releases/latest
• May also build it using make doc (see below) on your own computer.

Author

• Mu Yang <emfomy@gmail.com>

Tutorial

• \ref tutorial_main

Requirements

• CMake 2.8.11+ (CMake 3.0+ recommended).
• C/C++ compiler with C99/C++98 standard support (GCC 4.4+ recommended).
• BLAS & LAPACK library (Used for multi-core parallelization).
• MPI Library with 2.2+ standard support (MPICH 1.2+ or OpenMPI 1.7+).

Optional

• Intel® Math Kernel Library (Recommended for better performance, used for BLAS & LAPACK).
• MAGMA 2.0+ (Used for BLAS & LAPACK with GPU support).
• OpenMP Library (Recommended for better performance, used for multi-thread parallelization).
• Google Test Library (Used for code testing).
• Doxygen (Used for documentation).

Installation

Please use the following commands to create Makefiles

cd <isvd-source-folder>
mkdir build
cd build
cmake ..

Options

Use the following command to set options

ccmake ..

The following table are the main options

Makefile

The following table are the main Makefile rules

Test installation

• Set ISVD_BUILD_TEST using ccmake. (Also recommended to unset ISVD_TEST_VERBOSE if GPU is enabled).
• Run make check
  • Known issue: RealSingle_WenYinIntegration.Test.# / s_integrate_wenyin# fail the test.

Usage

• Define ISVD_USE_ILP64 before include isvd.h to use 64-bit integer.
• All 64bit libraries and executables are named with suffix _64.
• The header files are located in build/include
• The libraries are located in build/lib

Libraries

Please link exactly one library for all categories.

• Correct
  • gcc test.c -I<include-path> -L<library-path> -Wl,-rpath <library-path> -lisvd_core -lisvd_la_mkl_iomp -lisvd_gpu_magma
  • gcc test.c -I<include-path> -L<library-path> -Wl,-rpath <library-path> -lisvd_core -lisvd_la_blas -lisvd_gpu_none
• Wrong
  • gcc test.c -I<include-path> -L<library-path> -Wl,-rpath <library-path> -lisvd_core
  • (Some category of libraries are not linked)
  • gcc test.c -I<include-path> -L<library-path> -Wl,-rpath <library-path> -lisvd_core -lisvd_la_blas -lisvd_gpu_magma -lisvd_gpu_none
  • (Some category of libraries are linked multiple times)

Q&A

How to set CMake options?

• Use ccmake .. or ccmake <path-to-source> in the build folder.
• Press <Enter> on the option you want to change, change it, and press <Enter> again.
• After changing the options, press <c> to configure, and press <g> to generate Makefiles if configured successfully.
• To quit without saving, press <q>.

Why isn't Intel MKL found?

• Source mklvars.sh in the bin folder of your Intel MKL to set the environment variables.

Why isn't Google Test found?

• Set GTEST_ROOT to a folder containing include and lib of Google Test.

How to enable multithread support?

• Set ISVD_OMP with ccmake before building libraries.
• Make sure your LAPACK&BLAS / Intel MKL uses supports multithreading.

How to use 64-bit integer?

• Set ISVD_USE_ILP64 with ccmake before building libraries; or
• Add -DISVD_USE_ILP64 to compile flag.
• Make sure your LAPACK&BLAS / Intel MKL uses 64bit integer.

Error "make[2]: *** No rule to make target 'tmp/......" occurs. How to solve it?

• Use cmake . to and recompile again.
• Note that the tmp folder will be deleted after make clean.

Reference

• Ting-Li Chen, Dawei D. Chang, Su-Yun Huang, Hung Chen, Chienyao Lin, Weichung Wang, “Integrating Multiple Random Sketches for Singular Value Decomposition”
• Mu Yang, “Highly Scalable Parallelism of Integrated Randomized Singular Value Decomposition with Big Data Applications”

License {#Readme_License}

• MIT License \include LICENSE.md