Adding a skeleton DMT monitor
Adding a skeleton DMT monitor
Now you should have a working version of the DMT libraries. One of the primary functions of the DMT is to provide an environment in which you can construct monitors. These are programs that analyse incoming data in real time, or from a set of output files, producing output graphs, data streams or files containing derived data products. The DMT distribution contains many examples of monitors in the subdirectory gds/Monitors. Some of these are very useful and are used every day in the control rooms at the LIGO sites. Others are broken. It’s a real mixed bag. However, most of them are complicated in some sense, and if you are getting started it is better to look instead at a very bare bones template that basically does nothing much except coexist with the data. Fortunately, there is a such a template, in the directory gds/DMT/Templates. In this lesson we will learn to add a monitor based on this template to the DMT, recompile the source distribution to include this monitor, and try running it to make sure it works.
Hacking in a new monitor sub directory and copying the template code to it
$ cd ~/gds/Monitors
$ mkdir exmon; cd exmon
$ cp ~/gds/DMT/Templates/DatTemplate.cc .
$ cp ~/gds/DMT/Templates/DatTemplate.hh .
$ cp ~/gds/DMT/Templates/Makefile.am .
$ mv DatTemplate.cc exmon.cc
$ mv DatTemplate.hh exmon.hh
$ ls
exmon.cc exmon.hh Makefile.am
Note that you can save time here by using the upwards arrow in the shell to repeat the previous line of text, then alter the text by the few characters of difference between successive lines.
The last command is just to check that you have the required files with the required names in the
new subdirectory. You should now use your favourite editor to create a file exmon.author
containing a single line of text: Your Name <youremail@shef.ac.uk> . This will make four files
overall in your new monitor directory. Alternatively, since this such a simple file you can create
it from the command line like this:
$ echo “Ed Daw <e.daw@shef.ac.uk>” > exmon.author
Adapting makefile.am
Makefile.am is the input file used by the gnu automake utility to generate a makefile used to build
the monitor. Since ours was lifted from the Templates subdirectory, it contains the necessary
content to build executables for all five of the templates. Firstly, we are only interested in building
exmon, which before we renamed it was called DatTemplate. To fix this, edit line 6 of Makefile.am, removing everything except DatTemplate, and change DatTemplate to exmon. Next, delete the lines below referring to sources except DatTemplate.cc (lines 8 to 11), and line 7 should be altered to exmon_SOURCES=exmon.cc . Also, because we have moved this Makefile.am to a new directory, a few of the relative paths need to be changed. In particular, in the DMT/Templates directory, the path to the DatEnv subdirectory is ../DatEnv, but from the Monitors directory it is ../../DMT/DatEnv.
This needs to be changed on what is now line 49. Finally we are no longer building SvrTemplate,
so the entire contents of lines 53 to 66 inclusive can be removed. After making these changes,
save the modified Makefile.am.
Adapting gds/configure.ac
The file configure.ac in the top directory (directly under gds) is used by the gnu autoconf program
to generate Makefiles in all the subdirectories where code is to be built. Therefore we need to add
our new monitor subdirectory to this file. Open it and go to line 216. You should be most of the
way down a long list of directories, with one entry per line, and a \ character denoting the continuation to the next line. Add a new line Monitors/exmon/Makefile \ being careful not to forget the backslash at the end. Save your changes.
Rebuilding the gnu configure script
You should now be ready to rebuild the gnu configure script. To do this, go to the gds top directory and invoke:
$ rm configure
$ bash -c ‘./configure --prefix=/home/<username>/gds > configure.log 2>&1’ &
$ tail -f configure.log
(you should now be watching the configuration program output).
You will need to ctrl-C out of tail-f once configure appears to have finished. The last line is
config.status: executing depfiles commands
You should also be able to see a line:
config.status: creating Monitors/exmon/Makefile
about 10 lines above the end, which indicates that the Makefile for the new monitor directory has been created.
Modifying the source exmon.cc and exmon.hh
If you type make now, it will not work. We will now strip down DatTemplate.cc, which is become exmon.cc, and ready it for building into a bare bones monitor that does nothing. Then we will start to bolt things to it. First, edit exmon.cc. Here are the lines you have to change. First, line 4 should
be #include “exmon.hh”, and line 5 should be deleted. Line 10 should be altered to reference
exmon.cc rather than DatTemplate.cc, and feel free to change the authorship to your own LSC
username rather than jzweizig. This line is used by the CVS repository in cataloging the code. Line
12 could read #define PIDTITLE “An example monitor”. In referencing future line numbers, I will
assume that you have already deleted the ones I have instructed you to in previous instructions.
Next, change line 22 to EXECDAT(exmon). This is the line that builds the main() routine required to tell the compiler where execution of the program should start. Next, start to fix the naming of the class and the definition of its member functions. Line 26 should define the constructor for a new
exmon class, so change DatTemplate::DatTemplate to exmn::exmon, leaving the rest of the line
the same. Next, we are not going to apply a filter to the data at first, so delete lines 39 and 40 which handle a -filter command line argument. Next, the frame we will test our routine on does
not have an H0:PEM-LVEA_SEISX channel, so change mChannel on line 68 to
mChannel = “H1:LSC-AS_Q”. Finally for the constructor, we will not be defining a DMT viewer, a trender, or a dataviewer index entry, so delete lines 74-98 inclusive. The final brace of the
exmon::exmon constructor definition should now be on line 74. Next, change the name of the
destructor from DatTemplate::~DatTemplate to exmon::~exmon on line 77, and change the
namespace of the ProcessData member function on line 84 from DatTemplate::ProcessData(void)
to exmon::ProcessData(void). Remove most of the ProcessData functionality, including the filter
and the calculation of the channel standard deviation by deleting lines 92-111 inclusive. Lastly
for the ProcessData function, replace the new line 92 with std::cout << “success” << std::endl;
Lastly, alter the namespace of the Attention function on line 98 from DatTemplate::Attention
to exmon::Attention. Don’t forget to save after making these changes!
Next, changes to exmon.cc. Firstly the first two lines should say #ifndef exmon_HH and
#define exmon_HH. These lines are used to ensure that the same header files do not appear twice if exmon.hh is included multiple times in the same source. Second, delete lines 11-52
inclusive - this is documentation that will have to be re-written once our monitor works. The class
declaration should now begin at line 12. Change the class declaration to
class exmon : public DatEnv, MonServer {
In the class declaration, Change the names of the constructor and destructor member functions
on lines 14 and 15 to exmon and ~exmon (keeping the same argument lists). In the private data
members, delete the lines referring to the redundant private data mTrend, mFilter and mPipe.
Finally, change the last non-empty line to #endif // exmon_HH . Save changes. You are now ready
to try making the monitor.
In the exmon directory, type make. If compilation is successful, the last or second last lane should say ‘creating exmon’. If it does, type make install. Once you have done this, you should type which exmon to check that the exmon executable is in your search path. In order to run exmon, you will
need a frame containing the channel H1:LSC-AS_Q.