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

\section{Radiative Transitions}

\marginpar{Saturday\\ 2020-9-5, \\ compiled \\ \today}

This topic will be treated more quickly than what was originally planned for lack of time.

The basic question we will ask today is: given the knowledge of the various energy states of a certain atom, how do we characterize the radiation emitted by the various transitions of this atom?

First, we need to find out which transitions are actually permitted and thus can be observed in reality: \textbf{selection rules} will help with this. We will then determine what is the strength of the radiation from the transitions which are allowed.

A note: no transition in the cases we will treat is strictly \emph{forbidden}, meaning that it is actually \emph{impossible} for it to happen; rather, we use the word as a shorthand to denote transitions whose probability is quite small, so that the intensity of radiation they emit is vanishingly small (at least as compared to the ``allowed'' transitions).

We will use a \textbf{semi-classical} approach, treating the atom quantum-mechanically and radiation classically.
The justification for this (which amounts to not using QED, basically) is that the self-interaction of photons is negligible.

\todo[inline]{Is the condition we should check not that the number of photons is very large, so that any single-photon effect washes out?}

The transition probability per unit time from an initial state \(i\) to a final state \(f\) is denoted \(w_{fi}\).
There is an explicit quantum-mechanical expression for this quantity in terms of the Hamiltonian of the system and the wavefunctions corresponding to the two states of the electrons.

Because of the detailed balance equation we have that, at equilibrium, \(w_{fi} = w_{if}\).

The general expression for the transition rate contains integrals in the form
%
\begin{align}
\int \phi _f^{*} e^{i \vec{k} \cdot \vec{r}} \vec{\ell} \cdot \vec{\nabla}_j \phi _i \dd[3]{r}
\,,
\end{align}
%
where \(\vec{\ell}\) is a unit vector in the direction of the polarization of the wave \cite[eq.\ 10.13 onwards]{rybickiRadiativeProcessesAstrophysics1979}, while \(\vec{k}\) is the wavevector and \(\vec{r}\) is the position vector.

In the \textbf{long-wave} approximation, in which the wavelength of the radiation is much larger than the characteristic scale of the atom, we can expand
%
\begin{align}
e^{i \vec{k} \cdot \vec{r}} \approx 1 + i \vec{k} \cdot \vec{r} + \frac{1}{2} \qty(i \vec{k} \cdot \vec{r})^2 + \dots
\,.
\end{align}

Let us make the long-wave condition more explicit: typically we will have \(\abs{\vec{r}} \sim a_0 = \hbar / (m_e \alpha c)\), the Bohr radius, while the wavevector's magnitude will typically be \(\abs{\vec{k}} \sim \omega / c\). So, the quantity we want to be small is
%
\begin{align}
\vec{k} \cdot \vec{r} \sim \frac{a_0 \omega }{c} = a_0 \frac{\Delta E}{\hbar c}
\,,
\end{align}
%
where \(\Delta E\) is the transition energy.
Since the binding energy is electrostatic in nature, the typical value of \(\Delta E\) is \(\Delta E \sim Z e^2 / 2 a_0 \). Then, the Bohr radius simplifies, and we get
%
\begin{align}
\vec{k} \cdot \vec{r} \sim \frac{Z e^2}{2} \frac{1}{\hbar c} = \frac{Z \alpha }{2} \ll 1
\,,
\end{align}
%
so the approximation of taking the scalar product to be small works as long as we consider atoms which are not too far down the periodic table.

Truncating the series at the lowest order is equivalent to the dipole approximation. The link comes from the fact that \(Z \alpha \approx v / c\), at least to first order.
This means that, as long as the condition is satisfied, the electron is moving non-relativistically around the nucleus.

In the dipole approximation we do indeed have certain transitions with probability exactly equal to zero, but this is an artifact of the approximation.

If we consider an ensemble of atoms whose orientations are random, then the \emph{unpolarized} transition rate reads
%
\begin{align}
\expval{w_{fi}} = \frac{4 \pi^2}{3 \hbar^2 c}
\abs{d_{fi}}^2 \mathcal{I}(\omega_{fi})
\,,
\end{align}
%
where \(\mathcal{I}(\omega _{fi}) = 4 \pi J(\omega _{fi})\) is the intensity of radiation integrated over all solid angles and computed at the transition frequency, while \(d_{fi}\) is the matrix element of the electric dipole operator \(\hat{d} = e \sum_j \hat{r}_j\) between the initial and final state.

Now, this is related to the Einstein \(B\) coefficient as
%
\begin{align}
\expval{w_{lu}} = B_{lu} J(\nu _{ul})
\,,
\end{align}
%
where we switched from \(i\) and \(f\), meaning initial and final, to \(l\) and \(u\), meaning lower and upper energy state.

We have the conversion
%
\begin{align}
J(\nu _{ul}) = \frac{\mathcal{I}(\nu _{ul})}{4 \pi }
= \frac{2 \pi }{4 \pi } \mathcal{I}(\omega _{ul})
= \frac{\mathcal{I}(\omega _{ul})}{2}
\,.
\end{align}

\todo[inline]{What? a change by a factor \(2 \pi \) in the \emph{argument} results in a change in \(2 \pi \) in the \emph{function}? This only holds if intensity is a \emph{linear} function of the frequency!}

Therefore,
%
\begin{align}
\expval{w_{ul}} = B_{lu} \frac{\mathcal{I}(\omega _{ul})}{2}
\,,
\end{align}
%
which means that the Einstein \(B\) coefficient can be expressed in terms of the dipole operator as
%
\begin{align}
B_{lu} = \frac{8 \pi^2}{4 c \hbar^2} \abs{d_{ul}}^2
\,.
\end{align}

It is common to express this in terms of a quantity called the \emph{oscillator strength} for that given transition, however in order to introduce that formalism we need to generalize what we have found to transitions between degenerate energy levels.

If we have several degenerate upper levels, while the final lower state has a statistical weight \(g_l\), then we can write
%
\begin{align}
B_{lu} = \frac{32 \pi^2}{3 c \hbar^2} \frac{1}{g_l} \sum _{l} \abs{d_{ul}}^2
\,.
\end{align}

We are averaging over the initial states, and summing over the final ones.

\todo[inline]{why is this expression multiplied by a factor 4 compared to the nondegenerate one?}

\todo[inline]{Why is \(g_l\) outside the sum?}

The definition of the oscillator strength \(f_{lu}\) is then given by expressing the Einstein coefficient as
%
\begin{align}
B_{lu} &= \underbrace{\frac{4 \pi^2 e^2}{h \nu_{ul} m c}}_{\text{classical}} f_{lu}  \\
f_{lu} &= \frac{2 m }{3 \hbar^2 g_l c^2} (E_u - E_l) \sum \abs{d_{lu}}^2
\,.
\end{align}

The quantity \(f_{lu}\) is called the \textbf{oscillator strength}; the reason for this definition is that the quantity multiplying \(f_{lu}\) in the expression for the Einstein coefficient is the coefficient we would get with a classical oscillator; the oscillator strength is the quantum correction to it.

\section{Line broadening}

So far, we have implicitly assumed that the transition can be described by a single frequency, but as was discussed earlier in the course this is not really the case; instead, the line should be described by a certain function \(\phi (\nu )\) which is peaked around that frequency.

There are several processes which can broaden a line beyond the most basic time-energy uncertainty relation.

\subsubsection{Doppler broadening}

We are often dealing with plasmas which contain ions moving at high velocities due to thermal motion; since this is a random motion the distribution of the velocities' components along the observation direction will be quite wide.
Since we need to move from the atom rest frame to the observer frame, we will need to consider the Doppler effect.

The velocity component along the observation direction affects the effective frequency of the radiation as measured by us.
Let us make this reasoning quantitative.

Suppose that the observation direction is the \(z\) axis, and let us denote the velocity component in that direction as \(v_z\).
Further, let us assume that the velocity is nonrelativistic so that we can work to first order in \(v/c\). Then, the Doppler shift reads
%
\begin{align}
\nu - \nu_0  = \nu_0 \frac{v_z}{c}
\,,
\end{align}
%
where the (variable) frequency \(\nu \) is in the observer frame, while the (fixed) frequency \(\nu_0 \) is in the atom frame.

Since the velocities are assumed to be nonrelativistic and corresponding to thermal equilibrium, their distribution will be Maxwellian, meaning that each of the three components will have a Gaussian distribution: explicitly, the number density of atoms whose velocity component is near \(v_z\) in an interval of width \(\dd{v_z}\) is
%
\begin{align}
\dd{N} \propto \exp(- \frac{m v_z^2}{2 k_B T}) \dd{v_z}
\,.
\end{align}

We can refer this expression to the frequency change by inverting the Doppler relation: we find
%
\begin{align}
v_z = c \frac{\nu - \nu_0 }{\nu_0 }
\implies
\dd{v_z} = \frac{c}{\nu_0 } \dd{\nu }
\,,
\end{align}
%
using which we can refer the Gaussian distribution of the velocity components back to the emitted frequency distribution as
%
\begin{align}
\dd{N} \propto \phi (\nu ) \propto \exp(- \frac{m c^2 (\nu - \nu_0 )^2}{2 k_B T \nu_0^2}) \dd{\nu }
\,.
\end{align}

From this, we can say that the line profile function is given by
%
\begin{align}
\phi (\nu ) = \frac{1}{ \Delta \nu _D \sqrt{\pi }} \exp(- \frac{(\nu - \nu_0 )^2}{\Delta \nu_D^2})
\,,
\end{align}
%
where the width of the line is given by
%
\begin{align}
\Delta \nu _D = \frac{\nu_0 }{c} \sqrt{\frac{2 k_B T}{m}}
\,,
\end{align}
%
and the normalization is fixed by imposing \(\int_0^{\infty  } \phi (\nu ) \dd{\nu } = 1\).

\subsubsection{Natural broadening}

This effect is due to the fact that if a level has a lifetime of \(\Delta t\), then there must be a spread \(\Delta E\) in the transition energies of the level so that \(\Delta t \Delta E \gtrsim \hbar\).
Since no level has an infinite lifetime, not even at \(T =0 \) can a transition be truly monochromatic.

