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 ith ion in the mixture.

IONSYM

is the symbol for the ith 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 [ [ OMEGAX OMEGAY ] OMEGAY ] OMEGAZ [ 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)).

OMEGAX OMEGAY OMEGAZ

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

VELOCITY

is the radial 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.

Changed In Version 17.10.0: Added x and y components.

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

NAMEBG

name of generator file to read

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’.

If NAMEBG is omitted, NAMEPROBbg will be assumed as burn generator filename. This is particularly useful for embedded burn generators.

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

[ VALUEX VALUEY ] VALUEZ

rigidl 1.d52
VALUEX VALUEY VALUEZ

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

This card allows to give the star an angular momentum (units erg*sec) at start-up and distributes it such that the star is rigidly rotating. The rotation value on the grid cards is ignored. Components not specified are assumed to be 0..

New In Version >15.0.0.

Changed In Version 17.10.0: Added 3D components.

rigidv

Set surface rotation velocity of star.

name

parameters

rigidv

[ VALUEX VALUEY ] VALUEZ

rigidv 1.e6
VALUEX VALUEY VALUEZ

equatorial surface rotation velocity of star (units cm/sec)

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

New In Version >15.0.0.

Changed In Version 17.10.0: Added 3D components.

rigidw

Set surface angular velocity of star.

name

parameters

rigidw

[ VALUEX VALUEY ] VALUEZ

rigidw 1.e-6
VALUEX VALUEY VALUEZ

surface angular velocity of star (units rad/sec)

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

New In Version >15.0.0.

Changed In Version 17.10.0: Added 3D components.

rigidk

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

name

parameters

rigidk

[ VALUEX VALUEY ] VALUEZ

rigidk 0.2
VALUEX VALUEY VALUEZ

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 at startup such that the star is rigidly rotating. The rotation value on the grid cards is ignored. Components not specified are assumed to be 0..

New In Version >15.0.0.

Changed In Version 17.10.0: Added 3D components.

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.

nonormb

Do not normalise mapped BURN abundances.

name

parameters

nonormb

nonormb

Note

This is for debugging purposes.

Note

If BURN is not active, this card is ignored.

New In Version 18.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 following lines will be appended to command file until \\ command or end of 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.

//b

The following lines will be appended to BURN generator file until \\ command or end of file.

name

parameters

//b

If genburn has not been called before, this BURN section will be ignored. This allows to just comment out the genburn command and not worrying to remove //b section.

New In Version 17.11.7.

//b*

Same as //b but delete old BURN generator file.

name

parameters

//b*

Note

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

New In Version 17.11.7.

\\

End current command file or BURN generator file section.

name

parameters

\\\\

New In Version 17.0.10.

uuid

Set UUID of generator.

name

parameters

uuid

UUID

This may be used to better track connections between runs and generators used.

uuid 3f856e9e-b45b-11ea-b3f3-2cfda1c73a9c

New In Version 17.11.7.

sha

Set sha hash of generator.

name

parameters

sha

SHA

This may be used to better track connections between runs and generators used.

sha 1ebc0705ced3e43cfbdb219314da7cdf3bc0e6f8

New In Version 17.11.7.

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 | pow | * | - | + | / | % | ^ | **

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. The operators “^” and , “**” do the same things.

parmetercard ::=  "p" listspec | setspec | vallistspec
listspec     ::=  [ parameter [ rangeop parameter ] ] | wildspec
rangeop      ::=  ".."
wildspec     ::=  "*"string | string"*" | "*"string"*"
setspec      ::=  parameter value [ operation ] | parameter simpleop value
vallistspec  ::=  value [ "list" ]
parameter    ::=  name | number
name         ::=  string
number       ::=  integer
value        ::=  float | integer | string
operation    ::=  simpleop | complexop
simpleop     ::=  "*" | "-" | "+" | "/" | "%" | "^"
complexop    ::=  "add" | "mul" | "div" | "sub" | "mod" | "pow"

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.

Changed In Version 18.1.3: Add “^”, “**”, and pow.

Changed In Version 18.7.1: only allow .. for parameter range selection

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.