first version of HydroBase

git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinBase/HydroBase/trunk@2 57fe0bb3-ccba-405f-9b23-de0201f165b7

1 files changed, 190 insertions, 0 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
new file mode 100644
index 0000000..268068c
--- /dev/null
+++ b/doc/documentation.tex
@@ -0,0 +1,190 @@
+% *======================================================================*
+%  Thorn documentation in the latex file doc/documentation.tex 
+%  will be included in ThornGuides built with the Cactus make system.
+%  The scripts employed by the make system automatically include 
+%  pages about variables, parameters and scheduling parsed from the 
+%  relevant thorn CCL files.
+%  
+%  This template contains guidelines which help to assure that your     
+%  documentation will be correctly added to ThornGuides. More 
+%  information is available in the Cactus UsersGuide.
+%                                                    
+%  Guidelines:
+%   - Do not change anything before the line
+%       % START CACTUS THORNGUIDE",
+%     except for filling in the title, author, date etc. fields.
+%        - Each of these fields should only be on ONE line.
+%        - Author names should be separated with a \\ or a comma
+%   - You can define your own macros are OK, but they must appear after
+%     the START CACTUS THORNGUIDE line, and do not redefine standard 
+%     latex commands.
+%   - To avoid name clashes with other thorns, 'labels', 'citations', 
+%     'references', and 'image' names should conform to the following 
+%     convention:          
+%       ARRANGEMENT_THORN_LABEL
+%     For example, an image wave.eps in the arrangement CactusWave and 
+%     thorn WaveToyC should be renamed to CactusWave_WaveToyC_wave.eps
+%   - Graphics should only be included using the graphix package. 
+%     More specifically, with the "includegraphics" command. Do
+%     not specify any graphic file extensions in your .tex file. This 
+%     will allow us (later) to create a PDF version of the ThornGuide
+%     via pdflatex. |
+%   - References should be included with the latex "bibitem" command. 
+%   - use \begin{abstract}...\end{abstract} instead of \abstract{...}
+%   - For the benefit of our Perl scripts, and for future extensions, 
+%     please use simple latex.     
+%
+% *======================================================================* 
+% 
+% Example of including a graphic image:
+% \begin{figure}[ht]
+%  \begin{center}
+%   \includegraphics[width=6cm]{MyArrangement_MyThorn_MyFigure}
+%  \end{center}
+%  \caption{Illustration of this and that}
+%  \label{MyArrangement_MyThorn_MyLabel}
+% \end{figure}
+%
+% Example of using a label:
+%   \label{MyArrangement_MyThorn_MyLabel}
+%
+% Example of a citation:
+%    \cite{MyArrangement_MyThorn_Author99}
+%
+% Example of including a reference
+%   \bibitem{MyArrangement_MyThorn_Author99}
+%   {J. Author, {\em The Title of the Book, Journal, or periodical}, 1 (1999), 
+%   1--16. {\tt http://www.nowhere.com/}}
+%
+% *======================================================================* 
+
+\documentclass{article}
+
+% Use the Cactus ThornGuide style file
+% (Automatically used from Cactus distribution, if you have a 
+%  thorn without the Cactus Flesh download this from the Cactus
+%  homepage at www.cactuscode.org)
+\usepackage{../../../../doc/latex/cactus}
+
+\begin{document}
+
+% The author of the documentation
+\author{Tanja Bode \textless tbode@gravity.psu.edu\textgreater\\
+        Frank Löffler \textless knarf@cct.lsu.edu\textgreater}
+
+% The title of the document (not necessarily the name of the Thorn)
+\title{HydroBase}
+
+% the date your document was last changed, if your document is in CVS, 
+% please use:
+\date{February 13, 2009}
+
+\maketitle
+
+% Do not delete next line
+% START CACTUS THORNGUIDE
+
+% Add all definitions used in this documentation here 
+%   \def\mydef etc
+
+% Add an abstract for this thorn's documentation
+\begin{abstract}
+
+HydroBase extends the CactusEinstein framework to include an interface for hydrodynamics to 
+work within.  HydroBase's main function is to store the primitive variables, common among 
+hydrodynamic simulations, commonly needed parameters, and schedule groups for the main 
+functions of a hydrodynamics code.  This has been done with an eye on Whisky, but can be used 
+to implement any hydrodynamics formulation.
+
+\end{abstract}
+
+% The following sections are suggestive only.
+% Remove them or add your own.
+
+\section{Introduction}
+
+The idea behind this thorn is to create a slim, common set of variables, parameters and
+scheduling groups which can then be used by different hydrodynamics codes. It should contain
+the common concepts of different hydrodynamics codes, but at the same time it should be
+as slim as possible to remain as general as possible. HydroBase should not contain the
+actual source code of typical routines of hydrodynamics codes, it should merely provide
+a common setup in which hydrodynamics codes can put their routines.
+
+Because there exist different formulations of the hydrodynamics equations and not all of
+them involve concepts like conserved variabled or treat them
+differently, which is the reason why these variables are not defined in HydroBase but this
+is left to the hydrodynamics codes.
+
+One of the advantages of such a common base is that modules of hydrodynamics codes only
+working with entities defined in HydroBase could be used interchangeably. Prime examples
+for this are initial data solvers or importers and analysis modules.
+Another advantage is that the format of output generated by different hydrodynamics
+codes in Cactus would be the same, including variable names and unit conventions, which
+would improve the ability to compare results of different codes directly a lot.
+
+\section{Using This Thorn}
+
+HydroBase is to be used as a central part of hydrodynamics fields just as ADMBase is used as a 
+central part of spacetime evolution and analysis codes. HydroBase only stores variables which
+are common to most if not all hydrodynamics codes solving the Euler
+equations, the so called primitive variables. These are also the variables which are needed
+to couple to a spacetime solver and which are usually needed by analysis thorns. The usage of
+a common set of variables by different hydrodynamics codes creates the possibility to share
+parts of the code, e.g. initial data solvers or analysis routines. 
+
+Currently the defined primitive variables are (see~\cite{livrevgrfd} for
+details):
+\begin{itemize}
+ \item group \verb|hydrobase_prim_scalar_var|: scalar variables
+ \begin{itemize}
+  \item \verb|rho|: rest mass density $\varrho$
+  \item \verb|press|: pressure $p$
+  \item \verb|eps|: internal energy $\epsilon$
+ \end{itemize}
+ \item group \verb|hydrobase_prim_vector_var|: vector variables
+ \begin{itemize}
+  \item \verb|velx|, \verb|vely|, \verb|velz|: velocity $v^i$ defined as
+      \begin{equation}
+	  v^i = \frac{u^i}{\alpha u^0} + \frac{\beta^i}{\alpha}
+      \end{equation}
+      in terms of the four-velocity $u^\mu$, lapse $\alpha$, and shift vector
+      $\beta^i$.
+ \end{itemize}
+\end{itemize}
+
+HydroBase also sets up scheduling blocks that organize the main functions which modules of a 
+hydrodynamics code may need. All of those scheduling blocks are optional, however if used,
+they might simplify existing codes and make them more interoperable. HydroBase itself does
+not schedule something inside most of the groups which it provides.
+
+Currently the scheduling blocks are:
+\begin{itemize}
+ \item Initializing the primitive variables
+ \item Converting primitive variables to conservative variables
+ \item Calculating the right hand side (RHS) in the method of lines (MoL)
+ \item Setting and updating an atmosphere mask
+ \item Applying boundary conditions
+\end{itemize}
+
+In this way the initiation of the primitive variables, methods to recover the conservative
+variables, and basic atmosphere handling can be implemented in different thorns while allowing
+a central access point for analysis thorns.
+
+\subsection{Acknowledgments}
+
+This thorn was produced by Tanja Bode, Roland Haas, Frank Löffler and Erik Schnetter.
+
+\begin{thebibliography}{9}
+\bibitem{livrevgrrfd}
+    J.~A. Font.
+    \newblock Numerical hydrodynamics in {G}eneral {R}elativity.
+    \newblock {\em Living Rev. Relativity}, {\bf 3}, 2000.
+    \newblock [Article in on-line journal], cited on 31/07/01,
+      http://www.livingreviews.org/ Articles/Volume3/2000-2font/index.html.
+
+\end{thebibliography}
+
+% Do not delete next line
+% END CACTUS THORNGUIDE
+
+\end{document}