From b48e1ac16a596c0736c6c3b018c68dd6f4f89551 Mon Sep 17 00:00:00 2001
From: Shaivi Agarwal <agarwal.shaivi1@gmail.com>
Date: Sun, 5 Jan 2025 15:31:42 +0530
Subject: [PATCH] Add tensors.rst and update index.rst to include Tensors
 documentation

---
 docs/source/index.rst              |  10 +++
 docs/source/python/api/tensors.rst | 113 +++++++++++++++++++++++++++++
 2 files changed, 123 insertions(+)
 create mode 100644 docs/source/python/api/tensors.rst

diff --git a/docs/source/index.rst b/docs/source/index.rst
index e6e82c13d7eff..431ad4e5f7ca8 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -115,6 +115,16 @@ Implementations
    Rust <https://docs.rs/crate/arrow/>
    status
 
+Tensors
+-------
+
+.. _toc.tensors:
+
+.. toctree::
+   :maxdepth: 2
+
+   <python/api/tensors.rst>
+
 Examples
 --------
 
diff --git a/docs/source/python/api/tensors.rst b/docs/source/python/api/tensors.rst
new file mode 100644
index 0000000000000..155e925413b0a
--- /dev/null
+++ b/docs/source/python/api/tensors.rst
@@ -0,0 +1,113 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements.  See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership.  The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License.  You may obtain a copy of the License at
+
+..   http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+.. software distributed under the License is distributed on an
+.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+.. KIND, either express or implied.  See the License for the
+.. specific language governing permissions and limitations
+.. under the License.
+
+.. currentmodule:: pyarrow
+
+.. _api.tensor:
+
+Tensors
+=======
+
+PyArrow supports both dense and sparse tensors. Dense tensors store all data values explicitly, while sparse tensors represent only the non-zero elements and their locations, making them efficient for storage and computation.
+
+Dense Tensors
+^^^^^^^^^^^^^
+
+.. autosummary::
+   :toctree: ../generated/
+
+   Tensor
+
+Sparse Tensors
+^^^^^^^^^^^^^
+
+PyArrow supports the following sparse tensor formats:
+
+.. autosummary::
+   :toctree: ../generated/
+
+   SparseCOOTensor
+   SparseCSRMatrix
+   SparseCSCMatrix
+   SparseCSFTensor
+
+"""SparseCOOTensor"""
+
+The ``SparseCOOTensor`` represents a sparse tensor in Coordinate (COO) format, where non-zero elements are stored as tuples of row and column indices.
+
+Example:
+.. code-block:: python
+
+   import pyarrow as pa
+
+   indices = pa.array([[0, 0], [1, 2]])
+   data = pa.array([1, 2])
+   shape = (2, 3)
+
+   tensor = pa.SparseCOOTensor(indices, data, shape)
+   print(tensor.to_dense())
+
+"""SparseCSRMatrix"""
+
+The ``SparseCSRMatrix`` represents a sparse matrix in Compressed Sparse Row (CSR) format. This format is useful for matrix-vector multiplication.
+
+Example:
+.. code-block:: python
+
+   import pyarrow as pa
+
+   data = pa.array([1, 2, 3])
+   indptr = pa.array([0, 2, 3])
+   indices = pa.array([0, 2, 1])
+   shape = (2, 3)
+
+   sparse_matrix = pa.SparseCSRMatrix.from_numpy(data, indptr, indices, shape)
+   print(sparse_matrix)
+
+"""SparseCSCMatrix"""
+
+The ``SparseCSCMatrix`` represents a sparse matrix in Compressed Sparse Column (CSC) format, where data is stored by columns.
+
+Example:
+.. code-block:: python
+
+   import pyarrow as pa
+
+   data = pa.array([1, 2, 3])
+   indptr = pa.array([0, 1, 3])
+   indices = pa.array([0, 1, 2])
+   shape = (3, 2)
+
+   sparse_matrix = pa.SparseCSCMatrix.from_numpy(data, indptr, indices, shape)
+   print(sparse_matrix)
+
+"""SparseCSFTensor"""
+
+The ``SparseCSFTensor`` represents a sparse tensor in Compressed Sparse Fiber (CSF) format, which is a generalization of the CSR format for higher dimensions.
+
+Example:
+.. code-block:: python
+
+   import pyarrow as pa
+
+   data = pa.array([1, 2, 3])
+   indptr = [pa.array([0, 1, 3]), pa.array([0, 2, 3])]
+   indices = [pa.array([0, 1]), pa.array([0, 1, 2])]
+   shape = (2, 3, 2)
+
+   sparse_tensor = pa.SparseCSFTensor.from_numpy(data, indptr, indices, shape)
+   print(sparse_tensor)
\ No newline at end of file