FreeEOS Code

Table of Contents:

1. Introduction
2. Build and install FreeEOS and link your own application to that installed library
3. Instructions for users of FreeEOS
4. Conclusions

1. Introduction

This FreeEOS code is suitable for stellar interior and vibrational frequency
calculations, and is fast enough to be called directly from those
calculations which eliminates the errors associated with interpolating
tables.  The code produces smooth first- and second-order thermodynamic
functions.  It has option suites to mimic a number of different equations of
state.  Also it has the option suite for EOS1, which is our recommended EOS
which fits the OPAL EOS results quite well for the solar case. EOS1a, EOS2,
EOS3, and EOS4 are approximations to EOS1 which are of increasing speed, and
decreasing quality.  However, we find under all circumstances that we have
tested (including extreme LMS models where these option suites yield large
differences in results in the envelope) that the radius and luminosity
results are insensitive to differences between these option suites.  If you
require more detailed data than radius and luminosity (e.g., vibrational
frequencies) than EOS1 is the preferred EOS.

2. Build and install FreeEOS and link your own application to that installed library

The INSTALL file gives the latest directions.

3. Instructions for users of FreeEOS

N.B. I reserve the right to change the argument list of any routine in
the library without notice except for the generic (see below) free_eos
routine itself where the changes will be minimal and well documented
when they do occur.  Thus, free_eos is the routine which should be
called by all FreeEOS fortran users, and planned C and python
interfaces to the FreeEOS library will only contain the API of
free_eos and no other routine.

