torch.sparse

警告

稀疏半结构化张量目前是试验性功能，可能还会更改。如发现问题或有反馈意见，请随时提交issue。

注意

半结构化稀疏张量的指定元素和元数据掩码共同存储在同一个扁平压缩张量中。这些元素和掩码依次连接起来，形成一个连续的内存块。

压缩张量 = [原始张量中的指定元素 | 元数据掩码]

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

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

• .values() 返回一个大小为 (r, c//2)、数据类型与密集矩阵相同的张量。

• .indices() 返回一个大小为 (r, c//2) 的张量。如果数据类型是 torch.float16 或 torch.bfloat16，则元素类型为 torch.int16；如果是 torch.int8，则元素类型为 torch.int32。

注意

值得注意的是，torch.float32仅支持1:2的稀疏模式，因此不会遵循上面提到的公式。

构造稀疏半结构化张量

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

请留意，由于半结构化稀疏性仅在NVIDIA GPU上受支持，因此我们只提供对CUDA张量的支持。

以下数据类型支持半结构化的稀疏性。请留意，每种数据类型都具有特定的形状约束和压缩因子。

要构建半结构化的稀疏张量，首先需要创建一个符合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(密集矩阵, 稀疏矩阵, 偏置项)

• 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 张量的内存消耗至少为 (ndim * 8 + <元素类型所占字节大小>) 乘以 nse 字节（加上存储其他张量数据的常数开销）。

步长张量的内存消耗至少为 product( ) * 。

例如，一个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倍的内存。

建筑

建造

施工

建设

构建

可以通过提供索引张量和值张量，以及稀疏张量的大小（如果无法从索引和值张量推断出来的话），来构造一个稀疏 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 张量扩展了稀疏 COO 张量，允许 values 张量为多维张量，从而使我们能够拥有：

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

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

假设我们想创建一个(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 - 值以 strided 张量的形式存储。

未融合的稀疏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。

>>> 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 张量是一个 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 格式的数据。

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

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

构建一个新的稀疏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。

注意

我们使用 (B + M + K) 维张量来表示一个 N 维稀疏压缩混合张量。其中 B、M 和 K 分别代表批处理维度、稀疏维度和密集维度的数量，并且满足B + M + K == N 的条件。对于稀疏压缩张量，其稀疏维度的数量始终为两个，即M == 2。

注意

如果一个索引张量 compressed_indices 使用了 CSR 编码，则以下不变量必须成立：

• compressed_indices 是一个连续的、带有 stride 的 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-D 块被视为被指定的元素。例如，有一个3维块稀疏张量，它有一个长度为b 的批量维度和一个形状为 p, q 的块形。如果该张量有n 个指定元素，则实际上每个批次中有n 块被指定。此张量将具有形状为(b, n, p, q) 的values。这种对指定元素数量的解释来自于所有稀疏压缩布局都源自一个2维矩阵的压缩。批量维度被视为稀疏矩阵的堆叠，密集维度则改变了元素的意义，从简单的标量值变为具有自身维度的数组。

稀疏CSR tensor

与COO格式相比，CSR格式的主要优点在于更有效地利用存储空间，并且在执行如稀疏矩阵向量乘法等计算操作时，使用MKL和MAGMA后端能显著提高速度。

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

• crow_indices 张量包含压缩后的行索引，其大小为 nrows + 1（即行数加 1）。张量的最后一个值是总的非零元素数量 nse。这个张量用于确定在给定行开始时，values 和 col_indices 中对应的索引位置。张量中每个连续数字与前一个数字之差表示该行中的元素数量。

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

• values 张量包含了 CSR 张量元素的值，其大小为 nse 的一维张量。

通常情况下，(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。

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

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

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

稀疏CSC tensor

稀疏 CSC（压缩稀疏列）张量格式实现了用于存储二维张量的 CSC 格式，并且扩展了对稀疏 CSC 张量批次的支持，以及对多维张量值的支持。

类似于稀疏CSR张量，一个稀疏CSC张量由三个部分组成：ccol_indices、row_indices 和 values:

• ccol_indices 张量包含压缩后的列索引，其形状为 (*batchsize, ncols + 1) 的 (B + 1)-D 张量。最后一个元素表示指定的非零元素数量 nse。此张量编码了在给定列开始时 values 和 row_indices 中的索引位置。张量中每个连续数字与前一个数字之差，表示给定列中的元素数量。

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

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

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

>>> 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)-D 张量。张量的最后一个元素表示指定块的数量（nse）。该张量编码了在给定列块开始的位置上 values 和 col_indices 中的索引位置。张量中每个连续数字与前一个数字之差表示给定行中的块数。

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

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

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

>>> 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 tensor

稀疏 BSC（块压缩稀疏列）张量格式实现了 BSC 格式，用于存储二维张量，并且扩展了对稀疏 BSC 张量批处理的支持，其中值是多维张量的块。

一个稀疏的BSC张量包含三个张量：分别是ccol_indices、row_indices和values。

• ccol_indices 张量包含压缩的列索引，其形状为 (*batchsize, ncolblocks + 1)。最后一个元素是已指定的非零元素数量 nse。此张量编码了在给定行块开始的位置上，在 values 和 row_indices 中的索引位置。张量中每个连续数字与前一个数字之差表示给定列中的非零元素数量。

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

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

>>> 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编码的压缩索引，另一部分是与压缩索引正交的普通索引。这使得这些张量上的各种工具可以共享由张量布局参数化的相同实现。

>>> 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.smm()之外，所有PyTorch操作都支持针对带步长矩阵参数的反向传播。

张量方法与稀疏性

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

以下张量方法专为稀疏 COO 张量设计：

以下方法专用于稀疏CSR张量和稀疏BSR张量:

以下方法专用于稀疏 CSC 张量和稀疏 BSC 张量:

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

`add()` `add_()` `mm()` `mul()` `mul_()` `mv()` `narrow_copy()` `neg()` `neg_()` `negative()` `negative_()` `numel()` `pow()` `sqrt()` `square()` `smm()` `sspaddmm()` `sub()` `sub_()` `t()` `t_()` `transpose()` `transpose_()` `zero_()` `get_device()` `index_select()` `isnan()` `log1p()` `log1p_()` `resize_as_()` `size()` `floor_divide()` `floor_divide_()` `rad2deg()` `rad2deg_()`

专为稀疏张量设计的Torch函数

其他功能

以下 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() 函数，请参见：

保零一元函数

我们的目标是支持所有“保零一元函数”，即把零映射为零的函数。

如果你发现缺少了你需要的保持零值不变的一元函数，请提出功能请求。如常，提交问题前请先使用搜索功能。

以下运算符目前支持稀疏 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()