Introduction

Preface

This documentation is based on KEPLER Manual Version 1 of May 1991. This manual comprises also all the updates to KEPLER since that date: new parameters, output and input files, and new and modified code capabilities.

Histroric Preface

KEPLER is a general purpose stellar evolution/explosion code that incorporates implicit hydrodynamics and a detailed treatment of nuclear burning processes. It has been used to study the complete evolution of massive and supermassive stars, all major classes of supernovae, hydrostatic and explosive nucleosynthesis, and x- and gamma-ray bursts on neutron stars and white dwarfs. Many aspects of the physics it currently includes has been briefly summarized in [WZW78], [WWF83], and many other papers describing the results of its calculations. Additional documentation is in progress. KEPLER does not currently contain detailed models of neutrino transport and the equation of state of hot matter near nuclear density, but it has the capability to be linked to codes (such as that of Wilson et. al.) that do or to treat these processes in parameterized form.

After more a decade of specialized residence on the CDC 7600, a general (almost standard FORTRAN) version of KEPLER has been developed for use on UNIX super-minicomputers with X-Window graphics (such as P Group’s 4D/240VGX computer, leonardo), and in a more limited form on CRAY computers. This new version of KEPLER includes calculations of detailed isotopic nucleosynthesis (“BURN co-processing”), extensive graphics, interactive post-processing, updated nuclear reaction rates, and many other new and/or improved edit and physics capabilities.

The current UNIX version of KEPLER on which this manual is based is kepler.1may91.

This documentation includes a discussion of the input files (“generators”) needed for KEPLER, of the user-changeable KEPLER parameters, how to run a KEPLER problem and also the interactive keyboard commands that are available for editing and job-control.

Also useful is list of the zonal edit variables that may be edited, graphed, or stored in post-processor dumps and a lists of both the user-unchangeable edit (‘Q’) parameters and the non-zonal, time-dependent (“time-edit”) variables, which can be graphed vs. time, and a brief description of the form of some of the (less obvious) edits that KEPLER produces.

Conventions

Terminal commands and input file cards are listed according to the following conventions:

command REQUIRED-INPUT [ OPTIONAL-INPUT ]

Here the words in capital italics are to be replaced by specific input values, and words in square brackets are optional parameters. Usually a specific example is given directly below the command or card to clarify the input format.

Format Convetions

Example

Description

command

literal input card/command

VARIABLE

command variable - replace by actual value

xm

KEPLER varibale, parameter, or subroutine

Todo

refinestuff

All communication with the computer must currently be made in lower case and character strings must not be enclosed in quotes except where explicitly stated.

Historic Version Notes

keplera (16iii76)

keplera is an implicit hydrodynamics code which is identical in almost all respects to gbz’s code hino. the main difference is that the coupled equations and back substitution algorithms have been written in vectorized and matrix form to facilitate later changes in the physics and number of implicit variables. comparison of the results of keplera with those of hino show essentially exact agreement (in fact the only detectable difference is in the energy check and is due to differences in round off errors between the two codes.)

keplerb (26v76)

keplerb is a modified version of keplera in which luminosity as well as radius and temperature are treated as implicit variables. this was done to achieve a more accurate treatment of convection since the convective luminosity is a very sensitive function of the temperature gradient.

keplerc1 (5vii76)

an automatic rezoning option has been added to keplerb to produce keplerc. in general, the rezoning scheme conserves momentum and total energy, and where possible preserves interpolated accelerations ( and thus hydrostatic equilibrium). such rezoning is necessary to treat shell burning and core collapse.

keplerd (9ix76)

a modified version of sew’s approx code has been integrated into keplerc1 to produce keplerd. this resutlts in an sdot which calculates energy generation rates and abundance changes by inverting a 17x17 element network covering hydrogen burning through iron decomposition. a low temperature bypass and a 8x8 subnetwork for hydrogen and helium burning have also been incorporated to save computer time.

keplere (27x76)

new equation of state and opacity subroutines have been incorporated into keplerd to produce keplere. the present eos treatment includes both electrons and pairs with an arbitrary degree of relativity or degeneracy. the new analytic opacity fits apply to a wide range of stellar compositions, are principally due to iben (1975), and appear good to 50% for densities and temperatures of interest in stellar evolution. an accurate fit to the compton scattering opacity ,taking into account the effects of relativity and degeneracy, was made (by taw) and is good to 5% in the regime of interest. energy and pressure sources intended to crudely mock up neutrino deposition in a supernova explosion were also included. a fast sparse matrix gauss-jordan based technique has been added to speed up the nuclear energy genration calculation by a factor of 2.5. in addition, reaction rates near nuclear statistical equilibrium have been limited to prevent mass nonconservation and time step glitches due to round off error in the matrix inverter.

