TMCALGO V2R1: Algorithm Compiler

3.0: Compiling and Running Algorithms

3.1: .spec File Specification

The .spec file defines how the algorithm is compiled, including what other files must be included. The .spec file is processed by appgen to create a standard Makefile which can in turn be processed by make to compile any or all of an instrument's software.

Algorithm executables have names that end in "algo". Appgen uses the name as one clue in determining what functionality to include. [Other suffixes will work as well, but their use is discouraged unless necessary as such use may break in future versions of appgen. At present, suffixes "disp" and "ext" will work, but certain other suffixes which have special meaning to appgen will not.]

A minimal specification line for an algorithm defines the name of the executable and the source file:

    hsimalgo : hsim.tma

If the algorithm is split into more than one .tma file, they should all be listed in the appropriate order. If the algorithm depends on variables defined in .tmc files (other than those in TMCBASE), those files should also be listed -- before the .tma files.

If you need to compile your algorithm with a version of TMCALGO other than the current default version, you can specify the version at the end of your .spec file after the line consisting of the string '%%':

hsimalgo : hsim.tma
...
%%
...
TMAREV=tmcalgoV2R1
...

What should be obvious as well is that command definitions, specified via CMDBASE, are required in order to compile an algorithm. TMCALGO will launch the command server in order to verify the experiment-specific syntax of commands. Again, it is possible to circumvent this behaviour at a low level, but the point of .tma algorithms is to combine telemetry data with commands.

As always, you must run appgen after editting your .spec file. Thereafter you should be able to issue a 'make' or 'make hsimalgo' to compile your algorithm.

3.2: Interact/Runfile Specification

For most experiments, it makes sense to run the algorithm out of the "flight" script, interact or runfile.*. (but see also dual-node configuration) The recommended command line and options include:

    Launch - hsimalgo -vyl -c0 -C0 -b0 -i1

Launch is a shell function which starts processes in the background and optionally waits for them to register a name. The '-' after Launch indicates that the algo will not be registering a name, so there is no need to wait. 'hsimalgo' is the name of our algorithm.

'-vyl' is a shorthand for the three separate options, '-v', '-y' and '-l':

• -v suppresses diagnostic output to the screen (we'll be sending the diagnostics to the message log).
• -y suppresses msg()'s automatic errno analysis on log messages, which can be helpful, but is often misleading.
• -l requests the first level of debug logging, which includes a message each time a new state is entered. Adding additional '-l' options increases the logging level, logging each command as it is sent to the server, etc.

-c0, -C0 and -b0 tell the algorithm on which node to locate the message logger, the command server and the DRing buffer respectively. '0' means the current node, which is appropriate when running out of a flight script.

-i1 tells the algorithm to ask bfr to deliver one row of data at a time. This is important in realtime processing, since otherwise, the buffer is likely to save up rows of data and deliver them in larger blocks. This would clearly have a detrimental effect on carefully-timed procedures, since the algorithm would be making decisions and issuing commands based on older data.

There are a number of other command line options available to algorithms (and it is even possible to add your own!). You can examine all the options by issuing the command 'use hsimalgo' (replacing hsimalgo with the name of your own algorithm!). We'll use some of them in other configurations.

3.3: Doit Specification

Under certain circumstances, it may be simpler to run the algorithm out of the GSE 'doit' script. This may be true if you wish to switch between two or more algorithms by invoking different doit scripts, for example.

To run an algorithm out of a doit script, we simply add a line to the '.doit' source file:

    algorithm hsimalgo -l

In general, the mkdoit2 compiler will take care of all the standard command line options, including the code required to identify the data acquisition node for the -b and -C options, but you are still in control of the logging level via the '-l' flag.

In laboratory settings this may be reasonable, particularly where the same node is used for GSE and data acquisition. For flight instruments, this approach is strongly discouraged, since it does not exercise the instrument in a flight configuration. A recommended alternative for selecting alternate algorithms is to use the .doit command batchfile to select a different flight script.

Another problem with running the algorithm out of the doit script is that it ties the GSE more closely to the instrument; if you exit from the GSE, the algorithm is terminated; if you start up another GSE on another node, another copy of the algorithm is started and two copies of each command will be issued.

3.4: Dual-node Configuration

The downside to running the algorithm on the flight node is that you don't get all the cool diagnostic information on your GSE data screen. The simple solution to this problem is to run the algorithm in both places: in the flight script to control the instrument and in the doit script to display status information. The critical distinction here is that the copy that runs out of the doit script must not issue any commands. This is accomplished by use of the -p option for 'playback':

    algorithm hsimalgo -p

In addition to suppressing any commands, mkdoit2 will suppress all diagnostic messages from the local algorithm to avoid cluttering the log file with duplicates. (This is done by omitting the -c option on the command line.)

The configuration in the flight script remains the same as specified in Section 3.2.

This approach has some caveats as well. Fundamentally, The local algorithm and the flight algorithm are not guaranteed to be synchronized. This has the following implications:

• If both copies see exactly the same data from the very start of the run, they will track reliably
• If you exit from your GSE and later restart without restarting the instrument, you local algorithm will be out of synch with the flight algorithm.
• If you start up other GSEs after the instrument has been operating for a period of time, the new GSEs will be out of synch with the flight algorithm.
• If your algorithm has 'synchronization points', it is possible to get these latecomers in line, but an algorithm would have to be carefully designed to accomplish this goal.

The effect of de-synchronization is that commands displayed locally will not be the same as the commands which are actually being executed on the flight node. This can lead to considerable confusion if you aren't aware of the possibility. When in doubt, refer to the instrument log file, which records the commands that are actually being executed.

3.5: Playback Configuration

It can be very useful to run an algorithm in playback mode, particularly when trying to diagnose instrument misbehaviour. Specification of the algorithm in a playback .doit file is basically identical to the dual-node configuration except that you will probably want to add a '-ll' option to have the playback algorithm log the commands it would execute if it had control:

    algorithm hsimalgo -p -ll

3.6: Extraction

You can also replay flight algorithms against logged data using extract. As with playback, it is important to pass the '-p' option, and '-ll' is probably required if you hope to get useful information in the log. (Of course you might be running your algorithm for other side effects...)

Note that when specifying command line arguments to an algorithm for extract, you must enclose the algorithm and its arguments in quotes:

    extract 010130.1 "hsimalgo -pll"

Return to Manuals Guide. Written by Norton T. Allen