KEPLER Generator Input Cards¶

Except as noted, KEPLER generator cards may occur in any order, but must always include

a network definition (net card),
a mixture definition (m card), and
a grid definition (explicit definition by g card or from a linkfile card)
a box card on the CRAY.

Deprecated Since Version >15.0.0: CRAY is no longer used.

All cards not listed below are passed on to regular input processing. But in particular usually p cards are used and c cards should be used to document the file contents in comments.

Generator Input File Naming

When starting KEPLER and g is specified as input file name, KEPLER will search for file name BASEg, where BASE is base file name.

Required Cards¶

Below is a list of input cards that are specific to generator files only.

net

Network Card(s).

name

parameters

net

NETNUM IONSYM+
net 1 h1 he3 he4 n14 c12 o16 ne20 mg24 si28 s32
net 1 ar36 ca40 ti44 cr48 fe52 ni56 fe54 pt1 nt1
NETNUM

is the identification number of the network being specified. For the current version of KEPLER, the network specified must be the APPROX network given in the example, and the network number must be 1.

IONSYM

is the symbol for the an ion in the network. (See the m card description for how to format these symbols). They can be specified in any order. If there are more than 10 ions in the network, continue on a new net card with the same network number.
net_statement ::=  "net" netnum ( ionsym )+
netnum        ::=  number
number        ::=  "1"
ionsym        ::=  "h1" | "he3" | "he4" |
                    "n14" | "c12"  | "o16" |
                   "ne20" | "mg24" | "si28" |
                    "s32" | "ar36" | "ca40" |
                   "ti44" | "cr48" | "fe52" |
                   "ni56" | "fe54" | "pt1"  |
                   "nt1"

m

Materials Card(s).

name

parameters

m

MIXNAME ( MASSFRAC IONSYM )+
m solcomp .70 h1 .28 he4 .02 nl4
MIXNAME
is the name of this mixture of ions ( $\le8$ characters).

MASSFRAC
is the mass-fraction of the i^th ion in the mixture.

IONSYM
is the symbol for the i^th ion in the mixture and consists of an lower case elemental symbol followed by the atomic weight (without a space), e.g., he4. Also, each ion listed here must be one of the ions in a specific network specified by the NSE card(s).

Pairs of such mass fractions and ion symbols are listed for each ion in the mixture. Continue if necessary on a new m card with the same MIXNAME. After all such cards have been read, the code renormalizes the sum of the mass fractions to insure it equals 1.
material     ::=  ( materialcard )+
materialcard ::=  "m" materialname ( abundance )+
materialname ::=  string
abundance    ::=  massfrac ion
massfrac     ::=  float
ion          ::=  APPROX ion name

g

Grid Cards. (At least 2 required).

name

parameters

g

ZONENUM MASS NETNUM MIXNAME TEMP DENSITY [ OMEGA [ VELOCITY ] ]
g 0 4.e+34 1 solcomp 1.le+7 0.9 0.
ZONENUM
is the number of the zonal interface being described (j). This should always be 0 for the first g card and be equal to the total number of zones desired for the last g card. For intermediate g cards, j should increase monotonically between these values. Not every interface need be specified, and conditions at intermediate interfaces will be calculated as described below.

MASS
is the mass coordinate for the grid. Without other modification cards, this is the mass (in grams) exterior to the zonal interface being specified. (ym(j)). Specified values must increase monotonically with zonal interface number (j). Exterior masses for zonal interfaces between those specified will be interpolated from the specified values by minimizing the sum of the squares of the fractional changes in zone mass across each interface (See subroutine XXX zonit).

Changed In Version >15.0.0: When the generator cards rescalem or zonemass are used, the mass values will be interpreted differently, for ease of use and adaptability.

NETNUM
is the number of the nuclear-burning network to be used between this zonal interface and the next one specified. (netnum(j)). Currently it must be 1 (see net card(s)).

MIXNAME
is name of the material (as specified by the appropriate m cards) that lies between this zonal interface and the next one specified. (imsen(j)).

TEMP
is the temperature (K) of the zones that lie between this interface and the next one specified. (tn(j)).

DENSITY
is the density (g/cc) of the zones that lie between this interface and the next one specified. (dn(j)).

