compiler/circle-partitioner/README.md

   1 # circle-partitioner
   2
   3 _circle-partitioner_ provides model partitioning of circle model to two or more circle models.
   4
   5 ## How circle-partitioner work
   6
   7 _circle-partitioner_ requires 3 positional arguments
   8 - first: `partition` file
   9 - second: `input` circle model file
  10 - third: `work` folder
  11
  12 And options to override `partition` file as a helper to try out without editing `partition` file.
  13 - `--backends`: override `backends` of `[partition]` section
  14 - `--default`: override `default` of `[partition]` section
  15
  16 _circle-partitoner_ will read the `partition` and `input` files and group nodes with same backend
  17 and store them into new circle models in `work` folder, where the `partition` and `input` files
  18 are read from `work` folder.
  19
  20 Outputs are (1) one or more partitioned circle models and (2) connection file that gives how
  21 the partitioned models should be connected to act like the source `input` model.
  22
  23 Why does input files be placed in `work` folder too?
  24 - this is still work in progress condition
  25 - use cases are still ambigious
  26 - original `input` model file can be used by the backend, so `.conn` file links it as `source`
  27 - to make things simple for the backend, it would be better not to use relative path for the files
  28
  29 ### `partition` file
  30
  31 `partition` follows INI format of _crew_ project.
  32
  33 Several example files exist in _circle-part-value-test_ `parts` folder.
  34
  35 This section will explain with `Net_InstanceNorm_003.part` file as example.
  36 ```ini
  37 [partition]
  38 backends=cpu,acl_cl
  39 default=cpu
  40 comply=opcode
  41
  42 [OPCODE]
  43 DIV=acl_cl
  44 ```
  45
  46 ##### `[partition]` section
  47
  48 `[partition]` section is the main section first to read.
  49 - `backends`: Existing partition group names which nodes should be placed, in CSV format.
  50 - `default`: Default group name which should be one of `backends` item.
  51 - `comply`: How to group nodes of the model.
  52    - currently `opcode` and `opname` are supported
  53    - future work: set group by sequence number.
  54
  55 ##### `[OPCODE`] section
  56
  57 This section provides how to group nodes in OPCODE types.
  58 Nodes with same OPCODE will be grouped to that type.
  59 This does not mean number of output circle files will be same as number of backends.
  60 Number of output circle files will depend also on the network structure.
  61
  62 For above example, all `DIV` OPCODE nodes will be grouped to `acl_cl` backend.
  63
  64 `[OPCODE]` can override `default` backend set from `[partition]` section by using `_`.
  65
  66 For example, we can change default to `cpu`.
  67 ```
  68 [OPCODE]
  69 _=cpu
  70 DIV=acl_cl
  71 ```
  72
  73 ### `circle` file
  74
  75 Just normal `circle` file. Currently partition is supported in limited properties and
  76 models with these properties are not support yet;
  77 - Have multiple subgraph models
  78 - Operators with multiple output nodes such as IF or WHILE.
  79
  80 ### `work` folder
  81
  82 `partition` and `circle` file should reside in `work` folder. Output files will be
  83 generated inside this folder.
  84
  85 ### Example
  86
  87 Typical source of paritioning
  88 ```
  89 $ tree Net_InstanceNorm_003/
  90 Net_InstanceNorm_003/
  91 ├── Net_InstanceNorm_003.circle
  92 └── Net_InstanceNorm_003.part
  93 ```
  94
  95 Command example
  96 ```
  97 ./circle_partitioner Net_InstanceNorm_003.part Net_InstanceNorm_003.circle Net_InstanceNorm_003
  98 ```
  99
 100 Result of _circle-partitioner_
 101 ```
 102 $ tree Net_InstanceNorm_003/
 103 Net_InstanceNorm_003/
 104 ├── Net_InstanceNorm_003.00001_cpu.circle
 105 ├── Net_InstanceNorm_003.00002_acl_cl.circle
 106 ├── Net_InstanceNorm_003.00003_cpu.circle
 107 ├── Net_InstanceNorm_003.circle
 108 ├── Net_InstanceNorm_003.conn.ini
 109 ├── Net_InstanceNorm_003.conn.json
 110 └── Net_InstanceNorm_003.part
 111 ```
 112
 113 ### `Net_InstanceNorm_003.conn.ini` and `Net_InstanceNorm_003.conn.json`
 114
 115 These two files are identical in content but in different formats.
 116
 117 `.conn` file provides an information how to reconstruct the partitioned models,
 118 `Net_InstanceNorm_003.00001_cpu.circle`, `Net_InstanceNorm_003.00002_acl_cl.circle`
 119 and `Net_InstanceNorm_003.00003_cpu.circle`, so that it will identical to
 120 source `Net_InstanceNorm_003.circle` model in computational results.
 121
 122 Here, meaning of `reconstruct` is connection of outputs and inputs of partitioned
 123 models.
 124
 125 ```json
 126 $ cat Net_InstanceNorm_003/Net_InstanceNorm_003.conn.json
 127 {
 128   "source" : {
 129     "file" : "Net_InstanceNorm_003.circle",
 130     "inputs" : [ "Input" ],
 131     "outputs" : [ "Add_as_terminal" ]
 132   },
 133   "parts" : [
 134     {
 135       "file" : "Net_InstanceNorm_003.00001_cpu.circle",
 136       "inputs" : [ "Input" ],
 137       "outputs" : [ "Pow", "Sub" ]
 138     },
 139     {
 140       "file" : "Net_InstanceNorm_003.00002_acl_cl.circle",
 141       "inputs" : [ "Sub", "Pow" ],
 142       "outputs" : [ "Div" ]
 143     },
 144     {
 145       "file" : "Net_InstanceNorm_003.00003_cpu.circle",
 146       "inputs" : [ "Div" ],
 147       "outputs" : [ "Add_as_terminal" ]
 148     }
 149   ]
 150 }
 151 ```
 152 Above file is in `JSON` format with `source` file and `parts` for partitioned models.
 153 Each `parts` have `file` for the file, `inputs` for input nodes and `outputs`
 154 for output nodes.
 155
 156 From the `source` we can identify inputs and outputs for the model.
 157
 158 - Each items in `outputs` should connect to `inputs` of another item of `parts` model,
 159 or should be one of the `outputs` of the `source` model.
 160 - For first `Net_InstanceNorm_003.00001_cpu.circle` model, `inputs` is(are) same
 161 as the `source` model: `[ "Input" ]`.
 162 - `outputs` `[ "Pow", "Sub" ]` have same names in the second model
 163 `Net_InstanceNorm_003.00002_acl_cl.circle` which they should be connected.
 164 - And `outputs` `[ "Div" ]` should be connected to `inputs` of
 165 third model `Net_InstanceNorm_003.00003_cpu.circle`.