2. User Interface¶

Note

The NEMO command line user interface is a series of keyword=value pairs, where we differentiate between program keyword and system keyword. The --help or help= options will describe the keywords.

A NEMO program is invoked just as any other application program under the operating system, entering its name from a Unix shell, for example, the program mkplummer can be executing by typing

mkplummer --help

from your terminal shell. We first explain the command line interface to NEMO programs. Subsequently, followed by some of the more advanced concepts of this user interface. We also discuss the overall documentation system in NEMO, and how to get different types of help.

2.1. Keywords¶

2.1.1. Program Keywords¶

Note

The help=h system keyword gives a nice overview of the program keywords. Since it is so common, using –help invokes the default help= showing the program keywords and their defaults.

The most basic user interface is formed by the command line interface. Every NEMO program accepts input through a list of program keywords, constructed as ‘keyword=value’ string pairs on the commandline. We shall go through a few examples and point out a few noteworthy things as we go along. The first example runs an N-body simulation using the program hackcode1 and writes the results in a file r001.dat:

1% hackcode1 out=r001.dat

Hack code: test data

   nbody        freq         eps         tol
     128       32.00      0.0500      1.0000

    options: mass,phase

    tnow       T+U       T/U     nttot     nbavg     ncavg   cputime
   0.000   -0.2943   -0.4940      4363        15        18      0.01

            cm pos   -0.0000   -0.0000   -0.0000
            cm vel    0.0000    0.0000   -0.0000

    particle data written

    tnow       T+U       T/U     nttot     nbavg     ncavg   cputime
   0.031   -0.2940   -0.4938      4397        15        18      0.01

            cm pos    0.0000    0.0000   -0.0000
            cm vel    0.0001    0.0001   -0.0000

    tnow       T+U       T/U     nttot     nbavg     ncavg   cputime
   0.062   -0.2938   -0.4941      4523        16        18      0.02

            cm pos    0.0000    0.0000   -0.0000
            cm vel    0.0002    0.0002    0.0000

    ...

will integrate an (automatically generated) stellar system with 128 particles for 64 time steps. If your CPU is to slow or too fast, abort the program with the usual <control>-C and re-run it with fewer or more particles:

....
<Control>-C
2% hackcode1 out=r001.dat nbody=32 > r001.log
### Fatal error [hackcode1] stropen in hackcode1: file "r001.dat" already exists
3% rm r001.dat
4% hackcode1 out=r001.dat nbody=32 > r001.log

This example already shows a few peculiarities of the NEMO user interface, as shown by the line starting with ###. It is generated by the error routine, which immediately aborts the program with a message to the terminal, even if the normal output was diverted to a log-file, as in this example. The error shows that in general NEMO programs do not allow files to be overwritten, and hence the r001.dat file, which was already (partially) created in the previous run, must be deleted before hackcode1 can be re-run with the same keywords. The datafile, r001.dat, is in a NEMO specific binary format, which we shall discuss in the next chapter.

Now, plotting the first snapshot of the run, i.e. the initial conditions, can be done with the snapplot program

5% snapplot in=r001.dat times=0

It plots an X-Y projection of the initial conditions from the data file r001.dat at time 0.0. Your display will hopefully look something like the one displayed in Figure ???

There are many more keywords to this particular program, but they all have sensible default values and don’t have to be supplied. However, an invocation like

6% snapplot

will generally result in an error message, and shows you the minimum list of keywords which need a value. snapplot will then output something like

Insufficient parameters, try keyword 'help=', otherwise:
Usage: snapplot in=??? ...
plot particle positions from a snapshot file

which already suggests that issuing the help= keyword will list all possible keywords and their associated defaults:

7% snapplot help=

results in something like:

snapplot in=??? times=all xvar=x xlabel= xrange=-2.0:2.0
    yvar=y ylabel= yrange=-2.0:2.0 visib=1 psize=0
    fill_circle=t frame= VERSION=1.3f

As you see, snapplot happens to be a program with quite an extensive parameter list. Also note that help itself is not listed in the above list of program keywords because it is a system keyword (more on these later).

There are a few short-cut in this user interface worth mentioning at this stage. First of all, keywords don’t have to be specified by name, as long as you specify values in the correct order, they will be associated by the appropriate keyword. The order of program keywords can be seen with the keyword help=. The moment you deviate from this order, or leave gaps, all values must be accompanied by their keywords, i.e. in the example

8% snapplot r001.dat 0,2 xrange=-5:5 yrange=-5:5 "visib=i<10"

