## HydroBase

April 29, 2010

Abstract

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 to implement any hydrodynamics formulation.

### 1 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 diﬀerent hydrodynamics codes. It should contain the common concepts of diﬀerent 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 diﬀerent formulations of the hydrodynamics equations and not all of them involve concepts like conserved variabled or treat them diﬀerently, which is the reason why these variables are not deﬁned 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 deﬁned 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 diﬀerent hydrodynamics codes in Cactus would be the same, including variable names and unit conventions, which would improve the ability to compare results of diﬀerent codes directly a lot.

### 2 Using this Thorn

HydroBase is to be used as a central part of hydrodynamics ﬁelds 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 diﬀerent hydrodynamics codes creates the possibility to share parts of the code, e.g. initial data solvers or analysis routines.

Currently the deﬁned primitive variables are (see [1] for details):

• rho: rest mass density $\varrho$
• press: pressure $p$
• eps: speciﬁc internal energy $𝜖$
• vel[3]: contravariant ﬂuid three velocity ${v}^{i}$ with respect to the Eulerian observer deﬁned as  ${v}^{i}=\frac{{u}^{i}}{\alpha {u}^{0}}+\frac{{\beta }^{i}}{\alpha }$ (1)

in terms of the four-velocity ${u}^{\mu }$, lapse $\alpha$, and shift vector ${\beta }^{i}$.

• Y_e: electron fraction ${Y}_{e}$
• temperature: temperature $T$
• entropy: speciﬁc entropy per particle $s$
• Bvec[3]: contravariant magnetic ﬁeld vector deﬁned as  ${B}^{i}=\frac{1}{\sqrt{4\pi }}{n}_{\nu }{F}^{\ast \nu i}$ (2)

in terms of the dual ${F}^{\ast \mu \nu }=\frac{1}{2}{𝜀}^{\mu \nu \alpha \beta }{F}_{\alpha \beta }$ to the Faraday tensor and the unit normal of the foliation of spacetime ${n}^{\mu }$.

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:

• Initializing the primitive variables
• Converting primitive variables to conservative variables
• Calculating the right hand side (RHS) in the method of lines (MoL)
• Setting and updating an excision mask
• Applying boundary conditions

In this way the initiation of the primitive variables, methods to recover the conservative variables, and basic atmosphere handling can be implemented in diﬀerent thorns while allowing a central access point for analysis thorns.

### 3 Units

HydroBase does not require a speciﬁc set of units itself. However so that there are no misunderstandings between thorns a speciﬁc set of units is suggested. These units are derived from the conventions

$\begin{array}{rcll}{M}_{sun}=1& ;& c=G=1& \text{(3)}\text{}\text{}\end{array}$

which are commonly used in astrophysics and in relativity. The former sets the mass scale to the solar one and the latter adopts the same units for time, length and mass.

We assume the following deﬁnitions and constants of nature:

$\begin{array}{rcll}c& =& 299792458\phantom{\rule{0.3em}{0ex}}m∕s& \text{(4)}\text{}\text{}\\ G& =& 6.67428\cdot 1{0}^{-11}\phantom{\rule{0.3em}{0ex}}{m}^{3}∕kg∕{s}^{2}& \text{(5)}\text{}\text{}\\ {\mu }_{0}& =& 4\pi 1{0}^{-7}\phantom{\rule{0.3em}{0ex}}N∕{A}^{2}& \text{(6)}\text{}\text{}\\ {𝜖}_{0}& =& \frac{1}{{\mu }_{0}{c}^{2}}& \text{(7)}\text{}\text{}\\ {M}_{sun}& =& 1.98892\cdot 1{0}^{30}\phantom{\rule{0.3em}{0ex}}kg& \text{(8)}\text{}\text{}\end{array}$

This corresponds to the following units for mass, length, time, and magnetic ﬁeld:

$\begin{array}{rcll}\left[M\right]& =& {M}_{sun}& \text{(9)}\text{}\text{}\\ \left[L\right]& =& \left[M\right]\phantom{\rule{2.77695pt}{0ex}}G∕{c}^{2}& \text{(10)}\text{}\text{}\\ \left[T\right]& =& \left[L\right]\phantom{\rule{2.77695pt}{0ex}}∕c& \text{(11)}\text{}\text{}\\ \left[B\right]& =& 1∕\left[L\right]\phantom{\rule{2.77695pt}{0ex}}∕\sqrt{{𝜖}_{0}G∕{c}^{2}}\phantom{\rule{2em}{0ex}}\left(SI\right)& \text{(12)}\text{}\text{}\\ \left[B\right]& =& {c}^{2}∕\left[L\right]\phantom{\rule{2.77695pt}{0ex}}∕\sqrt{G}\phantom{\rule{2em}{0ex}}\phantom{\rule{2em}{0ex}}\left(Gaussian\right)& \text{(13)}\text{}\text{}\end{array}$

