[Users] EOS interface

[Christian D. Ott]

Dear all,

in the process of implementing MHD Con2Prim I got thinking
about the EOS interfaces (again).

I propose a drastic simplification that will reduce generality
dramatically, but will increase performance and flexibility.

The idea is to create (and I have coded a test implementation) a
EOS master thorn called EOS_Omni that provides aliased functions
for single-variable calls, e.g.,

EOS_Omni_press
EOS_Omni_DPressByDEps
...

as well as a 'full' call

EOS_Omni_hydro_full

that returns _at once_ all vars relevant for hydro. Calls that return
a certain set of variables (e.g., those needed by Con2Prim) would also
be possible. I would be happy to implement and maintain this thorn and
would also be willing to provide my finite-T microphysical EOS
routines as part of it.

EOS_Omni, being a master thorn, would implement all sensible EOS --
poly, gamma-law, piecewise poly, hybrid, hybrid-piecewise-poly, 
microphysical cold, and microphysical hot EOS. It would decide
which EOS to use based on an integer 'eoskey' that is passed to it.
This allows, e.g., to use a different EOS for the atmosphere than
for the actual fluid (something that is impossible currently!).
Currently, I have coded EOS_Omni with select case statements to
switch between EOS and have the EOS hardcoded. This will maximize
performance and will be much faster than using the current
one-thorn-per-EOS approach with a EOS_Base thorn by minimizing
function calls.

In addition, EOS_Omni would take as input variables all needed
for a nuclear-statistical equilibrium EOS (later to be extended to
non-NSE EOS that depend on individual isotope mass fractions).
In case a simple EOS analytic EOS is used, the compositional (Ye)
and temperature information would just be ignored.  A call
would look like this:

void FUNCTION EOS_Omni_press(CCTK_INT IN eoskey,         \
			     CCTK_INT IN havetemp,       \
                             CCTK_INT IN npoints,        \
			     CCTK_REAL IN ARRAY rho,     \
			     CCTK_REAL INOUT ARRAY eps,  \
			     CCTK_REAL INOUT ARRAY temp, \
			     CCTK_REAL IN ARRAY ye,      \
			     CCTK_REAL OUT ARRAY press,  \
			     CCTK_INT OUT ARRAY keyerr   \
                             CCTK_INT OUT anyerr)

eoskey   -- an integer specifying which EOS to use
havetemp -- for finite-T: 0, coming in with eps; 1, coming in with temp
npoints  -- passing n datapoints
rho      -- obvious
eps      -- obvious
temp     -- temperature
ye       -- electron fraction
press    -- obvious
keyerr   -- integer array that contains error codes in case 
            something went wrong
anyerr   -- .ne. 0 if there was any error

So, as you can see, this could be used for pointwise as well as
GF-wide calls. 

And one more thing: With the proposed aliased-function-based calls, it
would still be possible to have thorns implementing a single EOS
(e.g. a polytrope) provide EOS_Omni_* functions -- there could, of course,
be only one such thorn active at a given time.

Thoughts?

 - Christian