next up previous
Next: Setup and Action Commands Up: Namelist Command Dictionary Previous: Commandline Syntax

General Command Syntax

Each namelist has a number of variables associated with it, which are used to control details of the run. These variables come in three data types: (1) long, for the C long integer type. (2) double, for the C double-precision floating point type. (3) STRING, for a character string enclosed in double quotation marks. All variables have default values, which are listed on the following pages. STRING variables often have a default value listed as NULL, which means no data; this is quite different from the value ``'', which is a zero-length character string. long variables are often used as logical flags, with a zero value indicating false and a non-zero value indicating true.

On the following pages the reader will find individual descriptions of each of the namelist commands and their variables. Each description contains a sequence of the form

&<namelist-name>
    <variable-type> <variable-name> = <default-value>;
    .
    .
    .
&end
This summarizes the parameters of the namelist. Note, however, that the namelists are invoked in the form
&<namelist-name>
    [<variable-name> = <value> ,]
    [<array-name>[<index>] = <value> [,<value> ...] ,]
        .
        .
        .
&end
The square-brackets enclose an optional component. Not all namelists require variables to be given-the defaults may be sufficient. However, if a variable name is given, it must have a value. Values for STRING variables must be enclosed in double quotation marks. Values for double variables may be in floating-point, exponential, or integer format (exponential format uses the `e' character to introduce the exponent).

Array variables take a list of values, with the first value being placed in the slot indicated by the subscript. As in C, the first slot of the array has subscript 0, not 1. The namelist processor does not check to ensure that one does not put elements into nonexistent slots beyond the end of the array; doing so may cause the processor to hang up or crash.

Wildcards are allowed in a number of places in elegant and the SDDS Toolkit. The wildcard format is very similar to that used in UNIX:

The special characters *, ?, [, and ] are entered literally by preceeding the character by a backslash (e.g., \*).

In many places where a filename is required in an elegant namelist, the user may supply a so-called ``incomplete'' filename. An incomplete filename has the sequence ``%s'' imbedded in it, for which is substituted the ``rootname.'' The rootname is by default the filename (less the extension) of the lattice file. The most common use of this feature is to cause elegant to create names for all output files that share a common filename but differ in their extensions. Post-processing can be greatly simplified by adopting this naming convention, particularly if one consistently uses the same extension for the same type of output. Recommended filename extensions are given in the lists below.

When elegant reads a namelist command, one of its first actions is to print the namelist back to the standard output. This printout includes all the variables in the namelist and their values. Occasionally, the user may see a variable listed in the printout that is not in this manual. These are often obsolete and are retained only for backward compatibility, or else associated with a feature that is not fully supported. Use of such ``undocumented features'' is discouraged.

elegant supports substitution of fields in namelists using the commandline macro option. This permits making runs with altered parameters without editing the input file. Macros inside the input file have one of two forms: <tag> or \$tag. To perform substitution, use the syntax

elegant inputfile|-pipe=in -macro=tag1=value1[,tag2=value2...]
When using this feature, it is important to substitute the value of rootname (in run_setup) so that one can get a new set of output files (assuming use of the suggested ``%s'' field in all the output file names). One may give the macro option any number of times, or combine all substitutions in one option. The name of the input file is available using the macro INPUTFILENAME.

elegant also allows execution of commands in the shell as part of evaluation of a namelist field. To invoke this, one encloses the commandline string in curly braces. E.g.,

betax = "{sdds2stream -parameter=betaxFinal data.twi}"
(Note that the quotes are also required.) In this example, betax is assigned the value of the parameter betaxFinal from the file data.twi. Frequently, the commandline RPN calculator, rpnl is also used in this way, for example
betax = "{rpnl 8 pi / 2 /}"
assigns the value $8/(2 \pi)$ to betax. One possible pitfall with using rpnl in this fashion is interpretation of the multiplication symbol (*) as a file wildcard by the shell. For this reason, the alternate multiplication operator mult is preferred, e.g.,
betax = "{rpnl 8 pi mult}"
rather than
betax = "{rpnl 8 pi *}"

We used the program rpnl in these examples because it is perhaps familiar. However, versions 17.4 and later allow direct evaluation of RPN expressions in commands whenever parentheses are used to delimite a sequence. For example,

betax = "(8 2 / pi /)"
(Note that the quotes are also required.) The advantages of this method are speed (no subprocess is needed), lack of intermediate interpretation by the shell, and persistence of the stack and variables. So, for example, one might use
betax = "(8 2 / pi / sto betax0)"
betay = "(betax0)"
Another advantage is the ability to mix subcommands and rpn expressions, as in
betax = "({sdds2stream -parameter=betaxFinal data.twi} 2 /)"
would assign to betax half the value of the parameter betaxFinal from the file data.twi.


next up previous
Next: Setup and Action Commands Up: Namelist Command Dictionary Previous: Commandline Syntax
Robert Soliday 2014-06-26