\chapter{Validation of the Approach}
Our proposed approach is validated by running it through three data sets based off of the data sets used by Hasda, R., Bhattacharjya, R., and Bennis, F. (2017) \cite{Hasda2017}, and Lee, Y., and Lee, M. \cite{Lee2002} that will test its performance and compare it to a genetic algorithm-based approach. Basing from previous studies, the fitness of the solution produced by an approach determines the performance of an algorithm. As such, we will be comparing the average fitness values of our approach and two competing approaches, a modified genetic algorithm approach, and a particle swarm optimization-based approach. 30 feasible solutions are obtained with each approach and data set, and the fitnesses obtained in each run are averaged. Note that, however, only the fitnesses of feasible solutions are included in the average. Due to the non-deterministic nature of metaheuristics, infeasible solutions are bound to be generated.

\section{Data Sets Used}
Let us call the data sets used as problem configuration. The first two problem configurations are based off of the configurations used by Hasda, R., Bhattacharjya, R., and Bennis, F. (2017) \cite{Hasda2017}. The first configuration used, which we will call SFLP-II, is shown in Table \ref{dataset-sflp-ii}, contains 8 buildings, and the second configuration, which we will call mSFLP-III, is shown in Table \ref{dataset-msflp-iii}, contains 20 buildings. The second configuration is called as such due to the fact that it is a modification of the third problem configuration used by Hasda, R., Bhattacharjya, R., and Bennis, F.. SFLP-II uses a 12x12 bounding region, while mSFLP-III uses a 260x260 bounding region. The third configuration, which we will call mKra30a, is shown in Table \ref{dataset-mkra30a}, contains 30 buildings. The configuration consists of modified building dimension data from the 30-building data set by Lee, Y., and Lee, M. \cite{Lee2002} and cost data from the Kra30a data set in QAPLIB \cite{QAPLib}. A 250x250 bounding region is used for the data set.

\begin{table}[h!]
\centering
\begin{tabular}{P{7mm}|P{7mm}|P{7mm}|P{7mm}|P{7mm}|P{7mm}|P{7mm}|P{7mm}|P{7mm}|P{7mm}|P{7mm}|}
	\cline{2-11}
	& \multicolumn{8}{c|}{Cost of Material Flow Between Buildings} & W & H \\ \cline{1-9}
	\multicolumn{1}{|l|}{Building} & 1     & 2     & 3     & 4     & 5     & 6     & 7     & 8    &       &        \\ \hline
	\multicolumn{1}{|l|}{1}        & 0     & 1     & 2     & 0     & 0     & 0     & 2     & 0    & 2     & 3      \\ \hline
	\multicolumn{1}{|l|}{2}        & 0     & 0     & 4     & 3     & 6     & 0     & 0     & 2    & 4     & 5      \\ \hline
	\multicolumn{1}{|l|}{3}        & 0     & 0     & 0     & 2     & 0     & 3     & 1     & 0    & 2     & 2      \\ \hline
	\multicolumn{1}{|l|}{4}        & 0     & 0     & 0     & 0     & 5     & 2     & 0     & 2    & 3     & 3      \\ \hline
	\multicolumn{1}{|l|}{5}        & 0     & 0     & 0     & 0     & 0     & 0     & 0     & 4    & 2     & 4      \\ \hline
	\multicolumn{1}{|l|}{6}        & 0     & 0     & 0     & 0     & 0     & 0     & 4     & 0    & 4     & 4      \\ \hline
	\multicolumn{1}{|l|}{7}        & 0     & 0     & 0     & 0     & 0     & 0     & 0     & 1    & 4     & 4      \\ \hline
	\multicolumn{1}{|l|}{8}        & 0     & 0     & 0     & 0     & 0     & 0     & 0     & 0    & 3     & 4      \\ \hline
\end{tabular}
\caption{Configuration of SFLP-II. W and H mean width and height, respectively.}
\label{dataset-sflp-ii}
\end{table}

\begin{table}
\begin{adjustwidth}{-0.85in}{}
\begin{tabular}{P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|P{3mm}|}
	\cline{2-23}
	& \multicolumn{20}{c|}{Cost of Material Flow Between Buildings}                            & W & H \\ \cline{1-21}
	\multicolumn{1}{|l|}{Building} & 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 & 10 & 11 & 12 & 13 & 14 & 15 & 16 & 17 & 18 & 19 & 20 &       &        \\ \hline
	\multicolumn{1}{|l|}{1}        & 0 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 20    & 40     \\ \hline
	\multicolumn{1}{|l|}{2}        & 1 & 0 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 40    & 40     \\ \hline
	\multicolumn{1}{|l|}{3}        & 1 & 1 & 0 & 1 & 1 & 1 & 1 & 1 & 1 & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 20    & 20     \\ \hline
	\multicolumn{1}{|l|}{4}        & 1 & 1 & 1 & 0 & 1 & 1 & 1 & 1 & 1 & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 40    & 60     \\ \hline
	\multicolumn{1}{|l|}{5}        & 1 & 1 & 1 & 1 & 0 & 1 & 1 & 1 & 1 & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 60    & 60     \\ \hline
	\multicolumn{1}{|l|}{6}        & 1 & 1 & 1 & 1 & 1 & 0 & 1 & 1 & 1 & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 40    & 40     \\ \hline
	\multicolumn{1}{|l|}{7}        & 1 & 1 & 1 & 1 & 1 & 1 & 0 & 1 & 1 & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 40    & 20     \\ \hline
	\multicolumn{1}{|l|}{8}        & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 0 & 1 & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 40    & 60     \\ \hline
	\multicolumn{1}{|l|}{9}        & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 0 & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 60    & 40     \\ \hline
	\multicolumn{1}{|l|}{10}       & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 0  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 60    & 60     \\ \hline
	\multicolumn{1}{|l|}{11}       & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1  & 0  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 40    & 60     \\ \hline
	\multicolumn{1}{|l|}{12}       & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1  & 1  & 0  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 20    & 40     \\ \hline
	\multicolumn{1}{|l|}{13}       & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1  & 1  & 1  & 0  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 60    & 40     \\ \hline
	\multicolumn{1}{|l|}{14}       & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1  & 1  & 1  & 1  & 0  & 1  & 1  & 1  & 1  & 1  & 1  & 60    & 60     \\ \hline
	\multicolumn{1}{|l|}{15}       & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1  & 1  & 1  & 1  & 1  & 0  & 1  & 1  & 1  & 1  & 1  & 60    & 60     \\ \hline
	\multicolumn{1}{|l|}{16}       & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1  & 1  & 1  & 1  & 1  & 1  & 0  & 1  & 1  & 1  & 1  & 40    & 40     \\ \hline
	\multicolumn{1}{|l|}{17}       & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 0  & 1  & 1  & 1  & 60    & 40     \\ \hline
	\multicolumn{1}{|l|}{18}       & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 0  & 1  & 1  & 40    & 40     \\ \hline
	\multicolumn{1}{|l|}{19}       & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 0  & 1  & 40    & 40     \\ \hline
	\multicolumn{1}{|l|}{20}       & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 1  & 0  & 40    & 20     \\ \hline
\end{tabular}
\end{adjustwidth}
\caption{Configuration of mSFLP-III.}
\label{dataset-msflp-iii}
\end{table}

