From e021ca94536ba9e1674d9fbd82a5f7cd398a2498 Mon Sep 17 00:00:00 2001 From: knarf Date: Fri, 21 Aug 2009 13:28:21 +0000 Subject: first version of HydroBase git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinBase/HydroBase/trunk@2 57fe0bb3-ccba-405f-9b23-de0201f165b7 --- doc/documentation.tex | 190 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 doc/documentation.tex (limited to 'doc') 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} -- cgit v1.2.3