Readme
by Kunmiao Yang

******************** Structure ********************
The main structure of this project is generated by maven. So you may be familiar with
it if you used maven before. I also added my own directory to it.
1. Source code:
    The source code is under the <Project root>/src/main/java path. All the source code
    are in the org.ncsu.dnn package, therefore, they are in the org/ncsu/dnn sub-directory
    under the java path mentioned above.
    There are 2 sub packages under the org.ncsu.dnn, org.ncsu.dnn.caffe and
    org.ncsu.dnn.tf package. The Caffe model scanner, parser and model classes are in
    caffe package. The TensorFlow model, layer classes and convertion code are in tf
    package.
    The Simple and Multiplexing code generators are in the org.ncsu.dnn package. The 2
    Class SimpleCodeGenerator and MultiCodeGenerator both have a main function to run
    directly with 2 arguments.

2. Resources files:
    The root directory of resources files is <Project root>/src/main/resources. All the
    resources files are under the org/ncsu/dnn/tf/template sub-directory, including 4
    python template files to generate the TensorFlow python code. These files will be
    packaged into the jar file along with the compiled class file.

3. Test code:
    The test code are all under the <Project root>/src/test/java/org/ncsu/dnn/ path.
    Including unit tests for scanner and parser and feature tests for TensorFlow model
    conversion and code generation.

4. Test resources files:
    The test resources files are all under the path
    <Project root>/src/test/resources/org/ncsu/dnn/caffe. There are 4 Inception model
    files in prototxt format. They are used in the feature tests to be converted into
    TensorFlow python models.

5. Target files:
    The <Project root>/target directory contains the compiled result and packaged jar
    file.

6. Output files:
    The generated TensorFlow model files by automatic feature tests are under the
    <Project root>/output directory by default.

7. Script files:
    I made some shell script files under the <Project root> directory. They can be used
    to execute the generated jar file. To use them you will need to add executable
    attributes for them.

******************** Install ********************
1. Java 1.7 or higher:
    Installation instruction: https://www.java.com/en/download/help/download_options.xml

2. Maven 3.0.5 or higher:
    Installation instruction: https://maven.apache.org/install.html

3. Enable bash shell scripts (optional on linux):
    To enable the bash shell scripts on linux, use the following command under the root
    path of this project:
    $ chmod +x *.sh

******************** Compile ********************
1. Compile source code to class files:
    Under the root path of this project, use the following command to compile:
    $ mvn compile

2. Generate jar package:
    To generate jar package, you need to compile the code first, or the package would be
    empty jar file. Under the root path of this project, use the following command to
    generate:
    $ mvn jar:jar
    The jar file would be generated under the <Project root>/target directory by default

******************** Test ********************
To test the project you need to compile the code first.
    1. Execute automatic tests:
    Under the root path of this project, use the following command to execute automatic
    tests:
    $ mvn test

    2. Test class files:
    Test class files locate at <Project root>/src/test/java directory.

    3. Input files for tests:
    The input files for tests are caffe prototxt files, including Inception V1, V2, V3 and V4
    and AlexNet.
    You can find them under <Project root>/src/test/resources/org/ncsu/dnn/caffe directory.

******************** Execute ********************
You can also manually execute the program with your own input files. To execute the program you
need to generate the jar package first. Then you need to prepare the prototxt file.
1. Simple:
    use the following command to run:
    $ java -cp <DNNCodeGenerator.jar file path> org.ncsu.dnn.SimpleCodeGenerator <input file path> [output file path]
    or you can use the script under the root path of this project if you are on Linux:
    $ ./genSimpleCode.sh <input file path> [output file path]

2. Multiplexing:
    use the following command to run:
    $ java -cp <DNNCodeGenerator.jar file path> org.ncsu.dnn.MultiCodeGenerator <input file path> [output file path]
    or you can use the script under the root path of this project if you are on Linux:
    $ ./genMultiplexingCode.sh <input file path> [output file path]

Notations:
<DNNCodeGenerator.jar file path>:   the jar file path generated.
<input file path>:                  the input prototxt file path
[output file path]:                 (optional) the output python file path. If not provided,
                                    the program would use the input file name with an
                                    additional suffix (_simple or _multiplexing), and it
                                    would be generated at run path.

