\documentclass[12pt]{article}
\usepackage[utf8]{inputenc}
\usepackage[english]{babel}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{bbm}
\usepackage{tikz}
\usepackage{mathtools}
\usepackage{subfigure}
\usepackage[hang]{footmisc}

\setlength{\footnotemargin}{2.5mm}
\usetikzlibrary{shapes,automata,arrows}
\graphicspath{{images/}{../images/}}
\setcounter{tocdepth}{1}

\newcommand{\transpose}[1]{#1^{\mathsf{T}}}
\newcommand{\inverse}[1]{#1^{-1}}
\newcommand{\iterate}[2]{#1^{(#2)}}
\newcommand{\parens}[1]{ \left( #1 \right) }
\newcommand{\prob}{\mathbb{P}}
\newcommand{\dee}{\mathrm{d}}
\renewcommand{\thesubtable}{\Roman{subtable}}
\DeclareMathOperator{\rank}{rank}
\DeclareMathOperator{\Null}{null}
\DeclarePairedDelimiterX{\norm}[1]{\lVert}{\rVert}{#1}
\DeclarePairedDelimiter{\abs}{\lvert}{\rvert}

\title{Exploring PageRank}
\author{Nathanael Gentry}
\date{30 April 2019}

\begin{document}
\maketitle

\section{Motivation}
In 1995, the public Internet contained about 2.5 million pages
\cite{TotalNumberWebsites}, but search techniques relied upon classical
strategies for collections much smaller and less interconnected than the nascent
Internet. By 1998, two Stanford students -- Sergey Brin and Larry Page --
endeavored to bring order to the Web. The students’ graduate project, then hosted at
\texttt{google.stanford.edu}, did not rely on simple heuristics like URL length
or date of publication; their program used the link structure of the Web itself
to decide how relevant a page was to a user's query. Brin and Page thus defined
their problem as a problem of spectral ranking, or eigencentrality. Spectral
ranking provides a tractable definition of an entity's relative
\textit{importance} within a collection and thus gives an excellent heuristic
for its relevance in a search query. In this paper, we explore the foundation of
the Google enterprise: PageRank, the algorithm that provides a spectral ranking
of all pages on the indexed Web.

\section{First Steps}
\begin{figure}[h]
  \centering \scalebox{0.75}{\begin{tikzpicture}[
			scale=0.6,
      > = stealth,
			shorten > = 1pt,
			auto,
			node distance = 3cm,
			semithick]
			\tikzstyle{every state}=[
			draw = black,
			thick,
			fill = white,
			minimum size = 4mm]

			\node[state] (a) {$p_1$};
			\node[state] (b) [above right of=a] {$p_2$};
			\node[state] (c) [right of=a] {$p_3$};
			\node[state] (d) [below right of=a] {$p_4$};
			\node[state] (e) [right of=c] {$p_5$};

			\path[->] (a) edge node {} (b);
			\path[->] (a) edge node {} (d);
			\path[->] (a) edge node {} (c);
			\path[->] (c) edge node {} (b);
			\path[->] (d) edge node {} (c);
			\path[->] (e) edge node {} (b);
			\path[->] (b) edge [bend left=45] node {} (e);
			\path[->] (d) edge node {} (b);
			\path[->] (e) edge node {} (c);
			\path[->] (d) edge node {} (e);
		\end{tikzpicture}}
  \caption{A Miniscule Web}
  \label{fig:web}
\end{figure}
Consider a digraph $\mathcal{W}$, such as that given in Figure \ref{fig:web}.
Each vertex $p$ represents a Web page, and each edge represents the existence of
at least one hyperlink between pages $p_i$ and $p_j$. We seek to calculate the
importance of a Web page, and we can view a hyperlink to that page as an
endorsement of importance from the linking page. The more such votes of support
a page has, the more important it probably is. The votes of importance imparted
by a Web page should be distributed evenly across the pages it endorses. Let us
now formalize this intuition. Let $N^-_i$ represent the set of $p_i$'s
predecessors, and let $N^+_i$ represent the set of $p_i$'s successors. Note that
$|N^+_i|$ gives the out-degree of $p_i$. We thus define the importance score
$\pi_i$ of a page $p_i$:
\begin{equation}\label{eqn:pi_i}
  \pi_i = \sum_{p_j\in N^-_i}{\frac{\pi_j}{|N^+_i|}}.
\end{equation}

Equation \eqref{eqn:pi_i} gives an impredicative definition of an importance
score.\footnote{Logicians disagree about the distinction between
  \textit{recursion} and \textit{impredicativity}. In this paper, we take
  recursion to be constructive -- that is, recursion builds a class by feeding
  the results of a generator into itself. Impredicativity, however, defines an
  impredicative object $X$ as an instantiation of a class which itself contains
  $X$. Equation \eqref{eqn:pi_i} thus gives an impredicative definition of
  $\pi_i$.} We store all the $\pi_i$ in a vector $\pi$, which we take henceforth
as a row vector.\footnote{Some authors denote row vectors by transposing a
  column vector every time, but we have found this notation wearying. In this
  paper the probability distribution $\pi$ will always be given by a row vector,
  without indication of transposition.} Take some initial score vector
$\iterate{\pi}{0}$, say a uniform distribution $\pi = [1/|\mathcal{W}|]$. Then,
we define an iterative calculation for an iterator $t\geq 1$ to refine the
initial distribution:

\begin{equation}
  \label{eqn:pi_t}
  \iterate{\pi}{t+1}_i = \sum_{p_j\in N^-_i}{\frac{\iterate{\pi}{t}_j}{|N^+_i|}}.
\end{equation}
We encode the system given by Equation \eqref{eqn:pi_i} over $\mathcal{W}$ in a hyperlink matrix:
\begin{equation*}
  H(\mathcal{W})_{ij}=\begin{cases}
    1/|N^+_i|, & \text{if } p_i \in N^-_j; \\
    0, & \text{otherwise}.
  \end{cases}
\end{equation*}

Thus, we have the following iterative calculation:
\begin{equation}
  \iterate{\pi}{k+1} = \iterate{\pi}{k} H.
\end{equation}
The hyperlink matrix gives an adjacency matrix of $\mathcal{W}$ modified to
ensure that each nonzero row provides a probability distribution. By
construction, $H$ is nonnegative; that is, $H_{ij}\geq 0$ for all components.
\begin{figure}[t!]
  \centering
  \begin{subfigure}
    \centering
    $\begin{bmatrix}
      0 & 1/3 & 1/3 & 1/3 & 0 \\
      0 & 0 & 0 & 0 & 1 \\
      0 & 1 & 0 & 0 & 0 \\
      0 & 1/3 & 1/3 & 0 & 1/3 \\
      0 & 1/2 & 1/2 & 0 & 0
    \end{bmatrix}$
    \caption{Hyperlink Matrix for Figure \ref{fig:web}}
    \label{fig:hyperlink}
  \end{subfigure}
  \vspace{2em}
  \begin{subfigure}
    \centering
    \begin{tabular}{|c||c|c|c|c|c|}
      \hline
      $k$ & $\pi_1$ & $\pi_2$ & $\pi_3$ & $\pi_4$ & $\pi_5$ \\
      \hline\hline
      0 & 0.2 & 0.2 & 0.2 & 0.2 & 0.2 \\
      1 & 0 & 0.433 & 0.233 & 0.067 & 0.267 \\
      2 & 0 & 0.389 & 0.156 & 0 & 0.456 \\
      3 & 0 & 0.383 & 0.228 & 0 & 0.390 \\
      4 & 0 & 0.422 & 0.194 & 0 & 0.383 \\
      \hline
    \end{tabular}
    \caption{Score Iteration for Figure \ref{fig:web}}
    \label{fig:example_calculation}
  \end{subfigure}
\end{figure}

Figures \ref{fig:hyperlink} and \ref{fig:example_calculation} show the
hyperlink matrix and some iterative calculations for the digraph given in
Figure \ref{fig:web}. We simply rank the pages by the distribution given in
$\pi$.

Observe that $p_2$ has the highest rank, as most other pages point into it
and it only links to one page. However, this page $p_5$ also receives a high
score, since an important page directly links to it. Our na{\"i}ve approach
shuts out $p_1$ and $p_4$ entirely, which destroys the uniqueness of the
ranking. There are other problems with our formulation. Note that the zero
rows of $H$ correspond to dangling pages, i.e. vertices with zero
out-degree. These rank sinks will break our current calculation, but we
cannot simply exclude them. Some sinks -- for instance, published PDF
documents -- might be highly cited and quite important. Consider also the
trouble posed by cyclic graphs, which would eternally shift their importance
around their cycles. If we continued the iterative calculation in Figure
\ref{fig:example_calculation}, we would find the scores of $p_2$ and $p_5$
keep oscillating as the number of iterations grew. We will discuss the
problem of cyclicity later, but we easily fix can rank sinks by making $H$
fully row-stochastic.

\section{Markov Chains}

\subsection{Stochasticity}
Consider a vector $d$, where $d_i=1$ if page $p_i$ dangles and $d_i=0$
otherwise. Let $v$ be a distribution over all pages in a Web graph
$\mathcal{W}$. We stochasticize $H$ thusly:
\begin{equation}
  \label{eqn:S}
  S=H + d\transpose{v}.
\end{equation}

If an ideal ``random surfer'' on the Web hits a dangling page, it chooses based
upon the distribution $v$ what page to next visit. Let $\mathbbm{1}$ represent a
vector of ones, and note that the row-stochasticity of $S$ implies
$\Vert S \Vert_{\infty} = 1$, i.e. $S \mathbbm{1} = \mathbbm{1}$. Thus,
$(1, \mathbbm{1})$ provides a right eigenpair for every stochastic matrix. Now
consider an eigenpair $(v, \lambda)$ of a stochastic matrix $S$ and suppose
$|\lambda| > 1$. Then, the vector given by $|\lambda|^n v = S^n v$ grows
exponentially, so at least one $(S^n)_{ij} > 1$ for some $n$. This, however,
contradicts the stochasticity of $S$. Thus, we conclude that $|\lambda| \leq 1$,
and since we have already 1 as an eigenvalue, we conclude the spectral radius
$\rho(S)=1$. This result can be proved directly from the Gershgorin circle
theorem, but we will not explore that here.

\subsection{Transition Probability}
As noted above, we can view $S_{ij}$ as the probability that a random surfer on
a Web jumps from page $p_i$ to page $p_j$ at a given time. Thus, we can model
our spectral ranking problem as a Markov chain. In this conversation, we
consider homogeneous Markov chains -- those that have transition probabilities
independent of time. This probabalistic insight leads us to view $S$ as the
1-transition matrix of a finite-state, discrete-time Markov chain. Recall that a
discrete-time stochastic process $\{X_t\}_{t \in T}$ for a countable set $T$
over a finite $n$-sized state space $\Omega = \{s_i\}_{i\leq n}$ is a Markov chain if, for
each $t$, the Markov property holds. Markov chains are colloquially described by
\textit{memorylessness}, which the Markov property formalizes:
\begin{equation*}
  \prob(X_{t+1} = s_j \mid X_t = s_{i_t}, X_{t-1} = s_{i_{t-1}},\cdots, X_0 =
s_{i_0}) = \prob(X_{t+1} = s_j \mid X_t=s_{i_{t}}).
\end{equation*}
We encode the $k$-step transition probabilities for a homogeneous Markov chain
in a stochastic matrix of dimension $|\Omega| \times |\Omega|$:
\begin{equation}
  \iterate{P}{k} = [ \iterate{p}{k}_{ij} ] = [ \prob(X_{t+k} = s_j \mid X_t =
s_i) ] = [ \prob(X_{t} = s_j \mid X_0 = s_i) ].
\end{equation}
Note how the memorylessness of the Markov chain enables the powerful final
equality above. By the definition of the transition matrix, we see
$ [ \iterate{p}{1}_{ij} ] = P$. Now, suppose inductively that
$\iterate{p}{\ell}_{ij} = \parens{\iterate{P}{\ell}}_{ij}$ for all
$i, j \in \Omega$. Then, observe the following:
\begin{align*}
  \iterate{p}{1+\ell}_{ij} &= \prob(X_{\ell+1} = s_j \mid X_0 = s_i) \\
                           &= \sum_{s_k\in\Omega}{\prob(X_1 = s_k \mid X_0 = s_i) \prob(X_{1+\ell} = s_j \mid
                             X_1 = s_k)} && \text{(total probability)} \\
                           &= \sum_{s_k\in\Omega}{\prob(X_1 = s_k \mid X_0 = s_i) \prob(X_{\ell} = s_j \mid X_0 = s_k)} &&
                                                                                \text{(homogeneity)} \\
                           &= \sum_{k\leq
                             |\Omega|}{\parens{\iterate{p}{1}_{ik}\iterate{p}{\ell}_{kj}}}
                           && \text{(definition of transition matrix)}\\
                           &= p^{1+\ell}_{ij}. && \text{(matrix multiplication)}
\end{align*}
From this result, we derive the Chapman-Kolmogorov equations:
\begin{equation}
  \iterate{p}{m+n}_{ij} = \sum_{k\leq |\Omega|}{\parens{\iterate{p}{n}_{ik} \iterate{p}{m}_{kj}}}.
\end{equation}

We will denote the $k$-step transition probability from state $s_i$ to $s_j$ by
directly referencing the components of the transition matrix. Since Markov
chains are memoryless, we simply take each successive iteration as if it were
the first; in this way, we understand that iteration of transitions is given by
matrix multiplication in a homogenous chain. Recall that $k$-paths of graphs are
also given by the $k^\text{th}$ power of the adjacency matrix.

With this in mind, consider a distribution $\iterate{v}{\ell}$ over $\Omega$,
defined by $\iterate{v}{\ell}_i = \prob(X_\ell = i)$. Then, by the total law of
probability, we calculate the following:
\begin{align*}
  \iterate{v}{\ell}_i &= \sum_{s_k\in\Omega}{\prob(X_0 = s_k) \prob(x_\ell = s_i \mid X_0 = s_k)} \\
                      &= \sum_{k\leq |\Omega|}{\parens{\iterate{v}{0}_k \iterate{p}{\ell}_{ki}}}.
\end{align*}

From these results, we conclude that
$\iterate{v}{\ell} = \iterate{v}{0} \iterate{P}{\ell} = \iterate{v}{0} P^\ell$,
for some initial iterate $\iterate{v}{0}$. We have now more clearly justified
the construction of equation \eqref{eqn:pi_t}.

\subsection{Stationarity}
We may take the stochastic process $\{X_t\}_{t \in T}$ underlying a Markov chain
as a categorical distribution over $\mathcal{S}$, the state space.\footnote{The
  categorical (multinoulli) distribution is a generalization of the Bernoulli
  distribution, where each random variable may take one of $k$ states.} A chain
distribution $\pi$ gives a simplex of dimension $|S| - 1$. Choose such a
$P$-invariant simplex. By Brouwer's fixed point theorem, within this simplex
must be a $P$-invariant distribution, i.e., a
$P$-eigenvector.\footnote{Brower's fixed point theorem leads to an elegeant
  argument for Perron's theorem of positive matrices. Michael Brin -- Sergey's
  father -- first advanced such topological arguments for Perron-Frobenius
  theory in 1993. We encourage the reader to consult
  \cite{boyleBasicPerronFrobeniusTheory} for more details. \vspace{0.5em} \\
  Note further that the simplexical argument for the stationary distribution is
  interesting but not at all constructive. We can, in fact, construct an exact
  definition of $\pi$ from the expected number of visits to each state in a
  positive recurrent chain. See \cite{freedmanConvergenceTheoremFinite} for an
  excellent summary of these probabalistic arguments. In this paper, we take a
  linear-algebraic approach to convergence via the Perron-Frobenius theorem. In
  hindsight, we see that our route of exposition might have been the messier
  option. However, since Google determines PageRank through power iteration on
  the transition matrix, our conversation shows more clearly how PageRank works
  in the real world.} We denote this fixed distribution $\pi$ such that
$\pi P = \pi$. That is, $\pi_i = \prob(X_t = s_i)$ for all $t\in T$ over all
states. This time independence defines the stationarity of a distribution $\pi$,
and it thus gives an eigenequation for spectral analysis. Consider a stationary
distribution $\pi$ that is also a limiting distribution, so that we have the
following:
\begin{equation*}
  \pi = \lim_{k\to\infty}{{\iterate{\pi}{k}}} = \lim_{k\to\infty}{\parens{{\iterate{\pi}{0}} P^k}}.
\end{equation*}

In a Markov chain with a limiting distribution, any initial distribution
$\iterate{\pi}{0}$ will eventually converge upon $\pi$. However, a stationary
distribution does not itself imply a limiting distribution. For instance,
consider the Markov chain given by
$P=\begin{bsmallmatrix} 0 & 1 \\ 1 & 0 \end{bsmallmatrix}$. This standard
example corresponds to turning a coin over, so the opposite state is reached
with certainty at each step. However, the probability of revealing a certain
face at a given step depends entirely upon the initial state -- what face of the
coin was initially facing up. Thus, this chain does not have a limiting
distribution. However, we have an easy stationary distribution:
$v = [\frac{1}{2}, \frac{1}{2}]$, corresponding to choosing the initial state by
flipping a fair coin. The stationary distribution hides the chain's dependence
upon its initial state. However, if we have a biased coin, say one for which
$\iterate{v}{0} = [\frac{3}{5}, \frac{4}{5}]$, the transition probabilities at
each turn of the coin clearly depend upon the initial state of the coin.

We can also show that no limiting distribution exists by examining the
transition matrix. As $k\to\infty$, the iterate $\iterate{P}{k}$ swaps certainty
of transition between states; it alternates between $P$ and $I$. Thus, the limit
of the transition matrix does not exist, and so a limiting distribution does not
exist.

The nature of our spectral ranking problem thus becomes stunningly clear, for
the time-independent probabilities within $\pi$ yield a unique metric of the
importance we have sought to codify. We can predict, from the structure of the
Web itself, how much time a random Web surfer will spend on a given page, and we
can take these probabilities as evidence for how important a page actually is.
Analyzing the asymptopic behavior of $P$ will show us when such a limiting
distribution exists, and we will thus know when we have a unique solution to the
stationary eigenequation. We now answer the vital question of when a Markov
chain has such distribution by exploring a fundamental theory of dynamical
systems.

\section{Perron-Frobenius Theory}

\subsection{Irreducibility}
In a Markov chain, states $s_i$ and $s_j$ communicate if
$\iterate{P}{k}_{ij} > 0$, for some iterate $k$. That is, there is a path of
nonzero probability (a random walk) between states $s_i$ and $s_j$.
Communicativity is easily shown to be an equivalence relation.

Consider partitioning a Markov state space $\Omega$ of size $n$ into partitions
$\Omega_1 = \{ s_i \}_{i\leq k}$ and $\Omega_2 = \{ s_j \}_{k < j \leq n}$.
Moreover, suppose there are random walks from $\Omega_2$ to $\Omega_1$ but none
the other way. Note that the chain eventually never visits states in $\Omega_2$;
when $\Omega_1$ is a communicating class, the chain reduces to the states of
$\Omega_1$. We model such reducibility of a Markov chain in a lower-triangular
canonical form:
\begin{equation*}
  \label{eqn:reducible}
  P =
  \begin{bmatrix}
    \omega_{1\to 1} & 0 \\
    \omega_{2 \to 1} & \omega_{2 \to 2}
  \end{bmatrix},
\end{equation*}
where $\omega_{1\to 1}$ and $\omega_{2\to 2}$ are substochastic square matrices
representing transition probabilities within $\Omega_1$ and $\Omega_2$,
respectively, and $\omega_{2 \to 1}$ holds the transition probabilities from
$\Omega_2$ to $\Omega_1$. Note that when $\omega_{2\to 1} = 0$, the chain is
disconnected and so \textit{completely} reducible.

We say a Markov chain is irreducible if and only if it contains a single
communicating class. Equivalently, a digraph is irreducible when it has no
strongly connected components (SCCs) smaller than itself.\footnote{Note that a
  topological sort on a reducible graph can factorize it into its disjoint
  strongly-connected components.} An irreducible matrix is a matrix
corresponding to such irreducible objects. Note that an irreducible matrix is
nonnegative; the transition matrix motivation above shows the classes of
reducibility and irreducibility arise through the arrangement of zeroes within
the matrix. To find reducbility in a chain-graph, we simply attempt to permute
the state-vertices in the underlying matrix to obtain the above canonical form.

Consider further what reducibility means in a Markov chain. As time passes, the
probability of visiting the pages in $\Omega_2$ drops to zero. To our iterative
importance calculation on Web pages, these pages will eventually appear not at
all important, but there is no reason why they shouldn't be. We must not permit
this artifact of the Web structure to corrupt our importance scores. For now, we
take reducibility of a Markov chain as a hypothetical difficulty; later, we will
see that the real Web is quite reducible and requires a less naïve model to give
convergent and unique importance scores.

\subsection{Periodicity}
Consider a Markov chain with states $s_i \in \mathcal{S}$. Let
$D(s_i) = \{n\in \mathbb{Z}_{\geq 0} : \iterate{p}{n}_{ii} > 0 \} \subset
\mathbb{N}$. Note that $D(s_i)$ is trivially nonempty, as
$\iterate{p}{0}_{ii} = 1$ for all $s_i$. We observe that $D(s_i)$ forms a
numerical semigroup under addition. We define the period of a state by
$d(s_i)=\text{gcd}\{D(s_i)\}$. In other words, a random walk (a path where each
step has nonzero probability) from state $s_i$ can only return to $s_i$ in
multiples of $d(s_i)$ steps. Consider states $s_i$ and $s_j$ in the same
communicating class. Thus, $\iterate{p}{m}_{ij} > 0$ and
$\iterate{p}{n}_{ji} > 0$ for some nonnegative iterators. Otherwise stated,
consider a random $m$-path from $s_i$ to $s_j$ and a a random $n$-path from
$s_j$ to $s_i$.
\begin{figure}[h]
  \centering \scalebox{0.75}{\begin{tikzpicture}[
			scale=0.6,
      > = stealth,
			shorten > = 1pt,
			auto,
			node distance = 3cm,
			semithick]

			\tikzstyle{every state}=[
			draw = black,
			thick,
			fill = white,
			minimum size = 4mm]

			\node[state] (a) {$s_i$};
			\node[state] (b) [right of=a] {$s_j$};

			\path[->] (a) edge [bend left=45] node {$m$-step} (b)
      (a) edge [loop above]   node {$\ell$-step} (a)
      (b) edge [bend left=45] node {$n$-step} (a);
		\end{tikzpicture}}
  \caption{Communicating States}
  \label{fig:markov}
\end{figure}

Figure \ref{fig:markov} illustrates these cycles. Note that there are random
cycles of length $\ell \equiv m+n \pmod{d(s_i)}$ on state $s_i$. The
communicativity of $s_i$ and $s_j$ implies $\iterate{p}{n+m}_{jj} > 0$ and
$\iterate{p}{n + \ell + m}_{jj} > 0$. That is, there is a random $\ell$-cycle on
$s_j$; moreover, there is a random cycle on $s_j$ that goes from $s_j$ to $s_i$
and returns to $s_i$ before terminating at $s_j$. Thus, $d(s_j) \mid \ell$.
However, since we have shown that $s_i$ has a random $\ell$-cycle, we know that
$d(s_j) \mid d(s_i)$. By the symmetry of $s_i$ and $s_j$, we find
$d(s_i) \mid d(s_j)$, and so $d(s_i) = d(s_j)$ whenever $s_i$ and $s_j$
communicate. Thus, when $P$ is irreducible, $d(P)$ is well-defined; every state
has the same period. When $d(P) = 1$, we say the Markov chain is aperiodic.

\subsection{Primitivity}
Much has been said on the conditional convergence of periodic Markov chains, but
we confine this conversation to the aperiodic case. Suppose we have an aperiodic
irreducible Markov chain, and recall $D(s_i)$, the numerical semigroup given
above.\footnote{Markovian semigroups form an important part of ergodic theory,
  which we barely explore here.} For a semigroup $V$ with $d=\gcd(V)$, it can be
shown that there exists an integer $N$ such that $v\equiv n \pmod{d}$ for any
$v\in V$ and all $n \geq N$. Since we have supposed an aperiodic Markov chain,
we have a coprime numerical semigroup. Thus, there is some bound $t_i$ beyond
which $\iterate{p}{t}_{ii} > 0$ for all $t \geq t_i$ over all states. By the
irreducibility of the chain, we have a $k = k_{(i,j)}$ for which
$\iterate{p}{k}_{ij} > 0$. Thus, for $t \geq t_i + k$, the Chapman-Kolmogorov
equations yield the following:
\begin{align*}
  \iterate{p}{t}_{ij} \geq \iterate{p}{t-k}_{ii} \iterate{P}{k}_{ij} > 0.
\end{align*}
Let $t'_i = t_i + \max_{j\in\Omega}\{ k_{(i,j)} \}$. Thus, for $t \geq t'_i$, we
have $\iterate{p}{t}_{xy} > 0$ for all $y\in\Omega$. Then, for
$t \geq \max_{i\in\Omega}\{ t'_i \}$, we conclude that, for an irreducible
aperiodic chain, there is a $t$ that gives $\iterate{p}{t}_{ij} > 0$ over all
states, and so $P^t > 0$. We take this result as the definition of matrix
primitivity.

Primitivity is irreducibility plus aperiodicity. Recall that a merely
irreducible Markov chain requires an iterate-function of state pairs. However, a
primitive chain guarantees that \textit{all} states communicate -- not just that
they are a part of the same communicating class -- after $t$ transitions.

Consider a primitive Markov chain with eigenpair $(v, \lambda)$. The underlying
primitivity of the transition matrix $P$ gives $P^k v = \lambda^k v > 0$ for
some iterate $k$ and forever thereafter, so we see the eigenpair must be
positive. Take another eigenpair $(w, \gamma)$ such that $\norm{w} < \norm{v}$
and $\gamma = \rho(P)$. Then for all iterates $n$, we have the following:
\begin{equation*}
  \gamma^n w = P^n w \leq P^n v = \lambda^n v.
\end{equation*}
However, since we supposed $\norm{w} < \norm{v}$, we cannot have
$\beta < \lambda$. By the inequality above, we must conclude $\beta = \lambda$,
and so a primitive $P$ has only one eigenvalue on its spectral circle, namely
the spectral radius itself. This eigenvalue is the dominant eigenvalue of $P$.
Since all stochastic matrices have spectral radius 1, we conclude that primitive
Markov chains have an eigenpair $(1, \pi)$. This is exactly what we want to
satisfy our limiting distribution condition $\pi = \pi P$. The following
spectral properties of primitive Markov chains should not be terribly surprising
by now, but they are are quite beautiful.

\subsection{Perron-Frobenius Theorem}
Perron's theorem, proved in 1907, provided spectral properties of positive
matrices -- most notably, that such matrices have only one eigenvalue on their
spectral circle, the dominant eigenvalue $\lambda_1=\rho(A)$. However, Perron's
results results did not generally apply to nonnegative matrices. Frobenius
subsequently realized that irreducible matrices behave like positive matrices,
except that they may have multiple eigenvalues that are roots of unity of
$d(P)$. Primitive matrices, however, do have a dominant eigenvalue, as we have
seen above. The Perron-Frobenius theorem, proved in 1912, gives the following
properties for a primitive square matrix:
\begin{enumerate}
\item The spectral radius $\rho$ equals some real eigenvalue $\lambda_1$;
\item This eigenvalue (the Perron root) is simple, and it is the only eigenvalue on the spectral circle;
\item The Perron root has unique, strictly positive left and right eigenvectors (Perron vectors);
\item These left and right Perron eigenvectors are, up to normalization, the only nonnegative eigenvectors of $A$.
\end{enumerate}
Note that the Perron root is a dominant eigenvalue; it is the unique $\lambda_1$
such that $|\lambda_1|>|\lambda_2|\geq\cdots\geq |\lambda_{n}|$ for all
$\lambda \in \sigma(A)$. Recall that $A$ and $\transpose{A}$ share a spectrum,
and a left eigenvector of $A$ is a right eigenvector of $\transpose{A}$.

We will not prove the complete Perron-Frobenius theorem in this paper -- its
full statement contains far more than we have given here -- although we have
heretofore outlined some basic arguments for the properties we find useful for
spectral ranking.

\section{Limiting Distributions}

\subsection{Spectral Resolution\protect\footnote{The results in this section
    summarize the extended treatment of matrix functions and convergence given
    in \cite{meyerMatrixAnalysisApplied2000}}.}
Recall that, for a a diagonalizable matrix $A=PD\inverse{P}$, the columns of the
similarity transformation $P$ correspond to distinct right eigenvectors of $A$.
Consider partitioning $P$ into bases $\beta_{\mathcal{E}_\lambda}$ for distinct
right eigenspaces of $A$. Similarly, we partition the rows of $\inverse{P}$ into
bases $\gamma_{\mathcal{E}_\lambda}$ for distinct left eigenspaces. Thus, for a
matrix $A$ with with spectrum $\sigma$, we have an outer product formulation of
the spectral decomposition:
\begin{equation}
  \label{eqn:spectral_decomposition}
  A = PD\inverse{P} = \sum_{\lambda\in\sigma}{\lambda [\beta_{\mathcal{E}_\lambda}]\transpose{[\gamma_{\mathcal{E}_\lambda}]}}.
\end{equation}

Note that
$E_\lambda =
[\beta_{\mathcal{E}_\lambda}]\transpose{[\gamma_{\mathcal{E}_\lambda}]}$
projects onto the eigenspace $\mathcal{E}_\lambda$. In fact, $A$ is
diagonalizable if and only if it can be written as a sum of such spectral
projectors. Consider $x$ and $\transpose{y}$ as the handed eigenvectors of a
simple eigenvalue $\lambda_s$. We see this elegant formula for the corresponding
eigenprojection:
\begin{equation}
  \label{eqn:simple_eigenprojection}
  E_{\lambda_s} = \frac{x \transpose{y}}{\transpose{y} x},
\end{equation}
where the inner product in the denominator comes from normalization to ensure projection properties.

\subsection{Matrix Functions}
Consider generalizing a scalar function $f$ to be a matrix function. As the
well-known matrix exponential illustrates, we often do not define matrix
functions as scalar functions applied entrywise, for we then might lose the nice
properties associated with the scalar functions. Using the Taylor expansion of a
sufficiently-differentiable $f$, we first define such a function about a Jordan
block $J_k(\lambda)$:
\begin{equation*}
  f\big( J_k(\lambda) \big)=f(\lambda)I + f'(\lambda)(J_k(\lambda) - \lambda I) + \frac{f'(\lambda)(J_k(\lambda) - \lambda I)^2}{2!} + \cdots.
\end{equation*}
However, since $(J_k(\lambda) - \lambda I)$ is nilpotent of order $k$, the
Taylor expansion reduces nicely:
\begin{equation}
  \label{eqn:f_jordan_block}
  f\big( J_k(\lambda) \big) = \sum_{i=0}^{k - 1}\parens{\frac{f^{[i]}(\lambda)}{i!} (J_k(\lambda) - \lambda I)^i}.
\end{equation}

Thus, for $f$ with at least $(k - 1)$ derivatives that exist at $\lambda$, we
have the definition of a function applied to a Jordan block:
\begin{equation}\label{eq:f_jordan_block}
  f\big( J_k(\lambda) \big) =
  \begin{bmatrix}
    f(\lambda) & f'(\lambda) & \frac{f''(\lambda)}{2!} & \ldots & \frac{f^{[k - 1]}(\lambda)}{(k-1)!} \\
    0 & f(\lambda) & f'(\lambda) & \ldots & \frac{f^{[k - 2]}(\lambda)}{(k-2)!} \\
    0 & \vdots & \vdots & \ddots & \vdots \\
    0 & 0 & 0 & \ldots & f(\lambda)
  \end{bmatrix}.
\end{equation}

For a diagonalizable matrix $A$ as above, note that we can we apply Equation
\eqref{eqn:spectral_decomposition} to obtain a nice result:
\begin{align*}
  f(A) = Pf(D)\inverse{P} = \sum_{\lambda \in \sigma}{f(\lambda) E_\lambda}.
\end{align*}

We can extend $f$ to a Jordan form $J$ by requiring that $f$ has at least
$(\iota - 1)$ derivatives, where $\iota = \iota_\lambda$ is the index of
$\lambda$, i.e., the size of the largest $\lambda$-block. Then, for $A$ with
spectrum $\sigma$, not necessarily diagonalizable, we have this function
definition:
\begin{equation*}
  f(A) = P f(J) \inverse{P} = \sum_{\lambda \in \sigma}\parens{ [\beta_{\mathcal{E}_\lambda}]\, f\big( J_{k_\lambda}(\lambda) \big)\, \transpose{[\gamma_{\mathcal{E}_\lambda}]} }.
\end{equation*}
Expanding the definition of the function and applying the eigenprojection gives
this form:
\begin{equation}
  f(A) = \sum_{\lambda \in \sigma}\sum_{j=0}^{\iota_{\lambda} - 1}\parens{ \frac{f^{[j]}(\lambda)}{i!} (J_{k_\lambda}(\lambda) - \lambda I)^j E_{\lambda} }.
\end{equation}

\subsection{Matrix Convergence}
Consider the function $f(x) = x^n$ for some real $n$. Note that when we apply
$f$ to a Jordan block, we can easily give the coefficients of differentiation as
binomial coefficients.
\begin{equation}\label{eq:power_jordan_block}
  \big( J_k(\lambda) \big)^n =
  \begin{bmatrix}
    \lambda^n & \binom{n}{1}(\lambda^{n-1}) & \binom{n}{2}(\lambda^{n-2}) & \ldots & \binom{n}{k-1}(\lambda^{n-(k+1)}) \\
    0 & \lambda^n & \binom{n}{1}(\lambda^{m-1}) & \ldots & \binom{n}{k-2}(\lambda^{m-(k+2)}) \\
    0 & \vdots & \vdots & \ddots & \vdots \\
    0 & 0 & 0 & \ldots & \lambda^n
  \end{bmatrix}.
\end{equation}
In general, then, we define $f(A)$ thusly:
\begin{equation}
  A^n = \sum_{\lambda \in \sigma}\sum_{j=0}^{\iota_{\lambda} - 1}\parens{ \binom{n}{j} \lambda^{n-j} (J_{k_\lambda}(\lambda) - \lambda I)^j E_{\lambda} }.
\end{equation}

Suppose $| \lambda | < 1$. Then, for each $j \in [1, n-(k+1)]$, we have
\begin{equation*}
  \abs*{\binom{n}{j}\lambda^{m-j}} \leq \frac{k^j}{j!}{\abs*{\lambda^{m-j}}}.
\end{equation*}
Note that as $m \to \infty$, the numerator $k^j$ diverges polynomially since $j$
is fixed. However, since $| \lambda | < 1$, $\abs{\lambda^{m-j}}$ converges to
zero exponentially. Thus, we conclude the following:
\begin{equation*}
  \lim_{n\to\infty}{\big( J_k(\lambda) \big)^n} = 0.
\end{equation*}
We can extend this argument to show that, for a square matrix $A$,
$\lim_{n\to\infty}{\parens{A^n}} = 0$ if and only if $\rho(A) < 1$, and similar
reasoning shows the limit does not exist when $\rho(A) > 1$.

We now study the convergence of a matrix with $\rho(A) = 1$, such as we have
with all stochastic (and primitive) matrices. Suppose we have a primitive Markov
chain with transition matrix $P$. By the Perron-Frobenius theorem, we know $P$
has dominant eigenvalue $\lambda_1 = 1$. As all non-dominant eigenvalues have
modulus less than 1, we simply have the following:
\begin{equation*}
  \lim_{n\to\infty}{A^n} = E_{\lambda_1}.
\end{equation*}
Powers of a primitive matrix will eventually converge upon the dominant
eigenprojector. For primitive Markov chains, we have a left eigenvector $\pi$,
the stationary distribution. Moreover, we previously showed that all stochastic
matrices have right eigenvector $\mathbbm{1}$. Thus, using the limit we just
discovered, we have a limiting distribution:
\begin{equation}
  \lim_{k\to\infty}{{\iterate{\pi}{k}}} = \lim_{k\to\infty}{\parens{{\iterate{\pi}{0}} P^k}} = \iterate{\pi}{0} \parens{\frac{\mathbbm{1} \pi}{\pi \mathbbm{1}}} = \parens{\iterate{\pi}{0} \mathbbm{1}} \pi = \pi.
\end{equation}
Thus, primitivity guarantees a distribution completely independent of the
chain's starting state. The convergence of a primitive chain is a rather
remarkable result, one often called the fundamental theorem of Markov chains.

\subsection{Power Iteration}
Applying Perron-Frobenius theory to primitive Markov chains gives a classical
method for calculating the limiting distribution. Techniques based on Gaussian
elimination would not be a smart choice for calculating a limiting distribution
$\pi$ of the Internet, since this family of alogrithms generally has arithmetic
complexity of order $O(n^3)$.

Here, we explore the power method -- the simplest iterative calculation method.
Suppose a square matrix $A$ has $n$ eigenpairs $\{ (\lambda_i,x_i) \}_{i\leq n}$
with $\lambda_1$ as a dominant eigenvalue. Consider a starting vector
$x^{(0)}=\sum_i{\gamma_i x_i}$ for scalars $\gamma_i$. Then, we again consider
an iterative calculation:
\begin{equation}
  \iterate{x}{k} = A^k \iterate{x}{0} = \sum_{i=1}^{k}{\gamma_i \lambda_i^k x_i} = \lambda_1^k\parens{\gamma_1 x_1 + \sum_{i=2}^{k}{\gamma_i \frac{\lambda_i}{\lambda_1} x_i}} \to \lambda_1^k \gamma_1 x_1.
\end{equation}
Since $\lambda_i<\lambda_1$ for $i>1$, the sum approaches 0 as $k\to\infty$. The
speed of convergence clearly depends upon the subdominant eigenvalue
$\lambda_2$. Power method applications often normalize the the estimated
eigenvector after each iteration to avoid underflow or overflow under successive
powers of the eigenvalue, but we need not worry about this since primitive
Markov chains have dominant eigenvalue $\lambda_1 = 1$.

\section{The Google Matrix}
Deriving a limiting distribution from the Web graph still requires a bit more
work, for the real Web is quite reducible.
\begin{figure}
  \centering
  \includegraphics[scale=0.6]{bow-tie}
  \caption{The Bow Tie \cite{broderGraphStructureWeb}}
  \label{fig:bow-tie}
\end{figure}
In 1999, \cite{broderGraphStructureWeb} crawled over 1.5 billion links to
generate a comprehensive map of the Web. Their macroscopic figure, given in
Figure \ref{fig:bow-tie}, stylizes the Web super-graph as a rather eldritch bow
tie. Note that the figure has the form of a directed acyclic graph given from a
topological sort. In the middle is the ``bow knot'' -- the largest
strongly-connected component (SCC) of the Web. In 2012, when the last public Web
mapping occured, about half of mapped Web pages were strongly connected. The
``thistle ends'' of the tie, denoted \texttt{IN} and \texttt{OUT}, respectively
reference pages from which surfers can link into (out of) the SCC but cannot
return by the same route. Pages within the tendrils and tubes are likewise
unidirectional on this macroscopic scale: They be reached from \texttt{IN} and
\texttt{OUT}, but these components cannot be reached from within them. Although
the numbers in Figure \ref{fig:bow-tie} are obsolete, its bow-tie model wtill
describes the Web well.

We previously eliminated individual dangling pages, but we could view these
entire tendrils and tubes again as ``dangling pages,'' and we can again correct
for them. In our Markov discussion, we interpreted the stochastic Web matrix $S$
as the matrix of probabilities that an ideal random surfer follows links from a
page or chooses another randomly when it hits a dead end. However,
\textit{human} Web surfers often get bored. They will not follow a linear path
through the Web; they might suddenly elect to teleport -- shift course
altogether and visit a page on whim. Let $\mathbbm{1}$ represent a vector of
ones, and again consider a distribution $u$ over all Web pages. We model this
teleportation behavior with a rank-one matrix $T = \mathbbm{1}\transpose{u}$.

Now, consider a matrix $G$ formed from a convex combination of $S$ and $T$:
\begin{equation}
  \label{eqn:google_matrix}
  G = \alpha S + (1-\alpha)T.
\end{equation}
Every page now communicates with every other page, and our process is still
stochastic. In fact, $G$ is trivially primitive, as each page has a random loop.
In this model, the random surfer on page $p_i$ follows the Web's link structure
about $\alpha s_i$ percent of the time and teleports with probability
$(1-\alpha) u_j$. Note that the teleportation matrix need not give equal
deference to each Web page. External factors -- a user's search preferences or
browsing habits or a search engine's fiat against suspected abusers -- can
influence the teleportation probabilities. Here, however, we take a rank-one
distribution. The teleportation factor $\alpha$ dampens the wild, raw Web graph
into a more friendly model; it is the damping factor.

Note that the teleportation adjustment provides all we need for a guaranteed
limiting distribution, from which we can directly rank pages. In sum, $G$ simply
represents a lazy random walk on the Web graph $\mathcal{W}$. The matrix $G$ is
the Google matrix -- the original foundation of PageRank calculations.

Although the primitive Google matrix is completely dense, we can expand $S$ and
$T$ into their constituent distributions $v$ and $u$ to obtain a power
iteration:
\begin{align*}
  \iterate{\pi}{k+1} &= \iterate{\pi}{k} G
                     = \alpha \iterate{\pi}{k} (H + d \transpose{v}) + (1 - \alpha) \iterate{\pi}{k} (\mathbbm{1} \transpose{u}).
\end{align*}

Note that the rank-one reduction given above does not require us to actually
generate the dense component matrices $S$ and $G$. Unlike decompositional
methods (e.g. UR factorization and GMRES), we do not ruin the sparsity of $H$.
As we see above, we must only store the current iterate $\iterate{\pi}{k}$ and
the dangling page vector $d$ to apply the power method; we do not need $O(n^2)$
matrix multiplication. We need only perform vector-matrix multiplication on the
very sparse $H$, and sparse multiplications have approximate complexity
$O(\eta(H))$, where $\eta(H)$ is the number of nonzero elements in $H$.
Empirical data shows the average Web page has about 10 outgoing links, so
$\eta(H) \approx 10n$.

When we apply the power method to a primitive matrix, we have an
essentially linear algorithm. The power method beats more complex algorithms
here because it gives only the simple result we want: the dominant eigenvalue of
a primitive matrix. However, the convergence of a primitive Markov chain depends
upon how quickly powers of its subdominant eigenvalue converge to zero. We now
examine this eigenvalue more closely, and also investigate an optimum value for
$\alpha$.

\section{Network Topology}
\begin{figure}
  \centering
  \includegraphics[scale=1.8]{scale-free-network}
  \caption{A Scale-Free Network (Yeast Proteome) \cite{wangKineticConformationalCharacterization}}
  \label{fig:scale-free}
\end{figure}

\subsection{Near-Reducibility}
Consider a Markov chain given by
$P=\begin{bsmallmatrix} 1 & 0 \\ 0 & 1 \end{bsmallmatrix}$. The chain is fully
reducible, and equivalently, the underlying graph is disconnected. Clearly, $P$
will only have eigenvalue 1 with multiplicity 2. Suppose now we have a chain
with
$P'=\begin{bsmallmatrix} 1 - \epsilon_1 & \epsilon_1 \\ \epsilon_2 & 1 -
  \epsilon_2 \end{bsmallmatrix}$, for $\epsilon \in (1,0)$. Thus, the spectrum
$\sigma(P') =P' \{ 1, 1-\epsilon_1 - \epsilon_2 \}$.

Nearly-reducible Markov chains have strong interactions within their clusters,
but relatively weak interactions between clusters.\footnote{The formal study of
  clustering in Markov chains is a well-developed field much more clearly
  understood through the probabilistic convergence theorem, which we have
  eschewed in this paper for a linear-algebraic focus. Powerful analysis of
  graph clustering and subdominant eigenvalues can also be done through the
  graph Laplacian, but we will not expound that tool here.} Considering the
canonical form of reducibility in Equation \eqref{eqn:reducible}, we note that
an irreducible Markov chain with subdominant eigenvalue $\lambda_2 \approx 1$
will be nearly reducible. However, the existence of such a subdominant
eigenvalue does not itself ensure near-reducibility.

\subsection{Scale-Free Networks}
In 1959, Erdős and Rényi proposed generating random graphs by considering a
Poisson distribution over the out-degree of vertices. In such a random graph
(also called an exponential network), most nodes share a similar number of
out-links, and there are very few nodes that deviate from this mean. A random
network is thus very democratic and has a steep bell curve. Most natural
networks, however, do not follow a random structure.
\begin{figure}
  \centering
  \includegraphics[scale=0.15]{random-graph}
  \caption{A Random Graph \cite{RandomGeometricGraph}}
  \label{fig:random}
\end{figure}
Consider Figure \ref{fig:scale-free}, which maps the partial proteome of a
yeast. The red nodes, which denote proteins most essential for life, tend to
bind together clusters of proteins of lesser importance. Note our use of the
term \textit{importance} here. If we only had the proteome graph, sans color, we
would likely be able to determine which proteins were most ``important'' for
life by computing a spectral rank like the PageRank. Indeed, we have assumed
from the start that the most connected nodes are the most important nodes. In
fact, HITS -- another spectral rank developed at IBM contemporaneously with
PageRank -- makes the pursuit more explicit by splitting Web pages into hubs and
authorities; it uses the more complex heuristic that good hubs link to good
authorities and vice versa. In a random graph, however, such a definition of
importance breaks down.

A music theorist analyzes a piece of classical music by first determining what
chords are most important -- that is, what chords are most tonally connected to
other chords. However, an atonal piece by Schönberg defies such straightforward
analysis. A twelve-tone series ensures an equal distribution of tones so no few
tones or chords distinguish themselves as tonally important, just as a random
graph ensures no few nodes stand out.\footnote{Note that this does not mean
  atonal music is ``random" in the standard sense; just like an Erdős-Rényi
  random graph, an atonal piece provides little information about the
  connections between tones. Thus, from a tonal perspective, we cannot easily
  determine which chords are more important than others. Tonality concerns
  itself about relations between chords, and these relations are evenly
  distributed by design in a twelve-tone piece. The progressions in such a piece
  mostly sound alike to our tonal ears, except for a few serendipitous ones that
  give a fleeting sense of tonality. This perhaps gives
  insight into why Schönberg abhored the label \textit{atonal} and much
  preferred to call his music \textit{pan-tonal}.}

Networks such as these follow a power law. The probability that a node has $k$
outlinks is proportional to $1/k^\gamma$, for some power $\gamma$. Although most
nodes have only a few links to others, a few have thousands. Removing just these
most important nodes (the hubs) can catastrophically fragment the network into
its isolated components disrupt the network. These networks also reveal a
beautiful fractal structure, so we we call them scale-free networks.
Sociologists have long known of these networks. The Erdős number and the ``six
degrees of Kevin Bacon'' work because a few people are highly connected; they
bridge groups of people who would otherwise be unrelated. Income distribution in
Western countries can be similarly modeled with a scale-free network. Note that
scale-free networks will also be very reducible, as they have strong
interactions within their clusters but relatively weak interactions among them.

Both the physical and logical Internet have been shown to be scale-free
networks. The Internet is thus highly resilient to random attacks, but
destroying just about 3\% of hubs -- the most highly connected ones -- would be
enough to fragment the Internet into dozens of isolated components
\cite{barabasiNetworkScienceScaleFree}. This suggests that even the large SCC of
Figure \ref{fig:web} is vulnerable to targeted attacks. By contrast, the
strongly-connected components of a random graph would be quite strong, as a
random graph does not encode much information in unique locations.

As we have seen, only scale-free networks have a sufficiently heterogeneous,
information-rich structure to permit a meaningful spectral importance rank.
Thus, Markov chains over scale-free networks will have a subdominant eigenvalue
quite close to $\lambda_1 = 1$. Although the teleportation adjustment ensured
the primitivity of the Google matrix, it still tends to leave the dampened Web
only weakly irreducible -- that is, nearly reducible.

\subsection{Damping Factor}
Recall $\alpha$, the damping factor used in Equation \eqref{eqn:google_matrix}.
This probability $\alpha$ controls the fidelity of the model to the raw Web
structure. As $\alpha \to 1$, the Google matrix becomes more nearly reducible,
its subdominant eigenvalue $\lambda \to 1$, and the power method converges ever
more slowly. Moreover, as $\alpha \to 1$, the limiting distribution becomes far
more sensitive -- both in terms of importance score and the consequent PageRanks
-- to link changes even within minor clusters; further approaching 1 magnifies
these effects. We can explore these results more by analyzing the vector
derivative $\dee\pi(\alpha)/\dee\alpha$, but we will not do so here.

We learn in \cite{haveliwalaSecondEigenvalueGoogle} that a stochastic matrix $S$
with $\sigma_S = \{ 1, \lambda_2, \lambda_3, \cdots, \lambda_n \}$ gives a
Google matrix with
$\sigma_G = \alpha\sigma_S = \{ \alpha, \alpha\lambda_2, \alpha\lambda_3,
\cdots, \alpha\lambda_n \}$. From this, we see $\lambda_2 \leq \alpha$ for the
Google matrix. Thus, the power method converges at the rate which
$\alpha^k \to 0$ as $k$ grows. With $\alpha = 0.85$, Google's formulation of the
power method converges within a thousandth by approximately 50 iterations. Note
that the power method scales well to immense datasets like the Web graph -- it
requires at most 100 iterations to converge upon a unique ranking all pages on
the indexed Web.

\section{Evaluation}
Since PageRank incorporates the entire Web into its calculation, it is
query-independent. The refinements given in
\cite{haveliwalaAnalyticalComparisonApproaches2003} adapt the stochasticity and
teleportation distributions to provide a personalized PageRank. Query-dependent
algorithms like HITS beat PageRank in personalized searching, as they run a
power method on small components of the Web. However, the more serious induced
deficiencies -- like more imprecise ranking and susceptibility to link spamming
-- have made PageRank the dominant spectral ranking algorithm on the Web.
Moreover, the definition of importance built into PageRank means it can predict
backlinks (citations) well; Brin and Page \cite{brinPageRankCitationRanking1998}
showed that PageRank determines an optimal path for Web crawlers, who should
index the most important parts of the Web quickly and not be trapped by
closely-linked local chains.

Google still relies heavily upon the traditional vector space relevance models
and sophisticated analysis of anchor text, font style, and capitalization.
PageRank, after all, addresses a specific problem of structural relevance; other
systems must decide the a page's contextual relevance to a query. PageRank,
however, forms the central part of Google's search strategy -- a system designed
to scale even to a Web with $10^{100}$ pages -- a \textit{googol}.

\newpage
\bibliographystyle{ieeetr}
\bibliography{references}
\end{document}


\section{Arcana Rune}\label{rune:arcana}
\textbf{Cost:} 50 CP\\
\textbf{Requirements:} -\\
\textbf{Rune, Weapon, Active, Repeatable, Source (50 Gold)}\\
You have mastered the Arcana Rune.
It is associated with the basic flow of magic and manifests into an elemental force that is neutral of every element.
While Arcana seems to be a very simple Rune, especially for new Apprentices, it has many strong powers and enjoys synergies with other Elements, allowing it to be used in a multitude of Spells.\\

\subsection{Rank I Abilities}

\subsubsection{Arcane Bolt}
For 4 AP and 3 Mana, you create a bolt of magic out of thin air and hurl it towards an enemy.
Make a ranged magic weapon attack.
The bolt deals 2d4 piercing damage.

\subsubsection{Feel Arcane Energy}
Thanks to your attunement with the arcane energies, you can feel the presence of magic.
Any form of the Arcana Rune slightly starts glowing when it touches some magical item, unless that item is shielded from such detection in some form.

\subsection{Rank II Abilities}
\textbf{Cost:} 500 CP\\
\textbf{Source:} 350 Gold
\subsubsection{Enhanced Arcane Bolt}
When creating an Arcane Bolt you can now spend 6 Mana to create two bolts instead.
Each of these bolts can target different enemies, and each of the bolts requires its own attack roll.

\subsubsection{Arcane Blast}
You can create a blast of magic energy at a point in a range of \passus{9} around you.
This takes 6 AP and 15 Mana.
Any creature in a radius of \passus{3} around your chosen point takes 4d6 blunt damage and must make a Strength check, contested by your Intelligence Check.
If they fail, they are pushed \passus{1} away from the point of origin of the blast, and fall prone.

\subsubsection{Feel Lingering Magic}
Your attunement to the magical energies around you have become stronger.
Now your Arcana Rune also starts glowing in an area where magic has been cast recently.
For every point of Mana spent in an area, the lingering aura lasts for an additional 10 minutes.

\subsection{Rank III Abilities}
\textbf{Cost:} 1,000 CP\\
\textbf{Source:} 650 Gold
\subsubsection{Arcane Bolt}
When creating an Arcane Bolt you can now spend 9 Mana to create three bolts instead.
Each of these bolts can target different enemies, and each of the bolts requires its own attack roll.

\subsubsection{Strong Arcane Blast}
You can now create a stronger arcane blast.
The range in which you can choose its point of origin has increased to \passus{12} and the radius of the blast itself has increased to \passus{5}.\\
Additionally, you can now expand 20 Mana instead to deal 10d6 blunt damage.

\subsubsection{Arcane Sight}
You now have the ability to see magical energies circulating around you.
In order to do so, you must close your eyes and spend 1 Mana per Action Point.
Magical Energies swirl around the Universe like a web or radiation, allowing you to discern shapes of creatures and objects.
This type of Sight detects invisible creatures and is nearly 360 degrees.


\chapter{Output Files}

\LSMS\ can generate different output files to provide information about the progress of the calculation and about physical properties of the whole system and on an per atomic site basis.
The \texttt{k.out} file shows the convergence progress of a self-consistent calculation.. The main per atom information can be found in the \texttt{info\_evec\_out} file that is written at the end of a \LSMS\ job execution.

\section{\texttt{k.out}}
The \texttt{k.out} file tracks the convergence progress of a \LSMS\ calculation. It is updated at every iteration step and the last line contains the information about the most recently concluded step.
This file contains five columns with the following information:
\begin{enumerate}
\item iteration number
\item total energy of the system in Rydberg units.
\item Fermi energy
\item the magnetic moment of atomic site 1
\item RMS error (convergence parameter)
\end{enumerate}

\section{\texttt{info\_evec\_out}}
\subsection{Line 1}
The first line of \texttt{info\_evec\_out} has three columns and lists
\begin{enumerate}
\item total energy
\item band energy
\item Fermi energy
\end{enumerate}
\subsection{Per Atom Lines}
The rest of \texttt{info\_evec\_out} , beginning with the second line, contains one line for each site in the system.
Each line has 18 columns with the following information:
\begin{enumerate}
\item Atomic number
\item Site index (starting with 0 for the first site)
\item $x$ component of the site coordinate
\item $y$ component of the site coordinate
\item $z$ component of the site coordinate
\item electron charge associated with this site (note that the electron charge is counted here with a positive sign)
\item magnetic moment associated with this site in $\mu_B$
\item $x$ component of the magnetic moment direction
\item $y$ component of the magnetic moment direction
\item $z$ component of the magnetic moment direction
\item site dependent magnetic moment dirrection mixing parameter (Currently always $-1$)
\item $x$ component of the magnetic constraining field
\item $y$ component of the magnetic constraining field
\item $z$ component of the magnetic constraining field
\item shift of spin-up and spin-down potential
\item $x$ component of the new magnetic moment direction
\item $y$ component of the new magnetic moment direction
\item $z$ component of the new magnetic moment direction
\end{enumerate}

\section{Local Atom Data File}
if the input files specifies a filename for \texttt{localAtomData} this file is writen in a format similar to \texttt{info\_evec\_out}, but with somewhat different contents.
\subsection{Line 1}
The first line has four columns and lists
\begin{enumerate}
\item total energy
\item band energy
\item Fermi energy
\item electrostatic energy
\end{enumerate}
\subsection{Per Atom Lines}
The rest of the local atom data file, beginning with the second line, contains one line for each site in the system.
Each line has 16 columns with the following information:
\begin{enumerate}
\item Atomic number
\item Site index (starting with 0 for the first site)
\item $x$ component of the site coordinate
\item $y$ component of the site coordinate
\item $z$ component of the site coordinate
\item electron charge associated with this site (note that the electron charge is counted here with a positive sign)
\item magnetic moment associated with this site in $\mu_B$
\item $x$ component of the magnetic moment direction
\item $y$ component of the magnetic moment direction
\item $z$ component of the magnetic moment direction
\item $x$ component of the magnetic constraining field
\item $y$ component of the magnetic constraining field
\item $z$ component of the magnetic constraining field
\item shift of spin-up and spin-down potential
\item local site volume (in units of ${a_0}^3$)
\item local site energy
\end{enumerate}


\newcommand{\pKa}{\text{p}K_{\text{a}}}
\newcommand{\pKaX}[1]{\text{p}K_{\text{a}}^{\text{#1}}}

\section{
Constant-pH Simulations
\footnote[1]{
The features described in this section were implemented by Brian K. Radak
  (Argonne National Laboratory, Argonne, IL USA) with considerable technical
  support from James C. Phillips (University of Illinois, Urbana, IL USA) and
  Wei Jiang (Argonne National Laboratory).
The algorithm draws heavily from earlier work by Yunjie Chen and Beno{\^i}t
  Roux and later by Donghyuk Suh (University of Chicago, Chicago, IL USA), as
  well as time spent as a postdoctoral scholar at University of Chicago.
Testing and validation were also aided by Christophe Chipot
  (Universit\'{e} de Lorraine, Vand{\oe}uvre-l\`{e}s-Nancy cedex France and
  University of Illinois).
}
}
\label{section:constantph}

Constant-pH MD in NAMD is based on the scheme first proposed by
  Stern~\cite{Stern_JChemPhys_2007_v126_p164112} and later revised and extended
  by Chen and Roux~\cite{Chen_JChemTheoryComput_2015_v11_p3919}.
A detailed description of the modifications and improvements made in the NAMD
  implementation has been presented elsewhere by Radak,
  \textit{et al.}~\cite{Radak_JChemTheoryComput_2017_v13_p5933} and this is likely the
  best comprehensive description of the method, its uses, and its limitations/pitfalls.
Herein the goal is to provide a working understanding of how the implementation
  works and what kinds of data it produces.

\subsection{Overview and Theoretical Background}

Constant-pH MD is a simulation methodology specially formulated for the
  treatment of variable protonation states.
This is to be contrasted with conventional force-field based MD simulations,
  which generally treat protonation states by assuming they are fixed.
Consider, for example, a protein with two titratable residues which may both be
  either protonated or deprotonated (Figure~\ref{fig:cphStateCycle});
the system has four possible protonation states.
In the conventional route, the user must enumerate these possibilities,
  construct distinct topologies, and then simulate the cases individually.
The simulations for each state must then be connected by either asserting
  knowledge about the system (\textit{e.g.},~by assuming that only certain
  states are of biological importance) or by performing additional simulations
  to probe transitions between states directly (\textit{e.g.},~by performing
  free energy calculations).
In a constant-pH MD simulation, knowledge of the transformations is not
  assumed and is instead actively explored by interconverting between the
  various protonation states.
This is especially useful when the number of protonation states is extremely
  large and/or prior information on the importance of particular states is
  not available.

\begin{figure}[h]\center{
  \includegraphics[width=\textwidth]{figures/namdcph_cycle}
  \caption{\label{fig:cphStateCycle}
    The core difference between conventional and constant-pH MD can be
      illustrated by a simple enzyme $E$ with four protonation states
      describing the occupancy of two titratable residues, $R_1$ and $R_2$.
    A conventional MD simulation handles the states \emph{separately} (left
      panel).
    The relative importance of the states must be known beforehand or computed
      by other means.
    Conversely, a constant-pH MD simulation handles the states
      \emph{collectively} and actively simulates interconversion (right panel).
    Determining the relative importance of the states is a direct result of the
      simulation.
  }
}\end{figure}

In formal terms, conventional MD samples from a canonical ensemble, whereas
  constant-pH MD samples from a semi-grand canonical ensemble.
The new partition function,
\begin{equation}\label{eqn:semigrand}
  \Xi(\text{pH})
  =
  \sum_{\text{$\bm \lambda$} \in \mathcal{S}}
    Q_{\text{$\bm \lambda$}}
    10^{-n_{\text{$\bm \lambda$}} \text{pH}},
\end{equation}
  is essentially a weighted summation of canonical partition functions,
  $Q_{\text{$\bm \lambda$}}$, each of which are defined by an occupancy vector,
  ${\bm \lambda}$.
The elements of ${\bm \lambda}$ are either one or zero depending on whether a
  given protonation site is or is not occupied, respectively.
For a vector of length $m$, the set of all protonation states, $\mathcal{S}$,
  has at most $2^m$ members.
In order to sample from the corresponding semi-grand canonical distribution
  function, a simulation must explore \emph{both} the phase space defined by
  the canonical paritition functions and the state space defined by the
  different occupancy vectors.
The fraction of simulation time spent in each state is dictated by the weights
  in the summation and these depend on the pH and the number of protons,
  $n_{\text{$\bm \lambda$}}$, in the system (\textit{i.e.},~the sum of the
  elements in ${\bm \lambda}$).

Although a constant-pH MD system may contain any number of titratable protons,
  the base transformation is always the movement of \emph{one} proton from a
  molecule into a bath of non-interacting protons ``in solution.''
For a generic chemical species A, this corresponds to the usual deprotonation
  reaction definition, except with fixed pH:
\begin{equation*}
 \mathrm{
  HA
  \underset{\text{pH fixed}}{\stackrel{-H^{+}}{\rightleftharpoons}}
  A^{-}
 }.
\end{equation*}
In the language of statistical mechanics the species HA and A$^{-}$ refer to
  all terms in Eq.~\eqref{eqn:semigrand} which do and do not, respectively,
  contain the specific proton in question (\textit{i.e.},~the particular
  element of ${\bm \lambda}$ is one or zero).
By taking out a factor of $10^{-\text{pH}}$, this can be re-written as
\begin{equation*}
  \Xi(\text{pH})
  =
  \Xi_{\text{A}^{-}}(\text{pH})
  +
  \Xi_{\text{HA}}(\text{pH}) 10^{-\text{pH}}
\end{equation*}
  and then recast as a statistical mechanical analog of the
  Henderson-Hasselbalch equation by recognizing that
  $\Xi_{\text{A}^{-}}(\text{pH}) / \Xi_{\text{HA}}(\text{pH})$ is just the
  ratio of deprotonated / protonated fractions of species A.
The \emph{protonated} fraction is then
\begin{equation}\label{eqn:HH}
  P_{\text{HA}}(\text{pH})
  =
  \frac{1}{1 + 10^{\text{pH} - \pKa(\text{pH})}};
  \qquad
  \pKa(\text{pH})
  \equiv
  -\log{
    \frac{
      \Xi_{\text{A}^{-}}(\text{pH})
    }{
      \Xi_{\text{HA}}(\text{pH})
    }
  }.
\end{equation}
In practice, $P_{\text{HA}}(\text{pH})$ can be calculated from a simulation by
  simply counting the fraction of time spent in state HA (\textit{e.g.},~the
  fraction of time a specific element of ${\bm \lambda}$ is one).
Note also that $\pKa(\text{pH})$ is formally a pH dependent function
  unless the system only contains one proton (or type of proton).

In most experimental contexts, a different form of Eq.~\eqref{eqn:HH} is used
  which is often referred to as a ``generalized'' Hill equation.
This corresponds to a specific choice of pH dependence such that
\begin{equation*}
  \pKa(\text{pH})
  \approx
  \pKaX{(a)}
  +
  (1 - n)\left(\text{pH} - \pKaX{(a)}\right).
\end{equation*}
The constant $n$ is then known as the Hill coefficient and the so-called
  apparent $\pKa$, $\pKaX{(a)}$, generally corresponds to the inflection point
  of a plot of $P_{\text{HA}}(\text{pH})$.
Both quantities are usually determined by non-linear regression after
  $P_{\text{HA}}$ has been determined at different pH values.

\subsection{Implementation Details}

In NAMD, each canonical partition function is represented by a specific force
  field description embodied in a PSF -- in order to change the protonation
  state the underlying PSF must also be modified.
This is accomplished by a close coupling to \texttt{psfgen}.
The models that can be used with constant-pH MD are thus limited to only those
  which can be completely implemented within \texttt{psfgen}.
This also means that NAMD requires access to residue topology files (RTFs)
  during the course of a simulation.
These must be specified with the \texttt{psfgen} \texttt{topology} command.

For consistency between topological descriptions, NAMD uses ``dummy'' atoms to
  represent non-interacting protons.
These atoms have the same mass as protons but only interact with the system
  via a minimal number of force field bonded terms.
This formalism guarantees that:
  1) the number of atoms/coordinates during the simulation remains fixed
  and
  2) the thermodynamics of the model is unchanged.
The latter point is subtle and warrants comment.
As implemented in NAMD, constant-pH MD only captures the thermodynamics of
  the semi-grand canonical ensemble.
There is no active description of proton dissociation events.
However, this is more of a limitation of classical MD than a particular
  shortcoming of NAMD.
A useful analogy may be the use of Langevin dynamics as a thermostat as
  opposed to a phenomonological model for Brownian motion.

\begin{figure}[h]\center{
  \includegraphics[width=0.6\textwidth]{figures/namdcph_nemdmc_scheme}
  \caption{\label{fig:namdcph_nemdmc}
    The basic constant-pH MD scheme in NAMD is to alternate equilibrium
      sampling in a fixed protonation state followed by a nonequilibrium MD
      Monte Carlo move to sample other protonation states.
    The latter move can be accepted or rejected.
    If accepted, the simulation continues in the new protonation state.
    If the move is rejected, sampling continues as if the move were never
      attempted at all.
  }
}\end{figure}

The basic scheme in NAMD is to alternately sample the protonation state and
  then the configuration space within that state.
Protonation state sampling is accomplished by an alchemical coupling scheme
  that forcibly turns off interactions with the current protonation state and
  turns on interactions with a candidate protonation state.
This nonequilibrium ``switching'' is accomplished with the alchemy code
  (specifically the thermodynamic integration code branch) and necessarily has
  lower performance (by about 30\%) than regular MD due to the added
  electrostatic calculations in the reciprocal space (\textit{i.e.}, when
  using PME).
However, the configuration space sampling should still have normal performance.
The switching process exerts work on the system and thus drives the system out
  of equilibrium.
However, an appropriately designed Monte Carlo (MC) move using an accept/reject
  criterion can recover the correct semi-grand canonical equilibrium
  distribution in both the state and configuration
  spaces~\cite{Nilmeier_ProcNatlAcadSci_2011_v108_pE1009,
    Chen_JChemPhys_2015_v142_p024101}.
The resulting scheme is a hybrid nonequilibrium MD/MC (neMD/MC) algorithm.
The most important conceptual change from conventional MD is that, rather than
  being a continuous trajectory, the simulation now becomes a series of cycles
  composed of an MD and neMD/MC step.
This means that the length of the simulation is no longer simply determined by
  the number of steps (\texttt{numsteps}) but rather the number of cycles.
The length of a cycle is also determined by two parts -- the amount of time on
  equilibrium sampling and the amount of time executing the switch.

It may be profitable/necessary to vary the switch time depending on the type of
  protonation change that is being effected.
Indeed, this is a critical factor in the efficiency of the method.
That is, if the switch is too short, then moves are unlikely to be accepted and
  effort will be wasted when the move is rejected.
However, if the switch is too long, then an inordinate amount of effort will be
  spent sampling the state space and there will be fewer resources left for
  exploring the configuration space.
Some basic qualities of the system that affect sampling have been determined
  using nonequilibrium linear response
  theory~\cite{Radak_JChemPhys_2016_v145_p134109}.
In short, there are intrinsic limits based on:
  1) the extent that differing interactions between each state fluctuate
  (according to some variance, $\sigma_0^2$)
  and
  2) the ``molecular'' time scale, $\tau_{\text{m}}$, on which these
  fluctuations change.
These effects are roughly captured by the
  expression~\cite{Radak_JChemPhys_2016_v145_p134109,
    Radak_JChemTheoryComput_2017_v13_p5933}:
\begin{equation*}
  \tau_{\text{opt}}
  \le
  \frac{\sigma_0^2 \tau_{\text{m}}}{2.83475},
\end{equation*}
  where $\tau_{\text{opt}}$ is some optimal switching time, in the sense of
  maximizing the rate at which protonation states interconvert.
Overall, switching times on the order of tens of picoseconds tend to be optimal
  in that they balance the high cost of switching versus the high acceptance
  rate at longer switching times (in the infinite time limit the perturbation
  is adiabatic and exerts zero work).
For titratable groups exposed primarily to aqueous solvent, a switch on the
  order of 10-20~ps appears to give near optimal
  results~\cite{Radak_JChemPhys_2016_v145_p134109,
    Radak_JChemTheoryComput_2017_v13_p5933}.
An equivalent formulation of the above expression is that mean acceptance rates
  around 20-25\% are likely near optimal.

\fbox{
  \begin{minipage}[ht!]{15.3cm}
    \addtolength{\baselineskip}{0.225\baselineskip}
    \textbf{Important Limitations:}\\
    For various reasons concerning the implementation, constant-pH simulations
      are currently \emph{incompatible} with the following NAMD
      functionalities in all or most situations:
    \begin{itemize}
    \item Any system using GPUs/CUDA
    \item Generalized Born implict solvent (\texttt{GBIS})
    \item Alchemical free energy calculations, \textit{e.g.},~ligand binding
      (\texttt{alch})
    \item Drude polarizable force fields
    \item Hybrid quantum mechanical/molecular mechanical simulations
    \item Collective variables (\texttt{colvars})
    \item \texttt{extraBonds}
    \end{itemize}
    This list is neither exhaustive nor definitive.
    In many instances the problem may be overcome by modest additional
      developments. %(see Notes for Developers).
  \end{minipage}
}

\newpage
\begin{center}
  \includegraphics[width=0.9\textwidth]{figures/namdcph_flowchart}
\end{center}

\newpage
\subsection{New Commands and Keywords}

The constant-pH implementation is largely implemented in Tcl and can be found
  in \texttt{/lib/namdcph/namdcph.tcl}, where the base directory is the NAMD
  source home directory.
When that file has been loaded with a suitable \texttt{source} command, the
  following commands and keywords are available and appear to the user in a way
  similar to NAMD syntax.
The most significant change from normal NAMD usage is that there is generally
  no need to use the \texttt{run} command.
One should instead use the new \icommand{{\tt cphRun}} command;
this can only be used \emph{once} per script for now.
\textit{NB}, all commands and keywords are currently case sensitive!
\\[11pt]
\noindent
\icommand{{\tt cphRun}} $<$ Run constant-pH MD $>$
\\
\textbf{Arguments:} {\ARG{numsteps} \OARG{numcycles}}
\\
\textbf{Defaults:} {{\tt numcycles} = 1}
\\
\textbf{Description:}
Execute {\tt numcycles} cycles of constant-pH MD with the current settings.
Each cycle consists of 1) a neMD/MC move in both configuration and protonation
  space and 2) MD based sampling in configuration space.
By default, configuration space sampling simply consists of {\tt numsteps}
  dynamics, as in conventional MD.
The nature of the neMD/MC moves, however, is more elaborate and controlled by
  other keywords, \emph{many of which are required} (see below).
%\\[11pt]
%\noindent
%\icommand{{\tt testResidue}} $<$ Test a constant-pH residue definition $>$
%\\
%\textbf{Arguments:} {\ARG{resname list} \OARG{verbose}}
%\\
%\textbf{Defaults:} {{\tt verbose} = 0}
%\\
%\textbf{Description:}
%THIS IS AN ADVANCED OPTION, USE WITH CARE!
%This is meant to be a convenience command for verifying that RTF, PRM, and
%  configuration file definitions are complete and consistent.
%The \texttt{resname list} argument should be a Tcl list containing the names
%  of one or more residue definitions described in the configuration file.
%Accompanying \texttt{parameter} and \texttt{topology} information is also
%  required, as in normal simulations.
%The command will iterate through all possible protonation state transitions and
%  check that the energy of each state does not depend on the pathway by which
%  it is reached.
%Setting {\tt verbose} $\ne$ 0 will also show decomposition of energy terms
%  (\textit{e.g.}, ELEC and VDW).

\subsubsection{Required Keywords}
\begin{itemize}
\item \NAMDCONF{pH}
{pH value that the system is in contact with}
{decimal (usually between 0 and 14)}
{
The \KEY{pH} is effectively a chemical potential applied to protons
  \emph{only}.
This value affects the details of neMD/MC moves but otherwise has no effect
  on the system dynamics.
}

\item \NAMDCONF{cphConfigFile}
{File defining titratable residues}
{filename}
{
The \KEY{cphConfigFile} contains definitions for the available titratable
  residues.
This is essentially meta information regarding the RTF contents, but also
  includes experimental references and additional force field parameterization.
}

\item \NAMDCONF{cphNumstepsPerSwitch}
{Number of steps during nonequilibrium switching}
{
  \OARG{integer \OARG{\ARG{move label} \ARG{integer}} \ldots}
}
{
Each move must have an associated number of steps per switch.
If an odd number number of arguments is specified, then the first such argument
  is assumed to be a default number for all such moves.
After this (or if an even number of arguments is specified) all remaining
  arguments are assumed to be specific assignments for a given move label
  of the form \ARG{segid}:\ARG{resid}:\ARG{resname}/\ARG{segid}:\ARG{resid}:\ARG{resname}/\ldots.
}
\end{itemize}

\subsubsection{Commonly Used Options}
\begin{itemize}
\item \NAMDCONF{cphSetResidueState}
{Set the initial state of one or more titratable residues.}
{
\ARG{segid}:\ARG{resid}:\ARG{resname} \ARG{state} \OARG{\ldots}
}
{
Initial residue states can be assigned in three ways (in descending order of
  precedence): 1) via this command, 2) from a \KEY{cphRestartFile}, and 3)
  randomly from the assigned \KEY{pH} and the current inherent pKa of each
  residue.
}

\item \NAMDCONF{cphSetResiduepKai}
{Set the inherent pKa of one or more titratable residues.}
{
\ARG{segid}:\ARG{resid}:\ARG{resname} \ARG{pKai} \OARG{\ldots}
}
{
The two step inherent pKa algorithm implemented here permits on-the-fly update
  of an estimate for the pKa(s) of each residue.
These can either be guessed at the outset (the default is to use the reference
  pKa) or updated as the simulation progresses.
A more accurate estimate of the inherent pKa increases the statistical
  efficiency of the method, but the long time result is formally unbiased
  regardless of the value.
If an extremely large or extremely small value is assigned, then the residue
  will be assigned the most probable protonation state at the given pH and
  likely remain fixed in that state.
}

\item \NAMDCONF{cphExcludeResidue}
{Exclude one or more residues from being titratable}
{
\ARG{segid}:\ARG{resid}:\ARG{resname} \OARG{\ldots}
}
{
By default, any residue that matches a titratable residue type will be allowed
  to change protonation state.
This command permits specific residues to be excluded from consideration in a
  manner that is similar to assigning an extreme inherent pKa (see
  \texttt{cphSetResiduepKai}).
The main differences are that 1) the protonation state will not be modified and
  remain as it is in the original PSF and 2) the protons in the residue will
  \emph{not} be tracked in the \texttt{cphlog} file.
This command is not always recommended, but is currently necessary for handling
  disulfide linkages.
}

