EROS changes July 2003

 

Document version 31-July-2003

 

Jussi Markkanen


Contents

 

  1. The runexperiment command
  2. The testexperiment command
  3. User parameters  (upar)
  4. Support for archiver -- writeexperimentfile
  5. The findfile command
  6. The printdataaccess command  
  7. Eros utility commands check, print and kill
  8. Eros simulation
  9. Eros help
  10. Building EROS-related binaries
  11. Implementation status

 

1.  The runexperiment command


There is new functionality in the runexperiment command, but some features have been taken away, and some have been moved to other commands.

 

1.1 A backstep is that experiments cannot any more be queued. If an experiment is running and you try to start a new one, EROS immediately refuses to accept the new experiment. Queuing has not worked reliably, and has often hanged EROS.

1.2 Another inconvenience is that an explicit starttime is now obligatory in the runexperiment command, as the second parameter:

    runexperiment ElanFile StartTime ?arg arg ...?

If you want to start immediately, use "now" as the time parameter,

    run tau1 now,

and if you want to start at next full minute, use

    run tau1 fullminute.

The purpose of this change is to reduce the risk of bad start times, and also reduce confusion when a variable amount of parameters (the args) is now possible in the run command, see (1.4).

 

1.3 The -test option has been removed from the run command. There is now a separate testexperiment command, see section 2.

 

1.4 It is now possible to feed parameters to the experiment script at experiment start time, using the runexperiment command. All parameters after the second parameter, the starttime, in the runexperiment command are made available to the script via a new EROS command, argv. The argv command returns a list containing those parameters. One possibility to make use of them is to have the following structure in the elan file.

 


BLOCK tau1 { {scan cp1} {owner CP} {height 292.9} } {
      ...
      ...
};#endblock

eval callblock tau1 [argv]


For a complete example, see /kst/eros4/exp/tau1.elan.

Instead of BLOCK tau1, you could also use the standard tcl procedure declaration, proc tau1.  The proc would then be invoked in the normal tcl way,

 

    eval tau1 [argv].

 

The BLOCK/callblock is recommended, for it allows EROS to perform some bookkeeping and cleanup.

Note the use of the tcl
eval command in front of the EROS callblock command when invoking the tau1 BLOCK in the elan file. The eval is necessary if argv returns more than one parameter.

Note also the use of
callblock, not gotoblock, in this kind of context. A callblock command does not affect experiment syncronization, but a gotoblock command has a time parameter that must be taken care off. Gotoblock is normally more useful when used interactively.

The above tau1
BLOCK has default values for all three of its formal parameters. Therefore, it can  be called with zero, one, two or three arguments. For example,

    runexperiment tau1 13:00

 
==> tau1 is called without arguments, and hence uses the default values for all three parameters.

    runexperiment tau1 13:00 cp3


==> tau1 is called with argument cp3, and "owner" and "height" get the default values.

2.  The testexperiment command

 

There is a new testexperiment command. When an experiment is started with the testexperiment command, no data is recorded, and no logbook entries are made. No entries are made to the official EROS log, such as /kst/log/SODlog.log either, but instead, log entries are made to test-log, such as /kst/log/SODtestlog.log.

 

By default, an experiment started using the testexperiment command does not move the antenna, and the EROS messages window says that

    "Antenna access blocked by eros".

 

The syntax of testexperiment command is

    testexperiment ?Options? Elanfile Starttime ?Arg Arg ...?
        Options: -useant
                 -noant (default)
        Ex.1. test tau1 now
        Ex.2. test -useant tau1 10:30 cp3

If you want allow antenna motion during a testexperiment, you must explicitly use the -useant option as in the above Ex.2.

IMPORTANT. When a
testexperiment is active in the default (-noant) mode, also interactive antenna commands, including setting antenna to standby and computer mode, are disabled. Even the automatic setting of antenna to standby by EROS does not work.

When a
testexperiment is running, the printexperiment output looks something like this

 

 

    TEST EXPERIMENT (SOD) 23-Jul-2003 17:04:29.7

    --------------------------------------------
    Exp file    : tau1.elan
        dir     : /work/kst/exp
        state   : RUNNING since 23-Jul 17:03:31.8
               ...

 

 

3.  User parameters  (upar)


A facility similar to the old EROS II IPAR/RPAR has been implemented to get user definable parameters recorded into the parameter block (d_parbl).
   
