\chapter{Implementation}
\label{chp:implementation}

\nomad is a \verb|C++| implementation of reverse mode automatic
differentiation that uses an \textit{operator overloading} strategy.
More precisely, we introduce a dual number type and then overload
common functions to accept this type.

A key difference of \nomad to other implementations is the generalization
to higher-orders.  Most higher-order automatic differentiation
implementations leverage the recursive nature of higher-order dual
numbers directly, automatically differentiating through a first-order
implementation to compute higher-order partial derivatives and
the subsequent linear differential operators.  This approach allows for
arbitrary-order automatic differentiation, but only at the cost of inefficient and
sometimes numerically unstable results.  \nomad,
on the other hand, explicitly implements second and third-order operators
with a focus on performance and numerical stability.

In this chapter we introduce the architecture behind the \nomad automatic
differentiation implementation.  We first review the internal representation
of the expression graph and how it interfaces with function overloads before
discussing the user interface itself.

\section{Internal Representation of the Expression Graph}
\label{sec:exp_graph_rep}

While the expression graph represents the entire composite function, each
node in the expression graph represents just a single component function.
Consequently each node must be responsible for both implementing the
local pushforward and pullback of the corresponding function and storing
the dual numbers, input nodes, and any auxiliary storage convenient for
the operator implementations, such as partial derivatives.

Like many other automatic differentiation implementations, \nomad
topologically sorts the expression graph into a linear stack of nodes,
sometimes known as a tape (Figure \ref{fig:topologicalSort}).  This ordering
preserves the structure of the expression graph, ensuring that a sweep
through the stack executes a valid forward or reverse sweep through the
expression graph.

\begin{figure}
\setlength{\unitlength}{0.1in}
\centering
\begin{picture}(50, 20)
%
%\put(0, 0) { \framebox(50, 20){} }
%\put(25, 0) { \framebox(25, 30){} }
%\put(25, 0) { \framebox(6.25, 30){} }
%\put(25, 0) { \framebox(12.5, 30){} }
%\put(25, 0) { \framebox(18.75, 30){} }
%
%\put(25, 0) { \framebox(3.125, 30){} }
%\put(25, 0) { \framebox(9.375, 30){} }
%\put(25, 0) { \framebox(15.625, 30){} }
%
% Expression Graph
%
\put(6.25, 2.5) { \circle{4} }
\put(6.25, 2.5) { \makebox(0, 0) {$ x_{1} $} }
%
\put(12.5, 2.5) { \circle{4} }
\put(12.5, 2.5) { \makebox(0, 0) { $ x_{2} $ } }
%
\put(18.75, 2.5) { \circle{4} }
\put(18.75, 2.5) { \makebox(0, 0) { $ x_{3} $ } }
%
\put(6.25, 4.5) { \vector(3, 4){2.75} }
\put(12.5, 4.5) { \vector(-3, 4){2.75} }
\put(12.5, 4.5) { \vector(3, 4){2.75} }
\put(18.75, 4.5) { \vector(-3, 4){2.75} }
%
\put(10, 10) {\circle{4} } % Tweaked to the right
\put(9.375, 10) { \makebox(0, 0) { $f_{1}$ } }
%
\put(16.25, 10) {\circle{4} } % Tweaked to the right
\put(15.625, 10) { \makebox(0, 0) { $f_{2}$ } }
%
\put(9.375, 12) { \vector(3, 4){2.75} }
\put(15.625, 12) { \vector(-3, 4){2.75} }
%
\put(13, 17.5) {\circle{4} } % Tweaked to the right
\put(12.5, 17.5) { \makebox(0, 0) { $ g $ } }
%
% Middle Arrow
%
\put(21.875, 10) { \thicklines \vector(1, 0){6.25} }
%
% Stack
%
\put(33.5, 4) { \framebox(8, 2){ $x_{1}$} }
\put(33.5, 6) { \framebox(8, 2){ $x_{2}$ } }
\put(33.5, 8) { \framebox(8, 2){ $x_{3}$ } }
\put(33.5, 10) { \framebox(8, 2){ $f_{1}$ } }
\put(33.5, 12) { \framebox(8, 2){ $f_{2}$ } }
\put(33.5, 14) { \framebox(8, 2){ $g$ } }
%
\end{picture}
\caption{
A topological sort of the expression graph yields a linear stack of nodes,
sometimes known as a \textit{tape}, ordered such that a pass through the
stack yields a valid forward or reverse sweep of the expression graph.
}
\label{fig:topologicalSort}
\end{figure}

Nodes are implemented with the \verb|var_node| class which defines
default pushforward and pullback methods that can be specialized
for functions with structured Jacobians.  Because the amount of storage for
each node can vary widely depending on the corresponding function and the
order of the desired linear differential operator, storage is decoupled from
each node.  Instead the necessary data are stored in three global stacks, the
inputs stack, dual numbers stack, and partials stack, with \verb|var_node|
containing only an address to the relevant data in each
(Figure \ref{fig:architecture}), as well as accessor and mutator methods that
abstract the indirect storage.

Storage for each stack is pre-allocated and expanded only as necessary with
an arena-based allocation pattern.

\begin{figure}
\setlength{\unitlength}{0.1in}
\centering
\begin{picture}(50, 30)
%
%\put(0, 0) { \framebox(50, 30){} }
%
%\put(0, 0) { \framebox(12.5, 30){} }
%\put(0, 0) { \framebox(25, 30){} }
%\put(0, 0) { \framebox(37.5, 30){} }
%
%\put(0, 0) { \framebox(50, 7.5){} }
%\put(0, 0) { \framebox(50, 15){} }
%\put(0, 0) { \framebox(50, 22.5){} }
%
% Var Body
%
\put(8.5, 2) { \makebox(8, 2){Var Node} }
\put(8.5, 6) { \framebox(8, 2){} }
\put(8.5, 8) { \framebox(8, 2){} }
\put(8.5, 10) { \framebox(8, 2){} }
\put(8.5, 12) { \framebox(8, 2){} }
\put(8.5, 14) { \framebox(8, 2){} }
\put(8.5, 16) { \framebox(8, 2){} }
\put(8.5, 18) { \framebox(8, 2){} }
\put(8.5, 20) { \framebox(8, 2){} }
\put(8.5, 22) { \framebox(8, 2){} }
\put(8.5, 24) { \framebox(8, 2){} }
%
% Inputs
%
\put(39, 24) { \makebox(8, 2){Inputs} }
\put(25, 22) { \framebox(2, 6){} }
\put(27, 22) { \framebox(2, 6){} }
\put(29, 22) { \framebox(2, 6){} }
\put(31, 22) { \framebox(2, 6){} }
\put(33, 22) { \framebox(2, 6){} }
\put(35, 22) { \framebox(2, 6){} }
\put(37, 22) { \framebox(2, 6){} }
%
% Dual Numbers
%
\put(39, 15) { \makebox(8, 2){Dual} }
\put(39, 13) { \makebox(8, 2){Numbers} }
\put(25, 12) { \framebox(2, 6){} }
\put(27, 12) { \framebox(2, 6){} }
\put(29, 12) { \framebox(2, 6){} }
\put(31, 12) { \framebox(2, 6){} }
\put(33, 12) { \framebox(2, 6){} }
\put(35, 12) { \framebox(2, 6){} }
\put(37, 12) { \framebox(2, 6){} }
%
% Partials
%
\put(39, 4) { \makebox(8, 2){Partials} }
\put(25, 2) { \framebox(2, 6){} }
\put(27, 2) { \framebox(2, 6){} }
\put(29, 2) { \framebox(2, 6){} }
\put(31, 2) { \framebox(2, 6){} }
\put(33, 2) { \framebox(2, 6){} }
\put(35, 2) { \framebox(2, 6){} }
\put(37, 2) { \framebox(2, 6){} }
%
% Arrows
%
\thicklines
\put(32, 22) { \vector(-1, -1){4} }
\put(34, 22) { \vector(0, -1){4} }
%
\put(16.5, 15) { \vector(4, 3){15.5} }
\put(16.5, 15) { \vector(1, 0){19.5} }
\put(16.5, 15) { \vector(2, -1){17.5} }
%
\end{picture}
\caption{
Upon a topological sort (Figure \ref{fig:topologicalSort}), the expression graph
is represented by a stack of \texttt{var\_node} objects.  The input nodes,
dual numbers, and partial derivatives are stored in external stacks, with each
\texttt{var\_node} storing only addresses to each.  Note that the inputs stack
address not the \texttt{var\_node} objects directly, but rather only the dual numbers
of those nodes needed for implementing the pushforward and pullback operators.
}
\label{fig:architecture}
\end{figure}

\subsubsection{The Inputs Stack}

The inputs stack represents the edges in the expression graph
needed for directing the forward and reverse sweeps.  Because
the pushforward and pullback operators need to read and write only
the dual numbers at each node, edges index the dual numbers of any
dependencies directly (Figure \ref{fig:architecture}) and avoid the overhead
that would be acquired for indirect access through the \verb|var_node|
objects.

\subsubsection{Dual Number Stack}

The dual number stack stores the $2^{k}$ components of the $k$th-order
dual numbers at each node.  For example, a first-order expression graph
will need only two elements for each node while a third-order expression
graph will need eight (Figure \ref{fig:dualNumberStorage}).

\begin{figure}
\setlength{\unitlength}{0.1in}
\centering
\begin{picture}(50, 20)
%
%\put(0, 0) { \framebox(50, 20){} }
%
% First-Order
%
\put(0, 15) { \makebox(8, 2){First-} }
\put(0, 13) { \makebox(8, 2){Order} }
\put(9, 17) { \makebox(2, 2){ $\ldots$ } }
\put(9, 11) { \makebox(2, 2){ $\ldots$ } }
\put(11, 12) { \framebox(4, 6){ $x $ } }
\put(15, 12) { \framebox(4, 6){ $ \delta x $ } }
\put(19, 17) { \makebox(2, 2){ $\ldots$ } }
\put(19, 11) { \makebox(2, 2){ $\ldots$ } }
%
{ \thicklines \put(13, 20) { \vector(0, -1){2} } }
%
% Second-Order
%
\put(0, 5) { \makebox(8, 2){Third-} }
\put(0, 3) { \makebox(8, 2){Order} }
\put(9, 7) { \makebox(2, 2){ $\ldots$ } }
\put(9, 1) { \makebox(2, 2){ $\ldots$ } }
\put(11, 2) { \framebox(4, 6){ $s$ } }
\put(15, 2) { \framebox(4, 6){ $\delta s$ } }
\put(19, 2) { \framebox(4, 6){ $\delta t$ } }
\put(23, 2) { \framebox(4, 6){ $\delta^{2} t$ } }
\put(27, 2) { \framebox(4, 6){ $\delta u$ } }
\put(31, 2) { \framebox(4, 6){ $\delta^{2} u$ } }
\put(35, 2) { \framebox(4, 6){ $\delta^{2} v$ } }
\put(39, 2) { \framebox(4, 6){ $\delta^{3} v$ } }
\put(43, 7) { \makebox(2, 2){ $\ldots$ } }
\put(43, 1) { \makebox(2, 2){ $\ldots$ } }
%
{ \thicklines \put(13, 10) { \vector(0, -1){2} } }
%
\end{picture}
\caption{
The dual number stack is able to accommodate storage of dual numbers
of any order without reallocating memory.  For example, first-order dual
numbers require only two elements while third-order dual numbers require
eight elements.
}
\label{fig:dualNumberStorage}
\end{figure}

\subsubsection{Partials Stack}

A common approach in many automatic differentiation implementations
is to compute partial derivatives online as necessary and avoid storing them
in the expression graph.  This strategy is sound for first-order reverse
mode calculations where the partials are used only once, but higher-order
calculations require multiple sweeps that reuse the partials.  Recomputing
the partials for each sweep then becomes a significant computational burden.

With a focus on implementing efficient higher-order methods, \nomad
explicitly stores partial derivatives in a dedicated partials stack.  When
constructing an $k$th-order expression graph only the $k$th-order partial
derivatives and lower are stored, and only if the partial derivatives are
non-zero.  For example, a second-order expression graph will calculate
and store only the first and second-order partial derivatives.

