7. mcSPARSE 1 级函数参考

本章描述了执行稠密向量和稀疏向量之间操作的稀疏线性代数函数。

7.1. mcsparse<t>axpyi()

usparseStatus_t
mcsparseSaxpyi(mcsparseHandle_t    handle,
               int                 nnz,
               const float*        alpha,
               const float*        xVal,
               const int*          xInd,
               float*              y,
               mcsparseIndexBase_t idxBase)

mcsparseStatus_t
mcsparseDaxpyi(mcsparseHandle_t    handle,
               int                 nnz,
               const double*       alpha,
               const double*       xVal,
               const int*          xInd,
               double*             y,
               mcsparseIndexBase_t idxBase)

mcsparseStatus_t
mcsparseCaxpyi(mcsparseHandle_t    handle,
               int                 nnz,
               const mcComplex*    alpha,
               const mcComplex*    xVal,
               const int*          xInd,
               mcComplex*          y,
               mcsparseIndexBase_t idxBase)

mcsparseStatus_t
mcsparseZaxpyi(mcsparseHandle_t       handle,
               int                    nnz,
               const mcDoubleComplex* alpha,
               const mcDoubleComplex* xVal,
               const int*             xInd,
               mcDoubleComplex*       y,
               mcsparseIndexBase_t    idxBase)

此函数将稀疏向量 x 乘以常数alpha，然后将结果添加到稠密向量 y 中。该操作可以写成以下形式：

for i=0 to nnz-1
      y[xInd[i]-idxBase] = y[xInd[i]-idxBase] + alpha*xVal[i]

该例程不需要额外的存储空间。

该例程支持异步执行。

输入

`handle`	处理mcSPARSE库上下文的句柄。
`nnz`	向量 `x` 的元素数量。
`alpha`	用于乘法运算的<type>标量。
`xVal`	包含向量 `x` `nnz` 个非零值的<type>向量。
`xInd`	包含向量 `x` `nnz` 个非零值的索引的整数向量。
`y`	以稠密格式表示的<type>向量。
`idxBase`	`MCSPARSE_INDEX_BASE_ZERO` 或 `MCSPARSE_INDEX_BASE_ONE`。

输出

`y`	以稠密格式表示的更新后的<type>向量(如果 `nnz == 0`，则保持不变)。

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

7.2. mcsparse<t>gthr()

mcsparseStatus_t
mcsparseSgthr(mcsparseHandle_t    handle,
               int                 nnz,
               const float*        y,
               float*              xVal,
               const int*          xInd,
               mcsparseIndexBase_t idxBase)

mcsparseStatus_t
mcsparseDgthr(mcsparseHandle_t    handle,
               int                 nnz,
               const double*       y,
               double*             xVal,
               const int*          xInd,
               mcsparseIndexBase_t idxBase)

mcsparseStatus_t
mcsparseCgthr(mcsparseHandle_t    handle,
               int                 nnz,
               const mcComplex*    y,
               mcComplex*          xVal,
               const int*          xInd,
               mcsparseIndexBase_t idxBase)

mcsparseStatus_t
mcsparseZgthr(mcsparseHandle_t        handle,
               int                     nnz,
               const mcDoubleComplex*  y,
               mcDoubleComplex*        xVal,
               const int*              xInd,
               mcsparseIndexBase_t     idxBase)

此函数将向量 y 在索引数组 xInd 中列出的元素存储到数据数组 xVal 中。

该例程不需要额外的存储空间。

该例程支持异步执行。

输入

`handle`	处理mcSPARSE库上下文的句柄。
`nnz`	向量 `x` 的元素数量。
`y`	以稠密格式表示的<type>向量 ( `size>=max(xInd)-idxBase+1`)。
`xInd`	包含向量 `x` `nnz` 个非零值的索引的整数向量。
`idxBase`	`MCSPARSE_INDEX_BASE_ZERO` 或 `MCSPARSE_INDEX_BASE_ONE`。

输出

xVal

<type>向量，包含向量 y 向其中存储的 nnz 个非零值 (如果 nnz == 0，则保持不变)。

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

7.3. mcsparse<t>gthrz()

mcsparseStatus_t
mcsparseSgthrz(mcsparseHandle_t    handle,
               int                 nnz,
               float*              y,
               float*              xVal,
               const int*          xInd,
               mcsparseIndexBase_t idxBase)

mcsparseStatus_t
mcsparseDgthrz(mcsparseHandle_t    handle,
               int                 nnz,
               double*             y,
               double*             xVal,
               const int*          xInd,
               mcsparseIndexBase_t idxBase)

mcsparseStatus_t
mcsparseCgthrz(mcsparseHandle_t    handle,
               int                 nnz,
               mcComplex*          y,
               mcComplex*          xVal,
               const int*          xInd,
               mcsparseIndexBase_t idxBase)

