\section{UTxO}
\label{sec:utxo}

\begin{figure*}[htb]
  \emph{Functions}
  %
  \begin{align*}
    & \fun{isNonNativeScriptAddress} \in \Tx \to \Addr \to \Bool \\
    & \fun{isNonNativeScriptAddress}~tx~a = \\
      &\quad\begin{cases}
        s \in \ScriptNonNative & a \in \AddrScr \land \fun{validatorHash}~a \mapsto s \in \fun{txscripts} (\fun{txwits}~tx) \\
        \False & \text{otherwise}
      \end{cases}
                 \nextdef
    & \fun{totExunits} \in \Tx \to \ExUnits \\
    & \fun{totExunits}~\var{tx} = \sum_{\wcard \mapsto (\wcard, eu) \in \fun{txrdmrs}~(\fun{txwits}~tx)} eu
    \nextdef
    & \fun{feesOK} \in \PParams \to \Tx \to \UTxO \to \Bool  \\
    & \fun{feesOK}~\var{pp}~tx~utxo~= \\
    &~~      \minfee{pp}~{tx} \leq \txfee{txb} \wedge (\fun{totExunits}~tx \neq (0, 0) \Rightarrow \\
    &~~~~~~((\forall (a, \wcard, \_) \in \fun{range}~(\fun{txinputs_{fee}}~{txb} \restrictdom \var{utxo}), \neg \fun{isNonNativeScriptAddress}~tx~a) \\
    &~~~~~~\wedge~ \fun{adaOnly}~\var{balance} \\
    &~~~~~~      \wedge~ \var{balance} \geq \txfee{txb})) \\
    &~~      \where \\
    & ~~~~~~~ \var{txb}~=~\txbody{tx} \\
    & ~~~~~~~ \var{balance}~=~\fun{ubalance}~(\fun{txinputs_{fee}}~{txb} \restrictdom \var{utxo})
    \nextdef
    & \fun{txins} \in \TxBody \to \powerset{\TxId \times \Ix} \\
    & \fun{txins} ~\var{txb} = \fun{txinputs}~txb \cup \fun{txinputs_{fee}}~txb
    \nextdef
    & \fun{txscriptfee} \in \Prices \to \ExUnits \to \Coin \\
    & \fun{txscriptfee}~(pr_{mem}, pr_{steps})~ (\var{mem, steps})
    = \var{pr_{mem}}*\var{mem} + \var{pr_{steps}}*\var{steps}
    \nextdef
    &\fun{minfee} \in \PParams \to \Tx \to \Coin \\
    &\fun{minfee}~\var{pp}~\var{tx} = \\
    &~~(\fun{a}~\var{pp}) \cdot \fun{txSize}~\var{tx} + (\fun{b}~\var{pp}) +
    \hldiff{\fun{txscriptfee}~(\fun{prices}~{pp})~(\fun{totExunits}~(\fun{txbody}~{tx}))}
  \end{align*}
  \caption{Functions related to fees}
  \label{fig:functions:utxo}
\end{figure*}

We have added or changed several functions that deal with fees as shown in Figure \ref{fig:functions:utxo}.

\begin{itemize}
  \item $\fun{isNonNativeScriptAddress}$ is a predicate that checks
  whether an address is used as a script address with a non-native
  script.
  \item $\fun{totExunits}$ calculates the total $\ExUnits$ in a transaction by summing
  the per-script units stored in the indexed redeemer structure
  \item The predicate $\fun{feesOK}$ checks whether the transaction is
  paying the necessary fees, and that it does it correctly. That is, it checks that:
  \begin{enumerate}[label=({\roman*})]
    \item the fee amount that the transaction states it is paying suffices to cover
    the minimum fee that the transaction is obligated to pay; and if the transaction uses non-native scripts, that
    \item the fee-marked inputs do not belong to non-native script addresses;
    \item all the fee-marked inputs contain strictly Ada and no other kinds of token; and
    \item the fee-marked inputs are sufficient to cover the fee amount that is stated
    in the transaction.
  \end{enumerate}
  \item The function $\fun{txins}$ returns the UTxO keys of transaction inputs.
  \item $\fun{txscriptfee}$ calculates the fee that a transaction must pay for script
  execution based on the amount of $\ExUnits$ it has budgeted, and the prices in the current protocol parameters
  for each component of $\ExUnits$.
  \item The minimum fee calculation, $\fun{minfee}$, includes the script
  fees that the transaction is obligated to pay in order to run its scripts.
\end{itemize}

Note that when creating a transaction, the wallet is responsible for
determining the fees. Thus, it also has to execute the non-native scripts
and include the fees for their execution.

\subsection{Combining Scripts with Their Inputs}
\label{sec:scripts-inputs}

Figure~\ref{fig:functions:script1} shows the functions that are needed to
retrieve all the data that is relevant to Plutus script validation.
These include:

\begin{itemize}
\item $\Time$ is the system time
\item
  $\ScriptPurpose$ is a sum type of all parts of a transaction that may
  require a script witness to validate. Note that this contains the data
  (eg. a certificate $c \in \fun{txcerts}~{txb}$,
  or a transaction input $tin \in \fun{txcerts}~{txb}$) of the item being validated,
  not just a tag indicating the type.
\item
  $\fun{indexof}$ is a helper function that finds the index of a given certificate, value, input, or
  withdrawal in a list, finite map, or set of such objects.
  It assumes there is some ordering on each of these structures.
\item
  $\fun{indexedRdmrs}$ indexes the pair of a redeemer and an $\ExUnits$ value
  for a given script by its script purpose (eg. the input, or certificate, etc.)
\end{itemize}

\begin{figure}[htb]
  \emph{Abstract types}
  %
  \begin{equation*}
    \begin{array}{r@{~\in~}l@{}lr}
      \var{tm}
      & \Time
      & \text{System time}
    \end{array}
  \end{equation*}
  %
  \emph{Derived types}
  %
  \begin{equation*}
    \begin{array}{r@{~\in~}l@{\qquad=\qquad}lr}
      \var{sp}
      & \ScriptPurpose
      & \PolicyID \uniondistinct \UTxOIn \uniondistinct \AddrRWD \uniondistinct \DCert
%      & \text{item the script is validated for}
    \end{array}
  \end{equation*}
  %
  \emph{Abstract functions}
  \begin{align*}
    &\fun{indexof} \in \DCert \to \seqof{\DCert} \to \Ix\\
    &\fun{indexof} \in \AddrRWD \to \Wdrl \to \Ix\\
    &\fun{indexof} \in \UTxOIn \to \powerset{\TxIn} \to \Ix\\
    &\fun{indexof} \in \PolicyID \to \Value \to \Ix
  \end{align*}
  %
  \emph{Indexing functions}
  \begin{align*}
    &\fun{indexedRdmrs} \in \Tx \to \ScriptPurpose \to (\seqof{\Data}~\times~\ExUnits)\\
    &\fun{indexedRdmrs}~tx~sp =
      \begin{cases}
        ([], \var{eu}) & rdptr \mapsto (\Nothing, \var{eu}) \in \fun{txrdmrs}~(\fun{txwits}~{tx}) \} \\
        ([d], \var{eu}) & rdptr \mapsto (\var{d}, \var{eu}) \in \fun{txrdmrs}~(\fun{txwits}~{tx}) \} \\
        \Nothing & \text{otherwise}
      \end{cases} \\
    & ~~\where \\
    & ~~\quad \var{txb} = \txbody{tx} \\
    & ~~\quad \var{rdptr} = \begin{cases}
        (\mathsf{certTag},\fun{indexof}~\var{sp}~(\fun{txcerts}~{txb}))   & \var{sp}~\in~\DCert \\
        (\mathsf{wdrlTag},\fun{indexof}~\var{sp}~(\fun{txwdrls}~{txb}))   & \var{sp}~\in~\AddrRWD \\
        (\mathsf{mintTag},\fun{indexof}~\var{sp}~(\fun{mint}~{txb}))    & \var{sp}~\in~\PolicyID \\
        (\mathsf{inputTag},\fun{indexof}~\var{sp}~(\fun{txinputs}~{txb})) & \var{sp}~\in~\UTxOIn
      \end{cases}
  \end{align*}
  \caption{Indexing script and data objects}
  \label{fig:functions:script1}
\end{figure}

\subsection{Plutus Script Validation}
Figure~\ref{fig:defs:functions-valid} shows the abstract functions that are used for script validation.

\begin{itemize}
\item $\fun{slotToTime}$ translates a slot number to system time if possible.
If it is not possible to do this translation, $\Nothing$ is returned.
The reason it may not be possible to translate is that the slot number
is too far in the future for the system to accurately
predict the exact time to which it refers.

\item $\fun{txInfo}$ summarizes all the necessary transaction and chain state info
  that needs to be passed to the script interpreter. The $\Language$ argument
  is required because different languages have different expectations of the
  format and contents of the summary $\Data$ term.
  It has a $\UTxO$ as its argument to recover the full information of the inputs of the transaction,
  but only the inputs of the transaction are provided to scripts. For details, see~\ref{sec:txinfo}

\item
  $\fun{valContext}$ constructs the \emph{validation context}. A validation context is
  a $\Data$ term which encodes both the summary of the transaction and ledger information
  (this is supplied by the $\fun{txInfo}$ summarization function), and the script purpose.

\item
  $\fun{runPLCScript}$ validates Plutus scripts. It takes the following
  arguments:
  \begin{itemize}
  \item A cost model, that is used to calculate the $\ExUnits$ that are needed for script execution;
  \item A script to execute;
  \item A list of terms of type $\Data$ that will be passed to the script; and
  \item the execution unit budget.
  \end{itemize}
  It outputs the validation result.
  Note that script execution stops if the full budget has been spent before validation is complete.
  It is left abstract because it is implemented as part of the native script interpreter, not the ledger.
  The interpreter called depends on the language of the script.
\end{itemize}

\textbf{Slot to time translation.}
One of the inputs to scripts is the transaction validity interval (recall here that
they do not actually see the current slot number). The length of a
slot may change in a future era. In this case, for a script written in a previous
era, if we were to pass the transaction validity interval expressed as slot numbers,
we get that

\begin{itemize}
  \item the script logic is expressed in terms of slot numbers
  which likely assume the slot length of the era in which it was created
  \item the slot numbers in the validity interval of the transaction are used
  assuming slot length of the current era
\end{itemize}

Therefore, the slot numbers inside the contract and the slot numbers in the transaction
map differently onto points in time. The ledger does not have access to data (or conversion functions)
that is needed to convert transaction validity interval slots numbers to slots numbers
that correspond to the contracts world view. To address this, we decided to pass
non-native contracts (in all languages and all eras) the system time instead of slot numbers.
The conversion function is implemented by consensus (see~\cite{shelley_consensus}),
which has the information to do this correctly for

