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++使用行优先存储，用这些语言编写的应用程序无法直接对二维数组使用原生数组语义。相反，应定义宏或内联函数在一维数组基础上实现矩阵操作。对于以机械方式从Fortran移植到C的代码，可以选择保留基于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\)是由前一个内核生成时也是如此。

• 当库函数返回标量结果时，它可以通过主机或设备上的引用返回，而不仅限于在主机上通过值返回。这一变更允许库函数在标量结果通过设备上的引用生成和返回时被异步调用，从而实现最大并行度。

• 所有cuBLAS库函数调用都会返回错误状态cublasStatus_t。这一改动有助于调试并简化软件开发。请注意cublasStatus已更名为cublasStatus_t，以与cuBLAS库中的其他类型保持更一致的命名风格。

• cublasAlloc() 和 cublasFree() 函数已被弃用。这一变更移除了这些分别对 cudaMalloc() 和 cudaFree() 的不必要封装。

• 函数 cublasSetKernelStream() 被重命名为 cublasSetStream() 以与其他 CUDA 库保持更一致的命名风格。

传统的cuBLAS API（在使用传统cuBLAS API中有更详细说明）可以通过包含头文件cublas.h来使用。由于传统API与之前发布的cuBLAS库API完全相同，现有应用程序可以直接运行并自动使用此传统API，无需任何源代码更改。

The current and the legacy cuBLAS APIs cannot be used simultaneously in a single translation unit: including both cublas.h and cublas_v2.h header files will lead to compilation errors due to incompatible symbol redeclarations.

通常情况下，新应用程序不应使用传统的cuBLAS API，而现有应用程序如果需要进行复杂且最优化的流并行处理，或者需要从多个线程并发调用cuBLAS例程，则应转换为使用新API。

在文档的其余部分，新的cuBLAS库API将简称为cuBLAS库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位整数平铺布局的前向兼容性有限。

1.5. 浮点运算模拟

浮点模拟功能在CUDA 12.9中引入，用于进一步加速高精度数据类型的矩阵乘法运算。浮点模拟的工作原理是先将输入数据转换为多个低精度值，然后利用低精度硬件单元计算部分结果，最后将结果重新组合成全精度值。这些算法在保持相同或更高精度的同时，相比原生精度运算能带来显著的性能优势；但计算结果不完全符合IEEE-754标准。

浮点运算仿真支持概述

浮点模拟算法	支持的计算能力
BF16x9	10.0, 10.3

要在不更改任何代码的情况下启用浮点模拟，可以使用以下环境变量。

浮点模拟环境变量

环境变量	描述
CUBLAS_EMULATION_STRATEGY	一个用于覆盖默认模拟策略的环境变量。有效值为performant和eager，详情请参阅cublasEmulationStrategy_t。
CUBLAS_EMULATE_SINGLE_PRECISION	一个环境变量，分别使用值1和0来启用和禁用单精度浮点模拟。

1.5.1. BF16x9

BF16x9算法用于模拟FP32算术运算。一个FP32值可以精确表示为三个BF16值，具体如下：

\[\begin{split}a & = a_0 + 2^{-8} a_1 + 2^{-16} a_2 \\\end{split}\]

我们可以完全无损地从BF16值重建FP32值。基于此，我们定义如下FMA运算（d = ab + c）：

\[\begin{split}d & = ab + c \\ & = (a_0 + 2^{-8} a_1 + 2^{-16} a_2) \cdot (b_0 + 2^{-8} b_1 + 2^{-16} b_2) + c \\ & = a_0b_0 + 2^{-8}a_0b_1 + 2^{-16}a_0b_2 \\ & \quad + 2^{-8}a_1b_0 + 2^{-16}a_1b_1 + 2^{-24}a_1b_2 \\ & \quad + 2^{-16}a_2b_0 + 2^{-24}a_2b_1 + 2^{-32}a_2b_2 + c \\\end{split}\]

实际上，这里使用的是BF16张量核心而非FMA单元，这一理念也自然延伸到了复数运算领域。

虽然BF16x9可以在所有硬件上支持，但仅当峰值BF16吞吐量比峰值FP32吞吐量高出九倍以上时才能提供性能优势。此外，它还需要特殊的硬件特性才能以高性能方式应用额外的缩放因子。因此，BF16x9仅在特定架构上受支持。详情请参阅Floating Point Emulation Support Overview表格。

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()设置要使用的新设备，然后通过调用cublasCreate()创建另一个与新设备关联的cuBLAS上下文。当存在多个可用设备时，应用程序必须确保在使用该上下文调用cuBLAS函数之前，与给定cuBLAS上下文关联的设备是当前设备（例如通过调用cudaSetDevice()）。

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

2.1.3. 线程安全性

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

2.1.4. 结果可复现性

根据设计，来自特定工具包版本的所有cuBLAS API例程，在具有相同架构和相同SM数量的GPU上运行时，每次运行都会生成相同的比特级结果。然而，由于实现可能因某些变更而有所不同，不同工具包版本之间不保证比特级可重现性。

此保证仅在单个CUDA流处于活动状态时有效。如果有多个并发流处于活动状态，该库可能会通过选择不同的内部实现来优化整体性能。

注意

多流执行的非确定性行为源于库在并行流中运行的例程选择内部工作空间时的优化。为避免此影响，用户可采取以下任一措施：

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

• 每个流拥有一个cuBLAS句柄，或者

• 使用 cublasLtMatmul() 替代 GEMM 系列函数并提供用户拥有的工作空间，或者

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

以上任一设置都能确保确定性行为，即使多个并发流共享同一个cuBLAS句柄时也是如此。

预计此行为将在未来版本中发生变化。

对于某些例程，例如cublassymv()和cublashemv()，可以使用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()，因此仍可在调用后立即对alpha和/或beta调用cudaFree()，但这样会失去使用该指针模式的意义。

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

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

2.1.6. 流并行处理

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

The application can conceptually associate each stream with each task. In order to achieve the overlap of computation between the tasks, the user should create CUDA™ streams using the function cudaStreamCreate() and set the stream to be used by each individual cuBLAS library routine by calling cublasSetStream() just before calling the actual cuBLAS routine. Note that cublasSetStream() resets the user-provided workspace to the default workspace pool; see cublasSetWorkspace(). Then, the computation performed in separate streams would be overlapped automatically when possible on the GPU. This approach is especially useful when the computation performed by a single task is relatively small and is not enough to fill the GPU with work.

我们建议在使用流时，采用新的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™流，然后在每次调用cublasgemm()之前，为每个矩阵乘法调用cublasSetStream()并指定不同的流（注意cublasSetStream()会将用户提供的工作空间重置为默认工作空间池，参见cublasSetWorkspace()）。这将确保在可能的情况下，不同的计算将并发执行。尽管用户可以创建许多流，但实际上不可能同时执行超过32个并发内核。

2.1.8. 缓存配置

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

由于切换不同的配置可能会影响内核并发性，cuBLAS库不会设置任何缓存配置偏好，而是依赖于当前设置。然而，某些cuBLAS例程（尤其是Level-3级例程）高度依赖共享内存。因此，缓存偏好设置可能会对其性能产生不利影响。

2.1.9. 静态库支持

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

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

nvcc myCublasApp.c  -lcublas  -o myCublasApp

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

nvcc myCublasApp.c  -lcublas_static   -lculibos -o myCublasApp

也可以使用原生Host C++编译器。根据主机操作系统的不同，在链接行可能需要一些额外的库，如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启发式算法或用户显式选择此类算法时，每个分割的结果会以确定性方式求和到结果矩阵中，从而获得最终结果。

对于cublasgemmEx()和cublasGemmEx()例程，当计算类型大于输出类型时，分割块的总和可能导致某些中间溢出，从而产生包含部分溢出的最终结果矩阵。如果所有点积都在计算类型中累加完毕后再转换为输出类型，这些溢出可能就不会发生。当computeType为CUDA_R_32F而Atype、Btype和Ctype为CUDA_R_16F时，这种计算副作用很容易显现。可以通过使用cublasSetMathMode()设置计算精度模式CUBLAS_MATH_DISALLOW_REDUCED_PRECISION_REDUCTION来控制此行为。

2.1.11. Tensor Core 使用

张量核心最初随Volta GPU（计算能力7.0及以上）推出，能显著加速矩阵乘法运算。从cuBLAS 11.0.0版本开始，该库会自动在可能的情况下利用张量核心能力，除非通过选择cuBLAS中的严格计算模式明确禁用此功能（参见cublasSetMathMode()，cublasMath_t）。

需要注意的是，该库会在确定能提供最佳性能时自动选择启用Tensor Core的实现方案。

在使用Tensor Cores时，当矩阵维度和指针满足特定的内存对齐要求时，可以获得最佳性能。具体来说，必须满足以下所有条件才能充分发挥Tensor Cores的性能：

• ((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-bit Floating Point Data Types (FP8) Usage），必须确保矩阵维度和指针满足上述列出的最优要求。除FP8外，使用Tensor Core不再对矩阵维度和内存对齐有任何限制（从cuBLAS 11.0.0版本开始）。

2.1.12. CUDA Graphs 支持

在大多数情况下，cuBLAS例程可以在CUDA Graph流捕获中无限制地被捕获。

例外情况是将结果输出到主机缓冲区的例程（例如，当指针模式CUBLAS_POINTER_MODE_HOST配置时的cublasdot()），因为这强制要求同步。

对于输入系数（如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库的上下文。必须使用cublasCreate()初始化cuBLAS库上下文，并且返回的句柄必须传递给所有后续的库函数调用。最后应使用cublasDestroy()销毁该上下文。

2.2.2. cublasStatus_t

该类型用于函数状态返回。所有cuBLAS库函数都会返回其状态，状态值可能如下所示。

值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成。
CUBLAS_STATUS_NOT_INITIALIZED	cuBLAS库未被初始化。这通常是由于缺少先前的cublasCreate()调用、cuBLAS例程调用的CUDA Runtime 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

该类型指示稠密矩阵的主对角线是否为1，因此不应被函数触碰或修改。其值对应于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安培架构GPU及更新型号无效。
CUBLAS_GEMM_DEFAULT_TENSOR_OP[已弃用]	此模式已弃用，将在未来版本中移除。应用启发式方法选择GEMM算法，同时允许使用降低精度的CUBLAS_COMPUTE_32F_FAST_16F内核（以保持向后兼容性）。
CUBLAS_GEMM_ALGO0_TENSOR_OP 到 CUBLAS_GEMM_ALGO15_TENSOR_OP[已弃用]	这些值已被弃用，将在未来版本中移除。请显式选择张量核心GEMM算法0..15。允许使用降低精度的CUBLAS_COMPUTE_32F_FAST_16F内核（以保持向后兼容性）。注意：对NVIDIA安培架构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张量核心加速单精度计算例程。
CUBLAS_FP32_EMULATED_BF16X9_MATH	启用使用BF16x9算法加速单精度例程。详情请参阅浮点模拟。对于单精度GEMM例程，cuBLAS将使用CUBLAS_COMPUTE_32F_EMULATED_16BFX9计算类型。
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 Cores。
CUBLAS_COMPUTE_16F_PEDANTIC	此模式在计算的所有阶段均使用16位半精度浮点标准化算术，主要面向数值稳健性研究、测试和调试场景。由于该模式会禁用张量核心的使用，其性能可能不及其他模式。
CUBLAS_COMPUTE_32F	这是默认的32位单精度浮点类型，使用至少32位的计算和中间存储精度。
CUBLAS_COMPUTE_32F_PEDANTIC	在所有计算阶段使用32位单精度浮点运算，并禁用算法优化，例如高斯复杂度降低(3M)。
CUBLAS_COMPUTE_32F_FAST_16F	允许库使用Tensor Core，对32位输入和输出矩阵进行自动降精度转换和16位半精度计算。
CUBLAS_COMPUTE_32F_FAST_16BF	允许该库使用Tensor Core，对32位输入和输出矩阵进行自动降精度转换和bfloat16计算。有关bfloat16的更多详情，请参阅Alternate Floating Point章节。
CUBLAS_COMPUTE_32F_FAST_TF32	允许该库对32位输入和输出矩阵使用支持TF32计算的Tensor Cores。有关TF32计算的更多详情，请参阅Alternate Floating Point章节。
CUBLAS_COMPUTE_32F_EMULATED_16BFX9	允许该库使用BF16x9浮点模拟算法进行32位浮点运算。详情请参阅Floating Point Emulation。
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张量核心来加速单精度计算。

2.2.12. cublasEmulationStrategy_t

cublasEmulationStrategy_t 枚举类型用于 cublasSetEmulationStrategy() 函数，以选择如何利用浮点模拟算法。

值	含义
CUBLAS_EMULATION_STRATEGY_DEFAULT	这是默认的模拟策略，相当于CUBLAS_EMULATION_STRATEGY_PERFORMANT，除非设置了CUBLAS_EMULATION_STRATEGY环境变量。
CUBLAS_EMULATION_STRATEGY_PERFORMANT	一种策略，只要模拟能带来性能优势就会利用它。
CUBLAS_EMULATION_STRATEGY_EAGER	一种尽可能利用模拟的策略。

注意

通常情况下，cublasSetEmulationStrategy()函数的优先级高于环境变量设置。但是，将环境变量CUBLAS_EMULATION_STRATEGY设置为performant或eager会覆盖默认的仿真策略，即使默认策略是通过函数调用设置的。

2.3. CUDA 数据类型参考

本章描述了多个CUDA库共享的类型，这些类型定义在头文件library_types.h中。

2.3.1. cuda数据类型_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位实数浮点数
CUDA_R_4F_E2M1	该数据类型为E2M1格式的4位实数浮点数

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 为空

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 为空

注意

此函数可以安全地以handle设置为NULL的方式调用。这允许用户在不使用句柄的情况下获取库的版本。另一种实现方式是使用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库工作空间重置回默认工作空间池。调用此函数（包括将workspaceSizeInBytes设置为0）将阻止cuBLAS库使用默认工作空间。workspaceSizeInBytes值过小可能导致某些例程失败并返回CUBLAS_STATUS_ALLOC_FAILED错误，或导致性能大幅下降。工作空间大小等于或大于16KiB足以避免CUBLAS_STATUS_ALLOC_FAILED错误，而更大的工作空间可以为某些例程提供性能优势。

注意

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

下表显示了用户提供的工作空间的推荐大小。这是基于cuBLAS默认工作空间池大小，该大小取决于GPU架构。

GPU架构	推荐工作区大小
NVIDIA Hopper架构 (sm90)	32兆字节
NVIDIA Blackwell架构 (sm10x)	32 MiB
NVIDIA Blackwell架构 (sm12x)	12 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 为空

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字节。源向量中连续元素之间的存储间距由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)

一些例程如cublassymv()和cublashemv()提供了使用原子操作累加结果的替代实现。这种实现方式通常明显更快，但可能导致不同运行之间产生不完全相同的结果。从数学角度看，这些差异并不显著，但在调试过程中这些差异可能会带来不利影响。

此函数允许或禁止在所有具有替代实现的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 是一个空指针

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. cublasSetEmulationStrategy()

cublasStatus_t cublasSetEmulationStrategy(cublasHandle_t handle, cublasEmulationStrategy_t emulationStrategy)

cublasSetEmulationStrategy() 函数允许您选择库应如何使用浮点模拟功能。更多详情请参阅cublasEmulationStrategy_t。

返回值	含义
CUBLAS_STATUS_SUCCESS	模拟策略已成功设置。
CUBLAS_STATUS_INVALID_VALUE	指定的模拟策略值无效。
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化。

2.4.27. cublasGetEmulationStrategy()

cublasStatus_t cublasGetEmulationStrategy(cublasHandle_t handle, cublasEmulationStrategy_t *emulationStrategy)

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

返回值	含义
CUBLAS_STATUS_SUCCESS	模拟策略已成功返回。
CUBLAS_STATUS_INVALID_VALUE	emulationStrategy 为 NULL。
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化。

2.4.28. cublasLoggerConfigure()

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

此函数用于在运行时配置日志记录。除了这种配置方式外，还可以通过特殊环境变量来配置日志记录，这些变量将由libcublas进行检查：

• CUBLAS_LOGINFO_DBG - 将此环境变量设置为1表示开启日志记录（默认情况下日志记录是关闭的）。

• CUBLAS_LOGDEST_DBG - 此环境变量定义了日志写入的位置：stdout表示将日志消息写入标准输出流，stderr表示写入标准错误流。其他值将被解释为文件名。

参数

参数	内存	输入/输出	含义
logIsOn	host	input	完全开启/关闭日志记录。默认情况下为关闭状态，但通过调用cublasSetLoggerCallback()设置用户自定义回调函数时会自动开启。
logToStdOut	host	input	开启/关闭标准输出I/O流的日志记录功能。默认关闭。
logToStdErr	host	input	开启/关闭标准错误I/O流的日志记录。默认情况下为关闭状态。
日志文件名	主机	输入	根据文件名开启或关闭文件系统中的日志记录。cublasLoggerConfigure()会复制logFileName的内容。如果不需要此类日志记录，应提供空指针。

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

2.4.29. cublasGetLoggerCallback()

cublasStatus_t cublasGetLoggerCallback(
    cublasLogCallback* userCallback)

该函数获取之前通过cublasSetLoggerCallback()安装的用户自定义回调函数的指针，若未安装则返回零值。

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

该函数可能返回的错误值及其含义如下所示。

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

2.4.30. cublasSetLoggerCallback()

cublasStatus_t cublasSetLoggerCallback(
    cublasLogCallback   userCallback)

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

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

错误值	含义
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. cublasIamax()

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\)，使得对于\(i = 1,\ldots,n\)和\(j = 1 + \left( {i - 1} \right)*\text{ incx}\)，\(\left| \mathbf{Im}\left( {x\lbrack j\rbrack} \right) \middle| + \middle| \mathbf{Re}\left( {x\lbrack j\rbrack} \right) \right|\)达到最大值。请注意，最后一个等式反映了基于1的索引方式，这是为了与Fortran兼容。

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
n		输入	向量x中的元素数量。
x	device	输入	<类型> 包含元素的向量。
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 为空值

参考资料请查阅NETLIB文档：

isamax(), idamax(), icamax(), izamax()

2.5.2. cublasIamin()

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\)，使得对于\(i = 1,\ldots,n\)和\(j = 1 + \left( {i - 1} \right)*\text{incx}\)，\(\left| \mathbf{Im}\left( {x\lbrack j\rbrack} \right) \middle| + \middle| \mathbf{Re}\left( {x\lbrack j\rbrack} \right) \right|\)取得最小值。请注意，最后一个等式反映了基于1的索引方式，这是为了与Fortran兼容。

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
n		输入	向量 x 中的元素数量。
x	device	输入	<类型> 包含元素的向量。
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. cublasasum()

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	device	输入	<类型> 包含元素的向量。
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. cublasaxpy()

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	device	输入	<type> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
y	device	输入/输出	<type> 包含 n 个元素的向量。
incy		输入	y中连续元素之间的步长。

该函数可能返回的错误值及其含义如下所示。

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

参考资料请查阅NETLIB文档：

saxpy(), daxpy(), caxpy(), zaxpy()

2.5.5. cublascopy()

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	device	输入	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
y	device	输入/输出	<type> 包含 n 个元素的向量。
incy		输入	y中连续元素之间的步长。

该函数可能返回的错误值及其含义如下所示。

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

参考资料请查阅NETLIB文档：

scopy(), dcopy(), ccopy(), zcopy()

2.5.6. cublasdot()

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元素的共轭复数，且最后两个等式反映了为与Fortran兼容而使用的基于1的索引方式。

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
n		输入	向量x和y中的元素数量。
x	device	输入	<type> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
y	device	输入	<类型> 包含 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. cublasnrm2()

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	device	输入	<类型> 包含 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. cublasrot()

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位整数接口。

该函数应用吉文斯旋转矩阵（即在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	device	输入/输出	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
y	device	输入/输出	<类型> 包含 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. cublasrotg()

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位整数接口。

该函数用于构造吉文斯旋转矩阵

