\documentclass[main.tex]{subfiles}
\begin{document}

\subsection{Fermion masses and mixing}

\marginpar{Friday\\ 2021-12-10}

The full symmetry group of the standard model is
\(\text{SU}(3)_c \otimes \text{SU}(2)_L \otimes \text{U}(1)_Y\).

The building blocks are doublets like \((\nu_{eL}, e_L)\) with charges respectively
\(Q = 0\) and \(Q= -1\), as well as \(T_3 = +1/2\) and \(T_3 = -1/2\).

The right-handed singlets, on the other hand, also have \(Q = 0\) and \(Q=-1\)
but \(T = 0\).

Any right-handed neutrinos would be \emph{sterile}, since they do not interact.

This also holds for muonic and tauonic flavors,
as well as for quark doublets as long as we add \(2/3\) to all charges.

The relation between the quantum numbers is \(Y = 2 (Q-T_3)\).

In general the doublets look like
%
\begin{align}
\left[\begin{array}{c}
U^{\alpha } \\
D^{\alpha }
\end{array}\right]_L
\,,
\end{align}
%
where \(\alpha \) is a generation index.

The most general mass term looks like \(m \overline{\psi}_L \psi _R\) --- we should also
consider its Hermitian conjugate, but it works analogously.

As usual, we insert the Higgs field to saturate the doublets and diagonalize.
We will need to look at the effect of this change of basis on the mixing matrix.

The most general currents look like
%
\begin{align}
J^{\mu }_{EM} &= \sum _{\alpha } \overline{U}^{\alpha } \gamma^{\mu } U^{\alpha } + (U \to D)  \\
J^{\mu }_{NC} &= \sum _{\alpha } \overline{U}^{\alpha }_{L} \gamma^{\mu } (T_3 - Q s^2_W) U^{\alpha }_{L}
+ \sum _{\alpha } \overline{U}^{\alpha }_{R} \gamma^{\mu } (- Q s^2_W) U^{\alpha }_{R}  + (U \to D)  \\
J^{\mu }_{-} &= \sum _{\alpha} \overline{U}^{\alpha }_L \gamma^{\mu } D^{\alpha }_{L} (U \to D \text{ yields } J^{\mu }_{+})
\,.
\end{align}

The coupling terms then look like \(J^{\mu }_{EM} A_\mu \), \(J^{\mu }_{NC} Z_\mu \) and \(J^{\mu }_{\mp} W^{\pm}\).

The various components will transform according to some unitary matrices:
%
\begin{align}
D^{\alpha }_{R} &= W^{\alpha \beta } D^{\beta }_{R}
\qquad \text{and} \qquad
D^{\alpha }_{L} = S^{\alpha \beta } D^{\beta }_{L}  \\
U^{\alpha }_{R} &= T^{\alpha \beta } D^{\beta }_{R}
\qquad \text{and} \qquad
U^{\alpha }_{L} = R^{\alpha \beta } D^{\beta }_{L}
\,.
\end{align}

Most of the currents are left unchanged by these transformations;
the charged current however is the one which changes:
%
\begin{align}
J^{\mu }_{-} = \overline{U}_L \gamma^{\mu } \underbrace{R ^\dag S}_{\neq 1 \text{ in general}} D_L
\,.
\end{align}

The Yukawa Lagrangian will then include a term like
%
\begin{align}
\mathscr{L} \ni
\underbrace{\sum _{\alpha \beta } y^{\alpha \beta }_{D} \left[\begin{array}{cc}
\overline{U}^{\alpha } & \overline{D}^{\alpha }
\end{array}\right]_L
\left[\begin{array}{c}
0 \\
v / \sqrt{2}
\end{array}\right]
D^{\beta }_{R}}_{\text{D-type couplings}}
+ \underbrace{\sum _{ \alpha \beta } y^{\alpha \beta }_{U}
\left[\begin{array}{cc}
\overline{U}^{\alpha } & \overline{D}^{\alpha }
\end{array}\right]_L
\left[\begin{array}{c}
v / \sqrt{2} \\
0
\end{array}\right]
U^{\beta }_R}_{\text{U-type couplings}}
\,.
\end{align}

We define a mass matrix
%
\begin{align}
M^{\alpha \beta }_{U, D} = y^{\alpha \beta }_{U, D} \frac{v}{\sqrt{2}}
\,,
\end{align}
%
so that
%
\begin{align}
\mathscr{L} \ni \overline{D}_L M_D D_R + \overline{U}_L M_U U_R +
\text{h. c. }
\,.
\end{align}

How can we put the Higgs vacuum on the upper component?
We can define \(\widetilde{\phi} = i \sigma _2 \phi^{*}\).
For this field, the 1 component has zero charge while the 2 component has \(-1\) charge.

If we introduce this field, the charge of the Yukawa Lagrangian is zero.

Each of the \(M_{U, D}\) matrices will be diagonalized like \(S ^\dag M T = M _{\text{diag}}\), where \(S\) and \(T\) are both unitary.

We then have, for down-type fields: \(\overline{D}_L M_D D_R\) going into
%
\begin{align}
D_R \to W D_R \qquad D_L \to S D_L \qquad M_D \to M_D^{\text{diag}}
\,,
\end{align}
%
while \(\overline{U}_R M_U U_R\) becomes
%
\begin{align}
U_R \to T U_R \qquad U_L \to R U_L \qquad M_U \to M_U^{\text{diag}}
\,,
\end{align}
%

In general, these will be different matrices for leptons and for quarks.

The charged current then reads \(J^{\mu }_{-} = \overline{U}_L \gamma^{\mu } V D_L\), where \(V = R ^\dag S\).

More explicitly, we get
%
\begin{align}
J^{\mu }_{-} \overline{U}^{\alpha }_{L} \gamma^{\mu } V^{\alpha \beta } D^{\beta }_{L}
\,.
\end{align}

The interaction of a \(\overline{U}^{\alpha }_L\) and \(D^{\beta }_{L}\) is then modulated by a factor \((g/\sqrt{2}) V^{\alpha \beta }\).

If \(V\) were 2x2 it would be a real matrix, if it were 3x3 it would be a complex matrix.

For quarks, the values on the diagonal are close to 1, while the largest values off-diagonal are of the order \num{.22} for the CKM matrix, the mass-mixing matrix for quarks.

For example, in \(\beta \) decay we get a modulation by a factor \(V_{ud}\), which is slightly less than 1.

For leptons, the matrix is called PMNS.

In the usual construction of the Standard Model, there were no mass terms for neutrinos or right-handed \(\nu_{\alpha R}\).
Therefore, in this case there could be no mixing among leptons, since the mixing matrix only ever appears ``sandwitched''.

The basic definition of neutrino flavor is ``which lepton does it have charged current interactions with''.

For example, \(\nu _e\) is the \(\nu \) produced in \(\beta^{+} \) decay, and \(\overline{\nu}_e\) is the \(\nu \) produced in \(\beta^{-}\) decay.

Let us then consider \(\nu _e \to \nu _\mu  \) oscillations.
We always need to consider the amplitudes for production, propagation, detection.

However, it is convenient to isolate the propagation into the matrix
%
\begin{align}
\left[\begin{array}{c}
\nu _e \\
\nu _\mu  \\
\nu _\tau
\end{array}\right]
=
\left[\begin{array}{ccc}
U_{e1} & U_{e2} & U_{e3} \\
U_{\mu 1} & U_{\mu 2} & U_{\mu 3} \\
U_{\tau 1} & U_{\tau 2} & U_{\tau 3}
\end{array}\right]
\,.
\end{align}

Forgetting the fact that this is a simplification can lead to paradoxes;
for example, ether leptons do not oscillate.

There is a basis for the Dirac equation for which \(i \gamma^{\mu }\) is real --- this leads to the fact that \(\psi = \psi^{*}\).

This cannot work for electrons and positrons, since they are charged.
A neutral fermion, on the other hand, might be its own antiparticle.

If we have a \(\beta^{+}\) decay, we will produce a \(\nu _e\) which is left-handed.
In a \(\beta^{-}\) decay, on the other hand, we will produce a right-handed \(\overline{\nu}_e\).

If the neutrino is massless, this cannot change.
Formally, the Dirac equation decouples.

This ``Weyl'' case is not completely excluded by current phenomenology; the lightest of the neutrinos could be completely massless.

If we have massive neutrinos, though, there will be an \(\order{m_\nu / E}\) component with the opposite chirality.

However, the neutrino and antineutrino are still distinguishable.

If they are Majorana, on the other hand, \(\nu_e = \overline{\nu}_e\); this must mean that they are neutral not just for electric charge but for all charges.

We have observed inverse beta decay:
%
\begin{align}
\nu _e + \ce{n} \to \ce{p} + e^{-}
\qquad \text{and} \qquad
\overline{\nu} _e + \ce{p} \to \ce{n} + e^{+}
\,,
\end{align}
%
but not the same reaction for \(\nu _e \leftrightarrow \overline{\nu}_e\).
Is this an indication that neutrinos are indeed Dirac?

Well, if neutrinos are indeed Majorana these reactions are possible, but suppressed at order \(m_\nu / E\)!

The experiment which saw the largest number of neutrinos collected about 2 million events\dots

The way to have good statistics is to look at decays, specifically neutrinoless double-beta decay.

The decay looks like
%
\begin{align}
\{ 2 n \} \to
\{ 2 p \} + 2 e^{-}
\,.
\end{align}

The decay of the first proton looks like the emission of a right-handed \(\overline{\nu}_e\) with an \(e^{-}\), through a charged-current interaction.

IF \(m_\nu \neq 0\), the neutrino has a left-handed component (not possible if the neutrino is Weyl);
if \(\nu = \overline{\nu}\), this left-handed component is a left-handed \(\nu _e\) (not possible if the neutrino is Dirac)!

At the second proton, the left-handed \(\nu _e\) is absorbed and an \(e^{-}\) is emitted.

This process is suppressed by \(m_\nu / E\): it probes absolute neutrino mass.

Current neutrinoless double beta decay are probing lifetimes of the order of \(\num{e26}\) to \(\SI{e27}{yr}\).

It can be shown that if this process takes place, then neutrinos must be Majorana.

Pictorially, one can join the legs of the \(0 \nu \beta \beta \) diagram to find a diagram which turns a \(\nu _e\) into a \(\overline{\nu}_e\).

\end{document}


\newcommand{\baselineAlgorithm}{%
\begin{algorithm}
\SetAlgoLined
$i = 0$\;
\lnl{loop} \While{i $<$ d}{
$l = h_i(ikey)$\;
\uIf{$key_l = ikey$}{$val_l$++; end\;}
\uElseIf{$val_l = 0$}{l = (ikey, 1); end\;}
\Else{$min = update(min)$\;}
$i$++\;
}
\uIf{$i = d$}{$min = (ikey, val_{min} + 1)$\;}
\end{algorithm}}

\newcommand{\OurAlgorithm}{%
\begin{algorithm}
\SetAlgoLined
$i = 0, cKey = iKey, cVal = 1$\;
\lnl{loop} \While{i $<$ d}{
$l = h_i(cKey)$\;
\uIf{$key_l = ckey$}{$val_l$ += $cVal$; end\;}
\uElseIf{$val_l = 0$}{l = (ckey, cVal); end\;}
\uElseIf{$val_l < cVal$}{swap $(key_l, val_l)$ with $(cKey, cVal)$\;}
$i$++\;
}
\end{algorithm}}

\section{HashPipe based Heavy Hitter Algorithm}\label{sec:algorithm}

As described in \Sec{sec:related}, \TheSystem is heavily inspired by the \spacesaving algorithm \cite{metwally2005efficient}, which we describe now
(\Sec{sec:spacesaving}). In the later subsections
(\Sec{sec:sampling-d}-\Sec{sec:feed-forward}), we describe our modifications to
the algorithm to make it amenable to switch implementation.
%

