xx GRHayLib

GRHayLib

Samuel Cupp Leonardo Rosa Werneck Terrence Pierre Jacques

Zachariah Etienne

Date

Abstract

Provides access to the General Relativistic Hydrodynamics Library (GRHayL). This library provides a suite of functions for GRMHD evolution codes based on the IllinoisGRMHD code.

1 Introduction

This thorn provides access to the General Relativistic Hydrodynamics Library (GRHayL) through the GRHayLib.h header file. The library contains all the core components necessary to produce an IllinoisGRMHD-like code in a modular, infrastructure-agnostic form. These functions are tested via unit tests using GitHub Actions in the GRHayL repository.

For comprehensive documentation of GRHayL’s features, please visit the GitHub wiki. As a brief overview, the library is split into several ‘gems’ which are entirely self-contained. These are Atmosphere, Con2Prim, EOS, FluxxSource, Induction, Neutrinos, and Reconstruction. The GRHayLib implementation provides access to all these gems in its header file. Additionally, the thorn automatically initializes an instance of the ghlxparameters and ghlxeosxparameters structs. The instances are named ghlxparams and ghlxeos, and the pointers to these structs are provided by the GRHayLib.h header.

2 Equation of State

One of the more complicated part of GRMHD simulations is properly setting up the equation of state (EOS), especially for tabulated EOS. GRHayL provides both hybrid and tabulated EOS, and this information is passed to the library functions through ghlxeos. GRHayLib’s parameters control the initialization of this struct, so the user does not need to set any of the struct’s values unless they plan to manually adjust these parameters during the simulation. The EOSxtype parameter chooses the type of EOS, and the thorn then sets up the struct using the other parameters associated with this choice.

For several variables, there are minimum, atmosphere, and maximum parameters. We will refer to these as collectively limit parameters. For the limit parameters a given EOS uses, the atmosphere parameter is required. The other parameters either have defaults or are ignored if unset.

2.1 Hybrid EOS

The hybrid EOS requires several parameters to function properly. First, it needs the number of elements in the polytropic approximation. This is currently limited by GRHayL to 10 pieces. The transition values of rhoxb are set by rhoxppolyxin, and the associated Gamma values are stored in Gammaxppolyxin. Note that for neos=1, only a single Gamma is necessary. Additionally, the parameter kxppoly0 sets the polytropic constant for the first piece of the piecewise polytrope. The rest of the constanst are computed automatically.

In addition to the polytropic setup above, the value of the thermal Gamma Gammaxth must be set.

The hybrid EOS only uses the rhoxb limit parameters. If unset, the minimum is set to 0, and the maximum is set to 1e300, effectively turning off both of these features.

2.2 Tabulated EOS

To properly configure for tabulated EOS, the most important parameter is the path to the EOS table, given by the EOSxtablepath parameter. GRHayLib automatically reads this table and makes it accessible to GRHayL functions through ghlxeos.

The tabulated EOS uses all the limit parameters (rhoxb, Yxe, and T). If unset, the mimima and maxima are set to table bounds.

3 Conservative-to-Primitive Routines

GRHayL provides a selection of con2prim routines along with automated backup methods. ghlxparams passes the information from the thorn parameters textttcon2primxroutine and textttcon2primxbackupxroutines to the library’s multi-method functions. Of course, any of the routines can be called manually with logic dictated by the user. However, we provide functions for automatically calling the selected routine, as well as triggering the backup routines in the case of failure. The ghlxcon2primxhybridxmultixmethod() and ghlxcon2primxtabulatedxmultixmethod() functions implement this feature, and the ghlxcon2primxhybridxselectxmethod() and ghlxcon2primxtabulatedxselectxmethod() functions directly select a single method based on an input value. GRHayL supports up to three backups, but more complex behavior can be designed by the user using the core con2prim functions. Since the individual con2prim routines and the multi-method functions have identical argument lists, swapping routines is straightforward and requires little work from the user.

These routines are iterative solvers, so they require an initial guess. IllinoisGRMHD used always used default guess, which is also provided in GRHayL. The calcxprimitivexguess parameter automatically sets the guess to this default in the multi-method function, so set this to ”no” to use a user-defined guess. Manual use of the con2prim routines require the user to either provide a guess or use the ghlxguessxprimitives() function.

4 Changing parameters during a run