\(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 = \pm \sqrt{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{ if }\left| z \middle| < 1 \right.} \\ \left( {0.0,1.0} \right) & {\text{ if }\left| z \middle| = 1 \right.} \\ \left( 1/z,\sqrt{1 - z^{2}} \right) & {\text{ if }\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\) 时，而当 \(a = 0\) 时 \(r = b\)。最后，参数 \(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. cublasrotm()

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	device	输入/输出	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
y	device	输入/输出	<类型> 包含 n 个元素的向量。
incy		输入	y中连续元素之间的步长。
param	主机或设备	输入	<类型> 包含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. cublasrotmg()

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位整数接口。

该函数构建修正的Givens变换

\(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	主机或设备	输入	<类型> 标量。
param	主机或设备	输出	<类型> 包含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. cublasscal()

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位整数接口。

该函数将向量x按标量\(\alpha\)进行缩放，并用结果覆盖原向量。因此执行的操作是\(\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	device	输入/输出	<类型> 包含 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. cublasswap()

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	device	输入/输出	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
y	device	输入/输出	<类型> 包含 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. cublasgbmv()

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	device	输入	<类型> 维度为 lda x n 的数组，其中 lda >= kl + ku + 1。
lda		输入	用于存储矩阵A的二维数组的主维度。
x	device	输入	<类型> 如果 trans == CUBLAS_OP_N 则为包含 n 个元素的向量，否则为包含 m 个元素的向量。
incx		输入	x中连续元素之间的步长。
beta	主机或设备	输入	<类型> 用于乘法的标量。如果 beta == 0 则 y 不需要是有效输入。
y	device	输入/输出	<类型> 如果 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. cublasgemv()

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	device	输入	<类型> 维度为 lda x n 的数组，其中 lda >= max(1, m)。在输入前，数组 A 的前 m 行 n 列必须包含系数矩阵。退出时保持不变。
lda		输入	用于存储矩阵A的二维数组的主维度。lda必须至少为max(1, m)。
x	device	输入	如果trans == CUBLAS_OP_N，则<类型>向量至少需要(1 + (n - 1) * abs(incx))个元素，否则至少需要(1 + (m - 1) * abs(incx))个元素。
incx		输入	x中连续元素之间的步长。
beta	主机或设备	输入	<类型> 用于乘法的标量。如果 beta == 0 则 y 不需要是有效输入。
y	device	输入/输出	<类型> 向量至少需要 (1 + (m - 1) * abs(incy)) 个元素（如果 trans == CUBLAS_OP_N），否则至少需要 (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. cublasger()

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	device	输入	<类型> 包含 m 个元素的向量。
incx		输入	x中连续元素之间的步长。
y	device	输入	<类型> 包含 n 个元素的向量。
incy		输入	y中连续元素之间的步长。
A	device	输入/输出	<类型> 维度为 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. cublassbmv()

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	device	输入	<类型> 维度为 lda x n 的数组，其中 lda >= k + 1。
lda		输入	用于存储矩阵A的二维数组的主维度。
x	device	输入	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
beta	主机或设备	输入	<类型> 用于乘法的标量。如果 beta == 0 则 y 不需要是有效输入。
y	device	输入/输出	<类型> 包含 n 个元素的向量。
incy		输入	y中连续元素之间的步长。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0 或 k < 0，或者 如果 incx == 0 或 incy == 0，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 如果 alpha 或 beta 为 NULL，或者 如果 lda < (1 + k)
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

ssbmv(), dsbmv()

2.6.5. cublasspmv()

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位整数接口。

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

\(\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> 用于乘法的标量。
AP	device	输入	<type> 数组，其中 \(A\) 以压缩格式存储。
x	device	输入	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
beta	主机或设备	输入	<类型> 用于乘法的标量。如果 beta == 0 则 y 不需要是有效输入。
y	device	输入	<类型> 包含 n 个元素的向量。
incy		输入	y中连续元素之间的步长。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0，或者 如果 incx == 0 或 incy == 0，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 其中之一，或 如果 alpha 或 beta 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

sspmv(), dspmv()

2.6.6. cublasspr()

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位整数接口。

该函数执行打包对称秩1更新

\(A = \alpha\textbf{x}\textbf{x}^{T} + 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	device	输入	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
AP	device	输入/输出	<type> 数组，其中 \(A\) 以压缩格式存储。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0，或者 如果 incx == 0, 或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的一种，或者 如果 alpha 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

sspr(), dspr()

2.6.7. cublasspr2()

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更新

\(A = \alpha\left( {\textbf{x}\textbf{y}^{T} + \textbf{y}\textbf{x}^{T}} \right) + 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	device	输入	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
y	device	输入	<类型> 包含 n 个元素的向量。
incy		输入	y中连续元素之间的步长。
AP	device	输入/输出	<type> 数组，其中 \(A\) 以压缩格式存储。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0，或者 如果 incx == 0 或 incy == 0，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 其中之一，或 如果 alpha 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

sspr2(), dspr2()

2.6.8. cublassymv()

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位整数接口。

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

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

该函数有一个使用原子操作的替代实现，速度更快，可通过cublasSetAtomicsMode()启用。

有关原子操作的更多使用详情，请参阅函数cublasSetAtomicsMode()部分。

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
uplo		输入	指示矩阵的下三角部分或上三角部分是否被存储，另一对称部分未被引用，而是从存储的元素中推断得出。
n		输入	矩阵A的行数和列数。
alpha	主机或设备	输入	<type> 用于乘法的标量。
A	device	输入	<类型> 维度为 lda x n 的数组，其中 lda >= max(1, n)。
lda		输入	用于存储矩阵A的二维数组的主维度。
x	device	输入	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
beta	主机或设备	输入	<类型> 用于乘法的标量。如果 beta == 0 则 y 不需要是有效输入。
y	device	输入/输出	<类型> 包含 n 个元素的向量。
incy		输入	y中连续元素之间的步长。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0，或者 如果 incx == 0 或 incy == 0，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 其中之一，或 如果 lda < n
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

ssymv(), dsymv()

2.6.9. cublassyr()

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位整数接口。

该函数执行对称秩1更新

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

其中 \(A\) 是一个以列主序格式存储的 \(n \times n\) 对称矩阵，\(\mathbf{x}\) 是向量，\(\alpha\) 是标量。

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
uplo		输入	指示矩阵A的下三角部分或上三角部分是否被存储，另一对称部分未被引用，而是从存储的元素中推断得出。
n		输入	矩阵A的行数和列数。
alpha	主机或设备	输入	<type> 用于乘法的标量。
x	device	输入	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
A	device	输入/输出	<类型> 维度数组 lda x n，其中 lda >= max(1, n)。
lda		输入	用于存储矩阵A的二维数组的主维度。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0，或者 如果 incx == 0，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或者 如果 lda < max(1, n)，或者 如果 alpha 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

ssyr(), dsyr()

2.6.10. cublassyr2()

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更新

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

其中 \(A\) 是一个按列主序存储的 \(n \times n\) 对称矩阵，\(\mathbf{x}\) 和 \(\mathbf{y}\) 是向量，\(\alpha\) 是一个标量。

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
uplo		输入	指示矩阵A的下三角部分或上三角部分是否被存储，另一对称部分未被引用，而是从存储的元素中推断得出。
n		输入	矩阵A的行数和列数。
alpha	主机或设备	输入	<type> 用于乘法的标量。
x	device	输入	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
y	device	输入	<类型> 包含 n 个元素的向量。
incy		输入	y中连续元素之间的步长。
A	device	输入/输出	<类型> 维度数组 lda x n, 其中 lda >= max(1,n).
lda		输入	用于存储矩阵A的二维数组的主维度。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0，或者 如果 incx == 0 或 incy == 0，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 如果 alpha 为 NULL，或 如果 lda < max(1, n)
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

ssyr2(), dsyr2()

2.6.11. cublastbmv()

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位整数接口。

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

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

其中 \(A\) 是一个三角带状矩阵，\(\mathbf{x}\) 是一个向量。同样地，对于矩阵 \(A\)

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

如果 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主对角线上的元素是否为1且不应被访问。
n		输入	矩阵A的行数和列数。
k		输入	矩阵的子对角线和超对角线的数量。
A	device	输入	<类型> 维度为 lda x n 的数组，其中 lda >= k + 1。
lda		输入	用于存储矩阵A的二维数组的主维度。
x	device	输入/输出	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0 或 k < 0，或者 如果 incx == 0，或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 或 CUBLAS_OP_C 其中之一，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 如果 diag 不是 CUBLAS_DIAG_UNIT 或 CUBLAS_DIAG_NON_UNIT 中的一种，或 如果 lda < (1 + k)
CUBLAS_STATUS_ALLOC_FAILED	内部临时内存分配失败
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

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

2.6.12. cublastbsv()

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

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

解 \(\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主对角线上的元素是否为1且不应被访问。
n		输入	矩阵A的行数和列数。
k		输入	矩阵A的次对角线和超对角线的数量。
A	device	输入	<类型> 维度为 lda x n 的数组，其中 lda >= k+1。
lda		输入	用于存储矩阵A的二维数组的主维度。
x	device	输入/输出	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0 或 k < 0，或者 如果 incx == 0，或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 或 CUBLAS_OP_C 中的一个，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 如果 diag 不是 CUBLAS_DIAG_UNIT 或 CUBLAS_DIAG_NON_UNIT 其中之一，或 如果 lda < (1 + k)
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

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

2.6.13. cublastpmv()

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位整数接口。

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

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

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

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

如果 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] 中，其中 \(i \leq j\)。因此，这种压缩存储格式仅需要 \(\frac{n(n + 1)}{2}\) 个元素的空间。

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
uplo		输入	指示矩阵A的下三角或上三角部分是否被存储，另一部分未被引用，而是从存储的元素中推断得出。
trans		输入	操作op(A)表示非转置或共轭转置。
diag		输入	表示矩阵A主对角线上的元素是否为1且不应被访问。
n		输入	矩阵A的行数和列数。
AP	device	输入	<type> 数组，其中 \(A\) 以压缩格式存储。
x	device	输入/输出	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0，或者 如果 incx == 0，或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 或 CUBLAS_OP_C 其中之一，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 如果 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. cublastpsv()

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

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

解 \(\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		输入	表示矩阵主对角线上的元素是否为1且不应被访问。
n		输入	矩阵A的行数和列数。
AP	device	输入	<type> 数组，其中 \(A\) 以压缩格式存储。
x	device	输入/输出	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0，或者 如果 incx == 0, 或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 其中之一，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 其中之一，或 如果 diag 不是 CUBLAS_DIAG_UNIT 或 CUBLAS_DIAG_NON_UNIT 之一
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

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

2.6.15. cublastrmv()

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位整数接口。

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

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

其中\(A\)是一个以包含或不包含主对角线的下三角或上三角模式存储的三角矩阵，\(\mathbf{x}\)是一个向量。同样地，对于矩阵\(A\)

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

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
uplo		输入	指示矩阵A的下三角或上三角部分是否被存储，另一部分未被引用，而是从存储的元素中推断得出。
trans		输入	操作op(A)表示非转置或共轭转置。
diag		输入	表示矩阵A主对角线上的元素是否为1且不应被访问。
n		输入	矩阵A的行数和列数。
A	device	输入	<类型> 维度数组 lda x n，其中 lda >= max(1, n)。
lda		输入	用于存储矩阵A的二维数组的主维度。
x	device	输入/输出	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0，或者 如果 incx == 0, 或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 或 CUBLAS_OP_C 中的一个，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 其中之一，或 如果 diag 不是 CUBLAS_DIAG_UNIT 或 CUBLAS_DIAG_NON_UNIT 其中之一，或 如果 lda < max(1, n)
CUBLAS_STATUS_ALLOC_FAILED	内部临时内存分配失败
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

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

2.6.16. cublastrsv()

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主对角线上的元素是否为1且不应被访问。
n		输入	矩阵A的行数和列数。
A	device	输入	<类型> 维度为 lda x n 的数组，其中 lda >= max(1, n)。
lda		输入	用于存储矩阵A的二维数组的主维度。
x	device	输入/输出	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0，或者 如果 incx == 0, 或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 其中之一，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 其中之一，或 如果 diag 不是 CUBLAS_DIAG_UNIT 或 CUBLAS_DIAG_NON_UNIT 中的一种，或 如果 lda < max(1, n)
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

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

2.6.17. cublashemv()

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	device	输入	<类型> 维度为 lda x n 的数组，其中 lda >= max(1, n)。假定对角线元素的虚部为零。
lda		输入	用于存储矩阵A的二维数组的主维度。
x	device	输入	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
beta	主机或设备	输入	<类型> 用于乘法的标量。如果 beta == 0 则 y 不需要是有效输入。
y	device	输入/输出	<类型> 包含 n 个元素的向量。
incy		输入	y中连续元素之间的步长。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0，或者 如果 incx == 0 或 incy == 0，或者 如果 uplo 不等于 CUBLAS_FILL_MODE_LOWER 且 uplo != CUBLAS_FILL_MODE_UPPER，或者 如果 lda < n
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

chemv(), zhemv()

2.6.18. cublashbmv()

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	device	输入	<类型> 维度数组 lda x n，其中 lda >= k + 1。假定对角线元素的虚部为零。
lda		输入	用于存储矩阵A的二维数组的主维度。
x	device	输入	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
beta	主机或设备	输入	<类型> 用于乘法的标量。如果 beta == 0 则不必是有效输入。
y	device	输入/输出	<类型> 包含 n 个元素的向量。
incy		输入	y中连续元素之间的步长。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0 或 k < 0，或者 如果 incx == 0 或 incy == 0，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 其中之一，或 如果 lda < (1 + k)，或者 如果 alpha 或 beta 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

chbmv(), zhbmv()

2.6.19. cublashpmv()

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> 用于乘法的标量。
AP	device	输入	<type> 数组，其中 \(A\) 以压缩格式存储。假定对角线元素的虚部为零。
x	device	输入	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
beta	主机或设备	输入	<类型> 用于乘法的标量。如果 beta == 0 则 y 不需要是有效输入。
y	device	输入/输出	<类型> 包含 n 个元素的向量。
incy		输入	y中连续元素之间的步长。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0，或者 如果 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. cublasher()

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	device	输入	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
A	device	输入/输出	<类型> 维度为 lda x n 的数组，其中 lda >= max(1, n)。对角线元素的虚部被假定并设为零。
lda		输入	用于存储矩阵A的二维数组的主维度。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0，或者 如果 incx == 0, 或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 其中之一，或 如果 lda < max(1, n)，或者 如果 alpha 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

cher(), zher()

2.6.21. cublasher2()

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	device	输入	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
y	device	输入	<类型> 包含 n 个元素的向量。
incy		输入	y中连续元素之间的步长。
A	device	输入/输出	<类型> 维度为 lda x n 的数组，其中 lda >= max(1, n)。对角线元素的虚部被假定并设为零。
lda		输入	用于存储矩阵A的二维数组的主维度。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0，或者 如果 incx == 0, 或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 其中之一，或 如果 lda < max(1, n)，或者 如果 alpha 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

cher2(), zher2()

2.6.22. cublashpr()

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	device	输入	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
AP	device	输入/输出	<type> 数组，其中 \(A\) 以压缩格式存储。对角元素的虚部被假定并设为零。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0，或者 如果 incx == 0, 或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 其中之一，或 如果 alpha 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

chpr(), zhpr()

2.6.23. cublashpr2()

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	device	输入	<类型> 包含 n 个元素的向量。
incx		输入	x中连续元素之间的步长。
y	device	输入	<类型> 包含 n 个元素的向量。
incy		输入	y中连续元素之间的步长。
AP	device	输入/输出	<type> 数组，其中 \(A\) 以压缩格式存储。对角元素的虚部被假定并设为零。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0，或者 如果 incx == 0, 或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 其中之一，或 如果 alpha 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

chpr2, zhpr2

2.6.24. cublasgemvBatched()

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位整数接口。

该函数执行一批矩阵和向量的矩阵-向量乘法运算。该批次被视为"统一"的，即所有实例的维度(m, n)、前导维度(lda)、增量(incx, incy)以及各自A矩阵、x向量和y向量的转置(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{ for 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运算必须能够独立计算；否则可能会出现未定义行为。

对于某些特定规模的问题，相较于使用此API，在不同CUDA流中多次调用cublasgemv()可能更具优势。

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
trans		输入	操作op(A[i])表示非转置或共轭转置。
m		输入	矩阵 A[i] 的行数。
n		输入	矩阵 A[i] 的列数。
alpha	主机或设备	输入	<type> 用于乘法的标量。
Aarray	device	输入	指向<类型>数组的指针数组，每个数组的维度为lda x n，其中lda >= max(1, m)。 所有指针必须满足特定的对齐标准。详情请见下文。
lda		输入	用于存储每个矩阵A[i]的二维数组的主维度。
xarray	device	输入	指向<类型>数组的指针数组，当trans==CUBLAS_OP_N时每个维度为n，否则为m。 所有指针必须满足特定的对齐标准。详情请见下文。
incx		输入	每个一维数组x[i]的步长。
beta	主机或设备	输入	<类型> 用于乘法的标量。如果 beta == 0，则 y 不需要是有效输入。
yarray	device	输入/输出	指向<类型>数组的指针数组。如果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. cublasgemvStridedBatched()

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{ for 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{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A\lbrack i\rbrack}^{T} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_T}$}} \\ {A\lbrack i\rbrack}^{H} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

注意

\(\textbf{y}\lbrack i\rbrack\) 矩阵之间不能重叠，也就是说各个gemv运算必须能够独立计算；否则可能会出现未定义行为。

对于某些问题规模，在不同CUDA流中多次调用cublasgemv()可能比使用此API更有利。

注意

在下表中，我们使用A[i], x[i], y[i]作为A矩阵以及批次中第i个实例的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	device	输入	<类型>* 指向批次中第一个实例对应的A矩阵的指针，其维度为 lda x n，其中 lda >= max(1, m)。
lda		输入	用于存储每个矩阵A[i]的二维数组的主维度。
strideA		输入	类型为long long int的值，表示A[i]和A[i+1]之间以元素个数计算的偏移量
x	device	输入	<类型>* 指向批次中第一个实例对应的x向量的指针，当trans==CUBLAS_OP_N时每个维度为n，否则为m。
incx		输入	每个一维数组 x[i] 的步长。
stridex		输入	long long int类型的值，表示x[i]和x[i+1]之间以元素个数计算的偏移量
beta	主机或设备	输入	<类型> 用于乘法的标量。如果 beta == 0，则 y 不需要是有效输入。
y	device	输入/输出	<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. cublasgemm()

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)可以是非转置或(conj.)转置。
m		输入	矩阵 op(A) 和 C 的行数。
n		输入	矩阵 op(B) 和 C 的列数。
k		输入	op(A)的列数与op(B)的行数。
alpha	主机或设备	输入	<type> 用于乘法的标量。
A	device	输入	<类型> 维度数组 lda x k，当 transa == CUBLAS_OP_N 时要求 lda >= max(1, m)；否则为 lda x m 且 lda >= max(1, k)。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	device	输入	<类型> 维度为 ldb x n 的数组，当 transb == CUBLAS_OP_N 时要求 ldb >= max(1, k)，否则为 ldb x k 且 ldb>=max(1,n)。
ldb		输入	用于存储矩阵B的二维数组的主维度。
beta	主机或设备	输入	<type> 用于乘法的标量。如果 beta == 0，则 C 不需要是有效输入。
C	device	输入/输出	<类型> 维度数组 ldc x n，其中 ldc >= max(1, m)。
ldc		输入	用于存储矩阵C的二维数组的主维度。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
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)，否则 lda < max(1, k)，或者 当 transb == CUBLAS_OP_N 时，如果 ldb < max(1, k)；否则当 ldb < max(1, n) 时，或者 如果 ldc < max(1, m)，或者 如果 alpha 或 beta 为 NULL，或者 如果当beta不为零时C为NULL
CUBLAS_STATUS_ARCH_MISMATCH	在cublasHgemm()的情况下，该设备不支持半精度数学运算。
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

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

2.7.2. cublasgemm3m()

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)可以是非转置或(conj.)转置。
m		输入	矩阵 op(A) 和 C 的行数。
n		输入	矩阵 op(B) 和 C 的列数。
k		输入	op(A)的列数与op(B)的行数。
alpha	主机或设备	输入	<type> 用于乘法的标量。
A	device	输入	<类型> 维度数组 lda x k，当 transa == CUBLAS_OP_N 时要求 lda >= max(1, m)，否则为 lda x m 且 lda >= max(1, k)。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	device	输入	<类型> 维度为 ldb x n 的数组，当 transb == CUBLAS_OP_N 时需满足 ldb >= max(1, k)，否则为 ldb x k 且需满足 ldb>=max(1,n)。
ldb		输入	用于存储矩阵B的二维数组的主维度。
beta	主机或设备	输入	<类型> 用于乘法的标量。如果 beta == 0，则 C 不需要是有效输入。
C	device	输入/输出	<类型> 维度数组 ldc x n，其中 ldc >= max(1, m)。
ldc		输入	用于存储矩阵C的二维数组的主维度。

该函数可能返回的错误值及其含义如下表所示：

错误值	含义
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)，否则 lda < max(1, k)，或者 当 transb == CUBLAS_OP_N 时，如果 ldb < max(1, k)；否则当 ldb < max(1, n) 时 如果 ldc < max(1, m)，或者 如果 alpha 或 beta 为 NULL，或者 如果当beta不为零时C为NULL
CUBLAS_STATUS_ARCH_MISMATCH	该设备的计算能力低于5.0。
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动。

参考资料请查阅NETLIB文档：

cgemm(), zgemm()

2.7.3. cublasgemmBatched()

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位整数接口。

该函数执行一批矩阵的矩阵乘法运算。这批矩阵被视为"统一"的，即所有实例的维度(m, n, k)、前导维度(lda, ldb, ldc)以及各自A、B和C矩阵的转置状态(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.\)

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

注意

\(C\lbrack i\rbrack\) 矩阵之间不能重叠，也就是说，各个gemm运算必须能够独立计算；否则可能会出现未定义行为。

对于某些问题规模，在不同CUDA流中多次调用cublasgemm()可能比使用此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	device	输入	指向<类型>数组的指针数组，每个数组的维度为lda x k，当transa==CUBLAS_OP_N时要求lda >= max(1, m)，否则维度为lda x m且要求lda >= max(1, k)。 所有指针必须满足特定的对齐标准。详情请见下文。
lda		输入	用于存储每个矩阵A[i]的二维数组的主维度。
Barray	device	输入	指向<类型>数组的指针数组，每个数组的维度为ldb x n，当transb==CUBLAS_OP_N时要求ldb >= max(1, k)；否则维度为ldb x k且要求ldb>=max(1,n)。 所有指针必须满足特定的对齐标准。详情请见下文。
ldb		输入	用于存储每个矩阵B[i]的二维数组的主维度。
beta	主机或设备	输入	<类型> 用于乘法的标量。如果 beta == 0，则 C 不需要是有效输入。
Carray	device	输入/输出	指向<类型>数组的指针数组。其维度为ldc x n，其中ldc >= max(1, m)。矩阵C[i]之间不应重叠，否则可能导致未定义行为。 所有指针必须满足特定的对齐标准。详情请见下文。
ldc		输入	用于存储每个矩阵C[i]的二维数组的主维度。
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)，否则 lda < max(1, k)，或者 当 transb == CUBLAS_OP_N 时，如果 ldb < max(1, k)；否则当 ldb < max(1, n) 时 如果 ldc < max(1, m)
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动
CUBLAS_STATUS_ARCH_MISMATCH	cublasHgemmBatched() 仅在GPU架构能力等于或高于5.3时受支持

2.7.4. cublasgemmStridedBatched()

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位整数接口。

该函数执行一批矩阵的矩阵乘法运算。这批矩阵被视为"统一"的，即所有实例的维度(m, n, k)、前导维度(lda, ldb, ldc)以及各自A、B和C矩阵的转置状态(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.\)

并且 \(\text{op}(B\lbrack i\rbrack)\) 对矩阵 \(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	device	输入	指向批次中第一个实例对应的A矩阵的类型*指针，当transa==CUBLAS_OP_N时，矩阵维度为lda x k且lda >= max(1, m)；否则维度为lda x m且lda >= max(1, k)。
lda		输入	用于存储每个矩阵A[i]的二维数组的主维度。
strideA		输入	类型为long long int的值，表示A[i]和A[i+1]之间以元素个数计算的偏移量
B	device	输入	<类型>* 指向批次中第一个实例对应的B矩阵的指针，其维度为ldb x n，当transb==CUBLAS_OP_N时需满足ldb >= max(1, k)；否则维度为ldb x k且需满足ldb>=max(1,n)。
ldb		输入	用于存储每个矩阵B[i]的二维数组的主维度。
strideB		输入	long long int类型的值，表示B[i]和B[i+1]之间以元素个数计算的偏移量
beta	主机或设备	输入	<类型> 用于乘法的标量。如果 beta == 0，则 C 不需要是有效输入。
C	device	输入/输出	指向批次中第一个实例对应的C矩阵的<类型>*指针，矩阵维度为ldc x n，其中ldc >= max(1, m)。各C[i]矩阵不应重叠，否则可能导致未定义行为。
ldc		输入	用于存储每个矩阵C[i]的二维数组的主维度。
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)，否则 lda < max(1, k)，或者 当 transb == CUBLAS_OP_N 时，如果 ldb < max(1, k)；否则当 ldb < max(1, n) 时 如果 ldc < max(1, m)
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动
CUBLAS_STATUS_ARCH_MISMATCH	cublasHgemmStridedBatched() 仅支持计算能力5.3及以上的GPU架构

2.7.5. cublasgemmGroupedBatched()

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)、前导维度(lda, ldb, ldc)和转置设置(transa, transb)。但不同组之间的维度、前导维度、转置设置以及缩放因子(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}\)是指向按列主序存储的矩阵的指针数组。对于属于组\(i\)的给定索引\(\text{idx}\)，其维度为：

• \(\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接收两个不同长度的数组。维度数组、前导维度数组、转置数组和缩放因子数组的长度为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.\)

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

注意

\(C\lbrack\text{idx}\rbrack\) 矩阵之间不能重叠，也就是说，各个gemm运算必须能够独立计算；否则可能会导致未定义行为。

对于某些问题规模，在不同CUDA流中多次调用cublasgemmBatched()可能比使用此API更有利。

参数	内存	输入/输出	含义	数组长度
handle		输入	cuBLAS库上下文的句柄。
transa_array	主机	输入	对每个组执行非转置或共轭转置的操作op(A[idx])。	group_count
transb_array	主机	输入	对每个组进行非转置或共轭转置的操作op(B[idx])。	group_count
m_array	主机	输入	包含每个组的矩阵运算(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	device	输入	指向<类型>数组的指针数组，每个数组的维度为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])。 所有指针必须满足特定的对齐标准。详情请见下文。	问题数量
lda_array	主机	输入	包含用于存储每个组矩阵A[idx]的二维数组的前导维度的数组。	group_count
Barray	device	输入	指向<类型>数组的指针数组，每个数组的维度为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])。 所有指针必须满足特定的对齐标准。详情请见下文。	问题数量
ldb_array	主机	输入	包含用于存储每个组矩阵B[idx]的二维数组的前导维度的数组。	group_count
beta_array	主机	输入	包含用于每个组乘法的<类型>标量的数组。	group_count
Carray	device	输入/输出	指向<类型>数组的指针数组。其维度为ldc[i] x n[i]，其中ldc[i]>=max(1,m[i])。矩阵C[idx]不应重叠，否则可能导致未定义行为。 所有指针必须满足特定的对齐标准。详情请见下文。	问题数量
ldc_array	主机	输入	包含用于存储每个组矩阵C[idx]的二维数组的前导维度的数组。	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 中的一种，或者 如果 lda_array[i] < max(1, m_array[i]) 当 transa_array[i] == CUBLAS_OP_N 时，或者 lda_array[i] < max(1, k_array[i]) 其他情况下 如果 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. cublassymm()

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{如果 }\textsf{side == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ {\alpha BA + \beta C} & {\text{如果 }\textsf{side == $\mathrm{CUBLAS\_SIDE\_RIGHT}$}} \\ \end{matrix} \right.\)

