aoclsparse_?dotmv() - 5.2 English - 68552

AOCL API Guide (68552)

Document ID
68552
Release Date
2025-12-29
Version
5.2 English
aoclsparse_status aoclsparse_sdotmv(const aoclsparse_operation op, const float alpha, aoclsparse_matrix A, const aoclsparse_mat_descr descr, const float *x, const float beta, float *y, float *d)#
aoclsparse_status aoclsparse_ddotmv(const aoclsparse_operation op, const double alpha, aoclsparse_matrix A, const aoclsparse_mat_descr descr, const double *x, const double beta, double *y, double *d)#
aoclsparse_status aoclsparse_cdotmv(const aoclsparse_operation op, const aoclsparse_float_complex alpha, aoclsparse_matrix A, const aoclsparse_mat_descr descr, const aoclsparse_float_complex *x, const aoclsparse_float_complex beta, aoclsparse_float_complex *y, aoclsparse_float_complex *d)#
aoclsparse_status aoclsparse_zdotmv(const aoclsparse_operation op, const aoclsparse_double_complex alpha, aoclsparse_matrix A, const aoclsparse_mat_descr descr, const aoclsparse_double_complex *x, const aoclsparse_double_complex beta, aoclsparse_double_complex *y, aoclsparse_double_complex *d)#

Performs sparse matrix-vector multiplication followed by vector-vector multiplication.

aoclsparse_?dotmv multiplies the scalar \(\alpha\) with a sparse \(m \times n\) matrix, defined in a sparse storage format, and the dense vector \(x\) and adds the result to the dense vector \(y\) that is multiplied by the scalar \(\beta\), such that

