HydroBase

Tanja Bode <tanja.bode@physics.gatech.edu>
Frank Löffler <knarf@cct.lsu.edu>

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 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.

2 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 [1] for details):

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:

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.

3 Units

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_{\mathrm {sun}} = 1 &;& c = G = 1 \end {eqnarray}

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 definitions and constants of nature:

\begin {eqnarray} c & = & 299792458\, \mathrm {m/s} \\ G & = & 6.67428\cdot 10^{-11}\, \mathrm {m^3/kg/s^2} \\ \mu _0 & = & 4 \pi 10^{-7}\, \mathrm {N/A^2} \\ \epsilon _0 & = & \frac {1}{\mu _0 c^2} \\ M_{\mathrm {sun}} & = & 1.98892\cdot 10^{30}\, \mathrm {kg} \end {eqnarray}

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

\begin {eqnarray} [M] & = & M_{\mathrm {sun}} \\{} [L] & = & [M]\; G/c^2 \\{} [T] & = & [L]\; / c \\{} [B] & = & 1/[L]\; / \sqrt {\epsilon _0 G / c^2} \qquad (\mathrm {SI}) \\{} [B] & = & c^2/[L]\; / \sqrt {G} \qquad \qquad (\mathrm {Gaussian}) \end {eqnarray}

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

\begin {eqnarray} [L] & = & 1\, M_{\mathrm {sun}} \equiv 1.477\, \mathrm {km} \\{} [T] & = & 1\, M_{\mathrm {sun}} \equiv 4.92673\, \mathrm {\mu s} \\{} [B] & = & 1\, \sqrt {\mu _0/4\pi } /M_{\mathrm {sun}} \equiv 2.35537\cdot 10^{15}\, \mathrm {T}, \qquad (\mathrm {SI}) \\{} [B] & = & 1\, M^{-1}_{\mathrm {sun}} \equiv 2.35537\cdot 10^{19}\, \mathrm {G}, \qquad \qquad \qquad (\mathrm {Gaussian}) \end {eqnarray}

where T (Tesla) is the magnetic field unit in SI, \(1\,\mathrm {T}=1\,\mathrm {N/(A\cdot m)}\), and G (Gauss) is its cgs equivalent, \(1\,\mathrm {Tesla} = 10^4\,\mathrm {Gauss}\).

4 Acknowledgments

