\documentclass[12pt]{article}
\usepackage{url}
%\usepackage[dvips]{graphicx}
\usepackage[pdftex]{graphicx}
\usepackage[latin1]{inputenc}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{fancyhdr}
\usepackage{bm}
\usepackage{float}
\usepackage{color}
\usepackage[dvipsnames]{xcolor}
\usepackage{wrapfig}
\usepackage{multicol}
\usepackage[colorlinks=true,
		linkcolor=red,
		citecolor=blue,
		urlcolor=blue]{hyperref}

\usepackage{titlesec}
\usepackage[titletoc]{appendix}
%\usepackage{appendix}
\setcounter{secnumdepth}{4}

\titleformat{\paragraph}
{\normalfont\normalsize\bfseries}{\theparagraph}{1em}{}
\titlespacing*{\paragraph}
{0pt}{3.25ex plus 1ex minus .2ex}{1.5ex plus .2ex}

\setlength {\parindent} { 10mm}
\setlength{\textheight}{230mm}
\setlength{\textwidth}{160mm}
\setlength{\oddsidemargin}{0mm}
\setlength{\topmargin}{-10mm}
% newcommands
\newcommand{\p}{\partial}
\newcommand{\g}[1]{\mbox{\boldmath $#1$}}
\newcommand{\vi}{\g V_{\! \! i}}
\newcommand{\ps}{Pfirsch-Schl\"{u}ter}
\newcommand{\lp}{\left(}
\newcommand{\rp}{\right)}
\newcommand{\ca}[1]{\mbox{\cal $#1$}}
\newcommand{\be}{\begin{displaymath}}
\newcommand{\ee}{\end{displaymath}}
\newcommand{\bn}{\begin{equation}}
\newcommand{\en}{\end{equation}}
\newcommand{\mygtrsim}{\mathrel{\mbox{\raisebox{-1mm}{$\stackrel{>}{\sim}$}}}}
\newcommand{\mylsim}{\mathrel{\mbox{\raisebox{-1mm}{$\stackrel{<}{\sim}$}}}}
\newcommand{\vek}{\bf}
\newcommand{\ten}{\sf}
\newcommand{\bfm}[1]{\mbox{\boldmath$#1$}}
\newcommand{\lang}{\left\langle}
\newcommand{\rang}{\right\rangle}
\newcommand{\vo}[1]{\left|\begin {array}{l} \mbox{} \\ \mbox{} \\$#1$ \end
{array}\right .}
\newcommand{\von}[2]{\left |\begin {array}{l}
\mbox{}\\$#1$\\$#2$ \end {array}\right .}
\newcommand{\simgt}{\:{\raisebox{-1.5mm}{$\stackrel
{\textstyle{>}}{\sim}$}}\:}
\newcommand{\simlt}{\:{\raisebox{-1.5mm}{$\stackrel
{\textstyle{<}}{\sim}$}}\:}
%\renewcommand {\baselinestretch} {1.67}
%\pagestyle{empty}
\newcommand{\todo}[1]{\textbf{\textcolor{red}{TODO: #1}}}
\newcommand{\remark}[1]{\textbf{\textcolor{red}{REMARK: #1}}}

\title{Implementation of $\Phi_1$ in SFINCS}

\pagestyle{fancy}
\fancyhead{}
\chead{Albert Moll\'en %850227-2019
\\ Implementation of $\Phi_1$ in SFINCS}
\cfoot{\thepage}
\renewcommand{\headrulewidth}{1pt}
\renewcommand{\footrulewidth}{1pt}
\setlength{\headheight}{28pt}
\setlength{\footskip}{25pt}

\newcommand{\red}[1]{\textcolor{red}{#1}}
\newcommand{\mE}{\mathcal{E}}
\newcommand{\energy}{\mathcal{E}}
\newcommand{\mK}{\mathcal{K}}
\newcommand{\mN}{\mathcal{N}}
\newcommand{\mD}{\mathcal{D}}
\newcommand{\ord}{\mathcal{O}}
\newcommand{\Tpe}{T_\perp}
\newcommand{\Tpa}{T_\|}
\newcommand{\vpe}{v_\perp}
\newcommand{\vpa}{v_\|}
\newcommand{\kpe}{k_\perp}
\newcommand{\kpa}{k_\|}
\newcommand{\Bv}{\mathbf{B}}
\newcommand{\Ev}{\mathbf{E}}
\newcommand{\bv}{\mathbf{b}}
\newcommand{\vv}{\mathbf{v}}
\newcommand{\cd}{\cdot}
\newcommand{\na}{\nabla}
\newcommand{\btheta}{\bar{\theta}}
\newcommand{\phit}{\tilde{\phi}}
\newcommand{\oert}{\tilde{\omega}_{Er}}

\begin{document}
\titlepage

\maketitle

\section*{EUTERPE old equations vs new equations}
We want to modify the implementation of the old EUTERPE equations \cite{regana} in SFINCS
to the new equations \cite{reganaArxiv}.

The old equations for the particle trajectories and the drift-kinetic equation are
\begin{align}
\dot{\bm{R}} & =  v_\| \bm{b} - \frac{\na \Phi_0 \times \bm{b}}{B}  \\
\dot{v}_\| & =  - \frac{q}{m} \bm{b} \cdot \na \Phi_1 - \mu \bm{b} \cdot \na B - \frac{v_\|}{B^2} \left(\bm{b} \times \na B\right) \cdot \na \Phi_0 \\
\dot{\mu} & =  0
\label{eq:ParticleTrajEuterpeOld}
\end{align}
and
\begin{multline}
\frac{\p f_1}{\p t} + \dot{\bm{R}} \cdot \na f_1 + \dot{v}_\| \frac{\p f_1}{\p v_\|} - C = \\ =
- f_M \left[\frac{1}{n} \frac{\p n}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2}\right) \frac{1}{T} \frac{\p T}{\p \psi}\right]
\left(\bm{v}_d + \bm{v}_{E1}\right) \cdot \na \psi -
\frac{q}{m} \frac{f_M}{v_{\mathrm{th}}^2} \left(v_\| \bm{b} + \bm{v}_d\right) \cdot \left(\na \Phi_0 + \na \Phi_1\right).
\label{eq:DriftKineticEuterpeOld}
\end{multline}

The new equations are
\begin{align}
\dot{\bm{R}} & =  v_\| \bm{b} - \frac{\na \Phi_0 \times \bm{b}}{B}  \\
\dot{v}_\| & =  - \frac{q}{m} \bm{b} \cdot \na \Phi_1 - \mu \bm{b} \cdot \na B - \frac{v_\|}{B^2} \left(\bm{b} \times \na B\right) \cdot \na \Phi_0 \\
\dot{\mu} & =  0
\label{eq:ParticleTrajEuterpeNew}
\end{align}
and
\begin{multline}
\frac{\p f_1}{\p t} + \dot{\bm{R}} \cdot \na f_1 + \dot{v}_\| \frac{\p f_1}{\p v_\|} - C = \\ =
- f_0 \left[\frac{1}{n} \frac{\p n}{\p \psi} + \frac{q}{T} \frac{\p \Phi_0}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2} + \frac{q}{T} \Phi_1\right) \frac{1}{T} \frac{\p T}{\p \psi}\right]
\left(\bm{v}_d + \bm{v}_{E1}\right) \cdot \na \psi.
\label{eq:DriftKineticEuterpeNew}
\end{multline}
Here we have the definitions
\begin{equation}
\Phi\left(\psi, \theta, \varphi\right) \equiv \Phi_0\left(\psi\right) + \Phi_1\left(\theta, \varphi\right),
\label{eq:Phi}
\end{equation}
\begin{equation}
\bm{v}_d = \frac{m}{q} \frac{\mu B + v_\|^2}{B^2} \bm{b} \times \na B,
\label{eq:MagneticDrift}
\end{equation}
\begin{equation}
\bm{v}_{E1} = - \frac{\na \Phi_1 \times \bm{b}}{B},
\label{eq:ElectricDrift1}
\end{equation}
\begin{equation}
f_0 = f_M \exp \left(- q \Phi_1 / T \right) = \frac{n_0\left(\psi\right)}{\left(2 \pi\right)^{3/2} v_{\mathrm{th}}^3} \exp \left[- \frac{\left(v_\|^2  + v_\perp^2\right)}{2 v_{\mathrm{th}}^2}\right] \exp \left(- q \Phi_1 / T \right),
\label{eq:f0}
\end{equation}
$q = Z e$ and $v_{\mathrm{th}}^2 = T/m$.\\

\noindent The only differences appear in the RHS:s of Eqs.~\ref{eq:DriftKineticEuterpeOld} and \ref{eq:DriftKineticEuterpeNew}:\\
Firstly, $f_M$ has been replaced by $f_0$ containing the $\exp \left(- q \Phi_1 / T \right)$ factor.\\
Secondly, some of the terms have been modified.
We rewrite the RHS of \ref{eq:DriftKineticEuterpeNew}:
\begin{multline}
{\mathrm{RHS}}_{\mathrm{NEW}} =
- f_0 \left[\frac{1}{n} \frac{\p n}{\p \psi} + \frac{q}{T} \frac{\p \Phi_0}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2} + \frac{q}{T} \Phi_1\right) \frac{1}{T} \frac{\p T}{\p \psi}\right]
\left(\bm{v}_d + \bm{v}_{E1}\right) \cdot \na \psi = \\ =
%%
- f_0 \left[\frac{1}{n} \frac{\p n}{\p \psi} + \frac{q}{T} \frac{\p \Phi_0}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2}\right) \frac{1}{T} \frac{\p T}{\p \psi}\right]
\left(\bm{v}_d + \bm{v}_{E1}\right) \cdot \na \psi + \\ -
f_0  \frac{q}{T} \Phi_1 \frac{1}{T} \frac{\p T}{\p \psi}
\left(\bm{v}_d + \bm{v}_{E1}\right) \cdot \na \psi = \\ =
%%
- f_0 \left[\frac{1}{n} \frac{\p n}{\p \psi} + \frac{q}{T} \frac{\p \Phi_0}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2}\right) \frac{1}{T} \frac{\p T}{\p \psi}\right]
\bm{v}_d \cdot \na \psi + \\ -
f_0 \left[\frac{1}{n} \frac{\p n}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2}\right) \frac{1}{T} \frac{\p T}{\p \psi}\right]
\bm{v}_{E1} \cdot \na \psi - f_0 \frac{q}{T} \frac{\p \Phi_0}{\p \psi} \bm{v}_{E1} \cdot \na \psi + \\ -
f_0 \frac{q}{T} \Phi_1 \frac{\na T}{T} \cdot
\left(\bm{v}_d + \bm{v}_{E1}\right) = \\ =
%%
- f_0 \left[\frac{1}{n} \frac{\p n}{\p \psi} + \frac{q}{T} \frac{\p \Phi_0}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2}\right) \frac{1}{T} \frac{\p T}{\p \psi}\right]
\bm{v}_d \cdot \na \psi + \\
\textcolor{blue}{- f_0 \left[\frac{1}{n} \frac{\p n}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2}\right) \frac{1}{T} \frac{\p T}{\p \psi}\right]
\bm{v}_{E1} \cdot \na \psi}  + \\
\textcolor{red}{- f_0 \frac{q}{T} \left[\na \Phi_0 \cdot \bm{v}_{E1} + \Phi_1 \frac{\na T}{T} \cdot \bm{v}_d + \Phi_1 \frac{\na T}{T} \cdot \bm{v}_{E1} \right]}.
\label{eq:DriftKineticEuterpeNewRHS}
\end{multline}
Similarly, the RHS of \ref{eq:DriftKineticEuterpeOld} is rewritten as:
\begin{multline}
{\mathrm{RHS}}_{\mathrm{OLD}} =
- f_M \left[\frac{1}{n} \frac{\p n}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2}\right) \frac{1}{T} \frac{\p T}{\p \psi}\right]
\left(\bm{v}_d + \bm{v}_{E1}\right) \cdot \na \psi -
\frac{q}{m} \frac{f_M}{v_{\mathrm{th}}^2} \left(v_\| \bm{b} + \bm{v}_d\right) \cdot \left(\na \Phi_0 + \na \Phi_1\right) = \\ =
%%
- f_M \left[\frac{1}{n} \frac{\p n}{\p \psi} + \frac{q}{T} \frac{\p \Phi_0}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2}\right) \frac{1}{T} \frac{\p T}{\p \psi}\right]
\bm{v}_d \cdot \na \psi + \\
\textcolor{blue}{- f_M \left[\frac{1}{n} \frac{\p n}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2}\right) \frac{1}{T} \frac{\p T}{\p \psi}\right]
\bm{v}_{E1} \cdot \na \psi}  + \\
\textcolor{red}{- f_M \frac{q}{T} \left[v_\| \bm{b} \cdot  \na \Phi_1 + \bm{v}_d \cdot  \na \Phi_1\right]}.
\label{eq:DriftKineticEuterpeOldRHS}
\end{multline}
Comparing ${\mathrm{RHS}}_{\mathrm{NEW}}$ to ${\mathrm{RHS}}_{\mathrm{OLD}}$ we see that, apart from $f_M \rightarrow f_0$, only the terms in red have changed.