keplerf (26xii76)

keplerf incorporates an interactive graphics package, an improved treatment of convection (including convective overshoot), a more flexible rezoner, more detailed time edits, and a number of other minor improvements.

keplerg (21ii77)

keplerg includes strong, intermediate, and weak screening, a state of the art treatment of neutronization, alpha photo- disintegration, electron capture, an improved fe54-ni56 link, and a formulation of the nuclear rate equations that avoids large mass non-conservation errors near nse without having to artificially limit the reaction rates. in addition, the average running speed of the code has been increased by a factor of 2 by extrapolating nuclear energy generation rates from their previous values when rho and t have barely changed. non-relativistic ion degeneracy has also been added to deal with neuton star formation.

keplerh

keplerh incorporates an implicit link between changes in abar and the ion equation of state in order to improve code convergence in regions of near nuclear statistical equilibrium. permanent labeled restart dump files, automated output, and an excessive iteration code termination option have also been added. in addition, a post-processor dump and options to only calculate an interior subregion and eliminate unused sdot derivatives have been implemented.

keplerj

keplerj incorporates mazurek’s (1973) electron capture rates in place of hansen’s rates where the former are available and a nearly exact treatment of electron capture on protons and positron capture on neutrons (see ecapnuc). the nse and qse networks have been extended to 121 elements and are believed to give accurate compositions for electron abundances between 0.43 and 0.50.

keplerl

last modified 9 september 1982 to put in rp-process (keplerl15) keplerl is a modified version of keplerj. the qse subroutines have been changed to approximate situations where the dominant silicon isotpe is no longer just si28 but a mixture of si28 and si30. an initial profile of ye for various mass zones can be given as an initial condition to the silicon burning qse subroutine and silicon burning flows in addition to 24mg(ga)20ne are accounted for. all qse-related nuclear processing routines have been incorporated into a controllee called qburnl. features to allow automatic running in free standby mode and writing eos tables have also been implemented.

keplerm2 (24xii82)

keplerm incorporates a 125 isotope network, intermediate statistical equilibrium treatment of silicon burning in order to better treat the neutronization that occurs after oxygen burning and during the early phases of silicon burning. the weak interaction rates of fuller et al. (1982) are now used in preference to the earlier results of mazurek(1973) and hansen(1966), and the effects of photodisintegration flows through neutron-rich isoopes have been included in the calculation of the rate of silicon burning. space for additional zones and parameters (up to 500) has been added, together with the ability to restart problems from a version of kepler with a smaller or larger limit on the total number of zones. the normalized nuclear binding energy for qnse zones is now included as part of the zonal internal energy (in es), and the effect of energy stored in nuclear excited states is explicitly taken into account by differentiating the nuclear partition function with respect to temperature. this allows a careful and consistent distinction to be made between changes in nuclear binding energy due to temperature and density changes as opposed to changes due to non-equilibrated composition changes. the treatment of screening has been improved in the strong screening limit (but still not suitable for pyconuclear burning), and screening has been included for the first time on photodisintegration reactions and flows. the ise network has now been expanded by the inclusion of an unburned o16 component to allow the treatment of the burning of oxygen convected into si zones.

keplerm3 (26xii82)

keplerm3 incorporates abundance backups when abundances go too negative or change too much during the course of an iteration.

keplerm4

keplerm4 incorporates a multiplier on the non-resonant part of the c12(a,g) cross-section (p208) and doesn’t use neighboring zone values to initialize a new qse zone unless y56gessm (p201) is 1. neutrino acceleration option corrected.

keplerm5

keplerm5 incorporates two additional parameters. xltaucon which limits the amount of convective luminosity increase during a time step (for convective deflagrations) and noqsecon which can be used to circumvent automatic switching to qse of zones that are convectively linked. zero values defeat each of these two operations. also abundance back-ups will now specify which zone the back-up occurred in. finally the ability is incorporated to simulate real mass accretion. the accretion rate is accrate (p 211) and the surface boundary pressure is increased accordingly. each time the mass accretion counter (xmacrete = p 212) reaches the mass of the outer zone, a new mirror zone is added and the counter reset.

keplerm6