OMEGA
is angular velocity (rad/sec) of the zone. If not specified, it is assumed to be 0. Velocities for zones between those where OMEGA is specified are determined by interpolating linearly. For example, to generate an initial model with constant gradient in the rotational velocity (or a rigidly rotating model), only for the innermost and the outermost zone values for OMEGA have to be supplied.

New In Version >15.0.0.

VELOCITY

is the velocity (cm/sec) of this zonal interface. (un $(j)$ ). If not specified, it is assumed to be 0. Velocities for zonal interfaces between those specified are determined by interpolating linearly with radius.
grid     ::=  ( gridcard ){2,}
gridcard ::=  "g" ...
Changed In Version >15.0.0: The generator card g has been enhanced in order to allow for the addition of rotation on generation of the problem.

linkfile

Generate a stellar model from file FILENAME.

name

parameters

linkfile

FILENAME

linkfile E12B.dat

When this command is used, no further g cards are allowed nor needed.

For linkfile version 10000, the following comments come from the code:

read in link file from Kippenhahn code (Version A. Heger)
in Version 10000 this file contains the version number at columns
8..14 (8X,I7) of the first line and then 8 line of comments
describing the setup of the model
line 10 holds the current time of the problem (1p,e25.17)
line 11 holds the number of grid points (1X,I5)
then, the first section contains the number of the shell,
mass per shell, temperature of the shell density of shell,
velocity at outer boundary of shell and angular velocity of the
shell
the format is (1x,i5,1p,5e25.17)
the following blocks list the chemical composition of the shell,
again each line is headed by the number of the shell.
The composition is given in blocks of 6 elements.
The elements are y_n, y_p, y_3He, y_4He, y_12C, y_14N in the first
block and y_16O, y_20Ne, y_24Mg, y_28Si, y_54Fe in the second
the format is (1x,i5,1p,<columns>e25.17)

In linkfile version 20000 the file has the following format:

(8X,I7) ! ivers   - version number
*       ! ncyc    - cycle number of dump
*       ! timesec - current problem time (s)
*       ! jm      - number of zones
*       ! rn(0)   - inner radius (cm)
! loop over all j=1..jm
*       ! rn(j),xm(j),tn(j),dn(j),angw(j),un(j), \\
        ! (xn(j,i),i=1,19)
! here is we have:
! rn   - radius of outer zone boundary (cm)
! xm   - mass of zone (g)
! tn   - temperature of zone (K)
! dn   - density of zone (g/cm**3)
! angw - angular velocity of zone (rad/s)
! un   - velocity of outer zone boundary (cm/s)
! xn   - mass fraction if species i of zone j, i = ...
!           n,  h1,    p,  he3,  he4,  c12,  n14,  o16, ne20, mg24,
!        si28, s32, ar36, ca40, ti44, cr48, fe52, fe54, ni56

New In Version >15.0.0.

Optional Cards¶

genburn

Burn Generator Card.

name

parameters

genburn

NAMEBG
genburn soII60bg
Inclusion of this card causes KEPLER to read the BURN generator file, NAMEBG, immediately after normal problem generation and to initiate BURN co-processing. NAMEBG can be up to 16 characters long and is not restricted, though by normal convention it ends in the letters ‘bg’.

isenet

ISE Network Card.

name

parameters

isenet
isenet
This card is a flag that the standard ISE and NSE networks (NETNUM $=$ 2 and 3, respectively) are to be set up for possible later use, in addition to the usual APPROX network (NETNUM $=$ 1). Zones should never be specified on a g card to initially be either ISE or NSE, but they should instead be allowed to make the transition (or not) while the problem is running depending on the physical conditions encountered and the setting of various control parameters (see Chapter XXX).

hstat

Hydrostatic Equilibrium Card.

name

parameters

hstat
hstat
Forces the specified initial configuration into hydrostatic equilibrium by adjusting the temperature.

dstat

Degenerate Hydrostatic Equilibrium Card.

name

parameters

dstat
dstat
Forces the specified initial configuration into hydrostatic equilibrium by adjusting the density. Useful in very degenerate cases, such as white dwarfs or neutron stars.

radlim

Minimum zone thickness relative to radius coordinate.

name

parameters

radlim

VALUE
radlim 1.e-6
VALUE
value of relative radius limit for grid adjustment.

