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

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

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

2.2 Tabulated EOS

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.

3 Conservative-to-Primitive Routines

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.

4 Changing parameters during a run

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.

5 Parameters

[1]

Palenzuela1D\_entropy

[1]

Palenzuela1D\_entropy

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

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

CCTK_WRAGH (conditional)

  grhaylib_initialize

  set up the grhayl structs and read the table for tabulated eos.

CCTK_TERMINATE

  grhaylib_terminate

  free memory allocated for the grhayl structs.