Command Line Interface (CLI)

The build process generates an executable called fiction in the cli folder. A simple non-exhaustive workflow is described in the following. To get some information about the available commands, run fiction with a help flag:

cli/fiction --help

Starting the interactive mode by entering cli/fiction greets the user with a prompt. Again, input of help produces a list of available commands. One can generate a plain text full documentation by entering help --docs <filename>.

Preface

The fiction binary utilizes the CLI alice by Mathias Soeken. It provides a flexible store-based architecture. A store for logic networks holds specifications which then can be transformed into FCN circuit layouts. Specifications can be provided in terms of synthesized structural Verilog netlist files using assign statements and Boolean primitives, combinational AIGER files, or the BLIF format. Using the tool ABC for example, such files can be generated by:

read spec.bench
strash
write spec.v
write spec.aig
write spec.blif

ABC supports numerous file input formats from which .bench is just an example one. fiction also comes with a lot of preset logic networks in the benchmarks folder.

Stores

Stores hold data structures obtained by parsing, designing, or compiling. There are stores for

  • truth_table (-t)

  • network (-n)

  • gate_layout (-g)

  • cell_layout (-c)

objects. Several generic commands typed in interactive mode work on different kinds of stores and, therefore, need to be given a store flag from the list above. Applicable commands are for instance

  • store: prints a brief listing of the contained elements

  • current <n>: changes the active store element to element number <n> (otherwise, the latest entry is active)

  • ps: prints statistical data and cost metrics of the active store element

  • print: prints a textual representation of the store element to the standard output

  • show: displays a visual representation of the store element with the user’s standard viewer (.dot for -n and -g, .svg for -c)

For an exhaustive overview of available standard commands, see the full alice documentation.

Circuit specifications

As mentioned before, network objects parsed from some Verilog, AIGER, or BLIF file serve as specifications for FCN circuits to be designed. In other words, network objects are to be mapped onto grid-like structures under FCN constraints.

When in fiction’s interactive mode, one can 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 parser by Heinz Riener. The flag -s allows prior sorting. The content of the logic network store can be briefly viewed by entering store -n. A more detailed breakdown can be printed by command gates. Command show -n writes a Graphviz .dot file of the current network and opens it with the user’s standard viewer (e.g. xdot).

Multiple different network types are supported that can directly be created from the input file via individual flags:

  • AND-Inverter Graph (AIG), -a

  • XOR-AND-Inverter Graph (XAG), -x

  • MAJ-Inverter Graph (MIG), -m

  • Technology network (TEC), -t

Truth tables

The truth_table store (-t) can hold logic descriptions in binary format as implemented in the kitty library by Mathias Soeken. These can either be loaded via command tt by specifying a bit/hex string (-t) or a Boolean expression (-e), or be obtained by simulating a network or gate_layout via command simulate. Generating a truth_table from an expression uses the following syntax (from the kitty documentation):

An expression E is a constant 0 or 1, or a variable a, b, ..., p, the negation of an expression !E, the conjunction of multiple expressions (E...E), the disjunction of multiple expressions {E...E}, the exclusive OR of multiple expressions [E...E], or the majority of three expressions <EEE>. Examples are [(ab)(!ac)] to describe if-then-else, or !{!a!b} to describe the application of De Morgan’s law to (ab). The size of the truth table must fit the largest variable in the expression, e.g., if c is the largest variable, then the truth table has at least three variables.

For example, tt -t 0110 and tt -t 0xaffe generate a truth_table from bit and hex strings, respectively.

Logic synthesis

Having a truth_table in store, the command akers generates an equivalent Majority network using Akers’ synthesis.

Furthermore, it is possible to generate a random network by using command random. The desired number of primary inputs can be specified (-n) as well as the gate count excluding inverters and fan-outs (-g). A random seed (-s) allows for reproducibility as it will also be used as the network’s name.

However, most importantly, a technology mapping command map is available that rewrites any network type as a technology network that exclusively uses gates from a given set but computes the same Boolean function. For instance, map -oxi produces a logic network that only uses OR gates, XOR gates, and inverters. This is extremely helpful for FCN gate libraries that do not support certain gate types.