Inserting the SI units into the above unit correspondences, we ﬁnd the following conversion factors:

$\begin{array}{rcll}\left[L\right]& =& 1\phantom{\rule{0.3em}{0ex}}{M}_{sun}\equiv 1.477\phantom{\rule{0.3em}{0ex}}km& \text{(14)}\text{}\text{}\\ \left[T\right]& =& 1\phantom{\rule{0.3em}{0ex}}{M}_{sun}\equiv 4.92673\phantom{\rule{0.3em}{0ex}}\mu s& \text{(15)}\text{}\text{}\\ \left[B\right]& =& 1\phantom{\rule{0.3em}{0ex}}\sqrt{{\mu }_{0}∕4\pi }∕{M}_{sun}\equiv 2.35537\cdot 1{0}^{15}\phantom{\rule{0.3em}{0ex}}T,\phantom{\rule{2em}{0ex}}\left(SI\right)& \text{(16)}\text{}\text{}\\ \left[B\right]& =& 1\phantom{\rule{0.3em}{0ex}}{M}_{sun}^{-1}\equiv 2.35537\cdot 1{0}^{19}\phantom{\rule{0.3em}{0ex}}G,\phantom{\rule{2em}{0ex}}\phantom{\rule{2em}{0ex}}\phantom{\rule{2em}{0ex}}\left(Gaussian\right)& \text{(17)}\text{}\text{}\end{array}$

where T (Tesla) is the magnetic ﬁeld unit in SI, $1\phantom{\rule{0.3em}{0ex}}T=1\phantom{\rule{0.3em}{0ex}}N∕\left(A\cdot m\right)$, and G (Gauss) is its cgs equivalent, $1\phantom{\rule{0.3em}{0ex}}Tesla=1{0}^{4}\phantom{\rule{0.3em}{0ex}}Gauss$.

### 4 Acknowledgments

This thorn was produced by Tanja Bode, Roland Haas, Frank Löﬄer, and Erik Schnetter.

### References

[1]   J. A. Font. Numerical hydrodynamics in General Relativity. Living Rev. Relativity, 3, 2000. [Article in on-line journal], cited on 31/07/01, http://www.livingreviews.org/ Articles/Volume3/2000-2font/index.html.

[2]   F. Banyuls, J. A. Font, J. M. A. Ibanez, J. M. A. Marti, and J. A. Miralles. Numerical 3+1 General Relativistic Hydrodynamics: A Local Characteristic Approach. ApJ, 476, 221, 1997.

[3]   L. Antón, O. Zanotti, J. A. Miralles, J. M. Martí, J. M. Ibáñez, J. A. Font, and J. A Pons. Numerical 3+1 General Relativistic Magnetohydrodynamics: A Local Characteristic Approach. ApJ, 637, 296 – 312, 2006.

