1 /* Copyright 2020 The TensorFlow Authors. All Rights Reserved.
2 
3 Licensed under the Apache License, Version 2.0 (the "License");
4 you may not use this file except in compliance with the License.
5 You may obtain a copy of the License at
6 
7     http://www.apache.org/licenses/LICENSE-2.0
8 
9 Unless required by applicable law or agreed to in writing, software
10 distributed under the License is distributed on an "AS IS" BASIS,
11 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 See the License for the specific language governing permissions and
13 limitations under the License.
14 ==============================================================================*/
15 #ifndef TENSORFLOW_LITE_TOOLS_OPTIMIZE_SPARSITY_FORMAT_CONVERTER_H_
16 #define TENSORFLOW_LITE_TOOLS_OPTIMIZE_SPARSITY_FORMAT_CONVERTER_H_
17 
18 #include <vector>
19 
20 #include "Eigen/Core"
21 #include "tensorflow/lite/c/common.h"
22 
23 namespace tflite {
24 namespace optimize {
25 namespace sparsity {
26 
27 // A converter that keeps an internal representation of sparse tensor parameters
28 // and converts tensors between dense and sparse formats.
29 template <typename T>
30 class FormatConverter {
31  public:
32   /*
33    * Creates a dense to sparse converter.
34    * @param shape             Shape of the dense tensor.
35    * @param traversal_order   In what order to traverse all dimensions,
36    *                          including block dimensions.
37    * @param format            Whether each dimension in the dense tensor is
38    *                          dense or sparse (not in the traversal order).
39    * @param block_size        Size of each block dimension.
40    * @param block_map         Map from block dimension to original tensor
41    *                          dimension.
42    */
43   FormatConverter(const std::vector<int>& shape,
44                   const std::vector<int>& traversal_order,
45                   const std::vector<TfLiteDimensionType>& format,
46                   const std::vector<int>& block_size = {},
47                   const std::vector<int>& block_map = {});
48 
49   /* Creates a sparse to dense converter.
50    * @param shape      Shape of the target dense tensor.
51    * @param sparsity   Sparsity parameter of the sparse TfLiteTensor.
52    */
53   FormatConverter(const std::vector<int>& shape,
54                   const TfLiteSparsity& sparsity);
55 
GetData()56   const std::vector<T>& GetData() { return data_; }
GetDimMetadata()57   const std::vector<std::vector<int>>& GetDimMetadata() {
58     return dim_metadata_;
59   }
60 
61   // Method for dense to sparse conversion. Need to call GetData() method to get
62   // the compressed data.
63   TfLiteStatus DenseToSparse(const T* src_data);
64 
65   // Method for sparse to dense conversion. Need to call GetData() method to get
66   // the decompressed data.
67   TfLiteStatus SparseToDense(const T* src_data);
68   // Method for sparse to dense conversion with caller provided buffer. No need
69   // to call GetData() with this method.
70   TfLiteStatus SparseToDense(const T* src_data, const size_t dest_size,
71                              T* dest_data, TfLiteContext* context = nullptr);
72 
73  private:
74   // A recursive function to fetch data from the compressed src_data buffer and
75   // populate the dense buffer.
76   void Populate(const T* src_data, std::vector<int> indices, int level,
77                 int prev_idx, int* src_data_ptr, T* dest_data);
78 
79   // Check if val is equal to zero.
80   bool IsZero(const T val);
81 
82   // Shape of the conceptual dense tensor.
83   std::vector<int> dense_shape_;
84   // Shape of the dense tensor with inner blocks reduced. For example, a (4, 4)
85   // tensor with (2, 2) block has blocked_shape (2, 2).
86   std::vector<int> blocked_shape_;
87   // Total number of elements in the dense tensor.
88   size_t dense_size_;
89   // Has n(original dimension)+k(block_dimension) elements.
90   std::vector<int> traversal_order_;
91   // Format of each dimension in the traversal order.
92   std::vector<TfLiteDimensionType> format_;
93   // Size of each block dimension, in the same order as block map.
94   std::vector<int> block_size_;
95   // Map from block dimension to the original tensor dimension.
96   std::vector<int> block_map_;
97   // Metadata of each dimension in the traversal order.
98   // Each dimension needs two vectors. For dense dimensions, the first vector
99   // stores the size of that dimension, and the second vector is empty. For
100   // sparse dimensions, the first vector stores the segments and the second one
101   // stores the indices.
102   std::vector<std::vector<int>> dim_metadata_;
103   // Actual buffer holding data after conversion. Could be sparse buffer or
104   // dense buffer.
105   std::vector<T> data_;
106 };
107 
108 template <>
109 bool FormatConverter<Eigen::half>::IsZero(const Eigen::half val);
110 
111 extern template class FormatConverter<int32_t>;
112 extern template class FormatConverter<int8_t>;
113 extern template class FormatConverter<float>;
114 extern template class FormatConverter<Eigen::half>;
115 }  // namespace sparsity
116 }  // namespace optimize
117 }  // namespace tflite
118 
119 #endif  // TENSORFLOW_LITE_TOOLS_OPTIMIZE_SPARSITY_FORMAT_CONVERTER_H_
120