% Copyright 2019 by Mark Wibrow
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.

\section{Customizing the Mathematical Engine}
\label{pgfmath-reimplement}

Perhaps you have a desire for some function that \pgfname\ does not provide.
Perhaps you are not happy with the accuracy or efficiency of some of the
algorithms that are implemented in \pgfname. In these cases you will want to
add a function to the parser or replace the current implementations of the
algorithms with your own code.

The mathematical engine was designed with such customization in mind. It is
possible to add new functions, or modify the code for existing functions. Note,
however, that whilst adding new operators is possible, it can be a rather
tricky business and is only recommended for adventurous users.

To add a new function to the math engine the following command can be used:

\begin{command}{\pgfmathdeclarefunction\opt{|*|}\marg{function name}\marg{number of arguments}\marg{code}}
    This will set up the parser to recognize a function called \meta{name}. The
    name of the function can consist of, uppercase or lowercase letters,
    numbers or the underscore |_|. In line with many programming languages, a
    function name cannot begin with a number or contain any spaces. The
    function may not have been declared earlier, unless the optional star (|*|)
    is provided, which forces an ``overwriting'' of the function by the new
    function. Note that you \emph{should never change the arity of standard
    functions} and you should normally use |\pgfmathredeclarefunction|,
    which does not allow you to do anything wrong here.

    The \meta{number of arguments} can be any positive integer, zero, or the
    value |...|, which indicates a variable number of arguments. \pgfname{}
    treats constants, such as |pi| and |e|, as functions with zero arguments.
    Functions with more than nine arguments or with a variable number of
    arguments are a ``bit special'' and are discussed below.

    The effect of \meta{code} should be to set the macro |\pgfmathresult| to
    the correct value (namely to the result of the computation without units).
    Furthermore, the function should have no other side effects, that is, it
    should not change any global values. As an example, consider the creation
    of a new function |double|, which takes one argument, and returns the value
    of that argument times two.
    %
\begin{codeexample}[]
\makeatletter
\pgfmathdeclarefunction{double}{1}{
  \begingroup
    \pgf@x=#1pt\relax
    \multiply\pgf@x by2\relax
    \pgfmathreturn\pgf@x
  \endgroup
}
\makeatother
\pgfmathparse{double(44.3)}\pgfmathresult
\end{codeexample}

    The macro |\pgfmathreturn|\meta{tokens} must be
    directly followed by an |\endgroup| and will save the result of the
    computation, by defining |\pgfmathresult| as the expansion of
    \meta{tokens} (without units) outside the group, so \meta{tokens}
    must be something that can be assigned to a dimension register.

    Alternatively, the |\pgfmathsmuggle|\meta{macro} can be used. This must
    also be directly followed by an |\endgroup| and will simply ``smuggle'' the
    definition of \meta{macro} outside the \TeX-group.

    By performing computations within a \TeX-group, \pgfname{} registers such
    as |\pgf@x|, |\pgf@y| and |\c@pgf@counta|, |\c@pgfcountb|, and so forth,
    can be used at will.

    Beyond setting up the parser, this command also defines two macros which
    provide access to the function independently of the parser:
    %
    \begin{itemize}
        \item |\pgfmath|\meta{function name}

            This macro will provide a ``public'' interface for the function
            \meta{function name} allowing the function to be called
            independently of the parser. All arguments passed to this macro are
            evaluated using |\pgfmathparse| and then passed on to the following
            macro:
        \item |\pgfmath|\meta{function name}|@|

            This macro is the ``private'' implementation of the function's
            algorithm (but note that, for speed, the parser calls this macro
            rather than the ``public'' one). Arguments passed to this macro are
            expected to be numbers without units. It is defined using
            \meta{code}, but need not be self-contained.
    \end{itemize}

    For functions that are declared with less than ten arguments, the public
    macro is defined in the same way as normal \TeX{} macros using, for
    example, |\def\pgfmathNoArgs{|\meta{code}|}| for a function with no
    arguments, or |\def\pgfmathThreeArgs#1#2#3{|\meta{code}|}| for a function
    with three arguments. The private macro is defined in the same way, and
    each argument can therefore be accessed in \meta{code} using |#1|, |#2| and
    so on.

    For functions with more than nine arguments, or functions with a variable
    number of arguments, these macros are only defined as taking \emph{one}
    argument. The public macro expects its arguments to be comma separated, for
    example, |\pgfmathVariableArgs{1.1,3.5,-1.5,2.6}|. Each argument is parsed
    and passed on to the private macro as follows:
    |\pgfmathVariableArgs@{{1.1}{3.5}{-1.5}{2.6}}|. This means that some
    ``extra work'' will be required to access each argument (although it is a
    fairly simple task).

    Note that there are two exceptions to this arrangement: the public versions
    of the |min| and |max| functions still take two arguments for compatibility
    with older versions, but each of these arguments can take several comma
    separated values.
\end{command}

To redefine a function use the following command:

\begin{command}{\pgfmathredeclarefunction\marg{function name}\marg{code}}
    This command redefines the |\pgfmath|\meta{function name}|@| macro with the
    new \meta{code}. See the description of the
    |\pgfmathdeclarefunction| for details. You cannot change the number of
    arguments for an existing function.
    %
\begin{codeexample}[]
\makeatletter
\pgfmathdeclarefunction{foo}{1}{
  \begingroup
    \pgf@x=#1pt\relax
    \multiply\pgf@x by2\relax
    \pgfmathreturn\pgf@x
  \endgroup
}
\pgfmathparse{foo(42)}\pgfmathresult
\pgfmathredeclarefunction{foo}{
  \begingroup
    \pgf@x=#1pt\relax
    \multiply\pgf@x by3\relax
    \pgfmathreturn\pgf@x
  \endgroup
}
\pgfmathparse{foo(42)}\pgfmathresult
\makeatother
\end{codeexample}
    %
\end{command}

    \pgfname{} uses the last known definition of a function within the
    prevailing scope, so it is possible for a function to be redefined locally.
    You should also remember that any |.sty| or |.tex| file containing any
    re-implementations should be loaded after |pgfmath|.

    In addition to the above commands, the following key is provided to quickly
    create simple ad hoc functions which can greatly improve the readability of
    code, and is particularly useful in \tikzname{}:

\begin{key}{/pgf/declare function=\meta{function definitions}}
    This key allows simple functions to be created locally. Its use is perhaps
    best illustrated by an example:
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw [help lines] (0,0) grid (3,2);
  \draw [blue, thick, x=0.0085cm, y=1cm,
    declare function={
      sines(\t,\a,\b)=1 + 0.5*(sin(\t)+sin(\t*\a)+sin(\t*\b));
    }]
    plot [domain=0:360, samples=144, smooth] (\x,{sines(\x,3,5)});
\end{tikzpicture}
\end{codeexample}

    Each definition in \meta{function definitions} takes the form
    \meta{name}|(|\meta{arguments}|)=|\meta{definition}|;| (note the semicolon
    at the end, this is very important). If multiple functions are being
    defined, the semicolon is used to separate them (\emph{not} a comma). The
    function \meta{name} can be any name that is not already a function name in
    the current scope. The list of \meta{arguments} are commands such as |\x|,
    or |\y| (it is not possible to declare functions that take variable numbers
    of arguments using this key). If the function takes no arguments, then the
    parentheses need not be used. The \meta{definition} should be an expression
    that can be parsed by the mathematical engine and should use the commands
    specified in \meta{arguments}.

    When specifying multiple functions, functions that appear later on in
    \meta{function definitions} can refer to earlier functions:
    %
\begin{codeexample}[pre={\pgfmathsetseed{1}}]
\begin{tikzpicture}[
  declare function={
    excitation(\t,\w) = sin(\t*\w);
    noise             = rnd - 0.5;
    source(\t)        = excitation(\t,20) + noise;
    filter(\t)        = 1 - abs(sin(mod(\t, 90)));
    speech(\t)        = 1 + source(\t)*filter(\t);
  }
]
  \draw [help lines] (0,0) grid (3,2);
  \draw [blue, thick, x=0.0085cm, y=1cm] (0,1) --
    plot [domain=0:360, samples=144, smooth] (\x,{speech(\x)});
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/pgf/declare function/execute at begin function=\meta{tokens}}
    These \meta{tokens} are inserted just before |\pgfmathdeclarefunction|
    scans the body of the function definition.  This is a rather low-level
    option, so you should read the implementation to figure out where the
    \meta{tokens} are inserted.
\end{key}

\begin{key}{/pgf/declare function/execute at end function=\meta{tokens}}
    These \meta{tokens} are inserted just after |\pgfmathdeclarefunction| has
    finished scanning the body of the function definition.  This is a rather
    low-level option, so you should read the implementation to figure out where
    the \meta{tokens} are inserted.
\end{key}

\begin{key}{/pgf/declare function/ignore spaces=\meta{boolean}}
    Uses the two previously described keys |/pgf/declare function/execute at begin function| and
    |/pgf/declare function/execute at end function| to install catcodes such
    that spaces inside the body of the function definition of
    |\pgfmathdeclarefunction| are ignored.  The usual \TeX\ tokenization rules
    apply, so if the body of the function had already been tokenized by other
    means this will become ineffective.  If you want to use a space you can use
    |~| in the function body which has its catcode set to 10 (space).
\end{key}


%%===================================================================
%% Subsection 4.01.02: Integral Equation Solutions are Jost Solutions
%%===================================================================

\documentclass[../dissertation.tex]{subfiles}

\begin{document}
\subsection{Integral Equation Solutions are Jost Solutions}\label{subsec4:IEtoDE}

We continue in this subsection with our discussion of the equivalence of
the linear spectral problem with prescribed asymptotics its corresponding
integral equation reformulation by turning our attention to showing
that the analytic continuation $M$ to the strip $\mathcal S_1$ of a
function $M^+$ satisfying
Definition \ref{dfn4:IEsoln} satisfies Definition \ref{dfn4:DEsoln}.

From Proposition \ref{prop2:Tasymp} and our work in Chapter \ref{cptr03:xContin},
we already know that any function $M^+$ satisfying Definition \ref{dfn4:IEsoln}
has an analytic continuation to the complex strip $\mathcal S_1$ which
satisfies part (a) of property \ref{itm:asymp}, and property \ref{itm:space}
and property \ref{itm:cont} of Definition \ref{dfn4:DEsoln}. As such, our task in this
section is to first show that
the boundary value $M^-$ satisfies property \ref{itm:asymp}, which
we do in Lemma \ref{lma4:upperasymp}. We then show in Lemma \ref{lma4:IEtoDE4}
$M$ has decomposition satisfying property \ref{itm:decomp}, and prove
in \ref{lma4:IEtoDE5} that $M$ satisfies property \ref{itm:jost}\textemdash{}that is,
$M$ weakly solves \eqref{eq4:LinSpecProb}.

\begin{lma}\label{lma4:upperasymp}
	Suppose then $M^+$ satisfies Definition \ref{dfn4:IEsoln} and denote by $M$
	the analytic continuation of $M^+$ to the complex strip $\mathcal S_1$. The
	upper boundary value $M^-$ of $M$ satisfies asymptotic condition (b) of
	property \ref{itm:asymp} from Definition \ref{dfn4:DEsoln}. That is, there
	exist $M_1$, $M_2$ so that
	\[
		M^-(x) -1 = M_1(x) + M_2(x),
	\]
	where
	\[
		\inn{x}^{1+\upsilon} | M_1(x) | \lesssim 1
	\]
	as $x\to -\infty$ and
	\[
		\inn{\dotarg}^\tau M_2 \in L^2(\mathbb R)
	\]
	for any $\upsilon \in (0,1]$ and $\tau \in [0,1)$.