ABC Callback

ABC can be configured as a callback for logic synthesis and optimization from within the CLI. The command abc -c "<command>" will launch ABC and execute the given command string. Internally, it will first write fiction’s current network to a temporary AIGER file, have ABC parse this file as an AIG using read <filename>; strash, and then execute the given command string. Finally, ABC will write the result back to the temporary file which will be read back into fiction as a new network.

The ABC command string construction can be customized to - omit the network read command in ABC (--dont_read,-r) - omit the network strash command in ABC (--dont_strash,-s) - omit the network write command in ABC (--dont_write,-w)

Note

There are known limitations to this approach as an AIGER file is used for interfacing the two tools, which leads to the decomposition of all gates into ANDs and inverters. Furthermore, ABC’s abc script for shortcuts to common commands might not be included, leading to the absence of those abbreviations and scripts. The user is encouraged to use the full command strings instead, e.g., balance; refactor; rewrite; resub instead of b; rf; rw; rs.

Note

See ABC on how to enable ABC in the fiction CLI.

Structural manipulation

As known from the literature, some physical design approaches balance networks prior to the actual placement. This is also possible in fiction using command balance. However, it is not recommended as this will blow-up the resulting layout size tremendously. So far, the implemented physical design algorithms do not make use of balanced networks.

Besides, command fanouts enables the user to specify strategies when substituting high-degree connections into fan-out nodes. For instance, fanouts -d 3 -s 1 allows 3-output fan-out nodes and substitutes cascading fan-outs in a depth-first fashion. This is done with default settings by the physical design approaches if not specified by the user.

Physical design

Physical design is the task of generating a circuit layout from a specification (mostly a logic network). Currently, fiction offers placement and routing in the flavors exact (SMT-based) and scalable (OGD-based) as well as one-pass synthesis (SAT-based). The implementations can be called on the currently active network in store by exact and ortho, respectively. Find some information and parameters about them below.

Generated FCN gate layouts are also saved in stores. Entering store -g shows a list of all gate layouts available. Statistical information about store elements can be printed using the command ps -g and could produce the following output:

c17 (2DDWAVE) - 5 × 7, I/O: 5/2, gates: 8, wires: 28, CP: 11, TP: 1/1, sync. elems.: 0

This displays (from left to right) the name of the layout, its clocking scheme, the aspect ratio in tiles, the number of primary inputs and outputs, the number of gate tiles, wire elements, the length of the critical path, the throughput of the design (where 1/1 is the maximum possible throughput), and the number of synchronization elements.

SMT-based (exact)

Satisfiability Modulo Theories (SMT) is used to describe the physical design problem in first-order logic. The SMT solver engine Z3 is then used to extract a satisfiable model from the resulting formula which is then translated back into a valid solution to the original physical design problem. For more information, see the paper.

This exact approach generates minimal layouts in terms of circuit area. Since determining minimal FCN circuits for given specifications is an NP-complete problem, the process takes a while and is only suitable for rather small benchmarks with just a few gates.

On the other hand, this approach is highly parameterizable and can produce results for a variety of settings. The most important ones are

  • Define the clocking scheme to be used (-s ...)

  • Enable wire crossings (-x)

  • Route all I/Os to the layout’s borders (-b)

  • Allow for de-synchronized circuits (-d)

  • Specify a timeout (-t)

See exact -h for a full list.

Recommended settings include the use of I/O pins located at the layout borders for better integration (-b). Most networks are not realizable without crossings enabled (-x). Specifying a clocking scheme significantly speeds up the process. 2DDWave allows for the strictest constraints and thereby finds a solution the quickest (-s 2ddwave). However, for high input degree networks, no valid solution exists when border I/Os are to be used unless global synchronization is disabled (-d). Generally, solutions are found the fastest with the following settings: Crossings enabled, de-synchronization enabled, and 2DDWave clocking given (-xds 2ddwave). Multi-threading can sometimes speed up the process especially for large networks (-a ...). Note that the more threads are being used, the less information can be shared across the individual solver runs which destroys the benefits of incremental solving and thereby, comparatively, slows down each run. Parallelism is an unstable beta feature.