其中 \(A\) 是以下三角或上三角模式存储的对称矩阵，\(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	device	输入	类型 维度为 lda x m 的数组，当 side == CUBLAS_SIDE_LEFT 时要求 lda >= max(1, m)；否则为 lda x n 且 lda >= max(1, n)。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	device	输入	<类型> 维度为 ldb x n 的数组，其中 ldb >= max(1, m)。
ldb		输入	用于存储矩阵B的二维数组的主维度。
beta	主机或设备	输入	<类型> 用于乘法的标量。如果 beta == 0 则 C 不需要是有效输入。
C	device	输入/输出	<类型> 维度为 ldc x n 的数组，其中 ldc >= max(1, m)。
ldc		输入	用于存储矩阵C的二维数组的主维度。

该函数可能返回的错误值及其含义如下所示。

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

参考资料请查阅NETLIB文档：

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

2.7.7. cublassyrk()

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{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\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	device	输入	类型 维度为 lda x k 的数组，当 trans == CUBLAS_OP_N 时要求 lda >= max(1, n)；否则为 lda x n 的数组且要求 lda >= max(1, k)。
lda		输入	用于存储矩阵A的二维数组的主维度。
beta	主机或设备	输入	<类型> 用于乘法的标量。如果 beta == 0 则 C 不需要是有效输入。
C	device	输入/输出	<类型> 维度为 ldc x n 的数组，其中 ldc >= max(1, n)。
ldc		输入	用于存储矩阵C的二维数组的主维度。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0 或 k < 0，或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 其中之一，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 当 trans == CUBLAS_OP_N 时，如果 lda < max(1, n)；否则当 lda < max(1, k) 时 如果 ldc < max(1, n)，或者 如果 alpha 或 beta 为 NULL，或者 如果当beta不为零时C为NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

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

2.7.8. cublassyr2k()

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	device	输入	<类型> 维度为 lda x k 的数组，当 transa == CUBLAS_OP_N 时要求 lda >= max(1, n)，否则为 lda x n 且 lda >= max(1, k)。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	device	输入	<类型> 维度数组 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	device	输入/输出	<类型> 维度数组 ldc x n，其中 ldc >= max(1, n)。
ldc		输入	用于存储矩阵C的二维数组的主维度。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0 或 k < 0，或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 其中之一，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 当 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)，或者 如果 alpha 或 beta 为 NULL，或者 如果当beta不为零时C为NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

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

2.7.9. cublassyrkx()

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{) 和 op(}B\text{)} = \left\{ \begin{matrix} {A\text{ 和 }B} & {\text{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A^{T}\text{ 和 }B^{T}} & {\text{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_T}$}} \\ \end{matrix} \right.\)

当矩阵B满足结果保证对称的条件时，可以使用此例程。一个常见例子是当矩阵B是矩阵A的缩放形式时：这相当于B是矩阵A与对角矩阵的乘积。关于常规矩阵与对角矩阵乘积的高效计算，请参考例程cublasdgmm()。

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
uplo		输入	指示矩阵C的下三角或上三角部分是否被存储，另一对称部分未被引用，而是从存储的元素中推断得出。
trans		输入	操作op(A)可以是非转置或转置的。
n		输入	矩阵 op(A)、op(B) 和 C 的行数。
k		输入	矩阵 op(A) 和 op(B) 的列数。
alpha	主机或设备	输入	<type> 用于乘法的标量。
A	device	输入	<类型> 维度为 lda x k 的数组，当 transa == CUBLAS_OP_N 时要求 lda >= max(1, n)，否则为 lda x n 且 lda >= max(1, k)。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	device	输入	<类型> 维度数组 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	device	输入/输出	<类型> 维度为 ldc x n 的数组，其中 ldc >= max(1, n)。
ldc		输入	用于存储矩阵C的二维数组的主维度。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0 或 k < 0，或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 其中之一，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 当 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)，或者 如果 alpha 或 beta 为 NULL，或者 如果当beta不为零时C为NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

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

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

