\documentclass[12pt]{article}

\usepackage[noend]{algpseudocode}
\usepackage{algorithm}
\usepackage{algorithmicx}
\usepackage{float}
\usepackage{graphicx}
\usepackage[margin=1in]{geometry}
\usepackage{amsmath,amsthm,amssymb}
\usepackage{dsfont}
\usepackage{subcaption}
\usepackage{amsthm}
\usepackage{mathtools,amssymb}
\allowdisplaybreaks

\newtheorem*{definition}{Definition}
\newtheorem*{question}{Question}
\newtheorem{theorem}{Theorem}
\newtheorem{proposition}[theorem]{Proposition}
\newtheorem{claim}[theorem]{Claim}
\newtheorem{lemma}[theorem]{Lemma}
\newtheorem{corollary}[theorem]{Corollary}
\newtheorem{conjecture}[theorem]{Conjecture}

\newcommand{\N}{\mathbb{N}}
\newcommand{\Z}{\mathbb{Z}}
\newcommand{\R}{\mathbb{R}}
\newcommand{\Rgz}{\mathbb{R}_{\ge 0}}

\newcommand{\ip}[2]{\left\langle{#1},{#2}\right\rangle}

\newcommand{\woloss}{without loss of generality }

\DeclareMathOperator*{\argmin}{arg\,min}
\DeclareMathOperator*{\argmax}{arg\,max}
\DeclareMathOperator*{\cone}{cone}
\DeclareMathOperator*{\hull}{hull}

\newcommand{\1}[1]{\mathds{1}[{#1}]}
\renewcommand{\P}[1]{\mathds{P}\left[{#1}\right]}
\newcommand{\E}[1]{\mathds{E}\left[{#1}\right]}
\newcommand{\Var}[1]{\mathrm{Var}[{#1}]}

\newcommand{\unit}{\mathds{1}}

% \renewcommand{\thesubsection}{\thesection.\alph{subsection}}
% \renewcommand\thesubsection{\ \ (\alph{subsection})}

\begin{document}

% \renewcommand{\qedsymbol}{\filledbox}

\title{Preferences Resulting From Weighted Sums}
\author{
  Clay Thomas \\
  claytont@princeton.edu
\and
  Yufei Zheng\\
  yufei@cs.princeton.edu
}

\maketitle

\section{Motivation}
  Suppose students are told to rank different schools they would like to
  get into. The preferences of the students are likely correlated in some
  way due to an inherent notion of the quality of different schools.
  One way to define such a correlation is to assume there is some underlying
  space of quality along different attributes (e.g. STEM education vs
  liberal arts education) and the students' preference
  are determined by these attributes.
  The simplest instance of this is for each student to rank schools
  according to a weighted sum of the different attributes of the school.

  We want to study the inherent complexity of the collection of preferences
  that result from these procedure, as a function of the number of attributes
  the schools have. In other words, what sort of correlation arises in the
  preferences of students in this model?

  % as a weight vector $a = (a[1], \ldots, a[d])$, with each $a[k]\ge 0$.
  % Then every school $x$ is a vector $x = (x[1], \ldots, x[d])$ (with $x[k]\ge 0$)
  % of quality along the $d$ different attributes.
  % Student $a$ prefers

\section{Definitions}

  Let $\{x_1,\ldots,x_n\} = X\subseteq \Rgz^d$ be any (ordered) set of
  $n$ distinct points with nonnegative coordinates.
  Given any $a\in \Rgz^d$, define a order $>_a$ on $X$ as follows:
  $x_i >_a x_j$ if and only if $\ip{a}{x_i} > \ip{a}{x_j}$.
  Let $R(X)$ denote the set of linear orders on $X$.
  Define
  \begin{align*}
    P(X) = \{ \prec \in R(X) | \exists a\in\Rgz^d: x \prec y \iff x <_a y\}
  \end{align*}

  \begin{question}
    As a function of $d$ and $n$, how ``rich'' can $P(X)$ be
    (and what is the right notion of ``richness'')?
  \end{question}

  Some observations:
  \begin{itemize}
    \item If $d=1$, then $|P(X)| = 1$, i.e. students preferences are completely
      determined by the underlying set $X$.
    \item If $d=n$, then every linear preference on $X$ can occur in $P(X)$.
      \begin{proof}
        Let $X = \{e_i\}$ simply be the standard basis vectors.
        To induce an ordering $i_1, i_2, \ldots, i_n$, just create a preference
        vector $a$ which gives weight $1/k$ to coordinate $i_k$.
      \end{proof}
  \end{itemize}
  The above hints that there should be some sort of continuum between $d=1$
  and $d=n$ of how complex the set $P(X)$ can be.

\section{Lemmas}

  Here are some simple ways that the structure of $X$ induces structure on $P(X)$:

  \begin{definition}
    Let $x,y\in X\subseteq \Rgz^d$.
    We say $x$ \emph{dominates} $y$, denoted $x\gg y$,
    if $x[k] > y[k]$ for each $k=1,\ldots,d$.
  \end{definition}
  \begin{proposition}
    If $x \gg y$, then $x >_a y$ for any nonzero $a\in \Rgz^d$.
  \end{proposition}
  \begin{proof}
    Simply observe $a_i x_i \ge a_i y_i$ for each $i=1,\ldots, d$.
    Because $a\ne 0$, there is also some $i$ where $a_i x_i > a_i y_i$.
  \end{proof}

  \begin{definition}
    For points $x_1,\ldots,x_n \in \R^d$, let $\hull(x_1,\ldots,x_n)
    = \{u_1x_1 + \ldots + u_nx_n | 0\le u_i\le 1, \sum_{i=1}^n u_i = 1\}$
    denote the convex hull of $x_1,\ldots,x_n$.
  \end{definition}
  \begin{lemma}
    Let $z,x_1,\ldots,x_k \in \Rgz^d$ and $a\in \Rgz^d \setminus \{0\}$.
    If $z >_a x_i$ for $i=1,\ldots,k$, then $z >_a w$
    for any $w\in \hull(x_1,\ldots,x_k)$.
  \end{lemma}
  \begin{proof}
    We have $\ip{a}{z} > \ip{a}{x_i}$ for each $i=1,\ldots,k$.
    If $w = u_1x_1+ \ldots + u_nx_n$ and $\sum_i u_i =1$, then
    $\ip{a}{w} = u_1\ip{a}{x_1}+\ldots+u_n\ip{a}{x_n}
    < u_1\ip{a}{z} + \ldots + u_n\ip{a}{z} = \ip{a}{z}$
  \end{proof}
  \begin{proposition}
    Let $z,x_1,\ldots,x_k \in \Rgz^d$.
    Suppose that there exists $w\in \hull(x_1,\ldots,x_k)$
    such that $w \gg z$.
    Then no $a$ satisfies $z >_a x_i$ for each $i=1,\ldots, k$.
  \end{proposition}
  \begin{proof}
    For contradiction, suppose such an $a$ exists.
    Then $z >_a w$ as well. However, because $w \gg z$,
    this is a contradiction.
  \end{proof}

  Let's look at how preferences are related when different weight vectors $a$
  are related.
  \begin{definition}
    For any vectors $a_1,\ldots, a_k \in \Rgz^d$, define
    $\cone(a_1,\ldots,a_k) = \{ u_1a_1 + \ldots + u_ka_k | u_i\ge 0 \forall j\}$.
    That is, the convex cone of vectors defined by $a_1,\ldots,a_k$.
  \end{definition}
  \begin{proposition}
    Suppose that for preference weights $a_1,\ldots, a_k$,
    we have $x >_{a_1} y, \ldots, x >_{a_k} y$.
    Then for any nonzero $b\in \cone(a_1,\ldots, a_k)$,
    $x >_b y$ as well.
  \end{proposition}
  \begin{proof}
    Let $b = u_1a_1+ \ldots + u_ka_k$.
    We get $\ip{b}{x} = u_1\ip{a_1}{x} + \ldots + u_k\ip{a_k}{x}
    > u_1\ip{a_1}{y} + \ldots + u_k\ip{a_k}{y} = \ip{b}{y}$,
    as desired.
  \end{proof}

\section{Impossibility Results for $d=2$}

  \begin{proposition}
    If $d=2$, then the preferences
    \begin{align*}
      x >_a y >_a z \\
      y >_b z >_b x\\
      z >_c x >_c y\\
    \end{align*}
    cannot occur for $x,y,z\in X\subseteq \Rgz^2$.
  \end{proposition}
  \begin{proof}
    Suppose the above preferences exist.
    Because $d=2$, one of $a,b,c$ must be contained in the
    convex cone of the other two, i.e. $d \in \{a,b,c\}$
    with $d \in \cone(e,f)$ where $\{e,f\} = \{a,b,c\} \setminus \{d\}$.
    (This is visually very obvious: given three different
    vectors in two dimensions, one must lie between the other two.
    You can prove it by considering the angle of the vectors from the $x$ axis).
    Any pair of the above preferences has exactly one pair
    among $x,y,z$ which they rank the same, so
    $u >_e v$ and $u >_f v$ for some $u,v$.
    However, this pair is reversed in the remaining preference, i.e. $u <_d v$.
  \end{proof}

  More generally, we have the following:
  \begin{proposition}
    Let $d=2$ and $|X| = 3$. Then it is not possible
    for every point to be ranked highest by some preference,
    and ranked lowest by some other preference.
  \end{proposition}
  \begin{proof}
    Let $\{x,y,z\}$ be any set of distinct points in $\Rgz^2$.
    Because $d=2$, there must exist some $p\in \{x,y,z\}$
    such that $p \gg w$ or $p \ll w$ for some
    $w \in \hull(r,s)$, where $\{r,s\} = \{x,y,z\} \setminus \{p\}$
    (again, a proof by picture is best here, but it can be formally proven).
    But then, no $e$ satisfies $p >_e r$ and $p >_e s$,
    OR no $e$ satisfies $p <_e r$ and $p <_e s$.
  \end{proof}
  \begin{corollary}
    If $d=2$, then the preferences
    \begin{align*}
      x >_a y >_a z \\
      x >_b z >_b y \\
      y >_c z >_c x \\
      z >_d y >_d x \\
    \end{align*}
    cannot occur for $x,y,z\in X\subseteq \Rgz^2$.
  \end{corollary}

  It turns out that the above two patterns are,
  up to relabeling, the \emph{only} impossible subsets
  of preferences with $|X|=3$.
  We believe these patterns extend to higher dimensions,
  but the proofs above do not generalize because of the geometry involved.

  %\section{Cycles}

  % The above set of preferences intuitively forms a ``cycle'',
  % where each preference is ``shifted'' over by one. Formally,
  % \begin{definition}
  %   A $k$-cycle is a set of points $x_1,\ldots, x_k\in \Rgz^d$ and weights
  %   $a_1,\ldots, a_k \in \Rgz^d$ such that for each $i=1,\ldots,k$,
  %   \begin{align*}
  %     x_i >_{a_i} x_{i+1} >_{a_i} x_{i+2} >_{a_i} \ldots >_{a_i} x_{i-1}
  %   \end{align*}
  %   (where indices wrap around after $k$).
  % \end{definition}

  % \begin{conjecture}
  %   If $X \subseteq \Rgz^d$, then a $(d+1)$-cycle can never appear in $P(X)$.
  % \end{conjecture}

  % The second part of the proof from $d=2$ generalizes:
  % in a $d+1$ cycle, any subset of $d$ preferences has a consistent preference
  % on some pair, and this preference is broken in the remaining
  % element of the cycle.
  % However, the first part is not true: it is easy to construct $4$ vectors in
  % $3$ dimensions such that none lies in the convex cone of the others.

  % This conjecture has been checked by randomly placing $d+1$ points
  % in $d$ dimensional space many times, for $d=3,4$.

  % It may be that in some sense, $(d+1)$-cycles are the \emph{only}
  % set of preferences that are impossible with $d$ dimensions.
  % For example, there are two different (up to relabeling) ways for
  % a collection of preferences on three items to not contain a cycle.
  % Writing a linear preference as a simple ordered (most preferable
  % to least), the preference sets are $\{ 123, 132, 312, 321\}$ and
  % $\{ 123, 231, 213, 321 \}$. Both are realizable with $d=2$
  % (the first via points $\{(1,0), (0.4,0.4), (0,1) \}$
  % and the second with $\{(1,0), (0.6,0.6), (0,1)\}$).

  % When $d=3$, randomly searching over $X$ for the largest $|P(X)|$
  % yield a maximum size of $18$, and those sets exactly correspond
  % to removing one element from each of the $6$ cycles on $4$ points.
  % A variety of different ways of doing this are possible,  but I'm
  % not yet sure if all of them result.

\section{Experimental Counts}
  The following gives upper bounds on the maximal number
  of preferences $|P(X)|$ as a function of $n$ and $d$.
  I've only included entries if those points seem relatively
  close to the true maximum (i.e. when things seem pretty stable
  to checking more preference vectors or doing more trials).

  \begin{tabular}{c | c c c c c c c}
    n & d=2 & d=3 & d=4 \\
    \hline
    3  &  4   & 6  & 6  \\
    4  &  7   & 18 & 24 \\
    5  &  10  & 41 & 85 \\
    6  &  15  & 87  \\
    7  &  20  & 121 \\
    8  &  24  \\
    9  &  28  \\
    10 &  39  \\
    11 &  43  \\
    12 &  48  \\
  \end{tabular}

\end{document}


In this section will be described the main algorithms of the system, which are the search of a shop in the area and the next reservations query.
\subsection{Distance Calculation}
Since the GPS system is heavy on battery consumption, it's not always reliable (especially when just turned on) and the user may want to search in a different location than where he/she is right now, when the customer wants to start a search a dialog shown in \autoref{fig:addressSearch} asking for the address is shown, then the only needed values of \textbf{latitude} and the \textbf{longitude} are extracted.\\
Given the maximum \textbf{distance} the user wants the search to be done, the deltas for both the latitude and the longitude can be computed as follows:\\
\begin{center}
$ deltaLat = (distance/earthRadius) * (180 * Math.PI) $\\\vspace{0.5cm}
$ deltaLng = Math.toDegrees((dist / (earthRadius * Math.cos(Math.toRadians(currentLat))))) $
\end{center}
\subsection{Queries}
Firestore allows for some query functionalities, these can be used to retrieve data even when the the UID is not sufficient to identify the requested information.
\subsubsection{Shop Search Query}
Due to a limitation of Firestore, queries are made by searching for shops with the given tag, the latitude inside the min and max values (found respectively by subtracting and adding to the current latitude the value of deltaLat) and then a third parameter called \textit{intLongitude} is used, corresponding to the longitude truncated.\\
This has to be done since Firestore doesn't allow for queries with different search parameters except for equals, so instead of doing two queries (one for latitude and one for longitude) and then merging the common values, one query is done limiting the search to only one longitude and then the values retrieved are checked locally if they are inside the range. In the edge cases where the search spans over more than one longitude integer value, then more than one query will be made with the different values set, each query will return a different set than the others obviously so it must only be checked if the shops are in the correct range and no control between queries result has to be done.\\
Here is the example of the first (and usually only) query:\\
\begin{center}
\textit{shopsCollection\\
.whereArrayContains("tags", searchedText)\\
.whereGreaterThanOrEqualTo("latitude", minLat)\\
.whereLessThanOrEqualTo("latitude", maxLat)\\
.whereEqualTo("intLongitude", minIntLng)\\
.get();}
\end{center}
\clearpage
\subsubsection{Reservations Query}
The next/past reservations are queried once when the application is opened and after that a listener is placed on the current user entry in the \textbf{reservationsUpdate} collection, when a change occurs the trigger will result in a new query of both future and past reservations, the ViewModel will then handle the update of the Live Data lists and the views will automatically update once the observed value changes and the trigger is fired.\\
Here for example is show the query that will find the next reservations for a customer:
\begin{center}
\textit{reservationsCollection\\
.whereEqualTo("customerUid", thisUid)\\
.whereGreaterThan("time", now.getTime())\\
.orderBy("time", Query.Direction.ASCENDING)\\
.get();}
\end{center}
And one for the past reservations of a shop:
\begin{center}
\textit{reservationsCollection\\
.whereEqualTo("shopUid", thisUid)\\
.whereLessThan("time", now.getTime())\\
.orderBy("time", Query.Direction.DESCENDING)\\
.get();}
\end{center}
The duplicated elements in the \textit{reservation} stored object allow for one single query and therefore (given the asynchronous nature of Firebase requests) there is no need to locally order the results, unlike when a get request for each shop/customer that has to be displayed in the reservation card has to be done in the case of non-duplicated data. It should be remembered that duplicated data when needed is actually recommended by the Firebase team since the JSON database is much faster than a relational one when reads are in the majority of the actions performed (also the lack of classic relational functionalities like foreign keys make almost impossible to avoid duplicating data).


\chapter{Discussion}\label{ch:discussion}
In this chapter, we discuss our implementation of our ABC-MCMC approach and our results.

\section{Implementation}\label{sec:implementation}
All algorithms mentioned in this paper were implemented in Python 3.7.
To optimize the coalescent tree generation, repeat length determination, and likelihood determination processes, the
Numba package was used to compile and parallelize each function before running.
Simulations were run on the Cray CS300 supercomputer at the University of Hawaii at Manoa with
$\texttt{cpus-per-task} = 20$ and $\texttt{mem}=10,000\texttt{MB}$.
All code (and this paper) can be found at the following Git repository:
\begin{equation*}
    \text{\href{https://github.com/glennga/micro-coa}{https://github.com/glennga/micro-coa}}
\end{equation*}

In this implementation, the following details differ from the descriptions laid in the previous chapters:
\begin{enumerate}
    \item The BFS we perform in~\autoref{subsec:coalescentRepeatLengthResolution} is not guaranteed to explore nodes
        of the same depth in a deterministic manner, but still performs a BFS nonetheless.
        Numba parallelizes this process, which leads to this randomness.
    \item In order to use~\autoref{alg:twoStageBackwardEvolution}, a common ancestor repeat length $\ell^{(1)}$ must be
        specified.
        \emph{We assume $\ell^{(1)}$ to be a nuisance parameter.}
        Given the variance associated with this process, we feel it is safe to assume this parameter does not need to be
        as precisely defined as our other hyperparameters.
        We randomly select a repeat length from our observed data, and reduce the number of free parameters from
        four to three.
    \item In an effort to save space, two independent vectors $V$ and $E$ are not allocated for use at the same time
        in~\autoref{alg:twoStageBackwardEvolution}.
        Instead we define vector $V$ to hold the indices associated with each parent node to construct the edge set,
        and replace this with repeat lengths in the determination stage.
    \item The order with which the probabilities of some likelihood $\mathcal{\theta}$ are calculated are
        not guaranteed to be deterministic.
        Numba also parallelizes this process.
    \item In addition to recording the states required for Markov chain $X$ in~\autoref{alg:metropolis}, we also record
        the time between acceptances (known as the \emph{waiting time}), the likelihood of that point
        $\mathcal{L}(\theta^{(i)})$ (to avoid computing this later), the average distance associated with the generated
        data of the accepted parameter set and our observations, and the time of acceptance in terms of iterations.
\end{enumerate}

\section{Hyperparameters}\label{sec:hyperparameters}
\begin{table}
    \begin{tabu} to \textwidth {|c|c|X|}
       \toprule
        Symbol & Value / Type & Detail / Explanation \\
        \hline
        $\kappa$ & 3 & Lower bound of our repeat length space $\mathbb{M}$. \\
        $\Omega$ & 30 & Upper bound of our repeat length space $\mathbb{M}$. \\
        $n$ & $100$ & Sample size, number of end individuals to simulate. \\
        $\tau_N(e)$ & $\exp\left(\sfrac{N}{\binom{\rho(e)}{2}}\right)$ & Generation determination function\\
        $N$ & $10,000$ & Effective population size. \\
        $\delta(e)$ & $\delta_A(e)$ & The distance function between two populations. \\
        $\epsilon$ & 0.55 & ABC cutoff to define approximate. \\
        $T_1$ & 100 & Number of simulations to run to determine $\Pr(\mathcal{M}(\theta) \approx \mathcal{D}_i)$. \\
        $\theta^{(1)}_c$ & 0.01 & Starting $c$ value for initial state of Markov chain $\theta^{(1)}$. \\
        $\theta^{(1)}_d$ & 0.001 & Starting $d$ value for initial state of Markov chain $\theta^{(1)}$ . \\
        $g_c(c)$ & $N(c, \sigma_c)$ & Proposal function to generate new $c$ values. \\
        $g_d(d)$ & $N(d, \sigma_d)$ & Proposal function to generate new $d$ values. \\
        $\sigma_c$ & 0.001 & Deviation associated with proposal function $g_c(c)$. \\
        $\sigma_d$ & 0.001 & Deviation associated with proposal function $g_d(d)$. \\
        $T_2$ & $55,000$ & Running time of Metropolis sampler. \\
        $b_c$ & $0.001$ & Bin size for $c$ histogram. \\
        $b_d$ & $0.0001$ & Bin size for $d$ histogram. \\
        $w_c(c)$ & $\Gamma(\ldots)$ & The assumed posterior distribution for $c$. \\
        $w_d(d)$ & $\Gamma(\ldots)$ & The assumed posterior distribution for $d$. \\
       \bottomrule
    \end{tabu}
    \caption{Table of our hyperparameters: their symbol, the value we chose, and a description of parameter itself.
    }\label{tab:hyperparameters}
\end{table}

\begin{figure}[t]
    \centering{\input{include/floats/c-histogram.tex}}
    \caption{Frequency surface of $c$ parameter.
    Our histogram was constructed using a bin size of $b_c = 0.001$
    In blue the least-squares estimate of a $\Gamma$ distribution for this histogram is displayed,
    with $a=3.740, \mathit{loc}=0.0009042, \mathit{scale}=0.003572$.
    }\label{fig:cData}
\end{figure}
\begin{figure}[t]
    \centering{\input{include/floats/c-trace.tex}}
    \caption{Trace plot of $c$ for all three runs of the Metropolis sampler.
    }\label{fig:cTrace}
\end{figure}

\begin{figure}[t]
    \centering{\input{include/floats/d-histogram.tex}}
    \caption{Frequency surface of $d$ parameter.
    Our histogram was constructed using a bin size of $b_d = 0.0001$.
    In blue the least-squares estimate of a $\Gamma$ distribution for this histogram is displayed,
    with $a=4.000, \mathit{loc}=7.203-05, \mathit{scale}=0.0002524$.
    }\label{fig:dData}
\end{figure}
\begin{figure}[t]
    \centering{\input{include/floats/d-trace.tex}}
    \caption{Trace plot of $d$ for all three runs of the Metropolis sampler.
    }\label{fig:dTrace}
\end{figure}

Recall that we must specify hyperparameters in order to determine our parameters of interest: $c, d$.
Each is listed in~\autoref{tab:hyperparameters} with their symbol, the value we chose, and a brief description of
hyperparameter itself.
Below we give our reasoning for selecting each~\autoref{tab:hyperparameters} value:
\begin{enumerate}
    \item For all of the microsatellites we collected in~\autoref{ch:dataForParameterEstimation} from ALFRED, the
        lowest observed repeat length we found was $\ell=3$.
        We set $\kappa = 3$ for this reason.
    \item For all of the microsatellites we collected in~\autoref{ch:dataForParameterEstimation} from ALFRED, the
        highest observed repeat length we found was $\ell=30$.
        We set $\Omega = 30$ for this reason.
    \item The sample size $n$ heavily influences the computation time of our simulator.
        Per Metropolis sampler iteration, we generate $n \cdot T_1 \cdot | \mathcal{D} |$ lineages.
        We found that $n=100$ was on the lower end of sample sizes found in ALFRED observations, but this allowed us
        to simulate samples within a reasonable amount of time.
    \item We chose to follow Hudson's approach and drew our edge lengths from an exponential distribution with the mean
        $\sfrac{N}{\binom{\rho(e)}{2}}$.
        We defined $\tau_N$ as a function which accepts an edge as input, determines the expected time to coalescence
        based on the working node's depth from the common ancestor node, and outputs a draw from this exponential
        distribution with this expected time as the mean.
    \item We use a human effective population size of $N=10,000$ individuals, taken from
        Takahata~\cite{takahataAllelicGenealogyHuman1993}.
    \item The decision to use the angular distance $\delta_A$ as our $\delta$ function was made arbitrarily.
        Future work includes looking into other such distance functions.
    \item To determine $\epsilon$, our starting parameter values $\theta^{(1)}_c, \theta^{(1)}_d$, and our proposal
        deviations $\sigma_c, \sigma_d$, we started with some guess and refined these parameters as we went.
        $\epsilon$ itself depends on the other two parameters.
        We started at a high threshold $\epsilon \approx 0.9$, and decreased this number as we became more confident in
        our starting parameters over several instances of our Markov chains $\mathcal{X} = \{ X_1, X_2, \ldots \}$.
        We found $\epsilon=0.55$ to be a good compromise between accuracy and computation time.
    \item As mentioned in the point for sample size, $T_1$ is another major factor in computation time.
        If $T_1$ is too small, we end up with probabilities that are not representative of our posterior.
        If $T_1$ is too large, our computation time becomes too long.
        We found that $T_1 = 100$ was able to reasonably account for our simulator variance.
    \item The starting $c$ parameter $\theta^{(1)}_c$ was tuned by running our sampler to obtain various Markov chains
        $\mathcal{X}$ and selecting the average of the most likely $c$ values $\hat{c}$ for each chain.
        We rounded to the nearest $0.001$, and obtained $\theta^{(1)}_c = 0.010$.
    \item The starting $d$ parameter was found in a similar fashion to the starting $c$ parameter.
        We rounded to the nearest $0.0001$, and obtained $\theta^{(1)}_d = 0.001$.
    \item We chose to sample from a normal distribution $g_c(c) = N(c, \sigma_c)$ centered at a given $c$ for our
        proposal function $c$.
        This was the first symmetric distribution to come to mind, which is a requirement of the Metropolis sampler.
    \item We also chose to sample from a normal distribution for parameter $d$: $g_d(d) = N(d, \sigma_d)$.
    \item Associated with the proposal functions we defined in the previous two points are normal distribution
        deviations.
        A larger $\sigma_c$ means that our sampler will on average generate proposals at greater distances from our
        current point than a sampler with a smaller $\sigma_c$.
        These were found in the same manner as our $\epsilon$ term: running several instances of sampler to obtain
        $\mathcal{X}$ and decreasing $\sigma_c$ as we become more and more confident in our starting parameters.
        We found $\sigma_c = 0.0010$ after running this procedure.
    \item Running a similar procedure for the proposal normal distribution deviation associated with $d$, we found
        $\sigma_d = 0.0001$.
    \item Our Metropolis sampler is able to generate a Markov chain with $\Pr(\theta \mid \mathcal{D})$ as its
        equilibrium distribution \emph{given an infinite amount of time}.
        To make this problem tractable, we must choose some $T_2$ such that our target distribution converged
        at some Metropolis iteration before $T_2$.
        We have selected $T_2 = 55,000$ for this run.
    \item The histogram bin size is associated with the proposal function step size.
        A larger $\sigma_c, \sigma_d$ will result in wider distributions, leading to an increase in $b_c, b_d$ to
        ensure that our bin frequencies correctly resolve our posterior.
        This parameter was found after creating several different histograms with different $b_c$ until some density
        appeared.
        We found $b_c = 0.001$ to resolve our posterior well given our current $\sigma_c$.
    \item Using the same procedure for $b_c$, we found $b_d = 0.0001$ to resolve our posterior well given our
        current $\sigma_d$.
    \item While creating several histograms for $c$, we observed that our density was positively skewed.
        Visually, we found that fitting our histogram to a gamma distribution aligned better than fitting our histogram
        to a normal distribution.
    \item Again, while creating several histograms for $d$, we observed that our density was positively skewed.
        We went with a gamma distribution here as well.
\end{enumerate}

\section{Upward Constant Bias: $c$}\label{sec:upwardConstantBias}
In~\autoref{fig:cData}, we describe the frequency of the $c$ parameter.
The data for the histogram comes from three independent runs of the Metropolis sampler, all with identical
hyperparameters.
The distribution below represents the curve of this frequency, with a bin size of $b_c = 0.001$ to construct the
underlying histogram.
\begin{equation}
    w_c(c) = \Gamma(a = 3.740, \mathit{loc} = 0.0009042, \mathit{scale} = 0.003572)
\end{equation}
The most likely parameter $\hat{c}$ is given below:
\begin{equation}
    \hat{c} = 0.01426 \pm 4.773 \cdot 10^{-5}
\end{equation}

The trace plot for $c$, a plot of $c$ vs.\ Metropolis sampler iterations is shown in~\autoref{fig:cTrace}.
A visual approach to assessing Markov chain convergence is to look at how our Markov chain moves as a function of
time.
All three are shown to move in the same neighborhood, although the ideal plot here would be a set of straight, thick,
and tightly distributed lines.
This indicates that we need to run our MCMC longer to strengthen our confidence that we are sampling from the
correct distribution.

\section{Downward Linear Bias: $d$}\label{sec:downwardLinearBias}

In~\autoref{fig:dData}, we describe the frequency of the $d$ parameter.
The data for the histogram comes from three independent runs of the Metropolis sampler, all with identical
hyperparameters.
The distribution below represents the curve of this frequency, with a bin size of $b_d = 0.0001$ to construct the
underlying histogram.
\begin{equation}
    w_d(d) = \Gamma(a = 4.000, \mathit{loc} = 7.203-05, \mathit{scale} = 0.0002524)
\end{equation}
The most likely parameter $\hat{d}$ is given below:
\begin{equation}
    \hat{d} = 0.001082 \pm 2.549 \cdot 10^{-7}
\end{equation}
Using both $\hat{c}$ and $\hat{d}$, we get the following focal unit for the Columbian populace:
\begin{equation}
    \hat{\ell} \sim 13
\end{equation}

The trace plot for $d$ is shown in~\autoref{fig:dTrace}.
Same with $c$, all three are shown to move in the same neighborhood, but we would need to run our MCMC longer
to strengthen our confidence that our chain has converged.


\chapter{Multidimensional Nonuniform Gap Sampling}

\begin{quote}
{\it
  Anyone who considers arithmetical methods of producing random digits is,
  of course, in a state of sin.}
\\\\
 -- John von Neumann
\end{quote}

\section{Introduction}

\begin{doublespace}
The use of nonuniform sampling in multidimensional NMR is rapidly becoming
standard practice in most biomolecular solution-state experiments, thanks in
large part to recent developments in fast reconstruction algorithms, novel
sampling schemes, and the continually declining cost of computing power
\cite{mobli:pnmrs2014}. The potential benefits of collecting a subset of the
full Nyquist grid -- including increased sensitivity and signal-to-noise,
improved resolution, and reduced experiment time -- have received significant
attention \cite{
  rovnyak:jmr2004, rovnyak:jbnmr2004, kazimierczuk:angew2011,
  hyberts:jbnmr2013, palmer:jbnmr2014} in recent years as a consequence.
\\\\
One intriguing result of recent investigations into the parameters of NUS
experiments is the use of random deviates for generating sampling schedules
\cite{hoch:jmr2008}. In fully random sampling schemes, a subset of Nyquist
grid points is drawn from a probability density function that varies over the
grid, producing a sampling schedule with a desired distribution of points.
Common fully random sampling schemes utilize uniform, exponential, Gaussian
and envelope-matched probability densities
\cite{palmer:jbnmr2014,schuyler:jbnmr2011}. While randomization is a simple
means of reducing the artifacts due to aliasing of nonuniformly spaced samples,
it turns the already complex task of schedule generation into that of selecting
a schedule from an ensemble of possibilities, each of which performs
differently in practice \cite{hyberts:jacs2010,mobli:jmr2015}. Several ad hoc
metrics have been proposed to assess the relative performance sampling
schedules, but no universally accepted metric exists to guide the selection
of a stochastic schedule from its ensemble \cite{mobli:jmr2015,aoto:jmr2014}.
Without a priori knowledge of the frequency and decay rate distributions of
the signals to be measured, it is difficult to reliably quantify sampling
schedule performance \cite{mobli:pnmrs2014,schuyler:jbnmr2011}. As a result,
numerous recent attempts have been made to reduce or remove pseudorandom
seed-dependent variability from nonuniform sampling algorithms
\cite{kazimierczuk:jmr2007,hyberts:jacs2010,eddy:jmr2012,mobli:jmr2015}.
Such efforts are an important step towards increasing the practical utility
of nonuniform sampling in everyday spectroscopic experiments.
\\\\
One prominent method designed to reduce seed-dependent variability in
pseudorandomly constructed schedules in Poisson-gap sampling. Through an
empirical analysis of Forward Maximum Entropy (FM) reconstructions
of randomly sampled data, Hyberts et al. proposed the use of constrained
Poisson random deviates to define the \emph{gaps} between sampled points
in a Nyquist grid \cite{hyberts:jacs2010}. The FM reconstruction residuals
of these so-named Poisson-gap schedules exhibited a markedly lower dependence
on seed value than unconstrained random sampling methods. While Poisson-gap
sampling yields high-quality reconstructions of NUS spectral data, its average
behavior is not well-understood, its implementation for multidimensional
Nyquist grids is unclear
\cite{hyberts:tcc2012,hyberts:jbnmr2012,hyberts:jmr2014},
and its relationship -- if any -- to fully random sampling is unknown.
To meet this need, this work describes in detail the deterministic generation
of sinusoidally weighted multidimensional gap schedules that model the average
behavior of stochastic Poisson-gap (PG) sampling. An expectation sampling
probability distribution is also derived that reflects the average weighting
obtained using one-dimensional Poisson-gap sampling schedules.
\\\\
Among the myriad of different sampling schemes proposed for NUS data
collection \cite{maciejewski:tcc2012}, burst-mode sampling similarly concerns
itself with gaps between sampled grid points. Unlike Poisson-gap sampling,
which aims to minimize the \emph{length} of gaps, burst-mode sampling aims
to minimize the \emph{number} of gaps while keeping the effective dwell time
low \cite{maciejewski:jmr2009}. We leverage the complementarity of burst-mode
and Poisson-gap sampling in our deterministic gap sampling algorithm to
describe a novel sampling scheme that simultaneously seeks to bias sample
collection to early times, minimize the number of long gaps between densely
sampled regions, and minimize the largest gap length in the schedule. The
resulting method, called sine-burst (SB) sampling, exhibits the high
performance of Poisson-gap sampling while retaining the bijective mapping
between inputs and outputs offered by deterministic methods.
\end{doublespace}

\section{Theory}

\subsection{Poisson-gap Sequences}

\begin{doublespace}
Gap schedules on a one-dimensional Nyquist grid are effectively finite integer
sequences, computed from the following recurrence relation:
\begin{equation}
x_{i+1} = x_i + \lfloor g(x_i) \rfloor + 1
\end{equation}
where $x_i$ is the grid index of the $i$-th term in the sequence and $g(x_i)$
is the ``gap equation'' that defines the distance between terms. The first term
in the sequence, $x_1$, is set to 1 and subsequent terms are computed until
their value exceeds $N$, the size of the grid. The gap equation $g(x)$ may be
any non-negative function, and may be loosely interpreted as inversely related
to the local sampling density at the grid index $x_i$. Thus, when the gap
equation equals zero for all grid indices, gap sampling will yield a uniformly
sampled grid.
\\\\
Poisson-gap sequences treat the gap equation as a Poisson random deviate
having a rate parameter that varies as either a quarter- or half-sinusoid
over the grid indices:
\begin{equation}
g_{PG}(x_i) \sim \mathrm{Pois} \left\{
 \Lambda \sin \left(
  \frac{\pi}{2} \theta_i
 \right)
\right\}
\end{equation}
where $\Lambda$ is a scaling factor that determines the global sampling
density and $\theta_i$ is the fractional grid index that varies from 0 to 1
over the grid extents:
\begin{equation}
\theta_i = \frac{x_i}{N}
\end{equation}

In all following descriptions of Poisson-gap methods, we shall restrict our
attention to rate parameters which vary as quarter-sinusoids, where the
fractional grid index is multiplied by a factor of one-half $\pi$. This choice
of sinusoidal weight produces schedules that are heavily biased to earlier
grid points. Using a factor of $\pi$ produces half-sinusoidal rate parameters
and schedules that are more densely sampled at both early and late grid points.
\\\\
Because the expected value of a Poisson distribution is equal to its rate
parameter, one may trivially construct a deterministic sinusoidally weighted
gap sampler (sine-gap; SG) by setting the gap equation equal to the scaled
quarter-sinusoid from equation 2.2, as follows:
\begin{equation}
g_{SG} = \Lambda \sin \left( \frac{\pi}{2} \theta_i \right)
\end{equation}

By construction, gap sampling schedules computed according to $g_{SG}$ will
describe the average behavior of $g_{PG}$. This is readily verified in one
dimension by generating a sufficiently large set of stochastic Poisson-gap
schedules and comparing the mean value of each sequence term to that of a
sine-gap schedule (\figref{2.1}{Figure 2.1}). Sine-gap schedules
lie centrally within the Poisson-gap ensemble, while other schedules
unrelated to Poisson-gap deviate substantially from the confidence
region of the ensemble.
\end{doublespace}

\begin{figure}[ht!]
\includegraphics[width=6in]{figs/dgs/01-avepg.png}
\caption
      [Agreement between Poisson-gap and sine-gap Sequences.]{
  {\bf Agreement between Poisson-gap and sine-gap Sequences.}
  \\
  Relative errors between sine-gap (blue lines) and deterministic exponential
  (red lines) schedules with respect to the average Poisson-gap schedule at
  ({\bf A}) 30\% density, ({\bf B}) 10\% density and ({\bf C}) 5\% density.
  Confidence intervals indicating plus or minus one standard deviation of the
  Poisson-gap ensemble are shown as gray shaded regions. The vertical axes of
  all inset plots range from $-0.2$ to $0.2$. Because the sine-gap schedules
  describe the average behavior of the Poisson-gap equation, they lie
  centrally within the Poisson-gap ensemble, while any other schedule
  unrelated to Poisson-gap (e.g. exponential) does not.
}
\label{figure.2.1}
\end{figure}

\subsection{Multidimensional Gap Sampling}

\begin{doublespace}
Gap schedules on a Nyquist grid having at least two dimensions are generated
by placing multiple one-dimensional sub-schedules onto the grid, each with a
different direction and offset from the grid origin. In practice, this process
is accomplished recursively, with planes built up from vectors, cubes built up
from planes, and so forth. Initially, recursion begins on the entire grid. At
each level of recursion, sub-grids are constructed by ``masking off'' each
available grid direction in turn and constructing the remaining unmasked
directions. For example, a three-dimensional $xyz$ cube will be constructed
from repeated sequences of $yz$, $xz$ and $xy$ planes, and each $xy$ plane
will be constructed from repeated sequences of $y$ and $x$ vectors. Once a
round of sub-grid construction has been performed along each direction, the
sub-grid offset is incremented and the process is repeated until no more
sub-grids remain at the current level of recursion. The following executable
pseudocode provides a more precise definition of the recursive gap sampling
algorithm:
\end{doublespace}

\begin{algorithm}[H]
\caption{Multidimensional Gap Sampling Algorithm}
\label{algorithm.2.1}
\begin{python}
def build(N, origin, mask):
  D = len(N)
  if sum(mask) == 1:
    direction = mask.index(1)
    dirstring = ['x', 'y', 'z'][direction]
    print('sequence along ' + dirstring + ' at origin ' + origin)
    return

  suborigin = [0,] * D
  submask = [0,] * D
  done = False
  offset = 0

  while not done:
    done = True
    for direction in range(D):
      if mask[direction] != 1 or offset >= N[direction]:
        continue

      done = False
      for d in range(D):
        if d != direction and mask[d] == 1:
          submask[d] = 1
        else:
          submask[d] = 0

        if d == direction:
          suborigin[d] = offset
        else:
          suborigin[d] = origin[d]

      build(N, suborigin, submask)
    offset = offset + 1

build([8, 4, 4], [0, 0, 0], [1, 1, 1])
\end{python}
\end{algorithm}

\begin{doublespace}
Creation of multidimensional gap schedules requires a slight modification to
the fractional index, which now assumes the following form:
\begin{equation}
\theta_i = \frac{x_i + \sum_{d=1}^D O_d}{\sum_{d=1}^D N_d}
\end{equation}
where $O_d$ and $N_d$ are the origin and grid size along direction $d$,
respectively. The above equation is referred to as ``ADD'' mode in the context
of stochastic Poisson-gap sampling, and effectively results in multidimensional
schedules that exhibit triangular forms \cite{hyberts:jmr2014}. It is worthy of
mention that, in the one-dimensional case, equation 2.5 reduces to equation
2.3.
\\\\
Finally, whether the Nyquist grid is one- or many-dimensional, a value of the
global scaling factor $\Lambda$ must be determined that yields the desired
number of sampled grid points. Our gap sampling implementation, like the
existing Poisson-gap method, iteratively rebuilds new schedules until
$\Lambda$ has been suitably optimized. The published implementation uses a
heuristic search method that adjusts $\Lambda$ based on the relative difference
between the desired and obtained global sampling density at each iteration.
\end{doublespace}

\subsection{Burst Augmentation}

\begin{doublespace}
Recent statistical descriptions of the discrete Fourier transform have shown
that the bandwidth of a nonuniformly sampled signal is related to the greatest
common factor of the gaps between sampled grid points
\cite{bretthorst:cmr2008}. One proposed method of increasing bandwidth and
reducing artifacts in NUS data is to sample in multiple short bursts having
zero gap length \cite{maciejewski:jmr2009}. Using gap sampling, this may be
accomplished by modulating the gap equation between zero and its maximum value
several times over the Nyquist grid, like so:
\begin{equation}
g_{SB}(x_i; d) = \Lambda
 \sin \left( \frac{\pi}{2} \theta_i \right)
 \sin^2 \left( \frac{\pi}{4} N_d \theta_i \right)
\end{equation}

The sine-burst gap equation $g_{SB}$ combines the sinusoidal forward-biasing
and minimized gap lengths of Poisson-gap sampling with the minimized effective
dwell time of burst-mode sampling, and does not require the use of random
deviates to achieve reasonable artifact suppression.
\end{doublespace}

\begin{figure}[ht!]
\begin{center}
  \includegraphics[width=4.5in]{figs/dgs/02-expect-1d.png}
\end{center}
\caption
      [Poisson-gap 1D Expectation Sampling Distributions.]{
  {\bf Poisson-gap 1D Expectation Sampling Distributions.}
  \\
  Expectation sampling distributions computed by averaging 50,000
  one-dimensional Poisson-gap schedules of varying densities, with
  quarter-sinusoidal ({\bf A}) and half-sinusoidal ({\bf B}) weightings.
  The lighter blue, green and red points were computed from schedules having
  30\%, 10\% and 5\% sampling density, respectively. The dashed lines overlaid
  on each set of points correspond to the analytic sampling distribution
  (equation 2.11) derived from $g_{PG}$. Values of $\Lambda$ were 5.0, 25.4
  and 62.9 for 30\%, 10\% and 5\% sampling density, respectively.
}
\label{figure.2.2}
\end{figure}

\subsection{Expectation Sampling Distributions}

\begin{doublespace}
One disadvantage of stochastic gap equations is that they provide no direct
measure of how likely each Nyquist grid point is to be sampled. While one may
speculate on the approximate weighting obtained by a given gap equation,
quantitation of the expectation of the sampling distribution requires the
construction and averaging of a large number of sampling schedules
(cf. \figref{2.2}{Figures 2.2}, \figref{2.3}{2.3} and \figref{2.4}{2.4}).
Fortunately, the expectation sampling distribution of a given gap equation
may be analytically obtained by computing the probability of sampling each
point on the grid using a recursive formula. We define an expectation
sampling distribution $p(i)$ that varies over a one-dimensional Nyquist
grid of $N$ points as follows:
\begin{equation}
p(i) = \sum_{k=1}^{i-1} p(i \mid i-k) p(i-k)
\end{equation}
where $p(i \mid i-k)$ is the probability of grid point $i$ being emitted from
grid point $i-k$, which requires a gap size of $k-1$:
\begin{equation}
p(i \mid i-k) = \mathrm{Pr}\left\{
 \lfloor g(i-k) \rfloor = k - 1
\right\}
\end{equation}
\end{doublespace}

\begin{figure}[ht!]
\includegraphics[width=6in]{figs/dgs/03-expect-2d.png}
\caption
      [Poisson-gap 2D Expectation Sampling Distributions.]{
  {\bf Poisson-gap 2D Expectation Sampling Distributions.}
  \\
  Expectation sampling distributions of two-dimensional Poisson-gap schedules
  computed in strict accordance to Algorithm 2.1. Top panels were produced by
  averaging 50,000 two-dimensional schedules, and bottom panels were computed
  using equation 2.12 with appropriate substitutions of the Poisson
  probability mass function. Sampling densities of 30\%, 10\% and 5\% are
  shown in panels ({\bf A}, {\bf D}), ({\bf B}, {\bf E}) and
  ({\bf C}, {\bf F}), respectively.
}
\label{figure.2.3}
\end{figure}

\begin{doublespace}
In other words, the probability of sampling any given grid point is the
weighted sum of the probabilities of arriving at that point from all prior
points. In the case of Poisson-gap sampling, the gap equation is a Poisson
random deviate:
\begin{equation}
\mathrm{Pr}\left\{ \lfloor g(x_i) \rfloor = k - 1 \right\} =
 \frac{\lambda(x_i)^{k-1}}{(k-1)!} e^{-\lambda(x_i)}
\end{equation}
where the rate parameter $\lambda(x_i)$ varies sinusoidally over the Nyquist
grid:
\begin{equation}
\lambda(m) = \Lambda \sin \left( \frac{\pi m}{2 N} \right)
\end{equation}

By combining the above four equations, we arrive at the sampling distribution
of a one-dimensional Poisson-gap sequence:
\begin{equation}
p(i) = \sum_{k=1}^{i-1} \frac{\Lambda^{k-1}}{(k-1)!}
 \sin^{k-1} \left( \frac{\pi [i-k]}{2 N} \right)
 \exp\left\{
  -\Lambda \sin \left( \frac{\pi [i-k]}{2 N} \right)
 \right\}
p(i-k)
\end{equation}

As in the case of gap sampling, the sampling distribution produced by equation
2.11 is parameterized only by the scaling factor $\Lambda$, where larger values
yield more forward-biased schedules (\figref{2.2}{Figure 2.2}). We refer
to this equation as the ``expectation'' Poisson-gap sampling distribution
because it describes the expected value of the probability of sampling any
Nyquist grid point, and is not itself useful for generating schedules that
obey $g_{PG}$.
\end{doublespace}

\begin{figure}[ht!]
\includegraphics[width=6in]{figs/dgs/04-expect-hyb.png}
\caption
      [Poisson-gap 2D Expectation Sampling Distributions.]{
  {\bf Poisson-gap 2D Expectation Sampling Distributions.}
  \\
  Expectation sampling distributions computed by averaging 50,000
  two-dimensional Poisson-gap schedules generated using code provided by
  Hyberts and Wagner. Sampling densities of 30\%, 10\% and 5\% are
  shown in panels ({\bf A}), ({\bf B}) and ({\bf C}), respectively.
}
\label{figure.2.4}
\end{figure}

\subsection{Multidimensional Expectation Sampling Distributions}

\begin{doublespace}
Extension of equation 2.11 to compute the expectation sampling distributions
of stochastic gap equations in two or more dimensions follows from the fact
that sampling along each direction is essentially independent of other
directions within the presented gap sampling framework. As a consequence,
the probability of sampling any multidimensional grid point is therefore the
sum of sampling that point along each grid direction. For a two-dimensional
grid $(i_1,i_2)$, the expectation sampling distribution is the sum of the
probability matrices $p_1(i_1,i_2)$ and $p_2(i_1,i_2)$:
\begin{align}
p_1(i_1,i_2) =& \sum_{k=1}^{i_1-1} p(i_1,i_2 \mid i_1-k,i_2) p_1(i_1-k,i_2)
 \nonumber \\
p_2(i_1,i_2) =& \sum_{k=1}^{i_2-1} p(i_1,i_2 \mid i_1,i_2-k) p_2(i_1,i_2-k)
 \nonumber \\
p(i_1,i_2) =&\: p_1(i_1,i_2) + p_2(i_1,i_2)
\end{align}

\figref{2.3}{Figure 2.3} illustrates the expectation Poisson-gap sampling
distribution on two-dimensional Nyquist grids. It is important to note that
the Poisson-gap sampler originally proposed by Hyberts et al. does not
strictly follow Algorithm 2.1, because its sampling of each dimension is
dependent upon which points in other dimensions have been previously sampled.
This divergence between multidimensional Poisson-gap and Poisson-gap
constructed using Algorithm 2.1 is observed by comparison of
\figref{2.3}{Figures 2.3} and \figref{2.4}{2.4}, and is only
truly apparent at very low sampling densities.
\end{doublespace}

\begin{figure}[ht!]
\includegraphics[width=6in]{figs/dgs/05-psf.png}
\caption
      [Comparison of Gap Sampling Schedules.]{
  {\bf Comparison of Gap Sampling Schedules.}
  \\
  Comparison of sine-gap, Poisson-gap and sine-burst sampling schedules and
  their resulting point-spread functions at varying sampling densities,
  indicating close agreement between all methods. The increased artifact
  intensity in the sine-gap schedule at 5\% sampling density is likely due
  to slightly increased regularity of sampled grid points, which is reduced
  by Poisson-gap and sine-burst sampling. Grid sizes and point spread function
  colorings are the log-scaled versions of those found in Figure 1 of
  \cite{hoch:acr2014} in order to emphasize low-intensity sampling artifacts.
}
\label{figure.2.5}
\end{figure}

\section{Materials and Methods}

\subsection{Generation of Deterministic Schedules}

\begin{doublespace}
Deterministic sine-gap and sine-burst schedules were constructed using a small
C program that implements the presented gap sampling algorithm described above.
Schedules were generated at 30\%, 10\% and 5\% sampling densities on
one-dimensional grids having 1,024 points and two-dimensional grids having
64$\times$64 and 128$\times$128 points. The first and third rows of
\figref{2.5}{Figure 2.5} show the deterministic schedules resulting
from $g_{SG}$ and $g_{SB}$ at 30\% density on 128$\times$128 grids,
respectively.
\end{doublespace}

\subsection{Generation of Stochastic Schedules}

\begin{doublespace}
Poisson-gap schedules were constructed using Java source code authored and
provided by Hyberts et al. for generating multidimensional schedules
(\url{http://gwagner.med.harvard.edu/intranet/hmsIST/gensched_old.html}).
A small command-line wrapper was written to provide direct access to the
core schedule generation functions without use of the graphical interface.
Fifty thousand schedules were computed at each of the sampling densities
and grid sizes listed in \hyperlink{subsection.2.3.1}{Subsection 2.3.1}.
Each schedule was generated with a unique, large, odd-valued seed number
to ensure the broadest possible sampling of the PG ensemble. The second
row of \figref{2.5}{Figure 2.5} shows a representative two-dimensional
Poisson-gap schedule at 30\% sampling density.
\end{doublespace}

\begin{figure}[ht!]
\includegraphics[width=6in]{figs/dgs/06-hsqc.png}
\caption
      [Comparison of HSQC Spectral Reconstructions.]{
  {\bf Comparison of HSQC Spectral Reconstructions.}
  \\
  Uniformly sampled ({\bf A}) and IST reconstructed ({\bf B--D}) 2D \hnnmr{}
  HSQC spectra of ubiquitin, indicating nearly equivalent performance of all
  three gap sampling methods at low (5\%) sampling density. Spectra shown in
  ({\bf B}) through ({\bf D}) were reconstructed from nonuniformly subsampled
  copies of ({\bf A}) using Poisson-gap ({\bf B}), sine-gap ({\bf C}), and
  sine-burst ({\bf D}) schedules, respectively. All spectra are plotted with
  identical contour levels.
}
\label{figure.2.6}
\end{figure}

\begin{figure}[ht!]
\includegraphics[width=6in]{figs/dgs/07-hnca.png}
\caption
      [Comparison of HNCA Spectral Reconstructions.]{
  {\bf Comparison of HNCA Spectral Reconstructions.}
  \\
  Uniformly sampled ({\bf A}) and IST reconstructed ({\bf B--D}) 3D HNCA
  spectra of ubiquitin at low (5\%) sampling density, projected along the
  \nnmr{} dimension. Spectra shown in ({\bf B}) through ({\bf D}) were
  reconstructed from nonuniformly subsampled copies of ({\bf A}) using
  Poisson-gap ({\bf B}), sine-gap ({\bf C}), and sine-burst ({\bf D})
  schedules, respectively. While sine-gap sampling ({\bf C}) fails to
  adequately reproduce the spectrum due to its high sampling coherence,
  sine-burst sampling yields an essentially identical result to Poisson-gap
  sampling. All spectra are plotted with identical contour levels.
}
\label{figure.2.7}
\end{figure}

\subsection{Spectral Data Collection}

\begin{doublespace}
A high-resolution 2D \hnnmr{} HSQC NMR spectrum was collected at a temperature
of 298.0 K on a sample of uniformly [\nnmr{}, \cnmr{}]-labeled ubiquitin in
aqueous phosphate buffer at pH 6.5. Data were acquired on a Bruker Avance
III HD 700 MHz spectrometer equipped with a 5 mm inverse quadruple-resonance
(\hnmr{}, \cnmr{}, \nnmr{}, \pnmr{}) cryoprobe with cooled \hnmr{} and \cnmr{}
channels and a $z$-axis gradient. A 2D gradient-enhanced \hnnmr{} HSQC spectrum
with improved sensitivity \cite{kay:jacs1992,palmer:jmr1991} was collected with
16 scans and 32 dummy scans over a uniform grid of 2,048 and 1,024 hypercomplex
points along the \hnmr{} and \nnmr{} dimensions, respectively. Spectral widths
were set to 3,293$\pm$4,209 Hz along \hnmr{} and 8,514$\pm$1,419 Hz along
\nnmr{}. The spectrum was windowed with a squared-cosine function,
Fourier-transformed and phase-corrected along \hnmr{} to produce a
half-transformed spectrum for IST reconstruction analysis (vide infra),
and subsequently windowed and Fourier-transformed along \nnmr{} to yield the
``true'' uniformly sampled 2D \hnnmr{} HSQC spectrum.
\figref{2.6}{Figure 2.6} compares the true HSQC spectrum with
representative IST reconstructions after subsampling by
Poisson-gap, sine-gap and sine-burst schedules.
\\\\
In addition, a 3D HNCA NMR spectrum was collected on the same uniformly
[\nnmr{}, \cnmr{}]-labeled ubiquitin sample. The spectrum was collected at
298.0 K with 16 scans and 32 dummy scans over a uniform grid of
1,024$\times$64$\times$64 hypercomplex points along the \hnmr{}, \nnmr{} and
\cnmr{} dimensions, respectively. Spectral windows were set to
3,293$\pm$4,209 Hz along \hnmr{}, 8,514$\pm$1,419 Hz along \nnmr{}, and
9,508$\pm$2,818 Hz along \cnmr{}. The spectrum was windowed with a
squared-cosine, Fourier-transformed and phase-corrected along \hnmr{} to
produce an $F_3$-transformed spectrum for IST reconstruction analysis, and
subsequently windowed and Fourier transformed along \nnmr{} and \cnmr{} to
yield the ``true'' uniformly sampled 3D HNCA spectrum.
\figref{2.7}{Figure 2.7} compares \hcnmr{} projections of the true HNCA with
those of representative IST reconstructions after subsampling by Poisson-gap,
sine-gap and sine-burst schedules.
\end{doublespace}

\begin{figure}[ht!]
\includegraphics[width=6in]{figs/dgs/08-converge.png}
\caption
      [Convergence of IST Reconstruction Residuals.]{
  {\bf Convergence of IST Reconstruction Residuals.}
  \\
  Convergence analysis of IST reconstructions of ({\bf A}) \hnnmr{} HSQC $F_1$
  traces and ({\bf B}) HNCA $F_2-F_1$ planes. Both spectra were nonuniformly
  subsampled with a 5\% density sine-gap schedule prior to IST. Relative
  $\ell_2$ reconstruction errors computed from all data points are shown by
  blue lines, and errors computed only from initially sampled data points are
  shown by red lines. Grey dashed lines indicate the iteration count at which
  all IST reconstructions were performed to generate histograms of $\ell_2$
  errors.
}
\label{figure.2.8}
\end{figure}

\begin{figure}[ht!]
\includegraphics[width=6in]{figs/dgs/09-residuals.png}
\caption
      [Relative IST Reconstruction Residuals.]{
  {\bf Relative IST Reconstruction Residuals.}
  \\
  Iterative soft thresholding reconstruction $\ell_2$ residuals of ({\bf A})
  192 \hnnmr{} HSQC $F_1$ traces and ({\bf B}) 10 HNCA $F_2-F_1$ planes from
  Poisson-gap schedules having sampling densities of 30\% (blue), 10\% (green)
  and 5\% (red). Residuals of sine-gap and sine-burst schedules are shown as
  solid and dashed vertical lines, respectively.
}
\label{figure.2.9}
\end{figure}

\subsection{Computation of Performance Metrics}

\begin{doublespace}
All computational analyses were performed using in-house developed C programs.
An implementation of the hypercomplex algebra described by Schuyler et al.
\cite{schuyler:jmr2013} was used to perform all spectral data processing.
Iterative soft thresholding (IST) reconstructions of subsampled spectra were
performed using the algorithm described by Stern et al.
\cite{stern:jmr2007,sun:jbnmr2015}. Impulse sets were generated for each
constructed schedule by setting sampled grid points to one and skipped
grid points to zero. At each sampling density and grid size for which schedules
were created, point-spread functions were calculated by hypercomplex discrete
Fourier transformation of each schedule's impulse set. Point-spread functions
for schedules built on two-dimensional grids are shown for each sampling
density in \figref{2.5}{Figure 2.5}. For one-dimensional schedules,
reconstruction residuals were computed from a subset of 192 $F_1$ traces of
the half-transformed HSQC spectrum. The traces were nonuniformly subsampled
using sine-gap, sine-burst and Poisson-gap ($N$ = 10,000) schedules and
reconstructed with 400 iterations of IST at a threshold level of 98\%.
After reconstruction, the residual was calculated using the $\ell_2$-norm of
the differences between the true and reconstructed signals. A convergence
analysis was also performed (cf. \figref{2.8}{Figure 2.8}) to ensure
convergence of IST to a stationary point, as measured by a lack of decrease
in the $\ell_2$ error. \figref{2.9}{Figure 2.9A} shows the distributions of
IST reconstruction residuals from the HSQC traces. Reconstructions
of 10 $F_2-F_1$ planes of the $F_3$-transformed HNCA were also performed
after nonuniformly subsampling using sine-gap schedules, sine-burst
schedules, and a subset ($N$ = 10,000) of the generated Poisson-gap
schedules. \figref{2.9}{Figure 2.9B} shows IST reconstruction residuals
computed from the HNCA planes, and example reconstructions from each
sampling schedule at 5\% density are illustrated in
\figref{2.7}{Figure 2.7}.
\end{doublespace}

\begin{table}[h!]
\caption{Peak-picking Performances from IST-reconstructed HSQC Spectra.}
\begin{center}
\begin{tabular}{l l | l l l l l l}
  \hline
  {\bf Method} & & {\bf Matched}       & {\bf Lost}     & {\bf Gained} &
                   $\boldsymbol{\rho}$ & $\mathbf{d_H}$ & $\mathbf{d_N}$ \\
  \hline
     & 30\% & 99/99 & 0/99 & 2 & 0.9994 & 0.000724 & 0.004459 \\
  PG & 10\% & 99/99 & 0/99 & 4 & 0.9983 & 0.001208 & 0.008316 \\
     &  5\% & 98/99 & 1/99 & 8 & 0.9920 & 0.001430 & 0.009398 \\
  \hline
     & 30\% & 99/99 & 0/99 & 0 & 0.9996 & 0.000580 & 0.005957 \\
  SG & 10\% & 98/99 & 1/99 & 6 & 0.9983 & 0.001546 & 0.007809 \\
     &  5\% & 98/99 & 1/99 & 7 & 0.9939 & 0.001660 & 0.011393 \\
  \hline
     & 30\% & 99/99 & 0/99 & 1 & 0.9996 & 0.000534 & 0.008977 \\
  SB & 10\% & 98/99 & 1/99 & 5 & 0.9981 & 0.001071 & 0.010007 \\
     &  5\% & 98/99 & 1/99 & 7 & 0.9699 & 0.001482 & 0.013357 \\
\end{tabular}
\end{center}
\end{table}

\begin{table}[h!]
\caption{Peak-picking Performances from IST-reconstructed HNCA Spectra.}
\begin{center}
\begin{tabular}{l l | l l l l l l}
  \hline
  {\bf Method} & & {\bf Matched}       & {\bf Lost}     & {\bf Gained} &
                   $\boldsymbol{\rho}$ & $\mathbf{d_H}$ & $\mathbf{d_N}$ \\
  \hline
     & 30\% & 73/74 &  1/74 & 0 & 0.9978 & 0.000532 & 0.007556 \\
  PG & 10\% & 70/74 &  4/74 & 0 & 0.9905 & 0.001176 & 0.015378 \\
     &  5\% & 66/74 &  8/74 & 0 & 0.9745 & 0.001488 & 0.015092 \\
  \hline
     & 30\% & 73/74 &  1/74 & 0 & 0.9955 & 0.000585 & 0.010554 \\
  SG & 10\% & 66/74 &  8/74 & 1 & 0.9864 & 0.001793 & 0.016878 \\
     &  5\% & 64/74 & 10/74 & 0 & 0.9638 & 0.001903 & 0.020252 \\
  \hline
     & 30\% & 73/74 &  1/74 & 0 & 0.9977 & 0.000560 & 0.010475 \\
  SB & 10\% & 69/74 &  5/74 & 0 & 0.9883 & 0.001311 & 0.015739 \\
     &  5\% & 66/74 &  8/74 & 1 & 0.9781 & 0.001852 & 0.017306 \\
\end{tabular}
\end{center}
\end{table}

\subsection{Generation of Peak-picking Statistics}

\begin{doublespace}
A summary of the relative HSQC peak-picking performance for the IST
reconstructions from each sampling schedule and at each sampling density is
listed in Table 2.1. For each 2D \hnnmr{} HSQC spectrum of ubiquitin
reconstructed via IST at each sampling density and each sampling method,
a set of quality statistics was computed. Peak lists were generated using the
\verb peakHN.tcl  utility provided by NMRPipe \cite{delaglio:jbnmr1995}, with
a minimum intensity threshold of $3.0 \times 10^7$. Then, a greedy algorithm
was used to generate a maximum-cardinality bipartite matching between the peak
list of each reconstructed spectrum and the peak list of the true spectrum.
Chemical shift windows of 0.015 ppm and 0.08 ppm were used along the \hnmr{}
and \nnmr{} dimensions, respectively, during matching. The numbers of peaks
matched, lost and gained in the reconstructed spectra, relative to the true
spectrum, were all counted. Lost peaks were any picked peaks in the true
spectrum that had no match in the reconstruction. Gained peaks were any
picked peaks in the reconstruction with no partner in the true spectrum.
The intensities of all matched peaks in each reconstruction were then
compared against their true intensities through the computation of a Pearson
correlation coefficient, $\rho$, which effectively summarizes the linearity
of the reconstruction algorithm as a function of sampling schedule. Finally,
root-mean-square chemical shift deviations of all matched peaks along the
\hnmr{} dimension ($d_H$) and the \nnmr{} dimension ($d_N$) were also
computed. Identical procedures and parameters, with the exception of an
intensity threshold of $6.0 \times 10^8$, were used to peak-pick the \hnnmr{}
projections of the uniform and reconstructed HNCA spectra (cf. Table 2.2).
\end{doublespace}

\begin{figure}
\includegraphics[width=6in]{figs/dgs/10-rejhist.png}
\caption
      [Gap Length Histograms from Rejection Sampling.]{
  {\bf Gap Length Histograms from Rejection Sampling.}
  \\
  ({\bf A}) Normalized histograms of gap lengths at various points in an
  ensemble of 10,000,000 sampling schedules generated by rejection sampling
  from the Poisson-gap expectation sampling distribution (equation 2.11).
  ({\bf B}) Normalized histograms of gap lengths produced by true Poisson-gap
  sampling. Examination of these histograms clearly indicates that the
  schedules generated by rejection sampling are \emph{not} Poisson-gap
  schedules.
}
\label{figure.2.10}
\end{figure}

\subsection{Analysis of Sampling Distributions}

\begin{doublespace}
Expectation sampling distributions were also generated from the set of
Poisson-gap schedules by averaging their resulting impulse sets.
\figref{2.2}{Figure 2.2} shows the expectation sampling distributions
for one-dimensional schedules having different sampling densities, and
\figref{2.3}{Figures 2.3} and \figref{2.4}{2.4} show the distributions
for two-dimensional schedules having the same densities. The heavy bias
towards early time points in Poisson-gap sampling is reaffirmed in all
figures. Sampling distributions were also computed via equations
2.11 and 2.12 for comparison to the distributions obtained by averaging
multiple impulse sets (\figref{2.2}{Figures 2.2} and \figref{2.3}{2.3}).
To verify that fully random sampling from equation 2.11 and gap sampling
from $g_{PG}$ are not equivalent, 10,000,000 sampling schedules were generated
by rejection sampling 51 grid points from equation 2.11 at $\Lambda=62.9$
and $N=1024$, and histograms of the gap lengths at each grid point were
computed (\figref{2.10}{Figure 2.10}). If the two methods were indeed
equivalent, one would expect the histograms in \figref{2.10}{Figure 2.10A}
to resemble Poisson distributions (\figref{2.10}{2.10B}).
\end{doublespace}

\subsection{Average Poisson-gap Sequences}

\begin{doublespace}
For \figref{2.1}{Figure 2.1}, each schedule
$\{x_1^{(m)}, x_2^{(m)},\dots, x_n^{(m)}\}$ in
the generated ensemble of $M$ (here, $M$ = 50,000)
one-dimensional Poisson-gap schedules was averaged
on a term-by-term basis:
\begin{equation}
\langle x_i \rangle = \frac{1}{M} \sum_{m=1}^M x_i^{(m)}
\end{equation}
to produce the average Poisson-gap schedule
$\{\langle x_1 \rangle, \langle x_2 \rangle,\dots, \langle x_n \rangle\}$.
Similar procedures were performed to compute the standard deviation of the
Poisson-gap ensemble. Deterministic sampling schedules with a 1x exponential
bias were computed according to procedures outlined by
Eddy et al. \cite{eddy:jmr2012}. Relative errors
(\figref{2.1}{Figure 2.1}) between a given
sine-gap schedule $\{y_1, y_2,\dots, y_n\}$ and average Poisson-gap schedule
were computed by a term-by-term subtraction of one schedule from the other,
followed by a division by the average Poisson-gap terms:
\begin{equation}
\Delta_i = \frac{y_i - \langle x_i \rangle}{\langle x_i \rangle}
 \quad \forall i \in \{1,2,\dots, n\}
\end{equation}

Relative errors between the deterministic exponential schedules and the
average Poisson-gap sequence were similarly computed.
\end{doublespace}

\begin{SCfigure}
\includegraphics[width=3.25in]{figs/dgs/11-spurs.png}
\caption
      [Introduction of Spurs by Squared-sine Modulation.]{
  {\bf Introduction of Spurs by Squared-sine Modulation.}
  \\
  Impulse response functions (IRFs) of sine-gap (blue) and sine-burst (red)
  sampling schedules at 5\% density, demonstrating the appearance of
  low-frequency spurs induced by burst augmentation of the gap equation.
}
\label{figure.2.11}
\end{SCfigure}

\section{Results}

\begin{doublespace}
While at first glance, the deterministic schedule constructed using $g_{SG}$
in \figref{2.5}{Figure 2.5} may appear unrelated to the Poisson-gap
schedule, it is in fact a realization of Poisson-gap sampling in which all
random draws from the underlying Poisson distribution have resulted in the
expected value. This fact is corroborated by the corresponding point-spread
functions, which closely resemble those of the stochastic example at 30\% and
10\% sampling density. Reconstruction residuals from IST
(\figref{2.7}{Figure 2.7}) also reveal a high similarity between the
deterministic sine-gap and stochastic Poisson-gap schedules
at 30\% and 10\% density. However, the sine-gap PSF becomes less
comparable to that of Poisson-gap at low sampling densities, where the
benefits of incoherent sampling are more apparent. It is worth noting
that the striking appearance of sampling artifacts in the sine-gap PSF is a
consequence of the log-scaled color gradient used in \figref{2.5}{Figure 2.5},
which was necessary in order to visually expose very low-intensity artifacts.
\\\\
The addition of burst augmentation in the form of $g_{SB}$ does not
substantially alter IST reconstruction residuals relative to $g_{SG}$ and
$g_{PG}$. However, artifacts arising from regularity in $g_{SG}$-based
schedules at low sampling densities are diminished by burst augmentation,
resulting in point-spread functions that more closely resemble those from
stochastic Poisson-gap sampling. This reduction of artifacts by burst
augmentation comes at a small cost, at low-frequency spurs are introduced
into the sine-burst point-spread function (\figref{2.11}{Figure 2.11}) by
modulating the gap equation. However, these spurs are low in magnitude and
only readily apparent at very low (5\%) sampling density. These spurs could
potentially be reduced by burst-modulating each dimension in the schedule
by a different factor.

IST residuals of sine-burst schedules (\figref{2.9}{Figure 2.9}, dashed lines)
are slightly greater than those of one-dimensional sine-gap schedules and dense
two-dimensional sine-gap schedules, but they improve relative to sine-gap as
sampling density is decreased. Therefore, while sine-gap sampling is a valuable
tool for understanding the nature of Poisson-gap sampling, it is clearly bested
in performance by multidimensional sine-burst sampling as global sampling
density is decreased. Burst augmentation re-introduces sampling incoherence
into highly coherent sine-gap schedules to produce sine-burst schedules that
more closely resemble Poisson-gap sampling schedules. This added incoherence
is clearly evident in the \hcnmr{} projections of reconstructed HNCA spectra
(\figref{2.7}{Figure 2.7}), where the more incoherent sine-burst schedule
yields a more faithful spectral reconstruction than the sine-gap schedule
can.
\end{doublespace}

\section{Discussion and Conclusions}

\begin{doublespace}
This chapter has shown that Poisson-gap sampling is a single instance in a
class of gap sampling methods, which may or may not be defined stochastically.
Using the well-defined gap sampling algorithm, two novel deterministic sampling
methods have been described: sine-gap and sine-burst sampling. Neither of
these new methods relies on random deviates, and both have comparable
performance to Poisson-gap sampling according to IST reconstruction residuals.
From a practical perspective, Poisson-gap, sine-gap and sine-burst sampling
methods produced nearly equivalent HSQC spectral reconstructions
(\figref{2.6}{Figure 2.6}) that yielded essentially identical
information (chemical shifts, peak intensities) as highlighted in Table 2.1.
Poisson-gap and sine-burst sampling also produced nearly equivalent HNCA
spectra (\figref{2.7}{Figure 2.7}) after IST reconstruction, even at low
sampling density. Table 2.2 also summarizes the peak-picking statistics
collected on \hnnmr{} projections of the reconstructed HNCA spectra. For the
practicing spectroscopist, this equates to the ability to nonuniformly sample
at the performance level of Poisson-gap, without specifying a pseudorandom
seed. Gap sampling is a flexible and attractive alternative to traditional
probabilistic sampling methods that use probability densities to define the
local sampling density over a Nyquist grid. In effect, gap sampling approaches
the problem of local sampling density from the opposite direction of
probabilistic sampling by defining the distances \emph{between} samples on
the grid. This chapter also holds a brief derivation of the mathematical
connection between stochastic gap equations and their expectation sampling
distributions, which allows for direct visualization of the grid-point
weighting produced by a given gap equation. While these expectation sampling
distributions are useful in describing the sampling behavior of a stochastic
gap equation, they do not provide a means of converting a gap-based sampling
method into a fully random sampling method. In other words, it has been shown
that any method of constrained random sampling using a gap equation is
inequivalent to fully random sampling from its corresponding expectation
sampling distribution.
\\\\
Finally, burst augmentation provides a concrete example of how deterministic
gap sampling may be tuned to behave in a similar fashion to pseudorandom
numbers. At first glance, the third row of \figref{2.5}{Figure 2.5} would
appear to have been generated stochastically, but it is a consequence of the
squared-sine modulation term in $g_{SB}$. It has historically been true that
stochastically generated sampling schedules produced fewer prominent artifacts
than deterministic methods such as radial or spiral sampling, due to high
regularity (i.e. coherence) of the latter schemes. However, burst augmentation
demonstrates that pseudorandom variates are not strictly required for producing
incoherent sampling methods. Furthermore, while most pseudorandom number
generators are indeed deterministic for a given seed value, this
determinism is \emph{inherently different} from the determinism
offered by sine-gap and sine-burst sampling. By design, any
parameters (e.g. reconstruction residuals) measured from pseudorandomly
generated sampling schedules will not be smoothly varying -- and therefore
optimizable -- functions of their random seed value. As a consequence, no
absolute guarantee of spectral quality is provided to the spectroscopist
employing pseudorandom sampling schedules, even if the relative difference
in quality between the best- and worst-performing Poisson-gap seed values
is small at sampling densities above 30\%. This problem with seeds has
already been recognized: Poisson-gap and jittered sampling methods are, in
fact, two separate attempts at minimizing -- but not removing -- the effect
of seed values on schedule performance
\cite{hyberts:jacs2010,kazimierczuk:jmr2007,mobli:jmr2015}. Deterministic
gap sampling completely frees the user from specifying an arbitrary seed
value, and provides a highly general framework that enables further
investigation into which features of NUS schedules yield higher-quality
reconstruction results.
\\\\
The C implementations of Poisson-gap, sine-gap and sine-burst sampling are
free and open source software, and are available for download at
\url{http://bionmr.unl.edu/dgs.php}. The programs are highly portable and
C99 compliant, so they may be compiled on any modern operating system. An
online schedule generation tool is also provided at the same address for
rapid generation of one-, two- and three-dimensional NUS schedules suitable
for direct use on Bruker or Agilent spectrometers. As defined and implemented,
the recursive schedule generation algorithm is not limited to any number of
grid dimensions. However, the online tool has been hard-limited to 3D grids
to minimize server load.
\end{doublespace}

\bibliographystyle{abbrv}
\bibliography{bworley}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Copyright (c) 2003-2018 by The University of Queensland
% http://www.uq.edu.au
%
% Primary Business: Queensland, Australia
% Licensed under the Apache License, version 2.0
% http://www.apache.org/licenses/LICENSE-2.0
%
% Development until 2012 by Earth Systems Science Computational Center (ESSCC)
% Development 2012-2013 by School of Earth Sciences
% Development from 2014 by Centre for Geoscience Computing (GeoComp)
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Models}
\label{MODELS CHAPTER}

The following sections give a brief overview of the model classes and their
corresponding methods.

\input{stokessolver}
%\input{darcyfluxNew}
\input{darcyflux}
%\input{levelsetmodel}

\section{Isotropic Kelvin Material \label{IKM}}
As proposed by Kelvin~\cite{Muhlhaus2005} material strain
$D_{ij}=\frac{1}{2}(v_{i,j}+v_{j,i})$ can be decomposed into an elastic part
$D_{ij}^{el}$ and a visco-plastic part $D_{ij}^{vp}$:
\begin{equation}\label{IKM-EQU-2}
D_{ij}=D_{ij}^{el}+D_{ij}^{vp}
\end{equation}
with the elastic strain given as
\begin{equation}\label{IKM-EQU-3}
D_{ij}^{el'}=\frac{1}{2 \mu} \dot{\sigma}_{ij}'
\end{equation}
where $\sigma'_{ij}$ is the deviatoric stress (notice that $\sigma'_{ii}=0$).
If the material is composed by materials $q$ the visco-plastic strain can be
decomposed as
\begin{equation}\label{IKM-EQU-4}
D_{ij}^{vp'}=\sum_{q} D_{ij}^{q'}
\end{equation}
where $D_{ij}^{q}$ is the strain in material $q$ given as
\begin{equation}\label{IKM-EQU-5}
D_{ij}^{q'}=\frac{1}{2 \eta^{q}} \sigma'_{ij}
\end{equation}
and $\eta^{q}$ is the viscosity of material $q$.
We assume the following between the strain in material $q$
\begin{equation}\label{IKM-EQU-5b}
\eta^{q}=\eta^{q}_{N} \left(\frac{\tau}{\tau_{t}^q}\right)^{1-n^{q}}
\mbox{ with } \tau=\sqrt{\frac{1}{2}\sigma'_{ij} \sigma'_{ij}}
\end{equation}
for given power law coefficients $n^{q}\ge1$ and transition stresses
$\tau_{t}^q$, see~\cite{Muhlhaus2005}.
Notice that $n^{q}=1$ gives a constant viscosity.
After inserting \eqn{IKM-EQU-5} into \eqn{IKM-EQU-4} one gets:
\begin{equation}\label{IKM-EQU-6}
D_{ij}'^{vp}=\frac{1}{2 \eta^{vp}} \sigma'_{ij} \mbox{ with } \frac{1}{\eta^{vp}} = \sum_{q} \frac{1}{\eta^{q}} \;.
\end{equation}
and finally with~\ref{IKM-EQU-2}
\begin{equation}\label{IKM-EQU-2bb}
D_{ij}'=\frac{1}{2 \eta^{vp}} \sigma'_{ij}+\frac{1}{2 \mu} \dot{\sigma}_{ij}'
\end{equation}
The total stress $\tau$ needs to fulfill the yield condition\index{yield condition}
\begin{equation}\label{IKM-EQU-8c}
\tau \le \tau_{Y} + \beta \; p
\end{equation}
with the Drucker-Prager\index{Druck-Prager} cohesion factor\index{cohesion factor}
$\tau_{Y}$, Drucker-Prager friction $\beta$ and total pressure $p$.
The deviatoric stress needs to fulfill the equilibrium equation
\begin{equation}\label{IKM-EQU-1}
-\sigma'_{ij,j}+p_{,i}=F_{i}
\end{equation}
where $F_{j}$ is a given external force. We assume an incompressible medium:
\begin{equation}\label{IKM-EQU-2bbb}
-v_{i,i}=0
\end{equation}
Natural boundary conditions are taken in the form
\begin{equation}\label{IKM-EQU-Boundary}
\sigma'_{ij}n_{j}-n_{i}p=f
\end{equation}
which can be overwritten by a constraint
\begin{equation}\label{IKM-EQU-Boundary0}
v_{i}(x)=0
\end{equation}
where the index $i$ may depend on the location $x$ on the boundary.

\subsection{Solution Method \label{IKM-SOLVE}}
By using a first order finite difference approximation with step size
$dt>0$ \eqn{IKM-EQU-3} is transformed to
\begin{equation}\label{IKM-EQU-3b}
\dot{\sigma}_{ij}=\frac{1}{dt } \left( \sigma_{ij} - \sigma_{ij}^{-} \right)
\end{equation}
and
\begin{equation}\label{IKM-EQU-2b}
D_{ij}'=\left(\frac{1}{2 \eta^{vp}} + \frac{1}{2 \mu dt}\right) \sigma_{ij}'-\frac{1}{2 \mu dt } \sigma_{ij}^{-'}
\end{equation}
where $\sigma_{ij}^{-}$ is the stress at the previous time step. With
\begin{equation}\label{IKM-EQU-2c}
\dot{\gamma} = \sqrt{ 2 \left( D_{ij}' +
\frac{1}{  2 \mu \; dt} \sigma_{ij}^{-'}\right)^2}
\end{equation}
we have
\begin{equation}
\tau = \eta_{eff} \cdot \dot{\gamma}
\end{equation}
where
\begin{equation}
\eta_{eff}= min( \left(\frac{1}{\mu \; dt}+\frac{1}{\eta^{vp}}\right)^{-1}
, \eta_{max}) \mbox{ with }
\eta_{max} = \left\{
\begin{array}{rcl}
\frac{\tau_{Y} + \beta \; p}{\dot{\gamma}} & & \dot{\gamma}>0 \\
&\mbox{ if } \\
\infty & & \mbox{otherwise}
\end{array}
\right.
\end{equation}
The upper bound $\eta_{max}$ makes sure that yield condition~\ref{IKM-EQU-8c}
holds. With this setting the equation \ref{IKM-EQU-2b} takes the form
\begin{equation}\label{IKM-EQU-10}
\sigma_{ij}' =  2 \eta_{eff}  \left( D_{ij}' +
\frac{1}{  2 \mu \; dt} \sigma_{ij}^{'-}\right)
\end{equation}
After inserting~\ref{IKM-EQU-10} into~\ref{IKM-EQU-1} we get
\begin{equation}\label{IKM-EQU-1ib}
-\left(\eta_{eff} (v_{i,j}+ v_{i,j})
\right)_{,j}+p_{,i}=F_{i}+
 \left(\frac{\eta_{eff}}{\mu dt } \sigma_{ij}^{'-} \right)_{,j}
\end{equation}
Combining this with the incompressibility condition~\ref{IKM-EQU-2} we need to
solve a Stokes problem as discussed in \Sec{STOKES SOLVE} in each time step.

If we set
\begin{equation}\label{IKM-EQU-44}
\frac{1}{\eta(\tau)}= \frac{1}{\mu \; dt}+\frac{1}{\eta^{vp}}
\end{equation}
we need to solve the nonlinear problem
\begin{equation}
\eta_{eff} -  min(\eta( \dot{\gamma} \cdot \eta_{eff})
, \eta_{max}) =0
\end{equation}
We use the Newton-Raphson scheme\index{Newton-Raphson scheme} to solve this
problem:
\begin{equation}\label{IKM-EQU-45}
\eta_{eff}^{(n+1)} = \min(\eta_{max},
\eta_{eff}^{(n)} -
\frac{\eta_{eff}^{(n)} - \eta( \tau^{(n)}) }
{1-\dot{\gamma} \cdot \eta'( \tau^{(n)} )} )
=\min(\eta_{max},
\frac{\eta( \tau^{(n)}) -\tau^{(n)} \cdot  \eta'( \tau^{(n)} )  }
{1-\dot{\gamma} \cdot \eta'( \tau^{(n)} )} )
\end{equation}
where $\eta'$ denotes the derivative of $\eta$ with respect to $\tau$
and $\tau^{(n)} = \dot{\gamma} \cdot \eta_{eff}^{(n)}$.
Looking at the evaluation of $\eta$ in~\ref{IKM-EQU-44} it makes sense to
formulate the iteration~\ref{IKM-EQU-45} using $\Theta=\eta^{-1}$.
In fact we have
\begin{equation}
\eta' = - \frac{\Theta'}{\Theta^2}
\mbox{ with }
\Theta' = \sum_{q} \left(\frac{1}{\eta^{q}} \right)'
\label{IKM iteration 7}
\end{equation}
As
\begin{equation}\label{IKM-EQU-47}
\left(\frac{1}{\eta^{q}} \right)'
= \frac{n^{q}-1}{\eta^{q}_{N}} \cdot \frac{\tau^{n^{q}-2}}{(\tau_{t}^q)^{n^{q}-1}}
= \frac{n^{q}-1}{\eta^{q}}\cdot\frac{1}{\tau}
\end{equation}
we have
\begin{equation}\label{IKM-EQU-48}
\Theta' = \frac{1}{\tau} \omega \mbox{ with } \omega = \sum_{q}\frac{n^{q}-1}{\eta^{q}}
\end{equation}
which leads to
\begin{equation}\label{IKM-EQU-49}
\eta_{eff}^{(n+1)} = \min(\eta_{max},
\eta_{eff}^{(n)}
\frac{\Theta^{(n)}  + \omega^{(n)}  }
{\eta_{eff}^{(n)} \Theta^{(n)^2}+\omega^{(n)} })
\end{equation}

\subsection{Functions}

\begin{classdesc}{IncompressibleIsotropicFlowCartesian}{
domain
\optional{, stress=0
\optional{, v=0
\optional{, p=0
\optional{, t=0
\optional{, numMaterials=1
\optional{, verbose=True
\optional{, adaptSubTolerance=True
}}}}}}}}
opens an incompressible, isotropic flow problem in Cartesian coordinates on
the domain \var{domain}.
\var{stress}, \var{v}, \var{p}, and \var{t} set the initial deviatoric stress,
velocity, pressure and time.
\var{numMaterials} specifies the number of materials used in the power law
model. Some progress information is printed if \var{verbose} is set to \True.
If \var{adaptSubTolerance} is equal to \True the tolerances for subproblems
are set automatically.

The domain needs to support LBB compliant elements for the Stokes problem,
see~\cite{LBB} for details\index{LBB condition}.
For instance one can use second order polynomials for velocity and first order
polynomials for the pressure on the same element. Alternatively, one can use
macro elements\index{macro elements} using linear polynomials for both
pressure and velocity but with a subdivided element for the velocity.
Typically, the macro element method is more cost effective.
The fact that pressure and velocity are represented in different ways is
expressed by
\begin{python}
  velocity=Vector(0.0, Solution(mesh))
  pressure=Scalar(0.0, ReducedSolution(mesh))
\end{python}
\end{classdesc}

\begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{getDomain}{}
returns the domain.
\end{methoddesc}

\begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{getTime}{}
returns current time.
\end{methoddesc}

\begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{getStress}{}
returns current stress.
\end{methoddesc}

\begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{getDeviatoricStress}{}
returns current deviatoric stress.
\end{methoddesc}

\begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{getPressure}{}
returns current pressure.
\end{methoddesc}

\begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{getVelocity}{}
returns current velocity.
\end{methoddesc}

\begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{getDeviatoricStrain}{}
returns deviatoric strain of current velocity
\end{methoddesc}

\begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{getTau}{}
returns current second invariant of deviatoric stress
\end{methoddesc}

\begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{getGammaDot}{}
returns current second invariant of deviatoric strain
\end{methoddesc}

\begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{setTolerance}{tol=1.e-4}
sets the tolerance used to terminate the iteration on a time step.
\end{methoddesc}

\begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{setFlowTolerance}{tol=1.e-4}
sets the relative tolerance for the incompressible solver, see
\class{StokesProblemCartesian} for details.
\end{methoddesc}

\begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{setElasticShearModulus}{mu=None}
sets the elastic shear modulus $\mu$. If \var{mu} is set to None (default)
elasticity is not applied.
\end{methoddesc}

\begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{setEtaTolerance=}{rtol=1.e-8}
sets the relative tolerance for the effective viscosity. Iteration on a time
step is completed if the relative of the effective viscosity is less than
\var{rtol}.
\end{methoddesc}

\begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{setDruckerPragerLaw}
{\optional{tau_Y=None, \optional{friction=None}}}
sets the parameters $\tau_{Y}$ and $\beta$ for the Drucker-Prager model in
condition~\ref{IKM-EQU-8c}. If \var{tau_Y} is set to None (default) then the
Drucker-Prager condition is not applied.
\end{methoddesc}

\begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{setElasticShearModulus}{mu=None}
sets the elastic shear modulus $\mu$. If \var{mu} is set to None (default)
elasticity is not applied.
\end{methoddesc}

\begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{setPowerLaws}{eta_N, tau_t, power}
sets the parameters of the power-law for all materials as defined in \eqn{IKM-EQU-5b}.
\var{eta_N} is the list of viscosities $\eta^{q}_{N}$,
\var{tau_t} is the list of reference stresses  $\tau_{t}^q$,
and \var{power} is the list of power law coefficients $n^{q}$.
\end{methoddesc}

\begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{update}{dt
\optional{, iter_max=100
\optional{, inner_iter_max=20
}}}
updates stress, velocity and pressure for time increment \var{dt}, where
\var{iter_max} is the maximum number of iteration steps on a time step to
update the effective viscosity and \var{inner_iter_max} is the maximum
number of iteration steps in the incompressible solver.
\end{methoddesc}

%\subsection{Example}
%later

\input{faultsystem}

%\section{Drucker Prager Model}