Skip to content

Commit 3af6291

Browse files
rocm-cirocm-ci
authored
Merge pull request #649 from amd-jnovotny/rocrand-docs-refactor-phase1-rocmrel64
Auto-submit by Jenkins
2 parents 4d5d3a8 + c676e91 commit 3af6291

File tree

4 files changed

+189
-76
lines changed

4 files changed

+189
-76
lines changed

‎CMakeLists.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -233,7 +233,7 @@ set(ROCRAND_CONFIG_DIR "\${CPACK_PACKAGING_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDI
233233

234234
rocm_create_package(
235235
NAME ${package_name}
236-
DESCRIPTION "Radeon Open Compute RAND library"
236+
DESCRIPTION "rocRAND is a ROCm random number generation library"
237237
MAINTAINER "rocRAND Maintainer <[email protected]>"
238238
LDCONFIG
239239
# LDCONFIG_DIR ${ROCRAND_CONFIG_DIR}

‎docs/index.rst‎

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
.. meta::
2-
:description: rocRAND documentation and API reference library
2+
:description: introduction to the rocRAND documentation and API reference library
33
:keywords: rocRAND, ROCm, API, documentation
44

55
.. _rocrand-docs-home:
@@ -8,33 +8,36 @@
88
rocRAND documentation
99
********************************************************************
1010

11-
rocRAND provides functions that generate pseudo-random and quasi-random numbers. The rocRAND library is implemented in the `HIP <https://rocm.docs.amd.com/projects/HIP/en/latest/index.html>`_
12-
programming language and optimized for AMD's latest discrete GPUs. It is designed to run on top
13-
of AMD's `ROCm <https://rocm.docs.amd.com/en/latest/>`_, but it also works on NVIDIA CUDA-enabled GPUs.
11+
rocRAND provides functions that generate pseudo-random and quasi-random numbers.
12+
The rocRAND library is implemented in the :doc:`HIP <hip:index>`
13+
programming language and optimized for the latest discrete AMD GPUs. It is designed to run on top
14+
of the AMD :doc:`ROCm platform <rocm:what-is-rocm>`, but it also works on NVIDIA CUDA-enabled GPUs.
1415

15-
rocRAND includes a wrapper library called hipRAND, which you can use to easily port
16-
NVIDIA CUDA applications using the CUDA cuRAND library to the
17-
`HIP <https://rocm.docs.amd.com/projects/HIP/en/latest/index.html>`_ layer. In the
18-
`ROCm <https://rocm.docs.amd.com/en/latest/>`_ environment, hipRAND uses rocRAND.
16+
rocRAND integrates with a wrapper library called hipRAND, which you can use to easily port
17+
NVIDIA CUDA applications that use the CUDA cuRAND library to the
18+
:doc:`HIP <hip:index>` layer. In a
19+
ROCm environment, hipRAND uses the rocRAND library.
1920

20-
You can access rocRAND code on our `GitHub repository <https://github.com/ROCm/rocRAND>`_.
21-
22-
The documentation is structured as follows:
21+
The rocRAND public repository is located at `<https://github.com/ROCm/rocRAND>`_.
2322

2423
.. grid:: 2
2524
:gutter: 3
2625

2726
.. grid-item-card:: Install
2827

29-
* :ref:`installing`
28+
* :doc:`Installation guide <./install/installing>`
3029

3130
.. grid-item-card:: Conceptual
3231

33-
* :ref:`programmers-guide`
32+
* :doc:`Programming guide <./conceptual/programmers-guide>`
3433

3534
* :ref:`curand-compatibility`
3635
* :ref:`dynamic-ordering-configuration`
3736

37+
.. grid-item-card:: Examples
38+
39+
* `Examples <https://github.com/ROCm/rocRAND/tree/develop/python/rocrand/examples>`_
40+
3841
.. grid-item-card:: API reference
3942

4043
* :doc:`rocRAND data type support <api-reference/data-type-support>`
@@ -43,7 +46,6 @@ The documentation is structured as follows:
4346
* :doc:`Fortran API reference <fortran-api-reference>`
4447
* :doc:`API library <doxygen/html/index>`
4548

46-
To contribute to the documentation, refer to
47-
`Contributing to ROCm <https://rocm.docs.amd.com/en/latest/contribute/contributing.html>`_.
49+
To contribute to the documentation, see `Contributing to ROCm <https://rocm.docs.amd.com/en/latest/contribute/contributing.html>`_.
4850

4951
You can find licensing information on the `Licensing <https://rocm.docs.amd.com/en/latest/about/license.html>`_ page.

‎docs/install/installing.rst‎

Lines changed: 161 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,110 +1,211 @@
11
.. meta::
2-
:description: rocRAND documentation and API reference library
3-
:keywords: rocRAND, ROCm, API, documentation
2+
:description: rocRAND installation guide
3+
:keywords: rocRAND, ROCm, API, documentation, installation
44

55
.. _installing:
66

7-
============
8-
Installation
9-
============
7+
*******************************************************************
8+
Installing and building rocRAND
9+
*******************************************************************
10+
11+
This topic describes how to install or build rocRAND. The easiest method is to install the prebuilt
12+
packages from the ROCm repositories, but this chapter also describes how to build rocRAND from source.
13+
14+
Requirements
15+
===============================
16+
17+
rocRAND has the following prerequisites:
18+
19+
* CMake (version 3.16 or later)
20+
* C++ compiler with C++17 support to build the library
21+
22+
* gcc version 9 or later is recommended
23+
* Clang uses the development headers and libraries from gcc, so a recent version of it must still be installed when compiling with clang
24+
25+
* C++ compiler with C++11 support to use the library
26+
27+
* (Optional) Fortran compiler (This is only required for the Fortran wrapper. GFortran is recommended.)
28+
29+
* (Optional) GoogleTest (This is only required to build and use the tests. Building the tests is enabled by default.)
30+
31+
Use ``GTEST_ROOT`` to specify the GoogleTest location. For more information,
32+
see `FindGTest <https://cmake.org/cmake/help/latest/module/FindGTest.html>`_.
33+
34+
.. note::
35+
36+
If GoogleTest is not already installed, it will be automatically downloaded and built.
37+
38+
The following additional components are required to use rocRAND on AMD platforms:
39+
40+
* ROCm (see the :doc:`ROCm installation guide <rocm-install-on-linux:install/quick-start>`)
41+
* A HIP-clang compiler, which must be set as the C++ compiler on the ROCm platform.
42+
43+
The following additional components are required to use rocRAND on NVIDIA CUDA platforms:
44+
45+
* HIP
46+
* The latest CUDA SDK
47+
48+
Install using prebuilt packages
49+
===============================
50+
51+
To install the prebuilt rocRAND packages, you require a ROCm-enabled platform.
52+
For information on installing ROCm, see the :doc:`ROCm installation guide <rocm-install-on-linux:install/quick-start>`.
53+
After installing ROCm or enabling the ROCm repositories, use the system package manager to install rocRAND.
54+
55+
For Ubuntu and Debian:
56+
57+
.. code-block:: shell
1058
11-
Introduction
12-
------------
59+
sudo apt-get install rocrand
1360
14-
This chapter describes how to obtain rocRAND. There are two main methods: the easiest way is to install the prebuilt packages from the ROCm repositories. Alternatively, this chapter also describes how to build rocRAND from source.
61+
For CentOS-based systems:
1562

16-
Prebuilt packages
17-
-----------------
63+
.. code-block:: shell
1864
19-
Installing the prebuilt rocRAND packages requires a ROCm-enabled platform. See the `ROCm documentation <https://rocm.docs.amd.com/>`_ for more information. After installing ROCm or enabling the ROCm repositories, rocRAND can be obtained using the system package manager.
65+
sudo yum install rocrand
2066
21-
For Ubuntu and Debian::
67+
For SLES:
2268

23-
sudo apt-get install rocrand
69+
.. code-block:: shell
2470
25-
For CentOS::
71+
sudo dnf install rocrand
2672
27-
sudo yum install rocrand
73+
These commands install rocRAND in the ``/opt/rocm`` directory.
2874

29-
For SLES::
75+
Build rocRAND from source
76+
===============================
3077

31-
sudo dnf install rocrand
78+
This section provides the information required to build rocRAND from source.
3279

33-
This will install rocRAND into the ``/opt/rocm`` directory.
3480

35-
Building rocRAND from source
36-
----------------------------
81+
Obtaining the rocRAND source code
82+
---------------------------------
3783

38-
Obtaining sources
39-
^^^^^^^^^^^^^^^^^
84+
The rocRAND source code is available from the `rocRAND GitHub Repository <https://github.com/ROCm/rocRAND>`_.
85+
Use the branch that matches the ROCm version installed on the system.
86+
For example, on a system with ROCm 6.3 installed, use the following command to obtain the rocRAND version 6.3 source code:
4087

41-
The rocRAND sources are available from the `rocRAND GitHub Repository <https://github.com/ROCm/rocRAND>`_. Use the branch that matches the system-installed version of ROCm. For example on a system that has ROCm 5.3 installed, use the following command to obtain rocRAND sources::
88+
.. code-block:: shell
4289
43-
git checkout -b rocm-5.3 https://github.com/ROCmSoftwarePlatform/rocRAND.git
90+
91+
git checkout -b rocm-6.3 https://github.com/ROCmSoftwarePlatform/rocRAND.git
4492
4593
Building the library
46-
^^^^^^^^^^^^^^^^^^^^
94+
--------------------
95+
96+
After downloading the source code, use the installation script to build rocRAND:
4797

48-
After obtaining the sources, rocRAND can be built using the installation script::
98+
.. code-block:: shell
4999
50-
cd rocRAND
51-
./install --install
100+
cd rocRAND
101+
./install --install
52102
53-
This automatically builds all required dependencies, excluding HIP and Git, and installs the project to ``/opt/rocm`` if everything went well. See ``./install --help`` for further information.
103+
This automatically builds all required dependencies, excluding HIP and Git, and installs the project
104+
to ``/opt/rocm``. For further information, run the ``./install --help`` command.
54105

55106
Building with CMake
56-
^^^^^^^^^^^^^^^^^^^
107+
--------------------
108+
109+
For a more detailed installation process, build rocRAND manually using CMake.
110+
This enables certain configuration options that are not available through the ``./install`` script.
111+
To build rocRAND, use CMake with the following configuration:
112+
113+
.. code-block:: shell
114+
115+
cd rocrand; mkdir build; cd build
116+
# Configure the project
117+
CXX=<compiler> cmake [options] ..
118+
# Build
119+
make -j4
120+
# Optionally, run the tests
121+
ctest --output-on-failure
122+
# Install
123+
[sudo] make install
124+
125+
To build for the ROCm platform, ``<compiler>`` should be set to ``hipcc``. To build for CUDA,
126+
``<compiler>`` should be set to the host compiler. For CUDA, if the location of ``nvcc`` isn't on the path, it might need to be
127+
passed explicitly using ``-DCMAKE_CUDA_COMPILER=<path-to-nvcc>``.
128+
Additionally, the directory where ``FindHIP.cmake`` is installed needs to be passed explicitly
129+
using ``-DCMAKE_MODULE_PATH``. By default, this file is installed in ``/opt/rocm/hip/cmake``.
130+
131+
In addition to the built-in CMake options, the following configuration options are available:
132+
133+
* ``BUILD_FORTRAN_WRAPPER``: Controls whether to build the Fortran wrapper. Defaults to ``OFF``.
134+
* ``BUILD_TEST``: Controls whether to build the rocRAND tests. Defaults to ``OFF``.
135+
* ``BUILD_BENCHMARK``: Controls whether to build the rocRAND benchmarks. Defaults to ``OFF``.
136+
* ``BUILD_ADDRESS_SANITIZER`` Controls whether to build with address sanitization enabled. Defaults to ``OFF``.
137+
138+
To install rocRAND with a non-standard installation location of ROCm, pass ``-DCMAKE_PREFIX_PATH=</path/to/opt/rocm/>``
139+
or set the environment variable ``ROCM_PATH`` to ``path/to/opt/rocm``.
140+
141+
rocRAND with HIP on Windows
142+
===============================
57143

58-
For a more elaborate installation process, rocRAND can be built manually using CMake. This enables certain configuration options that are not exposed to the ``./install`` script. In general, rocRAND can be built using CMake by configuring as follows::
144+
rocRAND with HIP on Microsoft Windows has the following additional prerequisites:
59145

60-
cd rocrand; mkdir build; cd build
61-
# Configure the project
62-
CXX=<compiler> cmake [options] ..
63-
# Build
64-
make -j4
65-
# Optionally, run the tests
66-
ctest --output-on-failure
67-
# Install
68-
[sudo] make install
146+
* Python 3.6 or higher (Only required for the install script)
147+
* Visual Studio 2019 with Clang support
148+
* Strawberry Perl
69149

70-
To build for the ROCm platform,``<compiler>`` should be set to ``hipcc``. When building for CUDA ``<compiler>`` should be set to the host compiler. If building for CUDA, then the location of ``nvcc`` may need to be passed explicitly using ``-DCMAKE_CUDA_COMPILER=<path-to-nvcc>`` if it is not on the path. Additionally, the directory where FindHIP.cmake is installed needs to be passed explicitly using ``-DCMAKE_MODULE_PATH``. By default, this file is installed in ``/opt/rocm/hip/cmake``.
71150

72-
The following configuration options are available, in addition to the built-in CMake options:
151+
To install support for rocRAND and HIP on Windows, use the ``rmake.py`` Python script as follows:
73152

74-
* ``BUILD_FORTRAN_WRAPPER`` controls whether to build the Fortran wrapper. Defaults to ``OFF``.
75-
* ``BUILD_TEST`` controls whether to build the rocRAND tests. Defaults to ``OFF``.
76-
* ``BUILD_BENCHMARK`` controls whether to build the rocRAND benchmarks. Defaults to ``OFF``.
77-
* ``BUILD_ADDRESS_SANITIZER`` controls whether to build with address sanitization enabled. Defaults to ``OFF``.
153+
.. code-block:: shell
78154
79-
To install rocRAND with a non-standard installation location of ROCm, pass ``-DCMAKE_PREFIX_PATH=</path/to/opt/rocm/>`` or set the environment variable ``ROCM_PATH`` to ``path/to/opt/rocm``.
155+
git clone https://github.com/ROCm/rocRAND.git
156+
cd rocRAND
157+
158+
# the -i option will install rocRAND to C:\hipSDK by default
159+
python rmake.py -i
160+
161+
# the -c option will build all clients including unit tests
162+
python rmake.py -c
163+
164+
Any existing GoogleTest library in the system (especially static GoogleTest libraries built with other compilers)
165+
might cause a build failure. If you encounter errors with the existing GoogleTest library or other dependencies,
166+
pass the ``DEPENDENCIES_FORCE_DOWNLOAD`` flag to CMake to help solve the problem.
167+
168+
To disable inline assembly optimizations in rocRAND for both the host library and the device functions provided in ``rocrand_kernel.h``,
169+
set the CMake option ``ENABLE_INLINE_ASM`` to ``OFF``.
80170

81171
Building the Python API wrapper
82-
-------------------------------
172+
===============================
173+
174+
This section provides the information required to build the rocRAND Python API wrapper.
83175

84176
Requirements
85-
^^^^^^^^^^^^
177+
--------------------
86178

87179
The rocRAND Python API Wrapper requires the following dependencies:
88180

89181
* rocRAND
90182
* Python 3.5
91183
* NumPy (will be installed automatically as a dependency if necessary)
92184

93-
Note: If rocRAND is built from sources but not installed or installed in
94-
non-standard directory, set the ``ROCRAND_PATH`` environment variable. For example::
185+
.. note::
186+
187+
If rocRAND is built from source but is either not installed or installed in a
188+
non-standard directory, set the ``ROCRAND_PATH`` environment variable
189+
to the library location. For example:
190+
191+
.. code-block:: shell
192+
193+
export ROCRAND_PATH=~/rocRAND/build/library/
194+
195+
Installation
196+
--------------------
95197

96-
export ROCRAND_PATH=~/rocRAND/build/library/
198+
The Python rocRAND module can be installed using ``pip``:
97199

98-
Installing
99-
^^^^^^^^^^
200+
.. code-block:: shell
100201
101-
The Python rocRAND module can be installed using pip::
202+
cd rocrand/python/rocrand
203+
pip install .
102204
103-
cd rocrand/python/rocrand
104-
pip install .
205+
The tests can be executed as follows:
105206

106-
The tests can be executed as follows::
207+
.. code-block:: shell
107208
108-
cd rocrand/python/rocrand
109-
python tests/rocrand_test.py
209+
cd rocrand/python/rocrand
210+
python tests/rocrand_test.py
110211

‎docs/sphinx/_toc.yml.in‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,28 @@ subtrees:
55
- caption: Install
66
entries:
77
- file: install/installing
8+
title: Installation guide
9+
810
- caption: Conceptual
911
entries:
1012
- file: conceptual/programmers-guide
13+
title: Programming guide
1114
- file: conceptual/curand-compatibility
1215
- file: conceptual/dynamic_ordering_configuration
16+
17+
- caption: Examples
18+
entries:
19+
- url: https://github.com/ROCm/rocRAND/tree/develop/python/rocrand/examples
20+
title: Examples
21+
1322
- caption: API reference
1423
entries:
1524
- file: api-reference/data-type-support
1625
- file: api-reference/cpp-api
1726
- file: api-reference/python-api
1827
- file: fortran-api-reference
1928
- file: doxygen/html/index
29+
2030
- caption: About
2131
entries:
2232
- file: license

0 commit comments

Comments
 (0)