\documentclass[a4paper,UKenglish,cleveref, autoref]{lipics-v2019}
%This is a template for producing LIPIcs articles.
%See lipics-manual.pdf for further information.
%for A4 paper format use option "a4paper", for US-letter use option "letterpaper"
%for british hyphenation rules use option "UKenglish", for american hyphenation rules use option "USenglish"
%for section-numbered lemmas etc., use "numberwithinsect"
%for enabling cleveref support, use "cleveref"
%for enabling cleveref support, use "autoref"

%\graphicspath{{./graphics/}}%helpful if your graphic files are in another directory

\bibliographystyle{plainurl}% the mandatory bibstyle

\title{Integrality of stable matchings polytope} %TODO Please add

% \titlerunning{Dummy short title}%optional, please use if title is longer than one line

\author{Kishlaya Jaiswal}{Chennai Mathematical Institute }{kishlaya@cmi.ac.in}{}{}%TODO mandatory, please use full name; only 1 author per \author macro; first two parameters are mandatory, other parameters can be empty. Please provide at least the name of the affiliation and the country. The full address is optional

\authorrunning{K. Jaiswal}%TODO mandatory. First: Use abbreviated first/middle names. Second (only in severe cases): Use first author plus 'et al.'

\Copyright{Kishlaya Jaiswal}%TODO mandatory, please use full first names. LIPIcs license is "CC-BY";  http://creativecommons.org/licenses/by/3.0/

%\ccsdesc[100]{General and reference~General literature}
%\ccsdesc[100]{General and reference}%TODO mandatory: Please choose ACM 2012 classifications from https://dl.acm.org/ccs/ccs_flat.cfm

%\keywords{Dummy keyword}%TODO mandatory; please add comma-separated list of keywords

%\category{}%optional, e.g. invited paper

%\relatedversion{}%optional, e.g. full version hosted on arXiv, HAL, or other respository/website
%\relatedversion{A full version of the paper is available at \url{...}.}

%\supplement{}%optional, e.g. related research data, source code, ... hosted on a repository like zenodo, figshare, GitHub, ...

%\funding{(Optional) general funding statement \dots}%optional, to capture a funding statement, which applies to all authors. Please enter author specific funding statements as fifth argument of the \author macro.

%\acknowledgements{I want to thank \dots}%optional

\nolinenumbers %uncomment to disable line numbering

\hideLIPIcs  %uncomment to remove references to LIPIcs series (logo, DOI, ...), e.g. when preparing a pre-final version to be uploaded to arXiv or another public repository

%Editor-only macros:: begin (do not touch as author)%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\EventEditors{John Q. Open and Joan R. Access}
\EventNoEds{2}
\EventLongTitle{42nd Conference on Very Important Topics (CVIT 2016)}
\EventShortTitle{CVIT 2016}
\EventAcronym{CVIT}
\EventYear{2016}
\EventDate{December 24--27, 2016}
\EventLocation{Little Whinging, United Kingdom}
\EventLogo{}
\SeriesVolume{42}
\ArticleNo{23}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\theoremstyle{definition}
\newtheorem*{lemma*}{Lemma}
\newtheorem*{definition*}{Definition}
\newtheorem*{theorem*}{Theorem}
\begin{document}

\maketitle

%TODO mandatory: add short abstract of the document
\begin{abstract}
Given a complete bipartite graph with edge preferences, we know that Gale-Shapley algorithm confirms the existence of (and outputs) a stable matching. Further, we know that perfect matching polytope is integral. We want to add additional constraints corresponding to stability and see if these new constraints still keeps the polytope integral.

U. Rothblum showed that integrality of polytope remains intact even if the preference lists of men and women are incomplete, in his 1992 paper - \textsl{Characterization of stable matchings as extreme points of a polytope}, which I shall present now.
\end{abstract}

\section{Modelling Perfect Matchings}
\label{sec:typesetting-summary}

Consider the problem of determining a perfect matching for complete bipartite graph $(U,V)$ (with $|U|=|V|$). We know that it can be modeled using a system of linear inequalities as follows:

\begin{align}
    \sum_{j \in V} x_{ij} &= 1 & \forall i \in U \\
    \sum_{i \in U} x_{ij} &= 1 & \forall j \in V \\
    x_{ij} &\geq 0 & \forall (i,j) \in U \times V
\end{align}

We have variables $\{x_{ij}\}$ for each edge $(i,j) \in U \times V$, such that $x_{ij} = 1$ iff $(i,j)$ edge is in the matching, otherwise $x_{ij}=0$.

\begin{remark*}
In convex optimization problems, when the underlying polytope is integral, linear programming can be used to solve integer programming problems for the given system of inequalities, a problem that can otherwise be more difficult.
\end{remark*}

So the first question arises is if this polytope $P$ is integral, after the relaxation of variables $0 \leq x_{ij} \leq 1$?

Here is an interesting observation: the matrix $(x_{ij})_{U \times V}$ is a doubly stochastic matrix iff $\{x_{ij}\}$ is a feasible point for the polytope $P$. And furthermore, each perfect matching corresponds to a permutation matrix.

\textsl{Birkhoff-von Neumann} theorem states that polytope $P$ is the convex hull of $U \times V$ permutation matrices and furthermore that the vertices of the polytope $P$ are precisely the permutation matrices. Therefore, the perfect matchings are the extreme (integer) points of this polytope.

% \section{Stable Perfect Matching}

% Returning back to our stable perfect matching problem, we first ask: can the stability constraint be modeled as a linear inequality? And if so, then does the resulting polytope still has the integrality of extreme points?

% Rothblum addressed this problem in a more general setting, that is when lists are incomplete, strict and singlehood is permitted (some vertices can remain unmatched). This is what we shall discuss now.

\section{Stable Matching with Incomplete Lists}

We begin with sets of men $M$ and women $W$ (not necessarily equal in size). Each man $m$ has preference list $W_m \subseteq W$ along with a strict preference order $>_m$ on it, such that $w_1 >_m w_2$ (where $w_1, w_2 \in W_m$) means $m$ prefers $w_1$ over $w_2$. Similarly we have $(M_w, >_w)$ as the preference list for each woman $w$.
% We will assume that the lists are consistent that is $w \in W_m \iff m \in M_w$.

Now since the lists are incomplete, some people might remain unmatched as well. we need to re-setup linear inequalities to denote a matching between men and women:

% =============================================
%  Make the following equations align properly
% =============================================

\begin{align}
    \sum_{j \in W} x_{ij} \leq 1 && \forall i \in M \\
    \sum_{i \in M} x_{ij} \leq 1 && \forall j \in W \\
    x_{ij} \geq 0 && \forall (i,j) \in M \times W
\end{align}

We additionally also want that if a woman doesn't appears in some man's list then that edge variable should be zero, that is, let $A = \{(m,w) \mid m \in M_w \text{ and } w \in W_m\}$ be the set of possible pairs, then

\begin{align}
    x_{ij} = 0 && \forall (i,j) \not \in A
\end{align}

Now we need the final constraint for stability. For that we redefine blocking pair. Given a matching $N$, $(m,w) \in A$ blocks $N$ if any of the following holds:
\begin{itemize}
    \item $m$ and $w$ both have a partner in $N$ but $w >_m N(m)$ and $m >_w N(w)$
    \item Only $m$ has a partner in $N$ but $w >_m N(m)$
    \item Only $w$ has a partner in $N$ but $m >_w N(w)$
    \item Both $m$ and $w$ don't have partners in $N$
\end{itemize}

Hence the stability constraint should be:

\begin{align}
    \sum_{j >_m w} x_{mj} + \sum_{m >_ w i} x_{iw} + x_{mw} \geq 1 && \forall (m,w) \in A
\end{align}

Indeed if $\sum_{j >_m w} x_{mj} + \sum_{m >_ w i} x_{iw} + x_{mw} < 1 \implies \sum_{j >_m w} x_{mj} = \sum_{m >_ w i} x_{iw} = x_{mw} = 0$ which means that either $m$ has no partner or if he does then $w >_m x(m)$ and similarly either $w$ has no partner or if she does then $m >_w x(w)$.

\begin{remark*}
The same stability constraint works in the case of equal sizes of both sets of men and women and complete lists also.
\end{remark*}

We also note that if $\sum_{j >_m w} x_{mj} + \sum_{m >_ w i} x_{iw} + x_{mw} = 1$ then either $m$ and $w$ are matched together or one of them has a strictly better and other has strictly worse partner.

The only other possibility is $\sum_{j >_m w} x_{mj} + \sum_{m >_ w i} x_{iw} + x_{mw} = 2$ which says that both $m$ and $w$ have strictly better partners.
\newline

Finally, we relax our variables to $0 \leq x_{ij} \leq 1$ and discuss the integrality of the polytope $(4)-(8)$: \textsl{the stable matching polytope}.

% \newpage

We begin by showing that every integer point is an extreme point. Before we proceed I'd like to add a remark here that the author directly concludes this as a consequence of Birkhoff theorem. In my opinion, the result is not so straight-forward as feasible points may not be doubly stochastic. So we shall state (and prove) here a generalization of the Birkhoff theorem from which the result shall follow.

\begin{definition*}
A matrix $Q$ is said to be doubly substochastic if its entries are nonnegative and all its row and column sums are at most one.
\end{definition*}
\begin{definition*}
A matrix P is said to be a partial permutation matrix if it has at most one nonzero entry in each row and column, and these nonzero entries (if any) are all $1$.
\end{definition*}
\begin{theorem*}
Every doubly substochastic matrix is a finite convex combination of partial permutation matrices. Conversely, a finite convex combination of partial permutation matrices is evidently double substochastic.
\end{theorem*}
\begin{proof}
Let $Q$ be a doubly substochastic matrix. Consider the matrix $Q' = \begin{bmatrix} Q & I-D_r\\I-D_c & Q^T\end{bmatrix}$, where $D_r$ and $D_c$ are diagonal matrices with the row and column sums of $Q$ respectively. Notice that $Q'$ is now a doubly stochastic matrix and hence we can now apply Birkhoff theorem to complete the proof.
\end{proof}

Here is a simple observation: Let $P$ be a polytope such that all it's integer points are extreme points, then for any subpolytope $Q \subseteq P$ all it's integer points are extreme points.

We mention this because the equations $(4)-(6)$ form a simple polytope where each feasible point can be identified with a substochastic matrix and integral feasible point with a partial permutation matrix, and vice-versa. Hence we can apply our above theorem and observation to conclude that any integer point is an extreme point for the stable matching polytope.
\newline

