cuBLAS

cuBLAS，CUDA 基本线性代数子程序库的 API 参考指南。

1. 简介

cuBLAS 库是在 NVIDIA®CUDA™ 运行时之上实现的 BLAS（基本线性代数子程序）。它允许用户访问 NVIDIA 图形处理单元 (GPU) 的计算资源。

cuBLAS 库公开了四组 API

• cuBLAS API，在本文档中简称为 cuBLAS API（从 CUDA 6.0 开始），

• cuBLASXt API（从 CUDA 6.0 开始），以及

• cuBLASLt API（从 CUDA 10.1 开始）

• cuBLASDx API（未与 CUDA 工具包一起发布）

要使用 cuBLAS API，应用程序必须在 GPU 内存空间中分配所需的矩阵和向量，用数据填充它们，调用一系列所需的 cuBLAS 函数，然后将结果从 GPU 内存空间上传回主机。cuBLAS API 还提供了用于写入和检索 GPU 数据的辅助函数。

要使用 cuBLASXt API，应用程序可以将数据放在主机或参与计算的任何设备上，库将负责将操作调度到系统中的一个或多个 GPU，并根据用户请求将数据传输到这些 GPU。

cuBLASLt 是一个轻量级库，专门用于通用矩阵乘法 (GEMM) 操作，具有新的灵活 API。该库增加了矩阵数据布局、输入类型、计算类型以及通过参数可编程性选择算法实现和启发式的灵活性。在用户确定了预期 GEMM 操作的一组选项后，这些选项可以重复用于不同的输入。这类似于 cuFFT 和 FFTW 如何首先创建计划并将其重用于具有不同输入数据的相同大小和类型的 FFT。

1.1. 数据布局

为了与现有的 Fortran 环境最大程度地兼容，cuBLAS 库使用列优先存储和从 1 开始的索引。由于 C 和 C++ 使用行优先存储，因此以这些语言编写的应用程序不能对二维数组使用本机数组语义。相反，应定义宏或内联函数以在一维数组之上实现矩阵。对于以机械方式移植到 C 的 Fortran 代码，可以选择保留从 1 开始的索引，以避免转换循环的需要。在这种情况下，可以通过以下宏计算行“i”和列“j”中矩阵元素的数组索引

#define IDX2F(i,j,ld) ((((j)-1)*(ld))+((i)-1))

在这里，ld 指的是矩阵的前导维度，在列优先存储的情况下，它是已分配矩阵的行数（即使仅使用其子矩阵）。对于本机编写的 C 和 C++ 代码，最有可能选择从 0 开始的索引，在这种情况下，可以通过以下宏计算行“i”和列“j”中矩阵元素的数组索引

#define IDX2C(i,j,ld) (((j)*(ld))+(i))

1.2. 新的和旧的 cuBLAS API

从 4.0 版本开始，cuBLAS 库除了现有的旧版 API 外，还提供了一个新的 API。本节讨论了为什么提供新的 API、使用它的优势以及与现有旧版 API 的区别。

警告

旧版 cuBLAS API 已弃用，将在未来的版本中删除。

新的 cuBLAS 库 API 可以通过包含头文件 cublas_v2.h 来使用。它具有旧版 cuBLAS API 没有的以下功能

• cuBLAS 库上下文的 handle 使用该函数初始化，并显式传递给每个后续的库函数调用。当使用多个主机线程和多个 GPU 时，这允许用户更好地控制库设置。这也允许 cuBLAS API 是可重入的。

• 标量 \(\alpha\) 和 \(\beta\) 可以通过引用在主机或设备上传递，而不是仅允许通过值在主机上传递。此更改允许库函数即使在 \(\alpha\) 和 \(\beta\) 由先前的内核生成时，也可以使用流异步执行。

• 当库例程返回标量结果时，可以通过引用在主机或设备上返回，而不是仅允许通过值仅在主机上返回。当标量结果由设备上的引用生成和返回时，此更改允许异步调用库例程，从而实现最大的并行性。

• 错误状态 cublasStatus_t 由所有 cuBLAS 库函数调用返回。此更改有助于调试并简化软件开发。请注意，cublasStatus 已重命名为 cublasStatus_t，以便与 cuBLAS 库中的其他类型更加一致。

• cublasAlloc() 和 cublasFree() 函数已弃用。此更改删除了围绕 cudaMalloc() 和 cudaFree() 的这些不必要的包装器。

• 函数 cublasSetKernelStream() 已重命名为 cublasSetStream()，以便与其他 CUDA 库更加一致。

旧版 cuBLAS API 在使用旧版 cuBLAS API 中更详细地解释，可以通过包含头文件 cublas.h 来使用。由于旧版 API 与先前发布的 cuBLAS 库 API 相同，因此现有应用程序将开箱即用，并自动使用此旧版 API，而无需任何源代码更改。

当前和旧版 cuBLAS API 不能在单个翻译单元中同时使用：同时包含 cublas.h 和 cublas_v2.h 头文件将由于不兼容的符号重新声明而导致编译错误。

一般来说，新应用程序不应使用旧版 cuBLAS API，如果现有应用程序需要复杂且优化的流并行性，或者如果它从多个线程并发调用 cuBLAS 例程，则应转换为使用新的 API。

对于本文档的其余部分，新的 cuBLAS 库 API 将简称为 cuBLAS 库 API。

如前所述，旧版 API 和 cuBLAS 库 API 的接口分别是头文件 cublas.h 和 cublas_v2.h。此外，使用 cuBLAS 库的应用程序需要链接到

• Linux 的 DSO cublas.so，

• Windows 的 DLL cublas.dll，或

• Mac OS X 的动态库 cublas.dylib。

注意

相同的动态库实现新的和旧版 cuBLAS API。

1.3. 示例代码

有关示例代码参考，请参阅以下两个示例。它们展示了使用 cuBLAS 库 API 和两种索引样式用 C 编写的应用程序（示例 1.“使用 C 和 cuBLAS 的应用程序：从 1 开始的索引”和示例 2.“使用 C 和 cuBLAS 的应用程序：从 0 开始的索引”）。

//Example 1. Application Using C and cuBLAS: 1-based indexing
//-----------------------------------------------------------
#include <stdio.h>
#include <stdlib.h>
#include <math.h>
#include <cuda_runtime.h>
#include "cublas_v2.h"
#define M 6
#define N 5
#define IDX2F(i,j,ld) ((((j)-1)*(ld))+((i)-1))

static __inline__ void modify (cublasHandle_t handle, float *m, int ldm, int n, int p, int q, float alpha, float beta){
    cublasSscal (handle, n-q+1, &alpha, &m[IDX2F(p,q,ldm)], ldm);
    cublasSscal (handle, ldm-p+1, &beta, &m[IDX2F(p,q,ldm)], 1);
}

int main (void){
    cudaError_t cudaStat;
    cublasStatus_t stat;
    cublasHandle_t handle;
    int i, j;
    float* devPtrA;
    float* a = 0;
    a = (float *)malloc (M * N * sizeof (*a));
    if (!a) {
        printf ("host memory allocation failed");
        return EXIT_FAILURE;
    }
    for (j = 1; j <= N; j++) {
        for (i = 1; i <= M; i++) {
            a[IDX2F(i,j,M)] = (float)((i-1) * N + j);
        }
    }
    cudaStat = cudaMalloc ((void**)&devPtrA, M*N*sizeof(*a));
    if (cudaStat != cudaSuccess) {
        printf ("device memory allocation failed");
        free (a);
        return EXIT_FAILURE;
    }
    stat = cublasCreate(&handle);
    if (stat != CUBLAS_STATUS_SUCCESS) {
        printf ("CUBLAS initialization failed\n");
        free (a);
        cudaFree (devPtrA);
        return EXIT_FAILURE;
    }
    stat = cublasSetMatrix (M, N, sizeof(*a), a, M, devPtrA, M);
    if (stat != CUBLAS_STATUS_SUCCESS) {
        printf ("data download failed");
        free (a);
        cudaFree (devPtrA);
        cublasDestroy(handle);
        return EXIT_FAILURE;
    }
    modify (handle, devPtrA, M, N, 2, 3, 16.0f, 12.0f);
    stat = cublasGetMatrix (M, N, sizeof(*a), devPtrA, M, a, M);
    if (stat != CUBLAS_STATUS_SUCCESS) {
        printf ("data upload failed");
        free (a);
        cudaFree (devPtrA);
        cublasDestroy(handle);
        return EXIT_FAILURE;
    }
    cudaFree (devPtrA);
    cublasDestroy(handle);
    for (j = 1; j <= N; j++) {
        for (i = 1; i <= M; i++) {
            printf ("%7.0f", a[IDX2F(i,j,M)]);
        }
        printf ("\n");
    }
    free(a);
    return EXIT_SUCCESS;
}

---

//Example 2. Application Using C and cuBLAS: 0-based indexing
//-----------------------------------------------------------
#include <stdio.h>
#include <stdlib.h>
#include <math.h>
#include <cuda_runtime.h>
#include "cublas_v2.h"
#define M 6
#define N 5
#define IDX2C(i,j,ld) (((j)*(ld))+(i))

static __inline__ void modify (cublasHandle_t handle, float *m, int ldm, int n, int p, int q, float alpha, float beta){
    cublasSscal (handle, n-q, &alpha, &m[IDX2C(p,q,ldm)], ldm);
    cublasSscal (handle, ldm-p, &beta, &m[IDX2C(p,q,ldm)], 1);
}

int main (void){
    cudaError_t cudaStat;
    cublasStatus_t stat;
    cublasHandle_t handle;
    int i, j;
    float* devPtrA;
    float* a = 0;
    a = (float *)malloc (M * N * sizeof (*a));
    if (!a) {
        printf ("host memory allocation failed");
        return EXIT_FAILURE;
    }
    for (j = 0; j < N; j++) {
        for (i = 0; i < M; i++) {
            a[IDX2C(i,j,M)] = (float)(i * N + j + 1);
        }
    }
    cudaStat = cudaMalloc ((void**)&devPtrA, M*N*sizeof(*a));
    if (cudaStat != cudaSuccess) {
        printf ("device memory allocation failed");
        free (a);
        return EXIT_FAILURE;
    }
    stat = cublasCreate(&handle);
    if (stat != CUBLAS_STATUS_SUCCESS) {
        printf ("CUBLAS initialization failed\n");
        free (a);
        cudaFree (devPtrA);
        return EXIT_FAILURE;
    }
    stat = cublasSetMatrix (M, N, sizeof(*a), a, M, devPtrA, M);
    if (stat != CUBLAS_STATUS_SUCCESS) {
        printf ("data download failed");
        free (a);
        cudaFree (devPtrA);
        cublasDestroy(handle);
        return EXIT_FAILURE;
    }
    modify (handle, devPtrA, M, N, 1, 2, 16.0f, 12.0f);
    stat = cublasGetMatrix (M, N, sizeof(*a), devPtrA, M, a, M);
    if (stat != CUBLAS_STATUS_SUCCESS) {
        printf ("data upload failed");
        free (a);
        cudaFree (devPtrA);
        cublasDestroy(handle);
        return EXIT_FAILURE;
    }
    cudaFree (devPtrA);
    cublasDestroy(handle);
    for (j = 0; j < N; j++) {
        for (i = 0; i < M; i++) {
            printf ("%7.0f", a[IDX2C(i,j,M)]);
        }
        printf ("\n");
    }
    free(a);
    return EXIT_SUCCESS;
}

1.4. 向前兼容性

在大多数情况下，由于 PTX JIT，cuBLAS 库可以在未来的 GPU 上工作。但是，存在某些限制

• 没有性能保证：尽管理论峰值更高，但在新硬件上运行可能会更慢。

• 窄精度（FP4 和 FP8）和分块 8 位整数布局的向前兼容性有限。

2. 使用 cuBLAS API

2.1. 概述

本节介绍如何使用 cuBLAS 库 API。

2.1.1. 错误状态

所有 cuBLAS 库函数调用都返回错误状态 cublasStatus_t。

2.1.2. cuBLAS 上下文

应用程序必须通过调用 cublasCreate() 函数来初始化 cuBLAS 库上下文的句柄。然后，该句柄显式传递给每个后续的库函数调用。应用程序完成库使用后，必须调用函数 cublasDestroy() 以释放与 cuBLAS 库上下文关联的资源。

当使用多个主机线程和多个 GPU 时，此方法允许用户显式控制库设置。例如，应用程序可以使用 cudaSetDevice() 将不同的设备与不同的主机线程关联，并且在每个主机线程中，它可以初始化 cuBLAS 库上下文的唯一句柄，这将使用与该主机线程关联的特定设备。然后，使用不同句柄进行的 cuBLAS 库函数调用将自动将计算调度到不同的设备。

与特定 cuBLAS 上下文关联的设备假定在相应的 cublasCreate() 和 cublasDestroy() 调用之间保持不变。为了使 cuBLAS 库在同一主机线程中使用不同的设备，应用程序必须通过调用 cudaSetDevice() 设置要使用的新设备，然后创建另一个 cuBLAS 上下文，该上下文将通过调用 cublasCreate() 与新设备关联。当有多个设备可用时，应用程序必须确保与给定 cuBLAS 上下文关联的设备是当前的（例如，通过调用 cudaSetDevice()），然后再使用此上下文调用 cuBLAS 函数。

cuBLAS 库上下文与调用 cublasCreate() 时当前的 CUDA 上下文紧密耦合。使用多个 CUDA 上下文的应用程序需要为每个 CUDA 上下文创建一个 cuBLAS 上下文，并确保前者永远不会比后者寿命长。从 12.8 版本开始，cuBLAS 检测底层 CUDA 上下文是否与图形上下文绑定，并遵循在这种情况下设置的共享内存大小限制。

2.1.3. 线程安全性

该库是线程安全的，其函数可以从多个主机线程调用，即使使用相同的句柄也是如此。当多个线程共享同一个句柄时，在更改句柄配置时需要格外小心，因为该更改可能会影响所有线程中后续的 cuBLAS 调用。句柄的销毁更是如此。因此，不建议多个线程共享同一个 cuBLAS 句柄。

2.1.4. 结果可再现性

根据设计，当在具有相同架构和相同数量 SM 的 GPU 上执行时，给定工具包版本中的所有 cuBLAS API 例程在每次运行时都会生成相同的按位结果。但是，不能保证跨工具包版本的按位可再现性，因为由于某些实现更改，实现可能会有所不同。

当只有一个 CUDA 流处于活动状态时，此保证才成立。如果多个并发流处于活动状态，则库可能会通过选择不同的内部实现来优化总体性能。

注意

多流执行的不确定性行为是由于库在为并行流中运行的例程选择内部工作区时进行了优化。为了避免这种影响，用户可以

• 使用 cublasSetWorkspace() 函数为每个使用的流提供单独的工作区，或

• 每个流使用一个 cuBLAS 句柄，或

• 使用 cublasLtMatmul() 而不是 GEMM 系列函数，并提供用户拥有的工作区，或

• 将调试环境变量 CUBLAS_WORKSPACE_CONFIG 设置为 :16:8（可能会限制总体性能）或 :4096:8（将使 GPU 内存中的库占用空间增加约 24MiB）。

即使多个并发流共享单个 cuBLAS 句柄，这些设置中的任何一个都将允许确定性行为。

预计此行为将在未来的版本中更改。

对于某些例程，例如 cublas<t>symv() 和 cublas<t>hemv()，可以使用例程 cublasSetAtomicsMode() 选择备用的速度明显更快的例程。在这种情况下，不能保证结果是按位可再现的，因为原子用于计算。

2.1.5. 标量参数

有两类使用标量参数的函数

• 将 alpha 和/或 beta 参数作为比例因子通过引用在主机或设备上获取的函数，例如 gemm。

• 返回主机或设备上的标量结果的函数，例如 amax()、amin、asum()、rotg()、rotmg()、dot() 和 nrm2()。

对于第一类函数，当指针模式设置为 CUBLAS_POINTER_MODE_HOST 时，标量参数 alpha 和/或 beta 可以在堆栈上或堆上分配，不应放置在托管内存中。在底层，与这些函数相关的 CUDA 内核将使用 alpha 和/或 beta 的值启动。因此，即使内核启动是异步的，如果它们是在堆上分配的，也可以在调用返回后立即释放它们。当指针模式设置为 CUBLAS_POINTER_MODE_DEVICE 时，alpha 和/或 beta 必须在设备上可访问，并且在内核完成之前不应修改它们的值。请注意，由于 cudaFree() 执行隐式 cudaDeviceSynchronize()，因此 cudaFree() 仍然可以在调用后立即在 alpha 和/或 beta 上调用，但这将违背在这种情况下使用此指针模式的目的。

对于第二类函数，当指针模式设置为 CUBLAS_POINTER_MODE_HOST 时，这些函数会阻止 CPU，直到 GPU 完成其计算并将结果复制回主机。当指针模式设置为 CUBLAS_POINTER_MODE_DEVICE 时，这些函数会立即返回。在这种情况下，与矩阵和向量结果类似，标量结果仅在 GPU 上例程的执行完成后才准备就绪。这需要适当的同步，以便从主机读取结果。

在任何一种情况下，指针模式 CUBLAS_POINTER_MODE_DEVICE 都允许库函数完全异步地从主机执行，即使 alpha 和/或 beta 由先前的内核生成也是如此。例如，当使用 cuBLAS 库实现线性系统和特征值问题的迭代方法时，可能会出现这种情况。

2.1.6. 使用流的并行性

如果应用程序使用多个独立任务计算的结果，则可以使用 CUDA™ 流来重叠在这些任务中执行的计算。

应用程序可以在概念上将每个流与每个任务关联。为了实现任务之间计算的重叠，用户应使用函数 cudaStreamCreate() 创建 CUDA™ 流，并通过在调用实际 cuBLAS 例程之前调用 cublasSetStream() 将要由每个单独的 cuBLAS 库例程使用的流设置为该流。请注意，cublasSetStream() 会将用户提供的工作区重置为默认工作区池；请参阅 cublasSetWorkspace()。然后，在 GPU 上可能的情况下，在单独流中执行的计算将自动重叠。当单个任务执行的计算量相对较小且不足以用工作填充 GPU 时，此方法特别有用。

我们建议将新的 cuBLAS API 与通过引用在设备内存中传递的标量参数和结果一起使用，以便在使用流时实现计算的最大重叠。

流的一个特定应用，即多个小内核的批处理，将在下一节中介绍。

2.1.7. 批处理内核

在本节中，我们将解释如何使用流来批处理小内核的执行。例如，假设我们有一个应用程序，我们需要对稠密矩阵进行许多独立的小型矩阵-矩阵乘法。

很明显，即使有数百万个独立的小矩阵，我们也无法达到与一个大矩阵相同的GFLOPS速率。例如，单个 \(n \times n\) 大矩阵-矩阵乘法对 \(n^{2}\) 输入大小执行 \(n^{3}\) 次运算，而 1024 个 \(\frac{n}{32} \times \frac{n}{32}\) 小矩阵-矩阵乘法对相同的输入大小执行 \(1024\left( \frac{n}{32} \right)^{3} = \frac{n^{3}}{32}\) 次运算。然而，同样清楚的是，与单个小矩阵相比，我们可以使用许多独立的小矩阵实现明显更好的性能。

GPU 的架构系列允许我们同时执行多个内核。因此，为了批处理独立内核的执行，我们可以在单独的流中运行每个内核。特别是，在上面的示例中，我们可以使用函数 cudaStreamCreate() 创建 1024 个 CUDA™ 流，然后在每次调用 cublas<t>gemm() 之前调用 cublasSetStream()，每次矩阵-矩阵乘法使用不同的流（请注意，cublasSetStream() 会将用户提供的工作区重置为默认工作区池，请参阅 cublasSetWorkspace()）。这将确保在可能的情况下，不同的计算将并发执行。尽管用户可以创建许多流，但在实践中，同时执行的并发内核不超过 32 个。

2.1.8. 缓存配置

在某些设备上，L1 缓存和共享内存使用相同的硬件资源。可以使用 CUDA 运行时函数 cudaDeviceSetCacheConfig 直接设置缓存配置。也可以使用例程 cudaFuncSetCacheConfig 专门为某些函数设置缓存配置。有关缓存配置设置的详细信息，请参阅 CUDA 运行时 API 文档。

由于从一种配置切换到另一种配置可能会影响内核并发性，因此 cuBLAS 库不设置任何缓存配置首选项，而是依赖于当前设置。但是，某些 cuBLAS 例程，尤其是 Level-3 例程，严重依赖共享内存。因此，缓存首选项设置可能会对它们的性能产生不利影响。

2.1.9. 静态库支持

cuBLAS 库也以静态库 libcublas_static.a 的形式在 Linux 上发布。静态 cuBLAS 库和所有其他静态数学库都依赖于一个名为 libculibos.a 的通用线程抽象层库。

例如，在 Linux 上，要使用动态库编译一个使用 cuBLAS 的小型应用程序，可以使用以下命令

nvcc myCublasApp.c  -lcublas  -o myCublasApp

而要使用静态 cuBLAS 库进行编译，则必须使用以下命令

nvcc myCublasApp.c  -lcublas_static   -lculibos -o myCublasApp

也可以使用原生 Host C++ 编译器。根据 Host 操作系统，链接时可能需要一些额外的库，例如 pthread 或 dl。建议在 Linux 上使用以下命令

g++ myCublasApp.c  -lcublas_static   -lculibos -lcudart_static -lpthread -ldl -I <cuda-toolkit-path>/include -L <cuda-toolkit-path>/lib64 -o myCublasApp

请注意，在后一种情况下，不需要库 cuda。如果需要，CUDA 运行时将尝试显式打开 cuda 库。对于未安装 CUDA 驱动程序的系统，这允许应用程序优雅地处理此问题，并在 CPU 路径可用时可能运行。

从 11.2 版本开始，使用类型化函数而不是扩展函数 (cublas**Ex()) 有助于在链接到静态 cuBLAS 库时减小二进制文件大小。

2.1.10. GEMM 算法数值行为

一些 GEMM 算法沿维度 K 拆分计算，以增加 GPU 占用率，尤其是在维度 K 相对于维度 M 和 N 较大时。当 cuBLAS 启发式算法选择或用户显式选择此类算法时，每个拆分的结果会确定性地求和到结果矩阵中，以获得最终结果。

对于例程 cublas<t>gemmEx() 和 cublasGemmEx()，当计算类型大于输出类型时，拆分块的总和可能会导致一些中间溢出，从而产生一些溢出的最终结果矩阵。如果所有点积都在计算类型中累积，然后在最后转换为输出类型，则可能不会发生这些溢出。当 computeType 为 CUDA_R_32F 且 Atype、Btype 和 Ctype 为 CUDA_R_16F 时，这种计算副作用很容易暴露。可以使用计算精度模式 CUBLAS_MATH_DISALLOW_REDUCED_PRECISION_REDUCTION 和 cublasSetMathMode() 控制此行为

2.1.11. Tensor Core 使用

Tensor Core 首次在 Volta GPU（计算能力 7.0 及以上）中引入，并显着加速了矩阵乘法。从 cuBLAS 11.0.0 版本开始，除非通过在 cuBLAS 中选择 pedantic 计算模式显式禁用 Tensor Core 功能（请参阅 cublasSetMathMode(), cublasMath_t），否则库可能会自动使用 Tensor Core 功能。

应该注意的是，库将选择它认为可以提供最佳性能的启用 Tensor Core 的实现。

当矩阵维度和指针满足某些内存对齐要求时，可以实现使用 Tensor Core 的最佳性能。具体而言，必须满足以下所有条件才能充分发挥 Tensor Core 的性能

• ((op_A == CUBLAS_OP_N ? m : k) * AtypeSize) % 16 == 0

• ((op_B == CUBLAS_OP_N ? k : n) * BtypeSize) % 16 == 0

• (m * CtypeSize) % 16 == 0

• (lda * AtypeSize) % 16 == 0

• (ldb * BtypeSize) % 16 == 0

• (ldc * CtypeSize) % 16 == 0

• intptr_t(A) % 16 == 0

• intptr_t(B) % 16 == 0

• intptr_t(C) % 16 == 0

要使用 FP8 类型进行矩阵乘法（请参阅 8 位浮点数据类型 (FP8) 用法），您必须确保矩阵维度和指针满足上面列出的最佳要求。除了 FP8 之外，使用 Tensor Core 不再对矩阵维度和内存对齐有任何限制（从 cuBLAS 11.0.0 版本开始）。

2.1.12. CUDA Graphs 支持

在大多数情况下，cuBLAS 例程可以在 CUDA Graph 流捕获中捕获，而没有限制。

例外是将结果输出到主机缓冲区中的例程（例如，配置指针模式 CUBLAS_POINTER_MODE_HOST 时的 cublas<t>dot()），因为它强制同步。

对于输入系数（例如 alpha、beta），行为取决于指针模式设置

• 在 CUBLAS(LT)_POINTER_MODE_HOST 的情况下，系数的值在图中捕获。

• 在使用设备指针的指针模式下，在图执行时使用设备指针访问系数值。

注意

当在 CUDA Graph 流捕获中捕获时，cuBLAS 例程可以通过使用流排序分配 API cudaMallocAsync 和 cudaFreeAsync 创建 内存节点。但是，由于目前不支持 子图或从设备启动的图中的内存节点，因此尝试在此类场景中捕获 cuBLAS 例程可能会失败。为避免此问题，请使用 cublasSetWorkspace() 函数来提供用户拥有的工作区内存。

2.1.13. 64 位整数接口

cuBLAS 12 版本引入了支持 64 位整数的函数。每个 64 位整数函数都等效于具有以下更改的 32 位整数函数

• 函数名称带有 _64 后缀。

• 维度（问题大小）数据类型从 int 更改为 int64_t。维度示例：m、n 和 k。

• 前导维度数据类型从 int 更改为 int64_t。前导维度示例：lda、ldb 和 ldc。

• 向量增量数据类型从 int 更改为 int64_t。向量增量示例：incx 和 incy。

例如，考虑以下 32 位整数函数

cublasStatus_t cublasSetMatrix(int rows, int cols, int elemSize, const void *A, int lda, void *B, int ldb);
cublasStatus_t cublasIsamax(cublasHandle_t handle, int n, const float *x, int incx, int *result);
cublasStatus_t cublasSsyr(cublasHandle_t handle, cublasFillMode_t uplo, int n, const float *alpha, const float *x, int incx, float *A, int lda);

等效的 64 位整数函数是

cublasStatus_t cublasSetMatrix_64(int64_t rows, int64_t cols, int64_t elemSize, const void *A, int64_t lda, void *B, int64_t ldb);
cublasStatus_t cublasIsamax_64(cublasHandle_t handle, int64_t n, const float *x, int64_t incx, int64_t *result);
cublasStatus_t cublasSsyr_64(cublasHandle_t handle, cublasFillMode_t uplo, int64_t n, const float *alpha, const float *x, int64_t incx, float *A, int64_t lda);

并非每个函数都有 64 位整数等效项。例如，cublasSetMathMode() 没有可以有意义地成为 int64_t 的任何参数。为了文档简洁起见，未显式列出 64 位整数 API，而仅提及它们存在于相关函数中。

2.2. cuBLAS 数据类型参考

2.2.1. cublasHandle_t

cublasHandle_t 类型是指向不透明结构的指针类型，该结构保存 cuBLAS 库上下文。cuBLAS 库上下文必须使用 cublasCreate() 初始化，并且返回的句柄必须传递给所有后续库函数调用。上下文应在使用 cublasDestroy() 结束时销毁。

2.2.2. cublasStatus_t

该类型用于函数状态返回。所有 cuBLAS 库函数都返回其状态，该状态可以具有以下值。

值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成。
CUBLAS_STATUS_NOT_INITIALIZED	cuBLAS 库未初始化。这通常是由缺少之前的 cublasCreate() 调用、cuBLAS 例程调用的 CUDA 运行时 API 中的错误或硬件设置中的错误引起的。 纠正方法：在函数调用之前调用 cublasCreate()；并检查硬件、驱动程序的适当版本和 cuBLAS 库是否已正确安装。
CUBLAS_STATUS_ALLOC_FAILED	cuBLAS 库内部的资源分配失败。这通常是由 cudaMalloc() 失败引起的。 纠正方法：在函数调用之前，尽可能多地释放先前分配的内存。
CUBLAS_STATUS_INVALID_VALUE	将不支持的值或参数传递给函数（例如，负向量大小）。 纠正方法：确保传递的所有参数都具有有效值。
CUBLAS_STATUS_ARCH_MISMATCH	该函数需要设备架构中缺少的功能；通常是由计算能力低于 5.0 引起的。 纠正方法：在具有适当计算能力的设备上编译并运行应用程序。
CUBLAS_STATUS_MAPPING_ERROR	访问 GPU 内存空间失败，这通常是由纹理绑定失败引起的。 纠正方法：在函数调用之前，取消绑定任何先前绑定的纹理。
CUBLAS_STATUS_EXECUTION_FAILED	GPU 程序执行失败。这通常是由 GPU 上内核的启动失败引起的，这可能是由多种原因引起的。 纠正方法：检查硬件、驱动程序的适当版本和 cuBLAS 库是否已正确安装。
CUBLAS_STATUS_INTERNAL_ERROR	内部 cuBLAS 操作失败。此错误通常是由 cudaMemcpyAsync() 失败引起的。 纠正方法：检查硬件、驱动程序的适当版本和 cuBLAS 库是否已正确安装。此外，检查作为参数传递给例程的内存是否在例程完成之前被释放。
CUBLAS_STATUS_NOT_SUPPORTED	请求的功能不受支持。
CUBLAS_STATUS_LICENSE_ERROR	请求的功能需要某些许可证，并且在尝试检查当前许可时检测到错误。如果许可证不存在或已过期，或者如果未正确设置环境变量 NVIDIA_LICENSE_FILE，则可能会发生此错误。

2.2.3. cublasOperation_t

cublasOperation_t 类型指示需要对密集矩阵执行哪个操作。其值对应于 Fortran 字符 ‘N’ 或 ‘n’（非转置）、‘T’ 或 ‘t’（转置）和 ‘C’ 或 ‘c’（共轭转置），这些字符通常用作旧式 BLAS 实现的参数。

值	含义
CUBLAS_OP_N	选择非转置操作。
CUBLAS_OP_T	选择转置操作。
CUBLAS_OP_C	选择共轭转置操作。

2.2.4. cublasFillMode_t

该类型指示密集矩阵的哪个部分（下部或上部）被填充，因此应由函数使用。其值对应于 Fortran 字符 L 或 l（下部）和 U 或 u（上部），这些字符通常用作旧式 BLAS 实现的参数。

值	含义
CUBLAS_FILL_MODE_LOWER	矩阵的下部被填充。
CUBLAS_FILL_MODE_UPPER	矩阵的上部被填充。
CUBLAS_FILL_MODE_FULL	矩阵的全部被填充。

2.2.5. cublasDiagType_t

该类型指示密集矩阵的主对角线是否为单位，因此不应由函数触摸或修改。其值对应于 Fortran 字符 ‘N’ 或 ‘n’（非单位）和 ‘U’ 或 ‘u’（单位），这些字符通常用作旧式 BLAS 实现的参数。

值	含义
CUBLAS_DIAG_NON_UNIT	矩阵对角线具有非单位元素。
CUBLAS_DIAG_UNIT	矩阵对角线具有单位元素。

2.2.6. cublasSideMode_t

该类型指示在特定函数求解的矩阵方程中，密集矩阵是在左侧还是右侧。其值对应于 Fortran 字符 ‘L’ 或 ‘l’（左侧）和 ‘R’ 或 ‘r’（右侧），这些字符通常用作旧式 BLAS 实现的参数。

值	含义
CUBLAS_SIDE_LEFT	矩阵在方程的左侧。
CUBLAS_SIDE_RIGHT	矩阵在方程的右侧。

2.2.7. cublasPointerMode_t

cublasPointerMode_t 类型指示标量值是通过主机还是设备上的引用传递的。重要的是要指出，如果函数调用中存在多个标量值，则所有标量值都必须符合相同的单指针模式。可以使用 cublasSetPointerMode() 和 cublasGetPointerMode() 例程分别设置和检索指针模式。

值	含义
CUBLAS_POINTER_MODE_HOST	标量通过主机上的引用传递。
CUBLAS_POINTER_MODE_DEVICE	标量通过设备上的引用传递。

2.2.8. cublasAtomicsMode_t

该类型指示是否可以使用具有使用原子操作的替代实现的 cuBLAS 例程。可以使用 cublasSetAtomicsMode() 和 cublasGetAtomicsMode() 和例程分别设置和查询原子操作模式。

值	含义
CUBLAS_ATOMICS_NOT_ALLOWED	不允许使用原子操作。
CUBLAS_ATOMICS_ALLOWED	允许使用原子操作。

2.2.9. cublasGemmAlgo_t

cublasGemmAlgo_t 类型是一个枚举器，用于指定 GPU 架构上直到 sm_75 的矩阵-矩阵乘法算法。在 sm_80 和更新的 GPU 架构上，此枚举器无效。cuBLAS 具有以下算法选项

值	含义
CUBLAS_GEMM_DEFAULT	应用启发式算法选择 GEMM 算法
CUBLAS_GEMM_ALGO0 到 CUBLAS_GEMM_ALGO23	显式选择算法 0..23。注意：在 NVIDIA Ampere 架构 GPU 和更新的 GPU 上无效。
CUBLAS_GEMM_DEFAULT_TENSOR_OP[已弃用]	此模式已弃用，将在未来版本中删除。应用启发式算法选择 GEMM 算法，同时允许使用降低精度的 CUBLAS_COMPUTE_32F_FAST_16F 内核（为了向后兼容）。
CUBLAS_GEMM_ALGO0_TENSOR_OP 到 CUBLAS_GEMM_ALGO15_TENSOR_OP[已弃用]	这些值已弃用，将在未来版本中删除。显式选择 Tensor core GEMM 算法 0..15。允许使用降低精度的 CUBLAS_COMPUTE_32F_FAST_16F 内核（为了向后兼容）。注意：在 NVIDIA Ampere 架构 GPU 和更新的 GPU 上无效。

2.2.10. cublasMath_t

cublasMath_t 枚举类型在 cublasSetMathMode() 中用于选择计算精度模式，如下表定义。由于此设置不直接控制 Tensor Core 的使用，因此模式 CUBLAS_TENSOR_OP_MATH 已被弃用，并将在未来版本中删除。

值	含义
CUBLAS_DEFAULT_MATH	这是默认的最高性能模式，它使用计算和中间存储精度，其尾数和指数位数至少与请求的位数相同。只要有可能，就会使用 Tensor Core。
CUBLAS_PEDANTIC_MATH	此模式对计算的所有阶段使用规定的精度和标准算术，主要用于数值鲁棒性研究、测试和调试。此模式的性能可能不如其他模式。
CUBLAS_TF32_TENSOR_OP_MATH	使用 TF32 tensor core 启用单精度例程的加速。
CUBLAS_MATH_DISALLOW_REDUCED_PRECISION_REDUCTION	在混合精度例程中，如果输出类型精度低于计算类型精度，则强制矩阵乘法期间的任何归约都使用累加器类型（即，计算类型），而不是输出类型。这是一个标志，可以与其他任何值一起设置（使用按位或运算）。
CUBLAS_TENSOR_OP_MATH [已弃用]	此模式已弃用，将在未来版本中删除。允许库在可能的情况下使用 Tensor Core 操作。对于单精度 GEMM 例程，cuBLAS 将使用 CUBLAS_COMPUTE_32F_FAST_16F 计算类型。

2.2.11. cublasComputeType_t

cublasComputeType_t 枚举类型在 cublasGemmEx() 和 cublasLtMatmul()（包括所有批处理和步幅批处理变体）中使用，以选择计算精度模式，如下所述。

值	含义
CUBLAS_COMPUTE_16F	这是 16 位半精度浮点数的默认和最高性能模式，以及所有至少具有 16 位半精度的计算和中间存储精度。只要有可能，就会使用 Tensor Core。
CUBLAS_COMPUTE_16F_PEDANTIC	此模式对计算的所有阶段使用 16 位半精度浮点标准算术，主要用于数值鲁棒性研究、测试和调试。此模式的性能可能不如其他模式，因为它禁用了 tensor core 的使用。
CUBLAS_COMPUTE_32F	这是默认的 32 位单精度浮点数，并使用至少 32 位的计算和中间存储精度。
CUBLAS_COMPUTE_32F_PEDANTIC	对计算的所有阶段使用 32 位单精度浮点算术，并且还禁用算法优化，例如高斯复杂度降低 (3M)。
CUBLAS_COMPUTE_32F_FAST_16F	允许库对 32 位输入和输出矩阵使用 Tensor Core，并自动进行向下转换和 16 位半精度计算。
CUBLAS_COMPUTE_32F_FAST_16BF	允许库对 32 位输入和输出矩阵使用 Tensor Core，并自动进行向下转换和 bfloat16 计算。有关 bfloat16 的更多详细信息，请参阅 备用浮点 部分。
CUBLAS_COMPUTE_32F_FAST_TF32	允许库对 32 位输入和输出矩阵使用 Tensor Core 和 TF32 计算。有关 TF32 计算的更多详细信息，请参阅 备用浮点 部分。
CUBLAS_COMPUTE_64F	这是默认的 64 位双精度浮点数，并使用至少 64 位的计算和中间存储精度。
CUBLAS_COMPUTE_64F_PEDANTIC	对计算的所有阶段使用 64 位双精度浮点算术，并且还禁用算法优化，例如高斯复杂度降低 (3M)。
CUBLAS_COMPUTE_32I	这是默认的 32 位整数模式，并使用至少 32 位的计算和中间存储精度。
CUBLAS_COMPUTE_32I_PEDANTIC	对计算的所有阶段使用 32 位整数算术。

注意

设置环境变量 NVIDIA_TF32_OVERRIDE = 0 将覆盖 NVIDIA 库的任何默认设置或程序化配置，因此，cuBLAS 将不会使用 TF32 tensor core 加速单精度计算。

2.3. CUDA 数据类型参考

本章介绍由多个 CUDA 库共享并在头文件 library_types.h 中定义的类型。

2.3.1. cudaDataType_t

cudaDataType_t 类型是一个枚举器，用于指定数据精度。当数据引用不携带类型本身时（例如 void *），将使用它

例如，它在例程 cublasSgemmEx() 中使用。

值	含义
CUDA_R_16F	数据类型是 16 位实数半精度浮点数
CUDA_C_16F	数据类型是一个 32 位结构，由两个半精度浮点数组成，表示一个复数。
CUDA_R_16BF	数据类型是 16 位实数 bfloat16 浮点数
CUDA_C_16BF	数据类型是一个 32 位结构，由两个 bfloat16 浮点数组成，表示一个复数。
CUDA_R_32F	数据类型是 32 位实数单精度浮点数
CUDA_C_32F	数据类型是一个 64 位结构，由两个单精度浮点数组成，表示一个复数。
CUDA_R_64F	数据类型是 64 位实数双精度浮点数
CUDA_C_64F	数据类型是一个 128 位结构，由两个双精度浮点数组成，表示一个复数。
CUDA_R_8I	数据类型是 8 位实数有符号整数
CUDA_C_8I	数据类型是一个 16 位结构，由两个 8 位有符号整数组成，表示一个复数。
CUDA_R_8U	数据类型是 8 位实数无符号整数
CUDA_C_8U	数据类型是一个 16 位结构，由两个 8 位无符号整数组成，表示一个复数。
CUDA_R_32I	数据类型是 32 位实数有符号整数
CUDA_C_32I	数据类型是一个 64 位结构，由两个 32 位有符号整数组成，表示一个复数。
CUDA_R_8F_E4M3	数据类型是 E4M3 格式的 8 位实数浮点数
CUDA_R_8F_E5M2	数据类型是 E5M2 格式的 8 位实数浮点数

2.3.2. libraryPropertyType_t

libraryPropertyType_t 用作参数，用于在使用例程 cublasGetProperty() 时指定请求的属性

值	含义
MAJOR_VERSION	用于查询主版本的枚举器
MINOR_VERSION	用于查询次版本的枚举器
PATCH_LEVEL	用于标识补丁级别的数字

2.4. cuBLAS 辅助函数参考

2.4.1. cublasCreate()

cublasStatus_t
cublasCreate(cublasHandle_t *handle)

此函数初始化 cuBLAS 库并创建一个句柄，指向保存 cuBLAS 库上下文的不透明结构。它在主机和设备上分配硬件资源，并且必须在进行任何其他 cuBLAS 库调用之前调用。

cuBLAS 库上下文与当前 CUDA 设备相关联。要在多个设备上使用库，需要为每个设备创建一个 cuBLAS 句柄。另请参阅 cuBLAS 上下文。

对于给定的设备，可以创建具有不同配置的多个 cuBLAS 句柄。对于从不同线程使用同一设备的多线程应用程序，建议的编程模型是为每个线程创建一个 cuBLAS 句柄，并在线程的整个生命周期中使用该 cuBLAS 句柄。

由于 cublasCreate() 分配了一些内部资源，并且通过调用 cublasDestroy() 释放这些资源将隐式调用 cudaDeviceSynchronize()，因此建议尽量减少调用这些函数的次数。

返回值	含义
CUBLAS_STATUS_SUCCESS	初始化成功
CUBLAS_STATUS_NOT_INITIALIZED	CUDA™ 运行时初始化失败
CUBLAS_STATUS_ALLOC_FAILED	无法分配资源
CUBLAS_STATUS_INVALID_VALUE	handle 为 NULL

2.4.2. cublasDestroy()

cublasStatus_t
cublasDestroy(cublasHandle_t handle)

此函数释放 cuBLAS 库使用的硬件资源。此函数通常是使用特定句柄对 cuBLAS 库的最后一次调用。由于 cublasCreate() 分配了一些内部资源，并且通过调用 cublasDestroy() 释放这些资源将隐式调用 cudaDeviceSynchronize()，因此建议尽量减少调用这些函数的次数。

返回值	含义
CUBLAS_STATUS_SUCCESS	关闭成功
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化

2.4.3. cublasGetVersion()

cublasStatus_t
cublasGetVersion(cublasHandle_t handle, int *version)

此函数返回 cuBLAS 库的版本号。

返回值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_INVALID_VALUE	version 为 NULL

注意

可以使用设置为 NULL 的 handle 安全地调用此函数。这允许用户在没有句柄的情况下获取库的版本。另一种方法是使用 cublasGetProperty()。

2.4.4. cublasGetProperty()

cublasStatus_t
cublasGetProperty(libraryPropertyType type, int *value)

此函数返回 value 指向的内存中请求属性的值。有关支持的类型，请参阅 libraryPropertyType。

返回值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_INVALID_VALUE	无效的类型或值 如果 type 具有无效值，或者 如果 value 为 NULL

2.4.5. cublasGetStatusName()

const char* cublasGetStatusName(cublasStatus_t status)

此函数返回给定状态的字符串表示形式。

返回值	含义
以 NULL 结尾的字符串	status 的字符串表示形式

2.4.6. cublasGetStatusString()

const char* cublasGetStatusString(cublasStatus_t status)

此函数返回给定状态的描述字符串。

返回值	含义
以 NULL 结尾的字符串	关于 status 的描述

2.4.7. cublasSetStream()

cublasStatus_t
cublasSetStream(cublasHandle_t handle, cudaStream_t streamId)

此函数设置 cuBLAS 库流，该流将用于执行所有后续对 cuBLAS 库函数的调用。如果未设置 cuBLAS 库流，则所有内核都使用默认的 NULL 流。 特别是，此例程可用于在内核启动之间更改流，然后将 cuBLAS 库流重置回 NULL。 此外，此函数会无条件地将 cuBLAS 库工作区重置回默认工作区池（参见 cublasSetWorkspace()）。

返回值	含义
CUBLAS_STATUS_SUCCESS	流已成功设置
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化

2.4.8. cublasSetWorkspace()

cublasStatus_t
cublasSetWorkspace(cublasHandle_t handle, void *workspace, size_t workspaceSizeInBytes)

此函数将 cuBLAS 库工作区设置为用户拥有的设备缓冲区，该缓冲区将用于执行所有后续对 cuBLAS 库函数的调用（在当前设置的流上）。 如果未设置 cuBLAS 库工作区，则所有内核将使用在 cuBLAS 上下文创建期间分配的默认工作区池。 特别是，此例程可用于在内核启动之间更改工作区。 工作区指针必须至少对齐到 256 字节，否则将返回 CUBLAS_STATUS_INVALID_VALUE 错误。 cublasSetStream() 函数会无条件地将 cuBLAS 库工作区重置回默认工作区池。 调用此函数，包括使用等于 0 的 workspaceSizeInBytes，将阻止 cuBLAS 库使用默认工作区。 workspaceSizeInBytes 值太小可能会导致某些例程失败并返回 CUBLAS_STATUS_ALLOC_FAILED 错误，或导致性能大幅下降。 工作区大小等于或大于 16KiB 足以防止 CUBLAS_STATUS_ALLOC_FAILED 错误，而更大的工作区可以为某些例程提供性能优势。

注意

如果 cublasSetStream() 设置的流是 cudaStreamPerThread，并且有多个线程使用相同的 cuBLAS 库句柄，则用户必须手动管理同步，以避免用户提供的工作区中可能出现的竞争条件。 或者，用户可以依赖默认工作区池，该池可以安全地防止竞争条件。

下表显示了用户提供的工作区的建议大小。 这基于 cuBLAS 默认工作区池大小，该大小取决于 GPU 架构。

GPU 架构	建议的工作区大小
NVIDIA Hopper 架构 (sm90)	32 MiB
NVIDIA Blackwell 架构 (sm10x)	32 MiB
NVIDIA Blackwell 架构 (sm12x)	4 MiB
其他	4 MiB

下表列出了此函数可能返回的错误值及其含义。

返回值	含义
CUBLAS_STATUS_SUCCESS	流已成功设置
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	workspace 指针未至少对齐到 256 字节

2.4.9. cublasGetStream()

cublasStatus_t
cublasGetStream(cublasHandle_t handle, cudaStream_t *streamId)

此函数获取 cuBLAS 库流，该流正用于执行所有对 cuBLAS 库函数的调用。 如果未设置 cuBLAS 库流，则所有内核都使用默认的 NULL 流。

返回值	含义
CUBLAS_STATUS_SUCCESS	流已成功返回
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	streamId 为 NULL

2.4.10. cublasGetPointerMode()

cublasStatus_t
cublasGetPointerMode(cublasHandle_t handle, cublasPointerMode_t *mode)

此函数获取 cuBLAS 库使用的指针模式。 有关更多详细信息，请参阅关于 cublasPointerMode_t 类型的章节。

返回值	含义
CUBLAS_STATUS_SUCCESS	指针模式已成功获取
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	mode 为 NULL

2.4.11. cublasSetPointerMode()

cublasStatus_t
cublasSetPointerMode(cublasHandle_t handle, cublasPointerMode_t mode)

此函数设置 cuBLAS 库使用的指针模式。 默认情况下，值通过主机上的引用传递。 有关更多详细信息，请参阅关于 cublasPointerMode_t 类型的章节。

返回值	含义
CUBLAS_STATUS_SUCCESS	指针模式已成功设置
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	mode 不是 CUBLAS_POINTER_MODE_HOST 或 CUBLAS_POINTER_MODE_DEVICE

2.4.12. cublasSetVector()

cublasStatus_t
cublasSetVector(int n, int elemSize,
                const void *x, int incx, void *y, int incy)

此函数支持 64 位整数接口。

此函数将主机内存空间中向量 x 的 n 个元素复制到 GPU 内存空间中向量 y。 假设两个向量中的元素大小均为 elemSize 字节。 连续元素之间的存储间距由源向量 x 的 incx 和目标向量 y 的 incy 给出。

由于假定二维矩阵采用列优先格式，因此如果向量是矩阵的一部分，则向量增量等于 1 会访问该矩阵的（部分）列。 同样，使用等于矩阵前导维度的增量会导致访问该矩阵的（部分）行。

返回值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_INVALID_VALUE	参数 incx、incy 或 elemSize 不是正数
CUBLAS_STATUS_MAPPING_ERROR	访问 GPU 内存时出错

2.4.13. cublasGetVector()

cublasStatus_t
cublasGetVector(int n, int elemSize,
                const void *x, int incx, void *y, int incy)

此函数支持 64 位整数接口。

此函数将 GPU 内存空间中向量 x 的 n 个元素复制到主机内存空间中向量 y。 假设两个向量中的元素大小均为 elemSize 字节。 连续元素之间的存储间距由源向量 x 的 incx 和目标向量 y 的 incy 给出。

由于假定二维矩阵采用列优先格式，因此如果向量是矩阵的一部分，则向量增量等于 1 会访问该矩阵的（部分）列。 同样，使用等于矩阵前导维度的增量会导致访问该矩阵的（部分）行。

返回值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_INVALID_VALUE	参数 incx、incy 或 elemSize 不是正数
CUBLAS_STATUS_MAPPING_ERROR	访问 GPU 内存时出错

2.4.14. cublasSetMatrix()

cublasStatus_t
cublasSetMatrix(int rows, int cols, int elemSize,
                const void *A, int lda, void *B, int ldb)

此函数支持 64 位整数接口。

此函数将主机内存空间中矩阵 A 的 rows x cols 个元素的图块复制到 GPU 内存空间中矩阵 B。 假定每个元素都需要 elemSize 字节的存储空间，并且两个矩阵都以列优先格式存储，源矩阵 A 和目标矩阵 B 的前导维度分别在 lda 和 ldb 中给出。 前导维度指示已分配矩阵的行数，即使仅使用其子矩阵也是如此。

返回值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_INVALID_VALUE	参数 rows 或 cols 为负数，或者 elemSize、lda ldb 不是正数。
CUBLAS_STATUS_MAPPING_ERROR	访问 GPU 内存时出错

2.4.15. cublasGetMatrix()

cublasStatus_t
cublasGetMatrix(int rows, int cols, int elemSize,
                const void *A, int lda, void *B, int ldb)

此函数支持 64 位整数接口。

此函数将 GPU 内存空间中矩阵 A 的 rows x cols 个元素的图块复制到主机内存空间中矩阵 B。 假定每个元素都需要 elemSize 字节的存储空间，并且两个矩阵都以列优先格式存储，源矩阵 A 和目标矩阵 B 的前导维度分别在 lda 和 ldb 中给出。 前导维度指示已分配矩阵的行数，即使仅使用其子矩阵也是如此。

返回值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_INVALID_VALUE	参数 rows 或 cols 为负数，或者 elemSize、lda ldb 不是正数。
CUBLAS_STATUS_MAPPING_ERROR	访问 GPU 内存时出错

2.4.16. cublasSetVectorAsync()

cublasStatus_t
cublasSetVectorAsync(int n, int elemSize, const void *hostPtr, int incx,
                     void *devicePtr, int incy, cudaStream_t stream)

此函数支持 64 位整数接口。

此函数的功能与 cublasSetVector() 相同，但数据传输是使用给定的 CUDA™ 流参数异步完成的（相对于主机而言）。

返回值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_INVALID_VALUE	参数 incx、incy 或 elemSize 不是正数
CUBLAS_STATUS_MAPPING_ERROR	访问 GPU 内存时出错

2.4.17. cublasGetVectorAsync()

cublasStatus_t
cublasGetVectorAsync(int n, int elemSize, const void *devicePtr, int incx,
                     void *hostPtr, int incy, cudaStream_t stream)

此函数支持 64 位整数接口。

此函数的功能与 cublasGetVector() 相同，但数据传输是使用给定的 CUDA™ 流参数异步完成的（相对于主机而言）。

返回值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_INVALID_VALUE	参数 incx、incy 或 elemSize 不是正数
CUBLAS_STATUS_MAPPING_ERROR	访问 GPU 内存时出错

2.4.18. cublasSetMatrixAsync()

cublasStatus_t
cublasSetMatrixAsync(int rows, int cols, int elemSize, const void *A,
                     int lda, void *B, int ldb, cudaStream_t stream)

此函数支持 64 位整数接口。

此函数的功能与 cublasSetMatrix() 相同，但数据传输是使用给定的 CUDA™ 流参数异步完成的（相对于主机而言）。

返回值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_INVALID_VALUE	参数 rows 或 cols 为负数，或者 elemSize、lda ldb 不是正数。
CUBLAS_STATUS_MAPPING_ERROR	访问 GPU 内存时出错

2.4.19. cublasGetMatrixAsync()

cublasStatus_t
cublasGetMatrixAsync(int rows, int cols, int elemSize, const void *A,
                     int lda, void *B, int ldb, cudaStream_t stream)

此函数支持 64 位整数接口。

此函数的功能与 cublasGetMatrix() 相同，但数据传输是使用给定的 CUDA™ 流参数异步完成的（相对于主机而言）。

返回值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_INVALID_VALUE	参数 rows 或 cols 为负数，或者 elemSize、lda ldb 不是正数。
CUBLAS_STATUS_MAPPING_ERROR	访问 GPU 内存时出错

2.4.20. cublasSetAtomicsMode()

cublasStatus_t cublasSetAtomicsMode(cublasHandlet handle, cublasAtomicsMode_t mode)

某些例程（如 cublas<t>symv() 和 cublas<t>hemv()）具有使用原子操作累积结果的替代实现。 此实现通常明显更快，但可能会生成与其他运行不完全相同的结果。 从数学上讲，这些不同的结果并不重要，但在调试时，这些差异可能是有害的。

此函数允许或禁止在 cuBLAS 库中对所有具有替代实现的例程使用原子操作。 如果未在任何 cuBLAS 例程的文档中明确指定，则表示此例程没有使用原子操作的替代实现。 当禁用原子操作模式时，每个 cuBLAS 例程在同一硬件上使用相同的参数调用时，都应生成与其他运行相同的结果。

默认初始化的 cublasHandle_t 对象的默认原子操作模式为 CUBLAS_ATOMICS_NOT_ALLOWED。 有关更多详细信息，请参阅关于该类型的章节。

返回值	含义
CUBLAS_STATUS_SUCCESS	原子操作模式已成功设置
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化

2.4.21. cublasGetAtomicsMode()

cublasStatus_t cublasGetAtomicsMode(cublasHandle_t handle, cublasAtomicsMode_t *mode)

此函数查询特定 cuBLAS 上下文的原子操作模式。

默认初始化的 cublasHandle_t 对象的默认原子操作模式为 CUBLAS_ATOMICS_NOT_ALLOWED。 有关更多详细信息，请参阅关于该类型的章节。

返回值	含义
CUBLAS_STATUS_SUCCESS	原子操作模式已成功查询
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	参数 mode 是一个 NULL 指针

2.4.22. cublasSetMathMode()

cublasStatus_t cublasSetMathMode(cublasHandle_t handle, cublasMath_t mode)

cublasSetMathMode() 函数使您能够选择由 cublasMath_t 定义的计算精度模式。 允许用户将计算精度模式设置为它们的逻辑组合（不包括已弃用的 CUBLAS_TENSOR_OP_MATH）。 例如，cublasSetMathMode(handle, CUBLAS_DEFAULT_MATH | CUBLAS_MATH_DISALLOW_REDUCED_PRECISION_REDUCTION)。 请注意，默认数学模式为 CUBLAS_DEFAULT_MATH。

有关 cublasGemmEx() 和 cublasLtMatmul() API 及其步幅变体允许的矩阵和计算精度，请参阅： cublasGemmEx()、cublasGemmBatchedEx()、cublasGemmStridedBatchedEx() 和 cublasLtMatmul()。

返回值	含义
CUBLAS_STATUS_SUCCESS	数学模式已成功设置。
CUBLAS_STATUS_INVALID_VALUE	为模式指定了无效值。
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化。

2.4.23. cublasGetMathMode()

cublasStatus_t cublasGetMathMode(cublasHandle_t handle, cublasMath_t *mode)

此函数返回库例程使用的数学模式。

返回值	含义
CUBLAS_STATUS_SUCCESS	数学类型已成功返回。
CUBLAS_STATUS_INVALID_VALUE	如果 mode 为 NULL。
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化。

2.4.24. cublasSetSmCountTarget()

cublasStatus_t cublasSetSmCountTarget(cublasHandle_t handle, int smCountTarget)

cublasSetSmCountTarget() 函数允许覆盖库在内核执行期间可用的多处理器数量。

当已知 cuBLAS 例程与其他 CUDA 流上的工作并发运行时，可以使用此选项来提高库性能。 例如，在具有 108 个多处理器的 NVIDIA A100 GPU 上，当存在网格大小为 8 的并发内核运行时，可以使用 cublasSetSmCountTarget() 并将 smCountTarget 设置为 100，以覆盖库启发式方法，从而针对在剩余 100 个多处理器上运行进行优化。

设置为 0 时，库将恢复为其默认行为。 输入值不应超过设备的多处理器计数，可以使用 cudaDeviceGetAttribute 获取该计数。 不接受负值。

用户必须确保在使用此例程修改库句柄时的线程安全性，类似于使用 cublasSetStream() 等时的情况。

返回值	含义
CUBLAS_STATUS_SUCCESS	SM 计数目标已成功设置。
CUBLAS_STATUS_INVALID_VALUE	smCountTarget 的值超出允许范围。
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化。

2.4.25. cublasGetSmCountTarget()

cublasStatus_t cublasGetSmCountTarget(cublasHandle_t handle, int *smCountTarget)

此函数获取先前编程到库句柄的值。

返回值	含义
CUBLAS_STATUS_SUCCESS	SM 计数目标已成功设置。
CUBLAS_STATUS_INVALID_VALUE	smCountTarget 为 NULL。
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化。

2.4.26. cublasLoggerConfigure()

cublasStatus_t cublasLoggerConfigure(
    int             logIsOn,
    int             logToStdOut,
    int             logToStdErr,
    const char*     logFileName)

此函数配置运行时期间的日志记录。 除了这种类型的配置外，还可以使用 libcublas 将检查的特殊环境变量来配置日志记录

• CUBLAS_LOGINFO_DBG - 将此环境变量设置为 1 意味着打开日志记录（默认情况下日志记录处于关闭状态）。

• CUBLAS_LOGDEST_DBG - 此环境变量编码将日志写入到何处：stdout、stderr 表示分别将日志消息写入标准输出或错误流。 其他值被解释为文件名。

参数

参数。	内存	输入/输出	含义
logIsOn	主机	输入	完全打开/关闭日志记录。 默认情况下处于关闭状态，但通过调用 cublasSetLoggerCallback() 到用户定义的回调函数来打开。
logToStdOut	主机	输入	打开/关闭日志记录到标准输出 I/O 流。 默认情况下处于关闭状态。
logToStdErr	主机	输入	打开/关闭日志记录到标准错误 I/O 流。 默认情况下处于关闭状态。
logFileName	主机	输入	打开/关闭日志记录到文件系统中由其名称指定的文件。 cublasLoggerConfigure() 复制 logFileName 的内容。 如果您对此类型的日志记录不感兴趣，则应提供空指针。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成

2.4.27. cublasGetLoggerCallback()

cublasStatus_t cublasGetLoggerCallback(
    cublasLogCallback* userCallback)

此函数检索指向先前通过 cublasSetLoggerCallback() 安装的自定义用户定义回调函数的函数指针，否则为零。

参数。	内存	输入/输出	含义
userCallback	主机	输出	指向用户定义回调函数的指针。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_INVALID_VALUE	userCallback 为 NULL

2.4.28. cublasSetLoggerCallback()

cublasStatus_t cublasSetLoggerCallback(
    cublasLogCallback   userCallback)

此函数通过 cublas C 公共 API 安装自定义用户定义的回调函数。

参数。	内存	输入/输出	含义
userCallback	主机	输入	指向用户定义回调函数的指针。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成

2.5. cuBLAS Level-1 函数参考

在本章中，我们描述了执行标量和基于向量运算的 Level-1 基本线性代数子程序 (BLAS1) 函数。我们将使用缩写 <type> 表示类型，<t> 表示相应的短类型，以便更简洁明了地呈现已实现的函数。除非另有说明，否则 <type> 和 <t> 具有以下含义

<type>	<t>	含义
float	s 或 S	实数单精度
double	d 或 D	实数双精度
cuComplex	c 或 C	复数单精度
cuDoubleComplex	z 或 Z	复数双精度

当函数的参数和返回值不同时（这有时会发生在复数输入的情况下），<t> 也可以是 Sc、Cs、Dz 和 Zd。

缩写 \(\mathbf{Re}(\cdot)\) 和 \(\mathbf{Im}(\cdot)\) 将分别代表数字的实部和虚部。 由于实数的虚部不存在，我们将认为它为零，并且通常可以简单地从正在使用它的方程中丢弃它。 此外，\(\bar{\alpha}\) 将表示 \(\alpha\) 的复共轭。

通常在整个文档中，小写希腊字母 \(\alpha\) 和 \(\beta\) 将表示标量，粗体小写英文字母 \(\mathbf{x}\) 和 \(\mathbf{y}\) 将表示向量，大写英文字母 \(A\) 、 \(B\) 和 \(C\) 将表示矩阵。

2.5.1. cublasI<t>amax()

cublasStatus_t cublasIsamax(cublasHandle_t handle, int n,
                            const float *x, int incx, int *result)
cublasStatus_t cublasIdamax(cublasHandle_t handle, int n,
                            const double *x, int incx, int *result)
cublasStatus_t cublasIcamax(cublasHandle_t handle, int n,
                            const cuComplex *x, int incx, int *result)
cublasStatus_t cublasIzamax(cublasHandle_t handle, int n,
                            const cuDoubleComplex *x, int incx, int *result)

此函数支持 64 位整数接口。

此函数查找最大幅度元素的（最小）索引。 因此，结果是第一个 \(i\)，使得 \(\left| \mathbf{Im}\left( {x\lbrack j\rbrack} \right) \middle| + \middle| \mathbf{Re}\left( {x\lbrack j\rbrack} \right) \right|\) 对于 \(i = 1,\ldots,n\) 和 \(j = 1 + \left( {i - 1} \right)*\text{ incx}\) 最大。 请注意，最后一个方程式反映了基于 1 的索引，用于与 Fortran 兼容。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
n		输入	向量 x 中的元素数。
x	设备	输入	带有元素的 <type> 向量。
incx		输入	x 的连续元素之间的步幅。
result	主机或设备	输出	结果索引，如果 n <= 0 或 incx <= 0，则设置为 0。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_ALLOC_FAILED	无法分配缩减缓冲区
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动
CUBLAS_STATUS_INVALID_VALUE	result 为 NULL

有关参考，请参阅 NETLIB 文档

isamax()、idamax()、icamax()、izamax()

2.5.2. cublasI<t>amin()

cublasStatus_t cublasIsamin(cublasHandle_t handle, int n,
                            const float *x, int incx, int *result)
cublasStatus_t cublasIdamin(cublasHandle_t handle, int n,
                            const double *x, int incx, int *result)
cublasStatus_t cublasIcamin(cublasHandle_t handle, int n,
                            const cuComplex *x, int incx, int *result)
cublasStatus_t cublasIzamin(cublasHandle_t handle, int n,
                            const cuDoubleComplex *x, int incx, int *result)

此函数支持 64 位整数接口。

此函数查找最小幅度元素的（最小）索引。 因此，结果是第一个 \(i\)，使得 \(\left| \mathbf{Im}\left( {x\lbrack j\rbrack} \right) \middle| + \middle| \mathbf{Re}\left( {x\lbrack j\rbrack} \right) \right|\) 对于 \(i = 1,\ldots,n\) 和 \(j = 1 + \left( {i - 1} \right)*\text{incx}\) 最小。 请注意，最后一个方程式反映了基于 1 的索引，用于与 Fortran 兼容。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
n		输入	向量 x 中的元素数。
x	设备	输入	带有元素的 <type> 向量。
incx		输入	x 的连续元素之间的步幅。
result	主机或设备	输出	结果索引，如果 n <= 0 或 incx <= 0，则设置为 0。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_ALLOC_FAILED	无法分配缩减缓冲区
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动
CUBLAS_STATUS_INVALID_VALUE	result 为 NULL

有关参考，请参阅 NETLIB 文档

isamin()

2.5.3. cublas<t>asum()

cublasStatus_t  cublasSasum(cublasHandle_t handle, int n,
                            const float           *x, int incx, float  *result)
cublasStatus_t  cublasDasum(cublasHandle_t handle, int n,
                            const double          *x, int incx, double *result)
cublasStatus_t cublasScasum(cublasHandle_t handle, int n,
                            const cuComplex       *x, int incx, float  *result)
cublasStatus_t cublasDzasum(cublasHandle_t handle, int n,
                            const cuDoubleComplex *x, int incx, double *result)

此函数支持 64 位整数接口。

此函数计算向量 x 的元素绝对值之和。 因此，结果是 \(\left. \sum_{i = 1}^{n} \middle| \mathbf{Im}\left( {x\lbrack j\rbrack} \right) \middle| + \middle| \mathbf{Re}\left( {x\lbrack j\rbrack} \right) \right|\)，其中 \(j = 1 + \left( {i - 1} \right)*\text{incx}\)。 请注意，最后一个方程式反映了基于 1 的索引，用于与 Fortran 兼容。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
n		输入	向量 x 中的元素数。
x	设备	输入	带有元素的 <type> 向量。
incx		输入	x 的连续元素之间的步幅。
result	主机或设备	输出	结果总和，如果 n <= 0 或 incx <= 0，则设置为 0。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_ALLOC_FAILED	无法分配缩减缓冲区
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动
CUBLAS_STATUS_INVALID_VALUE	result 为 NULL

有关参考，请参阅 NETLIB 文档

sasum()、dasum()、scasum()、dzasum()

2.5.4. cublas<t>axpy()

cublasStatus_t cublasSaxpy(cublasHandle_t handle, int n,
                           const float           *alpha,
                           const float           *x, int incx,
                           float                 *y, int incy)
cublasStatus_t cublasDaxpy(cublasHandle_t handle, int n,
                           const double          *alpha,
                           const double          *x, int incx,
                           double                *y, int incy)
cublasStatus_t cublasCaxpy(cublasHandle_t handle, int n,
                           const cuComplex       *alpha,
                           const cuComplex       *x, int incx,
                           cuComplex             *y, int incy)
cublasStatus_t cublasZaxpy(cublasHandle_t handle, int n,
                           const cuDoubleComplex *alpha,
                           const cuDoubleComplex *x, int incx,
                           cuDoubleComplex       *y, int incy)

此函数支持 64 位整数接口。

此函数将向量 x 乘以标量 \(\alpha\)，并将其添加到向量 y，并用结果覆盖最新的向量。 因此，执行的操作是 \(\mathbf{y}\lbrack j\rbrack = \alpha \times \mathbf{x}\lbrack k\rbrack + \mathbf{y}\lbrack j\rbrack\)，对于 \(i = 1,\ldots,n\) 、 \(k = 1 + \left( {i - 1} \right)*\text{incx}\) 和 \(j = 1 + \left( {i - 1} \right)*\text{incy}\)。 请注意，最后两个方程式反映了基于 1 的索引，用于与 Fortran 兼容。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
n		输入	向量 x 和 y 中的元素数。
x	设备	输入	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
y	设备	输入/输出	<type> 带有 n 个元素的向量。
incy		输入	y 的连续元素之间的步幅。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

saxpy()、daxpy()、caxpy()、zaxpy()

2.5.5. cublas<t>copy()

cublasStatus_t cublasScopy(cublasHandle_t handle, int n,
                           const float           *x, int incx,
                           float                 *y, int incy)
cublasStatus_t cublasDcopy(cublasHandle_t handle, int n,
                           const double          *x, int incx,
                           double                *y, int incy)
cublasStatus_t cublasCcopy(cublasHandle_t handle, int n,
                           const cuComplex       *x, int incx,
                           cuComplex             *y, int incy)
cublasStatus_t cublasZcopy(cublasHandle_t handle, int n,
                           const cuDoubleComplex *x, int incx,
                           cuDoubleComplex       *y, int incy)

此函数支持 64 位整数接口。

此函数将向量 x 复制到向量 y 中。 因此，执行的操作是 \(\mathbf{y}\lbrack j\rbrack = \mathbf{x}\lbrack k\rbrack\)，对于 \(i = 1,\ldots,n\) 、 \(k = 1 + \left( {i - 1} \right)*\text{incx}\) 和 \(j = 1 + \left( {i - 1} \right)*\text{incy}\)。 请注意，最后两个方程式反映了基于 1 的索引，用于与 Fortran 兼容。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
n		输入	向量 x 和 y 中的元素数。
x	设备	输入	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
y	设备	输入/输出	<type> 带有 n 个元素的向量。
incy		输入	y 的连续元素之间的步幅。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

scopy()、dcopy()、ccopy()、zcopy()

2.5.6. cublas<t>dot()

cublasStatus_t cublasSdot (cublasHandle_t handle, int n,
                           const float           *x, int incx,
                           const float           *y, int incy,
                           float           *result)
cublasStatus_t cublasDdot (cublasHandle_t handle, int n,
                           const double          *x, int incx,
                           const double          *y, int incy,
                           double          *result)
cublasStatus_t cublasCdotu(cublasHandle_t handle, int n,
                           const cuComplex       *x, int incx,
                           const cuComplex       *y, int incy,
                           cuComplex       *result)
cublasStatus_t cublasCdotc(cublasHandle_t handle, int n,
                           const cuComplex       *x, int incx,
                           const cuComplex       *y, int incy,
                           cuComplex       *result)
cublasStatus_t cublasZdotu(cublasHandle_t handle, int n,
                           const cuDoubleComplex *x, int incx,
                           const cuDoubleComplex *y, int incy,
                           cuDoubleComplex *result)
cublasStatus_t cublasZdotc(cublasHandle_t handle, int n,
                           const cuDoubleComplex *x, int incx,
                           const cuDoubleComplex *y, int incy,
                           cuDoubleComplex       *result)

此函数支持 64 位整数接口。

此函数计算向量 x 和 y 的点积。 因此，结果是 \(\sum_{i = 1}^{n}\left( {\mathbf{x}\lbrack k\rbrack \times \mathbf{y}\lbrack j\rbrack} \right)\)，其中 \(k = 1 + \left( {i - 1} \right)*\text{incx}\) 和 \(j = 1 + \left( {i - 1} \right)*\text{incy}\)。 请注意，在第一个方程式中，如果函数名称以字符“c”结尾，则应使用向量 x 元素的共轭，并且最后两个方程式反映了基于 1 的索引，用于与 Fortran 兼容。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
n		输入	向量 x 和 y 中的元素数。
x	设备	输入	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
y	设备	输入	<type> 带有 n 个元素的向量。
incy		输入	y 的连续元素之间的步幅。
result	主机或设备	输出	结果点积，如果 n <= 0，则设置为 0

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_ALLOC_FAILED	无法分配缩减缓冲区
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

sdot()、ddot()、cdotu()、cdotc()、zdotu()、zdotc()

2.5.7. cublas<t>nrm2()

cublasStatus_t  cublasSnrm2(cublasHandle_t handle, int n,
                            const float           *x, int incx, float  *result)
cublasStatus_t  cublasDnrm2(cublasHandle_t handle, int n,
                            const double          *x, int incx, double *result)
cublasStatus_t cublasScnrm2(cublasHandle_t handle, int n,
                            const cuComplex       *x, int incx, float  *result)
cublasStatus_t cublasDznrm2(cublasHandle_t handle, int n,
                            const cuDoubleComplex *x, int incx, double *result)

此函数支持 64 位整数接口。

此函数计算向量 x 的欧几里得范数。 代码使用多阶段累积模型来避免中间下溢和溢出，结果等效于精确算术中的 \(\sqrt{\sum_{i = 1}^{n}\left( {\mathbf{x}\lbrack j\rbrack \times \mathbf{x}\lbrack j\rbrack} \right)}\)，其中 \(j = 1 + \left( {i - 1} \right)*\text{incx}\)。 请注意，最后一个方程式反映了基于 1 的索引，用于与 Fortran 兼容。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
n		输入	向量 x 中的元素数。
x	设备	输入	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
result	主机或设备	输出	结果范数，如果 n <= 0 或 incx <= 0，则设置为 0。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_ALLOC_FAILED	无法分配缩减缓冲区
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动
CUBLAS_STATUS_INVALID_VALUE	result 为 NULL

有关参考，请参阅 NETLIB 文档

snrm2()、dnrm2()、scnrm2()、dznrm2()

2.5.8. cublas<t>rot()

cublasStatus_t  cublasSrot(cublasHandle_t handle, int n,
                           float           *x, int incx,
                           float           *y, int incy,
                           const float  *c, const float           *s)
cublasStatus_t  cublasDrot(cublasHandle_t handle, int n,
                           double          *x, int incx,
                           double          *y, int incy,
                           const double *c, const double          *s)
cublasStatus_t  cublasCrot(cublasHandle_t handle, int n,
                           cuComplex       *x, int incx,
                           cuComplex       *y, int incy,
                           const float  *c, const cuComplex       *s)
cublasStatus_t cublasCsrot(cublasHandle_t handle, int n,
                           cuComplex       *x, int incx,
                           cuComplex       *y, int incy,
                           const float  *c, const float           *s)
cublasStatus_t  cublasZrot(cublasHandle_t handle, int n,
                           cuDoubleComplex *x, int incx,
                           cuDoubleComplex *y, int incy,
                           const double *c, const cuDoubleComplex *s)
cublasStatus_t cublasZdrot(cublasHandle_t handle, int n,
                           cuDoubleComplex *x, int incx,
                           cuDoubleComplex *y, int incy,
                           const double *c, const double          *s)

此函数支持 64 位整数接口。

此函数应用 Givens 旋转矩阵（即，在 x,y 平面中逆时针旋转，角度由 cos(alpha)=c, sin(alpha)=s 定义）

\(G = \begin{pmatrix} c & s \\ {- s} & c \\ \end{pmatrix}\)

到向量 x 和 y。

因此，结果是 \(\mathbf{x}\lbrack k\rbrack = c \times \mathbf{x}\lbrack k\rbrack + s \times \mathbf{y}\lbrack j\rbrack\) 和 \(\mathbf{y}\lbrack j\rbrack = - s \times \mathbf{x}\lbrack k\rbrack + c \times \mathbf{y}\lbrack j\rbrack\)，其中 \(k = 1 + \left( {i - 1} \right)*\text{incx}\) 和 \(j = 1 + \left( {i - 1} \right)*\text{incy}\)。 请注意，最后两个方程式反映了基于 1 的索引，用于与 Fortran 兼容。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
n		输入	向量 x 和 y 中的元素数。
x	设备	输入/输出	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
y	设备	输入/输出	<type> 带有 n 个元素的向量。
incy		输入	y 的连续元素之间的步幅。
c	主机或设备	输入	旋转矩阵的余弦元素。
s	主机或设备	输入	旋转矩阵的正弦元素。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

srot()、drot()、crot()、csrot()、zrot()、zdrot()

2.5.9. cublas<t>rotg()

cublasStatus_t cublasSrotg(cublasHandle_t handle,
                           float           *a, float           *b,
                           float  *c, float           *s)
cublasStatus_t cublasDrotg(cublasHandle_t handle,
                           double          *a, double          *b,
                           double *c, double          *s)
cublasStatus_t cublasCrotg(cublasHandle_t handle,
                           cuComplex       *a, cuComplex       *b,
                           float  *c, cuComplex       *s)
cublasStatus_t cublasZrotg(cublasHandle_t handle,
                           cuDoubleComplex *a, cuDoubleComplex *b,
                           double *c, cuDoubleComplex *s)

此函数支持 64 位整数接口。

此函数构造 Givens 旋转矩阵

\(G = \begin{pmatrix} c & s \\ {- s} & c \\ \end{pmatrix}\)

将 \(2 \times 1\) 向量 \(\left( {a,b} \right)^{T}\) 的第二个条目置零。

然后，对于实数，我们可以写成

\(\begin{pmatrix} c & s \\ {- s} & c \\ \end{pmatrix}\begin{pmatrix} a \\ b \\ \end{pmatrix} = \begin{pmatrix} r \\ 0 \\ \end{pmatrix}\)

其中 \(c^{2} + s^{2} = 1\) 和 \(r = a^{2} + b^{2}\) 。参数 \(a\) 和 \(b\) 分别被覆盖为 \(r\) 和 \(z\) 。 \(z\) 的值使得 \(c\) 和 \(s\) 可以使用以下规则恢复

\(\left( {c,s} \right) = \begin{cases} \left( {\sqrt{1 - z^{2}},z} \right) & {\text{ 如果 }\left| z \middle| < 1 \right.} \\ \left( {0.0,1.0} \right) & {\text{ 如果 }\left| z \middle| = 1 \right.} \\ \left( 1/z,\sqrt{1 - z^{2}} \right) & {\text{ 如果 }\left| z \middle| > 1 \right.} \\ \end{cases}\)

对于复数，我们可以写成

\(\begin{pmatrix} c & s \\ {- \bar{s}} & c \\ \end{pmatrix}\begin{pmatrix} a \\ b \\ \end{pmatrix} = \begin{pmatrix} r \\ 0 \\ \end{pmatrix}\)

其中 \(c^{2} + \left( {\bar{s} \times s} \right) = 1\) 和 \(r = \frac{a}{|a|} \times \parallel \left( {a,b} \right)^{T} \parallel_{2}\) ，其中 \(\parallel \left( {a,b} \right)^{T} \parallel_{2} = \sqrt{\left| a|^{2} + \middle| B|^{2} \right.}\) 对于 \(a \neq 0\) ，并且 \(r = b\) 对于 \(a = 0\) 。最后，参数 \(a\) 在退出时被覆盖为 \(r\) 。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
a	主机或设备	输入/输出	<type> 标量，被覆盖为 \(r\) 。
b	主机或设备	输入/输出	<type> 标量，被覆盖为 \(z\) 。
c	主机或设备	输出	旋转矩阵的余弦元素。
s	主机或设备	输出	旋转矩阵的正弦元素。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

srotg(), drotg(), crotg(), zrotg()

2.5.10. cublas<t>rotm()

cublasStatus_t cublasSrotm(cublasHandle_t handle, int n, float  *x, int incx,
                           float  *y, int incy, const float*  param)
cublasStatus_t cublasDrotm(cublasHandle_t handle, int n, double *x, int incx,
                           double *y, int incy, const double* param)

此函数支持 64 位整数接口。

此函数应用修正的吉文斯变换

\(H = \begin{pmatrix} h_{11} & h_{12} \\ h_{21} & h_{22} \\ \end{pmatrix}\)

到向量 x 和 y。

因此，结果是 \(\mathbf{x}\lbrack k\rbrack = h_{11} \times \mathbf{x}\lbrack k\rbrack + h_{12} \times \mathbf{y}\lbrack j\rbrack\) 和 \(\mathbf{y}\lbrack j\rbrack = h_{21} \times \mathbf{x}\lbrack k\rbrack + h_{22} \times \mathbf{y}\lbrack j\rbrack\) ，其中 \(k = 1 + \left( {i - 1} \right)*\text{incx}\) 和 \(j = 1 + \left( {i - 1} \right)*\text{incy}\) 。请注意，最后两个方程反映了基于 1 的索引，用于与 Fortran 的兼容性。

矩阵 \(H\) 的元素 , , 和 分别存储在 param[1]、 param[2]、 param[3] 和 param[4] 中。 flag=param[0] 定义了矩阵 \(H\) 条目的以下预定义值

flag=-1.0	flag= 0.0	flag= 1.0	flag=-2.0
\(\begin{pmatrix} h_{11} & h_{12} \\ h_{21} & h_{22} \\ \end{pmatrix}\)	\(\begin{pmatrix} {1.0} & h_{12} \\ h_{21} & {1.0} \\ \end{pmatrix}\)	\(\begin{pmatrix} h_{11} & {1.0} \\ {- 1.0} & h_{22} \\ \end{pmatrix}\)	\(\begin{pmatrix} {1.0} & {0.0} \\ {0.0} & {1.0} \\ \end{pmatrix}\)

请注意，标志隐含的值 -1.0、0.0 和 1.0 不存储在 param 中。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
n		输入	向量 x 和 y 中的元素数。
x	设备	输入/输出	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
y	设备	输入/输出	<type> 带有 n 个元素的向量。
incy		输入	y 的连续元素之间的步幅。
param	主机或设备	输入	<type> 5 个元素的向量，其中 param[0] 和 param[1..4] 包含标志和矩阵 \(H\)。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

srotm(), drotm()

2.5.11. cublas<t>rotmg()

cublasStatus_t cublasSrotmg(cublasHandle_t handle, float  *d1, float  *d2,
                            float  *x1, const float  *y1, float  *param)
cublasStatus_t cublasDrotmg(cublasHandle_t handle, double *d1, double *d2,
                            double *x1, const double *y1, double *param)

此函数支持 64 位整数接口。

此函数构造修正的吉文斯变换

\(H = \begin{pmatrix} h_{11} & h_{12} \\ h_{21} & h_{22} \\ \end{pmatrix}\)

将 \(2 \times 1\) 向量 \(\left( {\sqrt{d1}*x1,\sqrt{d2}*y1} \right)^{T}\) 的第二个条目置零。

flag=param[0] 定义了矩阵 \(H\) 条目的以下预定义值

flag=-1.0	flag= 0.0	flag= 1.0	flag=-2.0
\(\begin{pmatrix} h_{11} & h_{12} \\ h_{21} & h_{22} \\ \end{pmatrix}\)	\(\begin{pmatrix} {1.0} & h_{12} \\ h_{21} & {1.0} \\ \end{pmatrix}\)	\(\begin{pmatrix} h_{11} & {1.0} \\ {- 1.0} & h_{22} \\ \end{pmatrix}\)	\(\begin{pmatrix} {1.0} & {0.0} \\ {0.0} & {1.0} \\ \end{pmatrix}\)

请注意，标志隐含的值 -1.0、0.0 和 1.0 不存储在 param 中。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
d1	主机或设备	输入/输出	<type> 标量，在退出时被覆盖。
d2	主机或设备	输入/输出	<type> 标量，在退出时被覆盖。
x1	主机或设备	输入/输出	<type> 标量，在退出时被覆盖。
y1	主机或设备	输入	<type> 标量。
param	主机或设备	输出	<type> 5 个元素的向量，其中 param[0] 和 param[1-4] 包含标志和矩阵 \(H\)。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

srotmg(), drotmg()

2.5.12. cublas<t>scal()

cublasStatus_t  cublasSscal(cublasHandle_t handle, int n,
                            const float           *alpha,
                            float           *x, int incx)
cublasStatus_t  cublasDscal(cublasHandle_t handle, int n,
                            const double          *alpha,
                            double          *x, int incx)
cublasStatus_t  cublasCscal(cublasHandle_t handle, int n,
                            const cuComplex       *alpha,
                            cuComplex       *x, int incx)
cublasStatus_t cublasCsscal(cublasHandle_t handle, int n,
                            const float           *alpha,
                            cuComplex       *x, int incx)
cublasStatus_t  cublasZscal(cublasHandle_t handle, int n,
                            const cuDoubleComplex *alpha,
                            cuDoubleComplex *x, int incx)
cublasStatus_t cublasZdscal(cublasHandle_t handle, int n,
                            const double          *alpha,
                            cuDoubleComplex *x, int incx)

此函数支持 64 位整数接口。

此函数按标量 \(\alpha\) 缩放向量 x ，并使用结果覆盖它。因此，执行的操作是 \(\mathbf{x}\lbrack j\rbrack = \alpha \times \mathbf{x}\lbrack j\rbrack\) ，对于 \(i = 1,\ldots,n\) 和 \(j = 1 + \left( {i - 1} \right)*\text{incx}\) 。请注意，最后两个方程反映了基于 1 的索引，用于与 Fortran 的兼容性。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
n		输入	向量 x 中的元素数。
x	设备	输入/输出	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。

下表列出了此函数可能返回的错误值及其含义。

:class: table-no-stripes

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

sscal(), dscal(), csscal(), cscal(), zdscal(), zscal()

2.5.13. cublas<t>swap()

cublasStatus_t cublasSswap(cublasHandle_t handle, int n, float           *x,
                           int incx, float           *y, int incy)
cublasStatus_t cublasDswap(cublasHandle_t handle, int n, double          *x,
                           int incx, double          *y, int incy)
cublasStatus_t cublasCswap(cublasHandle_t handle, int n, cuComplex       *x,
                           int incx, cuComplex       *y, int incy)
cublasStatus_t cublasZswap(cublasHandle_t handle, int n, cuDoubleComplex *x,
                           int incx, cuDoubleComplex *y, int incy)

此函数支持 64 位整数接口。

此函数交换向量 x 和 y 的元素。因此，执行的操作是 \(\left. \mathbf{y}\lbrack j\rbrack\Leftrightarrow\mathbf{x}\lbrack k\rbrack \right.\) ，对于 \(i = 1,\ldots,n\) 、 \(k = 1 + \left( {i - 1} \right)*\text{incx}\) 和 \(j = 1 + \left( {i - 1} \right)*\text{incy}\) 。请注意，最后两个方程反映了基于 1 的索引，用于与 Fortran 的兼容性。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
n		输入	向量 x 和 y 中的元素数。
x	设备	输入/输出	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
y	设备	输入/输出	<type> 带有 n 个元素的向量。
incy		输入	y 的连续元素之间的步幅。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

sswap(), dswap(), cswap(), zswap()

2.6. cuBLAS Level-2 函数参考

在本章中，我们描述了执行矩阵-向量运算的 Level-2 基础线性代数子程序 (BLAS2) 函数。

2.6.1. cublas<t>gbmv()

cublasStatus_t cublasSgbmv(cublasHandle_t handle, cublasOperation_t trans,
                           int m, int n, int kl, int ku,
                           const float           *alpha,
                           const float           *A, int lda,
                           const float           *x, int incx,
                           const float           *beta,
                           float           *y, int incy)
cublasStatus_t cublasDgbmv(cublasHandle_t handle, cublasOperation_t trans,
                           int m, int n, int kl, int ku,
                           const double          *alpha,
                           const double          *A, int lda,
                           const double          *x, int incx,
                           const double          *beta,
                           double          *y, int incy)
cublasStatus_t cublasCgbmv(cublasHandle_t handle, cublasOperation_t trans,
                           int m, int n, int kl, int ku,
                           const cuComplex       *alpha,
                           const cuComplex       *A, int lda,
                           const cuComplex       *x, int incx,
                           const cuComplex       *beta,
                           cuComplex       *y, int incy)
cublasStatus_t cublasZgbmv(cublasHandle_t handle, cublasOperation_t trans,
                           int m, int n, int kl, int ku,
                           const cuDoubleComplex *alpha,
                           const cuDoubleComplex *A, int lda,
                           const cuDoubleComplex *x, int incx,
                           const cuDoubleComplex *beta,
                           cuDoubleComplex *y, int incy)

此函数支持 64 位整数接口。

此函数执行带状矩阵-向量乘法

\(\mathbf{y} = \alpha\text{ op}(A)\mathbf{x} + \beta\mathbf{y}\)

其中 \(A\) 是具有 \(kl\) 个子对角线和 \(ku\) 个超对角线的带状矩阵， \(\mathbf{x}\) 和 \(\mathbf{y}\) 是向量， \(\alpha\) 和 \(\beta\) 是标量。此外，对于矩阵 \(A\)

\(\text{ op}(A) = \begin{cases} A & \text{ 如果 trans == $\mathrm{CUBLAS\_OP\_N}$} \\ A^{T} & \text{ 如果 trans == $\mathrm{CUBLAS\_OP\_T}$} \\ A^{H} & \text{ 如果 trans == $\mathrm{CUBLAS\_OP\_C}$} \\ \end{cases}\)

带状矩阵 \(A\) 按列存储，主对角线存储在第 \(ku + 1\) 行（从第一个位置开始），第一个超对角线存储在第 \(ku\) 行（从第二个位置开始），第一个子对角线存储在第 \(ku + 2\) 行（从第一个位置开始）等等。因此，一般来说，元素 \(A\left( {i,j} \right)\) 存储在内存位置 A(ku+1+i-j,j) 中，对于 \(j = 1,\ldots,n\) 和 \(i \in \left\lbrack {\max\left( {1,j - ku} \right),\min\left( {m,j + kl} \right)} \right\rbrack\) 。此外，数组 \(A\) 中概念上不对应于带状矩阵中元素的元素（左上角 \(ku \times ku\) 和右下角 \(kl \times kl\) 三角形）不会被引用。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
trans		输入	运算 op(A)，它是非转置或（共轭）转置。
m		输入	矩阵 A 的行数。
n		输入	矩阵 A 的列数。
kl		输入	矩阵 A 的子对角线数。
ku		输入	矩阵 A 的超对角线数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	<type> 维度为 lda x n 的数组，其中 lda >= kl + ku + 1。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
x	设备	输入	<type> 如果 trans == CUBLAS_OP_N 则为具有 n 个元素的向量，否则为 m 个元素。
incx		输入	x 的连续元素之间的步幅。
beta	主机或设备	输入	<type> 用于乘法的标量。如果 beta == 0，则 y 不必是有效输入。
y	设备	输入/输出	<type> 如果 trans == CUBLAS_OP_N 则为具有 m 个元素的向量，否则为 n 个元素。
incy		输入	y 的连续元素之间的步幅。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0、 n < 0、 kl < 0 或 ku < 0，或者 如果 lda < (kl + ku + 1)，或者 如果 incx == 0 或 incy == 0，或者 如果 trans 不是 CUBLAS_OP_N、 CUBLAS_OP_T、 CUBLAS_OP_C 之一，或者 如果 alpha 或 beta 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

sgbmv(), dgbmv(), cgbmv(), zgbmv()

2.6.2. cublas<t>gemv()

cublasStatus_t cublasSgemv(cublasHandle_t handle, cublasOperation_t trans,
                           int m, int n,
                           const float           *alpha,
                           const float           *A, int lda,
                           const float           *x, int incx,
                           const float           *beta,
                           float           *y, int incy)
cublasStatus_t cublasDgemv(cublasHandle_t handle, cublasOperation_t trans,
                           int m, int n,
                           const double          *alpha,
                           const double          *A, int lda,
                           const double          *x, int incx,
                           const double          *beta,
                           double          *y, int incy)
cublasStatus_t cublasCgemv(cublasHandle_t handle, cublasOperation_t trans,
                           int m, int n,
                           const cuComplex       *alpha,
                           const cuComplex       *A, int lda,
                           const cuComplex       *x, int incx,
                           const cuComplex       *beta,
                           cuComplex       *y, int incy)
cublasStatus_t cublasZgemv(cublasHandle_t handle, cublasOperation_t trans,
                           int m, int n,
                           const cuDoubleComplex *alpha,
                           const cuDoubleComplex *A, int lda,
                           const cuDoubleComplex *x, int incx,
                           const cuDoubleComplex *beta,
                           cuDoubleComplex *y, int incy)

此函数支持 64 位整数接口。

此函数执行矩阵-向量乘法

\(\textbf{y} = \alpha\text{ op}(A)\textbf{x} + \beta\textbf{y}\)

其中 \(A\) 是以列优先格式存储的 \(m \times n\) 矩阵， \(\mathbf{x}\) 和 \(\mathbf{y}\) 是向量， \(\alpha\) 和 \(\beta\) 是标量。此外，对于矩阵 \(A\)

\(\text{ op}(A) = \begin{cases} A & \text{ 如果 trans == $\mathrm{CUBLAS\_OP\_N}$} \\ A^{T} & \text{ 如果 trans == $\mathrm{CUBLAS\_OP\_T}$} \\ A^{H} & \text{ 如果 trans == $\mathrm{CUBLAS\_OP\_C}$} \\ \end{cases}\)

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
trans		输入	运算 op(A)，它是非转置或（共轭）转置。
m		输入	矩阵 A 的行数。
n		输入	矩阵 A 的列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	<type> 维度为 lda x n 的数组，其中 lda >= max(1, m)。在输入之前，数组 A 的前导 m 乘 n 部分必须包含系数矩阵。在退出时未更改。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。 lda 必须至少为 max(1, m)。
x	设备	输入	<type> 向量，如果 trans == CUBLAS_OP_N 则至少包含 (1 + (n - 1) * abs(incx)) 个元素，否则至少包含 (1 + (m - 1) * abs(incx)) 个元素。
incx		输入	x 的连续元素之间的步幅。
beta	主机或设备	输入	<type> 用于乘法的标量。如果 beta == 0，则 y 不必是有效输入。
y	设备	输入/输出	<type> 向量，如果 trans == CUBLAS_OP_N 则至少包含 (1 + (m - 1) * abs(incy)) 个元素，否则至少包含 (1 + (n - 1) * abs(incy)) 个元素。
incy		输入	y 的连续元素之间的步幅

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	参数 m < 0 或 n < 0，或者 incx == 0 或 incy == 0
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

sgemv(), dgemv(), cgemv(), zgemv()

2.6.3. cublas<t>ger()

cublasStatus_t  cublasSger(cublasHandle_t handle, int m, int n,
                           const float           *alpha,
                           const float           *x, int incx,
                           const float           *y, int incy,
                           float           *A, int lda)
cublasStatus_t  cublasDger(cublasHandle_t handle, int m, int n,
                           const double          *alpha,
                           const double          *x, int incx,
                           const double          *y, int incy,
                           double          *A, int lda)
cublasStatus_t cublasCgeru(cublasHandle_t handle, int m, int n,
                           const cuComplex       *alpha,
                           const cuComplex       *x, int incx,
                           const cuComplex       *y, int incy,
                           cuComplex       *A, int lda)
cublasStatus_t cublasCgerc(cublasHandle_t handle, int m, int n,
                           const cuComplex       *alpha,
                           const cuComplex       *x, int incx,
                           const cuComplex       *y, int incy,
                           cuComplex       *A, int lda)
cublasStatus_t cublasZgeru(cublasHandle_t handle, int m, int n,
                           const cuDoubleComplex *alpha,
                           const cuDoubleComplex *x, int incx,
                           const cuDoubleComplex *y, int incy,
                           cuDoubleComplex *A, int lda)
cublasStatus_t cublasZgerc(cublasHandle_t handle, int m, int n,
                           const cuDoubleComplex *alpha,
                           const cuDoubleComplex *x, int incx,
                           const cuDoubleComplex *y, int incy,
                           cuDoubleComplex *A, int lda)

此函数支持 64 位整数接口。

此函数执行秩 1 更新

\(A = \begin{cases} {\alpha\mathbf{xy}^{T} + A} & \text{如果调用 ger(),geru()} \\ {\alpha\mathbf{xy}^{H} + A} & \text{如果调用 gerc()} \\ \end{cases}\)

其中 \(A\) 是以列优先格式存储的 \(m \times n\) 矩阵， \(\mathbf{x}\) 和 \(\mathbf{y}\) 是向量， \(\alpha\) 是标量。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
m		输入	矩阵 A 的行数。
n		输入	矩阵 A 的列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
x	设备	输入	<type> 具有 m 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
y	设备	输入	<type> 带有 n 个元素的向量。
incy		输入	y 的连续元素之间的步幅。
A	设备	输入/输出	<type> 维度为 lda x n 的数组，其中 lda >= max(1, m)。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0 或 n < 0，或者 如果 incx == 0 或 incy == 0，或者 如果 alpha 为 NULL，或者 如果 lda < max(1, m)
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

sger(), dger(), cgeru(), cgerc(), zgeru(), zgerc()

2.6.4. cublas<t>sbmv()

cublasStatus_t cublasSsbmv(cublasHandle_t handle, cublasFillMode_t uplo,
                           int n, int k, const float  *alpha,
                           const float  *A, int lda,
                           const float  *x, int incx,
                           const float  *beta, float *y, int incy)
cublasStatus_t cublasDsbmv(cublasHandle_t handle, cublasFillMode_t uplo,
                           int n, int k, const double *alpha,
                           const double *A, int lda,
                           const double *x, int incx,
                           const double *beta, double *y, int incy)

此函数支持 64 位整数接口。

此函数执行对称带状矩阵-向量乘法

\(\textbf{y} = \alpha A\textbf{x} + \beta\textbf{y}\)

其中 \(A\) 是具有 \(k\) 个子对角线和超对角线的 \(n \times n\) 对称带状矩阵， \(\mathbf{x}\) 和 \(\mathbf{y}\) 是向量， \(\alpha\) 和 \(\beta\) 是标量。

如果 uplo == CUBLAS_FILL_MODE_LOWER，则对称带状矩阵 \(A\) 按列存储，矩阵的主对角线存储在第 1 行，第一个子对角线存储在第 2 行（从第一个位置开始），第二个子对角线存储在第 3 行（从第一个位置开始），等等。因此，一般来说，元素 \(A(i,j)\) 存储在内存位置 A(1+i-j,j) 中，对于 \(j = 1,\ldots,n\) 和 \(i \in \lbrack j,\min(m,j + k)\rbrack\) 。此外，数组 A 中概念上不对应于带状矩阵中元素的元素（右下角 \(k \times k\) 三角形）不会被引用。

如果 uplo == CUBLAS_FILL_MODE_UPPER，则对称带状矩阵 \(A\) 按列存储，矩阵的主对角线存储在第 k + 1 行，第一个超对角线存储在第 k 行（从第二个位置开始），第二个超对角线存储在第 k-1 行（从第三个位置开始），等等。因此，一般来说，元素 \(A(i,j)\) 存储在内存位置 A(1+k+i-j,j) 中，对于 \(j = 1,\ldots,n\) 和 \(i \in \lbrack\max(1,j - k),j\rbrack\) 。此外，数组 A 中概念上不对应于带状矩阵中元素的元素（左上角 \(k \times k\) 三角形）不会被引用。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 A 的下部或上部是否存储，另一个对称部分未被引用，并从存储的元素中推断出来。
n		输入	矩阵 A 的行数和列数。
k		输入	矩阵 A 的子对角线和超对角线的数量。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	A
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
x	设备	输入	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
beta	主机或设备	输入	<type> 用于乘法的标量。如果 beta == 0，则 y 不必是有效输入。
y	设备	输入/输出	<type> 带有 n 个元素的向量。
incy		输入	y 的连续元素之间的步幅。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 维度为 lda x n 的数组，其中 lda >= k + 1。 如果 incx == 0 或 incy == 0，或者 如果 n < 0 或 k < 0，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 和 CUBLAS_FILL_MODE_UPPER 之一，或者 如果 alpha 或 beta 为 NULL，或者
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

如果 lda < (1 + k)

ssbmv(), dsbmv()

cublasStatus_t cublasSspmv(cublasHandle_t handle, cublasFillMode_t uplo,
                           int n, const float  *alpha, const float  *AP,
                           const float  *x, int incx, const float  *beta,
                           float  *y, int incy)
cublasStatus_t cublasDspmv(cublasHandle_t handle, cublasFillMode_t uplo,
                           int n, const double *alpha, const double *AP,
                           const double *x, int incx, const double *beta,
                           double *y, int incy)

此函数支持 64 位整数接口。

2.6.5. cublas<t>spmv()

\(\textbf{y} = \alpha A\textbf{x} + \beta\textbf{y}\)

此函数执行对称压缩矩阵-向量乘法

其中 \(A\) 是以压缩格式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 和 \(\mathbf{y}\) 是向量， \(\alpha\) 和 \(\beta\) 是标量。

如果 uplo == CUBLAS_FILL_MODE_LOWER，则对称矩阵 \(A\) 的下三角部分中的元素按列无间隙地压缩在一起，因此元素 \(A(i,j)\) 存储在内存位置 AP[i+((2*n-j+1)*j)/2] 中，对于 \(j = 1,\ldots,n\) 和 \(i \geq j\) 。因此，压缩格式仅需要 \(\frac{n(n + 1)}{2}\) 个元素用于存储。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	如果 uplo == CUBLAS_FILL_MODE_UPPER，则对称矩阵 \(A\) 的上三角部分中的元素按列无间隙地压缩在一起，因此元素 \(A(i,j)\) 存储在内存位置 AP[i+(j*(j+1))/2] 中，对于 \(j = 1,\ldots,n\) 和 \(i \leq j\) 。因此，压缩格式仅需要 \(\frac{n(n + 1)}{2}\) 个元素用于存储。
n		输入	指示矩阵 \(A\) 的下部或上部是否存储，另一个对称部分未被引用，并从存储的元素中推断出来。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
矩阵 \(A\) 的行数和列数。	设备	输入	AP
x	设备	输入	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
beta	主机或设备	输入	<type> 用于乘法的标量。如果 beta == 0，则 y 不必是有效输入。
y	设备	输入	<type> 带有 n 个元素的向量。
incy		输入	y 的连续元素之间的步幅。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 以压缩格式存储的 \(A\) 数组。 如果 incx == 0 或 incy == 0，或者 如果 n < 0 或 k < 0，或者 如果 alpha 或 beta 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

如果 n < 0，或者

sspmv(), dspmv()

cublasStatus_t cublasSspr(cublasHandle_t handle, cublasFillMode_t uplo,
                          int n, const float  *alpha,
                          const float  *x, int incx, float  *AP)
cublasStatus_t cublasDspr(cublasHandle_t handle, cublasFillMode_t uplo,
                          int n, const double *alpha,
                          const double *x, int incx, double *AP)

此函数支持 64 位整数接口。

2.6.6. cublas<t>spr()

此函数执行压缩对称秩 1 更新

\(A = \alpha\textbf{x}\textbf{x}^{T} + A\)

其中 \(A\) 是以压缩格式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 和 \(\mathbf{y}\) 是向量， \(\alpha\) 和 \(\beta\) 是标量。

如果 uplo == CUBLAS_FILL_MODE_LOWER，则对称矩阵 \(A\) 的下三角部分中的元素按列无间隙地压缩在一起，因此元素 \(A(i,j)\) 存储在内存位置 AP[i+((2*n-j+1)*j)/2] 中，对于 \(j = 1,\ldots,n\) 和 \(i \geq j\) 。因此，压缩格式仅需要 \(\frac{n(n + 1)}{2}\) 个元素用于存储。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	如果 uplo == CUBLAS_FILL_MODE_UPPER，则对称矩阵 \(A\) 的上三角部分中的元素按列无间隙地压缩在一起，因此元素 \(A(i,j)\) 存储在内存位置 AP[i+(j*(j+1))/2] 中，对于 \(j = 1,\ldots,n\) 和 \(i \leq j\) 。因此，压缩格式仅需要 \(\frac{n(n + 1)}{2}\) 个元素用于存储。
n		输入	指示矩阵 \(A\) 的下部或上部是否存储，另一个对称部分未被引用，并从存储的元素中推断出来。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
x	设备	输入	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
矩阵 \(A\) 的行数和列数。	设备	输入/输出	AP

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 以压缩格式存储的 \(A\) 数组。 其中 \(A\) 是以压缩格式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 是向量， \(\alpha\) 是标量。 如果 n < 0 或 k < 0，或者 如果 incx == 0，或者
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

如果 alpha 为 NULL

sspr(), dspr()

cublasStatus_t cublasSspr2(cublasHandle_t handle, cublasFillMode_t uplo,
                           int n, const float  *alpha,
                           const float  *x, int incx,
                           const float  *y, int incy, float  *AP)
cublasStatus_t cublasDspr2(cublasHandle_t handle, cublasFillMode_t uplo,
                           int n, const double *alpha,
                           const double *x, int incx,
                           const double *y, int incy, double *AP)

此函数支持 64 位整数接口。

2.6.7. cublas<t>spr2()

此函数执行压缩对称秩 2 更新

\(A = \alpha\textbf{x}\textbf{x}^{T} + A\)

其中 \(A\) 是以压缩格式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 和 \(\mathbf{y}\) 是向量， \(\alpha\) 和 \(\beta\) 是标量。

如果 uplo == CUBLAS_FILL_MODE_LOWER，则对称矩阵 \(A\) 的下三角部分中的元素按列无间隙地压缩在一起，因此元素 \(A(i,j)\) 存储在内存位置 AP[i+((2*n-j+1)*j)/2] 中，对于 \(j = 1,\ldots,n\) 和 \(i \geq j\) 。因此，压缩格式仅需要 \(\frac{n(n + 1)}{2}\) 个元素用于存储。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	如果 uplo == CUBLAS_FILL_MODE_UPPER，则对称矩阵 \(A\) 的上三角部分中的元素按列无间隙地压缩在一起，因此元素 \(A(i,j)\) 存储在内存位置 AP[i+(j*(j+1))/2] 中，对于 \(j = 1,\ldots,n\) 和 \(i \leq j\) 。因此，压缩格式仅需要 \(\frac{n(n + 1)}{2}\) 个元素用于存储。
n		输入	指示矩阵 \(A\) 的下部或上部是否存储，另一个对称部分未被引用，并从存储的元素中推断出来。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
x	设备	输入	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
y	设备	输入	<type> 带有 n 个元素的向量。
incy		输入	y 的连续元素之间的步幅。
矩阵 \(A\) 的行数和列数。	设备	输入/输出	AP

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 以压缩格式存储的 \(A\) 数组。 如果 incx == 0 或 incy == 0，或者 如果 n < 0 或 k < 0，或者 如果 incx == 0，或者
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

\(A = \alpha\left( {\textbf{x}\textbf{y}^{T} + \textbf{y}\textbf{x}^{T}} \right) + A\)

sspr2(), dspr2()

cublasStatus_t cublasSsymv(cublasHandle_t handle, cublasFillMode_t uplo,
                           int n, const float           *alpha,
                           const float           *A, int lda,
                           const float           *x, int incx, const float           *beta,
                           float           *y, int incy)
cublasStatus_t cublasDsymv(cublasHandle_t handle, cublasFillMode_t uplo,
                           int n, const double          *alpha,
                           const double          *A, int lda,
                           const double          *x, int incx, const double          *beta,
                           double          *y, int incy)
cublasStatus_t cublasCsymv(cublasHandle_t handle, cublasFillMode_t uplo,
                           int n, const cuComplex       *alpha, /* host or device pointer */
                           const cuComplex       *A, int lda,
                           const cuComplex       *x, int incx, const cuComplex       *beta,
                           cuComplex       *y, int incy)
cublasStatus_t cublasZsymv(cublasHandle_t handle, cublasFillMode_t uplo,
                           int n, const cuDoubleComplex *alpha,
                           const cuDoubleComplex *A, int lda,
                           const cuDoubleComplex *x, int incx, const cuDoubleComplex *beta,
                           cuDoubleComplex *y, int incy)

此函数支持 64 位整数接口。

2.6.8. cublas<t>symv()

此函数执行对称矩阵-向量乘法。

\(\textbf{y} = \alpha A\textbf{x} + \beta\textbf{y}\) 其中 \(A\) 是以较低或较高模式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 和 \(\mathbf{y}\) 是向量， \(\alpha\) 和 \(\beta\) 是标量。

此函数具有使用原子的替代更快实现，可以使用 cublasSetAtomicsMode() 启用。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	有关原子用法的更多详细信息，请参阅关于函数 cublasSetAtomicsMode() 的部分。
n		输入	矩阵 A 的行数和列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	指示矩阵的下部或上部是否存储，另一个对称部分未被引用，并从存储的元素中推断出来。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
x	设备	输入	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
beta	主机或设备	输入	<type> 用于乘法的标量。如果 beta == 0，则 y 不必是有效输入。
y	设备	输入/输出	<type> 带有 n 个元素的向量。
incy		输入	y 的连续元素之间的步幅。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 以压缩格式存储的 \(A\) 数组。 如果 incx == 0 或 incy == 0，或者 如果 n < 0 或 k < 0，或者 <type> 维度为 lda x n 的数组，其中 lda >= max(1, n)。
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

如果 lda < n

ssymv(), dsymv()

cublasStatus_t cublasSsyr(cublasHandle_t handle, cublasFillMode_t uplo,
                          int n, const float           *alpha,
                          const float           *x, int incx, float           *A, int lda)
cublasStatus_t cublasDsyr(cublasHandle_t handle, cublasFillMode_t uplo,
                          int n, const double          *alpha,
                          const double          *x, int incx, double          *A, int lda)
cublasStatus_t cublasCsyr(cublasHandle_t handle, cublasFillMode_t uplo,
                          int n, const cuComplex       *alpha,
                          const cuComplex       *x, int incx, cuComplex       *A, int lda)
cublasStatus_t cublasZsyr(cublasHandle_t handle, cublasFillMode_t uplo,
                          int n, const cuDoubleComplex *alpha,
                          const cuDoubleComplex *x, int incx, cuDoubleComplex *A, int lda)

此函数支持 64 位整数接口。

2.6.9. cublas<t>syr()

此函数执行压缩对称秩 1 更新

此函数执行对称秩 1 更新

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 A 的下部或上部是否存储，另一个对称部分未被引用，并从存储的元素中推断出来。
n		输入	矩阵 A 的行数和列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
x	设备	输入	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
A	设备	输入/输出	其中 \(A\) 是以列优先格式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 是向量， \(\alpha\) 是标量。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 以压缩格式存储的 \(A\) 数组。 其中 \(A\) 是以压缩格式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 是向量， \(\alpha\) 是标量。 如果 n < 0 或 k < 0，或者 <type> 维度为 lda x n 的数组，其中 lda >= max(1, n)。 如果 incx == 0，或者
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

如果 lda < max(1, n)，或者

ssyr(), dsyr()

cublasStatus_t cublasSsyr2(cublasHandle_t handle, cublasFillMode_t uplo, int n,
                           const float           *alpha, const float           *x, int incx,
                           const float           *y, int incy, float           *A, int lda
cublasStatus_t cublasDsyr2(cublasHandle_t handle, cublasFillMode_t uplo, int n,
                           const double          *alpha, const double          *x, int incx,
                           const double          *y, int incy, double          *A, int lda
cublasStatus_t cublasCsyr2(cublasHandle_t handle, cublasFillMode_t uplo, int n,
                           const cuComplex       *alpha, const cuComplex       *x, int incx,
                           const cuComplex       *y, int incy, cuComplex       *A, int lda
cublasStatus_t cublasZsyr2(cublasHandle_t handle, cublasFillMode_t uplo, int n,
                           const cuDoubleComplex *alpha, const cuDoubleComplex *x, int incx,
                           const cuDoubleComplex *y, int incy, cuDoubleComplex *A, int lda

此函数支持 64 位整数接口。

2.6.10. cublas<t>syr2()

此函数执行压缩对称秩 2 更新

此函数执行对称秩 2 更新

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 A 的下部或上部是否存储，另一个对称部分未被引用，并从存储的元素中推断出来。
n		输入	矩阵 A 的行数和列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
x	设备	输入	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
y	设备	输入	<type> 带有 n 个元素的向量。
incy		输入	y 的连续元素之间的步幅。
A	设备	输入/输出	其中 \(A\) 是以列优先格式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 和 \(\mathbf{y}\) 是向量， \(\alpha\) 是标量。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 以压缩格式存储的 \(A\) 数组。 如果 incx == 0 或 incy == 0，或者 如果 n < 0 或 k < 0，或者 如果 alpha 为 NULL，或者 <type> 维度为 lda x n 的数组，其中 lda >= max(1,n)。
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

如果 lda < max(1, n)

ssyr2(), dsyr2()

cublasStatus_t cublasStbmv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, int k, const float           *A, int lda,
                           float           *x, int incx)
cublasStatus_t cublasDtbmv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, int k, const double          *A, int lda,
                           double          *x, int incx)
cublasStatus_t cublasCtbmv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, int k, const cuComplex       *A, int lda,
                           cuComplex       *x, int incx)
cublasStatus_t cublasZtbmv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, int k, const cuDoubleComplex *A, int lda,
                           cuDoubleComplex *x, int incx)

此函数支持 64 位整数接口。

2.6.11. cublas<t>tbmv()

此函数执行三角带状矩阵-向量乘法

\(\textbf{x} = \text{op}(A)\textbf{x}\)

其中 \(A\) 是三角带状矩阵， \(\mathbf{x}\) 是向量。此外，对于矩阵 \(A\)

如果 uplo == CUBLAS_FILL_MODE_LOWER，则三角带状矩阵 \(A\) 按列存储，矩阵的主对角线存储在第 1 行，第一条子对角线存储在第 2 行（从第一个位置开始），第二条子对角线存储在第 3 行（从第一个位置开始），依此类推。因此，通常元素 \(A(i,j)\) 存储在内存位置 A(1+i-j,j)，对于 \(j = 1,\ldots,n\) 和 \(i \in \lbrack j,\min(m,j + k)\rbrack\) 。此外，数组 A 中概念上不对应于带状矩阵中元素的元素（右下角 \(k \times k\) 三角形）不会被引用。

如果 uplo == CUBLAS_FILL_MODE_UPPER，则三角带状矩阵 \(A\) 按列存储，矩阵的主对角线存储在第 k + 1 行，第一条超对角线存储在第 k 行（从第二个位置开始），第二条超对角线存储在第 k-1 行（从第三个位置开始），依此类推。因此，通常元素 \(A(i,j)\) 存储在内存位置 A(1+k+i-j,j)，对于 \(j = 1,\ldots,n\) 和 \(i \in \lbrack\max(1,j - k,j)\rbrack\) 。此外，数组 A 中概念上不对应于带状矩阵中元素的元素（左上角 \(k \times k\) 三角形）不会被引用。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 A 的下半部分还是上半部分被存储，另一部分不会被引用，而是从存储的元素中推断出来。
trans		输入	运算 op(A)，它是非转置或（共轭）转置。
diag		输入	指示矩阵 A 主对角线上的元素是否为单位元素且不应被访问。
n		输入	矩阵 A 的行数和列数。
k		输入	矩阵的子对角线和超对角线的数量。
A	设备	输入	<type> 维度为 lda x n 的数组，其中 lda >= k + 1。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
x	设备	输入/输出	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 维度为 lda x n 的数组，其中 lda >= k + 1。 其中 \(A\) 是以压缩格式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 是向量， \(\alpha\) 是标量。 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 n < 0 或 k < 0，或者 如果 diag 不是 CUBLAS_DIAG_UNIT 和 CUBLAS_DIAG_NON_UNIT 之一，或者 如果 alpha 或 beta 为 NULL，或者
CUBLAS_STATUS_ALLOC_FAILED	内部暂存内存分配失败
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

stbmv(), dtbmv(), ctbmv(), ztbmv()

2.6.12. cublas<t>tbsv()

cublasStatus_t cublasStbsv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, int k, const float           *A, int lda,
                           float           *x, int incx)
cublasStatus_t cublasDtbsv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, int k, const double          *A, int lda,
                           double          *x, int incx)
cublasStatus_t cublasCtbsv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, int k, const cuComplex       *A, int lda,
                           cuComplex       *x, int incx)
cublasStatus_t cublasZtbsv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, int k, const cuDoubleComplex *A, int lda,
                           cuDoubleComplex *x, int incx)

此函数支持 64 位整数接口。

此函数求解具有单个右侧向量的三角带状线性系统

\(\text{op}(A)\textbf{x} = \textbf{b}\)

其中 \(A\) 是一个三角带状矩阵，\(\mathbf{x}\) 和 \(\mathbf{b}\) 是向量。此外，对于矩阵 \(A\)

其中 \(A\) 是三角带状矩阵， \(\mathbf{x}\) 是向量。此外，对于矩阵 \(A\)

解 \(\mathbf{x}\) 在退出时覆盖右侧向量 \(\mathbf{b}\)。

此函数中不包含对奇异性或近奇异性的测试。

如果 uplo == CUBLAS_FILL_MODE_LOWER，则三角带状矩阵 \(A\) 按列存储，矩阵的主对角线存储在第 1 行，第一条子对角线存储在第 2 行（从第一个位置开始），第二条子对角线存储在第 3 行（从第一个位置开始），依此类推。因此，通常元素 \(A(i,j)\) 存储在内存位置 A(1+i-j,j)，对于 \(j = 1,\ldots,n\) 和 \(i \in \lbrack j,\min(m,j + k)\rbrack\) 。此外，数组 A 中概念上不对应于带状矩阵中元素的元素（右下角 \(k \times k\) 三角形）不会被引用。

如果 uplo == CUBLAS_FILL_MODE_UPPER，则三角带状矩阵 \(A\) 按列存储，矩阵的主对角线存储在第 k + 1 行，第一条超对角线存储在第 k 行（从第二个位置开始），第二条超对角线存储在第 k-1 行（从第三个位置开始），依此类推。因此，通常元素 \(A(i,j)\) 存储在内存位置 A(1+k+i-j,j)，对于 \(j = 1,\ldots,n\) 和 \(i \in \lbrack\max(1,j - k,j)\rbrack\) 。此外，数组 A 中概念上不对应于带状矩阵中元素的元素（左上角 \(k \times k\) 三角形）不会被引用。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 A 的下半部分还是上半部分被存储，另一部分不会被引用，而是从存储的元素中推断出来。
trans		输入	运算 op(A)，它是非转置或（共轭）转置。
diag		输入	指示矩阵 A 主对角线上的元素是否为单位元素且不应被访问。
n		输入	矩阵 A 的行数和列数。
k		输入	矩阵 A 的子对角线和超对角线的数量。
A	设备	输入	<type> 维度为 lda x n 的数组，其中 lda >= k+1。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
x	设备	输入/输出	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 维度为 lda x n 的数组，其中 lda >= k + 1。 其中 \(A\) 是以压缩格式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 是向量， \(\alpha\) 是标量。 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 n < 0 或 k < 0，或者 如果 diag 不是 CUBLAS_DIAG_UNIT 和 CUBLAS_DIAG_NON_UNIT 之一，或者 如果 alpha 或 beta 为 NULL，或者
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

stbsv(), dtbsv(), ctbsv(), ztbsv()

2.6.13. cublas<t>tpmv()

cublasStatus_t cublasStpmv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, const float           *AP,
                           float           *x, int incx)
cublasStatus_t cublasDtpmv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, const double          *AP,
                           double          *x, int incx)
cublasStatus_t cublasCtpmv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, const cuComplex       *AP,
                           cuComplex       *x, int incx)
cublasStatus_t cublasZtpmv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, const cuDoubleComplex *AP,
                           cuDoubleComplex *x, int incx)

此函数支持 64 位整数接口。

此函数执行三角压缩矩阵-向量乘法

此函数执行三角带状矩阵-向量乘法

其中 \(A\) 是以压缩格式存储的三角矩阵，\(\mathbf{x}\) 是向量。此外，对于矩阵 \(A\)

其中 \(A\) 是三角带状矩阵， \(\mathbf{x}\) 是向量。此外，对于矩阵 \(A\)

如果 uplo == CUBLAS_FILL_MODE_LOWER，则三角矩阵 \(A\) 的下三角部分中的元素按列无间隔地压缩在一起，因此元素 \(A(i,j)\) 存储在内存位置 AP[i+((2*n-j+1)*j)/2]，对于 \(j = 1,\ldots,n\) 和 \(i \geq j\) 。因此，压缩格式仅需要 \(\frac{n(n + 1)}{2}\) 个元素用于存储。

如果 uplo == CUBLAS_FILL_MODE_UPPER，则三角矩阵 \(A\) 的上三角部分中的元素按列无间隔地压缩在一起，因此元素 \(A(i,j)\) 存储在内存位置 AP[i+(j*(j+1))/2]，对于 \(A(i,j)\) 和 \(i \leq j\) 。因此，压缩格式仅需要 \(\frac{n(n + 1)}{2}\) 个元素用于存储。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 A 的下半部分还是上半部分被存储，另一部分不会被引用，而是从存储的元素中推断出来。
trans		输入	运算 op(A)，它是非转置或（共轭）转置。
diag		输入	指示矩阵 A 主对角线上的元素是否为单位元素且不应被访问。
n		输入	矩阵 A 的行数和列数。
矩阵 \(A\) 的行数和列数。	设备	输入	AP
x	设备	输入/输出	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 以压缩格式存储的 \(A\) 数组。 其中 \(A\) 是以压缩格式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 是向量， \(\alpha\) 是标量。 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 n < 0 或 k < 0，或者 如果 diag 不是 CUBLAS_DIAG_UNIT 和 CUBLAS_DIAG_NON_UNIT 之一
CUBLAS_STATUS_ALLOC_FAILED	内部暂存内存分配失败
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

stpmv(), dtpmv(), ctpmv(), ztpmv()

2.6.14. cublas<t>tpsv()

cublasStatus_t cublasStpsv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, const float           *AP,
                           float           *x, int incx)
cublasStatus_t cublasDtpsv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, const double          *AP,
                           double          *x, int incx)
cublasStatus_t cublasCtpsv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, const cuComplex       *AP,
                           cuComplex       *x, int incx)
cublasStatus_t cublasZtpsv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, const cuDoubleComplex *AP,
                           cuDoubleComplex *x, int incx)

此函数支持 64 位整数接口。

此函数求解具有单个右侧向量的压缩三角线性系统

\(\text{op}(A)\textbf{x} = \textbf{b}\)

其中 \(A\) 是以压缩格式存储的三角矩阵，\(\mathbf{x}\) 和 \(\mathbf{b}\) 是向量。此外，对于矩阵 \(A\)

其中 \(A\) 是三角带状矩阵， \(\mathbf{x}\) 是向量。此外，对于矩阵 \(A\)

解 \(\mathbf{x}\) 在退出时覆盖右侧向量 \(\mathbf{b}\)。

此函数中不包含对奇异性或近奇异性的测试。

如果 uplo == CUBLAS_FILL_MODE_LOWER，则三角矩阵 \(A\) 的下三角部分中的元素按列无间隔地压缩在一起，因此元素 \(A(i,j)\) 存储在内存位置 AP[i+((2*n-j+1)*j)/2]，对于 \(j = 1,\ldots,n\) 和 \(i \geq j\) 。因此，压缩格式仅需要 \(\frac{n(n + 1)}{2}\) 个元素用于存储。

如果 uplo == CUBLAS_FILL_MODE_UPPER，则三角矩阵 \(A\) 的上三角部分中的元素按列无间隔地压缩在一起，因此元素 \(A(i,j)\) 存储在内存位置 AP[i+(j*(j+1))/2]，对于 \(j = 1,\ldots,n\) 和 \(i \leq j\) 。因此，压缩格式仅需要 \(\frac{n(n + 1)}{2}\) 个元素用于存储。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 A 的下半部分还是上半部分被存储，另一部分不会被引用，而是从存储的元素中推断出来。
trans		输入	运算 op(A)，它是非转置或（共轭）转置。
diag		输入	指示矩阵主对角线上的元素是否为单位元素且不应被访问。
n		输入	矩阵 A 的行数和列数。
矩阵 \(A\) 的行数和列数。	设备	输入	AP
x	设备	输入/输出	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 以压缩格式存储的 \(A\) 数组。 其中 \(A\) 是以压缩格式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 是向量， \(\alpha\) 是标量。 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 n < 0 或 k < 0，或者 如果 diag 不是 CUBLAS_DIAG_UNIT 和 CUBLAS_DIAG_NON_UNIT 之一
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

stpsv(), dtpsv(), ctpsv(), ztpsv()

2.6.15. cublas<t>trmv()

cublasStatus_t cublasStrmv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, const float           *A, int lda,
                           float           *x, int incx)
cublasStatus_t cublasDtrmv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, const double          *A, int lda,
                           double          *x, int incx)
cublasStatus_t cublasCtrmv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, const cuComplex       *A, int lda,
                           cuComplex       *x, int incx)
cublasStatus_t cublasZtrmv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, const cuDoubleComplex *A, int lda,
                           cuDoubleComplex *x, int incx)

此函数支持 64 位整数接口。

此函数执行三角矩阵-向量乘法

此函数执行三角带状矩阵-向量乘法

其中 \(A\) 是以较低或较高模式存储的三角矩阵，可以包含或不包含主对角线，\(\mathbf{x}\) 是向量。此外，对于矩阵 \(A\)

其中 \(A\) 是三角带状矩阵， \(\mathbf{x}\) 是向量。此外，对于矩阵 \(A\)

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 A 的下半部分还是上半部分被存储，另一部分不会被引用，而是从存储的元素中推断出来。
trans		输入	运算 op(A)，它是非转置或（共轭）转置。
diag		输入	指示矩阵 A 主对角线上的元素是否为单位元素且不应被访问。
n		输入	矩阵 A 的行数和列数。
A	设备	输入	<type> 维度为 lda x n 的数组，其中 lda >= max(1, n)。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
x	设备	输入/输出	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 以压缩格式存储的 \(A\) 数组。 其中 \(A\) 是以压缩格式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 是向量， \(\alpha\) 是标量。 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 n < 0 或 k < 0，或者 如果 diag 不是 CUBLAS_DIAG_UNIT 和 CUBLAS_DIAG_NON_UNIT 之一，或者 <type> 维度为 lda x n 的数组，其中 lda >= max(1,n)。
CUBLAS_STATUS_ALLOC_FAILED	内部暂存内存分配失败
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

strmv(), dtrmv(), ctrmv(), ztrmv()

2.6.16. cublas<t>trsv()

cublasStatus_t cublasStrsv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, const float           *A, int lda,
                           float           *x, int incx)
cublasStatus_t cublasDtrsv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, const double          *A, int lda,
                           double          *x, int incx)
cublasStatus_t cublasCtrsv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, const cuComplex       *A, int lda,
                           cuComplex       *x, int incx)
cublasStatus_t cublasZtrsv(cublasHandle_t handle, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int n, const cuDoubleComplex *A, int lda,
                           cuDoubleComplex *x, int incx)

此函数支持 64 位整数接口。

此函数求解具有单个右侧向量的三角线性系统

\(\text{op}(A)\textbf{x} = \textbf{b}\)

其中 \(A\) 是以较低或较高模式存储的三角矩阵，可以包含或不包含主对角线，\(\mathbf{x}\) 和 \(\mathbf{b}\) 是向量。此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ A^{H} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

解 \(\mathbf{x}\) 在退出时覆盖右侧向量 \(\mathbf{b}\)。

此函数中不包含对奇异性或近奇异性的测试。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 A 的下半部分还是上半部分被存储，另一部分不会被引用，而是从存储的元素中推断出来。
trans		输入	运算 op(A)，它是非转置或（共轭）转置。
diag		输入	指示矩阵 A 主对角线上的元素是否为单位元素且不应被访问。
n		输入	矩阵 A 的行数和列数。
A	设备	输入	<type> 维度为 lda x n 的数组，其中 lda >= max(1, n)。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
x	设备	输入/输出	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 以压缩格式存储的 \(A\) 数组。 其中 \(A\) 是以压缩格式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 是向量， \(\alpha\) 是标量。 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 n < 0 或 k < 0，或者 如果 diag 不是 CUBLAS_DIAG_UNIT 和 CUBLAS_DIAG_NON_UNIT 之一，或者 <type> 维度为 lda x n 的数组，其中 lda >= max(1,n)。
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

strsv(), dtrsv(), ctrsv(), ztrsv()

2.6.17. cublas<t>hemv()

cublasStatus_t cublasChemv(cublasHandle_t handle, cublasFillMode_t uplo,
                           int n, const cuComplex       *alpha,
                           const cuComplex       *A, int lda,
                           const cuComplex       *x, int incx,
                           const cuComplex       *beta,
                           cuComplex       *y, int incy)
cublasStatus_t cublasZhemv(cublasHandle_t handle, cublasFillMode_t uplo,
                           int n, const cuDoubleComplex *alpha,
                           const cuDoubleComplex *A, int lda,
                           const cuDoubleComplex *x, int incx,
                           const cuDoubleComplex *beta,
                           cuDoubleComplex *y, int incy)

此函数支持 64 位整数接口。

此函数执行埃尔米特矩阵-向量乘法

\(\textbf{y} = \alpha A\textbf{x} + \beta\textbf{y}\)

其中 \(A\) 是一个 \(n \times n\) 埃尔米特矩阵，以较低或较高模式存储，\(\mathbf{x}\) 和 \(\mathbf{y}\) 是向量，\(\alpha\) 和 \(\beta\) 是标量。

此函数有一个使用原子操作的更快的替代实现，可以通过以下方式启用

有关原子操作用法的更多详细信息，请参见有关部分

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 A 的下半部分还是上半部分被存储，另一个埃尔米特部分不会被引用，而是从存储的元素中推断出来。
n		输入	矩阵 A 的行数和列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	<type> 维度为 lda x n 的数组，其中 lda >= max(1, n)。对角线元素的虚部被假定为零。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
x	设备	输入	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
beta	主机或设备	输入	<type> 用于乘法的标量。如果 beta == 0，则 y 不必是有效输入。
y	设备	输入/输出	<type> 带有 n 个元素的向量。
incy		输入	y 的连续元素之间的步幅。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 以压缩格式存储的 \(A\) 数组。 如果 incx == 0 或 incy == 0，或者 如果 uplo != CUBLAS_FILL_MODE_LOWER 且 uplo != CUBLAS_FILL_MODE_UPPER，或者 <type> 维度为 lda x n 的数组，其中 lda >= max(1, n)。
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

chemv(), zhemv()

2.6.18. cublas<t>hbmv()

cublasStatus_t cublasChbmv(cublasHandle_t handle, cublasFillMode_t uplo,
                          int n, int k, const cuComplex       *alpha,
                          const cuComplex       *A, int lda,
                          const cuComplex       *x, int incx,
                          const cuComplex       *beta,
                          cuComplex       *y, int incy)
cublasStatus_t cublasZhbmv(cublasHandle_t handle, cublasFillMode_t uplo,
                          int n, int k, const cuDoubleComplex *alpha,
                          const cuDoubleComplex *A, int lda,
                          const cuDoubleComplex *x, int incx,
                          const cuDoubleComplex *beta,
                          cuDoubleComplex *y, int incy)

此函数支持 64 位整数接口。

此函数执行埃尔米特带状矩阵-向量乘法

\(\textbf{y} = \alpha A\textbf{x} + \beta\textbf{y}\)

其中 \(A\) 是一个具有 \(k\) 条子对角线和超对角线的 \(n \times n\) 埃尔米特带状矩阵，\(\mathbf{x}\) 和 \(\mathbf{y}\) 是向量，\(\alpha\) 和 \(\beta\) 是标量。

如果 uplo == CUBLAS_FILL_MODE_LOWER，则埃尔米特带状矩阵 \(A\) 按列存储，矩阵的主对角线存储在第 1 行，第一条子对角线存储在第 2 行（从第一个位置开始），第二条子对角线存储在第 3 行（从第一个位置开始），依此类推。因此，通常元素 \(A(i,j)\) 存储在内存位置 A(1+i-j,j)，对于 \(j = 1,\ldots,n\) 和 \(i \in \lbrack j,\min(m,j + k)\rbrack\) 。此外，数组 A 中概念上不对应于带状矩阵中元素的元素（右下角 \(k \times k\) 三角形）不会被引用。

如果 uplo == CUBLAS_FILL_MODE_UPPER，则埃尔米特带状矩阵 \(A\) 按列存储，矩阵的主对角线存储在第 k + 1 行，第一条超对角线存储在第 k 行（从第二个位置开始），第二条超对角线存储在第 k-1 行（从第三个位置开始），依此类推。因此，通常元素 \(A(i,j)\) 存储在内存位置 A(1+k+i-j,j)，对于 \(j = 1,\ldots,n\) 和 \(i \in \lbrack\max(1,j - k),j\rbrack\) 。此外，数组 A 中概念上不对应于带状矩阵中元素的元素（左上角 \(k \times k\) 三角形）不会被引用。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 A 的下半部分还是上半部分被存储，另一个埃尔米特部分不会被引用，而是从存储的元素中推断出来。
n		输入	矩阵 A 的行数和列数。
k		输入	矩阵 A 的子对角线和超对角线的数量。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	<type> 维度为 lda x n 的数组，其中 lda >= k + 1。对角线元素的虚部被假定为零。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
x	设备	输入	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
beta	主机或设备	输入	<type> 用于乘法的标量。如果 beta == 0，则不必是有效输入。
y	设备	输入/输出	<type> 带有 n 个元素的向量。
incy		输入	y 的连续元素之间的步幅。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 维度为 lda x n 的数组，其中 lda >= k + 1。 如果 incx == 0 或 incy == 0，或者 如果 n < 0 或 k < 0，或者 如果 lda < (1 + k)，或者 如果 alpha 或 beta 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

chbmv(), zhbmv()

2.6.19. cublas<t>hpmv()

cublasStatus_t cublasChpmv(cublasHandle_t handle, cublasFillMode_t uplo,
                           int n, const cuComplex       *alpha,
                           const cuComplex       *AP,
                           const cuComplex       *x, int incx,
                           const cuComplex       *beta,
                           cuComplex       *y, int incy)
cublasStatus_t cublasZhpmv(cublasHandle_t handle, cublasFillMode_t uplo,
                           int n, const cuDoubleComplex *alpha,
                           const cuDoubleComplex *AP,
                           const cuDoubleComplex *x, int incx,
                           const cuDoubleComplex *beta,
                           cuDoubleComplex *y, int incy)

此函数支持 64 位整数接口。

此函数执行埃尔米特压缩矩阵-向量乘法

\(\textbf{y} = \alpha A\textbf{x} + \beta\textbf{y}\)

其中 \(A\) 是一个 \(n \times n\) 以压缩格式存储的埃尔米特矩阵，\(\mathbf{x}\) 和 \(\mathbf{y}\) 是向量，\(\alpha\) 和 \(\beta\) 是标量。

如果 uplo == CUBLAS_FILL_MODE_LOWER，则埃尔米特矩阵 \(A\) 的下三角部分中的元素按列无间隔地压缩在一起，因此元素 \(A(i,j)\) 存储在内存位置 AP[i+((2*n-j+1)*j)/2]，对于 \(j = 1,\ldots,n\) 和 \(i \geq j\) 。因此，压缩格式仅需要 \(\frac{n(n + 1)}{2}\) 个元素用于存储。

如果 uplo == CUBLAS_FILL_MODE_UPPER，则埃尔米特矩阵 \(A\) 的上三角部分中的元素按列无间隔地压缩在一起，因此元素 \(A(i,j)\) 存储在内存位置 AP[i+(j*(j+1))/2]，对于 \(j = 1,\ldots,n\) 和 \(i \leq j\) 。因此，压缩格式仅需要 \(\frac{n(n + 1)}{2}\) 个元素用于存储。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 A 的下半部分还是上半部分被存储，另一个埃尔米特部分不会被引用，而是从存储的元素中推断出来。
n		输入	矩阵 A 的行数和列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
矩阵 \(A\) 的行数和列数。	设备	输入	<type> 以压缩格式存储 \(A\) 的数组。对角线元素的虚部被假定为零。
x	设备	输入	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
beta	主机或设备	输入	<type> 用于乘法的标量。如果 beta == 0，则 y 不必是有效输入。
y	设备	输入/输出	<type> 带有 n 个元素的向量。
incy		输入	y 的连续元素之间的步幅。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 以压缩格式存储的 \(A\) 数组。 如果 incx == 0 或 incy == 0，或者 如果 uplo != CUBLAS_FILL_MODE_LOWER 且 uplo != CUBLAS_FILL_MODE_UPPER，或者 如果 alpha 或 beta 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

chpmv(), zhpmv()

2.6.20. cublas<t>her()

cublasStatus_t cublasCher(cublasHandle_t handle, cublasFillMode_t uplo,
                          int n, const float  *alpha,
                          const cuComplex       *x, int incx,
                          cuComplex       *A, int lda)
cublasStatus_t cublasZher(cublasHandle_t handle, cublasFillMode_t uplo,
                          int n, const double *alpha,
                          const cuDoubleComplex *x, int incx,
                          cuDoubleComplex *A, int lda)

此函数支持 64 位整数接口。

此函数执行埃尔米特秩 1 更新

\(A = \alpha\textbf{x}\textbf{x}^{H} + A\)

其中 \(A\) 是一个以列优先格式存储的 \(n \times n\) 埃尔米特矩阵，\(\mathbf{x}\) 是向量，\(\alpha\) 是标量。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 A 的下半部分还是上半部分被存储，另一个埃尔米特部分不会被引用，而是从存储的元素中推断出来。
n		输入	矩阵 A 的行数和列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
x	设备	输入	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
A	设备	输入/输出	<type> 维度为 lda x n 的数组，其中 lda >= max(1, n)。对角线元素的虚部被假定并设置为零。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 以压缩格式存储的 \(A\) 数组。 其中 \(A\) 是以压缩格式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 是向量， \(\alpha\) 是标量。 如果 n < 0 或 k < 0，或者 <type> 维度为 lda x n 的数组，其中 lda >= max(1, n)。 如果 incx == 0，或者
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

cher(), zher()

2.6.21. cublas<t>her2()

cublasStatus_t cublasCher2(cublasHandle_t handle, cublasFillMode_t uplo,
                           int n, const cuComplex       *alpha,
                           const cuComplex       *x, int incx,
                           const cuComplex       *y, int incy,
                           cuComplex       *A, int lda)
cublasStatus_t cublasZher2(cublasHandle_t handle, cublasFillMode_t uplo,
                           int n, const cuDoubleComplex *alpha,
                           const cuDoubleComplex *x, int incx,
                           const cuDoubleComplex *y, int incy,
                           cuDoubleComplex *A, int lda)

此函数支持 64 位整数接口。

此函数执行埃尔米特秩 2 更新

\(A = \alpha\textbf{x}\textbf{y}^{H} + \overset{ˉ}{\alpha}\textbf{y}\textbf{x}^{H} + A\)

其中 \(A\) 是一个以列优先格式存储的 \(n \times n\) 埃尔米特矩阵，\(\mathbf{x}\) 和 \(\mathbf{y}\) 是向量，\(\alpha\) 是标量。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 A 的下半部分还是上半部分被存储，另一个埃尔米特部分不会被引用，而是从存储的元素中推断出来。
n		输入	矩阵 A 的行数和列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
x	设备	输入	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
y	设备	输入	<type> 带有 n 个元素的向量。
incy		输入	y 的连续元素之间的步幅。
A	设备	输入/输出	<type> 维度为 lda x n 的数组，其中 lda >= max(1, n)。对角线元素的虚部被假定并设置为零。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 以压缩格式存储的 \(A\) 数组。 其中 \(A\) 是以压缩格式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 是向量， \(\alpha\) 是标量。 如果 n < 0 或 k < 0，或者 <type> 维度为 lda x n 的数组，其中 lda >= max(1, n)。 如果 incx == 0，或者
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

cher2(), zher2()

2.6.22. cublas<t>hpr()

cublasStatus_t cublasChpr(cublasHandle_t handle, cublasFillMode_t uplo,
                          int n, const float *alpha,
                          const cuComplex       *x, int incx,
                          cuComplex       *AP)
cublasStatus_t cublasZhpr(cublasHandle_t handle, cublasFillMode_t uplo,
                          int n, const double *alpha,
                          const cuDoubleComplex *x, int incx,
                          cuDoubleComplex *AP)

此函数支持 64 位整数接口。

此函数执行压缩埃尔米特秩 1 更新

\(A = \alpha\textbf{x}\textbf{x}^{H} + A\)

其中 \(A\) 是一个以压缩格式存储的 \(n \times n\) 埃尔米特矩阵，\(\mathbf{x}\) 是向量，\(\alpha\) 是标量。

如果 uplo == CUBLAS_FILL_MODE_LOWER，则埃尔米特矩阵 \(A\) 的下三角部分中的元素按列无间隔地压缩在一起，因此元素 \(A(i,j)\) 存储在内存位置 AP[i+((2*n-j+1)*j)/2]，对于 \(j = 1,\ldots,n\) 和 \(i \geq j\) 。因此，压缩格式仅需要 \(\frac{n(n + 1)}{2}\) 个元素用于存储。

如果 uplo == CUBLAS_FILL_MODE_UPPER，则埃尔米特矩阵 \(A\) 的上三角部分中的元素按列无间隔地压缩在一起，因此元素 \(A(i,j)\) 存储在内存位置 AP[i+(j*(j+1))/2]，对于 \(j = 1,\ldots,n\) 和 \(i \leq j\) 。因此，压缩格式仅需要 \(\frac{n(n + 1)}{2}\) 个元素用于存储。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 A 的下半部分还是上半部分被存储，另一个埃尔米特部分不会被引用，而是从存储的元素中推断出来。
n		输入	矩阵 A 的行数和列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
x	设备	输入	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
矩阵 \(A\) 的行数和列数。	设备	输入/输出	<type> 以压缩格式存储 \(A\) 的数组。对角线元素的虚部被假定并设置为零。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 以压缩格式存储的 \(A\) 数组。 其中 \(A\) 是以压缩格式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 是向量， \(\alpha\) 是标量。 如果 n < 0 或 k < 0，或者 如果 incx == 0，或者
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

chpr(), zhpr()

2.6.23. cublas<t>hpr2()

cublasStatus_t cublasChpr2(cublasHandle_t handle, cublasFillMode_t uplo,
                           int n, const cuComplex       *alpha,
                           const cuComplex       *x, int incx,
                           const cuComplex       *y, int incy,
                           cuComplex       *AP)
cublasStatus_t cublasZhpr2(cublasHandle_t handle, cublasFillMode_t uplo,
                           int n, const cuDoubleComplex *alpha,
                           const cuDoubleComplex *x, int incx,
                           const cuDoubleComplex *y, int incy,
                           cuDoubleComplex *AP)

此函数支持 64 位整数接口。

此函数执行压缩埃尔米特秩 2 更新

\(A = \alpha\textbf{x}\textbf{y}^{H} + \overset{ˉ}{\alpha}\textbf{y}\textbf{x}^{H} + A\)

其中 \(A\) 是一个以压缩格式存储的 \(n \times n\) 埃尔米特矩阵，\(\mathbf{x}\) 和 \(\mathbf{y}\) 是向量，\(\alpha\) 是标量。

如果 uplo == CUBLAS_FILL_MODE_LOWER，则埃尔米特矩阵 \(A\) 的下三角部分中的元素按列无间隔地压缩在一起，因此元素 \(A(i,j)\) 存储在内存位置 AP[i+((2*n-j+1)*j)/2]，对于 \(j = 1,\ldots,n\) 和 \(i \geq j\) 。因此，压缩格式仅需要 \(\frac{n(n + 1)}{2}\) 个元素用于存储。

如果 uplo == CUBLAS_FILL_MODE_UPPER，则埃尔米特矩阵 \(A\) 的上三角部分中的元素按列无间隔地压缩在一起，因此元素 \(A(i,j)\) 存储在内存位置 AP[i+(j*(j+1))/2]，对于 \(j = 1,\ldots,n\) 和 \(i \leq j\) 。因此，压缩格式仅需要 \(\frac{n(n + 1)}{2}\) 个元素用于存储。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 A 的下半部分还是上半部分被存储，另一个埃尔米特部分不会被引用，而是从存储的元素中推断出来。
n		输入	矩阵 A 的行数和列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
x	设备	输入	<type> 带有 n 个元素的向量。
incx		输入	x 的连续元素之间的步幅。
y	设备	输入	<type> 带有 n 个元素的向量。
incy		输入	y 的连续元素之间的步幅。
矩阵 \(A\) 的行数和列数。	设备	输入/输出	<type> 以压缩格式存储 \(A\) 的数组。对角线元素的虚部被假定并设置为零。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 以压缩格式存储的 \(A\) 数组。 其中 \(A\) 是以压缩格式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 是向量， \(\alpha\) 是标量。 如果 n < 0 或 k < 0，或者 如果 incx == 0，或者
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

chpr2, zhpr2

2.6.24. cublas<t>gemvBatched()

cublasStatus_t cublasSgemvBatched(cublasHandle_t handle, cublasOperation_t trans,
                                  int m, int n,
                                  const float           *alpha,
                                  const float           *const Aarray[], int lda,
                                  const float           *const xarray[], int incx,
                                  const float           *beta,
                                  float           *const yarray[], int incy,
                                  int batchCount)
cublasStatus_t cublasDgemvBatched(cublasHandle_t handle, cublasOperation_t trans,
                                  int m, int n,
                                  const double          *alpha,
                                  const double          *const Aarray[], int lda,
                                  const double          *const xarray[], int incx,
                                  const double          *beta,
                                  double          *const yarray[], int incy,
                                  int batchCount)
cublasStatus_t cublasCgemvBatched(cublasHandle_t handle, cublasOperation_t trans,
                                  int m, int n,
                                  const cuComplex       *alpha,
                                  const cuComplex       *const Aarray[], int lda,
                                  const cuComplex       *const xarray[], int incx,
                                  const cuComplex       *beta,
                                  cuComplex       *const yarray[], int incy,
                                  int batchCount)
cublasStatus_t cublasZgemvBatched(cublasHandle_t handle, cublasOperation_t trans,
                                  int m, int n,
                                  const cuDoubleComplex *alpha,
                                  const cuDoubleComplex *const Aarray[], int lda,
                                  const cuDoubleComplex *const xarray[], int incx,
                                  const cuDoubleComplex *beta,
                                  cuDoubleComplex *const yarray[], int incy,
                                  int batchCount)

#if defined(__cplusplus)
cublasStatus_t cublasHSHgemvBatched(cublasHandle_t handle, cublasOperation_t trans,
                                    int m, int n,
                                    const float           *alpha,
                                    const __half          *const Aarray[], int lda,
                                    const __half          *const xarray[], int incx,
                                    const float           *beta,
                                    __half                *const yarray[], int incy,
                                    int batchCount)
cublasStatus_t cublasHSSgemvBatched(cublasHandle_t handle, cublasOperation_t trans,
                                    int m, int n,
                                    const float           *alpha,
                                    const __half          *const Aarray[], int lda,
                                    const __half          *const xarray[], int incx,
                                    const float           *beta,
                                    float                 *const yarray[], int incy,
                                    int batchCount)
cublasStatus_t cublasTSTgemvBatched(cublasHandle_t handle, cublasOperation_t trans,
                                    int m, int n,
                                    const float           *alpha,
                                    const __nv_bfloat16   *const Aarray[], int lda,
                                    const __nv_bfloat16   *const xarray[], int incx,
                                    const float           *beta,
                                    __nv_bfloat16         *const yarray[], int incy,
                                    int batchCount)
cublasStatus_t cublasTSSgemvBatched(cublasHandle_t handle, cublasOperation_t trans,
                                    int m, int n,
                                    const float           *alpha,
                                    const __nv_bfloat16   *const Aarray[], int lda,
                                    const __nv_bfloat16   *const xarray[], int incx,
                                    const float           *beta,
                                    float                 *const yarray[], int incy,
                                    int batchCount)
#endif

此函数支持 64 位整数接口。

此函数执行一批矩阵和向量的矩阵-向量乘法。该批次被认为是“统一的”，即所有实例对于各自的 A 矩阵、x 和 y 向量都具有相同的维度 (m, n)、前导维度 (lda)、增量 (incx, incy) 和转置 (trans)。批次中每个实例的输入矩阵和向量以及输出向量的地址从调用者传递给函数的指针数组中读取。

\(\textbf{y}\lbrack i\rbrack = \alpha\text{op}(A\lbrack i\rbrack)\textbf{x}\lbrack i\rbrack + \beta\textbf{y}\lbrack i\rbrack,\text{ 对于 i} \in \lbrack 0,batchCount - 1\rbrack\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(A\) 是指向以列优先格式存储的维度为 \(m \times n\) 的矩阵 \(A\lbrack i\rbrack\) 的指针数组，\(\textbf{x}\) 和 \(\textbf{y}\) 是指向向量的指针数组。此外，对于矩阵 \(A\lbrack i\rbrack\) ，

\(\text{op}(A\lbrack i\rbrack) = \left\{ \begin{matrix} {A\lbrack i\rbrack} & {\text{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A\lbrack i\rbrack}^{T} & {\text{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_T}$}} \\ {A\lbrack i\rbrack}^{H} & {\text{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

注意

\(\textbf{y}\lbrack i\rbrack\) 向量不得重叠，即各个 gemv 操作必须可以独立计算；否则，将出现未定义的行为。

在某些问题规模下，多次调用不同 CUDA 流中的 cublas<t>gemv() 可能比使用此 API 更有优势。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
trans		输入	运算 op(A[i]) 是非转置或（共轭）转置。
m		输入	矩阵 A[i] 的行数。
n		输入	矩阵 A[i] 的列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
Aarray	设备	输入	指向 <type> 数组的指针数组，每个数组的维度为 lda x n，其中 lda >= max(1, m)。 所有指针都必须满足某些对齐标准。请参阅下文了解详细信息。
lda		输入	用于存储每个矩阵 A[i] 的二维数组的前导维度。
xarray	设备	输入	指向 <type> 数组的指针数组，如果 trans==CUBLAS_OP_N，则每个数组的维度为 n，否则为 m。 所有指针都必须满足某些对齐标准。请参阅下文了解详细信息。
incx		输入	每个一维数组 x[i] 的步幅。
beta	主机或设备	输入	<type> 用于乘法的标量。如果 beta == 0，则 y 不必是有效输入。
yarray	设备	输入/输出	指向 <type> 数组的指针数组。如果 trans==CUBLAS_OP_N，则其维度为 m，否则为 n。向量 y[i] 不应重叠；否则，将出现未定义的行为。 所有指针都必须满足某些对齐标准。请参阅下文了解详细信息。
incy		输入	每个一维数组 y[i] 的步幅。
batchCount		输入	Aarray、xarray 和 yarray 中包含的指针数量。

如果数学模式在使用 cublasSgemvBatched() 时启用快速数学模式，则放置在 GPU 内存中的指针（而非指针数组）必须正确对齐，以避免未对齐的内存访问错误。理想情况下，所有指针都至少对齐到 18 字节。否则，建议它们满足以下规则

• 如果 k % 4==0，则确保 intptr_t(ptr) % 16 == 0，

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	m < 0、n < 0 或 batchCount < 0
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

2.6.25. cublas<t>gemvStridedBatched()

cublasStatus_t cublasSgemvStridedBatched(cublasHandle_t handle,
                                         cublasOperation_t trans,
                                         int m, int n,
                                         const float           *alpha,
                                         const float           *A, int lda,
                                         long long int         strideA,
                                         const float           *x, int incx,
                                         long long int         stridex,
                                         const float           *beta,
                                         float                 *y, int incy,
                                         long long int         stridey,
                                         int batchCount)
cublasStatus_t cublasDgemvStridedBatched(cublasHandle_t handle,
                                         cublasOperation_t trans,
                                         int m, int n,
                                         const double          *alpha,
                                         const double          *A, int lda,
                                         long long int         strideA,
                                         const double          *x, int incx,
                                         long long int         stridex,
                                         const double          *beta,
                                         double                *y, int incy,
                                         long long int         stridey,
                                         int batchCount)
cublasStatus_t cublasCgemvStridedBatched(cublasHandle_t handle,
                                         cublasOperation_t trans,
                                         int m, int n,
                                         const cuComplex       *alpha,
                                         const cuComplex       *A, int lda,
                                         long long int         strideA,
                                         const cuComplex       *x, int incx,
                                         long long int         stridex,
                                         const cuComplex       *beta,
                                         cuComplex             *y, int incy,
                                         long long int         stridey,
                                         int batchCount)
cublasStatus_t cublasZgemvStridedBatched(cublasHandle_t handle,
                                         cublasOperation_t trans,
                                         int m, int n,
                                         const cuDoubleComplex *alpha,
                                         const cuDoubleComplex *A, int lda,
                                         long long int         strideA,
                                         const cuDoubleComplex *x, int incx,
                                         long long int         stridex,
                                         const cuDoubleComplex *beta,
                                         cuDoubleComplex       *y, int incy,
                                         long long int         stridey,
                                         int batchCount)
cublasStatus_t cublasHSHgemvStridedBatched(cublasHandle_t handle,
                                           cublasOperation_t trans,
                                           int m, int n,
                                           const float           *alpha,
                                           const __half          *A, int lda,
                                           long long int         strideA,
                                           const __half          *x, int incx,
                                           long long int         stridex,
                                           const float           *beta,
                                           __half                *y, int incy,
                                           long long int         stridey,
                                           int batchCount)
cublasStatus_t cublasHSSgemvStridedBatched(cublasHandle_t handle,
                                           cublasOperation_t trans,
                                           int m, int n,
                                           const float           *alpha,
                                           const __half          *A, int lda,
                                           long long int         strideA,
                                           const __half          *x, int incx,
                                           long long int         stridex,
                                           const float           *beta,
                                           float                 *y, int incy,
                                           long long int         stridey,
                                           int batchCount)
cublasStatus_t cublasTSTgemvStridedBatched(cublasHandle_t handle,
                                           cublasOperation_t trans,
                                           int m, int n,
                                           const float           *alpha,
                                           const __nv_bfloat16   *A, int lda,
                                           long long int         strideA,
                                           const __nv_bfloat16   *x, int incx,
                                           long long int         stridex,
                                           const float           *beta,
                                           __nv_bfloat16         *y, int incy,
                                           long long int         stridey,
                                           int batchCount)
cublasStatus_t cublasTSSgemvStridedBatched(cublasHandle_t handle,
                                           cublasOperation_t trans,
                                           int m, int n,
                                           const float           *alpha,
                                           const __nv_bfloat16   *A, int lda,
                                           long long int         strideA,
                                           const __nv_bfloat16   *x, int incx,
                                           long long int         stridex,
                                           const float           *beta,
                                           float                 *y, int incy,
                                           long long int         stridey,
                                           int batchCount)

此函数支持 64 位整数接口。

此函数执行一批矩阵和向量的矩阵-向量乘法。该批次被认为是“统一的”，即所有实例对于各自的 A 矩阵、x 和 y 向量都具有相同的维度 (m, n)、前导维度 (lda)、增量 (incx, incy) 和转置 (trans)。批次中每个实例的输入矩阵 A 和向量 x 以及输出向量 y 位于距先前实例中位置的固定元素偏移量处。第一个实例的 A 矩阵、x 和 y 向量的指针与元素数量偏移量（strideA、stridex 和 stridey）一起传递给函数，这些偏移量确定了未来实例中输入矩阵和向量以及输出向量的位置。

\(\textbf{y} + i*{stridey} = \alpha\text{op}(A + i*{strideA})(\textbf{x} + i*{stridex}) + \beta(\textbf{y} + i*{stridey}),\text{ 对于 i } \in \lbrack 0,batchCount - 1\rbrack\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(A\) 是指向以列优先格式存储的矩阵的指针数组，维度为 \(A\lbrack i\rbrack\) \(m \times n\) ，\(\textbf{x}\) 和 \(\textbf{y}\) 是指向向量的指针数组。此外，对于矩阵 \(A\lbrack i\rbrack\)

\(\text{op}(A\lbrack i\rbrack) = \left\{ \begin{matrix} {A\lbrack i\rbrack} & {\text{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A\lbrack i\rbrack}^{T} & {\text{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_T}$}} \\ {A\lbrack i\rbrack}^{H} & {\text{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

注意

\(\textbf{y}\lbrack i\rbrack\) 矩阵不得重叠，即各个 gemv 操作必须可以独立计算；否则，将出现未定义的行为。

在某些问题规模下，多次调用不同 CUDA 流中的 cublas<t>gemv() 可能比使用此 API 更有优势。

注意

在下表中，我们使用 A[i], x[i], y[i] 作为符号表示批次中第 i 个实例中的 A 矩阵以及 x 和 y 向量，隐含地假设它们分别是距 A[i-1], x[i-1], y[i-1] 的元素数量偏移量 strideA, stridex, stridey。偏移量的单位是元素数量，并且不得为零。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
trans		输入	运算 op(A[i]) 是非转置或（共轭）转置。
m		输入	矩阵 A[i] 的行数。
n		输入	矩阵 A[i] 的列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	<type>* 指向与批次的第一个实例相对应的 A 矩阵的指针，维度为 lda x n，其中 lda >= max(1, m)。
lda		输入	用于存储每个矩阵 A[i] 的二维数组的前导维度。
strideA		输入	类型为 long long int 的值，给出了 A[i] 和 A[i+1] 之间元素数量的偏移量
x	设备	输入	<type>* 指向与批次的第一个实例相对应的 x 向量的指针，如果 trans==CUBLAS_OP_N，则每个向量的维度为 n，否则为 m。
incx		输入	每个一维数组 x[i] 的步幅。
stridex		输入	类型为 long long int 的值，给出了 x[i] 和 x[i+1] 之间元素数量的偏移量
beta	主机或设备	输入	<type> 用于乘法的标量。如果 beta == 0，则 y 不必是有效输入。
y	设备	输入/输出	<type>* 指向与批处理中第一个实例对应的 y 向量的指针，如果 trans==CUBLAS_OP_N，则每个维度为 m；否则为 n。 向量 y[i] 不应重叠；否则，会产生未定义的行为。
incy		输入	每个一维数组 y[i] 的步长。
stridey		输入	类型为 long long int 的值，表示 y[i] 和 y[i+1] 之间元素数量的偏移量。
batchCount		输入	批处理中要执行的 GEMV 数量。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	m < 0、n < 0 或 batchCount < 0
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

2.7. cuBLAS Level-3 函数参考

本章介绍执行矩阵-矩阵运算的 Level-3 基本线性代数子程序 (BLAS3) 函数。

2.7.1. cublas<t>gemm()

cublasStatus_t cublasSgemm(cublasHandle_t handle,
                           cublasOperation_t transa, cublasOperation_t transb,
                           int m, int n, int k,
                           const float           *alpha,
                           const float           *A, int lda,
                           const float           *B, int ldb,
                           const float           *beta,
                           float           *C, int ldc)
cublasStatus_t cublasDgemm(cublasHandle_t handle,
                           cublasOperation_t transa, cublasOperation_t transb,
                           int m, int n, int k,
                           const double          *alpha,
                           const double          *A, int lda,
                           const double          *B, int ldb,
                           const double          *beta,
                           double          *C, int ldc)
cublasStatus_t cublasCgemm(cublasHandle_t handle,
                           cublasOperation_t transa, cublasOperation_t transb,
                           int m, int n, int k,
                           const cuComplex       *alpha,
                           const cuComplex       *A, int lda,
                           const cuComplex       *B, int ldb,
                           const cuComplex       *beta,
                           cuComplex       *C, int ldc)
cublasStatus_t cublasZgemm(cublasHandle_t handle,
                           cublasOperation_t transa, cublasOperation_t transb,
                           int m, int n, int k,
                           const cuDoubleComplex *alpha,
                           const cuDoubleComplex *A, int lda,
                           const cuDoubleComplex *B, int ldb,
                           const cuDoubleComplex *beta,
                           cuDoubleComplex *C, int ldc)
cublasStatus_t cublasHgemm(cublasHandle_t handle,
                           cublasOperation_t transa, cublasOperation_t transb,
                           int m, int n, int k,
                           const __half *alpha,
                           const __half *A, int lda,
                           const __half *B, int ldb,
                           const __half *beta,
                           __half *C, int ldc)

此函数支持 64 位整数接口。

此函数执行矩阵-矩阵乘法

\(C = \alpha\text{op}(A)\text{op}(B) + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(A\) 、 \(B\) 和 \(C\) 是以列优先格式存储的矩阵，其维度分别为 \(\text{op}(A)\) \(m \times k\) 、 \(\text{op}(B)\) \(k \times n\) 和 \(C\) \(m \times n\) 。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ A^{H} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

并且对于矩阵 \(B\) ，\(\text{op}(B)\) 的定义类似。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
transa		输入	运算 op(A)，它是非转置或（共轭）转置。
transb		输入	运算 op(B) 是非转置或（共轭）转置。
m		输入	矩阵 op(A) 和 C 的行数。
n		输入	矩阵 op(B) 和 C 的列数。
k		输入	op(A) 的列数和 op(B) 的行数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	维度为 lda x k 的 <type> 数组，如果 transa == CUBLAS_OP_N，则 lda >= max(1, m)；如果不是，则维度为 lda x m，且 lda >= max(1, k)。
lda		输入	用于存储矩阵 A 的二维数组的Leading Dimension（主导维度）。
B	设备	输入	维度为 ldb x n 的 <type> 数组，如果 transb == CUBLAS_OP_N，则 ldb >= max(1, k)；如果不是，则维度为 ldb x k，且 ldb>=max(1,n)。
ldb		输入	用于存储矩阵 B 的二维数组的 Leading Dimension（主导维度）。
beta	主机或设备	输入	用于乘法的 <type> 标量值。 如果 beta == 0，则 C 不必是有效的输入。
C	设备	输入/输出	维度为 ldc x n 的 <type> 数组，且 ldc >= max(1, m)。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0 或 n < 0 或 k < 0，或者 如果 transa 和 transb 不是 CUBLAS_OP_N、 CUBLAS_OP_C、 CUBLAS_OP_T 之一，或者 如果当 transa == CUBLAS_OP_N 时 lda < max(1, m)，否则当 transa 不是 CUBLAS_OP_N 时 lda < max(1, k)，或者 如果当 transb == CUBLAS_OP_N 时 ldb < max(1, k)，否则当 transb 不是 CUBLAS_OP_N 时 ldb < max(1, n)，或者 如果 ldc < max(1, m)，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 和 CUBLAS_FILL_MODE_UPPER 之一，或者 如果当 beta 非零时 C 为 NULL
CUBLAS_STATUS_ARCH_MISMATCH	在 cublasHgemm() 的情况下，设备不支持半精度数学运算。
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

sgemm(), dgemm(), cgemm(), zgemm()

2.7.2. cublas<t>gemm3m()

cublasStatus_t cublasCgemm3m(cublasHandle_t handle,
                           cublasOperation_t transa, cublasOperation_t transb,
                           int m, int n, int k,
                           const cuComplex       *alpha,
                           const cuComplex       *A, int lda,
                           const cuComplex       *B, int ldb,
                           const cuComplex       *beta,
                           cuComplex       *C, int ldc)
cublasStatus_t cublasZgemm3m(cublasHandle_t handle,
                           cublasOperation_t transa, cublasOperation_t transb,
                           int m, int n, int k,
                           const cuDoubleComplex *alpha,
                           const cuDoubleComplex *A, int lda,
                           const cuDoubleComplex *B, int ldb,
                           const cuDoubleComplex *beta,
                           cuDoubleComplex *C, int ldc)

此函数支持 64 位整数接口。

此函数执行复数矩阵-矩阵乘法，使用高斯复杂度降低算法。 这可以使性能提高高达 25%。

\(C = \alpha\text{op}(A)\text{op}(B) + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(A\) 、 \(B\) 和 \(C\) 是以列优先格式存储的矩阵，其维度分别为 \(\text{op}(A)\) \(m \times k\) 、 \(\text{op}(B)\) \(k \times n\) 和 \(C\) \(m \times n\) 。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ A^{H} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

并且对于矩阵 \(B\) ，\(\text{op}(B)\) 的定义类似。

注意

这两个例程仅在架构能力等于或大于 5.0 的 GPU 上受支持。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
transa		输入	运算 op(A)，它是非转置或（共轭）转置。
transb		输入	运算 op(B) 是非转置或（共轭）转置。
m		输入	矩阵 op(A) 和 C 的行数。
n		输入	矩阵 op(B) 和 C 的列数。
k		输入	op(A) 的列数和 op(B) 的行数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	维度为 lda x k 的 <type> 数组，如果 transa == CUBLAS_OP_N，则 lda >= max(1, m)；如果不是，则维度为 lda x m，且 lda >= max(1, k)。
lda		输入	用于存储矩阵 A 的二维数组的Leading Dimension（主导维度）。
B	设备	输入	维度为 ldb x n 的 <type> 数组，如果 transb == CUBLAS_OP_N，则 ldb >= max(1, k)；如果不是，则维度为 ldb x k，且 ldb>=max(1,n)。
ldb		输入	用于存储矩阵 B 的二维数组的 Leading Dimension（主导维度）。
beta	主机或设备	输入	用于乘法的 <type> 标量值。 如果 beta == 0，则 C 不必是有效的输入。
C	设备	输入/输出	维度为 ldc x n 的 <type> 数组，且 ldc >= max(1, m)。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。

下表列出了此函数可能返回的错误值及其含义

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成。
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化。
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0 或 n < 0 或 k < 0，或者 如果 transa 和 transb 不是 CUBLAS_OP_N、 CUBLAS_OP_C、 CUBLAS_OP_T 之一，或者 如果当 transa == CUBLAS_OP_N 时 lda < max(1, m)，否则当 transa 不是 CUBLAS_OP_N 时 lda < max(1, k)，或者 如果当 transb == CUBLAS_OP_N 时 ldb < max(1, k)，否则当 transb 不是 CUBLAS_OP_N 时 ldb < max(1, n)，或者 如果 ldc < max(1, m)，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 和 CUBLAS_FILL_MODE_UPPER 之一，或者 如果当 beta 非零时 C 为 NULL
CUBLAS_STATUS_ARCH_MISMATCH	设备计算能力低于 5.0。
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动。

有关参考，请参阅 NETLIB 文档

cgemm(), zgemm()

2.7.3. cublas<t>gemmBatched()

cublasStatus_t cublasHgemmBatched(cublasHandle_t handle,
                                  cublasOperation_t transa,
                                  cublasOperation_t transb,
                                  int m, int n, int k,
                                  const __half          *alpha,
                                  const __half          *const Aarray[], int lda,
                                  const __half          *const Barray[], int ldb,
                                  const __half          *beta,
                                  __half          *const Carray[], int ldc,
                                  int batchCount)
cublasStatus_t cublasSgemmBatched(cublasHandle_t handle,
                                  cublasOperation_t transa,
                                  cublasOperation_t transb,
                                  int m, int n, int k,
                                  const float           *alpha,
                                  const float           *const Aarray[], int lda,
                                  const float           *const Barray[], int ldb,
                                  const float           *beta,
                                  float           *const Carray[], int ldc,
                                  int batchCount)
cublasStatus_t cublasDgemmBatched(cublasHandle_t handle,
                                  cublasOperation_t transa,
                                  cublasOperation_t transb,
                                  int m, int n, int k,
                                  const double          *alpha,
                                  const double          *const Aarray[], int lda,
                                  const double          *const Barray[], int ldb,
                                  const double          *beta,
                                  double          *const Carray[], int ldc,
                                  int batchCount)
cublasStatus_t cublasCgemmBatched(cublasHandle_t handle,
                                  cublasOperation_t transa,
                                  cublasOperation_t transb,
                                  int m, int n, int k,
                                  const cuComplex       *alpha,
                                  const cuComplex       *const Aarray[], int lda,
                                  const cuComplex       *const Barray[], int ldb,
                                  const cuComplex       *beta,
                                  cuComplex       *const Carray[], int ldc,
                                  int batchCount)
cublasStatus_t cublasZgemmBatched(cublasHandle_t handle,
                                  cublasOperation_t transa,
                                  cublasOperation_t transb,
                                  int m, int n, int k,
                                  const cuDoubleComplex *alpha,
                                  const cuDoubleComplex *const Aarray[], int lda,
                                  const cuDoubleComplex *const Barray[], int ldb,
                                  const cuDoubleComplex *beta,
                                  cuDoubleComplex *const Carray[], int ldc,
                                  int batchCount)

此函数支持 64 位整数接口。

此函数执行一批矩阵的矩阵-矩阵乘法。 该批处理被认为是“统一的”，即所有实例对于其各自的 A、B 和 C 矩阵都具有相同的维度 (m, n, k)、Leading Dimension（lda、ldb、ldc）和转置（transa、transb）。 批处理中每个实例的输入矩阵和输出矩阵的地址从调用者传递给函数的指针数组中读取。

\(C\lbrack i\rbrack = \alpha\text{op}(A\lbrack i\rbrack)\text{op}(B\lbrack i\rbrack) + \beta C\lbrack i\rbrack,\text{ for i } \in \lbrack 0,batchCount - 1\rbrack\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(A\) 、 \(B\) 和 \(C\) 是指向以列优先格式存储的矩阵的指针数组，其维度分别为 \(\text{op}(A\lbrack i\rbrack)\) \(m \times k\) 、 \(\text{op}(B\lbrack i\rbrack)\) \(k \times n\) 和 \(C\lbrack i\rbrack\) \(m \times n\) 。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ A^{H} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

并且对于矩阵 \(B\lbrack i\rbrack\) ，\(\text{op}(B\lbrack i\rbrack)\) 的定义类似。

注意

\(C\lbrack i\rbrack\) 矩阵不得重叠，即，各个 gemm 运算必须是可独立计算的；否则，会产生未定义的行为。

在某些问题规模下，多次调用不同 CUDA 流中的 cublas<t>gemm() 可能比使用此 API 更有优势。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
transa		输入	运算 op(A[i]) 是非转置或（共轭）转置。
transb		输入	运算 op(B[i]) 是非转置或（共轭）转置。
m		输入	矩阵 op(A[i]) 和 C[i] 的行数。
n		输入	矩阵 op(B[i]) 和 C[i] 的列数。
k		输入	op(A[i]) 的列数和 op(B[i]) 的行数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
Aarray	设备	输入	指向 <type> 数组的指针数组，每个数组的维度为 lda x k，如果 transa==CUBLAS_OP_N，则 lda >= max(1, m)；如果不是，则维度为 lda x m，且 lda >= max(1, k)。 所有指针都必须满足某些对齐标准。请参阅下文了解详细信息。
lda		输入	用于存储每个矩阵 A[i] 的二维数组的前导维度。
Barray	设备	输入	指向 <type> 数组的指针数组，每个数组的维度为 ldb x n，如果 transb==CUBLAS_OP_N，则 ldb >= max(1, k)；如果不是，则维度为 ldb x k，且 ldb>=max(1,n)。 所有指针都必须满足某些对齐标准。请参阅下文了解详细信息。
ldb		输入	用于存储每个矩阵 B[i] 的二维数组的 Leading Dimension（主导维度）。
beta	主机或设备	输入	用于乘法的 <type> 标量值。 如果 beta == 0，则 C 不必是有效的输入。
Carray	设备	输入/输出	指向 <type> 数组的指针数组。 其维度为 ldc x n，且 ldc >= max(1, m)。 矩阵 C[i] 不应重叠；否则，会产生未定义的行为。 所有指针都必须满足某些对齐标准。请参阅下文了解详细信息。
ldc		输入	用于存储每个矩阵 C[i] 的二维数组的 Leading Dimension（主导维度）。
batchCount		输入	Aarray、Barray 和 Carray 中包含的指针数量。

如果数学模式在使用 cublasSgemmBatched() 时启用快速数学模式，则放置在 GPU 内存中的指针（不是指针数组）必须正确对齐，以避免未对齐的内存访问错误。 理想情况下，所有指针都至少对齐到 16 字节。 否则，建议它们满足以下规则

• 如果 k%4==0，则确保 intptr_t(ptr) % 16 == 0，

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0 或 n < 0 或 k < 0，或者 如果 transa 和 transb 不是 CUBLAS_OP_N、 CUBLAS_OP_C、 CUBLAS_OP_T 之一，或者 如果当 transa == CUBLAS_OP_N 时 lda < max(1, m)，否则当 transa 不是 CUBLAS_OP_N 时 lda < max(1, k)，或者 如果当 transb == CUBLAS_OP_N 时 ldb < max(1, k)，否则当 transb 不是 CUBLAS_OP_N 时 ldb < max(1, n)，或者 如果 ldc < max(1, m)
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动
CUBLAS_STATUS_ARCH_MISMATCH	cublasHgemmBatched() 仅在架构能力等于或大于 5.3 的 GPU 上受支持

2.7.4. cublas<t>gemmStridedBatched()

cublasStatus_t cublasHgemmStridedBatched(cublasHandle_t handle,
                                  cublasOperation_t transa,
                                  cublasOperation_t transb,
                                  int m, int n, int k,
                                  const __half           *alpha,
                                  const __half           *A, int lda,
                                  long long int          strideA,
                                  const __half           *B, int ldb,
                                  long long int          strideB,
                                  const __half           *beta,
                                  __half                 *C, int ldc,
                                  long long int          strideC,
                                  int batchCount)
cublasStatus_t cublasSgemmStridedBatched(cublasHandle_t handle,
                                  cublasOperation_t transa,
                                  cublasOperation_t transb,
                                  int m, int n, int k,
                                  const float           *alpha,
                                  const float           *A, int lda,
                                  long long int          strideA,
                                  const float           *B, int ldb,
                                  long long int          strideB,
                                  const float           *beta,
                                  float                 *C, int ldc,
                                  long long int          strideC,
                                  int batchCount)
cublasStatus_t cublasDgemmStridedBatched(cublasHandle_t handle,
                                  cublasOperation_t transa,
                                  cublasOperation_t transb,
                                  int m, int n, int k,
                                  const double          *alpha,
                                  const double          *A, int lda,
                                  long long int          strideA,
                                  const double          *B, int ldb,
                                  long long int          strideB,
                                  const double          *beta,
                                  double                *C, int ldc,
                                  long long int          strideC,
                                  int batchCount)
cublasStatus_t cublasCgemmStridedBatched(cublasHandle_t handle,
                                  cublasOperation_t transa,
                                  cublasOperation_t transb,
                                  int m, int n, int k,
                                  const cuComplex       *alpha,
                                  const cuComplex       *A, int lda,
                                  long long int          strideA,
                                  const cuComplex       *B, int ldb,
                                  long long int          strideB,
                                  const cuComplex       *beta,
                                  cuComplex             *C, int ldc,
                                  long long int          strideC,
                                  int batchCount)
cublasStatus_t cublasCgemm3mStridedBatched(cublasHandle_t handle,
                                  cublasOperation_t transa,
                                  cublasOperation_t transb,
                                  int m, int n, int k,
                                  const cuComplex       *alpha,
                                  const cuComplex       *A, int lda,
                                  long long int          strideA,
                                  const cuComplex       *B, int ldb,
                                  long long int          strideB,
                                  const cuComplex       *beta,
                                  cuComplex             *C, int ldc,
                                  long long int          strideC,
                                  int batchCount)
cublasStatus_t cublasZgemmStridedBatched(cublasHandle_t handle,
                                  cublasOperation_t transa,
                                  cublasOperation_t transb,
                                  int m, int n, int k,
                                  const cuDoubleComplex *alpha,
                                  const cuDoubleComplex *A, int lda,
                                  long long int          strideA,
                                  const cuDoubleComplex *B, int ldb,
                                  long long int          strideB,
                                  const cuDoubleComplex *beta,
                                  cuDoubleComplex       *C, int ldc,
                                  long long int          strideC,
                                  int batchCount)

此函数支持 64 位整数接口。

此函数执行一批矩阵的矩阵-矩阵乘法。 该批处理被认为是“统一的”，即所有实例对于其各自的 A、B 和 C 矩阵都具有相同的维度 (m, n, k)、Leading Dimension（lda、ldb、ldc）和转置（transa、transb）。 批处理中每个实例的输入矩阵 A、B 和输出矩阵 C 都位于其在前一个实例中的位置的固定元素数量偏移处。 第一个实例的 A、B 和 C 矩阵的指针与元素数量偏移量 strideA、strideB 和 strideC 一起传递给函数，这些偏移量确定了未来实例中输入和输出矩阵的位置。

\(C + i*{strideC} = \alpha\text{op}(A + i*{strideA})\text{op}(B + i*{strideB}) + \beta(C + i*{strideC}),\text{ for i } \in \lbrack 0,batchCount - 1\rbrack\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(A\) 、 \(B\) 和 \(C\) 是指向以列优先格式存储的矩阵的指针数组，其维度分别为 \(\text{op}(A\lbrack i\rbrack)\) \(m \times k\) 、 \(\text{op}(B\lbrack i\rbrack)\) \(k \times n\) 和 \(C\lbrack i\rbrack\) \(m \times n\) 。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ A^{H} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

并且对于矩阵 \(B\lbrack i\rbrack\) ，\(\text{op}(B\lbrack i\rbrack)\) 的定义类似。

注意

\(C\lbrack i\rbrack\) 矩阵不得重叠，即，各个 gemm 运算必须是可独立计算的；否则，会产生未定义的行为。

在某些问题规模下，多次调用不同 CUDA 流中的 cublas<t>gemm() 可能比使用此 API 更有优势。

注意

在下表中，我们使用 A[i]、B[i]、C[i] 作为批处理第 i 个实例中 A、B 和 C 矩阵的表示法，隐含地假设它们分别是从 A[i-1]、B[i-1]、C[i-1] 偏移 strideA、strideB、strideC 个元素。 偏移量的单位是元素数量，并且不得为零。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
transa		输入	运算 op(A[i]) 是非转置或（共轭）转置。
transb		输入	运算 op(B[i]) 是非转置或（共轭）转置。
m		输入	矩阵 op(A[i]) 和 C[i] 的行数。
n		输入	矩阵 op(B[i]) 和 C[i] 的列数。
k		输入	op(A[i]) 的列数和 op(B[i]) 的行数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	指向与批处理中第一个实例对应的 A 矩阵的 <type>* 指针，维度为 lda x k，如果 transa==CUBLAS_OP_N，则 lda >= max(1, m)；如果不是，则维度为 lda x m，且 lda >= max(1, k)。
lda		输入	用于存储每个矩阵 A[i] 的二维数组的前导维度。
strideA		输入	类型为 long long int 的值，给出了 A[i] 和 A[i+1] 之间元素数量的偏移量
B	设备	输入	指向与批处理中第一个实例对应的 B 矩阵的 <type>* 指针，维度为 ldb x n，如果 transb==CUBLAS_OP_N，则 ldb >= max(1, k)；如果不是，则维度为 ldb x k，且 ldb>=max(1,n)。
ldb		输入	用于存储每个矩阵 B[i] 的二维数组的 Leading Dimension（主导维度）。
strideB		输入	类型为 long long int 的值，表示 B[i] 和 B[i+1] 之间元素数量的偏移量。
beta	主机或设备	输入	用于乘法的 <type> 标量值。 如果 beta == 0，则 C 不必是有效的输入。
C	设备	输入/输出	指向与批处理中第一个实例对应的 C 矩阵的 <type>* 指针，维度为 ldc x n，且 ldc >= max(1, m)。 矩阵 C[i] 不应重叠；否则，会产生未定义的行为。
ldc		输入	用于存储每个矩阵 C[i] 的二维数组的 Leading Dimension（主导维度）。
strideC		输入	类型为 long long int 的值，表示 C[i] 和 C[i+1] 之间元素数量的偏移量。
batchCount		输入	批处理中要执行的 GEMM 数量。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0 或 n < 0 或 k < 0，或者 如果 transa 和 transb 不是 CUBLAS_OP_N、 CUBLAS_OP_C、 CUBLAS_OP_T 之一，或者 如果当 transa == CUBLAS_OP_N 时 lda < max(1, m)，否则当 transa 不是 CUBLAS_OP_N 时 lda < max(1, k)，或者 如果当 transb == CUBLAS_OP_N 时 ldb < max(1, k)，否则当 transb 不是 CUBLAS_OP_N 时 ldb < max(1, n)，或者 如果 ldc < max(1, m)
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动
CUBLAS_STATUS_ARCH_MISMATCH	cublasHgemmStridedBatched() 仅在架构能力等于或大于 5.3 的 GPU 上受支持

2.7.5. cublas<t>gemmGroupedBatched()

cublasStatus_t cublasSgemmGroupedBatched(cublasHandle_t handle,
                                         const cublasOperation_t transa_array[],
                                         const cublasOperation_t transb_array[],
                                         const int m_array[],
                                         const int n_array[],
                                         const int k_array[],
                                         const float  alpha_array[],
                                         const float *const  Aarray[],
                                         const int lda_array[],
                                         const float *const  Barray[],
                                         const int ldb_array[],
                                         const float  beta_array[],
                                         float *const  Carray[],
                                         const int ldc_array[],
                                         int group_count,
                                         const int group_size[])
cublasStatus_t cublasDgemmGroupedBatched(cublasHandle_t handle,
                                         const cublasOperation_t transa_array[],
                                         const cublasOperation_t transb_array[],
                                         const int m_array[],
                                         const int n_array[],
                                         const int k_array[],
                                         const double alpha_array[],
                                         const double *const Aarray[],
                                         const int lda_array[],
                                         const double *const Barray[],
                                         const int ldb_array[],
                                         const double beta_array[],
                                         double *const Carray[],
                                         const int ldc_array[],
                                         int group_count,
                                         const int group_size[])

此函数支持 64 位整数接口。

此函数对矩阵组执行矩阵-矩阵乘法。 给定组被认为是“统一的”，即所有实例对于其各自的 A、B 和 C 矩阵都具有相同的维度 (m, n, k)、Leading Dimension（lda、ldb、ldc）和转置（transa、transb）。 但是，维度、Leading Dimension、转置和缩放因子（alpha、beta）在组之间可能有所不同。 批处理中每个实例的输入矩阵和输出矩阵的地址从调用者传递给函数的指针数组中读取。 这在功能上等同于以下内容

idx = 0;
for i = 0:group_count - 1
    for j = 0:group_size[i] - 1
        gemm(transa_array[i], transb_array[i], m_array[i], n_array[i], k_array[i],
             alpha_array[i], Aarray[idx], lda_array[i], Barray[idx], ldb_array[i],
             beta_array[i], Carray[idx], ldc_array[i]);
        idx += 1;
    end
end

其中 \(\text{$\mathrm{alpha\_array}$}\) 和 \(\text{$\mathrm{beta\_array}$}\) 是缩放因子数组，\(\text{Aarray}\)、 \(\text{Barray}\) 和 \(\text{Carray}\) 是指向以列优先格式存储的矩阵的指针数组。 对于给定索引 \(\text{idx}\)，它是组 \(i\) 的一部分，维度为

• \(\text{op}(\text{Aarray}\lbrack\text{idx}\rbrack)\): \(\text{$\mathrm{m\_array}$}\lbrack i\rbrack \times \text{$\mathrm{k\_array}$}\lbrack i\rbrack\)

• \(\text{op}(\text{Barray}\lbrack\text{idx}\rbrack)\): \(\text{$\mathrm{k\_array}$}\lbrack i\rbrack \times \text{$\mathrm{n\_array}$}\lbrack i\rbrack\)

• \(\text{Carray}\lbrack\text{idx}\rbrack\): \(\text{$\mathrm{m\_array}$}\lbrack i\rbrack \times \text{$\mathrm{n\_array}$}\lbrack i\rbrack\)

注意

此 API 接受两种不同长度的数组。 维度数组、Leading Dimension 数组、转置数组和缩放因子数组的长度为 group_count，矩阵数组的长度为 problem_count，其中 \(\text{$\mathrm{problem\_count}$} = \sum_{i = 0}^{\text{$\mathrm{group\_count}$} - 1} \text{$\mathrm{group\_size}$}\lbrack i\rbrack\)

对于组 \(i\) 中的矩阵 \(A[\text{idx}]\)

\(\text{op}(A[\text{idx}]) = \left\{ \begin{matrix} A[\text{idx}] & {\text{if }\textsf{$\mathrm{transa\_array}\lbrack i\rbrack$ == $\mathrm{CUBLAS\_OP\_N}$}} \\ A[\text{idx}]^{T} & {\text{if }\textsf{$\mathrm{transa\_array}\lbrack i\rbrack$ == $\mathrm{CUBLAS\_OP\_T}$}} \\ A[\text{idx}]^{H} & {\text{if }\textsf{$\mathrm{transa\_array}\lbrack i\rbrack$ == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

并且对于组 \(i\) 中的矩阵 \(B[\text{idx}]\)，\(\text{op}(B[\text{idx}])\) 的定义类似。

注意

\(C\lbrack\text{idx}\rbrack\) 矩阵不得重叠，即，各个 gemm 运算必须是可独立计算的；否则，会产生未定义的行为。

在某些问题规模下，多次调用不同 CUDA 流中的 cublas<t>gemmBatched() 可能比使用此 API 更有优势。

参数。	内存	输入/输出	含义	数组长度
handle		输入	cuBLAS 库上下文的句柄。
transa_array	主机	输入	每个组的运算 op(A[idx]) 是非转置或（共轭）转置。	group_count
transb_array	主机	输入	每个组的运算 op(B[idx]) 是非转置或（共轭）转置。	group_count
m_array	主机	输入	包含每个组的矩阵 op(A[idx]) 和 C[idx] 的行数的数组。	group_count
n_array	主机	输入	包含每个组的矩阵 op(B[idx]) 和 C[idx] 的列数的数组。	group_count
k_array	主机	输入	包含每个组的 op(A[idx]) 的列数和 op(B[idx]) 的行数的数组。	group_count
alpha_array	主机	输入	包含每个组用于乘法的 <type> 标量值的数组。	group_count
Aarray	设备	输入	指向 <type> 数组的指针数组，每个数组的维度为 lda[i] x k[i]，如果 transa[i]==CUBLAS_OP_N，则 lda[i]>=max(1,m[i])；如果不是，则维度为 lda[i] x m[i]，且 lda[i]>=max(1,k[i])。 所有指针都必须满足某些对齐标准。请参阅下文了解详细信息。	problem_count
lda_array	主机	输入	包含用于存储每个组的每个矩阵 A[idx] 的二维数组的 Leading Dimension（主导维度）的数组。	group_count
Barray	设备	输入	指向 <type> 数组的指针数组，每个数组的维度为 ldb[i] x n[i]，如果 transb[i]==CUBLAS_OP_N，则 ldb[i]>=max(1,k[i])；如果不是，则维度为 ldb[i] x k[i]，且 ldb[i]>=max(1,n[i])。 所有指针都必须满足某些对齐标准。请参阅下文了解详细信息。	problem_count
ldb_array	主机	输入	包含用于存储每个组的每个矩阵 B[idx] 的二维数组的 Leading Dimension（主导维度）的数组。	group_count
beta_array	主机	输入	包含每个组用于乘法的 <type> 标量值的数组。	group_count
Carray	设备	输入/输出	指向 <type> 数组的指针数组。 其维度为 ldc[i] x n[i]，且 ldc[i]>=max(1,m[i])。 矩阵 C[idx] 不应重叠；否则，会产生未定义的行为。 所有指针都必须满足某些对齐标准。请参阅下文了解详细信息。	problem_count
ldc_array	主机	输入	包含用于存储每个组的每个矩阵 C[idx] 的二维数组的 Leading Dimension（主导维度）的数组。	group_count
group_count	主机	输入	组数
group_size	主机	输入	包含每个组的 Aarray、Barray 和 Carray 中包含的指针数量的数组。	group_count

如果数学模式在使用 cublasSgemmGroupedBatched() 时启用快速数学模式，则放置在 GPU 内存中的指针（不是指针数组）必须正确对齐，以避免未对齐的内存访问错误。 理想情况下，所有指针都至少对齐到 16 字节。 否则，它们需要满足以下规则

• 如果 k%4==0，则确保 intptr_t(ptr) % 16 == 0，

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 transa_array、 transb_array、 m_array、 n_array、 k_array、 alpha_array、 lda_array、 ldb_array、 beta_array、 ldc_array 或 group_size 为 NULL，或者 如果 group_count < 0，或者 如果 m_array[i] < 0、 n_array[i] < 0、 k_array[i] < 0、 group_size[i] < 0，或者 如果 transa_array[i] 和 transb_array[i] 不是 CUBLAS_OP_N、 CUBLAS_OP_C、 CUBLAS_OP_T 之一，或者 如果当 transa_array[i] == CUBLAS_OP_N 时 lda_array[i] < max(1, m_array[i])，否则当 transa_array[i] 不是 CUBLAS_OP_N 时 lda_array[i] < max(1, k_array[i])，或者 如果当 transb_array[i] == CUBLAS_OP_N 时 ldb_array[i] < max(1, k_array[i])，否则当 transb_array[i] 不是 CUBLAS_OP_N 时 ldb_array[i] < max(1, n_array[i])，或者 如果 ldc_array[i] < max(1, m_array[i])
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动
CUBLAS_STATUS_NOT_SUPPORTED	指针模式设置为 CUBLAS_POINTER_MODE_DEVICE

2.7.6. cublas<t>symm()

cublasStatus_t cublasSsymm(cublasHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           int m, int n,
                           const float           *alpha,
                           const float           *A, int lda,
                           const float           *B, int ldb,
                           const float           *beta,
                           float           *C, int ldc)
cublasStatus_t cublasDsymm(cublasHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           int m, int n,
                           const double          *alpha,
                           const double          *A, int lda,
                           const double          *B, int ldb,
                           const double          *beta,
                           double          *C, int ldc)
cublasStatus_t cublasCsymm(cublasHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           int m, int n,
                           const cuComplex       *alpha,
                           const cuComplex       *A, int lda,
                           const cuComplex       *B, int ldb,
                           const cuComplex       *beta,
                           cuComplex       *C, int ldc)
cublasStatus_t cublasZsymm(cublasHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           int m, int n,
                           const cuDoubleComplex *alpha,
                           const cuDoubleComplex *A, int lda,
                           const cuDoubleComplex *B, int ldb,
                           const cuDoubleComplex *beta,
                           cuDoubleComplex *C, int ldc)

此函数支持 64 位整数接口。

此函数执行对称矩阵-矩阵乘法

\(C = \left\{ \begin{matrix} {\alpha AB + \beta C} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ {\alpha BA + \beta C} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_RIGHT}$}} \\ \end{matrix} \right.\)

其中 \(A\) 是以lower或upper模式存储的对称矩阵，\(B\) 和 \(C\) 是 \(m \times n\) 矩阵，\(\alpha\) 和 \(\beta\) 是标量。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
side		输入	指示矩阵 A 在 B 的左侧还是右侧。
uplo		输入	指示矩阵 A 的下部或上部是否存储，另一个对称部分未被引用，并从存储的元素中推断出来。
m		输入	矩阵 C 和 B 的行数，矩阵 A 的大小相应调整。
n		输入	矩阵 C 和 B 的列数，矩阵 A 的大小相应调整。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	维度为 lda x m 的 <type> 数组，如果 side == CUBLAS_SIDE_LEFT，则 lda >= max(1, m)；如果不是，则维度为 lda x n，且 lda >= max(1, n)。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
B	设备	输入	维度为 ldb x n 的 <type> 数组，且 ldb >= max(1, m)。
ldb		输入	用于存储矩阵 B 的二维数组的 Leading Dimension（主导维度）。
beta	主机或设备	输入	用于乘法的 <type> 标量值。 如果 beta == 0，则 C 不必是有效的输入。
C	设备	输入/输出	维度为 ldc x n 的 <type> 数组，且 ldc >= max(1, m)。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0 或 n < 0，或者 如果 side 不是 CUBLAS_SIDE_LEFT 和 CUBLAS_SIDE_RIGHT 之一，或者 如果 n < 0 或 k < 0，或者 如果当 side == CUBLAS_SIDE_LEFT 时 lda < max(1, m)，否则当 side 不是 CUBLAS_SIDE_LEFT 时 lda < max(1, n)，或者 如果 ldb < max(1, m)，或者 如果 ldc < max(1, m)，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 和 CUBLAS_FILL_MODE_UPPER 之一，或者 如果当 beta 非零时 C 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

ssymm(), dsymm(), csymm(), zsymm()

2.7.7. cublas<t>syrk()

cublasStatus_t cublasSsyrk(cublasHandle_t handle,
                           cublasFillMode_t uplo, cublasOperation_t trans,
                           int n, int k,
                           const float           *alpha,
                           const float           *A, int lda,
                           const float           *beta,
                           float           *C, int ldc)
cublasStatus_t cublasDsyrk(cublasHandle_t handle,
                           cublasFillMode_t uplo, cublasOperation_t trans,
                           int n, int k,
                           const double          *alpha,
                           const double          *A, int lda,
                           const double          *beta,
                           double          *C, int ldc)
cublasStatus_t cublasCsyrk(cublasHandle_t handle,
                           cublasFillMode_t uplo, cublasOperation_t trans,
                           int n, int k,
                           const cuComplex       *alpha,
                           const cuComplex       *A, int lda,
                           const cuComplex       *beta,
                           cuComplex       *C, int ldc)
cublasStatus_t cublasZsyrk(cublasHandle_t handle,
                           cublasFillMode_t uplo, cublasOperation_t trans,
                           int n, int k,
                           const cuDoubleComplex *alpha,
                           const cuDoubleComplex *A, int lda,
                           const cuDoubleComplex *beta,
                           cuDoubleComplex *C, int ldc)

此函数支持 64 位整数接口。

此函数执行对称秩- \(k\) 更新

\(C = \alpha\text{op}(A)\text{op}(A)^{T} + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以较低或较高模式存储的对称矩阵，而 \(A\) 是维度为 \(\text{op}(A)\) \(n \times k\) 的矩阵。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ \end{matrix} \right.\)

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 C 的下半部分或上半部分是否存储，另一个对称部分不被引用，而是从存储的元素推断出来。
trans		输入	运算 op(A)，为非转置或转置。
n		输入	矩阵 op(A) 和 C 的行数。
k		输入	矩阵 op(A) 的列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	<type> 维度为 lda x k 的数组，如果 trans == CUBLAS_OP_N，则 lda >= max(1, n)；否则，维度为 lda x n，且 lda >= max(1, k)。
lda		输入	用于存储矩阵 A 的二维数组的前导维度。
beta	主机或设备	输入	用于乘法的 <type> 标量值。 如果 beta == 0，则 C 不必是有效的输入。
C	设备	输入/输出	<type> 维度为 ldc x n 的数组，且 ldc >= max(1, n)。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 维度为 lda x n 的数组，其中 lda >= k + 1。 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 n < 0 或 k < 0，或者 如果当 trans == CUBLAS_OP_N 时 lda < max(1, n)，否则如果 lda < max(1, k)，或者 如果 ldc < max(1, n)，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 和 CUBLAS_FILL_MODE_UPPER 之一，或者 如果当 beta 非零时 C 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

ssyrk(), dsyrk(), csyrk(), zsyrk()

2.7.8. cublas<t>syr2k()

cublasStatus_t cublasSsyr2k(cublasHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            int n, int k,
                            const float           *alpha,
                            const float           *A, int lda,
                            const float           *B, int ldb,
                            const float           *beta,
                            float           *C, int ldc)
cublasStatus_t cublasDsyr2k(cublasHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            int n, int k,
                            const double          *alpha,
                            const double          *A, int lda,
                            const double          *B, int ldb,
                            const double          *beta,
                            double          *C, int ldc)
cublasStatus_t cublasCsyr2k(cublasHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            int n, int k,
                            const cuComplex       *alpha,
                            const cuComplex       *A, int lda,
                            const cuComplex       *B, int ldb,
                            const cuComplex       *beta,
                            cuComplex       *C, int ldc)
cublasStatus_t cublasZsyr2k(cublasHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            int n, int k,
                            const cuDoubleComplex *alpha,
                            const cuDoubleComplex *A, int lda,
                            const cuDoubleComplex *B, int ldb,
                            const cuDoubleComplex *beta,
                            cuDoubleComplex *C, int ldc)

此函数支持 64 位整数接口。

此函数执行对称秩- \(2k\) 更新

\(C = \alpha(\text{op}(A)\text{op}(B)^{T} + \text{op}(B)\text{op}(A)^{T}) + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以较低或较高模式存储的对称矩阵，而 \(A\) 和 \(B\) 分别是维度为 \(\text{op}(A)\) \(n \times k\) 和 \(\text{op}(B)\) \(n \times k\) 的矩阵。 此外，对于矩阵 \(A\) 和 \(B\)

\(\text{op(}A\text{) and op(}B\text{)} = \left\{ \begin{matrix} {A\text{ and }B} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A^{T}\text{ and }B^{T}} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_T}$}} \\ \end{matrix} \right.\)

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 C 的下半部分或上半部分是否存储，另一个对称部分不被引用，而是从存储的元素推断出来。
trans		输入	运算 op(A)，为非转置或转置。
n		输入	矩阵 op(A)、op(B) 和 C 的行数。
k		输入	矩阵 op(A) 和 op(B) 的列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	<type> 维度为 lda x k 的数组，如果 transa == CUBLAS_OP_N，则 lda >= max(1, n)；否则，维度为 lda x n，且 lda >= max(1, k)。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
B	设备	输入	<type> 维度为 ldb x k 的数组，如果 transb == CUBLAS_OP_N，则 ldb >= max(1, n)；否则，维度为 ldb x n，且 ldb>=max(1,k)。
ldb		输入	用于存储矩阵 B 的二维数组的 Leading Dimension（主导维度）。
beta	主机或设备	输入	<type> 用于乘法的标量。 如果 beta == 0，则 C 不必是有效的输入。
C	设备	输入/输出	<type> 维度为 ldc x n 的数组，且 ldc >= max(1, n)。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 维度为 lda x n 的数组，其中 lda >= k + 1。 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 n < 0 或 k < 0，或者 如果当 trans == CUBLAS_OP_N 时 lda < max(1, n)，否则如果 lda < max(1, k)，或者 如果当 trans == CUBLAS_OP_N 时 ldb < max(1, n)，否则如果 ldb < max(1, k)，或者 如果 ldc < max(1, n)，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 和 CUBLAS_FILL_MODE_UPPER 之一，或者 如果当 beta 非零时 C 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

ssyr2k(), dsyr2k(), csyr2k(), zsyr2k()

2.7.9. cublas<t>syrkx()

cublasStatus_t cublasSsyrkx(cublasHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            int n, int k,
                            const float           *alpha,
                            const float           *A, int lda,
                            const float           *B, int ldb,
                            const float           *beta,
                            float           *C, int ldc)
cublasStatus_t cublasDsyrkx(cublasHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            int n, int k,
                            const double          *alpha,
                            const double          *A, int lda,
                            const double          *B, int ldb,
                            const double          *beta,
                            double          *C, int ldc)
cublasStatus_t cublasCsyrkx(cublasHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            int n, int k,
                            const cuComplex       *alpha,
                            const cuComplex       *A, int lda,
                            const cuComplex       *B, int ldb,
                            const cuComplex       *beta,
                            cuComplex       *C, int ldc)
cublasStatus_t cublasZsyrkx(cublasHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            int n, int k,
                            const cuDoubleComplex *alpha,
                            const cuDoubleComplex *A, int lda,
                            const cuDoubleComplex *B, int ldb,
                            const cuDoubleComplex *beta,
                            cuDoubleComplex *C, int ldc)

此函数支持 64 位整数接口。

此函数执行对称秩- \(k\) 更新的变体

\(C = \alpha\text{op}(A)\text{op}(B)^{T} + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以较低或较高模式存储的对称矩阵，而 \(A\) 和 \(B\) 分别是维度为 \(\text{op}(A)\) \(n \times k\) 和 \(\text{op}(B)\) \(n \times k\) 的矩阵。 此外，对于矩阵 \(A\) 和 \(B\)

\(\text{op(}A\text{) and op(}B\text{)} = \left\{ \begin{matrix} {A\text{ and }B} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A^{T}\text{ and }B^{T}} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_T}$}} \\ \end{matrix} \right.\)

当 B 以某种方式使得结果保证对称时，可以使用此例程。 一个常见的例子是当矩阵 B 是矩阵 A 的缩放形式时：这等效于 B 是矩阵 A 和对角矩阵的乘积。 为了有效计算规则矩阵与对角矩阵的乘积，请参阅例程 cublas<t>dgmm()。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 C 的下半部分或上半部分是否存储，另一个对称部分不被引用，而是从存储的元素推断出来。
trans		输入	运算 op(A)，为非转置或转置。
n		输入	矩阵 op(A)、op(B) 和 C 的行数。
k		输入	矩阵 op(A) 和 op(B) 的列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	<type> 维度为 lda x k 的数组，如果 transa == CUBLAS_OP_N，则 lda >= max(1, n)；否则，维度为 lda x n，且 lda >= max(1, k)。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
B	设备	输入	<type> 维度为 ldb x k 的数组，如果 transb == CUBLAS_OP_N，则 ldb >= max(1, n)；否则，维度为 ldb x n，且 ldb>=max(1,k)。
ldb		输入	用于存储矩阵 B 的二维数组的 Leading Dimension（主导维度）。
beta	主机或设备	输入	<type> 用于乘法的标量。 如果 beta == 0，则 C 不必是有效的输入。
C	设备	输入/输出	<type> 维度为 ldc x n 的数组，且 ldc >= max(1, n)。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 维度为 lda x n 的数组，其中 lda >= k + 1。 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 n < 0 或 k < 0，或者 如果当 trans == CUBLAS_OP_N 时 lda < max(1, n)，否则如果 lda < max(1, k)，或者 如果当 trans == CUBLAS_OP_N 时 ldb < max(1, n)，否则如果 ldb < max(1, k)，或者 如果 ldc < max(1, n)，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 和 CUBLAS_FILL_MODE_UPPER 之一，或者 如果当 beta 非零时 C 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

ssyrk(), dsyrk(), csyrk(), zsyrk() 和

ssyr2k(), dsyr2k(), csyr2k(), zsyr2k()

2.7.10. cublas<t>trmm()

cublasStatus_t cublasStrmm(cublasHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int m, int n,
                           const float           *alpha,
                           const float           *A, int lda,
                           const float           *B, int ldb,
                           float                 *C, int ldc)
cublasStatus_t cublasDtrmm(cublasHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int m, int n,
                           const double          *alpha,
                           const double          *A, int lda,
                           const double          *B, int ldb,
                           double                *C, int ldc)
cublasStatus_t cublasCtrmm(cublasHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int m, int n,
                           const cuComplex       *alpha,
                           const cuComplex       *A, int lda,
                           const cuComplex       *B, int ldb,
                           cuComplex             *C, int ldc)
cublasStatus_t cublasZtrmm(cublasHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int m, int n,
                           const cuDoubleComplex *alpha,
                           const cuDoubleComplex *A, int lda,
                           const cuDoubleComplex *B, int ldb,
                           cuDoubleComplex       *C, int ldc)

此函数支持 64 位整数接口。

此函数执行三角矩阵-矩阵乘法

\(C = \left\{ \begin{matrix} {\alpha\text{op}(A)B} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ {\alpha B\text{op}(A)} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_RIGHT}$}} \\ \end{matrix} \right.\)

其中 \(A\) 是以较低或较高模式存储的三角矩阵，可以带或不带主对角线，\(B\) 和 \(C\) 是 \(m \times n\) 矩阵，而 \(\alpha\) 是标量。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ A^{H} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

请注意，为了实现更好的并行性，cuBLAS 仅在此例程中与 BLAS API 不同。 BLAS API 假定就地实现（结果写回 B），而 cuBLAS API 假定异地实现（结果写入 C）。 应用程序可以通过在 cuBLAS API 中传递矩阵 B 的地址来代替矩阵 C，从而获得 BLAS 的就地功能。 不支持输入参数中的其他重叠。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
side		输入	指示矩阵 A 在 B 的左侧还是右侧。
uplo		输入	指示矩阵 A 的下半部分还是上半部分被存储，另一部分不会被引用，而是从存储的元素中推断出来。
trans		输入	运算 op(A)，它是非转置或（共轭）转置。
diag		输入	指示矩阵 A 主对角线上的元素是否为单位元素且不应被访问。
m		输入	矩阵 B 的行数，矩阵 A 的大小相应调整。
n		输入	矩阵 B 的列数，矩阵 A 的大小相应调整。
alpha	主机或设备	输入	<type> 用于乘法的标量，如果 alpha == 0，则不引用 A，并且 B 不必是有效的输入。
A	设备	输入	维度为 lda x m 的 <type> 数组，如果 side == CUBLAS_SIDE_LEFT，则 lda >= max(1, m)；如果不是，则维度为 lda x n，且 lda >= max(1, n)。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
B	设备	输入	维度为 ldb x n 的 <type> 数组，且 ldb >= max(1, m)。
ldb		输入	用于存储矩阵 B 的二维数组的 Leading Dimension（主导维度）。
C	设备	输入/输出	维度为 ldc x n 的 <type> 数组，且 ldc >= max(1, m)。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0、n < 0，或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 n < 0 或 k < 0，或者 如果 side 不是 CUBLAS_SIDE_LEFT 和 CUBLAS_SIDE_RIGHT 之一，或者 如果当 side == CUBLAS_SIDE_LEFT 时 lda < max(1, m)，否则如果 lda < max(1, n)，或者 如果 ldb < max(1, m)，或者 如果 ldc < max(1, m)，或者 如果 incx == 0，或者
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

strmm(), dtrmm(), ctrmm(), ztrmm()

2.7.11. cublas<t>trsm()

cublasStatus_t cublasStrsm(cublasHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int m, int n,
                           const float           *alpha,
                           const float           *A, int lda,
                           float           *B, int ldb)
cublasStatus_t cublasDtrsm(cublasHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int m, int n,
                           const double          *alpha,
                           const double          *A, int lda,
                           double          *B, int ldb)
cublasStatus_t cublasCtrsm(cublasHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int m, int n,
                           const cuComplex       *alpha,
                           const cuComplex       *A, int lda,
                           cuComplex       *B, int ldb)
cublasStatus_t cublasZtrsm(cublasHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           int m, int n,
                           const cuDoubleComplex *alpha,
                           const cuDoubleComplex *A, int lda,
                           cuDoubleComplex *B, int ldb)

此函数支持 64 位整数接口。

此函数求解具有多个右侧的三角线性系统

\(\left\{ \begin{matrix} {\text{op}(A)X = \alpha B} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ {X\text{op}(A) = \alpha B} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_RIGHT}$}} \\ \end{matrix} \right.\)

其中 \(A\) 是以较低或较高模式存储的三角矩阵，可以带或不带主对角线，\(X\) 和 \(B\) 是 \(m \times n\) 矩阵，而 \(\alpha\) 是标量。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ A^{H} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

解 \(X\) 在退出时覆盖右侧 \(B\)。

此函数中不包含对奇异性或近奇异性的测试。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
side		输入	指示矩阵 A 在 X 的左侧还是右侧。
uplo		输入	指示矩阵 A 的下半部分还是上半部分被存储，另一部分不会被引用，而是从存储的元素中推断出来。
trans		输入	运算 op(A)，它是非转置或（共轭）转置。
diag		输入	指示矩阵 A 主对角线上的元素是否为单位元素且不应被访问。
m		输入	矩阵 B 的行数，矩阵 A 的大小相应调整。
n		输入	矩阵 B 的列数，矩阵 A 的大小相应调整。
alpha	主机或设备	输入	<type> 用于乘法的标量，如果 alpha == 0，则不引用 A，并且 B 不必是有效的输入。
A	设备	输入	维度为 lda x m 的 <type> 数组，如果 side == CUBLAS_SIDE_LEFT，则 lda >= max(1, m)；如果不是，则维度为 lda x n，且 lda >= max(1, n)。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
B	设备	输入/输出	<type> 数组。 它的维度为 ldb x n，且 ldb >= max(1, m)。
ldb		输入	用于存储矩阵 B 的二维数组的 Leading Dimension（主导维度）。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0、n < 0，或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 n < 0 或 k < 0，或者 如果 side 不是 CUBLAS_SIDE_LEFT 和 CUBLAS_SIDE_RIGHT 之一，或者 如果 diag 不是 CUBLAS_DIAG_UNIT 和 CUBLAS_DIAG_NON_UNIT 之一，或者 如果当 side == CUBLAS_SIDE_LEFT 时 lda < max(1, m)，否则如果 lda < max(1, n)，或者 如果 ldb < max(1, m)，或者 如果 incx == 0，或者
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

strsm(), dtrsm(), ctrsm(), ztrsm()

2.7.12. cublas<t>trsmBatched()

cublasStatus_t cublasStrsmBatched( cublasHandle_t    handle,
                                   cublasSideMode_t  side,
                                   cublasFillMode_t  uplo,
                                   cublasOperation_t trans,
                                   cublasDiagType_t  diag,
                                   int m,
                                   int n,
                                   const float *alpha,
                                   const float *const A[],
                                   int lda,
                                   float *const B[],
                                   int ldb,
                                   int batchCount);
cublasStatus_t cublasDtrsmBatched( cublasHandle_t    handle,
                                   cublasSideMode_t  side,
                                   cublasFillMode_t  uplo,
                                   cublasOperation_t trans,
                                   cublasDiagType_t  diag,
                                   int m,
                                   int n,
                                   const double *alpha,
                                   const double *const A[],
                                   int lda,
                                   double *const B[],
                                   int ldb,
                                   int batchCount);
cublasStatus_t cublasCtrsmBatched( cublasHandle_t    handle,
                                   cublasSideMode_t  side,
                                   cublasFillMode_t  uplo,
                                   cublasOperation_t trans,
                                   cublasDiagType_t  diag,
                                   int m,
                                   int n,
                                   const cuComplex *alpha,
                                   const cuComplex *const A[],
                                   int lda,
                                   cuComplex *const B[],
                                   int ldb,
                                   int batchCount);
cublasStatus_t cublasZtrsmBatched( cublasHandle_t    handle,
                                   cublasSideMode_t  side,
                                   cublasFillMode_t  uplo,
                                   cublasOperation_t trans,
                                   cublasDiagType_t  diag,
                                   int m,
                                   int n,
                                   const cuDoubleComplex *alpha,
                                   const cuDoubleComplex *const A[],
                                   int lda,
                                   cuDoubleComplex *const B[],
                                   int ldb,
                                   int batchCount);

此函数支持 64 位整数接口。

此函数求解具有多个右侧的三角线性系统数组

\(\left\{ \begin{matrix} {\text{op}(A\lbrack i\rbrack)X\lbrack i\rbrack = \alpha B\lbrack i\rbrack} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ {X\lbrack i\rbrack\text{op}(A\lbrack i\rbrack) = \alpha B\lbrack i\rbrack} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_RIGHT}$}} \\ \end{matrix} \right.\)

其中 \(A\lbrack i\rbrack\) 是以较低或较高模式存储的三角矩阵，可以带或不带主对角线，\(X\lbrack i\rbrack\) 和 \(B\lbrack i\rbrack\) 是 \(m \times n\) 矩阵，而 \(\alpha\) 是标量。 此外，对于矩阵 \(A\)

\(\text{op}(A\lbrack i\rbrack) = \left\{ \begin{matrix} {A\lbrack i\rbrack} & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A^{T}\lbrack i\rbrack} & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ {A^{H}\lbrack i\rbrack} & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

解 \(X\lbrack i\rbrack\) 在退出时覆盖右侧 \(B\lbrack i\rbrack\)。

此函数中不包含对奇异性或近奇异性的测试。

此函数适用于任何大小，但旨在用于小尺寸矩阵，其中启动开销是一个重要因素。 对于较大的尺寸，在 CUDA 流集中调用 batchCount 次常规 cublas<t>trsm() 可能更有利。

当前实现仅限于计算能力高于或等于 2.0 的设备。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
side		输入	指示矩阵 A[i] 在 X[i] 的左侧还是右侧。
uplo		输入	指示矩阵 A[i] 的下半部分或上半部分是否存储，另一部分不被引用，而是从存储的元素推断出来。
trans		输入	运算 op(A[i]) 是非转置或（共轭）转置。
diag		输入	指示矩阵 A[i] 主对角线上的元素是否为单位元素，并且不应访问。
m		输入	矩阵 B[i] 的行数，矩阵 A[i] 的大小相应调整。
n		输入	矩阵 B[i] 的列数，矩阵 A[i] 的大小相应调整。
alpha	主机或设备	输入	<type> 用于乘法的标量，如果 alpha == 0，则不引用 A[i]，并且 B[i] 不必是有效的输入。
A	设备	输入	指向 <type> 数组的指针数组，每个数组的维度为 lda x m，如果 side == CUBLAS_SIDE_LEFT，则 lda >= max(1, m)；否则，维度为 lda x n，且 lda >= max(1, n)。
lda		输入	用于存储矩阵 A[i] 的二维数组的前导维度。
B	设备	输入/输出	指向 <type> 数组的指针数组，每个数组的维度为 ldb x n，且 ldb >= max(1, m)。 矩阵 B[i] 不应重叠；否则，将产生未定义的行为。
ldb		输入	用于存储矩阵 B[i] 的二维数组的前导维度。
batchCount		输入	A 和 B 中包含的指针数量。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0、n < 0，或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 n < 0 或 k < 0，或者 如果 side 不是 CUBLAS_SIDE_LEFT 和 CUBLAS_SIDE_RIGHT 之一，或者 如果 diag 不是 CUBLAS_DIAG_UNIT 和 CUBLAS_DIAG_NON_UNIT 之一，或者 如果当 side == CUBLAS_SIDE_LEFT 时 lda < max(1, m)，否则如果 lda < max(1, n)，或者 如果 ldb < max(1, m)
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

strsm(), dtrsm(), ctrsm(), ztrsm()

2.7.13. cublas<t>hemm()

cublasStatus_t cublasChemm(cublasHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           int m, int n,
                           const cuComplex       *alpha,
                           const cuComplex       *A, int lda,
                           const cuComplex       *B, int ldb,
                           const cuComplex       *beta,
                           cuComplex       *C, int ldc)
cublasStatus_t cublasZhemm(cublasHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           int m, int n,
                           const cuDoubleComplex *alpha,
                           const cuDoubleComplex *A, int lda,
                           const cuDoubleComplex *B, int ldb,
                           const cuDoubleComplex *beta,
                           cuDoubleComplex *C, int ldc)

此函数支持 64 位整数接口。

此函数执行 Hermitian 矩阵-矩阵乘法

\(C = \left\{ \begin{matrix} {\alpha AB + \beta C} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ {\alpha BA + \beta C} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_RIGHT}$}} \\ \end{matrix} \right.\)

其中 \(A\) 是以较低或较高模式存储的 Hermitian 矩阵，\(B\) 和 \(C\) 是 \(m \times n\) 矩阵，而 \(\alpha\) 和 \(\beta\) 是标量。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
side		输入	指示矩阵 A 在 B 的左侧还是右侧。
uplo		输入	指示矩阵 A 的下半部分还是上半部分被存储，另一个埃尔米特部分不会被引用，而是从存储的元素中推断出来。
m		输入	矩阵 C 和 B 的行数，矩阵 A 的大小相应调整。
n		输入	矩阵 C 和 B 的列数，矩阵 A 的大小相应调整。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	<type> 维度为 lda x m 的数组，如果 side==CUBLAS_SIDE_LEFT，则 lda >= max(1, m)；否则，维度为 lda x n，且 lda >= max(1, n)。 假定对角元素的虚部为零。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
B	设备	输入	维度为 ldb x n 的 <type> 数组，且 ldb >= max(1, m)。
ldb		输入	用于存储矩阵 B 的二维数组的 Leading Dimension（主导维度）。
beta		输入	用于乘法的 <type> 标量值。 如果 beta == 0，则 C 不必是有效的输入。
C	设备	输入/输出	维度为 ldc x n 的 <type> 数组，且 ldc >= max(1, m)。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0 或 n < 0，或者 如果 side 不是 CUBLAS_SIDE_LEFT 和 CUBLAS_SIDE_RIGHT 之一，或者 如果 n < 0 或 k < 0，或者 如果当 side == CUBLAS_SIDE_LEFT 时 lda < max(1, m)，否则当 side 不是 CUBLAS_SIDE_LEFT 时 lda < max(1, n)，或者 如果 ldb < max(1, m)，或者 如果 ldc < max(1, m)，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 和 CUBLAS_FILL_MODE_UPPER 之一，或者 如果当 beta 非零时 C 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

chemm(), zhemm()

2.7.14. cublas<t>herk()

cublasStatus_t cublasCherk(cublasHandle_t handle,
                           cublasFillMode_t uplo, cublasOperation_t trans,
                           int n, int k,
                           const float  *alpha,
                           const cuComplex       *A, int lda,
                           const float  *beta,
                           cuComplex       *C, int ldc)
cublasStatus_t cublasZherk(cublasHandle_t handle,
                           cublasFillMode_t uplo, cublasOperation_t trans,
                           int n, int k,
                           const double *alpha,
                           const cuDoubleComplex *A, int lda,
                           const double *beta,
                           cuDoubleComplex *C, int ldc)

此函数支持 64 位整数接口。

此函数执行 Hermitian 秩- \(k\) 更新

\(C = \alpha\text{op}(A)\text{op}(A)^{H} + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以较低或较高模式存储的 Hermitian 矩阵，而 \(A\) 是维度为 \(\text{op}(A)\) \(n \times k\) 的矩阵。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{H} & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 C 的下半部分或上半部分是否存储，另一个 Hermitian 部分不被引用。
trans		输入	运算 op(A)，它是非转置或（共轭）转置。
n		输入	矩阵 op(A) 和 C 的行数。
k		输入	矩阵 op(A) 的列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	<type> 维度为 lda x k 的数组，如果 transa == CUBLAS_OP_N，则 lda >= max(1, n)；否则，维度为 lda x n，且 lda >= max(1, k)。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
beta		输入	用于乘法的 <type> 标量值。 如果 beta == 0，则 C 不必是有效的输入。
C	设备	输入/输出	<type> 维度为 ldc x n 的数组，且 ldc >= max(1, n)。 假定对角元素的虚部为零并设置为零。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 维度为 lda x n 的数组，其中 lda >= k + 1。 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 n < 0 或 k < 0，或者 如果当 trans == CUBLAS_OP_N 时 lda < max(1, n)，否则如果 lda < max(1, k)，或者 如果 ldc < max(1, n)，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 和 CUBLAS_FILL_MODE_UPPER 之一，或者 如果当 beta 非零时 C 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

cherk(), zherk()

2.7.15. cublas<t>her2k()

cublasStatus_t cublasCher2k(cublasHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            int n, int k,
                            const cuComplex       *alpha,
                            const cuComplex       *A, int lda,
                            const cuComplex       *B, int ldb,
                            const float  *beta,
                            cuComplex       *C, int ldc)
cublasStatus_t cublasZher2k(cublasHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            int n, int k,
                            const cuDoubleComplex *alpha,
                            const cuDoubleComplex *A, int lda,
                            const cuDoubleComplex *B, int ldb,
                            const double *beta,
                            cuDoubleComplex *C, int ldc)

此函数支持 64 位整数接口。

此函数执行 Hermitian 秩- \(2k\) 更新

\(C = \alpha\text{op}(A)\text{op}(B)^{H} + \overset{ˉ}{\alpha}\text{op}(B)\text{op}(A)^{H} + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以较低或较高模式存储的 Hermitian 矩阵，而 \(A\) 和 \(B\) 分别是维度为 \(\text{op}(A)\) \(n \times k\) 和 \(\text{op}(B)\) \(n \times k\) 的矩阵。 此外，对于矩阵 \(A\) 和 \(B\)

\(\text{op(}A\text{) and op(}B\text{)} = \left\{ \begin{matrix} {A\text{ and }B} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A^{H}\text{ and }B^{H}} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 C 的下半部分或上半部分是否存储，另一个 Hermitian 部分不被引用。
trans		输入	运算 op(A)，它是非转置或（共轭）转置。
n		输入	矩阵 op(A)、op(B) 和 C 的行数。
k		输入	矩阵 op(A) 和 op(B) 的列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	<type> 维度为 lda x k 的数组，如果 transa == CUBLAS_OP_N，则 lda >= max(1, n)；否则，维度为 lda x n，且 lda >= max(1, k)。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
B	设备	输入	<type> 维度为 ldb x k 的数组，如果 transb == CUBLAS_OP_N，则 ldb >= max(1, n)；否则，维度为 ldb x n，且 ldb>=max(1,k)。
ldb		输入	用于存储矩阵 B 的二维数组的 Leading Dimension（主导维度）。
beta	主机或设备	输入	用于乘法的 <type> 标量值。 如果 beta == 0，则 C 不必是有效的输入。
C	设备	输入/输出	<type> 维度为 ldc x n 的数组，且 ldc >= max(1, n)。 假定对角元素的虚部为零并设置为零。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 维度为 lda x n 的数组，其中 lda >= k + 1。 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 n < 0 或 k < 0，或者 如果当 trans == CUBLAS_OP_N 时 lda < max(1, n)，否则如果 lda < max(1, k)，或者 如果 ldc < max(1, n)，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 和 CUBLAS_FILL_MODE_UPPER 之一，或者 如果当 beta 非零时 C 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

cher2k(), zher2k()

2.7.16. cublas<t>herkx()

cublasStatus_t cublasCherkx(cublasHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            int n, int k,
                            const cuComplex       *alpha,
                            const cuComplex       *A, int lda,
                            const cuComplex       *B, int ldb,
                            const float  *beta,
                            cuComplex       *C, int ldc)
cublasStatus_t cublasZherkx(cublasHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            int n, int k,
                            const cuDoubleComplex *alpha,
                            const cuDoubleComplex *A, int lda,
                            const cuDoubleComplex *B, int ldb,
                            const double *beta,
                            cuDoubleComplex *C, int ldc)

此函数支持 64 位整数接口。

此函数执行 Hermitian 秩- \(k\) 更新的变体

\(C = \alpha\text{op}(A)\text{op}(B)^{H} + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以较低或较高模式存储的 Hermitian 矩阵，而 \(A\) 和 \(B\) 分别是维度为 \(\text{op}(A)\) \(n \times k\) 和 \(\text{op}(B)\) \(n \times k\) 的矩阵。 此外，对于矩阵 \(A\) 和 \(B\)

\(\text{op(}A\text{) and op(}B\text{)} = \left\{ \begin{matrix} {A\text{ and }B} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A^{H}\text{ and }B^{H}} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

当矩阵 B 以某种方式使得结果保证为 Hermitian 矩阵时，可以使用此例程。 一个常见的例子是当矩阵 B 是矩阵 A 的缩放形式时：这等效于 B 是矩阵 A 和对角矩阵的乘积。 为了有效计算规则矩阵与对角矩阵的乘积，请参阅例程 cublas<t>dgmm()。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 C 的下半部分或上半部分是否存储，另一个 Hermitian 部分不被引用。
trans		输入	运算 op(A)，它是非转置或（共轭）转置。
n		输入	矩阵 op(A)、op(B) 和 C 的行数。
k		输入	矩阵 op(A) 和 op(B) 的列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	<type> 维度为 lda x k 的数组，如果 transa == CUBLAS_OP_N，则 lda >= max(1, n)；否则，维度为 lda x n，且 lda >= max(1, k)。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
B	设备	输入	<type> 维度为 ldb x k 的数组，如果 transb == CUBLAS_OP_N，则 ldb >= max(1, n)；否则，维度为 ldb x n，且 ldb>=max(1,k)。
ldb		输入	用于存储矩阵 B 的二维数组的 Leading Dimension（主导维度）。
beta	主机或设备	输入	用于乘法的实数标量。 如果 beta == 0，则 C 不必是有效的输入。
C	设备	输入/输出	<type> 维度为 ldc x n 的数组，且 ldc >= max(1, n)。 假定对角元素的虚部为零并设置为零。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 维度为 lda x n 的数组，其中 lda >= k + 1。 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 n < 0 或 k < 0，或者 如果当 trans == CUBLAS_OP_N 时 lda < max(1, n)，否则如果 lda < max(1, k)，或者 如果 ldc < max(1, n)，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 和 CUBLAS_FILL_MODE_UPPER 之一，或者 如果当 beta 非零时 C 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

cherk(), zherk() 和

cher2k(), zher2k()

2.8. 类 BLAS 扩展

本节介绍执行矩阵-矩阵运算的 BLAS 扩展函数。

2.8.1. cublas<t>geam()

cublasStatus_t cublasSgeam(cublasHandle_t handle,
                          cublasOperation_t transa, cublasOperation_t transb,
                          int m, int n,
                          const float           *alpha,
                          const float           *A, int lda,
                          const float           *beta,
                          const float           *B, int ldb,
                          float           *C, int ldc)
cublasStatus_t cublasDgeam(cublasHandle_t handle,
                          cublasOperation_t transa, cublasOperation_t transb,
                          int m, int n,
                          const double          *alpha,
                          const double          *A, int lda,
                          const double          *beta,
                          const double          *B, int ldb,
                          double          *C, int ldc)
cublasStatus_t cublasCgeam(cublasHandle_t handle,
                          cublasOperation_t transa, cublasOperation_t transb,
                          int m, int n,
                          const cuComplex       *alpha,
                          const cuComplex       *A, int lda,
                          const cuComplex       *beta ,
                          const cuComplex       *B, int ldb,
                          cuComplex       *C, int ldc)
cublasStatus_t cublasZgeam(cublasHandle_t handle,
                          cublasOperation_t transa, cublasOperation_t transb,
                          int m, int n,
                          const cuDoubleComplex *alpha,
                          const cuDoubleComplex *A, int lda,
                          const cuDoubleComplex *beta,
                          const cuDoubleComplex *B, int ldb,
                          cuDoubleComplex *C, int ldc)

此函数支持 64 位整数接口。

此函数执行矩阵-矩阵加法/转置

\(C = \alpha\text{op}(A) + \beta\text{op}(B)\)

其中 \(\alpha\) 和 \(\beta\) 是标量，而 \(A\)、\(B\) 和 \(C\) 是以列优先格式存储的矩阵，其维度分别为 \(\text{op}(A)\) \(m \times n\)、\(\text{op}(B)\) \(m \times n\) 和 \(C\) \(m \times n\)。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ A^{H} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

并且对于矩阵 \(B\) ，\(\text{op}(B)\) 的定义类似。

如果 C 不与 A 或 B 重叠，则运算是异地的。

就地模式支持以下两个操作：

\(C = \alpha\text{*}C + \beta\text{op}(B)\)

\(C = \alpha\text{op}(A) + \beta\text{*}C\)

对于就地模式，如果 C = A，则 ldc = lda 并且 transa = CUBLAS_OP_N。 如果 C = B，则 ldc = ldb 并且 transb = CUBLAS_OP_N。 如果用户不满足上述要求，则返回 CUBLAS_STATUS_INVALID_VALUE。

该操作包括以下特殊情况

用户可以通过设置 *alpha=*beta=0 将矩阵 C 重置为零。

用户可以通过设置 *alpha=1 和 *beta=0 来转置矩阵 A。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
transa		输入	运算 op(A)，它是非转置或（共轭）转置。
transb		输入	运算 op(B) 是非转置或（共轭）转置。
m		输入	矩阵 op(A) 和 C 的行数。
n		输入	矩阵 op(B) 和 C 的列数。
alpha	主机或设备	输入	<type> 用于乘法的标量。 如果 *alpha == 0，则 A 不必是有效的输入。
A	设备	输入	<type> 维度为 lda x n 的数组，如果 transa == CUBLAS_OP_N，则 lda >= max(1, m)；否则，维度为 lda x m，且 lda >= max(1, n)。
lda		输入	用于存储矩阵 A 的二维数组的Leading Dimension（主导维度）。
B	设备	输入	<type> 维度为 ldb x n 的数组，如果 transb == CUBLAS_OP_N，则 ldb >= max(1, m)；否则，维度为 ldb x m，且 ldb>=max(1,n)。
ldb		输入	用于存储矩阵 B 的二维数组的 Leading Dimension（主导维度）。
beta	主机或设备	输入	<type> 用于乘法的标量。 如果 *beta == 0，则 B 不必是有效的输入。
C	设备	输出	维度为 ldc x n 的 <type> 数组，且 ldc >= max(1, m)。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0 或 n < 0，或者 如果 transa 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 transb 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果当 transa == CUBLAS_OP_N 时 lda < max(1, m)，否则如果 lda < max(1, n)，或者 如果当 transb == CUBLAS_OP_N 时 ldb < max(1, m)，否则如果 ldb < max(1, n)，或者 如果 ldc < max(1, m)，或者 如果 A == C 并且 (transa != CUBLAS_OP_N) \|\| (lda != ldc)，或者 如果 B == C 并且 (transb != CUBLAS_OP_N) \|\| (ldb != ldc)，或者 如果 alpha 或 beta 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

2.8.2. cublas<t>dgmm()

cublasStatus_t cublasSdgmm(cublasHandle_t handle, cublasSideMode_t mode,
                          int m, int n,
                          const float           *A, int lda,
                          const float           *x, int incx,
                          float           *C, int ldc)
cublasStatus_t cublasDdgmm(cublasHandle_t handle, cublasSideMode_t mode,
                          int m, int n,
                          const double          *A, int lda,
                          const double          *x, int incx,
                          double          *C, int ldc)
cublasStatus_t cublasCdgmm(cublasHandle_t handle, cublasSideMode_t mode,
                          int m, int n,
                          const cuComplex       *A, int lda,
                          const cuComplex       *x, int incx,
                          cuComplex       *C, int ldc)
cublasStatus_t cublasZdgmm(cublasHandle_t handle, cublasSideMode_t mode,
                          int m, int n,
                          const cuDoubleComplex *A, int lda,
                          const cuDoubleComplex *x, int incx,
                          cuDoubleComplex *C, int ldc)

此函数支持 64 位整数接口。

此函数执行矩阵-矩阵乘法

\(C = \left\{ \begin{matrix} {A \times diag(X)} & {\text{if }\textsf{mode == $\mathrm{CUBLAS\_SIDE\_RIGHT}$}} \\ {diag(X) \times A} & {\text{if }\textsf{mode == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ \end{matrix} \right.\)

其中 \(A\) 和 \(C\) 是以列优先格式存储的矩阵，其维度为 \(m \times n\)。 如果 mode == CUBLAS_SIDE_RIGHT，则 \(X\) 是大小为 \(n\) 的向量；如果 mode == CUBLAS_SIDE_LEFT，则 \(X\) 是大小为 \(m\) 的向量。 \(X\) 是从步幅为 incx 的一维数组 x 中收集的。 incx 的绝对值是步幅，而 incx 的符号是步幅的方向。 如果 incx 为正，则我们从第一个元素向前移动 x。 否则，我们从最后一个元素向后移动 x。 X 的公式为

\(X\lbrack j\rbrack = \left\{ \begin{matrix} {x\lbrack j \times incx\rbrack} & {\text{if }incx \geq 0} \\ {x\lbrack(\chi - 1) \times |incx| - j \times |incx|\rbrack} & {\text{if }incx < 0} \\ \end{matrix} \right.\)

其中如果 mode == CUBLAS_SIDE_LEFT，则 \(\chi = m\)；如果 mode == CUBLAS_SIDE_RIGHT，则 \(\chi = n\)。

示例 1：如果用户想要执行 \(diag(diag(B)) \times A\)，则 \(incx = ldb + 1\)，其中 \(ldb\) 是矩阵 B 的前导维度，可以是行优先或列优先。

示例 2：如果用户想要执行 \(\alpha \times A\)，则有两种选择，要么使用 *beta=0 和 transa == CUBLAS_OP_N 的 cublas<t>geam()，要么使用 incx=0 和 x[0]=alpha 的 cublas<t>dgmm()。

该操作是异地的。 仅当 lda = ldc 时，就地操作才有效。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
模式		输入	如果 mode == CUBLAS_SIDE_LEFT 则为左乘，如果 mode == CUBLAS_SIDE_RIGHT 则为右乘
m		输入	矩阵 A 和 C 的行数。
n		输入	矩阵 A 和 C 的列数。
A	设备	输入	<type> 维度为 lda x n 的数组，且 lda >= max(1, m)
lda		输入	用于存储矩阵 A 的二维数组的Leading Dimension（主导维度）。
x	设备	输入	一维 <type> 数组，如果 mode == CUBLAS_SIDE_LEFT，则大小为 abs(incx) x m；如果 mode == CUBLAS_SIDE_RIGHT，则大小为 abs(incx) x n
incx		输入	一维数组 x 的步幅。
C	设备	输入/输出	维度为 ldc x n 的 <type> 数组，且 ldc >= max(1, m)。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0 或 n < 0，或者 如果 mode 不是 CUBLAS_SIDE_LEFT 和 CUBLAS_SIDE_RIGHT 之一，或者 如果 lda < max(1, m)，或者 如果 ldc < max(1, m)
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

2.8.3. cublas<t>getrfBatched()

cublasStatus_t cublasSgetrfBatched(cublasHandle_t handle,
                                   int n,
                                   float *const Aarray[],
                                   int lda,
                                   int *PivotArray,
                                   int *infoArray,
                                   int batchSize);

cublasStatus_t cublasDgetrfBatched(cublasHandle_t handle,
                                   int n,
                                   double *const Aarray[],
                                   int lda,
                                   int *PivotArray,
                                   int *infoArray,
                                   int batchSize);

cublasStatus_t cublasCgetrfBatched(cublasHandle_t handle,
                                   int n,
                                   cuComplex *const Aarray[],
                                   int lda,
                                   int *PivotArray,
                                   int *infoArray,
                                   int batchSize);

cublasStatus_t cublasZgetrfBatched(cublasHandle_t handle,
                                   int n,
                                   cuDoubleComplex *const Aarray[],
                                   int lda,
                                   int *PivotArray,
                                   int *infoArray,
                                   int batchSize);

Aarray 是指向以列优先格式存储的矩阵数组的指针，矩阵的维度为 nxn，前导维度为 lda。

此函数对每个 Aarray[i] 执行 LU 分解，其中 i = 0, …, batchSize-1，分解公式如下

\(\text{P}\text{*}{Aarray}\lbrack i\rbrack = L\text{*}U\)

其中 P 是置换矩阵，表示带行交换的部分主元法。L 是对角线为单位元素的下三角矩阵，U 是上三角矩阵。

形式上，P 由置换矩阵 Pj 的乘积写成，对于 j = 1,2,...,n，例如 P = P1 * P2 * P3 * .... * Pn。Pj 是一个置换矩阵，当执行 Pj*x 时，它会交换向量 x 的两行。Pj 可以通过 PivotArray[i] 的第 j 个元素用以下 Matlab 代码构建

// In Matlab PivotArray[i] is an array of base-1.
// In C, PivotArray[i] is base-0.
Pj = eye(n);
swap Pj(j,:) and Pj(PivotArray[i][j]  ,:)

L 和 U 被写回原始矩阵 A，并且 L 的对角线元素被丢弃。 L 和 U 可以通过以下 Matlab 代码构建

// A is a matrix of nxn after getrf.
L = eye(n);
for j = 1:n
    L(j+1:n,j) = A(j+1:n,j)
end
U = zeros(n);
for i = 1:n
    U(i,i:n) = A(i,i:n)
end

如果矩阵 A(=Aarray[i]) 是奇异的，getrf 仍然有效，并且 info(=infoArray[i]) 的值报告 LU 分解无法进行的第一个行索引。如果 info 是 k，则 U(k,k) 为零。方程 P*A=L*U 仍然成立，但是 L 和 U 的重建需要不同的 Matlab 代码，如下所示

// A is a matrix of nxn after getrf.
// info is k, which means U(k,k) is zero.
L = eye(n);
for j = 1:k-1
    L(j+1:n,j) = A(j+1:n,j)
end
U = zeros(n);
for i = 1:k-1
    U(i,i:n) = A(i,i:n)
end
for i = k:n
    U(i,k:n) = A(i,k:n)
end

此函数旨在用于小尺寸矩阵，其中启动开销是一个重要因素。

如果 PivotArray 为 NULL，cublas<t>getrfBatched 支持非主元 LU 分解。

cublas<t>getrfBatched 支持任意维度。

cublas<t>getrfBatched 仅支持计算能力 2.0 或更高版本。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
n		输入	Aarray[i] 的行数和列数。
Aarray	设备	输入/输出	指向 <type> 数组的指针数组，每个数组的维度为 n x n，其中 lda >= max(1, n)。矩阵 Aarray[i] 不应重叠；否则，会产生未定义的行为。
lda		输入	用于存储每个矩阵 Aarray[i] 的二维数组的前导维度。
PivotArray	设备	输出	大小为 n x batchSize 的数组，其中包含以线性方式存储的每个 Aarray[i] 分解的主元序列。 如果 PivotArray 为 NULL，则禁用主元。
infoArray	设备	输出	大小为 batchSize 的数组，其中 info(=infoArray[i]) 包含 Aarray[i] 分解的信息。 如果 info=0，则执行成功。 如果 info = -j，则第 j 个参数具有非法值。 如果 info = k，则 U(k,k) 为 0。分解已完成，但 U 是精确奇异的。
batchSize		输入	A 中包含的指针数量

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	参数 n < 0 或 batchSize < 0 或 lda <0
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

sgeqrf(), dgeqrf(), cgeqrf(), zgeqrf()

2.8.4. cublas<t>getrsBatched()

cublasStatus_t cublasSgetrsBatched(cublasHandle_t handle,
                                   cublasOperation_t trans,
                                   int n,
                                   int nrhs,
                                   const float *const Aarray[],
                                   int lda,
                                   const int *devIpiv,
                                   float *const Barray[],
                                   int ldb,
                                   int *info,
                                   int batchSize);

cublasStatus_t cublasDgetrsBatched(cublasHandle_t handle,
                                   cublasOperation_t trans,
                                   int n,
                                   int nrhs,
                                   const double *const Aarray[],
                                   int lda,
                                   const int *devIpiv,
                                   double *const Barray[],
                                   int ldb,
                                   int *info,
                                   int batchSize);

cublasStatus_t cublasCgetrsBatched(cublasHandle_t handle,
                                   cublasOperation_t trans,
                                   int n,
                                   int nrhs,
                                   const cuComplex *const Aarray[],
                                   int lda,
                                   const int *devIpiv,
                                   cuComplex *const Barray[],
                                   int ldb,
                                   int *info,
                                   int batchSize);

cublasStatus_t cublasZgetrsBatched(cublasHandle_t handle,
                                   cublasOperation_t trans,
                                   int n,
                                   int nrhs,
                                   const cuDoubleComplex *const Aarray[],
                                   int lda,
                                   const int *devIpiv,
                                   cuDoubleComplex *const Barray[],
                                   int ldb,
                                   int *info,
                                   int batchSize);

此函数求解形式如下的线性方程组数组

\(\text{op}(A\lbrack i \rbrack) X\lbrack i\rbrack = B\lbrack i\rbrack\)

其中 \(A\lbrack i\rbrack\) 是已使用主元法进行 LU 分解的矩阵，\(X\lbrack i\rbrack\) 和 \(B\lbrack i\rbrack\) 是 \(n \times {nrhs}\) 矩阵。此外，对于矩阵 \(A\)

\(\text{op}(A\lbrack i\rbrack) = \left\{ \begin{matrix} {A\lbrack i\rbrack} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A^{T}\lbrack i\rbrack} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_T}$}} \\ {A^{H}\lbrack i\rbrack} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

此函数旨在用于小尺寸矩阵，其中启动开销是一个重要因素。

如果 devIpiv 为 NULL，cublas<t>getrsBatched() 支持非主元 LU 分解。

cublas<t>getrsBatched() 支持任意维度。

cublas<t>getrsBatched() 仅支持计算能力 2.0 或更高版本。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
trans		输入	运算 op(A)，它是非转置或（共轭）转置。
n		输入	Aarray[i] 的行数和列数。
nrhs		输入	Barray[i] 的列数。
Aarray	设备	输入	指向 <type> 数组的指针数组，每个数组的维度为 n x n，其中 lda >= max(1, n)。
lda		输入	用于存储每个矩阵 Aarray[i] 的二维数组的前导维度。
devIpiv	设备	输入	大小为 n x batchSize 的数组，其中包含以线性方式存储的每个 Aarray[i] 分解的主元序列。 如果 devIpiv 为 NULL，则所有 Aarray[i] 的主元都被忽略。
Barray	设备	输入/输出	指向 <type> 数组的指针数组，每个数组的维度为 n x nrhs，其中 ldb >= max(1, n)。矩阵 Barray[i] 不应重叠；否则，会产生未定义的行为。
ldb		输入	用于存储每个解矩阵 Barray[i] 的二维数组的前导维度。
info	主机	输出	如果 info=0，则执行成功。 如果 info = -j，则第 j 个参数具有非法值。
batchSize		输入	A 中包含的指针数量

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0 或 nrhs < 0，或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 <type> 维度为 lda x n 的数组，其中 lda >= max(1, n)。 如果 ldb < max(1, n)
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

sgeqrs(), dgeqrs(), cgeqrs(), zgeqrs()

2.8.5. cublas<t>getriBatched()

cublasStatus_t cublasSgetriBatched(cublasHandle_t handle,
                                   int n,
                                   const float *const Aarray[],
                                   int lda,
                                   int *PivotArray,
                                   float *const Carray[],
                                   int ldc,
                                   int *infoArray,
                                   int batchSize);

cublasStatus_t cublasDgetriBatched(cublasHandle_t handle,
                                   int n,
                                   const double *const Aarray[],
                                   int lda,
                                   int *PivotArray,
                                   double *const Carray[],
                                   int ldc,
                                   int *infoArray,
                                   int batchSize);

cublasStatus_t cublasCgetriBatched(cublasHandle_t handle,
                                   int n,
                                   const cuComplex *const Aarray[],
                                   int lda,
                                   int *PivotArray,
                                   cuComplex *const Carray[],
                                   int ldc,
                                   int *infoArray,
                                   int batchSize);

cublasStatus_t cublasZgetriBatched(cublasHandle_t handle,
                                   int n,
                                   const cuDoubleComplex *const Aarray[],
                                   int lda,
                                   int *PivotArray,
                                   cuDoubleComplex *const Carray[],
                                   int ldc,
                                   int *infoArray,
                                   int batchSize);

Aarray 和 Carray 是指向以列优先格式存储的矩阵数组的指针，矩阵的维度为 n*n，前导维度分别为 lda 和 ldc。

此函数对 i = 0, …, batchSize-1 的矩阵 A[i] 执行求逆。

在调用 cublas<t>getriBatched 之前，必须先使用例程 cublas<t>getrfBatched 对矩阵 A[i] 进行分解。 在调用 cublas<t>getrfBatched 之后，由 Aarray[i] 指向的矩阵将包含矩阵 A[i] 的 LU 因子，而由 (PivotArray+i) 指向的向量将包含主元序列。

在 LU 分解之后，cublas<t>getriBatched 使用前向和后向三角求解器来完成 i = 0, …, batchSize-1 的矩阵 A[i] 的求逆。 求逆是异地的，因此 Carray[i] 的内存空间不能与 Array[i] 的内存空间重叠。

通常，cublas<t>getrfBatched 中的所有参数都将传递到 cublas<t>getriBatched 中。 例如，

// step 1: perform in-place LU decomposition, P*A = L*U.
//      Aarray[i] is n*n matrix A[i]
    cublasDgetrfBatched(handle, n, Aarray, lda, PivotArray, infoArray, batchSize);
//      check infoArray[i] to see if factorization of A[i] is successful or not.
//      Array[i] contains LU factorization of A[i]

// step 2: perform out-of-place inversion, Carray[i] = inv(A[i])
    cublasDgetriBatched(handle, n, Aarray, lda, PivotArray, Carray, ldc, infoArray, batchSize);
//      check infoArray[i] to see if inversion of A[i] is successful or not.

用户可以从 cublas<t>getrfBatched 或 cublas<t>getriBatched 检查奇异性。

此函数旨在用于小尺寸矩阵，其中启动开销是一个重要因素。

如果 cublas<t>getrfBatched 是通过非主元法执行的，则 cublas<t>getriBatched 的 PivotArray 应为 NULL。

cublas<t>getriBatched 支持任意维度。

cublas<t>getriBatched 仅支持计算能力 2.0 或更高版本。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
n		输入	Aarray[i] 的行数和列数。
Aarray	设备	输入	指向 <type> 数组的指针数组，每个数组的维度为 n*n，其中 lda >= max(1, n)。
lda		输入	用于存储每个矩阵 Aarray[i] 的二维数组的前导维度。
PivotArray	设备	输出	大小为 n*batchSize 的数组，其中包含以线性方式存储的每个 Aarray[i] 分解的主元序列。 如果 PivotArray 为 NULL，则禁用主元。
Carray	设备	输出	指向 <type> 数组的指针数组，每个数组的维度为 n*n，其中 ldc >= max(1, n)。矩阵 Carray[i] 不应重叠；否则，会产生未定义的行为。
ldc		输入	用于存储每个矩阵 Carray[i] 的二维数组的前导维度。
infoArray	设备	输出	大小为 batchSize 的数组，其中 info(=infoArray[i]) 包含 A[i] 求逆的信息。 如果 info=0，则执行成功。 如果 info = k，则 U(k,k) 为 0。U 是精确奇异的，求逆失败。
batchSize		输入	A 中包含的指针数量

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0 或 lda < 0 或 ldc < 0 或 batchSize < 0，或者 如果 lda < n 或 ldc < n
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

2.8.6. cublas<t>matinvBatched()

cublasStatus_t cublasSmatinvBatched(cublasHandle_t handle,
                                    int n,
                                    const float *const A[],
                                    int lda,
                                    float *const Ainv[],
                                    int lda_inv,
                                    int *info,
                                    int batchSize);

cublasStatus_t cublasDmatinvBatched(cublasHandle_t handle,
                                    int n,
                                    const double *const A[],
                                    int lda,
                                    double *const Ainv[],
                                    int lda_inv,
                                    int *info,
                                    int batchSize);

cublasStatus_t cublasCmatinvBatched(cublasHandle_t handle,
                                    int n,
                                    const cuComplex *const A[],
                                    int lda,
                                    cuComplex *const Ainv[],
                                    int lda_inv,
                                    int *info,
                                    int batchSize);

cublasStatus_t cublasZmatinvBatched(cublasHandle_t handle,
                                    int n,
                                    const cuDoubleComplex *const A[],
                                    int lda,
                                    cuDoubleComplex *const Ainv[],
                                    int lda_inv,
                                    int *info,
                                    int batchSize);

A 和 Ainv 是指向以列优先格式存储的矩阵数组的指针，矩阵的维度为 n*n，前导维度分别为 lda 和 lda_inv。

此函数对 i = 0, …, batchSize-1 的矩阵 A[i] 执行求逆。

此函数是 cublas<t>getrfBatched() 加上 cublas<t>getriBatched() 的快捷方式。但是，如果 n 大于 32，则此函数不起作用。否则，用户必须通过 cublas<t>getrfBatched() 和 cublas<t>getriBatched()。

如果矩阵 A[i] 是奇异的，则 info[i] 报告奇异性，与 cublas<t>getrfBatched() 相同。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
n		输入	A[i] 的行数和列数。
A	设备	输入	指向 <type> 数组的指针数组，每个数组的维度为 n*n，其中 lda >= max(1, n)。
lda		输入	用于存储每个矩阵 A[i] 的二维数组的前导维度。
Ainv	设备	输出	指向 <type> 数组的指针数组，每个数组的维度为 n*n，其中 lda_inv >= max(1, n)。矩阵 Ainv[i] 不应重叠；否则，会产生未定义的行为。
lda_inv		输入	用于存储每个矩阵 Ainv[i] 的二维数组的前导维度。
info	设备	输出	大小为 batchSize 的数组，其中 info[i] 包含 A[i] 求逆的信息。 如果 info[i] == 0，则执行成功。 如果 info[i] == k，则 U(k, k) == 0。U 是精确奇异的，求逆失败。
batchSize		输入	A 中包含的指针数量。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0 或 lda < 0 或 lda_inv < 0 或 batchSize < 0，或者 如果 lda < n 或 lda_inv < n，或者 如果 n > 32
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

2.8.7. cublas<t>geqrfBatched()

cublasStatus_t cublasSgeqrfBatched( cublasHandle_t handle,
                                    int m,
                                    int n,
                                    float *const Aarray[],
                                    int lda,
                                    float *const TauArray[],
                                    int *info,
                                    int batchSize);

cublasStatus_t cublasDgeqrfBatched( cublasHandle_t handle,
                                    int m,
                                    int n,
                                    double *const Aarray[],
                                    int lda,
                                    double *const TauArray[],
                                    int *info,
                                    int batchSize);

cublasStatus_t cublasCgeqrfBatched( cublasHandle_t handle,
                                    int m,
                                    int n,
                                    cuComplex *const Aarray[],
                                    int lda,
                                    cuComplex *const TauArray[],
                                    int *info,
                                    int batchSize);

cublasStatus_t cublasZgeqrfBatched( cublasHandle_t handle,
                                    int m,
                                    int n,
                                    cuDoubleComplex *const Aarray[],
                                    int lda,
                                    cuDoubleComplex *const TauArray[],
                                    int *info,
                                    int batchSize);

Aarray 是指向以列优先格式存储的矩阵数组的指针，矩阵的维度为 m x n，前导维度为 lda。TauArray 是指向维度至少为 max (1, min(m, n) 的向量数组的指针。

此函数使用 Householder 反射对 i = 0, ...,batchSize-1 的每个 Aarray[i] 执行 QR 分解。每个矩阵 Q[i] 表示为基本反射器的乘积，并存储在每个 Aarray[i] 的下部，如下所示

Q[j] = H[j][1] H[j][2] . . . H[j](k), where k = min(m,n).

每个 H[j][i] 的形式为

H[j][i] = I - tau[j] * v * v'

其中 tau[j] 是实标量，v 是实向量，其中 v(1:i-1) = 0 且 v(i) = 1；v(i+1:m) 在退出时存储在 Aarray[j][i+1:m,i] 中，tau 存储在 TauArray[j][i] 中。

此函数旨在用于小尺寸矩阵，其中启动开销是一个重要因素。

cublas<t>geqrfBatched 支持任意维度。

cublas<t>geqrfBatched 仅支持计算能力 2.0 或更高版本。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
m		输入	Aarray[i] 的行数。
n		输入	Aarray[i] 的列数。
Aarray	设备	输入	指向 <type> 数组的指针数组，每个数组的维度为 m x n，其中 lda >= max(1, m)。
lda		输入	用于存储每个矩阵 Aarray[i] 的二维数组的前导维度。
TauArray	设备	输出	指向 <type> 向量的指针数组，每个向量的维度为 max(1 ,min(m, n))。
info	主机	输出	如果 info == 0，则传递给函数的参数有效 如果 info < 0，则位置 -info 中的参数无效
batchSize		输入	Aarray 中包含的指针数量

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0 或 n < 0 或 batchSize < 0，或者 如果 lda < max(1, m)
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

sgeqrf(), dgeqrf(), cgeqrf(), zgeqrf()

2.8.8. cublas<t>gelsBatched()

cublasStatus_t cublasSgelsBatched( cublasHandle_t handle,
                                   cublasOperation_t trans,
                                   int m,
                                   int n,
                                   int nrhs,
                                   float *const Aarray[],
                                   int lda,
                                   float *const Carray[],
                                   int ldc,
                                   int *info,
                                   int *devInfoArray,
                                   int batchSize );

cublasStatus_t cublasDgelsBatched( cublasHandle_t handle,
                                   cublasOperation_t trans,
                                   int m,
                                   int n,
                                   int nrhs,
                                   double *const Aarray[],
                                   int lda,
                                   double *const Carray[],
                                   int ldc,
                                   int *info,
                                   int *devInfoArray,
                                   int batchSize );

cublasStatus_t cublasCgelsBatched( cublasHandle_t handle,
                                   cublasOperation_t trans,
                                   int m,
                                   int n,
                                   int nrhs,
                                   cuComplex *const Aarray[],
                                   int lda,
                                   cuComplex *const Carray[],
                                   int ldc,
                                   int *info,
                                   int *devInfoArray,
                                   int batchSize );

cublasStatus_t cublasZgelsBatched( cublasHandle_t handle,
                                   cublasOperation_t trans,
                                   int m,
                                   int n,
                                   int nrhs,
                                   cuDoubleComplex *const Aarray[],
                                   int lda,
                                   cuDoubleComplex *const Carray[],
                                   int ldc,
                                   int *info,
                                   int *devInfoArray,
                                   int batchSize );

Aarray 是指向以列优先格式存储的矩阵数组的指针。Carray 是指向以列优先格式存储的矩阵数组的指针。

此函数查找一批超定系统的最小二乘解：它求解如下所述的最小二乘问题

minimize  || Carray[i] - Aarray[i]*Xarray[i] || , with i = 0, ...,batchSize-1

退出时，每个 Aarray[i] 都被其 QR 分解覆盖，每个 Carray[i] 都被最小二乘解覆盖

cublas<t>gelsBatched 仅支持非转置操作，并且仅求解超定系统 (m >= n)。

cublas<t>gelsBatched 仅支持计算能力 2.0 或更高版本。

此函数旨在用于小尺寸矩阵，其中启动开销是一个重要因素。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
trans		输入	op(Aarray[i]) 操作，即非转置或（共轭）转置。 目前仅支持非转置操作。
m		输入	如果 trans == CUBLAS_OP_N，则为每个 Aarray[i] 和 Carray[i] 的行数，否则为每个 Aarray[i] 的列数（目前不支持）。
n		输入	如果 trans == CUBLAS_OP_N，则为每个 Aarray[i] 的列数，否则为每个 Aarray[i] 和 Carray[i] 的行数（目前不支持）。
nrhs		输入	每个 Carray[i] 的列数。
Aarray	设备	输入/输出	指向 <type> 数组的指针数组，每个数组的维度为 m x n，其中如果 trans == CUBLAS_OP_N，则 lda >= max(1, m)，否则为 n x m，其中 lda >= max(1, n)（目前不支持）。矩阵 Aarray[i] 不应重叠；否则，行为未定义。
lda		输入	用于存储每个矩阵 Aarray[i] 的二维数组的前导维度。
Carray	设备	输入/输出	指向 <type> 数组的指针数组，每个数组的维度为 m x nrhs，其中如果 trans == CUBLAS_OP_N，则 ldc >= max(1, m)，否则为 n x nrhs，其中 lda >= max(1, n)（目前不支持）。矩阵 Carray[i] 不应重叠；否则，行为未定义。
ldc		输入	用于存储每个矩阵 Carray[i] 的二维数组的前导维度。
info	主机	输出	如果 info == 0，则传递给函数的参数有效 如果 info < 0，则位置 -info 中的参数无效
devInfoArray	设备	输出	可选的整数数组，维度为 batchsize。 如果非空，则 devInfoArray[i] == V 的每个元素具有以下含义 V == 0 : 第 i 个问题已成功解决 V > 0 : Aarray[i] 的第 V 个对角线元素为零。Aarray[i] 没有满秩。
batchSize		输入	Aarray 和 Carray 中包含的指针数量

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0 或 n < 0 或 nrhs < 0 或 batchSize < 0 或 如果 lda < max(1, m) 或 ldc < max(1, m)
CUBLAS_STATUS_NOT_SUPPORTED	参数 m <n 或 trans 与非转置不同。
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

sgels(), dgels(), cgels(), zgels()

2.8.9. cublas<t>tpttr()

cublasStatus_t cublasStpttr ( cublasHandle_t handle,
                              cublasFillMode_t uplo,
                              int n,
                              const float *AP,
                              float *A,
                              int lda );

cublasStatus_t cublasDtpttr ( cublasHandle_t handle,
                              cublasFillMode_t uplo,
                              int n,
                              const double *AP,
                              double *A,
                              int lda );

cublasStatus_t cublasCtpttr ( cublasHandle_t handle,
                              cublasFillMode_t uplo,
                              int n,
                              const cuComplex *AP,
                              cuComplex *A,
                              int lda );

cublasStatus_t cublasZtpttr ( cublasHandle_t handle,
                              cublasFillMode_t uplo
                              int n,
                              const cuDoubleComplex *AP,
                              cuDoubleComplex *A,
                              int lda );

此函数执行从三角压缩格式到三角格式的转换

如果 uplo == CUBLAS_FILL_MODE_LOWER，则 AP 的元素被复制到三角矩阵 A 的下三角部分，而 A 的上部保持不变。 如果 uplo == CUBLAS_FILL_MODE_UPPER，则 AP 的元素被复制到三角矩阵 A 的上三角部分，而 A 的下部保持不变。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 AP 是否包含矩阵 A 的下部或上部。
n		输入	矩阵 A 的行数和列数。
矩阵 \(A\) 的行数和列数。	设备	输入	AP
A	设备	输出	维度为 lda x n 的 <type> 数组，其中 lda >= max(1, n)。 A 的另一侧保持不变。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	<type> 以压缩格式存储的 \(A\) 数组。 如果 n < 0 或 k < 0，或者 <type> 维度为 lda x n 的数组，其中 lda >= max(1,n)。
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

stpttr(), dtpttr(), ctpttr(), ztpttr()

2.8.10. cublas<t>trttp()

cublasStatus_t cublasStrttp ( cublasHandle_t handle,
                              cublasFillMode_t uplo,
                              int n,
                              const float *A,
                              int lda,
                              float *AP );

cublasStatus_t cublasDtrttp ( cublasHandle_t handle,
                              cublasFillMode_t uplo,
                              int n,
                              const double *A,
                              int lda,
                              double *AP );

cublasStatus_t cublasCtrttp ( cublasHandle_t handle,
                              cublasFillMode_t uplo,
                              int n,
                              const cuComplex *A,
                              int lda,
                              cuComplex *AP );

cublasStatus_t cublasZtrttp ( cublasHandle_t handle,
                              cublasFillMode_t uplo,
                              int n,
                              const cuDoubleComplex *A,
                              int lda,
                              cuDoubleComplex *AP );

此函数执行从三角格式到三角压缩格式的转换

如果 uplo == CUBLAS_FILL_MODE_LOWER，则三角矩阵 A 的下三角部分被复制到数组 AP 中。 如果 uplo == CUBLAS_FILL_MODE_UPPER，则三角矩阵 A 的上三角部分被复制到数组 AP 中。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示引用矩阵 A 的下部还是上部。
n		输入	矩阵 A 的行数和列数。
A	设备	输入	<type> 维度为 lda x n 的数组，其中 lda >= max(1, n)。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
矩阵 \(A\) 的行数和列数。	设备	输出	以压缩格式存储 A 的 <type> 数组。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0 或 如果 n < 0 或 k < 0，或者 <type> 维度为 lda x n 的数组，其中 lda >= max(1,n)。
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

strttp(), dtrttp(), ctrttp(), ztrttp()

2.8.11. cublas<t>gemmEx()

cublasStatus_t cublasSgemmEx(cublasHandle_t handle,
                           cublasOperation_t transa,
                           cublasOperation_t transb,
                           int m,
                           int n,
                           int k,
                           const float    *alpha,
                           const void     *A,
                           cudaDataType_t Atype,
                           int lda,
                           const void     *B,
                           cudaDataType_t Btype,
                           int ldb,
                           const float    *beta,
                           void           *C,
                           cudaDataType_t Ctype,
                           int ldc)
cublasStatus_t cublasCgemmEx(cublasHandle_t handle,
                           cublasOperation_t transa,
                           cublasOperation_t transb,
                           int m,
                           int n,
                           int k,
                           const cuComplex *alpha,
                           const void      *A,
                           cudaDataType_t  Atype,
                           int lda,
                           const void      *B,
                           cudaDataType_t  Btype,
                           int ldb,
                           const cuComplex *beta,
                           void            *C,
                           cudaDataType_t  Ctype,
                           int ldc)

此函数支持 64 位整数接口。

此函数是 cublas<t>gemm() 的扩展。在此函数中，输入矩阵和输出矩阵可以具有较低的精度，但计算仍然以类型 <t> 完成。 例如，在 cublasSgemmEx() 的 float 类型和 cublasCgemmEx() 的 cuComplex 类型中。

\(C = \alpha\text{op}(A)\text{op}(B) + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(A\) 、 \(B\) 和 \(C\) 是以列优先格式存储的矩阵，其维度分别为 \(\text{op}(A)\) \(m \times k\) 、 \(\text{op}(B)\) \(k \times n\) 和 \(C\) \(m \times n\) 。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ A^{H} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

并且对于矩阵 \(B\) ，\(\text{op}(B)\) 的定义类似。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
transa		输入	运算 op(A)，它是非转置或（共轭）转置。
transb		输入	运算 op(B) 是非转置或（共轭）转置。
m		输入	矩阵 op(A) 和 C 的行数。
n		输入	矩阵 op(B) 和 C 的列数。
k		输入	op(A) 的列数和 op(B) 的行数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	维度为 lda x k 的 <type> 数组，如果 transa == CUBLAS_OP_N，则 lda >= max(1, m)；如果不是，则维度为 lda x m，且 lda >= max(1, k)。
Atype		输入	指定矩阵 A 数据类型的枚举。
lda		输入	用于存储矩阵 A 的二维数组的Leading Dimension（主导维度）。
B	设备	输入	维度为 ldb x n 的 <type> 数组，如果 transb == CUBLAS_OP_N，则 ldb >= max(1, k)；如果不是，则维度为 ldb x k，且 ldb>=max(1,n)。
Btype		输入	指定矩阵 B 数据类型的枚举。
ldb		输入	用于存储矩阵 B 的二维数组的 Leading Dimension（主导维度）。
beta	主机或设备	输入	用于乘法的 <type> 标量值。 如果 beta == 0，则 C 不必是有效的输入。
C	设备	输入/输出	维度为 ldc x n 的 <type> 数组，且 ldc >= max(1, m)。
Ctype		输入	指定矩阵 C 数据类型的枚举。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。

下面列出了 cublasSgemmEx() 支持的矩阵类型组合

C	A/B
CUDA_R_16BF	CUDA_R_16BF
CUDA_R_16F	CUDA_R_16F
CUDA_R_32F	CUDA_R_8I
	CUDA_R_16BF
	CUDA_R_16F
	CUDA_R_32F

下面列出了 cublasCgemmEx() 支持的矩阵类型组合

C	A/B
CUDA_C_32F	CUDA_C_8I
	CUDA_C_32F

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_ARCH_MISMATCH	cublasCgemmEx() 仅在架构能力等于或大于 5.0 的 GPU 上受支持
CUBLAS_STATUS_NOT_SUPPORTED	不支持参数 Atype、Btype 和 Ctype 的组合
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0 或 n < 0 或 k < 0，或者 如果 transa 和 transb 不是 CUBLAS_OP_N、 CUBLAS_OP_C、 CUBLAS_OP_T 之一，或者 如果当 transa == CUBLAS_OP_N 时 lda < max(1, m)，否则当 transa 不是 CUBLAS_OP_N 时 lda < max(1, k)，或者 如果当 transb == CUBLAS_OP_N 时 ldb < max(1, k)，否则当 transb 不是 CUBLAS_OP_N 时 ldb < max(1, n)，或者 如果 ldc < max(1, m)，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 和 CUBLAS_FILL_MODE_UPPER 之一，或者 如果当 beta 非零时 C 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

sgemm()

有关某些 GEMM 算法的数值行为的更多信息，请参阅 GEMM 算法数值行为 部分。

2.8.12. cublasGemmEx()

cublasStatus_t cublasGemmEx(cublasHandle_t handle,
                           cublasOperation_t transa,
                           cublasOperation_t transb,
                           int m,
                           int n,
                           int k,
                           const void    *alpha,
                           const void     *A,
                           cudaDataType_t Atype,
                           int lda,
                           const void     *B,
                           cudaDataType_t Btype,
                           int ldb,
                           const void    *beta,
                           void           *C,
                           cudaDataType_t Ctype,
                           int ldc,
                           cublasComputeType_t computeType,
                           cublasGemmAlgo_t algo)

#if defined(__cplusplus)
cublasStatus_t cublasGemmEx(cublasHandle_t handle,
                           cublasOperation_t transa,
                           cublasOperation_t transb,
                           int m,
                           int n,
                           int k,
                           const void     *alpha,
                           const void     *A,
                           cudaDataType   Atype,
                           int lda,
                           const void     *B,
                           cudaDataType   Btype,
                           int ldb,
                           const void     *beta,
                           void           *C,
                           cudaDataType   Ctype,
                           int ldc,
                           cudaDataType   computeType,
                           cublasGemmAlgo_t algo)
#endif

此函数支持 64 位整数接口。

此函数是 cublas<t>gemm() 的扩展，允许用户单独指定矩阵 A、B 和 C 的数据类型、计算精度和要运行的 GEMM 算法。本节后面列出了支持的参数组合。

注意

cublasGemmEx() 函数的第二个变体是为了向后兼容 C++ 应用程序代码而提供的，其中 computeType 参数的类型为 cudaDataType 而不是 cublasComputeType_t。C 应用程序仍然可以使用更新后的函数签名进行编译。

此函数仅在计算能力为 5.0 或更高版本的设备上受支持。

\(C = \alpha\text{op}(A)\text{op}(B) + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(A\) 、 \(B\) 和 \(C\) 是以列优先格式存储的矩阵，其维度分别为 \(\text{op}(A)\) \(m \times k\) 、 \(\text{op}(B)\) \(k \times n\) 和 \(C\) \(m \times n\) 。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ A^{H} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

并且对于矩阵 \(B\) ，\(\text{op}(B)\) 的定义类似。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
transa		输入	运算 op(A)，它是非转置或（共轭）转置。
transb		输入	运算 op(B) 是非转置或（共轭）转置。
m		输入	矩阵 op(A) 和 C 的行数。
n		输入	矩阵 op(B) 和 C 的列数。
k		输入	op(A) 的列数和 op(B) 的行数。
alpha	主机或设备	输入	A*B 的比例因子，其类型与 computeType 和 Ctype 相对应，详情请参见下表。
A	设备	输入	维度为 lda x k 的 <type> 数组，如果 transa == CUBLAS_OP_N，则 lda >= max(1, m)；如果不是，则维度为 lda x m，且 lda >= max(1, k)。
Atype		输入	指定矩阵 A 数据类型的枚举。
lda		输入	用于存储矩阵 A 的二维数组的Leading Dimension（主导维度）。
B	设备	输入	维度为 ldb x n 的 <type> 数组，如果 transb == CUBLAS_OP_N，则 ldb >= max(1, k)；如果不是，则维度为 ldb x k，且 ldb>=max(1,n)。
Btype		输入	指定矩阵 B 数据类型的枚举。
ldb		输入	用于存储矩阵 B 的二维数组的 Leading Dimension（主导维度）。
beta	主机或设备	输入	C 的比例因子，其类型与 computeType 和 Ctype 相对应，详情请参见下表。如果 beta == 0，则 C 不必是有效的输入。
C	设备	输入/输出	维度为 ldc x n 的 <type> 数组，且 ldc >= max(1, m)。
Ctype		输入	指定矩阵 C 数据类型的枚举。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。
computeType		输入	指定计算类型的枚举。
algo		输入	指定算法的枚举。参见 cublasGemmAlgo_t。

cublasGemmEx() 支持以下计算类型、比例类型、Atype/Btype 和 Ctype

计算类型	比例类型（alpha 和 beta）	Atype/Btype	Ctype
CUBLAS_COMPUTE_16F 或 CUBLAS_COMPUTE_16F_PEDANTIC	CUDA_R_16F	CUDA_R_16F	CUDA_R_16F
CUBLAS_COMPUTE_32I 或 CUBLAS_COMPUTE_32I_PEDANTIC	CUDA_R_32I	CUDA_R_8I	CUDA_R_32I
CUBLAS_COMPUTE_32F 或 CUBLAS_COMPUTE_32F_PEDANTIC	CUDA_R_32F	CUDA_R_16BF	CUDA_R_16BF
		CUDA_R_16F	CUDA_R_16F
		CUDA_R_8I	CUDA_R_32F
		CUDA_R_16BF	CUDA_R_32F
		CUDA_R_16F	CUDA_R_32F
		CUDA_R_32F	CUDA_R_32F
	CUDA_C_32F	CUDA_C_8I	CUDA_C_32F
		CUDA_C_32F	CUDA_C_32F
CUBLAS_COMPUTE_32F_FAST_16F 或 CUBLAS_COMPUTE_32F_FAST_16BF 或 CUBLAS_COMPUTE_32F_FAST_TF32	CUDA_R_32F	CUDA_R_32F	CUDA_R_32F
	CUDA_C_32F	CUDA_C_32F	CUDA_C_32F
CUBLAS_COMPUTE_64F 或 CUBLAS_COMPUTE_64F_PEDANTIC	CUDA_R_64F	CUDA_R_64F	CUDA_R_64F
	CUDA_C_64F	CUDA_C_64F	CUDA_C_64F

注意

CUBLAS_COMPUTE_32I 和 CUBLAS_COMPUTE_32I_PEDANTIC 计算类型仅在 A、B 为 4 字节对齐且 lda、ldb 为 4 的倍数时受支持。为了获得更好的性能，还建议满足 此处 列出的 IMMA 内核对规则数据排序的要求。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成。
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化。
CUBLAS_STATUS_ARCH_MISMATCH	cublasGemmEx() 仅在架构能力等于或大于 5.0 的 GPU 上受支持。
CUBLAS_STATUS_NOT_SUPPORTED	不支持参数 Atype、Btype 和 Ctype 或算法 algo 的组合。
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0 或 n < 0 或 k < 0，或者 如果 transa 和 transb 不是 CUBLAS_OP_N、 CUBLAS_OP_C、 CUBLAS_OP_T 之一，或者 如果当 transa == CUBLAS_OP_N 时 lda < max(1, m)，否则当 transa 不是 CUBLAS_OP_N 时 lda < max(1, k)，或者 如果当 transb == CUBLAS_OP_N 时 ldb < max(1, k)，否则当 transb 不是 CUBLAS_OP_N 时 ldb < max(1, n)，或者 如果 ldc < max(1, m)，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 和 CUBLAS_FILL_MODE_UPPER 之一，或者 如果当 beta 非零时 C 为 NULL 如果不支持 Atype 或 Btype 或 Ctype 或 algo
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动。

从 11.2 版本开始，使用类型化函数而不是扩展函数 (cublas**Ex()) 有助于在链接到静态 cuBLAS 库时减小二进制文件大小。

另请参阅：sgemm.()

有关某些 GEMM 算法的数值行为的更多信息，请参阅 GEMM 算法数值行为 部分。

2.8.13. cublasGemmBatchedEx()

cublasStatus_t cublasGemmBatchedEx(cublasHandle_t handle,
                            cublasOperation_t transa,
                            cublasOperation_t transb,
                            int m,
                            int n,
                            int k,
                            const void    *alpha,
                            const void     *const Aarray[],
                            cudaDataType_t Atype,
                            int lda,
                            const void     *const Barray[],
                            cudaDataType_t Btype,
                            int ldb,
                            const void    *beta,
                            void           *const Carray[],
                            cudaDataType_t Ctype,
                            int ldc,
                            int batchCount,
                            cublasComputeType_t computeType,
                            cublasGemmAlgo_t algo)

#if defined(__cplusplus)
cublasStatus_t cublasGemmBatchedEx(cublasHandle_t handle,
                            cublasOperation_t transa,
                            cublasOperation_t transb,
                            int m,
                            int n,
                            int k,
                            const void     *alpha,
                            const void     *const Aarray[],
                            cudaDataType   Atype,
                            int lda,
                            const void     *const Barray[],
                            cudaDataType   Btype,
                            int ldb,
                            const void     *beta,
                            void           *const Carray[],
                            cudaDataType   Ctype,
                            int ldc,
                            int batchCount,
                            cudaDataType   computeType,
                            cublasGemmAlgo_t algo)
#endif

此函数支持 64 位整数接口。

此函数是 cublas<t>gemmBatched() 的扩展，它执行批量矩阵的矩阵-矩阵乘法，并允许用户单独指定每个矩阵数组 A、B 和 C 的数据类型、计算精度和要运行的 GEMM 算法。与 cublas<t>gemmBatched() 一样，该批次被认为是“统一的”，即所有实例对于其各自的矩阵 A、B 和 C 都具有相同的维度 (m, n, k)、主导维度 (lda, ldb, ldc) 和转置 (transa, transb)。批次中每个实例的输入矩阵和输出矩阵的地址从调用者传递给函数的指针数组中读取。本节后面列出了支持的参数组合。

注意

cublasGemmBatchedEx() 函数的第二个变体是为了向后兼容 C++ 应用程序代码而提供的，其中 computeType 参数的类型为 cudaDataType 而不是 cublasComputeType_t。C 应用程序仍然可以使用更新后的函数签名进行编译。

\(C\lbrack i\rbrack = \alpha\text{op}(A\lbrack i\rbrack)\text{op}(B\lbrack i\rbrack) + \beta C\lbrack i\rbrack,\text{ for i } \in \lbrack 0,batchCount - 1\rbrack\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(A\) 、 \(B\) 和 \(C\) 是指向以列优先格式存储的矩阵的指针数组，其维度分别为 \(\text{op}(A\lbrack i\rbrack)\) \(m \times k\) 、 \(\text{op}(B\lbrack i\rbrack)\) \(k \times n\) 和 \(C\lbrack i\rbrack\) \(m \times n\) 。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ A^{H} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

并且对于矩阵 \(B\lbrack i\rbrack\) ，\(\text{op}(B\lbrack i\rbrack)\) 的定义类似。

注意

\(C\lbrack i\rbrack\) 矩阵不得重叠，即，各个 gemm 操作必须能够独立计算；否则，行为未定义。

在某些问题规模下，多次调用不同 CUDA 流中的 cublas<t>gemm() 可能比使用此 API 更有优势。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
transa		输入	运算 op(Aarray[i]) 是非转置或（共轭）转置。
transb		输入	运算 op(Barray[i]) 是非转置或（共轭）转置。
m		输入	矩阵 op(Aarray[i]) 和 Carray[i] 的行数。
n		输入	矩阵 op(Barray[i]) 和 Carray[i] 的列数。
k		输入	op(Aarray[i]) 的列数和 op(Barray[i]) 的行数。
alpha	主机或设备	输入	矩阵乘积的比例因子，其类型与 computeType 和 Ctype 相对应，详情请参见下表。
Aarray	设备	输入	指向 <Atype> 数组的指针数组，每个数组的维度为 lda x k，其中 lda >= max(1, m)（如果 transa == CUBLAS_OP_N）和 lda x m，其中 lda >= max(1, k)（否则）。 所有指针都必须满足某些对齐标准。请参阅下文了解详细信息。
Atype		输入	指定 Aarray 数据类型的枚举。
lda		输入	用于存储矩阵 Aarray[i] 的二维数组的主导维度。
Barray	设备	输入	指向 <Btype> 数组的指针数组，每个数组的维度为 ldb x n，其中 ldb >= max(1, k)（如果 transb == CUBLAS_OP_N）和 ldb x k，其中 ldb>=max(1,n)（否则）。 所有指针都必须满足某些对齐标准。请参阅下文了解详细信息。
Btype		输入	指定 Barray 数据类型的枚举。
ldb		输入	用于存储矩阵 Barray[i] 的二维数组的主导维度。
beta	主机或设备	输入	Carray 的比例因子，其类型与 computeType 和 Ctype 相对应，详情请参见下表。如果 beta == 0，则 Carray[i] 不必是有效的输入。
Carray	设备	输入/输出	指向 <Ctype> 数组的指针数组。它的维度为 ldc x n，其中 ldc >= max(1, m)。矩阵 Carray[i] 不应重叠；否则，行为未定义。 所有指针都必须满足某些对齐标准。请参阅下文了解详细信息。
Ctype		输入	指定 Carray 数据类型的枚举。
ldc		输入	用于存储每个矩阵 Carray[i] 的二维数组的主导维度。
batchCount		输入	Aarray、Barray 和 Carray 中包含的指针数量。
computeType		输入	指定计算类型的枚举。
algo		输入	指定算法的枚举。参见 cublasGemmAlgo_t。

cublasGemmBatchedEx() 支持以下计算类型、比例类型、Atype/Btype 和 Ctype

计算类型	比例类型（alpha 和 beta）	Atype/Btype	Ctype
CUBLAS_COMPUTE_16F 或 CUBLAS_COMPUTE_16F_PEDANTIC	CUDA_R_16F	CUDA_R_16F	CUDA_R_16F
CUBLAS_COMPUTE_32I 或 CUBLAS_COMPUTE_32I_PEDANTIC	CUDA_R_32I	CUDA_R_8I	CUDA_R_32I
CUBLAS_COMPUTE_32F 或 CUBLAS_COMPUTE_32F_PEDANTIC	CUDA_R_32F	CUDA_R_16BF	CUDA_R_16BF
		CUDA_R_16F	CUDA_R_16F
		CUDA_R_8I	CUDA_R_32F
		CUDA_R_16BF	CUDA_R_32F
		CUDA_R_16F	CUDA_R_32F
		CUDA_R_32F	CUDA_R_32F
	CUDA_C_32F	CUDA_C_8I	CUDA_C_32F
		CUDA_C_32F	CUDA_C_32F
CUBLAS_COMPUTE_32F_FAST_16F 或 CUBLAS_COMPUTE_32F_FAST_16BF 或 CUBLAS_COMPUTE_32F_FAST_TF32	CUDA_R_32F	CUDA_R_32F	CUDA_R_32F
	CUDA_C_32F	CUDA_C_32F	CUDA_C_32F
CUBLAS_COMPUTE_64F 或 CUBLAS_COMPUTE_64F_PEDANTIC	CUDA_R_64F	CUDA_R_64F	CUDA_R_64F
	CUDA_C_64F	CUDA_C_64F	CUDA_C_64F

如果 Atype 是 CUDA_R_16F 或 CUDA_R_16BF，或者 computeType 是任何 FAST 选项，或者当数学模式或 algo 启用快速数学模式时，放置在 GPU 内存中的指针（不是指针数组）必须正确对齐，以避免未对齐的内存访问错误。理想情况下，所有指针都至少对齐到 16 字节。否则，建议它们满足以下规则

• 如果 k%8==0，则确保 intptr_t(ptr) % 16 == 0，

• 如果 k%2==0，则确保 intptr_t(ptr) %  4 == 0。

注意

计算类型 CUBLAS_COMPUTE_32I 和 CUBLAS_COMPUTE_32I_PEDANTIC 仅在所有指针 A[i]、B[i] 为 4 字节对齐且 lda、ldb 为 4 的倍数时受支持。为了获得更好的性能，还建议满足 此处 列出的 IMMA 内核对规则数据排序的要求。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成。
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化。
CUBLAS_STATUS_ARCH_MISMATCH	cublasGemmBatchedEx() 仅在架构能力等于或大于 5.0 的 GPU 上受支持。
CUBLAS_STATUS_NOT_SUPPORTED	不支持参数 Atype、Btype 和 Ctype 或算法 algo 的组合。
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0 或 n < 0 或 k < 0，或者 如果 transa 和 transb 不是 CUBLAS_OP_N、 CUBLAS_OP_C、 CUBLAS_OP_T 之一，或者 如果当 transa == CUBLAS_OP_N 时 lda < max(1, m)，否则当 transa 不是 CUBLAS_OP_N 时 lda < max(1, k)，或者 如果当 transb == CUBLAS_OP_N 时 ldb < max(1, k)，否则当 transb 不是 CUBLAS_OP_N 时 ldb < max(1, n)，或者 如果 ldc < max(1, m)，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 和 CUBLAS_FILL_MODE_UPPER 之一，或者 如果不支持 Atype 或 Btype 或 Ctype 或 algo 或 computeType
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动。

另请参阅：sgemm.()

2.8.14. cublasGemmStridedBatchedEx()

cublasStatus_t cublasGemmStridedBatchedEx(cublasHandle_t handle,
                            cublasOperation_t transa,
                            cublasOperation_t transb,
                            int m,
                            int n,
                            int k,
                            const void    *alpha,
                            const void     *A,
                            cudaDataType_t Atype,
                            int lda,
                            long long int strideA,
                            const void     *B,
                            cudaDataType_t Btype,
                            int ldb,
                            long long int strideB,
                            const void    *beta,
                            void           *C,
                            cudaDataType_t Ctype,
                            int ldc,
                            long long int strideC,
                            int batchCount,
                            cublasComputeType_t computeType,
                            cublasGemmAlgo_t algo)

#if defined(__cplusplus)
cublasStatus_t cublasGemmStridedBatchedEx(cublasHandle_t handle,
                            cublasOperation_t transa,
                            cublasOperation_t transb,
                            int m,
                            int n,
                            int k,
                            const void    *alpha,
                            const void     *A,
                            cudaDataType Atype,
                            int lda,
                            long long int strideA,
                            const void     *B,
                            cudaDataType Btype,
                            int ldb,
                            long long int strideB,
                            const void    *beta,
                            void           *C,
                            cudaDataType Ctype,
                            int ldc,
                            long long int strideC,
                            int batchCount,
                            cudaDataType computeType,
                            cublasGemmAlgo_t algo)
#endif

此函数支持 64 位整数接口。

此函数是 cublas<t>gemmStridedBatched() 的扩展，它执行批量矩阵的矩阵-矩阵乘法，并允许用户单独指定每个矩阵 A、B 和 C 的数据类型、计算精度和要运行的 GEMM 算法。与 cublas<t>gemmStridedBatched() 一样，该批次被认为是“统一的”，即所有实例对于其各自的矩阵 A、B 和 C 都具有相同的维度 (m, n, k)、主导维度 (lda, ldb, ldc) 和转置 (transa, transb)。批次中每个实例的输入矩阵 A、B 和输出矩阵 C 位于距上一实例中位置的固定元素偏移量处。第一个实例的矩阵 A、B 和 C 的指针与元素数量的偏移量 - strideA、strideB 和 strideC 一起传递给函数，这些偏移量确定了未来实例中输入和输出矩阵的位置。

注意

cublasGemmStridedBatchedEx() 函数的第二个变体是为了向后兼容 C++ 应用程序代码而提供的，其中 computeType 参数的类型为 cudaDataType_t 而不是 cublasComputeType_t。C 应用程序仍然可以使用更新后的函数签名进行编译。

\(C + i*{strideC} = \alpha\text{op}(A + i*{strideA})\text{op}(B + i*{strideB}) + \beta(C + i*{strideC}),\text{ for i } \in \lbrack 0,batchCount - 1\rbrack\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(A\) 、 \(B\) 和 \(C\) 是指向以列优先格式存储的矩阵的指针数组，其维度分别为 \(\text{op}(A\lbrack i\rbrack)\) \(m \times k\) 、 \(\text{op}(B\lbrack i\rbrack)\) \(k \times n\) 和 \(C\lbrack i\rbrack\) \(m \times n\) 。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ A^{H} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

并且对于矩阵 \(B\lbrack i\rbrack\) ，\(\text{op}(B\lbrack i\rbrack)\) 的定义类似。

注意

\(C\lbrack i\rbrack\) 矩阵不得重叠，即，各个 gemm 操作必须能够独立计算；否则，行为未定义。

在某些问题规模下，多次调用不同 CUDA 流中的 cublas<t>gemm() 可能比使用此 API 更有优势。

注意

在下表中，我们使用 A[i]、B[i]、C[i] 作为批处理第 i 个实例中 A、B 和 C 矩阵的表示法，隐含地假设它们分别是从 A[i-1]、B[i-1]、C[i-1] 偏移 strideA、strideB、strideC 个元素。 偏移量的单位是元素数量，并且不得为零。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
transa		输入	运算 op(A[i]) 是非转置或（共轭）转置。
transb		输入	运算 op(B[i]) 是非转置或（共轭）转置。
m		输入	矩阵 op(A[i]) 和 C[i] 的行数。
n		输入	矩阵 op(B[i]) 和 C[i] 的列数。
k		输入	op(A[i]) 的列数和 op(B[i]) 的行数。
alpha	主机或设备	输入	A*B 的比例因子，其 <比例类型> 与 computeType 和 Ctype 相对应，详情请参见下表。
A	设备	输入	指向 <Atype> 矩阵 A 的指针，对应于批次的第一个实例，维度为 lda x k，其中 lda >= max(1, m)（如果 transa == CUBLAS_OP_N）和 lda x m，其中 lda >= max(1, k)（否则）。
Atype		输入	指定 A 数据类型的枚举。
lda		输入	用于存储矩阵 A[i] 的二维数组的主导维度。
strideA		输入	类型为 long long int 的值，给出 A[i] 和 A[i+1] 之间以元素数量为单位的偏移量。
B	设备	输入	指向 <Btype> 矩阵 B 的指针，对应于批次的第一个实例，维度为 ldb x n，其中 ldb >= max(1, k)（如果 transb == CUBLAS_OP_N）和 ldb x k，其中 ldb>=max(1,n)（否则）。
Btype		输入	指定 B 数据类型的枚举。
ldb		输入	用于存储矩阵 B[i] 的二维数组的前导维度。
strideB		输入	类型为 long long int 的值，给出 B[i] 和 B[i+1] 之间以元素数量为单位的偏移量。
beta	主机或设备	输入	C 的比例因子，其 <比例类型> 与 computeType 和 Ctype 相对应，详情请参见下表。如果 beta == 0，则 C[i] 不必是有效的输入。
C	设备	输入/输出	指向 <Ctype> 矩阵 C 的指针，对应于批次的第一个实例，维度为 ldc x n，其中 ldc >= max(1, m)。矩阵 C[i] 不应重叠；否则，将出现未定义的行为。
Ctype		输入	指定 C 数据类型的枚举。
ldc		输入	用于存储每个矩阵 C[i] 的二维数组的主导维度。
strideC		输入	类型为 long long int 的值，给出 C[i] 和 C[i+1] 之间以元素数量为单位的偏移量。
batchCount		输入	批处理中要执行的 GEMM 数量。
computeType		输入	指定计算类型的枚举。
algo		输入	指定算法的枚举。参见 cublasGemmAlgo_t。

cublasGemmStridedBatchedEx() 支持以下计算类型、比例类型、Atype/Btype 和 Ctype

计算类型	比例类型（alpha 和 beta）	Atype/Btype	Ctype
CUBLAS_COMPUTE_16F 或 CUBLAS_COMPUTE_16F_PEDANTIC	CUDA_R_16F	CUDA_R_16F	CUDA_R_16F
CUBLAS_COMPUTE_32I 或 CUBLAS_COMPUTE_32I_PEDANTIC	CUDA_R_32I	CUDA_R_8I	CUDA_R_32I
CUBLAS_COMPUTE_32F 或 CUBLAS_COMPUTE_32F_PEDANTIC	CUDA_R_32F	CUDA_R_16BF	CUDA_R_16BF
		CUDA_R_16F	CUDA_R_16F
		CUDA_R_8I	CUDA_R_32F
		CUDA_R_16BF	CUDA_R_32F
		CUDA_R_16F	CUDA_R_32F
		CUDA_R_32F	CUDA_R_32F
	CUDA_C_32F	CUDA_C_8I	CUDA_C_32F
		CUDA_C_32F	CUDA_C_32F
CUBLAS_COMPUTE_32F_FAST_16F 或 CUBLAS_COMPUTE_32F_FAST_16BF 或 CUBLAS_COMPUTE_32F_FAST_TF32	CUDA_R_32F	CUDA_R_32F	CUDA_R_32F
	CUDA_C_32F	CUDA_C_32F	CUDA_C_32F
CUBLAS_COMPUTE_64F 或 CUBLAS_COMPUTE_64F_PEDANTIC	CUDA_R_64F	CUDA_R_64F	CUDA_R_64F
	CUDA_C_64F	CUDA_C_64F	CUDA_C_64F

注意

计算类型 CUBLAS_COMPUTE_32I 和 CUBLAS_COMPUTE_32I_PEDANTIC 仅在所有指针 A[i]、B[i] 为 4 字节对齐且 lda、ldb 为 4 的倍数时受支持。为了获得更好的性能，还建议满足 此处 列出的 IMMA 内核对规则数据排序的要求。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成。
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化。
CUBLAS_STATUS_ARCH_MISMATCH	cublasGemmBatchedEx() 仅在架构能力等于或大于 5.0 的 GPU 上受支持。
CUBLAS_STATUS_NOT_SUPPORTED	不支持参数 Atype、Btype 和 Ctype 或算法 algo 的组合。
CUBLAS_STATUS_INVALID_VALUE	如果 m < 0 或 n < 0 或 k < 0，或者 如果 transa 和 transb 不是 CUBLAS_OP_N、 CUBLAS_OP_C、 CUBLAS_OP_T 之一，或者 如果当 transa == CUBLAS_OP_N 时 lda < max(1, m)，否则当 transa 不是 CUBLAS_OP_N 时 lda < max(1, k)，或者 如果当 transb == CUBLAS_OP_N 时 ldb < max(1, k)，否则当 transb 不是 CUBLAS_OP_N 时 ldb < max(1, n)，或者 如果 ldc < max(1, m)，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 和 CUBLAS_FILL_MODE_UPPER 之一，或者 如果不支持 Atype 或 Btype 或 Ctype 或 algo 或 computeType
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

另请参阅：sgemm.()

2.8.15. cublasGemmGroupedBatchedEx()

cublasStatus_t cublasGemmGroupedBatchedEx(cublasHandle_t handle,
                            const cublasOperation_t transa_array[],
                            const cublasOperation_t transb_array[],
                            const int m_array[],
                            const int n_array[],
                            const int k_array[],
                            const void    *alpha_array,
                            const void     *const Aarray[],
                            cudaDataType_t Atype,
                            const int lda_array[],
                            const void     *const Barray[],
                            cudaDataType_t Btype,
                            const int ldb_array[],
                            const void    *beta_array,
                            void           *const Carray[],
                            cudaDataType_t Ctype,
                            const int ldc_array[],
                            int group_count,
                            const int group_size[],
                            cublasComputeType_t computeType)

此函数支持 64 位整数接口。

此函数对矩阵组执行矩阵-矩阵乘法。 给定组被认为是“统一的”，即所有实例对于其各自的 A、B 和 C 矩阵都具有相同的维度 (m, n, k)、Leading Dimension（lda、ldb、ldc）和转置（transa、transb）。 但是，维度、Leading Dimension、转置和缩放因子（alpha、beta）在组之间可能有所不同。 批处理中每个实例的输入矩阵和输出矩阵的地址从调用者传递给函数的指针数组中读取。 这在功能上等同于以下内容

idx = 0;
for i = 0:group_count - 1
    for j = 0:group_size[i] - 1
        gemmEx(transa_array[i], transb_array[i], m_array[i], n_array[i], k_array[i],
               alpha_array[i], Aarray[idx], Atype, lda_array[i], Barray[idx], Btype,
               ldb_array[i], beta_array[i], Carray[idx], Ctype, ldc_array[i],
               computeType, CUBLAS_GEMM_DEFAULT);
        idx += 1;
    end
end

其中 \(\text{$\mathrm{alpha\_array}$}\) 和 \(\text{$\mathrm{beta\_array}$}\) 是缩放因子数组，\(\text{Aarray}\)、 \(\text{Barray}\) 和 \(\text{Carray}\) 是指向以列优先格式存储的矩阵的指针数组。 对于给定索引 \(\text{idx}\)，它是组 \(i\) 的一部分，维度为

• \(\text{op}(\text{Aarray}\lbrack\text{idx}\rbrack)\): \(\text{$\mathrm{m\_array}$}\lbrack i\rbrack \times \text{$\mathrm{k\_array}$}\lbrack i\rbrack\)

• \(\text{op}(\text{Barray}\lbrack\text{idx}\rbrack)\): \(\text{$\mathrm{k\_array}$}\lbrack i\rbrack \times \text{$\mathrm{n\_array}$}\lbrack i\rbrack\)

• \(\text{Carray}\lbrack\text{idx}\rbrack\): \(\text{$\mathrm{m\_array}$}\lbrack i\rbrack \times \text{$\mathrm{n\_array}$}\lbrack i\rbrack\)

注意

此 API 接受两种不同长度的数组。 维度数组、Leading Dimension 数组、转置数组和缩放因子数组的长度为 group_count，矩阵数组的长度为 problem_count，其中 \(\text{$\mathrm{problem\_count}$} = \sum_{i = 0}^{\text{$\mathrm{group\_count}$} - 1} \text{$\mathrm{group\_size}$}\lbrack i\rbrack\)

对于组 \(i\) 中的矩阵 \(A[\text{idx}]\)

\(\text{op}(A[\text{idx}]) = \left\{ \begin{matrix} A[\text{idx}] & {\text{if }\textsf{$\mathrm{transa\_array}\lbrack i\rbrack$ == $\mathrm{CUBLAS\_OP\_N}$}} \\ A[\text{idx}]^{T} & {\text{if }\textsf{$\mathrm{transa\_array}\lbrack i\rbrack$ == $\mathrm{CUBLAS\_OP\_T}$}} \\ A[\text{idx}]^{H} & {\text{if }\textsf{$\mathrm{transa\_array}\lbrack i\rbrack$ == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

并且对于组 \(i\) 中的矩阵 \(B[\text{idx}]\)，\(\text{op}(B[\text{idx}])\) 的定义类似。

注意

\(C\lbrack\text{idx}\rbrack\) 矩阵不得重叠，即，各个 gemm 运算必须是可独立计算的；否则，会产生未定义的行为。

在某些问题规模下，多次调用不同 CUDA 流中的 cublasGemmBatchedEx() 可能比使用此 API 更有优势。

参数。	内存	输入/输出	含义	数组长度
handle		输入	cuBLAS 库上下文的句柄。
transa_array	主机	输入	数组，包含每个组的运算 op(A[idx])，即非转置或（共轭）转置。	group_count
transb_array	主机	输入	数组，包含每个组的运算 op(B[idx])，即非转置或（共轭）转置。	group_count
m_array	主机	输入	包含每个组的矩阵 op(A[idx]) 和 C[idx] 的行数的数组。	group_count
n_array	主机	输入	包含每个组的矩阵 op(B[idx]) 和 C[idx] 的列数的数组。	group_count
k_array	主机	输入	包含每个组的 op(A[idx]) 的列数和 op(B[idx]) 的行数的数组。	group_count
alpha_array	主机	输入	数组，包含用于每个组的乘法的 <比例类型> 标量。	group_count
Aarray	设备	输入	指向 <Atype> 数组的指针数组，每个数组的维度为 lda[i] x k[i]，其中 lda[i]>=max(1,m[i])（如果 transa[i]==CUBLAS_OP_N）和 lda[i] x m[i]，其中 lda[i]>=max(1,k[i])（否则）。 所有指针都必须满足某些对齐标准。请参阅下文了解详细信息。	problem_count
Atype		输入	指定 A 数据类型的枚举。
lda_array	主机	输入	包含用于存储每个组的每个矩阵 A[idx] 的二维数组的 Leading Dimension（主导维度）的数组。	group_count
Barray	设备	输入	指向 <Btype> 数组的指针数组，每个数组的维度为 ldb[i] x n[i]，其中 ldb[i]>=max(1,k[i])（如果 transb[i]==CUBLAS_OP_N）和 ldb[i] x k[i]，其中 ldb[i]>=max(1,n[i])（否则）。 所有指针都必须满足某些对齐标准。请参阅下文了解详细信息。	problem_count
Btype		输入	指定 B 数据类型的枚举。
ldb_array	主机	输入	包含用于存储每个组的每个矩阵 B[idx] 的二维数组的 Leading Dimension（主导维度）的数组。	group_count
beta_array	主机	输入	数组，包含用于每个组的乘法的 <比例类型> 标量。	group_count
Carray	设备	输入/输出	指向 <Ctype> 数组的指针数组。它的维度为 ldc[i] x n[i]，其中 ldc[i]>=max(1,m[i])。矩阵 C[idx] 不应重叠；否则，将出现未定义的行为。 所有指针都必须满足某些对齐标准。请参阅下文了解详细信息。	problem_count
Ctype		输入	指定 C 数据类型的枚举。
ldc_array	主机	输入	包含用于存储每个组的每个矩阵 C[idx] 的二维数组的 Leading Dimension（主导维度）的数组。	group_count
group_count	主机	输入	组数
group_size	主机	输入	包含每个组的 Aarray、Barray 和 Carray 中包含的指针数量的数组。	group_count
computeType		输入	指定计算类型的枚举。

cublasGemmGroupedBatchedEx() 支持以下计算类型、比例类型、Atype/Btype 和 Ctype

计算类型	比例类型（alpha 和 beta）	Atype/Btype	Ctype
CUBLAS_COMPUTE_32F	CUDA_R_32F	CUDA_R_16BF	CUDA_R_16BF
		CUDA_R_16F	CUDA_R_16F
		CUDA_R_32F	CUDA_R_32F
CUBLAS_COMPUTE_32F_PEDANTIC	CUDA_R_32F	CUDA_R_32F	CUDA_R_32F
CUBLAS_COMPUTE_32F_FAST_TF32	CUDA_R_32F	CUDA_R_32F	CUDA_R_32F
CUBLAS_COMPUTE_64F 或 CUBLAS_COMPUTE_64F_PEDANTIC	CUDA_R_64F	CUDA_R_64F	CUDA_R_64F

如果 Atype 是 CUDA_R_16F 或 CUDA_R_16BF，或者如果 computeType 是任何 FAST 选项，则放置在 GPU 内存中的指针（不是指针数组）必须正确对齐，以避免未对齐的内存访问错误。理想情况下，所有指针都至少对齐到 16 字节。否则，要求它们满足以下规则

• 如果 (k * AtypeSize) % 16 == 0，则确保 intptr_t(ptr) % 16 == 0，

• 如果 (k * AtypeSize) % 4 == 0，则确保 intptr_t(ptr) % 4 == 0。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 transa_array、 transb_array、 m_array、 n_array、 k_array、 alpha_array、 lda_array、 ldb_array、 beta_array、 ldc_array 或 group_size 为 NULL，或者 如果 group_count < 0，或者 如果 m_array[i] < 0、 n_array[i] < 0、 k_array[i] < 0、 group_size[i] < 0，或者 如果 transa_array[i] 和 transb_array[i] 不是 CUBLAS_OP_N、 CUBLAS_OP_C、 CUBLAS_OP_T 之一，或者 如果当 transa_array[i] == CUBLAS_OP_N 时 lda_array[i] < max(1, m_array[i])，否则当 transa_array[i] 不是 CUBLAS_OP_N 时 lda_array[i] < max(1, k_array[i])，或者 如果当 transb_array[i] == CUBLAS_OP_N 时 ldb_array[i] < max(1, k_array[i])，否则当 transb_array[i] 不是 CUBLAS_OP_N 时 ldb_array[i] < max(1, n_array[i])，或者 如果 ldc_array[i] < max(1, m_array[i])
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动
CUBLAS_STATUS_NOT_SUPPORTED	指针模式设置为 CUBLAS_POINTER_MODE_DEVICE 不支持 Atype 或 Btype 或 Ctype 或 computeType

2.8.16. cublasCsyrkEx()

cublasStatus_t cublasCsyrkEx(cublasHandle_t handle,
                             cublasFillMode_t uplo,
                             cublasOperation_t trans,
                             int n,
                             int k,
                             const cuComplex *alpha,
                             const void      *A,
                             cudaDataType    Atype,
                             int lda,
                             const cuComplex *beta,
                             cuComplex       *C,
                             cudaDataType    Ctype,
                             int ldc)

此函数支持 64 位整数接口。

此函数是 cublasCsyrk() 的扩展，其中输入矩阵和输出矩阵可以具有较低的精度，但计算仍以 cuComplex 类型完成

此函数执行对称秩- \(k\) 更新

\(C = \alpha\text{op}(A)\text{op}(A)^{T} + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以较低或较高模式存储的对称矩阵，而 \(A\) 是维度为 \(\text{op}(A)\) \(n \times k\) 的矩阵。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ \end{matrix} \right.\)

注意

此例程仅在架构能力等于或大于 5.0 的 GPU 上受支持

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 C 的下半部分或上半部分是否存储，另一个对称部分不被引用，而是从存储的元素推断出来。
trans		输入	运算 op(A)，为非转置或转置。
n		输入	矩阵 op(A) 和 C 的行数。
k		输入	矩阵 op(A) 的列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	<type> 维度为 lda x k 的数组，如果 trans == CUBLAS_OP_N，则 lda >= max(1, n)；否则，维度为 lda x n，且 lda >= max(1, k)。
Atype		输入	指定矩阵 A 数据类型的枚举。
lda		输入	用于存储矩阵 A 的二维数组的前导维度。
beta	主机或设备	输入	用于乘法的 <type> 标量值。 如果 beta == 0，则 C 不必是有效的输入。
C	设备	输入/输出	<type> 维度为 ldc x n 的数组，且 ldc >= max(1, n)。
Ctype		输入	指定矩阵 C 数据类型的枚举。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。

下面列出了 cublasCsyrkEx() 支持的矩阵类型组合

A	C
CUDA_C_8I	CUDA_C_32F
CUDA_C_32F	CUDA_C_32F

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成。
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化。
CUBLAS_STATUS_INVALID_VALUE	<type> 维度为 lda x n 的数组，其中 lda >= k + 1。 如果 n < 0 或 k < 0，或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 lda < max(1, n)（如果 trans == CUBLAS_OP_N）和 lda < max(1, k)（否则），或者 如果 ldc < max(1, n)，或者 如果不支持 Atype 或 Ctype
CUBLAS_STATUS_NOT_SUPPORTED	不支持参数 Atype 和 Ctype 的组合。
CUBLAS_STATUS_ARCH_MISMATCH	设备具有低于 5.0 的计算能力。
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动。

有关参考，请参阅 NETLIB 文档

ssyrk(), dsyrk(), csyrk(), zsyrk()

2.8.17. cublasCsyrk3mEx()

cublasStatus_t cublasCsyrk3mEx(cublasHandle_t handle,
                               cublasFillMode_t uplo,
                               cublasOperation_t trans,
                               int n,
                               int k,
                               const cuComplex *alpha,
                               const void      *A,
                               cudaDataType    Atype,
                               int lda,
                               const cuComplex *beta,
                               cuComplex       *C,
                               cudaDataType    Ctype,
                               int ldc)

此函数支持 64 位整数接口。

此函数是 cublasCsyrk() 的扩展，其中输入矩阵和输出矩阵可以具有较低的精度，但计算仍以 cuComplex 类型完成。此例程使用高斯复杂度降低算法实现，该算法可以使性能提高高达 25%

此函数执行对称秩- \(k\) 更新

\(C = \alpha\text{op}(A)\text{op}(A)^{T} + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以较低或较高模式存储的对称矩阵，而 \(A\) 是维度为 \(\text{op}(A)\) \(n \times k\) 的矩阵。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ \end{matrix} \right.\)

注意

此例程仅在架构能力等于或大于 5.0 的 GPU 上受支持

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 C 的下半部分或上半部分是否存储，另一个对称部分不被引用，而是从存储的元素推断出来。
trans		输入	运算 op(A)，为非转置或转置。
n		输入	矩阵 op(A) 和 C 的行数。
k		输入	矩阵 op(A) 的列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	<type> 维度为 lda x k 的数组，如果 trans == CUBLAS_OP_N，则 lda >= max(1, n)；否则，维度为 lda x n，且 lda >= max(1, k)。
Atype		输入	指定矩阵 A 数据类型的枚举。
lda		输入	用于存储矩阵 A 的二维数组的前导维度。
beta	主机或设备	输入	用于乘法的 <type> 标量值。 如果 beta == 0，则 C 不必是有效的输入。
C	设备	输入/输出	<type> 维度为 ldc x n 的数组，且 ldc >= max(1, n)。
Ctype		输入	指定矩阵 C 数据类型的枚举。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。

下面列出了 cublasCsyrk3mEx() 支持的矩阵类型组合

A	C
CUDA_C_8I	CUDA_C_32F
CUDA_C_32F	CUDA_C_32F

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成。
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化。
CUBLAS_STATUS_INVALID_VALUE	<type> 维度为 lda x n 的数组，其中 lda >= k + 1。 如果 n < 0 或 k < 0，或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 lda < max(1, n)（如果 trans == CUBLAS_OP_N）和 lda < max(1, k)（否则），或者 如果 ldc < max(1, n)，或者 如果不支持 Atype 或 Ctype
CUBLAS_STATUS_NOT_SUPPORTED	不支持参数 Atype 和 Ctype 的组合。
CUBLAS_STATUS_ARCH_MISMATCH	设备具有低于 5.0 的计算能力。
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动。

有关参考，请参阅 NETLIB 文档

ssyrk(), dsyrk(), csyrk(), zsyrk()

2.8.18. cublasCherkEx()

cublasStatus_t cublasCherkEx(cublasHandle_t handle,
                           cublasFillMode_t uplo,
                           cublasOperation_t trans,
                           int n,
                           int k,
                           const float     *alpha,
                           const void      *A,
                           cudaDataType    Atype,
                           int lda,
                           const float    *beta,
                           cuComplex      *C,
                           cudaDataType   Ctype,
                           int ldc)

此函数支持 64 位整数接口。

此函数是 cublasCherk() 的扩展，其中输入矩阵和输出矩阵可以具有较低的精度，但计算仍以 cuComplex 类型完成

此函数执行 Hermitian 秩- \(k\) 更新

\(C = \alpha\text{op}(A)\text{op}(A)^{H} + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以较低或较高模式存储的 Hermitian 矩阵，而 \(A\) 是维度为 \(\text{op}(A)\) \(n \times k\) 的矩阵。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{H} & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

注意

此例程仅在架构能力等于或大于 5.0 的 GPU 上受支持

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 C 的下半部分或上半部分是否存储，另一个 Hermitian 部分不被引用。
trans		输入	运算 op(A)，它是非转置或（共轭）转置。
n		输入	矩阵 op(A) 和 C 的行数。
k		输入	矩阵 op(A) 的列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	<type> 维度为 lda x k 的数组，如果 transa == CUBLAS_OP_N，则 lda >= max(1, n)；否则，维度为 lda x n，且 lda >= max(1, k)。
Atype		输入	指定矩阵 A 数据类型的枚举。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
beta		输入	用于乘法的 <type> 标量值。 如果 beta == 0，则 C 不必是有效的输入。
C	设备	输入/输出	<type> 维度为 ldc x n 的数组，且 ldc >= max(1, n)。 假定对角元素的虚部为零并设置为零。
Ctype		输入	指定矩阵 C 数据类型的枚举。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。

下表列出了 cublasCherkEx() 支持的矩阵类型组合

A	C
CUDA_C_8I	CUDA_C_32F
CUDA_C_32F	CUDA_C_32F

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成。
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化。
CUBLAS_STATUS_INVALID_VALUE	<type> 维度为 lda x n 的数组，其中 lda >= k + 1。 如果 n < 0 或 k < 0，或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 lda < max(1, n)（如果 trans == CUBLAS_OP_N）和 lda < max(1, k)（否则），或者 如果 ldc < max(1, n)，或者 如果不支持 Atype 或 Ctype
CUBLAS_STATUS_NOT_SUPPORTED	不支持参数 Atype 和 Ctype 的组合。
CUBLAS_STATUS_ARCH_MISMATCH	设备具有低于 5.0 的计算能力。
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动。

有关参考，请参阅 NETLIB 文档

cherk()

2.8.19. cublasCherk3mEx()

cublasStatus_t cublasCherk3mEx(cublasHandle_t handle,
                           cublasFillMode_t uplo,
                           cublasOperation_t trans,
                           int n,
                           int k,
                           const float     *alpha,
                           const void      *A,
                           cudaDataType    Atype,
                           int lda,
                           const float    *beta,
                           cuComplex      *C,
                           cudaDataType   Ctype,
                           int ldc)

此函数支持 64 位整数接口。

此函数是 cublasCherk() 的扩展，其中输入矩阵和输出矩阵可以具有较低的精度，但计算仍以 cuComplex 类型完成。此例程使用高斯复杂度降低算法实现，该算法可以使性能提高高达 25%

此函数执行 Hermitian 秩- \(k\) 更新

\(C = \alpha\text{op}(A)\text{op}(A)^{H} + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以较低或较高模式存储的 Hermitian 矩阵，而 \(A\) 是维度为 \(\text{op}(A)\) \(n \times k\) 的矩阵。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{H} & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

注意

此例程仅在架构能力等于或大于 5.0 的 GPU 上受支持

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
uplo		输入	指示矩阵 C 的下半部分或上半部分是否存储，另一个 Hermitian 部分不被引用。
trans		输入	运算 op(A)，它是非转置或（共轭）转置。
n		输入	矩阵 op(A) 和 C 的行数。
k		输入	矩阵 op(A) 的列数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
A	设备	输入	<type> 维度为 lda x k 的数组，如果 trans == CUBLAS_OP_N，则 lda >= max(1, n)；否则，维度为 lda x n，且 lda >= max(1, k)。
Atype		输入	指定矩阵 A 数据类型的枚举。
lda		输入	用于存储矩阵 A 的二维数组的引导维度。
beta		输入	用于乘法的 <type> 标量值。 如果 beta == 0，则 C 不必是有效的输入。
C	设备	输入/输出	<type> 维度为 ldc x n 的数组，且 ldc >= max(1, n)。 假定对角元素的虚部为零并设置为零。
Ctype		输入	指定矩阵 C 数据类型的枚举。
ldc		输入	用于存储矩阵 C 的二维数组的 Leading Dimension（主导维度）。

下表列出了 cublasCherk3mEx() 支持的矩阵类型组合

A	C
CUDA_C_8I	CUDA_C_32F
CUDA_C_32F	CUDA_C_32F

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成。
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化。
CUBLAS_STATUS_INVALID_VALUE	<type> 维度为 lda x n 的数组，其中 lda >= k + 1。 如果 n < 0 或 k < 0，或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 之一，或者 如果 lda < max(1, n)（如果 trans == CUBLAS_OP_N）和 lda < max(1, k)（否则），或者 如果 ldc < max(1, n)，或者 如果不支持 Atype 或 Ctype
CUBLAS_STATUS_NOT_SUPPORTED	不支持参数 Atype 和 Ctype 的组合。
CUBLAS_STATUS_ARCH_MISMATCH	设备具有低于 5.0 的计算能力。
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动。

有关参考，请参阅 NETLIB 文档

cherk()

2.8.20. cublasNrm2Ex()

cublasStatus_t  cublasNrm2Ex( cublasHandle_t handle,
                              int n,
                              const void *x,
                              cudaDataType xType,
                              int incx,
                              void *result,
                              cudaDataType resultType,
                              cudaDataType executionType)

此函数支持 64 位整数接口。

此函数是例程 cublas<t>nrm2() 的 API 泛化，其中可以独立指定输入数据、输出数据和计算类型。

此函数计算向量 x 的欧几里得范数。 代码使用多阶段累积模型来避免中间下溢和溢出，结果等效于精确算术中的 \(\sqrt{\sum_{i = 1}^{n}\left( {\mathbf{x}\lbrack j\rbrack \times \mathbf{x}\lbrack j\rbrack} \right)}\)，其中 \(j = 1 + \left( {i - 1} \right)*\text{incx}\)。 请注意，最后一个方程式反映了基于 1 的索引，用于与 Fortran 兼容。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
n		输入	向量 x 中的元素数。
x	设备	输入	<type> 带有 n 个元素的向量。
xType		输入	指定向量 x 数据类型的枚举。
incx		输入	x 的连续元素之间的步幅。
result	主机或设备	输出	结果范数，如果 n <= 0 或 incx <= 0，则设置为 0。
resultType		输入	指定 result 数据类型的枚举。
executionType		输入	指定执行计算的数据类型的枚举。

下面列出了当前 cublasNrm2Ex() 支持的数据类型组合

x	result	execution
CUDA_R_16F	CUDA_R_16F	CUDA_R_32F
CUDA_R_16BF	CUDA_R_16BF	CUDA_R_32F
CUDA_R_32F	CUDA_R_32F	CUDA_R_32F
CUDA_C_32F	CUDA_R_32F	CUDA_R_32F
CUDA_R_64F	CUDA_R_64F	CUDA_R_64F
CUDA_C_64F	CUDA_R_64F	CUDA_R_64F

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_ALLOC_FAILED	无法分配缩减缓冲区
CUBLAS_STATUS_NOT_SUPPORTED	不支持参数 xType、resultType 和 executionType 的组合
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动
CUBLAS_STATUS_INVALID_VALUE	如果不支持 xType 或 resultType 或 executionType，或者 如果 result 为 NULL

有关参考，请参阅 NETLIB 文档

snrm2()、dnrm2()、scnrm2()、dznrm2()

2.8.21. cublasAxpyEx()

cublasStatus_t cublasAxpyEx (cublasHandle_t handle,
                             int n,
                             const void *alpha,
                             cudaDataType alphaType,
                             const void *x,
                             cudaDataType xType,
                             int incx,
                             void *y,
                             cudaDataType yType,
                             int incy,
                             cudaDataType executiontype);

此函数支持 64 位整数接口。

此函数是例程 cublas<t>axpy() 的 API 泛化，其中可以独立指定输入数据、输出数据和计算类型。

此函数将向量 x 乘以标量 \(\alpha\)，并将其添加到向量 y，并用结果覆盖最新的向量。 因此，执行的操作是 \(\mathbf{y}\lbrack j\rbrack = \alpha \times \mathbf{x}\lbrack k\rbrack + \mathbf{y}\lbrack j\rbrack\)，对于 \(i = 1,\ldots,n\) 、 \(k = 1 + \left( {i - 1} \right)*\text{incx}\) 和 \(j = 1 + \left( {i - 1} \right)*\text{incy}\)。 请注意，最后两个方程式反映了基于 1 的索引，用于与 Fortran 兼容。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
n		输入	向量 x 和 y 中的元素数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
alphaType		输入	指定标量 alpha 数据类型的枚举。
x	设备	输入	<type> 带有 n 个元素的向量。
xType		输入	指定向量 x 数据类型的枚举。
incx		输入	x 的连续元素之间的步幅。
y	设备	输入/输出	<type> 带有 n 个元素的向量。
yType		输入	指定向量 y 数据类型的枚举。
incy		输入	y 的连续元素之间的步幅。
executionType		输入	指定执行计算的数据类型的枚举。

下表列出了当前 cublasAxpyEx() 支持的数据类型组合

alpha	x	y	execution
CUDA_R_32F	CUDA_R_16F	CUDA_R_16F	CUDA_R_32F
CUDA_R_32F	CUDA_R_16BF	CUDA_R_16BF	CUDA_R_32F
CUDA_R_32F	CUDA_R_32F	CUDA_R_32F	CUDA_R_32F
CUDA_R_64F	CUDA_R_64F	CUDA_R_64F	CUDA_R_64F
CUDA_C_32F	CUDA_C_32F	CUDA_C_32F	CUDA_C_32F
CUDA_C_64F	CUDA_C_64F	CUDA_C_64F	CUDA_C_64F

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成。
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化。
CUBLAS_STATUS_NOT_SUPPORTED	不支持参数 xType、yType 和 executionType 的组合。
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动。
CUBLAS_STATUS_INVALID_VALUE	不支持 alphaType 或 xType 或 yType 或 executionType。

有关参考，请参阅 NETLIB 文档

saxpy()、daxpy()、caxpy()、zaxpy()

2.8.22. cublasDotEx()

cublasStatus_t cublasDotEx (cublasHandle_t handle,
                            int n,
                            const void *x,
                            cudaDataType xType,
                            int incx,
                            const void *y,
                            cudaDataType yType,
                            int incy,
                            void *result,
                            cudaDataType resultType,
                            cudaDataType executionType);

cublasStatus_t cublasDotcEx (cublasHandle_t handle,
                             int n,
                             const void *x,
                             cudaDataType xType,
                             int incx,
                             const void *y,
                             cudaDataType yType,
                             int incy,
                             void *result,
                             cudaDataType resultType,
                             cudaDataType executionType);

这些函数支持 64 位整数接口。

这些函数是例程 cublas<t>dot() 和 cublas<t>dotc() 的 API 泛化，其中可以独立指定输入数据、输出数据和计算类型。注意：cublas<t>dotc() 是共轭点积，cublas<t>dotu() 是非共轭点积。

此函数计算向量 x 和 y 的点积。 因此，结果是 \(\sum_{i = 1}^{n}\left( {\mathbf{x}\lbrack k\rbrack \times \mathbf{y}\lbrack j\rbrack} \right)\)，其中 \(k = 1 + \left( {i - 1} \right)*\text{incx}\) 和 \(j = 1 + \left( {i - 1} \right)*\text{incy}\)。 请注意，在第一个方程式中，如果函数名称以字符“c”结尾，则应使用向量 x 元素的共轭，并且最后两个方程式反映了基于 1 的索引，用于与 Fortran 兼容。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
n		输入	向量 x 和 y 中的元素数。
x	设备	输入	<type> 带有 n 个元素的向量。
xType		输入	指定向量 x 数据类型的枚举。
incx		输入	x 的连续元素之间的步幅。
y	设备	输入	<type> 带有 n 个元素的向量。
yType		输入	指定向量 y 数据类型的枚举。
incy		输入	y 的连续元素之间的步幅。
result	主机或设备	输出	结果点积，如果 n <= 0，则设置为 0
resultType		输入	指定 result 数据类型的枚举。
executionType		输入	指定执行计算的数据类型的枚举。

下面列出了当前 cublasDotEx() 和 cublasDotcEx() 支持的数据类型组合

x	y	result	execution
CUDA_R_16F	CUDA_R_16F	CUDA_R_16F	CUDA_R_32F
CUDA_R_16BF	CUDA_R_16BF	CUDA_R_16BF	CUDA_R_32F
CUDA_R_32F	CUDA_R_32F	CUDA_R_32F	CUDA_R_32F
CUDA_R_64F	CUDA_R_64F	CUDA_R_64F	CUDA_R_64F
CUDA_C_32F	CUDA_C_32F	CUDA_C_32F	CUDA_C_32F
CUDA_C_64F	CUDA_C_64F	CUDA_C_64F	CUDA_C_64F

下表列出了此函数可能返回的错误值及其含义

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成。
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化。
CUBLAS_STATUS_ALLOC_FAILED	无法分配缩减缓冲区。
CUBLAS_STATUS_NOT_SUPPORTED	不支持参数 xType、yType、resultType 和 executionType 的组合。
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动。
CUBLAS_STATUS_INVALID_VALUE	不支持 xType 或 yType 或 resultType 或 executionType。

有关参考，请参阅 NETLIB 文档

sdot()、ddot()、cdotu()、cdotc()、zdotu()、zdotc()

2.8.23. cublasRotEx()

cublasStatus_t cublasRotEx(cublasHandle_t handle,
                           int n,
                           void *x,
                           cudaDataType xType,
                           int incx,
                           void *y,
                           cudaDataType yType,
                           int incy,
                           const void *c,  /* host or device pointer */
                           const void *s,
                           cudaDataType csType,
                           cudaDataType executiontype);

此函数支持 64 位整数接口。

此函数是例程 cublas<t>rot() 的扩展，其中可以独立指定输入数据、输出数据、余弦/正弦类型和计算类型。

此函数应用 Givens 旋转矩阵（即，在 x,y 平面中逆时针旋转，角度由 cos(alpha)=c, sin(alpha)=s 定义）

\(G = \begin{pmatrix} c & s \\ {- s} & c \\ \end{pmatrix}\)

到向量 x 和 y。

因此，结果是 \(\mathbf{x}\lbrack k\rbrack = c \times \mathbf{x}\lbrack k\rbrack + s \times \mathbf{y}\lbrack j\rbrack\) 和 \(\mathbf{y}\lbrack j\rbrack = - s \times \mathbf{x}\lbrack k\rbrack + c \times \mathbf{y}\lbrack j\rbrack\)，其中 \(k = 1 + \left( {i - 1} \right)*\text{incx}\) 和 \(j = 1 + \left( {i - 1} \right)*\text{incy}\)。 请注意，最后两个方程式反映了基于 1 的索引，用于与 Fortran 兼容。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
n		输入	向量 x 和 y 中的元素数。
x	设备	输入/输出	<type> 带有 n 个元素的向量。
xType		输入	指定向量 x 数据类型的枚举。
incx		输入	x 的连续元素之间的步幅。
y	设备	输入/输出	<type> 带有 n 个元素的向量。
yType		输入	指定向量 y 数据类型的枚举。
incy		输入	y 的连续元素之间的步幅。
c	主机或设备	输入	旋转矩阵的余弦元素。
s	主机或设备	输入	旋转矩阵的正弦元素。
csType		输入	指定 c 和 s 数据类型的枚举。
executionType		输入	指定执行计算的数据类型的枚举。

下面列出了当前 cublasRotEx() 支持的数据类型组合

executionType	xType / yType	csType
CUDA_R_32F	CUDA_R_16BF CUDA_R_16F CUDA_R_32F	CUDA_R_16BF CUDA_R_16F CUDA_R_32F
CUDA_R_64F	CUDA_R_64F	CUDA_R_64F
CUDA_C_32F	CUDA_C_32F CUDA_C_32F	CUDA_R_32F CUDA_C_32F
CUDA_C_64F	CUDA_C_64F CUDA_C_64F	CUDA_R_64F CUDA_C_64F

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

srot()、drot()、crot()、csrot()、zrot()、zdrot()

2.8.24. cublasScalEx()

cublasStatus_t  cublasScalEx(cublasHandle_t handle,
                             int n,
                             const void *alpha,
                             cudaDataType alphaType,
                             void *x,
                             cudaDataType xType,
                             int incx,
                             cudaDataType executionType);

此函数支持 64 位整数接口。

此函数按标量 \(\alpha\) 缩放向量 x ，并使用结果覆盖它。因此，执行的操作是 \(\mathbf{x}\lbrack j\rbrack = \alpha \times \mathbf{x}\lbrack j\rbrack\) ，对于 \(i = 1,\ldots,n\) 和 \(j = 1 + \left( {i - 1} \right)*\text{incx}\) 。请注意，最后两个方程反映了基于 1 的索引，用于与 Fortran 的兼容性。

参数。	内存	输入/输出	含义
handle		输入	cuBLAS 库上下文的句柄。
n		输入	向量 x 中的元素数。
alpha	主机或设备	输入	用于乘法的 <type> 标量。
alphaType		输入	指定标量 alpha 数据类型的枚举。
x	设备	输入/输出	<type> 带有 n 个元素的向量。
xType		输入	指定向量 x 数据类型的枚举。
incx		输入	x 的连续元素之间的步幅。
executionType		输入	指定执行计算的数据类型的枚举。

下面列出了当前 cublasScalEx() 支持的数据类型组合

alpha	x	execution
CUDA_R_32F	CUDA_R_16F	CUDA_R_32F
CUDA_R_32F	CUDA_R_16BF	CUDA_R_32F
CUDA_R_32F	CUDA_R_32F	CUDA_R_32F
CUDA_R_64F	CUDA_R_64F	CUDA_R_64F
CUDA_C_32F	CUDA_C_32F	CUDA_C_32F
CUDA_C_64F	CUDA_C_64F	CUDA_C_64F

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_NOT_SUPPORTED	参数 xType 和 executionType 的组合不受支持
CUBLAS_STATUS_EXECUTION_FAILED	该函数无法在 GPU 上启动
CUBLAS_STATUS_INVALID_VALUE	alphaType 或 xType 或 executionType 不受支持

有关参考，请参阅 NETLIB 文档

sscal(), dscal(), csscal(), cscal(), zdscal(), zscal()

3. 使用 cuBLASLt API

3.1. 概述

cuBLASLt 库是一个新的轻量级库，专用于通用矩阵乘法 (GEMM) 操作，并具有新的灵活 API。这个新库增加了矩阵数据布局、输入类型、计算类型的灵活性，还可以通过参数可编程性来选择算法实现和启发式方法。

一旦用户确定了预期 GEMM 操作的一组选项，这些选项就可以重复用于不同的输入。这类似于 cuFFT 和 FFTW 如何首先创建一个计划，并将其重复用于具有不同输入数据的相同大小和类型的 FFT。

注意

cuBLASLt 库不保证支持所有可能的尺寸和配置，但是，自 CUDA 12.2 update 2 以来，对 m、n 和批大小的问题尺寸限制已在很大程度上得到解决。该库的主要重点是提供性能最佳的内核，这可能有一些隐含的限制。一些非标准配置可能需要用户手动处理，通常是将问题分解为更小的部分（请参阅问题尺寸限制）。

3.1.1. 问题尺寸限制

存在固有的问题尺寸限制，这是 CUDA 网格维度限制的结果。例如，由于网格 z 维度的限制，许多内核不支持大于 65535 的批大小。对于给定的问题，m 和 n 值也存在类似的限制。

在单个内核无法运行问题的情况下，cuBLASLt 将尝试将问题分解为多个子问题，并通过在每个子问题上运行内核来解决它。

以下总结了 cuBLASLt 内部问题分解的一些限制

• 不支持 Amax 计算。这意味着 CUBLASLT_MATMUL_DESC_AMAX_D_POINTER 和 CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_AMAX_POINTER 必须保持未设置状态（请参阅cublasLtMatmulDescAttributes_t）

• 所有矩阵布局的 CUBLASLT_MATRIX_LAYOUT_ORDER 必须设置为 CUBLASLT_ORDER_COL（请参阅cublasLtOrder_t）

• 当 CUBLASLT_MATMUL_DESC_EPILOGUE 设置为 CUBLASLT_EPILOGUE_DRELU_BGRAD 或 CUBLASLT_EPILOGUE_DGELU_BGRAD 时，cuBLASLt 不会沿 n 维度进行分区（请参阅cublasLtEpilogue_t）

为了克服这些限制，用户可能希望自行对问题进行分区，为每个子问题启动内核，并计算任何必要的归约以组合结果。

3.1.2. 启发式缓存

cuBLASLt 使用启发式方法，根据问题大小、GPU 配置和其他参数选择最合适的 matmul 内核来执行。这需要在主机 CPU 上执行一些计算，这可能需要数十微秒。为了克服这种开销，建议使用 cublasLtMatmulAlgoGetHeuristic() 查询一次启发式方法，然后使用 cublasLtMatmul() 将结果重用于后续计算。

对于无法一次查询启发式方法然后重用的情况，cuBLASLt 实现了启发式缓存，该缓存将 matmul 问题映射到先前由启发式方法选择的内核。启发式缓存使用类似 LRU 的驱逐策略，并且是线程安全的。

用户可以使用 CUBLASLT_HEURISTICS_CACHE_CAPACITY 环境变量或具有更高优先级的 cublasLtHeuristicsCacheSetCapacity() 函数来控制启发式缓存容量。容量以条目数衡量，并且可能出于性能原因而向上舍入到某个因子的最接近倍数。每个条目大约占用 360 字节，但可能会发生变化。默认容量为 8192 个条目。

注意

将容量设置为零将完全禁用缓存。这对于没有稳定状态且缓存操作可能比常规启发式计算开销更高的工作负载非常有用。

注意

出于性能原因，缓存并非理想选择，因此有时需要将其容量增加到预期唯一 matmul 问题数量的 1.5 倍至 2 倍，以实现接近完美的命中率。

另请参阅：cublasLtHeuristicsCacheGetCapacity()、cublasLtHeuristicsCacheSetCapacity()。

3.1.3. cuBLASLt 日志记录

可以通过在启动目标应用程序之前设置以下环境变量来启用 cuBLASLt 日志记录机制

• CUBLASLT_LOG_LEVEL=<level>，其中 <level> 是以下级别之一

  • 0 - 关闭 - 禁用日志记录（默认）

  • 1 - 错误 - 仅记录错误

  • 2 - 跟踪 - 调用启动 CUDA 内核的 API 将记录其参数和重要信息

  • 3 - 提示 - 可能提高应用程序性能的提示

  • 4 - 信息 - 提供有关库执行的常规信息，可能包含有关启发式状态的详细信息

  • 5 - API 跟踪 - API 调用将记录其参数和重要信息

• CUBLASLT_LOG_MASK=<mask>，其中 <mask> 是以下标志的组合

  • 0 - 关闭

  • 1 - 错误

  • 2 - 跟踪

  • 4 - 提示

  • 8 - 信息

  • 16 - API 跟踪

  例如，使用 CUBLASLT_LOG_MASK=5 启用错误和提示消息。

• CUBLASLT_LOG_FILE=<file_name>，其中 <file_name> 是日志文件的路径。文件名可以包含 %i，它将被进程 ID 替换。例如 file_name_%i.log。

如果未设置 CUBLASLT_LOG_FILE，则日志消息将打印到标准输出。

另一种选择是使用实验性的 cuBLASLt 日志记录 API。请参阅

cublasLtLoggerSetCallback()、cublasLtLoggerSetFile()、cublasLtLoggerOpenFile()、cublasLtLoggerSetLevel()、cublasLtLoggerSetMask()、cublasLtLoggerForceDisable()

3.1.4. 8 位浮点数据类型 (FP8) 的使用

请参阅窄精度数据类型的使用部分。

3.1.5. 窄精度数据类型的使用

我们在此处称之为窄精度数据类型最初是作为 8 位浮点数据类型 (FP8) 引入的，适用于 Ada 和 Hopper GPU（计算能力 8.9 及更高版本），旨在进一步加速矩阵乘法。有两种类型的 FP8 可用

• CUDA_R_8F_E4M3 旨在比半精度在更小的动态范围内保持准确。E4 和 M3 分别表示 4 位指数和 3 位尾数。有关更多详细信息，请参阅__nv__fp8__e4m3。

• CUDA_R_8F_E5M2 旨在与半精度在相似的动态范围内保持准确。E5 和 M2 分别表示 5 位指数和 2 位尾数。有关更多信息，请参阅__nv__fp8__e5m2。

注意

除非另有说明，否则 FP8 指的是 CUDA_R_8F_E4M3 和 CUDA_R_8F_E5M2。

对于 Blackwell GPU（计算能力 10.0 及更高版本），cuBLAS 增加了对 4 位浮点数据类型 (FP4) CUDA_R_4F_E2M1 的支持。E2 和 M1 分别表示 2 位指数和 1 位尾数。有关更多详细信息，请参阅__nv_fp4_e2m1。

为了保持精度，窄精度数据需要在计算之前进行缩放或反量化，并在计算之后可能需要进行量化。cuBLAS 提供了几种应用缩放因子的模式，这些模式在 cublasLtMatmulMatrixScale_t 中定义，并通过 CUBLASLT_MATMUL_DESC_X_SCALE_MODE 属性配置（此处 X 代表 A、B、C、D、D_OUT 或 AUX；请参阅 cublasLtMatmulDescAttributes_t）。缩放模式概述在下表中给出，更多详细信息可在后续部分中找到。

模式	最低计算能力	张量值数据类型	缩放因子数据类型	缩放因子布局
张量范围缩放	8.9	CUDA_R_8F_E4M3 / CUDA_R_8F_E5M2	CUDA_R_32F	标量
32 元素 1D 块缩放	10.0	CUDA_R_8F_E4M3 / CUDA_R_8F_E5M2	CUDA_R_8F_UE8M0 1	平铺张量 3
16 元素 1D 块缩放	10.0	CUDA_R_4F_E2M1	CUDA_R_8F_UE4M3 2	平铺张量 3

注释

1

CUDA_R_8F_UE8M0 是一种 8 位无符号仅指数浮点数据类型。有关更多信息，请参阅__nv_fp8_e8m0。

2

CUDA_R_8F_UE4M3 是 CUDA_R_E4M3 的无符号版本。符号位被忽略，因此提供此枚举器是为了方便。

3(1,2)

有关更多详细信息，请参阅1D 块缩放因子布局。

注意

缩放仅适用于窄精度 matmul。如果为非窄精度 matmul 设置任何缩放，cuBLAS 将返回错误。此外，缩放通常仅支持窄精度张量。如果为非窄精度张量设置了相应的缩放，则将被忽略。一个例外是，在 Ada 和 Hopper GPU 上，张量 C 允许具有非窄数据类型的缩放。

3.1.5.1. FP8 数据类型的张量范围缩放

当所有 FP8 精度张量的 CUBLASLT_MATMUL_DESC_X_SCALE_MODE 属性（此处 X 代表 A、B、C、D 或 AUX；请参阅 cublasLtMatmulDescAttributes_t）设置为 CUBLASLT_MATMUL_MATRIX_SCALE_SCALAR_32F 时（这是 FP8 张量的默认值），将启用张量范围缩放。在这种情况下，cuBLAS 中的 matmul 操作定义如下（为便于说明，假设所有张量都使用 FP8 精度）

\[D = scale_D \cdot (\alpha \cdot scale_A \cdot scale_B \cdot \text{op}(A) \text{op}(B) + \beta \cdot scale_C \cdot C).\]

这里 \(A\)、\(B\) 和 \(C\) 是输入张量，\(scale_A\)、\(scale_B\)、\(scale_C\)、\(scale_D\)、\(\alpha\) 和 \(\beta\) 是输入标量。这与其他矩阵乘法例程不同，因为每个矩阵都添加了缩放因子。\(scale_A\)、\(scale_B\) 和 \(scale_C\) 用于反量化，\(scale_D\) 用于量化。请注意，所有缩放因子都以乘法方式应用。这意味着有时需要使用缩放因子或其倒数，具体取决于应用它的上下文。有关 FP8 的更多信息，请参阅 cublasLtMatmul() 和 cublasLtMatmulDescAttributes_t。

对于此类矩阵乘法，后记和中间值的绝对最大值计算如下

\[\begin{split}Aux_{temp} & = \alpha \cdot scale_A \cdot scale_B \cdot \text{op}(A) \text{op}(B) + \beta \cdot scale_C \cdot C, \\ D_{temp} & = \mathop{Epilogue}(Aux_{temp}), \\ amax_{D} & = \mathop{absmax}(D_{temp}), \\ amax_{Aux} & = \mathop{absmax}(Aux_{temp}), \\ D & = scale_D * D_{temp}, \\ Aux & = scale_{Aux} * Aux_{temp}. \\\end{split}\]

此处 \(Aux\) 是 matmul 的辅助输出，由传递给后记函数（如 GELU）的值组成，\(scale_{Aux}\) 是一个可选的缩放因子，可以应用于 \(Aux\)，\(amax_{Aux}\) 是缩放前 \(Aux\) 中的最大绝对值。有关更多信息，请参阅 cublasLtMatmulDescAttributes_t 中的属性 CUBLASLT_MATMUL_DESC_AMAX_D_POINTER 和 CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_AMAX_POINTER。

3.1.5.2. FP8 和 FP4 数据类型的 1D 块缩放

1D 块缩放旨在克服使用单个标量来缩放整个张量的限制。在 OCP MXFP 规范中对此进行了更详细的描述，因此我们在此处仅给出简要概述。块缩放意味着相邻值的同一 16 元素或 32 元素块内的元素被分配一个共享的缩放因子。

目前，块缩放支持 FP8 精度和 FP4 精度张量，并且不支持混合精度。要启用块缩放，必须将所有 FP8 精度张量的 CUBLASLT_MATMUL_DESC_X_SCALE_MODE 属性（此处 X 代表 A、B、C、D 或 AUX；请参阅 cublasLtMatmulDescAttributes_t）设置为 CUBLASLT_MATMUL_MATRIX_SCALE_VEC32_UE8M0，或者将所有 FP4 精度张量设置为 CUBLASLT_MATMUL_MATRIX_SCALE_VEC16_UE4M3。

使用块缩放时，cuBLAS 中的 matmul 操作定义如下（为便于说明，假设所有张量都使用窄精度）。我们粗略地遵循 OCP MXFP 规范符号。

首先，缩放块（或 OCP MXFP 规范中的符合 MX 格式的向量）是一个元组 \(x = \left(S^x, \left[x^i\right]_{i=1}^k\right)\)，其中 \(S^x\) 是共享缩放因子，每个 \(x^i\) 都使用 FP8 或 FP4 数据类型存储。

两个缩放块 \(x = \left(S^x, \left[x^i\right]_{i=1}^{k}\right)\) 和 \(y = \left(S^y, \left[y^i\right]_{i=1}^{k}\right)\) 的点积定义如下

\[Dot(x, y) = S^x S^y \cdot \sum_{i=1}^{k} x^i y^i.\]

对于 \(n\) 个块的序列 \(X = \{x_j\}_{j=1}^n\) 和 \(Y = \{y_j\}_{j=1}^n\)，广义点积定义为

\[DotGeneral(X, Y) = \sum_{j=1}^n Dot(x_j, y_j).\]

广义点积可用于通过组合 \(A\) 和 \(B\) 的每 \(k\) 个元素在 \(K\) 维度上的一个缩放因子来定义矩阵乘法（为简单起见，假设 \(K\) 可被 \(k\) 整除而没有余数）

\[\begin{split}L & = \frac{K}{k}, \\ A_i & = \left\{{Scale_A}_{i,b}, \left[A_{i,(b-1)k+l}\right]_{l=1}^{k}\right\}_{b=1}^L, \\ B_j & = \left\{{Scale_B}_{i,b}, \left[B_{(b-1)k+l,j}\right]_{l=1}^{k}\right\}_{b=1}^L, \\ (\left\{scale_A, A\right\} \times \left\{scale_B, B\right\})_{i,j} & = DotGeneral(A_i, B_j).\end{split}\]

现在，完整的 matmul 可以写成

\[\left\{scale_D^{out}, D\right\} = Quantize\left(scale_D^{in}\left(\alpha \cdot \left\{scale_A, \text{op}(A)\right\} \times \left\{scale_B, \text{op}(B)\right\} + \beta \cdot Dequantize(\left\{scale_C, C\right\})\right)\right).\]

\(Quantize\) 在1D 块量化部分中解释，\(Dequantize\) 定义为

\[Dequantize\left(\left\{scale_C, C\right\})\right)_{i,j} = {scale_C}_{i/k,j} \cdot C_{i,j}.\]

注意

除了在量化期间计算的 \(scale_D^{out}\) 之外，还有一个 输入 标量张量范围缩放因子 \(scale_D^{in}\)，仅当缩放因子使用 CUDA_R_8F_UE4M3 数据类型时才可用。它用于在量化之前“压缩”计算值。

3.1.5.2.1. 1D 块量化

考虑 \(M\) 维度中 \(D\) 的 \(k\) 个元素的单个块：\(D^b_{fp32} = \left[d^i_{fp32}\right]_{i=1}^k\)。部分块的量化执行方式与缺失值为零时相同。设 \(Amax(DType)\) 为目标精度中可表示的最大值。

以下计算步骤对于输出和缩放因子数据类型的所有组合都是通用的。

1. 计算块绝对最大值 \(Amax(D^b_{fp32}) = max(\{|d_i|\}_{i=1}^k)\)。

2. 以单精度计算块缩放因子为 \(S^b_{fp32} = \frac{Amax(D^b_{fp32})}{Amax(DType)}\)。

计算具有 UE8M0 缩放的 FP8 的缩放和转换因子

注意

除非另有说明，否则假定为 RNE 舍入。

计算包括以下步骤

1. 从 \(S^b_{fp32}\) 中提取块缩放因子指数（不进行偏差调整）作为整数 \(E^b_{int}\)，并将尾数作为定点数 \(M^b_{fixp}\)（实际实现直接在位表示上操作）。

2. 向上舍入块指数，使其保持在 UE8M0 中可表示的值范围内：\(E^b_{int} = \left\{\begin{array}{ll} E^b_{int} + 1, & \text{if } S^b_{fp32} \text{ 是一个普通数且 } E^b_{int} < 254 \text{ 且 } M^b_{fixp} > 0 \\ E^b_{int} + 1, & \text{if } S^b_{fp32} \text{是一个次正规数且 } M^b_{fixp} > 0.5, \\ E^b_{int}, & \text{否则。} \end{array}\right.\)

3. 计算块缩放因子为 \(S^b_{ue8m0} = 2^{E^b_{int}}\)。请注意，UE8M0 数据类型的指数偏差为 127。

4. 计算块转换因子 \(R^b_{fp32} = \frac{1}{fp32(S^b_{ue8m0})}\)。

注意

上述算法与 OCP MXFP 建议的舍入方案不同。

计算具有 UE4M3 缩放的 FP4 的缩放和转换因子

这里我们假设算法提供了一个预先计算的输入张量范围缩放因子 \(scale_D^{in}\)，在一般情况下，该因子计算为

\[scale_D^{in} = \frac{Amax(e2m1) \cdot Amax(e4m3)}{Amax(D_{temp})},\]

其中 \(Amax(D_{temp})\) 是量化之前 matmul 结果的全局绝对最大值。由于计算此值需要知道整个计算的结果，因此在实践中使用来自例如先前迭代的近似值。

计算包括以下步骤

1. 计算块缩放因子的窄精度值 \(S^b_{e4m3} = e4m3(S^b_{fp32} \cdot scale_D^{in})\)。

2. 计算块转换因子 \(R^b_{fp32} = \frac{scale_D^{in}}{fp32(S^b_{e4m3})}\)。

应用转换因子

对于每个 \(i = 1 \ldots k\)，计算 \(d^i = DType(d^i_{fp32} \cdot R^n_{fp32})\)。生成的量化块是 \(\left(S^b, \left[d^i\right]_{i=1}^k\right)\)，其中 \(S^b\) 对于具有 UE8M0 缩放因子的 FP8 为 \(S^b_{ue8m0}\)，对于具有 UE4M3 缩放因子的 FP4 为 \(S^b_{ue4m3}\)。

3.1.5.2.2. 1D 块缩放因子布局

缩放因子使用平铺布局存储。下图显示了每个平铺在内存中的布局方式。内存中的偏移量从左到右，然后从上到下递增。

以下伪代码可用于将 row 和 column 索引转换为平铺内的线性 offset 并返回

// Indices -> offset
offset = (row % 32) * 16 + (row / 32) * 4 + column

// Offset -> Indices
row = (offset / 4) * 32 + (offset / 16)
column = (offset % 4)

当缩放模式为 CUBLASLT_MATMUL_MATRIX_SCALE_VEC16_UE4M3 时，单个缩放因子平铺应用于 128x64 块；当缩放模式为 CUBLASLT_MATMUL_MATRIX_SCALE_VEC32_UE8M0 时，应用于 128x128 块。

多个块按以下方式排列。内存中的偏移量从左到右，然后从上到下递增。

注意

请注意，上述布局不允许转置。这意味着即使输入张量可以转置，缩放因子的布局也不会改变。

注意

请注意，当张量维度不是上述平铺大小的倍数时，仍然需要为存储分配完整的平铺，并用零填充超出范围的值。此外，在写入输出缩放因子时，内核可能会写入额外的零，因此最好不要对超出范围的值的持久性做任何假设。

3.1.6. 禁用 CPU 指令

如启发式缓存部分所述，cuBLASLt 启发式方法在主机 CPU 上执行一些计算密集型操作。为了加速操作，实现会检测 CPU 功能，并可能使用特殊指令，例如 x86-64 CPU 上的高级矢量扩展 (AVX)。但是，在某些极少数情况下，这可能是不希望的。例如，使用高级指令可能会导致 CPU 以较低的频率运行，这会影响其他主机代码的性能。

用户可以选择指示 cuBLASLt 库不要使用某些 CPU 指令，方法是使用 CUBLASLT_DISABLE_CPU_INSTRUCTIONS_MASK 环境变量或具有更高优先级的 cublasLtDisableCpuInstructionsSetMask() 函数。默认掩码为 0，这意味着没有限制。

请查看 cublasLtDisableCpuInstructionsSetMask() 以获取更多信息。

3.1.7. 原子同步

原子同步允许通过启用 cublasLtMatmul() 与另一个并发运行的内核建立生产者或消费者关系来优化 matmul 工作负载。这允许以更精细的粒度重叠计算和通信。从概念上讲，matmul 配备了一个包含 32 位整数计数器的数组，然后

• 在消费者模式下，矩阵 A 按行分区为块，或者矩阵 B 按列分区为块 4。只有当相应的原子计数器达到值 0 时，才能从内存中读取块并用于计算。生产者应执行内存栅栏，以确保写入的值对并发运行的 matmul 内核可见 5。

• 在生产者模式下，输出矩阵 C（或异地模式下的 D）按行或列分区，并且在计算完块后，相应的原子计数器设置为 0。每个计数器在 matmul 内核运行之前必须初始化为 1。

4

当前的实现允许对矩阵的行或列进行分区，但不能同时对两者进行分区。不支持批处理的情况。

5

内存栅栏的一种可能的实现是 cuda::atomic_thread_fence(cuda::memory_order_seq_cst, cuda::thread_scope::thread_scope_device)（有关更多详细信息，请参阅cuda::atomic_thread_fence()）。

计数器数组通过 CUBLASLT_MATMUL_DESC_ATOMIC_SYNC_IN_COUNTERS_POINTER 和 CUBLASLT_MATMUL_DESC_ATOMIC_SYNC_OUT_COUNTERS_POINTER 计算描述符属性分别传递给矩阵乘法，用于消费者和生产者模式 6。 对于所有分块，数组必须具有足够数量的元素。

6

当前的实现只允许启用生产者模式或消费者模式之一，但不能同时启用两者。 如果输入和输出计数器指针都指向非 NULL 值，则矩阵乘法将返回错误。

分块的数量由 CUBLASLT_MATMUL_DESC_ATOMIC_SYNC_NUM_CHUNKS_D_ROWS 和 CUBLASLT_MATMUL_DESC_ATOMIC_SYNC_NUM_CHUNKS_D_COLS 计算描述符属性控制。 必须将这两个属性都设置为大于零的值才能启用该功能。 对于列优先布局，分块的数量必须满足

\[\begin{split}0 \leq \text{$\mathrm{NUM\_CHUNKS\_ROWS}$} \leq & \mathop{\text{floor}}\left( \frac{\text{M}}{\text{$\mathrm{TILE\_SIZE\_M}$} * \text{$\mathrm{CLUSTER\_SHAPE\_M}$}} \right) \\ 0 \leq \text{$\mathrm{NUM\_CHUNKS\_COLS}$} \leq & \mathop{\text{floor}}\left( \frac{\text{N}}{\text{$\mathrm{TILE\_SIZE\_N}$} * \text{$\mathrm{CLUSTER\_SHAPE\_N}$}} \right)\end{split}\]

对于行优先布局，tile size 和 cluster shape 中的 M 和 N 必须交换。 这些限制意味着需要首先通过 cublasLtMatmulAlgoGetHeuristic() 查询启发式方法，并检查 tile 和 cluster shape 的结果，然后才能设置分块的数量。

下面的伪代码展示了操作原理

// The code below shows operation when partitioning over
// rows assuming column-major layout and TN case.
//
// The case when partitioning is done over columns or
// row-major case are handled in a similar fashion,
// with the main difference being the offsets
// computations.
//
// Note that the actual implementation does not
// guarantee in which order the chunks are computed,
// and may employ various optimizations to improve
// overall performance.
//
// Here:
//   - A, B, C -- input matrices in the column-major layout
//   - lda -- leading dimension of matrix A
//   - M, N, K -- the original problem dimensions
//   - counters_in[] and counters_out[] -- the arrays of
//     input and output atomic counters
//
for (int i = 0; i < NUM_CHUNKS_ROWS; i++) {
  // Consumer: wait for the input counter to become 0
  if (consumer) {
    while (counters_in[i] != 0); // spin
  }

  // compute chunk dimensions
  chunk_m_begin = floor((double)M / NUM_CHUNKS_ROWS * i);
  chunk_m_end = floor((double)M / NUM_CHUNKS_ROWS * (i + 1));
  chunk_m = chunk_m_end - chunk_m_begin;

  // Compute the current chunk
  matmul(chunk_m, N, K,
         A[chunk_m_begin * lda], // A is col-major transposed
         B, // B is not partitioned
         C[chunk_m_begin] // C is col-major non-transposed
         );

  // Producer: set the counter to 0 when done
  if (producer) {
    counters_out[i] = 0;
    // make the written value visible to the consumer kernel
    memory_fence();
  }
}

应该注意的是，一般来说，CUDA 编程模型提供的内核协同调度保证很少。 因此，使用此功能需要仔细编排生产者和消费者内核的启动顺序和资源可用性，因为它很容易造成死锁情况。 在以下情况下可能会发生死锁（这不是详尽的列表）

• 如果生产者内核无法启动，因为消费者内核先启动并占用了一些生产者内核启动所需的 SM。 强烈建议设置 CUBLASLT_MATMUL_DESC_SM_COUNT_TARGET 以划出一些 SM 用于执行非矩阵乘法（通常是通信）内核。

• 如果在消费者内核启动后但在生产者内核启动之前调用了 cudaDeviceSynchronize()。

• 当启用 延迟模块加载 时，并且由于 CUDA 运行时库中的锁定，生产者内核在消费者内核运行时无法加载。 两个内核也必须在它们一起运行之前加载，以避免这种情况。 使用 CUDA Graphs 是避免由于延迟加载导致死锁的另一种方法。

注意

此功能面向高级用户，仅在 Hopper 架构上适用于启用快速累加模式的 FP8 非批量情况，并且由于对其使用的大量限制，因此被认为是 Beta 质量。

3.2. cuBLASLt 代码示例

请访问 https://github.com/NVIDIA/CUDALibrarySamples/tree/master/cuBLASLt 以获取更新的代码示例。

3.3. cuBLASLt 数据类型参考

3.3.1. cublasLtClusterShape_t

cublasLtClusterShape_t 是一种枚举类型，用于配置线程块集群维度。 线程块集群添加了一个可选的层次级别，由线程块组成。 与线程块类似，这些可以是单维、二维或三维的。 另请参阅 线程块集群。

值	描述
CUBLASLT_CLUSTER_SHAPE_AUTO	自动选择集群形状。
CUBLASLT_CLUSTER_SHAPE_1x1x1	集群形状为 1 x 1 x 1。
CUBLASLT_CLUSTER_SHAPE_1x2x1	集群形状为 1 x 2 x 1。
CUBLASLT_CLUSTER_SHAPE_1x4x1	集群形状为 1 x 4 x 1。
CUBLASLT_CLUSTER_SHAPE_2x1x1	集群形状为 2 x 1 x 1。
CUBLASLT_CLUSTER_SHAPE_2x2x1	集群形状为 2 x 2 x 1。
CUBLASLT_CLUSTER_SHAPE_2x4x1	集群形状为 2 x 4 x 1。
CUBLASLT_CLUSTER_SHAPE_4x1x1	集群形状为 4 x 1 x 1。
CUBLASLT_CLUSTER_SHAPE_4x2x1	集群形状为 4 x 2 x 1。
CUBLASLT_CLUSTER_SHAPE_4x4x1	集群形状为 4 x 4 x 1。
CUBLASLT_CLUSTER_SHAPE_1x8x1	集群形状为 1 x 8 x 1。
CUBLASLT_CLUSTER_SHAPE_8x1x1	集群形状为 8 x 1 x 1。
CUBLASLT_CLUSTER_SHAPE_2x8x1	集群形状为 2 x 8 x 1。
CUBLASLT_CLUSTER_SHAPE_8x2x1	集群形状为 8 x 2 x 1。
CUBLASLT_CLUSTER_SHAPE_1x16x1	集群形状为 1 x 16 x 1。
CUBLASLT_CLUSTER_SHAPE_16x1x1	集群形状为 16 x 1 x 1。
CUBLASLT_CLUSTER_SHAPE_1x3x1	集群形状为 1 x 3 x 1。
CUBLASLT_CLUSTER_SHAPE_1x5x1	集群形状为 1 x 5 x 1。
CUBLASLT_CLUSTER_SHAPE_1x6x1	集群形状为 1 x 6 x 1。
CUBLASLT_CLUSTER_SHAPE_1x7x1	集群形状为 1 x 7 x 1。
CUBLASLT_CLUSTER_SHAPE_1x9x1	集群形状为 1 x 9 x 1。
CUBLASLT_CLUSTER_SHAPE_1x10x1	集群形状为 1 x 10 x 1。
CUBLASLT_CLUSTER_SHAPE_1x11x1	集群形状为 1 x 11 x 1。
CUBLASLT_CLUSTER_SHAPE_1x12x1	集群形状为 1 x 12 x 1。
CUBLASLT_CLUSTER_SHAPE_1x13x1	集群形状为 1 x 13 x 1。
CUBLASLT_CLUSTER_SHAPE_1x14x1	集群形状为 1 x 14 x 1。
CUBLASLT_CLUSTER_SHAPE_1x15x1	集群形状为 1 x 15 x 1。
CUBLASLT_CLUSTER_SHAPE_2x3x1	集群形状为 2 x 3 x 1。
CUBLASLT_CLUSTER_SHAPE_2x5x1	集群形状为 2 x 5 x 1。
CUBLASLT_CLUSTER_SHAPE_2x6x1	集群形状为 2 x 6 x 1。
CUBLASLT_CLUSTER_SHAPE_2x7x1	集群形状为 2 x 7 x 1。
CUBLASLT_CLUSTER_SHAPE_3x1x1	集群形状为 3 x 1 x 1。
CUBLASLT_CLUSTER_SHAPE_3x2x1	集群形状为 3 x 2 x 1。
CUBLASLT_CLUSTER_SHAPE_3x3x1	集群形状为 3 x 3 x 1。
CUBLASLT_CLUSTER_SHAPE_3x4x1	集群形状为 3 x 4 x 1。
CUBLASLT_CLUSTER_SHAPE_3x5x1	集群形状为 3 x 5 x 1。
CUBLASLT_CLUSTER_SHAPE_4x3x1	集群形状为 4 x 3 x 1。
CUBLASLT_CLUSTER_SHAPE_5x1x1	集群形状为 5 x 1 x 1。
CUBLASLT_CLUSTER_SHAPE_5x2x1	集群形状为 5 x 2 x 1。
CUBLASLT_CLUSTER_SHAPE_5x3x1	集群形状为 5 x 3 x 1。
CUBLASLT_CLUSTER_SHAPE_6x1x1	集群形状为 6 x 1 x 1。
CUBLASLT_CLUSTER_SHAPE_6x2x1	集群形状为 6 x 2 x 1。
CUBLASLT_CLUSTER_SHAPE_7x1x1	集群形状为 7 x 1 x 1。
CUBLASLT_CLUSTER_SHAPE_7x2x1	集群形状为 7 x 2 x 1。
CUBLASLT_CLUSTER_SHAPE_9x1x1	集群形状为 9 x 1 x 1。
CUBLASLT_CLUSTER_SHAPE_10x1x1	集群形状为 10 x 1 x 1。
CUBLASLT_CLUSTER_SHAPE_11x1x1	集群形状为 11 x 1 x 1。
CUBLASLT_CLUSTER_SHAPE_12x1x1	集群形状为 12 x 1 x 1。
CUBLASLT_CLUSTER_SHAPE_13x1x1	集群形状为 13 x 1 x 1。
CUBLASLT_CLUSTER_SHAPE_14x1x1	集群形状为 14 x 1 x 1。
CUBLASLT_CLUSTER_SHAPE_15x1x1	集群形状为 15 x 1 x 1。

3.3.2. cublasLtEpilogue_t

cublasLtEpilogue_t 是一种枚举类型，用于设置后记的后处理选项。

值	描述
CUBLASLT_EPILOGUE_DEFAULT = 1	没有特殊的后处理，只需在必要时缩放和量化结果。
CUBLASLT_EPILOGUE_RELU = 2	将 ReLU 逐点变换应用于结果 (x := max(x, 0))。
CUBLASLT_EPILOGUE_RELU_AUX = CUBLASLT_EPILOGUE_RELU \| 128	将 ReLU 逐点变换应用于结果 (x := max(x, 0))。 此后记模式生成一个额外的输出，请参阅 cublasLtMatmulDescAttributes_t 的 CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_POINTER。
CUBLASLT_EPILOGUE_BIAS = 4	从偏置向量应用（广播）偏置。 偏置向量长度必须与矩阵 D 的行匹配，并且必须是紧凑的（例如，向量元素之间的步幅为 1）。 偏置向量广播到所有列，并在应用最终后处理之前添加。
CUBLASLT_EPILOGUE_RELU_BIAS = CUBLASLT_EPILOGUE_RELU = CUBLASLT_EPILOGUE_BIAS	应用偏置，然后应用 ReLU 变换。
CUBLASLT_EPILOGUE_RELU_AUX_BIAS = CUBLASLT_EPILOGUE_RELU_AUX = CUBLASLT_EPILOGUE_BIAS	应用偏置，然后应用 ReLU 变换。 此后记模式生成一个额外的输出，请参阅 cublasLtMatmulDescAttributes_t 的 ``CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_POINTER``。
CUBLASLT_EPILOGUE_DRELU = 8 \| 128	将 ReLu 梯度应用于矩阵乘法输出。 将 ReLu 梯度存储在输出矩阵中。 此后记模式需要一个额外的输入，请参阅 cublasLtMatmulDescAttributes_t 的 ``CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_POINTER``。
CUBLASLT_EPILOGUE_DRELU_BGRAD = CUBLASLT_EPILOGUE_DRELU \| 16	将 ReLu 和 Bias 梯度独立应用于矩阵乘法输出。 将 ReLu 梯度存储在输出矩阵中，并将 Bias 梯度存储在偏置缓冲区中（请参阅 CUBLASLT_MATMUL_DESC_BIAS_POINTER）。 此后记模式需要一个额外的输入，请参阅 cublasLtMatmulDescAttributes_t 的 ``CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_POINTER``。
CUBLASLT_EPILOGUE_GELU = 32	将 GELU 逐点变换应用于结果 (x := GELU(x))。
CUBLASLT_EPILOGUE_GELU_AUX = CUBLASLT_EPILOGUE_GELU \| 128	将 GELU 逐点变换应用于结果 (x := GELU(x))。 此后记模式将 GELU 输入作为单独的矩阵输出（对训练有用）。 请参阅 cublasLtMatmulDescAttributes_t 的 ``CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_POINTER``。
CUBLASLT_EPILOGUE_GELU_BIAS = CUBLASLT_EPILOGUE_GELU = CUBLASLT_EPILOGUE_BIAS	应用 Bias，然后应用 GELU 变换 7。
CUBLASLT_EPILOGUE_GELU_AUX_BIAS = CUBLASLT_EPILOGUE_GELU_AUX = CUBLASLT_EPILOGUE_BIAS	应用 Bias，然后应用 GELU 变换 7。 此后记模式将 GELU 输入作为单独的矩阵输出（对训练有用）。 请参阅 cublasLtMatmulDescAttributes_t 的 ``CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_POINTER``。
CUBLASLT_EPILOGUE_DGELU = 64 \| 128	将 GELU 梯度应用于矩阵乘法输出。 将 GELU 梯度存储在输出矩阵中。 此后记模式需要一个额外的输入，请参阅 cublasLtMatmulDescAttributes_t 的 ``CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_POINTER``。
CUBLASLT_EPILOGUE_DGELU_BGRAD = CUBLASLT_EPILOGUE_DGELU \| 16	将 GELU 和 Bias 梯度独立应用于矩阵乘法输出。 将 GELU 梯度存储在输出矩阵中，并将 Bias 梯度存储在偏置缓冲区中（请参阅 CUBLASLT_MATMUL_DESC_BIAS_POINTER）。 此后记模式需要一个额外的输入，请参阅 cublasLtMatmulDescAttributes_t 的 ``CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_POINTER``。
CUBLASLT_EPILOGUE_BGRADA = 256	将 Bias 梯度应用于输入矩阵 A。偏置大小对应于矩阵 D 的行数。缩减发生在 GEMM 的 “k” 维度上。 将 Bias 梯度存储在偏置缓冲区中，请参阅 cublasLtMatmulDescAttributes_t 的 ``CUBLASLT_MATMUL_DESC_BIAS_POINTER``。
CUBLASLT_EPILOGUE_BGRADB = 512	将 Bias 梯度应用于输入矩阵 B。偏置大小对应于矩阵 D 的列数。缩减发生在 GEMM 的 “k” 维度上。 将 Bias 梯度存储在偏置缓冲区中，请参阅 cublasLtMatmulDescAttributes_t 的 ``CUBLASLT_MATMUL_DESC_BIAS_POINTER``。

注释

7(1,2)

GELU（高斯误差线性单元）近似为： \({0.5}x\left( 1 + \text{tanh}\left( \sqrt{2/\pi}\left( x + {0.044715}x^{3} \right) \right) \right)\)

3.3.3. cublasLtHandle_t

cublasLtHandle_t 类型是指向不透明结构的指针类型，该结构保存 cuBLASLt 库上下文。 使用 cublasLtCreate() 初始化 cuBLASLt 库上下文并返回指向保存 cuBLASLt 库上下文的不透明结构的句柄，并使用 cublasLtDestroy() 销毁先前创建的 cuBLASLt 库上下文描述符并释放资源。

注意

cuBLAS 句柄 (cublasHandle_t) 封装了一个 cuBLASLt 句柄。 任何有效的 cublasHandle_t 都可以通过简单的强制转换代替 cublasLtHandle_t 使用。 但是，与 cuBLAS 句柄不同，cuBLASLt 句柄不绑定到任何特定的 CUDA 上下文，除了绑定到图形上下文的 CUDA 上下文（从 CUDA 12.8 开始）。 如果在当前 CUDA 上下文绑定到图形上下文时创建了 cuBLASLt 句柄，则 cuBLASLt 会检测到相应的共享内存限制并将其记录在句柄中。

3.3.4. cublasLtLoggerCallback_t

cublasLtLoggerCallback_t 是一种回调函数指针类型。 可以使用 cublasLtLoggerSetCallback() 设置回调函数。

参数:

参数	内存	输入/输出	描述
logLevel		输出	请参阅 cuBLASLt 日志记录。
functionName		输出	记录此消息的 API 的名称。
message		输出	日志消息。

3.3.5. cublasLtMatmulAlgo_t

cublasLtMatmulAlgo_t 是一个不透明的结构，用于保存矩阵乘法算法的描述。 此结构可以轻松序列化，并在以后恢复以用于相同版本的 cuBLAS 库，以节省再次选择正确配置的时间。

3.3.6. cublasLtMatmulAlgoCapAttributes_t

cublasLtMatmulAlgoCapAttributes_t 枚举了可以从已初始化的 cublasLtMatmulAlgo_t 描述符中使用 cublasLtMatmulAlgoCapGetAttribute() 检索的矩阵乘法算法能力属性。

值	描述	数据类型
CUBLASLT_ALGO_CAP_SPLITK_SUPPORT	对 split-K 的支持。 布尔值（0 或 1）表示是否支持 split-K 实现。 0 表示不支持，否则表示支持。 请参阅 cublasLtMatmulAlgoConfigAttributes_t 的 CUBLASLT_ALGO_CONFIG_SPLITK_NUM。	int32_t
CUBLASLT_ALGO_CAP_REDUCTION_SCHEME_MASK	用于表示支持的归约方案类型的掩码，请参阅 cublasLtReductionScheme_t。 如果未屏蔽归约方案，则表示支持。 例如： int isReductionSchemeComputeTypeSupported ? (reductionSchemeMask & CUBLASLT_REDUCTION_SCHEME_COMPUTE_TYPE) == CUBLASLT_REDUCTION_SCHEME_COMPUTE_TYPE ? 1 : 0;	uint32_t
CUBLASLT_ALGO_CAP_CTA_SWIZZLING_SUPPORT	对 CTA 交错的支持。 布尔值（0 或 1）表示是否支持 CTA 交错实现。 0 表示不支持，1 表示支持值 1；其他值保留。 另请参阅 cublasLtMatmulAlgoConfigAttributes_t 的 CUBLASLT_ALGO_CONFIG_CTA_SWIZZLING。	uint32_t
CUBLASLT_ALGO_CAP_STRIDED_BATCH_SUPPORT	支持步幅式批处理。 0 表示不支持，否则表示支持。	int32_t
CUBLASLT_ALGO_CAP_OUT_OF_PLACE_RESULT_SUPPORT	支持异地结果（D != C in D = alpha.A.B + beta.C）。 0 表示不支持，否则表示支持。	int32_t
CUBLASLT_ALGO_CAP_UPLO_SUPPORT	Syrk（对称秩 k 更新）/herk（Hermitian 秩 k 更新）支持（在常规 gemm 之上）。 0 表示不支持，否则表示支持。	int32_t
CUBLASLT_ALGO_CAP_TILE_IDS	可能使用的 tile id。 请参阅 cublasLtMatmulTile_t。 如果不支持任何 tile id，则使用 CUBLASLT_MATMUL_TILE_UNDEFINED。 使用 cublasLtMatmulAlgoCapGetAttribute() 和 sizeInBytes = 0 查询实际计数。	uint32_t[]
CUBLASLT_ALGO_CAP_STAGES_IDS	可能使用的 stages id。 请参阅 cublasLtMatmulStages_t。 如果不支持任何 stages id，则使用 CUBLASLT_MATMUL_STAGES_UNDEFINED。 使用 cublasLtMatmulAlgoCapGetAttribute() 和 sizeInBytes = 0 查询实际计数。	uint32_t[]
CUBLASLT_ALGO_CAP_CUSTOM_OPTION_MAX	自定义选项范围从 0 到 CUBLASLT_ALGO_CAP_CUSTOM_OPTION_MAX（包括）。 请参阅 cublasLtMatmulAlgoConfigAttributes_t 的 CUBLASLT_ALGO_CONFIG_CUSTOM_OPTION 。	int32_t
CUBLASLT_ALGO_CAP_MATHMODE_IMPL	指示算法是使用常规计算还是张量运算。 0 表示常规计算，1 表示张量运算。 已弃用	int32_t
CUBLASLT_ALGO_CAP_GAUSSIAN_IMPL	指示算法是否实现了复数矩阵乘法的 Gaussian 优化。 0 表示常规计算； 1 表示 Gaussian。 请参阅 cublasMath_t。 已弃用	int32_t
CUBLASLT_ALGO_CAP_CUSTOM_MEMORY_ORDER	指示算法是否支持自定义（非 COL 或 ROW 内存顺序）。 0 表示仅允许 COL 和 ROW 内存顺序，非零表示算法可能具有不同的要求。 请参阅 cublasLtOrder_t。	int32_t
CUBLASLT_ALGO_CAP_POINTER_MODE_MASK	枚举算法支持的指针模式的位掩码。 请参阅 cublasLtPointerModeMask_t。	uint32_t
CUBLASLT_ALGO_CAP_EPILOGUE_MASK	枚举后记中支持的后处理种类的位掩码。 请参阅 cublasLtEpilogue_t。	uint32_t
CUBLASLT_ALGO_CAP_LD_NEGATIVE	支持所有矩阵的负前导维度。 0 表示不支持，否则表示支持。	uint32_t
CUBLASLT_ALGO_CAP_NUMERICAL_IMPL_FLAGS	有关影响算法数值行为的实现细节。 请参阅 cublasLtNumericalImplFlags_t。	uint64_t
CUBLASLT_ALGO_CAP_MIN_ALIGNMENT_A_BYTES	A 矩阵所需的最小对齐字节数。	uint32_t
CUBLASLT_ALGO_CAP_MIN_ALIGNMENT_B_BYTES	B 矩阵所需的最小对齐字节数。	uint32_t
CUBLASLT_ALGO_CAP_MIN_ALIGNMENT_C_BYTES	C 矩阵所需的最小对齐字节数。	uint32_t
CUBLASLT_ALGO_CAP_MIN_ALIGNMENT_D_BYTES	D 矩阵所需的最小对齐字节数。	uint32_t
CUBLASLT_ALGO_CAP_ATOMIC_SYNC	支持通过原子计数器进行同步。 请参阅 原子同步。	int32_t

3.3.7. cublasLtMatmulAlgoConfigAttributes_t

cublasLtMatmulAlgoConfigAttributes_t 是一种枚举类型，其中包含 cuBLASLt 矩阵乘法算法的配置属性。 配置属性是算法特定的，并且可以设置。 给定算法的属性配置应与其能力属性一致。 使用 cublasLtMatmulAlgoConfigGetAttribute() 和 cublasLtMatmulAlgoConfigSetAttribute() 获取和设置矩阵乘法算法描述符的属性值。

值	描述	数据类型
CUBLASLT_ALGO_CONFIG_ID	只读属性。 算法索引。 请参阅 cublasLtMatmulAlgoGetIds()。 由 cublasLtMatmulAlgoInit() 设置。	int32_t
CUBLASLT_ALGO_CONFIG_TILE_ID	Tile id。 请参阅 cublasLtMatmulTile_t。 默认值： CUBLASLT_MATMUL_TILE_UNDEFINED。	uint32_t
CUBLASLT_ALGO_CONFIG_STAGES_ID	stages id，请参阅 cublasLtMatmulStages_t。 默认值： CUBLASLT_MATMUL_STAGES_UNDEFINED。	uint32_t
CUBLASLT_ALGO_CONFIG_SPLITK_NUM	K 分裂的数量。 如果 K 分裂的数量大于 1，则将并行计算矩阵乘法的 SPLITK_NUM 部分。 结果将根据 CUBLASLT_ALGO_CONFIG_REDUCTION_SCHEME 累积。	uint32_t
CUBLASLT_ALGO_CONFIG_REDUCTION_SCHEME	当 splitK 值 > 1 时要使用的归约方案。 默认值： CUBLASLT_REDUCTION_SCHEME_NONE。 请参阅 cublasLtReductionScheme_t。	uint32_t
CUBLASLT_ALGO_CONFIG_CTA_SWIZZLING	启用/禁用 CTA 交错。 更改从 CUDA 网格坐标到矩阵各部分的映射。 可能的值：0 和 1；其他值保留。	uint32_t
CUBLASLT_ALGO_CONFIG_CUSTOM_OPTION	自定义选项值。 每个算法都可以支持一些不适合其他配置属性描述的自定义选项。 请参阅 cublasLtMatmulAlgoCapAttributes_t 的 CUBLASLT_ALGO_CAP_CUSTOM_OPTION_MAX 以获取特定情况的接受范围。	uint32_t
CUBLASLT_ALGO_CONFIG_INNER_SHAPE_ID	内部形状 ID。 请参阅 cublasLtMatmulInnerShape_t. 默认值： CUBLASLT_MATMUL_INNER_SHAPE_UNDEFINED。	uint16_t
CUBLASLT_ALGO_CONFIG_CLUSTER_SHAPE_ID	集群形状 ID。 请参阅 cublasLtClusterShape_t. 默认值： CUBLASLT_CLUSTER_SHAPE_AUTO。	uint16_t

3.3.8. cublasLtMatmulDesc_t

cublasLtMatmulDesc_t 是指向不透明结构的指针，该结构保存矩阵乘法运算 cublasLtMatmul() 的描述。 可以通过调用 cublasLtMatmulDescCreate() 创建描述符，并通过调用 cublasLtMatmulDescDestroy() 销毁描述符。

3.3.9. cublasLtMatmulDescAttributes_t

cublasLtMatmulDescAttributes_t 是一个描述符结构，包含定义矩阵乘法运算细节的属性。 使用 cublasLtMatmulDescGetAttribute() 和 cublasLtMatmulDescSetAttribute() 获取和设置矩阵乘法描述符的属性值。

值	描述	数据类型
CUBLASLT_MATMUL_DESC_COMPUTE_TYPE	计算类型。 定义用于乘法和累加运算的数据类型，以及矩阵乘法期间的累加器。 请参阅 cublasComputeType_t。	int32_t
CUBLASLT_MATMUL_DESC_SCALE_TYPE	缩放类型。 定义缩放因子 alpha 和 beta 的数据类型。 累加器值和来自矩阵 C 的值通常在最终缩放之前转换为缩放类型。 然后，该值从缩放类型转换为矩阵 D 的类型，然后再存储在内存中。 默认值取决于 CUBLASLT_MATMUL_DESC_COMPUTE_TYPE。 请参阅 cudaDataType_t。	int32_t
CUBLASLT_MATMUL_DESC_POINTER_MODE	指定 alpha 和 beta 是否通过引用传递，它们是主机上还是设备上的标量，还是设备向量。 默认值为： CUBLASLT_POINTER_MODE_HOST（即，在主机上）。 请参阅 cublasLtPointerMode_t。	int32_t
CUBLASLT_MATMUL_DESC_TRANSA	指定应在矩阵 A 上执行的变换操作的类型。 默认值为： CUBLAS_OP_N（即，非转置运算）。 请参阅 cublasOperation_t。	int32_t
CUBLASLT_MATMUL_DESC_TRANSB	指定应在矩阵 B 上执行的变换操作的类型。 默认值为： CUBLAS_OP_N（即，非转置运算）。 请参阅 cublasOperation_t。	int32_t
CUBLASLT_MATMUL_DESC_TRANSC	指定应在矩阵 C 上执行的变换操作的类型。 当前仅支持 CUBLAS_OP_N。 默认值为： CUBLAS_OP_N（即，非转置运算）。 请参阅 cublasOperation_t。	int32_t
CUBLASLT_MATMUL_DESC_FILL_MODE	指示是否填充了稠密矩阵的下半部分或上半部分，因此应由函数使用。 当前，此标志不支持 bfloat16 或 FP8 数据类型，并且在以下 GPU 上不支持：Hopper、Blackwell。 默认值为： CUBLAS_FILL_MODE_FULL。 请参阅 cublasFillMode_t。	int32_t
CUBLASLT_MATMUL_DESC_EPILOGUE	后记函数。 请参阅 cublasLtEpilogue_t。 默认值为： CUBLASLT_EPILOGUE_DEFAULT。	uint32_t
CUBLASLT_MATMUL_DESC_BIAS_POINTER	设备内存中的 Bias 或 Bias 梯度向量指针。 当使用以下后记之一时，长度与矩阵 D 的行数匹配的输入向量：CUBLASLT_EPILOGUE_BIAS、CUBLASLT_EPILOGUE_RELU_BIAS、CUBLASLT_EPILOGUE_RELU_AUX_BIAS、CUBLASLT_EPILOGUE_GELU_BIAS、CUBLASLT_EPILOGUE_GELU_AUX_BIAS。 当使用以下后记之一时，长度与矩阵 D 的行数匹配的输出向量：CUBLASLT_EPILOGUE_DRELU_BGRAD、CUBLASLT_EPILOGUE_DGELU_BGRAD、CUBLASLT_EPILOGUE_BGRADA。 当使用以下后记之一时，长度与矩阵 D 的列数匹配的输出向量：CUBLASLT_EPILOGUE_BGRADB。 当矩阵 D 数据类型为 CUDA_R_8I 时，Bias 向量元素类型与 alpha 和 beta 类型相同（请参阅此表中的 CUBLASLT_MATMUL_DESC_SCALE_TYPE），否则与矩阵 D 数据类型相同。 有关详细映射，请参阅 cublasLtMatmul() 下的数据类型表。 默认值为：NULL。	void * / const void *
CUBLASLT_MATMUL_DESC_BIAS_BATCH_STRIDE	用于步幅批处理操作的下一个 Bias 或 Bias 梯度向量的步幅（以元素为单位）。 默认值为 0。	int64_t
CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_POINTER	后记辅助缓冲区的指针。 当使用 CUBLASLT_EPILOGUE_RELU_AUX 或 CUBLASLT_EPILOGUE_RELU_AUX_BIAS 后记时，正向传播中的 ReLu 位掩码的输出向量。 当使用 CUBLASLT_EPILOGUE_DRELU 或 CUBLASLT_EPILOGUE_DRELU_BGRAD 后记时，反向传播中的 ReLu 位掩码的输入向量。 当使用 CUBLASLT_EPILOGUE_GELU_AUX_BIAS 后记时，正向传播中 GELU 输入矩阵的输出。 当使用 CUBLASLT_EPILOGUE_DGELU 或 CUBLASLT_EPILOGUE_DGELU_BGRAD 后记时，反向传播中 GELU 输入矩阵的输入。 有关辅助数据类型，请参阅 CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_DATA_TYPE。 像 cublasLtMatmulAlgoGetHeuristic() 这样不取消引用此指针的例程依赖于它的值来确定预期的指针对齐方式。 需要设置 CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_LD 属性。	void * / const void *
CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_LD	后记辅助缓冲区的引导维度。 当使用 CUBLASLT_EPILOGUE_RELU_AUX、CUBLASLT_EPILOGUE_RELU_AUX_BIAS、CUBLASLT_EPILOGUE_DRELU_BGRAD 或 CUBLASLT_EPILOGUE_DRELU_BGRAD 后记时，ReLu 位掩码矩阵的引导维度（以元素，即比特为单位）。 必须能被 128 整除，并且不小于输出矩阵的行数。 当使用 CUBLASLT_EPILOGUE_GELU_AUX_BIAS、CUBLASLT_EPILOGUE_DGELU 或 CUBLASLT_EPILOGUE_DGELU_BGRAD 后记时，GELU 输入矩阵的引导维度（以元素为单位）。 必须能被 8 整除，并且不小于输出矩阵的行数。	int64_t
CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_BATCH_STRIDE	后记辅助缓冲区的批处理步幅。 当使用 CUBLASLT_EPILOGUE_RELU_AUX、CUBLASLT_EPILOGUE_RELU_AUX_BIAS 或 CUBLASLT_EPILOGUE_DRELU_BGRAD 后记时，ReLu 位掩码矩阵的批处理步幅（以元素，即比特为单位）。 必须能被 128 整除。 当使用 CUBLASLT_EPILOGUE_GELU_AUX_BIAS、CUBLASLT_EPILOGUE_DRELU 或 CUBLASLT_EPILOGUE_DGELU_BGRAD 后记时，GELU 输入矩阵的批处理步幅（以元素为单位）。 必须能被 8 整除。 默认值：0。	int64_t
CUBLASLT_MATMUL_DESC_ALPHA_VECTOR_BATCH_STRIDE	Alpha 向量的批处理步幅。 当矩阵 D 的 CUBLASLT_MATRIX_LAYOUT_BATCH_COUNT 大于 1 时，与 CUBLASLT_POINTER_MODE_ALPHA_DEVICE_VECTOR_BETA_HOST 一起使用。 如果设置了 CUBLASLT_POINTER_MODE_ALPHA_DEVICE_VECTOR_BETA_ZERO，则 CUBLASLT_MATMUL_DESC_ALPHA_VECTOR_BATCH_STRIDE 必须设置为 0，因为此模式不支持批处理 alpha 向量。 默认值：0。	int64_t
CUBLASLT_MATMUL_DESC_SM_COUNT_TARGET	并行执行的目标 SM 数量。 当用户期望并发流占用某些设备资源时，优化针对不同 SM 数量执行的启发式算法。 默认值：0。	int32_t
CUBLASLT_MATMUL_DESC_A_SCALE_POINTER	指向比例因子值的设备指针，该值将矩阵 A 中的数据转换为计算数据类型范围。 比例因子必须与计算类型具有相同的类型。 如果未指定或设置为 NULL，则假定比例因子为 1。 如果为不支持的矩阵数据、比例和计算类型组合设置，则调用 cublasLtMatmul() 将返回 CUBLAS_INVALID_VALUE。 默认值：NULL	const void *
CUBLASLT_MATMUL_DESC_B_SCALE_POINTER	等效于矩阵 B 的 CUBLASLT_MATMUL_DESC_A_SCALE_POINTER。 默认值：NULL	const void *
CUBLASLT_MATMUL_DESC_C_SCALE_POINTER	等效于矩阵 C 的 CUBLASLT_MATMUL_DESC_A_SCALE_POINTER。 默认值：NULL	const void *
CUBLASLT_MATMUL_DESC_D_SCALE_POINTER	等效于矩阵 D 的 CUBLASLT_MATMUL_DESC_A_SCALE_POINTER。 默认值：NULL	const void *
CUBLASLT_MATMUL_DESC_AMAX_D_POINTER	指向内存位置的设备指针，该位置在完成时将设置为输出矩阵中绝对值的最大值。 计算值与计算类型具有相同的类型。 如果未指定或设置为 NULL，则不计算最大绝对值。 如果为不支持的矩阵数据、比例和计算类型组合设置，则调用 cublasLtMatmul() 将返回 CUBLAS_INVALID_VALUE。 默认值：NULL	void *
CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_DATA_TYPE	将存储在 CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_POINTER 中的数据类型。 如果未设置（或设置为默认值 -1），则数据类型设置为输出矩阵元素数据类型 (DType)，但有一些例外 ReLu 使用位掩码。 对于输出类型 (DType) 为 CUDA_R_8F_E4M3 的 FP8 内核，如果满足以下条件，则可以将数据类型设置为非默认值 AType 和 BType 为 CUDA_R_8F_E4M3。 Bias Type 为 CUDA_R_16F。 CType 为 CUDA_R_16BF 或 CUDA_R_16F CUBLASLT_MATMUL_DESC_EPILOGUE 设置为 CUBLASLT_EPILOGUE_GELU_AUX 当 CType 为 CUDA_R_16F 时，数据类型可以设置为 CUDA_R_16F 或 CUDA_R_8F_E4M3。 当 CType 为 CUDA_R_16BF 时，数据类型可以设置为 CUDA_R_16BF。 否则，数据类型应保持未设置或设置为默认值 -1。 如果为不支持的矩阵数据、比例和计算类型组合设置，则调用 cublasLtMatmul() 将返回 CUBLAS_INVALID_VALUE。 默认值：-1	int32_t (cudaDataType_t)
CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_SCALE_POINTER	指向比例因子值的设备指针，用于将通过 CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_POINTER 设置的辅助矩阵中的计算类型数据范围的结果转换为存储数据范围。 比例因子值必须与计算类型具有相同的类型。 如果未指定或设置为 NULL，则假定比例因子为 1。 如果为不支持的矩阵数据、比例和计算类型组合设置，则调用 cublasLtMatmul() 将返回 CUBLAS_INVALID_VALUE。 默认值：NULL	void *
CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_AMAX_POINTER	指向内存位置的设备指针，该位置在完成时将设置为通过 CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_POINTER 设置的缓冲区中绝对值的最大值。 计算值与计算类型具有相同的类型。 如果未指定或设置为 NULL，则不计算最大绝对值。 如果为不支持的矩阵数据、比例和计算类型组合设置，则调用 cublasLtMatmul() 将返回 CUBLAS_INVALID_VALUE。 默认值：NULL	void *
CUBLASLT_MATMUL_DESC_FAST_ACCUM	用于管理 FP8 快速累积模式的标志。 启用后，在某些 GPU 上，问题执行可能会更快，但会以降低精度为代价，因为中间结果不会定期提升到更高的精度。 目前，此标志对以下 GPU 有影响：Ada、Hopper。 默认值：0 - 禁用快速累积模式	int8_t
CUBLASLT_MATMUL_DESC_BIAS_DATA_TYPE	设备内存中 Bias 或 Bias 梯度向量的类型。 Bias 情况：请参阅 CUBLASLT_EPILOGUE_BIAS。 如果未设置（或设置为默认值 -1），则 Bias 向量元素类型与输出矩阵 (Dtype) 的元素类型相同，但以下情况除外 computeType=CUDA_R_32I 和 Ctype=CUDA_R_8I 的 IMMA 内核，其中 Bias 向量元素类型与 alpha、beta 类型相同 (CUBLASLT_MATMUL_DESC_SCALE_TYPE=CUDA_R_32F) 对于输出类型为 CUDA_R_32F、CUDA_R_8F_E4M3 或 CUDA_R_8F_E5M2 的 FP8 内核。 有关更多详细信息，请参阅 cublasLtMatmul()。 默认值：-1	int32_t (cudaDataType_t)
CUBLASLT_MATMUL_DESC_ATOMIC_SYNC_IN_COUNTERS_POINTER	指向 matmul 使用的输入原子计数器设备数组的指针。 当计数器达到零时，允许开始计算输出张量的相应块。 默认值：NULL。 请参阅 原子同步。	int32_t *
CUBLASLT_MATMUL_DESC_ATOMIC_SYNC_OUT_COUNTERS_POINTER	指向 matmul 生成的输出原子计数器设备数组的指针。 当输出张量的相应块的计算完成时，matmul 内核将计数器设置为零。 在运行 matmul 内核之前，所有计数器都必须初始化为 1。 默认值：NULL。 请参阅 原子同步。	int32_t *
CUBLASLT_MATMUL_DESC_ATOMIC_SYNC_NUM_CHUNKS_D_ROWS [已弃用]	此模式已弃用，将在未来版本中删除。 输出矩阵 D 的行维度中的原子同步块数。 每个块对应于一个原子计数器。 默认值：0（禁用原子同步）。 请参阅 原子同步。	int32_t
CUBLASLT_MATMUL_DESC_ATOMIC_SYNC_NUM_CHUNKS_D_COLS [已弃用]	此模式已弃用，将在未来版本中删除。 输出矩阵 D 的列维度中的原子同步块数。 每个块对应于一个原子计数器。 默认值：0（禁用原子同步）。 请参阅 原子同步。	int32_t
CUBLASLT_MATMUL_DESC_A_SCALE_MODE	定义如何解释矩阵 A 的矩阵比例因子的比例模式。 默认值：0。 请参阅 cublasLtMatmulMatrixScale_t。	int32_t
CUBLASLT_MATMUL_DESC_B_SCALE_MODE	定义如何解释矩阵 B 的矩阵比例因子的比例模式。 默认值：0。 请参阅 cublasLtMatmulMatrixScale_t。	int32_t
CUBLASLT_MATMUL_DESC_C_SCALE_MODE	定义如何解释矩阵 C 的矩阵比例因子的比例模式。 默认值：0。 请参阅 cublasLtMatmulMatrixScale_t。	int32_t
CUBLASLT_MATMUL_DESC_D_SCALE_MODE	定义如何解释矩阵 D 的矩阵比例因子的比例模式。 默认值：0。 请参阅 cublasLtMatmulMatrixScale_t。	int32_t
CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_SCALE_MODE	定义如何解释辅助矩阵的矩阵比例因子的比例模式。 默认值：0。 请参阅 cublasLtMatmulMatrixScale_t。	int32_t
CUBLASLT_MATMUL_DESC_D_OUT_SCALE_POINTER	指向比例因子的设备指针，这些比例因子用于将矩阵 D 中的数据转换为计算数据类型范围。 比例因子值类型由比例模式定义（请参阅 CUBLASLT_MATMUL_DESC_D_OUT_SCALE_MODE）。 如果为不支持的矩阵数据、比例、比例模式和计算类型组合设置，则调用 cublasLtMatmul() 将返回 CUBLAS_INVALID_VALUE。 默认值：NULL	void *
CUBLASLT_MATMUL_DESC_D_OUT_SCALE_MODE	定义如何解释矩阵 D 的输出矩阵比例因子的比例模式。 默认值：0。 请参阅 cublasLtMatmulMatrixScale_t。	int32_t

3.3.10. cublasLtMatmulHeuristicResult_t

cublasLtMatmulHeuristicResult_t 是一个描述符，用于保存配置的矩阵乘法算法描述符及其运行时属性。

成员	描述
cublasLtMatmulAlgo_t algo	如果偏好设置 CUBLASLT_MATMUL_PERF_SEARCH_MODE 设置为 CUBLASLT_SEARCH_LIMITED_BY_ALGO_ID，则必须使用 cublasLtMatmulAlgoInit() 初始化。 请参阅 cublasLtMatmulSearch_t。
size_t workspaceSize;	所需的实际工作区内存大小。
cublasStatus_t state;	结果状态。 仅当调用 cublasLtMatmulAlgoGetHeuristic() 后，此成员设置为 CUBLAS_STATUS_SUCCESS 时，其他字段才有效。
float wavesCount;	Waves count 是设备利用率指标。 wavesCount 值为 1.0f 表示内核启动时将完全占用 GPU。
int reserved[4];	保留。

3.3.11. cublasLtMatmulInnerShape_t

cublasLtMatmulInnerShape_t 是一个枚举类型，用于配置内部内核设计的各个方面。 这不会影响 CUDA 网格大小。

值	描述
CUBLASLT_MATMUL_INNER_SHAPE_UNDEFINED	内部形状未定义。
CUBLASLT_MATMUL_INNER_SHAPE_MMA884	内部形状为 MMA884。
CUBLASLT_MATMUL_INNER_SHAPE_MMA1684	内部形状为 MMA1684。
CUBLASLT_MATMUL_INNER_SHAPE_MMA1688	内部形状为 MMA1688。
CUBLASLT_MATMUL_INNER_SHAPE_MMA16816	内部形状为 MMA16816。

3.3.12. cublasLtMatmulPreference_t

cublasLtMatmulPreference_t 是指向不透明结构的指针，该结构保存 cublasLtMatmulAlgoGetHeuristic() 配置的偏好设置的描述。 使用 cublasLtMatmulPreferenceCreate() 创建描述符的一个实例，并使用 cublasLtMatmulPreferenceDestroy() 销毁先前创建的描述符并释放资源。

3.3.13. cublasLtMatmulPreferenceAttributes_t

cublasLtMatmulPreferenceAttributes_t 是一个枚举类型，用于在微调启发式函数时应用算法搜索偏好设置。 使用 cublasLtMatmulPreferenceGetAttribute() 和 cublasLtMatmulPreferenceSetAttribute() 获取和设置 matmul 偏好设置描述符的属性值。

值	描述	数据类型
CUBLASLT_MATMUL_PREF_SEARCH_MODE	搜索模式。 请参阅 cublasLtMatmulSearch_t。 默认为 CUBLASLT_SEARCH_BEST_FIT。	uint32_t
CUBLASLT_MATMUL_PREF_MAX_WORKSPACE_BYTES	允许的最大工作区内存。 默认为 0（不允许使用工作区内存）。	uint64_t
CUBLASLT_MATMUL_PREF_REDUCTION_SCHEME_MASK	归约方案掩码。 请参阅 cublasLtReductionScheme_t。 仅允许算法配置指定未被此属性屏蔽的 CUBLASLT_ALGO_CONFIG_REDUCTION_SCHEME。 例如，掩码值 0x03 将仅允许 INPLACE 和 COMPUTE_TYPE 归约方案。 默认为 CUBLASLT_REDUCTION_SCHEME_MASK（即，允许所有归约方案）。	uint32_t
CUBLASLT_MATMUL_PREF_MIN_ALIGNMENT_A_BYTES	矩阵 A 的最小缓冲区对齐（以字节为单位）。 选择较小的值将排除无法与矩阵 A 一起使用的算法，这些算法的对齐方式不如算法需要的那么严格。 默认为 256 字节。	uint32_t
CUBLASLT_MATMUL_PREF_MIN_ALIGNMENT_B_BYTES	矩阵 B 的最小缓冲区对齐（以字节为单位）。 选择较小的值将排除无法与矩阵 B 一起使用的算法，这些算法的对齐方式不如算法需要的那么严格。 默认为 256 字节。	uint32_t
CUBLASLT_MATMUL_PREF_MIN_ALIGNMENT_C_BYTES	矩阵 C 的最小缓冲区对齐（以字节为单位）。 选择较小的值将排除无法与矩阵 C 一起使用的算法，这些算法的对齐方式不如算法需要的那么严格。 默认为 256 字节。	uint32_t
CUBLASLT_MATMUL_PREF_MIN_ALIGNMENT_D_BYTES	矩阵 D 的最小缓冲区对齐（以字节为单位）。 选择较小的值将排除无法与矩阵 D 一起使用的算法，这些算法的对齐方式不如算法需要的那么严格。 默认为 256 字节。	uint32_t
CUBLASLT_MATMUL_PREF_MAX_WAVES_COUNT	最大 wave count。 请参阅 cublasLtMatmulHeuristicResult_t::wavesCount. 选择非零值将排除报告设备利用率高于指定值的算法。 默认值为 0.0f.	float
CUBLASLT_MATMUL_PREF_IMPL_MASK	数值实现细节掩码。 请参阅 cublasLtNumericalImplFlags_t。 筛选启发式结果以仅包括使用允许的实现的算法。 默认值：uint64_t(-1)（允许一切）	uint64_t

3.3.14. cublasLtMatmulSearch_t

cublasLtMatmulSearch_t 是一个枚举类型，其中包含启发式搜索类型的属性。

值	描述	数据类型
CUBLASLT_SEARCH_BEST_FIT	请求针对给定用例的最佳算法的启发式算法。
CUBLASLT_SEARCH_LIMITED_BY_ALGO_ID	仅请求针对预配置的算法 ID 的启发式算法。

3.3.15. cublasLtMatmulTile_t

cublasLtMatmulTile_t 是一个枚举类型，用于设置 行 x 列 中的 tile 大小。 另请参阅 CUTLASS：CUDA C++ 中的快速线性代数。

值	描述
CUBLASLT_MATMUL_TILE_UNDEFINED	Tile 大小未定义。
CUBLASLT_MATMUL_TILE_8x8	Tile 大小为 8 行 x 8 列。
CUBLASLT_MATMUL_TILE_8x16	Tile 大小为 8 行 x 16 列。
CUBLASLT_MATMUL_TILE_16x8	Tile 大小为 16 行 x 8 列。
CUBLASLT_MATMUL_TILE_8x32	Tile 大小为 8 行 x 32 列。
CUBLASLT_MATMUL_TILE_16x16	Tile 大小为 16 行 x 16 列。
CUBLASLT_MATMUL_TILE_32x8	Tile 大小为 32 行 x 8 列。
CUBLASLT_MATMUL_TILE_8x64	Tile 大小为 8 行 x 64 列。
CUBLASLT_MATMUL_TILE_16x32	Tile 大小为 16 行 x 32 列。
CUBLASLT_MATMUL_TILE_32x16	Tile 大小为 32 行 x 16 列。
CUBLASLT_MATMUL_TILE_64x8	Tile 大小为 64 行 x 8 列。
CUBLASLT_MATMUL_TILE_32x32	Tile 大小为 32 行 x 32 列。
CUBLASLT_MATMUL_TILE_32x64	Tile 大小为 32 行 x 64 列。
CUBLASLT_MATMUL_TILE_64x32	Tile 大小为 64 行 x 32 列。
CUBLASLT_MATMUL_TILE_32x128	Tile 大小为 32 行 x 128 列。
CUBLASLT_MATMUL_TILE_64x64	Tile 大小为 64 行 x 64 列。
CUBLASLT_MATMUL_TILE_128x32	Tile 大小为 128 行 x 32 列。
CUBLASLT_MATMUL_TILE_64x128	Tile 大小为 64 行 x 128 列。
CUBLASLT_MATMUL_TILE_128x64	Tile 大小为 128 行 x 64 列。
CUBLASLT_MATMUL_TILE_64x256	Tile 大小为 64 行 x 256 列。
CUBLASLT_MATMUL_TILE_128x128	Tile 大小为 128 行 x 128 列。
CUBLASLT_MATMUL_TILE_256x64	Tile 大小为 256 行 x 64 列。
CUBLASLT_MATMUL_TILE_64x512	Tile 大小为 64 行 x 512 列。
CUBLASLT_MATMUL_TILE_128x256	Tile 大小为 128 行 x 256 列。
CUBLASLT_MATMUL_TILE_256x128	Tile 大小为 256 行 x 128 列。
CUBLASLT_MATMUL_TILE_512x64	Tile 大小为 512 行 x 64 列。
CUBLASLT_MATMUL_TILE_64x96	Tile 大小为 64 行 x 96 列。
CUBLASLT_MATMUL_TILE_96x64	Tile 大小为 96 行 x 64 列。
CUBLASLT_MATMUL_TILE_96x128	Tile 大小为 96 行 x 128 列。
CUBLASLT_MATMUL_TILE_128x160	Tile 大小为 128 行 x 160 列。
CUBLASLT_MATMUL_TILE_160x128	Tile 大小为 160 行 x 128 列。
CUBLASLT_MATMUL_TILE_192x128	Tile 大小为 192 行 x 128 列。
CUBLASLT_MATMUL_TILE_128x192	Tile 大小为 128 行 x 192 列。
CUBLASLT_MATMUL_TILE_128x96	Tile 大小为 128 行 x 96 列。

3.3.16. cublasLtMatmulStages_t

cublasLtMatmulStages_t 是一个枚举类型，用于配置共享内存缓冲区的大小和数量，输入元素在其中分阶段。 分阶段缓冲区的数量定义了内核的流水线深度。

值	描述
CUBLASLT_MATMUL_STAGES_UNDEFINED	Stage 大小未定义。
CUBLASLT_MATMUL_STAGES_16x1	Stage 大小为 16，stage 数量为 1。
CUBLASLT_MATMUL_STAGES_16x2	Stage 大小为 16，stage 数量为 2。
CUBLASLT_MATMUL_STAGES_16x3	Stage 大小为 16，stage 数量为 3。
CUBLASLT_MATMUL_STAGES_16x4	Stage 大小为 16，stage 数量为 4。
CUBLASLT_MATMUL_STAGES_16x5	Stage 大小为 16，stage 数量为 5。
CUBLASLT_MATMUL_STAGES_16x6	Stage 大小为 16，stage 数量为 6。
CUBLASLT_MATMUL_STAGES_32x1	Stage 大小为 32，stage 数量为 1。
CUBLASLT_MATMUL_STAGES_32x2	Stage 大小为 32，stage 数量为 2。
CUBLASLT_MATMUL_STAGES_32x3	Stage 大小为 32，stage 数量为 3。
CUBLASLT_MATMUL_STAGES_32x4	Stage 大小为 32，stage 数量为 4。
CUBLASLT_MATMUL_STAGES_32x5	Stage 大小为 32，stage 数量为 5。
CUBLASLT_MATMUL_STAGES_32x6	Stage 大小为 32，stage 数量为 6。
CUBLASLT_MATMUL_STAGES_64x1	Stage 大小为 64，stage 数量为 1。
CUBLASLT_MATMUL_STAGES_64x2	Stage 大小为 64，stage 数量为 2。
CUBLASLT_MATMUL_STAGES_64x3	Stage 大小为 64，stage 数量为 3。
CUBLASLT_MATMUL_STAGES_64x4	Stage 大小为 64，stage 数量为 4。
CUBLASLT_MATMUL_STAGES_64x5	Stage 大小为 64，stage 数量为 5。
CUBLASLT_MATMUL_STAGES_64x6	Stage 大小为 64，stage 数量为 6。
CUBLASLT_MATMUL_STAGES_128x1	Stage 大小为 128，stage 数量为 1。
CUBLASLT_MATMUL_STAGES_128x2	Stage 大小为 128，stage 数量为 2。
CUBLASLT_MATMUL_STAGES_128x3	Stage 大小为 128，stage 数量为 3。
CUBLASLT_MATMUL_STAGES_128x4	Stage 大小为 128，stage 数量为 4。
CUBLASLT_MATMUL_STAGES_128x5	Stage 大小为 128，stage 数量为 5。
CUBLASLT_MATMUL_STAGES_128x6	Stage 大小为 128，stage 数量为 6。
CUBLASLT_MATMUL_STAGES_32x10	Stage 大小为 32，stage 数量为 10。
CUBLASLT_MATMUL_STAGES_8x4	Stage 大小为 8，stage 数量为 4。
CUBLASLT_MATMUL_STAGES_16x10	Stage 大小为 16，stage 数量为 10。
CUBLASLT_MATMUL_STAGES_8x5	Stage 大小为 8，stage 数量为 5。
CUBLASLT_MATMUL_STAGES_8x3	Stage 大小为 8，stage 数量为 3。
CUBLASLT_MATMUL_STAGES_8xAUTO	Stage 大小为 8，stage 数量自动选择。
CUBLASLT_MATMUL_STAGES_16xAUTO	Stage 大小为 16，stage 数量自动选择。
CUBLASLT_MATMUL_STAGES_32xAUTO	Stage 大小为 32，stage 数量自动选择。
CUBLASLT_MATMUL_STAGES_64xAUTO	Stage 大小为 64，stage 数量自动选择。
CUBLASLT_MATMUL_STAGES_128xAUTO	Stage 大小为 128，stage 数量自动选择。
CUBLASLT_MATMUL_STAGES_256xAUTO	Stage 大小为 256，stage 数量自动选择。

3.3.17. cublasLtNumericalImplFlags_t

cublasLtNumericalImplFlags_t：一组位标志，可以指定这些标志来选择可能影响算法数值行为的实现细节。

以下标志可以使用位 OR 运算符“|”组合。

值	描述
CUBLASLT_NUMERICAL_IMPL_FLAGS_FMA	指定实现基于 [H,F,D]FMA（融合乘加）系列指令。
CUBLASLT_NUMERICAL_IMPL_FLAGS_HMMA	指定实现基于 HMMA（张量运算）系列指令。
CUBLASLT_NUMERICAL_IMPL_FLAGS_IMMA	指定实现基于 IMMA（整数张量运算）系列指令。
CUBLASLT_NUMERICAL_IMPL_FLAGS_DMMA	指定实现基于 DMMA（双精度张量运算）系列指令。
CUBLASLT_NUMERICAL_IMPL_FLAGS_TENSOR_OP_MASK	用于筛选使用任何上述类型的张量运算的实现的掩码。
CUBLASLT_NUMERICAL_IMPL_FLAGS_OP_TYPE_MASK	用于筛选有关所用乘累加指令的实现细节的掩码。
CUBLASLT_NUMERICAL_IMPL_FLAGS_ACCUMULATOR_16F	指定实现方案的内部点积运算使用半精度累加器。
CUBLASLT_NUMERICAL_IMPL_FLAGS_ACCUMULATOR_32F	指定实现方案的内部点积运算使用单精度累加器。
CUBLASLT_NUMERICAL_IMPL_FLAGS_ACCUMULATOR_64F	指定实现方案的内部点积运算使用双精度累加器。
CUBLASLT_NUMERICAL_IMPL_FLAGS_ACCUMULATOR_32I	指定实现方案的内部点积运算使用 32 位有符号整数精度累加器。
CUBLASLT_NUMERICAL_IMPL_FLAGS_ACCUMULATOR_TYPE_MASK	用于过滤关于所用累加器的实现细节的掩码。
CUBLASLT_NUMERICAL_IMPL_FLAGS_INPUT_16F	指定实现方案的内部点积乘加指令使用半精度输入。
CUBLASLT_NUMERICAL_IMPL_FLAGS_INPUT_16BF	指定实现方案的内部点积乘加指令使用 bfloat16 输入。
CUBLASLT_NUMERICAL_IMPL_FLAGS_INPUT_TF32	指定实现方案的内部点积乘加指令使用 TF32 输入。
CUBLASLT_NUMERICAL_IMPL_FLAGS_INPUT_32F	指定实现方案的内部点积乘加指令使用单精度输入。
CUBLASLT_NUMERICAL_IMPL_FLAGS_INPUT_64F	指定实现方案的内部点积乘加指令使用双精度输入。
CUBLASLT_NUMERICAL_IMPL_FLAGS_INPUT_8I	指定实现方案的内部点积乘加指令使用 8 位整数输入。
CUBLASLT_NUMERICAL_IMPL_FLAGS_OP_INPUT_TYPE_MASK	用于过滤关于所用累加器输入的实现细节的掩码。
CUBLASLT_NUMERICAL_IMPL_FLAGS_GAUSSIAN	指定实现方案应用高斯复杂度降低算法来降低复矩阵乘法问题的算术复杂度

3.3.18. cublasLtMatrixLayout_t

cublasLtMatrixLayout_t 是指向一个不透明结构的指针，该结构保存矩阵布局的描述信息。使用 cublasLtMatrixLayoutCreate() 创建描述符的一个实例，并使用 cublasLtMatrixLayoutDestroy() 销毁先前创建的描述符并释放资源。

3.3.19. cublasLtMatrixLayoutAttribute_t

cublasLtMatrixLayoutAttribute_t 是一个描述符结构，包含定义矩阵操作细节的属性。使用 cublasLtMatrixLayoutGetAttribute() 和 cublasLtMatrixLayoutSetAttribute() 获取和设置矩阵布局描述符的属性值。

值	描述	数据类型
CUBLASLT_MATRIX_LAYOUT_TYPE	指定数据精度类型。请参阅 cudaDataType_t。	uint32_t
CUBLASLT_MATRIX_LAYOUT_ORDER	指定矩阵数据的内存顺序。默认值为 CUBLASLT_ORDER_COL。请参阅 cublasLtOrder_t 。	int32_t
CUBLASLT_MATRIX_LAYOUT_ROWS	描述矩阵中的行数。通常只支持可以表示为 int32_t 的值。	uint64_t
CUBLASLT_MATRIX_LAYOUT_COLS	描述矩阵中的列数。通常只支持可以表示为 int32_t 的值。	uint64_t
CUBLASLT_MATRIX_LAYOUT_LD	矩阵的 leading dimension。对于 CUBLASLT_ORDER_COL，这是矩阵列的步长（以元素为单位）。另请参阅 cublasLtOrder_t。 目前仅支持非负值。 必须足够大，以使矩阵内存位置不重叠（例如，在 CUBLASLT_ORDER_COL 的情况下，大于或等于 CUBLASLT_MATRIX_LAYOUT_ROWS）。	int64_t
CUBLASLT_MATRIX_LAYOUT_BATCH_COUNT	要在批处理中执行的 matmul 操作的数量。默认值为 1。另请参阅 cublasLtMatmulAlgoCapAttributes_t 中的 CUBLASLT_ALGO_CAP_STRIDED_BATCH_SUPPORT。	int32_t
CUBLASLT_MATRIX_LAYOUT_STRIDED_BATCH_OFFSET	用于跨步批处理操作的下一个矩阵的步长（以元素为单位）。默认值为 0。当矩阵类型为平面复数 (CUBLASLT_MATRIX_LAYOUT_PLANE_OFFSET != 0) 时，批量步长由 cublasLtMatmul() 以实值子元素的数量来解释。例如，对于 CUDA_C_16F 类型的数据，1024B 的偏移量被编码为步长值 512（因为实部和虚部矩阵的每个元素都是 2B (16bit) 浮点类型）。注意：cublasLtMatrixTransform() 中的一个错误导致它将平面复数矩阵的批量步长解释为好像它是以复数元素数量指定的。因此，当调用 cublasLtMatrixTransform() 时，1024B 的偏移量必须编码为步长值 256（每个复数元素为 4B，实部和虚部值各为 2B）。预计此行为将在下一个主要的 cuBLAS 版本中得到纠正。	int64_t
CUBLASLT_MATRIX_LAYOUT_PLANE_OFFSET	平面复数布局的虚数平面的步长（以字节为单位）。默认值为 0，表示布局是规则的（复数的实部和虚部在内存中为每个元素交错排列）。	int64_t

3.3.20. cublasLtMatrixTransformDesc_t

cublasLtMatrixTransformDesc_t 是指向一个不透明结构的指针，该结构保存矩阵变换操作的描述信息。使用 cublasLtMatrixTransformDescCreate() 创建描述符的一个实例，并使用 cublasLtMatrixTransformDescDestroy() 销毁先前创建的描述符并释放资源。

3.3.21. cublasLtMatrixTransformDescAttributes_t

cublasLtMatrixTransformDescAttributes_t 是一个描述符结构，包含定义矩阵变换操作细节的属性。使用 cublasLtMatrixTransformDescGetAttribute() 和 cublasLtMatrixTransformDescSetAttribute() 设置矩阵变换描述符的属性值。

值	描述	数据类型
CUBLASLT_MATRIX_TRANSFORM_DESC_SCALE_TYPE	缩放类型。输入被转换为缩放类型以进行缩放和求和，然后结果被转换为输出类型以存储在内存中。有关支持的数据类型，请参阅 cudaDataType_t。	int32_t
CUBLASLT_MATRIX_TRANSFORM_DESC_POINTER_MODE	指定标量 alpha 和 beta 是通过引用传递，无论是在主机上还是在设备上。默认值为：CUBLASLT_POINTER_MODE_HOST（即，在主机上）。请参阅 cublasLtPointerMode_t。	int32_t
CUBLASLT_MATRIX_TRANSFORM_DESC_TRANSA	指定应在矩阵 A 上执行的操作类型。默认值为：CUBLAS_OP_N（即，非转置操作）。请参阅 cublasOperation_t。	int32_t
CUBLASLT_MATRIX_TRANSFORM_DESC_TRANSB	指定应在矩阵 B 上执行的操作类型。默认值为：CUBLAS_OP_N（即，非转置操作）。请参阅 cublasOperation_t。	int32_t

3.3.22. cublasLtOrder_t

cublasLtOrder_t 是一种枚举类型，用于指示矩阵的数据顺序。

值	描述
CUBLASLT_ORDER_COL	数据以列优先格式排序。leading dimension 是到内存中下一列开头的步长（以元素为单位）。
CUBLASLT_ORDER_ROW	数据以行优先格式排序。leading dimension 是到内存中下一行开头的步长（以元素为单位）。
CUBLASLT_ORDER_COL32	数据以 32 列的列优先有序平铺方式排序。leading dimension 是到下一组 32 列开头的步长（以元素为单位）。例如，如果矩阵有 33 列和 2 行，则 leading dimension 必须至少为 32 * 2 = 64。
CUBLASLT_ORDER_COL4_4R2_8C	数据以复合平铺方式的列优先有序平铺方式排序，总共 32 列和 8 行。一个平铺由交错的内部平铺组成，内部平铺在交替模式下在 4 个列内，在 4 个偶数行或奇数行内。leading dimension 是到下一个 32 列宽组的列的第一个 32 列 x 8 行平铺的开头的步长（以元素为单位）。例如，如果矩阵有 33 列和 1 行，则 leading dimension 必须至少为 (32 * 8) * 1 = 256。
CUBLASLT_ORDER_COL32_2R_4R4	数据以复合平铺方式的列优先有序平铺方式排序，总共 32 列和 32 行。平铺内的元素偏移量计算为 (((row % 8) / 2 * 4 + row / 8) * 2 + row % 2) * 32 + col。Leading dimension 是到下一个 32 列宽组的列的第一个 32 列 x 32 行平铺的开头的步长（以元素为单位）。例如，如果矩阵有 33 列和 1 行，则其 leading dimension 必须至少为 (32 * 32) * 1 = 1024。

3.3.23. cublasLtPointerMode_t

cublasLtPointerMode_t 是一种枚举类型，用于为缩放因子 alpha 和 beta 设置指针模式。

值	描述
CUBLASLT_POINTER_MODE_HOST = CUBLAS_POINTER_MODE_HOST	与 CUBLAS_POINTER_MODE_HOST 匹配，指针指向单个值的主机内存。
CUBLASLT_POINTER_MODE_DEVICE = CUBLAS_POINTER_MODE_DEVICE	与 CUBLAS_POINTER_MODE_DEVICE 匹配，指针指向单个值的设备内存。
CUBLASLT_POINTER_MODE_DEVICE_VECTOR = 2	指针指向设备内存向量，其长度等于矩阵 D 的行数。
CUBLASLT_POINTER_MODE_ALPHA_DEVICE_VECTOR_BETA_ZERO = 3	alpha 指针指向设备内存向量，其长度等于矩阵 D 的行数，并且 beta 为零。
CUBLASLT_POINTER_MODE_ALPHA_DEVICE_VECTOR_BETA_HOST = 4	alpha 指针指向设备内存向量，其长度等于矩阵 D 的行数，并且 beta 是主机内存中的单个值。

3.3.24. cublasLtPointerModeMask_t

cublasLtPointerModeMask_t 是一种枚举类型，用于定义和查询指针模式功能。

值	描述
CUBLASLT_POINTER_MODE_MASK_HOST = 1	请参阅 cublasLtPointerMode_t 中的 CUBLASLT_POINTER_MODE_HOST。
CUBLASLT_POINTER_MODE_MASK_DEVICE = 2	请参阅 cublasLtPointerMode_t 中的 CUBLASLT_POINTER_MODE_DEVICE。
CUBLASLT_POINTER_MODE_MASK_DEVICE_VECTOR = 4	请参阅 cublasLtPointerMode_t 中的 CUBLASLT_POINTER_MODE_DEVICE_VECTOR。
CUBLASLT_POINTER_MODE_MASK_ALPHA_DEVICE_VECTOR_BETA_ZERO = 8	请参阅 cublasLtPointerMode_t 中的 CUBLASLT_POINTER_MODE_ALPHA_DEVICE_VECTOR_BETA_ZERO。
CUBLASLT_POINTER_MODE_MASK_ALPHA_DEVICE_VECTOR_BETA_HOST = 16	请参阅 cublasLtPointerMode_t 中的 CUBLASLT_POINTER_MODE_ALPHA_DEVICE_VECTOR_BETA_HOST。

3.3.25. cublasLtReductionScheme_t

cublasLtReductionScheme_t 是一种枚举类型，用于指定并行计算的点积部分（即“split - K”）的归约方案。

值	描述
CUBLASLT_REDUCTION_SCHEME_NONE	不应用归约。点积将按一个序列执行。
CUBLASLT_REDUCTION_SCHEME_INPLACE	归约使用输出缓冲区“就地”执行，各部分在输出数据类型中相加。工作区仅用于保证顺序性的计数器。
CUBLASLT_REDUCTION_SCHEME_COMPUTE_TYPE	归约在用户提供的工作区中异地完成。中间结果以计算类型存储在工作区中，并在单独的步骤中归约。
CUBLASLT_REDUCTION_SCHEME_OUTPUT_TYPE	归约在用户提供的工作区中异地完成。中间结果以输出类型存储在工作区中，并在单独的步骤中归约。
CUBLASLT_REDUCTION_SCHEME_MASK	允许所有归约方案。

3.3.26. cublasLtMatmulMatrixScale_t

cublasLtMatmulMatrixScale_t 是一种枚举类型，用于指定定义如何解释缩放因子指针的缩放模式。

值	描述
CUBLASLT_MATMUL_MATRIX_SCALE_SCALAR_32F	缩放因子是应用于整个张量的单精度标量（此模式是 fp8 的默认模式）。当 D 张量使用窄精度数据类型时，这是 CUBLASLT_MATMUL_DESC_D_SCALE_MODE 的唯一有效值。
CUBLASLT_MATMUL_MATRIX_SCALE_VEC16_UE4M3	缩放因子是张量，其中包含专用的缩放因子，该缩放因子存储为 CUDA_R_8F_UE4M3 8 位值，用于相应数据张量最内层维度中的每个 16 元素块。
CUBLASLT_MATMUL_MATRIX_SCALE_VEC32_UE8M0	缩放因子是张量，其中包含专用的缩放因子，该缩放因子存储为 CUDA_R_8F_UE8M0 8 位值，用于相应数据张量最内层维度中的每个 32 元素块。

3.4. cuBLASLt API 参考

3.4.1. cublasLtCreate()

cublasStatus_t
      cublasLtCreate(cublasLtHandle_t *lighthandle)

此函数初始化 cuBLASLt 库并创建一个句柄，该句柄指向保存 cuBLASLt 库上下文的不透明结构。它在主机和设备上分配轻量级硬件资源，并且必须在进行任何其他 cuBLASLt 库调用之前调用。

cuBLASLt 库上下文与当前 CUDA 设备绑定。要在多个设备上使用该库，必须为每个设备创建一个 cuBLASLt 句柄。此外，必须将设备设置为当前设备，然后才能使用绑定到该设备的句柄调用 cuBLASLt 函数。

另请参阅：cuBLAS 上下文。

参数

参数	内存	输入/输出	描述
lightHandle		输出	指向为创建的 cuBLASLt 上下文分配的 cuBLASLt 句柄的指针。

返回值

返回值	描述
CUBLAS_STATUS_SUCCESS	分配成功完成。
CUBLAS_STATUS_NOT_INITIALIZED	cuBLASLt 库未初始化。这通常发生在 未首先调用 cublasLtCreate() 时 cuBLASLt 例程调用的 CUDA Runtime API 中出现错误，或 硬件设置中出现错误。
CUBLAS_STATUS_ALLOC_FAILED	cuBLASLt 库内部的资源分配失败。这通常是由 cudaMalloc() 失败引起的。 更正方法：在函数调用之前，尽可能多地释放先前分配的内存。
CUBLAS_STATUS_INVALID_VALUE	lighthandle 为 NULL

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.2. cublasLtDestroy()

cublasStatus_t
      cublasLtDestroy(cublasLtHandle_t lightHandle)

此函数释放 cuBLASLt 库使用的硬件资源。此函数通常是对 cuBLASLt 库的特定句柄的最后一次调用。由于 cublasLtCreate() 分配了一些内部资源，并且通过调用 cublasLtDestroy() 释放这些资源将隐式调用 cudaDeviceSynchronize()，因此建议尽量减少调用这些函数的次数。

参数:

参数	内存	输入/输出	描述
lightHandle		输入	指向要销毁的 cuBLASLt 句柄的指针。

返回值:

返回值	含义
CUBLAS_STATUS_SUCCESS	cuBLASLt 上下文已成功销毁。
CUBLAS_STATUS_NOT_INITIALIZED	cuBLASLt 库未初始化。
CUBLAS_STATUS_INVALID_VALUE	lightHandle 为 NULL

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.3. cublasLtDisableCpuInstructionsSetMask()

unsigned cublasLtDisableCpuInstructionsSetMask(unsigned mask);

指示 cuBLASLt 库不使用 CPU 指令，这些指令由 mask 中的标志指定。此函数优先于 CUBLASLT_DISABLE_CPU_INSTRUCTIONS_MASK 环境变量。

参数： mask – 使用按位 OR(|) 运算符组合的标志，用于指定不应使用哪些 CPU 指令。

支持的标志

值	描述
0x1	x86-64 AVX512 ISA。

返回值： mask 的先前值。

3.4.4. cublasLtGetCudartVersion()

size_t cublasLtGetCudartVersion(void);

此函数返回 CUDA Runtime 库的版本号。

参数： 无。

返回值：size_t - CUDA Runtime 库的版本号。

3.4.5. cublasLtGetProperty()

cublasStatus_t cublasLtGetProperty(libraryPropertyType type, int *value);

此函数通过将请求的属性写入 value 参数指向的内存位置来返回该属性的值。

参数:

参数	内存	输入/输出	描述
type		输入	类型为 libraryPropertyType，其值从属性中请求。请参阅 libraryPropertyType_t。
value		输出	指向主机内存位置的指针，请求的信息应写入到该位置。

返回值:

返回值	含义
CUBLAS_STATUS_SUCCESS	请求的 libraryPropertyType 信息已成功写入到提供的地址。
CUBLAS_STATUS_INVALID_VALUE	如果 type 输入参数的值无效，或 如果 value 为 NULL

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.6. cublasLtGetStatusName()

const char* cublasLtGetStatusName(cublasStatus_t status);

返回给定状态的字符串表示形式。

参数： cublasStatus_t - 状态。

返回值： const char* - 以 NULL 结尾的字符串。

3.4.7. cublasLtGetStatusString()

const char* cublasLtGetStatusString(cublasStatus_t status);

返回给定状态的描述字符串。

参数： cublasStatus_t - 状态。

返回值： const char* - 以 NULL 结尾的字符串。

3.4.8. cublasLtHeuristicsCacheGetCapacity()

cublasStatus_t cublasLtHeuristicsCacheGetCapacity(size_t* capacity);

返回 启发式缓存 容量。

参数

参数	描述
capacity	指向返回的容量值的指针。

返回值

返回值	描述
CUBLAS_STATUS_SUCCESS	容量已成功写入。
CUBLAS_STATUS_INVALID_VALUE	容量已成功设置。

3.4.9. cublasLtHeuristicsCacheSetCapacity()

cublasStatus_t cublasLtHeuristicsCacheSetCapacity(size_t capacity);

设置 启发式缓存 容量。将容量设置为 0 以禁用启发式缓存。

此函数优先于 CUBLASLT_HEURISTICS_CACHE_CAPACITY 环境变量。

参数

参数	描述
capacity	desirableHeuristicsCacheCapacity

返回值

返回值	描述
CUBLAS_STATUS_SUCCESS	容量已成功设置。

期望的启发式缓存容量。

size_t cublasLtGetVersion(void);

3.4.10. cublasLtGetVersion()

参数： 无。

此函数返回 cuBLASLt 库的版本号。

返回值：size_t - cuBLASLt 库的版本号。

cublasStatus_t cublasLtLoggerSetCallback(cublasLtLoggerCallback_t callback);

3.4.11. cublasLtLoggerSetCallback()

参数:

参数	内存	输入/输出	描述
实验性：此函数设置日志记录回调函数。		输入	callback

返回值:

返回值	描述
CUBLAS_STATUS_SUCCESS	指向回调函数的指针。请参阅 cublasLtLoggerCallback_t。

如果回调函数已成功设置。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

cublasStatus_t cublasLtLoggerSetFile(FILE* file);

3.4.12. cublasLtLoggerSetFile()

参数:

参数	内存	输入/输出	描述
实验性：此函数设置日志记录输出文件。注意：一旦使用此函数调用注册，除非再次调用该函数以切换到不同的文件句柄，否则提供的文件句柄不得关闭。		输入	file

返回值:

返回值	描述
CUBLAS_STATUS_SUCCESS	指向打开文件的指针。文件应具有写入权限。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

如果日志记录文件已成功设置。

cublasStatus_t cublasLtLoggerOpenFile(const char* logFile);

3.4.13. cublasLtLoggerOpenFile()

参数:

参数	内存	输入/输出	描述
实验性：此函数在给定路径中打开日志记录输出文件。		输入	logFile

返回值:

返回值	描述
CUBLAS_STATUS_SUCCESS	日志记录输出文件的路径。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

如果日志记录文件已成功打开。

cublasStatus_t cublasLtLoggerSetLevel(int level);

3.4.14. cublasLtLoggerSetLevel()

参数:

参数	内存	输入/输出	描述
实验性：此函数设置日志记录级别的value。		输入	level

返回值:

返回值	描述
CUBLAS_STATUS_INVALID_VALUE	日志记录级别的 Value。请参阅 cuBLASLt 日志记录。
CUBLAS_STATUS_SUCCESS	如果该值不是有效的日志记录级别。请参阅 cuBLASLt 日志记录。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

如果日志记录级别已成功设置。

cublasStatus_t cublasLtLoggerSetMask(int mask);

3.4.15. cublasLtLoggerSetMask()

参数:

参数	内存	输入/输出	描述
实验性：此函数设置日志记录掩码的值。		输入	mask

返回值:

返回值	描述
CUBLAS_STATUS_SUCCESS	日志记录掩码的值。请参阅 cuBLASLt 日志记录。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

如果日志记录掩码已成功设置。

cublasStatus_t cublasLtLoggerForceDisable();

3.4.16. cublasLtLoggerForceDisable()

返回值:

返回值	描述
CUBLAS_STATUS_SUCCESS	实验性：此函数禁用整个运行的日志记录。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

如果日志记录已成功禁用。

cublasStatus_t cublasLtMatmul(
      cublasLtHandle_t               lightHandle,
      cublasLtMatmulDesc_t           computeDesc,
      const void                    *alpha,
      const void                    *A,
      cublasLtMatrixLayout_t         Adesc,
      const void                    *B,
      cublasLtMatrixLayout_t         Bdesc,
      const void                    *beta,
      const void                    *C,
      cublasLtMatrixLayout_t         Cdesc,
      void                          *D,
      cublasLtMatrixLayout_t         Ddesc,
      const cublasLtMatmulAlgo_t    *algo,
      void                          *workspace,
      size_t                         workspaceSizeInBytes,
      cudaStream_t                   stream);

3.4.17. cublasLtMatmul()

此函数计算矩阵 A 和 B 的矩阵乘法，以生成输出矩阵 D，根据以下操作

D = alpha*(A*B) + beta*(C),

注意

其中 A、B 和 C 是输入矩阵，alpha 和 beta 是输入标量。

此函数同时支持就地矩阵乘法 (C == D 和 Cdesc == Ddesc) 和异地矩阵乘法 (C != D，两个矩阵必须具有相同的数据类型、行数、列数、批大小和内存顺序)。在异地情况下，C 的 leading dimension 可以与 D 的 leading dimension 不同。具体来说，C 的 leading dimension 可以为 0 以实现行或列广播。如果省略 Cdesc，则此函数假定它等于 Ddesc。

workspace 指针必须至少对齐到 256 字节的倍数。workspaceSizeInBytes 上的建议与 cublasSetWorkspace() 部分中提到的相同。

支持的数据类型

cublasLtMatmul() 支持以下 computeType、scaleType、Atype/Btype 和 Ctype。脚注可以在本节末尾找到。

computeType	表 1. 当 A、B、C 和 D 是规则的列优先或行优先矩阵时	Atype/Btype	Ctype	scaleType
CUBLAS_COMPUTE_16F 或 CUBLAS_COMPUTE_16F_PEDANTIC	CUDA_R_16F	CUDA_R_16F	CUDA_R_16F	偏置类型 8
CUBLAS_COMPUTE_32I 或 CUBLAS_COMPUTE_32I_PEDANTIC	CUDA_R_32I	CUDA_R_8I	CUDA_R_32I	CUDA_R_16F 8
	CUDA_R_32F	CUDA_R_8I	CUDA_R_8I	CUDA_R_16F 8
CUBLAS_COMPUTE_32F 或 CUBLAS_COMPUTE_32F_PEDANTIC	CUDA_R_32F	CUDA_R_16BF	CUDA_R_16BF	不支持 Epilogue。
		CUDA_R_16F	CUDA_R_16F	CUDA_R_16BF 8
		CUDA_R_8I	CUDA_R_32F	CUDA_R_16F 8
		CUDA_R_16BF	CUDA_R_32F	CUDA_R_16F 8
		CUDA_R_16F	CUDA_R_32F	CUDA_R_32F 8
		CUDA_R_32F	CUDA_R_32F	CUDA_R_32F 8
	CUDA_C_32F 9	CUDA_C_8I 9	CUDA_C_32F 9	CUDA_R_16F 8
		CUDA_C_32F 9	CUDA_C_32F 9
CUBLAS_COMPUTE_32F_FAST_16F 或 CUBLAS_COMPUTE_32F_FAST_16BF 或 CUBLAS_COMPUTE_32F_FAST_TF32	CUDA_R_32F	CUDA_R_32F	CUDA_R_32F	CUDA_R_32F 8
	CUDA_C_32F 9	CUDA_C_32F 9	CUDA_C_32F 9	CUDA_R_16F 8
CUBLAS_COMPUTE_64F 或 CUBLAS_COMPUTE_64F_PEDANTIC	CUDA_R_64F	CUDA_R_64F	CUDA_R_64F	CUDA_R_64F 8
	CUDA_C_64F 9	CUDA_C_64F 9	CUDA_C_64F 9	CUDA_R_16F 8

要使用 IMMA 内核，必须满足以下要求集之一，首选第一种。

1. 使用常规数据排序

   • 所有矩阵指针必须是 4 字节对齐的。为了获得更好的性能，此条件应保持为 16 而不是 4。

   • 矩阵 A、B、C 的前导维度必须是 4 的倍数。

   • 仅支持 “TN” 格式 - A 必须转置，B 必须是非转置。

   • 指针模式可以是 CUBLASLT_POINTER_MODE_HOST、CUBLASLT_POINTER_MODE_DEVICE 或 CUBLASLT_POINTER_MODE_ALPHA_DEVICE_VECTOR_BETA_HOST。在后一种模式下，内核支持 CUBLASLT_MATMUL_DESC_ALPHA_VECTOR_BATCH_STRIDE 属性。

   • 维度 m 和 k 必须是 4 的倍数。

2. 在 Ampere（计算能力 8.0）或 Turing（计算能力 7.5）架构（但不包括 Hopper，计算能力 9.0 或更高版本）上使用 IMMA 特定的数据排序 - 矩阵 A、C、D 使用 CUBLASLT_ORDER_COL32`，矩阵 B 使用 CUBLASLT_ORDER_COL4_4R2_8C（在 Turing 或 Ampere 架构上）或 CUBLASLT_ORDER_COL32_2R_4R4（在 Ampere 架构上）

   • 矩阵 A、B、C 的前导维度必须满足特定于内存排序的条件（请参阅 cublasLtOrder_t）。

   • Matmul 描述符必须在矩阵 B 上指定 CUBLAS_OP_T，在矩阵 A 和 C 上指定 CUBLAS_OP_N（默认）。

   • 如果使用 scaleType CUDA_R_32I，则 alpha 和 beta 唯一支持的值为 0 或 1。

   • 指针模式可以是 CUBLASLT_POINTER_MODE_HOST、CUBLASLT_POINTER_MODE_DEVICE、CUBLASLT_POINTER_MODE_DEVICE_VECTOR 或 CUBLASLT_POINTER_MODE_ALPHA_DEVICE_VECTOR_BETA_ZERO。这些内核不支持 CUBLASLT_MATMUL_DESC_ALPHA_VECTOR_BATCH_STRIDE。

   • 仅支持 “NT” 格式 - A 必须转置，B 必须是非转置。

表 2. 当 A、B、C 和 D 使用 IMMA 布局时

computeType	表 1. 当 A、B、C 和 D 是规则的列优先或行优先矩阵时	Atype/Btype	Ctype	Bias 类型
CUBLAS_COMPUTE_32I 或 CUBLAS_COMPUTE_32I_PEDANTIC	CUDA_R_32I	CUDA_R_8I	CUDA_R_32I	不支持非默认尾声。
	CUDA_R_32F	CUDA_R_8I	CUDA_R_8I	CUDA_R_32F

要使用张量或块缩放的 FP8 内核，必须满足以下要求集

• 所有矩阵维度都必须满足 Tensor Core 使用 中列出的最佳要求（即，指针和矩阵维度必须支持 16 字节对齐）。

• 在 Ada（计算能力 8.9）、Hopper（计算能力 9.0）和 Blackwell GeForce（计算能力 12.x）GPU 上，缩放模式必须为 CUBLASLT_MATMUL_MATRIX_SCALE_SCALAR_32F。

• 在 Ada（计算能力 8.9）、Hopper（计算能力 9.0）和 Blackwell GeForce（计算能力 12.x）GPU 上，A 必须转置，B 必须是非转置（“TN” 格式）。

• 计算类型必须为 CUBLAS_COMPUTE_32F。

• 缩放类型必须为 CUDA_R_32F。

使用 FP8 内核时，请参见下表

表 3. 当 A、B、C 和 D 使用 FP8 布局时

AType	BType	CType	DType	Bias 类型
CUDA_R_8F_E4M3	CUDA_R_8F_E4M3	CUDA_R_16BF	CUDA_R_16BF	CUDA_R_16BF 8
			CUDA_R_8F_E4M3	CUDA_R_16BF 8
		CUDA_R_16F	CUDA_R_16F	CUDA_R_16F 8
			CUDA_R_8F_E4M3	CUDA_R_16F 8
		CUDA_R_32F	CUDA_R_32F	CUDA_R_16BF 8
	CUDA_R_8F_E5M2	CUDA_R_16BF	CUDA_R_16BF	CUDA_R_16BF 8
			CUDA_R_8F_E4M3	CUDA_R_16BF 8
			CUDA_R_8F_E5M2	CUDA_R_16BF 8
		CUDA_R_16F	CUDA_R_16F	CUDA_R_16F 8
			CUDA_R_8F_E4M3	CUDA_R_16F 8
			CUDA_R_8F_E5M2	CUDA_R_16F 8
		CUDA_R_32F	CUDA_R_32F	CUDA_R_16BF 8
CUDA_R_8F_E5M2	CUDA_R_8F_E4M3	CUDA_R_16BF	CUDA_R_16BF	CUDA_R_16BF 8
			CUDA_R_8F_E4M3	CUDA_R_16BF 8
			CUDA_R_8F_E5M2	CUDA_R_16BF 8
		CUDA_R_16F	CUDA_R_16F	CUDA_R_16F 8
			CUDA_R_8F_E4M3	CUDA_R_16F 8
			CUDA_R_8F_E5M2	CUDA_R_16F 8
		CUDA_R_32F	CUDA_R_32F	CUDA_R_16BF 8

要使用 Blackwell GPU（计算能力 10.x）上可用的块缩放 FP4 内核，必须满足以下要求集

• 所有矩阵维度都必须满足 Tensor Core 使用 中列出的最佳要求（即，指针和矩阵维度必须支持 16 字节对齐）。

• 缩放模式必须为 CUBLASLT_MATMUL_MATRIX_SCALE_VEC16_UE4M3

• A 必须转置，B 必须是非转置（“TN” 格式）

• 计算类型必须为 CUBLAS_COMPUTE_32F。

• 缩放类型必须为 CUDA_R_32F。

表 4. 当 A、B、C 和 D 使用 FP4 布局时

AType	BType	CType	DType	Bias 类型
CUDA_R_4F_E2M1	CUDA_R_4F_E2M1	CUDA_R_16BF	CUDA_R_16BF	CUDA_R_16BF 8
			CUDA_R_4F_E2M1	CUDA_R_16BF 8
		CUDA_R_16F	CUDA_R_16F	CUDA_R_16F 8
			CUDA_R_4F_E2M1	CUDA_R_16F 8
		CUDA_R_32F	CUDA_R_32F	CUDA_R_16BF 8

最后，当 A、B、C、D 是平面复矩阵时（CUBLASLT_MATRIX_LAYOUT_PLANE_OFFSET != 0，请参阅 cublasLtMatrixLayoutAttribute_t），请参见下表，以利用混合精度张量核心加速。

表 5. 当 A、B、C 和 D 是平面复矩阵时

computeType	表 1. 当 A、B、C 和 D 是规则的列优先或行优先矩阵时	Atype/Btype	Ctype
CUBLAS_COMPUTE_32F	CUDA_C_32F	CUDA_C_16F 9	CUDA_C_16F 9
			CUDA_C_32F 9
		CUDA_C_16BF 9	CUDA_C_16BF 9
			CUDA_C_32F 9

注释

8(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33)

当 D 矩阵内存顺序定义为 CUBLASLT_ORDER_ROW 时，不支持 ReLU、dReLu、GELU、dGELU 和 Bias 尾声模式（请参阅 cublasLtMatmulDescAttributes_t 中的 CUBLASLT_MATMUL_DESC_EPILOGUE）。为了在使用偏置向量时获得最佳性能，请指定零 beta 并将指针模式设置为 CUBLASLT_POINTER_MODE_HOST。

9(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17)

除非 A、B、C 和 D 矩阵都使用 CUBLAS_ORDER_ROW 排序，否则不支持将 CUBLAS_ORDER_ROW 与 CUBLAS_OP_C（Hermitian 运算符）一起使用。

参数

参数	内存	输入/输出	描述
lightHandle		输入	指向为 cuBLASLt 上下文分配的 cuBLASLt 句柄的指针。请参阅 cublasLtHandle_t。
computeDesc		输入	先前创建的类型为 cublasLtMatmulDesc_t 的矩阵乘法描述符的句柄。
alpha, beta	设备或主机	输入	指向乘法中使用的标量的指针。
A、B 和 C	设备	输入	指向与相应描述符 Adesc、Bdesc 和 Cdesc 关联的 GPU 内存的指针。
Adesc、Bdesc 和 Cdesc		输入	指向先前创建的类型为 cublasLtMatrixLayout_t 的描述符的句柄。
D	设备	输出	指向与描述符 Ddesc 关联的 GPU 内存的指针。
Ddesc		输入	指向先前创建的类型为 cublasLtMatrixLayout_t 的描述符的句柄。
algo		输入	要使用的矩阵乘法算法的句柄。请参阅 cublasLtMatmulAlgo_t。当为 NULL 时，将执行具有默认搜索首选项的隐式启发式查询，以确定要使用的实际算法。
workspace	设备		指向在 GPU 内存中分配的工作区缓冲区的指针。必须是 256B 对齐的（即，地址的最低 8 位必须为 0）。
workspaceSizeInBytes		输入	工作区的大小。
stream	主机	输入	所有 GPU 工作将提交到的 CUDA 流。

返回值

返回值	描述
CUBLAS_STATUS_NOT_INITIALIZED	如果 cuBLASLt 句柄尚未初始化。
CUBLAS_STATUS_INVALID_VALUE	如果参数意外地为 NULL、冲突或处于不可能的配置中。例如，当 workspaceSizeInBytes 小于配置的算法所需的工作区时。
CUBLAS_STATUS_NOT_SUPPORTED	如果所选设备上的当前实现不支持配置的操作。
CUBLAS_STATUS_ARCH_MISMATCH	如果配置的操作无法使用所选设备运行。
CUBLAS_STATUS_EXECUTION_FAILED	如果 CUDA 报告了来自设备的执行错误。
CUBLAS_STATUS_SUCCESS	如果操作成功完成。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.18. cublasLtMatmulAlgoCapGetAttribute()

cublasStatus_t cublasLtMatmulAlgoCapGetAttribute(
      const cublasLtMatmulAlgo_t *algo,
      cublasLtMatmulAlgoCapAttributes_t attr,
      void *buf,
      size_t sizeInBytes,
      size_t *sizeWritten);

此函数返回已初始化的 cublasLtMatmulAlgo_t 描述符结构的查询能力属性的值。能力属性值从枚举类型 cublasLtMatmulAlgoCapAttributes_t 中检索。

例如，要获取支持的 Tile ID 列表

cublasLtMatmulTile_t tiles[CUBLASLT_MATMUL_TILE_END];
size_t num_tiles, size_written;
if (cublasLtMatmulAlgoCapGetAttribute(algo, CUBLASLT_ALGO_CAP_TILE_IDS, tiles, sizeof(tiles), &size_written) == CUBLAS_STATUS_SUCCESS) {
  num_tiles = size_written / sizeof(tiles[0]);}

参数:

参数	内存	输入/输出	描述
algo		输入	指向先前创建的、保存矩阵乘法算法描述符的不透明结构的指针。请参阅 cublasLtMatmulAlgo_t。
attr		输入	要由此函数检索其值的能力属性。请参阅 cublasLtMatmulAlgoCapAttributes_t。
buf		输出	此函数返回的属性值。
sizeInBytes		输入	用于验证的 buf 缓冲区的大小（以字节为单位）。
sizeWritten		输出	仅当返回值是 CUBLAS_STATUS_SUCCESS 时有效。如果 sizeInBytes 为非零值：则 sizeWritten 是实际写入的字节数；如果 sizeInBytes 为 0：则 sizeWritten 是写入完整内容所需的字节数。

返回值:

返回值	描述
CUBLAS_STATUS_INVALID_VALUE	如果 sizeInBytes 为 0 且 sizeWritten 为 NULL，或者 如果 sizeInBytes 为非零值且 buf 为 NULL，或者 如果 sizeInBytes 与所选属性的内部存储大小不匹配
CUBLAS_STATUS_SUCCESS	如果属性值已成功写入用户内存。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.19. cublasLtMatmulAlgoCheck()

cublasStatus_t cublasLtMatmulAlgoCheck(
      cublasLtHandle_t lightHandle,
      cublasLtMatmulDesc_t operationDesc,
      cublasLtMatrixLayout_t Adesc,
      cublasLtMatrixLayout_t Bdesc,
      cublasLtMatrixLayout_t Cdesc,
      cublasLtMatrixLayout_t Ddesc,
      const cublasLtMatmulAlgo_t *algo,
      cublasLtMatmulHeuristicResult_t *result);

此函数对矩阵乘法算法描述符执行正确性检查，用于矩阵乘法运算 cublasLtMatmul() 函数，使用给定的输入矩阵 A、B 和 C 以及输出矩阵 D。它检查描述符是否在当前设备上受支持，并返回包含所需工作区和计算的波计数的结果。

注意

CUBLAS_STATUS_SUCCESS 不完全保证算法将运行。例如，如果缓冲区未正确对齐，算法将失败。但是，如果 cublasLtMatmulAlgoCheck() 失败，则算法将不会运行。

参数:

参数	内存	输入/输出	描述
lightHandle		输入	指向为 cuBLASLt 上下文分配的 cuBLASLt 句柄的指针。请参阅 cublasLtHandle_t。
operationDesc		输入	先前创建的类型为 cublasLtMatmulDesc_t 的矩阵乘法描述符的句柄。
Adesc、Bdesc、Cdesc 和 Ddesc		输入	指向先前创建的类型为 cublasLtMatrixLayout_t 的矩阵布局描述符的句柄。
algo		输入	指定应使用哪个矩阵乘法算法的描述符。请参阅 cublasLtMatmulAlgo_t。可能指向 result->algo。
result		输出	指向保存此函数返回的结果的结构的指针。结果包括所需的工作区和计算的波计数。algo 字段永远不会更新。请参阅 cublasLtMatmulHeuristicResult_t。

返回值:

返回值	描述
CUBLAS_STATUS_INVALID_VALUE	如果矩阵布局描述符或操作描述符与 algo 描述符不匹配。
CUBLAS_STATUS_NOT_SUPPORTED	如果给定设备上当前不支持 algo 配置或数据类型组合。
CUBLAS_STATUS_ARCH_MISMATCH	如果配置的 algo 无法使用所选设备运行。
CUBLAS_STATUS_SUCCESS	如果检查成功。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.20. cublasLtMatmulAlgoConfigGetAttribute()

cublasStatus_t cublasLtMatmulAlgoConfigGetAttribute(
      const cublasLtMatmulAlgo_t *algo,
      cublasLtMatmulAlgoConfigAttributes_t attr,
      void *buf,
      size_t sizeInBytes,
      size_t *sizeWritten);

此函数返回已初始化的 cublasLtMatmulAlgo_t 描述符的查询配置属性的值。配置属性值从枚举类型 cublasLtMatmulAlgoConfigAttributes_t 中检索。

参数:

参数	内存	输入/输出	描述
algo		输入	指向先前创建的、保存矩阵乘法算法描述符的不透明结构的指针。请参阅 cublasLtMatmulAlgo_t。
attr		输入	要由此函数检索其值的配置属性。请参阅 cublasLtMatmulAlgoConfigAttributes_t。
buf		输出	此函数返回的属性值。
sizeInBytes		输入	用于验证的 buf 缓冲区的大小（以字节为单位）。
sizeWritten		输出	仅当返回值是 CUBLAS_STATUS_SUCCESS 时有效。如果 sizeInBytes 为非零值：则 sizeWritten 是实际写入的字节数；如果 sizeInBytes 为 0：则 sizeWritten 是写入完整内容所需的字节数。

返回值:

返回值	描述
CUBLAS_STATUS_INVALID_VALUE	如果 sizeInBytes 为 0 且 sizeWritten 为 NULL，或者 如果 sizeInBytes 为非零值且 buf 为 NULL，或者 如果 sizeInBytes 与所选属性的内部存储大小不匹配
CUBLAS_STATUS_SUCCESS	如果属性值已成功写入用户内存。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.21. cublasLtMatmulAlgoConfigSetAttribute()

cublasStatus_t cublasLtMatmulAlgoConfigSetAttribute(
      cublasLtMatmulAlgo_t *algo,
      cublasLtMatmulAlgoConfigAttributes_t attr,
      const void *buf,
      size_t sizeInBytes);

此函数为已初始化的 cublasLtMatmulAlgo_t 描述符设置指定的配置属性的值。配置属性是类型 cublasLtMatmulAlgoConfigAttributes_t 的枚举数。

参数:

参数	内存	输入/输出	描述
algo		输入	指向先前创建的、保存矩阵乘法算法描述符的不透明结构的指针。请参阅 cublasLtMatmulAlgo_t。
attr		输入	要由此函数设置其值的配置属性。请参阅 cublasLtMatmulAlgoConfigAttributes_t。
buf		输入	应将配置属性设置为的值。
sizeInBytes		输入	用于验证的 buf 缓冲区的大小（以字节为单位）。

返回值:

返回值	描述
CUBLAS_STATUS_INVALID_VALUE	如果 buf 为 NULL 或 sizeInBytes 与所选属性的内部存储大小不匹配。
CUBLAS_STATUS_SUCCESS	如果属性已成功设置。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.22. cublasLtMatmulAlgoGetHeuristic()

cublasStatus_t cublasLtMatmulAlgoGetHeuristic(
      cublasLtHandle_t lightHandle,
      cublasLtMatmulDesc_t operationDesc,
      cublasLtMatrixLayout_t Adesc,
      cublasLtMatrixLayout_t Bdesc,
      cublasLtMatrixLayout_t Cdesc,
      cublasLtMatrixLayout_t Ddesc,
      cublasLtMatmulPreference_t preference,
      int requestedAlgoCount,
      cublasLtMatmulHeuristicResult_t heuristicResultsArray[],
      int *returnAlgoCount);

此函数检索矩阵乘法运算 cublasLtMatmul() 函数的可能算法，使用给定的输入矩阵 A、B 和 C 以及输出矩阵 D。输出按估计计算时间的升序放置在 heuristicResultsArray[] 中。

参数:

参数	内存	输入/输出	描述
lightHandle		输入	指向为 cuBLASLt 上下文分配的 cuBLASLt 句柄的指针。请参阅 cublasLtHandle_t。
operationDesc		输入	先前创建的类型为 cublasLtMatmulDesc_t 的矩阵乘法描述符的句柄。
Adesc、Bdesc、Cdesc 和 Ddesc		输入	指向先前创建的类型为 cublasLtMatrixLayout_t 的矩阵布局描述符的句柄。
preference		输入	指向保存启发式搜索首选项描述符的结构的指针。请参阅 cublasLtMatmulPreference_t。
requestedAlgoCount		输入	heuristicResultsArray 的大小（以元素为单位）。这是请求返回的最大算法数。
heuristicResultsArray[]		输出	包含算法启发式和关联运行时特征的数组，由此函数返回，并按估计计算时间的升序排列。
returnAlgoCount		输出	由此函数返回的算法数。这是写入的 heuristicResultsArray 元素的数量。

返回值:

返回值	描述
CUBLAS_STATUS_INVALID_VALUE	如果 requestedAlgoCount 小于或等于零。
CUBLAS_STATUS_NOT_SUPPORTED	如果当前配置没有可用的启发式函数。
CUBLAS_STATUS_SUCCESS	如果查询成功。检查 heuristicResultsArray[0 to (returnAlgoCount -1)].state 以获取结果的状态。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

注意

此函数可能会使用 CUDA Driver API 加载某些内核，当没有可用的 GPU 内存时，可能会失败。在运行 cublasLtMatmulAlgoGetHeuristic() 之前，请勿分配整个 VRAM。

3.4.23. cublasLtMatmulAlgoGetIds()

cublasStatus_t cublasLtMatmulAlgoGetIds(
      cublasLtHandle_t lightHandle,
      cublasComputeType_t computeType,
      cudaDataType_t scaleType,
      cudaDataType_t Atype,
      cudaDataType_t Btype,
      cudaDataType_t Ctype,
      cudaDataType_t Dtype,
      int requestedAlgoCount,
      int algoIdsArray[],
      int *returnAlgoCount);

此函数检索所有有效矩阵乘法算法的 ID，并且对于给定的输入矩阵 A、B 和 C 以及输出矩阵 D 的类型，这些算法可能由 cublasLtMatmul() 函数运行。

注意

ID 以无特定顺序返回。为确保最佳算法包含在列表中，请使 requestedAlgoCount 足够大以接收完整列表。如果 returnAlgoCount < requestedAlgoCount，则保证列表完整。

参数:

参数	内存	输入/输出	描述
lightHandle		输入	指向为 cuBLASLt 上下文分配的 cuBLASLt 句柄的指针。请参阅 cublasLtHandle_t。
computeType、scaleType、Atype、Btype、Ctype 和 Dtype		输入	计算类型、缩放因子和操作数矩阵的数据类型。请参阅 cudaDataType_t。
requestedAlgoCount		输入	请求的算法数。必须 > 0。
algoIdsArray[]		输出	包含由此函数返回的算法 ID 的数组。
returnAlgoCount		输出	由此函数实际返回的算法数。

返回值:

返回值	描述
CUBLAS_STATUS_INVALID_VALUE	如果 requestedAlgoCount 小于或等于零。
CUBLAS_STATUS_SUCCESS	如果查询成功。检查 returnAlgoCount 以获取可用的实际 ID 数。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.24. cublasLtMatmulAlgoInit()

cublasStatus_t cublasLtMatmulAlgoInit(
      cublasLtHandle_t lightHandle,
      cublasComputeType_t computeType,
      cudaDataType_t scaleType,
      cudaDataType_t Atype,
      cudaDataType_t Btype,
      cudaDataType_t Ctype,
      cudaDataType_t Dtype,
      int algoId,
      cublasLtMatmulAlgo_t *algo);

此函数为 cublasLtMatmul() 初始化矩阵乘法算法结构，用于指定的矩阵乘法算法以及输入矩阵 A、B 和 C 以及输出矩阵 D。

参数:

参数	内存	输入/输出	描述
lightHandle		输入	指向为 cuBLASLt 上下文分配的 cuBLASLt 句柄的指针。请参阅 cublasLtHandle_t。
computeType		输入	计算类型。请参阅 cublasLtMatmulDescAttributes_t 的 CUBLASLT_MATMUL_DESC_COMPUTE_TYPE。
表 1. 当 A、B、C 和 D 是规则的列优先或行优先矩阵时		输入	缩放类型。请参阅 cublasLtMatmulDescAttributes_t 的 CUBLASLT_MATMUL_DESC_SCALE_TYPE。通常与 computeType 相同。
Atype、Btype、Ctype 和 Dtype		输入	输入和输出矩阵的数据类型精度。请参阅 cudaDataType_t 。
algoId		输入	指定要初始化的算法。应为 cublasLtMatmulAlgoGetIds() 函数返回的有效 algoId。
algo		输入	指向要初始化的不透明结构的指针。请参阅 cublasLtMatmulAlgo_t。

返回值:

返回值	描述
CUBLAS_STATUS_INVALID_VALUE	如果 algo 为 NULL 或 algoId 超出识别范围。
CUBLAS_STATUS_NOT_SUPPORTED	如果给定的数据类型组合不支持 algoId。
CUBLAS_STATUS_SUCCESS	如果结构已成功初始化。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.25. cublasLtMatmulDescCreate()

cublasStatus_t cublasLtMatmulDescCreate( cublasLtMatmulDesc_t *matmulDesc,
                                         cublasComputeType_t computeType,
                                         cudaDataType_t scaleType);

此函数通过分配保存其不透明结构所需的内存来创建矩阵乘法描述符。

参数:

参数	内存	输入/输出	描述
matmulDesc		输出	指向保存由此函数创建的矩阵乘法描述符的结构的指针。请参阅 cublasLtMatmulDesc_t。
computeType		输入	指定此函数创建的矩阵乘法描述符的数据精度的枚举数。请参阅 cublasComputeType_t。
表 1. 当 A、B、C 和 D 是规则的列优先或行优先矩阵时		输入	指定此函数创建的矩阵变换描述符的数据精度的枚举数。请参阅 cudaDataType。

返回值:

返回值	描述
CUBLAS_STATUS_ALLOC_FAILED	如果内存无法分配。
CUBLAS_STATUS_SUCCESS	如果描述符已成功创建。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.26. cublasLtMatmulDescInit()

cublasStatus_t cublasLtMatmulDescInit( cublasLtMatmulDesc_t matmulDesc,
                                       cublasComputeType_t computeType,
                                       cudaDataType_t scaleType);

此函数在先前分配的矩阵乘法描述符中初始化一个。

参数:

参数	内存	输入/输出	描述
matmulDesc		输出	指向保存由此函数初始化的矩阵乘法描述符的结构的指针。请参阅 cublasLtMatmulDesc_t。
computeType		输入	指定此函数初始化的矩阵乘法描述符的数据精度的枚举数。请参阅 cublasComputeType_t。
表 1. 当 A、B、C 和 D 是规则的列优先或行优先矩阵时		输入	指定此函数初始化的矩阵变换描述符的数据精度的枚举数。请参阅 cudaDataType。

返回值:

返回值	描述
CUBLAS_STATUS_ALLOC_FAILED	如果内存无法分配。
CUBLAS_STATUS_SUCCESS	如果描述符已成功创建。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.27. cublasLtMatmulDescDestroy()

cublasStatus_t cublasLtMatmulDescDestroy(
      cublasLtMatmulDesc_t matmulDesc);

此函数销毁先前创建的矩阵乘法描述符对象。

参数:

参数	内存	输入/输出	描述
matmulDesc		输入	指向保存应由此函数销毁的矩阵乘法描述符的结构的指针。请参阅 cublasLtMatmulDesc_t。

返回值:

返回值	描述
CUBLAS_STATUS_SUCCESS	如果操作成功。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.28. cublasLtMatmulDescGetAttribute()

cublasStatus_t cublasLtMatmulDescGetAttribute(
      cublasLtMatmulDesc_t matmulDesc,
      cublasLtMatmulDescAttributes_t attr,
      void *buf,
      size_t sizeInBytes,
      size_t *sizeWritten);

此函数返回属于先前创建的矩阵乘法描述符的查询属性的值。

参数:

参数	内存	输入/输出	描述
matmulDesc		输入	指向先前创建的、保存由此函数查询的矩阵乘法描述符的结构的指针。请参阅 cublasLtMatmulDesc_t。
attr		输入	要由此函数检索的属性。请参阅 cublasLtMatmulDescAttributes_t。
buf		输出	包含由此函数检索的属性值的内存地址。
sizeInBytes		输入	用于验证的 buf 缓冲区的大小（以字节为单位）。
sizeWritten		输出	仅当返回值是 CUBLAS_STATUS_SUCCESS 时有效。如果 sizeInBytes 为非零值：则 sizeWritten 是实际写入的字节数；如果 sizeInBytes 为 0：则 sizeWritten 是写入完整内容所需的字节数。

返回值:

返回值	描述
CUBLAS_STATUS_INVALID_VALUE	如果 sizeInBytes 为 0 且 sizeWritten 为 NULL，或者 如果 sizeInBytes 为非零值且 buf 为 NULL，或者 sizeInBytes 与所选属性的内部存储大小不匹配
CUBLAS_STATUS_SUCCESS	如果属性值已成功写入用户内存。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.29. cublasLtMatmulDescSetAttribute()

cublasStatus_t cublasLtMatmulDescSetAttribute(
      cublasLtMatmulDesc_t matmulDesc,
      cublasLtMatmulDescAttributes_t attr,
      const void *buf,
      size_t sizeInBytes);

此函数设置属于先前创建的矩阵乘法描述符的指定属性的值。

参数:

参数	内存	输入/输出	描述
matmulDesc		输入	指向先前创建的、保存由此函数查询的矩阵乘法描述符的结构的指针。请参阅 cublasLtMatmulDesc_t。
attr		输入	要由此函数设置的属性。请参阅 cublasLtMatmulDescAttributes_t。
buf		输入	应将指定属性设置为的值。
sizeInBytes		输入	用于验证的 buf 缓冲区的大小（以字节为单位）。

返回值:

返回值	描述
CUBLAS_STATUS_INVALID_VALUE	如果 buf 为 NULL 或 sizeInBytes 与所选属性的内部存储大小不匹配。
CUBLAS_STATUS_SUCCESS	如果属性已成功设置。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.30. cublasLtMatmulPreferenceCreate()

cublasStatus_t cublasLtMatmulPreferenceCreate(
      cublasLtMatmulPreference_t *pref);

此函数通过分配保存其不透明结构所需的内存来创建矩阵乘法启发式搜索首选项描述符。

参数:

参数	内存	输入/输出	描述
pref		输出	指向保存由此函数创建的矩阵乘法首选项描述符的结构的指针。请参阅 cublasLtMatrixLayout_t。

返回值:

返回值	描述
CUBLAS_STATUS_ALLOC_FAILED	如果内存无法分配。
CUBLAS_STATUS_SUCCESS	如果描述符已成功创建。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.31. cublasLtMatmulPreferenceInit()

cublasStatus_t cublasLtMatmulPreferenceInit(
      cublasLtMatmulPreference_t pref);

此函数在先前分配的矩阵乘法启发式搜索首选项描述符中初始化一个。

参数:

参数	内存	输入/输出	描述
pref		输出	指向保存由此函数创建的矩阵乘法首选项描述符的结构的指针。请参阅 cublasLtMatrixLayout_t。

返回值:

返回值	描述
CUBLAS_STATUS_ALLOC_FAILED	如果内存无法分配。
CUBLAS_STATUS_SUCCESS	如果描述符已成功创建。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.32. cublasLtMatmulPreferenceDestroy()

cublasStatus_t cublasLtMatmulPreferenceDestroy(
      cublasLtMatmulPreference_t pref);

此函数销毁先前创建的矩阵乘法首选项描述符对象。

参数:

参数	内存	输入/输出	描述
pref		输入	指向保存应由此函数销毁的矩阵乘法首选项描述符的结构的指针。请参阅 cublasLtMatmulPreference_t。

返回值:

返回值	描述
CUBLAS_STATUS_SUCCESS	如果操作成功。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.33. cublasLtMatmulPreferenceGetAttribute()

cublasStatus_t cublasLtMatmulPreferenceGetAttribute(
      cublasLtMatmulPreference_t pref,
      cublasLtMatmulPreferenceAttributes_t attr,
      void *buf,
      size_t sizeInBytes,
      size_t *sizeWritten);

此函数返回属于先前创建的矩阵乘法启发式搜索首选项描述符的查询属性的值。

参数:

参数	内存	输入/输出	描述
pref		输入	指向先前创建的、保存由此函数查询的矩阵乘法启发式搜索首选项描述符的结构的指针。请参阅 cublasLtMatmulPreference_t。
attr		输入	要由此函数查询的属性。请参阅 cublasLtMatmulPreferenceAttributes_t。
buf		输出	包含由此函数检索的属性值的内存地址。
sizeInBytes		输入	用于验证的 buf 缓冲区的大小（以字节为单位）。
sizeWritten		输出	仅当返回值是 CUBLAS_STATUS_SUCCESS 时有效。如果 sizeInBytes 为非零值：则 sizeWritten 是实际写入的字节数；如果 sizeInBytes 为 0：则 sizeWritten 是写入完整内容所需的字节数。

返回值:

返回值	描述
CUBLAS_STATUS_INVALID_VALUE	如果 sizeInBytes 为 0 且 sizeWritten 为 NULL，或者 如果 sizeInBytes 为非零值且 buf 为 NULL，或者 sizeInBytes 与所选属性的内部存储大小不匹配
CUBLAS_STATUS_SUCCESS	如果属性值已成功写入用户内存。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.34. cublasLtMatmulPreferenceSetAttribute()

cublasStatus_t cublasLtMatmulPreferenceSetAttribute(
      cublasLtMatmulPreference_t pref,
      cublasLtMatmulPreferenceAttributes_t attr,
      const void *buf,
      size_t sizeInBytes);

此函数设置属于先前创建的矩阵乘法首选项描述符的指定属性的值。

参数:

参数	内存	输入/输出	描述
pref		输入	指向先前创建的结构的指针，该结构保存了此函数查询的矩阵乘法偏好描述符。请参阅 cublasLtMatmulPreference_t。
attr		输入	此函数将要设置的属性。请参阅 cublasLtMatmulPreferenceAttributes_t。
buf		输入	应将指定属性设置为的值。
sizeInBytes		输入	用于验证的 buf 缓冲区的大小（以字节为单位）。

返回值:

返回值	描述
CUBLAS_STATUS_INVALID_VALUE	如果 buf 为 NULL 或 sizeInBytes 与所选属性的内部存储大小不匹配。
CUBLAS_STATUS_SUCCESS	如果属性已成功设置。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.35. cublasLtMatrixLayoutCreate()

cublasStatus_t cublasLtMatrixLayoutCreate( cublasLtMatrixLayout_t *matLayout,
                                           cudaDataType type,
                                           uint64_t rows,
                                           uint64_t cols,
                                           int64_t ld);

此函数通过分配保存其不透明结构所需的内存来创建矩阵布局描述符。

参数:

参数	内存	输入/输出	描述
matLayout		输出	指向此函数创建的矩阵布局描述符结构的指针。请参阅 cublasLtMatrixLayout_t。
type		输入	枚举量，指定此函数创建的矩阵布局描述符的数据精度。请参阅 cudaDataType。
rows, cols		输入	矩阵的行数和列数。
ld		输入	矩阵的前导维度。在列主序布局中，这是跳到下一列的元素数量。因此 ld >= m （行数）。

返回值:

返回值	描述
CUBLAS_STATUS_ALLOC_FAILED	如果内存无法分配。
CUBLAS_STATUS_SUCCESS	如果描述符已成功创建。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.36. cublasLtMatrixLayoutInit()

cublasStatus_t cublasLtMatrixLayoutInit( cublasLtMatrixLayout_t matLayout,
                                         cudaDataType type,
                                         uint64_t rows,
                                         uint64_t cols,
                                         int64_t ld);

此函数在先前分配的矩阵布局描述符中进行初始化。

参数:

参数	内存	输入/输出	描述
matLayout		输出	指向此函数初始化的矩阵布局描述符结构的指针。请参阅 cublasLtMatrixLayout_t。
type		输入	枚举量，指定此函数初始化的矩阵布局描述符的数据精度。请参阅 cudaDataType。
rows, cols		输入	矩阵的行数和列数。
ld		输入	矩阵的前导维度。在列主序布局中，这是跳到下一列的元素数量。因此 ld >= m （行数）。

返回值:

返回值	描述
CUBLAS_STATUS_ALLOC_FAILED	如果内存无法分配。
CUBLAS_STATUS_SUCCESS	如果描述符已成功创建。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.37. cublasLtMatrixLayoutDestroy()

cublasStatus_t cublasLtMatrixLayoutDestroy(
      cublasLtMatrixLayout_t matLayout);

此函数销毁先前创建的矩阵布局描述符对象。

参数:

参数	内存	输入/输出	描述
matLayout		输入	指向应由此函数销毁的矩阵布局描述符结构的指针。请参阅 cublasLtMatrixLayout_t。

返回值:

返回值	描述
CUBLAS_STATUS_SUCCESS	如果操作成功。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.38. cublasLtMatrixLayoutGetAttribute()

cublasStatus_t cublasLtMatrixLayoutGetAttribute(
      cublasLtMatrixLayout_t matLayout,
      cublasLtMatrixLayoutAttribute_t attr,
      void *buf,
      size_t sizeInBytes,
      size_t *sizeWritten);

此函数返回属于指定矩阵布局描述符的查询属性的值。

参数:

参数	内存	输入/输出	描述
matLayout		输入	指向先前创建的结构的指针，该结构保存了此函数查询的矩阵布局描述符。请参阅 cublasLtMatrixLayout_t。
attr		输入	正在查询的属性。请参阅 cublasLtMatrixLayoutAttribute_t。
buf		输出	此函数返回的属性值。
sizeInBytes		输入	用于验证的 buf 缓冲区的大小（以字节为单位）。
sizeWritten		输出	仅当返回值是 CUBLAS_STATUS_SUCCESS 时有效。如果 sizeInBytes 为非零值：则 sizeWritten 是实际写入的字节数；如果 sizeInBytes 为 0：则 sizeWritten 是写入完整内容所需的字节数。

返回值:

返回值	描述
CUBLAS_STATUS_INVALID_VALUE	如果 sizeInBytes 为 0 且 sizeWritten 为 NULL，或者 如果 sizeInBytes 为非零值且 buf 为 NULL，或者 sizeInBytes 与所选属性的内部存储大小不匹配
CUBLAS_STATUS_SUCCESS	如果属性值已成功写入用户内存。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.39. cublasLtMatrixLayoutSetAttribute()

cublasStatus_t cublasLtMatrixLayoutSetAttribute(
      cublasLtMatrixLayout_t matLayout,
      cublasLtMatrixLayoutAttribute_t attr,
      const void *buf,
      size_t sizeInBytes);

此函数设置属于先前创建的矩阵布局描述符的指定属性的值。

参数:

参数	内存	输入/输出	描述
matLayout		输入	指向先前创建的结构的指针，该结构保存了此函数查询的矩阵布局描述符。请参阅 cublasLtMatrixLayout_t。
attr		输入	此函数将要设置的属性。请参阅 cublasLtMatrixLayoutAttribute_t。
buf		输入	应将指定属性设置为的值。
sizeInBytes		输入	buf 的大小，属性缓冲区。

返回值:

返回值	描述
CUBLAS_STATUS_INVALID_VALUE	如果 buf 为 NULL 或 sizeInBytes 与所选属性的内部存储大小不匹配。
CUBLAS_STATUS_SUCCESS	如果属性设置成功。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.40. cublasLtMatrixTransform()

cublasStatus_t cublasLtMatrixTransform(
      cublasLtHandle_t lightHandle,
      cublasLtMatrixTransformDesc_t transformDesc,
      const void *alpha,
      const void *A,
      cublasLtMatrixLayout_t Adesc,
      const void *beta,
      const void *B,
      cublasLtMatrixLayout_t Bdesc,
      void *C,
      cublasLtMatrixLayout_t Cdesc,
      cudaStream_t stream);

此函数计算输入矩阵 A 和 B 的矩阵变换操作，以生成输出矩阵 C，根据以下操作

C = alpha*transformation(A) + beta*transformation(B),

其中 A、B 是输入矩阵，alpha 和 beta 是输入标量。变换操作由 transformDesc 指针定义。此函数可用于更改数据的内存顺序或缩放和偏移值。

参数:

参数	内存	输入/输出	描述
lightHandle		输入	指向为 cuBLASLt 上下文分配的 cuBLASLt 句柄的指针。请参阅 cublasLtHandle_t。
transformDesc		输入	指向保存矩阵变换操作的不透明描述符的指针。请参阅 cublasLtMatrixTransformDesc_t。
alpha, beta	设备或主机	输入	指向乘法中使用的标量的指针。
A, B	设备	输入	指向与相应描述符 Adesc 和 Bdesc 关联的 GPU 内存的指针。
C	设备	输出	指向与 Cdesc 描述符关联的 GPU 内存的指针。
Adesc、Bdesc 和 Cdesc		输入	指向先前创建的类型为 cublasLtMatrixLayout_t 的描述符的句柄。 如果相应的指针为 NULL 且相应的标量为零，则 Adesc 或 Bdesc 可以为 NULL。
stream	主机	输入	所有 GPU 工作将提交到的 CUDA 流。

返回值:

返回值	描述
CUBLAS_STATUS_NOT_INITIALIZED	如果 cuBLASLt 句柄尚未初始化。
CUBLAS_STATUS_INVALID_VALUE	如果参数冲突或配置不可能。例如，当 A 不为 NULL，但 Adesc 为 NULL 时。
CUBLAS_STATUS_NOT_SUPPORTED	如果所选设备上的当前实现不支持配置的操作。
CUBLAS_STATUS_ARCH_MISMATCH	如果配置的操作无法使用所选设备运行。
CUBLAS_STATUS_EXECUTION_FAILED	如果 CUDA 报告了来自设备的执行错误。
CUBLAS_STATUS_SUCCESS	如果操作成功完成。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.41. cublasLtMatrixTransformDescCreate()

cublasStatus_t cublasLtMatrixTransformDescCreate(
      cublasLtMatrixTransformDesc_t *transformDesc,
      cudaDataType scaleType);

此函数通过分配保存其不透明结构所需的内存来创建矩阵变换描述符。

参数:

参数	内存	输入/输出	描述
transformDesc		输出	指向保存此函数创建的矩阵变换描述符的结构的指针。请参阅 cublasLtMatrixTransformDesc_t。
表 1. 当 A、B、C 和 D 是规则的列优先或行优先矩阵时		输入	指定此函数创建的矩阵变换描述符的数据精度的枚举数。请参阅 cudaDataType。

返回值:

返回值	描述
CUBLAS_STATUS_ALLOC_FAILED	如果内存无法分配。
CUBLAS_STATUS_SUCCESS	如果描述符已成功创建。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.42. cublasLtMatrixTransformDescInit()

cublasStatus_t cublasLtMatrixTransformDescInit(
      cublasLtMatrixTransformDesc_t transformDesc,
      cudaDataType scaleType);

此函数在先前分配的矩阵变换描述符中进行初始化。

参数:

参数	内存	输入/输出	描述
transformDesc		输出	指向此函数初始化的矩阵变换描述符结构的指针。请参阅 cublasLtMatrixTransformDesc_t。
表 1. 当 A、B、C 和 D 是规则的列优先或行优先矩阵时		输入	指定此函数初始化的矩阵变换描述符的数据精度的枚举数。请参阅 cudaDataType。

返回值:

返回值	描述
CUBLAS_STATUS_ALLOC_FAILED	如果内存无法分配。
CUBLAS_STATUS_SUCCESS	如果描述符已成功创建。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.43. cublasLtMatrixTransformDescDestroy()

cublasStatus_t cublasLtMatrixTransformDescDestroy(
      cublasLtMatrixTransformDesc_t transformDesc);

此函数销毁先前创建的矩阵变换描述符对象。

参数:

参数	内存	输入/输出	描述
transformDesc		输入	指向应由此函数销毁的矩阵变换描述符结构的指针。请参阅 cublasLtMatrixTransformDesc_t。

返回值:

返回值	描述
CUBLAS_STATUS_SUCCESS	如果操作成功。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.44. cublasLtMatrixTransformDescGetAttribute()

cublasStatus_t cublasLtMatrixTransformDescGetAttribute(
      cublasLtMatrixTransformDesc_t transformDesc,
      cublasLtMatrixTransformDescAttributes_t attr,
      void *buf,
      size_t sizeInBytes,
      size_t *sizeWritten);

此函数返回属于先前创建的矩阵变换描述符的查询属性的值。

参数:

参数	内存	输入/输出	描述
transformDesc		输入	指向先前创建的结构的指针，该结构保存了此函数查询的矩阵变换描述符。请参阅 cublasLtMatrixTransformDesc_t。
attr		输入	此函数将要检索的属性。请参阅 cublasLtMatrixTransformDescAttributes_t。
buf		输出	包含由此函数检索的属性值的内存地址。
sizeInBytes		输入	用于验证的 buf 缓冲区的大小（以字节为单位）。
sizeWritten		输出	仅当返回值是 CUBLAS_STATUS_SUCCESS 时有效。如果 sizeInBytes 为非零值：则 sizeWritten 是实际写入的字节数；如果 sizeInBytes 为 0：则 sizeWritten 是写入完整内容所需的字节数。

返回值:

返回值	描述
CUBLAS_STATUS_INVALID_VALUE	如果 sizeInBytes 为零且 sizeWritten 为 NULL，或者 如果 sizeInBytes 为非零值且 buf 为 NULL，或者 如果 sizeInBytes 与所选属性的内部存储大小不匹配
CUBLAS_STATUS_SUCCESS	如果属性值已成功写入用户内存。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

3.4.45. cublasLtMatrixTransformDescSetAttribute()

cublasStatus_t cublasLtMatrixTransformDescSetAttribute(
      cublasLtMatrixTransformDesc_t transformDesc,
      cublasLtMatrixTransformDescAttributes_t attr,
      const void *buf,
      size_t sizeInBytes);

此函数设置属于先前创建的矩阵变换描述符的指定属性的值。

参数:

参数	内存	输入/输出	描述
transformDesc		输入	指向先前创建的结构的指针，该结构保存了此函数查询的矩阵变换描述符。请参阅 cublasLtMatrixTransformDesc_t。
attr		输入	此函数将要设置的属性。请参阅 cublasLtMatrixTransformDescAttributes_t。
buf		输入	应将指定属性设置为的值。
sizeInBytes		输入	用于验证的 buf 缓冲区的大小（以字节为单位）。

返回值:

返回值	描述
CUBLAS_STATUS_INVALID_VALUE	如果 buf 为 NULL 或 sizeInBytes 与所选属性的内部存储大小不匹配。
CUBLAS_STATUS_SUCCESS	如果属性已成功设置。

有关有效返回代码的完整列表，请参阅 cublasStatus_t。

4. 使用 cuBLASXt API

4.1. 一般描述

cuBLAS 的 cuBLASXt API 公开了一个多 GPU 功能的主机接口：当使用此 API 时，应用程序仅需要在主机内存空间上分配所需的矩阵。此外，当前的实现在 Linux 上支持具有计算能力 6.x 或更高版本的 GPU 设备的托管内存，但将其视为主机内存。Windows 上不支持托管内存。只要它们可以容纳在主机内存中，矩阵的大小就没有限制。cuBLASXt API 负责在指定的 GPU 之间分配内存，并在它们之间调度工作负载，最后将结果检索回主机。cuBLASXt API 仅支持计算密集型 BLAS3 例程（例如矩阵-矩阵运算），其中可以摊销从 GPU 来回的 PCI 传输。cuBLASXt API 有其自己的头文件 cublasXt.h。

从 8.0 版本开始，cuBLASXt API 允许任何矩阵位于 GPU 设备上。

注意

当使用流排序内存分配器提供在 GPU 上分配的矩阵时，请通过使用 cudaMemPoolSetAccess 确保跨所有设备的可见性。

注意

cuBLASXt API 仅在 64 位平台上受支持。

4.1.1. 平铺设计方法

为了能够在多个 GPU 之间共享工作负载，cuBLASXt API 使用平铺策略：每个矩阵都划分为用户可控制维度 BlockDim x BlockDim 的正方形瓦片。生成的矩阵平铺定义了静态调度策略：每个生成的瓦片都以循环方式分配给 GPU。每个 GPU 创建一个 CPU 线程，负责执行适当的内存传输和 cuBLAS 操作，以计算其负责的所有瓦片。从性能的角度来看，由于这种静态调度策略，最好每个 GPU 的计算能力和 PCI 带宽都相同。下图说明了 3 个 GPU 之间的瓦片分布。为了计算 C 中的第一个瓦片 G0，负责 GPU0 的 CPU 线程 0 必须以流水线方式从 A 的第一行加载 3 个瓦片，并从 B 的第一列加载瓦片，以便重叠内存传输和计算，并将结果求和到 C 的第一个瓦片 G0 中，然后再继续处理下一个瓦片 G0。

cublasXt<t>gemm() 针对 3 个 GPU 的平铺示例

当瓦片尺寸不是 C 尺寸的精确倍数时，某些瓦片会在右边框或/和底部边框上部分填充。当前的实现不会填充不完整的瓦片，而是通过执行正确的缩减 cuBLAS 操作来简单地跟踪这些不完整的瓦片：这样，就不会进行额外的计算。但是，当所有 GPU 没有相同数量的不完整瓦片要处理时，仍然可能导致一些负载不平衡。

当一个或多个矩阵位于某些 GPU 设备上时，将应用相同的平铺方法和工作负载共享。在这种情况下，内存传输在设备之间完成。但是，当瓦片的计算和某些数据位于同一 GPU 设备上时，会绕过与本地数据之间的瓦片内存传输，并且 GPU 直接对本地数据进行操作。这可以显着提高性能，尤其是在仅使用一个 GPU 进行计算时。

矩阵可以位于任何 GPU 设备上，并且不必位于同一 GPU 设备上。此外，矩阵甚至可以位于不参与计算的 GPU 设备上。

与 cuBLAS API 相反，即使所有矩阵都位于同一设备上，cuBLASXt API 从主机的角度来看仍然是阻塞式 API：无论数据结果位于何处，在调用返回时都将有效，并且不需要设备同步。

4.1.2. 混合 CPU-GPU 计算

在非常大的问题的情况下，cuBLASXt API 提供了将部分计算卸载到主机 CPU 的可能性。可以使用例程 cublasXtSetCpuRoutine() 和 cublasXtSetCpuRatio() 设置此功能。分配给 CPU 的工作负载被放在一边：它只是结果矩阵的百分比，从底部和右侧获取，以较大尺寸为准。GPU 平铺是在缩减的结果矩阵上完成的。

如果任何矩阵位于 GPU 设备上，则忽略该功能，并且所有计算都将仅在 GPU 上完成

应谨慎使用此功能，因为它可能会干扰负责馈送 GPU 的 CPU 线程。

目前，只有例程 cublasXt<t>gemm() 支持此功能。

4.1.3. 结果可重复性

当前，当满足以下条件时，来自给定工具包版本的所有 cuBLASXt API 例程都会生成相同的位级结果

• 参与计算的所有 GPU 具有相同的计算能力和相同数量的 SM。

• 瓦片大小在运行之间保持不变。

• 要么不使用 CPU 混合计算，要么提供的 CPU Blas 也保证产生可重复的结果。

4.2. cuBLASXt API 数据类型参考

4.2.1. cublasXtHandle_t

cublasXtHandle_t 类型是指向保存 cuBLASXt API 上下文的不透明结构的指针类型。cuBLASXt API 上下文必须使用 cublasXtCreate() 初始化，并且返回的句柄必须传递给所有后续的 cuBLASXt API 函数调用。上下文应在使用 cublasXtDestroy() 结束时销毁。

4.2.2. cublasXtOpType_t

cublasOpType_t 枚举了 BLAS 例程支持的四种可能的类型。此枚举用作例程 cublasXtSetCpuRoutine 和 cublasXtSetCpuRatio 的参数，以设置混合配置。

值	含义
CUBLASXT_FLOAT	float 或单精度类型
CUBLASXT_DOUBLE	双精度类型
CUBLASXT_COMPLEX	单精度复数
CUBLASXT_DOUBLECOMPLEX	双精度复数

4.2.3. cublasXtBlasOp_t

cublasXtBlasOp_t 类型枚举了 cuBLASXt API 支持的 BLAS3 或类 BLAS 例程。此枚举用作例程 cublasXtSetCpuRoutine 和 cublasXtSetCpuRatio 的参数，以设置混合配置。

值	含义
CUBLASXT_GEMM	GEMM 例程
CUBLASXT_SYRK	SYRK 例程
CUBLASXT_HERK	HERK 例程
CUBLASXT_SYMM	SYMM 例程
CUBLASXT_HEMM	HEMM 例程
CUBLASXT_TRSM	TRSM 例程
CUBLASXT_SYR2K	SYR2K 例程
CUBLASXT_HER2K	HER2K 例程
CUBLASXT_SPMM	SPMM 例程
CUBLASXT_SYRKX	SYRKX 例程
CUBLASXT_HERKX	HERKX 例程

4.2.4. cublasXtPinningMemMode_t

此类型用于通过例程 cubasMgSetPinningMemMode 启用或禁用固定内存模式

值	含义
CUBLASXT_PINNING_DISABLED	禁用固定内存模式
CUBLASXT_PINNING_ENABLED	启用固定内存模式

4.3. cuBLASXt API 辅助函数参考

4.3.1. cublasXtCreate()

cublasStatus_t
cublasXtCreate(cublasXtHandle_t *handle)

此函数初始化 cuBLASXt API 并创建一个句柄，指向保存 cuBLASXt API 上下文的不透明结构。它在主机和设备上分配硬件资源，并且必须在进行任何其他 cuBLASXt API 调用之前调用。

返回值	含义
CUBLAS_STATUS_SUCCESS	初始化成功
CUBLAS_STATUS_ALLOC_FAILED	资源无法分配
CUBLAS_STATUS_NOT_SUPPORTED	cuBLASXt API 仅在 64 位平台上受支持

4.3.2. cublasXtDestroy()

cublasStatus_t
cublasXtDestroy(cublasXtHandle_t handle)

此函数释放 cuBLASXt API 上下文使用的硬件资源。GPU 资源的释放可能会延迟到应用程序退出时。此函数通常是使用特定句柄对 cuBLASXt API 的最后一次调用。

返回值	含义
CUBLAS_STATUS_SUCCESS	关闭成功
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化

4.3.3. cublasXtDeviceSelect()

cublasXtDeviceSelect(cublasXtHandle_t handle, int nbDevices, int deviceId[])

此函数允许用户提供 GPU 设备的数量及其各自的 ID，这些设备将参与后续的 cuBLASXt API 数学函数调用。此函数将为列表中提供的每个 GPU 创建一个 cuBLAS 上下文。当前，设备配置是静态的，并且在数学函数调用之间无法更改。在这方面，此函数应仅在 cublasXtCreate 之后调用一次。为了能够运行多个配置，应创建多个 cuBLASXt API 上下文。

返回值	含义
CUBLAS_STATUS_SUCCESS	用户调用成功
CUBLAS_STATUS_INVALID_VALUE	无法访问至少一个设备，或者无法在至少一个设备上创建 cuBLAS 上下文
CUBLAS_STATUS_ALLOC_FAILED	某些资源无法分配。

4.3.4. cublasXtSetBlockDim()

cublasXtSetBlockDim(cublasXtHandle_t handle, int blockDim)

此函数允许用户为后续的数学函数调用设置用于矩阵平铺的块维度。矩阵被分割成 blockDim x blockDim 维度的正方形瓦片。可以随时调用此函数，并且将对后续的数学函数调用生效。应选择块维度以优化数学运算，并确保 PCI 传输与计算良好重叠。

返回值	含义
CUBLAS_STATUS_SUCCESS	调用已成功
CUBLAS_STATUS_INVALID_VALUE	blockDim <= 0

4.3.5. cublasXtGetBlockDim()

cublasXtGetBlockDim(cublasXtHandle_t handle, int *blockDim)

此函数允许用户查询用于矩阵平铺的块维度。

返回值	含义
CUBLAS_STATUS_SUCCESS	调用已成功

4.3.6. cublasXtSetCpuRoutine()

cublasXtSetCpuRoutine(cublasXtHandle_t handle, cublasXtBlasOp_t blasOp, cublasXtOpType_t type, void *blasFunctor)

此函数允许用户提供相应 BLAS 例程的 CPU 实现。此函数可以与函数 cublasXtSetCpuRatio() 一起使用，以定义 CPU 和 GPU 之间的混合计算。当前，混合功能仅支持 xGEMM 例程。

返回值	含义
CUBLAS_STATUS_SUCCESS	调用已成功
CUBLAS_STATUS_INVALID_VALUE	blasOp 或 type 定义了无效的组合
CUBLAS_STATUS_NOT_SUPPORTED	该例程不支持 CPU-GPU 混合

4.3.7. cublasXtSetCpuRatio()

cublasXtSetCpuRatio(cublasXtHandle_t handle, cublasXtBlasOp_t blasOp, cublasXtOpType_t type, float ratio )

此函数允许用户定义在混合计算上下文中应在 CPU 上完成的工作负载百分比。此函数可以与函数 cublasXtSetCpuRoutine() 一起使用，以定义 CPU 和 GPU 之间的混合计算。当前，混合功能仅支持 xGEMM 例程。

返回值	含义
CUBLAS_STATUS_SUCCESS	调用已成功
CUBLAS_STATUS_INVALID_VALUE	blasOp 或 type 定义了无效的组合
CUBLAS_STATUS_NOT_SUPPORTED	该例程不支持 CPU-GPU 混合

4.3.8. cublasXtSetPinningMemMode()

cublasXtSetPinningMemMode(cublasXtHandle_t handle, cublasXtPinningMemMode_t mode)

此函数允许用户启用或禁用固定内存模式。启用后，如果矩阵尚未固定，则在后续 cuBLASXt API 调用中传递的矩阵将分别使用 CUDART 例程 cudaHostRegister() 和 cudaHostUnregister() 进行固定/取消固定。如果矩阵恰好是部分固定的，它也不会被固定。固定内存可以提高 PCI 传输性能，并允许 PCI 内存传输与计算重叠。但是，固定/取消固定内存需要一些时间，这可能无法摊销。建议用户使用 cudaMallocHost() 或 cudaHostRegister() 自行固定内存，并在计算序列完成后取消固定。默认情况下，固定内存模式已禁用。

注意

当用于不同 cuBLASXt API 调用的矩阵重叠时，不应启用固定内存模式。cuBLASXt 使用 cudaHostGetFlags() 确定矩阵是否已固定（如果该矩阵的第一个地址已固定），因此无法知道矩阵是否已部分固定。在多线程应用程序中尤其如此，在多线程应用程序中，当另一个线程正在访问该内存时，内存可能会被部分或完全固定或取消固定。

返回值	含义
CUBLAS_STATUS_SUCCESS	调用已成功
CUBLAS_STATUS_INVALID_VALUE	mode 值与 CUBLASXT_PINNING_DISABLED 和 CUBLASXT_PINNING_ENABLED 不同

4.3.9. cublasXtGetPinningMemMode()

cublasXtGetPinningMemMode(cublasXtHandle_t handle, cublasXtPinningMemMode_t *mode)

此函数允许用户查询固定内存模式。默认情况下，固定内存模式已禁用。

返回值	含义
CUBLAS_STATUS_SUCCESS	调用已成功

4.4. cuBLASXt API 数学函数参考

在本章中，我们描述了 cuBLASXt API 支持的实际线性代数例程。我们将使用缩写 <type> 表示类型，<t> 表示相应的简短类型，以便更简洁明了地介绍已实现的函数。除非另有说明，否则 <type> 和 <t> 具有以下含义

<type>	<t>	含义
float	‘s’ 或 ‘S’	实数单精度
double	‘d’ 或 ‘D’	实数双精度
cuComplex	‘c’ 或 ‘C’	复数单精度
cuDoubleComplex	‘z’ 或 ‘Z’	复数双精度

缩写 \(\mathbf{Re}(\cdot)\) 和 \(\mathbf{Im}(\cdot)\) 将分别代表数字的实部和虚部。 由于实数的虚部不存在，我们将认为它为零，并且通常可以简单地从正在使用它的方程中丢弃它。 此外，\(\bar{\alpha}\) 将表示 \(\alpha\) 的复共轭。

通常在整个文档中，小写希腊字母 \(\alpha\) 和 \(\beta\) 将表示标量，粗体小写英文字母 \(\mathbf{x}\) 和 \(\mathbf{y}\) 将表示向量，大写英文字母 \(A\) 、 \(B\) 和 \(C\) 将表示矩阵。

4.4.1. cublasXt<t>gemm()

cublasStatus_t cublasXtSgemm(cublasXtHandle_t handle,
                           cublasOperation_t transa, cublasOperation_t transb,
                           size_t m, size_t n, size_t k,
                           const float           *alpha,
                           const float           *A, int lda,
                           const float           *B, int ldb,
                           const float           *beta,
                           float           *C, int ldc)
cublasStatus_t cublasXtDgemm(cublasXtHandle_t handle,
                           cublasOperation_t transa, cublasOperation_t transb,
                           int m, int n, int k,
                           const double          *alpha,
                           const double          *A, int lda,
                           const double          *B, int ldb,
                           const double          *beta,
                           double          *C, int ldc)
cublasStatus_t cublasXtCgemm(cublasXtHandle_t handle,
                           cublasOperation_t transa, cublasOperation_t transb,
                           int m, int n, int k,
                           const cuComplex       *alpha,
                           const cuComplex       *A, int lda,
                           const cuComplex       *B, int ldb,
                           const cuComplex       *beta,
                           cuComplex       *C, int ldc)
cublasStatus_t cublasXtZgemm(cublasXtHandle_t handle,
                           cublasOperation_t transa, cublasOperation_t transb,
                           int m, int n, int k,
                           const cuDoubleComplex *alpha,
                           const cuDoubleComplex *A, int lda,
                           const cuDoubleComplex *B, int ldb,
                           const cuDoubleComplex *beta,
                           cuDoubleComplex *C, int ldc)

此函数执行矩阵-矩阵乘法

\(C = \alpha\text{op}(A)\text{op}(B) + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(A\) 、 \(B\) 和 \(C\) 是以列优先格式存储的矩阵，其维度分别为 \(\text{op}(A)\) \(m \times k\) 、 \(\text{op}(B)\) \(k \times n\) 和 \(C\) \(m \times n\) 。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ A^{H} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

并且对于矩阵 \(B\) ，\(\text{op}(B)\) 的定义类似。

参数。	内存	输入/输出	含义
handle		输入	cuBLASXt API 上下文的句柄。
transa		输入	运算 op(A) 是非转置或（共轭）转置。
transb		输入	运算 op(B) 是非转置或（共轭）转置。
m		输入	矩阵 op(A) 和 C 的行数。
n		输入	矩阵 op(B) 和 C 的列数。
k		输入	op(A) 的列数和 op(B) 的行数。
alpha	主机	输入	用于乘法的 <type> 标量。
A	主机或设备	输入	维度为 lda x k 的 <type> 数组，如果 transa == CUBLAS_OP_N，则 lda >= max(1, m)；如果不是，则维度为 lda x m，且 lda >= max(1, k)。
lda		输入	用于存储矩阵 A 的二维数组的前导维度。
B	主机或设备	输入	维度为 ldb x n 的 <type> 数组，其中 ldb >= max(1, k) 如果 transb == CUBLAS_OP_N 且 ldb x k 其中 ldb >= max(1, n) 否则。
ldb		输入	用于存储矩阵 B 的二维数组的前导维度。
beta	主机	输入	用于乘法的 <type> 标量值。 如果 beta == 0，则 C 不必是有效的输入。
C	主机或设备	输入/输出	维度为 ldc x n 的 <type> 数组，且 ldc >= max(1, m)。
ldc		输入	用于存储矩阵 C 的二维数组的前导维度。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	参数 m,n,k<0
CUBLAS_STATUS_EXECUTION_FAILED	函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

sgemm(), dgemm(), cgemm(), zgemm()

4.4.2. cublasXt<t>hemm()

cublasStatus_t cublasXtChemm(cublasXtHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           size_t m, size_t n,
                           const cuComplex       *alpha,
                           const cuComplex       *A, size_t lda,
                           const cuComplex       *B, size_t ldb,
                           const cuComplex       *beta,
                           cuComplex       *C, size_t ldc)
cublasStatus_t cublasXtZhemm(cublasXtHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           size_t m, size_t n,
                           const cuDoubleComplex *alpha,
                           const cuDoubleComplex *A, size_t lda,
                           const cuDoubleComplex *B, size_t ldb,
                           const cuDoubleComplex *beta,
                           cuDoubleComplex *C, size_t ldc)

此函数执行 Hermitian 矩阵-矩阵乘法

\(C = \left\{ \begin{matrix} {\alpha AB + \beta C} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ {\alpha BA + \beta C} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_RIGHT}$}} \\ \end{matrix} \right.\)

其中 \(A\) 是以较低或较高模式存储的 Hermitian 矩阵，\(B\) 和 \(C\) 是 \(m \times n\) 矩阵，而 \(\alpha\) 和 \(\beta\) 是标量。

参数。	内存	输入/输出	含义
handle		输入	cuBLASXt API 上下文的句柄。
side		输入	指示矩阵 A 在 B 的左侧还是右侧。
uplo		输入	指示矩阵 A 的下半部分或上半部分是否存储，另一个 Hermitian 部分未被引用，而是从存储的元素推断出来的。
m		输入	矩阵 C 和 B 的行数，矩阵 A 的大小也相应调整。
n		输入	矩阵 C 和 B 的列数，矩阵 A 的大小也相应调整。
alpha	主机	输入	用于乘法的 <type> 标量。
A	主机或设备	输入	<type> 维度为 lda x m 的数组，如果 side==CUBLAS_SIDE_LEFT，则 lda >= max(1, m)；否则，维度为 lda x n，且 lda >= max(1, n)。 假定对角元素的虚部为零。
lda		输入	用于存储矩阵 A 的二维数组的前导维度。
B	主机或设备	输入	维度为 ldb x n 的 <type> 数组，且 ldb >= max(1, m)。
ldb		输入	用于存储矩阵 B 的二维数组的前导维度。
beta	主机	输入	用于乘法的 <type> 标量，如果 beta == 0，则 C 不必是有效的输入。
C	主机或设备	输入/输出	维度为 ldc x n 的 <type> 数组，且 ldc >= max(1, m)。
ldc		输入	用于存储矩阵 C 的二维数组的前导维度。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	参数 m < 0 或 n < 0
CUBLAS_STATUS_EXECUTION_FAILED	函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

chemm(), zhemm()

4.4.3. cublasXt<t>symm()

cublasStatus_t cublasXtSsymm(cublasXtHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           size_t m, size_t n,
                           const float           *alpha,
                           const float           *A, size_t lda,
                           const float           *B, size_t ldb,
                           const float           *beta,
                           float           *C, size_t ldc)
cublasStatus_t cublasXtDsymm(cublasXtHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           size_t m, size_t n,
                           const double          *alpha,
                           const double          *A, size_t lda,
                           const double          *B, size_t ldb,
                           const double          *beta,
                           double          *C, size_t ldc)
cublasStatus_t cublasXtCsymm(cublasXtHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           size_t m, size_t n,
                           const cuComplex       *alpha,
                           const cuComplex       *A, size_t lda,
                           const cuComplex       *B, size_t ldb,
                           const cuComplex       *beta,
                           cuComplex       *C, size_t ldc)
cublasStatus_t cublasXtZsymm(cublasXtHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           size_t m, size_t n,
                           const cuDoubleComplex *alpha,
                           const cuDoubleComplex *A, size_t lda,
                           const cuDoubleComplex *B, size_t ldb,
                           const cuDoubleComplex *beta,
                           cuDoubleComplex *C, size_t ldc)

此函数执行对称矩阵-矩阵乘法

\(C = \left\{ \begin{matrix} {\alpha AB + \beta C} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ {\alpha BA + \beta C} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_RIGHT}$}} \\ \end{matrix} \right.\)

其中 \(A\) 是以较低或较高模式存储的对称矩阵，\(A\) 和 \(A\) 是 \(m \times n\) 矩阵，并且 \(\alpha\) 和 \(\beta\) 是标量。

参数。	内存	输入/输出	含义
handle		输入	cuBLASXt API 上下文的句柄。
side		输入	指示矩阵 A 在 B 的左侧还是右侧。
uplo		输入	指示矩阵 A 的下半部分或上半部分是否存储，另一个对称部分未被引用，而是从存储的元素推断出来的。
m		输入	矩阵 A 和 B 的行数，矩阵 A 的大小也相应调整。
n		输入	矩阵 C 和 A 的列数，矩阵 A 的大小也相应调整。
alpha	主机	输入	用于乘法的 <type> 标量。
A	主机或设备	输入	维度为 lda x m 的 <type> 数组，如果 side == CUBLAS_SIDE_LEFT，则 lda >= max(1, m)；如果不是，则维度为 lda x n，且 lda >= max(1, n)。
lda		输入	用于存储矩阵 A 的二维数组的前导维度。
B	主机或设备	输入	维度为 ldb x n 的 <type> 数组，且 ldb >= max(1, m)。
ldb		输入	用于存储矩阵 B 的二维数组的前导维度。
beta	主机	输入	用于乘法的 <type> 标量，如果 beta == 0，则 C 不必是有效的输入。
C	主机或设备	输入/输出	维度为 ldc x n 的 <type> 数组，且 ldc >= max(1, m)。
ldc		输入	用于存储矩阵 C 的二维数组的前导维度。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	参数 m < 0 或 n < 0
CUBLAS_STATUS_EXECUTION_FAILED	函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

ssymm(), dsymm(), csymm(), zsymm()

4.4.4. cublasXt<t>syrk()

cublasStatus_t cublasXtSsyrk(cublasXtHandle_t handle,
                           cublasFillMode_t uplo, cublasOperation_t trans,
                           int n, int k,
                           const float           *alpha,
                           const float           *A, int lda,
                           const float           *beta,
                           float           *C, int ldc)
cublasStatus_t cublasXtDsyrk(cublasXtHandle_t handle,
                           cublasFillMode_t uplo, cublasOperation_t trans,
                           int n, int k,
                           const double          *alpha,
                           const double          *A, int lda,
                           const double          *beta,
                           double          *C, int ldc)
cublasStatus_t cublasXtCsyrk(cublasXtHandle_t handle,
                           cublasFillMode_t uplo, cublasOperation_t trans,
                           int n, int k,
                           const cuComplex       *alpha,
                           const cuComplex       *A, int lda,
                           const cuComplex       *beta,
                           cuComplex       *C, int ldc)
cublasStatus_t cublasXtZsyrk(cublasXtHandle_t handle,
                           cublasFillMode_t uplo, cublasOperation_t trans,
                           int n, int k,
                           const cuDoubleComplex *alpha,
                           const cuDoubleComplex *A, int lda,
                           const cuDoubleComplex *beta,
                           cuDoubleComplex *C, int ldc)

此函数执行对称秩- \(k\) 更新

\(C = \alpha\text{op}(A)\text{op}(A)^{T} + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以较低或较高模式存储的对称矩阵，而 \(A\) 是维度为 \(\text{op}(A)\) \(n \times k\) 的矩阵。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ \end{matrix} \right.\)

参数。	内存	输入/输出	含义
handle		输入	cuBLASXt API 上下文的句柄。
uplo		输入	指示矩阵 C 的下半部分或上半部分是否存储，另一个对称部分未被引用，而是从存储的元素推断出来的。
trans		输入	运算 op(A) 是非转置或转置。
n		输入	矩阵 op(A) 和 C 的行数。
k		输入	矩阵 op(A) 的列数。
alpha	主机	输入	用于乘法的 <type> 标量。
A	主机或设备	输入	<type> 维度为 lda x k 的数组，如果 trans == CUBLAS_OP_N，则 lda >= max(1, n)；否则，维度为 lda x n，且 lda >= max(1, k)。
lda		输入	用于存储矩阵 A 的二维数组的前导维度。
beta	主机	输入	用于乘法的 <type> 标量，如果 beta == 0，则 C 不必是有效的输入。
C	主机或设备	输入/输出	<type> 维度为 ldc x n 的数组，且 ldc >= max(1, n)。
ldc		输入	用于存储矩阵 C 的二维数组的前导维度。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	参数 n < 0 或 k < 0
CUBLAS_STATUS_EXECUTION_FAILED	函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

ssyrk(), dsyrk(), csyrk(), zsyrk()

4.4.5. cublasXt<t>syr2k()

cublasStatus_t cublasXtSsyr2k(cublasXtHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            size_t n, size_t k,
                            const float           *alpha,
                            const float           *A, size_t lda,
                            const float           *B, size_t ldb,
                            const float           *beta,
                            float           *C, size_t ldc)
cublasStatus_t cublasXtDsyr2k(cublasXtHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            size_t n, size_t k,
                            const double          *alpha,
                            const double          *A, size_t lda,
                            const double          *B, size_t ldb,
                            const double          *beta,
                            double          *C, size_t ldc)
cublasStatus_t cublasXtCsyr2k(cublasXtHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            size_t n, size_t k,
                            const cuComplex       *alpha,
                            const cuComplex       *A, size_t lda,
                            const cuComplex       *B, size_t ldb,
                            const cuComplex       *beta,
                            cuComplex       *C, size_t ldc)
cublasStatus_t cublasXtZsyr2k(cublasXtHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            size_t n, size_t k,
                            const cuDoubleComplex *alpha,
                            const cuDoubleComplex *A, size_t lda,
                            const cuDoubleComplex *B, size_t ldb,
                            const cuDoubleComplex *beta,
                            cuDoubleComplex *C, size_t ldc)

此函数执行对称秩- \(2k\) 更新

\(C = \alpha(\text{op}(A)\text{op}(B)^{T} + \text{op}(B)\text{op}(A)^{T}) + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以较低或较高模式存储的对称矩阵，而 \(A\) 和 \(B\) 分别是维度为 \(\text{op}(A)\) \(n \times k\) 和 \(\text{op}(B)\) \(n \times k\) 的矩阵。 此外，对于矩阵 \(A\) 和 \(B\)

\(\text{op(}A\text{) and op(}B\text{)} = \left\{ \begin{matrix} {A\text{ and }B} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A^{T}\text{ and }B^{T}} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_T}$}} \\ \end{matrix} \right.\)

参数。	内存	输入/输出	含义
handle		输入	cuBLASXt API 上下文的句柄。
uplo		输入	指示矩阵 C 的下半部分或上半部分是否存储，另一个对称部分未被引用，而是从存储的元素推断出来的。
trans		输入	运算 op(A) 是非转置或转置。
n		输入	矩阵 op(A), op(B) 和 C 的行数。
k		输入	矩阵 op(A) 和 op(B) 的列数。
alpha	主机	输入	用于乘法的 <type> 标量。
A	主机或设备	输入	<type> 维度为 lda x k 的数组，如果 transa == CUBLAS_OP_N，则 lda >= max(1, n)；否则，维度为 lda x n，且 lda >= max(1, k)。
lda		输入	用于存储矩阵 A 的二维数组的前导维度。
B	主机或设备	输入	<type> 维度为 ldb x k 的数组，如果 transb == CUBLAS_OP_N，则 ldb >= max(1, n)；否则，维度为 ldb x n，且 ldb >= max(1, k)。
ldb		输入	用于存储矩阵 B 的二维数组的前导维度。
beta	主机	输入	<type> 用于乘法的标量；如果 beta == 0，则 C 不必是有效输入。
C	主机或设备	输入/输出	<type> 维度为 ldc x n 的数组，且 ldc >= max(1, n)。
ldc		输入	用于存储矩阵 C 的二维数组的前导维度。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	参数 n < 0 或 k < 0
CUBLAS_STATUS_EXECUTION_FAILED	函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

ssyr2k(), dsyr2k(), csyr2k(), zsyr2k()

4.4.6. cublasXt<t>syrkx()

cublasStatus_t cublasXtSsyrkx(cublasXtHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            size_t n, size_t k,
                            const float           *alpha,
                            const float           *A, size_t lda,
                            const float           *B, size_t ldb,
                            const float           *beta,
                            float           *C, size_t ldc)
cublasStatus_t cublasXtDsyrkx(cublasXtHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            size_t n, size_t k,
                            const double          *alpha,
                            const double          *A, size_t lda,
                            const double          *B, size_t ldb,
                            const double          *beta,
                            double          *C, size_t ldc)
cublasStatus_t cublasXtCsyrkx(cublasXtHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            size_t n, size_t k,
                            const cuComplex       *alpha,
                            const cuComplex       *A, size_t lda,
                            const cuComplex       *B, size_t ldb,
                            const cuComplex       *beta,
                            cuComplex       *C, size_t ldc)
cublasStatus_t cublasXtZsyrkx(cublasXtHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            size_t n, size_t k,
                            const cuDoubleComplex *alpha,
                            const cuDoubleComplex *A, size_t lda,
                            const cuDoubleComplex *B, size_t ldb,
                            const cuDoubleComplex *beta,
                            cuDoubleComplex *C, size_t ldc)

此函数执行对称秩- \(k\) 更新的变体

\(C = \alpha(\text{op}(A)\text{op}(B)^{T} + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以较低或较高模式存储的对称矩阵，而 \(A\) 和 \(B\) 分别是维度为 \(\text{op}(A)\) \(n \times k\) 和 \(\text{op}(B)\) \(n \times k\) 的矩阵。 此外，对于矩阵 \(A\) 和 \(B\)

\(\text{op(}A\text{) and op(}B\text{)} = \left\{ \begin{matrix} {A\text{ and }B} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A^{T}\text{ and }B^{T}} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_T}$}} \\ \end{matrix} \right.\)

当矩阵 B 以某种方式使得结果保证对称时，可以使用此例程。一个常见的例子是当矩阵 B 是矩阵 A 的缩放形式时：这等价于 B 是矩阵 A 和对角矩阵的乘积。

参数。	内存	输入/输出	含义
handle		输入	cuBLASXt API 上下文的句柄。
uplo		输入	指示矩阵 C 的下半部分或上半部分是否存储，另一个对称部分未被引用，而是从存储的元素推断出来的。
trans		输入	运算 op(A) 是非转置或转置。
n		输入	矩阵 op(A), op(B) 和 C 的行数。
k		输入	矩阵 op(A) 和 op(B) 的列数。
alpha	主机	输入	用于乘法的 <type> 标量。
A	主机或设备	输入	<type> 维度为 lda x k 的数组，如果 transa == CUBLAS_OP_N，则 lda >= max(1, n)；否则，维度为 lda x n，且 lda >= max(1, k)。
lda		输入	用于存储矩阵 A 的二维数组的前导维度。
B	主机或设备	输入	<type> 维度为 ldb x k 的数组，如果 transb == CUBLAS_OP_N，则 ldb >= max(1, n)；否则，维度为 ldb x n，且 ldb >= max(1, k)。
ldb		输入	用于存储矩阵 B 的二维数组的前导维度。
beta	主机	输入	<type> 用于乘法的标量；如果 beta == 0，则 C 不必是有效输入。
C	主机或设备	输入/输出	<type> 维度为 ldc x n 的数组，且 ldc >= max(1, n)。
ldc		输入	用于存储矩阵 C 的二维数组的前导维度。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	参数 n < 0 或 k < 0
CUBLAS_STATUS_EXECUTION_FAILED	函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

ssyrk(), dsyrk(), csyrk(), zsyrk() 和

ssyr2k(), dsyr2k(), csyr2k(), zsyr2k()

4.4.7. cublasXt<t>herk()

cublasStatus_t cublasXtCherk(cublasXtHandle_t handle,
                           cublasFillMode_t uplo, cublasOperation_t trans,
                           int n, int k,
                           const float  *alpha,
                           const cuComplex       *A, int lda,
                           const float  *beta,
                           cuComplex       *C, int ldc)
cublasStatus_t cublasXtZherk(cublasXtHandle_t handle,
                           cublasFillMode_t uplo, cublasOperation_t trans,
                           int n, int k,
                           const double *alpha,
                           const cuDoubleComplex *A, int lda,
                           const double *beta,
                           cuDoubleComplex *C, int ldc)

此函数执行 Hermitian 秩- \(k\) 更新

\(C = \alpha\text{op}(A)\text{op}(A)^{H} + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以较低或较高模式存储的 Hermitian 矩阵，而 \(A\) 是维度为 \(\text{op}(A)\) \(n \times k\) 的矩阵。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{H} & {\text{if }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

参数。	内存	输入/输出	含义
handle		输入	cuBLASXt API 上下文的句柄。
uplo		输入	指示矩阵 C 存储的是下半部分还是上半部分，另一个 Hermitian 部分不被引用。
trans		输入	运算 op(A) 是非转置或（共轭）转置。
n		输入	矩阵 op(A) 和 C 的行数。
k		输入	矩阵 op(A) 的列数。
alpha	主机	输入	用于乘法的 <type> 标量。
A	主机或设备	输入	<type> 维度为 lda x k 的数组，如果 transa == CUBLAS_OP_N，则 lda >= max(1, n)；否则，维度为 lda x n，且 lda >= max(1, k)。
lda		输入	用于存储矩阵 A 的二维数组的前导维度。
beta	主机	输入	用于乘法的 <type> 标量，如果 beta == 0，则 C 不必是有效的输入。
C	主机或设备	输入/输出	<type> 维度为 ldc x n 的数组，且 ldc >= max(1, n)。 假定对角元素的虚部为零并设置为零。
ldc		输入	用于存储矩阵 C 的二维数组的前导维度。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	参数 n < 0 或 k < 0
CUBLAS_STATUS_EXECUTION_FAILED	函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

cherk(), zherk()

4.4.8. cublasXt<t>her2k()

cublasStatus_t cublasXtCher2k(cublasXtHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            size_t n, size_t k,
                            const cuComplex       *alpha,
                            const cuComplex       *A, size_t lda,
                            const cuComplex       *B, size_t ldb,
                            const float  *beta,
                            cuComplex       *C, size_t ldc)
cublasStatus_t cublasXtZher2k(cublasXtHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            size_t n, size_t k,
                            const cuDoubleComplex *alpha,
                            const cuDoubleComplex *A, size_t lda,
                            const cuDoubleComplex *B, size_t ldb,
                            const double *beta,
                            cuDoubleComplex *C, size_t ldc)

此函数执行 Hermitian 秩- \(2k\) 更新

\(C = \alpha\text{op}(A)\text{op}(B)^{H} + \overset{ˉ}{\alpha}\text{op}(B)\text{op}(A)^{H} + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以较低或较高模式存储的 Hermitian 矩阵，而 \(A\) 和 \(B\) 分别是维度为 \(\text{op}(A)\) \(n \times k\) 和 \(\text{op}(B)\) \(n \times k\) 的矩阵。 此外，对于矩阵 \(A\) 和 \(B\)

\(\text{op(}A\text{) and op(}B\text{)} = \left\{ \begin{matrix} {A\text{ and }B} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A^{H}\text{ and }B^{H}} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

参数。	内存	输入/输出	含义
handle		输入	cuBLASXt API 上下文的句柄。
uplo		输入	指示矩阵 C 存储的是下半部分还是上半部分，另一个 Hermitian 部分不被引用。
trans		输入	运算 op(A) 是非转置或（共轭）转置。
n		输入	矩阵 op(A), op(B) 和 C 的行数。
k		输入	矩阵 op(A) 和 op(B) 的列数。
alpha	主机	输入	用于乘法的 <type> 标量。
A	主机或设备	输入	<type> 维度为 lda x k 的数组，如果 transa == CUBLAS_OP_N，则 lda >= max(1, n)；否则，维度为 lda x n，且 lda >= max(1, k)。
lda		输入	用于存储矩阵 A 的二维数组的前导维度。
B	主机或设备	输入	<type> 维度为 ldb x k 的数组，如果 transb == CUBLAS_OP_N，则 ldb >= max(1, n)；否则，维度为 ldb x n，且 ldb >= max(1, k)。
ldb		输入	用于存储矩阵 B 的二维数组的前导维度。
beta	主机	输入	用于乘法的 <type> 标量，如果 beta == 0，则 C 不必是有效的输入。
C	主机或设备	输入/输出	<type> 维度为 ldc x n 的数组，且 ldc >= max(1, n)。 假定对角元素的虚部为零并设置为零。
ldc		输入	用于存储矩阵 C 的二维数组的前导维度。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	参数 n < 0 或 k < 0
CUBLAS_STATUS_EXECUTION_FAILED	函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

cher2k(), zher2k()

4.4.9. cublasXt<t>herkx()

cublasStatus_t cublasXtCherkx(cublasXtHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            size_t n, size_t k,
                            const cuComplex       *alpha,
                            const cuComplex       *A, size_t lda,
                            const cuComplex       *B, size_t ldb,
                            const float  *beta,
                            cuComplex       *C, size_t ldc)
cublasStatus_t cublasXtZherkx(cublasXtHandle_t handle,
                            cublasFillMode_t uplo, cublasOperation_t trans,
                            size_t n, size_t k,
                            const cuDoubleComplex *alpha,
                            const cuDoubleComplex *A, size_t lda,
                            const cuDoubleComplex *B, size_t ldb,
                            const double *beta,
                            cuDoubleComplex *C, size_t ldc)

此函数执行 Hermitian 秩- \(k\) 更新的变体

\(C = \alpha\text{op}(A)\text{op}(B)^{H} + \beta C\)

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以较低或较高模式存储的 Hermitian 矩阵，而 \(A\) 和 \(B\) 分别是维度为 \(\text{op}(A)\) \(n \times k\) 和 \(\text{op}(B)\) \(n \times k\) 的矩阵。 此外，对于矩阵 \(A\) 和 \(B\)

\(\text{op(}A\text{) and op(}B\text{)} = \left\{ \begin{matrix} {A\text{ and }B} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A^{H}\text{ and }B^{H}} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

当矩阵 B 以某种方式使得结果保证 Hermitian 时，可以使用此例程。一个常见的例子是当矩阵 B 是矩阵 A 的缩放形式时：这等价于 B 是矩阵 A 和对角矩阵的乘积。

参数。	内存	输入/输出	含义
handle		输入	cuBLASXt API 上下文的句柄。
uplo		输入	指示矩阵 C 存储的是下半部分还是上半部分，另一个 Hermitian 部分不被引用。
trans		输入	运算 op(A) 是非转置或（共轭）转置。
n		输入	矩阵 op(A), op(B) 和 C 的行数。
k		输入	矩阵 op(A) 和 op(B) 的列数。
alpha	主机	输入	用于乘法的 <type> 标量。
A	主机或设备	输入	<type> 维度为 lda x k 的数组，如果 transa == CUBLAS_OP_N，则 lda >= max(1, n)；否则，维度为 lda x n，且 lda >= max(1, k)。
lda		输入	用于存储矩阵 A 的二维数组的前导维度。
B	主机或设备	输入	<type> 维度为 ldb x k 的数组，如果 transb == CUBLAS_OP_N，则 ldb >= max(1, n)；否则，维度为 ldb x n，且 ldb >= max(1, k)。
ldb		输入	用于存储矩阵 B 的二维数组的前导维度。
beta	主机	输入	用于乘法的实数标量；如果 beta == 0，则 C 不必是有效输入。
C	主机或设备	输入/输出	<type> 维度为 ldc x n 的数组，且 ldc >= max(1, n)。 假定对角元素的虚部为零并设置为零。
ldc		输入	用于存储矩阵 C 的二维数组的前导维度。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	参数 n < 0 或 k < 0
CUBLAS_STATUS_EXECUTION_FAILED	函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

cherk(), zherk() 和

cher2k(), zher2k()

4.4.10. cublasXt<t>trsm()

cublasStatus_t cublasXtStrsm(cublasXtHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasXtDiagType_t diag,
                           size_t m, size_t n,
                           const float           *alpha,
                           const float           *A, size_t lda,
                           float           *B, size_t ldb)
cublasStatus_t cublasXtDtrsm(cublasXtHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasXtDiagType_t diag,
                           size_t m, size_t n,
                           const double          *alpha,
                           const double          *A, size_t lda,
                           double          *B, size_t ldb)
cublasStatus_t cublasXtCtrsm(cublasXtHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasXtDiagType_t diag,
                           size_t m, size_t n,
                           const cuComplex       *alpha,
                           const cuComplex       *A, size_t lda,
                           cuComplex       *B, size_t ldb)
cublasStatus_t cublasXtZtrsm(cublasXtHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasXtDiagType_t diag,
                           size_t m, size_t n,
                           const cuDoubleComplex *alpha,
                           const cuDoubleComplex *A, size_t lda,
                           cuDoubleComplex *B, size_t ldb)

此函数求解具有多个右侧的三角线性系统

\(\left\{ \begin{matrix} {\text{op}(A)X = \alpha B} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ {X\text{op}(A) = \alpha B} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_RIGHT}$}} \\ \end{matrix} \right.\)

其中 \(A\) 是以较低或较高模式存储的三角矩阵，可以带或不带主对角线，\(X\) 和 \(B\) 是 \(m \times n\) 矩阵，而 \(\alpha\) 是标量。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ A^{H} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

解 \(X\) 在退出时覆盖右侧 \(B\)。

此函数中不包含对奇异性或近奇异性的测试。

参数。	内存	输入/输出	含义
handle		输入	cuBLASXt API 上下文的句柄。
side		输入	指示矩阵 A 在 X 的左侧还是右侧。
uplo		输入	指示矩阵 A 存储的是下半部分还是上半部分，另一部分不被引用，并从存储的元素中推断出来。
trans		输入	运算 op(A) 是非转置或（共轭）转置。
diag		输入	指示矩阵 A 主对角线上的元素是否为单位元素，并且不应被访问。
m		输入	矩阵 B 的行数，矩阵 A 的大小相应调整。
n		输入	矩阵 B 的列数，矩阵 A 的大小相应调整。
alpha	主机	输入	<type> 用于乘法的标量，如果 alpha == 0，则不引用 A，并且 B 不必是有效的输入。
A	主机或设备	输入	维度为 lda x m 的 <type> 数组，如果 side == CUBLAS_SIDE_LEFT，则 lda >= max(1, m)；如果不是，则维度为 lda x n，且 lda >= max(1, n)。
lda		输入	用于存储矩阵 A 的二维数组的前导维度。
B	主机或设备	输入/输出	<type> 数组。 它的维度为 ldb x n，且 ldb >= max(1, m)。
ldb		输入	用于存储矩阵 B 的二维数组的前导维度。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	参数 m < 0 或 n < 0
CUBLAS_STATUS_EXECUTION_FAILED	函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

strsm(), dtrsm(), ctrsm(), ztrsm()

4.4.11. cublasXt<t>trmm()

cublasStatus_t cublasXtStrmm(cublasXtHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           size_t m, size_t n,
                           const float           *alpha,
                           const float           *A, size_t lda,
                           const float           *B, size_t ldb,
                           float                 *C, size_t ldc)
cublasStatus_t cublasXtDtrmm(cublasXtHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           size_t m, size_t n,
                           const double          *alpha,
                           const double          *A, size_t lda,
                           const double          *B, size_t ldb,
                           double                *C, size_t ldc)
cublasStatus_t cublasXtCtrmm(cublasXtHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           size_t m, size_t n,
                           const cuComplex       *alpha,
                           const cuComplex       *A, size_t lda,
                           const cuComplex       *B, size_t ldb,
                           cuComplex             *C, size_t ldc)
cublasStatus_t cublasXtZtrmm(cublasXtHandle_t handle,
                           cublasSideMode_t side, cublasFillMode_t uplo,
                           cublasOperation_t trans, cublasDiagType_t diag,
                           size_t m, size_t n,
                           const cuDoubleComplex *alpha,
                           const cuDoubleComplex *A, size_t lda,
                           const cuDoubleComplex *B, size_t ldb,
                           cuDoubleComplex       *C, size_t ldc)

此函数执行三角矩阵-矩阵乘法

\(C = \left\{ \begin{matrix} {\alpha\text{op}(A)B} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ {\alpha B\text{op}(A)} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_RIGHT}$}} \\ \end{matrix} \right.\)

其中 \(A\) 是以较低或较高模式存储的三角矩阵，可以带或不带主对角线，\(B\) 和 \(C\) 是 \(m \times n\) 矩阵，而 \(\alpha\) 是标量。 此外，对于矩阵 \(A\)

\(\text{op}(A) = \left\{ \begin{matrix} A & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ A^{H} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

请注意，为了实现更好的并行性，与 cuBLAS API 类似，cuBLASXt API 在此例程中与 BLAS API 不同。BLAS API 假定就地实现（结果写回 B），而 cuBLASXt API 假定异地实现（结果写入 C）。应用程序仍然可以通过将矩阵 B 的地址传递到矩阵 C 的位置，在 cuBLASXt API 中获得 BLAS 的就地功能。不支持输入参数中的其他重叠。

参数。	内存	输入/输出	含义
handle		输入	cuBLASXt API 上下文的句柄。
side		输入	指示矩阵 A 在 B 的左侧还是右侧。
uplo		输入	指示矩阵 A 存储的是下半部分还是上半部分，另一部分不被引用，并从存储的元素中推断出来。
trans		输入	运算 op(A) 是非转置或（共轭）转置。
diag		输入	指示矩阵 A 主对角线上的元素是否为单位元素，并且不应被访问。
m		输入	矩阵 B 的行数，矩阵 A 的大小相应调整。
n		输入	矩阵 B 的列数，矩阵 A 的大小相应调整。
alpha	主机	输入	<type> 用于乘法的标量；如果 alpha，则不引用 A，并且 B 不必是有效输入。
A	主机或设备	输入	维度为 lda x m 的 <type> 数组，如果 side == CUBLAS_SIDE_LEFT，则 lda >= max(1, m)；如果不是，则维度为 lda x n，且 lda >= max(1, n)。
lda		输入	用于存储矩阵 A 的二维数组的前导维度。
B	主机或设备	输入	维度为 ldb x n 的 <type> 数组，且 ldb >= max(1, m)。
ldb		输入	用于存储矩阵 B 的二维数组的前导维度。
C	主机或设备	输入/输出	维度为 ldc x n 的 <type> 数组，且 ldc >= max(1, m)。
ldc		输入	用于存储矩阵 C 的二维数组的前导维度。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	参数 m < 0 或 n < 0
CUBLAS_STATUS_EXECUTION_FAILED	函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

strmm(), dtrmm(), ctrmm(), ztrmm()

4.4.12. cublasXt<t>spmm()

cublasStatus_t cublasXtSspmm( cublasXtHandle_t handle,
                                cublasSideMode_t side,
                                cublasFillMode_t uplo,
                                size_t m,
                                size_t n,
                                const float *alpha,
                                const float *AP,
                                const float *B,
                                size_t ldb,
                                const float *beta,
                                float *C,
                                size_t ldc );

cublasStatus_t cublasXtDspmm( cublasXtHandle_t handle,
                                cublasSideMode_t side,
                                cublasFillMode_t uplo,
                                size_t m,
                                size_t n,
                                const double *alpha,
                                const double *AP,
                                const double *B,
                                size_t ldb,
                                const double *beta,
                                double *C,
                                size_t ldc );

cublasStatus_t cublasXtCspmm( cublasXtHandle_t handle,
                                cublasSideMode_t side,
                                cublasFillMode_t uplo,
                                size_t m,
                                size_t n,
                                const cuComplex *alpha,
                                const cuComplex *AP,
                                const cuComplex *B,
                                size_t ldb,
                                const cuComplex *beta,
                                cuComplex *C,
                                size_t ldc );

cublasStatus_t cublasXtZspmm( cublasXtHandle_t handle,
                                cublasSideMode_t side,
                                cublasFillMode_t uplo,
                                size_t m,
                                size_t n,
                                const cuDoubleComplex *alpha,
                                const cuDoubleComplex *AP,
                                const cuDoubleComplex *B,
                                size_t ldb,
                                const cuDoubleComplex *beta,
                                cuDoubleComplex *C,
                                size_t ldc );

此函数执行对称压缩矩阵-矩阵乘法

\(C = \left\{ \begin{matrix} {\alpha AB + \beta C} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ {\alpha BA + \beta C} & {\text{if }\textsf{side == $\mathrm{CUBLAS\_SIDE\_RIGHT}$}} \\ \end{matrix} \right.\)

其中 \(A\) 是以压缩格式存储的 \(n \times n\) 对称矩阵，\(B\) 和 \(C\) 是 \(m \times n\) 矩阵，\(\alpha\) 和 \(\beta\) 是标量。

其中 \(A\) 是以压缩格式存储的 \(n \times n\) 对称矩阵， \(\mathbf{x}\) 和 \(\mathbf{y}\) 是向量， \(\alpha\) 和 \(\beta\) 是标量。

如果 uplo == CUBLAS_FILL_MODE_LOWER，则对称矩阵 \(A\) 的下三角部分中的元素按列无间隙地压缩在一起，因此元素 \(A(i,j)\) 存储在内存位置 AP[i+((2*n-j+1)*j)/2] 中，对于 \(j = 1,\ldots,n\) 和 \(i \geq j\) 。因此，压缩格式仅需要 \(\frac{n(n + 1)}{2}\) 个元素用于存储。

注意

压缩矩阵 AP 必须位于主机或托管内存上，而其他矩阵可以位于主机或任何 GPU 设备上。

参数。	内存	输入/输出	含义
handle		输入	cuBLASXt API 上下文的句柄。
side		输入	指示矩阵 A 在 B 的左侧还是右侧。
uplo		输入	指示矩阵 A 的下半部分或上半部分是否存储，另一个对称部分未被引用，而是从存储的元素推断出来的。
m		输入	矩阵 A 和 B 的行数，矩阵 A 的大小也相应调整。
n		输入	矩阵 C 和 A 的列数，矩阵 A 的大小也相应调整。
alpha	主机	输入	用于乘法的 <type> 标量。
矩阵 \(A\) 的行数和列数。	主机	输入	AP
B	主机或设备	输入	维度为 ldb x n 的 <type> 数组，且 ldb >= max(1, m)。
ldb		输入	用于存储矩阵 B 的二维数组的前导维度。
beta	主机	输入	用于乘法的 <type> 标量，如果 beta == 0，则 C 不必是有效的输入。
C	主机或设备	输入/输出	维度为 ldc x n 的 <type> 数组，且 ldc >= max(1, m)。
ldc		输入	用于存储矩阵 C 的二维数组的前导维度。

下表列出了此函数可能返回的错误值及其含义。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	参数 m < 0 或 n < 0
CUBLAS_STATUS_NOT_SUPPORTED	矩阵 AP 位于 GPU 设备上。
CUBLAS_STATUS_EXECUTION_FAILED	函数无法在 GPU 上启动

有关参考，请参阅 NETLIB 文档

ssymm(), dsymm(), csymm(), zsymm()

5. 使用 cuBLASDx API

cuBLASDx 库（预览版）是设备端 API 扩展，用于在 CUDA 内核中执行 BLAS 计算。通过融合数值运算，您可以减少延迟并进一步提高应用程序的性能。

• 您可以在这里访问 cuBLASDx 文档。

• cuBLASDx 不是 CUDA 工具包的一部分。您可以从这里单独下载 cuBLASDx。

6. 使用 cuBLAS Legacy API

本节不提供每个 Legacy API 数据类型和入口点的完整参考。相反，它描述了如何使用 API，特别是与常规 cuBLAS API 的不同之处。

请注意，在本节中，所有对 “cuBLAS Library” 的引用仅指 Legacy cuBLAS API。

警告

旧版 cuBLAS API 已弃用，将在未来的版本中删除。

6.1. 错误状态

cublasStatus 类型用于函数状态返回。cuBLAS Library 辅助函数直接返回状态，而核心函数的状态可以使用 cublasGetError() 检索。请注意，通过 cublasGetError() 读取错误状态会将内部错误状态重置为 CUBLAS_STATUS_SUCCESS。目前，定义了以下值：

值	含义
CUBLAS_STATUS_SUCCESS	操作已成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_ALLOC_FAILED	资源分配失败
CUBLAS_STATUS_INVALID_VALUE	使用了无效的数值作为参数
CUBLAS_STATUS_ARCH_MISMATCH	需要不存在的设备架构特性
CUBLAS_STATUS_MAPPING_ERROR	访问 GPU 内存空间失败
CUBLAS_STATUS_EXECUTION_FAILED	GPU 程序执行失败
CUBLAS_STATUS_INTERNAL_ERROR	内部操作失败
CUBLAS_STATUS_NOT_SUPPORTED	所需的功能不受支持

此旧版类型对应于 cuBLAS 库 API 中的类型 cublasStatus_t。

6.2. 初始化和关闭

函数 cublasInit() 和 cublasShutdown() 用于初始化和关闭 cuBLAS 库。建议在调用任何其他函数之前调用 cublasInit()。它在当前绑定到从中调用它的主机线程的 GPU 设备上分配硬件资源。

旧版的初始化和关闭函数类似于 cuBLAS 库 API 例程 cublasCreate() 和 cublasDestroy()。

6.3. 线程安全

当与多个主机线程和设备一起使用时，旧版 API 不是线程安全的。建议仅在需要与 Fortran 的最大兼容性，并且使用单个主机线程来设置库并进行所有函数调用时使用。

6.4. 内存管理

旧版 cuBLAS 库 API 使用的内存分别使用函数 cublasAlloc() 和 cublasFree() 分配和释放。这些函数在 GPU 内存空间中创建和销毁一个对象，该对象能够容纳 n 个元素的数组，其中每个元素需要 elemSize 字节的存储空间。有关这些函数的原型，请参阅旧版 cuBLAS API 头文件 “cublas.h”。

函数 cublasAlloc() 是函数 cudaMalloc() 的包装器，因此 cublasAlloc() 返回的设备指针可以传递给任何 CUDA™ 设备内核函数。但是，这些设备指针不能在主机代码中解引用。函数 cublasFree() 是函数 cudaFree() 的包装器。

6.5. 标量参数

在旧版 cuBLAS API 中，标量参数通过值从主机传递。此外，少数返回标量结果的函数，例如 dot() 和 nrm2()，在主机上返回结果值，因此这些例程将等待设备上的内核执行完成，然后才返回，这使得与流的并行性不切实际。但是，为了与 Fortran 和现有的 BLAS 库更加兼容，大多数函数不返回任何值。

6.6. 辅助函数

在本节中，我们列出了旧版 cuBLAS API 提供的辅助函数及其功能。有关这些函数的精确原型，请参阅旧版 cuBLAS API 头文件 “cublas.h”。

辅助函数	含义
cublasInit()	初始化库
cublasShutdown()	关闭库
cublasGetError()	检索库的错误状态
cublasSetKernelStream()	设置库要使用的流
cublasAlloc()	为库分配设备内存
cublasFree()	释放为库分配的设备内存
cublasSetVector()	将主机上的向量 x 复制到 GPU 上的向量
cublasGetVector()	将 GPU 上的向量 x 复制到主机上的向量
cublasSetMatrix()	将主机上矩阵的 \(m \times n\) 分块复制到 GPU
cublasGetMatrix()	将 GPU 上矩阵的 \(m \times n\) 分块复制到主机
cublasSetVectorAsync()	类似于 cublasSetVector()，但复制是异步的
cublasGetVectorAsync()	类似于 cublasGetVector()，但复制是异步的
cublasSetMatrixAsync()	类似于 cublasSetMatrix()，但复制是异步的
cublasGetMatrixAsync()	类似于 cublasGetMatrix()，但复制是异步的

6.7. Level-1,2,3 函数

Level-1,2,3 cuBLAS 函数（也称为核心函数）与本文档第 3、4 和 5 章中列出的函数具有相同的名称和行为。有关其精确原型，请参阅旧版 cuBLAS API 头文件 “cublas.h”。此外，下一节将更多地讨论旧版和 cuBLAS API 原型之间的差异，更具体地说是如何将函数调用从一个 API 转换为另一个 API。

6.8. 将 Legacy API 转换为 cuBLAS API

有一些通用规则可用于从旧版 API 转换为 cuBLAS API

• 将头文件 “cublas.h” 替换为 “cublas_v2.h”。

• 将类型 cublasStatus 替换为 cublasStatus_t。

• 将函数 cublasSetKernelStream() 替换为 cublasSetStream()。

• 分别将函数 cublasAlloc() 和 cublasFree() 替换为 cudaMalloc() 和 cudaFree()。请注意，cudaMalloc() 期望以字节为单位提供分配的内存大小（通常只需提供 n x elemSize 即可分配 n 个元素，每个元素的大小为 elemSize 字节）。

• 声明 cublasHandle_t cuBLAS 库句柄。

• 使用 cublasCreate() 初始化句柄。此外，完成后使用 cublasDestroy() 释放句柄。

• 将句柄添加为所有 cuBLAS 库函数调用的第一个参数。

• 将标量参数更改为按引用传递，而不是按值传递（通常只需在 C/C++ 中添加 “&” 符号就足够了，因为参数在主机上默认按引用传递）。但是，请注意，如果例程以异步方式运行，则在例程调度的内核完成之前，不能更改保存标量参数的变量。有关如何使用流的详细讨论，请参阅 CUDA C++ Programming Guide。

• 分别将参数字符 N 或 n（非转置操作）、T 或 t（转置操作）和 C 或 c（共轭转置操作）更改为 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C。

• 分别将参数字符 L 或 l（填充下半部分）和 U 或 u（填充上半部分）更改为 CUBLAS_FILL_MODE_LOWER 和 CUBLAS_FILL_MODE_UPPER。

• 分别将参数字符 N 或 n（非单位对角线）和 U 或 u（单位对角线）更改为 CUBLAS_DIAG_NON_UNIT 和 CUBLAS_DIAG_UNIT。

• 分别将参数字符 L 或 l（左侧）和 R 或 r（右侧）更改为 CUBLAS_SIDE_LEFT 和 CUBLAS_SIDE_RIGHT。

• 如果旧版 API 函数返回标量值，则添加一个相同类型的额外标量参数，该参数按引用传递，作为同一函数的最后一个参数。

• 使用函数本身的返回值来检查错误，而不是使用 cublasGetError()。

• 最后，请使用头文件 cublas.h 和 cublas_v2.h 中的函数原型来检查代码的正确性。

6.9. 示例

有关使用旧版 cuBLAS API 的示例代码参考，请参见以下两个示例。它们展示了一个使用旧版 cuBLAS 库 API 和两种索引样式（示例 A.1. “使用 C 和 cuBLAS 的应用程序：基于 1 的索引” 和示例 A.2. “使用 C 和 cuBLAS 的应用程序：基于 0 的索引”）用 C 编写的应用程序。此应用程序类似于简介章节中显示的，使用 cuBLAS 库 API 的应用程序。

示例 A.1. 使用 C 和 cuBLAS 的应用程序：基于 1 的索引

//-----------------------------------------------------------
#include <stdio.h>
#include <stdlib.h>
#include <math.h>
#include "cublas.h"
#define M 6
#define N 5
#define IDX2F(i,j,ld) ((((j)-1)*(ld))+((i)-1))

static __inline__ void modify (float *m, int ldm, int n, int p, int q, float alpha, float beta){
    cublasSscal (n-q+1, alpha, &m[IDX2F(p,q,ldm)], ldm);
    cublasSscal (ldm-p+1, beta, &m[IDX2F(p,q,ldm)], 1);
}

int main (void){
    int i, j;
    cublasStatus stat;
    float* devPtrA;
    float* a = 0;
    a = (float *)malloc (M * N * sizeof (*a));
    if (!a) {
        printf ("host memory allocation failed");
        return EXIT_FAILURE;
    }
    for (j = 1; j <= N; j++) {
        for (i = 1; i <= M; i++) {
            a[IDX2F(i,j,M)] = (float)((i-1) * M + j);
        }
    }
    cublasInit();
    stat = cublasAlloc (M*N, sizeof(*a), (void**)&devPtrA);
    if (stat != cuBLAS_STATUS_SUCCESS) {
        printf ("device memory allocation failed");
        cublasShutdown();
        return EXIT_FAILURE;
    }
    stat = cublasSetMatrix (M, N, sizeof(*a), a, M, devPtrA, M);
    if (stat != cuBLAS_STATUS_SUCCESS) {
        printf ("data download failed");
        cublasFree (devPtrA);
        cublasShutdown();
        return EXIT_FAILURE;
    }
    modify (devPtrA, M, N, 2, 3, 16.0f, 12.0f);
    stat = cublasGetMatrix (M, N, sizeof(*a), devPtrA, M, a, M);
    if (stat != cuBLAS_STATUS_SUCCESS) {
        printf ("data upload failed");
        cublasFree (devPtrA);
        cublasShutdown();
        return EXIT_FAILURE;
    }
    cublasFree (devPtrA);
    cublasShutdown();
    for (j = 1; j <= N; j++) {
        for (i = 1; i <= M; i++) {
            printf ("%7.0f", a[IDX2F(i,j,M)]);
        }
        printf ("\n");
    }
    free(a);
    return EXIT_SUCCESS;
}

示例 A.2. 使用 C 和 cuBLAS 的应用程序：基于 0 的索引

//-----------------------------------------------------------
#include <stdio.h>
#include <stdlib.h>
#include <math.h>
#include "cublas.h"
#define M 6
#define N 5
#define IDX2C(i,j,ld) (((j)*(ld))+(i))

static __inline__ void modify (float *m, int ldm, int n, int p, int q, float alpha, float beta){
    cublasSscal (n-q, alpha, &m[IDX2C(p,q,ldm)], ldm);
    cublasSscal (ldm-p, beta, &m[IDX2C(p,q,ldm)], 1);
}

int main (void){
    int i, j;
    cublasStatus stat;
    float* devPtrA;
    float* a = 0;
    a = (float *)malloc (M * N * sizeof (*a));
    if (!a) {
        printf ("host memory allocation failed");
        return EXIT_FAILURE;
    }
    for (j = 0; j < N; j++) {
        for (i = 0; i < M; i++) {
            a[IDX2C(i,j,M)] = (float)(i * M + j + 1);
        }
    }
    cublasInit();
    stat = cublasAlloc (M*N, sizeof(*a), (void**)&devPtrA);
    if (stat != cuBLAS_STATUS_SUCCESS) {
        printf ("device memory allocation failed");
        cublasShutdown();
        return EXIT_FAILURE;
    }
    stat = cublasSetMatrix (M, N, sizeof(*a), a, M, devPtrA, M);
    if (stat != cuBLAS_STATUS_SUCCESS) {
        printf ("data download failed");
        cublasFree (devPtrA);
        cublasShutdown();
        return EXIT_FAILURE;
    }
    modify (devPtrA, M, N, 1, 2, 16.0f, 12.0f);
    stat = cublasGetMatrix (M, N, sizeof(*a), devPtrA, M, a, M);
    if (stat != cuBLAS_STATUS_SUCCESS) {
        printf ("data upload failed");
        cublasFree (devPtrA);
        cublasShutdown();
        return EXIT_FAILURE;
    }
    cublasFree (devPtrA);
    cublasShutdown();
    for (j = 0; j < N; j++) {
        for (i = 0; i < M; i++) {
            printf ("%7.0f", a[IDX2C(i,j,M)]);
        }
        printf ("\n");
    }
    free(a);
    return EXIT_SUCCESS;
}

7. cuBLAS Fortran 绑定

cuBLAS 库是使用基于 C 的 CUDA 工具链实现的。因此，它提供了 C 风格的 API。这使得与用 C 和 C++ 编写的应用程序的接口变得简单，但该库也可以被用 Fortran 编写的应用程序使用。特别是，cuBLAS 库使用基于 1 的索引和 Fortran 风格的列优先存储来存储多维数据，以简化与 Fortran 应用程序的接口。不幸的是，Fortran 到 C 的调用约定没有标准化，并且因平台和工具链而异。特别是，以下方面可能存在差异：

• 符号名称（大小写，名称修饰）

• 参数传递（按值或按引用）

• 字符串参数的传递（长度信息）

• 指针参数的传递（指针的大小）

• 返回浮点或复合数据类型（例如单精度或复数数据类型）

为了在解决这些差异时提供最大的灵活性，cuBLAS Fortran 接口以包装器函数的形式提供，并且是工具包交付的一部分。这些包装器函数的 C 源代码位于 src 目录中，并以两种不同的形式提供：

• thunking 包装器接口，位于文件 fortran_thunking.c 中

• 直接包装器接口，位于文件 fortran.c 中

需要将这两个文件之一的代码编译到应用程序中，以便它可以调用 cuBLAS API 函数。提供源代码允许用户为特定平台和工具链进行任何必要的更改。

这两个 C 文件中的代码已用于演示与以下编译器的互操作性：32 位 Linux 上的 g77 3.2.3 和 g95 0.91、64 位 Linux 上的 g77 3.4.5 和 g95 0.91、32 位和 64 位 Microsoft Windows XP 上的 Intel Fortran 9.0 和 Intel Fortran 10.0 以及 Mac OS X 上的 g77 3.4.0 和 g95 0.92。

请注意，对于 g77，需要使用编译器标志 -fno-second-underscore 才能按提供的形式使用这些包装器。此外，期望使用关于参数和返回值传递的默认调用约定。使用标志 -fno-f2c 会更改关于这两项的默认调用约定。

thunking 包装器允许与现有的 Fortran 应用程序接口，而无需对应用程序进行任何更改。在每次调用期间，包装器分配 GPU 内存，将源数据从 CPU 内存空间复制到 GPU 内存空间，调用 cuBLAS，最后将结果复制回 CPU 内存空间并释放 GPU 内存。由于此过程会导致非常显著的调用开销，因此这些包装器旨在用于轻量级测试，而不是用于生产代码。要使用 thunking 包装器，需要使用文件 fortran_thunking.c 编译应用程序。

直接包装器旨在用于生产代码，它在所有 BLAS 函数中用设备指针替换向量和矩阵参数。要使用这些接口，需要稍微修改现有应用程序，以在 GPU 内存空间中分配和释放数据结构（使用 cuBLAS_ALLOC 和 cuBLAS_FREE），并在 GPU 和 CPU 内存空间之间复制数据（使用 cuBLAS_SET_VECTOR、cuBLAS_GET_VECTOR、cuBLAS_SET_MATRIX 和 cuBLAS_GET_MATRIX）。fortran.c 中提供的示例包装器将设备指针映射到操作系统相关的类型 size_t，该类型在 32 位平台上为 32 位宽，在 64 位平台上为 64 位宽。

处理 Fortran 代码中设备指针上的索引算术的一种方法是使用 C 风格的宏，并使用 C 预处理器来扩展这些宏，如下例所示。在 Linux 和 Mac OS X 上，预处理的一种方法是在使用 g77 编译器时使用选项 -E -x f77-cpp-input，或者在使用 g95 或 gfortran 时仅使用选项 -cpp。在带有 Microsoft Visual C/C++ 的 Windows 平台上，使用 ‘cl -EP’ 可以达到类似的结果。

! Example B.1. Fortran 77 Application Executing on the Host
! ----------------------------------------------------------
    subroutine modify ( m, ldm, n, p, q, alpha, beta )
    implicit none
    integer ldm, n, p, q
    real*4 m (ldm, *) , alpha , beta
    external cublas_sscal
    call cublas_sscal (n-p+1, alpha , m(p,q), ldm)
    call cublas_sscal (ldm-p+1, beta, m(p,q), 1)
    return
    end

    program matrixmod
    implicit none
    integer M,N
    parameter (M=6, N=5)
    real*4 a(M,N)
    integer i, j
    external cublas_init
    external cublas_shutdown

    do j = 1, N
        do i = 1, M
            a(i, j) = (i-1)*M + j
        enddo
    enddo
    call cublas_init
    call modify ( a, M, N, 2, 3, 16.0, 12.0 )
    call cublas_shutdown
    do j = 1 , N
        do i = 1 , M
            write(*,"(F7.0$)") a(i,j)
        enddo
        write (*,*) ""
    enddo
    stop
    end

当传统的固定格式 Fortran 77 代码移植为使用 cuBLAS 库时，当 BLAS 调用交换为 cuBLAS 调用时，行长度通常会增加。更长的函数名称和可能的宏扩展是促成因素。不小心超过最大行长度可能会导致难以找到的运行时错误，因此如果保留固定格式，则应注意不要超过 72 列的限制。

本章中的示例展示了一个在主机上用 Fortran 77 实现的小型应用程序，以及在使用非 thunking 包装器移植到使用 cuBLAS 库之后的相同应用程序。

第二个示例应该在 64 位操作系统上编译时将 ARCH_64 定义为 1，在 32 位操作系统上编译时定义为 0。例如，对于 g95 或 gfortran，这可以直接在命令行上使用选项 -cpp -DARCH_64=1 完成。

! Example B.2. Same Application Using Non-thunking cuBLAS Calls
!-------------------------------------------------------------
#define IDX2F (i,j,ld) ((((j)-1)*(ld))+((i)-1))
    subroutine modify ( devPtrM, ldm, n, p, q, alpha, beta )
    implicit none
    integer sizeof_real
    parameter (sizeof_real=4)
    integer ldm, n, p, q
#if ARCH_64
    integer*8 devPtrM
#else
    integer*4 devPtrM
#endif
    real*4 alpha, beta
    call cublas_sscal ( n-p+1, alpha,
    1                   devPtrM+IDX2F(p, q, ldm)*sizeof_real,
    2                   ldm)
    call cublas_sscal(ldm-p+1, beta,
    1                 devPtrM+IDX2F(p, q, ldm)*sizeof_real,
    2                 1)
    return
    end
    program matrixmod
    implicit none
    integer M,N,sizeof_real
#if ARCH_64
    integer*8 devPtrA
#else
    integer*4 devPtrA
#endif
    parameter(M=6,N=5,sizeof_real=4)
    real*4 a(M,N)
    integer i,j,stat
    external cublas_init, cublas_set_matrix, cublas_get_matrix
    external cublas_shutdown, cublas_alloc
    integer cublas_alloc, cublas_set_matrix, cublas_get_matrix
    do j=1,N
        do i=1,M
            a(i,j)=(i-1)*M+j
        enddo
    enddo
    call cublas_init
    stat= cublas_alloc(M*N, sizeof_real, devPtrA)
    if (stat.NE.0) then
        write(*,*) "device memory allocation failed"
        call cublas_shutdown
        stop
    endif
    stat = cublas_set_matrix(M,N,sizeof_real,a,M,devPtrA,M)
    if (stat.NE.0) then
        call cublas_free( devPtrA )
        write(*,*) "data download failed"
        call cublas_shutdown
        stop
    endif

—

— 代码块在下面继续。为了格式化目的添加了空格。 —

—

call modify(devPtrA, M, N, 2, 3, 16.0, 12.0)
stat = cublas_get_matrix(M, N, sizeof_real, devPtrA, M, a, M )
if (stat.NE.0) then
call cublas_free ( devPtrA )
write(*,*) "data upload failed"
call cublas_shutdown
stop
endif
call cublas_free ( devPtrA )
call cublas_shutdown
do j = 1 , N
    do i = 1 , M
        write (*,"(F7.0$)") a(i,j)
    enddo
    write (*,*) ""
enddo
stop
end

8. 与其他库和工具的交互

本节介绍了重要的要求和建议，这些要求和建议确保 cuBLAS 与其他库和实用程序正确使用。

8.1. nvprune

nvprune 允许修剪可重定位的主机对象和静态库，使其仅包含特定目标架构的设备代码。对于 cuBLAS，如果将 nvprune 与计算能力一起使用，并且计算能力的次要修订号与 0 不同，则必须特别注意。为了减小二进制文件大小，对于在不同次要修订版本之间重用的内核，cuBLAS 可能仅存储 CUDA 二进制文件的主修订等效项。因此，为了确保修剪后的库不会因任意问题而失败，用户必须在其主要架构中保留选定架构和所有先前次要架构的二进制文件。

例如，以下调用修剪 libcublas_static.a，使其仅包含 sm_75 (Turing) 和 sm_70 (Volta) cubins

nvprune --generate-code code=sm_70 --generate-code code=sm_75 libcublasLt_static.a -o libcublasLt_static_sm70_sm75.a

应该使用它来代替

nvprune -arch=sm_75 libcublasLt_static.a -o libcublasLt_static_sm75.a

9. 致谢

NVIDIA 感谢以下个人和机构的贡献：

• SGEMM、DGEMM、CGEMM 和 ZGEMM 库例程的部分代码由加利福尼亚大学的 Vasily Volkov 编写。

• SGEMM、DGEMM 和 ZGEMM 库例程的部分代码由罗马第二大学的 Davide Barbieri 编写。

• 针对 Fermi 架构优化的 DGEMM 和 SGEMM 库例程的部分代码由田纳西大学开发。随后，从这些初始 DGEMM 和 SGEMM 实现中派生出了针对 Fermi 架构优化的其他几个例程。

• STRSV、DTRSV、CTRSV 和 ZTRSV 库例程的实质性优化由科学技术设施委员会 (STFC) 的 Jonathan Hogg 开发。随后，STRSM、DTRSM、CTRSM 和 ZTRSM 的一些优化是从这些 TRSV 实现中派生出来的。

• SYMV 和 HEMV 库例程的实质性优化由阿卜杜拉国王科技大学 (KAUST) 的 Ahmad Abdelfattah、David Keyes 和 Hatem Ltaief 开发。

• TRMM 和 TRSM 库例程的实质性优化由阿卜杜拉国王科技大学 (KAUST) 的 Ali Charara、David Keyes 和 Hatem Ltaief 开发。

• 本产品包含 {fmt} - 一个现代格式化库 https://fmt.devCopyright (c) 2012 - present, Victor Zverovich。

• 本产品包含 spdlog - 快速 C++ 日志记录库。 https://github.com/gabime/spdlog The MIT License (MIT)。

• 本产品包含用于评估基本函数的 SIMD 库、矢量化 libm 和 DFT https://sleef.orgBoost Software License - Version 1.0 - August 17th, 2003。

• 本产品包含 Frozen - C++14 用户的仅标头、constexpr gperf 替代方案。 https://github.com/serge-sans-paille/frozen Apache License - Version 2.0, January 2004。

• 本产品包含 Boost C++ 库 - 免费的同行评审可移植 C++ 源代码库 https://boost.ac.cn/ Boost Software License - Version 1.0 - August 17th, 2003。

• 本产品包含 Zstandard - 一种快速无损压缩算法，旨在实现 zlib 级别和更高压缩率的实时压缩场景。 https://github.com/facebook/zstd The BSD License。

10. 通知

10.1. 声明

本文档仅供参考，不应视为对产品特定功能、状况或质量的保证。NVIDIA Corporation（“NVIDIA”）对本文档所含信息的准确性或完整性不作任何明示或暗示的陈述或保证，并且对本文档中包含的任何错误不承担任何责任。NVIDIA 对因使用此类信息或因使用此类信息而可能导致的侵犯第三方专利或其他权利的行为的后果或使用不承担任何责任。本文档不承诺开发、发布或交付任何材料（如下定义）、代码或功能。

NVIDIA 保留随时对此文档进行更正、修改、增强、改进和任何其他更改的权利，恕不另行通知。

客户在下订单前应获取最新的相关信息，并应验证此类信息是否为最新且完整。

NVIDIA 产品的销售受制于订单确认时提供的 NVIDIA 标准销售条款和条件，除非 NVIDIA 和客户的授权代表签署的个别销售协议（“销售条款”）另有约定。NVIDIA 在此明确反对将任何客户通用条款和条件应用于购买本文档中引用的 NVIDIA 产品。本文档未直接或间接形成任何合同义务。

NVIDIA 产品并非设计、授权或保证适用于医疗、军事、航空、航天或生命维持设备，也不适用于 NVIDIA 产品故障或失灵可能合理预期会导致人身伤害、死亡或财产或环境损害的应用。NVIDIA 对在上述设备或应用中包含和/或使用 NVIDIA 产品不承担任何责任，因此，此类包含和/或使用由客户自行承担风险。

NVIDIA 不保证基于本文档的产品将适用于任何特定用途。NVIDIA 不一定会对每个产品的所有参数进行测试。客户全权负责评估和确定本文档中包含的任何信息的适用性，确保产品适合客户计划的应用，并为该应用执行必要的测试，以避免应用或产品发生故障。客户产品设计中的缺陷可能会影响 NVIDIA 产品的质量和可靠性，并可能导致超出本文档中包含的附加或不同的条件和/或要求。对于可能基于或归因于以下原因的任何故障、损坏、成本或问题，NVIDIA 不承担任何责任：(i) 以任何违反本文档的方式使用 NVIDIA 产品，或 (ii) 客户产品设计。

在本文档下，未授予任何 NVIDIA 专利权、版权或其他 NVIDIA 知识产权的明示或暗示许可。NVIDIA 发布的有关第三方产品或服务的信息不构成 NVIDIA 授予的关于使用此类产品或服务的许可，也不构成对其的保证或认可。使用此类信息可能需要获得第三方专利或其他知识产权的许可，或获得 NVIDIA 专利或其他 NVIDIA 知识产权的许可。

只有在事先获得 NVIDIA 书面批准的情况下，并以未经修改且完全符合所有适用的出口法律和法规的方式复制本文档中的信息，并附带所有相关的条件、限制和声明，才是允许的。

本文档和所有 NVIDIA 设计规范、参考板、文件、图纸、诊断程序、列表和其他文档（统称为“材料”，单独称为“材料”）均按“原样”提供。NVIDIA 对材料不作任何明示、暗示、法定或其他形式的保证，并明确否认所有关于不侵权、适销性和特定用途适用性的暗示保证。在法律未禁止的范围内，在任何情况下，NVIDIA 均不对因使用本文档而引起的任何损害（包括但不限于任何直接、间接、特殊、偶然、惩罚性或后果性损害，无论如何造成，也无论责任理论如何）承担责任，即使 NVIDIA 已被告知可能发生此类损害。尽管客户可能因任何原因遭受任何损害，NVIDIA 对本文所述产品的客户的累计总责任应根据产品的销售条款进行限制。

10.2. OpenCL

OpenCL 是 Apple Inc. 的商标，Khronos Group Inc. 已获得许可使用。

10.3. 商标

NVIDIA 和 NVIDIA 徽标是 NVIDIA Corporation 在美国和其他国家/地区的商标或注册商标。其他公司和产品名称可能是与其相关的各自公司的商标。