N.B. free_eos is implemented as a modern Fortran generic routine where
different API's are allowed (different sets of arguments) with the
same name used for the routine itself. As of FreeEOS-3.0.0 there have
only been two API's implemented which are documented in
src/mod_free_eos.f90 where the internal free_eos_legacy subroutine
implements the legacy API (the API that was used for FreeEOS-2.2.1 and
many prior versions), and the internal free_eos_modern subroutine
implements the modern API that has been made available as of 3.0.0.
(Browse either
free_eos-3.0.0/document_FreeEOS/doxygen/doxygen/latex/FreeEOS_developer_documentation.pdf
or free_eos-3.0.0/document_FreeEOS/doxygen/doxygen/html/index.xhtml
for access to all doxygen-generated documentation of FreeEOS including
documentation of these two API's.)

These two API's are made indirectly available to user routines when
those routines call the generic free_eos subroutine with the
appropriate (legacy or modern) API, and this generic method allows
additional API's to be implemented without a (generic) subroutine name
change if that ever becomes necessary.  The modern API is more
powerful than the legacy API so I recommend its use in all cases.  For
example, the legacy API is implemented by calling the modern API.
However, the legacy API is still made available as a convenience for
those who do not want to take the trouble to convert to using the
modern API.

Regardless of API, free_eos sets up flags (a very important step) and
calls free_eos_detailed which in turn calls the rest of the
routines. src/README.developers is a convenient summary of the
relationships between the various routines. Many flag combinations in
free_eos have been tested by using them to produce the figures in the
papers collected at freeeos.sf.net/documentation.html.  A direct call
of free_eos_detailed is not recommended since arbitrary combinations
of flags (as opposed to the tested flag combinations in free_eos) may
not work.  All arguments for free_eos are documented in that code.

The input arguments to free_eos are the 4 flags: ifoption, ifmodified,
ifion, and kif_in which control the option suite being used for the
free-energy model; eps and neps, the array of abundances and the size of
that array (must be 20); match_variable (= fl, ln p, or ln rho for kif = 0,
1, 2), and tl (= ln T). All other arguments to free_eos are output from that
routine.

ifion is a flag that controls the way that ionization is done.  In general,
the lower ifion, the slower the code, and the more ionization details that
are calculated.

ifion = -2 implies all 295 ionization stages of the 20 elements are treated
in detail.

ifion = -1 implies the 10 low-abundance minor metals are treated as fully
ionized while H, He, and the major metals (currently the list is C, N, O,
Ne, Mg, Si, S, and Fe which is controlled by the iftracemetal array in
free_eos_detailed) are treated in detail.

ifion = 0 is interpreted identically to ifion = -1 below T = 1.d6 while
above that temperature ifion = 0 is interpreted identically to ifion = 1
(see next).

ifion = 1 implies all major and minor metals are always treated as fully
ionized.

ifion = 2 implies all elements are treated as fully ionized.

The principal flag combinations are the following:

ifoption, ifmodified, ifion

1,-1,1    (PTEH without radiation pressure (ifmodified = -1) and with

1,-101,1  radiation pressure (ifmodified = -101). I don't recommend PTEH
	  except for test calculations, but if you want to mimic the PTEH
	  code exactly you should calculate eps using integer atomic weights
	  before calling my EOS routine.)

2,-1,-1   (GEFF without radiation pressure (ifmodified = -1) and with

2,-101,-1 radiation pressure (ifmodified = -101).  I no longer recommend
          GEFF.)

2,-2,-1   (SIREFF without radiation pressure (ifmodified = -2) and with

2,-201,-1 radiation pressure (ifmodified = -201).  I no longer recommend
          SIREFF.)

3,0,-1    (MDH with modifications of the molecular treatment, see paper.)

3,1,-2    (EOS1, our recommended EOS that has been constrained by OPAL and SCVH
	  fits.  The ifion=-2 flag means that all 295 ionization states of
	  the 20 elements are treated in detail.)

3,1,-1    (EOS1a.  This is identical to EOS1 except that minor metals are
	  approximated as fully ionized (because of the different ifion
	  flag, see above) which increases the speed of the computation by
	  almost a factor of three at the expense of almost negligible
	  pressure errors at low temperatures.  N.B. for FreeEOS-1.3.0 and
	  below we used the EOS1 label for what is now called EOS1a.)

2,1,-1    (EOS2, a fit of EOS1 using modified GEFF pressure ionization.)

1,1,0     (EOS3, a fit of EOS1 using a modified PTEH pressure ionization with
	  the PTEH approximation used for the Coulomb sums above log T = 6.
	  Also, because of the ifion flag [see above], the major metals are
	  assumed fully ionized above log T = 6.)

1,101,0   (EOS4, same as EOS3, except use the PTEH approximation for the
	  Coulomb sums for **all** temperatures.) EOS4 produces excellent
	  results even for the extreme LMS if *just* reliable radii and
	  luminosities are required from the interior model.  For more
	  detailed results such as vibrational frequencies EOS1 is
	  recommended.

The PTEH, GEFF, SIREFF, and MDH options are included to provide good
compatibility with those equations of state (see paper), and to provide
comparisons with the remaining versions of our EOS.

The EOS1, EOS1a, EOS2, and EOS3 option suites respectively take about 80,
30, 8, and 2 times as long to compute as EOS4 for the locus of points in a
solar model. They represent various compromises between speed and quality
(see paper).  For solar vibrational frequencies or generating EOS tables to
be subsequently interpolated I recommend using EOS1. For most stellar work
involving calculations of luminosities and effective temperatures, EOS4
provides excellent results when called directly from the stellar interiors'
code, but it might be worthwhile to try EOS1 or EOS1a for a few test cases
(especially along the LMS where differences are the maximum) to make sure
the changes are within the observational errors.  Also, note that
interpolating EOS tables is a non-trivial task since the tables have to be
quite large to reduce interpolation errors to negligible proportions.

Don VandenBerg has found that even EOS4 does very well for the extreme LMS.
The reason is that the large changes from EOS1 involve the temperature (for
rho, P as the independent variables).  These large changes do not occur for
the core (so the luminosity is unaffected) or the surface (so the P(rho)
adiabat for the efficient convection occurring for the entire star is
unaffected).  On the other hand, the PTEH EOS does have significant
temperature changes at the surface and in the core so the mass-luminosity
relation for the extreme LMS is affected by using this EOS.  I no longer
recommend using GEFF or SIREFF.  They do fairly well for solar conditions,
but the Debye-Huckel Coulomb theory upon which they are based has huge
errors for the LMS which lead, for example, to negative pressures.

4. Conclusions

The latest version of this README should always be available at
<http://freeeos.sourceforge.net/documentation.html> along with most other
sources of FreeEOS documentation including research note(s) about the
implementation.  As always, the best source of documentation is the code
itself (especially the introductory comments to free_eos_modern contained in
src/mod_free_eos.f90). If in doubt, read the code and/or e-mail me your questions
on the freeeos-general list.  Note, to post to that list, you must subscribe
following the directions at
<http://lists.sourceforge.net/lists/listinfo/freeeos-general>

For detailed remarks on changes to the EOS code see the ChangeLog.prior_SF
and the ChangeLog files.

FreeEOS is free software; you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This software is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
(COPYING file in this directory) for more details.

You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 675 Mass
Ave, Cambridge, MA 02139, USA.

Alan W. Irwin <airwin@users.sourceforge.net>, 2022-05-25.