\subsection{\spacesaving\ Algorithm}
\label{sec:spacesaving}

To track the $k$ heaviest items, \spacesaving uses a table with $m$ (which is
$O(k)$) slots, each of which identifies a distinct flow key and its counter. All
slots are initially empty, \ie keys and counters are set to zero.

\begin{algorithm}
\DontPrintSemicolon % Some LaTeX compilers require you to use
% \dontprintsemicolon instead
\Comment{Table $T$ has $m$ slots, either containing $(key_j, val_j)$ at slot $j
  \in \{1, \ldots, m\}$, or empty. Incoming packet has key $iKey$.}\;

\eIf{$\exists$ slot $j$ in $T$ with $iKey = key_j$}{
  $val_j \gets val_j + 1$\;
}{
  \eIf{$\exists$ empty slot $j$ in $T$}{
    $(key_j, val_j) \gets (iKey, 1)$\;
  }{
    $m \gets argmin_{j \in \{1,\ldots,m\}}(val_j)$\;\label{alg:ss:minfind}
    $(key_m, val_m) \gets (iKey, val_m+1)$\;
  }
}
%% $min \gets 1$\;
%% \For{$i \gets 2$ \textbf{to} $m$} {
%%   \If{$val_i < val_{min}$} {
%%     $min \gets i$\;
%%   }
%% }
%% $min \gets (iKey, val_{min} + 1)$\;
\caption{\spacesaving algorithm~\cite{metwally2005efficient}}
\label{algo:spacesaving}
\end{algorithm}

The algorithm is summarized in \Alg{spacesaving}.\footnote{We show the algorithm
  for packet counting; it easily generalizes to byte counts.}
%
When a packet arrives, if its corresponding flow isn't already in the table, and
there is space left in the table, \spacesaving inserts the new flow with a count
of 1. If the flow is present in the table, the algorithm updates the
corresponding flow counter. However, if the table is full, and the flow isn't
found in the table, the algorithm replaces the flow entry that has the {\em
  minimum} counter value in the table with the incoming packet's flow, and
increments this minimum-valued counter.

This algorithm has three useful accuracy properties~\cite{metwally2005efficient}
that we list here. Suppose the true count of flow $key_j$ is $c_j$, and its
count in the table is $val_j$. First, no flow counter in the table is ever
underestimated, \ie $val_j \geq c_j$.
%%  since counters are never
%% decremented and consequently, the minimum is increasing.
Second, the minimum value in the table $val_m$ is an upper bound on the
overestimation error of any counter, \ie $val_j \leq c_j + val_m$.
%% This is because when a flow's counter is initialized with $val_m + 1$, its
%% value is overestimated by at most $val_m$ (if it was a brand new flow that
%% should have otherwise had a counter value $1$).
Finally, any flow with true count higher than the average table count, \ie $c_j
> C/m$, will always be present in the table (here $C$ is the total packet count
added into the table). This last error guarantee is particularly useful for the
threshold-heavy-hitter problem (\Sec{sec:problem}), since by using $1/t$
counters, we can extract all flows whose true count exceeds a threshold $t$ of
the total count. However, this guarantee cannot be extended directly to the
top-$k$ problem, since due to the heavy-tailed nature of
traffic~\cite{estan2002new}, the $k$th heaviest flow contributes nowhere close
to $1/k$th of total traffic.

However, the algorithm step of finding the minimum counter in the table (line
\ref{alg:ss:minfind})---possibly for each packet---is difficult within switch
hardware constraints (\Sec{sec:related}).
%
In the following subsections, we discuss how we incrementally modify the
\spacesaving algorithm to run on hardware switches.

%% While this seems like the best way to approach this problem, this is not
%% feasible in practice since it needs one to examine the entire list (entries in
%% the form of a table) which is not feasible at line-rate. Alternatively, one
%% could use a sorted data structure like a heap that would maintain the
%% minimum. However, complex data structures like heaps or sorted lists do not
%% involve deterministically O(1) cost per packet since once in a while, the
%% compression process for preserving order could involve an O(k) operation. Hence,
%% we need a different version amenable on hardware. \jrex{nice paragraph but very
%%   terse if readers haven't seen these algorithms before. also, in the
%%   pseudocode, min is sometimes a single number and sometimes a tuple}

\subsection{Sampling for the Minimum Value}
\label{sec:sampling-d}

The first simplification we make is to look at the minimum of a small, {\em
  constant} number $d$ of randomly chosen counters, instead of the entire table
(in line \ref{alg:ss:minfind}, \Alg{spacesaving}). This restricts the worst-case
number of memory accesses per packet to a small fixed constant $d$.  The
modified version, \Baseline, is shown in \Alg{Baseline}. The main change from
\Alg{spacesaving} is in the set of table slots examined (while looking up or
updating any key), which is now a set of $d$ slots obtained by hashing the
incoming key using $d$ independent hash functions.

In effect, we {\em sample} the table to estimate a minimum using a few
locations. However, the minimum of just $d$ slots can be far from the minimum of
the entire table of $m$ slots. An inflated value of the minimum could impact the
useful error guarantees of \spacesaving (\Sec{sec:spacesaving}). However, we
show analytically that the overestimation error is not too far from the average
table count $C/m$ with high probability. Further, our
evaluations in \Sec{subsec:comparisonIdeal} show that the distributions of the
minimum of the entire table and of the subsample are comparable.

%% In order to determine the minimum among the entries of a hash table, one would
%% usually need to scan all the complete set of key-value pairs. However, given
%% that that is not feasible, and that only reading a small constant number of
%% locations would be feasible, we attempt to approximate the minimum by reading
%% these locations alone and finding the minimum among them. Section
%% \ignore{include eval} shows that this process of approximating the minimum
%% results in an approximation that is reasonably close to the minimum of the
%% entire table. Independent hash functions are used to pick the indices from where
%% the values would be read to approximate the minimum.

%% the switch to generate multiple indices
%% in the same table by hashing on the incoming flow with $d$ different hash
%% functions. Further,

However, \Alg{Baseline} still requires the switch to read $d$ locations at once
to determine their minimum, and then write back the updated value. This
necessitates a read-modify-write operation, involving $d$ reads and one write
{\em anywhere in table memory}, within the per-packet time budget. However,
multiple reads to the same table ($d > 1$) are supported neither in switch
programming languages today~\cite{bosshart2014p4} nor in emerging programmable
switching chips~\cite{RMT}. Further, supporting multiple reads for every packet
at line rate requires multiported memories with strict access-latency
guarantees, which can be quite expensive in terms of area and
power~\cite{cmos-vlsi-design-book, vlsi-memory-lecture}.

\subsection{Multiple Stages of Hash Tables}
\label{sec:multiple-stages-d}
The next step is to reduce the number of reads to memory to facilitate operation
at line rate. We split the counter table $T$ into $d$ disjoint tables, and we
read exactly one slot per table. The algorithm is exactly the same as
\Alg{Baseline}; except that now hash function $h_i$ returns only slots in the
$i$th stage.

This design enables pipelining the memory accesses to the $d$ tables, since
different packets can access different tables at the same time. However, packets
may need to make two passes through this pipeline: once to determine the counter
with the minimum value among $d$ slots, and a second time to update that
counter. The second pass is possible through ``recirculation'' of packets
through the switching pipeline~\cite{p4-v1.1-spec, ovs-packet-recirculation,
  arista-7050-datasheet} with additional metadata on the packet, allowing the
switch to increment the minimum-valued counter in the second pass. However, the
second pass is potentially needed for {\em every packet}, and recirculating
every packet can halve the pipeline bandwidth available to process packets.

%% We essentially use $d$ different hash functions on the incoming flow’s key, one
%% per stage to pick exactly one location amongst the entries per stage. In this
%% manner, we are able to reduce the number of reads to one per-stage and carry
%% over the read values as metadata. The computation of the minimum can be done
%% using this state carried over at the end of the processing pipeline. However, if
%% the location where the new flow is to be rewritten is anything other than the
%% last stage, this would pose a problem. The feed-forward \ignore{cite}
%% restriction implies that a packet cannot make modifications to earlier stages in
%% the pipeline once it has passed through them. Hence, if this model was to work,
%% the packet would need to be recirculated into the pipeline and all incoming
%% packets would have to be stalled until the current packet finishes modification
%% to the appropriate pipelined stage. Clearly, this wouldn’t be feasible at line
%% rate where each stage processes a packet independently and atomically in a
%% pipelined fashion to speed up processing.

\begin{algorithm}
\DontPrintSemicolon % Some LaTeX compilers require you to use \dontprintsemicolon instead
%\KwIn{A finite set $A=\{a_1, a_2, \ldots, a_n\}$ of integers}
%\KwOut{The largest element in the set}
\Comment{Hash functions $h_i(iKey) \rightarrow$ slots, $i \in \{1,\dots,d\}$}\;

%% \For{$i \gets 1 $ \textbf{to} $d$} {
%% $l \gets h_i(ikey)$\;
%%   \If{$key_l = iKey$} {
%%     $val_l \gets val_l + 1$;\;
%%   }
%%   \ElseIf{$val_l = 0$}{
%%   	$(key_l,val_l) \gets (iKey, 1)$;\;
%%   }
%%   \Else{
%%   	$minLoc = update(minLoc)$
%%   }
%% }
%% \If{$i > d$}{$ minLoc \gets (ikey, val_{minLoc} + 1)$\;}

$H = \{h_1(iKey), \ldots, h_d(iKey)\}$\;
\eIf{$\exists$ slot $j \in H$ with $iKey = key_j$}{
  $val_j \gets val_j + 1$\;
}{
  \eIf{$\exists$ empty slot $j \in H$}{
    $(key_j, val_j) \gets (iKey, 1)$\;
  }{
    $m \gets argmin_{j \in H}(val_j)$\;\label{alg:hp:minfind}
    $(key_m, val_m) \gets (iKey, val_m+1)$\;
  }
}

\caption{\Baseline: Sample $d$ slots at once}
\label{algo:Baseline}
\end{algorithm}

\subsection{Feed-Forward Packet Processing}
\label{sec:feed-forward}
We now alleviate the need to process a packet more than once through the switch
pipeline, using two key ideas.

\begin{figure*}[h]
  \begin{subfigure}[b]{0.45\linewidth}
    \centering
    \includegraphics[width=0.75\linewidth, height=2.5cm]{entry.png}
    \caption{Initial status of table}
    \label{alg:a}
    \vspace{4ex}
  \end{subfigure}%%
  \begin{subfigure}[b]{0.45\linewidth}
    \centering
    \includegraphics[width=0.75\linewidth, height=2.5cm]{2nd_stage.png}
    \caption{New flow is placed with value $1$ in first stage of table}
    \label{alg:b}
    \vspace{4ex}
  \end{subfigure}
  \begin{subfigure}[b]{0.45\linewidth}
    \centering
    \includegraphics[width=0.75\linewidth, height=2.5cm]{3rd_stage.png}
    \caption{$B$ being larger evicts $E$}
    \label{alg:c}
  \end{subfigure}%%
  \begin{subfigure}[b]{0.45\linewidth}
    \centering
    \includegraphics[width=0.75\linewidth, height=2.5cm]{final_stage.png}
    \caption{$L$ being larger is retained in the table}
    \label{alg:d}
  \end{subfigure}
  \\
  \caption{An illustration of \TheSystem.}
  \label{fig:HashPipe}
\end{figure*}

\NewPara{Track a rolling minimum.} We track the minimum counter value seen so
far (and its key) as the packet traverses the pipeline, by {\em moving} the
counter and key through the pipeline as {\em packet metadata.} Emerging
programmable switches allow the use of such metadata to communicate results of
packet processing between different stages, and such metadata can be written to
at any stage, and used for packet matching at a later stage~\cite{p4-v1.1-spec}.