The decay rate of a state \(n\) is given by
%
\begin{align}
\gamma = \sum _{n'} A _{n n'}
\,,
\end{align}
%
where \(n'\) is a state with a lower energy than \(n\) into which the atom can decay, while \(A_{nn'}\) is the Einstein \(A\) coefficient for the transition from \(n\) to \(n'\).

It can be shown that the line profile due to natural broadening is given by a Lorentzian or Lorentz profile,
%
\begin{align}
\phi (\nu ) = \frac{1}{4 \pi^2} \frac{\gamma }{(\nu - \nu_0 )^2 + (\gamma / 4 \pi )^2}
\,.
\end{align}

It can also be shown that certain other effects, such as microturbulence, can be described by a similar profile: this is then accomplished by defining a ``generalized transition rate'' \(\Gamma \) to replace the transition rate \(\gamma \).
We will use the letter \(\Gamma \) in the next section.

\subsubsection{Combined Doppler and Lorentz profile}

We can give a description of the combined effects of the two kinds of broadening we discussed so far, which is needed since they will both occur in general.

The Lorentz profile referred to the observed frequency of the transition (which can be shifted due to the Doppler effect) is given, like before, as
%
\begin{align}
\phi (\nu ) = \frac{\Gamma / 4 \pi^2}{(\nu - \nu_0^{\text{obs}} )^2 + (\Gamma / 4 \pi )^2}
\,,
\end{align}
%
where
%
\begin{align}
\nu_0^{\text{obs}} = \nu_0 + \nu_0 \frac{v_z}{c}
\,,
\end{align}
%
so we can refer the profile to the atom frame like
%
\begin{align}
\phi (\nu ) = \frac{\Gamma / 4 \pi^2}{\qty[\nu - \nu_0 \qty(1 + v_z / c)]^2 + (\Gamma / 4 \pi )^2}
\,.
\end{align}

In order to find the observed broadening we need to average this over all the possible \(v_z\) according to their Gaussian distribution: this yields
%
\begin{align}
\phi (\nu ) &= \frac{\Gamma }{4 \pi^2}
\int_{- \infty }^{\infty } \frac{\sqrt{m / 2 \pi k_B T}\exp(- m v_z^2 / 2 k_B T)}{\qty[\nu - \nu_0 \qty(1 + v_z/c)]^2 + (\Gamma / 4 \pi )^2} \dd{v_z}  \\
&= \frac{1}{\Delta \nu_D \sqrt{\pi }} H(a, u)
\,,
\end{align}
%
where we introduced the Voigt function, which cannot be computed analytically:
%
\begin{align}
H(a, u) = \frac{a}{\pi }  \int_{- \infty }^{\infty } \frac{e^{- y^2} \dd{y}}{a^2 + (u-y)^2}
\,,
\end{align}
%
whose arguments are \(a = \Gamma / 4 \pi \Delta \nu _D\) and \(u = (\nu - \nu_0 ) / \Delta \nu _D\).
This finally yields the Voigt profile, which is basically the convolution of the Gaussian and Lorentzian profiles.

\end{document}


\section{Semantics definitions}
\label{sec:semant-defin}

% \input{fig-reduction}

% Two figures present the operational semantics in traditional style as
% an evaluation judgment $\Store, \Perm, \VEnv \vdash e \Downarrow
% \Store', \Perm', r$.
% \Cref{fig:reduction} contains the lambda calculus reductions  and
% \cref{fig:reduction-resources} shows the resource-related reductions.

\input{fig-full-code}

\cref{fig:full-big-step-interpretation} presents  the full big-step
interpretation. \cref{fig:full-big-step-interpretation-resources}
contains the cases for resources.

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "main"
%%% End:


\section{Conclusions}

The ability of an \gls{ESN} to predict dramatic changes in electricity demand
may cause skepticism, especially given the simplicity of its implementation.
It is important to note that a chaotic spatiotemporal system, like weather, is
the result of complex dynamics and not randomness. We demonstrated that even a
basic \gls{ESN} can predict the evolution of a dynamic system, such as
electricity demand.
More work needs to be done to improve prediction accuracy for the purpose of
load following with nuclear power plants. In the future we will use \glspl{ESN}
to forecast electricity production from solar and wind. We will also explore the
impact of training length and network size on accuracy. Finally, we must
determine an optimum set of input values for net demand prediction. These values
might include temperature, wind speed, air pressure, and irradiance because of
possible interactions among this data that could influence electricity
production from renewable sources.


\chapter{Game, Models and Metrics}
\label{ch3:game_model}

In this chapter, we first describe the proposed language game and the definition of numerals in our game. We then introduce the architecture of models we trained and also the transformed iterated learning framework for training models.

\section{Game Description}
\label{sec3.1:game_description}

Unlike traditional simulation methods in evolutionary linguistics introduced in Section \ref{sec2.1:evolang}, there are 3 necessary components in our architecture and they are given as follows:

\begin{itemize}
  \item \textit{Environment}: To imply our linguistic assumption as well as make the size of environment limited and thus analysable, all perceptions in the established environment are sequences of objects represented by one-hot vectors. For ease of demonstration, we denote these objects as $o \in \mathcal{O}$ where $\mathcal{O} = \{A, B, C, \dots\}$ is the universal set of all kinds of objects in the following sections.
  \item \textit{Agents}: There are 2 kinds of agents in our project: i) \textit{speakers} $S$ that can observe objects in the environment and emit messages $m_i$; ii) \textit{listeners} $L$ that can receive the messages and generate a sequence of objects.
  \item \textit{Dynamics}: In this project, the dynamics mean not only the manually designed reward function for agents but also all elements related to training them, e.g. iterated learning and blank vocabulary. The details will be introduced in Subsection \ref{ssec3.2.3:loss_learning} and Subsection \ref{ssec3.2.4:iterated_learning}.
\end{itemize}

It worth mentioning that one premise of our project is that we do not have any assumption about the architecture of computational agents, and we focus more on the representations from environments as well as how agents are trained.

\subsection{Game Procedure}
\label{ssec3.1.1:game_procedure}

 The first proposed game is to let listeners reconstruct sets of objects based on the messages transmitted by speakers, thus we call it ``Set-Reconstruct'' game. The overall view of the proposed Set-Reconstruct game is illustrated in Figure \ref{fig2:game_procedure} given as follow.

\begin{figure}[!h]
  \centering
  \includegraphics[width=0.8\textwidth]{graphs/task_illustration.pdf}
  \caption{Diagram of Game Playing Procedure.}
  \label{fig2:game_procedure}
\end{figure}

According to the steps of playing games at iteration $i$, the components of our games are illustrated as follows:
\begin{enumerate}
  \item Perceptions: the perception from environments is a \textbf{set} of objects, i.e. $s_i=\{o_{i_1}, o_{i_2}, \dots\ o_{i_n}\} \in \mathcal{S}$ where $n$ is the number of elements and $\mathcal{S}$ is meaning space.
  \item Speaker observation and message generation: after observing and encoding the perception, speaker $S$ would generate a message $m_i=\{t_{i_1}, t_{i_2}, \dots, t_{i_{|M|}}\} \in \mathcal{M}$ where $|M|$ is the maximum length of messages, $t_k \in V$ ($k \in {1, \dots, |V|}$) are selected from a randomly initialised vocabulary such that the symbols in the initially meaningless vocabulary whose size is $|V|$, and $\mathcal{M}$ is message space;
  \item Listener receiving message and perception reconstruction: after receiving and encoding the message $m_i$, the listener would generate a \textbf{sequence} $\hat{s}_i = \{\hat{o}_{i_1}, \hat{o}_{i_2}, \dots\ \hat{o}_{i_n}\}$ whose symbols are identical to those in the original perception $s_i$;
  \item Reward and parameter update: by comparing $s_i$ and $\hat{s}_i$, we take the cross-entropy between them as the reward for both listener and speaker and update parameters of both speaker and listener with respect to it.\footnote{Different ways of updating parameters are introduced in Section \ref{sec3.2:models}.}
\end{enumerate}

One thing that needs to be highlighted is that the perceptions $s_i$ are sets and thus order of objects would not make any difference. Further, we argue that the only important feature that need to be transmitted is actually the numbers of different objects which corresponds to the function of numerals in natural language.

\subsection{Functions of Numerals in the Game}
\label{ssec3.1.2:numeral_in_game}

Broadly speaking, numerals are words that can describe the numerical quantities and usually act as determiners to specify the quantities of nouns, e.g. "two dogs" and "three people". Also, under most scenarios, numerals correspond to non-referential concepts\cite{da2016wow}. Considering the objective of listeners $L$ in our language game, we define a numeral as a symbol $t^n$ at \textbf{position} $i$ indicating a function that reconstructs some object $o_i$ exactly $n$ times:

\begin{equation}
  t^n: o_i \rightarrow \{\overbrace{o_i, \dots, o_i}^{n \mbox{ elements}}\}
  \label{eq:3.1numeral_define}
\end{equation}

Note that, the meaning of a symbol is not only decided by itself but also its position in message, as $L$ would encode meanings of symbols according to their appearance in messages.

From the side of speakers $S$, a numeral is defined as a symbol $t^n$ at \textbf{position} $i$ that represents the numbers of specific object $o_i$, as we cannot tell whether agents realise the meanings of symbols are not related to their positions in the messages without specifically designed model architecture. Thus, we expect speaker $S$ would first learn to count the number of different objects and then encode them into a sequence of discrete symbols. As \cite{Siegelmann1992NN} shows that Recurrent Neural Networks (RNNs) are Turing-complete and Long-short Term Memory (LSTM) model proposed by \cite{hochreiter1997long} is a super set of RNN, it is safe to claim that LSTM is also Turing-complete and thus capable of counting numbers of objects.

\subsection{A Variant: Set-Select Game}
\label{ssec:3.1.3:refer_game}

\begin{figure}[!h]
  \centering
  \includegraphics[width=0.8\textwidth]{graphs/setrefer_game.pdf}
  \caption{Diagram of Referential Game Playing Procedure.}
  \label{fig3:refer_game_procedure}
\end{figure}

We illustrate the Set-Select game, a referential variant of Set-Reconstruct game, in Figure \ref{fig3:refer_game_procedure} given above. The only difference is that listeners need to select the correct set of objects among several distractors \footnote{A distractor is a set that contains different numbers of objects as the correct one.} instead of reconstructing it.

\section{Proposed Models}
\label{sec3.2:models}

\begin{figure}[!h]
  \centering
  \includegraphics[width=0.9\textwidth]{graphs/set2seq2_.pdf}
  \caption{Overall Diagram of Model Architectures for Playing Games.}
  \label{fig4:model_arch}
\end{figure}

We illustrate the overall architecture of our models in Figure \ref{fig4:model_arch} given above.

A speaker $S$ consists of 2 components: i) a set encoder that takes a set of objects as input and outputs its vector representation $h_s^s$; ii) a standard LSTM sequence decoder that can generate a message $s_{i_1}, s_{i_2}, s_{i_3}, \dots$ based on $h_s^s$.

As for a listeners $L$, it would first encode messages with a LSTM sequence encoder and get the feature vector $h^l_m$. Then, in the Set-Reconstruct game, $L$ would take $h^l_m$ as the initial hidden state and predict a sequence of objects with a LSTM sequence decoder, which is shown by the right upper part of Figure \ref{fig4:model_arch}. As for in Set-Select game, $L$ would compare $h^l_m$ with several sets which are encoded by set encoders of $L$, and select the one shown to $S$ based on the dot product between $h^l_m$ and feature vectors of all candidate sets.

Further details are shown in the following subsections.

\subsection{Speaker}
\label{ssec3.2.1:speaker}

The architecture of our speaking agents is very similar to the Seq-to-Seq model proposed by \cite{sutskever2014sequence} except that replace the encoder for input sequences with a set encoder whose details are introduced in the following subsubsection. As Seq-to-Seq model is quite popular nowadays, we skip details about how to generate sequences which correspond to the messages in our games, and focus on how to encode sets of objects.

\subsubsection{Set Encoder}
\label{sssec3.2.1.1:set_encoder}