If a zone is thinner than VALUE, radius and density are adjusted. Default is 0.001. Set to zero to keep density unchanged.

rescalem

Scaling of mass coordinate.

name

parameters

rescalem

SCALE [ msun ] [ mult | div ]
rescalem 12. msun
rescalem 12. div
rescalem 13. mult
SCALE
scaling value for mass coordinate

Scale the mass coordinate by SCALE. If msun is given, the scaling factor is multiplied by $\mathrm{M}_{\odot}/\mathrm{g}$ .

If div is given, the mass coordinate is divided by the scale factor, otherwise it is multiplied by the scale factor. The flag mult has no effect but but can be specified for clarity. It must not be given together with div.

This command allows to adopt a generator file with a given mass grid to a different mass.

Note

This overwrites/modifies the mass coordinate specified by the g cards.

New In Version >15.0.0.

zonemass

Determinse that generator card give zone mass not mass coordinate.

name

parameters

zonemass

[ g | msun ]
zonemass g
Obviously we need to specify same zones. As a backup, for now, the mass of the previous zone will be copied. In this case, however, you still need to specify the mass of Zone 1.

Note

The mass of zone 0 is ignored. But you may need to give this zone for velocity and angular velocity interpolation.

If the mass unit (g or msun) is omitted, g is used as the default.

Note

This overwrites/modifies the mass coordinate specified by the g cards.

New In Version >15.0.0.

rotation

Generator card to specify units of rotation to conserve during iteration.

name

parameters

rotation

k | kepler | o | omega | j
rotation omega
k, kepler
use fraction of keplerian rotation

o, omega
use angular velocity

j
use angular momentum

Note

Obviously this cannot be used in combination with rigidl, which takes precedence.

New In Version >15.0.0.

rigidl

Set angular momentum of star.

name

parameters

rigidl

VALUE
rigidl 1.d52
VALUE

new total angular momentum of star (units erg*sec)

This card allows to give the star the angular momentum VALUE (units erg*sec) at start-up and distribute it such that the star is rigidly rotating. The rotation value on the grid cards is ignored.

New In Version >15.0.0.

rigidv

Set surface rotation velocity of star.

name

parameters

rigidv

VALUE
rigidv 1.e6
VALUE
equatorial surface rotation velocity of star (units cm/sec)

This card allows to give the star a surface rotation velocity VALUE (unit cm/sec) at start-up such that the star is rigidly rotating. The rotation value on the grid cards is ignored.

New In Version >15.0.0.

rigidw

Set surface angular velocity of star.

name

parameters

rigidw

VALUE
rigidw 1.e-6
VALUE
surface angular velocity of star (units rad/sec)

This card allows to give the star an angular velocity VALUE (unit rad/sec) at start-up such that the star is rigidly rotating. The rotation value on the grid cards is ignored.

New In Version >15.0.0.

rigidk

Set surface angular velocity of star as fraction of Keplerian rotation velocity.

name

parameters

rigidk

VALUE
rigidk 0.2
VALUE
surface angular velocity of star as fraction of Keplerian rotation velocity.

This card allows to give the star a fraction of Keplerian velocity at the surface at the equator of VALUE at startup such that the star is rigidly rotating. The rotation value on the grid cards is ignored.

New In Version >15.0.0.

mapburn

Map BURN abundances to APPROX abundances.

name

parameters

mapburn
mapburn
Note

Abundances set using the g card or linkfile card are ignored.

Note

If BURN is not active, this card is ignored.

New In Version >15.0.0.

link

Include other files.

name

parameters

link

FILENAME
link sollo03g
FILENAME
name of file to include.

Commands from include file are inserted and executed literally.

Note

Include files can be nested (include files may contain further include files), however, the maximum nesting level is nine (9).

Note

This is different from the link command as it needs to process the generator commands and set flags for generation of the star. Files linked using the link command must not contain generator cards.

New In Version >15.0.0.

Changed In Version 17.0.2: The name of the card used to be “include” but has been renamed to reflect that it has a evry similar functunallity as the input card with the same name.

//

The rest of the file will be appended to command file.

name

parameters

//

New In Version 17.0.2.

//*

Same as // but delete all old command files.

name

parameters

//*

Note

This is done only once during generation, the first time it is encountered.

New In Version 17.0.11.

Deprecated Generator Commands¶