OGD-based (ortho)

Orthogonal Graph Drawing (OGD) is a well known problem in graph theory that remarkably resembles the physical design problem for tile-based FCN circuits. Even though the problem of determining minimal drawings is hard in general, there exist linear time approximations for 3-graphs. Luckily, AOIGs can be substituted until they are 3-graphs. Using a topological ordering and a certain direction assignment, even large circuits can be designed in reasonable runtime. For more information, see the paper.

This scalable approach only works on logic networks which are AOIGs (MAJ gates do not work). The clocking scheme is fixed to 2DDWave and the algorithm can only be slightly parameterized (see ortho -h).

SAT-based one-pass synthesis (onepass)

The idea of the one-pass synthesis is to combine logic synthesis and physical design into a single run and, thereby, obtain even smaller layouts than possible with the SMT-based exact placement & routing approach. The backend of this algorithm was developed by Winston Haaswijk as the Python3 library Mugen. It utilizes the SAT solver Glucose to solve instances of said combined physical design problem. Given a clocking scheme and a set of gate types to use, this algorithm finds the true minimum FCN circuit implementation of some specification under the provided parameters. For more information, see the paper.

The possible parameters are similar to the ones used for exact. See onepass -h for a full list.

Graph-oriented layout design (gold)

Generates gate-level layouts from logic network specifications by spanning a search space graph where each placement event can be represented as a search space vertex characterized by a partial layout at that instance. Edges between a partial layout a and b exist iff a can be transformed into b via a single placement event. Similar to navigating through a maze, A*-search can be employed to discover a path from the starting vertex (the empty layout) to the exit of the maze (a layout with all gates placed). This approach is scalable but requires that the input network is restricted to a 3-graph. At the same time, the output layout will always be 2DDWave-clocked and is not always optimal. For more information, see the paper.

Possible parameters:

  • Timeout (-t): Timeout for the algorithm in seconds.

  • Number of vertex expansions (-n): Specifies the number of vertex expansions during the search for each vertex in the search space graph (defaults to 4 if not provided).

  • Effort mode (-e): Determines the computational effort used by the algorithm. Possible values are:

    • 0 (high_efficiency): Uses minimal computational resources, resulting in fewer search space graphs and potentially lower quality solutions.

    • 1 (high_effort): Uses increased computational resources to generate more search space graphs, thereby improving the chance of finding an optimal solution.

    • 2 (highest_effort): Utilizes maximum computational resources to produce the most search space graphs, ensuring the highest probability of obtaining the best possible layout.

  • Cost objective (-c): Specifies the cost objective for the layout design. Options include:

    • 0 (area): Minimize the layout area.

    • 1 (wires): Minimize the number of wire segments.

    • 2 (crossings): Minimize the number of crossings.

    • 3 (acp): Minimize the area-crossing product (ACP), balancing area and number of crossings.

  • Return first (-r): Terminate the search as soon as the first valid layout is found, which reduces runtime but might sacrifice result quality.

  • Planar (-p): Enable planar layout generation to constrain routing to be free of crossings.

  • Multithreading (-m): Enable multithreading (currently a beta feature) to potentially accelerate computation.

  • Verbose (-v): Output detailed runtime statistics after the algorithm completes.

Hexagonalization (hex)

Transforms a 2DDWave-clocked Cartesian layout into a hexagonal row-clocked layout suitable for SiDBs by remapping all gates and wires. For more information, see the paper.

Possible parameters:

  • Input pin extension (-i): Extend primary inputs to the top row.

  • Output pin extension (-o): Extend primary outputs to the bottom row.

  • Planar (-p): If -i and/or (-o) is set, enforce planar rerouting when extending primary inputs and/or outputs, ensuring that the routing is free of crossings.

  • Verbose (-v): Output detailed runtime statistics after the algorithm completes.

Post-Layout Optimization (optimize)