Our set encoder shares an almost same architecture of inputting sets proposed by \cite{vinyals2015order}. However, as there is an addition in $softmax$ function and it would introduce counting bias into the feature representation of sets, we replace equation (5) in \cite{vinyals2015order} with the following operation in order to avoid exposing counting system to models:

\begin{equation}
  a_{i,t} = \sigma(e_{i,t})
  \label{eq3.2.1.1:sigmoid_to_replace_softmax}
\end{equation}
where $\sigma$ is sigmoid function.

Thus, assume the input for speaker $S$ is a set $s_i=\{o_{i_1}, o_{i_2}, \dots\ o_{i_n}\}$. The first step is to read the set $s_i$ as a sequence and project all objects to dense vectors by an embedding layer. Based on the sequence $\{w_{i_1}^s, w_{i_2}^s, \dots\ w_{i_n}^s\}$ (where $w_{i_k}^s$ is the embedding vector of $o_{i_k}$ for speaker where $k\in \{1, \dots, n\}$), the calculation of $h_s^s$ can be given as follows:

\begin{equation}
  \begin{split}
    e_{i, t}^s & = f(q_{t-1}^s, w_i^s) \\
    a_{i, t}^s & = \sigma(e_{i,t}^s) \\
    r_t^s & = \sum_i a_{i,t}^s w_i^s  \\
    q_t^s &= LSTM(r_t, q_{t-1}^s, c_{t-1}^s)
  \end{split}
  \label{eq3.2.1.2:speaker_hidden_calculation}
\end{equation}
where $t\in \{1, \dots, T\}$ is the number of attention times, $f$ is an affine layer, $q^s_{t}$ and $c^s_t$ are hidden and cell states in LSTM respectively.

Besides, in our implementation, $T$ is set to be the same as the number of all types of objects, as we want to help models to represent number of each kind of objects as features in the vector representation of input set.

\subsubsection{Message Generator}
\label{sssec3.2.1.2:msg_generator}

To generate the message $m_i$, we follow \cite{havrylov2017emergence} and adopt a LSTM-based sequence decoder with 2 different kinds of sampling mechanisms: i) direct sampling that directly sample from the corresponding categorical dist6ribution specified by $softmax(Wh_k^s + b)\ \forall k\in {1, 2, \dots, |M|}$; ii) Gumbel-softmax estimator proposed by \cite{jang2016categorical} with straight-through trick introduced by \cite{bengio2013estimating}. Beside, the learning mechanisms also vary for these 2 different sampling methods, which is further discussed in Subsection \ref{ssec3.2.3:loss_learning}.

Note that the length of each message $m_i$ is fixed to $|M|$ and symbols $t_{i_1},\dots,t_{i_|M|}$ are all one-hot vectors that represent different discrete symbols. The effect of number of all discrete message symbols $|V|$ and length of messages $|M|$ on the emergent language is further discussed in Chapter \ref{ch4:results_analysis}.

\subsection{Listener}
\label{ssec3.2.2:listeners}

The architectures of listening agents are specifically designed for handling different kinds of tasks/games and thus vary from Set-Reconstruct game to Set-Select game.

\noindent\textbf{Listener in Set-Reconstruct Game}: The listener in Set-Reconstruct game has exactly the same architecture as Seq-to-Seq model proposed by \cite{sutskever2014sequence}. And, when combined with speaker model, the overall model is called ``Set2Seq2Seq''.

\noindent\textbf{Listener in Set-Select Game}: The listener in Set-Select game would also first encode messages with a LSTM like it is in standard Seq-to-Seq model. However, as it needs to select among several candidates, it also needs to encode all these sets with Set Encoder introduced in Subsection \ref{sssec3.2.1.1:set_encoder}. Then, the listener would make predictions based on the dot-products between embedding of message $h^r_m$ and embeddings of each set of objects. Similarly, when combined with speaker model, the overall model is called as ``Set2Seq2Choice''.

\subsection{Loss/Reward and Learning}
\label{ssec3.2.3:loss_learning}

\textbf{In Set-Reconstruct game}, as the predictions of listeners are a sequence of objects $\hat{s}_i=\{\hat{o}_{i_1}, \dots, \hat{o}_{i_n}\}$, we use cross-entropy between the original set and the predicted sequence as the objective function that needs to be minimised. Formally,

\begin{equation}
  \mathcal{L}_{\theta^S, \theta^L}(o_{i_1}, \dots, o_{i_n}) =\mathbb{E}_{m_i\sim p_{\theta^S}(\cdot|s_i)} \left[ -\sum_{k=1}^{n} o_{i_k} \log(p(\hat{o}_{i_k}|m_i, \hat{o}_{-i_k})) \right]
  \label{eq3.2.3.1:cross_entropy_seq}
\end{equation}
where $\hat{o}_{-i_k}$ represent all predicted objects preceding $\hat{o}_{i_k}$.

\noindent\textbf{In Set-Select game}, we still use the cross entropy between the correct candidate and  as the loss to minimise, i.e.

\begin{equation}
  \mathcal{L}_{\theta^S, \theta^L}(s_i) = \mathbb{E}_{m_i\sim p_{\theta^S}(\cdot|s_i)} \left[-\sum_{k=1}^{C} s_i log(p(c_k)) \right]
  \label{eq3.2.3.2:cross_entropy_choose}
\end{equation}
where $c_k$ is the predicted logit score for candidate $k$ among $C$ candidates.

In the case that we use Gumbel-softmax to approximate sampling messages from speaker $S$, parameters $\theta^S$ and $\theta^L$ are learnt by back-propagation. In the case that we use direct sampling, $\theta^L$ is still learnt by back-propagation, where as $\theta^S$ is learnt by REINFORCE estimator \cite{williams1992simple} with cross-entropy scores as rewards.

\subsection{Neural Iterated Learning}
\label{ssec3.2.4:iterated_learning}

The evolutionary linguistic community has already studied the origins and metrics of language compositionality since \cite{kirby2002emergence} which points out a cultural evolutionary account of the origins of compositionality and proposes iterated learning to model this procedure. Thus, to facilitate the emergence of compositionality among the autonomous communication between agents, we also trained our agents in a iterated learning fashion. In the original iterated learning, an agent can both speak and listen. However, in this project, agent can be either a speaker or a listener, not both at the same time. Thus, we slightly transform the iterated learning framework and call the following one ``neural iterated learning'' (NIL).

Following the overall architecture of iterated learning, we also train agents generation by generation. In the beginning of each generation $t$, we would randomly re-instantiate a new speaker $S_t$ and a new listener $L_t$ and then execute the following 3 phases:

\begin{enumerate}
  \item \textbf{Speaker Learning phase}: During this phase, we would train $S_t$ with the set-message pairs generated by $S_{t-1}$, and the number of epochs is set to be fixed. Note that there is no such phase in the initial generation, as there is no set-message pair for training $S_t$.
  \item \textbf{Game Playing phase}: During this phase, we would let $S_t$ and $L_t$ cooperate to complete the game and update $\theta^S_t$ and $\theta^L_t$ with loss/reward illustrated in previous section, and use early-stopping to avoid overfitting.
  \item \textbf{Knowledge Generation phase}: During this phase, we would feed all $s_i$ in training set into $S_t$ and get corresponding messages $m_i$. Then, we would keep the sampled ``language'' for $S_{t+1}$ to learn.
\end{enumerate}

\subsection{Baseline Models}
\label{ssec3.2.5:baselines}

To get the upper bounds of our multi-agent communication systems, we remove the communication between speaker and listener to be the baseline models.

In Set-Reconstruct game, our baseline is Set-to-Seq model which first encodes the input set $s_i$ with the set encoder introduced in subsection \ref{sssec3.2.1.1:set_encoder} and then directly generate the predicted sequence $\hat{s}_i$ following the sequence generation in standard seq-to-seq model.

As for in Set-Select game, our baseline is Set-to-Choose model, in which speaker directly transmit representation vector $h^s_s$ of set $s_i$ to listener. And, listener compare $h^s_s$ with all candidate sets to make a selection.

\section{Compositionality and Metrics}
\label{sec3.3:metrics}

With the recent rapid development of grounded language learning, measuring the compositionality of emergent communication protocol attracts more and more attention nowadays, e.g. \cite{andreas2019measuring}, \cite{lowe2019pitfalls}.

First of all, to better define compositionality, we argue that if a language is said to be perfect compositional, then it should satisfy the following 2 properties:

\begin{itemize}
    \item \textbf{Mutual Exclusivity}: Symbols describing different values of a same property should be mutually exclusive to each other. For example, ``green'' and ``red'' are both used to describe colour of an object and they should not appear at the same time as an object can not be green and red at the same time.
    \item \textbf{Orthogonality}: Appearance of symbols for describing a property should be independent from the appearance of symbols used to describe another property. For example, the appearance of symbols used for describing colours of objects should be independent from the appearance of symbols used for describing shapes of objects.
\end{itemize}

As the setting of our game is simple and the space size is limited, we follow \cite{brighton2006understanding} and take the topological similarity between meaning space (space of all sets of objects) and message space as the metric of compositionality. Briefly speaking, as much of language is neighbourhood related, i.e. nearby meanings tend to be mapped to nearby messages, the compositionality of language can be measured as the correlation degree between distances of meanings and distances of corresponding messages. For example, the meaning of set $\{A,A,A,B,B\}$ is closer to $\{A,A,B,B\}$ than $\{A,A,A,A,B,B,B\}$. In natural language (which is perfectly compositional), messages for  $\{A,A,A,B,B\}, \{A,A,B,B\}, \{A,A,A,A,B,B,B\}$ are ``3A2B'', ``2A2B'' and ``4A3B''\footnote{In Chapter \ref{ch4:results_analysis}, we would illustrate messages with lower case alphabets. To make them easier to understand, we use natural language here.} respectively. However, in a non-compositional language, the messages may be ``5B5A'', ``1C2E'' and ``3A4C'',  which are randomly sampled mappings between meaning space and message space.

In order to calculate the topological compositionality, we need define the distance metric for meaning space and message space respectively. Thus, for an input set $s_i$, we could first count the number of each kind of object and then concatenate the Arabic numerals as the meaning sequence. Take a set $s_i=\{A, A, A, B, B\}$ for example, the corresponding meaning sequence would be ``32'' as there are 3 $A$ and 2 $B$ in $s_i$.\footnote{Again, the appearing order of objects would not effect the meaning sequence of a set.} As for the message space, we have several different settings which are further illustrated in subsection \ref{ssec4.2.2:topo_sim}, and edit distance as in \cite{brighton2006understanding} is also included.

Meanwhile, as we could perfectly encode the meaning of a set into natural language, we could take the speaker as a machine translation model that translates a meaning represented in natural language into emergent language invented by computational agents themselves. Inspired by this point of view, we could also use BLEU score proposed by \cite{papineni2002bleu} as a metric of semantic similarities between messages. For the sets that share more similar meanings, we expect their corresponding messages to share more uni-grams or bi-grams or so on. Following the above example, in a perfectly compositional language, as $\{A,A,A,B,B\}$ locates very close to $\{A,A,B,B\}$, their messages (``3A2B'' and ``2A2B'') share $3$ uni-grams (``A'', ``B'' and ``2'') and $2$ bi-grams (``A2'' and ``2B'') in common. However, in a non-compositional language, e.g. in which the messages for $\{A,A,A,B,B\}$ and $\{A,A,B,B\}$ are ``5B5A'' and ``1C2E'' respectively, the messages share no uni-gram and bi-gram in common.

