Fiction reveals the truth that reality obscures

CHANGELOG.md

@@ -3,13 +3,43 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## v0.2.0 - 2019-03-21
+*Fiction reveals the truth that reality obscures.* — Jessamyn West
+### Added
+- Export `fcn_cell_layout` objects as SVG using `show -c`. See README for more information
+- `ps -g` displays and logs critical path and throughput of `fcn_gate_layout` objects
+- Support for RES clocking and integration in `exact` 
+- New TOY benchmarks in respective folder
+- New command `clear` to remove all elements from stores (as a shorthand for `store --clear ...`)
+- Information about how to build fiction for WSL
+- Functions to distinguish different `logic_network` types like AIGs/MIGs/...
+- Parameter `-n` for command `ortho`
+
+### Changed
+- Revised folder structure due to the increasing amount of source files
+- `read_verilog` is now called `read` and can process directories
+- `gate_to_cell` is now called `cell`
+- `write_qca` is now called `qca` and handles file names automatically if necessary
+- `-u` is not a required parameter for `exact` anymore
+- Richer output for `print -w`
+- Included latest bugfixes for [Alice](https://github.com/msoeken/alice)
+- Included latest update for [Lorina](https://github.com/hriener/lorina)
+
+### Fixed
+- Starting layout size for calls to `exact -i` was too low and has been corrected
+- Several code and comment inconsistencies
+
+### Removed
+- ITC99 benchmark files
+
+
 ## v0.1.1 - 2018-12-29
 *Literature is a luxury; fiction is a necessity.* — G. K. Chesterton
 ### Added
-- Technology-specific energy model for fcn_gate_layout; supports QCA thus far
-- Support for `print -c` to write a textual representation of fcn_cell_layout objects
+- Technology-specific energy model for `fcn_gate_layout`; supports QCA thus far
+- Support for `print -c` to write a textual representation of `fcn_cell_layout` objects
 - Information on nested fiction scripts and documentation generation in README
-- *linguist* flags in .gitattributes to prevent benchmark files from being viewed as source code
+- *linguist* flags in `.gitattributes` to prevent benchmark files from being viewed as source code
 
 ### Changed
 - Moved to version 0.4 of [Alice](https://github.com/msoeken/alice)
@@ -19,8 +49,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - "Release" is the standard build mode now
 
 ### Fixed
-- Copy and move constructors of logic_network work properly now
-- Calculation of bounding_box size on fcn_gate_layout now handles empty layouts correctly
+- Copy and move constructors of `logic_network` work properly now
+- Calculation of `bounding_box` size on `fcn_gate_layout` now handles empty layouts correctly
 - Several minor and rare bugs, code inconsistencies, and performance issues
 
 ### Removed

CMakeLists.txt

@@ -1,7 +1,7 @@
 cmake_minimum_required(VERSION 3.2)
 project(fiction
         LANGUAGES CXX
-        VERSION 0.1.1)
+        VERSION 0.2.0)
 
 # C++14
 set(CMAKE_CXX_STANDARD 14)
@@ -18,12 +18,10 @@ endif()
 set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release")
 
 # Include header files
-include_directories(include/)
+include_directories(src/algo/ src/io/ src/tech/ src/topo/ src/util/)
 
 # Find source files
-file(GLOB SOURCES src/*.cpp)
-# Find header files
-file(GLOB HEADERS include/*.h)
+file(GLOB_RECURSE SOURCES src/*.cpp src/*.h)
 
 # Require Boost libraries
 find_package(Boost COMPONENTS system filesystem REQUIRED)
@@ -64,7 +62,7 @@ add_subdirectory(${LIB_PREFIX}/alice/)
 add_subdirectory(${LIB_PREFIX}/lorina/)
 
 # build executable
-add_executable(fiction ${SOURCES} ${HEADERS})
+add_executable(fiction ${SOURCES})
 add_dependencies(fiction z3)
 
 # link against Boost, Z3, alice, and lorina

README.md

@@ -1,10 +1,11 @@
 # 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.
+in C++14 using the [EPFL Logic Synthesis Libraries](https://github.com/lsils/lstools-showcase). *fiction* focuses on physical
+design of emerging nanotechnologies. 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
@@ -24,11 +25,11 @@ More technologies and libraries are to come!
 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.
+by Microsoft Research. It is only feasable for small circuits but provides the best results.
 
-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.
+Additionally, a [scalable method](http://www.informatik.uni-bremen.de/agra/doc/konf/2019_ASP-DAC_Scalable_Design_for_Field-coupled_Nanocomputing_Circuits.pdf)
+is implemented which is based on Orthogonal Graph Drawing (OGD). It has a huge runtime advantage compared to the SMT technique.
+Though, its results are not optimal in terms of area. It is feasable even for larger circuits and provides results real quick.
 
 This is ongoing research but more algorithms are to come!
 
@@ -73,6 +74,17 @@ You have the choice to change the `cmake` call to `cmake -DCMAKE_BUILD_TYPE=Debu
 information. The build mode can also be toggled via the `ccmake` CLI. Note that building with debug information will
 have a significant negative impact on the runtime.
 
+### Building on Windows Subsystem for Linux (WSL)
+
+To build *fiction* on Windows, WSL has to be installed. Instructions can be found on
+[the official Windows page](https://docs.microsoft.com/en-us/windows/wsl/install-win10). During installation, it is highly
+recommended to pick *Ubuntu* as the Linux distribution. Then, simply follow the build steps listed above on your WSL.
+
+If you want to use [Visual Studio](https://visualstudio.microsoft.com/de/) (VS) to work with the source code, have a look at
+how to [Target WSL from VS](https://devblogs.microsoft.com/cppblog/targeting-windows-subsystem-for-linux-from-visual-studio/),
+[Cross Platform C++ with VS](https://devblogs.microsoft.com/cppblog/using-visual-studio-for-cross-platform-c-development-targeting-windows-and-linux/),
+and [CMake with VS](https://docs.microsoft.com/en-us/cpp/linux/cmake-linux-project?view=vs-2017).
+
 ### Troubleshooting
 
 On some CMake systems, it might be necessary to type
@@ -85,6 +97,25 @@ make fiction
 after the `cmake` call instead of just `make` to guarantee the correct order of build steps. Try this if the initial
 call leads to some kind of error messages revolving around Z3.
 
+#### Troubleshooting while using the WSL
+
+If you cannot install `libboost-all-dev` (the error might look like this: `Unable to locate package libboost-all-dev`) 
+it should be fixed by adding `universe` to your repositories and trying again:
+
+```sh
+sudo add-apt-repository universe
+sudo apt-get update
+sudo apt-get install libboost-all-dev
+```
+
+Note that it is possible that *alice* does not find the readline-library even though it is 
+installed. CMake will inform you about this with a warning: 
+```
+CMake Warning at libs/alice/include/CMakeLists.txt:35 (message):
+  Cannot find readline library, fall back to native interface.
+```
+There is no solution to this as of yet and it may lead to missing tab-completion while interacting with *fiction*.
+
 ## Usage
 
 The build process generates an executable called `fiction`. A simple non-exhaustive workflow is described in the
@@ -114,11 +145,13 @@ netlists in the `benchmarks` folder.
 
 ### Stores
 
-When you are in interactive mode, 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.
+When you are in interactive mode, enter `read <filename>` to read a logic network into a store or `read <directory>` to
+parse all parsable files within that given directory powered by the [lorina](https://github.com/hriener/lorina) parser
+by Heinz Riener. The flag `-s` allows prior sorting. 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
 
@@ -127,44 +160,72 @@ has several flags and options which can be viewed in detail by `exact --help`. T
 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`).
+balancing I/O paths to internally synchronize the circuit using designated pins (`-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,
+[USE](https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=7219390), `2` is a simple diagonal scheme, and `3` is the
+[RES](https://www.tandfonline.com/doi/pdf/10.1080/21681724.2019.1570551?needAccess=true) clocking. 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`.
+Generated FCN gate layouts are also saved in stores. Entering `store -g` shows a list of all gate layouts available.
+Statistical informations about store elements can be printed using command `ps`. For a gate layout, a call to `ps -g`
+could for instance output the following.
+```
+c17 - 5 × 7, #G: 18, #W: 18, #C: 3, #L: 0, CP: 11, TP: 1/1
+```
+It displays from left to right the name of the layout, the dimension in tiles, the number of gate tiles (including
+designated I/O pins and fan-outs), wire elements, crossings, latches
+([synchronization elements](http://www.informatik.uni-bremen.de/agra/doc/konf/2018NANO_SynchronizationOfClockedFieldCoupledCircuits.pdf)),
+the length of the critical path, and the throughput of the design (where 1/1 is maximum throughput).
 
 ### 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
+To synthesize a gate layout to a cell level one, type `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
-`print -c` command to write layouts to the terminal should be used carefully.
+`print -c` command to write layouts to the terminal should be used carefully. See [SVG export](#svg-export) instead.
+
+Nevertheless, you can use `qca <filename>` to create a QCADesigner file for running physical simulations. If no
+filename is given, the stored layout name will be used and the file will be written to the current folder.
+
+### SVG export
+
+Cell level layouts can be exported as scalable vector graphics (`.svg` files) using the command `show -c`. It will open
+your standard SVG program immediately to give you a more sophisticated visual representation of the current cell layout
+in store. If you want to just generate the SVG file without opening it in your standard viewer, use
+`show -c <filename>.svg --silent`.
+
+Alternatively, open the exported file with a different program by using `show -c --program "\"google-chrome\" {}"` for
+instance to open it with your Chrome browser. Note, that this behavior is platform dependent and might not work properly
+under your system. For more information see `show --help` or the full
+[Alice documentation](https://libalice.readthedocs.io/en/latest/index.html).
+
+The used color scheme is based on the one known from [QCADesigner](https://waluslab.ece.ubc.ca/qcadesigner/).
 
-Nevertheless, you can use `write_qca <filename>.qca` to create a QCADesigner file for running physical simulations. 
+There is also an option for showing a simple version of cells that leaves out the quantum dots and clock zone numbers.
+This makes the exported files significantly smaller, especially for large layouts. The corresponding flag is `-s`.
 
 ### 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
+read ../benchmarks/ISCAS85/c17.v
 ps -w
-exact -u 30 -xp
+exact -xp
 print -g
 ps -g
-gate_to_cell
+cell
 ps -c
-write_qca c17.qca
+qca
+show -c c17.svg --silent
 ```
 
 which can be executed by `./fiction -ef c17_synth.fs -l c17_log.json` where statistics are to be logged in a JSON file
@@ -177,7 +238,7 @@ Additionally, *fiction* can also be part of a bash script. Consider the followin
 ```sh
 for filepath in ../benchmarks/TOY/*.v; do
     f="${filepath##*/}"
-    ./fiction -c "read_verilog $filepath; ortho; gate_to_cell; write_qca ${f%.*}.qca"
+    ./fiction -c "read $filepath; ortho; cell; qca ${f%.*}.qca"
 done
 ```
 
@@ -192,14 +253,16 @@ Since all tools were built locally, simply delete the git folder you have cloned
 
 ## Ongoing research
 
-*fiction* is part of my PhD Thesis entitled "Layout of Large Scale Field-coupled Nanocomputing Devices" (working title).
+*fiction* is part of my PhD Thesis entitled "Layout of Large Scale Field-coupled Nanocomputing Circuits" (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. 
+with this framework. Also, I thank Gregor Kuhn for implementing the SVG export and for reporting troublesome bugs; and
+Mario Kneidinger for code contributions, pointing out the Visual Studio resources and documentation inconsistencies
+on my side.
 
 ## Disclaimer