compiler/bcq-tools/README.md

   1 # BCQ Tools
   2
   3 This directory includes some tools related with BCQ.
   4
   5 ## preserve_bcq_info
   6
   7 ### Purpose
   8
   9 `preserve_bcq_info` is for preserving constant nodes which include BCQ information.
  10 When `.pb` file is converted to `.tflite` file by TFlite converter, constant nodes whose values are exactly same are removed and then linked to only one representative node.
  11 This makes us impossible to know what constant node should be linked to a node which we want to apply BCQ.
  12 One of the solutions is making all the same constant nodes different by inserting unique values and ignore the newly generated unique values when BCQ fusing is applied.
  13 `preserve_bcq_info` will generate and insert unique dummy values to the constant nodes whose values are same not to be removed by Tensorflow Lite converter.
  14 As a result, BCQ information will be preserved.
  15
  16 ### How to use
  17
  18 ```bash
  19 preserve_bcq_info \
  20 --input_path /path/to/original_model.pb \
  21 --output_path /path/to/preserved_model.pb
  22 ```
  23
  24 ### How it works
  25
  26 If we add unique dummy value at the end of each constant nodes, all the constant nodes would be different. Following is an example.
  27
  28 ```
  29 [Original Constant Nodes]
  30 const(value=[1, 2, 3], name='const1')
  31 const(value=[1, 2, 3], name='const2')
  32 const(value=[1, 2, 3], name='const3')
  33
  34 [After BCQ information preserved]
  35 const(value=[1, 2, 3, -1], name='const1')
  36 const(value=[1, 2, 3, -2], name='const2')
  37 const(value=[1, 2, 3, -3], name='const3')
  38 ```
  39
  40 For dummy values, negative values are used instead of positive values.
  41 This is because positive valus may be confused with original constant node values.
  42 For your information, unique dummy value starts from -1 and moves to -2, -3, ..., -N, where N is the number of preserved constant nodes.
  43
  44 ### Caution
  45
  46 - Newly generated dummy values should be ignored when the constant nodes are used.
  47
  48 ## generate_bcq_output_arrays
  49
  50 ### Purpose
  51
  52 To apply BCQ, BCQ information nodes should be designated as model output so that they are alive even after TFLite conversion is finished.
  53 However, there are so many nodes to designate and sometimes we cannot copy and paste all of them because the string size is too big.
  54 `generate_bcq_output_arrays` is for generating output_arrays, which include BCQ information nodes.
  55
  56 ### How to use
  57
  58 ```bash
  59 generate_bcq_output_arrays \
  60 --input_path /path/to/original_model.pb \
  61 --output_path /path/to/output_arrays.txt
  62 ```
  63
  64 ### How it works
  65
  66 ```
  67 [Original BCQ information nodes]
  68 const(value=[1, 2, 3, -1], name='const1')
  69 const(value=[1, 2, 3, -2], name='const2')
  70 const(value=[1, 2, 3, -3], name='const3')
  71
  72 [Generated output_arrays]
  73 ,const1,const2,const3
  74 ```
  75
  76 ### Caution
  77
  78 - Generated output_arrays will be start with comma.