\subsection*{What has to be changed in SFINCS}
The only part of the drift-kinetic equation block we need to modify is the RHS, where we need to update the red terms and substitute $f_M \rightarrow f_0$. SFINCS had earlier neglected the $\bm{v}_d \cdot  \na \Phi_1$-term which is small in the standard $\rho_\ast$-expansion.
The RHS that was implemented is (see Matt's ISHW poster, also note that $\bm{v}_{E} \cdot \na \psi = \bm{v}_{E1} \cdot \na \psi$)
\begin{multline}
{\mathrm{RHS}}_{\mathrm{SFINCS, OLD}} =
- f_M \left[\frac{1}{n} \frac{\p n}{\p \psi} + \frac{q}{T} \frac{\p \Phi_0}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2}\right) \frac{1}{T} \frac{\p T}{\p \psi}\right]
\bm{v}_d \cdot \na \psi + \\
\textcolor{blue}{- f_M \left[\frac{1}{n} \frac{\p n}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2}\right) \frac{1}{T} \frac{\p T}{\p \psi}\right]
\bm{v}_{E} \cdot \na \psi}  %+ \\
\textcolor{red}{- f_M \frac{q}{T} v_\| \bm{b} \cdot  \na \Phi_1 }.
\label{eq:DriftKineticSFINCSOldRHS}
\end{multline}
We thus replace
\begin{equation}
\textcolor{red}{
v_\| \bm{b} \cdot  \na \Phi_1
}
\label{eq:ReplaceOLD}
\end{equation}
with
\begin{equation}
\textcolor{red}{
\na \Phi_0 \cdot \bm{v}_{E} + \Phi_1 \frac{\na T}{T} \cdot \bm{v}_d + \Phi_1 \frac{\na T}{T} \cdot \bm{v}_{E}},
\label{eq:ReplaceNEW}
\end{equation}
and make the substitution
\begin{equation}
\textcolor{red}{
f_M \rightarrow f_0 = f_M \exp \left(- q \Phi_1 / T \right)}.
\label{eq:substitution}
\end{equation}
%\remark{In EUTERPE $\Phi_1$ is only an unknown in the quasi-neutrality equation, in the kinetic equation it is an input which means that there are no nonlinearities. It also means that the exponential in $f_0$ is not expanded in the kinetic equation.
%Are all terms in Eq.~\ref{eq:ReplaceNEW} feasible to implement in SFINCS? E.g. is it a problem that the $\Phi_1 \frac{\na T}{T} \cdot \bm{v}_{E}$-term contains 3 factors with $\Phi_1$?}\\
\\

\noindent All terms which contain $\Phi_1$ are now nonlinear.
It does not make sense to have both switches \textbf{includePhi1} and \textbf{nonlinear} still available in SFINCS,
and consequently we will remove the \textbf{nonlinear} switch.
\\

\noindent We will also introduce to possibility to run SFINCS with an adiabatic species.

\newpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section*{Implementation in SFINCS}
Of the equations implemented in SFINCS \cite{SFINCStechnicalDoc}, the only two we need to modify are the kinetic equation
\begin{multline}
R\left(f_{1}, \Phi_1\right) =
K \left\{\theta\right\} \frac{\p f}{\p \theta} + K \left\{\zeta\right\} \frac{\p f}{\p \zeta} +
K \left\{x\right\} \frac{\p f}{\p x} + K \left\{\xi\right\} \frac{\p f}{\p \xi} +
\textcolor{Goldenrod}{K \left\{\psi\right\} \frac{\p f_{M}}{\p \psi}} + \\
- C \left\{f\right\} - S_{1} f_{M} - S_{2} f_{M} x^2 - \frac{Z e v}{T} x \xi \frac{\left\langle \bm{E} \cdot \bm{B} \right\rangle B}{\left\langle B^2 \right\rangle} f_M = 0
\label{eq:KineticEqSFINCS}
\end{multline}
and the quasineutrality equation
\begin{equation}
\sum_s Z_s \int d^3v \, f_s + \lambda = 0.
\label{eq:QuasineutralityEqSFINCS}
\end{equation}
Here $x = v/v_s = v / \sqrt{2T/m}$ and $\xi = v_\| / v$.\\

\noindent In the implementation we need to rewrite all our equations into SFINCS units, using the following identities:\\
$m = \hat{m} \bar{m}$, $n = \hat{n} \bar{n}$, $T = \hat{T} \bar{T}$, $\Phi = \hat{\Phi} \bar{\Phi}$,
$B = \hat{B} \bar{B}$, $B_\zeta = \bar{R} \bar{B} \hat{B}_\zeta$, $B_\theta = \bar{R} \bar{B} \hat{B}_\theta$, $D = \bar{B} \hat{D} / \bar{R}$,
$\bar{v} = \sqrt{2 \bar{T} / \bar{m}}$, $\alpha = e \bar{\Phi} / \bar{T}$,  $\Delta = \bar{m} \bar{v} / \left(e \bar{B} \bar{R} \right)$, $\displaystyle \frac{d X}{d \psi} = \frac{1}{\hat{\psi}_a \bar{R}^2 \bar{B}} \frac{d X}{d \psi_N}$,
$\hat{\psi} = \psi_N \hat{\psi}_a$, $\displaystyle \frac{1}{\hat{\psi}_a} \frac{d X}{d \psi_N} = \frac{d X}{d \hat{\psi}}$
and
$\displaystyle \alpha \cdot \Delta = \frac{e \bar{\Phi}}{\bar{T}} \cdot \frac{\bar{m} \bar{v}}{e \bar{B} \bar{R}} = \frac{2^{1/2} \bar{m}^{1/2} \bar{\Phi}}{\bar{B} \bar{R} \bar{T}^{1/2}}$.
Furthermore, we note that the kinetic equation is made dimensionless by multiplying with the factor
\begin{equation}
  \label{eq:DimensionlessFactor}
  \frac{\bar{v}^3}{\bar{n}} \frac{\bar{R}}{\bar{v}} = \frac{2 \bar{T} \bar{R}}{\bar{m} \bar{n}}.
\end{equation}

\subsubsection*{Newton's method}
In each iteration step we want to calculate the residual and Jacobian of $R\left(\bm{X}\right) = 0$ with $\bm{X} = \left(f_{1}, \Phi_1\right)$.
The residual is $R$ itself, and the Jacobian is $\displaystyle R' = \frac{\delta R\left(\bm{X}\right)}{\delta \bm{X}}$.
The state-vector is updated as
\begin{equation}
  \label{eq:StateVectorUpdate}
  \bm{X}_{n+1} = \bm{X}_{n} - \frac{R\left(\bm{X}_{n}\right)}{R'\left(\bm{X}_{n}\right)}.
\end{equation}

\newpage
\subsection*{Drift-kinetic equation}
For the residual $R\left(f_{1}, \Phi_1\right)$ the only term in the kinetic equation we need to modify is the one in yellow in Eq.~\ref{eq:KineticEqSFINCS}.
We replace $f_M \rightarrow f_0 = f_M \exp \left(- q \Phi_1 / T \right)$,
and use that $K \left\{\psi\right\} = \bm{v}_E \cdot \na \psi + \bm{v}_d \cdot \na \psi = \bm{v}_{E1} \cdot \na \psi + \bm{v}_d \cdot \na \psi$
to write
\begin{multline}
K \left\{\psi\right\} \frac{\p f_{0}}{\p \psi} =  \exp \left(- q \Phi_1 / T \right) \frac{\p f_{M}}{\p \psi} \left(\bm{v}_{E1} \cdot \na \psi + \bm{v}_d \cdot \na \psi\right) = \\ =
\exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \left[\frac{1}{n} \frac{\p n}{\p \psi} + \frac{q}{T} \frac{\p \Phi_0}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2} + \frac{q}{T} \Phi_1\right) \frac{1}{T} \frac{\p T}{\p \psi}\right]
 \left(- \frac{\na \Phi_1 \times \bm{b}}{B} \cdot \na \psi + \bm{v}_d \cdot \na \psi\right) = \\ =
 \left\| - \frac{\na \Phi_1 \times \bm{b}}{B} \cdot \na \psi = - \frac{ \bm{B} \times \na \psi}{B^2} \cdot  \na \Phi_1 =
 \frac{1}{B^2} D \left[B_\theta \frac{\p \Phi_1}{\p \zeta} - B_\zeta \frac{\p \Phi_1}{\p \theta}\right] \right\| = \\ =
 \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \left[\frac{1}{n} \frac{\p n}{\p \psi} + \frac{q}{T} \frac{\p \Phi_0}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2} + \frac{q}{T} \Phi_1\right) \frac{1}{T} \frac{\p T}{\p \psi}\right] \cdot \\
 \left(\frac{1}{B^2} D \left[B_\theta \frac{\p \Phi_1}{\p \zeta} - B_\zeta \frac{\p \Phi_1}{\p \theta}\right] + \bm{v}_d \cdot \na \psi\right)
\label{eq:DKresidualNewTerm1}
\end{multline}
(Here $D = \na \psi \cdot \na \theta \times \na \zeta$.)
Written like this we explicitly see the places where $\Phi_1$ appears in $\displaystyle K \left\{\psi\right\} \frac{\p f_{0}}{\p \psi}$.
From Eq.~\ref{eq:DKresidualNewTerm1} we obtain the corresponding terms in the Jacobian matrix
\begin{multline}
\frac{\delta}{\delta \Phi_1} \left(K \left\{\psi\right\} \frac{\p f_{0}}{\p \psi}\right) = \textcolor{orange}{
- \frac{q}{T}
 \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \left[\frac{1}{n} \frac{\p n}{\p \psi} + \frac{q}{T} \frac{\p \Phi_0}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2} + \frac{q}{T} \Phi_1\right) \frac{1}{T} \frac{\p T}{\p \psi}\right] \cdot} \\ \textcolor{orange}{
 \left(\frac{1}{B^2} D \left[B_\theta \frac{\p \Phi_1}{\p \zeta} - B_\zeta \frac{\p \Phi_1}{\p \theta}\right] + \bm{v}_d \cdot \na \psi\right)} \, + \\ + \,\textcolor{green}{
 \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \frac{q}{T} \frac{1}{T} \frac{\p T}{\p \psi} \left(\frac{1}{B^2} D \left[B_\theta \frac{\p \Phi_1}{\p \zeta} - B_\zeta \frac{\p \Phi_1}{\p \theta}\right] + \bm{v}_d \cdot \na \psi\right)} \, + \\ + \,
\textcolor{brown}{
 \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \left[\frac{1}{n} \frac{\p n}{\p \psi} + \frac{q}{T} \frac{\p \Phi_0}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2} + \frac{q}{T} \Phi_1\right) \frac{1}{T} \frac{\p T}{\p \psi}\right] \cdot} \\ \textcolor{brown}{
 \left(\frac{1}{B^2} D \left[B_\theta \frac{\p }{\p \zeta} - B_\zeta \frac{\p }{\p \theta}\right]\right)}
\label{eq:DKJacobianNewTerm1}
\end{multline}

\subsubsection*{Residual}
Many of the terms involving $\bm{v}_d \cdot \na \psi$ are almost implemented in SFINCS already except that they now contain the $\exp \left(- \frac{q \Phi_1}{T}  \right)$-factor.
We therefore rewrite Eq.~\ref{eq:DKresidualNewTerm1} as
\begin{equation}
K \left\{\psi\right\} \frac{\p f_{0}}{\p \psi} = R_m + R_E
\label{eq:DKresidualNewTermSplit}
\end{equation}
where
\begin{equation}
R_m = \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \left[\frac{1}{n} \frac{\p n}{\p \psi} + \frac{q}{T} \frac{\p \Phi_0}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2} + \frac{q}{T} \Phi_1\right) \frac{1}{T} \frac{\p T}{\p \psi}\right] \bm{v}_d \cdot \na \psi
\label{eq:DKresidualNewTermRm}
\end{equation}
and
\begin{equation}
R_E = \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \left[\frac{1}{n} \frac{\p n}{\p \psi} + \frac{q}{T} \frac{\p \Phi_0}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2} + \frac{q}{T} \Phi_1\right) \frac{1}{T} \frac{\p T}{\p \psi}\right] \frac{1}{B^2} D \left[B_\theta \frac{\p \Phi_1}{\p \zeta} - B_\zeta \frac{\p \Phi_1}{\p \theta}\right].
\label{eq:DKresidualNewTermRE}
\end{equation}

\paragraph*{$\bm{R_m}$}
$R_m$ will be implemented in evaluateResidual.F90. We write the term as
\begin{multline}
R_m = \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \left[\frac{1}{n} \frac{\p n}{\p \psi} + \frac{q}{T} \frac{\p \Phi_0}{\p \psi} + \left(x^2 - \frac{3}{2}\right) \frac{1}{T} \frac{\p T}{\p \psi}\right] \bm{v}_d \cdot \na \psi + \\ +  \textcolor{red}{
  \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \frac{q}{T} \Phi_1 \frac{1}{T} \frac{\p T}{\p \psi} \bm{v}_d \cdot \na \psi }.
