6.3. Connecting scripts and your event processors.

6.3.1. Using Tcl variables to communicate with C/C++ code

In our toy example, we need to provde and offset and a slope to calibrate a single parameter. This section will show how to obtain the values of two variables named slope and offset defined in Tcl scripts at the C++ level.

	NOTE
	Before you think hard about extending and generalizing this code for your own use, you might check out the calibrated parameter SpecTcl plugin.

We're going to show two ways to do this. First we'll ask Tcl to return the value of the variables. Second we'll link the variables to C++ variables. The key to all of this are the following classes:

See the reference guides for detailed information about these classes.

Suppose we are writing a new event processor that will compute the calibrated parameter from the raw parameter. We're going to have a class definition for that event processor that looks like this:

#ifndef CALIB_H
#define CALIB_H

#include <EventProcessor.h>
#include <TreeParameter.h>


class Calibrator : public CEventProcessor
{
private:
  CTreeParameter  m_raw;
  CTreeParameter  m_calibrated;
public:
  Calibrator();
  Bool_t operator()(const Address_t pEvent, CEvent& rEvent,
                    CAnalyzer& rAnalyzer, CBufferDecoder& rDecoder);
private:
  double getSlope();                                      
  double getOffset();

};
#endif
                        
                    

If you've gone through the sections on writing event processors, this should be nothing new. We've added:

• Two CTreeParameter member variables. m_raw will is a tree parameter for the raw parameter. m_calibrated is a tree parameter for the calibrated parameter.

• We've added a construtor whose job it will be to create the tree parameters properly.

• We added two private methods, getSlope and getOffset that will insulate our event processing code from the mechanisms of fetching the calibration slope and offset values.

The constructor is pretty simple. Assuming the raw parameter is named raw and is from a 4K ADC e.g. and the calibrated parameter is named calibrated and represents energy in KeV between 0 and 2,000;

#include <config.h>
#include "Calib.h"
...
Calibrator::Calibrator() :
  m_raw("raw", 4096, 0.0, 4095.0, "arbitrary"),
  m_calibrated("calibrated", 4096, 0.0, 2000, "KeV")
{}

                    

Let's look at the event processor. It will be registered in the event processing pipeline after whatever does the raw unpacking and produces the raw parameter. That means that our event processor has access to the raw parameter in the tree parameter rather than having to decode it again from the data:

Bool_t
Calibrator::operator()(const Address_t pEvent, CEvent& rEvent,
                    CAnalyzer& rAnalyzer, CBufferDecoder& rDecoder)
{
  if (m_raw.isValid()) {
    m_calibrated = getSlope() * m_raw + getOffset();
  }
  return kfTRUE;
}

                    

Pretty simple. Note that we can only compute the calibrated parameter if the raw parameter has a value for this event. That's what the if statement checks.

Let's look at the getSlope method.

#include <SpecTcl.h>
#include <TCLInterpreter.h>
#include <TCLVariable.h>
#include <cstdlib>
...
double
Calibrator::getSlope()
{
  SpecTcl* pApi            = SpecTcl::getInstance();  
  CTCLInterpreter* pInterp = pApi->getInterpreter();  

  CTCLVariable slopeVar(pInterp, "slope", kfFALSE);   
  const char*  slopeString = slopeVar.Get();          
  double slope;

  if (slopeString) {
    slope = std::atof(slopeString);                  
  } else {
    slope = 1.0;
  }

  return slope;
}

                    

If you're not familiar with the classes being used some of this might be a bit confusing, so let's pick it apart step by step:

The code for offset is pretty much identical. As an exercise, create a method getDouble and rewrite getSlope and getOffset in terms of it.

double
Calibrator::getOffset()
{
  SpecTcl* pApi            = SpecTcl::getInstance();
  CTCLInterpreter* pInterp = pApi->getInterpreter();

  CTCLVariable offVar(pInterp, "offset", kfFALSE);
  const char*  offString = offVar.Get();
  double offset;

  if (offString) {
    offset = std::atof(offString);
  } else {
    offset = 0.0;
  }

  return slope;
}
                        
                    

