mindspore.COOTensor

class mindspore.COOTensor(indices=None, values=None, shape=None, coo_tensor=None)

用来表示某一Tensor在给定索引上非零元素的集合，其中索引(indices)指示了每一个非零元素的位置。

对一个稠密Tensor dense 来说，它对应的COOTensor(indices, values, shape)，满足 dense[indices[i]] = values[i] 。

如果 indices 是[[0, 1], [1, 2]]， values 是[1, 2]， shape 是(3, 4)，那么它对应的稠密Tensor如下：

[[0, 1, 0, 0],
 [0, 0, 2, 0],
 [0, 0, 0, 0]]

COOTensor的算术运算包括：加（+）、减（-）、乘（*）、除（/）。详细的算术运算支持请参考 运算符。

警告

• 这是一个实验性API，后续可能修改或删除。

• 使用PyNative模式，需要添加"export MS_PYNATIVE_CONFIG_STATIC_SHAPE=1"。

• 目前COOTensor中相同索引的值不会进行合并。如果索引中包含界外值，则得出未定义结果。

参数：

• indices (Tensor) - shape为 \((N, ndims)\) 的二维整数Tensor，其中N和ndims分别表示稀疏Tensor中 values 的数量和COOTensor维度的数量。目前 ndims 只能为2。请确保indices的值在所给shape范围内。支持的数据类型为int16， int32和int64。默认值： None 。

• values (Tensor) - shape为 \((N)\) 的一维Tensor，用来给 indices 中的每个元素提供数值。默认值： None 。

• shape (tuple(int)) - shape为 \((ndims)\) 的整数元组，用来指定稀疏矩阵的稠密shape。默认值： None 。

• coo_tensor (COOTensor) - COOTensor对象，用来初始化新的COOTensor。默认值： None 。

返回：

COOTensor，由 indices 、 values 和 shape 组成。

样例：

>>> import mindspore as ms
>>> from mindspore import Tensor, COOTensor
>>> indices = Tensor([[0, 1], [1, 2]], dtype=ms.int32)
>>> values = Tensor([1, 2], dtype=ms.float32)
>>> shape = (3, 4)
>>> x = COOTensor(indices, values, shape)
>>> print(x.values)
[1. 2.]
>>> print(x.indices)
[[0 1]
 [1 2]]
>>> print(x.shape)
(3, 4)

abs()

对所有非零元素取绝对值，并返回新的COOTensor。

返回：

COOTensor。

支持平台：

Ascend GPU CPU

样例：

>>> import mindspore as ms
>>> from mindspore import Tensor, COOTensor
>>> indices = Tensor([[0, 1, 2], [1, 0, 2]], dtype=ms.int32)
>>> values = Tensor([1, -5, -4], dtype=ms.float32)
>>> shape = (3, 3)
>>> coo_tensor = COOTensor(indices.transpose(), values, shape)
>>> res = coo_tensor.abs()
>>> print(res.values)
[1. 5. 4.]

add(other: COOTensor, thresh: Tensor)

与另一个COOTensor相加，并返回新的COOTensor。

参数：

• other (COOTensor) - 另一个操作数，与当前操作数相加。

• thresh (Tensor) - 零维。用来决定COOTensor.add结果中的indice/value对是否出现的阈值。如果结果中value的数据类型为实数，则 thresh 的数据类型应该与它的数据类型一致。如果结果中value小于 thresh, 它将会被丢掉。

返回：

COOTensor，为两COOTensor相加后的结果。

异常：

• ValueError - 如果操作数(本COOTensor/other)的indices的维度不等于2。

• ValueError - 如果操作数(本COOTensor/other)的values的维度不等于1。

• ValueError - 如果操作数(本COOTensor/other)的shape的维度不等于1。

• ValueError - 如果thresh的维度不等于0。

• TypeError - 如果操作数(本COOTensor/other)的indices的数据类型不为int64。