\label{eq:DKresidualNewTermRm2}
\end{multline}
Note that the first term in Eq.~\ref{eq:DKresidualNewTermRm2} can only be implemented in evaluateResidual.F90, since it is not of the form $L\left[\Phi_1\right]$ where $L\left[\right]$ is a linear operator.\\
The first term in Eq.~\ref{eq:DKresidualNewTermRm2} is already implemented in evaluateResidual.F90 except for the factor
\[
\exp \left(- \frac{q \Phi_1}{T}  \right) = \exp \left(- \frac{Z \alpha \hat{\Phi}_1}{\hat{T}}  \right)
\]
which has to be added.\\
The second term in Eq.~\ref{eq:DKresidualNewTermRm2} we rewrite in SFINCS units (also considering the factor Eq.~\ref{eq:DimensionlessFactor}) as
\begin{multline}
\textcolor{red}{
\left(\exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \frac{q}{T} \Phi_1 \frac{1}{T} \frac{\p T}{\p \psi} \bm{v}_d \cdot \na \psi\right)_{\mathrm{SFINCS}} = } \\ \textcolor{red}{ =
\frac{\alpha \Delta}{3 \pi^{3/2}} \frac{\hat{n} \hat{m}^{3/2} \hat{D}}{\hat{T}^{5/2} \hat{B}^3 } \hat{\Phi}_1 \frac{\p \hat{T}}{\p \hat{\psi}}
x^2 \left(P_2\left(\xi\right) + 2 P_0\right)
\exp\left(-x^2\right) \exp \left(- \frac{Z \alpha \hat{\Phi}_1}{\hat{T}}\right) \left[\hat{B}_{\theta} \frac{\p \hat{B}}{\p \zeta} - \hat{B}_{\zeta} \frac{\p \hat{B}}{\p \theta}\right].
}
\label{eq:Rmterm2}
\end{multline}
The first term in Eq.~\ref{eq:DKresidualNewTermRm2} becomes
\begin{multline}
\left(\exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \left[\frac{1}{n} \frac{\p n}{\p \psi} + \frac{q}{T} \frac{\p \Phi_0}{\p \psi} + \left(x^2 - \frac{3}{2}\right) \frac{1}{T} \frac{\p T}{\p \psi}\right] \bm{v}_d \cdot \na \psi \right)_{\mathrm{SFINCS}} = \\ = \frac{1}{Z}
\frac{\Delta}{3 \pi^{3/2}} \frac{\hat{n} \hat{m}^{3/2} \hat{D}}{\hat{T}^{1/2} \hat{B}^3 }
x^2 \left(P_2\left(\xi\right) + 2 P_0\right)
\exp\left(-x^2\right) \exp \left(- \frac{Z \alpha \hat{\Phi}_1}{\hat{T}}\right) \left[\hat{B}_{\theta} \frac{\p \hat{B}}{\p \zeta} - \hat{B}_{\zeta} \frac{\p \hat{B}}{\p \theta}\right] \cdot \\ \cdot
\left[\frac{1}{\hat{n}} \frac{\p \hat{n}}{\p \hat{\psi}} + \frac{Z \alpha}{\hat{T}} \frac{\p \hat{\Phi}_0}{\p \hat{\psi}} + \left(x^2 - \frac{3}{2}\right) \frac{1}{\hat{T}} \frac{\p \hat{T}}{\p \hat{\psi}}\right].
\label{eq:Rmterm1}
\end{multline}

\paragraph*{$\bm{R_E}$}
$R_E$ we will instead implement in populateMatrix.F90. We write the term as
\begin{multline}
R_E = \textcolor{blue}{
\exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \left[\frac{1}{n} \frac{\p n}{\p \psi}  + \left(x^2 - \frac{3}{2} \right) \frac{1}{T} \frac{\p T}{\p \psi}\right] \frac{1}{B^2} D \left[B_\theta \frac{\p }{\p \zeta} - B_\zeta \frac{\p }{\p \theta}\right] \Phi_1} + \\ +
\textcolor{magenta}{
\exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \frac{q}{T} \frac{\p \Phi_0}{\p \psi} \frac{1}{B^2} D \left[B_\theta \frac{\p }{\p \zeta} - B_\zeta \frac{\p }{\p \theta}\right]\Phi_1 } + \\ +
 \textcolor{cyan}{
 \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \frac{q}{T} \Phi_1 \frac{1}{T} \frac{\p T}{\p \psi} \frac{1}{B^2} D \left[B_\theta \frac{\p }{\p \zeta} - B_\zeta \frac{\p }{\p \theta}\right] \Phi_1}.
\label{eq:DKresidualNewTermRE2}
\end{multline}
Note that in the code when evaluating the residual, the matrix added in populateMatrix.F90 is multiplied by the state-vector in evaluateResidual.F90 and therefore the rightmost $\Phi_1$ should not be added inside populateMatrix.F90.\\
The first term in Eq.~\ref{eq:DKresidualNewTermRE2} is already implemented in populateMatrix.F90 except for the factor
\[
\exp \left(- \frac{q \Phi_1}{T}  \right) = \exp \left(- \frac{Z \alpha \hat{\Phi}_1}{\hat{T}}  \right)
\]
which has to be added.\\
The second term in Eq.~\ref{eq:DKresidualNewTermRE2} we rewrite in SFINCS units (also considering the factor Eq.~\ref{eq:DimensionlessFactor}) as
\begin{multline}
\textcolor{magenta}{
\left(\exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \frac{q}{T} \frac{\p \Phi_0}{\p \psi} \frac{1}{B^2} D \left[B_\theta \frac{\p \Phi_1}{\p \zeta} - B_\zeta \frac{\p \Phi_1}{\p \theta}\right] \right)_{\mathrm{SFINCS}} } = \\ = \textcolor{magenta}{
\frac{Z \alpha^2 \Delta}{2 \pi^{3/2}} \frac{\hat{n} \hat{m}^{3/2} \hat{D}}{\hat{T}^{5/2} \hat{B}^2 } \frac{\p \hat{\Phi}_0}{\p \hat{\psi}}
\exp\left(-x^2\right) \exp \left(- \frac{Z \alpha \hat{\Phi}_1}{\hat{T}}\right) \left[\hat{B}_{\theta} \frac{\p}{\p \zeta} - \hat{B}_{\zeta} \frac{\p}{\p \theta}\right] \hat{\Phi}_1.
}
\label{eq:REterm2}
\end{multline}
The third term in Eq.~\ref{eq:DKresidualNewTermRE2} we rewrite in SFINCS units (also considering the factor Eq.~\ref{eq:DimensionlessFactor}) as
\begin{multline}
\textcolor{cyan}{
\left(\exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \frac{q}{T} \Phi_1 \frac{1}{T} \frac{\p T}{\p \psi} \frac{1}{B^2} D \left[B_\theta \frac{\p \Phi_1}{\p \zeta} - B_\zeta \frac{\p \Phi_1}{\p \theta}\right]\right)_{\mathrm{SFINCS}}} = \\ = \textcolor{cyan}{
\frac{Z \alpha^2 \Delta}{2 \pi^{3/2}} \frac{\hat{n} \hat{m}^{3/2} \hat{D}}{\hat{T}^{7/2} \hat{B}^2 } \frac{\p \hat{T}}{\p \hat{\psi}} \hat{\Phi}_1
\exp\left(-x^2\right) \exp \left(- \frac{Z \alpha \hat{\Phi}_1}{\hat{T}}\right) \left[\hat{B}_{\theta} \frac{\p}{\p \zeta} - \hat{B}_{\zeta} \frac{\p}{\p \theta}\right] \hat{\Phi}_1.
}
\label{eq:REterm3}
\end{multline}
The first term in Eq.~\ref{eq:DKresidualNewTermRE2} in SFINCS units (also considering the factor Eq.~\ref{eq:DimensionlessFactor}) is
\begin{multline}
\textcolor{blue}{ \left(
\exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \left[\frac{1}{n} \frac{\p n}{\p \psi}  + \left(x^2 - \frac{3}{2} \right) \frac{1}{T} \frac{\p T}{\p \psi}\right] \frac{1}{B^2} D \left[B_\theta \frac{\p }{\p \zeta} - B_\zeta \frac{\p }{\p \theta}\right] \Phi_1\right)_{\mathrm{SFINCS}} } = \\ =
\textcolor{blue}{
\frac{\alpha \Delta}{2 \pi^{3/2}} \frac{\hat{n} \hat{m}^{3/2} \hat{D}}{\hat{T}^{3/2} \hat{B}^2 }  \left[\frac{1}{\hat{n}} \frac{\p \hat{n}}{\p \hat{\psi}}  + \left(x^2 - \frac{3}{2} \right) \frac{1}{\hat{T}} \frac{\p \hat{T}}{\p \hat{\psi}}\right]
\exp\left(-x^2\right) \exp \left(- \frac{Z \alpha \hat{\Phi}_1}{\hat{T}}\right) \left[\hat{B}_{\theta} \frac{\p}{\p \zeta} - \hat{B}_{\zeta} \frac{\p}{\p \theta}\right] \hat{\Phi}_1.
}
\label{eq:REterm1}
\end{multline}

\paragraph*{\textbf{Files to change:}}
\begin{verbatim}
evaluateResidual.F90
populateMatrix.F90
\end{verbatim}

\subsubsection*{Jacobian}
The Jacobian terms will be implemented in populateMatrix.F90.
In the code we use SFINCS units, and the Jacobian is calculated from taking the derivative of the residual in SFINCS units with respect to the state-vector in SFINCS units (also considering the factor Eq.~\ref{eq:DimensionlessFactor}). This implies that what we are calculating here is
\[
\frac{\delta}{\delta \hat{\Phi}_1} \left(\hat{R}_m + \hat{R}_E\right),
\]
where $\hat{R}_m$ and $\hat{R}_E$ are how the components of the residual are written in SFINCS. \\
We see that the \textcolor{brown}{last term} in the Jacobian in Eq.~\ref{eq:DKJacobianNewTerm1} corresponds to $R_E$ in Eq.~ \ref{eq:DKresidualNewTermRE} (since the rightmost $\Phi_1$ in the residual is not implemented in populateMatrix.F90),
so this term is already implemented by the residual.\\
%%\remark{Is there no difference implementationwise, when $\Phi_1$ disappears in the space derivative?}

\noindent The other two terms should only be added when 'whichMatrix==0' or 'whichMatrix==1'.
The \textcolor{orange}{first term} in the Jacobian is the residual multiplied by $- q / T$. However, since the exponential is
$ \displaystyle
\exp \left(- \frac{q \Phi_1}{T}  \right) = \exp \left(- \frac{Z \alpha \hat{\Phi}_1}{\hat{T}}  \right),
$
in SFINCS the term will be implemented as
\begin{equation}
  \label{eq:JacobianFirstTerm1}
  \textcolor{orange}{- \frac{Z \alpha}{\hat{T}}  \left(\hat{R}_m + \hat{R}_E\right)}.
\end{equation}

\noindent The \textcolor{green}{second term} in the Jacobian can be written as
\begin{multline}
  \label{eq:JacobianSecondTerm1}
  \textcolor{green}{
 \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \frac{q}{T} \frac{1}{T} \frac{\p T}{\p \psi} \left(\frac{1}{B^2} D \left[B_\theta \frac{\p \Phi_1}{\p \zeta} - B_\zeta \frac{\p \Phi_1}{\p \theta}\right] + \bm{v}_d \cdot \na \psi\right)} = \\ = \textcolor{green}{
\frac{1}{\Phi_1}} \left(
\textcolor{cyan}{
 \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \frac{q}{T} \Phi_1 \frac{1}{T} \frac{\p T}{\p \psi} \frac{1}{B^2} D \left[B_\theta \frac{\p }{\p \zeta} - B_\zeta \frac{\p }{\p \theta}\right] \Phi_1}
+
\textcolor{red}{
  \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \frac{q}{T} \Phi_1 \frac{1}{T} \frac{\p T}{\p \psi} \bm{v}_d \cdot \na \psi }
\right),
\end{multline}
where the two terms inside the brackets have already been implemented in $R_E$ and $R_m$ respectively. Consequently, to obtain this term we sum these two terms written in code units, and multiply by $1 / \hat{\Phi}_1$.\\
Although the \textcolor{orange}{first term} and the \textcolor{green}{second term} of the Jacobian consist of terms available in other terms, we need to rewrite them since we cannot access code in evaluateResidual.F90 from populateMatrix.F90, and also the residual terms in populateMatrix.F90 contain a factor $\Phi_1$ less which instead is in the state-vector.

