torch.spares_coo_tensor

方法： 

torch.sparse_coo_tensor(indices, values, size=None, *, dtype=None, device=None, requires_grad=False, check_invariants=None, is_coalesced=None)

作用：

此方法的意思是创建一个Coordinate(COO) 格式的稀疏矩阵，返回值也就h是一个tensor

稀疏矩阵指矩阵中的大多数元素的值都为0，由于其中非常多的元素都是0，使用常规方法进行存储非常的浪费空间，所以采用另外的方法存储稀疏矩阵。

使用一个三元组来表示矩阵中的一个非0数，三元组分别表示元素（所在行，所在列，元素值），也就是上图中每一个竖的三元组就是表示了一个非零数，其余值都为0，这样就存储了一个稀疏矩阵

Parameters  参数

• indices (array_like) – Initial data for the tensor. Can be a list, tuple, NumPy ndarray, scalar, and other types. Will be cast to a torch.LongTensor internally. The indices are the coordinates of the non-zero values in the matrix, and thus should be two-dimensional where the first dimension is the number of tensor dimensions and the second dimension is the number of non-zero values.

• 此参数是指定非零元素所在的位置，也就是行和列，所以此参数应该是一个二维的数组，当然它可以是很多格式（ist, tuple, NumPy ndarray, scalar, and other types. ）第一维指定了所有非零数所在的行数，第二维指定了所有非零元素所在的列数。例如indices=[[1, 4, 6], [3, 6, 7]]表示我们稀疏矩阵中(1, 3),(4, 6), (6, 7)几个位置是非零的数所在的位置

• values (array_like) – Initial values for the tensor. Can be a list, tuple, NumPy ndarray, scalar, and other types.

• 此参数指定了非零元素的值，所以此矩阵长度应该和上面的indices一样长也可以是很多格式（list, tuple, NumPy ndarray, scalar, and other types.）。例如``values=[1, 4, 5]表示上面的三个位置非零数分别为1, 4, 5

• size (list, tuple, or torch.Size, optional) – Size of the sparse tensor. If not provided the size will be inferred as the minimum size big enough to hold all non-zero elements.

• 指定了稀疏矩阵的大小，例如size=[10, 10]表示矩阵大小为10 × 10 10\times 1010×10，此大小最小应该足以覆盖上面非零元素所在的位置，如果不给定此值，那么默认是生成足以覆盖所有非零值的最小矩阵大小。

• Keyword Arguments: 可选参数

• dtype(torch.dtype, optional) – the desired data type of returned tensor. Default: if None, infers data type from values.

• 指定返回tensor中数据的类型，如果不指定，那么采取values中数据的类型

• device(torch.device, optional) – the desired device of returned tensor. Default: if None, uses the current device for the default tensor type (see torch.set_default_device()). device will be the CPU for CPU tensor types and the current CUDA device for CUDA tensor types..

• 指定创建的tensor在cpu还是cuda上

• requires_grad(bool, optional) – If autograd should record operations on the returned tensor. Default: False.

• 指定创建的tensor需不需要梯度信息，默认为False

• check_invariants(bool,optional) – If sparse tensor invariants are checked. Default: as returned by torch.sparse.check_sparse_tensor_invariants.is_enabled(), initially False.

• `check_invariants`（布尔型，可选）：如果设置为True，则会检查稀疏张量的不变性。默认情况下，通过`torch.sparse.is_sparse`函数返回值判断，默认值为False。

• is_coalesced (bool, optional) – When``True``, the caller is responsible for providing tensor indices that correspond to a coalesced tensor. If the check_invariants flag is False, no error will be raised if the prerequisites are not met and this will lead to silently incorrect results. To force coalescion please use coalesce() on the resulting Tensor. Default: None: except for trivial cases (e.g. nnz < 2) the resulting Tensor has is_coalesced set to False`

• `is_coalesced`（布尔型，可选）：当设为True时，调用者负责提供对应于已合并稀疏张量的索引和值。如果未设置`check_invariants`或其值为False，在不满足前置条件时也不会报错。 若要强制合并，请使用`coalesce()`函数；只有在非特殊情况下（如nnz < 2），返回的Tensor属性`.is_coalesced()`才会是False。

 官方说明：

软件翻译：
构造一个在给定索引处具有指定值的COO(坐标)格式的稀疏张量。

当is_coalesced未指定或为None时，此函数返回一个未合并张量。

注:如果未指定设备参数，则给定值和索引张量的设备必须匹配。
然而，如果指定了参数，则输入张量将被转换为给定的设备，并反过来确定构造的稀疏张量的设备。

官方示例：torch.sparse_coo_tensor — PyTorch 2.2 documentation

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

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

>>> torch.sparse_coo_tensor(i, v, [2, 4],
...                         dtype=torch.float64,
...                         device=torch.device('cuda:0'))
tensor(indices=tensor([[0, 1, 1],
                       [2, 0, 2]]),
       values=tensor([3., 4., 5.]),
       device='cuda:0', size=(2, 4), nnz=3, dtype=torch.float64,
       layout=torch.sparse_coo)

# Create an empty sparse tensor with the following invariants:
#   1. sparse_dim + dense_dim = len(SparseTensor.shape)
#   2. SparseTensor._indices().shape = (sparse_dim, nnz)
#   3. SparseTensor._values().shape = (nnz, SparseTensor.shape[sparse_dim:])
#
# For instance, to create an empty sparse tensor with nnz = 0, dense_dim = 0 and
# sparse_dim = 1 (hence indices is a 2D tensor of shape = (1, 0))
>>> S = torch.sparse_coo_tensor(torch.empty([1, 0]), [], [1])
tensor(indices=tensor([], size=(1, 0)),
       values=tensor([], size=(0,)),
       size=(1,), nnz=0, layout=torch.sparse_coo)

# and to create an empty sparse tensor with nnz = 0, dense_dim = 1 and
# sparse_dim = 1
>>> S = torch.sparse_coo_tensor(torch.empty([1, 0]), torch.empty([0, 2]), [1, 2])
tensor(indices=tensor([], size=(1, 0)),
       values=tensor([], size=(0, 2)),
       size=(1, 2), nnz=0, layout=torch.sparse_coo)