*************************************************************************
                Main README file for "Paczynski" codes.
***************************************************************************
        "Stellar Interiors," 2nd ed, by Hansen, Kawaler & Trimble
*************************************************************************
   The original version of this combination of evolution codes dates back
to the early 1970s and was due to Bohdan Paczynski. Since then there have
been many changes and improvements by several authors, some of which appear
on this CD. As noted below, there are three main codes run in the sequence,
all written in FORTRAN,
                k02 --> s03 --> h03.
            Each code has it separate directory on this CD.
The first (k02) makes a table of an envelope model for fixed X (H-mass
fraction) and Z (metal mass fraction). The second (s03) constructs a ZAMS model
using the fitting method (see our Chapter 7). The last code (h03) uses the fit
model and evolves it. This code will only treat hydrogen burning so you can
forget about helium burning and later stages. In addition, the opacities and
equations of state are, at latest, pre-1980 so don't expect up-to-date models.
Our purpose in including these codes is to give the student a taste of what
evolution codes are like. Frustration may also be present---as you may find out
from running them. The version of codes here have been trivially modified by
Carl Hansen so he could get them to run on a PC with a Microsoft (Powerstation)
FORTRAN compiler (c. 1994, but it is a strict compiler that does not like
sloppy coding). Also, see the note below for UNIX users.
        If you wish to try running a much more modern version of this code you
can access it and ftp download it from the WWW-site
          http://cfa-www.harvard.edu/~sasselov/astro206/tools.html
as the set "evolC." ("evolB" on that site is the code that is on this CD.) We
warn you, however, that it is VERY long and complicated. The reason we do not
include it here is that it represents many hours of work and we did not feel it
proper to include it in what for our publisher is a commercial enterprise. (We,
the writers, work for peanuts.) Bohdan Paczynski also maintains copies of the
codes that can be anonymous ftp-ed from the site
          astro.princeton.edu   in the directory   bp/evolution . There are two
sets listed below with the numbers in front denoting volume in bytes (after
compression and CJH thanks Bohdan for this info):
                   8752  readme_93
                 332657  evol_93.tar.gz  (this is evolB as CJH checked)
                   9174  readme_97
                9064361  evol_97.tar.gz  (evolC)
Note the size of  evol_97. It does real evolution!

Before we pass you on to the readme file that comes with the older codes, what
you will find in this directory are  .F  and  .EXE  versions of the codes
where the  .EXE is for Windows based PCs. CJH has checked them out and we
include sample output in the directories labeled as MMMZZXX where the MM
(after the initial M) gives the mass (in solar units), ZZ is the metal mass
fraction Z, and XX is for X. Thus M020370 is for a 2 solar mass model with
Z=0.02 and X=0.70. (NOTE: CJH could not get 2 solar mass models to evolve. An
example of frustration.) The files in those directories are discussed below
and in the introductions to s03 and h03. However, just so you don't have to
plough through h03 to find out what's in a  MOd00xx.h03 file (see below) we
offer the following key. (The file evol.h03 is self-explanatory.)
        first line:   2 4
        2nd line:     nh=2+number of points in the model
        3rd line:     log L(ergs/s), log M (g), log of elapsed time (yrs),
            log time step (yrs)
  then, for k=1 to nh-1 (from model center to next-to-last point with two lines
            per k)
        kth lines:     log density, log T, log r (cm), log L_r/L(surface),
            ln(M_r/[M-M_r]), x(at r), Y(at r), mass fraction of nitrogen (at r)
            Here, M_r (L_r) is mass (luminosity) to r and note that log is
            the natural log (ln)!
        Last two lines: log T_eff, log L/L(sun), M/M)(sun), then zeros of
            no import.

Also included in the M010270 directory are three Encapsulated PostScript files
(.eps) containing graphics illustrating some aspects of the evolution of
the model.