The only difference from getSlope is the name of the variable we care about and the default value.

The code shown in these examples is perfectly fine. It will work. It does, however require that for each event with a raw parameter the Tcl interpreter has to give us the variable values and we need to convert those string values into doubles. We can use Variable Linking to speed this up.

Tcl allows us to associate a script variable with a C/C++ variable. When you do this, you specify the underlying type of the variable and Tcl constrains values to valid values for that type. To access the value of a Tcl variable that is linked, you just need to get the value of the local C/C++ variable.

To make all of this work for use we'll:

• Add member variables to the class for the slope and offset.

• Modify the constructor to link member variables to the variable. Note that links are always one-to-one.

• Provide a class destructor to undo the link as storing data to the variable after our class is destroyed is likely to make a segfault happen. Note that this is good practice though in an event processor you probably could get away without it as most event processors exist for the length of the program's run.

• Modify getSlope and getOffset to return the values of the linked variables. While we could reference those variables directly in the operator(), we choose not to so that the method of obtaining the variable values is opaque to that method.

Let's look at the changes to the header:

#ifndef CALIB_H
#define CALIB_H

#include <EventProcessor.h>
#include <TreeParameter.h>


class Calibrator : public CEventProcessor
{
private:
  CTreeParameter  m_raw;                   
  CTreeParameter  m_calibrated;            

  double          m_slope;
  double          m_offset;
public:
  Calibrator();
  virtual ~Calibrator();
  Bool_t operator()(const Address_t pEvent, CEvent& rEvent,
                    CAnalyzer& rAnalyzer, CBufferDecoder& rDecoder);
private:
  double getSlope();
  double getOffset();

};


#endif

                    

The three lines added to the header are emphasized above.

The constructor must be modified to link the variables to the Tcl Variables. Note that the code also ensures there are initial values for the variables that make sense:

Calibrator::Calibrator() :
  m_raw("raw", 4096, 0.0, 4095.0, "arbitrary"),
  m_calibrated("calibrated", 4096, 0.0, 2000, "KeV")
{
  SpecTcl* pApi = SpecTcl::getInstance();
  CTCLInterpreter* pInterp = pApi->getInterpreter(); 

  CTCLVariable slope(pInterp, "slope", kfFALSE);
  m_slope = 1.0;                                     
  slope.Link(&m_slope, TCL_LINK_DOUBLE);         

  CTCLVariable offset(pInterp, "offset", kfFALSE);
  m_offset = 0.0;                                    
  offset.Link(&m_offset, TCL_LINK_DOUBLE);

}

                    

If our event processor is destroyed, referencing the Tcl variables slope and offset will likely cause segmentation faults. We therefore need code to undo the link at destruction time:

Calibrator::~Calibrator()
{
  SpecTcl* pApi = SpecTcl::getInstance();
  CTCLInterpreter* pInterp = pApi->getInterpreter();

  CTCLVariable slope(pInterp, "slope", kfFALSE);
  slope.Unlink();

  CTCLVariable offset(pInterp, "offset", kfFALSE);
  offset.Unlink();

}
                    

Much of this code should be understandable. The Unlink removes any link the variable may have with a C/C++ variable.

By using get getSlope() and getOffset() methods, the operator() method body is unchanged. The two getters, however become significantly simpler:

double
Calibrator::getSlope()
{

  return m_slope;
}

double
Calibrator::getOffset()
{

  return m_offset;
}

                    

No explanation is needed.

6.3.2. Using the Treevariable subsystem

In the previous section, we looked at how to get data from a Tcl variable using the SpecTcl and Tcl++ APIs to both SpecTcl and the Tcl interpreter. We used values stored in Tcl variables to compute a calibrated parameter.

In this section, we will introduce the treevariable subsystem. Daniel Bazin first designed and implemented this system as an extension to SpecTcl. Over time the code migrated into a contributed subsystsem and now, is a fully supported part of SpecTcl.