the second argument 0,2 binds to times=0,2; but if a value "i<10" for visib (the keyword immediately following yrange=) would be needed, the full "visib=i<10" would have to be supplied to the command line, anywhere after the first 0,2 where the keywords are explicitly named. Also note the use of quotes around the visib= keyword, to prevent the UNIX shell from interpreting the < sign for I/O redirection. In this particular case double as well as single quotes would have worked.

There are two other user interface short-cuts worth knowing about. The macro-include or keyword include allows you to prefix an existing filename with the @-symbol, which causes the contents of that file to become the keyword value. In UNIX the following two are nearly equivalent (treatment of multiple lines may cause differences in the subsequent parsing of the keyword value):

 9% program a=@keyfile
10% program a="`cat keyfile`"

Also useful is the reference include, which uses the $-symbol to prefix another program keyword, and causes the contents of that keyword to be included in-place. An obvious warning is in place: you cannot use recursion here. So, for example,

11% program a=$b b=$a          <---- illegal !!!

will probably cause the user interface to run out of memory or return something meaningless. Also, since the $-symbol has special meaning to the UNIX shell, it has to be passed in a special way, for example

12% program a=5 b=3+\$a
13% program a=5 'b=3+$a'

are both equivalent.

2.1.2. System Keywords¶

As just mentioned before, there are a fixed set of keywords to every NEMO program which are the hidden system keywords their values are defined automatically for the user by the user-interface routines from environment variables or, when absent, sensible preset defaults. They handle certain global (system) features and are not listed through the help= keyword. Of course their values can always be overridden by supplying it as a system parameter on the command line. To get an active list of the system keywords, try

tsf help=\?

In summary, the system keywords are:

help= The help= keyword itself, gives you a list of all available keywords to this specific program but can also aid you in command completion and/or explanation of keywords.
debug= The debug= keyword lets you upgrade the debug output level. This may be useful to check proper execution when a program seemingly takes too long to complete, or to trace weird errors. Output is to stderr though. Default level is 0. Some unix tools how to deal with pipes is useful (redir, ….)
error= The error= keyword allows you to override a specified number of fatal error calls. Not adviced really, but it’s there to use in case you really know what you’re doing (bypassing existence of an output file is a very common use). Default is 0.
yapp= The yapp= keyword lets you (re)define the graphics output device. Usually no default.
outkeys= This is a new feature under development, effectively allows exporting information in text strings back to the shell.
review= The review= keyword jumps the user into the REVIEW section before the actual execution of the NEMO program for a last review of the parameters before execution starts. (see also next section).
review= Interrupt mode to review keyword before execution
tcl= Deprecated
np= Number of processors (for OpenMP) to maximally use. Default is max.

For a more detailed description of the system keywords and all their options see aiface. The actual degree of implementation of the system keywords can be site dependent. Use the help=\? argument to any NEMO program to glean into the options the user interface was compiled with. Recent updates can also be found in NEMO’s online manual pages, getparam(3NEMO).

2.2. Advanced User Interfaces¶

