torch.sparse¶
警告
稀疏张量的 PyTorch API 目前处于测试阶段，在不久的将来可能会发生变化。 我们强烈欢迎作为 GitHub 问题的功能请求、错误报告和一般建议。
为什么以及何时使用 sparsity¶
默认情况下，PyTorch 将元素连续存储在
物理内存。这导致了各种数组的高效实现
需要快速访问元素的处理算法。
现在，一些用户可能决定表示图形邻接等数据 矩阵、修剪的权重或点云，其元素为 大多数是零值。我们认识到这些是重要的应用，并致力于 通过稀疏存储格式为这些使用案例提供性能优化。
COO、CSR/CSC、半结构化、LIL 等各种稀疏存储格式已经被 多年来发展起来。虽然它们的确切布局不同，但它们都 通过有效表示零值元素来压缩数据。 我们将 specified 的未压缩值称为 unspecified 与 unspecified 相反， 压缩元素。
通过压缩重复零，稀疏存储格式旨在节省内存 以及各种 CPU 和 GPU 上的计算资源。特别适用于高 稀疏度或高度结构化稀疏度，这可能具有显著的 性能影响。因此，稀疏存储格式可以看作是 性能优化。
与许多其他性能优化一样，稀疏存储格式则不是 总是有利的。为您的用例尝试稀疏格式时 您可能会发现执行时间增加而不是减少。
如果您分析，请鼓励您打开 GitHub 问题 预计性能会有明显的提升，但测得的 degradation 的。这有助于我们确定实施的优先级 高效的内核和更广泛的性能优化。
我们可以轻松尝试不同的稀疏布局，并在它们之间进行转换， 而不会对最适合您的特定应用程序的看法。
功能概述¶
我们希望从 通过为每个布局提供转换例程来给定 dense Tensor。
在下一个示例中，我们将转换默认 dense （strided） 的 2D Tensor layout 分配给由 COO 内存布局支持的 2D Tensor。Only values 和 在这种情况下，将存储非零元素的索引。
>>> 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： semi-structured sparsity<sparse-semi-structured-docs>。 有关更多详细信息，请参阅参考资料。
请注意，我们提供了这些格式的轻微概括。
批处理：GPU 等设备需要批处理以获得最佳性能，并且 因此，我们支持 Batch 维度。
我们目前提供了一个非常简单的批处理版本，其中每个组件都是稀疏格式 本身是批处理的。这也需要每个批次条目具有相同数量的指定元素。 在此示例中，我们从 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)
密集维度：另一方面，某些数据（如 Graph 嵌入）可能是 最好将其视为向量的稀疏集合，而不是标量。
在此示例中，我们创建了一个具有 2 个稀疏维度和 1 个密集维度的 3D Hybrid COO Tensor 来自 3D 跨步张量。如果 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 的操作。的特点 存储（即数据的物理布局）会影响 操作，但不应影响语义。
我们正在积极增加稀疏张量的运算符覆盖率。用户不应 expect 支持与密集 Tensor 相同级别的支持。 有关列表，请参阅我们的 operator 文档。
>>> 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.非零保留一元运算的输出 将无法利用稀疏存储格式 extent 作为输入，并可能导致内存的灾难性增加。 相反，我们依赖于用户首先显式转换为密集的 Tensor，然后 然后运行该操作。
>>> b_s.to_dense().cos()
tensor([[ 1.0000, -0.4161],
[-0.9900, 1.0000]])
我们知道，一些用户希望忽略压缩的零，例如 作为 cos，而不是保留操作的确切语义。为此，我们 可以指向 torch.masked 及其 MaskedTensor，而后者又是支持的，并且 由 Sparse Storage Format 和 Kernels 提供支持。
另请注意，目前，用户无法选择输出布局。例如 将稀疏 Tensor 添加到常规跨步 Tensor 会得到一个跨步 Tensor。一些 用户可能更喜欢保持稀疏布局，因为他们知道结果会 仍然足够稀疏。
>>> a + b.to_sparse()
tensor([[0., 3.],
[3., 0.]])
我们承认，访问可以有效地产生不同输出的内核 布局可能非常有用。后续操作可能会从中受益匪浅 接收特定布局。我们正在开发一个 API 来控制结果布局 并认识到规划更优化的执行路径是一项重要功能 任何给定的模型。
稀疏半结构化张量¶
警告
稀疏半结构化张量目前是一个原型功能，可能会发生变化。请随时打开一个问题来报告错误，或者如果您有任何反馈要分享。
半结构化稀疏性是一种稀疏数据布局，最初是在 NVIDIA 的 Ampere 架构中引入的。它也称为细粒度结构化稀疏性或 2：4 结构化稀疏性。
这种稀疏布局每 2n 个元素存储 n 个元素，其中 n 由 Tensor 数据类型 （dtype） 的宽度决定。最常用的 dtype 是 float16，其中 n=2，因此称为“2：4 结构化稀疏”。
半结构化稀疏性在这篇 NVIDIA 博客文章中有更详细的解释。
在 PyTorch 中，半结构化稀疏性是通过 Tensor 子类实现的。
通过子类化，我们可以覆盖 ，允许我们在执行矩阵乘法时使用更快的稀疏内核。
我们还可以将张量以压缩形式存储在子类中，以减少内存开销。__torch_dispatch__
在这种压缩形式中，稀疏张量通过仅保留指定的元素和一些元数据（对掩码进行编码）来存储。
注意
半结构化稀疏张量的指定元素和元数据掩码一起存储在单个 平面压缩张量。它们彼此附加以形成一个连续的内存块。
压缩张量 = [ 原始张量的指定元素 | metadata_mask ]
对于大小为 （r， c） 的原始张量，我们期望前 m * k // 2 个元素是保留的元素 Tensor 的其余部分是元数据。
为了方便用户查看指定的元素
和 mask 一起访问，可以使用 和 分别访问 mask 和指定的元素。.indices().values()
.values()返回大小为 （r， c//2） 且 DTYPE 与 Dense 矩阵相同的张量中的指定元素。.indices()返回大小为 （r， c//2 ） 的张量中的metadata_mask，如果 dtype 为 torch.float16 或 torch.bfloat16，则返回元素类型（如果 dtype 为 torch.int8）。torch.int16torch.int32
对于 2：4 稀疏张量，元数据开销很小 - 每个指定元素只有 2 位。
注意
请务必注意，仅支持 1：2 稀疏性。因此，它不遵循与上述相同的公式。torch.float32
在这里，我们分解了如何计算 2：4 稀疏张量的压缩率（大小密集/大小稀疏）。
设 （r， c） = tensor.shape 和 e = bitwidth（tensor.dtype），因此 e = 16 对于 和 e = 8 对于 .torch.float16torch.bfloat16torch.int8
使用这些计算，我们可以确定原始 dense 表示和新的 sparse 表示的总内存占用。
这为我们提供了一个简单的压缩率公式，该公式仅取决于 tensor 数据类型的位宽。
通过使用这个公式，我们发现 or 的压缩率为 56.25%，而 的压缩率为 62.5%。torch.float16torch.bfloat16torch.int8
构造稀疏半结构化张量¶
您只需使用该函数即可将密集张量转换为稀疏半结构化张量。torch.to_sparse_semi_structured
另请注意，我们只支持 CUDA 张量，因为半结构化稀疏性的硬件兼容性仅限于 NVIDIA GPU。
半结构化稀疏性支持以下数据类型。请注意，每种数据类型都有自己的形状约束和压缩因子。
PyTorch 数据类型 |
形状约束 |
压缩系数 |
稀疏模式 |
|---|---|---|---|
|
Tensor 必须是 2D 并且 （r， c） 都必须是 64 的正倍数 |
9/16 |
2:4 |
|
Tensor 必须是 2D 并且 （r， c） 都必须是 64 的正倍数 |
9/16 |
2:4 |
|
Tensor 必须是 2D 并且 （r， c） 都必须是 128 的正倍数 |
10/16 |
2:4 |
要构造半结构化稀疏张量，首先要创建一个遵循 2：4（或半结构化）稀疏格式的常规密集张量。
为此，我们平铺一个小的 1x4 条带，以创建一个 16x16 密集的 float16 张量。
之后，我们可以调用 function 对其进行压缩以加速推理。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))
稀疏半结构化张量操作¶
目前，半结构化稀疏 Tensor 支持以下操作：
torch.addmm（bias， dense， sparse.t（））
torch.mm（密集、稀疏）
torch.mm（稀疏、密集）
aten.linear.default（密集、稀疏、偏差）
aten.t.default（稀疏）
aten.t.detach（稀疏）
要使用这些运算，只需传递 of 的输出，而不是在张量以半结构化稀疏格式具有 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.线性与半结构化稀疏性¶
如果权重已经是半结构化稀疏的，则只需几行代码即可加速模型中的线性层：
>>> 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 format 作为实现 sparse 的存储格式之一 张。在 COO 格式中，指定的元素存储为 Tuples 元素索引和相应值。特别
指定元素的索引以 size 的 Tensor 和 element type ， 收集
indices(ndim, nse)torch.int64相应的值收集在 Tensor 的 size 和任意整数或浮点数 Number 元素类型、
values(nse,)
其中 是张量的维数，是
指定元素的数量。ndimnse
注意
稀疏 COO 张量的内存消耗至少为字节（加上一个常量
存储其他张量数据的开销）。(ndim *
8 + <size of element type in bytes>) * nse
跨步张量的内存消耗至少为 。product(<tensor shape>) * <size of element type in bytes>
例如，一个 10 000 x 10 000 张量的内存消耗
使用 COO 张量时，100 000 个非零 32 位浮点数至少是字节
layout 和 bytes
默认的跨步张量布局。注意 200 倍内存
使用 COO 存储格式进行保存。(2 * 8 + 4) * 100 000 = 2 000 00010 000 * 10 000 * 4 = 400 000 000
建设¶
稀疏 COO 张量可以通过提供
indices 和 values，以及稀疏张量的大小（当它
无法从 indices 和 values 张量推断出）到函数 。
假设我们想定义一个稀疏张量，条目 3 位于 location （0， 2），位置 （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]])
请注意，input 不是索引 Tuples 的列表。如果需要帮助，
要以这种方式编写索引，您应该在将它们传递给
Sparse 构造函数：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 张量通过允许
tensor 设置为多维张量，以便我们
有：values
指定元素的索引以 size 的 Tensor 和 element type ， 收集
indices(sparse_dims, nse)torch.int64相应的 （Tensor） 值以 size 的 Tensor 和任意整数收集 或浮点数元素类型。
values(nse, dense_dims)
注意
我们使用 （M + K） 维张量来表示 N 维稀疏 混合张量，其中 M 和 K 是稀疏和密集的数量 维度，使得 M + K == N 成立。
假设我们想创建一个 （2 + 1） 维张量，其中条目为 [3， 4] 在位置 （0， 2），条目 [5， 6] 在位置 （1， 0） 和条目 [7， 8] 在位置 （1， 2）。我们会写
>>> 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]]])
一般来说，如果 是一个稀疏 COO 张量和 ，那么我们有以下内容
invariants：sM =
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]- 值 的 Hybrid Tensor 是 K 维张量，
s.values().layout == torch.strided- 值存储为 跨步张量。
注意
密集维度始终遵循稀疏维度，即混合 不支持密集和稀疏维度。
未合并的稀疏 COO 张量¶
PyTorch 稀疏 COO 张量格式允许稀疏未合并张量，
索引中可能存在重复的坐标;在本例中，
解释是该索引处的值是所有
重复的值条目。例如，可以指定多个值，而 ， 对于同一索引 ，这将导致 1-D
uncoalesced Tensor：341
>>> 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)
通常，method 的输出是一个
sparse 张量具有以下属性：
注意
在大多数情况下，您不必关心 稀疏张量是否合并，因为大多数操作都可以 以相同方式给出稀疏合并或未合并张量。
但是，某些操作可以更有效地实现 未合并的张量，以及一些关于合并的张量。
例如，稀疏 COO 张量的添加是通过 简单地连接 indices 和 values 张量：
>>> 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)
如果您重复执行可能产生重复的操作
条目（例如，），您应该偶尔
合并稀疏张量以防止它们变得太大。
另一方面，索引的字典顺序可以是 有利于实现涉及许多元素的算法 选择操作，例如切片或矩阵产品。
使用稀疏 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 张量是一个实例，为了区别于使用
其他一些布局，可以使用 or 属性：torch.Tensor.layout
>>> isinstance(s, torch.Tensor)
True
>>> s.is_sparse
True
>>> s.layout == torch.sparse_coo
True
>>> s.sparse_dim(), s.dense_dim()
(2, 1)
如果 是稀疏 COO 张量，则其 COO 格式数据可以是
使用 方法 和 获取。s
注意
目前，只有当张量 instance 被合并：
>>> 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 张量会得到一个不是 coalesced：
>>> s.is_coalesced()
False
>>> s2 = s.coalesce()
>>> s2.indices()
tensor([[0, 1, 1],
[2, 0, 2]])
当使用未合并的稀疏 COO 张量时，必须考虑到
一个帐户 未合并数据的加法性质：的值
相同的指数是 Evaluation 给出 的值
相应的 Tensor 元素。例如，标量
稀疏未合并张量上的乘法可以通过以下方式实现
将所有未合并的值乘以标量 because 成立。但是，任何非线性运算
例如，一个平方根，不能通过将操作应用于
uncoalesced data （未合并的数据），因为
持有。c *
(a + b) == c * a + c * bsqrt(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 中，不能指定稀疏张量的 fill 值
显式 ，通常假定为零。然而，存在
可能以不同方式解释 fill 值的操作。为
实例中，使用
假设 Fill 值为负无穷大。
稀疏压缩张量¶
Sparse Compressed Tensors 表示一类稀疏张量，其中 具有压缩某个维度的索引的共同特征 使用对线性代数启用某些优化的编码 稀疏压缩张量的内核。此编码基于 PyTorch 稀疏压缩的压缩稀疏行 （CSR） 格式 Tensor 在稀疏 Tensor Batch 的支持下进行扩展，从而允许 多维张量值，并将稀疏张量值存储在 密集块。
注意
我们使用 （B + M + K） 维张量来表示 N 维
稀疏压缩混合张量，其中 B、M 和 K 是数字
分别是 batch、sparse 和 dense 维度，这样 就可以成立。的稀疏维度数
稀疏压缩张量始终为 2 。B + M + K == NM == 2
注意
我们说 indices 张量使用 CSR
encoding （如果满足以下不变量）：compressed_indices
compressed_indices是连续的跨步 32 位或 64 位 整数张量compressed_indicesshape 是 压缩维度数（例如行或列）(*batchsize, compressed_dim_size + 1)compressed_dim_sizecompressed_indices[..., 0] == 0其中 degram batch 指标...compressed_indices[..., compressed_dim_size] == nse其中 是指定元素的数量nse0 <= compressed_indices[..., i] - compressed_indices[..., i - 1] <= plain_dim_size为 其中 是普通维度的数量 （与压缩维度正交，例如列或行）。i=1, ..., compressed_dim_sizeplain_dim_size
为了确保构造的稀疏张量具有一致的索引，
values 和 size 时，可以为每个张量启用不变检查
通过 keyword argument 创建
全局使用 Context Manager 实例。默认情况下，稀疏张量不变量
检查被禁用。check_invariants=True
注意
稀疏压缩布局到 N 维的泛化
张量可能会导致对指定
元素。当稀疏压缩张量包含批量维度时
指定元素的数量将对应于此类元素的数量
元素。当稀疏压缩张量具有密集维度时
考虑的元素现在是 K 维数组。也适用于块
稀疏压缩布局 2-D 块被视为元素
被指定。以 3 维块稀疏为例
Tensor 的 Tensor 中，具有一个 length 的 batch 维度和一个块
的形状。如果此张量具有指定的元素，则
事实上，我们为每个批次指定了区块。这个张量将
有 与 形状 。这种对
指定元素的数量来自所有稀疏压缩布局
从 2 维矩阵的压缩中推导出来。批
维度被视为稀疏矩阵、密集维度的堆叠
将元素的含义从简单的标量值更改为
数组。bp, qnnvalues(b, n, p, q)
稀疏 CSR 张量¶
与 COO 格式相比，CSR 格式的主要优势更好 使用存储和更快的计算操作，例如 Sparse 使用 MKL 和 MAGMA 后端的矩阵向量乘法。
在最简单的情况下，一个 （0 + 2 + 0） 维稀疏 CSR 张量
由三个 1-D 张量组成： ， 和 ：crow_indicescol_indicesvalues
张量由压缩的行组成 指标。这是一个大小为 （ rows 加 1）。的最后一个元素是数字 的指定元素 .此张量在给定行的位置对索引进行编码 开始。张量中的每个连续数字减去 number 表示给定行中的元素数。
crow_indicesnrows + 1crow_indicesnsevaluescol_indices张量包含每个 元素。这是一个大小为 的 1-D 张量。
col_indicesnse张量包含 CSR 张量的值 元素。这是一个大小为 的 1-D 张量。
valuesnse
注意
index tensors 和 应该具有
元素类型 （default） 或 .如果要使用启用 MKL 的矩阵运算，
用。这是由于
pytorch 与 MKL LP64 一起使用，它使用 32 位整数索引。crow_indicescol_indicestorch.int64torch.int32torch.int32
在一般情况下， （B + 2 + K） 维稀疏 CSR 张量
由两个 （B + 1） 维索引张量和 和 和 组成，以及 （1 + K） 维张量，例如
那crow_indicescol_indicesvalues
crow_indices.shape == (*batchsize, nrows + 1)
col_indices.shape == (*batchsize, nse)
values.shape == (nse, *densesize)
而稀疏 CSR 张量的形状是 where 和 。(*batchsize, nrows,
ncols, *densesize)len(batchsize) == Blen(densesize) == K
注意
稀疏 CSR 张量的批次是相关的：的 所有 batch 中指定的元素必须相同。这在某种程度上 人工约束允许有效存储 不同的 CSR 批次。
注意
可以使用 and 方法获取稀疏和密集维度的数量。可以从张量计算批次维度
形状：。batchsize = tensor.shape[:-tensor.sparse_dim() -
tensor.dense_dim()]
注意
稀疏 CSR 张量的内存消耗至少为 bytes （加上一个常量
存储其他张量数据的开销）。(nrows * 8 + (8 + <size of element type in bytes> *
prod(densesize)) * nse) * prod(batchsize)
使用稀疏 COO 格式的注释的相同示例数据
简介，一个 10 000 的内存消耗
x 10 000 张量，具有 100 000 个非零 32 位浮点数
在使用 CSR 张量布局时至少为 bytes。注意 1.6 和 310 折叠
与使用 COO 相比，使用 CSR 存储格式可节省成本，并且
stribed 格式。(10000 * 8 + (8 + 4 * 1) * 100 000) * 1 = 1 280 000
CSR 张量的构造¶
稀疏 CSR 张量可以通过该函数直接构造。用户必须提供该行
和 column indices 和 values 张量，其中 row indices
必须使用 CSR 压缩编码指定。该参数是可选的，如果不存在，将从 和 中推导出来。sizecrow_indicescol_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)
注意
计算 deded 中稀疏维度的值
从 的大小和 中的最大索引值。如果列数需要大于
在推导中，则参数必须是
显式指定。sizecrow_indicescol_indicessizesize
从
条纹或稀疏 COO 张量是使用方法。（跨） 中的任何零
tensor 将被解释为稀疏 Tensor 中的缺失值：
>>> 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 操作¶
可以使用该方法执行稀疏矩阵向量乘法。这是目前唯一的数学运算
在 CSR 张量上受支持。tensor.matmul()
>>> vec = torch.randn(4, 1, dtype=torch.float64)
>>> sp.matmul(vec)
tensor([[0.9078],
[1.3180],
[0.0000]], dtype=torch.float64)
稀疏 CSC 张量¶
稀疏 CSC（压缩稀疏列）张量格式实现了 CSC 格式，用于存储 2 维张量，扩展名为 支持稀疏 CSC 张量和值的批处理 多维张量。
注意
稀疏 CSC 张量本质上是稀疏 CSR 的转置 tensor 时，当转置是关于交换稀疏 尺寸。
与稀疏 CSR 张量类似，稀疏 CSC
Tensor 由三个张量组成： ， 和 ：ccol_indicesrow_indicesvalues
张量由压缩列 指标。这是形状为 的 （B + 1）-D 张量。 最后一个元素是指定的 元素。此张量根据给定列的开始位置对索引进行编码。每 张量中的连续数字减去它之前的数字 表示给定列中的元素数。
ccol_indices(*batchsize, ncols + 1)nsevaluesrow_indices张量包含每个 元素。这是形状为 的 （B + 1）-D 张量。
row_indices(*batchsize, nse)张量包含 CSC 张量的值 元素。这是形状为 的 （1 + K）-D 张量。
values(nse, *densesize)
CSC 张量的构造¶
使用该函数可以直接构造稀疏 CSC 张量。用户必须提供该行
和 column indices 和 values 张量，其中 column indices
必须使用 CSR 压缩编码指定。该参数是可选的，如果不存在，将从 and 张量中推导出来。sizerow_indicesccol_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 张量构造函数具有压缩的 column indices 参数。
（0 + 2 + 0） 维稀疏 CSC 张量可以由
任何 Two-dimensional Tensor using 方法。（跨步） 张量中的任何零都将被解释为
稀疏张量中的缺失值：
>>> 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 （Block compressed Sparse Row） 张量格式实现了 BSR 格式，用于存储二维张量，扩展名为 支持稀疏 BSR 张量的批处理，并且值是 多维张量。
稀疏 BSR 张量由三个张量组成：、 和 ：crow_indicescol_indicesvalues
张量由压缩的行组成 指标。这是形状为 的 （B + 1）-D 张量。最后一个元素是指定块的数量 。此张量在给定列块的位置对索引进行编码 开始。张量中的每个连续数字减去 number 表示给定行中的块数。
crow_indices(*batchsize, nrowblocks + 1)nsevaluescol_indices张量包含每个 元素。这是形状为 的 （B + 1）-D 张量。
col_indices(*batchsize, nse)张量包含稀疏 BSR 张量的值 元素收集到二维块中。这是一个 （1 + 2 + 形状为 . 的 K）-D 张量
values(nse, nrowblocks, ncolblocks, *densesize)
BSR 张量的构造¶
使用该函数可以直接构造稀疏 BSR 张量。用户必须提供该行
和 column block indices 和 values 张量，其中 row 块索引
必须使用 CSR 压缩编码指定。
该参数是可选的，如果不存在，将从 and 张量中推导出来。sizecrow_indicescol_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 张量可以由
任何二维张量使用方法也需要指定 values 块大小：
>>> 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 （Block compressed Sparse Column） 张量格式实现了 BSC 格式，用于存储二维张量，扩展名为 支持稀疏 BSC 张量的批处理，并且值是 多维张量。
稀疏 BSC 张量由三个张量组成：、 和 ：ccol_indicesrow_indicesvalues
张量由压缩列 指标。这是形状为 的 （B + 1）-D 张量。最后一个元素是指定块的数量 。此张量在给定 row 块的位置对索引进行编码 开始。张量中的每个连续数字减去 number 表示给定列中的块数。
ccol_indices(*batchsize, ncolblocks + 1)nsevaluesrow_indices张量包含每个 元素。这是形状为 的 （B + 1）-D 张量。
row_indices(*batchsize, nse)该张量包含稀疏 BSC 张量的值 元素收集到二维块中。这是一个 （1 + 2 + 形状为 . 的 K）-D 张量
values(nse, nrowblocks, ncolblocks, *densesize)
BSC 张量的构造¶
使用该函数可以直接构建稀疏 BSC 张量。用户必须提供该行
和 column block indices 和 values 张量，其中 column block indices
必须使用 CSR 压缩编码指定。
该参数是可选的，如果不存在，将从 and 张量中推导出来。sizeccol_indicesrow_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 张量 — 在概念上非常相似，因为它们的 indices 数据是分开的 分为两部分：使用 CSR 的所谓压缩索引 编码，以及与 压缩索引。这允许这些张量上的各种工具执行以下操作 共享由 Tensor 参数化的相同实现 布局。
稀疏压缩张量的构造¶
稀疏 CSR、CSC、BSR 和 CSC 张量可以使用具有相同
接口，如上面讨论的构造函数 、 、 和 、
，但有一个额外的 required 参数。这
以下示例说明了构建 CSR 和 CSC 的方法
张量使用相同的输入数据，方法是指定相应的
layout 参数添加到函数中：layout
>>> 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)
支持的操作¶
线性代数运算¶
下表总结了 上支持的线性代数运算
操作数布局可能不同的稀疏矩阵。这里表示具有给定布局的张量。同样，表示矩阵（二维 PyTorch 张量），表示向量（一维 PyTorch 张量）。此外，表示
标量（浮点或 0-D PyTorch 张量）是按元素计算的
multiplication，并且是矩阵乘法。T[layout]M[layout]V[layout]f*@
PyTorch 操作 |
稀疏的毕业生？ |
布局签名 |
|---|---|---|
不 |
|
|
不 |
|
|
不 |
|
|
不 |
|
|
不 |
|
|
不 |
|
|
不 |
|
|
不 |
|
|
不 |
|
|
是的 |
|
|
不 |
|
|
不 |
|
|
不 |
|
|
不 |
|
|
不 |
|
|
不 |
|
|
是的 |
|
|
不 |
|
|
不 |
|
|
不 |
|
|
是的 |
|
|
是的 |
|
其中 “Sparse grad？” 列表示 PyTorch 操作是否支持
相对于稀疏矩阵参数向后。所有 PyTorch 操作、
except ，支持相对于 stribed 向后
matrix 参数。
注意
目前，PyTorch 不支持使用
布局签名 。然而
应用程序仍然可以使用 matrix relation 来计算此函数。M[strided] @ M[sparse_coo]D @
S == (S.t() @ D.t()).t()
张量方法和稀疏¶
以下 Tensor 方法与稀疏 Tensor 相关：
如果 Tensor 使用稀疏 COO 存储布局，否则。 |
|
如果 Tensor 使用稀疏 CSR 存储布局，否则。 |
|
返回 sparse tensor 中的密集维度数。 |
|
返回稀疏张量中的稀疏维度数。 |
|
返回一个新的稀疏张量，其中包含由 sparse 张量的索引过滤的跨步张量中的值。 |
|
返回张量的稀疏副本。 |
|
将张量转换为坐标格式。 |
|
将张量转换为压缩的行存储格式 （CSR）。 |
|
将张量转换为压缩列存储 （CSC） 格式。 |
|
将张量转换为给定块大小的块稀疏行 （BSR） 存储格式。 |
|
将张量转换为给定区块大小的区块稀疏列 （BSC） 存储格式。 |
|
创建 if 不是 stribed 张量的 stribed 副本，否则返回 。 |
|
返回稀疏 COO 张量的 values tensor。 |
以下 Tensor 方法特定于稀疏 COO 张量：
返回 if 是未合并张量的合并副本。 |
|
将稀疏张量的大小调整为所需的大小以及稀疏和密集维度的数量。 |
|
从稀疏张量中删除所有指定的元素，并调整为所需的大小以及稀疏和密集维度的数量。 |
|
如果是合并的稀疏 COO 张量，则返回，否则返回。 |
|
返回稀疏 COO 张量的 indices 张量。 |
当 是 layout 的稀疏 CSR 张量时，返回包含张量的压缩行索引的张量。 |
|
当 是 layout 的稀疏 CSR 张量时，返回包含张量列索引的张量。 |
以下 Tensor 方法支持稀疏 COO 张量：
特定于稀疏张量的 Torch 函数¶
以 COO（rdinate） 格式构造一个稀疏张量，并在给定的 . |
|
在 CSR（压缩稀疏行）中构造一个稀疏张量，并在给定的 和 处使用指定的值。 |
|
在 CSC（压缩稀疏列）中构造一个稀疏张量，并在给定的 和 处使用指定的值。 |
|
在 BSR（块压缩稀疏行）中构造一个稀疏张量，其中包含给定 和 处的指定二维块。 |
|
在 BSC（块压缩稀疏列）中构造一个稀疏张量，并在给定的 和 处使用指定的二维块。 |
|
以压缩稀疏格式（CSR、CSC、BSR 或 BSC）构造一个稀疏张量，并在给定的 和 处具有指定的值。 |
|
返回给定稀疏张量的每一行的总和。 |
|
对密集矩阵执行矩阵乘法，并在稀疏模式 指定的位置执行 。 |
|
执行稀疏矩阵的矩阵乘法 |
|
Matrix 将稀疏张量与密集张量相乘，然后将稀疏张量添加到结果中。 |
|
执行稀疏 COO 矩阵和跨步矩阵的矩阵乘法。 |
|
执行稀疏矩阵与密集矩阵 的矩阵乘法。 |
|
应用 softmax 函数。 |
|
计算具有唯一解的线性方程的平方组的解。 |
|
应用 softmax 函数，后跟对数。 |
|
通过沿输出的指定对角线放置行中的值来创建稀疏 2D 张量 |
其他功能¶
cat()
dstack()
empty()
empty_like()
hstack()
index_select()
is_complex()
is_floating_point()
is_nonzero()
is_tensor()
lobpcg()
mm()
pca_lowrank()
select()
stack()
svd_lowrank()
unsqueeze()
vstack()
zeros()
zeros_like()is_same_size()is_signed()native_norm()
要管理稀疏张量不变量的检查，请参阅：
一种控制检查稀疏张量不变量的工具。 |
Decorate 函数，用于扩展稀疏张量的 gradcheck。 |
零保留一元函数¶
我们的目标是支持所有 '零保留一元函数'：一个参数的函数，将 0 映射到 0。
如果您发现我们缺少一个保持零的一元函数 ，我们鼓励您为功能请求打开 issue。 与往常一样，请在打开期刊之前先尝试搜索功能。
目前支持稀疏 COO/CSR/CSC/BSR/CSR 张量输入的算子。