torch.sparse

警告

稀疏张量的 PyTorch API 尚处于 beta 阶段，未来可能会发生变化。我们非常欢迎以 GitHub issue 的形式提出功能请求、错误报告和一般性建议。

为何以及何时使用稀疏性

默认情况下，PyTorch 将 torch.Tensor 元素连续存储在物理内存中。这使得各种需要快速访问元素的数组处理算法能够高效实现。

现在，一些用户可能会决定用张量来表示诸如图邻接矩阵、剪枝权重或点云等数据，这些张量的元素大多为零值。我们认识到这些是重要的应用，并旨在通过稀疏存储格式为这些用例提供性能优化。

多年来，人们开发了各种稀疏存储格式，如 COO、CSR/CSC、半结构化、LIL 等。虽然它们在确切的布局上有所不同，但它们都通过有效地表示零值元素来压缩数据。我们将未压缩的值称为指定的，与未指定的压缩元素形成对比。

通过压缩重复的零，稀疏存储格式旨在节省各种 CPU 和 GPU 上的内存和计算资源。特别是对于高度稀疏或高度结构化的稀疏性，这可能会对性能产生重大影响。因此，稀疏存储格式可以被视为一种性能优化。

像许多其他性能优化一样，稀疏存储格式并非总是有利的。当为您的用例尝试稀疏格式时，您可能会发现执行时间反而增加而不是减少。

如果您从分析上预计会看到性能的显着提升，但实际上测量到的是性能下降，请随时打开 GitHub issue。这有助于我们优先实现高效的内核和更广泛的性能优化。

我们使其易于尝试不同的稀疏布局，并在它们之间进行转换，而不会对哪种布局最适合您的特定应用做出主观判断。

功能概述

我们希望通过为每种布局提供转换例程，能够直接从给定的稠密张量构造稀疏张量。

在下一个示例中，我们将具有默认稠密（步长）布局的 2D 张量转换为由 COO 内存布局支持的 2D 张量。在这种情况下，仅存储非零元素的值和索引。

>>> a = torch.tensor([[0, 2.], [3, 0]])
>>> a.to_sparse()
tensor(indices=tensor([[0, 1],
                       [1, 0]]),
       values=tensor([2., 3.]),
       size=(2, 2), nnz=2, layout=torch.sparse_coo)

PyTorch 当前支持 COO、CSR、CSC、BSR 和 BSC。

我们还有一个原型实现来支持 :ref: 半结构化稀疏性<sparse-semi-structured-docs>。请参阅参考文献以获取更多详细信息。

请注意，我们提供了这些格式的轻微泛化。

批处理：诸如 GPU 之类的设备需要批处理才能获得最佳性能，因此我们支持批处理维度。

我们目前提供非常简单的批处理版本，其中稀疏格式的每个组件本身都是批处理的。这也要求每个批处理条目具有相同数量的指定元素。在此示例中，我们从 3D 稠密张量构造 3D（批处理）CSR 张量。

>>> t = torch.tensor([[[1., 0], [2., 3.]], [[4., 0], [5., 6.]]])
>>> t.dim()
3
>>> t.to_sparse_csr()
tensor(crow_indices=tensor([[0, 1, 3],
                            [0, 1, 3]]),
       col_indices=tensor([[0, 0, 1],
                           [0, 0, 1]]),
       values=tensor([[1., 2., 3.],
                      [4., 5., 6.]]), size=(2, 2, 2), nnz=3,
       layout=torch.sparse_csr)

稠密维度：另一方面，诸如图嵌入之类的一些数据可能更适合被视为向量的稀疏集合，而不是标量。

在此示例中，我们从 3D 步长张量创建具有 2 个稀疏维度和 1 个稠密维度的 3D 混合 COO 张量。如果 3D 步长张量中的整行都为零，则不存储它。但是，如果行中的任何值非零，则会完全存储它们。这减少了索引的数量，因为我们需要每个行一个索引，而不是每个元素一个索引。但是，它也增加了值的存储量。因为只有完全为零的行才能被省略，并且任何非零值元素的出现都会导致整行被存储。

>>> t = torch.tensor([[[0., 0], [1., 2.]], [[0., 0], [3., 4.]]])
>>> t.to_sparse(sparse_dim=2)
tensor(indices=tensor([[0, 1],
                       [1, 1]]),
       values=tensor([[1., 2.],
                      [3., 4.]]),
       size=(2, 2, 2), nnz=2, layout=torch.sparse_coo)

算子概述

从根本上讲，对具有稀疏存储格式的张量进行的操作与对具有步长（或其他）存储格式的张量进行的操作行为相同。存储的特殊性，即数据的物理布局，会影响操作的性能，但不应影响语义。

我们正在积极增加稀疏张量的算子覆盖率。用户不应期望获得与稠密张量相同的支持水平。有关列表，请参阅我们的 算子 文档。

>>> b = torch.tensor([[0, 0, 1, 2, 3, 0], [4, 5, 0, 6, 0, 0]])
>>> b_s = b.to_sparse_csr()
>>> b_s.cos()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
RuntimeError: unsupported tensor layout: SparseCsr
>>> b_s.sin()
tensor(crow_indices=tensor([0, 3, 6]),
       col_indices=tensor([2, 3, 4, 0, 1, 3]),
       values=tensor([ 0.8415,  0.9093,  0.1411, -0.7568, -0.9589, -0.2794]),
       size=(2, 6), nnz=6, layout=torch.sparse_csr)

如上面的示例所示，我们不支持非零保留的一元算子，例如 cos。非零保留的一元运算的输出将无法像输入一样充分利用稀疏存储格式，并可能导致内存的灾难性增加。我们改为依赖用户先显式转换为稠密张量，然后再运行操作。

>>> b_s.to_dense().cos()
tensor([[ 1.0000, -0.4161],
        [-0.9900,  1.0000]])

我们意识到，一些用户希望忽略诸如 cos 之类的运算的压缩零，而不是保留运算的确切语义。为此，我们可以指向 torch.masked 及其 MaskedTensor，它反过来也由稀疏存储格式和内核支持和驱动。

另请注意，目前，用户无法选择输出布局。例如，将稀疏张量添加到常规步长张量会生成步长张量。一些用户可能更希望它保持稀疏布局，因为他们知道结果仍然会足够稀疏。

>>> a + b.to_sparse()
tensor([[0., 3.],
        [3., 0.]])

我们认识到，访问可以有效地生成不同输出布局的内核可能非常有用。后续操作可能会从接收特定的布局中显着受益。我们正在开发一个 API 来控制结果布局，并认识到这是一个重要的功能，可以为任何给定模型规划更优化的执行路径。

稀疏半结构化张量

警告

