github.com/cockroachdb/cockroach@v20.2.0-alpha.1+incompatible/pkg/col/colserde/arrowserde/tensor.fbs (about)

     1  // Licensed to the Apache Software Foundation (ASF) under one
     2  // or more contributor license agreements.  See the NOTICE file
     3  // distributed with this work for additional information
     4  // regarding copyright ownership.  The ASF licenses this file
     5  // to you under the Apache License, Version 2.0 (the
     6  // "License"); you may not use this file except in compliance
     7  // with the License.  You may obtain a copy of the License at
     8  //
     9  //   http://www.apache.org/licenses/LICENSE-2.0
    10  //
    11  // Unless required by applicable law or agreed to in writing,
    12  // software distributed under the License is distributed on an
    13  // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    14  // KIND, either express or implied.  See the License for the
    15  // specific language governing permissions and limitations
    16  // under the License.
    17  
    18  /// EXPERIMENTAL: Metadata for n-dimensional arrays, aka "tensors" or
    19  /// "ndarrays". Arrow implementations in general are not required to implement
    20  /// this type
    21  
    22  include "schema.fbs";
    23  
    24  namespace org.apache.arrow.flatbuf;
    25  
    26  /// ----------------------------------------------------------------------
    27  /// Data structures for dense tensors
    28  
    29  /// Shape data for a single axis in a tensor
    30  table TensorDim {
    31    /// Length of dimension
    32    size: long;
    33  
    34    /// Name of the dimension, optional
    35    name: string;
    36  }
    37  
    38  table Tensor {
    39    /// The type of data contained in a value cell. Currently only fixed-width
    40    /// value types are supported, no strings or nested types
    41    type: Type;
    42  
    43    /// The dimensions of the tensor, optionally named
    44    shape: [TensorDim];
    45  
    46    /// Non-negative byte offsets to advance one value cell along each dimension
    47    strides: [long];
    48  
    49    /// The location and size of the tensor's data
    50    data: Buffer;
    51  }
    52  
    53  root_type Tensor;
    54  
    55  /// ----------------------------------------------------------------------
    56  /// EXPERIMENTAL: Data structures for sparse tensors
    57  
    58  /// Coodinate format of sparse tensor index.
    59  table SparseTensorIndexCOO {
    60    /// COO's index list are represented as a NxM matrix,
    61    /// where N is the number of non-zero values,
    62    /// and M is the number of dimensions of a sparse tensor.
    63    /// indicesBuffer stores the location and size of this index matrix.
    64    /// The type of index value is long, so the stride for the index matrix is unnecessary.
    65    ///
    66    /// For example, let X be a 2x3x4x5 tensor, and it has the following 6 non-zero values:
    67    ///
    68    ///   X[0, 1, 2, 0] := 1
    69    ///   X[1, 1, 2, 3] := 2
    70    ///   X[0, 2, 1, 0] := 3
    71    ///   X[0, 1, 3, 0] := 4
    72    ///   X[0, 1, 2, 1] := 5
    73    ///   X[1, 2, 0, 4] := 6
    74    ///
    75    /// In COO format, the index matrix of X is the following 4x6 matrix:
    76    ///
    77    ///   [[0, 0, 0, 0, 1, 1],
    78    ///    [1, 1, 1, 2, 1, 2],
    79    ///    [2, 2, 3, 1, 2, 0],
    80    ///    [0, 1, 0, 0, 3, 4]]
    81    ///
    82    /// Note that the indices are sorted in lexcographical order.
    83    indicesBuffer: Buffer;
    84  }
    85  
    86  /// Compressed Sparse Row format, that is matrix-specific.
    87  table SparseMatrixIndexCSR {
    88    /// indptrBuffer stores the location and size of indptr array that
    89    /// represents the range of the rows.
    90    /// The i-th row spans from indptr[i] to indptr[i+1] in the data.
    91    /// The length of this array is 1 + (the number of rows), and the type
    92    /// of index value is long.
    93    ///
    94    /// For example, let X be the following 6x4 matrix:
    95    ///
    96    ///   X := [[0, 1, 2, 0],
    97    ///         [0, 0, 3, 0],
    98    ///         [0, 4, 0, 5],
    99    ///         [0, 0, 0, 0],
   100    ///         [6, 0, 7, 8],
   101    ///         [0, 9, 0, 0]].
   102    ///
   103    /// The array of non-zero values in X is:
   104    ///
   105    ///   values(X) = [1, 2, 3, 4, 5, 6, 7, 8, 9].
   106    ///
   107    /// And the indptr of X is:
   108    ///
   109    ///   indptr(X) = [0, 2, 3, 5, 5, 8, 10].
   110    indptrBuffer: Buffer;
   111  
   112    /// indicesBuffer stores the location and size of the array that
   113    /// contains the column indices of the corresponding non-zero values.
   114    /// The type of index value is long.
   115    ///
   116    /// For example, the indices of the above X is:
   117    ///
   118    ///   indices(X) = [1, 2, 2, 1, 3, 0, 2, 3, 1].
   119    indicesBuffer: Buffer;
   120  }
   121  
   122  union SparseTensorIndex {
   123    SparseTensorIndexCOO,
   124    SparseMatrixIndexCSR
   125  }
   126  
   127  table SparseTensor {
   128    /// The type of data contained in a value cell.
   129    /// Currently only fixed-width value types are supported,
   130    /// no strings or nested types.
   131    type: Type;
   132  
   133    /// The dimensions of the tensor, optionally named.
   134    shape: [TensorDim];
   135  
   136    /// The number of non-zero values in a sparse tensor.
   137    non_zero_length: long;
   138  
   139    /// Sparse tensor index
   140    sparseIndex: SparseTensorIndex;
   141  
   142    /// The location and size of the tensor's data
   143    data: Buffer;
   144  }
   145  
   146  root_type SparseTensor;