1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
% 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.
\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}
\author{Erik Schnetter \textless schnetter@cct.lsu.edu\textgreater}
\title{TmunuBase}
\date{2008-04-07}
\maketitle
% Do not delete next line
% START CACTUS THORNGUIDE
\begin{abstract}
Provide grid functions for the stress-energy tensor $T_{\mu\nu}$,
and schedule when these grid functions are calculated. This allows
different thorns to cooperate without explicitly depending on each
other. This thorn is compatible with the \texttt{CalcTmumu.inc}
interface, in the sense that thorns using this interface will work
correctly with TmunuBase. Thorn TmunuBase is for the stress-energy
tensor what thorn ADMBase is for the metric tensor.
\end{abstract}
\section{Introduction}
Thorn \texttt{TmunuBase} provides core infrastructure for thorns
implementing some kind of energy or matter in general relativity, for
example general relativistic hydrodynamics formulations. It provides
the basic variables, i.e., the stress-energy tensor $T_{\mu\nu}$, in
addition to a set of parameters to regulate their use. These
variables are used to communicate between (possibly multiple) thorns
contributing to the stress-energy content of the spacetime, and thorns
needing to evaluate the stress-energy tensor such as spacetime
evolution methods. It also provides schedule groups to manage when
$T_{\mu\nu}$ is calculated and when it is ready for access.
\section{Using TmunuBase}
\subsection{Variables}
TmunuBase weakly assumes (but does not require) that the spacetime is
described in terms of a $3+1$ decomposition. The variables provided
by \texttt{TmunuBase} are:
\begin{itemize}
\item The ``scalar'' part of $T_{\mu\nu}$, its time-time component:
\texttt{eTtt}
\item The ``vector'' part of $T_{\mu\nu}$, its time-space components:
\texttt{eTtx}, \texttt{eTty}, \texttt{eTtz}
\item The ``tensor'' part of $T_{\mu\nu}$, its space-space components:
\texttt{eTxx}, \texttt{eTxy}, \texttt{eTxz}, \texttt{eTyy},
\texttt{eTyz}, \texttt{eTzz}
\end{itemize}
These components have the prefix \texttt{e} to avoid naming conflicts
with existing variables. Many thorns dealing with matter already use
variable names such as \texttt{Ttt}.
These variables have up to three time levels.
\subsection{Parameters}
By default, the TmunuBase variables have no storage, and TmunuBase is
inactive. This makes it possible to add a matter interface to
existing vacuum spacetime methods without changing their behaviour.
Several parameters choose how TmunuBase behaves at run time:
\begin{itemize}
\item The parameter \texttt{stress\_energy\_storage} activates storage
for $T_{\mu\nu}$ and enables the schedule groups which calculate it.
\item The parameter \texttt{stress\_energy\_at\_RHS} moves calculating
the $T_{\mu\nu}$ from the \texttt{evol} bin into the
\texttt{MoL\_PostStep} group. This increases the order of accuracy
of the spacetime--matter coupling, but is only possible when thorn
MoL is used.\footnote{This was one of the main reason why thorn MoL
was instroduced.} Generally, this parameter should be set when
MoL is used.
\item The parameter \texttt{timelevels} chooses the number of time
levels for $T_{\mu\nu}$. The default is a single time level, which
is sufficient for unigrid simulation. Mesh refinement simulation
may require several time levels if mesh refinement boundaries
require correct values.
\item The parameter \texttt{prolongation\_type} defines the
prolongation operator for mesh refinement boundaries. The default
is Lagrange interpolation.
\end{itemize}
The grid scalar \texttt{stress\_energy\_state} describes whether the
$T_{\mu\nu}$ variables have storage.
\section{Programming with TmunuBase}
\subsection{Contributing to $T_{\mu\nu}$}
There may be multiple thorns contributing to $T_{\mu\nu}$. Therefore,
thorn TmunuBase initialises $T_{\mu\nu}$ to zero, and each thorn has
to add to the existing values in $T_{\mu\nu}$. The corresponding
routine should be scheduled in the bin \texttt{AddToTmunu}.
\emph{Note:} Do not schedule anything in the schedule bin
\texttt{SetTmunu}.
\subsection{Reading from $T_{\mu\nu}$}
Since the values of $T_{\mu\nu}$ change at each time step, or -- if a
thorn like \texttt{MoL} is used -- at each substep, $T_{\mu\nu}$ needs
to be recalculated frequently. This happens either in the schedule
bin \texttt{evol} or in the schedule group \texttt{MoL\_PostStep}.
$T_{\mu\nu}$ may only be accessed after it has been calculated, e.g.\
\texttt{IN MoL\_PostStep AFTER SetTmunu}. $T_{\mu\nu}$ can be freely
accessed at other times, e.g.\ in \texttt{MoL\_CalcRHS} or at
\texttt{poststep} or \texttt{analyisis}.
\section{Compatibility to ADMCoupling}
Cactus provides another interface for contributing to the
stress-energy tensor, called \texttt{CalcTmunu}. This alternative
interface (which is described in thorn \texttt{ADMCoupling}) requires
writing routines in fixed-format Fortran 77 and inserting lines of
code into a file \texttt{CalcTmunu.inc}. We suggest to use exactly
one of these two interface and not to mix them.
Thorn TmunuBase takes contributions from the \texttt{CalcTmunu}
interface automatically into account as well. It also collects the
values which are added to its $T_{\mu\nu}$ and provides these to other
thorns which use the \texttt{CalcTmunu.inc} interface. That is, thorn
TmunuBase is fully backwards compatible.
\subsection{Comparison to ADMCoupling}
The \texttt{CalcTmunu} interface and this thorn TmunuBase make
different space/performance tradeoffs. \texttt{CalcTmunu} does not
store any components of the stress-energy tensor, which saves memory
and is also more efficient if its components can be quickly calculated
from other variables (presumably the state vector of a hydrodynamics
thorn).
TmunuBase requires explicit storage for $T_{\mu\nu}$. This is
necessary if $T_{\mu\nu}$ needs to be interpolated e.g.\ for dynamical
horizon calculations. Compared to the overall number of grid function
in a typical simulation the number of additional variables is
tolerable (typical numbers are 10 additional variables with 200
existing variables). With the exception of the parts ensuring
compatibility to \texttt{CalcTmunu}, TmunuBase is also a much simpler
and more flexible mechanism.
\subsection{Acknowledgements}
We thank I. Hawke for designing and implementing thorn MoL, without
which a generic high-order coupling between spacetime and
hydrodynamics methods would not be possible.
% Do not delete next line
% END CACTUS THORNGUIDE
\end{document}
|