In current implementation, 20 locations in the d_parbl vector in the data dump are reserved for the user parameters. Each variable is a 8-byte real ("double") value, there are no integer-type user parameters. The variables are kept in the EROS rt-common as doubles, but in the present implementation, are read and written there via a four decimal digit fixed-point string representation. This means that an attempt to set an upar to the value 0.00004 will set it to (exact) zero instead. This implementation may change in the future.

The new eros command to access the upars, either interactively or in an elan file, is upar, see below for usage.

Implementing upar required expanding the rt-common data structure, defined in /kst/dsp/include/kstsys.h. Many programs depending on that header file required recompilations. I have compiled many of them in Sodankyla, but not necessarily all.

The parameterblock version number (d_parbl(40)) was changed from 2.1 to 2.2. Starting from 2.2, Upar(1-20) are available in d_parbl(43-62).

3.1 The EROS command to read current value of a user parameter, directly from the rt-common (the upars are stored in the rt-common so that they will always be up-to-date), is

    upar Index,

where Index is from 1 to MAX_UPAR, which currently is 20.

The Index can also be the keyword "all" to return a list of all MAX_UPAR values, or can be a list of indexes, to return a subset. For example,

    upar 1

returns the value of first upar, upar(1), which is in the parameter block location d_parbl(43), and

    upar { 2 5 }

returns the values of upar(2) and upar(5).

To make use of an upar value in EROS commands, the standard tcl bracket syntax must be used. For example, if upar(2) stores the desired common volume altitude, we can use that value in a pointing command as

    pointrheight 180 70 [upar 2]

3.2 The EROS command to set an upar's value (in the rt-common) is


    upar Index Value

For example, to set upar(2) to 295.6, use the command

    upar 2 295.6

EROS does not explicitly initialize the upars, because it is not clear when such an initialization should be done. It could be that a user wants to preserve upar values from experiment to experiment, say. However, it is possible to use an explicit command like

    upar all -1,

either interactively or in the elan file, to set all upars to a known initial value.

3.3 The upar command syntax allows simple arithmetic to be done in a simpler way compared to the standard tcl math command, expr, using c-language-mimicking operators. For example,

    upar 5 ++       ==> increment upar(5) by one
    upar 5 --       ==> decrement upar(5) by one
    upar 5 += 2.5   ==> increment upar(5) by 2.5
    upar 5 *= 2.5   ==> multiply upar(5) by 2.5

With the standard expr command, the first example would have to be written as

    upar 5 [expr [upar 5] + 1 ]

4.  Support for archiver -- writeexperimentfile


The command

    writeexperimentfile Filelist Directory

copies the files listed in Filelist to the specified Directory. If no Directory is specified, that is, we use

    writeexperimentfile Filelist

the files are copied to a daily subdirectory of the experiment's "information directory", as required by the archiver. The name of the information directory is deduced from the experiment identifier, ExpID, of the current (or last run) experiment. The ExpID is a required parameter of the EROS startdata command. After the startdata command is given, normally in the elan file, EROS knows the ExpID, and can form the information directory name. (EROS uses ExpID also to form the name of the actual data directories.) Therefore, in an elan file, writeexperimentfile Filelist command should come only after the startdata command.

 

        ...

 

    set Expfiles [list \
    $XDIR/tau1.elan $SCAN_FILE \
    $XDIR/tau1-r.tlan $XDIR/tau1-u.tlan $XDIR/tau1-v.tlan \
    $NCO1 $NCO2 $NCO4 $NCO5 $Filter12 $Filter45 \
    $Corrfile ]

        ...

    startdata $Corrfile $Expid $Iper_us
    writeexperimentfile $Expfiles

        ...

 

If the information directory does not exist, EROS attempts to create it, including all necessary higher level directories.

 

Note that in testexperiment mode, the writeexperimentfile shows the names of the directories it would create, but does not actually create them. Nor does it copy any of the files.

 

There are no defaults for the Filelist. All desired files must be specified explicitly, and preferably using absolute path names (there is no guarantee about what is the working directory when the experiment is run).

5.  The findfile command

 

Until we get our experiment directories drastically purged, it could be helpful to be able to use the unix find command to search for stuff. The new findfile EROS command implements a restricted form of find. For example, the EROS command

 

    findfile tau1*.elan

maps to the unix command

    find /kst/exp -name "tau1*.elan" -print

irrespective of what is the current working directory. If some other search root directory than /kst/exp is required, it can be specified explicitly, for example,

    findfile /kst *.fir