2.7.10. cublastrmm()

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{如果 }\textsf{side == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ {\alpha B\text{op}(A)} & {\text{如果 }\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矩阵）。应用程序可以通过将B矩阵地址作为C矩阵地址传入，在cuBLAS API中获得BLAS的原地功能。输入参数中不支持其他任何重叠情况。

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
side		输入	指示矩阵 A 位于 B 的左侧还是右侧。
uplo		输入	指示矩阵A的下三角或上三角部分是否被存储，另一部分未被引用，而是从存储的元素中推断得出。
trans		输入	操作op(A)表示非转置或共轭转置。
diag		输入	表示矩阵A主对角线上的元素是否为1且不应被访问。
m		输入	矩阵B的行数，矩阵A的大小需相应调整。
n		输入	矩阵B的列数，矩阵A会相应调整尺寸。
alpha	主机或设备	输入	<类型> 用于乘法的标量，如果 alpha == 0 则 A 不会被引用且 B 不需要是有效输入。
A	device	输入	类型 维度为 lda x m 的数组，当 side == CUBLAS_SIDE_LEFT 时要求 lda >= max(1, m)；否则为 lda x n 且 lda >= max(1, n)。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	device	输入	<类型> 维度为 ldb x n 的数组，其中 ldb >= max(1, m)。
ldb		输入	用于存储矩阵B的二维数组的主维度。
C	device	输入/输出	<类型> 维度为 ldc x n 的数组，其中 ldc >= max(1, m)。
ldc		输入	用于存储矩阵C的二维数组的主维度。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
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 其中之一，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 如果 side 不是 CUBLAS_SIDE_LEFT 或 CUBLAS_SIDE_RIGHT 其中之一，或 如果 lda < max(1, m) 当 side == CUBLAS_SIDE_LEFT 时，否则 lda < max(1, n)，或者 如果 ldb < max(1, m)，或者 如果 ldc < max(1, m)，或者 如果 alpha 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

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

2.7.11. cublastrsm()

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{如果 }\textsf{side == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ {X\text{op}(A) = \alpha B} & {\text{如果 }\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主对角线上的元素是否为1且不应被访问。
m		输入	矩阵B的行数，矩阵A的大小相应调整。
n		输入	矩阵B的列数，矩阵A的大小会相应调整。
alpha	主机或设备	输入	<类型> 用于乘法的标量，如果 alpha == 0 则 A 不会被引用且 B 不需要是有效输入。
A	device	输入	类型 维度为 lda x m 的数组，当 side == CUBLAS_SIDE_LEFT 时要求 lda >= max(1, m)；否则为 lda x n 且 lda >= max(1, n)。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	device	输入/输出	<类型> 数组。其维度为 ldb x n，其中 ldb >= max(1, m)。
ldb		输入	用于存储矩阵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 其中之一，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 如果 side 不是 CUBLAS_SIDE_LEFT 和 CUBLAS_SIDE_RIGHT 其中之一，或 如果 diag 不是 CUBLAS_DIAG_UNIT 或 CUBLAS_DIAG_NON_UNIT 中的一种，或 如果 lda < max(1, m) 当 side == CUBLAS_SIDE_LEFT 时，否则 lda < max(1, n)，或者 如果 ldb < max(1, m)，或者 如果 alpha 为 NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

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

2.7.12. cublastrsmBatched()

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{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A^{T}\lbrack i\rbrack} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_T}$}} \\ {A^{H}\lbrack i\rbrack} & {\text{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

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

此函数未包含对奇异性或接近奇异性的测试。

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

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

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
side		输入	表示矩阵 A[i] 位于 X[i] 的左侧还是右侧。
uplo		输入	指示矩阵A[i]的下三角部分或上三角部分是否被存储，另一部分未被引用，而是从存储的元素中推断得出。
trans		输入	操作op(A[i])表示非转置或共轭转置。
diag		输入	表示矩阵A[i]主对角线上的元素是否为1且不应被访问。
m		输入	矩阵B[i]的行数，矩阵A[i]的尺寸会相应调整。
n		输入	矩阵B[i]的列数，矩阵A[i]的大小会相应调整。
alpha	主机或设备	输入	<类型> 用于乘法的标量，如果 alpha == 0 则 A[i] 不会被引用且 B[i] 不需要是有效输入。
A	device	输入	指向<类型>数组的指针数组，每个数组的维度为lda x m，当side == CUBLAS_SIDE_LEFT时要求lda >= max(1, m)，否则维度为lda x n且要求lda >= max(1, n)。
lda		输入	用于存储矩阵A[i]的二维数组的主维度。
B	device	输入/输出	指向<类型>数组的指针数组，每个数组的维度为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 其中之一，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 如果 side 不是 CUBLAS_SIDE_LEFT 和 CUBLAS_SIDE_RIGHT 中的一个，或 如果 diag 不是 CUBLAS_DIAG_UNIT 或 CUBLAS_DIAG_NON_UNIT 中的一种，或 如果 lda < max(1, m) 当 side == CUBLAS_SIDE_LEFT 时，否则 lda < max(1, n)，或者 如果 ldb < max(1, m)
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

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

2.7.13. cublashemm()

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位整数接口。

该函数执行厄米特矩阵-矩阵乘法

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

其中\(A\)是一个以低位或高位模式存储的埃尔米特矩阵，\(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	device	输入	<类型> 维度为 lda x m 的数组，当 side==CUBLAS_SIDE_LEFT 时要求 lda >= max(1, m)，否则为 lda x n 且 lda >= max(1, n)。假定对角线元素的虚部为零。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	device	输入	<类型> 维度为 ldb x n 的数组，其中 ldb >= max(1, m)。
ldb		输入	用于存储矩阵B的二维数组的主维度。
beta		输入	<类型> 用于乘法的标量。如果 beta == 0 则 C 不需要是有效输入。
C	device	输入/输出	<类型> 维度数组 ldc x n，其中 ldc >= max(1, m)。
ldc		输入	用于存储矩阵C的二维数组的主维度。

该函数可能返回的错误值及其含义如下所示。

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

参考资料请查阅NETLIB文档：

chemm(), zhemm()

2.7.14. cublasherk()

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位整数接口。

该函数执行埃尔米特秩-\(k\)更新

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

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以下三角或上三角模式存储的厄米特矩阵，\(A\) 是一个维度为 \(\text{op}(A)\) \(n \times k\) 的矩阵。同样地，对于矩阵 \(A\)

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

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
uplo		输入	指示矩阵C的下三角或上三角部分是否被存储，另一侧的共轭对称部分不被引用。
trans		输入	操作op(A)表示非转置或共轭转置。
n		输入	矩阵 op(A) 和 C 的行数。
k		输入	矩阵 op(A) 的列数。
alpha	主机或设备	输入	<type> 用于乘法的标量。
A	device	输入	<类型> 维度为 lda x k 的数组，当 transa == CUBLAS_OP_N 时要求 lda >= max(1, n)，否则为 lda x n 且 lda >= max(1, k)。
lda		输入	用于存储矩阵A的二维数组的主维度。
beta		输入	<类型> 用于乘法的标量。如果 beta == 0 则 C 不需要是有效输入。
C	device	输入/输出	<类型> 维度为 ldc x n 的数组，其中 ldc >= max(1, n)。对角线元素的虚部被假定并设为零。
ldc		输入	用于存储矩阵C的二维数组的主维度。

该函数可能返回的错误值及其含义如下所示。

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

参考资料请查阅NETLIB文档：

cherk(), zherk()

2.7.15. cublasher2k()

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位整数接口。

该函数执行埃尔米特秩\(2k\)更新

\(C = \alpha\text{op}(A)\text{op}(B)^{H} + \overset{ˉ}{\alpha}\text{op}(B)\text{op}(A)^{H} + \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^{H}\text{ and }B^{H}} & {\text{if }\textsf{trans == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
uplo		输入	指示矩阵C的下三角或上三角部分是否被存储，另一侧的共轭对称部分不被引用。
trans		输入	操作op(A)表示非转置或共轭转置。
n		输入	矩阵 op(A)、op(B) 和 C 的行数。
k		输入	矩阵 op(A) 和 op(B) 的列数。
alpha	主机或设备	输入	<type> 用于乘法的标量。
A	device	输入	<类型> 维度为 lda x k 的数组，当 transa == CUBLAS_OP_N 时要求 lda >= max(1, n)，否则为 lda x n 且 lda >= max(1, k)。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	device	输入	<类型> 维度为 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	device	输入/输出	<类型> 维度为 ldc x n 的数组，其中 ldc >= max(1, n)。对角线元素的虚部被假定并设为零。
ldc		输入	用于存储矩阵C的二维数组的主维度。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0 或 k < 0，或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 其中之一，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 当 trans == CUBLAS_OP_N 时，如果 lda < max(1, n)；否则当 lda < max(1, k) 时 如果 ldc < max(1, n)，或者 如果 alpha 或 beta 为 NULL，或者 如果当beta不为零时C为NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

cher2k(), zher2k()

2.7.16. cublasherkx()

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位整数接口。

该函数执行埃尔米特秩\(k\)更新的变体

\(C = \alpha\text{op}(A)\text{op}(B)^{H} + \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{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A^{H}\text{ and }B^{H}} & {\text{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

当矩阵B满足结果保证为厄米特矩阵的条件时，可以使用此例程。一个常见例子是当矩阵B是矩阵A的缩放形式时：这相当于B是矩阵A与对角矩阵的乘积。关于常规矩阵与对角矩阵乘积的高效计算，请参考例程cublasdgmm()。

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
uplo		输入	指示矩阵C的下三角或上三角部分是否被存储，另一侧的共轭对称部分不被引用。
trans		输入	操作op(A)表示非转置或共轭转置。
n		输入	矩阵 op(A)、op(B) 和 C 的行数。
k		输入	矩阵 op(A) 和 op(B) 的列数。
alpha	主机或设备	输入	<type> 用于乘法的标量。
A	device	输入	<类型> 维度为 lda x k 的数组，当 transa == CUBLAS_OP_N 时要求 lda >= max(1, n)，否则为 lda x n 且 lda >= max(1, k)。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	device	输入	<类型> 维度为 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	device	输入/输出	<类型> 维度为 ldc x n 的数组，其中 ldc >= max(1, n)。对角线元素的虚部被假定并设为零。
ldc		输入	用于存储矩阵C的二维数组的主维度。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0 或 k < 0，或者 如果 trans 不是 CUBLAS_OP_N、CUBLAS_OP_T 和 CUBLAS_OP_C 其中之一，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 当 trans == CUBLAS_OP_N 时，如果 lda < max(1, n)；否则当 lda < max(1, k) 时 如果 ldc < max(1, n)，或者 如果 alpha 或 beta 为 NULL，或者 如果当beta不为零时C为NULL
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

cherk(), zherk() 和

cher2k(), zher2k()

2.8. 类BLAS扩展

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

2.8.1. cublasgeam()

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)可以是非转置或(conj.)转置。
m		输入	矩阵 op(A) 和 C 的行数。
n		输入	矩阵 op(B) 和 C 的列数。
alpha	主机或设备	输入	<类型> 用于乘法的标量。如果 *alpha == 0，则 A 不需要是有效输入。
A	device	输入	<类型> 维度数组 lda x n，当 transa == CUBLAS_OP_N 时要求 lda >= max(1, m)；否则为 lda x m 且 lda >= max(1, n)。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	device	输入	<类型> 维度为 ldb x n 的数组，当 transb == CUBLAS_OP_N 时要求 ldb >= max(1, m)；否则为 ldb x m 且 ldb>=max(1,n)。
ldb		输入	用于存储矩阵B的二维数组的主维度。
beta	主机或设备	输入	<type> 用于乘法的标量。如果 *beta == 0，则 B 不需要是有效输入。
C	device	输出	<类型> 维度数组 ldc x n，其中 ldc >= max(1, m)。
ldc		输入	用于存储矩阵C的二维数组的主维度。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
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)，或 如果 ldb < max(1, m) 当 transb == CUBLAS_OP_N 时，否则 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. cublasdgmm()

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{当 }\textsf{mode == $\mathrm{CUBLAS\_SIDE\_RIGHT}$}} \\ {diag(X) \times A} & {\text{当 }\textsf{mode == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ \end{matrix} \right.\)

其中 \(A\) 和 \(C\) 是以列主序格式存储的矩阵，维度为 \(m \times n\)。\(X\) 是一个向量，当 mode == CUBLAS_SIDE_RIGHT 时大小为 \(n\)，当 mode == CUBLAS_SIDE_LEFT 时大小为 \(m\)。\(X\) 从一维数组 x 中按步长 incx 采集。 incx 的绝对值表示步长，其符号表示步长方向。如果 incx 为正，则从第一个元素向前遍历 x；否则从最后一个元素向后遍历。X 的计算公式为

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

其中 \(\chi = m\) 当 mode == CUBLAS_SIDE_LEFT，而 \(\chi = n\) 当 mode == CUBLAS_SIDE_RIGHT。

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

示例2：如果用户想要执行\(\alpha \times A\)，那么有两种选择，要么使用cublasgeam()并设置*beta=0和transa == CUBLAS_OP_N，要么使用cublasdgmm()并设置incx=0和x[0]=alpha。

该操作是异地执行的。仅当lda = ldc时才能进行原地操作。

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
mode		输入	如果mode == CUBLAS_SIDE_LEFT则左乘，如果mode == CUBLAS_SIDE_RIGHT则右乘
m		输入	矩阵 A 和 C 的行数。
n		输入	矩阵 A 和 C 的列数。
A	device	输入	<类型> 维度数组 lda x n 满足 lda >= max(1, m)
lda		输入	用于存储矩阵A的二维数组的主维度。
x	device	输入	一维<类型>数组，大小为abs(incx) x m（当mode == CUBLAS_SIDE_LEFT时）或abs(incx) x n（当mode == CUBLAS_SIDE_RIGHT时）
incx		输入	一维数组x的步长。
C	device	输入/输出	<类型> 维度数组 ldc x n，其中 ldc >= max(1, m)。
ldc		输入	用于存储矩阵C的二维数组的主维度。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
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. cublasgetrfBatched()

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的两行。可以通过以下Matlab代码，利用PivotArray[i]的第j个元素来构造Pj。

// 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 的对角线元素会被丢弃。可以通过以下 Matlab 代码构建 L 和 U

// 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，cublasgetrfBatched支持非主元LU分解。

cublasgetrfBatched 支持任意维度。

cublasgetrfBatched 仅支持计算能力2.0及以上版本。

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
n		输入	Aarray[i]的行数和列数。
Aarray	device	输入/输出	指向<类型>数组的指针数组，每个数组的维度为n x n，且lda >= max(1, n)。矩阵Aarray[i]之间不应重叠，否则可能导致未定义行为。
lda		输入	用于存储每个矩阵Aarray[i]的二维数组的主维度。
PivotArray	device	输出	大小为n x batchSize的数组，包含以线性方式存储的每个Aarray[i]分解的旋转序列。如果PivotArray为NULL，则禁用旋转。
infoArray	device	输出	大小为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. cublasgetrsBatched()

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{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A^{T}\lbrack i\rbrack} & {\text{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_T}$}} \\ {A^{H}\lbrack i\rbrack} & {\text{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

此函数适用于矩阵尺寸较小且启动开销占主导因素的情况。

cublasgetrsBatched() 在 devIpiv 为 NULL 时支持非主元LU分解。

cublasgetrsBatched() 支持任意维度。

cublasgetrsBatched() 仅支持计算能力2.0及以上版本。

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
trans		输入	操作op(A)表示非转置或共轭转置。
n		输入	Aarray[i]的行数和列数。
nrhs		输入	Barray[i]的列数。
Aarray	device	输入	指向<类型>数组的指针数组，每个数组的维度为n x n，且lda >= max(1, n)。
lda		输入	用于存储每个矩阵Aarray[i]的二维数组的主维度。
devIpiv	device	输入	大小为n x batchSize的数组，以线性方式存储每个Aarray[i]分解的旋转序列。如果devIpiv为NULL，则忽略所有Aarray[i]的旋转。
Barray	device	输入/输出	指向<类型>数组的指针数组，每个数组的维度为n x nrhs，且ldb >= max(1, n)。矩阵Barray[i]之间不应重叠，否则可能导致未定义行为。
ldb		输入	用于存储每个解矩阵Barray[i]的二维数组的主维度。
信息	主机	输出	如果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 其中之一，或者 如果 lda < max(1, n)，或者 如果 ldb < max(1, n)
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

sgeqrs(), dgeqrs(), cgeqrs(), zgeqrs()

2.8.5. cublasgetriBatched()

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。

该函数执行矩阵A[i]的逆运算，其中i = 0, ..., batchSize-1。

在调用cublasgetriBatched之前，必须首先使用例程cublasgetrfBatched对矩阵A[i]进行分解。调用cublasgetrfBatched后，由Aarray[i]指向的矩阵将包含矩阵A[i]的LU因子，而由(PivotArray+i)指向的向量将包含主元交换序列。

在完成LU分解后，cublasgetriBatched使用前向和后向三角求解器来完成对矩阵A[i](i = 0, ..., batchSize-1)的求逆运算。该求逆运算是异地执行的，因此Carray[i]的内存空间不能与Array[i]的内存空间重叠。

通常，cublasgetrfBatched中的所有参数都会被传递到cublasgetriBatched中。例如，

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

用户可以从cublasgetrfBatched或cublasgetriBatched检查singularity。

此函数适用于矩阵尺寸较小且启动开销占主导因素的情况。

如果cublasgetrfBatched执行的是非主元消去法，那么cublasgetriBatched的PivotArray参数应设为NULL。

cublasgetriBatched 支持任意维度。

cublasgetriBatched 仅支持计算能力2.0或更高版本。

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
n		输入	Aarray[i]的行数和列数。
Aarray	device	输入	指向<类型>数组的指针数组，每个数组的维度为n*n，且lda >= max(1, n)。
lda		输入	用于存储每个矩阵Aarray[i]的二维数组的主维度。
PivotArray	device	输出	大小为n*batchSize的数组，以线性方式存储每个Aarray[i]分解的旋转序列。如果PivotArray为NULL，则禁用旋转。
Carray	device	输出	指向<类型>数组的指针数组，每个数组的维度为n*n，且ldc >= max(1, n)。矩阵Carray[i]之间不应重叠，否则可能导致未定义行为。
ldc		输入	用于存储每个矩阵Carray[i]的二维数组的主维度。
infoArray	device	输出	大小为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. cublasmatinvBatched()

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。

该函数执行矩阵A[i]的逆运算，其中i = 0, ..., batchSize-1。

该函数是cublasgetrfBatched()与cublasgetriBatched()的快捷组合。但当n大于32时无法使用。若超过此值，用户需分别调用cublasgetrfBatched()和cublasgetriBatched()。

如果矩阵 A[i] 是奇异的，那么 info[i] 会报告奇异性，与 cublasgetrfBatched() 相同。

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
n		输入	A[i]的行数和列数。
A	device	输入	指向<类型>数组的指针数组，每个数组的维度为n*n，且lda >= max(1, n)。
lda		输入	用于存储每个矩阵A[i]的二维数组的主维度。
Ainv	device	输出	指向<类型>数组的指针数组，每个数组的维度为n*n，且lda_inv >= max(1, n)。矩阵Ainv[i]不应重叠，否则可能导致未定义行为。
lda_inv		输入	用于存储每个矩阵Ainv[i]的二维数组的主维度。
信息	device	输出	大小为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. cublasgeqrfBatched()

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反射对每个Aarray[i]（其中i = 0, ...,batchSize-1）执行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]中。

此函数适用于矩阵尺寸较小且启动开销占主导因素的情况。

cublasgeqrfBatched 支持任意维度。

cublasgeqrfBatched 仅支持计算能力2.0或更高版本。

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
m		输入	行数 Aarray[i].
n		输入	Aarray[i]的列数。
Aarray	device	输入	指向<类型>数组的指针数组，每个数组的维度为m x n，且lda >= max(1, m)。
lda		输入	用于存储每个矩阵Aarray[i]的二维数组的主维度。
TauArray	device	输出	指向<类型>向量的指针数组，每个向量的维度为max(1 ,min(m, n))。
信息	主机	输出	如果 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. cublasgelsBatched()

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] 将被最小二乘解覆盖

cublasgelsBatched 仅支持非转置操作，并且只能求解超定系统（m >= n）。

cublasgelsBatched 仅支持计算能力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	device	输入/输出	指向<类型>数组的指针数组，每个数组的维度为m x n，当trans == CUBLAS_OP_N时lda >= max(1, m)，否则为n x m且lda >= max(1, n)（当前不支持）。矩阵Aarray[i]不应重叠，否则行为未定义。
lda		输入	用于存储每个矩阵Aarray[i]的二维数组的主维度。
Carray	device	输入/输出	指向<类型>数组的指针数组，每个数组的维度为m x nrhs，当trans == CUBLAS_OP_N时要求ldc >= max(1, m)，否则要求n x nrhs且lda >= max(1, n)（当前不支持）。矩阵Carray[i]之间不应重叠，否则行为未定义。
ldc		输入	用于存储每个矩阵Carray[i]的二维数组的主维度。
信息	主机	输出	如果 info == 0 表示传递给函数的参数是有效的 如果 info < 0 表示位置 -info 处的参数无效
devInfoArray	device	输出	可选的整数数组，维度为批次大小。 如果非空，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 或 trans 与非转置情况不同。
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

sgels(), dgels(), cgels(), zgels()

2.8.9. cublastpttr()

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的行数和列数。
AP	device	输入	<type> 数组，其中 \(A\) 以压缩格式存储。
A	device	输出	<类型> 维度数组 lda x n，其中 lda >= max(1, n)。A的另一侧保持不变。
lda		输入	用于存储矩阵A的二维数组的主维度。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 如果 lda < max(1, n)
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

stpttr(), dtpttr(), ctpttr(), ztpttr()

2.8.10. cublastrttp()

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	device	输入	<类型> 维度数组 lda x n，其中 lda >= max(1, n)。
lda		输入	用于存储矩阵A的二维数组的主维度。
AP	device	输出	<类型> 数组，其中A以压缩格式存储。

该函数可能返回的错误值及其含义如下所示。

错误值	含义
CUBLAS_STATUS_SUCCESS	操作成功完成
CUBLAS_STATUS_NOT_INITIALIZED	库未初始化
CUBLAS_STATUS_INVALID_VALUE	如果 n < 0 或 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 如果 lda < max(1, n)
CUBLAS_STATUS_EXECUTION_FAILED	该函数未能在GPU上启动

参考资料请查阅NETLIB文档：

strttp(), dtrttp(), ctrttp(), ztrttp()

2.8.11. cublasgemmEx()

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位整数接口。

此函数是cublasgemm()的扩展功能。在该函数中，输入矩阵和输出矩阵可以采用较低精度，但计算仍以类型执行。例如，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)可以是非转置或(conj.)转置。
m		输入	矩阵 op(A) 和 C 的行数。
n		输入	矩阵 op(B) 和 C 的列数。
k		输入	op(A)的列数与op(B)的行数。
alpha	主机或设备	输入	<type> 用于乘法的标量。
A	device	输入	<类型> 维度数组 lda x k，当 transa == CUBLAS_OP_N 时要求 lda >= max(1, m)，否则为 lda x m 且 lda >= max(1, k)。
Atype		输入	指定矩阵A数据类型的枚举值。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	device	输入	<类型> 维度为 ldb x n 的数组，当 transb == CUBLAS_OP_N 时需满足 ldb >= max(1, k)，否则为 ldb x k 且需满足 ldb>=max(1,n)。
Btype		输入	指定矩阵B数据类型的枚举值。
ldb		输入	用于存储矩阵B的二维数组的主维度。
beta	主机或设备	输入	<类型> 用于乘法的标量。如果 beta == 0，则 C 不需要是有效输入。
C	device	输入/输出	<类型> 维度数组 ldc x n，其中 ldc >= max(1, m)。
Ctype		输入	指定矩阵C数据类型的枚举值。
ldc		输入	用于存储矩阵C的二维数组的主维度。

以下是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() 仅在GPU架构能力等于或高于5.0时受支持
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)，否则 lda < max(1, k)，或者 当 transb == CUBLAS_OP_N 时，如果 ldb < max(1, k)；否则当 ldb < max(1, n) 时 如果 ldc < max(1, m)，或者 如果 alpha 或 beta 为 NULL，或者 如果当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位整数接口。

此函数是cublasgemm()的扩展，允许用户单独指定A、B和C矩阵的数据类型、计算精度以及要运行的GEMM算法。本节下文列出了支持的参数组合。

注意

为了与C++应用程序代码保持向后兼容，提供了cublasGemmEx()函数的第二种变体，其中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)可以是非转置或(conj.)转置。
m		输入	矩阵 op(A) 和 C 的行数。
n		输入	矩阵 op(B) 和 C 的列数。
k		输入	op(A)的列数与op(B)的行数。
alpha	主机或设备	输入	与computeType和Ctype对应的A*B类型的缩放因子，详情请参阅下表。
A	device	输入	<类型> 维度数组 lda x k，当 transa == CUBLAS_OP_N 时要求 lda >= max(1, m)，否则为 lda x m 且 lda >= max(1, k)。
Atype		输入	指定矩阵A数据类型的枚举值。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	device	输入	<类型> 维度为 ldb x n 的数组，当 transb == CUBLAS_OP_N 时需满足 ldb >= max(1, k)，否则为 ldb x k 且需满足 ldb>=max(1,n)。
Btype		输入	指定矩阵 B 数据类型的枚举值。
ldb		输入	用于存储矩阵B的二维数组的主维度。
beta	主机或设备	输入	与computeType和C类型对应的C的缩放因子，详情请参阅下表。如果beta == 0，则C不需要是有效输入。
C	device	输入/输出	<类型> 维度数组 ldc x n，其中 ldc >= max(1, m)。
Ctype		输入	指定矩阵C数据类型的枚举值。
ldc		输入	用于存储矩阵C的二维数组的主维度。
computeType		输入	指定计算类型的枚举值。
algo		输入	指定算法的枚举值。参见 cublasGemmAlgo_t。

cublasGemmEx() 支持以下计算类型、缩放类型、A类型/B类型和C类型：

计算类型	缩放类型(alpha和beta)	A类型/B类型	C类型
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 或 CUBLAS_COMPUTE_32F_EMULATED_16BFX9	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() 仅在GPU架构能力等于或高于5.0时受支持。
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)，否则 lda < max(1, k)，或者 当 transb == CUBLAS_OP_N 时，如果 ldb < max(1, k)；否则当 ldb < max(1, n) 时 如果 ldc < max(1, m)，或者 如果 alpha 或 beta 为 NULL，或者 如果当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位整数接口。

该函数是cublasgemmBatched()的扩展，可执行批量矩阵的矩阵乘法运算，并允许用户分别为A、B和C矩阵数组指定数据类型、计算精度以及要运行的GEMM算法。与cublasgemmBatched()类似，该批次被视为"统一"的，即所有实例的矩阵维度(m, n, k)、前导维度(lda, ldb, ldc)以及各自A、B和C矩阵的转置设置(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.\)

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

注意

\(C\lbrack i\rbrack\) 矩阵之间不能重叠，也就是说各个gemm运算必须能够独立计算；否则行为将是未定义的。

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

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
transa		输入	操作op(Aarray[i]) 是非转置或共轭转置。
transb		输入	操作op(Barray[i])可以是非转置或(conj.)转置。
m		输入	矩阵 op(Aarray[i]) 和 Carray[i]) 的行数。
n		输入	矩阵 op(Barray[i]) 和 Carray[i]) 的列数。
k		输入	op(Aarray[i])的列数与op(Barray[i])的行数。
alpha	主机或设备	输入	对应于computeType和C类型的矩阵乘积的缩放因子，详情请参阅下表。
Aarray	device	输入	指向<Atype>数组的指针数组，每个数组的维度为lda x k，当transa == CUBLAS_OP_N时lda >= max(1, m)，否则为lda x m且lda >= max(1, k)。 所有指针必须满足特定的对齐标准。详情请见下文。
Atype		输入	指定Aarray数据类型的枚举值。
lda		输入	用于存储矩阵Aarray[i]的二维数组的主维度。
Barray	device	输入	指向<Btype>数组的指针数组，每个数组的维度为ldb x n，当transb == CUBLAS_OP_N时要求ldb >= max(1, k)，否则维度为ldb x k且要求ldb>=max(1,n)。 所有指针必须满足特定的对齐标准。详情请见下文。
Btype		输入	指定Barray数据类型的枚举值。
ldb		输入	用于存储矩阵Barray[i]的二维数组的主维度。
beta	主机或设备	输入	与computeType和Ctype对应的Carray类型的缩放因子，详情请参阅下表。如果beta == 0，则Carray[i]不必是有效输入。
Carray	device	输入/输出	指向<Ctype>数组的指针数组。其维度为ldc x n，且满足ldc >= max(1, m)。矩阵Carray[i]之间不应重叠，否则行为将未定义。 所有指针必须满足特定的对齐标准。详情请见下文。
Ctype		输入	指定Carray数据类型的枚举值。
ldc		输入	用于存储每个矩阵Carray[i]的二维数组的主维度。
batchCount		输入	Aarray、Barray 和 Carray 中包含的指针数量。
computeType		输入	指定计算类型的枚举值。
algo		输入	指定算法的枚举值。参见 cublasGemmAlgo_t。

cublasGemmBatchedEx() 支持以下计算类型、缩放类型、A类型/B类型和C类型：