keplerm6 initializes ye in new ise zones to be 0.498 rather than 0.50 or greater as given by current composition (in absence of yeset cards). ye above 0.50 gives convergence problems in qburn.

keplerm7

keplerm7 updates the nuclear reaction rates to account for changes in the experimental values since 1976. in particular, new rates from harris et al (ann. rev. astron. ap., 21, 165, 1983) and caughlan et al (oap 400 1984) are incorporated for 3a, 15n(pa)12c, 12c(ag)16o, 16o(ag)20ne, 24mg(ag)28si, and 27al(pg)28si.

keplerm8

keplerm8 repairs a bug in the rezoning routines that would cause the code to crash on abundance back-ups under certain situations. previous runs are ok but the code should crash less now. (august 20, 1984).

keplerm9

keplerm9 allows resetting of abundance array with “approx” command in subroutine link that repacks ise arrays approximately correctly. “neutron-rich” iron is now stored in fe52 (this includes fe56). also energy storage in excited states of c12, o16, ne20, and mg24 has been eliminated in the equation of state when using the approx network. (december 14, 1984).

keplerma

flamerad parameter 214 introduced to vary flame velocity during deflagrations denconv parameter 213 introduced for variable convergence criterium using dstat option. slightly modified version of keplerm9 to allow ignition of ise off-center. initialization altered in subroutine sdot. (march 1, 1985)

keplermb

wilsonmt initialized to zero and coulomb corrections added to equation of state. new multiplier coulmult (p 215) multiplies these corrections (june 24 1987)

keplermd

new rezoning options (p 216) added to suppress rezoning across convective boundaries and to modify the density gradient considered in adzoning by the offsetting effects of abar gradients. these options serve to prevent unnecessary adzoning near the base of a convective hydrogen-burning shell. (october 20 1987)

temperature convergence criterion in tnconv and enconv changed from 1.e-6 to 1.e-5. default value of etaconv changed from 1.e-4 to 1.e-5. this should reduce code crashes due to rezoner nonconvergence and improve the general accuracy of the overall calculation. (november 23 1987)

keplerme

corrects a bug in how ye was being initialized for the coulomb correction introduced in keplerb which resulted in the ye value from a different zone (usually the innermost) being used (in calculating the coulomb correction only). this error only occurs where the burn network is used so that the quantitative effect may be small (i.e. ye usually about 0.5 where the coulomb correction is at all important). this bug seems responsible for the recent convergence problems in the rezoner. (november 25, 1987)

keplermf

mass loss options and parameters added. [i-iii.88]

more automatic output options added. also e1 and e2 partial width multipliers added for the c12ag reaction (approx only). [18 march 1988].

e1mltc12 (p 227) and e2mltc12 (p228) added. iautoout (p 159) modified. ascii output file size also reduced to stop fiche overflow. [30.iii.88]

fix dezoner bug by not allowing dezoning involving the outer zone. [17.v.88]

keplermg

12c(ag)16orate revised per caughlan and fowler 1988 (“thermonuclear reaction rates v” plus waf priv. comm.)

keplermh

neutrino losses modified for neutral currents may 27, 1988

keplern

fortran 77 version of keplermh

keplery

(1996 by S.E. Woosley)

This has been the basis for further development and for this manual.

keplerz (1997 by A. Heger)

OPACITY

opacity tables debugged

MASS LOSS

mass loss rate by Nieuwenhuijzen et al A&A 231 (1990) included: xmlossn(p 363) added. default: 0.0D0

metalicity dependent mass loss rate for DeJager and Nieuwenhuijzen mass loss rates Mdot~(Z/Zsun)**0.65D0 according to Kudritzki et al.

new edit parameter added

xmlossr(q 82) current mass loss rate in g/s

REGESS

fmin (p 375) added reduce correction to variables during iteration by this factor

ROTATION

generater card format changed

angular velocity inserted prior to velocity

new format now is

initial grid (zone #, exterior mass(g), network #, temp(K), rho(g/cc), [omega(1/s)[, u(cm/s)]])

u and omega both remain undefined if not specified explicitly and will then be interpolated, expect for the inner and outer boundary where a value of zero will be assumed

new edit variables added

eninr(q 78) initial total rotational energy

enr(q 79) actual total rotational energy

eninr(q 80) initial total angular momentum

eninr(q 81) actual total angular momentum

new zonal edit variables

new plots added

linkfile card added to generator file use:

linkefile FILENAME

will read in link file and initialize stellar structure.

do not use in combination with g cards (see subroutine gener/kepou.f for details)