    \filetitle{get}{Query VAR object properties}{VAR/get}

	\paragraph{Syntax}\label{syntax}

\begin{verbatim}
Ans = get(V,Query)
[Ans,Ans,...] = get(V,Query,Query,...)
\end{verbatim}

\paragraph{Input arguments}\label{input-arguments}

\begin{itemize}
\item
  \texttt{V} {[} VAR {]} - VAR object.
\item
  \texttt{Query} {[} char {]} - Query to the VAR object.
\end{itemize}

\paragraph{Output arguments}\label{output-arguments}

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  \texttt{Ans} {[} \ldots{} {]} - Answer to the query.
\end{itemize}

\paragraph{Valid queries to VAR
objects}\label{valid-queries-to-var-objects}

\subparagraph{VAR variables}\label{var-variables}

\begin{itemize}
\item
  \texttt{'yList'} -- Returns {[} cellstr {]} the names of endogenous
  variables.
\item
  \texttt{'eList'} -- Returns {[} cellstr {]} the names of residuals or
  shocks.
\item
  \texttt{'iList'} -- Returns {[} cellstr {]} the names of conditioning
  (forecast) instruments.
\item
  \texttt{'ny'} -- Returns {[} numeric {]} the number of variables.
\item
  \texttt{'ne'} -- Returns {[} numeric {]} the number of residuals or
  shocks.
\item
  \texttt{'ni'} -- Returns {[} numeric {]} the number of conditioning
  (forecast) instruments.
\end{itemize}

\subparagraph{System matrices}\label{system-matrices}

\begin{itemize}
\item
  \texttt{'A\#'}, \texttt{'A*'}, \texttt{'A\$'} -- Returns {[} numeric
  {]} the transition matrix in one of the three possible forms; see
  Description.
\item
  \texttt{'K'}, \texttt{'const'} -- Returns {[} numeric {]} the constant
  vector or matrix (the latter for panel VARs).
\item
  \texttt{'J'} -- Returns {[} numeric {]} the coefficient matrix in
  front of exogenous inputs.
\item
  \texttt{'Omg'}, \texttt{'Omega'} -- Returns {[} numeric {]} the
  covariance matrix of one-step-ahead forecast errors, i.e.~reduced-form
  residuals. Note that this query returns the same matrix also for
  structural VAR (SVAR) objects.
\item
  \texttt{'Sgm'}, \texttt{'Sigma'} -- Returns {[} numeric {]} the
  covariance matrix of the VAR parameter estimates; the matrix is
  non-empty only if the option \texttt{'covParam='} has been set to
  \texttt{true} at estimation time.
\item
  \texttt{'G'} -- Returns {[} numeric {]} the coefficient matrix on
  cointegration terms.
\end{itemize}

\subparagraph{Information criteria}\label{information-criteria}

\begin{itemize}
\item
  \texttt{'AIC'} -- Returns {[} numeric {]} Akaike information
  criterion.
\item
  \texttt{'SBC'} -- Returns {[} numeric {]} Schwarz bayesian criterion.
\end{itemize}

\subparagraph{Other queries}\label{other-queries}

\begin{itemize}
\item
  \texttt{'cumLong'} -- Returns {[} numeric {]} the matrix of long-run
  cumulative responses.
\item
  \texttt{'nFree'} -- Returns {[} numeric {]} the number of freely
  estimated (hyper-) parameters.
\item
  \texttt{'order'}, \texttt{'p'} -- Returns {[} numeric {]} the order of
  the VAR object.
\end{itemize}

\paragraph{Description}\label{description}

\subparagraph{Transition matrix}\label{transition-matrix}

There are three queries to request the VAR transition matrix:
\texttt{'A\#'}, \texttt{'A*'}, \texttt{'A\$'}. They differ in how the
higher-order transition matrices are arranged.

\begin{itemize}
\item
  \texttt{'A\#'} returns \texttt{cat(3,I,-A1,...,-Ap)} where \texttt{I}
  is an identity matrix, and \texttt{A1}, \ldots{} \texttt{Ap} are the
  coefficient matrices on individual lags.
\item
  \texttt{'A\#'} returns \texttt{cat(3,A1,...,Ap)} where \texttt{A1},
  \ldots{} \texttt{Ap} are the coefficient matrices on individual lags.
\item
  \texttt{'A\$'} returns \texttt{{[}A1,...,Ap{]}} where \texttt{A1},
  \ldots{} \texttt{Ap} are the coefficient matrices on individual lags.
\end{itemize}

\paragraph{Example}\label{example}


\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage{amsmath}
\usepackage{amsfonts}

\title{Marlin Diagram}
\date{July 2020}

\usepackage[x11names]{xcolor}
\usepackage[b4paper,margin=1.2in]{geometry}
\usepackage{tikz}
\usepackage{afterpage}

\newenvironment{rcases}
  {\left.\begin{aligned}}
  {\end{aligned}\right\rbrace}

\begin{document}