计算类型	缩放类型(alpha和beta)	A类型/B类型	C类型
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 或 CUBLAS_COMPUTE_32F_EMULATED_16BFX9	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() 仅在GPU架构能力等于或高于5.0时受支持。
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)，否则 lda < max(1, k)，或者 当 transb == CUBLAS_OP_N 时，如果 ldb < max(1, k)；否则当 ldb < max(1, n) 时 如果 ldc < max(1, m)，或者 如果 alpha 或 beta 为 NULL，或者 如果 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位整数接口。

该函数是cublasgemmStridedBatched()的扩展，用于执行批量矩阵乘法运算，并允许用户单独指定A、B和C矩阵的数据类型、计算精度以及要运行的GEMM算法。与cublasgemmStridedBatched()类似，该批次被视为"统一"的，即所有实例的矩阵维度(m, n, k)、前导维度(lda, ldb, ldc)和转置设置(transa, transb)都相同。批次中每个实例的输入矩阵A、B和输出矩阵C的位置相对于前一个实例的位置具有固定的元素偏移量。用户需要传入第一个实例的A、B和C矩阵指针，以及以元素数为单位的偏移量strideA、strideB和strideC，这些偏移量决定了后续实例中输入和输出矩阵的位置。

注意

为保持与C++应用程序代码的向后兼容性，提供了cublasGemmStridedBatchedEx()函数的第二种变体，其中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.\)

并且 \(\text{op}(B\lbrack i\rbrack)\) 对矩阵 \(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	主机或设备	输入	与computeType和Ctype对应的<缩放类型>中A*B的缩放因子，详情请参阅下表。
A	device	输入	指向<Atype>矩阵A的指针，对应批次中的第一个实例，当transa == CUBLAS_OP_N时维度为lda x k且lda >= max(1, m)，否则维度为lda x m且lda >= max(1, k)。
Atype		输入	指定A数据类型的枚举值。
lda		输入	用于存储矩阵A[i]的二维数组的主维度。
strideA		输入	类型为long long int的值，表示A[i]和A[i+1]之间以元素个数计算的偏移量。
B	device	输入	指向<Btype>矩阵B的指针，对应批次中的第一个实例，当transb == CUBLAS_OP_N时维度为ldb x n且ldb >= max(1, k)，否则维度为ldb x k且ldb>=max(1,n)。
Btype		输入	指定B数据类型的枚举值。
ldb		输入	用于存储矩阵B[i]的二维数组的主维度。
strideB		输入	类型为long long int的值，表示B[i]和B[i+1]之间以元素个数计算的偏移量。
beta	主机或设备	输入	对应于computeType和Ctype的<缩放类型>中C的缩放因子，详情请参阅下表。如果beta == 0，则C[i]不必是有效输入。
C	device	输入/输出	指向<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() 支持以下计算类型、缩放类型、A类型/B类型和C类型：

计算类型	缩放类型(alpha和beta)	A类型/B类型	C类型
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 或 CUBLAS_COMPUTE_32F_EMULATED_16BFX9	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() 仅在GPU架构能力等于或高于5.0时受支持。
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)，否则 lda < max(1, k)，或者 当 transb == CUBLAS_OP_N 时，如果 ldb < max(1, k)；否则当 ldb < max(1, n) 时 如果 ldc < max(1, m)，或者 如果 alpha 或 beta 为 NULL，或者 如果 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)、前导维度(lda, ldb, ldc)和转置设置(transa, transb)。但不同组之间的维度、前导维度、转置设置以及缩放因子(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}\)是指向按列主序存储的矩阵的指针数组。对于属于组\(i\)的给定索引\(\text{idx}\)，其维度为：

• \(\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接收两个不同长度的数组。维度数组、前导维度数组、转置数组和缩放因子数组的长度为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.\)

并且\(\text{op}(B[\text{idx}])\)对组\(i\)中的矩阵\(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	主机	输入	包含每个组的矩阵运算(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	device	输入	指向<Atype>数组的指针数组，每个数组的维度为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])。 所有指针必须满足特定的对齐标准。详情请见下文。	问题数量
Atype		输入	指定A数据类型的枚举值。
lda_array	主机	输入	包含用于存储每个组矩阵A[idx]的二维数组的前导维度的数组。	group_count
Barray	device	输入	指向<Btype>数组的指针数组，每个数组的维度为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])。 所有指针必须满足特定的对齐标准。详情请见下文。	问题数量
Btype		输入	指定B数据类型的枚举值。
ldb_array	主机	输入	包含用于存储每个组矩阵B[idx]的二维数组的前导维度的数组。	group_count
beta_array	主机	输入	包含用于每组乘法的<缩放类型>标量的数组。	group_count
Carray	device	输入/输出	指向<Ctype>数组的指针数组。其维度为ldc[i] x n[i]，其中ldc[i]>=max(1,m[i])。矩阵C[idx]不应重叠，否则可能导致未定义行为。 所有指针必须满足特定的对齐标准。详情请见下文。	问题数量
Ctype		输入	指定C数据类型的枚举项。
ldc_array	主机	输入	包含用于存储每个组矩阵C[idx]的二维数组的前导维度的数组。	group_count
group_count	主机	输入	组数
group_size	主机	输入	数组包含每组中Aarray、Barray和Carray所包含的指针数量。	group_count
computeType		输入	指定计算类型的枚举值。

cublasGemmGroupedBatchedEx() 支持以下计算类型、缩放类型、A类型/B类型和C类型：

计算类型	缩放类型(alpha和beta)	A类型/B类型	C类型
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 中的一种，或者 如果 lda_array[i] < max(1, m_array[i]) 当 transa_array[i] == CUBLAS_OP_N 时，或者 lda_array[i] < max(1, k_array[i]) 其他情况下 如果 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{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\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	device	输入	类型 维度为 lda x k 的数组，当 trans == CUBLAS_OP_N 时要求 lda >= max(1, n)；否则为 lda x n 的数组且要求 lda >= max(1, k)。
Atype		输入	指定矩阵A数据类型的枚举值。
lda		输入	用于存储矩阵A的二维数组的主维度。
beta	主机或设备	输入	<类型> 用于乘法的标量。如果 beta == 0 则 C 不需要是有效输入。
C	device	输入/输出	<类型> 维度为 ldc x n 的数组，其中 ldc >= max(1, n)。
Ctype		输入	指定矩阵C数据类型的枚举值。
ldc		输入	用于存储矩阵C的二维数组的主维度。

以下是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	如果 n < 0 或 k < 0，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 如果 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{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\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	device	输入	类型 维度为 lda x k 的数组，当 trans == CUBLAS_OP_N 时要求 lda >= max(1, n)；否则为 lda x n 的数组且要求 lda >= max(1, k)。
Atype		输入	指定矩阵A数据类型的枚举值。
lda		输入	用于存储矩阵A的二维数组的主维度。
beta	主机或设备	输入	<类型> 用于乘法的标量。如果 beta == 0 则 C 不需要是有效输入。
C	device	输入/输出	<类型> 维度为 ldc x n 的数组，其中 ldc >= max(1, n)。
Ctype		输入	指定矩阵C数据类型的枚举值。
ldc		输入	用于存储矩阵C的二维数组的主维度。

以下是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	如果 n < 0 或 k < 0，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 如果 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类型完成

该函数执行埃尔米特秩-\(k\)更新

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

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以下三角或上三角模式存储的厄米特矩阵，\(A\) 是一个维度为 \(\text{op}(A)\) \(n \times k\) 的矩阵。同样地，对于矩阵 \(A\)

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

注意

此例程仅在架构能力等于或大于5.0的GPU上受支持

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
uplo		输入	指示矩阵C的下三角或上三角部分是否被存储，另一侧的共轭对称部分不被引用。
trans		输入	操作op(A)表示非转置或共轭转置。
n		输入	矩阵 op(A) 和 C 的行数。
k		输入	矩阵 op(A) 的列数。
alpha	主机或设备	输入	<type> 用于乘法的标量。
A	device	输入	<类型> 维度为 lda x k 的数组，当 transa == CUBLAS_OP_N 时要求 lda >= max(1, n)，否则为 lda x n 且 lda >= max(1, k)。
Atype		输入	指定矩阵A数据类型的枚举值。
lda		输入	用于存储矩阵A的二维数组的主维度。
beta		输入	<类型> 用于乘法的标量。如果 beta == 0 则 C 不需要是有效输入。
C	device	输入/输出	<类型> 维度为 ldc x n 的数组，其中 ldc >= max(1, n)。对角线元素的虚部被假定并设为零。
Ctype		输入	指定矩阵C数据类型的枚举值。
ldc		输入	用于存储矩阵C的二维数组的主维度。

支持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	如果 n < 0 或 k < 0，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 如果 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%。

该函数执行埃尔米特秩-\(k\)更新

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

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以下三角或上三角模式存储的厄米特矩阵，\(A\) 是一个维度为 \(\text{op}(A)\) \(n \times k\) 的矩阵。同样地，对于矩阵 \(A\)

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

注意

此例程仅在架构能力等于或大于5.0的GPU上受支持

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
uplo		输入	指示矩阵C的下三角或上三角部分是否被存储，另一侧的共轭对称部分不被引用。
trans		输入	操作op(A)表示非转置或共轭转置。
n		输入	矩阵 op(A) 和 C 的行数。
k		输入	矩阵 op(A) 的列数。
alpha	主机或设备	输入	<type> 用于乘法的标量。
A	device	输入	类型 维度为 lda x k 的数组，当 trans == CUBLAS_OP_N 时要求 lda >= max(1, n)；否则为 lda x n 的数组且要求 lda >= max(1, k)。
Atype		输入	指定矩阵A数据类型的枚举值。
lda		输入	用于存储矩阵A的二维数组的主维度。
beta		输入	<类型> 用于乘法的标量。如果 beta == 0 则 C 不需要是有效输入。
C	device	输入/输出	<类型> 维度为 ldc x n 的数组，其中 ldc >= max(1, n)。对角线元素的虚部被假定并设为零。
Ctype		输入	指定矩阵C数据类型的枚举值。
ldc		输入	用于存储矩阵C的二维数组的主维度。

支持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	如果 n < 0 或 k < 0，或者 如果 uplo 不是 CUBLAS_FILL_MODE_LOWER 或 CUBLAS_FILL_MODE_UPPER 中的任意一个，或 如果 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位整数接口。

此函数是例程cublasnrm2()的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	device	输入	<类型> 包含 n 个元素的向量。
xType		输入	指定向量x数据类型的枚举值。
incx		输入	x中连续元素之间的步长。
result	主机或设备	输出	结果范数，如果n <= 0或incx <= 0则设为0。
resultType		输入	指定result数据类型的枚举值。
executionType		输入	指定执行计算所用数据类型的枚举值。

当前cublasNrm2Ex()支持的数据类型组合如下：

x	结果	执行
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位整数接口。

此函数是例程cublasaxpy()的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	device	输入	<类型> 包含 n 个元素的向量。
xType		输入	指定向量x数据类型的枚举常量。
incx		输入	x中连续元素之间的步长。
y	device	输入/输出	<类型> 包含 n 个元素的向量。
yType		输入	指定向量y数据类型的枚举值。
incy		输入	y中连续元素之间的步长。
executionType		输入	指定计算执行数据类型的枚举值。

当前支持的cublasAxpyEx()数据类型组合如下表所示：

alpha	x	y	执行
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位整数接口。

这些函数是cublasdot()和cublasdotc()例程的API泛化版本，其中输入数据、输出数据和计算类型可以独立指定。注意：cublasdotc()表示共轭点积，cublasdotu()表示非共轭点积。

该函数计算向量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元素的共轭复数，且最后两个等式反映了为与Fortran兼容而使用的基于1的索引方式。

参数	内存	输入/输出	含义
handle		输入	cuBLAS库上下文的句柄。
n		输入	向量x和y中的元素数量。
x	device	输入	<类型> 包含 n 个元素的向量。
xType		输入	指定向量x数据类型的枚举值。
incx		输入	x中连续元素之间的步长。
y	device	输入	<类型> 包含 n 个元素的向量。
yType		输入	指定向量y数据类型的枚举值。
incy		输入	y中连续元素之间的步长。
result	主机或设备	输出	结果点积，如果n <= 0则设为0
resultType		输入	指定result数据类型的枚举值。
executionType		输入	指定执行计算所用数据类型的枚举值。

当前cublasDotEx()和cublasDotcEx()支持的数据类型组合如下：

x	y	结果	执行
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位整数接口。

此函数是对常规cublasrot()的扩展，可以独立指定输入数据、输出数据、余弦/正弦类型以及计算类型。

该函数应用吉文斯旋转矩阵（即在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	device	输入/输出	<类型> 包含 n 个元素的向量。
xType		输入	指定向量x数据类型的枚举常量。
incx		输入	x中连续元素之间的步长。
y	device	输入/输出	<类型> 包含 n 个元素的向量。
yType		输入	指定向量y数据类型的枚举值。
incy		输入	y中连续元素之间的步长。
c	主机或设备	输入	旋转矩阵的余弦元素。
s	主机或设备	输入	旋转矩阵的正弦元素。
csType		输入	指定c和s数据类型的枚举值。
executionType		输入	指定执行计算所用数据类型的枚举值。

当前cublasRotEx()支持的数据类型组合如下：

执行类型	x类型 / y类型	cs类型
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位整数接口。

该函数将向量x按标量\(\alpha\)进行缩放，并用结果覆盖原向量。因此执行的操作是\(\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	device	输入/输出	<类型> 包含 n 个元素的向量。
xType		输入	指定向量x数据类型的枚举常量。
incx		输入	x中连续元素之间的步长。
executionType		输入	指定计算执行数据类型的枚举值。

当前支持的cublasScalEx()数据类型组合如下：

alpha	x	执行
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更新2开始，关于m、n和批量大小的问题尺寸限制已基本解决。该库的主要目标是提供性能最优的内核，这可能会带来一些隐含的限制。某些非标准配置可能需要用户手动处理，通常通过将问题分解为更小的部分来解决（参见Problem Size Limitations）。

3.1.1. 问题规模限制

由于CUDA网格维度的限制，存在固有的问题规模限制。例如，由于网格z维度的限制，许多内核不支持批量大小超过65535。对于给定问题的m和n值也存在类似的限制。

如果某个问题无法通过单个内核运行解决，cuBLASLt会尝试将问题分解为多个子问题，并通过在每个子问题上运行内核来解决。

There are some restrictions on cuBLASLt internal problem decomposition which are summarized below:

• 不支持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配置和其他参数选择最适合执行的矩阵乘法内核。这需要在主机CPU上执行一些计算，可能需要数十微秒。为了克服这种开销，建议使用cublasLtMatmulAlgoGetHeuristic()一次性查询启发式结果，然后在后续计算中通过cublasLtMatmul()复用该结果。

对于无法一次性查询启发式规则并重复使用的情况，cublaslt实现了一个启发式缓存，该缓存将矩阵乘法问题映射到先前通过启发式规则选定的内核。该启发式缓存采用类似LRU的淘汰策略，并且是线程安全的。

用户可以通过CUBLASLT_HEURISTICS_CACHE_CAPACITY环境变量或具有更高优先级的cublasLtHeuristicsCacheSetCapacity()函数来控制启发式缓存容量。容量以条目数计量，出于性能考虑可能会向上取整到某个因子的最近倍数。每个条目约占360字节（具体可能变动）。默认容量为8192个条目。

注意

将容量设置为零会完全禁用缓存。这对于没有稳定状态的工作负载非常有用，因为缓存操作的开销可能比常规启发式计算更高。

注意

出于性能考虑，该缓存并非理想方案，因此有时需要将其容量提升至预期唯一矩阵乘法问题数量的1.5-2倍，才能达到接近完美的命中率。

另请参阅: cublasLtHeuristicsCacheGetCapacity(), cublasLtHeuristicsCacheSetCapacity().

3.1.3. cuBLASLt 日志记录

可以通过在启动目标应用程序之前设置以下环境变量来启用cuBLASLt日志记录机制：

• CUBLASLT_LOG_LEVEL= 其中 为以下级别之一：

  • 0 - 关闭 - 日志记录已禁用（默认）

  • 1 - 错误 - 仅记录错误日志

  • 2 - 跟踪 - 调用启动CUDA内核的API将记录其参数和重要信息

  • 3 - 提示 - 可能提升应用性能的提示

  • 4 - 信息 - 提供关于库执行的一般信息，可能包含启发式算法状态的详细信息

  • 5 - API跟踪 - API调用将记录其参数和重要信息

• CUBLASLT_LOG_MASK=，其中是以下标志的组合：

  • 0 - 关闭

  • 1 - 错误

  • 2 - 追踪

  • 4 - 提示

  • 8 - 信息

  • 16 - API跟踪

  例如，使用CUBLASLT_LOG_MASK=5来启用错误和提示消息。

• CUBLASLT_LOG_FILE=，其中 是指向日志文件的路径。文件名可以包含 %i，它将被替换为进程ID。例如 file_name_%i.log。

如果未设置CUBLASLT_LOG_FILE，日志消息将打印到标准输出(stdout)。

另一个选项是使用实验性的cuBLASLt日志记录API。参见：

cublasLtLoggerSetCallback(), cublasLtLoggerSetFile(), cublasLtLoggerOpenFile(), cublasLtLoggerSetLevel(), cublasLtLoggerSetMask(), cublasLtLoggerForceDisable()

3.1.4. 窄精度数据类型使用

我们在此所称的窄精度数据类型最初是作为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或EPILOGUE_AUX；详见cublasLtMatmulDescAttributes_t）。缩放模式概述如下表所示，更多细节将在后续章节中提供。

扩展模式支持概览

模式	支持的计算能力	张量值数据类型	缩放因子数据类型	缩放因子布局
Tensorwide 扩展	8.9+	CUDA_R_8F_E4M3 / CUDA_R_8F_E5M2	CUDA_R_32F	标量
外部向量缩放	9.0	CUDA_R_8F_E4M3 / CUDA_R_8F_E5M2	CUDA_R_32F	向量
128元素一维块缩放	9.0	CUDA_R_8F_E4M3 / CUDA_R_8F_E5M2	CUDA_R_32F	Tensor
128x128元素二维块缩放	9.0	CUDA_R_8F_E4M3 / CUDA_R_8F_E5M2	CUDA_R_32F	Tensor
32元素一维块缩放	10.0+	CUDA_R_8F_E4M3 / CUDA_R_8F_E5M2	CUDA_R_8F_UE8M0 1	平铺张量 3
16元素一维块缩放	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 Block Scaling Factors Layout。

注意

缩放因子仅适用于窄精度矩阵乘法。如果为非窄精度矩阵乘法设置了任何缩放因子，cuBLAS将返回错误。此外，缩放因子通常仅支持窄精度张量。如果为非窄精度张量设置了相应的缩放因子，该设置将被忽略。唯一的例外是：在Ada和Hopper GPU上，允许对非窄数据类型的张量C设置缩放因子。

注意

当任何矩阵的cublasLtBatchMode_t设置为CUBLASLT_BATCH_MODE_POINTER_ARRAY时，仅支持Tensorwide缩放。

3.1.4.1. FP8数据类型的张量级缩放

当所有FP8精度张量的CUBLASLT_MATMUL_DESC_X_SCALE_MODE属性（此处X代表A、B、C、D或EPILOGUE_AUX；参见cublasLtMatmulDescAttributes_t）设置为CUBLASLT_MATMUL_MATRIX_SCALE_SCALAR_32F（这是FP8张量的默认值）时，将启用张量宽缩放。在这种情况下，cuBLAS中的矩阵乘法运算按以下方式定义（为说明起见，假设所有张量都使用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.4.2. FP8数据类型的向量外积缩放

这种缩放模式（也称为通道缩放或行缩放）是对张量整体缩放的改进。不同于将矩阵乘以单个标量，这里每个\(A\)的行和每个\(B\)的列都关联一个缩放因子：

\[D_{ij} = \alpha \cdot scale_A^i \cdot scale_B^j \sum_{l=1}^k a_{il}\cdot b_{lj} + \beta \cdot scale_C \cdot C_{ij}.\]

值得注意的是，\(scale_D\)不受支持，因为\(D\)唯一支持的精度是CUDA_R_16F、CUDA_R_16BF和CUDA_R_32F。

要启用外部向量缩放，必须将CUBLASLT_MATMUL_DESC_A_SCALE_MODE和CUBLASLT_MATMUL_DESC_B_SCALE_MODE属性设置为CUBLASLT_MATMUL_MATRIX_SCALE_OUTER_VEC_32F，同时不得修改所有其他缩放模式。

使用此缩放模式时，\(scale_A\)和\(scale_B\)必须分别是长度为\(M\)和\(N\)的向量。

3.1.4.3. FP8和FP4数据类型的16/32元素一维块缩放

一维块缩放旨在克服使用单一标量对整个张量进行缩放的局限性。OCP MXFP规范中对此有更详细的描述，因此我们在此仅作简要概述。块缩放意味着相邻值的16或32元素块内的元素会被分配一个共享的缩放因子。

目前，仅支持FP8精度和FP4精度张量的块缩放，不支持混合精度。要启用块缩放功能，必须为所有FP8精度张量将CUBLASLT_MATMUL_DESC_X_SCALE_MODE属性（此处X代表A、B、C、D或EPILOGUE_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).\]

广义点积可用于定义矩阵乘法，方法是在\(K\)维度上为\(A\)和\(B\)的每\(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}\]