The idea of tree variables is similar to that of tree parameters. These object provide a hierachical namespace of variables. Each tree parameter can be treated as if it were a double. Tree parameters, in addition to having a value, have units of measure. A tree variable array class allows you to aggregate several tree parameters in to a single object.

Tree parameters are implemented as C/C++ variables that are linked to Tcl variables. In addition to the C/C++ variable they have units of measure.

We will use tree variables to manage a set of calibration parameters. We'll assume we have a treeparameter array of 16 elements that are called raw.0 ... raw.15. Associated with these 16 parameters are two tree variables of calibration constants, one, slopes is a tree variable array of 16 sloops while the other, offsets is a tree variable array of calibration offsets.

Note that by adding a second level of indirection, as with Tree parameters, more than one tree variable can be associated with a single Tcl variable. Thus the mapping of Tcl variables to tree parameters is one to many.

Let's look at a header for the calibrator we've described using tree parameters and tree variables.

#ifndef TREECALIB_H
#define TREECALIB_H
#include <EventProcessor.h>
#include <TreeParameter.h>

class TreeCalibrator : public CEventProcessor
{
private:
  CTreeParameterArray m_raw;
  CTreeParameterArray m_calibrated;
  CTreeVariableArray  m_slope;
  CTreeVariableArray  m_offset;

public:
  TreeCalibrator();
  Bool_t operator()(const Address_t pEvent, CEvent& rEvent,
                    CAnalyzer& rAnalyzer, CBufferDecoder& rDecoder);

};

#endif

                    

In addition to tree parameter arrays with the raw and calibrated parameters, we have tree variable arrays for the calibration values. The constructor must instantiate these properly. We're going to assume again, that the raw parameters come from a 12 bit digitizer of some sort.

Here's the constructor:

^Cfox@charlie:~/test/sample$ cat TreeCalib.cpp
#include <config.h>
#include "TreeCalib.h"

TreeCalibrator::TreeCalibrator() :
  m_raw("raw", 12, 16, 0),
  m_calibrated("calibrated", 12, 16, 0),
  m_slope("slope", 1.0, "KeV/channel", 16, 0),
  m_offset("offset", 0.0, "KeV", 16, 0)
{}

                    

The form of the tree parameter constructor we are using says that the parameters are 12 bits wide (go from 0 through 4095). The tree variable array initializers create 16 slopes initialized to 1.0 and 16 offsets initialized to 0. The parameters will be calibrated in KeV.

Using Tree parameters and tree variables makes the operator() trivial to write:

Bool_t
TreeCalibrator::operator()(const Address_t pEvent, CEvent& rEvent,
                           CAnalyzer& rAnalyzer, CBufferDecoder& rDecoder)
{
  for (int i = 0; i < 16; i++) {
    if (m_raw[i].isValid()) {
      m_calibrated[i] = m_raw[i] * m_slope[i] + m_offset[i];
    }
  }
  return kfTRUE;
}

                    

The really cool thing about tree parameters and tree variables from the programmer's point of view is that they mimic ordinary doubles and that arrays mimic ordinary arrays.

6.3.3. Adding new compiled commands to Tcl

We'll continue to use our calibrated parameter as an example for how to add commands to SpecTcl. We've already seen that using tree parameters and tree variables provides a truly elegant solution.

Going back to our example of a single calibrated parameters: We're going to add a command called setcalib. setcalib accepts two double parameters. The first is the slope and the second the calibration offset.

This example is a bit involved:

• We need an event processor that stores slope and offset and uses them to compute a calibrated parameter. The event processor must also provide a mechanism to set the slope and offset

• We need a CTCLObjectProcessor derived object. CTCLObjectProcessor is a class that wraps Tcl compiled application specific commands. All of SpecTcl's extensions to the Tcl interpreter are implemented as classes derived from CTCLObjectProcessor.

  The class we design and implement must also have a way to modify the slope and offset of the event processor.

• We need to make the event processor and the command known to SpecTcl and Tcl respectively. Included in this are both modifications to the MySpecTclApp.cpp and Makefile files provided by the skeleton.

