## General equations of state

March 15 2005

Abstract

This thorn provides a generalized equation of state interface.

### 1 Equations of state

In solving the equations of hydrodynamics there are ﬁve independent variables (typically $\rho ,{v}^{i},𝜖$ for the rest mass density, velocity and speciﬁc internal energy) and further variables, such as the pressure $P$ which depend on the independent variables. Such dependent variables are speciﬁed by an equation of state (EOS) that closes the system of equations. Simple EOSs depend only on the independent variables and are usually given in terms of the pressure, i.e. $P=P\left(\rho ,𝜖\right)$ which then implicitly deﬁnes other variables such as the temperature $T$, pressure derivatives ${P}_{\rho },{P}_{𝜖}$ and the speed of sound ${c}_{s}$.

However there is no physical reason to prefer such simple EOSs. A realistic EOS will depend on the composition of the ﬂuid as well as the independent variables. This thorn is meant to provide an interface so that a hydrodynamics code can depend on such a realistic EOS without having to know about the details of the composition – without, in fact, needing an knowledge of the additional variables required by the EOS at all.

### 2 Calling an EOS

The most eﬃcient way of using the EOS is to call it to set grid functions. The interface is simple on the face of it; one function call will give you a call handle, and another function call will actually set the EOS. The complexity comes in setting up the key value tables involved in the function calls.

### EOS_SetupCall

Sets up an equation of state call. If the call handle is stored (which is recommended) then this only needs to be performed once at startup time, and the call handle can be reused.

Synopsis

C

CCTK_INT call_handle = EOS_SetupCall(CCTK_INT table_handle)

Fortran

CCTK_INT call_handle = EOS_SetupCall(CCTK_INT table_handle)

Result

The call_handle return must be stored for later use in the EOS call. The value should be $\ge 0$. Typically a level 0 warning will be given rather than returning an error code. $\ge 0$ The call handle, to be stored for later use.

Parameters

table_handle The handle of an existing key value table. Appropriate arguments will be described elsewhere.

Discussion

The complexity comes in setting up the key-value table to be passed through. Eﬀectively any arguments can be given that will be interpreted by the EOS, but the following are expected (note capitalization - it is always useful to set up the table using the CASE INSENSITIVE ﬂag):

• EOS Name: This must correspond to the name that the EOS thorn has registered.
• Independent variable names: This is a string (a CCTK_STRING) of whitespace separated names describing the independent variables. Although there is no particular values for these “names” required by this base thorns the following conventions for variable names have been used in existing thorns (name in parantheses is the variable name in whisky):
• Rho: Rest mass density (rho)
• SpecificInternalEnergy: Speciﬁc internal energy (eps)
• Pressure: Pressure (press)
• DPressureDRho: Partial derivative of pressure with respect to rest mass density, all else being ﬁxed (dpdrho)
• DPressureDSpecificInternalEnergy: Partial derivative of pressure with respect to speciﬁc internal energy, all else being ﬁxed (dpdeps)
• c_s^2: Speed of sound squared (cs2).
• Dependent variable names: A string describing the dependent variables, following the same syntax as the Independent variable names
• N independent variables: The number of independent variables
• N dependent variables: The number of dependent variables
• Independent GFs: An array of integers containing the indices of the grid functions corresponding to the independent variables. E.g., if the ﬁrst dependent variable name is Rho which is contained in the grid function whisky::rho then the ﬁrst entry of this array is found from CCTK_VarIndex("whisky::rho").
• Dependent GFs: An array of integers containing the indices of the dependent grid functions, following the syntax of the Independent GFs.

EOS_SetGFs Sets the EOS.

### EOS_SetGFs

Actually sets the dependent GFs in an EOS call. The call must have been previously set up using EOS_SetupCall. Must be called from routines scheduled in local mode.

Synopsis

C

CCTK_INT ierr = EOS_SetGFs(CCTK_POINTER_TO_CONST cGH, CCTK_INT call_handle)

Fortran