• TypeError - 如果操作数(本COOTensor/other)的shape的数据类型不为int64。

• ValueError - 如果操作数(本COOTensor/other)的indices的长度不等于它的values的长度。

• TypeError - 如果操作数(本COOTensor/other)的values的数据类型不为(int8/int16/int32/int64/float32/float64/complex64/complex128)中的任何一个。

• TypeError - 如果thresh的数据类型不为(int8/int16/int32/int64/float32/float64)中的任何一个。

• TypeError - 如果操作数(本COOTensor)的indices数据类型不等于other的indices数据类型。

• TypeError - 如果操作数(本COOTensor)的values数据类型不等于other的values数据类型。

• TypeError - 如果操作数(本COOTensor)的shape数据类型不等于other的shape数据类型。

• TypeError - 如果操作数(本COOTensor/other)的values的数据类型与thresh数据类型不匹配。

支持平台：

GPU CPU

样例：

>>> from mindspore import Tensor, COOTensor
>>> from mindspore import dtype as mstype
>>> indics0 = Tensor([[0, 1], [1, 2]], dtype=mstype.int64)
>>> values0 = Tensor([1, 2], dtype=mstype.int32)
>>> shape0 = (3, 4)
>>> input0 = COOTensor(indics0, values0, shape0)
>>> indics1 = Tensor([[0, 0], [1, 1]], dtype=mstype.int64)
>>> values1 = Tensor([3, 4], dtype=mstype.int32)
>>> shape1 = (3, 4)
>>> input1 = COOTensor(indics1, values1, shape1)
>>> thres = Tensor(0, dtype=mstype.int32)
>>> out = input0.add(input1, thres)
>>> print(out)
COOTensor(shape=[3, 4], dtype=Int32, indices=Tensor(shape=[4, 2], dtype=Int64, value=
[[0 0]
 [0 1]
 [1 1]
 [1 2]]), values=Tensor(shape=[4], dtype=Int32, value=[3 1 4 2]))

astype(dtype: mstype)

返回指定数据类型的COOTensor。

参数：

• dtype (Union[mindspore.dtype, numpy.dtype, str]) - 指定数据类型。

返回：

COOTensor。

支持平台：

Ascend GPU CPU

样例：

>>> import mindspore as ms
>>> from mindspore import Tensor, COOTensor
>>> indices = Tensor([[0, 1], [1, 2]], dtype=ms.int32)
>>> values = Tensor([1, 2], dtype=ms.float32)
>>> shape = (3, 4)
>>> coo_tensor = COOTensor(indices, values, shape)
>>> print(coo_tensor.astype(ms.float64).dtype)
Float64

coalesce()

合并COOTensor中相同索引的值。

返回：

COOTensor。

支持平台：

GPU

样例：

>>> import mindspore as ms
>>> from mindspore import Tensor, COOTensor
>>> x_indices = Tensor([[0, 0, 1], [1, 1, 2]], dtype=ms.int64)
>>> x_values = Tensor([1, 5, 4], dtype=ms.float32)
>>> x_shape = (3, 3)
>>> coo_tensor = COOTensor(x_indices.transpose(), x_values, x_shape)
>>> res = coo_tensor.coalesce()
>>> print(res)
COOTensor(shape=[3, 3], dtype=Float32, indices=Tensor(shape=[2, 2], dtype=Int64,
    value=[[0 1] [1 2]]), values=Tensor(shape=[2], dtype=Float32, value=[6.00000000e+00 4.00000000e+00]))

property dtype

返回COOTensor数据类型（mindspore.dtype）。

样例：

>>> import mindspore as ms
>>> from mindspore import Tensor, COOTensor
>>> indices = Tensor([[0, 1], [1, 2]], dtype=ms.int32)
>>> values = Tensor([1, 2], dtype=ms.float32)
>>> shape = (3, 4)
>>> coo_tensor = COOTensor(indices, values, shape)
>>> print(coo_tensor.dtype)
Float32