A post-layout optimization algorithm that can be used to reduce the area of a given sub-optimal Cartesian gate-level layout created by heuristics or machine learning. This optimization utilizes the distinct characteristics of the 2DDWave clocking scheme, which only allows information flow from top to bottom and left to right, therefore only the aforementioned clocking scheme is supported. For more information, see this paper or this paper.

Possible parameters:

  • Timeout (-t): Timeout for the algorithm in seconds.

  • Number of maximum gate relocations (-m): Should be set to 1 for layouts with more than 100000 tiles, defaults to the number of tiles in the layout.

  • Wiring reduction only (-w): Should be set for layouts with more than 20000000 tiles, not set by default.

  • Planar optimization (-p): Only relocate gates if the new wiring contains no crossings, not set by default.

  • Verbose (-v): Output detailed runtime statistics after the algorithm completes.

Design rule checking (check)

Physical integrity of designed circuits can be verified using command check. It triggers a design rule checker which tests various topological and structural properties of the layout, logs all discrepancies, and outputs a summary report. The design rule checker especially aims at structurally validating layouts that were generated with custom algorithms to find bugs quickly.

Logical simulation (simulate)

If an gate_layout has been created, its functionality can be simulated on a logic level. Command simulate -g traces all paths on the current gate layout in store respecting clocking and synchronization elements. To this end, truth tables for each output are generated.

Timing information, and thereby global synchronization, is not respected here. Use ps -g to get details about the layout’s throughput (TP) and thereby, the amount of clock cycles the PIs need to be stalled to generate the simulated outputs.

A network can also be simulated for comparison by using simulate -n.

Equivalence checking (equiv)

Performs logical and delay equivalence checks of implementations (gate layouts or logic networks) against specifications. Those can themselves be either logic networks or gate layout (-g/-n <index>). Three cases are to be distinguished:

  1. The implementation performs a different functionality under at least one input pattern than its specification. The implementation is not equivalent to its specification.

  2. The implementation performs the same functionality like its specification and has a throughput of 1/1 if it is a gate layout. The implementation is strongly equivalent to its specification.

  3. The implementation performs the same functionality like its specification and has a throughput of 1/x if it is a gate layout, where x > 1. The implementation is weakly equivalent to its specification.

Logical equivalence is checked with a SAT solver via miter structures and Tseitin transformation. For more information, see the paper.

Energy dissipation (energy)

A physical model for calculating the energy dissipation on the gate-level abstraction using the QCA ONE library has been proposed. Thereby, information about the cells’ function within a gate can be utilized to obtain switching energy consumption. The respective value can be printed using command energy. Note that this assumes that the gate-level layout can be physically synthesized using the QCA ONE gate library.

Physical synthesis (cell)

As mentioned above, gate-level layouts can be compiled down to cell-level ones in a physical synthesis step. A gate library is required to do so. The command cell does exactly this, where the -l option indicates the gate library to use. The following ones are currently supported:

  • -l QCAONE represents QCA ONE which is the default setting

  • -l ToPoliNano refers to ToPoliNano’s gate library for iNML circuits. Note that only exact can be used in the moment to create layouts mappable to iNML. Suggested parameters are exact -xnbds columnar --topolinano.

  • -l Bestagon chooses the Bestagon gate library for SiDB circuits. Note that only exact can be used in the moment to create layouts that are properly mappable. Suggested parameters are exact -xdbs row --hex even_row.

Cell-based 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. See SVG export instead.

Cell-level layouts can be written to files parsable by various physical simulators. The following file formats and simulators are currently supported:

If no filename is given, the stored layout name will be used and the file will be written to the current folder.

Physical Simulation of SiDBs

Performing physical simulation of SiDB layouts is crucial for understanding layout behavior and facilitating rapid prototyping, eliminating the need for expensive and time-intensive fabrication processes. The command read --sqd (or read -s) is used to import a SiDB layout from an sqd-file, a format compatible with SiQAD. The SiDB layout can be visualized using the print -c command. Currently, fiction provides three electrostatic physical simulators: the two exact ones: QuickExact and ClusterComplete, and the scalable one QuickSim.

QuickExact (quickexact)