\begin{table}[h!]
\centering
\begin{adjustwidth}{0.3in}{}
\resizebox{0.85\textwidth}{!}{\rotatebox{90}{
\begin{tabular}{l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|}
	\cline{2-33}
	& \multicolumn{30}{c|}{Cost of Material Flow Between Buildings}         					  & W & H \\ \cline{1-31} \multicolumn{1}{|l|}{Building} & 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 & 10 & 11 & 12 & 13 & 14 & 15 & 16 & 17 & 18 & 19 & 20 & 21 & 22 & 23 & 24 & 25 & 26 & 27 & 28 & 29 & 30 &  &     \\ \hline
	\multicolumn{1}{|l|}{1}                                     & 0 & 2 & 2 & 2 & 2 & 2 & 2  & 2 & 3 & 0  & 3  & 2  & 0  & 0  & 0  & 3  & 3  & 0  & 0  & 2  & 1  & 2  & 1  & 1  & 0  & 3  & 0  & 0  & 0  & 0  & 56                 & 43                  \\
	\hline
	\multicolumn{1}{|l|}{2}                                     & 2 & 0 & 2 & 2 & 3 & 2 & 3  & 2 & 0 & 0  & 2  & 1  & 0  & 0  & 2  & 3  & 3  & 0  & 0  & 2  & 1  & 2  & 1  & 1  & 0  & 3  & 0  & 0  & 0  & 0  & 37                 & 43                  \\
	\hline
	\multicolumn{1}{|l|}{3}                                     & 2 & 2 & 0 & 2 & 2 & 3 & 0  & 0 & 0 & 0  & 2  & 2  & 0  & 0  & 2  & 3  & 3  & 0  & 0  & 2  & 1  & 2  & 1  & 1  & 0  & 3  & 0  & 0  & 0  & 0  & 78                 & 47                  \\
	\hline
	\multicolumn{1}{|l|}{4}                                     & 2 & 2 & 2 & 0 & 0 & 2 & 2  & 3 & 1 & 0  & 0  & 2  & 1  & 0  & 0  & 4  & 3  & 0  & 0  & 2  & 1  & 2  & 1  & 1  & 0  & 3  & 0  & 0  & 0  & 0  & 40                 & 20                  \\
	\hline
	\multicolumn{1}{|l|}{5}                                     & 2 & 3 & 2 & 2 & 0 & 2 & 3  & 2 & 0 & 0  & 2  & 1  & 0  & 0  & 2  & 3  & 3  & 0  & 0  & 2  & 1  & 2  & 1  & 1  & 0  & 3  & 0  & 0  & 0  & 0  & 42                 & 50                  \\
	\hline
	\multicolumn{1}{|l|}{6}                                     & 2 & 2 & 3 & 2 & 2 & 0 & 0  & 0 & 0 & 0  & 2  & 2  & 0  & 0  & 2  & 3  & 3  & 0  & 0  & 2  & 1  & 2  & 1  & 1  & 0  & 3  & 0  & 0  & 0  & 0  & 50                 & 35                  \\
	\hline
	\multicolumn{1}{|l|}{7}                                     & 2 & 3 & 0 & 3 & 3 & 0 & 0  & 4 & 4 & 3  & 3  & 0  & 4  & 0  & 0  & 2  & 2  & 0  & 0  & 3  & 4  & 1  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 20                 & 18                  \\
	\hline
	\multicolumn{1}{|l|}{8}                                     & 2 & 2 & 0 & 1 & 2 & 0 & 4  & 0 & 0 & 0  & 0  & 2  & 0  & 0  & 0  & 3  & 3  & 0  & 0  & 3  & 1  & 1  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 40                 & 39                  \\
	\hline
	\multicolumn{1}{|l|}{9}                                     & 3 & 0 & 0 & 0 & 0 & 0 & 4  & 0 & 0 & 0  & 0  & 1  & 4  & 0  & 0  & 2  & 2  & 0  & 0  & 2  & 0  & 1  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 40                 & 50                  \\
	\hline
	\multicolumn{1}{|l|}{10}                                    & 0 & 0 & 0 & 0 & 0 & 0 & 3  & 0 & 0 & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 1  & 1  & 0  & 0  & 0  & 0  & 4  & 0  & 0  & 40                 & 49                  \\
	\hline
	\multicolumn{1}{|l|}{11}                                    & 3 & 2 & 2 & 2 & 2 & 2 & 3  & 0 & 0 & 0  & 0  & 3  & 4  & 0  & 0  & 3  & 3  & 0  & 0  & 0  & 1  & 2  & 0  & 0  & 0  & 2  & 0  & 0  & 0  & 0  & 40                 & 40                  \\
	\hline
	\multicolumn{1}{|l|}{12}                                    & 2 & 1 & 2 & 1 & 1 & 2 & 0  & 2 & 1 & 0  & 3  & 0  & 3  & 0  & 0  & 1  & 1  & 0  & 0  & 0  & 0  & 2  & 2  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 32                 & 28                  \\
	\hline
	\multicolumn{1}{|l|}{13}                                    & 0 & 0 & 0 & 0 & 0 & 0 & 4  & 0 & 4 & 0  & 4  & 3  & 0  & 4  & 0  & 3  & 3  & 0  & 0  & 2  & 1  & 1  & 1  & 0  & 0  & 0  & 0  & 4  & 0  & 0  & 30                 & 30                  \\
	\hline
	\multicolumn{1}{|l|}{14}                                    & 0 & 0 & 0 & 0 & 0 & 0 & 0  & 0 & 0 & 0  & 0  & 0  & 4  & 0  & 0  & 0  & 0  & 4  & 0  & 0  & 0  & 1  & 0  & 0  & 0  & 3  & 0  & 0  & 0  & 0  & 50                 & 50                  \\
	\hline
	\multicolumn{1}{|l|}{15}                                    & 0 & 2 & 2 & 4 & 2 & 2 & 0  & 0 & 0 & 0  & 0  & 0  & 0  & 0  & 0  & 1  & 1  & 0  & 0  & 0  & 0  & 2  & 0  & 0  & 0  & 3  & 0  & 2  & 0  & 0  & 20                 & 20                  \\
	\hline
	\multicolumn{1}{|l|}{16}                                    & 3 & 3 & 3 & 3 & 3 & 3 & 2  & 3 & 2 & 0  & 3  & 1  & 3  & 0  & 1  & 0  & 5  & 2  & 0  & 0  & 0  & 1  & 0  & 0  & 0  & 2  & 0  & 0  & 0  & 0  & 17                 & 18                  \\
	\hline
	\multicolumn{1}{|l|}{17}                                    & 3 & 3 & 3 & 3 & 3 & 3 & 2  & 3 & 2 & 0  & 3  & 1  & 3  & 0  & 1  & 4  & 0  & 2  & 0  & 0  & 0  & 1  & 0  & 0  & 0  & 2  & 0  & 0  & 0  & 0  & 20                 & 20                  \\
	\hline
	\multicolumn{1}{|l|}{18}                                    & 0 & 0 & 0 & 0 & 0 & 0 & 0  & 0 & 0 & 0  & 0  & 0  & 0  & 4  & 0  & 2  & 2  & 0  & 0  & 0  & 0  & 1  & 0  & 0  & 2  & 4  & 4  & 0  & 0  & 0  & 30                 & 30                  \\
	\hline
	\multicolumn{1}{|l|}{19}                                    & 0 & 0 & 0 & 0 & 0 & 0 & 0  & 0 & 0 & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 2  & 0  & 25                 & 18                  \\
	\hline
	\multicolumn{1}{|l|}{20}                                    & 2 & 2 & 2 & 2 & 2 & 2 & 3  & 3 & 2 & 0  & 0  & 0  & 2  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 1  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 3  & 0  & 31                 & 16                  \\
	\hline
	\multicolumn{1}{|l|}{21}                                    & 1 & 1 & 1 & 1 & 1 & 1 & 4  & 1 & 0 & 0  & 1  & 0  & 1  & 0  & 0  & 0  & 0  & 0  & 0  & 1  & 0  & 1  & 2  & 0  & 0  & 0  & 0  & 0  & 4  & 0  & 43                 & 37                  \\
	\hline
	\multicolumn{1}{|l|}{22}                                    & 2 & 2 & 2 & 2 & 2 & 2 & 1  & 1 & 1 & 1  & 2  & 2  & 1  & 1  & 2  & 1  & 1  & 1  & 0  & 0  & 1  & 0  & 1  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 32                 & 28                  \\
	\hline
	\multicolumn{1}{|l|}{23}                                    & 1 & 1 & 1 & 1 & 1 & 1 & 0  & 0 & 0 & 1  & 0  & 2  & 1  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 2  & 1  & 0  & 0  & 0  & 0  & 0  & 0  & 4  & 0  & 30                 & 30                  \\
	\hline
	\multicolumn{1}{|l|}{24}                                    & 1 & 1 & 1 & 1 & 1 & 1 & 0  & 0 & 0 & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 2  & 0  & 0  & 0  & 4  & 0  & 52                 & 48                  \\
	\hline
	\multicolumn{1}{|l|}{25}                                    & 0 & 0 & 0 & 0 & 0 & 0 & 0  & 0 & 0 & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 2  & 0  & 0  & 0  & 0  & 0  & 2  & 0  & 4  & 0  & 0  & 0  & 0  & 20                 & 20                  \\
	\hline
	\multicolumn{1}{|l|}{26}                                    & 3 & 3 & 3 & 3 & 3 & 3 & 0  & 0 & 0 & 0  & 2  & 0  & 0  & 3  & 3  & 2  & 2  & 4  & 0  & 0  & 0  & 0  & 0  & 0  & 5  & 0  & 0  & 0  & 0  & 4  & 17                 & 18                  \\
	\hline
	\multicolumn{1}{|l|}{27}                                    & 0 & 0 & 0 & 0 & 0 & 0 & 0  & 0 & 0 & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 4  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 20                 & 20                  \\
	\hline
	\multicolumn{1}{|l|}{28}                                    & 0 & 0 & 0 & 0 & 0 & 0 & 0  & 0 & 0 & 4  & 0  & 0  & 4  & 0  & 2  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 30                 & 30                  \\
	\hline
	\multicolumn{1}{|l|}{29}                                    & 0 & 0 & 0 & 0 & 0 & 0 & 0  & 0 & 0 & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 2  & 3  & 4  & 0  & 4  & 4  & 0  & 0  & 0  & 0  & 0  & 0  & 22                 & 21                  \\
	\hline
	\multicolumn{1}{|l|}{30}                                    & 0 & 0 & 0 & 0 & 0 & 0 & 00 & 0 & 0 & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 0  & 4  & 0  & 0  & 0  & 0  & 18                 & 28                  \\
	\hline
\end{tabular}}}
\end{adjustwidth}
\caption{Configuration of mKra30a. W and H mean width and height, respectively.}
\label{dataset-mkra30a}
\end{table}

\section{Competing Approaches}
In order for us to properly gauge the performance of our GWO approach for the unequal area static facility layout problem, we will be solving the problem configurations using two other approaches: (1) a modified genetic algorithm approach, and a particle swarm optimization-based approach. These two were chosen due to their popularity in solving facility layout problems \cite{Hosseini-Nasab2018}.

\subsection{Modified Genetic Algorithm Approach}
The competing GA approach, which we will compare our proposed GWO approach, contains multiple phases to solve the unequal area static facility layout problem. The basic framework of the algorithm is inspired from the works of Asl et al. (2015) \cite{Asl2015} and Asl, A. and Wong, K. (2015) \cite{Asl2015a}. We will be further discussing the algorithm in detail in this section.

\subsubsection{Population Generation}
In the competing GA approach, the population generation is the same the method for initialization the population as the one in our proposed modified GWO approach.

\subsubsection{Swapping Method}
The swapping method is used to find a possible configuration for a solution that is better than the current configuration. This method is applied to all solutions in the population, but only in the first 100 iterations. Pseudocode for the swapping method is provided in Algorithm \ref{pseudocode-comp-ga-swapping}.

\begin{algorithm}
\caption{Pseudocode for the swapping method.}
\label{pseudocode-comp-ga-swapping}
\begin{algorithmic}[1]
\State Let $S$ be the collection of generated solutions.
\State Set $S_{curr}$ be the current solution.
\State Add $S_{curr}$ to $S$.
\State Set $N_{B}$ be the maximum number of buildings.
\For{i = 0 until $N_{B} - 2$}
	\For{j = i + 1 until $N_{B} - 1$}
		\State Building $i$'s orientation in $S_{curr}$ is changed to the other orientation,\WRP and the resulting new solution is added to $S$
		\State Building $j$'s orientation in $S_{curr}$ is changed to the other orientation,\WRP and the resulting new solution is added to $S$
		\State Building $i$'s and $j$'s orientations in $S_{curr}$ are changed to the other\WRP orientation, and the resulting new solution is added to $S$
		\State Building $i$'s and $j$'s positions are exchanged in $S_{curr}$, and the resulting new\WRP solutiA movement and a orientation changeon is added to $S$.
		\State Building $i$'s and $j$'s positions are exchanged in and the orientation of\WRP building $i$ is changed in $S_{curr}$, and the resulting new solution\WRP is added to $S$.
		\State Building $i$'s and $j$'s positions are exchanged in and the orientation of\WRP building $j$ is changed in $S_{curr}$, and the resulting new solution\WRP is added to $S$.
		\State Building $i$'s and $j$'s positions are exchanged in and the orientations of\WRP buildings $i$ and $j$ are changed in $S_{curr}$, and the resulting new solution\WRP is added to $S$.
	\EndFor
\EndFor \\
\Return the best solution in $S$.
\end{algorithmic}
\end{algorithm}

\subsubsection{Selection, Crossover, Mutation, and Elitism}
Key parts of a genetic algorithm are the selection, crossover, and mutation operators. These drive the algorithm to produce good solutions. We will be discussing each operator used in detail in this section. Elitism is also implemented in our proposed approach to ensure that the best solutions found so far do not get lost throughout iterations. It will also be discussed in this section.

\paragraph{Selection}
The selection operator used in the competing approach is tournament selection. Tournament selection works by selecting $k$ (also known as tournament size) individuals from a population and using the best two selected individuals as parents for an offspring \cite{StackOverflow-TournamentSelection}. Algorithm \ref{pseudocode-tournament-selection} shows a pseudocode of tournament selection. Note that in the algorithm, $P_{p}$ denotes the $p$-th solution in $P$, and $|P|$ denotes the population size.