\item \NAMDCONF{cphRestartFile}
{Restart file for constant-pH}
{filename}
{
Constant pH requires additional checkpoint information regarding the state of
  the titratable residues and the nature of the neMD/MC moves.
This (optional) information is read from the file specified here.
After/during a simulation, this information is written to
  \KEY{[outputname]}.cphrst.
}

\item \NAMDCONFWDEF{cphRestartFreq}
{Frequency at which constant-pH checkpoint files are written}
{Non-negative integer}
{0}
{
Checkpoint information is written to \KEY{[outputname]}.cphrst every
  \KEY{cphRestartFreq} cycles (\emph{not} MD steps).
A checkpoint file is \emph{always} written at the end of the last cycle.
}

\item \NAMDCONFWDEF{cphOutFile}
{Log file for constant-pH}
{filename}
{\KEY{[outputname]}.cphlog}
{Titratable residue state information is logged here after every cycle.}

\item \NAMDCONF{cphProposalWeight}
{MC move label and weight specifications}
{
\ARG{move label} \ARG{weight}
  \OARG{\OARG{\ARG{move label} \ARG{weight}} \ldots}
}
{
During each cycle, MC moves are selected from the move set and then
  accepted/rejected according to a Metropolis criterion based on the combined
  inherent pKa information and pH.
The move weight affects the probability that such a move is selected.
Note that \emph{this does not affect the probability that any given proposal
  is accepted}, it merely increases the number of attempts at the given
  proposal.
This may be useful in a system where one desires specific attention on a given
  process, such as proton transfer or the exchange of a given residue, but one
  does not want to assume that all other residue protonation states are
  nominally fixed.
By default all moves are assigned equal weights of 1.0.
During the simulation these are automatically normalized to a discrete
  probability mass function.
}

