\XtoCBlock{TF1}
\label{block:TF1}
\begin{figure}[H]\includegraphics{TF1}\end{figure}

\begin{XtoCtabular}{Inports}
In & Input In(k)\tabularnewline
\hline
\end{XtoCtabular}

\begin{XtoCtabular}{Outports}
Out & Output Out(k)\tabularnewline
\hline
\end{XtoCtabular}

\begin{XtoCtabular}{Mask Parameters}
b1 & b1\tabularnewline
\hline
b0 & b0\tabularnewline
\hline
a0 & a0\tabularnewline
\hline
ts\_fact & Multiplication factor of base sampling time (in integer format)\tabularnewline
\hline
\end{XtoCtabular}

\subsubsection*{Description:}
First order transfer function:

    G(z) = (b1.z + b0) / (z + a0)

% include optional documentation file
\InputIfFileExists{\XcHomePath/Library/Control/Doc/TF1_Info.tex}{\vspace{1ex}}{}

\subsubsection*{Implementations:}
\begin{tabular}{l l}
\textbf{FiP8} & 8 Bit Fixed Point Implementation\tabularnewline
\textbf{FiP16} & 16 Bit Fixed Point Implementation\tabularnewline
\textbf{FiP32} & 32 Bit Fixed Point Implementation\tabularnewline
\textbf{Float32} & 32 Bit Floating Point Implementation\tabularnewline
\textbf{Float64} & 64 Bit Floating Point Implementation\tabularnewline
\end{tabular}

\XtoCImplementation{FiP8}
\index{Block ID!3280}
\nopagebreak[0]
% Implementation details
\begin{tabular}{l l}
\textbf{Name} & FiP8 \tabularnewline
\textbf{ID} & 3280 \tabularnewline
\textbf{Revision} & 0.1 \tabularnewline
\textbf{C filename} & TF1\_FiP8.c \tabularnewline
\textbf{H filename} & TF1\_FiP8.h \tabularnewline
\end{tabular}
\vspace{1ex}

8 Bit Fixed Point Implementation

\begin{XtoCtabular}{Controller Parameters}
b0 & Coefficient b0\tabularnewline
\hline
b1 & Coefficient b1\tabularnewline
\hline
a0 & Coefficient a0\tabularnewline
\hline
sfrb & Shift factor for coefficient b0 and b1\tabularnewline
\hline
sfra & Shift factor for coefficient a0\tabularnewline
\hline
in\_old & In(k-1)\tabularnewline
\hline
\end{XtoCtabular}

% Implementation data structure
\XtoCDataStruct{Data Structure:}
\begin{lstlisting}
typedef struct {
     uint16        ID;
     int8          *In;
     int8          Out;
     int8          b0;
     int8          b1;
     int8          a0;
     int8          sfrb;
     int8          sfra;
     int8          in_old;
} TF1_FIP8;
\end{lstlisting}

\ifdefined \AddTestReports
\InputIfFileExists{\XcHomePath/Library/Control/Doc/Test_TF1_FiP8.tex}{}{}
\fi
\XtoCImplementation{FiP16}
\index{Block ID!3281}
\nopagebreak[0]
% Implementation details
\begin{tabular}{l l}
\textbf{Name} & FiP16 \tabularnewline
\textbf{ID} & 3281 \tabularnewline
\textbf{Revision} & 0.1 \tabularnewline
\textbf{C filename} & TF1\_FiP16.c \tabularnewline
\textbf{H filename} & TF1\_FiP16.h \tabularnewline
\end{tabular}
\vspace{1ex}

16 Bit Fixed Point Implementation

\begin{XtoCtabular}{Controller Parameters}
b0 & Coefficient b0\tabularnewline
\hline
b1 & Coefficient b1\tabularnewline
\hline
a0 & Coefficient a0\tabularnewline
\hline
sfrb & Shift factor for coefficient b0 and b1\tabularnewline
\hline
sfra & Shift factor for coefficient a0\tabularnewline
\hline
in\_old & In(k-1)\tabularnewline
\hline
\end{XtoCtabular}

% Implementation data structure
\XtoCDataStruct{Data Structure:}
\begin{lstlisting}
typedef struct {
     uint16        ID;
     int16         *In;
     int16         Out;
     int16         b0;
     int16         b1;
     int16         a0;
     int8          sfrb;
     int8          sfra;
     int16         in_old;
} TF1_FIP16;
\end{lstlisting}

\ifdefined \AddTestReports
\InputIfFileExists{\XcHomePath/Library/Control/Doc/Test_TF1_FiP16.tex}{}{}
\fi
\XtoCImplementation{FiP32}
\index{Block ID!3282}
\nopagebreak[0]
% Implementation details
\begin{tabular}{l l}
\textbf{Name} & FiP32 \tabularnewline
\textbf{ID} & 3282 \tabularnewline
\textbf{Revision} & 0.1 \tabularnewline
\textbf{C filename} & TF1\_FiP32.c \tabularnewline
\textbf{H filename} & TF1\_FiP32.h \tabularnewline
\end{tabular}
\vspace{1ex}

32 Bit Fixed Point Implementation

\begin{XtoCtabular}{Controller Parameters}
b0 & Coefficient b0\tabularnewline
\hline
b1 & Coefficient b1\tabularnewline
\hline
a0 & Coefficient a0\tabularnewline
\hline
sfrb & Shift factor for coefficient b0 and b1\tabularnewline
\hline
sfra & Shift factor for coefficient a0\tabularnewline
\hline
in\_old & In(k-1)\tabularnewline
\hline
\end{XtoCtabular}

% Implementation data structure
\XtoCDataStruct{Data Structure:}
\begin{lstlisting}
typedef struct {
     uint16        ID;
     int32         *In;
     int32         Out;
     int32         b0;
     int32         b1;
     int32         a0;
     int8          sfrb;
     int8          sfra;
     int32         in_old;
} TF1_FIP32;
\end{lstlisting}

\ifdefined \AddTestReports
\InputIfFileExists{\XcHomePath/Library/Control/Doc/Test_TF1_FiP32.tex}{}{}
\fi
\XtoCImplementation{Float32}
\index{Block ID!3283}
\nopagebreak[0]
% Implementation details
\begin{tabular}{l l}
\textbf{Name} & Float32 \tabularnewline
\textbf{ID} & 3283 \tabularnewline
\textbf{Revision} & 0.1 \tabularnewline
\textbf{C filename} & TF1\_Float32.c \tabularnewline
\textbf{H filename} & TF1\_Float32.h \tabularnewline
\end{tabular}
\vspace{1ex}

32 Bit Floating Point Implementation

\begin{XtoCtabular}{Controller Parameters}
b0 & Coefficient b0\tabularnewline
\hline
b1 & Coefficient b1\tabularnewline
\hline
a0 & Coefficient a0\tabularnewline
\hline
in\_old & In(k-1)\tabularnewline
\hline
\end{XtoCtabular}

% Implementation data structure
\XtoCDataStruct{Data Structure:}
\begin{lstlisting}
typedef struct {
     uint16        ID;
     float32       *In;
     float32       Out;
     float32       b0;
     float32       b1;
     float32       a0;
     float32       in_old;
} TF1_FLOAT32;
\end{lstlisting}

\ifdefined \AddTestReports
\InputIfFileExists{\XcHomePath/Library/Control/Doc/Test_TF1_Float32.tex}{}{}
\fi
\XtoCImplementation{Float64}
\index{Block ID!3284}
\nopagebreak[0]
% Implementation details
\begin{tabular}{l l}
\textbf{Name} & Float64 \tabularnewline
\textbf{ID} & 3284 \tabularnewline
\textbf{Revision} & 0.1 \tabularnewline
\textbf{C filename} & TF1\_Float64.c \tabularnewline
\textbf{H filename} & TF1\_Float64.h \tabularnewline
\end{tabular}
\vspace{1ex}

64 Bit Floating Point Implementation

\begin{XtoCtabular}{Controller Parameters}
b0 & Coefficient b0\tabularnewline
\hline
b1 & Coefficient b1\tabularnewline
\hline
a0 & Coefficient a0\tabularnewline
\hline
in\_old & In(k-1)\tabularnewline
\hline
\end{XtoCtabular}

% Implementation data structure
\XtoCDataStruct{Data Structure:}
\begin{lstlisting}
typedef struct {
     uint16        ID;
     float64       *In;
     float64       Out;
     float64       b0;
     float64       b1;
     float64       a0;
     float64       in_old;
} TF1_FLOAT64;
\end{lstlisting}

\ifdefined \AddTestReports
\InputIfFileExists{\XcHomePath/Library/Control/Doc/Test_TF1_Float64.tex}{}{}
\fi


%!TEX root = ../Thesis.tex
\chapter{Introduction}\label{cha:introduction}
%
This chapter presents a short history, motivation, and background in the fields of mathematical programming and machine learning, summarizes the previous work on the topic of \textit{learning-to-branch}, poses the research questions for the project, and explains the structure of the project. \Cref{sec:int_background,sec:int_previouswork} and \ref{sec:int_structure} are adapted from the project report \textit{Multi-Layer Perceptrons for Branching in Mixed-Integer Linear Programming} (2020).

\section{Background}\label{sec:int_background}

In this section, a background in the relevant fields of mathematical programming and machine learning is presented, as well as an overview of the previous work in combining these fields. A familiarity of the reader with the central concepts and terms in this field is assumed.

\subsection{Mathematical Programming}

The invention of efficient solution algorithms for linear mathematical programming problems is considered one of the great post-war inventions \cite{dantzig1983reminiscences}. The simplex algorithm and its derivatives have since become ubiquitous in a number of disciplines including finance, engineering, transportation, and energy \cite{junger2010years}. These algorithms allow for the efficient solution of the global optimum of linear functions with an objective function, a number of variables and a number of constraints on these variables. However, the simplex algorithm is limited to problems where the \textit{feasible set} of possible solutions is convex.

To further increase the expressiveness of the linear programming \textit{language}, the inclusion of non-convex constraints such as limiting variables to only take integer values, is a reoccurring limitation in modeling real-world problems in a mathematical programming language. The set of linear optimization problems with these integer constraints is known as \textit{mixed-integer linear programs} (\gls{MILP}). The inclusion of integer constraints to linear problems has proved to be a very challenging problem class to develop efficient solution algorithms for, and it is considered unlikely that a polynomial-time solution algorithm exists \cite{bengio2020machine}.

For problems including integer constraints, the na\"ive approach of comparing every possible combination of feasible solutions, known as \textit{explicit enumeration}, will result in a solution algorithm that is of exponential complexity, which makes larger optimization problems intractable \cite{wolsey2020integer}. An alternative to explicit enumeration is \textit{implicit enumeration}, where a large number of possible solutions do not have to be evaluated explicitly.
\textit{Branch-and-bound} (\gls{BnB}), conceived in 1960 \cite{land1960automatic}, is an algorithm for solving mathematical programming problems via implicit enumeration that has become the standard solution algorithm \cite{wolsey2020integer}. It has since received numerous improvements and extensions \cite{wolsey2020integer}.