### 5 Parameters

 abar_evolution_method Scope: restricted KEYWORD Description: Evolution method for Abar Range Default: none none Evolution for Abar is disabled

 bvec_evolution_method Scope: restricted KEYWORD Description: Evolution method for Bvec Range Default: none none Evolution for Bvec is disabled

 entropy_evolution_method Scope: restricted KEYWORD Description: Evolution method for entropy Range Default: none none Evolution for entropy is disabled

 evolution_method Scope: restricted KEYWORD Description: The hydro evolution method Range Default: none none hydro variables are not evolved

 hydro_excision Scope: restricted INT Description: Turn on of oﬀ (default) storage for hydro excision Range Default: (none) 0:* Anything else than 0 turns hydro_excision on, added to by other thorns

 initial_abar Scope: restricted KEYWORD Description: Initial value for Abar Range Default: none none inactive zero initially set to zero read from ﬁle Read the initial data using the IOUtil ﬁle reader. Note that this only allows you to read the data from a ﬁle, it does not actually do it. You still have to programme the IOUtil ﬁle reader accordingly.

 initial_aphi Scope: restricted KEYWORD Description: Initial value for Aphi Range Default: none none inactive zero initially set to zero read from ﬁle Read the initial data using the IOUtil ﬁle reader. Note that this only allows you to read the data from a ﬁle, it does not actually do it. You still have to programme the IOUtil ﬁle reader accordingly.

 initial_avec Scope: restricted KEYWORD Description: Initial value for Avec Range Default: none none inactive zero initially set to zero read from ﬁle Read the initial data using the IOUtil ﬁle reader. Note that this only allows you to read the data from a ﬁle, it does not actually do it. You still have to programme the IOUtil ﬁle reader accordingly.

 initial_bvec Scope: restricted KEYWORD Description: Initial value for Bvec Range Default: none none inactive zero initially set to zero read from ﬁle Read the initial data using the IOUtil ﬁle reader. Note that this only allows you to read the data from a ﬁle, it does not actually do it. You still have to programme the IOUtil ﬁle reader accordingly.

 initial_entropy Scope: restricted KEYWORD Description: Initial value for entropy Range Default: none none inactive zero initially set to zero read from ﬁle Read the initial data using the IOUtil ﬁle reader. Note that this only allows you to read the data from a ﬁle, it does not actually do it. You still have to programme the IOUtil ﬁle reader accordingly.

 initial_hydro Scope: restricted KEYWORD Description: The hydro initial data Range Default: zero zero hydro variables are set to vacuum (without atmosphere) read from ﬁle Read the initial data using the IOUtil ﬁle reader. Note that this only allows you to read the data from a ﬁle, it does not actually do it. You still have to programme the IOUtil ﬁle reader accordingly.

 initial_temperature Scope: restricted KEYWORD Description: Initial value for temperature Range Default: none none inactive zero initially set to zero read from ﬁle Read the initial data using the IOUtil ﬁle reader. Note that this only allows you to read the data from a ﬁle, it does not actually do it. You still have to programme the IOUtil ﬁle reader accordingly.

 initial_y_e Scope: restricted KEYWORD Description: Initial value for Y_e Range Default: none none inactive one initially set to one read from ﬁle Read the initial data using the IOUtil ﬁle reader. Note that this only allows you to read the data from a ﬁle, it does not actually do it. You still have to programme the IOUtil ﬁle reader accordingly.

 prolongation_type Scope: restricted STRING Description: The prolongation operator used by Carpet for HydroBase variables Range Default: ENO ENO Third order ENO operators; only third order is implemented WENO Fifth order WENO operators; only ﬁfth order is implemented .* Anything else

 temperature_evolution_method Scope: restricted KEYWORD Description: Evolution method for temperature Range Default: none none Evolution for temperature is disabled

 timelevels Scope: restricted INT Description: Number of time levels in evolution scheme Range Default: 1 1:3

 y_e_evolution_method Scope: restricted KEYWORD Description: Evolution method for Y_e Range Default: none none Evolution for Y_e is disabled

 ﬁlereader_id_vars Scope: shared from IO STRING

### 6 Interfaces

Implements:

hydrobase

Inherits:

initbase

#### Grid Variables

##### 6.0.1 PUBLIC GROUPS
 Group Names Variable Names Details rho compact 0 rho description rest mass density dimensions 3 distribution DEFAULT group type GF tags ProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”Scalar” interpolator=”matter” timelevels 3 variable type REAL press compact 0 press description gas pressure dimensions 3 distribution DEFAULT group type GF tags ProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”Scalar” interpolator=”matter” timelevels 3 variable type REAL eps compact 0 eps description speciﬁc internal energy dimensions 3 distribution DEFAULT group type GF tags ProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”Scalar” interpolator=”matter” timelevels 3 variable type REAL vel compact 0 vel description velocity vî dimensions 3 distribution DEFAULT group type GF tags ProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”U” interpolator=”matter” timelevels 3 vararray_size 3 variable type REAL w_lorentz compact 0 w_lorentz description Lorentz Factor dimensions 3 distribution DEFAULT group type GF tags ProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”Scalar” interpolator=”matter” timelevels 3 variable type REAL y_e compact 0 Y_e description Electron Fraction dimensions 3 distribution DEFAULT group type GF tags ProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”Scalar” interpolator=”matter” timelevels 3 variable type REAL
 Group Names Variable Names Details abar compact 0 Abar description Average atomic mass [atomic mass unit] dimensions 3 distribution DEFAULT group type GF tags ProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”Scalar” interpolator=”matter” timelevels 3 variable type REAL temperature compact 0 temperature description Temperature [MeV] dimensions 3 distribution DEFAULT group type GF tags ProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”Scalar” interpolator=”matter” timelevels 3 variable type REAL entropy compact 0 entropy description Speciﬁc Entropy [k_b/baryon] dimensions 3 distribution DEFAULT group type GF tags ProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”Scalar” interpolator=”matter” timelevels 3 variable type REAL bvec compact 0 Bvec description Magnetic ﬁeld components Bî dimensions 3 distribution DEFAULT group type GF tags ProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”U” tensorparity=-1 interpolator=”matter” timelevels 3 vararray_size 3 variable type REAL avec compact 0 Avec description Vector potential dimensions 3 distribution DEFAULT group type GF tags ProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”D” jacobian=”jacobian” interpolator=”matter” timelevels 3 vararray_size 3 variable type REAL aphi compact 0 Aphi description Electric potential for Lorentz Gauge dimensions 3 distribution DEFAULT group type GF tags ProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”Scalar” jacobian=”jacobian” interpolator=”matter” timelevels 3 variable type REAL
 Group Names Variable Names Details hydro_excision_mask compact 0 hydro_excision_mask description Mask for hydro excision dimensions 3 distribution DEFAULT group type GF tags Prolongation=”None” checkpoint=”no” timelevels 1 variable type INT