\item \NAMDCONFWDEF{cphMaxProposalAttempts}
{Maximum number of switch proposal attempts per cycle}
{integer}
{0}
{
During each cycle, MC moves are selected from the move set and then
  accepted/rejected according to a Metropolis criterion based on the combined
  inherent pKa information and pH.
This process stops when either a switch move is accepted or a maximum limit is
  reached.
Any value less than one defaults to the number of titratable residues in the
  system.
}

\item \NAMDCONFWDEF{cphNumMinSteps}
{Number of steps of minimization before dynamics}
{integer}
{0}
{
This is a replacement for the normal minimize command, which is not compatible
  with constant-pH due to PSF modifications during initialization.
Setting this option to a modest number (100--200, say) might be necessary when
  randomizing protonation states based on pH, since in that case it cannot be
  assumed that the starting structure is representative of the initial
  protonation state.
}

\end{itemize}

\subsubsection{Specialized Options}
\begin{itemize}
\item \NAMDCONFWDEF{cphForceConstant}
{force constant for alchemical switches (in kcal/mol-\AA$^2$)}
{Non-negative decimal}
{100.0}
{
During ``dual-topology'' alchemical switches, a harmonic bond is formed between
  analogous atoms in each alchemical region.
This rigorously leaves all static thermodynamic quantities intact and is
  generally expected to improve the stability of dynamic quantities.
}