In our case, the BLEU score between $m_i$ and $m_j$ is calculated as follow:

\begin{equation}
  BLEU(m_i, m_j) = 1 - \sum_{n=1}^{N} \omega_n \cdot \frac{\mbox{Number of common } n\mbox{-grams}}{\mbox{Number of total different } n\mbox{-grams}}
  \label{eq3.3.1:bleu_score}
\end{equation}
where $n$ is the size of $n$-grams and $\omega_n$ is the weight for similarity based on $n$-grams. In the following discussions, we would denote BLEU score based on $n$-grams as BLEU-$n$, e.g. BLEU score based on uni-grams would be represented as BLEU-1.


\section{Turns}
During combat, a single \textbf{turn} is roughly equivalent to six seconds in the game world. Each turn is subdivided into two phases: the \textbf{planning phase}, and the \textbf{execution phase}. During the planning phase, each of the two opposing sides plan out their actions. During the execution phase, both side's planned actions are simultaneously executed, with differing success. Generally, during the execution phase, all action by player characters and non-player characters alike is involuntary. When two characters decide to attack each other at the same body part during the planning phase, it is very likely during the execution phase that one of them will parry the attack, effectively wasting that turn.\newline
Should a combatant commit a particularly punishable move, such as a clumsy attack \textit{(failed roll against dexterity)}, the target has to take a roll for willpower. Should the roll fail, the character will commit an involuntary action: instinctively counterattack. Should the roll be succesfull, the character's controller can decide whether they wish to counterattack or not, and if yes, then how exactly, effectively granting them an extra turn.\newline
A turn can also be spent by simply moving rather than attacking or casting a spell. However, this tabletop roleplaying system does not define any system for mapping movement, attributes and turns together, so players have to make up house rules for defining movement on a grid-based system. Under house rules, a turn can also be spent doing other potentially important actions, but hostile combatants may in turn intercept said actions and attack the character.\newline
Since combat happens on two phases and players may not be able to necessarily anticipate hostile actions during the planning phase, they may give conditional orders to their own characters, such as \textit{"retaliate if attacked (in melee)"} or \textit{"attempt to parry or block attacks but do not retaliate if attacked"}.\newline
To sum up:
\begin{enumerate}
  \item \textbf{Planning phase:} Each side decides what actions their characters intend to commit during this turn. Characters with high dexterity may plan more actions, as they may be fast enough to actually complete them.
  \item \textbf{Execution phase:} Each character attempts to commit their actions. Since targets and action-commiters will inevitably overlap, the intended actions of certain characters will be intercepted, causing a roll againt willpower to decide if the interrupted character's next action will be involuntary or player-controlled.
  \item The results of the turn are evaluated before the next turn may begin. Any damage done to characters is documented. Characters with negative status effects that prevent action are forced to skip the next turn. Damage done by negative status effects like poison and bleeding is evaluated.
  \item The turn is over, and the planning phase of the next turn may begin.
\end{enumerate}
During each attack - melee or ranged - the character's dexterity is measured up with a randomly generated or dice-rolled number.
\begin{itemize}
\item \textbf{Targeted Strike:} The character targets a specific body part of the enemy. On every strike, they roll either two 10-sided dice or four 5-sided dice \textit{(or use a random number generator to generate a number between 0 and 20)}, where randomness is measured up to the character's \textbf{Dexterity} stat. If the number is below the character's dexterity minus four, the strike is a success and hits the intended body part \textit{(if it was a targeted strike)} - if it's between dexterity minus four and dexterity, it's a \textit{"bittersweet success"} and the character hits a neighbouring body part instead \textit{(in case of torso: the neighbour is randomly picked, RNG or single 6-sided dice roll)}. If the rolled number is above the character's dexterity, it's a miss.
\item \textbf{Untargeted Strike:} The character simply swings their weapon in the enemy's general direction. A random number is generated or rolled between 0 and 20. If the character rolls below their dexterity plus two, it is a success, if over their dexterity plus two, a failure. The body part that gets damaged is decided randomly - which is discussed at the \textbf{Body parts} section of this document later on.
\end{itemize}
By default, involuntary counterattacks are always untargeted.


\subsection{Topology Skeletons}
\begin{frame}[fragile]{Simple Pipe}
A simple Pipe (without Futures):
\begin{lstlisting}[frame=htrbl]
pipeSimple :: conf -> [arr a a] -> arr a a
pipeSimple conf fs =
  loop (arr snd &&&
    (arr (uncurry (:) >>> lazy) >>> loopParEvalN conf fs)) >>>
  arr last
\end{lstlisting}
\end{frame}
\begin{frame}[fragile]{Pipe with Futures}
With Futures we get inter-node communication:
\begin{lstlisting}[frame=htrbl]
pipe :: conf -> [arr a a] -> arr a a
pipe conf fs =
	unliftFut conf (pipeSimple conf (map (liftFut conf) fs))
\end{lstlisting}
We can even implement
\begin{lstlisting}[frame=htrbl]
pipe2 :: conf -> arr a b -> arr b c -> arr a c|
\end{lstlisting}
Which gives us parallel composition:
\begin{lstlisting}[frame=htrbl]
(|>>>|) :: arr a b -> arr b c -> arr a c
(|>>>|) = pipe2 ()
\end{lstlisting}
\end{frame}
\begin{frame}[fragile]{Ring}
\begin{center}
\includegraphics[scale=0.8]{images/ring.pdf}
\end{center}
\end{frame}
\begin{frame}[fragile]{Torus}
\begin{center}
\includegraphics[scale=0.8]{images/torus.pdf}
\end{center}
\end{frame}


{{ '\\section{{Results for {aligner}/{caller}}}'.format(aligner=ALIGNER_LABEL, caller=CALLER_LABEL) }}
The following sections denote results that are specific the the pipeline consisting of aligner ``{{ ALIGNER_LABEL }}" and variant caller ``{{ CALLER_LABEL }}".

\subsection{RTG vcfeval Results}
The following sections contain results as reported by \texttt{rtg vcfeval}.
For information on how \texttt{rtg vcfeval} was invoked, refer to Section \ref{sec:rtg_vcfeval}.

\subsubsection{Pipeline Performance}
Table \ref{tab:{{ ALIGNER }}_{{ CALLER }}_rtg_summary} contains the results from the RTG vcfeval \texttt{summary.txt} file that primarily contains summary information regarding the evaluated VCF file.
We copied the results from this summary (unfiltered ``None'' row) and calculated summary mean and standard deviation as well.

Sensitivity is the fraction of annotated true positives that were correctly identified by the pipeline,
precision is the fraction of called variants that were part of the truth set,
and F-measure is the harmonic mean of sensitivity and precision.
A perfect caller would have 1.0000 for all scores.

\begin{table}
    \centering
    \begin{tabular}{|l|r|r|r|r|r|}
        \hline
        {{ FORMAT.HEADER_COLOR }}\textbf{Sample}
        {% for fk in FORMAT.RTG_RESULTS_ORDER %}
            &{{ '\\textbf{'+FORMAT.RTG_RESULTS.get(fk, {}).get('label', fk)+'}' }}
        {% endfor %}
        \\ \hline
        {% set final_sample = sorted(RTG_RESULTS.SAMPLE_SUMMARY.keys())[-1] %}
        {% for sample in sorted(RTG_RESULTS.SAMPLE_SUMMARY.keys()) %}
            {{ sample }} ({{ METADATA[sample]['sample'] }})
            {% for fk in FORMAT.RTG_RESULTS_ORDER %}
                &{{ FORMAT.RTG_RESULTS.get(fk, {}).get('format', FORMAT.RTG_RESULTS['default']['format']).format(RTG_RESULTS.SAMPLE_SUMMARY[sample][fk]) }}
            {% endfor %}
            {% if sample != final_sample %}
                \\ \hline
            {% else %}
                \\ \hhline{|=|=|=|=|=|=|}
            {% endif %}
        {% endfor %}
        {{ FORMAT.TOTAL_COLOR }} Mean$\pm$Stdev
        {% for fk in FORMAT.RTG_RESULTS_ORDER %}
            {% set formatting = FORMAT.RTG_RESULTS.get(fk, {}).get('format', FORMAT.RTG_RESULTS['default']['format']) %}
            &{{ (formatting+'$\\pm$'+formatting).format(RTG_RESULTS.TOTAL_SUMMARY[fk]['MEAN'], RTG_RESULTS.TOTAL_SUMMARY[fk]['STDEV']) }}
        {% endfor %}
        \\ \hline
    \end{tabular}
    \caption{Summary metrics from RTG vcfeval for aligner ``{{ ALIGNER_LABEL }}'' and variant caller ``{{ CALLER_LABEL }}''.}
    \label{tab:{{ ALIGNER }}_{{ CALLER }}_rtg_summary}
\end{table}

\subsubsection{Variant Counts}
Table \ref{tab:{{ ALIGNER }}_{{ CALLER }}_variants} contains a summary of the number of false and true positive variant calls after stratifying the results by variant type and genotype.

\begin{table}
    \centering
    \begin{tabular}{|l|l|r|r|r|r|r|r|r|}
        \hline
        {{ FORMAT.HEADER_COLOR }}\textbf{Sample}&
        \rot{\textbf{RTG Result}}
        {% for vt in FORMAT.VARIANT_ORDER %}
            {% for ct in FORMAT.CALL_ORDER %}
                &{{ '\\rot{{\\textbf{{{vt}-{ct}}}}}'.format(vt=vt, ct=ct) }}
            {% endfor %}
        {% endfor %}
        &\rot{\textbf{Total Calls}}
        \\ \hline
        {% for at in ['FP', 'TP'] %}
            {% for sample in sorted(RTG_RESULTS.FEATURES.keys()) %}
                {% if sample == 'total' %}
                    {{ FORMAT.TOTAL_COLOR }}Total
                {% else %}
                    {{ sample }} ({{ METADATA[sample]['sample'] }})
                {% endif %}
                &{{ at }}
                {% for vt in FORMAT.VARIANT_ORDER %}
                    {% for ct in FORMAT.CALL_ORDER %}
                        &{{ '{0:,}'.format(RTG_RESULTS['FEATURES'][sample][vt][ct][at]) }}
                    {% endfor %}
                {% endfor %}
                &{{ '{0:,}'.format(RTG_RESULTS['FEATURES'][sample]['sum'][at]) }}
                {% if at == 'FP' and sample == 'total' %}
                    \\ \hhline{|=|=|=|=|=|=|=|=|=|}
                {% else %}
                    \\ \hline
                {% endif %}
            {% endfor %}
        {% endfor %}
    \end{tabular}
    \caption{This table shows the number of false and true positive variants calls as reported by \texttt{rtg vcfeval} for the aligner {{ ALIGNER_LABEL }} and variant caller {{ CALLER_LABEL }}. The variants are further divided by variant type (SNV or INDEL) and genotype (HET=heterozygous, HOM=homozygous, HE2=complex heterozygous).  The ``total'' label refers to the sum of all samples for the corresponding ``RTG Result'' type.}
    \label{tab:{{ ALIGNER }}_{{ CALLER }}_variants}
