Extended documentation to include file layout / attribute specification

darcs-hash:20040318185217-19929-15b60a969595a625826a805c05a84a91084a80ee.gz

1 files changed, 104 insertions, 3 deletions

diff --git a/Carpet/CarpetIOHDF5/doc/documentation.tex b/Carpet/CarpetIOHDF5/doc/documentation.tex
index 0e2f22764..14ac578cc 100644
--- a/Carpet/CarpetIOHDF5/doc/documentation.tex
+++ b/Carpet/CarpetIOHDF5/doc/documentation.tex
@@ -2,7 +2,7 @@
 %  Cactus Thorn template for ThornGuide documentation
 %  Author: Ian Kelley
 %  Date: Sun Jun 02, 2002
-%  $Header: /home/eschnett/C/carpet/Carpet/Carpet/CarpetIOHDF5/doc/documentation.tex,v 1.2 2004/03/18 18:17:21 cott Exp $                                                             
+%  $Header: /home/eschnett/C/carpet/Carpet/Carpet/CarpetIOHDF5/doc/documentation.tex,v 1.3 2004/03/18 19:52:17 cott Exp $                                                             
 %
 %  Thorn documentation in the latex file doc/documentation.tex 
 %  will be included in ThornGuides built with the Cactus make system.
@@ -64,7 +64,7 @@
 % *======================================================================* 
 
 % If you are using CVS use this line to give version information
-% $Header: /home/eschnett/C/carpet/Carpet/Carpet/CarpetIOHDF5/doc/documentation.tex,v 1.2 2004/03/18 18:17:21 cott Exp $
+% $Header: /home/eschnett/C/carpet/Carpet/Carpet/CarpetIOHDF5/doc/documentation.tex,v 1.3 2004/03/18 19:52:17 cott Exp $
 
 \documentclass{article}
 
@@ -84,7 +84,7 @@
 
 % the date your document was last changed, if your document is in CVS, 
 % please use:
-%    \date{$ $Date: 2004/03/18 18:17:21 $ $}
+%    \date{$ $Date: 2004/03/18 19:52:17 $ $}
 \date{March 18, 2004}
 
 \maketitle
@@ -142,6 +142,25 @@ First, you have to activate the thorn in your Cactus parameter file:
   \item {\tt iohdf5::out3D\_dir = "your preferred 3-D output directory"}
 \end{itemize}
 
+\subsubsection{3-D Input}
+
+There are two ways to use the 3-D input capabilities:
+
+\begin{enumerate}
+  \item For evolutions using ADMBase, one may use the thorn IDFileADM and the following parameter settings:
+    \begin{itemize}
+      \item {\tt ADMBase::initial\_data  = "read from file"}
+      \item {\tt IO::filereader\_ID\_files = "space separated list of files containing the ADM variables"}
+      \item {\tt IO::filereader\_ID\_vars = "space separated list of variables to be read in"}
+    \end{itemize}
+  \item For evolutions not using ADMBase one may try to read in data by setting
+    \begin{itemize}
+      \item {\tt iohdf5::in3D\_dir = "directory from where to read data"}
+      \item {\tt iohdf5::in3D\_vars = "space separated list of variables to be read in"}
+    \end{itemize}
+\end{enumerate}
+
+
 \subsubsection{Checkpointing}
 
 CarpetIOHDF5 uses the Cactus checkpoint/recovery infrastructure provided by
@@ -189,6 +208,88 @@ of cpus  from a checkpoint file of a run using any (other or same) number of cpu
 \end{itemize}
 
 
