\documentclass{book}

\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[english]{babel}
\usepackage{xcolor}
\usepackage{listings}
\usepackage{graphicx}
\usepackage{fancyvrb} %keep
\usepackage{fancyhdr}
\usepackage{booktabs} %keep
\usepackage{mathtools} %keep
\usepackage{hyperref}

\definecolor{mygray}{HTML}{AAAAAA}

\newcommand{\code}[1]{{\ttfamily #1}}

\fancyhead{}
\fancyhead[LE]{\leftmark}
\fancyhead[RO]{\rightmark}
\cfoot{}
\rfoot{\thepage} %exit

\hypersetup{colorlinks=true}


\newcommand{\cppFile}[1]{\texttt{#1}}
\newcommand{\inputItem}[1]{\noindent\texttt{\bf #1} ---}
\newcommand{\inputSubItem}[1]{\indent\texttt{\it #1} --}
%% Remove the below command before submission
\newcommand{\todo}[1]{\textcolor{red}{#1}}
%Format to denote a C++ class name:
\newcommand{\cppClass}[1]{{\sffamily #1}}
%Format to denote a C++ variable:
\newcommand{\cppFunction}[1]{{\tt #1}}
% for the cover page:
\newcommand{\HRule}{\noindent\rule{\linewidth}{1.5pt}}
\newcommand{\ptexPaste}[1]{\fbox{\textcolor{red}{PLEASE RUN ptex.pl on this .ptex source
to obtain the correct test for tag #1}}}
\newcommand{\ptexLabel}[1]{\ptexPaste{#1}}
\newcommand{\ptexInterface}[1]{\ptexPaste{#1}}
\newcommand{\ptexReadFile}[1]{\ptexPaste{#1}}
\newcommand{\ptexReadFileVerbatim}[1]{\ptexPaste{#1}}

\hyphenation{Wave-Function-Transformation}
\lstset{language=c++,basicstyle=\footnotesize\ttfamily,
keywordstyle=\color{blue}\bfseries,frame=shadowbox}
\pagestyle{fancy}
\begin{document}

\begin{titlepage}
\vspace*{\stretch{1}}
\HRule
\begin{flushright}
\LARGE  PsimagLite v2 Manual\\
\end{flushright}
\HRule
\vspace*{\stretch{2}}

%
\begin{center}
\Large Manual Version: \today\\
\end{center}

\begin{center}
\textsc{Oak Ridge, 2018}
\end{center}

\end{titlepage}
%
\begin{titlepage}
\noindent
\begin{minipage}{0.4\textwidth}
\begin{flushleft}
Gonzalo \textsc{Alvarez}\\
Nanomaterials Theory Institute\\
Oak Ridge National Laboratory\\[0.2cm]
Oak Ridge, TN 37831\\
\today
\end{flushleft}
\end{minipage}

\vspace*{\stretch{2}}
\noindent
%\begin{minipage}{0.6\textwidth}
\begin{tiny}
\fontshape{sc}\selectfont
%\begin{verbatim}
\noindent
DISCLAIMER\\[0.2cm]
THE SOFTWARE IS SUPPLIED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
COPYRIGHT OWNER, CONTRIBUTORS, UNITED STATES GOVERNMENT,
OR THE UNITED STATES DEPARTMENT OF ENERGY BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.

NEITHER THE UNITED STATES GOVERNMENT, NOR THE UNITED STATES DEPARTMENT OF ENERGY,
NOR THE COPYRIGHT OWNER, NOR
ANY OF THEIR EMPLOYEES, REPRESENTS THAT THE USE OF ANY
INFORMATION, DATA, APPARATUS, PRODUCT, OR PROCESS
DISCLOSED WOULD NOT INFRINGE PRIVATELY OWNED RIGHTS.\\[1cm]

\fontshape{\shapedefault}\selectfont
%\end{verbatim}
\end{tiny}
%\end{minipage}
\noindent
\begin{minipage}{0.4\textwidth}
Copyright \copyright 2009-2018,\\
 UT-Battelle, LLC\\
All rights reserved
\end{minipage}
\hfill
\begin{minipage}{0.4\textwidth}
\begin{flushright}
\includegraphics[width=3cm]{PsimagLiteLogo.png}
\end{flushright}
\end{minipage}
\end{titlepage}
\tableofcontents

\pagebreak

\ptexReadFile{../README.md}

\chapter{IoNg}\label{sec:iong}
\subsection{Overview}
\code{IoNg} is the next generation (ng) input and output (io) subsystem for 
\textsc{DMRG++} and related 
scientific applications. To output data to a file the
client program first includes the \code{IoNg.h} header and then creates an object of class
\code{IoNg::Out io;} with argument the filename to be written to.
Next, the client code calls \code{io.write(object, label);} where
\code{object} is the object to be written with label \code{label}.
To input data from a file the client program first includes the 
\code{IoNg.h} header and then creates an object of class
\code{IoNg::In io;} with argument the filename to be read from.
Next, the client code calls \code{io.read(object, label);} where
\code{object} is the object to be read with label \code{label}.
If an object's constructor accepts an \code{IoNg::In} argument the object
can be constructed from data on the file.
The classes \code{IoNg::In} and \code{IoNg::Out} should be passed
to functions as \emph{non-const} references.
The copy constructor, assignment operator, and default constructor shall not
be available for either \code{IoNg::In} or \code{IoNg::Out}.

\subsection{How data is stored on disk}
The data on disk can be either a group (implemented as an HDF5 group) semantically
equivalent to a directory, or a dataset (implemented as an HDF5 dataset)
semantically equivalent to a file.
The following types are written as a single dataset:
Native types, complex of native types, std::vector of native types, 
std::vector of complex types, \code{std::pair<T1, T2>} if both \code{T1} and \code{T2} 
are either native types or complex of native types.
All other types involve the creation of one or more groups.
Moreover, \code{IoNg} will add the root group $/Def$, but client
source code must not use it. For example, client code
can write a \code{std::vector<double>} \code{myvector} with \code{io.write(myvector,} 
\code{``myvector'');}
and read it back with \code{io.read} \code{(myvector,} \code{``myvector'');}.
The HDF5 file will contain \code{myvector}  in the dataset \code{/Def} \code{/myvector,} but the client
code should not use the \code{/Def} group prefix when reading back with the \code{IoNg} class.
Only when using third-party tools should the \code{/Def} group prefix be added.

\subsection{Labels of datasets and groups}
Labels for dataset and groups must be of the form $/label_0/label_1/.../label_{n-1}$.
where each $label_i$ is of the form $[a-zA-Z0-9-\_]+$.

\subsection{API Reference}
TBW. This will be pulled directly form the source code.

\section{IoNgSerializer}
\subsection{Overview}
A client call to \code{io.write(label, object);} executes differently depending on the
object type. For source code purposes two kinds of types need to be considered:
\emph{root-undelegated} types, and \emph{root-delegated} types; the latter 
types are either native types or STL types. All other types that need
serialization are considered \emph{root-delegated}. STL containers of \emph{root-delegated} types
are themselves \emph{root-undelegated}: For example \code{std::vector<A>} is
\emph{root-undelegated} even if \code{A} is \emph{root-delegated}.

\subsection{Root-undelegated Types}
\ptexPaste{IsRootUnDelegated}

\subsubsection{Serialization of std::vector}
A single dataset is also used for \code{std::vector<T>} 
if \code{T} is native or the complex of a native.
If T is neither native nor the std::complex of a native, then \code{IoNg} creates a group with 
\code{label}, and inside that group
creates a dataset named \code{Size} containing the size of the vector.
\code{IoNg} then runs a loop over \code{index} and delegates the writing. 
If \code{T} is a root-undelegated type then
\code{write(label + ``/''} \code{ + ttos(index),} \code{ data[index]);} is used,
and if \code{T} is root-delegated
then
\code{data[index].write(} \code{ioNgSerializer\_,} \code{ label + ``/''}
\code{ + ttos(index))}  is used instead,
where \code{data} is the underlying \code{std::vector}.
Moreover, for  \code{std::vector} \code{<T*>} with T root-delegated, the variant
\code{data[index]} \code{->write} \code{(ioNgSerializer\_, } \code{label +}
\code{``/'' + ttos(index))} is used.
	
\subsubsection{Serialization of std::string}
TBW

\subsubsection{Serialization of std::pair}
TBW

\subsubsection{Serialization of std::stack}
TBW

\subsubsection{Serialization of std::map}
TBW

\subsection{Root-delegated Types}
A type is root-delegated if it is not root-undelegated.
Root-delegateds must include the \code{IoSerializer.h} class
but should not include \code{IoNg.h} unless needed. 
Root-delegateds must have a function named \code{serialize} returning \code{void}
and taking two arguments: the serializer object \code{ioSerializer}
by \emph{non-const} reference, and string \code{label}.
In their \code{write} function, root-delegateds must first create a group called label by calling
\code{io.createGroup} \code{(label),} and
should then go over their data members, and for each call either
\code{ioSerializer.} \code{write(dataMember,} \code{label +} \code{"/" + name);}
if \code{dataMember} is a root-undelegated type or
\code{dataMember.} \code{write(} \code{ioSerializer, } \code{label +} \code{"/" + names)}
if \code{dataMember} is a root-delegated type,
with the name being the name of the \code{dataMember} in question.

\section*{LICENSE}
\begin{verbatim}
\ptexReadFile{../LICENSE}
\end{verbatim}
%\bibliographystyle{plain}
%\bibliography{thesis}
\end{document}
