Galois: C++ library for multi-core and multi-node parallelization
Switch branches/tags
Nothing to show
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Use base/archlinux instead of archlinux/base. The out of date docker Aug 30, 2018
cmake FindPAPI cmake works on TACC stampede2 Jul 2, 2018
dist_apps bc_level: force neverOnlyData metadata mode Nov 15, 2018
docs doxygen namespaces (remove old, add new) Jul 3, 2018
inputs inputs don't download by default and fixed the "re-extracting of tar … Jun 26, 2018
libdist disabling network destructor (it causes non-deterministic hangs) Oct 29, 2018
libgalois very minor spacing change in Statistics Oct 25, 2018
libgpu Ran clang-format. Jun 18, 2018
liblci @ ec124ae Adding public LCI repo Jun 9, 2018
libllvm Give vendored LLVM headers precedence over ones found installed Jul 24, 2018
lonestar STA: now indentify clock_gate_clock_pin as clock pin Nov 15, 2018
scripts changing galois log parser for stats format Sep 9, 2018
test Give vendored LLVM headers precedence over ones found installed Jul 24, 2018
tools Specifically link Boost iostreams library in graph-convert. Jul 24, 2018
.clang-format Change clang-format config to not sort includes. Jun 18, 2018
.gitignore gitignore ignores files that start with . Jun 11, 2018
.gitmodules Adding public LCI repo Jun 9, 2018
.travis.yml Change source for CMake to avoid now unsupported package repository. Aug 30, 2018
CMakeLists.txt Link boost libs found by cmake rather than relying exlusively on having Jul 20, 2018
COPYRIGHT update COPYRIGHT Jun 20, 2018
Doxyfile.in got rid of deprecated list in doxygen Jun 18, 2018
LICENSE.txt license added to LICENSE.txt, remove old license Jun 19, 2018
README.md Added status indicator badges to main Galois README. Jul 24, 2018

README.md

Overview

CircleCI Build Status

Galois is a C++ library designed to ease parallel programming, especially for applications with irregular parallelism (e.g., irregular amount of work in parallel sections, irregular memory accesses and branching patterns). It implements an implicitly parallel programming model, where the programmer replaces serial loop constructs (e.g. for and while) and serial data structures in their algorithms with parallel loop constructs and concurrent data structures provided by Galois to express their algorithms. Galois is designed so that the programmer does not have to deal with low-level parallel programming constructs such as threads, locks, barriers, condition variables, etc.

Highlights include:

  • Parallel for_each loop that handles dependencies between iterations, as well as dynamic work creation, and a do_all loop for simple parallelism. Both provide load balancing and excellent scalability on multi-socket systems
  • A concurrent graph library designed for graph analytics algorithms as well as other domains such as irregular meshes.
  • Scalable concurrent containers such as bag, vector, list, etc.

Galois is released under the BSD-3-Clause license.

Building Galois

You can checkout the latest release by typing (in a terminal):

git clone -b release-4.0 https://github.com/IntelligentSoftwareSystems/Galois

The master branch will be regularly updated, so you may try out the latest development code as well by checking out master branch:

git clone https://github.com/IntelligentSoftwareSystems/Galois

Dependencies

Galois builds, runs, and has been tested on GNU/Linux. Even though Galois may build on systems similar to Linux, we have not tested correctness or performance, so please beware.

At the minimum, Galois depends on the following software:

  • A modern C++ compiler compliant with the C++-14 standard (GCC >= 6.1, Intel >= 17.0, LLVM >= 4.0)
  • CMake (>= 3.2.3)
  • Boost library ( >= 1.58.0, we recommend building/installing the full library)

Here are the dependencies for the optional features:

  • Linux HUGE_PAGES support (please see www.kernel.org/doc/Documentation/vm/hugetlbpage.txt). Performance will most likely degrade without HUGE_PAGES enabled. Galois uses 2MB huge page size and relies on the kernel configuration to set aside a large amount of 2MB pages. For example, our performance testing machine (4x14 cores, 192GB RAM) is configured to support up to 65536 2MB pages:

    cat /proc/mem_info | fgrep Huge
    AnonHugePages:    104448 kB
    HugePages_Total:   65536
    HugePages_Free:    65536
    HugePages_Rsvd:        0
    HugePages_Surp:        0
    Hugepagesize:       2048 kB
  • libnuma support. Performance may degrade without it. Please install libnuma-dev on Debian like systems, and numactl-dev on Red Hat like systems.

  • Doxygen (>= 1.8.5) for compiling documentation as webpages or latex files

  • PAPI (>= 5.2.0.0 ) for profiling sections of code

  • Vtune (>= 2017 ) for profiling sections of code

  • MPICH2 (>= 3.2) if you are interested in building and running distributed system applications in Galois

  • CUDA (>= 8.0) if you want to build distributed hetergeneous applications

  • Eigen (3.3.1 works for us) for some matrix-completion app variants

Compiling Galois

We use CMake. Let's assume that SRC_DIR is the directory where the source code for Galois resides, and you wish to build galois in some BUILD_DIR. Run the following commands to set up a build directory:

SRC_DIR=`pwd` # Or top-level Galois source dir
BUILD_DIR=<path-to-your-build-dir>
mkdir -p $BUILD_DIR; cd $BUILD_DIR; cmake $SRC_DIR

By default, cmake sets up a "Release" build. You can also set up a "Debug" build, as follows:

mkdir -p $BUILD_DIR; cd $BUILD_DIR; cmake -DCMAKE_BUILD_TYPE=Debug $SRC_DIR

Galois applications are in lonestar directory. In order to build a particular application:

cd $BUILD_DIR/lonestar/<app-dir-name>; make -j

You can also build everything by running make -j in the top-level of build directory, but that may take a lot of time and will download additional files.

More esoteric systems may require a toolchain file; check ../cmake/Toolchain if there is a file corresponding to your system. If so, use the following CMake command:

cmake -C ${SRC_DIR}/cmake/Toolchain/${platform}-tryrunresults.cmake \
  -DCMAKE_TOOLCHAIN_FILE=${SRC_DIR}/cmake/Toolchain/${platform}.cmake ${SRC_DIR}

Running Galois Applications

Inputs

We provide a few sample inputs that can be downloaded by running:

make input

'make input' will download a big (~2GB) tar-ball of inputs and extract it to $BUILD_DIR/inputs/reference directory. The tar-ball is downloaded to $BUILD_DIR/inputs

Many Galois/Lonestar applications work with graphs. We store graphs in a binary format called galois graph file (.gr file extension). Other formats such as edge-list or Matrix-Market can be converted to .gr format with graph-convert tool provided in galois. You can build graph-convert as follows:

cd $BUILD_DIR
make graph-convert
./tools/graph-convert --help

Other applications, such as Delaunay Mesh Refinement may read special file formats or some may even generate random inputs on the fly.

Running

All Lonestar applications take a -t command-line option to specify the number of threads to use. All applications run a basic sanity check (often insufficient for correctness) on the program output, which can be turned off with the -noverify option. You can specify -help command-line option to print all available options.

Upon successful completion, each application will produce some stats regarding running time of various sections, parallel loop iterations and memory usage, etc. These stats are in CSV format and can be redirected to a file using -statFile option. Please refer to the manual for details on stats.

Running Distributed Galois

Please refer to dist_apps/README.md for more details on running distributed benchmarks.

Documentation

Galois documentation is produced using doxygen, included in this repository, which includes a tutorial, a user's manual and API documentation for the Galois library.

Users can build doxygen documentation in the build directory using:

cd $BUILD_DIR
make doc
your-fav-browser html/index.html &

See online documentation at: http://iss.ices.utexas.edu/?p=projects/galois

Source-Tree Organization

  • libgalois contains the source code for the shared-memory Galois library, e.g., runtime, graphs, worklists, etc.
  • lonestar contains the Lonestar benchmark applications and tutorial examples for Galois
  • libdist contains the source code for the distributed-memory and heterogeneous Galois library
  • dist_apps contains the source code for the distributed-memory and heterogeneous benchmark applications. Please refer to dist_apps/README.md for instructions on building and running these apps.
  • tools contains various helper programs such as graph-converter to convert between graph file formats and graph-stats to print graph properties

Installing Galois as a library

If you want to install Galois as a library. Assuming that you wish to install Galois under INSTALL_DIR:

cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_DIR} ${SRC_DIR}
make install

or, to speed up compilation,

cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_DIR} -DSKIP_COMPILE_APPS=1 ${SRC_DIR}
make install

Using Installed Galois

If you are using CMake, put something like the following CMakeLists.txt:

set(CMAKE_PREFIX_PATH ${INSTALL_DIR}/lib/cmake/Galois ${CMAKE_PREFIX_PATH})
find_package(Galois REQUIRED)
include_directories(${Galois_INCLUDE_DIRS})
set(CMAKE_CXX_COMPILER ${Galois_CXX_COMPILER})
set(CMAKE_CXX_FLAGS  "${Galois_CXX_FLAGS} ${CMAKE_CXX_FLAGS}")
add_executable(app ...)
target_link_libraries(app ${Galois_LIBRARIES})

Using basic commands (although the specific commands vary by system):

c++ -std=c++14 app.cpp -I${INSTALL_DIR}/include -L${INSTALL_DIR}/lib -lgalois_shmem

Contact Us

For bugs, please raise an issue here at gihub using the 'Issues' tab https://github.com/IntelligentSoftwareSystems/Galois/issues. Please send questions and comments to Galois users mailing list: galois-users@utlists.utexas.edu. You may subscribe at https://utlists.utexas.edu/sympa/subscribe/galois-users.

If you find a bug, it would help us if you sent (1) the command and program output and (2) a gdb backtrace, preferably with the debug build. Assuming you will build Galois in BUILD_DIR, while the source is in SRC_DIR:

script Galois-errors-log.txt
mkdir -p $BUILD_DIR
cd $BUILD_DIR
cmake -DCMAKE_BUILD_TYPE=Debug $SRC_DIR
make VERBOSE=1
gdb --args path/to/failing/program args
(gdb) r
(gdb) bt
(gdb) q
exit

This will generate a file Galois-errors-log.txt, which you can send to the mailing list:galois-users@utlists.utexas.edu for further debugging or open a github issue.