+\section{CarpetIOHDF5's HDF5 file layout}
+
+The HDF5 file layout of CarpetIOHDF5 is quite simple. There are no groups besides the 
+standard HDF5 root data object group:
+
+\begin{itemize}
+  \item Each dataset is named according to this template: \\
+    {\tt \small [Full Variable Name] it=[Iteration] tl=[Timelevel] ml=[mglevel] rl=[reflevel] m=[map] c=[component]}
+    
+  \item Each dataset has the following (largely redundant!) attributes associated with it:
+
+    \begin{itemize}
+    \item {\tt level} : Carpet::reflevel
+    \item {\tt origin} : 1-D array of length Carpet::dim. \\ origin[d]=CCTK\_ORIGIN\_SPACE(d) + 
+      cctk\_lbnd[d] * delta[d]
+    \item {\tt delta} : 1-D array of length Carpet::dim. \\ delta[d] = CCTK\_DELTA\_SPACE(d)
+    \item {\tt min\_ext} : 1-D array of length Carpet::dim. \\ min\_ext[d] = delta[d] 
+    \item {\tt max\_ext} : 1-D array of length Carpet::dim. \\ origin[d] + cctk\_lsh[d] * delta[d]
+    \item {\tt time} : cctk\_time
+    \item {\tt timestep} : cctk\_iteration
+    \item {\tt level\_timestep} : cctk\_iteration / Carpet::reflevelfact
+    \item {\tt persistence} : cctk\_iteration / Carpet::reflevelfact
+    \item {\tt time\_refinement} : Carpet::time\_refinement
+    \item {\tt spatial\_refinement} : 1-D array of length Carpet::dim. \\ spatial\_refinement[d] = Carpet::reflevelfact
+    \item {\tt grid\_placement\_refinement} : 1-D array of length Carpet::dim. \\ grid\_placement\_refinement[d] = Carpet::reflevelfact
+    \item {\tt iorigin} : 1-D array of length Carpet::dim. \\ iorigin[d] = (Carpet::ext.lower() / Carpet::ext.stride())[d]
+    \item {\tt name} : CCTK\_FullName(variable index)
+    \item {\tt group\_version} : 1
+    \item {\tt group\_fullname} : CCTK\_FullName(variable index)
+    \item {\tt group\_varname} : CCTK\_VarName(variable index)
+    \item {\tt group\_groupname} : CCTK\_GroupName(group index)
+    \item {\tt group\_grouptype} : CCTK\_GF, CCTK\_ARRAY or CCTK\_SCALAR
+    \item {\tt group\_dim} : CCTK\_GroupDimI(group index)
+    \item {\tt group\_timelevel} : tl (current timelevel)
+    \item {\tt group\_numtimelevels} : CCTK\_NumTimeLevelsI(group index)
+    \item {\tt cctk\_version} : 1
+    \item {\tt cctk\_dim} : cctk\_dim
+    \item {\tt cctk\_iteration} : cctk\_iteration
+    \item {\tt cctk\_gsh} : 1-D array of length Carpet::dim. cctk\_gsh
+    \item {\tt cctk\_lsh} : 1-D array of length Carpet::dim. cctk\_lsh
+    \item {\tt cctk\_lbnd} : 1-D array of length Carpet::dim. cctk\_lbnd
+    \item {\tt cctk\_delta\_time} : 1-D array of length Carpet::dim. cctk\_delta\_time
+    \item {\tt cctk\_delta\_space} : 1-D array of length Carpet::dim. cctk\_delta\_space
+    \item {\tt cctk\_origin\_space} : 1-D array of length Carpet::dim. cctk\_origin\_space
+    \item {\tt cctk\_bbox} : 1-D array of length 2*Carpet::dim. cctk\_box
+    \item {\tt cctk\_levfac} : 1-D array of length Carpet::dim. cctk\_levfac
+    \item {\tt cctk\_levoff} : 1-D array of length Carpet::dim. cctk\_levoff
+    \item {\tt cctk\_levoffdenom} : 1-D array of length Carpet::dim. cctk\_levoffdenom
+    \item {\tt cctk\_timefac} : cctk\_timefac
+    \item {\tt cctk\_convlevel} : cctk\_convlevel
+    \item {\tt cctk\_convfac} : cctk\_convfac
+    \item {\tt cctk\_nghostzones} : 1-D array of length Carpet::dim. cctk\_nghostzones
+    \item {\tt cctk\_time} : cctk\_time
+    \item {\tt carpet\_version} : 1
+    \item {\tt carpet\_dim} : Carpet::dim
+    \item {\tt carpet\_basemglevel} : Carpet::basemglevel
+    \item {\tt carpet\_mglevel} : Carpet::mglevel
+    \item {\tt carpet\_mglevels} : Carpet::mglevels
+    \item {\tt carpet\_mgface} : Carpet::mgfact
+    \item {\tt carpet\_reflevel} : Carpet::reflevel
+    \item {\tt carpet\_reflevels} : Carpet::reflevels
+    \item {\tt carpet\_reffact} : Carpet::reffact
+    \item {\tt carpet\_map} : Carpet::map
+    \item {\tt carpet\_maps} : Carpet::maps
+    \item {\tt carpet\_component} : Carpet::component
+    \item {\tt carpet\_components} : Carpet::vhh.at(Carpet::map)->components(reflevel))
+
+    \end{itemize}
+\end{itemize}
+
+\subsection{Attributes needed by the file reader}
+
+The number of attributes needed by the CarpetIOHDF5 file reader is much smaller then the total
+number of attributes attached to each dataset:
+
+\begin{itemize}
+  \item {\tt name}
+  \item {\tt level}
+  \item {\tt iorigin}
+\end{itemize}
+
+
 %\subsection{Interaction With Other Thorns}
 %
 %\subsection{Support and Feedback}