\newcommand{\cm}[1]{\ensuremath{\mathsf{cm}_{#1}}}
\newcommand{\vcm}[1]{\ensuremath{\mathsf{vcm}_{#1}}}
\newcommand{\s}{\ensuremath{\hat{s}}}
\newcommand{\w}{\ensuremath{\hat{w}}}
\newcommand{\x}{\ensuremath{\hat{x}}}
\newcommand{\z}{\ensuremath{\hat{z}}}
\newcommand{\za}{\ensuremath{\hat{z}_A}}
\newcommand{\zb}{\ensuremath{\hat{z}_B}}
\newcommand{\zc}{\ensuremath{\hat{z}_C
}}
\newcommand{\zm}{\ensuremath{\hat{z}_M}}

\newcommand{\val}{\ensuremath{\mathsf{val}}}
\newcommand{\row}{\ensuremath{\mathsf{row}}}
\newcommand{\col}{\ensuremath{\mathsf{col}}}
\newcommand{\rowcol}{\ensuremath{\mathsf{rowcol}}}

\newcommand{\hval}{\ensuremath{\hat{\val}}}
\newcommand{\hrow}{\ensuremath{\hat{\row}}}
\newcommand{\hcol}{\ensuremath{\hat{\col}}}
\newcommand{\hrowcol}{\ensuremath{\hat{\rowcol}}}

\newcommand{\bb}{\ensuremath{\mathsf{b}}}
\newcommand{\denom}{\ensuremath{\mathsf{denom}}}

\newcommand{\sumcheckinner}{\mathsf{sumcheck}
_{\mathsf{inner}}}
\newcommand{\sumcheckouter}{\mathsf{sumcheck}_{\mathsf{outer}}}

\newcommand{\Prover}{\mathcal{P}}
\newcommand{\Verifier}{\mathcal{V}}

\newcommand{\F}{\mathbb{F}}

\newcommand{\DomainA}{H}
\newcommand{\DomainB}{K}

\newcommand{\vPoly}[1]{\ensuremath{v_{#1}}}

This diagram (on the following page) shows the interaction of the Marlin prover and verifier. It is similar to the diagrams in the paper (Figure 5 in Section 5 and Figure 7 in Appendix E, in the latest ePrint version), but with two changes: it shows not just the AHP but also the use of the polynomial commitments (the cryptography layer); and it aims to be fully up-to-date with the recent optimizations to the codebase. This diagram, together with the diagrams in the paper, can act as a ``bridge" between the codebase and the theory that the paper describes.

\section{Glossary of notation}
\begin{table*}[htbp]
  \centering
  \begin{tabular}{c|c}
    $\F$ & the finite field over which the R1CS instance is defined \\
     \hline
    $x$ & public input \\
     \hline
    $w$ & secret witness \\
     \hline
    $\DomainA$ & variable domain \\
     \hline
    $\DomainB$ & matrix domain \\
     \hline
    $X$ & domain sized for input (not including witness) \\
     \hline
    $v_D(X)$ & vanishing polynomial over domain $D$ \\
     \hline
    $A, B, C$ & R1CS instance matrices \\
    \hline
    $A^*, B^*, C^*$ &
    \begin{tabular}{@{}c@{}}shifted transpose of $A,B,C$ matries given by $M^*_{a,b} := M_{b,a} \cdot u_\DomainA(b,b) \; \forall a,b \in \DomainA$ \\ (optimization from Fractal, explained in Claim 6.7 of that paper) \end{tabular} \\
     \hline
    $\{\hval, \hrow, \hcol\}_{\{A^*,B^*,C^*\}}$ &
    	\begin{tabular}{@{}c@{}} preprocessed polynomials from $A^*, B^*, C^*$ matrices containing LDEs of (respectively) \\ row positions, column positions, and values of non-zero matrix elements \end{tabular} \\
    \hline
    $\hrowcol_{\{A^*, B^*, C^*\}}$ &
        	\begin{tabular}{@{}c@{}} the product polynomial of $\hrow$ and $\hcol$, given separately for efficiency (namely \\ to allow this product to be part of a \textit{linear} combination) \end{tabular} \\
     \hline
    $\Prover$ & prover \\
     \hline
    $\Verifier$ & verifier \\
     \hline
    $\Verifier^{p}$ &
    	\begin{tabular}{@{}c@{}} $\Verifier$ with ``oracle" access to polynomial $p$ (via commitments provided \\ by the indexer, later opened as necessary by $\Prover$) \end{tabular}
  \end{tabular}
\end{table*}

\afterpage{%
\newgeometry{margin=0.5in}

\section{Diagram}

\centering
\begin{tikzpicture}[scale=0.9, every node/.style={scale=0.9}]

\tikzstyle{lalign} = [minimum width=3cm,align=left,anchor=west]
\tikzstyle{ralign} = [minimum width=3cm,align=right,anchor=east]

\node[lalign] (prover) at (-3,27.3) {%
$\Prover(\F, \DomainA, \DomainB, A, B, C, x, w)$
};

\node[ralign] (verifier) at (16.2,27.3) {%
$\Verifier^{\{\hval, \hrow, \hcol, \hrowcol\}_{\{A^*, B^*, C^*\}}}(\F, \DomainA, \DomainB, x)$
};

\draw [line width=1.0pt] (-3,27.0) -- (16,27.0);

\node[lalign] (prover1) at (-3,26.1) {%
$z := (x, w), \za := Az, \zb := Bz$ \\
sample $\w(X) \in \F^{<|w|+\bb}[X]$ and $\za(X), \zb(X) \in \F^{<|\DomainA|+\bb}[X]$ \\
sample mask poly $\s(X) \in \F^{<3|\DomainA|+2\bb-2}[X]$ such that $\sum_{\kappa \in \DomainA}\s(\kappa) = 0$
};

\draw [->] (-2,24.8) -- node[midway,fill=white] {commitments $\cm{\w}, \cm{\za}, \cm{\zb}, \cm{\s}$} (15,24.8);

\node[ralign] (verifier1) at (16,24.0) {%
$\eta_A, \eta_B, \eta_C \gets \F$ \\
$\alpha \gets \F \setminus \DomainA$
};

\draw [->] (15,23.3) -- node[midway,fill=white] {$\eta_A, \eta_B, \eta_C, \alpha \in \F$} (-2,23.3);

\node[lalign] (prover2) at (-3,22.5) {%
compute $t(X) := \sum_M \eta_M r_M(\alpha, X)$
};

\draw (-2.4,22.0) rectangle (15.4,4.8);

\node (sc1label) at (6.5,21.7) {%
\textbf{sumcheck for} $\s(X) + r(\alpha, X) \left(\sum_M \eta_M \zm(X)\right) - t(X)\z(X)$ \textbf{ over } $\DomainA$
};

\node[lalign] (prover3) at (-2,20.7) {%
let $\zc(X) := \za(X) \cdot \zb(X)$ \\
find $g_1(X) \in \F^{|\DomainA|-1}[X]$ and $h_1(X)$ such that \\
$s(X)+r(\alpha, X)(\sum_M \eta_M \zm(X)) - t(X)\z(X) = h_1(X)\vPoly{\DomainA}(X) + Xg_1(X)$ \hspace{0.3cm} $(*)$
};

\draw [->] (-1,19.5) -- node[midway,fill=white] {commitments $\cm{t}, \cm{g_1}, \cm{h_1}$} (14,19.5);

\node[ralign] (verifier2) at (15.4,19.1) {%
$\beta \gets \F \setminus \DomainA$
};

\draw [->] (14,18.7) -- node[midway,fill=white] {$\beta \in \F$} (-1,18.7);

\draw (-0.85,18.2) rectangle (13.85,8.4);

\node (sc2label) at (6.5,17.6) {%
\textbf{sumcheck for } $\sum\limits_{M \in \{A, B, C\}} \eta_M \frac{\vPoly{\DomainA}(\beta) \vPoly{\DomainA}(\alpha)\hval_{M^*}(X)}{\color{purple}(\beta-\hrow_{M^*}(X))(\alpha-\hcol_{M^*}(X))} $ \textbf{ over } $\DomainB$
};

\node[align=center] (mid1) at (6.5, 16.3) {%
$\begin{aligned}
\text{for } M \in \{A, B, C\} \text{, let } {\color{purple} M_\denom(X)} &:= (\beta - \hrow_{M^*}(X)) (\alpha - \hcol_{M^*}(X)) \\
&= {\color{gray}\alpha\beta} - {\color{gray}\alpha}\hrow_{M^*}(X) - {\color{gray}\beta}\hcol_{M^*}(X) + \hrowcol_{M^*}(X)
\end{aligned}$
};

\node[align=center] (mid2) at (6.5, 15.0) {%
let ${\color{orange} a(X)} := \sum\limits_{M \in \{A, B, C\}} {\color{gray} \eta_M \vPoly{\DomainA}(\beta) \vPoly{\DomainA}(\alpha)} \hval_{M^*}(X) \prod_{N \neq M} {\color{purple} N_\denom(X)}$
};

\node[align=center] (mid3) at (6.5, 14.1) {%
let ${\color{Green4} b(X)} := \sum\limits_{M \in \{A, B, C\}} {\color{purple} M_\denom(X)}$
};

\node[lalign] (prover4) at (-0.75,13.2) {%
find $g_2(X) \in \F^{|\DomainB|-1}[X]$ and $h_2(X)$ s.t. \\
$h_2(X)\vPoly{\DomainB}(X) = {\color{orange} a(X)} - {\color{Green4} b(X)} (Xg_2(X)+t(\beta)/|\DomainB|)$ \hspace{0.3cm} $(**)$
};

\draw [->] (0,12.2) -- node[midway,fill=white] {commitments $\cm{g_2}, \cm{h_2}$} (13,12.2);

\draw [->] (13,11.5) -- node[midway,fill=white] {$\gamma \in \F$} (0,11.5);

\node[ralign] (verifier3) at (14.5, 11.9) {%
$\gamma \gets \F$
};

\draw[dashed] (1.5,11.0) rectangle (11.5,8.8);

\node[align=center] (mid4) at (6.5, 9.9) {%
To verify $(**)$, $\Verifier$ will need to check the following: \\[10pt]
$ \underbrace{{\color{orange} a({\color{black} \gamma})} - {\color{Green4} b({\color{black} \gamma})} {\color{gray} (\gamma g_2(\gamma) + t(\beta) / |\DomainB|) - \vPoly{\DomainB}(\gamma)} h_2(\gamma)}_{\sumcheckinner(\gamma)} \stackrel{?}{=} 0 $
};

\node[ralign] (verifier3) at (15.4, 7.9) {%
Compute $\x(X) \in \F^{<|x|}[X]$
};

\draw[dashed] (-2.2,7.4) rectangle (15.2,5.2);

\node[align=center] (mid5) at (6.5, 6.3) {%
To verify $(*)$, $\Verifier$ will need to check the following: \\[10pt]
$ \underbrace{s(\beta) + {\color{gray} r(\alpha, \beta)} ({\color{gray} \eta_A} \za(\beta) + {\color{gray} \eta_C\zb(\beta)} \za(\beta) + {\color{gray} \eta_B\zb(\beta)}) - {\color{gray} t(\beta) \vPoly{X}(\beta)} \w(\beta) - {\color{gray} t(\beta) \x(\beta)} - {\color{gray} \vPoly{\DomainA}(\beta)} h_1(\beta) - {\color{gray} \beta g_1(\beta)}}_{\sumcheckouter(\beta)} \stackrel{?}{=} 0 $
};

\node[lalign] (prover5) at (-3,3.9) {%
$v_{g_2} := g_2(\gamma), v_{A_\denom} := A_\denom(\gamma), v_{B_\denom} := B_\denom(\gamma), v_{C_\denom} := C_\denom(\gamma)$ \\[3pt]
$v_{g_1} := g_1(\beta), v_{\zb} := \zb(\beta), v_{t} := t(\beta)$
};

\draw [->] (-2,2.9) -- node[midway,fill=white] {$v_{g_2}, v_{A_\denom}, v_{B_\denom}, v_{C_\denom}, v_{g_1}, v_{\zb}, v_{t}$} (15,2.9);

\node[align=center] (mid6) at (6.5,1.9) {%
use index commitments $\hrow, \hcol, \hrowcol$ to construct virtual commitments $\vcm{\{A_\denom, B_\denom, C_\denom\}}$
};

\node[align=center] (mid7) at (6.5,0.8) {%
use index commitments $\hval$, commitments $\vcm{A_\denom}$, $\vcm{B_\denom}, \vcm{C_\denom}, \cm{h_2}$, {\color{gray} and evaluations $g_2(\gamma),t(\beta)$} \\
to construct virtual commitment $\vcm{\sumcheckinner}$
};

\node[align=center] (mid8) at (6.5,-0.5) {%
use commitments $\cm{\s}, \cm{\za}, \cm{\w}, \cm{h_1}$ {\color{gray} and evaluations $\zb(\beta), t(\beta), g_1(\beta)$} \\
to construct virtual commitment $\vcm{\sumcheckouter}$
};

\node[ralign] (verifier4) at (16,-1.5) {%
$\xi_1, \dots, \xi_5 \gets \F$
};

\draw [->] (15,-2.1) -- node[midway,fill=white] {$\xi_1, \dots, \xi_5$} (-2,-2.1);

\node[lalign] (prover6) at (-3,-3.6) {%
use $\mathsf{PC}.\mathsf{Prove}$ with randomness $\xi_1, \dots, \xi_5$ to \\
construct a batch opening proof $\pi$ of the following: \\
$(\cm{g_2}, \cm{A_\denom}, \cm{B_\denom}, \cm{C_\denom}, {\color{red} \vcm{\sumcheckinner}})$ at $\gamma$ evaluate to $(v_{g_2}, v_{A_\denom}, v_{B_\denom}, v_{C_\denom}, {\color{red} 0})$ \hspace{0.3cm} ${\color{red} (**)}$ \\
$(\cm{g_1}, \cm{\zb}, \cm{t}, {\color{red} \vcm{\sumcheckouter}})$ at $\beta$ evaluate to $(v_{g_1}, v_{\zb}, v_{t}, {\color{red} 0})$ \hspace{0.3cm} ${\color{red} (*)}$ \\
};

\draw [->] (-2,-4.7) -- node[midway,fill=white] {$\pi$} (15,-4.7);

\node[ralign] (verifier5) at (16,-6.0) {%
verify $\pi$ with $\mathsf{PC}.\mathsf{Verify}$, using randomness $\xi_1, \dots, \xi_5$, \\
evaluations $v_{g_2}, v_{A_\denom}, v_{B_\denom}, v_{C_\denom}, v_{g_1}, v_{\zb}, v_{t}$, and \\
commitments $\cm{g_2}, \cm{A_\denom}, \cm{B_\denom}, \cm{C_\denom},$ \\
$\vcm{\sumcheckinner}, \cm{g_1}, \cm{\zb}, \cm{t}, \vcm{\sumcheckinner}$
};

\end{tikzpicture}

\clearpage
\restoregeometry
}

\end{document}


\chapter{Create a Mesh from a Grid}
In this chapter, we show how to create a mesh with \Atlas
starting from a grid. We assume that the reader already
knows how to create a grid (see \chap{chap:global-grids}).
%
\begin{notebox}
With the term \textit{grid} we intend a list of points
without any specific connectivity rule, while with the
term mesh we intend a list of points with well-specified
connectivity rules.
\end{notebox}
%
As before, we show both the C++ and Fortran version
for this example.

\section{C++ version}
The \lista{code-meshes-C} shows how to construct a mesh
starting from a grid.
%
\lstinputlisting[caption=Generating a mesh starting from a grid
in \Atlas using C++, style=CStyle, label=code-meshes-C]{meshes-Structured.cc}
%
Once defined the command-line behaviour, we first create
a global structured grid object (see line 24). For more
details on how to create a grid see \chap{chap:global-grids}.

We then create a
\inltc{mesh::generators::Structured} object called \inltc{generate\_mesh}
that will allow us to generate the mesh starting from
a structured grid.
We successively create a mesh object, \inltc{mesh}
of the \inltc{Mesh} type on line 27 using the mesh generator.

In this simple example we took the freedom to add a few
lines to show how to visualize the mesh in Gmsh. In particular,
on line 29 we define a Gmsh object called \inltc{gmsh} that
will be used to generate a Gmsh output. On line 30 we specify
that we want to have some information regarding the mesh - this
is achieved by defining as \inltc{true} the tag \inltc{"info"}.
Between line 31 and 35, we add two additional lines to visualize
the mesh in 3D if required on the command-line.
Finally, on line 36 we write the mesh and save it into \inltc{mesh.msh}.
Note that the file containing the information on the mesh
just created is called \inltc{mesh\_info.msh}.

It is now possible to run this simple program by using
two command-line arguments representing the keyword that
identifies an \Atlas predefined grid and the visualization
type we want (either 2D or 3D), respectively. For instance,
we can execute the following command line
%
\begin{lstlisting}[style=BashStyle]
./atlas_c-meshes-Structured
\end{lstlisting}
%
This will produce an octahedral reduced Gaussian mesh
(stored in mesh.msh) with 32 latitudes on one hemisphere
(i.e. 64 latitudes in total). It will also produce an
additional file, called \inltc{mesh\_info.msh}, containing
some information regarding the mesh.
Note that we used the additional command-line argument
\inlsh{--visualize 3D}. This will produce a 3D representation
of the mesh, such as the one depicted in left side of
\fig{fig:meshes}.

We can re-run the executable file in order to obtain
a 2D representation as follows:
%
\begin{lstlisting}[style=BashStyle]
./atlas_c-meshes-Structured --grid O32 --visualize 2D
\end{lstlisting}
%
This will produce a representation of the mesh like
the one depicted on the right side of \fig{fig:meshes}.
%
\begin{figure}%
\centering
\subfloat{\includegraphics[width=5cm]{imgs/O32-3D.png}}\qquad\qquad\qquad
\subfloat{\includegraphics[width=5cm]{imgs/O32-2D.png}}
\caption{Meshes visualised in Gmsh}%
\label{fig:meshes}%
\end{figure}
%
You can now play with the command-line argument to generate
different types of global structured meshes using the keys
introduced in \chap{chap:global-grids}!

\section{Fortran version}
The \lista{code-meshes-C} shows how to construct a mesh
starting from a grid.
%
\lstinputlisting[caption=Generating a mesh starting from a grid
in \Atlas using Fortran, style=FStyle, label=code-meshes-F]{meshes-Structured.F90}
%
We first create
a global structured grid object (see line 13). For more
details on how to create a grid see \chap{chap:global-grids}.

We successively create the mesh object on line 15 and 16.
In particular, we first define a \inltc{atlas\_Meshgenerator}
object that is then used to effectively generate the mesh object
\inltc{mesh} that is an \inltc{atlas\_Mesh} type.

In this simple example we took the freedom to add just one line
line to visualize the mesh in Gmsh. In particular, on line 17
we call \inltc{atlas\_write\_gmsh} to write a Gmsh file called
\inlsh{mesh.msh}. Note that at the end of the program we also
need to destroy the local object created in this program (see
lines 19 to 21).

It is now possible to run this simple program by using
a command-line arguments representing the keyword that
identifies an \Atlas predefined grid. For instance,
we can execute the following command line
%
\begin{lstlisting}[style=BashStyle]
./atlas_c-meshes-Structured
\end{lstlisting}
%
This will produce an octahedral reduced Gaussian mesh
(stored in mesh.msh) with 32 latitudes on one hemisphere
(i.e. 64 latitudes in total).
If we visualize it in Gmsh, we will obtain something similar
to \fig{fig:meshes-f}.
%
\begin{figure}%
\centering
\includegraphics[width=0.5\textwidth]{imgs/O32-2D.png}
\caption{Mesh visualised in Gmsh}%
\label{fig:meshes-f}%
\end{figure}
%
You can now play with the command-line argument to generate
different types of meshes for global grids using the keys
introduced in \chap{chap:global-grids}!


\section{Results}
\label{sec:results}
\begin{table}
	\begin{center}
		\begin{tabular}{|p{0.2\linewidth}|p{0.2\linewidth}|p{0.2\linewidth}|} \hline
			Method & Mean Version & Standard Deviation \\ \hline
			Two Planes & 8.9\degree & 4.7\degree \\
			Corrected Friedman & 8.4\degree & 6.5\degree \\
			Friedman & 9.4\degree & 7.4\degree \\
			Vault & 12.3\degree & 7.7\degree \\
			Commercial software & 9.9\degree & 6.1\degree \\
                        \hline
		\end{tabular}
	\end{center}
	\caption{\label{tab:results}A comparison of the results of each method tested
	on 10 retrospective patients}
\end{table}

Table \ref{tab:results} presents the results of using \sksglenoid on 10 patients.
The version measured using the planes method has a mean glenoid
version of 8.9\degree (SD, 4.7\degree; range, 5\degree to 20.9\degree),
while mean glenoid version
for the 3D corrected Friedman method
was 8.4\degree (SD, 6.5\degree; range, -4.0\degree to 16.9\degree).
For the 2D methods, the mean glenoid version for the
Friedman method was 9.4\degree (SD, 7.4\degree; range, -0.7\degree to 24\degree)
and for the vault model was 12.3\degree (SD, 7.7\degree; range, 4\degree to 26\degree).
In this
case a positive value indicates retroversion while a negative value indicates anteversion of the
glenoid. Overall, the 3D methods resulted in both lower mean version values as well as lower
variability, while the 2D methods revealed a slightly higher variability.

The measurements using these methods were also compared with version measurements on the same
10 patients using a commercial software\cite{djosurgical}.
The planes method (r = 0.90, p = 0.0004),
corrected Friedman method (r = 0.83, p = 0.0034),
and conventional Friedman method (r = 0.79, p = 0.0064)
all showed significant correlation with the commercial software.
The vault method did not show significant correlation (r = 0.59, p = 0.074).
The mean difference between the methods were overall not significant ($\rm{p} > 0.05$),
except for the vault method (p = 0.03). Correlation plots are shown in Figure \ref{fig:correl}.

\begin{figure}
	\begin{center}
		\begin{subfigure}[b]{0.30\linewidth}
			\includegraphics[width=\linewidth]{figures/planes.png}
			\caption{Two Planes Method}
		\end{subfigure}
		\begin{subfigure}[b]{0.30\linewidth}
			\includegraphics[width=\linewidth]{figures/correctedfried.png}
			\caption{Corrected Friedman Method}
		\end{subfigure}
		\begin{subfigure}[b]{0.30\linewidth}
			\includegraphics[width=\linewidth]{figures/friedman.png}
			\caption{Friedman Method}
		\end{subfigure}
		\caption{\label{fig:correl}The Pearson correlation between the commercial software and the 3 methods that gave a statistically significant result.}
	\end{center}
\end{figure}


\chapter{{\tt Cartography} Module}\label{ch:cartography-module}

[{\em Note: The documentation for this chapter is not yet complete... }]
$$
$$
The earliest robots in space were not planetary rovers -- they were
unmanned probes that studied the planetary bodies in our solar system
from afar.  Today there are roughly twenty extraterrestrial spacecraft
in active communication with earth (and only two planetary rovers), so
the bulk of the extraterrestrial data that we receive consists of
imagery that originated on round(ish) surfaces.  The natural thing to
do with this data is to merge it together into a map, but when doing
so we are faced with the same problem that has plagued cartographers
for hundreds of years: how does one flatten the globe?  This is the job
of the Vision Workbench Cartography module: to make maps.

Before diving into an introduction on planetary cartography, we will
point out another problem that is relatively new to Cartography.  The
amount of map data that we have collected about Earth and the other
bodies in our solar system is {\em immense}.  It is often impossible
to store an entire mapping data set in memory all at once, so
intelligent paging, caching, and storage strategies must be used in
order to make working with this data tractable.  For this reason, the
Cartography module is particularly powerful when used in conjunction
with Mosaic module (see Chapter \ref{ch:mosaic-module}), which is
designed to efficiently process and combine extremely large data sets.

We will begin this chapter with a quick summary of the third party
libraries that are needed to compile the Vision Workbench.  We will
then describe the \verb#GeoRefence# class, which creates a
relationship between pixel coordinates in an image and coordinates on
a globe.  Next, we will discuss the \verb#GeoTransform# class, which
provides a simple means of re-projecting map data.  We finish this
section with methods for reading and writing image files with embedded
geospatial metadata.

\section{Software Dependencies}

The Cartography module is currently built on top of two third party
libraries:

\begin{itemize}
\item GDAL   [ {\tt http://www.remotesensing.org/gdal/ } ]
\item Proj.4 [ {\tt http://proj.maptools.org/ }]
\end{itemize}

In order to enable the Cartography module, you must have these
libraries installed on your system before you configure and build the
Vision Workbench.  You may need to use the \verb#PKG_PATHS# directive
in the \verb#config.options# file if you install them in a
non-standard location as discussed in Chapter \ref{ch:gettingstarted}.

Once the library for the Cartography module has been built, the header
files for GDAL and Proj.4 are no longer needed, so you can rely solely
on linking in libraries when building your own application.

\section{The {\tt GeoReference} Class}

When you point at a location on a map, you probably want to know where
that location can be found in the real world.  This relationship
depends first and foremost on the familiar notion of a map's scale.
However, this relationship is also affected by a subtle, but extremely
important dependence on how the map is {\em projected}.  That is, the
image depicts a scene that sits on the surface of a spheroid.
However, the image is flat, so at best it represents a very slightly
distorted view of the surface.

One can imagine all sorts of different ways that the surface can be
warped or projected onto a flat plane (or, at the very least,
projecting onto a manifold that can be unfolded into a plane without
distorting distances and areas -- a sphere cannot be unfolded in this
way).  Generations of cartographers have struggled with this
topological challenge, and as a result they have developed many
different ways to ``un-fold'' the globe so that it can be represented
as a flat image.  Rather than attempt a description of these many
techniques here, we suggest you look at this excellent web site
describing all aspects of map projections.

\begin{verbatim}
  http://www.progonos.com/furuti/MapProj/CartIndex/cartIndex.html
\end{verbatim}

The Proj.4 manual is also recommended as a reference for the specific
map projections supported by the Vision Workbench.

Now would be a good time to take a break from reading this section of
the documentation to look over these references.  When you return, we
will dive into some code examples.

\subsection{The Datum}

A Vision Workbench \verb#GeoReference# object is composed of three items:

\begin{itemize}
\item {\bf The Projection}: As discussed above, this is the technique
  used to represent the round globe in a flat image.
\item {\bf The Affine Transform}: This is the geometric transformation
  between pixel coordinates in the image to coordinates in the map
  projection space.
\item {\bf The Datum}: Describes the approximate shape of the
  planetary body, as either a sphere or an ellipsoid.
\end{itemize}

\subsection{The Affine Transform}

Let's start by being explicit about the coordinate systems we will be
working with.  For images, we adopt the usual Vision Workbench
coordinate system wherein the upper left corner of the image is the
origin, the $u$ coordinate increases as you move right along the
columns of the image, and the $v$ coordinate increases as you move
down the rows.

For a planetary body, the coordinate of a point on the surface is
typically measured in latitude, longitude, and radius ($\phi, \theta,
r$).  Lines of latitude are perpendicular to the axis of rotation and
are measured from the center line, the {\em equator} (+/-90 degrees).
Lines of Longitude are vertical, passing through both the North and
South poles of the planet.  It is measured from a vertical arc on the
surface called the {\em meridian}.  We will generally adopt an East
positive frame of reference (latitude increases to the east of the
meridian 0-360 degrees).  Finally, the radius is measured from the
point to the planet's center of mass.  Note that this coordinate
system is similar but not identical to spherical coordinates in a
mathematical sense, where ``latitude'' would be measured from the
North pole rather than the equator.

Under this set of assumptions, if we have a point $P_{img} = (u,v)$ in
the image, and we want to relate it to some planetary coordinates

\subsection{Putting Things Together}
%% - The GeoReference Object
%%   - Creating
%%     - proj4str
%%     - datum and transform
%%   - << streaming
%%   - Setting projections

\begin{table}[t]\begin{centering}
\begin{tabular}{|l|l|l|} \hline
Method & Description \\ \hline \hline
\verb#set_sinusoidal()# & Sinusoidal Projection \\ \hline
\verb#set_mercator()# & Mercator Projection \\ \hline
\verb#set_orthographic()# & Orthographic Projection \\ \hline
\verb#set_stereographic()# & Stereographic Projection \\ \hline
\verb#set_UTM()# & Universal Transverse Mercator (UTM) Projection (Earth only) \\ \hline
\end{tabular}
\caption{Currently supported {\tt GeoReference} map projections.}
\label{tbl:georeference-map-projections}
\end{centering}\end{table}

\section{Geospatial Image Processing}
\subsection{The {\tt GeoTransform} Functor}
%%     - Use to reproject maps
%%     - Formulate a source and destination \verb#GeoReference# object
%%     -
%%   - \verb#xyz_to_latlon()#

\section{Georeferenced File I/O}
\subsection{{\tt DiskImageResourceGDAL}}


\documentclass[11pt]{article}

%% WRY has commented out some unused packages %%
%% If needed, activate these by uncommenting
\usepackage{geometry}                % See geometry.pdf to learn the layout options. There are lots.
%\geometry{letterpaper}                   % ... or a4paper or a5paper or ...
\geometry{a4paper,left=2.5cm,right=2.5cm,top=2.5cm,bottom=2.5cm}
%\geometry{landscape}                % Activate for rotated page geometry
%\usepackage[parfill]{parskip}    % Activate to begin paragraphs with an empty line rather than an indent

\usepackage{natbib}

%for figures
%\usepackage{graphicx}

\usepackage{color}
\definecolor{mygreen}{RGB}{28,172,0} % color values Red, Green, Blue
\definecolor{mylilas}{RGB}{170,55,241}
%% for graphics this one is also OK:
\usepackage{epsfig}

%% AMS mathsymbols are enabled with
\usepackage{amssymb,amsmath}

%% more options in enumerate
\usepackage{enumerate}
%\usepackage{enumitem}

%% insert code
\usepackage{listings}

\usepackage[utf8]{inputenc}

\usepackage{hyperref}

%% To make really wide whats that cover everything:
\usepackage{scalerel}
\usepackage{stackengine}
\stackMath
\def\hatgap{2pt}
\def\subdown{-2pt}
\newcommand\what[2][]{%
\renewcommand\stackalignment{l}%
\stackon[\hatgap]{#2}{%
\stretchto{%
    \scalerel*[\widthof{$#2$}]{\kern-.6pt\bigwedge\kern-.6pt}%
    {\rule[-\textheight/2]{1ex}{\textheight}}%WIDTH-LIMITED BIG WEDGE
}{0.5ex}% THIS SQUEEZES THE WEDGE TO 0.5ex HEIGHT
_{\smash{\belowbaseline[\subdown]{\scriptstyle#1}}}%
}}

% Default fixed font does not support bold face
\DeclareFixedFont{\ttb}{T1}{txtt}{bx}{n}{12} % for bold
\DeclareFixedFont{\ttm}{T1}{txtt}{m}{n}{12}  % for normal

% Custom colors
\usepackage{color}
\definecolor{deepblue}{rgb}{0,0,0.5}
\definecolor{deepred}{rgb}{0.6,0,0}
\definecolor{deepgreen}{rgb}{0,0.5,0}

% colors
\usepackage{graphicx,xcolor,lipsum}

\usepackage{mathtools}

\usepackage{graphicx}
\newcommand*{\matminus}{%
  \leavevmode
  \hphantom{0}%
  \llap{%
    \settowidth{\dimen0 }{$0$}%
    \resizebox{1.1\dimen0 }{\height}{$-$}%
  }%
}

% commmand for this doc
\newcommand{\So}{\mathcal{S}}
\newcommand{\bvth}{\bar{\vth}}
\newcommand{\kappat}{\kappa_{tot}}
\newcommand{\kappae}{\kappa_{e}}
\newcommand{\kappaN}{\kappa_{n}}
\newcommand{\kappaoc}{\kappa_{oc}}

\title{Notes on Modal Projection and non-zero vertical shear at the boundary, etc.}
\author{Cesar \& Bill}
\date{\today}

\begin{document}

\include{symbols}

\maketitle

%\section{}

We want to calculate the mean quasigeostrophic potential vorticity gradients:
\beq
    \label{meanQGPV}
    Q_y = \beta - \sL V(z)\com \qquad \text{and} \qquad Q_x = \sL U(z) \com
\eeq
where $\sL \defn \p_z (f_0/N)^2 \p_z $ is the stretching operator. Calculation of $\sL U$ and $\sL V$
from data is typically noisy. To reduce the noise, we want to project the basic state velocity onto
the familiar vertical modes $\sp_n$ that satisfy
\beq
\label{modes}
\sL \sp_n = - \kappa_n^2 \sp_n\com
\eeq
with $\sp_n' = 0\com~ z = -h, 0$. However, with nonzero vertical shear at the boundaries we cannot differentiate the series for $U(z)$ and $V(z) $. So, instead of the tradition series, we write
\beq
\label{decomp}
U(z) \approx U_s(z) + U_i(z)\com
\eeq
where $U_i(z)$ is an ``interior'', boundary shearless, velocity component:
\beq
\label{Uint}
U_i(z) = \sum_{n=0}^{\nmax} \breve{U}_n \sp_n\com \qquad \breve{U}_n = \tfrac{1}{h}\int_{-h}^{0}\!\! \sp_n \, [U(z)-U_s(z)]  \dd z\com
\eeq
and $U_s(z)$ satisfies $U'(\zm) = U_s'(\zm)$ and  $U'(\zp) = U_s'(\zp)$. Also in \eqref{decomp} the approximate sign stems from the truncated nature of the series \eqref{Uint}. A simple choice is
\beq
\label{dUsurf}
\frac{\dd U_s}{\dd z} = \frac{N^2(z)}{N^2(0)} \frac{z + h}{h} U'(0) - \frac{N^2(z)}{N^2(-h)} \frac{z}{h} U'(-h)\per
\eeq
The reason we include the $N^2$ factors above, e.g. $N^2(z)/N^2(0)$ is that we want to calculate $\sL U_s$ as smoothly as possible, and hence independently of derivatives of $N^2(z)$. With this choice we have
\beq
\label{Usurf}
U_s(z) = \frac{U'(0)}{N^2(0) h}\int_{0}^{z} N^2(z') (z' + h) \dd z' -  \frac{U'(-h)}{N^2(-h) h}\int_{0}^{z} N^2(z') z'  \dd z  + A \com
\eeq
where $A$ is determined by imposing a no net transport condition
\beq
\int_{-h}^{0} U_s'(z) \dd z = 0\per
\eeq
We obtain
\beq
\label{A}
A =  -\frac{U'(0)}{N^2(0) h^2}\int_{-h}^0 \dd z \int_{0}^{z} N^2(z') (z' + h) \dd z' +  \frac{U'(-h)}{N^2(-h) h^2} \int_{-h}^0 \dd z  \int_{0}^{z} N^2(z') z'  \dd z
\eeq
The integrals above are calculated numerically for an arbitrary buoyancy profile $N^2(z)$.

% for constant N(z) we calculate the integrals analytically
%\beq
%\label{A}
%A = \frac{1}{3 h }\left( \frac{U'(-h)}{2} - U'(0) \right) \per
%\eeq
%Thus
%\beq
%\label{Usurf2}
%U_s(z) = \frac{U'(0)}{h}\left( \frac{z^2}{2} + z h - \frac{1}{3}\right) - \frac{U'(-h)}{h} \left(\frac{z^2}{2} + \frac{1}{6} \right) \per
%\eeq

In summary, knowledge of the shear at the boundaries determines the ``surface'' velocity component $U_s(z)$ that
can be then be subtracted from the total velocity to obtain a ``interior'' velocity component $U_i(z)$. Because $U_i(z)$ is shearless at the boundaries, we can accurately calculate $\sL U$
\beq
\sL U \approx \sL U_s + \sL U_i  = \frac{f_0^2}{N^2(0)} \frac{U'(0)}{h}
- \frac{f_0^2}{N^2(-h)} \frac{U'(-h)}{h} - \sum_{n=1}^{\nmax} \kappa_n^2 \breve{U}_n \sp_n \per
\eeq

\end{document}


\chapter{\projmr3 Catalog Analysis by the Two--Point Correlation Funciton}

\section{Definition}
\subsection{Introduction}
The two--point correlation function $\xi(r)$ has been the primary tool
for quantifying large--scale cosmic structure\cite{cf:peebles80}.
Assuming that the galaxy distribution in the Universe is a realization
of a stationary random process of density $\rho$, the two--point
correlation function can be defined from the probability $P$ to find
an object within a volume element $\delta v$ at distance $r$ from a
randomly chosen object or position inside the volume:
\begin{equation}
\delta P = n(1 + \xi(r))\delta v,
\end{equation}
where $n$ is the mean density of objects.  The $\xi(r)$ function
measures the clustering properties of objects in a given volume. It is
zero for a uniform random distribution, positive (resp.  negative) for
a more (resp. less) concentrated distribution. For a hierarchical
gravitational clustering or fractal processus, $\xi(r)$ has a power
law behavior
\begin{equation}
\xi(r) \sim r^{-\gamma}.
\end{equation}

In an unbounded volume embedded in a three-dimensional Euclidean
space, we can compute $\xi(r)$ by considering a large number of points
$N$ and calculate the average
\begin{equation}
1 + \xi(r) = {N(r) \over N_{p}(r)}
\end{equation}
where $N(r)$ is the number of pairs of points with a separation in the
interval $[r-\Delta r, r+\Delta r]$, and $N_{p}(r)$ is the number of
pairs for a Poisson distribution in the same volume. As $N_{p}(r) =
4\pi r^2 n dr$, we have
\begin{equation}
1 + \xi(r) = {1 \over N} \sum_{i=1}^N {N_i(r) \over 4\pi r^2 n dr}
\end{equation}
where $N_i(r)$ is the number of points lying in a shell of thickness
$dr$, with radius $r$, and centered at the point labeled $i$.
However, when the calculation has to be performed on a finite volume,
the effect of the edges has to be seriously considered.  For this
reason, other estimators have been proposed, which consider the
estimation of the volume around each data point by means of Monte
Carlo random catalog generations. We present in this report a
description of the most used estimators, and show the results obtained
for some samples with well-known or well-studied clustering
properties.

\subsection{The 2-points correlation function determination}
\subsubsection*{Standard method}
Given a catalogue containing $N_d$ points, we introduce a random
catalog with $N_R$ points, and note
\begin{itemize}
\item $DD(r)$ = number of pairs in the interval $(r \pm dr/2)$ in the
  data catalog.
\item $RR(r)$ = number of pairs in the interval $(r \pm dr/2)$ in the
  random catalog.
\end{itemize}
The two--point correlation function $\xi(r)$ is derived from
\begin{equation}
\tilde \xi(r) =  {N_R(N_R-1) \over N_D(N_D-1)} {DD(r) \over RR(r)} -1,
\label{std_method}
\end{equation}
where $N_R(N_R-1)/2$ and $ N_D(N_D-1)/2$ are the number of pairs in
the random and data catalog. The ratio of this two values is a
normalization term.

\subsubsection*{Davis-Peebles method}
Davis and Peebles \cite{cf:davis83} have proposed a more robust
estimator, by introducing $DR$, the number of pairs between the data
and the random sample within the same interval.
\begin{equation}
\tilde \xi_{DP}(r) =  2{N_R \over N_D-1} {DD(r) \over DR(r)} -1
\label{dp_method}
\end{equation}

\subsubsection*{Hamilton method}
Another possibility is to use Hamilton approach \cite{cf:hamilton93},
which corrects for a presence in the data of large-scale artificial
correlation due to some periodicity caused by the volume boundaries or
by some selection effects.

\begin{equation}
\tilde \xi_{HAM}(r) =   {DD(r) RR(r) \over [DR(r)]^2} -1
\label{ham_method}
\end{equation}

\subsubsection*{Landy-Szalay method}
Landy-Szalay estimator \cite{cf:landy93} was introduced with the goal
to produce a minimum variance estimator and also like Hamilton
estimator is not affected by large-scale correlations:
\begin{equation}
\tilde \xi_{LS}(r) =  c_1 {  DD(r) \over  RR(r)}  -  c_2 { DR(r) \over
RR(r)}
\label{ls_method}
\end{equation}
with
\begin{eqnarray}
c_1 & = & {N_R(N_R-1)\over   N_D(N_D-1)} \nonumber \\
c_2 & = &  {2 N_R(N_R-1) \over N_D N_R}
\end{eqnarray}

\subsection{Error analysis}

Assuming the errors in the correlation function are distributed
normally (which is not completely true having in mind the
cross-correlation in the different separation bins) we can estimate the
uncertainty as a Poisson statistics for the corresponding errors in
bins:
\begin{equation}
\Delta_{P} \tilde \xi(r) = {1 + \tilde  \xi(r) \over \sqrt{DD(r)}}
\label{eq_pois}
\end{equation}

If $C$ random catalogs $R_1, ..., R_C$ are created instead of one,
then $\tilde \xi(r)$ can be estimated $C$ times, and our final
estimate is:
\begin{equation}
\tilde \xi(r) = {1 \over C }\sum_{i=1}^C \tilde \xi_i(r)
\end{equation}
and the error is obtained by
\begin{equation}
\Delta_{STD} \tilde \xi(r) = \sqrt{ (\tilde \xi_i(r) -
  \tilde \xi(r))^2 \over C-1}
\label{eq_std}
\end{equation}

Finally, a third approach is also popular, and consists in using a
bootstrap method \cite{cf:efron86}. $C$ bootstrap samples $B_1,..,B_C$
are created by taking randomly with replacement the same number of
points that form the original sample. Then the bias-corrected 68\%
bootstrap confidence interval is
$[\xi_{boot}(0.16),\xi_{boot}(0.84)]$, where
\begin{equation} \xi_{boot}(t) = G^{-1}\left\{\Phi\left[\Phi^{-1}(t) +
      2\Phi^{-1}\left[G(\xi_0)\right]\right]\right\}.
\label{eq_boot}
\end{equation}

Here $G$ is the cumulative distribution function (CDF) of the $\xi(r)$
values, for a given bin $r \pm \Delta r$, for all bootstrap
resamplings, $\Phi$ is the CDF of the normal distribution, $\Phi^{-1}$
is its inverse function and $\xi_0$ is the estimated $\xi(r)$ taken
from other than the bootstrap resampling results (e.g. from random
catalog generations). Note that $\Phi(0.16) = -1.0$ and $\Phi(0.84) =
1.0$.

This confidence estimator, as the authors \cite{cf:efron86} claim, is
valid when $G$ is not Gaussian. However, this method requires a large
number of bootstrap resamplings (usually more than 100) and for large
datasets with tens of thousands of points it becomes quite time
consuming.

Note that we can take also the $\Delta^{boot}_{STD}$ for the bootstrap
resamplings and then it can be simply written --
$[\xi_{boot}(0.16),\xi_{boot}(0.84)] = \xi_0 \pm \sigma_{\xi}$,
where
\begin{equation}
\sigma_{\xi} = \sqrt{ (\xi^{i}_{boot}(r) - \xi_{0}(r))^2 \over B-1}.
\end{equation}

\subsection{Correlation length determination}

The two-point correlation function for the gravitational clustering or
fractal distribution can be given as a power low:
\begin{eqnarray}
 \xi(r) = A r^{-\gamma}
\end{eqnarray}
Where $A$ is the amplitude and $\gamma$ is the power low index.

The correlation length $r_c$ is defined by
\begin{eqnarray}
 \xi(r) = ({r\over r_c}) ^{-\gamma},
\end{eqnarray}
and it is the separation at which the correlation is 1. This scale in
principle divides the regime of strong, non-linear clustering ($\xi >>
1$) from linear clustering.

It is easy to connect $r_c$ with $A$ and $\gamma$ by:
\begin{eqnarray}
r_c = \exp^{-{A \over \gamma}}
\end{eqnarray}

\section{Application}
\subsection{Simulation of Cox process}

The segment Cox point process \cite{cf:pons99} is a clustering process
for which an analytical expression of its 2--point correlation
function is known and therefore can be used as a test to check the
accuracy of the $\xi$--estimators.  segments of length $l$ are
randomly scattered inside a cube $W$ and on these segments points are
randomly distributed.  Let $L_V$ be the length density of the system
of segments, $L_V=\lambda_{\rm{s}}l$, where $\lambda_{\rm{s}}$ is the
mean number of segments per unit volume. If $\lambda_l$ is the mean
number of points on a segment per unit length, then the intensity
$\lambda$ of the resulting point process is

\begin{equation}
\lambda=\lambda_lL_V=\lambda_l\lambda_{\rm{s}}l\,.
\end{equation}

For this point field the correlation function can be easily calculated
taking into account that the point field has a driving random measure
equal to the random length measure of the system of segments. It has
been shown \cite{cf:stoyan95} that
  \begin{equation}
\xi_{\rm {Cox}}(r)=\frac{1}{2\pi r^2L_V}-\frac{1}{2\pi rlL_V} \label{skm}
\end{equation}
for $r \le l$ and vanishes for larger $r$. The expression is
independent of the intensity $\lambda_l$.  Figure~\ref{fig_cox_cube}
show the simulation of a Cox process with 6000 points.
Figure~\ref{fig_cox_curve} shows the analytical $\xi_{\rm {Cox}}(r)$
curve (continuous line), and the estimated two--point correlation
function overplotted. The Landy-Szalay method has been used with 10000
random points. The errors are the results from 20 random Cox process
realizations.

\begin{figure}[htb]
\centerline{
\hbox{
\psfig{figure=fig_cox.ps,bbllx=2.5cm,bblly=13.5cm,bburx=18.5cm,bbury=25cm,width=14cm,height=14cm,clip=}
}}
\caption{Simulation of a Cox process with 6000 points.}
\label{fig_cox_cube}
\end{figure}

\begin{figure}[htb]
\centerline{
\hbox{
\psfig{figure=fig_coxcurve.ps,bbllx=2.cm,bblly=1cm,bburx=18cm,bbury=17cm,width=10cm,height=8cm,clip=}
}}
\caption{Analytical $\xi_{\rm {Cox}}(r)$ curve (continuous line), and
  two--point correlation function of the Cox process with 6000 points
  overplotted, using the Landy-Szalay method.  The error bars are
  obtained from the minimum and maximum of twenty realizations.}
\label{fig_cox_curve}
\end{figure}

% \section{Limitation}
% \begin{itemize}
% \item the evaluation of ${\cal \epsilon}$ depends on the size of the
%   sampled volume.
% \end{itemize}

\subsection{Two--point correlation of astronomical catalogues}

\subsubsection{Introduction}
Usually the catalogues of the extragalactic objects contain the
angular coordinates of the objects (galaxies, groups, clusters,
superclusters, voids) on the sky -- in equatorial coordinate system
they are right ascension ($\alpha$) and declination ($\delta$),
galactic longitude ($l$) and galactic latitude ($b$) in galactic
coordinates and supergalactic longitude ($SL$) and supergalactic
latitude ($SB$) in supergalactic coordinates. The recent
extragalactic catalogues could contain many objects with their
respective redshift $z$ so in principle it is possible to transform
the angular coordinates + redshift to a rectangular coordinates
system. To do this one has to assume a cosmological model ($H_0,\
q_0$) in order to transform the redshift to the distance in Mpc and
also to choose which distance measure to use (e.g. ``luminosity
distance'', ``angular diameter distance'', ``comoving distance'').

The choice for the angular coordinate system depends on the problem
and it is convenient to use that system for which the catalogue
boundaries could be most easily defined. For the distance, the
situation in the literature is quite confused with various authors
using various distance measures.

Also all the methods for estimation of the correlation function could
work also for the particular case of having only angular positions on
the sky. This is the case for example in catalogs from radio
observations where there is no information for the distance. Then
usually the correlation function, denoted $w(\theta)$ is a function on
the angular separation $\theta$.

\subsubsection{Creation of random catalogs}
One of the crucial steps in estimation of the correlation function is
the random catalogue creation. The catalogues contain data which is
subject to various selection effects and incompleteness. Not taking
them into account could lead to false correlation. The major effects
are the distance selection function -- the number of objects as a
function of the distance, and the galactic latitude
selection function.

The first effect is caused by the geometry of space-time and the
detection of only the strongest objects at a great distances. For
uniform distribution of points in 3D Euclidean space $N(R) \sim
R^{-3}$.

The second effect is caused by light absorption from our Galaxy and it
depends on the galactic latitude. Usually it is modeled as a cosec
function and in terms of probability density function it could be
given:
\begin{equation}
P(b) = 10^{\alpha(1-cosec|b|)}.
\end{equation}

These two effects after their correct treatment from the data
catalogue must be included in the random catalogue generation.

As the different catalogs of objects are subject to different
selections, it is not possible to make one single procedure for random
catalog generations. We have supplied however versions for some
interesting particular cases.

\subsubsection{Application to IRAS data}

We present in this section the two points correlation function
analysis of the IRAS 1.2 Jy Redshift Survey \cite{cf:fisher95} for a
volume limited subsample.

In order to create a volume limited subsample from the IRAS catalog,
we applied the following steps:

\begin{itemize}
\item Extract from the catalog the Right Ascension $\alpha$ (hh,mm,ss,1950),
the declination $\delta$ (sign,dg,mm,ss,1950), and the velocity $Hvel$ (km/s).
\item Convert $\alpha,\ \delta$ to galactic coordinates $l,b$ (in radians)
  because the catalog boundaries ($|b| > 5 \deg$) are most easily
  defined in this system.
\item Convert velocity to redshift ($z= Hvel/c$).
\item Assuming $H_0=100$ and $\Omega=1$, calculate the distance $d$ by the
luminosity distance formulae proposed by Ue-Li Pen (astro-ph/9904172):
\begin{eqnarray}
d_L & = & {c \over H_0}(1+z) [ F(1,\Omega_0) - F({1 \over 1 + z}, \Omega_0)] \nonumber  \\
F(a,\Omega_0) & = & 2 \sqrt{s^3+1}
[ {1 \over a^4} - 0.1540 {s \over a^3} + 0.4302 {s^2 \over  a^2} +
        0.19097*{s^3 \over a} + 0.066941 s^4 ]^{-{1\over 8}}  \nonumber  \\
 s^3 & = & {1 - \Omega_0 \over \Omega_0 }
\end{eqnarray}
\item Select galaxies (statusflag in [O,H,Z,F,B,D,L]) with
distance $ d < 100$ Mpc, and flux $F_{60\mu m} > 1.2$ Jy in the galaxy rest
frame. So the luminosity of a galaxy is given by:
\begin{eqnarray}
  L = 4\pi d^2 F_{60\mu m}
  \end{eqnarray}
  and the luminosity of a galaxy at the limiting distance (100 Mpc)
  with the limiting flux (1.2 Jy) is
  \begin{eqnarray}
  L_{limit} = 4\pi 100^2 1.2
  \end{eqnarray}
  We select all the galaxies with $L$ larger than $L_{limit}$.
\item Calculate the coordinates in a cube:
\begin{eqnarray}
 X  & = & d \cos(b) \cos(l) \nonumber \\
 Y  & = & d \cos(b) \sin(l) \nonumber \\
 Z  & = & d \sin(b)
\end{eqnarray}
\item Creates the catolog IRAS in the correct format (see program section).
\end{itemize}

Figure~\ref{fig_iras} shows the galaxies positions.
\begin{figure}[htb]
\centerline{
\hbox{
\psfig{figure=fig_iras.ps,bbllx=4.5cm,bblly=2.5cm,bburx=19cm,bbury=10cm,width=15cm,height=8cm,clip=}
}}
\caption{Aitoff equal-area projection in galactic coordinates of
  IRAS galaxies with $F_{60\mu m} > 1.2$ Jy and distance $<$
  100 Mpc. Their total number is 710.}
\label{fig_iras}
\end{figure}

The result for the redshift space correlation function for the
combined north+south IRAS catalog is presented on
fig.~\ref{fig_iras2}. The result is quite consistent with published
results for this catalog \cite{cf:fisher95}:
\begin{eqnarray}
r_0 = 4.27^{+0.66}_{-0.81} \mbox{ and } \gamma = 1.68^{+0.36}_{-0.29}
\end{eqnarray}

\begin{figure}[htb]
\centerline{
\hbox{
\psfig{figure=fig_iras_lin.ps,bbllx=2cm,bblly=1cm,bburx=18cm,bbury=17cm,width=8cm,height=8cm,clip=}
}}
\caption{Correlation function of the IRAS galaxies in linear bins with
  the corresponding linear least square fit for the data in separation
  range 1 -- 20 Mpc.}
\label{fig_iras2}
% \end{figure}

% \begin{figure}[hb]
\centerline{
\hbox{
\psfig{figure=fig_iras_log.ps,bbllx=2cm,bblly=1cm,bburx=18cm,bbury=17cm,width=8cm,height=8cm,clip=}
}}
\caption{Correlation function of the IRAS galaxies in logarithmic bins with
  the corresponding linear least square fit for the data in separation
  range 1 -- 20 Mpc.}
\label{fig_iras3}
\end{figure}
For comparison we present the correlation function for the same data
catalog but in logarithmic separation bins. As it is clear from
fig.~\ref{fig_iras3}, the strong fluctuations for the correlation
function for large separations is quite smoothed.

\subsubsection{Application to numerical simulations -- $\Lambda$CDM
  model}

For cosmological studies it is very important to test the predictions
of various cosmological models for the clustering properties of the
matter and to put constraints on various parameters by analyzing the
results from numerical simulations and their correspondence to what is
observed. Because in simulations we have all the parameter space of
the objects (coordinates, velocities, masses ...) it is a natural to
examine the clustering properties by means of various statistical
tools used in the analysis of the observational data: correlation
functions, power spectrum analysis, ...

We will present here the results for the correlation function for one
cosmological model ($\Lambda CDM,\ h = 0.7,\ \Omega_0 = 0.3,\
\Omega_\Lambda = 0.7$) from a Hubble volume simulation. The data
are available at the following address: \\
http://www.physics.lsa.umich.edu/hubble-volume \\

We have extracted a
volume limited slice with objects with redshift less than 0.4 (for the
cosmological model this corresponds to 1550 Mpc). The view of the data
is presented on fig.~\ref{fig_lcdm1} for XY plane and on
fig.~\ref{fig_lcdm2} for XZ plane. All the points represent groups or
clusters of galaxies with masses greater than $\sim 6.6 \times 10^{13}
M_{*}$.

\begin{figure}[htb]
\centerline{
\hbox{
\psfig{figure=fig_lcdm_xy.ps,bbllx=2cm,bblly=1cm,bburx=18cm,bbury=17cm,width=8cm,height=8cm,clip=}
}}
\caption{The XY plane view of the $\Lambda CDM$ slice used for the
  correlation function analysis. The opening angle is 45 deg. and the
  total number of objects is 6002.}
\label{fig_lcdm1}
\end{figure}

\begin{figure}[htb]
\centerline{
\hbox{
\psfig{figure=fig_lcdm_xz.ps,bbllx=2cm,bblly=1cm,bburx=18cm,bbury=17cm,width=8cm,height=8cm,clip=}
}}
\caption{The XZ plane view of the $\Lambda CDM$ slice.}
\label{fig_lcdm2}
\end{figure}

The results with the corresponding linear least squares fit are
presented on fig.~\ref{lcdm_fig3} for linear separation bins and on
fig.~\ref{lcdm_fig4} for logarithmic.

\begin{figure}[htb]
\centerline{
\hbox{
\psfig{figure=fig_lcdm_lin.ps,bbllx=2cm,bblly=1cm,bburx=18cm,bbury=17cm,width=8cm,height=8cm,clip=}
}}
\caption{The correlation function of $\Lambda CDM$ model for linear
  separation bins. The fit is done in 1--50 Mpc separations and the
  error bars are the standard deviations of 5 random catalog
  generations (the second method for estimating the uncertainty of the
  correlation function -- $\Delta_R$).}
\label{lcdm_fig3}
\end{figure}

\begin{figure}[htb]
\centerline{
\hbox{
\psfig{figure=fig_lcdm_log.ps,bbllx=2cm,bblly=1cm,bburx=18cm,bbury=17cm,width=8cm,height=8cm,clip=}
}}
\caption{Same as fig.~\ref{lcdm_fig3} but for logarithmic separation bins.}
\label{lcdm_fig4}
\end{figure}

The results are consistent with the normalization used in the
simulations -- the clustering properties of the simulation should
correspond to the observed clustering for redshift of 0 ($r_0 \approx
15,\ \gamma \approx 1.8$).

\clearpage
\newpage

\section{Program}

\subsection{Catalogue format}
The catalogue format is the following:
\begin{itemize}
\item the first line must contain the number of points $N$, the
  dimension $D$ (1,2, or 3), and the coordinate system $S$ ($S$ = 1 or
  2).  The recognized coordinate systems are:
  \begin{enumerate}
  \item $X$ and/or $Y$ and/or $Z$ Euclidien system.
  \item Angular coordinate system (longitude, latitude and/or
    distance; that could be the equatorial system -- right ascension
    $\alpha$, declination $\delta$, the galactic coordinate system
    with galactic longitude $l$, galactic latitude $b$, the
    supergalactic coordinate system with $SL$ and $SB$ etc.).
  \end{enumerate}
\item the $D$ following lines must contains three values: the range of
  variation of the $i-th$ coordinate (min,max) and a flag indicating
  the generation model for the corresponding coordinate: 0 -- uniform
  between [min,max], 1 -- bootstrapping the coordinate and 2 -- uniform
  on sphere between [min,max] in degrees. When the user have supplied
  its own generated random catalogs, then those three lines are
  ignored.
\item the $N$ following lines contains the coordinates of the points.
\end{itemize}

An example of a 3D catalogue, with 10 points in the Euclidien system,
each coordinate being defined in the interval $[0,100]$ and random
catalog coordinates uniform in [0,100] for each axis, is:
\begin{verbatim}
       10       3           1
       0      100.000       0
       0      100.000       0
       0      100.000       0
      42.1782      13.4610      73.7444
      41.6855      9.82727      75.3605
      42.3580      14.7867      73.1548
      42.0255      12.3347      74.2453
      42.7474      17.6581      71.8777
      41.9410      11.7113      74.5226
      65.5637      9.84036      71.3585
      65.7140      12.6019      70.5645
      65.5843      10.2196      71.2495
      65.4521      7.79074      71.9479
\end{verbatim}

\subsection{Random catalogue simulations}

There is one random catalog simulation incorporated inside the main
procedure and it is using the header information from the data
catalog. In that case the user must supply the min, max and type of
the corresponding coordinate generation, e.g. uniform from min,max
etc. as described in the previous section.

However, this simple case is not applicable for the real observed
catalogs, which in all cases are subject to selections and occupy
different volumes with complicated geometry. That's why it is quite
impossible to implement a dedicated procedure for this task. We have
implemented however a possibility for user to create his own set of
random catalogs and to feed them to the correlation analysis
procedure. The only required information for the random catalogs
(aside from the coordinates of the random points) should be given on
the first line: number of random points, number of dimensions and the
type of the coordinate system.

We givem as an examplem in the IDL routine section two such procedures
for the data presented in the report:

\subsection{two--point correlation function: cf\_ana}
Program {\em cf\_ana} estimates the two--point correlation function of
a 1D,2D, or a 3D data set between two points separations, {\em SepMin} and
{\em SepMax}, and with a given step (separation bin width). \\

The output file (fits format) contains a 2D array $T$, with:
\begin{itemize}
\item $T(*,0) = $ distance
\item $T(*,1) = $ two--point correlation function using the standard
  method.
\item $T(*,2) = $ Poisson error (eq.~\ref{eq_pois}).
\item $T(*,3) = $ standard deviation error (eq.~\ref{eq_std}).
\item $T(*,4) = $ bootstrap error (eq.~\ref{eq_boot}).
\end{itemize}
The bootstrap catalogs are created and bootstrap errors are calculated
only if the number of realization is larger or equal than 20.  If the
"-A" option is set, all estimators are used and the second dimension
of $T$ is 17 instead of 5. Data from $T(*,1)$ to $T(*,4)$ concern the
first method (standard one), $T(*,5)$ to $T(*,8)$ the second
(Davis-Peebles one), $T(*,9)$ to $T(*,12)$ the third, and $T(*,13)$ to
$T(*,16)$ the last one (Landy-Szalay).

By default, random catalogues are calculated, but they can be read
from the disk using the "-r {\em Prefix\_FileName}" option.  In this
case, files must have the correct names, {\em PREFIX\_rnd\_i.dat},
where is $i$ the simulation number.  This option has the advantage to
allows the user to use its own random catalog simulations.

\begin{center}
  USAGE: cf\_ana options catalog.dat cf.fits
\end{center}
where options are
\begin{itemize}
\item {\bf [-I InitRandomVal]} \\
  Value used for random value generator initialization. \\
  Default is 100.
\item {\bf [-n NbrRnd]} \\
  Number of random points used in the random realization.  Default is
  the number of data points.
\item {\bf [-g NbrSimu]} \\
  Number of realizations used to calculate the random error
  and the bootstrap error. \\
  Default is 20.
\item {\bf [-L]} \\
  Use logarithmic steps. Default is no.
\item {\bf [-s Step]} \\
  Pair separations bin size. Default is 1.
\item {\bf [-m SepMin]}  \\
  Pair separations min. Must be set.
\item {\bf [-M SepMax]}  \\
  Pair separations max. Must be set.
\item {\bf [-C CF\_Method]} \\
  Two-points correlation function calculation method
\begin{enumerate}
\item Standard method (eq.\ref{std_method})
\item Davis-Peebles method (eq.\ref{dp_method})
\item Hamilton method (eq.\ref{ham_method})
\item Landy-Szalay method (eq.\ref{ls_method})
\end{enumerate}
Default is Landy-Szalay method.
\item {\bf  [-r Prefix\_FileName]} \\
 Read from the disk the simulated random catalogue files.
 Default is no.
\item {\bf [-w prefix\_file\_name]} \\
  Write to the disk intermediate files. It is mainly for
  cross-checking and debugging. In addition to the random and
  bootstrap catalogues, five files are written:
\begin{enumerate}
\item prefix\_cf\_data\_data.fits: contains the 1D $DD$ data set, the number
  of pairs in the data catalog in each bin.
\item prefix\_cf\_rnd\_rnd.fits: contains the 2D $RR$ data set, the number of
  pairs for each realization in the random catalogue.
\item prefix\_cf\_data\_rnd.fits: contains the 2D $DR$ data set, the number of
  pairs for each realization of the random catalogue between the data
  and random points.
\item prefix\_cf\_boot\_boot.fits: contains the 2D $DD$ data set, the number
  of pairs for each realization in the bootstrap catalogue.
\item prefix\_cf\_boot\_rnd.fits: contains the 2D $DR$ data set, the number
  of pairs for each realization of the random catalogue between the
  bootstrap and the random catalogue.
\end{enumerate}
Default is no writing.
\item {\bf [-A]} \\
Apply all methods. The two point--correlation function is calculated
for all four methods.
 \item {\bf [-v]} \\
Verbose
\end{itemize}
Examples:
\begin{itemize}
\item {\tt cf\_ana -v -g 5 -s 0.5 -m 0 -M 10 -n 10000 -C 2 input.dat
    result.fits}\\ Calculates the two--point correlation function of
  the input data, with number of random points equal to $10^4$ using
  Davis-Peebles estimator, for distance between 0 and 10, with a bin
  size equal to 0.5 and 5 generations of random catalogs generated by
  the supplied model for each coordinate generation in the input.dat 4
  header lines.
\item {\tt cf\_ana -g 5 -v -s 0.5 -m 0 -M 10 -n 10000 -A -r random
    input.dat result.fits}\\ Ditto, but all estimators are calculated
  and the random catalogs named random\_rnd\_0.fits \dots
  random\_rnd\_5.fits (generated by the user) are read from disk.
\end{itemize}

\subsection{IDL routines}

\subsubsection{IDL Cox Process routine: cox\_data}
Program {\em cox\_data} creates a Cox process.
\begin{center}
     USAGE:  COX\_DATA, length=length, np=np, nseg=nseg, lcube=lcube,x, y, z,
randval=rndval, file=file
\end{center}
where
\begin{itemize}
\item {\em length} = length of the segments. Default is 10.
\item {\em np } = number of points per segment. Default is 6.
\item {\em nseg} = number of segments. Default is 1000.
\item {\em lcube } = the length of the cube volume. Default is 100.
\item {\em file } = file name. If set, the data are printed in a ascii
  file
\item {\em randval } = parameter for the random value generator.
\item {\em X,Y,Z} = output 1D vector of the same size containing the
  coqordinate values of the points.
\end{itemize}

\subsubsection{IDL Cox plot routine: plot\_cox}
Program {\em plot\_cox} plots the result of the two point correlation
function analysis of a Cox process. If input parameter is not given,
this routine just plots the COX process.
\begin{center}
PLOT\_COX, Result, method=method, err=err
\end{center}
where
\begin{itemize}
\item {\em method }= int: if the -A option was used when running cf\_ana,
several methods are available for estimation the two points correlation function:
\begin{enumerate}
\item Standard method ($DD/RR-1$)
\item Davis-Peebles method ($DD/DR-1$)
\item Hamilton method ($DD*RR/(DR^2) - 1$)
\item Landy-Szalay method ($DD/RR - DR/(2RR)$)
\end{enumerate}
Default is 1.

\item {\em err }= int: For each method the error is calculated by different
ways:
\begin{enumerate}
\item Poisson error.
\item From the standard deviation.
\item From the bootstrap bias-corrected interval.
\end{enumerate}
Default is 1.
\end{itemize}

\subsubsection{IDL 3D plot routine: plot\_xyz}
Program {\em plot\_xyz} plots a set of points in a cube.  If the
filename keyword is specified, the data are plotted in a postcript
file.z=0 is at the bottom of the cube.
\begin{center}
  USAGE: PLOT\_XYZ, X,Y,Z, col=col, filename=filename, land=lan
\end{center}
where
\begin{itemize}
\item {\em X,Y,Z} = input 1D vector of the same size containing the
  coordinate values of the points.
\item {\em  col } =  color value of the axes. Default is no color.
\item {\em filename} = if set, the plot is printed in a postcript
  file.
\item {\em land }= int: if set, and filename is set, the lanscape
  mode is activated.
\end{itemize}

\subsubsection{IDL correlation function plot routine: plot\_cf}

Program {\em plot\_cf} plots the result of the two point correlation
function analysis (see program {em cf\_ana}).

\begin{center}
PLOT\_CF, Result, method=method, err=err, last=last, XR=XR, YR=YR
\end{center}
where
\begin{itemize}
\item {\em method }= int: if the -A option was used when running cf\_ana,
several methods are available for estimation the two points correlation function:
\begin{enumerate}
\item Standard method ($DD/RR-1$)
\item Davis-Peebles method ($DD/DR-1$)
\item Hamilton method ($DD*RR/(DR^2) - 1$)
\item Landy-Szalay method ($DD/RR - DR/(2RR)$)
\end{enumerate}
Default is 1.

\item {\em err }= int: For each method the error is calculated by different
ways:
\begin{enumerate}
\item Poisson error
\item From the standard deviation.
\item From the bootstrap bias-corrected interval.
\end{enumerate}
Default is 1.
\item {\em last }= int: Do not plot the last N points.
\item {\em XR }= int[2]: Xrange. Default is  $[0.1, 100]$
\item {\em YR }= int[2]: Yrange. Default is  $[0.01, 100]$
\end{itemize}

\subsubsection{IDL luminosity distance calculation routine: ldist}
Program {\em ldist}  calculates the luminosity distance
from any given redshift for any
cosmological model with $H_0$ and  $\Omega_0$
(Source: Ue-Li Pen, astro-ph/9904172).
\begin{center}
    Result = LDIST(z, omega0=omega0, h0=h0)
\end{center}
where
\begin{itemize}
\item {\em  omega0 }= float: $\Omega_0$ value. Default is 1.
\item {\em  h0}= float: $H_0$ value  Default is 100.
\end{itemize}

\subsubsection{IRAS random catalog creation}
Program {\em iras\_random} creates random
catalogs for the IRAS 1.2 Jy survey. It creates in the current directory
{\em ngen} number of files named "prfx\_rnd\_\#\.dat", each one containing
one random realization with one header line describing the number of points,
the dimensions and the coordinate system type.
\begin{center}
    iras\_random,input\_catalog,nran=nran,ngen=ngen,ver=ver,prfx=prfx,seed=seed,boot=boot
\end{center}
\begin{itemize}
\item {\em  input\_catalog }= string: the name of the IRAS 1.2Jy catalog with the
                       required 4 header lines. The last 3 ignored for
                       this particular case.
\item {\em  nran }= int: the number of random points. If not set, then it is
              equal to the number of data points in the input catalog.
\item {\em  ngen }= int: the number of random catalog generations. Default to
              10.
\item {\em  ver}= int: which version of random catalog creation:
\begin{itemize}
\item {ver=1} - IRAS 1.2 Jy north
\item {ver=2} - IRAS 1.2 Jy south
\item {ver=3} - IRAS 1.2 Jy north+south.
\end{itemize}
The default is ver=3.
\item {\em  prfx}= string: the prefix of the files created. The full name
will be "prfx\_rnd\_\#\.dat", where \# is the generation number. The
default prefix is "random".
\item {\em  seed }= int:  the random seed.
\end{itemize}

\subsubsection{$\Lambda$CDM random catalog creation}
Program {\em lcdm\_random} creates random catalogs
for the LCDM numerical simulation.
It creates in the current directory
{\em ngen} number of files named "prfx\_rnd\_\#\.dat", each one containing
one random realization with one header line describing the number of points,
the dimensions and the coordinate system type.

\begin{center}
    lcdm\_random,input\_catalog,nran=nran,ngen=ngen,prfx=prfx,seed=seed
\end{center}
\begin{itemize}
\item {\em  input\_catalog }= string: the name of the LCDM simulation data
                       with the required 4 header lines. The last 3 ignored
		       for this particular case.
\item {\em  nran }= int: the number of random points. If not set, then it is
              equal to the number of data points in the input catalog.
\item {\em  ngen }= int: the number of random catalog generations. Default to
              10.
 \item {\em  prfx}= string: the prefix of the files created. The full name
will be "prfx\_rnd\_\#\.dat", where \# is the generation number. The
default prefix is "random".
\item {\em  seed }= int:  the random seed.
\end{itemize}


\documentclass{memoir}
\usepackage{notestemplate}

%\logo{./resources/pdf/logo.pdf}
%\institute{Rice University}
%\faculty{Faculty of Whatever Sciences}
%\department{Department of Mathematics}
%\title{Class Notes}
%\subtitle{Based on MATH xxx}
%\author{\textit{Author}\\Gabriel \textsc{Gress}}
%\supervisor{Linus \textsc{Torvalds}}
%\context{Well, I was bored...}
%\date{\today}

\begin{document}

% \maketitle

% Notes taken on 02/08/21

\chapter{Hausdorff and Packing Measures and Dimensions}
\label{cha:hausdorff_and_packing_measures_and_dimensions}

\begin{defn}
	Let \(F\) be a subset of \(\R^{n}\) and \(s\geq 0\). For each \(\delta>0\), define
	\begin{align*}
		\mathcal{H}^{s}_{\delta}(F) = \inf \left\{\sum_{i=1}^{\infty} \left| U_i \right|^{s} \mid \left\{ U_i \right\} \text{ is a \(\delta\)-cover of \(F\)} \right\} .
	\end{align*}
The Hausdorff dimension looks at all covers of \(F\) of a certain dimension, and minimizes the \(s\)-th power of the diameters of the covering set. Notice that as \(\delta\) decreases, the class of permissible covers in \(F\) is reduced, and so the infimum increases. This gives us
\begin{align*}
	\mathcal{H}^{s}(F) = \lim_{\delta \to 0} \mathcal{H}^{s}_{\delta}(F)
\end{align*}
which we define the \textbf{\(s\)-dimensional Hausdorff measure of \(F\)}. This limit exists for any subset \(F\), but it can and will usually be \(0\) or \(\infty\).
\end{defn}
In fact, \(\mathcal{H}^{s}\) is a measure. Hausdorff measure generlizes the typical ideas of length, area, volumne, and in fact for subsets of \(\R^{n}\), \(n\)-dimensional Hausdorff measure is within a constant multiple of \(n\)-dimensional Lebesgue measure. In particular, if \(F\) is a Borel subset of \(\R^{n}\), then
\begin{align*}
	\mathcal{H}^{n}(F) = c^{-1}_n \textrm{vol}^{n}(F)
\end{align*}
where \(c_n\) is the volume of an \(n\)-dimensional ball of diameter \(1\).

\begin{prop}
	Let \(F\subset \R^{n}\) and \(f:F\to \R^{m}\) be a Holder mapping-- that is, it satisfies
	\begin{align*}
		\left| f(x) - f(y) \right| \leq c \left| x-y \right|^{\alpha} \quad \forall x,y \in F
	\end{align*}
	for constants \(\alpha > 0\) and \(c > 0\). Then for each \(s\),
	\begin{align*}
		\mathcal{H}^{s / \alpha}(f(F)) \leq c^{s / a}\mathcal{H}^{s}(F).
	\end{align*}
	In particular, if \(f\) is a Lipschitz mapping, then
	\begin{align*}
		\mathcal{H}^{s}(f(F)) \leq c^{s}\mathcal{H}^{s}(F).
	\end{align*}
\end{prop}

\begin{prop}[Scaling Property]
	Let \(f:\R^{n}\to \R^{n}\) be a similarity transformation of scale factor \(\lambda>0\). If \(F\subset \R^{n}\), then
	\begin{align*}
		\mathcal{H}^{s}(f(F)) = \lambda^{s}\mathcal{H}^{s}(F).
	\end{align*}
\end{prop}

\section{Hausdorff Dimension}
\label{sec:hausdorff_dimension}

Using the robustness of the Hausdorff dimension, we can better construct a definition of dimension.\\

Observe that for \(\delta<1\), \(\mathcal{H}^{s}_{\delta}(F)\) is non-increasing with \(s\). In particular, for \(t>s\)
 \begin{align*}
	 \mathcal{H}^{t}_\delta(F) \leq \delta^{t-s}\mathcal{H}^{s}_{\delta}(F).
\end{align*}
This seems to imply that there is some critical value of \(s\) at which \(\mathcal{H}^{s}(F)\) jumps from \(\infty\) to \(0\). This critical value is what we call the Hausdorff dimension.

\begin{defn}
	Let \(F \subset \R^{n}\). Then the \textbf{Hausdorff dimension} of \(F\) is
	\begin{align*}
		\textrm{dim}_H F := \inf \left\{s \geq 0 \mid \mathcal{H}^{s}(F) = 0 \right\} = \sup \left\{s \mid \mathcal{H}^{s}(F) = \infty \right\} .
	\end{align*}
\end{defn}
This immediately gives
\begin{align*}
	\mathcal{H}^{s}(F) = \begin{cases}
		\infty & 0\leq s< \textrm{dim}_H F\\
		0 & s> \textrm{dim}_H F
	\end{cases}
\end{align*}
Note that for \(s =  \textrm{dim}_H F\), \(\mathcal{H}^{s}(F)\) can be zero, infinite, or finite. A Borel set that \(\mathcal{H}^{s}\) as finite is called an \(s\)-set.\\

Fortunately, \(\mathcal{H}^{s}\) satisfies many of the same properties as the box-counting dimension. Furthermore, it satisfies the Holder condition exactly as expected:
\begin{prop}
	Let \(F\subset \R^{n}\) and suppose that \(f:F\to \R^{m}\) satisfies the Holder condition
	\begin{align*}
		\left| f(x)-f(y) \right| \leq c \left| x-y \right|^{\alpha} \quad \forall x,y \in F.
	\end{align*}
	Then \( \textrm{dim}_H f(F) \leq (1 / \alpha) \textrm{dim}_H F\). If \(f\) is instead bi-Lipschitz, then we have equality instead.
\end{prop}

There is also a clear relationship between Hausdorff dimension and box-counting dimension.
\begin{prop}
	For every non-empty bounded \(F\subset \R^{n}\),
	\begin{align*}
		\textrm{dim}_H F \leq \underline{ \textrm{dim}}_B F \leq \overline{ \textrm{dim}}_B F.
	\end{align*}
\end{prop}
Note that so far, bi-Lipschitz mappings preserve all our notions of dimension. So similar to homeomorphisms, one can regard two sets as equivalent if there is a bi-Lipschitz mapping between them. This allows us to begin distinguishing topological properties from dimension.
\begin{prop}
	Every set \(F\subset \R^{n}\) with \( \textrm{dim}_H F < 1\) is totally disconnected.
\end{prop}
\begin{proof}
	Let \(x\) and \(y\) be distinct points of \(F\). We define a mapping \(f(z) = \left| z-x \right| \). The reverse triangle inequality gives us
	\begin{align*}
		\left| f(z) - f(w) \right| \leq \left| z-w \right| ,
	\end{align*}
	so that \(f\) is Lipschitz and so \( \textrm{dim}_H f(F) < 1\). This implies that \(f(F)\) is a subset of \(\R\) of \(\mathcal{H}^{1}\)-measure zero-- which implies it has a dense complement. Choosing \(r\) with \(r \not\in f(F)\) and \(0<r<f(y)\), it follows that
	\begin{align*}
		F = \left\{z \in F \mid \left| z-x \right| <r \right\} \cup \left\{z \in F \mid \left| z-x \right| >r \right\} .
	\end{align*}
	That is, \(F\) is contained in two disjoint open sets with \(x\) in one set and \(y\) in the other-- and so \(x,y\) lie in different connected components of \(F\).
\end{proof}

%% Section on computing examples

\begin{exmp}[Middle third Cantor set]
	The Cantor set \(F\) splits into a left part \(F_L=F \cap \left[ 0,\frac{1}{3} \right] \) and a right part \(F_R = F \cap \left[ \frac{2}{3},1 \right] \). Both parts are geometrically similar to \(F\) but simply scaled by a ratio of \(\frac{1}{3}\). Furthermore, \(F = F_L \sqcup F_R\). Thus, for any \(s\),
	\begin{align*}
		\mathcal{H}^{s}(F) = \mathcal{H}^{s}(F_L) + \mathcal{H}^{s}(F_R) = \left( \frac{1}{3} \right)^{s}\mathcal{H}^{s}(F) + \left( \frac{1}{3} \right)^{s}\mathcal{H}^{s}(F)
	\end{align*}
	by the scaling property of Hausdorff measures. Assuming that at the critical value \(s = \textrm{dim}_H F\), we have that the Hausdorff measure is finite (a nontrivial assumption), then we can divide both sides by \(\mathcal{H}^{s}(F)\) to get \(1 = 2\left( \frac{1}{3} \right)^{s}\) which then gives \(s = \log 2 / \log 3\).
\end{exmp}
A more rigorous approach can be shown to calculate this value, but this heuristic is particularly useful for self-similar sets.

%% Section on ball measures, net measure, that are equivalent

\section{Equivalent definitions of Hausdorff dimension}
\label{sec:equivalent_definitions_of_hausdorff_dimension}

It is useful to have equivalent definitions, as some definitions will be easier to compute for certain classes of sets. One simple variation is done via covering by spherical balls: let
\begin{align*}
	\mathcal{B}^{s}_{\delta}(F) = \inf \left\{\sum_{i} \left| B_i \right|^{s} \mid \left\{ B_i \right\} \text{ is a \(\delta\)-cover of \(F\) by balls} \right\}
\end{align*}
and consider the measure \(\mathcal{B}^{s}(F) = \lim_{\delta \to 0} \mathcal{B}^{s}_\delta(F)\). Once again, we obtain a dimension when \(\mathcal{B}^{s}(F)\) jumps from \(\infty\) to zero. One can verify that this bounds the Hausdorff measure on both sides by a constant, and so the value of \(s\) where the jumps occur must be the same.\\

Of course, we can further restrict by using covers by only open sets, or closed sets. If \(F\) is compact, we can even consider finite subcovers of open covers.\\

One important variant is the net measure. For now, consider the cases when \(F\) is a subset of \([0,1]\). Recall that a binary interval is an interval of the form \([r_2^{-k},(r+1)2^{-k}]\) where \(k = 0,1,\ldots\) and \(r = 0,1,\ldots,2^{k}-1\). Then
\begin{align*}
	\mathcal{M}^{s}_{\delta}(F) = \inf \left\{ \sum \left| U_i \right|^{s} \mid \left\{ U_i \right\} \text{ is a \(\delta\)-cover of \(F\) by binary intervals} \right\}
\end{align*}
which leads to the net measures
\begin{align*}
	\mathcal{M}^{s}(F) = \lim_{\delta \to 0} \mathcal{M}^{s}_\delta (F).
\end{align*}
This form can be more convenient, as two binary intervals are either disjoint or contained in one another, allowing any cover of a set by binary intervals to become a cover by disjoint binary intervals.n

%% Section on packing measure, which is a measure correlated with the modified upper box-counting dimension

\section{Packing Measure}
\label{sec:packing_measure}

For \(s\geq \) and \(\delta>0\), we define
\begin{align*}
	\mathcal{P}^{s}_\delta(F) = \sup \left\{\sum_{i=1}^{\infty} \left| B_i \right|^{s} \mid \left\{ B_i \right\} \text{ is a collection of disjoint balls of radii at most \(\delta\) with centers in \(F\)} \right\} .
\end{align*}
The limit
\begin{align*}
	\mathcal{P}^{s}_0(F) = \lim_{\delta \to 0} \mathcal{P}^{s}_\delta(F)
\end{align*}
exists. However, it is not a measure-- so we modify the definition by decomposing \(F\) into a countable collection of sets and define
\begin{align*}
	\mathcal{P}^{s}(F) = \inf \left\{\sum_{i=1}^{\infty} \mathcal{P}^{s}_0(F_i) \mid F\subset \bigcup_{i=1}^{\infty}F_i \right\}
\end{align*}
This is now a measure on \(\R^{n}\) known as the \(s\)-dimensional packing measure. Similarly, the packing dimension is the jump value given by
\begin{align*}
	\textrm{dim}_P F = \sup \left\{s\geq 0 \mid \mathcal{P}^{s}(F) = \infty \right\} = \inf \left\{s \mid \mathcal{P}^{s}(F) = 0 \right\} .
\end{align*}
In fact, this definition is the same as the modified upper box dimension.

\begin{lemma}
	For \(F\) a non-empty bounded subset of \(\R^{n}\),
	\begin{align*}
		\textrm{dim}_P F \leq \overline{ \textrm{dim}_B}F.
	\end{align*}
\end{lemma}
And hence
\begin{prop}
	If \(F\subset \R^{n}\), then \(\textrm{dim}_PF = \overline{\textrm{dim}_{MB}}F\).
\end{prop}
This gives us the relations
\begin{align*}
	\textrm{dim}_H F \leq \underline{\textrm{dim}_{MB}}F \leq \overline{\textrm{dim}}_{MB}F = \textrm{dim}_P F \leq \overline{\textrm{dim}}_B F
\end{align*}
This connection greatly opens the options in computing the geometry of fractals, however it is difficult to calculate. The following corollary strengthens the connection between the modified box dimension and the packing dimension.

\begin{cor}
	Let \(F\subset \R^{n}\) be compact and assume that
	\begin{align*}
		\overline{\textrm{dim}}_B(F\cap V) = \overline{\textrm{dim}}_B F
	\end{align*}
	for all open sets \(V\) that intersect \(F\). Then \(\textrm{dim}_P F = \overline{\textrm{dim}}_BF\).\\

	If \(F\subset \R^{n}\) is of second category, then \(\textrm{dim}_P F = n\). That is, this holds if \(F\) is or contains a dense \(G_\delta\) set.
\end{cor}

%% Gauge function

%% Dimension prints??

%% Porosity

\end{document}


\chapter*{Abstract}             % ne pas numéroter
\label{chap:abstract}           % étiquette pour renvois
\phantomsection\addcontentsline{toc}{chapter}{\nameref{chap:abstract}} % inclure dans TdM

\begin{otherlanguage*}{english}
This thesis discusses the use of bandit methods to solve
the problem of training extractive abstract generation models.
The extractive models, which build summaries by selecting sentences from an
original document, are difficult to train because the target summary of a document is usually not built in an extractive way.
It is for this purpose that we propose to see the production of extractive summaries
as different bandit problems, for which there exist algorithms that can be leveraged for training summarization models.

In this paper, BanditSum is first presented, an approach drawn from
the literature that sees the generation of the summaries
of a set of documents as a contextual bandit problem.
Next, we introduce CombiSum, a new algorithm
which formulates the generation of the summary of a
single document as a combinatorial bandit.
By exploiting the combinatorial formulation,
CombiSum manages to incorporate the notion of the extractive potential
of each sentence of a document in its training.
Finally, we propose LinCombiSum, the linear variant of CombiSum
which exploits the similarities between sentences in a document
and uses the linear combinatorial bandit formulation instead.

\end{otherlanguage*}


Constituents are referred to any chemical compound or a group of chemical compounds with assumed effective transport parameters that can present in aqueous phase or be sorbed to soil matrix or particles. In addition some biological agents such as bacteria or algae can also be treated as constituents. There is no pre-defined constituents in GIFMod and the user should introduce them and assign transformation processes to them. In this section the governing equations and different processes that can be assigned to constituents in GIFMod will be described. The general mass balance equation for fate and transport of constituents in GIFMod is:
\begin{equation}
\label{eq:26}
\begin{split}
\frac{d\Gamma_{i,p,l} C_{p,l,i,k}}{dt} =\\ \beta_{p,l} \sum_{j=1}^{nj} pos \big(Q_{ij}+(v_{s,p,ij}+v_{c,k,ij})A_{ij}\big)\tilde G_{p,l,j}C_{p,l,j,k} \\ -\beta_{p,l} \sum_{j=1}^{nj} pos \big(-Q_{ij}-(v_{s,p,ij}+v_{c,p,ij})A_{ij}\big)\tilde G_{p,l,j}C_{p,l,j,k}\bigg]\\
-S_i \big(\sum_{l'=1}^{nl_p}\textbf{K}_{p,l,l'}\tilde G_{p,l,i}C_{p,l,i,k}-\sum_{l'=1}^{nl_p}\textbf{K}_{p,l,l'}\tilde G_{p,l',i}C_{p,l',i,k}\big)\\
+ \beta_{p,l} \sum_{j=1}^{nj} A_{ij}\frac{D_{p,ij,k}}{d_{ij}}(\tilde G_{p,l,j}C_{p,l,j,k}-\tilde G_{p,l,i}C_{p,l,i,k}) \\
+ S_i \sum_{p=-1}^{np} \sum_{l'=1}^{nl_p}\kappa_{k,p,p'}\bigg(\frac{C_{p',l',i,k}}{\phi_{k,p'}}-\frac{C_{p,l,i,k}}{\phi_{k,p}}\bigg)  \\ +S_i \sum_{r=1}^{nr} \psi_{r,k}R_r + S_i \xi_{p,l,i,k} \\
+ \sum_j^{ns} pos(Q_{s,j} \tilde G_{p,l,j,in} C_{p,l,j,k,in}) - \sum_j^{ns} pos(-\omega_{p,l,j} Q_{s,j} \tilde G_{p,l,j,in} C_{p,l,j,k,in}) + \dot{m}_{i,p,l,k}
\end{split}
\end{equation}
In Eq. \ref{eq:26}, the first two terms of the right hand side represent dissolved and particle-bound advective transport due to flux and settling, the third term is the mass exchange of constituents between phases due to exchange of particles, the forth term is dispersion due to the dispersion due to both dispersion of particle-bound and dissolved constituents, the fifth term is the mass exchange through adsorption and desroption, the six term represents biogeochemical transformation, the seventh term is external flux (such as aeration), and eight and night terms are respectively sources or sinks due to inflow and outflow or plant uptake. Subscript $p=-1$ represent the solid matrix and $p=0$ represent the aqueous phase while a $p>0$ refer to the particle class. $\tilde G_{p,l,j}$ is the same as $G_{p,l,j}$ in Eq. \ref{eq:20} for $p>0$, is equal to $1$ for $p=0$ (dissolved species) and equal to bulk density, $\rho_i$ for $p=-1$ (soil matrix). Subscript $in$ indicate the values in the inflow. Also in this equation $D_{p,ij,k}$ is the dispersion/diffusion coefficient for particles when $p>0$ (particles) and constituent's dispersion/diffusion coefficient when $p=0$ (dissolved species). Also Sorption capacity, $\phi_{k,p}$, is equal to partitioning coefficient $K_D$ for soil and particles ($p=-1$ and $p>0$ respectively) and equal to 1 for dissolved species ($p=0$).

\subsection{Constituent properties}
In this section the properties of constituents are described. To  add a new constituent right-click on \textbf{Project Explorer}$\rightarrow$\textbf{Water Quality}$\rightarrow$\textbf{Constituents} and click on \textbf{Add Constituent}. \\
Below the properties of constituents are described.
\begin{itemize}
\item \textbf{Name: } This is the name of the constituent. Names of constituents should be unique. Constituent names will be used in producing outputs and also when entering the reaction network.
\item \textbf{Diffusion coefficient: } This specifies the molecular diffusion coefficient of the constituent. When calculating the mechanical dispersion, this value will be added to the dispersion coefficient calculated based on the dispersivity value entered for each connector.
\item \textbf{Exchange rate factor: } This bring a window where the user can enter the solid-aqueous phase rate $\kappa_{k,p,p'}$ in Eq. \ref{eq:26} and partitioning coefficient $K_D$ with respect to soil matrix and each particle class.
\item \textbf{Partitioning coefficient: } This bring a window where the user can enter the solid-aqueous phase rate $\kappa_{k,p,p'}$ in Eq. \ref{eq:26} and partitioning coefficient $K_D$ with respect to soil matrix and each particle class.
\item \textbf{Settling velocity: } The settling velocity of the constituent, $v_c$.
\end{itemize}

\subsection{Reactions}
In order to define reactions two steps are needed. First some reaction parameters will be defined that can represent reaction rate constants, half-saturation coefficients, stoichiometric constants and other parameters needed in defining the reaction process. It shoule be noted that a user can define reactions by explicitly entering parameter values into reaction expressions however this approach is not advised. The second step is to enter reaction rate expressions and stoichiometric constants into a Petersen matrix \citep{russell2006}.

\textit{Reactions Parameters: }\\
To add a reaction parameter right-click on \textbf{Project Explorer}$\rightarrow$\textbf{Water Quality}$\rightarrow$\textbf{Reactions}$\rightarrow$\textbf{Reaction Parameters} and click on \textbf{Add Reaction Parameter} from the drop down menu. Select the reaction parameter that was added to change its properties.
\begin{itemize}
\item \textbf{Name: } Name of the reaction parameter to be used in defining reaction expressions.
\item \textbf{Temperature correction factor: } Specifies the dependency of the value of the reaction rate parameter to temperature. Under variable temperature condition the value of the reaction parameter entered in the \textbf{Value} field represent the value of the parameter in $20^oC$. The value at other temperatures is calculated as:
\begin{equation}
\label{eq:27}
k_T = k_{20} \Theta^{T-20}
\end{equation}
\item \textbf{Value: } The value of the parameter. Please note that the unit used for the parameter value should be consistent with other units used in the model. The time dimension of the value is always days.
\end{itemize}
\textit{Reactions: }\\
In order to enter reaction rate expressions and stoichiometric constants right-click on \textbf{Project Explorer}$\rightarrow$\textbf{Water Quality}$\rightarrow$\textbf{Reactions}$\rightarrow$\textbf{Reaction Parameters} and click on \textbf{Open Reaction Network Window} from the drop down menu. A window as shown in Figure \ref{fig:20}. The headings of this table consists of a process name, a process rate and columns each representing the stoichiometric constants for each of the constituents defined in the model. Additional processes (reactions) can be added using the \textbf{Add Processes} at the bottom of the window and existing processes can be removed using the \textbf{Remove Process} bottom. \textbf{Process Name} is were the user-assigned name of the process is entered. In the process rate column the user can enter the rate expression of the process. The rate expression can include concentrations of constituents, reaction parameters and also physical parameters such as light, temperature or even velocity. The values entered under the columns identified by name of constituents indicate how much of a constituent is produced or consumed as a result of a unit progress in the reaction. A negative stoichiometric constant is indicative of consumption of the constituent as a result of the reaction while a positive value results in production of the constituent. The following example shows how to set up a simple reaction in GIFMod.
\begin{figure}[!ht]\label{fig:20}
\begin{center}
\includegraphics[width=8cm]{Images/Figure20.png} \\
\caption{Reaction window}
\end{center}
\end{figure}

\input{ASM_ex.tex}


\documentclass{article}
\usepackage[margin=8em]{geometry}
\usepackage{algorithm}
\usepackage{algorithmicx}
\usepackage{algpseudocode}
\usepackage{tikz}
\usepackage{tikz-qtree}
\usepackage{hyperref}
\setlength{\parskip}{\baselineskip}
\title{The Knapsack Problem \\ \small \textit{A Survey of Solution Approaches}}
\date{\small \today}
\author{Sayak Biswas \\ \small UNIVERSITY \textit{of} \textbf{FLORIDA} \\ \small UFID: 54584911}
\begin{document}
\pagenumbering{gobble}
\maketitle
\begin{abstract}
This paper surveys existing literature for different approaches to solve the knapsack problem. The Knapsack Problem is a combinatorial optimization problem in which one has to maximize the profits gained by packing a set of objects in a knapsack without exceeding its capacity. The problem is $\mathcal{NP}$-hard, thus there is no known polynomial time algorithm for a large input.

Specifically, we take a look at the \textit{0-1 Knapsack Problem} and provide a qualitative comparison between the two well-known approaches towards solving the problem: dynamic programming and backtracking algorithms.
\end{abstract}
\newpage

\pagenumbering{arabic}

\section{Introduction}
The \textit{Knapsack Problem} is an optimization problem, which at a high level is to choose the most profitable subset from a collection of available items without overloading the knapsack. The problem is formally defined as follows:

Given a knapsack of maximum capacity \textit{C} and \textit{n} items each weighing \textit{$w_{i}$} and with an associated profit of \textit{$p_{i}$}, the \textit{Knapsack Problem} is to choose a subset of the items such to maximize $\sum_{i=1}^{n}\textit{$p_{i}x_{i}$}$ on the condition $\sum_{i=1}^{n}\textit{$w_{i}x_{i}$} \leq \textit{C}, \textit{i} = 1,...,\textit{n}$ where \textit{$x_{i}$} is the number of copies of each item.

%\iffalse
The \textit{fractional} knapsack problem allows placing a fraction \textit{$x_{i}$} of object \textit{i} into the knapsack \textit{i.e.} $0 \le \textit{$x_{i}$} \le 1$.

The \textit{bounded} knapsack problem restricts each item type to an integer amount of copies \textit{i.e.} \textit{$x_{i}$} $\in \{0,...,m_{i}\}$

The \textit{unbounded} knapsack problem removes any restriction from the number of copies of each object type \textit{i.e.} \textit{$x_{i}$} $\ge$ 0.
%\fi

The \textit{0-1} knapsack problem restricts the copy count to either zero or one, meaning the object is either included in the knapsack or not, \textit{i.e.} \textit{$x_{i}$} $\in$ \{0, 1\}.

\section{Algorithms}
A na\"{\i}ve brute force approach would be to consider all $2^{n}$ possible combinations of items for the knapsack and choose the one that yields te maximum profit. Such an approach would lead to exponential complexity and hence is not desirable.
\subsection{Dynamic Programming}
Dynamic programming solves optimization problems by breaking it into smaller subproblems and then solving those subproblems to find the overall solution. To solve a problem using dynamic programming, it should have two important characteristics:
\begin{itemize}
	\item \textit{Optimal Substructure}: This means that the overall optimal solution to a problem comprises optimal solutions to the subproblems.
	\item \textit{Overlapping Subproblems}: This means that any algorithm used to solve the problem should be solving a subset of the subproblems over and over again instead of generating new subproblems. Dynamic programming stores the results of these subproblems and uses them whenever the subproblem is encountered again. This is called \textit{memoization}.
\end{itemize}
In this approach, we first define a function \textit{knap(1, n, C)} which finds the optimal solution, $f_{n}(C)$ for a knapsack of capacity \textit{C} using objects from \textit{1} to \textit{n}. We divide this into subproblems denoted by \textit{knap(1, j, y)} which finds the optimal solution for a knapsack of capacity \textit{y} using objects from \textit{1} to \textit{j}. Let the solution to this be defined by $f_{j}(y)$.

At any point in the problem state, the solution depends on making a decision on whether to use the current object or not. So, we obtain the top-down recurrence relation

\begin{equation} \label{eq:knapeq1}
	f_{j}(y) = max \quad \{f_{j-1}(y), f_{j-1}(y-w_{j}) + p_{j}\}, {y \ge w_{j}}
\end{equation}

Let us consider an example with a knapsack of capacity $C = 6$, three given objects with weights 2,3,4 and profits 1,2,5 respectively. Using the relation \ref{eq:knapeq1} we calculate all possible values and store them in a table as follows
\begin{center}
	\begin{tabular}{*8c}
		& 0 &1 &2 &3 &4 &5 &6 \\\cline{2-8}
		$f_{1}(y)$ &\multicolumn{1}{|c|}{0} &\multicolumn{1}{|c|}{0} &\multicolumn{1}{|c|}{1} &\multicolumn{1}{|c|}{1} &\multicolumn{1}{|c|}{1} &\multicolumn{1}{|c|}{1} &\multicolumn{1}{|c|}{1} \\\cline{2-8}
		$f_{2}(y)$ &\multicolumn{1}{|c|}{0} &\multicolumn{1}{|c|}{0} &\multicolumn{1}{|c|}{1} &\multicolumn{1}{|c|}{2} &\multicolumn{1}{|c|}{2} &\multicolumn{1}{|c|}{3} &\multicolumn{1}{|c|}{3} \\\cline{2-8}
		$f_{3}(y)$ &\multicolumn{1}{|c|}{0} &\multicolumn{1}{|c|}{0} &\multicolumn{1}{|c|}{1} &\multicolumn{1}{|c|}{2} &\multicolumn{1}{|c|}{5} &\multicolumn{1}{|c|}{5} &\multicolumn{1}{|c|}{6} \\\cline{2-8}
	\end{tabular}
\end{center}
So, we have a matrix of size \textit{n} x \textit{C} which we fill in row-wise manner as values in a row depend on the previous row values. The running time is \textit{O(nC)} and the space requirement is \textit{O(C)}. Below is the pseudo-code:

\begin{algorithm}
	\caption{DynamicKnapsack(\textit{p, w, n, C})}\label{dynamicKnapsack}
	\begin{algorithmic}[1]
		\For{$j$ from 0 to $C$}
			\State $result[0, j]\gets 0$
		\EndFor

		\For{$i$ from 1 to $n$}
			\For{$j$ from 0 to $C$}
				\If{$w[i-1] > j$}
					\State $result[i, j]\gets result[i-1, j]$
				\Else
					\State $result[i, j]\gets max(result[i-1, j], result[i-1, j-w[i-1]] + p[i-1])$
				\EndIf
			\EndFor
		\EndFor
	\end{algorithmic}
\end{algorithm}

\subsection{Backtracking}
A backtracking algorithm builds a set of possible solution all the while discarding any partial solution candidates which it determines to be not feasible. As discussed earlier the solution space for \textit{0-1} Knapsack problem consists of $2^{n}$ ways of assigning 0 or 1 to $x_{i}$. Below is a possible solution space when $n=3$.

\begin{center}
	\begin{tikzpicture}[every tree node/.style={draw,circle},
		level distance=1.25cm, sibling distance=0.5cm, minimum size = 0.5cm,
		edge from parent path={(\tikzparentnode) -- (\tikzchildnode)}]
	\Tree
	[.{}
		\edge node[auto=right] {$x_{1} = 0$};
		[.{}
			\edge node[midway, left] {$x_{2} = 0$};
			[.{}
				\edge node[midway, left] {$x_{3} = 0$};
				[.{} ]
				\edge node[midway, right] {$x_{3} = 1$};
				[.{} ]
			]
			\edge node[midway, right] {$x_{2} = 1$};
			[.{}
				\edge node[midway, left] {$x_{3} = 0$};
				[.{} ]
				\edge node[midway, right] {$x_{3} = 1$};
				[.{} ]
			]
		]
		\edge node[auto=left] {$x_{1} = 1$};
		[.{}
			\edge node[midway, left] {$x_{2} = 0$};
			[.{}
				\edge node[midway, left] {$x_{3} = 0$};
				[.{} ]
				\edge node[midway, right] {$x_{3} = 1$};
				[.{} ]
			]
			\edge node[midway, right] {$x_{2} = 1$};
			[.{}
				\edge node[midway, left] {$x_{3} = 0$};
				[.{} ]
				\edge node[midway, right] {$x_{3} = 1$};
				[.{} ]
			]
		]
	]
	\end{tikzpicture}
\end{center}
This space is searched in depth-first manner from the start node. From each E-node we check if the next node will result in a feasible solution. If yes, the next node becomes the E-node. If no, we backtrack to the previous node and kill the E-node. To do this, we use an upper bound on the best solution that can be achieved from this node. We obtain this bound by relaxing the constraint from \textit{$x_{i}$} $\in$ \{0, 1\} to $0 \le \textit{$x_{i}$} \le 1$ and using the greedy algorithm (of sorting the items in non-decreasing order of profit per unit weight and adding to the knapsack) for the rest of the problem. The pseudo-code for the bounding algorithm and the backtracking solution is given below.
\begin{algorithm}
	\caption{GreedyBound(\textit{p, w, n, C, k, $p_{c}$, $w_{c}$})}\label{greedyBound}
	\begin{algorithmic}[1]
		\For{$i$ from $k+1$ to $n$}
			\State $w_{c} \gets w_{c} + w_{i}$
			\If{$w_{c} < C$}
				\State $p_{c} \gets p_{c} + p_{i}$
			\Else
				\State \Return $p_{c} + (1 - (w_{c} - C)/w_{i}) * p_{i}$
			\EndIf
		\EndFor
		\State \Return $p_{c}$
	\end{algorithmic}
\end{algorithm}

\begin{algorithm}
	\caption{BacktrackingKnapsack(\textit{p, w, n, C, k, $p_{c}$, $w_{c}$})}\label{backtrackingKnapsack}
	\begin{algorithmic}[1]
		\If{$w_{c} + w_{k} \le C$}
			\State $y_{k} \gets 1$
			\If{$k < n$}
				\State \Call{BacktrackingKnapsack}{\textit{p, w, n, C, k+1, $p_{c} + p_{k}$, $w_{c} + w_{k}$}}
			\EndIf
			\If{$p_{c} + p_{k} > p_{t}$ \textbf{and} $k=n$}
				\State $p_{t} \gets p_{c} + p_{k}$
				\State $w_{t} \gets w_{c} + w_{k}$
				\For{$j$ from 1 to $k$}
					\State $x_{j} \gets y_{j}$
				\EndFor
			\EndIf
		\EndIf
		\If{$\Call{GreedyBound}{\textit{p, w, n, C, k, $p_{c}$, $w_{c}$}} \ge p_{t}$}
			\State $y_{k} \gets 0$
			\If{$k < n$}
				\State \Call{BacktrackingKnapsack}{\textit{p, w, n, C, k+1, $p_{c}$, $w_{c}$}}
			\EndIf
			\If{$p_{c} > p_{t}$ \textbf{and} $k=n$}
				\State $p_{t} \gets p_{c}$
				\State $w_{t} \gets w_{c}$
				\For{$j$ from 1 to $k$}
					\State $x_{j} \gets y_{j}$
				\EndFor
			\EndIf
		\EndIf

	\end{algorithmic}
\end{algorithm}

\section{Qualitative Comparison}
As we saw above, the brute force approach has a complexity of \textit{O(n$2^{n}$)}. Although it is quite simple to code, it can be used only for very small input due to its exponential complexity.

The dynamic programming approach performs much better with a running time of \textit{O(nC)}. It also has a space complexity of \textit{O(C)}. This stems from the fact that in a dynamic programming approach we need to store two rows of a \textit{C}-column array as values in the current row are calculated using those from the previous row. From the perspective of coding complexity, it is also quite easy to implement.

The backtracking algorithm will create the complete state space tree with $2^{n-1}-1$ nodes in the worst case. In theory it is hard to say how much of the search tree is pruned out by the bounding heuristics however in practice it does not generate all the possible nodes, so there is a substantial speed increase. The implementation in code is a bit more difficult in this case compared to the dynamic programming method as we need to maintain a separate data structure to store and manipulate the values per unit weight for the E-nodes.

\section{Conclusion}
In this paper we looked at two approaches to solve the \textit{0-1} Knapsack problem. We saw that runtimes for both the approaches have different characteristics. As such it cannot be explicitly defined which algorithm is a better choice. This needs to be determined by implementing both algorithms and executing the code by varying the input number of items and the maximum capacity of the knapsack.

\section{References}
1. Horowitz, Ellis and Sahni, Sartaj and Rajasekaran, Sanguthevar, 2007, \textit{Computer Algorithms}, Silicon Pr., 773p \\
2. Knapsack Problem, Wikipedia, \url{https://en.wikipedia.org/wiki/Knapsack_problem}
\end{document}