\item \NAMDCONFWDEF{cphMDBasename}
{basename of intermediate files for equilibrium MD}
{string}
{namdcph.md}
{
PSF/coordinate modifications are currently done via the file system and utilize
  intermediate files.
It may be advantageous to direct this I/O to a fast temporary directory.
}

\item \NAMDCONFWDEF{cphSWBasename}
{basename of intermediate files for nonequilibrium (switch) MD}
{string}
{namdcph.sw}
{
PSF/coordinate modifications are currently done via the file system and utilize
  intermediate files.
It may be advantageous to direct this I/O to a fast temporary directory.
}
\end{itemize}

\fbox{
  \begin{minipage}[ht!]{15.3cm}
    \addtolength{\baselineskip}{0.225\baselineskip}
    \textbf{Undocumented Features:}\\
    The constant-pH code is actively under development, although future work
      will almost exclusively be in adding new features and capabilities as
      well as improving performance.
    Because the code is fairly lightweight and available in \texttt{Tcl}, the
      intrepid user may discover ``easter egg'' features which are not listed
      in the documentation.
    \textbf{USE UNDOCUMENTED FEATURES AT YOUR OWN RISK.}
    Such undocumented features may work (and even be advisable) for specific
      problems, but have not undergone as rigorous of testing and may be prone
      to unintended consequences.
  \end{minipage}
}

