2.1.1 Program Keywords

The most basic user interface is formed by the command line interface. Every NEMO program accepts input through a list of so-called 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^2.1:

    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 very slow, abort the program with <control>-C and re-run it with fewer particles:

   ....
   <Control>-C 
   REVIEW called, enter your command:
   REVIEW|hackcode1> quit
   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. First of all, an interrupt might have thrown you into the REVIEW section: the quit command is needed to get you back to the parent shell. This REVIEW section may not have been compiled into your user interface, in which case not to worry. The second peculiarity is shown by the line starting with ``###''. It is generated by the fatal error routine, which immediately^2.2aborts the program with a message to the terminal, even if the normal output was diverted^2.3 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 peculiar binary format, which we shall discuss in the next chapter.

Now, plotting the first snapshot of the run can be done as follows:

    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 .

Figure: Initial conditions for hackcode1

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:^2.4

    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.