For time-constrained applications of these non-convex optimization problems, a decrease in time to calculate the optimal solution can result in significant improvements and has been a very active field of research for many decades \cite{wolsey2020integer}. For the interested reader, the modern advances of \textit{branch-and-cut}, \textit{column generation}, and \textit{Bender's decomposition} algorithms are recommended reading in \textit{Integer Programming} by Lawrence Wolsey \cite{wolsey2020integer}.

Currently, the most efficient solution algorithms using Branch and Bound are proprietary algorithms, notably IBM CPLEX and Gurobi \cite{anand2017comparative}. Open-source solvers also exist and are under continuous development, e.g. \gls{COIN-OR} and \gls{SCIP} Optimization Suites \cite{achterberg2009scip,anand2017comparative}. The algorithms are highly complex and employ a large variety of methods to quickly solve the complex problems \cite{wolsey2020integer}.

There is a large interest in both theoretical and practical mathematical programming for methods that can improve the efficiency of \gls{MILP} optimization algorithms \cite{wolsey2020integer}. This can have a lasting impact on the nature of mathematical programming and is therefore an important area to explore further. Researchers in mathematical optimization have also noted the potential for expert-constructed branching strategies based on knowledge obtained from \textit{statistical learning}, also known as \textit{machine learning} (\Gls{ML}) \cite{lodi2017learning}.

\subsection{Machine Learning}

The current dominating paradigm of \textit{artificial intelligence} (\gls{AI}) is \textit{machine learning}, where computers (algorithms) learn from experience (data) \cite{goodfellow2016deep}. The capabilities of these models have had exponential success in recent years, much due to advances in computer hardware \cite{goodfellow2016deep}. A variety of fields have seen breakthroughs by using \gls{ML} methods, including medical diagnostics, industrial optimization, autonomous vehicles, and board games \cite{goodfellow2016deep}.

There are a number of sub-fields within machine learning. In this project, the class known as \textit{supervised classification} is explored. Supervised classification is the general problem of dividing instances into classes based on past instances and their respective classes. These models learn through observing examples of past data and their classifications. The basic assumption is that the \gls{ML} model will learn from its experience, and be accurate in classifying previously unseen data.

An important field within machine learning in the last decade is \textit{deep learning} (\gls{DL}), where models are built up of series of nonlinear functions \cite{goodfellow2016deep}. The \textit{multi-layer perceptron} (\gls{MLP}), or feedforward deep neural network, is the most common model in Deep Learning \cite{goodfellow2016deep}. Nonlinear representations are iteratively performed, giving the model a large \textit{capacity} for representing complex relations between input and output.

For many tasks, e.g. tasks with a real-time component, the strength of \gls{ML} models lies in the fast evaluation of the generated, nonlinear functions, also known as the \textit{inference} \cite{bertsimas2019online}. This strength makes it possible for machines to take over tasks previously thought to require a human operator or increase efficiency greatly via automation.

Further, the results of the iterative optimization process of generating an \gls{ML} model can find patterns in data that are difficult to discover with traditional statistics \cite{goodfellow2016deep}. Much like chess grandmasters learn from observing the best \gls{AI} algorithms, so too might experts gain knowledge in their respective fields by analyzing the inner workings of an algorithm built on statistical learning.

Within the field of machine learning, the concept of \textit{ablations} and \textit{ablation studies} are gaining interest \cite{meyes2019ablation}. In an ablation study, the performance of a learned model is examined after the removal of sections of the original model. This is performed in an attempt to understand the role of a section within a complex system.

\section{Previous Work}\label{sec:int_previouswork}

There has been a recent surge of interest in leveraging machine learning methods in solving non-convex optimization problems, notably in a recent literature review conducted by Yoshua Bengio \cite{bengio2020machine}. The aim is for statistical learning to aid in the efficient solving of complex problems without sacrificing the strong guarantees inherent in mathematical optimization solvers. These hybrid methods now show the potential to be competitive with the state-of-the-art solvers for these difficult problems \cite{gasse2019exact}.

An overview of the history of learning in \gls{BnB} is given a survey paper by Lodi and Zarpellon \cite{lodi2017learning}. To summarize, interest in using more advanced statistics to unravel the relations of a \gls{MILP} problem and the optimal branching variable was first presented in 2009. Various approaches to learning have been attempted, with recent efforts to directly incorporate the learned algorithms into the solution algorithm from 2016 and onwards \cite{lodi2017learning}.

A thorough look into the possibilities of machine learning in \gls{BnB} was conducted by Elias Khalil \cite{khalil2020towards}, in which he chose the term \textit{data-driven algorithm design} for this approach.
In \textit{Learning to Branch} (2016) \cite{khalil2016learning} imitation learning of an expert branching policy. The algorithm was competitive with a selection of modern solvers \cite{khalil2016learning}.
Recent advances using\textit{ graph convolutional neural networks} (\Gls{GCNN}s) have proved to consistently improve on the solution time of the best available open-source solvers by Gasse et al. (2019) \cite{gasse2019exact}.

The promising results found by Gasse et al. (2019) \cite{gasse2019exact} were, however, criticized by Gupta et al. (2020) \cite{gupta2020hybrid} for reliance on modern \gls{GPU} processing power. They showed that the efficiency of the \gls{GCNN}-aided algorithm did not improve on the native branching strategies when run on a \gls{CPU}. Gupta et al. presented novel methods running only on the \gls{CPU} that were able to improve on the native strategies. These methods include \textit{support vector machines} (\Gls{SVM}), \textit{multi-layer perceptrons} (\Gls{MLP}), and  \textit{feature-wise linear modulation models} (\gls{FiLM}) \cite{gupta2020hybrid}.

Though \gls{GPU} aided algorithms are interesting in their own right, a fair comparison of algorithmic efficiency cannot be made when the machine learning-based models are aided by expensive, advanced and specialized \gls{GPU} processing power, as in Gasse et al. (2019) \cite{gasse2019exact}. However, the efficiency when run on a \gls{GPU} will be interesting for applications where this is available.
For this reason, all analysis of computational efficiency in this project will be performed on both \gls{GPU} and \gls{CPU}. Discrete optimization performed on \gls{GPU}s is a very interesting topic, for a discussion on Branch and Bound algorithms on \gls{GPU}s the reader is referred to Schultz et al. \cite{schulz2013gpu}. It is also assumed by the author that advances in ML aided optimization can combine nicely with advances in parallel computing and specialized hardware.

The methods of Gasse et al. (2019) \cite{gasse2019exact} and the improvements made by Gupta et al. (2020) \cite{gupta2020hybrid} have shown that data-driven methods can improve upon existing state-of-the-art solvers, and is therefore an avenue worth examining, exploring, and expanding further. Machine learning is a rapidly evolving field, and recent advances have shown to outclass the early proof-of-concept attempts, sometimes by considerable margins \cite{holzinger2018current}. There is little reason to believe that \gls{ML}-leveraged algorithms do not have this latent potential. %Further, many projects on implementing \gls{RL} in \gls{BnB} \cite{tang2020reinforcement,etheve2020reinforcement} an understanding of the relevant Neural Network models is fundamental.

Recent attempts to facilitate the development of \gls{ML}-aided \gls{BnB} includes a notable project named \textit{Extensible Combinatorial Optimization Learning Environments} (\emph{Ecole}) \cite{prouvost2020ecole, prouvost2021ecole}. It was developed by the group \textit{Data Science For Decision Making} (\gls{DS4DM}), connected to the Polytechnique Montr\'{e}al university. \gls{Ecole} is an open-source framework for a controllable and extensible python interface to \gls{BnB} algorithms and is built on \gls{SCIP} and PySCIPOpt \cite{prouvost2020ecole}. The framework is based on previous work from the group, notably Gasse et al. (2019) \cite{gasse2019exact} and Gupta et al. (2020) \cite{gupta2020hybrid}, and aims to standardize research within the field of \gls{BnB} algorithm improvement.
 A recent article by
Cappart et al. (2021) \cite{cappart2021combinatorial} presents the current status of and the role of the \gls{Ecole} framework in further developing this field.
As of May 2021, no articles have been published with results using this framework, bar the aforementioned introducing articles.

\section{Motivation}\label{sec:int_motivation}

As stated, the ubiquity of \gls{BnB} algorithms in industry implies that increased efficiency in computation time will be very beneficial. The benefits could be in the form of reduced resource expenditure on computations, increased time resolution in real-time applications, or even new applications due to the increased efficiency.

Machine learning has been proved by many researchers to be a good candidate for improving \gls{BnB} \cite{khalil2016learning,gasse2019exact,gupta2020hybrid,khalil2020towards,etheve2020reinforcement}. Of these, the graph convolutional neural network presented in Gasse et al. (2019) \cite{gasse2019exact} has received the most attention and provides a very interesting approach to the variable selection problem in \gls{BnB}. The model showed satisfactory improvements over the \gls{SCIP} native brancher, however, the model was shown to be non-competitive when running on a \gls{CPU} in Gupta et al. (2020).

While the alternative models presented in Gupta et al. (2020) \cite{gupta2020hybrid} are interesting, a thorough exploration of the more standard models in \gls{ML} (\gls{GCNN}s and \gls{MLP}s) is assumed to be more fruitful if they can achieve similar performance. The \gls{GCNN} developed and presented in Gasse et al. (2019) \cite{gasse2019exact} (from now on referred to as the \textit{Gasse \gls{GCNN}}) might not be competitive on the \gls{CPU} in the current configuration, however, this does not necessarily mean that the \gls{GCNN} architecture is unsuited for the application on a \gls{CPU}.

A comparison, with the solution efficiency reported on both \gls{GPU} and \gls{CPU}, of a selection of simplified variants of the Gasse \gls{GCNN} can give further insight into the model accuracy versus solution efficiency trade-off. When future researchers chose \gls{ML} models for learning in \gls{BnB}, this work will serve as a resource to better understand this trade-off on the two different computational resources.

The term \textit{iterative ablations} (\Gls{IA}) will be used to describe the process of removing parts of a network sequentially. The term is, to the knowledge of the author, only used once before, in the context of ablative liver surgery in Seror (2015) \cite{seror2015ablative}.

In addition, the choice to implement the source code in the new \gls{Ecole} framework is a conscious decision to aid in the standardization of how research is done within the field of improving \gls{BnB} algorithms.

\section{Research Questions}\label{sec:int_questions}

For this project, three research questions are considered. This is done to aid the reader in following the thesis. The questions will be answered explicitly in \Cref{cha:discussion}. In addition, the topics of accuracy-efficiency-implementation will be reoccurring throughout the chapters of the thesis.

The research questions are as follows:
%
\begin{enumerate}[label=(\roman*)]
    \item \textit{What is the impact of iterative ablations on the accuracy of the Gasse \gls{GCNN}?}
\end{enumerate}
%
The \gls{GCNN} successfully implemented in Gasse et al. (2019) \cite{gasse2019exact} was criticized in Gupta et al. (2020) for not being competitive with the classical strategies when run on a \gls{CPU}.
Hybrid models were implemented in Gupta et al. (2019) \cite{gupta2020hybrid}, where \Gls{GCNN} features were combined with the general variable features. This is done to mitigate the loss in efficiency by running \gls{GCNN}s on the \gls{CPU}. To investigate whether the original model can be competitive on both the \gls{GPU} and \gls{CPU}, 5 models are constructed by iteratively reducing the model size. These models will be referred to as GNN2, GNN1, MLP3, MLP2, and MLP1. The last models will consist of multi-layer perceptrons with only the variable features, and will therefore have dissimilar names. The \gls{MLP} models are devised based on promising results found in the project \textit{Multi-Layer Perceptrons for Learning to Branch
} (2020).
%
\begin{enumerate}[resume*]
    \item \textit{What is the impact of iterative ablations on the efficiency of the Gasse \gls{GCNN} when run on the \gls{CPU} and \gls{GPU} as a part of the \gls{BnB} algorithm}?
\end{enumerate}
%
Machine learning model choice based on reduced complexity is cited as a motivation for design choices in Gupta et al. \cite{gupta2020hybrid}, however the impact of varying sizes of the same model has not been performed before, and the magnitude of the impact is unknown. Increased model capacity is known to facilitate higher accuracy \cite{goodfellow2016deep}, however, whether this has a detrimental effect on the Branch and Bound algorithm's overall performance is unknown. Results from methods that are more comparable will indicate the importance of accuracy versus computational complexity. It is also not clear whether the graph convolution as developed in the Gasse \gls{GCNN} is the component resulting in a detrimental loss of \gls{CPU} performance. By conducting all experiments on both types of hardware, results should be sufficient to conclude with a degree of certainty what the accuracy and efficiency trade-offs are and what differences there are between the \gls{CPU} and \gls{GPU} methods.
%
\begin{enumerate}[resume*]
    \item \textit{What are the most promising research opportunities for learning in Branch and Bound?}
\end{enumerate}
%
The general field has gained traction recently \cite{bengio2020machine}, and the author assumes more research and interest will come in the next few years. In the implementation of this project, the new framework \gls{Ecole} is used. This is the first paper where \gls{Ecole} is used as the basis for the experiments, and an independent review of this framework is due. The road towards a conform and standardized framework and practice to develop methods in the field of \gls{ML} aided \Gls{BnB} can increase productivity and usher in breakthroughs in this field. On a broader note, as there is so much interest in the field, providing ideas for further research appears highly relevant.

\section{Thesis Structure}\label{sec:int_structure}

\Cref{cha:introduction} contains an introduction to the thesis with a short background in the relevant field, an overview of previous work, a section on the motivation for the conducted experiments, a formulation of the three research questions, and an overview of the thesis structure.
In the following chapter, \Cref{cha:background}, the necessary theoretical background in optimization and machine learning is presented, as well as a review of earlier work in the field. In \Cref{cha:methods}, the data set, chosen training and testing methods, and experiments are presented, along with the architectural choices. \Cref{cha:results} provides the results of the aforementioned experiments. Then, \Cref{cha:discussion} contains discussions of the results, a critique of the experiments, and ideas for further work. Finally, \Cref{cha:conclusion} summarizes the project with a conclusion on the implications of the results. Additional material is provided in \Cref{cha:dists} and \Cref{cha:coefficients}.


 \section{Overview and common stuff}

There are several things you should know when you read
the kernel program codes.

\subsection{Coding rule of \NICAM}

\NICAM is written with Fortran90/95 standards, and uses \src{module} to
modularize the program.
%
Module name begins with \src{mod_}, such as \src{mod_adm}.
%
Almost all source file defines only one module and have the same name
with the module, such as \file{mod_adm.f90}
%
Several modules are used to define public parameters, variables, and
subroutines, called ``public object''.
%
Name of such objects are prefixed its module name.
%
For example, \src{ADM_gall} is defined in module \src{mod_adm} that is
defined in \file{mod_adm.f90} in original \NICAM source.
%
Among the public objects, variables and parameters related to the
problem size are moved and defined in \file{problem_size.inc}, that is
included in \file{mod_misc.f90}

\subsection{Data array for regular region}

\autoref{f:data_store_regular} shows the schematic figure of data layout
in a regular region.
%
The grid points managed in the region are black circles, and white and
blue circles are so called ``halo points'', these are used only for the
reference and their values are provided from the neighboring regions by
the MPI communication or memory copy.
%
If the west-most vertex of the region is the vertex of the original
icosahedron, called singular points, two blue points have the same
value.
%
As you can see in \autoref{f:data_store_regular}, all grid points can be
specified by two index $i$ and $j$, in the direction of southward and
northword, respectively.
%
For the computational efficiency, especially for vectorizing or using
SIMD, the $i$ and $j$ dimension are merged, so usual variables are
defined in a form shown in \autoref{t:data_array_regular}.
%
The first dimensions corresponds to the horizontal index, the second is
vertical index, and the third is region number (index) in each process.

The range of $g$ is one from \src{ADM_gall}, that is the number of
horizontal grid points including the halo points.
%
Note that \src{ADM_gall = ADM_gall_1d*ADM_gall_1d},
where \src{ADM_gall_1d} is the number of grid points in $i$ or $j$ direction.
%
\src{ADM_kall} is the actual number of vertical layers, and
\src{ADM_lall} is the number of regions managed by a single MPI process.
%
For example, if four regions are managed as \autoref{f:parallellization},
\src{ADM_lall} is set to 4.

For some calculation, the values at the triangle center and those at the
mid-points of arcs are required, called ``the triangle point'' and ``the
arc point'', respectively.
%
Corresponding to the one grid point, there are two triangle points and
three arc points.
%
To specify these points, one more dimension $m$ are used. Their value
are \src{ADM_TI}, \src{ADM_TJ} for the triangle point, and \src{ADM_AI},
\src{ADM_AIJ} and \src{ADM_AJ} for the arc point, respectively (see
\autoref{f:data_store_regular}).

\begin{figure}[htbp]
 \centering
\includegraphics[scale=.5]{figs/Tomita2-12-0.png}
\caption{Schematic figure of data storing (regular region).}%
\label{f:data_store_regular}
\end{figure}

\begin{table}[htbp]
\centering
\caption{Data array for the regular region.}%
\label{t:data_array_regular}
\begin{tabular}{llll}
\hline\hline
 \multicolumn{4}{l}{\src{var(g,k,l)} : Grid point variables}\\
\hline
 $g$ & $=$ & $1 \ldots $ \text{\src{ADM_gall}} & horizontal index \\
 $k$ & $=$ & $1 \ldots $ \text{\src{ADM_kall}} & vertical index \\
 $l$ & $=$ & $1 \ldots $ \text{\src{ADM_lall}} & region index \\
\hline
 \multicolumn{4}{l}{\src{var(g,k,l,m)} : Triangle point variables}\\
\hline
 $g$ & $=$ & $1 \ldots $ \text{\src{ADM_gall}} & horizontal index \\
 $k$ & $=$ & $1 \ldots $ \text{\src{ADM_kall}} & vertical index \\
 $l$ & $=$ & $1 \ldots $ \text{\src{ADM_lall}} & region index \\
 $m$ & $=$ & \src{ADM_TI, ADM_TJ} & index of triangle position \\
\hline
 \multicolumn{4}{l}{\src{var(g,k,l,m)} : Arc point variables}\\
\hline
 $g$ & $=$ & $1 \ldots $ \text{\src{ADM_gall}} & first horizontal index \\
 $k$ & $=$ & $1 \ldots $ \text{\src{ADM_kall}} & vertical index \\
 $l$ & $=$ & $1 \ldots $ \text{\src{ADM_lall}} & region index \\
 $m$ & $=$ & \src{ADM_AI, ADM_AIJ, ADM_AJ} & index of arc position \\
\hline\hline
\end{tabular}
\end{table}

\subsection{Data array for pole region}

For pole region, \autoref{f:data_store_pole} shows the schematic figure
of data storing.
%
Only one grid point, the pole point, is managed, and the other point
marked by the white circles are the halo points, these are used only for
the reference and their values are provided from the neighboring regions
by the MPI communication or memory copy.
%
The indices for these halo are in order of clockwise direction.
%
The first dimension is horizontal suffix, and the size \src{ADM_GALL_PL} is set to 6,
one for pole point and five for halo points.
%
The second dimension is vertical suffix, which is the same with the
regular region.
%
The third dimension is region, suffix, and the range is 1 to
\src{ADM_LALL_PL}, which is the number of pole regions, and set to 2
(North pole and South pole).

Different from the regular region, the number of triangle points and arc
points are the same with the halo points, these are no need for more
dimension, and stored as the same dimensions with the grid points.
But the range of index are from \src{ADM_GMIN_PL}(=2) to \src{ADM_GMAX_PL}(=6).

\begin{figure}[htbp]
 \centering
\includegraphics[scale=.5]{figs/Tomita2-12-1.png}
\caption{Schematic figure of data storing (pole region).}
\label{f:data_store_pole}
\end{figure}

\begin{table}[htbp]
\centering
\caption{Data array for the pole region.}
\begin{tabular}{llll}
\hline\hline
 \multicolumn{4}{l}{\src{var_pl(n,k,l)} : Grid, triangle, arc point variables}\\
\hline
 $n$ & $=$ & $1 \ldots $ \text{\src{ADM_GALL_PL}} & horizontal index \\
 $k$ & $=$ & $1 \ldots $ \text{\src{ADM_kall}} & vertical index \\
 $l$ & $=$ & $1 \ldots $ \text{\src{ADM_LALL_PL}} & region index \\
\hline
\end{tabular}
\end{table}

\subsection{Kernelize}

The kernels are single or multiple subroutines in original \NICAM source code,
and extracted and imposed into the wrapper for the kernel program.
%
Values of input variables in the argument list of the kernel subroutine
are stored as a data file just before the call in execution of the original \NICAM, and
they are read and given to the kernel subroutine in the kernel program.
%
Similarly values of output variables in the argument list are stored
just after the call in execution, and they are read and compared to the
actual output values of kernel subroutine, the difference are written to
the standard output for validation.

\NICAM uses several ``public object'' defined in several modules,
briefly described later.
%
Some of them are moved to \file{problem_size.inc} and \src{include}ed in
the \src{mod_misc}.

Kernel programs output several messages to the standard output, such as:
\begin{itemize}
%\setlength{\itemsep}{0pt}
 \item min/max/sum of input data,
 \item min/max/sum of output data,
 \item min/max/sum of difference between output and validation data,
 \item computational time (elapsed time).
\end{itemize}
%
Elapsed time is measured using \src{omp_get_wtime()}.

There are sample output file for the reference in \src{reference/} directory
of each kernel program, and also they are shown in``Input data and
result'' section of each kernel program in this document.

\subsection{Problem size}

In this kernel program package, problem size are set in
\file{problem_size.inc} in each kernel program, except
\src{communication}, as follows.
%
Number of grid point of one side of the region \src{ADM_gall_1d} is
$130$ including two halo points, and the total number of grid points in
whole region \src{ADM_gall} is $16900$, which corresponds to
$\text{glevel}-\text{rlevel}=7$.
%
Number of vertical layers \src{ADM_vlayer} is $40$ and the actual size
of $k$-direction \src{ADM_kall} is $42$.
%
The kernel program runs on a single process and this process manages
only one normal region, ie. \src{ADM_lall} is $1$, and also have two
pole regions, ie. \src{ADM_have_pl} is \src{.true.} and
\src{ADM_lall_pl} is $2$.
%
This normal region is to manage singular point, then
\src{ADM_have_sgp(1)} is \src{.true.}

\subsection{MPI and OpenMP}\label{s:mpi_openmpi}

While original \NICAM is parallelized by MPI and OpenMP,
all kernel program in this package except \src{communication}
are meant to be executed as one process and no threading.
%
And you don't need MPI library to compile/execute these kernel programs,
but you need to make OpneMP enable in order to use \src{omp_get_wtime()}.

\subsection{Mesuring environment}\label{s:measuring_env}

In the following sections, the example of performance result part of the
log output file of each kernel program is shown.
%
These were measured on the machine environment shown in
\autoref{t:machine_env},
with setting \src{export IAB_SYS=Ubuntu-gnu-ompi} on compilation
(See \file{QuickStart.md}).

\begin{table}[htbp]
\centering
\caption{Measuring environment}\label{t:machine_env}
\small
\begin{tabularx}{.8\textwidth}{llX}
\hline
component & specification & notes \\
\hline
 CPU & Xeon E5-2630v4 @2.2GHz (10cores) x2 & HT disabled, TB enabled\\
 Memory & 256GB &\\
 Storage & SSD (SATA) &\\
 OS & Ubuntu 16.04.4 LTS &\\
 Compiler & GNU 5.4.0 & \\
 MPI & OpenMPI 1.10.2 & Ubuntu standard \\
\hline
\end{tabularx}
\end{table}


\documentclass[letterpaper,9pt,twoside,printwatermark=false]{pinp}

%% Some pieces required from the pandoc template
\providecommand{\tightlist}{%
  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}

% Use the lineno option to display guide line numbers if required.
% Note that the use of elements such as single-column equations
% may affect the guide line number alignment.

\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}

