\mainsection{Run Time Subsystem}
\label{ch:vm}

This chapter describes the implementation of the
MPC Virtual Machine.
The virtual machine is driven by Bytecodes which
are produced by the MAMBA compiler (see later).
Of course you could compile Bytecodes from any compiler
if you wanted to write one with the correct backend.

The virtual machine structure resembles that of a
simple multi-core processor, and is a register-based
machine.
Each core corresponds to a seperate online thread
of execution; so from now on we refer to these ``cores''
as threads.
Each thread has a seperate set of registers, as
well as a stack for {\em integer} values.
To allow the saving of state, or the transfer of data
between threads there is a global memory.
This global memory (or at least the first $2^{20}$
values) are saved whenever the SCALE system gracefully
shuts down.
The loading of this saved memory into a future run of the
system is controlled by the command line arguments
passed to the \verb+Player.x+ program.
The design is deliberately kept sparse to ensure a fast, low-level
implementation, whilst more complex optimization decisions are intended
to be handled at a higher level.

\subsection{Overview}

The core of the virtual machine is a set of threads, which
execute sequences of instructions encoded in a bytecode format.
Files of bytecode instructions are referred to as \emph{tapes},
and each thread processes a single tape at a time.
Each of these execution threads has a pairwise point-to-point
communication channels with the associated threads in all
other players' runtime environments.
These communication channels, like all communication channels
in SCALE, are secured via TLS.
The threads actually have two channels to the correspond
thread in the other parties; we call these different channels
``connections''.
For the online thread ``connection'' zero is used for standard
opening of shared data, whereas ``connection'' one is used for
private input and output. This is to avoid conflicts beween
the two (for example a \verb+PRIVATE_OUTPUT+ coming between
a \verb+STARTOPEN+ and a \verb+STOPOPEN+.
Each online thread is supported by four other threads
performing the offline phase, each again with pairwise
TLS secured point-to-point channels. Currently the offline
threads only communicate on ``connection'' zero.

In the case of Full Threshold secret sharing another set of
threads act as a factory for FHE ciphertexts. Actively secure
production of such ciphertexts is expensive, requiring complex
zero-knowledge proofs (see Section \ref{sec:fhe}). Thus
the FHE-Factory threads locates this production into a
single location. The number of FHE Factory threads can be
controlled at run-time by the user.

In addition to bytecode files, each program to be run must
have a \emph{schedule}. This is a file detailing the execution
order of the tapes, and which tapes are to be run in parallel.
There is no limit to the number of concurrent tapes specified in a schedule,
but in practice one will be restricted by the number of cores.
The schedule file allows you to schedule concurrent threads
of execution, it also defines the maximum number of threads
a given run-time system will support. It also defines
the specific bytecode sequences which are pre-loaded
into the system.
One can also programmatically control execution of new
threads using the byte-code instructions \verb+RUN_TAPE+ and \verb+JOIN_TAPE+
(see below for details).
The schedule is run by the \emph{control thread}.
This thread takes the tapes to be executed at a
given step in the schedule, passes them to the execution
threads, and waits for the threads to
finish their execution before proceeding to the next stage of
the schedule.

Communication between threads is handled by a global
\emph{main memory}, which all threads have access to.
To avoid unnecessary stalls there is no locking mechanism provided to
the memory. So if two simultaneously running threads
execute a read and a write, or two writes, to the same
memory location then the result is undefined since it is
not specified as to which order the instructions
will be performed in.
Memory comes in both clear and secret forms.

Each execution thread also has its own local clear and secret
registers, to hold temporary variables.
To avoid confusion with the main memory
The values of registers are not assumed to be maintained
between an execution thread running one tape and
the next tape, so all passing of values
between two sequential tape executions must be done
by reading and writing to the virtual machine's main memory.
This holds even if the two consequtive bytecode
sequences run  on the same ``core''.

\subsection{Bytecode instructions}

The design of the Bytecode instructions within a tape are influenced
by the RISC design strategy, coming in only a few basic
types and mostly taking between one and three
operands. The virtual machine also supports a limited form of
SIMD instructions within a thread, whereby a single instruction is used to
perform the same operation on a fixed size set of registers.
These vectorized instructions are not executed in parallel
as in traditional SIMD architectures, but exist to provide a compact way of
executing multiple instructions within a thread, saving on memory
and code size.

A complete set of byte codes and descriptions is
given in the html file in
\begin{center}
   \verb+$(HOME)/Documentation/Compiler_Documentation/index.html+
\end{center}
under the class \verb+instructions+.
Each encoded instruction begins with 32 bits reserved for the opcode.
The right-most nine bits specify the instruction to be executed\footnote{The choice of nine is to enable extension of the system later, as eight is probably going
to be too small.}.
The remaining 23 bits are used for vector instructions, specifying the
size of the vector of registers being operated on.
The remainder of an instruction encoding consists of 4-byte operands, which
correspond to either indices of registers or immediate integer values.
\begin{itemize}
\item Note, vector instructions are not listed in the \verb+html+ document above.
They have the same name as standard instructions, prefixed by `V',
with the opcode created as described above.
\end{itemize}
The basic syntax used in the above html file is as follows:
\begin{itemize}
\item `c[w]': clear register, with the optional suffix `w' if the register is
written to.
\item `s[w]': secret register, as above.
\item `r[w]': regint register, as above.
\item `i'   : 32-bit integer signed immediate value.
\item `int' : 64-bit integer unsigned immediate value.
\item `p'   : 32-bit number representing a player index.
\item `str' : A four byte string.
\end{itemize}
Memory comes in three varieties \verb+sint+, \verb+cint+, and
\verb+regint+; denoted by \verb+S[i]+, \verb+C[i]+ and \verb+R[i]+.

\subsection{Load, Store and Memory Instructions}
Being a RISC design the main operations are load/store
operations, moving operations, and memory operations.
Each type of instructions comes in either clear data,
sharedata, or integer data formats.
The integer data is pure integer arithemetic, say
for controling loops, whereas clear data is integer
arithmetic modulo $p$.
For the clear values all values represented as integers
in the range $(-\frac{p-1}{2}, \dots, \frac{p-1}{2}]$.
The integer stack is again mainly intended for loop
control.

\subsubsection{Basic Load/Store/Move Instructions:}
\verb+LDI+,
\verb+LDI+,
\verb+LDSI+,
\verb+LDINT+,
\verb+MOVC+,
\verb+MOVS+,
\verb+MOVINT+.

\subsubsection{Loading to/from Memory:}
 \verb+LDMC+,
 \verb+LDMS+,
 \verb+STMC+,
 \verb+STMS+,
 \verb+LDMCI+,
 \verb+LDMSI+,
 \verb+STMCI+,
 \verb+STMSI+,
 \verb+LDMINT+,
 \verb+STMINT+,
 \verb+LDMINTI+,
 \verb+STMINTI+.

\subsubsection{Accessing the integer stack:}
\verb+PUSHINT+, \verb+POPINT+.

\subsubsection{Data Conversion}
To convert from mod $p$ to integer values and
back we provide the conversion routines.
\verb+CONVINT+, \verb+CONVMODP+.
These are needed as the internal mod $p$ representation
of clear data is in Montgomery representation.

\subsection{Preprocessing loading instructions}
The instructions for loading data from the preprocessing phase
are denoted \verb+TRIPLE+, \verb+SQUARE+, \verb+BIT+,
and they take as argument three, two, and one secret registers
respectively.
The associated data is loaded from the concurrently running
offline threads and loaded into the registers given as arguments.

\subsection{Open instructions}

The process of opening secret values is covered by two instructions.
The \verb+STARTOPEN+ instruction takes as input a set of $m$
shared registers, and \verb+STOPOPEN+ an associated set of $m$
clear registers, where $m$ can be an arbitrary integer.
This initiates the protocol to reveal the $m$ secret shared register values,
storing the result in the specified clear registers. The reason for
splitting this into two instructions is so that local, independent
operations may be placed between a \verb+STARTOPEN+ and \verb+STOPOPEN+,
to be executed whilst waiting for the communication to finish.

There is no limit on the number of operands to these instructions,
allowing for communication to be batched into a single pair of
instructions to save on network latency. However, note that when
the \texttt{RunOpenCheck} function in the C++ class \texttt{Open\_Protocol}
is used to check MACs/Hashes then this can stall when the network buffer fills
up, and hang indefinitely.
On our test machines this happens when opening around 10000 elements
at once, so care must be taken to avoid this when compiling or writing
bytecode (the Python compiler could automatically detect and avoid
this).

\subsection{Threading tools}
Various special instructions are provided to ease the workload when writing
programs that use multiple tapes.
\begin{itemize}
\item The \verb+LDTN+ instruction loads the current thread number into
a clear register.
\item The \verb+LDARG+ instruction loads an argument that was passed
when the current thread was called.
Thread arguments are optional and consist of a single integer,
which is specified in the schedule file that determines the execution
order of tapes, or via the instruction \verb+RUN_TAPE+.
\item The \verb+STARG+ allows the current tape to change its
existing argument.
\item To run a specified pre-loaded tape in a given thread, with
a given argument the \verb+RUN_TAPE+ command is executed.
\item To wait until a specified thread has finished one executes
the \verb+JOIN_TAPE+ function.
\end{itemize}

\subsection{Basic Arithmetic}
This is captured by the following instructions,
with different instructions being able to be operated
on clear, shared and integer types.
    \verb+ADDC+,
    \verb+ADDS+,
    \verb+ADDM+,
    \verb+ADDCI+,
    \verb+ADDSI+,
    \verb+ADDINT+,
    \verb+SUBC+,
    \verb+SUBS+,
    \verb+SUBML+,
    \verb+SUBMR+,
    \verb+SUBCI+,
    \verb+SUBSI+,
    \verb+SUBCFI+,
    \verb+SUBSFI+,
    \verb+SUBINT+,
    \verb+MULC+,
    \verb+MULM+,
    \verb+MULCI+,
    \verb+MULSI+,
and
    \verb+MULINT+.

\subsection{Advanced Arithmetic}
More elaborate algorithms can clearly be executed directly on
clear or integer values; without the need for complex
protocols. These include logical, shift and number
theoretic functions.
    \verb+ANDC+,
    \verb+XORC+,
    \verb+ORC+,
    \verb+ANDCI+,
    \verb+XORCI+,
    \verb+ORCI+,
    \verb+NOTC+,
    \verb+SHLC+,
    \verb+SHRC+,
    \verb+SHLCI+,
    \verb+SHRCI+,
    \verb+DIVC+,
    \verb+DIVCI+,
    \verb+DIVINT+,
    \verb+MODC+,
    \verb+MODCI+.
    \verb+LEGENDREC+,
and
    \verb+DIGESTC+.

\subsection{Debuging Output}
To enable debugging we provide simple commands to send
debugging information to the \verb+Input_Output+ class.
These bytecodes are
\begin{verbatim}
    PRINTINT,           PRINTMEM,          PRINTREG,           PRINTREGPLAIN,
    PRINTCHR,           PRINTSTR,          PRINTCHRINT,        PRINTSTRINT,
    PRINTFLOATPLAIN,    PRINTFIXPLAIN.
\end{verbatim}

\subsection{Data input and output}
This is entirely dealt with in the later Chapter on IO.
The associated bytecodes are
\begin{verbatim}
             OUTPUT_CLEAR,           INPUT_CLEAR,
             OUTPUT_SHARE,           INPUT_SHARE,
             OUTPUT_INT,             INPUT_INT,
             PRIVATE_INPUT,          PRIVATE_OUTPUT,
             OPEN_CHAN,              CLOSE_CHAN
\end{verbatim}

\subsection{Branching}
Branching is supported by the following
instructions
 \verb+JMP+,
    \verb+JMPNZ+,
    \verb+JMPEQZ+,
    \verb+EQZINT+,
    \verb+LTZINT+,
    \verb+LTINT+,
    \verb+GTINT+,
    \verb+EQINT+,
and
    \verb+JMPI+.

\subsection{Other Commands}
The following byte codes are for fine tuning the machine
\begin{itemize}
\item \verb+REQBL+ this is output by the compiler to signal that
the tape requires a minimal bit length. This forces the runtime
to check the prime $p$ satisfies this constraint.
\item \verb+CRASH+ this enables the program to create a crash,
if the programmer is feeling particularly destuctive.
\item \verb+RAND+ this loads a pseudo-random value into a
clear register. This is not a true random number, as all
parties output the same random number at this point.
\item \verb+RESTART+ which restarts the online runtime.
See Section \ref{sec:restart} for how this intended to be used.
\item \verb+CLEAR_MEMORY+ which clears the current memory.
See Section \ref{sec:restart} for more details on how this is used.
\item \verb+CLEAR_REGISTERS+ which clears the registers of this processor core (i.e. thread).
See Section \ref{sec:restart} for more details on how this is used.
\item \verb+START_TIMER+ and \verb+STOP_TIMER+ are used to time different
parts of the code. There are 100 times available in the system;
each is initialized to zero at the start of the machine running.
The operation \verb+START_TIMER+ re-initializes a specified timer,
whereas \verb+STOP_TIMER+ prints the elapsed time since the last
initialization (it does not actually reinitialise/stop the timer itself).
These are accessed from MAMBA via the functions
\verb+start_timer(n)+ and \verb+stop_timer(n)+.
The timers use an internal class to measure time command in the C runtime.
\end{itemize}


\section{Reduce Attribute}\label{spell:reduceAbility}
\textbf{Cost:} 500 CP\\
\textbf{Requirements:}~\nameref{rune:nil} I, one other level I rune (see below)\\
\textbf{Spell, Active, Repeatable, Source(200 Gold), Memory}\\
You cast a spell for 15 Mana and 6 AP and then target a creature that you can see.
If the creature isn't willing, it can try to resist you.
Make an intellect check contested by the target's willpower and intellect check.
If you win or if the creature is willing, one of its attribute values of your choice is reduced by 2 for 1 minute.
You can not temporarily reduce an attribute to a value of 0 or lower with this spell. \\
When using this spell, the type of attribute you can reduce depends on the runes that you know.
In order to learn the spell, you only need to know one of these runes.\\
\begin{itemize}
    \item Strength: "\nameref{rune:heat} I"
    \item Vitality: "\nameref{rune:earth} I"
    \item Agility: "\nameref{rune:water} I"
    \item Dexterity: "\nameref{rune:air} I"
    \item Intellect: "\nameref{rune:nil} I"
    \item Perception: "\nameref{rune:light} I"
    \item Empathy: "\nameref{rune:dark} I"
\end{itemize}
Level Progression:\\
II: 1,000 CP, reduce by 3 for 25 Mana\\
III: 2,000 CP, reduce by 4 for 50 Mana\\
IV: 5,000 CP, reduce by 5 for 80 Mana\\
V: 10,000 CP, reduce by 6 for 120 Mana\\


%\newpage
%\setcounter{page}{1}
%\setcounter{section}{0}

\input{header}

\begin{document}

\begin{center}
{\LARGE Crypto Lab -- One-Way Hash Function and MAC}
\end{center}

\copyrightnotice

\newcounter{task}
\setcounter{task}{1}
\newcommand{\tasks} {\bf {\noindent (\arabic{task})} \addtocounter{task}{1} \,}

\section{Overview}

The learning objective of this lab is for students to get familiar with
one-way hash functions and Message Authentication Code (MAC). After
finishing the lab, in addition to gaining a deeper undertanding
of the concepts, students should be able to
use tools and
write programs to generate one-way hash value and MAC for
a given message.

\section{Lab Environment}
The lab is started from the Labtainer working
directory on your Docker-enabled host, e.g., a Linux VM.
From there, issue the command:
\begin{verbatim}
    labtainer onewayhash
\end{verbatim}
The resulting virtual terminals will include a display of
a bash shell.  The openssl package
and other software described below are pre-installed
on the system.

\section{Lab Tasks}

\subsection{Task 1: Generating Message Digest and MAC}

In this task, we will play with various one-way hash algorithms.
You can use the following {\tt openssl dgst}
command to generate the hash value for a file. To see the manpages, you can
type {\tt man openssl} and {\tt man dgst}.

\begin{Verbatim}[frame=single]
  % openssl dgst dgsttype filename
\end{Verbatim}

Please replace the {\tt dgsttype} with a specific one-way hash algorithm,
such as {\tt -md5}, {\tt -sha1}, {\tt -sha256}, etc.
And replace {\tt filename} with {\tt filetodigest.txt}, which is in your home directory.
In this task, you should try at least 3 different algorithms,
and describe your observations.
You can find the supported one-way hash algorithms
by typing {\tt "openssl dgst -h"}  NOTE: the list of algorithms included in the manpages is not correct.

\subsection{Task 2: Keyed Hash and HMAC}

In this task, we would like to generate a keyed hash (i.e. MAC)
for a file. We can use the {\tt -hmac} option (this option
is currently undocumented,
but it is supported by {\tt openssl}). The following example
generates a keyed hash for a file using the HMAC-MD5
algorithm. The string following the {\tt -hmac} option
is the key.
\begin{Verbatim}[frame=single]
 % openssl dgst -md5 -hmac "abcdefg" filename
\end{Verbatim}

Please generate a keyed hash using HMAC-MD5, HMAC-SHA256, and
HMAC-SHA1 for any file that you choose. Please try several
keys with different length. Do we have to use a key
with a fixed size in HMAC? If so, what is the key size? If
not, why?

\subsection{Task 3: The Randomness of One-way Hash}

To understand the properties of one-way hash functions, we would like to
do the following exercise for MD5 and SHA256:

\begin{enumerate}
\item Create a text file named "edit-this-file.txt" of any length.
\item Generate the hash value  $H_1$ for this file using a specific hash algorithm.
\item Flip one bit of the input file.
      You can achieve this modification using {\tt hexedit}.
\item Generate the hash value $H_2$ for the modified file.
\item Please observe whether $H_1$ and $H_2$ are similar or not. Please describe
      your observations in the lab report. You can write a short program to count
      how many bits are the same between $H_1$ and $H_2$.

\end{enumerate}

\subsection{Task 4: One-Way Property versus Collision-Free Property}

In this task, we will investigate the difference between
hash function's two perperties: one-way property versus collision-free property.
We will use the brute-force method to see how long it takes to break
each of these properties. Instead of using {\tt openssl}'s command-line tools,
you are required to write our own C programs to invoke the
message digest functions in {\tt openssl}'s crypto library.
A sample code can be found from
\url{http://www.openssl.org/docs/crypto/EVP_DigestInit.html}. Please
get familiar with this sample code.

Since most of the hash functions are quite strong against the brute-force
attack on those two properties, it will take us years to break them
using the brute-force method. To make the task feasible, we reduce
the length of the hash value to 24 bits. We can use any one-way
hash function, but we only use the first 24 bits of the hash value
in this task. Namely, we are using a modified one-way hash function.
Please design an experiment to find out the following:

\begin{enumerate}
\item How many trials it will take you to break the one-way
property using the brute-force method? You should repeat your
experiment for multiple times, and report your average number
of trials.
\item How many trials it will take you to break the collision-free
property using the brute-force method? Similarly, you should
report the average.
\item Based on your observation, which property is easier to
break using the brute-force method?
\item (10 Bonus Points) Can you explain the difference in your
observation mathematically?
\end{enumerate}

\section{Submission}
When the lab is completed, or you'd like to stop working for a while, run
\begin{verbatim}
    stoplab onewayhash
\end{verbatim}

from the host Labtainer working directory.  You can always restart the
Labtainer to continue your work.  When the Labtainer is stopped, a
zip file is created and copied to a location displayed by the stoplab
command.  When the lab is completed, send that zip file to the instructor.

You need to submit a detailed lab report to describe what you have
done and what you have observed; you also need to provide explanation
to the observations that are interesting or surprising. In your report,
you need to answer all the questions listed in this lab.

\end{document}


\lab{The Standard Library}{The Standard Library}
\label{lab:Standard Library}
\objective{Python is designed to make it easy to implement complex tasks with little code.
To that end, every Python distribution includes several built-in functions for accomplishing common tasks.
In addition, Python is designed to import and reuse code written by others.
A Python file with code that can be imported is called a \emph{module}.
All Python distributions include a collection of modules for accomplishing a variety of tasks, collectively called the \emph{Python Standard Library}.
In this lab we explore some built-in functions, learn how to create, import, and use modules, and become familiar with the standard library.}

\section*{Built-in Functions} % ===============================================

Python has several built-in functions that may be used at any time.
IPython's object introspection feature makes it easy to learn about these functions: start IPython from the command line and use \li{?} to bring up technical details on each function.
% Table \ref{table:builtin} lists a few built-in functions.

\begin{lstlisting}
<g<In [1]:>g> min?
<<Docstring:
min(iterable, *[, default=obj, key=func]) -> value
min(arg1, arg2, *args, *[, key=func]) -> value

With a single iterable argument, return its smallest item. The
default keyword-only argument specifies an object to return if
the provided iterable is empty.
With two or more arguments, return the smallest argument.
Type:      builtin_function_or_method>>

<g<In [2]:>g> len?
<<Signature: len(obj, /)
Docstring: Return the number of items in a container.
Type:      builtin_function_or_method>>
\end{lstlisting}

\begin{table}[H]
\begin{tabular}{r|l}
Function & Returns \\ \hline
\li{abs()} & The absolute value of a real number, or the magnitude\\
& of a complex number.\\
\li{min()} & The smallest element of a single iterable, or the smallest\\
& of several arguments. Strings are compared  based on\\
& lexicographical order: numerical characters first, then\\
& upper-case letters, then lower-case letters.\\
\li{max()} & The largest element of a single iterable, or the largest\\
& of several arguments.\\
\li{len()} & The number of items of a sequence or collection.\\
\li{round()} & A float rounded to a given precision in decimal digits.\\
\li{sum()} & The sum of a sequence of numbers.\\
\end{tabular}
\caption{Common built-in functions for numerical calculations.}
\label{table:builtin}
\end{table}

\begin{lstlisting}
# abs() can be used with real or complex numbers.
>>> print(abs(-7), abs(3 + 4j))
7 5.0

# min() and max() can be used on a list, string, or several arguments.
# String characters are ordered lexicographically.
>>> print(min([4, 2, 6]), min("aXbYcZ"), min('1', 'a', 'A'))
2 X 1
>>> print(max([4, 2, 6]), max("aXbYcZ"), max('1', 'a', 'A'))
6 c a

# len() can be used on a string, list, set, dict, tuple, or other iterable.
>>> print(len([2, 7, 1]), len("abcdef"), len({1, 'a', 'a'}))
3 6 2

# sum() can be used on iterables containing numbers, but not strings.
>>> my_list = [1, 2, 3]
>>> my_tuple = (4, 5, 6)
>>> my_set = {7, 8, 9}
>>> sum(my_list) + sum(my_tuple) + sum(my_set)
45
>>> sum([min(my_list), max(my_tuple), len(my_set)])
10

# round() is particularly useful for formatting data to be printed.
>>> round(3.14159265358979323, 2)
3.14
\end{lstlisting}

See \url{https://docs.python.org/3/library/functions.html} for more detailed documentation on all of Python's built-in functions.

\begin{problem} % Problem 1: using built-in methods with lists.
Write a function that accepts a list $L$ and returns the minimum, maximum, and average of the entries of $L$ (in that order).
Can you implement this function in a single line?
\end{problem}

\section*{Namespaces} % =======================================================

Whenever a Python object---a number, data structure, function, or other entity---is created, it is stored somewhere in computer memory.
A \emph{name} (or variable) is a reference to a Python object, and a \emph{namespace} is a dictionary that maps names to Python objects.

\begin{lstlisting}
# The number 4 is the object, 'number_of_students' is the name.
>>> number_of_sudents = 4

# The list is the object, and 'beatles' is the name.
>>> beatles = ["John", "Paul", "George", "Ringo"]

# Python statements defining a function also form an object.
# The name for this function is 'add_numbers'.
>>> def add_numbers(a, b):
...     return a + b
...
\end{lstlisting}

A single equals sign assigns a name to an object.
If a name is assigned to another name, that new name refers to the same object as the original name.

\begin{lstlisting}
>>> beatles = ["John", "Paul", "George", "Ringo"]
>>> band_members = beatles             # Assign a new name to the list.
>>> print(band_members)
<<['John', 'Paul', 'George', 'Ringo']>>
\end{lstlisting}

To see all of the names in the current namespace, use the built-in function \li{dir()}.
To delete a name from the namespace, use the \li{del} keyword (\textbf{with caution!}).
% Objects are not actually deleted from memory until there are no names referring to it.

\begin{lstlisting}
# Add 'stem' to the namespace.
>>> stem = ["Science", "Technology", "Engineering", "Mathematics"]
>>> dir()
<<['__annotations__', '__builtins__', '__doc__', '__loader__', '__name__',
 '__package__', '__spec__', 'stem']>>

# Remove 'stem' from the namespace.
>>> del stem
>>> "stem" in dir()
<<False>>
>>> print(stem)
<<Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'stem' is not defined>>
\end{lstlisting}

\begin{info}
Many programming languages distinguish between \emph{variables} and \emph{pointers}.
A pointer refers to a variable by storing the address in memory where the corresponding object is stored.
Python names are essentially pointers, and traditional pointer operations and cleanup are done automatically.
For example, Python automatically deletes objects in memory that have no names assigned to them (no pointers referring to them).
This feature is called \emph{garbage collection}.
% Understanding how Python handles memory access via names is important for implementing reference-based data structures, such as linked lists and trees.
\end{info}

\subsection*{Mutability} % ----------------------------------------------------

Every Python object type falls into one of two categories: a \emph{mutable} object, which may be altered at any time, or an \emph{immutable} object, which cannot be altered once created.
Attempting to change an immutable object creates a new object in memory.
If two names refer to the same mutable object, any changes to the object are reflected in both names since they still both refer to that same object.
On the other hand, if two names refer to the same immutable object and one of the values is ``changed,'' then one name will refer to the original object, and the other will refer to a new object in memory.

\begin{warn} % Extensive Mutability Warning.
Failing to correctly copy mutable objects can cause subtle problems.
For example, consider a dictionary that maps items to their base prices.
To make a similar dictionary that accounts for a small sales tax, we might try to make a copy by assigning a new name to the first dictionary.

\begin{lstlisting}
>>> holy = {"moly": 1.99, "hand_grenade": 3, "grail": 1975.41}
>>> tax_prices = holy               # Try to make a copy for processing.
>>> for item, price in tax_prices.items():
...     # Add a 7 percent tax, rounded to the nearest cent.
...     tax_prices[item] = round(1.07 * price, 2)
...
# Now the base prices have been updated to the total price.
>>> print(tax_prices)
<<{'moly': 2.13, 'hand_grenade': 3.21, 'grail': 2113.69}>>

# However, dictionaries are mutable, so 'holy' and 'tax_prices' actually
# refer to the same object. The original base prices have been lost.
>>> print(holy)
<<{'moly': 2.13, 'hand_grenade': 3.21, 'grail': 2113.69}>>
\end{lstlisting}

To avoid this problem, explicitly create a copy of the object by casting it as a new structure.
Changes made to the copy will not change the original object, since they are distinct objects in memory.
To fix the above code, replace the second line with the following:

\begin{lstlisting}
>>> tax_prices = dict(holy)
\end{lstlisting}
Then, after running the same procedure, the two dictionaries will be different.

\end{warn}

\begin{problem} % Problem 2: determine which Python types are immutable.
Determine which Python object types are mutable and which are immutable by repeating the following experiment for an \li{int}, \li{str}, \li{list}, \li{tuple}, and \li{set}.
\begin{enumerate}
    \item Create an object of the given type and assign a name to it.
    \item Assign a new name to the first name.
    \item Alter the object via only one of the names (for tuples, use \li{my_tuple += (1,)}).
    \item Check to see if the two names are equal.
    If they are, then changing one name also changes the other.
    Thus, both names refer to the same object and the object type is mutable.
    Otherwise, the names refer to different objects---meaning a new object was created in step 2---and therefore the object type is immutable.
\end{enumerate}
For example, the following experiment shows that \li{dict} is a mutable type.
\begin{lstlisting}
>>> dict_1 = {1: 'x', 2: 'b'}           # Create a dictionary.
>>> dict_2 = dict_1                     # Assign it a new name.
>>> dict_2[1] = 'a'                     # Change the 'new' dictionary.
>>> dict_1 == dict_2                    # Compare the two names.
<<True>>                                    # Both names changed!
\end{lstlisting}
Print a statement of your conclusions that clearly indicates which object types are mutable and which are immutable.
\end{problem}

% \begin{comment} % It's really that they have to be hashable...
\begin{warn} % Dictionary keys must be immutable.
Mutable objects cannot be put into Python sets or used as keys in Python dictionaries.
However, the values of a dictionary may be mutable or immutable.
\begin{lstlisting}
>>> a_dict = {"key": "value"}               # Dictionaries are mutable.
>>> broken = {1, 2, 3, a_dict, a_dict}      # Try putting a dict in a set.
<<Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: unhashable type: 'dict'>>

>>> okay = {1: 2, "3": a_dict}              # Try using a dict as a value.
\end{lstlisting}
\end{warn}
% \end{comment}

\section*{Modules} % ==========================================================

A \emph{module} is a Python file containing code that is meant to be used in some other setting, and not necessarily run directly.%
\footnote{Python files that are primarily meant to be executed, not imported, are often called \emph{scripts}.}
The \li{import} statement loads code from a specified Python file.
Importing a module containing some functions, classes, or other objects makes those functions, classes, or objects available for use by adding their names to the current namespace.

All import statements should occur at the top of the file, below the header but before any other code.
There are several ways to use \li{import}:
\begin{enumerate}

\item \li{import <module>} makes the specified module available under the alias of its own name.
% For example, the \li{math} module has a function called \li{sqrt()} that computes the square root of the input.
\begin{lstlisting}
>>> import math                 # The name 'math' now gives
>>> math.sqrt(2)                # access to the math module.
1.4142135623730951
\end{lstlisting}

\item \li{import <module> as <name>} creates an alias for an imported module. The alias is added to the current namespace, but the module name itself is not.

\begin{lstlisting}
>>> import numpy as np          # The name 'np' gives access to the numpy
>>> np.sqrt(2)                  # module, but the name 'numpy' does not.
1.4142135623730951
>>> numpy.sqrt(2)
<<Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'numpy' is not defined>>
\end{lstlisting}

\item \li{from <module> import <<<object>>>} loads the specified object into the namespace without loading anything else in the module or the module name itself.
This is used most often to access specific functions from a module.
The \li{as} statement can also be tacked on to create an alias.

\begin{lstlisting}
>>> from random import randint  # The name 'randint' gives access to the
>>> r = randint(0, 10000)       # randint() function, but the rest of
>>> random.seed(r)              # the random module is unavailable.
<<Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'random' is not defined>>
\end{lstlisting}
\end{enumerate}
%
In each case, the final word of the import statement is the name that is added to the namespace.

\subsection*{Running and Importing} % -----------------------------------------

Consider the following simple Python module, saved as \texttt{example1.py}.

\begin{lstlisting}
# example1.py

data = list(range(4))
def display():
    print("Data:", data)

if __name__ == "__main__":
    display()
    print("This file was executed from the command line or an interpreter.")
else:
    print("This file was imported.")
\end{lstlisting}

Executing the file from the command line executes the file line by line, including the code under the \li{if __name__ == "__main__"} clause.

\begin{lstlisting}
$ python example1.py
<<Data: [0, 1, 2, 3]
This file was executed from the command line or an interpreter.>>
\end{lstlisting}

Executing the file with IPython's special \li{<p<\%run>p>} command executes each line of the file and also adds the module's names to the current namespace.
\textbf{This is the quickest way to test individual functions via IPython}.

\begin{lstlisting}
<g<In [1]:>g> <p<%run>p> example1.py
<<Data: [0, 1, 2, 3]
This file was executed from the command line or an interpreter.>>

<g<In [2]:>g> display()
Data: [0, 1, 2, 3]
\end{lstlisting}

Importing the file also executes each line,\footnote{Try importing the \lif{this} or \lif{antigravity} modules.
Importing these modules actually executes some code.} but only adds the indicated alias to the namespace.
Also, code under the \li{if __name__ == "__main__"} clause is \textbf{not} executed when a file is imported.

\begin{lstlisting}
<g<In [1]:>g> import example1 as ex
<<This file was imported.>>

# The module's names are not directly available...
<g<In [2]:>g> display()
<<---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-2-795648993119> in <module>()
----> 1 display()

NameError: name 'display' is not defined>>

# ...unless accessed via the module's alias.
<g<In [3]:>g> ex.display()
Data: [0, 1, 2, 3]
\end{lstlisting}

\begin{problem} % Problem: create and use a simple module.
Create a module called \texttt{calculator.py}.
Write a function that returns the sum of two arguments and a function that returns the product of two arguments.
Also use \li{import} to add the \li{sqrt()} function from the \li{math} module to the namespace.
When this file is either run or imported, nothing should be executed.

In your solutions file, import your new custom module.
Write a function that accepts two numbers representing the lengths of the sides of a right triangle.
Using only the functions from \texttt{calculator.py}, calculate and return the length of the hypotenuse of the triangle.
\end{problem}

\begin{warn} % Use run in IPython instead of import.
If a module has been imported in IPython and the source code then changes, using \li{import} again does \textbf{not} refresh the name in the IPython namespace.
Use \li{run} instead to correctly refresh the namespace.
Consider this example where we test the function \li{sum_of_squares()}, saved in the file \texttt{example2.py}.

\begin{lstlisting}
# example2.py

def sum_of_squares(x):
    """Return the sum of the squares of all positive integers
    less than or equal to x.
    """
    return sum([i**2 for i in range(1,x)])
\end{lstlisting}

In IPython, run the file and test \li{sum_of_squares()}.

\begin{lstlisting}
# Run the file, adding the function sum_of_squares() to the namespace.
<g<In [1]:>g> <p<%run>p> example2

<g<In [2]:>g> sum_of_squares(3)
<r<Out[2]:>r> 5                           # Should be 14!
\end{lstlisting}

Since $1^2 + 2^2 + 3^2 = 14$, not $5$, something has gone wrong.
Modify the source file to correct the mistake, then run the file again in IPython.

\begin{lstlisting}
# example2.py

def sum_of_squares(x):
    """Return the sum of the squares of all positive integers
    less than or equal to x.
    """
    return sum([i**2 for i in range(1,x+1)])    # Include the final term.
\end{lstlisting}

\begin{lstlisting}
# Run the file again to refresh the namespace.
<g<In [3]:>g> <p<%run>p> example2

# Now sum_of_squares() is updated to the new, corrected version.
<g<In [4]:>g> sum_of_squares(3)
<r<Out[4]:>r> 14                          # It works!
\end{lstlisting}

Remember that running or importing a file executes any freestanding code snippets, but any code under an \li{if __name__ == "__main__"} clause will \textbf{only} be executed when the file is run (not when it is imported).
\end{warn}

\section*{The Python Standard Library} % ======================================

All Python distributions include a collection of modules for accomplishing a variety of common tasks, collectively called the \emph{Python standard library}.
Some commonly standard library modules are listed below, and the complete list is at \url{https://docs.python.org/3/library/}.

\begin{table}[H] % Some standard library modules.
\begin{tabular}{c|l}
Module & Description \\ \hline
\li{cmath} & Mathematical functions for complex numbers.\\
% \li{csv} & Comma Separated Value (CSV) file parsing and writing.\\
\li{itertools} & Tools for iterating through sequences in useful ways.\\
\li{math} & Standard mathematical functions and constants.\\
% \li{os} & Tools for interacting with the operating system.\\
\li{random} & Random variable generators.\\
\li{string} & Common string literals.\\
\li{sys} & Tools for interacting with the interpreter.\\
\li{time} & Time value generation and manipulation.\\
% \li{timeit} & Measuring execution time of small code snippets.
\end{tabular}
\end{table}

Use IPython's object introspection to quickly learn about how to use the various modules and functions in the standard library.
Use \li{?} or \li{help()} for information on the module or one of its names.
To see the entire module's namespace, use the \li{tab} key.

\begin{lstlisting}
<g<In [1]:>g> import math

<g<In [2]:>g> math?
<<Type:        module
String form: <module 'math' from '~/anaconda/lib/python3.6/>> # ...
<<File:        ~/anaconda/lib/python3.6/lib-dynload/>> # ...
<<Docstring:
This module is always available.  It provides access to the
mathematical functions defined by the C standard.>>

# Type the module name, a period, then press tab to see the module's namespace.
<g<In [3]:>g> math.   # Press 'tab'.
<<    acos()      cos()       factorial() isclose()   log2()      tan()
    acosh()     cosh()      floor()     isfinite()  modf()      tanh()
    asin()      degrees()   fmod()      isinf()     nan         tau
    asinh()     e           frexp()     isnan()     pi          trunc()
    atan()      erf()       fsum()      ldexp()     pow()
    atan2()     erfc()      gamma()     lgamma()    radians()
    atanh()     exp()       gcd()       log()       sin()
    ceil()      expm1()     hypot()     log10()     sinh()
    copysign()  fabs()      inf         log1p()     sqrt()>>

<g<In [3]:>g> math.sqrt?
<<Docstring:
sqrt(x)

Return the square root of x.
Type:      builtin_function_or_method>>
\end{lstlisting}

\subsection*{The Itertools Module} % ------------------------------------------

The \li{itertools} module makes it easy to iterate over one or more collections in specialized ways.

\begin{table}[H] % Itertools
\begin{tabular}{r|l}
Function & Description \\ \hline
\li{chain()} & Iterate over several iterables in sequence.\\
\li{cycle()} & Iterate over an iterable repeatedly.\\
\li{combinations()} & Return successive combinations of elements in an iterable.\\
\li{permutations()} & Return successive permutations of elements in an iterable.\\
\li{product()} & Iterate over the Cartesian product of several iterables.
\end{tabular}
\end{table}

\begin{lstlisting}
>>> from itertools import chain, cycle              # Import multiple names.

>>> list(chain("abc", ['d', 'e'], ('f', 'g')))      # Join several
<<['a', 'b', 'c', 'd', 'e', 'f', 'g']>>                 # sequences together.

>>> for i,number in enumerate(cycle(range(4))):     # Iterate over a single
...     if i > 10:                                  # sequence over and over.
...         break
...     print(number, end=' ')
...
0 1 2 3 0 1 2 3 0 1 2
\end{lstlisting}

A $k$-\emph{combination} is a set of $k$ elements from a collection where the ordering is unimportant.
Thus the combination $(a,b)$ and $(b,a)$ are equivalent because they contain the same elements.
One the other hand, a $k$-\emph{permutation} is a sequence of $k$ elements from a collection where the ordering matters.
Even though $(a,b)$ and $(b,a)$ contain the same elements, they are counted as different permutations.

\begin{lstlisting}
>>> from itertools import combinations, permutations

# Get all combinations of length 2 from the iterable "ABC".
>>> list(combinations("ABC", 2))
<<[('A', 'B'), ('A', 'C'), ('B', 'C')]>>

# Get all permutations of length 2 from "ABC". Note that order matters here.
>>> list(permutations("ABC", 2))
<<[('A', 'B'), ('A', 'C'), ('B', 'A'), ('B', 'C'), ('C', 'A'), ('C', 'B')]>>
\end{lstlisting}

\begin{problem}
The \emph{power set} of a set $A$, denoted $\mathcal{P}(A)$ or $2^A$, is the set of all subsets of $A$, including the empty set $\emptyset$ and $A$ itself.
For example, the power set of the set $A = \{a, b, c\}$ is $2^A = \{\emptyset, \{a\}, \{b\}, \{c\}, \{a,b\}, \{a,c\}, \{b,c\}, \{a,b,c\}\}$.

Write a function that accepts an iterable $A$.
Use an \li{itertools} function to compute the power set of $A$ as a list of sets (why couldn't it be a set of sets in Python?).
% \\(Hint: The power set of a set with $n$ elements should have exactly $2^n$ elements.)
\end{problem}

\newpage

\subsection*{The Random Module} % =============================================

Many real-life events can be simulated by taking random samples from a probability distribution.
For example, a coin flip can be simulated by randomly choosing between the integers 1 (for heads) and 0 (for tails).
The \li{random} module includes functions for sampling from probability distributions and generating random data.

\begin{table}[H] % The random module.
\begin{tabular}{r|l}
Function & Description\\ \hline
\li{choice()} & Choose a random element from a non-empty sequence, such as a list.\\
\li{randint()} & Choose a random integer integer over a closed interval.\\
\li{random()} & Pick a float from the interval [0, 1).\\
\li{sample()} & Choose several unique random elements from a non-empty sequence.\\
\li{seed()} & Seed the random number generator.\\
\li{shuffle()} & Randomize the ordering of the elements in a list.
\end{tabular}
\end{table}

Some of the most common \li{random} utilities involve picking random elements from iterables.

\begin{lstlisting}
>>> import random

>>> numbers = list(range(1,11))     # Get the integers from 1 to 10.
>>> print(numbers)
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

>>> random.shuffle(numbers)         # Mix up the ordering of the list.
>>> print(numbers)                  # Note that shuffle() returns nothing.
[5, 9, 1, 3, 8, 4, 10, 6, 2, 7]

>>> random.choice(numbers)          # Pick a single element from the list.
5

>>> random.sample(numbers, 4)       # Pick 4 unique elements from the list.
[5, 8, 3, 2]

>>> random.randint(1,10)            # Pick a random number between 1 and 10.
10
\end{lstlisting}

\subsection*{The Time Module} % -----------------------------------------------

The \li{time} module in the standard library include functions for dealing with time.
In particular, the \li{time()} function measures the number of seconds from a fixed starting point, called ``the Epoch'' (January 1, 1970 for Unix machines).

\begin{lstlisting}
>>> import time
>>> time.time()
1495243696.645818
\end{lstlisting}

The \li{time()} function
% \footnote{The \li{clock()} function is similar to \li{time()}, but it records more precision on Windows machines.}
is useful for measuring how long it takes for code to run: record the time just before and just after the code in question, then subtract the first measurement from the second to get the number of seconds that have passed.

\begin{lstlisting}
>>> def time_for_loop(iters):
...     """Time how long it takes to iterate 'iters' times."""
...     start = time.time()         # Clock the starting time.
...     for _ in range(int(iters)):
...         pass
...     end = time.time()           # Clock the ending time.
...     return end - start          # Report the difference.
...
>>> time_for_loop(1e5)              # 1e5 = 100000.
0.005570173263549805
>>> time_for_loop(1e7)              # 1e7 = 10000000.
0.26819777488708496
\end{lstlisting}

\subsection*{The Sys Module} % ------------------------------------------------

The \li{sys} (system) module includes methods for interacting with the Python interpreter.
For example, \li{sys.argv} is a list of arguments passed to the interpreter when it runs a Python file.

\begin{lstlisting}
# example3.py
"""Read a single command line argument and print it in all caps."""
import sys

if len(sys.argv) == 2:
    print(sys.argv[1].upper())
else:
    print("Exactly one extra command line argument is required")
    print("System Arguments:", sys.argv)
\end{lstlisting}

Now provide command line arguments for the program to process.

\begin{lstlisting}
$ python example3.py                # No extra command line arguments.
<<Exactly one extra command line argument is required
System Arguments: ['example3.py']>>

$ python example3.py hello          # One extra command line argument.
<<HELLO>>

$ python example3.py <<with 2 many arguments>>
<<Exactly one extra command line argument is required
System Arguments: ['example3.py', 'with', '2', 'many', 'arguments']>>
\end{lstlisting}

Note that the first command line argument is always the filename, and that \li{sys.argv} is always a list of strings, even if a number is provided on the command line.
In IPython, command line arguments are specified after the \li{<p<\%run>p>} command.

\begin{lstlisting}
<g<In [1]:>g> <p<%run>p> example3.py hello
<<HELLO>>
\end{lstlisting}

Another way to get input from the program user is to prompt the user for text.
The built-in function \li{input()} pauses the program and waits for the user to type something.
Like command line arguments, the user's input is parsed as a string.

\begin{lstlisting}
>>> x = input("Enter a value for x: ")
<<Enter a value for x:>> <r<20>r>             # Type '20' and press 'enter.'

>>> x
<<'20'>>                                # Note that x contains a string.

>> y = int(input("Enter an integer for y: "))
<<Enter an integer for y:>> <r<16>r>          # Type '16' and press 'enter.'

>>> y
16                                  # Note that y contains an integer.
\end{lstlisting}

\begin{problem} % Problem: shut the box.
\emph{Shut the box} is a popular British pub game that is used to help children learn arithmetic.
The player starts with the numbers 1 through 9, and the goal of the game is to eliminate as many of these numbers as possible.
At each turn the player rolls two dice, then chooses a set of integers from the remaining numbers that sum up to the sum of the dice roll.
These numbers are removed, and the dice are then rolled again.
The game ends when none of the remaining integers can be combined to the sum of the dice roll, and the player's final score is the sum of the numbers that could not be eliminated.
For a demonstration, see \url{https://www.youtube.com/watch?v=mwURQC7mjDI}.

Modify your solutions file so that when the file is run with the correct command line arguments (but \textbf{not} when it is imported), the user plays a game of shut the box.
The provided module \texttt{box.py} contains some functions that will be useful in your implementation of the game.
You do not need to understand exactly how the functions work, but you do need to be able to import and use them correctly.
Your game should match the following specifications:

\begin{itemize}
\item Require three total command line arguments: the file name (included by default), the player's name, and a time limit in seconds.
If there are not exactly three command line arguments, do not start the game.
\item Track the player's remaining numbers, starting with 1 through 9.
\item Use the \li{random} module to simulate rolling two six-sided dice.
However, if the sum of the player's remaining numbers is 6 or less, role only one die.
\item The player wins if they have no numbers left, and they lose if they are out of time or if they cannot choose numbers to match the dice roll.
\item If the game is not over, print the player's remaining numbers, the sum of the dice roll, and the number of seconds remaining.
Prompt the user for numbers to eliminate.
The input should be one or more of the remaining integers, separated by spaces.
If the user's input is invalid, prompt them for input again before rolling the dice again.
\\(Hint: use \li{round()} to format the number of seconds remaining nicely.)
\item When the game is over, display the player's name, their score, and the total number of seconds since the beginning of the game.
Congratulate or mock the player appropriately.
\end{itemize}
(Hint: \textbf{Before you start coding}, write an outline for the entire program, adding one feature at a time.
Only start implementing the game after you are completely finished designing it.)

Your game should look similar to the following examples.
The characters in red are typed inputs from the user.

% Sample game sessions.
\begin{lstlisting}
$ python standard_library.py LuckyDuke 60

Numbers left: [1, 2, 3, 4, 5, 6, 7, 8, 9]
Roll: 12
Seconds left: 60.0
Numbers to eliminate: <r<3 9>r>

Numbers left: [1, 2, 4, 5, 6, 7, 8]
Roll: 9
Seconds left: 53.51
Numbers to eliminate: <r<8 1>r>

Numbers left: [2, 4, 5, 6, 7]
Roll: 7
Seconds left: 51.39
Numbers to eliminate: <r<7>r>

Numbers left: [2, 4, 5, 6]
Roll: 2
Seconds left: 48.24
Numbers to eliminate: <r<2>r>

Numbers left: [4, 5, 6]
Roll: 11
Seconds left: 45.16
Numbers to eliminate: <r<5 6>r>

Numbers left: [4]
Roll: 4
Seconds left: 42.76
Numbers to eliminate: <r<4>r>

Score <<for>> player LuckyDuke: 0 points
Time played: 15.82 seconds
Congratulations!! You shut the box!
\end{lstlisting}

The next two examples show different ways that a player could lose (which they usually do), as well as examples of invalid user input.
Use the \li{box} module's \li{parse_input()} to detect invalid input.

\begin{lstlisting}
$ python standard_library.py ShakySteve 10

Numbers left: [1, 2, 3, 4, 5, 6, 7, 8, 9]
Roll: 7
Seconds left: 10.0
Numbers to eliminate: <r<Seven>r>             # Must enter a number.
<<Invalid input>>

Seconds left: 7.64
Numbers to eliminate: <r<1, 2, 4>r>           # Do not use commas.
<<Invalid input>>

Seconds left: 4.55
Numbers to eliminate: <r<1 2 3>r>             # Numbers don't sum to the roll.
<<Invalid input>>

Seconds left: 2.4
Numbers to eliminate: <r<1 2 4>r>

Numbers left: [3, 5, 6, 7, 8, 9]
Roll: 8
Seconds left: 0.31
Numbers to eliminate: 8
Game over!                              # Time is up!

<<Score for player ShakySteve: 30 points
Time played: 11.77 seconds
Better luck next time >:)>>
\end{lstlisting}

\begin{lstlisting}
$ python standard_library.py SnakeEyesTom 10000

Numbers left: [1, 2, 3, 4, 5, 6, 7, 8, 9]
Roll: 2
Seconds left: 10000.0
Numbers to eliminate: <r<2>r>

Numbers left: [1, 3, 4, 5, 6, 7, 8, 9]
Roll: 2
Game over!                              # Numbers cannot match roll.

<<Score for player SnakeEyesTom: 43 points
Time played: 1.53 seconds
Better luck next time >:)>>
\end{lstlisting}

\label{prob:shut-the-box}
\end{problem}

\newpage

\section*{Additional Material} % ==============================================

\subsection*{More Built-in Functions} % ---------------------------------------

The following built-in functions are worth knowing, especially for working with iterables and writing very readable conditional statements.

\begin{table}[H]
\begin{tabular}{r|l}
Function & Description \\ \hline
\li{all()} & Return \li{True} if \li{bool(entry)} evaluates to \li{True} for \emph{every} entry in \\&the input iterable.\\
\li{any()} & Return \li{True} if \li{bool(entry)} evaluates to \li{True} for \emph{any} entry in the\\&input iterable.\\
\li{bool()} & Evaluate a single input object as \li{True} or \li{False}.\\
\li{eval()} & Execute a string as Python code and return the output.\\
\li{map()} & Apply a function to every item of the input iterable and return \\&an iterable of the results.\\
\end{tabular}
\end{table}

\begin{lstlisting}
>>> from random import randint
# Get 5 random numbers between 1 and 10, inclusive.
>>> numbers = [randint(1,10) for _ in range(5)]

# If all of the numbers are less than 8, print the list.
>>> if all([num < 8 for num in numbers]):
...     print(numbers)
...
[1, 5, 6, 3, 3]

# If none of the numbers are divisible by 3, print the list.
>>> if not any([num % 3 == 0 for num in numbers]):
...     print(numbers)
...
\end{lstlisting}

\subsection*{Two-Player Shut the Box} % ---------------------------------------

% \emph{``A game that you can play with your girlfriend is much more fun than a game that you can only play alone.''}
% \begin{flushright}\emph{---Emily Evans}\end{flushright}
% %
Consider modifying your shut the box program so that it pits two players against each other (one player tries to shut the box while the other tries to keep it open).
The first player plays a regular round as described in Problem \ref{prob:shut-the-box}.
Suppose he or she eliminates every number but 2, 3, and 6.
The second player then begins a round with the numbers 1, 4, 5, 7, 8, and 9, the numbers that the first player had eliminated.
If the second player loses, the first player gets another round to try to shut the box with the numbers that the second player had eliminated.
Play continues until one of the players eliminates their entire list.
In addition, each player should have their own time limit that only ticks down during their turn.
If time runs out on your turn, you lose no matter what.

\subsection*{Python Packages} % -----------------------------------------------

Large programming projects often have code spread throughout several folders and files.
In order to get related files in different folders to communicate properly, the associated directories must be organized into a Python \emph{packages}.
This is a common procedure when creating smart phone applications and other programs that have graphical user interfaces (GUIs).

A package is simply a folder that contains a file called \texttt{\_\_init\_\_.py}.
This file is always executed first whenever the package is used.
A package must also have a file called \texttt{\_\_main\_\_.py} in order to be executable.
Executing the package will run \texttt{\_\_init\_\_.py} and then \texttt{\_\_main\_\_.py}, but importing the package will only run \texttt{\_\_init\_\_.py}.

Use the regular syntax to import a module or subpackage that is in the current package, and use \li{from <subpackage.module> import <<<object>>>} to load a module within a subpackage.
Once a name has been loaded into a package's \texttt{\_\_init\_\_.py}, other files in the same package can load the same name with \li{from . import <<<object>>>}.
To access code in the directory one level above the current directory, use the syntax \li{from .. import <<<object>>>}
This tells the interpreter to go up one level and import the object from there.
This is called an \emph{explicit relative import} and cannot be done in files that are executed directly (like \texttt{\_\_main\_\_.py}).

Finally, to execute a package, run Python from the shell with the flag \li{-m} (for ``module-name'') and exclude the extension \texttt{.py}.

\begin{lstlisting}
$ python -m package_name
\end{lstlisting}

See \url{https://docs.python.org/3/tutorial/modules.html\#packages} for examples and more details.


\subsection{Overlap Integral}
\begin{description}
\item[Type:] OverlapIntegral
\item[Description:]

This map shows regions of the field where emission of various spectral
lines overlaps (or doesn't overlap). This map (FITS or JPG) can only be
constructed after a set of zero moments has been created.

One can either create RGB type combinations of a selected set of lines
or by assigning a different bit in a bitmask of emission if that line is
present (over a cliplevel).

The number of zero moments is between 2 and 8, with a typical number
being 3 for RGB output and up to 8 for bitmask output.

The OverlapIntegral could be generalized to Cubes as well but that
is beyond the scope of our initial deliverable.

\item[Constituents:]: BDP\_Image

\item[ADMIT Task:]  AT\_OverlapIntegral

\item[CASA Task(s):] TBD

\item[Input BDP(s):] At least two Moment0 maps

\item[Output BDP(s):]  Image (JPG or other format) representation of where
emission from each input moment map overlaps.
\end{description}


\section{Conclusions and Future Work}

We presented a novel Bayesian approach to predicting argument convincingness from pairwise labels using
Gaussian process preference learning (GPPL).
Using recent advances in approximate inference, we developed a scalable algorithm for GPPL
that is suitable for large NLP datasets.
Our experiments demonstrated that our method significantly outperforms the state-of-the-art
on a benchmark dataset for argument convincingness,
particularly when noisy and conflicting pairwise labels are used in training.
Active learning experiments showed that GPPL is an effective model for cold-start situations
and that the convincingness of Internet arguments can be predicted reasonably
well given only a small number of samples.
The results also showed that linguistic features and word embeddings provide complementary information,
and that GPPL can be used to automatically identify relevant features.

Future work will evaluate our approach on other NLP tasks
where reliable classifications may be difficult to obtain,
such as learning to classify text from implicit user feedback~\cite{joachims2002optimizing}.
We also plan to investigate training the GP using absolute scores in combination with pairwise labels.


\documentclass{article}
\usepackage{parskip}
\usepackage{amsmath}

\setlength{\parindent}{0cm}

\begin{document}

\title{CPSC 413 \\ Assignment 1 - Analysis of Simple Algorithms}
\author{Andrew Helwer}
\date{February 2011}
\maketitle

\section{Partial Correctness of FindLeaf}

\emph{Precondition:}
\begin{itemize}
\item A nonempty binary tree $T$ is given as input
\end{itemize}

\emph{Postcondition:}
\begin{itemize} \item A leaf of $T$ is returned as output
\item The tree $T$ has not been changed
\end{itemize}

\textbf{Assertion A:} $v:=$ the root of $T$ and $T$ has not been modified

\textbf{Assertion B:} $v:=$ a leaf of $T$ and $T$ has not been modified

\textbf{Assertion C:} $v$ is an interior vertex of $T$

\textbf{Assertion D:} The depth of $v$ has increased by one, and $T$ has not
been modified

Assuming the precondition is satisfied, $T$ is nonempty - that is, it contains
at least one element, the root vertex. $v$ is set equal to this vertex before
execution of the loop, satistfying assertion $A$ as simply changing the
reference $v$ does not modify $T$.

If there is only one vertex in $T$, then $v$ (the root vertex) is a leaf and
the loop invariant $C$ is not satisfied. If there is more than one vertex in
$T$, then $v$ will be an interior vertex of $T$ as the root must then have at
least one child (either left or right) and so $C$ will be satisfied and the
loop entered.

By satisfying $C$ and entering the loop, $v$ is guaranteed to have either a
left or right child, specified $v.left$ and $v.right$ respectively. Once the
loop body has executed, $v$ has been set to either $v.left$ or $v.right$, and so
the number of $v:=v.parent$ operations it would take to reach the root node has
increased by one - thus the depth of $v$ has increased by one, partially
satisfying $D$. As well, the operations $v:=v.left$ and $v:=v.right$ make no
modifications to $T$ - they change only the reference $v$. Thus $T$ is not
modified during the loop body, and $D$ is fully satisfied. Therefore $C
\Rightarrow D$ over execution of the loop body.

$C$ is once again tested for, and if satisfied the loop body again executes. If
$C$ is not satisfied, the loop is exited. Since $C$ is not satisfied, $v$ is not
an interior vertex of $T$. Since $v$ is not an interior vertex, by definition it
must be a leaf. Thus $B$ is partially satisfied, which in turn satisfies one of
the postrequisites as $v$ is returned. The second postrequisite, and second
part of $B$ - that $T$ has not been modified - is ensured by satisfying $D$ at
the end of every execution of the loop body, or $A$ if there is only one vertex
in $T$. Thus $A \Rightarrow B$ over execution of the findLeaf function.

The above is sufficient to prove that the satisfaction of the preconditions
prior to findLeaf execution implies the satisfaction of the postconditions
after findLeaf execution. Since termination has not been proven, findLeaf has
only been shown to be partially correct.

\section{Termination of FindLeaf}

The following assumes that a binary tree consists of a finite number of
vertices.

Assume that findLeaf is executed on valid input whereby the precondition is
satisfied. Observe that instructions 1 and 6 are guaranteed to execute only
once, as they are not contained within the body of a loop. They may therefore
be disregarded when proving termination, and only the loop (instructions 2
through 5) considered.

A fundamental property of binary trees is depth, which is the number of edges
on the longest path from the root to any leaf in $T$. The depth of the root
is therefore zero. For any interior vertex $v$ of $T$, setting $v:=v.left$ or
$v:=v.right$ increases the depth of $v$ by one, as it adds an additional edge
to traverse to reach the root.

In question 1 it was proved that after every execution of the loop
body on valid input, the depth of $v$ was increased by one. Define a new
function $D$, whereby if $D(v)$ is computed for some $v \in T$, $D$ returns the
depth of $v$ in $T$, and if $D(T)$ is computed for some binary tree $T$, $D$
returns the depth of $T$. Thus after every execution of the loop body, where
$v'$ is the value of $v$ before execution, $D(v'):=D(v')+1=D(v)$.

Define another function $B(T,v) = D(T) - D(v)$, called the bound function. Since
$D(v)$ increases by one every time the loop body executes and $D(T)$ remains
constant (due to the condition of $T$ not being modified), $|B|$ decreases in
value with every execution of the loop body. Because the size of $T$ is finite,
$D(T)$ is finite as well, and so the loop body will execute only a finite
number of times before $B(T,v) = 0$ - at this point, $D(v) = D(T)$, and so $v$
must be a leaf node of $T$, as otherwise $v$ possesses a child with depth
greater than the depth of the tree, by definition impossible. Since $v$ is not
an interior vertex of $T$, the loop invariant is not satisfied and so the loop
will terminate when $B(T,v) = 0$ after a finite number of executions.

Thus it has been shown that the loop body will execute only a finite number of
times on valid input, and so findLeaf will terminate on valid input.

\section{Upper Bound on Cost of FindLeaf}

As in question 2, observe that on valid input steps 1 and 6 are executed only
once, for a total constant cost of 2. Also observe that the depth of $T$ is
maximized when every vertex in $T$ counts toward the depth of $T$ - that is,
when $T$ is in a configuration resembling a linked list with each vertex having
exactly one parent and one child except for the root (which lacks a parent) and
the leaf (which lacks a child). It will be in this case then that the bound
function defined in question 2 is initialized to a value furthest from zero.

The configuration described above will result in $T$ having a depth of
$|T|-1$, where $|T|$ is the number of vertices in $T$, also known as the size of
$T$. Since the depth of the root node is zero, $B$ is initialized to the value
of $|T|-1$, which is also the number of times the loop runs as $B$
decreases by exactly one with every execution of the loop body.

Inside the loop, three instructions will be executed every time it is run - the
initial check to see if the loop invariant is satisfied, a check whether the
vertex has a left child, and the assignment of the vertex reference to either
its left or right child depending on the outcome of this check. Thus the number
of instructions executed before the loop terminates will be $3*n$, where $n$ is
the number of times the loop executes.

Assembling these observations, the worst case running time of findLeaf may be
given by $R_U(s) = 3(s-1)+2 = 3s-1$, where $s=|T|$.

\section{Lower Bound on Cost of FindLeaf}

Steps 1 and 6 are executed exactly once, resulting in a cost of 2.
Since the number of other instructions executed has been proven to
be a function of the depth of the input, finding the binary tree
configuration with the least depth per unit size will also result in
a function for the lower bound on instruction executions in findLeaf.

Logically, this configuration results when each depth level of $T$ is completely
filled before putting a vertex on the next level - the binary tree cannot be
compressed any further. The structure described is one that is as close to a
full binary tree as possible. Since the capacity of each level is double the
previous, the function that relates $|T|$ to $D(T)$ is given by
$D(|T|)=fl(\log_2(|T|))$, where $fl$ is the flooring function that transforms
any real number into the next lowest integer value.
Following the same derivations as in question 3, we arrive at the best case
running time of findLeaf given by $R_L(s)=3*fl(\log_2(s))+2$, where $s=|T|$.

\section{The Action of the VertexCover Function}

\textbf{Proof A:}

By the action of vertexCover instruction either 6 or 7, the parent of the root
of $T_L$ in $T$ is $w$. Due to instructions 12 or 13, there is no path leading
from any vertex in $T_U$ to $w$, and thus no path leading from any vertex in
$T_U$ to any vertex in $T_L$. Thus any vertex in $T_U$ is not a vertex in
$T_L$, and vice versa - they are disjoint sets, with the addition that $u$ and
$v$ are in neither.

Since $v$ is defined to be a leaf, it has no children. The children of $w$ are
$v$ and the root of $T_L$, which could be $null$. Thus the removal of $T_L \cup
\{v\} \cup \{w\}$ from $T$ results in no lost vertices - all removed vertices
are in $T_L \cup \{v\} \cup \{w\}$. $T_U$ may thus be written $T \setminus T_L
\cup \{v\} \cup \{w\}$. Therefore $T_U$, $T_L$, $\{w\}$, and $\{v\}$ partition
$T$.

From the above it follows that every vertex of $T$ except $v$ and $w$ is a
vertex of exactly one of $T_U$ or $T_L$, so that $|T| = |T_U| + |T_L| + 2$.

\textbf{Proof B:}

The basis for the proof of disjointness in part A was that after the execution
of instructions 12 or 13, there is no path leading from any vertex in $T_U$ to
$w$, and thus no path leading from any vertex in $T_U$ to any vertex in $T_L$.
This may be modified slightly to prove something similar for edges in $T$.
Observe that of all the edges in $T$, there are only three that join to at
least one element outside of $T_U$ and $T_L$ - the edge from $x$ to $w$ (before
removal), the edge from the root of $T_L$ to $w$, and the edge from $v$ to $w$.
If these edges are disregarded, due to the partitioning nature of $T_U$ and
$T_L$ and how edges by definition must join two vertices, all other edges must
exist within $T_U$ or $T_L$.

Thus it is true that every edge in $T$ is an edge in exactly one of $T_U$ or
$T_L$, except for the edges that touch the vertex $w$.

\section{Correctness of VertexCover}

Prove: For all nonnegative integers $n = |T|$, $vertexCover(T)$ returns the
correct output

Base cases:

If $|T|$ = 0 or $|T|$ = 1, then the vertex cover is the empty set, as
there are no edges in $T$ to connect to the vertices in $T$.

Strong Inductive Hypothesis:

Assume the correct vertex cover is returned for $0...n$.
Show $vertexCover(n+1)$ also holds:

$vertexCover(n+1)$ splits $T$ up such that $|T| = |T_U| + |T_L|
+ 2$. Thus $|T_U| + |T_L| = |T|-2$, and so $|T_U| < |T|-2$ and $|T_U| < |T|-2$,
so by inductive hypothesis $vertexCover(T_U)$ and $vertexCover(T_L)$ return the
correct vertex cover of $T_U$ and $T_L$ respectively. Since $vertexCover(n+1) =
vertexCover(T_U) \cup vertexCover(T_L) \cup \{w\}$, $vertexCover(n+1)$ also
returns the correct vertexCover and so by the strong inductive hypothesis
vertexCover is correct for all nonnevative integers $n = |T|$.

\section{Worst-Case Cost of VertexCover}

The worst case running time will result from the same circumstances as the
worst case for findLeaf - that of a linked list configuration for $T$. Since
this is a recursive function, it is best to consider instruction 15 and work
from there.

Step 15 specifies returning $vertexCover(T_U) \cup vertexCover(T_L) \cup
\{w\}$. In the linked list configuration, $T_L$ will always be $null$, leading
to a cost of 2 for calling $vertexCover(T_L)$ as only instructions 1 and 2 will
be executed. The real cost lies in calling $vertexCover(T_U)$ - observe that by
removing both the leaf node and its parent from $T$ upon every execution of the
body of vertexCover, $|T_U| = |T|-2$. Since the precondition does not specify
whether $|T|$ is even or odd, this necessitates two base cases:

\begin{enumerate}
\item if $s = 0$, $C(s) = 2$
\item if $s = 1$, $C(s) = 2$
\item otherwise $C(s) = R_U(s) + 11 + 2 + C(s-2)$
\end{enumerate}

In the above, $s$ is initialized to $|T|$, $R_U(s)$ is the cost function of the
worst case for findLeaf defined back in question 3, and 11 is then number of
instructions that will be executed during a single level of recursion in
vertexCover, with 2 the number of instructions executed during the
$vertexCover(T_L)$ call.

\section{Upper Bound on Cost of VertexCover}

If we consider the recurrence defined in the previous question, it's clear that
there will be approximately $\frac{|T|}{2}$ levels of recursion. Consider the
quantities $A = C(s)$ and $B = C(s-2)$. As the recurrence is defined, $A$ must
be greater than or equal to $B$. Thus $A' = C(s) - C(s-2)$ is greater than or
equal to $B' = C(s-2) - C(s-4)$, and so $\frac{|T|}{2}(C(s) - C(s-2)) \geq C(s)$
for some large value of $s$, as $\frac{|T|}{2}(C(s) - C(s-2))$ may be viewed as
replacing the number of operations performed by all $\frac{|T|}{2}$ levels of
recursion with $C(s) - C(s-2)$, an increase over what they would have been.

Observing the above, the upper bound of the recurrence may be written
$\frac{|T|}{2}(R_U(s) + 13)$, which is of course linear in the product of the
size of $T$ and the number of steps used by findLeaf in the worst case.

\section{Lower Bound on Cost of VertexCover}

Observing that the best-case running time will occur if $T$ is as close
to a full binary tree as possible, using similar arguments to question 8 it is
ascertained that the lower bound on the running time will be of the order
$\frac{|T|}{2}(R_L(s) + C)$, where $C$ is some positive integer constant and
$R_L(s)$ is the lower bound on the running time of findLeaf defined in question
4. Thus the lower bound is also linear in the product of the size of $T$ and
the number of steps used by findLeaf in the best case.

\section{Bounds of VertexCover in Asymptotic Notation}

The worst-case running time of vertexCover, as a function of the size of the
input tree, $n$, is:

\begin{equation}
f(n) \in O(n^2)
\end{equation}

\end{document}


\chapter{Approach}
\label{chp:approach}
% (wie werde ich die Vagheit detektieren → NN, Transformer Architektur) welche
% Grob vorstellen was ich machen werde:

% ich benutze mehrere NNs um Vagheit zu klassifizieren
% Eingaben, Ausgaben
% eher top Level

In this chapter the concrete approach is presented which is used to detect vague requirements.
To classify requirements as vague or not we leverage \acp{DNN}.
The result of each \ac{DNN} is evaluated using dedicated metrics.

Transformer-based approaches have turned out to be viable alternatives to traditional architectures based on \acp{RNN} for \ac{NLP} tasks like language translation \parencites{Gehring:2017}{Vaswani:2017}.
This showcases that transformers are capable of solving complex \ac{NLP} tasks.
Therefore, we base our approach on transformers to attempt to classify vague requirements.
In detail, our approach considers three different pre-trained models as basis.
Namely \ac{BERT} \parencite{Devlin:2018}, \ac{DistilBERT} \parencite{Sanh:2019} and \ac{ERNIE2.0} \parencite{Sun:2019a}.
The following sections outline which particular models are used.

\input{chapters/04_approach/sections/BERT}
\input{chapters/04_approach/sections/distilBERT}
\input{chapters/04_approach/sections/ERNIE2.0}


\chapter{Theory and overview}
\label{chapter:overview}

\section{Terminology and data products}
\label{sec:terminology}
%
As mentioned in the Introduction, the overall topic of this document is the
extraction of geophysical data from observed spectra. This calculation step is
normally denoted as the retrieval or the inversion, where mainly the first term
is used in this document. The objective of \smr\ is to estimate atmospheric
quantities, mainly the concentration of different gases, and these variables
are accordingly the main target of the retrieval, and, together with auxiliary
information, they form the L2 data.

Besides geophysical variables, the retrieval must consider a number of
instrumental aspects to avoid that e.g.\ pointing errors cause unnecessary
large retrieval errors. The result of this part of the retrieval can be seen as
diagnostics data. Some of the quality fields of the L2 data are based on the
diagnostics data, and the data are also stored internally for further analysis
(then denoted as L2I), to e.g.\ detect instrumental drifts.

The retrieval can also include atmospheric state variables that influence the
measurement, but the accuracy of the retrieval is not sufficiently high to
justify inclusion in the L2 data. Regarding atmospheric gases, the ones
included in the L2 data are denoted as target species, while other retrieved
gases are called secondary species.

\section{Radiative transfer basics}
\label{sec:rt}
%
There is no \ATBD\ dedicated to radiative transfer, as a general software is used
to handle this task (Sec.~\ref{sec:setup:forward}). Instead the main
considerations around radiative transfer are commented inside this \ATBD. For a
more detailed discussion, targeting \smr, the reader is referred to
\citet{eriksson:studi:02}.

A strong advantage of using microwaves is that local thermodynamic equilibrium
(LTE) can be assumed, even for radiative transfer in the mesosphere and lower
thermosphere. Further, as long as the lowest altitude of the line-of-sight, the
tangent point, is some kilometres above the tropopause, scattering can safely
be neglected as \smr\ operates at wavelengths $>$\,0.5\,mm. Such a restriction in
tangent altitudes is made for the operational \smr\ retrievals.

The combination of LTE and no scattering makes the basic simulation task
relatively simple. In fact, when it comes to atmospheric radiative transfer,
the required simulations boil down to summing up emission along the propagation
path, weighted with the transmission between \smr\ and the point of emission.
That is, the expression for radiative transfer to handle is \citep[see
e.g.][Eq.~50]{chandrasekhar:60}:
\begin{equation}
  \label{eq:rteq}
     I(\nu) = I_0(\nu)e^{-\int^l_0{k(s,\nu)ds}} +
     \int^l_0{k(s,\nu)B(T(s),\nu) e^{-\int^l_0{k(s',\nu)ds'}} ds},
\end{equation}
where $I$ is radiance, $I_0$ is the radiance along the line-of-sight (\LOS) at
the top of the atmosphere, where the propagation path starts, $l$ is the length
of this propagation path, $k$ is the absorption coefficient, $s$ is the
distance along the propagation path, and $B$ is the Planck function giving the
emission of a blackbody at temperature $T$ and frequency $\nu$.
Eq.~\ref{eq:rteq} assumes that the gaseous absorption is unpolarised. This is a
valid assumption in the microwave region for all species, except for oxygen which
is affected by the Zeeman effect. That is, Earth's magnetic field induces
polarised absorption and emission, and a matrix-vector equivalent to
Eq.~\ref{eq:rteq} is required to handle oxygen \citep[see
e.g.][]{larsson:zeema:14}.

Evaluation of Eq.~\ref{eq:rteq} gives the monochromatic intensity (radiance)
along pencil-beam propagation paths, matching infinite frequency and angular
resolution. Accordingly, Eq.~\ref{eq:rteq} must be solved for a set of
frequencies and propagation paths, to make it possible to incorporate the
antenna pattern, channel frequency response and other characteristics of the
sensor in the simulations \citep[see e.g.][]{eriksson:studi:02,read2006clear}.

\section{Theoretical formalism}
\label{sec:formalism}

\subsection{Forward and inverse models}
%
The retrievals are presented and discussed using the formalism presented in
Chapter~3 of \citet{rodgers:00}. The data to be inverted are appended to create
the measurement vector, \MsrVct. This vector is related to other variables as
\begin{equation}
  \label{eq:fmodel1}
  \MsrVct = \FrwMdl(\SttVct,\FrwMdlVct) + \MsrErrVct_n,
\end{equation}
where \FrwMdl\ is denoted as the forward model, \SttVct\ as the state vector,
\FrwMdlVct\ as the vector of forward model parameters and $\MsrErrVct_n$
represents measurement noise. The distinction between the two arguments of the
forward model is that all variables that we want to retrieve form \SttVct,
while all other quantities required of the forward model are placed in
\FrwMdlVct.

The forward model treated explicitly in this document is the software used to
model atmospheric radiative transfer and sensor responses. This is a model
operating with discrete quantities, while the ``true'', hypothetical, forward
model, \trueFrwMdl, representing the actual physical mechanisms in the atmosphere
and the instrument, must be seen as a continuous function. If \FrwMdl\ is
constructed and used carefully, the discrete representation should not cause
any fundamental problems, and it is here assumed that all deviations between
\trueFrwMdl\ and \FrwMdl\ can be treated as imperfect values in \FrwMdlVct.
That is, $\trueFrwMdl=\FrwMdl(\SttVct,\FrwMdlVct)$, but the exact values of
\FrwMdlVct\ are unknown and all we can do is to use the best possible estimate,
\FrwMdlVctHat. That is:
\begin{equation}
  \label{eq:fmodel2}
  \MsrVct = \FrwMdl(\SttVct,\FrwMdlVctHat) + \MsrErrVct_b + \MsrErrVct_n,
\end{equation}
where
\begin{equation}
  \label{eq:eps_b}
  \MsrErrVct_b = \trueFrwMdl - \FrwMdl(\SttVct,\FrwMdlVctHat).
\end{equation}
This difference ($\MsrErrVct_b$) is below denoted as the forward model
uncertainty.

The retrieval process is formalised in the inverse model, \InvMdl:
\begin{equation}
  \label{eq:imodel}
   \RtrVct = \InvMdl(\MsrVct,\aSttVct{a},\FrwMdlVctHat,\InvMdlVct),
\end{equation}
where \RtrVct\ is the retrieved state vector and \InvMdlVct\ covers all
additional variables introduced by the inverse model. The exact nature
of the vector \aSttVct{a}\ varies between retrieval approaches, but in general it
represents an a priori estimate of \SttVct.

\subsection{Linearisation}
%
From this point it is assumed that the retrieval problem is not strongly
non-linear, and a local linear analysis is possible. Or expressed differently,
that derivatives of the forward and inverse models are approximately valid over
a significant range. The Jacobian, or the weighting function matrix, is the
partial derivative of \FrwMdl\ with respect to \SttVct:
\begin{equation}
  \label{eq:kx}
  \aWfnMtr{\SttVct} = \frac{\PartD\FrwMdl}{\PartD\SttVct}.
\end{equation}
In the same manner, we define \aWfnMtr{\FrwMdlVct} as
\begin{equation}
  \label{eq:kb}
  \aWfnMtr{\FrwMdlVct} = \frac{\PartD\FrwMdl}{\PartD\FrwMdlVct}.
\end{equation}
The contribution function matrix, \CtrFncMtr, is defined as the partial
derivative of the inverse model with respect to the measurement vector:
\begin{equation}
  \label{eq:g}
  \CtrFncMtr = \frac{\PartD\InvMdl}{\PartD\MsrVct}.
\end{equation}
Having these partial derivatives at hand, the retrieval error can be related
to the fundamental uncertainties. As a first step, the forward model is
linearised around (\aSttVct{a},\FrwMdlVctHat):
\begin{equation}
  \label{eq:fmodel3}
  \MsrVct = \FrwMdl(\aSttVct{a},\FrwMdlVctHat) +
  \aWfnMtr{\SttVct}\left(\SttVct-\aSttVct{a}\right) +
  \aWfnMtr{\FrwMdlVct}\left(\FrwMdlVct-\FrwMdlVctHat\right) +
  \MsrErrVct_n
\end{equation}
Under these assumptions, we now have a second way to express the forward
model uncertainty:
\begin{equation}
  \MsrErrVct_b = \aWfnMtr{\FrwMdlVct}\left(\FrwMdlVct-\FrwMdlVctHat\right).
\end{equation}
By combining the equations above and rearranging the terms, we can finally
derive an expression for the total retrieval error, $\RtrErr = \RtrVct - \SttVct$:
\begin{equation}
  \label{eq:delta}
  \RtrErr =  \left(\AvrKrnMtr-\IdnMtr\right)
    \left(\SttVct-\aSttVct{a}\right) +
    \CtrFncMtr\aWfnMtr{\FrwMdlVct}\left(\FrwMdlVct-\FrwMdlVctHat\right) +
    \CtrFncMtr\MsrErrVct_n,
\end{equation}
where \IdnMtr\ is the identity matrix and
\begin{equation}
  \label{eq:A}
  \AvrKrnMtr = \CtrFncMtr\aWfnMtr{\SttVct},
\end{equation}
is the averaging kernel matrix. The terms on the right hand side of
Eq.~\ref{eq:delta} are denoted as smoothing error, forward model retrieval
error and measurement noise retrieval error, respectively. These error
components are discussed further in Chapter~\ref{chapter:characterisation}.

\subsection{Calculation of retrieval error}
%
Despite that Eq.~\ref{eq:delta} gives an expression for the retrieval error it cannot be used in practice, for the simple reason that \SttVct\ and \FrwMdlVct\
are not known. The retrieval error can only evaluated in a statistical sense,
and for this purpose uncertainties and errors are described by
covariance matrices (\CvrMtr). See e.g.\
\url{en.wikipedia.org/wiki/Covariance_matrix} for a description of this type of
matrices, as well as the basic calculation rules needed to understand the error
propagation. The statistical correspondence to Eq.~\ref{eq:delta} is
\begin{equation}
  \label{eq:Sdelta1}
  \aCvrMtr{\RtrErr} = \left(\AvrKrnMtr-\IdnMtr\right)\aCvrMtr{\SttVct}
  \left(\AvrKrnMtr-\IdnMtr\right)^T +
  \CtrFncMtr\aWfnMtr{\FrwMdlVct}\aCvrMtr{\FrwMdlVct}
  \aWfnMtr{\FrwMdlVct}^T\CtrFncMtr^T +
  \CtrFncMtr\aCvrMtr{\MsrErrVct_n}\CtrFncMtr^T.
\end{equation}
The combination of the instrument and the forward model can be seen as
the ``observation system'', then having an uncertainty of
\begin{equation}
  \label{eq:eps_o}
  \MsrErrVct_o = \MsrErrVct_b + \MsrErrVct_n.
\end{equation}
The covariance matrix of the observation system uncertainty is
\begin{equation}
  \label{eq:So}
  \aCvrMtr{\MsrErrVct_o} = \aWfnMtr{\FrwMdlVct}\aCvrMtr{\FrwMdlVct}
  \aWfnMtr{\FrwMdlVct}^T + \aCvrMtr{\MsrErrVct_n}.
\end{equation}
Using the definition of $\aCvrMtr{\MsrErrVct_o}$, Eq.~\ref{eq:Sdelta1}
can be written in a somewhat more compact form:
\begin{equation}
  \label{eq:Sdelta2}
  \aCvrMtr{\RtrErr} = \left(\AvrKrnMtr-\IdnMtr\right)\aCvrMtr{\SttVct}
  \left(\AvrKrnMtr-\IdnMtr\right)^T + \CtrFncMtr\aCvrMtr{\MsrErrVct_o}\CtrFncMtr^T.
\end{equation}

\section{Selected set-up}
\label{sec:setup}

\subsection{Retrieval method}
\label{sec:setup:inverse}
%

\subsubsection{The need for regularisation}
\label{sec:setup:inverse:reg}
%
In short, the task of the retrieval method is to derive \RtrVct\ from \MsrVct.
It turns out that the mapping from \MsrVct\ to \RtrVct\ is not unique. That is,
there exists an infinite set of $\SttVct$-vectors that result in a fit with the
measurement, considering the measurement noise. Instead, some ``optimal'' state
must be selected, among this set of possible solutions.

If we for a moment assume that the retrieval problem can be treated as fully
linear around (\aSttVct{a},\FrwMdlVctHat), we
have that $\aWfnMtr{\SttVct}\left(\SttVct-\aSttVct{a}\right)\approx \MsrVct
-\FrwMdl(\aSttVct{a},\FrwMdlVctHat)$ and the solution can be written as
\begin{equation}
  \label{eq:linretrieval}
  \RtrVct = \aSttVct{a} + \CtrFncMtr(\MsrVct-\FrwMdl(\aSttVct{a},\FrwMdlVctHat)).
\end{equation}
It is clear that \CtrFncMtr, at least roughly, represents an inverse of
\aWfnMtr{\SttVct}, but to use the standard inverse of \aWfnMtr{\SttVct} (only
possible if \aWfnMtr{\SttVct} is square) or to apply the least squares method
($\CtrFncMtr=(\aWfnMtrTrp{\SttVct}\aWfnMtr{\SttVct})^{-1}\aWfnMtr{\SttVct}$)
will result in an extremely high sensitivity to noise. The retrieval problem at
hand is said to be ill-posed, which is the standard situation for passive
atmospheric sounding.

\subsubsection{The optimal estimation method}
\label{sec:setup:inverse:oem}
%
The normal way to tackle ill-posed problems of this type is
``regularisation'', where some constrain on the solution is introduced. In
passive atmospheric sounding, using statistical information as basis for the
regularisation has become the standard approach, and it is also the approach
selected for \smr. The method is probably most widely known as the optimal
estimation method (\OEM), which is the name used in this document. The method
can be seen as an application of Bayes theorem, under certain conditions, and
another possible name of the method the maximum a posteriori solution, see
further \citet{rodgers:00}.

The aspect of ``statistical regularisation'' is probably most clearly
identified by noting that \OEM\ minimises the following ``cost function'':
\begin{equation}
  \label{eq:costfun}
  \CstFnc(\SttVct) = (\MsrVct-\FrwMdl(\SttVct,\FrwMdlVctHat))^T\aCvrMtr{o}^{-1}
  (\MsrVct-\FrwMdl(\SttVct,\FrwMdlVctHat)) +
  (\SttVct-\aSttVct{a})^T\aCvrMtr{a}^{-1}(\SttVct-\aSttVct{a}),
\end{equation}
that is,
\begin{equation}
  \label{eq:mincost}
  \RtrVct = \min\limits_{\SttVct}(\CstFnc(\SttVct)).
\end{equation}
The cost function \CstFnc\ can be seen as the sum of the two penalty terms. The
first term weights how well the solution corresponds to the measurement. If
\CstFnc\ would be set to only contain this term, the standard least squares
solution would be obtained. The regularisation is introduced by the second
term, that evaluates the probability of \SttVct\ based on a priori
information.

If the retrieval problem is linear around (\aSttVct{a},\FrwMdlVctHat), \RtrVct\
can be calculated using Eq.~\ref{eq:linretrieval}, with
\citep[][Eq.~4.5]{rodgers:00}
\begin{equation}
  \label{eq:lindy}
  \CtrFncMtr = (\aWfnMtrTrp{\SttVct}\aCvrMtr{o}^{-1}\aWfnMtr{\SttVct}
  +\aCvrMtr{a}^{-1})^{-1}\aWfnMtrTrp{\SttVct}\aCvrMtr{o}^{-1}.
\end{equation}
However, the inversion of \smr\ measurements result in a (moderately)
non-linear problem and an iterative process is required to find the minimum of
\CstFnc, see Sec.~\ref{sec:ml}.

\subsubsection{Considerations around \SttVct\ and \FrwMdlVct}
\label{sec:setup:inverse:xb}
%
Formally, \aCvrMtr{a}\ shall be set to \aCvrMtr{\SttVct}\ \citep{rodgers:00},
that is, a description of the natural variability (including correlations) of
the elements in \SttVct, but this rule is not always obeyed. First of all,
normally there is no manner in which an exact \aCvrMtr{\SttVct} can be derived,
and this matrix is set in some parametric way, loosely based on measurements
and general knowledge of atmospheric physics. It could also be the case that
\aCvrMtr{a}\ is partly used as a ``tuning parameter''. The most common example
is that the variances in \aCvrMtr{a}\ are set with some margin with respect to
the true values, to maintain measurement information as far as possible, or
expressed differently, not to constrain the solution more than necessary.
Further, it is likely that \aSttVct{a}\ differs from the true mean value of
\SttVct, and this systematic deviation should also be represented in
\aCvrMtr{a}\ \citep{eriksson:analy:00}. For a continued discussion, and
comments on the relationship between \aCvrMtr{a}\ and the corresponding
regularisation matrix used in ``Tikhonov regularisation'', see, for example,
\citet{eriksson:analy:00} and \citet{ungermann2011tomographic}.

Finally regarding \aCvrMtr{a}, the point made in Sec.~2.6 of \citet{rodgers:00}
is stressed, for given values along the diagonal, setting \aCvrMtr{a}\ to be
purely diagonal means a stronger regularisation than including reasonable
off-diagonal elements (to reflect correlations). It is a popular mistake to
think that this relationship is reversed. Here it should be noted that using a
diagonal \aCvrMtr{a}\ equals the common choice in Tikhonov regularisation to
select the ``smallest norm'' ($\MtrStl{L}_0$) solution.

The formally correct choice for \aCvrMtr{o} is \aCvrMtr{\MsrErrVct_o}
\citep{eriksson:analy:00,rodgers:00}, but again this theoretical guideline is
seldomly followed exactly. The normal choice is to set
$\aCvrMtr{o}=\aCvrMtr{\MsrErrVct_n}$. One important practical consideration is
that the inverse of \aCvrMtr{\MsrErrVct_o}\ must be calculated and this is a
highly costly operation in the general case, but \aCvrMtr{\MsrErrVct_n}\ is in
general a pure diagonal matrix and the inverse can be determined with a minimal
calculation cost.

Further, the setting of \aCvrMtr{o}\ is influenced by the exact choice of
variables included in \SttVct. As discussed in Sec.~4.1.2 of \citet{rodgers:00}
there is no strict division line between \SttVct\ and \FrwMdlVct. Obviously,
\SttVct\ must contain a representation of the quantities targeted by the
measurements, but for variables of interfering character (e.g.\ frequency
off-set) there is a choice to make. For a perfectly linear retrieval case, exactly
the same results will be obtained for the target quantities independent of whether
interfering factors are covered by \SttVct\ or \FrwMdlVct. However, inclusion
in \SttVct\ is to prefer as this will result in that values describing the
interfering effects are obtained, which can provide important diagnostic
information (e.g.\ to detect instrumental changes). In addition, in a
non-linear situation a more optimal solution is obtained by placing interfering
factors in \SttVct, as it is likely that \aWfnMtr{\FrwMdlVct}, and then also
\aCvrMtr{\MsrErrVct_o} (cf.\ Eq.~\ref{eq:So}), varies with \SttVct. That is,
the description of observation uncertainties is likely to deteriorate with
the deviation between $\SttVct$ and $\aSttVct{a}$. If interfering species are part
of \SttVct, such non-linear effects will be taken care of by the reevaluation of
\aWfnMtr{\SttVct}.

\subsection{Forward model}
\label{sec:setup:forward}
%
Some basic requirements on the forward model were introduced in
Sec.~\ref{sec:rt}. The simulation problem to be tackled is basically the
simplest possible, Eq.~\ref{eq:rteq} should be handled by all forward models
for passive microwave measurements (but limb sounding requires that refraction
and the spherical shape of the Earth is considered when determining the
propagation path, which excludes all ``plane-parallel'' models). On the other
hand, the analysis of some \smr\ data requires non-standard forward model
features: the 118\,GHz oxygen measurements give rise to a demand for treatment
of Zeeman effects, and Doppler effects due to winds could have a significant
impact on mesospheric spectra.

Beside the atmospheric radiative transfer, the second main task of the forward
model is to incorporate effects of sensor characteristics. For the \smr\
radiometer package the sensor features needing consideration are antenna
angular response, mixer, sideband filtering and frequency response of each
spectrometer channel. Compensation of the Doppler shift due to
the satellite's movement is part of the L1b processing.

A further requirement is that the forward model can deliver the Jacobian
(\aWfnMtr{\SttVct}), a demand that should be clear from Eq.~\ref{eq:lindy}.
This task must be handled for all quantities that can be part of the state
vector. That is, the Jacobian is needed not only for the relevant atmospheric
variables (VMRs, temperature and winds), but also fitting of various sensor
imperfections must be handled (pointing off-set, frequency off-set and baseline
fit), see further Sec.~\ref{sec:x}.

In contrast to many other satellite missions \citep[e.g.][]{read2006clear}, no
\smr\ specific forward model has been developed. Instead, the general forward
model \ARTS\ (\ARTSlong) is used for \smr\ L2 processing. Earlier operational
L2 processing \citep{urban:odins:05-b} made use of the first \ARTS\ version
\citep{buehler:artst:05}, as well as the Moliere forward model
\citep{urban2004moliere}), while the retrievals described in this document are
based on the latest version (version 2.3). At this point it is just noted that
\ARTS\ complies fully with the demands listed above, and the presentation of
\ARTS\ is continued in Chapter~\ref{chapter:arts}.

\section{Non-standard retrievals}
\label{sec:nonstandard}
%
As mentioned already in Sec.~\ref{sec:aim}, the operational retrievals do not
handle all \smr\ measurements. Most importantly, scattering is not activated in
the forward model simulations and special retrievals have been developed to
extract information from spectra containing tropospheric information.
This retrieval scheme was introduced by \citet{rydberg:nonga:09} and the latest
results are found in \citet{eriksson:overw:14}. However, the method of
\citet{rydberg:nonga:09} is only applicable for tangent altitudes below 9\,km
and latitudes between 30$^\circ$S and 30$^\circ$N. This leaves a gap between
the operational and the tropical-tropospheric retrievals, and there are
still \smr\ spectra that are not part of any inversion.

The operational processing is of 1D character (Sec.~\ref{sec:arts:config}), as
the standard limb scanning pattern of \smr\ does not provide a basis for
resolving along-track features. However, Odin has during some shorter periods
made measurements dedicated to polar mesospheric clouds. During these
measurement campaigns, Odin has just scanned over a narrow altitude region in
order to enhance the along-track resolution. Accordingly, to maintain the
measurement information of these special observations, 2D (or tomographic)
retrievals were needed. These retrievals were also made by combing \OEM\ and
\ARTS\ but are presented separately, in \citet{christensen:tomog:15}.

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


\section{Discriminant Performance}

The matrix element analysis computes two quantites for each event,
$D_{s}(\vec{x})$ and $D_{t}(\vec{x})$, which are the discriminants for $s$-channel
and $t$-channel, respectively. This section shows several performance curves for
for signal and background Monte Carlo events. Each curve has been normalized to
unit area in order to show differences in shapes for the signal and background.

\subsection{$s$-channel Performance}

\vspace{0.1in}
\begin{figure}[!h!tbp]
\begin{center}
\subfigure[]{
	\includegraphics[width=0.48\textwidth]{figures/performance/tb_Discriminant__schannel_wbb.eps}
}
\subfigure[]{
	\includegraphics[width=0.48\textwidth]{figures/performance/tb_Discriminant__schannel_wjj.eps}
}
\subfigure[]{
	\includegraphics[width=0.48\textwidth]{figures/performance/tb_Discriminant__schannel_lepjets.eps}
}
\subfigure[]{
	\includegraphics[width=0.48\textwidth]{figures/performance/tb_Discriminant__schannel_dilepton.eps}
}
\end{center}
\vspace{-0.1in}
\caption{Discriminant performance for $s$-channel (cyan) against (a) Wbb (green),
(b) Wjj (light green), (c) \lepjets (red), and (d) \dilepton (pink)}
\end{figure}

\clearpage
\subsection{$t$-channel Performance}

\vspace{0.1in}
\begin{figure}[!h!tbp]
\begin{center}
\subfigure[]{
	\includegraphics[width=0.48\textwidth]{figures/performance/tq_Discriminant__tchannel_wbb.eps}
}
\subfigure[]{
	\includegraphics[width=0.48\textwidth]{figures/performance/tq_Discriminant__tchannel_wjj.eps}
}
\subfigure[]{
	\includegraphics[width=0.48\textwidth]{figures/performance/tq_Discriminant__tchannel_lepjets.eps}
}
\subfigure[]{
	\includegraphics[width=0.48\textwidth]{figures/performance/tq_Discriminant__tchannel_dilepton.eps}
}
\end{center}
\vspace{-0.1in}
\caption{Discriminant performance for $t$-channel (blue) against (a) Wbb (green),
(b) Wjj (light green), (c) \lepjets (red), and (d) \dilepton (pink)}
\end{figure}