\begin{itemize}
  \item all slots prior to the current slot
  \item a number of slots after the current slot (this number is determined by
  the consensus's forecast window)
\end{itemize}

\textbf{Validation context construction.}
  As additional non-native scripting languages become supported in the future, scripts of different
  languages may expect different (or differently structured) transaction and ledger data summary.
  The $\fun{txInfo}$ function will be implemented differently
  for each new language. So, the construction is
  dependent on both the language of the script being validated and the ledger/transaction structure
  of the current era.

  In order to ensure that running scripts of all script languages is supported indefinitely across
  future eras, the $\fun{txInfo}$ function must be total.
  Recall here that while \emph{running} all scripts must be supported across
  all future ledger changes,
  it is not a requirement that every script must \emph{validate} within the context of some transaction.

  The $\fun{txInfo}$ output is computed once for the whole transaction. The output of the function
  $\fun{valContext}$ is computed separately for each script purpose.
  The script purpose is passed to it
  to allow the script to reference itself via its hash, and to be aware of what it is validating.

\textbf{Know your contract arguments.}
  A Plutus validator script may receive either a list of three terms of type $\Data$, in case it validates the spending of script outputs
  or two terms (redeemer and context, with no datum), for all other uses.
  Script authors must keep this in mind when writing scripts, since the ledger call to the interpreter is oblivious to what
  arguments are required.

\begin{figure*}[htb]
  \emph{Abstract Script Validation Functions}
  %
  \begin{align*}
     &\fun{slotToTime} \in \Slot \to \Time^? \\
     &\text{Translate slot number to system time or fail} \\~\\
     &\fun{txInfo} \in \Language \to \UTxO \to \Tx \to \Data \\
     &\text{Summarizes transaction data} \\~\\
     &\fun{valContext} \in \Data \to \ScriptPurpose \to \Data \\
     &\text{Pairs transaction data with a script purpose} \\~\\
     &\fun{runPLCScript} \in \CostMod \to\ScriptPlutus \to
    \seqof{\Data} \to \ExUnits \to \IsValidating \\
     &\text{Validate a Plutus script, taking resource limits into account}
  \end{align*}
  %
  \emph{Notation}
  %
  \begin{align*}
    \llbracket \var{script_v} \rrbracket_{\var{cm},\var{exunits}}~\var{d}
    &=& \fun{runPLCScript} ~{cm}~\var{script_v}~\var{d}~\var{exunits}
  \end{align*}
  \caption{Script Validation, cont.}
  \label{fig:defs:functions-valid}
\end{figure*}

Figure \ref{fig:functions:script2} contains the functions used to
match scripts with their corresponding inputs and pass them to the
evaluator.

\begin{itemize}
  \item $\fun{getData}$ looks for a datum associated with a given script purpose. Note that
  only an $\TxIn$-type script purpose can result in finding an associated datum hash.
  In no datum is found, an empty list is returned. A list containing the found datum
  is returned otherwise.

  \item $\fun{collectNNScriptInputs}$ builds a list of scripts, paired with their
  inputs. Specifically, each tuple in the list contains :

  \begin{itemize}
  \item the script;

  \item the validation context, built by the $\fun{valContext}$ function using
  the transaction summary built by $\fun{txInfo}$, together with the current item being validated;

  \item the hash of the required datum, if any (returned by the $\fun{getData}$ function,
  wrapped in a list type instead of a $\Data^?$ type).

  \item a pair, returned by the $\fun{indexedRdmrs}$ function, of
  \begin{itemize}
    \item a list of $\Data$, containing exactly one or zero elements (this
    is not checked here, however, see~\ref{fig:functions:script1}). This list
    contains the optional redeemer if there is one.
    \item an $\ExUnits$ value, which is mandatory for all scripts
  \end{itemize}

  \item $\fun{evalScripts}$ evaluates a whole list of scripts paired with all their
  inputs by calling the native script validator function, $\fun{runPLCScript}$

  \item $\fun{runNativeScript}$ replaces the $\fun{validateScript}$ function,
  to diffentiate running native and non-native scripts. The definition is the
  same as in the ShelleyMA specification.
\end{itemize}

Note that no ``checks'' are performed within these functions.
Missing validators, missing inputs, incorrect hashes, the wrong type of script etc,
are caught during the application of the UTXOW rule (before these functions are ever applied).
%

\end{itemize}

\begin{figure}[htb]
  \begin{align*}
    & \fun{getData} \in \Tx \to \UTxO \to \ScriptPurpose \to \seqof{\Data} \\
    & \fun{getData}~{tx}~{utxo}~{sp}~=~
      \begin{cases}
        [\var{d}] & \var{sp} \mapsto (\_, \_, h_d) \in \var{utxo}, \var{h_d}\mapsto \var{d} \in \fun{txdats}~(\fun{txwits}~tx) \\
        \epsilon  & \text{otherwise}
      \end{cases}
    \nextdef
    & \fun{collectNNScriptInputs} \in \PParams \to \Tx \to \UTxO \to \seqof{(\ScriptNonNative \times \seqof{\Data} \times \ExUnits \times \CostMod)} \\
    & \fun{collectNNScriptInputs} ~\var{pp}~\var{tx}~ \var{utxo} ~=~ \\
    & ~~\fun{toList} \{ (\var{script}, (\fun{valContext}~\var{txinfo}~\var{sp}~++~ \fun{getData}~tx~utxo~sp~++~\var{d}), \var{eu}, \var{cm}) \mid \\
    & ~~~~(\var{sp}, \var{scriptHash}) \in \fun{scriptsNeeded}~{utxo}~{tx}, \\
    & ~~~~\var{scriptHash}\mapsto \var{script}\in \fun{txscripts}~(\fun{txwits}~tx), \\
    & ~~~~(\var{d}, \var{eu}) := \fun{indexedRdmrs}~tx~sp, \\
    & ~~~~\fun{language}~{script} \mapsto \var{cm} \in \fun{costmdls}~{pp} \} \\
    & \where \\
    & ~~~~~~~ \var{txinfo}~=~\fun{txInfo}~(\fun{language}~{script})~\var{utxo}~\var{tx} \\
    \nextdef
    & \fun{evalScripts} \in \seqof{(\ScriptNonNative \times \seqof{\Data} \times \ExUnits \times \CostMod)} \to \IsValidating \\
    & \fun{evalScripts}~\epsilon = \True \\
    & \fun{evalScripts}~((\var{sc}, \var{d}, \var{eu}, \var{cm});\Gamma) =
      \llbracket sc \rrbracket_{cm,\var{eu}} d \land \fun{evalScripts}~\Gamma
    \nextdef
    &\fun{runNativeScript} \in\ScriptNative \to \Tx \to \IsValidating
  \end{align*}
  \caption{Scripts and their arguments}
  \label{fig:functions:script2}
\end{figure}

\subsection{Two-Phase Transaction Validation for Non-Native Scripts}
\label{sec:two-phase}

Transactions are validated in two phases:
the first phase consists of every aspect of transaction validation apart from executing the non-native scripts; and
the second phase involves actually executing those scripts.
This ensures that users pay for the computational resources that are needed to validate non-native scripts, even
if script validation fails. %
In order to handle script execution, an additional transition system is used, called UTXOS.
It performs the appropriate UTxO state changes, based on the
value of the $\IsValidating$ tag, which it checks using the $\fun{evalScripts}$ function.

In general, there is no way to check \emph{a-priori} that the budget that has been supplied is sufficient for the transaction.
This can only be done by actually running the scripts. From the perspective of the ledger, there is no difference
between a script that exhausts the $\ExUnits$ budget during validation, and one that fails to validate.
If a transaction contains a failing script, the only change to the ledger that is made
is to collect all inputs that have been marked for fees.

It is always in the interest of the slot leader to have the new block validate,
and for it to contain only valid transactions. This motivates the
slot leader to:

\begin{enumerate}
  \item Correctly apply the $\IsValidating$ tag;
  \item Include all transactions that validate within the block,
  \textit{even when there is a 2nd step script validation failure};
  \item Exclude any transactions that are invalid in some way \textit{other than 2nd step script validation failure}.
\end{enumerate}

One important reason for adding the validation tag
to a transaction is that re-applying blocks will not require repeat
execution of scripts in the transactions inside a block, which would increase execution costs.
In fact, when replaying
blocks, all the witnessing information can be thrown away.

\subsection{The UTXOS transition system}
\label{sec:utxo-state-trans}

We have defined a separate transition system, UTXOS, to represent the two distinct
UTxO state changes: i) when all the scripts in a transaction validating; and
ii) when at least one fails to validate. Its transition types
are identical to the UTXO transition (Figure
\ref{fig:ts-types:utxo-scripts}).

\begin{figure}[htb]
  \emph{State transitions}
  \begin{equation*}
    \_ \vdash
    \var{\_} \trans{utxos}{\_} \var{\_}
    \subseteq \powerset (\UTxOEnv \times \UTxOState \times \Tx \times \UTxOState)
  \end{equation*}
  %
  \caption{UTxO script state update types}
  \label{fig:ts-types:utxo-scripts}
\end{figure}

There are two rules, corresponding to the two possible state changes of the
UTxO state in the UTXOS transition system (Figure~\ref{fig:rules:utxo-state-upd}).
%
In both cases, the $\fun{evalScripts}$ function is called upon to verify that the $\IsValidating$
tag has been applied correctly. The function $\fun{collectNNScriptInputs}$ is used to build
the inputs $\var{sLst}$ for the $\fun{evalScripts}$ function.
%
The first rule
applies when the validation tag is $\True$.
In this case, the states of the UTxO, fee
  and deposit pots, and updates are updated exactly as in the current Shelley
  ledger spec.
%
  The second rule
  applies when the validation tag is $\False$.
  In this case, the UTxO state changes as follows:

  \begin{enumerate}
    \item All the
    UTxO entries corresponding to the transaction inputs selected for covering
    fees are removed;

    \item The sum total of the value of the marked UTxO entries
    is added to the fee pot.
  \end{enumerate}