HydroBase.h

HydroBase.h

### 7 Schedule

This section lists all the variables which are assigned storage by thorn EinsteinBase/HydroBase. Storage can either last for the duration of the run (Always means that if this thorn is activated storage will be assigned, Conditional means that if this thorn is activated storage will be assigned for the duration of the run if some condition is met), or can be turned on for the duration of a schedule function.

#### Storage

 Conditional: rho[1] press[1] temperature[1] entropy[1] rho[2] press[2] eps[2] vel[2] w_lorentz[2] Y_e[2] Abar[2] Bvec[2] eps[1] Avec[2] Aphi[2] temperature[2] entropy[2] rho[3] press[3] eps[3] vel[3] w_lorentz[3] Y_e[3] vel[1] Abar[3] Bvec[3] Avec[3] Aphi[3] temperature[3] entropy[3] hydro_excision_mask w_lorentz[1] Y_e[1] Abar[1] Bvec[1] Avec[1] Aphi[1]

#### Scheduled Functions

CCTK_INITIAL (conditional)

hydrobase_initial

hydrobase initial data group

CCTK_STARTUP (conditional)

hydrobase_startup

startup banner

 Language: c Type: function

CCTK_INITIAL (conditional)

hydrobase_prim2coninitial

recover the conservative variables from the primitive variables

 After: hydrobase_initial Before: settmunu Type: group

HydroBase_Initial (conditional)

hydrobase_zero

set up vacuum hydro initial data

 Language: c Type: function

HydroBase_Initial (conditional)

hydrobase_y_e_one

set electron fraction to 1

 Language: c Type: function

HydroBase_Initial (conditional)

hydrobase_bvec_zero

set magnetic ﬁeld to 0

 Language: c Type: function

HydroBase_Initial (conditional)

hydrobase_avec_zero

set vector potential to 0

 Language: c Type: function

HydroBase_Initial (conditional)

hydrobase_aphi_zero

set vector potential phi to 0

 Language: c Type: function

HydroBase_Initial (conditional)

set up hydro excision mask

 Type: group

CCTK_POSTREGRIDINITIAL (conditional)

set up hydro excision mask

 Before: mol_poststep Type: group

CCTK_POSTREGRID (conditional)

set up hydro excision mask

 Before: mol_poststep Type: group

CCTK_POST_RECOVER_VARIABLES (conditional)

set up hydro excision mask

 Before: mol_poststep Type: group

CCTK_PARAMCHECK (conditional)

hydrobase_paramcheck

check that hydrobase parameters are consistent

 Language: c Type: function

initialize hydro excision mask to ’no excision everywhere’

 Language: c Type: function

CCTK_POSTSTEP (conditional)

hydrobase_excisionhasbeenset

group to schedule thorns changing the mask before and thorns using the mask after

 Type: group

MoL_CalcRHS (conditional)

hydrobase_rhs

groups for scheduling tasks for calculating rhs of hydro variables

 Type: group

MoL_PostStep (conditional)

hydrobase_poststep

post step tasks for hydro thorns

HydroBase_PostStep (conditional)

hydrobase_boundaries

hydrobase-internal boundary conditions group

 Before: hydrobase_con2prim Type: group

HydroBase_Boundaries (conditional)

hydrobase_select_boundaries

group to schedule the boundary condition functions

 Type: group

HydroBase_Boundaries (conditional)

applybcs

apply the boundary conditions of hydrobase

 After: hydrobase_select_boundaries Type: group

HydroBase_PostStep (conditional)

hydrobase_con2prim

convert from conservative to primitive variables

 Type: group

CCTK_POSTPOSTINITIAL (conditional)

hydrobase_con2prim

convert from conservative to primitive variables (might be redundant)

 Before: admconstraintsgroup Type: group

#### Aliased Functions

 Alias Name: Function Name: ApplyBCs HydroBase_ApplyBCs HydroBase_Con2Prim Con2Prim