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)
算子概览¶
从根本上讲，对具有稀疏存储格式的 Tensor 进行操作的行为与对具有跨步（或其他）存储格式的 Tensor 进行操作的行为相同。存储的特殊性，即数据的物理布局，会影响操作的性能，但不应影响其语义。
我们正在积极增加稀疏张量的算子覆盖范围。用户目前不应期望获得与密集张量相同级别的支持。有关列表，请参阅我们的算子文档。
>>> 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 中，半结构化稀疏性通过 Tensor 子类实现。通过子类化，我们可以重写 __torch_dispatch__，从而在执行矩阵乘法时使用更快的稀疏核函数。我们还可以将张量以其压缩形式存储在子类内部，以减少内存开销。
在这种压缩形式中，稀疏张量只保留**指定**的元素和一些编码掩码的元数据来存储。
注意
半结构化稀疏张量的**指定**元素和元数据掩码存储在一个扁平的压缩张量中。它们彼此附加形成一块连续的内存区域。
压缩张量 = [ 原始张量的指定元素 | 元数据掩码 ]
对于大小为 (r, c) 的原始张量，我们期望前 m * k // 2 个元素是保留的元素，张量的其余部分是元数据。
为了方便用户查看指定元素和掩码，可以使用 .indices() 和 .values() 分别访问掩码和指定元素。
.values()返回大小为 (r, c//2) 且 dtype 与密集矩阵相同的张量中的指定元素。.indices()返回大小为 (r, c//2) 的张量中的元数据掩码，如果 dtype 是 torch.float16 或 torch.bfloat16，其元素类型为torch.int16，如果 dtype 是 torch.int8，则元素类型为torch.int32。
对于 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。
使用这些计算，我们可以确定原始密集表示和新稀疏表示的总内存占用。
这为我们提供了一个计算压缩比的简单公式，该公式仅取决于张量数据类型的位宽。
通过使用此公式，我们发现对于 torch.float16 或 torch.bfloat16，压缩比为 56.25%，对于 torch.int8，压缩比为 62.5%。
构建稀疏半结构化张量¶
您可以通过简单地使用 torch.to_sparse_semi_structured 函数，将密集张量转换为稀疏半结构化张量。
另请注意，我们仅支持 CUDA 张量，因为半结构化稀疏性的硬件兼容性仅限于 NVIDIA GPU。
半结构化稀疏性支持以下数据类型。请注意，每种数据类型都有其自己的形状约束和压缩系数。
PyTorch 数据类型 |
形状约束 |
压缩系数 |
稀疏模式 |
|---|---|---|---|
|
张量必须是 2D 的，并且 (r, c) 都必须是 64 的正倍数 |
9/16 |
2:4 |
|
张量必须是 2D 的，并且 (r, c) 都必须是 64 的正倍数 |
9/16 |
2:4 |
|
张量必须是 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)
要使用这些操作，只需在张量以半结构化稀疏格式包含 0 后，传递 to_sparse_semi_structured(tensor) 的输出，而不是直接使用 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 实现了一种称为 Coordinate format（坐标格式），或 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> 字节。
例如，一个 10 000 x 10 000 的张量，包含 100 000 个非零的 32 位浮点数，使用 COO 张量布局时，内存消耗至少为 (2 * 8 + 4) * 100 000 = 2 000 000 字节；使用默认的跨步张量布局时，内存消耗至少为 10 000 * 10 000 * 4 = 400 000 000 字节。注意，使用 COO 存储格式可节省 200 倍的内存。
构建¶
通过向函数 `torch.sparse_coo_tensor()` 提供索引和值这两个张量，以及稀疏张量的大小（当无法从索引和值张量推断时），可以构建一个稀疏 COO 张量。
假设我们想定义一个稀疏张量，在位置 (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-D 非合并张量
>>> 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()` 方法分别获取稀疏维度和密集维度的数量。批量维度可以从张量形状计算得出：batchsize = tensor.shape[:-tensor.sparse_dim() - 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。
稀疏压缩张量¶
稀疏压缩张量代表一类稀疏张量，它们通过一种编码来压缩特定维度的索引，从而能够对稀疏压缩张量的线性代数核进行某些优化。这种编码基于 Compressed Sparse Row (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 维数组。此外，对于块状稀疏压缩布局，将 2D 块视为被指定的元素。举例来说，一个 3 维块状稀疏张量，包含一个长度为 b 的批量维度，以及形状为 p, q 的块。如果此张量有 n 个指定元素，则实际上我们每个批量指定了 n 个块。该张量的 values 形状将为 (b, n, p, q)。对指定元素数量的这种解释源于所有稀疏压缩布局都是从 2 维矩阵的压缩中派生出来的。批量维度被视为稀疏矩阵的堆叠，密集维度将元素的含义从简单的标量值改变为具有自身维度的数组。
稀疏 CSR 张量¶
与 COO 格式相比，CSR 格式的主要优点是更好地利用存储空间，以及使用 MKL 和 MAGMA 后端进行的稀疏矩阵向量乘法等计算操作快得多。
在最简单的情况下，(0 + 2 + 0) 维稀疏 CSR 张量由三个 1-D 张量组成：crow_indices、col_indices 和 values
crow_indices张量由压缩的行索引组成。这是一个大小为nrows + 1（行数加 1）的 1-D 张量。crow_indices的最后一个元素是指定元素的数量nse。该张量根据给定行的起始位置，在values和col_indices中编码索引。张量中每个后继数字减去前一个数字表示给定行中的元素数量。
col_indices张量包含每个元素的列索引。这是一个大小为nse的 1-D 张量。
values张量包含 CSR 张量元素的值。这是一个大小为nse的 1-D 张量。
注意
索引张量 crow_indices 和 col_indices 的元素类型应为 torch.int64（默认）或 torch.int32。如果要使用支持 MKL 的矩阵操作，请使用 torch.int32。这是由于 pytorch 默认链接的是使用 32 位整数索引的 MKL LP64。
在一般情况下，(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 格式介绍中的说明 相同的示例数据，一个 10 000 x 10 000 的张量，包含 100 000 个非零的 32 位浮点数，使用 CSR 张量布局时，内存消耗至少为 (10000 * 8 + (8 + 4 * 1) * 100 000) * 1 = 1 280 000 字节。注意，使用 CSR 存储格式相比 COO 和跨步格式，分别节省了 1.6 倍和 310 倍的内存。
构建 CSR 张量¶
可以使用 `torch.sparse_csr_tensor()` 函数直接构建稀疏 CSR 张量。用户必须单独提供行索引、列索引和值张量，其中行索引必须使用 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-D 稀疏 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 (压缩稀疏列) 张量格式实现了 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 张量构造函数将压缩后的列索引参数放在行索引参数之前。
(0 + 2 + 0) 维稀疏 CSC 张量可以使用 torch.Tensor.to_sparse_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)
(0 + 2 + 0) 维稀疏 BSR 张量可以使用 torch.Tensor.to_sparse_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] 表示一个矩阵 (二维 PyTorch 张量)，而 V[layout] 表示一个向量 (一维 PyTorch 张量)。此外，f 表示一个标量 (浮点数或零维 PyTorch 张量)，* 是按元素乘法，@ 是矩阵乘法。
PyTorch 操作 |
稀疏梯度? |
布局签名 |
|---|---|---|
否 |
|
|
否 |
|
|
否 |
|
|
否 |
|
|
否 |
|
|
否 |
|
|
否 |
|
|
否 |
|
|
否 |
|
|
是 |
|
|
否 |
|
|
否 |
|
|
否 |
|
|
否 |
|
|
否 |
|
|
否 |
|
|
是 |
|
|
否 |
|
|
否 |
|
|
否 |
|
|
是 |
|
|
是 |
|
其中“稀疏梯度?” 列表示 PyTorch 操作是否支持对稀疏矩阵参数进行反向传播 (backward)。除了 torch.smm() 之外，所有 PyTorch 操作都支持对跨步矩阵参数进行反向传播。
注意
目前，PyTorch 不支持布局签名为 M[strided] @ M[sparse_coo] 的矩阵乘法。然而，应用程序仍然可以使用矩阵关系 D @ S == (S.t() @ D.t()).t() 来计算它。
Tensor 方法和稀疏张量¶
以下 Tensor 方法与稀疏张量相关
如果 Tensor 使用稀疏 COO 存储布局，则为 |
|
如果 Tensor 使用稀疏 CSR 存储布局，则为 |
|
返回 稀疏张量 |
|
返回 稀疏张量 |
|
返回一个新 稀疏张量，其值来自跨步张量 |
|
返回张量的一个稀疏副本。 |
|
将张量转换为 坐标格式。 |
|
将张量转换为压缩行存储格式 (CSR)。 |
|
将张量转换为压缩列存储格式 (CSC)。 |
|
将张量转换为分块稀疏行 (BSR) 存储格式，并指定块大小。 |
|
将张量转换为分块稀疏列 (BSC) 存储格式，并指定块大小。 |
|
如果 |
|
返回 稀疏 COO 张量 的值张量。 |
以下 Tensor 方法专门用于稀疏 COO 张量
如果 |
|
将 |
|
从 稀疏张量 |
|
如果 |
|
返回 稀疏 COO 张量 的索引张量。 |
以下方法专门用于 稀疏 CSR 张量 和 稀疏 BSR 张量
当 |
|
当 |
以下方法专门用于 稀疏 CSC 张量 和 稀疏 BSC 张量
以下 Tensor 方法支持稀疏 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 函数¶
使用指定值在给定 |
|
使用指定值在给定 |
|
使用指定值在给定 |
|
使用指定的二维块在给定 |
|
使用指定的二维块在给定 |
|
使用指定值在给定 |
|
返回给定稀疏张量每行的总和。 |
|
这个函数在前向传播中与 |
|
在由 |
|
对稀疏矩阵 |
|
将稀疏张量 |
|
对 稀疏 COO 矩阵 |
|
对稀疏矩阵 |
|
应用 softmax 函数。 |
|
计算具有唯一解的线性方程组的解。 |
|
应用 softmax 函数后跟对数。 |
|
通过将 |
其他函数¶
以下 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()
为了管理稀疏张量不变性检查，请参阅
一个用于控制稀疏张量不变性检查的工具。 |
若要将稀疏张量与 gradcheck() 函数一起使用，请参阅
装饰函数，以扩展 gradcheck 以支持稀疏张量。 |
零保持的一元函数¶
我们目标是支持所有‘零保持的一元函数’：接受一个参数并将零映射到零的函数。
如果您发现我们缺少您需要的零保持的一元函数，请随时提交 feature request 的 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()
