FreeEOS Code
Brought to you by:
airwin
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.