HydroBase: add references to Valencia formulation, update documentation to

include new grid variables


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

2 files changed, 77 insertions, 26 deletions

diff --git a/README b/README
index 97ef971..d1439a8 100755
--- a/README
+++ b/README
@@ -13,3 +13,38 @@ This thorn should be the interface between all hydro codes and the
 spacetime codes.
 
 For more information see the documentation in the ThornGuide.
+
+2. Publications
+
+The variables provided by this thorn are those of the Valencia formulation of GRHD:
+@ARTICLE{1997ApJ...476..221B,
+   author = {{Banyuls}, F. and {Font}, J.~A. and {Ibanez}, J.~M.~A. and {Marti}, J.~M.~A. and 
+	{Miralles}, J.~A.},
+    title = "{Numerical $\{$3+1$\}$ General Relativistic Hydrodynamics: A Local Characteristic Approach}",
+  journal = {\apj},
+ keywords = {HYDRODYNAMICS, METHODS: NUMERICAL, RELATIVITY, SHOCK WAVES},
+     year = 1997,
+    month = feb,
+   volume = 476,
+    pages = {221-+},
+      doi = {10.1086/303604},
+   adsurl = {http://adsabs.harvard.edu/abs/1997ApJ...476..221B},
+  adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+@ARTICLE{2006ApJ...637..296A,
+   author = {{Ant{\'o}n}, L. and {Zanotti}, O. and {Miralles}, J.~A. and 
+	{Mart{\'{\i}}}, J.~M. and {Ib{\'a}{\~n}ez}, J.~M. and {Font}, J.~A. and 
+	{Pons}, J.~A.},
+    title = "{Numerical 3+1 General Relativistic Magnetohydrodynamics: A Local Characteristic Approach}",
+  journal = {\apj},
+   eprint = {arXiv:astro-ph/0506063},
+ keywords = {Methods: Numerical, Magnetohydrodynamics: MHD, Relativity},
+     year = 2006,
+    month = jan,
+   volume = 637,
+    pages = {296-312},
+      doi = {10.1086/498238},
+   adsurl = {http://adsabs.harvard.edu/abs/2006ApJ...637..296A},
+  adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
diff --git a/doc/documentation.tex b/doc/documentation.tex
index 601a123..0b87fc0 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -69,15 +69,15 @@
 \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}
+\author{Tanja Bode \textless tanja.bode@physics.gatech.edu\textgreater\\
+        Frank L\"offler \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}
+\date{April 29, 2010}
 
 \maketitle
 
@@ -90,7 +90,7 @@
 % Add an abstract for this thorn's documentation
 \begin{abstract}
 
-HydroBase extends the CactusEinstein framework to include an interface for hydrodynamics to 
+HydroBase extends the CactusEinstein framework to include an interface for magnetohydrodynamics 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 
@@ -122,7 +122,7 @@ Another advantage is that the format of output generated by different hydrodynam
 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}
+\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
@@ -135,21 +135,26 @@ 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}
+ \item \verb|rho|: rest mass density $\varrho$
+ \item \verb|press|: pressure $p$
+ \item \verb|eps|: internal energy $\epsilon$
+ \item \verb|vel[3]|: contravariant fluid three 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$.
+ \item \verb|Y_e|: electron fraction $Y_e$
+ \item \verb|temperature|: temperature $T$
+ \item \verb|entropy|: specific entropy per particle $s$
+ \item \verb|Bvec[3]|: contravariant magnetic field vector defined as 
+  \begin{equation}
+      B^i = \frac{1}{\sqrt{4\pi}} n_{\nu} F^{*\nu i}
+  \end{equation}
+  in terms of the dual 
+  $F^{*\mu\nu} = \frac{1}{2}\varepsilon^{\mu\nu\alpha\beta}F_{\alpha\beta}$ 
+  to the Faraday tensor and the unit normal of the foliation of spacetime
+  $n^\mu$.
 \end{itemize}
 
 HydroBase also sets up scheduling blocks that organize the main functions which modules of a 
@@ -162,7 +167,7 @@ Currently the scheduling blocks are:
  \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 Setting and updating an excision mask
  \item Applying boundary conditions
 \end{itemize}
 
@@ -172,11 +177,12 @@ a central access point for analysis thorns.
 
 \section{Units}
 
-HydroBase uses a specific set of units, so that there are no
-misunderstandings between thorns.  These units are derived from the
+HydroBase does not require a specific set of units itself. However 
+so that there are no misunderstandings between thorns a specific 
+set of units is suggested.  These units are derived from the
 conventions
 \begin{eqnarray}
-  M = M_\mathrm{sun} &;& c = G = 1
+  M_\mathrm{sun} = 1 &;& c = G = 1
 \end{eqnarray}
 which are commonly used in astrophysics and in relativity.
 
@@ -207,7 +213,7 @@ magnetic field:
 
 \section{Acknowledgments}
 
-This thorn was produced by Tanja Bode, Roland Haas, Frank Löffler, and Erik Schnetter.
+This thorn was produced by Tanja Bode, Roland Haas, Frank L\"offler, and Erik Schnetter.
 
 \begin{thebibliography}{9}
 \bibitem{livrevgrrfd}
@@ -216,7 +222,17 @@ This thorn was produced by Tanja Bode, Roland Haas, Frank Löffler, and Erik Sch
     \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.
-
+\bibitem{valenciaHD}
+    F. Banyuls, J.~A. Font, J.~M.~A. Ibanez, J.~M.~A. Marti, and 
+	J.~A. Miralles. 
+    \newblock Numerical 3+1 General Relativistic Hydrodynamics: A Local Characteristic Approach.
+    \newblock {\em ApJ}, {\bf 476}, 221, 1997.
+\bibitem{valenciaMHD}
+    L. Ant{\'o}n, O. Zanotti, J.~A. Miralles,  
+	J.~M. Mart{\'{\i}}, J.~M. Ib{\'a}{\~n}ez, J.~A. Font, and 
+	 J.~A Pons.
+    \newblock Numerical 3+1 General Relativistic Magnetohydrodynamics: A Local Characteristic Approach.
+    \newblock {\em ApJ}, {\bf 637}, 296 -- 312, 2006.
 \end{thebibliography}
 
 % Do not delete next line