box

Identification Card. (Required on CRAY, optional on UNIX systems).

name

parameters

box

BOX ID-WORD
box v98 weaver
BOX
is the user’s output box and must be three characters long. It is used for directing output files on the CRAY.

ID-WORD
is an identification word (88 characters), usually the user’s name.

Deprecated Since Version >15.0.0: (about 1996)

Useful Input Cards¶

Note

The following cards are not specific to generators.

c

Comment - ignored.

name

parameters

c

[ COMMENT ]
c the parameter settings below make the run more smooth
Comment Card.

COMMENT
is an arbitrary alphanumeric string that is ignored by the code. Note that it must be separated from the c by at least one space.
Main entry:
Normal Program Managment Commands

p

Edit changable (‘P’) parameters.

name

parameters

p

[ ( PARAMETER [ ( ( - | .. ) PARAMETER ) | ( VALUE [ OPERATION ] ) ] ) | ( LISTVALUE [ list ] ) ]
p
p 1
p 1 1.e-5
p 1 2. *
p 1 - 3
p 1 .. 3
p 1 .0001 %
p 1 list
p 1.d-14
p *time
PARAMETER

is the name or number of the parameter to be specified. See Changable (‘P’) Parameters for a list of the changeable parameters in the code and their units and default values.

VALUE

is the value to be assigned to this parameter. Note that fixed point parameters must have fixed pointed values specified, and floating point parameters must be given floating point values (i.e., $1 \ne 1.$ ). If VALUE is a string, this cannot be a valid float

OPERATION

add | mul | div | sub | mod | * | - | + | / | %

LISTVALUE

Value for parameter list by value. Integer or float.

Note

If the desired list value is also valid parameter number, then use the “list” keyword, otherwise it may be omitted.

Parameters are internally first set to their default values, but can be overwritten uisng input cards, e.g., in generators or interactively.

For editing parameters one may use either their number or name.

Current parameter values can be querried using the “p command by just specifying their numer or name. A range of parameters can be listed using “-” or “..”. The “*” wildcard can be used at the beginning or the end to list all parmeters with matching names where the usual UNIX shell-type maching is performed, “*” standing for any number of arbitrary characters. Parameters can be listed by matching numerical value using the “list” keyword. If the numeric value is of type float or integer and out of the allowed range of allowed parameter numbers, the “list” keyword may be omitted.

Parameters can be changed by specifying the new value or using one of the operations “*”, “-“, “+”, “/”, or “%” on the current value.
parmetercard ::=  "p" listspec | setspec | vallistspec
listspec     ::=  [ parameter [ rangeop parameter ] ] | wildspec
rangeop      ::=  "-" | ".."
wildspec     ::=  "*"string | string"*" | "*"string"*"
setspec      ::=  parameter value [ operation ]
vallistspec  ::=  value [ "list" ]
parameter    ::=  name | number
name         ::=  string
number       ::=  integer
value        ::=  float | integer | string
operation    ::=  "add" | "mul" | "div" | "sub" | "mod" | "*" | "-" | "+" | "/" | "%"
Changed In Version >15.0.0: Added matching by wildchard and parameter range.

Changed In Version 16.85.0: procession of p cards by ttycom allows the use of parameter names in generators. Prior to that, only parameter numners were allowed in generators.

Changed In Version 17.0.2: List parameters by value.
Main entry:
Normal Program Managment Commands

Note

All forms of the p card are allowed in generators, however, only setting values has any useful impact.

Changed In Version 17.0.0: generator p cards used to allow only setting parameters and only allowed to specify parameters by number.; now any form of the p card is allowed in generators (as they are processed by the same routine as other input).

datapath

Set or enquire path to data files.

name

parameters

datapath

[ PATH | clear ]
datapath /home/alex/kepler/local_data/
PATH

path to data files.

clear

reset the data path.

Set the data path if PATH is specified. Delete the content of datapath of “clear” is specifies. Display the current data path otherwise.

The datapath variable is where KEPLER looks for data files if they cannot be found in the local directory.

