diff --git a/.githooks/install b/.githooks/install new file mode 100755 index 00000000..cbb0569b --- /dev/null +++ b/.githooks/install @@ -0,0 +1,8 @@ +#!/usr/bin/env bash + +cd $(git rev-parse --git-dir) +cd hooks + +echo "Installing hooks..." +ln -s ../../.githooks/pre-commit pre-commit +echo "Done!" diff --git a/.githooks/pre-commit b/.githooks/pre-commit new file mode 100755 index 00000000..63690e77 --- /dev/null +++ b/.githooks/pre-commit @@ -0,0 +1,43 @@ +#!/bin/sh +# +# This pre-commit hook checks if any versions of clang-format +# are installed, and if so, uses the installed version to format +# the staged changes. + +base=clang-format-3.8 +format="" + +# Redirect output to stderr. +exec 1>&2 + + # check if clang-format is installed +type "$base" >/dev/null 2>&1 && format="$base" + +# no versions of clang-format are installed +if [ -z "$format" ] +then + echo "$base is not installed. Pre-commit hook will not be executed." + exit 0 +fi + +# Do everything from top - level +cd $(git rev-parse --show-toplevel) + +if git rev-parse --verify HEAD >/dev/null 2>&1 +then + against=HEAD +else + # Initial commit: diff against an empty tree object + against=4b825dc642cb6eb9a060e54bf8d69288fbee4904 +fi + +# do the formatting +for file in $(git diff-index --cached --name-only $against | grep -E '\.h$|\.hpp$|\.cpp$|\.cl$|\.h\.in$|\.hpp\.in$|\.cpp\.in$') +do + if [ -e "$file" ] + then + echo "$format $file" + "$format" -i -style=file "$file" + fi +done + diff --git a/.github/BUG_REPORT.md b/.github/BUG_REPORT.md new file mode 100644 index 00000000..972a5470 --- /dev/null +++ b/.github/BUG_REPORT.md @@ -0,0 +1,21 @@ +### What is the expected behavior +- + +### What actually happens +- + +### How to reproduce +- + +### Environment +| Hardware | description | +|-----|-----| +| GPU | device string | +| CPU | device string | + +| Software | version | +|-----|-----| +| ROCK | v0.0 | +| ROCR | v0.0 | +| HCC | v0.0 | +| Library | v0.0 | diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..88baf7d0 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,85 @@ + +## Contribution License Agreement +1. The code I am contributing is mine, and I have the right to license it. + +2. By submitting a pull request for this project I am granting you a license to distribute said code under the MIT License for the project. + +## How to contribute + +Our code contriubtion guidelines closely follows the model of [GitHub pull-requests](https://help.github.com/articles/using-pull-requests/). This repository follows the [git flow](http://nvie.com/posts/a-successful-git-branching-model/) workflow, which dictates a /master branch where releases are cut, and a /develop branch which serves as an integration branch for new code. + * A [git extention](https://github.com/nvie/gitflow) has been developed to ease the use of the 'git flow' methodology, but requires manual installation by the user. Refer to the projects wiki + +## Pull-request guidelines +* target the **develop** branch for integration +* ensure code builds successfully. +* do not break existing test cases +* new functionality will only be merged with new unit tests + * new unit tests should integrate within the existing [googletest framework](https://github.com/google/googletest/blob/master/googletest/docs/primer.md) + * tests must have good code coverage + * code must also have benchmark tests, and performance must approach the compute bound limit or memory bound limit. + +## StyleGuide +This project follows the [CPP Core guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md), with few modifications or additions noted below. All pull-requests should in good faith attempt to follow the guidelines stated therein, but we recognize that the content is lengthy. Below we list our primary concerns when reviewing pull-requests. + +### Interface +- All public APIs are C89 compatible; all other library code should use c++14 + - Our minimum supported compiler is clang 3.6 +- Avoid CamelCase + - This rule applies specifically to publicly visible APIs, but is also encouraged (not mandated) for internal code + +### Philosophy +- [P.2](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rp-Cplusplus): Write in ISO Standard C++ (especially to support windows, linux and macos plaforms ) +- [P.5](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rp-compile-time): Prefer compile-time checking to run-time checking + +### Implementation +- [SF.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rs-file-suffix): Use a .cpp suffix for code files and .h for interface files if your project doesn't already follow another convention + - We modify this rule: + - .h: C header files + - .hpp: C++ header files +- [SF.5](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rs-consistency): A .cpp file must include the .h file(s) that defines its interface +- [SF.7](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rs-using-directive): Don't put a using-directive in a header file +- [SF.8](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rs-guards): Use #include guards for all .h files +- [SF.21](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rs-unnamed): Don't use an unnamed (anonymous) namespace in a header +- [SL.10](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rsl-arrays): Prefer using STL array or vector instead of a C array +- [C.9](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rc-private): minimize exposure of members +- [F.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rf-single): Keep functions short and simple +- [F.21](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rf-out-multi): To return multiple 'out' values, prefer returning a tuple +- [R.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-raii): Manage resources automatically using RAII (this includes unique_ptr & shared_ptr) +- [ES.11](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-auto): use auto to avoid redundant repetition of type names +- [ES.20](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-always): Always initialize an object +- [ES.23](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-list): Prefer the {} initializer syntax +- [ES.49](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-casts-named): If you must use a cast, use a named cast +- [CP.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#S-concurrency): Assume that your code will run as part of a multi-threaded program +- [I.2](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Ri-global): Avoid global variables + +## Format +C and C++ code is formatted using clang-format. To format a file, use + +``` +clang-format-3.8 -style=file -i +``` + +To format all files, run the following script in rocSPARSE directory: + +``` +#!/bin/bash + +find . -iname '*.h' \ +-o -iname '*.hpp' \ +-o -iname '*.cpp' \ +-o -iname '*.h.in' \ +-o -iname '*.hpp.in' \ +-o -iname '*.cpp.in' \ +-o -iname '*.cl' \ +| grep -v 'build' \ +| xargs -n 1 -P 8 -I{} clang-format-3.8 -style=file -i {} +``` + + +Also, githooks can be installed to format the code per-commit: + +``` +./.githooks/install +``` + + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..194dc857 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,6 @@ +resolves #___ + +Summary of proposed changes: +- +- +- diff --git a/.gitignore b/.gitignore index f9bbf717..1300bd7a 100644 --- a/.gitignore +++ b/.gitignore @@ -37,3 +37,7 @@ tags # build-in-source directory build + +# doc directory +docBin +_build diff --git a/CMakeLists.txt b/CMakeLists.txt index 32a2e04f..e8492e02 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -41,8 +41,7 @@ list(APPEND CMAKE_MODULE_PATH include(cmake/SetToolchain.cmake) # rocSPARSE project -project(rocsparse VERSION 0.1.3.1 LANGUAGES CXX) -set(rocsparse_SOVERSION 0) +project(rocsparse LANGUAGES CXX) # Set a default build type if none was specified if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES) @@ -72,6 +71,10 @@ option(BUILD_VERBOSE "Output additional build information" OFF) # Dependencies include(cmake/Dependencies.cmake) +# Setup version +rocm_setup_version(VERSION 0.1.3.2 NO_GIT_TAG_VERSION) +set(rocsparse_SOVERSION 0) + # AMD targets set(AMDGPU_TARGETS gfx803;gfx900;gfx906 CACHE STRING "List of specific machine types for library to target") diff --git a/Jenkinsfile b/Jenkinsfile index bee15511..d7c95f8b 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -470,7 +470,7 @@ def build_pipeline( compiler_data compiler_args, docker_data docker_args, projec //}, rocm_ubuntu: { - node( 'docker && rocm && dkms') + node( 'docker && rocm19 && dkms') { def hcc_docker_args = new docker_data( from_image:'rocm/dev-ubuntu-16.04:1.9.0', diff --git a/README.md b/README.md index cf042b0d..c119a9b6 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,9 @@ # rocSPARSE rocSPARSE exposes a common interface that provides Basic Linear Algebra Subroutines for sparse computation implemented on top of AMD's Radeon Open Compute [ROCm][] runtime and toolchains. rocSPARSE is created using the [HIP][] programming language and optimized for AMD's latest discrete GPUs. +## Documentation +The latest rocSPARSE documentation and API description can be found [here][]. + ## Requirements * Git * CMake (3.5 or later) @@ -92,3 +95,4 @@ The [license file][] can be found in the main repository. [Boost]: https://www.boost.org/ [the issue tracker]: https://github.com/ROCmSoftwarePlatform/rocSPARSE/issues [license file]: https://github.com/ROCmSoftwarePlatform/rocSPARSE +[here]: https://rocsparse.readthedocs.io/en/develop/library.html diff --git a/clients/CMakeLists.txt b/clients/CMakeLists.txt index 64073834..ef7ef2b6 100644 --- a/clients/CMakeLists.txt +++ b/clients/CMakeLists.txt @@ -52,7 +52,7 @@ if(NOT TARGET rocsparse) endif() # Hip headers required of all clients; clients use hip to allocate device memory -find_package(hip REQUIRED CONFIG PATHS /opt/rocm) +find_package(HIP REQUIRED CONFIG PATHS /opt/rocm) if(BUILD_CLIENTS_SAMPLES) add_subdirectory(samples) diff --git a/cmake/Dependencies.cmake b/cmake/Dependencies.cmake index eea54d6d..bfad9650 100644 --- a/cmake/Dependencies.cmake +++ b/cmake/Dependencies.cmake @@ -37,7 +37,7 @@ if(HIP_PLATFORM STREQUAL "hcc") # Ignore hcc warning: argument unused during compilation: '-isystem /opt/rocm/hip/include' set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Wno-unused-command-line-argument") find_package(hcc REQUIRED CONFIG PATHS /opt/rocm) - find_package(hip REQUIRED CONFIG PATHS /opt/rocm) + find_package(HIP REQUIRED CONFIG PATHS /opt/rocm) elseif(HIP_PLATFORM STREQUAL "nvcc") set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Xcompiler -Wall") set(CMAKE_C_COMPILE_OPTIONS_PIC "-Xcompiler ${CMAKE_C_COMPILE_OPTIONS_PIC}" ) diff --git a/cmake/Verbose.cmake b/cmake/Verbose.cmake index 1d82d5dc..91f4bdca 100644 --- a/cmake/Verbose.cmake +++ b/cmake/Verbose.cmake @@ -21,7 +21,7 @@ # # ######################################################################## -message(STATUS "rocsparse_VERSION : ${rocsparse_VERSION}") +message(STATUS "rocsparse_VERSION : ${rocsparse_VERSION}") message(STATUS "\t==>CMAKE_BUILD_TYPE : ${CMAKE_BUILD_TYPE}") message(STATUS "\t==>BUILD_SHARED_LIBS : ${BUILD_SHARED_LIBS}") message(STATUS "\t==>CMAKE_INSTALL_PREFIX link : ${CMAKE_INSTALL_PREFIX}") diff --git a/docs/Doxyfile b/docs/Doxyfile index f3c64fa6..32e3231c 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -238,7 +238,7 @@ TAB_SIZE = 4 # "Side Effects:". You can put \n's in the value part of an alias to insert # newlines. -ALIASES = +ALIASES = # This tag can be used to specify a number of word-keyword mappings (TCL only). # A mapping has the form "name=value". For example adding "class=itcl::class" diff --git a/docs/source/allapi.rst b/docs/source/allapi.rst deleted file mode 100644 index 952df2dd..00000000 --- a/docs/source/allapi.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. toctree:: - :maxdepth: 4 - :caption: Contents: - -======= -All API -======= - -.. doxygenindex:: diff --git a/docs/source/api.rst b/docs/source/api.rst deleted file mode 100644 index 6550b29f..00000000 --- a/docs/source/api.rst +++ /dev/null @@ -1,209 +0,0 @@ -.. toctree:: - :maxdepth: 4 - :caption: Contents: - -=== -API -=== - -This section provides details of the library API. - -Types ------ - -There are few data structures that are internal to the library. The pointer types to these -structures are given below. The user would need to use these types to create handles and pass them -between different library functions. - -.. doxygentypedef:: rocsparse_handle - -.. doxygentypedef:: rocsparse_mat_descr - -.. doxygentypedef:: rocsparse_mat_info - -.. doxygentypedef:: rocsparse_hyb_mat - -Auxiliary Functions -------------------- - -The following functions deals with initialization and cleanup of the different types. - -.. doxygenfunction:: rocsparse_create_handle - -.. doxygenfunction:: rocsparse_destroy_handle - -.. doxygenfunction:: rocsparse_set_stream - -.. doxygenfunction:: rocsparse_get_stream - -.. doxygenfunction:: rocsparse_set_pointer_mode - -.. doxygenfunction:: rocsparse_get_pointer_mode - -.. doxygenfunction:: rocsparse_create_mat_descr - -.. doxygenfunction:: rocsparse_destroy_mat_descr - -.. doxygenfunction:: rocsparse_set_mat_index_base - -.. doxygenfunction:: rocsparse_get_mat_index_base - -.. doxygenfunction:: rocsparse_set_mat_type - -.. doxygenfunction:: rocsparse_get_mat_type - -.. doxygenfunction:: rocsparse_create_mat_info - -.. doxygenfunction:: rocsparse_destroy_mat_info - -.. doxygenfunction:: rocsparse_create_hyb_mat - -.. doxygenfunction:: rocsparse_destroy_hyb_mat - -Sparse Level 1 Functions ------------------------- - -This section describes all rocSPARSE level 1 sparse linear algebra functions. - -.. doxygenfunction:: rocsparse_saxpyi - -.. doxygenfunction:: rocsparse_daxpyi - -.. doxygenfunction:: rocsparse_sdoti - -.. doxygenfunction:: rocsparse_ddoti - -.. doxygenfunction:: rocsparse_sgthr - -.. doxygenfunction:: rocsparse_dgthr - -.. doxygenfunction:: rocsparse_sgthrz - -.. doxygenfunction:: rocsparse_dgthrz - -.. doxygenfunction:: rocsparse_sroti - -.. doxygenfunction:: rocsparse_droti - -.. doxygenfunction:: rocsparse_ssctr - -.. doxygenfunction:: rocsparse_dsctr - -Sparse Level 2 Functions ------------------------- - -.. doxygenfunction:: rocsparse_scoomv - -.. doxygenfunction:: rocsparse_dcoomv - -.. doxygenfunction:: rocsparse_csrmv_analysis - -.. doxygenfunction:: rocsparse_csrmv_clear - -.. doxygenfunction:: rocsparse_scsrmv - -.. doxygenfunction:: rocsparse_dcsrmv - -.. doxygenfunction:: rocsparse_csrsv_buffer_size - -.. doxygenfunction:: rocsparse_csrsv_analysis - -.. doxygenfunction:: rocsparse_scsrsv_solve - -.. doxygenfunction:: rocsparse_dcsrsv_solve - -.. doxygenfunction:: rocsparse_csrsv_zero_pivot - -.. doxygenfunction:: rocsparse_csrsv_clear - -.. doxygenfunction:: rocsparse_sellmv - -.. doxygenfunction:: rocsparse_dellmv - -.. doxygenfunction:: rocsparse_shybmv - -.. doxygenfunction:: rocsparse_dhybmv - -Sparse Level 3 Functions ------------------------- - -.. doxygenfunction:: rocsparse_scsrmm - -.. doxygenfunction:: rocsparse_dcsrmm - -Sparse Preconditioner Functions -------------------------------- - -.. doxygenfunction:: rocsparse_csrilu0_buffer_size - -.. doxygenfunction:: rocsparse_csrilu0_analysis - -.. doxygenfunction:: rocsparse_scsrilu0 - -.. doxygenfunction:: rocsparse_dcsrilu0 - -.. doxygenfunction:: rocsparse_csrilu0_zero_pivot - -.. doxygenfunction:: rocsparse_csrilu0_clear - -Sparse Conversion Functions ---------------------------- - -.. doxygenfunction:: rocsparse_csr2coo - -.. doxygenfunction:: rocsparse_coo2csr - -.. doxygenfunction:: rocsparse_csr2csc_buffer_size - -.. doxygenfunction:: rocsparse_scsr2csc - -.. doxygenfunction:: rocsparse_dcsr2csc - -.. doxygenfunction:: rocsparse_csr2ell_width - -.. doxygenfunction:: rocsparse_scsr2ell - -.. doxygenfunction:: rocsparse_dcsr2ell - -.. doxygenfunction:: rocsparse_ell2csr_nnz - -.. doxygenfunction:: rocsparse_sell2csr - -.. doxygenfunction:: rocsparse_dell2csr - -.. doxygenfunction:: rocsparse_scsr2hyb - -.. doxygenfunction:: rocsparse_dcsr2hyb - -.. doxygenfunction:: rocsparse_create_identity_permutation - -.. doxygenfunction:: rocsparse_csrsort_buffer_size - -.. doxygenfunction:: rocsparse_csrsort - -.. doxygenfunction:: rocsparse_coosort_buffer_size - -.. doxygenfunction:: rocsparse_coosort_by_row - -.. doxygenfunction:: rocsparse_coosort_by_column - -Enumerations ------------- - -This section provides all the enumerations used. - -.. doxygenenum:: rocsparse_action - -.. doxygenenum:: rocsparse_hyb_partition - -.. doxygenenum:: rocsparse_index_base - -.. doxygenenum:: rocsparse_layer_mode - -.. doxygenenum:: rocsparse_matrix_type - -.. doxygenenum:: rocsparse_operation - -.. doxygenenum:: rocsparse_pointer_mode - -.. doxygenenum:: rocsparse_status diff --git a/docs/source/index.rst b/docs/source/index.rst index 4d9d4a9d..13293442 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -11,8 +11,6 @@ Welcome to rocSPARSE's documentation! :caption: Contents: library - api - allapi Indices and tables ================== diff --git a/docs/source/library.rst b/docs/source/library.rst index 95a4c061..b4ebcd40 100644 --- a/docs/source/library.rst +++ b/docs/source/library.rst @@ -13,20 +13,24 @@ rocSPARSE Introduction ------------ -rocSPARSE is a library that contains basic linear algebra subroutines for sparse matrices and vectors written in HiP for GPU devices. It is designed to be used from C and C++ code. The functionality of rocSPARSE is organized in in the following categories: +rocSPARSE is a library that contains basic linear algebra subroutines for sparse matrices and vectors written in HiP for GPU devices. It is designed to be used from C and C++ code. The functionality of rocSPARSE is organized in the following categories: -* :ref:`rocsparse_auxiliary_functions` describe available helper functions that are required for subsequent library calls. -* :ref:`rocsparse_level1_functions` describe operations between a vector in sparse format and a vector in dense format. -* :ref:`rocsparse_level2_functions` describe operations between a matrix in sparse format and a vector in dense format. -* :ref:`rocsparse_level3_functions` describe operations between a matrix in sparse format and multiple vectors in dense format. -* :ref:`rocsparse_precond_functions` describe manipulations on a matrix in sparse format to obtain a preconditioner. -* :ref:`rocsparse_conversion_functions` describe operations on a matrix in sparse format to obtain a different matrix format. +* :ref:`rocsparse_auxiliary_functions_` describe available helper functions that are required for subsequent library calls. +* :ref:`rocsparse_level1_functions_` describe operations between a vector in sparse format and a vector in dense format. +* :ref:`rocsparse_level2_functions_` describe operations between a matrix in sparse format and a vector in dense format. +* :ref:`rocsparse_level3_functions_` describe operations between a matrix in sparse format and multiple vectors in dense format. +* :ref:`rocsparse_precond_functions_` describe manipulations on a matrix in sparse format to obtain a preconditioner. +* :ref:`rocsparse_conversion_functions_` describe operations on a matrix in sparse format to obtain a different matrix format. The code is open and hosted here: https://github.com/ROCmSoftwarePlatform/rocSPARSE Device and Stream Management ***************************** -:cpp:func:`hipSetDevice` and :cpp:func:`hipGetDevice` are HIP device management APIs. They are NOT part of the rocSPARSE API. +*hipSetDevice()* and *hipGetDevice()* are HIP device management APIs. They are NOT part of the rocSPARSE API. + +Asynchronous Execution +`````````````````````` +All rocSPARSE library functions, unless otherwise stated, are non blocking and executed asynchronously with respect to the host. They may return before the actual computation has finished. To force synchronization, *hipDeviceSynchronize()* or *hipStreamSynchronize()* can be used. This will ensure that all previously executed rocSPARSE functions on the device / this particular stream have completed. HIP Device Management `````````````````````` @@ -34,17 +38,17 @@ Before a HIP kernel invocation, users need to call *hipSetDevice()* to set a dev The above is a HIP (and CUDA) device management approach and has nothing to do with rocSPARSE. rocSPARSE honors the approach above and assumes users have already set the device before a rocSPARSE routine call. -Once users set the device, they create a handle with :ref:`rocsparse_create_handle`. +Once users set the device, they create a handle with :ref:`rocsparse_create_handle_`. Subsequent rocSPARSE routines take this handle as an input parameter. rocSPARSE ONLY queries (by *hipGetDevice()*) the user's device; rocSPARSE does NOT set the device for users. If rocSPARSE does not see a valid device, it returns an error message. It is the users' responsibility to provide a valid device to rocSPARSE and ensure the device safety. -Users CANNOT switch devices between :ref:`rocsparse_create_handle` and :ref:`rocsparse_destroy_handle`. If users want to change device, they must destroy the current handle and create another rocSPARSE handle. +Users CANNOT switch devices between :ref:`rocsparse_create_handle_` and :ref:`rocsparse_destroy_handle_`. If users want to change device, they must destroy the current handle and create another rocSPARSE handle. HIP Stream Management `````````````````````` HIP kernels are always launched in a queue (also known as stream). -If users do not explicitly specify a stream, the system provides a default stream, maintained by the system. Users cannot create or destroy the default stream. However, users can freely create new streams (with *hipStreamCreate()*) and bind it to the rocSPARSE handle using :ref:`rocsparse_set_stream`. HIP kernels are invoked in rocSPARSE routines. The rocSPARSE handle is always associated with a stream, and rocSPARSE passes its stream to the kernels inside the routine. One rocSPARSE routine only takes one stream in a single invocation. If users create a stream, they are responsible for destroying it. +If users do not explicitly specify a stream, the system provides a default stream, maintained by the system. Users cannot create or destroy the default stream. However, users can freely create new streams (with *hipStreamCreate()*) and bind it to the rocSPARSE handle using :ref:`rocsparse_set_stream_`. HIP kernels are invoked in rocSPARSE routines. The rocSPARSE handle is always associated with a stream, and rocSPARSE passes its stream to the kernels inside the routine. One rocSPARSE routine only takes one stream in a single invocation. If users create a stream, they are responsible for destroying it. Multiple Streams and Multiple Devices `````````````````````````````````````` @@ -392,136 +396,101 @@ coo_row_ind array of ``nnz`` elements containing the COO part row indices (integ coo_col_ind array of ``nnz`` elements containing the COO part column indices (integer). =========== ========================================================================================= -The HYB format is a combination of the ELL and COO sparse matrix formats. Typically, the regular part of the matrix is stored in ELL storage format, and the irregular part of the matrix is stored in COO storage format. Three different partitioning schemes can be applied when converting a CSR matrix to a matrix in HYB storage format. For further details on the partitioning schemes, see :ref:`rocsparse_hyb_partition`. +The HYB format is a combination of the ELL and COO sparse matrix formats. Typically, the regular part of the matrix is stored in ELL storage format, and the irregular part of the matrix is stored in COO storage format. Three different partitioning schemes can be applied when converting a CSR matrix to a matrix in HYB storage format. For further details on the partitioning schemes, see :ref:`rocsparse_hyb_partition_`. Types ----- -.. _rocsparse_handle: - rocsparse_handle ***************** -The rocSPARSE handle is a structure holding the rocSPARSE library context. It must be initialized using :ref:`rocsparse_create_handle` and the returned handle must be passed to all subsequent library function calls. It should be destroyed at the end using :ref:`rocsparse_destroy_handle`. -.. _rocsparse_mat_descr: +.. doxygentypedef:: rocsparse_handle rocsparse_mat_descr ******************** -The rocSPARSE matrix descriptor is a structure holding all properties of a matrix. It must be initialized using :ref:`rocsparse_create_mat_descr` and the returned descriptor must be passed to all subsequent library calls that involve the matrix. It should be destroyed at the end using :ref:`rocsparse_destroy_mat_descr`. -.. _rocsparse_mat_info: +.. doxygentypedef:: rocsparse_mat_descr + + +.. _rocsparse_mat_info_: rocsparse_mat_info ******************* -The rocSPARSE matrix info is a structure holding all matrix information that is gathered during analysis routines. It must be initialized using :ref:`rocsparse_create_mat_info` and the returned info structure must be passed to all subsequent library calls that require additional matrix information. It should be destroyed at the end using :ref:`rocsparse_destroy_mat_info`. -.. _rocsparse_hyb_mat: +.. doxygentypedef:: rocsparse_mat_info rocsparse_hyb_mat ****************** -The rocSPARSE HYB matrix structure holds the HYB matrix. It must be initialized using :ref:`rocsparse_create_hyb_mat` and the returned HYB matrix must be passed to all subsequent library calls that involve the matrix. It should be destroyed at the end using :ref:`rocsparse_destroy_hyb_mat`. For more details on the HYB format, see :ref:`HYB storage format`. -.. _rocsparse_action: +.. doxygentypedef:: rocsparse_hyb_mat + +For more details on the HYB format, see :ref:`HYB storage format`. rocsparse_action ***************** -The rocSPARSE action indicates whether the operation is performed on the full matrix, or only on the sparsity pattern of the matrix. -========================= ==== -rocsparse_action_numeric operate on data and indices. -rocsparse_action_symbolic operate only on indices. -========================= ==== +.. doxygenenum:: rocsparse_action -.. _rocsparse_hyb_partition: +.. _rocsparse_hyb_partition_: rocsparse_hyb_partition ************************ -The rocSPARSE hyb partition type indicates how the hybrid format partitioning between COO and ELL storage formats is performed. - -============================ ==== -rocsparse_hyb_partition_auto automatically decide on ELL non-zero elements per row (recommended). -rocsparse_hyb_partition_user user given ELL non-zero elements per row. -rocsparse_hyb_partition_max maximum ELL non-zero elements per row, COO part is empty. -============================ ==== -.. _rocsparse_index_base: +.. doxygenenum:: rocsparse_hyb_partition rocsparse_index_base ********************* -The rocSPARSE index base indicates the index base of the given indices. -========================= =========================================== -rocsparse_index_base_zero zero index base (e.g. indices start with 0) -rocsparse_index_base_one one index base (e.g. indices start with 1) -========================= =========================================== +.. doxygenenum:: rocsparse_index_base -.. _rocsparse_layer_mode: +.. _rocsparse_layer_mode_: -rocsparse_layer_mode -********************* -The rocSPARSE layer mode bit mask indicates the logging characteristics. See :ref:`rocsparse_logging` for more informations. +rocsparse_matrix_type +********************** -============================== ============================== -rocsparse_layer_mode_none layer is not active. -rocsparse_layer_mode_log_trace layer is in logging mode. -rocsparse_layer_mode_log_bench layer is in benchmarking mode. -============================== ============================== +.. doxygenenum:: rocsparse_matrix_type -.. _rocsparse_matrix_type: +rocsparse_fill_mode +******************* -rocsparse_matrix_type -********************** -The rocSPARSE matrix type indices the type of the given matrix. +.. doxygenenum:: rocsparse_fill_mode -================================ ====================== -rocsparse_matrix_type_general general matrix type -rocsparse_matrix_type_symmetric symmetric matrix type -rocsparse_matrix_type_hermitian hermitian matrix type -rocsparse_matrix_type_triangular triangular matrix type -================================ ====================== +rocsparse_diag_type +******************* -.. _rocsparse_operation: +.. doxygenenum:: rocsparse_diag_type rocsparse_operation ******************** -The rocSPARSE operation indicates the operation performed with the given matrix. -======================================= ================================== -rocsparse_operation_none non transposed operation mode -rocsparse_operation_transpose transpose operation mode -rocsparse_operation_conjugate_transpose conjugate transpose operation mode -======================================= ================================== - -.. _rocsparse_pointer_mode: +.. doxygenenum:: rocsparse_operation rocsparse_pointer_mode *********************** -The rocSPARSE pointer mode indicates whether scalar values are passed by reference on the host or device. The pointer mode can be changed by :ref:`rocsparse_set_pointer_mode`. The currently used pointer mode can be obtained by :ref:`rocsparse_get_pointer_mode`. -The following table lists the available pointer modes. +.. doxygenenum:: rocsparse_pointer_mode -============================= ==================================================== -rocsparse_pointer_mode_host scalar values are passed by reference on the host. -rocsparse_pointer_mode_device scalar values are passed by reference on the device. -============================= ==================================================== +rocsparse_analysis_policy +************************* + +.. doxygenenum:: rocsparse_analysis_policy + +rocsparse_solve_policy +********************** -.. _rocsparse_status: +.. doxygenenum:: rocsparse_solve_policy + +rocsparse_layer_mode +********************* + +.. doxygenenum:: rocsparse_layer_mode + +For more details on logging, see :ref:`rocsparse_logging`. rocsparse_status ***************** -This is a list of the status types that are used by the rocSPARSE library. - -================================ ============================================ -rocsparse_status_success success. -rocsparse_status_invalid_handle handle not initialized, invalid or ``NULL``. -rocsparse_status_not_implemented function is not implemented. -rocsparse_status_invalid_pointer invalid pointer parameter. -rocsparse_status_invalid_size invalid size parameter. -rocsparse_status_memory_error failed memory allocation, copy or dealloc. -rocsparse_status_internal_error other internal library failure. -rocsparse_status_invalid_value invalid value parameter. -rocsparse_status_arch_mismatch device is not supported. -================================ ============================================ + +.. doxygenenum:: rocsparse_status .. _rocsparse_logging: @@ -529,7 +498,7 @@ Logging ------- Three different environment variables can be set to enable logging in rocSPARSE: ``ROCSPARSE_LAYER``, ``ROCSPARSE_LOG_TRACE_PATH`` and ``ROCSPARSE_LOG_BENCH_PATH``. -``ROCSPARSE_LAYER`` is a bit mask, where several logging modes (:ref:`rocsparse_layer_mode`) can be combined as follows: +``ROCSPARSE_LAYER`` is a bit mask, where several logging modes (:ref:`rocsparse_layer_mode_`) can be combined as follows: ================================ =========================================== ``ROCSPARSE_LAYER`` unset logging is disabled. @@ -544,2344 +513,408 @@ If the user sets the environment variable ``ROCSPARSE_LOG_TRACE_PATH`` to the fu Note that performance will degrade when logging is enabled. By default, the environment variable ``ROCSPARSE_LAYER`` is unset and logging is disabled. -.. _rocsparse_auxiliary_functions: +.. _rocsparse_auxiliary_functions_: Sparse Auxiliary Functions -------------------------- -This section describes all rocSPARSE auxiliary functions. -.. _rocsparse_create_handle: +This module holds all sparse auxiliary functions. -rocsparse_create_handle() -************************** -.. code-block:: c +The functions that are contained in the auxiliary module describe all available helper functions that are required for subsequent library calls. - rocsparse_status - rocsparse_create_handle(rocsparse_handle* handle); +.. _rocsparse_create_handle_: -*rocsparse_create_handle()* creates the rocSPARSE library context. It must be initialized before any other rocSPARSE API function is invoked and must be passed to all subsequent library function calls. The handle should be destroyed at the end using :ref:`rocsparse_destroy_handle`. - -====== =========================================================== -Output -====== =========================================================== -handle the pointer to the handle to the rocSPARSE library context. -====== =========================================================== +rocsparse_create_handle() +************************** -=============================== =============================================== -Status Returned -=============================== =============================================== -rocsparse_status_success the initialization succeeded. -rocsparse_status_invalid_handle ``handle`` pointer is invalid. -rocsparse_status_internal_error an internal error occurred. -=============================== =============================================== +.. doxygenfunction:: rocsparse_create_handle -.. _rocsparse_destroy_handle: +.. _rocsparse_destroy_handle_: rocsparse_destroy_handle() *************************** -.. code-block:: c - - rocsparse_status - rocsparse_destroy_handle(rocsparse_handle handle); - -*rocsparse_destroy_handle()* destroys the rocSPARSE library context. -====== ============================================ -Input -====== ============================================ -handle the handle to the rocSPARSE library context. -====== ============================================ +.. doxygenfunction:: rocsparse_destroy_handle -=============================== =============================================== -Status Returned -=============================== =============================================== -rocsparse_status_success the initialization succeeded. -rocsparse_status_internal_error an internal error occurred. -=============================== =============================================== - -.. _rocsparse_set_stream: +.. _rocsparse_set_stream_: rocsparse_set_stream() *********************** -.. code-block:: c - - rocsparse_status - rocsparse_set_stream(rocsparse_handle handle, - hipStream_t stream); - -*rocsparse_set_stream()* specifies the stream to be used by the rocSPARSE library context and all subsequent function calls. -====== ======================================================= -Input -====== ======================================================= -handle the handle to the rocSPARSE library context. -stream the stream to be used by the rocSPARSE library context. -====== ======================================================= - -================================ ============================= -Status Returned -================================ ============================= -rocsparse_status_success the initialization succeeded. -rocsparse_status_invalid_handle the library context was not initialized. -================================ ============================= +.. doxygenfunction:: rocsparse_set_stream rocsparse_get_stream() *********************** -.. code-block:: c - - rocsparse_status - rocsparse_get_stream(rocsparse_handle handle, - hipStream_t* stream); - -*rocsparse_get_stream()* gets the rocSPARSE library context stream which is currently used for all subsequent function calls. -====== ============================================ -Input -====== ============================================ -handle the handle to the rocSPARSE library context. -====== ============================================ - -====== =========================================================== -Output -====== =========================================================== -stream the stream currently used by the rocSPARSE library context. -====== =========================================================== - -================================ =============================================== -Status Returned -================================ =============================================== -rocsparse_status_success the initialization succeeded. -rocsparse_status_invalid_handle the library context was not initialized. -================================ =============================================== - -.. _rocsparse_set_pointer_mode: +.. doxygenfunction:: rocsparse_get_stream rocsparse_set_pointer_mode() ***************************** -.. code-block:: c - - rocsparse_status - rocsparse_set_pointer_mode(rocsparse_handle handle, - rocsparse_pointer_mode pointer_mode); - -*rocsparse_set_pointer_mode()* specifies the pointer mode to be used by the rocSPARSE library context and all subsequent function calls. By default, all values are passed by reference on the host. Valid pointer modes are ``rocsparse_pointer_mode_host`` or ``rocsparse_pointer_mode_device``. - -============ ============================================================= -Input -============ ============================================================= -handle the handle to the rocSPARSE library context. -pointer_mode the pointer mode to be used by the rocSPARSE library context. -============ ============================================================= - -================================ ============================= -Status Returned -================================ ============================= -rocsparse_status_success the initialization succeeded. -rocsparse_status_invalid_handle the library context was not initialized. -================================ ============================= -.. _rocsparse_get_pointer_mode: +.. doxygenfunction:: rocsparse_set_pointer_mode rocsparse_get_pointer_mode() ***************************** -.. code-block:: c - rocsparse_status - rocsparse_get_pointer_mode(rocsparse_handle handle, - rocsparse_pointer_mode* pointer_mode); - -*rocsparse_get_pointer_mode()* gets the rocSPARSE library context pointer mode which is currently used for all subsequent function calls. - -====== ============================================ -Input -====== ============================================ -handle the handle to the rocSPARSE library context. -====== ============================================ - -============ ========================================================================= -Output -============ ========================================================================= -pointer_mode the pointer mode that is currently used by the rocSPARSE library context. -============ ========================================================================= - -================================ =============================================== -Status Returned -================================ =============================================== -rocsparse_status_success the initialization succeeded. -rocsparse_status_invalid_handle the library context was not initialized. -================================ =============================================== +.. doxygenfunction:: rocsparse_get_pointer_mode rocsparse_get_version() ************************ -.. code-block:: c - - rocsparse_status - rocsparse_get_version(rocsparse_handle handle, - rocsparse_int* version); - -*rocsparse_get_version()* gets the rocSPARSE library version number. -====== ============================================ -Input -====== ============================================ -handle the handle to the rocSPARSE library context. -====== ============================================ - -======= ============================================ -Output -======= ============================================ -version the version number of the rocSPARSE library. -======= ============================================ - -================================ =============================================== -Status Returned -================================ =============================================== -rocsparse_status_success the initialization succeeded. -rocsparse_status_invalid_handle the library context was not initialized. -================================ =============================================== - -.. _rocsparse_create_mat_descr: +.. doxygenfunction:: rocsparse_get_version rocsparse_create_mat_descr() ***************************** -.. code-block:: c - - rocsparse_status - rocsparse_create_mat_descr(rocsparse_mat_descr* descr); - -*rocsparse_create_mat_descr()* creates the matrix descriptor. It initializes ``rocsparse_matrix_type`` to ``rocsparse_matrix_type_general`` and ``rocsparse_index_base`` to ``rocsparse_index_base_zero``. It should be destroyed at the end using :ref:`rocsparse_destroy_mat_descr`. - -====== ===================================== -Output -====== ===================================== -descr the pointer to the matrix descriptor. -====== ===================================== - -================================ =============================================== -Status Returned -================================ =============================================== -rocsparse_status_success the initialization succeeded. -rocsparse_status_invalid_pointer ``descr`` pointer is invalid. -================================ =============================================== -.. _rocsparse_destroy_mat_descr: +.. doxygenfunction:: rocsparse_create_mat_descr rocsparse_destroy_mat_descr() ****************************** -.. code-block:: c - rocsparse_status - rocsparse_destroy_mat_descr(rocsparse_mat_descr descr); +.. doxygenfunction:: rocsparse_destroy_mat_descr -*rocsparse_destroy_mat_descr()* destroys the matrix descriptor. - -===== ====================== -Input -===== ====================== -descr the matrix descriptor. -===== ====================== +rocsparse_copy_mat_descr() +************************** -================================ =============================================== -Status Returned -================================ =============================================== -rocsparse_status_success the initialization succeeded. -================================ =============================================== +.. doxygenfunction:: rocsparse_copy_mat_descr rocsparse_set_mat_index_base() ******************************* -.. code-block:: c - - rocsparse_status - rocsparse_set_mat_index_base(rocsparse_mat_descr descr, - rocsparse_index_base base); -*rocsparse_set_mat_index_base()* sets the index base of the matrix descriptor. Valid index bases are ``rocsparse_index_base_zero`` or ``rocsparse_index_base_one``. - -===== ============================================================================================ -Input -===== ============================================================================================ -descr the matrix descriptor. -base the matrix index base, can be ``rocsparse_index_base_zero`` or ``rocsparse_index_base_one``. -===== ============================================================================================ - -================================ =============================================== -Status Returned -================================ =============================================== -rocsparse_status_success the initialization succeeded. -rocsparse_status_invalid_pointer ``descr`` pointer is invalid. -rocsparse_status_invalid_value ``base`` is invalid. -================================ =============================================== +.. doxygenfunction:: rocsparse_set_mat_index_base rocsparse_get_mat_index_base() ******************************* -.. code-block:: c - - rocsparse_index_base - rocsparse_get_mat_index_base(const rocsparse_mat_descr descr); -*rocsparse_get_mat_index_base()* returns the index base of the matrix descriptor. - -===== ====================== -Input -===== ====================== -descr the matrix descriptor. -===== ====================== +.. doxygenfunction:: rocsparse_get_mat_index_base rocsparse_set_mat_type() ************************* -.. code-block:: c - - rocsparse_status - rocsparse_set_mat_type(rocsparse_mat_descr descr, - rocsparse_matrix_type type); - -*rocsparse_set_mat_type()* sets the matrix type of the matrix descriptor. Valid matrix types are ``rocsparse_matrix_type_general``, ``rocsparse_matrix_type_symmetric``, ``rocsparse_matrix_type_hermitian`` or ``rocsparse_matrix_type_triangular``. - -===== ========================================================================== -Input -===== ========================================================================== -descr the matrix descriptor. -type the matrix type, can be ``rocsparse_matrix_type_general``, |br| ``rocsparse_matrix_type_symmetric``, ``rocsparse_matrix_type_hermitian`` or |br| ``rocsparse_matrix_type_triangular``. -===== ========================================================================== -================================ =============================================== -Status Returned -================================ =============================================== -rocsparse_status_success the initialization succeeded. -rocsparse_status_invalid_pointer ``descr`` pointer is invalid. -rocsparse_status_invalid_value ``type`` is invalid. -================================ =============================================== +.. doxygenfunction:: rocsparse_set_mat_type rocsparse_get_mat_type() ************************* -.. code-block:: c - - rocsparse_matrix_type - rocsparse_get_mat_type(const rocsparse_mat_descr descr); - -*rocsparse_get_mat_type()* returns the matrix type of the matrix descriptor. - -===== ==================================== -Input -===== ==================================== -descr the matrix descriptor. -===== ==================================== -.. _rocsparse_create_mat_info: +.. doxygenfunction:: rocsparse_get_mat_type -rocsparse_create_mat_info() -**************************** -.. code-block:: c - - rocsparse_status - rocsparse_create_mat_info(rocsparse_mat_info* info); - -*rocsparse_create_mat_info()* creates a structure that holds the matrix info data that is gathered during the analysis routines available. It should be destroyed at the end using :ref:`rocsparse_destroy_mat_info`. +rocsparse_set_mat_fill_mode() +***************************** -====== ================================= -Output -====== ================================= -info the pointer to the info structure. -====== ================================= +.. doxygenfunction:: rocsparse_set_mat_fill_mode -================================ =============================================== -Status Returned -================================ =============================================== -rocsparse_status_success the initialization succeeded. -rocsparse_status_invalid_pointer ``info`` pointer is invalid. -================================ =============================================== +rocsparse_get_mat_fill_mode() +***************************** -.. _rocsparse_destroy_mat_info: +.. doxygenfunction:: rocsparse_get_mat_fill_mode -rocsparse_destroy_mat_info() +rocsparse_set_mat_diag_type() ***************************** -.. code-block:: c - - rocsparse_status - rocsparse_destroy_mat_info(rocsparse_mat_info info); -*rocsparse_destroy_mat_info()* destroys the info structure. +.. doxygenfunction:: rocsparse_set_mat_diag_type -===== =================== -Input -===== =================== -info the info structure. -===== =================== +rocsparse_get_mat_diag_type() +***************************** -================================ =============================================== -Status Returned -================================ =============================================== -rocsparse_status_success the initialization succeeded. -rocsparse_status_invalid_pointer ``info`` pointer is invalid. -rocsparse_status_internal_error an internal error occurred. -================================ =============================================== +.. doxygenfunction:: rocsparse_get_mat_diag_type -.. _rocsparse_create_hyb_mat: +.. _rocsparse_create_hyb_mat_: rocsparse_create_hyb_mat() *************************** -.. code-block:: c - - rocsparse_status - rocsparse_create_hyb_mat(rocsparse_hyb_mat* hyb); - -*rocsparse_create_hyb_mat()* creates a structure that holds the matrix in HYB storage format. It should be destroyed at the end using :ref:`rocsparse_destroy_hyb_mat`. - -====== ================================= -Output -====== ================================= -hyb the pointer to the hybrid matrix. -====== ================================= - -================================ =============================================== -Status Returned -================================ =============================================== -rocsparse_status_success the initialization succeeded. -rocsparse_status_invalid_pointer ``hyb`` pointer is invalid. -================================ =============================================== -.. _rocsparse_destroy_hyb_mat: +.. doxygenfunction:: rocsparse_create_hyb_mat rocsparse_destroy_hyb_mat() **************************** -.. code-block:: c - rocsparse_status - rocsparse_destroy_hyb_mat(rocsparse_hyb_mat hyb); +.. doxygenfunction:: rocsparse_destroy_hyb_mat -*rocsparse_destroy_hyb_mat()* destroys the HYB structure. +rocsparse_create_mat_info() +*************************** + +.. doxygenfunction:: rocsparse_create_mat_info -===== ================== -Input -===== ================== -hyb the hybrid matrix. -===== ================== +.. _rocsparse_destroy_mat_info_: + +rocsparse_destroy_mat_info() +***************************** -================================ =============================================== -Status Returned -================================ =============================================== -rocsparse_status_success the initialization succeeded. -rocsparse_status_invalid_pointer ``hyb`` pointer is invalid. -rocsparse_status_internal_error an internal error occurred. -================================ =============================================== +.. doxygenfunction:: rocsparse_destroy_mat_info -.. _rocsparse_level1_functions: +.. _rocsparse_level1_functions_: Sparse Level 1 Functions ------------------------ -This section describes all rocSPARSE level 1 sparse linear algebra functions. +The sparse level 1 routines describe operations between a vector in sparse format and a vector in dense format. This section describes all rocSPARSE level 1 sparse linear algebra functions. rocsparse_axpyi() -********************* -.. code-block:: c - - rocsparse_status - rocsparse_saxpyi(rocsparse_handle handle, - rocsparse_int nnz, - const float* alpha, - const float* x_val, - const rocsparse_int* x_ind, - float* y, - rocsparse_index_base idx_base); - - rocsparse_status - rocsparse_daxpyi(rocsparse_handle handle, - rocsparse_int nnz, - const double* alpha, - const double* x_val, - const rocsparse_int* x_ind, - double* y, - rocsparse_index_base idx_base); - -*rocsparse_axpyi()* multiplies the sparse vector :math:`x` with scalar :math:`\alpha` and adds the result to the dense vector :math:`y`, such that :math:`y := y + \alpha \cdot x`. - -.. code-block:: c - - for(i = 0; i < nnz; ++i) - y[x_ind[i] - idx_base] = y[x_ind[i] - idx_base] + alpha * x_val[i]; - -======== ============================================================================= -Input -======== ============================================================================= -handle handle to the rocSPARSE library context queue. -nnz number of non-zero entries of vector :math:`x`. -alpha scalar :math:`\alpha`. -x_val array of ``nnz`` elements containing the values of :math:`x`. -x_ind array of ``nnz`` elements containing the indices of the non-zero values of :math:`x`. -y array of values in dense format. -idx_base ``rocsparse_index_base_zero`` or ``rocsparse_index_base_one``. -======== ============================================================================= - -====== ================================ -Output -====== ================================ -y array of values in dense format. -====== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_value ``idx_base`` is invalid. -rocsparse_status_invalid_size ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``alpha``, ``x_val``, ``x_ind`` or ``y`` pointer is invalid. -================================ ==== +***************** + +.. doxygenfunction:: rocsparse_saxpyi + :outline: +.. doxygenfunction:: rocsparse_daxpyi rocsparse_doti() ********************* -.. code-block:: c - - rocsparse_status - rocsparse_sdoti(rocsparse_handle handle, - rocsparse_int nnz, - const float* x_val, - const rocsparse_int* x_ind, - const float* y, - float* result, - rocsparse_index_base idx_base); - - rocsparse_status - rocsparse_ddoti(rocsparse_handle handle, - rocsparse_int nnz, - const double* x_val, - const rocsparse_int* x_ind, - const double* y, - double* result, - rocsparse_index_base idx_base); - -*rocsparse_doti()* computes the dot product of the sparse vector :math:`x` with the dense vector :math:`y`, such that :math:`\text{result} := y^T x`. - -.. code-block:: c - - for(i = 0; i < nnz; ++i) - result = result + x_val[i] * y[x_ind[i] - idx_base]; - -======== ============================================================================= -Input -======== ============================================================================= -handle handle to the rocSPARSE library context queue. -nnz number of non-zero entries of vector :math:`x`. -x_val array of ``nnz`` elements, containing the values of :math:`x`. -x_ind array of ``nnz`` elements, containing the indices of the non-zero values of :math:`x`. -y array of values in dense format. -idx_base ``rocsparse_index_base_zero`` or ``rocsparse_index_base_one``. -======== ============================================================================= - -====== ==================================================== -Output -====== ==================================================== -result pointer to the ``result``, can be host or device memory. -====== ==================================================== - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_value ``idx_base`` is invalid. -rocsparse_status_invalid_size ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``x_val``, ``x_ind``, ``y`` or ``result`` pointer is invalid. -rocsparse_status_memory_error the buffer for the dot product reduction could not be allocated. -rocsparse_status_internal_error an internal error occurred. -================================ ==== + +.. doxygenfunction:: rocsparse_sdoti + :outline: +.. doxygenfunction:: rocsparse_ddoti rocsparse_gthr() ********************* -.. code-block:: c - - rocsparse_status - rocsparse_sgthr(rocsparse_handle handle, - rocsparse_int nnz, - const float* y, - float* x_val, - const rocsparse_int* x_ind, - rocsparse_index_base idx_base); - - rocsparse_status - rocsparse_dgthr(rocsparse_handle handle, - rocsparse_int nnz, - const double* y, - double* x_val, - const rocsparse_int* x_ind, - rocsparse_index_base idx_base); - -*rocsparse_gthr()* gathers the elements that are listed in ``x_ind`` from the dense vector :math:`y` and stores them in the sparse vector :math:`x`. - -.. code-block:: c - - for(i = 0; i < nnz; ++i) - x_val[i] = y[x_ind[i] - idx_base]; - -======== ============================================================================= -Input -======== ============================================================================= -handle handle to the rocSPARSE library context queue. -nnz number of non-zero entries of vector :math:`x`. -y array of values in dense format. -x_ind array of ``nnz`` elements, containing the indices of the non-zero values of :math:`x`. -idx_base ``rocsparse_index_base_zero`` or ``rocsparse_index_base_one``. -======== ============================================================================= - -====== ===================================================== -Output -====== ===================================================== -x_val array of ``nnz`` elements containing the values of :math:`x`. -====== ===================================================== - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_value ``idx_base`` is invalid. -rocsparse_status_invalid_size ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``y``, ``x_val`` or ``x_ind`` pointer is invalid. -================================ ==== + +.. doxygenfunction:: rocsparse_sgthr + :outline: +.. doxygenfunction:: rocsparse_dgthr rocsparse_gthrz() ********************* -.. code-block:: c - - rocsparse_status - rocsparse_sgthrz(rocsparse_handle handle, - rocsparse_int nnz, - const float* y, - float* x_val, - const rocsparse_int* x_ind, - rocsparse_index_base idx_base); - - rocsparse_status - rocsparse_dgthrz(rocsparse_handle handle, - rocsparse_int nnz, - const double* y, - double* x_val, - const rocsparse_int* x_ind, - rocsparse_index_base idx_base); - -*rocsparse_gthrz()* gathers the elements that are listed in ``x_ind`` from the dense vector :math:`y` and stores them in the sparse vector :math:`x`. The gathered elements in :math:`y` are replaced by zero. - -.. code-block:: c - - for(i = 0; i < nnz; ++i) - { - x_val[i] = y[x_ind[i] - idx_base]; - y[x_ind[i] - idx_base] = 0; - } - -======== ============================================================================= -Input -======== ============================================================================= -handle handle to the rocSPARSE library context queue. -nnz number of non-zero entries of vector :math:`x`. -y array of values in dense format. -x_ind array of ``nnz`` elements, containing the indices of the non-zero values of :math:`x`. -idx_base ``rocsparse_index_base_zero`` or ``rocsparse_index_base_one``. -======== ============================================================================= - -====== ===================================================== -Output -====== ===================================================== -x_val array of ``nnz`` elements containing the values of :math:`x`. -====== ===================================================== - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_value ``idx_base`` is invalid. -rocsparse_status_invalid_size ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``y``, ``x_val`` or ``x_ind`` pointer is invalid. -================================ ==== -rocsparse_roti() -********************* -.. code-block:: c - - rocsparse_status - rocsparse_sroti(rocsparse_handle handle, - rocsparse_int nnz, - float* x_val, - const rocsparse_int* x_ind, - float* y, - const float* c, - const float* s, - rocsparse_index_base idx_base); - - rocsparse_status - rocsparse_droti(rocsparse_handle handle, - rocsparse_int nnz, - double* x_val, - const rocsparse_int* x_ind, - double* y, - const double* c, - const double* s, - rocsparse_index_base idx_base); - -*rocsparse_roti()* applies the Givens rotation matrix :math:`G` to the sparse vector :math:`x` and the dense vector :math:`y`, where +.. doxygenfunction:: rocsparse_sgthrz + :outline: +.. doxygenfunction:: rocsparse_dgthrz -.. math:: +rocsparse_roti() +**************** - G = \begin{pmatrix} c & s \\ -s & c \end{pmatrix}. - -.. code-block:: c - - for(i = 0; i < nnz; ++i) - { - double x = x_val[i]; - double y = y[x_ind[i] - idx_base]; - - x_val[i] = c * x + s * y; - y[x_ind[i] - idx_base] = c * y - s * x; - } - -======== ============================================================================= -Input -======== ============================================================================= -handle handle to the rocSPARSE library context queue. -nnz number of non-zero entries of vector :math:`x`. -x_val array of ``nnz`` elements, containing the values of :math:`x`. -x_ind array of ``nnz`` elements, containing the indices of the non-zero values of :math:`x`. -y array of values in dense format. -c pointer to the cosine element of :math:`G`, can be on host or device. -s pointer to the sine element of :math:`G`, can be on host or device. -idx_base ``rocsparse_index_base_zero`` or ``rocsparse_index_base_one``. -======== ============================================================================= - -====== ===================================================== -Output -====== ===================================================== -x_val array of ``nnz`` elements, containing the values of :math:`x`. -y array of values in dense format. -====== ===================================================== - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_value ``idx_base`` is invalid. -rocsparse_status_invalid_size ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``c``, ``s``, ``x_val``, ``x_ind`` or ``y`` pointer is invalid. -================================ ==== +.. doxygenfunction:: rocsparse_sroti + :outline: +.. doxygenfunction:: rocsparse_droti rocsparse_sctr() -********************* -.. code-block:: c - - rocsparse_status - rocsparse_ssctr(rocsparse_handle handle, - rocsparse_int nnz, - const float* x_val, - const rocsparse_int* x_ind, - float* y, - rocsparse_index_base idx_base); - - rocsparse_status - rocsparse_dsctr(rocsparse_handle handle, - rocsparse_int nnz, - const double* x_val, - const rocsparse_int* x_ind, - double* y, - rocsparse_index_base idx_base); - -*rocsparse_sctr()* scatters the elements that are listed in ``x_ind`` from the sparse vector :math:`x` into the dense vector :math:`y`. Entries of :math:`y` that are not listed in ``x_ind`` remain unchanged. - -.. code-block:: c - - for(i = 0; i < nnz; ++i) - y[x_ind[i] - idx_base] = x_val[i]; - -======== ============================================================================= -Input -======== ============================================================================= -handle handle to the rocSPARSE library context queue. -nnz number of non-zero entries of vector :math:`x`. -x_val array of ``nnz`` elements, containing the values of :math:`x`. -x_ind array of ``nnz`` elements, containing the indices of the non-zero values of :math:`x`. -y array of values in dense format. -idx_base ``rocsparse_index_base_zero`` or ``rocsparse_index_base_one``. -======== ============================================================================= - -====== ===================================================== -Output -====== ===================================================== -y array of values in dense format. -====== ===================================================== - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_value ``idx_base`` is invalid. -rocsparse_status_invalid_size ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``x_val``, ``x_ind`` or ``y`` pointer is invalid. -================================ ==== - -.. _rocsparse_level2_functions: +**************** + +.. doxygenfunction:: rocsparse_ssctr + :outline: +.. doxygenfunction:: rocsparse_dsctr + +.. _rocsparse_level2_functions_: Sparse Level 2 Functions ------------------------ -This section describes all rocSPARSE level 2 sparse linear algebra functions. +This module holds all sparse level 2 routines. -rocsparse_coomv() -********************* -.. code-block:: c - - rocsparse_status - rocsparse_scoomv(rocsparse_handle handle, - rocsparse_operation trans, - rocsparse_int m, - rocsparse_int n, - rocsparse_int nnz, - const float* alpha, - const rocsparse_mat_descr descr, - const float* coo_val, - const rocsparse_int* coo_row_ind, - const rocsparse_int* coo_col_ind, - const float* x, - const float* beta, - float* y); - - rocsparse_status - rocsparse_dcoomv(rocsparse_handle handle, - rocsparse_operation trans, - rocsparse_int m, - rocsparse_int n, - rocsparse_int nnz, - const double* alpha, - const rocsparse_mat_descr descr, - const double* coo_val, - const rocsparse_int* coo_row_ind, - const rocsparse_int* coo_col_ind, - const double* x, - const double* beta, - double* y); - -*rocsparse_coomv()* multiplies the scalar :math:`\alpha` with a sparse :math:`m \times n` matrix, defined in COO storage format, and the dense vector :math:`x` and adds the result to the dense vector :math:`y` that is multiplied by the scalar :math:`\beta`, such that :math:`y := \alpha \cdot op(A) \cdot x + \beta \cdot y` with +The sparse level 2 routines describe operations between a matrix in sparse format and a vector in dense format. -.. math:: +rocsparse_coomv() +***************** - op(A) = \Bigg\{ - \begin{array}{ll} - A, & \text{if trans == rocsparse_operation_none} \\ - A^T, & \text{if trans == rocsparse_operation_transpose} \\ - A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} - \end{array}. - -Currently, only ``trans == rocsparse_operation_none`` is supported. - -The COO matrix has to be sorted by row indices. This can be achieved by using :ref:`rocsparse_coosort`. - -.. code-block:: c - - for(i = 0; i < m; ++i) - y[i] = beta * y[i]; - - for(i = 0; i < nnz; ++i) - y[coo_row_ind[i]] += alpha * coo_val[i] * x[coo_col_ind[i]]; - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -trans matrix operation type. -m number of rows of the sparse COO matrix. -n number of columns of the sparse COO matrix. -nnz number of non-zero entries of the sparse COO matrix. -alpha scalar :math:`\alpha`. -descr descriptor of the sparse COO matrix. |br| Currently, *rocsparse_coomv()* supports only ``rocsparse_matrix_type_general``. -coo_val array of ``nnz`` elements of the sparse COO matrix. -coo_row_ind array of ``nnz`` elements containing the row indices of the sparse COO matrix. -coo_col_ind array of ``nnz`` elements containing the column indices of the sparse COO matrix. -x array of ``n`` elements (:math:`op(A) == A`) or |br| ``m`` elements (:math:`op(A) == A^T` or :math:`op(A) == A^H`). -beta scalar :math:`\beta`. -y array of ``m`` elements (:math:`op(A) == A`) or |br| ``n`` elements (:math:`op(A) == A^T` or :math:`op(A) == A^H`). -=========== ============================================================================= - -====== ================================ -Output -====== ================================ -y array of ``m`` elements (:math:`op(A) == A`) or |br| ``n`` elements (:math:`op(A) == A^T` or :math:`op(A) == A^H`). -====== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m``, ``n`` or ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``descr``, ``alpha``, ``coo_val``, ``coo_row_ind``, ``coo_col_ind``, |br| ``x``, ``beta`` or ``y`` pointer is invalid. -rocsparse_status_arch_mismatch the device is not supported by *rocsparse_coomv()*. -rocsparse_status_not_implemented ``trans != rocsparse_operation_none`` or |br| ``rocsparse_matrix_type != rocsparse_matrix_type_general``. -================================ ==== - -.. _rocsparse_csrmv_analysis: +.. doxygenfunction:: rocsparse_scoomv + :outline: +.. doxygenfunction:: rocsparse_dcoomv rocsparse_csrmv_analysis() *************************** -.. code-block:: c - - rocsparse_status - rocsparse_csrmv_analysis(rocsparse_handle handle, - rocsparse_operation trans, - rocsparse_int m, - rocsparse_int n, - rocsparse_int nnz, - const rocsparse_mat_descr descr, - const rocsparse_int* csr_row_ptr, - const rocsparse_int* csr_col_ind, - rocsparse_mat_info info); - -*rocsparse_csrmv_analysis()* performs the analysis step for :ref:`rocsparse_csrmv`. It is expected that this function will be executed only once for a given matrix and particular operation type. Note that if the matrix sparsity pattern changes, the gathered information will become invalid. - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -trans matrix operation type. -m number of rows of the sparse CSR matrix. -n number of columns of the sparse CSR matrix. -nnz number of non-zero entries of the sparse CSR matrix. -descr descriptor of the sparse CSR matrix. |br| Currently, *rocsparse_csrmv_analysis()* supports only ``rocsparse_matrix_type_general``. -csr_row_ptr array of ``m+1`` elements that point to the start of every row of the sparse CSR matrix. -csr_col_ind array of ``nnz`` elements containing the column indices of the sparse CSR matrix. -=========== ============================================================================= - -====== ================================ -Output -====== ================================ -info structure that holds the information collected during analysis step. -====== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m``, ``n`` or ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``descr``, ``csr_row_ptr``, ``csr_col_ind`` or ``info`` pointer is invalid. -rocsparse_status_memory_error the buffer for the gathered information could not be allocated. -rocsparse_status_internal_error an internal error occurred. -rocsparse_status_not_implemented ``trans != rocsparse_operation_none`` or |br| ``rocsparse_matrix_type != rocsparse_matrix_type_general``. -================================ ==== - -.. _rocsparse_csrmv_analysis_clear: -rocsparse_csrmv_analysis_clear() -********************************* -.. code-block:: c +.. doxygenfunction:: rocsparse_scsrmv_analysis + :outline: +.. doxygenfunction:: rocsparse_dcsrmv_analysis - rocsparse_status - rocsparse_csrmv_analysis_clear(rocsparse_handle handle, - rocsparse_mat_info info); +rocsparse_csrmv() +***************** -*rocsparse_csrmv_analysis_clear()* deallocates all memory that was allocated by :ref:`rocsparse_csrmv_analysis`. This is especially useful, if memory is an issue and the analysis data is not required anymore for further computation, e.g. when switching to another sparse matrix format. Calling *rocsparse_csrmv_analysis_clear()* is optional. All allocated resources will be cleared when the opaque :ref:`rocsparse_mat_info` struct is destroyed using :ref:`rocsparse_destroy_mat_info`. +.. doxygenfunction:: rocsparse_scsrmv + :outline: +.. doxygenfunction:: rocsparse_dcsrmv -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -info structure that holds the information collected during analysis step. -=========== ============================================================================= +rocsparse_csrmv_analysis_clear() +********************************* -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_pointer ``info`` pointer is invalid. -rocsparse_status_memory_error the buffer for the information could not be deallocated. -rocsparse_status_internal_error an internal error occurred. -================================ ==== +.. doxygenfunction:: rocsparse_csrmv_clear -.. _rocsparse_csrmv: +rocsparse_ellmv() +***************** -rocsparse_csrmv() -********************* -.. code-block:: c - - rocsparse_status - rocsparse_scsrmv(rocsparse_handle handle, - rocsparse_operation trans, - rocsparse_int m, - rocsparse_int n, - rocsparse_int nnz, - const float* alpha, - const rocsparse_mat_descr descr, - const float* csr_val, - const rocsparse_int* csr_row_ptr, - const rocsparse_int* csr_col_ind, - const float* x, - const float* beta, - float* y, - const rocsparse_mat_info info); - - rocsparse_status - rocsparse_dcsrmv(rocsparse_handle handle, - rocsparse_operation trans, - rocsparse_int m, - rocsparse_int n, - rocsparse_int nnz, - const double* alpha, - const rocsparse_mat_descr descr, - const double* csr_val, - const rocsparse_int* csr_row_ptr, - const rocsparse_int* csr_col_ind, - const double* x, - const double* beta, - double* y, - const rocsparse_mat_info info); - -*rocsparse_csrmv()* multiplies the scalar :math:`\alpha` with a sparse :math:`m \times n` matrix, defined in CSR storage format, and the dense vector :math:`x` and adds the result to the dense vector :math:`y` that is multiplied by the scalar :math:`\beta`, such that :math:`y := \alpha \cdot op(A) \cdot x + \beta \cdot y` with +.. doxygenfunction:: rocsparse_sellmv + :outline: +.. doxygenfunction:: rocsparse_dellmv -.. math:: +rocsparse_hybmv() +***************** - op(A) = \Bigg\{ - \begin{array}{ll} - A, & \text{if trans == rocsparse_operation_none} \\ - A^T, & \text{if trans == rocsparse_operation_transpose} \\ - A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} - \end{array}. - -The ``info`` parameter is optional and contains information collected by :ref:`rocsparse_csrmv_analysis`. If present, the information will be used to speed up the *csrmv* computation. If ``info == NULL``, general *csrmv* routine will be used instead. - -Currently, only ``trans == rocsparse_operation_none`` is supported. - -.. code-block:: c - - for(i = 0; i < m; ++i) - { - y[i] = beta * y[i]; - for(j = csr_row_ptr[i]; j < csr_row_ptr[i + 1]; ++j) - y[i] = y[i] + alpha * csr_val[j] * x[csr_col_ind[j]]; - } - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -trans matrix operation type. -m number of rows of the sparse CSR matrix. -n number of columns of the sparse CSR matrix. -nnz number of non-zero entries of the sparse CSR matrix. -alpha scalar :math:`\alpha`. -descr descriptor of the sparse CSR matrix. |br| Currently, *rocsparse_csrmv()* supports only ``rocsparse_matrix_type_general``. -csr_val array of ``nnz`` elements of the sparse CSR matrix. -csr_row_ptr array of ``m+1`` elements that point to the start of every row of the sparse CSR matrix. -csr_col_ind array of ``nnz`` elements containing the column indices of the sparse CSR matrix. -x array of ``n`` elements (:math:`op(A) == A`) or |br| ``m`` elements (:math:`op(A) == A^T` or :math:`op(A) == A^H`). -beta scalar :math:`\beta`. -y array of ``m`` elements (:math:`op(A) == A`) or |br| ``n`` elements (:math:`op(A) == A^T` or :math:`op(A) == A^H`). -info information collected by :ref:`rocsparse_csrmv_analysis`, |br| can be ``NULL`` if no information is available. -=========== ============================================================================= - -====== ================================ -Output -====== ================================ -y array of ``m`` elements (:math:`op(A) == A`) or |br| ``n`` elements (:math:`op(A) == A^T` or :math:`op(A) == A^H`). -====== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m``, ``n`` or ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``descr``, ``alpha``, ``csr_val``, ``csr_row_ptr``, ``csr_col_ind``, |br| ``x``, ``beta`` or ``y`` pointer is invalid. -rocsparse_status_arch_mismatch the device is not supported by *rocsparse_csrmv()*. -rocsparse_status_memory_error the buffer for the segmented reduction could not be allocated. -rocsparse_status_internal_error an internal error occurred. -rocsparse_status_not_implemented ``trans != rocsparse_operation_none`` or |br| ``rocsparse_matrix_type != rocsparse_matrix_type_general``. -================================ ==== +.. doxygenfunction:: rocsparse_shybmv + :outline: +.. doxygenfunction:: rocsparse_dhybmv -rocsparse_ellmv() -********************* -.. code-block:: c - - rocsparse_status - rocsparse_sellmv(rocsparse_handle handle, - rocsparse_operation trans, - rocsparse_int m, - rocsparse_int n, - const float* alpha, - const rocsparse_mat_descr descr, - const float* ell_val, - const rocsparse_int* ell_col_ind, - rocsparse_int ell_width, - const float* x, - const float* beta, - float* y); - - rocsparse_status - rocsparse_dellmv(rocsparse_handle handle, - rocsparse_operation trans, - rocsparse_int m, - rocsparse_int n, - const double* alpha, - const rocsparse_mat_descr descr, - const double* ell_val, - const rocsparse_int* ell_col_ind, - rocsparse_int ell_width, - const double* x, - const double* beta, - double* y); - -*rocsparse_ellmv()* multiplies the scalar :math:`\alpha` with a sparse :math:`m \times n` matrix, defined in ELL storage format, and the dense vector :math:`x` and adds the result to the dense vector :math:`y` that is multiplied by the scalar :math:`\beta`, such that :math:`y := \alpha \cdot op(A) \cdot x + \beta \cdot y` with +rocsparse_csrsv_zero_pivot() +**************************** -.. math:: +.. doxygenfunction:: rocsparse_csrsv_zero_pivot - op(A) = \Bigg\{ - \begin{array}{ll} - A, & \text{if trans == rocsparse_operation_none} \\ - A^T, & \text{if trans == rocsparse_operation_transpose} \\ - A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} - \end{array}. - -Currently, only ``trans == rocsparse_operation_none`` is supported. - -.. code-block:: c - - for(i = 0; i < m; ++i) - { - y[i] = beta * y[i]; - for(p = 0; p < ell_width; ++p) - if((ell_col_ind[p * m + i] >= 0) && (ell_col_ind[p * m + i] < n)) - y[i] = y[i] + alpha * ell_val[p * m + i] * x[ell_col_ind[p * m + i]]; - } - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -trans matrix operation type. -m number of rows of the sparse ELL matrix. -n number of columns of the sparse ELL matrix. -alpha scalar :math:`\alpha`. -descr descriptor of the sparse ELL matrix. |br| Currently, *rocsparse_ellmv()* supports only ``rocsparse_matrix_type_general``. -ell_val array that contains the elements of the sparse ELL matrix. |br| Padded elements should be zero. -ell_col_ind array that contains the column indices of the sparse ELL matrix. |br| Padded column indices should be -1. -ell_width number of non-zero elements per row of the sparse ELL matrix. -x array of ``n`` elements (:math:`op(A) == A`) or |br| ``m`` elements (:math:`op(A) == A^T` or :math:`op(A) == A^H`). -beta scalar :math:`\beta`. -y array of ``m`` elements (:math:`op(A) == A`) or |br| ``n`` elements (:math:`op(A) == A^T` or :math:`op(A) == A^H`). -=========== ============================================================================= - -====== ================================ -Output -====== ================================ -y array of ``m`` elements (:math:`op(A) == A`) or |br| ``n`` elements (:math:`op(A) == A^T` or :math:`op(A) == A^H`). -====== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m``, ``n`` or ``ell_width`` is invalid. -rocsparse_status_invalid_pointer ``descr``, ``alpha``, ``ell_val``, ``ell_col_ind``, |br| ``x``, ``beta`` or ``y`` pointer is invalid. -rocsparse_status_not_implemented ``trans != rocsparse_operation_none`` or |br| ``rocsparse_matrix_type != rocsparse_matrix_type_general``. -================================ ==== +rocsparse_csrsv_buffer_size() +***************************** -rocsparse_hybmv() -********************* -.. code-block:: c - - rocsparse_status - rocsparse_shybmv(rocsparse_handle handle, - rocsparse_operation trans, - const float* alpha, - const rocsparse_mat_descr descr, - const rocsparse_hyb_mat hyb, - const float* x, - const float* beta, - float* y); - - rocsparse_status - rocsparse_dhybmv(rocsparse_handle handle, - rocsparse_operation trans, - const double* alpha, - const rocsparse_mat_descr descr, - const rocsparse_hyb_mat hyb, - const double* x, - const double* beta, - double* y); - - -*rocsparse_hybmv()* multiplies the scalar :math:`\alpha` with a sparse :math:`m \times n` matrix, defined in HYB storage format, and the dense vector :math:`x` and adds the result to the dense vector :math:`y` that is multiplied by the scalar :math:`\beta`, such that :math:`y := \alpha \cdot op(A) \cdot x + \beta \cdot y` with +.. doxygenfunction:: rocsparse_scsrsv_buffer_size + :outline: +.. doxygenfunction:: rocsparse_dcsrsv_buffer_size -.. math:: +rocsparse_csrsv_analysis() +************************** - op(A) = \Bigg\{ - \begin{array}{ll} - A, & \text{if trans == rocsparse_operation_none} \\ - A^T, & \text{if trans == rocsparse_operation_transpose} \\ - A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} - \end{array}. - -Currently, only ``trans == rocsparse_operation_none`` is supported. - -.. code-block:: c - - // ellmv on the ELL matrix part - ellmv(hyb->ell); - // coomv on the COO matrix part - coomv(hyb->coo); - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -trans matrix operation type. -alpha scalar :math:`\alpha`. -descr descriptor of the sparse HYB matrix. |br| Currently, *rocsparse_hybmv()* supports only ``rocsparse_matrix_type_general``. -hyb matrix in HYB storage format. -x array of ``n`` elements (:math:`op(A) == A`) or |br| ``m`` elements (:math:`op(A) == A^T` or :math:`op(A) == A^H`). -beta scalar :math:`\beta`. -y array of ``m`` elements (:math:`op(A) == A`) or |br| ``n`` elements (:math:`op(A) == A^T` or :math:`op(A) == A^H`). -=========== ============================================================================= - -====== ================================ -Output -====== ================================ -y array of ``m`` elements (:math:`op(A) == A`) or |br| ``n`` elements (:math:`op(A) == A^T` or :math:`op(A) == A^H`). -====== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``hyb`` structure was not initialized with valid matrix sizes. -rocsparse_status_invalid_pointer ``descr``, ``alpha``, ``hyb``, ``x``, ``beta`` or ``y`` pointer is invalid. -rocsparse_status_invalid_value ``hyb`` structure was not initialized with a valid partitioning type. -rocsparse_status_arch_mismatch the device is not supported by *rocsparse_hybmv()*. -rocsparse_status_memory_error the buffer for *rocsparse_hybmv()* could not be allocated. -rocsparse_status_internal_error an internal error occurred. -rocsparse_status_not_implemented ``trans != rocsparse_operation_none`` or |br| ``rocsparse_matrix_type != rocsparse_matrix_type_general``. -================================ ==== - -.. _rocsparse_csrsv_buffer_size: +.. doxygenfunction:: rocsparse_scsrsv_analysis + :outline: +.. doxygenfunction:: rocsparse_dcsrsv_analysis -rocsparse_csrsv_buffer_size() -****************************** -.. code-block:: c - - rocsparse_status - rocsparse_csrsv_buffer_size(rocsparse_handle handle, - rocsparse_operation trans, - rocsparse_int m, - rocsparse_int nnz, - const rocsparse_mat_descr descr, - const rocsparse_int* csr_row_ptr, - const rocsparse_int* csr_col_ind, - rocsparse_mat_info info, - size_t* buffer_size); - -*rocsparse_csrsv_buffer_size()* returns the size of the temporary storage buffer required by :ref:`rocsparse_csrsv_analysis`. The temporary storage buffer must be allocated by the user. - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -trans matrix operation type. -m number of rows of the sparse CSR matrix. -nnz number of non-zero entries of the sparse CSR matrix. -descr descriptor of the sparse CSR matrix. |br| Currently, *rocsparse_csrsv_buffer_size()* supports only ``rocsparse_matrix_type_general``. -csr_row_ptr array of ``m+1`` elements that point to the start of every row of the sparse CSR matrix. -csr_col_ind array of ``nnz`` elements containing the column indices of the sparse CSR matrix. -info structure that holds the information collected during analysis step. -=========== ============================================================================= - -=========== ================================ -Output -=========== ================================ -buffer_size number of bytes of the temporary storage buffer required by :ref:`rocsparse_csrsv_analysis`. -=========== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m`` or ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``descr``, ``csr_row_ptr``, ``csr_col_ind``, ``info`` |br| or ``buffer_size`` pointer is invalid. -rocsparse_status_internal_error an internal error occurred. -rocsparse_status_not_implemented ``trans != rocsparse_operation_none`` or |br| ``rocsparse_matrix_type != rocsparse_matrix_type_general``. -================================ ==== - -.. _rocsparse_csrsv_analysis: +rocsparse_csrsv_solve() +*********************** -rocsparse_csrsv_analysis() -*************************** -.. code-block:: c - - rocsparse_status - rocsparse_csrsv_analysis(rocsparse_handle handle, - rocsparse_operation trans, - rocsparse_int m, - rocsparse_int nnz, - const rocsparse_mat_descr descr, - const rocsparse_int* csr_row_ptr, - const rocsparse_int* csr_col_ind, - rocsparse_mat_info info, - void* temp_buffer); - -*rocsparse_csrsv_analysis()* performs the analysis step for :ref:`rocsparse_csrsv`, :ref:`rocsparse_csric0` and/or :ref:`rocsparse_csrilu0`. It is expected that this function will be executed only once for a given matrix and particular operation type. Note that if the matrix sparsity pattern changes, the gathered information will become invalid. -*rocsparse_csrsv_analysis()* requires extra temporary storage buffer that has to be allocated by the user. Storage buffer size can be determined by :ref:`rocsparse_csrsv_buffer_size`. - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -trans matrix operation type. -m number of rows of the sparse CSR matrix. -nnz number of non-zero entries of the sparse CSR matrix. -descr descriptor of the sparse CSR matrix. |br| Currently, *rocsparse_csrsv_analysis()* supports only ``rocsparse_matrix_type_general``. -csr_row_ptr array of ``m+1`` elements that point to the start of every row of the sparse CSR matrix. -csr_col_ind array of ``nnz`` elements containing the column indices of the sparse CSR matrix. -temp_buffer temporary storage buffer allocated by the user, |br| size is returned by :ref:`rocsparse_csrsv_buffer_size`. -=========== ============================================================================= - -====== ================================ -Output -====== ================================ -info structure that holds the information collected during analysis step. -====== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m`` or ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``descr``, ``csr_row_ptr``, ``csr_col_ind``, ``info`` |br| or ``temp_buffer`` pointer is invalid. -rocsparse_status_internal_error an internal error occurred. -rocsparse_status_not_implemented ``trans != rocsparse_operation_none`` or |br| ``rocsparse_matrix_type != rocsparse_matrix_type_general``. -================================ ==== - -.. _rocsparse_csrsv_analysis_clear: +.. doxygenfunction:: rocsparse_scsrsv_solve + :outline: +.. doxygenfunction:: rocsparse_dcsrsv_solve rocsparse_csrsv_analysis_clear() -********************************* -.. code-block:: c - - rocsparse_status - rocsparse_csrsv_analysis_clear(rocsparse_handle handle, - rocsparse_mat_info info); - -*rocsparse_csrsv_analysis_clear()* deallocates all memory that was allocated by :ref:`rocsparse_csrsv_analysis`. This is especially useful, if memory is an issue and the analysis data is not required anymore for further computation, e.g. when switching to another sparse matrix format. Calling *rocsparse_csrmv_analysis_clear()* is optional. All allocated resources will be cleared when the opaque :ref:`rocsparse_mat_info` struct is destroyed using :ref:`rocsparse_destroy_mat_info`. - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -info structure that holds the information collected during analysis step. -=========== ============================================================================= - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_pointer ``info`` pointer is invalid. -rocsparse_status_memory_error the buffer for the information could not be deallocated. -rocsparse_status_internal_error an internal error occurred. -================================ ==== - -.. _rocsparse_csrsv: - -rocsparse_csrsv() -********************* -.. code-block:: c - - rocsparse_status - rocsparse_scsrsv(rocsparse_handle handle, - rocsparse_operation trans, - rocsparse_int m, - rocsparse_int nnz, - const float* alpha, - const rocsparse_mat_descr descr, - const float* csr_val, - const rocsparse_int* csr_row_ptr, - const rocsparse_int* csr_col_ind, - const rocsparse_mat_info info, - const float* x, - float* y, - rocsparse_solve_policy policy, - void* temp_buffer); - - rocsparse_status - rocsparse_dcsrsv(rocsparse_handle handle, - rocsparse_operation trans, - rocsparse_int m, - rocsparse_int nnz, - const double* alpha, - const rocsparse_mat_descr descr, - const double* csr_val, - const rocsparse_int* csr_row_ptr, - const rocsparse_int* csr_col_ind, - const rocsparse_mat_info info, - const float* x, - float* y, - rocsparse_solve_policy policy, - void* temp_buffer); - -*rocsparse_csrsv()* solves a sparse triangular linear system with a sparse :math:`m \times n` matrix, defined in CSR storage format, the dense vector :math:`y`, the scalar :math:`\alpha` and the right-hand side vector :math:`x` such that :math:`op(A) \cdot y = \alpha \cdot x` with +******************************** -.. math:: +.. doxygenfunction:: rocsparse_csrsv_clear - op(A) = \Bigg\{ - \begin{array}{ll} - A, & \text{if trans == rocsparse_operation_none} \\ - A^T, & \text{if trans == rocsparse_operation_transpose} \\ - A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} - \end{array}. - -Currently, only ``trans == rocsparse_operation_none`` is supported. - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -trans matrix operation type. -m number of rows of the sparse CSR matrix. -nnz number of non-zero entries of the sparse CSR matrix. -alpha scalar :math:`\alpha`. -descr descriptor of the sparse CSR matrix. |br| Currently, *rocsparse_csrmv()* supports only ``rocsparse_matrix_type_general``. -csr_val array of ``nnz`` elements of the sparse CSR matrix. -csr_row_ptr array of ``m+1`` elements that point to the start of every row of the sparse CSR matrix. -csr_col_ind array of ``nnz`` elements containing the column indices of the sparse CSR matrix. -info information collected by :ref:`rocsparse_csrsv_analysis`. -x array of ``n`` elements (:math:`op(A) == A`) or |br| ``m`` elements (:math:`op(A) == A^T` or :math:`op(A) == A^H`). -policy ``rocsparse_solve_policy_no_level`` or ``rocsparse_solve_policy_use_level``. -temp_buffer temporary storage buffer allocated by the user, |br| size is returned by :ref:`rocsparse_csrsv_buffer_size`. -=========== ============================================================================= - -====== ================================ -Output -====== ================================ -y array of ``m`` elements (:math:`op(A) == A`) or |br| ``n`` elements (:math:`op(A) == A^T` or :math:`op(A) == A^H`). -====== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m`` or ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``descr``, ``alpha``, ``csr_val``, ``csr_row_ptr``, ``csr_col_ind``, |br| ``x`` or ``y`` pointer is invalid. -rocsparse_status_arch_mismatch the device is not supported by *rocsparse_csrsv()*. -rocsparse_status_internal_error an internal error occurred. -rocsparse_status_not_implemented ``trans != rocsparse_operation_none`` or |br| ``rocsparse_matrix_type != rocsparse_matrix_type_general``. -================================ ==== - -.. _rocsparse_level3_functions: +.. _rocsparse_level3_functions_: Sparse Level 3 Functions ------------------------ -This section describes all rocSPARSE level 3 sparse linear algebra functions. +This module holds all sparse level 3 routines. + +The sparse level 3 routines describe operations between a matrix in sparse format and multiple vectors in dense format that can also be seen as a dense matrix. rocsparse_csrmm() ********************* -.. code-block:: c - - rocsparse_status - rocsparse_scsrmm(rocsparse_handle handle, - rocsparse_operation trans_A, - rocsparse_operation trans_B, - rocsparse_int m, - rocsparse_int n, - rocsparse_int k, - rocsparse_int nnz, - const float* alpha, - const rocsparse_mat_descr descr, - const float* csr_val, - const rocsparse_int* csr_row_ptr, - const rocsparse_int* csr_col_ind, - const float* B, - rocsparse_int ldb, - const float* beta, - float* C, - rocsparse_int ldc); - - rocsparse_status - rocsparse_dcsrmm(rocsparse_handle handle, - rocsparse_operation trans_A, - rocsparse_operation trans_B, - rocsparse_int m, - rocsparse_int n, - rocsparse_int k, - rocsparse_int nnz, - const double* alpha, - const rocsparse_mat_descr descr, - const double* csr_val, - const rocsparse_int* csr_row_ptr, - const rocsparse_int* csr_col_ind, - const double* B, - rocsparse_int ldb, - const double* beta, - double* C, - rocsparse_int ldc); - -*rocsparse_csrmm()* multiplies the scalar :math:`\alpha` with a sparse :math:`m \times k` matrix :math:`A`, defined in CSR storage format, and the dense :math:`k \times n` matrix :math:`B` and adds the result to the dense :math:`m \times n` matrix :math:`C` that is multiplied by the scalar :math:`\beta`, such that :math:`C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot C` with -.. math:: +.. doxygenfunction:: rocsparse_scsrmm + :outline: +.. doxygenfunction:: rocsparse_dcsrmm - op(A) = \Bigg\{ - \begin{array}{ll} - A, & \text{if trans_A == rocsparse_operation_none} \\ - A^T, & \text{if trans_A == rocsparse_operation_transpose} \\ - A^H, & \text{if trans_A == rocsparse_operation_conjugate_transpose} - \end{array} +.. _rocsparse_precond_functions_: -and +Preconditioner Functions +------------------------ -.. math:: +This module holds all sparse preconditioners. - op(B) = \Bigg\{ - \begin{array}{ll} - B, & \text{if trans_B == rocsparse_operation_none} \\ - B^T, & \text{if trans_B == rocsparse_operation_transpose} \\ - B^H, & \text{if trans_B == rocsparse_operation_conjugate_transpose} - \end{array}. - -Currently, only ``trans_A == rocsparse_operation_none`` is supported. - -.. code-block:: c - - for(i = 0; i < ldc; ++i) - for(j = 0; j < n; ++j) - { - C[i][j] = beta * C[i][j]; - for(k = csr_row_ptr[i]; k < csr_row_ptr[i + 1]; ++k) - C[i][j] += alpha * csr_val[k] * B[csr_col_ind[k]][j]; - } - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -trans_A matrix :math:`A` operation type. -trans_B matrix :math:`B` operation type. -m number of rows of the sparse CSR matrix :math:`A`. -n number of columns of the dense matrix :math:`op(B)` and :math:`C`. -k number of columns of the sparse CSR matrix :math:`A`. -nnz number of non-zero entries of the sparse CSR matrix :math:`A`. -alpha scalar :math:`\alpha`. -descr descriptor of the sparse CSR matrix :math:`A`. |br| Currently, *rocsparse_csrmm()* supports only ``rocsparse_matrix_type_general``. -csr_val array of ``nnz`` elements of the sparse CSR matrix :math:`A`. -csr_row_ptr array of ``m+1`` elements that point to the start of every row of the sparse CSR matrix :math:`A`. -csr_col_ind array of ``nnz`` elements containing the column indices of the sparse CSR matrix :math:`A`. -B array of dimension :math:`ldb \times n` (:math:`op(B) == B`) or |br| :math:`ldb \times k` (:math:`op(B) == B^T` or :math:`op(B) == B^H`). -ldb leading dimension of :math:`B`, must be at least :math:`\max{(1, k)}` (:math:`op(A) == A`) or |br| :math:`\max{(1, m)}` (:math:`op(A) == A^T` or :math:`op(A) == A^H`). -beta scalar :math:`\beta`. -C array of dimension :math:`ldc \times n`. -ldc leading dimension of :math:`C`, must be at least :math:`\max{(1, m)}` (:math:`op(A) == A`) or |br| :math:`\max{(1, k)}` (:math:`op(A) == A^T` or :math:`op(A) == A^H`). -=========== ============================================================================= - -====== ================================ -Output -====== ================================ -C array of dimension :math:`ldc \times n`. -====== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m``, ``n``, ``k``, ``nnz``, ``ldb`` or ``ldc`` is invalid. -rocsparse_status_invalid_pointer ``descr``, ``alpha``, ``csr_val``, ``csr_row_ptr``, ``csr_col_ind``, |br| ``B``, ``beta`` or ``C`` pointer is invalid. -rocsparse_status_arch_mismatch the device is not supported by *rocsparse_csrmm()*. -rocsparse_status_not_implemented ``trans_A != rocsparse_operation_none`` or |br| ``rocsparse_matrix_type != rocsparse_matrix_type_general``. -================================ ==== - -.. _rocsparse_precond_functions: +The sparse preconditioners describe manipulations on a matrix in sparse format to obtain a sparse preconditioner matrix. -Preconditioner Functions ------------------------- +rocsparse_csrilu0_zero_pivot() +****************************** -.. _rocsparse_csric0: +.. doxygenfunction:: rocsparse_csrilu0_zero_pivot -rocsparse_csric0 -***************** +rocsparse_csrilu0_buffer_size() +******************************* -.. _rocsparse_csrilu0: +.. doxygenfunction:: rocsparse_scsrilu0_buffer_size + :outline: +.. doxygenfunction:: rocsparse_dcsrilu0_buffer_size -rocsparse_csrilu0 -****************** +rocsparse_csrilu0_analysis() +**************************** + +.. doxygenfunction:: rocsparse_scsrilu0_analysis + :outline: +.. doxygenfunction:: rocsparse_dcsrilu0_analysis + +rocsparse_csrilu0() +******************* + +.. doxygenfunction:: rocsparse_scsrilu0 + :outline: +.. doxygenfunction:: rocsparse_dcsrilu0 + +rocsparse_csrilu0_analysis_clear() +********************************** + +.. doxygenfunction:: rocsparse_csrilu0_clear -.. _rocsparse_conversion_functions: +.. _rocsparse_conversion_functions_: Sparse Conversion Functions --------------------------- -This section describes all rocSPARSE conversion functions. +This module holds all sparse conversion routines. -rocsparse_csr2coo -****************** -.. code-block:: c - - rocsparse_status - rocsparse_csr2coo(rocsparse_handle handle, - const rocsparse_int* csr_row_ptr, - rocsparse_int nnz, - rocsparse_int m, - rocsparse_int* coo_row_ind, - rocsparse_index_base idx_base); - -*rocsparse_csr2coo()* converts the CSR array containing the row offsets, that point to the start of every row, into a COO array of row indices. It can also be used, to convert a CSC array containing the column offsets into a COO array of column indices. - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -csr_row_ptr array of ``m+1`` elements that point to the start of every row of the sparse CSR matrix. -nnz number of non-zero entries of the sparse CSR matrix. -m number of rows of the sparse CSR matrix. -idx_base ``rocsparse_index_base_zero`` or ``rocsparse_index_base_one``. -=========== ============================================================================= - -=========== ================================ -Output -=========== ================================ -coo_row_ind array of ``nnz`` elements containing the row indices of the sparse COO matrix. -=========== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m`` or ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``csr_row_ptr`` or ``coo_row_ind`` pointer is invalid. -rocsparse_status_arch_mismatch the device is not supported by *rocsparse_csr2coo()*. -================================ ==== - -rocsparse_coo2csr -****************** -.. code-block:: c - - rocsparse_status - rocsparse_coo2csr(rocsparse_handle handle, - const rocsparse_int* coo_row_ind, - rocsparse_int nnz, - rocsparse_int m, - rocsparse_int* csr_row_ptr, - rocsparse_index_base idx_base); - -*rocsparse_coo2csr()* converts the COO array containing the row indices into a CSR array of row offsets, that point to the start of every row. It can also be used, to convert a COO array containing the column indices into a CSC array of column offsets, that point to the start of every column. - -It is assumed that the COO row index array is sorted. - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -coo_row_ind array of ``nnz`` elements containing the row indices of the sparse COO matrix. -nnz number of non-zero entries of the sparse CSR matrix. -m number of rows of the sparse CSR matrix. -idx_base ``rocsparse_index_base_zero`` or ``rocsparse_index_base_one``. -=========== ============================================================================= - -=========== ================================ -Output -=========== ================================ -csr_row_ptr array of ``m+1`` elements that point to the start of every row of the sparse CSR matrix. -=========== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m`` or ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``coo_row_ind`` or ``csr_row_ptr`` pointer is invalid. -================================ ==== - -.. _rocsparse_csr2csc_buffer_size: - -rocsparse_csr2csc_buffer_size -****************************** -.. code-block:: c - - rocsparse_status - rocsparse_csr2csc_buffer_size(rocsparse_handle handle, - rocsparse_int m, - rocsparse_int n, - rocsparse_int nnz, - const rocsparse_int* csr_row_ptr, - const rocsparse_int* csr_col_ind, - rocsparse_action copy_values, - size_t* buffer_size); - -*rocsparse_csr2csc_buffer_size()* returns the size of the temporary storage buffer required by :ref:`rocsparse_csr2csc`. The temporary storage buffer must be allocated by the user. - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -m number of rows of the sparse CSR matrix. -n number of columns of the sparse CSR matrix. -nnz number of non-zero entries of the sparse CSR matrix. -csr_row_ptr array of ``m+1`` elements that point to the start of every row of the sparse CSR matrix. -csr_col_ind array of ``nnz`` elements containing the column indices of the sparse CSR matrix. -copy_values ``rocsparse_action_numeric`` or ``rocsparse_action_symbolic``. -=========== ============================================================================= - -=========== ================================ -Output -=========== ================================ -buffer_size number of bytes of the temporary storage buffer required by :ref:`rocsparse_csr2csc`. -=========== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m``, ``n`` or ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``csr_row_ptr``, ``csr_col_ind`` or ``buffer_size`` pointer is invalid. -rocsparse_status_internal_error an internal error occurred. -================================ ==== - -.. _rocsparse_csr2csc: - -rocsparse_csr2csc -********************* -.. code-block:: c - - rocsparse_status - rocsparse_scsr2csc(rocsparse_handle handle, - rocsparse_int m, - rocsparse_int n, - rocsparse_int nnz, - const float* csr_val, - const rocsparse_int* csr_row_ptr, - const rocsparse_int* csr_col_ind, - float* csc_val, - rocsparse_int* csc_row_ind, - rocsparse_int* csc_col_ptr, - rocsparse_action copy_values, - void* temp_buffer); - - rocsparse_status - rocsparse_dcsr2csc(rocsparse_handle handle, - rocsparse_int m, - rocsparse_int n, - rocsparse_int nnz, - const double* csr_val, - const rocsparse_int* csr_row_ptr, - const rocsparse_int* csr_col_ind, - double* csc_val, - rocsparse_int* csc_row_ind, - rocsparse_int* csc_col_ptr, - rocsparse_action copy_values, - void* temp_buffer); - -*rocsparse_csr2csc()* converts a CSR matrix info a CSC matrix. The resulting matrix can also be seen as the transpose of the input matrix. *rocsparse_csr2csc()* can also be used to convert a CSC matrix into a CSR matrix. ``copy_values`` decides whether ``csc_val`` is being filled during conversion (``rocsparse_action_numeric``) or not (``rocsparse_action_symbolic``). - -*rocsparse_csr2csc()* requires extra temporary storage buffer that has to be allocated by the user. Storage buffer size can be determined by :ref:`rocsparse_csr2csc_buffer_size`. - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -m number of rows of the sparse CSR matrix. -n number of columns of the sparse CSR matrix. -nnz number of non-zero entries of the sparse CSR matrix. -csr_val array of ``nnz`` elements of the sparse CSR matrix. -csr_row_ptr array of ``m+1`` elements that point to the start of every row of the sparse CSR matrix. -csr_col_ind array of ``nnz`` elements containing the column indices of the sparse CSR matrix. -copy_values ``rocsparse_action_numeric`` or ``rocsparse_action_symbolic``. -temp_buffer temporary storage buffer allocated by the user, |br| size is returned by :ref:`rocsparse_csr2csc_buffer_size`. -=========== ============================================================================= - -=========== ================================ -Output -=========== ================================ -csc_val array of ``nnz`` elements of the sparse CSC matrix. -csc_row_ind array of ``nnz`` elements containing the row indices of the sparse CSC matrix. -csc_col_ptr array of ``n+1`` elements that point to the start of every column of the sparse CSC matrix. -=========== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m``, ``n`` or ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``csr_val``, ``csr_row_ptr``, ``csr_col_ind``, ``csc_val``, |br| ``csc_row_ind``, ``csc_col_ptr`` or ``temp_buffer`` pointer is invalid. -rocsparse_status_arch_mismatch the device is not supported by *rocsparse_csr2csc()*. -rocsparse_status_internal_error an internal error occurred. -================================ ==== - -.. _rocsparse_csr2ell_width: - -rocsparse_csr2ell_width -************************ -.. code-block:: c - - rocsparse_status - rocsparse_csr2ell_width(rocsparse_handle handle, - rocsparse_int m, - const rocsparse_mat_descr csr_descr, - const rocsparse_int* csr_row_ptr, - const rocsparse_mat_descr ell_descr, - rocsparse_int* ell_width); - -*rocsparse_csr2ell_width()* computes the maximum of the per row non-zero elements over all rows, the ELL width, for a given CSR matrix. - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -m number of rows of the sparse CSR matrix. -csr_descr descriptor of the sparse CSR matrix. |br| Currently, *rocsparse_csr2ell_width()* supports only ``rocsparse_matrix_type_general``. -csr_row_ptr array of ``m+1`` elements that point to the start of every row of the sparse CSR matrix. -ell_descr descriptor of the sparse ELL matrix. |br| Currently, *rocsparse_csr2ell_width()* supports only ``rocsparse_matrix_type_general``. -=========== ============================================================================= - -=========== ================================ -Output -=========== ================================ -ell_width pointer to the number of non-zero elements per row in ELL storage format. -=========== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m`` is invalid. -rocsparse_status_invalid_pointer ``csr_descr``, ``csr_row_ptr``, |br| ``ell_descr`` or ``ell_width`` pointer is invalid. -rocsparse_status_internal_error an internal error occurred. -rocsparse_status_not_implemented ``rocsparse_matrix_type != rocsparse_matrix_type_general``. -================================ ==== - -.. _rocsparse_csr2ell: - -rocsparse_csr2ell -********************* -.. code-block:: c - - rocsparse_status - rocsparse_scsr2ell(rocsparse_handle handle, - rocsparse_int m, - const rocsparse_mat_descr csr_descr, - const float* csr_val, - const rocsparse_int* csr_row_ptr, - const rocsparse_int* csr_col_ind, - const rocsparse_mat_descr ell_descr, - rocsparse_int ell_width, - float* ell_val, - rocsparse_int* ell_col_ind); - - rocsparse_status - rocsparse_dcsr2ell(rocsparse_handle handle, - rocsparse_int m, - const rocsparse_mat_descr csr_descr, - const double* csr_val, - const rocsparse_int* csr_row_ptr, - const rocsparse_int* csr_col_ind, - const rocsparse_mat_descr ell_descr, - rocsparse_int ell_width, - double* ell_val, - rocsparse_int* ell_col_ind); - -*rocsparse_csr2ell()* converts a CSR matrix into an ELL matrix. It is assumed, that ``ell_val`` and ``ell_col_ind`` are allocated. Allocation size is computed by the number of rows times the number of ELL non-zero elements per row, such that :math:`\text{nnz}_{\text{ELL}} = m \cdot \text{ell_width}`. The number of ELL non-zero elements per row is obtained by :ref:`rocsparse_csr2ell_width`. - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -m number of rows of the sparse CSR matrix. -csr_descr descriptor of the sparse CSR matrix. |br| Currently, *rocsparse_csr2ell()* supports only ``rocsparse_matrix_type_general``. -csr_val array containing the values of the sparse CSR matrix. -csr_row_ptr array of ``m+1`` elements that point to the start of every row of the sparse CSR matrix. -csr_col_ind array containing the column indices of the sparse CSR matrix. -ell_descr descriptor of the sparse ELL matrix. |br| Currently, *rocsparse_csr2ell()* supports only ``rocsparse_matrix_type_general``. -ell_width number of non-zero elements per row in ELL storage format. -=========== ============================================================================= - -=========== ================================ -Output -=========== ================================ -ell_val array of ``m`` times ``ell_width`` elements of the sparse ELL matrix. -ell_col_ind array of ``m`` times ``ell_width`` elements containing the column indices |br| of the sparse ELL matrix. -=========== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m`` or ``ell_width`` is invalid. -rocsparse_status_invalid_pointer ``csr_descr``, ``csr_val``, ``csr_row_ptr``, ``csr_col_ind``, |br| ``ell_descr``, ``ell_val`` or ``ell_col_ind`` pointer is invalid. -rocsparse_status_not_implemented ``rocsparse_matrix_type != rocsparse_matrix_type_general``. -================================ ==== - -.. _rocsparse_ell2csr_nnz: - -rocsparse_ell2csr_nnz -********************** -.. code-block:: c - - rocsparse_status - rocsparse_ell2csr_nnz(rocsparse_handle handle, - rocsparse_int m, - rocsparse_int n, - const rocsparse_mat_descr ell_descr, - rocsparse_int ell_width, - const rocsparse_int* ell_col_ind, - const rocsparse_mat_descr csr_descr, - rocsparse_int* csr_row_ptr, - rocsparse_int* csr_nnz); - -*rocsparse_ell2csr_nnz()* computes the total CSR non-zero elements and the CSR row offsets, that point to the start of every row of the sparse CSR matrix, for a given ELL matrix. It is assumed that ``csr_row_ptr`` has been allocated with size ``m + 1``. - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -m number of rows of the sparse ELL matrix. -n number of columns of the sparse ELL matrix. -ell_descr descriptor of the sparse ELL matrix. |br| Currently, *rocsparse_ell2csr_nnz()* supports only ``rocsparse_matrix_type_general``. -ell_width number of non-zero elements per row in ELL storage format. -ell_col_ind array of ``m`` times ``ell_width`` elements containing the column indices |br| of the sparse ELL matrix. -csr_descr descriptor of the sparse CSR matrix. |br| Currently, *rocsparse_ell2csr_nnz()* supports only ``rocsparse_matrix_type_general``. -=========== ============================================================================= - -=========== ================================ -Output -=========== ================================ -csr_row_ptr array of ``m+1`` elements that point to the start of every row of the sparse CSR matrix. -csr_nnz pointer to the total number of non-zero elements in CSR storage format. -=========== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m``, ``n`` or ``ell_width`` is invalid. -rocsparse_status_invalid_pointer ``ell_descr``, ``ell_col_ind``, |br| ``csr_descr``, ``csr_row_ptr`` or ``csr_nnz`` pointer is invalid. -rocsparse_status_not_implemented ``rocsparse_matrix_type != rocsparse_matrix_type_general``. -================================ ==== - -.. _rocsparse_ell2csr: - -rocsparse_ell2csr -********************* -.. code-block:: c - - rocsparse_status - rocsparse_sell2csr(rocsparse_handle handle, - rocsparse_int m, - rocsparse_int n, - const rocsparse_mat_descr ell_descr, - rocsparse_int ell_width, - const float* ell_val, - const rocsparse_int* ell_col_ind, - const rocsparse_mat_descr csr_descr, - float* csr_val, - const rocsparse_int* csr_row_ptr, - rocsparse_int* csr_col_ind); - - rocsparse_status - rocsparse_dell2csr(rocsparse_handle handle, - rocsparse_int m, - rocsparse_int n, - const rocsparse_mat_descr ell_descr, - rocsparse_int ell_width, - const double* ell_val, - const rocsparse_int* ell_col_ind, - const rocsparse_mat_descr csr_descr, - double* csr_val, - const rocsparse_int* csr_row_ptr, - rocsparse_int* csr_col_ind); - -*rocsparse_ell2csr()* converts an ELL matrix into a CSR matrix. It is assumed that ``csr_row_ptr`` has already been filled and that ``csr_val`` and ``csr_col_ind`` are allocated by the user. ``csr_row_ptr`` and allocation size of ``csr_col_ind`` and ``csr_val`` is defined by the number of CSR non-zero elements. Both can be obtained by :ref:`rocsparse_ell2csr_nnz`. - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -m number of rows of the sparse ELL matrix. -n number of columns of the sparse ELL matrix. -ell_descr descriptor of the sparse ELL matrix. |br| Currently, *rocsparse_ell2csr()* supports only ``rocsparse_matrix_type_general``. -ell_width number of non-zero elements per row in ELL storage format. -ell_val array of ``m`` times ``ell_width`` elements of the sparse ELL matrix. -ell_col_ind array of ``m`` times ``ell_width`` elements containing the column indices |br| of the sparse ELL matrix. -csr_descr descriptor of the sparse CSR matrix. |br| Currently, *rocsparse_ell2csr()* supports only ``rocsparse_matrix_type_general``. -csr_row_ptr array of ``m+1`` elements that point to the start of every row of the sparse CSR matrix. -=========== ============================================================================= - -=========== ================================ -Output -=========== ================================ -csr_val array containing the values of the sparse CSR matrix. -csr_col_ind array containing the column indices of the sparse CSR matrix. -=========== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m``, ``n`` or ``ell_width`` is invalid. -rocsparse_status_invalid_pointer ``csr_descr``, ``csr_val``, ``csr_row_ptr``, ``csr_col_ind``, |br| ``ell_descr``, ``ell_val`` or ``ell_col_ind`` pointer is invalid. -rocsparse_status_not_implemented ``rocsparse_matrix_type != rocsparse_matrix_type_general``. -================================ ==== - -rocsparse_csr2hyb -********************* -.. code-block:: c - - rocsparse_status - rocsparse_scsr2hyb(rocsparse_handle handle, - rocsparse_int m, - rocsparse_int n, - const rocsparse_mat_descr descr, - const float* csr_val, - const rocsparse_int* csr_row_ptr, - const rocsparse_int* csr_col_ind, - rocsparse_hyb_mat hyb, - rocsparse_int user_ell_width, - rocsparse_hyb_partition partition_type); - - rocsparse_status - rocsparse_dcsr2hyb(rocsparse_handle handle, - rocsparse_int m, - rocsparse_int n, - const rocsparse_mat_descr descr, - const double* csr_val, - const rocsparse_int* csr_row_ptr, - const rocsparse_int* csr_col_ind, - rocsparse_hyb_mat hyb, - rocsparse_int user_ell_width, - rocsparse_hyb_partition partition_type); - -*rocsparse_csr2hyb()* converts a CSR matrix into a HYB matrix. It is assumed that ``hyb`` has been initialized with :ref:`rocsparse_create_hyb_mat`. - -This function requires a significant amount of storage for the HYB matrix, depending on the matrix structure. - -============== ============================================================================= -Input -============== ============================================================================= -handle handle to the rocSPARSE library context queue. -m number of rows of the sparse ELL matrix. -n number of columns of the sparse ELL matrix. -descr descriptor of the sparse CSR matrix. |br| Currently, *rocsparse_csr2hyb()* supports only ``rocsparse_matrix_type_general``. -csr_val array containing the values of the sparse CSR matrix. -csr_row_ptr array of ``m+1`` elements that point to the start of every row of the sparse CSR matrix. -csr_col_ind array containing the column indices of the sparse CSR matrix. -user_ell_width width of the ELL part of the HYB matrix (only required if |br| ``partition_type == rocsparse_hyb_partition_user``). -partition_type ``rocsparse_hyb_partition_auto`` (recommended), |br| ``rocsparse_hyb_partition_user`` or ``rocsparse_hyb_partition_max``. -============== ============================================================================= - -====== ================================ -Output -====== ================================ -hyb sparse matrix in HYB format. -====== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m``, ``n`` or ``user_ell_width`` is invalid. -rocsparse_status_invalid_value ``partition_type`` is invalid. -rocsparse_status_invalid_pointer ``descr``, ``hyb``, ``csr_val``, ``csr_row_ptr`` |br| or ``csr_col_ind`` pointer is invalid. -rocsparse_status_memory_error the buffer for the HYB matrix could not be allocated. -rocsparse_status_internal_error an internal error occurred. -rocsparse_status_not_implemented ``rocsparse_matrix_type != rocsparse_matrix_type_general``. -================================ ==== - -.. _rocsparse_create_identity_permutation: - -rocsparse_create_identity_permutation -************************************** -.. code-block:: c +The sparse conversion routines describe operations on a matrix in sparse format to obtain a matrix in a different sparse format. - rocsparse_status - rocsparse_create_identity_permutation(rocsparse_handle handle, - rocsparse_int n, - rocsparse_int* p); +rocsparse_csr2coo() +******************* -*rocsparse_create_identity_permutation()* stores the identity map in ``p``, such that :math:`p = 0:1:(n-1)`. +.. doxygenfunction:: rocsparse_csr2coo -.. code-block:: c +rocsparse_coo2csr() +******************* - for(i = 0; i < n; ++i) - p[i] = i; +.. doxygenfunction:: rocsparse_coo2csr -====== ============================================== -Input -====== ============================================== -handle handle to the rocSPARSE library context queue. -n size of the map ``p``. -====== ============================================== +rocsparse_csr2csc_buffer_size() +******************************* -====== =========================================== -Output -====== =========================================== -p array of ``n`` integers containing the map. -====== =========================================== +.. doxygenfunction:: rocsparse_csr2csc_buffer_size -================================ ======================================== -Returned rocsparse_status -================================ ======================================== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``n`` is invalid. -rocsparse_status_invalid_pointer ``p`` pointer is invalid. -================================ ======================================== +rocsparse_csr2csc() +******************* -.. _rocsparse_csrsort_buffer_size: +.. doxygenfunction:: rocsparse_scsr2csc + :outline: +.. doxygenfunction:: rocsparse_dcsr2csc -rocsparse_csrsort_buffer_size -****************************** -.. code-block:: c - - rocsparse_status - rocsparse_csrsort_buffer_size(rocsparse_handle handle, - rocsparse_int m, - rocsparse_int n, - rocsparse_int nnz, - const rocsparse_int* csr_row_ptr, - const rocsparse_int* csr_col_ind, - size_t* buffer_size); - -*rocsparse_csrsort_buffer_size()* returns the size of the temporary storage buffer required by :ref:`rocsparse_csrsort`. The temporary storage buffer must be allocated by the user. - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -m number of rows of the sparse CSR matrix. -n number of columns of the sparse CSR matrix. -nnz number of non-zero entries of the sparse CSR matrix. -csr_row_ptr array of ``m+1`` elements that point to the start of every row of the sparse CSR matrix. -csr_col_ind array of ``nnz`` elements containing the column indices of the sparse CSR matrix. -=========== ============================================================================= - -=========== ================================ -Output -=========== ================================ -buffer_size number of bytes of the temporary storage buffer required by :ref:`rocsparse_csrsort`. -=========== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m``, ``n`` or ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``csr_row_ptr``, ``csr_col_ind`` or ``buffer_size`` pointer is invalid. -rocsparse_status_internal_error an internal error occurred. -================================ ==== - -.. _rocsparse_csrsort: - -rocsparse_csrsort -********************* -.. code-block:: c - - rocsparse_status - rocsparse_csrsort(rocsparse_handle handle, - rocsparse_int m, - rocsparse_int n, - rocsparse_int nnz, - const rocsparse_mat_descr descr, - const rocsparse_int* csr_row_ptr, - rocsparse_int* csr_col_ind, - rocsparse_int* perm, - void* temp_buffer); - -*rocsparse_csrsort()* sorts a matrix in CSR format. The sorted permutation vector ``perm`` can be used to obtain sorted ``csr_val`` array. In this case, ``perm`` must be initialized as the identity permutation, see :ref:`rocsparse_create_identity_permutation`. - -*rocsparse_csrsort()* requires extra temporary storage buffer that has to be allocated by the user. Storage buffer size can be determined by :ref:`rocsparse_csrsort_buffer_size`. - -Example application: - -.. code-block:: c - - // 1 2 3 - // A = 4 5 6 - // 7 8 9 - rocsparse_int m = 3; - rocsparse_int n = 3; - rocsparse_int nnz = 9; - - csr_row_ptr[m + 1] = {0, 3, 6, 9} // device memory - csr_col_ind[nnz] = {2, 0, 1, 0, 1, 2, 0, 2, 1}; // device memory - csr_val[nnz] = {3, 1, 2, 4, 5, 6, 7, 9, 8}; // device memory - - // Allocate temporary buffer - size_t buffer_size = 0; - void* temp_buffer = NULL; - rocsparse_csrsort_buffer_size(handle, m, n, nnz, csr_row_ptr, csr_col_ind, &buffer_size); - hipMalloc(&temp_buffer, sizeof(char) * buffer_size); - - // Create permutation vector perm as the identity map - rocsparse_int* perm = NULL; - hipMalloc((void**)&perm, sizeof(rocsparse_int) * nnz); - rocsparse_create_identity_permutation(handle, nnz, perm); - - // Sort the CSR matrix - rocsparse_csrsort(handle, m, n, nnz, descr, csr_row_ptr, csr_col_ind, perm, temp_buffer); - - // Gather sorted csr_val array - float* csr_val_sorted = NULL; - hipMalloc((void**)&csr_val_sorted, sizeof(float) * nnz); - rocsparse_sgthr(handle, nnz, csr_val, csr_val_sorted, perm, rocsparse_index_base_zero); - - // Clean up - hipFree(temp_buffer); - hipFree(perm); - hipFree(csr_val); - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -m number of rows of the sparse CSR matrix. -n number of columns of the sparse CSR matrix. -nnz number of non-zero entries of the sparse CSR matrix. -descr descriptor of the sparse CSR matrix. |br| Currently, *rocsparse_csrsort()* supports only ``rocsparse_matrix_type_general``. -csr_row_ptr array of ``m+1`` elements that point to the start of every row of the sparse CSR matrix. -csr_col_ind array of ``nnz`` elements containing the column indices of the sparse CSR matrix. -perm array of ``nnz`` integers containing the unsorted map indices, can be ``NULL``. -temp_buffer temporary storage buffer allocated by the user, |br| size is returned by :ref:`rocsparse_csrsort_buffer_size`. -=========== ============================================================================= - -=========== ================================ -Output -=========== ================================ -csr_col_ind array of ``nnz`` elements containing the column indices of the sparse CSR matrix. -perm array of ``nnz`` integers containing the unsorted map indices, if not ``NULL``. -=========== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m``, ``n`` or ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``descr``, ``csr_row_ptr``, ``csr_col_ind`` or |br| ``temp_buffer`` pointer is invalid. -rocsparse_status_internal_error an internal error occurred. -rocsparse_status_not_implemented ``rocsparse_matrix_type != rocsparse_matrix_type_general``. -================================ ==== - -.. _rocsparse_coosort_buffer_size: - -rocsparse_coosort_buffer_size +rocsparse_csr2ell_width() +************************* + +.. doxygenfunction:: rocsparse_csr2ell_width + +rocsparse_csr2ell() +******************* + +.. doxygenfunction:: rocsparse_scsr2ell + :outline: +.. doxygenfunction:: rocsparse_dcsr2ell + +rocsparse_ell2csr_nnz() +*********************** + +.. doxygenfunction:: rocsparse_ell2csr_nnz + +rocsparse_ell2csr() +******************* + +.. doxygenfunction:: rocsparse_sell2csr + :outline: +.. doxygenfunction:: rocsparse_dell2csr + +rocsparse_csr2hyb() +******************* + +.. doxygenfunction:: rocsparse_scsr2hyb + :outline: +.. doxygenfunction:: rocsparse_dcsr2hyb + +rocsparse_create_identity_permutation() +*************************************** + +.. doxygenfunction:: rocsparse_create_identity_permutation + +rocsparse_csrsort_buffer_size() +******************************* + +.. doxygenfunction:: rocsparse_csrsort_buffer_size + +rocsparse_csrsort() +******************* + +.. doxygenfunction:: rocsparse_csrsort + +rocsparse_coosort_buffer_size() +******************************* + +.. doxygenfunction:: rocsparse_coosort_buffer_size + +rocsparse_coosort_by_row() +************************** + +.. doxygenfunction:: rocsparse_coosort_by_row + +rocsparse_coosort_by_column() ***************************** -.. code-block:: c - - rocsparse_status - rocsparse_coosort_buffer_size(rocsparse_handle handle, - rocsparse_int m, - rocsparse_int n, - rocsparse_int nnz, - const rocsparse_int* coo_row_ind, - const rocsparse_int* coo_col_ind, - size_t* buffer_size); - -*rocsparse_coosort_buffer_size()* returns the size of the temporary storage buffer required by :ref:`rocsparse_coosort`. The temporary storage buffer must be allocated by the user. - -=========== ============================================================================= -Input -=========== ============================================================================= -handle handle to the rocSPARSE library context queue. -m number of rows of the sparse COO matrix. -n number of columns of the sparse COO matrix. -nnz number of non-zero entries of the sparse COO matrix. -coo_row_ind array of ``nnz`` elements containing the row indices of the sparse COO matrix. -coo_col_ind array of ``nnz`` elements containing the column indices of the sparse COO matrix. -=========== ============================================================================= - -=========== ================================ -Output -=========== ================================ -buffer_size number of bytes of the temporary storage buffer required by :ref:`rocsparse_coosort`. -=========== ================================ - -================================ ==== -Returned rocsparse_status -================================ ==== -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m``, ``n`` or ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``coo_row_ind``, ``coo_col_ind`` or ``buffer_size`` pointer is invalid. -rocsparse_status_internal_error an internal error occurred. -================================ ==== - -.. _rocsparse_coosort: - -rocsparse_coosort -***************** -.. code-block:: c - - rocsparse_status - rocsparse_coosort_by_row(rocsparse_handle handle, - rocsparse_int m, - rocsparse_int n, - rocsparse_int nnz, - rocsparse_int* coo_row_ind, - rocsparse_int* coo_col_ind, - rocsparse_int* perm, - void* temp_buffer); - - rocsparse_status - rocsparse_coosort_by_column(rocsparse_handle handle, - rocsparse_int m, - rocsparse_int n, - rocsparse_int nnz, - rocsparse_int* coo_row_ind, - rocsparse_int* coo_col_ind, - rocsparse_int* perm, - void* temp_buffer); - -*rocsparse_coosort_by_row/column()* sorts a matrix in COO format by row/column. The sorted permutation vector ``perm`` can be used to obtain sorted ``coo_val`` array. In this case, ``perm`` must be initialized as the identity permutation, see :ref:`rocsparse_create_identity_permutation`. - -*rocsparse_coosort_by_row/column()* requires extra temporary storage buffer that has to be allocated by the user. Storage buffer size can be determined by :ref:`rocsparse_coosort_buffer_size`. - -=========== ================================================================================================= -Input -=========== ================================================================================================= -handle handle to the rocSPARSE library context queue. -m number of rows of the sparse COO matrix. -n number of columns of the sparse COO matrix. -nnz number of non-zero entries of the sparse COO matrix. -coo_row_ind array of ``nnz`` elements containing the row indices of the sparse COO matrix. -coo_col_ind array of ``nnz`` elements containing the column indices of the sparse COO matrix. -perm array of ``nnz`` integers containing the unsorted map indices, can be ``NULL``. -temp_buffer temporary storage buffer allocated by the user, |br| size is returned by :ref:`rocsparse_coosort_buffer_size`. -=========== ================================================================================================= - -=========== ================================================================================= -Output -=========== ================================================================================= -coo_row_ind array of ``nnz`` elements containing the row indices of the sparse COO matrix. -coo_col_ind array of ``nnz`` elements containing the column indices of the sparse COO matrix. -perm array of ``nnz`` integers containing the unsorted map indices, if not ``NULL``. -=========== ================================================================================= - -================================ ======================================================================= -Returned rocsparse_status -================================ ======================================================================= -rocsparse_status_success the operation completed successfully. -rocsparse_status_invalid_handle the library context was not initialized. -rocsparse_status_invalid_size ``m``, ``n`` or ``nnz`` is invalid. -rocsparse_status_invalid_pointer ``coo_row_ind``, ``coo_col_ind`` or ``temp_buffer`` pointer is invalid. -rocsparse_status_internal_error an internal error occurred. -================================ ======================================================================= + +.. doxygenfunction:: rocsparse_coosort_by_column diff --git a/library/CMakeLists.txt b/library/CMakeLists.txt index 2324ef22..50c0a4c5 100644 --- a/library/CMakeLists.txt +++ b/library/CMakeLists.txt @@ -95,7 +95,7 @@ rocm_install_targets(TARGETS rocsparse # Export targets rocm_export_targets(TARGETS roc::rocsparse PREFIX rocsparse - DEPENDS PACKAGE hip + DEPENDS PACKAGE HIP NAMESPACE roc:: ) diff --git a/library/include/rocsparse-auxiliary.h b/library/include/rocsparse-auxiliary.h index 44ebdb03..18557042 100644 --- a/library/include/rocsparse-auxiliary.h +++ b/library/include/rocsparse-auxiliary.h @@ -50,9 +50,9 @@ extern "C" { * @param[out] * handle the pointer to the handle to the rocSPARSE library context. * - * \returns \ref rocsparse_status_success the initialization succeeded.
- * \ref rocsparse_status_invalid_handle \p handle pointer is invalid.
- * \ref rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_success the initialization succeeded. + * \retval rocsparse_status_invalid_handle \p handle pointer is invalid. + * \retval rocsparse_status_internal_error an internal error occurred. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_create_handle(rocsparse_handle* handle); @@ -67,9 +67,9 @@ rocsparse_status rocsparse_create_handle(rocsparse_handle* handle); * @param[in] * handle the handle to the rocSPARSE library context. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle \p handle is invalid.
- * \ref rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle \p handle is invalid. + * \retval rocsparse_status_internal_error an internal error occurred. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_destroy_handle(rocsparse_handle handle); @@ -86,8 +86,30 @@ rocsparse_status rocsparse_destroy_handle(rocsparse_handle handle); * @param[in] * stream the stream to be used by the rocSPARSE library context. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle \p handle is invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle \p handle is invalid. + * + * \par Example + * This example illustrates, how a user defined stream can be used in rocSPARSE. + * \code{.c} + * // Create rocSPARSE handle + * rocsparse_handle handle; + * rocsparse_create_handle(&handle); + * + * // Create stream + * hipStream_t stream; + * hipStreamCreate(&stream); + * + * // Set stream to rocSPARSE handle + * rocsparse_set_stream(handle, stream); + * + * // Do some work + * // ... + * + * // Clean up + * rocsparse_destroy_handle(handle); + * hipStreamDestroy(stream); + * \endcode */ ROCSPARSE_EXPORT rocsparse_status rocsparse_set_stream(rocsparse_handle handle, hipStream_t stream); @@ -104,8 +126,8 @@ rocsparse_status rocsparse_set_stream(rocsparse_handle handle, hipStream_t strea * @param[out] * stream the stream currently used by the rocSPARSE library context. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle \p handle is invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle \p handle is invalid. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_get_stream(rocsparse_handle handle, hipStream_t* stream); @@ -124,8 +146,8 @@ rocsparse_status rocsparse_get_stream(rocsparse_handle handle, hipStream_t* stre * @param[in] * pointer_mode the pointer mode to be used by the rocSPARSE library context. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle \p handle is invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle \p handle is invalid. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_set_pointer_mode(rocsparse_handle handle, @@ -144,8 +166,8 @@ rocsparse_status rocsparse_set_pointer_mode(rocsparse_handle handle, * pointer_mode the pointer mode that is currently used by the rocSPARSE library * context. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle \p handle is invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle \p handle is invalid. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_get_pointer_mode(rocsparse_handle handle, @@ -155,19 +177,18 @@ rocsparse_status rocsparse_get_pointer_mode(rocsparse_handle handle, * \brief Get rocSPARSE version * * \details - * rocsparse_get_version gets the rocSPARSE library version number. - * - * patch = version % 100
- * minor = version / 100 % 1000
- * major = version / 100000 + * \p rocsparse_get_version gets the rocSPARSE library version number. + * - patch = version % 100 + * - minor = version / 100 % 1000 + * - major = version / 100000 * * @param[in] * handle the handle to the rocSPARSE library context. * @param[out] * version the version number of the rocSPARSE library. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle \p handle is invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle \p handle is invalid. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_get_version(rocsparse_handle handle, int* version); @@ -183,8 +204,8 @@ rocsparse_status rocsparse_get_version(rocsparse_handle handle, int* version); * @param[out] * descr the pointer to the matrix descriptor. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_pointer \p descr pointer is invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_pointer \p descr pointer is invalid. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_create_mat_descr(rocsparse_mat_descr* descr); @@ -200,9 +221,8 @@ rocsparse_status rocsparse_create_mat_descr(rocsparse_mat_descr* descr); * @param[in] * src the pointer to the source matrix descriptor. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_pointer \p src or \p dest pointer is - * invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_pointer \p src or \p dest pointer is invalid. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_copy_mat_descr(rocsparse_mat_descr dest, const rocsparse_mat_descr src); @@ -217,8 +237,8 @@ rocsparse_status rocsparse_copy_mat_descr(rocsparse_mat_descr dest, const rocspa * @param[in] * descr the matrix descriptor. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_pointer \p descr is invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_pointer \p descr is invalid. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_destroy_mat_descr(rocsparse_mat_descr descr); @@ -235,9 +255,9 @@ rocsparse_status rocsparse_destroy_mat_descr(rocsparse_mat_descr descr); * @param[in] * base \ref rocsparse_index_base_zero or \ref rocsparse_index_base_one. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_pointer \p descr pointer is invalid.
- * \ref rocsparse_status_invalid_value \p base is invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_pointer \p descr pointer is invalid. + * \retval rocsparse_status_invalid_value \p base is invalid. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_set_mat_index_base(rocsparse_mat_descr descr, rocsparse_index_base base); @@ -251,7 +271,7 @@ rocsparse_status rocsparse_set_mat_index_base(rocsparse_mat_descr descr, rocspar * @param[in] * descr the matrix descriptor. * - * \returns \ref rocsparse_index_base_zero or \ref rocsparse_index_base_one. + * \returns \ref rocsparse_index_base_zero or \ref rocsparse_index_base_one. */ ROCSPARSE_EXPORT rocsparse_index_base rocsparse_get_mat_index_base(const rocsparse_mat_descr descr); @@ -272,9 +292,9 @@ rocsparse_index_base rocsparse_get_mat_index_base(const rocsparse_mat_descr desc * \ref rocsparse_matrix_type_hermitian or * \ref rocsparse_matrix_type_triangular. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_pointer \p descr pointer is invalid.
- * \ref rocsparse_status_invalid_value \p type is invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_pointer \p descr pointer is invalid. + * \retval rocsparse_status_invalid_value \p type is invalid. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_set_mat_type(rocsparse_mat_descr descr, rocsparse_matrix_type type); @@ -308,9 +328,9 @@ rocsparse_matrix_type rocsparse_get_mat_type(const rocsparse_mat_descr descr); * @param[in] * fill_mode \ref rocsparse_fill_mode_lower or \ref rocsparse_fill_mode_upper. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_pointer \p descr pointer is invalid.
- * \ref rocsparse_status_invalid_value \p fill_mode is invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_pointer \p descr pointer is invalid. + * \retval rocsparse_status_invalid_value \p fill_mode is invalid. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_set_mat_fill_mode(rocsparse_mat_descr descr, @@ -343,9 +363,9 @@ rocsparse_fill_mode rocsparse_get_mat_fill_mode(const rocsparse_mat_descr descr) * @param[in] * diag_type \ref rocsparse_diag_type_unit or \ref rocsparse_diag_type_non_unit. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_pointer \p descr pointer is invalid.
- * \ref rocsparse_status_invalid_value \p diag_type is invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_pointer \p descr pointer is invalid. + * \retval rocsparse_status_invalid_value \p diag_type is invalid. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_set_mat_diag_type(rocsparse_mat_descr descr, @@ -376,8 +396,8 @@ rocsparse_diag_type rocsparse_get_mat_diag_type(const rocsparse_mat_descr descr) * @param[inout] * hyb the pointer to the hybrid matrix. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_pointer \p hyb pointer is invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_pointer \p hyb pointer is invalid. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_create_hyb_mat(rocsparse_hyb_mat* hyb); @@ -389,11 +409,11 @@ rocsparse_status rocsparse_create_hyb_mat(rocsparse_hyb_mat* hyb); * \p rocsparse_destroy_hyb_mat destroys a \p HYB structure. * * @param[in] - * hyb + * hyb the hybrid matrix structure. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_pointer \p hyb pointer is invalid.
- * \ref rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_pointer \p hyb pointer is invalid. + * \retval rocsparse_status_internal_error an internal error occurred. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_destroy_hyb_mat(rocsparse_hyb_mat hyb); @@ -407,10 +427,10 @@ rocsparse_status rocsparse_destroy_hyb_mat(rocsparse_hyb_mat hyb); * at the end using rocsparse_destroy_mat_info(). * * @param[inout] - * info + * info the pointer to the info structure. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_pointer \p info pointer is invalid.
+ * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_pointer \p info pointer is invalid. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_create_mat_info(rocsparse_mat_info* info); @@ -422,11 +442,11 @@ rocsparse_status rocsparse_create_mat_info(rocsparse_mat_info* info); * \p rocsparse_destroy_mat_info destroys a matrix info structure. * * @param[in] - * info + * info the info structure. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_pointer \p info pointer is invalid.
- * \ref rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_pointer \p info pointer is invalid. + * \retval rocsparse_status_internal_error an internal error occurred. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_destroy_mat_info(rocsparse_mat_info info); diff --git a/library/include/rocsparse-functions.h b/library/include/rocsparse-functions.h index fa785f8f..b6ff3f86 100644 --- a/library/include/rocsparse-functions.h +++ b/library/include/rocsparse-functions.h @@ -50,9 +50,9 @@ extern "C" { * \p rocsparse_axpyi multiplies the sparse vector \f$x\f$ with scalar \f$\alpha\f$ and * adds the result to the dense vector \f$y\f$, such that * - * \f$ + * \f[ * y := y + \alpha \cdot x - * \f$ + * \f] * * \code{.c} * for(i = 0; i < nnz; ++i) @@ -61,6 +61,10 @@ extern "C" { * } * \endcode * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] @@ -77,13 +81,12 @@ extern "C" { * @param[in] * idx_base \ref rocsparse_index_base_zero or \ref rocsparse_index_base_one. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was not - * initialized.
- * \ref rocsparse_status_invalid_value \p idx_base is invalid.
- * \ref rocsparse_status_invalid_size \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p alpha, \p x_val, \p x_ind or - * \p y pointer is invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_value \p idx_base is invalid. + * \retval rocsparse_status_invalid_size \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p alpha, \p x_val, \p x_ind or \p y pointer + * is invalid. */ /**@{*/ ROCSPARSE_EXPORT @@ -130,8 +133,9 @@ rocsparse_status rocsparse_zaxpyi(rocsparse_handle handle, * \details * \p rocsparse_doti computes the dot product of the sparse vector \f$x\f$ with the * dense vector \f$y\f$, such that - * - * \f$\text{result} := y^T x\f$ + * \f[ + * \text{result} := y^T x + * \f] * * \code{.c} * for(i = 0; i < nnz; ++i) @@ -140,6 +144,10 @@ rocsparse_status rocsparse_zaxpyi(rocsparse_handle handle, * } * \endcode * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] @@ -156,16 +164,15 @@ rocsparse_status rocsparse_zaxpyi(rocsparse_handle handle, * @param[in] * idx_base \ref rocsparse_index_base_zero or \ref rocsparse_index_base_one. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was not - * initialized.
- * \ref rocsparse_status_invalid_value \p idx_base is invalid.
- * \ref rocsparse_status_invalid_size \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p x_val, \p x_ind, \p y or - * \p result pointer is invalid.
- * \ref rocsparse_status_memory_error the buffer for the dot product - * reduction could not be allocated.
- * \ref rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_value \p idx_base is invalid. + * \retval rocsparse_status_invalid_size \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p x_val, \p x_ind, \p y or \p result + * pointer is invalid. + * \retval rocsparse_status_memory_error the buffer for the dot product reduction + * could not be allocated. + * \retval rocsparse_status_internal_error an internal error occurred. */ /**@{*/ ROCSPARSE_EXPORT @@ -220,6 +227,10 @@ rocsparse_status rocsparse_zdoti(rocsparse_handle handle, * } * \endcode * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] @@ -234,13 +245,12 @@ rocsparse_status rocsparse_zdoti(rocsparse_handle handle, * @param[in] * idx_base \ref rocsparse_index_base_zero or \ref rocsparse_index_base_one. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was not - * initialized.
- * \ref rocsparse_status_invalid_value \p idx_base is invalid.
- * \ref rocsparse_status_invalid_size \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p y, \p x_val or \p x_ind pointer - * is invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_value \p idx_base is invalid. + * \retval rocsparse_status_invalid_size \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p y, \p x_val or \p x_ind pointer is + * invalid. */ /**@{*/ ROCSPARSE_EXPORT @@ -294,6 +304,10 @@ rocsparse_status rocsparse_zgthr(rocsparse_handle handle, * } * \endcode * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] @@ -308,13 +322,12 @@ rocsparse_status rocsparse_zgthr(rocsparse_handle handle, * @param[in] * idx_base \ref rocsparse_index_base_zero or \ref rocsparse_index_base_one. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was not - * initialized.
- * \ref rocsparse_status_invalid_value \p idx_base is invalid.
- * \ref rocsparse_status_invalid_size \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p y, \p x_val or \p x_ind pointer - * is invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_value \p idx_base is invalid. + * \retval rocsparse_status_invalid_size \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p y, \p x_val or \p x_ind pointer is + * invalid. */ /**@{*/ ROCSPARSE_EXPORT @@ -357,8 +370,9 @@ rocsparse_status rocsparse_zgthrz(rocsparse_handle handle, * \details * \p rocsparse_roti applies the Givens rotation matrix \f$G\f$ to the sparse vector * \f$x\f$ and the dense vector \f$y\f$, where - * - * \f$G = \begin{pmatrix} c & s \\ -s & c \end{pmatrix}\f$ + * \f[ + * G = \begin{pmatrix} c & s \\ -s & c \end{pmatrix} + * \f] * * \code{.c} * for(i = 0; i < nnz; ++i) @@ -371,6 +385,10 @@ rocsparse_status rocsparse_zgthrz(rocsparse_handle handle, * } * \endcode * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] @@ -389,13 +407,12 @@ rocsparse_status rocsparse_zgthrz(rocsparse_handle handle, * @param[in] * idx_base \ref rocsparse_index_base_zero or \ref rocsparse_index_base_one. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was not - * initialized.
- * \ref rocsparse_status_invalid_value \p idx_base is invalid.
- * \ref rocsparse_status_invalid_size \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p c, \p s, \p x_val, \p x_ind or - * \p y pointer is invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_value \p idx_base is invalid. + * \retval rocsparse_status_invalid_size \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p c, \p s, \p x_val, \p x_ind or \p y + * pointer is invalid. */ /**@{*/ ROCSPARSE_EXPORT @@ -434,6 +451,10 @@ rocsparse_status rocsparse_droti(rocsparse_handle handle, * } * \endcode * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] @@ -448,13 +469,12 @@ rocsparse_status rocsparse_droti(rocsparse_handle handle, * @param[in] * idx_base \ref rocsparse_index_base_zero or \ref rocsparse_index_base_one. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was not - * initialized.
- * \ref rocsparse_status_invalid_value \p idx_base is invalid.
- * \ref rocsparse_status_invalid_size \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p x_val, \p x_ind or \p y pointer - * is invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_value \p idx_base is invalid. + * \retval rocsparse_status_invalid_size \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p x_val, \p x_ind or \p y pointer is + * invalid. */ /**@{*/ ROCSPARSE_EXPORT @@ -498,29 +518,28 @@ rocsparse_status rocsparse_zsctr(rocsparse_handle handle, */ /*! \ingroup level2_module - * \brief Sparse matrix vector multiplication using \p COO storage format + * \brief Sparse matrix vector multiplication using COO storage format * * \details * \p rocsparse_coomv multiplies the scalar \f$\alpha\f$ with a sparse \f$m \times n\f$ - * matrix, defined in \p COO storage format, and the dense vector \f$x\f$ and adds the + * matrix, defined in COO storage format, and the dense vector \f$x\f$ and adds the * result to the dense vector \f$y\f$ that is multiplied by the scalar \f$\beta\f$, * such that - * - * \f$y := \alpha \cdot op(A) \cdot x + \beta \cdot y\f$, with - * - * \f$ - * op(A) = \left\{ - * \begin{array}{ll} - * A, & \text{if trans == rocsparse_operation_none} \\ - * A^T, & \text{if trans == rocsparse_operation_transpose} \\ - * A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} - * \end{array} - * \right. - * \f$ - * - * Currently, only \p trans == \ref rocsparse_operation_none is supported. - * - * The \p COO matrix has to be sorted by row indices. This can be achieved by using + * \f[ + * y := \alpha \cdot op(A) \cdot x + \beta \cdot y, + * \f] + * with + * \f[ + * op(A) = \left\{ + * \begin{array}{ll} + * A, & \text{if trans == rocsparse_operation_none} \\ + * A^T, & \text{if trans == rocsparse_operation_transpose} \\ + * A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} + * \end{array} + * \right. + * \f] + * + * The COO matrix has to be sorted by row indices. This can be achieved by using * rocsparse_coosort_by_row(). * * \code{.c} @@ -535,29 +554,36 @@ rocsparse_status rocsparse_zsctr(rocsparse_handle handle, * } * \endcode * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * + * \note + * Currently, only \p trans == \ref rocsparse_operation_none is supported. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] * trans matrix operation type. * @param[in] - * m number of rows of the sparse \p COO matrix. + * m number of rows of the sparse COO matrix. * @param[in] - * n number of columns of the sparse \p COO matrix. + * n number of columns of the sparse COO matrix. * @param[in] - * nnz number of non-zero entries of the sparse \p COO matrix. + * nnz number of non-zero entries of the sparse COO matrix. * @param[in] * alpha scalar \f$\alpha\f$. * @param[in] - * descr descriptor of the sparse \p COO matrix. Currently, only + * descr descriptor of the sparse COO matrix. Currently, only * \ref rocsparse_matrix_type_general is supported. * @param[in] - * coo_val array of \p nnz elements of the sparse \p COO matrix. + * coo_val array of \p nnz elements of the sparse COO matrix. * @param[in] - * coo_row_ind array of \p nnz elements containing the row indices of the sparse \p COO + * coo_row_ind array of \p nnz elements containing the row indices of the sparse COO * matrix. * @param[in] * coo_col_ind array of \p nnz elements containing the column indices of the sparse - * \p COO matrix. + * COO matrix. * @param[in] * x array of \p n elements (\f$op(A) = A\f$) or \p m elements * (\f$op(A) = A^T\f$ or \f$op(A) = A^H\f$). @@ -567,15 +593,13 @@ rocsparse_status rocsparse_zsctr(rocsparse_handle handle, * y array of \p m elements (\f$op(A) = A\f$) or \p n elements * (\f$op(A) = A^T\f$ or \f$op(A) = A^H\f$). * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p descr, \p alpha, \p coo_val, - * \p coo_row_ind, \p coo_col_ind, \p x, \p beta or \p y pointer is - * invalid.
- * \ref rocsparse_status_arch_mismatch the device is not supported.
- * \ref rocsparse_status_not_implemented + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p descr, \p alpha, \p coo_val, + * \p coo_row_ind, \p coo_col_ind, \p x, \p beta or \p y pointer is invalid. + * \retval rocsparse_status_arch_mismatch the device is not supported. + * \retval rocsparse_status_not_implemented * \p trans != \ref rocsparse_operation_none or * \ref rocsparse_matrix_type != \ref rocsparse_matrix_type_general. */ @@ -643,48 +667,53 @@ rocsparse_status rocsparse_zcoomv(rocsparse_handle handle, /**@}*/ /*! \ingroup level2_module - * \brief Sparse matrix vector multiplication using \p CSR storage format + * \brief Sparse matrix vector multiplication using CSR storage format * * \details * \p rocsparse_csrmv_analysis performs the analysis step for rocsparse_scsrmv() and * rocsparse_dcsrmv(). It is expected that this function will be executed only once for - * a given matrix and particular operation type. Note that if the matrix sparsity - * pattern changes, the gathered information will become invalid. The gathered analysis - * meta data can be cleared by rocsparse_csrmv_clear(). + * a given matrix and particular operation type. The gathered analysis meta data can be + * cleared by rocsparse_csrmv_clear(). + * + * \note + * If the matrix sparsity pattern changes, the gathered information will become invalid. + * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] * trans matrix operation type. * @param[in] - * m number of rows of the sparse \p CSR matrix. + * m number of rows of the sparse CSR matrix. * @param[in] - * n number of columns of the sparse \p CSR matrix. + * n number of columns of the sparse CSR matrix. * @param[in] - * nnz number of non-zero entries of the sparse \p CSR matrix. + * nnz number of non-zero entries of the sparse CSR matrix. * @param[in] - * descr descriptor of the sparse \p CSR matrix. + * descr descriptor of the sparse CSR matrix. * @param[in] - * csr_val array of \p nnz elements of the sparse \p CSR matrix. + * csr_val array of \p nnz elements of the sparse CSR matrix. * @param[in] * csr_row_ptr array of \p m+1 elements that point to the start of every row of the - * sparse \p CSR matrix. + * sparse CSR matrix. * @param[in] * csr_col_ind array of \p nnz elements containing the column indices of the sparse - * \p CSR matrix. + * CSR matrix. * @param[out] * info structure that holds the information collected during the analysis step. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p descr, \p csr_val, - * \p csr_row_ptr, \p csr_col_ind or \p info pointer is invalid.
- * \ref rocsparse_status_memory_error the buffer for the gathered - * information could not be allocated.
- * \ref rocsparse_status_internal_error an internal error occurred.
- * \ref rocsparse_status_not_implemented + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p descr, \p csr_val, \p csr_row_ptr, + * \p csr_col_ind or \p info pointer is invalid. + * \retval rocsparse_status_memory_error the buffer for the gathered information + * could not be allocated. + * \retval rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_not_implemented * \p trans != \ref rocsparse_operation_none or * \ref rocsparse_matrix_type != \ref rocsparse_matrix_type_general. */ @@ -715,59 +744,60 @@ rocsparse_status rocsparse_dcsrmv_analysis(rocsparse_handle handle, /**@}*/ /*! \ingroup level2_module - * \brief Sparse matrix vector multiplication using \p CSR storage format + * \brief Sparse matrix vector multiplication using CSR storage format * * \details * \p rocsparse_csrmv_clear deallocates all memory that was allocated by - * rocsparse_csrmv_analysis(). This is especially useful, if memory is an issue and the - * analysis data is not required anymore for further computation, e.g. when switching - * to another sparse matrix format. Calling \p rocsparse_csrmv_clear is optional. All - * allocated resources will be cleared, when the opaque \ref rocsparse_mat_info struct is - * destroyed using rocsparse_destroy_mat_info(). + * rocsparse_scsrmv_analysis() or rocsparse_dcsrmv_analysis(). This is especially + * useful, if memory is an issue and the analysis data is not required anymore for + * further computation, e.g. when switching to another sparse matrix format. + * + * \note + * Calling \p rocsparse_csrmv_clear is optional. All allocated resources will be + * cleared, when the opaque \ref rocsparse_mat_info struct is destroyed using + * rocsparse_destroy_mat_info(). * * @param[in] * handle handle to the rocsparse library context queue. * @param[inout] * info structure that holds the information collected during analysis step. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_pointer \p info pointer is invalid.
- * \ref rocsparse_status_memory_error the buffer for the gathered - * information could not be deallocated.
- * \ref rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_pointer \p info pointer is invalid. + * \retval rocsparse_status_memory_error the buffer for the gathered information + * could not be deallocated. + * \retval rocsparse_status_internal_error an internal error occurred. * */ ROCSPARSE_EXPORT rocsparse_status rocsparse_csrmv_clear(rocsparse_handle handle, rocsparse_mat_info info); /*! \ingroup level2_module - * \brief Sparse matrix vector multiplication using \p CSR storage format + * \brief Sparse matrix vector multiplication using CSR storage format * * \details * \p rocsparse_csrmv multiplies the scalar \f$\alpha\f$ with a sparse \f$m \times n\f$ - * matrix, defined in \p CSR storage format, and the dense vector \f$x\f$ and adds the + * matrix, defined in CSR storage format, and the dense vector \f$x\f$ and adds the * result to the dense vector \f$y\f$ that is multiplied by the scalar \f$\beta\f$, * such that - * - * \f$y := \alpha \cdot op(A) \cdot x + \beta \cdot y\f$, with - * - * \f$ - * op(A) = \left\{ - * \begin{array}{ll} - * A, & \text{if trans == rocsparse_operation_none} \\ - * A^T, & \text{if trans == rocsparse_operation_transpose} \\ - * A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} - * \end{array} - * \right. - * \f$ + * \f[ + * y := \alpha \cdot op(A) \cdot x + \beta \cdot y, + * \f] + * with + * \f[ + * op(A) = \left\{ + * \begin{array}{ll} + * A, & \text{if trans == rocsparse_operation_none} \\ + * A^T, & \text{if trans == rocsparse_operation_transpose} \\ + * A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} + * \end{array} + * \right. + * \f] * * The \p info parameter is optional and contains information collected by - * rocsparse_csrmv_analysis(). If present, the information will be used to speed up the - * \p csrmv computation. If \p info == \p NULL, general \p csrmv routine will be used - * instead. - * - * Currently, only \p trans == \ref rocsparse_operation_none is supported. + * rocsparse_scsrmv_analysis() or rocsparse_dcsrmv_analysis(). If present, the + * information will be used to speed up the \p csrmv computation. If \p info == \p NULL, + * general \p csrmv routine will be used instead. * * \code{.c} * for(i = 0; i < m; ++i) @@ -781,32 +811,40 @@ rocsparse_status rocsparse_csrmv_clear(rocsparse_handle handle, rocsparse_mat_in * } * \endcode * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * + * \note + * Currently, only \p trans == \ref rocsparse_operation_none is supported. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] * trans matrix operation type. * @param[in] - * m number of rows of the sparse \p CSR matrix. + * m number of rows of the sparse CSR matrix. * @param[in] - * n number of columns of the sparse \p CSR matrix. + * n number of columns of the sparse CSR matrix. * @param[in] - * nnz number of non-zero entries of the sparse \p CSR matrix. + * nnz number of non-zero entries of the sparse CSR matrix. * @param[in] * alpha scalar \f$\alpha\f$. * @param[in] - * descr descriptor of the sparse \p CSR matrix. Currently, only + * descr descriptor of the sparse CSR matrix. Currently, only * \ref rocsparse_matrix_type_general is supported. * @param[in] - * csr_val array of \p nnz elements of the sparse \p CSR matrix. + * csr_val array of \p nnz elements of the sparse CSR matrix. * @param[in] * csr_row_ptr array of \p m+1 elements that point to the start - * of every row of the sparse \p CSR matrix. + * of every row of the sparse CSR matrix. * @param[in] * csr_col_ind array of \p nnz elements containing the column indices of the sparse - * \p CSR matrix. + * CSR matrix. * @param[in] - * info information collected by rocsparse_csrmv_analysis(), can be \p NULL if - * no information is available. + * info information collected by rocsparse_scsrmv_analysis() or + * rocsparse_dcsrmv_analysis(), can be \p NULL if no information is + * available. * @param[in] * x array of \p n elements (\f$op(A) == A\f$) or \p m elements * (\f$op(A) == A^T\f$ or \f$op(A) == A^H\f$). @@ -816,17 +854,59 @@ rocsparse_status rocsparse_csrmv_clear(rocsparse_handle handle, rocsparse_mat_in * y array of \p m elements (\f$op(A) == A\f$) or \p n elements * (\f$op(A) == A^T\f$ or \f$op(A) == A^H\f$). * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p descr, \p alpha, \p csr_val, + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p descr, \p alpha, \p csr_val, * \p csr_row_ptr, \p csr_col_ind, \p x, \p beta or \p y pointer is - * invalid.
- * \ref rocsparse_status_arch_mismatch the device is not supported.
- * \ref rocsparse_status_not_implemented + * invalid. + * \retval rocsparse_status_arch_mismatch the device is not supported. + * \retval rocsparse_status_not_implemented * \p trans != \ref rocsparse_operation_none or * \ref rocsparse_matrix_type != \ref rocsparse_matrix_type_general. + * + * \par Example + * This example performs a sparse matrix vector multiplication in CSR format + * using additional meta data to improve performance. + * \code{.c} + * // Create matrix info structure + * rocsparse_mat_info info; + * rocsparse_create_mat_info(&info); + * + * // Perform analysis step to obtain meta data + * rocsparse_scsrmv_analysis(handle, + * rocsparse_operation_none, + * m, + * n, + * nnz, + * descr, + * csr_val, + * csr_row_ptr, + * csr_col_ind, + * info); + * + * // Compute y = Ax + * rocsparse_scsrmv(handle, + * rocsparse_operation_none, + * m, + * n, + * nnz, + * &alpha, + * descr, + * csr_val, + * csr_row_ptr, + * csr_col_ind, + * info, + * x, + * &beta, + * y); + * + * // Do more work + * // ... + * + * // Clean up + * rocsparse_destroy_mat_info(info); + * \endcode */ /**@{*/ ROCSPARSE_EXPORT @@ -896,13 +976,13 @@ rocsparse_status rocsparse_zcsrmv(rocsparse_handle handle, /**@}*/ /*! \ingroup level2_module - * \brief Sparse triangular solve using \p CSR storage format + * \brief Sparse triangular solve using CSR storage format * * \details * \p rocsparse_csrsv_zero_pivot returns \ref rocsparse_status_zero_pivot, if either a * structural or numerical zero has been found during rocsparse_scsrsv_solve() or * rocsparse_dcsrsv_solve() computation. The first zero pivot \f$j\f$ at \f$A_{j,j}\f$ - * is stored in \p position, using same index base as the \p CSR matrix. + * is stored in \p position, using same index base as the CSR matrix. * * \p position can be in host or device memory. If no zero pivot has been found, * \p position is set to -1 and \ref rocsparse_status_success is returned instead. @@ -910,19 +990,18 @@ rocsparse_status rocsparse_zcsrmv(rocsparse_handle handle, * @param[in] * handle handle to the rocsparse library context queue. * @param[in] - * descr descriptor of the sparse \p CSR matrix. + * descr descriptor of the sparse CSR matrix. * @param[in] * info structure that holds the information collected during the analysis step. * @param[inout] * position pointer to zero pivot \f$j\f$, can be in host or device memory. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was not - * initialized.
- * \ref rocsparse_status_invalid_pointer \p info or \p position - * pointer is invalid.
- * \ref rocsparse_status_internal_error an internal error occurred.
- * \ref rocsparse_status_zero_pivot zero pivot has been found. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_pointer \p info or \p position pointer is + * invalid. + * \retval rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_zero_pivot zero pivot has been found. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_csrsv_zero_pivot(rocsparse_handle handle, @@ -931,7 +1010,7 @@ rocsparse_status rocsparse_csrsv_zero_pivot(rocsparse_handle handle, rocsparse_int* position); /*! \ingroup level2_module - * \brief Sparse triangular solve using \p CSR storage format + * \brief Sparse triangular solve using CSR storage format * * \details * \p rocsparse_csrsv_buffer_size returns the size of the temporary storage buffer that @@ -947,19 +1026,19 @@ rocsparse_status rocsparse_csrsv_zero_pivot(rocsparse_handle handle, * @param[in] * trans matrix operation type. * @param[in] - * m number of rows of the sparse \p CSR matrix. + * m number of rows of the sparse CSR matrix. * @param[in] - * nnz number of non-zero entries of the sparse \p CSR matrix. + * nnz number of non-zero entries of the sparse CSR matrix. * @param[in] - * descr descriptor of the sparse \p CSR matrix. + * descr descriptor of the sparse CSR matrix. * @param[in] - * csr_val array of \p nnz elements of the sparse \p CSR matrix. + * csr_val array of \p nnz elements of the sparse CSR matrix. * @param[in] * csr_row_ptr array of \p m+1 elements that point to the start of every row of the - * sparse \p CSR matrix. + * sparse CSR matrix. * @param[in] * csr_col_ind array of \p nnz elements containing the column indices of the sparse - * \p CSR matrix. + * CSR matrix. * @param[out] * info structure that holds the information collected during the analysis step. * @param[in] @@ -967,15 +1046,13 @@ rocsparse_status rocsparse_csrsv_zero_pivot(rocsparse_handle handle, * rocsparse_scsrsv_analysis(), rocsparse_dcsrsv_analysis(), * rocsparse_scsrsv_solve() and rocsparse_dcsrsv_solve(). * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m or \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p descr, \p csr_val, - * \p csr_row_ptr, \p csr_col_ind, \p info or \p buffer_size pointer is - * invalid.
- * \ref rocsparse_status_internal_error an internal error occurred.
- * \ref rocsparse_status_not_implemented + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m or \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p descr, \p csr_val, \p csr_row_ptr, + * \p csr_col_ind, \p info or \p buffer_size pointer is invalid. + * \retval rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_not_implemented * \p trans != \ref rocsparse_operation_none or * \ref rocsparse_matrix_type != \ref rocsparse_matrix_type_general. */ @@ -1006,14 +1083,13 @@ rocsparse_status rocsparse_dcsrsv_buffer_size(rocsparse_handle handle, /**@}*/ /*! \ingroup level2_module - * \brief Sparse triangular solve using \p CSR storage format + * \brief Sparse triangular solve using CSR storage format * * \details * \p rocsparse_csrsv_analysis performs the analysis step for rocsparse_scsrsv_solve() * and rocsparse_dcsrsv_solve(). It is expected that this function will be executed only - * once for a given matrix and particular operation type. Note that if the matrix - * sparsity pattern changes, the gathered information will become invalid. The analysis - * meta data can be cleared by rocsparse_csrsv_clear(). + * once for a given matrix and particular operation type. The analysis meta data can be + * cleared by rocsparse_csrsv_clear(). * * \p rocsparse_csrsv_analysis can share its meta data with * rocsparse_scsrilu0_analysis() and rocsparse_dcsrilu0_analysis(). Selecting @@ -1022,24 +1098,31 @@ rocsparse_status rocsparse_dcsrsv_buffer_size(rocsparse_handle handle, * pattern remains unchanged. If this cannot be assured, * \ref rocsparse_analysis_policy_force has to be used. * + * \note + * If the matrix sparsity pattern changes, the gathered information will become invalid. + * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] * trans matrix operation type. * @param[in] - * m number of rows of the sparse \p CSR matrix. + * m number of rows of the sparse CSR matrix. * @param[in] - * nnz number of non-zero entries of the sparse \p CSR matrix. + * nnz number of non-zero entries of the sparse CSR matrix. * @param[in] - * descr descriptor of the sparse \p CSR matrix. + * descr descriptor of the sparse CSR matrix. * @param[in] - * csr_val array of \p nnz elements of the sparse \p CSR matrix. + * csr_val array of \p nnz elements of the sparse CSR matrix. * @param[in] * csr_row_ptr array of \p m+1 elements that point to the start of every row of the - * sparse \p CSR matrix. + * sparse CSR matrix. * @param[in] * csr_col_ind array of \p nnz elements containing the column indices of the sparse - * \p CSR matrix. + * CSR matrix. * @param[out] * info structure that holds the information collected during * the analysis step. @@ -1051,14 +1134,13 @@ rocsparse_status rocsparse_dcsrsv_buffer_size(rocsparse_handle handle, * @param[in] * temp_buffer temporary storage buffer allocated by the user. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m or \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p descr, \p csr_row_ptr, - * \p csr_col_ind, \p info or \p temp_buffer pointer is invalid.
- * \ref rocsparse_status_internal_error an internal error occurred.
- * \ref rocsparse_status_not_implemented + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m or \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p descr, \p csr_row_ptr, + * \p csr_col_ind, \p info or \p temp_buffer pointer is invalid. + * \retval rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_not_implemented * \p trans != \ref rocsparse_operation_none or * \ref rocsparse_matrix_type != \ref rocsparse_matrix_type_general. */ @@ -1093,7 +1175,7 @@ rocsparse_status rocsparse_dcsrsv_analysis(rocsparse_handle handle, /**@}*/ /*! \ingroup level2_module - * \brief Sparse triangular solve using \p CSR storage format + * \brief Sparse triangular solve using CSR storage format * * \details * \p rocsparse_csrsv_clear deallocates all memory that was allocated by @@ -1107,17 +1189,16 @@ rocsparse_status rocsparse_dcsrsv_analysis(rocsparse_handle handle, * @param[in] * handle handle to the rocsparse library context queue. * @param[in] - * descr descriptor of the sparse \p CSR matrix. + * descr descriptor of the sparse CSR matrix. * @param[inout] * info structure that holds the information collected during the analysis step. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_pointer \p info pointer is invalid.
- * \ref rocsparse_status_memory_error the buffer holding the meta data - * could not be deallocated.
- * \ref rocsparse_status_internal_error an internal error occurred.
+ * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_pointer \p info pointer is invalid. + * \retval rocsparse_status_memory_error the buffer holding the meta data could not + * be deallocated. + * \retval rocsparse_status_internal_error an internal error occurred. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_csrsv_clear(rocsparse_handle handle, @@ -1125,26 +1206,25 @@ rocsparse_status rocsparse_csrsv_clear(rocsparse_handle handle, rocsparse_mat_info info); /*! \ingroup level2_module - * \brief Sparse triangular solve using \p CSR storage format + * \brief Sparse triangular solve using CSR storage format * * \details * \p rocsparse_csrsv_solve solves a sparse triangular linear system of a sparse - * \f$m \times m\f$ matrix, defined in \p CSR storage format, a dense solution vector + * \f$m \times m\f$ matrix, defined in CSR storage format, a dense solution vector * \f$y\f$ and the right-hand side \f$x\f$ that is multiplied by \f$\alpha\f$, such that - * - * \f$op(A) * y = \alpha * x\f$, with - * - * \f$ - * op(A) = \left\{ - * \begin{array}{ll} - * A, & \text{if trans == rocsparse_operation_none} \\ - * A^T, & \text{if trans == rocsparse_operation_transpose} \\ - * A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} - * \end{array} - * \right. - * \f$ - * - * Currently, only \p trans == \ref rocsparse_operation_none is supported. + * \f[ + * op(A) \cdot y = \alpha \cdot x, + * \f] + * with + * \f[ + * op(A) = \left\{ + * \begin{array}{ll} + * A, & \text{if trans == rocsparse_operation_none} \\ + * A^T, & \text{if trans == rocsparse_operation_transpose} \\ + * A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} + * \end{array} + * \right. + * \f] * * \p rocsparse_csrsv_solve requires a user allocated temporary buffer. Its size is * returned by rocsparse_scsrsv_buffer_size() or rocsparse_dcsrsv_buffer_size(). @@ -1155,29 +1235,37 @@ rocsparse_status rocsparse_csrsv_clear(rocsparse_handle handle, * If \ref rocsparse_diag_type == \ref rocsparse_diag_type_unit, no zero pivot will be * reported, even if \f$A_{j,j} = 0\f$ for some \f$j\f$. * - * Note that the sparse \p CSR matrix has to be sorted. This can be achieved by calling + * \note + * The sparse CSR matrix has to be sorted. This can be achieved by calling * rocsparse_csrsort(). * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * + * \note + * Currently, only \p trans == \ref rocsparse_operation_none is supported. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] * trans matrix operation type. * @param[in] - * m number of rows of the sparse \p CSR matrix. + * m number of rows of the sparse CSR matrix. * @param[in] - * nnz number of non-zero entries of the sparse \p CSR matrix. + * nnz number of non-zero entries of the sparse CSR matrix. * @param[in] * alpha scalar \f$\alpha\f$. * @param[in] - * descr descriptor of the sparse \p CSR matrix. + * descr descriptor of the sparse CSR matrix. * @param[in] - * csr_val array of \p nnz elements of the sparse \p CSR matrix. + * csr_val array of \p nnz elements of the sparse CSR matrix. * @param[in] * csr_row_ptr array of \p m+1 elements that point to the start - * of every row of the sparse \p CSR matrix. + * of every row of the sparse CSR matrix. * @param[in] * csr_col_ind array of \p nnz elements containing the column indices of the sparse - * \p CSR matrix. + * CSR matrix. * @param[in] * info structure that holds the information collected during the analysis step. * @param[in] @@ -1189,20 +1277,19 @@ rocsparse_status rocsparse_csrsv_clear(rocsparse_handle handle, * @param[in] * temp_buffer temporary storage buffer allocated by the user. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m or \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p descr, \p alpha, \p csr_val, - * \p csr_row_ptr, \p csr_col_ind, \p x or \p y pointer is invalid.
- * \ref rocsparse_status_arch_mismatch the device is not supported.
- * \ref rocsparse_status_internal_error an internal error occurred.
- * \ref rocsparse_status_not_implemented + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m or \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p descr, \p alpha, \p csr_val, + * \p csr_row_ptr, \p csr_col_ind, \p x or \p y pointer is invalid. + * \retval rocsparse_status_arch_mismatch the device is not supported. + * \retval rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_not_implemented * \p trans != \ref rocsparse_operation_none or * \ref rocsparse_matrix_type != \ref rocsparse_matrix_type_general. * * \par Example - * Consider the lower triangular \f$m \times m\f$ matrix \f$L\f$, stored in \p CSR + * Consider the lower triangular \f$m \times m\f$ matrix \f$L\f$, stored in CSR * storage format with unit diagonal. The following example solves \f$L \cdot y = x\f$. * \code{.c} * // Create rocSPARSE handle @@ -1310,27 +1397,26 @@ rocsparse_status rocsparse_dcsrsv_solve(rocsparse_handle handle, /**@}*/ /*! \ingroup level2_module - * \brief Sparse matrix vector multiplication using \p ELL storage format + * \brief Sparse matrix vector multiplication using ELL storage format * * \details * \p rocsparse_ellmv multiplies the scalar \f$\alpha\f$ with a sparse \f$m \times n\f$ - * matrix, defined in \p ELL storage format, and the dense vector \f$x\f$ and adds the + * matrix, defined in ELL storage format, and the dense vector \f$x\f$ and adds the * result to the dense vector \f$y\f$ that is multiplied by the scalar \f$\beta\f$, * such that - * - * \f$y := \alpha \cdot op(A) \cdot x + \beta \cdot y\f$, with - * - * \f$ - * op(A) = \left\{ - * \begin{array}{ll} - * A, & \text{if trans == rocsparse_operation_none} \\ - * A^T, & \text{if trans == rocsparse_operation_transpose} \\ - * A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} - * \end{array} - * \right. - * \f$ - * - * Currently, only \p trans == \ref rocsparse_operation_none is supported. + * \f[ + * y := \alpha \cdot op(A) \cdot x + \beta \cdot y, + * \f] + * with + * \f[ + * op(A) = \left\{ + * \begin{array}{ll} + * A, & \text{if trans == rocsparse_operation_none} \\ + * A^T, & \text{if trans == rocsparse_operation_transpose} \\ + * A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} + * \end{array} + * \right. + * \f] * * \code{.c} * for(i = 0; i < m; ++i) @@ -1349,27 +1435,34 @@ rocsparse_status rocsparse_dcsrsv_solve(rocsparse_handle handle, * } * \endcode * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * + * \note + * Currently, only \p trans == \ref rocsparse_operation_none is supported. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] * trans matrix operation type. * @param[in] - * m number of rows of the sparse \p ELL matrix. + * m number of rows of the sparse ELL matrix. * @param[in] - * n number of columns of the sparse \p ELL matrix. + * n number of columns of the sparse ELL matrix. * @param[in] * alpha scalar \f$\alpha\f$. * @param[in] - * descr descriptor of the sparse \p ELL matrix. Currently, only + * descr descriptor of the sparse ELL matrix. Currently, only * \ref rocsparse_matrix_type_general is supported. * @param[in] - * ell_val array that contains the elements of the sparse \p ELL matrix. Padded + * ell_val array that contains the elements of the sparse ELL matrix. Padded * elements should be zero. * @param[in] - * ell_col_ind array that contains the column indices of the sparse \p ELL matrix. + * ell_col_ind array that contains the column indices of the sparse ELL matrix. * Padded column indices should be -1. * @param[in] - * ell_width number of non-zero elements per row of the sparse \p ELL matrix. + * ell_width number of non-zero elements per row of the sparse ELL matrix. * @param[in] * x array of \p n elements (\f$op(A) == A\f$) or \p m elements * (\f$op(A) == A^T\f$ or \f$op(A) == A^H\f$). @@ -1379,14 +1472,12 @@ rocsparse_status rocsparse_dcsrsv_solve(rocsparse_handle handle, * y array of \p m elements (\f$op(A) == A\f$) or \p n elements * (\f$op(A) == A^T\f$ or \f$op(A) == A^H\f$). * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m, \p n or \p ell_width is - * invalid.
- * \ref rocsparse_status_invalid_pointer \p descr, \p alpha, \p ell_val, - * \p ell_col_ind, \p x, \p beta or \p y pointer is invalid.
- * \ref rocsparse_status_not_implemented + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m, \p n or \p ell_width is invalid. + * \retval rocsparse_status_invalid_pointer \p descr, \p alpha, \p ell_val, + * \p ell_col_ind, \p x, \p beta or \p y pointer is invalid. + * \retval rocsparse_status_not_implemented * \p trans != \ref rocsparse_operation_none or * \ref rocsparse_matrix_type != \ref rocsparse_matrix_type_general. */ @@ -1451,26 +1542,32 @@ rocsparse_status rocsparse_sellmv(rocsparse_handle handle, /**@}*/ /*! \ingroup level2_module - * \brief Sparse matrix vector multiplication using \p HYB storage format + * \brief Sparse matrix vector multiplication using HYB storage format * * \details * \p rocsparse_hybmv multiplies the scalar \f$\alpha\f$ with a sparse \f$m \times n\f$ - * matrix, defined in \p HYB storage format, and the dense vector \f$x\f$ and adds the + * matrix, defined in HYB storage format, and the dense vector \f$x\f$ and adds the * result to the dense vector \f$y\f$ that is multiplied by the scalar \f$\beta\f$, * such that - * - * \f$y := \alpha \cdot op(A) \cdot x + \beta \cdot y\f$, with - * - * \f$ - * op(A) = \left\{ - * \begin{array}{ll} - * A, & \text{if trans == rocsparse_operation_none} \\ - * A^T, & \text{if trans == rocsparse_operation_transpose} \\ - * A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} - * \end{array} - * \right. - * \f$ - * + * \f[ + * y := \alpha \cdot op(A) \cdot x + \beta \cdot y, + * \f] + * with + * \f[ + * op(A) = \left\{ + * \begin{array}{ll} + * A, & \text{if trans == rocsparse_operation_none} \\ + * A^T, & \text{if trans == rocsparse_operation_transpose} \\ + * A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} + * \end{array} + * \right. + * \f] + * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * + * \note * Currently, only \p trans == \ref rocsparse_operation_none is supported. * * @param[in] @@ -1480,10 +1577,10 @@ rocsparse_status rocsparse_sellmv(rocsparse_handle handle, * @param[in] * alpha scalar \f$\alpha\f$. * @param[in] - * descr descriptor of the sparse \p HYB matrix. Currently, only + * descr descriptor of the sparse HYB matrix. Currently, only * \ref rocsparse_matrix_type_general is supported. * @param[in] - * hyb matrix in \p HYB storage format. + * hyb matrix in HYB storage format. * @param[in] * x array of \p n elements (\f$op(A) == A\f$) or \p m elements * (\f$op(A) == A^T\f$ or \f$op(A) == A^H\f$). @@ -1493,20 +1590,18 @@ rocsparse_status rocsparse_sellmv(rocsparse_handle handle, * y array of \p m elements (\f$op(A) == A\f$) or \p n elements * (\f$op(A) == A^T\f$ or \f$op(A) == A^H\f$). * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p hyb structure was not initialized - * with valid matrix sizes.
- * \ref rocsparse_status_invalid_pointer \p descr, \p alpha, \p hyb, \p x, - * \p beta or \p y pointer is invalid.
- * \ref rocsparse_status_invalid_value \p hyb structure was not initialized - * with a valid partitioning type.
- * \ref rocsparse_status_arch_mismatch the device is not supported.
- * \ref rocsparse_status_memory_error the buffer could not be - * allocated.
- * \ref rocsparse_status_internal_error an internal error occurred.
- * \ref rocsparse_status_not_implemented + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p hyb structure was not initialized with + * valid matrix sizes. + * \retval rocsparse_status_invalid_pointer \p descr, \p alpha, \p hyb, \p x, + * \p beta or \p y pointer is invalid. + * \retval rocsparse_status_invalid_value \p hyb structure was not initialized + * with a valid partitioning type. + * \retval rocsparse_status_arch_mismatch the device is not supported. + * \retval rocsparse_status_memory_error the buffer could not be allocated. + * \retval rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_not_implemented * \p trans != \ref rocsparse_operation_none or * \ref rocsparse_matrix_type != \ref rocsparse_matrix_type_general. */ @@ -1560,39 +1655,36 @@ rocsparse_status rocsparse_dhybmv(rocsparse_handle handle, */ /*! \ingroup level3_module - * \brief Sparse matrix dense matrix multiplication using \p CSR storage format + * \brief Sparse matrix dense matrix multiplication using CSR storage format * * \details * \p rocsparse_csrmm multiplies the scalar \f$\alpha\f$ with a sparse \f$m \times k\f$ - * matrix \f$A\f$, defined in \p CSR storage format, and the dense \f$k \times n\f$ + * matrix \f$A\f$, defined in CSR storage format, and the dense \f$k \times n\f$ * matrix \f$B\f$ and adds the result to the dense \f$m \times n\f$ matrix \f$C\f$ that * is multiplied by the scalar \f$\beta\f$, such that - * - * \f$C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot C\f$, with - * - * \f$ - * op(A) = \left\{ - * \begin{array}{ll} - * A, & \text{if trans_A == rocsparse_operation_none} \\ - * A^T, & \text{if trans_A == rocsparse_operation_transpose} \\ - * A^H, & \text{if trans_A == rocsparse_operation_conjugate_transpose} - * \end{array} - * \right. - * \f$ - * + * \f[ + * C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot C, + * \f] + * with + * \f[ + * op(A) = \left\{ + * \begin{array}{ll} + * A, & \text{if trans_A == rocsparse_operation_none} \\ + * A^T, & \text{if trans_A == rocsparse_operation_transpose} \\ + * A^H, & \text{if trans_A == rocsparse_operation_conjugate_transpose} + * \end{array} + * \right. + * \f] * and - * - * \f$ - * op(B) = \left\{ - * \begin{array}{ll} - * B, & \text{if trans_B == rocsparse_operation_none} \\ - * B^T, & \text{if trans_B == rocsparse_operation_transpose} \\ - * B^H, & \text{if trans_B == rocsparse_operation_conjugate_transpose} - * \end{array} - * \right. - * \f$ - * - * Currently, only \p trans_A == \ref rocsparse_operation_none is supported. + * \f[ + * op(B) = \left\{ + * \begin{array}{ll} + * B, & \text{if trans_B == rocsparse_operation_none} \\ + * B^T, & \text{if trans_B == rocsparse_operation_transpose} \\ + * B^H, & \text{if trans_B == rocsparse_operation_conjugate_transpose} + * \end{array} + * \right. + * \f] * * \code{.c} * for(i = 0; i < ldc; ++i) @@ -1609,6 +1701,13 @@ rocsparse_status rocsparse_dhybmv(rocsparse_handle handle, * } * \endcode * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * + * \note + * Currently, only \p trans_A == \ref rocsparse_operation_none is supported. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] @@ -1616,26 +1715,26 @@ rocsparse_status rocsparse_dhybmv(rocsparse_handle handle, * @param[in] * trans_B matrix \f$B\f$ operation type. * @param[in] - * m number of rows of the sparse \p CSR matrix \f$A\f$. + * m number of rows of the sparse CSR matrix \f$A\f$. * @param[in] * n number of columns of the dense matrix \f$op(B)\f$ and \f$C\f$. * @param[in] - * k number of columns of the sparse \p CSR matrix \f$A\f$. + * k number of columns of the sparse CSR matrix \f$A\f$. * @param[in] - * nnz number of non-zero entries of the sparse \p CSR matrix \f$A\f$. + * nnz number of non-zero entries of the sparse CSR matrix \f$A\f$. * @param[in] * alpha scalar \f$\alpha\f$. * @param[in] - * descr descriptor of the sparse \p CSR matrix \f$A\f$. Currently, only + * descr descriptor of the sparse CSR matrix \f$A\f$. Currently, only * \ref rocsparse_matrix_type_general is supported. * @param[in] - * csr_val array of \p nnz elements of the sparse \p CSR matrix \f$A\f$. + * csr_val array of \p nnz elements of the sparse CSR matrix \f$A\f$. * @param[in] * csr_row_ptr array of \p m+1 elements that point to the start of every row of the - * sparse \p CSR matrix \f$A\f$. + * sparse CSR matrix \f$A\f$. * @param[in] * csr_col_ind array of \p nnz elements containing the column indices of the sparse - * \p CSR matrix \f$A\f$. + * CSR matrix \f$A\f$. * @param[in] * B array of dimension \f$ldb \times n\f$ (\f$op(B) == B\f$) or * \f$ldb \times k\f$ (\f$op(B) == B^T\f$ or \f$op(B) == B^H\f$). @@ -1652,18 +1751,74 @@ rocsparse_status rocsparse_dhybmv(rocsparse_handle handle, * (\f$op(A) == A\f$) or \f$\max{(1, k)}\f$ (\f$op(A) == A^T\f$ or * \f$op(A) == A^H\f$). * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m, \p n, \p k, \p nnz, \p ldb or - * \p ldc is invalid.
- * \ref rocsparse_status_invalid_pointer \p descr, \p alpha, \p csr_val, - * \p csr_row_ptr, \p csr_col_ind, \p B, \p beta or \p C pointer is - * invalid.
- * \ref rocsparse_status_arch_mismatch the device is not supported.
- * \ref rocsparse_status_not_implemented + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m, \p n, \p k, \p nnz, \p ldb or \p ldc + * is invalid. + * \retval rocsparse_status_invalid_pointer \p descr, \p alpha, \p csr_val, + * \p csr_row_ptr, \p csr_col_ind, \p B, \p beta or \p C pointer is invalid. + * \retval rocsparse_status_arch_mismatch the device is not supported. + * \retval rocsparse_status_not_implemented * \p trans_A != \ref rocsparse_operation_none or * \ref rocsparse_matrix_type != \ref rocsparse_matrix_type_general. + * + * \par Example + * This example multiplies a CSR matrix with a dense matrix. + * \code{.c} + * // 1 2 0 3 0 + * // A = 0 4 5 0 0 + * // 6 0 0 7 8 + * + * rocsparse_int m = 3; + * rocsparse_int k = 5; + * rocsparse_int nnz = 8; + * + * csr_row_ptr[m+1] = {0, 3, 5, 8}; // device memory + * csr_col_ind[nnz] = {0, 1, 3, 1, 2, 0, 3, 4}; // device memory + * csr_val[nnz] = {1, 2, 3, 4, 5, 6, 7, 8}; // device memory + * + * // Set dimension n of B + * rocsparse_int n = 64; + * + * // Allocate and generate dense matrix B + * std::vector hB(k * n); + * for(rocsparse_int i = 0; i < k * n; ++i) + * { + * hB[i] = static_cast(rand()) / RAND_MAX; + * } + * + * // Copy B to the device + * float* B; + * hipMalloc((void**)&B, sizeof(float) * k * n); + * hipMemcpy(B, hB.data(), sizeof(float) * k * n, hipMemcpyHostToDevice); + * + * // alpha and beta + * float alpha = 1.0f; + * float beta = 0.0f; + * + * // Allocate memory for the resulting matrix C + * float* C; + * hipMalloc((void**)&C, sizeof(float) * m * n); + * + * // Perform the matrix multiplication + * rocsparse_scsrmm(handle, + * rocsparse_operation_none, + * rocsparse_operation_none, + * m, + * n, + * k, + * nnz, + * &alpha, + * descr, + * csr_val, + * csr_row_ptr, + * csr_col_ind, + * B, + * k, + * &beta, + * C, + * m); + * \endcode */ /**@{*/ ROCSPARSE_EXPORT @@ -1751,14 +1906,14 @@ rocsparse_status rocsparse_zcsrmm(rocsparse_handle handle, */ /*! \ingroup precond_module - * \brief Incomplete LU factorization with 0 fill-ins and no pivoting using \p CSR + * \brief Incomplete LU factorization with 0 fill-ins and no pivoting using CSR * storage format * * \details * \p rocsparse_csrilu0_zero_pivot returns \ref rocsparse_status_zero_pivot, if either a * structural or numerical zero has been found during rocsparse_scsrilu0() or * rocsparse_dcsrilu0() computation. The first zero pivot \f$j\f$ at \f$A_{j,j}\f$ - * is stored in \p position, using same index base as the \p CSR matrix. + * is stored in \p position, using same index base as the CSR matrix. * * \p position can be in host or device memory. If no zero pivot has been found, * \p position is set to -1 and \ref rocsparse_status_success is returned instead. @@ -1770,13 +1925,12 @@ rocsparse_status rocsparse_zcsrmm(rocsparse_handle handle, * @param[inout] * position pointer to zero pivot \f$j\f$, can be in host or device memory. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was not - * initialized.
- * \ref rocsparse_status_invalid_pointer \p info or \p position - * pointer is invalid.
- * \ref rocsparse_status_internal_error an internal error occurred.
- * \ref rocsparse_status_zero_pivot zero pivot has been found. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_pointer \p info or \p position pointer is + * invalid. + * \retval rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_zero_pivot zero pivot has been found. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_csrilu0_zero_pivot(rocsparse_handle handle, @@ -1784,12 +1938,12 @@ rocsparse_status rocsparse_csrilu0_zero_pivot(rocsparse_handle handle, rocsparse_int* position); /*! \ingroup precond_module - * \brief Incomplete LU factorization with 0 fill-ins and no pivoting using \p CSR + * \brief Incomplete LU factorization with 0 fill-ins and no pivoting using CSR * storage format * * \details * \p rocsparse_csrilu0_buffer_size returns the size of the temporary storage buffer - * that is required by rocsparse_scsrilu0_analysis(), rocsparse_dcsrilu0_analysis, + * that is required by rocsparse_scsrilu0_analysis(), rocsparse_dcsrilu0_analysis(), * rocsparse_scsrilu0() and rocsparse_dcsrilu0(). The temporary storage buffer must * be allocated by the user. The size of the temporary storage buffer is identical to * the size returned by rocsparse_scsrsv_buffer_size() and @@ -1799,19 +1953,19 @@ rocsparse_status rocsparse_csrilu0_zero_pivot(rocsparse_handle handle, * @param[in] * handle handle to the rocsparse library context queue. * @param[in] - * m number of rows of the sparse \p CSR matrix. + * m number of rows of the sparse CSR matrix. * @param[in] - * nnz number of non-zero entries of the sparse \p CSR matrix. + * nnz number of non-zero entries of the sparse CSR matrix. * @param[in] - * descr descriptor of the sparse \p CSR matrix. + * descr descriptor of the sparse CSR matrix. * @param[in] - * csr_val array of \p nnz elements of the sparse \p CSR matrix. + * csr_val array of \p nnz elements of the sparse CSR matrix. * @param[in] * csr_row_ptr array of \p m+1 elements that point to the start of every row of the - * sparse \p CSR matrix. + * sparse CSR matrix. * @param[in] * csr_col_ind array of \p nnz elements containing the column indices of the sparse - * \p CSR matrix. + * CSR matrix. * @param[out] * info structure that holds the information collected during the analysis step. * @param[in] @@ -1819,15 +1973,13 @@ rocsparse_status rocsparse_csrilu0_zero_pivot(rocsparse_handle handle, * rocsparse_scsrilu0_analysis(), rocsparse_dcsrilu0_analysis(), * rocsparse_scsrilu0() and rocsparse_dcsrilu0(). * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m or \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p descr, \p csr_val, - * \p csr_row_ptr, \p csr_col_ind, \p info or \p buffer_size pointer is - * invalid.
- * \ref rocsparse_status_internal_error an internal error occurred.
- * \ref rocsparse_status_not_implemented + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m or \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p descr, \p csr_val, \p csr_row_ptr, + * \p csr_col_ind, \p info or \p buffer_size pointer is invalid. + * \retval rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_not_implemented * \p trans != \ref rocsparse_operation_none or * \ref rocsparse_matrix_type != \ref rocsparse_matrix_type_general. */ @@ -1856,15 +2008,14 @@ rocsparse_status rocsparse_dcsrilu0_buffer_size(rocsparse_handle handle, /**@}*/ /*! \ingroup precond_module - * \brief Incomplete LU factorization with 0 fill-ins and no pivoting using \p CSR + * \brief Incomplete LU factorization with 0 fill-ins and no pivoting using CSR * storage format * * \details * \p rocsparse_csrilu0_analysis performs the analysis step for rocsparse_scsrilu0() * and rocsparse_dcsrilu0(). It is expected that this function will be executed only - * once for a given matrix and particular operation type. Note that if the matrix - * sparsity pattern changes, the gathered information will become invalid. The analysis - * meta data can be cleared by rocsparse_csrilu0_clear(). + * once for a given matrix and particular operation type. The analysis meta data can be + * cleared by rocsparse_csrilu0_clear(). * * \p rocsparse_csrilu0_analysis can share its meta data with * rocsparse_scsrsv_analysis() and rocsparse_dcsrsv_analysis(). Selecting @@ -1873,22 +2024,29 @@ rocsparse_status rocsparse_dcsrilu0_buffer_size(rocsparse_handle handle, * pattern remains unchanged. If this cannot be assured, * \ref rocsparse_analysis_policy_force has to be used. * + * \note + * If the matrix sparsity pattern changes, the gathered information will become invalid. + * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] - * m number of rows of the sparse \p CSR matrix. + * m number of rows of the sparse CSR matrix. * @param[in] - * nnz number of non-zero entries of the sparse \p CSR matrix. + * nnz number of non-zero entries of the sparse CSR matrix. * @param[in] - * descr descriptor of the sparse \p CSR matrix. + * descr descriptor of the sparse CSR matrix. * @param[in] - * csr_val array of \p nnz elements of the sparse \p CSR matrix. + * csr_val array of \p nnz elements of the sparse CSR matrix. * @param[in] * csr_row_ptr array of \p m+1 elements that point to the start of every row of the - * sparse \p CSR matrix. + * sparse CSR matrix. * @param[in] * csr_col_ind array of \p nnz elements containing the column indices of the sparse - * \p CSR matrix. + * CSR matrix. * @param[out] * info structure that holds the information collected during * the analysis step. @@ -1900,15 +2058,13 @@ rocsparse_status rocsparse_dcsrilu0_buffer_size(rocsparse_handle handle, * @param[in] * temp_buffer temporary storage buffer allocated by the user. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m or \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p descr, \p csr_val, - * \p csr_row_ptr, \p csr_col_ind, \p info or \p temp_buffer pointer is - * invalid.
- * \ref rocsparse_status_internal_error an internal error occurred.
- * \ref rocsparse_status_not_implemented + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m or \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p descr, \p csr_val, \p csr_row_ptr, + * \p csr_col_ind, \p info or \p temp_buffer pointer is invalid. + * \retval rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_not_implemented * \p trans != \ref rocsparse_operation_none or * \ref rocsparse_matrix_type != \ref rocsparse_matrix_type_general. */ @@ -1941,15 +2097,18 @@ rocsparse_status rocsparse_dcsrilu0_analysis(rocsparse_handle handle, /**@}*/ /*! \ingroup precond_module - * \brief Incomplete LU factorization with 0 fill-ins and no pivoting using \p CSR + * \brief Incomplete LU factorization with 0 fill-ins and no pivoting using CSR * storage format * * \details * \p rocsparse_csrilu0_clear deallocates all memory that was allocated by * rocsparse_scsrilu0_analysis() or rocsparse_dcsrilu0_analysis(). This is especially * useful, if memory is an issue and the analysis data is not required for further - * computation. Calling \p rocsparse_csrilu0_clear is optional. All allocated resources - * will be cleared, when the opaque \ref rocsparse_mat_info struct is destroyed using + * computation. + * + * \note + * Calling \p rocsparse_csrilu0_clear is optional. All allocated resources will be + * cleared, when the opaque \ref rocsparse_mat_info struct is destroyed using * rocsparse_destroy_mat_info(). * * @param[in] @@ -1957,26 +2116,26 @@ rocsparse_status rocsparse_dcsrilu0_analysis(rocsparse_handle handle, * @param[inout] * info structure that holds the information collected during the analysis step. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_pointer \p info pointer is invalid.
- * \ref rocsparse_status_memory_error the buffer holding the meta data - * could not be deallocated.
- * \ref rocsparse_status_internal_error an internal error occurred.
+ * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_pointer \p info pointer is invalid. + * \retval rocsparse_status_memory_error the buffer holding the meta data could not + * be deallocated. + * \retval rocsparse_status_internal_error an internal error occurred. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_csrilu0_clear(rocsparse_handle handle, rocsparse_mat_info info); /*! \ingroup precond_module - * \brief Incomplete LU factorization with 0 fill-ins and no pivoting using \p CSR + * \brief Incomplete LU factorization with 0 fill-ins and no pivoting using CSR * storage format * * \details * \p rocsparse_csrilu0 computes the incomplete LU factorization with 0 fill-ins and no - * pivoting of a sparse \f$m \times m\f$ \p CSR matrix \f$A\f$, such that - * - * \f$A \approx LU\f$ + * pivoting of a sparse \f$m \times m\f$ CSR matrix \f$A\f$, such that + * \f[ + * A \approx LU + * \f] * * \p rocsparse_csrilu0 requires a user allocated temporary buffer. Its size is returned * by rocsparse_scsrilu0_buffer_size() or rocsparse_dcsrilu0_buffer_size(). Furthermore, @@ -1985,25 +2144,30 @@ rocsparse_status rocsparse_csrilu0_clear(rocsparse_handle handle, rocsparse_mat_ * (either numerical or structural zero). The zero pivot status can be obtained by * calling rocsparse_csrilu0_zero_pivot(). * - * Note that the sparse \p CSR matrix has to be sorted. This can be achieved by calling + * \note + * The sparse CSR matrix has to be sorted. This can be achieved by calling * rocsparse_csrsort(). * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] - * m number of rows of the sparse \p CSR matrix. + * m number of rows of the sparse CSR matrix. * @param[in] - * nnz number of non-zero entries of the sparse \p CSR matrix. + * nnz number of non-zero entries of the sparse CSR matrix. * @param[in] - * descr descriptor of the sparse \p CSR matrix. + * descr descriptor of the sparse CSR matrix. * @param[inout] - * csr_val array of \p nnz elements of the sparse \p CSR matrix. + * csr_val array of \p nnz elements of the sparse CSR matrix. * @param[in] * csr_row_ptr array of \p m+1 elements that point to the start - * of every row of the sparse \p CSR matrix. + * of every row of the sparse CSR matrix. * @param[in] * csr_col_ind array of \p nnz elements containing the column indices of the sparse - * \p CSR matrix. + * CSR matrix. * @param[in] * info structure that holds the information collected during the analysis step. * @param[in] @@ -2011,20 +2175,19 @@ rocsparse_status rocsparse_csrilu0_clear(rocsparse_handle handle, rocsparse_mat_ * @param[in] * temp_buffer temporary storage buffer allocated by the user. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m or \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p descr, \p csr_val, - * \p csr_row_ptr or \p csr_col_ind pointer is invalid.
- * \ref rocsparse_status_arch_mismatch the device is not supported.
- * \ref rocsparse_status_internal_error an internal error occurred.
- * \ref rocsparse_status_not_implemented + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m or \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p descr, \p csr_val, \p csr_row_ptr + * or \p csr_col_ind pointer is invalid. + * \retval rocsparse_status_arch_mismatch the device is not supported. + * \retval rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_not_implemented * \p trans != \ref rocsparse_operation_none or * \ref rocsparse_matrix_type != \ref rocsparse_matrix_type_general. * * \par Example - * Consider the sparse \f$m \times m\f$ matrix \f$A\f$, stored in \p CSR + * Consider the sparse \f$m \times m\f$ matrix \f$A\f$, stored in CSR * storage format. The following example computes the incomplete LU factorization * \f$M \approx LU\f$ and solves the preconditioned system \f$My = x\f$. * \code{.c} @@ -2235,36 +2398,85 @@ rocsparse_status rocsparse_dcsrilu0(rocsparse_handle handle, */ /*! \ingroup conv_module - * \brief Convert a sparse \p CSR matrix into sparse \p COO matrix + * \brief Convert a sparse CSR matrix into a sparse COO matrix * * \details - * \p rocsparse_csr2coo converts the \p CSR array containing the row offsets, that point - * to the start of every row, into a \p COO array of row indices. It can also be used - * to convert a \p CSC array containing the column offsets into a \p COO array of column - * indices. + * \p rocsparse_csr2coo converts the CSR array containing the row offsets, that point + * to the start of every row, into a COO array of row indices. + * + * \note + * It can also be used to convert a CSC array containing the column offsets into a COO + * array of column indices. + * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] * csr_row_ptr array of \p m+1 elements that point to the start of every row - * of the sparse \p CSR matrix. + * of the sparse CSR matrix. * @param[in] - * nnz number of non-zero entries of the sparse \p CSR matrix. + * nnz number of non-zero entries of the sparse CSR matrix. * @param[in] - * m number of rows of the sparse \p CSR matrix. + * m number of rows of the sparse CSR matrix. * @param[out] - * coo_row_ind array of \p nnz elements containing the row indices of the sparse \p COO + * coo_row_ind array of \p nnz elements containing the row indices of the sparse COO * matrix. * @param[in] * idx_base \ref rocsparse_index_base_zero or \ref rocsparse_index_base_one. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m or \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p csr_row_ptr or \p coo_row_ind - * pointer is invalid.
- * \ref rocsparse_status_arch_mismatch the device is not supported. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m or \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p csr_row_ptr or \p coo_row_ind + * pointer is invalid. + * \retval rocsparse_status_arch_mismatch the device is not supported. + * + * \par Example + * This example converts a CSR matrix into a COO matrix. + * \code{.c} + * // 1 2 0 3 0 + * // A = 0 4 5 0 0 + * // 6 0 0 7 8 + * + * rocsparse_int m = 3; + * rocsparse_int n = 5; + * rocsparse_int nnz = 8; + * + * csr_row_ptr[m+1] = {0, 3, 5, 8}; // device memory + * csr_col_ind[nnz] = {0, 1, 3, 1, 2, 0, 3, 4}; // device memory + * csr_val[nnz] = {1, 2, 3, 4, 5, 6, 7, 8}; // device memory + * + * // Allocate COO matrix arrays + * rocsparse_int* coo_row_ind; + * rocsparse_int* coo_col_ind; + * float* coo_val; + * + * hipMalloc((void**)&coo_row_ind, sizeof(rocsparse_int) * nnz); + * hipMalloc((void**)&coo_col_ind, sizeof(rocsparse_int) * nnz); + * hipMalloc((void**)&coo_val, sizeof(float) * nnz); + * + * // Convert the csr row offsets into coo row indices + * rocsparse_csr2coo(handle, + * csr_row_ptr, + * nnz, + * m, + * coo_row_ind, + * rocsparse_index_base_zero); + * + * // Copy the column and value arrays + * hipMemcpy(coo_col_ind, + * csr_col_ind, + * sizeof(rocsparse_int) * nnz, + * hipMemcpyDeviceToDevice); + * + * hipMemcpy(coo_val, + * csr_val, + * sizeof(float) * nnz, + * hipMemcpyDeviceToDevice); + * \endcode */ ROCSPARSE_EXPORT rocsparse_status rocsparse_csr2coo(rocsparse_handle handle, @@ -2275,40 +2487,39 @@ rocsparse_status rocsparse_csr2coo(rocsparse_handle handle, rocsparse_index_base idx_base); /*! \ingroup conv_module - * \brief Convert a sparse \p CSR matrix into sparse \p CSC matrix + * \brief Convert a sparse CSR matrix into a sparse CSC matrix * * \details * \p rocsparse_csr2csc_buffer_size returns the size of the temporary storage buffer - * required by rocsparse_csr2csc(). The temporary storage buffer must be allocated by - * the user. + * required by rocsparse_scsr2csc() and rocsparse_dcsr2csc(). The temporary storage + * buffer must be allocated by the user. * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] - * m number of rows of the sparse \p CSR matrix. + * m number of rows of the sparse CSR matrix. * @param[in] - * n number of columns of the sparse \p CSR matrix. + * n number of columns of the sparse CSR matrix. * @param[in] - * nnz number of non-zero entries of the sparse \p CSR matrix. + * nnz number of non-zero entries of the sparse CSR matrix. * @param[in] * csr_row_ptr array of \p m+1 elements that point to the start of every row of the - * sparse \p CSR matrix. + * sparse CSR matrix. * @param[in] * csr_col_ind array of \p nnz elements containing the column indices of the sparse - * \p CSR matrix. + * CSR matrix. * @param[in] * copy_values \ref rocsparse_action_symbolic or \ref rocsparse_action_numeric. * @param[out] * buffer_size number of bytes of the temporary storage buffer required by * sparse_csr2csc(). * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p csr_row_ptr, \p csr_col_ind or - * \p buffer_size pointer is invalid.
- * \ref rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p csr_row_ptr, \p csr_col_ind or + * \p buffer_size pointer is invalid. + * \retval rocsparse_status_internal_error an internal error occurred. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_csr2csc_buffer_size(rocsparse_handle handle, @@ -2321,43 +2532,48 @@ rocsparse_status rocsparse_csr2csc_buffer_size(rocsparse_handle handle, size_t* buffer_size); /*! \ingroup conv_module - * \brief Convert a sparse \p CSR matrix into sparse \p CSC matrix + * \brief Convert a sparse CSR matrix into a sparse CSC matrix * * \details - * \p rocsparse_csr2csc converts a \p CSR matrix info a \p CSC matrix. The resulting - * matrix can also be seen as the transpose of the input matrix. \p rocsparse_csr2csc - * can also be used to convert a \p CSC matrix into a \p CSR matrix. \p copy_values - * decides whether \p csc_val is being filled during conversion - * (\ref rocsparse_action_numeric) or not (\ref rocsparse_action_symbolic). + * \p rocsparse_csr2csc converts a CSR matrix into a CSC matrix. \p rocsparse_csr2csc + * can also be used to convert a CSC matrix into a CSR matrix. \p copy_values decides + * whether \p csc_val is being filled during conversion (\ref rocsparse_action_numeric) + * or not (\ref rocsparse_action_symbolic). * - * \p rocsparse_csr2csc requires extra temporary storage buffer that has to be - * allocated by the user. Storage buffer size can be determined by - * rocsparse_csr2csc_buffer_size(). + * \p rocsparse_csr2csc requires extra temporary storage buffer that has to be allocated + * by the user. Storage buffer size can be determined by rocsparse_csr2csc_buffer_size(). + * + * \note + * The resulting matrix can also be seen as the transpose of the input matrix. + * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] - * m number of rows of the sparse \p CSR matrix. + * m number of rows of the sparse CSR matrix. * @param[in] - * n number of columns of the sparse \p CSR matrix. + * n number of columns of the sparse CSR matrix. * @param[in] - * nnz number of non-zero entries of the sparse \p CSR matrix. + * nnz number of non-zero entries of the sparse CSR matrix. * @param[in] - * csr_val array of \p nnz elements of the sparse \p CSR matrix. + * csr_val array of \p nnz elements of the sparse CSR matrix. * @param[in] * csr_row_ptr array of \p m+1 elements that point to the start of every row of the - * sparse \p CSR matrix. + * sparse CSR matrix. * @param[in] * csr_col_ind array of \p nnz elements containing the column indices of the sparse - * \p CSR matrix. + * CSR matrix. * @param[out] - * csc_val array of \p nnz elements of the sparse \p CSC matrix. + * csc_val array of \p nnz elements of the sparse CSC matrix. * @param[out] - * csc_row_ind array of \p nnz elements containing the row indices of the sparse \p CSC + * csc_row_ind array of \p nnz elements containing the row indices of the sparse CSC * matrix. * @param[out] * csc_col_ptr array of \p n+1 elements that point to the start of every column of the - * sparse \p CSC matrix. + * sparse CSC matrix. * @param[in] * copy_values \ref rocsparse_action_symbolic or \ref rocsparse_action_numeric. * @param[in] @@ -2366,15 +2582,72 @@ rocsparse_status rocsparse_csr2csc_buffer_size(rocsparse_handle handle, * temp_buffer temporary storage buffer allocated by the user, size is returned by * rocsparse_csr2csc_buffer_size(). * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p csr_val, \p csr_row_ptr, + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p csr_val, \p csr_row_ptr, * \p csr_col_ind, \p csc_val, \p csc_row_ind, \p csc_col_ptr or - * \p temp_buffer pointer is invalid.
- * \ref rocsparse_status_arch_mismatch the device is not supported.
- * \ref rocsparse_status_internal_error an internal error occurred. + * \p temp_buffer pointer is invalid. + * \retval rocsparse_status_arch_mismatch the device is not supported. + * \retval rocsparse_status_internal_error an internal error occurred. + * + * \par Example + * This example computes the transpose of a CSR matrix. + * \code{.c} + * // 1 2 0 3 0 + * // A = 0 4 5 0 0 + * // 6 0 0 7 8 + * + * rocsparse_int m_A = 3; + * rocsparse_int n_A = 5; + * rocsparse_int nnz_A = 8; + * + * csr_row_ptr_A[m+1] = {0, 3, 5, 8}; // device memory + * csr_col_ind_A[nnz] = {0, 1, 3, 1, 2, 0, 3, 4}; // device memory + * csr_val_A[nnz] = {1, 2, 3, 4, 5, 6, 7, 8}; // device memory + * + * // Allocate memory for transposed CSR matrix + * rocsparse_int m_T = n_A; + * rocsparse_int n_T = m_A; + * rocsparse_int nnz_T = nnz_A; + * + * rocsparse_int* csr_row_ptr_T; + * rocsparse_int* csr_col_ind_T; + * float* csr_val_T; + * + * hipMalloc((void**)&csr_row_ptr_T, sizeof(rocsparse_int) * (m_T + 1)); + * hipMalloc((void**)&csr_col_ind_T, sizeof(rocsparse_int) * nnz_T); + * hipMalloc((void**)&csr_val_T, sizeof(float) * nnz_T); + * + * // Obtain the temporary buffer size + * size_t buffer_size; + * rocsparse_csr2csc_buffer_size(handle, + * m_A, + * n_A, + * nnz_A, + * csr_row_ptr_A, + * csr_col_ind_A, + * rocsparse_action_numeric, + * &buffer_size); + * + * // Allocate temporary buffer + * void* temp_buffer; + * hipMalloc(&temp_buffer, buffer_size); + * + * rocsparse_scsr2csc(handle, + * m_A, + * n_A, + * nnz_A, + * csr_val_A, + * csr_row_ptr_A, + * csr_col_ind_A, + * csr_val_T, + * csr_col_ind_T, + * csr_row_ptr_T, + * rocsparse_action_numeric, + * rocsparse_index_base_zero, + * temp_buffer); + * \endcode */ /**@{*/ ROCSPARSE_EXPORT @@ -2409,37 +2682,40 @@ rocsparse_status rocsparse_dcsr2csc(rocsparse_handle handle, /**@}*/ /*! \ingroup conv_module - * \brief Convert a sparse \p CSR matrix into sparse \p ELL matrix + * \brief Convert a sparse CSR matrix into a sparse ELL matrix * * \details * \p rocsparse_csr2ell_width computes the maximum of the per row non-zero elements - * over all rows, the \p ELL \p width, for a given \p CSR matrix. + * over all rows, the ELL \p width, for a given CSR matrix. + * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] - * m number of rows of the sparse \p CSR matrix. + * m number of rows of the sparse CSR matrix. * @param[in] - * csr_descr descriptor of the sparse \p CSR matrix. Currently, only + * csr_descr descriptor of the sparse CSR matrix. Currently, only * \ref rocsparse_matrix_type_general is supported. * @param[in] * csr_row_ptr array of \p m+1 elements that point to the start of every row of the - * sparse \p CSR matrix. + * sparse CSR matrix. * @param[in] - * ell_descr descriptor of the sparse \p ELL matrix. Currently, only + * ell_descr descriptor of the sparse ELL matrix. Currently, only * \ref rocsparse_matrix_type_general is supported. * @param[out] - * ell_width pointer to the number of non-zero elements per row in \p ELL storage + * ell_width pointer to the number of non-zero elements per row in ELL storage * format. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m is invalid.
- * \ref rocsparse_status_invalid_pointer \p csr_descr, \p csr_row_ptr, or - * \p ell_width pointer is invalid.
- * \ref rocsparse_status_internal_error an internal error occurred.
- * \ref rocsparse_status_not_implemented + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m is invalid. + * \retval rocsparse_status_invalid_pointer \p csr_descr, \p csr_row_ptr, or + * \p ell_width pointer is invalid. + * \retval rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_not_implemented * \ref rocsparse_matrix_type != \ref rocsparse_matrix_type_general. */ ROCSPARSE_EXPORT @@ -2451,49 +2727,103 @@ rocsparse_status rocsparse_csr2ell_width(rocsparse_handle handle, rocsparse_int* ell_width); /*! \ingroup conv_module - * \brief Convert a sparse \p CSR matrix into sparse \p ELL matrix + * \brief Convert a sparse CSR matrix into a sparse ELL matrix * * \details - * \p rocsparse_csr2ell converts a \p CSR matrix into an \p ELL matrix. It is assumed, + * \p rocsparse_csr2ell converts a CSR matrix into an ELL matrix. It is assumed, * that \p ell_val and \p ell_col_ind are allocated. Allocation size is computed by the - * number of rows times the number of \p ELL non-zero elements per row, such that - * \f$\text{nnz}_{\text{ELL}} = m \cdot \text{ell_width}\f$. The number of \p ELL + * number of rows times the number of ELL non-zero elements per row, such that + * \f$\text{nnz}_{\text{ELL}} = m \cdot \text{ell_width}\f$. The number of ELL * non-zero elements per row is obtained by rocsparse_csr2ell_width(). * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] - * m number of rows of the sparse \p CSR matrix. + * m number of rows of the sparse CSR matrix. * @param[in] - * csr_descr descriptor of the sparse \p CSR matrix. Currently, only + * csr_descr descriptor of the sparse CSR matrix. Currently, only * \ref rocsparse_matrix_type_general is supported. * @param[in] - * csr_val array containing the values of the sparse \p CSR matrix. + * csr_val array containing the values of the sparse CSR matrix. * @param[in] * csr_row_ptr array of \p m+1 elements that point to the start of every row of the - * sparse \p CSR matrix. + * sparse CSR matrix. * @param[in] - * csr_col_ind array containing the column indices of the sparse \p CSR matrix. + * csr_col_ind array containing the column indices of the sparse CSR matrix. * @param[in] - * ell_descr descriptor of the sparse \p ELL matrix. Currently, only + * ell_descr descriptor of the sparse ELL matrix. Currently, only * \ref rocsparse_matrix_type_general is supported. * @param[in] - * ell_width number of non-zero elements per row in \p ELL storage format. + * ell_width number of non-zero elements per row in ELL storage format. * @param[out] - * ell_val array of \p m times \p ell_width elements of the sparse \p ELL matrix. + * ell_val array of \p m times \p ell_width elements of the sparse ELL matrix. * @param[out] * ell_col_ind array of \p m times \p ell_width elements containing the column indices - * of the sparse \p ELL matrix. + * of the sparse ELL matrix. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m or \p ell_width is invalid.
- * \ref rocsparse_status_invalid_pointer \p csr_descr, \p csr_val, + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m or \p ell_width is invalid. + * \retval rocsparse_status_invalid_pointer \p csr_descr, \p csr_val, * \p csr_row_ptr, \p csr_col_ind, \p ell_descr, \p ell_val or - * \p ell_col_ind pointer is invalid.
- * \ref rocsparse_status_not_implemented + * \p ell_col_ind pointer is invalid. + * \retval rocsparse_status_not_implemented * \ref rocsparse_matrix_type != \ref rocsparse_matrix_type_general. + * + * \par Example + * This example converts a CSR matrix into an ELL matrix. + * \code{.c} + * // 1 2 0 3 0 + * // A = 0 4 5 0 0 + * // 6 0 0 7 8 + * + * rocsparse_int m = 3; + * rocsparse_int n = 5; + * rocsparse_int nnz = 8; + * + * csr_row_ptr[m+1] = {0, 3, 5, 8}; // device memory + * csr_col_ind[nnz] = {0, 1, 3, 1, 2, 0, 3, 4}; // device memory + * csr_val[nnz] = {1, 2, 3, 4, 5, 6, 7, 8}; // device memory + * + * // Create ELL matrix descriptor + * rocsparse_mat_descr ell_descr; + * rocsparse_create_mat_descr(&ell_descr); + * + * // Obtain the ELL width + * rocsparse_int ell_width; + * rocsparse_csr2ell_width(handle, + * m, + * csr_descr, + * csr_row_ptr, + * ell_descr, + * &ell_width); + * + * // Compute ELL non-zero entries + * rocsparse_int ell_nnz = m * ell_width; + * + * // Allocate ELL column and value arrays + * rocsparse_int* ell_col_ind; + * hipMalloc((void**)&ell_col_ind, sizeof(rocsparse_int) * ell_nnz); + * + * float* ell_val; + * hipMalloc((void**)&ell_val, sizeof(float) * ell_nnz); + * + * // Format conversion + * rocsparse_scsr2ell(handle, + * m, + * csr_descr, + * csr_val, + * csr_row_ptr, + * csr_col_ind, + * ell_descr, + * ell_width, + * ell_val, + * ell_col_ind); + * \endcode */ /**@{*/ ROCSPARSE_EXPORT @@ -2548,54 +2878,85 @@ rocsparse_status rocsparse_scsr2ell(rocsparse_handle handle, /**@}*/ /*! \ingroup conv_module - * \brief Convert a sparse \p CSR matrix into sparse \p HYB matrix + * \brief Convert a sparse CSR matrix into a sparse HYB matrix * * \details - * \p rocsparse_csr2hyb converts a \p CSR matrix into a \p HYB matrix. It is assumed + * \p rocsparse_csr2hyb converts a CSR matrix into a HYB matrix. It is assumed * that \p hyb has been initialized with rocsparse_create_hyb_mat(). * - * This function requires a significant amount of storage for the \p HYB matrix, + * \note + * This function requires a significant amount of storage for the HYB matrix, * depending on the matrix structure. * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] - * m number of rows of the sparse \p CSR matrix. + * m number of rows of the sparse CSR matrix. * @param[in] - * n number of columns of the sparse \p CSR matrix. + * n number of columns of the sparse CSR matrix. * @param[in] - * descr descriptor of the sparse \p CSR matrix. Currently, only + * descr descriptor of the sparse CSR matrix. Currently, only * \ref rocsparse_matrix_type_general is supported. * @param[in] - * csr_val array containing the values of the sparse \p CSR matrix. + * csr_val array containing the values of the sparse CSR matrix. * @param[in] * csr_row_ptr array of \p m+1 elements that point to the start of every row of the - * sparse \p CSR matrix. + * sparse CSR matrix. * @param[in] - * csr_col_ind array containing the column indices of the sparse \p CSR matrix. + * csr_col_ind array containing the column indices of the sparse CSR matrix. * @param[out] - * hyb sparse matrix in \p HYB format. + * hyb sparse matrix in HYB format. * @param[in] - * user_ell_width width of the \p ELL part of the \p HYB matrix (only required if + * user_ell_width width of the ELL part of the HYB matrix (only required if * \p partition_type == \ref rocsparse_hyb_partition_user). * @param[in] * partition_type \ref rocsparse_hyb_partition_auto (recommended), * \ref rocsparse_hyb_partition_user or * \ref rocsparse_hyb_partition_max. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m, \p n or \p user_ell_width is - * invalid.
- * \ref rocsparse_status_invalid_value \p partition_type is invalid.
- * \ref rocsparse_status_invalid_pointer \p descr, \p hyb, \p csr_val, - * \p csr_row_ptr or \p csr_col_ind pointer is invalid.
- * \ref rocsparse_status_memory_error the buffer for the \p HYB matrix - * could not be allocated.
- * \ref rocsparse_status_internal_error an internal error occurred.
- * \ref rocsparse_status_not_implemented + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m, \p n or \p user_ell_width is invalid. + * \retval rocsparse_status_invalid_value \p partition_type is invalid. + * \retval rocsparse_status_invalid_pointer \p descr, \p hyb, \p csr_val, + * \p csr_row_ptr or \p csr_col_ind pointer is invalid. + * \retval rocsparse_status_memory_error the buffer for the HYB matrix could not be + * allocated. + * \retval rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_not_implemented * \ref rocsparse_matrix_type != \ref rocsparse_matrix_type_general. + * + * \par Example + * This example converts a CSR matrix into a HYB matrix using user defined partitioning. + * \code{.c} + * // Create HYB matrix structure + * rocsparse_hyb_mat hyb; + * rocsparse_create_hyb_mat(&hyb); + * + * // User defined ell width + * rocsparse_int user_ell_width = 5; + * + * // Perform the conversion + * rocsparse_scsr2hyb(handle, + * m, + * n, + * descr, + * csr_val, + * csr_row_ptr, + * csr_col_ind, + * hyb, + * user_ell_width, + * rocsparse_hyb_partition_user); + * + * // Do some work + * + * // Clean up + * rocsparse_destroy_hyb_mat(hyb); + * \endcode */ /**@{*/ ROCSPARSE_EXPORT @@ -2649,37 +3010,85 @@ rocsparse_status rocsparse_dcsr2hyb(rocsparse_handle handle, /**@}*/ /*! \ingroup conv_module - * \brief Convert a sparse \p COO matrix into sparse \p CSR matrix + * \brief Convert a sparse COO matrix into a sparse CSR matrix * * \details - * \p rocsparse_coo2csr converts the \p COO array containing the row indices into a - * \p CSR array of row offsets, that point to the start of every row. It can also be - * used, to convert a \p COO array containing the column indices into a \p CSC array - * of column offsets, that point to the start of every column. + * \p rocsparse_coo2csr converts the COO array containing the row indices into a + * CSR array of row offsets, that point to the start of every row. + * It is assumed that the COO row index array is sorted. + * + * \note It can also be used, to convert a COO array containing the column indices into + * a CSC array of column offsets, that point to the start of every column. Then, it is + * assumed that the COO column index array is sorted, instead. * - * It is assumed that the \p COO row index array is sorted. + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] - * coo_row_ind array of \p nnz elements containing the row indices of the sparse \p COO + * coo_row_ind array of \p nnz elements containing the row indices of the sparse COO * matrix. * @param[in] - * nnz number of non-zero entries of the sparse \p CSR matrix. + * nnz number of non-zero entries of the sparse CSR matrix. * @param[in] - * m number of rows of the sparse \p CSR matrix. + * m number of rows of the sparse CSR matrix. * @param[out] * csr_row_ptr array of \p m+1 elements that point to the start of every row of the - * sparse \p CSR matrix. + * sparse CSR matrix. * @param[in] * idx_base \ref rocsparse_index_base_zero or \ref rocsparse_index_base_one. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m or \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p coo_row_ind or \p csr_row_ptr + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m or \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p coo_row_ind or \p csr_row_ptr * pointer is invalid. + * + * \par Example + * This example converts a COO matrix into a CSR matrix. + * \code{.c} + * // 1 2 0 3 0 + * // A = 0 4 5 0 0 + * // 6 0 0 7 8 + * + * rocsparse_int m = 3; + * rocsparse_int n = 5; + * rocsparse_int nnz = 8; + * + * coo_row_ind[nnz] = {0, 0, 0, 1, 1, 2, 2, 2}; // device memory + * coo_col_ind[nnz] = {0, 1, 3, 1, 2, 0, 3, 4}; // device memory + * coo_val[nnz] = {1, 2, 3, 4, 5, 6, 7, 8}; // device memory + * + * // Allocate CSR matrix arrays + * rocsparse_int* csr_row_ptr; + * rocsparse_int* csr_col_ind; + * float* csr_val; + * + * hipMalloc((void**)&csr_row_ptr, sizeof(rocsparse_int) * (m + 1)); + * hipMalloc((void**)&csr_col_ind, sizeof(rocsparse_int) * nnz); + * hipMalloc((void**)&csr_val, sizeof(float) * nnz); + * + * // Convert the coo row indices into csr row offsets + * rocsparse_coo2csr(handle, + * coo_row_ind, + * nnz, + * m, + * csr_row_ptr, + * rocsparse_index_base_zero); + * + * // Copy the column and value arrays + * hipMemcpy(csr_col_ind, + * coo_col_ind, + * sizeof(rocsparse_int) * nnz, + * hipMemcpyDeviceToDevice); + * + * hipMemcpy(csr_val, + * coo_val, + * sizeof(float) * nnz, + * hipMemcpyDeviceToDevice); + * \endcode */ ROCSPARSE_EXPORT rocsparse_status rocsparse_coo2csr(rocsparse_handle handle, @@ -2690,46 +3099,48 @@ rocsparse_status rocsparse_coo2csr(rocsparse_handle handle, rocsparse_index_base idx_base); /*! \ingroup conv_module - * \brief Convert a sparse \p ELL matrix into sparse \p CSR matrix + * \brief Convert a sparse ELL matrix into a sparse CSR matrix * * \details - * \p rocsparse_ell2csr_nnz computes the total \p CSR non-zero elements and the \p CSR - * row offsets, that point to the start of every row of the sparse \p CSR matrix, for - * a given \p ELL matrix. It is assumed that \p csr_row_ptr has been allocated with + * \p rocsparse_ell2csr_nnz computes the total CSR non-zero elements and the CSR + * row offsets, that point to the start of every row of the sparse CSR matrix, for + * a given ELL matrix. It is assumed that \p csr_row_ptr has been allocated with * size \p m + 1. * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] - * m number of rows of the sparse \p ELL matrix. + * m number of rows of the sparse ELL matrix. * @param[in] - * n number of columns of the sparse \p ELL matrix. + * n number of columns of the sparse ELL matrix. * @param[in] - * ell_descr descriptor of the sparse \p ELL matrix. Currently, only + * ell_descr descriptor of the sparse ELL matrix. Currently, only * \ref rocsparse_matrix_type_general is supported. * @param[in] - * ell_width number of non-zero elements per row in \p ELL storage format. + * ell_width number of non-zero elements per row in ELL storage format. * @param[in] * ell_col_ind array of \p m times \p ell_width elements containing the column indices - * of the sparse \p ELL matrix. + * of the sparse ELL matrix. * @param[in] - * csr_descr descriptor of the sparse \p CSR matrix. Currently, only + * csr_descr descriptor of the sparse CSR matrix. Currently, only * \ref rocsparse_matrix_type_general is supported. * @param[out] * csr_row_ptr array of \p m+1 elements that point to the start of every row of the - * sparse \p CSR matrix. + * sparse CSR matrix. * @param[out] - * csr_nnz pointer to the total number of non-zero elements in \p CSR storage + * csr_nnz pointer to the total number of non-zero elements in CSR storage * format. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m, \p n or \p ell_width is - * invalid.
- * \ref rocsparse_status_invalid_pointer \p ell_descr, \p ell_col_ind, - * \p csr_descr, \p csr_row_ptr or \p csr_nnz pointer is invalid.
- * \ref rocsparse_status_not_implemented + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m, \p n or \p ell_width is invalid. + * \retval rocsparse_status_invalid_pointer \p ell_descr, \p ell_col_ind, + * \p csr_descr, \p csr_row_ptr or \p csr_nnz pointer is invalid. + * \retval rocsparse_status_not_implemented * \ref rocsparse_matrix_type != \ref rocsparse_matrix_type_general. */ ROCSPARSE_EXPORT @@ -2744,52 +3155,111 @@ rocsparse_status rocsparse_ell2csr_nnz(rocsparse_handle handle, rocsparse_int* csr_nnz); /*! \ingroup conv_module - * \brief Convert a sparse \p ELL matrix into sparse \p CSR matrix + * \brief Convert a sparse ELL matrix into a sparse CSR matrix * * \details - * \p rocsparse_ell2csr converts an \p ELL matrix into a \p CSR matrix. It is assumed + * \p rocsparse_ell2csr converts an ELL matrix into a CSR matrix. It is assumed * that \p csr_row_ptr has already been filled and that \p csr_val and \p csr_col_ind * are allocated by the user. \p csr_row_ptr and allocation size of \p csr_col_ind and * \p csr_val is defined by the number of CSR non-zero elements. Both can be obtained * by rocsparse_ell2csr_nnz(). * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] - * m number of rows of the sparse \p ELL matrix. + * m number of rows of the sparse ELL matrix. * @param[in] - * n number of columns of the sparse \p ELL matrix. + * n number of columns of the sparse ELL matrix. * @param[in] - * ell_descr descriptor of the sparse \p ELL matrix. Currently, only + * ell_descr descriptor of the sparse ELL matrix. Currently, only * \ref rocsparse_matrix_type_general is supported. * @param[in] - * ell_width number of non-zero elements per row in \p ELL storage format. + * ell_width number of non-zero elements per row in ELL storage format. * @param[in] - * ell_val array of \p m times \p ell_width elements of the sparse \p ELL matrix. + * ell_val array of \p m times \p ell_width elements of the sparse ELL matrix. * @param[in] * ell_col_ind array of \p m times \p ell_width elements containing the column indices - * of the sparse \p ELL matrix. + * of the sparse ELL matrix. * @param[in] - * csr_descr descriptor of the sparse \p CSR matrix. Currently, only + * csr_descr descriptor of the sparse CSR matrix. Currently, only * \ref rocsparse_matrix_type_general is supported. * @param[out] - * csr_val array containing the values of the sparse \p CSR matrix. + * csr_val array containing the values of the sparse CSR matrix. * @param[in] * csr_row_ptr array of \p m+1 elements that point to the start of every row of the - * sparse \p CSR matrix. + * sparse CSR matrix. * @param[out] - * csr_col_ind array containing the column indices of the sparse \p CSR matrix. - * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m, \p n or \p ell_width is - * invalid.
- * \ref rocsparse_status_invalid_pointer \p csr_descr, \p csr_val, + * csr_col_ind array containing the column indices of the sparse CSR matrix. + * + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m, \p n or \p ell_width is invalid. + * \retval rocsparse_status_invalid_pointer \p csr_descr, \p csr_val, * \p csr_row_ptr, \p csr_col_ind, \p ell_descr, \p ell_val or - * \p ell_col_ind pointer is invalid.
- * \ref rocsparse_status_not_implemented + * \p ell_col_ind pointer is invalid. + * \retval rocsparse_status_not_implemented * \ref rocsparse_matrix_type != \ref rocsparse_matrix_type_general. + * + * \par Example + * This example converts an ELL matrix into a CSR matrix. + * \code{.c} + * // 1 2 0 3 0 + * // A = 0 4 5 0 0 + * // 6 0 0 7 8 + * + * rocsparse_int m = 3; + * rocsparse_int n = 5; + * rocsparse_int nnz = 9; + * rocsparse_int ell_width = 3; + * + * ell_col_ind[nnz] = {0, 1, 0, 1, 2, 3, 3, -1, 4}; // device memory + * ell_val[nnz] = {1, 4, 6, 2, 5, 7, 3, 0, 8}; // device memory + * + * // Create CSR matrix descriptor + * rocsparse_mat_descr csr_descr; + * rocsparse_create_mat_descr(&csr_descr); + * + * // Allocate csr_row_ptr array for row offsets + * rocsparse_int* csr_row_ptr; + * hipMalloc((void**)&csr_row_ptr, sizeof(rocsparse_int) * (m + 1)); + * + * // Obtain the number of CSR non-zero entries + * // and fill csr_row_ptr array with row offsets + * rocsparse_int csr_nnz; + * rocsparse_ell2csr_nnz(handle, + * m, + * n, + * ell_descr, + * ell_width, + * ell_col_ind, + * csr_descr, + * csr_row_ptr, + * &csr_nnz); + * + * // Allocate CSR column and value arrays + * rocsparse_int* csr_col_ind; + * hipMalloc((void**)&csr_col_ind, sizeof(rocsparse_int) * csr_nnz); + * + * float* csr_val; + * hipMalloc((void**)&csr_val, sizeof(float) * csr_nnz); + * + * // Format conversion + * rocsparse_sell2csr(handle, + * m, + * n, + * ell_descr, + * ell_width, + * ell_val, + * ell_col_ind, + * csr_descr, + * csr_val, + * csr_row_ptr, + * csr_col_ind); + * \endcode */ /**@{*/ ROCSPARSE_EXPORT @@ -2860,6 +3330,10 @@ rocsparse_status rocsparse_zell2csr(rocsparse_handle handle, * } * \endcode * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] @@ -2867,18 +3341,30 @@ rocsparse_status rocsparse_zell2csr(rocsparse_handle handle, * @param[out] * p array of \p n integers containing the map. * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p n is invalid.
- * \ref rocsparse_status_invalid_pointer \p p pointer is invalid. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p n is invalid. + * \retval rocsparse_status_invalid_pointer \p p pointer is invalid. + * + * \par Example + * The following example creates an identity permutation. + * \code{.c} + * rocsparse_int size = 200; + * + * // Allocate memory to hold the identity map + * rocsparse_int* perm; + * hipMalloc((void**)&perm, sizeof(rocsparse_int) * size); + * + * // Fill perm with the identity permutation + * rocsparse_create_identity_permutation(handle, size, perm); + * \endcode */ ROCSPARSE_EXPORT rocsparse_status rocsparse_create_identity_permutation(rocsparse_handle handle, rocsparse_int n, rocsparse_int* p); /*! \ingroup conv_module - * \brief Sort a sparse \p CSR matrix + * \brief Sort a sparse CSR matrix * * \details * \p rocsparse_csrsort_buffer_size returns the size of the temporary storage buffer @@ -2888,26 +3374,25 @@ rocsparse_create_identity_permutation(rocsparse_handle handle, rocsparse_int n, * @param[in] * handle handle to the rocsparse library context queue. * @param[in] - * m number of rows of the sparse \p CSR matrix. + * m number of rows of the sparse CSR matrix. * @param[in] - * n number of columns of the sparse \p CSR matrix. + * n number of columns of the sparse CSR matrix. * @param[in] - * nnz number of non-zero entries of the sparse \p CSR matrix. + * nnz number of non-zero entries of the sparse CSR matrix. * @param[in] * csr_row_ptr array of \p m+1 elements that point to the start of every row of the - * sparse \p CSR matrix. + * sparse CSR matrix. * @param[in] * csr_col_ind array of \p nnz elements containing the column indices of the sparse - * \p CSR matrix. + * CSR matrix. * @param[out] * buffer_size number of bytes of the temporary storage buffer required by * rocsparse_csrsort(). * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p csr_row_ptr, \p csr_col_ind or + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p csr_row_ptr, \p csr_col_ind or * \p buffer_size pointer is invalid. */ ROCSPARSE_EXPORT @@ -2920,33 +3405,40 @@ rocsparse_status rocsparse_csrsort_buffer_size(rocsparse_handle handle, size_t* buffer_size); /*! \ingroup conv_module - * \brief Sort a sparse \p CSR matrix + * \brief Sort a sparse CSR matrix * * \details - * \p rocsparse_csrsort sorts a matrix in \p CSR format. The sorted permutation vector + * \p rocsparse_csrsort sorts a matrix in CSR format. The sorted permutation vector * \p perm can be used to obtain sorted \p csr_val array. In this case, \p perm must be * initialized as the identity permutation, see rocsparse_create_identity_permutation(). * - * rocsparse_csrsort requires extra temporary storage buffer that has to be allocated by + * \p rocsparse_csrsort requires extra temporary storage buffer that has to be allocated by * the user. Storage buffer size can be determined by rocsparse_csrsort_buffer_size(). * + * \note + * \p perm can be \p NULL if a sorted permutation vector is not required. + * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] - * m number of rows of the sparse \p CSR matrix. + * m number of rows of the sparse CSR matrix. * @param[in] - * n number of columns of the sparse \p CSR matrix. + * n number of columns of the sparse CSR matrix. * @param[in] - * nnz number of non-zero entries of the sparse \p CSR matrix. + * nnz number of non-zero entries of the sparse CSR matrix. * @param[in] - * descr descriptor of the sparse \p CSR matrix. Currently, only + * descr descriptor of the sparse CSR matrix. Currently, only * \ref rocsparse_matrix_type_general is supported. * @param[in] * csr_row_ptr array of \p m+1 elements that point to the start of every row of the - * sparse \p CSR matrix. + * sparse CSR matrix. * @param[inout] * csr_col_ind array of \p nnz elements containing the column indices of the sparse - * \p CSR matrix. + * CSR matrix. * @param[inout] * perm array of \p nnz integers containing the unsorted map indices, can be * \p NULL. @@ -2954,17 +3446,17 @@ rocsparse_status rocsparse_csrsort_buffer_size(rocsparse_handle handle, * temp_buffer temporary storage buffer allocated by the user, size is returned by * rocsparse_csrsort_buffer_size(). * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p descr, \p csr_row_ptr, - * \p csr_col_ind or \p temp_buffer pointer is invalid.
- * \ref rocsparse_status_internal_error an internal error occurred.
- * \ref rocsparse_status_not_implemented + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p descr, \p csr_row_ptr, \p csr_col_ind + * or \p temp_buffer pointer is invalid. + * \retval rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_not_implemented * \ref rocsparse_matrix_type != \ref rocsparse_matrix_type_general. * * \par Example + * The following example sorts a \f$3 \times 3\f$ CSR matrix. * \code{.c} * // 1 2 3 * // A = 4 5 6 @@ -2977,22 +3469,22 @@ rocsparse_status rocsparse_csrsort_buffer_size(rocsparse_handle handle, * csr_col_ind[nnz] = {2, 0, 1, 0, 1, 2, 0, 2, 1}; // device memory * csr_val[nnz] = {3, 1, 2, 4, 5, 6, 7, 9, 8}; // device memory * - * // Allocate temporary buffer - * size_t buffer_size = 0; - * void* temp_buffer = NULL; - * rocsparse_csrsort_buffer_size(handle, m, n, nnz, csr_row_ptr, csr_col_ind, &buffer_size); - * hipMalloc(&temp_buffer, sizeof(char) * buffer_size); - * * // Create permutation vector perm as the identity map - * rocsparse_int* perm = NULL; + * rocsparse_int* perm; * hipMalloc((void**)&perm, sizeof(rocsparse_int) * nnz); * rocsparse_create_identity_permutation(handle, nnz, perm); * + * // Allocate temporary buffer + * size_t buffer_size; + * void* temp_buffer; + * rocsparse_csrsort_buffer_size(handle, m, n, nnz, csr_row_ptr, csr_col_ind, &buffer_size); + * hipMalloc(&temp_buffer, buffer_size); + * * // Sort the CSR matrix * rocsparse_csrsort(handle, m, n, nnz, descr, csr_row_ptr, csr_col_ind, perm, temp_buffer); * * // Gather sorted csr_val array - * float* csr_val_sorted = NULL; + * float* csr_val_sorted; * hipMalloc((void**)&csr_val_sorted, sizeof(float) * nnz); * rocsparse_sgthr(handle, nnz, csr_val, csr_val_sorted, perm, rocsparse_index_base_zero); * @@ -3014,38 +3506,37 @@ rocsparse_status rocsparse_csrsort(rocsparse_handle handle, void* temp_buffer); /*! \ingroup conv_module - * \brief Sort a sparse \p COO matrix + * \brief Sort a sparse COO matrix * * \details - * coosort_buffer_size returns the size of the temporary storage buffer - * that is required by coosort. The temporary storage buffer has to be - * allocated by the user. + * \p coosort_buffer_size returns the size of the temporary storage buffer that is + * required by rocsparse_coosort_by_row() and rocsparse_coosort_by_column(). The + * temporary storage buffer has to be allocated by the user. * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] - * m number of rows of the sparse \p COO matrix. + * m number of rows of the sparse COO matrix. * @param[in] - * n number of columns of the sparse \p COO matrix. + * n number of columns of the sparse COO matrix. * @param[in] - * nnz number of non-zero entries of the sparse \p COO matrix. + * nnz number of non-zero entries of the sparse COO matrix. * @param[in] * coo_row_ind array of \p nnz elements containing the row indices of the sparse - * \p COO matrix. + * COO matrix. * @param[in] * coo_col_ind array of \p nnz elements containing the column indices of the sparse - * \p COO matrix. + * COO matrix. * @param[out] * buffer_size number of bytes of the temporary storage buffer required by * rocsparse_coosort_by_row() and rocsparse_coosort_by_column(). * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p coo_row_ind, \p coo_col_ind or - * \p buffer_size pointer is invalid.
- * \ref rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p coo_row_ind, \p coo_col_ind or + * \p buffer_size pointer is invalid. + * \retval rocsparse_status_internal_error an internal error occurred. */ ROCSPARSE_EXPORT rocsparse_status rocsparse_coosort_buffer_size(rocsparse_handle handle, @@ -3057,32 +3548,39 @@ rocsparse_status rocsparse_coosort_buffer_size(rocsparse_handle handle, size_t* buffer_size); /*! \ingroup conv_module - * \brief Sort a sparse \p COO matrix by row + * \brief Sort a sparse COO matrix by row * * \details - * \p rocsparse_coosort_by_row sorts a matrix in \p COO format by row. The sorted + * \p rocsparse_coosort_by_row sorts a matrix in COO format by row. The sorted * permutation vector \p perm can be used to obtain sorted \p coo_val array. In this * case, \p perm must be initialized as the identity permutation, see * rocsparse_create_identity_permutation(). * - * rocsparse_coosort_by_row requires extra temporary storage buffer that has to be + * \p rocsparse_coosort_by_row requires extra temporary storage buffer that has to be * allocated by the user. Storage buffer size can be determined by * rocsparse_coosort_buffer_size(). * + * \note + * \p perm can be \p NULL if a sorted permutation vector is not required. + * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] - * m number of rows of the sparse \p COO matrix. + * m number of rows of the sparse COO matrix. * @param[in] - * n number of columns of the sparse \p COO matrix. + * n number of columns of the sparse COO matrix. * @param[in] - * nnz number of non-zero entries of the sparse \p COO matrix. + * nnz number of non-zero entries of the sparse COO matrix. * @param[inout] * coo_row_ind array of \p nnz elements containing the row indices of the sparse - * \p COO matrix. + * COO matrix. * @param[inout] * coo_col_ind array of \p nnz elements containing the column indices of the sparse - * \p COO matrix. + * COO matrix. * @param[inout] * perm array of \p nnz integers containing the unsorted map indices, can be * \p NULL. @@ -3090,13 +3588,64 @@ rocsparse_status rocsparse_coosort_buffer_size(rocsparse_handle handle, * temp_buffer temporary storage buffer allocated by the user, size is returned by * rocsparse_coosort_buffer_size(). * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p coo_row_ind, \p coo_col_ind or - * \p temp_buffer pointer is invalid.
- * \ref rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p coo_row_ind, \p coo_col_ind or + * \p temp_buffer pointer is invalid. + * \retval rocsparse_status_internal_error an internal error occurred. + * + * \par Example + * The following example sorts a \f$3 \times 3\f$ COO matrix by row indices. + * \code{.c} + * // 1 2 3 + * // A = 4 5 6 + * // 7 8 9 + * rocsparse_int m = 3; + * rocsparse_int n = 3; + * rocsparse_int nnz = 9; + * + * coo_row_ind[nnz] = {0, 1, 2, 0, 1, 2, 0, 1, 2}; // device memory + * coo_col_ind[nnz] = {0, 0, 0, 1, 1, 1, 2, 2, 2}; // device memory + * coo_val[nnz] = {1, 4, 7, 2, 5, 8, 3, 6, 9}; // device memory + * + * // Create permutation vector perm as the identity map + * rocsparse_int* perm; + * hipMalloc((void**)&perm, sizeof(rocsparse_int) * nnz); + * rocsparse_create_identity_permutation(handle, nnz, perm); + * + * // Allocate temporary buffer + * size_t buffer_size; + * void* temp_buffer; + * rocsparse_coosort_buffer_size(handle, + * m, + * n, + * nnz, + * coo_row_ind, + * coo_col_ind, + * &buffer_size); + * hipMalloc(&temp_buffer, buffer_size); + * + * // Sort the COO matrix + * rocsparse_coosort_by_row(handle, + * m, + * n, + * nnz, + * coo_row_ind, + * coo_col_ind, + * perm, + * temp_buffer); + * + * // Gather sorted coo_val array + * float* coo_val_sorted; + * hipMalloc((void**)&coo_val_sorted, sizeof(float) * nnz); + * rocsparse_sgthr(handle, nnz, coo_val, coo_val_sorted, perm, rocsparse_index_base_zero); + * + * // Clean up + * hipFree(temp_buffer); + * hipFree(perm); + * hipFree(coo_val); + * \endcode */ ROCSPARSE_EXPORT rocsparse_status rocsparse_coosort_by_row(rocsparse_handle handle, @@ -3109,32 +3658,39 @@ rocsparse_status rocsparse_coosort_by_row(rocsparse_handle handle, void* temp_buffer); /*! \ingroup conv_module - * \brief Sort a sparse \p COO matrix by column + * \brief Sort a sparse COO matrix by column * * \details - * \p rocsparse_coosort_by_column sorts a matrix in \p COO format by column. The sorted + * \p rocsparse_coosort_by_column sorts a matrix in COO format by column. The sorted * permutation vector \p perm can be used to obtain sorted \p coo_val array. In this * case, \p perm must be initialized as the identity permutation, see * rocsparse_create_identity_permutation(). * - * rocsparse_coosort_by_column requires extra temporary storage buffer that has to be + * \p rocsparse_coosort_by_column requires extra temporary storage buffer that has to be * allocated by the user. Storage buffer size can be determined by * rocsparse_coosort_buffer_size(). * + * \note + * \p perm can be \p NULL if a sorted permutation vector is not required. + * + * \note + * This function is non blocking and executed asynchronously with respect to the host. + * It may return before the actual computation has finished. + * * @param[in] * handle handle to the rocsparse library context queue. * @param[in] - * m number of rows of the sparse \p COO matrix. + * m number of rows of the sparse COO matrix. * @param[in] - * n number of columns of the sparse \p COO matrix. + * n number of columns of the sparse COO matrix. * @param[in] - * nnz number of non-zero entries of the sparse \p COO matrix. + * nnz number of non-zero entries of the sparse COO matrix. * @param[inout] * coo_row_ind array of \p nnz elements containing the row indices of the sparse - * \p COO matrix. + * COO matrix. * @param[inout] * coo_col_ind array of \p nnz elements containing the column indices of the sparse - * \p COO matrix. + * COO matrix. * @param[inout] * perm array of \p nnz integers containing the unsorted map indices, can be * \p NULL. @@ -3142,13 +3698,64 @@ rocsparse_status rocsparse_coosort_by_row(rocsparse_handle handle, * temp_buffer temporary storage buffer allocated by the user, size is returned by * rocsparse_coosort_buffer_size(). * - * \returns \ref rocsparse_status_success the operation completed successfully.
- * \ref rocsparse_status_invalid_handle the library context was - * not initialized.
- * \ref rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid.
- * \ref rocsparse_status_invalid_pointer \p coo_row_ind, \p coo_col_ind or - * \p temp_buffer pointer is invalid.
- * \ref rocsparse_status_internal_error an internal error occurred. + * \retval rocsparse_status_success the operation completed successfully. + * \retval rocsparse_status_invalid_handle the library context was not initialized. + * \retval rocsparse_status_invalid_size \p m, \p n or \p nnz is invalid. + * \retval rocsparse_status_invalid_pointer \p coo_row_ind, \p coo_col_ind or + * \p temp_buffer pointer is invalid. + * \retval rocsparse_status_internal_error an internal error occurred. + * + * \par Example + * The following example sorts a \f$3 \times 3\f$ COO matrix by column indices. + * \code{.c} + * // 1 2 3 + * // A = 4 5 6 + * // 7 8 9 + * rocsparse_int m = 3; + * rocsparse_int n = 3; + * rocsparse_int nnz = 9; + * + * coo_row_ind[nnz] = {0, 0, 0, 1, 1, 1, 2, 2, 2}; // device memory + * coo_col_ind[nnz] = {0, 1, 2, 0, 1, 2, 0, 1, 2}; // device memory + * coo_val[nnz] = {1, 2, 3, 4, 5, 6, 7, 8, 9}; // device memory + * + * // Create permutation vector perm as the identity map + * rocsparse_int* perm; + * hipMalloc((void**)&perm, sizeof(rocsparse_int) * nnz); + * rocsparse_create_identity_permutation(handle, nnz, perm); + * + * // Allocate temporary buffer + * size_t buffer_size; + * void* temp_buffer; + * rocsparse_coosort_buffer_size(handle, + * m, + * n, + * nnz, + * coo_row_ind, + * coo_col_ind, + * &buffer_size); + * hipMalloc(&temp_buffer, buffer_size); + * + * // Sort the COO matrix + * rocsparse_coosort_by_column(handle, + * m, + * n, + * nnz, + * coo_row_ind, + * coo_col_ind, + * perm, + * temp_buffer); + * + * // Gather sorted coo_val array + * float* coo_val_sorted; + * hipMalloc((void**)&coo_val_sorted, sizeof(float) * nnz); + * rocsparse_sgthr(handle, nnz, coo_val, coo_val_sorted, perm, rocsparse_index_base_zero); + * + * // Clean up + * hipFree(temp_buffer); + * hipFree(perm); + * hipFree(coo_val); + * \endcode */ ROCSPARSE_EXPORT rocsparse_status rocsparse_coosort_by_column(rocsparse_handle handle, diff --git a/library/include/rocsparse-types.h b/library/include/rocsparse-types.h index 72816cf2..cb7b04d4 100644 --- a/library/include/rocsparse-types.h +++ b/library/include/rocsparse-types.h @@ -56,9 +56,9 @@ typedef struct _rocsparse_handle* rocsparse_handle; * * \details * The rocSPARSE matrix descriptor is a structure holding all properties of a matrix. - * It must be initialized using rocsparse_create_mat_descr() and the returned descriptor - * must be passed to all subsequent library calls that involve the matrix. It should be - * destroyed at the end using rocsparse_destroy_mat_descr(). + * It must be initialized using rocsparse_create_mat_descr() and the returned + * descriptor must be passed to all subsequent library calls that involve the matrix. + * It should be destroyed at the end using rocsparse_destroy_mat_descr(). */ typedef struct _rocsparse_mat_descr* rocsparse_mat_descr; @@ -69,8 +69,7 @@ typedef struct _rocsparse_mat_descr* rocsparse_mat_descr; * The rocSPARSE HYB matrix structure holds the HYB matrix. It must be initialized using * rocsparse_create_hyb_mat() and the returned HYB matrix must be passed to all * subsequent library calls that involve the matrix. It should be destroyed at the end - * using rocsparse_destroy_hyb_mat(). TODO For more details on the HYB format, see HYB storage - * format. + * using rocsparse_destroy_hyb_mat(). */ typedef struct _rocsparse_hyb_mat* rocsparse_hyb_mat; @@ -230,8 +229,7 @@ typedef enum rocsparse_pointer_mode_ { * \brief Indicates if layer is active with bitmask. * * \details - * The \ref rocsparse_layer_mode bit mask indicates the logging characteristics. See - * TODO rocsparse_logging for more informations. + * The \ref rocsparse_layer_mode bit mask indicates the logging characteristics. */ typedef enum rocsparse_layer_mode { rocsparse_layer_mode_none = 0x0, /**< layer is not active. */ diff --git a/library/src/conversion/csr2ell_device.h b/library/src/conversion/csr2ell_device.h index 144018f8..42d2631b 100644 --- a/library/src/conversion/csr2ell_device.h +++ b/library/src/conversion/csr2ell_device.h @@ -56,14 +56,12 @@ ell_width_kernel_part1(rocsparse_int m, const rocsparse_int* csr_row_ptr, rocspa rocsparse_int gid = hipBlockIdx_x * hipBlockDim_x + hipThreadIdx_x; __shared__ rocsparse_int sdata[NB]; + sdata[tid] = 0; - if(gid < m) - { - sdata[tid] = csr_row_ptr[gid + 1] - csr_row_ptr[gid]; - } - else + for(rocsparse_int idx = gid; idx < m; idx += hipGridDim_x * hipBlockDim_x) { - sdata[tid] = 0; + rocsparse_int row_nnz = csr_row_ptr[idx + 1] - csr_row_ptr[idx]; + sdata[tid] = max(sdata[tid], row_nnz); } ell_width_reduce(tid, sdata); diff --git a/library/src/conversion/ell2csr_device.h b/library/src/conversion/ell2csr_device.h index 32d137e7..0a3017be 100644 --- a/library/src/conversion/ell2csr_device.h +++ b/library/src/conversion/ell2csr_device.h @@ -29,6 +29,11 @@ #include +__global__ void ell2csr_index_base(rocsparse_int* __restrict__ nnz) +{ + --(*nnz); +} + __global__ void ell2csr_nnz_per_row(rocsparse_int m, rocsparse_int n, rocsparse_int ell_width, diff --git a/library/src/conversion/rocsparse_csr2ell.cpp b/library/src/conversion/rocsparse_csr2ell.cpp index 10cee34c..074e64ad 100644 --- a/library/src/conversion/rocsparse_csr2ell.cpp +++ b/library/src/conversion/rocsparse_csr2ell.cpp @@ -115,18 +115,20 @@ extern "C" rocsparse_status rocsparse_csr2ell_width(rocsparse_handle handle, // Determine ELL width -#define CSR2ELL_DIM 512 +#define CSR2ELL_DIM 1024 // Workspace size - rocsparse_int blocks = (m - 1) / CSR2ELL_DIM + 1; + rocsparse_int nblocks = CSR2ELL_DIM; - // Allocate workspace - rocsparse_int* workspace = NULL; - RETURN_IF_HIP_ERROR(hipMalloc((void**)&workspace, sizeof(rocsparse_int) * blocks)); + // Get workspace from handle device buffer + rocsparse_int* workspace = reinterpret_cast(handle->buffer); + + dim3 csr2ell_blocks(nblocks); + dim3 csr2ell_threads(CSR2ELL_DIM); // Compute maximum nnz per row hipLaunchKernelGGL((ell_width_kernel_part1), - dim3(blocks), - dim3(CSR2ELL_DIM), + csr2ell_blocks, + csr2ell_threads, 0, stream, m, @@ -135,10 +137,10 @@ extern "C" rocsparse_status rocsparse_csr2ell_width(rocsparse_handle handle, hipLaunchKernelGGL((ell_width_kernel_part2), dim3(1), - dim3(CSR2ELL_DIM), + csr2ell_threads, 0, stream, - blocks, + nblocks, workspace); // Copy ELL width back to host, if handle says so @@ -153,9 +155,6 @@ extern "C" rocsparse_status rocsparse_csr2ell_width(rocsparse_handle handle, hipMemcpy(ell_width, workspace, sizeof(rocsparse_int), hipMemcpyDeviceToHost)); } - // Free workspace - RETURN_IF_HIP_ERROR(hipFree(workspace)); - return rocsparse_status_success; } diff --git a/library/src/conversion/rocsparse_ell2csr.cpp b/library/src/conversion/rocsparse_ell2csr.cpp index 1b6d028f..cbc550e2 100644 --- a/library/src/conversion/rocsparse_ell2csr.cpp +++ b/library/src/conversion/rocsparse_ell2csr.cpp @@ -150,37 +150,53 @@ extern "C" rocsparse_status rocsparse_ell2csr_nnz(rocsparse_handle handle, #undef ELL2CSR_DIM // Exclusive sum to obtain csr_row_ptr array and number of non-zero elements - void* d_temp_storage = nullptr; size_t temp_storage_bytes = 0; // Obtain hipcub buffer size RETURN_IF_HIP_ERROR(hipcub::DeviceScan::InclusiveSum( - d_temp_storage, temp_storage_bytes, csr_row_ptr, csr_row_ptr, m + 1)); + nullptr, temp_storage_bytes, csr_row_ptr, csr_row_ptr, m + 1)); + + // Get hipcub buffer + bool d_temp_alloc; + void* d_temp_storage; - // Allocate hipcub buffer - RETURN_IF_HIP_ERROR(hipMalloc(&d_temp_storage, temp_storage_bytes)); + // Device buffer should be sufficient for hipcub in most cases + if(handle->buffer_size >= temp_storage_bytes) + { + d_temp_storage = handle->buffer; + d_temp_alloc = false; + } + else + { + RETURN_IF_HIP_ERROR(hipMalloc(&d_temp_storage, temp_storage_bytes)); + d_temp_alloc = true; + } // Perform actual inclusive sum RETURN_IF_HIP_ERROR(hipcub::DeviceScan::InclusiveSum( d_temp_storage, temp_storage_bytes, csr_row_ptr, csr_row_ptr, m + 1)); - // Extract and adjust nnz according to index base + // Extract and adjust nnz if(csr_descr->base == rocsparse_index_base_one) { - rocsparse_int nnz; - RETURN_IF_HIP_ERROR( - hipMemcpy(&nnz, csr_row_ptr + m, sizeof(rocsparse_int), hipMemcpyDeviceToHost)); - - nnz -= csr_descr->base; - if(handle->pointer_mode == rocsparse_pointer_mode_device) { - RETURN_IF_HIP_ERROR( - hipMemcpy(csr_nnz, &nnz, sizeof(rocsparse_int), hipMemcpyHostToDevice)); + RETURN_IF_HIP_ERROR(hipMemcpyAsync(csr_nnz, csr_row_ptr + m, sizeof(rocsparse_int), hipMemcpyDeviceToDevice, stream)); + + // Adjust nnz according to index base + hipLaunchKernelGGL((ell2csr_index_base), + dim3(1), + dim3(1), + 0, + stream, + csr_nnz); } else { - *csr_nnz = nnz; + RETURN_IF_HIP_ERROR(hipMemcpy(csr_nnz, csr_row_ptr + m, sizeof(rocsparse_int), hipMemcpyDeviceToHost)); + + // Adjust nnz according to index base + *csr_nnz -= csr_descr->base; } } else @@ -197,8 +213,11 @@ extern "C" rocsparse_status rocsparse_ell2csr_nnz(rocsparse_handle handle, } } - // Free hipcub buffer - RETURN_IF_HIP_ERROR(hipFree(d_temp_storage)); + // Free hipcub buffer, if allocated + if(d_temp_alloc == true) + { + RETURN_IF_HIP_ERROR(hipFree(d_temp_storage)); + } return rocsparse_status_success; } diff --git a/library/src/handle.cpp b/library/src/handle.cpp index f02220cc..3897b640 100644 --- a/library/src/handle.cpp +++ b/library/src/handle.cpp @@ -50,15 +50,17 @@ _rocsparse_handle::_rocsparse_handle() layer_mode = (rocsparse_layer_mode)(atoi(str_layer_mode)); } - // Allocating small device buffer + // Obtain size for coomv device buffer rocsparse_int nthreads = properties.maxThreadsPerBlock; rocsparse_int nprocs = properties.multiProcessorCount; rocsparse_int nblocks = (nprocs * nthreads - 1) / 128 + 1; rocsparse_int nwfs = nblocks * (128 / properties.warpSize); - size_t size = (((sizeof(rocsparse_int) + 16) * nwfs - 1) / 256 + 1) * 256; + size_t coomv_size = (((sizeof(rocsparse_int) + 16) * nwfs - 1) / 256 + 1) * 256; - THROW_IF_HIP_ERROR(hipMalloc(&buffer, size)); + // Allocate device buffer + buffer_size = (coomv_size > 1024 * 1024) ? coomv_size : 1024 * 1024; + THROW_IF_HIP_ERROR(hipMalloc(&buffer, buffer_size)); // Device one THROW_IF_HIP_ERROR(hipMalloc(&sone, sizeof(float))); diff --git a/library/src/include/handle.h b/library/src/include/handle.h index c63583ab..7b76c2ee 100644 --- a/library/src/include/handle.h +++ b/library/src/include/handle.h @@ -68,6 +68,7 @@ struct _rocsparse_handle // logging mode rocsparse_layer_mode layer_mode; // device buffer + size_t buffer_size; void* buffer; // device one float* sone; diff --git a/library/src/level1/doti_device.h b/library/src/level1/doti_device.h index faa524f6..5072798a 100644 --- a/library/src/level1/doti_device.h +++ b/library/src/level1/doti_device.h @@ -53,18 +53,15 @@ __global__ void doti_kernel_part1(rocsparse_int nnz, T* workspace, rocsparse_index_base idx_base) { - rocsparse_int idx = hipBlockIdx_x * hipBlockDim_x + hipThreadIdx_x; rocsparse_int tid = hipThreadIdx_x; + rocsparse_int gid = hipBlockDim_x * hipBlockIdx_x + tid; __shared__ T sdata[NB]; + sdata[tid] = static_cast(0); - if(idx < nnz) - { - sdata[tid] = y[x_ind[idx] - idx_base] * x_val[idx]; - } - else + for(rocsparse_int idx = gid; idx < nnz; idx += hipGridDim_x * hipBlockDim_x) { - sdata[tid] = static_cast(0); + sdata[tid] += y[x_ind[idx] - idx_base] * x_val[idx]; } rocsparse_sum_reduce(tid, sdata); @@ -90,20 +87,7 @@ __global__ void doti_kernel_part2(rocsparse_int n, T* workspace, T* result) } __syncthreads(); - if(n < 32) - { - if(tid == 0) - { - for(rocsparse_int i = 1; i < n; ++i) - { - sdata[0] += sdata[i]; - } - } - } - else - { - rocsparse_sum_reduce(tid, sdata); - } + rocsparse_sum_reduce(tid, sdata); if(tid == 0) { diff --git a/library/src/level1/rocsparse_doti.hpp b/library/src/level1/rocsparse_doti.hpp index e3727289..72e2e0b3 100644 --- a/library/src/level1/rocsparse_doti.hpp +++ b/library/src/level1/rocsparse_doti.hpp @@ -113,12 +113,11 @@ rocsparse_status rocsparse_doti_template(rocsparse_handle handle, // Stream hipStream_t stream = handle->stream; -#define DOTI_DIM 512 - rocsparse_int nblocks = (nnz - 1) / DOTI_DIM + 1; +#define DOTI_DIM 1024 + rocsparse_int nblocks = DOTI_DIM; - // Allocate workspace - T* workspace = NULL; - RETURN_IF_HIP_ERROR(hipMalloc((void**)&workspace, sizeof(T) * nblocks)); + // Get workspace from handle device buffer + T* workspace = reinterpret_cast(handle->buffer); dim3 doti_blocks(nblocks); dim3 doti_threads(DOTI_DIM); @@ -148,22 +147,18 @@ rocsparse_status rocsparse_doti_template(rocsparse_handle handle, } else { - if(nblocks > 1) - { - hipLaunchKernelGGL((doti_kernel_part2), - dim3(1), - doti_threads, - 0, - stream, - nblocks, - workspace, - result); - } + hipLaunchKernelGGL((doti_kernel_part2), + dim3(1), + doti_threads, + 0, + stream, + nblocks, + workspace, + result); + RETURN_IF_HIP_ERROR(hipMemcpy(result, workspace, sizeof(T), hipMemcpyDeviceToHost)); } - RETURN_IF_HIP_ERROR(hipFree(workspace)); - return rocsparse_status_success; }