Cactus allows for changing parameters during a run using CCTKxParameterSet(). However, this is only allowed for those with ”STEERABLE=ALWAYS” in the parfile. Those without this tag aren’t able to be steered during a run. Because GRHayLib stores this information inside GRHayL structs, the actual parameters are not steerable during a simulation. However, the parameters can be effectively steered by changing the values inside the structs. For the EOS struct, this can be dangerous since some elements are computed from the other parameters. To remedy this, the derived values need to also be recomputed. For the hybrid and simple EOS, we recommend running the appropriate ghlxinitializexEOSTYPExeos() function to ensure that the elements are properly reinitialized. For tabulated EOS, initializing the struct involves allocating memory for the table. As such, just re-running the initialize function will not behave as desired. The simplest solution is to copy the needed code from the GRHayL function into a scheduled function and manage the elements values manually.

5 Parameters

11 calcxprimitivexguess 10 Scope: restricted01 BOOLEAN

11 Description: Do we want to calculate estimates for the primitives in Con2Prim?

11 Range 10 01 Default: yes
11 no  10 Uses the data currently in the primitive variables as the guess.
11 yes  10 Calculates primitive guesses from the current conservatives.

11

11 con2primxbackupxroutines10 Scope: restricted01  KEYWORD

11 Description: We allow up to 3 backup routines

11 Range 10 01 Default: None
11 None  10 Don’t use backup routines
11 Noble2D  10 ”2D routine in https://arxiv.org/pd f/astro-ph/0512420.p df”
11 Noble1D  10 ”1Dw routine in https://arxiv.org/pd f/astro-ph/0512420.p df”
11 Noble1Dxentropy  10 ”1Dw routine in https://arxiv.org/pd f/astro-ph/0512420.p df, but uses the entropy”
11 Font1D  10 TODO
11 Palenzuela1D  10 ”https://arxiv.org/p df/1505.01607.pdf (see also https://arxiv.org/pd f/1712.07538.pdf)”
11 Newman1D  10 ”https://escholarshi p.org/content/qt0s53 f84b/qt0s53f84b.pdf (see also https://arxiv.org/pd f/1712.07538.pdf)”
11 see [1] below  10 ”https://arxiv.org/p df/1505.01607.pdf (see also https://arxiv.org/pd f/1712.07538.pdf)”
11 Newman1Dxentropy  10 ”https://escholarshi p.org/content/qt0s53 f84b/qt0s53f84b.pdf (see also https://arxiv.org/pd f/1712.07538.pdf)”

11

Palenzuela1D\_entropy

11 con2primxroutine  10 Scope: restricted01  KEYWORD

11 Description: What con2prim routine is used

11 Range 10 01 Default: Noble2D
11 Noble2D  10 ”2D routine in https://arxiv.org/pd f/astro-ph/0512420.p df”
11 Noble1D  10 ”1Dw routine in https://arxiv.org/pd f/astro-ph/0512420.p df”
11 Noble1Dxentropy  10 ”1Dw routine in https://arxiv.org/pd f/astro-ph/0512420.p df, but uses the entropy”
11 Font1D  10 TODO
11 Palenzuela1D  10 ”https://arxiv.org/p df/1505.01607.pdf (see also https://arxiv.org/pd f/1712.07538.pdf)”
11 Newman1D  10 ”https://escholarshi p.org/content/qt0s53 f84b/qt0s53f84b.pdf (see also https://arxiv.org/pd f/1712.07538.pdf)”
11 see [1] below  10 ”https://arxiv.org/p df/1505.01607.pdf (see also https://arxiv.org/pd f/1712.07538.pdf)”
11 Newman1Dxentropy  10 ”https://escholarshi p.org/content/qt0s53 f84b/qt0s53f84b.pdf (see also https://arxiv.org/pd f/1712.07538.pdf)”

11

Palenzuela1D\_entropy

11 eosxtablepath  10 Scope: restricted01  STRING

11 Description: Path to the EOS table

11 Range 10 01 Default: (none)
11                       10 Forbidden, will error out
11 .+?  10 Any string

11

11 eosxtype  10 Scope: restricted01  KEYWORD

11 Description: The type of EOS for the simulation

11 Range 10 01 Default: (none)
11                       10 Forbidden default; an EOS type must be specified
11 Simple  10 Simple EOS (often referred to as ’ideal fluid’ in literature)
11 Hybrid  10 Hybrid EOS
11 Tabulated  10 Tabulated EOS