\begin{algorithm}
\caption{Pseudocode for the tournament selection.}
\label{pseudocode-tournament-selection}
\begin{algorithmic}[1]
\State Set $X^{(1)}$ to be the first best parent.
\State Set $X^{(2)}$ to be the second best parent.
\State Set $P$ to be the population of solutions.
\State Set $k$ to be the tournament size.
\State Set $f(X)$ to be the fitness function.
\State $X^{(1)} = \text{null}$
\State $X^{(2)} = \text{null}$
\For{$i = 1, 2,\ldots,k$}
	\State $p = U(1, |P|)$
	\If{$X^{(1)}== \text{null}$ or $f(P_{p}) < f(X^{(1)}$}
		\State $X_{(2)} = X^{(1)}$
		\State $X_{(1)} = P_{p}$
	\ElsIf{$X^{(2)}== \text{null}$ or $f(P_{p}) < f(X^{(2)}$}
		\State $X_{(2)} = P_{p}$
	\EndIf
\EndFor \\
\Return $X^{(1)}$, and $X^{(2)}$.
\end{algorithmic}
\end{algorithm}

\paragraph{Crossover}
The crossover operator used in the competing approach is uniform crossover. Uniform crossover works by selecting a gene from a random parent and placing it in the offspring. This is applied for every gene in the offspring. Algorithm \ref{pseudocode-uniform-crossover} shows a pseudocode of uniform crossover.

\begin{algorithm}
\caption{Pseudocode for the uniform crossover.}
\label{pseudocode-uniform-crossover}
\begin{algorithmic}[1]
\State Set $X$ to be the offspring.
\State Set $N$ to be the number of genes a solution has.
\State Set $X^{(1)}$ to be the first parent.
\State Set $X^{(2)}$ to be the second parent.
\For{$i = 1, 2,\ldots, N$}
	\State $\text{rand} = U(0, 1)$
	\If{$\text{rand} < 0.5$}
		\State $X_{i} = X^{(1)}_{i}$
	\Else
		\State $X_{i} = X^{(2)}_{i}$
	\EndIf
\EndFor \\
\Return $X$.
\end{algorithmic}
\end{algorithm}

\paragraph{Mutation}
Over time, as more and more iterations are performed, the diversity of the population will eventually be lost. To combat this, a mutation operator is performed to reintroduce diversity. The mutation operator used is an operator that we dub the "Buddy-Buddy Mutation".

The \textbf{Buddy-Buddy Mutation} is a mutation operator that simply selects two pairs of buildings $D$ and $S$, and move one of them to the side of the other building. Building $D$ is referred to as the dynamic buddy, while building $S$ is referred to as the static buddy. Building $D$ will be the building that will be moved towards the other building, which is building $S$ in our case. When moving building $D$, a side $E$ of building $S$ will first be randomly chosen. Afterwards, an orientation for building $D$ will be randomly chosen, whether it will be parallel or perpendicular to $E$. Once a side and orientation has been selected, building $D$ will be moved adjacent towards building $S$ at side $E$ with the chosen orientation. The implementation of this mutation operator in our proposed approach gives buildings that intersect with another building more chances of being selected as the dynamic buddy. Pseudocode and a visualization of the operator is provided by Algorithm \ref{pseudocode-buddybuddy-mutation} and Figure \ref{buddy-buddy-mutation-viz}, respectively.

\begin{algorithm}
\caption{Pseudocode for the Buddy-Buddy Mutation.}
\label{pseudocode-buddybuddy-mutation}
\begin{algorithmic}[1]
	\State Randomly select two buildings $D$ and $S$, with more weight given to buildings that are intersecting with another.
	\State Set $E$ to be a randomly selected side of building $S$.
	\State Set $O$ to either be a parallel or perpendicular orientation, randomly selected.
	\State Move building $D$ adjacent to side $E$ of building $S$ with the orientation $O$.
\end{algorithmic}
\end{algorithm}

\begin{figure}[h!]
	\centering
	\includegraphics{./images/chap06-validation/buddy-buddy-mutation.png}
	\caption{Visualization of how Buddy-Buddy Mutation works. On the left are two buildings that are overlapping one another. The right shows the same buildings but with the mutation applied, causing them to no longer overlap. Note that the right shows only one possible arrangement for both buildings.}
	\label{buddy-buddy-mutation-viz}
\end{figure}

The rate at which a solution is mutated is highly dependent on the fitness of the solution. The worse the fitness of a solution is, the more likely it is to be mutated. This encourages the proposed algorithm to improve solutions that are generally bad. This rate scheme makes this an adaptive mutation operator \cite{Jiang2018}. The mutation rate is mathematically modelled as:

\begin{equation}
	m(X, t) = 1 - \frac{fit_{max}(t) - fit(X(t))}{fit_{max}(t) - fit_{min}(t)}
\end{equation}

where $m_{k}$ refers to the mutation rate of a solution $X$ at iteration $t$, $fit$ is a function that gets the fitness of a solution, and $fit_{min}$ and $fit_{max}$ gets the minimum and maximum fitnesses of the population, respectively.

\paragraph{Elitism}
One variant of genetic algorithms includes elitism. This elitism allows a genetic algorithm to keep a number of best solutions in the next generation, ensuring that the best solutions do not get discarded over time. Note that this elitism strategy is not only limited to genetic algorithms. Other evolutionary algorithms may also utilize this strategy \cite{Du2018}. We are also taking this principle into our competing GA approach. In the competing approach, we are keeping the best $E_{N}$ solutions in the previous iteration to the next iteration.

\subsubsection{Local Searches}
Remember that our implementation is based on aforementioned previous works that used local search algorithms in conjunction to genetic algorithms. They combined GAs with local search algorithms because GAs find it hard to explore within the convergence area. Hybridizing it with a local search algorithm improves performance \cite{Ripon2013}. In our proposed approach, we are keeping this aspect of the previous works. This will also ensure that we are able to search within the convergence area more intensely and find better solutions. In the previous works and in ours, there are two local search algorithms, dubbed "Local Search 1" and "Local Search 2". They vary in terms of searching intensity, but both attempts to obtain better solutions. We will be discussing details of both in this section.

\paragraph{Local Search 1}
The first local search algorithm, "Local Search 1", performs a local search by creating a number of solutions by moving each building in different directions by a certain random amount and changing its orientations after movement and obtaining the best solution from these activities. In our approach, the certain amount of movement is a random number between 1 and 5. This search algorithm is only applied to the best solution of the current iteration, and the best solution found in this search becomes the new best solution and replaces the previously best solution. The movements of each building is defined by a set of "activities". This set of activities is shown by Table \ref{local-search-1-activities}. Additionally, pseudocode of the search algorithm is shown in Algorithm \ref{pseudocode-local-search-1}.

\begin{table}[h!]
	\centering
	\begin{tabular}{| c | p{110mm} |}
		\hline
		Activity Number & Description \\
		\hline
		0 & A building is moved to the right along the x-axis by a random number between 1 and 5. \\
		1 & A building is moved to the left along the x-axis by a random number between 1 and 5. \\
		2 & A building is moved to the upwards along the y-axis by a random number between 1 and 5. \\
		3 & A building is moved to the downwards along the y-axis by a random number between 1 and 5. \\
		4 & Generate two random numbers from 1 and 5 and a building is moved to the right and then upward, respectively, by those numbers. \\
		5 & Generate two random numbers from 1 and 5 and a building is moved to the right and then downward, respectively, by those numbers. \\
		6 & Generate two random numbers from 1 and 5 and a building is moved to the left and then upward, respectively, by those numbers. \\
		7 & Generate two random numbers from 1 and 5 and a building is moved to the left and then downward, respectively, by those numbers. \\
		\hline
	\end{tabular}
	\caption{Activities for moving a building in Local Search 1}
	\label{local-search-1-activities}
\end{table}

\begin{algorithm}[h!]
\caption{Pseudocode for Local Search 1.}
\label{pseudocode-local-search-1}
\begin{algorithmic}[1]
\State Set $S$ to be a collection of solutions.
\State Set $S_{curr}$ to be the solution being optimized.
\State Add $S_{curr}$ to $S$.
\State Set $N_{B}$ be the maximum number of buildings.
\State Set $N_{A}$ be the maximum number of activities.
\For{i = 0 until $N_{B} - 1$}
	\For{a = 0 until $N_{B} - 1$}
		\State Perform activity $a$ with building $i$ in $S_{curr}$ and save the new solution in $S$.
		\State Perform activity $a$ with building $i$, and change the orientation of the building to the other orientation in $S_{curr}$ and save the new solution in $S$.
	\EndFor
\EndFor \\
\Return the best solution in $S$.
\end{algorithmic}
\end{algorithm}

\paragraph{Local Search 2}
Local Search 2 is a more intense version of Local Search 1, in order to find the best solution so far. Unlike the latter that only moves one building at a time, Local Search 2 moves two buildings instead. The two buildings will also have their orientations changed after each activity. This local search is only applied to the best solution found in the last 50 iterations. The set of activities for this local search is shown by Table \ref{local-search-2-activities}, and a pseudocode of the search algorithm is shown in Algorithm \ref{pseudocode-local-search-2}.

\begin{algorithm}[h!]
	\caption{Pseudocode for Local Search 2.}
	\label{pseudocode-local-search-2}
	\begin{algorithmic}[1]
		\State Set $S$ to be a collection of solutions.
		\State Set $S_{curr}$ to be the solution being optimized.
		\State Add $S_{curr}$ to $S$.
		\State Set $N_{B}$ be the maximum number of buildings.
		\State Set $N_{A}$ be the maximum number of activities.
		\For{i = 0 until $N_{B} - 2$}
		\For{a = 0 until $N_{B} - 1$}
		\State Perform activity $a$ with building $i$ in $S_{curr}$ and save the new solution in $S$.
		\State Perform activity $a$ with building $i$, and change the orientation of \WRP building $i$ to the other orientation in $S_{curr}$ and save the new \WRP solution in $S$.
		\State Perform activity $a$ with building $i$, and change the orientation of \WRP building $i + 1$ to the other orientation in $S_{curr}$ and save the new \WRP solution in $S$.
		\State Perform activity $a$ with building $i$, and change the orientations of \WRP buildings $i$ and $i + 1$ to the other orientations in $S_{curr}$ and save the new \WRP solution in $S$.
		\EndFor
		\EndFor \\
		\Return the best solution in $S$.
	\end{algorithmic}
\end{algorithm}

\begin{longtable}{| c | p{120mm} |}
	\hline
	Activity Number & Description \\
	\hline
	0  & Building $i$ and $i + 1$ are moved to the right along the x-axis by a random number between 1 and 5. \\
	1  & Building $i$ and $i + 1$ are moved to the left along the x-axis by a random number between 1 and 5. \\
	2  & Building $i$ and $i + 1$ are moved upwards along the x-axis by a random number between 1 and 5. \\
	3  & Building $i$ and $i + 1$ are moved downwards along the x-axis by a random number between 1 and 5. \\
	4  & Generate two random numbers from 1 and 5 and buildings $i$ and $i + 1$ are moved to the right and then upward, respectively, by those numbers. \\
	5  & Generate two random numbers from 1 and 5 and buildings $i$ and $i + 1$ are moved to the right and then downward, respectively, by those numbers. \\
	6  & Generate two random numbers from 1 and 5 and buildings $i$ and $i + 1$ are moved to the left and then upward, respectively, by those numbers. \\
	7  & Generate two random numbers from 1 and 5 and buildings $i$ and $i + 1$ are moved to the left and then downward, respectively, by those numbers. \\
	8  & Generate two random numbers $a$ and $b$ that are from 1 to 5, and building $i$ is moved upward by $a$ and building $i + 1$ is moved to the right by $b$. \\
	9  & Generate two random numbers $a$ and $b$ that are from 1 to 5, and building $i$ is moved upward by $a$ and building $i + 1$ is moved downward by $b$. \\
	10 & Generate two random numbers $a$ and $b$ that are from 1 to 5, and building $i$ is moved upward by $a$ and building $i + 1$ is moved to the left by $b$. \\
	11 & Generate two random numbers $a$ and $b$ that are from 1 to 5, and building $i$ is moved to the right by $a$ and building $i + 1$ is moved downward by $b$. \\
	12 & Generate two random numbers $a$ and $b$ that are from 1 to 5, and building $i$ is moved to the right by $a$ and building $i + 1$ is moved upward by $b$. \\
	13 & Generate two random numbers $a$ and $b$ that are from 1 to 5, and building $i$ is moved to the right by $a$ and building $i + 1$ is moved to the left by $b$. \\
	14 & Generate two random numbers $a$ and $b$ that are from 1 to 5, and building $i$ is moved to the left by $a$ and building $i + 1$ is moved to downward by $b$. \\
	15 & Generate two random numbers $a$ and $b$ that are from 1 to 5, and building $i$ is moved to the left by $a$ and building $i + 1$ is moved to the right by $b$. \\
	16 & Generate two random numbers $a$ and $b$ that are from 1 to 5, and building $i$ is moved to the left by $a$ and building $i + 1$ is moved upward by $b$. \\
	17 & Generate two random numbers $a$ and $b$ that are from 1 to 5, and building $i$ is moved downward by $a$ and building $i + 1$ is moved to the right by $b$. \\
	18 & Generate two random numbers $a$ and $b$ that are from 1 to 5, and building $i$ is moved downward by $a$ and building $i + 1$ is moved to the left by $b$. \\
	19 & Generate two random numbers $a$ and $b$ that are from 1 to 5, and building $i$ is moved downward by $a$ and building $i + 1$ is moved upward by $b$. \\
	\hline
	\caption{Activities for moving a building in Local Search 2}
	\label{local-search-2-activities}
\end{longtable}

\subsubsection{GA Summarized}
The entire competing GA algorithm is summarized in pseudocode with Algorithm \ref{pseudocode-ga-approach}. Note that our implementation of the competing GA algorithm produces two children during the crossover phase. If there is no space for the second child in the current geenration, the worst offspring will be replaced by the second child.

\begin{algorithm}
\caption{Pseudocode for the competing GA approach.}
\label{pseudocode-ga-approach}
\begin{algorithmic}[1]
\State Initialize population $P$.
\State Calculate the fitness of each solution in $P$.
\State Set $T$ to be the number of generations.
\State Set $X^{(best)}$ to be the best solution found.
\State Set $E_{N}$ to be the number of elite solutions that will be kept in the next generation.
\State Sort $P$ from lowest to highest fitness value.
\For{$t = 1, 2, \ldots T$}
	\If{$t \leq 100$}
		\State Apply swapping method.
	\EndIf
	\For{$i = E_{N} + 1, \ldots, |P|$}
		\State Select parents $X^{(1)}$ and $X^{(2)}$ using tournament selection.
		\State Crossover parents and produce offspring $X^{(o)}$.
		\State Mutate $X^{(o)}$ if mutation probability allows.
		\State $P_{i} = X^{(o)}$.
	\EndFor
	\State Sort $P$ from lowest to highest fitness value.
	\State Apply Local Search 1 to the best solution in $P$.
	\If{$t \geq T - 50$}
		\State Apply Local Search 2 to the best solution in $P$.
	\EndIf
\EndFor \\
\Return best solution in $P$.
\end{algorithmic}
\end{algorithm}

\subsubsection{Particle Swarm Optimization}
Particle swarm optimization (PSO) is a metaheuristic inspired by the social behaviour of animals. It was proposed by Kennedy, J. and Eberhart, R. \cite{Kennedy1995}. A population of solutions is called a swarm, and each solution is called a particle $P$. Each particle has position and velocity vectors. The position vector $X_{i}^{t}$ is the solution itself, while the velocity vector $V_{i}^{t}$ which influences how each particle changes its position. During each iteration of a run, the particle's position is updated to a different position based on the swarm's best found position $\text{gbest}$ so far, the particle's personal best found position $\text{pbest}$ so far, and the current velocity vector $V_{ij}^{t}$. This behaviour is mathematically defined using the following equations.

\begin{align}
	\vec{V}_{i}^{t+1} &= w\vec{V}_{i}^{t} + c_{1}\vec{r}_{1}^{t} \left( \vec{pbest}_{i} - \vec{X}_{i}^{t} \right) + c_{2}\vec{r_{2}}^{t} \left( \vec{gbest}_{i} - \vec{X}_{i}^{t} \right) \label{vt1-pso-equation} \\
	\vec{X}_{i}^{t+1} &= \vec{X}_{i}^{t} + \vec{V}_{i}^{t+1} \label{xt1-pso-equation}
\end{align}

In Equation \ref{vt1-pso-equation}, $w$ is the inertial weight constant, and is important for balancing between exploration and exploitation. It also determines how much the previous velocity will influence the current velocity. The second term in the equation is called the individual cognition term. This calculates the difference between the particle's own best position and current position. It is multiplied by the individual-cognition parameter, $c_{1}$, which influences how important the particle's previous experiences are. $\vec{r}_{1}$ is a random vector that has a range of $[0, 1]$. This helps the algorithm avoid premature convergences. The last term is the social learning term. This allows the swarm to share information to each other about the best global position found so far. Similar to the individual cognition term, this term computes the distance between the particle's current position, and the swarm's best known position. This term also attracts particles towards the $\text{gbest}$. $c_{2}$ is the social learning parameter, and it determines how influential the global learning of the swarm is. $\vec{r}_{2}$ does the same task as $\vec{r}_{1}$. Equation \ref{xt1-pso-equation} finally updates the current position of a particle.

In our approach, little was changed from the classical particle swarm optimization algorithm. Population/Swarm generation is the same as in our approach. The initial velocity was for all particles is set to $0$, as per recommendation by Engelbrecht, A. \cite{Engelbrecht2012}. We also clamped the building to within the bounding region. Our prior experiments showed that without this clamping, many buildings would be positioned outside of the boundary. Clamping is done the same way as in our approach. Since PSO is a continuous metaheuristic, we would not be able to obtain a building orientation that is either $0$ or $90$ immediately after using equations \ref{vt1-pso-equation} and \ref{xt1-pso-equation}. A building's orientation $B_{o}$ may be any real value. As such, the current building orientation is also computed using the following equation, applied after using the PSO equations:

\begin{align}
B_{o} = \left\{\begin{matrix}
0  & \text{if } B_{o}\text{ mod }360 < 180 \\
90 & \text{otherwise}
\end{matrix}\right. \label{building-orientation-pso}
\end{align}

In Equation \ref{building-orientation-pso}, the $B_{o}$ is modulo-ed by 360 to ensure that the range of values are within the range of $[0, 360)$. This range was selected since all angles larger than $359.\bar{999}$ are symmetries with the values in the aforementioned range.

The entire PSO approach is summarized in pseudocode in Algorithm \ref{pseudocode-pso-approach}.

\begin{algorithm}
\caption{Pseudocode for the competing PSO approach.}
\label{pseudocode-pso-approach}
\begin{algorithmic}[1]
\State Set $T$ to be the maximum number of iterations.
\State Initialize $w$, $c_{1}$, and $c_{2}$.
\State Initialize the swarm $\vec{X}_{i} (i = 1, 2, \ldots, n)$
\State Set the velocity $\vec{V}_{i}^{t}$ of each particle $i$ to $0$.
\State Calculate the fitness of each particle.
\State Set the current solution of each particle $i$ as their personal best $\text{pbest}_{i}$.
\State Set the $\text{gbest}$ to be the best solution in the swarm.
\While{t $<$ T}
	\For{each particle $\vec{X}_{i}$}
		\State Initialize $\vec{r}_{1}$ and $\vec{r}_{1}$.
		\State Update the position of the current particle $\vec{X}_{i}$ using Equations \ref{vt1-pso-equation} and \ref{xt1-pso-equation}.
		\State Set the orientation of each building in $\vec{X}_{i}$ using Equation \ref{building-orientation-pso}.
		\State Clamp the buildings in particle $i$ using Equations \ref{bx-clamp-equation} and \ref{by-clamp-equation}.
		\State Calculate the fitness of $\vec{X}_{i}$.
		\If{$f(\vec{X}_{i}) < f(\text{pbest}_{i})$)}
			\State $\text{pbest}_{i} = \vec{X}_{i}$
		\EndIf
		\If{$f(\vec{X}_{i}) < f(\text{gbest})$)}
			\State $\text{gbest} = \vec{X}_{i}$
		\EndIf
	\EndFor
	\State $t = t + 1$
\EndWhile \\
\Return $\text{gbest}$
\end{algorithmic}
\end{algorithm}


\section{ZoKrates}
\label{sec:zokrates}
Nightfall uses \href{https://github.com/Zokrates/ZoKrates}{ZoKrates}~\cite{zokrates} to generate zk-SNARKs.
As discussed in Part~\ref{part:introduction},
zk-SNARKs allow a Prover to `prove' that they have performed a particular computation,
and in order to do so they must convert that computation into an abstract `proof'.
ZoKrates gives us a domain specific language (DSL) through which we can express our computations in a human-readable way.
It then abstracts the code into the format expected by the zk-SNARK prover and verifier.
In all, ZoKrates assists Nightfall with the following:
\begin{itemize} \itemsep-0.5em
  \item[--] A human-readable language for writing code (computations) which can be turned into a zk-SNARK;
  \item[--] Compilation of human-readable code into constraints;
  \item[--] Generation of a (verification key, proving key) pair, which together represent the constraints;
  \item[--] Computation of a `witness'. A Prover can feed their private inputs and public inputs into ZoKrates, and ZoKrates will produce a `witness' -- a step-by-step vector of evidence that each constraint has been satisfied by these inputs.
  \item[--] Generation of a `proof' -- This, combined with the public inputs, is the attestation that the constraints of the computation have been satisfied.
\end{itemize}

\subsection{ZoKrates JavaScript Wrapper}
\label{sec:zokratesJavascriptWrapper}

Nightfall includes a JavaScript wrapper for each of the ZoKrates functions:
\begin{itemize} \itemsep-0.5em
  \item[--] compile;
  \item[--] setup;
  \item[--] compute-witness;
  \item[--] generate-proof;
  \item[--] export-verifier.
\end{itemize}
Nightfall uses the GM17 backend~\cite{DBLP:conf/crypto/GrothM17} of ZoKrates. Nightfall does not currently support the PGHR13 backend~\cite{DBLP:journals/cacm/ParnoHG016}.
Nightfall could be adapted to also support PGHR13.

The ZoKrates JavaScript wrapper:
\begin{itemize} \itemsep-0.5em
  \item[--] Uses a \href{https://hub.docker.com/r/michaelconnor/zok}{Docker Image of ZoKrates} from January 2019;
  \item[--] Performs a Trusted Setup:
  \begin{itemize}
    \item[--] Mounts `.code' files into a ZoKrates container;
    \item[--] Compiles this code into constraints;
    \item[--] Performs the `trusted setup' to output a `proving key' and a `verification key'
    \item[--] Outputs this `proving key' and `verification key' into the mounter directory of the user's local machine;
    \item[--] Jsonifies the `verification key'.
  \end{itemize}
  \item[--] Generates proofs:
  \begin{itemize}
    \item[--] Generates a proof for a particular set of public and private inputs (passed from the UI):
    \item[--] Extracts the proof object from the container's console (ready for use by the node.js application)
  \end{itemize}
\end{itemize}

Nightfall doesn't use the hard-coded \texttt{verifier.sol} contracts which are created by ZoKrates. Instead, Nightfall uses a single verifier contract which can handle all GM17 verification keys, and all proof submissions against these verification keys. This verifier contract (called \texttt{GM17.sol}) adheres to the draft EIP1922 standard.

\begin{center}
  \begin{mdframed}[backgroundcolor=verylightblue]
    Where to look?\\
    \\
    \begin{tabular}{lp{14cm}}
      \url{https://github.com/Zokrates/ZoKrates} & ZoKrates source code\\
      \url{https://zokrates.github.io} & ZoKrates documentation\\
      \texttt{./zkp/src/zokrates.js} & ZoKrates JavaScript Wrapper\\
      \texttt{./zkp/code/gm17/} & \texttt{.pcode} files\\
      \texttt{./zkp/code/README-tools-code-preprop.md} & explanation of \texttt{.pcode} syntax\\
      \texttt{./zkp/code/README-tools-trusted-setup.md} & how to automatically do the trusted setup\\
      \url{https://github.com/EYBlockchain/zokrates-preprocessor} & how to manually transpile from \texttt{.pcode} to \texttt{.code}\\
      \texttt{./zkp/code/README-manual-trusted-setup.md} & how to manually do the trusted setup\\
      \texttt{./zkp/contracts/GM17.sol} & for the EIP1922 Verifier contract.\\
      \url{https://eips.ethereum.org/EIPS/eip-1922} & for the draft zk-SNARK Verifier Standard.
    \end{tabular}
  \end{mdframed}
\end{center}

\begin{figure}[H]
  \begin{center}
    \begin{mdframed}[backgroundcolor=verylightred]
      \noindent
      SECURITY WARNINGS
      \begin{itemize}
        \item[--] The \href{https://hub.docker.com/r/michaelconnor/zok}{Docker Image of ZoKrates} from January 2019 is already outdated. It might include security bugs which have since been fixed over in the ZoKrates repository. The syntax of the ZoKrates DSL has also changed considerably since January 2019, and therefore the \texttt{.pcode} files of Nightfall are written in outdated syntax.
      \end{itemize}
    \end{mdframed}
  \end{center}
  \caption{Security warning: ZoKrates versioning}
  \label{fig:zokratesWarning}
\end{figure}


\documentclass[12pt]{article}

\usepackage{amsmath}
\usepackage{graphicx}
\usepackage{color}
\usepackage{bbm}
\usepackage{epsfig}
\usepackage{latexsym}
\usepackage{color}

% \RR is supposed to represent the reals.
\newcommand{\RR}{\mathbbm{R}}
% \FF is supposed to represent a field.
\newcommand{\FF}{\mathbbm{F}}
% \CC is supposed to represent the complex plane.
\newcommand{\CC}{\mathbbm{C}}
% \ZZ is supposed to represent the integers
\newcommand{\ZZ}{\mathbbm{Z}}

\newtheorem{theorem}{Theorem}
\newtheorem{lemma}{Lemma}
\newtheorem{corollary}{Corollary}
\newtheorem{conjecture}{Conjecture}

\newcommand{\proof}{\textsc{Proof: }}
% ``eop'' is ``End of Proof''.
\newcommand{\eop}{ $\Box$}

\begin{document}
\title{Tale 2 Cities}
\author{Dickens}
\maketitle
\bibliographystyle{plain}

\begin{abstract}
Best of times, worst of times.
\end{abstract}

% How to add a table of contents:
%\tableofcontents

% How to include an eps file (called ``cell.eps'' in this case).
%\begin{center}
%\epsfig{file=cell.eps,height=3.0in}
%\end{center}

% How to make a figure (with caption, number, etc)
%\begin{figure}[htbp] %  figure placement: here, top, bottom, or page
%   \centering
%   \includegraphics[width=0.9\linewidth]{filename.eps}
%   \caption{ Trenchant description goes here.}
%  \label{fig:my_great_figure}
%\end{figure}

% How to add a bibliography:  Use ``\cite{reference_name}'' and the following
%\bibliography{../../bibliography/master/master}

% If you want the References (i.e. bibliography) to show up as its own
% section in the table of contents, include the following at the top
% of the document, with all the other "usepackage" commands:
%\usepackage[nottoc,numbib]{tocbibind}

\section{Introduction}

Observed:
\begin{itemize}
\item $N$, the number of subjects in the population
\item Reduction ratio $R_i$ for each subjects (where $R=0.25$ means a 75\% reduction)
\end{itemize}
Latent:
\begin{itemize}
\item $Q_{25} = \Pr[R_{subject}\leq 0.25]$.
\end{itemize}
Then probability of success is:
$$\sum_{k=0}^N \binom{N}{k} Q_{25}^k (1-Q_{25})^{N-k} \mathbbm{1}_{<0.05}(I_{x=0.5}(k, N-k+1))$$

\end{document}


\documentclass{article}

\usepackage{graphicx}% Include figure files
\usepackage{dcolumn}% Align table columns on decimal point
\usepackage{bm}% bold math
\usepackage{amsmath}
\usepackage{ifthen}
\usepackage{amsfonts}
\usepackage{dsfont}
\usepackage{boxedminipage}
\usepackage{hyperref}
\usepackage{placeins}
\usepackage[toc,page]{appendix}

\newcommand{\R}{\ensuremath{\mathds{R}}}
\newcommand{\C}{\ensuremath{\mathds{C}}}
\newcommand{\Q}{\ensuremath{\mathds{Q}}}
\newcommand{\N}{\ensuremath{\mathcal{N}}}
\newcommand{\Z}{\ensuremath{\mathds{Z}}}
\newcommand{\D}{\ensuremath{\mathds{D}}}
\newcommand{\W}{\ensuremath{\mathds{W}}}
\newcommand{\B}{\ensuremath{\mathds{B}}}
\newcommand{\mS}{\ensuremath{\mathds{S}}}
\newcommand{\I}{\ensuremath{I}}
\newcommand{\1}{\ensuremath{\mathds{1}}}
\newcommand{\SO}{\ensuremath{\mathsf{SO}}}
\newcommand{\Sp}{\ensuremath{\mathsf{Sp}}}
\newcommand{\s}{\ensuremath{\mathfrak{s}}}
\newcommand{\n}{\ensuremath{\mathfrak{n}}}
\newcommand{\Ocplx}{\ensuremath{\mathcal{O}}}
\newcommand{\0}{\ensuremath{0}}
\newcommand{\cset}[1]{\mathcal{#1}}

\newcommand{\softname}{SSA Toolbox}

\newcommand{\KLD}{D_{\text{KL}}}
%\DeclareMathOperator*{\KLD}{KL}

\DeclareMathOperator*{\diag}{diag}
\DeclareMathOperator*{\E}{\mathbb{E}}
\DeclareMathOperator*{\sign}{sign}
\DeclareMathOperator*{\trace}{tr}
\DeclareMathOperator*{\var}{var}
\DeclareMathOperator*{\cov}{cov}
\DeclareMathOperator*{\expm}{expm}
\DeclareMathOperator*{\myspan}{span}

\setcounter{tocdepth}{1}

\begin{document}

\title{SSA Toolbox \input version.tex --- Manual}
\author{Jan Saputra M\"uller, Paul von B\"unau, \\ Frank C.~Meinecke, Franz J.~Kir\'{a}ly, Klaus-Robert M\"uller}

\maketitle

\tableofcontents

\newpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction and Overview}

This is the manual for the SSA Toolbox, an efficient open-source implementation of the
Stationary Subspace Analysis~\cite{PRL:SSA:2009} algorithm. Stationary Subspace Analysis (SSA)
is a general purpose algorithm for the explorative analysis of non-stationary data, i.e.~data
whose statistical properties change over time. SSA can help to detect, characterize and
visualize temporal changes in complex high-dimensional data sets.

The SSA Toolbox is written entirely in Java and is thus platform-independent. It has been tested
successfuly under Windows, Linux and MacOS. The SSA Toolbox comes with a state-of-the-art native
Linear Algebra library (BLAS,LAPACK). For maximum platform independence, the user can also
choose the purely Java-based library COLT.
Data and results can be imported and exported as comma-separated values \texttt{.csv} files, the fail-safe
format of last resort, and through Matlab's proprietary \texttt{.mat} files, a de-facto standard in the
Machine Learning community.

The source code of the SSA Toolbox is fully documented (using the JavaDoc standard) and accompanied
by a set of unit tests written in JUnit. The latest version is always available from
github\footnote{See \url{http://https://github.com/paulbuenau/SSA-Toolbox}}, a hosting service for
the git versioning system. Section~\ref{sec:dev} contains further information for developers,
including a high-level overview of the class structure.

There are four ways to use the SSA Toolbox
\begin{enumerate}
	\item As a standalone application with a graphical user interface.

	\item As a standalone application from the command line.

	\item From within Matlab, using the wrapper script \texttt{ssa.m}.

	\item As a Java library, from your own application.
\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Installation and Running}
\label{sec:install_run}

\paragraph{Obtaining the latest SSA~Toolbox}

The latest version of the SSA~Toolbox is available from the offical SSA homepage:
\begin{center}
	\url{http://www.stationary-subspace-analysis.org/toolbox}
\end{center}
There you can also find pointers to further references, example data and a link
to the SSA mailing list.

\paragraph{Platforms}

The SSA~Toolbox is written in the platform-independent Java programming language;
platform-specific numerical libraries\footnote{BLAS+LAPACK provided through
jblas (see \url{http://www.jblas.org}).} are included for several target architectures.
The SSA~Toolbox requires the Java Runtime Environment\footnote{See
\url{http://www.java.com/getjava}} version 1.5 or later. Most operating systems
have a Java Runtime Environment pre-installed, you might be able to find out
the version by typing \texttt{java -version} on the command line. The SSA~Toolbox has
been tested on the following platforms.
\begin{itemize}
	\item Microsoft Windows (32 and 64 bit)
	\item Linux (32 and 64 bit)
	\item Mac OS X (32 and 64 bit)
\end{itemize}

\paragraph{Installation and Running}

The SSA~Toolbox comes as a single \texttt{.zip} or \texttt{.tar.gz} archive.
After unpacking, you can start the SSA~Toolbox by opening the file \texttt{ssa.jar}
with the default method of your operating system, e.g.~by double-clicking on it under
Microsoft Windows, OS X and some Linux distributions.

You can also manually invoke the SSA~Toolbox by typing
\begin{center}
  \texttt{java -jar ssa.jar}
\end{center}
on the command line of your operating system.

In some cases, if you want to run SSA on very large data sets, it might be necessary to start the toolbox
with a higher amount of Java heap space (in those cases the SSA toolbox will inform you
about this issue). There is a section in the Frequently Asked Questions which explains how to do that
(see Section~\ref{sec:faq}).

If you want to use the SSA~Toolbox directly
from Matlab, you can use the wrapper script \texttt{ssa.m}. Type \texttt{help ssa} on
the Matlab command line to find out about the format of its input and output parameters.
Note that if you invoke the SSA Toolbox from within Matlab, it will use its
internal JVM unless you specify an external JVM, e.g. using the environment
variable \texttt{MATLAB\_JAVA} under Linux.

You can also use the toolbox from the command line.
In this case, you have to pass options after \texttt{java -jar ssa.jar}. The following table
shows the available options:\\

\begin{tabular}{cp{10cm}}
 \textbf{Option} & \textbf{Meaning/Argument}\\
 -i & Input file (in \texttt{.csv} or \texttt{.mat} format). Required.\\
 -o & Output file or directory. If it ends with \texttt{.mat} a Matlab file will be created,
      otherwise \texttt{.csv} files are created in the specified directory. Required.\\
 -d & Number of stationary sources. Required.\\
 -r & Number of restarts. Optional. Default: 5\\
 -n & Number of equally-sized epochs. Optional. If this option is not specified, and no custom
      epochization has been given, a heuristic is used to determine the number of epochs.\\
 -e & Epochization file in \texttt{.csv} format. Optional.\\
 -m & Use the means during optimization. Has to be 0 or 1. Optional. Default: 1\\
 -c & Use the covariances during optimization. Has to be 0 or 1. Optional. Default: 1\\
 -s & Random seed. Optional.\\
 -j & Use jBlas instead of Colt. Has to be 0 or 1. Optional. Default: 0\\
\end{tabular}
\\

For example, the following line would run SSA on the example data set:\\

\texttt{java -jar ssa.jar -i example\_data/example\_data.mat -d 2 -o results.mat}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Stationary Subspace Analysis in Brief}

Stationary Subspace Analysis \cite{PRL:SSA:2009} factorizes a multivariate time-series
into its stationary and non-stationary components. That is, we assume that the data
generating system consists of $d$ stationary source signals
${\mathbf s^\s}(t) = [s_1(t), \dots, s_d(t)]^\top$ and $D-d$ non-stationary source signals
${\mathbf s^\n}(t) = [s_{d+1}(t), \dots, s_D(t)]^\top$ and that the observed signals
$x(t)$ are a linear superposition of these sources,
\begin{equation}
  {\mathbf x}(t) = A {\mathbf s}(t) =
    \begin{bmatrix} A^{\s} & A^{\n} \end{bmatrix}
    \begin{bmatrix} {\mathbf s^{\s}}(t) \\ {\mathbf s^{\n}}(t) \end{bmatrix}
\label{eq:mixing_model}
\end{equation}
where $A$ is an invertible matrix. Note that we do \textit{not} assume that
the sources ${\mathbf s}(t)$ are independent. We refer to the spaces spannend
by the columns of $A^{\s}$ and $A^{\n}$ as the stationary ($\s$-) and
non-stationary ($\n$-) space respectively.

The SSA algorithm factorizes the observed signals $x(t)$ according to
Equation~\ref{eq:mixing_model}, i.e.~it finds a linear transformation
\begin{equation}
\label{eq:est_demixing}
  \hat{A}^{-1} = \begin{bmatrix} \hat{P}^{\s} \\ \hat{P}^{\n} \end{bmatrix}
\end{equation}
that separates the \s-sources from the \n-sources. The inverse of the estimated
demixing matrix $\hat{A}^{-1}$ is the estimated mixing matrix,
\begin{equation}
\label{eq:est_mixing}
 \hat{A} = \begin{bmatrix} \hat{A}^{\s} & \hat{A}^{\n} \end{bmatrix},
\end{equation}
and the estimated stationary and non-stationary sources are thus given by
\begin{align}
\label{eq:est_s_sources}
  \hat{\mathbf s}^{\s}(t) & = \hat{P}^{\s} {\mathbf x}(t) \\
\label{eq:est_n_sources}
  \hat{\mathbf s}^{\n}(t) & = \hat{P}^{\n} {\mathbf x}(t)
\end{align}
respectively.
Note that only the $\s$-projection and the $\n$-space are uniquely identifiable.
The projection to the \n-sources $\hat P^{\n}$ is found by maximizing the non-stationarity
of the estimated \n-sources.

The SSA Toolbox allows for input and output in (time $\times$ channel) and
(channel $\times$ time) format. Note that the above definitions of sources,
projections and basis correspond to the (channel $\times$ time) format.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Input, Output and Parameters}

The input to the SSA Toolbox consists of
\begin{itemize}
 \item Data: the time series $x(t)$, either as $(\text{channels} \times \text{time})$ or
				$(\text{channels} \times \text{time})$.

 \item Segmentation of the time series $x(t)$ into epochs, either
	\begin{itemize}
	  \item equally-sized, where the number of epochs is supplied by the user; or

		\item equally-sized, where the number of epochs is set automatically by a heuristic;

	  \item according to a user-supplied custom epoch definition.
	\end{itemize}

 \item Parameters to the SSA Algorithm (see Section~\ref{sec:params}).
\end{itemize}

The parameters are set via the graphical user interface. The time series
$x(t)$ and a custom epoch definition can be loaded from comma-separated values
(CSV) and Matlab (.mat) files.

\subsection{Comma-Separated-Values File Format}
\label{sec:csv_input}

Comma Separated Values (CSV) files are human-readable text files for storing tabular data.
The columns are separated by commas and each line of the file corresponds to a row.
Lines starting with a hash (\texttt{\#}) are ignored. If the data has more rows than columns,
then each row will be interpreted as a time point and each column as a channel. Otherwise,
the format is assumed to be $(\text{channels} \times \text{time})$. See
Figure~\ref{fig:ex_timeseries} for an example time series file.

\begin{figure}[h]
\centering
\begin{boxedminipage}{10cm}
\begin{verbatim}
# 2ch recording VPzj Oct 30th
-0.18671,0.11393
0.72579,1.0668
-0.58832,0.059281
2.1832,-0.095648
-0.1364,-0.83235
...
\end{verbatim}
\end{boxedminipage}
\caption{
The first five time points of a timeseries in CSV format with two channels.
The first line is a comment for documentation purposes.
\label{fig:ex_timeseries}
}
\end{figure}

A custom segmentation of the time series into epochs can be specified by means of
a separate CSV file, which must have the same number of rows as the time series
and one column. The entries correspond to the index (starting with 1) of the
epoch that a time point belongs to. Figure~\ref{fig:ex_segmentation} shows
an example CSV file for a segmentation of the time series into custom epochs.

\begin{figure}[h]
\centering
\begin{boxedminipage}{10cm}
\begin{verbatim}
# Epochs for recording VPzj Oct 30th
1
1
1
2
2
...
\end{verbatim}
\end{boxedminipage}
\caption{
Custom epoch definition for the first five time points of the time series shown in Figure~\ref{fig:ex_timeseries}.
The first three time points belong to the same epoch and the last two time points form the second epoch.
\label{fig:ex_segmentation}
}
\end{figure}

\subsection{Matlab File Format}

In the Matlab file format, the time series must be contained in a variable
called \texttt{X}. If \texttt{X} has more rows than columns, then each row
will be interpreted as a time point and each column as a channel. Otherwise,
the format is assumed to be $(\text{channels} \times \text{time})$.

\begin{figure}[h]
\centering
\begin{boxedminipage}{10cm}
\begin{verbatim}
>> X

X =

   -0.4326   -0.1867
   -1.6656    0.7258
    0.1253   -0.5883
    0.2877    2.1832
   -1.1465   -0.1364
    ...
\end{verbatim}
\end{boxedminipage}
\caption{Timeseries in Matlab with two channels and five time points.
\label{fig:ex_matlabts}
}
\end{figure}

If \texttt{X} is a cell array, then the elements
are interpreted as epochs where each epoch must have the same number
of channels, Figure~\ref{fig:ex_matlabsegs} shows
an example.

\begin{figure}[h]
\centering
\begin{boxedminipage}{10cm}
\begin{verbatim}
>> X

X =

    [100x2 double]    [100x2 double]    [80x2 double]
\end{verbatim}
\end{boxedminipage}
\caption{Timeseries in Matlab with custom epoch definition. The time series is split
into three epochs where the first two epochs contain 100 samples each and the third
epoch consists of 80 samples.
\label{fig:ex_matlabsegs}
}
\end{figure}

\FloatBarrier

\subsection{Parameters of SSA}
\label{sec:params}

The SSA algorithm has the following parameters which can be set via the graphical
user interface.

\paragraph{Number of stationary sources} The number of stationary sources $d$ to be
found in the time series. Depending on $d$, the algorithm needs a certain minimum number
of distinct epochs, see next paragraph. A warning message will be issued
if this condition is violated.

\paragraph{Number of restarts} The number of times the optimization procedure
should be repeated with different random initialization in order to avoid local minima.
The final result is the decomposition which attained the smallest objective function
value.

\paragraph{Number of equally-sized epochs} The number of equally sized epochs $N$ that
the time series should be split into, if the user did not supply a custom segmentation.
The minimum number of epochs required to avoid spurious
stationary directions depends on the number of stationary sources $d$, see next paragraph.

\paragraph{Which moments of the sources should be considered} Depending on the application domain,
changes in mean or covariance matrix either do not occur or are not relevant. The user can therefore
select whether non-stationarities in the mean, covariance matrix or both should be considered.
The default is that both moments are taken into account.

\subsubsection*{Determinacy of the solution}
\label{sec:determinacy}

If the number of epochs $N$ is too small in relation to the number of
non-stationary sources $D-d$, there may exist spurious stationary components that render
the solution non-identifiable, i.e. components which appear stationary on the
limited amount of observed data but which are in fact non-stationary.
Informally speaking, spurious stationary components occur when the amount of
observed variation in the distributions (i.e. the number of distinct epochs)
 is insufficient to eliminate seemingly stationary directions in the non-stationary subspace.
For example, if you think of two covariance matrices $\Sigma_1, \Sigma_2 \in \R^{2 \times 2}$ in two-dimension,
then one can always find a one-dimensional subspace on which the projected variances
agree, unless $\Sigma_1 - \Sigma_2$ has an indefinite spectrum (i.e.~the contour plot
of one covariance matrix is strictly contained in the other).

It can be shown \cite{PRL:SSA:2009} that there exist no spurious stationary directions
if the number of epochs $N$ is at least
\begin{equation*}
	N > \frac{D-d}{2} + 2.
\end{equation*}
When only changes in one moment are considered, we need more epochs, namely
\begin{equation*}
	N > D-d + 1 .
\end{equation*}
The SSA~Toolbox issues a warning if these conditions are violated.
In practice, if there is enough data, it is advisable to use more epochs than the minimum
indicated by this bound.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Output}

The result of the SSA algorithm is an estimated demixing matrix $\hat{A}^{-1}$
(see Equation~\ref{eq:est_demixing}). From this, the following output
is generated by the SSA~Toolbox (assuming the output format $\text{channels} \times \text{time}$):
\begin{itemize}
	\item the estimated projection to the stationary sources $\hat{P}^\s \in \R^{d \times D}$

	\item the estimated projection to the non-stationary sources $\hat{P}^\n \in \R^{ (D-d) \times D}$

	\item the estimated basis of the stationary subspace $\hat{A}^\s \in \R^{D \times d}$

	\item the estimated basis of the non-stationary subspace $\hat{A}^\n \in \R^{D \times (D-d)}$

	\item the estimated stationary sources $\hat{s}^\s(t) = \hat{P}^\s {x}(t)$,

	\item the estimated non-stationary sources $\hat{s}^\n(t) = \hat{P}^\n {x}(t) $

\end{itemize}
These six matrices resp.~time series can either be saved in individual CSV files
(see Section~\ref{sec:csv_input} for a general description of the format) or to a single
Matlab file (.mat).

\subsection{Matlab File Format}

The output of the SSA Toolbox can be written to a single Matlab file which contains
a structure \texttt{ssa\_results} where the attributes correspond to the six outputs.
See Figure~\ref{fig:ex_matlab_res} for an example.

\begin{figure}[h]
\centering
\begin{boxedminipage}{12cm}
\begin{verbatim}
>> ssa_results =

          Ps: [3x6 double]
          Pn: [3x6 double]
          As: [6x3 double]
          An: [6x3 double]
       s_src: [3x10000 double]
       n_src: [3x10000 double]
  parameters: [1x1 struct]
      loss_s: -1.2789
      loss_n: 73.2571
iterations_s: 13
iterations_n: 10
 description: 'SSA results (Thu Jun 10 12:58:23 CEST 2010)'
\end{verbatim}
\end{boxedminipage}
\caption{
Matlab result structure of the SSA Toolbox. Five dimensional data (500 samples)
are decomposed into $d = 3$ stationary sources and $D-d = 2$ non-stationary sources.
\label{fig:ex_matlab_res}
}
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\FloatBarrier % Flush all figures, we don't want the file format examples below.

\section{Examples and Toy Data}

The SSA Toolbox comes with an example data set in Matlab and CSV format (\texttt{example\_data.csv} and \texttt{example\_data.mat}), a Matlab script to generate synthetic data (\texttt{ssa\_toydata.m}), and a self-contained
Matlab demonstration (\texttt{ssa\_demo.m}). In the
following sections, we describe each of these files.

\subsection{Example Data}

The example data sets in the directory \texttt{example\_data} were generated using the Matlab
script \texttt{ssa\_toydata.m} using the command-line
\begin{center}
	\texttt{[X, A] = ssa\_toydata(10, 2, 2, 'mean\_nonstat', 0.5)};
\end{center}
The dataset consists of ten epochs (each 500 samples); it has two stationary and two non-stationary
sources. The Matlab file \texttt{example\_data.mat} also contains the true mixing matrix \texttt{A}
so that you can assess the quality of the found solution using the subspace error between the true
and the estimated basis of the non-stationary spaces as follows:
\begin{center}
	\texttt{subspace\_error(ssa\_results.An, A(:,3:4))}
\end{center}
A description of this error measure can be found in Appendix~\ref{app:error_measure}. The comma-separated
values file \texttt{example\_data.csv} contains the same data as the Matlab file. Further details about
the toy data generation can be found in the next section.

\subsection{Toy Data Generation}

The Matlab script \texttt{ssa\_toydata.m} generates synthetic datasets according to the SSA mixing
model. A documentation of the parameters of this function is available from the Matlab help, in this
section we describe how the data is generated.

Let $X_1, \ldots, X_n$ be random variables modeling the distribution of the data in each of
the $n$ epochs. According to the SSA mixing model (Equation~\ref{eq:mixing_model}), each
epoch is a linear mixture of $d$ stationary and $D-d$ non-stationary sources,
\begin{align*}
	X_i = A \begin{bmatrix} X^\s \\ X^\n_i \end{bmatrix}
\end{align*}
where $A$ is the mixing matrix and $X^\s$ and $X^\n_i$ are random variables representing
the \s- and the \n-sources in the $i$-th epoch respectively. The entries of $A$ are chosen
uniformly at random from $[-0.5, 0.5]$ and its columns are normalized to one. The distribution
of the \s-sources is the same over all epochs,
\begin{align*}
	X^\s \sim \N(0,I),
\end{align*}
and the \n-sources are correlated with the \s-sources,
\begin{align*}
	X^\n_i = C_i X^\s + Y^\n_i,
\end{align*}
where $C_i$ is $(D-d \times d)$-matrix and $Y^\n_i \sim \N(\mu_i, \Sigma_i)$ is a
random variable corresponding to the conditional $X^\n_i | X^s$. The covariance
matrix $\Sigma^\n_i$ is generated as,
\begin{align*}
	\Sigma^\n_i = B^\n_i \Lambda_i (B^\n_i)^\top,
\end{align*}
where $B^\n_i$ is a random orthogonal matrix and $\Lambda_i$ is a diagonal matrix of
the eigenvalues $\lambda_1, \ldots, \lambda_{D-d}$. The log eigenvalues
are drawn from a uniform distribution, and the sign is chosen to be positive
with probability $p$ and negative otherwise; then they normalized such that
\begin{align*}
	\frac{1}{D-d} \sum_{i=1}^{D-d} | \log \lambda_i | = \log \lambda_{\text{mean}},
\end{align*}
where $\log \lambda_{\text{mean}}$ is a measure of the distance from the standard normal
distribution.

For each epoch, the canonical correlation $\rho_i$ is drawn uniformly at random from
$[\rho_\text{min}, \rho_\text{max}]$, which determines the scaling of the rows of $C_i$,
\begin{align*}
	C_i = B C' (B^\n_i)^\top,
\end{align*}
where $B$ is a random orthogonal matrix and $C'$ is a $(D-d \times d)$-matrix with
non-zero entries only on the diagonal,
\begin{align*}
	(C')_{jj} = \sqrt{ \frac{\lambda_{jj}}{\frac{1}{\rho_i^2 } - 1}} .
\end{align*}
This ensures that the canonical correlation is $\rho_i$ for all principal vectors.
Thus the covariance matrix of the sources in the $i$-th epoch is given by,
\begin{align*}
	\Sigma_i = \cov \left(
		\begin{bmatrix} X^\s \\ X^\n_i
		\end{bmatrix}
	\right) =
	\begin{bmatrix}
		I & C^\top_i \\
		C_i & C_i  C^\top_i + \Sigma^\n_i
	\end{bmatrix} .
\end{align*}
The strength of the non-stationarity in the mean of the \n-sources is chosen relative to the
total non-stationarity $\tilde{\sigma}$ in the covariance matrix which we measure
as the the sum of the absolute log eigenvalues of the whitened covariance matrices as follows.
Let $\Sigma'_i = A \Sigma_i A^\top$ be the covariance matrix of the mixed sources. The whitening matrix
$W$ of the average covariance matrix is given by,
\begin{align*}
	W = \left[ \frac{1}{n} \sum_{i=1}^n \Sigma'_i \right]^{-\frac{1}{2}} .
\end{align*}
Let $W \Sigma'_i W^\top = U \Lambda' U^\top$ be the eigenvalue decomposition of the whitened covariance
matrix of the $i$-th epoch, where $\Lambda'$ is the diagonal matrix of eigenvalues. The total
non-stationarity $\tilde{\sigma}$ in the covariance matrix is measured as,
\begin{align*}
	\tilde{\sigma} = \sum_{i=1}^n \sum_{j=1}^{D} \left|\log (\Lambda'_i)_{jj} \right| .
\end{align*}
The total non-stationarity in the mean  $\tilde{\mu}$ is measured as the sum of the squared norms
of the epoch mean vectors $\mu'_1, \ldots, \mu'_n$ in the whitened basis,
\begin{align*}
	\tilde{\mu} = \sum_{i=1}^n \| W \mu'_i \|^2 .
\end{align*}
Thus we first choose a random set of squared norms $m_1, \ldots, m_n$ such that
$\sum_{i=1}^n m_i = \tilde{\sigma} = \tilde{\mu}$, and then a set of mean vectors
$\mu_1, \ldots, \mu_n$ of the sources where the first $d$ entries (corresponding to the \s-sources)
are zero and the last $D-d$ entries are drawn uniformly from $[-0.5, 0.5]$. These source
mean vectors are then rescaled such that that $\| W A \mu_i \|^2 = m_i$ for each epoch.

\clearpage

\subsection{Matlab Demonstration}
\begin{figure}[h]
\begin{center}
	\includegraphics[angle=90,width=10cm]{ssa_example.pdf}
	\caption{\label{fig:matlab_example}
		Output of the Matlab example \texttt{ssa\_demo.m}}
\end{center}
The plot generated by the example script is shown in Figure~\ref{fig:matlab_example}. The top panel
shows the two dimensional input time series $x(t)$. Both dimensions (or variables, channels) appear
non-stationary. The vertical red lines indicate how the time series is segmented into four epochs.
In the middle row, we see the result of applying SSA: for every epoch, the scatter plot shows
the distribution of the estimated stationary source (vertical axis) vs.~the estimated non-stationary
source (horizontal axis). We can see that the mean and the variance projected to the vertical axis
is constant over the epochs, whereas both change significantly for the estimated non-stationary source.
The bottom panel shows the time courses for the estimated stationary (top) and the estimated non-stationary
(bottom) source.
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\FloatBarrier

\section{Frequently Asked Questions}
\label{sec:faq}

\paragraph{When should I use SSA?}
SSA can be applied whenever a multivariate dataset, that has a temporal structure is conceivable
generated as a mixture of stationary and non-stationary components, where the non-stationary
effects are visible in changes of the mean and covariance matrix.

\paragraph{Can I use SSA on a univariate time series?} No.

\paragraph{How do I determine the number of stationary sources?} To date, there exists no \textit{automatic}
selection procedure. In practice, one can apply SSA for several numbers of stationary sources and inspect
the result, e.g.~visually or using appropriate statistical hypothesis tests. Moreover, the value of the
objective function can be used as a guideline, see Appendix~\ref{app:objfunval}.

\paragraph{Why is it not possible to identify the non-stationary sources and what does this mean?}
The true non-stationary sources cannot be identified because adding stationary components to a
non-stationary time series leaves it non-stationary. This makes the estimated non-stationary sources
arbitrary. It is therefore not possible to recover the true non-stationary sources from the mixture.

\paragraph{Why is it not possible to identify the stationary subspace and what does this mean?} The basis
of the stationary subspace cannot be identified because we cannot estimate the non-stationary sources, which
are dual to the basis of the stationary subspace. If we could identify the stationary subspace, then we could
find the non-stationary sources by projecting orthogonal to it.

\paragraph{I would like to use the Toolbox from Python/Octave/or any other environment, is this possible?}
The SSA Toolbox can be used directly from any environment that can invoke Java code, such as
e.g.~Matlab. Based on the command-line interface, future releases will include wrappers for R and Python.

\paragraph{Can I get a $p$-value for my result?} The objective function value is an approximate
$p$-value for a stationarity test, see Appendix~\ref{app:objfunval}.

\paragraph{The toolbox says that there is not enough Java heap space. How can I solve this issue?}
You have to increase the Java heap space. If you are using the standalone version of the toolbox, you can
do this by running it from the command line like this:
\begin{center}
\texttt{java -Xmx512M -jar ssa.jar}
\end{center}
This would set the Java heap space to \texttt{512M}. Of course, you can replace \texttt{512M} with your
desired size.

If you are using the toolbox from within Matlab, you have to increase the Java heap space which Matlab uses.
The following website explains how to do that:
\begin{center}
    \url{http://www.mathworks.com/support/solutions/en/data/1-18I2C}
\end{center}
In Matlab 2010a and later, this can be easily done from Matlab's preferences dialog.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Developers}
\label{sec:dev}

This section contains some information about the technical structure of the SSA Toolbox
that is helpful for developers who want to extend it or use parts in other projects. The
source code distribution of the SSA Toolbox is available from the project
web site (see Section~\ref{sec:install_run}) and from github, a public git repository
server, which is the primary location of the source code:
\begin{center}
	\texttt{https://github.com/paulbuenau/SSA-Toolbox}
\end{center}
On github you will always find the latest, probably unreleased version of the SSA Toolbox.

%%%%%%%%%%%%%%%%%
\subsection*{Example}

The code of the SSA Toolbox can be used as a library from other applications. Below you can can find a
simple example which shows how to load data, parametrize the SSA algorithm, apply it and save the
results to a file.

\bigskip

\begin{boxedminipage}{12cm}
\small
\begin{verbatim}
public class SSAJavaExample
{
    public static void main(String args[])
    {
        // create a console logger for writing log messages
        ssatoolbox.ConsoleLogger cl = new ssatoolbox.ConsoleLogger();

        // create instance of SSA main class.
        ssatoolbox.Main ssaMain = new ssatoolbox.Main(false, cl);

        // load data from CSV-file
        ssaMain.loadTimeseries(new java.io.File("data.csv"));

        // set SSA parameters
        ssaMain.parameters.setNumberOfStationarySources(3);

        // set epochization type
        ssaMain.data.setEpochType(
        	ssatoolbox.Data.EPOCHS_EQUALLY_HEURISTIC);

        // Run SSA (*not* using a separate thread!)
        ssaMain.runSSA(false);

        // save stationary sources
        ssaMain.saveStationarySourcesCSV(
        		new java.io.File("stationary.csv"));

        // save non-stationary sources
        ssaMain.saveNonstationarySourcesCSV(
        	new java.io.File("non-stationary.csv"));
    }
}
\end{verbatim}
\end{boxedminipage}

%%%%%%%%%%%%%%%%%
\subsection*{Class Structure}

The SSA Toolbox consists of the classes \texttt{SSA}, \texttt{SSAParameters}, \texttt{Data}, \texttt{Results}, \texttt{MathFunctions},
\texttt{GUI}, \texttt{Main}, \texttt{SSAMatrix}.

\paragraph{SSA}

This class implements the SSA algorithm. The main-part of the implementation is in the method \texttt{optimizeOnce}, which does
the conjugate gradient descent. The calculation of the objective function and its gradient is done in the method \texttt{objectiveFunction}.
Apart from that, the class \texttt{SSA} is responsible for checking our determinacy bounds and has to throw an exception if they are violated.

\paragraph{SSAParameters}

The class \texttt{SSAParameters} stores the parameters, such as the assumed number of stationary sources, the number of restarts for the optimization and
whether to use means/covariance matrices. It is responsible to check whether the entered parameters are valid and has to throw an exception otherwise.

\paragraph{Data}

The class \texttt{Data} stores our time series and does the epochization (equally sized epochs or custom epochization). It has to check whether the
epochization is valid (and possible) and has to throw an exception otherwise.

\paragraph{Results}

This class stores the results of the SSA algorithm.

\paragraph{MathFunctions}

This class contains auxilliary functions.

\paragraph{GUI}

This class is responsible for the GUI of the standalone-version of the toolbox. It implements the interface \texttt{Logger}.

\paragraph{Main}

This is the main class of the standalone-version of the toolbox.

\paragraph{SSAMatrix}

\texttt{SSAMatrix} is a wrapper class for different matrix libraries. All matrices in the toolbox are instances of this class. It passes the
matrix operations to the currently used matrix library.

\paragraph{Logger}

This is an interface for logging. It contains only one method, which has to be implemented by all implementing classes: \texttt{appendToLog}.

\paragraph{ConsoleLogger}

This class implements the interface \texttt{Logger}. It writes all messages which are passed to the method
\texttt{appendToLog} directly to the console (needed for the matlab-wrapper).

%%%%%%%%%%%%%%%%%
\subsection*{External Dependencies}

All necessary libraries are included in the distribution archive. These are the following.
\begin{itemize}
	\item \texttt{JMatIO} for reading and writing Matlab files;

 	\item \texttt{COLT} and \texttt{jblas} for matrix computations; and

	\item \texttt{java-getopt} for evaluation command-line arguments.

\end{itemize}

%%%%%%%%%%%%%%%%%
\subsection*{Unit Tests}
The unit tests are realized using \texttt{JUnit} and can be found in the subdirectory \texttt{tests} of the repository.
There are tests for the classes \texttt{Data} and \texttt{SSA}.

\subsubsection*{Tests for the Data class}

\paragraph{\texttt{testSetNumberOfEqualSizeEpochs()}}

This test checks whether an exception is thrown if we have less data points than epochs (in case of equally sized epochs).

\paragraph{\texttt{testSetCustomEpochDefinition()}}

This test checks whether an exception is thrown if we have less data points than epochs (in case of a custom epoch definition).

\subsubsection*{Tests for the SSA class}

\paragraph{\texttt{testOptimizeMeanCov()}}

This test checks whether an exception is thrown if the determinacy bound is violated (when using both means and covariance matrices).

\paragraph{\texttt{testOptimizeMean()}}

This test checks whether an exception is thrown if the determinacy bound is violated (when using means only).

\paragraph{\texttt{testOptimizeCovariance()}}

This test checks whether an exception is thrown if the determinacy bound is violated (when using covariance matrices only).

\paragraph{\texttt{testOptimize()}}

This function contains a simple test which checks
if the SSA optimization works correctly by running the optimization on a very simple data set. This data set is $2$-dimensional, where
the first dimension is stationary and the second one is non-stationary (this means the mixing matrix to be estimated is the identity matrix).
For checking the solution of the optimization, the angle between the estimated stationary projection direction and the correct one
$\begin{pmatrix} 1 \\ 0\end{pmatrix}$ is considered. The same is done with the estimated basis vector of the non-stationary subspace,
where the correct direction is $\begin{pmatrix} 0 \\ 1\end{pmatrix}$.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Contact and Support}

If you have any question, bug report or want to discuss the application of SSA
to a specific problem, please join the SSA mailing list:
\begin{center}
        \url{http://groups.google.com/group/ssa-list}
\end{center}
You can find further
information on the official SSA homepage:
\begin{center}
	\url{http://www.stationary-subspace-analysis.org}
\end{center}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newpage

\begin{appendices}

\section{Interpreting the objective function value}
\label{app:objfunval}

\newcommand{\emu}{\hat{\mu}}
\newcommand{\esi}{\hat{\Sigma}}

In practice, in order to assess a demixing found by the SSA algorithm, we need an interpretable
measure of  stationarity resp.~non-stationarity of the estimated stationary sources $\hat{s}^\s(t)$
and the estimated non-stationary sources $\hat{s}^\n(t)$. To that end, we can interpret
the SSA objective function from an hypothesis testing point of view. The SSA objective function
is equivalent to the likelihood-ratio test statistic for comparing two models for the data:
all epochs follow a multivariate standard normal distribution (null hypothesis $H_0$) vs.~the
more complex model where every epoch has a different mean and covariance matrix
(alternative hypothesis $H_A$). This also suggests a procedure for determining the number of
the stationary sources: we increase the number of stationary sources as long as the stationarity
test on the estimated \s-sources is not rejected.

More formally, let $X_1, \ldots, X_N$ be $d$-variate random variables
modeling the distribution of the data in the $N$ epochs. Formally, the hypothesis can
be written as follows.
\begin{align*}
	& H_0 : X_1, \ldots, X_N \sim \mathcal{N}(0, I) \\
	& H_A : X_1 \sim \mathcal{N}(\mu_1, \Sigma_1), \ldots, X_N \sim \mathcal{N}(\mu_N, \Sigma_N)
\end{align*}
In other words, the statistical test tells us whether we
should reject the simple model $H_0$ in favor of the more complex model $H_A$. This decision
is based on the value of the test statistics, whose distribution is known under the null hypothesis
$H_0$. Since $H_0$ is a special case of $H_A$ and since the parameter estimates are obtained by
Maximum Likelihood, we can use the likelihood ratio test statistic $\Lambda$,
which is the ratio of the likelihood of the data under $H_0$ and $H_A$, where the parameters are
their maximum likelihood estimates.
The likelihood ratio test statistic $\Lambda(\mathcal{X})$ is,
\begin{align}
\label{eq:teststat}
  \Lambda(\mathcal{X}) = -2 \log \frac{L_{H_0}(\mathcal{X})}{ L_A(\mathcal{X})},
%  \frac{ \prod_{x \in \mathcal{X}} p_{\mathcal{N}}(x ; 0, I)  }
%  {
%  	\prod_{i=1}^N \prod_{x \in \mathcal{T}_i} p_{\mathcal{N}}(x ; \emu^\n_i , \esi^\n_i)
%  }
\end{align}
where $L_{H_0}(\mathcal{X})$ is the likelihood of the data set under the simpler null model and
$L_A(\mathcal{X})$ is the likelihood of the data set under the more complex alternative model. In order
to find the estimated stationary sources $\hat{s}^\s(t)$, the SSA algorithm minimizes the test
statistic $\Lambda(\mathcal{X})$, i.e.~it maximizes the $p$-value to not reject the null
hypothesis of stationarity. Conversely, to estimate the most non-stationary sources
$\hat{s}^\n(t)$, we maximize $\Lambda(\mathcal{X})$ and thereby minimize the $p$-value.

Under the null hypothesis $H_0$, the test statistic $\Lambda(\mathcal{X})$ is approximately $\chi^2$ distributed with
$k = \frac{1}{2} N d (d+3)$ degrees of freedom. It can be shown that
$\sqrt{2 \Lambda(\mathcal{X})}$ converges (faster) to a Gaussian distribution
with mean $\mu_0 = \sqrt{2 k - 1}$ and unit standard deviation $\sigma_0 = 1$. We therefore
report the normalized objective function value,
\begin{align*}
	\Lambda'(\mathcal{X}) = \sqrt{2 \Lambda(\mathcal{X})} - \sqrt{2 k - 1},
\end{align*}
both for the estimated stationary and the estimated non-stationary sources. We can thus
derive approximate $p$-values for the stationarity test from the value of $\Lambda'(\mathcal{X})$
and the standard normal distribution.

\subsection{Derivation of the test statistic}

In this section we note the mathematical details for deriving the value of the test statistic (Equation~\ref{eq:teststat}).
Let $\mathcal{X} \subset \R^{d}$ be the data set which is divided into $N$ epochs
$\mathcal{T}_1 \cup \cdots \cup \mathcal{T}_n = \mathcal{X}$ with corresponding sample
sizes $N_i = | \mathcal{T}_i |$ for $1 \leq i \leq N$ and let $\emu_1, \ldots, \emu_N \in \R^d$
and $\esi_1, \ldots, \esi_N \in \R^{d \times d}$ be estimates of the epoch mean and epoch covariance matrices
respectively. Let $p_{\mathcal{N}}(x ; \mu, \Sigma)$ be the probability density function of the
multivariate Gaussian distribution. We have centered and whitened the data set such that,
\begin{align*}
	\sum_{i=1}^N \frac{N_i}{\sum_{j=1}^N N_j} \emu_i = 0 \; \text{ and } \; \sum_{i=1}^N \frac{N_i-1}{\sum_{j=1}^N (N_j -1)} \esi_i = I .
\end{align*}
The log-likelihood under $H_0$ is given by,
\begin{align*}
	\log L_{H_0}(\mathcal{X}) & = \sum_{i=1}^N \sum_{x \in \mathcal{T}_i} \log p_{\mathcal{N}}(x ; 0, I) \\
 & = -\frac{1}{2} \sum_{i=1}^N N_i d \log (2\pi) + \sum_{x \in \mathcal{T}_i} x^\top x \\
 &  = -\frac{1}{2} \sum_{i=1}^N N_i d \log (2\pi) + \trace \left[  \left( \sum_{x \in \mathcal{T}_i} x^\top x - \emu_i \emu^\top_i  \right)+ N_i \emu_i \emu^\top_i \right] \\
 & =  -\frac{1}{2} \sum_{i=1}^N N_i d \log (2\pi) + N_i \emu^\top_i \emu_i  + \trace \left[ (N_i-1) \esi_i \right] \\
 & =  -\frac{1}{2} \sum_{i=1}^N \left( N_i d \log (2\pi) + N_i \emu^\top_i \emu_i \right) + \left(\sum_{i=1}^n (N_i - 1)\right)  \trace\left[ I \right] \\
 & =  -\frac{1}{2} \sum_{i=1}^N  N_i d \log (2\pi) + N_i \emu^\top_i \emu_i + (N_i - 1) d .
\end{align*}
The log-likelihood under $H_A$ is given by,
\begin{align*}
	\log L_{H_A}(\mathcal{X}) & = \sum_{i=1}^N \sum_{x \in \mathcal{T}_i} \log p_{\mathcal{N}}(x ; \emu_i, \esi_i) \\
& = -\frac{1}{2} \sum_{i=1}^N N_i d \log (2\pi)  + N_i \log \det \esi_i + \sum_{x \in \mathcal{T}_i} (x-\emu_i)^\top \esi_i^{-1} (x-\emu_i) \\
& = -\frac{1}{2} \sum_{i=1}^N N_i d \log (2\pi)  + N_i \log \det \esi_i +
		\trace\left[ \sum_{x \in \mathcal{T}_i} (x-\emu_i) (x-\emu_i)^\top \esi_i^{-1} \right] \\
& = -\frac{1}{2} \sum_{i=1}^N N_i d \log (2\pi) + N_i \log \det \esi_i + \trace\left[  (N_i-1) \esi_i \esi_i^{-1} \right] \\
& = -\frac{1}{2} \sum_{i=1}^N N_i d \log (2\pi) + N_i \log \det \esi_i + (N_i-1) d .
\end{align*}
Thus the test statistic, and the SSA objective function, is given by
\begin{align*}
 \Lambda(\mathcal{X}) & = -2 ( \log L_{H_0} - \log L_{H_A} ) \\
 						& = \sum_{i=1}^N N_i \left(-\log \det\esi_i + \emu_i^\top \emu_i \right) .
\end{align*}

\section{Measuring the Error of SSA}
\label{app:error_measure}

In the case where the true solution (the mixing matrix $A$) is known, e.g.~in simulations
on synthetic data, we may want to measure the accuracy of the demixing estimated by the
SSA algorithm. Since only the non-stationary subspace (spanned
by the columns of $A^\n$) is identifiable, we measure the deviation between the true and the
estimated \n-space. To that end, we define a \textit{subspace error} based on the
\textit{principle angles} between two subspaces. Let $U$ and $V$ be two linear subspaces of the
vector space $\mathcal{V}$ with $\dim U \leq \dim V$. The first principle angle $\theta_1$ is
defined as the smallest angle between any two vectors $u \in U$ and $v \in V$,
\begin{align*}
	\theta_1 = \min \left. \left\{ \frac{ u^\top v }{ \| u \| \| v \| } \right| u \in U, v \in V \right\} = \angle(u_1, v_1),
\end{align*}
where the vectors $u_1$ and $v_1$ that minimize the angle are called the principle vectors.
The remaining principle angles $\theta_2, \ldots, \theta_{\dim U}$ are found recursively in the orthogonal
complement of the previous principle vectors,
\begin{align*}
	\theta_{k+1} = \min \left. \left\{ \frac{ u^\top v }{ \| u \| \| v \| } \right| u \in U, u \perp u_1, \ldots, u_k ,
			v \in V, v \perp v_1, \ldots, v_k \right\} .
\end{align*}
Thus the principle vectors in each subspace are mutually orthogonal. If a principle vector $\theta_k$ is zero
then $U$ and $V$ share a common subspace and $u_k,v_k \in U \cap V$. Hence the dimension of the intersection
of $U$ and $V$ is equivalent to the number of zero principle angles. The principle angles and vectors
can be found using the singular value decomposition (SVD). Let the columns of the matrices $U'$ and $V'$ be
orthonormal bases for the spaces $U$ and $V$ respectively. From the singular value decomposition
$\hat{U} \Sigma \hat{V}^\top = (U')^\top V'$ we obtain the principle angles from the singular values,
$\cos \theta_k = \Sigma_{kk}$ and the principle vectors are the columns of $\hat{U}$ and $\hat{V}$.

In order to quantify the difference between the true and the estimated stationary subspace
(spanned by the columns of $\hat{A}^\n$), we define the subspace error given the principle
angles $\theta_1, \ldots, \theta_{D-d}$ as
\begin{align*}
	\mathcal{E}(\hat{A}^\n , A^\n ) = \frac{1}{D-d} \sum_{i=1}^{D-d} \sin^2 (\theta_i) .
\end{align*}
This error is zero when the true subspaces are identical and one if they are orthogonal to
each other. The subspace error can be interpreted in terms of the sources. It is the
percentage of the signal power which a non-stationary sources loses if it is projected
from the true onto the estimated non-stationary sources. Conversely, for the estimated stationary
sources $\hat{s}^\s(t) = \hat{P}^\s x(t)$ this means that $\mathcal{E}(\hat{A}^\n , A^\n )$
is the percentage of non-stationary signal power that they contain.

The SSA Toolbox comes with a Matlab function \texttt{subspace\_error} that computes the subspace
error between two subspaces spanned by the columns of two matrices.

\end{appendices}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\newpage
\bibliographystyle{plain}
\bibliography{ssa.bib}

\end{document}


\section{Usage}
\begin{itemize}
  \item In order to use the Voice Activity Detector component properly,
        it must be clocked at 16\si{\mega\hertz}\footnote{This value has been
        arbitrarily chosen since it was not stated in the requirements. However,
        changing the operating frequency is pretty straightforward since it implies
        just changing the default value of the frame clocker.}, while samples will be fed
        into the VAD at a 16\si{\kilo\hertz} rate.
  \item In order to start feeding a frame into the VAD,
        \texttt{frame\_start} must be raised and kept high for 1 clock cycle
  \item After \texttt{frame\_start} has been raised,
        the first \texttt{x[15 downto 0]} input must be ready by
        and kept at least until the 499th clock.
  \item After the first sample, following samples must be ready by
        and kept until the $(499 + 1000n)$-th clock cycle, where
        $n = 1, \dots, N - 1$
  \item As soon as the threshold is exceeded the output will be raised.
        This means that for early detection (before remaining samples are
        processed) the output of the VAD can be sampled at the
        $(503 + 1000n)$-th clock cycle, with $n = 13, \dots, N - 1$. With fewer
        than 13 samples the partial energy can't be greater than the threshold.
        The output will be ready at last in 255503 clock cycles after having
        raised \texttt{frame\_start} for one clock cycle and will not change
        later on until a new frame is fed into the VAD.
\end{itemize}