现在，完整的矩阵乘法可以写成：

\[\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 Block Quantization 章节中有详细说明，而 \(Dequantize\) 的定义如下：

\[Dequantize\left(\left\{scale_C, C\right\})\right)_{i,j} = {scale_C}_{i/k,j} \cdot C_{i,j}.\]

注意

除了在量化过程中计算的\(scale_D^{out}\)外，当缩放因子使用CUDA_R_8F_UE4M3数据类型时，还会有一个针对\(D\)的输入标量张量级缩放因子\(scale_D^{in}\)。该因子用于在量化前"压缩"计算值。

3.1.4.3.1. 一维块量化

考虑在\(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)}\)。

为FP8与UE8M0比例计算缩放和转换因子

注意

除非另有说明，否则默认采用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{如果 } S^b_{fp32} \text{ 是规格化数且 } E^b_{int} < 254 \text{ 且 } M^b_{fixp} > 0 \\ E^b_{int} + 1, & \text{如果 } 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建议的舍入方案有所不同。

为FP4与UE4M3比例计算缩放和转换因子

我们假设算法提供了一个预先计算好的输入张量全局缩放因子\(scale_D^{in}\)，在一般情况下该因子计算公式为

\[scale_D^{in} = \frac{Amax(e2m1) \cdot Amax(e4m3)}{Amax(D_{temp})},\]

其中 \(Amax(D_{temp})\) 表示量化前矩阵乘法结果的全局绝对最大值。由于计算该值需要知道整个运算的结果，实践中通常使用前一迭代的近似值来代替。

计算包含以下步骤：

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\)在FP8使用UE8M0缩放因子时为\(S^b_{ue8m0}\)，在FP4使用UE4M3缩放因子时为\(S^b_{ue4m3}\)。

3.1.4.3.2. 一维块缩放因子布局

缩放因子采用平铺布局存储。下图展示了每个128x4平铺块在内存中的布局方式。内存偏移量从左到右递增，然后从上到下递增。

以下伪代码可用于在inner（A和B的K，C或D的M）和outer（A的M，B、C和D的N）索引与图块内的线性offset之间进行相互转换：

// Indices -> offset
offset = (outer % 32) * 16 + (outer / 32) * 4 + inner

// Offset -> Indices
outer = ((offset % 16) / 4) * 32 + (offset / 16)
inner = (offset % 4)

当缩放模式为CUBLASLT_MATMUL_MATRIX_SCALE_VEC16_UE4M3时，单个缩放因子图块应用于128x64块；当模式为CUBLASLT_MATMUL_MATRIX_SCALE_VEC32_UE8M0时，则应用于128x128块。

多个块按行优先方式排列。下图展示了一个示例。内存中的偏移量从左到右递增，然后从上到下递增。

通常，对于一个每行包含sf_inner_dim个缩放因子的张量，左上角坐标为(sf_outer, sf_inner)的块（使用与上述相同的矩阵坐标对应关系）的偏移量可以通过以下伪代码计算：

// Indices -> offset
//   note that sf_inner is a multiple of 4 due to the tiling layout
offset = (sf_inner + sf_outer * sf_inner_dim) * 128

注意

缩放因子的起始地址必须16字节对齐。

注意

请注意，上述描述的布局不支持转置操作。这意味着即使输入张量可以转置，缩放因子的布局也不会改变。

注意

请注意，当张量维度不是上述平铺大小的整数倍时，仍需要分配完整的平铺存储空间，并用零填充越界值。此外，在写入输出缩放因子时，内核可能会额外写入零值，因此最好不要对越界值的持久性做任何假设。

3.1.4.4. 针对FP8数据类型的128元素一维及128x128二维块缩放

这两种缩放模式将16/32元素一维块缩放方法(适用于FP8和FP4数据类型)的原理应用于Hopper GPU架构。不过这里的缩放数据类型是CUDA_R_32F，且\(A\)和\(B\)可以使用不同的缩放模式，而\(D\)唯一支持的精度为CUDA_R_16F、CUDA_R_16BF和CUDA_R_32F。

要启用此缩放模式，必须将CUBLASLT_MATMUL_DESC_X_SCALE_MODE属性（此处X代表A或B）设置为CUBLASLT_MATMUL_MATRIX_SCALE_VEC128_32F或CUBLASLT_MATMUL_MATRIX_SCALE_BLK128x128_32F，同时不得修改其他所有缩放模式。下表显示了支持的组合：

CUBLASLT_MATMUL_DESC_A_SCALE_MODE	CUBLASLT_MATMUL_DESC_B_SCALE_MODE	是否支持?
CUBLASLT_MATMUL_MATRIX_SCALE_VEC128_32F	CUBLASLT_MATMUL_MATRIX_SCALE_VEC128_32F	是
CUBLASLT_MATMUL_MATRIX_SCALE_VEC128_32F	CUBLASLT_MATMUL_MATRIX_SCALE_BLK128x128_32F	是
CUBLASLT_MATMUL_MATRIX_SCALE_BLK128x128_32F	CUBLASLT_MATMUL_MATRIX_SCALE_VEC128_32F	是
CUBLASLT_MATMUL_MATRIX_SCALE_BLK128x128_32F	CUBLASLT_MATMUL_MATRIX_SCALE_BLK128x128_32F	否

使用16/32元素1D块针对FP8和FP4数据类型的缩放中的表示法，我们可以按以下方式为\(A\)的第\(i\)行定义缩放块的序列：

\[\begin{split}L & = \lceil \frac{K}{128} \rceil, \\ A^{128}_i & = \left\{{scale_A}_{i,b}, \left[A_{i,(b-1)128+l}\right]_{l=1}^{128}\right\}_{b=1}^L, \text{(这是128元素一维块缩放)} \\ \\ p & = \lceil \frac{i}{128} \rceil, \\ A^{128 \times 128}_i & = \left\{{scale_A}_{p,b}, \left[A_{i,(b-1)128+l}\right]_{l=1}^{128}\right\}_{b=1}^L. \text{(这是128x128元素二维块缩放)} \\\end{split}\]

关于\(B\)的定义类似。矩阵乘法的定义与16/32-Element 1D Block Scaling for FP8 and FP4 Data Types中所述相同，显著区别在于使用2D块缩放时，整个128x128元素块采用单一缩放因子。

3.1.4.4.1. 缩放因子布局

注意

缩放因子的起始地址必须16字节对齐。

注意

\(M\) 和 \(N\) 必须是4的倍数。

对于CUBLASLT_MATMUL_MATRIX_SCALE_VEC128_32F缩放模式，缩放因子为：

• \(M\)主序的\(A\)矩阵，形状为\(M \times L\)（\(M\)主序表示内存中沿\(M\)维度的元素是连续的），

• \(N\)为主维度的\(B\)，形状为\(N \times L\)。

对于CUBLASLT_MATMUL_MATRIX_SCALE_BLK128x128_32F缩放模式，缩放因子采用\(K\)主序排列，且连续列之间的步长必须是4的倍数。设\(L_4 = \lceil L \rceil_4\)，其中\(\lceil \cdot \rceil_4\)表示向上取整至最近的4的倍数。因此

• 对于 \(A\)，缩放因子的形状为 \(L_4 \times \lceil \frac{M}{128} \rceil\)，

• 对于 \(B\)，缩放因子的形状为 \(L_4 \times \lceil \frac{N}{128} \rceil\)。

3.1.5. 禁用CPU指令

如启发式缓存部分所述，cuBLASLt启发式算法会在主机CPU上执行一些计算密集型操作。 为了加速这些操作，该实现会检测CPU能力并可能使用特殊指令，例如x86-64 CPU上的高级矢量扩展(AVX)。 但在极少数情况下，这可能不是理想选择。例如，使用高级指令可能导致CPU以较低频率运行，从而影响其他主机代码的性能。

用户可以选择性地通过CUBLASLT_DISABLE_CPU_INSTRUCTIONS_MASK环境变量或优先级更高的cublasLtDisableCpuInstructionsSetMask()函数，指示cuBLASLt库不使用某些CPU指令。 默认掩码为0，表示没有任何限制。

更多信息请查看cublasLtDisableCpuInstructionsSetMask()。

3.1.6. 原子操作同步

原子同步通过使cublasLtMatmul()能够与另一个并发运行的内核建立生产者或消费者关系，从而优化矩阵乘法工作负载。这允许以更细的粒度重叠计算和通信。从概念上讲，矩阵乘法被提供一个包含32位整数计数器的数组，然后：

• 在消费者模式下，矩阵A可以按行分块，或者矩阵B可以按列分块4。只有当对应的原子计数器值达到0时，才能从内存中读取数据块并用于计算。生产者需要执行内存屏障操作，以确保写入的值对并行运行的矩阵乘法内核可见5。

• 在生产者模式下，输出矩阵C（或异地模式下的D）按行或列进行分区。当一个数据块计算完成后，对应的原子计数器会被重置为0。在矩阵乘法内核运行之前，每个计数器必须初始化为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值，Matmul将返回错误。

分块数量由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}\]

对于行优先布局，需要交换分块尺寸和集群形状中的M和N。这些限制意味着必须首先通过cublasLtMatmulAlgoGetHeuristic()查询启发式结果，检查分块和集群形状，然后才能设置分块数量。

以下伪代码展示了其工作原理：

// 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（这些SM是生产者内核启动所需的）而无法启动。强烈建议设置CUBLASLT_MATMUL_DESC_SM_COUNT_TARGET来为非矩阵乘法（通常是通信）内核预留部分SM以供执行。

• 如果在消费者内核启动之后但在生产者内核启动之前调用cudaDeviceSynchronize()。

• 当启用延迟模块加载时，由于CUDA运行时库中的锁定，消费者内核运行时可能无法加载生产者内核。为避免这种情况，两个内核必须在同时运行前完成加载。使用CUDA Graphs是另一种避免因延迟加载导致死锁的方法。

注意

此功能面向高级用户，仅在Hopper架构上可用，适用于启用快速累加模式的FP8非批处理场景，由于使用限制较多，目前处于测试阶段。

3.2. cuBLASLt 代码示例

请访问 https://github.com/NVIDIA/CUDALibrarySamples/tree/master/cuBLASLt 获取最新的代码示例。

3.3. cuBLASLt 数据类型参考

3.3.1. cublasLtClusterShape_t

cublasLtClusterShape_t 是一个枚举类型，用于配置线程块集群的维度。线程块集群添加了一个可选的层次级别，由线程块组成。与线程块类似，这些集群可以是一维、二维或三维的。另请参阅Thread Block Clusters。

值	描述
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 是一个枚举类型，用于设置后处理（epilogue）的选项。

值	描述
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和偏置梯度。将ReLu梯度存储在输出矩阵中，偏置梯度存储在偏置缓冲区中（参见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	应用偏置后进行GELU变换 7。
CUBLASLT_EPILOGUE_GELU_AUX_BIAS = CUBLASLT_EPILOGUE_GELU_AUX = CUBLASLT_EPILOGUE_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和偏置梯度。将GELU梯度存储在输出矩阵中，偏置梯度存储在偏置缓冲区（参见CUBLASLT_MATMUL_DESC_BIAS_POINTER）。此结尾模式需要一个额外输入，详见cublasLtMatmulDescAttributes_t中的CUBLASLT_MATMUL_DESC_EPILOGUE_AUX_POINTER。
CUBLASLT_EPILOGUE_BGRADA = 256	将偏置梯度应用于输入矩阵A。偏置大小对应于矩阵D的行数。归约操作发生在GEMM的"k"维度上。将偏置梯度存储在偏置缓冲区中，参见cublasLtMatmulDescAttributes_t的CUBLASLT_MATMUL_DESC_BIAS_POINTER。
CUBLASLT_EPILOGUE_BGRADB = 512	将偏置梯度应用于输入矩阵B。偏置大小对应于矩阵D的列数。归约操作发生在GEMM的"k"维度上。将偏置梯度存储在偏置缓冲区中，请参阅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)\)

注意

当任何矩阵的cublasLtBatchMode_t设置为CUBLASLT_BATCH_MODE_POINTER_ARRAY时，仅支持CUBLASLT_EPILOGUE_DEFAULT。

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 Logging。
functionName		输出	记录此消息的API名称。
message		输出	日志消息。

3.3.5. cublasLtMatmulAlgo_t

cublasLtMatmulAlgo_t 是一个不透明结构体，用于描述矩阵乘法算法。该结构体可以轻松序列化，并在后续与相同版本的cuBLAS库一起使用时恢复，以避免重复选择正确的配置。

3.3.6. cublasLtMatmulAlgoCapAttributes_t

cublasLtMatmulAlgoCapAttributes_t 枚举了矩阵乘法算法的能力属性，这些属性可以通过cublasLtMatmulAlgoCapGetAttribute()函数从已初始化的cublasLtMatmulAlgo_t描述符中获取。

值	描述	数据类型
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-swizzling功能。布尔值(0或1)用于表示是否支持CTA-swizzling实现。0表示不支持，1表示支持；其他值保留。另请参阅cublasLtMatmulAlgoConfigAttributes_t中的CUBLASLT_ALGO_CONFIG_CTA_SWIZZLING。	uint32_t
CUBLASLT_ALGO_CAP_STRIDED_BATCH_SUPPORT	支持跨步批处理。0表示不支持，其他值表示支持。	int32_t
CUBLASLT_ALGO_CAP_POINTER_ARRAY_BATCH_SUPPORT	支持指针数组批量处理。0表示不支持，其他值表示支持。	int32_t
CUBLASLT_ALGO_CAP_OUT_OF_PLACE_RESULT_SUPPORT	支持结果位置不匹配（在D = alpha.A.B + beta.C公式中D不等于C）。0表示不支持，其他值表示支持。	int32_t
CUBLASLT_ALGO_CAP_UPLO_SUPPORT	Syrk（对称秩k更新）/herk（厄米特秩k更新）支持（基于常规gemm）。0表示不支持，其他值表示支持。	int32_t
CUBLASLT_ALGO_CAP_TILE_IDS	可使用的瓦片ID。参见cublasLtMatmulTile_t。如果不支持任何瓦片ID，则使用CUBLASLT_MATMUL_TILE_UNDEFINED。使用cublasLtMatmulAlgoCapGetAttribute()并设置sizeInBytes = 0来查询实际数量。	uint32_t[]
CUBLASLT_ALGO_CAP_STAGES_IDS	可使用的阶段ID。参见cublasLtMatmulStages_t。如果不支持任何阶段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	指示该算法是否实现了复数矩阵乘法的高斯优化。0表示常规计算；1表示高斯优化。参见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
CUBLASLT_ALGO_CAP_FLOATING_POINT_EMULATION_SUPPORT	支持浮点运算模拟。参见Floating Point Emulation。	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	瓦片ID。参见cublasLtMatmulTile_t。默认值：CUBLASLT_MATMUL_TILE_UNDEFINED。	uint32_t
CUBLASLT_ALGO_CONFIG_STAGES_ID	阶段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	设备内存中的偏置或偏置梯度向量指针。 当使用以下任一结尾操作时，输入向量的长度需与矩阵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时，偏置向量元素与alpha和beta类型相同（参见本表中的CUBLASLT_MATMUL_DESC_SCALE_TYPE），否则与矩阵D的数据类型相同。详细映射关系请参阅cublasLtMatmul()下的数据类型表。默认值为：NULL。	void * / const void *
CUBLASLT_MATMUL_DESC_BIAS_BATCH_STRIDE	在跨步批量操作中，到下一个偏置或偏置梯度向量的步长（以元素为单位）。默认值为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	epilogue辅助缓冲区的前导维度。 当使用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向量。若任何矩阵的cublasLtBatchMode_t设为CUBLASLT_BATCH_MODE_POINTER_ARRAY，则必须将CUBLASLT_MATMUL_DESC_ALPHA_VECTOR_BATCH_STRIDE设为0。默认值：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。 偏置类型为 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	设备内存中偏置或偏置梯度向量的类型。偏置情况：参见CUBLASLT_EPILOGUE_BIAS。如果未设置（或设置为默认值-1），则偏置向量元素与输出矩阵（Dtype）元素类型相同，但以下情况例外： 使用computeType=CUDA_R_32I和Ctype=CUDA_R_8I的IMMA内核，其中偏置向量元素与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	指向由矩阵乘法消耗的输入原子计数器设备数组的指针。当计数器归零时，允许开始计算输出张量的相应块。默认值：NULL。参见原子同步。	int32_t *
CUBLASLT_MATMUL_DESC_ATOMIC_SYNC_OUT_COUNTERS_POINTER	指向由矩阵乘法生成的输出原子计数器设备数组的指针。当输出张量对应块的计算完成时，矩阵乘法内核会将计数器置零。在运行矩阵乘法内核前，所有计数器必须初始化为1。默认值：NULL。参见原子操作同步。	int32_t *
CUBLASLT_MATMUL_DESC_ATOMIC_SYNC_NUM_CHUNKS_D_ROWS [已弃用]	此模式已弃用，将在未来版本中移除。输出矩阵D行维度中的原子同步块数量。每个块对应一个原子计数器。默认值：0（禁用原子同步）。参见Atomics Synchronization。	int32_t
CUBLASLT_MATMUL_DESC_ATOMIC_SYNC_NUM_CHUNKS_D_COLS [已弃用]	此模式已弃用，将在未来版本中移除。输出矩阵D列维度中的原子同步块数量。每个块对应一个原子计数器。默认值：0（禁用原子同步）。参见Atomics Synchronization。	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() 来获取和设置矩阵乘法偏好描述符的属性值。

值	描述	数据类型
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的算法，因为矩阵A的对齐方式不如算法要求的严格。默认值为256字节。	uint32_t
CUBLASLT_MATMUL_PREF_MIN_ALIGNMENT_B_BYTES	矩阵B的最小缓冲区对齐（以字节为单位）。选择较小的值将排除那些无法处理矩阵B的算法，因为这些算法对矩阵B的对齐要求不如算法本身严格。默认值为256字节。	uint32_t
CUBLASLT_MATMUL_PREF_MIN_ALIGNMENT_C_BYTES	矩阵C的最小缓冲区对齐（以字节为单位）。选择较小的值将排除那些无法处理矩阵C的算法，因为这些算法对矩阵C的对齐要求更为严格。默认值为256字节。	uint32_t
CUBLASLT_MATMUL_PREF_MIN_ALIGNMENT_D_BYTES	矩阵D的最小缓冲区对齐（以字节为单位）。选择较小的值将排除那些无法处理矩阵D的算法，因为这些算法对矩阵D的对齐要求更为严格。默认值为256字节。	uint32_t
CUBLASLT_MATMUL_PREF_MAX_WAVES_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 列数形式的矩阵分块尺寸。另请参阅CUTLASS: Fast Linear Algebra in CUDA C++。

