FreeEOS Code
Brought to you by:
airwin
Menu
▾
▴
Tree [c3ba9e] v1_4_0 / History
Read Me
Introduction
This EOS 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.
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. EOS1 has
been constrained by fits to the OPAL and SCVH equations of state.
Installation Prerequisites
FreeEOS requires that you have the lapack and blas libraries installed
somewhere on your system. These are common library packages so with any
luck you will have them installed on your system already as a matter of
course. For rpm-based Linux distributions try "rpm -qi lapack" and "rpm -qi
blas" and for Debian-based Linux systems use "dpkg --list |grep lapack" and
"dpkg --list grep blas" to find whether these packages are already
installed. For Unix systems consult with your system administrator and/or
use the "find" command to look for liblapack* and libblas* on your system.
If you do not have these packages installed on Debian-based systems, then
simply issue "apt-get install lapack-dev blas-dev" to install. (Installing
these development packages will automatically also install other required
packages.) On rpm-based systems with an apt-get front-end, use "apt-get
install lapack blas" to install. (The development versions of lapack and
blas are lumped in with ordinary lapack and blas on most rpm-based systems.)
On rpm-based Linux systems without an apt-get front-end, search the web for
appropriate rpm's for your particular version of Linux. For example, enter
lapack or blas in the search box at http://rpm.pbone.net/ to find rpms for
lapack and blas for a wide variety of Linux distribution versions. Make
sure you download and install _only_ the rpms that are appropriate for your
Linux distribution version.
For Unix (and also Linux systems if you cannot find good rpms for lapack and
blas), follow the lapack and blas download and build instructions at
http://www.netlib.org/lapack/lawn81/index.html.
In particular "File Format" tells you where to download the tarball, and
"Installing LAPACK on a Unix System" tells you how to set up the
all-important make.inc file that guides the build. Note that a variety of
make.inc example files have been included in the tarball for several
flavours of Unix/Linux so usually you can just copy the one that is
appropriate for your system.
***AIX (4.3.3) lapack quirks: (I thank Santi Cassisi for giving me access to
his AIX system to help figure out these quirks).
* Use the make.inc.RS6K version
cd LAPACK
cp INSTALL/make.inc.RS6K make.inc
* change ETIME ==> ETIME_ following the directions at
http://www.netlib.org/lapack/lawn41/node119.html
* Don't bother with the extensive testing that the "make" command gives you.
It inevitably fails (probably because a non-standard libessl version of BLAS
is being used). Instead, for LAPACK testing, rely on my EOS test done with
./free_eos_test below. So assuming you are in the LAPACK directory instead
of using
make
use
make install lib
(which skips all the blas and lapack tests) instead. That last command
creates a library called lapack_RS6K.a which is rather awkward for my build
routine (which assume library names of the form lib*) to deal with. To get
around that simply make a symlink.
ln -s lapack_RS6K.a liblapack.a
***Solaris (uname -a ==> SunOS sparc-solaris1 5.9 Generic_112233-03 sun4u
sparc SUNW,Ultra-60) lapack quirks: (I thank Sourceforge for providing
a Solaris compile farm system where I could figure out these quirks).
On solaris the location of the fortran compiler and its associated loader
are not obvious. What you
have to do is put the correct directories first on your path.
PATH="/opt/SUNWspro/bin:/usr/ccs/bin:"$PATH"
cd LAPACK
cp INSTALL/make.inc.SUN4SOL2 make.inc
On the solaris system accessible to me I could not find sunperf (although it
may be there) so I chose to use
BLASLIB = ../../blas$(PLAT).a
to replace
BLASLIB = -xlic_lib=sunperf
in this file. Also, I replaced f77 by f95 since that is what will be used
to compile FreeEOS below for the solaris case.
FORTRAN = f95
LOADER = f95
Furthermore, I adjusted Makefile to build the blas library from scratch.
lib: blaslib lapacklib tmglib
To save testing time I ran
make install lib
The result was the following libraries:
ls -l *.a
blas_SUN4SOL2.a lapack_SUN4SOL2.a tmglib_SUN4SOL2.a
Finally, I symlinked the more standard names to these libraries so that
my FreeEOS build procedure would recognize them.
ln -s blas_SUN4SOL2.a libblas.a
ln -s lapack_SUN4SOL2.a liblapack.a
***Mac OS X 10.3 (uname -a ==> Darwin Bill-Paxtons-Computer.local 7.5.0
Darwin Kernel Version 7.5.0: Thu Aug 5 19:26:16 PDT 2004;
root:xnu/xnu-517.7.21.obj~3/RELEASE_PPC Power Macintosh powerpc) with fink
lapack quirks: (I thank Bill Paxton for running Mac OS X 10.3 build
tests for me.)
Bill reports it is impossible to link to the lapack/blas libraries
installed by the fink atlas package. Typical errors are undefined symbols
for restFP saveFP, and if you look those up on google, that appears to be
some inconsistency between the g77 version used to build older fink packages
and the modern g77 available on fink. This problem may eventually be solved
by a new build of atlas so it is worth continuing to try the fink atlas
package, but for now we fall back to building lapack/blas from scratch.
Here is how to build lapack/blas from scratch on Mac OS X 10.3
unpack the lapack.tgz tarball (see "file format" above to find how to get
that tarball.
cd LAPACK
cp INSTALL/make.inc.LINUX make.inc
edit make.inc and change the following line:
OPTS = -funroll-all-loops -fno-f2c -O3
OPTS = -funroll-all-loops -O3
The -fno-f2c g77 option has to be applied consistently for all software, and
since we don't use that option for FreeEOS, we don't use it for lapack and
blas as well.
Yes, that is right. Aside from the change to OPTS we tried the vanilla
Linux version of make.inc, and it works fine on the above Mac OS X 10.3
system with g77.
Furthermore, I adjusted Makefile to build the blas library from scratch.
lib: blaslib lapacklib tmglib
To save testing time I ran
make install lib
The result was the following libraries:
ls -l *.a
blas_LINUX.a lapack_LINUX.a tmglib_LINUX.a
Finally, I symlinked the more standard names to these libraries so that
my FreeEOS build procedure would recognize them.
ln -s blas_LINUX.a libblas.a
ln -s lapack_LINUX.a liblapack.a
Installation of FreeEOS
* Note this first step is only required for users of the CVS version of
FreeEOS. Note this step requires autoconf-1.59, automake-1.8.5, and
libtool-1.5.6 or later versions to be installed.
./bootstrap.sh
This shell script runs the appropriate autotools commands from the above
packages using information in configure.ac and the Makefile.am files
to prepare a configure script, appropriate Makefile.in files, and additional
files (such as the generic INSTALL file).
Please check the output of bootstrap.sh to be sure you have the above
versions (or later) of the autotools installed.
N.B. bootstrap.sh is run automatically during the process of tarball creation
so that tarball users will not need to install the autotools or run
the bootstrap.sh script.
* Start here if you are using a tarball version of FreeEOS or if you have
executed the previous step for the CVS version of FreeEOS.
Generic install instructions are given in INSTALL, but it is actually
simpler than that.
. To find out about all configure options and important environment
variables controlling what fortran compiler and fortran options you will
use for building FreeEOS.
./configure --help
A lot of the results of this command are standard "boilerplate" which
you can ignore. The key options are prefix, disable-static, and
disable-shared, and the key environment variables are
F77 Fortran 77 compiler command
FFLAGS Fortran 77 compiler flags
LDFLAGS linker flags, e.g. -L<lib dir> if you have libraries in a
nonstandard directory <lib dir>
Possible choices for F77 that I am aware of are g77 (on most Linux and
Mac systems) and f77, f90, or f95 on Unix systems. If you don't like
the default choice found by the ./configure command below, be sure to
set the F77 environment variable to your choice for fortran compiler
before re-running that ./configure command.
. Configuration for various known systems. Note, that if the prerequisite
lapack (and possibly libblas, if a native version is not pre-built)
locations are not properly identified or if lapack and libblas are not
installed at all (see prerequisites above), the ./configure step will
terminate with an error.
+ Linux systems. Normally you configure with whatever install prefix
you decide to use (which we designate as $PREFIX); excluding the
static library build (to save build time since most users won't want
to link to the static library); and with default F77, FFLAGS, and
LDFLAGS. All output from the command is stored in a file and that
file checked afterward to make sure everything went okay.
export PREFIX=/my/eos/install/directory
(or "setenv PREFIX /my/eos/install/directory" for csh-based shells such as tcsh)
./configure --prefix=$PREFIX --disable-static >& configure.out
less configure.out
grep F77 Makefile
grep FFLAGS Makefile
grep LDFLAGS Makefile
+ AIX (4.3.3) systems where liblapack.a is located in
/home/myusername/mylibs and has been built using the libessl form of
blas. Everything as above except the ./configure command now has
LDFLAGS to specify the location and --with-blas to specify the library
which contains the blas routines.
./configure --prefix=$PREFIX --disable-static \
LDFLAGS='-L/home/myusername/mylibs' --with-blas=essl >& configure.out
+ Solaris (uname -a ==> SunOS sparc-solaris1 5.9 Generic_112233-03 sun4u
sparc SUNW,Ultra-60systems) where liblapack.a and libblas.a (symlinked
to non-standard names in /home/myusername/mylibs) have been built from
source code that comes with lapack. Everything as above except the
./configure command now has LDFLAGS to specify the location of
liblpack.a and libblas.a, and CC=cc and F77=f77 has been specified to
get the solaris native compilers. Also, note that the PATH changes
described for solaris above in the prerequisites must hold here as
well. N.B. Our actual solaris tests set environment variables CC and
F77 rather than putting them in the command line as below, but our
understanding is the two ways of doing things are equivalent. Also,
note there is one other solaris glitch when building, see below.
./configure --prefix=$PREFIX --disable-static \
LDFLAGS='-L/home/myusername/mylibs' CC=cc F77=f77 >& configure.out
+ Mac OS X 10.3 (uname -a ==> Darwin Bill-Paxtons-Computer.local 7.5.0
Darwin Kernel Version 7.5.0: Thu Aug 5 19:26:16 PDT 2004;
root:xnu/xnu-517.7.21.obj~3/RELEASE_PPC Power Macintosh powerpc)
systems where liblapack.a and libblas.a (symlinked to non-standard
names in /home/myusername/mylibs) have been built from source code
that comes with lapack. Everything as above except the ./configure
command now has LDFLAGS to specify the location of liblpack.a and
libblas.a.
./configure --prefix=$PREFIX --disable-static \
LDFLAGS='-L/home/myusername/mylibs' >& configure.out
Note this works on Mac OS X 10.3 systems but not on
MacOS X 10.2 systems so 10.3 is a prerequisite.
. Build the library and check that everything went okay
This part failed to work for solaris (uname -a ==> SunOS sparc-solaris1
5.9 Generic_112233-03 sun4u sparc SUNW,Ultra-60). Our build script
demands all symbols are resolved for libraries, and this translates to
the -z test loader option for solaris. This is a libtool error that
somebody promised to fix in 2001 (see
http://lists.gnu.org/archive/html/bug-libtool/2001-04/msg00008.html),
but apparently the fix never made it into the final product. The Solaris
workaround, for now, is to edit src/Makefile and get rid of the
-no-undefined option before running the command below.
make >& make.out
less make.out
. Build the free_eos_test test code and check everything went okay.
make check >& make_check.out
less make_check.out
. Run the compiled test code, and check results against a standard run on
my own machine. This code runs a particularly difficult example of the
EOS, and tests all derivatives by comparing with centred numerical
differences for 8 step sizes which are reduced by an order of magnitude
between results. Although this is a particularly difficult example
(corresponding to the physical conditions in the deep envelope of an
extreme lower-main-sequence model), it takes only a total of 0.5 secs to
execute this command on a linux/Athlon 600 MHz PC. That time should be
divided by 33 to arrive at the approximate cpu time required per EOS
call on a 600MHz PC since free_eos_test has an original call to the EOS
and 32 additional calls to the EOS to form the required centred
numerical differences.
Note that on various platforms (Linux, AIX, Solaris, and Mac OS X 10.3)
typical differences between free_eos_test.out_local and
free_eos_test.out_standard occur in the 12th to 16th figure (or 10^-12
or smaller for logarithmic quantities) which is a very good numerical
floating-point result (i.e., the calculation loses at most 4 significant
digits from the original ~16 decimal digits we started with in this
complicated double-precision calculation).
Note it is important to pay attention to the results of the following
test. I have had one case where FreeEOS built and free_eos_test ran
without any obvious error messages. But free_eos_test results were
completely unreliable (presumably due to fortran compiler problems on the
old, poorly maintained system where this problem occurred.)
Also note, that complete documentation of free_eos_test occurs in
utils/README.free_eos_test
cd utils
./free_eos_test <free_eos_test.in >& free_eos_test.out_local
less free_eos_test.out_local
sdiff -w 156 free_eos_test.out_local free_eos_test.out_standard
. Install the library and fortran include files in the prefix area you
designated in the configure step. Check results.
make install >& make_install.out
less make_install.out
. To link your own (stellar-interiors) code to FreeEOS on Linux using g77
use options like the following:
g77 mycode.f -I$PREFIX/include/free_eos -Wl,--rpath -Wl,$PREFIX/lib \
-L$PREFIX/lib -lfree_eos -llapack -lblas
The -I option is only required if you make use of some of the installed
fortran include files associated with FreeEOS such as physical
constants, etc. The "-Wl,--rpath -Wl,$PREFIX/lib" options mean you
don't have to fool around with LD_LIBRARY_PATH for non-standard
prefixes.
N.B. Users of fortran compilers other than g77 (set the environment
variable F77 _before_ running ./configure if you want something other
than the default choice for your system, and look at the above
configure.out and make.out to see which fortran compiler you got) will
have to read their fortran user's manual to mimic the effect of the -I
and -Wl, options. The -L and -l options should be the same for all
fortran compilers. Note, you will also need an additional -L option for
the location of liblapack.a and libblas.a if they are not installed in a
standard location.
* Instructions for all users of FreeEOS
N.B. I reserve the right to change the argument list of any routine in
the library without notice except for free_eos 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.
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. All flag combinations in free_eos.f have
been tested by using them to produce the figures in the paper. A direct
call of free_eos_detailed.f is not recommended since arbitrary
combinations of flags (as opposed to the tested flag combinations in
free_eos.f) 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.
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 (MHD 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 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. Also,
for EOS3 the major metals are assumed fully ionized above log T =
6, and the PTEH approximation is used for the Coulomb sums 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 MHD 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. 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.
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 contained in
src/free_eos.f). 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 recent changes to the EOS code see the ChangeLog.prior_SF and ChangeLog
file.
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 (irwin@beluga.phys.uvic.ca) 2005-04-22