稀疏半结构化张量目前是一项原型功能，可能会发生变化。如果您要报告错误或有反馈要分享，请随时打开 issue。

半结构化稀疏性是 NVIDIA Ampere 架构中首次引入的一种稀疏数据布局。它也称为细粒度结构化稀疏性或 2:4 结构化稀疏性。

此稀疏布局存储每 2n 个元素中的 n 个元素，其中 n 由张量数据类型 (dtype) 的宽度确定。最常用的 dtype 是 float16，其中 n=2，因此称为“2:4 结构化稀疏性”。

在 这篇 NVIDIA 博客文章 中更详细地解释了半结构化稀疏性。

在 PyTorch 中，半结构化稀疏性是通过张量子类实现的。通过子类化，我们可以覆盖 __torch_dispatch__，从而允许我们在执行矩阵乘法时使用更快的稀疏内核。我们还可以将张量以其压缩形式存储在子类内部，以减少内存开销。

在这种压缩形式中，稀疏张量通过仅保留指定的元素和一些元数据（用于编码掩码）来存储。

注意

半结构化稀疏张量的指定元素和元数据掩码一起存储在单个扁平压缩张量中。它们相互附加以形成连续的内存块。

压缩张量 = [ 原始张量的指定元素 | metadata_mask ]

对于大小为 (r, c) 的原始张量，我们希望前 m * k // 2 个元素是保留的元素，张量的其余部分是元数据。

为了方便用户查看指定的元素和掩码，可以使用 .indices() 和 .values() 分别访问掩码和指定的元素。