% \begin{multline}
% K \left\{\psi\right\} \frac{\p f_{M}}{\p \psi}  =
% %%
%  \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \left[\frac{1}{n} \frac{\p n}{\p \psi} + \frac{q}{T} \frac{\p \Phi_0}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2} + \frac{q}{T} \Phi_1\right) \frac{1}{T} \frac{\p T}{\p \psi}\right]  \bm{v}_d \cdot \na \psi \, + \\ + \,
%  \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \left[\frac{1}{n} \frac{\p n}{\p \psi} + \frac{q}{T} \frac{\p \Phi_0}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2} + \frac{q}{T} \Phi_1\right) \frac{1}{T} \frac{\p T}{\p \psi}\right] \frac{1}{B^2} D \left[B_\theta \frac{\p \Phi_1}{\p \zeta} - B_\zeta \frac{\p \Phi_1}{\p \theta}\right] = \\ =
%  %%
%  \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \left[\frac{1}{n} \frac{\p n}{\p \psi} + \frac{q}{T} \frac{\p \Phi_0}{\p \psi} + \left(\frac{m v^2}{2 T} - \frac{3}{2} \right) \frac{1}{T} \frac{\p T}{\p \psi}\right]  \bm{v}_d \cdot \na \psi \, + \\ + \,
%  \textcolor{blue}{
%  \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \left[\frac{1}{n} \frac{\p n}{\p \psi}  + \left(\frac{m v^2}{2 T} - \frac{3}{2} \right) \frac{1}{T} \frac{\p T}{\p \psi}\right] \frac{1}{B^2} D \left[B_\theta \frac{\p \Phi_1}{\p \zeta} - B_\zeta \frac{\p \Phi_1}{\p \theta}\right]} \, + \\ + \,
%  \textcolor{red}{
%   \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \frac{q}{T} \Phi_1 \frac{1}{T} \frac{\p T}{\p \psi} \bm{v}_d \cdot \na \psi } \, + \\ + \,
%   \textcolor{magenta}{
%   \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \frac{q}{T} \frac{\p \Phi_0}{\p \psi} \frac{1}{B^2} D \left[B_\theta \frac{\p \Phi_1}{\p \zeta} - B_\zeta \frac{\p \Phi_1}{\p \theta}\right] } \, + \\ + \,
%   \textcolor{cyan}{
%   \exp \left(- \frac{q \Phi_1}{T}  \right) f_{M} \frac{q}{T} \Phi_1 \frac{1}{T} \frac{\p T}{\p \psi} \frac{1}{B^2} D \left[B_\theta \frac{\p \Phi_1}{\p \zeta} - B_\zeta \frac{\p \Phi_1}{\p \theta}\right] }
% \label{eq:DKresidualNewTerm2}
% \end{multline}

\paragraph*{\textbf{Files to change:}}
\begin{verbatim}
populateMatrix.F90
\end{verbatim}

\subsubsection*{Additional implementation related to the kinetic equation}
Besides implementing the above terms, we need to remove the former term in SFINCS corresponding to $\displaystyle \frac{Z e}{T} f_M v_\| \na_\| \Phi_1$. \\
\\
We will remove the \textbf{nonlinear} switch from the code, since all terms related to $\Phi_1$ are now nonlinear.
The \textbf{nonlinear} switch will be incorporated into the \textbf{includePhi1} switch.\\
\\
We will replace the \textbf{includeRadialExBDrive} switch with the \textbf{includePhi1inKineticEquation} switch which is \textbf{true} by default.
This new switched can be set to \textbf{false} if one only wants to include $\Phi_1$ in the quasi-neutrality equation.

\paragraph*{\textbf{Files to change:}}
\begin{verbatim}
globalVariables.F90
populateMatrix.F90
preallocateMatrix.F90
readInput.F90
sfincs.F90
solver.F90
validateInput.F90
\end{verbatim}

\newpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newpage
\subsection*{Quasi-neutrality equation}
In EUTERPE $\Phi_1$ is calculated from quasi-neutrality by expanding the exponential, assuming adiabatic electrons and neglecting the impurities.
However, this is not a generic quasi-neutrality equation and in SFINCS we can easily implement the full equation.
To be able to compare to results from EUTERPE we will allow for both possibilities in the code, and implement an adiabatic species.
The option \textbf{quasineutralityOption = 1} corresponds to the full quasi-neutrality equation and is the default,
whereas \textbf{quasineutralityOption = 2} corresponds to the EUTERPE equations.

\subsubsection*{Adiabatic species}
We will allow for the possibility to run SFINCS with an adiabatic species.
The following input parameters will be introduced (with their default values in brackets) in the \textbf{speciesParameters} namelist:
\begin{verbatim}
logical :: withAdiabatic  (.false.)
PetscScalar :: adiabaticZ  (-1)
PetscScalar :: adiabaticMHat  (5.446170214d-4)
PetscScalar :: adiabaticNHat  (1.0)
PetscScalar :: adiabaticTHat  (1.0)
\end{verbatim}
Note that the
adiabatic species will only enter into the quasi-neutrality equation,
we neglect its collisional impact on the kinetic species (the adiabatic species will typically be electrons, and the effect of ion-electron collisions is small compared to ion-ion collisions).

\paragraph*{\textbf{Files to change:}}
\begin{verbatim}
globalVariables.F90
populateMatrix.F90
readInput.F90
sfincs.F90
validateInput.F90
writeHDF5Output.F90
\end{verbatim}

\subsubsection*{Full quasi-neutrality equation, quasineutralityOption = 1}

Firstly, we need to make sure that the input densities fulfill quasi-neutrality (also considering the adiabatic species if it is used):
\begin{equation}
  \label{eq:QuasiNeutralityInputFull}
  \sum_s Z_s \hat{n}_s = 0.
\end{equation}
%
The densities can be written
\begin{equation}
n_s = n_{s 0} \left(\psi\right) \, \exp \left(- q_s \Phi_1 / T_s \right) + n_{s 1},
\label{eq:DensityParts}
\end{equation}
and the quasi-neutrality equation is
\begin{equation}
\sum_s Z_s n_s = 0.
\label{eq:Quasineutrality}
\end{equation}
For an adiabatic species $a$
\[
n_{a 1} = 0.
\]
The velocity integration in SFINCS is done in $\left(x, \xi\right) = \left(v / v_s, v_\| / v\right)$, and
\begin{equation}
\int d^3 v = 2 \pi v_{s}^3 \int_{0}^{\infty} dx\, x^2 \int_{-1}^{1} d\xi
\label{eq:VelocityIntegration}
\end{equation}
where $v_{s} = \sqrt{2 T_s / m_s}$.
Since
\begin{equation}
  \label{eq:ns1Int}
  n_{s 1} = \int d^3 v \, f_{s 1},
\end{equation}
we can rewrite quasi-neutrality in form of its contribution to the residual of the full linear system as
\begin{equation}
R_{QN}\left(f_{1}, \Phi_1\right) = \sum_s Z_s n_{s0} \exp\left(- \frac{Z_s e \Phi_1}{T_s}\right) + 2\pi \sum_{s \setminus a} v_s^3 Z_s \int_0^{\infty} dx \, x^2 \int_{-1}^1 d\xi \, f_{s 1} = 0
\label{eq:Quasineutrality}
\end{equation}
(note that the adiabatic species is excluded in the second summation).\\

\noindent In SFINCS we add a Lagrange multiplier $\lambda$, divide Eq.~\ref{eq:Quasineutrality} by $\bar{n}$, and use $n = \hat{n} \bar{n}$, $\bar{v} = \sqrt{2 \bar{T} / \bar{m}}$, $v_s / \bar{v} = \sqrt{\hat{T}_s / \hat{m}_s}$, $f_s = \bar{n} \hat{f}_s / \bar{v}^3$, $ \displaystyle
\exp \left(- \frac{q_s \Phi_1}{T_s}  \right) = \exp \left(- \frac{Z_s \alpha \hat{\Phi}_1}{\hat{T}_s}  \right)
$, to write
\begin{multline}
\hat{R}_{QN}\left(\hat{f}_{1}, \hat{\Phi}_1, \lambda\right) = \textcolor{JungleGreen}{
\sum_s Z_s \hat{n}_{s0} \exp \left(- \frac{Z_s \alpha \hat{\Phi}_1}{\hat{T}_s}  \right)} + \\ +
\textcolor{MidnightBlue}{
2\pi \sum_{s \setminus a} Z_s \left(\frac{\hat{T}_s}{\hat{m}_s}\right)^{3/2} \int_0^{\infty} dx \, x^2 \int_{-1}^1 d\xi \, \hat{f}_{s 1} \, + \, \lambda } = 0.
\label{eq:QuasineutralitySFINCS}
\end{multline}
The first term in Eq.~\ref{eq:QuasineutralitySFINCS} must be implemented in evaluateResidual.F90 because it does not include a linear operation on $\hat{\Phi}_1$.
The other terms will be implemented in populateMatrix.F90.\\

\noindent When implementing the Jacobian terms, we note that
\begin{equation}
  \label{eq:QNJacobianf1}
\textcolor{MidnightBlue}{
  \frac{\delta \hat{R}_{QN}}{\delta \hat{f}_{s 1}} = 2\pi Z_s \left(\frac{\hat{T}_s}{\hat{m}_s}\right)^{3/2} \int_0^{\infty} dx \, x^2 \int_{-1}^1 d\xi},
\end{equation}
\begin{equation}
  \label{eq:QNJacobianLambda}
\textcolor{MidnightBlue}{
  \frac{\delta \hat{R}_{QN}}{\delta \lambda} = 1},
\end{equation}
which means that these two terms are the same as the corresponding terms in the residual and are thus implemented in populateMatrix.F90.
Moreover,
\begin{equation}
  \label{eq:QNJacobianPhi1}
\textcolor{JungleGreen}{
  \frac{\delta \hat{R}_{QN}}{\delta \hat{\Phi}_1} = -
\sum_s  \frac{Z_s^2 \alpha}{\hat{T}_s} \hat{n}_{s0} \exp \left(- \frac{Z_s \alpha \hat{\Phi}_1}{\hat{T}_s}  \right)}
\end{equation}
will also be implemented in populateMatrix.F90 when 'whichMatrix==0' or 'whichMatrix==1'.
\\

\noindent Note that, since the distribution function in SFINCS is stored as an expansion in Legendre polynomials in $\xi$
\[
\hat{f}_{s 1}\left(\theta, \zeta, x, \xi\right) = \sum_{l=0}^{N_l} \hat{f}_{s 1}^{\left(l\right)}\left(\theta, \zeta, x\right) P_l \left(\xi\right),
\]
and using that
\[
\int_{-1}^1 P_m\left(\xi\right) P_n\left(\xi\right) = \frac{2}{2n + 1} \delta_{m,n}
\]
the integration over $\xi$ in Eq.~\ref{eq:QuasineutralitySFINCS} becomes
\begin{equation}
  \label{eq:xiIntegration}
  \int_{-1}^1 d\xi \, f_{s 1} = \int_{-1}^1 d\xi \, \left(\sum_{l=0}^{N_l} \hat{f}_{s 1}^{\left(l\right)}\left(\theta, \zeta, x\right) P_l \left(\xi\right)\right) \cdot P_0 \left(\xi\right) = 2 \cdot  \hat{f}_{s 1}^{\left(0\right)}\left(\theta, \zeta, x\right).
\end{equation}

\paragraph*{\textbf{Files to change:}}
\begin{verbatim}
evaluateResidual.F90
populateMatrix.F90
validateInput.F90
\end{verbatim}

\subsubsection*{EUTERPE quasi-neutrality equation, quasineutralityOption = 2}
For the EUTERPE equations, the code must be run with
an adiabatic species and only one kinetic species (the first) is considered in the quasi-neutrality equation.
We need to make sure that the input densities fulfill quasi-neutrality:
\begin{equation}
  \label{eq:QuasiNeutralityInputFull}
   Z_i \hat{n}_{i} + Z_a \hat{n}_{a} = 0