\begin{algorithm}
\DontPrintSemicolon % Some LaTeX compilers require you to use \dontprintsemicolon instead
%\KwIn{A finite set $A=\{a_1, a_2, \ldots, a_n\}$ of integers}
%\KwOut{The largest element in the set}
\Comment{Insert in the first stage}\;
$l_1 \gets h_1(iKey)$\;
\If{$key_{l_1} = iKey$}{
  $val_{l_1} \gets val_{l_1} + 1$\;
  end processing\;
}\ElseIf{$l_1$ is an empty slot}{
  $(key_{l_1}, val_{l_1}) \gets (iKey, 1)$\;
  end processing\;
}\Else{
  $(cKey, cVal) \gets (key_{l_1}, val_{l_1})$\;
  $(key_{l_1}, val_{l_1}) \gets (iKey, 1)$\;
}
\Comment{Track a rolling minimum}\;
\For{$i \gets 2$ \textbf{to} $d$} {
$l \gets h_i(cKey)$\;
  \If{$key_l = cKey$} {
    $val_l \gets val_l + cVal$\;
    end processing\;
  }
  \ElseIf{$l$ is an empty slot}{
    $(key_l, val_l) \gets (cKey, CVal)$\;
    end processing\;
  }
  \ElseIf{$val_l < cVal$}{
    swap $(cKey, cVal)$ with $(key_l, val_l)$
  }
}
\caption{\TheSystem: Pipeline of $d$ hash tables}
\label{algo:Sequential}
\end{algorithm}

As the packet moves through the pipeline, the switch hashes into each stage on
the {\em carried key,} instead of hashing on the key corresponding to the
incoming packet. If the keys match in the table, or the slot is empty, the
counter is updated in the usual way, and the key need no longer be carried
forward with the packet. Otherwise, the keys and counts corresponding to the
{\em larger} of the counters that is carried and the one in the slot is written
back into the table, and the smaller of the two is carried on the packet. We
leverage arithmetic and logical action operations available in the match-action
tables in emerging switches~\cite{RMT} to implement the counter comparison. The
key may be carried to the next stage, or evicted completely from the tables when
the packet reaches the last (\ie $d$th) stage.

\NewPara{Always insert in the first stage.} If the incoming key isn't found in
the first stage in the pipeline, there is no associated counter value to compare
with the key that is in that table. Here, we choose to {\em always insert the
  new flow} in the first stage, and evict the existing key and counter into
packet metadata. After this stage, the packet can track the rolling minimum of
the {\em subsequent stages} in the usual way described above. The final
algorithm, \TheSystem, is shown in \Alg{Sequential}.

One consequence of always inserting an incoming key in the first stage is the
possibility of duplicate keys across different tables in the pipeline, since the
key can exist at a later stage in the pipeline. Note that this is unavoidable
when packets only move once through the pipeline. It is possible that such
duplicates may occupy space in the table, leaving fewer slots for heavy flows,
and causing evictions of heavy flows whose counts may be split across the
duplicate entries.

\label{sec:coalescing}
However, many of these duplicates are easily {\em merged} through the algorithm
itself, \ie the minimum tracking merges counters when the carried key has a
``hit'' in the table. Further, switches can easily estimate the flow count
corresponding to any packet in the data plane itself by summing all the matching
flow counters; so can a data collector, after reading the tables out of the
switch. We also show in our evaluations (\Sec{subsec:sensitivity}) that
  duplicates only have a small effect on the memory available to heavy keys in the table.

\Fig{HashPipe} illustrates an example of processing a packet using \TheSystem. A
packet with a key $K$ enters the switch pipeline (a), and since it isn't found
in the first table, it is inserted there (b). Key $B$ (that was in the slot
currently occupied by $K$) is carried with the packet to the next stage, where
it hashes to the slot containing key $E$. But since the count of $B$ is larger
than that of $E$, $B$ is written to the table and $E$ is carried out on the
packet instead (c). Finally, since the count of $L$ (that $E$ hashes to) is
larger than that of $E$, $L$ stays in the table (d). The net effect is that the new
key $K$ is inserted in the table, and the minimum of the three keys $B$, $E$, and
$L$---namely $E$---is evicted in its favor.

%% The only way to fix the need for packet recirculation would be to make a local
%% approximation as a packet passes through a particular stage in the packet
%% processing pipeline as to what the minimum across the $d$ stages might be. What
%% this means is that we hash on the incoming flow’s key in the first stage and
%% update its counter if it is present in the corresponding location. If not, we
%% treat it as a new key and insert the flow with value 1 in the first table stage,
%% evicting any other flow that might be present in that location. In all further
%% table stages, we carry a flow with a count as metadata on the packet. This
%% carried flow represents the current minimum as observed upon passing the current
%% table stage.

%% At every table stage, based on the carried flow, its count and the flow and its
%% count in the location that the carried flow hashes to (when hashed using the
%% hash function in this particular stage), we make a local choice in favor of
%% retaining the flow with a heavier count. Of course, if any location that the
%% carried flow hashes to is empty, we place the flow and count there and zero out
%% the packet metadata fields so that they do not affect any subsequent
%% stages. When a packet finishes the entire pipeline, the consequence is that the
%% ultimate flow evicted out of the table is a relative minimum and all
%% intermediate flows are given a chance to be placed again in a future table stage
%% if there are smaller flows in later tables.

%%\subsection{Coalescing Duplicate Keys}

%% The one issue with the above mentioned algorithm is that the incoming flow is
%% placed in the first stage without any knowledge on whether this flows is present
%% at a later table stage or not. To get around this, we ensure that if the key
%% being carried is the same as the key present in the location it hashes to, we
%% coalesce the two values, the carried one with the one present in the table. We
%% also expect the controller to interpret the actual count associated with a flow
%% as the sum of the counts in the multiple occurrences of the flow in the
%% table. We show in our evaluations that despite the presence of duplicates, and
%% increased number of evictions by smaller flows due to the presence of split
%% counts for each flow\ignore{explain more?}, our algorithm performs
%% well\ignore{refer right place}. The final algorithm is detailed in
%% \ignore{refer}.

%\subsection{Baseline Implementation/ All Probes at once}

%Given that we are interested in the top $k$ keys by value or count, the most unlikely candidate would be the key with the least value amongst the keys in the $d$ locations if a given incoming key is competing with $d$ keys at the locations its hashes to across $d$ tables. Hence, the most basic modification of the d-left hashing scheme to determine the heavy hitters involves an update to the existing location if the key is already present or insertion of the new key into the leftmost empty location if there is one or eviction of the key with the least value amongst the $d$ candidate keys. When replacing this minimum entry with the new key, the value assigned to it could be $1$, if treated as a brand new flow or the current minimum value + 1, as done in . This translates to the algorithm in %Fig:~\ref{Basic Implementation}%
%which generically calls the value "newVal". In order to reduce the number of passes through the hash table, the minimum amongst the $d$ locations is found as the algorithm looks for the leftmost empty location or the key itself for a given incoming key. This algorithm is hard to implement in practice though since the collision handling mechanism requires one to go back to a previously traversed table stage after determining the minimum and make a modification to it for a given packet that has already passed through these tables in the packet processing pipeline. This would cause a lot of delay and is very impractical.

%\subsection{Sequential Probes/Feed Forward}

%Since the ultimate goal is to implement the algorithm on hardware and multi-ported reads would involve more combinational circuits, reducing the number of lookups per stage could also be useful. Hence, instead of hashing on both the evicted key from a previous table stage and the original key like the algorithm in Section 6.3, we limit ourselves to hashing only on the evicted key or the key being carried and finding a location for it. However, this approach could leave us with multiple occurences of the same key with different values that we aren't even aware of since we are no longer looking for it and updating those values. However, our simulation show that this is still reasonable, as long as the controller is reading and interpreting these values correctly and associating the sum across the multiple values as the real value associated with a particular key (since the values are split acorss multiple occurences in this case). The algorithm is detailed on the right side of %Fig:~\ref{fig:HardwareImplementable}.

%The one downside of this approach is that if the value of a key is split between two locations with neither of them individually high enough relative to the values of other keys even though their sum (the actual value associated with that flow) is high enough to make that flow a heavy hitter, the chances of all occurences of that key being evicted are fairly high. The multiple lookup case (Section 6.3), on the other hand, tries to address this by making the values in the later table stages more accurate and hence, more robust to eviction.


\subsection{Maximum Likelihood Estimation (MLE) for generative and discriminative models}


\documentclass[english]{pkupaper}

\usepackage{lipsum}
\usepackage{essay-def}
\usepackage{clrscode}
\usepackage{appendix}
\usepackage{mathrsfs}
\newcommand{\ind}{\ \ \ }
\newenvironment{eqt}{\begin{equation}\begin{aligned}}{\end{aligned}\end{equation}}
\usepackage{indentfirst}
\usepackage{algorithm}
\usepackage{algorithmic}
\usepackage{multirow}
\usepackage{makecell}
\renewcommand{\algorithmicrequire}{\textbf{Input:}}
\renewcommand{\algorithmicensure}{\textbf{Output:}}

\newcommand{\titlemark}{Final Report: Algorithms for large-scale optimal transport}

\DeclareRobustCommand{\authorthing}{
\begin{tabular}{cc}
汪祎非\thanks{The authors are arranged lexicographically.} & 朱峰\thanksmark{1} \\
1500010611 & 1600010643
\end{tabular}
}
\title{\titlemark}
\author{\authorthing}
\date{}
\bibliography{DeepL}
\begin{document}
\maketitle
\section*{Statement}
The main content of this project is not used as course project or assignment in other courses.

\section{Introduction}
According to \cite{COT}, optimal transport is a mathematical gem at the interface between probability, analysis and optimization. The theoretical importance of OT is that it defines a metric between probability distributions, namely, Wasserstein metric. It reveals a canonical geometric structure with rich properties to be exploited.  The earliest contribution to OT originated from Monge in 18th century. Kantorovich rediscovered it under a different formalism, namely the Linear Programming formulation of OT. With the development of scalable solvers, OT is widely applied to problems in imaging sciences(color and texture processing), computer vision and machine learning(regression).

In this report, we focus on the LP formulation and the Entropy Regularization of optimal transport. Our report is organized as follows. In Section \ref{sec:2}, we propose three first-order methods and introduce Bregman ADMM. In Appendix we also introduce a splitting method with penalty functions. The Entropy Regularization of optimal transport and Sinkhorn's algorithm is presented in Section \ref{sec:3}. We further propose an improvement of Sinkhorn's algorithm and ADMM for Entropy Regularization. Section \ref{sec:4} presents five datasets and contains comprehensive numerical experiments. In Section \ref{sec:5}, we conclude our work.

Question 1(a) is answered in Section 4.2. Question 1(b) is answered in Section 2. Question 2 is answered in Section 3. The numerical results of all questions are provided in Section 4. The division of our work is listed in Acknowledgement (in the end of our report).

\section{First Order Methods for Optimal Transport}
\label{sec:2}
We consider to solve the standard form of Linear Programming (LP).
\begin{equation}
\label{lp}
\begin{aligned}
\min\limits_{\pi\in\mbR^{m\times n}}&\sum_{i=1}^m\sum_{j=1}^nC_{i,j}\pi_{i,j}\\
s.t.&\sum_{j=1}^n\pi_{i,j}=\mu_i, \, \forall i=1, 2, \dots m\\
&\sum_{i=1}^m\pi_{i,j}=\nu_j , \, \forall j=1, 2, \dots n\\
&\pi_{i,j}\geqslant0
\end{aligned}
\end{equation}
To ensure that the feasible set for problem \ref{lp} is non-empty, we assume that $\mu_i\geqslant 0, \nu_j\geqslant0$ and $\sum_{i=1}^m\mu_i=\sum_{j=1}^n\nu_j$. Without loss of generality, we further assume $C_{i,j}\geqslant 0$ and $\sum_{i=1}^m\mu_i=\sum_{j=1}^n\nu_j=1$. Else we could add a positive constant on $C_{i, j}$ and divide $\mu_i$ and $\nu_j$ by $\sum_{i=1}^m\mu_i=\sum_{j=1}^n\nu_j$.