Note: All the input data files have been cleaned to remove  ^M (Control M,
CR, Hex 0D) bytes so that they can be read on UNIX based systems that cannot
tolerate the ^M. Line feeds (^J, Hex 0A) have been retained. We mention this
because Windows based systems (among others) love to stick in ^M AND a
line feed for no good reason apparent to us. You will, however, see ^M
bytes in the output files since they were written on a Windows based sysytem.
What this means is that some of you will have to start with k02 and march
through s03 and h03 from scratch to generate output to go from one step to the
next.

        Cheers and good luck, Carl J. Hansen
***********************************************************************
And now for the readme file that came with the codes.
***********************************************************************
c ==========                                    ==========
c                   Stellar evolution package
c ==========                                    ==========
c
c        This code has been originally developed by
c         Bohdan Paczynski  and  Maciej Kozlowski,
c          some parts of it have been written by
c                   Stephen J. Ratcliff
c
c            and this version has been prepared
c                   and distributed by:
c
c      Ryszard Sienkiewicz
c      Nicolaus Copernicus Astronomical Center
c      Bartycka 18, 00-716 Warsaw, POLAND
c
c      e-mail: rs@camk.edu.pl
c      FAX   : (intl) - 48 (Poland) - 22 (Warsaw) - 410046
c      telex : 81 3978  (zapan pl)
c
c ==========                                    ==========
c               ANY COMMENTS ARE MOST WELCOME
c ==========                                    ==========
                                          date: October 26, 1993
**************************************************************************
   These programs and data come with absolutely no warranty of any kind.
   The entire risk as to the quality and performance of this package is
   with you.
**************************************************************************



     How to use this standard stellar evolution package ?
     ====================================================

 See a file "h03.f" for some useful remarks concerning range of application
 of this code and then, compile and execute the following Fortran-77 programs:

 1. - "k02"   -  to create a disk file "envopa".
 2. - "s03"   -  to create a disk file "mod0000.h03".
 3. - "h03"   -  to follow stellar evolution - some results
                 are stored on disk files "evol.h03" and "mod####.h03"

                               Good luck !

 Notice:
 the changes introduced to the previous version "02" are as follows:
  - ln (Mr/(M-Mr)) is used as an independent variable (instead of Mr)
  - There is no separate integration of static envelope.
    The boundary conditon is given at the stellar surface.


*******************************************

   IEEE arithmetic errors:
   Before IEEE arithmetic was introduced, all small values, less than
   about 1e-308 (for double precision numbers) were rounded to zero
   (so called "Store(0)" option) without any screen messages.
   Now, IEEE arithmetic does something sophisticated with "subnormal"
   numbers smaller then about 2e-308 and greater than about 5e-324.
   This is so called "gradual underflow" (see e.g.,Sun-4, Numerical
   Computation Guide, page 9-120).
   Moreover, the message "..underflow..."  is send to the user.
   One can switch off this job using "-fast" option during compilation.
   However, the warning "underflows..." will still be sended to the user.
   I did not find where in my code these "underflows" occur,
   but I made some numerical experiments switching on and off the
   above mentioned arithmetic. I did not find any differences in output
   data (at least as concerns first 11 digits - my output format).
   So, I assume that the code is o.k. and these "underflows" are harmless,
   but formally, there is a "non-zero" possibility that some of these
   "underflows" are meaningful....(see Numerical... page 110)
   "Inexact" just means that somwhere in the code are inexact arithmetic
   operations, let us say: 2./3. (see Numerical....page 61).

*******************************************
   As concerns possible errors in the code:
*******************************************

   I shall send by e-mail corrected versions of file to all users
   each time I will find a meaningful error. So the users are asked
   to provide me with their actual e-mail addresses.



 Enclosed please find examples (Sun-4 computer) of these disk files created
 by the above-mentioned programs for the following screen input data:

  program "k02" :