The command-line interface, as we described it above, makes it relatively straightforward to plug in any other front-end as a new user interface with possibly a very different look-and-feel. In fact, the command-line interface is the most primitive front-end that we can think of: most host shell interpreters can be used to perform various short-cuts in executing programs. Modern interactive UNIX shells like tcsh and bash can be used very efficiently in this mode. In batch mode shell scripts, if used properly, can provide a very powerful method of running complex simulations. Other plug-compatible interfaces that are available are mirtool and miriad, described in more detail in Appendix~ref{s:mirtool} and ref{s:miriad} There was also a Khoros (cantata, under khoros V1) interface (http://www.khoral.com) available, but this product is not open source anymore. Lastly, lets not forget scripting languages like python, perl and ruby. Although the class UNIX (c)sh shell is very WYSIWYG, with a modest amount of investment the programmability of higher level scripts can give you a very powerful programming environment.

2.2.1. tkrun, qtrun¶

The tkrun program can take directives strategically placed in the comment fields of a shell script, and provide a dynamical GUI frontend to the command line parameters. Since the GUI is built up automatically, the number of keyword should be limited to a dozen or so, as vertical space is limited in most desktop managers.

The qtrun program is an updated version using python and the Qt library.

2.2.2. Interrupt to the REVIEW section¶

Warning

Interrupting to the REVIEW section is not enabled by default, and is likely being deprecated in some future release.

NEMO programs are generally not interactive, they are of the so-called load-and-go type, i.e. at startup all necessary parameters are supplied either through the commandline, or, as will be described later, a keyword file or even a combination thereof. The actual program is then started until it’s all done. There is no feedback possible to the user. This is particularly convenient when combining programs into a script or batch type environments.

There are of course a few exceptions. Certain graphics interfaces require the user to push a button on the keyboard or click the mouse to advance to a next frame or something like that; a few very old NEMO programs may still get their input through user defined routines (they will become obsolete).

2.3. Help¶

The HELP system in NEMO is manyfold, nice but with the obvious danger that things get updated in one place and outdated in another. With that caveat, here are various help options:

Inline help,
The help= system keyword is available for each NEMO program. Since this is compiled into the program, you can copy a program to another system, without all the NEMO system support, and still have a little bit of help. Use help=h to get the keyword descriptions and more vertical space.

The special --help option is allowed for those with gnu fingers.

The special --man option delivers the unix style man page (see next item).
Unix manual pages
for programs, functions, and file formats, all in good old UNIX tradition. All these files live in $NEMO/man and below. Several interfaces to the manual pages are now available:
- man
  the good old UNIX man command (this relies on $MANPATH environment variable) The manpdf script can print out the manual pages in a pretty decent form.
- xman
  The X-windows utility {it xman(1)} provides a point-and-click interface, and also has a decent {it whatis} interface.
- tkman
  The Tcl/Tk X-windows utility tkman formats manual pages on-the-fly and allows hypertextual moving around. and has lots of good options, such as dynamic manipulation of the $MANPATH elements, a history and bookmark mechanism etc.
- gman
  Under GNOME the gman formats tool has nice browsing capabilities.
- html
  The html formatted manual pages. Has some limited form of hypertext, but contains the links to general UNIX manual pages, if properly addressed. Try the github link or local pages
Since manual pages are kept separate from the source code, it is easy to diverge from the “by definition” more up to date inline help. A script checkpar.py can be used to flag where they differ. As of this writing, about 25% of the programs diverge.
The old manual, the The NEMO User and Programmers Guide,
contains information on a wide level, aimed at beginners as well as advanced users, and at is being coverted to this RST manual, outdated.
This manual, in reStructuredText might be available in many different formats. html and pdf are the common ones.

Every NEMO program accepts input through a user supplied parameter list of keyword=value arguments. In addition to these program specific program keywords, there are a number of system wide defined system keywords, known to every NEMO program.

2.4. Program keywords¶

Program keywords are unique to a program, and need to be looked up in the online manual page or by using the help= system keyword (dubbed the inline help). Parsing of values is usually done, though sometimes primitive. Program keywords also have the ability to read the value(s) of a keyword from a file through the keyword=@file construct. This is called the include keyword file, and is very handy for long keyword values, not having to escape shell characters etc. Newlines are replaced by blanks.

2.5. System keywords¶

The ‘hidden’ system keywords, although overridden by any program defined counterpart, can also be set by an equivalent environment variable (in upper case).

help= Sets the help level to a program. As with all system keywords, their value can be fixed for a session by setting the appropriate environment variable in upper case, e.g. expor HELP=5.

By using the keyword form, the value of the environment variable will be ignored.

The individual help levels are numeric and add up to combine functionality, and are hence powers of 2:
- 1 Remembers previous usage of a program, by maintaining a keyword file from program to program. These files are normally stored in the current directory, but can optionally be stored in one common directory if the environment variable {bf NEMODEF}footnote{mirtool also uses this environment variable} is set. The keyword files have the name {{it “progname”}{bf.def}}, {it e.g.} {tt snapshot.def}footnote{This may result in long filenames, Unix SYS5 allows only 14 characters - a different solution is needed here}. When using this lowest help-level it is still possible to use UNIX I/O redirection. This help level reads, as well as writes the keyword file during the program execution; hence the user needs both read and write permission in the keyword directory. As can also be seen, programs cannot run in parallel while using this help-level: they might compete for the same keyword file. Within the simple commandline interface it is not possible to maintain a global keyword database, as is {it e.g.} the case in AIPS; you would have to use the {tt miriad} shell.
- 2 prompts the user for a (new) value for every keyword; it shows the default (old) value on the prompt line, which can then be edited. It is not possible to combine this level with UNIX I/O redirection. By combining the previous helplevel with this one, previous values and modified ones are maintained in a keyword file.
- 4 provides a simple fullscreen menu interface, by having the user edit the keyword file. The environment variable {bf EDITOR} can be used to set any other editor than good old {it vi(1)}. It is not possible to combine this level with UNIX I/O redirection.
- 8,16,... although not processed, higher powers of 2 are reserved for future options
  
  Example: help=3 will remember old keywords in a local keyword file, prompt you with new values, and puts the new values in the keyword file for the next time. The help=5 option happen to be somewhat similar to the way AIIPS and IRAF appear to the user.
  
  Help levels can also include an alpha-string, which generally display the values of the keyword, their default values or their help strings.
- ? lists all these options, as a reminder. It also displays the version index{version, user interface} of the {tt getparam} user interface package.
- h list all the keywords, plus a help string what the keywords does/expects. This is really what we call the inline manual or inline help. index{inline, help} index{manual, inline} index{help, inline}
- a list all arguments in the form {it keyword=value}.
- p,k list parameters (keywords) of all arguments in the form {it keyword}.
- d,v list defaults (values) of all arguments in the form {it value}.
- n add a newline to every {it keyword/value} string on output. In this way a keyword file could be build manually by redirecting this output.
- t output a documentation file according to the %N,%A specifications index{mirtool} of {tt miriad}footnote{Both {tt mirtool} and {tt miriad} need such a doc-file index{doc file, miriad} to lookup keywords and supply help}. Is mainly intended to be used by scripts such as {tt mktool}. The procedure in NEMO to update a {tt .doc} file would be:
```
% program help=t > $NEMODOC/program.doc
```
- q quit, do not start program. Useful when the helpstring contains options to print.
  
  Example: key=val help=1q redefines a keyword in the keywordfile, but does not run the program. This is also a way to ‘repair’ a keyword file, when the program has been updated with new keywords. key=val help=1aq redefines the keyword, shows the results but does still not run the program. Finally, key=val help=1a redefines a keyword, shows the result and then runs the program.
debug= Changes the debug output level. The higher the debug level, the more output can appear on the standard error output device stderr. The default value is either 0 or the value set by the DEBUG environment variable. The use of the debug= keyword will override your default setting. A value of ‘0’ for debug may still show some warning messages. Setting debug to -1 will prevent even those warning/debug messages. Legal values are 0 through 9. Values of DEBUG higher than 9 are not used, or you may get some weird screen output. Values larger than 5 cause an error to coredump, which can then be used with debug utilities like abd(1) and gdb(1).
error= Specifies how many times the fatal error routine can be bypassed. The ERROR environment variable can also be set for this. The default, if neither of them present, is 0.
yapp= Defines the device to which graphics output is send. Currently only interpreted for a limited number of yapp devices. Some yapp devices do not even listen to this keyword. Check yapp(5NEMO) or your local NEMO guru which one is installed. The default device is either 0 or the value set by the YAPP environment variable.
np= Defines the number of processors (e.g. in an OpenMP setting) that can be used. This would override the OMP_NUM_THREADS environment variable, if it was present.
outkeys= TBD
argv= TBD

2.6. YAPP¶

2.6.1. yapp_ps¶

By default NEMO is compile with a very simple PostScript device driver, as specified in yapp_ps. This YAPP interface produces a simple PS (supposedly correctly calibrated to be 20 x 20 cm), and the yapp= keyword value specifies the PS filename.

2.6.2. yapp_pgplot¶

The YAPP interface to the common PGPLOT library is the most used interface, and allows one to select from a variety of graphics output devices without having to recompile the program.

A graphics device in PGPLOT is defined by preceding it with a slash Optional parameters (e.g. filename, X device etc.) can be supplied before the slash. The following list gives an overview of some of the available devices (your list may be a lot shorter (see ?) in list below):

   ?           Get a list of all currently defined graphics devices
   /XTERM     (XTERM Tek terminal emulator)
   /XWINDOW   (X window window@node:display.screen/xw)
   /XSERVE    (A /XWINDOW window that persists for re-use)
Non-interactive file formats:
   /NULL      (Null device, no output)
   /PNG       (Portable Network Graphics file)
   /TPNG      (Portable Network Graphics file - transparent background)
   /PS        (PostScript file, landscape orientation)
   /VPS       (PostScript file, portrait orientation)
   /CPS       (Colour PostScript file, landscape orientation)
   /VCPS      (Colour PostScript file, portrait orientation)
   /EPS       (Encapsulated Postscript, colour)

See also manual pages such as getparam(3NEMO) and yapp(5NEMO)

A special script yapp_query is available for yapp_pgplot in order to provide script writers with a way to select between possibly not implemented device drivers

dev=$(yapp_query png ps gif)
mkplummer - 100 | snapplot -  yapp=fig1.$dev/$dev