11

11 evolvexentropy  10 Scope: restricted01  BOOLEAN

11 Description: Do we want to evolve the entropy?

11                       10                01  Default: no

11

11 evolvextemperature  10 Scope: restricted01  BOOLEAN

11 Description: Do we want to evolve the temperature?

11                       10                01  Default: no

11

11 gamma  10 Scope: restricted01  REAL

11 Description: Gamma parameter

11 Range 10 01 Default: -1
11 0:*  10 Physical values
11 -1  10 forbidden value to make sure it is explicitly set in the parfile

11

11 gammaxppolyxin  10 Scope: restricted01  REAL

11 Description: Set polytropic Gamma parameters. Gammaxppolyxin[0] goes from rho=0 to rho=rhoxppolyxin[0].

11  Range  10                01  Default: -1
11 0:*  10 value of Gamma for the polytropic rho in the bounds rhoxppoly[i-1] to rhoxppoly[i]
11 -1  10 forbidden value to make sure it is explicitly set in the parfile

11

11 gammaxth  10 Scope: restricted01  REAL

11 Description: thermal Gamma parameter

11 Range 10 01 Default: -1
11 0:*  10 Physical values
11 -1  10 forbidden value to make sure it is explicitly set in the parfile

11 kxppoly0  10 Scope: restricted01  REAL

11 Description: Also known as kxppoly[0], this is the polytropic constant for the lowest density piece of the piecewise polytrope. All other kxppoly elements are set using rhoxppolyxin and enforcing continuity in the equation of state.

11  Range  10                01  Default: -1
11 0:*  10 Physical values
11 -1  10 forbidden value to make sure it is explicitly set in the parfile

11

11 lorenzxdampingxfactor 10 Scope: restricted01  REAL

11 Description: Damping factor for the generalized Lorenz gauge. Has units of 1/length = 1/M. Typically set this parameter to 1.5/(maximum Delta t on AMR grids).

11  Range  10                01  Default: 0.0
11 *:*  10 any real

11

11 maxxlorentzxfactor  10 Scope: restricted01  REAL

11 Description: Maximum Lorentz factor.

11 Range 10 01 Default: 10.0
11 1:*  10 Positive > 1, though you’ll likely have troubles far above 10.

11

11 neos  10 Scope: restricted01  INT

11 Description: number of parameters in EOS table

11 Range 10 01 Default: 1
11 1:10  10 Any integer between 1 and 10

11

11 pxatm  10 Scope: restricted01  REAL

11 Description: Atmospheric pressure (required)

11 Range 10 01 Default: -1
11 0:*  10 Should be non-negative
11 -1  10 Used to check if anything was given

11

11 pxmax  10 Scope: restricted01  REAL

11 Description: Maximum temperature allowed (disabled by default)

11 Range 10 01 Default: -1
11 0:*  10 Should be non-negative
11 -1  10 Used to check if anything was given

11

11 pxmin  10 Scope: restricted01  REAL

11 Description: Minimum temperature allowed (disabled by default)

11 Range 10 01 Default: -1
11 0:*  10 Should be non-negative
11 -1  10 Used to check if anything was given

11

11 ppmxflatteningxepsilon 10 Scope: restricted01  REAL

11 Description: Epsilon used for flattening in PPM algorithm

11 Range 10 01 Default: 0.33
11 :  10 Anything goes. Default is from Colella & Woodward

11 ppmxflatteningxomega1 10 Scope: restricted01  REAL

11 Description: Omega1 used for flattening in PPM algorithm

11 Range 10 01 Default: 0.75
11 :  10 Anything goes. Default is from Colella & Woodward

11

11 ppmxflatteningxomega2 10 Scope: restricted01  REAL

11 Description: Omega2 used for flattening in PPM algorithm

11 Range 10 01 Default: 10.0
11 :  10 Anything goes. Default is from Colella & Woodward

11

11 ppmxshockxepsilon  10 Scope: restricted01  REAL

11 Description: Epsilon used for shock detection in steepenxrho algorithm

11 Range 10 01 Default: 0.01
11 :  10 Anything goes. Default is from Colella & Woodward

11

11 ppmxshockxeta1  10 Scope: restricted01  REAL

11 Description: Eta1 used for shock detection in steepenxrho algorithm

11 Range 10 01 Default: 20.0
11 :  10 Anything goes. Default is from Colella & Woodward