\[\begin{split} y := \alpha \, op(A) \, x + \beta \, y, \quad \text{ with } \quad op(A) = \left\{ \begin{array}{ll} A, & \text{if } {\bf\mathsf{op}} = \text{aoclsparse}\_\text{operation}\_\text{none} \\ A^T, & \text{if } {\bf\mathsf{op}} = \text{aoclsparse}\_\text{operation}\_\text{transpose} \\ A^H, & \text{if } {\bf\mathsf{op}} = \text{aoclsparse}\_\text{operation}\_\text{conjugate}\_\text{transpose} \end{array} \right. \end{split}\]

followed by dot product of dense vectors \(x\) and \(y\) such that

\[\begin{split} {\bf\mathsf{d}} = \left\{ \begin{array}{ll} \sum_{i=0}^{\min(m,n)-1} x_{i} \; y_{i}, & \text{real case} \\ \sum_{i=0}^{\min(m,n)-1} \overline{x_i} \; y_{i}, & \text{complex case} \end{array} \right. \end{split}\]

 1/* ************************************************************************
 2 * Copyright (c) 2023-2024 Advanced Micro Devices, Inc.
 3 *
 4 * Permission is hereby granted, free of charge, to any person obtaining a copy
 5 * of this software and associated documentation files (the "Software"), to deal
 6 * in the Software without restriction, including without limitation the rights
 7 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 8 * copies of the Software, and to permit persons to whom the Software is
 9 * furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice shall be included in
12 * all copies or substantial portions of the Software.
13 *
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
20 * THE SOFTWARE.
21 *
22 * ************************************************************************ */
23
24#include "aoclsparse.h"
25
26#include <iostream>
27#include <limits>
28
29#define M 6
30#define N 5
31#define NNZ 8
32
33int main(void)
34{
35    aoclsparse_operation op = aoclsparse_operation_none;
36
37    double alpha = 1.0;
38    double beta  = 0.0;
39
40    // Print aoclsparse version
41    std::cout << aoclsparse_get_version() << std::endl;
42
43    // Create matrix descriptor
44    aoclsparse_mat_descr descr;
45    // aoclsparse_create_mat_descr set aoclsparse_matrix_type to aoclsparse_matrix_type_general
46    // and aoclsparse_index_base to aoclsparse_index_base_zero.
47    aoclsparse_create_mat_descr(&descr);
48
49    aoclsparse_index_base base = aoclsparse_index_base_zero;
50
51    // Initialise matrix
52    //  1  0  0  2  0
53    //  0  3  0  0  0
54    //  0  0  4  0  0
55    //  0  5  0  6  7
56    //  0  0  0  0  8
57    //  0  0  0  0  0
58    aoclsparse_int    csr_row_ptr[M + 1] = {0, 2, 3, 4, 7, 8, 8};
59    aoclsparse_int    csr_col_ind[NNZ]   = {0, 3, 1, 2, 1, 3, 4, 4};
60    double            csr_val[NNZ]       = {1, 2, 3, 4, 5, 6, 7, 8};
61    aoclsparse_matrix A;
62    aoclsparse_create_dcsr(&A, base, M, N, NNZ, csr_row_ptr, csr_col_ind, csr_val);
63
64    // Initialise vectors
65    double x[N]     = {1.0, 1.0, 1.0, 1.0, 1.0};
66    double y[M]     = {1.0, 1.0, 1.0, 1.0, 1.0, 1.0};
67    double d        = 0;
68    double y_exp[M] = {3.0, 3.0, 4.0, 18.0, 8.0};
69    double d_exp    = 36;
70
71    //to identify hint id(which routine is to be executed, destroyed later)
72    aoclsparse_set_dotmv_hint(A, op, descr, 1);
73
74    // Optimize the matrix, "A"
75    aoclsparse_optimize(A);
76
77    std::cout << "Invoking aoclsparse_ddotmv..";
78    //Invoke DOTMV API (double precision)
79    aoclsparse_ddotmv(op, alpha, A, descr, x, beta, y, &d);
80    std::cout << "Done." << std::endl;
81
82    // Print and check the result
83    std::cout << std::endl << "y = ";
84    bool   oki, ok = true;
85    double tol = 20 * std::numeric_limits<double>::epsilon();
86    for(aoclsparse_int i = 0; i < M; i++)
87    {
88        oki = std::abs(y[i] - y_exp[i]) <= tol;
89        std::cout << y[i] << (oki ? " " : "!  ");
90        ok &= oki;
91    }
92
93    ok &= (std::abs(d - d_exp) <= tol);
94    std::cout << std::endl << "Output dot product: " << d << (ok ? " " : "!  ") << std::endl;
95
96    aoclsparse_destroy_mat_descr(descr);
97    aoclsparse_destroy(&A);
98    return ok ? 0 : 4;
99}
Parameters:
  • op[in] matrix operation type.

  • alpha[in] scalar \(\alpha\).

  • A[in] the sparse \(m \times n\) matrix structure that is created using aoclsparse_create_scsr() or other variation.

  • descr[in] descriptor of the sparse CSR matrix. Both base-zero and base-one are supported, however, the index base needs to match the one used when aoclsparse_matrix was created.

  • x[in] array of atleast n elements if \(op(A) = A\) or at least m elements if \(op(A) = A^T\) or \(A^H\).

  • beta[in] scalar \(\beta\).

  • y[inout] array of atleast m elements if \(op(A) = A\) or at least n elements if \(op(A) = A^T\) or \(A^H\).

  • d[out] dot product of y and x.

Return values:
  • aoclsparse_status_success – the operation completed successfully.

  • aoclsparse_status_invalid_sizem, n or nnz is invalid.

  • aoclsparse_status_invalid_value – (base index is neither aoclsparse_index_base_zero nor aoclsparse_index_base_one, or matrix base index and descr base index values do not match.

  • aoclsparse_status_invalid_pointerdescr, internal structures related to the sparse matrix A, x, y or d are invalid pointer.

  • aoclsparse_status_wrong_type – matrix data type is not supported.

  • aoclsparse_status_not_implementedaoclsparse_matrix_type is aoclsparse_matrix_type_hermitian or, aoclsparse_matrix_format_type is not aoclsparse_csr_mat