uses /kst as the search root directory.

6.  The printdataaccess command

 

There is a new EROS command, printdata, to summarize data access status, with the following output format

 

 

    DATA ACCESS (SOD) 29-Jul-2003 00:52:25.9

    ----------------------------------------
     Data access   : running
     Recording     : enabled
     Corr program  : /kst/exp/tau1/tau1-r.fil
     ExpId         : kst0 tau1r_cp1_1.30_CP
     Integration   : 5.0 s
     Disk          : /data1 (14.415 GB avail)
     Data path     : tau1r_cp1_1.30_CP@sod
     Latest dump   : 20030729_00/18060744.mat
            time   : 29-Jul 00:52:25

 

 

The first field (Data access) can be "running" or "stopped". The second field shows the status of the enablerecording bit as read from the rt-common. This bit is controlled by the disablerecording and enablerecording commands. Correlator program name and the "experiment identifier" string are got via the latest startdata command. The fields Disk, Data path and Latest dump show the file path name components of the latest data dump.

 

7.  Eros utility commands

 

The EROS4 script (normally executed via the Eros command) can do a few other things besides kicking EROS running. These utilities are accessed by the commands

    Eros check
    Eros kill
    Eros printant
    Eros printdata
    Eros printexp

The commands must be given in the main process computer (t4501 etc). The commands might be useful e.g. when the on-duty person logs-on to the site from home and wants to see how EROS is doing.

The command

    Eros check ?LocalRadar?

checks whether the various EROS wishe processes are running. When all processes are found, the output should be similar to the following.

 

 

    eiscat@s2501:/home/eiscat> Eros check

     Checking EROS4 processes in SOD ...
     SOD_MONITOR: running (2)
     SOD_EXPDOER: running (2)
     SOD_EXPRUN: running (2)
     SOD_COMPRO: running (2)
     SOD_ACU in s5011.eiscat.sgo.fi: running (2)

 

 

The command

    Eros kill ?LocalRadar?

can be tried to get rid of a hanging or otherwise misbehaving EROS. You must be logged-in either as root or as the owner of the EROS processes (which is either eiscat or kstdev, but you must know which one) to be able to do the kill.

The print commands

    Eros printXXX ?LocalRadar?

require that EROS is running, and return the same status info as when the commands is given from EROS console.

8.  Eros simulation


The command

    Eros simulate ?RadarName?

starts EROS simulation. The simulation runs entirely on the local computer, no network is needed. The simulation is mainly intended for EROS development, but should also be useful when testing experiment files for syntax errors and general structure, when the official EROS is not available.

Note that in the present implementation only a single simulated EROS can be running on a given computer. That is because the simulation (as well as the real EROS) create an "rt-common" in a fixed location in the memory of the computer which runs the EROS "acu" process. Therefore:

WARNING. Do not run the simulation on the receiver crate computer (which hosts the real rt-common).

It is safe to run the simulation on the main server, even simultaneously with the actual EROS.

I have ported the simulated EROS to Mac OS X also. Those interested can ask me for more details about how to set up the necessary X11/tcl/tk environment.

9.  Eros online help


Eros online help is slightly changed. The EROS command


    help CommandName

now always shows as much help as is available, not only the command's parameter list. I have also updated the help information for several -- but not nearly all -- individual commands. The help command without arguments now also prints out a pointer to the EROS-related web pages in HQ.

10.  Building EROS-related binaries


There is now a master makefile /kst/eros4/Makefile that attempts to build all binaries actually used to run experiments, but not too many of the innumerable test programs and old versions that litter the /kst/bin directory at the moment.


The master makefile invokes recursively five other makefiles. Those makefiles have been slightly reorganized, especially, they all now initially build executables to the source directories only -- a "make install" is required to copy the executables to the kst/bin directory where EROS can see them.


WARNING. The build system has been tested only in Sodankyla. The directory structures even on the mainland sites are slightly different, most especially with regard to the contents of /opt and opt1, and this means that the makefiles will not work at the other sites without modifications.


Also, there are some OS-dependent stuff incorporated in the makefiles, with the purpose of allowing EROS, in simulation mode, to run natively on Mac OS X ("Darwin") also.

 

11. Implementation status

 

The changes described in this document have so far (30-Jul-2003) been implemented only at the Sodankyla site. The changes have been checked in to EISCAT CVS repository, but have not been implemented at the other sites.