值	描述
CUBLASLT_MATMUL_TILE_UNDEFINED	瓦片大小未定义。
CUBLASLT_MATMUL_TILE_8x8	瓦片大小为8行x8列。
CUBLASLT_MATMUL_TILE_8x16	瓦片大小为8行x16列。
CUBLASLT_MATMUL_TILE_16x8	瓦片大小为16行 x 8列。
CUBLASLT_MATMUL_TILE_8x32	瓦片大小为8行 x 32列。
CUBLASLT_MATMUL_TILE_16x16	瓦片大小为16行 x 16列。
CUBLASLT_MATMUL_TILE_32x8	瓦片大小为32行 x 8列。
CUBLASLT_MATMUL_TILE_8x64	瓦片大小为8行x64列。
CUBLASLT_MATMUL_TILE_16x32	瓦片大小为16行 x 32列。
CUBLASLT_MATMUL_TILE_32x16	瓦片大小为32行 x 16列。
CUBLASLT_MATMUL_TILE_64x8	瓦片大小为64行 x 8列。
CUBLASLT_MATMUL_TILE_32x32	瓦片大小为32行 x 32列。
CUBLASLT_MATMUL_TILE_32x64	瓦片大小为32行x64列。
CUBLASLT_MATMUL_TILE_64x32	瓦片大小为64行 x 32列。
CUBLASLT_MATMUL_TILE_32x128	瓦片大小为32行 x 128列。
CUBLASLT_MATMUL_TILE_64x64	瓦片大小为64行x64列。
CUBLASLT_MATMUL_TILE_128x32	瓦片大小为128行 x 32列。
CUBLASLT_MATMUL_TILE_64x128	瓦片大小为64行 x 128列。
CUBLASLT_MATMUL_TILE_128x64	瓦片大小为128行 x 64列。
CUBLASLT_MATMUL_TILE_64x256	瓦片大小为64行 x 256列。
CUBLASLT_MATMUL_TILE_128x128	瓦片大小为128行 x 128列。
CUBLASLT_MATMUL_TILE_256x64	瓦片大小为256行 x 64列。
CUBLASLT_MATMUL_TILE_64x512	分块大小为64行 x 512列。
CUBLASLT_MATMUL_TILE_128x256	区块大小为128行 x 256列。
CUBLASLT_MATMUL_TILE_256x128	区块大小为256行 x 128列。
CUBLASLT_MATMUL_TILE_512x64	区块大小为512行 x 64列。
CUBLASLT_MATMUL_TILE_64x96	瓦片大小为64行 x 96列。
CUBLASLT_MATMUL_TILE_96x64	瓦片大小为96行 x 64列。
CUBLASLT_MATMUL_TILE_96x128	瓦片大小为96行 x 128列。
CUBLASLT_MATMUL_TILE_128x160	分块大小为128行 x 160列。
CUBLASLT_MATMUL_TILE_160x128	区块大小为160行 x 128列。
CUBLASLT_MATMUL_TILE_192x128	瓦片大小为192行 x 128列。
CUBLASLT_MATMUL_TILE_128x192	瓦片大小为128行 x 192列。
CUBLASLT_MATMUL_TILE_128x96	瓦片大小为128行 x 96列。

3.3.16. cublasLtMatmulStages_t

cublasLtMatmulStages_t 是一个枚举类型，用于配置暂存输入元素的共享内存缓冲区的大小和数量。暂存缓冲区的数量决定了内核流水线的深度。

值	描述
CUBLASLT_MATMUL_STAGES_UNDEFINED	阶段大小未定义。
CUBLASLT_MATMUL_STAGES_16x1	阶段大小为16，阶段数量为1。
CUBLASLT_MATMUL_STAGES_16x2	阶段大小为16，阶段数量为2。
CUBLASLT_MATMUL_STAGES_16x3	阶段大小为16，阶段数量为3。
CUBLASLT_MATMUL_STAGES_16x4	阶段大小为16，阶段数量为4。
CUBLASLT_MATMUL_STAGES_16x5	阶段大小为16，阶段数量为5。
CUBLASLT_MATMUL_STAGES_16x6	阶段大小为16，阶段数量为6。
CUBLASLT_MATMUL_STAGES_32x1	阶段大小为32，阶段数量为1。
CUBLASLT_MATMUL_STAGES_32x2	阶段大小为32，阶段数量为2。
CUBLASLT_MATMUL_STAGES_32x3	阶段大小为32，阶段数量为3。
CUBLASLT_MATMUL_STAGES_32x4	阶段大小为32，阶段数量为4。
CUBLASLT_MATMUL_STAGES_32x5	阶段大小为32，阶段数量为5。
CUBLASLT_MATMUL_STAGES_32x6	阶段大小为32，阶段数量为6。
CUBLASLT_MATMUL_STAGES_64x1	阶段大小为64，阶段数量为1。
CUBLASLT_MATMUL_STAGES_64x2	阶段大小为64，阶段数量为2。
CUBLASLT_MATMUL_STAGES_64x3	阶段大小为64，阶段数量为3。
CUBLASLT_MATMUL_STAGES_64x4	阶段大小为64，阶段数量为4。
CUBLASLT_MATMUL_STAGES_64x5	阶段大小为64，阶段数量为5。
CUBLASLT_MATMUL_STAGES_64x6	阶段大小为64，阶段数量为6。
CUBLASLT_MATMUL_STAGES_128x1	阶段大小为128，阶段数量为1。
CUBLASLT_MATMUL_STAGES_128x2	阶段大小为128，阶段数量为2。
CUBLASLT_MATMUL_STAGES_128x3	阶段大小为128，阶段数量为3。
CUBLASLT_MATMUL_STAGES_128x4	阶段大小为128，阶段数量为4。
CUBLASLT_MATMUL_STAGES_128x5	阶段大小为128，阶段数量为5。
CUBLASLT_MATMUL_STAGES_128x6	阶段大小为128，阶段数量为6。
CUBLASLT_MATMUL_STAGES_32x10	阶段大小为32，阶段数量为10。
CUBLASLT_MATMUL_STAGES_8x4	阶段大小为8，阶段数量为4。
CUBLASLT_MATMUL_STAGES_16x10	阶段大小为16，阶段数量为10。
CUBLASLT_MATMUL_STAGES_8x5	阶段大小为8，阶段数量为5。
CUBLASLT_MATMUL_STAGES_8x3	阶段大小为8，阶段数量为3。
CUBLASLT_MATMUL_STAGES_8xAUTO	阶段大小为8，阶段数量自动选择。
CUBLASLT_MATMUL_STAGES_16xAUTO	阶段大小为16，阶段数量自动选择。
CUBLASLT_MATMUL_STAGES_32xAUTO	阶段大小为32，阶段数量自动选择。
CUBLASLT_MATMUL_STAGES_64xAUTO	阶段大小为64，阶段数量自动选择。
CUBLASLT_MATMUL_STAGES_128xAUTO	阶段大小为128，阶段数量自动选择。
CUBLASLT_MATMUL_STAGES_256xAUTO	阶段大小为256，阶段数量自动选择。

3.3.17. cublasLtNumericalImplFlags_t

cublasLtNumericalImplFlags_t: 一组位标志，可用于选择可能影响算法数值行为的实现细节。

以下标志可以通过按位或运算符“|”组合使用。

值	描述
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. cublasLt矩阵布局属性类型

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	矩阵的主维度。对于CUBLASLT_ORDER_COL，这表示矩阵列的跨度（以元素为单位）。另请参阅cublasLtOrder_t。 目前仅支持非负数值。 必须足够大，以确保矩阵内存位置不会重叠（例如，在CUBLASLT_ORDER_COL情况下，需大于或等于CUBLASLT_MATRIX_LAYOUT_ROWS）。	int64_t
CUBLASLT_MATRIX_LAYOUT_BATCH_COUNT	批量执行的矩阵乘法运算数量。默认值为1。另请参阅cublasLtMatmulAlgoCapAttributes_t中的CUBLASLT_ALGO_CAP_STRIDED_BATCH_SUPPORT和CUBLASLT_ALGO_CAP_POINTER_ARRAY_BATCH_SUPPORT。	int32_t
CUBLASLT_MATRIX_LAYOUT_STRIDED_BATCH_OFFSET	跨步批处理操作中到下一个矩阵的元素步长。默认值为0。当矩阵类型为平面复数（CUBLASLT_MATRIX_LAYOUT_PLANE_OFFSET != 0）时，cublasLtMatmul()会将批处理步长解释为实值子元素的数量。例如，对于CUDA_C_16F类型的数据，1024字节的偏移量被编码为步长值512（因为实部和虚部矩阵的每个元素都是2字节（16位）浮点类型）。注意：cublasLtMatrixTransform()中存在一个错误，导致它将平面复数矩阵的批处理步长解释为复数元素的数量。因此，在调用cublasLtMatrixTransform()时，1024字节的偏移量必须编码为步长值256（每个复数元素为4字节，实部和虚部各占2字节）。此行为预计将在下一个主要cuBLAS版本中修正。	int64_t
CUBLASLT_MATRIX_LAYOUT_PLANE_OFFSET	平面复数布局中到虚数平面的步长（以字节为单位）。默认值为0，表示布局是常规的（复数的实部和虚部在内存中为每个元素交错排列）。	int64_t
CUBLASLT_MATRIX_LAYOUT_BATCH_MODE	矩阵的批量模式。默认值为CUBLASLT_BATCH_MODE_STRIDED。参见cublasLtBatchMode_t。	int32_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	数据以列优先格式排列。主维度是内存中到下一列起始位置的步长（以元素为单位）。
CUBLASLT_ORDER_ROW	数据按行优先格式排列。主维度是指内存中到下一行起始位置的跨度（以元素为单位）。
CUBLASLT_ORDER_COL32	数据按32列的列主序块排列。前导维度是指到下一组32列起始位置的跨度（以元素为单位）。 例如，如果矩阵有33列和2行，那么前导维度必须至少为32 * 2 = 64。
CUBLASLT_ORDER_COL4_4R2_8C	数据以列优先顺序排列在复合图块中，每个复合图块包含32列和8行。一个图块由交错的内层图块组成，每个内层图块包含4列，分布在4个偶数或奇数行中，呈交替模式。 前导维度是指到达下一个32列组中第一个32列×8行图块起始位置的跨度（以元素为单位）。例如，如果矩阵有33列和1行， 前导维度必须至少为(32 * 8) * 1 = 256。
CUBLASLT_ORDER_COL32_2R_4R4	数据以列优先顺序排列在复合图块中，每个图块共32列32行。图块内元素偏移量计算公式为(((row % 8) / 2 * 4 + row / 8) * 2 + row % 2) * 32 + col。 前导维度是指到达下一个32列组中第一个32列x32行图块起始位置的跨度（以元素为单位）。例如，若矩阵有33列1行，则其前导维度至少需为(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 是主机内存中的单个值。

注意

当任何矩阵的cublasLtBatchMode_t设置为CUBLASLT_BATCH_MODE_POINTER_ARRAY时，仅支持指针模式CUBLASLT_POINTER_MODE_HOST和CUBLASLT_POINTER_MODE_DEVICE。

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	缩放因子是张量，其中包含一个专用的缩放因子，存储为8位CUDA_R_8F_UE4M3值，对应数据张量最内层维度中的每个16元素块。
CUBLASLT_MATMUL_MATRIX_SCALE_VEC32_UE8M0	缩放因子是张量，其中包含针对对应数据张量最内维度中每个32元素块的专用缩放因子，存储为8位CUDA_R_8F_UE8M0值。
CUBLASLT_MATMUL_MATRIX_SCALE_OUTER_VEC_32F	缩放因子是CUDA_R_32F值的向量。此模式仅适用于矩阵A和B，在这种情况下，向量应分别具有M和N个元素，并且A和B乘积的每个(i,j)元素将乘以A缩放的第i个元素和B缩放的第j个元素。
CUBLASLT_MATMUL_MATRIX_SCALE_VEC128_32F	缩放因子是张量，其中包含对应数据张量最内层维度中每个128元素块的专用CUDA_R_32F缩放因子。
CUBLASLT_MATMUL_MATRIX_SCALE_BLK128x128_32F	缩放因子是张量，其中包含对应数据张量中每个128x128元素块的专用CUDA_R_32F缩放因子。

3.3.27. cublasLtBatchMode_t

值	描述
CUBLASLT_BATCH_MODE_STRIDED	批次中每个实例的矩阵都位于前一个实例位置的固定元素偏移量处。
CUBLASLT_BATCH_MODE_POINTER_ARRAY	批次中每个实例矩阵的地址是从指针数组中读取的。

3.4. cuBLASLt API参考

3.4.1. cublasLtCreate()

cublasStatus_t
      cublasLtCreate(cublasLtHandle_t *lighthandle)

此函数初始化cuBLASLt库，并创建一个指向持有cuBLASLt库上下文的不透明结构的句柄。它会在主机和设备上分配轻量级硬件资源，必须在调用任何其他cuBLASLt库函数之前调用。

cuBLASLt库上下文与当前CUDA设备绑定。要在多个设备上使用该库，必须为每个设备创建一个cuBLASLt句柄。此外，在调用与特定设备绑定的cuBLASLt函数之前，必须先将该设备设置为当前设备。

另请参阅：cuBLAS Context。

参数：

参数	内存	输入/输出	描述
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 为空

查看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 为空

查看cublasStatus_t获取完整有效返回码列表。

3.4.3. cublasLtDisableCpuInstructionsSetMask()

unsigned cublasLtDisableCpuInstructionsSetMask(unsigned mask);

指示cuBLASLt库不使用mask中标志指定的CPU指令。 该函数优先于CUBLASLT_DISABLE_CPU_INSTRUCTIONS_MASK环境变量。

参数： mask – 通过按位OR(|)运算符组合的标志，用于指定不应使用哪些CPU指令。

支持的标志：

值	描述
0x1	x86-64 AVX512指令集架构。

返回值： mask 的前一个值。

3.4.4. cublasLtGetCudartVersion()

size_t cublasLtGetCudartVersion(void);

该函数返回CUDA运行时库的版本号。

参数： 无。

返回值：size_t - CUDA运行时库的版本号。

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

返回Heuristics Cache的容量。

参数：

参数	描述
capacity	指向返回容量值的指针。

返回：

返回值	描述
CUBLAS_STATUS_SUCCESS	容量已成功写入。
CUBLAS_STATUS_INVALID_VALUE	容量已成功设置。

3.4.9. cublasLtHeuristicsCacheSetCapacity()

cublasStatus_t cublasLtHeuristicsCacheSetCapacity(size_t capacity);

设置启发式缓存的容量。将容量设为0可禁用启发式缓存。

该函数优先级高于CUBLASLT_HEURISTICS_CACHE_CAPACITY环境变量。

参数：

参数	描述
capacity	理想的启发式缓存容量。

返回：

返回值	描述
CUBLAS_STATUS_SUCCESS	容量已成功设置。

3.4.10. cublasLtGetVersion()

size_t cublasLtGetVersion(void);

该函数返回cuBLASLt库的版本号。

参数： 无。

返回：size_t - cuBLASLt库的版本号。

3.4.11. cublasLtLoggerSetCallback()

cublasStatus_t cublasLtLoggerSetCallback(cublasLtLoggerCallback_t callback);

实验性功能：此函数用于设置日志记录回调函数。

参数:

参数	内存	输入/输出	描述
callback		输入	指向回调函数的指针。参见 cublasLtLoggerCallback_t。

返回:

返回值	描述
CUBLAS_STATUS_SUCCESS	如果回调函数设置成功。

请参阅cublasStatus_t获取完整的有效返回代码列表。

3.4.12. cublasLtLoggerSetFile()

cublasStatus_t cublasLtLoggerSetFile(FILE* file);

实验性功能：此函数用于设置日志输出文件。注意：一旦通过此函数调用注册后，除非再次调用该函数切换至不同的文件句柄，否则不得关闭所提供的文件句柄。

参数:

参数	内存	输入/输出	描述
file		输入	指向一个已打开文件的指针。该文件应具有写入权限。

返回:

返回值	描述
CUBLAS_STATUS_SUCCESS	如果日志文件设置成功。

查看cublasStatus_t获取完整有效返回码列表。

3.4.13. cublasLtLoggerOpenFile()

cublasStatus_t cublasLtLoggerOpenFile(const char* logFile);

实验性功能：此函数在指定路径下打开一个日志输出文件。

参数:

参数	内存	输入/输出	描述
logFile		输入	日志输出文件的路径。

返回:

返回值	描述
CUBLAS_STATUS_SUCCESS	如果日志文件成功打开。

查看cublasStatus_t获取完整有效返回码列表。

3.4.14. cublasLtLoggerSetLevel()

cublasStatus_t cublasLtLoggerSetLevel(int level);

实验性功能：此函数用于设置日志记录级别的值。

参数:

参数	内存	输入/输出	描述
level		输入	日志记录级别的值。请参阅cuBLASLt Logging。

返回:

返回值	描述
CUBLAS_STATUS_INVALID_VALUE	如果该值不是有效的日志级别。请参阅cuBLASLt Logging。
CUBLAS_STATUS_SUCCESS	如果日志级别设置成功。

查看cublasStatus_t获取完整有效返回码列表。

3.4.15. cublasLtLoggerSetMask()

cublasStatus_t cublasLtLoggerSetMask(int mask);

实验性功能：此函数用于设置日志掩码的值。

参数:

参数	内存	输入/输出	描述
mask		输入	日志掩码的值。请参阅cuBLASLt Logging。

返回:

返回值	描述
CUBLAS_STATUS_SUCCESS	如果日志掩码设置成功。

查看cublasStatus_t获取完整有效返回码列表。

3.4.16. cublasLtLoggerForceDisable()

cublasStatus_t cublasLtLoggerForceDisable();

实验性功能：此函数会禁用整个运行过程中的日志记录。

返回:

返回值	描述
CUBLAS_STATUS_SUCCESS	如果日志记录已成功禁用。

查看cublasStatus_t获取完整有效返回码列表。

3.4.17. cublasLtMatmul()

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

该函数根据以下运算计算矩阵A和B的矩阵乘法，生成输出矩阵D：

D = alpha*(A*B) + beta*(C),

其中 A, B 和 C 是输入矩阵，alpha 和 beta 是输入标量。

注意

该函数支持原地矩阵乘法（C == D 和 Cdesc == Ddesc）以及非原地矩阵乘法（C != D，两个矩阵必须具有相同的数据类型、行数、列数、批处理大小和内存顺序）。在非原地情况下，C的主维度可以与D的主维度不同。具体来说，C的主维度可以设为0以实现行或列广播。如果省略Cdesc，该函数会假定其等于Ddesc。

workspace 指针必须至少对齐到256字节的倍数。 关于workspaceSizeInBytes的建议与cublasSetWorkspace()部分提到的相同。

支持的数据类型：

cublasLtMatmul() 支持以下 computeType、scaleType、Atype/Btype 和 Ctype。脚注可在本节末尾找到。

表1. 当A、B、C和D是常规列主序或行主序矩阵时

计算类型	缩放类型	A类型/B类型	C类型	偏置类型 8
CUBLAS_COMPUTE_16F 或 CUBLAS_COMPUTE_16F_PEDANTIC	CUDA_R_16F	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_32F	CUDA_R_8I	CUDA_R_8I	不支持尾声部分。
CUBLAS_COMPUTE_32F 或 CUBLAS_COMPUTE_32F_PEDANTIC	CUDA_R_32F	CUDA_R_16BF	CUDA_R_16BF	CUDA_R_16BF 8
		CUDA_R_16F	CUDA_R_16F	CUDA_R_16F 8
		CUDA_R_8I	CUDA_R_32F	不支持尾声部分。
		CUDA_R_16BF	CUDA_R_32F	CUDA_R_32F 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_C_32F 9	CUDA_C_32F 9
CUBLAS_COMPUTE_32F_FAST_16F 或 CUBLAS_COMPUTE_32F_FAST_16BF 或 CUBLAS_COMPUTE_32F_FAST_TF32 或 CUBLAS_COMPUTE_32F_EMULATED_16BFX9	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	不支持尾声部分。
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	不支持尾声部分。

要使用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）。

   • 矩阵乘法描述符必须在矩阵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布局时

计算类型	缩放类型	A类型/B类型	C类型	偏置类型
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 Usage中列出的最优要求（即指针和矩阵维度必须支持16字节对齐）。

• 缩放模式必须符合缩放模式支持概述表格中列出的限制条件。

• 在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 Type
CUDA_R_8F_E4M3	CUDA_R_8F_E4M3	CUDA_R_16BF	CUDA_R_16BF	CUDA_R_16BF 8
			CUDA_R_8F_E4M3 10	CUDA_R_16BF 8
		CUDA_R_16F	CUDA_R_16F	CUDA_R_16F 8
			CUDA_R_8F_E4M3 10	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 10	CUDA_R_16BF 8
			CUDA_R_8F_E5M2 10	CUDA_R_16BF 8
		CUDA_R_16F	CUDA_R_16F	CUDA_R_16F 8
			CUDA_R_8F_E4M3 10	CUDA_R_16F 8
			CUDA_R_8F_E5M2 10	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 10	CUDA_R_16BF 8
			CUDA_R_8F_E5M2 10	CUDA_R_16BF 8
		CUDA_R_16F	CUDA_R_16F	CUDA_R_16F 8
			CUDA_R_8F_E4M3 10	CUDA_R_16F 8
			CUDA_R_8F_E5M2 10	CUDA_R_16F 8
		CUDA_R_32F	CUDA_R_32F	CUDA_R_16BF 8

要使用块级缩放的FP4内核，必须满足以下要求：

• 所有矩阵维度必须满足Tensor Core Usage中列出的最优要求（即指针和矩阵维度必须支持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 Type
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为平面复数矩阵时

计算类型	缩放类型	A类型/B类型	C类型
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)