--------------------------------------------------------------
             hydrogen mass fraction, ( 0 &lt; X &lt; 0.80) = .7    |
 heavy elements mass fraction, ( 0.00003 &lt; Z &lt; 0.03) = .03   |
--------------------------------------------------------------

  program "s03" :
----------------------------------------------------------
                mass of the star / solar mass  = 1.      |
                initial hydrogen mass fraction = .7      |
                  heavy elements mass fraction = .03     |
                                                         |
      log10 (surface temperature in degrees K) = 3.64    |
         log10 (luminosity / solar luminosity) = -.25    |
      log10 (central temperature in degrees K) = 7.1     |
            log10 (central density in g/cm**3) = 1.9     |
----------------------------------------------------------

    part of a screen output generated by the program "s03"
    for the above input data :
*****************************************************************************
 iter    = the iteration counter
 log Ts  = log10 (surface temperature)        [K]
 log L   = log10 (surface luminosity)         [L Sun]
 log Tc  = log10 (central temperature)        [K]
 log rhc = log10 (central density)            [g/cm**3]
 facdel  = reduction factor for the corrections, if no reduction
           is applied then "facdel" indicates the largest correction
           (in units of "delmax")
 difmax  = the maximum relative difference calculated at the fitting point,
           in a fitted model, it is less than  1.D-08

  iter  log Ts  log L   log Tc  log rhc        facdel         difmax
     0  3.6400 -0.2500  7.1000  1.9000       2.375261673    0.224008501
     1  3.6303 -0.3000  7.1052  1.8537       0.738629310    0.120803876
     2  3.6264 -0.2756  7.1109  1.8980       1.877541318    0.071214487
     3  3.6213 -0.3256  7.1097  1.8438       1.281436177    0.211247846
     4  3.6265 -0.2756  7.1104  1.8947       1.028643089    0.072779217
     5  3.6212 -0.3256  7.1001  1.8653       0.843711427    0.040756016
     6  3.6252 -0.2834  7.1098  1.8871       0.098169724    0.019718985
     7  3.6245 -0.2883  7.1087  1.8829       0.027511378    0.001586547
     8  3.6243 -0.2897  7.1083  1.8820       0.000541534    0.000034792
     9  3.6243 -0.2897  7.1083  1.8820       0.000000119    0.000000018
    10  3.6243 -0.2897  7.1083  1.8820       0.000000119    0.000000000
    X        Z       M     log Ts   log L  log Tc  log rhc
  0.700 0.0300000  1.0000  3.6243 -0.2897  7.1083  1.8820
 writing "mod0000.h03",   nh =333
  ...done
 Programmed STOP =&gt; s03 - okay
*****************************************************************************


  program "h03" :
---------------------------------------------------------------
  ready to read model prepared earlier by the program "s03"   |
  (file "mod0000.h03") or "h03" (file "mod####.h03") =&gt;       |
  enclose selected file name in SINGLE quotes :               |
  'mod0000.h03'                                               |
  number of models to be calculated,         nofmod= 10       |
  every nwrmod`th model data will be stored, nwrmod= 10       |
---------------------------------------------------------------

================================================
   Contents of this package (23 files):
================================================

    1. " readme.03 "              this file
            +                 ..................
    2. " k02.f "
    3. " s03.f "                 main programs
    4. " h03.f "
                              ..................

    5. " commonsb.03 "
    6. " opacity.03 "           auxiliary
    7. " eostate.03 "              subroutines
    8. " nuclear.03 "
    9. " data.03 "
                              ..................

   10. " opint1 "
   . . . . . . . .
   16. " opint7 "               opacity  data
   17. " molgr.ajr "
   18. " minigrid.ajr "
                              ..................

   19. " electron.gas "          e.o.s. data

                              ..................

   20. " envopa "                  examples
   21. " mod0000.h03 "          of output/input
   22. " evol.h03 "             data disk files
   23. " mod0010.h03 "
================================================
****************************************************************************
                        End of README.TXT