To avoid redundant calculations and storage, \nomad stores only the
unique higher-order values.  In a second-order calculation a node
representing the component function
$f: \mathbb{R}^{N} \rightarrow \mathbb{R}$ will store
%
\begin{equation*}
\frac{ \partial^{2} f }{ \partial x_{i} \partial x_{j} }, \, i \in 1, \ldots, N, j \in 1, \ldots i,
\end{equation*}
%
while a third-order calculation will store
%
\begin{equation*}
\frac{ \partial^{3} f }{ \partial x_{i} \partial x_{j} \partial x_{k} }, \,
i \in 1, \ldots, N, j \in 1, \ldots i, k \in 1, \ldots, j.
\end{equation*}
%
For example, when executing a third-order calculation the node representing
a binary function, $f : \mathbb{R}^{2} \rightarrow \mathbb{R}$, utilizes the
compact storage demonstrated in Figure \ref{fig:partialsStorage}.

\begin{figure}
\setlength{\unitlength}{0.1in}
\centering
\begin{picture}(50, 10)
%
%\put(0, 0) { \framebox(50, 10){} }
%
% Second-Order
%
\put(5, 7) { \makebox(2, 2){ $\ldots$ } }
\put(5, 1) { \makebox(2, 2){ $\ldots$ } }
\put(7, 2) { \framebox(4, 6){ $ \frac{ \partial f }{ \partial x} $ } }
\put(11, 2) { \framebox(4, 6){ $ \frac{ \partial f }{ \partial y} $ } }
\put(15, 2) { \framebox(4, 6){ $ \frac{ \partial^{2} f }{ \partial x^{2}} $ } }
\put(19, 2) { \framebox(4, 6){ $ \frac{ \partial^{2} f }{ \partial x \partial y} $ } }
\put(23, 2) { \framebox(4, 6){ $ \frac{ \partial^{2} f }{ \partial y^{2}} $ } }
\put(27, 2) { \framebox(4, 6){ $ \frac{ \partial^{3} f }{ \partial x^{3}} $ } }
\put(31, 2) { \framebox(4, 6){ $ \frac{ \partial^{3} f }{ \partial x^{2} \partial y} $ } }
\put(35, 2) { \framebox(4, 6){ $ \frac{ \partial^{3} f }{ \partial x \partial y^{3}} $ } }
\put(39, 2) { \framebox(4, 6){ $ \frac{ \partial^{3} f }{ \partial y^{3}} $ } }
\put(43, 7) { \makebox(2, 2){ $\ldots$ } }
\put(43, 1) { \makebox(2, 2){ $\ldots$ } }
%
{ \thicklines \put(9, 10) { \vector(0, -1){2} } }
%
\end{picture}
\caption{
Only unique partial derivatives are stored in the partials stack,
as demonstrated here for node representing a binary function,
$f: \mathbb{R}^{2} \rightarrow \mathbb{R}$, in a third-order
expression graph that requires first, second, and third-order
partial derivatives.
}
\label{fig:partialsStorage}
\end{figure}

In general a function with $N$ inputs and non-vanishing derivatives at
all orders will require $\binom{N + M}{M}$ elements to store the unique
$M$th-order partial derivatives.

\section{Extending Functions to Accept Dual Numbers}

In order to implement automatic differentiation calculations, each dual-number
valued-function is responsible for not only computing the function
value but also expanding the expression graph with the addition of
a node with the desired pushforward and pullback methods and
addresses to the top of the inputs, dual numbers, and partials stacks.
The evaluation of a composite dual number-valued function will then
build the complete expression graph primed for the application of
linear differential operators.

Dual numbers in \nomad are exposed to the user by the \verb|var|
class with \verb|var|-valued functions responsible for the management
of the expression graph.  In this section we present the details of
the \verb|var| class and the implementation of \verb|var|-valued functions.

\subsection{The var Class}

