Command Files¶

Command files are checked for execution at the beginning of each cycle. KEPLER searches for cmd files in the current directory. First it checks for a file named nameprob.cmd. Is that file not found, KEPLER checks for a file named cmd. This latter can lead to conflicts if more than one instance of KEPLER is running in the same directory and they compete for reading the file.

New Commad File Syntax¶

Changed In Version 17.0.2: the cmd package was rewritten from scratch, including addition of Used-Defind Optional (‘O’) Parameters.

Supported command file-specific commands¶

# OPTIONS

Options/flags/directives to the command file interpreter.

The debug flag allows debugging of expression interpretation.
# debug
New In Version 17.0.2.
The nodebug flag switches debugging off (default).
# nodebug
New In Version 17.0.12.
The noecho flag disables printout of expression tests to console.
# noecho
New In Version 17.0.12.
The echo flag enables printout of expression tests to console (possibly misguided default).
# echo
New In Version 17.0.12.
The xsave flag enables saving of command file before each command execution. This is to prevent loss of changes to command file in case KEPLER terminates during execution, e.g., for a end command.
# xsave
New In Version 17.0.13.
The noxsave flag disables saving of command file before each command execution. This save a lot of write operations, however, changes to command file may be lost in case KEPLER terminates during execution, e.g., for a end command.
# noxsave
New In Version 17.0.13.
The end flag end KEPLER in a save way, also saving the command file properly before termination.
# end
New In Version 17.0.13.
The delete directive deletes the command file and terminates its execution.
# delete
New In Version 17.0.13.
The delsec directive deletes the current section and skips to the next section.
*
: tn(1) > 1.d8
p 1 1.
@ dn(1) > 1.d6
# delsec
New In Version 17.0.13.

* [ NAME ]

Alternate entry point.

Command file execution is also started/tested at these points. Named entry points are only executed using the cmd_call subroutine (currently used for all standard aliases), or can be accessed using the ! command
*
* bounce
Changed In Version 17.0.2: added NAME option

Changed In Version 17.3.1: called for standard aliases.

! NAME

execute the named entry point
@ un(1) > 0.
! bounce
New In Version 17.0.2.

!!

return from entry point (if applicable)
* bounce
p 1 1.
!!
New In Version 17.0.12.

< NAME

Jump target, ignored otherwise.
< home
New In Version 17.0.2.

> NAME [ EXPRESSION ]

Jump to jump target labelled NAME. If the optional argument EXPRESSION is specified, the jump is only executed if the expression evaluates to TRUE.
@ tn(1) > 1.d9
> home
A loop example:
:
o i 0 def
< yyy
> xxx i>10
o i {i + 1}
z en {i}
>yyy
<xxx
end
New In Version 17.0.2.

Changed In Version 17.0.12: Added jump condition.

;

All lines until next entry point are ignored.
*
p 1 1.
;
p 1 2.
*
@ tn(1) > 1.d7
p 13 .1

>

Jump back to origin of previous labelled.
:
< ttest
> home tn(1) > 1.d9
>
< home
p 1 1.
>
New In Version 17.0.13.

>>

Skip rest of section.
:
c example of coding if/then/else
c
> home tn(1) > 1.d9
p 1 2. *
>>
< home
p 1 2. /
If executing external call to alternate entry point, just return, identical to the !! directive.

New In Version 17.0.13.

>>>

Terminate execution of command file.
>>>
If executing external call to alternate entry point, just return, identical to the !! directive.

New In Version 17.0.13.

@ [ EXPRESSION ]

If EXPRESSION evaluates to TRUE, the @ command is removed and the subsequent command are executed and removed until the next @, :, ;, or * command. An empty expression is interpreted as TRUE, allowing to specify sections to be executed only once.
@ tn(0) > 1.d4
p xmlossn 1.
*
:
> lowt tn(1) < 1.d9
p 13 0.
p 69 0.
@
zerotime
>>
< lowt
p 13 .1
p 69 {pn(0) * 0.5}
Changed In Version 17.0.13: Make expression optional.

: [ EXPRESSION ]

If EXPRESSION evaluates to TRUE, the commands following up to the next @, :, ;, or * command are executed but not removed. An empty expression is interpreted as TRUE, allowing to specify sections to be executed repeatedly.
: ncyc % 100 == 0
d xxx#{ncyc}

Variable Replacement in Commands¶

All other commands are processed by ttycom as regular input. Prior to passing the command to ttycom, however, and strings enclosed in curly braces, { and }, are arithmetically interpreted similar to the @ and : commands. The result is converted to a string of same type (integer or float) and passed to ttycom. One extra variable name allowed here is nameprob which is replaced by the current problem name.