\subsection{ADMM: Complete Splitting}
\subsubsection{ADMM for primal}
We introduce a new variable $\tilde \pi \in \mbR^{m\times n}$ and split the constraints into two sets $\{\pi\in \mbR^{m\times n}| \sum_{j=1}^n\pi_{i,j}=\mu_i, \sum_{i=1}^m\pi_{i,j}=\nu_j\}$ and $\{\tilde\pi\in \mbR^{m\times n}|\tilde\pi\geq0\}$. Then we rewrite the LP problem \ref{lp} in the following form,
\begin{equation}
\label{new_lp}
\begin{aligned}
\min\limits_{\pi\in\mbR^{m\times n}}&\sum_{i=1}^m\sum_{j=1}^nC_{i,j}\pi_{i,j}\\
\text{s.t.}&\sum_{j=1}^n\pi_{i,j}=\mu_i,\quad \sum_{i=1}^m\pi_{i,j}=\nu_j\\
&\pi_{i,j} = \tilde\pi_{i,j}, \quad \tilde\pi_{i,j}\geqslant0
\end{aligned}
\end{equation}
Then we write down its augmented Lagrangian function as follows,
\begin{eqt}
&L_t(\pi, \tilde{\pi}, \gamma, \lambda, \omega) \\
= &  \sum_{i, j}C_{i,j}\pi_{i,j} + \sum_{i}\gamma_i(\mu_i-\sum_{j}\pi_{i,j}) + \sum_{j}\lambda_j(\nu_j-\sum_i\pi_{i,j}) + \sum_{i, j}\omega_{i,j}(\tilde{\pi}_{i,j}-\pi_{i,j}) \\
&+ \frac{t}{2}\left(\sum_{i}(\mu_i-\sum_{j}\pi_{i,j})^2 + \sum_{j}(\nu_j-\sum_{i}\pi_{i,j})^2 + \sum_{i, j}(\tilde{\pi}_{i,j}-\pi_{i,j})^2\right)
\end{eqt}
where $\gamma\in\mathbb{R}^{m\times 1}, \lambda\in\mathbb{R}^{1\times n}, \omega\in\mathbb{R}^{m\times n}, \tilde{\pi}\in\mathbb{R}^{m\times n}, \tilde{\pi}_{i,j}\geqslant 0$.

For the update of $\pi_{i,j}$, since $L$ is strongly convex with $\pi_{i,j}$, we set $\frac{\partial L}{\partial \pi_{ij}}$ to zero and yields
\begin{eqt}
\pi_{i,j} + \sum_{k}\pi_{i,k} + \sum_{k}\pi_{k,j} = \frac{1}{t}(\gamma_{i}+\lambda_{j}+\omega_{i,j}-c_{i,j}) + \mu_{i} + \nu_{j} + \tilde{\pi}_{i,j}\triangleq x_{i,j} \label{pi}
\end{eqt}
Though a bit complicated, (\ref{pi}) can be solved in closed form,
\begin{eqt}
\label{upd_pi}
\pi_{i,j} \gets x_{i,j} & - \frac{1}{m+1}\left(\sum_kx_{k,j} - \frac{1}{m+n+1}\sum_{k, l}x_{k,l}\right)
\\& - \frac{1}{n+1}\left(\sum_kx_{i,k}-\frac{1}{m+n+1}\sum_{k, l}x_{k,l}\right)
\end{eqt}

To update $\tilde{\pi}_{i,j}$, it's easy to compute that
\begin{eqt}
\label{upd_pit}
\tilde{\pi}_{i,j} \gets (\pi_{i,j}-\frac{\omega_{i,j}}{t})_+
\end{eqt}

For the update of multipliers, we have
\begin{eqt}
& \gamma_{i} \gets \gamma_i + t(\mu_i - \sum_k\pi_{i,k}) \\
& \lambda_{j} \gets \lambda_j + t(\nu_j - \sum_k\pi_{k,j}) \\
& \omega_{i, j} \gets \omega_{i, j} + t(\tilde{\pi}_{i, j} - \pi_{i, j}) \label{multiplier}
\end{eqt}

We thus can obtain the following Algorithm \ref{alg:ADMM}.

\begin{algorithm}
\caption{ADMM for Optimal Transport}
\label{alg:ADMM}
\begin{algorithmic}[1]
\REQUIRE {$C\in\mbR^{m\times n}$, $\mu\in\mbR^m$, $\nu\in\mbR^n$, $t\in \mathbb{R}^+$}
\STATE $\pi, \tilde{\pi}, \gamma, \lambda, \omega\gets 0$
\WHILE {\text{not converge}}
	\STATE Update $\pi$ by \ref{upd_pi}
	\STATE Update $\tilde\pi$ by \ref{upd_pit}
	\STATE Update $\gamma, \lambda, \omega$  by \ref{multiplier}
\ENDWHILE
\RETURN $\pi$
\end{algorithmic}
\end{algorithm}

\subsubsection{ADMM for dual}

We also derive and implement an ADMM for dual problem of Optimal Transport. The Lagrangian of \ref{lp} is given by
\begin{eqt}
&\min_{\pi}\max_{\omega\geqslant 0, \gamma, \lambda}L(\pi, \gamma, \lambda, \omega) \\
= &  \sum_{i, j}C_{i,j}\pi_{i,j} - \sum_i\gamma_i(\mu_i-\sum_{j}\pi_{i,j}) - \sum_j\lambda_j(\nu_j-\sum_i\pi_{i,j}) - \sum_{i, j}\omega_{i,j}\pi_{i,j}\label{primallagrangian}
\end{eqt}

However, the first two constraints in \ref{new_lp} are linearly dependent. More rigorously, one constraint can be removed since $\sum_{i=1}^m\mu_i = \sum_{j=1}^n\nu_j$. Thus, we impose another constraint on the dual variables in \ref{primallagrangian}, namely, $\lambda_n=0$.

Calculating $\max_{\omega\geqslant 0, \gamma, \lambda}\min_{\pi_{i, j}}L(\pi, \gamma, \lambda, \omega)$ yields the dual problem
\begin{eqt}
\max_{\gamma, \lambda}&\ -\sum_i\gamma_i\mu_i - \sum_j\lambda_j\nu_j \\
\text{s.t.}&\ C_{i, j}+\gamma_i+\lambda_j\geqslant 0 \\
&\ \lambda_{n} = 0 \label{dual}
\end{eqt}
which is equivalent to

\begin{eqt}
\min_{\gamma, \lambda}&\ \sum_i\gamma_i\mu_i + \sum_j\lambda_j\nu_j \\
\text{s.t.}&\ C_{i, j}+\gamma_i+\lambda_j\geqslant 0 \\
&\ \lambda_n=0 \label{dual2}
\end{eqt}

Similar to that in Section (2.1.1), we introduce a new variable $ z_{i, j} \in \mbR^{m\times n}$ and split the constraints into two sets $\{\gamma\in \mbR^{m\times 1}, \lambda\in \mbR^{1\times n}| C_{i, j}+\gamma_i+\lambda_j=z_{i, j}\}$ and $\{z_{i, j}\in \mbR^{m\times n}|z_{i, j}\geqslant0\}$. We can now write down its augmented Lagrangian function,
\begin{eqt}
L_t(\gamma, \lambda, \omega, z, \tilde z) = &\sum_i\gamma_i\mu_i + \sum_j\lambda_j\nu_j + \omega_{i, j}(C_{i, j}+\gamma_i+\lambda_j-z_{i, j}) \\&+ \frac{t}{2}\sum_{i, j}(C_{i, j}+\gamma_i+\lambda_j-z_{i, j})^2
\label{alf-dual}
\end{eqt}
where $\gamma\in\mathbb{R}^{m\times 1}, \lambda\in\mathbb{R}^{1\times n}, \omega\in\mathbb{R}^{m\times n}, z\in\mathbb{R}^{m\times n}, z_{i,j}\geqslant 0, \lambda_n=0$. In LP problems, ``dual of dual" is primal, and $\omega$ has direct relation with $\pi$. In fact, if we ignore the quadratic term in \ref{alf-dual}, we can find that $\omega = -\pi$. This imples that $-\omega$ can be interpreted as an approximation to $\pi$ in the primal problem.

For the update of $z_{i, j}$, we have
\begin{eqt}
z_{i, j}\gets \max\{C_{i, j}+\gamma_i+\lambda_j+\frac{\omega_{i, j}}{t}, 0\} \label{splitvarupdate}
\end{eqt}

For the update of $\gamma$ and $\lambda$, we set $\frac{\partial L}{\partial \gamma_i}$ and $\frac{\partial L}{\partial \lambda_j}$ to zero and yield
\begin{eqt}
n\gamma_i+\sum_j\lambda_j = \sum_jz_{i, j}-\sum_jC_{i, j}-\frac{1}{t}(\mu_i+\sum_j\omega_{i, j})&\triangleq a_i\ (i=1, ..., m)\\
m\lambda_j + \sum_i\gamma_i = \sum_iz_{i, j} - \sum_iC_{i, j} - \frac{1}{t}(\nu_j+\sum_i\omega_{i, j})&\triangleq b_j\ (j=1, ..., n-1) \label{equation}
\end{eqt}

Thanks for $\lambda_n=0$, \ref{equation} has a unique solution:
\begin{eqt}
&\gamma_i \gets \frac{1}{n}\left(a_i-\sum_ia_i+\sum_jb_j\right)\ (i=1, ..., m)\\
&\lambda_j \gets \frac{1}{m}\left(b_j - \frac{n}{m}\sum_jb_j+\frac{n-1}{m}\sum_ia_i\right)\ (j=1, ..., n-1). \label{dualupdate}
\end{eqt}

For the update of multipliers, it's easy to obtain that
\begin{eqt}
\omega_{i, j}\gets \omega_{i, j}+t(C_{i, j}+\gamma_i+\lambda_j-z_{i, j}). \label{multiplierupdate}
\end{eqt}

We thus can obtain the following Algorithm \ref{alg:ADMM-dual}.

\begin{algorithm}
\caption{ADMM for Dual of Optimal Transport}
\label{alg:ADMM-dual}
\begin{algorithmic}[1]
\REQUIRE {$C\in\mbR^{m\times n}$, $\mu\in\mbR^m$, $\nu\in\mbR^n$, $t\in \mathbb{R}^+$}
\STATE $\gamma, \lambda, \omega\gets 0$
\WHILE {\text{not converge}}
	\STATE Update $\gamma, \lambda$ by \ref{dualupdate}
	\STATE Update $z$ by \ref{splitvarupdate}
	\STATE Update $\omega$  by \ref{multiplierupdate}
\ENDWHILE
\RETURN $-\omega$
\end{algorithmic}
\end{algorithm}

\subsection{ADMM: Simplex Splitting}
\label{sec:2.2}
We still focus on the primal problem, but this time, we utilize another splitting method. We rewrite the problem \ref{lp} as follows,
\begin{eqt}
\min_{\pi\in\mathbb{R}^{m\times n}}&\ \sum_{i=1}^m\sum_{j=1}^nC_{i, j}\pi_{i, j} \\
\text{s.t.}&\ \sum_{j}\pi_{i, j} = \mu_i,\ \sum_{i}\tilde{\pi}_{i, j} = \nu_j \\
&\ \pi_{i, j} = \tilde{\pi}_{i, j}\geqslant 0
\end{eqt}
The augmented Lagrangian function can be written as
\begin{eqt}
L_t(\pi, \tilde{\pi}, \omega) = & \sum_{i, j}C_{i, j}\frac{\pi_{i, j} + \tilde{\pi}_{i, j}}{2} + \sum_{i, j}\omega_{i, j}(\pi_{i, j} - \tilde{\pi}_{i, j}) + \frac{t}{2}\sum_{i, j}(\pi_{i, j}-\tilde{\pi}_{i, j})^2 \\
\text{s.t.}\ & \sum_{j}\pi_{i, j} = \mu_i,\ \pi_{i, j} \geqslant 0 \\
& \sum_{i}\tilde{\pi}_{i, j} = \nu_j,\ \tilde{\pi}_{i, j}\geqslant 0
\end{eqt}

