{"id":18711146,"url":"https://github.com/rocm/rocthrust","last_synced_at":"2025-04-12T23:41:25.563Z","repository":{"id":37934251,"uuid":"176359532","full_name":"ROCm/rocThrust","owner":"ROCm","description":"ROCm Thrust - run Thrust dependent software on AMD GPUs","archived":false,"fork":false,"pushed_at":"2025-04-11T19:46:53.000Z","size":7464,"stargazers_count":106,"open_issues_count":12,"forks_count":50,"subscribers_count":23,"default_branch":"develop","last_synced_at":"2025-04-12T23:41:24.914Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://rocm.docs.amd.com/projects/rocThrust/en/latest/","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/ROCm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-03-18T19:55:25.000Z","updated_at":"2025-04-08T23:10:06.000Z","dependencies_parsed_at":"2023-02-15T13:15:32.499Z","dependency_job_id":"5827c012-bedf-4a4f-a896-7a6569ec49d9","html_url":"https://github.com/ROCm/rocThrust","commit_stats":{"total_commits":942,"total_committers":80,"mean_commits":11.775,"dds":0.7823779193205944,"last_synced_commit":"3bbf862e27ebe01f6ae0c73c84280ff4f65d4240"},"previous_names":["rocm/rocthrust","rocmsoftwareplatform/rocthrust"],"tags_count":67,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ROCm%2FrocThrust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ROCm%2FrocThrust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ROCm%2FrocThrust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ROCm%2FrocThrust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ROCm","download_url":"https://codeload.github.com/ROCm/rocThrust/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248647256,"owners_count":21139081,"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-11-07T12:37:17.182Z","updated_at":"2025-04-12T23:41:25.542Z","avatar_url":"https://github.com/ROCm.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rocThrust\n\n\u003e [!NOTE]\n\u003e The published rocThrust documentation is available [here](https://rocm.docs.amd.com/projects/rocThrust/en/latest/) in an organized, easy-to-read format, with search and a table of contents. The documentation source files reside in the `docs` folder of this repository. As with all ROCm projects, the documentation is open source. For more information on contributing to the documentation, see [Contribute to ROCm documentation](https://rocm.docs.amd.com/en/latest/contribute/contributing.html).\n\nThrust is a parallel algorithm library. It has been ported to\n[HIP](https://github.com/ROCm/HIP) and [ROCm](https://www.github.com/ROCm/ROCm), which use\nthe [rocPRIM](https://github.com/ROCm/rocPRIM) library. The HIP-ported library\nworks on HIP and ROCm software. Currently there is no CUDA backend in place.\n\n## Requirements\n\nSoftware requirements include:\n\n* CMake (3.10.2 or later)\n* AMD [ROCm](https://rocm.docs.amd.com) Software (1.8.0 or later)\n  * Including the [HipCC](https://github.com/ROCm/HIP) compiler, which must be set\n    as your C++ compiler for ROCm\n* [rocPRIM](https://github.com/ROCm/rocPRIM) library\n  * This is automatically downloaded and built by the CMake script\n* Python 3.6 or higher (for HIP on Windows; only required for install scripts)\n* Visual Studio 2019 with Clang support (for HIP on Windows)\n* Strawberry Perl (for HIP on Windows)\n\nOptional:\n\n* [GoogleTest](https://github.com/google/googletest)\n  * Required only for tests; building tests is enabled by default\n  * This is automatically downloaded and built by the CMake script\n* [doxygen](https://www.doxygen.nl/)\n  * Required for building the documentation\n\nFor ROCm hardware requirements, refer to:\n\n* [Linux support](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html)\n* [Windows support](https://rocm.docs.amd.com/projects/install-on-windows/en/latest/reference/system-requirements.html)\n\n## Build and install\n\n```sh\ngit clone https://github.com/ROCm/rocThrust\n\n# Go to rocThrust directory, create and go to the build directory.\ncd rocThrust; mkdir build; cd build\n\n# Configure rocThrust, setup options for your system.\n# Build options:\n#   DISABLE_WERROR        - ON  by default, This flag disable the -Werror compiler flag\n#   BUILD_TEST            - OFF by default,\n#   BUILD_HIPSTDPAR_TEST  - OFF by default,\n#   BUILD_EXAMPLES        - OFF by default,\n#   BUILD_BENCHMARKS      - OFF by default,\n#   DOWNLOAD_ROCPRIM      - OFF by default, when ON rocPRIM will be downloaded to the build folder,\n#   RNG_SEED_COUNT        - 0 by default, controls non-repeatable random dataset count\n#   PRNG_SEEDS            - 1 by default, reproducible seeds to generate random data\n#\n# ! IMPORTANT !\n# On ROCm platform set C++ compiler to HipCC. You can do it by adding 'CXX=\u003cpath-to-hipcc\u003e'\n# before 'cmake' or setting cmake option 'CMAKE_CXX_COMPILER' with the path to the HipCC compiler.\n#\n[CXX=hipcc] cmake ../. # or cmake-gui ../.\n\n# Build\nmake -j4\n\n# Optionally, run tests if they're enabled.\nctest --output-on-failure\n\n# Package\nmake package\n\n# Install\n[sudo] make install\n```\n\n### HIP on Windows\n\nWe've added initial support for HIP on Windows. To install, use the provided `rmake.py` Python script:\n\n```shell\ngit clone https://github.com/ROCm/rocThrust.git\ncd rocThrust\n\n# the -i option will install rocPRIM to C:\\hipSDK by default\npython rmake.py -i\n\n# the -c option will build all clients including unit tests\npython rmake.py -c\n```\n\n### Macro options\n\n```cpp\n# Performance improvement option. If you define THRUST_HIP_PRINTF_ENABLED before\n# thrust includes to 0, you can disable printfs on device side and improve\n# performance. The default value is 1\n#define THRUST_HIP_PRINTF_ENABLED 0\n```\n\n### Using rocThrust in a project\n\nWe recommended including rocThrust into a CMake project by using its package configuration files.\n\n```cmake\n# On ROCm rocThrust requires rocPRIM\nfind_package(rocprim REQUIRED CONFIG PATHS \"/opt/rocm/rocprim\")\n\n# \"/opt/rocm\" - default install prefix\nfind_package(rocthrust REQUIRED CONFIG PATHS \"/opt/rocm/rocthrust\")\n\n...\nincludes rocThrust headers and roc::rocprim_hip target\ntarget_link_libraries(\u003cyour_target\u003e roc::rocthrust)\n```\n\n## Running unit tests\n\n```sh\n# Go to rocThrust build directory\ncd rocThrust; cd build\n\n# Configure with examples flag on\nCXX=hipcc cmake -DBUILD_TEST=ON ..\n\n# Build tests\nmake -j4\n\n# To run all tests\nctest\n\n# To run unit tests for rocThrust\n./test/\u003cunit-test-name\u003e\n```\n\n### Using multiple GPUs concurrently for testing\n\nThis feature requires CMake 3.16+ to be used for building and testing. *(Prior versions of CMake can't\nassign IDs to tests when running in parallel. Assigning tests to distinct devices could only be done at\nthe cost of extreme complexity.)*\n\nUnit tests can make use of the\n[CTest Resource Allocation](https://cmake.org/cmake/help/latest/manual/ctest.1.html#resource-allocation) feature, which enables distributing tests across multiple GPUs in an intelligent manner. This feature can\naccelerate testing when multiple GPUs of the same family are in a system. It can also test multiple\nproduct families from one invocation without having to use the `HIP_VISIBLE_DEVICES` environment\nvariable. CTest Resource Allocation requires a resource spec file.\n\n```important\nUsing `RESOURCE_GROUPS` and `--resource-spec-file` with CMake and CTest, respectively for versions\nprior to 3.16 omits the feature silently. Therefore, you must ensure that the `cmake` and `ctest` you\ninvoke are sufficiently recent.\n```\n\n#### Auto resource spec generation\n\nThere is a utility script in the repo that may be called independently:\n\n```shell\n# Go to rocThrust build directory\ncd rocThrust; cd build\n\n# Invoke directly or use CMake script mode via cmake -P\n../cmake/GenerateResourceSpec.cmake\n\n# Assuming you have 2 compatible GPUs in the system\nctest --resource-spec-file ./resources.json --parallel 2\n```\n\n#### Manual\n\nAssuming you have two GPUs from the gfx900 family and they are the first devices enumerated by the\nsystem, you can specify `-D AMDGPU_TEST_TARGETS=gfx900` during configuration to specify that you\nwant only one family to be tested. If you leave this var empty (default), the default device in the system\nis targeted. To specify that there are two GPUs that should be targeted, you must feed a JSON file to\nCTest using the `--resource-spec-file \u003cpath_to_file\u003e` flag. For example:\n\n```json\n{\n  \"version\": {\n    \"major\": 1,\n    \"minor\": 0\n  },\n  \"local\": [\n    {\n      \"gfx900\": [\n        {\n          \"id\": \"0\"\n        },\n        {\n          \"id\": \"1\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n## Using custom seeds for the tests\n\nThere are two CMake configuration-time options that control random data fed to unit tests.\n\n* `RNG_SEED_COUNT`: 0 by default, controls non-repeatable random dataset count.\n  * Draws values from a default constructed `std::random_device`.\n  * Should tests fail, the actual seed producing the failure is reported by Googletest, which allows for\n    reproducibility.\n\n* `PRNG_SEEDS`: 1 by default, controls repeatable dataset seeds.\n  * This is a CMake formatted (semicolon delimited) array of 32-bit unsigned integers. Note that\n    semicolons often collide with shell command parsing. We advise escaping the entire CMake CLI\n    argument to avoid having the variable pick up quotation marks. For example, pass\n    `cmake \"-DPRNG_SEEDS=1;2;3;4\"` instead of `cmake -DPRNG_SEEDS=\"1;2;3;4\"` (these cases differ in\n    how the CMake executable receives arguments from the operating system).\n\n## Running examples\n\n```sh\n# Go to rocThrust build directory\ncd rocThrust; cd build\n\n# Configure with examples flag on\nCXX=hipcc cmake -DBUILD_EXAMPLES=ON ..\n\n# Build examples\nmake -j4\n\n# Run the example you want to run\n# ./examples/example_thrust_\u003cexample-name\u003e\n# For example:\n./examples/example_thrust_version\n\n# Example for linking with cpp files\n./examples/cpp_integration/example_thrust_linking\n```\n\n## Running benchmarks\n\n```sh\n# Go to rocThrust build directory\ncd rocThrust; cd build\n\n# Configure with benchmarks flag on\nCXX=hipcc cmake -DBUILD_BENCHMARKS=ON ..\n\n# Build benchmarks\nmake -j4\n\n# Run the benchmarks\n./benchmarks/benchmark_thrust_bench\n```\n\n## HIPSTDPAR\n\nrocThrust also hosts the header files for [HIPSTDPAR](https://rocm.blogs.amd.com/software-tools-optimization/hipstdpar/README.html#c-17-parallel-algorithms-and-hipstdpar).\nWithin these headers, a great part of the C++ Standard Library parallel algorithms are overloaded so that rocThrust's and rocPRIM's implementations of those algorithms are used when they are invoked with the `parallel_unsequenced_policy` policy.\nWhen compiling with the proper flags (see [LLVM (AMD's fork) docs](https://github.com/ROCm/llvm-project/blob/rocm-6.2.x/clang/docs/HIPSupport.rst#implementation-driver)[^1] for the complete list), the HIPSTDPAR headers are implicitly included by the compiler, and therefore the execution of these parallel algorithms will be offloaded to AMD devices.\n\n[^1]: Altough currently only AMD's fork of LLVM contains the docs for the [C++ Standard Parallelism Offload Support](https://github.com/ROCm/llvm-project/blob/rocm-6.2.x/clang/docs/HIPSupport.rst#c-standard-parallelism-offload-support-compiler-and-runtime), both of them (the upstream LLVM and AMD's fork) do support it.\n\n### Install\n\nHIPSTDPAR is currently packaged along rocThrust. The `hipstdpar` package is set up as a virtual package provided by `rocthrust`, so the latter needs to be installed entirely for getting HIPSTDPAR's headers. Conversely, installing the `rocthrust` package will also include HIPSTDPAR's headers in the system.\n\n### Tests\nrocThrust also includes tests to check the correct building of HIPSTDPAR implementations. They are located in the [tests/hipstdpar](/test/hipstdpar/) folder. When configuring the project with the `BUILD_TEST` option, these tests will not be enabled by default. To enable them, set `BUILD_HIPSTDPAR_TEST=ON`. Additionally, you can configure only HIPSTDPAR's tests by disabling `BUILD_TEST` and enabling `BUILD_HIPSTDPAR_TEST`. In general, the following steps can be followed for building and running the tests:\n\n```sh\ngit clone https://github.com/ROCm/rocThrust\n\n# Go to rocThrust directory, create and go to the build directory.\ncd rocThrust; mkdir build; cd build\n\n# Configure rocThrust.\n[CXX=hipcc] cmake ../. -D BUILD_TEST=ON # Configure rocThrust's tests.\n[CXX=hipcc] cmake ../. -D BUILD_TEST=ON -D BUILD_HIPSTDPAR_TEST=ON # Configure both rocThrust's tests and HIPSTDPAR's tests.\n[CXX=hipcc] cmake ../. -D BUILD_TEST=OFF -D BUILD_HIPSTDPAR_TEST=ON # Only configure HIPSTDPAR's tests.\n\n# Build\nmake -j4\n\n# Run tests.\nctest --output-on-failure\n```\n\n#### Requirements\n\n* [rocPRIM](https://github.com/ROCm/rocPRIM) and [rocThrust](https://github.com/ROCm/rocThrust) libraries\n* [TBB](https://www.intel.com/content/www/us/en/developer/tools/oneapi/onetbb.html) library\n  * Notice that oneTBB (oneAPI TBB) may fail to compile when libstdc++-9 or -10 is used, due to them using legacy TBB interfaces that are incompatible with the oneTBB ones (see the [release notes](https://www.intel.com/content/www/us/en/developer/articles/release-notes/intel-oneapi-threading-building-blocks-release-notes.html)).\n* CMake (3.10.2 or later)\n\n## Building the documentation locally\n\n### Requirements\n\n#### Doxygen\n\nThe build system uses Doxygen [version 1.9.4](https://github.com/doxygen/doxygen/releases/tag/Release_1_9_4). You can try using a newer version, but that might cause issues.\n\nAfter you have downloaded Doxygen version 1.9.4:\n\n```shell\n# Add doxygen to your PATH\necho 'export PATH=\u003cdoxygen 1.9.4 path\u003e/bin:$PATH' \u003e\u003e ~/.bashrc\n\n# Apply the updated .bashrc\nsource ~/.bashrc\n\n# Confirm that you are using version 1.9.4\ndoxygen --version\n```\n\n#### Python\n\nThe build system uses Python version 3.10. You can try using a newer version, but that might cause issues.\n\nYou can install Python 3.10 alongside your other Python versions using [pyenv](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation):\n\n```shell\n# Install Python 3.10\npyenv install 3.10\n\n# Create a Python 3.10 virtual environment\npyenv virtualenv 3.10 venv_rocthrust\n\n# Activate the virtual environment\npyenv activate venv_rocthrust\n```\n\n### Building\n\nAfter cloning this repository, and `cd`ing into it:\n\n```shell\n# Install Python dependencies\npython3 -m pip install -r docs/sphinx/requirements.txt\n\n# Build the documentation\npython3 -m sphinx -T -E -b html -d docs/_build/doctrees -D language=en docs docs/_build/html\n```\n\nYou can then open `docs/_build/html/index.html` in your browser to view the documentation.\n\n## Support\n\nYou can report bugs and feature requests through the GitHub\n[issue tracker](https://github.com/ROCm/rocThrust/issues).\n\n## License\n\nrocThrust is distributed under the [Apache 2.0 LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frocm%2Frocthrust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frocm%2Frocthrust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frocm%2Frocthrust/lists"}