% The geometry package layout settings need to be set here...
\geometry{layoutsize={0.95588\paperwidth,0.98864\paperheight},%
          layouthoffset=0.02206\paperwidth,%
		  layoutvoffset=0.00568\paperheight}

\definecolor{pinpblue}{HTML}{185FAF}  % imagecolorpicker on blue for new R logo
\definecolor{pnasbluetext}{RGB}{101,0,0} %

\title{DALITE Q7 - Two Sample Inference. Solutions.}

\author[a]{EPIB607 - Inferential Statistics}

  \affil[a]{Fall 2018, McGill University}

\setcounter{secnumdepth}{5}

% Please give the surname of the lead author for the running footer
\leadauthor{Bhatnagar and Hanley}

% Keywords are not mandatory, but authors are strongly encouraged to provide them. If provided, please include two to five keywords, separated by the pipe symbol, e.g:
 \keywords{  Two sample means |  Two sample proportions  }

\begin{abstract}
This DALITE quiz will cover two sample inference. This builds on the one
sample inference we have seen so far.
\end{abstract}

\dates{This version was compiled on \today}
\doi{\url{https://sahirbhatnagar.com/EPIB607/}}

\pinpfootercontents{DALITE Q7 due November 7, 2018 by 5pm}

\begin{document}

% Optional adjustment to line up main text (after abstract) of first page with line numbers, when using both lineno and twocolumn options.
% You should only change this length when you've finalised the article contents.
\verticaladjustment{-2pt}

\maketitle
\thispagestyle{firststyle}
\ifthenelse{\boolean{shortarticle}}{\ifthenelse{\boolean{singlecolumn}}{\abscontentformatted}{\abscontent}}{}

% If your first paragraph (i.e. with the \dropcap) contains a list environment (quote, quotation, theorem, definition, enumerate, itemize...), the line after the list may have some extra indentation. If this is the case, add \parshape=0 to the end of the list environment.

\section{A researcher who wished to test the difference of two
(independent) y-bars with reported SEMs, SE0 and SE1 , did so by
computing which test
statistic?}\label{a-researcher-who-wished-to-test-the-difference-of-two-independent-y-bars-with-reported-sems-se0-and-se1-did-so-by-computing-which-test-statistic}

\begin{enumerate}
\def\labelenumi{\alph{enumi}.}
\tightlist
\item
  (ybar1 - ybar0) / (SE1 + SE0)
\item
  (ybar1 - ybar0) / (SE1 - SE0)
\item
  \textbf{(ybar1 - ybar0) / sqrt( (SE1)\^{}2 + (SE0)\^{}2 ) (Correct)}
\item
  (ybar1 - ybar0) / sqrt( (SE1)\^{}2 - (SE0)\^{}2 )
\end{enumerate}

\subsection{Correct rationales}\label{correct-rationales}

\begin{itemize}
\tightlist
\item
  Two-sample t-test statistic - A isn't right because we aren't taking
  the squares of the sum of the SEs and then taking the sqrt in the
  denominator - B isn't right because it is taking the difference in the
  denominator - D isn't right because it is taking the difference in the
  denominator
\end{itemize}

\subsection{Incorrect rationales}\label{incorrect-rationales}

\begin{itemize}
\tightlist
\item
  We compute the two-sample t-statistic which is given by t = (ybar1 -
  ybar0) / SE, and SE of the difference in the sampling means =
  sqrt(s1\^{}2/n1 + s2\^{}2 / n2), which can be simplified to
  (sqrt(s1\^{}2) / sqrt (n1)) + (sqrt(s2\^{}2) / sqrt(n2 )) =
  (s1/sqrt(n1)) + (s2/sqrt(n2)) = SE1 + SE0
\item
  Since the SEMs are given, they are simply added to obtain the
  denominator of the t statistic formula.
\item
  sqrt(s1\^{}2/n1 + s2\^{}2/n2)= s1/sqrt(n1) + s2/sqrt(n2) = SE1 +SE2
\item
  Because SE= sigma / sqrtn
\item
  This is the formula for two-sample inference.
\end{itemize}

\section{Which distribution is closer to Normal
?}\label{which-distribution-is-closer-to-normal}

\begin{enumerate}
\def\labelenumi{\alph{enumi}.}
\tightlist
\item
  Body weights of (unrelated) male air passengers
\item
  Body weights of (unrelated) female air passengers
\item
  \textbf{Sum of weights of a (random male, random female) pair
  (Correct)}
\item
  \textbf{Difference of weights of a (random male, random female) pair
  (Correct)}
\end{enumerate}

\subsection{Correct rationales}\label{correct-rationales-1}

\begin{itemize}
\tightlist
\item
  when two random variables are normally distributed, the new variable
  ``difference in sample means'' also follows a normal distribution,
  centered on the difference in two variables' means and with variance
  equal to the sum of the two variables variances. The same applies for
  the sum but centered on the sum of the means. C and D are correct.
\item
  When 2 random variables are Normally distributed, the new variable
  ``difference in sample means'' is also Normally distributed and is
  centered on the difference in 2 variables' means
\end{itemize}

\subsection{Incorrect rationales}\label{incorrect-rationales-1}

\begin{itemize}
\tightlist
\item
  difference has less variance, so more normal
\item
  males show more variation
\item
  We can reasonable assume that unrelated air passengers are a SRS and
  body weight follows a normal distribution.
\item
  Adding weights would increase n, which could make the distribution
  more normal
\end{itemize}

\section{\texorpdfstring{Refer to the Table on ``Postoperative Effect on
Plasma Ascorbic Acid for 105 Cases; Readings on the Same Individuals''.
You would get contradictory answers if you tested the differences in the
means using i. the SE's in columns 1 and 2, and ii. the SE in column 3.
TRUE or FALSE? Explain why in your rationale and say which one is
correct.}{Refer to the Table on Postoperative Effect on Plasma Ascorbic Acid for 105 Cases; Readings on the Same Individuals. You would get contradictory answers if you tested the differences in the means using i. the SE's in columns 1 and 2, and ii. the SE in column 3. TRUE or FALSE? Explain why in your rationale and say which one is correct.}}\label{refer-to-the-table-on-postoperative-effect-on-plasma-ascorbic-acid-for-105-cases-readings-on-the-same-individuals.-you-would-get-contradictory-answers-if-you-tested-the-differences-in-the-means-using-i.-the-ses-in-columns-1-and-2-and-ii.-the-se-in-column-3.-true-or-false-explain-why-in-your-rationale-and-say-which-one-is-correct.}

\begin{figure}
\centering
\includegraphics[scale=0.5]{tab3.jpg}
\end{figure}

\begin{enumerate}
\def\labelenumi{\alph{enumi}.}
\tightlist
\item
  \textbf{TRUE (Correct)}
\item
  FALSE
\end{enumerate}

\subsection{Correct rationales}\label{correct-rationales-2}

\begin{itemize}
\tightlist
\item
  The SE in column 3 is the SE for a new variable which is the di
  fference between pre and post and it is different than the SE in
  columns 1 and 2 which correspond to the Se for each individual group.
\item
  You would get contradictory answers since the proper way to calculate
  the standard error for a two-sample t-test is to take the square root
  of the sum of the standard errors of each column. Therefore, the
  correct way is to use the SE's in columns 1 and 2
\end{itemize}

\subsection{Incorrect rationales}\label{incorrect-rationales-2}

\begin{itemize}
\tightlist
\item
  For two-sample test: SE = sqrt (SE1\^{}2 + SE2\^{}2) SE in column3
  comes from SE in columns 1 and 2
\item
  The SE in column 3 is the SE of the sampling distribution of the mean
  difference and 1 and 2 are SE of the respective mean. When computing
  the mean difference, SE calculation accounts for both SEs in 1 and 2.
\end{itemize}

\section{\texorpdfstring{How many calories does a fruit juice popsicle
labeled ``no sugar added'' pack? A random sample of 10 popsicles of a
particular brand is selected, and the calories per serving are measured.
To get a confidence interval for the mean calories per serving of all
no-sugar-added popsicles from this brand, you would
use}{How many calories does a fruit juice popsicle labeled no sugar added pack? A random sample of 10 popsicles of a particular brand is selected, and the calories per serving are measured. To get a confidence interval for the mean calories per serving of all no-sugar-added popsicles from this brand, you would use}}\label{how-many-calories-does-a-fruit-juice-popsicle-labeled-no-sugar-added-pack-a-random-sample-of-10-popsicles-of-a-particular-brand-is-selected-and-the-calories-per-serving-are-measured.-to-get-a-confidence-interval-for-the-mean-calories-per-serving-of-all-no-sugar-added-popsicles-from-this-brand-you-would-use}

\begin{enumerate}
\def\labelenumi{\alph{enumi}.}
\tightlist
\item
  \textbf{the one-sample t interval (Correct)}
\item
  the matched pairs t interval
\item
  the two sample t interval
\item
  the one sample z interval
\end{enumerate}

\subsection{Correct rationales}\label{correct-rationales-3}

\begin{itemize}
\tightlist
\item
  I would use the one-sample t interval because we are only comparing
  one mean and the population standard deviation is unknown.
\end{itemize}

\subsection{Incorrect rationales}\label{incorrect-rationales-3}

\begin{itemize}
\tightlist
\item
  Since we are only inferring about one sample you will do a one sample
  z interval
\end{itemize}

\section{A study is designed to compare the amount of vitamin C (in
milligrams per serving) in oranges that reach the stores either 1 day
after being picked or 3 days after being picked. A random sample of 15
oranges is taken for each group. To test whether there is a difference
in the mean vitamin C amount of all oranges reaching stores either 1 day
or 3 days after being picked, you would
use}\label{a-study-is-designed-to-compare-the-amount-of-vitamin-c-in-milligrams-per-serving-in-oranges-that-reach-the-stores-either-1-day-after-being-picked-or-3-days-after-being-picked.-a-random-sample-of-15-oranges-is-taken-for-each-group.-to-test-whether-there-is-a-difference-in-the-mean-vitamin-c-amount-of-all-oranges-reaching-stores-either-1-day-or-3-days-after-being-picked-you-would-use}

\begin{enumerate}
\def\labelenumi{\alph{enumi}.}
\tightlist
\item
  the one-sample t test
\item
  the one-sample z test
\item
  the one-sample t interval
\item
  the matched pairs t test
\item
  \textbf{the two-sample t test (Correct)}
\end{enumerate}

\subsection{Correct rationales}\label{correct-rationales-4}

\begin{itemize}
\tightlist
\item
  It is a two-sample t test because we are comparing means of two
  different samples. It is not the matched pairs t-test because the two
  samples are not paired, the oranges reaching the stores one day after
  picking do not have an impact on the oranges reaching the stores three
  days after picking, they are independent of each other.
\item
  There are two samples and they are not matched, because the samples
  are not from the same oranges.
\item
  You have two samples, so only D or E should be considered. The way the
  question is worded, we have a random sample for EACH of the groups and
  so it's not a matched test. We measure oranges that get to the store 1
  day after picking and then measure a different group of oranges that
  arrive 3 days after picking.
\end{itemize}

\subsection{Incorrect rationales}\label{incorrect-rationales-4}

\begin{itemize}
\tightlist
\item
  This is a before-after test and so the two samples are not independent
  of each other.
\item
  The matched pairs t test is concerned with the difference between two
  measures in one population. In this case, we wish to compare the mean
  vitamin C amount in the same population (of oranges) at two time
  points post-harvesting: 1 day or 3 days. We are using the t-test
  because the sample size is small (n\textless{}30). Thus we use the
  matched pairs t-test.
\end{itemize}

\section{There are two common methods for measuring the concentration of
a pollutant in fish tissue. Do the results of the two methods differ on
the average? You apply both methods to one sample of 18 carp and
use}\label{there-are-two-common-methods-for-measuring-the-concentration-of-a-pollutant-in-fish-tissue.-do-the-results-of-the-two-methods-differ-on-the-average-you-apply-both-methods-to-one-sample-of-18-carp-and-use}

\begin{enumerate}
\def\labelenumi{\alph{enumi}.}
\tightlist
\item
  \textbf{the one-sample t test (Correct)}
\item
  the one-sample z test
\item
  \textbf{the matched pairs t test (Correct)}
\item
  the two-sample t test
\end{enumerate}

\subsection{Correct rationales}\label{correct-rationales-5}

\begin{itemize}
\tightlist
\item
  A can be correct since can do a t-test on the difference
\item
  This is a matched pairs t test because you are applying the two
  difference methods to the sample sample of fish. Therefore the samples
  are not independent of each other and are paired.
\end{itemize}

\subsection{Incorrect rationales}\label{incorrect-rationales-5}

%\showmatmethods

\bibliography{pinp}
\bibliographystyle{jss}

\end{document}


\documentclass[12pt]{article}

\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{epsfig}

\title{BISICLES Input parameters}

\author{Dan Martin and Stephen Cornford}

%\date{November 14, 2006}

\begin{document}

\maketitle

This is an attempt to catalog the various input parameters which can
be used to control the various forms of the BISICLES code (which can
be run either as a standalone ice sheet code, or as an alternate
dycore coupled with CISM). Input parameters are generally passed in
from inputs files through the Chombo ParmParse utility. In general,
input parameters in inputs files will be of the form {\it
  group.variable}, where {\it group} is the subgroup to which the
variable belongs. This is used to improve the organization of the
inputs.

\section{Driver inputs}
These inputs are read by the driver (for example {\tt
  exec2D/driver.cpp} and are used to set up the various classes used
in a BISICLES run.

\begin{itemize}

\item{ {\tt main} group}
\begin{itemize}
  \item{ { \tt domain\_size} }
    \item{ { \tt constitutiveRelation } }
    \item{ { \tt rateFactor} }
        \item{ { \tt surface\_flux\_type} }
        \item{ { \tt basal\_flux\_type} }
    \item{ { \tt basalFrictionRelation} }
    \item{ { \tt maxTime} }
    \item{ { \tt maxStep} }
\end{itemize}

\item{ { \tt  constMu } group  }
  \begin{itemize}
    \item { { \tt mu } }
  \end{itemize}
\item{ { \tt  l1l2 } group  }
  \begin{itemize}
    \item { { \tt solverTolerance } }
  \end{itemize}
\item{ { \tt  constRate } group  }
  \begin{itemize}
    \item { \tt A }
    \item { \tt epsSqr0 }
  \end{itemize}

\item{ { \tt  ArrheniusRate } group  }
  \begin{itemize}
    \item { \tt epsSqr0 }
  \end{itemize}

\item{ { \tt  constFlux } group  }
  \begin{itemize}
    \item { \tt fluxValue }
  \end{itemize}
\item{ { \tt  basalConstFlux } group  }
  \begin{itemize}
    \item { \tt fluxValue }
  \end{itemize}

\item{ { \tt  basalMaskedFlux } group  }
\begin{itemize}
  \item { {\tt grounded\_flux\_type } }
  \item { {\tt floating\_flux\_type} }
\end{itemize}

\item{ { \tt  groundedBasalConstFlux } group  }
  \begin{itemize}
    \item { \tt fluxValue }
  \end{itemize}

\item{ { \tt  floatingBasalConstFlux } group  }
  \begin{itemize}
    \item { \tt fluxValue }
  \end{itemize}

\item{ { \tt  floatingBasalPWLFlux } group }
  \begin{itemize}
    \item{\tt n}
    \item {\tt abscissae}
    \item {\tt ordinates}
  \end{itemize}

\item{ { \tt  muCoefficient } group  }
  \begin{itemize}
    \item {\tt type}
  \end{itemize}

\item{ { \tt  inputLevelData } group  }
  \begin{itemize}
    \item  {\tt muCoefFile}
    \item {\tt muCoefName }

    \item {\tt frictionFile}
    \item {\tt frictionName}

    \item {\tt geometryFile }
    \item {\tt thicknessName }
    \item {\tt topographyName }

    \item {\tt temperatureFile }
    \item {\tt temperatureName}

  \end{itemize}

\item{ { \tt  geometry } group  }
\begin{itemize}
   \item {\tt beta\_type }
   \item {\tt betaValue }
   \item {\tt betaValue }

   \item {\tt omega }  ( omegaVect, 0, SpaceDim)
   \item {\tt betaEps }
   \item {\tt betaValue }
   \item {\tt omega}
   \item {\tt betaEps}
   \item {\tt betaValue}

   \item {\tt magOffset }
   \item {\tt betaEps }
   \item {\tt gaussianBump\_nt}
   \item {\tt gaussianBump\_t}
   \item {\tt gaussianBump\_C}
   \item {\tt gaussianBump\_a}
   \item {\tt gaussianBump\_xb}
   \item {\tt gaussianBump\_xc}
   \item {\tt gaussianBump\_yb}
   \item {\tt gaussianBump\_yc}
   \item {\tt problem\_type}
\end{itemize}

\item{ { \tt  BasalFrictionPowerLaw } group  }
\begin{itemize}
  \item{\tt m}
  \item{\tt includeEffectivePressure}
\end{itemize}

\item{ { \tt  vieliPayne } group  }
  \begin{itemize}
    \item {\tt thickness }
    \item {\tt seaLevel }
    \item {\tt basal\_slope}
    \item {\tt originElevation}
  \end{itemize}

\item{ { \tt  marineIceSheet } group  }
  \begin{itemize}
    \item {\tt seaLevel}
    \item {\tt thickness\_type }
    \item {\tt thickness }
    \item {\tt thickness\_flowline\_dx}
    \item {\tt thickness\_flowline\_file }
    \item {\tt thickness\_flowline\_set }
    \item {\tt geometry }
    \item {\tt basal\_slope}
    \item {\tt originElevation}
    \item {\tt originElevation}
    \item {\tt schoofLengthScaleFactor}
    \item {\tt schoofCoeff2}
    \item {\tt schoofCoeff4}
    \item {\tt schoofCoeff6}
    \item {\tt originElevation}
    \item {\tt schoofLengthScaleFactor}
    \item {\tt katzAlpha}
    \item {\tt katzSigma}
    \item {\tt schoofCoeff2}
    \item {\tt schoofCoeff4}
    \item {\tt schoofCoeff6}
  \end{itemize}

\item{ { \tt  hump } group  }
  \begin{itemize}
  \item {\tt radSqr }
  \item {\tt maxThickness }
  \item {\tt baseElevation }
  \item {\tt minThickness }

  \item {\tt center }
  \item {\tt widthScale }
\end{itemize}

\item{ { \tt  temperature } group  }
\begin{itemize}
  \item {type}
  \item {value}
\end{itemize}

\item{ { \tt  amr } group  }
  \begin{itemize}
    \item {\tt num\_cells}
  \end{itemize}

\end{itemize}

\section{ \tt AmrIce inputs}
  These inputs are read by the {\tt AmrIce} class (\verb|BISICLES/code/src/AmrIce.cpp| ).

\begin{itemize}
\item { \tt constants } group
Physical onstants which are settable from inputs file
\begin{itemize}
  \item {\tt ice\_density }
  \item {\tt sea\_water\_density }
  \item {\tt gravity }
\end{itemize}

 \item { \tt amr } group
\begin{itemize}
  \item {\tt maxLevel}
  \item {\tt tagCap}
  \item {\tt num\_cells}
  \item {\tt domain\_size }
  \item {\tt is\_periodic }
  \item {\tt cfl }
  \item {\tt initial\_cfl }
  \item {\tt max\_dt\_grow\_factor }
  \item {\tt time\_step\_ticks }
  \item {\tt fixed\_dt }
  \item {\tt offsetTime }
  \item {\tt isothermal }
  \item {\tt isothermalTemperature }
  \item {\tt plot\_interval }
  \item {\tt plot\_time\_interval }
  \item {\tt plot\_prefix }
  \item {\tt write\_map\_file }
  \item {\tt write\_preSolve\_plotfiles }
  \item {\tt write\_flux\_velocities }
  \item {\tt write\_viscous\_tensor }
  \item {\tt write\_base\_velocities }
  \item {\tt write\_temperature }
  \item {\tt write\_thickness\_sources }
  \item {\tt write\_layer\_velocities }
  \item {\tt evolve\_thickness }
  \item {\tt grounded\_ice\_stable }
  \item {\tt floating\_ice\_stable }
  \item {\tt check\_interval }
  \item {\tt check\_prefix }
  \item {\tt check\_overwrite }
  \item {\tt check\_exit }
  \item {\tt write\_dHDt }
  \item {\tt write\_solver\_rhs }
      \item {\tt ref\_ratio }
  \item {\tt verbosity }
  \item {\tt regrid\_interval }
  \item {\tt interpolate\_zb }
  \item {\tt blockFactor }
%  // \item {\tt n\_tag\_subset\_boxes }
%  //     \item {\tt tag\_subset\_boxes }
  \item {\tt fill\_ratio }
  \item {\tt nestingRadius }
  \item {\tt tag\_on\_grad\_velocity }
  \item {\tt tagging\_val }
  \item {\tt tag\_on\_laplacian\_velocity }
  \item {\tt tag\_on\_grounded\_laplacian\_velocity }
      \item {\tt lap\_vel\_tagging\_val }
      \item {\tt lap\_vel\_tagging\_max\_basal\_friction\_coef }
  \item {\tt tag\_on\_strain\_rate\_invariant }
      \item {\tt strain\_rate\_invariant\_tagging\_val }
  \item {\tt tag\_on\_velocity\_rhs }
      \item {\tt velocity\_rhs\_tagging\_val }
  \item {\tt tag\_grounding\_line }
      \item {\tt grounding\_line\_tagging\_min\_vel }
      \item {\tt grounding\_line\_tagging\_max\_basal\_friction\_coef }
  \item {\tt tag\_ice\_margin }
  \item {\tt tag\_all\_ice }
  \item {\tt tag\_on\_div\_H\_grad\_vel }
      \item {\tt div\_H\_grad\_vel\_tagging\_val }
  \item {\tt tags\_grow }
  \item {\tt max\_box\_size }
  \item {\tt max\_base\_grid\_size }
  \item {\tt report\_sum\_grounded\_ice }
  \item {\tt temporal\_accuracy }
  \item {\tt velocity\_solver\_type }
  \item {\tt max\_solver\_iterations }
  \item {\tt velocity\_solver\_tolerance }
  \item {\tt limit\_velocity\_rhs }
  \item {\tt limit\_rhs\_radius }
  \item {\tt limit\_flux\_speed }
  \item {\tt do\_initial\_velocity\_solve }
  \item {\tt do\_initial\_velocity\_guess }
  \item {\tt initial\_velocity\_guess\_type }
  \item {\tt initial\_velocity\_guess\_const\_mu }
  \item {\tt initial\_velocity\_guess\_solver\_type }
  \item {\tt initial\_velocity\_guess\_const\_vel }
  \item {\tt additional\_velocity }
  \item {\tt diffusion\_treatment }
  \item {\tt additional\_diffusivity }
  \item {\tt finest\_timestep\_level }
  \item {\tt basal\_length\_scale }
  \item {\tt basal\_friction\_decay }
  \item {\tt wallDrag }
  \item {\tt wallDragExtra }
  \item {\tt grounding\_line\_regularization }
  \item {\tt grounding\_line\_correction }
  \item {\tt calving\_model\_type }
  \item {\tt sigma }
  \item {\tt tagSubsetBoxesFile }
  \item {\tt gridsFile }
  \item {\tt restart\_file }

  \item {\tt initial\_velocity\_function\_type }
  \item {\tt initial\_velocity\_function\_flowline\_dx }
  \item {\tt initial\_velocity\_function\_flowline\_file }
  \item {\tt initial\_velocity\_function\_flowline\_set }
\end{itemize}

\item { \tt DeglaciationCalvingModelA } group
\begin{itemize}
  \item {\tt min\_thickness }
  \item {\tt calving\_thickness }
  \item {\tt calving\_depth }
  \item {\tt start\_time }
  \item {\tt end\_time }
\end{itemize}

\item { \tt DomainEdgeCalvingModel } group
\begin{itemize}
  \item {\tt front\_lo }
  \item { \tt front\_hi }
  \item {\tt preserveSea }
  \item {\tt preserveLand }
\end{itemize}

\item { \tt geometry } group
\begin{itemize}
\item  {\tt basalSlope }
\end{itemize}

\end{itemize}

\section {\tt BasicThicknessIBC} inputs
\begin{itemize}
  \item {\tt geometry } group
  \begin{itemize}
    \item {\tt basal\_type }
    \item {\tt thickness\_type }
    \item {\tt thickness\_scale }
    \item {\tt basalSlope }
  \end{itemize}

  \item {\tt bc} group
     \begin{itemize}
       \item {\tt lo\_bc }
       \item {\tt hi\_bc }
     \end{itemize}
\end{itemize}

\section {\tt CalvingModel}
\begin{itemize}
  \item {\tt a\_prefix } group
     \begin{itemize}
       \item {\tt type }
       \item {\tt front\_lo}
       \item {\tt front\_hi }
       \item {\tt preserveSea }
       \item {\tt preserveLand }
       \item {\tt min\_thickness }
       \item {\tt calving\_thickness }
       \item {\tt calving\_depth }
       \item {\tt start\_time }
       \item {\tt end\_time }
       \item {\tt proximity }
       \item {\tt velocity }
       \item {\tt startTime }
       \item {\tt endTime }
     \end{itemize}

\end{itemize}

\section {\tt FortranInterfaceIBC }
\begin{itemize}
  \item {\tt geometry } group
    \begin{itemize}
      \item {\tt thickness\_scale }
      \item {\tt basalSlope }
      \item {\tt extrap\_boundary}
    \end{itemize}

\item {\tt bc } group
  \begin{itemize}
     \item {\tt lo\_bc }
     \item {\tt hi\_bc }
  \end{itemize}

\end{itemize}

%\section{ \tt HumpIBC.cpp }

\section{JFNKSolver.cpp}
\begin{itemize}
\item {\tt JFNKSolver} group
\begin{itemize}
  \item {\tt maxIter }
  \item {\tt absTol }
  \item {\tt relTol }
  \item {\tt normType }
  \item {\tt verbosity}
  \item {\tt vtopSafety}
  \item {\tt vtopRelaxTol}
  \item {\tt vtopRelaxMinIter}
  \item {\tt numMGSmooth}
  \item {\tt numMGIter}
  \item {\tt h}
  \item {\tt hAdaptive}
  \item {\tt err}
  \item {\tt umin}
  \item {\tt switchRate}
  \item {\tt minPicardIterations}
  \item {\tt muMax}
  \item {\tt muMin}
  \item {\tt uMaxAbs}
  \item {\tt writeResiduals}

  \item {\tt solverType}
  \item {\tt BiCGStabRelTol}
  \item {\tt maxBiCGStabIter}
  \item {\tt RelaxTol}
  \item {\tt RelaxRelTol}
  \item {\tt maxRelaxIter}
  \item {\tt RelaxHang}
  \item {\tt CGRelTol}
  \item {\tt maxCGIter}
  \item {\tt RelaxTol}
  \item {\tt RelaxRelTol}
  \item {\tt maxRelaxIter}
  \item {\tt RelaxHang}
  \item {\tt bottom\_solver\_type}
  \item {\tt mg\_solver\_depth}
  \item {\tt mgCoefficientAverageType}
  \item {\tt mgProlongType}
\end{itemize}

\end{itemize}

\section {\tt KnownVelocitySolver.cpp}
\begin{itemize}
\item {\tt KnownVelocitySolver } group
  \begin{itemize}
    \item {\tt function\_type}
    \item {\tt flowline\_dx}
    \item {\tt flowline\_file }
    \item {\tt flowline\_set}
  \end{itemize}
\end{itemize}

\section{ \tt PetscIceSolver.cpp}
\begin{itemize}
\item {\tt petscSolver } group
\end{itemize}

\section{\tt PicardSolver.cpp }
\begin{itemize}
  \item {\tt  picardSolver} group
    \begin{itemize}
      \item {\tt writeResidualPlots }
      \item {\tt absoluteTolerance }
      \item {\tt max\_picard\_iterations }
      \item {\tt vtopSafety }
      \item {\tt linearSolver }
      \item {\tt mgBottomSolver }
      \item {\tt linearsolver\_tolerance }
      \item {\tt maxMGdepth }
      \item {\tt numMGSmooth }
    \end{itemize}

\end{itemize}

\section{The {\tt SurfaceFlux} class}
These are a bit different -- a prefix name is passed in to the
\begin{itemize}
\item { \tt a\_prefix} group
  \begin{itemize}
  \item {\tt type } Types may have additional inputs, also with the {\tt prefix} prefix. Types can be:
    \begin{itemize}
      \item {\tt zeroFlux}  (no additional inputs)
      \item {\tt constantFlux}
        \begin{itemize}
          \item {\tt flux\_value}
        \end{itemize}
      \item {\tt LevelData }
        \begin{itemize}
          \item {\tt fileFormat }
          \item {\tt n }
          \item {\tt offset }
          \item {\tt startTime }
          \item {\tt timeStep }
          \item {\tt name }
        \end{itemize}

        \item {\tt piecewiseLinearFlux}
          \begin{itemize}
            \item {\tt n }
            \item {\tt abscissae }
            \item {\tt ordinates }
          \end{itemize}

        \item {\tt maskedFlux }
          The {\tt maskedFlux } type recursively calls the {\tt parseSurfaceFlux} function, adding {\tt .grounded}, {\tt .floating}, {\tt .openLand}, {\tt .openSea} to classify the flux types for regions with grounded ice, floating ice, open land, and open sea, respectively.

        \item {\tt boxBoundedFlux }

        \item {\tt axbyFlux }

        \item {\tt compositeFlux }

        \item {\tt groundingLineLocalizedFlux }

        \item {\tt pythonFlux }
    \end{itemize}

  \end{itemize}
\item {\tt prefix.c\_str()} group (``pe'')
\end{itemize}

\end{document}


    \filetitle{fanchart}{Add fanchart to graph}{report/fanchart}

	\paragraph{Syntax}\label{syntax}

\begin{verbatim}
P.fanchart(Cap,X,Std,Prob,...)
\end{verbatim}

\paragraph{Input arguments}\label{input-arguments}

\begin{itemize}
\item
  \texttt{P} {[} struct {]} - Report object created by the
  \href{report/new}{\texttt{report.new}} function.
\item
  \texttt{Cap} {[} char {]} - Caption used as a legend entry for the
  line (mean of fanchart)
\item
  \texttt{X} {[} tseries {]} - Tseries object with input data to be
  displayed.
\item
  \texttt{Std} {[} tseries {]} - Tseries object with standard deviations
  of input data.
\item
  \texttt{Prob} {[} numeric {]} - Confidence porbabilities of intervals
  to be displayed.
\end{itemize}

\paragraph{Options for fancharts}\label{options-for-fancharts}

\begin{itemize}
\item
  \texttt{'asym='} {[} numeric \textbar{} tseries \textbar{}
  \emph{\texttt{1}} {]} - Ratio of asymmetry (area of upper part to one
  of lower part).
\item
  \texttt{'exclude='} {[} numeric \textbar{} true \textbar{}
  \emph{\texttt{false}} {]} - Exclude some of the confidence intervals.
\item
  \texttt{'factor='} {[} numeric \textbar{} \emph{\texttt{1}} {]} -
  factor to increase or decrease input standard deviations
\item
  \texttt{'fanLegend='} {[} cell \textbar{} \texttt{NaN} \textbar{}
  \emph{\texttt{Inf}} {]} - Legend entries used instead of confidence
  interval values; Inf means all confidence intervals values will be
  used to construct legend entries; NaN means the intervals will be
  exluded from legend; \texttt{NaN} in cellstr means the intervals of
  respective fancharts will be exluded from legend.
\end{itemize}

See help on \href{report/series}{\texttt{report/series}} for other
options available.

\paragraph{Description}\label{description}

The confidence intervals are based on normal distributions with standard
deviations supplied by the user. Optionally, the user can also specify
assumptions about asymmetry and/or common correction factors.

\paragraph{Example}\label{example}


\documentclass{article}
\usepackage[margin=1.25in]{geometry}
\usepackage{amsmath}
\usepackage{physics}
\usepackage{bm}

\usepackage{graphicx}
\begin{document}

\centerline{\sc \large Analytic derivatives of the trajectory with respect to forcefield parameters.}
\vspace{.5pc}
\centerline{An exact solution for fitting parameters to ensemble observables.}
\vspace{.5pc}
\centerline{Yutong Zhao (proteneer@gmail.com), unaffiliated}
\vspace{2pc}

\section{Introduction}

When we run molecular dynamics to generate conformations along a trajectory, we almost always generate observables derived from the ensemble. Example observables span from simple quantities such as pseudo-electron density in XRD/ED refinement, density, radii of gyration, Helmholtz free energies, distance information arising from NMR, etc. Nearly always, the experimentally measured observable and the predicted observable don't agree with each other. This results in the painstaking effort of identifying new forcefield functional forms and/or fitting their parameters. Note that this paper is not concerned with the former (discovery of functional forms), but rather, on how to fit the parameters used by these functional forms to condensed phase properties that arise from a simulation (which often span from simple fixed-charged models, all the way to more complicated polarizable forcefields).

In stark contrast to training techniques of modern machine learning, forcefield parameter fitting in MD has been sort of a black-art. At a high level, the parameter tuning procedure is typically separated into two parts: 1) fitting to gas phase QM energies across a varying level of theories either by energy or force-matching, which initializes parameters into a sane region of parameter space, 2) followed by a difficult procedure of fitting to condensed phase properties in a variety of solvent and/or crystallographic conditions. Typically, the second step requires repeated simulations to generate predicted observables from the ensemble. However, there lacks an analytic derivative of the observables to parameters partially owing to complexity of generating necessary derivatives.

Fortunately, with the advent of sophisticated auto differentiation systems in modern machine learning frameworks, it has become not only possible, but also practical to generate these derivatives. We introduce a new molecular dynamics tool with two primary aims:

First, the ability to quickly test new functional forms, as well as its derivatives. Ideally, the user should only need to specify the functional form of the energy function, and all subsequent higher order derivatives should be automatically generated. As an example, OpenMM uses symbolic differentiation (lepton) that's then JIT compiled into the respective kernels. However, symbolic differentiation has severe drawbacks in that it scales poorly with increased complexity of functional forms. In contrast, forward/reverse-mode autograd systems uses dual-algebra, which tends to scale better with complexity as well as naturally lending itself to higher order derivatives. This should enable us to rapidly prototype novel functional forms, ranging from polarizable models to neural-network potentials.

Second, the ability to analytically fit these parameters to observables derived from a simulation trajectory. We show that one can, without too much difficulty, implement analytic derivatives through Langevin dynamics provided one has access to analytic hessians and second-order mixed partial derivatives of the energy function. This allows for optimization of not only the location of the minimas, but also the curvature along the path to reach said minimias. This approach is in contrast to other approaches such as thermodynamic gradients (assuming the ergodic limit has been reached), which uses only the first order derivative of the energy with respect to the parameters. In practice, the implementation is realized in two parts through the chain rule, the first being the derivative of the observable with respect to each conformation in the ensemble, the second being the derivative of a conformation in the trajectory with respect to the forcefield parameters.

\section{Mathematical Formalism}

Define the loss function $L(O(\bm{X}_{label}), O(\bm{X}_{md}))$, where $O$ is a function that calculates some observable from an ensemble. $\bm{X}_{md}(\bm{x}_0; \theta)$ is a set of conformations derived from a molecular dynamics simulation, starting from some initial state $\bm{x}_0$ with some set of forcefield parameters $\theta$. We can also write $\bm{X}_{md}$ as a collection of individual states $\bm{x}_t$ at various times $t$. The goal is to analytically derive $\dfrac{\partial L}{\partial \theta}$ so we can train $\theta$ to some experimental observable $O(\bm{X}_{label})$ by using a standard MSE loss:

\begin{equation}
L(O(\bm{x}_{label}), O(\bm{x}_t)) = \lbrack O(\bm{x}_{label}) - O(\bm{X}(\bm{x}_0;\theta)) \rbrack ^2
\end{equation}
Training the parameters means we need the gradient of $L$ with respect to the parameters $\theta$, which we compute using the chain rule:
\begin{equation}
\dfrac {\partial L}{\partial \theta} = \dfrac{\partial L}{\partial \bm{X}_{md}} \dfrac{\partial \bm{X}_{md}}{\partial \theta}
\end{equation}
In an unbiased sample of conformations, this is equal to a sum of the derivatives of individual states from the trajectory:
\begin{equation}
\dfrac {\partial L}{\partial \theta} = \sum_{t}{\dfrac{\partial L}{\partial \bm{x}_t} \dfrac{\partial \bm{x}_t}{\partial \theta}}
\end{equation}
Each summand is a component-wise matrix-multiply, where both $\partial L / \partial \bm{x}_t$ and ${\partial \bm{x}_t}/{\partial \theta}$ are $(N, 3)$ matrices. The LHS is the derivative of the loss w.r.t. to a conformation, and the RHS is the derivative of a conformation w.r.t. to the model parameters. The LHS is trivial to compute, so the RHS is the main quantity of interest.

If we were to run Langevin dynamics, the velocity is $\bm{v}_t$ is updated according to:
\begin{equation}
\bm{v}_t = a \bm{v}_{t-1} - b \grad  E(\bm{x}_{t-1};\theta) + c \bm{n}_{t-1}
\end{equation}
Where $\grad_x $ is the gradient operator (w.r.t. coordinates), and $a$, $b$, $c$ are the coefficents derived from the temperature and the friction, and $\bm{n}$ is noise sampled from an independent gaussian.
\begin{equation}
\bm{x}_{t} = \bm{x}_{t-1} + \bm{v}_{t} \tau
\end{equation}
Expanding out the first few terms we get:
\begin{equation}
\begin{split}
\bm{x}_1  &= \bm{x}_0 + \big(a \bm{v}_0 - b \grad  E(\bm{x}_0) + c \bm{n}_0  \big) \tau \\
\bm{x}_2  &= \bm{x}_1 + \bigg( a \Big( a \bm{v}_0 - b \grad  E(\bm{x}_0) + c \bm{n}_0 \Big) - b \grad  E(\bm{x}_1) + c \bm{n}_1 \bigg) \tau \\
\bm{x}_3  &= \bm{x}_2 + \Bigg(a\bigg(a \Big( a \bm{v}_0 - b \grad  E(\bm{x}_0) + c \bm{n}_0 \Big) - b \grad  E(\bm{x}_1) + c \bm{n}_1 \bigg) - b \grad  E(\bm{x}_2) + c \bm{n}_2 \Bigg) \tau \\
\end{split}
\end{equation}
Recall we can compute the derivatives with respect to a parameter $\theta$ using the total derivative:
\begin{equation}
D_{\theta}f \equiv \dfrac{df( x_0, \ldots, x_n ;\theta)}{d\theta} = \dfrac{\partial f}{\partial x_0} \dfrac{\partial x_0} {\partial\theta} + \ldots + \dfrac{\partial f}{\partial x_n}\dfrac{\partial x_n}{\partial\theta} + \dfrac{\partial f}{\partial \theta}
\end{equation}
We can then compute the equations of motion:
\begin{equation}
\begin{split}
\dfrac{\partial\bm{x}_1}{\partial\theta}  &= - b\tau D_{\theta} \grad E(\bm{x}_0) \\
\dfrac{\partial\bm{x}_2}{\partial\theta}  &= - b\tau \Big(D_{\theta} \grad E(\bm{x}_0)(1+a)+D_{\theta} \grad E(\bm{x}_1)\Big)\\
\dfrac{\partial\bm{x}_3}{\partial\theta}  &= - b\tau \Big(D_{\theta} \grad E(\bm{x}_0)(1+a+a^2)+D_{\theta} \grad E(\bm{x}_1)(1+a)+D_{\theta} \grad E(\bm{x}_2)\Big)\\
\end{split}
\end{equation}
Where,
\begin{equation}
D_{\theta} \grad E(\bm{x}_t) = \dfrac{\partial \grad E}{\partial \bm{x}_t} \dfrac{\partial \bm{x}_t} {\partial\theta} + \dfrac{\partial \grad E}{\partial \theta}
\end{equation}
Which we can tidy this up into the following expression:
\begin{equation}
\dfrac {\partial \bm{x}_t}{\partial \theta} = -b  \tau \Big( D_{\theta} \grad E(\bm{x}_0; \theta)S_{t-1}^a + D_{\theta} \grad E(\bm{x}_1;\theta)S_{t-2}^a + \ldots +  D_{\theta} \grad E(\bm{x}_{t-1};\theta) \Big)
\end{equation}
$S_n^a$ is the geometric series of $n$ terms of $a$. Observe that we only need to do a single forward pass, which can be implemented using forward-mode auto-differentiation. Naively, this procedure needs $O(t)$ memory and $O(t^2)$ runtime since we need to store $\partial\bm{x}_i / \partial\theta$ and traverse back in time as they're re-weighted after each step. But this would catastrophic for all practical purposes. Fortunately, we can immediately leverage the geometric series, whose rapid convergence implies we need to store the $\zeta$ terms for only a small numbers of the most recent steps, since for large $t$:
\begin{equation}
D_{\theta} \grad E(\bm{x}_0)(1+a+a^2+...+a^t) \approx D_{\theta} \grad E(\bm{x}_0)(1+a+a^2+...+a^{t-1})
\end{equation}

Suppose it takes $k$ steps for the geometric series converge to numerical accuracy. This allows us to maintain a rolling window of only size $O(k)$ for unconverged $\zeta$ values. The converged $\zeta$ terms can be reduced and thus require only $O(1)$ extra space. In practice, $k \approx 4000$, so the over all algorithm becomes becomes $O(1)$ in memory and $O(t)$ in time.

% With this machinery in place, we can now use some additional tricks to regularize the fitting process, such as enforcing that for all ergodic systems, the time averaged observable must be equal to the ensemble averaged observable. The exact method is that we use reservoir sampling to draw from the time average, and the last time slice of a replica simulation to generate the ensemble average.

\section{Periodic Boundary Conditions}

If our energy function also depends on a set of box vectors $\bm{b}$ then we need to augment our equations of motion with:

\begin{equation}
\bm{b}_t = \bm{b}_{t-1} - \grad_{\bm{b}}E \tau
\end{equation}

Here $\grad_{\bm{b}}$ is the gradient operator with respect to the box vectors $\bm{b}$. Similar to the above, we can also compute the parameter derivatives of the box vectors through time:

\begin{equation}
\dfrac {\partial \bm{b}_t}{\partial \theta} = -\tau \Big( D_{\theta} \grad_{\bm{b}} E(\bm{x}_0,\bm{b}_0; \theta) + D_{\theta} \grad_{\bm{b}} E(\bm{x}_1,\bm{b}_1;\theta) + \ldots +  D_{\theta} \grad_{\bm{b}} E(\bm{x}_{t-1},\bm{b}_{t-1};\theta) \Big)
\end{equation}

We should also take care to update all the total derivatives to account for the box vectors:

\begin{equation}
D_{\theta} \grad E(\bm{x},\bm{b}) = \dfrac{\partial \grad E}{\partial \bm{x}} \dfrac{\partial \bm{x}} {\partial\theta} + \dfrac{\partial \grad E}{\partial \bm{b}} \dfrac{\partial \bm{b}} {\partial\theta} + \dfrac{\partial \grad E}{\partial \theta}
\end{equation}

Similarly,

\begin{equation}
D_{\theta} \grad_{\bm{b}} E(\bm{x},\bm{b}) = \dfrac{\partial \grad_{\bm{b}} E}{\partial \bm{x}} \dfrac{\partial \bm{x}} {\partial\theta} + \dfrac{\partial \grad_{\bm{b}} E}{\partial \bm{b}} \dfrac{\partial \bm{b}} {\partial\theta} + \dfrac{\partial \grad_{\bm{b}} E}{\partial \theta}
\end{equation}

Note that:

\begin{equation}
\dfrac{\partial \grad E}{\partial \bm{b}} \equiv \dfrac{\partial \grad_{\bm{b}} E}{\partial \bm{x}}
\end{equation}

\section{Issues and Caveats}

The first major issue has to do how training proceeds. The above procedure needs to be repeated multiple times for the parameters to converge. That is, each iteration would require us to re-run an entire MD simulation since we can't easily re-use the intermediate values. For some test systems it can take anywhere from 50 to 500 rounds of simulations for a single system to be fully optimized (internal data).

A second more practical issue deals with the computational complexity and speed. The analytically dense Hessian is an inherently $O(N^2)$, which is a major increase from the standard $O(N log N)$ in MD. While the bonded terms have sparse diagonal Hessians, it is unclear if the nonbonded hessians can be sparsified. Furthermore, because the derivatives are automatically generated, and that it's using tensorflow underneath the hood, the simulation itself is significantly slower than a highly optimized MD package. However, with recent advances in XLA-JIT and the flexibility of implementing custom ops, we hope to reconcile this to within an order of magnitude.

\section{Code}

The code is publicly available at www.github.com/proteneer/timemachine and licensed under the Apache V2.

\end{document}


\chapter{Evaluation}

\section{Measures of Success}

The success of the project can be measured by comparing the project results with objectives. We will also review the design choices in constructing the tool. The review will highlight the practical outcomes from using argumentation to explain scheduling.
\linespace
Arguably, the most important outcome of this project is that the tool is functionality correct. This means the tool is required to explain schedules for feasibility, efficiency and satisfaction with respect to user decisions.
\linespace
One objective is to implement an accessible tool. To measure accessibility, we can refer to the tractability complexity from explanations. The length of explanations either in the number of words or characters may be correlated with understandability. In addition, we conduct a survey targeted towards potential users. Because the understandability of explanations are difficult to measure, we will use open-ended questions. To carefully evaluate explanations, one would need to refer to cognitive science, which is beyond the scope of this project. We use a survey to measure the accessibility of our tool. Moreover, we can measure performance to reflect responsiveness and scalability of the tool \cite{foundationimplementation}. This may be achieved by using profiling utilities to measure performance metrics such as execution time and memory consumption.

\section{Complexity Results}

We summarise our complexity results from Chapter \ref{implementation}.

\begin{figure}[H]
	\begin{tabular}{lccc}
		\hline
		Algorithm & Computational & Memory & Tractability\\
		\hline
		\textsc{Construct-Feasibility} & $\mathcal{O}(m^2n^2)$ & $\mathcal{O}(m^2n^2)$ &\\
		\textsc{Construct-Efficiency} & $\mathcal{O}(m^2n^2)$ & $\mathcal{O}(m^2n^2)$ &\\
		\textsc{Construct-Satisfaction} & $\mathcal{O}(m^2n)$ & $\mathcal{O}(m^2n^2)$ &\\
		\textsc{Compute-Unattacked} & $\mathcal{O}(m^2n^2)$ & $\mathcal{O}(mn)$ &\\
		\textsc{Compute-Partial-Conflicts} & $\mathcal{O}(mn)$ & $\mathcal{O}(mn)$ &\\
		\textsc{Explain-Stability} & $\mathcal{O}(m^2n^2)$ & $\mathcal{O}(m^2n^2)$ &\\
		\textsc{Explain-Feasibility} & $\mathcal{O}(mn^2)$ & $\mathcal{O}(mn)$ & $\mathcal{O}(mn)$\\
		\textsc{Explain-Efficiency} & $\mathcal{O}(mn^2\log(mn^2))$ & $\mathcal{O}(mn^2)$ & $\mathcal{O}(mn^2)$\\
		\textsc{Explain-Satisfaction} & $\mathcal{O}(mn)$ & $\mathcal{O}(mn)$ & $\mathcal{O}(mn)$\\
		\textsc{Full-Precomputation-Explain} & $\mathcal{O}(m^2n^2\log(mn^2))$ & $\mathcal{O}(m^2n^2)$ & $\mathcal{O}(mn^2)$\\
		\textsc{Partial-Precomputation-Explain} & $\mathcal{O}(m^2n^2\log(mn^2))$ & $\mathcal{O}(mn^2)$ & $\mathcal{O}(mn^2)$\\
		\hline
	\end{tabular}
	\caption{Computational, memory and tractability complexity of algorithms using argumentation}
\end{figure}

Using an naive explanation approach only improves the computational complexity of verifying the feasibility property, from $\mathcal{O}(m^2n^2)$ to $\mathcal{O}(mn)$. Overall, we sse that \textsc{Partial-Precomputation-Explain} is better than \textsc{Full-Precomputation-Explain} by an order of $m$ in memory.

\section{Profiling}

The tool's functionality is demonstrated in the user documentation guide in Appendix \ref{userguide}. We will compare different implementation methods and their effectiveness using performance metrics. We will compare two algorithmic approaches to AAF construction with and the naive approach without argumentation. We implement the algorithms, then we profile for elapsed time and maximum allocated memory. The time and memory are measured with the Python's \texttt{cProfile} and \texttt{memory-profiler} modules respectively. The tool was executed on Department of Computing's virtual machines, with the specification of dual-core CPU at 2GHz with 2GiB RAM.
\linespace
Time comparison:
\begin{itemize}
	\item Elapsed time measurements are noisy.
	\item For less than 100 jobs, all approaches have approximately equal timings.
	\item From profiling, the tool takes 0.4 seconds on average to startup.
	\item Partial precomputation is 3\% faster than full precomputation on average, excluding startup time.
	\item Naive is 18\% faster than partial precomputation on average, excluding startup time.
	\item Both graphs hint at quadratic complexity.
\end{itemize}

Memory comparison:
\begin{itemize}
	\item For less than 40 jobs, all approaches have approximately equal memory usage.
	\item From profiling, the tool uses 52MiB on average to startup.
	\item For a large number of jobs, partial-precomputation is 7 times more efficient than full precomputation excluding startup memory.
	\item Naive and partial-precomputation have less than 1\% memory usage difference.
	\item Both graphs hint at quadratic complexity.
\end{itemize}
\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{figures/precomputation_cpu_small}
	\caption{Elapsed time comparison where $m=10$ and $0\leq n\leq 100$ with 1000 samples.}
\end{figure}

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{figures/precomputation_cpu_big}
	\caption{Elapsed time comparison where $m=10$ and $0\leq n\leq 800$ with 8000 samples.}
\end{figure}

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{figures/precomputation_memory_small}
	\caption{Maximum allocated memory comparison where $m=10$ and $0\leq n\leq 100$ with 1000 samples.}
\end{figure}

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{figures/precomputation_memory_big}
	\caption{Maximum allocated memory comparison where $m=10$ and $0\leq n\leq 800$ with 8000 samples.}
\end{figure}

\section{Questionnaire}

We conduct surveys with three disjoint sample groups.

\begin{itemize}
	\item \textbf{Group 1}: 10 people who are not given any explanations.
	\item \textbf{Group 2}: 12 people who are given simple explanations generated from the tool, but do not have interactive access to the tool.
	\item \textbf{Group 3}: 7 people who are given interactive access to the tool.
\end{itemize}

In all groups, we used the same questionnaire, which can be found in the appendix. Each question was carefully designed to be completed mentally while exploring concepts in makespan scheduling. We do not ask about feasibility because its validation is trivial.

\begin{itemize}
	\item Question 1 shows an efficient but non-optimal schedule. The tool does not explain optimality, so users can see cases where the tool may not be helpful.
	\item Question 2 shows a schedule with more machines and jobs, to test whether users can find improvements in a non-trivial schedule. It is possible to optimise the schedule in one single exchange, but this may not be obvious.
	\item Question 3 shows an application of fixed decisions.
	\item Question 4 explores pairs of jobs, which can be modelled using fixed decisions. The question explores how intuition can be formed using additional constraints.
	\item Question 5 explores replanning of a schedule by insertion of a new job. Clearly, trivially inserting a new job does not result in a optimal schedule. It is possible to arrange the schedule in one single exchange before insertion to achieve an optimal updated schedule.
\end{itemize}

Although these five questions do not cover the tool's complete functionality, they seek explanations that require intuition, with or without the tool. This is important in assessing how users can operate the tool in non-trivial cases. In this survey, we asked a wide demographic, from GCSE students to graduates, including friends who have little knowledge of computer science or mathematics.

\subsection{Group 1 Results}

\begin{figure}[H]
	\begin{center}
		\includegraphics[scale=0.55]{figures/questionnaire_results_group_one}
	\end{center}
	\caption{Aggregated Group 1 results from Section \ref{group1data}}
	\label{group1chart}
\end{figure}

From Figure \ref{group1chart}, we see that the majority of respondents are able to get most questions correct. Some responses are considered complex, when their answers are technically correct, but give more steps than necessary. This may hint that some intuitive ways to optimise a schedule may not minimise the number of job exchanges. This was evident in Question 2 and 5, that has many jobs. We can see in more complex schedules that users give more complex answers. Some responses are considered incomplete, where only the question was partially answered. This was evident in Question 4, where many respondents failed to identity either decision yields an optimal schedule.

\subsection{Group 2 Results}

\begin{figure}[H]
	\begin{center}
		\includegraphics[scale=0.55]{figures/questionnaire_results_group_two}
	\end{center}
	\caption{Aggregated Group 2 results from Section \ref{group2data}}
	\label{group2chart}
\end{figure}

From Figure \ref{group2chart}, we can make the following observations of Group 2 compared to Group 1:
\begin{itemize}
	\item Group 2 respondents performed better than Group 1, and in less time, from 15 minutes 37 seconds to 9 minutes 12 seconds on average, excluding outliers.
	\item Group 1 respondents completed all questions, but there a few Group 2 respondents who did not answer the latter questions. This is illustrated the constant bar heights in Figure \ref{group1chart} and decreasing bar heights in Figure \ref{group2chart}.
	\item When relevant explanations are given in Questions 2 and 5, there are more complex answers in Group 2 than Group 1. The answers suggests that respondents are likely to select the easiest to understand explanation, rather than the simplest optimal schedule. This is significant in Question 5, where many respondents used the first suggestion from the explanation without further intuition.
	\item Question 3 and 4 give situations in which respondents answer which situation results in a more optimal schedule. We can see that explanations significantly improve answers.
	\item In question 1, the explanation given was not relevant, so we would expect answers from Groups 1 and 2 would be similar because the underlying question is the same. From the data, we can see some variance between Groups 1 and 2.
\end{itemize}

\subsection{Group 3 Results}

\begin{figure}[H]
	\begin{center}
		\includegraphics[scale=0.55]{figures/questionnaire_results_group_three}
	\end{center}
	\caption{Aggregated Group 3 results from Section \ref{group3data}}
	\label{group3chart}
\end{figure}

\begin{itemize}
	\item Group 3 respondents took the longest to answer the questions, with 18 minutes and 27 seconds, excluding outliers. Users spent time understanding how to use the tool. To give a more fair comparison of time, users should not been able to start the questionnaire while reading the user guide.
	\item From question 3, many respondents said to simply move jobs to satisfy negative fixed decisions, without concern of the schedule's optimality. This suggests that users took the suggestions from the tool literally. As many users suggested local changes, many answers were considered incomplete. If we instructed users to write explicitly the path to an optimum, then we can expect results from Group 2 and 3 to be similar.
	\item Group 3 has the smallest sample size, means that the data is noisy. For instance, one respondent got two questions wrong, which largely offsets the chart.
\end{itemize}

\subsection{Summary}

\begin{figure}
	\begin{center}
		\includegraphics[scale=0.55]{figures/questionnaire_results_summary}
	\end{center}
	\caption{Aggregated results from Figures \ref{group1chart}, \ref{group2chart}, and \ref{group3chart}}
	\label{summarychart}
\end{figure}

\begin{itemize}
	\item Group 1 has the worst performance.
	\item Group 2 has the best performance, but many answers use are long and complex, often using the first obvious solution.
	\item Group 3 has the median performance, with many incomplete answers, using only one iteration of the tool.
\end{itemize}

After Group 3 used the tool, we had an informal discussion of the tool.
\begin{itemize}
	\item Many respondents said the tool was largely useable.
	\item The idea of fixed decisions was intuitive but was confusing at the beginning. For many respondents, the concept of fixed decisions was trivial with small problems, so they didn't see the purpose of it.
	\item The respondents who skipped the user guide had issues with inputting data. Although they learnt to use the tool, future work on the interface would be helpful.
\end{itemize}

\subsection{Feedback}

During development of the tool and questionnaires, I asked my colleagues and friends for feedback about the tool.

\begin{itemize}
	\item In early versions of the tool, the GUI did not arrange textboxes and buttons into groups such as problem, schedule and explanation. Instead, all buttons and their functionality were exposed as an menu. This was confusing to new users because it was not evident which textboxes were input or output.
	\item The paper \cite{aes} represented machine job pair assignments as a pairs of integer indices. The tool internally uses indices to compute explanations, however exposing both machines and job as integer indices was confusing. Therefore, jobs are now represented alphabetically.
	\item The tool uses regular expressions to validate user input. Many users complained about the strict validation errors. We solve this by pre-processing the input by correcting missing or surplus white-space.
\end{itemize}


\chapter{confelm}

\section{Introduction}
One way in which information about confluence can be used before state space generation, is by appending confluent ISTEPs to other summands.
This has the effect that other branches that could follow those summands are ignored, reducing the size of the state space while maintaining its equivalence up to branching bisimulation.

\section{Formal background}

\subsection{Definite successors}

Consider a summand pair $(s_\alpha, s_\beta)$, referencing the elements of $s_\alpha$ and $s_\beta$ conform \ref{summandelements}.
Summand $s_\beta$ is said to be a \emph{definite successor} of $s_\alpha$ if the following expression is a tautology:
\begin{align*}
g_\alpha \rightarrow {g_\beta}[v \mapsto q(v) \;|\; v \in \varsof{g_\beta} \setminus P][p \mapsto v_\alpha(p) \;|\; p \in P]
\end{align*}

where $q(v)$ is a bijective function that relates variable $v$ to a fresh variable.

For a summand $s$, let $D(s)$ be the set of all definite successors of $s$.
By design, $D(s)$ is an under-approximation of the actual successors of $s$.

\section{Algorithm}

The algorithm follows these steps:

\begin{enumerate}

\item Determine which \istep{} summands of the LPE are confluent (see \ref{confcheck}).
Rename the \istep{} channels in confluent \istep{} summands to \cistep{}.

\item For each summand $s_\alpha$, determine $D(s_\alpha)$.
Consider all possible pairs of summands $(s_\alpha, s_\beta)$ such that $s_\beta \in D(s_\alpha)$ and $C_\beta = \cistep{}$, and reference the elements of $s_\alpha$ and $s_\beta$ conform \ref{summandelements}.

Let
\begin{align*}
X = [ x_\beta(j) \mapsto q(x_\beta(j)) \;|\; 1 \leq j \leq m_\beta ]
\end{align*}

where $q(x)$ is a surjective function that yields fresh variables, and let
\begin{align*}
V_\alpha &= [p_j \mapsto v_\alpha(p_j) \;|\; 1 \leq j \leq k]
\end{align*}

Replace $s_\alpha$ by ${s_\alpha}'$, which is defined as
\begin{align*}
{s_\alpha}' = C_\alpha \; &\texttt{?} \; x_\alpha(1) \; \cdots{} \; \texttt{?} \; x_\alpha(m_\alpha) \\
&\texttt{?} \; x_\beta(1)[X] \; \cdots{} \; \texttt{?} \; x_\beta(m_\beta)[X] \\
&[[g_\alpha]] \; \texttt{>->} \; P(v_\beta(p_1)[X][V_1], \cdots{}, v_2(p_k)[X][V_\alpha])
\end{align*}

\item Replace all occurrences of \cistep{} channels with \istep{} channels.
\end{enumerate}

\section{Example}

Consider the following example:

\begin{lstlisting}
//Process definition:
PROCDEF example[A :: Int](x, y :: Int)
  = A >-> example[A]((x+1) mod 3, y)
  + CISTEP >-> example[A](x, (y+1) mod 4)
  ;

//Initialization:
example[A](0, 0);
\end{lstlisting}

The second summand is a \cistep{} summand.
It is also a definite successor of the first summand.
This means that the second summand will be appended to the first summand.

The second summand is also a definite successor of itself.
This means that the second summand will also be appended to itself.

Therefore, the original process is changed to

\begin{lstlisting}
//Process definition:
PROCDEF example[A :: Int](x, y :: Int)
  = A >-> example[A]((x+1) mod 3, (y+1) mod 4)
  + ISTEP >-> example[A](x, (((y+1) mod 4)+1) mod 4)
  ;

//Initialization:
example[A](0, 0);
\end{lstlisting}

\section{Benchmark results}

The following durations were measured with a benchmark for several models:
\begin{itemize}
\item The average duration of \txs{} to make 500 steps in a model after it has been converted to LPE form;
\item The average duration of \txs{} to make 500 steps in a model after it has been converted to LPE form and after the \texttt{confelm} operation has been applied.
\end{itemize}

When plotting the second series of measurements against the first (see Figure~\ref{confelm-vs-lpe-only:fig}), the effect of \texttt{confelm} appears to only have some minor effect on one model, namely the \texttt{Adder3} model.
Unfortunately, this model is not very realistic since it simply consists of three parallel processes without any synchronization.

\begin{figure}[!ht]
\begin{center}
\includegraphics[width=0.7\linewidth]{charts/confelm-vs-lpe-only}
\caption{Benchmark results: confelm vs LPE transformation}
\label{confelm-vs-lpe-only:fig}
\end{center}
\end{figure}