For update of $\pi$, we need to solve the following subproblem, i.e., the projection on a simplex,
\begin{eqt}
&\min_{\pi}\ \sum_{i, j}\left(\pi_{i, j} - \tilde{\pi}_{i, j}+\frac{1}{t}\left(\omega_{i, j} + \frac{C_{i, j}}{2}\right)\right)^2 \\
&\text{s.t.}\ \sum_{j}\pi_{i, j} = \mu_i, \ \pi_{i, j} \geqslant 0 \label{projpro}
\end{eqt}

From standard duality theory and with some calculation, we can derive that the solution must be the form
\begin{eqt}
\pi_{i, j}\gets \max\{\tilde{\pi}_{i, j}-\frac{1}{t}\left(\omega_{i, j}+\frac{C_{i, j}}{2}\right)+\lambda_i, 0\} \triangleq \pi_{i, j}(\lambda_i) \label{projup}
\end{eqt}
where $\lambda_i$ is chosen such that
\begin{eqt}
\sum_{j}\pi_{i, j}(\lambda_i) = \mu_i. \label{cst1}
\end{eqt}

Similarly, the update of $\tilde{\pi}$ can be written as
\begin{eqt}
\tilde{\pi}_{i, j} \gets \max\{\pi_{i, j}-\frac{1}{t}\left(\omega_{i, j}-\frac{C_{i, j}}{2}\right)+\tilde\lambda_j, 0\} \triangleq \tilde{\pi}_{i, j}(\tilde\lambda_j) \label{projup2}
\end{eqt}
where $\tilde\lambda_j$ is chosen such that
\begin{eqt}
\sum_{i}\tilde\pi_{i, j}(\tilde\lambda_j) = \nu_j. \label{cst2}
\end{eqt}

We now briefly describe an algorithm mentioned in \cite{projection} to find the exact value of $\lambda$. For simplicity of statement, we consider the following problem, which is the canonical form of \ref{projpro},
\begin{eqt}
\min_{\mathbf{x}}&\ \frac{1}{2}\|\mathbf{x}-\mathbf{v}\|_2^2 \\
\text{s.t.}&\ \|\mathbf{x}\|_1 = z,\ \mathbf{x}\geqslant 0,
\end{eqt}
where $\mathbf{x}, \mathbf{v}\in\mathbb{R}^n$, $z\geqslant 0$. First, we sort $\mathbf{x}$ into descending order, namely
\begin{eqt}
y_1 \geqslant y_2 \geqslant ... \geqslant y_n. \label{descend}
\end{eqt}
Then we set
\begin{eqt}
& \rho \gets \max\left\{j\in[n]: y_j - \frac{1}{j}\left(\sum_{r=1}^jy_r-z\right) > 0\right\} \\
& \lambda \gets \frac{1}{\rho}\left(z-\sum_{r=1}^\rho y_r\right) \\
& \mathbf{x} \gets \max\{\mathbf{x}-\lambda, 0\} \label{projupdate}
\end{eqt}
if $z>0$. If $z=0$, then $\mathbf{x}$ is automatically $\mathbf{0}$.

For multipliers, it's easy to have the following updates,
\begin{eqt}
\omega_{i, j} \gets \omega_{i, j} + t(\pi_{i, j} - \tilde\pi_{i, j}) \label{mult}
\end{eqt}
We thus have the following Algorithm \ref{alg:ADMM-split}:
\begin{algorithm}
\caption{ADMM for Primal of Optimal Transport: A second splitting method}
\label{alg:ADMM-split}
\begin{algorithmic}[1]
\REQUIRE {$C\in\mbR^{m\times n}$, $\mu\in\mbR^m$, $\nu\in\mbR^n$, $t\in \mathbb{R}^+$}
\STATE $\pi, \tilde{\pi}, \gamma, \lambda, \omega\gets 0$
\WHILE {\text{not converge}}
	\STATE Update $\pi$ according to \ref{projup}, \ref{descend} and \ref{projupdate}
	\STATE Update $\tilde\pi$ according to  \ref{projup2}, \ref{descend}, and \ref{projupdate}
	\STATE Update $\omega$ by \ref{mult}
\ENDWHILE
\RETURN $\pi$
\end{algorithmic}
\end{algorithm}

\subsection{Bregman ADMM}
\cite{BADMM} proposes Bregman ADMM, which uses Bregman divergence to replace the penalty term in ADMM. Let $\phi: \Omega \to \mbR$ be a continuously differentiable and strictly convex function on the relative interior of the convex set $\Omega$. We define the Bregman divergence $B_\phi:\Omega\,\times \,\mathrm{relint} \, \Omega\to\mbR_+$ induced by $\phi$ as
\begin{equation}
B_\phi(x,y)=\phi(x)-\phi(y)-\la\nabla \phi(y),x-y\ra
\end{equation}
From the convexity of $\phi$, $B_\phi(x,y)\geqslant 0$ and the equality holds if and only if $x=y$. To solve the LP problem \ref{lp}, we consider to take $\phi(x)=\sum_{i}x_i\log(x_i)$. In this case, $B_\phi(x,y)=\mathrm{KL}(x,y)$ is the KL divergence between $x$ and $y$.