Conversely, let $\{x_{ij}\}$ be an extreme point. We want to argue that if it is not integral then it can be written as a convex combination of two other feasible points. For that, we consider two extreme matchings which can be extracted out of any feasible solution. Denote by $S_M(x) = \{m \in M \mid \sum_{j \in W} x_{mj} > 0\}$ (men who weren't left unmatched). For $m \in S_M(x)$ let $W^*(x,m)$ and $W_*(x,m)$ be the most preferred woman and the least preferred woman of $m$ in the list $\{w \mid x_{mw} > 0\}$, respectively. Similarly we can define $S_W(x) = \{w \in W \mid \sum_{i \in M} x_{iw} > 0\}$ and maps $M^*(x,w)$ and $M_*(x,w)$ for all $w \in S_W(x)$.

What we shall do is for every man $m \in S_M(x)$ increment the edge variable $(m, W^*(x,m))$ by $\epsilon$ and decrement $(m, W_*(x,m))$ by $\epsilon$. This shall give us another feasible solution. Similarly, if we exchange the increment/decrement in above process, then we get another feasible solution. And then $x$ is the middle point of these two feasible solutions. To make this idea precise, we define our extreme matchings $x^*$ and $x_*$ as follows:

$$
(x^*)_{mw} =
     \begin{cases}
       1 &\quad m \in S_M(x) \text{ and } w=W^*(x,m) \\
       0 &\quad \text{otherwise.} \\
     \end{cases}
$$

$$
(x_*)_{mw} =
     \begin{cases}
       1 &\quad m \in S_M(x) \text{ and } w=W_*(x,m) \\
       0 &\quad \text{otherwise.} \\
     \end{cases}
$$

Observe that $x$ is a matching (integer point) iff $x^*=x_*$ that is both the most preferred and least preferred partner are same. So we consider $z = x^* - x_*$. To proceed, we state a few properties about $z$, corresponding to our original constraints:

\begin{itemize}
    \item $\sum_{j \in W} z_{ij} = 0, i \in M$ (row sums are zero)
    \item $\sum_{i \in M} z_{ij} = 0, j \in W$ (column sums are zero)
    \item $x_{ij} = 0 \implies z_{ij} = 0, (i,j) \in M \times W$
    \item $z_{ij} = 0, (i,j) \not \in A$
    \item $\left(\sum_{j >_m w} x_{mj} + \sum_{m >_ w i} x_{iw} + x_{mw} = 1 \right) \implies \left(\sum_{j >_m w} z_{mj} + \sum_{m >_ w i} z_{iw} + z_{mw} = 0\right)$
\end{itemize}

Assuming these properties, we can choose a small enough $\epsilon > 0$, such that both $x + \epsilon z$ and $x - \epsilon z$ are feasible solutions. Then we re-write $x = \frac{1}{2}(x + \epsilon z) + \frac{1}{2}(x - \epsilon z)$. Since $x$ was an extreme point, we conclude that $z=0$ and hence the integrality of $x$ follows.

To prove above-mentioned properties we shall build some results (which shall be of independent interest) using our intuition from stable marriage with complete lists problem. An essential result we had was men-optimal matching is women-pessimal and vice-versa. Rothblum establishes a similar result here.

\begin{lemma*}
For $(m,w) \in A$,
\begin{itemize}
    \item $\Big( \big(m \not \in S_M(x)\big)$ or $\big(m \in S_M(x)$ and $w \geq_m W^*(x,m)\big) \Big)$ $\implies$ $\Big(\sum_{i \in M} x_{iw} = 1$ and $m \leq_w M_*(x,w)\Big)$ (Converse is also true provided $\sum_{j >_m w} x_{mj} + \sum_{m >_ w i} x_{iw} + x_{mw} = 1$)
    \item $\big( m \in S_M(x)$ and  $w = W^*(x,m) \big) \iff \big( \sum_{i \in M} x_{iw} = 1$ and $m = M_*(x,w) \big)$
    \item $m \in S_M(x) \iff \sum_{j \in W} x_{mj} = 1$
\end{itemize}
\end{lemma*}

The first two points dictate what we said about optimality vs pessimality, whose proofs follow from a simple manipulation of inequalities. But I, particularly, find the last point of more interest as it tells that the row sums are always either $0$ or $1$, which was apriori not at all expected. The proof technique used for this point is equally interesting and moreover helps in establishing the validity of the matchings $x^*$ and $x_*$.

It is clear that that if $\sum_{j \in W} x_{mj} = 1$ then $m \in S_M(x)$. For the converse, Let us consider the set $F_W(x) = \{w \mid \sum_{i \in M} x_{iw}=1\}$ and the map $W^*(x,.) : S_M(x) \rightarrow F_W(x)$ (definition is valid because of the second point in the lemma). Moreover, injectivity also follows from the second point because if $w=W^*(x,m_1)=W^*(x,m_2)$ then $m_1 = M_*(x,w) = m_2$. Now consider the following inequality:

$$|F_W(x)| = \sum_{j \in F_W(x)} \sum_{i \in M} x_{ij} = \sum_{i \in S_M(x)} \sum_{j \in F_W(x)} x_{ij} \leq \sum_{i \in S_M(x)} 1 = |S_M(x)|$$

Implying that it is surjective also and hence equality is achieved in the above equation, which tells us that for $i \in S_M(x)$ $\sum_{j \in F_W(x)} x_{ij} = 1$, completing the proof.

Similarly, with the roles reversed, we have the analogous lemma:
\begin{lemma*}
For $(m,w) \in A$,
\begin{itemize}
    \item $\Big( \big[w \not \in S_W(x)\big]$ or $\big[w \in S_W(x)$ and $m \geq_w M^*(x,w)\big] \Big)$ $\implies$ $\Big(\sum_{j \in W} x_{mj} = 1$ and $w \leq_m W_*(x,m)\Big)$ (Converse is also true provided $\sum_{j >_m w} x_{mj} + \sum_{m >_ w i} x_{iw} + x_{mw} = 1$)
    \item $\big[ w \in S_W(x)$ and  $m = M^*(x,w) \big] \iff \big[ \sum_{j \in W} x_{mj} = 1$ and $w = W_*(x,m) \big]$
    \item $w \in S_W(x) \iff \sum_{i \in M} x_{iw} = 1$
\end{itemize}
\end{lemma*}

I would like to add that since the row and columns sums are always $1$ (or $0$ in case someone remains unmatched), as established by the above lemmas, the exact same proof goes through in the original stable marriage with complete lists instance.

\section{Conclusion}

It is interesting to note that these lemmas indeed add a lot of structure/restrictions on the feasible points. They can be used to give an easy proof for the \textsl{Decomposition property}, which is: if $x$ and $y$ are two stable matchings, and $(m,w)$ is a pair in the matching $x$, then if one of them prefers the matching $x$ over $y$ then their partner prefers the matching $y$ over $x$ - which seems intuitive from our optimality vs pessimality result.

As a last remark, Rothblum adds that in the case of many-to-one matching, for example: students have to be matched to colleges where several students can be matched to a single college, depending upon the number of available seats; our results can be easily extended by cloning each college as many times as available seats in that college, and uniformly ordering them in each student's list.

\section{Further Work}

Following this course, the next immediate question for me to ask would be: What happens if there are ties in the preference lists?

In such a case, the ordering on the preference lists will not be strict one. We have crucially used that strictness in our stability constraint and in the lemmas. So it is interesting to see where would (if) the above lemmas fail?

We have also seen in class that there are different notions of stability in case of ties. So, I would like to study about the following:
\begin{itemize}
    \item Can we model super-stability, strong-stability and weak-stability respectively as linear inequalities?
    \item Will the resulting polytope be integral with those matchings as their extreme points?
\end{itemize}
\end{document}


\chapter{Appendix: \uclid{} Grammar}

\newcommand{\paratitle}[1]{\textsf{\textbf{#1}}}
\newcommand{\nonterminal}[1]{$\langle \textit{#1} \rangle$}

\setlength{\grammarindent}{12em} % increase separation between LHS/RHS

This appendix describes \uclid{}'s grammar.

\section{Grammar of Modules and Declarations}
\paratitle{A model} consist of a list of modules. Each module consists of a list of declarations followed by an optional control block.
\begin{grammar}
     <Model> ::= <Module>*

     <Module> ::= \keywordbf{module} <Id>~~ `{' <Decl>* <ControlBlock>? `}'
\end{grammar}

\paratitle{Declarations} can be of the following types.
\begin{grammar}
     <Decl> ::= <TypeDecl>
            \alt <InputsDecl>
            \alt <OutputsDecl>
            \alt <VarsDecl>
            \alt <SharedVarsDecl>
            \alt <DefineDecl>
            \alt <ConstsDecl>
            \alt <ConstLitDecl>
            \alt <FuncDecl>
            \alt <ProcedureDecl>
            \alt <InstanceDecl>
            \alt <InitDecl>
            \alt <NextDecl>
            \alt <AxiomDecl>
            \alt <SpecDecl>
\end{grammar}

\paratitle{Type declarations} declare either a type synonym or an uninterpreted type.
\begin{grammar}
     <TypeDecl> ::= \keywordbf{type} <Id> `=' <Type> `;'
              \alt \keywordbf{type} <Id> `;'

\end{grammar}

\paratitle{Variable declarations} can refer to inputs, outputs, state variables, symbolic constants, named constant literals, shared variables, or define declarations.
\begin{grammar}
     <InputsDecl> ::=
       \keywordbf{input} ~ <IdList> `:' <Type> `;'

     <OutputsDecl> ::=
       \keywordbf{output} ~ <IdList> `:' <Type> `;'

     <VarsDecl> ::=
       \keywordbf{var} ~ <IdList> `:' <Type> `;'

     <ConstsDecl> ::=
       \keywordbf{const} ~ <IdList> `:' <Type> `;'

     <ConstLitDecl> ::=
       \keywordbf{const} ~ <Id> ~ `:' <Type> = <Number> `;'

     <SharedVarsDecl> ::=
       \keywordbf{sharedvar} ~ <IdList> `:' <Type> `;'

     <DefineDecl> ::=
       \keywordbf{define} <Id> `(' <IdTypeList> `)' `:' <Type> `=' <Expr>  `;'

\end{grammar}

\paratitle{Function declarations} refer to uninterpreted functions.
\begin{grammar}
     <FuncDecl> ::=
       \keywordbf{function} <Id> `(' <IdTypeList> `)' `:' <Type> `;'

\end{grammar}

\paratitle{Procedure declarations} consist of a formal parameter list, a list of return values and types,
followed by optional pre-/post-conditions and the list of state variables modified by procedure.
\begin{grammar}
     <ProcedureDecl> ::=
       \keywordbf{procedure} <Id> `(' <IdTypeList> ')' <ProcReturnArg>? \\
       <RequireExprs> <EnsureExprs> <ModifiesExprs> \\
       <BlkStmt>

     <ProcReturnArg> ::= \keywordbf{returns} `(' <IdTypeList> `)'

     <RequireExprs> ::= ( \keywordbf{requires} <Expr> `;' )*

     <EnsureExprs> ::= ( \keywordbf{ensures} <Expr> `;' )*

     <ModifiesExprs> ::= ( \keywordbf{modifies} <IdList> `;' )*

\end{grammar}

\paratitle{Instance declarations} allow the instantiation (duh!) of other modules. They consist of the instance name, the name of the module being instantiated and the list of mappings for the instances' inputs, output and shared variables.
\begin{grammar}
     <InstanceDecl> ::= \keywordbf{instance} <Id> `:' <Id> <ArgMapList> `;'

     <ArgMapList>   ::= `(' `)'
                    \alt `(' <ArgMap> `,' <ArgMapList> `)'

     <ArgMap> ::= <Id> `:' `(' `)'
              \alt <Id> `:' `(' <Expr> `)'

\end{grammar}

\paratitle{Axioms} refer to assumptions while a \paratitle{specification declaration} refers to design \keywordbf{invariants}. Note \keywordbf{axiom} and \keywordbf{assume} are synonyms, as are \keywordbf{property} and \keywordbf{invariant}.

\begin{grammar}
     <AxiomDecl> ::= <AxiomKW> <Id> `:' <Expr> `;'
                 \alt <AxiomKW> <Expr> `;'

     <AxiomKW> ::= \keywordbf{axiom} | \keywordbf{assume}

     <SpecDecl> ::= <PropertyKW> <Id> `:' <Expr> `;'
                 \alt <PropertyKW> <Expr> `;'

     <PropertyKW> ::= \keywordbf{property} | \keywordbf{invariant}
\end{grammar}

\paratitle{Init} and \paratitle{next} blocks consist of lists of statements.
\begin{grammar}
     <InitDecl> ::= \keywordbf{init} <BlkStmt>

     <NextDecl> ::= \keywordbf{next} <BlkStmt>

\end{grammar}
Assignment statements in the \keywordbf{next} block declaration must
assign primed variables only, and are concurrently evaluated.

\section{Statement Grammar}
\paratitle{Statements} are the following types, most of which should be familiar. Note the support for simultaneous assignment \`a la Python. The keyword \keywordbf{next} allows for synchronous scheduling of instantiated modules.
\begin{grammar}
     <Statement>
       ::= \keywordbf{skip} `;'
       \alt \keywordbf{assert} <Expr> `;'
       \alt \keywordbf{assume} <Expr> `;'
       \alt \keywordbf{havoc} <Id>  `;'
       \alt <LhsList> `=' <ExprList> `;'
       \alt \keywordbf{call} `(' <LhsList> `)' `=' <Id> <ExprList> `;'
       \alt \keywordbf{call} <Id> `(' <ExprList> `)' `;'
       \alt \keywordbf{next} `(' <Id> `)' `;'
       \alt <IfStmt>
       \alt <CaseStmt>
       \alt <ForLoop>
       \alt <WhileLoop>
       \alt <BlkStmt>
\end{grammar}

\paratitle{Block statements} are a list of variables with local scope, and a list of statements.

\begin{grammar}
    <BlkStmt> ::= `{' <BlockVarDecl>* <Statement>* `}'

    <BlockVarDecl> ::= \keywordbf{var} <IdList> `:' <Type> `;'
\end{grammar}

\paratitle{Assignments} and \paratitle{call} statements refer to the nonterminal \nonterminal{LhsList}. As the name suggests, this is a list of syntactic forms that can appear on the left hand side of an assignment. \nonterminal{Lhs} are of four types: (i) identifiers, bitvector slices within identifiers, (iii) array indices, and (iv) fields within records.
\begin{grammar}
    <LhsList> ::= <Lhs> (`,' <Lhs>)*

    <Lhs> ::= <Id>
	  \alt <Id> `''
          \alt <Id> `[' <Expr> `:' <Expr> `]'
          \alt <Id> `[' <ExprList> `]'
          \alt <Id> (`.' <Id>)+
\end{grammar}

\paratitle{If} statements are as per usual. ``Braceless'' if statements are not permitted.
\begin{grammar}
    <IfStmt> ::=
    \keywordbf{if} `(' <CondExpr> `)'  <BlkStmt> \\ \keywordbf{else} <BlkStmt>
    \alt \keywordbf{if} `(' <CondExpr> `)'  <BlkStmt>

    <IfExpr> ::= <Expr> | *
\end{grammar}

\paratitle{Case} statements are as follows.
\begin{grammar}
    <CaseStmt> ::= \keywordbf{case} <CaseBlock>* \keywordbf{esac}

    <CaseBlock> ::= <Expr> `:' <BlkStmt>
                \alt \keywordbf{default} `:' <BlkStmt>
\end{grammar}

\paratitle{For loops} allow iteration over a statically defined range of values.
\begin{grammar}
    <ForLoop> ::= \keywordbf{for} <Id> \keywordbf{in} \keywordbf{range} `(' <Number> ',' <Number> `)' \\
                  <BlkStmt>
\end{grammar}

\paratitle{While loops} allow unbounded iteration.
\begin{grammar}
    <WhileLoop> ::= \keywordbf{while} `(' <CondExpr> `)' \\
                  <InvariantClause>* \\
                  <BlkStmt>

    <InvariantClause> ::= \keywordbf{invariant} <Expr> `;'
\end{grammar}

\section{Expression Grammar}
Let us turn to \paratitle{expressions}, which may be quantified.
\begin{grammar}
    <Expr> ::= <E1>

    <E1> ::= <E2>
         \alt `(' \keywordbf{forall} `(' <IdTypeList> `)' `::' E1 `)'
         \alt `(' \keywordbf{exists} `(' <IdTypeList> `)' `::' E1 `)'

\end{grammar}

The usual logical and bitwise operators are allowed.
\begin{grammar}
    <E2> ::= <E3> `<==>' <E2> | <E3>

    <E3> ::= <E4> `==>' <E3> | <E4>

    <E4> ::=  <E5> `&&' <E4> | <E5> `||' <E4> |
         \alt <E5> `&' <E4> | <E5> `|' <E4> | <E5> `^' <E4>
         \alt <E5>
\end{grammar}

As are relational operators, bitvector concatentation (++) and arithmetic.

\begin{grammar}
<E5> ::=  <E6> <RelOp> <E6> | <E6>

<RelOp> ::= `>' | `<' | `=' | `!=' | `>=' | `<='

<E6> ::=  <E7> `++' <E6> | <E7>

<E7> ::=  <E8> `+' <E7> | <E8>

<E8> ::=  <E8> `-' <E9> | <E9>

<E9> ::= <E9> `*' <E10> | <E9> `/' <E10> | <E10>
\end{grammar}

The unary operators are arithmetic negation (unary minus), logical negation and bitwise negation of bitvectors.
\begin{grammar}
    <E10> ::= <UnOp> <E11> | <E11>

    <UnOp> ::= `-' | `!' | `~'
\end{grammar}

Array select, update and bitvector select operators are defined as follows.
\begin{grammar}
    <E11> ::= <E12> `[' <Expr> (`,' <Expr>)* `]'
          \alt <E12> `[' <Expr> (`,' <Expr>)* `->' <Expr> `]'
          \alt <E12> `[' <Expr> `:' <Expr> `]'
          \alt <E12>
\end{grammar}

Function invocation, record selection, and access to variables in instantiated modules is as follows.
\begin{grammar}
    <E12> ::=  <E13> `(' <ExprList> `)'
          \alt <E13> (`.' <Id>)+
\end{grammar}

And finally, we have the terminal symbols, identifiers, record field access, tuples and the if-then-else operator.
\begin{grammar}
    <E12> ::= \keywordbf{false} | \keywordbf{true} | <Number> | <String>
          \alt <Id> | <Id> `.' <Id>
          \alt `{' <Expr> (`,' <Expr>)* `}'
          \alt \keywordbf{if} `(' <Expr> `)' \keywordbf{then} <Expr> \keywordbf{else} <Expr>
\end{grammar}

Strings can only be used as arguments to the \texttt{print} command in the control block.

\section{Types}

\begin{grammar}
<Type> ::= <PrimitiveType>
       \alt <EnumType>
       \alt <TupleType> | <RecordType>
       \alt <ArrayType>
       \alt <SynonymType>
       \alt <ExternalType>
%%     }
\end{grammar}

Supported primitive types are Booleans, integers and bit-vectors. Bit-vector types are defined according the regular expression `bv[0-9]+' and the number following `bv' is the width of the bit-vector.

\begin{grammar}
    <PrimitiveType> ::= \keywordbf{boolean} | \keywordbf{integer} | <BitVectorType>
\end{grammar}

Enumerated types are defined using the \keywordbf{enum} keyword.
\begin{grammar}
    <EnumType> ::= \keywordbf{enum} `{' <IdList> `}'
\end{grammar}

Tuple types are declared using curly brace notation.
\begin{grammar}
    <TupleType> ::= `{' <Type>  (`,' <Type>)* `}'
\end{grammar}

Record types use the keyword \keywordbf{record}.
\begin{grammar}
    <Recordtype> ::= \keywordbf{record} `{' <IdTypeList> `}'
\end{grammar}

Array types are defined using square brackets. The list of types within square brackets defined the array's index type.
\begin{grammar}
    <ArrayType> ::= `[' <Type> (`,' <Type>)* `]' <Type>
\end{grammar}

Type synonyms are just identifiers, while external types refer to synonym types defined in a different module.
\begin{grammar}
    <SynonymType> ::= <Id>

    <ExternalType> ::= <Id> `.' <Id>
\end{grammar}

\section{Control Block}
\paratitle{The control block} consists of a list of commands. A command can have an optional result object, an optional argument object, an optional list of command parameters and finally an optional list of argument expressions.
\begin{grammar}
     <ControlBlock> ::= \keywordbf{control}~~ `{' <Cmd>* `}'

     <Cmd> ::= (<Id> `=' )? (<Id> `.')? <CmdName> \\
              (`[' <IdList> `]')? <ExprList>? `;'
\end{grammar}

The following is a list of currently accepted commands.

\begin{grammar}
    <CmdName> ::= `bmc' \alt
                  `bmc_LTL' \alt
                  `bmc_noLTL' \alt
                  `check' \alt
                  `clear\_context' \alt
                  `induction' \alt
                  `print' \alt
                  `print\_cex' \alt
                  `print\_module' \alt
                  `print\_results' \alt
                  `print\_smt2'
                  `synthesize\_invariant' \alt
                  `unroll' \alt
                  `verify'
\end{grammar}

\section{Miscellaneous Nonterminals}

\nonterminal{IdList}, \nonterminal{IdTypeList} and \nonterminal{ExprList} are non-empty, comma-separated list of identifiers, identifier/type tuples and expressions respectively.
\begin{grammar}
     <IdList> ::= <Id> \alt <Id> `,' <IdList>

     <IdTypeList> ::=  <Id> (`,' <Id>)* `:' <Type>
                  \alt <Id> (`,' <Id>)* `:' <Type> `,' <IdTypeList>

     <ExprList> ::=  <Expr>
                \alt <Expr> `,' <ExprList>
\end{grammar}


\documentclass[a4paper,12pt]{article}
\usepackage{graphicx}
\author{Didrik Jonassen, Imre Kerr}
\title{Project 1B\\ IT3708 --- Subsymbolic methods in AI}
\date{\today}

\begin{document}

\maketitle

\section{Representation and Development}
We chose to represent the chromosome as a binary vector of length $4B$. Every four bits are interpreted as a binary number, meaning that the genome codes for $B$ integers between 0 and 15. These integers are then normalized so they all sum to 1, and the resulting fractions are the troop deployment for each battle.

\section{Strategy Entropy}
Strategy entropy is a measure of how ``spread out'' the troops are for a given strategy. Putting all troops in one battle gives minimum entropy, and spreading them evenly over all battles gives maximum entropy. This is interesting because it characterizes a strategy as a single number, letting you get the gist of the strategy without having to interpret the deployment numbers themselves.

\section{EA Parameters}
\begin{tabular}{|l|l|}
\hline
Parameter & value \\
\hline \hline
Population Size & 20 \\
Mutation Rate & $\frac{1}{40B}$ \\
Crossover Rate & 100\% \\
Selection Mechanism & Fitness Proportionate \\
Selection Protocol & Generational Mixing \\
Litter size & 20 \\
Generations & 400 \\
\hline
\end{tabular}

\section{Base Case Summary}
\begin{tabular}{|c|c|c|l|}
\hline
B & R_{f} & L_{f} & Notes \\
\hline \hline
5 & 0 & 0 & Switches between various strategies putting everything on two battles \\
5 & 0 & 1 & Puts everything on battle 1 \\
5 & 0 & 0.5 & Same as (5,0,0), but weighted towards the first of the two \\
5 & 1 & 0 & Spread out, weighted towards the earlier battles \\
5 & 1 & 1 &  All on battle 1 \\
5 & 1 & 0.5 & All on battle 1 \\
5 & 0.5 & 0 & Switches between various 2-battle strategies \\
5 & 0.5 & 1 & All on battle 1 \\
5 & 0.5 & 0.5 & All on battle 1 \\
20 & 0 & 0 & Converges toward fewer battles, step by step \\
20 & 0 & 1 & Same as B = 5, but slower\\
20 & 0 & 0.5 & Same as B = 5, but slower \\
20 & 1 & 0 & Switches between different strategies involving the 10 first battles \\
20 & 1 & 1 & Same as B = 5, but slower \\
20 & 1 & 0.5 & Same as B = 5, but slower \\
20 & 0.5 & 0 & Switches between different strategies with no clear pattern \\
20 & 0.5 & 1 & Same as B = 5, but slower \\
20 & 0.5 & 0.5 & Same as B = 5, but slower \\
\hline
\end{tabular}
You'll notice that the descriptions for most the B=20 runs were the same. They did however provide us with a clearer look at what was going on, so these runs were not wasted.

\section{Signature Cases}
For each of these cases we give:
\begin{itemize}
\item{an entropy plot showing the average entropy in the population}
\item{a fitness plot showing the best, worst and average (plus/minus std.dev.) fitness in the population}
\item{and a strategy plot, which is a visualization of the winning strategy in each generation. The horizontal axis is generations, and the vertical axis is normalized troop deployment. This plot makes it very easy to see what the dominant strategy looks like at any given point.}
\end{itemize}
\subsection{Case 1: $B=5, R_{f}=0, L_{f}=1$}
\centerline{\includegraphics[width=1.2\textwidth]{case1}}
This case quickly converges towards putting all troops on the first battle. This is not surprising, since having $L_{f}=1$ means that losing the first battle will make the morale zero for all the following battles. This is true for all cases with $L_{f}=1$.

\subsection{Case 2: $B=20, R_{f}=0, L_{f}=0$}
\centerline{\includegraphics[width=1.2\textwidth]{case2}}
\small{(There are two distinct regions that unfortunately both happened to be blue.)}\\
This case gradually converges towards a strategy involving putting everything on two battles, with the trend being one less battle every few generations. We think this can be explained as follows: In order to mutate an n-battle strategy into an (n-1)-battle strategy that beats the original, only one of the battles needs to have a lower weight, and all the other weights will rise as a result. Conversely, if an (n+1)-battle strategy is to beat an n-battle strategy, more than one of the battles needs to get an updated value. Thus it is easier to find winning strategies with lower numbers of battles, so it converges towards lower numbers, with the limit being 2.

\subsection{Case 3: $B=20, R_{f}=1, L_{f}=0$}
\centerline{\includegraphics[width=1.2\textwidth]{case3}}
Here we see a chaotic switching between strategies involving approximately the first half of the battles. Weighting towards earlier battles makes sense due to redeployment, but other than that this one is hard to explain. We made the strategy plot greyscale for this one in order to better see which battles were included in the strategy.

\section{Brief Discussion}
In the cases where there exists an optimal solution, we see that co-evolution finds this solution quite quickly. In the more complex cases, for any given strategy there is a strategy that can beat it, and this will eventually be found. The limiting factor in these cases is how easy it is to get to that strategy by random mutation. This has parallels in biology, where most change we observe is gradual, with quantum leaps being quite rare.

\end{document}


\chapter{Code Structure}\label{structure}

Roughly the code structure is displayed in Fig.\ref{graph}. For more accurate and detailed description, run Doxygen utility and refer the generated documentation.

\begin{figure}[H]
	\begin{center}
		\includegraphics[width=0.8\textwidth]{graph.pdf}
		\caption{\label{graph} Class dependency (crudely)}
	\end{center}
\end{figure}

Each of the the constituent elements are briefly described next.

\section{Code structure}
\subsection{Tensor}
MEANDG has a central datastructure called as `Tensor', which forms all the important arrays, matrices, multidimensional storage lists etc.
Refer `include/Tensor' for details. Tensor class is made of 4 sub-classes.
\begin{verbatim}
TensorO1<dType>, TensorO2<dType>, TensorO3<dType>, Matrix<dType>
\end{verbatim}
From these, $O(1), O(2), O(3)$ tensors can be created of arbitrary dimensions. The tensor objects interact with one another and
have several in-build methods such as $L_1, L_2, L_\infty$ norms etc. All the maths functions accept objects of Tensor library.

Following example code shows usage of tensor class:
\begin{verbatim}
TensorO1<double> A(5);		// creates a O(1) tensor of size 5 with
				// data-members of the type double
TensorO1<double> C(5);

for (int i=0; i<5; i++){
	// generate a random number between 0 and 100
	double valueA = getRandom(0.0,100.0);
	// generate another random number between 0 and 100
	double valueC = getRandom(0.0,100.0);

	// set value at ith index
	A.setValue(i, valueA);
	C.setValue(i, valueC);
};
// now A and C have random values

double dotAnswer = Math::dot(A,C);		// perform math product between two arrays
cout << dotAnswer << endl;			// print the answer

\end{verbatim}

For further details and the available functions, refer the code documentation.

\subsection{Point}
Point is a physical point in $(x,y,z)$ coordiante system. It has a unique id, and description of its location.

\subsection{Cell}
If the domain is indicated by $\Omega$, then the descritization of the domain ($\Omega_h$) is described as,
\begin{equation}
	\Omega_h = \bigcup\limits_{l = 1}^ n S_i
\end{equation}
where $S_i$ are the finite volume cells. These are non-overlapping pieces of the domain.
Each cell has the following important attributes (among others):
\begin{itemize}
	\item Vertices (of the type `Point')
	\item Faces (i.e. boundary of the cell)
	\item Degrees of Freedom (i.e. locations where unkowns are evaluated)
	\item Data (such as the conserved variables)
	\item Volume
	\item Mathematical constructs (Mass matrix, Stiffness matrix etc.)
	\item Mapping onto the standart cell (Jacobian etc.)
\end{itemize}

Thus, each of these parameters (among others) can be accessed using the accessor (get, set) functions of the class `Cell'.
For further details, refer Cell.h and Cell.cpp.

\subsection{Face}
A face is the boundary of a Cell. The face has following important attributes:
\begin{itemize}
	\item Geometrical information (area, normal, vertices etc.)
	\item Neighbour and Owner cells
	\item Data (numerical flux and variables)
	\item Mapping (Jacobian etc.)
\end{itemize}

\subsection{GeometryIO}
This module reads the input file in the OpenFOAM format and fills the data arrays. Refer:
\begin{verbatim}
GeometryIO::fillDataArrays(args)
\end{verbatim}

\subsection{Functional Space}
This module is responsible for everything related to $L^2, H^1$ functional spaces. It contains nodal, modal basis functions and derivatives.
It also computes various matrices used in DG formulation.

\subsection{Math functions}
These are various mathematical functions.

\subsection{Gasdynamics, Riemann solvers etc.}
Depending on the system of equations which one wants to solve, include the physics-specific functions and files. For example, for
Euler's equations of Gasdynamics, we have Gasdyanmics.cpp module and corresponding Riemann solvers.
Apart from these, there are test functions, display functions etc. Refer the code files in `include/' and `src/' folders.

\subsection{DG}
This is the core (central) module of the code. It performs following operations:
\begin{itemize}
	\item Memory management
	\item Cells, faces creation
	\item Calling appropriate functions for computation of cell matrices
	\item Time integration
	\item PDE solving
\end{itemize}

Currently it is configured to solve the hyperbolic system of PDEs of the type:
\begin{equation}
	\frac{\partial {Q}}{\partial{t}} + \nabla .  {\bf F}(Q) = 0
\end{equation}


\section{Overview}
From earlier calibration versions of data from the autocorrelators
of Odin-SMR we know that calibrated spectra from both high and
low altitudes contain spectral features not caused by the atmospheric
species.
This short report contains a likely explanation
of how these spectral features are induced
and how they affect the spectra.

\clearpage
\newpage

\section{Spectral features in spectra}
\begin{figure}[!t]
\centering
\includegraphics[scale=0.7]{odinspectrumpattern.png}\\
\caption{Wave induced pattern in calibrated spectra. The red line represents
a perturbed brightness temperature spectrum of the
hot load (a cosinus wave with eight cycles is added)
The blue line represents a perturbed brightness temperature
spectrum of the cold sky (a cosinus wave with four cycles is added).
The thin red lines represent perfectly calibrated spectra.
The green lines show what features the cosinus waves of the
references induce on calibrated spectra if they are not taken into account.
}
\label{fig:study2ac2a}
\end{figure}

From earlier calibration versions of data from the autocorrelators
of Odin-SMR we know that calibrated spectra from both high and
low altitudes contain spectral features not caused by the atmospheric
species.
The spectral features, which are different at low and and high altitudes,
are instead caused by the instrument itself and not taken into account
in the calibration process.

The calibration process (level1a to level1b) is based on that we have
measurements of the clod sky (\(C_{s}(f)\) at 2.7 K), hot load (\(C_{L}(f)\)
at around 290 K), and the target atmosphere (\(C_{A}(f)\)
at unkown temperature \(T_{A}\)).
The calibration process can be understand as a linear interpolation
of \(C_{A}(f)\)  using \(C_{s}(f)\) and \(C_{L}(f)\) and their temperatures
as references.

The calibration process assumes that both the cold sky and hot load signal
are clean. Figure~\ref{fig:study2ac2a} shows an example of what would happen with
calibrated spectra if these signals are not clean
(but the target signal is clean).
In the example the blue line represents a perturbed brightness temperature
spectrum of the cold sky (a cosinus wave with four cycles is added).
The red line represents a perturbed brightness temperature spectrum of the
hot load (a cosinus wave with eight cycles is added).
The thin red lines can be interpreted as perfectly calibrated spectra.

The green lines show what features the cosinus waves of the
references induce on calibrated spectra if they are not taken into account:

At low brightness temperatures this pattern is caused by the
the wave on the cold sky signal (and 180 degree phase shifted
w.r.t. wave on the cold sky signal).

At high brightness temperatures this pattern is caused by the
the wave on the hot load signal (and 180 degree phase shifted
w.r.t. wave on the hot load signal).

At intermediate brightness temperatures the pattern is a linear
combination of the mentioned pattern,
i.e. (using the equations in the figure)
\begin{equation}
\Delta T=c \cdot cos\left(\frac{f2\pi}{d}+\pi\right) \cdot (1-w(f))
+a \cdot cos \left( \frac{f2\pi}{b}+\pi \right) \cdot w(f)
\end{equation}
where
\begin{equation}
w(f)=\frac{C_{A}(f)-C_{s}(f)}{C_{L}(f)-C_{S}(f)}\approx\frac{T_{A}(f)}{T_{L}(f)}
\end{equation}

\section{Odin data}
\subsection{AC2}
\begin{figure}[!t]
\centering
\includegraphics[scale=0.7]{ac2spechigh.png}\\
\caption{High tangent altitude median spectrum from AC2 (strat 1).}
\label{fig:study2spec1}
\end{figure}

\begin{figure}[!t]
\centering
\includegraphics[scale=0.7]{ac2speclow.png}\\
\caption{Low tangent altitude median spectrum from AC2 (strat 1).}
\label{fig:study2spec2}
\end{figure}

\begin{figure}[!t]
\centering
\includegraphics[scale=0.7]{ac2spec1015.png}\\
\caption{Intermediate tangent altitude median spectrum from AC2 (strat 1).}
\label{fig:study2spec3}
\end{figure}

\begin{figure}[!t]
\centering
\includegraphics[scale=0.7]{ac2spec1520.png}\\
\caption{Intermediate tangent altitude median spectrum from AC2 (strat 1).}
\label{fig:study2spec4}
\end{figure}

\begin{figure}[!t]
\centering
\includegraphics[scale=0.7]{ac2spec3035.png}\\
\caption{Intermediate tangent altitude median spectrum from AC2 (strat 1).}
\label{fig:study2spec5}
\end{figure}

\begin{figure}[!t]
\centering
\includegraphics[scale=0.7]{ac2spec4045.png}\\
\caption{Intermediate tangent altitude median spectrum from AC2 (strat 1).}
\label{fig:study2spec6}
\end{figure}

\begin{figure}[!t]
\centering
\includegraphics[scale=0.7]{ac2spec5560.png}\\
\caption{Intermediate tangent altitude median spectrum from AC2 (strat 1).}
\label{fig:study2spec7}
\end{figure}
\clearpage
\newpage
\subsection{AC1}
\begin{figure}[!t]
\centering
\includegraphics[scale=0.7]{ac1spechigh.png}\\
\caption{High tangent altitude median spectrum from AC1 (strat 2).}
\label{fig:study2spec8}
\end{figure}

\begin{figure}[!t]
\centering
\includegraphics[scale=0.7]{ac1speclow.png}\\
\caption{Low tangent altitude median spectrum from AC1 (strat 2).}
\label{fig:study2spec9}
\end{figure}

\begin{figure}[!t]
\centering
\includegraphics[scale=0.7]{ac1spec4045.png}\\
\caption{Intermediate tangent altitude median spectrum from AC1 (strat 2).}
\label{fig:spec1}
\end{figure}

\begin{figure}[!t]
\centering
\includegraphics[scale=0.7]{ac1spec5560.png}\\
\caption{Intermediate tangent altitude median spectrum from AC1 (strat 2).}
\label{fig:spec1}
\end{figure}


\documentclass{beamer}

\input{../../shared_slides.tex}

\title{Projected Gradient Descent}

\begin{document}
\maketitle
\frame{\tableofcontents}

\section{Introduction}%

\begin{frame}
  \frametitle{Constrained Optimization}

  \begin{minipage}{0.5\textwidth}
    \begin{block}{Constrained optimization problem}
      \begin{equation}
        \begin{aligned}
          \text{minimize } & f(x)\\
          \text{subject to } & x\in C
        \end{aligned}
      \end{equation}
      \textcolor{blue}{How to solve them}
      \begin{itemize}
        \item Project onto $C$
        \item transform to \textit{unconstrained problem}
      \end{itemize}
    \end{block}
  \end{minipage}
  \begin{minipage}{0.45\textwidth}
    \begin{figure}[ht]
      \centering
      \includegraphics[width=\textwidth,height=\textheight,keepaspectratio]{constrained_3d}
      % \caption{\label{fig:label} }
    \end{figure}
  \end{minipage}
\end{frame}

\begin{frame}
  \frametitle{Constrained Optimization}

  \begin{minipage}{0.5\textwidth}
    \begin{block}{Constrained optimization problem}
      \begin{equation}
        \begin{aligned}
          \text{minimize } & f(x)\\
          \text{subject to } & x\in C
        \end{aligned}
      \end{equation}
      \end{block}
      \textcolor{blue}{We will focus on:}
      \begin{itemize}
        \item \textbf{Projected Gradient Descent}
      \end{itemize}
  \end{minipage}
  \begin{minipage}{0.45\textwidth}
    \begin{figure}[ht]
      \centering
      \includegraphics[width=\textwidth,height=\textheight,keepaspectratio]{constrained_3d}
      % \caption{\label{fig:label} }
    \end{figure}
  \end{minipage}
\end{frame}

\section{Projection}%
\label{sec:}

\begin{frame}
  \frametitle{Projected Gradient Descent}

  \textcolor{blue}{Idea:} After every step project back onto the set: $\Pi_C(x) :=\argmin_{y\in C} \Vert y-x \Vert$.

    \begin{figure}[ht]
      \centering
      \includegraphics[width=\textwidth,height=0.7\textheight,keepaspectratio]{test}
      % \caption{\label{fig:label} }
    \end{figure}

\end{frame}

\begin{frame}
  \frametitle{Projected subgradient method}
  \begin{equation}
    \text{(constrained setting)} \quad \min_{x\in C}\, f(x)
  \end{equation}
  \begin{algorithm}[H]
    \caption{Projected subgradient method}\label{label:}
    \begin{algorithmic}[1]
      \For{$k=0, 1, \dots$}
      \State{Pick $g_k \in \partial f(x_k)$}
      \State{$y_{k+1} =  x_k- \alpha g_k $}
      \State{$x_{k+1} = \Pi_C(y_{k+1})$}
      \EndFor
    \end{algorithmic}
  \end{algorithm}
\end{frame}

\begin{frame}
  \frametitle{Properties of the Projection}
  \begin{block}{Fact}
    Let $C\subseteq \R^d$ be closed and convex, $x\in C$ and $y \in \R^d$.Then
    \begin{itemize}
      \item $\langle x- \Pi_C(y), y - \Pi_C(y)  \rangle \le 0$
      \item $\Vert x - \Pi_C(y) \Vert^2 + \Vert y - \Pi_c(y) \Vert^2 \le \Vert y-x \Vert^2$
    \end{itemize}
  \end{block}
  \begin{figure}[ht]
    \centering
    \includegraphics[height=0.5\textheight,keepaspectratio]{projection_property}
    % \caption{\label{fig:label} }
  \end{figure}

\end{frame}

\begin{frame}
  \frametitle{Properties of the Projection}
  \begin{block}{Fact}
    Let $C\subseteq \R^d$ be closed and convex, $x\in C$ and $y \in \R^d$.Then
    \begin{itemize}
      \item $\langle x- \Pi_C(y), y - \Pi_C(y)  \rangle \le 0$
      \item $\Vert x - \Pi_C(y) \Vert^2 + \Vert y - \Pi_c(y) \Vert^2 \le \Vert y-x \Vert^2$
    \end{itemize}
  \end{block}
  \begin{proof}
    Since $\Pi_C(x)$ is the minimizer of a differentiable convex function $d_x(y) =\frac12 \Vert y-x \Vert^2$ over $C$, by the \textbf{first-order optimality condition}
    \begin{align}
      0 &\le \langle \nabla d_x(\Pi_C(x)), y - \Pi_C(x) \rangle \\
        &= \langle \Pi_C(x) - x, y - \Pi_C(x) \rangle
    \end{align}
  \end{proof}
\end{frame}

\begin{frame}
  \frametitle{Results for projected GD}
  For \textbf{closed}, \textbf{convex} set $C\subset \R^d$ \textcolor{blue}{same} number of gradient steps.
  \begin{itemize}
    \item Lipschitz convex function over $C$: $\mathcal{O}(\epsilon^{-2})$ steps
    \item Smooth convex function over $C$: $\mathcal{O}(\epsilon^{-1})$ steps
    \item Smooth and strongly convex over $C$: $\mathcal{O}(\log(\epsilon^{-1}))$
  \end{itemize}

  But:
  \begin{itemize}
    \item Each step requires a projection onto $C$
    \item May or may not be easy to compute
  \end{itemize}

\end{frame}

\begin{frame}
  \frametitle{The projection step: $\Pi_C(x) := \argmin_{y\in C} \Vert y-x \Vert$}
  Computing $\Pi_C(x)$ is an optimization problem itself.

  Efficient in relevant cases:
  \begin{itemize}
    \item Box constraints: $C= [a_1, b_1] \times \dots \times [a_d, b_d]$
    \item Affine subspace (requires solution of system of linear equations)
          \begin{figure}[ht]
            \centering
            \includegraphics[scale=.12]{projection_onto_affine_space}
          \end{figure}
    \item Projection onto ball with center $c$
          \begin{figure}[ht]
            \centering
            \includegraphics[scale=.2]{projection_onto_ball}
          \end{figure}
  \end{itemize}
\end{frame}

\begin{frame}
  \frametitle{Convergence analysis}
  \begin{proof}
    We can deduce the exact same inequality as before
    \begin{equation}
      \begin{aligned}
        \Vert x_{k+1} - x^* \Vert^2 &= \Vert \Pi_C(x_k - \alpha g_k) - \Pi_C(x^*) \Vert^2 \\
        &\le \Vert x_k - \alpha g_k - x^* \Vert^2 \\
        &= \Vert x_k-x^* \Vert^2 + 2 \alpha \langle g_k, x^*-x_k \rangle + \alpha^2 \Vert g_k \Vert^2\\
        &\le \Vert x_k-x^* \Vert^2 + 2 \alpha (f^* - f(x_k))+ \alpha^2 \Vert g_k \Vert^2.
      \end{aligned}
    \end{equation}
    Continue the proof as in the unconstrained setting.
  \end{proof}
\end{frame}

\section{Proximal Gradient}%
\label{sec:}

\begin{frame}
  \frametitle{Composite minimization problem}

  Consider objective function composed as
  \begin{equation}
    f(x) = g(x) + h(x)
  \end{equation}
  where
  \begin{itemize}
    \item $g$ is \textcolor{blue}{nice}
    \item $h$ is \textcolor{blue}{simple}
  \end{itemize}
  typically we mean nice means smooth. Relevant if $h$ is not differentiable.
  Most notably: Lasso

\end{frame}

\begin{frame}
  \frametitle{Idea}
  Classical gradient step for $g$:
  \begin{equation}
    x_{k+1} = \argmin_{x} g(x_k) + \langle \nabla g(x_k), x-x_k \rangle + \frac{1}{2 \alpha} \Vert x-x_k \Vert^2
  \end{equation}
  Now, for $f= g+h$ we keep this for $g$ and add $h$ \textcolor{blue}{unmodified}:
  \begin{align}
    x_{k+1} &= \argmin_{x} g(x_k) + \langle \nabla g(x_k), x-x_k \rangle + \frac{1}{2 \alpha} \Vert x-x_k \Vert^2 \textcolor{red}{+ h(x)} \\
    &= \argmin_x \frac{1}{2 \alpha} \Vert x - (x_k - \alpha \nabla g(x_k)) \Vert^2 + h(x)
  \end{align}
\end{frame}

\begin{frame}
  \frametitle{The proximal gradient algorithm}

  An iteration is defined as
  \begin{block}{}
  \begin{equation}
    x_{k+1} = \prox{\alpha h}{x_k - \alpha \nabla g(x_k)}
  \end{equation}
  \end{block}
  where the \textcolor{blue}{proximal mapping} for a function $h$ and parameter $\alpha$ is defined as
  \begin{equation}
    \prox{\alpha h}{x} = \argmin_{y \in \R^d} \left\{ h(y) + \frac{1}{2 \alpha} \Vert y-x \Vert^2\right\}.
  \end{equation}

\end{frame}

\begin{frame}
  \frametitle{A generalization of (projected) GD}

  \begin{itemize}
    \item $h \equiv 0$ recovers \textcolor{blue}{gradient descent}.
    \item $h = \chi_C$ recovers \textcolor{blue}{projected gradient descent}
          We call $\chi_C$ the \textbf{indicator function} of $C$
          \begin{align}
            \chi_C&: \R^d \to \R \cup +\infty \\
              & x \mapsto \begin{cases}
                0 & \text{if $x \in C$} \\
                +\infty & \text{otherwise.}
              \end{cases}
          \end{align}
          Proximal mapping becomes
          \begin{equation}
            \prox{\alpha h}{x} = \argmin_{y \in \R^d} \left\{ \chi_C(y) + \frac{1}{2 \alpha} \Vert y-x \Vert^2\right\} = \argmin_{y \in C} \{ \Vert y-x \Vert^2\}.
          \end{equation}
  \end{itemize}
\end{frame}

\begin{frame}
  \frametitle{Convergence}

  Same complexity as GD or projected GD,

  \textcolor{blue}{if we can compute the proximal mapping!}

\end{frame}

\end{document}


\documentclass[10pt,a4paper]{article}
\usepackage[utf8]{inputenc}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{makeidx}
\usepackage{graphicx}

\newtheorem{defi}{Defintion}

\author{moi}
\begin{document}
\section{Introduction}
We shall concentrate our discussion on fixed points and its implication with regard to algebra. We assume the reader confident with basic ring and module theory. In particular, unless stated otherwise we assume each ring $R$ to be commutative and unital (i.e. with one $1_R \in R$.
\subsection{Polynomial example}
Let $R$ be a ring. Firstly, let us discuss the specialisation of fixed points in the polynomial case.
\begin{defi}[Polynomial case]
Fix $f \in R[X]\backslash R$. An element $r_f \in R$ is a fixed point wrt. to $f$, if $f \in \ker \phi_{r_f}$ or equivalently if $r_f \in \ker \rho \circ \psi (f)$, where
$$\begin{array}{rrclcrcl}
ev_r : & R[X] & \longrightarrow & R,&& \sum_i f_i X^i & \longmapsto & \sum_i f_i r^i\\
\rho : &R& \longrightarrow &\mathrm{CRng}(R[X],R),&& r &\longmapsto& ev_r\\% = \left[\sum_i f_i X^i \longmapsto \sum_i f_i r^i\right],\\
\psi :& R[X] &\longrightarrow& R[X],&& f &\longmapsto &f - x,\ \mathrm{and}\\
\phi_r := ev_r \circ \psi :& R[X]& \longrightarrow& R&,& f &\longmapsto& ev_r (f - x).\\
\end{array}$$
\end{defi}
Firstly, we note that $\psi$ is an $R$ module automorphism and $ev_r$ is a ring homomorphism (hence, the notation of the class of ring homs $\mathrm{CRng}(R[X],R)$). The equivalence is obvious. However, the map $\phi_r$ is not a module

\end{document}


%! Author = tstreule

\section{Potentiometric Biosensors}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Redox Reaction}
%
\textbf{oxidation}: $e^-$ donor (\textit{anode}) \qquad
\textbf{reduction}: $e^-$ acceptor (\textit{cathode})

\formtex{Chemical reaction}{\ce{A*ox + B*X + z*e^- <=>[$k_{red}$][$k_{ox}$] C*red + D*Y}}
\vspace{-.5mm}
\formbox{reaction quotient}{
    Q = \mathrm{\frac{a\ped{ox}^A \;\cdot\; a\ped{X}^B}{a\ped{red}^C \;\cdot\; a\ped{Y}^D}}
}
%\textcolor{gray}{$= \Big(\prod\limits_j a_j^{v_j}\Big)$}
\begin{tabular}{@{$\bullet\;$}l @{\quad$\bullet\;$}l}
    $\mathrm{a}\ped{ion} = r\ped{ion} [\mathrm{ion}]/\unitfrac[1]{mol}{l}$ &
    $\mathrm{a}\ped{solids} = 1$\\
    $\mathrm{a}\ped{gas} = p\ped{gas}/\unit[1.013]{bar}$ &
    $[\ce{H2O}] = 1$
\end{tabular}

\formula{Standard conditions}{
    T = \SI{1}{\degreeCelsius}, \quad
    p = \SI{101.3}{\kilo\pascal} = \SI{1.013}{\bar}
}
\formula{\centering ``STP''}{
    [\mathrm{ion}] \equiv c\ped{ion} = \unitfrac[1]{mol}{l}, \quad
    r = 1 \text{ ``activity coeff.''}
}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Electrochemistry}
%
\formtex{Dynamic equi.}{no net charge over time ($k_1 = k_{-1}$)}
\formula{Chemical potential}{\mu_j = \big( \pderiv{G}{n_j} \big)_{p,T,n'}}
\formula{Equilibrium}{\mu_A = \mu_B}
\quad general: $\sum\limits\ped{prod}v_j\mu_j = \sum\limits\ped{react}v_j\mu_j$
\vspace{-.5mm}
\formula{Chemical potential}{\mu\ped{redox}\equiv E\ped{\emph{F},redox}\equiv E^*}
%\quad where \quad $D\ped{red}(\lambda,E^*) = D\ped{ox}(\lambda,E^*)$
\formbox{Equilibrium}{\bar\mu_A = \bar\mu_B}
\quad $\bar\mu_j = \mu_j^0 + z_jF\Delta\phi$

\formula{\textbf{Contact potential}}{\Delta\phi
    = V\ped{in}-V\ped{out} = \frac{k\ped{B}T}{Q} \ln\left(\frac{[C]\ped{out}}{[C]\ped{in}}\right)
}
\formula{~}{\phantom{\Delta\phi}
    = -\frac{\Delta_rG}{zF}
    = \frac{1}{zF} \Big( \sum\limits\ped{ox} v_j\mu_j - \sum\limits\ped{red} v_j\mu_j + z\mu_e \Big)
}
\formbox{Nernst eq., $\Delta\phi$}{E {=} E^0 {-} \frac{\unit[59]{mV}}{z} \log_{10}Q}
\textcolor{gray}{\footnotesize $\frac{RT}{zF}\ln Q = \frac{2.303 RT}{zF}\log_{10}Q$}
\formtex{~}{$E\ped{cell}=E_1-E_2$ \quad or \quad let $E_1 \overset{!}{=} E_2 \to \mathrm{pH}=\ldots$}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Ion-selective Electrodes \textnormal{(ISE)}}
%
Sensor is seperated to solution through a \ce{H+} permeable glass.
\formbox{pH electrode}{\mathrm{pH} = -\log_{10} a\ped{\ce{H+}} = \frac{K'-\Delta\phi}{\unit[0.059]{V}}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Bioenzymatic Electrodes}
%
\formtex{Find out how much}{\fbox{\ce{substrate + X + ... ->[enzyme] product + Y + ...}}}
\formtex{of an enzyme was}{Detect \textbf{``a lot''} \ce{X}}
\formtex{initially present}{\hfill$\leftrightarrow$ \textbf{``very few''} \ce{substrate} was initially present}


\section*{Notes Week 8}

\begin{itemize}

    \item A \definition{loop} is an edge that connects a node to itself. Mostly relevant to directed graphs \\
    \begin{tikzpicture}[node distance={15mm}, thick, main/.style = {draw, circle}]
        \node[main] (1) {$x_1$};
        \draw (1) to [out=180,in=270,looseness=5] (1);
    \end{tikzpicture}

    \item A \definition{simple path} is a path where all vertices are distinct except possibly the first and last. \\
    \begin{tikzpicture}[node distance={15mm}, thick, main/.style = {draw, circle}]
        \node[main] (1) {$x_1$};
        \node[main] (2) [right of = 1] {$x_2$};
        \node[main] (3) [right of = 2] {$x_3$};
        \node[main] (4) [right of = 3] {$x_4$};
        \draw (1) -- (2);
        \draw (3) -- (4);
        \draw (2) -- (3);
    \end{tikzpicture}

    \item A \definition{cycle} is a path that starts and ends on the same vertex.

    \item \definition{Acyclic} graphs contain no cycles.

    \item \definition{DAG}: Directed Acyclic Graph

    \item \definition{Strongly} connected graphs are ones where any vertex has a path to any other vertex; \definition{Weakly} connected graphs have vertices without paths to other vertices.

    \item A \definition{Bipartite Graph} is one we can separate vertices into two groups where edges only travel between groups. \\
    \begin{tikzpicture}[node distance={15mm}, thick, main/.style = {draw, circle}]
        \node[main] (1) {$x_1$};
        \node[main] (2) [right of = 1] {$x_2$};
        \node[main] (3) [right of = 2] {$x_3$};
        \node[main] (4) [right of = 3] {$x_4$};
        \node[main] (5) [below right of = 1] {$x_5$};
        \node[main] (6) [below right of = 2] {$x_6$};
        \node[main] (7) [below right of = 3] {$x_7$};
        \draw (1) -- (5);
        \draw (2) -- (5);
        \draw (2) -- (6);
        \draw (3) -- (6);
        \draw (3) -- (7);
        \draw (4) -- (7);
    \end{tikzpicture}

    \item Formally, a \definition{Bipartite Graph} is $BG = (A \cup B, E)$ such that every edge connects an element of A with an element B.

    \item A complete Bipartite graph is one where all nodes in group B are connected to all nodes in group B.

    \item A \definition{Tree} is any connected, undirected, acyclic graph.

\end{itemize}

\pagebreak

\section*{Depth-First $vs$ Breadth-First Searches}

\begin{tabularx}{\textwidth}{X X}

    \definition{Depth-First Search}

    \begin{enumerate}

        \item Push Start Vertex
        \item Mark start vertex as visited
        \item Loop until stack empty
        \begin{enumerate}
            \item Pop $U$
            \item Mark $U$ as visited
            \item For each of $U$ unvisited neighbors, push them
        \end{enumerate}

    \end{enumerate}

    &

    \definition{Breadth-First Search}

    \begin{enumerate}

        \item Enqueue Start Vertex
        \item Mark start vertex as visited
        \item Loop until queue empty
        \begin{enumerate}
            \item Dequeue $U$
            \item Mark $U$ as visited
            \item For each of $U$ unvisited neighbors, Enqueue them
        \end{enumerate}

    \end{enumerate}

\end{tabularx}

\begin{itemize}

    \item Both BFS and DFS are $O(V + E)$
    \begin{itemize}
        \item Vertices: $V = n$
        \item Edges: $E = n(n-1)/2$ at most in a complete, undirected graph
        \item Therefore: $O(n + n^2) = O(n^2)$ as an upper bound, but is dependet on
    \end{itemize}

    \item Under what circumstances would BFS or DFS run faster?

    \item Well, neither? Closer on graph favors BFS.

\end{itemize}

\section*{Topological Sort}

\begin{itemize}

    \item An ordering of vertices in a directed, acyclic graph such that, if there is a path, from vertex $A$ to vertex $B$, then vertex $B$ appears after vertex $A$ in the order. \\

\end{itemize}

\begin{tikzpicture}[node distance={15mm}, thick, main/.style = {draw, circle}]
        \node[main] (1) {$x_1$};
        \node[main] (2) [right of = 1] {$x_2$};
        \node[main] (3) [right of = 2] {$x_3$};
        \node[main] (4) [right of = 3] {$x_4$};
        \draw[->] (1) -- (2);
        \draw[->] (3) -- (4);
        \draw[->] (2) -- (3);
\end{tikzpicture}

\begin{itemize}

    \item Topological sorts are not guaranteed to be unique. There could be many correct orders.

    \item Examples: Family Tree, Course Prerequisites

    \item Assumptions:
    \begin{enumerate}
        \item Indegree for each vertex is stored
        \item Edges stored in an adjacency list
    \end{enumerate}

\end{itemize}

\pagebreak

\begin{algorithm}
    \caption{Topological Sort 1 $O(n^2)$}
    \begin{algorithmic}
        \While{Graph is not empty}
            \State Find any vertex with no incoming edges
            \State Display Vertex
            \State Remove it, and its edges, from the graph
        \EndWhile
    \end{algorithmic}
\end{algorithm}

\begin{algorithm}
    \caption{Topological Sort 2}
    \begin{algorithmic}
        \State Maintain a queue of vertices with indegree $0$
        \While Queue is not empty
            \State Dequeue a vertex
            \State Display the Vertex
            \State Remove it and its edges from the graph
            \State Update remaining Vertices, enqueueing any whose indgree is $0$
        \EndWhile
    \end{algorithmic}
\end{algorithm}

\begin{itemize}
    \item Each vertex enqueued and dequeued once $\rightarrow O(n^2)$
    \item Each edge gets removed once $\rightarrow n^2$ potential
    \item Therefore, Topological Sort 2 is $O(V+E)$
    \item TS2 depends on number of edges, whereas TS1 depends on nodes
    \item TS2 approaches TS1 only when the graph is complete, or close to it
\end{itemize}

\section*{The Selection Problem}

Find the $k^{th}$ largest number in a set of $n$ numbers.

\begin{itemize}

    \item \definition{$i^{th}$ order statistic}: the $i^{th}$ smallest term in a set of $n$ elements
    \item Recall week 1 notes; best algorithm was $O(nlog(n))$
    \item It's possible to make this $O(n)$
    \begin{itemize}
        \item Pick a good pivot similar to QuickSort
        \item Then like Binary Search, use the half that's relevant
        \item The dividing runs in $(log(n))$ but the pivot search runs in $O(n)$
    \end{itemize}

\end{itemize}

\end{document}


\documentclass{article}

\usepackage[T1]{fontenc}
\usepackage[osf]{libertine}
\usepackage[scaled=0.8]{beramono}
\usepackage[margin=1.5in]{geometry}
\usepackage{url}
\usepackage{booktabs}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{nicefrac}
\usepackage{microtype}
\usepackage{bm}

\usepackage{sectsty}
\sectionfont{\large}
\subsectionfont{\normalsize}

\usepackage{titlesec}
\titlespacing{\section}{0pt}{10pt plus 2pt minus 2pt}{0pt plus 2pt minus 0pt}
\titlespacing{\subsection}{0pt}{5pt plus 2pt minus 2pt}{0pt plus 2pt minus 0pt}

\usepackage{pgfplots}
\pgfplotsset{
  compat=newest,
  plot coordinates/math parser=false,
  tick label style={font=\footnotesize, /pgf/number format/fixed},
  label style={font=\small},
  legend style={font=\small},
  every axis/.append style={
    tick align=outside,
    clip mode=individual,
    scaled ticks=false,
    thick,
    tick style={semithick, black}
  }
}

\pgfkeys{/pgf/number format/.cd, set thousands separator={\,}}

\usepgfplotslibrary{external}
\tikzexternalize[prefix=tikz/]

\newlength\figurewidth
\newlength\figureheight

\setlength{\figurewidth}{8cm}
\setlength{\figureheight}{6cm}

\newlength\squarefigurewidth
\newlength\squarefigureheight

\setlength{\squarefigurewidth}{7cm}
\setlength{\squarefigureheight}{6cm}

\setlength{\parindent}{0pt}
\setlength{\parskip}{1ex}

\newcommand{\acro}[1]{\textsc{\MakeLowercase{#1}}}
\newcommand{\given}{\mid}
\newcommand{\mc}[1]{\mathcal{#1}}
\newcommand{\data}{\mc{D}}
\newcommand{\trans}{^\top}
\newcommand{\inv}{^{-1}}
\newcommand{\intd}[1]{\,\mathrm{d}{#1}}
\newcommand{\mat}[1]{\bm{\mathrm{#1}}}
\renewcommand{\vec}[1]{\bm{\mathrm{#1}}}

\DeclareMathOperator{\var}{var}

\begin{document}

{\large \textbf{CSE 515T (Spring 2015) Midterm solutions}}
\begin{enumerate}
\item
  Consider two coins with unknown bias $\theta_1$ and $\theta_2$,
  respectively.  We place independent, identical beta priors on these
  quantities:
  \begin{equation*}
    p(\theta_1) = \mc{B}(\theta_1; 2, 2);
    \qquad
    p(\theta_2) = \mc{B}(\theta_2; 2, 2).
  \end{equation*}
  Imagine someone flips both coins and tells you that \emph{exactly
    one} of the outcomes (but not which) was a ``head.''  Thus the
  observation was either HT or TH, but you are not told which.  The
  below expressions are conditioned on ``H'' to indicate this
  observation.
  \begin{itemize}
  \item
    Give an expression for the posterior of the first coin's bias
    given this observation, $p(\theta_1 \given \text{H})$.  Simplify
    the result as much as you can.  Plot the prior and the posterior
    for $\theta_1$ over the interval $\theta_1 \in (0, 1)$.
  \item
    Give an expression for the joint posterior $p(\theta_1, \theta_2
    \given \text{H})$. Plot the joint prior, the likelihood, and the
    joint posterior as three separate heat maps over the unit square
    $(\theta_1, \theta_2) \in (0, 1)^2$.  Use a grid with at least 100
    values along each of the two $\theta$ axes.
  \item
    Summarize what the observation taught us about the bias of the
    coins.
  \end{itemize}
\end{enumerate}

\subsection*{Solution}

The outcome of the unseen experiment was either HT or TH.  These are
mutually exhaustive and independent events, so we may use the sum
rule to derive the desired posterior:
\begin{equation*}
  p(\theta_1 \given \text{H})
  =
  \Pr(\text{HT})p(\theta_1 \given \text{HT})
  +
  \Pr(\text{TH})p(\theta_1 \given \text{TH})
  .
\end{equation*}
Notice that both $p(\theta_1 \given \text{HT})$ and $p(\theta_1 \given
\text{TH})$ can be computed explicitly as updated beta distributions,
now that the coins in the outcomes have been identified:
\begin{align*}
  p(\theta_1 \given \text{HT})
  &=
  \mc{B}(\theta_1; 3, 2)
  \\
  p(\theta_1 \given \text{TH})
  &=
  \mc{B}(\theta_1; 2, 3).
\end{align*}

What is $\Pr(\text{HT})$?  It can be calculated explicitly, but a
simpler approach is to appeal to symmetry between the coins to
conclude $\Pr(\text{HT}) = \Pr(\text{TH}) = \nicefrac{1}{2}$.  Thus
\begin{equation*}
  p(\theta_1 \given \text{H})
  =
  \tfrac{1}{2}
  \bigl(
  p(\theta_1 \given \text{HT}) +
  p(\theta_1 \given \text{TH})
  \bigr)
  =
  \tfrac{1}{2}
  \bigl(
  \mc{B}(\theta_1; 3, 2) +
  \mc{B}(\theta_1; 2, 3)
  \bigr)
  .
\end{equation*}
We can simply this expression further.  The posterior is proportional
to
\begin{equation*}
  p(\theta_1 \given \text{H})
  \propto
  \theta_1^2 (1 - \theta_1)
  +
  \theta_1 (1 - \theta_1)^2
  =
  \theta_1(1 - \theta_1)
  \propto
  \mc{B}(\theta_1; 2, 2).
\end{equation*}
Therefore the distribution of $\theta_1$ has not changed given our
observation!  The prior (and posterior!) for $\theta_1$ is plotted
in Figure \ref{problem_1_prior_1}.

\begin{figure}
  \centering
  \input{figures/problem_1_prior_1}
  \caption{The prior and posterior (given the observation H) of
    $\theta_1$.}
  \label{problem_1_prior_1}
\end{figure}

There are two ways to compute the joint posterior over $(\theta_1,
\theta_2)$: the easy way and the hard way.  The easy way is to use the
sum rule again to write
\begin{align*}
  p(\theta_1, \theta_2 \given \text{H})
  &=
  \Pr(\text{HT})
  p(\theta_1, \theta_2 \given \text{HT})
  +
  \Pr(\text{TH})
  p(\theta_1, \theta_2 \given \text{TH})
  \\
  &=
  \tfrac{1}{2}
  \mc{B}(\theta_1; 3, 2)
  \mc{B}(\theta_2; 2, 3)
  +
  \tfrac{1}{2}
  \mc{B}(\theta_1; 2, 3)
  \mc{B}(\theta_2; 3, 2).
\end{align*}

If we go with the hard way, we begin by computing the joint prior.  By
independence, we have:
\begin{equation*}
  p(\theta_1, \theta_2)
  =
  \mc{B}(\theta_1; 2, 2)
  \mc{B}(\theta_2; 2, 2).
\end{equation*}
To derive the likelihood, we again note that our observation could
have been generated by two mutually independent events: HT or TH.
Given $\theta_1$ and $\theta_2$, the total probability of these
events is:
\begin{equation*}
  \Pr(\text{H} \given \theta_1, \theta_2)
  =
  \theta_1(1 - \theta_2)
  +
  (1 - \theta_1)\theta_2;
\end{equation*}
the first term accounts for HT and the second term for TH.  The
posterior is now:
\begin{align*}
  p(\theta_1, \theta_2 \given \text{H})
  &=
  \tfrac{1}{Z}
  \Pr(\text{H} \given \theta_1, \theta_2)
  p(\theta_1, \theta_2)
  \\
  &=
  \tfrac{1}{Z}
  \bigl(
  \theta_1(1 - \theta_2)
  +
  (1 - \theta_1)\theta_2
  \bigr)
  \mc{B}(\theta_1; 2, 2)
  \mc{B}(\theta_2; 2, 2).
\end{align*}
The normalization constant is
\begin{equation*}
  Z
  =
  \Pr(\text{H})
  =
  \int_0^1
  \int_0^1
  \bigl(
  \theta_1(1 - \theta_2)
  +
  (1 - \theta_1)\theta_2
  \bigr)
  \mc{B}(\theta_1; 2, 2)
  \mc{B}(\theta_2; 2, 2)
  \intd{\theta_1}
  \intd{\theta_2}.
\end{equation*}
This integral is tractable and equals
\nicefrac{1}{2}.\footnote{\url{http://goo.gl/wRofuX}} In fact, this is
always true for any arbitrary mean-\nicefrac{1}{2} beta priors on
$\theta_1, \theta_2$: if our best guess is that each coin is unbiased,
then the outcomes HT/TH always have equal combined probability as the
outcomes HH/TT.

The posterior is now
\begin{equation*}
  p(\theta_1, \theta_2 \given \text{H})
  =
  2
  \bigl(
  \theta_1(1 - \theta_2)
  +
  (1 - \theta_1)\theta_2
  \bigr)
  \mc{B}(\theta_1; 2, 2)
  \mc{B}(\theta_2; 2, 2).
\end{equation*}
This is equivalent to the expression we derived with ``the easy way.''

The prior, likelihood, and posterior are plotted below.  From the
posterior, we can see that joint probabilities corresponding to
jointly low or high values: these combinations would correspond to a
higher probability of seeing either HH or TT observations.  Despite
the marginals for $\theta_1$ and $\theta_2$ remaining unchanged, the H
observation has entangled the previously independent beliefs in the
anticorrelated posterior.

\begin{figure}
  \centering
  \input{figures/problem_1_joint_prior.tex}
  \caption{The joint prior $p(\theta_1, \theta_2)$.}
  \label{problem_joint_prior}
\end{figure}

\begin{figure}
  \centering
  \input{figures/problem_1_joint_likelihood.tex}
  \caption{The joint likelihood $p(\text{H} \given \theta_1, \theta_2)$.}
  \label{problem_joint_likelihood}
\end{figure}

\begin{figure}
  \centering
  \input{figures/problem_1_joint_posterior.tex}
  \caption{The joint posterior $p(\theta_1, \theta_2 \given \text{H})$.}
  \label{problem_joint_posterior}
\end{figure}

\clearpage
\begin{enumerate}
\setcounter{enumi}{1}
\item
  Consider the three-dimensional parameter vector $\vec{\theta} =
  [\theta_1, \theta_2, \theta_3]\trans$, with the following joint
  multivariate Gaussian prior:
  \begin{equation*}
    p(\vec{\theta})
    =
    \mc{N}(\vec{\theta}; \vec{\mu}, \mat{\Sigma})
    =
    \mc{N}
    \left(
    \begin{bmatrix}
      \theta_1 \\
      \theta_2 \\
      \theta_3
    \end{bmatrix}
    ;
    \begin{bmatrix}
      0 \\
      1 \\
      2
    \end{bmatrix},
    \begin{bmatrix}
      1 & 2 & 0   \\
      2 & 9 & 0 \\
      0 & 0 & 16
    \end{bmatrix}
    \right).
  \end{equation*}
  We are going to consider a decision problem with action space
  $\mc{A} = \{1, 2, 3\}$.  The result of choosing an action $a \in
  \mc{A}$ will be to observe the exact value of $\theta_a$, the $a$th
  element of $\vec{\theta}$.

  Consider the following loss functions, $\ell_1$ and $\ell_2$:
  \begin{equation*}
    \ell_1(\vec{\theta}, a) =
    \begin{cases}
      1 & \theta_a   >  0 \\
      0 & \theta_a \leq 0
    \end{cases}
    \qquad
    \ell_2(\vec{\theta}, a) = \min(0, \theta_a).
  \end{equation*}
  For each:
  \begin{itemize}
  \item
    Write a generic expression for the expected loss of action $a$ in
    terms of $\vec{\mu}$ and $\mat{\Sigma}$.  Evaluate any integrals
    you encounter.
  \item
    Give a numerical value for the expected loss of each action, using
    the values of $(\vec{\mu}, \mat{\Sigma})$ provided above.
  \item
    State the Bayes action.
  \end{itemize}
\end{enumerate}

\subsection*{Solution}

First, we note that the loss functions only depend on $\vec{\theta}$
through $\theta_a$, so we must only consider the marginal belief about
$\theta_a$ when contemplating action $a$.  By applying the marginalization
formula for multivariate Gaussians, this belief is:
\begin{equation*}
  p(\theta_a) = \mc{N}(\theta_a; \mu_a, \Sigma_{aa}).
\end{equation*}
For loss $\ell_1$, we may calculate the expected loss of each action:
\begin{equation*}
  \mathbb{E}
  \bigl[
    \ell_1(\vec{\theta}, a)
  \bigr]
  =
  \int_{-\infty}^\infty
  \ell_1(\vec{\theta}, a)
  p(\theta_a)
  \intd{\theta_a}
  =
  \int_0^\infty
  \mc{N}(\theta_a; \mu_a, \Sigma_{aa})
  \intd{\theta_a}
  =
  1 - \Phi(0; \mu_a, \Sigma_{aa}).
\end{equation*}
Using this result, we may numerically calculate the expected loss for
each action:
\begin{equation*}
  \mathbb{E}\bigl[\ell_1(\vec{\theta}, 1)\bigr]
  =
  0.5 \qquad
  \mathbb{E}\bigl[\ell_1(\vec{\theta}, 2)\bigr]
  =
  0.631 \qquad
  \mathbb{E}\bigl[\ell_1(\vec{\theta}, 3)\bigr]
  =
  0.691.
\end{equation*}
The Bayes action is $a = 1$, with the lowest expected loss.

For loss $\ell_2$, we proceed in the same way:
\begin{equation*}
  \mathbb{E}
  \bigl[
    \ell_2(\vec{\theta}, a)
  \bigr]
  =
  \int_{-\infty}^\infty
  \ell_2(\vec{\theta}, a)
  p(\theta_a)
  \intd{\theta_a}
  =
  \int_{-\infty}^0
  \theta_a
  \mc{N}(\theta_a; \mu_a, \Sigma_{aa})
  \intd{\theta_a}.
\end{equation*}
We may compute this definite integral; I used a table of Gaussian
integrals\footnote{\url{http://en.wikipedia.org/wiki/List_of_integrals_of_Gaussian_functions}}
and the identity
\begin{equation*}
  \phi\biggl(
  \frac{a - \mu}{\sigma}
  \biggr)
  =
  \sigma \mc{N}(a; \mu, \sigma^2)
\end{equation*}
to derive
\begin{equation*}
  \mathbb{E}
  \bigl[
    \ell_2(\vec{\theta}, a)
  \bigr]
  =
  \mu_a \Phi(0; \mu_a, \Sigma_{aa})
  -
  \Sigma_{aa}
  \mc{N}(0; \mu_a, \Sigma_{aa}).
\end{equation*}
Using this result, we may numerically calculate the expected loss for
each action:
\begin{equation*}
  \mathbb{E}\bigl[\ell_2(\vec{\theta}, 1)\bigr]
  =
  -0.399 \qquad
  \mathbb{E}\bigl[\ell_2(\vec{\theta}, 2)\bigr]
  =
  -0.763 \qquad
  \mathbb{E}\bigl[\ell_2(\vec{\theta}, 3)\bigr]
  =
  -0.791.
\end{equation*}
The Bayes action is now $a = 3$, with the lowest expected loss.

\clearpage
\begin{enumerate}
\setcounter{enumi}{2}
\item
  Consider a $d$-dimensional vector $\vec{\theta}$ with an arbitrary
  multivariate Gaussian distribution:
  \begin{equation*}
    p(\vec{\theta})
    =
    \mc{N}(\vec{\theta}; \vec{\mu}, \mat{\Sigma}).
  \end{equation*}
  \begin{itemize}
  \item
    Give a general expression for the distribution of the following
    (scalar) value $\tau$.
    \begin{equation*}
      \tau = \theta_1 + 2\theta_2 + \dotsb d\theta_d
    \end{equation*}
  \item
    Consider again the specific distribution of the three-dimensional
    vector $\vec{\theta}$ from the last problem, as well as the action
    space $\mc{A}$ with the same observation mechanism: after choosing
    $a \in \mc{A}$, we will observe the corresponding value
    $\theta_a$.  Suppose we may select one action and then must
    predict $\tau$ under a squared loss function:
    \begin{equation*}
      \ell(\tau, \hat{\tau}) = (\tau - \hat{\tau})^2.
    \end{equation*}
    Using the distribution from the last problem. what is the expected
    loss of each of the three available actions?  Which is the Bayes
    action?
  \end{itemize}
\end{enumerate}

\subsection*{Solution}

Define the (row) vector $\vec{d}\trans = [1, 2, \dotsc, d]$.  We first
notice that $\tau$ is simply a linear transformation of
$\vec{\theta}$:
\begin{equation*}
  \tau = \vec{d}\trans \vec{\theta};
\end{equation*}
therefore $\tau$ has a multivariate Gaussian distribution:
\begin{equation*}
  p(\tau)
  =
  p(\vec{d}\trans \vec{\theta})
  =
  \mc{N}(\tau; \vec{d}\trans \vec{\mu}, \vec{d}\trans \mat{\Sigma} \vec{d}).
\end{equation*}

In the second part of the question, we must consider estimating $\tau$
under a squared loss function $\ell(\tau, \hat{\tau}) = (\tau -
\hat{\tau})^2$.  A general result from Bayesian decision theory is
that the Bayes action is to estimate $\hat{\tau}$ as the (posterior)
mean of $\tau$.  For example, given the initial belief from the last
problem, we would predict $\hat{\tau} = \vec{d}\trans \vec{\mu} = 8$.
What is the \emph{expected} loss when predicting the mean $\hat{\tau}
= \mathbb{E}[\tau]$?
\begin{equation*}
  \mathbb{E}
  \Bigl[
    \ell\bigl(\tau, \mathbb{E}[\tau]\bigr)
  \Bigr]
  =
  \mathbb{E}
  \Bigl[
    \bigl(\tau - \mathbb{E}[\tau]\bigr)^2
  \Bigr]
  =
  \var [ \tau ]
  =
  \vec{d}\trans \mat{\Sigma} \vec{d}.
\end{equation*}
The expected squared loss is simply the variance of $\tau$!  Conveniently,
we have a closed-form expression for this variance.

The problem asks us to consider how we would proceed with estimating
$\tau$ if we could observe one of the entries of the vector
$\vec{\theta}$ before making our prediction $\hat{\tau}$.  If we wish
to minimize our expected loss, we should minimize the variance of
$\tau$ with our observation.  Observing an entry of $\vec{\theta}$ is
a conditioning observation of a multivariate Gaussian.  We have a
closed-form expression for the posterior covariance of $\vec{\theta}$
after observing any entry $\theta_a$.  Remarkably, the posterior
covariance of $\vec{\theta}$ does not depend on the actual value we
observe, only the index of the entry we choose, $a$.  The posterior
covariance matrices $\mat{\Sigma}_{\vec{\theta} \given \theta_a}$ for
each available action $a \in \mc{A}$ are:
\begin{align*}
  \mat{\Sigma}_{\vec{\theta} \given \theta_1}
  &=
  \begin{bmatrix}
    0 & 0 & 0   \\
    0 & 5 & 0   \\
    0 & 0 & 16
  \end{bmatrix}
  \\
  \mat{\Sigma}_{\vec{\theta} \given \theta_2}
  &=
  \begin{bmatrix}
    \frac{5}{9} & 0 & 0   \\
    0           & 0 & 0   \\
    0           & 0 & 16
  \end{bmatrix}
  \\
  \mat{\Sigma}_{\vec{\theta} \given \theta_3}
  &=
  \begin{bmatrix}
    1 & 2 & 0 \\
    2 & 9 & 0 \\
    0 & 0 & 0
  \end{bmatrix}.
\end{align*}
The expected losses of our final prediction of $\hat{\tau}$
given $\theta_a$ is now given by
\begin{equation*}
  \mathbb{E}\bigl[\ell(\tau, \hat{\tau}) \given \theta_a \bigr]
  =
  \vec{d}\trans \mat{\Sigma}_{\vec{\theta} \given \theta_a} \vec{d}.
\end{equation*}
For our particular problem, the expected final loss after each potential
action is:
\begin{equation*}
  \mathbb{E}\bigl[\ell(\tau, \hat{\tau}) \given \theta_1\bigr]
  =
  164 \qquad
  \mathbb{E}\bigl[\ell(\tau, \hat{\tau}) \given \theta_2\bigr]
  =
  144\,\nicefrac{5}{9} \qquad
  \mathbb{E}\bigl[\ell(\tau, \hat{\tau}) \given \theta_3\bigr]
  =
  45.
\end{equation*}
The Bayes action is $a = 3$.  Despite the fact that $\theta_3$ is
uncorrelated with the other two entries, collapsing its large variance
from $16$ to zero has the effect of reducing the variance of $\tau$
(and therefore our expected loss) by $3^2 \cdot 16 = 144$.

\clearpage
\begin{enumerate}
\setcounter{enumi}{3}
\item
  Consider the following data:
  \begin{align*}
    \vec{x} &= [0.54, 1.84, -2.26, 0.86, 0.32]\trans; \\
    \vec{y} &= [-1.31, -0.43, 0.34, 3.58, 2.77]\trans.
  \end{align*}
  Consider the Bayesian linear regression model with $\phi(x) = [1,
    x]\trans$.  Use the prior $p(\vec{w}) = \mc{N}(\vec{w}; \vec{0},
  \mat{I})$.

  Plot the posterior probability that the slope of the regression line
  is positive as a function of the standard deviation of the
  observation noise $\sigma$ (the noise variance is then $\sigma^2$).
  Use a grid of at least 100 points in the range $\sigma \in (0.01,
  10)$.
\end{enumerate}

\subsection*{Solution}

Using the given linear regression model, we assume
\begin{equation*}
  y
  =
  \phi(x)\trans \vec{w} + \varepsilon
  =
  w_1 + w_2 x + \varepsilon.
\end{equation*}
The second entry of the weight vector $\vec{w}$, $w_2$, therefore
serves as the slope of the regression line.

The Bayesian linear regression model gives the following posterior for
$\vec{w}$ given observations $\data$ and a specified noise variance
$\sigma^2$:
\begin{equation*}
  p(\vec{w} \given \data, \sigma^2)
  =
  \mc{N}(\vec{w};
  \vec{\mu}_{\vec{w}\given\data},
  \mat{\Sigma}_{\vec{w}\given\data}
  ),
\end{equation*}
where
\begin{align*}
  \vec{\mu}_{\vec{w}\given\data}
  &=
  \mat{X}\trans
  (\mat{X}\mat{X}\trans + \sigma^2 \mat{I})\inv
  \vec{y};
  \\
  \mat{\Sigma}_{\vec{w}\given\data}
  &=
  \mat{I}
  -
  \mat{X}\trans
  (\mat{X}\mat{X}\trans + \sigma^2 \mat{I})\inv
  \mat{X},
\end{align*}
where we have plugged the given prior $p(\vec{w}) = \mc{N}(\vec{w};
\vec{0}, \mat{I})$ into the general result.

Given a value of $\sigma$, the formulas above give the posterior over
$\vec{w}$.  To determine the probability that $w_2$ is positive, we
simply take the marginal posterior distribution and evaluate the
normal \acro{CDF}:
\begin{equation*}
  \Pr(w_2 > 0 \given \data, \sigma^2)
  =
  1 -
  \Phi\bigl(
  0;
  (\vec{\mu}_{\vec{w}\given\data})_2
  ,
  (\mat{\Sigma}_{\vec{w}\given\data})_{22}
  \bigr).
\end{equation*}

This quantity is plotted as a function of $\sigma$ in Figure
\ref{problem_4}.  The larger the noise, the less confident we become
about the sign of the slope.

\begin{figure}
  \centering
  \input{figures/problem_4.tex}
  \caption{The posterior probability that the slope of the regression
    line is positive as a function of the noise standard deviation
    $\sigma$.  Note the limits on the $y$-axis.}
  \label{problem_4}
\end{figure}

\end{document}


\chapter{Overview}

The \sfincs~code is a freely available, open-source tool for solving neoclassical-type kinetic problems in nonaxisymmetric or axisymmetric plasmas
with nested toroidal flux surfaces.
As with other neoclassical codes, the input information used by \sfincs~is the equilibrium magnetic geometry together with the density, radial density gradient, temperature,
and radial temperature gradient of each species.  The code then solves a drift-kinetic equation for each species,
yielding the (gyro-angle averaged) distribution function.  Moments of the distribution function are computed such as the parallel
flow, bootstrap current, radial particle flux, radial heat flux, and variation of the density over a flux surface.
These moments are all saved in the output file, and if you wish, you can also save the distribution function itself.
Optionally, a quasi-neutrality
equation can be solved at the same time as the drift-kinetic equations, yielding the self-consistent variation of the electrostatic potential on a flux surface.

The kinetic equations solved in \sfincs~have four independent variables: poloidal angle $\theta$, toroidal angle $\zeta$,
normalized speed $x = v / v_{thermal}$, and pitch angle $\xi = v_{||}/v$.  The third velocity coordinate (gyro-angle) does not appear
since gyro-averaged equations are solved.  The flux surface label (radius) coordinate is only a parameter, rather than a full independent variable,
since a radially local approximation is made.
The solution is the first-order distribution function $f_{s1} \left(\theta, \zeta, x, \xi\right)$ (where the full distribution is $f_s = f_{s0} + f_{s1}$) on the flux surface for all species $s$, and if quasi-neutrality is solved also the electrostatic potential variation on the flux surface $\Phi_1 \left(\theta, \zeta\right) = \Phi-\left<\Phi\right>$.

This document discusses the practical use and operation of the code.  For more details about the specific equations implemented,
see the version 3 technical documentation available in the \path{sfincs/docs} directory.
Ref \cite{sfincsPaper} gives many details and some early physics results.

Often, the limiting factor for \sfincs~is the ability of the libraries \mumps~or \superludist~to factorize the preconditioner matrix, discussed in section \ref{sec:gmres}.
You may therefore find it useful to see the control parameters and error codes in the \mumps~user manual:
\url{http://mumps.enseeiht.fr/doc/userguide_5.0.0.pdf}.

This manual describes ``version 3'' of \sfincs.
To preserve previous versions of the code that have been used for publications, two older versions of the
code called singleSpecies and multiSpecies are also present in the repository.
For all versions, both MATLAB and fortran editions exist which are independent of each other.
The MATLAB editions exist primarily for debugging the fortran editions.
The same algorithms are implemented in the two different languages, and for identical input parameters,
the matrices and output quantities from the different editions should agree to several significant digits (roughly within the solver tolerance.)
Any significant differences between the matrices and output of the MATLAB and fortran editions can be used to identify a bug.
The MATLAB versions are serial whereas the fortran versions
are parallelized, so the fortran versions are significantly faster and can access much more memory.
For realistic experimental geometry and collisionality, the resolution (and hence memory) requirements will mean
you will need to use the fortran edition.

\section{Features}

\begin{itemize}

\item
Both self-species and inter-species collisions are treated using the most accurate linear operator available, the full linearized Fokker-Planck collision operator,
with no approximation of the field-particle term or expansion in mass ratio.  This collision operator conserves mass, momentum, and energy.

\item
Realistic experimental geometry can be simulated using an interface to \vmec.  Analytic model equilibria can also be used.

\item
Full coupling in the speed (or equivalently, kinetic energy) coordinate is retained, i.e. no monoenergetic approximation is made.  However,
if desired, \sfincs~can also be run in monoenergetic mode to compare with older codes.

\item
The code is formulated to permit solution of a wide variety of kinetic equations, whether or not phase space volume and/or energy are conserved, so individual terms can be turned on or off to examine their effect.

\item
A variety of models for terms involving the radial electric field are available to allow comparison between models.

\item
You can choose to include or not include the poloidal and toroidal magnetic drifts in the kinetic equation.

\item
The code takes advantage of modern algorithms (GMRES) and parallelized libraries (\PETSc, \superludist, and \mumps).

\item
Efficient representation of velocity space is achieved using a pseudospectral method based upon non-classical orthogonal polynomials. \cite{speedGrids}

\item
The electrostatic potential can either be taken to be constant or non-constant on a flux surface.

\item
Optional nonlinear terms in the kinetic equation (involving both the non-Maxwellian distribution function and poloidal/toroidal electric field) can be included using Newton's method.

\item
The radial classical particle and heat fluxes are calculated.

\end{itemize}

\section{Limitations}

\begin{itemize}

\item
The \sfincs~code is radially local, in the sense that it approximates
the radial derivative of the distribution function $\partial f/\partial \psi$ by
the derivative of a Maxwellian flux function $\partial f_M(\psi,x)/\partial \psi$.
This approximation is important for reducing the otherwise 5D space of independent variables $(\psi,\theta,\zeta,x,\xi)$
to a 4D space $(\theta,\zeta,x,\xi)$.
As a result, \sfincs~cannot compute certain finite-orbit-width effects that occur when the radial extent of the particle orbits
between bounces or transits is not small compared to the scale of radial variation in the equilibrium.
Such finite orbit width effects are significant near the magnetic axis, and in strong transport barriers, such as the pedestal of a tokamak H-mode.

\item
Turbulence is neglected.  There are good theoretical reasons to expect that the neoclassical effects computed by \sfincs~should
decouple from turbulence, as detailed in \cite{AbelReview}.  However, this argument relies on an expansion in $\rho_* \ll 1$, and so may break down
in some circumstances when $\rho_*$ is not sufficiently small.

\item
It is assumed that nested toroidal magnetic surfaces exist. Thus, the code cannot accurately model regions of stochastic field,
magnetic islands, or open field lines.

\end{itemize}

\section{Geometry options}
In \sfincs, a variety of options are available for the magnetic field geometry.  The geometry can be read directly
from a {\ttfamily vmec wout}
file, or from the {\ttfamily .bc} format Boozer-coordinate data files used at the Max Planck Institute for Plasma Physics (IPP).
A general analytic model for the magnetic field is also available, given by equation (\ref{eq:Bmodel}),
as are several analytic models for LHD and W7-X in which 3 or 4 Fourier components are retained.
The primary switch for controlling the magnetic geometry in \sfincs~is the \parlink{geometryScheme} parameter
in the {\ttfamily \hyperref[sec:geometryParameters]{geometryParameters}} input namelist.
For more details about geometry options in \sfincs, see section \ref{sec:geometryParameters}.

\section{GMRES/KSP and preconditioning}
\label{sec:gmres}

At its heart, \sfincs~solves one or more large sparse linear systems $Ax=b$.  Here $b$ is a known right-hand side vector,
$A$ is a large (often millions $\times$ millions) known sparse matrix, and $x$ is the desired and unknown solution vector.
The direct way to solve such systems is to $LU$-factorize
the matrix $A$ into lower- and upper-triangular factors.
Once the $L$ and $U$ factors are found, the solution of the linear system
for any right-hand side vector can be rapidly obtained.  However, even if the original matrix is sparse, the $L$ and $U$ factors
are generally not sparse, and so a very large amount of memory can be required for a direct $LU$-factorization.

An alternative way to solve
such large linear systems is with a so-called ``Krylov-space'' iterative method, which can dramatically reduce the memory required
compared to a direct solution.  For the non-symmetric matrices that arise in \sfincs, the preferred Krylov-space
algorithm is called GMRES (Generalized Minimal RESidual.)  In \sfincs, the \PETSc~library is used to solve the large systems
of equations. \PETSc~calls its family of linear solvers KSP, so in the output of \sfincs~you will see a ``KSP residual'' reported
as GMRES iterates towards the solution.

An important element of Krylov methods is preconditioning.  The art of preconditioning is to find a linear operator which has similar eigenvalues
to the ``true'' matrix you would like to invert (or more precisely, to $LU$-factorize), but which can be inverted faster.
If a good preconditioner can be found, the number of GMRES iterations is greatly reduced.  Many schemes for preconditioning exist,
but the version adopted in \sfincs~is to explicity form and $LU$-factorize a preconditioning matrix which is similar
to the true matrix (but somewhat simpler).  There is a basic trade-off:
the more similar the preconditioner matrix is to the true matrix, the fewer iterations will be required, but the more time will
be required to $LU$-factorize the preconditioning operator.  The usual preconditioner matrix in \sfincs~is obtained by dropping all coupling
between grid points in the speed coordinate and dropping coupling between species.  The preconditioner matrix need not be a physically
accurate or meaningful operator; as long as GMRES converges, the solution obtained will be independent of the preconditioner to whatever tolerance is specified.

\section{\sfincs~vs. \sfincsScan}
The core fortran part of \sfincs~solves the kinetic equation for each species
at a single flux surface, a single value of $E_r$, and a single set of other parameters.
However, often the goal is to determine the ambipolar $E_r$ at one or more surfaces, or to scan some other parameter.
For this task, the \sfincsScan~family of \python~scripts is available.
Using these scripts, it is also possible to scan other variables in the input file,
and in particular, to scan the resolution parameters to ensure
the physical output quantities are numerically converged.
For a full list of the types of scans available, see section \ref{sec:sfincsScanParams}

\section{Input and Output}

The input parameters for a \sfincs~computation are specified in a file named {\ttfamily input.namelist}.
This file contains both information for the fortran part of \sfincs~(in standard fortran namelist format),
as well as special lines beginning with {\ttfamily !ss} which are read by \sfincsScan.
The variables which can be specified in {\ttfamily input.namelist} are detailed in chapter \ref{ch:input}.
For scans over minor radius, an additional file named {\ttfamily profiles} is used to specify the profiles of density and temperature
for each species, as well as the range of radial electric field to consider.

The output from a single \sfincs~computation is saved in \HDF~format in the file %{\ttfamily sfincsOutput.h5}.
specified by \parlink{outputFileName}.
To browse this file you can enter {\ttfamily h5dump outputFileName|less} %{\ttfamily h5dump sfincsOutput.h5|less}
from the command line.
Every array saved in this file is annotated with strings that describe the array dimensions,
for example \Ntheta$\times$ \Nzeta. One of the array dimensions may be {\ttfamily iteration},
which can either indicate the iteration of the Newton solver for a nonlinear calculation,
or which right-hand side vector was used when computing a transport matrix.
Many of the variables in the output file are also annotated with
text that describes their meaning and normalization.
Some of the most frequently used output quantities are detailed in chapter~\ref{ch:output}.

\section{Questions, Bugs, and Feedback}

We enthusiastically welcome any contributions to the code or documentation.
For write permission to the repository, or to report any bugs, provide feedback, or ask questions, contact Matt Landreman at
\href{mailto:matt.landreman@gmail.com}{\nolinkurl{matt.landreman@gmail.com} }