{"id":13819078,"url":"https://github.com/owensgroup/BGHT","last_synced_at":"2025-05-16T04:32:27.344Z","repository":{"id":40620471,"uuid":"418728648","full_name":"owensgroup/BGHT","owner":"owensgroup","description":"BGHT: High-performance static GPU hash tables.","archived":false,"fork":false,"pushed_at":"2025-04-07T20:57:33.000Z","size":8472,"stargazers_count":62,"open_issues_count":7,"forks_count":8,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-04-07T21:42:42.546Z","etag":null,"topics":["cuckoo","cuda","gpu","hashing","hashmap"],"latest_commit_sha":null,"homepage":"https://owensgroup.github.io/BGHT/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/owensgroup.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2021-10-19T01:34:00.000Z","updated_at":"2025-04-07T20:57:37.000Z","dependencies_parsed_at":"2024-03-25T07:32:13.277Z","dependency_job_id":"b307575e-d7fd-4db9-8410-aedfcff2f780","html_url":"https://github.com/owensgroup/BGHT","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owensgroup%2FBGHT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owensgroup%2FBGHT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owensgroup%2FBGHT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owensgroup%2FBGHT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/owensgroup","download_url":"https://codeload.github.com/owensgroup/BGHT/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254469395,"owners_count":22076492,"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":["cuckoo","cuda","gpu","hashing","hashmap"],"created_at":"2024-08-04T08:00:39.487Z","updated_at":"2025-05-16T04:32:22.335Z","avatar_url":"https://github.com/owensgroup.png","language":"C++","readme":"# [BGHT: Better GPU Hash Tables](https://owensgroup.github.io/BGHT/)\n\n| [**Documentation**](https://owensgroup.github.io/BGHT/) | [**Tests**](https://github.com/owensgroup/BGHT/tree/main/test)  | [**Examples**](https://github.com/owensgroup/BGHT/tree/main/examples)  |  [**Benchmarks**](https://github.com/owensgroup/BGHT/tree/main/benchmarks) | [**Results**](https://github.com/owensgroup/BGHT/blob/main/results.md) |\n|--------------|----------------------|-------------------|-------------------|-------------------|\n\nBGHT is a collection of high-performance static GPU hash tables. BGHT contains hash tables that use three different probing schemes 1) bucketed cuckoo, 2) power-of-two, 3) iceberg hashing. Our bucketed static cuckoo hash table is the state-of-art static hash table.\nFor more information, please check our papers:\n\n[**Better GPU Hash Tables**](https://owensgroup.github.io/BGHT/) [[arXiv]](https://arxiv.org/abs/2108.07232) [[APOCS]](https://escholarship.org/uc/item/6cb1q6rz)\u003cbr\u003e\n*[Muhammad A. Awad](https://maawad.github.io/), [Saman Ashkiani](https://scholar.google.com/citations?user=Z4_ZfiEAAAAJ\u0026hl=en), [Serban D. Porumbescu](https://web.cs.ucdavis.edu/~porumbes/), [Martín Farach-Colton](https://people.cs.rutgers.edu/~farach/), and [John D. Owens](https://www.ece.ucdavis.edu/~jowens/)*\n\n## Key features\n* State-of-the-art static GPU hash tables\n* Device and host side APIs\n* Support for different types of keys and values\n* Standard-like APIs\n\n\u003e [!NOTE]  \n\u003e An experimental HIP-based version of the library targeting AMD GPUs is available at the [hip](https://github.com/owensgroup/BGHT/tree/hip) branch (See the [Radeon-RX-7900-XT](https://github.com/owensgroup/BGHT/tree/hip/figs/Radeon-RX-7900-XT) results).\n\n## How to use\nBGHT is a header-only library. To use the library, you can add it as a submodule or use [CMake Package Manager (CPM)](https://github.com/cpm-cmake/CPM.cmake) to fetch the library into your CMake-based project ([complete example](https://github.com/owensgroup/BGHT/tree/main/examples/cpm)).\n```cmake\ncmake_minimum_required(VERSION 3.8 FATAL_ERROR)\nCPMAddPackage(\n  NAME bght\n  GITHUB_REPOSITORY owensgroup/BGHT\n  GIT_TAG main\n  OPTIONS\n     \"build_tests OFF\"\n     \"build_benchmarks OFF\"\n)\ntarget_link_libraries(my_library PRIVATE bght)\n```\n\n### APIs\nAll the data structures follow the C++ standard hash map (`std::unordered_map`) APIs closely. An example APIs for BCHT is shown below:\n```cuda\ntemplate \u003cclass Key,\n          class T,\n          class Hash = bght::universal_hash\u003cKey\u003e,\n          class KeyEqual = bght::equal_to\u003cKey\u003e,\n          cuda::thread_scope Scope = cuda::thread_scope_device,\n          class Allocator = bght::cuda_allocator\u003cchar\u003e,\n          int B = 16\u003e class bcht;\n```\n#### Member functions\n```cuda\n// Constructor\nbcht(std::size_t capacity,\n     Key sentinel_key,\n     T sentinel_value,\n     Allocator const\u0026 allocator = Allocator{});\n// Host-side APIs\ntemplate \u003ctypename InputIt\u003e\n  bool insert(InputIt first, InputIt last, cudaStream_t stream = 0);\ntemplate \u003ctypename InputIt, typename OutputIt\u003e\n  void find(InputIt first, InputIt last, OutputIt output_begin, cudaStream_t stream = 0);\n// Device-side APIs\ntemplate \u003ctypename tile_type\u003e\n__device__ bool insert(value_type const\u0026 pair, tile_type const\u0026 tile);\ntemplate \u003ctypename tile_type\u003e\n__device__ mapped_type find(key_type const\u0026 key, tile_type const\u0026 tile);\n```\n### Member types\n```\nMember type                     Definition\nkey_type                        Key\nmapped_type                     T\nvalue_type                      bght::pair\u003cKey, T\u003e\nallocator_type                  Allocator\nbucket_size                     Bucket size for device-side APIs cooperative groups tile construction\n```\n\n\n#### Example\n```cuda\n// Example using host-side APIs\n#include \u003cbght/cht.hpp\u003e\nint main(){\n  using key_type = uint32_t;\n  using value_type = uint32_t;\n  using pair_type = bght::pair\u003ckey_type, value_type\u003e;\n  std::size_t capacity = 128; std::size_t num_keys = 64;\n  key_type invalid_key = 0; value_type invalid_value = 0; // sentinel key and value\n\n  bght::bcht\u003ckey_type, value_type\u003e table(capacity, invalid_key, invalid_value); //ctor\n\n  pair_type* pairs; // input pairs\n  // ... allocate pairs\n\n  bool success = table.insert(pairs, pairs + num_keys);\n  assert(success);\n\n  key_type* queries;  // query keys\n  value_type* results; // query result\n  // ... allocate queries and results\n  table.find(queries, queries + num_keys, results);\n}\n\n```\n```cuda\n// Example using device-side APIs\ntemplate\u003cclass HashMap\u003e\n__global__ void kernel(HashMap table){\n  // construct tile\n  auto block = cooperative_groups::this_thread_block();\n  auto tile = cooperative_groups::tiled_partition\u003cHashMap::bucket_size\u003e(block);\n  pair_type pair{...};\n  table.insert(pair, tile);\n  pair_type query{..};\n  query.second = table.find(query.first, tile);\n}\nint main(){\n  // Call the hash table constructor on the CPU\n  bght::bcht\u003ckey_type, value_type\u003e table(...);\n  // Pass the hash table to a GPU kernel\n  kernel\u003c\u003c\u003c...\u003e\u003e\u003e(table);\n}\n```\n\n## Requirements and limitations\nPlease create an issue if you face challenges with any of the following limitations and requirements.\n### Requirements\n* C++17/CUDA C++17\n* NVIDIA Volta GPU or later microarchitectures\n* CMake 3.8 or later\n* CUDA 11.5 or later\n\n#### Using Docker\nWe provide a docker image that include the software requirements (except for CUDA drivers). To build the docker image, run:\n```bash\nsource docker/build\n```\nTo start the container, run:\n```bash\nsource docker/run\n```\nAfter starting the container, you can build and execute BGHT code without any additional requirements.\n\n### limitations\n* Currently hash tables based on cuckoo hashing do not support concurrent insertion and queries. IHT and P2BHT support concurrent insertions and queries.\nFor hash tables that use a probing scheme other than IHT:\n* Keys must be unique.\n* Construction of the data structures offered *may* fail. In these scenarios, reconstructing the table using a larger capacity or a lower load factor should be considered. Our paper offers recommended hash table load factors (for uniformly distributed unsigned keys) to achieve at least a 99% success rate ([See Fig. 2](https://arxiv.org/abs/2108.07232)). For example, BCHT will offer a 100% success rate for up to 0.991 load factor. Please create an issue if you encounter any problems with different key distributions.\n\n## Reproducing the arXiv paper results\nTo reproduce the results, follow the following [steps](reproduce.md). You can also view our results [here](./results.md). If you find any mismatch (either faster or slower) between the results offered in the repository or the paper, please create an issue, and we will investigate the performance changes.\n\n## Benchmarks\nPlease check our [paper](https://arxiv.org/abs/2108.07232) for comprehensive analysis and benchmarks. Also, see the following steps to [reproduce](reproduce.md) the results.\n\n## Questions and bug report\nPlease create an issue. We will welcome any contributions that improve the usability and quality of our repository.\n\n## Bibtex\n```bibtex\n@InProceedings{   Awad:2023:AAI,\n  title         = {Analyzing and Implementing {GPU} Hash Tables},\n  author        = {Muhammad A. Awad and Saman Ashkiani and Serban D.\n                  Porumbescu and Mart{\\'{i}}n Farach-Colton and John D.\n                  Owens},\n  booktitle     = \"SIAM Symposium on Algorithmic Principles of Computer\n                  Systems\",\n  series        = {APOCS23},\n  year          = 2023,\n  month         = jan,\n  pages         = {33--50},\n  code          = {https://github.com/owensgroup/BGHT},\n  doi           = {10.1137/1.9781611977578.ch3},\n  url           = {https://escholarship.org/uc/item/6cb1q6rz}\n}\n```\n\n## Acknowledgments\n\nThe structure and organization of the repository were inspired by [NVIDIA's cuCollection](https://github.com/nviDIA/cuCollections/) and [RXMesh](https://github.com/owensgroup/RXMesh).\n","funding_links":[],"categories":["C++"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fowensgroup%2FBGHT","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fowensgroup%2FBGHT","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fowensgroup%2FBGHT/lists"}