Similar to that in Section \ref{sec:2.2}, we introduce a new variable $\tilde \pi\in\mbR^{m\times n}$ to split the constraints into two simplex $S_\mu=\{\pi|\pi\geqslant0, \pi\mbone_n = \mu\}$ and $S_\nu=\{\tilde \pi |\tilde \pi\geqslant 0, \tilde \pi^T\mbone_m = \mu\}$. Then problem \ref{lp} can be written in the following form,
\begin{equation}
\left\{
\begin{aligned}
&\min\quad \la C, \pi\ra\\
&\mathrm{s.t.}\quad \pi\in S_\mu, \tilde \pi\in S_\nu, \pi=\tilde \pi
\end{aligned}
\right.
\end{equation}

We then introduce another variable $\sigma\in\mbR^{m\times n}$ for BADMM. Given $(\pi^{(l)},\tilde\pi^{(l)},\sigma^{(l)})$, we first update $\pi^{(l+1)}$ and $\tilde\pi^{(l+1)}$:
\begin{equation}
\label{badmm_pi_upd}
\pi^{(l+1)}=\arg\min\limits_{\pi\in S_\mu} \la C, \pi\ra+\la \tilde \sigma^{(l)}, \pi\ra+t \KL(\pi,\tilde\pi^{(l)})
\end{equation}
\begin{equation}
\label{badmm_pit_upd}
\tilde\pi^{(l+1)}=\arg\min\limits_{\tilde\pi\in S_\nu} \la \sigma^{(l)}, -\tilde\pi\ra+t \KL(\tilde\pi, \pi^{(l+1)})
\end{equation}
Both \ref{badmm_pi_upd} and \ref{badmm_pit_upd} have closed form solution
\begin{equation}
\label{badmm_pipit_upd}
\pi_{i,j}^{(l+1)}=\frac{\tilde\pi^{(l)}_{i,j}\exp(-\frac{C_{i,j}+\sigma_{i,j}^{(l)}}{t})}{\sum_{j=1}^n\tilde\pi^{(l)}_{i,j}\exp(-\frac{C_{i,j}+\sigma_{i,j}^{(l)}}{t})}\mu_i, \quad \tilde\pi_{i,j}^{(l+1)}=\frac{\pi_{i,j}^{(l+1)}\exp(\frac{\sigma_{i,j}^{(l)}}{t})}{\sum_{i=1}^m\pi_{i,j}^{(l+1)}\exp(\frac{\sigma_{i,j}^{(l)}}{t})}\nu_j
\end{equation}
We update $\sigma^{(l+1)}$ as
\begin{equation}
\label{badmm_sigma_upd}
\sigma^{(l+1)} = \sigma^{(l)} + t (\pi^{(l+1)}-\tilde\pi^{(l+1)})
\end{equation}
Then we get the following Bregman ADMM, Algorithm \ref{alg:BADMM}.

\begin{algorithm}
\caption{Bregman ADMM for Optimal Transport}
\label{alg:BADMM}
\begin{algorithmic}[1]
\REQUIRE {$C\in\mbR^{m\times n}$, $\mu\in\mbR^m$, $\nu\in\mbR^n$, $t>0$}
\STATE Initialize $\tilde\pi^{(0)}=\mu\nu^T$, set $\sigma^{(0)}=\mathbf{0}_{n\times m}$, $l=0$
\WHILE {\text{not converge}}
	\STATE Update $(\pi^{(l+1)},\tilde\pi^{(l+1)},\sigma^{(l+1)})$ by \ref{badmm_pipit_upd} and \ref{badmm_sigma_upd}, $l=l+1$
\ENDWHILE
\RETURN $\frac{\pi^{(l)}+\tilde\pi^{(l)}}{2}$
\end{algorithmic}
\end{algorithm}

\cite{BADMM} proves that when $m=n$, BADMM can be faster than ADMM by a factor of $O(n/ \log(n))$.

\input{final/entropy_regularization}

\input{final/numerical_experiment}

\section{Conclusion}
\label{sec:5}
Our work for OT (Optimal Transport) ends up here, but new ideas for improvement and continuous passion for research will never fade. We now give a brief summary for what we have done and give some outlooks.

We first implemented several first-order methods, mainly `ADMM's. Generally, they do not perform very well if compared to state-of-art algorithm packages such as Gurobi. However, the violation of constraints and optimality of objective values are within our tolerance. From our experiments, directly solving primal problems are much better than solving dual ones. Needless to say, it has been considered that first-order methods such as `ADMM' are not suitable for large-scale OT problems. But we observe that first-order methods could also achieve relatively satisfying results, if we choose smart splitting schemes and tuning parameters.

We then choose Entropy Regularization as our main topic. Sinkhorn is a theoretically and practically elegant algorithm. However, numerical stability and convergence speed cause difficulty in optimizing the regularized problem, especially when the coefficient of regularized term $\epsilon$ is small. We adopt a technique to improve the stability and the continuation strategy to boost convergence. Great improvement has been observed, but deterioration of performance when $\epsilon$ is very small still exists. It's worth mentioning that ADMM shows moderate results on Entropy Regularization.

Now we provide some future outlooks. For first order methods, we hope to implement the interior point algorithm to deal with constraints satisfaction. In addition, second-order algorithms like Newton methods and semi-smooth Newton methods can be tested out. Also, as is mentioned before, projection on a simplex in first order methods can be further simplified to reduce iteration time. Furthermore, though we have testified that our choice of parameters achieve good results, theoretical properties remained to be studied.

For Sinkhorn's method, we hope to continue on refining the numerical stability and boosting convergence. A simple method is to combine Sinkhorn with other methods such as ADMM. Additionally, if time has permitted, we might want to try implementing the algorithm in C++ in order to accelerate processing.

For numerical experiments, we hope to test on the whole DOTmark to have a more precise investigation on the accuracy and efficiency of all these algorithms.

Transportation problem is the basis for many high level applications. However, solving the problem is still tough even with numerous proposed methods. Of course, we hope that we can find more efficient methods, both in time and space. This will be left for future research.

\section*{Acknowledgement}
We would like to thank Zeyu Jia a lot for providing his server to let us run our numerical experiments.

The division of our work is listed below. Yifei Wang is responsible for the writing and coding of Bregman ADMM (Section 2.3), Sinkhorn's algorithm and related methods (Section 3.1-3.3); the framework of coding and the conducting of most of the numerical experiments in Section 4. Feng Zhu is responsible for the writing and coding of ADMMs and related methods (Section 2.1-2.2, Section 3.4, Appendix); the writing of most of the experiment reports in Section 4.

\printbibliography
\begin{appendix}
\section*{Appendix: Splitting method with penalty functions}

To impose more attention on constraints, we propose the following splitting method with penalty functions.

Let $F(\pi)$ and $G(\pi)$ be defined in the following way,
\begin{eqt}
& F(\pi) = \sum_{i, j}C_{i,j}\pi_{i,j} + \frac{t}{2}\left(\sum_{i}(\mu_i-\sum_{j}\pi_{i,j})^2 + \sum_{j}(\nu_j-\sum_{i}\pi_{i,j})^2\right) \\
& G(\pi) =
\left\{
\begin{matrix}
0, \indent &\pi_{i, j}\geqslant0,\ \forall i, j\\
+\infty, \indent &\text{else}
\end{matrix}
\right.
\end{eqt}
Now let the problem be
\begin{eqt}
\min_\pi \ F(\pi) + G(\pi)
\end{eqt}
It's easy to obtain
\begin{eqt}
\text{prox}_{\frac{1}{w}G}(\pi) = \max\{\pi, 0\} \label{proxg}
\end{eqt}

To compute $\text{prox}_{\frac{1}{w}F}(\pi)$ is equivalent to solve
\begin{eqt}
\min_{\tilde{\pi}} \tilde L(\tilde{\pi}) = & \sum_{i, j}C_{i,j}\tilde\pi_{i,j} + \frac{t}{2}\left(\sum_{i}(\mu_i-\sum_{j}\tilde\pi_{i,j})^2 + \sum_{j}(\nu_j-\sum_{i}\tilde\pi_{i,j})^2\right) \\&+ \frac{w}{2}\left(\sum_{i, j}(\tilde{\pi}_{i, j} - \pi_{i, j})^2\right),
\end{eqt}
We set $\frac{\partial \tilde{L}}{\partial \pi}$ to zero and solve the linear equations. This yields
\begin{eqt}
w\tilde{\pi}_{i, j} + t\left(\sum_k\tilde{\pi}_{i, k}+\sum_k\tilde{\pi}_{k, j}\right) = -C_{i, j} + w\pi_{i, j} + t(\mu_i+\nu_j) \triangleq r_{i, j}
\end{eqt}
and
\begin{eqt}
\tilde{\pi}_{i, j} & = \frac{1}{w}(r_{i, j}-\frac{t}{nt+w}\sum_kr_{i, k} - \frac{t}{mt+w}\sum_kr_{k, j}\\
& + \frac{t^2}{mt+nt+w}(\frac{1}{mt+w}+\frac{1}{nt+w})\sum_{k, l}r_{k, l}) \label{proxf}
\end{eqt}

We now have the following algorithm \ref{alg:smpf}. Here we apply Douglas-Rachford update scheme and Nesterov accelerating method to boost convergence.

\begin{algorithm}
\caption{Splitting method with penalty functions for Optimal Transport}
\label{alg:smpf}
\begin{algorithmic}[1]
\REQUIRE {$C\in\mbR^{m\times n}$, $\mu\in\mbR^m$, $\nu\in\mbR^n$, $t\in\mbR^+$, $w\in\mbR^+$}
\STATE Initialize $\pi^{(0)}$ and set $\pi^{(-1)} = \pi$, $l\gets 0$
\WHILE {\text{not converge}}
	\STATE $\pi \gets \pi^{(l)}+\frac{i-1}{i+2}(\pi^{(l)}-\pi^{(l-1)})$
	\STATE Compute $\tilde\pi$ by \ref{proxf}
	\STATE Compute $\hat\pi$ by \ref{proxg}, with $\pi$ replaced by $2\tilde\pi-\pi$
	\STATE $\pi^{(l+1)} \gets \hat\pi+\tilde\pi-\pi$
	\STATE $l\gets l + 1$
\ENDWHILE
\RETURN $\pi^{(i)}$
\end{algorithmic}
\end{algorithm}

In real implmentation, we found that $t$ is hard to tune. If it is small, then the constraints are not satisfied well. If it is large, the objective value becomes unacceptable. We have tried to combine \ref{alg:smpf} with \ref{alg:ADMM-dual} to impose constraints, but the results are not satisfactory.
\end{appendix}
\end{document}


% !TEX root = ../main.tex
\chapter{Topic Modeling}
\label{ch:topicModeling}

Topic models are probabilistic models which are used to extract an underlying semantic structure from text artifacts, or documents.
They are based on a hierarchical bayesian analysis on the terms in a document,
on which a similarity measure for its content can be defined and used to "connect" and cluster documents.

Topic models are useful when dealing with large quantities of unstructured documents,
that need to be automatically structured, grouped or filtered for knowledge extraction,
for example to provide similar/related content at the end of blog entries,
or to automatically tag content with relevant keywords~\cite{blei2009topic}.

In this chapter, methods for topic modeling will be explored,
and a suitable model for the use-case of this thesis will be determined.
While it is easy for humans to gain an intuitive understanding what a document is about
and other subjective attributes, machines lack this intuition.
Therefore, the topic modeling methods presented in this chapter infer \textit{latent} topics,
meaning that they are unable to name or describe a topic, but merely confirm its existence.
However, since the topics inferred are dependent on term (in this case: word) frequencies,
the models can provide a human-understandable representation of a topic by listing its most frequent terms.

\section{Methods}
\label{sec:methods_topicmodeling}

Similar to the previous chapter, multiple methods to perform topic modeling will be explained and demonstrated.
However, since no labeled dataset of a representative sample of statuses on Twitter and their respective topics is available,
only subjective assessments can be made to their performance.
Although the Sanders-dataset was collected by filtering a stream for specific keywords as described in~\cref{sec:theSandersDataset},
and these could be used as labels for a supervised approach such as supervised LDA~\cite{Blei2008},
the dataset is not representative of all activity on Twitter and not suitable for training such a model.
Therefore, only unsupervised approaches will be considered,
and subjective choices will be made as to what constitutes a "topic" in the context of this thesis,
with the parameters for the models being determined accordingly.

\subsection{TF-IDF}
\label{subsec:tfidf}

Both algorithms use TF-IDF (\textbf{T}erm \textbf{F}requency - \textbf{I}nverse \textbf{D}ocument \textbf{F}requency).
In the TF-IDF scheme, first, a dictionary of terms (words, usually) that the documents are made of is formed.
In this case, this dictionary will be created by taking all the terms (words) in the dataset,
and removing those that occur only once, to reduce its size.
Also, contrary to~\cref{ch:sentimentAnalysis}, in this chapter,
the tokenization function will also remove stopwords, as described in~\cref{sec:preprocessingAndTokenization}.
Another strategy that could've been used for scenarios where comprehensive stopword lists are not available
would be to remove a percentage or absolute number of most and least frequent terms,
which have little informativeness since they occur in too many or too few documents.
The implementation of the dictionary creation process can be seen in~\cref{code:create_corpus}.

\begin{figure}
    \caption{Implementation of corpus-creation}
    \label{code:create_corpus}
    % @formatter:off
    \begin{minted}{python}
        # The usual preprocessing and tokenization
        tweets = [tokenize(preprocess(tweet)) for tweet in tweets]

        # Count term occurrences
        term_count_dictionary = defaultdict(int)
        for tweet in tweets:
            for term in tweet:
                term_count_dictionary[term] += 1

        # keep terms that occur more than once
        terms = [[(term, term_count_dictionary[term]) for term in tweet
                if term_count_dictionary[term] > 1] for tweet in tweets]
    \end{minted}
    % @formatter:on
\end{figure}

To compute the TF-IDF values for a specific document,
a term count vector is then formed containing how often each term in the dictionary occurs in that document,
and normalized over the length to result in the frequency.
This is usually sparsely implemented, since especially with short Twitter statuses,
most words in the corpus do not occur in the document.
Also, since some words might generally occur more often, thereby being less informative of the topic,
the frequency for each term in the document is then divided by the frequency of that term in the dictionary,
giving $term\_frequency / document\_frequency$, or $term\_frequency \times inverse\_document\_frequency$ (TF-IDF)~\cite{Blei2003}.

The gensim library was used to create and save the TF-IDF model,
which contains rows with two term identifiers (the terms themselves are saved in the dictionary) and a count of how often
they co-occur in any of the training documents, while omitting term-combinations that never co-occur, to reduce size~\cite{gensimDocs}.

\subsection{LDA}
\label{subsec:lda}

The basic idea behind LDA (\textbf{L}atent \textbf{D}irichlet \textbf{A}llocation) is to represent documents as a distribution of (latent) topics,
each of which is characterized as a distribution over words.
This thesis will provide an outside view of this method, while explaining important hyperparameters and their impact.
LDA is a bag-of-words model, which means there are no syntax rules.\\
An LDA model takes the TF-IDF model created in~\cref{subsec:tfidf} as an input to determine the dirichlet distributions,
and two major hyperparameters, $\alpha$ and $\eta$,
both of which are parameters of the internal dirichlet-distributions.\\
$\alpha$ controls the per-document topic dirichlet distribution,
where a higher value indicates that documents tend to be a mixture of many topics,
and lower values lead to few topics with higher probability.\\
$\eta$ (also sometimes denoted $\beta$) controls the per-topic word dirichlet distribution, where, as with $\alpha$,
higher values lead to few words with high probabilities determining the topics,
and vice-versa.\\
The output is a matrix where every row represents a topic,
the columns are the terms from the dictionary,
and every element represents the probability that the word belongs to the topic,
with every column therefore adding up to 1.
When classifying a document, this matrix is used to allocate a distribution of topics for which the probability to have generated that document is maximized~\cite{Blei2003}.

%First, try the default settings
For LDA topic modeling, the gensim library was used~\cite{gensimDocs}.
The dataset used was the streaming sample dataset described in~\cref{sec:streamingSampleDataset},
since the Sanders dataset is topically not representative of Twitter, as described in~\cref{sec:theSandersDataset}.

To explore the results and determine the best hyperparameters, LDAvis was used.
LDAvis plots the topics on a 2D-scatterplot, with the axes being the top 2 principal components
in the hyperdimensional space of all topics, to visualize topic similarity and overlap~\cite{ldavis}.
It can also list the most relevant terms for each topic showing their frequencies in relation to their overall frequencies,
where relevancy is determined through a formula developed by Sievert \etAl~\cite{sievert2014ldavis},
which can be seen in~\cref{math:relevance}.

\begin{figure}
    \caption{Relevancy measure used in LDAvis, developed by Sievert \etAl~\cite{sievert2014ldavis}}
    \label{math:relevance}
    \begin{align*}
        relevance(term | topic) = \lambda \* p(term | topic) + (1 - \lambda) \* \frac{p(term | topic)}{p(term)}
    \end{align*}
\end{figure}

$\lambda$ adjusts the relative importance of words that are discriminant to a certain topic,
where 0.5 was found to be a good value.

After some exploration, the best-suited hyperparameters were chosen.
The number of topics was set to 10.
$\eta$ was set to 0.01, which also showed good results in previous Twitter topic modeling research~\cite{Hong2010}.
$\alpha$ is set to "auto", which means gensim learns it from the data provided, and proved to give better results than trial and error.
The LDAvis visualization for this model can be seen in~\cref{fig:ldavis}.

\begin{figure}
    \centering
    \caption{LDAvis visualization of the topic model trained on the sample dataset}
    \label{fig:ldavis}
    \includegraphics[width=\textwidth]{../images/LDAvis.png}
\end{figure}

Next, a different visualization, as a network graph, was devised to make a subjective assessment of the model.
In the graph, each light-blue node represents a topic.
For each topic, the 5 terms with the highest probabilities are connected with edges whose weight (thickness) represent the probability
of that word being in a document of that topic, as computed by the model.
It can be seen that some topics share terms - however, these shared terms are not very distinct terms.
The model even successfully modeled trending topics on the evening when the data was collected as described in~\cref{sec:streamingSampleDataset}.
The network graph can be seen in~\cref{fig:lda_network_graph}.
Since LDA is not deterministic, the top terms for each topic and other values might change slightly,
even if the model is trained with the same parameters on the same data.

\begin{figure}
    \centering
    \caption{Network graph of the LDA topic model created from the stream sample dataset}
    \label{fig:lda_network_graph}
    \includegraphics[width=\textwidth]{../figures/lda_network_graph.pdf}
\end{figure}

The training dataset was about equally distributed on the topic, as expected by the definition of LDA~\cite{Blei2003}.
This can be seen in~\cref{fig:sample_topic_distribution}.

\begin{figure}
    \centering
    \caption{Topic distribution of the LDA model trained on the sample dataset}
    \label{fig:sample_topic_distribution}
    \includegraphics[width=\textwidth]{../figures/topic_distribution.pdf}
\end{figure}

\subsection{NMF}
\label{subsec:nmf}

NMF (\textbf{N}onnegative \textbf{M}atrix \textbf{F}actorization) is another active area of research in topic modeling.
It overcomes some of the shortcomings of LDA in terms of consistency across runs and empirical convergence,
since it is deterministic~\cite{Choo2013}.
It is also easier to adjust the model and incorporate feedback on the classification results in a semi-supervised approach,
making it a potentially more suitable solution for recommendation systems as described at the beginning of this chapter.
The output of the model is the same as the output of an LDA model: a term-wise representation of topics, even though the columns
do not necessarily sum up to 1.

The implementation of NMF in the scikit-learn library was used~\cite{scikitDocs}.
The number of components (the number of topics in this case) was set to 10 to ensure comparability with the LDA results.
Although several parameters were explored, the best results were accomplished with the default parameters.
The resulting network graph can be seen in~\cref{fig:nmf_network_graph}.

\begin{figure}
    \centering
    \caption{Network graph of the NMF topic model created from the stream sample dataset}
    \label{fig:nmf_network_graph}
    \includegraphics[width=\textwidth]{../figures/nmf_network_graph.pdf}
\end{figure}

\section{Results}
\label{sec:results}

Overall, the results that could be achieved with both methods were similar in terms of subjective descriptiveness of the top terms and amount of overlap.
There were even some equal topics, like topic number 6 in the LDA model and topic number 1 in the NMF model.
The advantages of NMF also do not apply to this use case, therefore a decision was made in favor or LDA,
since it is the more mature method with more available research.
Furthermore, there are a variety of libraries and tools available for LDA that can be used to implement and tune models,
like gensim and LDAvis.


%Setting the physical process

\section{Sub-Grid Scale Turbulence Scheme} \label{sec:basic_usel_turbulence}
%------------------------------------------------------

The sub-grid scale turbulence model is for representing energy cascade to the sub-grid scale due to the advection terms in Large-eddy simulations (LESs).

The turbulence scheme is specified in \nmitem{ATMOS_PHY_TB_TYPE} in \namelist{PARAM_ATMOS} in files \verb|init.conf| and \verb|run.conf|. The timing of the calling of the turbulence scheme is specified in \namelist{PARAM_TIME}. Refer to Section \ref{sec:timeintiv} for the detailed configuration of the calling timing.

\editboxtwo{
\verb|&PARAM_ATMOS  | & \\
\verb| ATMOS_PHY_TB_TYPE = "SMAGORINSKY", | & ; Select the scheme shown in Table \ref{tab:nml_atm_tb}\\
\verb|/             | & \\
}
\begin{table}[h]
\begin{center}
  \caption{List of turbulence scheme types}
  \label{tab:nml_atm_tb}
  \begin{tabularx}{150mm}{lXX} \hline
    \rowcolor[gray]{0.9}  Schemes & Description of scheme & Reference\\ \hline
      \verb|OFF|          & Do not calculate the turbulence process &  \\
      \verb|SMAGORINSKY|  & Smagorinsky—Lilly-type sub-grid model & \citet{smagorinsky_1963,lilly_1962,Brown_etal_1994,Scotti_1993} \\
      \verb|D1980|        & Deardorff-type sub-grid model & \citet{Deardorff_1980} \\
    \hline
  \end{tabularx}
\end{center}
\end{table}

The \verb|SMAGORINSKY| scheme can be also used for the horizontal eddy viscosity in RANS simulations.
The planetary boundary layer parameterization (Section \ref{sec:basic_usel_pbl}) is a scheme considering only vertical mixing.
If you want to consider the horizontal eddy viscosity in RANS simulations,
use the sub-grid scale turbulence model for horizontal mixing.
Then, \nmitem{ATMOS_PHY_TB_SMG_horizontal} in \namelist{PARAM_ATMOS_PHY_TB_SMG} should be \verb|.true.| as follows:
\editboxtwo{
\verb|&PARAM_ATMOS_PHY_TB_SMG  | & \\
\verb| ATMOS_PHY_TB_SMG_horizontal = .true., | & \\
\verb|/             | & \\
}


\documentclass[letterpaper, titlepage, 11pt]{article}

\usepackage{hyperref}
\usepackage[toc,page]{appendix}
\usepackage{graphicx}
\usepackage{caption}
\usepackage{subcaption}
\usepackage{amsmath}
\usepackage{listings}
\usepackage{color}
\definecolor{mygreen}{RGB}{28,172,0} % color values Red, Green, Blue
\definecolor{mylilas}{RGB}{170,55,241}
\lstset{language=Matlab,%
    basicstyle=\footnotesize,
    breaklines=true,%
    morekeywords={matlab2tikz},
    keywordstyle=\color{blue},%
    morekeywords=[2]{1}, keywordstyle=[2]{\color{black}},
    identifierstyle=\color{black},%
    stringstyle=\color{mylilas},
    commentstyle=\color{mygreen},%
    showstringspaces=false,%without this there will be a symbol in the places where there is a space
    numbers=left,%
    numberstyle={\tiny \color{black}},% size of the numbers
    numbersep=9pt, % this defines how far the numbers are from the text
    emph=[1]{for,end,break},emphstyle=[1]\color{red}, %some words to emphasise
    %emph=[2]{word1,word2}, emphstyle=[2]{style},
}
\title{Implementation of a Real-Time Spectrum Analyzer Synthesized on FPGA}
\author{David Lavoie-Boutin, 260583602}
\date{\today}

\begin{document}

\maketitle
\begin{abstract}\
As a final project for the Signal Processing Hardware course (ECSE 436), I was tasked with designing, implementing and deploying a Real-Time spectrum analyzer. This project included the custom implementation of the FFT algorithm in Matlab, porting that algorithm to HDL code that would be synthesized for an FPGA, the acquisition of audio samples and display of the FFT results on the same FPGA. To achieve this goal, I implemented the common Cooley–Tukey algorithm for computing the FFT. I used Matlab and Simulink to generate the HDL code for the FFT algorithm based on the Simulink testbench created. I created the control logic modules to prepare the samples for the FFT and parse its output for the display module, which displays the magnitude of each FFT coefficient output.
\end{abstract}

\tableofcontents
\clearpage

\section{Introduction \& Background}
The FFT algorithm is often considered as one of the algorithms that revolutionized the world, some even say, "the most important of our lifetime"~\cite{important}. Its applications are virtually endless and range from simple voice analysis to radar to every form of communication we know of. For this project, I had to create an audio spectrum analyzer that would employ the FFT to decompose the signal in its frequency components and display the magnitude of each component on a computer monitor. \\
\\
In the end, this entire system was to run on an Altera DE-II development board which integrates the Cyclone II FGPA with a bunch of other dedicated controllers, including RAM, ADCs, USB, etc. First, I developed my custom implementation of the Cooley–Tukey FFT algorithm in Matlab. Then I created a Simulink testbench using Matlab's FFT function, optimized for HDL synthesis and used Matlab to generate the HDL code for the FFT.\\
\\
I integrated the generated code the to rest of the FPGA project and linked it with some control logic to the acquisition system. The output of the FFT are then buffered until all the data is available and displayed on a VGA monitor. For this, I designed a simple module that plots an array of data in a bar chart.

\section{Matlab Algorithm}
The Matlab algorithm I implemented for the computation of the FFT follows very closely the Cooley–Tukey algorithm described on Wikipedia~\cite{wiki_cooley} and further developed in a paper by Stefan Worner~\cite{fft_it}. My first implementation followed the recursive strategy and the second uses the iterative strategy:
\lstinputlisting[language=Matlab, caption="Recursive FFT implementation"]{../myFFT.m}
\lstinputlisting[language=Matlab, caption="Iterative FFT implementation"]{../fft_it.m}

After implementing my own version of FFT, I considered using Matlab to generate synthesizable HDL code. Using Simulink and the DSP toolbox, I used the HDL optimized FFT function in the example diagram shipped with Matlab and adapted it to my input specifications. The schematic is illustrated in figure~\ref{fig:simulink}.
\begin{figure}[!htb]
  \centering
  \includegraphics[width=0.8\textwidth]{sim2.PNG}
  \caption{Simulink schematic of a HDL optimized FFT}
  \label{fig:simulink}
\end{figure}

Running the simulation compares the output of the built-in FFT function to the HDL optimized FFT function and we can see that they do not match. This is due to the optimization strategy of the HDL block where the $e^x$ function is replaced with a lookup table which is not as precise as the native function. With this schematic established, I was able to use the HD Coder function in Matlab to generate the VHDL code for the FFT component.

\section{Display on the FPGA}
Before implementing the full processing to display pipeline, I created and tested the display module on its own using the infrastructure provided in Lab 3. For this purpose, I designed a modular block that displays an array of values as a bar chart. There are several interesting points I want to outline in the implementation of this block.

\subsection{Package Definitions}
In order to maximize modularity of the code developed, I choose to define custom types and package constants to parameters that would be used in different modules and that were susceptible to change frequently in the life of the project. These include a specific data type to pass values to display as an array, the number of data samples and the number of bits used to represent those samples.

\lstinputlisting[language=VHDL, firstline=5, lastline=10]{../VideoLab/graph_display.vhd}

\subsection{Modular Bar Chart}
Another interesting design point in this graphing module is the use of compilation time resolution of different parameters such as the number of bars and the width of each bars. This is done using simple arithmetic, but makes the design very modular simply using the constants described earlier.

\lstinputlisting[language=VHDL, firstline=47, lastline=49]{../VideoLab/graph_display.vhd}

\subsection{Array Input}
The last point I want to mention is the use of custom types to pass and manipulate the set of data to graph. The use of the array type make is easy to address the data elements using simple indexes and allows us to iterate on the data using a ``for loop'' construct in VHDL.
\begin{lstlisting}[language=VHDL]
for j in 0 to NUMBER_OF_SAMPLES-1 loop
    temp := pad & switch(j*switch_range_width+switch_range_width-1 downto j*switch_range_width);
    data(j) <= temp(SAMPLES_DATA_LENGTH -5 downto 0) & "0000";  -- convert range of switches to data element
end loop;
\end{lstlisting}

\subsection{Switch to Test}
In order to test this design, I used the switches on the board to emulate data and confirm the good behavior of the module. First I created a module that converts the vector of switch values to the data array type I defined.

\lstinputlisting[language=VHDL, firstline=7]{../VideoLab/switch_to_array.vhd}

I then used Modelsim to simulate this module and confirm its good behavior which yielded figure~\ref{fig:switch_sim}. In the figure we can see that each sample is represented by a group of 4 switches and that switches 17 and 18 are not mapped to any sample as 18 is not divisible by 4.

\begin{figure}[!htb]
  \centering
  \includegraphics[width=0.8\textwidth]{switch_sim.PNG}
  \caption{Modelsim simulation of the switch to array module}
  \label{fig:switch_sim}
\end{figure}

\section{FFT on FPGA}

After implementing and testing the graphing module, I used the infrastructure provided for lab 2 and modified it with the modules I needed to run the FFT on the audio samples. For this I created the block diagram shown in figure~\ref{fig:block_filter}

\begin{figure}[!htb]
  \centering
  \includegraphics[width=\textwidth]{full_filter.PNG}
  \caption{FFT integration in the audio processing unit}
  \label{fig:block_filter}
\end{figure}

This block diagram show several additional modules. The first block is the data controller. This block simply casts the 32 bit audio sample to a 16 bits representation that the FFT block will use. It also drives the start signal which indicates a new set of inputs for the FFT computation. The data is then passed to the FFT block.

\lstinputlisting[language=VHDL, firstline=6]{../VideoLab/fft_controller_block.vhd}

After the FFT, we compute the magnitude of the coefficients using the traditional geometric norm. This poses the challenge of requiring us to compute the square root of the numbers which is not that trivial. For this task, I used an implementation of the Non-Restoring Square Root Algorithm~\cite{sqrt}.

\lstinputlisting[language=VHDL, firstline=5, caption="Square-Root function"]{../VideoLab/sqrt.vhd}
\lstinputlisting[language=VHDL, firstline=7, caption="Magnitude module"]{../VideoLab/magnitude.vhd}

The last step before displaying the data is to buffer a set of outputs since the FFT outputs the coefficients in series and we want to display all the data at once. For this purpose I implemented a simple buffer module that build an array with the samples and published it once it is filled.

\lstinputlisting[language=VHDL, firstline=7, caption="Buffer module for the FFT output"]{../VideoLab/buffer_fft_output.vhd}

And in order to test the proper behavior of this module, I also created a Modelsim testbench and simulated its behavior. In the simulation results in figure~\ref{fig:buff_sim}, notice how each cell is loaded sequentially and how the ``valid'' signal is set once all the cells are loaded.

\lstinputlisting[caption="Buffer module testbench"]{../VideoLab/buffer_testbench.tcl}

\begin{figure}[!htb]
  \centering
  \includegraphics[width=\textwidth]{buffer_sim.PNG}
  \caption{Simulation results for the buffer module}
  \label{fig:buff_sim}
\end{figure}

\section{Conclusion}
For this final project, I designed, implemented, integrated and tested a real-time spectrum analyzer which uses the FFT to decompose a signal in its frequency components which are then plotted on a computer monitor. This implementation was synthesized from Verilog and VHDL code and loaded on a Cyclone II FPGA development board.\\
\\
Preliminary steps in the project included a Matlab and Simulink implementation and simulation of the FFT algorithm, generation of HDL code for the FFT using Matlab, Modelsim simulations of different HDL modules and finally a full deployment and test of the processing pipeline.\\
\\
During the tests with the FPGA, the data observed on the screen was very noisy. I must point out that signal acquired by the FPGA itself was very noisy to begin with so many parasitic frequency components are expected on the output and this is what I observed. When sitting idle, the bars shown on screen oscillated very much very fast, to the point where many samples aliased together and gave the impression the full bars were displayed.\\
\\
When playing a tone, this parasitic noise behavior was still observed, but some bars clearly had more consistent values and we could see a clear value for that bar. Additionally, the position of that bar on the frequency scale matched the frequency of the tone, which leads me to believe this implementation is generally functional. With extra noise filtering efforts, I believe this project to turn to a fully functional analyzer.

\section{References}
\bibliography{sources}
\bibliographystyle{plain}
\end{document}


\vsssub
\subsubsection{~$S_{nl}$: Generalized Multiple \dia\  (\gmd)} \label{sec:NL3}
\vsssub

\opthead{NL3}{\ws}{H. L. Tolman}

\noindent
The \gmd\ has been developed as an extension to the \dia. Its development is
documented in a set of Technical notes \citep{tol:MMAB03a, tol:MMAB05a, tol:MMAB08b,
tol:MMAB10d}, reports \citep{tol:Oahu04a, tol:Hal09a, tol:Kona11b}, and papers
\citep{tol:OMOD04, tol:OMOD13d}. As part of the development of the \gmd, a
holistic genetic optimization technique was developed \citep{tol:OMOD13e}. A
package to perform this optimization within \ws\ was first provided by
\cite{tol:MMAB10e}. The most recent version of this package is version
\genever\ \citep{\generef}.

The \gmd\ expands on the \dia\ in three ways. First, the definition of the
representative quadruplets is expanded. Second, the equations are developed
for arbitrary depths, including the description of strong interactions in
extremely shallow water \citep[e.g.,][]{art:Web78}. Third, multiple
representative quadruplets are used.

The \gmd\ allows for arbitrary configurations of the representative
quadruplet, by expanding on the resonance conditions (\ref{eq:resonance}) as

\begin{equation} \left .
\begin{array}{ccc}
  \sigma_1    & = & a_1 \: \sigma_r \\
  \sigma_2    & = & a_2 \: \sigma_r \\
  \sigma_3    & = & a_3 \: \sigma_r \\
  \sigma_4    & = & a_4 \: \sigma_r \\
  \theta_{12} & = & \theta_1 \pm \theta_{12}   \
\end{array} \:\:\: \right \rbrace \:\:\: , \label{eq:gmd_res}
\end{equation}

\begin{table}
\caption{One, two, or three parameter definitions of the representative
         quadruplet in the \gmd. $\bk_d$ or ($\sigma_d, \theta_d$) represents
         the discrete spectral grid point for which the discrete interaction
         contributions are evaluated. All quadruplets are aligned with the
         discrete directions by taking $\bk_1 + \bk_2 // \bk_d$.}
  \label{tab:gmd_quad_def}
\vspace{\baselineskip}
\begin{center}
\begin{tabular}{ccccccc} \hline
 parameters  & $a_1$ & $a_2$ & $a_3$  & $a_4$ & $\theta_{12}$ &
 $\sigma_r$  \\ \hline
$(\lambda)$
    &    1    &    1    & $1+\lambda$  & $1-\lambda$ &    0  & $\sigma_d$ \\
$(\lambda, \mu)$
    & $1+\mu$ & $1-\mu$ & $1+\lambda$ & $1-\lambda$  &
                                   implied\textsuperscript{*}& $\sigma_d$ \\
$(\lambda, \mu, \theta_{12})$
    & $1+\mu$ & $1-\mu$ & $1+\lambda$ & $1-\lambda$  & free  &
                                                 $\frac{\sigma_d}{1+\mu}$ \\
\hline
\end{tabular}
\end{center}
\hspace{55mm} \textsuperscript{*}~assuming $\bk_1 + \bk_2 = \bk_3 + \bk_4 =
2\bk_d$
\vspace{\baselineskip}
\botline
\end{table}

\noindent
where $a_1 + a_2 = a_3 + a_4$ to satisfy the general resonance conditions
(\ref{eq:resonance_2}), $\sigma_r$ is a reference frequency, and $\theta_{12}$
is the angular gap between the wavenumbers $\bk_1$ and $\bk_2$. The latter
parameter can either be implicit to the quadruplet definition, or can be an
explicitly tunable parameter. With this, a one- ($\lambda$), two- ($\lambda,
\mu$) or three-parameter ($\lambda, \mu, \theta_{12}$) quadruplet definition
have been constructed as outlined in Table~\ref{tab:gmd_quad_def}. Note that,
unlike in the \dia, all quadruplets are evaluated for the actual water depth
and frequency.

In the \gmd, the discrete interactions are computed for arbitrary depths.
Somewhat surprisingly, interactions computed for the $F(f, \theta)$ spectrum
and converted to the native \ws\ spectrum $N(k, \theta)$ using a Jacobian
transformation proved more easily optimizable than computing the interaction
contributions for the latter spectrum directly. Furthermore, a two-component
scaling function was introduced with a `deep' scaling function for the
traditionally represented weak interactions in intermediate to deep water, and
a `shallow' scaling function representing strong interactions in extremely
shallow water. With these modifications, the discrete interaction
contributions (\ref{eq:snl_dia}) of the \dia\ become
\begin{eqnarray}
\left ( \begin{array}{c}
  \delta S_{nl,1} \\ \delta S_{nl,2} \\ \delta S_{nl,3} \\ \delta S_{nl,4}
\end{array} \right )  & = &
\left ( \begin{array}{r} -1 \\  -1 \\ 1 \\ 1 \end{array} \right )
  \left ( \frac{1}{n_{q,d}} C_{\rm{deep}} B_{\rm{deep}} +
          \frac{1}{n_{q,s}} C_{\rm{shal}} B_{\rm{shal}} \right ) \times \nonumber \\
 &  & \hspace{20mm} \left [ \:\:\:\:
                    \frac{c_{g,1}F_1}{k_1 \sigma_1}
                    \frac{c_{g,2}F_2}{k_2 \sigma_2} \left (
                    \frac{c_{g,3}F_3}{k_3 \sigma_3} +
                    \frac{c_{g,4}F_4}{k_4 \sigma_4} \right )
                                                         \right . \nonumber \\
 &  &  \hspace{20mm} \left . - \:\:
                    \frac{c_{g,3}F_3}{k_3 \sigma_3}
                    \frac{c_{g,4}F_4}{k_4 \sigma_4} \left (
                    \frac{c_{g,1}F_1}{k_1 \sigma_1} +
                    \frac{c_{g,2}F_2}{k_2 \sigma_2} \right ) \:\:\:\:
                                                    \right ] \:\:\:
, \label{eq:gmd_dsnl}
\end{eqnarray}

\noindent
where $B_{\rm{deep}}$ and $B_{\rm{shal}}$ are the deep and shallow water
scaling functions

\begin{equation}
B_{\rm{deep}} = \frac{k^{4+m} \sigma^{13-2m} }{(2\pi)^{11} \:
                 g^{4-m} \: c_g^2 } \:\:\: , \label{eq:gmd_B_deep}
\end{equation}

\begin{equation}
B_{\rm{shal}} = \frac{g^2 \: k^{11}}{(2\pi)^{11} \: c_g} (kd)^n
\:\:\: , \label{eq:gmd_B_shal}
\end{equation}

\noindent
with $m$ and $n$ as tunable parameters, $C_{\rm{deep}}$ and $C_{\rm{shal}}$
in Eq.~(\ref{eq:gmd_dsnl}) are the corresponding deep and shallow water tunable proportionality
constants, and $n_{q,d}$ and $n_{q,s}$ are the number of representative
quadruplets with deep and shallow water scaling, respectively, representing
the feature of the \gmd\ that multiple representative quadruplets can be used.

In the namelists {\F snl3} and {\F anl3} the user defines the number of
quadruplets, and per quadruplet $\lambda$, $\mu$, $\theta_{12}$,
$C_{\rm{deep}}$ and $C_{\rm{shal}}$. Values of $m$ and $n$ are defined once,
and used for all quadruplets. Finally relative depth below which deep water
scaling is not used and above which shallow water scaling is not used are
defined. Examples of some of the \gmd\ configurations from \cite{tol:MMAB10d}
are included in the example input file {\file ww3\_grid.inp}
in \para\ref{sub:ww3grid}. The default setting is to reproduce the traditional
\dia.

Note that the \gmd\ is significantly more complex that the \dia\ formulation,
and requires evaluation of the quadruplet layout for every spectral frequency
(compared to a single layout used for the \dia). For effective computation,
quadruplet layouts are pre-computed and stored in memory for a set of
nondimensional depths. Even with these and other optimizations, the \gmd\ is
roughly twice as expensive to compute for a single representative quadruplet
than the \dia\ when using the one-parameter quadruplet layout. Using the two-
or three-parameter quadruplet layout, the \gmd\ has four rather than two
quadruplet realizations, making the \gmd\ per quadruplet four times as
expensive as the traditional \dia. Using multiple representative quadruplets
is linearly additive in computational costs. For more in depth assessment of
computational costs of a model including the \gmd, see \cite{tol:MMAB10d} and
\cite{tol:OMOD13d}.