• .values() 返回大小为 (r, c//2) 且 dtype 与稠密矩阵相同的张量中指定的元素。

• .indices() 返回大小为 (r, c//2 ) 且元素类型为 torch.int16（如果 dtype 为 torch.float16 或 torch.bfloat16）以及元素类型为 torch.int32（如果 dtype 为 torch.int8）的张量中的 metadata_mask。

对于 2:4 稀疏张量，元数据开销很小 - 每个指定的元素仅 2 位。

注意

重要的是要注意，torch.float32 仅支持 1:2 稀疏性。因此，它不遵循与上述相同的公式。

在这里，我们分解如何计算 2:4 稀疏张量的压缩率（稠密大小 / 稀疏大小）。

令 (r, c) = tensor.shape 和 e = bitwidth(tensor.dtype)，因此对于 torch.float16 和 torch.bfloat16，e = 16，对于 torch.int8，e = 8。

$$M_{dense} = r \times c \times e \\ M_{sparse} = M_{specified} + M_{metadata} = r \times \frac{c}{2} \times e + r \times \frac{c}{2} \times 2 = \frac{rce}{2} + rc =rce(\frac{1}{2} +\frac{1}{e})$$

使用这些计算，我们可以确定原始稠密表示和新的稀疏表示的总内存占用。

这为我们提供了一个简单的压缩率公式，该公式仅取决于张量数据类型的位宽。

$$C = \frac{M_{sparse}}{M_{dense}} = \frac{1}{2} + \frac{1}{e}$$

通过使用此公式，我们发现对于 torch.float16 或 torch.bfloat16，压缩率为 56.25%，对于 torch.int8，压缩率为 62.5%。

构造稀疏半结构化张量

您可以通过简单地使用 torch.to_sparse_semi_structured 函数将稠密张量转换为稀疏半结构化张量。

另请注意，我们仅支持 CUDA 张量，因为半结构化稀疏性的硬件兼容性仅限于 NVIDIA GPU。

以下数据类型受半结构化稀疏性支持。请注意，每种数据类型都有其自身的形状约束和压缩因子。

PyTorch dtype	形状约束	压缩因子	稀疏模式
torch.float16	张量必须是 2D 的，并且 (r, c) 都必须是 64 的正倍数	9/16	2:4
torch.bfloat16	张量必须是 2D 的，并且 (r, c) 都必须是 64 的正倍数	9/16	2:4
torch.int8	张量必须是 2D 的，并且 (r, c) 都必须是 128 的正倍数	10/16	2:4

要构造半结构化稀疏张量，请首先创建一个符合 2:4（或半结构化）稀疏格式的常规稠密张量。为此，我们平铺一个小的 1x4 条带以创建一个 16x16 稠密 float16 张量。之后，我们可以调用 to_sparse_semi_structured 函数来压缩它以加速推理。

>>> from torch.sparse import to_sparse_semi_structured
>>> A = torch.Tensor([0, 0, 1, 1]).tile((128, 32)).half().cuda()
tensor([[0., 0., 1.,  ..., 0., 1., 1.],
        [0., 0., 1.,  ..., 0., 1., 1.],
        [0., 0., 1.,  ..., 0., 1., 1.],
        ...,
        [0., 0., 1.,  ..., 0., 1., 1.],
        [0., 0., 1.,  ..., 0., 1., 1.],
        [0., 0., 1.,  ..., 0., 1., 1.]], device='cuda:0', dtype=torch.float16)
>>> A_sparse = to_sparse_semi_structured(A)
SparseSemiStructuredTensor(shape=torch.Size([128, 128]), transposed=False, values=tensor([[1., 1., 1.,  ..., 1., 1., 1.],
        [1., 1., 1.,  ..., 1., 1., 1.],
        [1., 1., 1.,  ..., 1., 1., 1.],
        ...,
        [1., 1., 1.,  ..., 1., 1., 1.],
        [1., 1., 1.,  ..., 1., 1., 1.],
        [1., 1., 1.,  ..., 1., 1., 1.]], device='cuda:0', dtype=torch.float16), metadata=tensor([[-4370, -4370, -4370,  ..., -4370, -4370, -4370],
        [-4370, -4370, -4370,  ..., -4370, -4370, -4370],
        [-4370, -4370, -4370,  ..., -4370, -4370, -4370],
        ...,
        [-4370, -4370, -4370,  ..., -4370, -4370, -4370],
        [-4370, -4370, -4370,  ..., -4370, -4370, -4370],
        [-4370, -4370, -4370,  ..., -4370, -4370, -4370]], device='cuda:0',
dtype=torch.int16))

稀疏半结构化张量运算

目前，半结构化稀疏张量支持以下运算

• torch.addmm(bias, dense, sparse.t())

• torch.mm(dense, sparse)

• torch.mm(sparse, dense)

• aten.linear.default(dense, sparse, bias)

• aten.t.default(sparse)

• aten.t.detach(sparse)

要使用这些运算，只需传递 to_sparse_semi_structured(tensor) 的输出，而不是在您的张量具有半结构化稀疏格式的 0 后使用 tensor，就像这样

>>> a = torch.Tensor([0, 0, 1, 1]).tile((64, 16)).half().cuda()
>>> b = torch.rand(64, 64).half().cuda()
>>> c = torch.mm(a, b)
>>> a_sparse = to_sparse_semi_structured(a)
>>> torch.allclose(c, torch.mm(a_sparse, b))
True

使用半结构化稀疏性加速 nn.Linear

如果模型的权重已经是半结构化稀疏的，只需几行代码即可加速线性层

>>> input = torch.rand(64, 64).half().cuda()
>>> mask = torch.Tensor([0, 0, 1, 1]).tile((64, 16)).cuda().bool()
>>> linear = nn.Linear(64, 64).half().cuda()
>>> linear.weight = nn.Parameter(to_sparse_semi_structured(linear.weight.masked_fill(~mask, 0)))

稀疏 COO 张量

PyTorch 实现了所谓的坐标格式或 COO 格式，作为实现稀疏张量的存储格式之一。在 COO 格式中，指定的元素存储为元素索引和相应值的元组。特别是，

• 指定元素的索引收集在大小为 (ndim, nse) 且元素类型为 torch.int64 的 indices 张量中，

• 相应的值收集在大小为 (nse,) 且具有任意整数或浮点数元素类型的 values 张量中，

其中 ndim 是张量的维度，nse 是指定元素的数量。

注意

稀疏 COO 张量的内存消耗至少为 (ndim * 8 + <size of element type in bytes>) * nse 字节（加上存储其他张量数据的恒定开销）。

步长张量的内存消耗至少为 product(<tensor shape>) * <size of element type in bytes>。

例如，具有 100 000 个非零 32 位浮点数的 10 000 x 10 000 张量的内存消耗在使用 COO 张量布局时至少为 (2 * 8 + 4) * 100 000 = 2 000 000 字节，而在使用默认步长张量布局时为 10 000 * 10 000 * 4 = 400 000 000 字节。请注意，使用 COO 存储格式可节省 200 倍的内存。

构造

稀疏 COO 张量可以通过提供索引和值的两个张量，以及稀疏张量的大小（当无法从索引和值张量推断时）来构建，使用函数 torch.sparse_coo_tensor()。

假设我们要定义一个稀疏张量，在位置 (0, 2) 处输入 3，在位置 (1, 0) 处输入 4，在位置 (1, 2) 处输入 5。未指定的元素被假定为具有相同的值，填充值，默认为零。然后我们可以这样写

>>> i = [[0, 1, 1],
         [2, 0, 2]]
>>> v =  [3, 4, 5]
>>> s = torch.sparse_coo_tensor(i, v, (2, 3))
>>> s
tensor(indices=tensor([[0, 1, 1],
                       [2, 0, 2]]),
       values=tensor([3, 4, 5]),
       size=(2, 3), nnz=3, layout=torch.sparse_coo)
>>> s.to_dense()
tensor([[0, 0, 3],
        [4, 0, 5]])

请注意，输入 i 不是索引元组的列表。 如果你想以这种方式编写索引，你应该在将它们传递给稀疏构造函数之前进行转置

>>> i = [[0, 2], [1, 0], [1, 2]]
>>> v =  [3,      4,      5    ]
>>> s = torch.sparse_coo_tensor(list(zip(*i)), v, (2, 3))
>>> # Or another equivalent formulation to get s
>>> s = torch.sparse_coo_tensor(torch.tensor(i).t(), v, (2, 3))
>>> torch.sparse_coo_tensor(i.t(), v, torch.Size([2,3])).to_dense()
tensor([[0, 0, 3],
        [4, 0, 5]])

可以通过仅指定大小来构造一个空的稀疏 COO 张量

>>> torch.sparse_coo_tensor(size=(2, 3))
tensor(indices=tensor([], size=(2, 0)),
       values=tensor([], size=(0,)),
       size=(2, 3), nnz=0, layout=torch.sparse_coo)

稀疏混合 COO 张量

PyTorch 实现了稀疏张量的扩展，将标量值扩展到具有（连续）张量值的稀疏张量。这种张量被称为混合张量。

PyTorch 混合 COO 张量通过允许 values 张量为多维张量来扩展稀疏 COO 张量，因此我们有

• 指定元素的索引收集在大小为 (sparse_dims, nse) 且元素类型为 torch.int64 的 indices 张量中，

• 相应的（张量）值收集在大小为 (nse, dense_dims) 且元素类型为任意整数或浮点数的 values 张量中。

注意

我们使用 (M + K) 维张量来表示 N 维稀疏混合张量，其中 M 和 K 分别是稀疏维度和稠密维度的数量，使得 M + K == N 成立。

假设我们要创建一个 (2 + 1) 维张量，在位置 (0, 2) 处输入 [3, 4]，在位置 (1, 0) 处输入 [5, 6]，在位置 (1, 2) 处输入 [7, 8]。 我们可以这样写

>>> i = [[0, 1, 1],
         [2, 0, 2]]
>>> v =  [[3, 4], [5, 6], [7, 8]]
>>> s = torch.sparse_coo_tensor(i, v, (2, 3, 2))
>>> s
tensor(indices=tensor([[0, 1, 1],
                       [2, 0, 2]]),
       values=tensor([[3, 4],
                      [5, 6],
                      [7, 8]]),
       size=(2, 3, 2), nnz=3, layout=torch.sparse_coo)

>>> s.to_dense()
tensor([[[0, 0],
         [0, 0],
         [3, 4]],
        [[5, 6],
         [0, 0],
         [7, 8]]])

一般来说，如果 s 是一个稀疏 COO 张量，并且 M = s.sparse_dim(), K = s.dense_dim()，那么我们有以下不变性

• M + K == len(s.shape) == s.ndim - 张量的维度是稀疏维度和稠密维度数量的总和，

• s.indices().shape == (M, nse) - 稀疏索引被显式存储，

• s.values().shape == (nse,) + s.shape[M : M + K] - 混合张量的值是 K 维张量，

• s.values().layout == torch.strided - 值被存储为跨步张量。

注意

稠密维度始终跟随稀疏维度，也就是说，不支持稠密维度和稀疏维度的混合。

注意

为了确保构建的稀疏张量具有一致的索引、值和大小，可以通过 check_invariants=True 关键字参数在每个张量创建时启用不变量检查，或者全局使用 torch.sparse.check_sparse_tensor_invariants 上下文管理器实例。默认情况下，稀疏张量不变量检查是禁用的。

非合并稀疏 COO 张量

PyTorch 稀疏 COO 张量格式允许稀疏*非合并*张量，其中索引中可能存在重复坐标；在这种情况下，解释是该索引处的值是所有重复值条目的总和。 例如，可以为同一索引 1 指定多个值，3 和 4，这将导致一个 1 维非合并张量

>>> i = [[1, 1]]
>>> v =  [3, 4]
>>> s=torch.sparse_coo_tensor(i, v, (3,))
>>> s
tensor(indices=tensor([[1, 1]]),
       values=tensor(  [3, 4]),
       size=(3,), nnz=2, layout=torch.sparse_coo)

而合并过程将使用求和将多值元素累积为单个值

>>> s.coalesce()
tensor(indices=tensor([[1]]),
       values=tensor([7]),
       size=(3,), nnz=1, layout=torch.sparse_coo)

一般来说，torch.Tensor.coalesce() 方法的输出是一个具有以下属性的稀疏张量

• 指定张量元素的索引是唯一的，

• 索引按字典顺序排序，

• torch.Tensor.is_coalesced() 返回 True。

注意

在大多数情况下，您不必关心稀疏张量是否合并，因为大多数操作在给定的稀疏合并或非合并张量上将以相同的方式工作。

但是，某些操作可以在非合并张量上更有效地实现，而某些操作可以在合并张量上更有效地实现。

例如，稀疏 COO 张量的加法是通过简单地连接索引和值张量来实现的

>>> a = torch.sparse_coo_tensor([[1, 1]], [5, 6], (2,))
>>> b = torch.sparse_coo_tensor([[0, 0]], [7, 8], (2,))
>>> a + b
tensor(indices=tensor([[0, 0, 1, 1]]),
       values=tensor([7, 8, 5, 6]),
       size=(2,), nnz=4, layout=torch.sparse_coo)

如果您重复执行可能产生重复条目的操作（例如，torch.Tensor.add()），您应该偶尔合并您的稀疏张量，以防止它们变得过大。

另一方面，索引的字典顺序对于实现涉及许多元素选择操作的算法可能是有利的，例如切片或矩阵乘积。

使用稀疏 COO 张量

让我们考虑以下示例

>>> i = [[0, 1, 1],
         [2, 0, 2]]
>>> v =  [[3, 4], [5, 6], [7, 8]]
>>> s = torch.sparse_coo_tensor(i, v, (2, 3, 2))

如上所述，稀疏 COO 张量是一个 torch.Tensor 实例，为了将其与使用其他布局的 Tensor 实例区分开来，可以使用 torch.Tensor.is_sparse 或 torch.Tensor.layout 属性

>>> isinstance(s, torch.Tensor)
True
>>> s.is_sparse
True
>>> s.layout == torch.sparse_coo
True

可以使用方法 torch.Tensor.sparse_dim() 和 torch.Tensor.dense_dim() 分别获取稀疏维度和稠密维度的数量。 例如

>>> s.sparse_dim(), s.dense_dim()
(2, 1)

如果 s 是一个稀疏 COO 张量，那么可以使用方法 torch.Tensor.indices() 和 torch.Tensor.values() 获取其 COO 格式数据。

注意

目前，只有当张量实例被合并时才能获取 COO 格式数据

>>> s.indices()
RuntimeError: Cannot get indices on an uncoalesced tensor, please call .coalesce() first

为了获取非合并张量的 COO 格式数据，请使用 torch.Tensor._values() 和 torch.Tensor._indices()

>>> s._indices()
tensor([[0, 1, 1],
        [2, 0, 2]])

警告

调用 torch.Tensor._values() 将返回一个*分离的*张量。 为了跟踪梯度，必须使用 torch.Tensor.coalesce().values() 代替。

构造一个新的稀疏 COO 张量会得到一个未合并的张量

>>> s.is_coalesced()
False

但是可以使用 torch.Tensor.coalesce() 方法构造稀疏 COO 张量的合并副本

>>> s2 = s.coalesce()
>>> s2.indices()
tensor([[0, 1, 1],
       [2, 0, 2]])

当使用非合并稀疏 COO 张量时，必须考虑非合并数据的加法性质：相同索引的值是总和的项，该总和的评估给出相应张量元素的值。 例如，稀疏非合并张量上的标量乘法可以通过将所有非合并值与标量相乘来实现，因为 c * (a + b) == c * a + c * b 成立。 然而，任何非线性运算，例如平方根，都不能通过将运算应用于非合并数据来实现，因为 sqrt(a + b) == sqrt(a) + sqrt(b) 一般不成立。

仅稠密维度支持稀疏 COO 张量的切片（正步长）。 稀疏维度和稠密维度都支持索引

>>> s[1]
tensor(indices=tensor([[0, 2]]),
       values=tensor([[5, 6],
                      [7, 8]]),
       size=(3, 2), nnz=2, layout=torch.sparse_coo)
>>> s[1, 0, 1]
tensor(6)
>>> s[1, 0, 1:]
tensor([6])

在 PyTorch 中，稀疏张量的填充值不能显式指定，并且通常假定为零。 但是，存在一些操作可能会以不同的方式解释填充值。 例如，torch.sparse.softmax() 计算 softmax 时假设填充值为负无穷大。

稀疏压缩张量

稀疏压缩张量代表一类稀疏张量，它们具有一个共同的特征，即使用一种编码来压缩特定维度的索引，这种编码可以在稀疏压缩张量的线性代数内核上实现某些优化。 这种编码基于 压缩稀疏行 (CSR) 格式，PyTorch 稀疏压缩张量对其进行了扩展，支持稀疏张量批处理、允许多维张量值以及将稀疏张量值存储在稠密块中。

注意

我们使用 (B + M + K) 维张量来表示 N 维稀疏压缩混合张量，其中 B、M 和 K 分别是批处理维度、稀疏维度和稠密维度的数量，使得 B + M + K == N 成立。 稀疏压缩张量的稀疏维度数量始终为两个，M == 2。

注意

如果索引张量 compressed_indices 满足以下不变性，我们就说它使用 CSR 编码

• compressed_indices 是一个连续的跨步 32 位或 64 位整数张量

• compressed_indices 形状为 (*batchsize, compressed_dim_size + 1)，其中 compressed_dim_size 是压缩维度的数量（例如行或列）

• compressed_indices[..., 0] == 0，其中 ... 表示批处理索引

• compressed_indices[..., compressed_dim_size] == nse，其中 nse 是指定元素的数量

• 0 <= compressed_indices[..., i] - compressed_indices[..., i - 1] <= plain_dim_size，对于 i=1, ..., compressed_dim_size，其中 plain_dim_size 是普通维度（与压缩维度正交，例如列或行）的数量。

为了确保构建的稀疏张量具有一致的索引、值和大小，可以通过 check_invariants=True 关键字参数在每个张量创建时启用不变量检查，或者全局使用 torch.sparse.check_sparse_tensor_invariants 上下文管理器实例。默认情况下，稀疏张量不变量检查是禁用的。

注意

稀疏压缩布局推广到 N 维张量可能会导致关于指定元素计数的混淆。 当稀疏压缩张量包含批处理维度时，指定元素的数量将对应于每个批处理中此类元素的数量。 当稀疏压缩张量具有稠密维度时，考虑的元素现在是 K 维数组。 同样，对于块稀疏压缩布局，2 维块被视为正在指定的元素。 以一个 3 维块稀疏张量为例，它具有一个长度为 b 的批处理维度，以及一个形状为 p, q 的块。 如果此张量有 n 个指定元素，那么实际上我们每个批处理指定了 n 个块。 此张量的 values 的形状为 (b, n, p, q)。 对指定元素数量的这种解释来自所有稀疏压缩布局都源自二维矩阵的压缩。 批处理维度被视为稀疏矩阵的堆叠，稠密维度将元素的含义从简单的标量值更改为具有自身维度的数组。

稀疏 CSR 张量

与 COO 格式相比，CSR 格式的主要优点是更好地利用存储空间以及更快的计算操作，例如使用 MKL 和 MAGMA 后端的稀疏矩阵-向量乘法。

在最简单的情况下，一个 (0 + 2 + 0) 维稀疏 CSR 张量由三个 1 维张量组成：crow_indices、col_indices 和 values

• crow_indices 张量由压缩行索引组成。 这是一个大小为 nrows + 1（行数加 1）的 1 维张量。 crow_indices 的最后一个元素是指定元素的数量，nse。 此张量编码 values 和 col_indices 中的索引，具体取决于给定行从哪里开始。 张量中每个连续的数字减去它之前的数字表示给定行中元素的数量。

• col_indices 张量包含每个元素的列索引。 这是一个大小为 nse 的 1 维张量。

• values 张量包含 CSR 张量元素的值。 这是一个大小为 nse 的 1 维张量。

注意

索引张量 crow_indices 和 col_indices 的元素类型应为 torch.int64（默认）或 torch.int32。 如果要使用启用 MKL 的矩阵运算，请使用 torch.int32。 这是由于 pytorch 的默认链接与 MKL LP64 链接，后者使用 32 位整数索引。

在一般情况下，(B + 2 + K) 维稀疏 CSR 张量由两个 (B + 1) 维索引张量 crow_indices 和 col_indices，以及 (1 + K) 维 values 张量组成，使得

• crow_indices.shape == (*batchsize, nrows + 1)

• col_indices.shape == (*batchsize, nse)

• values.shape == (nse, *densesize)

而稀疏 CSR 张量的形状为 (*batchsize, nrows, ncols, *densesize)，其中 len(batchsize) == B 且 len(densesize) == K。

注意

稀疏 CSR 张量的批次是相关的：所有批次中指定元素的数量必须相同。 这种有些人为的约束允许有效存储不同 CSR 批次的索引。

注意

可以使用 torch.Tensor.sparse_dim() 和 torch.Tensor.dense_dim() 方法获取稀疏维度和稠密维度的数量。 批处理维度可以从张量形状计算得出：batchsize = tensor.shape[:-tensor.sparse_dim() - tensor.dense_dim()]。

注意

稀疏 CSR 张量的内存消耗至少为 (nrows * 8 + (8 + <size of element type in bytes> * prod(densesize)) * nse) * prod(batchsize) 字节（加上存储其他张量数据的恒定开销）。

使用与 稀疏 COO 格式介绍中的注释 相同的示例数据，具有 100 000 个非零 32 位浮点数的 10 000 x 10 000 张量的内存消耗至少为 (10000 * 8 + (8 + 4 * 1) * 100 000) * 1 = 1 280 000 字节（当使用 CSR 张量布局时）。 请注意，与分别使用 COO 和跨步格式相比，使用 CSR 存储格式可节省 1.6 倍和 310 倍的内存。

CSR 张量的构造

稀疏 CSR 张量可以直接使用 torch.sparse_csr_tensor() 函数构造。 用户必须分别提供行索引、列索引和值张量，其中行索引必须使用 CSR 压缩编码指定。 size 参数是可选的，如果不存在，将从 crow_indices 和 col_indices 推断出来。

>>> crow_indices = torch.tensor([0, 2, 4])
>>> col_indices = torch.tensor([0, 1, 0, 1])
>>> values = torch.tensor([1, 2, 3, 4])
>>> csr = torch.sparse_csr_tensor(crow_indices, col_indices, values, dtype=torch.float64)
>>> csr
tensor(crow_indices=tensor([0, 2, 4]),
       col_indices=tensor([0, 1, 0, 1]),
       values=tensor([1., 2., 3., 4.]), size=(2, 2), nnz=4,
       dtype=torch.float64)
>>> csr.to_dense()
tensor([[1., 2.],
        [3., 4.]], dtype=torch.float64)

注意

推断的 size 中稀疏维度的值是从 crow_indices 的大小和 col_indices 中的最大索引值计算出来的。 如果列数需要大于推断的 size，则必须显式指定 size 参数。

从跨步或稀疏 COO 张量构造 2 维稀疏 CSR 张量的最简单方法是使用 torch.Tensor.to_sparse_csr() 方法。 （跨步）张量中的任何零都将被解释为稀疏张量中的缺失值

>>> a = torch.tensor([[0, 0, 1, 0], [1, 2, 0, 0], [0, 0, 0, 0]], dtype=torch.float64)
>>> sp = a.to_sparse_csr()
>>> sp
tensor(crow_indices=tensor([0, 1, 3, 3]),
      col_indices=tensor([2, 0, 1]),
      values=tensor([1., 1., 2.]), size=(3, 4), nnz=3, dtype=torch.float64)

CSR 张量运算

可以使用 tensor.matmul() 方法执行稀疏矩阵-向量乘法。 这是目前 CSR 张量上唯一支持的数学运算。

>>> vec = torch.randn(4, 1, dtype=torch.float64)
>>> sp.matmul(vec)
tensor([[0.9078],
        [1.3180],
        [0.0000]], dtype=torch.float64)

稀疏 CSC 张量

稀疏 CSC（压缩稀疏列）张量格式实现了用于存储 2 维张量的 CSC 格式，并扩展为支持稀疏 CSC 张量批处理和作为多维张量的数值。

注意

当转置是关于交换稀疏维度时，稀疏 CSC 张量本质上是稀疏 CSR 张量的转置。

与 稀疏 CSR 张量 类似，稀疏 CSC 张量由三个张量组成：ccol_indices、row_indices 和 values

• ccol_indices 张量由压缩列索引组成。 这是一个形状为 (*batchsize, ncols + 1) 的 (B + 1) 维张量。 最后一个元素是指定元素的数量，nse。 此张量编码 values 和 row_indices 中的索引，具体取决于给定列从哪里开始。 张量中每个连续的数字减去它之前的数字表示给定列中元素的数量。

• row_indices 张量包含每个元素的行索引。 这是一个形状为 (*batchsize, nse) 的 (B + 1) 维张量。

• values 张量包含 CSC 张量元素的值。 这是一个形状为 (nse, *densesize) 的 (1 + K) 维张量。

CSC 张量的构造

稀疏 CSC 张量可以直接使用 torch.sparse_csc_tensor() 函数构造。 用户必须分别提供行索引、列索引和值张量，其中列索引必须使用 CSR 压缩编码指定。 size 参数是可选的，如果不存在，将从 row_indices 和 ccol_indices 张量推断出来。

>>> ccol_indices = torch.tensor([0, 2, 4])
>>> row_indices = torch.tensor([0, 1, 0, 1])
>>> values = torch.tensor([1, 2, 3, 4])
>>> csc = torch.sparse_csc_tensor(ccol_indices, row_indices, values, dtype=torch.float64)
>>> csc
tensor(ccol_indices=tensor([0, 2, 4]),
       row_indices=tensor([0, 1, 0, 1]),
       values=tensor([1., 2., 3., 4.]), size=(2, 2), nnz=4,
       dtype=torch.float64, layout=torch.sparse_csc)
>>> csc.to_dense()
tensor([[1., 3.],
        [2., 4.]], dtype=torch.float64)

注意

稀疏 CSC 张量构造函数在行索引参数之前具有压缩列索引参数。

可以使用 torch.Tensor.to_sparse_csc() 方法从任何二维张量构造 (0 + 2 + 0) 维稀疏 CSC 张量。 （跨步）张量中的任何零都将被解释为稀疏张量中的缺失值

>>> a = torch.tensor([[0, 0, 1, 0], [1, 2, 0, 0], [0, 0, 0, 0]], dtype=torch.float64)
>>> sp = a.to_sparse_csc()
>>> sp
tensor(ccol_indices=tensor([0, 1, 2, 3, 3]),
       row_indices=tensor([1, 1, 0]),
       values=tensor([1., 2., 1.]), size=(3, 4), nnz=3, dtype=torch.float64,
       layout=torch.sparse_csc)

稀疏 BSR 张量

稀疏 BSR（块压缩稀疏行）张量格式实现了用于存储二维张量的 BSR 格式，并扩展为支持稀疏 BSR 张量批处理和作为多维张量块的数值。

稀疏 BSR 张量由三个张量组成：crow_indices、col_indices 和 values

• crow_indices 张量由压缩行索引组成。 这是一个形状为 (*batchsize, nrowblocks + 1) 的 (B + 1) 维张量。 最后一个元素是指定的块数，nse。 此张量编码 values 和 col_indices 中的索引，具体取决于给定列块从哪里开始。 张量中每个连续的数字减去它之前的数字表示给定行中块的数量。

• col_indices 张量包含每个元素的列块索引。 这是一个形状为 (*batchsize, nse) 的 (B + 1) 维张量。

• values 张量包含收集到二维块中的稀疏 BSR 张量元素的值。 这是一个形状为 (nse, nrowblocks, ncolblocks, *densesize) 的 (1 + 2 + K) 维张量。

BSR 张量的构造

稀疏 BSR 张量可以直接使用 torch.sparse_bsr_tensor() 函数构造。 用户必须分别提供行块索引、列块索引和值张量，其中行块索引必须使用 CSR 压缩编码指定。 size 参数是可选的，如果不存在，将从 crow_indices 和 col_indices 张量推断出来。

>>> crow_indices = torch.tensor([0, 2, 4])
>>> col_indices = torch.tensor([0, 1, 0, 1])
>>> values = torch.tensor([[[0, 1, 2], [6, 7, 8]],
...                        [[3, 4, 5], [9, 10, 11]],
...                        [[12, 13, 14], [18, 19, 20]],
...                        [[15, 16, 17], [21, 22, 23]]])
>>> bsr = torch.sparse_bsr_tensor(crow_indices, col_indices, values, dtype=torch.float64)
>>> bsr
tensor(crow_indices=tensor([0, 2, 4]),
       col_indices=tensor([0, 1, 0, 1]),
       values=tensor([[[ 0.,  1.,  2.],
                       [ 6.,  7.,  8.]],
                      [[ 3.,  4.,  5.],
                       [ 9., 10., 11.]],
                      [[12., 13., 14.],
                       [18., 19., 20.]],
                      [[15., 16., 17.],
                       [21., 22., 23.]]]),
       size=(4, 6), nnz=4, dtype=torch.float64, layout=torch.sparse_bsr)
>>> bsr.to_dense()
tensor([[ 0.,  1.,  2.,  3.,  4.,  5.],
        [ 6.,  7.,  8.,  9., 10., 11.],
        [12., 13., 14., 15., 16., 17.],
        [18., 19., 20., 21., 22., 23.]], dtype=torch.float64)

可以使用 torch.Tensor.to_sparse_bsr() 方法从任何二维张量构造 (0 + 2 + 0) 维稀疏 BSR 张量，该方法还需要指定值块大小

>>> dense = torch.tensor([[0, 1, 2, 3, 4, 5],
...                       [6, 7, 8, 9, 10, 11],
...                       [12, 13, 14, 15, 16, 17],
...                       [18, 19, 20, 21, 22, 23]])
>>> bsr = dense.to_sparse_bsr(blocksize=(2, 3))
>>> bsr
tensor(crow_indices=tensor([0, 2, 4]),
       col_indices=tensor([0, 1, 0, 1]),
       values=tensor([[[ 0,  1,  2],
                       [ 6,  7,  8]],
                      [[ 3,  4,  5],
                       [ 9, 10, 11]],
                      [[12, 13, 14],
                       [18, 19, 20]],
                      [[15, 16, 17],
                       [21, 22, 23]]]), size=(4, 6), nnz=4,
       layout=torch.sparse_bsr)

稀疏 BSC 张量

稀疏 BSC（块压缩稀疏列）张量格式实现了用于存储二维张量的 BSC 格式，并扩展为支持稀疏 BSC 张量批处理和作为多维张量块的数值。

稀疏 BSC 张量由三个张量组成：ccol_indices、row_indices 和 values

• ccol_indices 张量由压缩列索引组成。 这是一个形状为 (*batchsize, ncolblocks + 1) 的 (B + 1) 维张量。 最后一个元素是指定的块数，nse。 此张量编码 values 和 row_indices 中的索引，具体取决于给定行块从哪里开始。 张量中每个连续的数字减去它之前的数字表示给定列中块的数量。

• row_indices 张量包含每个元素的行块索引。 这是一个形状为 (*batchsize, nse) 的 (B + 1) 维张量。

• values 张量包含收集到二维块中的稀疏 BSC 张量元素的值。 这是一个形状为 (nse, nrowblocks, ncolblocks, *densesize) 的 (1 + 2 + K) 维张量。

BSC 张量的构造

稀疏 BSC 张量可以直接使用 torch.sparse_bsc_tensor() 函数构造。 用户必须分别提供行块索引、列块索引和值张量，其中列块索引必须使用 CSR 压缩编码指定。 size 参数是可选的，如果不存在，将从 ccol_indices 和 row_indices 张量推断出来。

>>> ccol_indices = torch.tensor([0, 2, 4])
>>> row_indices = torch.tensor([0, 1, 0, 1])
>>> values = torch.tensor([[[0, 1, 2], [6, 7, 8]],
...                        [[3, 4, 5], [9, 10, 11]],
...                        [[12, 13, 14], [18, 19, 20]],
...                        [[15, 16, 17], [21, 22, 23]]])
>>> bsc = torch.sparse_bsc_tensor(ccol_indices, row_indices, values, dtype=torch.float64)
>>> bsc
tensor(ccol_indices=tensor([0, 2, 4]),
       row_indices=tensor([0, 1, 0, 1]),
       values=tensor([[[ 0.,  1.,  2.],
                       [ 6.,  7.,  8.]],
                      [[ 3.,  4.,  5.],
                       [ 9., 10., 11.]],
                      [[12., 13., 14.],
                       [18., 19., 20.]],
                      [[15., 16., 17.],
                       [21., 22., 23.]]]), size=(4, 6), nnz=4,
       dtype=torch.float64, layout=torch.sparse_bsc)

用于处理稀疏压缩张量的工具

所有稀疏压缩张量（CSR、CSC、BSR 和 BSC 张量）在概念上都非常相似，因为它们的索引数据被分成两个部分：所谓的压缩索引（使用 CSR 编码）和所谓的普通索引（与压缩索引正交）。这使得这些张量上的各种工具可以共享相同的实现，这些实现通过张量布局进行参数化。

稀疏压缩张量的构造

稀疏 CSR、CSC、BSR 和 CSC 张量可以使用 torch.sparse_compressed_tensor() 函数构造，该函数具有与上面讨论的构造函数 torch.sparse_csr_tensor()、 torch.sparse_csc_tensor()、 torch.sparse_bsr_tensor() 和 torch.sparse_bsc_tensor() 相同的接口，但需要一个额外的 layout 参数。以下示例说明了通过为 torch.sparse_compressed_tensor() 函数指定相应的布局参数，使用相同输入数据构造 CSR 和 CSC 张量的方法

>>> compressed_indices = torch.tensor([0, 2, 4])
>>> plain_indices = torch.tensor([0, 1, 0, 1])
>>> values = torch.tensor([1, 2, 3, 4])
>>> csr = torch.sparse_compressed_tensor(compressed_indices, plain_indices, values, layout=torch.sparse_csr)
>>> csr
tensor(crow_indices=tensor([0, 2, 4]),
       col_indices=tensor([0, 1, 0, 1]),
       values=tensor([1, 2, 3, 4]), size=(2, 2), nnz=4,
       layout=torch.sparse_csr)
>>> csc = torch.sparse_compressed_tensor(compressed_indices, plain_indices, values, layout=torch.sparse_csc)
>>> csc
tensor(ccol_indices=tensor([0, 2, 4]),
       row_indices=tensor([0, 1, 0, 1]),
       values=tensor([1, 2, 3, 4]), size=(2, 2), nnz=4,
       layout=torch.sparse_csc)
>>> (csr.transpose(0, 1).to_dense() == csc.to_dense()).all()
tensor(True)

支持的操作

线性代数运算

下表总结了稀疏矩阵上支持的线性代数运算，其中操作数的布局可能不同。这里 T[layout] 表示具有给定布局的张量。类似地，M[layout] 表示矩阵（2-D PyTorch 张量），V[layout] 表示向量（1-D PyTorch 张量）。此外，f 表示标量（浮点数或 0-D PyTorch 张量），* 是逐元素乘法，@ 是矩阵乘法。

PyTorch 操作	稀疏梯度？	布局签名
torch.mv()	否	M[sparse_coo] @ V[strided] -> V[strided]
torch.mv()	否	M[sparse_csr] @ V[strided] -> V[strided]
torch.matmul()	否	M[sparse_coo] @ M[strided] -> M[strided]
torch.matmul()	否	M[sparse_csr] @ M[strided] -> M[strided]
torch.matmul()	否	M[SparseSemiStructured] @ M[strided] -> M[strided]
torch.matmul()	否	M[strided] @ M[SparseSemiStructured] -> M[strided]
torch.mm()	否	M[sparse_coo] @ M[strided] -> M[strided]
torch.mm()	否	M[SparseSemiStructured] @ M[strided] -> M[strided]
torch.mm()	否	M[strided] @ M[SparseSemiStructured] -> M[strided]
torch.sparse.mm()	是	M[sparse_coo] @ M[strided] -> M[strided]
torch.smm()	否	M[sparse_coo] @ M[strided] -> M[sparse_coo]
torch.hspmm()	否	M[sparse_coo] @ M[strided] -> M[hybrid sparse_coo]
torch.bmm()	否	T[sparse_coo] @ T[strided] -> T[strided]
torch.addmm()	否	f * M[strided] + f * (M[sparse_coo] @ M[strided]) -> M[strided]
torch.addmm()	否	f * M[strided] + f * (M[SparseSemiStructured] @ M[strided]) -> M[strided]
torch.addmm()	否	f * M[strided] + f * (M[strided] @ M[SparseSemiStructured]) -> M[strided]
torch.sparse.addmm()	是	f * M[strided] + f * (M[sparse_coo] @ M[strided]) -> M[strided]
torch.sparse.spsolve()	否	SOLVE(M[sparse_csr], V[strided]) -> V[strided]
torch.sspaddmm()	否	f * M[sparse_coo] + f * (M[sparse_coo] @ M[strided]) -> M[sparse_coo]
torch.lobpcg()	否	GENEIG(M[sparse_coo]) -> M[strided], M[strided]
torch.pca_lowrank()	是	PCA(M[sparse_coo]) -> M[strided], M[strided], M[strided]
torch.svd_lowrank()	是	SVD(M[sparse_coo]) -> M[strided], M[strided], M[strided]

其中“稀疏梯度？”列指示 PyTorch 操作是否支持相对于稀疏矩阵参数的反向传播。所有 PyTorch 操作，除了 torch.smm()，都支持相对于步幅矩阵参数的反向传播。

注意

目前，PyTorch 不支持布局签名为 M[strided] @ M[sparse_coo] 的矩阵乘法。但是，应用程序仍然可以使用矩阵关系 D @ S == (S.t() @ D.t()).t() 来计算它。

张量方法和稀疏性

以下张量方法与稀疏张量相关

Tensor.is_sparse	如果张量使用稀疏 COO 存储布局，则为 True，否则为 False。
Tensor.is_sparse_csr	如果张量使用稀疏 CSR 存储布局，则为 True，否则为 False。
Tensor.dense_dim	返回 稀疏张量 self 中的稠密维度数。
Tensor.sparse_dim	返回 稀疏张量 self 中的稀疏维度数。
Tensor.sparse_mask	返回一个新的 稀疏张量，其值来自步幅张量 self，并由稀疏张量 mask 的索引过滤。
Tensor.to_sparse	返回张量的稀疏副本。
Tensor.to_sparse_coo	将张量转换为 坐标格式。
Tensor.to_sparse_csr	将张量转换为压缩行存储格式 (CSR)。
Tensor.to_sparse_csc	将张量转换为压缩列存储 (CSC) 格式。
Tensor.to_sparse_bsr	将张量转换为给定块大小的块稀疏行 (BSR) 存储格式。
Tensor.to_sparse_bsc	将张量转换为给定块大小的块稀疏列 (BSC) 存储格式。
Tensor.to_dense	如果 self 不是步幅张量，则创建 self 的步幅副本，否则返回 self。
Tensor.values	返回 稀疏 COO 张量 的值张量。

以下张量方法特定于稀疏 COO 张量

Tensor.coalesce	如果 self 是 未合并张量，则返回 self 的合并副本。
Tensor.sparse_resize_	将 self 稀疏张量 调整为所需大小以及稀疏和稠密维度的数量。
Tensor.sparse_resize_and_clear_	从 稀疏张量 self 中删除所有指定的元素，并将 self 调整为所需大小以及稀疏和稠密维度的数量。
Tensor.is_coalesced	如果 self 是已合并的 稀疏 COO 张量，则返回 True，否则返回 False。
Tensor.indices	返回 稀疏 COO 张量 的索引张量。

以下方法特定于 稀疏 CSR 张量 和 稀疏 BSR 张量

Tensor.crow_indices	当 self 是布局为 sparse_csr 的稀疏 CSR 张量时，返回包含 self 张量的压缩行索引的张量。
Tensor.col_indices	当 self 是布局为 sparse_csr 的稀疏 CSR 张量时，返回包含 self 张量的列索引的张量。

以下方法特定于 稀疏 CSC 张量 和 稀疏 BSC 张量

Tensor.row_indices
Tensor.ccol_indices

以下张量方法支持稀疏 COO 张量

add() add_() addmm() addmm_() any() asin() asin_() arcsin() arcsin_() bmm() clone() deg2rad() deg2rad_() detach() detach_() dim() div() div_() floor_divide() floor_divide_() get_device() index_select() isnan() log1p() log1p_() mm() mul() mul_() mv() narrow_copy() neg() neg_() negative() negative_() numel() rad2deg() rad2deg_() resize_as_() size() pow() sqrt() square() smm() sspaddmm() sub() sub_() t() t_() transpose() transpose_() zero_()

特定于稀疏张量的 Torch 函数

sparse_coo_tensor	使用给定 indices 处指定的值构造 COO(rdinate) 格式的稀疏张量。
sparse_csr_tensor	使用给定 crow_indices 和 col_indices 处指定的值构造 CSR（压缩稀疏行）格式的稀疏张量。
sparse_csc_tensor	使用给定 ccol_indices 和 row_indices 处指定的值构造 CSC（压缩稀疏列）格式的稀疏张量。
sparse_bsr_tensor	使用给定 crow_indices 和 col_indices 处指定的 2 维块构造 BSR（块压缩稀疏行）格式的稀疏张量。
sparse_bsc_tensor	使用给定 ccol_indices 和 row_indices 处指定的 2 维块构造 BSC（块压缩稀疏列）格式的稀疏张量。
sparse_compressed_tensor	使用给定 compressed_indices 和 plain_indices 处指定的值构造 压缩稀疏格式（CSR、CSC、BSR 或 BSC）的稀疏张量。
sparse.sum	返回给定稀疏张量的每一行的总和。
sparse.addmm	此函数在前向传播中执行与 torch.addmm() 完全相同的操作，不同之处在于它支持稀疏 COO 矩阵 mat1 的反向传播。
sparse.sampled_addmm	在由 input 的稀疏模式指定的位置执行稠密矩阵 mat1 和 mat2 的矩阵乘法。
sparse.mm	执行稀疏矩阵 mat1 的矩阵乘法
sspaddmm	将稀疏张量 mat1 与稠密张量 mat2 相乘，然后将稀疏张量 input 添加到结果中。
hspmm	执行 稀疏 COO 矩阵 mat1 和步幅矩阵 mat2 的矩阵乘法。
smm	执行稀疏矩阵 input 与稠密矩阵 mat 的矩阵乘法。
sparse.softmax	应用 softmax 函数。
sparse.spsolve	计算具有唯一解的线性方程组的平方系统的解。
sparse.log_softmax	应用 softmax 函数，然后应用对数。
sparse.spdiags	通过将 diagonals 行中的值沿输出的指定对角线放置来创建稀疏 2D 张量

其他函数

以下 torch 函数支持稀疏张量

cat() dstack() empty() empty_like() hstack() index_select() is_complex() is_floating_point() is_nonzero() is_same_size() is_signed() is_tensor() lobpcg() mm() native_norm() pca_lowrank() select() stack() svd_lowrank() unsqueeze() vstack() zeros() zeros_like()

要管理检查稀疏张量不变量，请参阅

sparse.check_sparse_tensor_invariants

一种控制检查稀疏张量不变量的工具。

要将稀疏张量与 gradcheck() 函数一起使用，请参阅

sparse.as_sparse_gradcheck

装饰器函数，用于为稀疏张量扩展 gradcheck。

保零一元函数

我们的目标是支持所有“保零一元函数”：将零映射到零的单参数函数。

如果您发现我们缺少您需要的保零一元函数，请随时提出功能请求的 issue。与往常一样，在打开 issue 之前，请先尝试搜索功能。

以下运算符当前支持稀疏 COO/CSR/CSC/BSR/CSR 张量输入。

abs() asin() asinh() atan() atanh() ceil() conj_physical() floor() log1p() neg() round() sin() sinh() sign() sgn() signbit() tan() tanh() trunc() expm1() sqrt() angle() isinf() isposinf() isneginf() isnan() erf() erfinv()