Skip to content

Commit

Permalink
aocl-sparse API Guide added in docs folder
Browse files Browse the repository at this point in the history 
Doxygen generated API guide added in docs folder
Few comments modified for removing doxygen warnings

Change-Id: Ieccedeb4c569e33110dbec2979628056388db386
Signed-off-by: Chithra Sankar <[email protected]>
  • Loading branch information
@chsankar
chsankar committed Dec 4, 2020
1 parent 9503b5a commit 7eab271
Show file tree
Hide file tree
Showing 3 changed files with 17 additions and 196 deletions.
Binary file added docs/aocl-sparse API Guide.pdf
View file
Binary file not shown.
18 changes: 9 additions & 9 deletions library/include/aoclsparse_convert.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ extern "C" {
*/
__attribute__((__visibility__("default")))
aoclsparse_status aoclsparse_csr2ell_width(
aoclsparse_int M,
aoclsparse_int m,
aoclsparse_int nnz,
const aoclsparse_int *csr_row_ptr,
aoclsparse_int *ell_width);
Expand Down Expand Up @@ -101,7 +101,7 @@ aoclsparse_status aoclsparse_csr2ell_width(
/**@{*/
__attribute__((__visibility__("default")))
aoclsparse_status aoclsparse_scsr2ell(
aoclsparse_int M,
aoclsparse_int m,
const aoclsparse_int *csr_row_ptr,
const aoclsparse_int *csr_col_ind,
const float *csr_val,
Expand All @@ -111,7 +111,7 @@ aoclsparse_status aoclsparse_scsr2ell(

__attribute__((__visibility__("default")))
aoclsparse_status aoclsparse_dcsr2ell(
aoclsparse_int M,
aoclsparse_int m,
const aoclsparse_int *csr_row_ptr,
const aoclsparse_int *csr_col_ind,
const double *csr_val,
Expand Down Expand Up @@ -150,8 +150,8 @@ aoclsparse_status aoclsparse_dcsr2ell(
*/
__attribute__((__visibility__("default")))
aoclsparse_status aoclsparse_csr2dia_ndiag(
aoclsparse_int M,
aoclsparse_int N,
aoclsparse_int m,
aoclsparse_int n,
aoclsparse_int nnz,
const aoclsparse_int *csr_row_ptr,
const aoclsparse_int *csr_col_ind,
Expand Down Expand Up @@ -196,8 +196,8 @@ aoclsparse_status aoclsparse_csr2dia_ndiag(
/**@{*/
__attribute__((__visibility__("default")))
aoclsparse_status aoclsparse_scsr2dia(
aoclsparse_int M,
aoclsparse_int N,
aoclsparse_int m,
aoclsparse_int n,
const aoclsparse_int *csr_row_ptr,
const aoclsparse_int *csr_col_ind,
const float *csr_val,
Expand All @@ -207,8 +207,8 @@ aoclsparse_status aoclsparse_scsr2dia(

__attribute__((__visibility__("default")))
aoclsparse_status aoclsparse_dcsr2dia(
aoclsparse_int M,
aoclsparse_int N,
aoclsparse_int m,
aoclsparse_int n,
const aoclsparse_int *csr_row_ptr,
const aoclsparse_int *csr_col_ind,
const double *csr_val,
Expand Down
195 changes: 8 additions & 187 deletions library/include/aoclsparse_functions.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ extern "C" {
#endif

/*! \ingroup level2_module
* \brief Single precision sparse matrix vector multiplication using CSR storage format
* \brief Single & Double precision sparse matrix vector multiplication using CSR storage format
*
* \details
* \p aoclsparse_csrmv multiplies the scalar \f$\alpha\f$ with a sparse \f$m \times n\f$
Expand Down Expand Up @@ -69,6 +69,8 @@ extern "C" {
*
* \note
* Currently, only \p trans == \ref aoclsparse_operation_none is supported.
* Currently, for \ref aoclsparse_matrix_type == \ref aoclsparse_matrix_type_symmetric,
* only lower triangular matrices are supported.
*
* @param[in]
* trans matrix operation type.
Expand All @@ -88,8 +90,10 @@ extern "C" {
* @param[in]
* csr_row_ptr array of \p m+1 elements that point to the start
* of every row of the sparse CSR matrix.
* @param[in]
* descr descriptor of the sparse CSR matrix. Currently, only
* \ref aoclsparse_matrix_type_general is supported.
* \ref aoclsparse_matrix_type_general and
* \ref aoclsparse_matrix_type_symmetric is supported.
* @param[in]
* x array of \p n elements (\f$op(A) == A\f$) or \p m elements
* (\f$op(A) == A^T\f$ or \f$op(A) == A^H\f$).
Expand All @@ -107,6 +111,7 @@ extern "C" {
* \retval aoclsparse_status_not_implemented
* \p trans != \ref aoclsparse_operation_none or
* \ref aoclsparse_matrix_type != \ref aoclsparse_matrix_type_general.
* \ref aoclsparse_matrix_type != \ref aoclsparse_matrix_type_symmetric.
*
* \par Example
* This example performs a sparse matrix vector multiplication in CSR format
Expand Down Expand Up @@ -145,107 +150,7 @@ aoclsparse_status aoclsparse_scsrmv(aoclsparse_operation trans,
const float* x,
const float* beta,
float* y);
/**@}*/

/*! \ingroup level2_module
* \brief Double precision sparse matrix vector multiplication using CSR storage format
*
* \details
* \p aoclsparse_csrmv multiplies the scalar \f$\alpha\f$ with a sparse \f$m \times n\f$
* matrix, defined in CSR storage format, and the dense vector \f$x\f$ and adds the
* result to the dense vector \f$y\f$ that is multiplied by the scalar \f$\beta\f$,
* such that
* \f[
* y := \alpha \cdot op(A) \cdot x + \beta \cdot y,
* \f]
* with
* \f[
* op(A) = \left\{
* \begin{array}{ll}
* A, & \text{if trans == aoclsparse_operation_none} \\
* A^T, & \text{if trans == aoclsparse_operation_transpose} \\
* A^H, & \text{if trans == aoclsparse_operation_conjugate_transpose}
* \end{array}
* \right.
* \f]
*
* \code{.c}
* for(i = 0; i < m; ++i)
* {
* y[i] = beta * y[i];
*
* for(j = csr_row_ptr[i]; j < csr_row_ptr[i + 1]; ++j)
* {
* y[i] = y[i] + alpha * csr_val[j] * x[csr_col_ind[j]];
* }
* }
* \endcode
*
* \note
* Currently, only \p trans == \ref aoclsparse_operation_none is supported.
*
* @param[in]
* trans matrix operation type.
* @param[in]
* alpha scalar \f$\alpha\f$.
* @param[in]
* m number of rows of the sparse CSR matrix.
* @param[in]
* n number of columns of the sparse CSR matrix.
* @param[in]
* nnz number of non-zero entries of the sparse CSR matrix.
* @param[in]
* csr_val array of \p nnz elements of the sparse CSR matrix.
* @param[in]
* csr_col_ind array of \p nnz elements containing the column indices of the sparse
* CSR matrix.
* @param[in]
* csr_row_ptr array of \p m+1 elements that point to the start
* of every row of the sparse CSR matrix.
* descr descriptor of the sparse CSR matrix. Currently, only
* \ref aoclsparse_matrix_type_general is supported.
* @param[in]
* x array of \p n elements (\f$op(A) == A\f$) or \p m elements
* (\f$op(A) == A^T\f$ or \f$op(A) == A^H\f$).
* @param[in]
* beta scalar \f$\beta\f$.
* @param[inout]
* y array of \p m elements (\f$op(A) == A\f$) or \p n elements
* (\f$op(A) == A^T\f$ or \f$op(A) == A^H\f$).
*
* \retval aoclsparse_status_success the operation completed successfully.
* \retval aoclsparse_status_invalid_size \p m, \p n or \p nnz is invalid.
* \retval aoclsparse_status_invalid_pointer \p descr, \p alpha, \p csr_val,
* \p csr_row_ptr, \p csr_col_ind, \p x, \p beta or \p y pointer is
* invalid.
* \retval aoclsparse_status_not_implemented
* \p trans != \ref aoclsparse_operation_none or
* \ref aoclsparse_matrix_type != \ref aoclsparse_matrix_type_general.
*
* \par Example
* This example performs a sparse matrix vector multiplication in CSR format
* using additional meta data to improve performance.
* \code{.c}
* // Compute y = Ax
* aoclsparse_scsrmv(aoclsparse_operation_none,
* &alpha,
* m,
* n,
* nnz,
* csr_val,
* csr_col_ind,
* csr_row_ptr,
* descr,
* x,
* &beta,
* y);
*
* // Do more work
* // ...
*
* \endcode
*/
/**@{*/
__attribute__((__visibility__("default")))
aoclsparse_status aoclsparse_dcsrmv(aoclsparse_operation trans,
const double* alpha,
Expand All @@ -262,7 +167,7 @@ aoclsparse_status aoclsparse_dcsrmv(aoclsparse_operation trans,
/**@}*/

/*! \ingroup level2_module
* \brief Single precision sparse matrix vector multiplication using ELL storage format
* \brief Single & Double precision sparse matrix vector multiplication using ELL storage format
*
* \details
* \p aoclsparse_ellmv multiplies the scalar \f$\alpha\f$ with a sparse \f$m \times n\f$
Expand Down Expand Up @@ -355,89 +260,7 @@ aoclsparse_status aoclsparse_sellmv(aoclsparse_operation trans,
const float* x,
const float* beta,
float* y );
/**@}*/

/*! \ingroup level2_module
* \brief Double precision sparse matrix vector multiplication using ELL storage format
*
* \details
* \p aoclsparse_ellmv multiplies the scalar \f$\alpha\f$ with a sparse \f$m \times n\f$
* matrix, defined in ELL storage format, and the dense vector \f$x\f$ and adds the
* result to the dense vector \f$y\f$ that is multiplied by the scalar \f$\beta\f$,
* such that
* \f[
* y := \alpha \cdot op(A) \cdot x + \beta \cdot y,
* \f]
* with
* \f[
* op(A) = \left\{
* \begin{array}{ll}
* A, & \text{if trans == aoclsparse_operation_none} \\
* A^T, & \text{if trans == aoclsparse_operation_transpose} \\
* A^H, & \text{if trans == aoclsparse_operation_conjugate_transpose}
* \end{array}
* \right.
* \f]
*
* \code{.c}
* for(i = 0; i < m; ++i)
* {
* y[i] = beta * y[i];
*
* for(p = 0; p < ell_width; ++p)
* {
* idx = p * m + i;
*
* if((ell_col_ind[idx] >= 0) && (ell_col_ind[idx] < n))
* {
* y[i] = y[i] + alpha * ell_val[idx] * x[ell_col_ind[idx]];
* }
* }
* }
* \endcode
*
* \note
* Currently, only \p trans == \ref aoclsparse_operation_none is supported.
*
* @param[in]
* trans matrix operation type.
* @param[in]
* alpha scalar \f$\alpha\f$.
* @param[in]
* m number of rows of the sparse ELL matrix.
* @param[in]
* n number of columns of the sparse ELL matrix.
* @param[in]
* nnz number of non-zero entries of the sparse ELL matrix.
* @param[in]
* descr descriptor of the sparse ELL matrix. Currently, only
* \ref aoclsparse_matrix_type_general is supported.
* @param[in]
* ell_val array that contains the elements of the sparse ELL matrix. Padded
* elements should be zero.
* @param[in]
* ell_col_ind array that contains the column indices of the sparse ELL matrix.
* Padded column indices should be -1.
* @param[in]
* ell_width number of non-zero elements per row of the sparse ELL matrix.
* @param[in]
* x array of \p n elements (\f$op(A) == A\f$) or \p m elements
* (\f$op(A) == A^T\f$ or \f$op(A) == A^H\f$).
* @param[in]
* beta scalar \f$\beta\f$.
* @param[inout]
* y array of \p m elements (\f$op(A) == A\f$) or \p n elements
* (\f$op(A) == A^T\f$ or \f$op(A) == A^H\f$).
*
* \retval aoclsparse_status_success the operation completed successfully.
* \retval aoclsparse_status_invalid_size \p m, \p n or \p ell_width is invalid.
* \retval aoclsparse_status_invalid_pointer \p descr, \p alpha, \p ell_val,
* \p ell_col_ind, \p x, \p beta or \p y pointer is invalid.
* \retval aoclsparse_status_not_implemented
* \p trans != \ref aoclsparse_operation_none or
* \ref aoclsparse_matrix_type != \ref aoclsparse_matrix_type_general.
*/
/**@{*/
__attribute__((__visibility__("default")))
aoclsparse_status aoclsparse_dellmv(aoclsparse_operation trans,
const double* alpha,
Expand Down Expand Up @@ -580,8 +403,6 @@ aoclsparse_status aoclsparse_ddiamv(aoclsparse_operation trans,
* @param[in]
* nb number of block columns of the sparse BSR matrix.
* @param[in]
* nnzb number of non-zero blocks of the sparse BSR matrix.
* @param[in]
* alpha scalar \f$\alpha\f$.
* @param[in]
* descr descriptor of the sparse BSR matrix. Currently, only
Expand Down

0 comments on commit 7eab271

Please sign in to comment.