\end{equation}
(here species $i$ would be the first kinetic species and $a$ the adiabatic).\\
Again we use
\begin{equation}
n_s = n_{s 0} \left(\psi\right) \, \exp \left(- q_s \Phi_1 / T_s \right) + n_{s 1},
\label{eq:DensityParts2}
\end{equation}
\begin{equation}
\sum_s Z_s n_s = 0,
\label{eq:Quasineutrality2}
\end{equation}
but here we Taylor expand the exponential to $1^{\mathrm{st}}$ order and write
\begin{multline}
\label{eq:QuasineutralityExpanded}
%\Rightarrow \;\;\;
0 \simeq \sum_s Z_s \left[n_{s 0} \left(1 - q_s \Phi_1 / T_s \right) + n_{s 1}\right] \;\;\; \Leftrightarrow \\
\sum_s Z_s \left[n_{s 0} + n_{s 1}\right] = \sum_s \frac{Z_s^2 e}{T_s} \Phi_1 n_{s 0} .
\end{multline}
%Since $n_{s 0} \left(\psi\right)$ is obtained by integrating the Maxwellian $f_{M s}$ over velocity space we must have
From the condition of quasi-neutral input we know that
\[
\sum_s Z_s n_{s 0} = 0,
\]
which yields
\begin{equation}
\sum_s Z_s n_{s 1} - \Phi_1 \sum_s \frac{Z_s^2 e}{T_s} n_{s 0}  = 0.
\label{eq:Quasineutrality2}
\end{equation}
With kinetic ions, adiabatic electrons ($n_{a 1} = 0$) and neglecting other ion species we obtain
\begin{equation}
\Phi_1 = \frac{T_a}{Z_a^2 e} \left[\frac{Z_i^2 T_a}{Z_a^2 T_i} n_{i 0} + n_{a 0}\right]^{-1} Z_i n_{i 1}.
\label{eq:Phi1}
\end{equation}
%
%\subsection*{Implementation in SFINCS}
%For a first benchmark, we want to implement the same equations as EUTERPE in SFINCS. \\
%\remark{This is not a very generic quasi-neutrality equation so it is possible that we might want to change it in SFINCS later.} \\
%In the code we add an adiabatic species which only enters into the quasi-neutrality equation, and neglect its collisional impact on the kinetic species (the effect of ion-electron collisions is small compared to ion-ion collisions).
%Moreover, we will only consider the first of the kinetic species in quasi-neutrality and neglect the rest.
%This is implemented by modifying the LHS of the row corresponding to quasi-neutrality in the block-matrix structure of Matt's ISHW poster, adding the adiabatic term to the $\Phi_1$-column and removing all kinetic species except the first. \\
% \remark{It feels a bit weird to remove species from quasi-neutrality, even if the impurity density is small. Does this mean that we should removed the check that the input densities are quasi-neutral and instead check that $n_{i 0} \left(\psi\right) = n_{e 0} \left(\psi\right)$ in the input?}\\
The equation we will implement in SFINCS is thus
\begin{equation}
Z_i n_{i 1} - \Phi_1 \left[ \frac{Z_i^2 e}{T_i} n_{i 0} + \frac{Z_a^2 e}{T_a} n_{a 0}\right] = 0.
\label{eq:QuasineutralityIonElectrons}
\end{equation}
We note that
\begin{multline}
n_s = n_{s 0} \left(\psi\right) \, \exp \left(- q_s \Phi_1 / T_s \right) + n_{s 1} = \int d^3 v f_{Ms} \exp \left(- q_s \Phi_1 / T_s \right) + \int d^3 v f_{1 s} = \\ =
d^3 v f_{0 s} + d^3 v f_{1 s}.
\label{eq:distributionToDensity}
\end{multline}
The velocity integration is SFINCS is done in $\left(x, \xi\right) = \left(v / v_s, v_\| / v\right)$, and
\begin{equation}
\int d^3 v = 2 \pi v_{s}^3 \int_{0}^{\infty} dx\, x^2 \int_{-1}^{1} d\xi
\label{eq:VelocityIntegration2}
\end{equation}
(note that $v_{s}^2 = 2 T_s/m_s$ differs from Jose's notation $v_{\mathrm{th}}^2 = T/m$).
Using SFINCS normalizations $n_s = \bar{n}  \hat{n}_s$, $T_s = \bar{T}  \hat{T}_s$, $v_s / \bar{v} = \sqrt{\hat{T}_s / \hat{m}_s}$,
$f_s = \bar{n} \hat{f}_s / \bar{v}^3$,
we find
\begin{equation}
\hat{n}_s = 2 \pi \left(\hat{T}_s / \hat{m}_s\right)^{3/2} \int_{0}^{\infty} dx\, x^2 \int_{-1}^{1} d\xi \hat{f}_s.
\label{eq:VelocityIntegrationSFINCS}
\end{equation}
Also using $\Phi_1 = \bar{\Phi} \hat{\Phi}_1$ and $\alpha = e \bar{\Phi} / \bar{T}$ we can write Eq.~\ref{eq:QuasineutralityIonElectrons}
\begin{equation}
Z_i \hat{n}_{i 1} - \alpha \hat{\Phi}_1 \left[ \frac{Z_i^2}{\hat{T}_i} \hat{n}_{i 0} + \frac{Z_a^2}{\hat{T}_a} \hat{n}_{a 0}\right] = 0
\label{eq:QuasineutralityIonElectronsSFINCS}
\end{equation}
and finally obtain the residual
\begin{equation}
\hat{R}_{QN}^{\mathrm{EUTERPE}}\left(\hat{f}_{i 1}, \hat{\Phi}_1, \lambda\right) =
\left[2 \pi Z_i \left(\hat{T}_i / \hat{m}_i\right)^{3/2} \int_{0}^{\infty} dx\, x^2 \int_{-1}^{1} d\xi \hat{f}_{i 1}\right]
- \alpha \hat{\Phi}_1 \left[ \frac{Z_i^2}{\hat{T}_i} \hat{n}_{i 0} + \frac{Z_a^2}{\hat{T}_a} \hat{n}_{a 0}\right] \, + \, \lambda = 0.
\label{eq:QuasineutralityIonElectronsSFINCS2}
\end{equation}
%This is the equation we will implement in the code, but adding a $\lambda$ to make the system square.\\
% \remark{Is the $2\pi$ factor correct in Eq.~\ref{eq:QuasineutralityIonElectronsSFINCS2}? It is not in the former implementation of quasi-neutrality, but in that situation it could be divided away.}
Since the residual has a linear operator dependence on all unknown variables, both the Jacobian and the residual can be implemented in populateMatrix.F90 with the same equations.

\paragraph*{\textbf{Files to change:}}
\begin{verbatim}
populateMatrix.F90
validateInput.F90
\end{verbatim}

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

\subsection*{Additional changes}
Decide which output fluxes should be possible to obtain, i.e. which combinations of
\begin{equation}
  \label{eq:OutputFluxes}
  \langle \int d^3 v \, f \bm{v} \cdot \na X \rangle,
\end{equation}
should be possible?
Here $f$ can be $f_0$, $f_1$ or $f_0 + f_1$.
$\bm{v}$ can be $\bm{v}_E$, $\bm{v}_m$ or $\bm{v}_E + \bm{v}_m$.
$X$ can be any of the radial coordinates, $r$, $r_N$, $\psi$ or $\psi_N$. \\

\noindent Allow for the output fluxes in SI units.\\

\noindent In all output flux quantities the substitution
\[
\textcolor{red}{
f_M \rightarrow f_0 = f_M \exp \left(- q \Phi_1 / T \right)}
\]
must be made.
\paragraph*{\textbf{Files to change:}}
\begin{verbatim}
diagnostics.F90
\end{verbatim}

\newpage
%\appendix
\titleformat{\section}{\large\bfseries}{\appendixname~\thesection .}{0.5em}{}

\begin{appendices}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Check of Matt's former implementation of $\displaystyle \frac{Z e}{T} f_M v_\| \na_\| \Phi_1$}
\textbf{This section is only to compare to what has already been implemented in SFINCS, to see that we understand the normalizations.}\\
\\
Looking at Matt's ISHW poster, since $\Phi_1$ is an unknown this term is in the LHS of the square block matrix system.
The term is accessed by ``rowIndex = BLOCK\_F'' and ``colIndex = BLOCK\_QN''.
We use
\[
\na_\| \Phi_1 = \bm{b} \cdot \na \Phi_1 = \frac{1}{B} \left[ B^{\theta} \frac{\p \Phi_1}{\p \theta} + B^{\zeta} \frac{\p \Phi_1}{\p \zeta} \right] =
\frac{\bar{\Phi}}{\hat{B} \bar{R}} \left[ \hat{B}^{\theta} \frac{\p \hat{\Phi}_1}{\p \theta} + \hat{B}^{\zeta} \frac{\p \hat{\Phi}_1}{\p \zeta} \right],
\]
\[
f_M = n_0\left(\psi\right) \frac{m^{3/2}}{\left(2 \pi T\right)^{3/2}} \exp \left[- \frac{v^2}{v_{s}^2}\right] =
\hat{n} \bar{n} \frac{\hat{m}^{3/2}}{\left(2 \pi \hat{T}\right)^{3/2}} \left(\frac{\bar{m}}{\bar{T}}\right)^{3/2} \exp \left[- x^2\right],
\]
$v_\| = v_s x \xi = v_s x P_1 = x P_1 \sqrt{2 \hat{T} / \hat{m}} \sqrt{\bar{T} / \bar{m}} $ and $x = v / v_s$.
With $\alpha = e \bar{\Phi} / \bar{T}$ we obtain
\begin{multline}
\frac{Z e}{T} f_M v_\| \na_\| \Phi_1 = \frac{Z e}{\hat{T} \bar{T}} \, \hat{n} \bar{n} \frac{\hat{m}^{3/2}}{\left(2 \pi \hat{T}\right)^{3/2}} \left(\frac{\bar{m}}{\bar{T}}\right)^{3/2} \exp \left[- x^2\right] \, x P_1 \sqrt{2 \hat{T} / \hat{m}} \sqrt{\bar{T} / \bar{m}} \, \frac{\bar{\Phi}}{\hat{B} \bar{R}} \left[ \hat{B}^{\theta} \frac{\p \hat{\Phi}_1}{\p \theta} + \hat{B}^{\zeta} \frac{\p \hat{\Phi}_1}{\p \zeta} \right] = \\ =
 \frac{Z \alpha}{2\pi^{3/2} } x P_1  \exp \left[- x^2\right] \, \frac{\hat{n} \hat{m}}{\hat{B} \hat{T}^2 }  \, \frac{\bar{n} \bar{m}}{\bar{R} \bar{T}} \left[ \hat{B}^{\theta} \frac{\p }{\p \theta} + \hat{B}^{\zeta} \frac{\p }{\p \zeta} \right] \hat{\Phi}_1.
\label{eq:TermNaParallelPhi1}
\end{multline}

%\noindent\textcolor{red}{
%Questions:\\
%\begin{itemize}
%	\item In the code you name a quantity ``dfMdx''. I don't see the reason for doing this since the expression doesn't contain the derivative of the Maxwellian. However, because of the $x$ it will turn out to be the same.
%	\item Looking in the code and comparing to what I get there seems to be a factor $1/2$ discrepancy. Can you see where it is? It seems to be because a factor $2 x$ pops out when taking the derivative of the Maxwellian.
%	\item In the code I can simply neglect the bar-quantities, right?
%	\item Since this is a linear term in the unknowns, I suppose it gives the same contribution to the residual matrix as to the Jacobian matrix. Is it correct understood that when I calculate the residual matrix I will substitute the term as it is, whereas when I calculate the Jacobian matrix I will have to take the derivative with respect to $\Phi_1$ (in this case when there is no $f_1$ in the term)? E.g. would a $\Phi_1^2$-term be $\Phi_1^2$ in the residual but $2 \Phi_1$ in the Jacobian?
%\end{itemize}
%}

\noindent In SFINCS the kinetic equation is made dimensionless by multiplying with
\[
\frac{\bar{v}^3 \bar{R}}{\bar{n} \bar{v}} = \frac{2 \bar{T} \bar{R}}{\bar{m} \bar{n}},
\]
which implies that the RHS of Eq.~\ref{eq:TermNaParallelPhi1} becomes
\begin{equation}
 \frac{Z \alpha}{\pi^{3/2} } x P_1  \exp \left[- x^2\right] \, \frac{\hat{n} \hat{m}}{\hat{B} \hat{T}^2 }  \,  \left[ \hat{B}^{\theta} \frac{\p }{\p \theta} + \hat{B}^{\zeta} \frac{\p }{\p \zeta} \right] \hat{\Phi}_1
\label{eq:TermNaParallelPhi1SFINCS}
\end{equation}
in the implementation.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\newpage
% \section{Temporary page}
% \subsection*{Implementation of $\displaystyle f_0 \frac{q}{T} \na \Phi_0 \cdot \bm{v}_{E1}$}
% \begin{multline}
% \left(f_0 \frac{q}{T} \na \Phi_0 \cdot \bm{v}_{E1}\right)_{\mathrm{SFINCS}} = \\ =
% \frac{Z \alpha^2 \Delta}{2 \pi^{3/2}} \frac{\hat{n} \hat{m}^{3/2} \hat{D}}{\hat{T}^{5/2} \hat{B}^2 \hat{\psi}_a} \frac{\p \hat{\Phi}_0}{\p \psi_N}
% \exp\left(-x^2\right) \exp \left(- \frac{Z \alpha \hat{\Phi}_1}{\hat{T}}\right) \left[\hat{B}_{\theta} \frac{\p}{\p \zeta} - \hat{B}_{\zeta} \frac{\p}{\p \theta}\right] \hat{\Phi}_1
% \label{eq:RHSphi1term1}
% \end{multline}

% \subsection*{Implementation of $\displaystyle f_0 \frac{q}{T} \Phi_1 \frac{\na T}{T} \cdot \bm{v}_d$}
% \begin{multline}
% \left(f_0 \frac{q}{T} \Phi_1 \frac{\na T}{T} \cdot \bm{v}_d\right)_{\mathrm{SFINCS}} = \\ =
% \frac{\alpha \Delta}{3 \pi^{3/2}} \frac{\hat{n} \hat{m}^{3/2} \hat{D}}{\hat{T}^{5/2} \hat{B}^3 \hat{\psi}_a} \hat{\Phi}_1 \frac{\p \hat{T}}{\p \psi_N}
% x^2 \left(P_2\left(\xi\right) + 2\right)
% \exp\left(-x^2\right) \exp \left(- \frac{Z \alpha \hat{\Phi}_1}{\hat{T}}\right) \left[\hat{B}_{\theta} \frac{\p \hat{B}}{\p \zeta} - \hat{B}_{\zeta} \frac{\p \hat{B}}{\p \theta}\right]
% \label{eq:RHSphi1term2}
% \end{multline}

% \subsection*{Implementation of $\displaystyle f_0 \frac{q}{T} \Phi_1 \frac{\na T}{T} \cdot \bm{v}_{E1}$}
% \begin{multline}
% \left(f_0 \frac{q}{T} \Phi_1 \frac{\na T}{T} \cdot \bm{v}_{E1}\right)_{\mathrm{SFINCS}} = \\ =
% \frac{Z \alpha^2 \Delta}{2 \pi^{3/2}} \frac{\hat{n} \hat{m}^{3/2} \hat{D}}{\hat{T}^{7/2} \hat{B}^2 \hat{\psi}_a} \frac{\p \hat{T}}{\p \psi_N} \hat{\Phi}_1
% \exp\left(-x^2\right) \exp \left(- \frac{Z \alpha \hat{\Phi}_1}{\hat{T}}\right) \left[\hat{B}_{\theta} \frac{\p}{\p \zeta} - \hat{B}_{\zeta} \frac{\p}{\p \theta}\right] \hat{\Phi}_1
% \label{eq:RHSphi1term3}
% \end{multline}
 \end{appendices}
 \newpage

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

\begin{thebibliography}{99}

\bibitem{regana} J.~M.~Garc\'{\i}a-Rega\~{n}a, R.~Kleiber, C.~D.~Beidler, Y.~Turkin, H.~Maa{\ss}berg
and P.~Helander,
\href{http://dx.doi.org/10.1088/0741-3335/55/7/074008}{\em Plasma Phys.~Control.~Fusion} {\bf 55} (2013) 074008.

\bibitem{reganaArxiv} J.~M.~Garc\'{\i}a-Rega\~{n}a, C.~D.~Beidler, Y.~Turkin, R.~Kleiber, P.~Helander, H.~Maa{\ss}berg, J. A. Alonso and J. L. Velasco,
\href{http://arxiv.org/abs/1501.03967}{\em arXiv:1501.03967} (2015).

\bibitem{landremanSFINCS} Landreman~M, Smith~H~M, Moll\'en~A and Helander~P 2014
 \href{http://dx.doi.org/10.1063/1.4870077}{\em Phys. Plasmas} {\bf 21} 042503

\bibitem{SFINCStechnicalDoc} M.~Landreman, {\em Technical Documentation for version 3 of SFINCS} (2014).

%\bibitem{simakov} A.~N.~Simakov, P.~Helander,
%  {\em Phys. Plasmas} {\bf 16}, 042503 (2009).

%\bibitem{nonAxis} P.~Helander, Theory of plasma confinement in non-axisymmetric magnetic fields (2013).

%\bibitem{MH} L.~Råde and B.~Westergren, Mathematics Handbook for Science and Engineering, $5^{\mathrm{th}}$ edition, 2004. %\vspace{-5mm}

%\bibitem{Abra} M.~Abramowitz and I.~A.~Stegun, Handbook of Mathematical Functions, $10^{\mathrm{th}}$ printing, 1972.

\end{thebibliography}

\end{document}


A common operational approach that water utilities use to address water quality concerns is flushing, which
is the purging of water from the distribution network via a fire hydrant or blow-off port.
Many utilities flush water mains following maintenance work
or in response to customer complaints. Flushing can remove the sources
of poor water quality (e.g., pipe corrosion, bio-film microorganisms), as well
as loose or suspended material that has accumulated in low-flow portions or
dead-ends of the distribution system. It is a response option that can be undertaken
relatively quickly after a contamination incident, and it can be made more efficient through
the careful selection of where to implement flushing activities. This chapter describes
the \code{flushing} subcommand in WST that assists in the identification of effective
hydrant locations to flush in order to remove contaminated water and the valves to close
in order to direct the contaminated water towards the hydrants.

A flowchart representation of the \code{flushing} subcommand is shown in Figure \ref{fig:flushing-flowchart}.
The \code{flushing} subcommand employs an iterative process that combines contaminant transport, impact assessment
and optimization. The optimization process identifies a set of flushing activities
that are simulated in the contaminant transport process and evaluated
based upon the impact assessment process. Since the \code{flushing} subcommand relies
on the \code{tevasim} and \code{sim2Impact} subcommands, their required input
is also required for the \code{flushing} subcommand. In addition, the sensor network
design used to detect the contamination incident(s) and the flushing characteristics
are required inputs. The utility network model is defined by a EPANET 2.00.12 INP file,
while the rest of the input can be specified in the \code{flushing} WST configuration file.

\begin{figure}[h]
  \centering
  \includegraphics[scale=0.75]{graphics/flushing_flowchart.pdf}
  \caption{Flushing response simulation flowchart.}
  \label{fig:flushing-flowchart}
\end{figure}

\section{Flushing Formulation}\label{flushing_formulations}
The flushing problem formulation can be summarized
as selecting a set of hydrant locations to flush and valves to close
that minimizes the average impact of all contamination incidents
given a set of potential hydrant locations to flush and valves to close.
The mathematical formulation can be written as follows:
\begin{align}
\textrm{  minimize } \qquad &\dfrac{1}{A} \sum_{a \in {A}} d_{a,\max} \label{eqn:flushing} \\
\textrm{subject to } \qquad &\sum_{h\in H}y_{h} \leq H_{\max} \label{eq:flushing_2} \\
&\sum_{v\in V}y_{v} \leq V_{\max} \label{eq:flushing_3} \\
&y_{h} \in \{0,1\} &&\forall h\in H \label{eq:flushing_4} \\
&y_{v} \in \{0,1\} &&\forall v\in V \label{eq:flushing_5}
\end{align}
where $A$ represents a set of contamination incidents,
$d_{a,\max}$ defines the maximum impact of the contamination incident $a$,
$H$ represents the set of potential hydrant locations,
$y_h$ is a binary variable which is 1 if node $h$ is selected as a flushing location,
$H_{\max}$ is the maximum number of hydrant locations,
$V$ represents the set of potential valve locations,
$y_v$ is a binary variable which is 1 if node $v$ is selected as a valving location and
$V_{\max}$ is the maximum number of valve locations. The maximum impact of a contamination
incident, $d_{a,\max}$, is the total impact across the entire network at the end of the simulation
assuming that the contaminant was not detected by a sensor, and no interventions to reduce
impacts were implemented. This value is found in the -1 entry of the impact file.

For this problem, hydrants are assumed to be located at any user-defined nodes in the network.
In addition, valves are assumed to be located on any user-defined pipes in the network.

\section{Flushing Solvers}\label{flushing_solvers}
The flushing problem is solved through an iterative optimization process which
selects different sets of hydrant and valve locations and evaluates their effectiveness
in minimizing the impact of a set of contamination incidents. Two optimization
methods, an evolutionary algorithm and a network solver, are available in WST to solve this problem.
Each solver is explained in more detail in the following subsections.

\subsection{Evolutionary Algorithm}\label{coliny_ea}
The evolutionary algorithm (EA) included with DAKOTA, Coliny EA, is used in the
optimization routine for the \code{flushing} subcommand.
Additional information on DAKOTA/Coliny solvers can be found at
\url{http://dakota.sandia.gov/docs/dakota/5.2/html-ref/index.html}
and in the DAKOTA user manual \citep{DakotaUserManual}.
The random number generator used in Coliny EA is platform dependent.
This can result in slight variations in the solution.

To design an EA, the parameter space for the optimization problem
is first encoded into a string of numbers. This encoded
representation of the problem is called a genetic string, where each
element of the genetic string represents one parameter.
When the EA is used with the \code{flushing} subcommand, the parameter space is defined by the number
of flushing and valve closure locations. Each location is assigned a sequential
integer that represents a feasible location within the EPANET network. The final EA solution
is reported based on the EPANET node/pipe IDs.

The EA has several solver options that define how the EA evolves. These options can be set in the
\code{[solver][options]} sections of the \code{flushing} WST configuration file and are specific to the Coliny EA solver.
The EA evolves an initial genetic strings of size \code{[population\_size]}
that is set based on \code{[initialization\_type]} using the following steps:
\begin{enumerate}
\item Evaluation: Evaluate the solution for each genetic string. This involves function
calls to the \code{tevasim} and \code{sim2Impact} subcommands for each string to define the impact value.
\item Breeding: Select two members of the population based on fitness. The
probability of selection is based on \code{[fitness\_type]}.
\item Crossover: Crossover two members based on \code{[crossover\_type]} and \code{[crossover\_rate]}.
\item Mutation: Mutate the two members based on \code{[mutation\_type]} and \code{[mutation\_rate]}.
\item Steps 2-4 are repeated until the entire population has been changed.
\item Replacement: After a new population is created, the old population is
replaced by the current population while keeping the highest ranked string
(elitist = 1 replacement option).
\end{enumerate}
Steps 1-6 are repeated until \code{[max\_iterations]} or \code{[max\_function\_evaluations]} criteria is met.

\subsection{Network Solver}\label{coliny_statemachine}

The network solver used in WST is a network-constrained, derivative-free local search optimization algorithm.
It is a discrete analog-to-pattern search. The allowable moves are to adjacent nodes (or pipes), rather than moves in the
continuous space. This approach provides local refinement of candidate solutions. The valid moves include
removing a node (or pipe) location and replacing it with one anywhere in the network. Two forms of the network solver can be
used: with and without initial starting points. The initial starting points are node (or pipe) locations in the network
in which the algorithm should begin its local search. If these points are not supplied to the algorithm,
then it reduces to a greedy placement algorithm. Convergence is met when no remaining moves improve the solution.

\subsection{Flushing Optimization for Large Problems}

The iterative optimization process used for flushing requires numerous
simulations of the network hydraulics and water quality. Computational run time depends on several factors, including
the size of the network model,
the number of possible contamination incidents,
the number of feasible flushing locations
and the solver options. For the network solver,the computational run time also depends on the network model
geometry surrounding the local search region. For large flushing optimization problems, several techniques can be used to
decrease the computational run time. These options include running multiple instances of the underlying
simulation in parallel, setting a stop time criteria and skeletonizing the network model.

\subsubsection{Parallelization}

The Dakota coliny\_ea and StateMachineLS solvers both include an option to set
the number of threads used to perform the simulations.
This option is specified in \code{[solver][threads]}, as shown below. It should be
set to the number of threads that are available for the simulation. The default value is 1.
If an integer greater than 1 is specified, Dakota will run that many threads.
The expected efficiency of parallelization is nearly linear with the number of
threads (up to the number of processor cores in the computer).

\begin{unknownListing}
solver:
  type: coliny_ea
  threads: 2
\end{unknownListing}

\subsubsection{Stop time criteria}

If a solution needs to be identified within a certain amount of time, a simulation stop time
criteria can be defined. This option causes the solver to terminate after a
specified time, even if the underlying algorithm has not converged to an optimal solution.
The stop time criteria is included with both the Dakota coliny\_ea and
StateMachineLS solvers, and it is specified in \code{[solver][options][misc\_options]}, as
shown below. The max\_time has to be given in seconds. As the optimization
algorithms only check the elapsed time once per major iteration, the actual
solver run time will be slightly longer than the specified maximum run time.
When the optimization process is cut off prematurely, the best solution
obtained so far is reported to the user.

\begin{unknownListing}
solver:
  type: StateMachineLS
  options:
    misc_options: "'max_time=10'"
\end{unknownListing}

\subsubsection{Skeletonization}

To reduce the size of the network model, possible contamination incidents and the number of
feasible flushing locations, the user can skeletonize the problem and evaluate
the results on the full network model. WST includes a utility script, spotSkeleton,
that can be used to skeletonize network models (See Executable Files Section ~\ref{skelExecutable}).
Network models are skeletonized based on a pipe diameter threshold. The executable, spotSkeleton,
creates a new EPANET input (inp) file and a related map file.
The map file associates the nodes in the skeletonized network model (upscaled nodes)
to the nodes in the original network model (downscaled nodes). When
working with a skeletonized network model, other aspects of the flushing problem also
need to upscaled based on the skeletonization map. These include: the injection location(s)
and strength of the contamination incident(s), the population at each node, the sensor
placement, the feasible flushing locations and the initial points for the optimization
solver. For example, if Nodes 1, 2, 3 and 4 in the original network model are
represented by Node 2 in the skeletonized network model, then a sensor placed at
Node 4 in the original network model should be placed at Node 2 in the skeletonized
network model.

After flushing optimization is run on the skeletonized network model, the
solution can then be evaluated or refined using the original network model.
To evaluate the current solution, the locations on the skeletonized network
should be listed as the only feasible flushing locations
in the original network model and the EVALUATE solver option should be used (See Example ~\ref{flushing_ex3}).
To refine the current solution, downscale the locations on the skeletonized network
and use those original network nodes as the only feasible flushing locations
in a second optimization. In this refinment, the solver type and
solver options can be different for the first and second optimization.

\section{\code{flushing} Subcommand}

The \code{flushing} subcommand is executed using the following command line:
\begin{unknownListing}
wst flushing <configfile>
\end{unknownListing}
where \code{configfile} is a WST configuration file in the YAML format.

The \code{---help} option prints information about this subcommand, such as usage,
arguments and a brief description:
\begin{unknownListing}
wst flushing --help
\end{unknownListing}

\subsection{Configuration File}

The \code{flushing} subcommand generates a template configuration file using the following command line:

\begin{unknownListing}
wst flushing --template <configfile>
\end{unknownListing}

The \code{flushing} template configuration file is shown in Figure \ref{fig:flushing_template}.
Brief descriptions of the options are included in the template after the \# sign.

\begin{figure}[p!]
  \unknownInputListing{examples/flushing_config.yml}{}{1}{50}
  \caption{The \code{flushing} configuration template file.}
  \label{fig:flushing_template}
\end{figure}

\subsection{Configuration Options}

Full descriptions of the WST configuration options used by the \code{flushing} subcommand are listed below.
\input{examples/flushing_config}

In addition to these standard WST configuration options, the solver block can define
an evaluation option. To evaluate the flushing response without solving the
optimization problem, the solver type can be set as EVALUATE. This option allows a
set of flushing locations to be evaluated against a different contamination
scenario than the one for which it was designed.

The solver block can also define specific options for the optimization solver.
The solver options should be modified according to the specific optimization problem.
If the options are not set in the solver block, then the default values for these options are used.
The two solvers available in the \code{flushing} subcommand each have their own options.
The EA solver has numerous options which can be defined. Additional information on the options available
for the EA solver can found in the DAKOTA user manual \citep{DakotaUserManual}.
An example of the EA solver options are listed below.

\begin{unknownListing}
solver:
  type: coliny_ea
  options:
    crossover_rate: 0.8
    crossover_type: uniform
    fitness_type: linear_rank
    initialization_type: unique_random
    max_function_evaluations: 30000
    max_iterations: 1000
    mutation_rate: 1
    mutation_type: offset_uniform
    population_size: 50
    seed: 11011011
\end{unknownListing}

The network solver has two options that can be set in the solver block of the configuration file.
\begin{unknownListing}
solver:
  type: StateMachineLS
  options:
    verbosity: 2
    max_fcn_evaluations: 0
\end{unknownListing}

\subsection{Subcommand Output}
The \code{flushing} subcommand creates a YAML file called <output prefix>flushing\_output.yml
that contains an optimized set of node locations (EPANET node IDs) to flush,
an optimized set of pipe locations (EPANET pipe IDs) to close,
the final impact metric, the run date and CPU time.
The log file called <output prefix>flushing\_output.log contains basic debugging information.
A visualization YAML configuration file named <output prefix>flushing\_output\_vis.yml is also created.
The \code{visualization} subcommand is automatically run using this YAML file.

\section{Flushing Response Examples}\label{flushing_example}
To demonstrate the two different solvers available in the \code{flushing} subcommand,
two examples are presented. Both examples have the same characteristics in terms
of the contamination scenario and flushing parameters. EPANET Example Network 3 (Net3.inp)
is the network used and the contamination scenario is an hour long injection at
node 101 beginning at hour 3 in the simulation. A maximum of three hydrants can be flushed
for a duration of eight hours at a rate 800 gal/min. The option to close pipes/valves was
not included in these analyses. The impact metric being minimized is population exposed (PE).
In addition, the third and forth examples are provided to demonstrate the evaluate and stop time
criteria options, respectively.

\subsection{Example 1}

The first example uses the EA solver (coliny\_ea) with the parallization option enabled
and the configuration file, flushing\_ex1.yml, is shown in Figure \ref{fig:flushing_ex1}. This example
has the \code{[solver][threads]} option set to 2 threads. Please note:
if the computer used to execute the example only has one thread, change the \code{[solver][threads]}
option to 1 instead of 2.

\begin{figure}[h]
  \unknownInputListing{../../examples/flushing_ex1.yml}{}{1}{55}
  \caption{The \code{flushing} configuration file for example 1.}
  \label{fig:flushing_ex1}
\end{figure}

The example can be executed using the following command line:

\begin{unknownListing}
wst flushing flushing_ex1.yml
\end{unknownListing}

The YAML output file, Net3flushing\_output.yml, for example 1
is shown in Figure \ref{fig:flushing_ex1_yml}. The EA selected to
flush nodes 113, 191 and 197 for a PE impact value of 5292. The CPU time
was approximately 6 minutes using 2 threads.
Since the random number generator used in the EA solver is platform dependent,
the solution can be slightly different if the example is executed on a computer with Windows.

\begin{figure}[h]
  \unknownInputListing{examples/flushing/flushing_ex1_output.yml}{}{1}{11}
  \caption{The \code{flushing} YAML output file for example 1.}
  \label{fig:flushing_ex1_yml}
\end{figure}

% \FloatBarrier
\subsection{Example 2}

The second example uses the network solver (StateMachineLS)
without initial points and the configuration file, flushing\_ex2.yml,
is shown in Figure \ref{fig:flushing_ex2}.

\begin{figure}[h]
  \unknownInputListing{../../examples/flushing_ex2.yml}{}{1}{45}
  \caption{The \code{flushing} configuration file for example 2.}
  \label{fig:flushing_ex2}
\end{figure}

The example can be executed using the following command line:

\begin{unknownListing}
wst flushing flushing_ex2.yml
\end{unknownListing}

The YAML output file, Net3flushing\_output.yml, for example 2 is shown
in Figure \ref{fig:flushing_ex2_yml}. The network solver selected to
flush nodes 101, 103 and 109 for a PE impact metric of 4919. The CPU time
was approximately 2 minutes.

\begin{figure}[h]
  \unknownInputListing{examples/flushing/flushing_ex2_output.yml}{}{1}{11}
  \caption{The \code{flushing} YAML output file for example 2.}
  \label{fig:flushing_ex2_yml}
\end{figure}

Examining the output files from the two examples shows that the optimization
solvers identified different solutions. As EAs are not guaranteed to find the
optimal solution, these results are not unexpected. In addition, the CPU times
to obtain the solutions are different. The EA solution took about 6 minutes
to obtained using 2 threads, while the network solver solution was achieved in approximately 2 minutes.

\subsection{Example 3}\label{flushing_ex3}

The third example uses the evaluate option and the configuration
file, flushing\_ex3.yml, is shown in Figure \ref{fig:flushing_ex3}.
In this example, the same contamination scenario is used but only two
(2) flushing locations are evaluated in terms of reducing the PE impact
metric. The flushing locations being evaluated are nodes 101 and 127.

\begin{figure}[h]
  \unknownInputListing{../../examples/flushing_ex3.yml}{}{1}{44}
  \caption{The \code{flushing} configuration file for example 3.}
  \label{fig:flushing_ex3}
\end{figure}

The example can be executed using the following command line:

\begin{unknownListing}
wst flushing flushing_ex3.yml
\end{unknownListing}

The YAML output file, Net3flushing\_output.yml, for example 3 is shown
in Figure \ref{fig:flushing_ex3_yml}. These two flushing locations
resulted in a PE impact metric of 10,759. Compared to the results from
example 2, the PE impact metric is much larger since only two flushing
locations are used instead of three. The evaluate option can be used to compare
the impact metrics obtained from various flushing location combinations.

\begin{figure}[h]
  \unknownInputListing{examples/flushing/flushing_ex3_output.yml}{}{1}{11}
  \caption{The \code{flushing} YAML output file for example 3.}
  \label{fig:flushing_ex3_yml}
\end{figure}

\subsection{Example 4}

The fourth example demonstrates the stop time option and uses almost the same configuration file as example 2.
The configuration file, flushing\_ex4.yml, is shown in Figure \ref{fig:flushing_ex4}, in which
the stop criteria option is enabled using the \code{[solver][options][misc\_options]} option set to "'max\_time=30'".

\begin{figure}[h]
  \unknownInputListing{../../examples/flushing_ex4.yml}{}{1}{46}
  \caption{The \code{flushing} configuration file for example 4.}
  \label{fig:flushing_ex4}
\end{figure}

The example can be executed using the following command line:

\begin{unknownListing}
wst flushing flushing_ex4.yml
\end{unknownListing}

The YAML output file, Net3flushing\_output.yml, for example 4
is shown in Figure \ref{fig:flushing_ex4_yml}. The network solver selected to
flush node 105 for a PE impact value of 9676. The CPU time was 45 seconds,
which is greater than the stop time criteria since it is only checked periodically.
The flushing solution was different than the solution obtained from example 2,
since the stop time option was not used and it executed the optimization process to completion.

\begin{figure}[h]
  \unknownInputListing{examples/flushing/flushing_ex4_output.yml}{}{1}{11}
  \caption{The \code{flushing} YAML output file for example 4.}
  \label{fig:flushing_ex4_yml}
\end{figure}


\part{Outline of the AXFI Data Model}
\vspace{.5em}
\section{Types of Image Annotations}
\p{The most fundamental kinds of image annotations
are geometric primitives such as points, lines,
and polygons.  Many other forms of annotations
are possible, however, mostly supplemental
data which is associated with these primitives
or, in some cases, with the image as a whole.
In general, \AXFI{} classifies annotations into
the following groups:

\begin{description}
\item[Geometric Primitives]  These annotations
delineate spatial/geometric regions in zero, one,
or two dimensions (or potentially higher dimensions
when working in non-\TwoD{} contexts).  At a minimum,
\AXFI{} data should support points, lines,
polygons, polylines (considered a superkind of
polygons where a polygon is a closed polyline), circles,
and ellipses.  Additionally, \AXFI{} recognizes
generic \q{closed} and \q{open} \textit{curves}, which
are nonlinear one-dimensional regions (or boundaries
of two-dimensional regions) that are neither
elliptical or circular arcs.  Depending on
context, \AXFI{} can be extended to provide
more detailed subkinds of curves generated
by different sorts of mathematical equations,
along with notations for the formulae
(e.g., b-splines) that generate a particular
curve.\footnote{In formal statements,
this and other \sAXFI{} documentation will
use the term \q{kind,} as well as \q{superkind}
and \q{subkind,} to indicate groups of values/entities
identified via a classification.  Vocabulary
based on \q{kind} is preferred to \q{type} or
\q{class} because of the distinct meanings these
latter terms have in computational contexts
which are also discussed in reference to \sAXFI{}.}
More information about encoding
ellipse data as well as other sorts of
curves is outlined below (page~\lpageref{ph:curves}).

A variation on the polygon/polygon-line alternative
are polygon-lines demarcating spatial regions
whose boundaries extend to one or more sides/corners
of the image (e.g., a \q{quadrant} is defined
via one central point with line segments
parallel to and implicitly
extended to the edges).  These poly-lines
may not explicitly represent the overall image
boundary as part of their own boundary.
Conceptually, treating the image-border itself
as a different \textit{sort} of boundary than
those explicitly notated may be more accurate
than eliding these distinctions.  This
applies also to segment boundaries.  For instance,
the sand/ocean border in a beach scene represents
a physical discontinuity between two different
material substances, and so it records an
observable detail of the depicted scene.
On the other hand, the edge of the sand-region
at the bottom of the image is not a physical
boundary, but an artifact of the camera position;
we assume the beach itself extends further than
what the camera captures.  All told, then,
in addition to polygons (or curves or segment-boundaries)
being \textit{open} or \textit{closed}, \AXFI{}
recognizes a third form of closure dubbed
\q{incomplete,} meaning that a spatial region is
geometrically closed by the edge of the image but
that this closure has no observational or semantic
significance.  \lAXFI{} allows a notation that
a spatial region is \q{closed by fiat} when the closure
results from the intrusion of the global image boundary.
A polygonal line may be closed by fiat when it does
not explicitly include lines along the global boundary,
but forms a closed polygon when such lines are
included in practice; the result is called a
\textit{fiat polygon} (similarly an annotation
can be classified as a \textit{fiat curve} or
\textit{fiat segment}).

\item[Segments and Regions]  A \textit{segment} is
considered to be, canonically, an integral
subimage with a semantically precise
separation of \q{foreground} from \q{background.}
There may be vagueness or approximation
in how the segment is precisely individuated
from its surroundings, but these ambiguities
are considered to be practical limitations
due to limited computer power, limiting pixel
resolution, and so forth.  A \textit{region}
or \textit{region of interest} is similar to a
segment, but defined more loosely; regions
can have vague descriptors, and spatially
disconnected parts of an image could be treated
as parts of one same region.  In a photograph
of a flock of birds, for example, there may be
multiple segments, each outlining one single bird.
However, the flock as a whole may be outlined
by one \textit{region}, which could (without
being deemed approximative) include some of the
background sky.  A \textit{segment} can be seen
as subkind of \textit{region} with stricter
granular and topological requirements.

A \textit{partition} of an image is a segmentation
which exhaustively classifies every point into
one or another segment.  A \textit{selective}
segmentation, unlike a complete partition, only
isolates certain segments or regions of
interests.  \lAXFI{} adopts these terms
as parameters that can characterize
segmentation processes, and by extension the
resulting segments/regions.

\item[Locations]  In \AXFI{}, \textit{locations}
are considered to be designations of areas
within an image (of varying dimensions) which
are significant by virtue of their directional,
morphological, or topological relations to
the rest of the image, rather than by virtue
of their intrinsic shape.  Conceptually,
a \textit{location} is in many cases similar
to a \textit{point}, but \AXFI{} does not require
locations to be zero-dimensional.  A location
may be designated by a small disk, or even a
region/segment.  The distinguishing feature
of locations is that their spatial shape or extent
are not semantically significant; instead,
what is important about locations is their
position in the image and how this position
relates to surrounding image content.  For
instance, a location might be the point/position
where two roads intersect, or it could
be the leftmost point on the segment-boundary of
a car's fender or a bird's wings, or the
geometric center of a car's body or a bird's torso.

\lAXFI{} distinguishes location-annotations from
secondary annotations used to identify locations
(insofar as these may be visually distinct).  For
instance, a position may be modeled as a single
point, but visually conveyed by an arrow, or by
a circle hovering above the relevant point.

\item[Focal Points]  The concept of \textit{focal
points} integrates locations and geometric primitives
for certain analytic tasks.  In general, focal points
are important for positional rather than morphological
regions, similar to locations.  However, focal points
may function more like segments or geometric objects
when used as part of an analytic objective.  For
instance, points embodying the center of a car's body
or a bird's torso could be used to count the number
of birds or cars appearing in a photograph.
In this case the concept of \q{geometric center} has
no meaningful morphological properties, so it
is analogous to a location.  On the other hand, the
center may be treated as a proxy for, or a most
significant component of, a segment or region; in this
sense the point is \textit{part of} a segment.
This mereological aspect makes focal points
act conceptually more like geometric primitives than
like locations.  In short, the classification
\textit{focal point} is available for spatial
objects which behave somewhere between locations
and regions/points, and particularly when they
are used in some proxying or indicative relation
to other regions (e.g. for counting).

\item[Secondary Images]  In some contexts, such
as segmentation, image-transforms are used to
convey image-processing operations, in contrast
to geometric-style annotations that can be
defined via vertex coordinates.  A crisp
segment can be defined via a two-toned image
with the same dimensions as the annotated
image, but with only two logical colors
(colors are called \q{logical} insofar as the
relevant detail is how the colors compare to
one another, irregardless of the optical colors
used to render them\footnote{In \sQt{}, for instance,
the \textbf{QColorConstants::Color0} and
\textbf{QColorConstants::Color1} color values
are considered to be special \q{colors}
(i.e., \textbf{QColor} instances) which define
the foreground and background of a two-toned
image; they are not formally assigned to a
visual color, like black or white.}).
A \q{fuzzy} segment can likewise be defined
via a greyscale image (anything which
is pure-background becoming either pure white,
or pure transparent, depending on context).
Secondary images can be used to denote annotations
which are too granular to be summarized by
any mathematical expression.  In these cases,
the actual annotation data should identify the
secondary image (e.g., via a file path) and
explain how it relates to the primary
(or \q{ground}) image, whereas the secondary
file itself fills in the annotation details.

Secondary images may be derived from ground
images merely to present annotations, but they
may also be intermediate analysands which are
themselves annotated.  In the latter case,
annotations on secondary images are usually
meaningful also as annotations on ground
images, so the interrelations between both
images should be notated in the annotation data.

\item[Proscriptive Annotations]  \lAXFI{}
allows for the designation of certain annotations
as \q{proscriptive} when they do not
formally delineate a geometric object, but
indirectly express such an object's shape
or how it may be derived.  A canonical
example is the use of color --- perhaps
color-enhanced secondary images --- to
designate segments or regions of interest.
For instance, one common segmentation technique
uses color simplification; smoothing out color
patches can facilitate image partitioning
by reinforcing the boundaries between different
regions.  With sufficient color manipulation,
image-segments can potentially be described
chromatically: a region may for instance
be identified as \q{the area all of whose
pixels display a red channel above} some
threshold.  \lAXFI{} data should therefore
allow such indirect designations of
segments (and spatial/geometric regions in
general) to be encoded as annotations.

The concept of proscriptive annotations is not
only chromatic --- one can imagine other scenarios
where morphological features, such as symmetries,
may be employed to similar effect.  In describing
a chess board, for instance, a set of image-regions
(each square on the board) can be derived
via translational transforms of an initial
two-segment kernel (one black square and one white).
This representation is possible because of
translational symmetries in the underlying image.
Such geometric transforms and symmetries can
sometimes be used to \q{generate} meaningful
image segments, so they should be notated
in \AXFI{} data when appropriate.

\item[Semantic Labels]  Some annotations supply data
about other annotations (what \AIM{} calls
\q{Annotation on Annotation} as opposed to
\q{Annotation on Image}).  In general, we
can supply a label, description, or semantic
classification indicating what an image segment
or region is \q{about}, i.e., what it \q{depicts}
(a bird, a flock of birds, a car, a traffic
jam, and so forth).  Such meta-annotation may be
seen as a semantic postlude to an imaging
process, but it may also be seen as providing further
detail about the process itself.  For instance,
suppose segmentation isolates a bird from the
sky: the epilogue to this operation is an ability
(for a human user or a computer algorithm) to
classify the segment as \q{bird.}  However, we
can also say that the given fact of the segment
capturing the optics of a bird (with its apparent
anatomical outline and coloration) is what
allowed the segmentation to be possible in the
first place.  Therefore, the label \q{bird}
serves both to utilize the segmentation for
further analytic/classificatory purposes and
also, potentially, to characterize the
inner workings or effectiveness of
achieving the desired processing objective.
It should be kept in mind, in short, that
label annotations are not exclusively
intended to be used for practical labeling
in the contexts of tasks such as subject-marking
images in corpora; labeling could also
be used to notate how semantic properties
of the image make segmentation (and other
processing objectives) more or less
feasible, or computationally intensive/error-prone.

The semantics of labels themselves is outside
the scope of \AXFI{}.  \lAXFI{} makes no effort
to proscibe what sorts of terms are useful
as labels (\q{bird,} \q{car,} \q{ocean,}
\q{tumor,} etc.), or whether labels are
simple strings/words or have internal structure
of their own.  \lAXFI{} does, however,
make the following minimal stipulations about
labels.  First, \AXFI{} distinguishes
\q{mass,} \q{count,} and \q{plural} label
targets --- e.g., \textit{ocean}, \textit{one bird},
\textit{two birds}.  These distinctions are
directly relevant to how segments are bounded and
counted; for instance, labeling a body of water
as \textit{a lake} (e.g. on a satellite image where
the lake's full shore is visible) versus \textit{ocean}
(continuing to the horizon) implies different
desiderata for how the labeled region spatially extends
in relation to the surrounding image.  Secondly,
with respect to semantic labels, \AXFI{} recommends
that applications and libraries enable
labels to be typed values --- instances of
application-specific data types --- as well
as simple character strings (like \q{bird.})
This is consistent with \AXFI{}'s general
approach to application integration and
type systems, to be discussed further in
Part II.

In addition to labels being second-order annotations
--- assertions attached to an image segment,
for example, or any other image feature deemed
semantically relevant in some context --- labels
may be applied to the image as a whole.  In this
context labels would be an example of
\textit{metadata} annotations (discussed next),
which apply to the image itself
rather than any proper part.

%\item[Data Transformations]

\item[Image Metadata]   This category
of annotation concerns any information
\q{about} an image which is apart from
the specific image content.  Such details could encompass
computational/encoding details such
as color depth, pixel dimensions, and image
file format; or acquisition details
such as the make and settings of the camera
whose photograph yields the current image.
In theory, any information prerequisite to
displaying an image may potentially
be relevant to how annotations are
used and interpreted.  Therefore,
\AXFI{} should support representations of
image metadata where such information is needed
to fully specify annotation data; the metadata
would then, typically, be considered an
annotation on the entire image.  It is
outside the scope of \AXFI{} to present
image-related data which is applicable
to the sharing or rendering of images but
not, in a particular context, important to
annotations themselves --- unlike \DICOM{},
for instance, which is designed as a
standard for ensuring that images are correctly
rendered and therefore includes detailed
specifications of image formats and
prerequisites, \AXFI{} introduces
image metadata only where such information
can be considered intrinsic to the
specific objectives and operations of image
annotation.

\item[Acquisition Context]  Among the class of
annotations which apply to the image as a whole,
\AXFI{} recognizes a distinct kind of annotation
covering what \AIM{} calls the \q{context,}
or the purpose and concrete goal which compels
users to initiate image-processing operations.
In general, some of this contextual data
should be preserved as a supplement to
the overall information generated by image-processing
operations.  Often image processing itself is only
one stage in a multi-faceted scientific workflow,
and contextual information which exists prior to
the image-annotation step may still be important
for subsequent steps.  For example, clinical data
which motivates a radiographic study should remain
linked to images and annotations which result from
that study; this is why \DICOMSR{} includes
clinical as well as imaging data.
%More details about \AXFI{} context descriptions are provided
%below (section ?).
\end{description}

This outline covers the different kinds
of annotation data recognized by \AXFI{}.
The following section will fill in some
missing details by addressing other
sorts of information, apart from annotations
themselves, which might be included in an
\AXFI{} data package.}


\section{Sliding Game}
Our metric for algorithmic performance involves running A* on the sliding game (see the Youtube video for a demonstration). The sliding game is a particularly convenient search problem for two reasons: the state representation is small and the state space is very large. It blows up exponentially with respect to the puzzle dimensions. This is particularly important since our goal was to measure the effectiveness of a parallel A* algorithm, and the expansive state space would decrease potential overhead.
\newline\newline
\begin{tabular}{ |p{3cm}||p{3cm}|p{3cm}|p{3cm}|  }
\hline
\multicolumn{4}{|c|}{Sliding Game Sequential Execution times} \\
\hline
Board Size& Runtime (ns)&Runtime (ms)& Runtime (s)\\
\hline
2x3 & 35880 & 0 & 0\\
3x3 & 84711 & 0 & 0\\
3x4 & 258638033 & 259 & 0\\
4x4 & 171623957677 & 171624 & 172\\
\hline
\end{tabular}
\newline
\begin{figure}[h]
    \includegraphics[scale=0.5]{figures/4x4.png}
    \caption{The puzzle grid used for the 4x4 measure}
    \label{fig:gastar_ds}
\end{figure}
\newline
The object of the game is to order the tiles in increasing numerical order. The 0 tile represents an empty tile where adjacent tiles can "slide" to. Thus, every turn can result in 4 more possible states (exponential). The graph below is a visual representation of the above runtimes in log scale.

\begin{tikzpicture}[scale=0.91]
    \begin{axis}[
        xlabel=$area$,
        ylabel=$time(ns)$,
        ymode=log
                ]
    \addplot[mark=*,blue] plot coordinates {
        (6,35880)
        (9,84711)
        (12,258638033)
        (16,171623957677)
    };
    \addlegendentry{Runtime}

    \end{axis}
    \node[above,font=\large\bfseries] at (current bounding box.north) {Sequential Execution times (log scale)};
\end{tikzpicture}

\section{Evaluating Performance}
For this problem, we evaluated our implementations by checking the wall time of the implementations. We found this to be appropriate for the serial algorithm given that we were not able to properly evaluate speedup for the GA* GPU method.

\section{Scaling the Problem Space}
Considering our sequential performance in the graph above, we see that the line is roughly linear. This supports our hypothesis that as the number of cells grow, the runtime grows roughly exponentially. In particular, we see that because most nodes on the frontier have 3 or 4 neighbors, the number of states being added as we go further from the initial state increases exponentially. Due to the nature of the problem, a small change in workload could result in dramatically larger runtime.

\section{Limitations of our Approach}
The main source of issues with our CUDA implementation came from our hash map. Our implementation of the hash map involves a table and two hash functions where the second can search for new locations in the table for a node if another element collides with it per the first hash function. Although this simplification allows us to not need sychronization in this section, it means that we need a very large hash table. If the hash table is small compared to the number of states, it is possible that an element has collisions with both the hash functions. In this case, the hash map will \textit{lose information} that could potentially be important for the final path.\newline\newline
Another limitation of our approach was the amount of global memory that we allocate in this method. We use it for the large array \verb|S| as well as the hash table. If we scale up the hash table size in order to reduce the likelihood of collisions, we will increase the global memory allocated. In the GPU, global memory is far less efficient to update than shared memory. \textbf{As a result, the global memory brought upon by the hash table would likely be our main bottleneck in the CUDA implementation.}

\section{Changing the Hardware}
As we have discovered through this project, a GPU implementation of A* is not too pragmatic. In particular, the memory constraint of GPUs especially for search problems of this magnitude is quite restrictive. In contrast, using MPI would alleviate this. \textbf{MPI is not restricted by a single device and can be used across a network of devices, thus relaxing the space constraints}. Furthermore, MPI is a more task oriented system whereas CUDA is more data oriented, which is more suitable for search problems.