Writing a SpecTcl Configuration Script

Writing a SpecTcl Configuration Script

The command language of SpecTcl is Tcl/Tk. There is no special configuration file format. Instead, experimenters usually create a SpecTcl script named setup.tcl, and source that script into SpecTcl at startup.

This script usually defines the initial set of parameters and spectra that SpecTcl should know about. While it's also possible to enter gate definitions and gate applications in this script, it's usually easier to enter these graphically and interactively once SpecTcl is running. Once entered, gates can be saved into a script that can be loaded back into SpecTcl later.

For information about the Tcl/Tk scripting language, see either of the books:

• Tcl and the Tk Toolkit Ousterhout, Addison Wesley, ISBN 020163337X
• Practical Programming in Tcl and Tk (3rd Edition) Welch, Prentice Hall PTR, ISBN: 0130220280

A limited number of copies of these books are available from the computer group.

The SpecTcl documentation is an on line set of web pages. You can locate them by pointing your browser at: the NSCL documentation web and clicking on SpecTcl.

Following our running example, we need to provide definitions for our 16 TDC and 16 ADC parameters. We will also create 1-d spectra to monitor each of these channels, and summary spectra that allow us to see all TDC's and all ADC's at a glance for troubleshooting purposes.

Defining Parameters

Parameters make a correspondence between a parameter name and a slot in the parameter array. In the final code for MyEventProcessor.cpp, we assigned the values of 100 and 120 to nADCBase and nTDCBase respectively. This means that the ADC's have been unpacked into slots 100-115 and the TDC's into slots 120-135.

It's possible to write parameter definitions for these as shown below:

parameter adc1 100 12
parameter adc2 101 12
...
parameter adc16 115 12
parameter tdc1 120 12
...
parameter tdc16 135 12

This is a lot of typing however. It's much more efficient to take advantage of the fact that Tcl/Tk is a general purpose scripting langauge. This allows us to reduce the amount of typing required to enter this configuration file without losing clarity. This approach is shown in the annotated example below:

set slot 100                                 [1]
for {set i 1} {$i <= 16} {incr i} {          [2]
   parameter adc$i $slot  12                   [3]
   incr slot
}
set slot 120 
for {set i 1} {$i <= 16} {incr i} {
   parameter tdc$i $slot  12                    [4]
   incr slot
}

In the description of this example, the numbers for each annotation refer to The numbers like [1] in the example.

1. Since the ADC's begin at slot 100, create a variable slot and set its value to 100.
2. Loop over the range [1, 16], assigning the variable i successive values in this range.
3. Using variable substitution, for each pass in the loop create a parameter definition.
4. Do the same thing for the TDCs.

Defining the 1-d Spectra

The SpecTcl spectrum command defines histograms on parameters that have been defined by the parameter command. SpecTcl supports 1-d, 2-d, summary, bitmask, and multiply incremented spectra in 1-d and 2-d (gamma spectra). Each spectrum definition contains the following elements:

The script fragment below makes spectra for each of the ADC and TDC parameters. A loop is used to minimize the typing required:

for {set i 1} {$i <= 16}  {incr i} {
    spectrum adc$i 1 adc$i {{0 4095 2048}}
    spectrum tdc$i  1 tdc$i {{0 4095 2048}}
}

Each spectrum has 2048 channels and covers the full 12 bit range of the digitizer.

Defining the summary spectra

A summary spectrum is a 2-d spectrum with 1-d spectra on the y axis and a parameter id on the x axis. Summary spectra are a convenient and compact way to look at a number of similar parameters from a detector array.

On a summary spectrum it's easy to spot failing channels or channels that are not well gain-matched. We will create a summary spectrum for the ADCs and another for the TDCs. Rather than typing in all of the parameters needed by each summary spectrum, the list is created in the script. First two Tcl lists are created. The first, adcs is the list of ADC parameters. The second tdcs is the list of all TDC parameters. Finally the two spectra are created.

for {set i 1} {$i <= 16} {incr i} {
    lappend adcs adc$i
    lappend tdcs tdc$i
}
spectrum alladcs s $adcs {{0 4095 4096}}
spectrum alltdcs s $tdcs  {{0 4095 4096}}

Making the Spectra Displayable

SpecTcl allows you to create as many spectra and use as much spectrum storage as virtual memory allows. However Xamine, the display program used by SpecTcl, creates a shared memory region that holds all the spectra it knows about. It is therefore limited by the size of this memory region. The SpecTcl user's guide describes how to set the size of this memory region.

In order to allow SpecTcl to hold more spectrum storage than the displayer can display, SpecTcl allows you to move spectra in and out of displayer storage using the commands sbind and unbind. The final command in our setup script is to sbind all of the spectra to the displayer (our storage requirements are small enough that we don't need to swap spectra in and out):

sbind -all

Running SpecTcl

Assuming we have named our setup script setup.tcl and stored it in the same directory as the SpecTcl executable, run SpecTcl as shown below:

The characters in bold are what you type. Everything else is computer generated output.

Writing a SpecTcl Configuration Script