\begin{figure}[htb]
  \begin{equation}
    \inference[Scripts-Yes]
    {
    \var{txb}\leteq\txbody{tx} &
    \var{sLst} := \fun{collectNNScriptInputs}~\var{pp}~\var{tx}~\var{utxo}
    \\
    ~
    \\
    \fun{txvaltag}~\var{tx} = \fun{evalScripts}~\var{sLst} = \True
    \\~\\
    {
      \begin{array}{r}
        \var{slot} \\
        \var{pp} \\
        \var{genDelegs} \\
      \end{array}
    }
    \vdash \var{pup} \trans{\hyperref[fig:rules:update]{ppup}}{\fun{txup}~\var{tx}} \var{pup'}
    \\~\\
    \var{refunded} \leteq \keyRefunds{pp}{txb}
    \\
    \var{depositChange} \leteq
      (\deposits{pp}~{poolParams}~{(\txcerts{txb})}) - \var{refunded}
    }
    {
    \begin{array}{l}
      \var{slot}\\
      \var{pp}\\
      \var{poolParams}\\
      \var{genDelegs}\\
    \end{array}
      \vdash
      \left(
      \begin{array}{r}
        \var{utxo} \\
        \var{deposits} \\
        \var{fees} \\
        \var{pup} \\
      \end{array}
      \right)
      \trans{utxos}{tx}
      \left(
      \begin{array}{r}
        \varUpdate{\var{(\txins{txb} \subtractdom \var{utxo}) \cup \outs{slot}~{txb}}}  \\
        \varUpdate{\var{deposits} + \var{depositChange}} \\
        \varUpdate{\var{fees} + \txfee{txb}} \\
        \varUpdate{\var{pup'}} \\
      \end{array}
      \right) \\
    }
  \end{equation}
  \begin{equation}
    \inference[Scripts-No]
    {
    \var{txb}\leteq\txbody{tx} &
    \var{sLst} := \fun{collectNNScriptInputs}~\var{pp}~\var{tx}~\var{utxo}
    \\
    ~
    \\
    \fun{txvaltag}~\var{tx} = \fun{evalScripts}~\var{sLst} = \False
    }
    {
    \begin{array}{l}
      \var{slot}\\
      \var{pp}\\
      \var{poolParams}\\
      \var{genDelegs}\\
    \end{array}
      \vdash
      \left(
      \begin{array}{r}
        \var{utxo} \\
        \var{deposits} \\
        \var{fees} \\
        \var{pup} \\
      \end{array}
      \right)
      \trans{utxos}{tx}
      \left(
      \begin{array}{r}
        \varUpdate{\var{\fun{txinputs_{fee}}~{txb} \subtractdom \var{utxo}}}  \\
        \var{deposits} \\
        \varUpdate{\var{fees} + \fun{ubalance}~(\fun{txinputs_{fee}}~{txb}\restrictdom \var{utxo})} \\
        \var{pup} \\
      \end{array}
      \right)
    }
  \end{equation}
  \caption{State update rules}
  \label{fig:rules:utxo-state-upd}
\end{figure}

Figure \ref{fig:rules:utxo-shelley} shows the $\type{UTxO-inductive}$
transition rule for the UTXO transition type.
This rule has the following changes:

\begin{enumerate}
  \item The transaction pays fees correctly, as defined above;

  \item The end of the transaction validity interval is translatable into
  system time (ie. within the consensus's forecast window). This is checked
  by $\fun{slotToTime}$, which returns $\Nothing$ if the end slot is outside.
  Note that we do not need to check that the start slot can be converted to
  time, because all pasts slots can be converted into time correctly.

  \item $\fun{adaPerUTxOWord}$ is now a protocol parameter explicitly, the
  $\fun{utxoEntrySize}$ calculation is defined differently than for ShelleyMA
  (see Section~\ref{sec:value-size})

  \item $\fun{maxValSize}$ is now also a protocol parameter (not a constant).
  It represents a size (in bytes) of the total transaction
  size that the size of a $\Value$ in an output can be. Otherwise, this check is
  the same as in ShelleyMA.

 \item The execution unit budget for a transaction is within the maximum
  permitted number of units for a transaction;

  \item The UTXOS state transition is valid (this is the transition that runs the
  non-native scripts)
\end{enumerate}

The resulting state transition is defined entirely by the application of the
UTXOS rule.

\begin{figure}[htb]
  \begin{equation}\label{eq:utxo-inductive-shelley}
    \inference[UTxO-inductive]
    {
      \var{txb}\leteq\txbody{tx} &
      \fun{ininterval}~\var{slot}~(\fun{txvldt}~{tx}) \\
      \hldiff{\var{(\wcard, i_f)}\leteq\fun{txvldt}~{tx}} & \hldiff{\fun{slotToTime}~i_f \neq \Nothing} \\
      \txins{txb} \neq \emptyset
      & \hldiff{\fun{feesOK}~pp~tx~utxo}
      & \txins{txb} \subseteq \dom \var{utxo}
      \\
      \consumed{pp}{utxo}{txb} = ~\produced{pp}{poolParams}~{txb}
      \\~\\
      \mathsf{adaID}\notin \supp {\fun{mint}~tx} \\~\\
      \forall txout \in \txouts{txb}, \\
      \fun{getValue}~txout \geq \fun{inject}~(\hldiff{\fun{utxoEntrySize}~{txout} * \fun{adaPerUTxOWord}~pp)} \\~
      \\
      \forall txout \in \txouts{txb},\\
      \hldiff{\fun{serSize}~(\fun{getValue}~txout) ~\leq ~ (\fun{maxTxSize}~pp) * (\fun{maxValSize}~pp)} \\~
      \\
      \forall (\wcard\mapsto (a,~\wcard)) \in \txouts{txb}, \fun{netId}~a = \NetworkId
      \\
      \forall (a\mapsto\wcard) \in \txwdrls{txb}, \fun{netId}~a = \NetworkId
      \\
      \fun{txsize}~{tx}\leq\fun{maxTxSize}~\var{pp} \\
      \hldiff{\fun{totExunits}~{tx} \leq \fun{maxTxExUnits}~{pp}}
      \\
      ~
      \\
      \hldiff{{
        \begin{array}{c}
          \var{slot}\\
          \var{pp}\\
          \var{poolParams}\\
          \var{genDelegs}\\
        \end{array}
      }
      \vdash
      {
        \left(
          \begin{array}{r}
            \var{utxo} \\
            \var{deposits} \\
            \var{fees} \\
            \var{pup}\\
          \end{array}
        \right)
      }
      \trans{utxos}{\var{tx}}
      {
        \left(
          \begin{array}{r}
            \var{utxo'} \\
            \var{deposits'} \\
            \var{fees'} \\
            \var{pup'}\\
          \end{array}
        \right)
      }
    }}
    {
      \begin{array}{l}
        \var{slot}\\
        \var{pp}\\
        \var{poolParams}\\
        \var{genDelegs}\\
      \end{array}
      \vdash
      \left(
      \begin{array}{r}
        \var{utxo} \\
        \var{deposits} \\
        \var{fees} \\
        \var{pup}\\
      \end{array}
      \right)
      \trans{utxo}{tx}
      \left(
      \begin{array}{r}
        \varUpdate{\var{utxo'}}  \\
        \varUpdate{\var{deposits'}} \\
        \varUpdate{\var{fees'}} \\
        \varUpdate{\var{pup'}}\\
      \end{array}
      \right)
    }
  \end{equation}
  \caption{UTxO inference rules}
  \label{fig:rules:utxo-shelley}
\end{figure}

\subsection{Witnessing}
\label{sec:wits}

Because of two-phase transaction validation, non-native script validation is not part of phase one of transaction witnessing
(it is done in phase 2, once the rest of the transaction is validated).
However, native script validation does remain part of transaction witnessing.
When witnessing a transaction in phase one, we therefore need to validate only the native scripts.

We construct the following helper functions :

\begin{itemize}
  \item $\fun{scriptsNeeded}$ assembles the all the $\ScriptPurpose$ terms
  for validation of every transaction action that requires script validation,
  paired with the hashes of corresponding the witnessing scripts.
  This function collects hashes of both native and non-native scripts.

  \item $\fun{checkRedeemers}$ returns $\True$ if, for the given script purpose,
  whenever the script it points to is non-native, the transaction contains an associated entry
  in the indexed redeemers structure.
  Recall that redeemers are optional to include, so there may be a $\Nothing$ in place of
  a redeemer. Execution units are mandatory for all scripts, so each script purpose
  should have an associated entry specifying the $\ExUnits$ value.

  \item $\fun{languages}$ returns the set of (non-native) script languages
  of all the scripts included in the transaction
\end{itemize}

\begin{figure}[htb]
  \begin{align*}
    & \hspace{-1cm}\fun{scriptsNeeded} \in \UTxO \to \Tx \to \powerset (\ScriptPurpose \times \ScriptHash) \\
    & \hspace{-1cm}\fun{scriptsNeeded}~\var{utxo}~\var{tx} = \\
    & ~~\{ (\var{i}, \fun{validatorHash}~a) \mid i \mapsto (a, \wcard, \wcard) \in \var{utxo},
      i\in\fun{txinsScript}~{(\fun{txins~\var{txb}})}~{utxo}\} \\
    \cup & ~~\{ (\var{a}, \fun{stakeCred_{r}}~\var{a}) \mid a \in \dom (\AddrRWDScr
           \restrictdom \fun{txwdrls}~\var{txb}) \} \\
    \cup & ~~\{ (\var{cert}, \var{c}) \mid \var{cert} \in (\DCertDeleg \cup \DCertDeRegKey)\cap\fun{txcerts}~(\txbody{tx}), \\
    & ~~~~~~\var{c} \in \cwitness{cert} \cap \AddrScr\} \\
      \cup & ~~\{ (\var{pid}, \var{pid}) \mid \var{pid} \in \supp~(\fun{mint}~\var{txb}) \} \\
    & \where \\
    & ~~~~~~~ \var{txb}~=~\txbody{tx}
    \nextdef
    & \hspace{-1cm}\fun{checkRedeemers} \in \Tx \to \UTxO \to (\ScriptPurpose \times \ScriptHash) \to \Bool \\
    & \hspace{-1cm}\fun{checkRedeemers}~\var{tx}~\var{utxo}~(\var{sp},\var{h})~=~ \forall s, (h\mapsto s) \in \fun{txscripts}~(\fun{txwits}~tx),\\
    & (s \in \ScriptNonNative~\Rightarrow \fun{indexedRdmrs}~tx~sp \neq \Nothing) \\
    \nextdef
    & \hspace{-1cm}\fun{languages} \in \TxWitness \to \powerset{\Language} \\
    & \hspace{-1cm}\fun{languages}~\var{txw}~=~
      \{\fun{language}~s \mid s \in \range (\fun{txscripts}~{txw}) \cap \ScriptNonNative\}
  \end{align*}
  \caption{UTXOW helper functions}
  \label{fig:functions-witnesses}
\end{figure}

We have made the following changes and additions to the UTXOW preconditions:

\begin{itemize}

\item All the native scripts in the transaction validate;

\item The transaction contains exactly those scripts that are required for witnessing and no
additional ones;

    \item The datums included in the witnesses are exactly those that are required for validating;

    \item For every item that needs to be validated by a non-native script, the transaction contains
      an entry in the indexed redeemer structure (ie. the execution units for it are specified);

    \item The signatures of the keys whose hashes are specified in the
    $\fun{reqSignerHashes}$ field in a transaction
    have all indeed signed it;

    \item
    The hash of the subset of protocol parameter values that have been included in the transaction body is the same as
    the hash of the same subset of protocol parameters that are currently contained in the ledger;

    \item A check that ensures that the list of scripts paired with their input data (context, datum and redeemer)
    has the same number of elements as the set of scripts needed for each script purpose. Note that the same
    script may appear more than once in both the list and the set, as it can be used for different purposes, and therefore
    run separately for each, with different input data. Note also that by construction, the output of
    the $\fun{collectNNScriptInputs}$ function should have exactly the same collection of scripts as
    the $\fun{scriptsNeeded}$ function output - this check is in place to catch discrepancies in this construction.
    \begin{note}
      Note that $\fun{collectNNScriptInputs}$ is called twice, here and in UTXO. We need to avoid this.
      ALSO we need to audit the $\fun{wppHash}$ function
    \end{note}
\end{itemize}

If these conditions are all satisfied, then the resulting UTxO state change is fully determined
by the UTXO transition (the application of which is also part of the conditions).

\begin{figure}[htb]
  \emph{State transitions}
  \begin{equation*}
    \_ \vdash
    \var{\_} \trans{utxow}{\_} \var{\_}
    \subseteq \powerset (\UTxOEnv \times \UTxOState \times \Tx \times \UTxOState)
  \end{equation*}
  %
  \caption{UTxO with witnesses state update types}
  \label{fig:ts-types:utxo-witness}
\end{figure}

\begin{figure}
  \begin{equation}
    \label{eq:utxo-witness-inductive-alonzo}
    \inference[UTxO-witG]
    {
      \var{txb}\leteq\txbody{tx} &
      \var{txw}\leteq\fun{txwits}~{tx} \\
      (utxo, \wcard, \wcard, \wcard) \leteq \var{utxoSt} \\
      \var{witsKeyHashes} \leteq \{\fun{hashKey}~\var{vk} \vert \var{vk} \in
      \dom (\txwitsVKey{txw}) \}\\~\\
      \hldiff{\forall \var{s} \in \range (\fun{txscripts}~{txw}) \cap \ScriptNative,
      \fun{runNativeScript}~\var{s}~\var{tx}}\\~\\
      \hldiff{\{ s \mid (\_, s) \in \fun{scriptsNeeded}~\var{utxo}~\var{tx}\} = \dom (\fun{txscripts}~{txw})} \\
      \hldiff{\{ h \mid (\_ \mapsto (a, \_, h)) \in \txins{txb} \restrictdom \var{utxo}, \fun{isNonNativeScriptAddress}~{tx}~{a}\} =} \\
      \hldiff{\dom (\fun{txdats}~{txw})} \\
      \hldiff{\forall sph \in \fun{scriptsNeeded}~\var{utxo}~\var{tx},~ \fun{checkRedeemers}~tx~utxo~sph}
      \\~\\
      \forall \var{vk} \mapsto \sigma \in \txwitsVKey{txw},
      \mathcal{V}_{\var{vk}}{\serialised{txbodyHash}}_{\sigma} \\
      \hldiff{\fun{witsVKeyNeeded}~{utxo}~{tx}~{genDelegs} \cup \fun{reqSignerHashes}~txb \subseteq \var{witsKeyHashes}}
      \\~\\
      genSig \leteq
      \left\{
        \fun{hashKey}~gkey \vert gkey \in\dom{genDelegs}
      \right\}
      \cap
      \var{witsKeyHashes}
      \\
      \left\{
        c\in\txcerts{txb}~\cap\DCertMir
      \right\} \neq\emptyset \implies \vert genSig\vert \geq \Quorum \wedge
      \fun{d}~\var{pp} > 0
      \\~\\
      \var{adh}\leteq\fun{txADhash}~\var{txb}
      &
      \var{ad}\leteq\fun{txAD}~\var{tx}
      \\
      (\var{adh}=\Nothing \land \var{ad}=\Nothing)
      \lor
      (\var{adh}=\fun{hashAD}~\var{ad})
      \\~\\
      \hldiff{\fun{wppHash}~{txb}~=~\fun{hashWitnessPPData}~\var{pp}~(\fun{languages}~{txw})~(\fun{txrdmrs}~{txw})}
      \\~\\
      \hldiff{\|~\fun{scriptsNeeded}~\var{utxo}~\var{tx}~\|~=~\|~\fun{collectNNScriptInputs} ~\var{pp}~\var{tx}~ \var{utxo}~\|}
      \\~\\
      {
        \begin{array}{r}
          \var{slot}\\
          \var{pp}\\
          \var{poolParams}\\
          \var{genDelegs}\\
        \end{array}
      }
      \vdash \var{utxoSt} \trans{\hyperref[fig:rules:utxo-shelley]{utxo}}{tx}
      \var{utxoSt'}\\
    }
    {
      \begin{array}{r}
        \var{slot}\\
        \var{pp}\\
        \var{poolParams}\\
        \var{genDelegs}\\
      \end{array}
      \vdash \var{utxoSt} \trans{utxow}{tx} \varUpdate{\var{utxoSt'}}
    }
  \end{equation}
  \caption{UTxO with witnesses inference rules for Tx}
  \label{fig:rules:utxow-alonzo}
\end{figure}


\documentclass[11pt]{article}
%============Macros==================%
% you don't need to change anything. start editing from main body.
\usepackage{amsmath,amsfonts,amssymb,amsthm, cancel, float, enumitem}
\usepackage{qcircuit}
\usepackage[margin=1in]{geometry}
%--------------Cosmetic----------------%
\usepackage{mathtools}
\usepackage{hyperref}
\usepackage{fullpage}
\usepackage{microtype}
\usepackage{xspace}
\usepackage[svgnames]{xcolor}
\usepackage[sc]{mathpazo}
\usepackage{enumitem}
\setlist[enumerate]{itemsep=1pt,topsep=2pt}
\setlist[itemize]{itemsep=1pt,topsep=2pt}
%--------------Header------------------%
\def\course{CS 410/510 Introduction to Quantum Computing}
\def\term{Portland State U, Spring 2017}
\def\prof{Lecturer: Fang Song}
\newcommand{\handout}[5]{
   \renewcommand{\thepage}{\arabic{page}}
   \begin{center}
   \framebox{
      \vbox{
    \hbox to 5.78in { \hfill \large{\course} \hfill }
       \vspace{2mm}
       \hbox to 6in { {\Large \hfill #5  \hfill} }
       \vspace{2mm}
       \hbox to 6in { \term \hfill \emph{#2}}
       \hbox to 6in { {#3 \hfill \emph{#4}}}
      }
   }
   \end{center}
   \vspace*{4mm}
}
\newcommand{\lecture}[4]{\handout{#1}{#2}{#3}{#4}{{Lecture #1}}}

\def\complex{\mathbb{C}}
\def\real{\mathbb{R}}
\def\natural{\mathbb{N}}
\def\integer{\mathbb{Z}}

\newcommand{\norm}[1]{\left\lVert#1\right\rVert}
\newcommand{\snorm}[1]{\lVert#1\rVert}
\newcommand{\abs}[1]{\left\lvert #1 \right\rvert}
\newcommand{\ceil}[1]{\left\lceil #1 \right\rceil}
\newcommand{\floor}[1]{\left\lfloor #1 \right\rfloor}
\newcommand{\set}[1]{\left\{ #1 \right\}}
\newcommand{\vecb}[1]{\boldsymbol{\vec{#1}}}
\newcommand{\conj}[1]{\overline{#1}}
\newcommand{\op}[2]{#1#2#1^\dag}

\newcommand{\tr}{\operatorname{Tr}}
\newcommand{\se}{\operatorname{H}}
\newcommand{\vne}{\operatorname{S}}
\newcommand{\e}{\operatorname{E}}
\newcommand{\rank}{\operatorname{rank}}
\renewcommand{\det}{\operatorname{Det}}

\newcommand{\bra}[1]{\langle #1 \rvert}
\newcommand{\ket}[1]{\lvert #1 \rangle}
\newcommand{\bret}[2]{\langle{#1}|{#2}\rangle}
\newcommand{\kret}[2]{\ket{#1}\bra{#2}}
\newcommand{\kera}[1]{\kret{#1}{#1}}
\newcommand{\Example}[1]{{\bf Example #1}:}

\def\X{\mathcal{X}}
\def\Y{\mathcal{Y}}
\def\Z{\mathcal{Z}}
\def\W{\mathcal{W}}
\def\A{\mathcal{A}}
\def\B{\mathcal{B}}
\def\V{\mathcal{V}}
\def\U{\mathcal{U}}
\def\C{\mathcal{C}}
\def\D{\mathcal{D}}
\def\E{\mathcal{E}}
\def\F{\mathcal{F}}
\def\M{\mathcal{M}}
\def\R{\mathcal{R}}
\def\P{\mathcal{P}}
\def\Q{\mathcal{Q}}
\def\S{\mathcal{S}}
\def\T{\mathcal{T}}
\def\K{\mathcal{K}}
\def\L{\mathcal{L}}

\def\fill{   \hfill}

%=============Main Doc=================%
\begin{document}
%-----Specs: change accordingly--------%
\def\lecdate{May 16, 2017} % put lecture date here
\def\scribe{Scribe: Enis K. Inan} % put your name here
\def\lecnum{13} % change the lecture number

\lecture{\lecnum}{\lecdate}{\prof}{\scribe}%

\begin{center}
{\textsc{Version: \today}}
\end{center}

\noindent Last lecture we introduced the density operator, which made it easier for us to describe general quantum states. We will briefly review it before proceeding any further. In the old notation, we only had pure states of the form $\ket{\psi} = \alpha \ket{0} + \beta \ket{1}$ where $\alpha, \beta \in \complex$ and $\abs{\alpha}^2 + \abs{\beta}^2 = 1$. With our new framework, a pure state is expressed as $\kera{\psi}$ where for our example,
\begin{equation*}
\kera{\psi} = \left(\begin{array}{cc}
\alpha\conj{\alpha} & \alpha\conj{\beta} \\
\conj{\alpha}\beta & \beta\conj{\beta}
\end{array}
\right) = \left(\begin{array}{cc}
\abs{\alpha}^2 & \alpha\conj{\beta} \\
\conj{\alpha}\beta & \abs{\beta}^2
\end{array}
\right)
\end{equation*}
The expressive power of this notation is apparent when we have general quantum states. Specifically, imagine we have a register $X$ that could be in one of the quantum states $\ket{\psi_1}, \dots, \ket{\psi_k}$ with a probability distribution $p_1, \dots, p_k$ where $p_i$ is the probability that $X$ is in state $\ket{\psi_i}$. With our new notation, we expressed our ``knowledge'' of $X$ as a density matrix $\rho$ where
\begin{equation*}
\rho = \sum_{i} p_i \kera{\psi_i}
\end{equation*}
Intuitively, $\rho$ corresponds to a weighted average of each state. There were also several important properties associated with density matrices:
\begin{enumerate}
	\item $\tr{(\rho)} = 1$

	\item $\rho$ is positive semidefinite.
\end{enumerate}
Property 2 will be important later in this lecture, so keep it in the back of your head for now.

\fill

\noindent In our old notation, the physically allowable operations on $\ket{\psi}$ were unitary operations $U$ -- the state $\ket{\psi'} = U\ket{\psi}$ is the resulting state after applying the unitary $U$ on $\ket{\psi}$. In our new notation, $\rho' = U\rho U^\dag$ corresponds to applying the unitary $U$ on the general quantum state described by $\rho$ -- the result is $\rho'$.

%==============================%
\section{General (Physically Admissible) Quantum Operations}
%==============================%
The density matrix formalism does not limit us to just unitary operations. Specifically, any \emph{physically admissible operation} $\Phi$ is a series of matrices $A_1, A_2, \dots, A_k$ where $A_{i_{jk}} \in \complex$ and
\begin{equation} \label{eq:phya:completeness}
\sum_{i} A^\dag_iA_i = I
\end{equation}
\begin{equation} \label{eq:phya:app}
\Phi(\rho) = \sum_{i} \op{A_i}{\rho}
\end{equation}
Note that each $A_i$ in $\Phi$ does \emph{not} have to be a square matrix, and that unitary matrices $U$ are a special case of $\Phi$ with $k = 1$.

\noindent Applying $\Phi$ to $\rho$ yields another density matrix, just like how applying unitary $U$ to $\ket{\psi}$ resulted in another valid quantum state. In fact, $\Phi$ is also known as a completely positive trace preserving (CPTP) operator, which is just jargon for an operation that preserves a matrix's trace and semi-positive definitiveness. Another way to think of $\Phi$ is as follows. Let $\X$ and $\Y$ denote spaces describing $m$ and $n$ qubits, respectively, and let $\L(\X, \Y)$ be the set of all linear mappings from $\X$ to $\Y$. Let $\D(\X)$ be the set of all density matrices in $\X$; define $\D(\Y)$ in a similar manner. Then $\Phi : \D(\X) \rightarrow \D(\Y)$ or, informally, $\Phi$ is the set of all density matrix mappings from $\X$ to $\Y$.

\fill

\noindent \Example{1} Here we investigate decoherence as a physically admissible operation, which is when a quantum system interacts with some environmental noise and loses its quantumness (i.e. gets measured). Note that the operation used in this example is equivalent to measurement in the standard basis $\set{\ket{0}, \ket{1}}$. Here we have $A_0 = \kera{0}$ and $A_1 = \kera{1}$ so that
\begin{equation*}
\Phi(\rho) = \op{A_0}{\rho} + \op{A_1}{\rho}
\end{equation*}
Firs we check if $A_0$ and $A_1$ are valid, i.e. that they satisfy Eqn. \ref{eq:phya:completeness}:
\begin{align*}
\sum_{i} A^\dag_iA_i
&= A^\dag_0A_0 + A^\dag_1A_1 \\
&= \ket{0}\bret{0}{0}\bra{0} + \ket{1}\bret{1}{1}\bra{1} \\
&= \kera{0} + \kera{1} \\
&= I
\end{align*}
which they do. Now assume that $\rho=\kera{\psi}$ where $\ket{\psi} = \alpha\ket{0} + \beta\ket{1}$, i.e. that $\rho$ corresponds to a pure state. We have,
\begin{align*}
\Phi(\kera{\psi})
&= \op{A_0}{\kera{\psi}} + \op{A_1}{\kera{\psi}} \\
&= \kera{0}\kera{\psi}\kera{0} + \kera{1}\kera{\psi}\kera{1} \\
&= \left(\begin{array}{cc}
1 & 0 \\
0 & 0
\end{array}\right)
\left(\begin{array}{cc}
\abs{\alpha}^2 & \alpha\conj{\beta} \\
\conj{\alpha}\beta & \abs{\beta}^2
\end{array}
\right)
\left(\begin{array}{cc}
1 & 0 \\
0 & 0
\end{array}\right) + \left(\begin{array}{cc}
0 & 0 \\
0 & 1
\end{array}\right)
\left(\begin{array}{cc}
\abs{\alpha}^2 & \alpha\conj{\beta} \\
\conj{\alpha}\beta & \abs{\beta}^2
\end{array}
\right)
\left(\begin{array}{cc}
0 & 0 \\
0 & 1
\end{array}\right) \\
&= \left(\begin{array}{cc}
\abs{\alpha}^2 & 0 \\
0 & \abs{\beta}^2
\end{array}
\right) \\
&= \abs{\alpha}^2\kera{0} + \abs{\beta}^2\kera{1}
\end{align*}
which is exactly what we get by doing a measurement on the standard basis! To see why, the last line shows that we can think of $\Phi(\kera{\psi})$ as representing the general quantum state where we have an $\abs{\alpha}^2$ chance of being in $\ket{0}$ and a $\abs{\beta}^2$ chance of being in $\ket{1}$. This is the definition of measurement in the standard basis.

\fill

\noindent Another important operation is the partial trace. Imagine that we have an $m + n$ qubit-state, e.g. $\ket{\psi} = \sum_{x \in \set{0, 1}^m}\sum_{y \in \set{0, 1}^n} \alpha_{xy}\ket{x}\ket{y}$. We want to examine the resulting state after we discard either $x$ or $y$. For our old notation, this is easy -- for $\ket{\psi}$, we can just remove $\ket{x}$ or $\ket{y}$. But in our new notation of density matrices, it is not as obvious. Let $\X$ and $\Y$ be the spaces describing $\ket{x}$ and $\ket{y}$, respectively, and assume without any loss of generality that we want to remove $\ket{y}$. Then what we want is an operation $\Phi: \D(\X \otimes \Y) \rightarrow \D(\X)$ -- this is the partial trace, denoted as $\tr_y$ for our specific case to explicitly indicate that we want to discard $\ket{y}$.

\fill

\noindent Let's examine what $\tr_y$ would look like when $\X$ and $\Y$ both describe 1-qubit each -- i.e., when we have a two-qubit state and we want to discard the second qubit. We have $\Phi$ be the matrices:
\begin{equation*}
\begin{split}
A_0 &= I_x \otimes \bra{0}_y = \left(\begin{array}{cccc}
1 & 0 & 0 & 0 \\
0 & 0 & 1 & 0
\end{array}\right) \\
A_1 &= I_x \otimes \bra{1}_y = \left(\begin{array}{cccc}
0 & 1 & 0 & 0 \\
0 & 0 & 0 & 1
\end{array}\right)
\end{split}
\end{equation*}
Note that $A_0$ and $A_1$ are $2 \times 4$ matrices -- $I_x$ is the $2 \times 2$ identity matrix. We first check that $A_0$ and $A_1$ satisfy Eqn. \ref{eq:phya:completeness}:
\begin{align*}
\sum_{i} A^\dag_iA_i
&= A^\dag_0A_0 + A^\dag_1A_1 \\
&= (I_x \otimes \ket{0}_y)(I_x \otimes \bra{0}_y)
+  (I_x \otimes \ket{1}_y)(I_x \otimes \bra{1}_y) \\
&= (I_x \otimes \kera{0}_y) + (I_x \otimes \kera{1}_y) \\
&= I_x \otimes (\kera{0}_y + \kera{1}_y) \\
&= I_x \otimes I_y = I_{xy}
\end{align*}
Now let's do an example calculation using $\Phi$.

\fill

\noindent \Example{2} Let $\rho = \kera{0} \otimes \kera{1}$. Intuitively, we should get $\kera{0}$ back after applying $\Phi$. Let's see if this is indeed the case.
\begin{align*}
\Phi(\rho)
&= \op{A_0}{\rho} + \op{A_1}{\rho} \\
&= (I_x \otimes \bra{0}_y)(\kera{0} \otimes \kera{1})(I_x \otimes \ket{0}_y)
+  (I_x \otimes \bra{1}_y)(\kera{0} \otimes \kera{1})(I_x \otimes \ket{1}_y) \\
&= \cancelto{0}{(\kera{0} \otimes \bret{0}{1}\bra{1})}(I_x \otimes \ket{0}_y)
+  (\kera{0} \otimes \bret{1}{1}\bra{1})(I_x \otimes \ket{1}_y) \\
&= (\kera{0} \otimes \bra{1})(I_x \otimes \ket{1}_y) \\
&= \kera{0}
\end{align*}
which is exactly what we expected. In the general case, e.g. when we have $\rho' = \rho \otimes \ket{0}$, then $\Phi(\rho') = \rho$ which is consistent with the physical meaning of $\tr_y$ -- take away $y$ and only look at $x$. We can think of it as ``tracing out $y$'', which is where the name ``partial trace'' comes from.

\fill

\noindent Now what if the qubits $x$ and $y$ are entangled? What do we get after we apply $\tr_y$? We will use $\ket{\phi^+} = \frac{1}{\sqrt{2}}(\ket{00} + \ket{11})_{xy}$ as our example.

\fill

\noindent \Example{3} $\tr_y(\kera{\phi^+}) = \frac{1}{2}\kera{0} + \frac{1}{2}\kera{1} = \frac{1}{2}I$ which can be verified by brute-force computation using $\Phi$, like we did in Example 2. So we see that we get a \emph{maximally mixed state}, i.e. a density matrix where the pure states form an orthonormal basis and each state has a probability $1/n$ of occurring, where $n$ is the dimension of the matrix. Here, $n = 2$. In fact, it can be shown that $\tr_y$ for \emph{any} Bell state is $\frac{1}{2}I$. Here's why this makes sense. In a Bell state, when we measure the second register, we \emph{collapse} the resulting state to either just $\ket{0}$ with probability $1/2$, or just $\ket{1}$ with probability $1/2$ -- exactly our maximally mixed state. For example in $\ket{\phi^+}$, if we measure a $1$ in the second register, then the state collapses to $\ket{1}_x$; otherwise, it collapses to $\ket{0}_x$.

\fill

\noindent The next operation we will consider is an extension of Example 1. Instead of constraining the measurement to a specific basis, e.g. the standard basis, let's generalize it. Imagine that $\Gamma$ represents the set of all possible outcomes resulting from our measurement and, for an $a \in \Gamma$, $M_a$ is the matrix ``capturing'' an outcome $a$. For example in Example 1, $\Gamma = \set{0, 1}$, and $M_0 = \kera{0}$, $M_1 = \kera{1}$. Then if
\begin{equation*}
\sum_{a \in \Gamma} M^\dag_aM_a = I
\end{equation*}
then the set of matrices $M = \set{M_a \: | \: a \in \Gamma}$ form a physically admissible operation $\Phi$, i.e. $\Phi$ is a valid measurement. Let's take an outcome $a$ and its measurement matrix $M_a$ where $M_a$ is a projecter ($M^2_a = M_a$). Then $\tr(M_a\rho M^\dag_a)$ is the probability that we will observe outcome $a$ when we measure the quantum system described by $\rho$. In Example 1, $\tr(M_0\rho M^\dag_0) = \abs{\alpha}^2$, which is exactly the probability of measuring a $0$. Now assume that we did measure $a$. Then our state would collapse to
\begin{equation*}
\frac{M_a\rho M^\dag_a}{\tr(M_a\rho M^\dag_a)}
\end{equation*}
which makes sense. If $M_a$ is the measurement matrix ``capturing'' an outcome $a$ then when we see $a$, we should only have $M_a\rho M^\dag_a$ left in our summation for $\Phi(\rho)$. However $M_a\rho M^\dag_a$ may not be a valid density matrix, so we need to normalize its trace back down to $1$ -- this is what the $\tr(M_a\rho M^\dag_a)$ in the denominator does. This corresponds to what we do in the pure state case, which is to keep only parts of the state that contain the measured outcome in its qubits ($M_a\rho M^\dag_a$ here), then normalize that part (divide by $\tr(M_a\rho M^\dag_a)$).

\fill

\noindent The above is known as a Von-Neumann measurement. Another way to think about measurement is through positive operator valued measurements (POVMs) which are the most general class of quantum measurements. In a POVM, we do not care about the resulting state after the measurement; only the probability of a specific outcome $a$. Above, we determined this to be $\tr(M_a\rho M^\dag_a)$. Using a nice property of the trace, $\tr(AB) = \tr(BA)$, we see that $\tr(M_a\rho M^\dag_a) = \tr(M^\dag_aM_a \rho ) = \tr(E_a \rho)$ where $E_a = M^\dag_aM_a$. Given that $\tr(E_a \rho)$ is the probability that we will see outcome $a$, we can think of $E_a$ as a ``probability'' matrix for outcome $a$ that we multiply with $\rho$ to obtain the probability that we measure $a$. Then note that the completeness condition, i.e. Eqn. \ref{eq:phya:completeness}, can be restated as $\sum_{a} E_a = 1$ -- intuitively, this is like $\sum_{i} p_i = 1$ for a probability distribution. So POVM is a generalization of measurement, but in a different flavor.

\fill

\noindent It would appear on the surface that a physically admissible operator $\Phi$ is more powerful than a unitary $U$ because $U$ is just $\Phi$ with $k = 1$, i.e. $\Phi$ has more matrices that we're applying on $\rho$. Surprisingly according to Stinespring's Dilation Theorem, this is not the case - unitaries and physically admissible operators are \emph{equally} powerful. Proving this result is beyond the scope of this class, but the basic idea is that we can simulate any circuit implementing $\Phi$ with a corresponding unitary circuit using some ancilla bits as input to the latter. At a high-level, the diagram looks like the following:
\includegraphics[scale = 0.7]{phisim}
%NOTE: Don't know how to draw the above as a circuit, spent too much time trying to figure it out.

\noindent \Example{4} As an example, let's simulate $\Phi$ as described in Example 1. The following circuit will do the trick:

\centerline{
\Qcircuit @C=1em @R=0.75em {
	\lstick{\ket{0}}   & \targ & \qw & \qw \\
	\lstick{\alpha\ket{0}+\beta\ket{1}} & \ctrl{-1} & \qw & \rstick{\rho' = \Phi(\rho)}
}
}

\fill

\noindent so we see that we've introduced an extra ancillary bit and applied the CNOT gate to do the measurement, discarding the ancilla at the end.

%==============================%
\section{Quantum Information Theory}
%==============================%
So far we talked about the no-cloning theorem (1), distinguishing between two quantum states (2), entanglement (3), and the density matrix formalistm (4). An example of (2) was given in HW. 1 Problem 4. Here Alice and Bob are physically separated, each given one of the qubits of some 2-qubit state; the 2-qubit state is either State I or State II. The problem asked us to devise a strategy they could use to distinguish whether they're sharing State I or State II given that they are allowed to make only local measurements and communicate across a classical channel. An example of (3) was quantum teleportation where we showed that through entanglement, Alice can transmit a 1-qubit state to Bob.

\fill

\noindent In both classical and quantum information theory, we have three important issues that we would like to consider. These are:
\begin{enumerate}[start=0]
\item What is the information comprised of? What is its source? How do we measure the \emph{amount} of information that's being transmitted?
	\begin{itemize}
		\item In the classical world, the source is a random variable $X$. We measure the amount of information using the Shannon entropy, $\se(X)$.

		\item In the quantum world, the source is a mixed state $\rho$. We measure the amount of information using the Von Neumann entropy, $\vne(\rho)$.
	\end{itemize}

\item How do we transmit information over a noiseless channel? To put another way, if we store the information on a physical device, then what is the optimal compression that's possible for storing this information source?
	\begin{itemize}
		\item Given an $m$-bit source, if we want to represent it using only $\alpha\bullet m$ bits where $\alpha < 1$, then Shannon's noiseless source coding theorem says that we can only do so iff $\alpha \geq H(X)$

		\item Given a density matrix $\rho$ on $m$-qubits, if we want to represent it using only $\alpha\bullet m$ qubits where $\alpha < 1$, then Schumacher's noiseless quantum source coding theorem says that we can only do so iff $\alpha \geq S(\rho)$.
	\end{itemize}

\item How do we transmit information over a noisy channel?
	\begin{itemize}
		\item We can do so using error correction codes, ECC.

		\item We can do so using quantum error correction codes, QECC.
	\end{itemize}
\end{enumerate}

\fill

\noindent Imagine that we have a classical source churning out $m$-bit binary strings that are being transmitted on a quantum channel. The information transfer can be summarized by the following steps for a given $n$-bit binary string $x$:
\begin{enumerate}
\item The classical source churns out $x$

\item Some kind of process encodes $x$ as a $\alpha\bullet n$ qubit quantum source $\rho_x$, where $\alpha \leq 1$.

\item $\rho_x$ is transmitted across the quantum channel.

\item $\rho_x$ is decoded at the end to get back $x$.
\end{enumerate}
The question here is whether we can use a shorter quantum message to transmit our classical message, i.e. if we can find an $\alpha < 1$. Unfortunately, we're stuck with $\alpha = 1$ due to Holevo's theorem, which states that it is impossible to communicate more than $n$ bits of classical information when transmitting $n$ qubits.

%==============================%
\section{Entropy}
%==============================%

\subsection{Shannon Entropy}
We think of information as some kind of a message but, as counter-intuitive as it might be, a message may not necessarily contain any ``information''. For example, if all participating parties know the exact contents of the message that's being transmitted, then anybody who opens to read the message does not gain any new ``information'' -- they already know what to expect! So really, it is better to think of ``information'' as the \emph{amount of uncertainty} that's present in a message. The more uncertainty we have in our message, the more ``information'' it contains. For example, an e-mailed job offer would tell you a lot of information because, in general, there are a lot of factors that determine whether you will get the job or not and hence, a lot of uncertainty on whether you will get said job.

\fill

\noindent In physics, entropy is a quantity used to capture the amount of uncertainty in a given system. Similarly, the \emph{Shannon Entropy} quantifies the amount of uncertainty in a given piece of information -- that is why we use the term entropy. Mathematically it is defined as follows. Say we have a source that outputs a random variable $X \in \set{0, 1}^m$ with probability $p_x$. Then we define the Shannon Entropy $\se(x)$ as:
\begin{equation} \label{eq:def-se}
\se(X) = -\sum_{x} p_x \lg{p_x}
\end{equation}
where we define $0\lg{0} = 1$.

\fill

\noindent \Example{5} Let $X \in \set{0, 1}$ where $p_0 = 0$ and $p_1 = 1$. Note that there is no uncertainty involved in $X$ -- we know that our source will always transmit a $1$. Thus we expect that $\se(X) = 0$. Doing the calculation:
\begin{align*}
\se(X)
&= -\sum_{x} p_x \lg{p_x} \\
&= -1\lg{1} \\
&= 0
\end{align*}

\fill

\noindent \Example{6} Let $X \in \set{0, 1}$ where $p_0 = p_1 = 1/2$, i.e. $X$ corresponds to a fair coin. Then we see that:
\begin{align*}
\se(X)
&= -\sum_{x} p_x \lg{p_x} \\
&= -\left(
\frac{1}{2}\lg{\frac{1}{2}} + \frac{1}{2}\lg{\frac{1}{2}}
\right) \\
&= -(-\frac{1}{2} + -\frac{1}{2}) \\
&= 1
\end{align*}
which is exactly 1-bit of information. This is the mathematical definition of a bit.

\fill

\noindent Generalizing Example 6, if we have $X \in \set{0, 1}^m$ and $H(X) = m$, then this corresponds to $m$ fair coins each with 1-bit of information for a total of $m$-bits of information. Note that the Shannon Entropy is non-negative, bounded by the size of %NOTE: I didn't quite hear this part in lecture, so couldn't record it.
It also works well in a syntactic sense in that we can take many independent and identically distributed random variables %NOTE: Didn't hear this part in lecture too, I think it was glazed over.

\subsection{Von Neumann Entropy}
Imagine that we have an $m$-qubit space $\X$, and a source that outputs $k$ pure states with probability $p_k$ for each. Then our source is summarized by the density matrix $\rho_x = \sum_{i} p_i \kera{\psi_i}$. First, note that the quantum source subsumes the classical source as any classical source with $X \in \{0, 1\}^m$ and associated probability $p_x$ is just the densitry matrix $\rho' = \sum_{x \in \set{0, 1}^m} p_x \kera{x}$. %NOTE: In class, we had a density matrix with density matrices p1, p2, ..., pm along its diagonals as being the one that summarizes a classical source. I don't understand why this is the case. The previous sentence makes more sense to me so I included that instead. If it is incorrect, then I apologize.
Let us try to come up with a way to describe the amount of information contained in the density matrix, i.e. its entropy. At a glance, it might seem like we could use $\se$ defined above. Letting $\e(\rho_x)$ denote the entropy quantity of $\rho_x$, we get:
\begin{equation*}
\e(\rho_x) = -\sum_{i} p_i \lg{p_i}
\end{equation*}
However this definition does not work because two different quantum sources can have the same entropy -- entropy is meant to be unique. For example, the quantum source $S_1$ that outputs $\ket{0}$ with probability $1/2$ and $\ket{1}$ with probability $1/2$ is certainly different than the quantum source $S_2$ that outputs $\ket{0}$ with probability $1/2$ and $\ket{+}$ with probability $1/2$ -- the density matrices are not the same! However the probabilities of all the possible pure states in each source are the same, so $\e(S_1) = \e(S_2)$. The intuition is that in the quantum world, we have different bases that we can output our information in such as the standard and Hadamard bases. Further, there is no requirement that the pure states outputted by our source be orthogonal or even form an orthonormal basis -- $S_2$ is an example of one such source. In the classical world, however, everything is in binary -- all our possible sources will output information that's the same representation, so it is enough to just examine the probabilities. But the Shannon Entropy is too limited in the quantum world because we have sources that output different kinds of pure states together.

\fill

\noindent Fortunately, there is a way we can resolve our problem and that is by using the spectral decomposition. Because $\rho$ is positive semi-definite, it has a unique decomposition under the eigenbasis which is:
\begin{equation*}
\rho = \sum_{i = 0}^{d-1} \lambda_i \kera{\psi_i}
\end{equation*}
where $d$ is the dimension of $\rho$'s space, $\lambda_i$ is an eigenvalue, and $\ket{\psi_i}$ is an eigenvector such that $\rho\ket{\psi_i} = \lambda_i \ket{\psi_i}$ and $\bret{\psi_i}{\psi_j} = \delta_{ij}$. Note that $\lambda_i \geq 0$. Because $\tr(\rho) = 1$, we see that $\sum_{i} \lambda_i = 1$ so the eigenvalues form a valid probability distribution. Then we define the Von-Neumann entropy $\vne$ as:
\begin{equation} \label{eq:def-vne}
\vne(\rho) = -\sum_{i = 0}^{d-1} \lambda_i \lg{\lambda_i}
\end{equation}

\fill

\noindent \Example{7} Consider the source summarized by $\rho = \kera{0}$, i.e. a source that always outputs the pure state $\ket{0}$. We would expect that $\vne(\rho) = 0$ since there is no uncertainty in what state we get. This is indeed the case, as $\vne(\rho) = -1\lg{1} = 0$, i.e. $\lambda = 1$ is the only eigenvalue of $\rho$.

\fill

\noindent \Example{8} Consider a fair coin, i.e. the source where $\rho = \frac{1}{2}\kera{0} + \frac{1}{2}\kera{1}$. Here, $\vne(\rho) = 1$ which matches the corresponding classical case. In fact, if we have a mixed state on $n$-qubits where $\rho = \frac{1}{2^n}I$, then $\vne(\rho) = n$.

\end{document}


%
% vecmat3.tex - LaTeX documentation source for vecmat3.h version 2.3.1:
%               Fast 3d vector and matrix classes using expression templates
%
% Copyright (c) 2007-2013  Ramses van Zon
%
% Permission is hereby granted, free of charge, to any person obtaining a copy
% of this software and associated documentation files (the "Software"), to deal
% in the Software without restriction, including without limitation the rights
% to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
% copies of the Software, and to permit persons to whom the Software is
% furnished to do so, subject to the following conditions:
%
% The above copyright notice and this permission notice shall be included in
% all copies or substantial portions of the Software.
%
% THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
% IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
% FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
% AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
% LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
% OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
% THE SOFTWARE.
%

\documentclass[12pt,twoside]{article}

\usepackage{a4wide,fancyhdr,mathptm,charter,color}
%\usepackage[colorlinks]{hyperref}

\pagestyle{fancy}
\renewcommand{\sectionmark}[1]{\markright{#1}}
\fancyhf{}
\fancyhead[LE,RO]{\bfseries\thepage}
\fancyhead[LO]{\bfseries \hfill\rightmark\hfill}
\fancyhead[RE]{\hfill\bfseries\rightmark \hfill}
\fancyfoot[L]{\textit{vecmat3} v2.3.1}
\fancyfoot[R]{\hfill{\color{white}.}\hfill Ramses van Zon\hfill May 15, 2013}
\renewcommand{\headrulewidth}{0.5pt}
\renewcommand{\footrulewidth}{0pt}
\addtolength{\headheight}{2.5pt}
\fancypagestyle{plain}{\fancyhead{}\renewcommand{\headrulewidth}{0pt}}

\newcommand{\Vector}{{Vector}}
\newcommand{\Matrix}{{Matrix}}
\newcommand{\cxx}{C\texttt{++}}
\newcommand{\TT}{{\tt<}T{\tt>}}

\begin{document}

\setlength{\parskip}{1mm}

\title{User Documentation for the  \emph{vecmat3}\\\Vector\ and
  \Matrix\ classes\\(version 2.3.1)}

\author{Ramses van Zon\footnote{vanzonr@gmail.com}}

\date{May 15, 2013}

\maketitle
\begin{abstract}
This document describes how to use the \cxx\ \Vector\ and
\Matrix\ classes defined in the header file vecmat3.h. These classes
offer a very convenient notation for three dimensional vector and
matrix algebra by using overloaded operators.  Furthermore, they are
constructed to be numerically efficient through the internal use of
expression templates, without interfering at the user level.  As a
result, one can convert mathematical matrix-vector expressions
straightforwardly into the corresponding \cxx\ expression without
having to worry about incurring an efficiency penalty.
\end{abstract}

\newpage

\renewcommand{\contentsname}{\vspace{-13mm}}\markright{Contents}
\tableofcontents

\newpage

\section{Introduction}
Vectors and matrices are used frequently in scientific computation (as
well as in modeling, games and movie rendering).  Unfortunately, no
built-in support for matrices and vectors exists in \cxx.  In
principle, expressions involving matrices and vectors, such as
\[
\vec a=\vec b+\mathsf M \cdot \vec c
\]
(with $\vec a$, $\vec b$ and $\vec c$ vectors and $\mathsf M$ a
matrix) can be implemented in \cxx\
such that they strongly resemble their mathematical notations, e.g.
\begin{quote}
\tt
Vector a,b;

Matrix M;

Vector c = a + M*b;
\end{quote}
The technique used to accomplish such notational convenience is
operator overloading, whose straightforward implementation comes with
a high computational cost due to the creation of temporary
objects.

A more efficient implementation is possible by using \emph{expression
templates}.  Efficient matrix-vector implementations are somewhat of a
by-product of \cxx\ templates, and this shows in the awkward and
complicated notation needed for general matrix-vector
manipulations. In addition, the \cxx\ standard is somewhat quirky on
what is and is not allowed when using templates.

These notational issues probably explain why there are far fewer
template-based implementations of matrices and vectors available.
This is especially problematic for small vectors and matrices of fixed
size, for instance three-dimensional ones. These allow additional
efficiency gains over general-size vectors and matrices (because loops
over indices can be replaced by explicit sums in the implementation).
Two known implementations are the \texttt{TinyVector} and \texttt{
TinyMatrix} classes of \texttt{Blitz++} and the ones by the same name of
\texttt{tvmet}. The former is not very developed, i.e., many operations
that one would like to have are not present, and indeed, the latter is
aimed at fixing that. Still, \texttt{tvmet} lacks some functionality that
built-in types do have, for instance, \texttt{TinyVector<3,double> v =
a+b;} is not possible.

This is where \emph{vecmat3} comes in. It defines very efficient
three dimensional vector and matrix manipulations.  The aim is to be
able to use these vectors and matrices as if they were built-in types,
with which the same kind of expressions can be formed as can with
built-in types without worrying about template techniques, but also without
substantial losses compared to hard-coded element-by-element
techniques.

\emph{vecmat3} uses expression templates and operator
overloading. The restrictions of vecmat3 at present are that the
elements of the vectors and matrices have to be of a single type,
which is \texttt{double} by default, and that only three-dimensional
quantities are supported (as the name suggests).

\section*{Change history}
\subsection*{Changes in version 2}

The main difference between the first version of vecmat3 and the
second is that the matrices and vectors no longer need to be all of
one type in a single application.  In addition to the standard Vector
and Matrix classes of type \texttt{DOUBLE} (which defaults to double)
as in version 1, in version 2 one also has three-dimensional
structures of any type \texttt{T} at one's disposal. To be more
precise:
\begin{itemize}
\item \texttt{vecmat3::Vector\TT{}} and \texttt{vecmat3::Matrix\TT{}} are
  three-dimensional vector and matrix classes whose elements are of
  type \texttt{T}.

  For example, one can define a 3x3 matrix of integers as\ \
  \texttt{vecmat3::Matrix<int>~m;}
\item This notation reflects two changes in the code:
\begin{itemize}
\item Almost all of the \texttt{vecmat3} code is now contained in its own
  namespace called \texttt{vecmat3}.
\item The type is a template argument.
\end{itemize}
\item In version 2 the standard Vector and Matrix classes are simply
  typedef'ed as equivalent to \texttt{vecmat3::Vector<DOUBLE>} and
  \texttt{vecmat3::Vector<DOUBLE>}, whereas in version 1 they were the
  only vectors and matrices available.
\item The typedef's of Vector and Matrix will be omitted if the
  compiler flag \texttt{NOVECMAT3DEF} is defined.
\end{itemize}

\subsection*{Changes between version 2 and version 2.3}

(Versions 2.1 and 2.2 were internal development stages.)

\begin{itemize}
\item Most functionality remained the same as in version 2, except that square bracket support has been added. See Section \ref{bracketsnowtoo}.

\item The header file now also enforces inlining the template functions for
the GNU (tested version 4.4.0) and the Intel compilers (tested
versions 11 and 12), even when no optimization is used.

\item A major improvement of version 2.3 is that the library is now
compatible with IBM's xlC compiler, which had trouble with some
template constructions in versions 1 and 2. While I'm on the
subject, one should compile with \texttt{-O4} when using the IBM
compilers with vecmat3 in order to get all inlining done properly (in
the latest version, xlC 11, the options \texttt{-O2 -qinline=level=6} suffice).
\end{itemize}

\subsection*{Changes between version 2.3 and version 2.3.1}

Version 2.3.1 comes with an open-source license (MIT). Here is the
text of the license:
\begin{verbatim}
Copyright (c) 2007-2013 Ramses van Zon

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
\end{verbatim}

\section{Installation}

To use this header-only library, one merely needs to copy the header
file vecmat3.h to the directory of the source files that include it,
or to a default directory where the compiler will look for header
files (e.g. /usr/local/include).

The \emph{vecmat3} library has been tested with the GNU g++ compiler version
4.4 and up, the Intel C++ compiler version 11 and up and IBM's XL C++
compiler version 10 and up.

\section{Using the \Vector\ and \Matrix\ classes}
\label{use}

\subsection{Classes}

\emph{vecmat3} provides two general template classes within the
namespace \texttt{vecmat3}:

\begin{quote}\tt
  template<typename T> vecmat3::Vector;

  template<typename T> vecmat3::Matrix;
\end{quote}
The template parameter T determines the type of the vector and
matrix elements. Thus, for a vector of integers one uses the type
\texttt{vecmat3::Vector<int>}, while for a matrix of doubles one would
use \texttt{vecmat3::Matrix<double>}.

Since applications often need only one type of vector, a default
vector type a and default matrix type are defined outside the
\texttt{vecmat3} namespace, as follows
\begin{quote}\tt

typedef vecmat3::Vector<DOUBLE> Vector;

typedef vecmat3::Matrix<DOUBLE> Matrix;
\end{quote}
Here, DOUBLE is a predefined macro that should contain the type of the
elements of the default vectors and matrices. Thus, \texttt{Vector v;}
defines a vector with elements of type DOUBLE.

The type DOUBLE can be defined in three ways:
\begin{enumerate}
\item One can write an
\texttt{\#define DOUBLE <something>} before including the
\texttt{vecmat3.h} header, with \texttt{<something>} replaced by the
desired type (e.g.\ \texttt{float} or \texttt{double});
\item One can give a command line argument to the compiler to define
  DOUBLE to be \texttt{<something>} (e.g.\ \texttt{-DDOUBLE=float} for
  g++);
\item One can do nothing, which makes \texttt{DOUBLE} default to
\texttt{double}.
\end{enumerate}

The definition of DOUBLE and the type definition of Vector and Matrix
in the global namespace does pollute the global namespace, and in many
cases is not wanted. These definitions are omitted if \texttt{NOVECMAT3DEF} is defined.

\subsection{Header file}

To use \emph{vecmat3}, the following general procedure should be
followed:

\begin{itemize}
  \item If the elements of the vectors and matrices are to have a
  different type than \texttt{double}, first \texttt{\#define} their type as
  \texttt{DOUBLE}, e.g.
  \begin{quote}
    \tt \#define DOUBLE float
  \end{quote}
  The type of the elements of a vector or matrix will be referred to
  as the ``value type'' in this documentation.
  \item Include the header file vecmat3.h:
  \begin{quote}
    \tt \#include "vecmat3.h"
  \end{quote}

  \item The class \Vector\ and the class \Matrix\ are now
  defined and instances these classes can be declared as follows:
    \begin{quote}\tt
      Vector a;

      Matrix R;
    \end{quote}
    \item One can explicitly use any other value type
      than DOUBLE type, e.g.
    \begin{quote}\tt
      vecmat3::Vector<int> a;

      vecmat3::Matrix<int> R;
    \end{quote}
    If vectors and matrices of a specific value type are used a lot in an
    application, it may be useful to typedef them to a shorter
    notation, e.g.
    \begin{quote}\tt
      typedef vecmat3::Vector<int> intVector;

      typedef vecmat3::Matrix<int> intMatrix;

      intVector b;

      intMatrix S;
    \end{quote}
  \item Alternatively, one can have no default global \Vector\ and \Matrix\ class defined, and use only the namespace vecmat3, e.g.
    \begin{quote}\tt
      \#define NOVECMAT3DEF

      \#include "vecmat3.h"

      vecmat3::Vector<double> a;

      vecmat3::Matrix<double> R;
    \end{quote}

      \item In the above examples, the elements of the vectors and
        matrices are unspecified, and likely contain garbage. In the
        next section, it will be explained how to initialize these
        elements of these
        classes.
    \item Note that currently, operations between matrices and vectors
      of different value types are not supported, even when mathematically
      this would make sense (such as for \texttt{int} and
      \texttt{double}).
      \item However, it is possible to assign any kind of number to an
        element of any value type, as long as a (standard)
        conversion to that type is known to the c++ compiler.  Thus,
        one may, for instance, assign an integer to an element of a
        vector, or one may multiply a vector by 2 (i.e., one may write
        \texttt{2*v} instead of being
        forced to write \texttt{2.0*v} or \texttt{2.0f*v}).
\end{itemize}

\subsection{Initialization methods}

There are four ways to initialize a \Vector\ or \Matrix, which we will
discuss by example.  In describing the initialization methods, the
default Vector and Matrix types will be used; the arbitrary type
versions \texttt{vecmat3::Vector\TT{}} and
\texttt{vecmat3::Matrix\TT{}} have the same functionality.

\subsubsection{Initialization through constructor parameters}
  Example:
    \begin{quote}\tt
         Vector a(1.1, 3.0, -4.3);

         Matrix R(1, 2, 3,

\ \ \ \ \ \ \ \ \ 4, 5, 6,

\ \ \ \ \ \ \ \ \ 7, 8, 9);
    \end{quote}
    defines a \Vector\ \texttt a and \Matrix\ \texttt R with specified
    elements. Note that the first set of three elements given to
    \texttt R comprise the top row of \texttt R, the second set of
    three the middle row and the last set of three the bottom row.

    If fewer than three or nine (for \Vector\ and \Matrix,
    respectively) number are given, the unspecified elements are set
    to zero. Thus, one can define a zero \Vector\ and \Matrix\ simply by
    \begin{quote}\tt
         Vector a(0);

         Matrix R(0);
    \end{quote}

  \subsubsection{Initialization through assignment}
  Example:
    \begin{quote}\tt
         Vector b = a;

         Matrix S = R;
    \end{quote}
    defines a \Vector\ \texttt b with the same elements as \texttt a,
    and a \Matrix\ \texttt S with the elements~as~\texttt R.

    The right hand sides may also be an expression involving \Vector's
    and Matrices. The allowed expressions are explained in
    sections \ref{operations} and \ref{expressions}.
%\newpage
  \subsubsection{Initialization through a comma separated list}
  Example:
    \begin{quote}  \tt
         Vector a;

	 a = 1.1, 3.0, -4.3;

         Matrix R;

	 R = 1, 2, 3,

     \ \ \ \ 4, 5, 6,

     \ \ \ \ 7, 8, 9;
    \end{quote}
    Note: this is the standard construction for \texttt{Blitz++} and
    \texttt{tvmet}, and is achieved though an overloaded comma
    operator. Not everybody likes overloading the comma operator,
    because it may confuse the user (more than the above methods), and
    it is somewhat less efficient than the method in 3.2.1.

    Furthermore, it is  not possible to use this method in
    the declaration, i.e., one cannot write \texttt{Vector
    a=1.1,3.0,-4.3;} since \cxx\ would consider this a
    declaration of 3.0 and -4.3 as being of type \Vector.

    If not enough elements are given in the list, the remaining
    elements are set to zero. Thus, one can write
    \begin{quote}\tt
         b = 1;
    \end{quote}
    to get the vector (1,0,0), and
    \begin{quote}\tt
         R = 2;
    \end{quote}
    to get the matrix $\left(\begin{array}{ccc}2&0&0\\0&0&0\\0&0&0\end{array}\right)$.

  \subsubsection{Initialization through member functions}
  Example:
    \begin{quote}\tt
         Vector a;

	 a.zero();

         Matrix R;

	 R.zero();
    \end{quote}
    also define a \Vector\ and \Matrix, respectively, with zero
    elements.

\noindent
    For a \Matrix, there also is a member function {\tt one()} to turn
    it into an identity matrix:
    \begin{quote}\tt
         Matrix S;

	 S.one();
    \end{quote}
    Furthermore, one can initialize a \Matrix\ also per row or column, e.g.
    \begin{quote}\tt
      R.setRow(0,a);

      R.setRow(1,Vector(0,2,0));

      R.setRow(2,Vector(0,2,-1));

      S.setColumn(0,a);

      S.setColumn(1,Vector(0,2,0));

      S.setColumn(2,Vector(0,2,-1));
    \end{quote}
    Note that rows and columns are numbered from 0 to 2.

 \subsubsection{Arrays}
     Example:
    \begin{quote}\tt
         Vector a[3];

         Matrix S[3];
    \end{quote}
    Defines arrays of three Vectors and Matrices which are
    non-initialized. One can initialize these arrays as follows
    \begin{quote}\tt
         Vector a[3] = \{ Vector(1,2,3), Vector(3,4,5), Vector(5,6,7) \};

         Matrix S[3] = \{ Matrix(0), Matrix(1,2,3,4,5,6,7,8,9), Matrix(2) \} ;
    \end{quote}

\subsection{Accessing the elements}
\label{bracketsnowtoo}

There are three ways to assess the elements of Vectors and Matrices:

\begin{enumerate}

\item Basic elements of Vectors and Matrices are generally accessible using the
parenthesis notation, i.e., the elements of a  \Vector\ \texttt a are
\texttt{a(0)}, \texttt{a(1)} and \texttt{a(2)}, while those of a
\Matrix\ \texttt R are \texttt{R(0,0)}, \texttt{R(0,1)}, \dots
\texttt{R(2,2)}.

\item Bracket notation can also be used,
 i.e., the elements of a  \Vector\ \texttt a are
\texttt{a[0]}, \texttt{a[1]} and \texttt{a[2]}, while those of a
\Matrix\ \texttt R are \texttt{R[0][0]}, \texttt{R[0][1]}, \dots
\texttt{R[2][2]}. Note the double brackets for matrix element access.
This way, Vector and Matrix objects act as if they are of type \texttt{T[3]} and \texttt{T[3][3]}, respectively. Accessing the matrix elements in this way may be moderately slower than the parenthesis method (depending on the compiler).

\item Another way to access the elements is though the class members
themselves, i.e., \texttt x, \texttt y and \texttt z for \Vector, and
\texttt{xx}, \texttt{xy}, \texttt{xz}, \texttt{yx}, \texttt{yy},
\texttt{yz}, \texttt{zx}, \texttt{zy} and \texttt{zz} for Matrix. This is
potentially  more efficient, but cannot be used for expressions, i.e.,
\texttt{(A+B).xx} is not possible, unless one writes \texttt{Matrix(A+B).xx}.
\end{enumerate}
Furthermore, the rows and columns of a Matrix can be used as if they
were vectors as follows
\begin{quote}\tt
  Vector v = R.row(1);

  Vector w = R.column(2);
\end{quote}

\subsection{Operators}
\label{operations}

The available algebraic operators for the Vector and Matrix classes
are summarized in table 1, in which '\Vector\TT' stands for
'\texttt{const Vector\TT\&}' or a \Vector-valued expression, and '\Matrix\TT'
stands for '\texttt{const Matrix\TT\&}' or a Matrix\TT-valued expression.

In addition, \texttt{<<} operators are defined for output of Vectors
and Matrices to \texttt{ostream}s, such that
\begin{quote}\tt
  Vector a(1,2,3);

  std::cout << a << endl;
\end{quote}
would print the numbers 1, 2 and 3 with just a space in between.
\begin{quote}\tt
  Matrix<T> M(1,2,3,4,5,6,7,8,9);

  std::cout << M << endl;
\end{quote}
would print a newline, the numbers 1, 2 and 3, another newline, the
numbers 4, 5 and 6, another newline, the numbers 7, 8 and 9 and
finally another newline.

\begin{table}[t]\small
\begin{center}
\begin{tabular}{|rcl|c|c|rcl|}
\hline
 \multicolumn{3}{|c|}{\bf form} & \bf description & \bf example & \multicolumn{3}{c|}{\bf mathematically}\\\hline\hline
%
&\texttt{\textcolor{red}-}
&\texttt{Vector<T>}
& negative
& \tt c = -a;
& $\quad \vec c$&=&$-\vec a$\\
%
\texttt{Vector<T>}
&\textcolor{red}{\texttt +}
&\texttt{Vector<T>}
& add
& \tt c = a + b;
& $\quad \vec c$&=&$\vec a +\vec b$\\
%
\texttt{Vector<T>}
&\textcolor{red}{\texttt -}
&\texttt{Vector<T>}
& subtract
& \tt c = a - b;
& $\quad \vec c$&=&$\vec a -\vec b$\\
%
\texttt{T}
&\textcolor{red}{\texttt *}
&\texttt{Vector<T>}
& multiply with scalar
& \tt c = d * a;
& $\quad \vec c$&=&$d\,\vec a$\\
%
\texttt{Vector<T>}
&\textcolor{red}{\texttt *}
&\texttt{T}
& multiply with scalar
& \tt c = a * d;
& $\quad \vec c$&=&$\vec a\, d$\\
%
\texttt{Vector<T>}
&\textcolor{red}{\texttt /}
&\texttt{T}
& divide by scalar
& \tt c = a / d;
& $\quad \vec c$&=&$\vec a / d$\\
%
\texttt{Vector<T>}
&\textcolor{red}{\texttt \^{}}
&\texttt{Vector<T>}
& cross/outer product$^\dagger$
& \tt c = a \^{} b;
& $\quad \vec c$&=&$\vec a \times \vec b$\\
%
\texttt{Vector<T>}
&\textcolor{red}{\texttt *}
&\texttt{Vector<T>}
& dot/inner product$^\ddagger$
& \tt d = a * b;
& $\quad d$&=&$\vec a \cdot \vec b$\\
%
\ \textcolor{red}( \texttt{Vector<T>}
&\textcolor{red}{\texttt |}
& \texttt{Vector<T>} \textcolor{red})
& dot/inner product$^\ddagger$
& \tt d = (a|b);
& $\quad d$&=&$\vec a \cdot \vec b$\\
%
\hline
%
&\texttt{\textcolor{red}-}
&\texttt{Matrix<T>}
& negative
& \tt T = -S;
& $\quad \mathsf T$&=&$-\mathsf S$\\
%
\texttt{Matrix<T>}
&\textcolor{red}{\texttt +}
&\texttt{Matrix<T>}
& add
& \tt T = S + R;
& $\quad \mathsf T$&=&$\mathsf S +\mathsf R$\\
%
\texttt{Matrix<T>}
&\textcolor{red}{\texttt -}
&\texttt{Matrix<T>}
& subtract
& \tt T = S - R;
& $\quad \mathsf T$&=&$\mathsf S -\mathsf R$\\
%
\texttt{T}
&\textcolor{red}{\texttt *}
&\texttt{Matrix<T>}
& multiply with scalar
& \tt T = d * S;
& $\quad \mathsf T$&=&$d\,\mathsf S$\\
%
\texttt{Matrix<T>}
&\textcolor{red}{\texttt *}
&\texttt{T}
& multiply with scalar
& \tt T = S * d;
& $\quad \mathsf T$&=&$\mathsf S\, d$\\
%
\texttt{Matrix<T>}
&\textcolor{red}{\texttt /}
&\texttt{T}
& divide by scalar
& \tt T = S / d;
& $\quad \mathsf T$&=&$\mathsf S / d$\\
%
\texttt{Matrix<T>}
&\textcolor{red}{\texttt *}
&\texttt{Matrix<T>}
& matrix-matrix product
& \tt T = S * R;
& $\quad \mathsf T$&=&$\mathsf S\,\mathsf R$\\
%
\texttt{Matrix<T>}
&\textcolor{red}{\texttt *}
&\texttt{Vector<T>}
& matrix-vector product
& \tt c = S * a;
& $\quad \vec c$&=&$\mathsf S \, \vec a$\\
%
\hline
%
\texttt{Vector<T>}
&\textcolor{red}{\texttt{+=}}
&\texttt{Vector<T>}
& add
& \tt c += b;
& $\quad \vec c$&=&$\vec c +\vec b$\\
%
 \texttt{Vector<T>}
&\texttt{\textcolor{red}{-=}}
&\texttt{Vector<T>}
& subtract
& \tt c -= b;
& $\quad \vec c$&=&$\vec c -\vec b$\\
%
\texttt{Vector<T>}
&\texttt{\textcolor{red}{*=}}
&\texttt{T}
& multiply by scalar
& \tt c *= d;
& $\quad \vec c$&=&$d\,\vec c$\\
%
\texttt{Vector<T>}
&\texttt{\textcolor{red}{/=}}
&\texttt{T}
& divide by scalar
& \tt c /= d;
& $\quad \vec c$&=&$\vec c/d$\\
%
\texttt{Matrix<T>}
&\texttt{\textcolor{red}{+=}}
&\texttt{ Matrix<T>}
& add
& \tt T += R;
& $\quad \mathsf T$&=&$\mathsf T +\mathsf R$\\
%
 \texttt{Matrix<T>}
&\texttt{\textcolor{red}{-=}}
&\texttt{ Matrix<T>}
& subtract
& \tt T -= R;
& $\quad \mathsf T$&=&$\mathsf T -\mathsf R$\\
%
\texttt{Matrix<T>}&
\texttt{\textcolor{red}{*=}}
&\texttt{T}
& multiply by scalar
& \tt T *= d;
& $\quad \mathsf T$&=&$d\,\mathsf T$\\
%
 \texttt{Matrix<T>}
&\texttt{\textcolor{red}{/=}}
&\texttt{T}
& divide by scalar
& \tt T /= d;
& $\quad \mathsf T$&=&$\mathsf T/d$\\
\hline
\multicolumn{6}{l}{
$^\dagger$ The \texttt \^{} operator has rather low precedence, so
often one has to write \texttt{(a\^{}b)}.
}\\\multicolumn{6}{l}{
$^\ddagger$ Two operators are provided for the dot product, which do
the exact same thing.
}
\end{tabular}
\end{center}
\caption{Operators available for matrices and
  vectors with elements of type \texttt{T}. }
\end{table}

\subsection{Member functions}

For any \Vector, or \Vector-valued expression, or for any \Matrix, or
\Matrix-valued expression, the following properties are available as
member functions. Note that below, {\tt T} stands for the typename of the template, while {\tt Vector\TT{}} and {\tt Matrix\TT{}} stand for {\tt vecmat3::Vector\TT{}} and {\tt vecmat3::Matrix\TT{}}, respectively.  The examples all use {\tt T=DOUBLE}.

\subsubsection{T nrm2()}

This returns the sum of the squares of the elements, which is its norm
squared. E.g., with {\tt T=DOUBLE},
\begin{quote} \tt
  Vector a(1,2,3.316625);

  Matrix R(1,2,0,

\ \ \ \ \ \ \ \ \ 2,0,2

\ \ \ \ \ \ \ \	\ 1,1,1);

  DOUBLE d1 = a.nrm2(); // will be equal to 16.0000014

  DOUBLE d2 = R.nrm2(); // will be equal to 16
\end{quote}

\subsubsection{T nrm()}

This returns the norm of a \Vector\ or \Matrix, e.g., with {\tt T=DOUBLE},
\begin{quote} \tt
  DOUBLE d3 = a.nrm(); // will be equal to 4.00000017

  DOUBLE d4 = R.nrm(); // will be equal to 4
\end{quote}

\noindent
The following properties are for Matrices only:

\subsubsection{T tr()}

This returns the trace of a \Matrix, i.e., the sum of its diagonal
elements. E.g., with {\tt T=DOUBLE},
\begin{quote} \tt
  DOUBLE d5 = R.tr(); // will be equal to 2
\end{quote}

\subsubsection{T det()}

This returns the determinant of a \Matrix, e.g., with {\tt T=DOUBLE},
\begin{quote} \tt
  DOUBLE d6 = R.det(); // will be equal to -2
\end{quote}

\subsubsection{Vector\TT{} row(int i)}
This returns the ith row of a \Matrix.

\subsubsection{Vector\TT{} column(int j)}

This returns the jth column of a \Matrix.

\pagebreak[3]
\subsection{Non-member functions}

In the definition of the following non-member functions, the specified
return type are effective ones. E.g. a return type of Matrix may
return a Matrix-Expression when this is more efficient. In any case, it
can be treated as a Matrix in virtually all ways. Likewise, if an
argument is of Matrix type, a Matrix expression is also allowed.

\subsubsection{Matrix\TT{} Transpose(const Matrix\TT{} \& M)}

Returns the transpose of the argument, which is a \Matrix, e.g.
\begin{quote}\tt
  Matrix S = Transpose(R);
\end{quote}

\subsubsection{Matrix\TT{} Inverse(const Matrix\TT{} \& M)}

Returns the inverse of the argument, which is a \Matrix, e.g.
\begin{quote}\tt
  Matrix S = Inverse(R);
\end{quote}

\subsubsection{Matrix\TT{} Rodrigues(const Vector\TT{} \& v)}

Returns the \Matrix-valued rotation matrix for a rotation along the
axis given by the direction of the \Vector\ argument, with the angle
equal to the norm of that \Vector, e.g.
\begin{quote}\tt
  Matrix S = Rodrigues(a);
\end{quote}

\subsubsection{Matrix\TT{} Dyadic(const Vector\TT{} \& a, const Vector\TT{} \& b)}

Returns the \Matrix-valued dyadic product of two arguments which are
\Vector s, e.g.
\begin{quote}\tt
  Matrix S = Dyadic(a,b);
\end{quote}

\subsubsection{Vector\TT{} MTVmult(const Matrix\TT{} \& M, const Vector\TT{} \& v)}

This simply returns Transpose(Matrix)*Vector.

\subsubsection{T dist(const Vector\TT{} \& a, const Vector\TT{} \& b)}

Returns the length of the difference vector between a and b. This is a
remnant of earlier versions of the \Vector and \Matrix classes, and
barely if at all more efficient than \texttt{(a-b).nrm()}.

\subsubsection{T dist2(const Vector\TT{} \& a, const Vector\TT{} \& b)}

Returns the square length of the difference vector between a and
b. This is a remnant of earlier versions of the Vector and Matrix
classes, and barely if at all more efficient than \texttt{(a-b).nrm2()}.

\subsubsection{T distwithshift(const Vector\TT{}\&a,const Vector\TT{}\&b,const Vector\TT{}\&s)}

Returns the length of the difference vector between a and b shifted by
s. This is a remnant of earlier versions of the vector and Matrix
classes, and barely if at all more efficient than \texttt{(a+s-b).nrm()}.

\vspace{1cm}\pagebreak[3]
Finally, because the notation \texttt{a*b} and \texttt{a\^{}b} for dot and
cross product may be confusing, the following equivalent alternatives
are defined:
\nopagebreak
\subsubsection{T dotProduct(const Vector\TT{} \& a, const Vector\TT{} \& b)}

Returns the DOUBLE which is the dot, or inner, product of the two
\Vector\ arguments.  It is by definition equal to
\texttt{(\texttt{Vector}|\texttt{Vector})}.
Example, with {\tt T=DOUBLE}:
\begin{quote}\tt
  DOUBLE d = dotProduct(a,b);
\end{quote}

\subsubsection{Vector\TT{} crossProduct(const Vector\TT{} \& a, const Vector\TT{} \& b)}

Returns the \Vector\ which is the cross, or outer, product of the two
\Vector\ arguments.  It is by definition equal to
\texttt{(\texttt{Vector}\^{}\texttt{Vector})}.
Example:
\begin{quote}\tt
  Vector c = crossProduct(a,b);
\end{quote}

\section{Expressions}
\label{expressions}

Using the above elementary operations and functions, complex
expressions can be constructed just as for built-in type such as
\texttt{double}. To be more specific, for all operator expressions in table 1
on page 8, the arguments can be expressions themselves.

For example, one can write,
\begin{quote}\tt
  Vector r[2] = \{ Vector(1,4,5), Vector(2,3,4) \};

  Vector v[2] = \{ Vector(1,0,0), Vector(-1,0,0) \};

  Vector s(7,1,0);

  Matrix A(1,0,0,0,1,0,0,-1,0);

  DOUBLE t =  (r[0]+2*A*(s\^{}r[1]) ) | (v[1]-v[0]);

  // alternatively:

  //DOUBLE t =  dotProduct(r[0]+2*A*crossProduct(s,r[1]), v[1]-v[0]);
\end{quote}

Internally, the expressions are not computed directly via temporaries,
but are computed only upon assignment. As a result, the definitions of
these operators and functions in vecmat3.h is not as simple as
e.g. \texttt{Vector operator+(Vector\&,Vector\&)}.  For that reason,
above we used \texttt{Vector} and \texttt{Matrix} wherever a
\Vector/\Matrix\ or a \Vector/\Matrix\ expression can occur. Never
mind the implementation though, things work as expected.

\newpage
\renewcommand{\refname}{Background references}
\begin{thebibliography}{9}
\bibitem{Lippmann}
T. Veldhuizen, \emph{Expression Templates} C++ Report, Vol. 7 No. 5 June
1995, pp. 26-31. See also
http://ubiety.uwaterloo.ca/\~{}tveldhui/papers/Expression-Templates/exprtmpl.html.\\
Reprinted in:
S. B. Lippmann (ed.) \emph{C++ Gems} (Cambridge
  University Press, 1998).
\bibitem{VandevoordeJosuttis} D.\ Vandevoorde and N.\ M.\ Josuttis,
  \emph{C++ Templates: The Complete Guide} (Addison-Wesley, Boston,
  2002).
\bibitem{blitz} http://www.oonumerics.org/blitz
\bibitem{tvmet} http://tvmet.sourceforge.net
\end{thebibliography}
\addcontentsline{toc}{section}{\refname}

\end{document}


\section{Introduction}
\label{sec:introduction}

Full bayesian inference for most neural network is intractable due to the model's nonlinearity causing the true posterior distribution to be highly complex. This has led to the use of variational methods which attempt to approximate the posterior. With regard to bayesian variational inference; this paper addresses the general issue of prior selection to reduce the sensitivity BNNs have toward such initializations and the high variance that arises in the gradients when employing Monte Carlo approximation techniques.

The authors list their contributions as:
\begin{itemize}
	\item Development of a deterministic procedure for propagating uncertain activations through neural networks with uncertain weights and ReLU or Heaviside activation functions.
	\item Development of an EB method for principled tuning of weight priors during BNN training.
	\item Experimental results showing the accuracy and efficiency of our method and applicability to heteroscedastic and homoscedastic regression on real datasets.
\end{itemize}


\documentclass[10pt]{article}
\usepackage[margin=1in]{geometry}

\input{global_macros}
\input{macros}

% Enable (uncolored) cross-reference hyperlinks
% Should always be last package loaded.
% See: https://tex.stackexchange.com/questions/103123/links-do-not-lead-to-right-pages
\usepackage[colorlinks=false]{hyperref}
\begin{document}
  \begin{center}
    {\Large \textbf{Text Classification under Negative Covariate Shift}}

    \vspace{6pt}{\large Project Proposal}

    \vspace{6pt}Zayd Hammoudeh
  \end{center}

  Consider the task of binary (supervised) classification.  Each sample is a tuple of feature vector~${\X \in \domain}$ and label~${\y \in \lbls}$.  Samples are generated from unknown, joint probability distribution~$\joint$.  Given hypothesis class~${\hypoCls=\setbuild{\dec}{\func{\dec}{\domain}{\real}}}$ and loss function~$\func{\loss}{\real \times \lbls}{\real}$, the ideal classifier is:

  \begin{equation}\label{eq:IdealClassifier}
    \dec\opt = \argmin_{\dec \in \hypoCls} \mathbb{E}_{(\X, \y) \sim \joint} \sbrack{\fLoss{\fDec{\X}, \y}}\text{.}
  \end{equation}

  Since $\joint$~is unknown, Eq.~\eqref{eq:IdealClassifier} cannot be determined exactly.  \textit{Empirical risk minimization}, defined in Eq.~\eqref{eq:ERM}, is used in practice for selection of the optimal learner,~${\dec\opt}$. Observe that the true expected loss is replaced with an empirical estimate using i.i.d.\ training set~${\train \sim \joint}$.

  \begin{equation}\label{eq:ERM}
    \dec\opt = \argmin_{\dec \in \hypoCls} \sum_{(\X_i,\y_i) \in \train} \fLoss{\fDec{\X_i}, \y_i}
  \end{equation}

  There are many real-world applications where $\train$~is not an i.i.d.\ sample. For example, given a huge (unlabeled) news corpus, a particular user may only be interested in a single topic,~$\interest$.  There are numerous irrelevant news topics,~${\irrel_1,\ldots,\irrel_n}$ where~$n$ is huge.  This user could label a few relevant articles she manually found as positive~($\pCls$). She could also label any irrelevant articles she encountered negative. Such an ad-hoc labeling mechanism generally induces \textit{covariate shift} (i.e.,~train and test marginal distributions) for the negative class. For instance, the user may fail to label documents from each negative topic~$\irrel_i$. Similarly, the training set's negative topic prior probabilities will not match the corresponding true priors. Constructing a classifier given negative covariate shift is know as \textit{positive, unlabeled, biased negative} (PUbN)~\textit{learning}.

  There are three common approaches to PUbN learning:

  \begin{enumerate}
    \item Supervised (PN -- Positive-Negative) Learning: Ignores the bias in the negative training examples.  Serves as a baseline of comparison and quantifies the effect of any correction.

    \item Positive\-/Unlabeled (PU) Learning: Premised on the idea that using the biased negative training examples can be inherently deleterious.  It constructs a binary classifier strictly using the positive examples and the residual unlabeled corpus.  An example where this approach was used is~\cite{Li:2010}.

    \item Positive, Unlabeled, biased Negative (PUbN) Learning: Constructs a classifier using some \textit{a~priori} knowledge of the negative training set's bias.  Similar to~\cite{Hsieh:2019}, this project assumes knowledge of the negative training sets prior probabilities.
  \end{enumerate}

  \paragraph{Goal} This project will explore negative covariate shift's effect on news topic classification.  The experiments in this section are inspired by Fei \&~Liu~\cite{Fei:2015} and Hsieh\etal~\cite{Hsieh:2019}.

  \paragraph{Experimental Setup} This project will use the 20~newsgroups dataset~\cite{20Newsgroups}.  The dataset statistics are shown in Table~\ref{tab:DatasetComparison}.  We will use the latest (cleaned) version of the dataset published by Jason Rennie where duplicate and empty documents were removed.

  \begin{table}[b]
    \centering
    \caption{Dataset statistics for 20~Newsgroups}\label{tab:DatasetComparison}
    \begin{tabular}{|c|c|c|}
      \hline
      \#~Classes     & 20                     \\\hline
      Train Size     & 13,180                 \\\hline
      Test Size      & 5,648                  \\\hline
      Test Set Prior & Nearly uniform         \\\hline
    \end{tabular}
  \end{table}

  When constructing the experimental datasets, one topic will be selected as the positive class and all remaining~(19) topics will form joint form the negative class.  The experiments will be divided into three categories:

  \begin{itemize}
    \item \textit{In-Training}: All negative subclasses (${\irrel_1,\ldots,\irrel_n}$) are present in both the training and test sets.  The only difference is their train/test marginal distributions.

    \item \textit{Out-of-Training}: Some negative subclasses are only present in the test set. Beside that difference, the train and test marginal distributions are identical.

    \item \textit{Combined}: Synthesis of in-training and out-of-training.  Bias includes missing training set subclasses and a marginal distribution shifts  Most challenging case.
  \end{itemize}

  \noindent
  This procedure will be repeated with different topics as the positive class to ensure as representative of an experiment set as possible.

  \paragraph{Implementation Plan} The PN, PU, and PUbN implementations will share the same standard neural network architecture implemented in PyTorch.  There will be an embedding of some kind (at minimum a word embedding but potentially also character as well), a bidirectional (possibly stacked) RNN, and an output feed forward.

  Where the three learning classes differ is the risk estimator used in gradient descent training.  PN~will use standard logistic loss.  PU~will use the nnPU risk estimator by Kiryo\etal\ in~\cite{Kiryo:2017}.  PUbN will use~\cite{Hsieh:2019}'s risk estimator.

  \bibliographystyle{ieeetr}
  \bibliography{bib/ref.bib}
\end{document}