ROCm · Beanavil · Jun 26, 2024 · May 8, 2024
@@ -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

@@ -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<float>("a");
     const float h_beta  = parser.get<float>("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;
 

@@ -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

@@ -38,7 +38,7 @@
 #include <vector>
 
 /// \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,

@@ -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
 

@@ -73,7 +73,7 @@ int main(const int argc, const char** argv)
     const rocblas_float h_alpha = parser.get<float>("a");
     const rocblas_float h_beta  = parser.get<float>("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;
 

@@ -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
 

@@ -84,7 +84,7 @@ int main(const int argc, const char** argv)
     const rocblas_float h_alpha = parser.get<float>("a");
     const rocblas_float h_beta  = parser.get<float>("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;
 

@@ -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.

@@ -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,

@@ -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`)

@@ -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,

@@ -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.
 

@@ -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 )