first version of HydroBase

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

8 files changed, 342 insertions, 0 deletions

diff --git a/README b/README
new file mode 100755
index 0000000..9e31b7a
--- /dev/null
+++ b/README
@@ -0,0 +1,10 @@
+Cactus Code Thorn HydroBase
+Authors    : See the ThornGuide.
+--------------------------------------------------------------------------
+
+Purpose of the thorn:
+
+This thorn should be the interface between all hydro codes and the
+spacetime codes.
+
+For more information see the documentation in the ThornGuide.
diff --git a/configuration.ccl b/configuration.ccl
new file mode 100755
index 0000000..27ed326
--- /dev/null
+++ b/configuration.ccl
@@ -0,0 +1,4 @@
+# Configuration definition for thorn HydroBase
+
+REQUIRES Boundary CartGrid3D SpaceMask
+
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}
diff --git a/interface.ccl b/interface.ccl
new file mode 100755
index 0000000..b011f33
--- /dev/null
+++ b/interface.ccl
@@ -0,0 +1,17 @@
+# Interface definition for thorn HydroBase
+
+implements: HydroBase
+inherits: ADMBase
+
+protected:
+
+real hydrobase_prim_scalar_var type = GF Timelevels = 3 tags='ProlongationParameter="HydroBase::HydroBase_Prolongation_Type" tensortypealias="Scalar" interpolator="matter"'
+{
+  rho, press, eps
+} "Scalar primitive variables"
+
+real hydrobase_prim_vector_var type = GF Timelevels = 3 tags='ProlongationParameter="HydroBase::HydroBase_Prolongation_Type" tensortypealias="U" interpolator="matter"'
+{
+  velx, vely, velz
+} "Vector primitive variables"
+
diff --git a/param.ccl b/param.ccl
new file mode 100755
index 0000000..aa78e4b
--- /dev/null
+++ b/param.ccl
@@ -0,0 +1,16 @@
+# Parameter definitions for thorn HydroBase
+
+restricted:
+
+int timelevels "Number of time levels in evolution scheme"
+{
+  1:3 :: "FMR/AMR runs probably need 3. Otherwise use 2"
+} 2
+
+STRING HydroBase_Prolongation_Type "The prolongation operator used by Carpet for HydroBase variables"
+{
+  "ENO"  :: "Third order ENO operators; only third order is implemented"
+  "WENO" :: "Fifth order WENO operators; only fifth order is implemented"
+  ".*"   :: "Anything else"
+} "ENO"
+
diff --git a/schedule.ccl b/schedule.ccl
new file mode 100755
index 0000000..0cf8c07
--- /dev/null
+++ b/schedule.ccl
@@ -0,0 +1,81 @@
+# Schedule definitions for thorn HydroBase
+
+#######################################################################
+### We leave the storage on all the time for the variables required ###
+### by MoL. There is probably a better way of doing this.           ###
+#######################################################################
+
+if (timelevels == 3)
+{
+  STORAGE:hydrobase_prim_scalar_var[3]
+  STORAGE:hydrobase_prim_vector_var[3]
+}
+else if (timelevels == 2)
+{
+  STORAGE:hydrobase_prim_scalar_var[2]
+  STORAGE:hydrobase_prim_vector_var[2]
+}
+else if (timelevels == 1)
+{
+  STORAGE:hydrobase_prim_scalar_var[1]
+  STORAGE:hydrobase_prim_vector_var[1]
+}
+
+schedule group HydroBase_Initial AT Initial after ADMBase_InitialData after ADMBase_InitialGauge after IOUtil_RecoverIDFromDatafiles before ADMBase_PostInitial before SetTmunu
+{
+} "HydroBase initial data group"
+
+###############################
+### Register startup banner ###
+###############################
+
+schedule HydroBase_StartUp AT WRAGH
+{
+  LANG: C
+} "Startup banner"
+
+schedule group HydroBase_RHS IN MoL_CalcRHS
+{
+} "Groups for scheduling tasks for calculating RHS of hydro variables"
+
+schedule group HydroBase_PostStep IN MoL_PostStep BEFORE SetTmunu
+{
+} "Post step tasks for hydro thorns"
+
+schedule group HydroBase_PostStep AT POSTRESTRICTINITIAL
+{
+} "Post step tasks for hydro thorns"
+
+# Hydro thorns should not schedule something in this group
+# (schedule them in HydroBase_Boundaries), but they can refer to it
+# in order to schedule own routines before or after the boundary
+# treatment
+schedule group HydroBase_Do_Boundaries IN HydroBase_PostStep BEFORE HydroBase_Con2Prim
+{
+} "HydroBase Boundary conditions group"
+
+schedule group HydroBase_Do_Boundaries IN MoL_Evolution AFTER MoL_Step
+{
+} "HydroBase Boundary conditions group"
+
+schedule group HydroBase_Boundaries IN HydroBase_Do_Boundaries
+{
+} "Group to schedule the boundary condition functions"
+
+schedule group ApplyBCs AS HydroBase_ApplyBCs IN HydroBase_Do_Boundaries AFTER HydroBase_Boundaries
+{
+} "Apply the boundary conditions of HydroBase"
+
+schedule group HydroBase_Con2Prim IN HydroBase_PostStep
+{
+} "Convert from conservative to primitive variables"
+
+# I am not quite sure why this has to be scheduled in CCTK_PostPostInitial (roland)
+schedule group HydroBase_Con2Prim AT CCTK_PostPostInitial AS Con2Prim BEFORE ADMConstraintsGroup
+{
+} "Convert from conservative to primitive variables (might be redundant)"
+
+schedule group HydroBase_Prim2ConInitial AT Initial AFTER HydroBase_Initial
+{
+} "Recover the conservative variables from the primitive variables"
+
diff --git a/src/StartUp.c b/src/StartUp.c
new file mode 100644
index 0000000..ced68a6
--- /dev/null
+++ b/src/StartUp.c
@@ -0,0 +1,16 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <math.h>
+#include <assert.h>
+
+#include <cctk.h>
+#include <cctk_Arguments.h>
+#include <cctk_Parameters.h>
+
+int HydroBase_StartUp()
+{
+    CCTK_RegisterBanner("HydroBase: Let it flow.");
+
+    return 0;
+}
+
diff --git a/src/make.code.defn b/src/make.code.defn
new file mode 100755
index 0000000..7f86d75
--- /dev/null
+++ b/src/make.code.defn
@@ -0,0 +1,8 @@
+# Main make.code.defn file for thorn HydroBase
+
+# Source files in this directory
+SRCS = StartUp.c
+
+# Subdirectories containing source files
+SUBDIRS = 
+