QuickExact serves as an exact simulator, meticulously determining all physically valid charge distributions. It enumerates all possible charge distributions. However, by incorporating three techniques, namely 1.) Physically-informed Search Space Pruning, 2.) Partial Solution Caching, and 3.) Effective State Enumeration, it provides a significant performance advantage of more than three orders of magnitude over ExGS from SiQAD. For additional details, see the paper.

Most important parameters:

  • Relative permittivity \(\epsilon_r\) (-e)

  • Thomas-Fermi screening length \(\lambda_{tf}\) (-l)

  • Energy transition level (0/-) \(\mu_-\) (-m)

See quickexact -h for a full list.

The simulated ground state charge distribution can be printed with print -c.

ClusterComplete (clustercomplete)

ClusterComplete too serves as an exact simulator in much the same way as QuickExact, yet it introduces a new dimension of scalability for the purpose of SiDB logic simulation. For the first time, it enables exact simulation of layouts with multiple gates in base 3, incorporating efficient consideration of positive charges. Similar to QuickExact, it considers all possible charge distributions, though through intricate analysis of bounds on local potentials, it is able to prune charge assignments to clusters of SiDBs in a hierarchy, thus providing scalability to exact simulation of SiDB logic to an extent that was previously thought to be impossible.

Most important parameters:

  • Relative permittivity \(\epsilon_r\) (-e)

  • Thomas-Fermi screening length \(\lambda_{tf}\) (-l)

  • Energy transition level (0/-) \(\mu_-\) (-m)

  • Witness partitioning limits (-w, -o)

  • Report pruning statistics (-r)

See clustercomplete -h for a full list.

Pruning statistics may be useful to optimise the efficacy of the first pruning stage with the witness partitioning limits to save time on time intensive simulation problems. These statistics can also provide an indication for the complexity of the remaining problem that is solved in the second stage. Thus, through experience with ClusterComplete and these statistics, the expected time required to terminate may be gauged.

The simulated ground state charge distribution can be printed with print -c.

QuickSim (quicksim)

QuickSim serves as a scalable simulator designed to determine the ground state charge distribution for a given SiDB layout. To enhance efficiency, effective search space pruning techniques, such as (max-min diversity distributions), are integrated. For more in-depth information, refer to the paper.

Most important parameters:

  • Relative permittivity \(\epsilon_r\) (-e)

  • Thomas-Fermi screening \(\lambda_{tf}\) (-l)

  • Energy transition level (0/-) \(\mu_-\) (-m)

  • Number of iterations (-i)

  • \(\alpha\) value (-a)

The simulated ground state charge distribution can be printed with print -c.

Critical Temperature (temp)

The critical temperature of an SiDB layout is the temperature at which the layout’s ground state is populated with a probability larger than a certain threshold. This threshold is specified as a confidence level \(1 - \eta\), where \(\eta \in [0,1]\). The simulation can be conducted for gate-based SiDB layouts as well, where the gate is simulated with respect to the stability of a given Boolean function in form of the current truth table in store. For more in-depth information, refer to the paper.

Most important parameters:

  • Confidence level \(1 - \eta\) (-c)

  • Maximum temperature in K to explore (-t)

  • Gate-based simulation toggle (-g)

  • Relative permittivity \(\epsilon_r\) (-e)

  • Thomas-Fermi screening \(\lambda_{tf}\) (-l)

  • Energy transition level (0/-) \(\mu_-\) (-m)

  • SiDB simulation engine to use (--engine)

Operational Domain (opdom)

Computes the operational domain of the current SiDB cell-level layout in store. The operational domain is the set of all parameter combinations for which the layout is logically operational. Logical operation is defined as the layout implementing the current truth table in store. The input BDL pairs of the layout are assumed to be in the same order as the inputs of the truth table. For more information, see the paper.

The command opdom writes the operational domain to a CSV file with the given filename from where it can be further processed by other tools.

The parameter space to sweep over can be specified by the user via the flags - --x_sweep - --y_sweep - --z_sweep which have to be either epsilon_r, lambda_tf, or mu_minus. The default is epsilon_r for --x_sweep and lambda_tf for --y_sweep, with --z_sweep being an optional third sweep dimension.

