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.
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, Flux_Source, 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 ghl_parameters and ghl_eos_parameters structs. The instances are named ghl_params and ghl_eos, and the pointers to these structs are provided by the GRHayLib.h header.
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 ghl_eos. 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 EOS_type 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.
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 rho_b are set by rho_ppoly_in, and the associated Gamma values are stored in Gamma_ppoly_in. Note that for neos=1, only a single Gamma is necessary. Additionally, the parameter k_ppoly0 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 Gamma_th must be set.
The hybrid EOS only uses the rho_b limit parameters. If unset, the minimum is set to 0, and the maximum is set to 1e300, effectively turning off both of these features.
To properly configure for tabulated EOS, the most important parameter is the path to the EOS table, given by the EOS_tablepath parameter. GRHayLib automatically reads this table and makes it accessible to GRHayL functions through ghl_eos.
The tabulated EOS uses all the limit parameters (rho_b, Y_e, and T). If unset, the mimima and maxima are set to table bounds.
GRHayL provides a selection of con2prim routines along with automated backup methods. ghl_params passes the information from the thorn parameters textttcon2prim_routine and textttcon2prim_backup_routines 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 ghl_con2prim_hybrid_multi_method() and ghl_con2prim_tabulated_multi_method() functions implement this feature, and the ghl_con2prim_hybrid_select_method() and ghl_con2prim_tabulated_select_method() 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 calc_primitive_guess 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 ghl_guess_primitives() function.
Cactus allows for changing parameters during a run using CCTK_ParameterSet(). 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 ghl_initialize_EOSTYPE_eos() 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.
calc_primitive_guess | Scope: restricted | BOOLEAN |
Description: Do we want to calculate estimates for the primitives in Con2Prim?
| ||
| Range | Default: yes | |
no | Uses the data currently in the primitive variables as the guess.
| |
yes | Calculates primitive guesses from the current conservatives.
| |
con2prim_backup_routines | Scope: restricted | KEYWORD |
Description: We allow up to 3 backup routines
| ||
| Range | Default: None | |
None | Don’t use backup routines
| |
Noble2D | ”2D routine in https://arxiv.org/pd f/astro-ph/0512420.p df”
| |
Noble1D | ”1Dw routine in https://arxiv.org/pd f/astro-ph/0512420.p df”
| |
Noble1D_entropy | ”1Dw routine in https://arxiv.org/pd f/astro-ph/0512420.p df, but uses
the entropy”
| |
Font1D | TODO
| |
Palenzuela1D | ”https://arxiv.org/p df/1505.01607.pdf (see also https://arxiv.org/pd
f/1712.07538.pdf)”
| |
Newman1D | ”https://escholarshi p.org/content/qt0s53 f84b/qt0s53f84b.pdf (see also
https://arxiv.org/pd f/1712.07538.pdf)”
| |
see [1] below | ”https://arxiv.org/p df/1505.01607.pdf (see also https://arxiv.org/pd
f/1712.07538.pdf)”
| |
Newman1D_entropy | ”https://escholarshi p.org/content/qt0s53 f84b/qt0s53f84b.pdf (see also
https://arxiv.org/pd f/1712.07538.pdf)”
| |
[1]
Palenzuela1D\_entropy
con2prim_routine | Scope: restricted | KEYWORD |
Description: What con2prim routine is used
| ||
| Range | Default: Noble2D | |
Noble2D | ”2D routine in https://arxiv.org/pd f/astro-ph/0512420.p df”
| |
Noble1D | ”1Dw routine in https://arxiv.org/pd f/astro-ph/0512420.p df”
| |
Noble1D_entropy | ”1Dw routine in https://arxiv.org/pd f/astro-ph/0512420.p df, but uses
the entropy”
| |
Font1D | TODO
| |
Palenzuela1D | ”https://arxiv.org/p df/1505.01607.pdf (see also https://arxiv.org/pd
f/1712.07538.pdf)”
| |
Newman1D | ”https://escholarshi p.org/content/qt0s53 f84b/qt0s53f84b.pdf (see also
https://arxiv.org/pd f/1712.07538.pdf)”
| |
see [1] below | ”https://arxiv.org/p df/1505.01607.pdf (see also https://arxiv.org/pd
f/1712.07538.pdf)”
| |
Newman1D_entropy | ”https://escholarshi p.org/content/qt0s53 f84b/qt0s53f84b.pdf (see also
https://arxiv.org/pd f/1712.07538.pdf)”
| |
[1]
Palenzuela1D\_entropy
eos_tablepath | Scope: restricted | STRING |
Description: Path to the EOS table
| ||
| Range | Default: (none) | |
Forbidden, will error out
| ||
.+? | Any string
| |
eos_type | Scope: restricted | KEYWORD |
Description: The type of EOS for the simulation
| ||
| Range | Default: (none) | |
Forbidden default; an EOS type must be specified
| ||
Simple | Simple EOS (often referred to as ’ideal fluid’ in literature)
| |
Hybrid | Hybrid EOS
| |
Tabulated | Tabulated EOS
| |
evolve_entropy | Scope: restricted | BOOLEAN |
Description: Do we want to evolve the entropy?
| ||
| Default: no | ||
evolve_temperature | Scope: restricted | BOOLEAN |
Description: Do we want to evolve the temperature?
| ||
| Default: no | ||
gamma | Scope: restricted | REAL |
Description: Gamma parameter
| ||
| Range | Default: -1 | |
0:* | Physical values
| |
-1 | forbidden value to make sure it is explicitly set in the parfile
| |
gamma_ppoly_in | Scope: restricted | REAL |
Description: Set polytropic Gamma parameters. Gamma_ppoly_in[0] goes from rho=0 to
rho=rho_ppoly_in[0].
| ||
| Range | Default: -1 | |
0:* | value of Gamma for the polytropic rho in the bounds rho_ppoly[i-1] to
rho_ppoly[i]
| |
-1 | forbidden value to make sure it is explicitly set in the parfile
| |
gamma_th | Scope: restricted | REAL |
Description: thermal Gamma parameter
| ||
| Range | Default: -1 | |
0:* | Physical values
| |
-1 | forbidden value to make sure it is explicitly set in the parfile
| |
k_ppoly0 | Scope: restricted | REAL |
Description: Also known as k_ppoly[0], this is the polytropic constant for the lowest density piece
of the piecewise polytrope. All other k_ppoly elements are set using rho_ppoly_in and enforcing
continuity in the equation of state.
| ||
| Range | Default: -1 | |
0:* | Physical values
| |
-1 | forbidden value to make sure it is explicitly set in the parfile
| |
lorenz_damping_factor | Scope: restricted | REAL |
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).
| ||
| Range | Default: 0.0 | |
*:* | any real
| |
max_lorentz_factor | Scope: restricted | REAL |
Description: Maximum Lorentz factor.
| ||
| Range | Default: 10.0 | |
1:* | Positive > 1, though you’ll likely have troubles far above 10.
| |
neos | Scope: restricted | INT |
Description: number of parameters in EOS table
| ||
| Range | Default: 1 | |
1:10 | Any integer between 1 and 10
| |
p_atm | Scope: restricted | REAL |
Description: Atmospheric pressure (required)
| ||
| Range | Default: -1 | |
0:* | Should be non-negative
| |
-1 | Used to check if anything was given
| |
p_max | Scope: restricted | REAL |
Description: Maximum temperature allowed (disabled by default)
| ||
| Range | Default: -1 | |
0:* | Should be non-negative
| |
-1 | Used to check if anything was given
| |
p_min | Scope: restricted | REAL |
Description: Minimum temperature allowed (disabled by default)
| ||
| Range | Default: -1 | |
0:* | Should be non-negative
| |
-1 | Used to check if anything was given
| |
ppm_flattening_epsilon | Scope: restricted | REAL |
Description: Epsilon used for flattening in PPM algorithm
| ||
| Range | Default: 0.33 | |
: | Anything goes. Default is from Colella & Woodward
| |
ppm_flattening_omega1 | Scope: restricted | REAL |
Description: Omega1 used for flattening in PPM algorithm
| ||
| Range | Default: 0.75 | |
: | Anything goes. Default is from Colella & Woodward
| |
ppm_flattening_omega2 | Scope: restricted | REAL |
Description: Omega2 used for flattening in PPM algorithm
| ||
| Range | Default: 10.0 | |
: | Anything goes. Default is from Colella & Woodward
| |
ppm_shock_epsilon | Scope: restricted | REAL |
Description: Epsilon used for shock detection in steepen_rho algorithm
| ||
| Range | Default: 0.01 | |
: | Anything goes. Default is from Colella & Woodward
| |
ppm_shock_eta1 | Scope: restricted | REAL |
Description: Eta1 used for shock detection in steepen_rho algorithm
| ||
| Range | Default: 20.0 | |
: | Anything goes. Default is from Colella & Woodward
| |
ppm_shock_eta2 | Scope: restricted | REAL |
Description: Eta2 used for shock detection in steepen_rho algorithm
| ||
| Range | Default: 0.05 | |
: | Anything goes. Default is from Colella & Woodward
| |
ppm_shock_k0 | Scope: restricted | REAL |
Description: K0 used for shock detection in steepen_rho algorithm
| ||
| Range | Default: 0.1 | |
: | Anything goes. Default suggested by Colella & Woodward is: (polytropic
constant)/10.0
| |
psi6threshold | Scope: restricted | REAL |
Description: Where Psi
 > Psi6threshold, we assume we’re inside the horizon in the primitives