\subsection{Minimal Examples}

Constant-pH simulations can be carried out with largely the same options as
  conventional MD simulations (with some exceptions, see previous sections).
The follwing examples assume that: 1) PSF and PDB files for the
  system of interest have already been constructed and 2) appropriate
  simulation keywords have already been chosen (\textit{e.g.},~for PME,
  Langevin dynamics, \textit{etc.}).
\begin{verbatim}
# End conventional settings...
source .../namd/lib/namdcph/namdcph.tcl
# Constant-pH MD requires additional force field files _during_ the simulation.
# In general, all RTFs used to construct the system need to be included with
# the ``topology'' command (just as in psfgen). Additional constant-pH specific
# RTF and PRM files are also necessary, as well as an accompanying
# configuration file in JSON format.
#
cphConfigFile <path to JSON config file>
topology <path to RTF>
topology <path to another RTF>
pH 7.0
# The following defaults all nonequilibrium switches to 5000 steps and then
# increases the time for residue 5 of segid PROA to 7500 steps -- multiple
# residues can be specified
#
cphNumStepsPerSwitch 5000 PROA:5:ASP 7500
# Run 100 minimization cycles before starting dynamics.
cphNumMinSteps 100
# Run 2500 steps of MD between attempted protonation state changes. Run 10
# cycles of MD and neMD/MC. The _upper_ bound of the simulation is thus:
#
# 10*(2500 + 7500) = 100000 steps
#
# but the actual simulation may be shorter in length.
#
cphRun 2500 10
\end{verbatim}