This thorn was produced by Tanja Bode, Roland Haas, Frank Löffler, 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 off (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 file
Read the initial data using the IOUtil file reader. Note that this only allows you to read the data from a file, it does not actually do it. You still have to programme the IOUtil file reader accordingly.






initial_aphi
Scope: restricted  KEYWORD



Description: Initial value for Aphi



Range   Default: none
none
inactive
zero
initially set to zero
read from file
Read the initial data using the IOUtil file reader. Note that this only allows you to read the data from a file, it does not actually do it. You still have to programme the IOUtil file reader accordingly.






initial_avec
Scope: restricted  KEYWORD



Description: Initial value for Avec



Range   Default: none
none
inactive
zero
initially set to zero
read from file
Read the initial data using the IOUtil file reader. Note that this only allows you to read the data from a file, it does not actually do it. You still have to programme the IOUtil file reader accordingly.






initial_bvec
Scope: restricted  KEYWORD



Description: Initial value for Bvec



Range   Default: none
none
inactive
zero
initially set to zero
read from file
Read the initial data using the IOUtil file reader. Note that this only allows you to read the data from a file, it does not actually do it. You still have to programme the IOUtil file reader accordingly.






initial_entropy
Scope: restricted  KEYWORD



Description: Initial value for entropy



Range   Default: none
none
inactive
zero
initially set to zero
read from file
Read the initial data using the IOUtil file reader. Note that this only allows you to read the data from a file, it does not actually do it. You still have to programme the IOUtil file 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 file
Read the initial data using the IOUtil file reader. Note that this only allows you to read the data from a file, it does not actually do it. You still have to programme the IOUtil file reader accordingly.






initial_temperature
Scope: restricted  KEYWORD



Description: Initial value for temperature



Range   Default: none
none
inactive
zero
initially set to zero
read from file
Read the initial data using the IOUtil file reader. Note that this only allows you to read the data from a file, it does not actually do it. You still have to programme the IOUtil file 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 file
Read the initial data using the IOUtil file reader. Note that this only allows you to read the data from a file, it does not actually do it. You still have to programme the IOUtil file 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 fifth 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






filereader_id_vars
Scope: shared from IO STRING



6 Interfaces

General

Implements:

hydrobase

Inherits:

initbase

Grid Variables

6.0.1 PUBLIC GROUPS




  Group Names    Variable Names    Details   




rho rho   compact0
  descriptionrest mass density
  dimensions3
  distributionDEFAULT
  group typeGF
  tagsProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”Scalar” interpolator=”matter”
  timelevels3
 variable typeREAL




press press   compact0
  descriptiongas pressure
  dimensions3
  distributionDEFAULT
  group typeGF
  tagsProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”Scalar” interpolator=”matter”
  timelevels3
 variable typeREAL




eps eps   compact0
  descriptionspecific internal energy
  dimensions3
  distributionDEFAULT
  group typeGF
  tagsProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”Scalar” interpolator=”matter”
  timelevels3
 variable typeREAL




vel vel   compact0
  descriptionvelocity vî
  dimensions3
  distributionDEFAULT
  group typeGF
  tagsProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”U” interpolator=”matter”
  timelevels3
 vararray_size3
 variable typeREAL




w_lorentz w_lorentz   compact0
  descriptionLorentz Factor
  dimensions3
  distributionDEFAULT
  group typeGF
  tagsProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”Scalar” interpolator=”matter”
  timelevels3
 variable typeREAL




y_e Y_e   compact0
  descriptionElectron Fraction
  dimensions3
  distributionDEFAULT
  group typeGF
  tagsProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”Scalar” interpolator=”matter”
  timelevels3
 variable typeREAL








  Group Names    Variable Names    Details   




abar Abar   compact0
  descriptionAverage atomic mass [atomic mass unit]
  dimensions3
  distributionDEFAULT
  group typeGF
  tagsProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”Scalar” interpolator=”matter”
  timelevels3
 variable typeREAL




temperature temperature   compact0
  descriptionTemperature [MeV]
  dimensions3
  distributionDEFAULT
  group typeGF
  tagsProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”Scalar” interpolator=”matter”
  timelevels3
 variable typeREAL




entropy entropy   compact0
  descriptionSpecific Entropy [k_b/baryon]
  dimensions3
  distributionDEFAULT
  group typeGF
  tagsProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”Scalar” interpolator=”matter”
  timelevels3
 variable typeREAL




bvec Bvec   compact0
  descriptionMagnetic field components Bî
  dimensions3
  distributionDEFAULT
  group typeGF
  tagsProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”U” tensorparity=-1 interpolator=”matter”
  timelevels3
 vararray_size3
 variable typeREAL




avec Avec   compact0
  descriptionVector potential
  dimensions3
  distributionDEFAULT
  group typeGF
  tagsProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”D” jacobian=”jacobian” interpolator=”matter”
  timelevels3
 vararray_size3
 variable typeREAL




aphi Aphi   compact0
  descriptionElectric potential for Lorentz Gauge
  dimensions3
  distributionDEFAULT
  group typeGF
  tagsProlongationParameter=”HydroBase::prolongation_type” tensortypealias=”Scalar” jacobian=”jacobian” interpolator=”matter”
  timelevels3
 variable typeREAL








  Group Names    Variable Names    Details   




hydro_excision_mask hydro_excision_mask   compact0
  descriptionMask for hydro excision
  dimensions3
  distributionDEFAULT
  group typeGF
  tagsProlongation=”None” checkpoint=”no”
  timelevels1
 variable typeINT




Adds header:

HydroBase.h

Uses header:

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

 

Always: Conditional:
rho[timelevels] press[timelevels]
eps[timelevels] temperature[timelevels]
vel[timelevels] entropy[timelevels]
w_lorentz[timelevels]hydro_excision_mask
  Y_e[timelevels]
  Abar[timelevels]
  Bvec[timelevels]
  Avec[timelevels]
  Aphi[timelevels]
   

Scheduled Functions

CCTK_INITIAL (conditional)

  hydrobase_initial

  hydrobase initial data group

 

 After: admbase_initialdata
    admbase_initialgauge
   ioutil_recoveridfromdatafiles
 Before:admbase_postinitial
   settmunu
 Type: 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
 Writes: hydrobase::rho(everywhere)
   rho_p(everywhere)
   rho_p_p(everywhere)
   hydrobase::vel(everywhere)
   vel_p(everywhere)
   vel_p_p(everywhere)
   hydrobase::w_lorentz(everywhere)
   w_lorentz_p(everywhere)
   w_lorentz_p_p(everywhere)
   hydrobase::eps(everywhere)
   eps_p(everywhere)
   eps_p_p(everywhere)
   hydrobase::abar(everywhere)
   abar_p(everywhere)
   abar_p_p(everywhere)
   hydrobase::temperature(everywhere)
   temperature_p(everywhere)
   temperature_p_p(everywhere)
   hydrobase::entropy(everywhere)
   entropy_p(everywhere)
   entropy_p_p(everywhere)

HydroBase_Initial (conditional)

  hydrobase_y_e_one

  set electron fraction to 1

 

 Language:c
 Type: function
 Writes: hydrobase::y_e(everywhere)
   y_e_p(everywhere)
   y_e_p_p(everywhere)

HydroBase_Initial (conditional)

  hydrobase_bvec_zero

  set magnetic field to 0

 

 Language:c
 Type: function
 Writes: hydrobase::bvec(everywhere)
   bvec_p(everywhere)
   bvec_p_p(everywhere)

HydroBase_Initial (conditional)

  hydrobase_avec_zero

  set vector potential to 0

 

 Language:c
 Type: function
 Writes: hydrobase::avec(everywhere)
   avec_p(everywhere)
   avec_p_p(everywhere)

HydroBase_Initial (conditional)

  hydrobase_aphi_zero

  set vector potential phi to 0

 

 Language:c
 Type: function
 Writes: hydrobase::aphi(everywhere)
   aphi_p(everywhere)
   aphi_p_p(everywhere)

HydroBase_Initial (conditional)

  hydrobase_excisionmasksetup

  set up hydro excision mask

 

 Type:group

CCTK_POSTREGRIDINITIAL (conditional)

  hydrobase_excisionmasksetup

  set up hydro excision mask

 

 Before:mol_poststep
 Type: group

CCTK_POSTREGRID (conditional)

  hydrobase_excisionmasksetup

  set up hydro excision mask

 

 Before:mol_poststep
 Type: group

CCTK_POST_RECOVER_VARIABLES (conditional)

  hydrobase_excisionmasksetup

  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

HydroBase_ExcisionMaskSetup (conditional)

  hydrobase_initexcisionmask

  initialize hydro excision mask to ’no excision everywhere’

 

 Language:c
 Type: function
 Writes: hydrobase::hydro_excision_mask(everywhere)

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

 

 After: admbase_setadmvars
  Before:settmunu
 Type: group

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