General equations of state

Ian Hawke <ih@maths.soton.ac.uk>

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 ρ,vi,ūĚúĖ 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(ρ,ūĚúĖ) which then implicitly deÔ¨Ānes other variables such as the temperature T, pressure derivatives Pρ,PūĚúĖ and the speed of sound cs.

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 efficient 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 0. Typically a level 0 warning will be given rather than returning an error code. 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):

See Also

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.

See Also

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 differentiate between different calls. For example, if one thorn implements many different 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.

See Also

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 difficulty 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 differentiate between different calls. For example, if one thorn implements many different 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.