From fd765f61d7b8b46b5b2dcf848e90c72b689df38b Mon Sep 17 00:00:00 2001 From: zhwesky2010 <1183042833@qq.com> Date: Thu, 17 Aug 2023 09:36:49 +0800 Subject: [PATCH] add some Tensor API en doc (#55958) --- paddle/fluid/pybind/eager_method.cc | 301 ++++++++++++++++++++++++++-- paddle/phi/core/sparse_coo_tensor.h | 8 +- paddle/phi/core/sparse_csr_tensor.h | 12 +- third_party/flashattn | 2 +- 4 files changed, 300 insertions(+), 23 deletions(-) diff --git a/paddle/fluid/pybind/eager_method.cc b/paddle/fluid/pybind/eager_method.cc index e78ad37962b..1800a100a52 100644 --- a/paddle/fluid/pybind/eager_method.cc +++ b/paddle/fluid/pybind/eager_method.cc @@ -1968,6 +1968,32 @@ static PyObject* tensor_method_get_map_tensor(TensorObject* self, EAGER_CATCH_AND_THROW_RETURN_NULL } +PyDoc_STRVAR(tensor_method_nnz__doc__, + R"DOC(nnz($self, /) +-- + +Note: + **This API is only available for SparseCooTensor or SparseCsrTensor.** + +Returns the total number of non zero elements in input SparseCooTensor/SparseCsrTensor. + +Returns: + int + +Examples: + .. code-block:: python + + import paddle + + indices = [[0, 1, 2], [1, 2, 0]] + values = [1.0, 2.0, 3.0] + dense_shape = [3, 3] + coo = paddle.sparse.sparse_coo_tensor(indices, values, dense_shape) + coo.nnz() + # 3 + +)DOC"); + static PyObject* tensor_method_get_non_zero_nums(TensorObject* self, PyObject* args, PyObject* kwargs) { @@ -1989,6 +2015,34 @@ static PyObject* tensor_method_get_non_zero_nums(TensorObject* self, EAGER_CATCH_AND_THROW_RETURN_NULL } +PyDoc_STRVAR(tensor_method_indices__doc__, + R"DOC(indices($self, /) +-- + +Note: + **This API is only available for SparseCooTensor.** + +Returns the indices of non zero elements in input SparseCooTensor. + +Returns: + DenseTesnor + +Examples: + .. code-block:: python + + import paddle + + indices = [[0, 1, 2], [1, 2, 0]] + values = [1.0, 2.0, 3.0] + dense_shape = [3, 3] + coo = paddle.sparse.sparse_coo_tensor(indices, values, dense_shape) + coo.indices() + # Tensor(shape=[2, 3], dtype=int64, place=Place(gpu:0), stop_gradient=True, + # [[0, 1, 2], + # [1, 2, 0]]) + +)DOC"); + static PyObject* tensor_method_get_non_zero_indices(TensorObject* self, PyObject* args, PyObject* kwargs) { @@ -2004,6 +2058,33 @@ static PyObject* tensor_method_get_non_zero_indices(TensorObject* self, EAGER_CATCH_AND_THROW_RETURN_NULL } +PyDoc_STRVAR(tensor_method_values__doc__, + R"DOC(values($self, /) +-- + +Note: + **This API is only available for SparseCooTensor or SparseCsrTensor.** + +Returns the values of non zero elements in input SparseCooTensor. + +Returns: + DenseTesnor + +Examples: + .. code-block:: python + + import paddle + + indices = [[0, 1, 2], [1, 2, 0]] + values = [1.0, 2.0, 3.0] + dense_shape = [3, 3] + coo = paddle.sparse.sparse_coo_tensor(indices, values, dense_shape) + coo.values() + # Tensor(shape=[3], dtype=float32, place=Place(gpu:0), stop_gradient=True, + # [1., 2., 3.]) + +)DOC"); + static PyObject* tensor_method_get_non_zero_elements(TensorObject* self, PyObject* args, PyObject* kwargs) { @@ -2029,6 +2110,34 @@ static PyObject* tensor_method_get_non_zero_elements(TensorObject* self, EAGER_CATCH_AND_THROW_RETURN_NULL } +PyDoc_STRVAR(tensor_method_crows__doc__, + R"DOC(crows($self, /) +-- + +Note: + **This API is only available for SparseCsrTensor.** + +Returns the compressed row index of non zero elements in input SparseCsrTensor. + +Returns: + DenseTesnor + +Examples: + .. code-block:: python + + import paddle + + crows = [0, 2, 3, 5] + cols = [1, 3, 2, 0, 1] + values = [1, 2, 3, 4, 5] + dense_shape = [3, 4] + csr = paddle.sparse.sparse_csr_tensor(crows, cols, values, dense_shape) + csr.crows() + # Tensor(shape=[4], dtype=int64, place=Place(gpu:0), stop_gradient=True, + # [0, 2, 3, 5]) + +)DOC"); + static PyObject* tensor_method_get_non_zero_crows(TensorObject* self, PyObject* args, PyObject* kwargs) { @@ -2044,6 +2153,34 @@ static PyObject* tensor_method_get_non_zero_crows(TensorObject* self, EAGER_CATCH_AND_THROW_RETURN_NULL } +PyDoc_STRVAR(tensor_method_cols__doc__, + R"DOC(cols($self, /) +-- + +Note: + **This API is only available for SparseCsrTensor.** + +Returns the column index of non zero elements in input SparseCsrTensor. + +Returns: + DenseTesnor + +Examples: + .. code-block:: python + + import paddle + + crows = [0, 2, 3, 5] + cols = [1, 3, 2, 0, 1] + values = [1, 2, 3, 4, 5] + dense_shape = [3, 4] + csr = paddle.sparse.sparse_csr_tensor(crows, cols, values, dense_shape) + csr.cols() + # Tensor(shape=[5], dtype=int64, place=Place(gpu:0), stop_gradient=True, + # [1, 3, 2, 0, 1]) + +)DOC"); + static PyObject* tensor_method_get_non_zero_cols(TensorObject* self, PyObject* args, PyObject* kwargs) { @@ -2115,6 +2252,31 @@ static PyObject* tensor_method_is_dist(TensorObject* self, EAGER_CATCH_AND_THROW_RETURN_NULL } +PyDoc_STRVAR(tensor_is_sparse__doc__, + R"DOC(is_sparse($self, /) +-- + +Returns whether the input Tensor is SparseCooTensor or SparseCsrTensor. + +When input is SparseCooTensor/SparseCsrTensor, will return True. When input is DenseTensor, will return False. + +Returns: + bool + +Examples: + .. code-block:: python + + import paddle + + indices = [[0, 1, 2], [1, 2, 0]] + values = [1.0, 2.0, 3.0] + dense_shape = [3, 3] + coo = paddle.sparse.sparse_coo_tensor(indices, values, dense_shape) + coo.is_sparse() + # True + +)DOC"); + static PyObject* tensor_method_is_sparse(TensorObject* self, PyObject* args, PyObject* kwargs) { @@ -2127,6 +2289,31 @@ static PyObject* tensor_method_is_sparse(TensorObject* self, EAGER_CATCH_AND_THROW_RETURN_NULL } +PyDoc_STRVAR(tensor_is_sparse_coo__doc__, + R"DOC(is_sparse_coo($self, /) +-- + +Returns whether the input Tensor is SparseCooTensor. + +When input is SparseCooTensor, will return True. When input is DenseTensor/SparseCsrTensor, will return False. + +Returns: + bool + +Examples: + .. code-block:: python + + import paddle + + indices = [[0, 1, 2], [1, 2, 0]] + values = [1.0, 2.0, 3.0] + dense_shape = [3, 3] + coo = paddle.sparse.sparse_coo_tensor(indices, values, dense_shape) + coo.is_sparse_coo() + # True + +)DOC"); + static PyObject* tensor_method_is_sparse_coo(TensorObject* self, PyObject* args, PyObject* kwargs) { @@ -2138,6 +2325,32 @@ static PyObject* tensor_method_is_sparse_coo(TensorObject* self, EAGER_CATCH_AND_THROW_RETURN_NULL } +PyDoc_STRVAR(tensor_is_sparse_csr__doc__, + R"DOC(is_sparse_csr($self, /) +-- + +Returns whether the input Tensor is SparseCsrTensor. + +When input is SparseCsrTensor, will return True. When input is DenseTensor/SparseCooTensor, will return False. + +Returns: + bool + +Examples: + .. code-block:: python + + import paddle + + crows = [0, 2, 3, 5] + cols = [1, 3, 2, 0, 1] + values = [1, 2, 3, 4, 5] + dense_shape = [3, 4] + csr = paddle.sparse.sparse_csr_tensor(crows, cols, values, dense_shape) + csr.is_sparse_csr() + # True + +)DOC"); + static PyObject* tensor_method_is_sparse_csr(TensorObject* self, PyObject* args, PyObject* kwargs) { @@ -2149,6 +2362,37 @@ static PyObject* tensor_method_is_sparse_csr(TensorObject* self, EAGER_CATCH_AND_THROW_RETURN_NULL } +PyDoc_STRVAR(tensor_to_sparse_csr__doc__, + R"DOC(to_sparse_csr($self, /) +-- + +Note: + **This API is only available for DenseTensor or SparseCooTensor.** + +Convert input Tensor to SparseCsrTensor. + +When input is SparseCooTensor, will convert `COO` to `CSR` . When input is DenseTensor, will convert `Dense` to `CSR` . + +Returns: + SparseCsrTensor + +Examples: + .. code-block:: python + + import paddle + + indices = [[0, 1, 2], [1, 2, 0]] + values = [1.0, 2.0, 3.0] + dense_shape = [3, 3] + coo = paddle.sparse.sparse_coo_tensor(indices, values, dense_shape) + coo.to_sparse_csr() + # Tensor(shape=[3, 3], dtype=paddle.float32, place=Place(gpu:0), stop_gradient=True, + # crows=[0, 1, 2, 3], + # cols=[1, 2, 0], + # values=[1., 2., 3.]) + +)DOC"); + static PyObject* tensor_method_to_sparse_csr(TensorObject* self, PyObject* args, PyObject* kwargs) { @@ -2164,6 +2408,38 @@ static PyObject* tensor_method_to_sparse_csr(TensorObject* self, EAGER_CATCH_AND_THROW_RETURN_NULL } +PyDoc_STRVAR(tensor_is_same_shape__doc__, + R"DOC(is_same_shape($self, y, /) +-- + +Return the results of shape comparison between two Tensors, check whether x.shape equal to y.shape. +Any two type Tensor among DenseTensor/SparseCooTensor/SparseCsrTensor are supported. + +Args: + x (Tensor): The input tensor. It can be DenseTensor/SparseCooTensor/SparseCsrTensor. + y (Tensor): The input tensor. It can be DenseTensor/SparseCooTensor/SparseCsrTensor. + +Returns: + bool: True for same shape and False for different shape. + +Examples: + + .. code-block:: python + + import paddle + + x = paddle.rand([2, 3, 8]) + y = paddle.rand([2, 3, 8]) + y = y.to_sparse_csr() + z = paddle.rand([2, 5]) + + x.is_same_shape(y) + # True + x.is_same_shape(z) + # False + +)DOC"); + static PyObject* tensor_method_is_same_shape(TensorObject* self, PyObject* args, PyObject* kwargs) { @@ -2227,9 +2503,10 @@ PyDoc_STRVAR(tensor_method__bump_inplace_version__doc__, // NOLINT R"DOC(_bump_inplace_version($self, /) -- -**Notes**: +Note: **This API is ONLY available in Dygraph mode.** **This is a very low level API. Users should not use it directly. ** + Bump the version whenever the Tensor is modified through an inplace operation. )DOC"); static PyObject* tensor__bump_inplace_version(TensorObject* self, @@ -2752,48 +3029,48 @@ PyMethodDef variable_methods[] = { // NOLINT {"nnz", (PyCFunction)(void (*)())tensor_method_get_non_zero_nums, METH_VARARGS | METH_KEYWORDS, - nullptr}, + tensor_method_nnz__doc__}, {"indices", (PyCFunction)(void (*)())tensor_method_get_non_zero_indices, METH_VARARGS | METH_KEYWORDS, - nullptr}, + tensor_method_indices__doc__}, {"values", (PyCFunction)(void (*)())tensor_method_get_non_zero_elements, METH_VARARGS | METH_KEYWORDS, - nullptr}, + tensor_method_values__doc__}, {"crows", (PyCFunction)(void (*)())tensor_method_get_non_zero_crows, METH_VARARGS | METH_KEYWORDS, - nullptr}, + tensor_method_crows__doc__}, {"cols", (PyCFunction)(void (*)())tensor_method_get_non_zero_cols, METH_VARARGS | METH_KEYWORDS, - nullptr}, + tensor_method_cols__doc__}, {"is_sparse", (PyCFunction)(void (*)())tensor_method_is_sparse, METH_VARARGS | METH_KEYWORDS, - nullptr}, + tensor_is_sparse__doc__}, {"is_sparse_coo", (PyCFunction)(void (*)())tensor_method_is_sparse_coo, METH_VARARGS | METH_KEYWORDS, - nullptr}, + tensor_is_sparse_coo__doc__}, {"is_sparse_csr", (PyCFunction)(void (*)())tensor_method_is_sparse_csr, METH_VARARGS | METH_KEYWORDS, - nullptr}, + tensor_is_sparse_csr__doc__}, {"is_same_shape", (PyCFunction)(void (*)())tensor_method_is_same_shape, METH_VARARGS | METH_KEYWORDS, - nullptr}, + tensor_is_same_shape__doc__}, {"to_sparse_csr", (PyCFunction)(void (*)())tensor_method_to_sparse_csr, METH_VARARGS | METH_KEYWORDS, - nullptr}, + tensor_to_sparse_csr__doc__}, + /***the method of sparse tensor****/ {"element_size", (PyCFunction)(void (*)())tensor_method_element_size, METH_VARARGS | METH_KEYWORDS, tensor_method_element_size__doc__}, - /***the method of sparse tensor****/ {"_inplace_version", (PyCFunction)(void (*)())tensor__inplace_version, METH_VARARGS | METH_KEYWORDS, diff --git a/paddle/phi/core/sparse_coo_tensor.h b/paddle/phi/core/sparse_coo_tensor.h index f0343585485..97db6cb8c26 100644 --- a/paddle/phi/core/sparse_coo_tensor.h +++ b/paddle/phi/core/sparse_coo_tensor.h @@ -63,15 +63,15 @@ class SparseCooTensor : public TensorBase, /// \brief Destroy the tensor object and release exclusive resources. virtual ~SparseCooTensor() = default; - /// \brief Returns the indices of non zero elemetns in original dense tensor. - /// \return The indices of non zero elemetns in original dense tensor. + /// \brief Returns the indices of non zero elements in original dense tensor. + /// \return The indices of non zero elements in original dense tensor. const DenseTensor& indices() const { return non_zero_indices_; } /// Note: This function will removed soon. It is recommended to use indices() const DenseTensor& non_zero_indices() const { return non_zero_indices_; } - /// \brief Returns the non zero elemetns in original dense tensor. - /// \return The non zero elemetns in original dense tensor. + /// \brief Returns the non zero elements in original dense tensor. + /// \return The non zero elements in original dense tensor. const DenseTensor& values() const { return non_zero_elements_; } /// Note: This function will removed soon. It is recommended to use values() diff --git a/paddle/phi/core/sparse_csr_tensor.h b/paddle/phi/core/sparse_csr_tensor.h index 38f330a7275..1901b824f56 100644 --- a/paddle/phi/core/sparse_csr_tensor.h +++ b/paddle/phi/core/sparse_csr_tensor.h @@ -70,25 +70,25 @@ class SparseCsrTensor : public TensorBase, /// \return The name of the class. static const char* name() { return "SparseCsrTensor"; } - /// \brief Returns the compressed row index of non zero elemetns in original + /// \brief Returns the compressed row index of non zero elements in original /// dense tensor. - /// \return The compressed row index of non zero elemetns in original dense + /// \return The compressed row index of non zero elements in original dense /// tensor. const DenseTensor& crows() const { return non_zero_crows_; } /// Note: This function will removed soon. It is recommended to use crows() const DenseTensor& non_zero_crows() const { return non_zero_crows_; } - /// \brief Returns the column index of non zero elemetns in original dense + /// \brief Returns the column index of non zero elements in original dense /// tensor. - /// \return The column index of non zero elemetns in original dense tensor. + /// \return The column index of non zero elements in original dense tensor. const DenseTensor& cols() const { return non_zero_cols_; } /// Note: This function will removed soon. It is recommended to use cols() const DenseTensor& non_zero_cols() const { return non_zero_cols_; } - /// \brief Returns the non zero elemetns in original dense tensor. - /// \return The non zero elemetns in original dense tensor. + /// \brief Returns the non zero elements in original dense tensor. + /// \return The non zero elements in original dense tensor. const DenseTensor& values() const { return non_zero_elements_; } /// Note: This function will removed soon. It is recommended to use indices() diff --git a/third_party/flashattn b/third_party/flashattn index b5bdb79d5e1..18106c1ba0c 160000 --- a/third_party/flashattn +++ b/third_party/flashattn @@ -1 +1 @@ -Subproject commit b5bdb79d5e1f2f88b1ef62e86899a14f82fa079a +Subproject commit 18106c1ba0ccee81b97ca947397c08a141815a47 -- GitLab