Let there be a fiction

.gitmodules

@@ -0,0 +1,12 @@
+[submodule "libs/alice"]
+	path = libs/alice
+	url = https://github.com/marcelwa/alice.git
+[submodule "libs/lorina"]
+	path = libs/lorina
+	url = https://github.com/marcelwa/lorina.git
+[submodule "libs/cppitertools"]
+	path = libs/cppitertools
+	url = https://github.com/marcelwa/cppitertools.git
+[submodule "libs/z3"]
+	path = libs/z3
+	url = https://github.com/marcelwa/z3.git

CMakeLists.txt

@@ -0,0 +1,64 @@
+cmake_minimum_required(VERSION 3.2)
+project(fiction
+        LANGUAGES CXX
+        VERSION 0.1)
+
+# C++14
+set(CMAKE_CXX_STANDARD 14)
+
+# Set debug build options
+set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -Wall -Wextra -Wpedantic")
+# Set release build options
+set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -Wall -O3")
+
+# Include header files
+include_directories(include/)
+
+# Find source files
+file(GLOB SOURCES src/*.cpp)
+# Find header files
+file(GLOB HEADERS include/*.h)
+
+# Require Boost libraries
+find_package(Boost COMPONENTS system filesystem REQUIRED)
+if(Boost_FOUND)
+    include_directories(${Boost_INCLUDE_DIRS})
+    link_directories(${Boost_LIBRARY_DIRS})
+endif()
+
+# custom install prefix for libraries
+set(LIB_PREFIX ${CMAKE_SOURCE_DIR}/libs)
+
+# Clone, build and locally install Z3
+include(ExternalProject)
+set(Z3_DIR ${CMAKE_BINARY_DIR}/z3)
+ExternalProject_Add(z3
+        SOURCE_DIR        ${LIB_PREFIX}/z3/
+        BUILD_IN_SOURCE   1
+        INSTALL_DIR       ${Z3_DIR}/
+        CONFIGURE_COMMAND env CC=${CMAKE_C_COMPILER} CXX=${CMAKE_CXX_COMPILER}
+                          ./configure -p <INSTALL_DIR> -b build --staticlib ${Z3_DEBUG}
+        BUILD_COMMAND     make -j3 -C build
+        INSTALL_COMMAND   make -C build install
+        COMMAND           ${CMAKE_COMMAND} -E touch ${CMAKE_CURRENT_LIST_FILE}
+        LOG_CONFIGURE     1
+        LOG_INSTALL       1
+        LOG_BUILD         1)
+
+# include Z3
+include_directories(${Z3_DIR}/include/)
+
+# include cppitertools
+include_directories(${LIB_PREFIX}/cppitertools/)
+
+# include alice
+add_subdirectory(${LIB_PREFIX}/alice/)
+
+# include lorina
+add_subdirectory(${LIB_PREFIX}/lorina/)
+
+# build executable
+add_executable(fiction ${SOURCES} ${HEADERS})
+
+# link against Boost, Z3, alice, and lorina
+target_link_libraries(fiction ${Boost_LIBRARIES} ${Z3_DIR}/lib/libz3.so alice lorina)

LICENSE.txt

@@ -0,0 +1,115 @@
+                        THE CRAPL v0 BETA 1
+
+
+0. Information about the CRAPL
+
+If you have questions or concerns about the CRAPL, or you need more
+information about this license, please contact:
+
+   Matthew Might
+   http://matt.might.net/
+
+
+I. Preamble
+
+Science thrives on openness.
+
+In modern science, it is often infeasible to replicate claims without
+access to the software underlying those claims.
+
+Let's all be honest: when scientists write code, aesthetics and
+software engineering principles take a back seat to having running,
+working code before a deadline.
+
+So, let's release the ugly.  And, let's be proud of that.
+
+
+II. Definitions
+
+1. "This License" refers to version 0 beta 1 of the Community
+    Research and Academic Programming License (the CRAPL). 
+
+2. "The Program" refers to the medley of source code, shell scripts,
+    executables, objects, libraries and build files supplied to You,
+    or these files as modified by You.
+
+   [Any appearance of design in the Program is purely coincidental and
+    should not in any way be mistaken for evidence of thoughtful
+    software construction.]
+
+3. "You" refers to the person or persons brave and daft enough to use
+    the Program.
+
+4. "The Documentation" refers to the Program.
+
+5. "The Author" probably refers to the caffeine-addled graduate
+    student that got the Program to work moments before a submission
+    deadline.
+
+
+III. Terms
+
+1. By reading this sentence, You have agreed to the terms and
+   conditions of this License.
+
+2. If the Program shows any evidence of having been properly tested
+   or verified, You will disregard this evidence.
+
+3. You agree to hold the Author free from shame, embarrassment or
+   ridicule for any hacks, kludges or leaps of faith found within the
+   Program.
+
+4. You recognize that any request for support for the Program will be
+   discarded with extreme prejudice.
+
+5. The Author reserves all rights to the Program, except for any
+   rights granted under any additional licenses attached to the
+   Program.
+
+
+IV. Permissions
+
+1. You are permitted to use the Program to validate published
+   scientific claims.
+
+2. You are permitted to use the Program to validate scientific claims
+   submitted for peer review, under the condition that You keep
+   modifications to the Program confidential until those claims have
+   been published.
+
+3. You are permitted to use and/or modify the Program for the
+   validation of novel scientific claims if You make a good-faith
+   attempt to notify the Author of Your work and Your claims prior to
+   submission for publication.
+
+4. If You publicly release any claims or data that were supported or
+   generated by the Program or a modification thereof, in whole or in
+   part, You will release any inputs supplied to the Program and any
+   modifications You made to the Progam.  This License will be in
+   effect for the modified program.
+
+
+V. Disclaimer of Warranty
+
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
+WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
+PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
+DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
+CORRECTION.
+
+
+VI. Limitation of Liability
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
+CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
+ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT
+NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
+LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
+TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
+PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

README.md

@@ -0,0 +1,198 @@
+# Let there be a fiction
+
+This code base provides a framework for **fi**eld-**c**oupled **t**echnology-**i**ndependent **o**pen **n**anocomputing
+in C++14. As a promising class of post-CMOS technologies, [Field-coupled Nanocomputing
+(FCN)](https://www.springer.com/de/book/9783662437216) devices like Quantum-dot Cellular Automata (QCA) in manifold
+forms (e.g. atomic or molecular), Nanomagnet Logic (NML) devices, and many more, allow for high computing performance
+with tremendously low power consumption without the flow of electric current.
+
+With ongoing research in the field, it is unclear, which technology will eventually be large scale fabricable.
+Therefore, *fiction* is able to perform placement and routing tasks for specific tile-based layouts on a data structure
+that abstracts from physical cell design. Using an extensible set of gate libraries, technologies, and cell types, these
+can be translated easily into what ever FCN technology is desired.
+
+### Technologies
+
+So far, created layouts can be converted into QCA circuits using a custom version of the
+[QCA-ONE](https://ieeexplore.ieee.org/document/7538997/) gate library. Those can be written as files for
+[QCADesigner](https://waluslab.ece.ubc.ca/qcadesigner/) to run physical simulations.
+
+More technologies and libraries are to come!
+
+### Layout Algorithms
+
+An [exact approach](http://www.informatik.uni-bremen.de/agra/doc/konf/2018DATE_ExactMethodforDesignExplorationOfQCA.pdf)
+in terms of circuit area is provided which is the first one ever in the field of FCN circuits.
+It is based on Satisfiability Modulo Theories (SMT) and utilizes the solver engine [Z3](https://github.com/Z3Prover/z3)
+by Microsoft Research.
+
+Additionally, a heuristic method is implemented which is based on orthogonal graph drawing. It has a huge runtime
+advantage compared to the SMT technique. Though, its results are not optimal in terms of area. This approach was
+recently accepted at the ASP-DAC 2019.
+
+This is ongoing research but more algorithms are to come!
+
+## Building process
+
+Git, g++, cmake and the Boost libraries are necessary in order to build *fiction*. Since a Python interpreter and
+GNU readline are utilized by some dependencies, it is also recommended to set them up.
+If you are on *Ubuntu*, you should be fine installing them with this command:
+
+```sh
+sudo apt-get install git g++ cmake libboost-all-dev python libreadline-dev
+```
+
+Note that there is no guarantee that your system lacks some required packages which are not listed here! CMake will
+inform you about missing dependencies during the build process.
+
+Check out the git project (and all of its submodules) using the following command:
+
+```sh
+git clone https://github.com/marcelwa/fiction.git --recursive
+```
+
+Several third-party libraries will be cloned within the `libs/` folder. The `cmake` build process will take care of
+them automatically.
+
+Afterwards, *fiction* is ready to be built. Simply enter the following commands:
+
+```sh
+cd fiction
+mkdir build
+cd build
+cmake -DCMAKE_BUILD_TYPE=Release ..
+make -j4
+```
+
+Note that this process may take a while!
+
+You have the choice to change the `cmake` call to `cmake -DCMAKE_BUILD_TYPE=Debug ..` if you prefer building with debug
+information. Note that this will have a significant negative impact on the runtime.
+
+### Troubleshooting
+
+On some older CMake systems, it might be necessary to type
+
+```sh
+make z3 -j4
+make -j4
+```
+
+after the `cmake` call to guarantee the correct order of build steps. Try this if the initial call leads to some kind
+of error messages revolving around Z3.
+
+## Usage
+
+The build process generates an executable called `fiction`. A simple non-exhaustive workflow is described in the
+following. To get some information about the available commands, run `fiction` with a help flag:
+
+```sh
+./fiction --help
+```
+
+### Preface
+
+*fiction* utilizes the CLI [alice](https://github.com/msoeken/alice) by Mathias Soeken. It provides a flexible
+store-based architecture. A store for logic networks holds specifications which then can be transformed into placed
+and routed FCN circuit layouts. Specifications can be provided in terms of synthesized Verilog netlist files. Using the
+tool [ABC](https://github.com/berkeley-abc/abc) for example, such netlist files can be generated by
+
+```sh
+read spec.bench
+strash
+write spec.v
+```
+
+ABC supports numerous file formats from which `.bench` is just an example one. *fiction* also comes with a lot of preset
+netlists in the `benchmarks` folder.
+
+### Stores
+
+Starting the interactive mode by entering `./fiction` greets the user with a prompt. Again, input of `help` produces a
+list of available commands. Enter `read_verilog <filename>` to read a logic network into a store. The content of the
+logic network store can be briefly viewed by entering `store -w` whereas `print -w` writes a
+[Graphviz](https://www.graphviz.org/) dot file of the current network to the standard output. Arbitrarily many logic
+networks can be held in store from which the latest is always the active one. Change active network with `set -w <n>`
+where you replace `<n>` by the number of the store element you want to activate.
+
+### Placement & Routing
+
+Initiate an exact placement and routing call with the active logic network element in store by `exact`. This approach
+has several flags and options which can be viewed in detail by `exact --help`. The approach relies on a series of SMT
+solver calls to which `-u 20` defines an upper bound of 20 FCN tiles. Note that since the approach is exact, only small
+networks can be placed and routed in reasonable runtime. Another call of `exact -u 25 -xaib` would try to place
+and route the current network on 25 FCN tiles, utilizing crossings (`-x`) and artificial latches (`-a`) while also
+balancing I/O paths to internally synchronize the circuit (`-i`) plus routing all I/Os to the grid borders for easier
+access (`-b`).
+
+Additionally, you can provide a pre-defined clocking scheme to prune the search space. Doing so by option `-s` expects a
+number where `0` represents default open clocking, `1` is
+[USE](https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=7219390), and `2` is a simple diagonal scheme. Additionally,
+a number of clock phases to use can be specified by utilizing the `-n` flag. Currently, only 3- and 4-phase clockings
+are supported. Additional clocking schemes can be implemented in the header file `fcn_clocking_scheme.h`.
+
+Calls to `ortho` are not expecting flags. This algorithm based on orthogonal graph drawing produces layouts in much
+shorter time. Though their quality in terms of area is far from optimum. Plus, for physical implementation, it might be
+necessary to route primary inputs/outputs to the grid borders by hand.
+
+Generated FCN gate layouts are also saved in stores. Entering `store -g` shows a list of all gate layouts available. A
+simple textual representation can be viewed by entering `print -g`.
+
+### Physical synthesis
+
+To synthesize a gate layout to a cell level one, type `gate_to_cell`, where the `-l` flag indicates the gate library to
+use. Currently, only QCA-ONE is available which is the default setting. Cell layouts are also saved in stores which can
+be accessed by typing `store -c`. Due to significantly larger size of cell layouts compared to gate layouts, the
+`write -c` command to print layouts to the terminal is not implemented.
+
+Nevertheless, use `write_qca <filename>.qca` to create a QCADesigner file for running physical simulations. 
+
+### Automation by scripting
+
+All steps can also be specified within a *fiction script* file like the following called `c17_synth.fs`
+
+```sh
+read_verilog ../benchmarks/ISCAS85/c17.v
+ps -w
+exact -u 30 -xp
+print -g
+ps -g
+gate_to_cell
+ps -c
+write_qca c17.qca
+```
+
+which can be executed by `./fiction -ef c17_synth.fs -l c17_log.json` where statistics are to be logged in a JSON file
+called `c17_log.json`.
+
+Additionally, *fiction* can also be part of a bash script. Consider the following snippet
+
+```sh
+for filepath in ../benchmarks/TOY/*.v; do
+    f="${filepath##*/}"
+    ./fiction -c "read_verilog $filepath; ortho; gate_to_cell; write_qca ${f%.*}.qca"
+done
+```
+
+where the for-loop iterates over all Verilog files in the `../benchmarks/TOY/` folder. Using the flag `-c`, a
+semicolon-separated list of commands can be entered in *fiction*. In this case, the files are to be read in a store, placed
+and routed using the `ortho` algorithm, synthesized to cell level, and written as QCA using their original file name.
+
+## Uninstall
+
+Since all tools were built locally, simply delete the git folder you have cloned initially to uninstall this project.
+
+## Ongoing research
+
+*fiction* is part of my PhD Thesis entitled "Layout of Large Scale Field-coupled Nanocomputing Devices" (working title).
+Please find my publication list [here](http://www.informatik.uni-bremen.de/agra/eng/pub.php?search=Marcel%20Walter).
+Should you be interested in a collaboration or an academic exchange, feel free to reach out at any time.
+
+## Acknowledgments
+
+I would like to thank Frank Sill Torres for introducing me to FCN and for countless helpful discussions and support
+with this framework. Also, I thank Gregor Kuhn for reporting troublesome bugs. 
+
+## Disclaimer
+
+This is academic software made available under the CRAPL license. For more information see the LICENSE file.