diff --git a/Libraries/hipBLAS/gemm_strided_batched/README.md b/Libraries/hipBLAS/gemm_strided_batched/README.md index 178fe599..292e8c17 100644 --- a/Libraries/hipBLAS/gemm_strided_batched/README.md +++ b/Libraries/hipBLAS/gemm_strided_batched/README.md @@ -4,17 +4,17 @@ This example illustrates the use of the hipBLAS Level 3 Strided Batched General Matrix Multiplication. The hipBLAS GEMM STRIDED BATCHED performs a matrix--matrix operation for a _batch_ of matrices as: -$C[i] = \alpha \cdot A[i]' \cdot B[i]' + \beta \cdot (C[i])$ +$C[i] = \alpha \cdot op_a(A[i]) \cdot op_b(B[i]) + \beta \cdot (C[i])$ -for each $i \in [0, batch - 1]$, where $X[i] = X + i \cdot strideX$ is the $i$-th element of the correspondent batch and $X'$ is one of the following: +for each $i \in [0, batch - 1]$, where $X[i] = X + i \cdot strideX$ is the $i$-th element of the correspondent batch and $op_m(M)$ is one of the following: -- $X' = X$ or -- $X' = X^T$ (transpose $X$: $X_{ij}^T = X_{ji}$) or -- $X' = X^H$ (Hermitian $X$: $X_{ij}^H = \bar X_{ji} $). +- $op_m(M) = M$ or +- $op_m(M) = M^T$ (transpose $M$: $M_{ij}^T = M_{ji}$) or +- $op_m(M) = M^H$ (Hermitian $M$: $M_{ij}^H = \bar M_{ji} $). In this example the identity is used. $\alpha$ and $\beta$ are scalars, and $A$, $B$ and $C$ are the batches of matrices. For each $i$, $A[i]$, $B[i]$ and $C[i]$ are matrices such that -$A_i'$ is an $m \times k$ matrix, $B_i'$ a $k \times n$ matrix and $C_i$ an $m \times n$ matrix. +$op_a(A[i])$ is an $m \times k$ matrix, $op_b(B[i])$ a $k \times n$ matrix and $C_i$ an $m \times n$ matrix. ### Application flow @@ -48,11 +48,10 @@ The application provides the following optional command line arguments: We can apply the same multiplication operator for several matrices if we combine them into batched matrices. Batched matrix multiplication has a performance improvement for a large number of small matrices. For a constant stride between matrices, further acceleration is available by strided batched GEMM. - hipBLAS is initialized by calling `hipblasCreate(hipblasHandle*)` and it is terminated by calling `hipblasDestroy(hipblasHandle)`. - The _pointer mode_ controls whether scalar parameters must be allocated on the host (`HIPBLAS_POINTER_MODE_HOST`) or on the device (`HIPBLAS_POINTER_MODE_DEVICE`). It is controlled by `hipblasSetPointerMode`. -- The symbol $X'$ denotes the following operations, as defined in the Description section: - - - `HIPBLAS_OP_N`: identity operator ($X' = X$), - - `HIPBLAS_OP_T`: transpose operator ($X' = X^T$) or - - `HIPBLAS_OP_C`: Hermitian (conjugate transpose) operator ($X' = X^H$). +- The symbol $op(M)$ denotes the following operations, as defined in the Description section: + - `HIPBLAS_OP_N`: identity operator ($op(M) = M$), + - `HIPBLAS_OP_T`: transpose operator ($op(M) = M^T$) or + - `HIPBLAS_OP_C`: Hermitian (conjugate transpose) operator ($op(M) = M^H$). - `hipblasStride` strides between matrices or vectors in strided_batched functions. - `hipblas[HSDCZ]gemmStridedBatched` @@ -63,7 +62,25 @@ We can apply the same multiplication operator for several matrices if we combine - `C` (single-precision complex: `hipblasComplex`) - `Z` (double-precision complex: `hipblasDoubleComplex`). - Input parameters for `hipblasSgemmStridedBatched`: + Input parameters for `hipblasSgemmStridedBatched`: + - `hipblasHandle_t handle` + - `hipblasOperation_t trans_a`: transformation operator on each $A_i$ matrix + - `hipblasOperation_t trans_b`: transformation operator on each $B_i$ matrix + - `int m`: number of rows in each $op_a(A[i])$ and $C$ matrices + - `int n`: number of columns in each $op_b(B[i])$ and $C$ matrices + - `int k`: number of columns in each $op_a(A[i])$ matrix and number of rows in each $op_b(B[i])$ matrix + - `const float *alpha`: scalar multiplier of each $C_i$ matrix addition + - `const float *A`: pointer to the each $A_i$ matrix + - `int lda`: leading dimension of each $A_i$ matrix + - `long long stride_a`: stride size for each $A_i$ matrix + - `const float *B`: pointer to each $B_i$ matrix + - `int ldb`: leading dimension of each $B_i$ matrix + - `const float *beta`: scalar multiplier of the $B \cdot C$ matrix product + - `long long stride_b`: stride size for each $B_i$ matrix + - `float *C`: pointer to each $C_i$ matrix + - `int ldc`: leading dimension of each $C_i$ matrix + - `long long stride_c`: stride size for each $C_i$ matrix + - `int batch_count`: number of matrices - `hipblasHandle_t handle` - `hipblasOperation_t trans_a`: transformation operator on each $A_i$ matrix diff --git a/Libraries/hipBLAS/gemm_strided_batched/main.hip b/Libraries/hipBLAS/gemm_strided_batched/main.hip index 456d40cd..3e4aa63b 100644 --- a/Libraries/hipBLAS/gemm_strided_batched/main.hip +++ b/Libraries/hipBLAS/gemm_strided_batched/main.hip @@ -1,6 +1,6 @@ // MIT License // -// Copyright (c) 2022-204 Advanced Micro Devices, Inc. All rights reserved. +// Copyright (c) 2022-2024 Advanced Micro Devices, Inc. All rights reserved. // // Permission is hereby granted, free of charge, to any person obtaining a copy // of this software and associated documentation files (the "Software"), to deal @@ -84,7 +84,7 @@ int main(const int argc, const char** argv) const float h_alpha = parser.get("a"); const float h_beta = parser.get("b"); - // Set GEMM operation as identity operation: $X' = X$ + // Set GEMM operation as identity operation: $op(X) = X$ const hipblasOperation_t trans_a = HIPBLAS_OP_N; const hipblasOperation_t trans_b = HIPBLAS_OP_N; diff --git a/Libraries/rocBLAS/level_2/gemv/README.md b/Libraries/rocBLAS/level_2/gemv/README.md index b7b4db93..d4a0030b 100644 --- a/Libraries/rocBLAS/level_2/gemv/README.md +++ b/Libraries/rocBLAS/level_2/gemv/README.md @@ -34,11 +34,9 @@ The application provides the following optional command line arguments: - The _pointer mode_ controls whether scalar parameters must be allocated on the host (`rocblas_pointer_mode_host`) or on the device (`rocblas_pointer_mode_device`). It is controlled by `rocblas_set_pointer_mode`. - `rocblas_Xgemv(handle, trans, m, n, *alpha, *A, lda, *x, incx, *beta, *y, incy)` computes a general matrix-vector product. `m` and `n` specify the dimensions of matrix $A$ _before_ any transpose operation is performed on it. `lda` is the _leading dimension_ of $A$: the number of elements between the starts of columns of $A$. Columns of $A$ are packed in memory. Note that rocBLAS matrices are stored in _column major_ ordering in memory. `x` and `y` specify vectors $x$ and $y$, and `incx` and `incy` denote the increment between consecutive items of the respective vectors in elements. `trans` specifies a matrix operation that may be performed before the matrix-vector product is computed: - - `rocblas_operation_none` specifies that no operation is performed. In this case, $x$ needs to have $n$ elements, and $y$ needs to have $m$ elements. - - `rocblas_operation_transpose` specifies that $A$ should be transposed ($A' = A^T$) before the matrix-vector product is performed. - - `rocblas_operation_conjugate_tranpose` specifies that $A$ should be conjugate transposed ($A' = A^H$) before the matrix-vector product is performed. In this and the previous case, $x$ needs to have $m$ elements, and $y$ needs to have $n$ elements. - + - `rocblas_operation_transpose` specifies that $A$ should be transposed ($op(A) = A^T$) before the matrix-vector product is performed. + - `rocblas_operation_conjugate_tranpose` specifies that $A$ should be conjugate transposed ($op(A) = A^H$) before the matrix-vector product is performed. In this and the previous case, $x$ needs to have $m$ elements, and $y$ needs to have $n$ elements. `X` is a placeholder for the data type of the operation and can be either `s` (float: `rocblas_float`) or `d` (double: `rocblas_double`). ## Demonstrated API Calls diff --git a/Libraries/rocBLAS/level_2/gemv/main.cpp b/Libraries/rocBLAS/level_2/gemv/main.cpp index ed9f27dc..fd33dee6 100644 --- a/Libraries/rocBLAS/level_2/gemv/main.cpp +++ b/Libraries/rocBLAS/level_2/gemv/main.cpp @@ -38,7 +38,7 @@ #include /// \brief Computes a general matrix-vector product: -/// y := alpha * A * x + beta * y +/// y := alpha * op(A) * x + beta * y /// where A is optionally transposed before the multiplication. /// The result is computed in-place, and stored in `y`. void gemv_reference(const rocblas_operation transpose_a, diff --git a/Libraries/rocBLAS/level_3/gemm/README.md b/Libraries/rocBLAS/level_3/gemm/README.md index 6430fcb9..2560522b 100644 --- a/Libraries/rocBLAS/level_3/gemm/README.md +++ b/Libraries/rocBLAS/level_3/gemm/README.md @@ -3,16 +3,16 @@ ## Description This example illustrates the use of the rocBLAS Level 3 General Matrix Multiplication. The rocBLAS GEMM performs a matrix--matrix operation as: -$C = \alpha \cdot A' \cdot B' + \beta \cdot C$, -where $X'$ is one of the following: +$C = \alpha \cdot op_a(A) \cdot op_b(B) + \beta \cdot C$, +where $op_m(M)$ is one of the following: -- $X' = X$ or -- $X' = X^T$ (transpose $X$: $X_{ij}^T = X_{ji}$) or -- $X' = X^H$ (Hermitian $X$: $X_{ij}^H = \bar{X_{ji}} $), +- $op_m(M) = M$ or +- $op_m(M) = M^T$ (transpose $M$: $M_{ij}^T = M_{ji}$) or +- $op_m(M) = M^H$ (Hermitian $M$: $M_{ij}^H = \bar{M_{ji}} $), In this example the identity is used. $\alpha and $\beta$ are scalars, and $A$, $B$ and $C$ are matrices, with -$A'$ an $m \times k$ matrix, $B'$ a $k \times n$ matrix and $C$ an $m \times n$ matrix. +$op_a(A)$ an $m \times k$ matrix, $op_b(B)$ a $k \times n$ matrix and $C$ an $m \times n$ matrix. ### Application flow diff --git a/Libraries/rocBLAS/level_3/gemm/main.cpp b/Libraries/rocBLAS/level_3/gemm/main.cpp index f4c9ad4c..7a81fbd2 100644 --- a/Libraries/rocBLAS/level_3/gemm/main.cpp +++ b/Libraries/rocBLAS/level_3/gemm/main.cpp @@ -73,7 +73,7 @@ int main(const int argc, const char** argv) const rocblas_float h_alpha = parser.get("a"); const rocblas_float h_beta = parser.get("b"); - // Set GEMM operation as identity operation: $X' = X$ + // Set GEMM operation as identity operation: $op(X) = X$ const rocblas_operation trans_a = rocblas_operation_none; const rocblas_operation trans_b = rocblas_operation_none; diff --git a/Libraries/rocBLAS/level_3/gemm_strided_batched/README.md b/Libraries/rocBLAS/level_3/gemm_strided_batched/README.md index 8556ae0a..0597a7bd 100644 --- a/Libraries/rocBLAS/level_3/gemm_strided_batched/README.md +++ b/Libraries/rocBLAS/level_3/gemm_strided_batched/README.md @@ -4,18 +4,17 @@ This example illustrates the use of the rocBLAS Level 3 Strided Batched General Matrix Multiplication. The rocBLAS GEMM STRIDED BATCHED performs a matrix--matrix operation for a _batch_ of matrices as: -$C[i] = \alpha \cdot A[i]' \cdot B[i]' + \beta \cdot (C[i])$ +$C[i] = \alpha \cdot op_a(A[i]) \cdot op_b(B[i]) + \beta \cdot (C[i])$ -for each $i \in [0, batch - 1]$, where $X[i] = X + i \cdot strideX$ is the $i$-th element of the correspondent batch and $X'$ is one of the following: - -- $X' = X$ or -- $X' = X^T$ (transpose $X$: $X_{ij}^T = X_{ji}$) or -- $X' = X^H$ (Hermitian $X$: $X_{ij}^H = \bar X_{ji} $). +for each $i \in [0, batch - 1]$, where $X[i] = X + i \cdot strideX$ is the $i$-th element of the correspondent batch and $op_m(M)$ is one of the following: +- $op_m(M) = M$ or +- $op_m(M) = M^T$ (transpose $M$: $M_{ij}^T = M_{ji}$) or +- $op_m(M) = M^H$ (Hermitian $M$: $M_{ij}^H = \bar M_{ji} $). In this example the identity is used. $\alpha$ and $\beta$ are scalars, and $A$, $B$ and $C$ are the batches of matrices. For each $i$, $A[i]$, $B[i]$ and $C[i]$ are matrices such that -$A_i'$ is an $m \times k$ matrix, $B_i'$ a $k \times n$ matrix and $C_i$ an $m \times n$ matrix. +$op_a(A[i])$ is an $m \times k$ matrix, $op_b(B[i])$ a $k \times n$ matrix and $C_i$ an $m \times n$ matrix. ### Application flow diff --git a/Libraries/rocBLAS/level_3/gemm_strided_batched/main.cpp b/Libraries/rocBLAS/level_3/gemm_strided_batched/main.cpp index 469875ed..d7db729a 100644 --- a/Libraries/rocBLAS/level_3/gemm_strided_batched/main.cpp +++ b/Libraries/rocBLAS/level_3/gemm_strided_batched/main.cpp @@ -84,7 +84,7 @@ int main(const int argc, const char** argv) const rocblas_float h_alpha = parser.get("a"); const rocblas_float h_beta = parser.get("b"); - // Set GEMM operation as identity operation: $X' = X$. + // Set GEMM operation as identity operation: $op(X) = X$. const rocblas_operation trans_a = rocblas_operation_none; const rocblas_operation trans_b = rocblas_operation_none; diff --git a/Libraries/rocSPARSE/level_2/bsrmv/README.md b/Libraries/rocSPARSE/level_2/bsrmv/README.md index 0088baa1..1d878c43 100644 --- a/Libraries/rocSPARSE/level_2/bsrmv/README.md +++ b/Libraries/rocSPARSE/level_2/bsrmv/README.md @@ -6,13 +6,13 @@ This example illustrates the use of the `rocSPARSE` level 2 sparse matrix-vector The operation calculates the following product: -$$\hat{\mathbf{y}} = \alpha \cdot A' \cdot \mathbf{x} + \beta \cdot \mathbf{y}$$ +$$\hat{\mathbf{y}} = \alpha \cdot op(A) \cdot \mathbf{x} + \beta \cdot \mathbf{y}$$ where - $\alpha$ and $\beta$ are scalars - $\mathbf{x}$ and $\mathbf{y}$ are dense vectors -- $A'$ is a sparse matrix in BSR format with `rocsparse_operation` and described below. +- $op(A)$ is a sparse matrix in BSR format, result of applying one of the `rocsparse_operation` described below in [Key APIs and Concepts - rocSPARSE](#rocsparse). ## Application flow @@ -158,16 +158,16 @@ bsr_col_ind = { 0, 0, 2, 0, 1 } ### rocSPARSE -- `rocsparse_[dscz]bsrmv(...)` performs the sparse matrix-dense vector multiplication $\hat{y}=\alpha \cdot A' x + \beta \cdot y$ using the BSR format. The correct function signature should be chosen based on the datatype of the input matrix: +- `rocsparse_[dscz]bsrmv(...)` performs the sparse matrix-dense vector multiplication $\hat{y}=\alpha \cdot op(A) x + \beta \cdot y$ using the BSR format. The correct function signature should be chosen based on the datatype of the input matrix: - `s` single-precision real (`float`) - `d` double-precision real (`double`) - `c` single-precision complex (`rocsparse_float_complex`) - `z` double-precision complex (`rocsparse_double_complex`) - `rocsparse_operation trans`: matrix operation type with the following options: - - `rocsparse_operation_none`: identity operation: $A' = A$ - - `rocsparse_operation_transpose`: transpose operation: $A' = A^\mathrm{T}$ - - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $A' = A^\mathrm{H}$ + - `rocsparse_operation_none`: identity operation: $op(M) = M$ + - `rocsparse_operation_transpose`: transpose operation: $op(M) = M^\mathrm{T}$ + - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $op(M) = M^\mathrm{H}$ Currently, only `rocsparse_operation_none` is supported. - `rocsparse_mat_descr`: descriptor of the sparse BSR matrix. diff --git a/Libraries/rocSPARSE/level_2/bsrmv/main.cpp b/Libraries/rocSPARSE/level_2/bsrmv/main.cpp index 2ecc9642..0444148b 100644 --- a/Libraries/rocSPARSE/level_2/bsrmv/main.cpp +++ b/Libraries/rocSPARSE/level_2/bsrmv/main.cpp @@ -39,7 +39,7 @@ int main() // 1. Set up input data // - // alpha * A * x + beta * y = y + // alpha * op(A) * x + beta * y = y // // alpha * ( 1.0 0.0 2.0 ) * ( 1.0 ) + beta * ( 4.0 ) = ( 31.1 ) // ( 3.0 0.0 4.0 ) * ( 2.0 ) ( 5.0 ) = ( 62.0 ) @@ -134,7 +134,7 @@ int main() HIP_CHECK(hipMemcpy(d_x, h_x.data(), x_size, hipMemcpyHostToDevice)); HIP_CHECK(hipMemcpy(d_y, h_y.data(), y_size, hipMemcpyHostToDevice)); - // 4. Call bsrmv to perform y = alpha * A x + beta * y + // 4. Call bsrmv to perform y = alpha * op(A) * x + beta * y // This function is non blocking and executed asynchronously with respect to the host. ROCSPARSE_CHECK(rocsparse_dbsrmv(handle, dir, diff --git a/Libraries/rocSPARSE/level_2/bsrsv/README.md b/Libraries/rocSPARSE/level_2/bsrsv/README.md index a69d9a9c..4d2754fe 100644 --- a/Libraries/rocSPARSE/level_2/bsrsv/README.md +++ b/Libraries/rocSPARSE/level_2/bsrsv/README.md @@ -7,16 +7,16 @@ This example illustrates the use of the `rocSPARSE` level 2 triangular solver us This triangular solver is used to solve a linear system of the form $$ -A'y = \alpha x, +op(A) \cdot y = \alpha \cdot x, $$ where - $A$ is a sparse triangular matrix of order $n$ whose elements are the coefficients of the equations, -- $A'$ is one of the following: - - $A' = A$ (identity) - - $A' = A^T$ (transpose $A$: $A_{ij}^T = A_{ji}$) - - $A' = A^H$ (conjugate transpose/Hermitian $A$: $A_{ij}^H = \bar A_{ji}$), +- $op(A)$ is one of the following: + - $op(A) = A$ (identity) + - $op(A) = A^T$ (transpose $A$: $A_{ij}^T = A_{ji}$) + - $op(A) = A^H$ (conjugate transpose/Hermitian $A$: $A_{ij}^H = \bar A_{ji}$), - $\alpha$ is a scalar, - $x$ is a dense vector of size $m$ containing the constant terms of the equations, and - $y$ is a dense vector of size $n$ which contains the unknowns of the system. @@ -30,7 +30,7 @@ Obtaining the solution for such a system consists of finding concrete values of 3. Initialize rocSPARSE by creating a handle. 4. Prepare utility variables for rocSPARSE bsrsv invocation. 5. Perform analysis step. -6. Perform triangular solve $Ay = \alpha x$. +6. Perform triangular solve $op(A) \cdot y = \alpha \cdot x$. 7. Check results obtained. If no zero-pivots, copy solution vector $y$ from device to host and compare with expected result. 8. Free rocSPARSE resources and device memory. 9. Print validation result. @@ -177,9 +177,9 @@ bsr_col_ind = { 0, 0, 2, 0, 1 } - `rocsparse_direction_column`: parse blocks by columns. - `rocsparse_operation trans`: matrix operation applied to the given input matrix. The following values are accepted: - - `rocsparse_operation_none`: identity operation $A' = A$. - - `rocsparse_operation_transpose`: transpose operation $A' = A^\mathrm{T}$. - - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $A' = A^\mathrm{H}$. This operation is not yet supported. + - `rocsparse_operation_none`: identity operation $op(M) = M$. + - `rocsparse_operation_transpose`: transpose operation $op(M) = M^\mathrm{T}$. + - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $op(M) = M^\mathrm{H}$. This operation is not yet supported. - `rocsparse_mat_descr descr`: holds all properties of a matrix. The properties set in this example are the following: - `rocsparse_diag_type`: indicates whether the diagonal entries of a matrix are unit elements (`rocsparse_diag_type_unit`) or not (`rocsparse_diag_type_non_unit`). @@ -189,7 +189,7 @@ bsr_col_ind = { 0, 0, 2, 0, 1 } - `rocsparse_solve_policy policy`: specifies the policy to follow for triangular solvers and factorizations. The only value accepted is `rocsparse_solve_policy_auto`. -- `rocsparse_[sdcz]bsrsv_solve` solves a sparse triangular linear system $A'y = \alpha x$. The correct function signature should be chosen based on the datatype of the input matrix: +- `rocsparse_[sdcz]bsrsv_solve` solves a sparse triangular linear system $op(A) \cdot y = \alpha \cdot x$. The correct function signature should be chosen based on the datatype of the input matrix: - `s` single-precision real (`float`) - `d` double-precision real (`double`) - `c` single-precision complex (`rocsparse_float_complex`) diff --git a/Libraries/rocSPARSE/level_2/bsrsv/main.cpp b/Libraries/rocSPARSE/level_2/bsrsv/main.cpp index 9b95e823..cb4c2dfc 100644 --- a/Libraries/rocSPARSE/level_2/bsrsv/main.cpp +++ b/Libraries/rocSPARSE/level_2/bsrsv/main.cpp @@ -191,7 +191,7 @@ int main() solve_policy, temp_buffer)); - // 6. Perform triangular solve Ay = alpha * x. + // 6. Perform triangular solve op(A) * y = alpha * x. ROCSPARSE_CHECK(rocsparse_dbsrsv_solve(handle, dir, trans, diff --git a/Libraries/rocSPARSE/level_2/bsrxmv/README.md b/Libraries/rocSPARSE/level_2/bsrxmv/README.md index dcb1fdca..9169ab4e 100644 --- a/Libraries/rocSPARSE/level_2/bsrxmv/README.md +++ b/Libraries/rocSPARSE/level_2/bsrxmv/README.md @@ -6,13 +6,13 @@ This example illustrates the use of the `rocSPARSE` level 2 sparse matrix-vector The function returns the BSR matrix-vector product for the masked blocks -$$\hat{\mathbf{y}} = \alpha \cdot A' \cdot \mathbf{x} + \beta \cdot \mathbf{y}$$ +$$\hat{\mathbf{y}} = \alpha \cdot op(A) \cdot \mathbf{x} + \beta \cdot \mathbf{y}$$ where - $\alpha$ and $\beta$ are scalars - $\mathbf{x}$ and $\mathbf{y}$ are dense vectors -- $A'$ is a sparse matrix in BSR format with `rocsparse_operation` and described below. +- $op(A)$ is a sparse matrix in BSR format, result of applying one of the `rocsparse_operation` described below in [Key APIs and Concepts - rocSPARSE](#rocsparse). - $\textbf{m}$ is the mask vector with elements 0 and 1. Value 1 represents the elements where the function returns with the product, and value 0 represents the identity values. - $\mathbf{\bar{m}} = \mathbf{1} - \mathbf{m}$ @@ -165,7 +165,7 @@ It is a common case that not all the elements are required from the result. Ther Mathematically it means we are looking for the following product: -$$\hat{\mathbf{y}} = \mathbf{m} \circ \left( \alpha \cdot A' \cdot \mathbf{x} \right) + \left( \mathbf{m} \cdot \beta + \mathbf{\bar{m}} \right) \circ \mathbf{y}$$ +$$\hat{\mathbf{y}} = \mathbf{m} \circ \left( \alpha \cdot op(A) \cdot \mathbf{x} \right) + \left( \mathbf{m} \cdot \beta + \mathbf{\bar{m}} \right) \circ \mathbf{y}$$ For instance the mask: @@ -211,9 +211,9 @@ Additionally, `bsrx_end_ptr` can be used for column masking, how it is presented - `z` double-precision complex (`rocsparse_double_complex`) - `rocsparse_operation trans`: matrix operation type with the following options: - - `rocsparse_operation_none`: identity operation: $A' = A$ - - `rocsparse_operation_transpose`: transpose operation: $A' = A^\mathrm{T}$ - - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $A' = A^\mathrm{H}$ + - `rocsparse_operation_none`: identity operation: $op(M) = M$ + - `rocsparse_operation_transpose`: transpose operation: $op(M) = M^\mathrm{T}$ + - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $op(M) = M^\mathrm{H}$ Currently, only `rocsparse_operation_none` is supported. diff --git a/Libraries/rocSPARSE/level_2/bsrxmv/main.cpp b/Libraries/rocSPARSE/level_2/bsrxmv/main.cpp index e1e62c3a..8adc71ad 100644 --- a/Libraries/rocSPARSE/level_2/bsrxmv/main.cpp +++ b/Libraries/rocSPARSE/level_2/bsrxmv/main.cpp @@ -35,7 +35,7 @@ int main() // // unmasked: // - // alpha * A * x + beta * y = y + // alpha * op(A) * x + beta * y = y // // 3.7 * ( 1.0 0.0 2.0 ) * ( 1.0 ) + 1.3 * ( 4.0 ) = ( 31.1 ) // ( 3.0 0.0 4.0 ) * ( 2.0 ) ( 5.0 ) = ( 62.0 ) diff --git a/Libraries/rocSPARSE/level_2/coomv/README.md b/Libraries/rocSPARSE/level_2/coomv/README.md index b3ea8fde..99992b89 100644 --- a/Libraries/rocSPARSE/level_2/coomv/README.md +++ b/Libraries/rocSPARSE/level_2/coomv/README.md @@ -6,13 +6,13 @@ This example illustrates the use of the `rocSPARSE` level 2 sparse matrix-vector The operation calculates the following product: -$$\hat{\mathbf{y}} = \alpha \cdot A' \cdot \mathbf{x} + \beta \cdot \mathbf{y}$$ +$$\hat{\mathbf{y}} = \alpha \cdot op(A) \cdot \mathbf{x} + \beta \cdot \mathbf{y}$$ where - $\alpha$ and $\beta$ are scalars - $\mathbf{x}$ and $\mathbf{y}$ are dense vectors -- $A'$ is a sparse matrix in COO format with `rocsparse_operation` and described below. +- $op(A)$ is a sparse matrix in COO format, result of applying one of the `rocsparse_operation` described below in [Key APIs and Concepts - rocSPARSE](#rocsparse). ## Application flow @@ -49,9 +49,9 @@ The COO matrix is sorted by row indices, and by column indices in the same row. - `z` double-precision complex (`rocsparse_double_complex`) - `rocsparse_operation`: matrix operation type with the following options: - - `rocsparse_operation_none`: identity operation: $A' = A$ - - `rocsparse_operation_transpose`: transpose operation: $A' = A^\mathrm{T}$ - - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $A' = A^\mathrm{H}$ + - `rocsparse_operation_none`: identity operation: $op(M) = M$ + - `rocsparse_operation_transpose`: transpose operation: $op(M) = M^\mathrm{T}$ + - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $op(M) = M^\mathrm{H}$ - `rocsparse_mat_descr`: holds all properties of a matrix. diff --git a/Libraries/rocSPARSE/level_2/coomv/main.cpp b/Libraries/rocSPARSE/level_2/coomv/main.cpp index 797cb8aa..684a5300 100644 --- a/Libraries/rocSPARSE/level_2/coomv/main.cpp +++ b/Libraries/rocSPARSE/level_2/coomv/main.cpp @@ -34,7 +34,7 @@ int main() { // 1. Set up input data // - // alpha * A * x + beta * y = y + // alpha * op(A) * x + beta * y = y // // 3.7 * ( 1.0 0.0 2.0 ) * ( 1.0 ) + 1.3 * ( 4.0 ) = ( 31.1 ) // ( 3.0 0.0 4.0 ) * ( 2.0 ) ( 5.0 ) = ( 62.0 ) @@ -106,7 +106,7 @@ int main() HIP_CHECK(hipMemcpy(d_x, h_x.data(), x_size, hipMemcpyHostToDevice)); HIP_CHECK(hipMemcpy(d_y, h_y.data(), y_size, hipMemcpyHostToDevice)); - // 4. Call coomv to perform y = alpha * A x + beta * y + // 4. Call coomv to perform y = alpha * op(A) * x + beta * y // This function is non blocking and executed asynchronously with respect to the host. ROCSPARSE_CHECK(rocsparse_dcoomv(handle, trans, diff --git a/Libraries/rocSPARSE/level_2/csritsv/README.md b/Libraries/rocSPARSE/level_2/csritsv/README.md index 97a2d012..0f206b49 100644 --- a/Libraries/rocSPARSE/level_2/csritsv/README.md +++ b/Libraries/rocSPARSE/level_2/csritsv/README.md @@ -7,16 +7,16 @@ This example illustrates the use of the `rocSPARSE` level 2 iterative triangular This triangular solver is used to find an iterative solution with Jacobi method for a linear system of the form $$ -A' y \approx \alpha x, +op(A) \cdot y \approx \alpha \cdot x, $$ with a `tolerance` and a `max_iter` maximal number of iterations where - $A$ is a sparse triangular matrix of order $n$ whose elements are the coefficients of the equations, -- $A'$ is one of the following: - - $A' = A$ (identity) - - $A' = A^T$ (transpose $A$: $A_{ij}^T = A_{ji}$) - - $A' = A^H$ (conjugate transpose/Hermitian $A$: $A_{ij}^H = \bar A_{ji}$), +- $op(A)$ is one of the following: + - $op(A) = A$ (identity) + - $op(A) = A^T$ (transpose $A$: $A_{ij}^T = A_{ji}$) + - $op(A) = A^H$ (conjugate transpose/Hermitian $A$: $A_{ij}^H = \bar A_{ji}$), - $\alpha$ is a scalar, - $x$ is a dense vector of size $n$ containing the constant terms of the equations, and - $y$ is a dense vector of size $n$ which contains the unknowns of the system. @@ -30,7 +30,7 @@ Obtaining solution for such a system consists on finding concrete values of all 3. Initialize rocSPARSE by creating a handle. 4. Prepare utility variables for rocSPARSE csritsv invocation. 5. Perform analysis step. -6. Perform triangular solve $A' y = \alpha x$. +6. Perform triangular solve $op(A) y = \alpha x$. 7. Check results obtained. 8. Copy solution vector $y$ from device to host and compare with expected result. 9. Free rocSPARSE resources and device memory. @@ -94,15 +94,15 @@ csr_col_ind = { 0, 1, 3, 1, 2, 0, 3, 4 } - rocSPARSE is initialized by calling `rocsparse_create_handle(rocsparse_handle*)` and is terminated by calling `rocsparse_destroy_handle(rocsparse_handle)`. - `rocsparse_pointer_mode` controls whether scalar parameters must be allocated on the host (`rocsparse_pointer_mode_host`) or on the device (`rocsparse_pointer_mode_device`). It is controlled by `rocsparse_set_pointer_mode`. - `rocsparse_operation trans`: matrix operation applied to the given input matrix. The following values are accepted: - - `rocsparse_operation_none`: identity operation $A' = A$. - - `rocsparse_operation_transpose`: transpose operation $A' = A^\mathrm{T}$. - - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $A' = A^\mathrm{H}$. This operation is not yet supported. + - `rocsparse_operation_none`: identity operation $op(M) = M$. + - `rocsparse_operation_transpose`: transpose operation $op(M) = M^\mathrm{T}$. + - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $op(M) = M^\mathrm{H}$. This operation is not yet supported. - `rocsparse_mat_descr descr`: holds all properties of a matrix. The properties set in this example are the following: - `rocsparse_diag_type`: indicates whether the diagonal entries of a matrix are unit elements (`rocsparse_diag_type_unit`) or not (`rocsparse_diag_type_non_unit`). - `rocsparse_fill_mode`: indicates whether a (triangular) matrix is lower (`rocsparse_fill_mode_lower`) or upper (`rocsparse_fill_mode_upper`) triangular. - `rocsparse_[sdcz]csritsv_buffer_size` allows to obtain the size (in bytes) of the temporary storage buffer required for the `rocsparse_[sdcz]csritsv_analysis` and `rocsparse_[sdcz]csritsv_solve` functions. The character matched in `[sdcz]` coincides with the one matched in any of the mentioned functions. - `rocsparse_solve_policy policy`: specifies the policy to follow for triangular solvers and factorizations. The only value accepted is `rocsparse_solve_policy_auto`. -- `rocsparse_[sdcz]csritsv_solve` solves a sparse triangular linear system $A' y = \alpha x$. The correct function signature should be chosen based on the datatype of the input matrix: +- `rocsparse_[sdcz]csritsv_solve` solves a sparse triangular linear system $op(A) \cdot y = \alpha \cdot x$. The correct function signature should be chosen based on the datatype of the input matrix: - `s` single-precision real (`float`) - `d` double-precision real (`double`) - `c` single-precision complex (`rocsparse_float_complex`) diff --git a/Libraries/rocSPARSE/level_2/csritsv/main.cpp b/Libraries/rocSPARSE/level_2/csritsv/main.cpp index 2b978cfd..850e80ad 100644 --- a/Libraries/rocSPARSE/level_2/csritsv/main.cpp +++ b/Libraries/rocSPARSE/level_2/csritsv/main.cpp @@ -35,7 +35,7 @@ int main() { // 1. Setup input data. - // alpha * A' * y = x + // alpha * op(A) * y = x // 1.0 * ( 1.0 0.0 0.0 0.0 ) * ( 1 ) = ( 1.0 ) // ( 2.0 3.0 0.0 0.0 ) * ( 0 ) ( 2.0 ) // ( 4.0 5.0 6.0 0.0 ) * ( -1/6 ) ( 3.0 ) @@ -161,7 +161,7 @@ int main() solve_policy, temp_buffer)); - // 6. Perform triangular solve A' y = alpha * x. + // 6. Perform triangular solve op(A) * y = alpha * x. // This function is non blocking and executed asynchronously with respect to the host. ROCSPARSE_CHECK(rocsparse_dcsritsv_solve(handle, &iter_counter, diff --git a/Libraries/rocSPARSE/level_2/csrmv/README.md b/Libraries/rocSPARSE/level_2/csrmv/README.md index a8f67a3f..28a5206e 100644 --- a/Libraries/rocSPARSE/level_2/csrmv/README.md +++ b/Libraries/rocSPARSE/level_2/csrmv/README.md @@ -6,13 +6,13 @@ This example illustrates the use of the `rocSPARSE` level 2 sparse matrix-vector The operation calculates the following product: -$$\hat{\mathbf{y}} = \alpha \cdot A' \cdot \mathbf{x} + \beta \cdot \mathbf{y}$$ +$$\hat{\mathbf{y}} = \alpha \cdot op(A) \cdot \mathbf{x} + \beta \cdot \mathbf{y}$$ where - $\alpha$ and $\beta$ are scalars - $\mathbf{x}$ and $\mathbf{y}$ are dense vectors -- $A'$ is a sparse matrix in CSR format with `rocsparse_operation`, which is described below in more detail. +- $op(A)$ is a sparse matrix in CSR format with `rocsparse_operation`, which is described below in [Key APIs and Concepts - rocSPARSE](#rocsparse) in more detail. ## Application flow @@ -87,9 +87,9 @@ csr_col_ind = { 0, 1, 3, 1, 2, 0, 3, 4 } - `z` double-precision complex (`rocsparse_double_complex`) - `rocsparse_operation`: matrix operation type with the following options: - - `rocsparse_operation_none`: identity operation: $A' = A$ - - `rocsparse_operation_transpose`: transpose operation: $A' = A^\mathrm{T}$ - - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $A' = A^\mathrm{H}$ + - `rocsparse_operation_none`: identity operation: $op(M) = M$ + - `rocsparse_operation_transpose`: transpose operation: $op(M) = M^\mathrm{T}$ + - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $op(M) = M^\mathrm{H}$ - `rocsparse_mat_descr`: holds all properties of a matrix. diff --git a/Libraries/rocSPARSE/level_2/csrmv/main.cpp b/Libraries/rocSPARSE/level_2/csrmv/main.cpp index 2964f9ef..9a6e0a7a 100644 --- a/Libraries/rocSPARSE/level_2/csrmv/main.cpp +++ b/Libraries/rocSPARSE/level_2/csrmv/main.cpp @@ -34,7 +34,7 @@ int main() { // 1. Set up input data // - // alpha * A * x + beta * y = y + // alpha * op(A) * x + beta * y = y // // 3.7 * ( 1.0 0.0 2.0 ) * ( 1.0 ) + 1.3 * ( 4.0 ) = ( 31.1 ) // ( 3.0 0.0 4.0 ) * ( 2.0 ) ( 5.0 ) = ( 62.0 ) @@ -110,7 +110,7 @@ int main() HIP_CHECK(hipMemcpy(d_x, h_x.data(), x_size, hipMemcpyHostToDevice)); HIP_CHECK(hipMemcpy(d_y, h_y.data(), y_size, hipMemcpyHostToDevice)); - // 4. Call csrmv to perform y = alpha * A x + beta * y + // 4. Call csrmv to perform y = alpha * op(A) * x + beta * y ROCSPARSE_CHECK(rocsparse_dcsrmv(handle, trans, m, diff --git a/Libraries/rocSPARSE/level_2/csrsv/README.md b/Libraries/rocSPARSE/level_2/csrsv/README.md index 8fd2b047..217d35cd 100644 --- a/Libraries/rocSPARSE/level_2/csrsv/README.md +++ b/Libraries/rocSPARSE/level_2/csrsv/README.md @@ -7,16 +7,16 @@ This example illustrates the use of the `rocSPARSE` level 2 triangular solver us This triangular solver is used to solve a linear system of the form $$ -A'y = \alpha x, +op(A) \cdot y = \alpha \cdot x, $$ where - $A$ is a sparse triangular matrix of order $n$ whose elements are the coefficients of the equations, -- $A'$ is one of the following: - - $A' = A$ (identity) - - $A' = A^T$ (transpose $A$: $A_{ij}^T = A_{ji}$) - - $A' = A^H$ (conjugate transpose/Hermitian $A$: $A_{ij}^H = \bar A_{ji}$), +- $op(A)$ is one of the following: + - $op(A) = A$ (identity) + - $op(A) = A^T$ (transpose $A$: $A_{ij}^T = A_{ji}$) + - $op(A) = A^H$ (conjugate transpose/Hermitian $A$: $A_{ij}^H = \bar A_{ji}$), - $\alpha$ is a scalar, - $x$ is a dense vector of size $m$ containing the constant terms of the equations, and - $y$ is a dense vector of size $n$ which contains the unknowns of the system. @@ -30,7 +30,7 @@ Obtaining solution for such a system consists on finding concrete values of all 3. Initialize rocSPARSE by creating a handle. 4. Prepare utility variables for rocSPARSE csrsv invocation. 5. Perform analysis step. -6. Perform triangular solve $Ay = \alpha x$. +6. Perform triangular solve $op(A) \cdot y = \alpha \cdot x$. 7. Check results obtained. If no zero-pivots, copy solution vector $y$ from device to host and compare with expected result. 8. Free rocSPARSE resources and device memory. 9. Print validation result. @@ -95,9 +95,9 @@ csr_col_ind = { 0, 1, 3, 1, 2, 0, 3, 4 } - `rocsparse_pointer_mode` controls whether scalar parameters must be allocated on the host (`rocsparse_pointer_mode_host`) or on the device (`rocsparse_pointer_mode_device`). It is controlled by `rocsparse_set_pointer_mode`. - `rocsparse_operation trans`: matrix operation applied to the given input matrix. The following values are accepted: - - `rocsparse_operation_none`: identity operation $A' = A$. - - `rocsparse_operation_transpose`: transpose operation $A' = A^\mathrm{T}$. - - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $A' = A^\mathrm{H}$. This operation is not yet supported for `rocsparse_[sdcz]_csrsv_solve`. + - `rocsparse_operation_none`: identity operation $op(M) = M$. + - `rocsparse_operation_transpose`: transpose operation $op(M) = M^\mathrm{T}$. + - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $op(M) = M^\mathrm{H}$. This operation is not yet supported for `rocsparse_[sdcz]_csrsv_solve`. - `rocsparse_mat_descr descr`: holds all properties of a matrix. The properties set in this example are the following: - `rocsparse_diag_type`: indicates whether the diagonal entries of a matrix are unit elements (`rocsparse_diag_type_unit`) or not (`rocsparse_diag_type_non_unit`). @@ -107,7 +107,7 @@ csr_col_ind = { 0, 1, 3, 1, 2, 0, 3, 4 } - `rocsparse_solve_policy policy`: specifies the policy to follow for triangular solvers and factorizations. The only value accepted is `rocsparse_solve_policy_auto`. -- `rocsparse_[sdcz]csrsv_solve` solves a sparse triangular linear system $A'y = \alpha x$. The correct function signature should be chosen based on the datatype of the input matrix: +- `rocsparse_[sdcz]csrsv_solve` solves a sparse triangular linear system $op(A) \cdot y = \alpha \cdot x$. The correct function signature should be chosen based on the datatype of the input matrix: - `s` single-precision real (`float`) - `d` double-precision real (`double`) - `c` single-precision complex (`rocsparse_float_complex`) diff --git a/Libraries/rocSPARSE/level_2/csrsv/main.cpp b/Libraries/rocSPARSE/level_2/csrsv/main.cpp index 43279005..2c353f7d 100644 --- a/Libraries/rocSPARSE/level_2/csrsv/main.cpp +++ b/Libraries/rocSPARSE/level_2/csrsv/main.cpp @@ -35,7 +35,7 @@ int main() { // 1. Setup input data. - // alpha * A' * y = x + // alpha * op(A) * y = x // 1.0 * ( 1.0 0.0 0.0 0.0 ) * ( 1 ) = ( 1.0 ) // ( 2.0 3.0 0.0 0.0 ) * ( 0 ) ( 2.0 ) // ( 4.0 5.0 6.0 0.0 ) * ( -1/6 ) ( 3.0 ) @@ -149,7 +149,7 @@ int main() solve_policy, temp_buffer)); - // 6. Perform triangular solve A' y = alpha * x. + // 6. Perform triangular solve op(A) * y = alpha * x. ROCSPARSE_CHECK(rocsparse_dcsrsv_solve(handle, trans, m, diff --git a/Libraries/rocSPARSE/level_2/ellmv/README.md b/Libraries/rocSPARSE/level_2/ellmv/README.md index bd786caa..9de32513 100644 --- a/Libraries/rocSPARSE/level_2/ellmv/README.md +++ b/Libraries/rocSPARSE/level_2/ellmv/README.md @@ -6,13 +6,13 @@ This example illustrates the use of the `rocSPARSE` level 2 sparse matrix-vector The operation calculates the following product: -$$\hat{\mathbf{y}} = \alpha \cdot A' \cdot \mathbf{x} + \beta \cdot \mathbf{y}$$ +$$\hat{\mathbf{y}} = \alpha \cdot op(A) \cdot \mathbf{x} + \beta \cdot \mathbf{y}$$ where - $\alpha$ and $\beta$ are scalars - $\mathbf{x}$ and $\mathbf{y}$ are dense vectors -- $A'$ is a sparse matrix in ELL format with `rocsparse_operation` and described below. +- $op(A)$ is a sparse matrix in ELL format, result of applying one of the `rocsparse_operation` described below in [Key APIs and Concepts - rocSPARSE](#rocsparse). ## Application flow @@ -80,9 +80,9 @@ ell_col_ind = { 0, 1, 0, - `z` double-precision complex (`rocsparse_double_complex`) - `rocsparse_operation`: matrix operation type with the following options: - - `rocsparse_operation_none`: identity operation: $A' = A$ - - `rocsparse_operation_transpose`: transpose operation: $A' = A^\mathrm{T}$ - - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $A' = A^\mathrm{H}$ + - `rocsparse_operation_none`: identity operation: $op(M) = M$ + - `rocsparse_operation_transpose`: transpose operation: $op(M) = M^\mathrm{T}$ + - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $op(M) = M^\mathrm{H}$ - `rocsparse_mat_descr`: holds all properties of a matrix. diff --git a/Libraries/rocSPARSE/level_2/ellmv/main.cpp b/Libraries/rocSPARSE/level_2/ellmv/main.cpp index 3ae6539f..57fbb02a 100644 --- a/Libraries/rocSPARSE/level_2/ellmv/main.cpp +++ b/Libraries/rocSPARSE/level_2/ellmv/main.cpp @@ -34,7 +34,7 @@ int main() { // 1. Set up input data // - // alpha * A * x + beta * y = y + // alpha * op(A) * x + beta * y = y // // 3.7 * ( 1.0 0.0 2.0 ) * ( 1.0 ) + 1.3 * ( 4.0 ) = ( 31.1 ) // ( 3.0 0.0 4.0 ) * ( 2.0 ) ( 5.0 ) = ( 62.0 ) @@ -101,8 +101,7 @@ int main() HIP_CHECK(hipMemcpy(d_x, h_x.data(), x_size, hipMemcpyHostToDevice)); HIP_CHECK(hipMemcpy(d_y, h_y.data(), y_size, hipMemcpyHostToDevice)); - // 4. Call ellmv to perform y = alpha * A x + beta * y - // This function is non blocking and executed asynchronously with respect to the host. + // 4. Call ellmv to perform y = alpha * op(A) * x + beta * y // This function is non blocking and executed asynchronously with respect to the host. ROCSPARSE_CHECK(rocsparse_dellmv(handle, trans, m, diff --git a/Libraries/rocSPARSE/level_2/gebsrmv/README.md b/Libraries/rocSPARSE/level_2/gebsrmv/README.md index 44b55535..ebdd289e 100644 --- a/Libraries/rocSPARSE/level_2/gebsrmv/README.md +++ b/Libraries/rocSPARSE/level_2/gebsrmv/README.md @@ -6,17 +6,17 @@ This example illustrates the use of the `rocSPARSE` level 2 sparse matrix-vector The operation calculates the following product: -$$\hat{y} = \alpha \cdot A' \cdot x + \beta \cdot y$$ +$$\hat{y} = \alpha \cdot op(A) \cdot x + \beta \cdot y$$ where - $\alpha$ and $\beta$ are scalars, - $x$ and $y$ are dense vectors, - $A$ is an $m\times n$ sparse matrix, and -- $A'$ is one of the following: - - $A' = A$ (identity) - - $A' = A^T$ (transpose $A$: $A_{ij}^T = A_{ji}$) - - $A' = A^H$ (conjugate transpose/Hermitian $A$: $A_{ij}^H = \bar A_{ji}$). +- $op(A)$ is one of the following: + - $op(A) = A$ (identity) + - $op(A) = A^T$ (transpose $A$: $A_{ij}^T = A_{ji}$) + - $op(A) = A^H$ (conjugate transpose/Hermitian $A$: $A_{ij}^H = \bar A_{ji}$). ## Application flow @@ -61,16 +61,16 @@ Note that, for a given $m\times n$ matrix, if $m$ is not evenly divisible by the - rocSPARSE is initialized by calling `rocsparse_create_handle(rocsparse_handle*)` and is terminated by calling `rocsparse_destroy_handle(rocsparse_handle)`. -- `rocsparse_[dscz]gebsrmv(...)` performs the sparse matrix-dense vector multiplication $\hat{y}=\alpha \cdot A' x + \beta \cdot y$ using the GEBSR format. The correct function signature should be chosen based on the datatype of the input matrix: +- `rocsparse_[dscz]gebsrmv(...)` performs the sparse matrix-dense vector multiplication $\hat{y}=\alpha \cdot op(A) x + \beta \cdot y$ using the GEBSR format. The correct function signature should be chosen based on the datatype of the input matrix: - `s` single-precision real (`float`) - `d` double-precision real (`double`) - `c` single-precision complex (`rocsparse_float_complex`) - `z` double-precision complex (`rocsparse_double_complex`) - `rocsparse_operation trans`: matrix operation type with the following options: - - `rocsparse_operation_none`: identity operation: $A' = A$ - - `rocsparse_operation_transpose`: transpose operation: $A' = A^\mathrm{T}$ - - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $A' = A^\mathrm{H}$ + - `rocsparse_operation_none`: identity operation: $op(M) = M$ + - `rocsparse_operation_transpose`: transpose operation: $op(M) = M^\mathrm{T}$ + - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $op(M) = M^\mathrm{H}$ Currently, only `rocsparse_operation_none` is supported for `rocsparse_[dscz]gebsrmv`. diff --git a/Libraries/rocSPARSE/level_2/gebsrmv/main.cpp b/Libraries/rocSPARSE/level_2/gebsrmv/main.cpp index 2ff7262b..1bdb353a 100644 --- a/Libraries/rocSPARSE/level_2/gebsrmv/main.cpp +++ b/Libraries/rocSPARSE/level_2/gebsrmv/main.cpp @@ -36,7 +36,7 @@ int main() { // 1. Setup input data. - // alpha * A * x + // alpha * op(A) * x // + beta * y = // = 1.0 * ( 4.0 0.0 0.0 0.0 ) * ( 1.0 ) - 1.0 * ( 4.0 ) // ( 4.0 3.0 0.0 0.0 ) ( 2.0 ) ( 5.0 ) @@ -80,13 +80,13 @@ int main() // clang-format off constexpr std::array h_bsr_val{4.0, 0.0, 0.0, - 4.0, 3.0, 0.0, // A_{00} + 4.0, 3.0, 0.0, // op(A)_{00} 4.0, 3.0, 2.0, - 4.0, 3.0, 2.0, // A_{10} + 4.0, 3.0, 2.0, // op(A)_{10} 0.0, 0.0, 0.0, - 1.0, 0.0, 0.0}; // A_{11} + 1.0, 0.0, 0.0}; // op(A)_{11} // clang-format on // GEBSR row pointers. @@ -145,7 +145,7 @@ int main() rocsparse_mat_descr descr; ROCSPARSE_CHECK(rocsparse_create_mat_descr(&descr)); - // 5. Call gebsrmv to perform y = alpha * A * x + beta * y. + // 5. Call gebsrmv to perform y = alpha * op(A) * x + beta * y. // This function is non blocking and executed asynchronously with respect to the host. ROCSPARSE_CHECK(rocsparse_dgebsrmv(handle, dir, diff --git a/Libraries/rocSPARSE/level_2/gemvi/README.md b/Libraries/rocSPARSE/level_2/gemvi/README.md index 784dfb0b..0ff9dbb3 100644 --- a/Libraries/rocSPARSE/level_2/gemvi/README.md +++ b/Libraries/rocSPARSE/level_2/gemvi/README.md @@ -4,7 +4,7 @@ This example showcases the usage of `rocsparse_gemvi` which multiplies a dense $m \times n$ matrix $A$ with a sparse vector $x$, scales this with $\alpha$, and adds the result to the dense the $\beta$-scaled vector $y$: -$y' = \alpha \cdot A \cdot x + \beta \cdot y$ +$y' = \alpha \cdot op(A) \cdot x + \beta \cdot y$ The example solves for $y'$ with the following concrete values: @@ -84,9 +84,9 @@ This works by storing the sparse vector $x$ as: - `z` double-precision complex (`rocsparse_double_complex`) - `rocsparse_operation trans`: matrix operation type with the following options: - - `rocsparse_operation_none`: identity operation: $A' = A$ - - `rocsparse_operation_transpose`: transpose operation: $A' = A^\mathrm{T}$ - - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $A' = A^\mathrm{H}$ + - `rocsparse_operation_none`: identity operation: $op(M) = M$ + - `rocsparse_operation_transpose`: transpose operation: $op(M) = M^\mathrm{T}$ + - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $op(M) = M^\mathrm{H}$ Currently, only `rocsparse_operation_none` is supported. diff --git a/Libraries/rocSPARSE/level_2/gemvi/main.cpp b/Libraries/rocSPARSE/level_2/gemvi/main.cpp index 6d7960ba..a82b7f86 100644 --- a/Libraries/rocSPARSE/level_2/gemvi/main.cpp +++ b/Libraries/rocSPARSE/level_2/gemvi/main.cpp @@ -44,7 +44,7 @@ int main() // - dense vector : y // - dense matrix : A // Calculate dense vector y' such that: - // y' = alpha * A * x + beta * y + // y' = alpha * op(A) * x + beta * y // Or more concretely with default alpha and beta: // ( 1.0 ) // (245.7) ( 9.0 10.0 11.0 12.0 13.0 ) ( 2.0 ) ( 4.0 ) @@ -119,7 +119,7 @@ int main() void* buffer; HIP_CHECK(hipMalloc(&buffer, buffer_size)); - // 4. Call dgemvi to perform y' = alpha * A * x + beta * y + // 4. Call dgemvi to perform y' = alpha * op(A) * x + beta * y ROCSPARSE_CHECK(rocsparse_dgemvi(handle, trans, A_rows, diff --git a/Libraries/rocSPARSE/level_2/spitsv/README.md b/Libraries/rocSPARSE/level_2/spitsv/README.md index cedbfde9..f8639d20 100644 --- a/Libraries/rocSPARSE/level_2/spitsv/README.md +++ b/Libraries/rocSPARSE/level_2/spitsv/README.md @@ -7,16 +7,16 @@ This example illustrates the use of the `rocSPARSE` level 2 iterative triangular This triangular solver is used to solve a linear system of the form $$ -A'y = \alpha x, +op(A) \cdot y = \alpha \cdot x, $$ where - $A$ is a sparse triangular matrix of order $n$ whose elements are the coefficients of the equations, -- $A'$ is one of the following: - - $A' = A$ (identity) - - $A' = A^T$ (transpose $A$: $A_{ij}^T = A_{ji}$) - - $A' = A^H$ (conjugate transpose/Hermitian $A$: $A_{ij}^H = \bar A_{ji}$), +- $op(A)$ is one of the following: + - $op(A) = A$ (identity) + - $op(A) = A^T$ (transpose $A$: $A_{ij}^T = A_{ji}$) + - $op(A) = A^H$ (conjugate transpose/Hermitian $A$: $A_{ij}^H = \bar A_{ji}$), - $\alpha$ is a scalar, - $x$ is a dense vector of size $n$ containing the constant terms of the equations, and - $y$ is a dense vector of size $n$ which contains the unknowns of the system. @@ -28,7 +28,7 @@ where 3. Initialize rocSPARSE by creating a handle. 4. Prepare device for rocSPARSE iterative SpSV invocation. 5. Perform analysis step. -6. Perform triangular solve $Ay = \alpha x$. +6. Perform triangular solve $op(A) \cdot y = \alpha \cdot x$. 7. Copy solution vector $y$ from device to host. 8. Free rocSPARSE resources and device memory. 9. Fetch convergence data. @@ -42,9 +42,9 @@ where - rocSPARSE is initialized by calling `rocsparse_create_handle(rocsparse_handle*)` and is terminated by calling `rocsparse_destroy_handle(rocsparse_handle)`. - `rocsparse_pointer_mode` controls whether scalar parameters must be allocated on the host (`rocsparse_pointer_mode_host`) or on the device (`rocsparse_pointer_mode_device`). It is controlled by `rocsparse_set_pointer_mode`. - `rocsparse_operation`: matrix operation applied to the given input matrix. The following values are accepted: - - `rocsparse_operation_none`: identity operation $A' = A$. - - `rocsparse_operation_transpose`: transpose operation $A' = A^\mathrm{T}$. - - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $A' = A^\mathrm{H}$. This operation is not yet supported. + - `rocsparse_operation_none`: identity operation $op(M) = M$. + - `rocsparse_operation_transpose`: transpose operation $op(M) = M^\mathrm{T}$. + - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $op(M) = M^\mathrm{H}$. This operation is not yet supported. - `rocsparse_spitsv()` performs a stage of the triangular linear system solver of a sparse matrix in CSR format, iteratively. diff --git a/Libraries/rocSPARSE/level_2/spitsv/main.cpp b/Libraries/rocSPARSE/level_2/spitsv/main.cpp index e0c3760f..f15853cf 100644 --- a/Libraries/rocSPARSE/level_2/spitsv/main.cpp +++ b/Libraries/rocSPARSE/level_2/spitsv/main.cpp @@ -32,7 +32,7 @@ int main() { // 1. Set up input data. - // A' * y = alpha * x + // op(A) * y = alpha * x // // ( 1.0 0.0 0.0 0.0 ) ( 1.0 ) ( 0.4 ) // ( 2.0 3.0 0.0 0.0 ) * ( 2.0 ) = 2.5 * ( 3.2 ) @@ -174,7 +174,7 @@ int main() nullptr, temp_buffer)); - // 6. Perform triangular solve Ay = alpha * x. + // 6. Perform triangular solve op(A) * y = alpha * x. // This function is non blocking and executed asynchronously with respect to the host. ROCSPARSE_CHECK(rocsparse_spitsv(handle, &iter_counter, diff --git a/Libraries/rocSPARSE/level_2/spmv/README.md b/Libraries/rocSPARSE/level_2/spmv/README.md index 2617d14c..f615cfc1 100644 --- a/Libraries/rocSPARSE/level_2/spmv/README.md +++ b/Libraries/rocSPARSE/level_2/spmv/README.md @@ -6,14 +6,14 @@ This example illustrates the use of the `rocSPARSE` level 2 sparse matrix-vector The operation calculates the following product: -$$\hat{\mathbf{y}} = \alpha \cdot A' \cdot \mathbf{x} + \beta \cdot \mathbf{y}$$ +$$\hat{\mathbf{y}} = \alpha \cdot op(A) \cdot \mathbf{x} + \beta \cdot \mathbf{y}$$ where - $\alpha$ and $\beta$ are scalars - $\mathbf{x}$ and $\mathbf{y}$ are dense vectors - $A$ is a sparse matrix -- $A'$ is the result of applying to matrix $A$ one of the `rocsparse_operation` described below. +- $op(A)$ is the result of applying to matrix $A$ one of the `rocsparse_operation` described below in [Key APIs and Concepts - rocSPARSE](#rocsparse). ### Application flow @@ -33,9 +33,9 @@ where - rocSPARSE is initialized by calling `rocsparse_create_handle(rocsparse_handle*)` and is terminated by calling `rocsparse_destroy_handle(rocsparse_handle)`. - `rocsparse_operation`: matrix operation applied to the given input matrix. The following values are accepted: - - `rocsparse_operation_none`: identity operation $A' = A$. - - `rocsparse_operation_transpose`: transpose operation $A' = A^\mathrm{T}$. - - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $A' = A^\mathrm{H}$. + - `rocsparse_operation_none`: identity operation $op(M) = M$. + - `rocsparse_operation_transpose`: transpose operation $op(M) = M^\mathrm{T}$. + - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $op(M) = M^\mathrm{H}$. - `rocsparse_spmv()` solves a sparse matrix-vector product in the following formats: BELL, BSR, COO, COO AoS, CSR, CSC and ELL. diff --git a/Libraries/rocSPARSE/level_2/spmv/main.cpp b/Libraries/rocSPARSE/level_2/spmv/main.cpp index a95c6cc9..6e81e585 100644 --- a/Libraries/rocSPARSE/level_2/spmv/main.cpp +++ b/Libraries/rocSPARSE/level_2/spmv/main.cpp @@ -39,7 +39,7 @@ int main() // 1. Set up input data // - // alpha * A * x + beta * y = y + // alpha * op(A) * x + beta * y = y // // 3.7 * ( 1.0 0.0 2.0 ) * ( 1.0 ) + 1.3 * ( 4.0 ) = ( 31.1 ) // ( 3.0 0.0 4.0 ) * ( 2.0 ) ( 5.0 ) = ( 62.0 ) diff --git a/Libraries/rocSPARSE/level_2/spsv/README.md b/Libraries/rocSPARSE/level_2/spsv/README.md index 674e748a..53c0bab8 100644 --- a/Libraries/rocSPARSE/level_2/spsv/README.md +++ b/Libraries/rocSPARSE/level_2/spsv/README.md @@ -7,16 +7,16 @@ This example illustrates the use of the `rocSPARSE` level 2 triangular solver wi This triangular solver is used to solve a linear system of the form $$ -A'y = \alpha x, +op(A) \cdot y = \alpha \cdot x, $$ where - $A$ is a sparse triangular matrix of order $n$ whose elements are the coefficients of the equations, -- $A'$ is one of the following: - - $A' = A$ (identity) - - $A' = A^T$ (transpose $A$: $A_{ij}^T = A_{ji}$) - - $A' = A^H$ (conjugate transpose/Hermitian $A$: $A_{ij}^H = \bar A_{ji}$), +- $op(A)$ is one of the following: + - $op(A) = A$ (identity) + - $op(A) = A^T$ (transpose $A$: $A_{ij}^T = A_{ji}$) + - $op(A) = A^H$ (conjugate transpose/Hermitian $A$: $A_{ij}^H = \bar A_{ji}$), - $\alpha$ is a scalar, - $x$ is a dense vector of size $n$ containing the constant terms of the equations, and - $y$ is a dense vector of size $n$ which contains the unknowns of the system. @@ -28,7 +28,7 @@ where 3. Initialize rocSPARSE by creating a handle. 4. Prepare device for rocSPARSE SpSV invocation. 5. Perform analysis step. -6. Perform triangular solve $Ay = \alpha x$. +6. Perform triangular solve $op(A) \cdot y = \alpha \cdot x$. 7. Copy solution vector $y$ from device to host. 8. Free rocSPARSE resources and device memory. 9. Print solution vector $y$ to the standard output. @@ -40,9 +40,9 @@ where - rocSPARSE is initialized by calling `rocsparse_create_handle(rocsparse_handle*)` and is terminated by calling `rocsparse_destroy_handle(rocsparse_handle)`. - `rocsparse_pointer_mode` controls whether scalar parameters must be allocated on the host (`rocsparse_pointer_mode_host`) or on the device (`rocsparse_pointer_mode_device`). It is controlled by `rocsparse_set_pointer_mode`. - `rocsparse_operation`: matrix operation applied to the given input matrix. The following values are accepted: - - `rocsparse_operation_none`: identity operation $A' = A$. - - `rocsparse_operation_transpose`: transpose operation $A' = A^\mathrm{T}$. - - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $A' = A^\mathrm{H}$. This operation is not yet supported. + - `rocsparse_operation_none`: identity operation $op(M) = M$. + - `rocsparse_operation_transpose`: transpose operation $op(M) = M^\mathrm{T}$. + - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $op(M) = M^\mathrm{H}$. This operation is not yet supported. - `rocsparse_spsv()` solves a sparse triangular linear system of a sparse matrix in CSR or COO format. diff --git a/Libraries/rocSPARSE/level_2/spsv/main.cpp b/Libraries/rocSPARSE/level_2/spsv/main.cpp index aa1adcb0..fa27192c 100644 --- a/Libraries/rocSPARSE/level_2/spsv/main.cpp +++ b/Libraries/rocSPARSE/level_2/spsv/main.cpp @@ -31,8 +31,8 @@ int main() { - // 1. Setup input data. - // A' * y = alpha * x + // 1. Set up input data. + // op(A) * y = alpha * x // // ( 1.0 0.0 0.0 0.0 ) ( 1.0 ) ( 0.4 ) // ( 2.0 3.0 0.0 0.0 ) * ( 2.0 ) = 2.5 * ( 3.2 ) @@ -156,7 +156,7 @@ int main() nullptr, temp_buffer)); - // 6. Perform triangular solve Ay = alpha * x. + // 6. Perform triangular solve op(A) * y = alpha * x. // This stage is non blocking and executed asynchronously with respect to the host. ROCSPARSE_CHECK(rocsparse_spsv(handle, trans, diff --git a/Libraries/rocSPARSE/level_3/bsrmm/README.md b/Libraries/rocSPARSE/level_3/bsrmm/README.md index 6062ff24..7406115b 100644 --- a/Libraries/rocSPARSE/level_3/bsrmm/README.md +++ b/Libraries/rocSPARSE/level_3/bsrmm/README.md @@ -6,14 +6,14 @@ This example illustrates the use of the `rocSPARSE` level 3 sparse matrix-matrix The operation calculates the following product: -$\hat{C} = \alpha \cdot A' \cdot B' + \beta \cdot C$ +$\hat{C} = \alpha \cdot op_a(A) \cdot op_b(B) + \beta \cdot C$ where - $\alpha$ and $\beta$ are scalars - $A$ is a sparse matrix in BSR format - $B$ and $C$ are dense matrices -- and $A'$ is the result of applying to matrix $A$ one of the `rocsparse_operation` described below. +- and $op_a(A)$ and $op_b(B)$ are the result of applying to matrices $A$ and $B$, respectively, one of the `rocsparse_operation` described below in [Key APIs and Concepts - rocSPARSE](#rocsparse). ## Application flow @@ -166,9 +166,9 @@ bsr_col_ind = { 0, 0, 2, 0, 1 } - `z` double-precision complex (`rocsparse_double_complex`) - `rocsparse_operation`: matrix operation type with the following options: - - `rocsparse_operation_none`: identity operation: $A' = A$ - - `rocsparse_operation_transpose`: transpose operation: $A' = A^\mathrm{T}$ - - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $A' = A^\mathrm{H}$ + - `rocsparse_operation_none`: identity operation: $op(M) = M$ + - `rocsparse_operation_transpose`: transpose operation: $op(M) = M^\mathrm{T}$ + - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $op(M) = M^\mathrm{H}$ Currently, only `rocsparse_operation_none` is supported. diff --git a/Libraries/rocSPARSE/level_3/bsrmm/main.cpp b/Libraries/rocSPARSE/level_3/bsrmm/main.cpp index 4b21d456..7cf42b1a 100644 --- a/Libraries/rocSPARSE/level_3/bsrmm/main.cpp +++ b/Libraries/rocSPARSE/level_3/bsrmm/main.cpp @@ -129,7 +129,7 @@ int main() HIP_CHECK(hipMemcpy(d_B, h_B.data(), size_B, hipMemcpyHostToDevice)); HIP_CHECK(hipMemcpy(d_C, h_C.data(), size_C, hipMemcpyHostToDevice)); - // 4. Call bsrmm to perform C = alpha * A' * B' + beta * C + // 4. Call bsrmm to perform C = alpha * op_a(A) * op_b(B) + beta * C // This function is non blocking and executed asynchronously with respect to the host. ROCSPARSE_CHECK(rocsparse_dbsrmm(handle, dir, diff --git a/Libraries/rocSPARSE/level_3/bsrsm/README.md b/Libraries/rocSPARSE/level_3/bsrsm/README.md index 91fb0fb6..d87a66f7 100644 --- a/Libraries/rocSPARSE/level_3/bsrsm/README.md +++ b/Libraries/rocSPARSE/level_3/bsrsm/README.md @@ -7,24 +7,24 @@ This example illustrates the use of the `rocSPARSE` level 3 triangular solver us This triangular solver is used to solve a linear system of the form $$ -A' X' = \alpha B'. +op_a(A) \cdot op_b(X) = \alpha \cdot op_b(B). $$ where - $A$ is a sparse triangular matrix of order $n$ whose elements are the coefficients of the equations, -- given a matrix $M$, $M'$ denotes one of the following: - - $M' = M$ (identity) - - $M' = M^T$ (transpose $M$: $M_{ij}^T = M_{ji}$) - - $M' = M^H$ (conjugate transpose/Hermitian $M$: $M_{ij}^H = \bar M_{ji}$), +- given a matrix $M$, $op_m(M)$ denotes one of the following: + - $op_m(B) = M$ (identity) + - $op_m(B) = M^T$ (transpose $M$: $M_{ij}^T = M_{ji}$) + - $op_m(B) = M^H$ (conjugate transpose/Hermitian $M$: $M_{ij}^H = \bar M_{ji}$), - $X$ is a dense matrix of size $n \times nrhs$ which contains the unknowns of the system, and - $\alpha$ is a scalar, - $B$ is a dense matrix of size $n \times nrhs$ containing the constant terms of the equations, -- the performed operation on $B$ and $X$ must be the same. +- the operation performed on $B$ and $X$, $op_b$, must be the same. Obtaining the solution for such a system consists of finding concrete values of all the unknowns such that the above equality holds. -This is the same as solving the classical system of linear equations $A' x_i = \alpha b_i$, where $x_i$ and $b_i$ are the $i$-th rows or columns of $X$ and $B$, depending on the operation performed on $X$ and $B$. This is showcased in [level 2 example bsrsv](../../level_2/bsrsv/README.md). +This is the same as solving the classical system of linear equations $op_a(A) x_i = \alpha b_i$, where $x_i$ and $b_i$ are the $i$-th rows or columns of $X$ and $B$, depending on the operation performed on $X$ and $B$. This is showcased in [level 2 example bsrsv](../../level_2/bsrsv/README.md). ### Application flow @@ -33,7 +33,7 @@ This is the same as solving the classical system of linear equations $A' x_i = \ 3. Initialize rocSPARSE by creating a handle. 4. Prepare utility variables for rocSPARSE bsrsm invocation. 5. Perform analysis step. -6. Call dbsrsm to solve $A' X' = \alpha B$ +6. Call dbsrsm to solve $op_a(A) op_b(X) = \alpha B$ 7. Check results. If no zero-pivots, copy solution matrix $X$ from device to host and compare with expected result. 8. Free rocSPARSE resources and device memory. 9. Print validation result. @@ -182,9 +182,9 @@ bsr_col_ind = { 0, 0, 2, 0, 1 } - `rocsparse_operation trans`: matrix operation applied to the given matrix. The following values are accepted: - - `rocsparse_operation_none`: identity operation $A' = A$. - - `rocsparse_operation_transpose`: transpose operation $A' = A^\mathrm{T}$. - - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $A' = A^\mathrm{H}$. This operation is not yet supported. + - `rocsparse_operation_none`: identity operation $op(M) = M$. + - `rocsparse_operation_transpose`: transpose operation $op(M) = M^\mathrm{T}$. + - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $op(M) = M^\mathrm{H}$. This operation is not yet supported. - `rocsparse_mat_descr descr`: holds all properties of a matrix. The properties set in this example are the following: diff --git a/Libraries/rocSPARSE/level_3/bsrsm/main.cpp b/Libraries/rocSPARSE/level_3/bsrsm/main.cpp index 4ac0d17b..9bb9d608 100644 --- a/Libraries/rocSPARSE/level_3/bsrsm/main.cpp +++ b/Libraries/rocSPARSE/level_3/bsrsm/main.cpp @@ -36,7 +36,7 @@ int main() { // 1. Set up input data. - // Solve A' * X' = alpha * B' for X', with triangular sparse matrix A, + // Solve op_a(A) * op_b(X) = alpha * op_b(B) for X, with triangular sparse matrix A, // and a dense matrix B containing several right-hand sides {b_1, ..., b_nrhs}. // // A * X = alpha * B @@ -214,7 +214,7 @@ int main() solve_policy, temp_buffer)); - // 6. Call dbsrsm to solve A * X = alpha * B. + // 6. Call dbsrsm to solve op_a(A) * op_b(X) = alpha * op_b(B). ROCSPARSE_CHECK(rocsparse_dbsrsm_solve(handle, dir, trans_A, diff --git a/Libraries/rocSPARSE/level_3/csrmm/README.md b/Libraries/rocSPARSE/level_3/csrmm/README.md index b520d9a1..3983665f 100644 --- a/Libraries/rocSPARSE/level_3/csrmm/README.md +++ b/Libraries/rocSPARSE/level_3/csrmm/README.md @@ -6,14 +6,14 @@ This example illustrates the use of the `rocSPARSE` level 3 sparse matrix-matrix The operation calculates the following product: -$\hat{C} = \alpha \cdot A' \cdot B' + \beta \cdot C$ +$\hat{C} = \alpha \cdot op_a(A) \cdot op_b(B) + \beta \cdot C$ where - $\alpha$ and $\beta$ are scalars - $A$ is a sparse matrix in CSR format - $B$ and $C$ are dense matrices -- and $A'$ is the result of applying to matrix $A$ one of the `rocsparse_operation` described below. +- and $op_a(A)$ and $op_b(B)$ are the result of applying to matrices $A$ and $B$, respectively, one of the `rocsparse_operation` described below in [Key APIs and Concepts - rocSPARSE](#rocsparse). ## Application flow @@ -88,9 +88,9 @@ csr_col_ind = { 0, 1, 3, 1, 2, 0, 3, 4 } - `z` double-precision complex (`rocsparse_double_complex`) - `rocsparse_operation`: matrix operation type with the following options: - - `rocsparse_operation_none`: identity operation: $A' = A$ - - `rocsparse_operation_transpose`: transpose operation: $A' = A^\mathrm{T}$ - - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $A' = A^\mathrm{H}$ + - `rocsparse_operation_none`: identity operation: $op(M) = M$ + - `rocsparse_operation_transpose`: transpose operation: $op(M) = M^\mathrm{T}$ + - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $op(M) = M^\mathrm{H}$ ## Demonstrated API Calls diff --git a/Libraries/rocSPARSE/level_3/csrmm/main.cpp b/Libraries/rocSPARSE/level_3/csrmm/main.cpp index 185bc772..8ece1b36 100644 --- a/Libraries/rocSPARSE/level_3/csrmm/main.cpp +++ b/Libraries/rocSPARSE/level_3/csrmm/main.cpp @@ -132,7 +132,7 @@ int main() HIP_CHECK(hipMemcpy(d_B, h_B.data(), size_B, hipMemcpyHostToDevice)); HIP_CHECK(hipMemcpy(d_C, h_C.data(), size_C, hipMemcpyHostToDevice)); - // 4. Call csrmm to perform C = alpha * A' * B' + beta * C + // 4. Call csrmm to perform C = alpha * op_a(A) * op_b(B) + beta * C // This function is non blocking and executed asynchronously with respect to the host. ROCSPARSE_CHECK(rocsparse_dcsrmm(handle, trans_A, diff --git a/Libraries/rocSPARSE/level_3/csrsm/README.md b/Libraries/rocSPARSE/level_3/csrsm/README.md index 29b03c6a..0ba41341 100644 --- a/Libraries/rocSPARSE/level_3/csrsm/README.md +++ b/Libraries/rocSPARSE/level_3/csrsm/README.md @@ -7,24 +7,24 @@ This example illustrates the use of the `rocSPARSE` level 3 triangular solver us This triangular solver is used to solve a linear system of the form $$ -A' X' = \alpha B'. +op_a(A) \cdot op_b(X) = \alpha \cdot op_b(B). $$ where - $A$ is a sparse triangular matrix of order $n$ whose elements are the coefficients of the equations, -- given a matrix $M$, $M'$ denotes one of the following: - - $M' = M$ (identity) - - $M' = M^T$ (transpose $M$: $M_{ij}^T = M_{ji}$) - - $M' = M^H$ (conjugate transpose/Hermitian $M$: $M_{ij}^H = \bar M_{ji}$), +- given a matrix $M$, $op_m(M)$ denotes one of the following: + - $op_m(M) = M$ (identity) + - $op_m(M) = M^T$ (transpose $M$: $M_{ij}^T = M_{ji}$) + - $op_m(M) = M^H$ (conjugate transpose/Hermitian $M$: $M_{ij}^H = \bar M_{ji}$), - $X$ is a dense matrix of size $n \times nrhs$ containing the unknowns of the systems, - $\alpha$ is a scalar, - $B$ is a dense matrix of size $n \times nrhs$ containing the right hand sides of the equations, -- the operation performed on $B$ and $X$ must be the same. +- the operation performed on $B$ and $X$, $op_b$, must be the same. Obtaining the solution for such a system consists of finding concrete values of all the unknowns such that the above equalities holds. -This is the same as solving the classical system of linear equations $A' x_i = \alpha b_i$ for each $i\in[0, nrhs-1]$, where $x_i$ and $b_i$ are the $i$-th rows or columns of $X$ and $B$, depending on the operation performed on $X$ and $B$. This is showcased in [level 2 example csrsv](../../level_2/csrsv/README.md). +This is the same as solving the classical system of linear equations $op_a(A) x_i = \alpha b_i$ for each $i\in[0, nrhs-1]$, where $x_i$ and $b_i$ are the $i$-th rows or columns of $X$ and $B$, depending on the operation performed on $X$ and $B$. This is showcased in [level 2 example csrsv](../../level_2/csrsv/README.md). ### Application flow @@ -100,9 +100,9 @@ csr_col_ind = { 0, 1, 3, 1, 2, 0, 3, 4 } - `rocsparse_operation trans`: matrix operation applied to the given matrix. The following values are accepted: - - `rocsparse_operation_none`: identity operation $M' = M$. - - `rocsparse_operation_transpose`: transpose operation $M' = M^\mathrm{T}$. - - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $M' = M^\mathrm{H}$. + - `rocsparse_operation_none`: identity operation $op(M) = M$. + - `rocsparse_operation_transpose`: transpose operation $op(M) = M^\mathrm{T}$. + - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $op(M) = M^\mathrm{H}$. Currently, only `rocsparse_operation_none` and `rocsparse_operation_transpose` are supported for both $A$ and $B$ matrices. diff --git a/Libraries/rocSPARSE/level_3/csrsm/main.cpp b/Libraries/rocSPARSE/level_3/csrsm/main.cpp index 4a4467a9..4f1caecc 100644 --- a/Libraries/rocSPARSE/level_3/csrsm/main.cpp +++ b/Libraries/rocSPARSE/level_3/csrsm/main.cpp @@ -36,7 +36,7 @@ int main() { // 1. Set up input data. - // Solve A' * X' = alpha * B', with triangular sparse matrix A, and a dense + // Solve op_a(A) * op_b(X) = alpha * op_b(B), with triangular sparse matrix A, and a dense // matrix B containing several right-hand sides (b_1, ..., b_nrhs) as columns. // // A * X = alpha * B diff --git a/Libraries/rocSPARSE/level_3/gebsrmm/README.md b/Libraries/rocSPARSE/level_3/gebsrmm/README.md index e90f3a9d..b836efb9 100644 --- a/Libraries/rocSPARSE/level_3/gebsrmm/README.md +++ b/Libraries/rocSPARSE/level_3/gebsrmm/README.md @@ -6,14 +6,14 @@ This example illustrates the use of the `rocSPARSE` level 3 sparse matrix-matrix The operation calculates the following product: -$\hat{C} = \alpha \cdot A' \cdot B' + \beta \cdot C$ +$\hat{C} = \alpha \cdot op_a(A) \cdot op_b(B) + \beta \cdot C$ where - $\alpha$ and $\beta$ are scalars - $A$ is a sparse matrix in GEBSR format - $B$ and $C$ are dense matrices -- and $A'$ is the result of applying to matrix $A$ one of the `rocsparse_operation` described below. +- and $op_a(A)$ and $op_b(B)$ are the result of applying to matrices $A$ and $B$, respectively, one of the `rocsparse_operation` described below in [Key APIs and Concepts - rocSPARSE](#rocsparse). ## Application flow @@ -63,9 +63,9 @@ Note that, for a given $m\times n$ matrix, if $m$ is not evenly divisible by the - `z` double-precision complex (`rocsparse_double_complex`) - `rocsparse_operation`: matrix operation type with the following options: - - `rocsparse_operation_none`: identity operation: $A' = A$ - - `rocsparse_operation_transpose`: transpose operation: $A' = A^\mathrm{T}$ - - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $A' = A^\mathrm{H}$ + - `rocsparse_operation_none`: identity operation: $op(M) = M$ + - `rocsparse_operation_transpose`: transpose operation: $op(M) = M^\mathrm{T}$ + - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $op(M) = A^\mathrm{H}$ Currently, only `rocsparse_operation_none` is supported. - `rocsparse_mat_descr`: descriptor of the sparse BSR matrix. diff --git a/Libraries/rocSPARSE/level_3/gebsrmm/main.cpp b/Libraries/rocSPARSE/level_3/gebsrmm/main.cpp index 6ae3e8ed..077a1026 100644 --- a/Libraries/rocSPARSE/level_3/gebsrmm/main.cpp +++ b/Libraries/rocSPARSE/level_3/gebsrmm/main.cpp @@ -151,7 +151,7 @@ int main() HIP_CHECK(hipMemcpy(d_B, h_B.data(), size_B, hipMemcpyHostToDevice)); HIP_CHECK(hipMemcpy(d_C, h_C.data(), size_C, hipMemcpyHostToDevice)); - // 4. Call gebsrmm to perform C = alpha * A' * B' + beta * C + // 4. Call gebsrmm to perform C = alpha * op_a(A) * op_b(B) + beta * C // This function is non blocking and executed asynchronously with respect to the host. ROCSPARSE_CHECK(rocsparse_dgebsrmm(handle, dir, diff --git a/Libraries/rocSPARSE/level_3/gemmi/README.md b/Libraries/rocSPARSE/level_3/gemmi/README.md index 40d6b5a5..1cbc7db5 100644 --- a/Libraries/rocSPARSE/level_3/gemmi/README.md +++ b/Libraries/rocSPARSE/level_3/gemmi/README.md @@ -7,16 +7,16 @@ This example illustrates the use of the `rocsparse_gemmi` function, which perfor That is, it does the following operation: $$ -C = \alpha \cdot A' \cdot B' + \beta \cdot C, +C = \alpha \cdot op_a(A) \cdot op_b(B) + \beta \cdot C, $$ where -- given a matrix $M$, $M'$ denotes one of the following: +- given a matrix $M$, $op_m(M)$ denotes one of the following: - - $M' = M$ (identity) - - $M' = M^T$ (transpose $M$: $M_{ij}^T = M_{ji}$) - - $M' = M^H$ (conjugate transpose/Hermitian $M$: $M_{ij}^H = \bar M_{ji}$), + - $op_m(M) = M$ (identity) + - $op_m(M) = M^T$ (transpose $M$: $M_{ij}^T = M_{ji}$) + - $op_m(M) = M^H$ (conjugate transpose/Hermitian $M$: $M_{ij}^H = \bar M_{ji}$), - $A$ is a dense matrix $m \times k$, - $B$ is a sparse matrix of size $k \times n$, @@ -92,12 +92,12 @@ csr_col_ind = { 0, 1, 3, 1, 2, 0, 3, 4 } - rocSPARSE is initialized by calling `rocsparse_create_handle(rocsparse_handle*)` and is terminated by calling `rocsparse_destroy_handle(rocsparse_handle)`. - `rocsparse_pointer_mode` controls whether scalar parameters must be allocated on the host (`rocsparse_pointer_mode_host`) or on the device (`rocsparse_pointer_mode_device`). It is controlled by `rocsparse_set_pointer_mode`. - `rocsparse_operation trans`: matrix operation applied to the given matrix. The following values are accepted: - - `rocsparse_operation_none`: identity operation $A' = A$. - - `rocsparse_operation_transpose`: transpose operation $A' = A^\mathrm{T}$. - - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $A' = A^\mathrm{H}$. + - `rocsparse_operation_none`: identity operation $op(M) = M$. + - `rocsparse_operation_transpose`: transpose operation $op(M) = M^\mathrm{T}$. + - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $op(M) = M^\mathrm{H}$. Currently, operation on $A$ must be `rocsparse_operation_none` and operation on $B$ must be `rocsparse_operation_transpose`. The other options are not yet supported. - `rocsparse_mat_descr descr`: holds all properties of a matrix. -- `rocsparse_[sdcz]gemmi` performs the operation $C = \alpha \cdot A' \cdot B' + \beta \cdot C$ for $C$. The correct function signature should be chosen based on the datatype of the input matrix: +- `rocsparse_[sdcz]gemmi` performs the operation $C = \alpha \cdot op_a(A) \cdot op_b(B) + \beta \cdot C$ for $C$. The correct function signature should be chosen based on the datatype of the input matrix: - `s` single-precision real (`float`) - `d` double-precision real (`double`) - `c` single-precision complex (`rocsparse_float_complex`) diff --git a/Libraries/rocSPARSE/level_3/gemmi/main.cpp b/Libraries/rocSPARSE/level_3/gemmi/main.cpp index 5da873c2..3365d56e 100644 --- a/Libraries/rocSPARSE/level_3/gemmi/main.cpp +++ b/Libraries/rocSPARSE/level_3/gemmi/main.cpp @@ -36,7 +36,7 @@ int main() { // 1. Set up input data. - // Solve C = alpha * A' * B' + beta * C, with an m x k dense matrix A, + // Solve C = alpha * op_a(A) * op_b(B) + beta * C, with an m x k dense matrix A, // a k x n sparse matrix B and alpha beta scalars. // Number of rows and columns of the input matrix. constexpr rocsparse_int m = 4; diff --git a/Libraries/rocSPARSE/level_3/sddmm/README.md b/Libraries/rocSPARSE/level_3/sddmm/README.md index c2c906e0..ecf264da 100644 --- a/Libraries/rocSPARSE/level_3/sddmm/README.md +++ b/Libraries/rocSPARSE/level_3/sddmm/README.md @@ -7,7 +7,7 @@ This example illustrates the use of the `rocSPARSE` sampled dense-dense matrix m The operation solves the following equation for C: -$ C := \alpha (\cdot A' * \cdot B') * sppat(\cdot C) + \beta C $ +$\C := \alpha(\cdot op_a(A) * \cdot op_b(B)) * sppat(\cdot C) + \beta C $ where @@ -15,7 +15,7 @@ where - $A$ and $B$ are dense matrices - $C$ is a sparse matrix in CSR format, the result will be in this matrix - $sppat(C)$ is the sparsity pattern of C matrix -- and $A'$ and $B'$ is the result of applying one of the `rocsparse_operation`s to the respective matrices. +- and $op_a(A)$ and $op_b(B)$ are the result of applying to matrices $A$ and $B$, respectively, one of the `rocsparse_operation` described below in [Key APIs and Concepts - rocSPARSE](#rocsparse). ## Application flow @@ -95,9 +95,9 @@ csr_col_ind = { 0, 1, 3, 1, 2, 0, 3, 4 } - The `rocsparse_spsm_stage_buffer_size` and `rocsparse_spsm_stage_compute` stages are asynchronous. It is the callers responsibility to assure that these stages are complete, before using their result. `rocsparse_spsm_stage_preprocess` will run in a blocking manner, no synchronization is necessary. - `rocsparse_operation`: matrix operation type with the following options: - - `rocsparse_operation_none`: identity operation: $A' = A$ - - `rocsparse_operation_transpose`: transpose operation: $A' = A^\mathrm{T}$ - - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $A' = A^\mathrm{H}$. This is currently not supported. + - `rocsparse_operation_none`: identity operation: $op(M) = M$ + - `rocsparse_operation_transpose`: transpose operation: $op(M) = M^\mathrm{T}$ + - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $op(M) = M^\mathrm{H}$. This is currently not supported. ## Demonstrated API Calls diff --git a/Libraries/rocSPARSE/level_3/spmm/README.md b/Libraries/rocSPARSE/level_3/spmm/README.md index 2b5361de..2aeb8680 100644 --- a/Libraries/rocSPARSE/level_3/spmm/README.md +++ b/Libraries/rocSPARSE/level_3/spmm/README.md @@ -6,14 +6,14 @@ This example illustrates the use of the `rocSPARSE` level 3 sparse matrix-dense The operation calculates the following product: -$\hat{C} = \alpha \cdot A' \cdot B' + \beta \cdot C$ +$\hat{C} = \alpha \cdot op_a(A) \cdot op_b(B) + \beta \cdot C$ where - $\alpha$ and $\beta$ are scalars - $A$ is a sparse matrix - $B$ and $C$ are dense matrices -- and $A'$ is the result of applying to matrix $A$ one of the `rocsparse_operation` described below. +- and $op_a(A)$ and $op_b(B)$ are the result of applying to matrices $A$ and $B$, respectively, one of the `rocsparse_operation` described below in [Key APIs and Concepts - rocSPARSE](#rocsparse). ## Application flow @@ -48,9 +48,9 @@ The following sparse matrix formats are supported: Blocked ELL, COO and CSR. - rocSPARSE is initialized by calling `rocsparse_create_handle(rocsparse_handle*)` and is terminated by calling `rocsparse_destroy_handle(rocsparse_handle)`. - `rocsparse_pointer_mode` controls whether scalar parameters must be allocated on the host (`rocsparse_pointer_mode_host`) or on the device (`rocsparse_pointer_mode_device`). It is controlled by `rocsparse_set_pointer_mode`. - `rocsparse_operation`: matrix operation applied to the given input matrix. The following values are accepted: - - `rocsparse_operation_none`: identity operation $A' = A$. - - `rocsparse_operation_transpose`: transpose operation $A' = A^\mathrm{T}$. - - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $A' = A^\mathrm{H}$. This operation is not yet supported. + - `rocsparse_operation_none`: identity operation $op(M) = M$. + - `rocsparse_operation_transpose`: transpose operation $op(M) = M^\mathrm{T}$. + - `rocsparse_operation_conjugate_transpose`: conjugate transpose operation (Hermitian matrix) $op(M) = M^\mathrm{H}$. This operation is not yet supported. - `rocsparse_datatype`: data type of rocSPARSE matrix elements. - `rocsparse_datatype_f32_r`: real 32-bit floating point type diff --git a/Libraries/rocSPARSE/level_3/spsm/README.md b/Libraries/rocSPARSE/level_3/spsm/README.md index cbeb769c..3720b3a2 100644 --- a/Libraries/rocSPARSE/level_3/spsm/README.md +++ b/Libraries/rocSPARSE/level_3/spsm/README.md @@ -4,18 +4,18 @@ This example illustrates the use of the `rocSPARSE` level 3 triangular solver with a chosen sparse format. -The operation solves the following equation for $X$: +The operation solves the following equation for $C$: -$A' \cdot X = \alpha \cdot B'$ +$op_a(A) \cdot C = \alpha \cdot op_b(B)$ where -- given a matrix $M$, $M'$ denotes one of the following: - - $M' = M$ (identity) - - $M' = M^T$ (transpose $M$: $M_{ij}^T = M_{ji}$) - - $M' = M^H$ (conjugate transpose/Hermitian $M$: $M_{ij}^H = \bar M_{ji}$), +- given a matrix $M$, $op_m(M)$ denotes one of the following: + - $op_m(M) = M$ (identity) + - $op_m(M) = M^T$ (transpose $M$: $M_{ij}^T = M_{ji}$) + - $op_m(M) = M^H$ (conjugate transpose/Hermitian $M$: $M_{ij}^H = \bar M_{ji}$), - $A$ is a sparse triangular matrix of order $m$ in CSR or COO format, -- $X$ is a dense matrix of size $m\times n$ containing the unknowns of the system, +- $C$ is a dense matrix of size $m\times n$ containing the unknowns of the system, - $B$ is a dense matrix of size $m\times n$ containing the right hand side of the equation, - $\alpha$ is a scalar @@ -97,9 +97,9 @@ csr_col_ind = { 0, 1, 3, 1, 2, 0, 3, 4 } - `rocsparse_spsm_alg_default`: default SpSM algorithm for the given format (the only available option) - `rocsparse_operation`: matrix operation type with the following options: - - `rocsparse_operation_none`: identity operation: $A' = A$ - - `rocsparse_operation_transpose`: transpose operation: $A' = A^\mathrm{T}$ - - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $A' = A^\mathrm{H}$. This is currently not supported. + - `rocsparse_operation_none`: identity operation: $op(M) = M$ + - `rocsparse_operation_transpose`: transpose operation: $op(M) = M^\mathrm{T}$ + - `rocsparse_operation_conjugate_transpose`: Hermitian operation: $op(M) = M^\mathrm{H}$. This is currently not supported. - `rocsparse_datatype`: data type of rocSPARSE vector and matrix elements. - `rocsparse_datatype_f32_r`: real 32-bit floating point type diff --git a/Libraries/rocSPARSE/level_3/spsm/main.cpp b/Libraries/rocSPARSE/level_3/spsm/main.cpp index 85dddf97..d645df98 100644 --- a/Libraries/rocSPARSE/level_3/spsm/main.cpp +++ b/Libraries/rocSPARSE/level_3/spsm/main.cpp @@ -145,7 +145,7 @@ int main() rocsparse_create_dnmat_descr(&mat_B_desc, m, n, m, d_B, data_type, order); rocsparse_create_dnmat_descr(&mat_X_desc, m, n, m, d_X, data_type, order); - // 5. Call spsm to solve A' * C = alpha * B' + // 5. Call spsm to solve op_a(A) * C = alpha * op_b(B) // Query the necessary temp buffer size size_t buffer_size; void* d_temp_buffer{};