{"id":13398796,"url":"https://github.com/IntelligentSoftwareSystems/Galois","last_synced_at":"2025-03-14T03:30:28.193Z","repository":{"id":43061728,"uuid":"137784875","full_name":"IntelligentSoftwareSystems/Galois","owner":"IntelligentSoftwareSystems","description":"Galois: C++ library for multi-core and multi-node parallelization","archived":false,"fork":false,"pushed_at":"2024-05-16T21:11:41.000Z","size":24945,"stargazers_count":309,"open_issues_count":61,"forks_count":129,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-07-31T19:17:01.468Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://iss.ices.utexas.edu/?p=projects/galois","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IntelligentSoftwareSystems.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-18T17:33:03.000Z","updated_at":"2024-07-24T15:05:10.000Z","dependencies_parsed_at":"2022-08-12T10:11:36.654Z","dependency_job_id":"8a12035c-f89c-4fc7-a4a8-29f00a5677aa","html_url":"https://github.com/IntelligentSoftwareSystems/Galois","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntelligentSoftwareSystems%2FGalois","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntelligentSoftwareSystems%2FGalois/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntelligentSoftwareSystems%2FGalois/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntelligentSoftwareSystems%2FGalois/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IntelligentSoftwareSystems","download_url":"https://codeload.github.com/IntelligentSoftwareSystems/Galois/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243520399,"owners_count":20304137,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T19:00:31.725Z","updated_at":"2025-03-14T03:30:27.510Z","avatar_url":"https://github.com/IntelligentSoftwareSystems.png","language":"C++","readme":"Overview\n========\n\n[![CircleCI](https://circleci.com/gh/IntelligentSoftwareSystems/Galois.svg?style=svg)](https://circleci.com/gh/IntelligentSoftwareSystems/Galois)\n[![Build Status](https://travis-ci.org/IntelligentSoftwareSystems/Galois.svg?branch=master)](https://travis-ci.org/IntelligentSoftwareSystems/Galois)\n\nGalois is a C++ library designed to ease parallel programming, especially for\napplications with irregular parallelism (e.g., irregular amount of work in parallel\nsections, irregular memory accesses and branching patterns). It implements\nan implicitly parallel programming model, where the programmer replaces serial loop\nconstructs (e.g. for and while) and serial data structures in their algorithms with parallel loop\nconstructs and concurrent data structures provided by Galois to express their algorithms.\nGalois is designed so that the programmer does not have to deal with low-level parallel programming constructs such as\nthreads, locks, barriers, condition variables, etc. \n\nHighlights include:\n- Parallel *for_each* loop that handles dependencies between iterations, as well as\n  dynamic work creation, and a *do_all* loop for simple parallelism. Both provide load balancing and excellent\n  scalability on multi-socket systems\n- A concurrent graph library designed for graph analytics algorithms as well as\n  other domains such as irregular meshes. \n- Scalable concurrent containers such as bag, vector, list, etc. \n\nGalois is released under the BSD-3-Clause license. \n\n\nBuilding Galois\n===============\n\nYou can checkout the latest release by typing (in a terminal):\n\n```Shell\ngit clone -b release-5.0 https://github.com/IntelligentSoftwareSystems/Galois\n```\n\nThe master branch will be regularly updated, so you may try out the latest\ndevelopment code as well by checking out master branch:\n\n```Shell\ngit clone https://github.com/IntelligentSoftwareSystems/Galois\n```\n\nDependencies\n------------\n\nGalois builds, runs, and has been tested on GNU/Linux. Even though\nGalois may build on systems similar to Linux, we have not tested correctness or performance, so please\nbeware. \n\nAt the minimum, Galois depends on the following software:\n\n- A modern C++ compiler compliant with the C++-17 standard (gcc \u003e= 7, Intel \u003e= 19.0.1, clang \u003e= 7.0)\n- CMake (\u003e= 3.13)\n- Boost library (\u003e= 1.58.0, we recommend building/installing the full library)\n- libllvm (\u003e= 7.0 with RTTI support)\n- libfmt (\u003e= 4.0)\n\nHere are the dependencies for the optional features: \n\n- Linux HUGE_PAGES support (please see [www.kernel.org/doc/Documentation/vm/hugetlbpage.txt](https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt)). Performance will most likely degrade without HUGE_PAGES\n  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:\n  ```Shell\n  cat /proc/meminfo | fgrep Huge\n  AnonHugePages:    104448 kB\n  HugePages_Total:   65536\n  HugePages_Free:    65536\n  HugePages_Rsvd:        0\n  HugePages_Surp:        0\n  Hugepagesize:       2048 kB\n  ```\n\n- libnuma support. Performance may degrade without it. Please install\n  libnuma-dev on Debian like systems, and numactl-dev on Red Hat like systems. \n- Doxygen (\u003e= 1.8.5) for compiling documentation as webpages or latex files \n- PAPI (\u003e= 5.2.0.0 ) for profiling sections of code\n- Vtune (\u003e= 2017 ) for profiling sections of code\n- MPICH2 (\u003e= 3.2) if you are interested in building and running distributed system\n  applications in Galois\n- CUDA (\u003e= 8.0 and \u003c 11.0) if you want to build GPU or distributed heterogeneous applications.\n  Note that versions \u003e= 11.0 use an incompatible CUB module and will fail to execute.\n- Eigen (3.3.1 works for us) for some matrix-completion app variants\n\n\nCompiling and Testing Galois\n----------------------------\nWe use CMake to streamline building, testing and installing Galois. In the\nfollowing, we will highlight some common commands.\n\nLet's assume that `SRC_DIR` is the directory where the source code for Galois\nresides, and you wish to build Galois in some `BUILD_DIR`. Run the following\ncommands to set up a build directory:\n\n```Shell\nSRC_DIR=`pwd` # Or top-level Galois source dir\nBUILD_DIR=\u003cpath-to-your-build-dir\u003e\n\nmkdir -p $BUILD_DIR\ncmake -S $SRC_DIR -B $BUILD_DIR -DCMAKE_BUILD_TYPE=Release\n```\n\nYou can also set up a `Debug` build by running the following instead of the last command above:\n\n```Shell\ncmake -S $SRC_DIR -B $BUILD_DIR -DCMAKE_BUILD_TYPE=Debug\n```\n\nGalois applications are in `lonestar` directory.  In order to build a particular application:\n\n```Shell\nmake -C $BUILD_DIR/lonestar/\u003capp-dir-name\u003e -j\n# or alternatively\nmake -C $BUILD_DIR \u003capp-executable-name\u003e -j\n# or\ncmake --build $BUILD_DIR \u003capp-executable-name\u003e --parallel\n```\n\nYou can also build everything by running `make -j` in the top-level of build directory, but that may\ntake a lot of time.\n\nSetting the `BUILD_SHARED_LIBS` to `ON` when calling CMake will make the core runtime library be built as a shared object instead of a static library.\n\nThe tests for the core runtime will be built by default when you run `make`\nwith no target specified. They can be also built explicitly with:\n\n```Shell\nmake -C $BUILD_DIR/test\n```\n\nWe provide a few sample inputs that can be downloaded by running:\n\n```Shell\nmake -C $BUILD_DIR input\n```\n\n`make input` will download a tarball of inputs and extract it to\n`$BUILD_DIR/inputs/small_inputs` directory. The tarball is downloaded to\n`$BUILD_DIR/inputs`\n\nMost of the Galois apps have corresponding tests.\nThese tests depend on downloading the reference inputs and building the corresponding apps and test binaries.\nOnce the reference inputs have been downloaded and everything has been built,\nthe tests for the core library and all the apps can be run by running:\n\n```Shell\nmake test\n# or alternatively\nctest\n```\n\nin the build directory.\n\n\nRunning Galois Applications\n===========================\n\nGraph Format\n------------\n\nMany Galois/Lonestar applications work with graphs. We store graphs in a binary format\ncalled *galois graph file* \n(`.gr` file extension). Other formats such as edge-list or Matrix-Market can be\nconverted to `.gr` format with `graph-convert` tool provided in galois. \nYou can build graph-convert as follows:\n\n```Shell\ncd $BUILD_DIR\nmake graph-convert\n./tools/graph-convert/graph-convert --help\n```\n\nOther applications, such as Delaunay Mesh Refinement may read special file formats\nor some may even generate random inputs on the fly. \n\nRunning\n-------\n\nAll Lonestar applications take a `-t` command-line option to specify the number of\nthreads to use. All applications run a basic sanity check (often insufficient for\ncorrectness) on the program output, which can be turned off with the `-noverify` option. You \ncan specify `-help` command-line option to print all available options. \n\nUpon successful completion, each application will produce some stats regarding running\ntime of various sections, parallel loop iterations and memory usage, etc. These\nstats are in CSV format and can be redirected to a file using `-statFile` option.\nPlease refer to the manual for details on stats. \n\nRunning LonestarGPU applications\n--------------------------\n\nPlease refer to `lonestar/analytics/gpu/README.md` and `lonestar/scientific/gpu/README.md` for more details on\ncompiling and running LonestarGPU applications.\n\nRunning Distributed Galois\n--------------------------\n\nPlease refer to `lonestar/analytics/distributed/README.md` for more details on\nrunning distributed benchmarks.\n\nDocumentation\n=============\n\nGalois documentation is produced using doxygen, included in this repository, which includes a tutorial, a user's\nmanual and API documentation for the Galois library. \n\nUsers can build doxygen documentation in the build directory using:\n\n```Shell\ncd $BUILD_DIR\nmake doc\nyour-fav-browser html/index.html \u0026\n```\n\nSee online documentation at:\n [http://iss.ices.utexas.edu/?p=projects/galois](http://iss.ices.utexas.edu/?p=projects/galois)\n\nSource-Tree Organization\n========================\n\n- `libgalois` contains the source code for the shared-memory Galois library, e.g., runtime, graphs, worklists, etc. \n- `lonestar` contains the Lonestar benchmark applications and tutorial examples for Galois\n- `libdist` contains the source code for the distributed-memory and heterogeneous Galois library\n- `lonestardist` contains the source code for the distributed-memory and heterogeneous\n  benchmark applications. Please refer to `lonestardist/README.md` for instructions on\n  building and running these apps. \n- `tools` contains various helper programs such as graph-converter to convert\n  between graph file formats and graph-stats to print graph properties\n\nUsing Galois as a library\n=========================\n\nThere are two common ways to use Galois as a library. One way is to copy this\nrepository into your own CMake project, typically using a git submodule. Then\nyou can put the following in your CMakeLists.txt:\n\n```CMake\nadd_subdirectory(galois EXCLUDE_FROM_ALL)\nadd_executable(app ...)\ntarget_link_libraries(app Galois::shmem)\n```\n\nThe other common method is to install Galois outside your project and import it\nas a package.\n\nIf you want to install Galois, assuming that you wish to install it under\n`INSTALL_DIR`:\n\n```Shell\ncmake -DCMAKE_INSTALL_PREFIX=$INSTALL_DIR $SRC_DIR\nmake install\n```\n\nThen, you can put something like the following in CMakeLists.txt:\n\n```CMake\nlist(APPEND CMAKE_PREFIX_PATH ${INSTALL_DIR})\nfind_package(Galois REQUIRED)\nadd_executable(app ...)\ntarget_link_libraries(app Galois::shmem)\n```\n\nIf you are not using CMake, the corresponding basic commands (although the\nspecific commands vary by system) are:\n\n```Shell\nc++ -std=c++14 app.cpp -I$INSTALL_DIR/include -L$INSTALL_DIR/lib -lgalois_shmem\n```\nThird-Party Libraries and Licensing\n====================\n\nGalois includes some third party libraries that do not use the same license as\nGalois. This includes the bliss library (located in lonestar/include/Mining/bliss)\nand Modern GPU (located in libgpu/moderngpu). Please be aware of this when\nusing Galois.\n\nContact Us\n==========\nFor bugs, please raise an\n[issue](https://github.com/IntelligentSoftwareSystems/Galois/issues) on\nGiHub.\nQuestions and comments are also welcome at the Galois users mailing list:\n[galois-users@utlists.utexas.edu](galois-users@utlists.utexas.edu). You may\n[subscribe here](https://utlists.utexas.edu/sympa/subscribe/galois-users).\n\nIf you find a bug, it would help us if you sent (1) the command line and\nprogram inputs and outputs and (2) a core dump, preferably from an executable\nbuilt with the debug build.\n\nYou can enable core dumps by setting `ulimit -c unlimited` before running your\nprogram. The location where the core dumps will be stored can be determined with\n`cat /proc/sys/kernel/core_pattern`.\n\nTo create a debug build, assuming you will build Galois in `BUILD_DIR` and the\nsource is in `SRC_DIR`:\n\n```Shell\ncmake -S $SRC_DIR -B $BUILD_DIR -DCMAKE_BUILD_TYPE=Debug\nmake -C $BUILD_DIR\n```\n\nA simple way to capture relevant debugging details is to use the `script`\ncommand, which will record your terminal input and output. For example,\n\n```Shell\nscript debug-log.txt\nulimit -c unlimited\ncat /proc/sys/kernel/core_pattern\nmake -C $BUILD_DIR \u003cmy-app\u003e VERBOSE=1\nmy-app with-failing-input\nexit\n```\n\nThis will generate a file `debug-log.txt`, which you can send to the mailing\nlist:[galois-users@utlists.utexas.edu](galois-users@utlists.utexas.edu) for\nfurther debugging or supply when opening a GitHub issue.\n","funding_links":[],"categories":["Projects (sorted by year)","Software","C++"],"sub_categories":["2010","Trends"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIntelligentSoftwareSystems%2FGalois","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FIntelligentSoftwareSystems%2FGalois","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIntelligentSoftwareSystems%2FGalois/lists"}