#ifndef CMDCALIBRATION_H
#define CMDCALIBRATION_H

#include <EventProcessor.h>
#include <TreeParameter.h>

class CmdCalibrator : public CEventProcessor
{
private:
  CTreeParameter m_raw;
  CTreeParameter m_calibrated;
  double         m_slope;
  double         m_offset;
public:
  CmdCalibrator();
  Bool_t operator()(Address_t pEvent, CEvent& rEvent,
                    CAnalyzer& rAnalyzer, CBufferDecoder& rDecoder);

  void setSlope(double slope);
  void setOffset(double offset);
};


#endif

                        

CmdCalibrator::CmdCalibrator() :
  m_raw("raw", 4096, 0.0, 4095.0, "arbitrary"),
  m_calibrated("calibrated", 4096, 0.0, "KeV"),
  m_slope(1.0),
  m_offset(0.0)
{}


                        

Bool_t
CmdCalibrator::operator()(Address_t pEvent, CEvent& rEvent,
                          CAnalyzer& rAnalyzer, CBufferDecoder& rDecoder)
{
  if (m_raw.isValid()) {
    m_calibrated = m_slope * m_raw + m_offset;
  }
}

void CmdCalibrator::setSlope(double slope) {
  m_slope = slope;
}
void CmdCalibrator::setOffset(double offset) {
  m_offset = offset;
};

                        

#ifndef SETCALIBCOMMAND_H
#define SETCLIBCOMMAND_H

#include <TCLObjectProcessor.h>                      
class CmdCalibrator;                                       

class SetCalibCommand : public CTCLObjectProcessor         
{
private:
  CmdCalibrator&   m_eventProcessor;                   

public:
  SetCalibCommand(CTCLInterpreter& interp, CmdCalibrator& evp); 

  int operator()(CTCLInterpreter& interp, std::vector<CTCLObject>& objv); 
};


#endif

                        

#include <config.h>

#include "SetCalibCommand.h"
#include "CmdCalibration.h"                
#include <TCLInterpreter.h>
#include <TCLObject.h>

SetCalibCommand::SetCalibCommand(CTCLInterpreter& interp, CmdCalibrator& evp) :
  CTCLObjectProcessor(interp, "setcalib", true),  
  m_eventProcessor(evp)                           
{}

                        

SetCalibCommand::operator()(CTCLInterpreter& interp, std::vector<CTCLObject>> objv)
{
  int status = TCL_OK;                 

  bindAll(interp, objv);               
  try {
    requireExactly(                    
        objv, 3,
        "setcalib needs only slope and offset params"
    );

    double slope  = objv[1];           
    if (slope == 0.0) {
        throw "Slope equal to zero makes no sense";  
    }
    double offset = objv[2];

    m_eventProcessor.setSlope(slope);   
    m_eventProcessor.setOffset(offset);

  }
  catch (CException& e) {
    interp.setResult(e.ReasonText());
    status = TCL_ERROR;
  }
  catch (std::exception& e) {
    interp.setResult(e.what());
    status = TCL_ERROR;
  }                                     
  catch (std::string msg) {
    interp.setResult(msg);
    status = TCL_ERROR;
  }
  catch (const char* msg) {
    interp.setResult(msg);
    status = TCL_ERROR;
  }
  catch (...) {
    interp.setResult("Unexpected exception type caught executing setcalib");
    status = TCL_ERROR;
  }

  return status;                     

}
                            
                        

#include "CmdCalibration.h"
#include "SetCalibCommand.h"
                        

CmdCalibrator calibration;
void
CMySpecTclApp::CreateAnalysisPipeline(CAnalyzer& rAnalyzer)
{
  RegisterEventProcessor(*(new SimpleEventProcessor), "Test");
  RegisterEventProcessor(calibration, "Calibrator");

}

                        

void
CMySpecTclApp::AddCommands(CTCLInterpreter& rInterp)
{ CTclGrammerApp::AddCommands(rInterp);

  new SetCalibCommand(rInterp, calibration);
}