\end{table}

\subsection{Model Results}
The following sections contain results specific to the final trained models.

\subsubsection{Selected Models}
Table \ref{tab:{{ ALIGNER }}_{{ CALLER }}_best_models} contains the selected models for aligner ``{{ ALIGNER_LABEL }}'' and caller ``{{ CALLER_LABEL }}'' given the minimum capture rate, $S_m = {{ TRAINING_RESULTS.CLINICAL_MINIMUM }}$, and the target capture rate, $S_t = {{ TRAINING_RESULTS.CLINICAL_TARGET }}$.

\begin{table}
    \centering
    \begin{tabular}{|l|l|r|r|r|r|r|}
        \hline
        {{ FORMAT.HEADER_COLOR }}
        \textbf{Variant type}
        {% for fk in FORMAT.MODEL_RESULTS_ORDER %}
            {% if fk == 'best_model' %}
                &{{ '\\textbf{'+FORMAT.MODEL_RESULTS.get(fk, {}).get('label', fk)+'}' }}
            {% else %}
                &{{ '\\rot{\\textbf{'+FORMAT.MODEL_RESULTS.get(fk, {}).get('label', fk)+'}}' }}
            {% endif %}
        {% endfor %}
        \\ \hline
        {% for vt in FORMAT.VARIANT_ORDER %}
            {% for gt in FORMAT.CALL_ORDER %}
                {{ vt+'-'+gt }}
                {% for fk in FORMAT.MODEL_RESULTS_ORDER %}
                    &{{ FORMAT.MODEL_RESULTS.get(fk, {}).get('format', FORMAT.MODEL_RESULTS['default']['format']).format(TRAINING_RESULTS.CLINICAL_MODELS[vt+'_'+gt][fk]) }}
                {% endfor %}
                \\ \hline
            {% endfor %}
        {% endfor %}
    \end{tabular}
    \caption{Selected models for aligner ``{{ ALIGNER_LABEL }}'', caller ``{{ CALLER_LABEL }}'', $S_m = {{ TRAINING_RESULTS.CLINICAL_MINIMUM }}$, $S_t = {{ TRAINING_RESULTS.CLINICAL_TARGET }}$.
    If no model passed the criteria, then the ``Best Model'' field will be ``None''.
    Evaluation capture rate is the training capture that was used to gather results for the remaining fields in testing.
    Results prefaced with ``CV'' represent the test results during cross-validation.
    Similarly, results prefaced with ``Final'' represent the results on the held-out testing set during final evaluation.
    Note that we required the models to have capture requirements based on both the CV and Final results.
    In contrast, TP flag rate is not bound by any requirements, but is instead representative of the expected fraction of orthogonal confirmations required if the model is used.}
    \label{tab:{{ ALIGNER }}_{{ CALLER }}_best_models}
\end{table}

\subsubsection{Strict Models}
Table \ref{tab:{{ ALIGNER }}_{{ CALLER }}_strict_models} contains the strict models for aligner ``{{ ALIGNER_LABEL }}'' and caller ``{{ CALLER_LABEL }}'' given the minimum capture rate, $S_m = {{ STRICT_RESULTS.CLINICAL_MINIMUM }}$, and the target capture rate, $S_t = {{ STRICT_RESULTS.CLINICAL_TARGET }}$.
These models are labeled strict due to very high requirements, and the majority of models at different evaluation capture rates fail to pass these criteria.
As a result, many variant/genotype combinations have no passing models or have models that are not practically useful (e.g. a TP flag rate of 99\%).

\begin{table}
    \centering
    \begin{tabular}{|l|l|r|r|r|r|r|}
        \hline
        {{ FORMAT.HEADER_COLOR }}
        \textbf{Variant type}
        {% for fk in FORMAT.MODEL_RESULTS_ORDER %}
            {% if fk == 'best_model' %}
                &{{ '\\textbf{'+FORMAT.MODEL_RESULTS.get(fk, {}).get('label', fk)+'}' }}
            {% else %}
                &{{ '\\rot{\\textbf{'+FORMAT.MODEL_RESULTS.get(fk, {}).get('label', fk)+'}}' }}
            {% endif %}
        {% endfor %}
        \\ \hline
        {% for vt in FORMAT.VARIANT_ORDER %}
            {% for gt in FORMAT.CALL_ORDER %}
                {{ vt+'-'+gt }}
                {% for fk in FORMAT.MODEL_RESULTS_ORDER %}
                    &{{ FORMAT.MODEL_RESULTS.get(fk, {}).get('format', FORMAT.MODEL_RESULTS['default']['format']).format(STRICT_RESULTS.CLINICAL_MODELS[vt+'_'+gt][fk]) }}
                {% endfor %}
                \\ \hline
            {% endfor %}
        {% endfor %}
    \end{tabular}
    \caption{Strict models for aligner ``{{ ALIGNER_LABEL }}'', caller ``{{ CALLER_LABEL }}'', $S_m = {{ STRICT_RESULTS.CLINICAL_MINIMUM }}$, $S_t = {{ STRICT_RESULTS.CLINICAL_TARGET }}$. If no model passed the criteria, then the ``Best Model'' field will be ``None''. Evaluation capture rate is the training capture rate that was used to gather results for the remaining fields in testing. Results prefaced with ``CV'' represent the test results during cross-validation. Similarly, results prefaced with ``Final'' represent the results on the held-out testing set during final evaluation. Note that we required the models to have capture rate requirements based on both the CV and Final results.  In contrast, TP flag rate is not bound by any requirements, but is instead representative of the expected fraction of orthogonal confirmations required if the model is used.}
    \label{tab:{{ ALIGNER }}_{{ CALLER }}_strict_models}
\end{table}

\subsubsection{Feature Importances}
Table \ref{tab:{{ ALIGNER }}_{{ CALLER }}_eli5} contains results regarding feature importances according to the models.  These were gathered using the \texttt{eli5} package and the \texttt{ExtractELI5Results.py} script from this repo. Feature importances may be missing due to any of the following reasons:

\begin{enumerate}
    \item ELI5 interpretation was not run correctly - This could be because the \texttt{ExtractELI5Results.py} script has not been executed or the outputs are not in the expected location.
    \item The model failed to pass our base clinical criteria - We restricted the outputs to only include models that met the minimum capture rate requirement as defined in the ``Selected Models'' section above.
    \item The model is not interpretable by \texttt{eli5} - Not all models provide feature importance measures through eli5 so these results are excluded
\end{enumerate}

\begin{table}
    \centering
    \begin{tabular}{|l|r|r|r|r|r|r|r|}
        \hline
        {{ FORMAT.HEADER_COLOR }}
        \textbf{Feature}
        {% for vt in FORMAT.VARIANT_ORDER %}
            {% for gt in FORMAT.CALL_ORDER %}
                &\rot{{"{"}}{{ vt }}-{{ gt }}}
            {% endfor %}
        {% endfor %}
        &Cumulative \\ \hline
        {% for feature in ELI5_RESULTS.COMBINED_ORDER %}
            {{ feature.replace('_', '\\_') }}
            {% for vt in FORMAT.VARIANT_ORDER %}
                {% for gt in FORMAT.CALL_ORDER %}
                    {% if vt+'_'+gt in ELI5_RESULTS.COMBINED_DICT[feature] %}
                        &{{ '{:0.4f}'.format(ELI5_RESULTS.COMBINED_DICT[feature][vt+'_'+gt]['weight']) }}
                    {% else %}
                        &--
                    {% endif %}
                {% endfor %}
            {% endfor %}
            &{{ '{:0.4f}'.format(ELI5_RESULTS.COMBINED_DICT.get(feature, {}).get('CUMULATIVE_WEIGHT', 0.0)) }}
            \\ \hline
        {% endfor %}
    \end{tabular}
    \caption{This table shows the feature importances results for aligner ``{{ ALIGNER_LABEL}}'' and caller ``{{ CALLER_LABEL }}''. Importances are broken down by category with a cumulative sum at the end. Note that some results may be missing if the pipeline was run incorrectly or the models are not interpretable through \texttt{eli5}.}
    \label{tab:{{ ALIGNER }}_{{ CALLER }}_eli5}
\end{table}

{% for vt in FORMAT.VARIANT_ORDER %}
    {% for gt in FORMAT.CALL_ORDER %}
        \subsubsection{Model for {{vt}}-{{gt}}}
        {% if TRAINING_RESULTS.IMAGE_FILENAMES[vt+'_'+gt] != 'NO_IMAGE_FOUND' %}
            Figure \ref{fig:{{ ALIGNER }}_{{ CALLER }}_{{ vt }}_{{ gt }}} contains the receiver-operator curves (ROC) for the final trained models for aligner ``{{ ALIGNER_LABEL }}'', caller ``{{ CALLER_LABEL }}'', variant type ``{{ vt }}'', and genotype ``{{ gt }}''.
            \begin{figure}[H]
                \centering
                \includegraphics[width=0.65\linewidth]{{"{"}}{{ TRAINING_RESULTS.IMAGE_FILENAMES[vt+'_'+gt] }}}
                \caption{ROC curve for aligner ``{{ ALIGNER_LABEL }}'', caller ``{{ CALLER_LABEL }}'', variant type ``{{ vt }}'', and genotype ``{{ gt }}''.  Note that these curves are zoomed in to focus on only the region greater than the minimum clinical capture rate (0.99).}
                \label{fig:{{ ALIGNER }}_{{ CALLER }}_{{ vt }}_{{ gt }}}
            \end{figure}
        {% else %}
            No image found, try re-running the pipeline with the \texttt{-s} option to produce summary images.
        {% endif %}

        %DEPRECATED: old ELI5 results were placed here

    {% endfor %}
{% endfor %}


\documentclass[letterpaper]{article}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage[left=0.8cm,top=1cm,right=0.8cm,nohead,nofoot]{geometry}

\author{Ken Esler}
\title{Electron-electron-ion Jastrow factor}
\date{\today}
\begin{document}
\maketitle
\newcommand{\riI}{r_{iI}}
\newcommand{\briI}{\mathbf{r}_{iI}}
\newcommand{\rjI}{r_{jI}}
\newcommand{\brjI}{\mathbf{r}_{jI}}
\newcommand{\rij}{r_{ij}}
\newcommand{\brij}{\mathbf{r}_{ij}}
\section{Form of the Jastrow}
The general form of the 3-body Jastrow we describe here depends on the
three inter-particle distances, $(\rij, \riI, \rjI)$.
\begin{equation}
J_3 = \sum_{I\in\text{ions}} \sum_{i,j \in\text{elecs};i\neq j} U(\rij, \riI,
\rjI)
\end{equation}
Note that we constrain the form of $U$ such that
$U(\rij, \riI,\rjI) = U(\rij, \rjI,\riI)$, so as to preserve the
particle symmetry of the wave function.  We then compute the gradient as
\begin{equation}
\nabla_i J_3 =  \sum_{I\in\text{ions}} \sum_{j \neq i}
\left[\frac{\partial U(\rij, \riI,\rjI)}{\partial\rij}
  \frac{\mathbf{r}_i - \mathbf{r}_j}{|\mathbf{r}_i - \mathbf{r}_j|}
+ \frac{\partial U(\rij, \riI,\rjI)}{\partial\riI}
  \frac{\mathbf{r}_i - \mathbf{I}}{|\mathbf{r}_i - \mathbf{I}|}  \right]
