Skip to content

Commit 5a2de46

Browse files
zichguan-amdNB4444
zichguan-amd
and
NB4444
authored
Add README files and make files to hiprand examples (#302) (#306)
* Add READMEs and Makefiles hiprand * Add hiprand to root-level readme (cherry picked from commit 9d38082) Also incorporates commit 5076a78 Co-authored-by: Nick Breed <78807921+NB4444@users.noreply.github.com>
1 parent af239d8 commit 5a2de46

File tree

12 files changed

+666
-142
lines changed

12 files changed

+666
-142
lines changed

‎Libraries/Makefile‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,8 @@ LIBRARIES := \
2525
hipCUB \
2626
hipFFT \
2727
hipSOLVER \
28-
rocRAND
28+
rocRAND \
29+
hipRAND
2930

3031
ifneq ($(GPU_RUNTIME), CUDA)
3132
LIBRARIES += \

‎Libraries/hipRAND/Makefile‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# MIT License
2+
#
3+
# Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved.
4+
#
5+
# Permission is hereby granted, free of charge, to any person obtaining a copy
6+
# of this software and associated documentation files (the "Software"), to deal
7+
# in the Software without restriction, including without limitation the rights
8+
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
# copies of the Software, and to permit persons to whom the Software is
10+
# furnished to do so, subject to the following conditions:
11+
#
12+
# The above copyright notice and this permission notice shall be included in all
13+
# copies or substantial portions of the Software.
14+
#
15+
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
# SOFTWARE.
22+
23+
EXAMPLES := \
24+
c_cpp_api \
25+
device_api
26+
27+
all: $(EXAMPLES)
28+
29+
clean: TARGET=clean
30+
clean: all
31+
32+
$(EXAMPLES):
33+
$(MAKE) -C $@ $(TARGET)
34+
35+
.PHONY: all clean $(EXAMPLES)

‎Libraries/hipRAND/README.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# hipRAND Examples
2+
3+
## Summary
4+
5+
The examples in this subdirectory showcase the functionality of the [hipRAND](https://github.com/ROCm/rocm-libraries/tree/develop/projects/hiprand) library. The examples build on both Linux and Windows for both the ROCm (AMD GPU) and CUDA (NVIDIA GPU) backends.
6+
7+
## Prerequisites
8+
9+
### Linux
10+
11+
- [CMake](https://cmake.org/download/) (at least version 3.21) OR GNU Make - available via the distribution's package manager
12+
- [ROCm](https://rocm.docs.amd.com/projects/HIP/en/latest/install/install.html) (at least version 6.x.x)
13+
- [hipRAND](https://github.com/ROCm/hipRAND)
14+
- ROCm platform: `hipRAND-dev` package available from [repo.radeon.com](https://repo.radeon.com/rocm/). The repository is added during the standard ROCm [install procedure](https://rocm.docs.amd.com/projects/HIP/en/latest/install/install.html).
15+
- CUDA platform: Install hipRAND from source: [instructions](https://github.com/ROCm/hipRAND#build-and-install).
16+
- [cuRAND](https://developer.nvidia.com/curand) is a dependency of hipRAND for NVIDIA platforms. CUB is part of the NVIDIA CUDA Toolkit.
17+
18+
### Windows
19+
20+
- [Visual Studio](https://visualstudio.microsoft.com/) 2019 or 2022 with the "Desktop Development with C++" workload
21+
- ROCm toolchain for Windows
22+
- The Visual Studio ROCm extension needs to be installed to build with the solution files.
23+
- [hipRAND](https://github.com/ROCm/hipRAND)
24+
- ROCm platform: Installed as part of the ROCm SDK on Windows for ROCm platform.
25+
- CUDA platform: Install hipRAND from source: [instructions](https://github.com/ROCm/rocm-libraries/tree/develop/projects/hiprand#build-and-install).
26+
- [cuRAND](https://developer.nvidia.com/curand) is a dependency of hipRAND for NVIDIA platforms. cuRAND is part of the NVIDIA CUDA Toolkit.
27+
- [CMake](https://cmake.org/download/) (optional, to build with CMake. Requires at least version 3.21)
28+
- [Ninja](https://ninja-build.org/) (optional, to build with CMake)
29+
30+
## Building
31+
32+
### Linux
33+
34+
Make sure that the dependencies are installed, or use one of the [provided Dockerfiles](../../Dockerfiles/) to build and run the examples in a containerized environment.
35+
36+
#### Using CMake
37+
38+
All examples in the `hipRAND` subdirectory can either be built by a single CMake project or be built independently.
39+
40+
- `$ cd Libraries/hipRAND`
41+
- `$ cmake -S . -B build` (on ROCm) or `$ cmake -S . -B build -D GPU_RUNTIME=CUDA` (on CUDA)
42+
- `$ cmake --build build`
43+
44+
#### Using Make
45+
46+
All examples can be built by a single invocation to Make or be built independently.
47+
48+
- `$ cd Libraries/hipRAND`
49+
- `$ make` (on ROCm) or `$ make GPU_RUNTIME=CUDA` (on CUDA)
50+
51+
### Windows
52+
53+
#### Visual Studio
54+
55+
Visual Studio solution files are available for the individual examples. To build all examples for hipRAND open the top level solution file [ROCm-Examples-VS2019.sln](../../ROCm-Examples-VS2019.sln) and filter for hipRAND.
56+
57+
For more detailed build instructions refer to the top level [README.md](../../README.md#visual-studio).
58+
59+
#### CMake
60+
61+
All examples in the `hipRAND` subdirectory can either be built by a single CMake project or be built independently. For build instructions refer to the top-level [README.md](../../README.md#cmake-2).

‎Libraries/hipRAND/c_cpp_api/Makefile‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# MIT License
2+
#
3+
# Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved.
4+
#
5+
# Permission is hereby granted, free of charge, to any person obtaining a copy
6+
# of this software and associated documentation files (the "Software"), to deal
7+
# in the Software without restriction, including without limitation the rights
8+
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
# copies of the Software, and to permit persons to whom the Software is
10+
# furnished to do so, subject to the following conditions:
11+
#
12+
# The above copyright notice and this permission notice shall be included in all
13+
# copies or substantial portions of the Software.
14+
#
15+
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
# SOFTWARE.
22+
23+
EXAMPLES := \
24+
simple_distributions_cpp
25+
26+
all: $(EXAMPLES)
27+
28+
clean: TARGET=clean
29+
clean: all
30+
31+
$(EXAMPLES):
32+
$(MAKE) -C $@ $(TARGET)
33+
34+
.PHONY: all clean $(EXAMPLES)

‎Libraries/hipRAND/c_cpp_api/simple_distributions_cpp/Makefile‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# MIT License
2+
#
3+
# Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved.
4+
#
5+
# Permission is hereby granted, free of charge, to any person obtaining a copy
6+
# of this software and associated documentation files (the "Software"), to deal
7+
# in the Software without restriction, including without limitation the rights
8+
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
# copies of the Software, and to permit persons to whom the Software is
10+
# furnished to do so, subject to the following conditions:
11+
#
12+
# The above copyright notice and this permission notice shall be included in all
13+
# copies or substantial portions of the Software.
14+
#
15+
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
# SOFTWARE.
22+
23+
EXAMPLE := hiprand_simple_distributions_cpp
24+
COMMON_INCLUDE_DIR := ../../../../Common
25+
EXTERNAL_DIR := ../../../../External
26+
GPU_RUNTIME := HIP
27+
28+
# HIP variables
29+
ROCM_INSTALL_DIR := /opt/rocm
30+
CUDA_INSTALL_DIR := /usr/local/cuda
31+
32+
HIP_INCLUDE_DIR := $(ROCM_INSTALL_DIR)/include
33+
HIPRAND_INCLUDE_DIR := $(HIP_INCLUDE_DIR)
34+
35+
HIPCXX ?= $(ROCM_INSTALL_DIR)/bin/hipcc
36+
CUDACXX ?= $(CUDA_INSTALL_DIR)/bin/nvcc
37+
38+
# Common variables and flags
39+
CXX_STD := c++17
40+
ICXXFLAGS := -std=$(CXX_STD)
41+
ICPPFLAGS := -isystem $(HIPRAND_INCLUDE_DIR) -I $(COMMON_INCLUDE_DIR) -I $(EXTERNAL_DIR)
42+
ILDFLAGS := -L $(ROCM_INSTALL_DIR)/lib
43+
ILDLIBS := -lhiprand
44+
45+
ifeq ($(GPU_RUNTIME), CUDA)
46+
ICXXFLAGS += -x cu
47+
ICPPFLAGS += -isystem $(HIP_INCLUDE_DIR) -D__HIP_PLATFORM_NVIDIA__
48+
COMPILER := $(CUDACXX)
49+
else ifeq ($(GPU_RUNTIME), HIP)
50+
CXXFLAGS ?= -Wall -Wextra
51+
ICPPFLAGS += -D__HIP_PLATFORM_AMD__
52+
COMPILER := $(HIPCXX)
53+
else
54+
$(error GPU_RUNTIME is set to "$(GPU_RUNTIME)". GPU_RUNTIME must be either CUDA or HIP)
55+
endif
56+
57+
ICXXFLAGS += $(CXXFLAGS)
58+
ICPPFLAGS += $(CPPFLAGS)
59+
ILDFLAGS += $(LDFLAGS)
60+
ILDLIBS += $(LDLIBS)
61+
62+
$(EXAMPLE): main.cpp $(COMMON_INCLUDE_DIR)/example_utils.hpp $(EXTERNAL_DIR)/CmdParser/cmdparser.hpp
63+
$(COMPILER) $(ICXXFLAGS) $(ICPPFLAGS) $(ILDFLAGS) -o $@ $< $(ILDLIBS)
64+
65+
clean:
66+
$(RM) $(EXAMPLE)
67+
68+
.PHONY: clean

‎Libraries/hipRAND/c_cpp_api/simple_distributions_cpp/README.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# hipRAND c_cpp_api simple_distributions Example
2+
3+
## Description
4+
5+
This example illustrates the use of the hipRAND cpp API. It specifically shows an example for a simple distribution.
6+
7+
### Application flow
8+
9+
1. Parse command-line arguments:
10+
- Device ID
11+
- Random distribution type
12+
- Problem size
13+
- Print toggle
14+
2. Query and set the selected HIP device.
15+
3. Generate random numbers on the device (GPU) using hipRAND.
16+
4. Generate random numbers on the host (CPU) using the standard library.
17+
5. Measure and print execution time for both device and host.
18+
6. Optionally print the generated random numbers.
19+
20+
## Key APIs and Concepts
21+
22+
### hiprand_cpp
23+
24+
- The host level API of hipRAND is used to generate different random distributions using the GPU (in this case `hiprand_cpp::uniform_int_distribution<unsigned int>`, `hiprand_cpp::uniform_real_distribution<float>`, `hiprand_cpp::normal_distribution<double>` and `hiprand_cpp::poisson_distribution<unsigned int>`).
25+
26+
## Used API surface
27+
28+
### hiprand_cpp
29+
30+
- `default_random_engine`
31+
- `uniform_int_distribution`
32+
- `uniform_real_distribution`
33+
- `normal_distribution`
34+
- `poisson_distribution`
35+
36+
### HIP runtime
37+
38+
- `HIP_CHECK`
39+
- `hipSetDevice`
40+
- `hipDeviceProp_t`
41+
- `hipGetDeviceProperties`
42+
- `hipMalloc`
43+
- `hipMemcpy`
44+
- `hipMemcpyDeviceToHost`
45+
- `hipGetDeviceCount`

‎Libraries/hipRAND/device_api/Makefile‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# MIT License
2+
#
3+
# Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved.
4+
#
5+
# Permission is hereby granted, free of charge, to any person obtaining a copy
6+
# of this software and associated documentation files (the "Software"), to deal
7+
# in the Software without restriction, including without limitation the rights
8+
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
# copies of the Software, and to permit persons to whom the Software is
10+
# furnished to do so, subject to the following conditions:
11+
#
12+
# The above copyright notice and this permission notice shall be included in all
13+
# copies or substantial portions of the Software.
14+
#
15+
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
# SOFTWARE.
22+
23+
EXAMPLES := \
24+
pseudorandom_generations \
25+
quasirandom_generations
26+
27+
all: $(EXAMPLES)
28+
29+
clean: TARGET=clean
30+
clean: all
31+
32+
$(EXAMPLES):
33+
$(MAKE) -C $@ $(TARGET)
34+
35+
.PHONY: all clean $(EXAMPLES)

‎Libraries/hipRAND/device_api/pseudorandom_generations/Makefile‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# MIT License
2+
#
3+
# Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved.
4+
#
5+
# Permission is hereby granted, free of charge, to any person obtaining a copy
6+
# of this software and associated documentation files (the "Software"), to deal
7+
# in the Software without restriction, including without limitation the rights
8+
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
# copies of the Software, and to permit persons to whom the Software is
10+
# furnished to do so, subject to the following conditions:
11+
#
12+
# The above copyright notice and this permission notice shall be included in all
13+
# copies or substantial portions of the Software.
14+
#
15+
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
# SOFTWARE.
22+
23+
EXAMPLE := hiprand_pseudorandom_generations
24+
COMMON_INCLUDE_DIR := ../../../../Common
25+
EXTERNAL_DIR := ../../../../External
26+
GPU_RUNTIME := HIP
27+
28+
# HIP variables
29+
ROCM_INSTALL_DIR := /opt/rocm
30+
CUDA_INSTALL_DIR := /usr/local/cuda
31+
32+
HIP_INCLUDE_DIR := $(ROCM_INSTALL_DIR)/include
33+
HIPRAND_INCLUDE_DIR := $(HIP_INCLUDE_DIR)
34+
35+
HIPCXX ?= $(ROCM_INSTALL_DIR)/bin/hipcc
36+
CUDACXX ?= $(CUDA_INSTALL_DIR)/bin/nvcc
37+
38+
# Common variables and flags
39+
CXX_STD := c++17
40+
ICXXFLAGS := -std=$(CXX_STD)
41+
ICPPFLAGS := -isystem $(HIPRAND_INCLUDE_DIR) -I $(COMMON_INCLUDE_DIR) -I $(EXTERNAL_DIR)
42+
ILDFLAGS := -L $(ROCM_INSTALL_DIR)/lib
43+
ILDLIBS := -lhiprand
44+
45+
ifeq ($(GPU_RUNTIME), CUDA)
46+
ICXXFLAGS += -x cu
47+
ICPPFLAGS += -isystem $(HIP_INCLUDE_DIR) -D__HIP_PLATFORM_NVIDIA__
48+
COMPILER := $(CUDACXX)
49+
else ifeq ($(GPU_RUNTIME), HIP)
50+
CXXFLAGS ?= -Wall -Wextra
51+
ICPPFLAGS += -D__HIP_PLATFORM_AMD__
52+
COMPILER := $(HIPCXX)
53+
else
54+
$(error GPU_RUNTIME is set to "$(GPU_RUNTIME)". GPU_RUNTIME must be either CUDA or HIP)
55+
endif
56+
57+
ICXXFLAGS += $(CXXFLAGS)
58+
ICPPFLAGS += $(CPPFLAGS)
59+
ILDFLAGS += $(LDFLAGS)
60+
ILDLIBS += $(LDLIBS)
61+
62+
$(EXAMPLE): main.hip $(COMMON_INCLUDE_DIR)/example_utils.hpp $(EXTERNAL_DIR)/CmdParser/cmdparser.hpp
63+
$(COMPILER) $(ICXXFLAGS) $(ICPPFLAGS) $(ILDFLAGS) -o $@ $< $(ILDLIBS)
64+
65+
clean:
66+
$(RM) $(EXAMPLE)
67+
68+
.PHONY: clean

0 commit comments

Comments
 (0)