\newpage
\noindent
\textbf{Restarting a simulation}

\noindent
The following assumes that a simulation has already been run (as in the example
  above).
For clarity we shall assume that \texttt{outputname} was set to "foo" such that
  restart files have been written to foo.coor and foo.vel (normal output) as
  well as foo.psf, foo.pdb, and foo.cphrst (constant-pH specific output).

\begin{verbatim}
# End conventional settings...
source .../namd/lib/namdcph/namdcph.tcl
# Constant-pH MD requires additional force field files _during_ the simulation.
# In general, all RTFs used to construct the system need to be included with
# the ``topology'' command (just as in psfgen). Additional constant-pH specific
# RTF and PRM files are also necessary, as well as an accompanying
# configuration file in JSON format.
#
cphConfigFile <path to JSON config file>
topology <path to RTF>
topology <path to another RTF>
pH 7.0

structure foo.psf
coordinates foo.pdb
binCoordinates foo.coor
binVelocities foo.vel
cphRestartFile foo.cphrst
# NB: switch times and inherent pKa values are read here and no longer need to
# be specified as during initialization

cphRun 2500 10
\end{verbatim}

%% COMING SOON
%\newpage
%\subsection{Notes for Developers}
%
%This section of the user's guide is likely not necessary reading for those
%  who simply want to perform constant-pH simulations.
%Rather, it is a companion guide for the code and comments so that furthur
%  developments can be made as a community.


