.. _iface: User Interface ============== .. note:: The NEMO command line user interface is a series of *keyword=value* pairs, where we differentiate between :term:`program keyword` and :term:`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 .. code-block:: mkplummer 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. Keywords -------- 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**: .. code-block:: 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 ``-C`` and re-run it with fewer or more particles: .. code-block:: .... -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 .. code-block:: 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 ??? .. % \PSinsert{encounter1.ps}{7.5}{7.5}{0.5}{0.5}{1}{0} 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 .. code-block:: 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 .. code-block:: 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: .. code-block:: 7% snapplot help= results in something like: .. code-block:: 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 .. code-block:: 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): .. code-block:: 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, .. code-block:: 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 .. code-block:: 12% program a=5 b=3+\$a 13% program a=5 'b=3+$a' are both equivalent. .. A third interesting shortcut is something new and introduced in version 3.2, which allows keyword references using the \% symbol to cut accross programs. 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 .. code-block:: 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 :ref:`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)*. 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. 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. 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). 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 <../../../man_html/index.html>`_ 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. .. _aiface: 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. 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. 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: .. code-block:: % 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 YAPP ---- 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. 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): .. code-block:: ? 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 .. code-block:: bash dev=$(yapp_query png ps gif) mkplummer - 100 | snapplot - yapp=fig1.$dev/$dev