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 example2.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 immediately2.2aborts the program with a message to the terminal, even if the normal output was diverted2.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 .
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
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
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
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
$-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.