sync with release branch

Author: dboyliao

.circleci/config.yml

@@ -6,10 +6,10 @@ jobs:
     steps:
       - checkout
       - run: mkdir -p /tmp/coverage && mkdir -p /tmp/test_results
-      - run: pip3 install -e .[dev]
+      - run: pip3 install .
       - run: 
           name: Test
-          command: pytest -vv tests
+          command: LC_ALL=C.UTF-8 LANG=C.UTF-8 pytest -vv tests -m 'not slow_test and not deprecated'
           #- run: genhtml main_coverage.info --output-directory /tmp/coverage
           #- store_test_results:
           #    path: /tmp/test_results

.gitignore

@@ -1,3 +1,6 @@
+#system files
+__pycache__
+.DS_Store
 # virtual env
 .venv
 venv
@@ -8,6 +11,8 @@ dev_notes
 !tests/deep_mlp/end_to_end.ipynb
 *.egg*
 worktree/
+build/
+dist/
 # tests
 .pytest_cache
 tests/*/cpp
@@ -18,4 +23,4 @@ tests/deep_mlp/data
 .vscode
 # docs
 doc/build
-doc/source/_build
+doc/source/_build

MANIFEST.in

@@ -1,2 +1,2 @@
 include LICENSE README.md
-recursive-include utensor_cgen/backend/snippets/templates *
+recursive-include utensor_cgen/backend/utensor/snippets/templates *

Makefile

@@ -3,7 +3,7 @@
 tests:
 	rm -f tests_log.txt
 	make test_utils test_ir test_transformer test_frontend \
-		test_matcher test_graph_constructor
+		test_matcher test_graph_constructor test_backend
 
 test_%:
 	@if [ -d .venv ]; then \
@@ -12,5 +12,23 @@ test_%:
 	 	 pytest tests/$@ -vv -s | tee -a tests_log.txt; \
 	 fi;
 
+package:
+	rm -rf dist/*
+	.venv/bin/python setup.py bdist_wheel sdist
+	rm -rf build utensor_cgen.egg-info/
+
+upload-test: package
+	.venv/bin/twine upload -r pypitest dist/*
+
+install-test: package
+	pip uninstall -y utensor-cgen
+	pip install dist/*.tar.gz
+
+upload: package
+	.venv/bin/twine upload -r pypi dist/*
+
 clean:
-	rm -rf tests_log.txt *.pdf .pytest_cache
+	rm -rf tests_log.txt *.pdf \
+	models data \
+	tests/test_backend/{models,data} \
+	.pytest_cache dist/ build/

Pipfile

@@ -1,12 +1,13 @@
 [[source]]
 url = "https://pypi.python.org/simple"
-verify_ssl = true
+verify_ssl = false
 name = "pypi"
 
 [packages]
 e1839a8 = {path = ".",editable = true}
 
 [dev-packages]
+matplotlib = "*"
 pylint = "*"
 "flake8" = "*"
 pytest = "*"
@@ -16,3 +17,6 @@ scipy = "*"
 graphviz = "*"
 sphinx = "*"
 sphinx-autoapi = "*"
+
+[pipenv]
+allow_prereleases = true

Pipfile.lock

@@ -72,26 +72,22 @@ Overall Architecture
 
 ::
 
-      ============       +-----------------+       ===================
-    || model file || --> | frontend Parser | --> || uTensorGraph (IR) ||
-      ============       +-----------------+       ===================
-                                                               |
-                     +-------------------------------+         |
-                     |       graph transformer       |         |
-                     | (legalization & optimization) | <------/
-                     +-------------------------------+
-                                    |
-                                    v
-                         ===========================
-                       ||       uTensorGraph        ||
-                       || (legalized and optimized) ||
-                         ===========================
-                                       |
-    +--------------------------+       |
-    | backend (code generator) | <----/
+      ============       +-----------------+       ============================
+    || model file || --> | frontend Parser | --> || uTensorGraph (IR, generic) ||
+      ============       +-----------------+       ============================
+                                                                |
+                                                                v
+                                                     +---------------------+
+                        =======================      |  graph transformer  |
+                      ||     uTensorGraph     || <-- |    (optimization)   |
+                      || (generic, optimized) ||     +---------------------+
+                        =======================                                    
+                                     |
+    +--------------------------+     |
+    | backend (code generator) | <--/
     +--------------------------+
          |
-         `---> (target files, ex: model.cpp, model.hpp, weights.idx)
+         `---> (target files, ex: model.cpp, model.hpp, weights.idx, ...etc)
 
 Basic Usage
 ===========
@@ -114,7 +110,8 @@ Convert Model File to C/C++ Code
 .. code-block:: console
 
   $ utensor-cli convert <model.pb> \
-    --output-nodes=<node_name>[,<node_name>,...]
+    --output-nodes=<node name>[,<node name>,...] \
+    [--config=config.toml]
 
 Convert given pb file into cpp/hpp files.
 
@@ -123,6 +120,8 @@ nodes you want to output, seperated by comma for multiple values.
 
 In graph theory terminology, they are ``leaf`` nodes of your graph.
 
+Use ``--config`` to pass a configuration file to the cli, you can use ``generate-config`` command to generate one (see below).
+
 example
 ~~~~~~~
 
@@ -132,8 +131,34 @@ example
 
 Run ``utensor-cli convert --help`` for detailed information.
 
-:mod:`utensor_cgen` as Library
-==============================
+Configuration
+-------------
+
+``utensor-cli`` use ``toml`` as configuration format.
+
+You can generate configuration file of given target as following:
+
+.. code-block:: console
+
+  $ utensor-cli generate-config --target <target name> [-o filename.toml]
+
+This command will generate a ``toml`` file listing all configurable values with its defaults.
+
+You can modify the value and pass the file to cli with ``--config`` flag.
+
+example
+~~~~~~~
+
+.. code-block:: console
+
+  # generate config file
+  $ utensor-cli generate-config --target utensor -o myconfig.toml
+
+  # after editting myconfig.toml
+  $ utensor-cli convert mymodel.pb --config=myconfig.toml --output-nodes=output,...
+
+Use :mod:`utensor_cgen` as Library
+==================================
 
 .. subgraph-match-begine
 
@@ -201,12 +226,32 @@ Use Case: Dropout Layer Removal
 
 \ |cnn-dropout|
 
-.. subgraph-match-end
-
 We use mainly `Tensorflow`_ for declaring the pattern graph for matcher now.
 
 High-level graph builder is on its way, see `Future Works <#future-works>`_ for detail.
 
+.. subgraph-match-end
+
+.. offline-tensor-alloc-start
+
+Offline Tensor Memory Allocation
+--------------------------------
+
+Considering following simple multi layers perceptron (`simple_mnist.pb`_):
+
+\ |mlp-alloc-graph|
+
+Once enabled the optimization transformer, ``tensor_alloc``, an offline tensor memory allocation planner,
+``utensor-cli`` will generate ``uTensor`` runtime codes that use following optimized allocation plan:
+
+\ |mlp-alloc|
+
+- y-axis: tensor names ordered by topological sorting
+- x-axis: these are the memory span occupied by each tensor, that is, the memory address offset and
+the size of the tensor
+
+.. offline-tensor-alloc-end
+
 Tutorials
 =========
 
@@ -223,8 +268,8 @@ TensorFlow_
 
 1. Freeze your `tensorflow.Graph`
 
-  - please refer to the `official doc <https://www.tensorflow.org/guide/extend/model_files>`_
-    and read the `Freezing <https://www.tensorflow.org/guide/extend/model_files#freezing>`_ section
+  - please refer to this `issue track <https://github.com/tensorflow/tensorflow/issues/27614>`_ for detail
+  - especially this `comment <https://github.com/tensorflow/tensorflow/issues/27614#issuecomment-571889676>`_ by Robin2091
 
 2. Follow instructions in :ref:`install` section to install :mod:`utensor_cgen`
 
@@ -288,6 +333,7 @@ Future Works
 .. _Tensorflow: https://www.tensorflow.org
 .. _PyTorch: https://pytorch.org/
 .. _uTensor: https://github.com/uTensor/uTensor
+.. _simple_mnist.pb: https://github.com/uTensor/utensor_cgen/blob/develop/tests/deep_mlp/simple_mnist.pb
 
 .. readme_end
 
@@ -297,7 +343,10 @@ Future Works
     :alt: conv-pool-fuse
 .. |convert-example| image:: doc/source/_images/convert_example.png
     :alt: convert-example
-
+.. |mlp-alloc| image:: doc/source/_images/mlp_alloc.png
+    :alt: mlp-alloc
+.. |mlp-alloc-graph| image:: doc/source/_images/mlp_alloc_graph.png
+    :alt: mlp-alloc-graph
 
 .. TODOs
 .. =====

README.rst

@@ -8,3 +8,9 @@
   :height: 300
 .. |convert-example| image:: /_images/convert_example.png
   :alt: convert-example
+.. |mlp-alloc| image:: /_images/mlp_alloc.png
+    :alt: mlp-alloc
+.. |mlp-alloc-graph| image:: /_images/mlp_alloc_graph.png
+    :alt: mlp-alloc-graph
+    :width: 300
+    :height: 450