\end{equation}
To compute the laplacian, we take
\begin{eqnarray}
\nabla_i^2 J_3 & = & \nabla_i \cdot \left(\nabla_i J_3\right) \\
& = & \sum_{I\in\text{ions}} \sum_{j\neq i } \left[
\frac{\partial^2 U}{\partial \rij^2} + \frac{2}{\rij} \frac{\partial
  U}{\partial \rij} + 2 \frac{\partial^2 U}{\partial \rij \partial
  \riI}\frac{\brij\cdot\briI}{\rij\riI} +\frac{\partial^2 U}{\partial
  \riI^2}
+ \frac{2}{\riI}\frac{\partial U}{\partial \riI} \nonumber
\right]
\end{eqnarray}
We now wish to compute the gradient of these terms w.r.t. the ion position, $I$.
\begin{equation}
\nabla_I J_3 = -\sum_{j\neq i} \left[ \frac{\partial U(\rij, \riI,\rjI)}{\partial\riI}
  \frac{\mathbf{r}_i - \mathbf{I}}{|\mathbf{r}_i - \mathbf{I}|}
+\frac{\partial U(\rij, \riI,\rjI)}{\partial\rjI}
  \frac{\mathbf{r}_j - \mathbf{I}}{|\mathbf{r}_j - \mathbf{I}|} \right]
\end{equation}
For the gradient w.r.t. $i$ of the gradient w.r.t. $I$, the result is a tensor,
\begin{eqnarray}
\nabla_I \nabla_i J_3 & = & \nabla_I \sum_{j \neq i}
\left[\frac{\partial U(\rij, \riI,\rjI)}{\partial\rij}
  \frac{\mathbf{r}_i - \mathbf{r}_j}{|\mathbf{r}_i - \mathbf{r}_j|}
+ \frac{\partial U(\rij, \riI,\rjI)}{\partial\riI}
  \frac{\mathbf{r}_i - \mathbf{I}}{|\mathbf{r}_i - \mathbf{I}|}  \right] \\\nonumber \\\nonumber
& = & -\sum_{j\neq i} \left[
\frac{\partial^2 U}{\partial \rij \riI} \hat{\mathbf{r}}_{ij} \otimes
\hat{\mathbf{r}}_{iI} + \left(\frac{\partial^2 U}{\partial \riI^2} -
\frac{1}{\riI} \frac{\partial U}{\partial \riI}\right)
\hat{\mathbf{r}}_{iI} \otimes \hat{\mathbf{r}}_{iI} \right. + \\\nonumber
& & \left. \qquad \ \ \  \frac{\partial^U}{\partial \rij \rjI} \hat{\mathbf{r}}_{ij} \otimes \hat{\mathbf{r}}_{jI} + \frac{\partial^2 U}{\partial \riI \partial \rjI}
\hat{\mathbf{r}}_{iI}\otimes \hat{\mathbf{r}}_{jI}  +
\frac{1}{\riI} \frac{\partial U}{\partial \riI} \overleftrightarrow{\mathbf{1}}\right]
\end{eqnarray}

\begin{eqnarray}
\nabla_I \nabla_i J_3 & = & \nabla_I \sum_{j \neq i}
\left[\frac{\partial U(\rij, \riI,\rjI)}{\partial\rij}
  \frac{\mathbf{r}_i - \mathbf{r}_j}{|\mathbf{r}_i - \mathbf{r}_j|}
+ \frac{\partial U(\rij, \riI,\rjI)}{\partial\riI}
  \frac{\mathbf{r}_i - \mathbf{I}}{|\mathbf{r}_i - \mathbf{I}|}  \right] \\\nonumber
& = & \sum_{j\neq i} \left[ -\frac{\partial^2 U}{\partial \rij \partial \riI} \hat{\mathbf{r}}_{ij} \otimes \hat{\mathbf{r}}_{iI} +
\left(-\frac{\partial^2 U}{\partial \riI^2}  + \frac{1}{\riI}\frac{\partial U}{\partial \riI} \right)
\hat{\mathbf{r}}_{iI} \otimes \hat{\mathbf{r}}_{iI} - \frac{1}{\riI}\frac{\partial U}{\partial \riI} \overleftrightarrow{\mathbf{1}}
\right]
\end{eqnarray}
For the laplacian,
\begin{eqnarray}
\nabla_I \nabla_i^2 J_3 & = & \nabla_I\left[\nabla_i \cdot \left(\nabla_i J_3\right)\right] \\
& = & \nabla_I \sum_{j\neq i } \left[
\frac{\partial^2 U}{\partial \rij^2} + \frac{2}{\rij} \frac{\partial
  U}{\partial \rij} + 2 \frac{\partial^2 U}{\partial \rij \partial
  \riI}\frac{\brij\cdot\briI}{\rij\riI} +\frac{\partial^2 U}{\partial
  \riI^2}
+ \frac{2}{\riI}\frac{\partial U}{\partial \riI} \nonumber
\right] \\
& = & \sum_{j\neq i }
\left[ \frac{\partial^3 U}{\partial r_{iI} \partial^2 r_{ij}} +
\frac{2}{r_{ij}} \frac{\partial^2 U}{\partial r_{iI} \partial r_{ij}}
+ 2\left(\frac{\partial^3 U}{\partial \rij \partial^2 \riI} -\frac{1}{\riI} \frac{\partial^2 U}{\partial \rij \partial \riI}\right)\frac{\brij\cdot\briI}{\rij\riI} + \frac{\partial^3 U}{\partial^3 \riI} - \frac{2}{\riI^2} \frac{\partial U}{ \partial \riI} + \frac{2}{\riI} \frac{\partial^2 U}{\partial^2 \riI}
\right] \frac{\mathbf{I} - \mathbf{r}_i}{|\mathbf{I} - \mathbf{r}_i|} + \nonumber \\\nonumber
 & & \sum_{j\neq i } \left[ \frac{\partial^3U}{\partial \rij^2 \partial \rjI} + \frac{2}{\rij}\frac{\partial^2 U}{\partial \rjI \partial \rij}
+ 2\frac{\partial^3 U}{\partial \rij \partial \riI \partial \rjI}\frac{\brij\cdot\briI}{\rij\riI}
+\frac{\partial^3 U}{\partial \riI^2 \partial \rjI} + \frac{2}{\riI}\frac{\partial^2 U}{\partial \riI \partial \rjI} \right]
\frac{\mathbf{I} - \mathbf{r}_j}{|\mathbf{r}_j - \mathbf{I}|} + \\\nonumber
& & \sum_{j\neq i } \left[ -\frac{2}{\riI}\frac{\partial^2 U}{\partial \rij \partial \riI}\right] \frac{\mathbf{r}_{ij}}{r_{ij}}
\end{eqnarray}

\end{document}


\section{First-order correlation analysis}
In this section, we analyse the effectiveness of the implemented countermeasures against first-order side-channel analysis based on the linear correlation coefficient (Correlation Power Analysis CPA). For this study, we will target the Sbox output value.

We separate this study in two parts. In the first part, we will characterize the effectiveness of a CPA against this implementation, by considering an attacker with priviledged knowledge. In the second part, we will evaluate the effectiveness of a CPA against this implementation without such knowledge.

\subsection{Priviledged knowledge}
We first study the setting where the attacker knows the random masks used to compute the permutation.

In order to characterize the effectiveness of a CPA against this implemenation, we use the random masks to recompute the permutation $Sh(i)$ for each byte index $i$. We then perform an attack targeting the value

\noindent $Z_{\hat{\key}}[i]=S[\plain[Sh(i)] \oplus \key[Sh(i)] \oplus \hat{\key}]$, where $\hat{\key}$ is an hypothesis on a value of one byte.
The attack is successful if the best hypothesis returned by the attack is $0$.

% Equivalently, $Z[i]=S[P[Sh(i)] \oplus K[Sh(i)] \oplus \hat{k} \oplus K[i]] and the best result is K[i]

\subsubsection{Affinely masked Sbox output}
We suppose the knowledge of both the multiplicative mask and the output mask. This knowledge allows for the prediction of the value $\rmult \times Z_{\hat{\key}}[i] \oplus \rout$ for any hypothesis $\key$. Depending on the index byte, the attack succeeds with around $1.000$ traces.
Figure~\ref{fig:CPA1O_trickedaZb1} illustrates the result of the attack targeting byte 0, using $1.000$ traces.

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.4]{figures/CPA1O_2Mpts_trickedaS+b0_1ktraces.png}
	\caption{Correlation coefficients obtained when targeting $\rmult \times Z_{\hat{\key}}[i] \oplus \rout$, for every value of $\hat{\key}$. Correct hypothesis is plotted  in red. }
	\label{fig:CPA1O_trickedaZb1}
\end{figure}

%attack_results_without_flaw_fixed_100k
\subsubsection{Multiplicatively masked Sbox output}
We suppose the knowledge of the multiplicative mask. This knowledge allows for the prediction of the value $\rmult \times Z_{\hat{\key}}[i]$ for any hypothesis $\hat{\key}$.
The attack is unsuccessful using $50.000$ traces.
Figure~\ref{fig:CPA1O_trickedaZ1} illustrates the result of the attack targeting byte 0, using $50.000$ traces.

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.4]{figures/CPA1O_2Mpts_trickedaS0traces.png}
	\caption{Correlation coefficients obtained when targeting $\rmult \times Z_{\hat{\key}}[i]$, for every value of $\hat{\key}$. Correct hypothesis is plotted  in red. }
	\label{fig:CPA1O_trickedaZ1}
\end{figure}

%attack_results_without_flaw_fixed_100k
\subsubsection{Raw Sbox output}
We suppose no prior knowledge (except the permutation), and predict the value $Z_{\hat{\key}}[i]$ for any hypothesis $\hat{\key}$.
The attack is unsuccessful using $50.000$ traces.
Figure~\ref{fig:CPA1O_trickedZ1} illustrates the result of the attack targeting byte 0, using $50.000$ traces.

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.4]{figures/CPA1O_2Mpts_trickedS0traces.png}
	\caption{Correlation coefficients obtained when targeting $\rmult \times Z_{\hat{\key}}[i]$, for every value of $\hat{k}$. Correct hypothesis is plotted  in red. }
	\label{fig:CPA1O_trickedZ1}
\end{figure}

\subsection{Unknown permutation, processed traces}
We now study the setting where the attacker does not know the random masks used to compute the permutation.

We preprocess the traces in order to average the leakage over the different byte indices manipulation:
\begin{itemize}
	\item for each index $i$ in $[0,15]$, we define a small window $w_i$ of $\ell$ points around the SNR peak corresponding to the manipulation of $\rmult \times S[P[Sh(i)] \oplus K[Sh(i)]]\oplus \rout$ in the characterization phase. In our experiments, the size of the window was arbitrarily fixed to $\ell=11$.
	\item for each trace in our acquisition campaign, we compute the average window $m$ such that for each time sample $j$, $m[j]=\frac{1}{16}\sum_{i=0}^{15} w_i[j]$. We then consider $m$ as our reduced averaged trace of size $\ell$.