The \verb|var| class itself is only a lightweight wrapper for an underlying
\verb|var_node| in the expression graph, storing an address to the
corresponding node with a variety of member functions that expose the
node's data.  Most importantly, \verb|var| is templated to allow for the
compile-time configuration of the expression graph,
%
\begin{verbatim}
template <short AutodiffOrder, bool StrictSmoothness, bool ValidateIO>
class var { ...
\end{verbatim}
%
\nomad also defines a variety of type definitions for the most commonly
used template configurations (Table \ref{tab:typedefs}).

\begin{table*}[t!]
	\centering
	\renewcommand{\arraystretch}{2}
	\begin{tabular}{cccc}
	\rowcolor[gray]{0.9} Type Definition & \verb|AutodiffOrder|
	& \verb|StrictSmoothness| & \verb|ValidateIO| \\
	\verb|var1| & \verb|1| & \verb|true| & \verb|false| \\
	\rowcolor[gray]{0.9} \verb|var2| & \verb|2| & \verb|true| & \verb|false| \\
	\verb|var3| & \verb|3| & \verb|true| & \verb|false| \\
	\rowcolor[gray]{0.9} \verb|var1_debug| & \verb|1| & \verb|true| & \verb|true| \\
	\verb|var2_debug| & \verb|2| & \verb|true| & \verb|true| \\
	\rowcolor[gray]{0.9} \verb|var3_debug| & \verb|3| & \verb|true| & \verb|true| \\
	\verb|var1_wild| & \verb|1| & \verb|false| & \verb|false| \\
	\rowcolor[gray]{0.9} \verb|var2_wild| & \verb|2| & \verb|false| & \verb|false| \\
	\verb|var3_wild| & \verb|3| & \verb|false| & \verb|false| \\
	\end{tabular}
	\caption{The \texttt{nomad} namespace includes helpful type definitions for
	the most common \texttt{var} configurations.}
	\label{tab:typedefs}
\end{table*}

\subsubsection{AutodiffOrder}

The template parameter \verb|AutodiffOrder| defines the maximum order
linear differential operator that the corresponding expression graph will
admit.  Attempting to apply a second-order linear differential operator
to a graph built from \verb|var|s with \verb|AutodiffOrder = 1|, for example,
will induce a compile-time error.

Note that lower-order graphs require the computation and storage of
fewer dual numbers and partial derivatives, not to mention faster pushforward
and pullback implementations.  Consequently, although a higher-order
graph will admit lower-order operators, it is much more efficient to match
the order of the expression graph, via the choice of \verb|AutodiffOrder|,
to the linear differential operators of interest.

\subsubsection{StrictSmoothness}

\verb|StrictSmoothness| defines the smoothness requirements of
component functions.

Formally, automatic differentiation requires only that each component
function have well-behaved derivatives defined in some neighborhood
containing the point at which the function is being evaluated.  For
example, a linear differential operator applied to the absolute value
function is well defined everywhere except at the origin.  Many
algorithms that use these operators, however, actually require that
the derivatives be well-defined \textit{everywhere} because even
functions with only point discontinuities in their derivatives will
manifest undesired pathologies.

With these algorithms in mind, when \verb|StrictSmoothness = true|
\nomad will disable functions and operators that are not everywhere
smooth, as well as those that admit comparisons that may introduce cusps.

\subsubsection{ValidateIO}

\verb|ValidateIO| enables strict validation of the inputs and outputs
to each component function.

Identifying the source of potential floating-point pathologies like
underflow, overflow and \verb|NaN| in a large, composite function
is often a challenging debugging task.  When \verb|ValidateIO = true|,
\nomad assists users by checking all input values, output values,
and output partial derivatives for \verb|NaN| and throws an
exception identifying the responsible component function if any
are found.  Domain validation will also be done if implemented in
the function.  These checks, however, are a nontrivial computational
burden and should be disabled for high-performance applications.

\subsection{var-valued Functions}

Extending a function to take \verb|var| arguments requires not just propagating the
value of the function but also creating a new node in the expression
graph.  In this section we review the steps necessary for implementing
a \verb|var|-valued function and present some specific examples.

\subsubsection{Input Validation}

Firstly, a \verb|var|-valued function has to validate its inputs if
\verb|ValidateIO| is \verb|true|.  \nomad provides helper functions
that validate double values and throws \nomad-specific exceptions
if \verb|NaN|s are encountered,
%
\begin{verbatim}
inline void validate_input(double val, std::string f_name)
\end{verbatim}
%
Here \verb|f_name| is the name of the function being implemented
and is used to trace the exception to the origin of the violation.
Domain constraints may also be validated here with helper functions
such as
%
\begin{verbatim}
inline void validate_lower_bound(double val, double lower, std::string f_name)
\end{verbatim}

\subsubsection{Expression Graph Node Creation}

With the inputs validated we can now append a new node to the
expression graph with the \verb|create_node| function.  This function
is templated to accept the type of node being used by the function
and will require the number of inputs to the function unless the
specific \verb|var_node| implementation does not require it.

For example, if the function is utilizing the default \verb|var_node|
implementation then the call would be
%
\begin{verbatim}
create_node<var_node<AutodiffOrder, PartialsOrder>>(n_inputs);
\end{verbatim}
%
On the other hand, a function utilizing a \verb|var_node| specialization
with a predefined number of inputs would not need to specify an
argument,
%
\begin{verbatim}
create_node<binary_var_node<AutodiffOrder, PartialsOrder>>();
\end{verbatim}

\subsubsection{Pushing Inputs}

Once the node representing the component function has been created
we can now being to push the necessary data onto the external stacks.
First are the addresses of the inputs to the function,
%
\begin{verbatim}
inline void push_inputs(nomad_idx_t input)
\end{verbatim}
%
which are readily accessed from the input \verb|var| arguments.

\subsubsection{Pushing Dual Numbers}

Next are the dual numbers.  The function
%
\begin{verbatim}
template<short AutodiffOrder, bool ValidateIO>
inline void push_dual_numbers(double val)
\end{verbatim}
%
pushes $2^{\mathrm{AutodiffOrder}}$ components onto the stack, with
the first component set to the value of the function, \verb|val|, and the
rest set to zero.

When \verb|ValidateIO = true| the function \verb|push_dual_numbers|
will also check the output \verb|val| for a \verb|NaN| and throw an
exception if necessary.  Consequently the call to \verb|push_dual_numbers|
must be wrapped in a \verb|try/catch| block, preferable one that throws
a new exception identifying the current function, for example
%
\begin{verbatim}
try {
  push_dual_numbers<AutodiffOrder, ValidateIO>(binary_function(x, y));
} catch(nomad_error) {
  throw nomad_output_value_error("binary_function");
}
\end{verbatim}

\subsubsection{Pushing Partials}

Finally we can compute the partial derivatives and push them onto the
partials stack with
%
\begin{verbatim}
template<bool ValidateIO>
inline void push_partials(double partial)
\end{verbatim}
%
As with \verb|push_dual_numbers|, \verb|push_partials| will optionally
validate the values of the partial derivatives and must be wrapped in
a \verb|try/catch| block,
%
\begin{verbatim}
try {
  if (AutodiffOrder >= 1) {
    push_partials<ValidateIO>(df_dx);
    push_partials<ValidateIO>(df_dy);
  }
  ...Push higher-order partial derivatives...
} catch(nomad_error) {
  throw nomad_output_partial_error("binary_function");
}
\end{verbatim}

Because partial derivatives only up to \verb|AutodiffOrder| need to be
computed and stored, efficient implementations of a \verb|var|-valued
function should evaluate partial derivatives only conditionally on
\verb|AutodiffOrder|.

\subsubsection{Returning a New Var}

Finally we return a new \verb|var| that wraps the freshly-created node.
%
\begin{verbatim}
return var<AutodiffOrder, StrictSmoothness, ValidateIO>(next_node_idx_ - 1);
\end{verbatim}
%
\verb|next_node_idx_| addresses the top of the \verb|var_node| stack, hence
\verb|next_node_idx_ - 1| addresses the last node pushed to the stack.

\subsubsection{Example Implemention of a Smooth Function}

The logic of a \verb|var|-valued function implementation is more clear
when each step is presented together.  Here is an example implementation
of a smooth, binary function using the default \verb|var_node| implementation.

\begin{verbatim}
template <short AutodiffOrder, bool StrictSmoothness, bool ValidateIO>
inline var<AutodiffOrder, StrictSmoothness, ValidateIO>
  binary_function(const var<AutodiffOrder, StrictSmoothness, ValidateIO>& v1,
                  const var<AutodiffOrder, StrictSmoothness, ValidateIO>& v2) {

  // Validate input values if ValidateIO is true
  if (ValidateIO) {
    validate_input(v1.first_val(), "binary_function");
    validate_input(v2.first_val(), "binary_function");
  }

  // Create a var_node on the top of the stack
  const short partials_order = 3;
  const unsigned int n_inputs = 2;

  create_node<var_node<AutodiffOrder, partials_order>>(n_inputs);

  // Push dependencies to top of the inputs stack
  push_inputs(v1.dual_numbers());
  push_inputs(v2.dual_numbers());

  // Push dual numbers to the the top of the dual numbers stack
  double x = v1.first_val();
  double y = v2.first_val();

  try {
    push_dual_numbers<AutodiffOrder, ValidateIO>(binary_function(x, y));
  } catch(nomad_error) {
    throw nomad_output_value_error("binary_function");
  }

  // Push partial derivatives to the top of the partials stack
  try {
    if (AutodiffOrder >= 1) {
      ...Compute df_dx and df_dy...
      push_partials<ValidateIO>(df_dx);
      push_partials<ValidateIO>(df_dy);
    }
    if (AutodiffOrder >= 2) {
      ...Compute df2_dx2, df2_dxy, and df2_dy2...
      push_partials<ValidateIO>(df2_dx2);
      push_partials<ValidateIO>(df2_dxdy);
      push_partials<ValidateIO>(df2_dy2);
    }
    if (AutodiffOrder >= 3) {
      ...Compute df3_dx3, df3_dx2dy, df3_dxdy2, and df3_dy3...
      push_partials<ValidateIO>(df3_dx3);
      push_partials<ValidateIO>(df3_dx2dy);
      push_partials<ValidateIO>(df3_dxdy2);
      push_partials<ValidateIO>(df3_dy3);
    }
  } catch(nomad_error) {
    throw nomad_output_partial_error("binary_function");
  }

  // Return a new var that wraps the newly created node
  return var<AutodiffOrder, StrictSmoothness, ValidateIO>(next_node_idx_ - 1);

}
\end{verbatim}
%
Note that expensive calculations, such as when validating inputs and computing
and storing partial derivatives, are conditioned on template parameters wherever
possible to avoid unnecessary computation.  Because these template parameters
are known at compile-time these checks incur no run-time penalties.

When the partial derivatives of a function are structured then we can achieve
much higher performance by specializing the underlying \verb|var_node|.
For example, the only non-zero partial derivatives of the addition operator
are at first-order, and they are all equal to $1$.  Consequently we can speed
up the automatic differentiation computations by specializing \verb|var_node|
to avoid unnecessary multiplications by $1$.

This is done in the \verb|binary_sum_var_node| and the implementation of
the addition operator then becomes
%
\begin{verbatim}
template <short AutodiffOrder, bool StrictSmoothness, bool ValidateIO>
inline var<AutodiffOrder, StrictSmoothness, ValidateIO>
  operator+(const var<AutodiffOrder, StrictSmoothness, ValidateIO>& v1,
            const var<AutodiffOrder, StrictSmoothness, ValidateIO>& v2) {

  if (ValidateIO) {
    validate_input(v1.first_val(), "operator+");
    validate_input(v2.first_val(), "operator+");
  }

  // Create a specialized var_node on the stack
  create_node<binary_sum_var_node<AutodiffOrder>>();

  push_inputs(v1.dual_numbers());
  push_inputs(v2.dual_numbers());

  try {
    push_dual_numbers<AutodiffOrder, ValidateIO>(v1.first_val() + v2.first_val());
  } catch(nomad_error) {
    throw nomad_output_value_error("operator+");
  }

  // The binary_sum_var_node pushforward and pullback implementations
  // use hardcoded partial derivatives and don't require partial derivatives to
  // be pushed onto the partials stack

  return var<AutodiffOrder, StrictSmoothness, ValidateIO>(next_node_idx_ - 1);

}
\end{verbatim}

\subsubsection{Example Implemention of a Non-Smooth Function}

Non-smooth functions are implemented almost exactly the same as smooth functions.
The only difference is in the function signature which uses the \verb|enable_if|
template metaprogram to disable the function unless \verb|StrictSmoothness = 1|.

For example, the absolute value function is implemented as
%
\begin{verbatim}
template <short AutodiffOrder, bool StrictSmoothness, bool ValidateIO>
inline typename
  std::enable_if<!StrictSmoothness,
                 var<AutodiffOrder, StrictSmoothness, ValidateIO> >::type
  fabs(const var<AutodiffOrder, StrictSmoothness, ValidateIO>& input) {

  if (ValidateIO) validate_input(input.first_val(), "fabs");

  const short partials_order = 1;
  const unsigned int n_inputs = 1;

  create_node<unary_var_node<AutodiffOrder, partials_order>>(n_inputs);

  double x = input.first_val();

  try {
    push_dual_numbers<AutodiffOrder, ValidateIO>(fabs(x));
  } catch(nomad_error) {
    throw nomad_output_value_error("fabs");
  }

  push_inputs(input.dual_numbers());

  try {
    if (AutodiffOrder >= 1) {
      if (x < 0)
        push_partials<ValidateIO>(-1);
      else
        push_partials<ValidateIO>(1);
    }
  } catch(nomad_error) {
    throw nomad_output_partial_error("fabs");
  }

  return var<AutodiffOrder, StrictSmoothness, ValidateIO>(next_node_idx_ - 1);

}
\end{verbatim}

\section{The \nomad User Interface}
\label{sec:user_interface}

In \nomad, linear differential operators are implemented as functionals acting
on \verb|var|-valued functors.

Specifically, functors are classes deriving from \verb|base_functor|
%
\begin{verbatim}
template<class T>
class base_functor {
public:
  virtual T operator()(const Eigen::VectorXd& x) const;
  typedef T var_type;
};
\end{verbatim}
%
that implement a \verb|var|-valued \verb|operator()| taking an
\verb|Eigen::VectorXd&| of input values.  For example, at
first-order the composite function
%
\begin{equation*}
f \! \left( x, y, z \right) = \cos \! \left( e^{x} + e^{y} \right) / z
\end{equation*}
%
would be defined as
%
\begin{verbatim}
class example_functor: public base_functor<var1> {
  var1 operator()(const Eigen::VectorXd& x) const {
    var1 v1 = x[0];
    var1 v2 = x[1];
    var1 v3 = x[2];
    return cos( exp(v1) + exp(v2) ) / v3;
  }
};
\end{verbatim}

The functionals implementing linear differential operators then
take a functor instance as an argument, first calling \verb|operator()|
to build the expression graph and then the various sweeps
necessary to compute the differential operator itself.  For example,
the gradient is defined with the signature
%
\begin{verbatim}
template <typename F>
void gradient(const F& f,
              const Eigen::VectorXd& x,
              Eigen::VectorXd& g)
\end{verbatim}
%
Consequently computing a gradient is straightforward,
%
\begin{verbatim}
int n = 100;
Eigen::VectorXd x = Eigen::VectorXd::Ones(n);

double f;
Eigen::VectorXd grad(x.size());

example_functor example;
gradient(example, x, f, grad);

std::cout << grad.transpose() << std::endl;
\end{verbatim}

For the complete list of \verb|var|-valued functions and linear differential
operators implemented in \nomad please consult Chapter \ref{chap:reference_guide}.


\section{Test Description and Success Criteria}
This test is located at {\tt simulation/dynamics/RadiationPressure/\_UnitTest/test\_radiationPressure.py} In order to get good coverage of all the aspects of the module, the test is broken up into three sub-tests. In each sub-test, a spacecraft is placed in the solar system and acted upon by the Sun. \par

\subsection{``Cannonball" Method} This test utilizes the ``cannonball" method to calculate the effects of radiation pressure on spacecraft dynamics. The cannonball method approximates the spacecraft as a sphere. External forces in the inertial and body frame, as well as external torques in the body frame, are checked against known values.
\subsection{Table Look-up Method} This test uses a stored table of known effects of radiation pressure. It looks up values and compares them to the expected result to validate radiation pressure table look-up capabilities.
\subsection{Table Look-up with Eclipse} This test is the same as the Table Look-up Method except that the spacecraft experiences a partial eclipse during the test. The experiences forces and torques are expected to be exactly half of what they are without the eclipse.
\subsection{Table Look-up Compared to Cannonball} This test compares the output of the table look-up method to the outputs of the cannonball method. This time, the look-up tables have been generated assuming a spherical spacecraft so that no torques are calculated. The tables also indicate that the spacecraft has a radius which works with the solar radiation pressure to generate a 1 $N$ away from the sun. Furthermore, the cannonball method is given a very specific area input to generate the appropriate force. This test validates that the look-up method is generating reasonable results.

\section{Test Parameters}

This section summarizes the error tolerances for each test. Error tolerances are determined based on whether the test results comparison should be exact or approximate due to integration or other reasons. Error tolerances for each test are summarized in table \ref{tab:errortol}.

\begin{table}[htbp]
	\caption{Error tolerance for each test.}
	\label{tab:errortol}
	\centering \fontsize{10}{10}\selectfont
	\begin{tabular}{ c | c } % Column formatting,
		\hline
		\textbf{Test}   	      	               & \textbf{Tolerated Error} 						           \\ \hline
		``Cannonball"                           &\input{AutoTex/cannonballAccuracy}	 			  \\ \hline
		Look-up						                & \input{AutoTex/lookupAccuracy}		   				\\ \hline
		Look-up With Eclipse	             & \input{AutoTex/lookupWithEclipseAccuracy}    \\ \hline
		Look-up	(torque)			               & \input{AutoTex/lookupTorqueAccuracy}		   				\\ \hline
		Look-up With Eclipse (torque)	& \input{AutoTex/lookupWithEclipseTorqueAccuracy}    \\ \hline
		``Cannonball'' Look-up				&\input{AutoTex/cannonballLookupAccuracy} \\ \hline
		``Cannonball'' Look-up (torque)&\input{AutoTex/cannonballLookupTorqueAccuracy} \\ \hline
	\end{tabular}
\end{table}

\noindent Note that the lookup model tests utilize more stringent tolerances for torques. This is because the torque values are too small to use the same tolerances as the force calculations.

\section{Test Results}

All checks within test\_radiationPressure.py passed as expected. Table \ref{tab:results} shows the test results.

\begin{table}[H]
	\caption{Test results.}
	\label{tab:results}
	\centering \fontsize{10}{10}\selectfont
	\begin{tabular}{c | c | c  } % Column formatting,
		\hline
		\textbf{Test} 				      			& \textbf{Pass/Fail} 						   		   		 				& \textbf{Notes} 									        \\ \hline
		``Cannonball"	   			  			&\input{AutoTex/cannonballPassFail}      	  					&\input{AutoTex/cannonballFailMsg} 	        \\ \hline
		Look-up	   	                     				&\input{AutoTex/lookupPassFail}              				  &\input{AutoTex/lookupFailMsg}            		\\ \hline
		Look-up	(torque)			               & \input{AutoTex/lookupPassFail}				  			     &\input{AutoTex/lookupFailMsg}					\\ \hline
		Look-up With Eclipse      				&\input{AutoTex/lookupWithEclipsePassFail}  			&\input{AutoTex/lookupWithEclipseFailMsg}\\ \hline
		Look-up With Eclipse (torque)	& \input{AutoTex/lookupWithEclipsePassFail}                &\input{AutoTex/lookupWithEclipseFailMsg}\\ \hline
		``Cannonball'' Look-up				&\input{AutoTex/cannonballLookupPassFail}				&\input{AutoTex/cannonballLookupFailMsg}\\ \hline
		``Cannonball'' Look-up (torque)&\input{AutoTex/cannonballLookupPassFail}               &\input{AutoTex/cannonballLookupFailMsg}\\ \hline
	\end{tabular}
\end{table}


\section{Type inference}

We now formulate type inference for the \lang language. Type inference is
based on the HM(X) framework~\citep{DBLP:journals/tapos/OderskySW99} which
presents how to implement Hindley-Milner type inference in a language
with qualified types. We first present various preliminaries definitions,
we then show our extension of HM(X) that support a kind system and affine
types.

\subsection{Preliminaries}

\subsubsection{Usage maps}

In order to determine if a variable is used in an affine manner, we must track
its uses and the associated kinds. For instance, in the expression
$(x,x)$, $x$ is used twice. If $x$ is of type $\tau$, which is of kind $k$,
we must add the constraint $\Cleq{k}{\kun}$. In order to record uses and kinds,
our type inference relation will return a ``usage map'', noted $\Sv$,
which associates each variable to a list of kinds corresponding to each use site
of the variable.
We note $\Sone{x}{k_1,\dots,k_n}$ the singleton usage map.
Common operations on usage maps are defined in \cref{op:usgmap}. We define
regular set operations such as union
($\Sv\cup\Sv'$) and intersection ($\Sv\cap\Sv'$), along
with constraint creation $\Cleq{\Sv}{k_0}$ which indicates that all the kinds
presents in the usage map $\Sv$ are constrained by the kind $k_0$.
These operations corresponds roughly to the various parts of the join
operator on sets $\esplit{}{}$.

\begin{figure}[tp]\centering
\begin{mathpar}
  % \Sv\cap\Sv'
  % &= \left\{ x \to l,l'
  %   \mid \Sone{x}{l}\in\Sv \text{ and } \Sone{x}{l'}\in\Sv' \right\} \\
  % \infer
  % { \forall x \in \Dom{\Sv_1}\cup\Dom{\Sv_2}.\quad
  %   \bsplit{C_x}{\Sv(x)}{\Sv_1(x)}{\Sv_2(x)}
  % }
  % { \bsplit{(\bigwedge C_x)}{\Sv}{\Sv_1}{\Sv_2} }
  % &= \Sv\cap\Sv' \sqcup
  %   (\Sv\Sdel{x' \mid x'\in\Sv'}) \sqcup
  %   (\Sv'\Sdel{x \mid x\in\Sv})
  %   &\text{where $\sqcup$ is the disjoint union}\\
  % \and
  \inferrule{}
  { \Cleq{\Sv}{k}
    = \bigwedge_{\Sone{x}{\schm}\in\Sv} \Cleq{\schm}{k}
  }
  \and
  % \inferrule
  % { \forall \bshadow{x} \in \Sv, b'\in\Sv'.\quad
  %   \tregion{C_x}{y}{\bshadow{x}}{b'} }
  % { \bregion{(\bigwedge C_x)}{y}{\Sv}{\Sv'} }
  % \and
  % \inferrule
  % { \text{if } \operatorname{lenght}(\Sv(x))  = \Cempty{} \wedge  }
  { \Weaken_{(x,k)}(\Sv) =
    \begin{dcases}
      \Ctrue& \operatorname{length}(\Sv(x)) = 1\\
      {k}\lk\kaff_\infty& \text{ otherwise}\\
    \end{dcases}

  }
\end{mathpar}
\caption{Operation on usage maps $\Sv$}
\label{op:usgmap}
\end{figure}

\subsection{Kind inference}

We note $\inferK{(C,\unif)}{\bf{\E}}{\bf{\tau}}{k}$ when type $\tau$ has kind $k$
in environment $\E$ under constraints $C$ and unifier $\unif$. From an
algorithmic point of view, $\E$ and $\tau$ are the input parameters of
our inference procedure.
We present the kind inference algorithm as a set of syntax-directed rules in
\cref{rules:kinding}.
Since higher-kinded types are not supported, the type application
rule and the type constructor rule are merged in {\sc KApp}.
Additionally, type variables must be of a simple kind in rule {\sc KVar}.
Note that in the case of a type constructor with no argument, the {\sc KApp}
rule degenerates to a simpler form which is similar to the {\sc KVar} rule.
Kind schemes are instantiated in the {\sc KApp} and {\sc KVar} rules by creating
fresh kind variables and the associated substitution.

\begin{figure}[ht]
  \centering
  \input{infer/kinds}
  \caption{Kind inference algorithm -- $\inferK{(C,\unif)}{\E}{\tau}{(\Multi{k}) k}$}
  \label{rules:kinding}
\end{figure}

\subsection{Type inference}

We reformulate the HM(X) type inference in the context of our affine type
system. The main difference compared to HM(X) are noted in \addlin{blue}.
We note $\inferW{\addlin{\Sigma}}{(C,\unif)}{\bf{\E}}{\bf{e}}{\tau}$ when
$e$\ as type $\tau$ in $\E$ under the constraints $C$ and unifier $\unif$.
$\Sigma$ is a map which associates free variables in $e$ to
their kinds.
As before, $\E$ and $e$ are the input parameters of the inference
algorithm. The syntax-directed rules are shown in \cref{rules:typing}.

\begin{figure*}[htp]
  \input{infer/typing}
  \caption{Type inference algorithm -- $\inferW{\Sigma}{(C,\psi)}{\bf{\E}}{\bf{e}}{\tau}$ }
  \label{rules:typing}
\end{figure*}

\subsection{Normal forms and generalization}
\label{sec:normalize}

We now place ourselves in a more general context where kinds are either variables
or constants belonging to a total bounded lattice $(\mathcal L, \lk_\Lat)$ ie.,
a lattice which admits a total order and upper and lower bounds ($l^\top$ and $l^\bot$).
We note lattice elements $l$ and $\glb_i l_i$ (resp. $\lub_i l_i$)
the greatest lower bound (resp. least upper bound) in $\mathcal L$.
%
Let $\CL$ the set of constraints in this lattice. We consider the
following base entailment rules in this system:
\begin{center}
  \begin{mathpar}
    \inferrule{l \lk_\Lat l'}{\entail{}{\Cleq{l}{l'}}}
    \and
    \inferrule{}{\entail{}{\Cleq{k}{l^\top}}}
    \and
    \inferrule{}{\entail{}{\Cleq{l^\bot}{k}}}
  \end{mathpar}
\end{center}

The normalization procedure is noted $\normalize{C_0}{\unif_0}$ where
$C_0\in \CL$ is a set of constraints and $\unif_0$ is a substitution.
It returns a constraint $C \in \mathcal S$ in
solved form and a unifier $\unif$.
The main idea of the algorithm is to first remove all the type equalities
by using regular Herbrand unification. After that, we only have
a set of inequalities among kinds, which we can consider as a relation.
We can then saturate the relation,
unify all kinds that in the same equivalence classes to obtain
a most general unifier on kind variables,
remove all existentially quantified variables and
then minimize back the relation.

More precisely, we apply the following steps:
\begin{enumerate}
\item Solve all type equality constraints through Herband unification and
  gather all existential quantifications at the front of the constraint.
  We obtain a constraint $C^k = \exists \kvar_i,\ \Cleq{k_j}{k'_j}_j$ and
  a substitution $\unif_\tau$.

  We note $\mathcal R$ the relation $\Cleq{k_j}{k'_j}_j$,
  $\mathcal G$ the underlying directed graph and $V$ its vertices.

\item Saturate the lattice equalities in $\mathcal R$.

  More precisely, for each kind variable $\kvar \in V$,
  for each constant $l_i$ (resp. $l_j$) such that
  there is a path from $l_i$ to $\kvar$ (resp. from $\kvar$ to $l_j$) in $\mathcal G$,
  add an edge from $\lub l_i$ to $\kvar$
  (resp. from $\kvar$ to $\glb l_j$).
  This step is well defined since $\mathcal L$ is a bounded lattice
  and $\lub\emptyset$ and $\glb\emptyset$ are well defined.

  We also complement $\mathcal R$ with $(\leq)$ by adding an edge
  between related constants.
\item
  At this point, we can easily check for satisfiability: A constraint
  is satisfiable (in the given environment) if and only if,
  for any constants $l_1$ and $l_2$ such that
  there is a path from $l_1$ to $l_2$ in $\mathcal G$, then $l_1\lk_\Lat l_2$.
  If this is not the case, we return \textbf{fail}.

\item For each strongly connected component in $\mathcal G$, unify all its vertices and replace it by a representative.
  We note $\unif_k$ the substitution that replaces a kind variable by
  its representative.
  The representative of a strongly connected component $g$ can be determined as follows:
  \begin{itemize}
  \item If $g$ does not contain any constant, then the representative
    is a fresh kind variable.
  \item If $g$ contains exactly one constant, it is the representative.
  \item Otherwise, the initial constraint $C_0$ is not satisfiable.
  \end{itemize}
  Note that this step will also detect all unsatisfiable constraints.
\item Take the transitive closure of $\mathcal R$.
\item Remove all the vertices corresponding to the kind variables $\kvar_i$
  that are existentially quantified in $C^k$.
\item Take the transitive reduction of $\mathcal R$.
\item Remove the extremums of $\mathcal L$ and the edges of $(\leq)$
  from $\mathcal R$.
\item Return $C = \left\{ k \leq k' \mid k \operatorname{\mathcal R}k' \right\}$
  and $\unif =  \unif_\tau \meet \unif_k$.
\end{enumerate}

\TODO{Add an example}

\subsubsection{Soundness and Principality}

\begin{lemma}[Normal form]
  \label{lemma:normalform}
  Given a constraint $D\in\CL$, a substitution $\phi$ and
  $(C,\unif) = \normalize{D}{\phi}$,
  then $\phi\leq\unif$,
  $C \equivC \unif D$ and
  $\unif C = C$.
\end{lemma}
\begin{proof}
  % For simplicity, we assume that any substitution has been already applied
  % to $D$ and that $\phi = id$.
  Let us partition $\phi$ into a part which affects type variables,
  $\phi_\tau$, and a part which affects kind variables, $\phi_k$.

  We note $(C^k,\unif_\tau)$ the result of
  the modified Herbrand unification on $(D,\phi)$ in step (1).
  Herbrand unification computes the most general
  unifier. Our modified Herbrand unification only output additional
  kind constraints for kind on the arrows and does not change
  the result of the unification. Thus, we have
  $\phi_\tau\leq\unif_\tau$,
  $C^k \equivC \unif_\tau D$ and
  $\unif_\tau C^k = C^k$.

  Let $C^{k+}$ be the result after step (2), we trivially have that
  $\fv{C^{k+}} = \fv{C^k}$ and that $C^{k+} \equivC C^k$.

  Let $C^{A}$ and $\unif_k$ be the results after step (4).
  By definition, we have $\unif_k C^{k+} \equivC C^{A}$ and
  $\unif_k C^{A} = C^{A}$. Since $\phi_k$ has already be applied to $C$ before
  unifying the strongly connected components,
  we have that $\phi_k\leq\unif_k$.

  Let $\unif = \unif_\tau \meet \unif_k$. Since $\unif_\tau$ and $\unif_k$
  have disjoint supports,
  we have $C^{A} = \unif_\tau C^{A} \equivC \unif C^{k+} \equivC \unif D$
  and $\unif C^{A} = C^{A}$.
  Furthermore, $\phi_\tau \meet \phi_k \leq \unif_\tau \meet \unif_k$.

  Steps (5) to (9) all preserve the free variables and the equivalence
  of constraints, which concludes.
\end{proof}

\begin{lemma}[Uniqueness]
  Given $(C_1,\unif_1)$ and $(C_2,\unif_2)$ such that
  $\unif_1 C_1 \equivC \unif_2 C_2$, then
  $\normalize{C_1}{\unif_1}$ and $\normalize{C_2}{\unif_2}$
  are identical up to $\alpha$-renaming.
\end{lemma}
\begin{proof}
  In \cref{lemma:normalform}, we have showed that all the steps of the
  normalization procedure preserve equivalence.
  Since $\unif_1 C_1 \equivC \unif_2 C_2$, equivalence between
  the two results of the normalization procedures is preserved for all steps.

  We note $P(C_a)$ if for all $C = (k, k)'$
  such that $\entail{C_a}{C}$ and $\nvdash_eC$,
  we have $C \in {\mathcal R}_a$.

  Let us note $C_1'$ and $C_2'$ the constraints after step (4). $P(C_1')$ and
  $P(C_2')$ hold. Indeed, since $C_1'$ and $C_2'$ are only composed
  of existential quantifications and kind inequalities, the only rules
  that applies are transitivity and lattice inequalities.
  After step (2) and (5), the associated relations are fully saturated for these
  two rules, hence all inequalities that can be deduced from $C_a'$ are already
  present in the relation.

  The property $P$ is preserved by step (6) since we only remove
  inequalities that involve existentially quantified variables. Such
  inequalities could not be picked in $P$.
  % In (6) we only remove
  % trivial lattice inequalities.

  Let us note $C''_a$ for $a\in\{1,2\}$ the constraints after step (5).
  Since there are no more existential variables,
  we have $C''_a=(k_i,k'_i)_i=\mathcal R''_a$.
  For any $C=(k,k')$ such that $\entail{}{C}$ and $\entail{C''_a}{C}$,
  then $C \in (\leq) \subset {\mathcal R}''_a$.
  Indeed, the only trivial inequalities in our system are equalities of the form
  $(\kvar, \kvar)$, which were removed in step (4) and the lattice inequalities.

  Let us consider $C = (k,k') \in \mathcal R''_1$.
  Since $C''_1\equivC C''_2$, we have $\entail{C''_2}{C}$.
  If $\nvdash_e{C}$, by $P(C''_2)$ we have that
  $C\in R''_2$.
  If $\entail{}{C}$, then $C\in (\leq) \subset R''_2$.
  We conclude that $R''_1 \subset R''_2$.
  By symmetry, $R''_1 = R''_2$ and $C''_1 = C''_2$.

  This equality is preserved by step (7) and (8)
  since the transitive reduction of a directed acyclic graph is unique,
  which concludes.
\end{proof}

\begin{theorem}
  $\CL$ has the principal constraint property and
  $\operatorname{normalize}$ computes principal normal forms for $\CL$.
\end{theorem}

\begin{lemma}
  For all $C\in\mathcal S$, $\entail{C}{x = x}$ implies
  $\entail{}{x = x}$.
\end{lemma}
\begin{proof}
  By definition of $\operatorname{normalize}$, We have $C = \Cleq{k}{k'}_i$
  such that the underlying relation has no cycles.
  Thus, we can not deduce neither kind nor type equalities from $C$.
\end{proof}

\begin{lemma}
  $\CL$ is regular, ie, for $x, x'$ two types or kinds,
  $\entail{}{\Ceq{x}{x'}}$ implies
  $\fv{x} = \fv{x'}$
\end{lemma}
\begin{proof}
  The only equalities possibles are between variables (via symmetry) or
  between constants.
\end{proof}

\begin{theorem}
  Type inference in $HM(\CL)$ is sound, principal and complete.
\end{theorem}

\subsection{Principality}

\TODO{}

\begin{itemize}
\item Properly ensure that it respects HM(X) (cylindric, \dots)
\item Show principal type inference:
  \begin{itemize}
  \item Principal constraint system
  \item Regular constraint system: $\Ceq{\tau}{\tau'} \implies \fv{\tau} = \fv{\tau'}$.
  \item Solved forms are in simplified form.
    $C\in S, \entail{C}{\Ceq{\tau}{\tau'}} \implies \entail{}{\Ceq{\tau}{\tau'}}$.
  \end{itemize}
\item Show equivalence with the logic-based system.

\end{itemize}

% \begin{lemma}
%   Without loss of generality, we can consider that
%   kind inequalities in satisfiable constraints
%   are only done on kind variables.

%   \begin{proof}
%     Consider the constraint $\Cleq{k}{k'}\Cand C$.
%     \begin{itemize}
%     \item If $k$ and $k'$ are both constants, it can be removed.
%     \item If the constraint is $\Cleq{\kvar}{\kaff}$ or $\Cleq{\kun}{\kvar}$, it can be removed.
%     \item If the constraint is $\Cleq{\kvar}{\kun}$ or $\Cleq{\kaff}{\kvar}$, we
%       can substitute $\kvar$ by its value in $C$.
%     \end{itemize}
%   \end{proof}
% \end{lemma}

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "../main"
%%% End:


\subsection{ZINDO-based transfer integrals using MOO }
\label{sec:izindo}

\newcommand{\moo}{MOO\xspace}
\index{electronic coupling!ZINDO}

An approximate method based on Zerner's Intermediate Neglect of Differential Overlap (ZINDO) has been described in Ref.~\cite{kirkpatrick_approximate_2008}. This semiempirical method is substantially faster than first-principles approaches, since it avoids the self-consistent calculations on each individual monomer and dimer. This allows to construct the matrix elements of the ZINDO Hamiltonian of the dimer from the weighted overlap of molecular orbitals of the two monomers. Together with the introduction of rigid segments, only a single self-consistent calculation on one isolated conjugated segment is required. All relevant molecular overlaps can then be constructed from the obtained molecular orbitals.

The main advantage of the molecular orbital overlap (\moo) library is {\em fast} evaluation of electronic coupling elements. Note that \moo is based on the ZINDO Hamiltonian which has limited applicability. The general advice is to first compare the accuracy of the \moo method to the DFT-based calculations.

\moo can be used both in a \slink{prog:moo_overlap}{standalone mode} and as an \calc{izindo} \calculator of \votcactp.

Since \moo constructs the Fock operator of a dimer from the  molecular orbitals of monomers by translating and rotating the orbitals of \slink{sec:segments}{rigid fragments}, the optimized geometry of all \slink{sec:segments}{conjugated segments} and the coefficients of the molecular orbitals are required as its input in addition to the state file (\sqlstate) with the \slink{sec:neighborlist}{neighbor list}. Coordinates are stored in \xyz files with four columns, first being the atom type and the next three atom coordinates. This is a standard \texttt{xyz} format without a header. Note that the atom order in the \xyz files can be different from that of the mapping files. The correspondence between the two is established in the \xmlcsg file.

\attention{Izindo requires the specification of orbitals for hole and electron transport in \xmlcsg. They are the HOMO and LUMO respectively and can be retrieved from the \texttt{log} file from which the \orb file is generated. The number of \texttt{alpha electrons} is the HOMO, the LUMO is HOMO+1 }

The calculated transfer integrals are immediately saved to the \sqlstate file.
\votcacommand{Transfer integrals from \calc{izindo}}{\ctprun \opt \xmloptions \sql \sqlstate \exe \calc{izindo} }


% !TEX root = ../../../proposal.tex
In the following, $a||b$ denotes concatenation of strings $a$ and $b$.
$a{[i]}$ references the $i$-th byte in $a$. $(N,e)$ denotes an RSA public
key, where $N$ has byte-length $\ell_m$ ($|N|=\ell_m$) and $e$ is the public
exponent. The corresponding secret exponent is $d = 1/e \bmod \phi(N)$.

\subsection{\PKCS encryption padding}
\label{sec:PKCSdescr}

Our attacks rely on the structure of RSA \PKCS padding. Although RSA PKCS\#1
v2.0 implements OAEP, SSL/TLS still uses \PKCS. The \PKCS encryption padding
scheme~\cite{rfc2313} randomizes encryptions by prepending a random padding
string $PS$ to a message $k$ (here, a symmetric session key) before RSA
encryption:

\begin{enumerate}
	\item The plaintext message is $k$, $\ell_k = |k|$. The encrypter generates a random byte
	string $PS$, where $|PS| \geq 8$, $|PS|=\ell_m-3-\ell_k$, and $\hex{00} \not \in \{PS{[1]}, \ldots,PS{[|PS|]}\}$.
	\item The encryption block is $m = 00||02||PS||00||k$.
	\item The ciphertext is computed as $c = m^e \bmod N$.
\end{enumerate}

To decrypt such a ciphertext, the decrypter first computes $m = c^d
\bmod N$.  Then it checks whether the decrypted message $m$ is
correctly formatted as a \PKCS-encoded message. We say that the
ciphertext $c$ and the decrypted message bytes $m{[1]} || m{[2]} || ... ||
m{[\ell_m]}$ are \PKCSconform if:
\begin{equation*}
	\begin{split}
		m{[1]}||m{[2]} \text{ } = &\text{ } \hex{00} || \hex{02}\\
		\hex{00} \text{ } \not \in &\text{ } \{m{[3]}, \ldots,m{[10]}\}\\
	\end{split}
\end{equation*}
If this condition holds, the decrypter searches for the first value
$i>10$ such that $m{[i]}=0x00$. Then, it extracts $k =
m{[i+1]}||\ldots||m{[\ell_m]}$. Otherwise, the ciphertext is rejected.

In SSLv3 and TLS, RSA \PKCS is used to encapsulate the \pms exchanged during
the handshake~\cite{rfc5246}. Thus, $k$ is interpreted as the \pms. In SSLv2,
RSA \PKCS is used for encapsulation of an equivalent key denoted the
\texttt{master\_key}.

\subsection{SSL and TLS}
The first incarnation of the TLS protocol was the SSL (Secure Socket Layer)
protocol, which was designed by Netscape in the 90s. The first two versions
of SSL were immediately found to be vulnerable to trivial
attacks~\cite{rfc6176,ssl-v3-1996} which were fixed in SSLv3~\cite{rfc6101}.
Later versions of the standard were renamed TLS, and share a similar
structure to SSLv3. The current version of the protocol is TLS 1.2; TLS 1.3
is currently under development.

An SSL/TLS protocol flow consists of two phases: handshake and
application data exchange. In the first phase, the communicating
parties agree on cryptographic algorithms and establish shared
keys. In the second phase, these keys are used to protect the
confidentiality and authenticity of the transmitted application data.

The handshake protocol was fundamentally redesigned in the \sslthree
version. This new handshake protocol was then used in later TLS
versions up to TLS 1.2. In the following, we describe the RSA-based
handshake protocols used in TLS and \ssltwo, and highlight their
differences.

\paragraph{The \ssltwo handshake protocol.}
\label{sec:ssl2}

The \ssltwo protocol description~\cite{sslv2} is less formally specified than
modern RFCs. Figure~\ref{fig:ssl-handshake} depicts an \ssltwo handshake.

\begin{figure}
	\includegraphics[width=\linewidth]{\DrownFigures/ssl-handshake}
	\caption{\textbf{\ssltwo handshake}\,---\,%
	The server responds with a \texttt{ServerVerify} message directly after
    receiving an RSA-\PKCS ciphertext contained in \texttt{ClientMasterKey}.
	This protocol feature enables the attack.
	}
	\label{fig:ssl-handshake}
\end{figure}

A client initiates an \ssltwo handshake by sending a
\texttt{ClientHello} message, which includes a list of cipher
suites $cs_c$ supported by the client and a client nonce $r_c$,
termed \texttt{challenge}.
The server responds with a \texttt{ServerHello} message, which
contains a list of cipher suites $cs_s$ supported by the server,
the server certificate, and a server nonce $r_s$, termed
$\texttt{connection\_ID}$.

The client responds with a \texttt{ClientMasterKey} message, which
specifies a cipher suite supported by both peers and key data
used for constructing a \texttt{master\_key}. In order to support
\textit{export} cipher suites with 40-bit security (e.g.,
\texttt{SSL\_RC2\_128\_CBC\_EXPORT40\_WITH\_MD5}), the key data is
divided into two parts:
\begin{itemize}
	\item $mk_{clear}$: A portion of the \texttt{master\_key} sent in the \texttt{ClientMasterKey} message as plaintext (termed \texttt{clear\_key\_data} in the \ssltwo standard).
	\item $mk_{secret}$: A secret portion of the
          \texttt{master\_key}, encrypted with RSA \PKCS (termed \texttt{secret\_key\_data}).
\end{itemize}
The resulting \texttt{master\_key} $mk$ is constructed by
concatenating these two keys: $mk = mk_{clear} || mk_{secret}$. For
40-bit export cipher suites, $mk_{secret}$ is five bytes in length.
For non-export cipher suites, the whole \texttt{master\_key} is
encrypted, and the length of $mk_{clear}$ is zero.

The client and server can then compute session keys from the reconstructed \texttt{master\_key} $mk$:

\vspace{-6pt}
\begin{center}
\begin{math}
	\texttt{server\_write\_key} = MD5(mk || ``0" || r_c || r_s) \linebreak
	\texttt{client\_write\_key} = MD5(mk || ``1" || r_c || r_s)
\end{math}
\end{center}
\vspace{-6pt}

The server responds with a \texttt{ServerVerify} message
consisting of the \texttt{challenge} $r_c$ encrypted with the
\texttt{server\_write\_key}.  Both peers then exchange
\texttt{Finished} messages in order to authenticate to each other.

Our attack exploits the fact that the server always decrypts an RSA-\PKCS
ciphertext, computes the \texttt{server\_write\_key}, and \textit{immediately}
responds with a \texttt{ServerVerify} message.  The \ssltwo standard
implies this message ordering, but does not make it explicit.
However, we observed this behavior in every implementation we
examined.  Our attack also takes advantage of the fact that the
encrypted $mk_{secret}$ portion of the \texttt{master\_key} can vary
in length, and is only five bytes for export ciphers.

\ifsubmit\relax\else
\begin{figure}
	\includegraphics[width=\linewidth]{\DrownFigures/tls-handshake}
	\caption{\textbf{TLS-RSA handshake}\,---\,%
    After receiving an encrypted \pms, the server waits for an authenticated
	\texttt{ClientFinished} message.
	}
	\label{fig:tls-handshake}
\end{figure}
\fi

\paragraph{The TLS handshake protocol.}
In TLS~\cite{rfc5246} or \sslthree, the client initiates the handshake with a \texttt{ClientHello}, which contains a client random $r_c$ and a list of supported cipher suites. The server chooses one of the cipher suites and responds with three messages, \texttt{ServerHello}, \texttt{Certificate}, and \texttt{ServerHelloDone}. These messages include the server's choice of cipher suite, server nonce $r_s$, and a server certificate with an RSA public key. The client then uses the public key to encrypt a newly generated 48-byte \pms $pms$ and sends it to the server in a \texttt{ClientKeyExchange} message. The client and server then derive encryption and MAC keys from the \pms and the client and server random nonces. The details of this derivation are not important to our attack.  The client then sends \texttt{ChangeCipherSpec} and \texttt{Finished} messages. The \texttt{Finished} message authenticates all previous handshake messages using the derived keys. The server responds with its own \texttt{ChangeCipherSpec} and \texttt{Finished} messages.

The two main details relevant to our attacks are:
\begin{itemize}
	\item The \pms is always 48 bytes long, independent of the chosen cipher suite.  This is also true for export cipher suites.
	\item After receiving the \texttt{ClientKeyExchange} message, the server waits for the \texttt{ClientFinished} message, in order to authenticate the client.
\end{itemize}

\subsubsection{Real-world protocol support}
TLSv1.0 is the most commonly supported protocol version, according to several
surveys. The SSL Labs SSL Pulse survey~\cite{ssl-pulse} reports that 98.6\%
of about 140,000 popular TLS/SSL-enabled web sites supported TLSv1.0 in
January 2016. 72.0\% supported TLSv1.2. Support for \ssltwo was at 9.3\%, and
\sslthree was at 29\%. Mayer et al.~\cite{mail-tls-mayer-2015} performed
Internet-wide surveys of SMTP, IMAP, and POP3 between April and August 2015,
and found that support for \ssltwo support was as high as 41.7\% of servers
for SMTP on port 25 and as low as 3.7\% of IMAP servers on port 143. Support
for TLSv1.0 was nearly universal on these ports, varying from 91.6\% on port
25 to 98.9\% on port 143.

Bowen~\cite{cab-forum-sslv2} collected 213 million SSL/TLS client hellos and
user agent strings from connections to popular sites, of which 183,000
(0.09\%) client hellos supported \ssltwo. All of these client hellos also
supported at least TLSv1.0.

Holz et al.~\cite{mail-tls-holz-2016} performed passive monitoring to collect
information about 16 million SSL/TLS connections during one week in
July-August 2015. They did not report any numbers for \ssltwo, and stated in
personal communication that they did not observe any \ssltwo connections in
their dataset.

%In response to our disclosure, OpenSSL has disabled \ssltwo by default in the 1.0.1r and 1.0.2f releases~\cite{opensslchangelog}.

%This bug was also fixed in the aforementioned openssl releases.

\subsection{Bleichenbacher's attack}
\label{sec:bleichenbacher}
Bleichenbacher's attack is a padding oracle attack---it exploits the fact
that RSA ciphertexts should decrypt to \PKCS-compliant plaintexts. If an
implementation receives an RSA ciphertext that decrypts to an invalid \PKCS
plaintext, it might naturally leak this information via an error message, by
closing the connection, or by taking longer to process the error condition.
This behavior can leak information about the plaintext that can be modeled as
a cryptographic \textit{oracle} for the decryption process.
Bleichenbacher~\cite{bleichenbacher-1998} demonstrated how such an oracle
could be exploited to decrypt RSA ciphertexts.

%For example, the decrypting code may require different processing times for valid vs.\ invalid plaintexts - this is termed a "timing side-channel vulnerability". As another example, the decrypting code may send messages derived in some way from the plaintexts - this is termed a "direct message side channel vulnerability".
%The seminal work in this area \cite{Bleichenbacher} identified the general potential for such vulnerabilities, specifically using a direct message side channel vulnerability present in TLS implementations at the time, and demonstrated how such information could be gradually combined to eventually decrypt the RSA ciphertext in full.

\paragraph{Algorithm.}
In the simplest attack scenario, the attacker has a valid \PKCS
ciphertext $c_{0}$ that they wish to decrypt to discover the message
$m_{0}$.  They have no access to the private RSA key, but instead have
access to an oracle $\Oracle$ that will decrypt a ciphertext $c$ and
inform the attacker whether the most significant two bytes match
the required value for a correct \PKCS padding:
\begin{equation*}
\Oracle(c) =
\begin{cases}
1 & \text{ if } m=c^d \bmod N \text{ starts with \hexb{00}{02}} \\
0 & \text{ otherwise.}
\end{cases}
\end{equation*}

If the oracle answers with \texttt{1}, the attacker knows that $2B
\leq m \leq 3B-1$, where $B = 2^{8(\ell_m-2)}$.  The attacker can
take advantage of RSA malleability to generate new candidate ciphertexts
for any $s$:
\[
c = (c_{0} \cdot s^e) \bmod N = (m_{0} \cdot s)^e \bmod N
\]
The attacker queries the oracle with $c$. If the oracle responds with
$0$, the attacker increments $s$ and repeats the previous
step. Otherwise, the attacker learns that for some~$r$, $2B \leq m_{0}s - rN  < 3B$. This allows the attacker to reduce the range of possible solutions to:
\[
\frac{2B+rN}{s} \leq m_{0} < \frac{3B+rN}{s}
\]
The attacker proceeds by refining guesses for $s$ and $r$ values and
successively decreasing the size of the interval containing $m_{0}$.  At
some point the interval will contain a single valid value, $m_{0}$.
Bleichenbacher's original paper describes this process in further
detail~\cite{bleichenbacher-1998}.

\paragraph{Countermeasures.}
In order to protect against this attack, the decrypter must not leak
information about the \PKCS validity of the ciphertext.  The
ciphertext does not decrypt to a valid message, so the
decrypter generates a fake plaintext and continues the
protocol with this decoy.  The attacker should not be able to
distinguish the resulting computation from a correctly decrypted
ciphertext.

In the case of SSL/TLS, the server generates a random \pms to continue
the handshake if the decrypted ciphertext is
invalid.  The client will not possess the session key to send a valid
\texttt{ClientFinished} message and the connection will terminate.


\subsection{Introduction}

partial dependence plots can be used on black box models

Interpretation: if its interpretable then you can adjust an interpretable part manually part way?

Transparency of models:
Sparse linear models are more transparent.
Decomposition: Can each part of the model have input, output, parameters which can be interpreted?
Complex feature selection means loss of this. Complex models. Boosting. Loses
Can we say formal things about performance? We can for linear models (?), but not for others
For agents, we can't validate their behaviour. We can for manually defined rules. We can for interpretive  models.
Post-hoc interpretability

LIME Local Interpretable Model-Agnostic Explanations. Page on explainable models, h3 in that on locally explainable models

Explaining models: We may want to understand how it works. Black box algorithms are hard to understand.

This is important if the algorithm is used in high stakes cases, or where data is different to the static case used for training.

We can create explainable models (sparse linear models)

Take black box models and make them explainable.

SLAM algorithms?

Local explanation? Saliency maps?

Why do we care about transparency?


\documentclass[twoside]{article}

\usepackage{amsmath,amsthm}
\usepackage{xspace}
\usepackage{fancyhdr}
\usepackage{hyperref}
\usepackage[a4paper,left=2cm,right=2cm,top=2cm,bottom=2cm]{geometry}
\newtheorem{definition}{Definition}
%%% Logik

\input{./definitions}
\input{./version}

\title{\DiMo -- A Tool for Discrete Modelling Using Propositional Logic \\ Version \DiMoVersion}

\author{Martin Lange \\ University of Kassel, Germany}

\fancyhead[L]{M.~Lange}
\fancyhead[R]{The \DiMo Tool}
\fancyfoot[RO, LE]{\thepage}
\fancyfoot[C]{}
\renewcommand{\headrulewidth}{0.4pt}
\renewcommand{\footrulewidth}{0.4pt}
\pagestyle{fancy}

\allowdisplaybreaks

\begin{document}

\maketitle

\tableofcontents

\section{Discrete Modelling Problems}

The \DiMo language can be used to model various discrete decision or computation problems as logical problems in quantifier-free logic.
The four logical problems that are supported are
\begin{itemize}
\item the \emph{satisfiability problem} for finding \emph{some} model of a given formula;
\item the \emph{validity problem} for checking whether \emph{all} interpretations satisfy a given formula, respectively for finding
      a countermodel;
\item the \emph{model class} problem for finding \emph{all} models of a given formula;
\item the \emph{equivalence} problem for checking whether two given formulas are semantically equivalent on a given set of propositions,
      respectively finding a model (in those propositions) that separates the two.
\end{itemize}
The \DiMo language can be used to specify formulas \emph{parametrised} by natural numbers. The logical problems above are then applied
to \emph{all} instances of such formula schemes.

\section{Basic Design Principles of the Language}

\paragraph*{Specifying problems.}
A \DiMo input starts with the specification of the problem, defined by the keywords \texttt{SATISFIABLE}, \texttt{VALID},
\texttt{EQUIVALENT} or \texttt{MODELS}, followed by the formula scheme to be tested.

In case of the equivalence problem this is followed by the keyword \texttt{TO} and a second formula scheme. Note that this is a generalisation
of the standard equivalence problem which checks equality between the model classes of two formulas. Here the input is given by two formulas
$\varphi$ and $\psi$ and a set of propositional variables $L$, and the question is to decide whether the model classes of $\varphi$ and $\psi$
coincide when restricted to $L$. In other words: for every propositional variable assignment $\vartheta$ s.t.\ $\vartheta \models \varphi$, is
there a variable assignment $\vartheta'$ s.t.\ $\vartheta' \models \psi$ and $\vartheta(X) = \vartheta'(X)$ for all $X \in L$. Moreover, does
the same hold vice-versa between $\psi$ and $\varphi$? Note that this generalises semantic equivalence in the sense that each pair of
semantically equivalent formulas is also equivalent when restricted to any $L$ but not vice-versa.

\paragraph*{Specifying interesting predicates.}
One can then optionally specifiy the (names) of the predicate symbols which should be considered in the output. This can be used
to suppress the reporting of unnecessarily long models or countermodels, for instance when the formula schemes use certain predicate
symbols as auxiliary only. This is indicated by the keyword \texttt{PROPOSITIONS}, followed by a list of those predicate names. Note
that all predicate symbols not listed here are suppressed. Hence, without the \texttt{PROPOSITIONS} section in the input, no models /
countermodels are generated.

Furthermore, when the chosen problem is the equivalence problem then it is taken to be restricted to those propositions that are given
in this section. Consequently, when no propositions are given here, the equivalence problem boils down to a simple equi-satisfiability check.

\paragraph*{Specifying parameters.}
This section is followed by a section specifying the parameters to the formula scheme, started with the keyword \texttt{PARAMETERS}.
Parameters are variables for natural numbers and can be denoted with an arbitrary alphanumeric string starting with a lowercase letter.
Parameters to the scheme are specified as a comma-separated list of name-domain pairs, for instance
\begin{quote}
\texttt{n : NAT}
\end{quote}
defines a parameter \texttt{n} that stands for any number in $\{0,1,\ldots\}$. Other means to specify a domain are, for instance
\begin{center}
\begin{tabular}{ll}
\texttt{\{3,..\}} & for the set $\{3,4,5,\ldots\}$, \\
\texttt{\{3,7,..\}} & for the set $\{3,7,11,15,\ldots\}$, \\
\texttt{\{3,7,..,20\}} & for the set $\{3,7,11,15,19\}$, \\
\texttt{\{3,7,20,4,16\}} & for the set $\{3,4,7,16,20\}$.
\end{tabular}
\end{center}
It is possible to impose certain simple conditions on parameter combinations by appending the keyword \texttt{WITH}, followed by
a comma-separated non-empty list of basic comparisons like \texttt{n < m}. Allowed comparisons are \emph{equals}, \emph{greater-than},
\emph{less-than}, \emph{greater-or-equals}, \emph{less-or-equals}, and \emph{unequals}.

\paragraph*{Specifying formula abbreviations.}
There is no distinction between a predicate, like \texttt{P(n,m)} and an auxiliary formula. It is thus possible to abbreviate certain
formula parts and give the definition of these predicates in a final section started with the keyword \texttt{WHERE}, followed by
a list of definitions of the form
\begin{quote}
\emph{pattern} \texttt{=} \emph{formula}
\end{quote}
Note that there is no comma separation between these definitions. A pattern in this context is a predicate symbol, possibly followed
by a comma-separated list of variables or numbers, enclosed in parentheses, i.e.\ \texttt{P} or \texttt{P(n)} or \texttt{P(0,n)}.
Note that \DiMo does not type-check predicates w.r.t.\ their arity. A symbol should only be used with the same arity throughout the
entire specification.

\paragraph*{Specifying terms and finite sets.}
Terms are made up from integers and variables which are either specified in the \texttt{PARAMETERS} section or introduced by the junctors
\texttt{FORALL} and \texttt{FORSOME}, using the arithmetical operations of addition, subtraction and multiplication. Terms can be used
as arguments to predicate symbols, for instance as in \texttt{X(n,n+2)}.

A finite set is an enumeration of terms like \texttt{\{1,n,n+3,m-2,n*m+i,10\}}. It is possible to define linear sets by specifying the
least, possibly the second-to-least, and the last element. This follows the same convention as used in the specification of domains
above. For instance, \texttt{\{1,..,n\}}, \texttt{\{0,2,..,n-1\}} and \texttt{\{n,2*n,..,m*n\}} are valid specifications of such sets
provided that the variables have been defined either as parameters or via generalised junctors, see below.

There are also the operators \texttt{MIN} and \texttt{MAX} which turn sets into terms. For instance, \texttt{MIN \{n+1,9,k,m-n\}} is a term.

\paragraph*{Specifying formulas.}
The \DiMo language supports propositional logic with the standard Boolean unary or binary operators $\wedge,\vee,\neg,\to,\leftrightarrow$,
as well as conjunctions and disjunctions over finite sets of indices (e.g.\ $\bigwedge_{i=1}^n \ldots$). For instance, formula (scheme)
$\bigwedge_{i=0}^{n-1} X_i \leftrightarrow X_{i+1}$, parametrised by a natural number $n$ would be specified as
\begin{quote} \tt
  FORALL i: \{0,..,n-1\} . X(i) <-> X(i+1)
\end{quote}
In general, such a junctor defines a new variable \texttt{i} which can be used in the formula following the dot. A disjunction $\bigvee$
is denoted using the keyword \texttt{FORSOME}.

\section{Examples}

\subsection{The $n$-Queens Problem}

A standard discrete modelling problem is the following: given a chess board of size $n \times n$ with $n \ge 1$, place $n$ queens on this board such that
none of them threatens another. A queen in chess can move an arbitrary distance along a row, column or diagonale. Clearly, the problem
amounts to placing one queen in each column for example. Moreover, to exclude possible threats between queens, by symmetry it suffices to
consider one direction per row/column/diagonale only, for example no queen should ``see'' another queen in the directions east, north,
north-east and south-east.

The question of finding a solution to the $n$-queens problem boils down to finding a model of the following propositional formula (scheme) $\varphi_n$ for
given $n$. We use propositional variables $D_{i,j}$ with $1 \le i,j, \le n$ to intuitively denote that the square in column $i$ and row $j$ is occupied by a queen.
\begin{align*}
\varphi_n := & \bigwedge\limits_{i=1}^n \bigvee\limits_{j=1}^n D_{i,j} & \text{``\emph{in each column place a queen in some row}''} \\
\wedge & \bigwedge\limits_{i=1}^n \bigwedge\limits_{j=1}^{n-1} D_{i,j} \to \bigwedge\limits_{k=j+1}^n \neg D_{i,k} & \text{``\emph{no two queens per row}''} \\
\wedge & \bigwedge\limits_{i=1}^{n-1} \bigwedge\limits_{j=1}^n D_{i,j} \to \bigwedge\limits_{k=i+1}^n \neg D_{k,j} & \text{``\emph{no two queens per column}''} \\
\wedge & \bigwedge\limits_{i=1}^{n-1} \bigwedge\limits_{j=1}^{n-1} D_{i,j} \to \hspace*{-1cm}
  \bigwedge\limits_{k = 1 \atop \text{s.t. } i+k \le n \text{ and } j+k \le n}^\infty \hspace*{-1cm}\neg D_{i+k,j+k}
  & \text{``\emph{no two queens per diagonale up}''} \\
\wedge & \bigwedge\limits_{i=1}^{n-1} \bigwedge\limits_{j=2}^{n} D_{i,j} \to \hspace*{-1cm}
  \bigwedge\limits_{k = 1 \atop \text{s.t. } i+k \le n \text{ and } j-k \ge 1}^\infty \hspace*{-1cm}\neg D_{i+k,j-k}
  & \text{``\emph{no two queens per diagonale down}''} \\
\end{align*}
The problem of finding a model for each instance of $\varphi_n$ can be specified as a \DiMo program as follows.
\begin{verbatim}
SATISFIABLE NQueens(n)
PROPOSITIONS D
PARAMETERS n: {1,..}
FORMULAS
  NQueens(n) = AtLeastOneInEachRow(n)
             & AtMostOneInEachRow(n)
             & AtMostOneInEachColumn(n)
             & AtMostOneInEachDiagUp(n)
             & AtMostOneInEachDiagDown(n)

  AtLeastOneInEachRow(n)     =
    FORALL i: {1,..,n}. FORSOME j: {1,..,n}. D(i,j)

  AtMostOneInEachRow(n)      =
    FORALL i: {1,..,n}. FORALL j: {1,..,n-1}.
      D(i,j) -> FORALL k: {j+1,..,n}. -D(i,k)

  AtMostOneInEachColumn(n)   =
    FORALL i: {1,..,n-1}. FORALL j: {1,..,n}.
      D(i,j) -> FORALL k: {i+1,..,n}. -D(k,j)

  AtMostOneInEachDiagUp(n)   =
    FORALL i: {1,..,n-1}. FORALL j: {1,..,n-1}.
      D(i,j) -> FORALL k: {1,..,MIN {n-i,n-j}}. -D(i+k,j+k)

  AtMostOneInEachDiagDown(n) =
    FORALL i: {1,..,n-1}. FORALL j: {2,..,n}.
      D(i,j) -> FORALL k: {1,..,MIN {n-i,j-1}}. -D(i+k,j-k)
\end{verbatim}
Testing this problem with the \DiMo tool reveals solutions in terms of propositional variable assignments from which the placement of queens on the
chess boards of respective sizes can immediately be derived.
\begin{verbatim}
[~] dimo.native examples/nQueens.dm
Instance n=1 ................................... satisfiable.
  Satisfying assignment: D(1,1)
Instance n=2 ................................... unsatisfiable.
Instance n=3 ................................... unsatisfiable.
Instance n=4 ................................... satisfiable.
  Satisfying assignment: -D(1,1), -D(1,2), D(1,3), -D(1,4), D(2,1), -D(2,2), -D(2,3),
  -D(2,4), -D(3,1), -D(3,2), -D(3,3), D(3,4), -D(4,1), D(4,2), -D(4,3), -D(4,4)
...
\end{verbatim}
The output shows that the \DiMo tool has chosen the standard enumeration $n = 1,2,\ldots$ for the parameter \texttt{n}, instantiated the formulas scheme for
each instance of this enumeration and checked each of them for satisfiability subsequently. For $n = 2$ and $n = 3$ there is no solution to the $n$-queens
problem as one can easily check. Consequently, these instances are reported as being unsatisfiable. On the other hand, the instances $n=1,4,5,\ldots$ are
satisfiable, and a propositional model is found. It is easy to read off a solution to the $n$-queens problem from the assignment satisfying the $n$-th formula,
given the interpretation of the propositions $D_{i,j}$ mentioned above.

\subsection{A Simple Combinatorial Problem}

As a second example we consider the simple combinatorial problem of choosing exactly $m$ out of $n$ items. This can equally be modelled as the problem
of finding some or all models of a propositional formula $\varphi_{n,m}$ with $n \ge 1$ and $0 \le m \le n$. We use propositions $A_i$ to denote that
the $i$-th element is chosen. The straight-forward scheme
\begin{displaymath}
\bigvee\limits_{I \subseteq \{1,\ldots,n\} \atop |C| = m} (\bigwedge\limits_{i \in I} A_i) \wedge \hspace*{-5mm} \bigwedge\limits_{i \in \{1,\ldots,n\} \setminus I} \hspace*{-5mm} \neg A_i)
\end{displaymath}
cannot be written down as such in the \DiMo language because variables for sets of natural numbers are not supported (yet). However, note that this
is a formula of size $\mathcal{O}(n \cdot \binom{n}{m}) = \mathcal{O}(n^{m+1})$, and there is a much shorter way of specifying this which uses formulas
of size $\mathcal{O}(n^2)$ only. The trick is to use auxiliary propositions $B_{i,j}$ to abbreviate the fact that at least $j$ out of the first $i$
elements have chosen, or equivalently, at least $j$ of the $A_1,\ldots,A_i$ need to be set to true. Consider
\begin{align*}
\varphi_{n,m} := &B_{n,m}  & \text{``\emph{at least m out of (the first) n are chosen''}} \\
\wedge &\bigwedge\limits_{i=1}^n \bigwedge\limits_{j=1}^m B_{i,j} \to & \text{``\emph{if j of i are chosen then}} \\
&\hspace*{2.4cm} A_i \wedge B_{i-1,j-1} & \text{\emph{the i-th is chosen and j-1 of i-1 are chosen}} \\
&\hspace*{2cm}\vee B_{i-1,j} &\text{\emph{or j of i-1 are chosen}''} \\
\wedge &\bigwedge\limits_{j=1}^m \neg B_{0,j} & \text{``\emph{it is impossible to choose j from 0 elements}''}
\end{align*}
Using the same principle one can also demand that at the same time \emph{at most} $m$ out of $n$ are chosen. Note that this is the case if and only if
\emph{at least} $n-m$ are \emph{not chosen}. Based on this, the following \DiMo program specifies the problem of choosing exactly $m$ out $n$ elements
represented by propositions $A_i$. The auxiliary propositions $B_{i,j}$ are hidden away from output by not listing them in the \texttt{PROPOSITIONS}
section.
\begin{verbatim}
MODELS       ExactlyMofN(n,m)
PROPOSITIONS A
PARAMETERS   n : {1,..}, m : NAT WITH m <= n
FORMULAS

  ExactlyMofN(n,m) = AtLeastMChosen(n,m) & AtMostMChosen(n,m)

  AtLeastMChosen(n,m) = B(n,m) & BsWellBehaved(n,m) & BsEndOk(m)
  BsWellBehaved(n,m)  = FORALL i : {1,..,n}. FORALL j: {1,..,m}.
                          B(i,j) -> A(i) & B(i-1,j-1) | B(i-1,j)
  BsEndOk(m)          = FORALL j : {1,..,m}. -B(0,j)

  AtMostMChosen(n,m) = AtLeastNminusMNotChosen(n,n-m)
  AtLeastNminusMNotChosen(n,m) = N(n,m) & NsWellBehaved(n,m) & NsEndOk(m)
  NsWellBehaved(n,m) = FORALL i : {1,..,n}. FORALL j: {1,..,m}.
                          N(i,j) -> -A(i) & N(i-1,j-1) | N(i-1,j)
  NsEndOk(m)         = FORALL j : {1,..,m}. -N(0,j)
\end{verbatim}
Note that formulas constraining the propositions \texttt{N(i,j)} are copied verbatim from those for the \texttt{B(i,j)}. It is not (yet) possible to
re-use such code because only integer variables can be used as parameters, not propositions themselves.

Running the \DiMo tool on this program results in finding all possibilities to choose $m$ out of $n$ elements, represented by propositional variable
assignments, for some enumeration of the parameters $n$ and $m$.
\begin{verbatim}
[~] dimo.native examples/exactlyMofN.dm
Instance m=0, n=1 ..............................
  Found model -A(1)
1 model found.
Instance m=0, n=2 ..............................
  Found model -A(1), -A(2)
1 model found.
Instance m=1, n=1 ..............................
  Found model A(1)
1 model found.
Instance m=0, n=3 ..............................
  Found model -A(1), -A(2), -A(3)
1 model found.
Instance m=1, n=2 ..............................
  Found model A(1), -A(2)
  Found model -A(1), A(2)
2 models found.
Instance m=0, n=4 ..............................
  Found model -A(1), -A(2), -A(3), -A(4)
1 model found.
Instance m=1, n=3 ..............................
  Found model A(1), -A(2), -A(3)
  Found model -A(1), A(2), -A(3)
  Found model -A(1), -A(2), A(3)
3 models found.
Instance m=2, n=2 ..............................
  Found model A(1), A(2)
1 model found.
Instance m=0, n=5 ..............................
  Found model -A(1), -A(2), -A(3), -A(4), -A(5)
1 model found.
...
\end{verbatim}
The chosen enumeration of all pairs of parameters $n,m$ such that $n \ge 1$, and $0 \le m \le n$ is the standard ``diagonale'' $(1,0),(2,0),(1,1),(3,0),(2,1),(4,0),\ldots$.
Here, for each such instance \DiMo finds all possibilities to choose $m$ out of $n$ elements, represented by a propositional variable assignment in the variables $A_i$.

\appendix

\section{The \DiMo Tool}

\subsection{License}
As of version 0.2.1, \DiMo is available via GitHub under the BSD-3-Clauses licence.

\subsection{Installation}

The \DiMo testing tool is written in OCaml using version 4.07.0. Lower version may work as well. The simplest way to use the tool is to install the OCaml package manager
\texttt{Opam}\footnote{\url{https://opam.ocaml.org/}}. Make sure you use version 2 of \texttt{Opam}. For correct functionality, version 0.4 of the Opam package
\texttt{ocaml-sat-solvers} is needed which is not installed with previous versions of Opam.

Opam then gives a simple way to install the OCaml compiler and runtime environment. To use the precompiled byte code version this should suffice. To compile a native
version of the \DiMo tool one needs additional components that can be installed via \texttt{Opam}. See the file \texttt{README} for details.

\section{Syntax of the \DiMo Language}

The syntax of the \DiMo input language is given by the following grammar.
\begin{align*}
\nonterm{Main} ::=\ & \nonterm{Problem} \optional{\term{PROPOSITIONS} \nonterm{Props}}\
                                         \optional{\term{PARAMETERS} \nonterm{Params}}\
                                         \optional{\term{FORMULAS} \nonterm{Defs}} \\
\nonterm{Problem}\ ::=\ & \term{SATISFIABLE} \nonterm{Formula} \\
                 \altn & \term{VALID} \nonterm{Formula} \\
                 \altn & \term{EQUIVALENT} \nonterm{Formula} \term{TO} \nonterm{Formula} \\
                 \altn & \term{MODELS} \nonterm{Formula} \\
\nonterm{Props} ::=\ & \epsilon \altn \nonterm{Ident} \Big(\term{,} \nonterm{Ident}\Big)^* \\
\nonterm{Ident} ::=\ & \enumset{\texttt{A},\ldots,\texttt{Z}}\enumset{\texttt{A},\ldots,\texttt{Z},\texttt{a}\ldots,\texttt{z},\texttt{0},\ldots,\texttt{9},\term{\_}}^*\enumset{\term{'}}^* \\
\nonterm{Params} ::=\ & \nonterm{Var} \term{:} \nonterm{Domain} \Big( \term{,} \nonterm{Var} \term{:} \nonterm{Domain} \Big)^*
                           \optional{\term{WITH} \nonterm{Constr}} \\
\nonterm{Var} ::=\ & \enumset{\texttt{a},\ldots,\texttt{z}}\enumset{\texttt{A},\ldots,\texttt{Z},\texttt{a}\ldots,\texttt{z},\texttt{0},\ldots,\texttt{9},\term{\_}}^*\enumset{\term{'}}^* \\
\nonterm{Domain} ::=\ & \term{Nat} \\
                \altn & \term{\{} \nonterm{Number} \term{,} \optional{\nonterm{Number} \term{,}} \term{..}
                                         \optional{\term{,} \nonterm{Number}} \term{\}} \\
                \altn & \term{\{} \nonterm{Number} \group{\term{,} \nonterm{Number}}^* \term{\}} \\
\nonterm{Number} ::=\ & \enumset{\texttt{1},\ldots,\texttt{9}}\enumset{\texttt{0},\ldots,\texttt{9}}^* \\
\nonterm{Constr} ::=\ & \nonterm{Var} \nonterm{Cmp} \nonterm{Var} \group{\term{,} \nonterm{Var} \nonterm{Cmp} \nonterm{Var}}^* \\
\nonterm{Cmp} ::=\ & \term{=} \altn \term{<=} \altn \term{>=} \altn \term{<} \altn \term{>} \altn \term{<>} \\
\nonterm{Defs} ::=\ & \epsilon \altn \nonterm{Pattern} \term{=} \nonterm{Formula} \group{\term{,} \nonterm{Pattern} \term{=} \nonterm{Formula}}^* \\
\nonterm{Pattern} ::=\ &\nonterm{Ident} \optional{\term{(} \nonterm{Atom} \group{\term{,} \nonterm{Atom}}^* \term{)}} \\
\nonterm{Atom} ::=\ &\nonterm{Var} \altn \nonterm{Number} \\
\nonterm{Formula} ::=\ & \term{True} \altn \term{False} \altn \nonterm{Pred} \\
                 \altn & \term{(} \nonterm{Formula} \term{)} \\
                 \altn & \term{-} \nonterm{Formula} \altn \nonterm{Formula} \nonterm{Junct} \nonterm{Formula} \\
                 \altn & \nonterm{GenJunct} \nonterm{Var} \term{:} \nonterm{FinSet} \term{.} \nonterm{Formula} \\
\nonterm{Junct} ::=\ & \term{\&} \altn \term{|} \altn \term{->} \altn \term{<->} \\
\nonterm{GenJunct} ::=\ & \term{FORALL} \altn \term{FORSOME} \\
\nonterm{Pred} ::=\ & \nonterm{Ident} \optional{\term{(} \nonterm{Term} \group{\term{,} \nonterm{Term}}^* \term{)}} \\
\nonterm{Term} ::=\ & \nonterm{Atom} \altn \term{(} \nonterm{Term} \term{)} \altn \nonterm{UnOp} \nonterm{Term} \altn \nonterm{Term} \nonterm{BinOp} \nonterm{Term} \altn \nonterm{AccOp} \nonterm{FinSet} \\
\nonterm{UnOp} ::=\ & \term{LOG} \altn \term{FLOG} \\
\nonterm{BinOp} ::=\ &\term{+} \altn \term{-} \altn \term{*} \altn \term{\textasciicircum} \altn \term{MOD} \\
\nonterm{AccOp} ::=\ &\term{MIN} \altn \term{MAX} \\
\nonterm{FinSet} ::=\ & \term{\{} \nonterm{Term} \term{,} \optional{\nonterm{Term} \term{,}} \term{..} \term{,} \nonterm{Term} \term{\}} \\
                \altn & \term{\{} \nonterm{Term} \group{\term{,} \nonterm{Term}}^* \term{\}} \\
                \altn & \nonterm{FinSet} \nonterm{SetOp} \nonterm{FinSet} \\
\nonterm{SetOp} ::=\ & \term{\&} \altn \term{|} \altn{-}
\end{align*}
A note regarding precedences: the \DiMo tool implements the standard precedence rules for Boolean operators, i.e.\ \texttt{A \& B | C} is parsed in the same way as
\texttt{(A \& B) | C}.

The precedence and associativity rules for the arithmetic operators are as follows: Addition, subtraction, multiplication and division are left-associative; exponentiation is
right-associative. This enumeration also reflects the increasing order of precedence amongst these operations.

\section{Version History}

%Bug fixes:
%\begin{itemize}
%\item
%\end{itemize}

\subsubsection*{Version 0.2.3 (21/06/2021)}

Bug fixes:
\begin{itemize}
\item Fixed throwing of \texttt{exception Invalid_argument("Bytes.create")} on instances with long (or many) parameter names.
\end{itemize}

\subsubsection*{Version 0.2.2 (01/07/2020)}

Feature changes:
\begin{itemize}
\item Output of Boolean constants has been changed to match input, now \texttt{True} and \texttt{False}
\item The format of variables and formulas has been extended to allow quote symbols in the end as in \texttt{x'} etc.
\end{itemize}

\subsubsection*{Version 0.2.1 (29/10/2019)}

Feature changes:
\begin{itemize}
\item \DiMo has moved to GitHub under the BSD-3-Clauses license.
\end{itemize}

\subsubsection*{Version 0.2.0 (10/09/2019)}

Bug fixes:
\begin{itemize}
\item The tokenizer did not recognise line breaks properly so that failure because of lexing errors resulted in error messages reporting the line and column number wrongly. Fixed.
\item Applying the LOG function to argument 0 does not result in a stack overflow anymore. Instead the program terminates with failure.
\end{itemize}
Feature changes:
\begin{itemize}
\item The \DiMo language has been extended with a function FLOG on terms that computes the rounded-off logarithm to base 2.
\item The standard precedence and associativity rules for the arithmetic operators have been implemented. The \DiMo language has been extended with a function FLOG on terms that computes the rounded-off logarithm to base 2.
\end{itemize}

\subsubsection*{Version 0.1.5 (03/07/2019)}

Bug fixes:
\begin{itemize}
\item Operator MAX was interpreted as MIN: fixed.
\end{itemize}

\subsubsection*{Version 0.1.4 (01/07/2019)}

Bug fixes:
\begin{itemize}
\item Command line parameters \texttt{--onlypos} and \texttt{--onlyneg} no longer ignored in checking validity problems.
\item Problem with non-atomic terms like \texttt{i+1} in set definitions, leading to program crashes with error ``\texttt{compare: invalid argument}'', fixed.
\item Problem with instantiation of formula schemes into negation normal form fixed.
\end{itemize}
Feature changes:
\begin{itemize}
\item Model enumeration problems now report the number of models that were found.
\end{itemize}

\subsubsection*{Version 0.1.2 (27/11/2018)}
Bug fixes:
\begin{itemize}
\item Faulty instantiation of formulas containing negation, generalised junctions (\texttt{FORALL}, \texttt{FORSOME}) and propositional constants (\texttt{True}, \texttt{False}) fixed.
\item Crash through array-out-of-bounds exception when specifying finite domains by enumeration of alle elements (e.g.\ \texttt{n:~\{1,2\}}) fixed.
\end{itemize}
Feature changes:
\begin{itemize}
\item Output in debug mode streamlined.
\item Added command-line parameters to suppress the printing of negative, resp.\ positive literals in models.
\end{itemize}

\subsubsection*{Version 0.1.1 (26/11/2018)}

Bug fixes:
\begin{itemize}
\item Problem with producing output for validity problems trying to show refuting assignments for valid rather than invalid formulas fixed.
\item Program crashes due to an error in function ``toCNF.negate'' caused by non-literal arguments fixed.
\end{itemize}

\bibliographystyle{plain}
\bibliography{../literature}
\end{document}