solver, and certain limits are relaxed or imposed | ||
| Range | Default: 1e100 | |
*:* | Can set to anything
| |
rho_b_atm | Scope: restricted | REAL |
Description: Atmosphere value on the baryonic rest mass density rho_b (required). If this is unset,
the run will die.
| ||
| Range | Default: -1 | |
0:* | Atmosphere density; must be positive
| |
-1 | Used to check if anything was given
| |
rho_b_max | Scope: restricted | REAL |
Description: Ceiling value on the baryonic rest mass density rho_b (disabled by default). Can
help with stability to limit densities inside the BH after black hole formation.
| ||
| Range | Default: -1 | |
0:* | Maximum density; must be positive
| |
-1 | Used to check if anything was given
| |
rho_b_min | Scope: restricted | REAL |
Description: Floor value on the baryonic rest mass density rho_b (disabled by default).
| ||
| Range | Default: -1 | |
0:* | Minimum density; must be positive
| |
-1 | Used to check if anything was given
| |
rho_ppoly_in | Scope: restricted | REAL |
Description: Set polytropic rho parameters
| ||
| Range | Default: -1 | |
0:* | value of the density delimiters for the pieces of the piecewise polytrope
| |
-1 | forbidden value to make sure it is explicitly set in the parfile (only checked
for neos > 1)
| |
t_atm | Scope: restricted | REAL |
Description: Atmospheric temperature (required)
| ||
| Range | Default: -1 | |
0:* | Should be non-negative
| |
-1 | Used to check if anything was given
| |
t_max | Scope: restricted | REAL |
Description: Maximum temperature allowed (optional; table bounds used by default)
| ||
| Range | Default: -1 | |
0:* | Should be non-negative
| |
-1 | Used to check if anything was given
| |
t_min | Scope: restricted | REAL |
Description: Minimum temperature allowed (optional; table bounds used by default)
| ||
| Range | Default: -1 | |
0:* | Should be non-negative
| |
-1 | Used to check if anything was given
| |
y_e_atm | Scope: restricted | REAL |
Description: Atmospheric electron fraction (required)
| ||
| Range | Default: -1 | |
0:1 | Only makes sense if set to something between 0 and 1
| |
-1 | Used to check if anything was given
| |
y_e_max | Scope: restricted | REAL |
Description: Atmospheric electron fraction (optional; table bounds used by default)
| ||
| Range | Default: -1 | |
0:1 | Only makes sense if set to something between 0 and 1
| |
-1 | Used to check if anything was given
| |
y_e_min | Scope: restricted | REAL |
Description: Atmospheric electron fraction (optional; table bounds used by default)
| ||
| Range | Default: -1 | |
0:1 | Only makes sense if set to something between 0 and 1
| |
-1 | Used to check if anything was given
| |
Implements:
grhaylib
Adds header:
GRHayLib.h
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.
NONE
CCTK_WRAGH (conditional)
grhaylib_initialize
set up the grhayl structs and read the table for tabulated eos.
| Language: | c | |
| Options: | global | |
| Type: | function | |
CCTK_TERMINATE
grhaylib_terminate
free memory allocated for the grhayl structs.
| Language: | c | |
| Options: | global | |
| Type: | function | |