% *********** Document name and reference:
% Title of document
\renewcommand{\ndoctitle}{NuPyCEE}
% Document category acronym
\renewcommand{\ndocname}{NuPyCEE}
% svn dir
\renewcommand{\svndir}{svn://forum.astro.keele.ac.uk/utils/GCE/NuPyCEE}
% Contributors to this document
\renewcommand{\ndoccontribs}{Christian Ritter, Benoit C\^ot\'e}

%\input{chap}

Document name: \ndocname \\
SVN directory: \svndir\\
Contributors: \ndoccontribs\\
Please send any feedback to critter@uvic.ca or bcote@uvic.ca. Thank you.

{  \textbf{Abstract:} %\slshape{}
%\begin{abstract}
\noindent The Nugrid-Python-Chemical-Evolution Environment, short NuPyCEE, provides
a framework to simulate the ejecta of simple stellar populations with the 1-zone code
Stellar Yields for Galactic Modeling Applications as well as galaxies
with the One-zone Model for the Evolution of Galaxies.
Various chemical evolution input parameters can be specified through a python-based interface.
Both tools provide extraction and plotting methods.
We also provide a web interface with limited capabilities which allows to download
yield tables containing the ejecta of SSPs.
To compare the results to observational data, the user can utilize the STELLAB module
which provides various spectroscopic abundance ratios of stars observed in the
Milky Way and local dwarf spheroidal galaxies.
%\end{abstract}
}

%##############################################################
%# Section: Introduction
%##############################################################

\section{Introduction}
\index{\ndocname}
Welcome to the \ndocname\ user Guide. The purpose of \ndocname\ is to
provide the user with a framework to perform chemical evolution calculations.
The focus lies on simplification and user-friendliness.
The user can choose between the \textit{Stellar Yields for Galactic Modeling Applications} (SYGMA) module
and the \textit{One-zone Model for the Evolution of Galaxies} (OMEGA) module.
SYGMA allows to follow the ejecta of simple stellar populations in a closed box while OMEGA deals with
the simulation of galaxies with inflows and outflows.
Both tools can be used in a similar manner through the ipython command line or
ipython notebooks.
%However included are low-mass, intermediate and massive star contributions, including
%SN2 and SN1a.

%This section will provide the user with a
%tutorial and walk through of the tools contained within \ndocname\ and
%how a typical user would go about using and working with this python module.
%Note also that each SYGMA version provides a python-based function documentation (Sphinx)
%in Sphinx\textunderscore DOC which can be accessed with the web brower through build/html/index.hmtl.

\subsection{Fastest possible instruction}

To download the code
you need to have git installed on your local machine.
Then download the code from github at

\url{https://github.com/NuGrid/NuPyCEE}

into your local directory via

\begin{verbatim}
git clone  https://github.com/NuGrid/NuPyCEE.git .
\end{verbatim}

Install ipython with numpy and matplotlib and
nugridpy via

\begin{verbatim}
pip install nugridpy
\end{verbatim}

Start ipython in the NuPyCEE directory with

\begin{verbatim}
ipython -pylab -p numpy
\end{verbatim}

To run a SYGMA calculation:

\begin{verbatim}
import sygma as s
s1=s.sygma()
\end{verbatim}

That's it! To plot the total  mass ejected:

\begin{verbatim}
s1.plot_totmasses(source='all')
\end{verbatim}

%More plot functions are available: s1.plot$<$tab$>$.
%Use a question mark after the plotting function
%for more infos.

To run OMEGA:

\begin{verbatim}
import omega as o
o1=o.omega()
\end{verbatim}

\begin{verbatim}
o1.plot_spectro(xaxis='[Fe/H]',yaxis='[O/Fe]')
\end{verbatim}

Now you might want to compare the prediction with
observations through the STELLAB module.

\begin{verbatim}
import stellab as st
st1=st.stellab()
st1.plot_spectro(xaxis='[Fe/H]', yaxis='[O/Fe]')
\end{verbatim}

%Check out the documentation in Section \ref{sect_omega}.

\subsection{Preparing the environment}%Tutorial and Walkthough}

To take advantage of the interactive ipython environment
SYGMA and OMEGA are both launched after starting
ipython with

\begin{verbatim}
ipython -pylab -p numpy
\end{verbatim}

where the modules numpy and matploblib have to be installed.
Also you might need to install other python modules (e.g., h5py).

A necessary dependence is NuGrid's pylib toolbox nugridpy which
contains a number of python scripts.  It can simply be installed via
pip:

\begin{verbatim}
pip install nugridpy
\end{verbatim}

%Make sure your PYTHONPATH variable is pointing to this directory.

\subsection{SYGMA}

\subsubsection{General concepts}

In order to follow the chemical enrichment via gas particles
in hydrodynamical simulations one has to describe the ejecta of material
from such star particles, essentially simple stellar populations.
With SYGMA one can follow the ejecta of such populations via
diagrams and you can extract the composition of the ejecta via tables.

\subsubsection{Getting started}

If one wants to start SYGMA from outside the SYGMA directory
one has to specify the $SYGMADIR$ variable which
points to the SYGMA dir.

Import the module:

\begin{verbatim}
import sygma as s
\end{verbatim}

Next, we create an SSP instance, initiate a class instance $s1$ of SYGMA:

\begin{verbatim}
s1=sygma.sygma(iniZ=0.0001,tend=1e10,mgal=1e9)
\end{verbatim}

A single stellar population of mass $1\times10^{9}\msun$ and metal fraction
of $0.0001$ is created and evolved in time steps of $10^{8}$ years
to the final time of 1e10 years. Other not specified and hence
default parameter include for example the choice of the initial-mass function.
%range of $1\msun$ up to $30\msun$ is used. NuGrid tables
%and SN1a yields from Thielemann86 are taken

One can check the definition of these input parameter online via
\url{http://nugrid.github.io/NuPyCEE/SPHINX/build/html/sygma.html}.

No yield tables are defined and hence the NuGrid tables as the
default choice were selected. These are the Set1 and Set1extension
yields which are
%\begin{verbatim}
%s1=sygma.sygma(alphaimf=2.35,sfr='input',iniZ=0.0001,dt=1e8,tend=1e10,mgal=1e9,
% table='yield_tables/isotope_yield_table.txt',
% sn1a_table='yield_tables/sn1a_t86.txt',
% bb_table='yield_tables/bb_walker91.txt')
%\end{verbatim}
AGB and massive star yields for five different metallicities.
In this mode the user specifies $iniZ$
which can be either $Z=2e-2, 1e-2, 6e-3, 1e-3, 1e-4$ and $0.0$.
Scaled abundances for Z=1e-t65, 1e-6 will be available soon.
Currently for $Z=0$ the PopIII stars from Heger et al. (2010) are set
as default.

\subsubsection{Providing your own yield tables}

Yield tables are available in the NuPyCEE subdirectory
yield\textunderscore tables. Add your yield tables to
this directory and SYGMA will be able read the table
if you have specified the $table$ variable. Only
for table of Z=0 the variable $pop3\textunderscore table$ is used.
Both tables need yields specified in the SYGMA (and OMEGA)
yield input format. See for the structure the default table.
It is important to provide an initial abundance
file which has to match the number of species provided in the yield tables.
Provide the file in the iniAbu directory inside the directory yield\textunderscore tables.
The input variable with which the table file can be specified is $iniabu\textunderscore table$.
For the necessary structure see again the default choice of that variable.
%Another subdirectory,
%plotting\textunderscore scripts, contains various
%plotting scripts. The latter use SYGMA's plotting functions.

\subsubsection{What do I get out?}

The output during execution shows some initial parameters,
e.g. the isotopes being part of chemical evolution,
as well as the time and metallicity evolution.
Also shown is the contribution time of stars of
certain initial mass.

%For more examples, see the SYGMA ipython notebooks available
%at \\http://208.75.74.161:8888/tree/Publicnotebooks/intro\textunderscore SYGMA.

To analyze the run afterwards we provide a variety of plotting  functions
which are described in detail at \url{http://nugrid.github.io/NuPyCEE/SPHINX/build/html/sygma.html}.
In following we give some examples. The function plot\textunderscore mass() shows the evolution
of the yield in solar masses.

\begin{verbatim}
s1.plot_mass()
\end{verbatim}

With SYGMA you can look at different contributions
for AGB stars, massive stars, and SN~Ia.

\begin{verbatim}
s1.plot_mass(source='agb')
s1.plot_mass(source='massive')
s1.plot_mass(source='sn1a')

\end{verbatim}

Note that those lines appear all in one figure.
%The solar abundance distribution is taken from GN93 (NuGrid file).

%To get an overview over the available abundance distribution
%(in mass fraction divided by solar mass fraction) of the gas
%reservoir at a certain timestep, a function
%called plot\textunderscore abu\textunderscore distr() is available.
The function $plot\textunderscore mass\textunderscore range\textunderscore contributions()$
shows the yield contribution of stars as a function of their initial mass.
It allows to identify which mass range contributes to certain elements.
%Also plotted is to each yield (grid input) corresponding mass range
%as vertical lines. In these intervals the yields are the same (for one
%simple stellar population).
To monitor the evolution of the mass of the gas reservoir ejected
masses over time, use plot\textunderscore totmasses().
The star formation rate as a function of time can be plotted with the function $plot\textunderscore sfr()$.
In the case you want to write out detailed chemical evolution tables
of isotopes, use the function $write\textunderscore evol\textunderscore table()$.
It writes out the mass of isotopes ejected by stars as a function of time
(each line represents a timestep).

\subsection{OMEGA}

\subsubsection{General concepts}
OMEGA is a classical one-zone, open-box galaxy model with
an input star formation history where stars form and inject new elements within
the same gas reservoir, using SYGMA to create a SSP at every timestep.
At any time, each existing SSP ejects material that reflects its age, mass, and initial metallicity.
OMEGA can mimic known local galaxies, such as Sculptor, Carina, and Fornax,
by using the observed star formation history and current mass, which is taken
from the literature.  It also offers the possibility to mimic the Milky Way, but we
warn the user that a one-zone model is probably too simplistic to simulate the
evolution of massive and complex galaxies, although they are useful for testing
stellar yields.

The code offers three different prescriptions for treating gas inflows and outflows
(see the OMEGA Userguide ipython notebook on WENDI, \url{http://www.nugridstars.org/projects/wendi}).
Inflows and outflows can be independently switched off to consider a semi-open box or a closed box model.
The different prescriptions can also be found in C\^ot\'e et al. (2016, \url{http://adsabs.harvard.edu/abs/2016arXiv160407824C}).

A complete description of OMEGA's input parameters and functions can
be found in the Sphinx documentation (\url{http://nugrid.github.io/NuPyCEE/SPHINX/build/html/omega.html}).
All the SSP parameters associated with SYGMA are available with OMEGA as well.

\subsubsection{Getting Started with OMEGA}

We refer to the OMEGA Userguide ipython notebook on WENDI (\url{http://www.nugridstars.org/projects/wendi})
for more information about how to use OMEGA with command lines, and how to use plotting functions
to analyze the predicted chemical evolution of the target galaxy.

\subsection{STELLAB}

STELLAB (short for Stellar Abundances) is a module that allows to plot the stellar abundances
observed in different galaxies.  So far, data are available for the Milky Way, Sculptor, Fornax, Carina,
and the LMC.  This code uses an input collection of data and plots any abundance ratio [X/Y] as
a function of another one.  It also offers the possibility to re-normalize all data to the same solar
normalization.  It is a useful and complementary tool that enables to confront numerical predictions
with observations.

We refer to the STELLAB Userguide ipython notebook on WENDI (\url{http://www.nugridstars.org/projects/wendi})
for more information on its usage, options, and collection of data.  It should be noted that observational
data have not been curated, but have rather been blindly taken from the literature.  We are currently
working on a curation process in collaboration with JINA-CEE members (\url{http://www.jinaweb.org}).

\section{Disclaimer}

\section{History}
This document history complements the svn log.

\begin{tabular*}{\textwidth}{lll}
\hline
Authors & yymmdd & Comment \\
CR & 130926 & Update of links and details \\
\hline
CR & 160513 & creation \\
\end{tabular*}

\subsection{Contact}
If any bugs do appear or if there are any questions, please email critter@uvic.ca or bcote@uvic.ca
% --------------- latex template below ---------------------------
\begin{verbatim}

\end{verbatim}

%\begin{figure}[htbp]
%   \centering
%%   \includegraphics[width=\textwidth]{layers.jpg} %
%      \caption{}   \includegraphics[width=0.48\textwidth]{FIGURES/HRD90ms.png}
%   \includegraphics[width=0.48\textwidth]{FIGURES/HRD150ms.png}
%
%   \label{fig:one}
%\end{figure}
%
%\begin{equation}
%Y\_a = Y\_k + \sum\_{i \neq k} Y\_i
%\end{equation}
%
%{
%%\color{ForestGreen}
%\sffamily
%  {\center  --------------- \hfill {\bf START: Some special text} \hfill ---------------}\\
%$Y\_c$ does not contain ZZZ but we may assign one $Y_n$ to XYZ which is the decay product of the unstable nitrogen isotope JJHJ. %
%
%{\center ---------------  \hfill {\bf END:Some special text} \hfill ---------------}\\
%}


\subsubsection{\stid{3.01} hypre}

\paragraph{Overview}
The {\sl hypre} software library \cite{hypre:homepage,hypre_design_impl_2006} provides high performance preconditioners and solvers for the solution of large sparse linear systems on massively parallel computers, with particular focus on algebraic multigrid solvers. One of {\sl hypre}’s unique features is the provision of a (semi)-structured interface, in addition to a traditional linear-algebra based interface. The semi-structured interface is appropriate for applications whose grids are mostly structured, but with some unstructured features. Examples include block-structured grids, composite grids in structured adaptive mesh refinement (AMR) applications, and overset grids. These interfaces give application users a more natural means for describing their linear systems, and provide access to methods such as structured multigrid solvers, which can take advantage of the additional information beyond just the matrix. Since current architecture trends are favoring regular compute patterns to achieve high performance, the ability to express structure has become much more important. The {\sl hypre} library provides both unstructured and structured multigrid solvers, which have shown excellent scalability on a variety of high performance computers, e.g Blue Gene systems (unstructured solver BoomerAMG has scaled up to 1.25 million MPI cores with a total of 4.5 million hardware threads). It is used by many ECP application teams, including ExaAM, Subsurface, ExaWind, CEED, and more. It requires a C compiler and an MPI implementation, but it also runs in an OpenMP environment. It has some GPU capabilities.

\paragraph{Key  Challenges}

While {\sl hypre}'s solvers contain much parallelism, their main focus is the solution of sparse linear systems, leading to  very large demands on memory bandwidth. In addition, the use of multiple levels, while greatly aiding convergence of the solvers, leads to decreasing systems sizes, number of operations and parallel efficiencies on coarser levels. Particularly the unstructured algebraic multigrid solver BoomerAMG\cite{HeYa2002}, which is {\sl hypre}'s most often used preconditioner, suffers from increasing communication complexities on coarser levels. Coarse grid operators are generated by multiplying three matrices leading to increasing numbers of nonzeroes per row in the resulting matrices and with it increasing numbers of neighbor processes. While BoomerAMG's solve phase mainly consists of matrix vector products and smoothing operations, which are fairly straight forward to parallelize, even on a GPU, its setup phase is highly complex, including many branches, a lot of integer operations as well as some sequential passages. Current  interpolation strategies that lead to best convergence and performance on distributed memory machines are not suitable for implementation on GPUs or similar architectures requiring extreme parallelism. Since {\sl hypre} is a mature product with many solvers and interdependent features, any significant changes that affect the whole library, are tedious and require much testing to ensure that the library stays backward compatible and no features are broken.

\paragraph{Solution Strategy}

Since computer architectures continue to change rapidly, it was important to come up with strategies that will facilitate future porting of the software. Therefore we developed and implemented a new memory model that addresses the use of different memory locations.
Since the upcoming computer architectures are heterogeneous with accelerators, we focus on enabling {\sl hypre} for GPUs. We have looked into various options, such as the use of CUDA, OpenMP 4.5, as well as RAJA and Kokkos. We limited the latter two options to the structured interface and solvers which are more natural candidates for such an approach due to their use of macros, called BoxLoops, for loops. We will also investigate the use of HIP and SYCL for AMD and Intel accelerators that will be available on future exascale computers.

\paragraph{Recent Progress}

Previously, we enabled the structured solvers, SMG and PFMG\cite{AsFa1996}, both setup and solve phase, to completely run on GPUs, using both CUDA or OpenMP4.5, and to not require unified memory. In addition, options to use RAJA and Kokkos are available.
Porting the unstructured solver, BoomerAMG turned out to be far more complex. We first ported the solve phase to GPUs for select smoothers, mainly Jacobi smoothers, requiring unified memory. During the last year, we focused on enabling selected components of the setup phase to run on GPUs, specifically PMIS coarsening, direct interpolation, and the generation of the coarse grid operator, which consists of the multiplication of three sparse matrices. Figure \ref{fig:rap} shows runtime comparisons of different implementations of the coarse grid operator generation on one V-100 GPU or one Power 9, which demonstrate that the hypre GPU implementation outperforms state-of-the-art implementations such as CUSP and cuSPARSE. It is now possible to perform a complete linear system solve with BoomerAMG on GPUs using specific settings.

\begin{figure}
\centering
	\includegraphics[width=5in]{projects/2.3.3-MathLibs/2.3.3.12-SUNDIALS-hypre/hypre-rap-1gpu.png}
	\caption{\label{fig:rap} Runtimes to generate a coarse grid operator for a 7pt 3d Laplace problem matrix on 1 V-100 GPU or Power 9 CPU with up to 20 OMP threads for various implementations}
\end{figure}

We also implemented a new integer datatype called HYPRE$\_$BigInt to avoid the requirement that all integers need to be converted to 64 bit integers when solving linear systems greater than 2 billions using the unstructured solvers. The new datatype allows to only convert variables that need to be 64 bit integers and improves memory usage and performance, as illustrated in Figure \ref{fig:mixed-int}.

\begin{figure}
\centering
	\includegraphics[width=3in]{projects/2.3.3-MathLibs/2.3.3.12-SUNDIALS-hypre/hypre-mixed-int.png}
	\caption{\label{fig:mixed-int} Weak scaling study on LLNL Linux cluster Quartz: Total runtimes in seconds for AMG-PCG using 1M points/core for 2 different 3D diffusion problems.The new mixed-int capability performs about 20-25 percent better than the 64 bit integer version while using less memory and is capable to solve larger problems than the 32 bit integer version.}
\end{figure}

\paragraph{Next Steps}

We will pursue the following tasks:

\begin{itemize}
\item We will continue to add new GPU capabilities to {\sl hypre}. This includes converting various components that are currently running only on the CPU to be usable on the GPU using CUDA or OpenMP 4.5. We will particularly focus on additional setup components, such as interpolation operators, to achieve better convergence.
\item We also plan on improving the efficiency of interfacing applications with {\sl hypre}'s solvers.
\end{itemize}
In addition, we will work with ECP application teams who are using {\sl hypre}, such as ExaWind, or would like to use it, to achieve best performance by tuning the solvers for them and potentially implementing suitable algorithmic changes.


\section{Experiments and Results}

We conducted a variety of experiments to audit our previously
described approach. As a running example we used a DNN which we
trained on images from a generated dataset we dubbed \emph{Picasso
  Dataset}. The foundation are images of human faces we took from the
FASSEG dataset~\cite{khan2015multi,khan2017head}.
The Picasso Dataset contains collage images of faces with the facial
features (eyes, mouth, nose) either in the correct constellation
(positive class) or in a mixed-up constellation (negative class). See
Fig.~\ref{fig:picasso} for examples.
No distinction is made between originally left and right eyes.

\begin{figure}
  \begin{center}
    \includegraphics[width=.15\textwidth]{pic_00001_pos.png}\quad
    \includegraphics[width=.15\textwidth]{pic_00009_pos.png}\qquad\qquad
    \includegraphics[width=.15\textwidth]{pic_00000_neg.png}\quad
    \includegraphics[width=.15\textwidth]{pic_00001_neg.png}
  \end{center}
  \caption{Examples from the Picasso Dataset
    (\textit{left:} positive class, \textit{right:} negative).}
  \label{fig:picasso}
\end{figure}

In order to not establish a divergence in the image space of the two
classes, the positive and negative classes contain facial features
that were cut out of a set of images from the original FASSEG
dataset. As a canvas to include the features, we took a set of
original faces and got rid of the facial features by giving the
complete facial area a similar skin-like texture. Then we included the
cut out facial features onto the original positions of the original
features in the faces.

The face images in Fig.~\ref{fig:picasso} show that
the resulting dataset is rather constructed. This however will suffice for
a proof of concept to show that our approach in fact exploits object parts
and their relations. In the future we plan on moving towards more natural
datasets.

\subsection{Analyzed DNNs}
We evaluated our method on three different architectures from the pytorch
model-zoo\footnote{\url{https://pytorch.org/docs/stable/torchvision/models.html}}:
AlexNet~\cite{krizhevsky_one_2014},
VGG16~\cite{simonyan_very_2015}, and
ResNeXt-50~\cite{xie_aggregated_2017}.
The convolutional parts of the networks were initialized with weights
pre-trained on the ImageNet dataset.
For fine-tuning the DNNs for the Picasso Dataset task,
%
the output dimension was reduced to one and the in- and output
dimension of the second to last hidden dense layer was reduced to 512
for AlexNet and VGG16.
Then the dense layers and the last two convolutional layers
(AlexNet, VGG16) respectively bottleneck blocks (ResNeXt) were fine-tuned.
%
The fine-tuning was conducted in one epoch on a training set of 18,002
generated, $224\times224$-sized picasso samples with equal
distribution of positive and negative class.
All models achieved accuracy greater than 99\%
on a test set of 999 positive and 999 negative samples.

% The fine-tuning failed for VGG16 when initialized with weights from
% the VGG face dataset, which we explain with the sub-optimal alignment
% of the objectives between VGG face and the Picasso Dataset.

\subsection{Training the Concept Models}
%%% Concept Data
In our example we determined the best ensembled detection concept vectors for
the concepts \textsc{eyes}, \textsc{mouth} and \textsc{nose} amongst the
considered layers.
%
%%% Analyzed Model Layers
We excluded layers with low receptive field, as they are assumed to
hold only very local features
(for the layers used see Fig.~\ref{fig:layerwiseresults}).
Convolutional output was only considered after the activation.
% ResNeXt: starting at bottleneck modules 4/16,
% VGG16: starting at conv layer 5/13,
% AlexNet: starting at conv layer 2/5
%
\begin{figure}%
  \centering%
  \hspace*{-0.08\textwidth}\includegraphics[width=1.16\textwidth]{layerwise_results_concept_embedding}
  \caption{The layer-wise mean set IoU results of the concept analysis runs.}
  \label{fig:layerwiseresults}
\end{figure}
%
For each concept, 452 training/validation, and 48 test picasso samples
with segmentation masks were used.
% The concept window size determining the kernel size of the concept
% model convolution was chosen as the mean boxed size of the concept.
% The latter was chosen as
% $0.15\times0.05$ for the nose,
% $0.08\times0.2$ for the mouth, and
% $0.08\times0.16$ for an eye.
The training objective was: Predict at each activation map pixel
whether the kernel window centered there lies \enquote{over}
an instance of the concept. Over meant that the fuzzy intersection of
the concept segmentation and the kernel window area exceeds a threshold
(\emph{intersection encoding}).
This fuzzy definition of a box center
% introduces some noise to the ground truth, but
tackles the problem of sub-optimal intersections in later layers
due to low resolution.
% At a threshold greater or equal 0.5 masks are smoothed and sharpened.
Too high values may lead to elimination of an instance,
% Intersection over union (IoU) encoding is especially vulnerable to this for
% small concepts, wherefore we preferred intersection encoding.
and thresholds were chosen to avoid such issues with
values 0.5/0.8/0.7 for nose/mouth/eye.
We implemented the encoding via a convolution.
As evaluation metric we use set IoU (sIoU) between the detection
masks and the intersection encoded masks as in Net2Vec.
%
%%% Optimization Method
On each dataset and each layer, 15 concept models were trained in
three 5-fold-cross-validation runs with the following settings:
Adam optimization with mean best learning rate of 0.001,
a weighting of 5:1 of Dice to bBCE loss,
batch size of 8, and
two epochs (all layers showed quick convergence).
% \begin{align*}
    %     \text{Loss}(M_\text{pred}, M)
    %     &= \lambda_\text{Dice} \text{Dice}(M_\text{pred}, M) +
            %             \lambda_\text{bBCE} \text{bBCE}(M_\text{pred}, M) \\
    %     \text{Dice}(M_\text{pred}, M)
    %           &= \frac{2\cdot MM_\text{pred}}
                  %                   {2\cdot MM_\text{pred} + (1-M)M_\text{pred} + M(1-M_\text{pred})} \\
    %     \text{bBCE}(M_\text{pred}, M)
    %           &= b M \log(M_\text{pred}) + (1-b) (1-M) \log(1-M_\text{pred})
                  %   \end{align*}
                  %                   for a ground truth intersection encoded mask $M$,
                  %                   a predicted mask $M_\text{pred}$,
                  %                   $b=0.99$ the mean proportion of background pixels in a concept mask
                  %                   (chosen for nose 0.999, else 0.995),
                  %                   and $\lambda_\text{Dice}=0.5$ and $\lambda_{bBCE}=0.1$.
                  %                   We recorded slightly worse results for higher weighting of the binary
                  %                   cross-entropy part or balancing of the Dice loss towards less false
                  %                   positives or less false negatives as described in
                  %                   \cite{salehi_tversky_2017}.
                  %

\paragraph{Results}
%%% ensemble performance pretty well coincides with mean performance, sometimes slightly better (possibly due to implicit confidence calibration)
Our normalized ensembling approach proved valuable as it yielded
mean or slightly better performance compared to the single runs.
For the considered models, meaningful embeddings of all concepts could
be found (see Tab.~\ref{tab:bestembeddings}): The layers all reached
sIoU values greater than 0.22
%%% influence of resolution
despite of the still seemingly high influence of sub-optimal
resolutions of the activation maps.
Fig.~\ref{fig:conceptsamples} shows some exemplary outputs.
%%% embeddings in early layers
The concepts were best embedded in earlier layers,
%%% embeddings in different layers
while different concepts did not necessarily share the same layer.
\begin{table}
  \centering
  \caption{Results for ensemble embeddings with
    set IoU (sIoU), mean cosine distance to the runs (Cos.d.),
    and index of conv layer or block (L) (cf. Fig.~\ref{fig:layerwiseresults}).
    \label{tab:bestembeddings}}%
  \footnotesize%
  \newcommand*{\normentry}[1]{\multicolumn{1}{c}{#1}}%
  \newcommand{\model}[1]{\multirow{4}{*}{
      \begin{tabular}{@{}c@{}}
        \rotatebox[origin=c]{90}{\strut#1}
      \end{tabular}}}%
  \newenvironment{statstable}[1]{%
    \begin{tabular}{@{}l >{\scshape}l c@{~~} S[table-auto-round] S[table-auto-round]@{}}%
      \toprule%
      \model{#1}
      &
      & \normentry{L~~}
      & \normentry{sIoU}
      & \normentry{Cos.d.}\\%
      \cmidrule[\heavyrulewidth]{2-5}
    }{\bottomrule\end{tabular}}%
  \mbox{%
    \begin{statstable}{AlexNet}
      & nose  & 2 & 0.227925 & 0.04030534426371257 \\ % 0.290909
      & mouth & 2 & 0.239023 & 0.04018515348434448 \\ % 0.290484
      & eyes  & 2 & 0.271918 & 0.0581478198369344  \\ % 0.347822
    \end{statstable}\hspace*{1em}%
    \begin{statstable}{VGG16}
      & nose  & 7 & 0.332171 & 0.10435034632682805 \\ % 0.468819
      & mouth & 6 & 0.295552 & 0.15369088053703306 \\ % 0.561507
      & eyes  & 6 & 0.349707 & 0.1969874024391174  \\ % 0.628199
    \end{statstable}\hspace*{1em}%
    \begin{statstable}{ResNeXt}
      & nose  & 6 & 0.263708 & 0.017367599999999928 \\ % 0.192076
      & mouth & 5 & 0.236788 & 0.020498533333333402 \\ % 0.208507
      & eyes  & 7 & 0.302339 & 0.019860466666666854 \\ % 0.205269
    \end{statstable}%
  }
\end{table}
\begin{figure}%
  \centering%
  \includegraphics[width=0.6\textwidth]{vis_concept_predictions_vgg16}\\
  \includegraphics[width=0.6\textwidth]{vis_concept_predictions_alexnet}%
  \caption{
    Ensemble embedding outputs of
    \textsc{nose} (green), \textsc{mouth} (blue), \textsc{eyes} (red).}
  \label{fig:conceptsamples}
\end{figure}

\subsection{Example Selection for ILP Training}
The goal of the ILP model is to approximate the behavior of the main
DNN, \idest its decision boundary.
For this, few but meaningful training samples and their DNN output
are needed: class-prototypes as well as ones that tightly frame the
DNN decision boundary.
From the 1,998 samples in the picasso test set, in total 100 samples
were chosen from the DNN test set to train the ILP model.
The DNN confidence score here was used to estimate
the proximity of a data point to the decision boundary.
For each class, we selected the 50 samples predicted to be in this
class and with confidence closest to the class boundary of 0.5.
In our setup this provided a wide range of confidence values
(including 0 and 1).

\subsection{Finding the Symbolic Explanation}
In order to find the background knowledge needed for Aleph to generate
the explanation, we need to extract the information about the facial
features and their constellations from the masks of the samples drawn in the
previous step. Abiding the procedure described in
Sec.~\ref{sec:bkextraction}, we first find contiguous clusters in the
mask layers to then infer the positional information for them. This is
straight-forward for the nose and the mouth but imposes a problem for
the eyes, since we do not want to have a single position proposal for
them in the eye that produces the biggest cluster in the mask
layer. Thus, we allow for the top two biggest clusters to infer a
position. Although we give them unique constants in the BK, we both
give them the type \ilprule{eye} $\in C$.

The next step consists of the extraction of the spatial features
between the found parts. Since the relation pair
\ilprule{left\_of}\,/ \ilprule{right\_of} as well as
\ilprule{top\_of}\,/ \ilprule{bottom\_of} can be seen as the inverses of
the respective other relation, we omit the relations
\ilprule{right\_of} and \ilprule{bottom\_of} in the BK. This is
possible, because the \emph{Closed World Assumption} holds (Everything
that is not stated explicitly is false).

Once the BK is found for all examples, we can let Aleph induce a
theory of logic rules. Consider the induced theory for the trained
VGG16 network:
\ilprule{
  \begin{align*}
    \text{face(F) :- } &\text{contains(F, A), isa(A, nose), contains(F, B), isa(B, mouth),}\\
                       &\text{top\_of(A, B), contains(F, C), top\_of(C, A).}
  \end{align*}
}
The rule explicitly names the required facial concepts \ilprule{nose}
and \ilprule{mouth} and the fact that the nose has to be above the
mouth in order for an image to be a face. Further there is another
unnamed component \ilprule{C} required which has to be placed above
the nose. By construction this has to be one of the eyes. The rule
makes sense intuitively as it describes a subset of correct
constellations of the features of a human face.

To further test the fidelity of the generated explanations to the
original black-box network, we calculated several performance metrics
for a test set of 1998 test images (999 positive and 999 negative
examples). We handled the learned explanation rules as binary
classification model for the test images in BK representation. If an
image representation is covered by the explanation rules, it is
predicted to be positive, otherwise negative. We now can handle the
binary output of the black-box model as ground truth to our
explanation predictions. The performance metrics together with the
induced explanation rules for several DNN architectures are listed in
Tab.~\ref{tab:ilp_results}. It can be seen that the explanations stay
true to the original black-box model.

\begin{table}[t]
  \newcommand*{\rulepart}[1]{\ilprule{\scriptsize #1}}
  \caption{Learned rules for different architectures and their
    fidelity scores (accuracy and F1 score wrt.\ to the original model
    predictions).
    Learned rules are of common form
    \rulepart{face(F) :- contains(F, A), isa(A, nose), contains(F, B), isa(B, mouth), distinctPart}
  }
  \label{tab:ilp_results}
  \begin{tabular*}{\textwidth}{lcc@{\extracolsep{\fill}}l}
    \toprule
    \textbf{Arch.}   & \textbf{Accuracy} & \textbf{F1} & \textbf{Distinct rule part}\\
    \midrule[\heavyrulewidth]
    VGG16   & 99.60\%  & 99.60\%  & \rulepart{top\_of(A, B), contains(F, C), top\_of(C, A)} \\
    AlexNet & 99.05\%  & 99.04\%  & \rulepart{contains(F, C), left\_of(C, A), top\_of(C, B), top\_of(C, A)} \\
    ResNext & 99.75\%  & 99.75\%  & \rulepart{top\_of(A, B), contains(F, C), top\_of(C, A)}\\
    \bottomrule
  \end{tabular*}
\end{table}

% When it comes to explaining the network behavior it is
% particularly important to look at edge cases. This can be cases
% where the network is not sure about a prediction or is even
% wrong. We expect an explanation to accurately resemble the
% decisions of the original network. We therefore investigated if
% the false positives in the test set are correctly labeled as
% positives and the false negatives are correctly labeled as
% negatives by the explanation rules. This was in fact the case all
% occurring

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


\chapter{Height Field Files}

This appendix describes the format of the files that store data
for the height field primitive.
The format is an historical relic; a better format is needed.

Height field data is stored in binary form.
The first record in the file is a
32-bit integer giving the square root of number of data
points in the file.
We'll call this number
the size of the height field.

The size is
followed by altitude ($z$) values stored as 32-bit
floating point values.  The 0th value in the file specifies the $z$
coordinate
of the lower-left corner of the height field (0, 0).
The next
specifies the Z coordinate for $(1/(size-1), 0)$.  The last specifies the
coordinate for $(1., 1.)$.  In other words, the $i^{th}$ value
in the heightfield file specifies the $z$ coordinate for the point
whose $x$ coordinate is
$(i \% size) / (size -1)$, and whose
$y$ coordinate is $(i / size) / (size -1)$.
Non-square height fields may be rendered by specifying altitude values
less than or equal to the magic value
$-1000$.  Triangles that have any vertex less than
or equal in altitude to this value are not rendered.

While this file format is compact, it sacrifices portability for
ease of use.  While creating and handling height field files is
simple, transporting a height field from one machine to another
is problematical due to the fact that differences in byte order
and floating-point format between machines is not taken into
account.

These problems could be circumvented by writing the height field file
in a fixed-point format, taking care to write the bytes that
encode a given value in a consistent way from machine to machine.
An even better idea would be to write a set of tools for
manipulating arbitrary 2D arrays of floating-point values in a compact,
portable way, allowing for comments and the like in the file\ldots


% !TEX root = thesis.tex

\chapter{Implementing higher-dimensional representations and operations}
\label{ch:implementation}

The higher-dimensional representations described in \refpa{pa:representation} and the operations described in \refpa{pa:operations} can be difficult to implement, especially when we expect these implementations to be fast, robust, generic, compact and dimension-independent.
This is true even when the basic ideas and algorithms are provided, as has been done in this thesis.

For the sake of full reproducibility, this chapter shows some of the key implementation details that are used to efficiently implement the representations and operations described in this thesis.
\refse{se:libraries} lists the main libraries that were used and how they were used.
\refse{se:computerarithmetic} explains the main techniques that are used to perform arithmetic and geometric operations robustly.
Finally, \refse{se:traits} describes the traits programming technique and its use in CGAL and this thesis to produce dimension-independent efficient implementations.

\section{Main libraries used within this thesis}
\label{se:libraries}

\begin{description}

\item[CGAL\footnotemark]
\footnotetext{\url{http://www.cgal.org}}
(the Computational Geometry Algorithms Library) contains a wide variety of 2D/3D/$n$D data structures and computational geometry algorithms.
Some of its basic packages are directly used within this thesis to store and manipulate numbers and basic shapes, namely: Algebraic Foundations, Number Types, 2D and 3D Linear Geometry Kernel, and $d$D Geometry Kernel.
Most significantly, the packages Combinatorial Maps and Linear Cell Complex are used in most of the implementations described in the previous chapters.
Finally, other packages are used as temporary data structures and to process and clean input data: 3D Polyhedral Surface, Halfedge Data Structures, 3D Boolean Operations on Nef Polyhedra, 2D Triangulation, and Principal Component Analysis.
A few other packages are used as dependencies of the aforementioned packages.

\item[GDAL\footnotemark]
\footnotetext{\url{http://www.gdal.org}}
(the Geospatial Data Abstraction Library) reads and writes commonly used GIS file formats.
Within this thesis, its OGR vector module is mainly used to read and write polygons described as well-known text \citep{SimpleFeatures1}, or in Esri Shapefile \citep{Shapefile} and FileGDB files.

\item[IfcOpenShell\footnotemark]
\footnotetext{\url{http://www.ifcopenshell.org}}
is a library that is able to read and write IFC files \citep{ISO16739:2013}.
It internally uses the Open CASCADE geometry types, including to convert implicit geometries (\eg\ those built using constructive-solid geometry or sweeps as in \reffig{fig:ifc}) into explicit ones that can be stored using boundary representation, or to create meshes of a given degree of accuracy from curved surfaces.

\item[Open CASCADE\footnotemark]
\footnotetext{\url{http://www.opencascade.org}}
is a library that is able to manipulate geometric representations in CAD applications.
In theory, it supports complex geometric operations between implicit geometries, including Boolean set operations with 3D point sets.
However, in practice it performs poorly with GIS data, often failing due to numerical errors or imperfect data.

\end{description}

\section{Geometric operations using computer arithmetic}
\label{se:computerarithmetic}

Theoretical descriptions of geometric objects and geometric algorithms generally start from the notions of the Euclidean space $\mathbb{R}^n$, in which the coordinates of a point can be described precisely using real numbers ($\mathbb{R}$).
However, as real numbers cannot be represented on (digital) computers, implementations usually opt for a combination of \emph{integer numbers} to represent whole numbers of known precision that are known to fall within a given interval and \emph{floating-point numbers} in all other cases.
While integers can be precisely expressed as a sequence of binary digits of a given length, floating-point numbers often cannot.
The latter are therefore usually\footnote{This is only the most common representation among those provided by the much broader IEEE 754 standard \citep{IEEE754-2008}, which provides for decimal numbers as well as special values for $\pm \infty$ and NaN (not a number), among other features.} expressed using binary numbers with a predefined number of bits.
% as:

% \begin{equation*}
% {(-1)}^\mathrm{sign} \times 2^\mathrm{exponent} \times \mathrm{significand}
% \end{equation*}

% where the exponent is a positive integer and the significand is expressed as a normalised number.
% As a normalised binary number always begins with \texttt{1.}, the first binary digit is known and therefore not stored.
% The \emph{fraction} of the number (\ie\ the digits following the \texttt{1.}) is stored instead.
% Single precision (or 32-bit) floating-point numbers use 1 bit for the sign, 8 bits for the exponent and 23 bits for the significand.
% Double precision (or 64-bit) floating-point numbers use 1 bit for the sign, 11 bits for the exponent and 52 bits for the significand.

Floating-point numbers can represent a wide range of values and work well in many instances.
However, arithmetic performed using floating-point numbers needs special care, as it often leads to a loss of precision \citep{Goldberg91}.
While this is a problem for all kinds of algorithms \citep{Hoffmann88}, geometric operations are particularly vulnerable as they often rely on getting a correct result for a large number of predicates, which can fail when dealing with edge cases \citep{Kettner08}, such as almost collinear or coplanar points.

Many alternatives have been developed to deal with various limitations of integer and floating-point numbers.
Among these, the ones described below are those that have been used for the implementations related to this thesis.
\emph{Multiple precision arithmetic} is a generic solution that can achieve an arbitrary level of precision by using numbers with a user-definable number of digits.
It is widely implemented in libraries such as GMP\footnote{\url{https://gmplib.org/}} and MPFR\footnote{\url{http://www.mpfr.org}}.

Simple arithmetic operations can be computed precisely by using \emph{rational arithmetic}, where a number is stored as a ratio of two other numbers, most commonly integers.
In a geometric context, this type of representation is often used in the form of homogeneous coordinates, where a single number is used as a common denominator for all of the coordinates.
This common denominator can be used to represent special values, such as a point at infinity by setting it to zero.

In \emph{interval arithmetic} numbers are substituted with intervals.
When these are used to represent the error bounds of an operation\footnote{combined with correct rounding in the case of floating-point numbers}, it is possible to compute arithmetic operations with provably correct results \citep[Ch.~2]{Ratschek88}, such as those provided by the MPFI library\footnote{\url{https://perso.ens-lyon.fr/nathalie.revol/software.html}}.
Unfortunately, while this setup using multiple precision interval arithmetic can be applied to most problems with relative ease, it is also very slow.
For instance, \citet{Held11} reports a factor of 70 for the computation of Voronoi diagrams.

It is possible to go around this problem by fine-tuning a multiple-precision approach to a specific problem.
Notably, this is done with very good results for a few geometric predicates by \citet{Shewchuk97}, and the simulation of simplicity paradigm advocated by \citet{Edelsbrunner90}.
A more generic and easier to implement solution is provided by the lazy evaluation scheme used in CGAL \citep{Pion11}, which is based on interval arithmetic and is the one used in this thesis.
% , which is used in the implementations mentioned in this thesis.
In it, the computationally expensive multiple precision operations are only computed when floating-point precision is not sufficient.
As these cases are important to get correct results, but also relatively rare, it significantly improves the performance of most operations while maintaining their correctness.

\section{Efficient and flexible dimension-independent programming}
\label{se:traits}

Previously, \refse{ss:dimensions} discussed how higher-dimensional representations have large sizes and methods using them have high computational complexities, which often increase exponentially on the dimension.
However, there are also practical obstacles that make it difficult to implement dimension-independent structures and methods efficiently, especially when these have to be used in a generic setting such as in GIS, where varied objects of different dimensions need to be dynamically created and modified, as well as appended with possibly multiple attributes of various types.

One of these obstacles is the need to allocate and use structures that are dimension- and data-independent, and therefore flexible enough to cover all the aforementioned use cases, but at the same time remain compact and allow their contents to be accessed efficiently.
These structures can range from simple ones that can be handled by standard data types and containers, to more complex ones that need to be dynamically defined.
For instance, some simple types are directly dependent on the dimension, such as $n$-tuples storing the coordinates of a point in $\mathbb{R}^n$, and can thus be stored as arrays or vectors.

At the opposite end, consider the sets of extrusion intervals that were associated to each cell in \refch{ch:extrusion}, where an unknown number of cells need to be each associated with an unknown number of intervals.
As the number of intervals per cell is not known, it is not possible to store the intervals in a fixed-length structure that is integrated into the embedding structure of each cell.
Also, while it is possible to directly link a cell to its set of intervals from its embedding structure, these intervals are only temporarily needed, so allocating space for the intervals directly in the embedding structure is wasteful at all other times and thus difficult to justify.
The end result was that the intervals per cell were kept in an external structure, where a \texttt{map} linked a cell embedding to a \texttt{set} of intervals.
As \reftab{tab:complexitystd} shows, this means that accessing a given interval of a given cell---an operation that is performed a very large number of times---, takes logarithmic rather than constant time, significantly slowing the extrusion algorithm in practice.
\marginpar{
\captionsetup{type=table}
\centering
\caption[Computational complexity of accessing an element in C++ containers]{The typical computational complexity of accessing a given element in common C++ containers \citep{ISO14882:2015}}
\label{tab:complexitystd}
\small
\begin{tabular}{cc}
\toprule
structure & complexity \\
\midrule
hard-coded & $O(1)$ \\
array/vector & $O(1)$ \\
map/set & $O(\log n)$ \\
list & $O(n)$ \\
\bottomrule
\end{tabular}
}

A possible solution to the aforementioned problems is based on \emph{template meta-programming}.
Template meta-programming is a technique that uses templates to generate certain data structures or perform certain computations during the compilation of a program rather than during its execution.
Templates are normally used as a way to support generic programming, enabling the creation of functions that can deal with different data types indistinctly.
A template might thus be instantiated with the dimension of an object or a particular attribute type, thus generating a data structure of the appropriate size and disposition whose members can be accessed in constant time.
\reffig{fig:template-conversion} shows a slightly more complex example, where a template can be used to convert a string into any number type, which is used in this thesis to parse numbers from various types of files (\eg\ coordinates and identifiers).
\begin{figure}[tb]
\centering
\small
\lstinputlisting[language=C++]{figs/templateconversion.txt}
\caption[Using C++ templates to convert a \texttt{string} into any number type]{Using C++ templates to convert a \texttt{string} containing a number into any number type $T$, including scientific notation. Adapted from \url{http://www.cplusplus.com/forum/articles/9645/}.}
\label{fig:template-conversion}
\end{figure}

However, apart from their use in generic programming, templates can also be used to create complex dimension-dependent structures, such as through the use of the traits programming technique \citep{Myers95} used in CGAL, which exploits C++'s \texttt{typedef} declarations to create custom dependent types.\@
As an example, \reffig{fig:extrudedlcc} shows how the implementation of the extrusion algorithm defines a combinatorial map that is one dimension higher than the input, which is created during compilation.
\begin{figure*}[tb]
\centering
\small
\lstinputlisting[language=C++,numbers=left]{figs/extrudedlcc.txt}
\caption[Creating a dependent type using C++ templates]{Using C++ templates it is possible to create dependent types such as the \texttt{Higher\_dimensional\_cell\_complex} defined in line 5 and used in line 15.}
\label{fig:extrudedlcc}
\end{figure*}

This type of mechanism can be used to a much higher degree by defining \emph{recursive templates}, which are used extensively in the CGAL Combinatorial Maps package.
As an example, \reffig{fig:dimensionindependent} shows how this was applied in order to store the extrusion ranges maps for each dimension separately, which is necessary because the embedding structures of each cell are different depending on the dimension.
\begin{figure*}[tb]
\centering
\small
\lstinputlisting[language=C++,numbers=left]{figs/dimensionindependent.txt}
\caption[Using recursive C++ templates to produce dimension independent code]{Recursive C++ templates can be used to generate dimension independent code.
The first structure \texttt{Extrusion\_ranges\_map\_of\_dimension} (lines 1--8) contains the extrusion map for a single dimension.
The second structure \texttt{Extrusion\_ranges\_tuple\_per\_dimension\_up\_to} (lines 10--23) uses as a triplet of definitions to create copies of the first for every dimension up to a given one.
This is done using a template specialisation for dimension 0 which stops the recursion.
The last structure \texttt{Extrusion\_ranges\_tuple\_per\_dimension} (lines 25--32) creates all structures using the dimension of a passed combinatorial map \texttt{LCC}.
Note the non-ideal use of \texttt{std::map} in line 5.}
\label{fig:dimensionindependent}
\end{figure*}

The same technique can be used to create algorithms that are also fully dimension-independent.
In fact, C++ templates are known to be Turing-complete \citep{Veldhuizen03}, and thus can be used to compute general-purpose problems.
\reffig{fig:manifoldvalidation} shows one such example from the implementation of the incremental construction algorithm of \refch{ch:incremental-construction}, which shows the validation that a set of $(n-1)$-cells form a quasi-$n$-manifold.
\begin{figure*}[tb]
\centering
\small
\lstinputlisting[language=C++]{figs/manifoldvalidation.txt}
\caption[Dimension-independent algorithms using recursive C++ templates]{Recursive C++ templates can also be used to implement dimension-independent algorithms. In this case, the \texttt{dimension} that is passed to the templated function is passed on to other functions to obtain appropriate orbits for a given facet (\texttt{dimension-1}) or ridge (\texttt{dimension-2}), which are then compared dart by dart.}
\label{fig:manifoldvalidation}
\end{figure*}


\section{Longitudinal string excitation.}

\subsection{Hadron--nucleon inelastic collision.}

\hspace{1.0em}Let us consider collision of two hadrons with their c. m. momenta
$P_1 = \{E^{+}_1,m^2_1/E^{+}_1,{\bf 0}\}$ and $P_2 =
\{E^{-}_2,m^2_2/E^{-}_2,{\bf 0}\}$, where the light-cone variables
$E^{\pm}_{1,2} = E_{1,2} \pm P_{z1,2}$ are defined through hadron
energies $E_{1,2}=\sqrt{m^2_{1,2} + P^2_{z1,2}}$, hadron longitudinal
momenta $P_{z1,2}$ and hadron masses $m_{1,2}$, respectively. Two
hadrons collide by two partons with momenta $p_1 = \{x^{+}E^{+}_1,0,{\bf
0}\}$ and $p_2 = \{0, x^{-}E^{-}_2,{\bf 0}\}$, respectively.

\subsection{The diffractive string excitation.}

In the diffractive string excitation (the Fritiof approach \cite{FRITIOF87})
 only momentum can be transferred:
\begin{equation}
\label{LSE1}
\begin{array}{cc}
P^{\prime}_1 = P_1 + q\\
P^{\prime}_2 = P_2 -q,
\end{array}
\end{equation}
where
\begin{equation}
\label{LSE2}q=\{-q^2_t/(x^{-}E^{-}_2),q^2_t/(x^{+}E^{+}_1),\bf q_t \}
\end{equation}
 is parton
momentum transferred and ${\bf q_t}$ is its transverse component.
We use the Fritiof approach to simulate the diffractive excitation of
particles.

\subsection{The string excitation by parton exchange.}

\hspace{1.0em}For this case the parton exchange (rearrangement) and
the momentum exchange are allowed \cite{QGSM82},\cite{DPM94}:
\begin{equation}
\label{LSE3}
\begin{array}{cc}
P^{\prime}_1 = P_1 - p_1 + p_2 + q \\
P^{\prime}_2 = P_2 + p_1 - p_2 - q,
\end{array}
\end{equation}
where $q= \{0,0, {\bf q_t}\}$ is parton momentum transferred, i. e. only
its transverse components ${\bf q_t}$ is taken into account \cite{Am86}.

\subsection{Transverse momentum sampling.}

\hspace{1.0em}The transverse component of the parton momentum
transferred is generated according to probability
\begin{equation}
\label{LSE4}P({\bf q_t})d{\bf q_t} =
\sqrt{\frac{a}{\pi}} \exp{(-aq^2_t)}d{\bf q_t},
\end{equation}
where  parameter $a = 1.4$ GeV$^{-2}$.

{\bf $x^{+}$ and $x^{-}$ samplings.}

Light cone parton quantities $x^{+}$ and $x^{-}$ are generated
independently and according to distribution:
\begin{equation}
\label{LSE5} u(x) \sim x^{\alpha}(1 - x)^{\beta},
\end{equation}
where $x=x^{+}$ or $x=x^{-}$.
Parameters $\alpha =-1$ and $\beta = 0$ are chosen for the FRITIOF approach
\cite{FRITIOF87}. In the case of the QGSM approach \cite{Am86} $\alpha = -0.5$
and $\beta = 1.5$ or $\beta = 2.5$.  Masses of the excited strings
should satisfy the kinematical constraints:
\begin{equation}
\label{LSE6} P^{\prime +}_1 P^{\prime -}_1 \geq m^2_{h1} + q^2_t
\end{equation}
and
\begin{equation}
\label{LSE7} P^{\prime +}_2 P^{\prime -}_2 \geq m^2_{h2} + q^2_t,
\end{equation}
where hadronic masses $m_{h1}$ and $m_{h2}$ (model parameters) are
defined by string quark contents.  Thus, the random selection of the
values $x^{+}$ and $x^{-}$ is limited by above constraints.

\subsection{The string excitation by quark or diquark annihilation.}

\hspace{1.0em}
We consider also hadron-hadron inelastic processes when antiquark or
antidiquark from hadron projectile annihilate with corresponding quark
or diquark from hadron target.
In this case excitation of one baryonic (string with quark and diquark
ends) or mesonic (string with quark and antiquark ends) is created,
respectively. These processes in the Regge theory correspond to cut
reggeon exchange diagrams. Initial energy $\sqrt{s}$
dependences of these processes
cross sections are defined by  intercepts of reggeon exchange trajectories.
For example $\sigma_{\pi^{+}p\rightarrow S(s)} \sim s^{\alpha_{\rho}(0)-1}$,
$S$ notes string and $\alpha_{\rho}(0)$ is the intercept of $\rho$ reggeon
trajectory. Thus $\sigma_{\pi^{+}p\rightarrow S(s)}
$ decreases with energy
rise. Cross sections for other quark and diquark proccesses have simiar
as $\sigma_{\pi^{+}p\rightarrow S(s)}$ initial energy dependences.
Thus quark and diquark annihilation processes are important at
relative low initial energies. Another example of these processes is
$\bar{p}p \rightarrow S$, which is used in the kinetic model to describe
final state of $\bar{p}p$ annihilation.
Simulation of such kind process is rather simple. We should randomly
(according to weight calculated using hadron wave function)
choose quark (antiquark) or diquark (antidiquark) from projectile and
find suitable (with the same flavor content) partner for annihilation
from target. The created string four-momentum will be equal total reaction
four-momentum since annihilated system has small neglected momentum (only
low momenta quarks are able to annihilate).

To determine statistical weights for
 quark annihilation processes are leading to a string production
and separate them from processes, when two or more strings can be produced we
use the Regge motivated total cross section parametrization suggested by
Donnachie and Landshoff \cite{DL92}. Using their parametrization the
statistical weight for the one string production process is given by
\begin{equation}
\label{OSE1} W_{1} = \frac{Y_{hN}s^{-\eta}}{\sigma^{tot}_{hN}(s)}
\end{equation}
and statistical weight to produce two and more strings is given by
\begin{equation}
\label{OSE2} W_{2} = \frac{X_{hN}s^{\epsilon}}{\sigma^{tot}_{hN}(s)},
\end{equation}
where hadron-nucleon total cross sections  $\sigma^{tot}_{hN}(s)$ and its
fit parameters $Y_{hN}$, $X_{hN}$, which do not depend
from the total c.m. energy squared $s$ and depend on type of
projectile hadron $h$ and target nucleon $N$ can be found in \cite{PDG96}.
The reggeon intercept $\eta \approx
0.45$ and the pomeron intercept $\epsilon \approx 0.08$.

\subsection{Hadron--nucleus or nucleus--nucleus inelastic collisions.}

\hspace{1.0em}Hadron-nucleus or nucleus-nucleus collisions in the both
approaches (diffractive and parton exchange) are considered
as a set of the independent hadron-nucleon or
nucleon-nucleon collisions.  However, the string excitation procedures
in these approaches are rather different.

\subsection{The diffractive string excitation.}

\hspace{1.0em}In the diffractive string excitation (the
FRITIOF approach \cite{FRITIOF87}) for each
inelastic hadron--nucleon or nucleon--nucleon collision we have to select
randomly the transverse momentum transferred ${\bf q_t}$ (in accordance
with the probability given by Eq. ($\ref{LSE4}$)) and select randomly
the values of $x^{\pm}$ (in accordance with distribution defined by
Eq. ($\ref{LSE5}$)). Then we have to calculate the parton momentum
transferred $q$ using Eq. ($\ref{LSE2}$) and update scattered hadron
and nucleon or scatterred nucleon and nucleon momenta using
Eq. ($\ref{LSE3}$). For each collision we have to check the constraints
($\ref{LSE6}$) and ($\ref{LSE7}$), which can be written more
explicitly:
\begin{equation}
\label{LSE8} [E_1^{+} -\frac{q^2_t}{x^{-}E^{-}_2}][\frac{m_1^2}{E^{+}_1} +
\frac{q^2_t}{x^{+}E^{+}_1}]\geq m^2_{h1} + q^2_t
\end{equation}
and
\begin{equation}
\label{LSE9} [E_2^{-} +\frac{q^2_t}{x^{-}E^{-}_2}][\frac{m_2^2}{E^{-}_2} -
\frac{q^2_t}{x^{+}E^{+}_1}]\geq m^2_{h1} + q^2_t.
\end{equation}

\subsection{The string excitation by parton rearrangement.}

\hspace{1.0em}In this approach \cite{Am86} strings (as result of parton
rearrangement) should be spanned not only between valence quarks of
colliding hadrons, but also between valence and sea quarks and between
sea quarks.  The each participant hadron or nucleon should be splitted
into set of partons: valence quark and antiquark for meson or valence
quark (antiquark) and diquark (antidiquark) for baryon (antibaryon) and
additionaly the $(n-1)$ sea quark-antiquark pairs (their flavours are
selected according to probability ratios $ u:d:s = 1:1:0.35$), if hadron
or nucleon is participating in the $n$ inelastic collisions.  Thus for
each participant hadron or nucleon we have to generate a set of light
cone variables $x_{2n}$, where $x_{2n}=x^{+}_{2n}$ or
$x_{2n}=x^{-}_{2n}$ according to distribution:
\begin{equation}
\label{LS10} f^{h}(x_1,x_2,...,x_{2n})=f_{0}\prod_{i=1}^{2n}u^h_{q_i}(x_i)
\delta{(1-\sum_{i=1}^{2n}x_i)},
\end{equation}
where $f_0$ is the normalization constant.
Here, the quark structure functions $u_{q_i}^h(x_i)$ for valence quark
(antiquark) $q_v$,
sea quark and antiquark $q_s$ and valence diquark (antidiquark) $qq$ are:
\begin{equation}
\label{LS11}
u^h_{q_v}(x_v)=x_v^{\alpha_v},\ u^h_{q_s}(x_s)=x_s^{\alpha_s},\ u^h_{qq}(x_{qq})
=x_{qq}^{\beta_{qq}},
\end{equation}
where $\alpha_v = -0.5$ and $\alpha_s = -0.5$ \cite{QGSM82}
 for the non-strange quarks (antiquarks) and $\alpha_v =
0$ and $\alpha_s = 0$ for strange quarks (antiquarks), $\beta_{uu} =
1.5$ and $\beta_{ud} = 2.5$ for proton (antiproton) and $\beta_{dd} =
1.5$ and $\beta_{ud} = 2.5$ for neutron (antineutron).  Usualy $x_i$ are
selected between $x^{min}_i \leq x_i \leq 1$, where model parameter
$x^{min}$ is a function of initial energy, to prevent from production of
strings with low masses (less than hadron masses), when whole selection
procedure should be repeated.  Then the transverse momenta of partons
${\bf q_{it}}$ are generated according to the Gaussian probability
Eq. ($\ref{LSE4}$) and under the constraint: $\sum_{i=1}^{2n}{\bf
q_{it}}=0$. The partons are considered as the off-shell partons,
i. e. $m^2_i \neq 0$.

\subsection{Barion and meson splitting.}
\hspace{1.0em}To perform
 a simulation of the string excitation we need to split hadron and
choose valence quark (antiquark) and diquark (antidiquark). In the case
of a meson we split it into valence quark and antiquark (for neutral mixed
mesons this sampling is performed according to mixing probabilities.)
In the case of barion we determine probabilities of baryon (antbarion)
state (a quark (antiquark) and
diquark (antidiquark) with given spin and isospin)
 from $SU(6)$ symmetric wave barion functions. These probabilities are
 given in the Table 3.1.
\hspace{1.0em}
\begin{table}
\begin{center}
\begin{tabular}{|c|c|}
\hline
Baryon type & Quark content \\
\hline
$p$         &$1/3uu_{11}d+1/6(1/12)ud_{11}u+1/2(7/12)ud_{00}u$    \\
$n$         &$1/6(1/12)ud_{11}d+1/2(7/12)ud_{00}d+1/3dd_{11}u$    \\
$\Sigma^{+}$&$1/3uu_{11}s+1/6us_{11}u+1/2us_{00}u$    \\
$\Sigma^{0}$&$1/3ud_{11}s+1/12us_{11}d+1/4us_{00}d+1/12ds_{11}u+1/4ds_{00}u$\\
$\Sigma^{-}$&$1/3dd_{11}s+1/6ds_{11}d+1/2ds_{00}d$    \\
$\Xi^{-}$   &$1/6ds_{11}s+1/2ds_{00}s+1/3ss_{11}d$    \\
$\Xi^{0}$   &$1/6us_{11}s+1/2us_{00}s+1/3ss_{11}u$    \\
$\Lambda^{0}$&$1/3ud_{00}s+1/4us_{11}d+1/12us_{00}d+1/4ds_{11}u+1/12ds_{00}u$\\
$\Delta^{++}$&$uu_{11}u$    \\
$\Delta^{+}$ &$1/3uu_{11}d+2/3ud_{11}u$    \\
$\Delta^{0}$ &$2/3ud_{11}d+1/3dd_{11}u$    \\
$\Delta^{-}$ &$dd_{11}d$    \\
$\Sigma^{*+}$&$1/3uu_{11}s+2/3us_{11}u$    \\
$\Sigma^{*0}$&$1/3ud_{11}s+1/3us_{11}d+1/3ds_{11}u$\\
$\Sigma^{*-}$&$1/3dd_{11}s+2/3ds_{11}d$    \\
$\Xi^{*0}$   &$1/3us_{11}s+2/3ss_{11}u$    \\
$\Xi^{*-}$   &$2/3ds_{11}s+1/3ss_{11}d$    \\
$\Omega^{-}$   &$ss_{11}s$    \\
\hline
\end{tabular}
\end{center}
Table 3.1: Baryon quark contents. Diquark indices indicate spin-isospin states.
\end{table}
We also  use these probability to sample barion or barion resonance in
the string fragmentation, assuming that a valence diquark (antidiquark)
keeps its spin and isospin during whole reaction.


\chapter{Methodology}
\newtheorem{definition}{Definition}
% \label{ch:relatedwork}
As mentioned in the previous sections, the rapid increase in IoT devices as well as its use-cases has
significantly impacted and at times more often than not, improved our experiences. However, when these
personal, and usually hand-held or wearable devices like smart phones and smart watches, have a
plethora of added functionality, it also poses the problem of increased energy consumption. This results
on a less uptime for one charge of a battery which corresponds to the device not being utilized for proper
amounts of time. This is especially important in the healthcare sector where a device monitoring a patient's
vitals should be able to do so for prolonged lengths of time. \\
In this thesis, our study focused on optimizing energy consumption for communication. Most applications
on an edge device usually communicate with a remote server to exchange different data and it varies from
application to application. But within these applications, communication is a core aspect which is not
being investigated by researchers.
The best general practice used when designing these applications is to send data in sizes multiples of 2, which
generally means faster communication without unwanted packet drops but on the other hand, is no where near
optimal. This is due to the fact that each edge device may have different hardware and different software
versions, and the energy cost for communication for each possible variation of these is different \cite{6200281}. It has no
optimal trend, therefore, the best practice is to use general values of chunk sizes that the protocol
can easily handle. Our work focuses on communication cost because most of the times other hardware related
factors are not flexible or would otherwise compromise the integrity of the task. \\

This work is divided into two portions. First, we present a pretty straightforward way to estimate an
application's energy consumption over time. Next, we present an approach to compute optimal chunk sizes
for respective edge devices. We evaluate and confirm whether this optimal chunk size approach consumes less
energy or not with the help of our energy estimation approach, on two real-world applications. \\
\section{Estimating Energy Usage}
There have been other approaches in the past to estimate energy consumption of applications \cite{6606555} but we
adopt an approach that is similar to energest \cite{energest} which is an energy profiling approach for Contiki OS.
We combine runtime information from applications with static information from data sheets of specific
hardware components to estimate energy consumption. Before getting into the details, we will define some
terminologies. \\

\begin{definition}
    \textbf{Current }(I) is defined as the flow of electrical charge (q) over time (t). It is measured in Amperes (A).
\end{definition}

\begin{definition}
    \textbf{Power}(P) is defined as the amount of charge (q) moved through voltage (V) in a time interval (t). It is measured in Watts (W).
\end{definition}

For devices powered by a battery, both current and voltage is an important factor and is heavily dependent
on the components used on the device itself. Different electrical components operate on different voltages, thereby,
drawing different amounts of current, resulting in different power consumption. However, in order to calculate the
energy consumption, the dynamic factor is time. Power used or spent over a specific period of time equals the
energy used by the specific device or specific component of device.

\begin{definition}
    \textbf{Energy}(E) is defined as the amount of power (P) expended over a time interval (t). It is measured in Joules (J).
\end{definition}

We use these definitions to be able to express how we estimate the energy consumption of a specific edge IoT device.
Almost all hardware components when designed and brought to market have a corresponding data sheet publicly available,
with important information such as circuit diagrams, and current and voltage values for different modes (if possible). Current
and voltage are dynamic factors however by using information from said data sheets, we can estimate these values by
computing the mean average sum of values corresponding to different operating modes. The data sheet for BCM43455, the
wifi adapter used in Raspberry Pi 4 Model B \cite{cypress} contains valuable information regarding different technical
details such as frequency, circuit design, power management etc. However,
what is interesting to us is current and voltage values. Figure \ref{fig:bcm} provides a snapshot from one such table.
It outlines the different current values corresponding to different voltage values for different modes. In a
real world setting, the devices switch between these modes depending on various factors. A reasonable assumption
in this case would be to take the mean average sum of values for different modes. \\

\begin{figure}
    \begin{center}
        \includegraphics[scale=0.25]{Figs/datasheet.png}
    \end{center}
    \caption{Current and Voltage values for BCM43455}
    \label{fig:bcm}
\end{figure}

Given this information, we can estimate the power \texttt{P} that the wifi adapter would use in this case when it is
turned on. Consider an app \texttt{A} which finishes executing in about \texttt{t} seconds. The total energy
consumed (by the wifi adapter) by running \texttt{A} would then be calculated by \texttt{E = P * t}. \\
In order to calculate the estimated energy for specific block of code, such as ones which handle communication, all one
needs to do is instrument the app to log execution time for that specific block of code. And then we can
calculate the energy usage of that specific portion of program. The main idea behind this approach to
estimate energy is that software developers don't usually have the technical equipment required to
individually measure current and voltage values of actual devices. Given that setback, estimating energy
consumption off of publicly available data sheets and runtime information from the app itself is a
pretty reliable way to gather the required data. \\
\section{Calculating Optimal Chunk Size}
As mentioned before, our study focuses on optimizing communication cost of applications for IoT edge devices.
Even though the best practices involved in this case do perform well for average case, our hypothesis
is that after a communication pipe is established between the client and the server, having data sent or
received in different chunk sizes could have an impact on the energy consumption of the whole process.
The motivation behind this is that even though hardware optimizations such as power saving modes improve
energy consumption efficiency, there are still software related configurations that can be altered to reduce
the overall energy usage. We chose to focus on communication cost because it is an integral part of more or less
every app deployed on an edge device where it communicated with the server one way or another to transmit
some sort of data. \\
But why communication cost? Indeed, there are multiple code related factors that can help optimize energy
consumption but our work is done under the assumption that these factors, such as data collection, via the
sensor, the disk I/O operations etc. differ heavily from use-case to use-case and any alteration in code
functionality to them, may affect their usage in real world. For example, a device monitoring a patient's
heartbeat continuously is bound to use more energy than, let's say, monitoring every five minutes.
However, in these kinds of critical health monitoring applications, such types of optimizations severely undermine the actual
functionality of the app. Therefore, our approach addresses a factor that is independent of the sensor
usage in such a context and can potentially work on diverse examples. \\
To better explain how we calculate the optimal chunk size, we will first define energy-per-byte or EPB.
It is a metric we use to determine which chunk size consumes the least amount of energy. \\

\begin{definition}
    \textbf{EPB} or Energy-per-Byte is defined as the amount of energy consumed when a single byte of data is sent from one device to another.
\end{definition}

But why is EPB an important factor rather than the overall energy consumed for the corresponding chunk size?
We will explain this with the help of an example. Consider an app \texttt{C} on the edge device \texttt{EdgeD} that needs
to send 256 bytes to the server-side app \texttt{S}. Assume you calculated the energy to send data at a
chunk size of 64 bytes was the lowest at \texttt{E1} Joules. However, if you used 128 bytes at a time to
send this data, you consume \texttt{E2} Joules which is slightly more than \texttt{E1}. In this case,
we can not say the 64 bytes is the optimal chunk size for \texttt{EdgeD} because it would take \texttt{E1*4}
amounts of energy to send the complete data and \texttt{E2*2} on the other hand. For the sake of this
example, assume \texttt{E1} has the arbitrary value of 2 Joules (actual values are way way less and are usually
in microJoules) and \texttt{E2} has the arbitrary value of 3 Joules. 64 bytes would take 8 Joules in total
to send 256 bytes of data where as 128 bytes of chunk size would only use 6 Joules. That is why, EPB is an
important factor and metric in this case. So what we need to do is divide \texttt{E1} by 64 and \texttt{E2}
by 128 to get the EPB for their respective chunk sizes. Now, the lower energy consumption value of the
two would be the optimal one as it would consume the lowest amount of energy among different chunk sizes. \\
To calculate the optimal chunk size on an edge device, we deploy a Python script which comprises of a
list of different chunk sizes of order \texttt{$2^{n}$} where \texttt{n} by default can be anything between
1 and 30 (included). The upper limit can be adjusted depending on the use case of the program. It then
proceeds to send data in different chunk sizes and then measure the time it took for the communication to take
place. This time is then used to calculated the overall energy consumption for sending a specific amount of
data. It must be mentioned here that the chunk size is also bounded by the protocol being used and
the local disk space of the device.
It is provided as a pseudocode in algorithm \ref{alg:two} on the next page. For both evaluation subjects,
we use the same pseudocode but had to implement it in Python and Java for both applications respectively. \\
\SetKwComment{Comment}{/* }{ */}

\begin{algorithm}
\caption{Pseudocode for determining optimal chunk size}\label{alg:two}
\Comment{n is the upper limit of chunk size as exponent of 2, p is the power computed from datasheet }
\KwData{$n \geq 0, p$}
\Comment{Array of energy consumption for each chunk size}
\KwResult{$energyArray$}
$N \gets n$\;
$P \gets p$\;
% $timeArray \gets \phi$\;
$energyArray \gets \phi$\;
\While{$N \neq 0$}{
     \Comment{Create a byte array of the given size using a helper function}
     $array \gets CreateByteArray(2^N)$\;
     \Comment{Start a timer}
     $start \gets GetCurrentTime()$\;
     \Comment{Send the data to the server}
     $SendToServer(array)$\;
     \Comment{Stop the timer and compute the difference}
     $end \gets GetCurrentTime()$\;
     $executionTime \gets end-start$\;
     \Comment{Compute the EPB and store it in array}
     $energy \gets P * executionTime$\;
     $EPB \gets energy/2^N$\;
     $energyArray \gets energyArray \cup EPB$\;
}
\end{algorithm}
This is a pretty straightforward but novel approach to aid programmers in developing applications for
a target edge device where they can optimize the communication cost in terms of energy. In some use cases, the
difference is considerable while in others it may not be that much. In short, it depends on the nature of the app
itself. The following section will clarify more as to why it is as we describe our experimental and nature of the
applications, and discuss our results. \\