\end{itemize}

%/media/nas/projects/ASCAD_CW/ASCAD_ChipWhisperer/ARM/traces/averaged_attack_results_without_flaw_fixed_100k.h5
\subsubsection{Affinely masked Sbox output}
We suppose the knowledge of both the multiplicative mask and the output mask. This knowledge allows for the prediction of the value $\rmult \times S[\plain[i]\oplus \hat{\key}] \oplus \rout$ for any hypothesis $\hat{\key}$ on one byte of the secret key.
Depending on the byte index, the CPA is successful using around $20.000$ to $30.000$ traces.

Figure~\ref{fig:CPA1O_averaged_aZb1} illustrates the results using $50.000$ traces.
\begin{figure}[H]
	\centering
	\includegraphics[scale=0.4]{figures/CPA1O_averaged_aZb1.png}
	\caption{Correlation coefficients obtained when targeting $\rmult \times S[\plain[i]\oplus \hat{\key}] \oplus \rout$, on averaged traces, for every value of $\hat{\key}$. Correct hypothesis is plotted  in red.}
	\label{fig:CPA1O_averaged_aZb1}
\end{figure}

\subsubsection{Multiplicatively masked Sbox output}
With $50.000$ traces, the attack does not succeed when targeting $\rmult \times S[\plain[i]\oplus \hat{\key}]$.
Figure~\ref{fig:CPA1O_averaged_aZ1} illustrates the results using $50.000$ traces.

Figure~\ref{fig:CPA1O_averaged_aZ1} illustrates the results using $50.000$ traces.
\begin{figure}[H]
	\centering
	\includegraphics[scale=0.4]{figures/CPA1O_averaged_aZ1.png}
	\caption{Correlation coefficients obtained when targeting $\rmult \times S[\plain[i]\oplus \hat{\key}] \oplus \rout$, on averaged traces, for every value of $\hat{\key}$. Correct hypothesis is plotted in red.}
	\label{fig:CPA1O_averaged_aZ1}
\end{figure}

\subsubsection{Raw Sbox output}
With $50.000$ traces, the attack does not succeed when targeting $S[\plain[i]\oplus \hat{\key}]$.
Figure~\ref{fig:CPA1O_averaged_Z1} illustrates the results using $50.000$ traces.
Figure~\ref{fig:CPA1O_averaged_Z1} illustrates the results using $50.000$ traces.

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.4]{figures/CPA1O_averaged_Z1.png}
	\caption{Correlation coefficients obtained when targeting $\rmult \times S[\plain[i]\oplus \hat{\key}] \oplus \rout$, on averaged traces, for every value of $\hat{\key}$. Correct hypothesis is plotted  in red.}
	\label{fig:CPA1O_averaged_Z1}
\end{figure}

\subsection{Unknown permutation, non-processed traces}

For the sake of completeness, we also perform these experiments on raw unprocessed traces. No success is obtained when targeting $Z_{\hat{\key}}[i]$ or $\rmult \times Z_{\hat{\key}}[i]$ using $50.000$ traces.
Similarly, by targeting $\rmult \times S[\plain[i]\oplus \hat{\key}] \oplus \rout$, the attack does not succeed.

\subsection{Summary}
The results in this section evidence the effectiveness of the implementation of the countermeasures against first-order side-channel attack.
Assuming knowledge of the mask values, the shuffling countermeasure alone increases the number of necessary traces by a factor $\sim 20$.
Furthermore, masking countermeasures seem to completely thwart first order side-channel attacks using $50.000$ traces.

\begin{figure}[h!]
\centering
\begin{tabular}{|c|c|c|c|c|c|c|}
  \hline
   & \multicolumn{3}{c|}{Known permutation}&\multicolumn{3}{c|}{Unknown permutation}\\
  \hline
  Known & $\rmult, \rout$ & $\rmult $ &  None & $\rmult,\rout$ & $\rmult $  &  None \\
  \hline
  \# Traces& $\approx 1.000$ & $ > 50.000$ & $> 50.000$& $\approx 20.000$ & $ > 50.000$ & > $50.000$\\
  \hline
\end{tabular}
\caption{Number of traces needed for a successful first-order attack, in the different settings.}
\end{figure}


\par
\section{Data Structures}
\label{section:FrontMtx:dataStructure}
\par
The {\tt FrontMtx} structure has the following fields.
\begin{itemize}
\item
{\tt int nfront} : number of fronts.
\item
{\tt int neqns} : number of rows and columns in the factor matrix.
\item
{\tt int symmetryflag} : flag to denote the type of symmetry
of $A + \sigma B$.
\begin{itemize}
\item
{\tt SPOOLES\_SYMMETRIC} --- $A$ and/or $B$ are symmetric.
\item
{\tt SPOOLES\_HERMITIAN} --- $A$ and/or $B$ are hermitian.
\item
{\tt SPOOLES\_NONSYMMETRIC} --- $A$ and/or $B$ are nonsymmetric.
\end{itemize}
\item
{\tt int pivotingflag} : flag to specify pivoting for stability,
\begin{itemize}
\item
{\tt SPOOLES\_NO\_PIVOTING} --- pivoting not used
\item
{\tt SPOOLES\_PIVOTING} --- pivoting used
\end{itemize}
\item
{\tt int sparsityflag} : flag to specify storage of factors.
\begin{itemize}
\item
{\tt 0} --- each front is dense
\item
{\tt 1} --- a front may be sparse due to entries dropped
because they are below a drop tolerance.
\end{itemize}
\item
{\tt int dataMode} : flag to specify data storage.
\begin{itemize}
\item
{\tt 1} --- one-dimensional, used during the factorization.
\item
{\tt 2} --- two-dimensional, used during the solves.
\end{itemize}
\item
{\tt int nentD} : number of entries in $D$
\item
{\tt int nentL} : number of entries in $L$
\item
{\tt int nentU} : number of entries in $U$
\item
{\tt Tree *tree} : Tree object that holds the tree of fronts.
Note, normally this is {\tt frontETree->tree}, but we leave this
here for later enhancements where we change the tree after the
factorization, e.g., merge/drop fronts.
\item
{\tt ETree *frontETree} : elimination tree object that holds the
front tree.
\item
{\tt IVL *symbfacIVL} : {\tt IVL} object that holds the
symbolic factorization.
\item
{\tt IV *frontsizesIV} : {\tt IV} object that holds the
vector of front sizes, i.e., the number of internal rows
and columns in a front.
\item
{\tt IVL *rowadjIVL} : {\tt IVL} object that holds the
row list for the fronts, used only for a nonsymmetric factorization
with pivoting enabled.
\item
{\tt IVL *coladjIVL} : {\tt IVL} object that holds the
column list for the fronts, used only for a symmetric or
nonsymmetric factorization with pivoting enabled.
\item
{\tt IVL *lowerblockIVL} : {\tt IVL} object that holds the
front-to-front coupling in $L$, used only for a
nonsymmetric factorization.
\item
{\tt IVL *upperblockIVL} : {\tt IVL} object that holds the
front-to-front coupling in $U$.
\item
{\tt SubMtx **p\_mtxDJJ} : a vector of pointers to diagonal submatrices.
\item
{\tt SubMtx **p\_mtxUJJ} : a vector of pointers to  submatrices in U
that are on the block diagonal, used only during the factorization.
\item
{\tt SubMtx **p\_mtxUJN} : a vector of pointers to  submatrices in U
that are off the block diagonal, used only during the factorization.
\item
{\tt SubMtx **p\_mtxLJJ} : a vector of pointers to  submatrices in L
that are on the block diagonal, used only during a nonsymmetric
factorization.
\item
{\tt SubMtx **p\_mtxLNJ} : a vector of pointers to  submatrices in L
that are off the block diagonal, used only during a nonsymmetric
factorization.
\item
{\tt I2Ohash *lowerhash} : pointer to a {\tt I2Ohash} hash table
for submatrices in $L$, used during the solves.
\item
{\tt I2Ohash *upperhash} : pointer to a {\tt I2Ohash} hash table
for submatrices in $U$, used during the solves.
\item
{\tt SubMtxManager *manager} : pointer to an object that manages
the instances of submatrices during the factors and solves.
\item
{\tt Lock *lock} : pointer to a {\tt Lock} lock used
in a multithreaded environment to ensure exlusive access while
allocating storage in the {\tt IV} and {\tt IVL} objects.
This is not used in a serial or MPI environment.
\item
{\tt int nlocks} : number of times the lock has been locked.
\item
{\tt PatchAndGo *info} : this is a pointer to an object that is
used by the {\tt Chv} object during the factorization of a front.
\end{itemize}
\par
One can query the properties of the front matrix object
using these simple macros.
\begin{itemize}
\item
{\tt FRONTMTX\_IS\_REAL(frontmtx)} is {\tt 1} if {\tt frontmtx}
has real entries and {\tt 0} otherwise.
\item
{\tt FRONTMTX\_IS\_COMPLEX(frontmtx)} is {\tt 1} if {\tt frontmtx}
has complex entries and {\tt 0} otherwise.
\item
{\tt FRONTMTX\_IS\_SYMMETRIC(frontmtx)} is {\tt 1} if {\tt frontmtx}
comes from a symmetric matrix or linear combination of symmetric
matrices, and {\tt 0} otherwise.
\item
{\tt FRONTMTX\_IS\_HERMITIAN(frontmtx)} is {\tt 1} if {\tt frontmtx}
comes from a Hermitian matrix or linear combination of Hermitian
matrices, and {\tt 0} otherwise.
\item
{\tt FRONTMTX\_IS\_NONSYMMETRIC(frontmtx)} is {\tt 1} if {\tt frontmtx}
comes from a nonsymmetric matrix or linear combination of nonsymmetric
matrices, and {\tt 0} otherwise.
\item
{\tt FRONTMTX\_IS\_DENSE\_FRONTS(frontmtx)} is {\tt 1}
if {\tt frontmtx}
comes from a direct factorization and so stores dense submatrices,
and {\tt 0} otherwise.
\item
{\tt FRONTMTX\_IS\_SPARSE\_FRONTS(frontmtx)} is {\tt 1}
if {\tt frontmtx} comes from an approximate factorization
and so stores sparse submatrices, and {\tt 0} otherwise.
\item
{\tt FRONTMTX\_IS\_PIVOTING(frontmtx)} is {\tt 1}
if pivoting was used during the factorization,
and {\tt 0} otherwise.
\item
{\tt FRONTMTX\_IS\_1D\_MODE(frontmtx)} is {\tt 1}
if the factor are still stored as a one-dimensional data
decomposition (i.e., the matrix has not yet been post-processed),
and {\tt 0} otherwise.
\item
{\tt FRONTMTX\_IS\_2D\_MODE(frontmtx)} is {\tt 1}
if the factor are stored as a two-dimensional data
decomposition (i.e., the matrix has been post-processed),
and {\tt 0} otherwise.
\end{itemize}


\subsubsection{YY Leg Data}
\label{ss:yylegdata}

