7.2 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

This summarizes the parameters of the namelist. Note, however, that the namelists are invoked in the form

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:

• * — stands for any number of characters, including none.
• ? — stands for any single character.
• [<list-of-characters>] — stands for any single character from the list. The list may include ranges, such as a-z, which includes all characters between and including ‘a’ and ‘z’ in the ASCII character table.

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 command (i.e., main input) 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.

Note that this substitution feature is not generally available for input files, though there are some exceptions (e.g., load_parameters). Another convenience for input file organization is the search-path feature, which can be set from the run_setup command. By default, elegant assumes input filenames give the full pathname. If the search path is specified, elegant will instead look for files in one of the listed directories.

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

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

(Note that the quotes are also required.) In this example, betax is assigned the value of the parameter betaxFinal from the file data.twi.

It is also possible to perform calculations using elegant’s built-in RPN calculator. (It is identical to the commandline programs rpn and rpnl supplied with the SDDS toolkit.) To do this in the command file, one must use quotation marks and enclose the expression in parentheses, as in

(Note that this is different from using such expressions in the lattice file; in that case, one doesn’t need the parentheses.) One can not only make such computations, but also use the stack and variables. So, for example, one might use

One can also mix subcommands and RPN expressions, as in

would assign to betax half the value of the parameter betaxFinal from the file data.twi.