CCTK_INT ierr = EOS_SetGFs(CCTK_POINTER_TO_CONST cGH, CCTK_INT call_handle)

Result

The call_handle should have been previously set up by EOS_SetupCall. Currently only successful returns (0) are given. 0 success.

Parameters

cGH The Cactus GH structure, and the reason why this must be called in local mode.
call_handle An EOS call previously set up by EOS_SetupCall.

Discussion

Once the EOS call has been setup this routine basically tells the EOS function to apply the appropriate EOS calls at this point to the appropriate arrays.

EOS_SetupCall Setup the EOS call.

### 3 Registering an EOS

Before you can use an EOS one ﬁrst has to be registered. The best way of learning how to do this is to look at the example thorns, such as the “generalized” polytropic EOS (thorn EOS_GeneralPolytrope) or ideal gas EOS (thorn EOS_GeneralIdealFluid). Here is just the essential description.

The essential thing that is required is a function (probably in C, although in theory it’s language independent) that sets arbitrary sized arrays1 of dependent variables from the independent variables. This function is registered using the aliased function EOS_RegisterCall. This function, and the function pointer that must be called, are as follows.

### EOS_RegisterCall

Register an EOS with the base thorn.

Synopsis

C

CCTK_INT ierr = EOS_RegisterCall(CCTK_INT table_handle, \
CCTK_INT CCTK_FPOINTER EOS_fn(...))

Fortran

CCTK_INT ierr = EOS_RegisterCall(CCTK_INT table_handle, \
CCTK_INT CCTK_FPOINTER EOS_fn(...))

Result

The function pointer EOS_fn is described below on page ??.

Currently only successful returns (0) are given. 0 success.

Parameters

table_handle A key/value table containing any persistent information that the EOS thorn may want to store. This is not used by the base thorn, and is there for the convenience of the EOS thorn.
EOS_fn A function pointer for the EOS call itself, described below.

Discussion

The table can be used to diﬀerentiate between diﬀerent calls. For example, if one thorn implements many diﬀerent EOSs and the number is not known at compile time (e.g., a table interpolator thorn that provides multiple tables) then only one registration need take place, and the key/value table can be used store which (interpolation) table is being used in the particular call.

EOS_fn The actual EOS function.

### EOS_fn

The actual EOS function that must be provided.

Synopsis

C

CCTK_INT ierr = EOS_fn(CCTK_INT param_table, \
CCTK_INT n_elems, \
CCTK_POINTER* indep_arrays, \
CCTK_INT* which_dep_arrays_to_set, \
CCTK_POINTER* dep_arrys)

Fortran

CCTK_INT ierr = EOS_fn(CCTK_INT param_table, \
CCTK_INT n_elems, \
CCTK_POINTER* indep_arrays, \
CCTK_INT* which_dep_arrays_to_set, \
CCTK_POINTER* dep_arrys)

Result

Currently only successful returns (0) are given. 0 success.

Parameters

param_table A key/value table containing any persistent information that the EOS thorn may want to store. This is not used by the base thorn, and is there for the convenience of the EOS thorn.
n_elems The size of the arrays that are passed in.
indep_arrays The independent arrays (should essentially be cast to a CCTK_REAL**).
which_dep_arrays_to_set An array telling the EOS thorn which dependent arrays should be set in this thorn. This is important because dependent arrays that are not needed will NOT be passed in the call; see below.
dep_arrays The dependent arrays (should essentially be cast to a CCTK_REAL**). Note that you should not assume that all these pointers are non-null (hence the diﬃculty in using this with Fortran). In general, if the calling thorn does NOT request that a dependent variable be set then the equivalent pointer WILL be null.

Discussion

The table can be used to diﬀerentiate between diﬀerent calls. For example, if one thorn implements many diﬀerent EOSs and the number is not known at compile time (e.g., a table interpolator thorn that provides multiple tables) then only one registration need take place, and the key/value table can be used store which (interpolation) table is being used in the particular call.