diff --git a/docs/cpp-api.rst b/docs/cpp-api.rst new file mode 100644 index 0000000..0815eaa --- /dev/null +++ b/docs/cpp-api.rst @@ -0,0 +1,23 @@ +.. meta:: + :description: A wrapper library that allows you to easily port CUDA applications that use the cuRAND library to the HIP layer + :keywords: hipRAND, ROCm, library, API, tool + +.. _cpp-api: + +=================== +C/C++ API reference +=================== + +This document describes the hipRAND APIs available in C and C++. + +Device Functions +================ +.. doxygengroup:: hipranddevice + +C Host API +========== +.. doxygengroup:: hiprandhost + +C++ Host API Wrapper +==================== +.. doxygengroup:: hiprandhostcpp diff --git a/docs/cpp_api.rst b/docs/cpp_api.rst deleted file mode 100644 index cc3ab74..0000000 --- a/docs/cpp_api.rst +++ /dev/null @@ -1,17 +0,0 @@ -=================== -C/C++ API Reference -=================== - -This chapter describes the hipRAND C and C++ API. - -Device Functions -================ -.. doxygengroup:: hipranddevice - -C Host API -========== -.. doxygengroup:: hiprandhost - -C++ Host API Wrapper -==================== -.. doxygengroup:: hiprandhostcpp diff --git a/docs/data-type-support.rst b/docs/data-type-support.rst index cae7d23..fea922a 100644 --- a/docs/data-type-support.rst +++ b/docs/data-type-support.rst @@ -1,6 +1,13 @@ +.. meta:: + :description: A wrapper library that allows you to easily port CUDA applications that use the cuRAND library to the HIP layer + :keywords: hipRAND, ROCm, library, API, tool + +.. _data-type: + +==================== Data type support -****************************************** +==================== -hipRAND's data type support is matching cuRAND's data type support. On AMD hardware, the backend is provided by rocRAND. The detailed description, which includes a comparison to cuRAND's data type support, can be found at :doc:`rocRAND's data type support page.` +The data type support in hipRAND is similar to cuRAND. On AMD hardware, the backend is provided by rocRAND. To see the data type comparison between rocRAND and cuRAND, see `rocRAND's data type support `_ page. -You can find the ROCm data type support summary at :doc:`Supported data types in ROCm` +You can find the ROCm data type support summary at `Supported data types in ROCm `_. diff --git a/docs/index.rst b/docs/index.rst index 16ad98d..bf1e394 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,10 +1,35 @@ -================== -hipRAND User Guide -================== +.. meta:: + :description: A wrapper library that allows you to easily port CUDA applications that use the cuRAND library to the HIP layer + :keywords: hipRAND, ROCm, library, API, tool -Overview --------- +.. _index: -The hipRAND library is a wrapper library which allows users to easily port CUDA applications that use the cuRAND library to the HIP layer. In a ROCm environment hipRAND uses rocRAND, however in a CUDA environment cuRAND is used instead. +=========================== +hipRAND documentation +=========================== -hipRAND provides both C/C++ and Python API wrappers. +The hipRAND library is a wrapper library that allows you to easily port CUDA applications that use the cuRAND library to the HIP layer. hipRAND uses rocRAND in a ROCm environment and cuRAND in a CUDA environment. + +hipRAND provides C, C++, and Python API wrappers. + +You can access hipRAND code on our `GitHub repository `_. + +The documentation is structured as follows: + +.. grid:: 2 + :gutter: 3 + + .. grid-item-card:: Install + + * :ref:`installation` + + .. grid-item-card:: API reference + + * :ref:`data-type` + * :ref:`cpp-api` + * :ref:`python-api` + +To contribute to the documentation, refer to +`Contributing to ROCm `_. + +You can find licensing information on the `Licensing `_ page. diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..1d7b203 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,181 @@ +.. meta:: + :description: A wrapper library that allows you to easily port CUDA applications that use the cuRAND library to the HIP layer + :keywords: hipRAND, ROCm, library, API, tool + +.. _installation: + +============ +Installation +============ + +To install hipRAND, you can choose between the following two methods: + +- :ref:`Using prebuilt packages from the ROCm repositories ` +- :ref:`Building from source ` + +Both the methods are described below. + +.. _prebuilt-packages: + +Install using prebuilt packages +-------------------------------- + +To install the prebuilt hipRAND packages, you require a ROCm-enabled platform. For information on ROCm installation, see the `ROCm installation for Linux `_ page. After installing ROCm or enabling the ROCm repositories, you can install hipRAND using the system package manager. + +For Ubuntu and Debian: + +.. code-block:: shell + + sudo apt-get install hiprand + +For CentOS: + +.. code-block:: shell + + sudo yum install hiprand + +For SLES: + +.. code-block:: shell + + sudo dnf install hiprand + +This installs hipRAND in the ``/opt/rocm`` directory. + +.. _build-from-source: + +Build hipRAND from source +---------------------------- + +This section provides the information required to build hipRAND from source. + +Requirements +^^^^^^^^^^^^ + +To build hipRAND, CMake version 3.10 or later is required. + +Additionally, to build hipRAND for ROCm software, the following softwares are required: + +* `AMD ROCm Software `_ (version 5.0.0 or later). +* `rocRAND `_ + +To build hipRAND for the CUDA platform instead, the following softwares are required: + +* The CUDA toolkit +* cuRAND (included in the CUDA Toolkit) + +Obtaining sources +^^^^^^^^^^^^^^^^^ + +You can find the hipRAND sources in the `hipRAND GitHub Repository `_. Use the branch that matches the system-installed version of ROCm. For example, on a system with ROCm 5.4 installed, use the following command to obtain hipRAND sources: + +.. code-block:: shell + + git checkout -b release/rocm-rel-5.4 https://github.com/ROCm/hipRAND.git + +Building library +^^^^^^^^^^^^^^^^^^^^ + +After obtaining the sources and dependencies, build hipRAND for ROCm software using the installation script: + +.. code-block:: shell + + cd hipRAND + ./install --install + +This automatically builds all required dependencies, excluding Git and the requirements listed above, and installs the project to ``/opt/rocm`` if everything went well. See ``./install --help`` for further information. The clients, enabled by option ``--clients``, consist of the hipRAND tests and add the additional dependency of `googletest `_. + +Building with CMake +^^^^^^^^^^^^^^^^^^^ + +For a more elaborate installation process, build hipRAND manually using CMake. This enables certain configuration options that are not exposed to the ``./install`` script. In general, you can build hipRAND using CMake with the following configuration: + +.. code-block:: shell + + cd hipRAND; mkdir build; cd build + # Configure the project + CXX= cmake [options] .. + # Build + make -j$(nproc) + # Optionally, run the tests + ctest --output-on-failure + # Install + [sudo] make install + +Where ```` should be set to ``hipcc`` or ``amdclang`` on ROCm software or to a regular C++ compiler such as ``g++`` on a CUDA platform. The default build configuration is ``Release``. + +Here are the CMake options: + +* ``BUILD_WITH_LIB`` decides whether to build hipRAND with the rocRAND or cuRAND backend. If set to ``CUDA``, hipRAND is built using the cuRAND backend. Otherwise, the rocRAND backend is used. +* ``BUILD_FORTRAN_WRAPPER`` builds the Fortran wrapper when set to ``ON``. Defaults to ``OFF``. +* ``BUILD_TEST`` builds the hipRAND tests when set to ``ON``. Defaults to ``OFF``. +* ``BUILD_BENCHMARK`` builds the hipRAND benchmarks when set to ``ON``. Defaults to ``OFF``. +* ``BUILD_ADDRESS_SANITIZER`` builds with address sanitization enabled when set to ``ON``. Defaults to ``OFF``. +* ``ROCRAND_PATH`` specifies a rocRAND install other than the default system installed one. +* ``DOWNLOAD_ROCRAND`` downloads and installs rocRAND in the build directory when set to ``ON``. Defaults to ``OFF``. +* ``DEPENDENCIES_FORCE_DOWNLOAD`` downloads and builds the dependencies instead of using system-installed dependencies when set to ``ON``. Defaults to ``OFF``. + +If using ``ROCRAND_PATH`` or ``DOWNLOAD_ROCRAND`` when rocRAND is already installed in the default location in the system then, use ``CMAKE_NO_SYSTEM_FROM_IMPORTED=ON`` while configuring the project. +Failing to do so might resolve the rocRAND headers to the system-installed version instead of the specified version, leading to errors or missing functionalities. + +Common build errors +""""""""""""""""""""" + +* + .. code-block:: shell + + Could not find a package configuration file provided by "rocrand" with any of the following names: + + rocrandConfig.cmake + rocrand-config.cmake + + Solution: install `rocRAND `_. +* + .. code-block:: shell + + Could not find a package configuration file provided by "ROCM" with any of the following names: + + ROCMConfig.cmake + rocm-config.cmake + + Solution: install `ROCm CMake modules `_. + +Building Python API wrapper +------------------------------- + +This section provides information required to build the hipRAND Python API wrapper. + +Requirements +^^^^^^^^^^^^ + +The hipRAND Python API Wrapper requires the following dependencies: + +* hipRAND +* Python 3.5 +* NumPy (will be installed automatically as a dependency if necessary) + +.. note:: + + If hipRAND is built from sources but not installed or rather installed in a + non-standard directory, then set the ``ROCRAND_PATH`` or ``HIPRAND_PATH`` environment variable to the path containing ``libhiprand.so`` as shown below: + + .. code-block:: shell + + export HIPRAND_PATH=~/hipRAND/build/library/ + +Installation +^^^^^^^^^^^^^ + +To install Python hipRAND module using ``pip``: + +.. code-block:: shell + + cd hipRAND/python/hiprand + pip install . + +To execute the tests: + +.. code-block:: shell + + cd hipRAND/python/hiprand + python tests/hiprand_test.py diff --git a/docs/installing.rst b/docs/installing.rst deleted file mode 100644 index 52ac186..0000000 --- a/docs/installing.rst +++ /dev/null @@ -1,139 +0,0 @@ -============ -Installation -============ - -Introduction ------------- - -This chapter describes how to obtain hipRAND. 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 hipRAND from source. - -Prebuilt Packages ------------------ - -Installing the prebuilt hipRAND packages requires a ROCm-enabled platform. See the `ROCm documentation `_ for more information. After installing ROCm or enabling the ROCm repositories, hipRAND can be obtained using the system package manager. - -For Ubuntu and Debian: - -.. code-block:: shell - - sudo apt-get install hiprand - -For CentOS: - -.. code-block:: shell - - sudo yum install hiprand - -For SLES: - -.. code-block:: shell - - sudo dnf install hiprand - -This will install hipRAND into the ``/opt/rocm`` directory. - -Building hipRAND From Source ----------------------------- - -Requirements -^^^^^^^^^^^^ - -To build hipRAND, CMake version 3.10 or later is required. - -Additionally, to build hipRAND for ROCm software, the following software are required: - -* AMD ROCm Software (version 5.0.0 or later). -* `rocRAND `_ - -To build hipRAND for the CUDA platform instead, the following software is required: - -* The CUDA Toolkit -* cuRAND (included in the CUDA Toolkit) - -Obtaining Sources -^^^^^^^^^^^^^^^^^ - -The hipRAND sources are available from the `hipRAND GitHub Repository `_. Use the branch that matches the system-installed version of ROCm. For example on a system that has ROCm 5.4 installed, use the following command to obtain hipRAND sources: - -.. code-block:: shell - - git checkout -b release/rocm-rel-5.4 https://github.com/ROCm/hipRAND.git - -Building the Library -^^^^^^^^^^^^^^^^^^^^ - -After obtaining the sources and dependencies, hipRAND can be built for ROCm software using the installation script:: - -.. code-block:: shell - - cd hipRAND - ./install --install - -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. - -Building with CMake -^^^^^^^^^^^^^^^^^^^ - -For a more elaborate installation process, hipRAND can be built manually using CMake. This enables certain configuration options that are not exposed to the ``./install`` script. In general, hipRAND can be built using CMake by configuring as follows: - -.. code-block:: shell - - cd hipRAND; mkdir build; cd build - # Configure the project - CXX= cmake [options] .. - # Build - make -j$(nproc) - # Optionally, run the tests - ctest --output-on-failure - # Install - [sudo] make install - -Where ``>`` should be set to ``hipcc`` or ``amdclang`` on ROCm software, or to a regular C++ compiler such as ``g++`` on a CUDA platform. - -* ``BUILD_WITH_LIB`` controls whether to build hipRAND with the rocRAND or cuRAND backend. If set to ``CUDA``, hipRAND will be built using the cuRAND backend. Otherwise, the rocRAND backend will be used. -* ``BUILD_FORTRAN_WRAPPER`` controls whether to build the Fortran wrapper. Defaults to ``OFF``. -* ``BUILD_TEST`` controls whether to build the hipRAND tests. Defaults to ``OFF``. -* ``BUILD_BENCHMARK`` controls whether to build the hipRAND benchmarks. Defaults to ``OFF``. -* ``BUILD_ADDRESS_SANITIZER`` controls whether to build with address sanitization enabled. Defaults to ``OFF``. -* ``ROCRAND_PATH`` specifies a rocRAND install other than the default system installed one. -* ``DOWNLOAD_ROCRAND`` specifies that rocRAND will be downloaded and installed in the build directory. - -If using ``ROCRAND_PATH`` or ``DOWNLOAD_ROCRAND`` and rocRAND is also installed on the system in the default location then ``CMAKE_NO_SYSTEM_FROM_IMPORTED=ON`` should be passed -when configuring the project. -Otherwise the headers of rocRAND might be resolved to the system installed version instead of the specified version, leading to errors or missing functionality. - -Building the Python API Wrapper -------------------------------- - -Requirements -^^^^^^^^^^^^ - -The hipRAND Python API Wrapper requires the following dependencies: - -* hipRAND -* Python 3.5 -* NumPy (will be installed automatically as a dependency if necessary) - -Note: If hipRAND is built from sources but not installed or installed in -non-standard directory, set the ``ROCRAND_PATH`` or ``HIPRAND_PATH`` environment variable to the path containing ``libhiprand.so``. For example: - -.. code-block:: shell - - export HIPRAND_PATH=~/hipRAND/build/library/ - -Installing -^^^^^^^^^^ - -The Python hipRAND module can be installed using pip: - -.. code-block:: shell - - cd hipRAND/python/hiprand - pip install . - -The tests can be executed as follows: - -.. code-block:: shell - - cd hipRAND/python/hiprand - python tests/hiprand_test.py diff --git a/docs/python_api.rst b/docs/python-api.rst similarity index 58% rename from docs/python_api.rst rename to docs/python-api.rst index 6fc830f..72e5236 100644 --- a/docs/python_api.rst +++ b/docs/python-api.rst @@ -1,11 +1,16 @@ +.. meta:: + :description: A wrapper library that allows you to easily port CUDA applications that use the cuRAND library to the HIP layer + :keywords: hipRAND, ROCm, library, API, tool + +.. _python-api: + ==================== -Python API Reference +Python API reference ==================== -This chapter describes the hipRAND Python module API. +This document describes the hipRAND APIs in Python. -This wrapper has API similar to **pyculib.rand** -(http://pyculib.readthedocs.io/en/latest/curand.html). +The APIs in this wrapper are similar to `pyculib.rand `_. .. default-domain:: py .. py:currentmodule:: hiprand diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index ef0a0d6..89b2021 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -2,11 +2,14 @@ # These comments will also be removed. root: index subtrees: -- entries: - - file: installing +- caption: Install + entries: + - file: installation +- caption: API reference + entries: - file: data-type-support - - file: cpp_api - - file: python_api + - file: cpp-api + - file: python-api - caption: About entries: - file: license diff --git a/docs/sphinx/requirements.in b/docs/sphinx/requirements.in index ba804ab..175b386 100644 --- a/docs/sphinx/requirements.in +++ b/docs/sphinx/requirements.in @@ -1,2 +1,2 @@ -rocm-docs-core==0.38.1 +rocm-docs-core[api_reference]==1.1.2 numpy diff --git a/docs/sphinx/requirements.txt b/docs/sphinx/requirements.txt index 15756f6..f40e9f3 100644 --- a/docs/sphinx/requirements.txt +++ b/docs/sphinx/requirements.txt @@ -2,7 +2,7 @@ # This file is autogenerated by pip-compile with Python 3.10 # by the following command: # -# pip-compile --resolver=backtracking requirements.in +# pip-compile requirements.in # accessible-pygments==0.0.4 # via pydata-sphinx-theme @@ -39,11 +39,9 @@ docutils==0.21.2 # via # breathe # myst-parser - # pybtex-docutils # pydata-sphinx-theme # sphinx - # sphinxcontrib-bibtex -doxysphinx==3.3.7 +doxysphinx==3.3.8 # via rocm-docs-core fastjsonschema==2.19.1 # via rocm-docs-core @@ -59,8 +57,6 @@ jinja2==3.1.3 # via # myst-parser # sphinx -latexcodec==3.0.0 - # via pybtex libsass==0.22.0 # via doxysphinx lxml==4.9.4 @@ -75,22 +71,18 @@ mdit-py-plugins==0.4.0 # via myst-parser mdurl==0.1.2 # via markdown-it-py -mpire==2.10.1 +mpire==2.10.2 # via doxysphinx myst-parser==3.0.0 # via rocm-docs-core numpy==1.26.4 - # via -r requirements.in + # via + # -r requirements.in + # doxysphinx packaging==24.0 # via # pydata-sphinx-theme # sphinx -pybtex==0.24.0 - # via - # pybtex-docutils - # sphinxcontrib-bibtex -pybtex-docutils==1.0.3 - # via sphinxcontrib-bibtex pycparser==2.22 # via cffi pydata-sphinx-theme==0.15.2 @@ -116,17 +108,14 @@ pyparsing==3.1.2 pyyaml==6.0.1 # via # myst-parser - # pybtex # rocm-docs-core # sphinx-external-toc requests==2.31.0 # via # pygithub # sphinx -rocm-docs-core[api_reference]==1.1.0 +rocm-docs-core[api_reference]==1.1.2 # via -r requirements.in -six==1.16.0 - # via pybtex smmap==5.0.1 # via gitdb snowballstemmer==2.2.0 @@ -144,8 +133,6 @@ sphinx==7.3.7 # sphinx-design # sphinx-external-toc # sphinx-notfound-page - # sphinxcontrib-bibtex - # sphinxcontrib-moderncmakedomain sphinx-book-theme==1.1.2 # via rocm-docs-core sphinx-copybutton==0.5.2 @@ -158,23 +145,19 @@ sphinx-notfound-page==1.0.0 # via rocm-docs-core sphinxcontrib-applehelp==1.0.8 # via sphinx -sphinxcontrib-bibtex==2.6.2 - # via -r requirements.in sphinxcontrib-devhelp==1.0.6 # via sphinx sphinxcontrib-htmlhelp==2.0.5 # via sphinx sphinxcontrib-jsmath==1.0.1 # via sphinx -sphinxcontrib-moderncmakedomain==3.27.0 - # via -r requirements.in sphinxcontrib-qthelp==1.0.7 # via sphinx sphinxcontrib-serializinghtml==1.1.10 # via sphinx tomli==2.0.1 # via sphinx -tqdm==4.66.2 +tqdm==4.66.4 # via mpire typing-extensions==4.11.0 # via