\subsection{Full List of Keywords}
\addtocounter{table}{1} \index{Keywords!full list of}
\addcontentsline{lot}{table}{\protect\numberline{\thetable}{\ignorespaces Full list of Keywords used in MOPAC}}
\begin{description}
\item[\comp{\&}] Turn next line into keywords
\item[\comp{+}] Add another line of keywords
\item[\comp{0SCF}] Read in data, then stop
\item[\comp{1ELECTRON}] Print final one-electron matrix
\item[\comp{1SCF}] Do one scf and then stop
\item[\comp{AIDER}] Read in ab-initio derivatives
\item[\comp{AIGIN}] Geometry must be in gaussian format
\item[\comp{AIGOUT}] In arc file, include ab-initio geometry
\item[\comp{ALLBONDS}] Print final bond-order matrix, including bonds to hydrogen
\item[\comp{ALLVEC}] Print all vectors (keywords vectors also needed)
\item[\comp{ALT\_a={\em A}}] In pdb files with alternative atoms, select atoms
{\em A}
\item[\comp{ALT\_r={\em A}}] In pdb files with alternative residues, select residues
{\em A}
\item[\comp{ANALYT}] Use analytical derivatives of energy wrt geometry
\item[\comp{AUTOSYM}] Symmetry to be imposed automatically
\item[\comp{AM1}] Use the AM1 hamiltonian
\item[\comp{BAR=$n.n$}] reduce bar length by a maximum of $n.n$
\item[\comp{BCC}] Solid is body-centered cubic (used by BZ)
\item[\comp{BFGS}] Optimize geometries using bfgs procedure
\item[\comp{BIGSCF}] If restart, do a full scf to re-form starting density matrix
\item[\comp{BIGCYCLES}] Do  a maximum of $n$ big steps
\item[\comp{BIRADICAL}] System has two unpaired electrons
\item[\comp{BONDS}] Print final bond-order matrix
\item[\comp{C.I.}] A multi-electron configuration interaction specified
\item[\comp{CHARGE=$n$}] Charge on system = $n$ (e.g.\ NH4 $\Rightarrow$ charge=1)
\item[\comp{CIS}] C.I.\ uses 1 electron excitations only
\item[\comp{CISD}] C.I.\ uses 1 and electron excitations
\item[\comp{CISDT}] C.I.\ uses 1, 2 and 3 electron excitations
\item[\comp{COMPFG}] Print heat of formation calculated in COMPFG
\item[\comp{CONNOLLY}] Use Connolly surface
\item[\comp{CROSS}] Determine intersystem crossing geometry
\item[\comp{CUTOF1=$n.nn$}] Cutoff for polarization functions is $n.nn$ {\aa}ngstroms
\item[\comp{CUTOF2=$n.nn$}] Cutoff for nddo approximation is $n.nn$ {\aa}ngstroms
\item[\comp{CUTOFP=$n.nn$}] Madelung distance cutoff is $n.nn$ {\aa}ngstroms
\item[\comp{CUTOFS=$n.nn$}] Overlap cutoff distance is $n.nn$ {\aa}ngstroms
\item[\comp{CVB}] User defined chemical bonds (used in making Lewis structures)
\item[\comp{CYCLES=$n$}] Do a maximum of $n$ steps
\item[\comp{DAMP=$n.nn$}] Use damping factor $n.nn$ in SCF calculation
\item[\comp{DCART}] Print part of working in DCART
\item[\comp{DDMAX}] See EF code
\item[\comp{DDMIN}] Minimum trust radius in a EF/TS calculation
\item[\comp{DEBUG}] Debug option turned on
\item[\comp{DENOUT}] Density matrix output (channel 10)
\item[\comp{DENOUT=$n$}] Density matrix output every $n$ seconds
\item[\comp{DENSITY}] Print final density matrix
\item[\comp{DEP}] Generate Fortran code for parameters for new elements
\item[\comp{DERIV}] Print part of working in DERIV
\item[\comp{DFORCE}] Force calculation specified, also print force matrix.
\item[\comp{DFP}] Use Davidson-Fletcher-Powell method to optimize geometries
\item[\comp{DIAGG2}] Print part of working in DIAGG2
\item[\comp{DIPOLE}] Fit the ESP to the calculated dipole
\item[\comp{DIPX}] X component of dipole to be fitted
\item[\comp{DIPY}] Y component of dipole to be fitted
\item[\comp{DIPZ}] Z component of dipole to be fitted
\item[\comp{DISEX}] Distance for interactions in fine grid in COSMO
\item[\comp{DMAX}] Maximum stepsize in eigenvector following
\item[\comp{DMIN}] See EF code
\item[\comp{DOUBLET}] Doublet state required
\item[\comp{DRC}] Dynamic reaction coordinate calculation
\item[\comp{DUMP=$n$}] Write restart files every $n$ seconds
\item[\comp{ECHO}] Data are echoed back before calculation starts
\item[\comp{EF}] Use ef routine for minimum search
\item[\comp{EIGEN}] Generate canonical eigenvectors instead of LMOs
\item[\comp{EIGS}] Print all eigenvalues in ITER
\item[\comp{ENPART}] Partition energy into components
\item[\comp{EPS}] Dielectric constant in COSMO calculation
\item[\comp{ESP}] Electrostatic potential calculation
\item[\comp{ESPRST}] Restart of electrostatic potential
\item[\comp{ESR}] Calculate RHF spin density
\item[\comp{EXCITED}] Optimize first excited singlet state
\item[\comp{EXTERNAL}] Read parameters off disk
\item[\comp{FIELD}] An external electric field is to be used
\item[\comp{FILL=$n$}] In RHF open and closed shell, force M.O.\ $n$  to be filled
\item[\comp{FLEPO}] Print details of geometry optimization
\item[\comp{FMAT}] Print details of working in FMAT
\item[\comp{FOCK}] Print last Fock matrix
\item[\comp{FORCE}] Force calculation specified
\item[\comp{GEO-OK}] override interatomic distance check
\item[\comp{GEOCHK}] Print part of working in GEOCHK
\item[\comp{GNMIN}] Minimize gradients in EF
\item[\comp{GNORM=$n.n$}] Exit when gradient norm drops below $n.n$
\item[\comp{GRADIENTS}] Print all gradients
\item[\comp{GRAPH}] Generate file for graphics
\item[\comp{GREENF}] Correct I.P.s using Green's function technique
\item[\comp{H2O}] Use water as the solvent in MST calculations
\item[\comp{HCORE}] Print details of working in HCORE
\item[\comp{HESS=$n$}] options for calculating hessian matrices in EF
\item[\comp{H-PRIO}] Heat of formation takes priority in DRC
\item[\comp{HYBRID}] Print details of working in HYBRID
\item[\comp{HYPERFINE}] Hyperfine coupling constants to be calculated
\item[\comp{IMEM=$nn$}] Integer memory increased by $nn$
\item[\comp{INT}] Make all coordinates internal coordinates
\item[\comp{IRC}] Intrinsic reaction coordinate calculation
\item[\comp{ISOTOPE}] Force matrix written to disk (channel 9 )
\item[\comp{ITER}] Print details of working in ITER
\item[\comp{ITRY=$n$}] Set limit of number of SCF iterations to $n$
\item[\comp{IUPD}] Mode of Hessian update in eigenvector following
\item[\comp{K=($n$,$n$)}] Brillouin zone structure to be calculated
\item[\comp{KINETIC}] Excess kinetic energy added to DRC calculation
\item[\comp{LEWIS}] Print details of working in LEWIS
\item[\comp{LINMIN}] Print details of line minimization
\item[\comp{LARGE}] Print expanded output
\item[\comp{LET}] Override certain safety checks
\item[\comp{LOCALIZE}] Print localized orbitals
\item[\comp{MAX}] In GRID, use maximum grid size (23*23)
\item[\comp{MECI}] Print details of MECI calculation
\item[\comp{MEP=1}] Print Orozco-Luque electrostatic potentials for cross-section
\item[\comp{MEP=2}] Print Orozco-Luque electrostatic potentials for Connolly surface
\item[\comp{MERS=($n$)}] Keyword for BZ
\item[\comp{MICROS}] Use specific microstates in the C.I.
\item[\comp{MINDO/3}] use the MINDO/3 hamiltonian
\item[\comp{MINMEP}] Minimize MEP minima in the plane defined
\item[\comp{MMOK}] Use molecular mechanics correction to CONH bonds
\item[\comp{MNDO}] Use the MNDO hamiltonian
\item[\comp{MNDO-d}] Use the MNDO-d hamiltonian
\item[\comp{MODE=$n$}] In EF, follow Hessian mode no.\ $n$
\item[\comp{MOLDAT}] Print details of working in MOLDAT
\item[\comp{MS=$n$}] In MECI, magnetic component of spin
\item[\comp{MULLIK}] Print the Mulliken population analysis
\item[\comp{NEWGEO}] Make backbone atoms Cartesian and side-chain internal
\item[\comp{NLLSQ}] Minimize gradients using NLLSQ
\item[\comp{NLMO=$nnn$}] define average size of LMOs as $nnn$
\item[\comp{NOANCI}] Do not use analytical C.I. derivatives
\item[\comp{NOINT}] Do not print internal coordinates
\item[\comp{NOLOG}] Suppress log file trail, where possible
\item[\comp{NOMM}] Do not use molecular mechanics correction to CONH bonds
\item[\comp{NONET}] NONET state required
\item[\comp{NONR}] Do not use Newton-Raphson method in EF
\item[\comp{NOREOR}] In symmetry work, use supplied orientation
\item[\comp{NOSYM}] Point-group symmetry set to C1
\item[\comp{NOTHIEL}] Do not use Thiel's FSTMIN technique
\item[\comp{NSPA}] Sets number of geometric segments in COSMO
\item[\comp{NSURF=$n$}] Number of surfaces in an ESP calculation
\item[\comp{NOXYZ}] Do not print Cartesian coordinates
\item[\comp{NSURF}] Number of layers used in electrostatic potential
\item[\comp{OCTET}] Octet state required
\item[\comp{OLDENS}] Read initial density matrix off disk
\item[\comp{OLDFPC}] Use the old fundamental physical constants
\item[\comp{OLDGEO}] Previous geometry to be used
\item[\comp{OMIN}] In TS, minimum allowed overlap of eigenvectors
\item[\comp{OPEN}] Open-shell RHF calculation requested
\item[\comp{OPTBACK}] Set optimization flags for backbone atoms in a protein
\item[\comp{OPTRES}] Set optimization flags for side-chain atoms in a protein
\item[\comp{ORT}] Use Reynolds-Richards molecular electrostatic pot.
\item[\comp{P=$n.nn$}] An external pressure of $n.nn$ NM$^{-2}$ or N is applied to a solid or polymer.
\item[\comp{PARASOK}] In AM1 calculations some MNDO parameters are to be used
\item[\comp{PDB}] Geometry is in protein data bank format
\item[\comp{PDB($text$)}] User defined chemical symbols in protein data base
\item[\comp{PDBOUT}] Output geometry in pdb format
\item[\comp{PECI}] C.I. involves paired excitations only
\item[\comp{PI}] Resolve density matrix into $\sigma$ and $\pi$ bonds
\item[\comp{PINOUT}] Print localized M.O.s whenever PINOUT is called
\item[\comp{PL}] Monitor convergence of density matrix in ITER
\item[\comp{PM3}] Use the MNDO-PM3 hamiltonian
\item[\comp{PMEP}] Complete semiempirical MEP calculation
\item[\comp{PMEPR}] Complete semiempirical MEP in a plane to be defined
\item[\comp{POINT=$n$}] Number of points in reaction path
\item[\comp{POINT1=$n$}] Number of points in first direction in grid calculation
\item[\comp{POINT2=$n$}] Number of points in second direction in grid calculation
\item[\comp{POLAR}] Calculate first, second and third order polarizabilities
\item[\comp{POPS}] Print the self consistent field atomic orbital populations
\item[\comp{POTWRT}] In ESP, write out electrostatic potential to unit 21
\item[\comp{POWSQ}] Print details of working in POWSQ
\item[\comp{PRECISE}] Criteria to be increased by 100 times
\item[\comp{PRTMEP}] MEP contour data output to \comp{$<$filename$>$.mep}
\item[\comp{PULAY}] Use Pulay's converger to obtain a SCF
\item[\comp{QPMEP}] Charges derived from Wang-Ford type AM1 MEP
\item[\comp{QUARTET}] Quartet state required
\item[\comp{QUINTET}] Quintet state required
\item[\comp{RAPID}] In SCF, use atoms being optimized only
\item[\comp{RECALC=$n$}] In EF, recalculate Hessian every $n$ steps
\item[\comp{RE-LOCAL}] Re-localize localized molecular orbitals
\item[\comp{RELSCF=$n$}] Default SCF criterion multiplied by $n$
\item[\comp{RELTHR=$n$}] Default threshold for LMOs multiplied by $n$
\item[\comp{REORTH}] Reorthogonalize LMOs
\item[\comp{RESEQ}] Resequence the atoms in a protein
\item[\comp{RESIDUES}] Label all atoms in a protein
\item[\comp{RESTART}] Calculation restarted
\item[\comp{RMAX}] In TS, maximum allowed ratio for energy change
\item[\comp{RMEM=$nn$}] Real memory increased by $nn$
\item[\comp{RMIN}] In TS, minimum allowed ratio for energy change
\item[\comp{ROOT=$n$}] Root $n$ to be optimized in a C.I. calculation
\item[\comp{RSCAL}] In EF, scale p-RFO to trust radius
\item[\comp{RSOLV}] Effective radius of solvent in COSMO
\item[\comp{SADDLE}] Optimize transition state
\item[\comp{SAFE}] Allow memory intensive scf convergers
\item[\comp{SCALE}] Scaling factor for van der Waals distance in ESP
\item[\comp{SCFCRT=$n$}] Default SCF criterion replaced by the value supplied
\item[\comp{SCINCR}] Increment between layers in ESP
\item[\comp{SEPTET}] Septet state required
\item[\comp{SETUP}] Extra keywords to be read of setup file
\item[\comp{SEXTET}] Sextet state required
\item[\comp{SHIFT=$n$}] a damping factor of $n$ defined to start SCF
\item[\comp{SIGMA}] Minimize gradients using SIGMA
\item[\comp{SINGLET}] Singlet state required
\item[\comp{SIZES}] Print the sizes of all arrays created or destroyed
\item[\comp{SLOG=$n.nn$}] In BFGS optimization, use fixed step of length $n.nn$
\item[\comp{SLOPE}] Multiplier used to scale MNDO charges
\item[\comp{SNAP}]Increase precision of symmetry angles
\item[\comp{SPIN}] Print final UHF spin matrix
\item[\comp{STEP}] Step size in path
\item[\comp{STEP1=$n$}] Step size $n$ for first coordinate in grid calculation
\item[\comp{STEP2=$n$}] Step size $n$ for second coordinate in grid calculation
\item[\comp{STO-3G}] Deorthogonalize orbitals in STO-3G basis
\item[\comp{SUPER}] Print superdelocalizabilities
\item[\comp{SYMAVG}] Average symmetry equivalent ESP charges
\item[\comp{SYMMETRY}] Impose symmetry conditions
\item[\comp{T=$n$}] A time of $n$ seconds requested
\item[\comp{THERMO}] Perform a thermodynamics calculation
\item[\comp{THRESH=$n.nn$}] Set the cutoff for LMO coefficients to $n.nn$
\item[\comp{TIDY}] Print details of working in TIDY
\item[\comp{TIMES}] Print times of various stages
\item[\comp{TOM}] Use the Miertus-Scrocco-Tomasi solvation model
\item[\comp{T-PRIO}] Time takes priority in DRC
\item[\comp{TRANS}] The system is a transition state (used in thermodynamics calculation)
\item[\comp{TRIPLET}] Triplet state required
\item[\comp{TS}] Using EF routine for TS search
\item[\comp{UHF}] Unrestricted Hartree-Fock calculation
\item[\comp{UNSAFE}] Use reduced memory (may affect SCF convergence)
\item[\comp{VDW}] Van der Waals radius for atoms in COSMO defined by user
\item[\comp{VECTORS}] Print final eigenvectors
\item[\comp{VELOCITY}] Supply the initial velocity vector in a DRC calculation
\item[\comp{WILLIAMS}] Use Williams surface
\item[\comp{XENO}] Specify fragments which are attached to residues
\item[\comp{X-PRIO}] Geometry changes take priority in DRC
\item[\comp{XYZ}] Do all geometric operations in Cartesian coordinates
\end{description}