******************** Output ********************
    1. Output of compile:
    The output of compile is generated by maven. Upon success, maven would generate success
    messages like this:
    [INFO] Compiling 25 source files to /home/kyang12/DNNCodeGenerator/target/classes
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 15.451s
    [INFO] Finished at: Thu Nov 15 22:05:43 EST 2018
    [INFO] Final Memory: 12M/34M
    [INFO] ------------------------------------------------------------------------
    And it would generate compiled targets under <Project root>/target directory.
    If it failed to compile, it would generate error messages.

    2. Output of jar package generation:
    The output of jar package generation is generated by maven. Upon success, maven would
    generate success messages like this:
    [INFO] --- maven-jar-plugin:3.0.0:jar (default-cli) @ DNNCodeGenerator ---
    [INFO] Building jar: /home/kyang12/DNNCodeGenerator/target/DNNCodeGenerator-1.0.jar
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 5.088s
    [INFO] Finished at: Thu Nov 15 22:06:48 EST 2018
    [INFO] Final Memory: 7M/89M
    [INFO] ------------------------------------------------------------------------
    And it would generate DNNCodeGenerator-1.0.jar under <Project root>/target directory.
    If generate before compile, it would still generate the jar file, but the file would be
    empty.

    3. Output of automatic tests:
    The output of automatic tests is generated by maven. Upon success, maven would generate success
    messages like this:
    Results :
    Tests run: 22, Failures: 0, Errors: 0, Skipped: 0
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 19.573s
    [INFO] Finished at: Thu Nov 15 22:09:17 EST 2018
    [INFO] Final Memory: 13M/33M
    [INFO] ------------------------------------------------------------------------
    If any test case failed, it would generate error messages.

    4. Output files from the tests:
    After execute this automatic tests, the program would generate 8 python files containing
    simple and multiplexing tensorflow models for each of the input caffe model file. You can
    find them under <Project root>/output directory. this directory would be generated after
    these teats are executed.

******************** Limitation ********************
    1. Applicable models:
    This program is designed to parse and generate Inception models. I tested from V1 to V4.
    I also tested AlexNet, the generated code would use convolution layer to implement fully
    connected layer.

    2. Caffe layer limitations:
    Currently it only supports the following caffe layers:
    Convolution, BatchNorm, Scale, Relu, Pooling, Concat, Dropout, Reshape, Softmax,
    InnerProduct
    And it only supports the following tensorflow layers:
    slim.conv2d, slim.max_pool2d, slim.avg_pool2d, slim.concat, slim.dropout, slim.softmax,
    tf.squeeze
    But based on OO design, it would be easy to add new type of layers.

    3. Limitation on conversion of InnerProduct layer in caffe:
    Since it is very popular to convert the last fully connected layer into convolution layer,
    and in Inception models the fully connected layer often comes last, I converted the
    InnerProduct layer in caffe into slim.conv2d by default. You can easily change the output in
    org.ncsu.dnn.tf.InnerProductLayer class.

    4. Branch limitation:
    I found that the caffe models for Inceptions doesn't provide a scope hierarchy for inception
    layers like the example input file (inception_v1.prototxt). So I tried to construct this branch
    hierarchy using the a special DFS traverse. But this hierarchy construction can only support
    Inception models right now. It cannot handle NN blocks with more than one concat layers, because
    theoretically, this branch organized architecture cannot support graph with any complexity. It
    need to develop specifically for each different kind of model.

    5. Default parameter limitation:
    The stride parameter for pooling layers would always be generated right now, unlike the example
    tensorflow code in which some stride parameter would be omitted because it equals the default
    value. I found in the example file, when the stride parameter equals default value, it would
    explicitly declare it in some cases, but omit it in others. So I decide to explicitly generate
    them by default.

    6. The select depth injection in multiplexing:
    I assume that it is used for pruning, so it should not affect the output number of the block. So,
    I only inject them in convolution layers inside blocks that do not directly connect to the concat
    layer.