Additionally, min, max, and step size values can be specified for each parameter using the flags - --x_min - --x_max - --x_step - --y_min - --y_max - --y_step - --z_min - --z_max - --z_step respectively. The default values are 1, 10, and 0.1 on x and y axis, for min, max, and step, respectively. The z axis is not used by default. However, if --z_sweep is specified, the default values are -0.5, -0.1, and 0.025 for min, max, and step, respectively, assuming z to be used for mu_minus.

By default, grid search is applied to explore the operational domain. The algorithm can be changed by specifying one of the following options: - --random_sampling/-r - --flood_fill/-f - --contour_tracing/-c each of which start from a set of random samples, whose number has to be passed as an argument to the flag.

Operational domain calculation may be powered by QuickExact, ClusterComplete, ExGS or QuickSim. The simulation engine to use can be set with --engine.

See opdom -h for a full list of arguments.

Area usage (area)

Based on the physical implementation, the actual size of a single FCN cell changes. Therefore, dimensions are typically given in abstract tiles and cells. If one however desires physical measures, command area can provide these. Given width and height of a single cell as well as horizontal and vertical spacing (each in nm), the area of a cell_layout is printed in nm².

If no information about such values is given, fiction uses default technology-depended lengths taken from QCADesigner, NMLSim, or SiQAD, respectively. These are

QCA (default QCADesigner settings)

  • width = 18nm

  • height = 18nm

  • hspace = 2nm

  • vspace = 2nm

iNML (default NMLSim settings)

  • width = 50nm

  • height = 100nm

  • hspace = 10nm

  • vspace = 10nm

SiDB (default SiQAD settings)

  • width = 0nm

  • height = 0nm

  • hspace = 0.384nm

  • vspace = 0.384nm

SVG export (show -c)

QCA cell-level layouts can be exported as scalable vector graphics (.svg files) using the command show -c. This will immediately open your standard SVG program to give a more sophisticated visual representation of the current cell layout in store. If one wants to just generate the SVG file without opening it in the standard viewer, show -c <filename>.svg --silent can be used.

Alternatively, open the exported file with a different program by using show -c --program "\"google-chrome\" {}" for instance to open it with the Chrome browser. Note that this behavior is platform-dependent and might not properly work under every system. For more information see show -h or the full alice documentation.

The used color scheme is based on the one known from QCADesigner.

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.

Benchmarking and scripting

All design steps explained in the previous sections can also be specified within a single fiction script file like the following called c17_synth.fs:

read ../benchmarks/ISCAS85/c17.v -t
exact -xbs 2ddwave
ps -g
cell
show -c
exact -ds use
ps -g
cell
show -c

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. The following table presents possible results.

Results

exact -xbs 2ddwave

exact -ds use
_images/compare1.png
_images/compare2.png

c17 (2DDWAVE) - 5 × 7, I/O: 5/2, gates: 8, wires: 28, CP: 11, TP: 1/1, sync. elems.: 0

c17 (USE) - 4 × 7, I/O: 5/2, gates: 8, wires: 16, CP: 14, TP: 1/3, sync. elems.: 0

These scripts can also be nested. One can use < script.fs within a fiction script to load script.fs in that very position. A script called shortcuts.fs has been placed in the top level folder. It can be loaded on start-up by calling ./fiction -if ../shortcuts.fs in the build folder. This makes predefined commands and flows available as shortcuts. Try synth -xibs use for instance to perform the whole flow of design (utilizing USE clocking) and physical synthesis down to cell-level including visual representation.

Additionally, fiction itself can be part of a bash script. Consider the following snippet:

for filepath in ../benchmarks/TOY/*.v; do
    f="${filepath##*/}"
   ./fiction -c "read $filepath; ortho; cell; qca ${f%.*}.qca"
done

where the for-loop iterates over all Verilog files in the ../benchmarks/TOY/ folder. By using the flag -c, a semicolon-separated list of commands can be passed to fiction. In this case, the files are to be read in a store, designed using the ortho algorithm, synthesized to cell-level, and written as QCA using their original file name.