\chapter{Using ScaffCC}\label{ch:usage}

\section{Running the Compiler}
To run the compiler, simply use the `scaffold.sh' script in the main directory, with the name of the program and optional compiler flags.

\subsection{Basic Example:}

The command below runs the compiler with default options on the Binary Welded Tree algorithm, with n=100 and s=100 as problem sizes.
The default compiler option is to generate resource estimations (number of qubits and gates).

\begin{lstlisting}
./scaffold.sh Algorithms/Binary Welded Tree/Binary_Welded_Tree_n100s100.scaffold
\end{lstlisting}


\section{Compiler Options}
To see a list of compiler options which can be passed as flags, run:

\begin{lstlisting}
./scaffold.sh -h

Usage: ./scaffold.sh [-hv] [-rqfRFckdso] [-l #] [-P #] <filename>.scaffold
    -r   Generate resource estimate (default)
    -q   Generate QASM
    -f   Generate flattened QASM
    -R   Disable rotation decomposition
    -T   Disable Toffoli decomposition
    -l   Levels of recursion to run (default=1)
    -P   Set precision of rotation decomposition in decimal digits (default=10)
    -F   Force running all steps
    -c   Clean all files (no other actions)
    -k   Keep all intermediate files (default only keeps specified output,
         but requires recompilation for any new output)
    -d   Dry-run; show all commands to be run, but do not execute
    -s   Generate QX Simulator input file 
    -o   Generate optimized QASM
    -v   Show current ScaffCC version
\end{lstlisting}



\section{Sample Scripts}
This section describes some of the example scripts contained in the `scripts/' directory. They are written to test the various functionalities 
of ScaffCC, as detailed below.

Each of them automates the process of running multiple compiler passes on an input file to perform the required analysis or optimization.


\subsection{Generating LLVM Intermediate Format: ./gen-ll.sh}

Lowers .scaffold source file to .ll file (intermediary LLVM format). Creates \textless algorithm\textgreater.ll
The .ll file is the main file in LLVM on which all transformations, optimizations and analysis are performed.


\subsection{Critical Path Estimation: ./gen-cp.sh}

Finds critical path information for several different flattening thresholds by doing the following:
\begin{enumerate}
\item Finding module sizes using the ResourceCount2 pass.
\item Flattening modules based on the found module sizes and the requested threshold.
\item Finds length of critical path, in terms of number of operations on it. Look for the number in front of "main" in the output. 
\end{enumerate}

\subsubsection{flattening\_thresh.py} 
Divides modules into different buckets based on their size, to be used for flattening decision purposes.


\subsection{Module Call Frequency Estimation: ./gen-freq-estimate.sh}
Generates an estimate of how many times each module is called, which can guide flattening decisions.


\subsection{Generate Longest-Path-First-Schedule (LPFS): ./gen-lpfs.sh}
Generates LPFS schedules with different options as specified below.

Options in the script: 
  K=number of SIMD regions / D=capacity of each region / th=flattening thresholds

Calls the following scripts:
  
  \subsubsection{./regress.sh}
  
  Runs the 3 different communication-aware schedulers, LPFS, RCP, SS, with different scheduler configurations.
  Look in ./sched.pl for configuration options. For example using -m gives metrics only, while -s outputs entire schedule.

  \subsubsection{./sched.pl}
  The main scheduler code for LPFS and RCP.

  \subsubsection{./comm\_aware.pl}
  Applies the communication penalty to timesteps.

All output files are placed in a new directory to avoid cluttering.

\subsection{Rotation Generator: gen\_rotation/}

This is a C++ implemetation of the library construction method for generating Rz rotations. The main features of this generator include: 
\begin{itemize}
\item Powered by gridsynth, the package can generate rotation sequences that approximate arbitrary $Rz$ angles, up to given precision. 
\item Generate libraries of rotation sequences given use-defined precision and storage requirements, trading storage for execution time. 
\item Dynamically concatenate rotation sequences at run time using generated libraries.
\end{itemize}
Detailed description and usage can be found in the subdirectory scripts/gen\_rotations/.


\subsection{Test Correctness of RKQC Programs: RKQCVerifier/}

RKQCVerifier is a tool that helps verify the correctness of RKQC applications. For detailed description and usage, please refer to the subdirectory scripts/RKQCVerifier/.

\subsection{Braidflash}

Braidflash is a software for efficient simulation of braids in the context of surface error correction of quantum applications. For further explanation and to cite this tool, please refer to the following publication:

\begin{quote}
A. Javadi-Abhari, P. Gokhale, A. Holmes, D. Franklin, K. R. Brown, M. R. Martonosi, F. T. Chong, {\em``Optimized Surface Code Communication in Superconducting Quantum Computers,"} IEEE/ACM MICRO, Cambridge, MA, 2017
\end{quote}

Detailed description and usage can be found in the subdirectory braidflash/.