property indices

返回COOTensor的索引值。

property itemsize

返回每个非零元素所占字节数。

样例：

>>> import mindspore as ms
>>> from mindspore import Tensor, COOTensor
>>> indices = Tensor([[0, 1], [1, 2]], dtype=ms.int32)
>>> values = Tensor([1, 2], dtype=ms.float64)
>>> shape = (3, 4)
>>> coo_tensor = COOTensor(indices, values, shape)
>>> print(coo_tensor.itemsize)
8

property ndim

返回稀疏矩阵的稠密维度。

样例：

>>> import mindspore as ms
>>> from mindspore import Tensor, COOTensor
>>> indices = Tensor([[0, 1], [1, 2]], dtype=ms.int32)
>>> values = Tensor([1, 2], dtype=ms.float32)
>>> coo_tensor = COOTensor(indices, values, (3, 4))
>>> print(coo_tensor.ndim)
2

property shape

返回稀疏矩阵的稠密shape。

property size

返回稀疏矩阵非零元素值数量。

样例：

>>> import mindspore as ms
>>> from mindspore import Tensor, COOTensor
>>> indices = Tensor([[0, 1, 2], [1, 0, 2]], dtype=ms.int32)
>>> values = Tensor([1, 5, 4], dtype=ms.float32)
>>> shape = (3, 3)
>>> coo_tensor = COOTensor(indices.transpose(), values, shape)
>>> print(coo_tensor.size)
3

to_csr()

将COOTensor转换为CSRTensor。

说明

如果运行后端是CPU，那么仅支持在安装了LLVM12.0.1的机器运行。

返回：

CSRTensor。

支持平台：

GPU CPU

样例：

>>> import mindspore as ms
>>> from mindspore import Tensor, COOTensor
>>> indices = Tensor([[0, 1], [1, 2]], dtype=ms.int32)
>>> values = Tensor([1, 2], dtype=ms.int32)
>>> shape = (3, 4)
>>> coo_tensor = COOTensor(indices, values, shape)
>>> print(coo_tensor.to_csr())
CSRTensor(shape=[3, 4], dtype=Int32, indptr=Tensor(shape=[4], dtype=Int32, value=[0 1 2 2]),
    indices=Tensor(shape=[2], dtype=Int32, value=[1 2]), values=Tensor(shape=[2], dtype=Int32, value=[1 2]))

to_dense()

将COOTensor转换为稠密Tensor。

返回：

Tensor。

支持平台：

GPU

样例：

>>> import mindspore as ms
>>> from mindspore import Tensor, COOTensor
>>> indices = Tensor([[0, 1, 2], [1, 0, 2]], dtype=ms.int32)
>>> values = Tensor([1, 5, 4], dtype=ms.float32)
>>> shape = (3, 3)
>>> coo_tensor = COOTensor(indices.transpose(), values, shape)
>>> print(coo_tensor.to_dense())
[[0. 1. 0.]
 [5. 0. 0.]
 [0. 0. 4.]]

to_tuple()

将COOTensor的索引，非零元素，以及shape信息作为tuple返回。

返回：

tuple(Tensor, Tensor, tuple(int))。

支持平台：

Ascend GPU CPU

样例：

>>> import mindspore as ms
>>> from mindspore import Tensor, COOTensor
>>> indices = Tensor([[0, 1], [1, 2]], dtype=ms.int32)
>>> values = Tensor([1, 2], dtype=ms.float32)
>>> shape = (3, 4)
>>> coo_tensor = COOTensor(indices, values, shape)
>>> print(coo_tensor.to_tuple())
(Tensor(shape=[2, 2], dtype=Int32, value=
[[0, 1],
 [1, 2]]), Tensor(shape=[2], dtype=Float32, value= [ 1.00000000e+00,  2.00000000e+00]), (3, 4))

property values

返回COOTensor的非零元素值。