If the environment variable KEPLER_DATA is set, KEPLER will also look in the path specified in the variable for data file if they cannot be found in the local directory or the directory specified in datapath (if set). This allows for a machine-dependent setting of the data path and is probably the better way in most cases when general/global files are to be used. The use of datapath allows. however, to give the location of specialized files (maybe as relative path). In both cases, datapath and KEPLER_DATA, the character “~” (tilde) is replaced by the value of the system variable “HOME”, allowing for machine-independent specification of paths.

Note

It is more portable to use environment variables or keep the data files or links to them in the local directory.

New In Version >15.0.0.

Todo

Check whether this is not already in ttycom
Main entry:
Special Purpose Commands

dump

Add dump variable DUMPVAR to the list of variables to be dumped to the qq post-processor dump file or change its dump parameters if it is already in the dump list.

name

parameters

dump

DUMPVAR RATZDUMP RATIODEZ RATIOADZ
dump convect .l -1. 0.
DUMPVAR

may be any zonal edit variable, and in addition it may take the values:

value

result

parm

to dump the values of the changeable (‘p’) parameters

qparm

to dump the values of the edit (‘q’) parameters

RATZDUMP

the maximum allowed fractional change between dumps of the specified zonal

RATIODEZ

the minimum fractional change of this zonal dump variable allowed between two adjacent dump grid points before the dump grid for the variable is dezoned

RATIOADZ

the maximum fractional change of this zonal dump variable allowed between two adjacent dump grid points before the dump grid for the variable is adzoned

The associated dump parameters must be given for each variable. In the case of parm and qparm the values of RATIOADZ and RATIODEZ are ignored but dummy values must still be given.

Note

Note that the dump command for new variables is usually given in the problem generator file.

Note

This command may be useful in generators

Deprecated Since Version >15.0.0.
Main entry:
Special Purpose Commands

zedit

Initiate that a special multiple column ASCII edit of the specified zonal edit variables (EDITVAR+ )to be written every NCYCZED cycles.

name

parameters

zedit

IZED NCYCZED ( EDITVAR )+ [ ZEDMASSl [ ZEDMASS2 ] ]
zedit 1 50 dn tn sige sigi sigr 0. 2.
IZED

Edit variable index number (max nzedz).

NCYCZED

Cycle frequency. Set to 0 to terminate edits.

EDITVAR

Edit variable, see Zonal Edit Varlables.

ZEDMASSl

Lower bound of mass range in scalem (p 273) units or mass coordinate ( $\pm1\,\%$ ) for which edits are made.

ZEDMASS2

Uper bound of mass range in scalem (p 273) units for which edit is made.

This command causes a special multiple column ASCII edit of the specified zonal edit variables (EDITVAR+) to be written every NCYCZED cycles. Here lZED is an index number (maximum of NZEDZ, which currently is 30, see kepcom) that distinguishes separate zedit requests, and ZEDMASSl and ZEDMASS2 specify an optional interior mass range (in scalem (p 273) units) to be edited. If only ZEDMASSl is specified, a $\pm1\,\%$ range around it is edited, and if no masses are specified, an edit of the whole star is made. Previously specified edits can be changed or terminated by overwriting them with a new zedit command with the same index number.

Note

Setting NCYCZED $=$ 0 ternlinates the edit.

Note

This command is especially useful in generators.

Deprecated Since Version >15.0.0.
Main entry:
Other ASCII Output-File Edit Commands

/

Add command after “/” at the end of command file.

name

parameters

/

COMMAND
/ *
/ @tn(1)>1.d9
/ d #tc9
/ end
COMMAND

string to add to command file

See the page on command files for command file name resolution rules.

New In Version 17.0.2.
Main entry:
Special Purpose Commands

KEPLER Generator Restrictions

Note

The values below are historic values; current values may differ.

Restrictions corresponding to current FORTRAN parameter settings in include-file kepcom and subroutine gener are listed below. These may be changed by editing and recompiling KEPLER.

nniz: Maximum Number of Networks $=$ 5. (But see discussion in net card definition.)
nhiz: Maximum Number of Ion Types per Network $=$ 20.
nmiz: Maximum Number of Material Mixtures $=$ 10.
nimz: Maximum Number of Ion Types per Mixture $=$ 20.
nitz: Maximum Number of Ion Types Overall $=$ 100.
ndatqz: Maximum Number of dump cards $=$ 250.
nzedz: Maximum Number of zedit cards $=$ 30.
jmz: Maximum Number of Zones $=$ 650.