One-Time and Persistent Commands¶

All executed commands not in sections lead by :, including @ commands that match, until the next entry point (*) or comment section (;), are removed from the command file and the revised version is written back to disk. Entry points, (*) and section comments (;) remain unless they mark empty sections.

Arithmetic Expressions¶

In arithmetic expressions integer and float numbers can be used. Arithmetic operations permitted are +, -, * , / , % (modulo), ** or ^ (power), and brackets, ( and ), however, the operands must be of same type (integer or float).

Additionally, the abs, log (logarithm base 10), ln (logarithm base $e$ ), exp, sqrt, sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh, erf, erfc, and erfcs (erfc_scaled), function have been defined.

The type conversion functions aint (truncate to integer - returns float), int (truncate to integer - returns integer), nint (nearest integer - returns integer), floor (nearest integer below - returns integer), ceil (nearest integer above - returns integer), and real (returns float) are defined as well.

Changed In Version 17.0.12.

Command Expressions¶

Command expressions consist of a logical expression that use the comparison operators >, <, >=, <=, ==, and = (same as ==) to compare arithmetic expressions. More complex expression can be composed using &, |, and brackets, ( and ).

Special Variables¶

Special variables are cpu_time which returns the CPU time used since start of the executable, and timeused which returns the CPU time since start of the problems, both as float and in sec.

Kepler Variables¶

A selection of KEPLER variables can also be used, including p and q parameters (by name or number), and user-defined optional o parameters. Also allowed are any zonal variables accessible through loadbuf where zone number or mass coordinate can be used similar to the z interactive command.

One can also use a small selection of array functions named after the FORTRAN functions on loadbuf quantities and specify ranges using the : (colon) syntax where omitted first and last indices stand for 1 and jm (q 2) respectively.

function	type	description
sum	float	sum up values
maxval	float	maximum value
minval	float	minimum value
maxloc	integer	index of maximum
minloc	integer	index of minimum

To obtain location of variable values in loadbuf arrays, the following functions can be used. No range specification is allowed in this case.

function	type	description
locl	integer	lower zone number
loc	integer	closest zone number
loch	integer	higher zone number
locx	float	linear interpolated floating zone number

@loc(rn,1.d12) > 1000
@loc rn 1.d12  > 1000

Note

Dissection of the expression fails with variable names that contain operators, e.g., for some reaction rates. In this case, square brackets, [ and ] can be used to keep these together.

@ [o16+o16](1) > 1.d10
d xxx#oign

Changed In Version 17.0.13.

Examples¶

# debug
:
o i 1 def
: (dn(.0) > 0. | (dn(i+1) < 1.e+10))
z dn 1
o i 1 +
p { i + 1 } {p i} +
c {abs (- i)}
c {10.^3}
>xxx
o i del
*
:0>1
<xxx
p 1
d {nameprob}#{i}

# debug
p vinstopm 2.
@ zm(minloc(un(:vinstopm))) < 3.d33
d {nameprob}#mysn
end

Warning

Currently, when a command like end that terminates KEPLER is executed, the modified command file is not saved back to disk before the program ends. The file is only written back when command execution comes to a normal end.

Old Command Files¶

Note

Prior to version 17.00.02 the command file was based on a library that was developed for the STERN code. Only a limited set of cmd-files command was supported, including

the @ command for
- cycle (integer, ncyc (q 4))
- ttcc (float, tstop (p 15) $-$ time (p 2))
- timesec (float, time (p 2))
- un(1) (float, un $($ 1 $)$ )
- un(jm) (float, un $($ jm (q 2) $)$ )
- tn(1) (float, tn $($ 1 $)$ )
- dn(1) (float, tn $($ 1 $)$ )
- T_eff (float, teff (q 48))
- R_eff (float, radius (q 47))
- totm (float, totm (q 17))
- xm(jm) (float, xm $($ jm (q 2) $)$ )
- jm (float, jm (q 2))
- dtnew (float, dtnew (p 1))
Allowed comparison operators are >, <, >=, <=, and == (following FORTRAN standard). No spaces are allowed.
% for comments (line ignored)
* alternate entry point
; all lines after this are ignored up to the next entry point

All other commands are processed by ttycom as regular input.

Example:

@un(1)<=1.d+6
d xxx#infall
exit
*
@dn(1)>=1.d10
d xxx#d10
exit

All executed commands, including @ commands that match, are removed from the command file and the revised version is written back to disk. Entry points, (*) and section comments (;) remain unless they make empty sections.

New In Version >15.0.0.

Deprecated Since Version 17.0.2: Replaced with New Syntax