mcsparseStatus_t
mcsparseZgthrz(mcsparseHandle_t    handle,
               int                 nnz,
               mcDoubleComplex*    y,
               mcDoubleComplex*    xVal,
               const int*          xInd,
               mcsparseIndexBase_t idxBase)

此函数将向量 y 在索引数组 xInd 中列出的元素存储到数据数组 xVal 中。同时将向量 y 中已转存的元素清零。

该例程不需要额外的存储空间。

该例程支持异步执行。

输入

`handle`	处理mcSPARSE库上下文的句柄。
`nnz`	向量 `x` 的元素数量。
`y`	以稠密格式表示的<type>向量 ( `size>=max(xInd)-idxBase+1`)。
`xInd`	包含向量 `x` `nnz` 个非零值的索引的整数向量。
`idxBase`	`MCSPARSE_INDEX_BASE_ZERO` 或 `MCSPARSE_INDEX_BASE_ONE`。

输出

`xVal`	<type>向量，包含向量 `y` 向其中存储的 `nnz` 个非零值 (如果 `nnz == 0`，则保持不变)。
`y`	以稠密格式表示的<type>向量，其中由 `xInd` 索引的元素设为零(如果 `nnz == 0`，则保持不变)。

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

7.4. mcsparse<t>roti()

mcsparseStatus_t
mcsparseSroti(mcsparseHandle_t    handle,
               int                 nnz,
               float*              xVal,
               const int*          xInd,
               float*              y,
               const float*        c,
               const float*        s,
               mcsparseIndexBase_t idxBase)

mcsparseStatus_t
mcsparseDroti(mcsparseHandle_t    handle,
               int                 nnz,
               double*             xVal,
               const int*          xInd,
               double*             y,
               const double*       c,
               const double*       s,
               mcsparseIndexBase_t idxBase)

此函数应用了Givens旋转矩阵。

for i=0 to nnz-1
      y[xInd[i]-idxBase] = c * y[xInd[i]-idxBase] - s*xVal[i]
      x[i]               = c * xVal[i]            + s * y[xInd[i]-idxBase]

该例程不需要额外的存储空间。

该例程支持异步执行。

输入

`handle`	处理mcSPARSE库上下文的句柄。
`nnz`	向量 `x` 的元素数量。
`xVal`	包含向量 `x` `nnz` 个非零值的<type>向量。
`xInd`	包含向量 `x` `nnz` 个非零值的索引的整数向量。
`y`	以稠密格式表示的<type>向量。
`c`	旋转矩阵的余弦元素。
`s`	旋转矩阵的正弦元素。
`idxBase`	`MCSPARSE_INDEX_BASE_ZERO` 或 `MCSPARSE_INDEX_BASE_ONE`。

输出

`xVal`	以稀疏格式更新了向量<type> (如果 `nnz == 0` 则保持不变)。
`y`	以稠密格式表示的更新后的<type>向量(如果 `nnz == 0`，则保持不变)。

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

7.5. mcsparse<t>sctr()

mcsparseStatus_t
mcsparseSsctr(mcsparseHandle_t    handle,
               int                 nnz,
               const float*        xVal,
               const int*          xInd,
               float*              y,
               mcsparseIndexBase_t idxBase)

mcsparseStatus_t
mcsparseDsctr(mcsparseHandle_t    handle,
               int                 nnz,
               const double*       xVal,
               const int*          xInd,
               double*             y,
               mcsparseIndexBase_t idxBase)

mcsparseStatus_t
mcsparseCsctr(mcsparseHandle_t    handle,
               int                 nnz,
               const mcComplex*    xVal,
               const int*          xInd,
               mcComplex*          y,
               mcsparseIndexBase_t idxBase)

mcsparseStatus_t
mcsparseZsctr(mcsparseHandle_t       handle,
               int                    nnz,
               const mcDoubleComplex* xVal,
               const int*             xInd,
               mcDoubleComplex*       y,
               mcsparseIndexBase_t    idxBase)

此函数将稀疏向量 x 中的元素散布到稠密向量 y 中。此函数只修改了数组 xInd 中列出的索引对应的 y 中的元素。

该例程不需要额外的存储空间。

该例程支持异步执行。

输入

`handle`	处理mcSPARSE库上下文的句柄。
`nnz`	向量 `x` 的元素数量。
`xVal`	包含向量 `x` `nnz` 个非零值的<type>向量。
`xInd`	包含向量 `x` `nnz` 个非零值的索引的整数向量。
`y`	稠密向量<type>(并且 `size>=max(xInd)-idxBase+1`)。
`idxBase`	`MCSPARSE_INDEX_BASE_ZERO` 或 `MCSPARSE_INDEX_BASE_ONE`。

输出

`y`	由向量 `x` 中的 `nnz` 个非零值散布得到的新向量(如果 `nnz == 0`，则向量x保持不变)。

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。