不支持同时使用CUBLAS_ORDER_ROW和CUBLAS_OP_C(厄米特算子)，除非A、B、C和D矩阵都采用CUBLAS_ORDER_ROW排序方式。

10(1,2,3,4,5,6,7,8,9,10)

当缩放模式为CUBLASLT_MATMUL_MATRIX_SCALE_OUTER_VEC_32F、CUBLASLT_MATMUL_MATRIX_SCALE_VEC128_32F或CUBLASLT_MATMUL_MATRIX_SCALE_BLK128x128_32F时，不支持FP8数据类型。

参数：

参数	内存	输入/输出	描述
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内存的指针。
描述		输入	指向先前创建的cublasLtMatrixLayout_t类型描述符的句柄。
algo		输入	用于矩阵乘法算法的句柄。参见cublasLtMatmulAlgo_t。当为NULL时，将执行带有默认搜索偏好的隐式启发式查询以确定实际使用的算法。
workspace	设备		指向GPU内存中分配的工作区缓冲区的指针。必须256字节对齐（即地址的最低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为零：则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。
操作描述		输入	指向先前创建的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为零：则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);

该函数根据给定的输入矩阵A、B和C以及输出矩阵D，获取矩阵乘法运算cublasLtMatmul()可能的算法。输出结果按预估计算时间递增的顺序存放在heuristicResultsArray[]中。

参数:

参数	内存	输入/输出	描述
lightHandle		输入	指向为cuBLASLt上下文分配的cuBLASLt句柄的指针。参见cublasLtHandle_t。
操作描述		输入	指向先前创建的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);

此函数检索所有有效且可能由cublasLtMatmul()函数运行的矩阵乘法算法ID，适用于给定输入矩阵A、B和C以及输出矩阵D的类型。

注意

返回的ID没有特定顺序。为确保列表中包含最佳算法，请将requestedAlgoCount设置得足够大以获取完整列表。如果满足returnAlgoCount < requestedAlgoCount条件，则保证该列表是完整的。

参数:

参数	内存	输入/输出	描述
lightHandle		输入	指向已分配的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。
scaleType		输入	缩放类型。请参阅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。
scaleType		输入	枚举值，用于指定该函数创建的矩阵变换描述符的数据精度。参见cudaDataType_t。

返回:

返回值	描述
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。
scaleType		输入	枚举值，用于指定该函数初始化的矩阵变换描述符的数据精度。参见 cudaDataType_t。

返回:

返回值	描述
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为零：则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为零：则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_t。
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_t。
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为零：则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类型描述符的句柄。 Adesc 或 Bdesc 可以为 NULL，前提是对应的指针为 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。
scaleType		输入	枚举值，用于指定该函数创建的矩阵变换描述符的数据精度。参见cudaDataType_t。

返回:

返回值	描述
CUBLAS_STATUS_ALLOC_FAILED	如果无法分配内存。
CUBLAS_STATUS_SUCCESS	如果描述符创建成功。

查看cublasStatus_t获取完整有效返回码列表。

3.4.42. cublasLtMatrixTransformDescInit()

cublasStatus_t cublasLtMatrixTransformDescInit(
      cublasLtMatrixTransformDesc_t transformDesc,
      cudaDataType scaleType);

该函数在预先分配的矩阵变换描述符中进行初始化。

参数:

参数	内存	输入/输出	描述
transformDesc		输出	指向该函数初始化的矩阵变换描述符结构的指针。参见 cublasLtMatrixTransformDesc_t。
scaleType		输入	枚举值，用于指定该函数初始化的矩阵变换描述符的数据精度。参见 cudaDataType_t。

返回:

返回值	描述
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为零：则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分块。

针对3个GPU的cublasXtgemm()分块示例

当分块维度不是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线程。

目前，只有例程cublasXtgemm()支持此功能。

4.1.3. 结果可复现性

目前，当满足以下条件时，来自给定工具包版本的所有cuBLASXt API例程都会生成相同的位级结果：

• 参与计算的所有GPU具有相同的计算能力和相同数量的流式多处理器(SMs)。

• 每次运行时瓦片大小保持一致。

• 要么不使用CPU混合计算，要么提供的CPU Blas也保证能产生可重现的结果。

4.2. cuBLASXt API 数据类型参考

4.2.1. cublasXtHandle_t

cublasXtHandle_t类型是一个指向不透明结构的指针类型，该结构保存了cuBLASXt API上下文。必须使用cublasXtCreate()初始化cuBLASXt API上下文，并且返回的句柄必须传递给所有后续的cuBLASXt API函数调用。最后应使用cublasXtDestroy()销毁该上下文。

4.2.2. cublasXtOpType_t

cublasOpType_t 枚举了BLAS例程支持的四种可能类型。该枚举用作例程 cublasXtSetCpuRoutine 和 cublasXtSetCpuRatio 的参数，用于设置混合配置。

值	含义
CUBLASXT_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[])

此函数允许用户指定参与后续cuBLASXt API数学函数调用的GPU设备数量及其对应的ID。该函数将为列表中提供的每个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或类型定义了无效的组合
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或类型定义了无效的组合
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	模式值与 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. cublasXtgemm()

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)可以是非转置或(conj.)转置。
transb		输入	操作op(B)表示非转置或共轭转置。
m		输入	矩阵 op(A) 和 C 的行数。
n		输入	矩阵 op(B) 和 C 的列数。
k		输入	op(A)的列数与op(B)的行数。
alpha	主机	输入	<type> 用于乘法的标量。
A	主机或设备	输入	<类型> 维度数组 lda x k，当 transa == CUBLAS_OP_N 时要求 lda >= max(1, m)，否则为 lda x m 且 lda >= max(1, k)。
lda		输入	用于存储矩阵 A 的二维数组的主维度。
B	主机或设备	输入	<类型> 维度为 ldb x n 的数组，当 transb == CUBLAS_OP_N 时要求 ldb >= max(1, k)，否则为 ldb x k 维度且要求 ldb >= max(1, n)。
ldb		输入	用于存储矩阵B的二维数组的主维度。
beta	主机	输入	<类型> 用于乘法的标量。如果 beta == 0，则 C 不需要是有效输入。
C	主机或设备	输入/输出	<类型> 维度数组 ldc x n，其中 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. cublasXthemm()

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)

该函数执行厄米特矩阵-矩阵乘法

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

其中\(A\)是一个以低位或高位模式存储的埃尔米特矩阵，\(B\)和\(C\)是\(m \times n\)矩阵，\(\alpha\)和\(\beta\)是标量。

参数	内存	输入/输出	含义
handle		输入	cuBLASXt API 上下文的句柄。
side		输入	指示矩阵 A 位于 B 的左侧还是右侧。
uplo		输入	指示矩阵 A 的下三角或上三角部分是否被存储，另一侧的共轭对称部分不会被引用，而是从存储的元素中推断得出。
m		输入	矩阵C和B的行数，矩阵A的大小相应调整。
n		输入	矩阵C和B的列数，矩阵A的大小相应调整。
alpha	主机	输入	<type> 用于乘法的标量。
A	主机或设备	输入	<类型> 维度为 lda x m 的数组，当 side==CUBLAS_SIDE_LEFT 时要求 lda >= max(1, m)，否则为 lda x n 且 lda >= max(1, n)。假定对角线元素的虚部为零。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	主机或设备	输入	<类型> 维度为 ldb x n 的数组，其中 ldb >= max(1, m)。
ldb		输入	用于存储矩阵B的二维数组的主维度。
beta	主机	输入	<type> 用于乘法的标量，如果 beta == 0 则 C 不需要是有效输入。
C	主机或设备	输入/输出	<类型> 维度数组 ldc x n，其中 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. cublasXtsymm()

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{如果 }\textsf{side == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ {\alpha BA + \beta C} & {\text{如果 }\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 的数组，当 side == CUBLAS_SIDE_LEFT 时要求 lda >= max(1, m)；否则为 lda x n 且 lda >= max(1, n)。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	主机或设备	输入	<类型> 维度为 ldb x n 的数组，其中 ldb >= max(1, m)。
ldb		输入	用于存储矩阵B的二维数组的主维度。
beta	主机	输入	<type> 用于乘法的标量，如果 beta == 0 则 C 不需要是有效输入。
C	主机或设备	输入/输出	<类型> 维度为 ldc x n 的数组，其中 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. cublasXtsyrk()

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{如果 }\textsf{transa == $\mathrm{CUBLAS\_OP\_N}$}} \\ A^{T} & {\text{如果 }\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	主机或设备	输入	类型 维度为 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	主机或设备	输入/输出	<类型> 维度为 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. cublasXtsyr2k()

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{) 和 op(}B\text{)} = \left\{ \begin{matrix} {A\text{ 和 }B} & {\text{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A^{T}\text{ 和 }B^{T}} & {\text{如果 }\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	主机或设备	输入	<类型> 维度为 lda x k 的数组，当 transa == CUBLAS_OP_N 时要求 lda >= max(1, n)，否则为 lda x n 且 lda >= max(1, k)。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	主机或设备	输入	<类型> 维度数组 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	主机或设备	输入/输出	<类型> 维度为 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. cublasXtsyrkx()

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{) 和 op(}B\text{)} = \left\{ \begin{matrix} {A\text{ 和 }B} & {\text{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A^{T}\text{ 和 }B^{T}} & {\text{如果 }\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	主机或设备	输入	<类型> 维度为 lda x k 的数组，当 transa == CUBLAS_OP_N 时要求 lda >= max(1, n)，否则为 lda x n 且 lda >= max(1, k)。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	主机或设备	输入	<类型> 维度数组 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	主机或设备	输入/输出	<类型> 维度为 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. cublasXtherk()

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)

该函数执行埃尔米特秩-\(k\)更新

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

其中 \(\alpha\) 和 \(\beta\) 是标量，\(C\) 是以下三角或上三角模式存储的厄米特矩阵，\(A\) 是一个维度为 \(\text{op}(A)\) \(n \times k\) 的矩阵。同样地，对于矩阵 \(A\)

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

参数	内存	输入/输出	含义
handle		输入	cuBLASXt API 上下文的句柄。
uplo		输入	指示矩阵 C 的下三角或上三角部分是否被存储，另一侧的共轭对称部分不会被引用。
trans		输入	操作op(A)可以是非转置或(conj.)转置。
n		输入	矩阵 op(A) 和 C 的行数。
k		输入	矩阵 op(A) 的列数。
alpha	主机	输入	<type> 用于乘法的标量。
A	主机或设备	输入	<类型> 维度为 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	主机或设备	输入/输出	<类型> 维度为 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. cublasXther2k()

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)

该函数执行埃尔米特秩\(2k\)更新

\(C = \alpha\text{op}(A)\text{op}(B)^{H} + \overset{ˉ}{\alpha}\text{op}(B)\text{op}(A)^{H} + \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{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A^{H}\text{ and }B^{H}} & {\text{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

参数	内存	输入/输出	含义
handle		输入	cuBLASXt API 上下文的句柄。
uplo		输入	指示矩阵 C 的下三角或上三角部分是否被存储，另一侧的共轭对称部分不会被引用。
trans		输入	操作op(A)可以是非转置或(conj.)转置。
n		输入	矩阵op(A)、op(B)和C的行数。
k		输入	矩阵 op(A) 和 op(B) 的列数。
alpha	主机	输入	<type> 用于乘法的标量。
A	主机或设备	输入	<类型> 维度为 lda x k 的数组，当 transa == CUBLAS_OP_N 时要求 lda >= max(1, n)，否则为 lda x n 且 lda >= max(1, k)。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	主机或设备	输入	<类型> 维度为 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	主机或设备	输入/输出	<类型> 维度为 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. cublasXtherkx()

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)

该函数执行埃尔米特秩\(k\)更新的变体

\(C = \alpha\text{op}(A)\text{op}(B)^{H} + \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{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_N}$}} \\ {A^{H}\text{ and }B^{H}} & {\text{如果 }\textsf{trans == $\mathrm{CUBLAS\_OP\_C}$}} \\ \end{matrix} \right.\)

当矩阵B满足结果保证为厄米特矩阵的条件时，可以使用此例程。一个常见例子是当矩阵B是矩阵A的缩放形式时：这相当于B是矩阵A与对角矩阵的乘积。

参数	内存	输入/输出	含义
handle		输入	cuBLASXt API 上下文的句柄。
uplo		输入	指示矩阵 C 的下三角或上三角部分是否被存储，另一侧的共轭对称部分不会被引用。
trans		输入	操作op(A)可以是非转置或(conj.)转置。
n		输入	矩阵op(A)、op(B)和C的行数。
k		输入	矩阵 op(A) 和 op(B) 的列数。
alpha	主机	输入	<type> 用于乘法的标量。
A	主机或设备	输入	<类型> 维度为 lda x k 的数组，当 transa == CUBLAS_OP_N 时要求 lda >= max(1, n)，否则为 lda x n 且 lda >= max(1, k)。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	主机或设备	输入	<类型> 维度为 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	主机或设备	输入/输出	<类型> 维度为 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. cublasXttrsm()

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{如果 }\textsf{side == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ {X\text{op}(A) = \alpha B} & {\text{如果 }\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)可以是非转置或(conj.)转置。
diag		输入	表示矩阵A主对角线上的元素是否为1且不应被访问。
m		输入	矩阵B的行数，矩阵A的大小相应调整。
n		输入	矩阵B的列数，矩阵A会相应调整尺寸。
alpha	主机	输入	<类型> 用于乘法的标量，如果 alpha == 0 则 A 不会被引用且 B 不需要是有效输入。
A	主机或设备	输入	类型 维度为 lda x m 的数组，当 side == CUBLAS_SIDE_LEFT 时要求 lda >= max(1, m)；否则为 lda x n 且 lda >= max(1, n)。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	主机或设备	输入/输出	<类型> 数组。其维度为 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. cublasXttrmm()

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{如果 }\textsf{side == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ {\alpha B\text{op}(A)} & {\text{如果 }\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)可以是非转置或(conj.)转置。
diag		输入	表示矩阵A主对角线上的元素是否为1且不应被访问。
m		输入	矩阵B的行数，矩阵A的大小相应调整。
n		输入	矩阵B的列数，矩阵A的大小相应调整。
alpha	主机	输入	<类型> 用于乘法的标量，如果alpha存在则A不会被引用且B不需要是有效输入。
A	主机或设备	输入	类型 维度为 lda x m 的数组，当 side == CUBLAS_SIDE_LEFT 时要求 lda >= max(1, m)；否则为 lda x n 且 lda >= max(1, n)。
lda		输入	用于存储矩阵A的二维数组的主维度。
B	主机或设备	输入	<类型> 维度为 ldb x n 的数组，其中 ldb >= max(1, m)。
ldb		输入	用于存储矩阵B的二维数组的主维度。
C	主机或设备	输入/输出	<类型> 维度为 ldc x n 的数组，其中 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. cublasXtspmm()

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{如果 }\textsf{side == $\mathrm{CUBLAS\_SIDE\_LEFT}$}} \\ {\alpha BA + \beta C} & {\text{如果 }\textsf{side == $\mathrm{CUBLAS\_SIDE\_RIGHT}$}} \\ \end{matrix} \right.\)

其中\(A\)是一个以压缩格式存储的\(n \times n\)对称矩阵，\(B\)和\(C\)是\(m \times n\)矩阵，\(\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}\) 个元素的空间。

注意

压缩矩阵AP必须位于主机或托管内存中，而其他矩阵可以位于主机或任何GPU设备上

参数	内存	输入/输出	含义
handle		输入	cuBLASXt API 上下文的句柄。
side		输入	指示矩阵 A 位于 B 的左侧还是右侧。
uplo		输入	指示矩阵A的下三角部分或上三角部分是否被存储，另一对称部分未被引用，而是从存储的元素中推断得出。
m		输入	矩阵A和B的行数，其中矩阵A的大小相应调整。
n		输入	矩阵C和A的列数，其中矩阵A的大小相应调整。
alpha	主机	输入	<type> 用于乘法的标量。
AP	主机	输入	<type> 数组，其中 \(A\) 以压缩格式存储。
B	主机或设备	输入	<类型> 维度为 ldb x n 的数组，其中 ldb >= max(1, m)。
ldb		输入	用于存储矩阵B的二维数组的主维度。
beta	主机	输入	<type> 用于乘法的标量，如果 beta == 0 则 C 不需要是有效输入。
C	主机或设备	输入/输出	<类型> 维度为 ldc x n 的数组，其中 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传统API

本节并非对每个传统API数据类型和入口点的完整参考。相反，它描述了如何使用该API，特别是在与常规cuBLAS API存在差异的情况下。

请注意，本节中所有提及“cuBLAS库”的内容仅指传统cuBLAS API。

警告

传统的cuBLAS API已被弃用，将在未来版本中移除。

6.1. 错误状态

cublasStatus 类型用于函数状态返回。cuBLAS库的辅助函数直接返回状态，而核心函数的状态可以通过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"。此外，下一节将更详细地讨论传统API与cuBLAS API原型之间的差异，特别是如何将函数调用从一个API转换到另一个API。

6.8. 将旧版转换为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++编程指南。

• 将参数字符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编写的C语言应用程序，包含两种索引风格（示例A.1《使用C和cuBLAS的应用：基于1的索引》和示例A.2《使用C和cuBLAS的应用：基于0的索引》）。该应用程序与简介章节中展示的使用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目录中，并以两种不同的形式提供：

• 位于文件fortran_thunking.c中的thunking包装器接口

• 位于文件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选项。在Windows平台使用Microsoft Visual C/C++时，通过'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实现的小型应用程序，以及移植使用cuBLAS库后采用非thunking封装器的相同应用。

第二个示例应在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（图灵架构）和sm_70（伏特架构）的cubin文件：

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编写。

• 专为费米架构优化的DGEMM和SGEMM库例程部分由田纳西大学开发。随后，针对费米架构优化的其他多个例程都是从这些最初的DGEMM和SGEMM实现中衍生而来。

• STRSV、DTRSV、CTRSV和ZTRSV库例程的重大优化是由英国科学技术设施委员会(STFC)的Jonathan Hogg开发的。随后，STRSM、DTRSM、CTRSM和ZTRSM的部分优化就是从这些TRSV实现中衍生而来的。

• 阿卜杜拉国王科技大学(KAUST)的Ahmad Abdelfattah、David Keyes和Hatem Ltaief对SYMV和HEMV库例程进行了重大优化。

• 阿卜杜拉国王科技大学(KAUST)的Ali Charara、David Keyes和Hatem Ltaief对TRMM和TRSM库例程进行了重大优化。

• 本产品包含 {fmt} - 一个现代化的格式化库 https://fmt.dev 版权所有 (c) 2012 - 至今，Victor Zverovich。

• 本产品包含spdlog - 一个快速的C++日志库。https://github.com/gabime/spdlog 采用MIT许可证(MIT License)。

• 本产品包含用于评估初等函数的SIMD库、向量化libm和离散傅里叶变换库 https://sleef.orgBoost软件许可证 - 版本1.0 - 2003年8月17日。

• 本产品包含Frozen - 一个专为C++14用户设计的仅头文件、constexpr替代gperf的工具。https://github.com/serge-sans-paille/frozen Apache许可证 - 2.0版，2004年1月。

• 本产品包含Boost C++库 - 免费经过同行评审的可移植C++源代码库 https://www.boost.org/ Boost软件许可证 - 版本1.0 - 2003年8月17日。

• 本产品包含Zstandard——一种快速无损压缩算法，旨在实现zlib级别的实时压缩场景及更优的压缩比。https://github.com/facebook/zstd 采用BSD许可证。

10. 公告

10.1. 通知

本文档仅供信息参考之用，不应视为对产品功能、状态或质量的保证。NVIDIA公司（“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对客户就本文所述产品的全部及累计责任应受产品销售条款的限制。

10.2. OpenCL

OpenCL是苹果公司的商标，经Khronos Group Inc.授权使用。

10.3. 商标

NVIDIA和NVIDIA标识是美国及其他国家NVIDIA公司的商标或注册商标。其他公司及产品名称可能是其各自关联公司的商标。