Added documentation for thorns IOUtil, IOHDF5, IOFlexIO, and IOASCII.

git-svn-id: http://svn.cactuscode.org/arrangements/CactusBase/IOUtil/trunk@28 b32723a9-ab3a-4a60-88e2-2e5d99d7c17a

1 files changed, 71 insertions, 0 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
new file mode 100644
index 0000000..a7e1134
--- /dev/null
+++ b/doc/documentation.tex
@@ -0,0 +1,71 @@
+% Thorn documentation template
+\documentclass{article}
+\begin{document}
+
+\title{IOUtil}
+\author{Gabrielle Allen, Tom Goodale}
+\date{1999}
+\maketitle
+
+\abstract{Thorn IOUtil provides basic IO parameters as well as a function
+interface for registration and scheduling of recovery routines supplied by
+other IO thorns.}
+%
+\section{Purpose}
+%
+Together with the flesh, thorn IOUtil provides the infrastructure for
+implementing IO in Cactus.\\
+For that purpose IOUtil declares a set of basic parameters that are commonly
+used to control IO in general, eg. saying
+%
+\begin{itemize}
+  \item when to do output
+  \item where output files should be put
+  \item what output modes should be used, etc.
+\end{itemize}
+%
+These parameters should be used by other IO thorns
+to define the default behaviour for the IO methods they implement.
+Of course, those thorns can also declare their own parameters in addition
+to the general ones from IOUtil, giving the user a chance to override the
+defaults and provide some specific control over individual IO methods.\\
+%
+\newline
+{\bf Example}\\
+You want to output some grid function in 1D, 2D, and 3D format at
+every iteration. Simply tell the different IO methods what they should
+output, and set the single IOUtil parameter {\tt IO::out\_every = 1}. This saves
+you setting the specific {\tt out\_every} parameter for each of the 3 formats.\\
+If you want to restrict 3D output to only every 10th iteration (because it takes
+too long to do it at every iteration) you just change the {\tt out\_every}
+parameter there -- and you're done.\\
+%
+\newline
+IOUtil also provides a skeleton for implementing checkpointing/recovery.
+There are parameters to
+%
+\begin{itemize}
+  \item enable/disable checkpointing \& recovery
+  \item specify how often checkpointing should take place
+  \item tell where checkpoint files should go to or can be found 
+\end{itemize}
+%
+Like with IO, checkpointing/recovery is implemented by other IO thorns. These
+register their checkpoint routines with the RFR if checkpointing was
+explicitely enabled for them.\\
+To recover from a checkpoint file you normally would have to know what data
+format the file is, and which IO thorn can process that format. To free the user
+from this burden, thorn IOUtil provides its own generic recovery routine and
+a function interface to register other IO thorns' recovery routines.
+IOUtil's generic routine will then just loop over all registered recovery
+routines (passing it the name of the recovery file) until one of them succeeded
+to process it.
+%
+%
+% Automatically created from the ccl files 
+% Do not worry for now.
+\include{interface}
+\include{param}
+\include{schedule}
+
+\end{document}