Listing \ref{lst:yylegdata} shows an example for a leg of type YY. The YYLegData block contains the following
elements:

\begin{itemize}
\item Index: The underlying zero inflation index.

Allowable values:  Any string (provided it is the ID of an inflation index in the market configuration).
\item FixingDays: The number of fixing days.

Allowable values: An integer followed by \emph{D},
\item ObservationLag: The observation lag to be applied.

Allowable values: An integer followed by \emph{D}, \emph{W}, \emph{M} or \emph{Y}. Interpolation lags are typically expressed in \emph{M}, months.
%\item Interpolated: A flag indicating whether interpolation should be applied to inflation fixings.

%Allowable values:  \emph{true, false}

\item Spreads [Optional]: The spreads applied to index fixings. As usual, this can be a single value, a vector of values or a dated vector of
  values.

\item Gearings [Optional]: This node contains child elements of type \lstinline!Gearing! indicating that the coupon rate is
  multiplied by the given factors. The mode of specification is analogous to spreads, see above.

\item Caps [Optional]: This node contains child elements of type \lstinline!Cap! indicating that the coupon rate is capped at the
  given rate (after applying gearing and spread, if any).

\item Floors [Optional]: This node contains child elements of type \lstinline!Floor! indicating that the coupon rate is floored at
  the given rate (after applying gearing and spread, if any).

\item NakedOption [Optional]: Optional node (defaults to N), if Y the leg represents only the embedded floor, cap or collar. By convention these embedded options are considered long if the leg is a receiver leg, otherwise short.

\item AddInflationNotional [Optional]: If true, the payoff will include the notional of the coupon $N \, \tau \, \frac{I_t}{I_{t-1Y}}$.

\item IrregularYoY [Optional]: If true, instead of using a YoY inflation rate the coupon is based on the inflation rate during the actual coupon period, e.g.  for a 6M coupon the inflation rate will be computed as $\frac{I_t}{I_{t-6m}}-1$.
\end{itemize}

\begin{listing}[H]
%\hrule\medskip
\begin{minted}[fontsize=\footnotesize]{xml}
      <LegData>
        <LegType>YY</LegType>
        <Payer>false</Payer>
        <Currency>EUR</Currency>
        <Notionals>
          <Notional>10000000</Notional>
        </Notionals>
        <DayCounter>ACT/ACT</DayCounter>
        <PaymentConvention>Following</PaymentConvention>
        <ScheduleData>
          <Rules>
            <StartDate>2016-07-18</StartDate>
            <EndDate>2021-07-18</EndDate>
            <Tenor>1Y</Tenor>
            <Calendar>UK</Calendar>
            <Convention>ModifiedFollowing</Convention>
            <TermConvention>ModifiedFollowing</TermConvention>
            <Rule>Forward</Rule>
            <EndOfMonth/>
            <FirstDate/>
            <LastDate/>
          </Rules>
        </ScheduleData>
        <YYLegData>
          <Index>EUHICPXT</Index>
          <FixingDays>2</FixingDays>
          <ObservationLag>2M</ObservationLag>
          <Interpolated>true</Interpolated>
          <Spreads>
            <Spread>0.0010</Spread>
          </Spreads>
          <Gearings>
            <Gearing>2.0</Gearing>
          </Gearings>
          <Caps>
            <Cap>0.05</Cap>
          </Caps>
          <Floors>
            <Floor>0.01</Floor>
          </Floors>
          <NakedOption>N</NakedOption>
          <AddInflationNotional>false</AddInflationNotional>
					<IrregularYoY>false</IrregularYoY>
        </YYLegData>
      </LegData>
\end{minted}
\caption{YY leg data}
\label{lst:yylegdata}
\end{listing}


\documentclass[12pt]{article}

\addtolength{\textwidth}{1.0in}
\addtolength{\oddsidemargin}{-0.5in}
\addtolength{\evensidemargin}{-0.5in}
\addtolength{\textheight}{1.0in}
\addtolength{\topmargin}{-0.5in}

\usepackage [english]{babel}
\usepackage [autostyle, english = american]{csquotes}
\MakeOuterQuote{"}

\title{\texttt{seq\_gen.py}: a Synthetic Sequence Generator for the MCAT Pipeline}

\author{Jake Martinez}

\begin{document}

\maketitle

\section{Introduction}
Determining the effectiveness of a motif-finding pipeline is not easy when the "correct" result is unknown. For this purpose, we have developed a sequence generation program that creates synthetic biological sequences from a set of input parameters. These input parameters can be tweaked to simulate a genome that is statistically similar to a target genome. Alternatively, the software can be used to modify certain characteristics of the embedded motif to find specific shortfalls of the motif-finding pipeline, regardless of genome context.

\section{Methods}
The sequence generator a large number of possible input parameters to enable a high degree of customization for the generated genetic information. After processing some of the input parameters, an initial set of sequence data $S$ is generated. The specified number of motifs are then generated and embedded within randomized sequences within $S$. During the embedding, a parameterized amount of error can be introduced into the motif to simulate single-nucleotide polymorphisms. Additionally during the embedding process, meta data describing the motif location, sequence, and error are collected to then be used in the generation of each sequence name in the modified set of sequence data $S'$.

\subsection{Initial Sequence Generation}
Prior to generation of the initial sequence, a model for describing base pair probabilities is created. This model may be created in one of four ways (listed in order of priority):

\begin{enumerate}
	\item Template Sequence File: Uses a specified sequence file to generate a Markov model
	\item Markov Probability File: Loads a Markov model from a file \footnote{format described in Appendix B}
	\item Background Probability File: Loads a background probability model from a file\footnote{format described in Appendix B}
	\item Default Background Probability Model: Uses the background model $P(X)=.25$ where $X\in\{A,T,C,G\}$
\end{enumerate}

Once the statistical model is established, the sequence generator then uses input parameters for the number of sequences to generate as well as the length for each sequence. Currently, there is no variation in sequence length between sequences but could potentially be added in the future. The generator then creates sequences, embedding motifs after each sequence is generated.

\subsection{Motif Sequence Generation and Embedding}
In order to allow a high degree of customization, input parameters for motif width, minimum and maximum starting location, as well as the probability that a motif exists in each sequence have been included in the sequence generation tool. Additionally, the number of distinct motifs present within any of the given sequences can also be specified by the user. This tool currently uses the same statistical model used to create sequences to create motifs. One key difference between motif and background sequence generation is the potential for SNPs (or other errors) within the motif. The maximum number of allowed errors in a motif can be specified as a parameter as well as the probability that an error will exist in a given motif.

\subsubsection{Probability of Error Existing in a Motif}
During the embedding process of a motif, the motif can be altered slightly to simulate SNPs or other sources of error. To determine whether an error exists, a random value $r$ between 0 and 1 is generated; if that value is less than the probability that an error exists, then an error is introduced into the sequence. To introduce the error, a random index within the motif is selected and then the base pair is replaced with another. For motifs that allow multiple errors, the index of each error is stored as to not add an error in the same location as a previously generated error.

\section{Discussion}
There are many possible uses for this tool in the analysis of a motif-finding pipeline. A series of experiments could be created to analyze the effectiveness of the pipeline with respect to each of the input parameters. For example, a set of ten sequence files could be created, each with differing values for the probability that a motif is present in the sequence (and constant values for all other parameters). This would allow the experimenter to establish certain thresholds of accuracy for each parameter to discover the potential limitations of the pipeline. Furthermore, this method of experimentation and establishing thresholds could be used as an alternative metric for measuring the robustness of the pipeline. \\
\indent In addition to the features already implemented in the pipeline, potential improvements could include the option to have multiple of the same motif within each sequence as well as variable sequence length.

\section{Appendicies}
\subsection*{Appendix A: Input Parameters Reference}
\begin{itemize}
	\item \texttt{-w}: motif width; expects an integer value (default=8)
	\item \texttt{-N}: number of sequences; expects an integer value (default=20)
	\item \texttt{-n}: sequence length; expects an integer value (default=100)
	\item \texttt{-P}: probability the motif is present in the sequence; expects a decimal value less than or equal to 1 (default=8)
	\item \texttt{-e}: maximum number of SNPs allowed in a motif; expects an integer value (default=0)
	\item \texttt{--eprob}: probability of a SNP existing in the motif; expects a decimal value less than or equal to 1 (default=0.65)
	\item \texttt{--maxloc}: max starting location for motifs; expects an integer value, -1 denotes the end of the sequence (default=-1)
	\item \texttt{--minloc}: min starting location for motifs; expects an integer value (default=0)
	\item \texttt{--nmotifs}: max number of distinct motifs in a single sequence; expects an integer value (default=1)
	\item \texttt{--nsites}: max number of appearance of the motif in a single sequence; expects an integer value (default=1) [NOT IMPLEMENTED]

	\item \texttt{--dyad}: sets the generator to spaced dyad mode, overrides nmotifs (nmotifs=2); motif width option now represents total combined width of dyad
	\item \texttt{--negative}: sets the generator to negative sequence mode, overrides nmotifs (nmotifs=0)

	\item \texttt{--template}: specifies the template sequence file path; expects a string
	\item \texttt{--markov}: specifies the Markov probability file path; expects a string
	\item \texttt{--bgprob}: specifies the background probability file path; expects a string

	\item \texttt{-o}: output filename; expects a string value
	\item \texttt{--dir}: output directory; expects a string value (default=''; i.e. current directory)
\end{itemize}

\subsection*{Appendix B: Markov \& Background Probability File Formats}

\subsubsection*{Markov File Format}
\begin{verbatim}
P(A|A) = .25
P(T|A) = .25
P(C|A) = .25
P(G|A) = .25

P(A|T) = .25
P(T|T) = .25
P(C|T) = .25
P(G|T) = .25

P(A|C) = .25
P(T|C) = .25
P(C|C) = .25
P(G|C) = .25

P(A|G) = .25
P(T|G) = .25
P(C|G) = .25
P(G|G) = .25
\end{verbatim}

\textit{Note: each grouping should add up to 1, otherwise the model will be invalid and not be loaded.}

\subsubsection*{Background Probability File Format}
\begin{verbatim}
A = .25
T = .25
C = .25
G = .25
\end{verbatim}

\textit{Note: all values should add up to 1, otherwise the background model will be invalid and not be loaded.}

\subsection*{Appendix C: Example Uses of the Sequence Generator}

\begin{itemize}
	\item \texttt{python \textit{path}/seq\_gen.py} : runs the program with all default values
	\item \texttt{python \textit{path}/seq\_gen.py -w 12 -N 20 -n 250} : generates 20 sequences, each 250 base pairs long, with a motif width of 12
	\item \texttt{python \textit{path}/seq\_gen.py -e 2 --eprob .23 -P .85} : generates the default number of sequences at the default length; each sequence only has a 85\% chance of containing a motif, and each motif has a maximum of of 2 possible SNPs which have a 23\% chance of being generated
	\item \texttt{python \textit{path}/seq\_gen.py -o seq01.fasta --dir sequences} : runs the program with all default values except changes the output directory to the "sequences" directory and changes the output filename to "seq01.fasta" (i.e. \textit{path}/sequences/seq01.fasta)
\end{itemize}

\end{document}