11

11 ppmxshockxeta2  10 Scope: restricted01  REAL

11 Description: Eta2 used for shock detection in steepenxrho algorithm

11 Range 10 01 Default: 0.05
11 :  10 Anything goes. Default is from Colella & Woodward

11

11 ppmxshockxk0  10 Scope: restricted01  REAL

11 Description: K0 used for shock detection in steepenxrho algorithm

11 Range 10 01 Default: 0.1
11 :  10 Anything goes. Default suggested by Colella & Woodward is: (polytropic constant)/10.0

11

11 psi6threshold  10 Scope: restricted01  REAL

11 Description: Where Psiˆ6 > Psi6threshold, we assume we’re inside the horizon in the primitives solver, and certain limits are relaxed or imposed

11  Range  10                01  Default: 1e100
11 *:*  10 Can set to anything

11

11 rhoxbxatm  10 Scope: restricted01  REAL

11 Description: Atmosphere value on the baryonic rest mass density rhoxb (required). If this is unset, the run will die.

11  Range  10                01  Default: -1
11 0:*  10 Atmosphere density; must be positive
11 -1  10 Used to check if anything was given

11 rhoxbxmax  10 Scope: restricted01  REAL

11 Description: Ceiling value on the baryonic rest mass density rhoxb (disabled by default). Can help with stability to limit densities inside the BH after black hole formation.

11  Range  10                01  Default: -1
11 0:*  10 Maximum density; must be positive
11 -1  10 Used to check if anything was given

11

11 rhoxbxmin  10 Scope: restricted01  REAL

11 Description: Floor value on the baryonic rest mass density rhoxb (disabled by default).

11 Range 10 01 Default: -1
11 0:*  10 Minimum density; must be positive
11 -1  10 Used to check if anything was given

11

11 rhoxppolyxin  10 Scope: restricted01  REAL

11 Description: Set polytropic rho parameters

11 Range 10 01 Default: -1
11 0:*  10 value of the density delimiters for the pieces of the piecewise polytrope
11 -1  10 forbidden value to make sure it is explicitly set in the parfile (only checked for neos > 1)

11

11 txatm  10 Scope: restricted01  REAL

11 Description: Atmospheric temperature (required)

11 Range 10 01 Default: -1
11 0:*  10 Should be non-negative
11 -1  10 Used to check if anything was given

11

11 txmax  10 Scope: restricted01  REAL

11 Description: Maximum temperature allowed (optional; table bounds used by default)

11 Range 10 01 Default: -1
11 0:*  10 Should be non-negative
11 -1  10 Used to check if anything was given

11

11 txmin  10 Scope: restricted01  REAL

11 Description: Minimum temperature allowed (optional; table bounds used by default)

11 Range 10 01 Default: -1
11 0:*  10 Should be non-negative
11 -1  10 Used to check if anything was given

11

11 yxexatm  10 Scope: restricted01  REAL

11 Description: Atmospheric electron fraction (required)

11 Range 10 01 Default: -1
11 0:1  10 Only makes sense if set to something between 0 and 1
11 -1  10 Used to check if anything was given

11 yxexmax  10 Scope: restricted01  REAL

11 Description: Atmospheric electron fraction (optional; table bounds used by default)

11 Range 10 01 Default: -1
11 0:1  10 Only makes sense if set to something between 0 and 1
11 -1  10 Used to check if anything was given

11

11 yxexmin  10 Scope: restricted01  REAL

11 Description: Atmospheric electron fraction (optional; table bounds used by default)

11 Range 10 01 Default: -1
11 0:1  10 Only makes sense if set to something between 0 and 1
11 -1  10 Used to check if anything was given

11

6 Interfaces

General Implements: grhaylib

Adds header: GRHayLib.h

7 Schedule This section lists all the variables which are assigned storage by thorn GRHayL/GRHayLib. 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 NONE

Scheduled Functions

CCTKxWRAGH (conditional) x grhaylibxinitialize x set up the grhayl structs and read the table for tabulated eos. x

11 x 11 Language: 11 c
11 x 11 Options: 11 global
11 x 11 Type:  11 function

11

CCTKxTERMINATE x grhaylibxterminate x free memory allocated for the grhayl structs. x

11 x 11 Language: 11 c
11 x 11 Options: 11 global
11 x 11 Type:  11 function