\end{lma}
\begin{proof}
	Recall from Equation \eqref{eq3:GLminus} of Theorem \ref{eq3:GstarMinus} in
	Section \ref{sec3:Intro} that
	\begin{align*}
		M^-(x) - 1
			&= G_L(\dotarg; \lambda)^- * \big[u\,M^+\big](x) \\
			&=
				\bigg[
					\mathfrak C(\dotarg, 2) + \mathpzc R_L(\dotarg+i2; \lambda)
				\bigg]
				*
				\big[u\,M^+\big](x)
				+
				\left[E - \frac{1}{2}\right]\big[u\,M^+\big](x)
	\end{align*}
	Define
	\begin{align*}
		I_1(x;\lambda) &:= \mathfrak C(\dotarg, 2) * \big[u\,M^+\big](x) \\
		I_2(x;\lambda) &:= \mathpzc R_L(\dotarg+i2; \lambda) * \big[u\,M^+\big](x) \\
		I_3(x;\lambda) &:= \left[E - \frac{1}{2}\right]\big[u\,M^+\big](x),
	\end{align*}
	and set
	\begin{align*}
		M_1(x;\lambda) :=  I_1(x;\lambda) + I_2(x;\lambda),
			\qquad\text{and}\qquad
		M_2(x;\lambda) := \left[E - \frac{1}{2}\right]\big[u\,M^+\big](x).
	\end{align*}

	A result of Fefferman-Stein from the theory of Calder\'on-Zygmund operators
	with Muckenhaupt $A_p$ weights holds that Calder\'on-Zygmund operators are
	bounded between $L^p(\omega \,dx)$ if $1 < p < \infty $ and $\omega \in A_p$.
	Since $|\dotarg|^\iota$ is an $A_2$-weight in $\mathbb R^1$ for any
	$\iota\in [0, 1)$ and the exponentially weighted Hilbert trasnform is a
	Calder\'on-Zygmund operator, we have that
	\[
		\int_{\mathbb R} (1+|x|)^{2\iota} \left|(Ef)(x)\right|^2 \, \mathrm{d}x
			\lesssim_{\iota}
				\int_{\mathbb R}(1+|x|)^{2\iota} |f(x)|^2 \, \mathrm{d}x
	\]
	for any $\iota \in [0, 1)$. Hence, since $u\in L^{2,4}(\mathbb R)$ implies
	$u\,M^+ \in L^{2,\tau}(\mathbb R)$ for $\tau \in [0, 3]$, we conclude
	that $E(uM^+) \in L^{2, \tau}(\mathbb R)$ and thus $M_2 \in L^{2,\tau}(\mathbb R)$
	for $\tau \in [0, 1)$.

	Since
	\[
		\mathfrak C(x, 2)
			= \frac{e^{-\pi|x|}}{2\pi}	\
				\int_{\mathbb R} e^{ix\xi} \rho\big(\xi, 2, \sign(x)\big) \, \mathrm{d}x,
	\]
	where $\rho$ is absolutely integrable in $\xi$, it is easy to see that
	$\mathfrak C(\dotarg, 2)$ is bounded by a Schwartz class function. As such,
	a simple application of Dominated Convergence implies
	$\inn{x}^{1+\upsilon} I_1(x; \lambda) \to 0$ as $x\to -\infty$ for each
	$\lambda \in \mathbb R$.

	For $I_2$, we note that $\mathpzc R_L$ grows linearly only when $\lambda=0$
	and is otherwise bounded. As such, we verify that
	$\inn{x}^{1+\upsilon} I_2(x; \lambda =0)$ is bounded for $\upsilon \in (0,1]$
	and $x < 0$ and note that the corresponding result for $\lambda \ne 0$ follows.
	Now
	\begin{align*}
		I_2(x; \lambda=0)
			=
				\int_{-\infty}^x
					\left(i\frac{2}{3} - (x - x')\right) u(x')\,M^+(x')
				\,dx.
	\end{align*}
	Assuming $x < 0$, then $\inn{x'} \geq \inn{x}$, $\inn{x}^{-1} \geq \inn{x'}^{-1}$, and
	\[
		\inn{x-x'} \leq \inn{x} + \inn{x'} \lesssim \inn{x'}
	\]
	whenever $x' \leq x$.
	Consequently,
	\begin{align*}
		|I_2(x; \lambda = 0)|
			&\lesssim \int_{-\infty}^x \inn{x - x'} |u(x')| \left|M^+(x')\right| \, \mathrm{d}x'
				\\
			&\lesssim
				\inn{x}^{-1-\upsilon}
				\int_{-\infty}^x
					\inn{x'}^{2+\upsilon} |u(x')| \inn{x'}
					\left(\inn{x'}^{-1} \left|M^+(x')\right| \right)
				\, \mathrm{d}x'
				\\
			&\lesssim
				\inn{x}^{-1-\upsilon}
				\nm{M^+}_{\inn{\dotarg}L^\infty} \
				\nm{u}_{\inn{\dotarg}^{3+\upsilon}L^1},
	\end{align*}
	where $\nm{u}_{\inn{\dotarg}^{3+\upsilon}L^1}<\infty$ as
	\begin{align*}
		\nm{u}_{\inn{\dotarg}^{3+\upsilon}L^1}
			=
				\left|
					\int_{\mathbb R}
						\inn{x}^{-1+\upsilon}\inn{x}^{4} u(x)
					\, \mathrm{d}x
				\right|
			\leq
				\nm{\inn{\dotarg}^{-1+\upsilon}}_{L^2}
				\nm{\inn{\dotarg}^{4} u}_{L^2},
	\end{align*}
	and $-1+\upsilon < -\frac{1}{2}$ implies
	$\inn{\dotarg}^{-1+\upsilon} \in L^2(\mathbb R)$. It therefore follows that
	$\inn{x}^{1+\upsilon} |M_1(x)| \lesssim 1$ for $x < 0$.
\end{proof}

\begin{lma}\label{lma4:IEtoDE4}
	Suppose then $M^+$ satisfies Definition \ref{dfn4:IEsoln}. Then
	its analytic continuation $M$ to the complex strip $\mathcal S_1$
	satisfies property \ref{itm:decomp} of Definition \ref{dfn4:DEsoln}.
	That is, there is a decomposition $M(z) = M_c(z) + M_s(z)$ for
	$0 < \im  z < 2$ so that
	\begin{itemize}
		\item[(a)] $M_c$ extends to a continuous function on the closure
			$\ol{\mathcal S}_1$ of $\mathcal S_1$ with
			\[
				\mathop{\lim_{x\to-\infty}}_{x\in \mathbb R} M_c(x+2i) = 1
			\]
		\item[(b)] The estimates
			\[
				\|M_s(\dotarg+iy)\|_{L^\infty} \leq (2-y)^{-1/2}, \qquad
				\sup_{0\leq y < 2} \|M_s(\dotarg+iy)\|_{L^2} < \infty
			\]
			hold. Moreover, $M_s$ has an $L^2$ boundary value
			$M_s^-(x):= \lim_{\varepsilon \searrow 0} M_s\big(\dotarg+i(2-\varepsilon)\big)$
			on $\im z = 2$ with $M_s(x+iy) \to M_s^-(x)$ for almost every
			$x$.
	\end{itemize}
\end{lma}
\begin{proof}
	Recalling the discussion following Theorem \ref{thm3:main_result},
	we note that
	\begin{align*}
		M(z) = M_c(z) + M_s(z),
	\end{align*}
	where
	\begin{align*}
		M_c(x+iy)
			:= 1
				+
				\big[
					\mathfrak C(\dotarg, y) + \mathpzc R_L(\dotarg+iy; \lambda)
				\big]
				*
				\big[u\,M^+\big](x)
	\end{align*}
	and
	\begin{align*}
		M_s(x+iy)
			:= \mathcal E_{2-y} \big[u\,M^+\big](x).
	\end{align*}
	That $M_c(x+i2)$ is continous for $x \in \mathbb R$ follows from our work in
	Sections \ref{sec3:Analyticity} and \ref{sec3:ContPart}. Further,
	since $\mathfrak C(x, 2)$ is bounded by Schwartz class function, it is easy
	to show through direct computation that
	$\mathfrak C(\dotarg, 2) * [u\,M^+](x) \to 0$ as $|x| \to \infty$.
	By following the proof of Proposition \ref{prop2:Tasymp}, one can
	also easily show that $\mathpzc R_L(\dotarg + i2; \lambda) * [u\,M^+] \to 0$
	as $x \to -\infty$ for every real $\lambda$, which implies $M_c(x+i2) \to 1$ as
	$x \to - \infty$. Lastly, the convergence of $M_r(x+iy)$ to $M_r^-(x)$ and the
	estimates on $\|M_s(\dotarg+iy)\|_{L^\infty}$ and
	$\sup_{0\leq y < 2} \|M_s(\dotarg+iy)\|_{L^2}$ are all consequences of our
	analyses in Sections \ref{sec3:CauchyTrans} and \ref{sec3:BndE}.
\end{proof}

\begin{lma}\label{lma4:IEtoDE5}
	The analytic continuation $M$ of
	a solution $M^+$ of integral equation form of the linear spectral problem
	as defined by Definition \ref{dfn4:IEsoln} also satisfies property \ref{itm:jost}
	of Definition \ref{dfn4:DEsoln} and is therefore a Jost solution.
\end{lma}
\begin{proof}
	%%====================================================================
	%% Begin direct thievery (with modification) from Prof. Perry's notes.
	%% Rewrite this section later.
	%%====================================================================
	To prove that the solution $M$ of \eqref{dfn4:IEsoln} solves
	\eqref{eq4:LinSpecProb} in the sense of Definition \ref{dfn4:DEsoln} we
	first consider the case $u \in C_0^\infty(\mathbb R)$. It is not difficult to
	see that if $u \in C_0^\infty(\mathbb R)$, $M$ is also $C^\infty$. By Laurent
	Schwartz's formulation of the Paley-Wiener Theorem \cite{Schwartz1952}, the
	function $\widehat{u\,M^+}$ is entire and rapidly decaying in $\xi$ for
	$\im \xi$ bounded. Thus we may compute
	\[
		M^+(x) - 1
			= \int_{\Gamma_L} \frac{e^{i\xi x}}{p(\xi)} \wh{u\,M^+}(\xi) \, \mathrm{d}\xi
	\]
	where the right-hand side makes sense owing to the analyticity of $\wh{uM}$.
	We also have
	\[
		M(x+iy) - 1
			=
				\int_{\Gamma_L}
					\frac{e^{i\xi x} e^{-y\xi}}{p(\xi)} \wh{u\,M^+}(\xi)
				\, \mathrm{d}\xi
	\]
	from which it follows that
	\[
		\frac{1}{i} \frac{\partial M^+}{\partial x}(x)  - \zeta(M^+(x) - M^-(x))
			=	\int_{\Gamma_L} e^{i\xi x} \wh{u\,M^+}(\xi) \, \mathrm{d}\xi
			= u(x) M^+(x)
	\]
	for each $x$, where we used analyticity of $\widehat{u\,M^+}$ to deform the
	contour from $\Gamma_L$ to $\mathbb R$.

	Now let $u \in X$ and let $\{ u_n \}$ be a sequence from $C_0^\infty(\mathbb R)$
	with $u_n \to u$ in $X$. Let $M_n$ be the corresponding solution of
	\eqref{eq4:MPluseq} for $u=u_n$. For any $\varphi \in C_0^\infty(\mathbb R)$ we have
	\begin{align}\label{eq4:Mnweak}
		\frac{1}{i} \inn{\varphi', \, M^+_n} - \zeta \inn{\varphi,\,M_n^+ - M_n^-}
			- \inn{\varphi, \, u_n M^+_n} = 0.
	\end{align}
	As $u_n \to u$ in $X$ it follows that $M_n \to M$ in $L^\infty$, hence
	$u_n M_n \to uM$ in $L^{1,2}$. To show that $M$ is a weak solution,
	that is, $M$ satisfies \eqref{eq4:Mnweak}, it
	suffices to show that for any $\varphi \in C_0^\infty(\mathbb R)$,  the
	differences
	\[
		\inn{\varphi', \, M^+-M^+_n}, \quad
		\inn{\varphi, \, (M^\pm - M_n^\pm)}, \quad
		\inn{\varphi, \, u\,M^+ - u_n\,M_n^+}
	\]
	all converge to zero as $n \to \infty$.
	Note that
	\begin{align*}
		\left|\inn{\varphi', \, M^+-M^+_n}\right|
			&= \left|\int_{\mathbb R} \phi'\big(M^+ - M_n^+\big) \, \mathrm{d}x \right| \\
			&\leq \nm{M^+ - M_n^+}_{\inn{\dotarg}L^\infty} \nm{\inn{\dotarg}\phi'}_{L^1}.
	\end{align*}
	Since $\phi' \in C_0^\infty$ implies $\nm{\inn{\dotarg}\phi'}_{L^1}$ and the map
	$B_X(0, c_0) \ni u \mapsto M\in\inn{\dotarg}L^\infty(\mathbb R)$ is Lipschitz
	by Lemma \ref{lma4:cont}, it follows that
	\[
		\lim_{n\to\infty} \inn{\varphi', \, M^+-M^+_n} = 0.
	\]
	A similar argument also shows that
	\[
		\lim_{n\to\infty} \inn{\varphi, \, (M^+ - M_n^+)}= 0
	\]
	The Lipschitz continuity of the map
	$B_X(0, c_0) \ni u \mapsto u\,M \in L^1(\mathbb R)$ (Lemma \ref{prop4:uMcont})
	in conjunction with the fact that $\phi$ is bounded again implies
	\[
		\lim_{n\to\infty} \inn{\varphi, \, u\,M^+ - u_n\,M_n^+} = 0.
	\]

	To prove $\inn{\varphi, \, (M^- - M_n^-)} \to 0$ as $n \to \infty$, we
	recall that

	\[
		\big[M^-(x;\lambda)- M_n^-(x;\lambda)\big]
			= \left[M^-_c(x;\lambda) - \left( M_n^- \right)_c(x;\lambda)\right]
				+ \left[M^-_s(x;\lambda) - \left( M_n^- \right)_s(x;\lambda)\right]
	\]
	where
	\begin{align}
		 M^-_c(x;\lambda) - \left( M_n^- \right)_c(x;\lambda)
			=
				\big[
					\mathfrak C(\dotarg, 2) + \mathpzc R_L(\dotarg+i2, \lambda)
				\big]
				*
				\big[u\,M^+ - u_n\,M_n^+](x)
	\end{align}
	and
	\begin{align}\label{ILW.Mnr}
		 &M^-_s(x;\lambda) - \left( M_n^- \right)_s(x;\lambda) \\
			&\qquad=
				E\big[u\,M^+(\dotarg;\lambda)- u_n\,M_n^+(\dotarg;\lambda)\big](x)
				- \frac{1}{2} \big[u\,M^+(x;\lambda)- u_n\,M_n^+(x;\lambda)\big]
	\end{align}
	Hence, using the fact that $\phi \in C_0^\infty(\mathbb R)$ implies
	$\inn{\dotarg} \phi \in L^1$ and estimate \eqref{eq3:tlma2} from
	Technical Lemma \ref{tlma2:1} we find for all $\lambda \in \mathbb R$
	\begin{align*}
		\inn{\phi, \, M^-_c - \left( M_n^- \right)_c }
			&\leq \nm{\inn{\dotarg} \phi }_{L^1}
				\nm{M^-_c - \left( M_n^- \right)_c}_{\inn{\dotarg} L^\infty}
				\\
			&\leq \nm{\inn{\dotarg} \phi }_{L^1}
				\nm{M^+ - M_n^+}_{L^{1,1}}
				\nm{\mathfrak C(\dotarg, 2) + \mathpzc R_L(\dotarg + i2)}_{\inn{\dotarg}L^\infty}
	\end{align*}
	Again appealing to Lemma \ref{prop4:uMcont} we conclude,
	\begin{align*}
		\lim_{n\to\infty} \inn{\phi, \, M^-_c - \left( M_n^- \right)_c } = 0.
	\end{align*}
	Lastly, to prove
	\begin{align*}
		\lim_{n\to\infty} \inn{\phi, \, M^-_s - \left( M_n^- \right)_s}
			= 0,
	\end{align*}
	we can use the $\inn{\dotarg} L^\infty$ convergence of $M_n^+$ to $M^+$, the $X$-convergence
	of $u_n$ to $u$, and dominated convergence to show that the right-hand side of
	\eqref{ILW.Mnr} goes to zero in $L^2$ as $n \to \infty$, and, by passing to a
	subsequence, goes to zero almost everywhere.
\end{proof}

\label{lastpagePenultimateSection}

\end{document}


\subsubsection{Default Curves from CDS}

Default curves can be bootstrapped from credit default swap (CDS) market instruments. The CDS market quotes may be given as a par spread or as an upfront price. These market quotes are documented in Sections \ref{md:cds_spread_quote} and \ref{md:cds_price_quote} respectively. The bootstrap also requires a market recovery rate quote and this is documented in Section \ref{md:cds_recovery_rate_quote}.

Listing \ref{lst:defaultcurve_cds_configuration} outlines the configuration required to build a default curve from CDS quotes. The meaning of each of the nodes is as follows:

\begin{itemize}
\item
\lstinline!CurveId!: Unique identifier for the bootstrapped default curve.

\item \lstinline!CurveDescription! [Optional]:
A description of the default curve. It is for information only and may be left blank.

\item \lstinline!Currency!:
The default curve's currency.

\item \lstinline!Type!:
For a default curve built from CDS, the \lstinline!Type! should be set to \lstinline!SpreadCDS! if the \lstinline!Quotes! reference CDS spread quotes or \lstinline!Price! if the \lstinline!Quotes! reference upfront price quotes.

\item \lstinline!DiscountCurve!:
A reference to a valid discount curve specification that will be used to discount cashflows during the bootstrap process. It should be of the form \lstinline!Yield/Currency/curve_name! where \lstinline!curve_name! is the name of a yield curve defined in the yield curve configurations.

\item \lstinline!DayCounter!:
The day counter used to convert from dates to times in the underlying structure. Allowable values are given in the Table \ref{tab:daycount}.

\item \lstinline!RecoveryRate!:
A valid recovery rate quote name as documented in Section \ref{md:cds_recovery_rate_quote}.

\item \lstinline!StartDate! [Optional]:
The \lstinline!StartDate! is optional and is used for index CDS to specify the start date of the index CDS. This is then used to determine the maturity associated with the index CDS spread quotes which are quoted with a tenor. For single name CDS, this should be omitted.

\item \lstinline!Quotes!:
The \lstinline!Quotes! element should be populated with a list of valid \lstinline!Quote! elements. If the \lstinline!Type! is \lstinline!SpreadCDS!, the quotes should be CDS spread quote strings as documented in Section \ref{md:cds_spread_quote} and if \lstinline!Type! is \lstinline!Price!, the quotes should be CDS upfront price quote strings as documented in Section \ref{md:cds_price_quote}. The attribute \lstinline!optional! in the \lstinline!Quote! element should be set to \lstinline!true! if the associated quote is optional and set to \lstinline!false! if the associated quote is mandatory. If a quote is mandatory and not found in the market, the default curve building will fail. The attribute \lstinline!optional! may be omitted from the quote element. In this case, it defaults to \lstinline!false! and the quote is mandatory. Note also that instead of a list of explicit quotes, a single quote may be provided with the wildcard character \lstinline!*!. In this case, the market is searched for quotes matching the pattern. For example, \lstinline!CDS/CREDIT_SPREAD/JPM/SNRFOR/USD/XR14/*! would return all quotes in the market that start with \lstinline!CDS/CREDIT_SPREAD/JPM/SNRFOR/USD/XR14!.

\item \lstinline!Conventions!:
The name of a valid set of CDS conventions, as documented in Section \ref{sss:cds_conventions}, to use in the bootstrap.

\item \lstinline!Extrapolation! [Optional]:
A boolean value indicating if the bootstrapped default curve allows for extrapolation past the last pillar date. Allowable boolean values are given in the Table \ref{tab:boolean_allowable}. If omitted, it defaults to \lstinline!true!.

\item \lstinline!ImplyDefaultFromMarket! [Optional]:
A boolean value indicating if a reference entity's default should be implied from the market data. Allowable boolean values are given in the Table \ref{tab:boolean_allowable}. If omitted, it defaults to \lstinline!false!. When a default credit event has been determined for an entity, certain market data providers continue to supply a recovery rate from the credit event determination date up to the credit event auction settlement date. In this period, no CDS spreads or upfront prices are provided. When this flag is \lstinline!true!, we assume an entity is in default and awaiting a credit event auction if we find a recovery rate in the market but no CDS spreads or upfront prices. In this case, we build a survival probability curve with a value of close to but greater than 0.0 for one day after the valuation date. This will give an approximation to the correct price for CDS and index CDS in these cases. When this flag is \lstinline!false!, we make no such assumption and the default curve building will fail.

\item \lstinline!BootstrapConfig! [Optional]:
This node holds configuration details for the iterative bootstrap that are described in section \ref{sec:bootstrap_config}. If omitted, this node's default values described in section \ref{sec:bootstrap_config} are used.

\item AllowNegativeRates [Optional]: If set to false (default) negative instantaneous hazard rates implied by the CDS
  quotes lead to an exception or - if the DontThrow flag in the BootstrapConfig is set to true - to a zero instantaneous
  hazard rate in the relevant segment of the curve. In the latter case the market CDS instrument associated to the
  critical curve segment will not match the market quote exactly. If set to true, negative instantaneous hazard rates
  will be allowed during the bootstrap (in a range that is technically defined by the MaxFactor and MaxAttempts
  parameters for the survival probability in the bootstrap config).

\end{itemize}

\begin{longlisting}
%\hrule\medskip
\begin{minted}[fontsize=\footnotesize]{xml}
<DefaultCurve>
  <CurveId>...</CurveId>
  <CurveDescription>...</CurveDescription>
  <Currency>USD</Currency>
  <Type>...</Type>
  <DiscountCurve>...</DiscountCurve>
  <DayCounter>...</DayCounter>
  <RecoveryRate>...</RecoveryRate>
  <StartDate>...</StartDate>
  <Quotes>
    <Quote optional="true">...</Quote>
    ...
  </Quotes>
  <Conventions>...</Conventions>
  <Extrapolation>...</Extrapolation>
  <ImplyDefaultFromMarket>...</ImplyDefaultFromMarket>
  <BootstrapConfig>
    ...
  </BootstrapConfig>
  <AllowNegativeRates>...</AllowNegativeRates>
</DefaultCurve>
\end{minted}
\caption{Default curve configuration based on CDS quotes}
\label{lst:defaultcurve_cds_configuration}
\end{longlisting}


\documentclass{article}

\usepackage{amsmath}
\usepackage{graphicx}
\usepackage{multicol}
\usepackage{color}
\usepackage{comment}
\usepackage{makeidx}
\usepackage{hyperref}
\oddsidemargin 0cm
\evensidemargin 0cm

\textwidth 16.5cm
\topmargin -2.0cm
\parindent 0cm
\textheight 24cm
\parskip 0.5cm

\usepackage{fancyhdr}
\pagestyle{fancy}
\fancyhf{}
%\fancyhead[L]{AOSS Reference Sheet}
%\fancyhead[CH]{test}
\fancyfoot[C]{Page \thepage}

\newcommand{\vb}{\mathbf}
\newcommand{\vg}{\boldsymbol}
\newcommand{\mat}{\mathsf}
\newcommand{\diff}[2]{\frac{d #1}{d #2}}
\newcommand{\diffsq}[2]{\frac{d^2 #1}{{d #2}^2}}
\newcommand{\pdiff}[2]{\frac{\partial #1}{\partial #2}}
\newcommand{\pdiffsq}[2]{\frac{\partial^2 #1}{{\partial #2}^2}}
\newcommand{\topic}{\textbf}
\newcommand{\arccot}{\mathrm{arccot}}
\newcommand{\arcsinh}{\mathrm{arcsinh}}
\newcommand{\arccosh}{\mathrm{arccosh}}
\newcommand{\arctanh}{\mathrm{arctanh}}

\makeindex

\begin{document}

{\Huge \textbf{TempestExtremes}}

\tableofcontents

\section{Setting up TempestExtremes}

All of the necessary source files for compiling TempestExtremes can be found at the GitHub repository \url{https://github.com/ClimateGlobalChange/tempestextremes}. Users can either download a zip file and extract it into the directory of choice (here denoted as \texttt{\$USER\_DIR}) or

\texttt{git clone https://github.com/ClimateGlobalChange/tempestextremes}

into \texttt{\$USER\_DIR}.

Once the directory has been set up, simply use the \texttt{make} command in the base directory (\texttt{\$USER\_DIR/tempestextremes/}) and it will compile all of the necessary binaries.

\section{Objective blocking detection methods}

There are two main methods for block detection: the Z500 gradient method of Tibaldi and Molteni 1990 (hereafter referred to as TM90), and anomaly-based methods such as that of Dole and Gordon 1983 (Z500 anomaly, DG83) or Schwierz et al 2004 (potential vorticity anomaly, S04).

\paragraph{Geopotential height gradient (TM90)} Two slopes are calculated around a single gridpoint:\index{Tibaldi and Molteni 1990}

\begin{eqnarray}
GHGN=\frac{Z(\phi_n)-Z(\phi_0)}{\phi_n-\phi_0}\\
GHGS=\frac{Z(\phi_0)-Z(\phi_s)}{\phi_0-\phi_s}
\end{eqnarray}

\noindent where $\phi_0$, $\phi_n$, and $\phi_s$ are the reference latitude and the latitudes 15$^\circ$ poleward and equatorward of $\phi_0$, respectively, and $GHGN$ and $GHGS$ are the height gradients. For $GHGN<-10$ m/deg lat and $GHGS>0$ m/deg lat, the point is considered instantaneously blocked.

This is a modification of the original TM90 algorithm, which was calculated for all longitude values about a single predetermined latitude. Scherrer et al 2006 and others expanded the definition to encompass all latitudes 35-75 degrees in both hemispheres.

\paragraph{Anomaly methods (S04 and DG83)} Each anomaly method has a general workflow that can be described as follows:

\begin{enumerate}
\item If doing S04: Generate the input files using \texttt{BlockingPV}.
\item Calculate the long term daily average, using \texttt{BlockingDFT} (Section \ref{avg})
\item Calculate the anomalies from the long term daily average, using \texttt{BlockingDevs} (Section \ref{dev})
\item (If using a non-constant threshold) Calculate the long term daily average of the anomalies using \texttt{BlockingDFT} for use in the threshold calculations, then calculate a spatiotemporally varying threshold variable using \texttt{BlockingThresh}
\item Calculate the normalized anomalies using \texttt{BlockingNormDevs}
\end{enumerate}

\textit{Potential Vorticity anomaly:} S04 uses vertically averaged (150-500 hPa) potential vorticity as the variable of choice for block detection. The presence of negative (positive) anomalies in the Northern (Southern) Hemisphere denotes either a slowing or reversal of the flow with respect to the climatological mean. \index{Schwierz et al 2004}

\textit{Z500 anomaly:} DG83 uses 500 hPa geopotential height (Z500) anomaly as the variable of choice for block detection. The anomaly signifies heights that exceed a threshold above a climatological mean.\index{Dole and Gordon 1983}

All of the initial blocking code can be found in the \texttt{src/blocking/} directory.

\subsection{Blocking Event Detection: The StitchBlobs Framework} \index{StitchBlobs}\index{BlobStats}

StitchBlobs is a standardized framework for identifying persistent events (in this case, blocking). Clusters of grid points that meet minimum spatial constraints (if specified) and overlap over time are defined as individual events and tagged with unique identifiers. The corresponding BlobStats program reads in the StitchBlobs output and provides a text file with per-timestep information on size(in terms of maximum latitude/longitude extent or area) and location (in terms of the cluster centroid's latitude/longitude position). This allows the user to track events from start to finish and and examine trends in the event's spatial characteristics.

There are options to provide constraints in terms of the study region (specifying minimum and maximum latitude and longitude values), cluster size, and minimum duration (in terms of number of timesteps).

\subsection{General workflow}

The following sections explain the various command line parameters that control the program inputs and outputs. Parameters with an asterisk (\texttt{*}) are mandatory and will raise an exception if not included. Parameters with multiple asterisks (\texttt{**}), such as \texttt{--in} and \texttt{inlist}, are also mandatory, but only one of the two should be used; if both are used, the program will raise an exception. If there is a default value, it is included in brackets (\texttt{["string"]}); otherwise, the quotation marks indicate a default empty string (\texttt{[""]}).

Flags such as \texttt{--latname} are only necessary if the variable names differ from the default. These optional flags are marked with a plus (\texttt{+}) and are explained in Section \ref{option}.

\textbf{Example: Calculating vertically averaged PV anomalies with a non-constant threshold:} This example assumes a dataset with default axes \texttt{[time, lev, lat, lon]} with the \texttt{lev} axis initially in units of hPa.

\begin{enumerate}
\item Calculate vertically averaged PV from a list of input files, \texttt{inPV.txt}: \\
\texttt{\$USER\_DIR/tempestextremes/bin/BlockingPV --hpa --inlist inPV.txt }
\item Calculate the LTDM from a list of vertically averaged PV files, \texttt{VPV.txt}: \\
\texttt{\$USER\_DIR/tempestextremes/bin/BlockingDFT  --inlist VPV.txt --out avgPV.nc --varname VPV --avgname AVPV }
\item Calculate PV anomalies from the LTDM using list \texttt{VPV.txt}:\\
 \texttt{\$USER\_DIR/tempestextremes/bin/BlockingDevs --inlist VAPV.txt --avg avgPV.nc --avgname AVPV --varname VPV --pv}
\item Calculate the LTDM of anomalies from a list of anomaly files, \texttt{ADVPV.txt} and using the smoothed anomaly, \texttt{ADVPV}:\\
\texttt{\$USER\_DIR/tempestextremes/bin/BlockingDFT --inlist ADVPV.txt --out avgADVPV.nc --varname ADVPV --avgname AVG\_ADVPV}
\item Calculate a spatiotemporally varying threshold for the normalized anomalies calculation using \texttt{ADVPV.txt} and the averaged anomalies file: \\
\texttt{\$USER\_DIR/tempestextremes/bin/BlockingThresh --inlist ADVPV.txt --outfile PVthresh.nc --davgfile avgADVPV.nc --davgname AVG\_ADVPV --dvarname ADVPV}
\item Calculate normalized anomalies using the threshold file \texttt{PVthresh.nc} and list \texttt{ADVPV.txt}:\\
\texttt{\$USER\_DIR/tempestextremes/bin/BlockingNormDevs --inlist ADVPV.txt --varname ADVPV --thresh PVthresh.nc --threshname THRESHOLD\_DFT --pv}
\end{enumerate}

\textbf{Example: Calculating 500 hPa geopotential height anomalies with a constant threshold:} This example assumes a dataset with default axes \texttt{[time, lev, lat, lon]} with the \texttt{lev} axis initially in units of hPa and geopotential (\texttt{GEOPOTENTIAL}), rather than geopotential height, as the input variable.

\begin{enumerate}
\item Calculate the LTDM from a list of input files, \texttt{fList.txt}, noting that the input has 4 axes rather than the default 3 and the variable is geopotential: \\
\texttt{\$USER\_DIR/tempestextremes/bin/BlockingDFT  --inlist fLIst.txt --out avgZ500.nc --varname GEOPOTENTIAL--avgname AZ500 --hpa --is4D --gh}
\item Calculate Z500 anomalies from the LTDM using list \texttt{fList.txt}:\\
 \texttt{\$USER\_DIR/tempestextremes/bin/BlockingDevs --inlist fList.txt --avg avgZ500.nc --avgname AZ500 --varname GEOPOTENTIAL --z500 --hpa --gh --is4D}
\item Calculate normalized anomalies
\end{enumerate}

\subsection{BlockingGHG}\label{ghg}

\begin{verbatim}
Usage: BlockingGHG <parameter list>
Parameters:
  --in <string> [""] **
  --inlist <string>  [""] **
  --varname <string> ["Z"]
  --tname <string> ["time"] +
  --latname <string> ["lat"] +
  --lonname <string> ["lon"] +
  --insuff <string> [".nc"] +
  --outsuff <string> ["_GHG.nc"] +
  --gh +
  --hpa +
  --is4D +
\end{verbatim}

\begin{itemize}
\item[]\texttt{--in <string>} \\ input file in NetCDF format, with axes \texttt{[time, latitude, longitude]}.
\item[]\texttt{--inlist <string>}\\ list of input datafiles (one file per line) in NetCDF format, with axes \texttt{[time, latitude, longitude]}.
\item[] \texttt{--varname <string>}\\ name of Z500 variable (default \texttt{Z}).
\end{itemize}

** Do not use both \texttt{--in} and \texttt{--inlist} flags simultaneously.

\subsubsection{File input and output}

This program takes each input file containing the Z500 variable (specified by the \texttt{--varname} flag if name is not default \texttt{Z}) and outputs a file (original file name plus output suffix), containing the variable \texttt{ZG}, which has a value of either 1 (gridpoint is instantaneously blocked) or 0 (not blocked). Use the additional boolean flags (explained in Section \ref{option}) as necessary.

\subsection{Anomalies, Step 1 (S04): Input files: BlockingPV}\label{PV}
\begin{verbatim}
Usage: BlockingPV <parameter list>
Parameters:
  --in <string> [""] **
  --in2d <string> [""]
  --inlist <string>  [""] **
  --inlist2d <string> [""]
  --hasPV
  --ipl +
  --hpa +
  --PVname <string> ["PV"] +
  --VPVname <string> ["VPV"] +
  --uname <string> ["U"] +
  --vname <string> ["V"] +
  --tempname <string> ["T"] +
  --tname <string> ["time"] +
  --levname <string> ["lev"] +
  --latname <string> ["lat"] +
  --lonname <string> ["lon"] +
  --insuff <string> [".nc"] +
  --outsuff <string> ["_integ.nc"] +
  --insuff2d <string> [".nc"] +
  --outsuff2d <string> ["_ipl.nc"] +
\end{verbatim}

\begin{itemize}
\item[]\texttt{--in <string>} \\ Input file in NetCDF format containing temperature and wind variables, with axes \texttt{[time, lev, lat, lon]}
\item[]\texttt{--in2d <string>} \\ Optional input file in NetCDF format containing surface pressure, with axes \texttt{[time, lat, lon]}. Only necessary if input file's vertical axis is on model levels.
\item[]\texttt{--inlist <string>} \\ A list of input datafiles in NetCDF format containing temperature and wind variables, with axes \texttt{[time, lev, lat, lon]}
\item[]\texttt{--inlist2d <string>} \\ Optional list of input datafiles in NetCDF format containing surface pressure, with axes \texttt{[time, lat, lon]}. Only necessary if input files' vertical axis is on model levels.
\item[]\texttt{--hasPV} \\ Optional bool that tells program that PV variable is already present, and only vertically averaged PV needs to be calculated.
\end{itemize}

** Do not use both \texttt{--in} and \texttt{--inlist} flags simultaneously.

\subsubsection{File input and output}

This program produces vertically averaged (150-500 hPa) potential vorticity for use in S04. Without the \texttt{--hasPV flag}, this program takes input files containing temperature (\texttt{T}) and zonal (\texttt{U}) and meridional (\texttt{V}) winds and outputs files  (original file name plus suffix \texttt{\_integ.nc}) with both potential vorticity (\texttt{PV}) and vertically averaged potential vorticity (\texttt{VPV}).

If potential vorticity variable is already present in the input file,  use the \texttt{--hasPV} flag (with optional \texttt{--PVname} flag if name of variable differs from the default) and the program will output new files (original file name plus suffix \texttt{\_integ.nc}) containing the vertically averaged \texttt{IPV} variable.

Input files should have a vertical axis on pressure levels. If the vertical axis is on model levels, use the \texttt{--ipl} flag, as well as input surface pressure files (\texttt{--in2d} or \texttt{--inlist2d}) to first interpolate variables to pressure levels. If the pressure levels are in units of hPa (or mb), use the \texttt{--hpa} flag to inform the program that the units need to be converted.

\subsection{Anomalies, Step 2: Long Term Daily Mean: BlockingDFT}\label{avg}
\begin{verbatim}
Usage: BlockingDFT <parameter list>
Parameters:
  --inlist <string>  [""] *
  --out <string>  [""] *
  --varname<string>  [""] *
  --avgname <string>  [""] *
  --ncoef <integer>  [12]
  --is4D +
  --gh +
  --hpa +
  --tname <string> ["time"] +
  --levname <string> ["lev"] +
  --latname <string> ["lat"] +
  --lonname <string> ["lon"] +
\end{verbatim}

\begin{itemize}
\item[]\texttt{--inlist <string>} \\ A list of input datafiles in NetCDF format containing variables that will be averaged, with axes \texttt{[time, lat, lon]} (if axes are \texttt{[time, lev, lat, lon] } then use boolean flag \texttt{--is4D})
\item[]\texttt{--out <string>} \\ Name of output file
\item[]\texttt{--varname <string>} \\ Name of input variable
\item[]\texttt{--avgname <string>} \\ Name of output average variable
\item[]\texttt{--ncoef <integer>} \\ Number of coefficients used in Fourier transform (default is 12)
\end{itemize}

\subsubsection{File input and output}
This program takes a list of files and computes the mean field for each of the 365 days in a year (excluding leap days). The values for these days are Fourier transformed and then back transformed using the specified number of coefficients, producing a long term daily mean which has been smoothed.

The program outputs a file that contains the averaged variable with axes \texttt{[time, lat, lon]}. The time axis has 365 time steps, each representing a day in the year. The time axis has units of ``days since 0001-01-01''.

\subsection{Anomalies, Step 3: Unsmoothed and Smoothed Anomalies: BlockingDevs}\label{dev}
\begin{verbatim}
Usage: BlockingDevs <parameter list>
Parameters:
  --in <string> [""] **
  --inlist <string>  [""] **
  --out <string> [""] ***
  --avg <string> [""] *
  --avgname <string> [""] *
  --varname <string> [""] *
  --pv
  --z500
  --is4D +
  --gh +
  --hpa +
  --tname <string> ["time"] +
  --levname <string> ["lev"] +
  --latname <string> ["lat"] +
  --lonname <string> ["lon"] +
\end{verbatim}

\begin{itemize}
\item[]\texttt{--in <string>}\\ Name of input datafile in NetCDF format.
\item[]\texttt{--inlist <string>} \\ A list of input datafiles in NetCDF format.
\item[] \texttt{--avg <string>}\\ The name of the long term daily average file
\item[]\texttt{--avgname <string>}\\Name of input long term daily average variable.
\item[] \texttt{--varname <string>}\\Name of input variable for which anomaly will be calculated.
\item[]\texttt{--pv} or \texttt{--z500}\\Boolean which specifies whether the vertically averaged potential anomaly (\texttt{--pv}) or 500 mb geopotential height (\texttt{--z500}) anomaly will be calculated. If neither is specified, the names for the unsmoothed (\texttt{--devname}) and smoothed (\texttt{--adevname}) anomalies are required.
\end{itemize}

** Do not use both \texttt{--in} and \texttt{--inlist} flags simultaneously.

*** Only use \texttt{--out} in conjunction with the \texttt{--in} flag.

\subsubsection{File input and output}
This program takes a list of files and calculates anomalies from the long term daily mean (the file which was calculated in Section \ref{avg}). If \texttt{--z500} is not included, then the anomaly is simply $V^*=V-\overline{V}$. The boolean flag \texttt{--z500} tells the program to multiply the Z500 anomalies by a weight that is proportional to the sine of latitude (this eliminates bias in energy propagation due to the convergence of meridians at the higher latitudes).

For each input file, the program produces a corresponding output file containing the calculated anomalies with the suffix (default \texttt{\_devs}) appended to the original file name. There are 2 output variables: the unsmoothed anomaly (\texttt{DVPV/DZ/other}) and  the anomaly with 2-day smoothing (\texttt{ADVPV/ADZ/other}).

\subsection{Anomalies, Step 4a: Long Term Daily Mean of Anomalies: BlockingDFT}\label{davg}

The procedure is identical to that of Section \ref{avg}, except the list of input files will be a list of the anomaly files that were calculated in the previous step (Section \ref{dev}). It is recommended to use the smoothed anomalies.

Note that this step is optional if you wish to use a constant threshold value.

\subsection{Anomalies, Step 4b: Spatiotemporally Varying Threshold: BlockingThresh}\label{thresh}

\begin{verbatim}
Usage: BlockingThresh <parameter list>
Parameters:
  --inlist <string>  [""] *
  --outfile <string>  [""] *
  --davgfile <string>  [""] *
  --davgname <string>  [""] *
  --dvarname <string> [""] *
  --tname <string> ["time"] +
  --levname <string> ["lev"] +
  --latname <string> ["lat"] +
  --lonname <string> ["lon"] +
\end{verbatim}

\begin{itemize}
\item[]\texttt{--inlist <string>} \\ A list of input datafiles in NetCDF format containing variables that will be averaged, with axes \texttt{[time, lat, lon]} (if axes are \texttt{[time, lev, lat, lon] } then use boolean flag \texttt{--is4D})
\item[]\texttt{--outfile <string>} \\ Name of output file.
\item[]\texttt{--davgfile <string>} \\ Name of time-average anomalies file (as calculated in Section \ref{davg})
\item[]\texttt{--davgname <string>} \\ Name of time-average anomaly variable
\item[]\texttt{--dvarname <string>} \\ Name of the anomaly variable (preferably the smoothed anomaly variable)
\end{itemize}

\subsubsection{File input and output}
This program calculates a threshold field (with variable name \texttt{THRESHOLD\_DFT}) that varies in both time and space. The threshold is defined as 1.5 times the standard deviation of the anomaly values for a given day over the course of a range of years, and is calculated at each grid point. The threshold is smoothed across the latitude, longitude, and time axes using the same Fourier transform method that was utilized in Section \ref{avg}.

The program outputs a file that contains the threshold variable with axes \texttt{[time, lat, lon]}. The time axis has 365 time steps, each representing a day in the year. The time axis has units of ``days since 0001-01-01''.

Note that this step is optional if you wish to use a constant threshold value.

\subsection{Anomalies, Step 6: Normalized Anomalies: BlockingNormDevs}\label{ndev}
\begin{verbatim}
Usage: BlockingNormDevs <parameter list>
Parameters:
  --in <string> [""] **
  --inlist <string>  [""] **
  --out <string> [""] ***
  --varname <string> [""] *
  --thresh <string> [""] ***
  --threshname <string> [""] ***
  --normname <string> [""]
  --pv
  --z500
  --const ***
  --threshval <double> [0.]
  --minthreshval <double> [0.]
  --tname <string> ["time"] +
  --levname <string> ["lev"] +
  --latname <string> ["lat"] +
  --lonname <string> ["lon"] +
\end{verbatim}

\begin{itemize}
\item[]\texttt{--in <string>}\\ Name of input datafile in NetCDF format.
\item[]\texttt{--inlist <string>} \\ A list of input datafiles in NetCDF format.
\item[] \texttt{--out <string>} \\ Name of a single output file (only use with \texttt{--in} flag).
\item[] \texttt{--varname <string>}\\Name of input anomaly variable which will be normalized.
\item[]\texttt{--pv} or \texttt{--z500}\\Boolean which specifies whether the vertically averaged potential anomaly (\texttt{--pv}) or 500 mb geopotential height (\texttt{--z500}) anomaly will be used. If neither is specified, a generic anomaly normalization is performed.
\item[]\texttt{--thresh <string>} Name of threshold file calculated in Section \ref{thresh} (if using spatiotemporally varying threshold)
\end{itemize}

** Do not use both \texttt{--in} and \texttt{--inlist} flags simultaneously.

*** Either specify a threshold file with a spatiotemporally varying threshold (\texttt{--thresh}) or use the \texttt{--const} boolean to specify a constant threshold.

\subsubsection{File input and output}
This program calculates anomalies that are normalized by the specified threshold value. The \texttt{--pv} flag tells the program to search for negative anomalies in the Northern Hemisphere and positive anomalies in the Southern Hemisphere (minimum magnitude 1.1 PVU for varying threshold, or a constant 1.2 PVU threshold). The \texttt{--z500} flag tells the program to search for positive anomalies (minimum magnitude 100 m for varying threshold, or a constant 170 m threshold). If neither \texttt{--pv} nor \texttt{--z500} is specified,

\subsection{Optional flags}\label{option}

Some of the flags, such as \texttt{--latname}, are optional; if not provided, they will default to the value specified in the code. These flags are not all available for each program, so check the documentation to see which ones can be utilized (you can also run the desired program without any flags, which will print out the command list, raise an exception, and terminate).

\subsubsection{Variable and axis names}

\begin{itemize}
\item[] \texttt{--tname <string>}\\Name of the time axis (default \texttt{time}).
\item[] \texttt{--levname <string>}\\Name of the vertical level axis (default \texttt{lev}).
\item[]\texttt{--latname <string>}\\Name of the latitude axis (default \texttt{lat}).
\item[]\texttt{--lonname <string>}\\Name of the longitude axis (default \texttt{lon}).
\item[] \texttt{--PVname <string>}\\Name of the potential vorticity variable (default \texttt{PV}).
\item[]\texttt{--VPVname <string>}\\Name of the output vertically averaged potential vorticity variable (default \texttt{VPV})
\item[] \texttt{--uname <string>}\\Name of the zonal wind variable (default \texttt{U}).
\item[] \texttt{--vname <string>}\\Name of the meridional wind variable (default \texttt{V}).
\item[] \texttt{--tempname <string>}\\Name of the temperature variable (default \texttt{T}).
\end{itemize}

\subsubsection{File naming conventions}
\begin{itemize}
\item[]\texttt{--insuff <string>}\\Input file extension string (default \texttt{.nc}).
\item[]\texttt{--insuff2d <string>}\\Input surface pressure file extension string (default \texttt{.nc}).
\item[]\texttt{--outsuff <string>}\\Output file naming convention (default varies between programs).
\item[] \texttt{--outsuffipl<string>}\\Output interpolated variable file naming convention (default varies between programs).
\end{itemize}

\subsubsection{Booleans}
\begin{itemize}
\item[] \texttt{--gh}\\Boolean that tells the program to convert geopotential to geopotential height ($Z=\frac{\Phi}{g}$).
\item[] \texttt{--hpa}\\Boolean that tells the program that the pressure axis is in hPa instead of Pa.
\item[]\texttt{--ipl}\\ Optional bool directing program to create new input file with vertical pressure axis (using input file with vertical model level axis and surface pressure file)
\item[] \texttt{--is4D}\\Boolean that tells the program that the input variable has 4 dimensions (time, vertical level, latitude, longitude).
\end{itemize}

\section{DetectCyclonesUnstructured}

\begin{verbatim}
Usage: DetectCyclonesUnstructured <parameter list>
Parameters:
  --in_data <string> [""]
  --in_data_list <string> [""]
  --in_connect <string> [""]
  --out <string> [""]
  --out_file_list <string> [""]
  --searchbymin <string> [""] (default PSL)
  --searchbymax <string> [""]
  --minlon <double> [0.000000] (degrees)
  --maxlon <double> [0.000000] (degrees)
  --minlat <double> [0.000000] (degrees)
  --maxlat <double> [0.000000] (degrees)
  --topofile <string> [""]
  --maxtopoht <double> [0.000000] (m)
  --mergedist <double> [0.000000] (degrees)
  --closedcontourcmd <string> [""] [var,delta,dist,minmaxdist;...]
  --noclosedcontourcmd <string> [""] [var,delta,dist,minmaxdist;...]
  --thresholdcmd <string> [""] [var,op,value,dist;...]
  --outputcmd <string> [""] [var,op,dist;...]
  --timestride <integer> [1]
  --regional <bool> [false]
  --out_header <bool> [false]
  --verbosity <integer> [0]
\end{verbatim}

\begin{itemize}
\item[] \texttt{--in\_data <string>} \\ A list of input datafiles in NetCDF format, separated by semi-colons.
\item[] \texttt{--in\_data\_list <string>} \\ A file containing the \texttt{--in\_data} argument for a sequence of processing operations (one per line).
\item[] \texttt{--in\_connect <string>} \\ A connectivity file, which uses a vertex list to describe the graph structure of the input grid.  This parameter is not required if the data is on a latitude-longitude grid.
\item[] \texttt{--out <string>} \\ The output file containing the filtered list of candidates in plain text format.
\item[] \texttt{--out\_file\_list <string>} \\ A file containing the \texttt{--out} argument for a sequence of processing operations (one per line).
\item[] \texttt{--searchbymin <string>} \\ The input variable to use for initially selecting candidate points (defined as local minima).  By default this is ``PSL'', representing detection of surface pressure minima.  Only one of \texttt{searchbymin} and \texttt{searchbymax} may be set.
\item[] \texttt{--searchbymax <string>} \\ The input variable to use for initially selecting candidate points (defined as local maxima).  Only one of \texttt{searchbymin} and \texttt{searchbymax} may be set.
\item[] \texttt{--minlon <double>} \\ The minimum longitude for candidate points.
\item[] \texttt{--maxlon <double>} \\ The maximum longitude for candidate points.
\item[] \texttt{--minlat <double>} \\ The minimum latitude for candidate points.
\item[] \texttt{--maxlat <double>} \\ The maximum latitude for candidate points.
\item[] \texttt{--mergedist <double>} \\ Merge candidate points with distance (in degrees) shorter than the specified value.  Among two candidates within the merge distance, only the candidate with lowest \texttt{searchbymin} or highest \texttt{searchbymax} value will be retained.
\item[] \texttt{--closedcontourcmd <cmd1>;<cmd2>;...} Eliminate candidates if they do not have a closed contour.  Closed contour commands are separated by a semi-colon.  Each closed contour command takes the form \texttt{var,delta,dist,minmaxdist}.  These arguments are as follows.
\begin{itemize}
\item[] \texttt{var <variable>}  The variable used for the contour search.
\item[] \texttt{dist <double>}  The great-circle distance (in degrees) from the pivot within which the closed contour criteria must be satisfied.
\item[] \texttt{delta <double>}  The amount by which the field must change from the pivot value.  If positive (negative) the field must increase (decrease) by this value along the contour.
\item[] \texttt{minmaxdist <double>}  The distance away from the candidate to search for the minima/maxima.  If \texttt{delta} is positive (negative), the pivot is a local minimum (maximum).
\end{itemize}
\item[] \texttt{--noclosedcontourcmd <cmd1>;<cmd2>;...} \\ As \texttt{closedcontourcmd}, except eliminates candidates if a closed contour is present.
\item[] \texttt{--thresholdcmd <cmd1>;<cmd2>;...}  Eliminate candidates that do not satisfy a threshold criteria (there must exist a point within a given distance of the candidate that satisfies a given equality or inequality).  Threshold commands are separated by a semi-colon.  Each threshold command takes the form \texttt{var,op,value,dist}.  These arguments are as follows.
\begin{itemize}
\item[] \texttt{var <variable>}  The variable used for the contour search.
\item[] \texttt{op <string>}  Operator that must be satisfied for threshold (options include \texttt{>}, \texttt{>=}, \texttt{<}, \texttt{<=}, \texttt{=}, \texttt{!=}).
\item[] \texttt{value <double>}  The value on the RHS of the comparison.
\item[] \texttt{dist <double>}  The great-circle-distance away from the candidate to search for a point that satisfies the threshold (in degrees).
\end{itemize}
\item[] \texttt{--outputcmd <cmd1>;<cmd2>;...}  Include additional columns in the output file.  Output commands take the form \texttt{var,op,dist}. These arguments are as follows.
\begin{itemize}
\item[] \texttt{var <variable>}  The variable used for the contour search.
\item[] \texttt{op <string>}  Operator that is applied over all points within the specified distance of the candidate (options include \texttt{max}, \texttt{min}, \texttt{avg}, \texttt{maxdist}, \texttt{mindist}).
\item[] \texttt{dist <double>}  The great-circle-distance away from the candidate wherein the operator is applied (in degrees).
\end{itemize}
\item[] \texttt{--timestride <integer>} \\ Only examine discrete times at the given stride (by default 1).
\item[] \texttt{--regional} \\ When a latitude-longitude grid is employed, do not assume longitudinal boundaries to be periodic.
\item[] \texttt{--out\_header} \\ Output a header describing the columns of the data file.
\item[] \texttt{--verbosity <integer>} \\ Set the verbosity level (default 0).
\end{itemize}

\subsection{Variable Specification} \label{sec:VariableSpecification}

Quantities of type \texttt{<variable>} include both NetCDF variables in the input file (for example, ``Z850'') and simple operations performed on those variables.  By default it is assumed that NetCDF variables are specified in the \texttt{.nc} file as
\begin{center}
\texttt{float Z850(time, lat, lon)} \quad or \quad \texttt{float Z850(time, ncol)}
\end{center} for structured latitude-longitude grids and unstructured grids, respectively.  If variables have no time variable, they have the related specification
\begin{center}
\texttt{float Z850(lat, lon)} \quad or \quad \texttt{float Z850(ncol)}
\end{center}  If variables include an additional dimension, for instance,
\begin{center}
\texttt{float Z(time, lev, lat, lon)} \quad or \quad \texttt{float Z(time, lev, ncol)}
\end{center} they may be specified on the command-line as $\texttt{Z(<lev>)}$, where the integer index \texttt{<lev>} corresponds to the first dimension (or the dimension after \texttt{time}, if present).

Simple operators are also supported, including
\begin{itemize}
\item[] \texttt{\_ABS(<variable>)} Absolute value of a variable,
\item[] \texttt{\_AVG(<variable>, <variable>)} Pointwise average of variables,
\item[] \texttt{\_DIFF(<variable>, <variable>)} Pointwise difference of variables,
\item[] \texttt{\_F()}  Coriolis parameter,
\item[] \texttt{\_MEAN(<variable>, <distance>)} Spatial mean over a given radius,
\item[] \texttt{\_PLUS(<variable>, <variable>)} Pointwise sum of variables,
\item[] \texttt{\_VECMAG(<variable>, <variable>)} 2-component vector magnitude.
\end{itemize}  For instance, the following are valid examples of \texttt{<variable>} type,
\begin{center}
\texttt{\_MEAN(PSL,2.0)}, \quad \texttt{\_VECMAG(U850, V850)} \quad and \quad \texttt{\_DIFF(U(3),U(5))}.
\end{center}

\subsection{MPI Support} \label{sec:MPI}

The \texttt{DetectCyclonesUnstructured} executable supports parallelization via MPI when the \texttt{--in\_data\_list} argument is specified.  When enabled, the parallelization procedure simply distributes the processing operations evenly among available MPI threads.

\section{StitchNodes}

\begin{verbatim}
Usage: StitchNodes <parameter list>
Parameters:
  --in <string> [""]
  --out <string> [""]
  --format <string> ["no,i,j,lon,lat"]
  --range <double> [5.000000] (degrees)
  --minlength <integer> [3]
  --min_endpoint_dist <double> [0.000000] (degrees)
  --min_path_dist <double> [0.000000] (degrees)
  --maxgap <integer> [0]
  --threshold <string> [""] [col,op,value,count;...]
  --timestride <integer> [1]
  --out_format <string> ["std"] (std|visit)
\end{verbatim}

\begin{itemize}
\item[] \texttt{--in <string>} \\ The input file (a list of candidates from DetectCyclonesUnstructured).
\item[] \texttt{--out <string>} \\ The output file containing the filtered list of candidates in plain text format.
\item[] \texttt{--format <string>} \\ The structure of the columns of the input file.
\item[] \texttt{--range <double>} \\ The maximum distance between candidates along a path.
\item[] \texttt{--minlength <integer>} \\ The minimum length of a path (in terms of number of discrete times).
\item[] \texttt{--min\_endpoint\_dist <double>} \\ The minimum great-circle distance between the first candidate on a path and the last candidate (in degrees).
\item[] \texttt{--min\_path\_dist <double>} \\ The minimum path length, defined as the sum of all great-circle distances between candidate nodes (in degrees).
\item[] \texttt{--maxgap <integer>} \\ The largest gap (missing candidate nodes) along the path (in discrete time points).
\item[] \texttt{--threshold <cmd1>;<cmd2>;...} \\  Eliminate paths that do not satisfy a threshold criteria (a specified number of candidates along path must satisfy an equality or inequality).  Threshold commands are separated by a semi-colon.  Each threshold command takes the form \texttt{col,op,value,count}.  These arguments are as follows.
\begin{itemize}
\item[] \texttt{col <integer>}  The column in the input file to use in the threshold criteria.
\item[] \texttt{op <string>}  Operator used for comparison of column value (options include \texttt{>}, \texttt{>=}, \texttt{<}, \texttt{<=}, \texttt{=}, \texttt{!=}).
\item[] \texttt{value <double>}  The value on the right-hand-side of the operator.
\item[] \texttt{count <integer>}  The minimum number of candidates along the path that must satisfy this criteria.
\end{itemize}
\item[] \texttt{--timestride <integer>} \\ Only examine discrete times at the given stride (by default 1).
\end{itemize}

\printindex
\end{document}


\section{Requirements}

	The product receives EEG/MEG sensor data and constructs a real-time 3D visualization of the brain's current activity.
	Users can choose between further options, changing the output immediately to their personal preferences.

\begin{figure}[h]

	\begin{center}

		\includegraphics[scale=0.35]{Figures/disp3DScreenShot.png}
		\caption{Interpolated brain activity}

	\end{center}

\end{figure}

\subsection{Mandatory Criteria}

	The following functions have to be implemented correctly and must fulfill given requirements.

\subsubsection{Surface Constrained Distance Calculation (SCDC)} \label{scdc}

	Because the algorithm is supposed to work on folded surfaces, e.g. the brain, a function for calculating the distance between two points is needed.

	As the euclidian distance would not respect the structure of the surface, a different approach for determining the exact 	distances has to be implemented.
	The function receives input data in form of a preprocessed triangulated surface mesh and calculates the distance between 	the vertices.

	\begin{aims}

		\item[C111] Based on a given mesh, the function calculates a matrix that holds values describing the distances between 						all vertices using double precision.
		\item[C112] The function must be able to process up to 200,000 vertices.
		\item[C113] The user can limit the calculation to a subset of vertices.

	\end{aims}

\subsubsection{Sensor-to-Mesh Mapping} \label{projection}

	Since the sensors do not directly touch the head and therefore float slightly above it, an accurate projection is needed 	to exactly localize their positions on the surface beneath (e.g. head/brain/MEG helmet).

	Hence a function must be implemented to solve this problem.
	The function receives a set of sensor locations in 3D-Space and maps them onto the underlying mesh. Thus every 			sensor gets assigned to a vertex of the mesh.

	\begin{aims}

		\item[C121] The function must be able to handle data from MEG-sensors which have a known orientation.
		\item[C122] The function must be able to handle data from EEG-sensors which are non-orientated.

	\end{aims}

\subsubsection{Interpolation Algorithm} \label{interpolation}

	The main task is the ongoing interpolation, processing a particular set of sensor data, representing the brain's 			activity.

	Because the number of vertices is bigger than the quantity of sensor points, most vertex-values must be interpolated.
	Thus the algorithm receives a mesh and a subset of vertices with their respective sensor data.

	\begin{aims}

		\item[C131] Based on the said subset the algorithm must calculate the values of the neurophysiological activity for every vertex of the mesh.
		\item[C132] For this, the algorithm creates a matrix storing weights for the later interpolation.
					The interpolation process can be summarized by the following equation:

					$y_{full} = W \cdot y_{sub}$
					, where $W$ is the mentioned matrix and $y_{sub}$ is the current dataset for the known sensors, i.e. 							vertices.
		\item[C133] The calculation of the weight matrix must be based on the result of the SCDC (\ref{scdc}).
		\item[C134] Bad channels, a part of the given sensor meta data, must be considered during processing.

	\end{aims}

\subsubsection{Integration in Disp3D} \label{integration}

	In order to ensure usability within the given framework MNE-CPP, the final visualization must be integrated into the 			preexisting 3D visualization library, namely Disp3D.

	\begin{aims}

		\item[C141] A new function must be added to the Disp3D tree model. Internally this function must create a new 								handler.

	\end{aims}

\subsubsection{Non-Functional Requirements}

	\begin{aims}

		\item[C151] The software is cross-platform compatible.
		\item[C152] Features \ref{scdc} and \ref{projection} are implemented in the class \textit{GeometryInfo}, while 								\ref{interpolation} is facilitated in the class \textit{Interpolation}.
		\item[C153] The function to integrate the product into Disp3D (\ref{integration}) is named \textit{addSensorData()}.
		\item[C154] For introduction purposes, a product video is to be created and published on the MNE-CPP website.
		\item[C155] The software must be integratable into MNE Scan.
		\item[C156] Only Qt libraries and the Eigen framework are used during development.

	\end{aims}

\newpage

\subsection{Optional Criteria}

	As long as the mandatory requirements are fulfilled, it is desirable to further match the following criteria.

\subsubsection[SCDC]{SCDC (\ref{scdc})}

	\begin{aims}

		\item[C211] The computation time should be as low as possible.
		\item[C212] A threshold for the maximum distance between two vertices is used for reduction of processing time.

	\end{aims}

\subsubsection[Interpolation]{Interpolation (\ref{interpolation})}

	\begin{aims}

		\item[C221] One interpolation cycle should take less than 17ms.
		\item[C222] Multiple methods for calculating the weight matrix can be implemented. The user can select one.
		\item[C223] The computation is executed on GPU-level using compute shaders.

	\end{aims}

\subsection{Delimiting Criteria}

	The following criteria limit the functionality of the system.

	\begin{aims}

		\item[C311] The program receives preprocessed data and does not get in touch with hardware sensors.
		\item[C312] The program does not evaluate the data medically and solely processes the data for further 										visualization.

	\end{aims}


\subsection{Bounce}
\screenshot{plugins/images/ss-bounce}{Bounce}{img:bounce}
This demo is of the word ``Rockbox'' bouncing across the screen.
\opt{rtc}{There is also an analogue clock in the background.}
In \setting{Scroll mode} the bouncing text is replaced by a different one
scrolling from right to left.

\begin{btnmap}
    \PluginUp / \PluginDown
        \opt{HAVEREMOTEKEYMAP}{& }
    & Moves to next/previous option\\
    \nopt{scrollwheel} {
       \PluginRight{} / \PluginLeft
    }
    \opt{scrollwheel} {
       \PluginScrollFwd{} / \PluginScrollBack
    }
       \opt{HAVEREMOTEKEYMAP}{& }
    & Increases/decreases option value\\
    \PluginSelect
       \opt{HAVEREMOTEKEYMAP}{& }
    & Toggles Scroll mode\\
    \PluginCancel{} or \PluginExit
       \opt{HAVEREMOTEKEYMAP}{& }
    & Exits bounce demo\\
\end{btnmap}

Available options are:

\begin{description}
\item[Xdist/Ydist.] The distance to X axis and Y axis
respectively
\item[Xadd/Yadd.]How fast the code moves on the sine curve on
each axis
\item[Xsane/Ysane.] Changes the appearance of the bouncing.
\end{description}


\chapter{{\tt I2Ohash}:
% \break Integer
% (key1, key2, value)
Two Key Hash Table}
\par
The {\tt I2Ohash} is a object that manages a hash table
where there are two integer keys and the data to be stored
is {\tt void *} pointer.
This object was created to support a block sparse matrix, where
each block has two keys, a row and column id, and the value is a
pointer to a {\tt SubMtx} object.
\par
This is a very simple implementation.
Each {\tt <key1,key2>} is mapped to a list.
Each list contains {\tt <key1,key2,value>} triples
whose keys are mapped to the list,
and the triples are in lexicographic order
of their {\tt <key1,key2>} fields.
The size of the hash table (the number of lists)
is fixed upon initialization.
The number of allowable {\tt <key1,key2,value>} triples
can either be fixed (upon initialization)
or can grow by a user supplied amount.
\par
The methods that are supported are
\begin{itemize}
\item insert a {\tt <key1,key2,value>} triple
\item locate a {\tt <key1,key2,*>} triple and return the value
\item remove a {\tt <key1,key2,*>} triple and return the value
\end{itemize}


\section{Transactions Processing System}
\label{sec:prelim}
%\subsection{Web Service Architecture}
%\label{subsec:web}
Web services typically have two tiers of machines within a datacenter: a stateless
frontend tier and a stateful storage tier.
The frontends handle user requests by executing application logic that generates
sub-requests to read/write data in the storage tier that shards (or splits) data across many machines.
We refer to the front-ends as the \textit{clients}, the storage machines as
the \textit{servers} and the stored data items as \textit{objects}, to match common terminology.
While web services are typically geo-replicated, we focus on sharding within a datacenter because the reads that dominate their workloads are handled within a single datacenter.

We consider a transaction processing system that comprises a set of read/write objects $\mathcal{O}$,
 where each object
$o \in \mathcal{O}$ is maintained by a separate server process,
%, and all processes are connected via a  communication network.
and also another set of processes, we refer to as \emph{clients}, that can initiate transactions, after the previous ones, if any, have completed.
 The system allows two types of transaction: {\sc READ} transaction, a group of read requests for the values stored in some subset of objects in $\mathcal{O}$; and {\sc WRITE} transaction, a group of write requests intending to update the values stored in some subset of objects  $\mathcal{O}$.
 A read-client executes only READ transactions, while write-client executes only WRITE transactions; no client executes both types of transaction.

A typical READ transaction, we denote as $\textit{R}(o_{i_1}, o_{i_2}, \ldots, o_{i_q})$ or in short by $R$, consists a set of individual read requests
  $read(o_{i_1})$,  $read(o_{i_2})$ and  $read(o_{i_q})$ to read values in objects $o_{i_1}, o_{i_2}, \ldots, o_{i_q}$, respectively.
   $read(o)$ denotes a read that intends to read the value of object $o$.
 A typical WRITE, denoted as
 $\textit{W}((o_{i_1}, v_{i_1}), (o_{i_2}, v_{i_2}), \ldots, (o_{i_p}, v_{i_p}))$ or in short as $W$, consists of a set of which requests to update the values of objects $o_{i_1}, o_{i_2}, \ldots, o_{i_p}$ with  $v_{i_1}, v_{i_2}, \ldots, v_{i_p}$, respectively.

 A read (or write) client initiates a  READ (or WRITE) transaction with an invocation step  $\INV{R}$ (or $\INV{W}$), then it carries out the read or write operations in the transaction; and eventually completes  the transaction with a $\RESP{R}$ (or $\RESP{W}$).
 After the completion of the reads or writes in a transaction the client responds, in the case of $R$, with the values of objects;  and, in the case of $W$, an \emph{ok} status, to the external client.

We assume that the network channels are reliable but asynchronous, i.e., any message sent by a process will eventually arrive at its destination uncorrupted. We assume  local computations are  asynchronous, i.e., local computations at various processes proceed at arbitrary and unpredictable speeds. When a client receives a transaction request, usually from an external client, such as an user's device,  it  executes the transaction, denote by $R$ or $W$,  and finally, responds to the external client with the results.

\remove{KMK
The impossibility results we prove in this work involve showing the impossibility of algorithms for transaction processing where the executions are expected to guarantee  certain properties, such as the SNOW properties, described below. Our proofs rely on showing contradictions in some execution of an algorithm $\mathcal{A}$,  if such an algorithm was possible.  A typical proof assumes a simple set of transactions whose outcome is obvious,  satisfies the SNOW properties (described below) and also shows the existence of an execution $\alpha_0$, with desired properties,  of $\mathcal{A}$. Based on this,
we inductively argue the existence of a sequence of executions, with the properties, of $\mathcal{A}$, and finally arrive at an execution that contradicts at least one of the properties.  Since $\mathcal{A}$ can be any algorithm,  simple or complex, as long as it (to be precise, its executions) respects the same properties, there are innumerable  types of executions due to the asynchrony and the steps of $\mathcal{A}$. To create a series of possible executions, $\{\alpha\}_{i=0}$ we create the new execution $\alpha_{i+1}$, with the properties,  by starting with $\alpha_i$ and then perturbing (delaying or speeding up, using the liberty allowed by asynchrony) the occurrence of some events of $\alpha_i$ and thereafter allowing $\mathcal{A}$ to execute.
}

%In order to carry out our proofs we use IO Automata, which is  useful for careful analysis of the executions of $\mathcal{A}$ in asynchronous setting. Below we describe the following using the IO Automata: $(i)$ The models for the client and the servers processes, and the channels; $(ii)$ any execution  of $\mathcal{A}$ in terms of transition steps of individual automata; $(iii)$ the SNOW properties  of the algorithm; and  $(iv)$ the SNOW theorem.

\remove{
%\subsection{System Model and Assumptions}
\subsection{Algorithm Specification with I/O Automata}
\label{subsec:model}

\paragraph{\textbf{Processes and channels.}}
We consider a set $\Omega$ of $n$ processes in the system: $P_1, P_2, \ldots, P_n$. Each process represents a machine in the datacenter. More specifically, we denote client machines (processes) that can issue reads (readers) by $r_1, r_2, \ldots, r_k$, the clients that can issue writes (writers) by $w_1, w_2, \ldots, w_l$, and servers that store the data by $s_1, s_2, \ldots, s_m$, with $r, w, s \in \Omega$. Each client can only have one outstanding transaction, i.e., it cannot issue a new transaction until the outstanding transaction finishes. As a result, each client can either be a reader or a writer but not both at a given time.

%\paragraph{\textbf{Executions and I/O automata.}}
We model a distributed algorithm using   the I/O Automata~\cite{Lynch1996}.
%. A detailed account on IO Automata can be found in ~\cite{Lynch1996}.
Here we limit our discussion of I/O Automata to the relevant concepts, but for a detailed account the reader should refer
to ~\cite{Lynch1996}.
An algorithm is a composition $\mathcal{A}$ of a set of \emph{automata} where each automaton  $A_i$ corresponds to a process (e.g., client or server) or a communication channel in the system.  $A_i$ is defined in terms of
a set of deterministic transition functions  $\trans{A_i}$ (also called \textit{actions}), which can be thought of as the algorithmic steps of $A_i$;  and  a set of states $\states{A_i}$.
%Each process is an automation $A_i \in A$, i.e., a deterministic state machine. $A_i$ contains a set of states $\states{A_i} \subseteq \states{A}$.
%The set of possible initial state of $A_i$ is $\startstates{A_i} \subseteq \states{A_i}$.
An execution of $\mathcal{A}$ is a sequence of alternating states and actions of $A$,  $\sigma_0, a_1, \sigma_1, a_2, \sigma_2, \ldots, \sigma_n$.
A state change, called a \textit{step}, is a 3-tuple $(\sigma_i, a_i, \sigma_{i+1})$, with $\sigma_i, \sigma_{i+1} \in \states{A_i}$ and $a_i \in \trans{A_i}$.
%$a_i$ is an input action if it receives a message.
The set of input actions is denoted by $\inactions{A_i}$, e.g.,  $a_i \in \inactions{A_i}$ is an input action if it receives a message. The set of output actions is denoted by $\outactions{A_i}$. The input and output actions are also called external actions, denoted by $\extactions{A_i}$ and $\inactions{A_i} \cup \outactions{A_i}=\extactions{A_i}$. If an action $a_i \notin \extactions{A_i}$, then $a_i$ is an internal action.
Communications between any two automata $A_i$ and $A_j$ is modeled by using channel automata $Channel_{i, j}$ for sending messages from $A_i$ to $A_j$; and $Channel_{j, i}$ for sending message from $A_j$ to $A_i$. When $A_i$ sends some
message $m$ to $A_j$ the following sequence of actions occur: $send(m)_{i,j}$  occurs at $A_i$, then
$send(m)_{i,j}$ followed by $recv(m)_{i, j}$ occur at $Channel_{i,j}$; then finally, $A_j$ receives $m$ via the action $recv_{i,j}(m)$.
In our model,  the communication channels are simple because we assume reliable communication between each pair of processes. Therefore, we ignore the actions in the $Channel_{i, j}$ and instead say   $send(m)_{i,j}$  occurs at $A_i$ and then $A_j$ receives $m$ via the action $recv_{i,j}(m)$.
%$a_i$ is an external action, i.e., $a_i \in \extactions{A_i}$, if $a_i$ receives/sends a message from/to another automation, otherwise $a_i$ is an internal action of $A_i$.
%
%An execution of algorithm $\pi$ is a composition $E$ of $E_i$, i.e., the execution on each automation.
An execution fragment $\alpha$ %is a continuous segment of $E$. $\alpha$
can be either finite, i.e., having finite states, or infinite.
% We use the notation $trace(\alpha)$ to denote the sequence of external actions in $\alpha$; and by $trace(\alpha) | A_i$ we denote the sequence of external actions in $trace(\alpha)$ that belongs to automaton $A_i$.
If $\alpha$ is a finite execution and $\beta$ is an execution fragment, such that $\beta$ starts with the final state of $\alpha$ then we use $\alpha \circ \beta$ to denote the concatenation of $\alpha$ and $\beta$.
If $\epsilon$ and $\epsilon'$ are two execution fragments, such that they have the same sequence of states at automaton $A_i$, i.e., $\epsilon|A_i = \epsilon'|A_i$, then $\epsilon$ and $\epsilon'$ are indistinguishable at $A_i$, denoted by $\epsilon \stackrel{A_i}{\sim} \epsilon'$. When the context is clear, we simply use $\epsilon \sim \epsilon'$.
}
We model a distributed algorithm using the I/O automata modeling framework (see ~\cite{Lynch1996} for a detailed account).
In the rest of this paper, for any execution of an automaton $\mathcal{A}$,
$\finiteprefix{k-1}{k}\ldots$, where $\sigma$'s and $a$'s are states and actions,
we use the notation $\finiteprefixt{k-1}{k}\ldots$ which shows only the actions to simplify notation.
% The network is either asynchronous or partially synchronous, i.e., there do not exist perfect wall clocks in the system that atomically synchronize the sending and receiving of messages. That is, messages can be delayed and the delay is assumed to be either unbounded or bounded by some upper bound.
We use the notation $\textit{prefix}(\alpha, a)$ to refer to the finite prefix of any execution $\alpha$ ending with action  $a$ such that $a$ occurs within $\alpha$.
In our model, an individual read, such as $read(o)$, in some read transaction $R$ initiated by some read client $r$ consists of the following sequence of actions: after $\INV{R}$ at $r$, $r$ sends a message $m$ (requesting the value stored in $o$) to a server $s$ via action $\send{m}{r, s}$. When  $s$ receives $m$ via  action $\recv{m}{r, s}$ it sends the value $v$ (stored in $o$) to $r$  via action $\send{v}{s, r}$. Then $read(o)$ completes as soon as $r$ receives $v_j$ via action  $\recv{v}{s, r}$.

\remove{
\subsection{Transactions Processing System}
\label{subsec:notation}
We consider a transaction processing system that comprises a set $\mathcal{O}$ of read/write objects,
 where each object
$o \in \mathcal{O}$ is maintained by a separate server process, and we consider a set of client process,  and all processes are connected via  reliable and asynchronous communication channels.
%The system has a set of physical objects (data items) sharded across many (server) processes. Without loss of generality, we treat the group of objects that reside on the same process $P_k$ as a single logical object $o_k$, where $o_k \in \mathcal{O}$ and $\mathcal{O}$ is the set of logical objects.
%We assume that between any pair of processes $p_1$ and $p_2$,   such that $p_1 \neq p_2$,   there are channel automata $Channel_{p_1, p_2}$ and $Channel_{p_2, p_1}$.
%\hl{I commented out the text on assuming there is a channel between each pair of processes here.}
\sloppy
The distributed algorithm $\mathcal{A}$  for the transaction processing system runs on these set of processes. In this setting,  there are two types of transactions: READ and WRITE transactions. The \textit{invocation} of a \rot{} $R$, denoted by $\INV{R}$, is the external action at a read client process $\textit{READ}(o_{i_1}, o_{i_2}, \ldots, o_{i_q})$, for any subset  of objects $o_{i_1}, o_{i_2}, \ldots, o_{i_q}$ in $\mathcal{O}$.
%
%, which sends messages to the server processes that hold objects $o_{i_1}, o_{i_2}, \ldots, o_{i_q}$. More specifically, $\INV{R}$ consists of a set of output actions, $\send{m_j^{r}}{r, s_j}$, which sends a message $m_j^{r}$ from reader $c_r$ to server $s_j$.
%Server $s_j$ starts processing $R$ with an input action $\recv{m_j^{r}}{r, s_j}$ that receives the message $m_j^{r}$, and finishes processing $R$ by an output action $\send{v_j}{ s_j, r}$ that sends value $v_j$ to $c_r$.
The \textit{response} of $R$, denoted by  $\RESP{R}$,  occurs at the same read client by returning the value read from each of the  objects $o_{i_1}, o_{i_2}, \ldots, o_{i_q}$.
%
%\sloppy We model the processing of \wots{} in the same way.
 The goal of a write transaction $\textit{WRITE}((o_{i_1}, v_{i_1}), (o_{i_2}, v_{i_2}), \ldots, (o_{i_p}, v_{i_p}))$,  we denote by $W$, is to update the
 value of object $o_{i}$ to $v_i$.  The invocation of a \wot{} $W$, denoted by $\INV{W}$, is
 $\textit{WRITE}((o_{i_1}, v_{i_1}), (o_{i_2}, v_{i_2}), \ldots, (o_{i_p}, v_{i_p}))$, which writes $o_i$ with value $v_i$. The response of $W$, denoted by $\RESP{W}$, is simply $\textit{ok}$. %The lifetime of a transaction is the time between invocation and response.
}

\subsection{SNOW Properties}
In this subsection, we define the SNOW properties for a transaction
processing system.  Namely, we require that any fair execution of the
system satisfies the following
 four properties: $(i)$ \emph{Strict serializability} (S), which means there is a total ordering  of the transactions such that  all transactions in the resulting execution  appear to be processed by  a single machine one at a time; $(ii)$ \emph{Non-blocking operations} (N), which  means that the servers respond immediately to the read requests of a READ transaction without waiting for any input from other processes; $(iii)$ \emph{One response per read} (O), which requires that any read operation  consists of one round trip of communication with a server,  and also, that  the server responds with a message that contains exactly  one version of the  object value; and $(iv)$ \emph{WRITE transactions that conflict} (W) implies the  existence of concurrent WRITE transactions that update the data objects  while READ transactions are in progress reading the same objects.  Below we describe the individual properties of the SNOW properties in more detail.

{\bf Strict serializability (S).} By \emph{strict serializability} (for a formal definition please see~\cite{HW90}), we mean each WRITE or READ transaction appears to the clients to be executed atomically, at some point in an execution  between the invocation and response events.
%In other words,  for  each transaction, we can associate a
%serialization point between the invocation and response actions, such that all  the read operations return values such that the transactions appear to  occur in the same order as the serialization points.

Next, we describe the non-blocking and one-response
properties.  Both are defined as properties of read operations to an
individual object. For the purpose of elucidation, we consider an execution $\alpha$ of a transaction processing system $T$ that has a set of objects $\mathcal{O}$, where there is a READ transaction  $\textit{R}(o_{i_1}, o_{i_2}, \ldots, o_{i_q})$, in short $R$, invoked at some reader $r$, such that $R$ contains a read $read(o_j)$ for some $o_j \in \mathcal{O}$ maintained at server $s_j$.
% By $\textit{prefix}(\alpha', a)$ we denote the execution fragment in $\alpha$ from the  beginning of $\alpha$ to the state immediately following any action $a$ in $\alpha$.
 %Consider a READ transaction  $\textit{READ}(o_{i_1}, o_{i_2}, \ldots, o_{i_q})$,   denote it by $R$, initiated at read client $r$.
 % where $R$ contains the individual reads $read(o_{i_1})$,  $read(o_{i_2})$ and  $read(o_{i_q})$ to read values stored in $o_{i_1}, o_{i_2}, \ldots, o_{i_q}$, respectively.
%
  % and there is  a read operation in it  to  read the value of some object $o_i$ managed by some server $s_i$.
% If The read operation involves $r$ communicating a \emph{send value} message   to $s_i$ requesting the stored value of $o_i$.

{\bf Non-blocking reads (N).} The \emph{non-blocking} property means that if $r$, a reader-client,  sends any message to any $s_i$ ($s_i$ manages object $o_i$) during the transaction then  $s_i$ can  respond to  $r$ without waiting for any external input event, such as the arrival of messages, any mutex operations, time, etc. This property ensures that {\sc READ} transactions are delayed only due to delay in message delivery between $r$ and $s_i$. We define this property formally as follows.

\begin{definition}[Non-blocking read (N)]
%The one-round, one-version and non-blocking properties states the following properties for $\alpha$.
 Suppose in  $\alpha$, following the action $\INV{R}$,  the actions  $\recv{m_j^{r}}{r, s_j}$ and   $\send{v_j}{ s_j, r}$
   corresponding to $read(o_j)$, occurs at $s_j$.  Then there  exists an execution $\alpha'$ of $T$ such that
  \begin{enumerate}
  \item[ $(i)$ ] The execution fragments
 $\textit{prefix}( \alpha, \recv{m_j^{r}}{r, s_j})$ and $\textit{prefix}( \alpha', \recv{m_j^{r}}{r, s_j})$ are identical, where
 $\textit{prefix}(\alpha, a)$.
 \item [ $(ii)$] In $\alpha'$ the action  $\send{v_j}{ s_j, r}$ at $s_j$ occurs after $\recv{m_j^{r}}{r, s_j}$ without any input action in between.
\end{enumerate}
\end{definition}

{\bf One-response per read (O).} The \emph{one-response} property requires that each read operation, $read(o_i)$,  during any
READ transaction, completes successfully in one round of client-to-server communication and the \emph{one-version}  states that exactly one version of the value is sent by server $s_i$, that manages $o_i$, to $r$. \emph{One-round} consists of
a read  request from the client initiating the read operation to the server  and  the response containing value sent by the server.
%, and subsequently, the server sending only one version of the object value  in its response.

\begin{definition}[One response per read (O)]
%The one-round, one-version properties states the following properties for $\alpha$.
 Suppose in  $\alpha$, the action $\INV{R}$ occur at $r$  then in $\alpha$ there exists  exactly a pair of actions $ \recv{m_j^{r}}{r, s_j})$ and   $\send{v_j}{ s_j, r}$, corresponding to $R$,  occur at $s_j$, such that
 $v_j$ is the object value of $o_j$.
\end{definition}
If the reads,  of some READ transaction, of a transaction processing system respect the \emph{non-blocking} and \emph{one-response} properties then each read includes one-round trip from client to server,  where the server returns only the requested value as soon as it receives the request. It is worth noting that the READ transaction can complete only after all the $read(\cdot)$s in it complete.

\begin{definition}[Conflicting writes (W)]
%The one-round, one-version properties states the following properties for $\alpha$.
 Suppose in  $\alpha$, the action $\INV{W}$, the actions  occur
  at a write client $w$ then there is an action $\RESP{W}$ in $\alpha$ that appears after $\INV{W}$.
\end{definition}

%\paragraph{Concurrent and conflicting writes (W)} The \emph{concurrent and conflicting writes}
{\bf WRITE transactions that conflict (W).} The \emph{conflicting writes}
 property states that READ transactions complete even in the presence of concurrent WRITE
  transactions, where the write operations  might update some objects that are also being read by read operations in READ transaction.
  This shows that READ transactions can be invoked at any point, even in the presence of ongoing WRITE
   transactions.  Note that the liveness of any WRITE transaction is not implied by any of
   the SNOW properties;  however, for useful practical systems   the  WRITE transactions must eventually complete.
   % is essential in practical systems where \emph{WRITE}s complete if the writer
 % transactions is essential
   % to avoid trivial and uninteresting  executions such as  executions where no \emph{WRITE} transaction ever completes
   % but the \emph{READ} transactions return the  initial values of the objects.
    Therefore, we assume that every WRITE
    transaction eventually completes via the $RESP$ event, and think of this constraint as a part of the W property.

\remove{KMK
\subsection{One-Version, Multi-Round Property (o)}
We also introduce a weaker version of the O property, denote it as ``o'',  where during a read operation the  server returns exactly one object value but there exists a finite bound on the number of rounds of communication between the client and the  server. We use the acronym SNoW to denote the S, N, o, and W properties.  Moreover,  it is easy to realize that if an algorithm satisfies the SNoW properties then READ transactions always complete, and hence, READ transactions are always live. This is because the N and o properties imply that the server must immediately respond to a read request due to a read operation with exactly one object value without waiting in expectation of incoming messages, and
there is a fixed upper bound on the number of such rounds for a READ.
}
%The system has a set of physical objects (data items) sharded across many (server) processes. Without loss of generality, we treat the group of objects that reside on the same process $P_k$ as a single logical object $o_k$, where $o_k \in \mathcal{O}$ and $\mathcal{O}$ is the set of logical objects. The \textit{invocation} of a \rot{} $R$, denoted by $\INV{R}$, is the external action on a client process: $READ(o_{i_1}, o_{i_2}, \ldots, o_{i_q})$, which sends messages to the server processes that hold objects $o_{i_1}, o_{i_2}, \ldots, o_{i_q}$. The \textit{response} of $R$, denoted by $\RESP{R}$, is the external action on the same client process: $RECV(v_{i_1}, v_{i_2}, \ldots, v_{i_q})$, which returns the value of each object. For simplicity, we often omit ``RECV" when the context is clear. The invocation of a \wot{} $W$, denoted by $\INV{W}$, is $WRITE((o_{i_1}, v_{i_1}), (o_{i_2}, v_{i_2}), \ldots, (o_{i_p}, v_{i_p}))$, which writes each object $o_i$ with new value $v_i$. The response of $W$, denoted by $\RESP{W}$, is $ok$. The lifetime of a transaction $T$ is the time between its invocation and response.


\section{Model Description}

Spice interfaces with the AVS Basilisk simulation. This is done through spice\_interface.cpp, which loads the proper kernels in External/EphemerisData. Given an epoch, it generates information on universal time (UTC/GPS...) as well as ephemeris information for the bodies of the Solar System. It writes this out in a spice output message for other modules to use.

\subsection{Output message}

This module outputs a message called \texttt{SpicePlanetStateSimMsg}. This message is used throughout the sim and contains:

\begin{itemize}
    \item[-] J2000Current: the time of validity for the planet state
    \item[-] PositionVector: the true position of the planet for the time
    \item[-] VelocityVector: the true velocity of the planet for the time
    \item[-] J20002Pfix: the orientation matrix of planet-fixed relative to inertial
    \item[-] J20002Pfix\_dot: the derivative of the orientation matrix of planet-fixed relative to inertial
    \item[-] computeOrient: the flag indicating whether the reference should be computed
    \item[-] PlanetName: the name of the planet for the state
\end{itemize}

\subsection{Citation}

More information on Spice can be read by following the following link:\href{ \underline{https://naif.jpl.nasa.gov/naif/spiceconcept.html}}{The Navigation and Ancillary Information Facility}.