Chapter 1 Introduction

What is Rustogramer

Rustogramer is a histograming application written in the Rust programming language.

The Rust programing language is a language that is optimized for reliable programing. By this I mean:

• It is very hard to generate memory leaks in Rust programs.
• Threading is layered on the language in a way that makes many of the issues normally associated with threading (race conditions, deadlocks) very difficult.

The support for reliable programing in Rust makes it a good choice for mission critical software at the FRIB.

Rustogramer is written as a closed program. Unlike NSCLSpecTcl, for example, you don't have to and are not allowed to write user code sections to make a version of Rustogramer suitable for use. This is good because:

• Most SpecTcl ``bugs'' are actually errors in user code.
• You won't have to learn Rust to use Rustogramer.

Other interesting features of Rustogramer:

• It is portable between Linux and Windows. It may well run on OS-X but we don't test/debug on that system so no assurances. With the FRIB standard desktop a Windows system, this means you can extend you data analysis to the power of your desktop system.
• It is noninteractive. This allows you to run it in the background, only interacting with it as desired.
• It is compatible with the CutiePie visualizer see FRIB docs on CutiePie
• It provides a REST-like interface that allows you to interact with it either through the provided Python GUI or with any GUI you might write in Python or Tcl. Since REST protocols are inherently stateless, you can start or stop any number of GUIs at any time.

How to use this book

How you use this book depends on how you are going to use Rustogramer.

• If you need to create data sets that Rustogramer can use you need to read Insert link to preparing data here.
• If you are going to use Rustogramer to analyze existing data sets, you'll need to look at:
  • Link to running rustogramer
  • Link to interacting with rustogramer via GUI here
  • and link to CutiePie here.
  • Link to command line options referenc here
• If you want to write, or modify rustogramer GUIs you'll want to look at:
  • Tcl clients: Rest interfaces for Tcl
  • Python clients: Rest interfaces for Python
  • Some other language: REST Requests/responses

If Rustogramer is not installed on your system, you or your system manager, depending on your environment will need to look at Installing

If you're interested in how Rutogramer works, or are interested in contributing to it in some way, you'll need to know How to look at the rustogramer internals.

Preparing data for Rustogramer

How Rustogramer differs from SpecTcl

The material in this chapter describes how to prepare a data set for Rustogramer. This differs a bit from what you are used to if you came to Rustogramer from NSCLSpecTcl.

In NSCLSpecTcl, analyzing a data set required that you prepare a data analysis pipeline that you then used to create a customized version of NSCLSpecTcl.

The event processing pipeline then ran each time you processed an event file to turn the raw event data into a set of parameters that could then be histogramed. If you had an error in your event processing pipeline, your modified SpecTcl could crash. Furthermore, if you had to analyze an event file more than once, you would do this decode each time you analyzed that event file.

Rustogramer expects the processing that was done by the NSCLSpecTcl event processing pipeline to be done by an external program that only runs once on each event file. While you can do this processing any way you want; we recommend you use the FRIB analysis pipeline as described here to create the processed event data files expected by Rustogramer (as a side note, beginning with version 5.13, NSCLSpecTcl can also take these files as input and bypass the event processing pipeline to go straight to histograming).

The FRIB analysis pipeline supports:

• Paralelizing the decoding of events.
• Taking input from a previous pass and extending the data (e.g. with computed parameters) to produce another data-set.
• By combining these two mechanisms, you can compute that which can be parallelized in one process, which is run parallelized, and those which cannot (e.g. cross event computations) in another which is not parallelized.

The FRIB analysis pipeline

This document describes how to use the FRIB analysis pipeline to create data sets for Rustogramer. Refer, as needed to full documentation of the FRIB Analysis Pipeline.

This section will walk through a simple example that uses the FRIB event processing pipeline (from now on called the pipeline for brevity) to decode some data from a fixed format event.

The key point is that the pipeline processes raw events from some file (e.g. event data acquired at the FRIB) to a simple self-describing data set that Rustogramr can understand without any further processing. In the next section, we'll describe the format of the data expected by Rustogramer so that, if you want, you can use whatever other method you want to prepare your data.

Our example is going to show how to take event data which are stored in fixed length, fixed format events and use the pipeline to produce a rustogramer data-set.

The payload of the ringbuffer for each event will consist of something that looks like:

+----------------------+
| Value of parameter 1 | (32 bits)
+----------------------+
| Value of parameter 2 | (32 bits)
+----------------------+
| Value of parameter 3 | (32 bits)
+----------------------+
| Value of parameter 4 | (32 bits)
+----------------------+

Note that while the raw data contains 32 bit integer parameters; The file we generate will consist of double precision floating point values. This accomodates computed parameters that are not integral.

The steps we need to follow are to:

• Prepare a paramter definition file for the output stage of the pipeline
• Write a worker and main for an events -> parameters pipeline.
• Build a Makefile to build the program.
• Run our application.

For a more general and detailed look at this process, see the documentation on Raw parameters to parmaeters in the FRIB analysis pipeline documentation.

Preparing the parameter definition file

The purpose of the parameter definition file is to attach names to data we unpack from the raw event data. Rustogramer will allow you to refer to those names when constructing Spectra and conditions (conditions are what NSCLSpecTcl calls gates).

In our case, the data are array like so we're going to make an logical array of four parameters named; parameters.0 - parameters.3

Let's make a file defintions.tcl and write the following in it:

treeparameterarray parameters 0 4096 4096 arbitrary 4 0

The file is interpreted by a Tcl interpreter with some extended commands. See the description of this file for a detailed description of these extended commands.

For the purpose of this example, we just need to know that the treeparamterarray command creates an array of parameters named as we described above. The additional command line paramters provide, in order:

• A base name for the generated parameters.
• The suggested low limit for histogram axes on these parameters.
• The suggested high limit for histogram axes on this parmaeter.
• Suggested number of bins for histogram axes on these parameters
• Metadata descdribing the units of measure for these parameters.
• The number of parameters in the array.
• The base index of the array. Had we specified 1,instead of 0, the parameters produced would be named parameters.1 - parameters.4

Writing the Code

Recall that we need to write both a worker class and a main for the application.

The worker class

The worker class will be given events to decode. When you run the program you can determine how many workers will be run in parallel (between 1 and many). Each worker runs in a separate processs. There is some resemblance between the worker class and the NSCLSpecTcl event analysis pipeline. This is no coincidence.

If you alread have an event processing pipeline from NSCLSpecTcl, you might want to look at SpecTcl compatibility software in the FRIB pipeline documentation.

We're going to ignore that. Workers that decode raw event data are derived from the frib::analysis::CMPIRawToParametersWorkerclass. Our worker has to construct in a way that it can bind some of its data to the parameters defined in the previous section. We then must override unpackData which actually unpacks a raw event into the parameters.

We're going to assume that the input data are NSCLDAQ-11 ring items. We're also going to assume that each ring item has a body header. The pipeline ensures that unpackData only receives PHYSICS_EVENT ring items, the ring items that contain raw event data.

MyWorker.h

Our header looks like this:

#include <MPIRawToParametersWorker.h>
#include <AnalysisRingItems.h>               // 1
#include <CTreeParamteerArray.h>
#include <cstdint>
using namespace frib::analysis;               // 2
ckass AbstractApplication;
class MyWorker : public CMPIRawToParametersWorker {
private:
    CTreeParameterArray*  m_pParams;         // 3
public:
    MyWorker(AbstractApplication& app) :
        CMPIRawToParameterWorker(app),
        m_pParams(new CTreeParameterArray("parameters", 4, 0)) {} // 4
    ~MyWorker() {
        delete m_pParams;
    }
    void unpackData(const void* pData);
};

The numbered comments refer to the points below:

1. The AnalysisRingItems.h header defines the shape of ring items as well as the types of the new ring items the pipeline creates in the output file.
2. All of the pipeline names are encapsulated in the frib::analsyis namespace. For simplicity we bring those names into the file namespace. In a more complex application you might want to defer this action to the implementation of this class.
3. The CTreeParameterArray class represents a binding between an array like object (implements indexing) of real number like objects and names. We'll bind this to the names of the paramters we made in our parameter definition file
4. The constructor simply initializes the m_pParams member data to point to a tree parameter array object that has the same base name we used in the treeparameterarray command in our parameter definition file. This is all that's needed to bind this to those parameters. Note that bindings to parameters are many-to-one; that is you can bind more than one variable to the same name. This can be convenient when you compose your worker class with components objects.

The destructor simply deletes the parameter binding variable. We also declare the unpackData method which we'll implement in a separate file.

MyWorker.cpp

This file contains the actual code for unpackData. What it has to do is:

1. Find the body header of the ring item.
2. Skip the body header (or lack of one) if it exists.
3. Unpack sequential uint32_t values from the ring item payload into m_pParams.

Here's one possible implementation:

#include <MyWorker.h>
void MyWorker::unpackData(const void* pData) {
    union {
        const RingItemHeader* u_pHeader;
        const std::uint8_t*   u_pBytes;
        const std::uint32_t*   u_pLongs;
    } p;
    p.u_pBytes = static_cast::<const std::uint8_t*>(pData); // 1
    p.u_pHeader++;                                          // 2
    std::uint32_t bodyHeaderSize = *(p.u_pLongs);
    if (bodyHeaderSize == 0) {
        bodyHeaderSize = sizeof(std::uint32_t);            // 3
    }
    p.u_pBytes += bodyHeaderSIze;                          // 4

    CTreeParameterArray& rParams(*m_pParams);
    for (int i = 0; i < 4; i++ ) {
        rParams[i] = *(p.u_pLongs);                       // 5
        p.u_pLongs++;
    }


}

The numbers in the list below refer to the numbered comments in the code sample above:

1. This initializes the union p to point to the raw data that was passed in. We use a union because there are times when it's conveniion to refer to the data using all of the pointer types in the union and this is simpler than doing casts every time we need to use a different type of pointer.
2. Here's an example of what I meant in 1. above. This allows us to skip over the ring item header simply by incrementing the u_pHeader element of the union p.
3. Since all elements of the union occupy the same storage, the u_pLongs element points to the size of the body header. In NSCLDAQ-11, this size is 0 if there is no body header. In NSCLDAQ-12 or greater it is the size of a std::uint32_t. By the end of this block of code, bodyHeaderSize contains either the sizes of the body header or sizeof(std::uint32_t).
4. Now, since we want to skip forwards bodyHeaderSize bytes, it's convenient to increment p.u_pBYtes to skip over either a body header or, if one is not present, the longword that indicates that.
5. Now that the union is pointing at the body of the event, we just need to sequentially unpack the four std::uint32_t values into consecutive elements of the CTreeParameterArray that m_pParams points to. Initializing the reference rParams makes this notationally simple.

A production version of this may be a bit more complex. Specifically, it's probably a good idea to ensure that the total size of the ring item passed in is not smaller than the amount of data we reference.

The main program

The pipeline program we are writing consists of several processes:

1. A dealer process is responsible for reading the raw event file and passing events to workers (there is one of these).
2. As many workers as you desire are responsible for executing the unpacking code and generating parameters from events. These run in parallel. Since MPI runs them in separate processes, you don't have to worry about writing workers to be thread-safe.
3. A farmer process collects data from the workers and re-orders the events back to the order in which they were read from the event file. There is only one of these.
4. The Outputter outputs data sorted by the farmer to the output file.

With the exception of the worker, there are pre-written classes for each of these. The main program, must, therefore:

1. Create an application class that is derived from frib::analysis::AbstractApplication
2. Instantiate that application,
3. Create an object to read the parameter definition script (a frib::analysis::CTCLParameterREader).
4. Start up all of the processes that make up the application passing them the reader.

Note that you use miprun to run the application and specify the total number of processes it should run using the -n option. You are required to specify a minimum of 4 for n, that will create one of each type of process. Larger values for -n will create more worker processes to run in parallel.

mpirun passes all parameters it does not understand back to the application in the usual argc, argv variables. For our application these are:

• argv[0] - the program path as passed to mpirun.
• argv[1] - the name of the raw event file to process.
• argv[2] - the name of the file to generate. These files will be referred to as parameter files
• argv[3] - The path to the Tcl parameter definition file.

Here is a very simple main program that does all of those things:

#include <AbstractApplication.h>
#include <MPIRawReader.h>
#include <MPIParameterOutputter.h>
#include <MPIParameterFarmer.h>
#include "MyWorker.h"  
#include <stdlib.h>
#include <iostream>

using namespace frib::analysis;

class MyApp : public AbstractApplication {                                   // 1 
public:
    MyApp(int argc, char** argv);                                            // 2
    virtual void dealer(int argc, char** argv, AbstractApplication* pApp);   // 3
    virtual void farmer(int argc, char** argv, AbstractApplication* pApp);   // 4
    virtual void outputter(int argc, char** argv, AbstractApplication* pApp); // 5
    virtual void worker(int argc, char** argv, AbstractApplication* pApp); // 6
};
void
MyApp::dealer(int argc, char** argv, AbstractApplication* pApp) {
    MPIRawReader dealer(argc, argv, pApp);                         // 7
    dealer();                                              
}
void
MyApp::farmer(int argc, char** argv, AbstractApplication* pApp) {
    CMPIParameterFarmer farmer(argc, argv, *pApp);                // 8
    farmer();                                            
}
void
MyApp::outputter(int argc, char** argv, AbstractApplication* pApp) {
    CMPIParameterOutput outputter(argc, argv, pApp);           // 9
    outputter();                                       
}
void
MyApp::worker(int argc, char** argv, AbstractApplication* pApp) {
    MyWorker worker(*pApp);                                  // 10
    worker(argc, argv);                              
}


int main(int argc, char** argv) {                            // 11
    if (argc <   4) {                                        // 12
        std::cerr <<
            "Usage: mpirun <mpirun-parameters> program-name infile outfile paramdef-file\n";
        exit(EXIT_FAILURE);
    }
    MyApp app(argc, argv);                                 // 13
    CTCLParameterReader reader(argv[3]);                   // 14
    app(reader);                                           // 15
    exit(EXIT_SUCCESS);                                    // 16
}

Refer to the numbered comments above when reading the list of descriptions below

1. This section of code defines the MyApp class. This class ties together the entire pipeline and must be derived from frib::analysis::AbstractApplication (note we've pulled in the frib::analysis namespace just above this line).
2. The Constructor should contain initialization that is done prior to the startup of the parallel application. Normally the only thing the constructor does (in the base class) is store the arguments.
3. When the application is started up in MPI, an instance of MyApp will be created in each of the processes that make up the application. The base class will figure out if its instance is the correct one in which to run the dealer process and, if so, invoke this method
4. Similarly this method will be invoked in the farmer process
5. ...and this one in the outputter process.
6. Finally the worker method is invoked in each of the work er processes.
7. The implementation of the dealer process simply instantiates an MPIRawReader and runs it by invoking its operator(). Raw readers are appropriate for any type of ring item file. Note that parameter files are also composed of ring items so you can use this reader if you are writing a parameter file to parameter file pipeline. The only difference, in that case, is that the worker class must be derived from the base class CMPIParametersToParametersWorker which will select parameter items and fill any parameters (CTreeParameter or CTreeParameterArray elements) from those events.
8. The farmer just instantiates a CMPIParameterFarmer and runs it.
9. The outputter instantiates a CMPIParameterrOutput object which knows how to write parameter files and runs it. If you know how, you can create an outputter that writes data in some other format.
10. The worker, method is called in each worker process. We instantiate the custom worker that we wrote in the The worker class section above.
11. The next bit of business is writing the main function. It is important to note that main is run in each of the proceses that make up the MPI applications.
12. We need four parameters, as described above. If we don't getting, we describe how we really should be run. Note that this will be output for each of the processes. If you only want one of them to output this, you can also conditionalize on the rank of the process being 0 (see MPI_Comm_rank)
13. Next an application object is instantiated. When the operator() of this is called analysis will start.
14. Some ranks will need to know about the parameter definitions we put in our parameter definition file (since each process has a separate process address space our CTreeParameter and CTreeParameterArrays created in our worker class are not known to e.g. the outputter which needs them).
15. Runs the application and, as each process complete....
16. exit is called to exit the application.

Writing the Makefile.

Writing the Makefile will require that you

• Know where the FRIB analysis pipeline is installed.
• Where the version of MPI it used is installed.

At the FRIB, frib-analysis pipeline versions are installed in containers at /usr/opt/frib-analysis with versious version numbers below that top level directory.

Mpi at the FRIB is installed in various versions under various versions in /usr/opt/mpi. For example OpenMpi version 4.0.1, if installed is in /usr/opt/mpi/openmpi-4.0.1

Naturally, if you depend on any other software component's you'll need to know how to compile and link against them.

FRIB_ANALYSIS=/usr/opt/frib-analysis/1.0-000
MPI=/usr/opt/mpi/openmpi-4.0.1

CXXFLAGS=-I$(FRIB_ANALYSIS)/include -I$(MPI)/include
FRIB_ANALYSIS_LDFLAGS=-L$(FRIB_ANALYSIS)/lib -Wl,-rpath=$(FRIB_ANALYSIS)/lib \
    -lSpecTclFramework -lfribore -ltclPlus -lException

MPI_LDFLAGS=-L$(MPI)/lib -Wl,-rpath=$(MPI)/lib -lmpi

CXXLDFLAGS=$(FRIB_ANALYSIS_LDFLAGS) $(MPI_LDFLAGS)

CXX=$(MPI)/bin/mpicxx


myapp: MyWorker.o main.o
    $(CXX) -o$@ $^  $(CXXLDFLAGS) 

MyWorker.o: MyWorker.cpp MyWorker.h
    $(CXX) $(CXXFLAGS) -c $<

main.o:  main.cpp MyWorker.h
    $(CXX) $(CXXFLAGS) -c $<

The key points are that we defined FRIB_ANALYSIS to be the top level directory of the FRIB analysis pipeline version we're using and similalrly, defined MPI to be the toplevel directory for the version of MPI we're using. Note that different versions of MPI (e.g. mpich) may require different linking flags. See your MPI documentation for more information.

Once those definitions are made the remainder of the Makefile is pretty trivial.

Format of data Rustogramer accepts

Data files Rustogramer can analyze contain NSCLDAQ ring items. The set of ring items has been extended, however and Rustogramer only pays attention to a very few of the items. The items it cares about are defined in the AnalysisRingItem.h header file.

Note that analysis ring items doin't have body headers. Therefore if you want to retain the timestamp in your processed data, you must allocate a parameter to it and pull it out of the raw event body headers.

Therefore a Ring item header for analysis Ring item is defined as:

#pragma pack(push, 1)
namespace frib { namespace analysis {
typedef struct _RingItemHeader {
        std::uint32_t s_size;
        std::uint32_t s_type;
        std::uint32_t s_unused;    // must be sizeof(std::uint32_t).
    } RingItemHeader, *pRingItemHeader;
}}
#pragma pack(pop)

Where, as in NSCLDAQ ring items, s_size is the size in bytes of the entire ring item (including the s_size field itself). The s_type field is the type of the ring item, where AnalysisRingItems.h defines several new ring item types in the user ring item type domain. Note as well that RingItemHeader is, like all definitions for the FRIB analysis pipeline framework in the frib::analysis namespace and the two #pragma statements are g++ magic to ensure that the structures are tightly packed.

Parameter definition ring items

Each parameter file opens with a ParameterDefinitions ring item. Parameter definitions associate an integer with the names of each parameter written to the file:

#pragma pack(push, 1)
namespace frib { namespace analysis {
typedef struct _ParameterDefintion {
    std::uint32_t s_parameterNumber;
    char          s_parameterName[0];   // Actually a cz string.
} ParameterDefinition, *pParameterDefinition;

/**
    *  parameter defintion ring item
    *  sizeof  is not useful.
    */
typedef struct  _ParameterDefinitions {
    RingItemHeader s_header;
    std::uint32_t  s_numParameters;
    ParameterDefinition s_parameters [0];
} ParameterDefinitions, *pParameterDefinitions;

}}
#pragma pack(pop)

Starting with the defiition of ParameterDefinitions; This ring item has the normal ring item header. s_numParameters is the number of ParameterDefinition items that follow. Each ParameterDefinition provides a parameter number; s_parameterNumber and a null terminated parameter name string who's first character is at s_parameterName. This implies that the ParameterDefinition struct is really variable length.

The s_type field of the RingItemHeader for parameter definition ring items will be frib::analysis::PARAMETER_DEFINITIONS. At the time this is being written, this is 32768, however you should always relay on the symbolic name as that insulates your source code from changes.

A ParameterDefinitions ring item prior to actual event data is mandatory.

Variable Value ring items.

Our description of the FRIB analysis pipeline did not mention many of its capabilities. One capability is the ability to define values in the parameter definition file that can steer the computations of your workers. For example, you might provide calibration values to compute some calibrated parameters fromt he raw event parameters.

The NSCLSpecTcl CTreeVariable and CTreeVariableArray classes have identical classes (in the frib::analysis namespace) which bind objects to the names of treevariables and treevariablearrays you define in your configuration file.

The frib::analysis::VariableItem ring item documents the values of these variables at the time the parameter file was produced. The VariableItem ring item will immediately follow the ParmeterDefinitions ring item and is optional.

#pragma pack(push, 1)
namespace frib { namespace analysis {
typedef struct _Variable {
    double s_value;
    char   s_variableUnits[MAX_UNITS_LENGTH];     // Fixed length
    char   s_variableName[0];       // variable length
} Variable, *pVariable;

typedef struct _VariableItem {
    RingItemHeader s_header;
    std::uint32_t  s_numVars;
    Variable       s_variables[0];
    
} VariableItem, *pVariableItem;

}}
#pragma pack(pop)

The s_header.s_type value for these ring items is frib::analysis::VARIABLE_VALUES. As you might expect, s_numVars is the number of variable definitions that follow starting at s_variables

A variable has a name, a value and units of measure. These are held in a variable length frib::analysis::Variable struct:

• s_value is the value of the variable. For maximum flexibility, these are represented in double precision floats.
• s_variableUnits - is a character array frib::analysis::MAX_UNITS_LENGTH long that contains the variable's units of measure. The string itself is null terminated and no assurances are made about the values following that null.
• s_variableName - is the first character of the variable's name. The name is stored as a null terminated string and is what makes the Variable struct variable length.

Parameter data ring items.

frib::analysis::ParameterItem ring items hold the paramters in one event extracted by your worker from the raw data. In general, the remainder of the parameter file will be composed of these items as well as items from the original event file that the pipeline ignored.

Here is the structure of frib::analysis::ParamterItem ring items:

#pragma pack(push, 1)
namespace frib { namespace analysis {
typedef struct _ParameterValue {
    std::uint32_t s_number;
    double        s_value;
} ParameterValue, *pParameterValue;

/*
    * Ring item of parameter unpacked data.
    * sizeof is worthless.
    */
typedef struct _ParameterItem {
    RingItemHeader s_header;
    std::uint64_t  s_triggerCount;
    std::uint32_t  s_parameterCount;
    ParameterValue s_parameters[0];
} ParameterItem, *pParameterItem;
}
#pragma pack(pop) 

The s_header.s_type value of this type of ring item will be frib::analysis::PARAMETER_DATA.

• s_triggerCount - is the number of the event. Each raw event is assigned a trigger number by the pipeline dealer. That trigger number is just a sequential value and is used to re-sort the data emitted by the workers into the original event order. In this way the framework can be used wih data that are not timestamped.
• s_parameterCount - The number of parameters unpacked from this event. A parameter that was not assigned a value by the worker's unpacker for this event will not have a parameter value in this ring item.
• s_parameters is an array of s_parameterCount instances of frib::analysis::ParameterValue objects.

Parameter values contain:

• s_number the parameter number of a parameter in the ParameterValue ring item. This number is used to make a correspondence between parameter names and actual parameters.
• s_value for this event, the value of that parameter.

Suppose, for example, that ther ewas a ParameterDefinition with s_parameterNumber having a value of 124 and a s_paramterName of "dummy"; Any ParameterValue with s_number == 124 will have s_value set to the value of parameter dummy for this event.

Chapter 3 - Running Rustogramer

Rustogramer tries to be compatible with NSCLSpecTcl in several ways:

• It supports the most commonly used spectrum types defined by SpecTcl
• It supports the most commonly used condition (gate) types defined by SpecTcl
• It implements a REST server that is highly compatible with SpecTcl's allowing clients to work both with SpecTcl and Rustogramer.
• It implements a share display memory that has a structure that is compatible with SpecTcl's, though rather than placing that shared memory in a SYSV shared memory segment, the mmap subsystem which maps shared memory to ordinary files is used.
• It implements a mirror server that allows remote clients to create a mirror of the display memory in remote systems.
• It can either user hard coded port values for its servers or it can use the NSCLDAQ port manager software to allocated a named service.

For simplicity, we assume that rustogramer was installed in /usr/opt/rustogramer/version In practice, version in the path above would be a rustogramer version string of the form a.b.c where a,b,c are integers.

Running rustogramer with hard coded server port values.

Before you take this approach note that you'll need to assign port numbers that are unique system wide. That means you must avoid port numbers used by other instances of rustogramer you run in your system as well those run by other users. This can be very difficult and is why we recommend that you use the NSCLDAQ port manager to assign and advertise services. See the next section below for a description of this process and the prerequisites it requires.

The rustogramer command is in the bin directory of the rustogramer installation tree and is named rustogrammer (note the doubled m). The command accepts serveral options that are described fully in Command Line Options. To run with manuall assigned ports you'll need:

• --shm-mbytes (which can be abbreviated -s). The value that follows this option are the number of megabytes of shared spectrum memory rustogramer will create. Note that you must have sufficient disk quota in your home directory to support the creation of the shared memory file. If not specified, this defaults to 32
• --rest-port (which can be abbreviated -r). Specifies the port on which the REST server will listen for connections. This defaults to 8000.
• --mirror-port Specifies the port on which the shared memory mirror server listens for connections. This defaults to 8001.

Typically, then to run rustogramer with hard coded port values you choose the amount of spectrum memory you will need, assign prot values for the REST and mirror servers and supply appropriate values to the options above. Given the defaults; if rustogrammer is in your path:

rustogramer

is equivalent to

rustogrammer --shm-mbytes 32 --rest-port 8000 --mirror-port 8001

Using the port manager to assign server port values

The NSCLDAQ port manager can be run to reduce the work you have to do to ensure that rustogramer ports are uniquely chosen. The port manager assigns free ports from a pool it maintains and associates them with a name (service name) and the user whose program made the request. As long as the program holds the connection over which it asked for a port open, the port remains allocated to the requester and clients can interact with the port manager to translate service name/user pairs into port numbers.

Where possible, this is the recommended way to use rustogramer. Rustogramer knows that the port manager itself has allocated port 30000 and can interact with it by making connections to that port.

You still must take care that for every instance of rustogramer you run within a single system, you choose a unique service name. You don't have to worry about choosing a unique name across all system users, but, if you run rustogramer more than once in a single system, you need unique service names for each rustogramer.

You can specify service names using the --rest-service and --mirror-service command line options rather than the ---rest-port and --mirror-port options described in Using hard coded values above. There are no default values for these options. Supplying these options will override any port values you may have otherwise specified. Here's a sample command line:

rustogrammer --shm-mbytes 128 --rest-service RG_REST --mirror-service RG_MIRROR

It runs rustogramer creating a 128 Megabytes spectrum memor region, and allocates/advertises with the port manager:

• RG_REST - for the REST server.
• RG_MIRROR - for the mirror server.

At any run of rustogramer with these values the actual ports allocated may vary. Note that if another user runs rustogramer with the same service names, there is no collision as the NSCLDAQ port manager qualifies the service name with a username so, if my username is rusty and another user named graham runs rustogramer in the same way, four distinct ports wil be allocated and advertised as:

| Service   |  user  | 
|--------------------|
| RG_REST   | rusty  |
| RG_MIRROR | rusty  |
| RG_REST   | graham |
| RG_MIRROR | graham |

If graham looks up the port RG_REST he'll get the port his rustogramer rserved and rusty will get the one she allocated.

Chapter 4 - Using the Rustogramer GUI

Rustogramer suplies a sample GUI that is based on the NSCLSpecTcl treegui with, what I think are, some improvements in how objects are creatd. The GUI is a sample of a REST client written in Python against the Python Rest API.

If the envirionment variable RUST_TOP is defined to point to the top installation directory of Rustogramer, you can run the gui as follows:

$RUST_TOP/bin/gui [--host rghost] [[--port rest_port] | [--service rest_service] [--service-user rg_user]]

The gui supports the following command options

• --host specifies the host on which the rustogramer you want to control is running. This defaults to localhost if not specified.
• One of two methods to specify the REST port that Rustogramer is using:
  • --port specifies the numeric port on which Rustogramer's REST server is listening. This defaults to 8000 which is Rustogrammer's default REST port.
  • If rustogramer is using the NSCLDAQ port manager to advertise a service name:
    • --service specifies the name of service rustogramer is advertising.
    • --service-user specifies the name of the user that rustogramer is running under. This defaults to your login username and, in general, should not be used.

When connected to Rustogramer, the GUI will look like this:

Prior to describing each of the user interface elements let's look at a few features of this image.

• The menubar at the top of the window provides access to operations that are not as frequent as those available on the main window. Note that the contents of the menubar depends on the actual application the GUI is connectec to.
• The tabs below the menu-bar provide access to the sections of functionality of the GUI. Note that the set of tabs will, again, depend on the application the GUI is connected to. For example, Rustogramer does not have TreeVariable like functionality as that capability is pushed back onto the code that prepares data-sets. If connected to SpecTcl, however, a Variables tab will be present.
• Below the Tabs are controls for the things that Tab manages. In the figure above, the Spectra tab is selected and shows a tabbed notebook that allows you to create and edit the definitions of Spectra as well as a filtered list of spectra and their applications. More about this tab in the documentation the spectra tab
• Note that the only thing the Help menu provides is information about the program (the About menu command).

For information about the contents of each tab:

• The Spectra Tab
• The Parameters Tab
• The Variables Tab (SpecTcl only).
• The Gate Tab
• The BindSets Tab

For information about the Menus:

• The File Menu
• The Data Source Menu
• The Filters Menu (SpecTcl only).
• The Spectra Menu
• The Gate Menu

The rustogramer GUI is now included in SpecTcl (as of version 7.0). To use it you'll need to setup the ReST server as described in the CutiePie documentation. You can then start the GUI from SpecTclRC.tcl by adding the line:

exec python3 $SpecTclHome/pythontree/Gui.py --port $HTTPDPort &

towards the end of that file.

The Spectra Tab

The spectra tab has three components:

• A set of tabs that selec spectrum editors. The actual set of tabs depends on the program the GUI is connected to as SpecTcl implements a few spectrum types that are not implemented in Rustogramer.
• A vertical bar of buttons that provide access to operations on spectra.
• A filterable spectrum list. Spectra in this list can be selected so that they become the target of some opeartions.

The Button bar.

The button bar contains the controls show below:

The button bar works in conjunction with selected spectra in the spectrum listing (see The Spectrum Listing).

As we will see in the section that describes the spectrum listing, you can select any number of spectra in the list.

• The Clear button clears the contents of all selected spectra.
• The Clear All button clears the contents of all spectra.
• The Delete button, after prompting for confirmation, deletes the selected spectra.
• The Pull down menu below the Delete button allows you to select a condition.
• The Gate button, applies the selected conditions to all selected spectra.
• The Ungate button removes any condition applied to the selected spectra.
• The Load editor button requires that only one spectrum be selected. It loads the definition of that spectrum into the appropriate spectrum editor and selects the tab of that editor. This allows you to either modify the definition of that spectrum or, by changing the name, to copy the spectrum.
• The pulldown menu labeled Channel Type: allows you to select the data type for the channels of spectra that are created. The values in the pull down will reflect the capabilities of the program the GUI is connected to:
  • Rustogramer only supports channels that are 64 bit floats. Note that these get stored in shared spectrum memory as uint_32's.
  • SpecTcl supports the following channel types;
    • long (32 bit unsigned integer).
    • short (16 bit unsigned integer).
    • bytes (8 bit unsigned integer)

The Spectrum listing

The Spctrum listing part of the Spectrum Tab looks like this:

Note that you can stretch the listing horizontally and, if you stretch the entire GUI vertically, all additional space is added to the listing.

Let's start with the controls at the bottom of the listing. The Filter button updates the listing to only show the spectra with names that match the pattern in the editable text field to its right. This pattern can contain any filesystem wild card characters. The Clear button clears the pattern back to the default *, which matches all spectra and updates the list.

The columns on the table reflect the contents of the column for each spectrumin the list. From left to right:

• Name The name of the spectrum.
• Type The SpecTcl spectrum type string for the spectcrum.
• XParameter(s) lists all parameters on the X axis of the spectrum.
• Low, High, Bins to the right of XParameter(s) describe the X axis of the spectrum.
• YParameter(s) lists all parameters on the Y axis of the spectrumn.
• Low, High, Bins to the right of YParameter(s) describe the Y axis of the spectrum.
• Gate If not blank, contains the name of the condition applied to the Spectrum.

You can also stretch the column widths to match your needs.

You can select any number of spectra simultaneously and selection regions need not be contiguous. The selected spectra are operated on by the buttons in the Button bar

The Spectrum editors.

The tabs allow you to select spectrum editors that allow you to create/replace spectra. Each of these editors has a

• Name edit which is mandatory and into which you should put the spectrum name.
• Create/Replace button which you should click to create the spectrum.

If, when you click the Create/Replace button, spectra with the same name exist, a dialog will ask you to confirm the replacement of those spectra (which will be listed in the dialog).

The set of editors (tabs) will depend on the spectrum types that are supported by the histogramer we are connected to.

The subsections below will describe each of the spectrum types and their editors:

• 1D spectrum editor
• 2D Spectrum editor
• Summary Spectra
• Gamma 1D spectra
• Gamma 2D spectrum editor
• Gamma Deluxe spectrum editor
• 2d Sum Spectrum
• Projection Spectra
• Strip charts
• Bit mask spectra
• Gamma summary spectra

1-D Spectrum

1-D spectra (SpecTcl type 1), histogram the values of a single parameter over a range with a specified binning. The editor looks like this:

Select the parameter to histogram from the Parmater pull down. It's a hierarchical menu using the . character as a path separator. When you have selected a parameter, the full name of the parameter will appear below the pull down. If the parameter has metadata definining the range and suggested binning, that information will initially populate the Axis pulldowns. The Low, High and Bins pull-downs pre-load with a set of common values but you can also type a value you want in the pulldown. If you do so, that value is added to the list of values.

The Array? checkbox allows you to create a group of spectra very quickliy. Suppose, for example, you have paramters p.0, p.1...p.15 and you want to create spectra named p.raw.0 ... p.raw.15. If yo uchose any of the p.n parameters and set the name to p.raw, checking the Array? checkbox will create those spectra.

2-d Spectrum

2-d spectram (SpecTcl type 2) are two dimensional heat map spectra that histogram the correlated values of an x and a y parameter. The editor for these looks like this:

The mechanics of this editor are very similar to those of the 1D editor. Select X and Y axis parameters from the pulldowns associated with each axis, ensure the axis specifications for the X and Y axes are what you want, provide a spectrum name and click Create/Replace to create the spectrum or overwrite (after confirmation) an exising spectrum with the same name.

Summary Spectrum:

Summary spectra (SpecTcl type s) are a 2-d spectrum that allow you to look at the health of several identical spectra simultaneously. Each X axis bin is associated with a parameter and the 1-d histogram of that parameter's values appears on the Y axis of that bin.

The summary spectrum editor editor looks like this:

Parameter selection involves filling in the Parameters box to the right of the parameter chooser dropdown. If you have selected a parameter you can add it to the list of parameters in the box by clicking the right arrow button. To remove parameters fromt the list, select them and click the X button. You can add a related set of parameters to the list box by checking the array checkbox before clicking the right arrow button.

For example, if you have parameters named p.0, p.1 ... p.15 and you want them all in the list box, select one of them, check the array checkbox and click the right arrow button. That will add all parameters that match p.*

You can re-order parameters. Move parameters up in the list by selecting them (you can select more than one) and clicking the up arrow button. Similarly the down arrow button moves parameters down in the list. The Clear button clears the parameter list.

The Axis inputs define the Y axis. If From Parameters is checked, than the right arrow button also loads the axis description from the parameter metadata for the parameter(s) it added.

Once the desired list of parameters has been selected, the Y axis defined and a spectrum name input; Clicking the Create/Replace button will create the spectrum (or replace an identically named spectrum after confirming)

Gamma 1-D spectrum

Gamma 1-d spectra (SpecTcl type g1) are multiply incremented 1-d spectra. The histogram is incremented for all of the values of its parameters. You can think of it as a sum of the 1D spectra of all of its parameters. The Gamma-1D spectrum looks exactly like the summary spectrum:

When creating a Gamma 1d spectrum, however, the list of parameters determines the set of parameters that can increment the spectrum for any event. Note that while in summary spectra the order of the parameters in the list box determines which X axis bin that parameter occupies, for Gamma-1D Spectra, the order is meaningless.

Gamma 2-D spectrum

Gamma 2d spectra (SpecTcl type g2) are 2-d spectra that increment for all pairs of spectrum parameters present in any events. The editor for this spectrum type is similar to the summary spectrum editor but has a pair of axes:

Normally the X and Y axes have the same definition but neither rustogramer nor SpecTcl require this

Particle Gamma Spectrum.

Particle gamma spectra (SpecTcl type gd) allow you to define a set of X and Y parameters. The resulting 2d spectrum is incremented for each ordered pair of parameters in the event. In general, this results in more than one increment per event.

The editor, therefore looks like:

The mechanics of using this editor are the same as using the editor for a summary spectrum, however: There are two editable parameter lists. Having selected a parameter you can put it in either the X or Y parameters list depending on which of the arrow buttons you click.

2-D Sum spectrum

2d Sum spectra (SpecTcl type m2), are spectra that, effectively are the sum of one or more 2-d specctra. They require an equal number of x and y paramters (unlike gamm deluxe where the number of X paramters need not be the same as the number of y parameters). Channels are incremented for matching pairs of parameters in the event.

Suppose, for example, the X parameters are x1, x2 and the y parameters are y1 and y2. If all four parameters are present, then two channels will be incremented. One at the values of x1, y1 and the other at x2, y2.

The editor is identical, however to the Gamma Deluxe editor:

Projection spectra.

Projection spectra are spectra that are created by initially projecting a suitable 2d spectrum onto one of its axes. The projection can also occur within a Contoure that is displayable on the spectrum. The spectrum could be created either as a snapshot, in which case it does not increment, or a "normal" spectrum in which case, if possible it will increment as addition data are analyzed.

The editor is a bit odd looking compared with the other ones we've looked at:

After selecting a name for the spectrum and choosing whether or not the spectrum is a snapshot or not; select a source spectrum in the Spectrum pulldown menu. Choose if an X or Y projection is desired.

If the projection is within a contour; check the contour checkbox and choose the contour from the dropdown below the checkbox. As usual the Create/Replace button, when clicked, creates the spectrum.

Strip charts

Strip chart spectra (SpecTcl type S), show the time evolution of one parameter against another. Typically the X parameter is something that changes monotonically with time and the Y parameter represents a count of the number of times something occured within some time bucket (usually it's a computed parameter that is just set to 1 if the event of interest occured). Strip chart spectra have the interesting characteristic that if an X value appears that is off the end of the spectrum (in either direction), the X axis is scrolled to accomodate that new value (the data too are scrolled).

The Strip chart spectrum editor looks like this:

In addition to the name of the spectrum you need to select a time (X) parameter and a Y parameter. The values of the Y parmeter that occur within a time bin are summed. The axis specification is an initial axis range and a fixed binning along that range. The range may scroll, but the number of bins in the range will be fixed.

Bit mask parameters

Spectra can also be created on parameters that represent integer bit masks (for example a trigger mask). The editor for a bitmask spectrum looks like this:

In addition to the spectrum name, select a paramter and define the number of bits that are significan (starting from the low order bit). The spectrum will be incremented for each bit that is set in the parameter within the number of bits desired.

Gamma summary spectra

A gamma summary spectrum is a bit like a summary spectrum, however, each vertical channel is a gamma spectrum. Thus each X bin requires a list of parameters and increments will occur in the vertical stripe defined by that bin for each of those parameters present in the event.

As such the editor for Gamma Summary Spectra is a bit complicated:

Let's start by looking at the tabbed set of list-boxes at the right of the editor. The tabs are labeled numerically with the exception of the right most tab which is labeled +. The numbered tabs represent lists of parameters for the gamma spectrum that's stacked on that bin. E.g. The tab labled 0 which is the only numbered tab initially available should be filled in with the parameters you want on that bin. The process of filling in these parameter list boxes should, by now, be familiar.

Clicking the tab labeled + will add a new tab with the next sequential X bin number. This allows you to build up, bin-by-bin, the list of parameters for each bin.

The remainder of the editor should be familiar by now. A spectrum name, a Y axis specification and the usual Create/Replace button to actually create the spectrum.

The Parameters Tab

The Parameters tab allows you to see and modify the metadata associated with paraemters. Each parameter optionally has the following metadata:

• Low The recommended low limit for axes that are defined on this parameter.
• High The recommended high limit for axes that are defined on this parameter.
• Bins The recommended number of bins between [Low, High).
• Units The units of measure of the parameter.

Modifying these metadata will modify the axis definitions that the GUI will suggest for spectra you define with the Spectrua tab.

Let's have a look at the Parameters tab:

The top part of this GUI contains a parameter chooser and a bunch of buttons. The bottom part, contains a tabular list of parameters and their metadata. You determine which parameters are displayed.

You can edit the contents of the table as follows:

• Clicking the Append button adds a new row to the table that will contain the paramete metadata for the parameter currently selected in the parameter chooser. If the Array checkbox is selected, the parameter is assumed to be a member of an array of parameters and lines are added for all parameters in the array.
• Clicking the Replace button will replace the current selected row in the table with the parameter that is selected in the parameter chooser. Only one parameter line may be selected for this to operate.
• Clicking Remove Selected will remove all selected rows from the table.

Once the table is populated; you an select any number of rows. THe selection can be non-contiguous as well. You can also edit the metadata by typing into the metadata cells in the table. The Reload button will Reload the metadata for all table cells.

The following button operate on the selected rows of the table:

• Load - loads the parameter metadata for the selected cells from the server.
• Set - Sets the parameter metadata for the selected cells into the server.
• Change Spectra Uses the metadata in the selected parameters to re-define the axis specifications for spectra that use any of the selected parameters. You will be prompted to confirm along with the names of the affected spectra.

The Variables Tab

This tab is only available with SpecTcl. The Variables GUI looks like this:

The controls on this tab are similar to those on the Parameters tab. The only differences are:

• The only data associated with a variable are its value and units of measure.
• Since spectra don't depend directly on the values of variables, there's no button to redefine spectra.

As with the parameters tab, there are several controls at the top of the window and a table of variables and their data below. You use the controls in the top line of the window to populate the table:

• At the left is a variable chooser. You can drop it down to select a variable name.
• Clicking Append adds the variable and its current values/units to the end of the table. If the array checkbox is checked, the variable selected is taken to be an element of an array of variables and all elements are of the array are added.
• Clicking Replace Replaces the one selected line in the table with the variable selected by the variable chooser.
• Clicking Remove removes all seleted rows in the table.
• The Load button loads the selected table rows with the current variable values and units.
• The Set button stores into SpecTcl the variables in the selected rows with their values and units.

The values and units in the table can be edited, however the Set button must be used to transfer selected, edited variable values and units int SpecTcl. Furthermore any number of rows can be selected to be operated on by the buttons in the to section of the UI. Note that the selection need not be a contiguous set of rows.

The Gate Tab

The gate tab can be used to define rustogramer conditions (gates in SpecTcl). Conditions are entities that, per event, are either true or false. A single condition can be applied to a spectrum (of course the same condition can be applied to as many spectra as you like). If a spectrum has a condition applied to it, it will only increment for events for which it's applied condition (in rustogramer this is called a gate) is true (of course the parameters needed to increment the histogram must also be present in the spectrum).

With respect to primitive conditions, an important, and often forgotten point is that conditions are not defined on spectra, even if a displayer like CutiePie was used to create the condition. It is defined on one or more parameters. For example, a slice condition is true for events where its parameter lies within its limits. A condition may be displayable on a spectrum but is never defined on it.

Let's look at the Gates tab when the Gui is attached to Spectcl. SpecTcl defines a few condition types that rustogramer does not implement. Therefore not all of the gate editor tabs visible in the picture below will be available if the GUI is used to control rustogramer.

Key features to note:

• At the top of the Gates tab are a set of tabs. Each tab is labeled with a condition type. Clicking on tabs allows you to display a condition editor for that condition type.
• At the bottom is a table of conditions and their properties.
  • The Filter button updates the table, only displaying the conditions whose names match the pattern.
  • The text input to the right of the Filter button allows you to edit a pattern which Filter will match names against. The filter string can contain any of the wild-card characters used in file system name matching (e.g by ls).
  • The Clear button clears the pattern to *, which matches all names and upates the table.
• The table supports selecting an arbitrary number of conditions. The selection, need not be contiguous. The table is not editable.

The buttons between the editor and table manipulate selected condition(s) in the table:

• Delete Selected deletes the selected gates. The behavior of spectra that use that condition as a gate or conditions that depend on that condition differs somewhat between SpecTcl and rustogramer
  • In SpecTcl, a deleted condition is replaced with a False condition.
  • In rustogramer deleted conditions are really deleted and:
    • Spectra gated by that condition become ungated on the next event.
    • Conditions that depend on that condition operate in a manner depending on their type:
      • Not conditions will always return false if the condition they depend on is deleted.
      • And conditions will always return false if any condition they depend on is deleted.
      • Or conditions will return a value that depends on the values of the remaining conditions, that is if any remaining condition is true they will return true, but if all remaining conditions are false the condition evaluates as false. Thus you can treat the deleted condition as if it were a false condition.
• Load Editor requires that only one table item be selected. The tab for the selected condition type is selected and the condition is loaded into the editor. This allows for:
  • Edits to the condition that do not change its type.
  • Creation of new conditions that start from the same definition as an existing condition (e.g. a slice with the same parameter but a different acceptance region).
• Delete Displayed Deletes the condition currently displayed in the editor.

You might wonder how you can edit a condition to change its type. Simply edit a condition with a different type but the name of the condition you want to change. When you save the edited condition, it will transparently replace the previous condition and:

• Any spectrum gated on the old condition will now be gated on the new condition.
• Any condition that depended on the old condition will not depend on the new one.

The sections below describe the various types of condition editors:

• Slice editor
• Contour editor
• And and Or editor
• Not editor
• Band editor
• Gamma band and contour editors
• Gamma slice editor
• Bit mask conditions
• True/false conditions

Slice conditions

Slice conditions are defined on a single parameter. Slices have an acceptance region defined on that parameter.

• If the parameter the slice is defined on is not defined in an event, the slice is false
• If the parameter the slice is defined on is defined in an event, the slice is true if the parameter value lies within the acceptance region.

Here's what the slice editor looks like:

The name entry allows you to provide a name for the condition. The parameter chooser allows you to select the parameter the condition is defined on and the Low and High editors allow you to specify floating point limits for the condition's acceptance region.

Clicking the Create/Replace button creates a new condition or replaces an existing one with the same name if it iexists.

If you are using a displayer like CutiePie, it is often easier to create a slice gate by drawing it on a spectrum which displays the desired parameter. The displayer will convert screen coordinates to parameter coordinates and ask rustogramer or SpecTcl to create/replace the appropriate slice gate.

Contour condition

Contour conditions are defined on two parameters. These two parameters define a plane in parameter space. A contour then is a closed polyline on that plane. Contour conditions are true when:

• Both parameters are defined for the event.
• The point defined by the ordered pair of parameters is inside the closed polyline.

It is possible to draw quite pathalogical polylines with corssing lines. I have seen use cases where this is important (hour-glass shaped contours to accept any point in either lobe of the hourglass). It is therefore important to carefully define waht inside means for arbitrary figures.

Definition: A point is inside a contour if, extending a line in any direction crosses an odd number of lines that compose the contour.

This definition of insided-ness is used by both SpecTcl and Rustogramer.

Here's what the contour editor looks like:

• As usual, at the top of the editor, you can type in the contour name.
• Parameter choosers allow you to specify the X and Y parameters that define the parameter plane.
• The two entries labeled X and Y let you enter floating point values for points on the polyline that define the contour. Clicking the right arrow button adds a point to the list of points to the right. The list can be edited using the X button to remove selected points, the up and down arrows to move selected points up or down in the list and the Clear button to clear the list. Note that you do not need to close the polyline. An implied additional line is created joining the first an last points.
• Clicking Create/Replace creates the named contour or replaces a condition with the same name.

And and Or conditions.

These two condition types are defined on an arbitrary number of dependent conditions. There is no requirement that the dependent conditions be primitive conditions. You can use these (in conjunction with Not conditions) to build up arbitrarily complex condition logic.

• And conditions are true for events that make all dependent conditions true
• Or conditions are true for events that make any dependent condition true.

Here's what the editor for And and Or conditions looks like (same editor is used for both types):

• The name entry at the type, as usual, allows you to enter a name for the condition.
• The condition selector allows you to chose a conditions which you then add to the list of dependent conditions by clicking the right arrow.
• You can edit the list of dependent conditions using the usual controls for lists of this sort.
• Clicking Create/Replace creates the new gate (or replaces one with the same name).

Not conditions

Not conditions depend on a single condition. They return the inverse value of their dependent condition. If their dependent condition is true, they return false. If the dependent condtion is false, they return true.

The dependent condition can be any type of condition. For example you can construct a Nand condition by defining and And condition and making it the dependent condition.

The editor for Not conditions is very simple:

Fill in the name of the condition at the top, select the dependent condtion from the Gate: drop-down menu and click Create/Replace to create the new condition or to replace any existing condition with the same name.

Band Conditions

Band conditions are similar to Contour conditions. The difference is the meaning of the points accepted. For a contour condition, one needs at least three points to define a closed figure and events where the parameters are inside the closed figure make the condition true. For band conditions, you need at least two points and the condition is true for events that make points below at least one line segment. Note that if you define a polyline with backtracking, this means that points lower than the highest segment the point is above rules.

The band editor looks, and functions exactly like the contour editor:

The only differences are:

• The condition only requires two points.
• A band condition is created rather than a contour.

Gamma bands and contours

Gamma bands and contours are defined on at least two parameters. The operate like band and contours, however all ordered pairs of paramters are checked to see if satisfy the band or contour condition.

Both use the same editor:

As you can see, in addition to the controls present for a contour or band editor, the Gamma band/contour editor provides for an arbitrary list of parameters to be accumulated.

Gamma slice conditions

A gamma slice is like the or of several identical slices on different parameters but with the same acceptance region. Here's the gamma slice editor:

In addition to the name and acceptance regions needed for a slice condition, this editor allows you to accumulate an arbitrary list of parameters on which the slice will be evaluated. If any parameter is inside the acceptance region the condition evaluates as True.

Bit mask conditions

Bit mask conditions treat a parameter as an integer set of bits. When you define a bitmask condition you define a mask of bits. The condition is satisfied depending on the bits set in the parameter and the mask:

• Mask== are satisfied if the parameter is equal to the mask (SpecTcl em gate)
• Mask* are satisfied if the parameter anded with the mask is equal to the mask (the paramter has all bits set the mask has) (SpecTcl am gate).
• Mask- are satisfied if the parameter anded with the bitwise complement of the mask is equal to the bitwise compllement of the maski (SpecTcl nm gate).

All of these bit mask conditions share the same editor:

After choosing a name and parameter for the condition, check the bits that are set in the mask. As usual the Create/Replace button creates the new condition, if necessary replacing any existing condition with the same name.

True and False conditions

True and False conditions are generally used as placeholders. As their names imply, True conditions are true for all events and False conditions are false for all events. A normal use is that you anticipate you will gate a spectrum but don't yet know how. You can create the spectrum, create a True condition and apply that to gate the spectrum.

When you know how you will actually gate the spectrum, you can create a condition with the same name as your placholder True condition. Since the gated spectrum is already gated on the correct condition you don't have to remember to apply the condition you just made.

True and False condition editors only differ in the type of condition initially set on them:

Note that if you change your mind about which condition type you are making, simple click the correct radio button.

The BindSets Tab

This section describes the Bindsets tab. Before describing how to use that tab let's take a bit of time to describe what a bindset it and why they can be useful.

Both SpecTcl and Rustogramer don't have intrinsic visualizers for their spectra. These are supplied by external, programs such as CutiePie. SpecTcl and Rustogramer both provide a display shared memory region in which spectra that can be visualized are stored. The process of storing spectra in this shared memory is called sbinding and the process of removing a spectrum from the shared memory is called unbinding. Sbinding and unbinding have no effect on spectrum contents.

Both Spec Tcl and Rustogrammer can support as many spectra and as much spectrum data as virtual memory allows. However the shared memory size is fixed at program start. In the past, SpecTcl GUIs attempted to just sbind all spectra. As analysis becomes more complex and the amount of spectrum storage increases, this is less and less feasible. Thus bindsets.

What are bindsets

A bindset is:

• A name
• A description
• A list of spectra.

The GUI supports loading bindsets into shared memory (either first unbinding the spectra in shared memory first or supplementing the set of spectra already sbound int shared memory). Think of a bindset as a group of spectra that you will tend to want to look at for some period of time. The idea is that the set of spectra you need to see when you are setting up an experiment, debugging detectors and electrons, may well be different from the set of spectra you want to see at various points of running the experiment with beam. Bindsets support loading only the spectra you want to see at any given time into the display shared memory.

The Bindests tab supports:

• Saving the currently bound spectrum in a new or existing bindset.
• Creating a new bind set.
• Editing an existing bind set.
• Loading a bind set into shared memory.
• Adding the spectra in a bind set to those in shared memory.
• Attempting to sbind all spectra into shared memory.

Furthermore, the File->Save... menu operation saves the bindsets you've defined to the database file and File->Load... loads them from the selected database file.

The BindSets tab contents

The BindSets tab looks like this:

At the center of the user interface is a table (which becomes scrollable if needed). The table lists the bind sets you have defined along with their descriptions. At any time you can select one of the bind sets by clicking on it.

If you have loaded a bindset, its name and description are loaded into the labels above the table. The buttons that have the text Selected in their labels require that you have selected a bindset in the table and operate on the selected bindset.

The buttons are in logical rather than visual order:

• New... - makes a new bindset.
• Edit Selecteed... - edits the selected bindeset.
• Load Selected - Loads the selected bindset in to shared memory after first unbinding any spectra that are there.
• Add Selected - Attempts to add the selected bindest to those in shared memory.
• Save as selected... - Save the currently bound spectra to the selected bindset
• Save as new... - Save the currently bound spectra to a new bindset.
• Bind All - attempts to bind all defined spectra to the display memory.
• Update (spectra) - updates the spectra known to the bindset editors from the histogramer

New bindset

Clicking the New... button pops up a dialog that contains the bind set editor:

At the top are entries for the bindset name and description. The description can be omitted, though this is not recommended. The bindset name is mandatory.

The list at the left of the editor is the list of spectra that can be put into the bind set. It's called the source list. The list at the right is the set of spectra you've currently got in the bind set. Add spectra to the bindset by selecting any number of spectra from the source list and clicking the right arrow button between the two lists. When you do this the spectra are removed from the source list and appended to the right listbox.

You can also select spectra from the right box and click X to remove them (they will be added back to the source list). The Clear button removes all spectra from the right list adding them back to the source list. The up/down arrows move the selected spectra up or down in the right list box and are just there to allow you to organize that box.

When you are happy with the bindset you've created, click the Ok button. To abort the creation of the bind list, click the Cancel button.

Edit bindset

The Edit Selected... button also pops up the bind set editor described in the New bind set section. However, the editor is first populated with the name and description of the selectged bind set. The right list box is populated with the spectra in the bind set and those spectra do not appear in the source list.

Save selected

Pops up the bind set editor with the name and description of the editor populated from the selected bindset but the right listbox, populated from the spectra that are currently bound in the shared memory.

Save new

Pops up the bind set editor with the name and description not populated but the right listbox populated from the spectra currently bound to shared memory.

The File Menu

The file menu provides access to various file related operations. The available commands differ depending on whether the Gui is attached to SpecTcl or Rustogramer.

Here's the exhaustive list of operations the File menu can perform. IF a menu item is only available in SpecTcl or Rustogramer that is noted:

• Save...
• Save Treevariables... (SpecTcl only)
• Save Spectrum contents...
• Load...
• Read spectrum contents...
• Source Tcl Script... (SpecTcl only)
• Exit
• Stop Histogramer (Rustogramer only)

File->Save...

This menu item saves the cofiguration in an SQLite3 database file. The schema for these files closely follows the SpecTcl database storage schema and is described in Schema of configuration files. You will be prompted for a filename and the following will be saved:

• Parameter definitions and their metadata.
• Spectrum definitions.
• Condition definitions.
• Which conditions are applied to which spectra.
• For SpecTcl, the treevariable definitions (names values and units.)

File->Save Treevariables...

SpecTcl only can save tree variable definitions to an Sqlite3 data base file. The schema for that file is the same as for the file saved by the Save configuration operation, however only the tables germane to tree parameter definitions are populated.

File->Save spectrum contents...

Provides the capability to save the contents of one or more spectra to file. Before being prompted for the output file you'll be prompted for the spectrum and file format as follows:

In the top part, select the spectra to save. The right arrow button adds the spectra selected on the lef to the listbox on the right. The list box on the right is editable; you can remove and reorder its spectra or just remove them all from the box.

The radio buttons on the bottom select the file format. The following file formats are supported:

• ASCII this is SpecTcl ASCII format.
• Binary (SpecTcl only) this is legacy Smaug format.
• JSON is Java Object Script Notation (click the link for format details).

Note that spectra are actually saved by the server not by the GUI. This means that this operation will only work properly if the GUI is run on a system that shares the same file system as the server.

For example, a client running on a desktop system communicating with a SpecTcl or Rustogramer running on an FRIB linux system in general, will not be able to successfully save files as the file paths requested for the server won't exist in the server.

A more subtle case is if, on a desktop, you are running the GUI natively but rustogramer or SpecTcl in Windows Subsystem for Linux or a virtual machine, the save will, in general fail.

File->Load...

Loads a configuration file from an SQlite3 databas file into the server. It is the GUI that interprets the database file contents. After being prompted for the name a file, parameter definitions will be loaded from that file. You'll be prompted for what to do with duplicate spectrum definitions:

You have the following choices:

• Delete all existing all existing spectra will be deleted before restoring the spectrum definitions from file.
• Overwrite existing defs any spectra defined in the server with the same name as one in the file get ovewritten by the definition in the file.
• Don't re-define duplicates any spectra defined in the server with the same name as one in the file don't get restored from file, retaining the old definition.

Conditions will unconditionally overwrite existing conditions with the same name. All spectra will be bound to the display memory.

File->Read spectrum contents...

Reads the contents of a spectrum file. First you will be presented with the following dialog:

This dialog allows you to describe how spectra read from file will be loaded by the server and in what format the file is.

• Save Options:
  • Save as snapshots - spectra will be created as snapshots which means they will never increment as new data are processed.
  • Replace Spectra with same names - If unchecked new unique names will be used to avoid collisions with existing spectra. If checked, any exising spectrum with the same name as one in file will be deleted.
  • Bind to display memory - IF checked, the spectra are bound into display memory. If not, they are held local to the histogram server and can't be visualized until they are bound later.
• File format; as described in File->Save spectrum contents..., the format of the file that is being read.

File->Source Tcl Script...

This option is only available to SpecTcl servers. As with spectrum contents files, since the file is opened in the server, the GUI must have a shared file system with the server. Select a file and SpecTcl will run it as a Tcl script.

File->Exit

After prompting if you are sure, exits the GUI. Note that in general the server continues to run and you can connect to it again later with a new GUI instance. For Rustogramer, see, however File->Stop Histogramer below.

File->Stop Histogramer

This is only available if the server is Rustogramer. After prompting if you are sure, requests the histogramer to exit. Once the histogram responds that it is exiting, the GUI exits as well.

The Data Source Menu

The data source menu allows you to attach data sources of various sorts to the histogram server. Some source types are not (yet?) available to Rustogramer.

• Online (SpecTcl only) Select an NSCLDAQ helper (e.g. rinselector) and take data from an online system.
• File Take data from a file. Note that as of SpecTcl version 5.13-002, SpecTcl can analyze data from a parameter file prepared for Rustogramer as well as from raw event files.
• Pipe (SpecTcl only) Read data from an arbitrary helper program.
• Cluster File (SpecTcl 5.14 and later only) Use a file to drive analysis from several event files.
• Filter file (SpecTcl only) take data from a filter file.
• Detach Stop analyzing data from the current data source.
• Abort Cluster File (SpecTcl only) abort an in progress cluster file.

Notes on cluster file processing. The SpecTcl REST handlers to support cluster files (added in SpecTcl 5.14) depend on software that is part of the Tree GUI to function. cluster file processing may fail in the server if the tree GUi is not being used.

Data Source->Online (SpecTcl Only)

The Data Source->Online menu command allows you to get data from an online data source. Really this is just the same as a Pipe data source (see Data Source->Pipe below), however additional options are automatically added to the helper program by the GUI. These options make the attachment suitable for online data taking by ensuring the server does not limit the data flow if its analysis cannot keep up with the data rates.

WHen you select this option, you will see the following dialog:

In the input edit line labeled Ring Buffer URL enter the URL of the ring buffer from which the server's helper should get data. This is of the form tcp://hostname/ringname where

• hostname is the DNS name or IP address of the system from which you wish to get data.
• ringname is the name of the ringbuffer in that system.

In the input edit line with the Browse... button to the right of it, find the name of the helper progam. For NSCLDAQ, this is the ringselector program in the bin director of the version of NSCLDAQ you are using. When starting the pipe data source, the GUI will automatically add appropriate options and values. For example, suppose you selected /usr/opt/daq/12.1-000/bin/ringselector as the helper program. The full command line that the GUI will specify for the helper for the ring tcp:///spdaq49/e1400x is:

/usr/opt/daq/12.1-000/bin/ringselector ---source=tcp://spdaq49/e1400x \\
    --sample=PHYSICS_EVENT \
    --non-blocking```

Finally, select the radio button that corresponds to he format of the data you are analyzing. This is the format of the NSCLDAQ program that generates data in the ringbuffer. Normally, this will be the version of NSCLDAQ that the readout programs were built under.

Data Source->File

Initiates analysis of data from either a raw event file or a parameter file. Note that rustogramer can only analyze data from parameter files. SpecTcl, with an appropriate analysis pipeline can analyze data from either.

You will first be prompted for an event or parameter file. Once that has been selected, you'll be asked to provide the version of NSCLDAQ the data are in via this prompter:

Once that is selected the server will start analyzing data from that file.

Data Source->Pipe (SpecTcl Only)

Pipe data sources allow the server to take data from the stdout of any program. This is actually how Data Source->Online works. One example of how you can use this; After performing your experiment, you could use e.g. gzip to compress all of your event files. If you then analyze event files by using gzcat as a pipe data source, you could analyze data without actually every having the uncompressed event files on disk. Since, in general, I/O is quite a bit slower than Disk I/O doing this might very well be faster than analyzing the raw event data, once you've paid the computational price of compressing the data in the first place.

When you select Data Source->Pipe you will be greeted with the following dialog:

The Program line edit and its accompanying Browse... button allow you to enter the program to use as the pipe data source.

The Entry and editable list box below it allow you to provide an ordered set of parameters to the pipe program. Finally the radio buttons at the bottom of the dialog allow you to select thd format of the NSCLDAQ data you are analyzing. Clicking the Ok button commences analysis from that pipe data source.

Data Source->Cluster File (SpecTcl Only)

Cluster file processing is not yet implemented in the GUI see issue #168

Data Source->Filter file... (SpecTcl Only)

A filter file is a file written by SpecTcl that is very much like a parameter file. Filter files contain a subset of the parameters for a subset of events that have made a condition true. Filter files and how to make them are described in The SpecTcl User guide. See the chapters named:

• Using event filters
• Analyzing filter files

Before attempting to analyze a filter file, be sure your SpecTcl analysis pipeline is properly configured to do so. Filter files have the following advantages over parameter files

• They can be written from SpecTcl without any additional code.
• They can be used as the first stage of the analysis pipeline allowing additional stages to follow.

Because you must take special care to ensure the version of SpecTcl you are running has been prepared to analyze filter data, the first time you select Data Source->Filter file you'll be prompted with a reminder that you must have the correctly tailored version of SpecTcl running.

The GUI simply prompts for a filter file and, when one is selected from a standard file chooser dialog, analysis from that file begins.

Data Source->Detach

Stops analysis of the current data source and detaches from it.

Data Source->Abort Cluster File (SpecTcl Only)

Cluster file processing is not yet implemented in the GUI see #168

The Filters Menu (SpecTcl Only).

As we have described in our documentation of the Data Source->Filter file menu SpecTcl an write filtered event data files. See that section for more information about what filter files are and pointers to SpecTcl documentation on filter files. The Filters menu provides:

• The ability to create filters via a filter wizard.
• The ability to control which filters are enabled; enabled filters write data.
• Another menu entry to attach a filter file for analyais.

Note again, that these menu entries are only available with SpecTcl and on rustogramer, the Filter menu itself will ont be present.

Filter->Filter Wizard

Creating a filter is a multi-step process. The filter wizard leads you through the process of:

• Naming the filter
• Selecting, if desired, a gate to determine which events are written to the filter file.
• Choosing the parameters to write for each event that makes the gate true.
• Choosing the file to which filter data will be written and whether the filter should be created enabled.

The next subsections will look at each of these steps, showing you the Wizard GUI for each step:

Naming the filter.

THe firs step of the filter wizard:

Describes the process of making a filter and presents you with an editable text input in which you can type the filter's name. Filter names must be unique.

When you are satisfied with your filter name, click the Next > button.

Selecting the filter gate

A filter is gated. Only events that make the filter true are written to the output file. This allows you to do things like write only events with a specific particle ID for example. The second stage of the filter wizard prompts you for a filter gate:

Select a gate from the pull down:

• If you've updated the gates your gate may not be visible. Clicking the Update Gate list button, will then update the list of gates that populate the gate chooser pull-down.
• If you want all events to be written, create and select a True gate as the filter gate.

When you hvae the desired gate selected, click the Next > Button.

Selecting the parameters to output.

Only a subset of parameters need to be written to filter files. The next stop provides a parameter chooser/editable list to allow you to choose the parameters you want output:

Improvements to this stage of the GUI are planned see Issue #169 for more information. When the parameters you want written are all in the editable list box, click the Next > button to advance to the last stage of the wizard.

Choosing the output file.

The final step of the filter creation process is to specify where the filtered data will be written and, optionally to enable the filter.

Only enabled filters will actually write data.

Filter->Enable/Disable Filters

This menu entry allows you to enable and disable filters. It brings up this dialog:

The table has a line per filter. The left column are filter names and the right columns checkboxes. Check the boxes for the filters you want enbled then click the Ok button to apply your selections.

Filter->Read Filter Files

This menu command allows you to attach a filter file. THe mechanics of this are described in the Data Source Menu.

The Spectra Menu

Many of the items on the Spectra menu are available on the Spectra tab and File menu. THey are grouped here to make it unecessary to switch tabs to access them:

• Save spectrum contents.
• Read spectrum file
• Clear All
• Create
• Delete
• Apply Gate

Save Spectrum Contents.

This allows you to save the contents of one or more spectra to file. See The file menu for a description of the user interface behind this.

Read Spectrum File

Allows you to read a file that contains the contents of one or more spectra. See The file maneu for a description of the user interface behind this.

Clear all

Clears the contents of all spectra. All spectrum channels are set to zero.

Create

Allows you to create one or more spectra. The spectrum editor tabbed widget is displayed. When you are done creating the spectra you want, click Ok to dismiss the dialog. A section of the Spectra Tab page describes how to use the spectrum editors

Delete

Allows you to delete one or more spectra. You can select the spectra to delete using:

Simply select spectra (you can select more than one at a time). And click the > button to add it to the editable list box. When the listbox contains the spectra you want to delete; click Ok to delete those spectra.

Improvements are planned to the spectrum selection see issue #170

You can achieve the same effect in the Spectra tab using the Delete Button on the Spectra tab button bar after selecting the spectra you want deleted from the spectrum listing in that tab.

Apply Gate

Allows you to apply a gate/condition to one or more spectra;

Select the condition on the left and select however many spectra you want (selections need not be contiguous) on the right and click Ok to apply the gate to the selected spectra.

The Gate Menu

Allows you to perform the folowing operations on gates.

• Create one or more gates
• Apply a gate to one or more spectra.
• Delete a gate.

Create gates

Selecting this brings up the tabbed window of the gate editors:

Use it to create as many gates as you want then dismiss it with the Ok button. See the various gate editor descriptions in the Gate Tab documentation

Apply gate

This functionality is the same as that in the Spectrum menu

Delete gate

Allows you to delete one or more gates.

Simply select the gates you wish to delete from the list in the dialog above and click Okto delete them.

Chapter 5 - Using CutiePie to display histograms

The Cutie Pie Displayer uses the spectrum shared memory mirroring capability of SpecTcl and Rustogramer as well as the REST interface to allow you to display and interact with the histograms produced by both programs. CutiePie can run in both Linux and Windows, bringing, along with rustogramer, fully functional histograming to the Windows desktop.

At the FRIB, the standalon CutiePie will normally be installed in /usr/opt/cutiepie/x.y-nnn where x.y.nnn is the version of CutiePie. To run Cutiepie assuming you have defined the environment variable CUTIETOP to point at this directory:

$CUTIETOP/bin/CutiePie

In Windows, typically CutiePie is installed in C:\CutiePie and you can start it via

\CutiePie\bin\cutiepie

Naturally, in windows, you can make a desktop shortcut.

When Cutiepie is running, Use it's Connect button to connect it to SpecTcl or Rustogramer. Note that due to differences in how shared memory and mirroring works between Linux and Windows, you cannot mix environments. You can only:

1. Run native Windows CutiePie with native Windows Rustogramer.
2. Run Linux/WSL CutiePie with Linux/WSL Rustogramer or SpecTcl.

For CutiePie user documentation see The FRIB documentation page on CutiePie

Chapter 6 - the REST interface

Rustogramer has no interactive interface baked into it. It does provide a REST-like interface/API to which user interface programs can use. There are two language bindings to this interface:

• Tcl which you can use to create/port GUIs using Tcl/Tk
• Python which also includes a sample fully featured GUI

To be clear, these are client side APIs. If you are interested in contributing a binding for another language, here is documentation for tha requests and responses

Tcl REST interface

Two Tcl packages get installed with Rustogramer.

• On Windows these are installed in %RUSTOGRAMER%\restclients\tcl where %RUSTOGRAMER% is that directory you gaven to the installer.bat file.
• On Linux these are installed in $dest/share/restclients/Tcl where $dest is the install directory you gave install.sh

These are ports of the SpecTcl REST client software and retain those names:

• SpecTclRESTClient is a package that provides low level REST request/response using the response formats created by both SpecTcl and Rustogramer.
• SpecTclRestCommand is a package that provides most of the Tcl command extensions that SpecTcl creates, however implemented over the REST interface. This can be used as a tool to port existing SpecTcl Tcl/Tk based GUIs.

In addition, the program rusttcl.tcl in that directory provides a script that you can use to run a Tcl shell that talks to rustogramer (well SpecTcl too for that matter).

Setting up the packages for use.

There are two ways to setup any Tcl package for use:

• Defining the environment variable TCLLIBPATH to include the directory tree that includes the package (e.g. /usr/opt/rustogramer/restclients/tcl on linux).
• Manually adding the package directory tree to the Tcl auto_path variable.

Suppose you have a script that defined the variable tclrest_dir to point to the directory that includes the Tcl Rest clients:

lappend auto_path $tclrest_dir

will add those packages to the package search path used by the package require command.

How to create an environment variable depends on your environment. This addition to your .bashrc can add $tclrest_dir to that variable in Linux:

export TCLIBPATH="$TCLLIBPATH $tclrest_dir

In Windows it's probably best to very carefully add this to the registery. Start regedit and navigate to HKEY_CURRENT_USER\Environment Choose Edit->New expandable string value Enter the name TCLLIBPATH and the value the path to your the restclients\tcl directory.

Using The low level client.

Once you are set up to add the package path for the Tcl REST clients to your scripts. You can use the low leve client. See the Tcl REST reference for reference material. In this section we're just going to give a brief overview of the package and how to use it.

The Tcl low level client is implemented in an object oriented manner. You instantiate a client object and then issue it subcommands to get the server to do things. It's important to note that the client does not attempt to connect with the server until it is asked to interact with it and each interaction, therefore involes a new connection to the server.

Here's a very brief example of how all this works.

#    Somewhere above tclrest_dir was defined to point to the package directory.

lappend auto_path $tclrest_dir
package rquire SpecTclRESTClient;      # 1



set host locallhost;    # Modify if needed.
set port 8000;          # Modify if needed.         2
set debug 0;            # nonzero to enable debugging output.

set client [SpecTclRestClient %AUTO% -host $host -port $port -debug $debug]; # 3

# Let's see who we're talking to:

set versionInfo [$client version];   # 4

#  Major and minor and editlevel are always present. program_name was added last time:

if {[dict exists $versionInfo program_name]} {;     # 5
    set name [dict get $versionInfo program_name]
} else {
    set name *unknown*
}

set major [dict get $versionInfo major]
set minor [dict get $versionInfo minor]
set edit  [dict get $versionInfo editLevel];     # 6
puts "Connected to $name"
puts "Version $major.$minor-$edit"

Refer to the numbered comments above when reading the remarks below

1. Loads the Rest low level package.
2. These define the connection parameters for the client. Note that the client can run in debugging mode, in which case, it output information about the requests it makes and the responses it got. To run in debug mode set the debug variable to some non-zero value.
3. This creates a client object using our connection parameters. Note that the first paramter to the instance creation command is the name of a command ensemble that will be created (command ensembles are commands that have subcommands). The special name %AUTO% will create a unique command name. I recommned using %AUTO% to avoid colliding with other commands. The name of the command is stored in the client variable.
4. This is the first (and only) interaction with the server. The version subcommand requests the server identify itself and its current version number. The resulting information is stored in the dict versionInfo
5. Originally, when there was only SpecTcl, the only information returned was the major and minor versions and the edit lievel. When rustogramer's Rest interface was written it, and later SpecTcl added the program_name key. This block of code determines if the returned inforation has the program_name key and, if so, sets the value of name to it. Otherwise, the value of name is set to *unknown*
6. The version information is pulled out of the dict and finally everything is printed.

Using the high level client.

The high level client implements much of the SpecTcl command set on top of the low level Tcl REST client. To use it you must:

1. Pull the SpecTclRestCommand package into your script.
2. Provide the connection parameters to SpecTclRest package.
3. Use SpecTcl commands as you might normally do.

Here's a sample script to provide the version of the server and a list of the tree parameters and their metadata:

...
#   some where above tclrest_dir is defined as the path to the package directory.

lappend auto_path $tlclrest_dir
package require SpecTclRestCommand

set host localhost
set port 8000

SpecTclRestCommand::initialize $host $port;   # 1

puts "SpecTcl/Rustogramer version [version]" ;  # 2


#   3

foreach param [treeparameter -list] {
    set name [lindex $param 0]
    set bins [lindex $param 1]
    set low  [lindex $param 2];         # 4
    set high [lindex $param 3]
    set units [lindex $param 5]

    puts "Name: $name  recommended axis: \[$low - $high\]$units $bins bins";  # 5
}

As before we assume that somewhere above the script shown, the script defines tclrest_dir to point to the package installation directory.

1. The SpecTclRestCommand::initialize command sets the connection parameters for the pacakge. The parameters correspond in turn to the -host and -port option values to the constructor for the SZpecTclRestClient described in the previous section. Note that a third optional parameter, which defaults to 0 is used as the value for the -debug option. This allows you to run the high level package with debugging output enabled on the low level package.
2. The version command in SpecTcl and the SpecTclRestCommand package provides the version of the histogramer. This line simply outputs it.
3. The loop below iterates over the output of the treeparameter -list command. This command, in SpecTcl and the SpecTclRestCommand package provides a list of information about parmeters and their metadata. A REST endpoint is also defined for rustogramer that is identical to the one provided by SpecTcl that provides the same information for all parameters it knows about (you can think of all Rustogramer parameters as treeparameters in the SpecTcl sense of the word).
4. Each element of the list returned by treeparameter -list provides the following information:
   • The name of the parameter.
   • The number of bins recommended for axes on the parameter.
   • The suggested axis low limit for the parameter.
   • The suggested axis high limit for the parameter.
   • The width of an axis bin if the suggested limits and bin count are used. We don't pull this out of the lst.
   • The units of measure for the parameter.
5. This line just outputs the information we extracted about the tree parameter.

The main point to take awayh from this example is that once you've pulled in the SpecTclRestCommand package and initialized it withthe connection parameters, you can treat your script as if it was running natively in SpecTcl (even if the server is Rustogramer) with the command descdribed in the SpecTcl Command Reference all defined.

Python REST interface

They Python Rest interface provides an API and a sample GUI based on the capabilities of the SpecTcl Tree GUi for Rustogramer and SpecTcl. We have already described the use of the GUI in Using the Rustogramer GUI. Refer back there for very detailed documentation.

This section is intended to get users started that want to write their own Python applications for Rustogramer or SpecTcl.

To use the REST API you must:

• Add the package directory to the Python import path.
• Import tha rustogramer_client package in your Python script.
• Instantiate a rustogramer_client.rustogramer object with the connection parameters set to allow it to connect to the server.
• Make requests through the object you created in the previous step.

Note that failed requests will raise a rustogramer_client.RustogramerException which is derived from the standard Python Exception base class. Normally, the only exceptions you will see are those that heppen when the server has exited (remember each REST request forms and destroys a new connection to the server).

Extending the import path and importing the module

In python there are two ways to extend the built-in module search path:

1. Define the environment variable PYTHONPATH to be colon separated set of paths in which modules can be found.
2. Appending paths to the sys.path variable.

Note that in both Linux and Windows envirionments the Unix path separator (/) is acceptable and should be preferred.

My preference is to extend sys.path as it's less error prone.

Let's assume that there's an environment variable called RUSTOGRAMER_TOP that is pointing to the directory in which rustogramer was installed. In Linux,

$RUSTOGRAMER_TOP/share/restclients/Python

points to the Python Rest client directory while on Windows:

%RUSTOGRAMER_TOP%/restclients/Python

Points to the package.

Supposing that RUSTOGRAMER_TOP is defined here's a bit of scriptery that will extend the search path irregardless of the environment and import the rustogramer_client package

import sys     # 1
import os

if sys.platform == 'linux':                                            # 2
    suffix = os.path.join('share', 'restclients', 'Python')
elif sys.platform == 'win32':
    suffix = os.path.join('restclients', 'Python')
else:
    print("Error - unsupported os:", sys.platform)                     # 3
    exit()

rust_top = os.getenv('RUSTOGRAMER_TOP')                                # 4
if rust_top is None:
    print('Error - you must define the "RUSTOGRAMER_TOP" environment variable')
    exit()

module_path = os.path.join(rust_top, suffix)                         # 5
sys.path.append(module_path)

import rustogramer_client

Sample Script.

In the exmaple below, we create a rustogramer client object and get the version of the histogramer that is running:

import sys
import os
def extend_path():                      
    if sys.platform == 'linux':                                            
        suffix = os.path.join('share', 'restclients', 'Python')
    elif sys.platform == 'win32':
        suffix = os.path.join('restclients', 'Python')
    else:
        print("Error - unsupported os:", sys.platform)                     
        exit()

    rust_top = os.getenv('RUSTOGRAMER_TOP')                               
    if rust_top is None:
        print('Error - you must define the "RUSTOGRAMER_TOP" environment variable')
        exit()

    module_path = os.path.join(rust_top, suffix)                                                        
    sys.path.append(module_path)


if __name__ == '__main__':
    extend_path()                       # 1
    from rustogramer_client import rustogramer, RustogramerException  # 2

    host = 'localhost'     # 3
    port=  8000

    try:                                                          # 4
        client = rustogramer({'host'=host, 'port'= port})         # 5
        versionInfo = client.get_version()                        # 6

        major = versionInfo['major']
        minor = versionInfo['minor']
        edit  = versionInfo['editLevel]
        if 'program_name' in versionInfo.keys():                 # 7
            name = versionInfo['program_name']
        else:
            name = '*unknown*'
        
        print('Runing program: ', name, 'Version', f'{}.{}-{}', major, minor, edit) # 8
    except RustogramerException as e:
        print("An operation failed", e)                          # 9
        exit()

1. We've extracted the program fragment that shows how to extend the import path from the previous section into the function extedn_path here we call that in the main program.
2. This imports the names we need from the rustogramer_client module.
3. These are the connection parameters we will use.
4. Our code all runs in a try block so that we can catch any exceptions raised by the client object, output them and exit. If you want a bit more error granularity, you can encapsulate each client request in a try/except block, however that can make the code look a bit unwieldy.
5. This creates a client object. The client supports both hard-coded ports an service lookup. That's why the parameter to its constructor is a dict. If you want to do service lookup, instead of providing the 'port' key, provide the 'service', 'pmanport' and optionally the 'user' keys to fully specify the service and how to contact the port manager ('pmanport' should normally be 30000)
6. We ask the client to request and return the version of the server. The returned value for all requests is a dict with keys that are specific to each request. In this case we will have the following keys:
   • 'major' - the program major version.
   • 'minor' - the program minor version.
   • 'editLevel' - the version's edit level.
   • 'program_name' Rustogramer will always provide this but older versions of SpecTcl will not. If provided it is the name of the server program.
7. This section of code unpacks the version bits and pieces and the program name, providing the default value of *unknown* if the server did not provide it.
8. Print out the program and version information.
9. If a RustogramerException was raised this code is executed to print out the reason for the exception and exit the program (presumably in a real program there might be more code to follow.)

Chapter 7 - Reference material

This chapter contains reference material:

• Rustogramer command line options
• REST requests and responses
• Tcl REST API reference
• Python REST API reference
• Pointer to the Rustogramer internals documentation
• GUI configurationfile schema
• Schema of JSON Spectrum contents files

Command Line Options

Rustogramer command line options

Rustogramer supports a few command line arguments. These arguments are inthe form of options that have a long form and, in some cases a short form. Many options also have default values:

If you run rustogramer with the --help option (e.g. on linux /usr/opt/rustogramer/bin/rustogramer --help) you will get a summary of the command line options.

• --shm-mbytes (short form -s) the value of this option is the number of megabytes of shared spectrum memory that will be created by rustoramer when it starts up. The default value is 32 (32 Megabytes). The maximum value is system dependent. Rustogramer creates the shared memory using mmap backed up ordinary files. This was, as near as I could tell, the only portable shared memory interface between windows and Linux. If rustogramer exits cleanly (you tell it to exit using the GUI e.g.) these files get cleaned up by rustogramer. If not, they are in the home directory on Linux and \Users\username on Windows where username is your windows username. They will have names like .tmp6chars where 6chars means 6 random characters. Note as well that in addition to the requested spectrum memory size, rustogramer will allocate a significant amount of additional storage for spectrum descsriptions. If your home directory is in a file system with quotas enforced, you'll need to have sufficient free quota to create these files.
• --rest-port (short form -r) the value of this option is the port on which rustogramer's REST server will listen for connections. The default value of this option is 8000. Where possible, you are encouraged to use the --rest-service option instead.
• --rest-service - provides a service name which Rustogramer will advertise with the NSCLDAQ port manager. If the NSCLDAQ port manager is not running; rustogramer will fail. There is no short form and no default for this option.
• ---mirror-port - The value of this option is the port on wich rustogramer's mirror server will listen. This has no short form and defaults to 8001 though again, where possible, you are encouraged to use --mirror-service (see below).
• --mirror-service - The value of this option is the service name that rustogramer will use to advertise the mirror servers. This has no default.

Examples, assuming rustogramer is in the path:

rustogramer  --shm-mbytes 100 --rest-service RUSTO_REST --mirror-service RUSTO_MIRROR

rustogramer --rest-port 10000 --mirror-port 10001 -s 128

GUI Command line options.

The GUI allows you to specify command line options that control how it connects to Rustogramer or SpecTcl. These have short forms and long forms and, in some cases, default values. The --help option will display a summary of the options e.g.

/usr/opt/rustogramer/bin/gui --help

• --host (short option -H) the value of this option is the host in which rustogramer or SpecTcl are running.
• --port (Short option -p), the value of this option is the numeric port on which rustogramer or SpecTcl is listening for REST requests. Default is 8000
• --service (Short option -s) the service on which the REST server of rustogramer or SpecTcl has advertised with the NSCLDAQ port manager if that's how it got its server port.
• --user (short option -u) Username under which Rustogramer/SpecTcl is running. This is only needed if you are using the --service option to translate the port. This defaults to your logged in user name.

Examples (assuming the gui is in the path):

gui --host localhost --service RUSTO_REST
gui --host localhost --port 8000

REST requests and responses

REST Requests look like URLs sent to a webserver with query parameters (in fact they are URLs sent to a web server). Rustogramer's REST requests/responses were patterned after SpecTcl's. Therefore all requests use URLs of the form:

http://hostname:rest-port/spectcl/...

where

• hostname - is of course the host in which the rustogramer REST server is running.
• port - is the port on which the rustogramer REST server is listening for connections
• spectcl is the fixed string spectcl and
• ... is the remainder of the URL.

The remainder of the URL are divided into functional categories, for exmaple

http://hostname:rest-port/spectcl/spectrum/...

requests manipulate spectra.

The number of request families is large. Refer to the sidebar table of contents to home in on a particular family.

Pre-requisites to understand this reference section:

• You should understand the form of Uniform Resource Identifiers URIs; specifically query parameters and how to format them.
• You should be able to read simple Java Script Object Notation (JSON) objects.

Other notes:

• The client, when making requests of SpecTcl must be able to accept data with Content-Encoding: deflate as this is used in the resonses to the spectrum/contents request.

Response format

The response bodies from the server for requests are in Java Script Object Notation or JSON.

There are several libraries for various programing languages that support decoding JSON. These are installed at the FRIB:

• C++ - libjson-cpp can generate as well as decode JSON.
• Tcl - The tcllib json package the companion json::write package is used by SpecTcl to generate responses.
• Python - The requests package is a package that can make HTTP requests and decode the resulting response data from Json to Dicts.
• Rust - The serde framework provides a framework for seralizing and de-serializing structs to various format using drivers specific to that format. Rustogramer uses the JSON driver embedded in the Rocket HTTPD framework to generate responses and to decode them in its unit tests for the REST server. If you want a standalone JSON decoder you might, instead want the Serde JSON package which can be added to your program as shown on that page.

The JSON language docs pointed to above, describes JSON as a set of name/value pairs, where the values can be scalars, arrays or structs (which themselves are name value pairs). We're going to call the names keys for simplicity as most JSON Parsers really don't expose the order of the names to you.

The overarching structure for the REST responses is a struct with two fields whos keys are:

• status - Provides a human readable string that is status of the request as processed by a valid URL handler. If this value is OK the request completed successfully. If not its value will be a string containing a human readable error message.
• detail - If status was OK, this contains data that depends on the actual request. The value may be a string, a struct or an array. Read the individual request documentation for information about the shape of the value for this key.

The simplest response type is a struct where the detail fields is a string. Here, for example is a response from the /spectcl/attach/list request:

{
    "status" : "OK",
    "detail" : "Test Data Source"
}

As you can see, the requrest succeeded and the detail key provides the information requested, in this case information about the data source attached to SpecTcl.

This response is used enough times that it has been given a name: It is referred to in the documentation as a gheneric response. If a page describing a request says that it returns a generic response the struture above is what to expect.

Here is a simple example where the detail value is a bit more complex; a structure. This is the response to the /spectcl/version request:

{
    "status" : "OK",
    "detail" : {
        "major"        : 5,
        "minor"        : 14,
        "editlevel"    : "000",
        "program_name" : "SpecTcl"
    }
}

Again, the status field says that the request succeeded and the detail provides several fields identified by the keys major, minor, editlevel and program_name which provide the desired information.

Here is an example of a generic response from a /spectcl/paramter/create?name=event.raw.00 requets that completed in error:

{
    "status" : "'treeparameter -create' failed: ",
    "detail" : "event.raw.00 is already a treeparameter.  Duplicates are not allowed"
}

Where a generic response is used, error information usually uses the detail field to provide additional information about the error. In this case you can see that the SpecTcl treeparameter -create command executed by the REST handler failed and the reason it failed was that there was already a parameter named event.raw.00 defined.

parameter requests

The base URI for these, after the protocol//host:port stuff is /spectcl/parameter Several operations are supported on parameters:

• /list - lists the parameters and their properties.
• /edit - Modifies the metadata associated with a parameter.
• /promote - Promote a raw parameter to a tree parameter.
• /create - Create a new parameter (Rustogramer only)
• /listnew - lists parameters that have modified metadata.
• /check - Checks the modified state of parameters.
• /uncheck - Turns off the modified state of parameters.
• /version - Provides version information about the capabilities of the parameter system (earlier versions of the SpecTcl treeparameter did not support the -create operation).

/spectcl/parameter/list

Lists the parameters that are defined along with their metadata

Query parameters

• filter (optional) if provided the value of this query parameter is a patter that must be matched by the parameter name in order for it to appear in the response. The filter string can include filesystem matching wild-card characters (e.g. * or .). If the filter query parameter is not supplied, it will default to * which will match all parameters.

Reponse format detail

The detail field of the response is a possibly empty array of parameter descriptions. Each parameter description is, itself, a struct. It is not an error for the filter string not to match any parameters. That case results in an OK status with an empty array as the detail

Each parameter description is a struct with the following keys:

• name - Name of the parameter being described.
• id - An integer id that is assigned to the parameter. The id is used in the histograming engine to specify the parameter.
• bins - Suggested binning for axes that are defined on the parameter.
• low - Suggested low limit for axes that are defined on the parameter.
• hi - Suggested high limit for axes that are defined on the parameter.
• units - Units of measure for the parameter (these are for documentation purposes only).
• description - (Rustogramer only) A description that documents the parameter purpose. In SpecTcl, this field is missing.

Sample Responses.

A single parameter matches the filter.

{
  "status" : "OK",
  "detail" : [{
      "name"        : "event.sum",
      "id"          : 10,
      "bins"        : 100,
      "low"         : 1,
      "hi"          : 100,
      "units"       : "arbitrary",
      "description" : "Sum over the arraay event.raw.nn"
  }]
}

Here is what you will get if your filter does not match any parameters

{
  "status" : "OK",
  "detail" : []
}

Note how the detail field is just an empty array.

/spectcl/parameter/edit

This request lets you modify the metadata associated with a parameter.

Query parameters

• name (Required string) - Name of the parameter to modify.
• low (Optional float) New value for the suggested axis low limit.
• high (Optional float) New value for the suggested axis high limit.
• bins (Optional unsigned integer) New value for the suggested axis binning.
• units (Optional string) New value for the parameters units of measure.
• description (Optional string -ignored by SpeTcl) - A description that documents the purpose of the parameter

Reponse format detail

• Rustogramer returns a generic response. SpecTcl, returns only a status on success, but the detail field is present on error. Rustogramer always returns a detail field and on success it is an empty string.

Sample Responses.

Successful return (Rustogramer):

{
    "status" : "OK",
    "detail" : ""
}

Successful return (SpecTcl)

{
    "status" : "OK"
}

Failure return for both Rustogramer and SpecTcl

{
    "status" : "not found",
    "detail" : "event.raw"
}

/spectcl/parameter/promote

In SpecTcl, there is a distinction between parameters with metadata (tree parameters) and parameters without metadata (raw parameters). In Rustogramer all parameters have metadata. For

• Rustogramer - this is equivalent to the /spectcl/parameter/edit operation.
• SpecTcl - this makes a treeparameter from a raw parameter.

Query parameters

• name (required String) - Name of the parameter to promote.
• bins (required for SpecTcl, optional for Rustogramer unsigned int) - The recommended bins for the promoted parameter.
• low (required for SpecTcl, optional for Rustogramer float) - The recommended low value for the promoted parameter.
• high (required for SpecTcl, optional for Rustogramer float) - The new high value for the promoted parameter.
• units (optional string) - Units of measure string for the promoted parameter.
• description (Rustogramer only String) - New desciption for the parameter

Reponse format detail

The response is a Generic response.

Sample Responses.

Note again that SpecTcl may omit the detail field on success:

{
    "status" : "already treeparameter"
}

Here's an error respons:

{
    "status" : "already treeparameter",
    "detail" : "event.raw.00"
}

Here the detail is used to indicate which parameter was involved in the error

/spectcl/parameter/create

Creatse a new tree parameter in SpecTcl or an ordinary parameter in Rustogramer. The parameter must not yet exist.

Note that with SpecTcl this is a front end to the treeparameter -create command.

Query parameters

• name (Required string) - Name of the parameter to create.
• low (Required for SpecTcl optional for Rustogramer float) - parameter's low limit metadata.
• high (Required for SpecTcl optional for Rustogramer float) - parameter's high limit metadata.
• units (Optional string) - parameter's units of measure metadata (defaults to "" for SpecTcl)
• description (Optional Rustogramer only string) desription metadata for the parameter.

Reponse format detail

Generic response where again, SpecTcl might omit the detail field on success. THe detail filed is used on failure to supply additional information for the failure reason.

Sample Responses.

Successful creation:

{
    "status" : "OK"
}

Failure in Spectcl:

{
    "status" : "'treeparameter -create' failed: ",
    "detail" : "Could not parse  as type double\nUsage:\n     treeparameter -list ?pattern?\n     treeparameter -listnew\n     treeparameter -set name bins low high inc units\n     treeparameter -setinc name inc\n     treeparameter -setbins name bins\n     treeparameter -setunit name units\n     treeparameter -setlimits name low high\n     treeparameter -check name\n     treeparameter -uncheck name\n     treeparameter -create  name low high bins units\n     treeparameter -version"
}

Note how the detail field just contains the error message directly from the treeparameter -create command.

/spectcl/parameter/listnew

Query parameters

None.

Reponse format detail

detail is an array of names of parameters that wre created since the start of the run. Note that this is really only implemented in SpecTcl. In Rustogramer, this will be an empty array.

Sample Responses.

SpecTcl response:

{
    "status" : "OK",
    "detail" : ["george"]
}

The parameter george was created.

/spectcl/parameter/check

SpecTcl has a modification flag associated with each tree parameter. The check flag is set if the parameter's metadta are modified. This determines if that parameter has the check flag set.

Query parameters

• name (required string) - Name of the parameter to check on.

Reponse format detail

• detail is an integer which is 0 if the check flag is not set and nonzero if it is.

Sample Responses.

Found the parameter but its check flag is clear:

{
    "status" : "OK",
    "detail" : 0
}

Nte that rustogramer will always have a detail = 0.

No such parameter (SpecTcl)

{
    "status" : "'treeparameter -check failed: ",
    "detail" : "Could not find parameter event.raw.000"
}

Note that in SpecTcl, detail is a string that describes why the request failed in detail. For Rustogramer, in case of failure, the detail string is None

/spectcl/parameter/uncheck

Sets the check flag for a parameter to 0. This is implemented in Rustogramer but, unlike SpecTcl, has no effect

Query parameters

• name (Required string) - Name of the parameter to unceck.

Reponse format detail

A generic response. For SpecTcl, on success, this is only the status field, and the request never fails. For Rustogramer; detail field is null

Sample Responses.

Sample successful completion:

{
    "status" : "OK",
    "detail" : null
}

/spectcl/parameter/version

Reports the version of the tree paramter subsystem.

Query parameters

None

Reponse format detail

Generic response with the stringified version number in the detail field

Sample Responses.

{ 
    "status" : "OK", 
    "detail" : "2.1" 
}

/spectcl/rawparameter requests

For Rustogramer, the requests in this URI domain map to similar requests in the /spectcl/parameter domain. For SpecTcl, however for historical reasons, there is a difference between a raw parameter and a tree parameter.

Originally tree parameters were a contributed package written by Daniel Bazin. Later, due to its utility, tree parameters were incorporated into supported SpecTcl code. However a distinction does exist, internally between tree parameters and the original raw parameters, which may not be mapped to tree paramters.

In SpecTcl, therefor, these URIs manipulate raw parameters without affecting any tree parameters that might be bound to them.

The requests include:

• /spectcl/rawparameter/new (Rustogramer maps this to /spectcl/parameter/create). SpecTcl creates a new raw parameter.
• /spectcl/rawparameter/delete (Rustogramer implements this). This deletes an existing (raw) parameter.
• /spectcl/rawparameter/list (Rustogramer maps this to spectcl/parameter/list)

/spectcl/rawparameter/new

Creates a new raw parameter. Note that in Rustogramer, this is forwarded to the handler for /spectcl/parameter/new. Refer to that documentation. This section documents how this URI is implemented for SpecTcl.

Query parameters

• name (required string) - Name of the parameter to be created. The value of this parameter must not be the name of an existing parameter,
• number (required in SpecTcl unsigned integer) - The parameter id to be assigned to the parameter.
• resolution (optional unsigned integer) - Number of bits of resolution in the metadata for the raw parameter.
• low, high (optional floats) - Low and high limits for parameter values.
• units (optional string) - Units of measure metadata.

Response format detail

On success, this just has status with the value OK . On failure detail provides more information about the error.

Sample Responses.

Successful completion:

{
    "status" : "OK"
}

Attempt to redefine a parameter:

{
    "status" : "'parameter -new' command failed",
    "detail" : "Duplicate Key during Dictionary insertion\nKey was:  event.raw.00 Id was: -undefined-\n"
}

detail is the error message from parameter -new in this case it indicates that event.raw.00 already exists and the request is attemptig to find it.

/spectcl/rawparameter/delete

Deletes a raw parameter.

Query parameters

One of the following parameters must be present, but not both.

• name (string) - Name of the parameter to delete.
• id (unsigned integer) - Number of the parameter to delete

Response format detail

The response is a generic response, whith SpecTcl omitting detail if the operation succeded.

Sample Responses.

Successful request:

{
    "status" : "OK"
}

Delete a nonexistent parameter:

{
    "status" : "'parameter -delete' command failed",
    "detail" : "Failed search of dictionary by Key string\nKey was:  aaaa Id was: -undefined-\n"
}

/spectcl/rawparameter/list

Lists the raw parameters with names matching a pattern or a specific id.

Query parameters

One of the following are required

• pattern (string) pattern used to match the parameter names that will be listed. The pattern can contain any filename matching wild cards supported by the shell.
• id (unsigned integer) Number of the paramter to list.

Response format detail

On success, detail is an array of structs. Each struct has the fields:

• name - name of the parameter being described.
• id - Id of the parameter.
• resolution - Only present if the raw parameter has a resolution set. The integer resolution.
• low high - Only present if the raw parameter has low/high limits. These are the floating point low and high limits.
• units - Only present if the raw parameter has units of measure. This is the units string.

Sample Responses.

Successful return with one match event.sum

{ 
    "status" : "OK", 
    "detail" : [
        { 
            "name" : "event.sum", 
            "id" : 10, 
            "units" : "arbitrary" 
        }
    ] 
}

/spectcl/gate requests

The /spectcl/gate domain or URIs provides the ability to manipulate gates (rustogramer conditions).

URIs include:

• /spectcl/gate/list - lists defined conditions.
• /spectcl/gate/delete - Delets a condition
• /spectcl/gate/edit - Create or modify a condition.

/spectcl/gate/list

Returns a list of gates with names that match an optional pattern.

Query parameters

• pattern (optional string) If not supplied this defaults to * which matches all names. The pattern can use any filesystem wild-card characters and patterns.

Response format detail

The detail of the response is a bit complex. It consists of an array of structs. Some struct fields are gate type dependent and, for SpecTcl unecessary fields are not present while for rustogramer all fields are present but the unecessary fields have the value null

Each struct has the following fields.

• name (String) - Always present. This is the name of the condition/gate
• type (String) - Always present. The gate type string. See the SpecTcl command reference for gate for the possible values and meanings of this string.
• gates (Array of Strings) - Present only for compound conditions/gates (e.g. and or an d not).
• parameters (Array of Strings) - Present only for conditions/gates that depend on parameters (for example, and not limitied to slice or contour). This is a list of the parameter names the condition/gate depends on.
• points (Array of Point structs ) - Present only for conditions/gates that represent geometric shapes in two dimensional parameter space (for example, but not limited to slice or contour). These are the points that make up the shape. Each point, itself, is a struct made up of.
  • x - (float) the x coordinate of the point.
  • y - (float) the y coordinate of the point.
• low - (float) Present only for conditions/gates that are a one-dimensional slice in parameter space. This is the low limit of that slice.
• high - (float) Present only for conditions/gates that are a one-dimensional slice in parameter space. This is the high limit of that slice.

Sample Responses.

Here is a response that shows pretty much all of the gate struct types (from SpecTcl so unused fields are omitted - had this come from Rustogramer, unused fields would be null):

{
    "status" : "OK",
    "detail" : [{
        "name"       : "acontour",
        "type"       : "c",
        "parameters" : ["event.raw.00","event.raw.01"],
        "points"     : [{
            "x" : 398.316437,
            "y" : 458.697357
        },{
            "x" : 206.994919,
            "y" : 138.077942
        },{
            "x" : 647.967651,
            "y" : 77.811142
        },{
            "x" : 845.511047,
            "y" : 302.003662
        },{
            "x" : 710.186035,
            "y" : 550.302917
        }]
    },{
        "name"  : "anand",
        "type"  : "*",
        "gates" : ["acontour","anot"]
    },{
        "name"  : "anot",
        "type"  : "-",
        "gates" : ["aslice"]
    },{
        "name"       : "aslice",
        "type"       : "s",
        "parameters" : ["event.raw.00"],
        "low"        : 330.595703,
        "high"       : 674.400635
    }]
}

• acontour is a contour and therefore has points. Note that the points are in parameter space defined by X=event.raw.00 and Y=event.raw.01
• aslice is a slice gate and therefore has low and high
• anot is a not gate and therefore has gates with a single gate name, the name of the gate it negates.
• anand is an And gate which also has gates, in this case both acontour and anot must be true (the inverse of aslice) for the condition to be true.

Another important note; The order in which the conditions are listed should not be assumed. While SpecTcl will, in general list the conditions alphabetically by name, Rustogramer will list them at random. In particular this means that, in order to reconstruct the gates, they must be re-ordered in dependency order (you can't make anand until acontour and anot have been defined and you can't make anot until aslice is defined).

/spectcl/gate/delete

Deletes a condition. Note that while rustogramer actually delete conditions, SpecTcl modifies them into False conditions.

Query parameters

• name (String) this mandatory parameter is the name of the condition to delete.

Response format detail

A generic response.

Sample Responses.

Successful condition deletion:

{
    "status" : "OK"
}

Where Rustogramer's response will include an empty detail field. Note that since SpecTcl just replaces deleted gates with a False gate it is legal to delete a "deleted" gate. That is an error in Rustogramer, however.

Attempting to delete a nonexistent gate anando generates the following in SPecTcl

{
    "status" : "not found",
    "detail" : "anando"
}

In rustogramer you'll get:

{
    "status" : "Failed to delete condition anando",
    "detail" : "anando"
}

/spectcl/gate/edit

Creates a new condition/gate or edits an existing one. These two operations are functionalyly identical. If the condition specified in the query parameters for this request already exists, it is replaced. If not, it is created.

Note that condition replacement is dynamic. Spectra that gave this condition applied to them as gates have their gating modified to reflect the new condition definition on the next event processed.

Query parameters

• name (String) - Mandatory specifies the name of the condition/gate being edited.
• type (String) - mandatory specifies the type of condition/gate being edited. See the SpecTcl command reference for gate for the possible values and meanings of this string.
• gate (Multiple String) - This is required for conditions that depend on other conditions. It should be presenet once for each dependent condition. For example:
  .../spectcl/gate/edit?name=anand&type=*&gate=g1&gate=g2&gate=g3
  is how to specify an and gate named anand that depends on the gates g1, g2 and g3
• xparameter (String) - Mandatory for two dimensional geometric shape gates in parameter space. The parameter on the X axis of the condition/gates space.
• yparameter (String) - Mandatory for two dimensional geometric shape gates in parameter space. The parameter on the Y axis of the condition/gates space.
• parameter (String) - Mandaatory for slice (s type) and for conditions with multiple unorderd parameters, for example gamma slices (gs) or gamma contours (gc). This can be specified as many times as needed to supply all parameters. For examle the gamma contour depending on p1, p2, p3 would be something like:<br'> .../spectdl/gate/edit?name=gamma-contour&type=gc&parameter=p1&parameter=p2&parameter=p3...
• xcoord (float) - mandatory for 2d geometric gates (e.g. contours c). This is the X-coordinate of a gate point. specify this as many times as needed. To specify an ordered set of x-coordinates.
• ycoord (float) - mandatory for 2d geometric gates (e.g. contours c). This is the X-coordinate of a gate point. specify this as many times as needed. To specify an ordered set of x-coordinates. Here, for example, is a definition of a contour that is a right triangle:
  

.../spectcl/gate/edit?name=contour&type=c&xparameter=p1&yparameter=p2&xcoord=100&ycoord=100&xcoord=200&ycoord=100&xcoord=200&ycoord=200

• low (float) - mandatory for slice like gates (e.g. ``sandgs```); The low limit of the condition.
• high (float) - mandatory for slice like gates; the high limit of the conditions.
• value (integer) - For SpecTcl mask gates, this is the mask value.

Response format detail

The response is a generic response.

Sample Responses.

Successful gate creation in SpecTcl:

{
    "status" : "OK"
}

Rustogramer will include an empty detail field as well.

Failed gate creation - type parameter omitted (SpecTcl):

{
    "status" : "missing Parameter",
    "detail" : "type"
}

Note that the REST server in Rustogramer does some pre-processing and will fail to match a URI that does not include both a name and a type

However detailed error messages will be in the status field for rustogramer. Suppose, for example, you try to create a not codition without supplying a dependent gate:

{
    "status" : "Not conditions can have at most one dependent condition",
    "detail" : ""
}

Will be returned.

/spectcl/spectrum

Requests from this domain manipulate spectra defined in Rustogramer (and SpecTcl). The URI's in this domain are:

• /spectcl/spectrum/list List spectra.
• /spectcl/spectrum/delete Delete an existing spectrum.
• /spectcl/spectrum/create Create a new spectrum.
• /spectcl/spectrum/contents Get the contents (channel values) of a spectrum.
• /spectcl/spectrum/zero Clear the contents of spectra.

/spectcl/spectrum/list

Lists the properties of one or more spectra.

Query parameters

• filter (String) - optional parameter to limit the listing to onliy spectra with names that match the pattern specified by this parameter. The pattern can include any of the bash filesystem matching characters such as * and ?.

Response format detail

The response detail will be an array of spectrum definition structs.

Fields in the response detail are:

• id (unsigned int) - Always present. An integer spectrum id. This has more meaning in SpecTcl than it does for Rustogramer.
• name (string) - Always present, the name of the spectrum.
• type (string) - always present, the spectrum type. See the spectrum command in the SpecTcl command reference for the valid spectrum type strings.
• parameters (array of strings) - Always present. The list of parameters the spectrum dependson on. With the exception of gd spectra, it is possible to determine which parameters are x and which are y. In SpecTcl 5.14, the following fields were added that rustogramer has always had, to make determination simpler.
• xparameters (array of strings) - Always present. List of x axis parameters.
• yparameters (array of strings) - Always present. List of y axis parameters.
• axes (array of axis definitions) - This is always present. It is usually simple to figure out which axes are which, however xaxis and yaxis were added for simplicity in SpecTcl 5.14 and were always provided in Rustogramer. Each axis is a struct that contains the following fields:
  • low (float) axis low limit.
  • high (float) axis high limit.
  • bins (unsigned integer) NUmber of bins on the axis.
• xaxis (axis definition) - X axis specification.
• yaxis (axis definition) - Y axis definition. This is meaningless if there's no meaningful Y axis for the spectrum. Note that summary spetctra have a Y axis that the user defines and an X axis that is determined by the number of parameters.
• chantype (string) - Channel type string. For SpecTcl see the spectrum command in the SpecTcl command reference for the valid channel type strings. Rustogramer adds the channel type f64 which means that channel values are 64 bit floats.
• gate (String) - Present when the spectrum is gated (note that in SpecTcl, spectra start out gated on a True gate named -TRUE-).

Sample Responses.

Here's what a 1-d spectrum loosk like (SpecTcl):

{
    "status" : "OK",
    "detail" : [{
        "name"        : "raw.00",
        "type"        : "1",
        "parameters"  : ["event.raw.00"],
        "xparameters" : ["event.raw.00"],
        "yparameters" : [],
        "axes"        : [{
            "low"  : 0.000000,
            "high" : 1024.000000,
            "bins" : 1024
        }],
        "xaxis"       : {
            "low"  : 0.000000,
            "high" : 1024.000000,
            "bins" : 1024
        },
        "yaxis"       : {
            "low"  : 0,
            "high" : 0,
            "bins" : 0
        },
        "chantype"    : "long",
        "gate"        : "-TRUE-"
    }]
}

For Rustogramer the gate and yaxis values will be null and the chantype will be f64

Here's a 2d word spectrum (SpecTcl):

{
    "status" : "OK",
    "detail" : [{
        "name"        : "raw",
        "type"        : "2",
        "parameters"  : ["event.raw.00","event.raw.01"],
        "xparameters" : ["event.raw.00"],
        "yparameters" : ["event.raw.01"],
        "axes"        : [{
            "low"  : 0.000000,
            "high" : 1024.000000,
            "bins" : 512
        },{
            "low"  : 0.000000,
            "high" : 1024.000000,
            "bins" : 512
        }],
        "xaxis"       : {
            "low"  : 0.000000,
            "high" : 1024.000000,
            "bins" : 512
        },
        "yaxis"       : {
            "low"  : 0.000000,
            "high" : 1024.000000,
            "bins" : 512
        },
        "chantype"    : "word",
        "gate"        : "-TRUE-"
    }]
}

/spectcl/spectrum/delete

Allows you to delete an existing spectrum.

Query parameters

• name (string) this mandatory parameter is the name of the spectrum to try to delete.

Response format detail

The response type is a generic response.

Sample Responses.

Successful deleteion (SpecTcl)

{
    "status" : "OK"
}

Rustogramer will include an empty detail string field.

Attempt to delete a spectrum that does not exist (SpecTcl):

{
    "status" : "not foUNd",
    "detail" : "raw"
}

For rustogramer this will look more like:

{
    "status" : "Failed to delete raw",
    "detail" : "Some reason for the failure"
}

/spectcl/spectrum/create

Allows you to create new spectra.

Query parameters

As this was one of the first URI families to be implemented in SpecTcl, some of the query parameters are a bit oddly formatted. You will need to understand the format of Tcl lists to understand how the query parameters work.

• name Name of the spectrum you want to create.
• parameters Tcl Lists of parameters in the form expected by the SpecTcl spectrum command described in the SpecTcl command reference.
• axes Tcl lists of axis definitions as described in the spectrum command section of the he SpecTcl command reference
• chantype Channel type (required by SpecTcl, ignored by rustogramer who's channel typ e is alays f64). For SpecTcl channel types again, see the spectrumcommand desribed in the he SpecTcl command reference.

This is a confusing enough description that I'll give a couple of URI examples for spectrum defintions; a 1d and a 2d spectrum

Sample URI for creating a 1d spectrum.

.../spectcl//spectrum/create?name=test&type=1&parameters=event.raw.00&axes={0%201024%201024}

Note that the string %20 is the URL escape for an ASCII space character.

Sample URI for creating a 2d spectrum

http://localhost:8000/spectcl//spectrum/create?name=test2&type=2&parameters=event.raw.00%20event.raw.01&axes={0%201024%201024}%20{0%201024%201024}

Again, the string %20 is the URI escape for an ASCII Space character.

Response format detail

This request produces a generic response

Sample Responses.

Successful detail from SpecTcl:

{
    "status" : "OK"
}

where Rustogramer will add a detail field with an empty string.

Failure for duplicate spectrum name (SpecTcl):

{
    "status" : "command failed",
    "detail" : "Duplicate Key during Dictionary insertion\nKey was:  test2 Id was: -undefined-\n"
}

Note that the detail is the same as the error message produced by the SpecTcl spectrum command.

/spectcl/spectrum/contents

Retrieves the contents of a spectrum. SpecTcl only allows the retrieval of the entire spectrum while rustogramer supports returning only the data within a region of intersst.

Query parameters

• name (string) required name of the spectrum to fetch.

If you want to get data only within a region of interest from a 1-d spectrum, you must also add:

• xlow (float) - low limit of the region of interest.
• xhigh (float) - high limit of the region of interest.

For 2-d spectra, the region of interest is a rectangle defined by xlow, xhigh and

• ylow (float) - Low limit of the y axis of the region of interest.
• yhigh (float) - High limit of the y axis of the region of interest.

Response format detail

Detail is a struct:

• statistics* is a structure that provides information aobut the spectrum over/underflows:
  • xunderflow (unsigned) - the number of underlows in the X direction.
  • yoverflow (unsigned) - The number of overflows in the x direction.
  • yunderflow (unsigned) - If present, the number of undeflows in the Y direction. For rustogramer e.g. 1-d spectrum this will be null. For SpecTcl this will be missing.
  • yunverflow (unsigned) - if present, the number of overflows in the y direction.
• channels (array of Channel structs) Each element represents a channel with non-zero counts and contains:
  • x (float) - the X bin number of the channel.
  • y (float) - the Y bin number of the channel (meaningless for e.g. 1d spectra). Note that SpecTcl can omit this.
  • v (float) - number of counts in the bin.

Note: Rustogramer does not (yet) implement gettin gthe Statistics information. As such, the x under/overflows will always be zero and the y over/underflows will be null

Sample Responses.

Empty 1d spectrum from SpecTcl:

{
    "status" : "OK",
    "detail" : {
        "statistics" : {
            "xunderflow" : 0,
            "xoverflow"  : 0
        },
        "channels"   : []
    }
}

From Rustogramer, there will also be yunderflow and yoverflow fields in statistics with null values.

1d spectrum with counts (from SpecTcl) excerpt:

{
    "status" : "OK",
    "detail" : {
        "statistics" : {
            "xunderflow" : 0,
            "xoverflow"  : 1
        },
        "channels"   : [{
            "x" : 52,
            "v" : 1
        },{
            "x" : 61,
            "v" : 1
        },{
            "x" : 66,
            "v" : 1
        },{
            "x" : 75,
            "v" : 1
        },{
            "x" : 77,
            "v" : 1
        },{
            "x" : 79,
            "v" : 1
        }
        ...
        ]
    }
}

Excerpt of a 2d spectrum (from SpecTcl):

{
    "status" : "OK",
    "detail" : {
        "statistics" : {
            "xunderflow" : 0,
            "xoverflow"  : 0
        },
        "channels"   : [{
            "x" : 1,
            "v" : 1
        },{
            "x" : 28,
            "v" : 1
        },{
            "x" : 31,
            "v" : 1
        },{
            "x" : 36,
            "v" : 1
        },{
            "x" : 47,
            "v" : 1
        },{
            "x" : 56,
            "v" : 1
        },{
            "x" : 64,
            "v" : 1
        }
        ...
    }
}

/spectcl/spectrum/zero

Allows you to clear one or more spectra.

Query parameters

• pattern optional pattern. If supplied all spectra that match that glob pattern will be cleared. If not provided the default value of * clears all spectra.

Response format detail

The response is a generic response.

Sample Responses.

{
    "status" : "OK",
    "detail" : ""
}

/spectcl/attach

This set of URIs manipulates the attachment of a data source to the server. The following URIs are provided:

• /spectcl/attach/attach attaches a data source to the server. Note that any previously attached source is detached.
• /spectcl/attach/list describes the data source attached tot he server.
• /spectcl/attach/detach detaches the current data source.

/spectcl/attach/attach

Attaches a new data source to the server. The server detaches any previously attached data source.

Query parameters

• type Type of data source to attach. This can be one of:
  • pipe (only supported by SpecTcl) data comes from a program started on the other end of a pipe. The program must emit data to stdout
  • file (supported by both) data is read from a file.
• source Specifies the data source. This depends on the data source type:
  • pipe A string containing the program and its arguments. For example suppose you are attaching gzcat to uncompress a file named ./events.gz this would be gzcat ./events.gz
  • file Path to the file to attach e.g. ./run-0000-00.evt
• size optional size of reads done from the data source. This defaults to 8192 if not provided. Rustogramer ignores this but SpecTcl honors it.

Response format detail

A Generic response is returned.

Sample Responses.

Success:

{
    "status" : "OK",
    "detail" : ""
    
}

Failure:

{
    "status" : "attach command failed",
    "detail" : "No such file or directory"
}

/spectcl/attach/list

Queries what is attached to the server.

Query parameters

No query parameters are supported/required

Response format detail

A generic repsonse. This always has status=OK

Sample Responses.

Attached to a file:

{
    "status" : "OK",
    "detail" : "File: run-0001-00.evt"
}

/spectcl/attach/detach

This method is only supported by Rustogramer. It detaches the data source.

Query parameters

None supported.

Response format detail

A generic response.

Sample Responses.

Success:

{
    "status" : "OK",
    "detail" : ""
    
}

/spectcl/analyze

This family of URIs control data analysis.

• /spectcl/analyze/start Starts analysis
• /spectcl/analyze/stop Stops analysis
• /spectcl/analyze/size Sets the event chunksize for Rustogramer.

/spectcl/analyze/start

Begins analyzing the attached data source.

Query parameters

None supported

Response format detail

Generic response. SpecTcl always returns an OK status but Rustogramer has a few possibilities.

/spectcl/analyze/stop

Query parameters

None

Response format detail

Genric response.

Sample Responses.

One possible error case is that analysis is not active. Here's a SpecTcl return for that:

{
    "status" : "'stop' command failed",
    "detail" : "Run is already halted"
}

/spectcl/analyze/size

Only supported by rustoramer. Rustogramer is a highly threaded program. During analysis, a reader thread reads data from the data source passing it on to a histograming thread. Data communication is via Rust channels. This URI allows you to set the number of events in a batch sent between the reader and histogramer.

Query parameters

• size - Number of events in a chunk.

Response format detail

Generic responses.

/spectcl/apply requests

Conditions are only useful when applied to a spectrum. When a condition/gate is applied to a spectrum it is said to gate that spectrum. This means that for events, which normally could increment the histogram, that increment will only occur if the gate is satisfied (the condition is true for that event).

The /spectcl/apply domain of URIs allow you to apply unapply and list applications:

• /spectcl/apply/apply - Applies a gate/condition to one or more spectra.
• /spectcl/apply/list - Produces a list of gates applied to spectra.
• /spectcl/ungate - Removes any gate a spectrum has.

/spectcl/apply/apply

Applies a gate to one or more spectra.

Query parameters

• gate - Name of the gate to apply.
• spectrum A spectrum to apply the gate to. In rustogramer, this can appear more than once; e.g. ../spectcl/apply?gate=agate&spectrum=larry&spectrum=moe&spectrum=curly applies the gate agate to the spectra larry, curly and moe

Response format detail

Generic rsponse

/spectcl/apply/list

List the gates applied to spectra.

Query parameters

• pattern - glob pattern that, filters the listing to only contain spectra that match the pattern. If not supplied defaults to * and all spectra are listed.

Response format detail

The detail is a vector of structs with the fields:

• spectrum - name of a spectrum.
• gate - Name of the gate applied to the spectrum.

In SpecTcl, spectra are always gated. When reated they are gated by the -TRUE- gate which is always true. In Rustogramer, spectra can be ungated in which case the gate field is null

Sample Responses.

{
    "status" : "OK",
    "detail" : [{
        "spectrum" : "raw.00",
        "gate"     : "-TRUE-"
    }]
}

This represents an ungated spectrum.

/spectcl/ungate

Removes the gate from one or more spectra.

Note that in Rustogramer spectra can exist without gates. In SpecTcl, all spectra are gated and this operation gates the specrat with the -Ungated- gate which is a True gate.

Query parameters

• name name of a spectrum to ungate. This parameter an appear more than once and allows you to ungate more than one spectrum.

Response format detail

Generic response

Sample Responses.

Here's an error return from SpecTcl attempting to ungate a spectrum event.raw.00 that dos not exist:

{
  "status": "'ungate' command failed",
  "detail": "{event.raw.00 {Failed search of dictionary by Key string\nKey was:  event.raw.00 Id was: -undefined-\n}}"
}

/spectcl/ungate requests

See the apply documentation

/spectcl/channel requests

The requests in this domain support accessing single channels of a spectrum:

• /spectcl/channel/set allows you to set the value of a channel.
• /spectcl/channel/get provides the value of a channel

/spectcl/channel/set

Sets the value of a single bin/channel in a spectrum.

Query parameters

• spectrum (string) - mandatory parameter that provides the name of the spectrum ot modify.
• xchannel (unsigned) - mandatory parameter that provides the bin on the X axis to set.
• ychannel (unsigned) - optional parameter that provides the bin on the Y axis to set for spectra with X and Y axes. For spectra without a Y bin axis, this can be omitted.
• value (float) - mandatory paramter that provides the new value for the channel.

Response format detail

The response is a generic respones.

Sample Responses.

Successful return:

{
    "status":"OK",
    "detail":""
}

Failure (no such spectrum):

{
    "status":"Unable to set channel: ",
    "detail":"No such spectrum: araw.04"
}

Failure (bad channel number):

{
    "status":"Unable to set channel: ",
    "detail":"X index is out of range"
}

/spectcl/channel/get

Returns the value of a channel of a spectrum.

Query parameters

• spectrum (string) - mandatory parameter that provides the name of the spectrum ot modify.
• xchannel (unsigned) - mandatory parameter that provides the bin on the X axis to set.
• ychannel (unsigned) - optional parameter that provides the bin on the Y axis to set for spectra with X and Y axes. For spectra without a Y bin axis, this can be omitted.

Response format detail

The detail of this request, on success, is a floating point value (generally the float is a valid unsigned integer).

Sample Responses.

Succes:

{
    "status":"OK",
    "detail":1234.0
}

Failure (bad channel):

{
    "status":"Could not get channel: X index is out of range",
    "detail":0.0
}

While this shows the detail field to be zero, you should not rely on that. If status is not OK you must ignore the detail field.

Failure (no such spectrum):

{
    "status":"Could not get channel: No such spectrum 'araw.04'",
    "detail":0.0
}

/spectcl/evbunpack requests

This domain of URIs is only available in SpecTcl. It works with the dynamic event processing pipeline to configure an event processor that can be used with data that was emitted from the FRIB/NSCLDAQ event builder. The idea is that you can use the pipline manager to create event processing pipelines which you then associated with specific source ids using this set of URIs.

Operations supported are:

• /spectcl/evbunpack/create - Creating an event processor with pipeline slots for source ids.
• /spectcl/evbunpack/add - Associate an existing event processing pipeline with an source id.
• /spectcl/evbunpack/list - list the event builder event processors that have been created by this command.

For more information and background, see the evbunpack command in the SpecTcl command reference

/spectcl/evbunpack/create

Creates a new event unpacker for event built data. You can think of the unpacker as having a slot for each possible source id. Initially, all slots are empty. Note that this operation creates and registers an event processor. Such event processors can be put into pipelines just like any other event processor.

Query parameters

All parameters are mandatory

• *name (string) - name of the event processing pipeline. This must be unique.
• frequency (float) - Clock frequency of the timestamp. This is used to create event builder diagnostic parameters. The value of this parameter are in units of floating point MHz. For examle 16.5 means 16.5MHz.
• basename (string) - Provides a basename for the diagnostic parameters. For more information aobut the diagnostic parameters; see the documentation of CEventBuilterEventProcessor in the SpecTcl Programming Reference.

Response format detail

The response is a generic response

Sample Responses.

Successful resopnse:

{
    "status": "OK"
}

/spectcl/evbunpack/add

Associates an exiting, registered event processor with a source-id. Events with fragments that match the source id will invoke that pipeline, passed the fragment's payload.

Query parameters

All parameters are mandatory.

• evpname (string) - Name of an event processor made via e.g. /spectcl/evbunpack/create.
• source (unsigned) - Source id that will be associated with the next parameter.
• pipe (string) - Name of a registered event processor that will be run to process fragments from source in each event. Note this is a badly named parameter.

Response format detail

The response is a generic response. On failure, the status contains evbunpack addprocessor command failed with detail set to the error message from that command.

Sample Responses.

Success:

{
    "status": "OK"
}

/spectcl/evbunpack/list

Returns a list of event processors that are evbunpack event processors.

Query parameters

• pattern (string) - Optional glob pattern that filters out the list to only those names which match the pattern.

Response format detail

The detail is an array of strings. Each element is the name of an event builder unpacker.

Sample Responses.

Success:

{
    "status" : "OK",
    "detail" : [
        "s800",
        "lenda",
        "greta"
    ]
}

/spectcl/filter requests

SpecTcl filters output a reduced data set given an input set. The output set is self-descsribing and can contain a limited parameters set as well as events that only make a specific gate true.

This domain of URIs is only supported by SpecTcl. If attempted with Rustogramer, Generic responses of the form:

{
    "status" : "/spectcl/filter/<specific> is not implemented",
    "detail" : "This is not SpecTcl"
}

Are returned where <specific> is the specific request and is one of:

• new - Which SpecTcl uses to create a new filter.
• delete - which delets an existing filter.
• enable - which enables an existing filter to write it's subset of data for future events.
• disable - which disables an existing filter so that it will no longher write events.
• regate - which associates a different gate with an existing filter, changing the subset of events that will be written by the filter (when enabled).
• file - Which specifies a file on which filtered data will be written.
• list - which lists filters and their properties.
• format - which specifies an output format for a filter.

This family of URIs is a front end to the SpecTcl filter command documented in the SpecTcl command reference

/spectcl/filter/new

Creates a new filter. The filter is not associated with a file and cannot be enabled until it is.

Query parameters

• name (string) - Mandatory Name to be given to the new filter.
• gate (string) - name of a gate that will select the events the filter will write whne it is enabled.
• parameter (string) - In general this occurs several times, once for each parameter you wish written by the filter.

For example:

.../spectcl/filter/create?name=afilter&gate=alpha&parameter=alpha.energy&parameter=alpha.theta&parameter=alphas.phi&parameter=total.energy

Attempts to create a filter named afilter that will write events that make alpha true and will write the parameters alpha.energy, alpha.theta, alpha.phi and total.energy

Response format detail

The response is a generic respones.

Sample Responses.

Succesful request:

{
    "status" : "ok"
}

Request that is missing a gate:

{
    "status" : "Missing required query parameter: ",
    "detail" : "gate"
}

/spectcl/filter/delete

Deletes a filter. Any open filter file is flushed and closed.

Query parameters

• name (string) - Mandatory name of a filter to delete.

Response format detail

Rsponses are generic responses.

Sample Responses.

Successful completion:

{
    "status" : "OK"
}

Failure:

{
    "status" :  "'filter -delete' command failed",
    "detail" : "<error message from the fileter -delete command>"
}

## /spectcl/filter/enable

Enable a filter.   Note that the filter must have a file associated with it for this to succeed.  Filters are created in the disabled state.  Once enabled, on subsequent events that make their gates true, they will write filtered data to file.

### Query parameters

* **name** (string) - mandtory filter name.

### Response format detail

Response is a generic response.


#### Sample Responses.

Success:
```json
{
    "status" : "OK"
}

Falure form:

{
    "status" : "'filter -enable' command failed" 
    "detail" : "<Error message from SpecTcl filter commnand>"
}

/spectcl/filter/enable

Enables a filter to write events. Once a file has been associated with a filter it can be enabled to write events to that file. See also /disable

Query parameters

• name (string) - mandatory parameter - the name of the filter to enable.

Response format detail

Generic response.

Sample Responses.

Success:

{
    "status" : "OK"
}

Failure:

{
    "status" : "'filter command' command failed" ,
    "detail" : "<error message from filter command>"
}

/spectcl/filter/disable

THe filter specified flushes any buffered data to its output file; and no longer writes data unless it is later enabled without changing the output file.

Query parameters

• name (string) - mandatory parameter specifies the filter.

Response format detail

Generic format.

Sample Responses.

Success:

{
    "status" : "OK"
}

Failure:

{
    "status" : "'filter -disable' command failed" ,
    "detail" : "<error message from filter command>"
}

/spectcl/filter/regate

Changes the gate that determines which event are written to the filter. Note as well that the filter will also dynamically reflects edits to its gate.

Query parameters

• name (string) - mandatory parameter that specifies the filter to modify.
• gate (string) - mandatory parameter that specifies a new gate for the filter. While odd, it is not an error to specify the current gate.

Response format detail

Generic reply.

Sample Responses.

Success:

{
    "status" : "OK"
}

Failure:

{
    "status" : "'filter -regate' command failed" ,
    "detail" : "<error message from filter command>"
}

/spectcl/filter/file

Sets the filter output file. Note that any existing file is first closed.

Query parameters

• name (string) - mandatory name of the filter.
• file (string) - mandatory path to the new output file:
  • file is interpreted by SpecTcl an therefore must be a valid file path in the context of the server.
  • If file exists, it will be ovewritten.
  • A file must have been specified for a filter for it to be legally enabled.

Response format detail

Generic response.

Sample Responses.

Success:

{
    "status" : "OK"
}

Failure:

{
    "status" : "'filter -file' command failed" ,
    "detail" : "<error message from filter command>"
}

/spectcl/filter/list

Lists filters and their properties.

Query parameters

• pattern (string) - Optional glob pattern. Only filters with names that match pattern will be included in the listing. If omitted the pattern defaults to * which matches all filters.

Response format detail

detail is an array of objects. The objects have the followig fields:

• name (string) - Name of the filter being desribed.
• gate (string) - Name of the gate applied to the filter.
• file (string) - File to which the filter writes its events. This could be an empty string if the filters is not yet associated with a file.
• parameters (array of strings) - Name of the parameters written to the filter for each event it writes.
• enabled (string) - Either enabled or disabled depending on the filter enabled status.
• format (string) - The format with which the filter is written. See format for more information about this.

Sample Responses.

Success - with a single filter:

{
    "status" : "OK",
    "detail" : [
        {
            "name" : "afilter",
            "gate" : "agate",
            "file" : "/home/ron/filterile.flt",
            "parameters" : [
                "param1",
                "param2",
                "param3"
            ],
            "enabled": "enabled",
            "format" : "xdr"
        }
    ]
}

This can only fail if pattern is an illegal glob pattern.

/spectcl/filter/format

Sets the format of the filter output. By default this is xdr, which is the built in filter file format. The set of filter file formats can be extended. This is described in the section Extending SpecTcl's filter file format in the SpecTcl Programming Guide.

The format of the built in xdr filter format is described here. Scroll down to the section Structure of a Filtered event file.

Query parameters

• name (string) - mandatory name of the filter to modify.
• format (string) - mandatory format selector.

Response format detail

This is a Generic response.

Sample Responses.

Success:

{
    "status": "OK"
}

Failure:

{
    "status" : "'filter -format' command failed" ,
    "detail" : "<error message from filter command>"
}

/spectcl/fit requests

This is only avaialble with SpecTcl. SpecTcl supports fitting regions of interest on 1-d spectra. The actual fit function used can be extended, however linear and gaussian. Note that gaussian performs a gaussian fit on a constant background.

See the SpecTcl command reference for information about the fit command. The set of fits is extensible by the user. See the section "Extending the set of SpecTcl fit types in the SpecTcl programming guide

The /spectcl/fit domain of URIs provides the following operations:

• /spectcl/fit/create - create a new SpecTcl fit object.
• /spectcl/fit/update - Computes fit parameter values on current histogram data.
• /spectcl/fit/delete - Delete a spectcl fit object.
• /spectcl/fit/list - List one or more fits providing each fit's current function parameterization.
• /spectcl/fit/proc - Returns a Tcl proc that can be used to evaluate the fit at any point.

/spectcl/fit/create

Creates a new fit object. Fit object, once created, can be updated, which causes them to compute/recompute their parameterizations, which can the be fetched via the list operation.

Query parameters

• name (string) - mandatory name to associate with the fit object.
• spectrum (string) - mandatory name of a spectrum that only has an X paramter axis (e.g. a 1d or gamma 1d spectrum).
• low (unsigned integer) - mandatory low limit in channels of the region of interest.
• high (unsigned integer) - mandatory high limit in channels of the region of interest.
• type (string) - Fit type string, e.g. gaussian

Response format detail

The response is a Generic response.

Sample Responses.

Success:

{
    "status" : "OK"
}

Failure:

{
    "status" : "'fit'command failed: ",
    "detail" : "<error message from the fit command>"
}

/spectcl/fit/update

Performs fits an updates the paramterization of the fit functionss stored in the update. This computes the parameterization of the fit functions on current data. Prior to its first update, the parameterization is whatever values the author of that fit type chose and, in general, is not meaningful.

Query parameters

• pattern (string) - Glob pattern. Only fits with names that match the pattern are pdated.

Response format detail

Response is a generic response.

Sample Responses.

On Success:

{
    "status" : "OK"
}

On Failure:

 {
    "status": "'fit'command failed: ",
    "detail": "<Error message from the fit command>"

 }

## /spectcl/fit/delete

Deletes a single named fit object.

### Query parameters

* **name** - name of the fit to delete.

### Response format detail

The response is a generic response.

#### Sample Responses.

On Success:

```json
{
    "status" : "OK"
}

On Failure:

{
    "status" : "'fit'command failed: ",
    "detail" : "<Error returned from the fit command>"
}

/spectcl/fit/list

Lists a set of fits. When fits are listed the fit function parameters as of the most recent /update are also listed.

Query parameters

• pattern (string) - (optional) Restricts the listed fits to only those that match the glob pattern provided.

Response format detail

The detail is an array of objects. Each object describes a fit that was done and contains the fields:

• name (string) - Name of the fit being described.
• spectrum (string) name of the spectrum the fit is defined on
• type (string) - fit type (e.g. gaussian).
• low (unsigned) - Low bin of the area of interest.
• high (unsigned) - High bin of the area of interest.
• parameters (Object) - the shape of this object depends on the type of fit. Fields of this object are the most recently computed fit parameters. See the fit command in the SpecTcl command reference for the fields for each of the built-int fit types. The fields provided by user written fits depend on the author of the fit type support. All fit types should provide a chisquare field which holds the goodness of fit.

Sample Responses.

Successful list where a single gaussian fit is matched to pattern:

{
    "status" : "OK",
    "detail" : [
        {
            "name" : "agaussianfit",
            "spectrum" : "aspectrum",
            "type" : "gaussian",
            "low" : 100,
            "high" : 300,
            "parameters" :  {
               "baseline" : 127,
               "height"   : 1234.7,
               "centroid" : 207.6,
               "sigma"    : 12.7,
               "chisquare" : 15.766
            }
        }
    ]
}

Note the parameters are just pulled out of the air and do not relflect any actual fit.

spectcl/fit/proc

Given a fit, provides a Tcl proc that can be given channel numbers (floating point) and return to value of the fit at that channel.

Query parameters

• name - name of the fit.

Response format detail

A generic response is produced however detail is the text of a Tcl proc.

Sample Responses.

Suppose we have a linear fit, what you might get back is:

{
    "status" : "OK",
    "detail" : "proc fitline x {   \nset slope 2.7\nset offset 362.6\nreturn [expr {$x*$slope+$offset}]\n}"
}

/spectcl/fold requests

The /spectcl/fold request domain creates and manipulates folds. Folds are used in γ-ray spectroscopy to untangle decay chains. SpecTcl and Rustogramer both support multiply-incremented spectrum types that are tailored for these sorts of experiments.

The Rustogramer mutiply-incremented 1-d/SpecTcl g1 spectrum can be used with an array of γ detectors; incremented for each γ ray detected by the array. In decay cascades, if fully captured, each decay will increment the spectrum. A decay chain will result in a set of correlated increments.

A fold is like a conditiont that, when applied to a g1 spectrum, will increment all hits that are not in the condition. Suppose, therefore, that you know the peak that corresponds to one of the decays in the sequential decay. If you set a condition (slice) around that peak and apply that as a fold, and gate the spectrum on that condition as well, the spectrum will only show peaks that are in coincidence with the peak used to fold the spectrum. These are the other decays in the sequential decay chain.

The following operations are defined on folds:

• /spectcl/fold/apply - Apply a condition as a fold to a spectrum
• /spectcl/fold/list - List the folds.
• /spectcl/fold/remove - Remove a fold.

/spectcl/fold/apply

Apply a fold to a spectrum. Note that folds can only be applied to an appropriate spectrum type.

Query parameters

• gate (string) - Mandatory name of the condition/gate to use as a fold.
• spectrum (string) - Mandatory name of the spectrum to fold with this gate.

Response format detail

The response is a generic response.

Sample Responses.

Success:

{
    "status": "OK"
}

Failure (Spectcl):

{
    "status": "'fold -apply' command failed",
    "detail": "<erorr message from fold -apply>"
}

Failure (Rustogramer):

{
    "status": "Could not fold spectrum",
    "detail": "<why the fold failed>"
}

/spectcl/fold/list

List the folds that are applied to spectra.

Query parameters

• pattern (string) - optional glob pattern to filter the listing to only spectra with names that match the pattern. If omitted, the pattern defaults to * which matches all spectra.

Response format detail

The detail is a vector of objects. Each object has the following attributes:

• spectrum (string) - the name of a spectrum.
• gate (string) - the fold applied to the spectrum.

Note that the listing will only contain spectra that match the pattern and have a fold applied.

Sample Responses.

Success with a spectrum named gamma folded on a condition named peak and no other folded spectra that match whatever the pattern was:

{
    "status" : "OK",
    "detail" : [
        {
            "spectrum" : "gamma",
            "gate"     : "peak"
        }
    ]
}

/spectcl/fold/remove

Removes a fold applied to a spectrum.

Query parameters

• spectrum (string) Mandatory name of the spetrum that will have folds removed.

Response format detail

The response is a generic response

Sample Responses.

Sucess:

{
    "status": "OK"
}

Failure (SpecTcl)

{
    "status" : "'fold -remove' command failed: ",
    "detail" : "<fold -removce error message>"
}

Failure (Rustogramer)

{
    "status" : "Failed to remove fold",
    "detail" : <reason the fold could not be removed>"
}

/spectcl/integrate requests

This request allows you to integrate regions of interest on 1-d or 2-d spectra.

/spectcl/integrate

Request the integraion. The region of interest can be specfied:

• 1-d spectrum :
  • as a low/high pair of floats.
  • as a slice condition.
• 2-d spectrum :
  • As a set of x/y points that are closed to form a contour-like area of interest (insidedness is computed in the same way as it is for contours).
  • As a contour condition/gate.

Query parameters

At least one set of the optional parameters that specify a region of interest must be present in the query parameters.

• spectrum (string) - Required - name of the spectrum to integrate.
• gate (string) - Optional Name of gate whose interior is integrated.
• For 1-d spectra only providing explicit limits:
  • low (float) - Low limit of region of interest.
  • high (float) - High limit of region of interest.
• For 2-d spectra only, providing an explicit ROI
  • xcoord (float) - X coordinates of points that define the ROI.
  • ycoord (float) - Y Coordinates of points that define the ROI.

Note that xcoord and ycoord must appear at least three times to define an area of interest. These paramters are taken as defining an ordered set of coordinats so, for example:

...?xcoord=100&xcoord=200&xcoord=200&ycoord=100&ycoord=100&ycoord=150....

Defines the region of interest as a triangle with coordinates:

(100,100)
(200,100)
(200,150)

Response format detail

The detail of the response provides the integration details. Note there are slight differencess betwen SpecTcl and rustogramer; The attributes of the object are:

• centroid - Centroid of the integration. For SpecTcl; integrating a 1d, this is a scaler, or a 2 element array if a 2d. For rustogramer, this is always an array with one element for a 1-d spectrum and two elements for a 2-d.
• fwhm - Full width at half maximum under gaussian shape assumptions. SpecTcl may be a scalar float or 2 element float array; while rustogramer is a one or two element array of floats. Same as for centroid above.
• counts (unsigned integer) - total counts inside the AOI.

Sample Responses.

SpecTcl 1-d success.

{
    "status" : "OK",
    "detail" {
        "centroid" : 102.512,
        "fwhm" : 5.32,
        "counts": : 124567

    }
}

Rustogramer 1-d success.

{
    "status" : "OK",
    "detail" {
        "centroid" :[102.512],
        "fwhm" : [5.32],
        "counts": : 124567

    }
}

2-d success.

{
    "status" : "OK",
    "detail" {
        "centroid" :[102.512, 50.7],
        "fwhm" : [5.32, 7.66],
        "counts": : 124567

    }
}

Failure (SpecTcl)

Below, the word ```$command``` is the ```integrate``` command the REST handler generated:

```json
{
    "status": "'$command' failed",
    "detail":  "<reason for the failure>"
}

Failure (Rustogramer) - only either low or high were provided as query parameters:

{
    "status": "If using limits both low and high must be provided"
    "detail" :
    "detail" {
        "centroid" :[0.0],
        "fwhm" : [0.0],
        "counts": : 0

    }
}

/spectcl/shmem requests

Returns information about the shared Spectrum shared memory. Both SpecTcl and Rustogramer can bind histograms into shared memory. When they do this, external programs can map that same shared memory and e.g. render the histograms graphically.

The following URIs are supported in this domain:

• /spectcl/shmem/key Get shared memory attachment information
• /spectcl/shmem/size Get the total size of the shared memory region.
• spectcl/shmem/variables Provide the values of some "interesting" shared memory variables.

/spectcl/shmem/key

This URI provides information about how to attach to the server's shared memory. Historically, SpecTcl used SYSV shared memory segments. These are identified by a 4byte key (SpecTcl uses ASCII bytes for these bytes so they are printable).

SYSV shared memory, however is not portable. There are two other forms of shared memory:

• POSIX shared memory
• File mapped shared memory.

Of these, rustogramer chose the latter. One problem, therefor was how to identify the method to use to map the shared memory from a "key". A key, therefore, can either look like:

• kkkk - a four character string, in which case it identifies a SYSV shared memory key.
• sysv:kkkk - which identifies a sysV shared memory.
• posix:filename - which identifies a POSIX shared memory region.
• file:filename - which identifies a file backed shared memory.

Query parameters

None

Response format detail

The resonse is a generic response. On success, detail will be the shared memory key.

Sample Responses.

SpecTcl success:

{
    "status" : "OK",
    "detail" : "XA7c"
}

Rustogramer success:

{
    "status" : "OK",
    "detail" : "file:/home/ron/.tmpabcde"
}

Rustogramer failure:

{
    "status": "Failed to get shared memory name",
    "detail": "<reason for the failure"
}

Note that SpecTcl always succeeds.

/spectcl/shmem/size

Returns the size of the display shared memory in bytes.

Query parameters

None

Response format detail

detail is the stringified size in bytes.

Sample Responses.

Success:

{
    "status" : "OK",
    "detail" : "209715200"
}

In this case the entire shared memory region, headers and spectrum channels is 209715200 bytes.

/spectcl/shmem/variables

Provides the values of some internal SpecTcl variables. Note that

Query parameters

No query parameters are supported.

Response format detail

The detail is an object where each field is a name/value of an internal variable. Note that some of the variables are not supported by Rustogramer but are provided with a "sensible" value. The list below will point out when this is the case. Note that all variable values are strings the types given are hints about how to interpret the srings. For example DisplayMegabytes could be "200" which means 200.

The attributes are:

• Displaymegabytes (unsigned) - Megabytes of shared memory spectrum storage.
• OnlineState (bool) - set true by some SpecTcl scripts that use attach -pipe to attach to the online DAQ system. Rustogramer sets this to false
• EventListSize - The size of the event batch. For SpecTcl this is the number of decoded events sent on each histogramming operation. For Rustogramer, the number of event ring items sent to the histogram thread in each operation.
• ParameterCount (unsigned/string)- In SpecTcl, this is the initial size used for CEvent objects, while for Rusgtogramer this is the value "-undefined-"
• SpecTclHome (string) - SpecTcl - the top level of the installation directory tree. for Rustogramer, this is the directory in which the executable was installed.
• LastSequence (unsigned/string) - Number of ring items processed in the most recent run for SpecTcl, for Rustogramer, this is "--undefined-"
• RunNumber (unsigned/string) - for SpecTcl, this is the run number of the most recently seen state change ring item. For rustogramer this is "-undefined-"
• RunState (int/string) - For SpecTcl this is nonzero if analysis is active or zero if not. For Rustogramer this is "-undefined-".
• DisplayType (string) - For SpecTcl this identifies the type of the displayer, e.g. qtpy. Rustogramer has no integrated displayer so it always returns None to be consistent with headless SpecTcl.
• BuffersAnalyzed (unsigned/string) - The total number of ring items analyzed. For SpecTcl, taken with LastSequence the fraction of events analyzed can be computed. Rustogramer returns "-undefined-"
• RunTitle (string) - Title from the most recent state change item for SpecTcl, "-undefined-" for rustohgramer.

The following statistics attributes are present in SpecTcl but not in Rustogramer:

• Statistics(EventsRejectedThisRun) (unsigned) - Number of eevents for which the event processing pipeline returned kfFALSE in this run.
• Statistics(RunsAnalyzed) - Number of times a BEGIN_RUN ring item was seen when analyzing data.
• Statistics(EventsAnalyzed) - Number of events analyzed.
• Statistics(EventsAccepted) - Number of events for which the event processing pipline returned kfTRUE
• Statistics(EventsAnalyzedThisRun) - Number of events analyzed in the current run.
• Statistics(EventsRejected) - Total number of events for which the event processing pipeline returned kfFALSE.
• Statistics(EventsAcceptedThisRun) - Number of events in this run for which the event processing pipeline retunrned kfTRUE

Sample Responses.

SpecTcl:

{
    "status" : "OK",
    "detail" : {
        "DisplayMegabytes"                  : "200",
        "OnlineState"                       : ">>> Unknown <<<",
        "EventListSize"                     : "1",
        "ParameterCount"                    : "256",
        "SpecTclHome"                       : "/usr/opt/spectcl/5.14-000",
        "LastSequence"                      : "0",
        "RunNumber"                         : "0",
        "RunState"                          : "0",
        "DisplayType"                       : "qtpy",
        "BuffersAnalyzed"                   : "1",
        "RunTitle"                          : ">>> Unknown <<<",
        "Statistics(EventsRejectedThisRun)" : "0",
        "Statistics(RunsAnalyzed)"          : "0",
        "Statistics(EventsAnalyzed)"        : "0",
        "Statistics(EventsAccepted)"        : "0",
        "Statistics(EventsAnalyzedThisRun)" : "0",
        "Statistics(EventsRejected)"        : "0",
        "Statistics(EventsAcceptedThisRun)" : "0"
    }
}

/spectcl/sbind requests

SpecTcl and rustogrramer maintain a shared memory into which spectra can be put. Such spectra can be accessed by local display programs providing a high speed channel to send histogram data to the displayer.

Spectra placed in shared memory are said to be bound to shared memory. In SpecTcl, there is no cost to binding spectra, the spectrum bins are moved into shared memory and histograming directly occurs in shared memory. In Rustogramer, the underlying histograming engine does not allow this so channels are periodically copied o that shared memory.

Note that sbind has its origins in the original SpecTcl where the more natural bind collides with the Tk bind command for binding events in display elements to scripts.

The /spectcl/sbind URI domain has the follwing URIs:

• /spectcl/sbind/all - Bind all spectra to display memory.
• /spectcl/sbind/sbind - Bind a single spectrum to the display.
• /spectcl/sbind/list - List th current bindings.
• /spectcl/sbind/set_update Rustogramer only, specifies the number of seconds between updates to the shared memory.
• /spectcl/sbind/get_update Rustogramer only, returns the shared memory refresh rate.

/spectcl/sbind/all

Binds all spectra to display memory.

Query parameters

No paramters are supported.

Response format detail

A generic response is returned.

Sample Responses.

{
    "status": "OK",
    "detail" : ""
}

Failure is possible for example, if there is not sufficient free space in the shared memory region to accomodate all of the spectrum channels. An error return from Rustogramer might look like

{
    "status": "Unable to bind spectrum <aspectrum-name>",
    "detail": "<reason the bind failed>"
}

/spectcl/sbind/sbind

Bind some spectra to the display memory.

Query parameters

• spectrum (string) - Mandatory. Names a spectrum to bind to the display memory. Note that if this query parameter appears more than once, all mentioned spetra will be bound.

Response format detail

The response is a generic response.

Sample Responses.

Success:

{
    "status": "OK",
    "detail" : ""
}

Failure:

{
    "status": "Unable to bind spectrum <aspectrum-name>",
    "detail": "<reason the bind failed>"
}

/spectcl/sbind/list

List the spectrum bindings.

Query parameters

• pattern (string) - Optional glob pattern, only bindings for spectra with names that match the pattern will be listed. The pattern defaults to * which matches all spectra.

Response format detail

The detail is a vector of objects with the following attributes:

• spectrumid (unsigned)- A number associated with the spectrum (not really useful in most cases).
• name (string) - Name of the spectrum.
• binding (unsigned) - The shared memory slot number containing the spectrum's description.

Sample Responses.

Success with a single matching spectrum in slot 6:

{
    "status" : "OK",
    "detail" : [
        {
            "spectrumid" : 12,
            "name"       : "a-spectrum",
            "binding"    : 6
        }
    ]
}

/spectcl/sbind/set_update

Available only on Rustogramer. Provides the refresh period in seconds for the shared memory. In SpecTcl, since histograms are directly incremented in display memory for bound spectra, this is not needed, however in Rustogramer, spectrum contents in shared memory must be refreshed from their histograms

Query parameters

• seconds (unsigned int) - Mandatory. Provdes a new update period in seconds.

Response format detail

A generic response.

Sample Responses.

If attempted in SpecTcl you will get a 404 error from the server indicating there is no URL match.

Success:

{
    "status" : "OK",
    "detail" : ""
}

/spectcl/sbind/get_update

Rustogramer only Queries the shared memor refresh period.

Query parameters

No query parameters are supported.

Response format detail

The detail attribute is an unsigned integer that is the number of seconds between spectrum contents refreshes.

Sample Responses.

{
    "status" : "OK",
    "detail" : 2
}

The spectrum memory is refreshed every 2 seconds.

/spectcl/unbind requests

For more information about spectrum binding, see /spectcl/sbind.

This domain of URIs supports a few methods for unbinding spectra.

• /spectcl/unbind/byname - Unbind given the name of a spectrum.
• /spectcl/unbind/byid - (SpecTcl only) - by spectrum id.
• /spectcl/unbind/all - Unbind all spectra.]

/spectcl/unbind/byname

Give a spectrum name, removes it from spectrum memory. The spectrum still exists and is incremented, however clients of the shared memory are blind to it.

Query parameters

• name (string) - mandatory name of the spetrum to unbind.

Response format detail

A generic response is produced.

Sample Responses.

Success:

{
    "status" : "OK",
    "detail" : ""
}

Failure

{
    "status": "Failed to unbind <spectrum-name>",
    "detail": "<reason unbind failed>"
}

/spectcl/unbind/byid

This is only supported in SpecTcl. Unbinds a spectrum from the shared memory given its spectrum id.

Query parameters

• id (unsigned) - mandatory parameter that provides the id of the spectrum to unbind.

Response format detail

Generic response.

Sample Responses.

Rustogramer:

{
    "status" : "Unbind by id is not implemented",
    "detail" : "This is not SpecTcl"
}

Spectcl success:

```json
{
    "status" : "OK"
}

/spectcl/unbind/all

Unbinds all bound spectra from shared memory.

Query parameters

No query parameters are supported.

Response format detail

A generic response is returned.

Sample Responses.

{
    "status" : "OK"
}

Shared memory Mirror service

SpecTcl maintains a list of all of the mirror clients that have registered with it. See the reference documentation about the mirror server for more information about the mirror server protocol in general and mirror registration specifically.

The registration of a mirror client provides the host on which the client runs and the shared memory it created. SpecTcl's mirror client application and API use this to share mirrored shared memories between clients. The mirror client either establishes a new mirror, if one does not yet exist for the host, or maps to the existing mirror if there already is one.

Rustogramer provides this service as well. Note that in windows, it's assumed there's typically only one client so the client code unconditionally creates a new mirror internal to the process that requests it.

/spectcl/mirror

Returns a list of the mirrors being remotely maintained.

Query parameters

No query paramters are supported.

Response format detail

The detail is an array of structs where each struct describes a mirror registration and contains the following attributes:

• host (string) - DNS name or IP address in dotted notation of the host maintaining a mirror.
• shmkey (string) - Shared memory identifier. See the shmem requests for information about this

Sample Responses.

{
    "status" : "OK",
    "detail" : [
        {
            "host" : "some.host.at.adomain",
            "shmkey" : "Xa3b"
        }
    ]
}

/spectcl/pman requests

This domain of URIs only is supported by SpecTcl. SpecTcl transforms raw event data into parameterized data via a logical analysis pipeline. The pipeline consists of stages called event processors. Each event processor has access to the raw event as well as the unpacked parameters at that stage of the pipeline. As such, event processors can, not only decode raw data into parameters, but create computed parameters independent of the format of the raw data.

Rustogramer is built to operate on decoded parameter sets rather than raw data so that the process of creating parameters does not have to happen over and over again for each analysis pass. Therefore analysis pipeline manipulation makes no sense.

In SpecTcl 5.0 and later, commands and APIs were introduced to allow event processors to be incorporated and registered but not, necesarily, made part of the event processing pipeline in use. The pman command, describedi n the SpecTcl Command Reference is the user side of this SpecTcl subsystem.

The requests in this URI domain provide support for dynamically composing event processing pipelines and selecting the pipeline to be used with the analyzed data. One very simple use case for this would be to register the filter unpacker and make a pipeline for it while also making a raw event decoding pipeline. One could then switch between processing raw and filtered data without modifying or switching SpecTcl by selecting the appropriate pipeline for the data set.

The following URIs are supported:

• /spectcl/pman/create - Create a new, empty, event processing pipeline.
• /spectcl/pman/ls - List just the names of the event procesing pipelines currently defined.
• /spectcl/pman/current - Return the currently selected pipeline.
• /spectcl/pman/lsall - List processing pipelines and the event processors in them.
• /spectcl/pman/lsevp - Lists the names of the event processors.
• /spectcl/pman/use - Select the current event processing pipeline.
• /spectcl/pman/add - Add an event processor to the end of an event processing pipeline.
• /spectcl/pman/rm - Remove an event processor from a pipeline.
• /spectcl/pman/clear - Remove all event processors from a pipe.
• /spectcl/pman/clone - Create a duplicat of an existing pipeline.

/spectcl/pman/create

SpecTcl only - create a new event processing pipeline. The pipeline will have no event processors.

Query parameters

• name (string) - Name of the processor to create.

Response format detail

Generic response

Sample Responses.

From rustogramer:

{
    "status": "Pipeline management is not implemented",
    "detail": "This is not SpecTcl",
}

From SpecTcl success:

{
    "status": "OK"
}

From SpecTcl failure: j

{
    "status" :  "'pman mk' command failed",
    "detail" : "<Error message from pman mk command>"

}

/spectcl/pman/ls

Lists just the names of the pipelines. To get more information, see /spectcl/pman/lsall.

Query parameters

• pattern (string) - Optional glob pattern. Only pipeline names that match that pattern will be listed. If not supplied, the pattern defaults to * which matches everthing.

Response format detail

detail is an array of strings. Each string is the name of a pipeline.

Sample Responses.

Rustogramer:

{
    "status" : "Pipeline managment is not implemented - this is not SpecTcl",
    "detail": []
}

SpecTcl success:

{
    "status" : "OK", 
    "detail" : [
        "raw-to-parameters",
        "filter"
    ]
}

SpecTcl failure gives a generic response:

{
    "status" : "'pman ls' command failed",
    "detail" : "<Error message from the pman ls command>"
}

/spectcl/pman/current

Provide information about the currently selected event processor.

Query parameters

No query parameters are supported.

Response format detail

detail is an object with attributes:

• name (string) - pipeline name.
• processors (array of strings) - Names of the processors in the current pipeline. Note that the array element order is the same as the pipeline order.

Sample Responses.

Rustogramer (Generic response):

{
    "status" : "Pipeline management is not implemented",
    "detail" : "This is not SpecTcl",
}

SpecTcl success:

{
    "status" "OK",
    "detail" {
        "name" : "raw-to-parameters", 
        "processors" : [
            "subsystem-1",
            "subsystem-2",
            "correlations",
            "computed-parameters"
        ]
    }
}

SpecTcl failure (Generic response):

{
    "status" : "'pman current' command failed",
    "detail" : "<Error message from pman current command>"
}

/spectcl/pman/lsall

Provide detailed listings of event processing pipelines.

Query parameters

• pattern (string) - Optional glob pattern. The event processors listed must have names that match the pattern. If not provided, pattern defaults to * which matches everything.

Response format detail

The detail is an array of objects. Each object has the attributes:

• name (string) - pipeline name.
• processors (array of strings) - Names of the event processors in the pipeline in the order in which they will be called.

Sample Responses.

Rustogramer

{
    "status" : "Pipeline management is not implemented - this is not SpecTcl",
    "detail" : []
}


SpecTcl success:

```json
{
    "status" : "OK", 
    "detail" : [
        {
            "name" : "raw",
            "processors" : [
                "subsystem-1",
                "subsystem-2",
                "correlations",
                "computed-parameters"
            ]
        },
        {
            "name" : "filter",
            "processors": [
                "filter-unpacker"
            ]
        }
    ]
}

/spectcl/pman/lsevp

List the names of event processors.

Query parameters

• pattern (string) - Optional glob pattern. Only event processors that match the pattern will be listed.

Response format detail

detail is an array of strings that are the names of event processors.

Sample Responses.

Rustogramer

{
    "status" :  "Pipeline management is not implemented - this is not SpecTcl", 
    "detail" : []
}

Success from SpecTcl:

{
    "status" : "OK",
    "detail" :  [
        "subsystem-1",
        "subsystem-2",
        "correlations",
        "computed-parameters",
        "filter-unpacker"
    ]
}

Failure from SpecTcl (generic response):

{
    "status" : "'pman ls-evp' command failed",
    "detail" : "<error message from pman ls-evp command>"
}

/spectcl/pman/use

Select the current event pipeline

Query parameters

• name (string) - Name of the event processing pipeline to make current.

Response format detail

Generic response.

Sample Responses.

Rustogramer:

{
    "status" : "Pipeline management is not implemented",
    "detail" : "This is not SpecTcl"
}

SpecTcl success:

{
    "status" : "OK"
}

SpecTcl Failure:

{
    "status" : "'pman use' command failed",
    "detail" : "<error message from pman use>"
}

/spectcl/pman/add

Adds a new event processor to an event processing pipeline. The new processor is added to the end of the pipeline. Note that if the pipeline being edited is current the effect on event processing is immediate.

Query parameters

• pipeline (string) - Mandatory name of the pipeline to be edited.
• processor (string) - Mandatory name of the event processor to append to the pipeline. Note that a processor can be part of more than one pipeline of the application requires it.

Response format detail

Generic response.

Sample Responses.

Rustogramer:

{
    "status": "Pipeline management is not implemented",
    "detail": "This is not SpecTcl"
}

SpecTcl success:

{
    "status" : "OK"
}

SpecTcl Failure:

{
    "status" : "pman 'add' command failed",
    "detail" : "<error message from pman add command>"
}

/spectcl/pman/rm

Remove an event processor from a pipeline. If the pipeline is currently in use, the effects on event processing are immediate.

Query parameters

• pipeline (string) - mandatory name of the pipeline to modify.
• processor (string) - mandatory name of the event processor to remove from the pipeline.

Response format detail

The response is a generic response.

Sample Responses.

Rustogramer:

{
    "status": "Pipeline management is not implemented",
    "detail": "This is not SpecTcl"
}

SpecTcl success:

{
    "status" : "OK"
}

SpecTcl Failure:

{
    "status" : "'pman rm' command failed",
    "detail" : "<error message returned by pman rm command>"
}

/spectcl/pman/clear

Removes all of the processors from an event processing pipeline. If the pipeline is currently in use, the effect is immediate and could be disaastrous.

Query parameters

• pipeline (string) - Mandatory name of the pipeline to clear.

Response format detail

Generates a generic response.

Sample Responses.

Rustogramer:

{
    "status": "Pipeline management is not implemented",
    "detail": "This is not SpecTcl"
}

SpecTcl success:

{
    "status" : "OK"
}

SpecTcl Failure:

{
    "status" : "'pman clear' command failed",
    "detail" : "<error message returned by pman clear command>"
}

/spectcl/pman/clone

Sometimes it's useful to take an exising event processing pipeline as a starting point for a new one. The clone request creates a new event processing pipeline that is a duplicate of an existing one.

Query parameters

• source (string) - Mandatory name of an existing pipeline to clone.
• new (string) - Name of a new pipeline to create that will be a duplicate of the source.

Response format detail

A generic response is produced.

Sample Responses.

Rustogramer:

{
    "status": "Pipeline management is not implemented",
    "detail": "This is not SpecTcl"
}

SpecTcl success:

{
    "status" : "OK"
}

SpecTcl Failure:

{
    "status" : "'pman clone' command failed",
    "detail" : "<error message returned by pman clone command>"
}

/spectcl/project requests

The /spectcl/project URI crates a new spectrum by projecting a 2-d spectrum (e.g. 2 or g2 ...) onto one of its axes. Optionally the projection can be inside an area of interest specified by a contour. The new spectrum can either be a snapshot spectrum, in which case it is never incremented after being created, or an ordinary spectcrum, in which case it will be incremented if possible.

Snapshot Spectra are handled differently betweeen SpecTcl and Rustogramer. SpecTcl snapshot spectra are 1-d spectra that are wrapped in a container that prevents them from being incremented. Rustogramer snapshot spectra are created by gating them on a False gate. This also implies that a snapshot spectrum, in Rustogramer can be turned into an ordinary spectrum by ungating it, while a SpecTcl snapshot cannot.

/spectcl/snapshot

Query parameters

• source (string) - Mandatory name of the spectrum to project.
• newname (string) - Mandatory name of the new spectrom to create.
• snapshot (boolean) - Mandatory, if true a snapshot will be created. For SpecTcl any boolean Tcl value can be used. For Rustogramer;
  • True values are any of Yes, yes, True or true
  • False values are any of No, no, False or false
• direction (string) - Mandatory direction selector indicating which direction the projectionis onto. One of:
  • Onto the X axis if X or x
  • Onto the Y axis if Y oe y
• contour (string) - Optional. If supplied this must be a contour that is displayable on the spectrum and the projection will be inside the contour. If the resulting spectrum is not a snapshot, it will be gated on the contour. Thus if the contour is modified after the projection, the manner in which the spectrum is incremented will no longer be faithful to the original projection.
• bind (boolean) - Optional. If supplied and false the new spectrum is not bound into display memory. If not supplied or true it is.

Response format detail

A generic response is produced.

Sample Responses.

Success (Rustogramer)

{
    "status" : "OK",
    "detail" : ""
}

Failure from Rustogramer:

{
    "status" : "Could not bind projected spectrum",
    "detail" : "<reason the projection failed>"
}

Failure from Spectcl

{
    "status" : "'project' command failed: ",
    "detail" : "<error message from the project command>"
}

/spectcl/psuedo requests

Psuedo parameters are a SpecTcl only object. A SpecTcl psuedo parameter is a Tcl script that is invoked for each event and may return a new parameter value. A pseudo parameter depends on a list of other parameters (some of which may also be psuedo parameters as long as they are defined chronogically before used).

Psuedo parameters are not terribly performant. They are intended to answer what-if experiments which, if successful result in compiled code to produce the computed parameter.

Pseudo parameters are processed after all stages of the event processing pipeline have completed.

See the psuedo command documented in the SpecTcl Command Reference for more information on psuedo parameters.

The following URIs manipulate pseudo parameters:

• /spectcl/pseudo/create - Create a new pseudo parameter.
• /spectcl/pseudo/list - List the properties of pseudo parameters.
• /spectcl/pseudo/delete - Delete an exising pseudo parameter.

/spectcl/pseudo/create

Query parameters

• pseudo (string) - Mandatory name to give the pseudo parameter. In addition to provide a name that is used to refer to the pseudo paramater, the actual proc name for the computation is derived from its name.
• parameter (string) - At least one instance is mandatory. An instance of parameter should appear as a query parameter once for each parameter the computation depends on.
• computation (string) -Mandatory. The body of the computation. You can assume that for each parameter specified by the parameter query parameter, there are a pair of variables available to the computation:
  • The name of the parameter (e.g. ?parameter=george implies a varialbe named george), will contain the value of the parameter for the event being processed when the pseudo code is invoked.
  • THe name of the parameter with isValid appended. THe example above implied, that a variable named georgeisValid is defined. This variable is true if the parameter has been produced by the proccessing pipline.

Response format detail

The response is a generic response.

Sample Responses.

Rustogramer

{
    "status" : "Pseudo parameters are not implemented",
    "detail" : "This is not SpecTcl"
}

SpecTcl success:

{
    "status": "OK"
}

SpecTcl failure:

{
    "status": "'pseudo' command failed",
    "detail": "<Error message fromt he pseudo command"
}

/spectcl/pseudo/list

List pseudo parameters and their properties.

Query parameters

• pattern (string) - Optional parameter. If provided, the names of pseudos included inthe listing must match the pattern. If not supplied, the pattern defaults to ```*```` which matches everything.

Response format detail

*detail is an array containing objects, on object for each listed pseudo parameter. The attributes of the objects are:

• name (string) - name of the pseudo parameter.
• parameters (array of strings) - the parameters the pseudo parameter computation depends on.
• computation (string) - The computation script.

Sample Responses.

From Rustogramer:

{
    "status": "Psuedo parameters are not implemented - this is not SpecTcl",
    "detail": []
}

Successful SpecTcl with a parameter add12 that add par1 and par2 together.

{
    "status" :"OK",
    "detail": [
        {
            "name" : "add12",
            "parameters": [
                "par1", 
                "par2"
            ],
            "computation" : " if {$par1isValid && $par2isValid} {
                return [expr {$par1 + $par2}]
            } else {
                return -1000
            }
            "
        }
    ]
}

SpecTcl failure:

{
    "status" : "'pseudo -list' command failed",
    "detail" : "<error message from pseudo -list command"
}

/spectcl/pseudo/delete

Deletes an existing Psuedo parameters.

Query parameters

• name - Name of the parameter to delete.

Response format detail

Response is a Generic Response.

Sample Responses.

Rustogramer:

{
    "status" :"Pseudo parameters are not implemented",
    "detail" : "This is not SpecTcl"
}

SpecTcl success:

{
    "status" : "OK"
}

SpecTcl failed:

{
    "status" : "'pseudo -delete' command failed",
    "detail" : "<error message from pseudo -delete command"
}

/spectcl/rootree requests

This URI domain is only available in SpecTcl. It supports access to SpecTcl's ability to make root trees from the parameters created by its event processing pipeline. Since Rustogramer does not create root trees, this is not meaningful and making requests to these URIs for Rustogramer will result in a Generic response of the form:

{
    "status": "Root Tree output is not supported",
    "detail": "This is not SpecTcl"
}

unless otherwise noted (e.g. for reponses from SpecTcl that are not generic responses).

SpecTcl, supports the following URIs:

• /spectcl/roottree/create - Makes a new root tree.
• /spectcl/roottree/delete - Delete an existing root tree.
• /spectcl/roottree/list - List root trees and their properties.

For more information about root tree support in SpecTcl, see the roottree command in the SpecTcl Command Reference.

/spectcl/roottree/create

Create a new root tree object.

Query parameters

• name (string) - Required. Name of the new tree being created. Must be unique.
• parameter (string) - At least one required. Each instance of the parameter query paramater provides a glob pattern. Parameters in the event which match the pattern are included in the output tree.
• gate (string) - Optional. If provided the root tree will only output events that satisfy the specified gate. Note that:
  • If no gate is specified all events are written.
  • Changes to the gate dynamically affect the roottree output.
  • The point above means that if you delete the gate, the root tree will not output events as in SpecTcl a deleted gate is the same as a False gate.

Response format detail

detail is a generic response.

Sample Responses.

Success:

{
    "status" : "OK"
}

Failure:

{
    "status" : "'roottree create' command failed",
    "detail":  "<root tree create error message>"
}

/spectcl/roottree/delete

Delete an existing root tree object.

Query parameters

• tree (string) - Required. The name of the tree to delete.

Response format detail

The response is a generic response.

Sample Responses.

Success:

{
    "status": "OK"
}

Failure:

{
    "status" : "'roottree delete' command failed",
    "detail" : "<error message from roottree delete command>"
}

/spectcl/roottree/list

Lists the properties of root trees.

Query parameters

• Pattern (string) - Optional. If provided, only the root trees with names that match the glob pattern are included in the list. If not provided, the pattern defaults to * which matches all names.

Response format detail

detail is an array of objects. Each object describes one root tree and has the following attributes:

• tree (string) - name of the tree.
• params (array of strings) - Array of parameter patterns that are booked into the tree.
• gate (string) - name of the tree's gate. If the tree does not have a gate, this will be an empty string.

Sample Responses.

Since the detail is not a string, the Rustogramer return object looks like this:

{
    "status" : "Root tree output is not implemented - this is not SpecTcl",
    "detail" : []
}

This shape is compatible with what's expected by SpecTcl clients.

SpecTcl success with one matching tree:

{
    "status" : "OK", 
    "detail" :[
        {
            "tree" : "atree",
            "params": [
                "event.raw.*",
                "event.sum"
            ],
            "gate": "tree-gate"
        }
    ]
}

SpecTcl failure is a generic response:

{
    "status" : "'roottree list' command failed",
    "detail" : "<roottree list error message>"
}

/spectcl/script requests

This URI is only supported by SpecTcl. It allows the REST interface to inject and execute a Tcl script in the SpecTcl interpreter. Rustogramer has no command interpreter, Tcl or otherwise and therefore will never support this.

The intended use case is not to inject complex scripts (other than, perhaps via a source, or package require command), but to send one-liners to SpecTcl. Normally, this would be used to set Tcl variables or invoke application specific commands.

/spectcl/script

Query parameters

• command (string) - Required. command string to execute.

Response format detail

The response generated is a generic response.

Sample Responses.

Rustogramer:

{
    "status" :  "Script execution is not supported",
    "detail" : "This is not SpecTcl"
}

SpecTcl successful command completion:

{
    "status" : "OK",
    "detail" : "<the result of the command>"
}

Failure:

{
    "status" : "ERROR",
    "detail" : "<The result of the command>"
}

/spectcl/treevariable requests

This is only supported by SpecTcl, as Rustogramer does not support tree variables.

Almost all requests directed at Rustogramer for this domain produce Generic Responses that are:

{
    "status" :"Tree variables are not implemented",
    "detail" : "This is not SpecTcl"
}

Other return types are noted in the individual request documentation.

The domain provides the following URIs.

• /spectcl/treevariable/list - List tree variables and their properties.
• /spectcl/treevariable/set - Set new value and units for a tree variable.
• /spectcl/treevariable/check - See if the changed flag is set for the tree variable.
• /spectcl/treevariable/setchanged - Set the changed flag for a treevariable.
• /spectcl/treevariable/firetraces - Fire the traces for a set of tree variables, allowin scripts and UI elements that care about the variable to know about changes.

In SpecTcl, tree variables are bound to Tcl variables as linked variables. the set operation changes the value of the linked variable. In general, for scripts which have traces set o the variable, traces must be explicitly fired (/spectcl/treevariablefiretraces) for those traces to execute. Tk GUi elements that bind to variables will, behind the scenes, establish traces and therefore traces must be fired for those elements to update visually. The units metadata are kept separate from the Tcl interpreter and is only known to it through the treevariable -list command.

The purpose of the changed flag is to keep track of which variables have values different from those compiled into SpecTcl. This allows software that saves the SpecTcl state to selectively save only the changed treevariables.

/spectcl/treevariable/list

Lists the priperties of all treevariables. Note that there is no way to selectively list the treevariables (e.g. with a pattern query parameter.)

Query parameters

None supported.

Response format detail

The detail is an array of objects. Each object describes tree variable and has the following attributes.

• name (string) - name of the tree variable being described.
• value (float) - Value of the variable. This will be correct whether traces have been fired or not.
• units (string) - Units of measure metadata.

Sample Responses.

To maintain the shape of the response detail Rustogramer's response is:

{
    "status" : "Tree variables are not implemented.  This is not SpecTcl",
    "detail" : []
}

Here's a SpecTcl return with one treevariable:

{
    "status" : "OK",
    "detail" : [
        {
            "name" : "avarialbe",
            "value" : 3.14159265359,
            "units" : "radians/half-pie"
        }
    ]
}

Failure (I'm not sure I see how this can ever happen but...):

{
    "status" :  "'treevariable -list' failed: ",
    "detail" : "<error message from treevariable -list>"
}

/spectcl/treevariable/set

Sets the value and units of measure metadata of a treevariable. Note that for historical reasons, both must be set.

Query parameters

• name (string) - Required. Name of the treevariable to modify.
• value (float) - Required. New value for the tree variable.
• units (string) - Required. New units of measure for the variable.

Response format detail

Generic response.

Sample Responses.

Success:

{
    "status" : "OK"
}

Failure:

{
    "status" : "'treevariable -set' failed",
    "detail" : "<treevariable -set error message"
}

/spectcl/treevariable/check

Return the value of the check flag for a tree variable. The check flag is non-zero if, at any time during the SpecTcl run, the treevariable was modified.

Query parameters

• name (string) - Required. Name of the tree variable being queried.

Response format detail

On success, detail containss an integer that is zero if the change flag was not set and non-zero if it was.

Sample Responses.

Change flag not set:

{
    "status" : "OK"
    "detail" : 0
}

Error:

{
    "status" : "'treevariable -check' failed",
    "detail" : "<treevariable -check error message>"
}

Note: Prior to 5.13-012, the error return mistakenly had a status of OK

/spectcl/treevariable/setchanged

Set a treevariable changed flag. The changed flag is a latched boolean that is initialized false but is set to true by, e.g. this request, when a value is changed.

Query parameters

• name (string) - Required. Name of the treevariable whose changed flag will be set.

Response format detail

Generic response.

Sample Responses.

Success:

{
    "status"  : " OK"
}

Failure:

{
    "status" :  "'treevariable -setchanged' command failed",
    "detail" : "<treevariable -setchanged' error message" 
}

Note: Prior to 5.13-012, the error return mistakenly had a status of OK

/spectcl/treevariable/firetraces

Fire traces associated with a set of tree variable.s

Query parameters

• pattern (string) - Optional. The traces associated with all treevariables with names matching the pattern are fired. If the pattern is omitted, * is matched, which matches everything.

Response format detail

Generic response

Sample Responses.

Success:

{
    "status" : "OK"
}

Failure:

{ 
    "status" : "'treevariable -firetraces failed: ", 
    "detail" : "treevariable -firetraces error message> "
}

/spectcl/version requests

Provides information about the version and program.

/spectcl/version

In SpecTcl, version strings are of the form M.m-eee where M is called the major version, m the minor version and eee the edit level. In rustogramer version strings are of the form M.m.e

While the version strings differ in format, the fields present are the same.

Query parameters

none

Response format detail

detail is a struct. It has the following attributes:

• major (unsigned) - the major version number of the program.
• minor (unsigned) - the minor version number of the program.
• editlevel (unsigned) - the edit level of the program.
• program_name (string) - This is always present from Rustogramer and contains the string: Rustogramer. It is only present in SpecTcl versions later than 5.14-013 when it contains the string SpecTcl. Therefore the server program is
  • Rustogramer if program_name is present and contains Rustogramer
  • SpecTcl if program_name is no present or is present and contains SpecTcl

Sample Responses.

Rustogramer Version 1.1.0:

{
    "status" : "OK",
    "detail" : {
        "major" :1,
        "minor" :1, 
        "editlevel" : 0,
        "program_name" : "Rustogramer"
    }
}

SpecTcl 5.14-015:

{
    "status" : "OK",
    "detail" : {
        "major" :5,
        "minor" :14, 
        "editlevel" : 15,
        "program_name" : "SpecTcl"
    }
}

SpecTcl 5.14-001; Note that program_name is missing from detail

{
    "status" : "OK",
    "detail" : {
        "major" :5,
        "minor" :14, 
        "editlevel" : 1,
    }
}

/spectcl/exit requests

This request is only supported at this time by Rustogramer. Since Rustogramer never has a command processor, only a ReST request can be used to get it to exit cleanly.

Rustogramer sends a Generic response:

{
    "status" : "OK",
    "detail" : ""
}

And then exits normally. If Rustogramer exits abnormally, it most likely will leave behind the file that is used for its shared display memory.

/spectcl/ringformat request

This request allows the client to set the default ringitem version format. Note that if either SpecTcl or rustogramer encounter a ring format ring item, this is overridden by the contents of that item.

/spectcl/ringformat

Query parameters

• major (unsigned) - Required. Major vesion number of the format.
• minor (unsigned) - Required for SpecTcl, ignored by Rustogramer. The minor version of the format. This is ignored by Rustogramer because changing the format of ring items is grounds to increment the major version of NSCLDAQ.

Response format detail

A generic response is returned.

Sample Responses.

Rustogramer success:

{
    "status" : "OK",
    "detail": ""
}

SpecTcl success:

{
    "status" : "OK",
}

/spectcl/specstats requests

Returns statistics about the underflows and overflows for spectra.

/spectcl/specstats

Query parameters

• pattern (string) - Optional pattern. Only spectra whose names match the glob pattern are included in the listing. The pattern defaults to * matching all names if not provided in the request.

Response format detail

detail is an array of structs, one for each spectrum that matches the pattern. Each struct has the following attributes:

• name (string) name of the spectrum.
• undeflows (array of u32) - two element array of number of underflows. The first element are X axis overflows the second, Y axis overflows.
• overflows (array of u32) - two element array of number of underflows. The first element are X axis overflows the second, Y axis overflows.

Note that SpecTcl, for one dimensional spectrim types will have a one element array for both underflows and overflows rustogramer will unconditionally use 2 element arrays but the second element of the array should be ignored for one dimensional spectrum types.

Sample Responses.

Rustogramer a single 1-d spectrum matches:

{
    "status" : "OK", 
    "detail" : [
        {
            "name" : "1-d-spectrum",
            "underflows" : [12, 0],
            "overflows":   [732, 0]
        }
    ]
}

Same result for SpecTcl:

{
    "status" : "OK", 
    "detail" : [
        {
            "name" : "1-d-spectrum",
            "underflows" : [12],
            "overflows":   [732]
        }
    ]
}

Both Rustogramer an SpecTcl 2-d spectrum matches:

{
    "status" : "OK", 
    "detail" : [
        {
            "name" : "2-d-spectrum",
            "underflows" : [12, 5],
            "overflows":   [732, 0]
        }
    ]
}

/spectcl/swrite requests

Provides access to the SpecTcl swrite command to write the contents of spectra to file. Note that since it is SpecTcl or Rustogramer that is doing the actual write operation, file paths passed to this request must make sense in the filesystem seen by the server program.

/spectcl/swrite

Query parameters

• file (string) - Required. File path of the file in which the spectra are to be written.
• format (string) - Required. Format in which the file should be written. Valid format strings are:
  • ascii - SpecTcl ASCII format. This is supported by both SpecTcl and Rustogramer.
  • binary - SMAUG binary format. This is a binary format that should be considered deprecated.
  • json - JavaScript Object Notation. This is supportd by Rustogramer and SpecTcl after version 5.13-012. For a description of the JSON see Format of JSON Spectrum contents files.
• spectrum (string) - Requires at least one. Each occurance of this query parameters adds a spectrum to the list of spectra that will be written to file.

Response format detail

Response is a Generic Response object.

Sample Responses.

Rustogramer success:

{
    "status" :  "OK",
    "detail" : ""
}

SpecTcl success:

{
    "status" :  "OK"
}

One possible rustogramer failure, jason specified for format.:

{
    "status" : "Invalid format type specification:",
    "detail" : "jason"
}

One possible SpecTcl failure the underlying swrite command failed:

{
    "status" : "'swrite' command failed",
    "detail" : "<swrite command error message>"
}

/spectcl/sread requests

Requests that a spectrum contenst file be read. Note that since it is the server itself that does the read, file paths specified must make sense in the context of that server. This point is important if the client and server don't have a common view of the file system. For example, systems that don't share filesystem NFS mounts or a native Windows client talking to a server running in a WSL or other type of virtual machine.

/spectcl/shared

Query parameters

• filename (string) - Required path to file to be read. This must make sense in the server.
• format (string) - Required. Format in which the file should be written. Valid format strings are:
  • ascii - SpecTcl ASCII format. This is supported by both SpecTcl and Rustogramer.
  • binary - SMAUG binary format. This is a binary format that should be considered deprecated.
  • json - JavaScript Object Notation. This is supportd by Rustogramer and SpecTcl after version 5.13-012. For a description of the JSON see Format of JSON Spectrum contents files.
• snapshot (boolean) - Optional defaults to true. If true spectra read from file are made as snapshot spectra. This means they will not increment:
  • In SpecTcl snapshot spectra are spectra that are wrapped in a special container object that refuses to increment the spectrum.
  • In Rustogramer snapshot spectra are just gated on a special False gate.
• replace (boolean) - Optional defaults to false. If true, then if a spectrum is read with the same name as an existing spectrum, the existing spectrum is overwitten. Otherwise a unique spectrum name is generated.
• bind (boolean) - Optional defaults to true. If true the spectrum is bound to display shared memory.

Response format detail

A generic responses is returned.

Sample Responses.

Rustogramer success:

{
    "status" : "OK",
    "detail" : ""
}

SpecTcl success:

{
    "status" : "OK"
}

Rustogramer fails because the file does not exist:

{
    "status" : "Failed to open input file: /no/such/file",
    "detail" : "No such file or device"
}

SpecTcl fails

{
    "status" :  "'sread' command failed",
    "detail" : "<sread command error message>"
}

/spectcl/trace requests

Under ordinary circumstances, a ReST client that wants to be informed of changes to parameter, spectra and condition/application definitions would need to periodically issue requests to list these and analyze the differences between results from a prior time. This can be computationally and bandwidth expensive, especially for large analysis configurations.

Traces are a scheme that reduces this load. Traces are a mechanism that allow applications to be informed of changes to the analysis configuration. The application:

• Establishes a trace using /spectcl/trace/establish. This declares the desire for a client to use the trace system. The server returns a token the client should use in subsequent trace requests.
• Periodically, the client asks for changes since the last time it asked for changes using /spectcl/trace/fetch supplying its token.
• When the client exits, it ideally issues /spectcl/trace/done providing its token. All resources associted with this token are released and the token is rendered invalid.

As the server runs, changes in parameter, spectrum, condition and condition application are queued for each token. You might be concerned that these queues can grow without bound if clients either stop polling without doing a done, or just exit in error due to program errors. That is a valid concern.

When tracing is established, the client must, therefore pass a retention time which s associated with the client's queue (identified by the client token returned). As traces are added, all trace records older than this retention time are removed from the queue. This serves to bound the storage requirements in the server for a queue for a dead client.

Both SpecTcl and Rustogramer support traces. As described above:

• /spectcl/trace/establish is requested first to associated a token with the clietn, and create a trace queue for the client with a retention time.
• /spectcl/trace/fetch - fetches the trace records that have been queued for the client since the last time this request was issued that are not older than the retention time.
• /spectcl/trace/done is issued by the client to indicate that it is done using the trace subsystem (usually clients issue this as part of their exit code).

/spectcl/trace/establish

Establish trace queues for a client.

Query parameters

• retention (unsigned integer > 0)- Mandatory. Number of seconds in the retention interval. Note that this is a minimum retention time as it is the queuing of new trace data that performs the pruning of old trace data.

Response format detail

detail is an integer value; the trace token generated to identify the client.

Sample Responses.

Successful completion

{
    "status" : "OK",
    "detail" : 17394
}

In the example above, the client should use the token value 17394 to identify itself.

/spectcl/trace/fetch

Fetch the traces associated with the client. This is destructive in the sense that once a trace has been fetched it will no longer be in the trace queue. Thus fetches fetch the traces since the last fetch operation (which have not aged out).

Query parameters

• token - Value of the token gotten from /spectcl/trace/establish.

Response format detail

detail is a struct containing the following attributes.

• parameter - The traces on parameters.
• spectrum - The traces on spectra.
• gate - Traces on gates (conditions).
• binding - Traces on bindings of spectra to shared memory.

The value of each trace is a string array. Each element of the string array describes a trace. The first word of a trace is the operation that was done to fire the trace and the second the name of the object on which the trace fired.

Trace operations are:

• add - the named item was aded.
• changed - the named item was deleted.
• delete - the named item was deleted.

Bindings traces have the name and the binding id and their operations are:

• add - the named spectrum was bound to display shared memory and assigned the binding id.
• remove - the named spectrum with the bindgin id was removed from shared memory.

Sample Responses.

Here is an example showing the pre-existing spectrum george was just modified. Note that spectrum modification means deleting the old one and adding a new one.

{
    "status" : "OK",
    "detail" : {
        "parameters" : [],
        "spectrum" : [
            "delete george",
            "create george"
        ],
        "gate" : [],
        "binding" : []
    }
}

/spectcl/trace/done

Stop accumulating trces for a specific client.

Query parameters

• token (unsigned) - Mandatory - the token returned when requesting /spectcl/trace/establish.

Response format detail

detail is a generic response.

Sample Responses.

Success in Rustogramer:

{
    "status": "OK",
    "detail" : ""
}

Shared memory Mirror service

Shared memory provides low overhead, high speed access to the display memory of SpecTcl and Rustogramer, however it does only allow access to those data within a single machine, or virtual machine or persistent container. The mirror service, provided by both SpecTcl and Rustogramer allow software that is not necessarily running in the same system access to this shared memory in an efficient manner.

In Linux systems, mirror clients operate by registering a local shared memory region with the server, and setting up a network pipeline to refresh the contents of that local shared memory from the server's shared memory. Subsequent clients are able to detect, via the /spectcl/mirror ReST rquest if a shared memory mirror has already been set up and, if so, simply connect the requesting process to that mirror.

This section will document:

• The network application level protocol the client and server exchange with each other.
• The SpecTcl client C++ software available for your application.

The actual structure of the shared memory is outside the scope of this document, however the SpecTcl header xamineDataTypes.h provides that information.

Network messages

The mirror client (the software settting up the mirror) and mirror server operate by exchanging binary messages. This section descsribes the structure of these messages using C++ struct definitions. These messages structures are also availble in the SpecTcl header file: MirrorMessages.h

For non C++ authors; the mirror messages can assumed to be packed. Note that the CutiePie displayer includes a Python encapsulation of the mirror software as well as a C++ implementation for Linux and Windows.

The message header

All messages have a message header as their first 64 bits. The structure of this header is:

#include <stdint.h>
...
namespace Mirror {
...
    struct MessageHeader {
        uint32_t s_messageSize;
        uint32_t s_messageType;
    };
    ...
}

• s_messageSize -- is the total message size (including the header) in bytes.
• s_messageType -- is a message type which describes what, if any, payload might follow. The currently defined types are defined symbolically (also in the Mirror namespace) in the MirrorMessages.h header as:
  • MSG_TYPE_SHMINFO (1) - The client is sending the server information about the shared memory section it is going to create on its local host.
  • MSG_TYPE_REQUEST_UPDATE (2) - The client is requesting an update of the contents of its local shared memory from the server's shared memory.
  • MSG_TYPE_FULL_UPDATE (3) - In response to a MSG_TYPE_REQUEST_UPDATE message, the server is sending a full update of the used part of the shared memory. The shared memory consists of two subsections. A header describes the spectra that are held in the memory and a channel soup contains the actual channel values of the spectra described in the header. The MSG_TYPE_FULL_UPDATE message contains both the header and the used part of the channel soup.
  • MSG_TYPE_PARTIAL_UPDATE (4) - If the mirror server determines that there have been no changes to the shared memory header since the client's last MSG_TYPE_REQUEST_UPDATE request, it will send only the channel soup part of the shared memory in this type of message. Since header data seems relatively stable compared with channel data this can result in a bandwidth improvements for updates given that header data are rather substantial.

Any payload required by the messages immediately follows the header (withi no padding) and will described in subsequent sections.

MSG_TYPE_SHMINFO

This message type should be sent to the mirror server once it realizes, by using the /spectcl/mirror ReST URI that it is the first mirror client in its host to register information about the shared memory section that it will create locally. Other clients will retrieve this information via that ReST request and can simply map to that exising mirror on behalf of their clients.

The payload for this message is a textual memory key whose lenght is determined by the header's s_messageSize. In the MirrorMessages.h header this is declared as:

#include <stdint.h>
...
namespace Mirror {
...
 
    typedef char MemoryKey[4];
...
}

Which is appropriate for SYSV shared memory keys, however, within the SpecTcl and Rustogramer mirror servers it can be any length to accomodate shared memory information for other types of shared memory systems. See the documentation of /spectcl/mirror, and /spectcl/shmem for information about:

1. How to obtain the shared memory keys that are in use.
2. The meanings of the memory key values for various types of shared memory subsystem.

NOTE: Since windows sytems are generally considered personal desktops, the mirror clients don't bother to create a local shared memory but simply maintain the mirror within the private memory space of the client process, and the key is generated from the process id of the client.

MSG_TYPE_REQUEST_UPDATE

This messagse has no payload.

MSG_TYPE_FULL_UPDATE and MSG_TYPE_PARTIAL_UPDATE

The payloads of these messages are just the memory contents. For a MSG_TYPE_FULL_UPDATE the payload can be read directly into the local mirror memory. For MSG_TYPE_PARTIAL_UPDATE the payload can be directly read into the spctrum soup part of the shared memory (the dsp_spectra field of the Xamine_Shared type).

How client software should work:

Client software will need to use both the ReST an Mirror services as the ReST API provides informational data the client will need.

• The first thing a client should do is make a ReST request of /spectcl/mirror and see if the list of existing mirrors includes one for the local host. Note that hosts may appear in the mirror list in many ways so you may need to do DNS requests to resolve the the host names in the returned data to IP addresses and compare those with the IP addresse(s) of the local system. If a match is found the client should use the shmkey to map to the shared memory and return the pointer to the application.
• If it is necessary to create a shared memory region, the client will need to use the
  • Form a persistent connection to the mirror server.
  • use /spectcl/shmem/size to learn the size of the server's display memory.
  • Create a shared memory region of that size.
  • Send a MSG_TYPE_SHMINFO message to the mirror server.
  • Periodically send MSG_TYPE_REQUEST_UPDATE messages to the mirror server and use its response to to update the contents of the mirror. Note tha the first update request should be sent and processed prior to returning the pointer to the mirror to the application code so that the shared memory has the correct contents prior to use. You are guaranteed that first update response will be a MSG_TYPE_FULL_UPDATE
  • Maintain a connection to the mirror server as long as the mirror is required. This is important because once the connection is closed, the mirror server will forget about the remote mirror as far as its replise to /spectcl/mirror.

Client software

SpecTcl and Cutiepie provide mirror client software.

• SpecTcl provides a mirrorclient application (Linux only)
• Both SpecTcl and CutiePie provide a mirror client library for programs to use (Linux and Windows)

The mirrorclient program.

The simplest way, in Linux to set up a mirror is to use the $SpecTclHome/bin/mirrorclient program. If necessary, it will setup and maintain a mirror. Your programs, can then use the /spectcl/mirror ReST service to locate the shared memory of the mirror and map it. The mirrorclient program takes care of updating the mirror periodically. It has the following command options:

• --host - Mandatory - the value of this option should be the host in wich the histogram server (SpecTcl or Rustogramer) is running
• --restport - Mandatory - the value of this option should be the ReST server port of the histogram server. If the service is advertised via the DAQPort manager, this can also be the name of that service.
• --mirrorport - Mandatory - the value of this option sould be the port on which the histogram's mirror server. Once more if this is advertised inthe DAQPortManager, this can be the name of the service.
• --user - Optional - the name of the user that is running the histogram server. This defaults to your login name on the client system.

Note that once the mirror client program has been run and is maintaining a mirror shared memory, the mirror client library can be used to get a pointer to the mirror in your program.

The mirror client library.

Both SpecTcl and CutiePie provide a mirror client library (actually in SpecTcl 5.14 and later, then library is incoroprated fromt he CutiePie source tree). This is available on Linux and Windows (Cutipie can be installed on windows).

• In SpecTcl installations, the library is in $SpecTclHome/lib/libMirrorClient.so and the headers are in $SpecTclHome/include/SpecTclMirrorClient.h
• In CutiePie installations if the installation top level directory is $CUTIEPIE:
  • In Linux the library is in $CUTIEPIE/lib/libMirrorClient.so and the header is in #CUTIEPIE/include/SpecTclMirrorClient.hi
  • In windows, the library is in $CUTIEPIE/Script/MirrorClient.dll THe header is not installed but can be gotten from The git repository for Cutiepie.

The mirrorclient library header defines the entry points into the library (some parts omitted for brevity).

#ifdef __cplusplus
extern "C" {
#endif
/**
 *  getSpecTclMemory
 *     Returns a pointer to a SpecTcl display memory mirror.
 *
 *  @param host - the host in which SpecTcl is running.
 *  @param rest - The Rest service.  This can be a port number or an NSCLDAQ
 *                advertised service name.
 *  @param mirror - The mirror service.  This can be a port number or an NSCLDAQ
 *                advertised service name.
 *  @param user - If neither rest nor mirror are NSCLDAQ services, this optional argument
 *               is ignored.  If either is a service:
 *               *  A nullptr will qualifiy service discovery by the name of the
 *                  user running this program.
 *               *  Anything else is a username that's assumed to be running SpecTcl.
 *                  This supports, in a collaborative environment such as an
 *                  experiment, user a looking at spectra accumulated by the
 *                  SpecTcl run by user b.
 * @return void* - Pointer to the shared memory region that holds the mirror.
 * @retval nullptr - The mirror, for some reason, could not be created.
 */
EXPORT void*
getSpecTclMemory(
    const char* host, const char* rest, const char* mirror, const char*user = 0
);


/**
 * errorCode
 *    Can only be called after a failed call to getSpecTclMemory - returns
 *    the error code that describes the failure.  These are given symbolically
 *    towards the bottom of this file.
 *  
 *  @return int  - Error status from the failed getSpecTclMemory call.
 */
EXPORT int
Mirror_errorCode();

/**
 * errorString
 *     Returns a human readable description of the error from the code gotten
 *     via errorCode().
 *
 * @param code - the error code gotteen from errorCode().
 * @return const char*  - Pointer to the static error message string.
 */
EXPORT const char*
Mirror_errorString(unsigned code);

/*------------------------------------------------------------------------*/
/*  Error code symbolic values:                                           */

static const unsigned MIRROR_SUCCESS = 0;   // Successful completion.
static const unsigned MIRROR_NORESTSVC=1;   // REST service not advertised.
static const unsigned MIRROR_NOMIRRORSVC=2; // Mirror service not advertised.
static const unsigned MIRROR_CANTGETUSERNAME=3; // getlogin failed.
static const unsigned MIRROR_CANTGETSIZE=4;
static const unsigned MIRROR_CANTGETMIRRORS=5;
static const unsigned MIRROR_SETUPFAILED=6;
static const unsigned MIRROR_CANTGETHOSTNAME = 7;

Note that the extern "C" means that C or C++ code can call this. There are just three entry points. The comments in the header describe the paramters and return values. to expect. A note, you should only call getSpecTclMemory once for each mirror. Thus you might want to encapsulate getting the memory pointer in a singleton object:

class Memory {
    private:
        static void* m_pMemory;
        static Memory* m_pInstance;
        Memory(const char* host, const char* rest, const char* mirror, const char*user) {
            m_pMemory = getSpecTclMemory(host, rest, mirror, user);
        }
    public:
        static void* getMemory(const char* host, const char* rest, const char* mirror, const char*user = 0) {
            if (!m_pInstance) {
                m_pInstance = new Memory(host, rest, mirror, user);
            }
            return m_pInstance->m_pMemory;
        }
}

void* Memory::m_pMemory(nullptr);
Memory* Memory:m_pInstance(nullptr);

Then calling Memory::getMemory(....) is safe to call more than once, if needed

Tcl REST reference

Rustogramer installs a Tcl REST API in the /share/restclients/Tcl subdirectory of the installation tree Linux and in the restclients\Tcl directory on windows. To use the packages in that directory add it to the Tcl Library search path. Two packages are provided:

• SpecTclRESTClient - a low level obejct oriented interface.
• SpecTclRestCommand Simulation of SpecTcl commands using the low level REST client software.

There two ways to get the appropriate subdirectory added to your package search path. The first is to define TCLLIBPATH e.g. suppose the installation directory was /usr/opt/rustogramer/1.0.0: On linux:

TCLLIBPATH=/usr/opt/rustogramer/1.0.0/share/restclients/Tcl tclsh

Rusn tclsh with the library added and

TCLLIBPATH=/usr/opt/rustogramer/1.0.0/restclients/Tcl tclsh

does so on windows as well.

As second method, is to lappend the script package directory to the auto_path global variable, which contains the search path. Suppose, to prevent pollution of the TCLLIBPATH environment variable (which could have additional package directory trees needed by your application), you instead define the TCLREST environment variable to point to the package directory:

lappend auto_path $::env(TCLREST)

Will work on both Linux and Windows to add that path to the package search path because the global variable env is an array whose keys are environment variable names and values the values of those environment variables.

Low Level Package

The low level pacakge provides an object oriented approach to interacting with the SpecTcl server.
Scripts that use this should

• Instantiate a SpecTclRestClient object.
• Make requests of that object.

Construction

Construction looks like:

set client [SpecTclRestClient name ?-host host-spec? ?-port port-spec? ?-debug bool?]

Where:

• name - is the name of the object. If you use the special name %AUTO% a unique name will be used.
• -host - if provided is the host (IP address or DNS name) of the host running the server. This defaults to localhost
• -port - If provided is the port number on which SpecTcl or Rustogramer is listening for ReST connections. Both programs output the value of this to stdout early in their startup. This defaults to 8000 which is the default Rustogramer ReST port.
• -debug - Expects a boolean value which, if provided and true enabled debugging output to stdout showing both the requests and response received. Defaults to false.

$client applyGate

$client applyGate agate spectra

Apply a gate to one or more spectra.

Parameters

• agate - Name of a condition/gate.
• spectra - List of spectra to apply the gate to.

Description

Applies the gate to the list of spectra.

Example:

$client applyGate slice [list spec1 spec2 spec3]

### $client applyList

```tcl
$client applylist ?pattern?

Parameters

• pattern - optional glob pattern against which the spectrum names must match to be included.

Description

List the gates for all spectra that match the pattern. If not supplied, the pattern defaults to ```*```` matching all spectra.

Returns

A list of dicts. Each dict has the keys:

• gate - name of a gate.
• spectrum - The name of the spectrum the gate is applied to.

$client attachSource

$client attachSource type source-spec ?size? ?format?

Parameters

• type - The source type. This can be either pipe or file.
• source-spec - Source specification. For file data sources this is the path to the file. For pipe data sources this is the full command string needed to run the program.
• size - Size of reads in bytes that will be done (defaults to 8192).
• format- Data format. Defaults to ring

See the Spectcl attach command in the documentation.

Description

Attaches a data source to the server. Note that for file data sources, and command names, those must be visible in the context of the server. The data source is not active when attached. Data analysis must first be started.

Returns

Nothing.

$client attachList

$client attachList

Parameters

None

Returns

Returns a string that identifies the current data source.

$client sbindAll

$client sbindAll

Parameters

None

Description

Binds all spectra to the shared display memory.

Returns

None

$client sbindSpectra

$client sbindSpectra spectra

Parameters

• spectra - A list of spectra to bind.

Description

Binds the spectra in the list provided to display memory e.g.

$client sbindSpectra [list spec1 spec2 spec3]

Returns

None

$client sbindList

$client sbindList ?pattern?

Parameters

• pattern Optional pattern. Only spectra that match the pattern will be included in the listing. If omitted, * is used which matches all spectra.

Description

Returns a list of dicts that reflect the display bindings for spectra that match a glob pattern.

Returns

List of dicts that have the keys:

• spectrumid - a numeric id assigned to the spectrum.
• name - name of the spectrum.
• binding - Binding slot number for the spectrm.

Note that unbound spectra are omitted from the list, even if their name matchs the pattern.

$client fitCreate

$client fitCreate name spectruml ow high type

Parameters

• name - unique name to assign to the fit.
• spectrum - Name of the one dimensional spectrumon which to define the fit.
• low - low channel limit over which the fit is performed.
• high - high channel limit over which the fit is performed.
• ftype - fit type. This can be a built in fit type or a fit type that was added by the application.

Description

Creates a new fit object. This unconditionally fails on Rustogramer as it does not support internsl fitting.

Returns

None

$client fitUpdate

$client fitUpdate ?pattern?

Parameters

• pattern - optional glob pattern. Only fits with names that match the pattern are updated. If not supplied, defaults to * which matches everything.

Description

Matching fits are recomputed on the current data in their spectra. As data accumulate into histograms it is important to update the fit parameters to prevent them from getting out of date.

Returns

Nothing.

$client fitDelete

$client fit delete fit-name

Parameters

• fit-name - Name of the fit to delete.

Description

Deletes the named fit.

Returns

None

$client fitList

$client fitList ?pattern?

Parameters

• pattern - Optional glob pattern. Only fits with names that match the pattern are included in the list. If not rovided, the pattern defaults to * which matches everything.

Description

Returns a list of the properties of all fits that match the pattern.

Returns

Tcl list of dicts. Each dict in the list decribes a fit with the following keys:

• name - Name of the fit.
• spectrum - Name of the spectrum the fit is defined on.
• type - Type of fit.
• low, high Limits of the fit in bins.
• parameters Dict containing fit parameters computed by the most recent update request. THe keys in this dict will depend on the fit type, however all fits should provide a chisquare key to asess the goodness of the fit. See the Fit ReST request for more information.

$client fitProc

$client fitProc name

Parameters

• name - name of the fit.

Description

Returns a Tcl proc definition that can compute the fit at any point on the spectrum. The fit is parameterized by a floating point position on the spectrum x axis. It evaluates and returns the value of the model function given the parameterization of the fit as of its last update.

Returns

The text of the fit proc. The proc name will be fitline and will be paramterized by a position on the X axis.

$client foldApply

$clent foldApply gate spectrum

Parameters

• gate - name of the gate to use as a fold.
• spectra - List of spectra to apply8 the fold to

For example:

$client foldApply afold [list s1 s2 s3 s4]

Description

Given a gate and a Tcl list of spectra, applies the gate as a fold to the spectrum.

Returns

None

$client foldList

$client foldList ?pattern?

Parameters

• pattern - Optional glob pattern. Only spectra with names that match the pattern will be listed. If the pattern parameter is omitted, * is used which matches everything.

Description

Lists the properties of folds that match a pattern.

Returns

A list of dicts. Each dict contains the keys:

• spectrum - name of the folded spectrum.
• gate - Name of the gate/condition used to do the folding.

$client foldRemove

$client foldRemove spectrum

Parameters

• spectrum - name of a spectrum to be unfolded.

Description

Removes any fold from a spectrum.

Returns

Nothing.

$client channelGet

$client channelGet spectrum xchan ?ychan?

Parameters

• spectrum - name of the spectrum.
• xchan - X channel coordinate to fetch.
• ychan - only required for spectra with two axes, this is the Y channel coordinate to fetch.

Description

Fetches the value of a spectrum bin idendified by its bin coordinates.

Returns

Integer number of counts in the specified bin.

$client channelSet

$client channelSet spectrum value xchannel ?ychannel?

Parameters

• spectrum - name of the spectrum.
• value - Value to load into the channel
• xchan - X channel coordinate to fetch.
• ychan - only required for spectra with two axes, this is the Y channel coordinate to load

Description

Loads a channel in a spectrum with a specified value.

Returns

None.

$client spectrumClear

$client spectrum clear pattern

Parameters

• pattern Required glob pattern. Spectra which match this pattern are cleared. There is no default, See, however spectrumClearAll below. Making pattern required supports clearing individual spectra.

Examples:

$client spectrumClear george;  # Only clear spectrum named "george"
$client spectrumClear event.*; # Clear spectra with names beginning "event."

Description

Clears the contents of spectra that match the required glob pattern parameter.

Returns

None

$client spectrumClearAll

$client spectrumClearAll

Parameters

None

Description

Clear the contents of all spectra.

Returns

None

$client spectrumProject

Make a projection spectrum.

Parameters

• old - Name of the spectrum being projected (must exist).
• new - Name of the spectrum to create (must not exist).
• direction - The string x or y indicating the projection direction. x Means project down onto the x axis.
• snapshot non-zero value if the spectrum created should be a snapshot spectum. If zero the projection will be a snapshot.
• contour (optional) - if provided must be the name of a contour that is displayable on old. Only the region within this contour is projected. If the spectrum is not a snapshot, the contour is applied to the new spectrum so that the region of projection remains the contour.

Description

Creates a projection spectrum. Note that in the Tcl API at this time, projections are always bound into display memory.

Returns

None.

$client spectrumStatistics

Obtain over and underflow statistics spectra.

Parameters

• pattern (optional) - Spectra whose names match the pattern are returned. If not supplied, the pattern defaults to * which matches all spectrum names.

Description

Requests a count of the x/y under and overflow counts. Underflow counts are incremented when an increment point would be to the left, or below of the axis (x underflow if left of the y axis, y undeflow if below the x axis). Overflows are when the increment point would be to the right or above an axis end point.

Returns

A list of dicts. Each dict provides the under/overflow counts for one spectrum and has the following keys:

• name - name of the spectrum being described.
• underflows - list of underflow counts (one element for 1d spectra and 2 elements for 2d spectra). Note that rustogramer provides both elements unconditionally so you must know something about the underlying spectrum to interpret the result. If a second list element is meaningful, the first element is the number of x underfows, the second the y undeflows.
• overflows - list of overflow counts.

$client treeparameterCreate

Create a new paraemeter with tree parameter metadata.

Parameters

• name - name of the new parameter. This must not already be a parameter name.
• low - Low limit metadata for the parameter.
• high - High limit metadata for the parameter.
• units - (optional) Units of measure for the parameter, if not supplied, defaults to an empty string.

Description

Creates a new parameter and provides it with tree parameter metadata.

Returns

None

$client treeparameterList

Lists the tree parameters.

Parameters

• filter (optional) - Lists the properties of all parameters with names that match the glob filter string. If the optional filter is not supplied it defaults to * which matches all parameter names.

Description

Produces a list of all parameters and their tree parameter metadata. Note that if the server is SpecTcl only parameters that are explitly tree parameters can be included in the list.

Returns

A list of dicts. One per parameter that matches the filter. Each dict describes a parameter with the following keys:

• name - name of the parameter.
• id - Id of the parameter. In Rustogramer this is assigned. In SpecTcl, it can be either explicitly defined by the user or assigned by the tree parameter subsystem.
• bins - Number of bins recommended for axes on this parameter.
• low - Recommended low limit for axes on this parameter.
• hi - recommended high limit for axes on this parameter.
• units - Units of measure of the parameter.
• description - This is only available for Rustogrmer and reserved for a future use when this might be a long form description of the parameter's purpose.

$client treeparameterListNew

Lists the tree paramters that were created by users during the program run. Only SpecTcl produces useful information here.

Parameters

None

Description

In SpecTcl the treeparameter -create command provides the ability to create tree parameters on the fly. It may be desirable to save these tree parameter definitions to file. Rustogramer, however, can define tree parameters from the event parameter files. As such it does not really support this but returns as if no parameters were created.

Returns

A list of the names of created parameters.

$client treeparameterSet

Sets the tree parameter metadata for a parameter.

Parameters

• name - Name of the parameter
• bins - Suggested number of bins for an axis on this parameter.
• low - Suggested low limit for axes on this parameter.
• high - Suggested high limit for axes on this parameter.
• units (optional) - Units of measure for the parameter. Defaults to an empty string

Description

Modifies the metadata for a treee parameter. This modifies all metadata. To modify selected parts of the metaata, you can first list the parameter for example

# Modify only the bins metadata (to 100) for the parameter geore.
# For simplicity assume george exists.

set metadata [lindex [$client treeparameterList george] 0]
$client treeparameterSet [dict get $metadata name]  \
    100, [dict get $metadata low] \
    [dict get $metadata hi] \ 
    [dict get $metadata units]

see the convienience method below, however which can do this sort of thing in a production quality way for you.

Returns

None

$client treeparameterSetInc

Sets the width of chanels for a tree parmeter's suggested axes.

Parameters

• name - name of an existing tree parameter.
• width - desired bin width.

Description

Using the high/low metadata for a parameter, computes a new value for the bins metadata so that the bin width will be the width parameter.

Returns

None

$client treeparameterSetBins

Set the number of bins metadata fo a tree parameter.

Parameters

• name - tree parameter name.
• bins - desired bins metadata

Description

For a given tree parameter, sets its bins metadata only.

Returns

None

$client treeparameterSetUnits

Sets new units metadata for a parameter.

Parameters

• name - name of the parameter.
• units - New units of measure. Must not be an empty string.

Description

Sets a new units of measure metadata for a given treeparameter.

Returns

None

$client treeparameterSetLimits

Sets the suggested axis limits for a tree parameter.

Parameters

• name - name of the tree parameter.
• low - new low limit metadata.
• high - new high limit metadata.

Returns

None

$client treeparameterCheck

Fetch the modified flag for the tree parameter.

Parameters

• name - name of the parameter.

Description

Tree parameters have a modification flag. When metadata are changed, this flag is set. The intent is that applications can use this to determine if saving a tree parameter is needed for state recovery. If the modifiation flag is not set, in general; the parameter need not be saved.

Returns

None

treeparameterUncheck

Reset the modified flag.

Parameters

• name - name of the tree parameter.

Description

Unsets the changed flag of the tree parmaeter (see) treeparameterCheck above.

Returns

None

$client treeparameterVersion

Get the verison string

Parameters

none

Description

Not all of the tree parameter capabilities are implemented in all versions. THis method returns the tree parameter version string.

Returns

Tree parameter subsystem version string. In general this will be in the form M.m where M is a major version and m is the minor version.

$client treevariableList

Lists the tree variables and their properties.

Parameters

None

Returns

A list of dicts. Each dict describes a single treevariable using the following keys:

• name - name of the variable.
• value - Current variable value.
• units - Variable's units of measure.

$client treevariableSet

Set new value and metadata:

Parameters

• name - name of the variable to modify.
• value - New value for the variable.
• units - New units for the variable.

Description

Sets value and metadata for the treevariable. Sadly the only way to just set the value is to first get its units:

proc setValue {client name value} {
    set listing [$client treevariableList]
    foreach item $listing {
        if {$name eq [$dict get $item name]} {
            set units [dict get $item units]
            $client treevariableSet $name $value $units
            return
        }
    }
    
    error "No such tree variable: $name"
}

Returns

None

$client treevariableCheck

Check the state of the variable's changed flag.

Parameters

• name - name of the variable to check.k

Description

Tree variables have an associated changed flag. When either the value or units of measure are changed, this flag is set, and cannot be reset. This method determines the value of that flag.

The normal use of the flag is to selectively save treevariables in configuration files rather than saving all of them. This saves time and disk space for large configurations.

Returns

Non zero if the change flag is true.

$client treevariableSetChanged

Sets the changed flag.

Parameters

• name - tree variable name.

Description

Sets the changed flag to true.

Returns

None.

$client treevariableFireTraces

Fire traces associated with a tree variable.

Parameters

• pattern (optional) - Only variables with names that match this glob pattern have their traces fired. If not supplied, the pattern used is * which matches everything.

Description

Tcl tree variables are mapped to C++ variables. The treevariableSet method changes this underlying C++ variable. When this is done, traces that might be set on that variable (e.g. by Tk because the variable is a -textvariable for a label) are not fired as Tcl knows nothing of the modification.

This method fires write traces for all of the tree variables with names that match the pattern allowing Tcl scripts to become aware of the changes.

Returns

None

$client filterCreate

Create an event filter (SpecTcl).

Parameters

• name - name of the new filter.
• gate - Gate that determines which events make it through the filter to its output file.
• parameters - List of parameters that will be written to the output file.

Description

SpecTcl filters allow the rapid re-analysis of data subsets. Data are subsetted by parameters (only some parameters need be written to a filter) and category (only events that make a gate true are written to a filter). Filter event files, like parameter files are self-describing and do not need to be decoded by user code. As the decode process is often the most time expensive part of running SpecTcl, analyzing a filter file, even one that contains the entire data-set is significantly faster than analyzing a raw data file.

This operation creates a new filter defining its name, the condition which must be met to write an event to the filter and a list of parameters that will be written. Once created a filter must still be associated with an output file and enabledfor it to write data.

Returns

None

$client filterDelete

Delete a filter.

Parameters

• name - name of the filter to delete.

Description

Deletes a filter. If the filter is active (enabled and associated with a file), the data are flushed to file and the file closed.

Returns

None

$client filterEnable

Enable a filter.

Parameters

• name - Name of the filter.

Description

Enables a filter to write data. This is only legal if the filter is already associated with a file.

Returns

None

$client filterDisable

Disables a filter

Parameters

• name - name of the filter.

Description

Disables an filter from writing data. The filter's pending data are flushed to file and the file closed. Note that re-enabling the filter will append data.

Returns

None

$client filterRegate

Apply a new gate to the filter.

Parameters

• name - Name of the filter.
• gate - name of the condition that will gate the filter. If data analysis are active and the filter is enabled, the gate takes effect with the next event the filter sees.

Description

Changes the gate that is used to determine which events are filtered into the file.

Returns

None

$client filterFile

Associate an output file with the filter.

Parameters

• name - name of the filter.
• path - Path to the file to create.

Description

Changes or sets the file to which the filter will output data.

Returns

None

$client filterList

List filters and their properties.

Parameters

• pattern (optional) - Optional pattern. Filter names must match this glob pattern to be inclued in the listing. Note that if the pattern is not supplied, it defaults to * which matches everything.

Description

Returns a list of filters and their properties for filters with names that match a glob pattern.

Returns

A list of dicts. Each dict describes a filter and contains the keys:

• name - name of the filter.
• gate - Name of the filter's gate.
• file - Path to the filter file (this is valid in the context of the server). Empty string if the filter is not yet associated with a file.
• parameters - List of parameters that are written to the filter on events that make gate true.
• enabled - The text enabled if the filter is enabled. If the filters is not enabled, the value disabled is returned.
• format - The filter format string. The only built in format is xdr however other formats may be added since filter formats are extensible.

$client filterFormmat

Set the filter output file format.

Parameters

• name - filter name.
• format - String selecting the format e.g. xdr

Description

Selects the format of the filter file. This must be done when the filter is disabled (not writing data).

Returns

None

$client gateList

Lists conditions that are defined.

Parameters

• pattern (optional) - Only gates with names that match this glob pattern are included in the listing. If omitted, * is used for the pattern which matches everything.

Description

Lists gates and their properties for the subset of gates that match the glot pattern

Returns

A list of dicts. Each dict describes a gate. Note that from Rustogramer, all dict keys are always present but must be ignored or are null if not relevant to the gate type. SpecTcl may omit dict keys for gate types for which they are not relevant.

• name - always present; the gate name
• type - always present, the gate type. See the gate command in the SpecTcl command reference for the set of supported types. Note that Rustogramer gate types are a subset of those supported by SpecTcl.
• gates - List of names of gates this gate depends on (e.g. for a * gate).
• parameters - List of names of parameters the gate depends on (e.g. for a gs gate).
• points - List of dicts that describe the points that make up 2-d geometric gates. Each dict contains x and y keys for the x and y coordinates of the point respectively.
• low - Low limit for 1d geometric gates (e.g. s gates).
• high - High limit for 1d geometric gates.

$client gateDelete

Delete a gate.

Parameters

• name - name of the gate to delete.

Description

Deletes a gate. This means different things on SpecTcl vs. Rutogramer:

In SpecTcl, a deleted gate becomes a False gate and is treated accordingly in e.g. compound gates and gated spectra.

In Rustogrammer, gates are actually deleted and

• The deleted gate is treated as always false in compound gates that depended on it.
• Spectra that were gated directly on the gate are ungated.

Returns

Nothing

gateCreateSimple1D

Create a 1d geometrical gate.

Parameters

• name - name of the gate.
• gatetype - type of the gate.
• parameters - parameters the gate depends on.
• low, high - gate limits.

Description

Creates a slice-like gate. A slice like gate can currently be either a slice (type s) or gamma slice (type gs) and the caller will get an error if gatetype is any other gate type. Slice-like gates are characterized by a low and high limit that define a region of interest in parameter space within which the gate is considered true.

Returns

None

$client gateCreateSimple2D

Create a 2d geometric gate.

Parameters

• name name of the new gate.
• gatetype type of gate (see the Description below).
• xparameters - List of x parameters.
• yparameters - List of y parameters
• xcoords - list of X coordinates of the points.
• ycoords - list of y coordinates of the points.

Description

Creates a gate that is a 2-d geometric figure. There are two types of figures;

• Contours; which are closed regions for which the interior is considered accepted.
• Bands; which are polylines for which below the line is considered accepted.

Different gate types will require different handling of the parameters:

• b and c gatse require a single x and a sinle y parameters.
• Gamma gates (gc and gb) require all parameters the gate is checked on to be a list in the xparameters parameter. For these gates yparameters are ignored.

Returns

None

$client gateCreateMask

Creat a bitmask gate.

Parameters

• name - name of the new gate.
• gatetype - Type of the new gate. See Description.
• parameter - parameter the gate is checked on.
• mask - the bit mask.

Description

Creates a bitmask gate. Ther are three types of bitmask gates: am, em and nm. See the SpecTcl Command Reference descrption of the gate command for a description of these gate types.

Returns

None.

$client createCompound

Creates a compound gate.

Parameters

• name Gate name.
• gatetype Type of gate being made.
• gates dependent gate names.

Description

Creates a gate that depends on other gates. These are *, +````, -andc2band. For a -gate, only one gate name can be in *gate*. For ag2bandgate, there must be two dependent gates and they must both beb``` gates.

The c2band gate takes two bands and joins the first points together as wel as the last to define a contour.

Returns

None

$client integrate

Parameters

• name - name of the spectrum to integrate.
• roi region of interest in which to integrate. See Description below.

Description

Performs a 1d or 2d integration of a spectrum within a region of interest. The roi parameter must be one of the following:

• A dict containing the key gate gate name - in which case it must be a slice-like gate for 1d integrations and a contour-like gate for 2ds.
• A dict containing keys low and high which are the limits of integration for a 1d integration.
• A dict containing the keys xcoords and ycoords in which case these define the x and y coordinates of a contour-like area of interest.

For example

$client integrate aspectrum [dict create gate acontour]
$client integrate oned [dict create low 100 high 200]
$client integrate apectrum [dict create xcoords [list 100 200 200] ycoords [list 100 100 400]]

Returns

A dict containing the keys:

• centroid - one or two element list with the centroid (coorinates).
• fwhm - one or two element list with the FWHM under gaussian peak shape assumptions.
• counts - total counts within the AOI.

$client parameterNew

Create a new raw parameter and its metadata.

Parameters

• name - name of the new parameter (must not exist)
• id - identifying integer (must not exist).
• metadata - dict containing the metadata.

Description

Note in rustogramer there is no distinction between a treeparameter and a raw parameter. In SpecTcl, for historic reasons there is. In SpecTcl, parameters have limited metadata while tree parameters in SpecTcl and Rustogramer have full metadata.

The id* binds the parameter to a specific array-like object index in which that parameter should be unpacked. In SpecTcl this allows user code to explicitly set CEvent elements in Rustogramer, there are only parameter name/id correspondences and you are better using the tree parameter create as it will assign and id.

The metadata is a dict (possibly empty if you do not require/desire metadata). The possible dict keys are:

• resolution - number of bits of resolution the parameter (assumed to be a raw digitizer has). If the value is m, the parameter low is 0 and high 2^m - 1.
• low - low value metadata. This cannot be used with resolution
• high - high value metadat. This cannot be used with resolution ** units** - Units of measure metadata.

Returns

None.

$client parameterDelete

Deletes a raw parameter.

Parameters

• name - name of the parameter to delete.
• id - id of the parameter to delete.

Description

Delete a parameter by naem or id. Only one should be supplied for example:

$client parameterDelete george;   # Delete parameter george by name
$client parameterDelete {} 123;   # Delete parameter no. 123 by id.

Returns

None

$client parameterList

Lists raw parameter and their metadata.

Parameters

• pattern - Glob pattern matched against the names to determine which are listied. Defaults to * which matches everything.
• id - Id of single parameter to list.

Description

Either the pattern should be provided or the id or neither. Here is an exhaustive list of examples:

$client parameterList event*;   # lists all params beginning with "event"
$client parameterList {} 1234;  # Lists parameter id 1234
$client parameterList;          # Lists all parameters.

Returns

List of dicts. Each dict describes a parameter. Dicts may have the following keys:

• name name of the parameter.
• id id of the parameter.
• resolution bits of resolution (if that was set or omitted if not).
• low low limit if set or omitted if not.
• high High limit if set or emitted if not.
• units Units of measure of the parameter. Only present if supplied to the parameter.

$client pseudoCreate

Creates a pseudo parameter. Pseudo parameter are only supported by SpecTcl.

Parameters

• name - name of the new pseudo parameter
• parameters - Parameters that are required to compute the pseudo.
• body - Body of the Tcl proc to use to compute the parameters. See the pseudo command in the SpecTcl Command Reference for a description of this.

Description

Creates a new psueod parameter that is computed via the script in body and depends on the parameters for its computation. Only SpecTcl supports pseudo parameters computed via Tcl scripts.

Note SpecTcl does not ensure that all parameters are present in the event as it is possible the computation may not always need them all.

Returns

Nothing

$client pseudoList

List pseudo parameters and their definitions.

Parameters

• pattern - An optional glob pattern that psuedo names must match to be included in the list. If not supplied the pattern * is used which matches everything.

Description

Returns a listing of pseudo parameters and their properties. The pseudos with name matching pattern are returned.

Returns

List of dicts. Each dict describes a pseudo parameter and has the keys:

• name - name of the pseudo.
• parameters - list of parameters used by the pseudo.
• computation - A Tcl body that computes the pseudo parameter value for each event. See the pseudo command in the SpecTcl Command Reference for a description of this.

$client pseudoDelete

Delete an existing pseudo parameter.

Parameters

@param name - name of the pseudo to delete.

Description

Deletes a pseudo parameter. While the parameter will no longer be computed, its definition (use of name and id) will remain.

Returns

None

$client sread

Read spectrum from file.

Parameters

• filename - Path, in the context of the server, to the file to read.
• options - Dict describing the options for the read:
  • format Format of the file (defaults to ASCII).
  • snapshot True if the spectrum read is a snapshot (true by default).
  • replace If true any existing spectrum with the same name is replaed (false by default).
  • bind If true, the spectrum read will be bound into display memory (true by default).

Description

Reads a spectrum from a spectrum definition file. Valid values for format are:

• ascii - SpecTcl ASCII format.
• json - Rustogramer JSON format (Supported by SpecTcl beginning with 5.13-014)
• binary - Deprecated VMS/SMAUG format (SpecTcl only).

Note that while the sread command has the ability to read several spectra serially from a file (see sread in the SpecTcl Command Reference) the lack of shared state between ReST client anb server for this makes it impossible for ReST clients to do so.

Returns

Nothing

$client ringformat

Set the ring format for event file processing.

Parameters

• major - major version of NSCLDAQ that took the data in the source.
• minor - minor version of NSCLDAQ that took the data in the source.

Description

Data taken by NSCLDAQ are in ring item format, however, there are several payload formats. The format of the ring item depends, largely on the major version of the NSCLDAQ that read it. This method sets the ring format. Note tha the existence of a ring format item in the data itself can override this.

Returns

None.

$client scontents

Get the contents of a spectrum.

Parameters

• name - name of the spectrum.

Description

Returns information about the spectrum statistics and the non zero channels. For large 2-axis histograms this can be time/bandwidth expensive both due to the number of spectrum bins to look at in the server and the amount of data that might be returned in a dense spectrum. If you really need to access spectrum contents at high bandwidt, you should look into the mirroring API as that provides much better bandwidth and much lower latency.

Returns

A dict is returned. Note, for Rustogramer, all keys are present while for SpecTcl, the keys that don't make sense for the spectrum type (e.g. yoverflow for 1d spectrum types) can be omitted. The dict can have the following keys:

• xoverflow Number of overflow counts on the X axis.
• xunderflow Number of underflow counts on the X axis.
• yoverflow Number of overflow counts for the Y axis of a 2d spectrum type.
• yunderflow Number of underflow counts for the Y axis of a 2d spectrum type.
• channels List of bin content information dicts. There will only be entries for bins that have non-zero counts. Each dict has the keys:
  • x - the X bin number.
  • y - the Y bins number for 2d spectrum types. Omitted in SpecTcl for 1d types and shold be ignored for 1d types in Rustogramer.
  • v - The value of the bin (number of counts).

The channels spectrum dicts have shortened keys to somewhat decrease the bandwidth requirements. SpecTcl may also send its return value with deflate Content-Encoding as well to reduce the bandwidth requirements.

$client shmkey

Return the server's shared memory identifier.

Parameters

None

Description

Returns the display shared memory identifier for the server.

Returns

A string with any of the following forms:

• Four characters with no : This is an SYSV shared memory key.
• A string that begins with sysv: and has four more characters; a SYSV shared memory key.
• A string that begins with file: the remainder of the string is the path to a file that can be memory mapped to get access to the shared memory.
• A string that begins with posix: the remainder of the string is a POSIX shared memory identifier that can be accessed via shm_open.

$client shmemsize

Get display memory size.

Parameters

None

Description

Obtains the size of the shared display memory in bytes.

Returns

Size of shared memory in bytes.

$client shmupdate_set

Rustogramer only - sets the shared memory update period.

Parameters

• seconds - minimum number of seconds between shared memory updates.

Description

Rustogramer's display bound histograms are not directly incremented in shared memory, unlike SpecTcl. This returns the update period in seconds. Note that this is the minimum time between updates as load may stretch it out.;

Returns

none

$client shmupdate_get

get the shared memory update period (Rustogramer only).

Parameters

None

Description

Returns the shared memory update period. See also shm_set.

Returns

Number of seconds between updates of the rustogramer shared display memory.

$client spectrumList

List spectrum properties.

Parameters

• pattern - optional glob pattern. If provided, to be included in the resonse a spectrum's name must match the pattern. If not provided, the matching pattern defaults to * which matches all spectra.

Description

Produces a list of the properties spectra defined in the server. Note that spectra do not have to be bound to display memory to be listed. The pattern optional parameter allows the list to be filtered by names that match a glob pattern.

Returns

List of dicts. Each dict describes a spectrum. In rustogramer all keys of the dict are returned but some may have empty values, if they are not relevantt o that type of spectrum. In SpecTcl, irrelevant keys may be omitted.

Dict keys are:

• id - Integer id of the spectrum. This is not really all that useful.
• name - Name of the spectrum.
• type - Spectrum types. See the SpecTcl command reference description of the spectrum command for a list of the valid spectrum type codes.
• parameter - List of parameter required by the spectrum. These are the same as you might provide to a spectrum -create command to SpecTcl
• axes - List of axis definitions. Each dict has the keys low, high, and bins.
• chantype - Data type of channels in the spectrum. THis can be one of:
  • f64 - Rustogramer only - channels are 64 bit floating values.
  • long - SpecTcl only, channels contain a 32 bit unsigned integer.
  • short - SpecTcl only, channels contain a 16 bit unsigned integer.
  • byte - SpecTcl only, channels contain an 8 bit unsiged integer,
• gate - If the spectrum is gated, the name of the gate.

$client spectrumCreate

Get the server to make a new specttrum.

Parameters

• name - Name of the new spectrum. This must not be the name of an existing spectcrum.
• type - Spectrum type. See the SpecTcl command reference description of the spectrum command for a list of the valid spectrum type codes you can use here.
• parameters - List of parameters the spectrum uses. This is in the form used by the SpecTcl spectrum -create command.
• axes List of spectrum axes. With the exception of summary spectrum types, where this is a Y axis specification, there is always an X axis specification and, if the spectrum is a 2d type, a second axis in the list which is a Y axis specification.
• opts - A dict of options. Not all options are required.
  • chantype Channel data type of the spectrum. In SpecTcl, this defaults to long but can be word or byte. In rustogramer, the channel type is unconditionally f64.
  • direction - Needed for 2dmproj spectrum types. This is the projection direction.
  • roigate - Optional for 2dmproj spectrum types. This can be an contour displayable on an underlying m2 spectrum type within which the projection is done.

Note that this allows the creation of a 2dmproj spectrum without the initial creation of the underlying m2 spectrum which is projected. If this is done, you'll get a new spectrum with no initial counts but which is incremented as new data come in and which, would be a faithful representation of a projection of a virtual underlying m2 spectrum.

Description

Creates a new spectrum. Note that this also allows the creatino of a 2dmproj spectrum without requiring a source spectrum from which to make the initial projection.

Spectra created will have no counts but will increment as new data arrive.

Returns

None

$client spectrumDelete

Delete a spectrum.

Parameters

• name - name of the spectrum to delete.

Description

• Deletes a spectrum. If the spectrum is bound to display memory, resources it used in the display shared memory (the description header and channel soup section it used) are freed for re-use.

Returns

None

$client unbindByName

Undbind spectra from display shared memory given their names.

Parameters

• names - List of names of the spectra to unbind.

Description

Removes spectra from display shared memory given their names. This releases all resources used by them in shared memory. This includes its header description and the chunk of the channel soup it consumed.

Returns

None.

$client unbindById

Unbinds spectra from display shared memory given their ids.

Parameters

• ids - List of spectrum ids to unbind.

Description

Removes spectra from display shared memory given their ids. This releases all resources used by them in shared memory. This includes its header description and the chunk of the channel soup it consumed.

unbindByName should be preferred to this.

Returns

None.

$client unbindAll

Unbind all spectra from display shared memory

Parameters

None

Returns

None

$client ungate

Removes gating conditions from spectra.

Parameters

• names - list of names of spectra to ungate.

Description

For each spectrum name in names any gating condition is removed from that spectrum.

Returns

None

$client version

Get server version information.

Parameters

None

Description

Returns version information and, possibly program name, for the server. Note that only older SpecTcl does not return the pogram name and therefore the lack of a program name implies a SpecTcl server.

Returns

A dict containing the following keys:

• major - program major version number.
• minor - program minor version number.
• editlevel - programe edit/patch-level version number.
• program_name - may be omitted by older SpecTcl's. The name of the program. For now this can be the strings:
  • Rustogramer
  • SpecTcl

$client swrite

Write spectra and contents to file.

Parameters

• filename - name of the file to write to. This path must make sense in the context of the server program.
• spectra - list of names of spectra to write to file.
• format - Format specifier. This can be:
  • ascii - Simple ASCII format.
  • json - Json ASCII format. was added to SpecTcl in 5.13-014.
  • binary - Legacy VMS/SMAUG format which onlyi SpecTcl can write.

Description

Writes the list of spectra to file in the selected format. Note that it is the server that does the actual write and therefore filename must make sense in its context rather than the client's. This point is important in environments where the client and server don't share the same filesystem mappings. A simple FRIB example might be the client running in a container with a different set of --bind options that the container the server is running in.

Returns

None

$client start

Start analysis.

Parameters

None

Description

Once an event source is specified for the server, it is still necessary to start analyzing data from that source. This method asks the server to start analyzing data from it current source.

Returns

None

$client stop

Stop analysis.

Parameters

None

Description

Stops analyzing data from the current data source. Note the data source is not detached. This can be problematic for blocking data sources that are adaptors for an online system. Specifically, stopping analysis in the midst of a run can result in back-pressure flow control that eventually works its way back to the data source halting acquisition.

For NSCLDAQ see the --non-blocking option in the ringselector application to avoid this problem. This is decribed in the NSCLDAQ Documentation. See the 1daq section of that table of contents and click on the ringselector link.

Returns

None.

$client rootTreeCreate

Create a root tree.

Parameters

• name - name of the root tree.
• parameterPatterns - list of glob patterns that specify the parameters that will be booked into the tree.
• gate Optional patern. Specifies a gate that will determine which events are added to the tree. The default is an empty string which applies a True gate.

Description

Roottrees are a bit like SpecTcl filters. They too are only supported by SpecTcl. Root trees are file backed Root data files. The tree created in that file by a root tree is a selected set of decoded parameters for each event. The selection criterion is an ordinary SpecTcl gate.

Unlike filters, which are only part of the event sink pipeline; RootTrees have feet both in the event processing pipeline and the event sink pipeline. The event processing pipeline parts are responsible for opening/closing new files as new runs are encountered an the event sink pipeline is responsible for booking tree leaves for each event that satisfies the tree's gate.

Returns

None

$client rootTreeDelete

Deletes a root tree

Parameters

• name - name of the tree to delete.

Description

Flushes and closes the file associated with a root tree and then destroys the tree releasing all resources associated with it.

Returns

None

$client rootTreeList

Lists root trees and their properties.

Parameters

• pattern optional glob pattern. If provided, only trees with names that match the pattern are included int the list. If omitted, the pattern is treated as * which matches everything.

Description

Lists the properties of all root trees that match the pattern.

Returns

A list of dicts that have the following keys:

• tree - name of of the tree.
• parameters - list of the parameter patterns that are booked into the tree.
• gate - Name of the gate that determines which event are booked into the tree.

$client pmanCreate

Make an analyss pipeline (SpecTcl only).

Parameters

• name - name of the new analysis pipeline. This must not be the name of an existing pipeline. The pipeline will, intially, have no event processors.

Description

Creates a new, empty event processing pipeline. A feature of SpecTcl 5 and later is that in addition to the initial, compiled in event analysis pipeline, applications can register event processors, create additional pipelines and switch them in and out as required.

One use case. An event analysis pipeline consisting of the filter decoder processing element could be created then made current to analyze filter files. Other use cases might be to have a sigle SpecTcl with event processors registered for all of the detector systems you use with the analysis pipeline composed at startup from them, depending on the actual experiment.

Note that the SpecTcl plug-in capability can also be used to dynamically load and register event processors and pipelines at run time. See the SpecTcl programming guide chatper 11.

Returns

None

$client pmanList

List the names of all of the event processing pipelines (SpecTcl Only).

Parameters

• pattern - optional pattern. If supplied, this is a glob pattern. Only names matching the patter will be returned. If not supplied, the matching pattern defaults o * which matches everything.

Description

Lists the names (only) of all of the registered event processing pipelines. Pipelines can be registered programmatically or at run time via pmanCreate, or in user C++ code.

Returns

A Tcl list whose elements are the event processing piplines. While the current pipeline manager dictionary will spit out the names in alphabetical order, you should not rely on that or any other order.

$pmanCurrent

List the information about the current event procesing pipeline (SpecTcl only).

Parameters

None

Description

The current event processing pipeline is the one that raw events are dispatched to by SpecTcl to be turned into parameters. This returns details about the current processing pipeline. Note that the even processing pipeline created in the classical MySpecTclApp::CreateAnalysisPipeline method is called default

Returns

A dict that contains:

• name - the name of the current pipeline. The initial pipeline, unless changed by the user's MySpecTclApp implementation is default
• processors -Tcl list of the event names of the event processors in the pipeline. These names are in registration order and, therefore reflect the order in which they will be invoked to process an event.

$client pmanListAll

List all information about event procesing pipelines (SpecTcl only).

Parameters

• pattern - optional glob pattern. If supplied the names of pipelines must match the pattern to be included in the listing. IF not provided the pattern matched against is * which matches everything.

Description

Provides detailed information about all event processors that match pattern.

Returns

A Tcl list of Tcl dicts. Each dict contains the following keys:

• name - name of the event processing pipeline.
• processors - Tcl list of the names of the event processors in the pipeline. The order of this list will be the order in which processors were added to the pipeline which, in turn, is the order in which the pipeline processors are called.

$client pmanListEventProcessors

Lists the registered event processors (SpecTcl only).

Parameters

• pattern - Optional glob pattern. If supplied, processor names must match the pattern to be included. If omitted, the match pattern defaults to * which matches everything.

Description

Returns a list of the event processors that have been registered with the dynamic pipeline subsystem. These are processors that can be added to event processing pipelines. As a side note, an event processor, can be registered to more than one pipeline.

Returns

Tcl list of event processor names. You should not rely on these to be in any order.

$client pmanUse

Select the current event processing pipeline (SpecTcl only)

Parameters

• pipeline - name of the event processing pipeline to make current.

Description

Select pipeline to be the current event processing pipeline. The current event processing pipeline is the one that SpecTcl will hand events to for processing into parameters. There can only be one current event processing pipeline. If this succeeds, the previous current pipeline is available for future use (to be made current) but is not invoked for events.

Returns

None

$client pmanAdd

Adds an event processor to an event processing pipeline (SpecTcl only).

Parameters

• pipeline - name of the event processing pipeline.
• processor - name of the event processor to add.

Description

Event processing pipelines are made up of an ordered list of event processors. This method appends an event processor to the end of the list of event processors that make up a pipeline. If or when the event processor is made current, this implies tha the event processor will be invoked to process events fromt he data source.

Returns

None.

$client pmanRemove

Removes an event processor from an pipeline (SpecTcl only).

Parameters

• pipeline - name of the pipeline to be edited.
• processor - name of the event processor to remove from the pipeline.

$client mirror

Return a list of the mirrors that are currently being served.

Parameters

• pattern - Optional, if supplied this is a glob pattern. The mirrors listed must have hosts that match pattern. If pattern is omitted, it defaults to *

Description

Both SpecTcl and Rustogramer can serve their display shared memories via a mirror server. On linux the clients are smart enough to know if a specific host is already mirroring to a local shared memory and just attach to the mirror.

This service provides a list of the mirrors active on the host to support exactly that sort of intelligence.

Returns

A list of dicts that describe the active mirror clients. Each dict contains the following keys:

• host - A host which is mirroring.
• memory - Identifies the shared memory local to the host in which the mirror is being maintained. This has the forms:
  • Four characters - the key to a SYSV shared memory segment.
  • ```sysv:`` followed by four characters, the four characters are a SYSV memory key.
  • posix: followed by a string. The string is A POSIX shared memory file.
  • file: followed by a stsring. The string is a path to a file that is the backing store for the shared memory. A mmap(2) of that file will, if permissions allow, gain access to that memory.

Description

Removes the named event processor from the named event processinug pipeline.

Returns

None.

$client pmanClear

Removes all event processors from a pipeline (SpecTcl only).

Parameters

• pipeline - name of the pipeline to clear

Description

Removes all event processors fromt he named pipeline. Once this is done, if the pipeline were current, it would do nothing.

Returns

None

$client pmanClone

Create a copy of an existing pipeline (SpecTcl only).

Parameters

• source - existing pipeline to clone.
• new - Name of the new pipeline to create.

Description

You can think of this request as a way of using an existing event processing pipeline as a starting point for the create of a new pipeline.

For example, suppose you have a pipeline named raw that has event processors that create raw parameters from the detector data in the event. Suppose further that you have event processors that create computed parameters from the raw parameters, and that during setup, you need to understand how to set treevariables to properly parameterize those event processors. You could make a new pipeline named raw+computed by cloning raw and adding the computational event processors to raw+computed.

You could, during setup, make raw current and then, once the treevariables are set, make raw+computed current at which time SpecTcl will populate the computed values.

Returns

None

$client evbCreate

Create an event builder event processor (SpecTcl only).

Parameters

• name - name of the new event processor. This must be unique amongst event processors.
• frequency - The timestamp clock frequency in floating point MHz. This is used to create some time evolution diagnostic parameters.
• basename - Textual base name for the diagnostic parameters.

Description

To understand the event builder interfaces, see the SpecTcl program reference description of CEventBuilderEventProcessor as these are the objects this set of interfaces manipulate. See also the evbunpack command in the SpecTcl command reference as that's the underlying command that these requests will invoke.

This request creates a new event processor and registers it. The event processor itself is a CEventBuilderEventProcesssor. That processor understands how to iterate over the fragments in an event and dispatch to event processors registered to handle each expected source id. The new event processor has no registered source id handlers when created.

The idea is that you can use this to unpack raw data from event built data, as e.g. the first element of some event processing pipeline that is made current.

Returns

Nothing.

$client evbAdd

Register an event processor to handle a source id for a an event builder unpacker (SpecTcl only)

Parameters

• name - name of the event build event processor created with evbCreate above.
• source - Integer source id the processor will handle.
• processor - Name of an event processor that will handle that source id.

Description

The event builder unpackers managed by this API subset have an event processor registered for each source id that is expected from the raw data. Note that for hierarchical event building, nothing stops you from using another event built event processor for the processor parameter.

This method associates an event processor, processor with fragments from the source id source. If there already was one for that source, it is no longer associated with that source. It is important to note that in spite of some mis-naming and inconsistencies in the source-code, processor is a processor not a pipeline. This is usually not a problem because:

• Usually a single processor can make the raw data for the pipeline and additional processors after the event built data processor can compute from the resulting raw unpacking.
• It is pretty trivial to have an event processor that, itself, implements a pipeline of event processors which could be registered if needed.

Returns

None

$client evbList

Lists the event builder event processors (SpecTcl only).

Parameters

• pattern - Optional glob pattern which the name of an evb event processor must match to be listed. If omitted the matching pattern defaults to * which matches everything.

Description

Lists the event builder event processors (Those reated via evbCreate) with names that match the pattern.

Returns

List of strings that are the evb event processor names.

$client command

Execute a Tcl command in the server's interpreter (SpecTcl only)

Parameters

• script - The script to execute.

Description

Executes a script in the server's interpreter.

Returns

The result of the command.

$client getVars

Return informational variables.

Parameters

None

Description

SpecTcl holds some useful information in Tcl variables. Rustogramer has muh of the same information available (in Rust data/variables). This method returns these variables.

Returns

A dict with the following keys:

• Displaymegabytes (unsigned) - Megabytes of shared memory spectrum storage.
• OnlineState (bool) - set true by some SpecTcl scripts that use attach -pipe to attach to the online DAQ system. Rustogramer sets this to false
• EventListSize - The size of the event batch. For SpecTcl this is the number of decoded events sent on each histogramming operation. For Rustogramer, the number of event ring items sent to the histogram thread in each operation.
• ParameterCount (unsigned/string)- In SpecTcl, this is the initial size used for CEvent objects, while for Rusgtogramer this is the value "-undefined-"
• SpecTclHome (string) - SpecTcl - the top level of the installation directory tree. for Rustogramer, this is the directory in which the executable was installed.
• LastSequence (unsigned/string) - Number of ring items processed in the most recent run for SpecTcl, for Rustogramer, this is "--undefined-"
• RunNumber (unsigned/string) - for SpecTcl, this is the run number of the most recently seen state change ring item. For rustogramer this is "-undefined-"
• RunState (int/string) - For SpecTcl this is nonzero if analysis is active or zero if not. For Rustogramer this is "-undefined-".
• DisplayType (string) - For SpecTcl this identifies the type of the displayer, e.g. qtpy. Rustogramer has no integrated displayer so it always returns None to be consistent with headless SpecTcl.
• BuffersAnalyzed (unsigned/string) - The total number of ring items analyzed. For SpecTcl, taken with LastSequence the fraction of events analyzed can be computed. Rustogramer returns "-undefined-"
• RunTitle (string) - Title from the most recent state change item for SpecTcl, "-undefined-" for rustohgramer.

The following statistics attributes are present in SpecTcl but not in Rustogramer:

• Statistics(EventsRejectedThisRun) (unsigned) - Number of eevents for which the event processing pipeline returned kfFALSE in this run.
• Statistics(RunsAnalyzed) - Number of times a BEGIN_RUN ring item was seen when analyzing data.
• Statistics(EventsAnalyzed) - Number of events analyzed.
• Statistics(EventsAccepted) - Number of events for which the event processing pipline returned kfTRUE
• Statistics(EventsAnalyzedThisRun) - Number of events analyzed in the current run.
• Statistics(EventsRejected) - Total number of events for which the event processing pipeline returned kfFALSE.
• Statistics(EventsAcceptedThisRun) - Number of events in this run for which the event processing pipeline retunrned kfTRUE

$client traceEstablish

Establish an interest in obtaining changes to the parameter, spectrum, bindings and gate dictionaries.

Parameters

• retention - minimum retention time for queued trace data. Note that traces may be retained longer because trace data queues are only pruned when new trace data can be queued.

Description

Traces in SpecTcl support notifying scripts of events that might require action in e.g. user interfaces. They are a mechanism to avoid having applications poll for full spectrum, gate, parameter and display shared memory bindings to understand how to update their models of what is going on in SpecTcl (e.g. Tk displays). ReST interfaces are inherently unable to directly implement the sorts of server notifications that tracing requires.

Therefore, tracing in Rustogramer and SpecTcl works as follows:

1. A client registers interest in trace data by invoking the traceEstablish request.
2. Periodically, the client polls for new traces by invoking the traceFetch request.
3. When no longer interested in trace data (e.g. on exit) the client performs a traceDone request.

Clients that have established an interest in traces are given a token to use when polling for traces and when declaring they are done with traces. In order to prevent the queued trace data from growing without bound if a client never does a traceDone request or just does not perform traceFetch requests, the ReST server associates a retention time with each client/token. When new trace data arrives, any queued trace data older than a client's retention time is removed fromt he queue.

Therefore the client should set retention to a value significantly larger than it intends to poll for new traces.

Returns

An integer trace token that should be used to identify iteself when performing tracFetch and traceDone requests.

Note it is possible for a cilent to outlast a server. When that happens, the trace token will be invalid and an attemp to do a traceFetch will fail. What to do at that point depends on the client. It could re-establish its concept of the server's state and do another traceEstablish or, more usually exit.

$client traceDone

Mark no longer interested in trace data.

Parameters

• token - The client token returned from traceEstablish.

Description

Indicates the client is no longer interseted in polling for trace data. The token passed in will no longer be valid on return.

Returns

None

$client traceFetch

Fetch client trace data

Parameters

• token - the token gotten from traceEstablish.

Description

Returns any trace data since the last invokation of traceFetch on this token. Note that if the time since the last poll was longer than the retention period specified on traceEstablish some traces may be lost.

Returns

A dict containing the following keys:

• parameter - array of parameter trace strings.
• spectrum - array of spectrum trace strings.
• gate - array of gate trace strings.
• binding - array of display bindings trace strings.

The value of each element of a trace array is a string the form of the string is:

operation target

where target is the name of the object that was affected by the operation (e.g. for spectrum traces a spectrum name)

Valid trace operations for all but binding traces are:

• add - the object was added.
• changed - the object was changed (really you'll only see this in gate traces).
• delete - the named object was deleted.

Bindings traces have these operations:

• add the named spectrum was bound into display shared memory.
• remove the named spetrum was unbound from display shared memory.

SpecTcl Command Simulation

Applications that are meant to run locally in the SpecTcl interpreter can also be easily ported to run over the ReST server using the SpecTcl command simulation package. This means that those peograms can also control Rustogramer if they stick to the set of commands for which there are functioning Rustogramer ReST services.

This section:

• Shows how to start up an application that use SpecTcl command simulation and
• Describes the set of supported commands as well as which ones are not supported by Rustogramer.

How to get started with an existing application.

This section presents a pair of sample framing scripts that show how you can use the SpecTcl command simulator to wrap existing applications.

Both scripts assume

• There is an environment variabla named RG_ROOT with a value that is the installation directory of Rustogramer.
• There is an environment variable named RG_HOST with a value that is the name of the host on which the server is runing.
• There is an environment variable named RG_REST which has the ReST port on which the server is listening for requests.

Wrapping an application using source

This wrapping assumes there is a Tcl script whose path is in the environment variable CLIENT_SCRIPT It

• Sets up the path to the SpecTclRestCommand package and includes it.
• Sets up the package to talk to the correct host and port.
• Starts the application's script using source In that case, note that the argv argument list is available to the application

#  The package directory depends on the os:
set package_dir $::env(RG_ROOT)
set os $tcl_platform(platform);   # "windows" for windows. unix for linux e.g.

if {$os eq "windows"} {
    set package_dir [file join $package_dir restclients tcl]
} elseif {$os eq "unix"} {
    set package_dir [file join $package_dir share restclients Tcl]
} else {
    error "Unsupported operating system platform:  $os"
}

# Now we can load the package:

lappend auto_path $package_dir
package require SpecTclRestCommand

#  Set up the package:

set host $::env(RG_HOST)
set port $::env(RG_REST)
set debug 0;           # 1 if you want debugging output.


SpecTclCommand::initialize $host $port $debug
maintainVariables 1

#  Start the application:

set application $::env(CLIENT_SCRIPT)
source $application

Wrapping an application using package require

This wrapping assumes that

• The application is encapsulated in a Tcl package and that loading the package will start the application.
• The application's package directory is in the envirionment variable APP_DIR
• The application's package name is APP_PACKAGE

much of the code below is identical to that of the previous example.

#  The package directory depends on the os:
set package_dir $::env(RG_ROOT)
set os $tcl_platform(platform);   # "windows" for windows. unix for linux e.g.

if {$os eq "windows"} {
    set package_dir [file join $package_dir restclients tcl]
} elseif {$os eq "unix"} {
    set package_dir [file join $package_dir share restclients Tcl]
} else {
    error "Unsupported operating system platform:  $os"
}

# Now we can load the package:

lappend auto_path $package_dir
package require SpecTclRestCommand

#  Set up the package:

set host $::env(RG_HOST)
set port $::env(RG_REST)
set debug 0;           # 1 if you want debugging output.

SpecTclCommand::initialize $host $port $debug
maintainVariables 1

#  Start the application:

lappend auto_path $::env(APP_DIR)
package require $::env(APP_PACKAGE)

Support for SpecTcl commands:

If the column labeled rustogramer support in the table below is empty, full support is available. Parenthesized notes to the right of a row refer to numbered elements of the list below the table.

+--------------------+-----------------+---------------------+
| Command            | Supported       | rustogramer support |
+====================+=================+=====================+
| apply              | Yes             |                     |
| attach             | Yes             | only -file          |
| sbind              | Yes             |                     |
| fit                | Yes             | not supported       |
| fold               | Yes             |                     |
+--------------------+-----------------+---------------------+
| channel            | Yes             |                     |
| clear              | Yes             |                     |
| project            | Yes             |                     |
| specstats          | Yes             |                     |
| treeparameter      | Yes             |                     |
+--------------------+-----------------+---------------------+
| treevariable       | Yes             | not supported       |
| filter             | Yes             | not supported       |
| gate               | Yes             | only rg gate types  |
| integrate          | Yes             |                     |
| parameter          | Yes             |                     |
+--------------------+-----------------+---------------------+
| pseudo             | Yes             | not supported       |
| sread              | Yes             | all but binary fmt  | (1)
| ringformat         | Yes             |                     |
| scontents          | Yes             |                     |
| shmemkey           | Yes             |                     |
+--------------------+-----------------+---------------------+
| spectrum           | Yes             | only rg spec types  |
| unbind             | Yes             |                     |
| ungate             | Yes             |                     |
| version            | Yes             |                     |
| swrite             | Yes             | all but binary fmt  | (1)
+--------------------+-----------------+---------------------+
| start              | Yes             |                     |
| stop               | Yes             |                     |
| roottree           | Yes             | Not supported       |
| pman               | Yes             | Not supported       |
| evbunpack          | Yes             | not supported       |
+--------------------+-----------------+---------------------+
| mirror             | Yes             |                     |
| shmemsize          | Yes             |                     |
| rootexec           | No              |                     | (2)
| isRemote           | Yes             |                     |
| tape               | No              |                     | (3)
+--------------------+-----------------+---------------------+
| ungate             | Yes             |                     |
+--------------------+-----------------+---------------------+

Notes:

1. The sread command over the ReST interface does not support doing an sread from a file descriptor that was opened by the client side script.
2. See the execCommand proc however to get SpecTcl to do that.
3. This command is deprecated in SpecTcl.

The proc maintainVariables fetches the current values of the spectcl variables. This requires an event loop such as Tk applications have or the vwait command runs for the duration of the vwait If you want to be sure that you have the current values of the SpecTcl variables; invoke updateVariables.

Traces

The SpecTcl command simulator doe support all tracing. The first time traces re requrested, the package informs the ReST server of its interest in traces. It then starts an re-triggered timed proc that fetches and dispatches any traces. All of this requires an event loop which you get in a Tk application and for the duration of a vwaitcommand.

If you are not a Tk application you can, from time to time enter the event loop for a fixed number of milliseconds using code like this:

proc updateTraces {miliseconds} {
    after $milliseconds incr ::_trace_update_variable
    vwait ::_trace_update_variable
}

...
updateTraces 100;     #  Enter event loop for 100ms.

Note that the proc updateTraces above will run for the number of milliseconds specified.

Python REST reference

Rustogramer also provides a Python ReST client. This is an object oriented wrapper for the ReST requests supported by Rustogramer and SpecTcl. In fact, the GUI uses this ReST client library.

This section provides:

• Recipies for Importing the ReST client on Linux and windows.
• Reference for the RustogramerException exception class.
• Reference for the rustogramer client class.

Importing the client

The issue to consider for being able to import the Python ReST is how to set up the import path given the installation base of the Rustogrammer package. This is because the winddows and linux installer install these in different subdirectories. Here is sample code that should work in both Windows and Linux to locate and import both the RustogramerException exception class and the client class:

The code below assumes the environment variable RG_ROOT contains the top level installation directory for rustogramer.

import os
import sys

linux_subdir   = "/share/restclients/Python"

rg_root = os.getenv("RG_ROOT")                  # 1
if rg_root is None:
    print("You must define the environment variable 'RG_ROOT'")
    exit()

if os.name == "nt":                             # 2
    import_path = os.path.join(rg_root, 'restclients', 'python')
elif os.name == "posix":
    import_path = os.path.join(rg_root, 'share', 'restclients', 'python')
else:
    print("Unsupported platform: ", os.name)

sys.path.append(import_path)                  # 3

from rustogramer_client import RustogramerException, rustogramer  # 4

The numbers in the explanatory text below refer to the numbered comments in the code fragment above.

1. This code fetches the definition of the environment variable RG_ROOT which is the top-level installation directory for Rustogramer.
2. Depending on the operating system platform, nt for windows and posix for unix/linux systems, the correct full import path is computed as the variable import_path
3. The correct import path is added to the import library search list.
4. The rustogramer_client library elements are imported into the script.

RustogramerException Reference

If an error is detected performing a transaction with the server, the rustogramer client will raise a RustogramerException this method is dervived from Exception. It includes an implemenation of the str method which allows it to be printable. For example:

< Code from the previous section to import the libraries: >

client = rustogramer({"host":"localhost", "port":8000})
try:
    version = client.get_version()
    ...
except RustogramerException as e:
    print("Interaction with the server failed:" e)
    exit(-1)

Rustogramer Client Reference

The rustogramer_client.rustogramer class is the client for rustogramer's ReST interface. Instantiating it provides a client object. Invoking the methods of that object results in transactions. Failing transactions raise a RustogramerException which, if not caught results in program termination.

• debugThe rustogramer class provides this class variable to turn on debugging. This is initialized to False if set to be True, the class will output the URIs of the requests it makes. For example

< stuff needed to import rustogramer >
rustogramer.debug = True    # I want debugging output.

Below we describe the clent methods. Note that all methods also have docstrings in the code so you can interactively get information about them from the Python help function e.g.:

help(rustogramer.condition_list)
Help on function condition_list in module rustogramer_client:

condition_list(self, pattern='*')
    Returns a list of defined conitions.  Conditions returned must
    have names that match the optional pattern parameter which is a glob pattern.
    If the pattern is omitted, it defaults to "*" which matches all gates.

init (constructor)

Description

Constructs a new instance of the client object. Note that the connection to the server is not tested. Only performing actions on the server result in connections to the server as ReST is a single transaction protocol at that level.

Parameters

• connection (dict)- This is a dict that decribes how the connection to the server will be done. The keys determine how the connection is done and where:
  • host (string) - Required - The host on which the server is running. This can be the DNS name of the system or a dotted IP address.
  • port (unsigned integer) - If using explicit port numbers the value of this key shoulid be the port number.
  • service (string) - if using NSCLDAQ service lookups, this is the name of the service. In that case, port should not be present and pmanport must be provided.
  • pmanport (unsigned integer) - the port on which the NSCLDAQ port manager is listening. If service lookup is being used, this must be present. Normally, this will have the value 30000
  • user (string) - If using NSLCDAQ service lookups and a user other than the user you are running under registered service this should be the username of the user that did.

Returns

An instance of a rustogramer class. Methods on this object can be called to perform operations with the server. In general, those operations will return a dict that has keys status and detail note that if status was not OK a RustogramerException will be raised. The useful information will be in the value of the detail key.

apply_gate

Description

Applies a gate to one or more spectra. The gate and spectrum must, of course already be defined.

Parameters

• gate_name (string)- Name of the gate to apply.
• spectrum_name (string or iterable of strings) - If a single string, this is the name of the one spectrum to which gate_name will be applied. If an iterable of strings, this will be e.g. a list of the names of the spectra to which the gate will be applied.

Returns

The detail key of the the returned dict will have nothing.

apply_list

Description

Returns a list of gate applications.

Parameters

• pattern (Optional string defaults to *) - A pattern that spectrum names must match to be inclded in the list.

Returns

The detail key of the returned dict is an iterable that contains dicts with the following keys:

• spectrum (string)- name of a spectrum.
• gate (string)- Name of the gate applied to that spectrum.

ungate_spectrum

Description

Remove any gate from one or more spectra.

Parameters

• names (string or iterable of strings) - If a single string, the spectrum with that name will be ungated. If an iterable, all of the named spectra in the iterable will be ungated.

Returns

detail has nothing useful.

get_chan

Description

Get the value of a spectrum channel.

Parameters

• name (string) - name of the specturm.
• x (number) - X channel.
• y (number, optional) - Y channel, only required if the spectrum has two axes.

Returns

detail contains a number which is the number of counts in the specified bin of the spectrum.

set_chan

Description

Sets the contents of a spectrum bin to the desired value.

Parameters

• name (string) - name of the specturm.
• x (number) - X channel.
• value (number) - counts to set in the desired channel
• y (number, optional) - Y channel, only required if the spectrum has two axes.

Returns

detail contains nothing useful.

attach_source

Description

Attach a data source for analysis. Note:

• If a data source is attached it may be detached even if this fails.
• Once a data source is attached, analysis must be explicitly started.
• Rustogramer only supports file data sources while SpecTcl supports file and pipe data sources. See Parameters below.

Parameters

• type (string) the type of data source. This can be either file or pipe.
• source (string) the source for that type:
  • If the source is file this must be the path to that file in the context of the server.
  • If the source is pipe this must be the program invocation line to run on the other end of the pipe. Note that:
    • PATH is in the context of the server.
    • The program will not have a shell.
    • The program must emit data in the format expected by the server to its stdout as that will be connected to the write end of the pipe while the server will be connected to the read end.
• format (optional string) - THe format of data produced by the source. This can be one of:
  • ring - the default if not supplied. Data comes from NSCLDAQ ring buffer based systems (NSCLDAQ 10 and later).
  • nscl - Fixed size buffers in NSCLDAQ 8 or earlier format. Only supported by SpecTcl.
  • jumbo - Fixed sized buffers in NSCLDAQ 8 or later with sizes that can be larger than 64Kbytes. Only supported by SpecTcl.
  • filter - XDR Filter format. Only supported by SpecTcl.
• size (optional unsigned) - Size of the reads done on the data source. For fixed size block formats (nscl, jumbo and filter), this must be the size of the block in the data. E.g. for nscl and filter this must be 8192. For ring this can be anything as ring items are properly assembled across block boundaries. THis is actually ignored by Rustogramer which reads one ring item at a time.

Returns

Nothing useful in detail

attach_show

Description

Describes what the attached data source is.

Parameters

None

Returns

detail is a string that contains a connection description string. For example, for a file data source, this will be something like File: <path to filename> while for a pipe: Pipe: <full program invocation string>

detach_source

Description

Detaches the current data source. What this means depends on the server. Rustogramer does support being detached from a data source while SpecTcl does not, therefore this is implemented by attaching SpecTcl to the file /dev/nulll

Parameters

None

Returns

detail is nothing useful.

start_analysis

Description

Start analyzing data from the current data source.

SpecTcl is initially attached to a test data source which supplies ring items that contains fixed size test data. When "detached", SpecTcl is actually attached to /dev/null and therefore SpecTcl will immediately see an end file.

Rustogramer, will return an error if the program is not attached to anything.

Parameters

None

Returns

detail is not useful.

stop_analysis

Description

Stops analysis from any current data source. If analysis is not active an error is returned.

Parameters

None

Returns

detail as nothing useful.

set_batch_size

Description

Rustogramer only. The input thread in Rustogramer reads a ring item at a time until a batch of ring items have been read. At that point, the entire batch of ring item data are submitted to the histograming thread for processing.

This allows the number of events in a batch to be set. Larger values are more efficient, but the histogram updates will have higher latencies. Smaller values, reduce the latency but are lesss efficient.

Parameters

• num_events Number of events in a batch.

Returns

detail contains nothing useful.

evbunpack_create

Description

Creat an event built data unpacker. This is only supported by SpecTcl and is part of the dynamic event processing pipeline subsystem. An eventbuilt data unpacker is an event processor that can assign event processors to handle data for fragments from each expected source id. Unhandled source ids are simply skipped.

Parameters

• name (string) - name by which the event processor will be referred.
• frequency (float) - The event building clock in MHz. This is used to produce diagnostic parameters.
• basename (string) - The base name from which the diagnostic parameters will be created. For example, if basename is evb_diag the timestamp in seconds for each event will be called. evb_diag.run_time

Returns

detail will contain nothing useful.

evbunpack_add

Description

Register an event processor to handle data from a source id. If one has been registered previously it is replaced. It is legal to register the same event processor to handle more than one source (though it is up to the processor to know how to use the source id to determine which parameters each source should generate). Only supported by SpecTcl

Parameters

• name (string) -name of the event built event procesor.
• source_id (unsigned) - Source id on which to register.
• processor_name (string) - name of the evnt processor that will handle fragments with the source_id specifiedl

Returns

detail has nothing useful.

evbunpack_list

Description

List the event builder unpackers. Only supported by SpecTcl

Parameters

None

Returns

detail is an iterable collection of strings. Each string the name of an event built data unpacker created via e.g. evbunpack_create.

request_exit

Description

As the server to exit. Currently this is only supported by Rustogramer. After returning the response to the request, the server will do an orderly shutdown.

Parameters

None

Returns

detail has nothing useful

filter_new

Description

Create a new filter. This is only implemented in SpecTcl.

Parameters

• name (string) - name of the filter.
• gate (string) - Gate which will select events that are written by the filter.
• parameters (iterable string collection) - Names of the parameters that will be written for each event that makes gate true.

Returns

detail is nothing useful.

filter_delete

Description

Destroys a filter. Once deleted a filter will no longer writte data. This is only implemented in SpecTcl.

Parameters

• name (string) - Name of the filter to delete.

Returns

detail contains nothing useful.

filter_enable

Description

Turns on a filter. A filter can be enabled if it is associated with an output file. Enabling a filter means that it will write events to the output file beginning with the next evnt that satisfied its gate. Only supported by SpecTcl

Parameters

• name (string)- name of the filter to enable.

Returns

detail has nothing useful.

filter_disable

Description

Turns of a filter. The filter will no longer write data to its output file until it is once more enabled. Only supported by SpecTcl

Parameters

• name (string) - name of the filter.

Returns

detail has nothing useful.

filter_regate

Description

Changes the gate that is used to select events the filter will write. Only supported by SpecTcl

Parameters

• name (string)- name of the filter.
• gate_name (string) - Name of the new gate for the filter.

Returns

detail contains nothing useful.

filter_setfile

Description

Sets the output file for the filter. Since filters are written by the server, the filename/path must make sense in the server's context. Only supported by SpecTcl

Parameters

• name (string) - name of the filter.
• path (string) - Path to the file to write, in the context of the server.

Returns

detail contains nothing useful.

filter_list

Description

List the properties of filters. Only supported by SpecTcl

Parameters

None

Returns

An iterable that contains dictionaries with the following keys:

• name (string) - name of the filter.
• gate (string) - name of the gate that determines which events are written to the filter file.
• file (string) - Path to the file the filter will write.
• parameters (iterable of strings) - Names of parameters that are being written each event.
• enabled (string) - If the filter is enabled, this will be enabled if not, disabled.
• format (string) - format of the filter file (e.g. xdr).

filter_setformat

as of 1.1.2

Description

Sets the format of a filter. Note that as the format selector is a text string, any filter formats added by the application will be usable.

Parameters

• name (string) - name of the filter.
• format (string) - name of the filter format. SpecTcl has the following filter formats baked in:
  • xdr - Exchange data representation.
  • FRIBPipe - (added with SpecTcl 5.14) - Output format of the FRIB analysis pipeline. Filter files written in this format can be analyzed directly by rustogramer.

Returns

Nothing

fit_create

Description

Creates a new fit object. SpecTcl only.

Parameters

• name (string)- name of the fit object
• spectrum (string) - name of the spectrum on which the fit is defined.
• low, high (floats) - Limits over which the fit will be performed.
• type (string) - type of fit to do. See he documentation of the fit command in the [SpecTcl command referend](https://docs.nscl.msu.edu/daq/newsite/spectcl-5.0/cmdref/index.html

Returns

detail contains nothing useful.

fit_update

Description

Recompute set of fits. SpecTcl only.

Parameters

• pattern (string) - Fits must have names that match the pattern to be updated. If not provided this defatults to * which matches all strings.

Returns

A list of dicts. Each dict describves a fit an dcontains the following keys:

• name (string)- Name of the fit.
• spectrum (string)- name of the spectrum on which the fit is computed.
• type (string) - type of the fit.
• low, high (floats) - Limits of the fit.
• parameters (dict) - Fit parameters. The keys depend on the fit type, however fits should provide a chisquare which would hold the goodness of the fit.

fit_delete

Description

Delete a fit (SpecTcl only).

Parameters

• name (string)- name of the fit to delete.

Returns

detail has nothing useful.

fit_proc

Description

Returns a Tcl proc that can be evaluated at any point to evaluate the fit (SpecTcl Only).

Parameters

• name (string) - Name of the fit.

Returns

detail contains a Tcl procedure which takes a single parameter as an argument. When called the proc will evaluate the fit at the point passed in. The proc evaulates the fit only as of the most recent update and is not dynamic (that is if you upate a fit again, you should re-fetch the proc).

fold_apply

Description

Apply a fold to a spectrum. Folded spectra must be gamma spectra.

Parameters

• fold (string) - name of the gate used to fold the gamma spectrum.
• spectrum (string) - name of the spectrum to fold.

Returns

detail contains nothing.

fold_list

Description

List the properties of folds that match the pattern.

Parameters

• pattern (string) - optional pattern that folded spectra must macth to be listed.

Returns

detail consists of an iterable of dicts. The dicts have the following keys: spectrum (string) - name of a folded spectrum. gate (string) - name of the gate folding the spectrum.

fold_remove

Description

Unfolds a previously folded spectrum.

Parameters

• spectrum (string) - name of the spectrum to unfold.

Returns

detail returns nothing interesting.

condition_list

Description

Lists the properties of conditions (gates) that have names that match a pattern.

Parameters

• pattern (string) - Names of conditions listed must match this optional pattern. If not supplied, this defaults to * which matches all strings.

Returns

An iterable containing dicts with the following keys.

• name (string) - name of the condition.
• type (string) - contidion type. See the gate command in the SpecTcl command Reference for valid type strings.
• gates (iterable) - Iterable containing strings which are the gates this condition depends on if it is a compound gate.
• parameters (iterable) - Iterable containing strings which are the parameters this condition depends on if it is a primitive gate.
• points (iterable) - Iterable containing dicts if the condition is a 2-d geometric shape. Each dict contains x - the X coordinate and y the Y coordinate of a point which are floats. These points define the acceptance region for the condition in accordance with the condition type.
• low, high (floats) - the low and high limits of the acceptance region of a condition that represents a 1D acceptance region.

condition_delete

Description

Deletes a condition.

Parameters

• name (string) - name of the gate to delete.

Returns

Nothing.

Note that if the server is SpecTcl only the appropriate keys may be present.

condition_make_true

Description

Creates a condition that is always true.

Parameters

• name (string) - Name of the new condition to create. If there is already a condition with this name it is replaced.

Returns

Nothing

condition_make_false

Description

Create a condition that is never true (always false).

Parameters

• name (string) -Name of the new condition.

Returns

Nothing

conditio_make_not

Description

Makes a condition that is the logical inverse of the dependent codition.

Parameters

• name (string) - Name of the condition being made.
• negated (string) - The name of the condition that will be negated to make this new condition.

Returns

Nothing.

condition_make_or

Description

Create an or compound gate. The condition is true when any component condition is true.

Parameters

• name (string) - name of the condition.
• components (iterable) - Iterable of the condition names that are evaluated to evaluate this condition.

Returns

None

condition_make_and

Description

Create an and condition. This condition is true only if all of its component conditions are also otrue.

Parameters

• name (string) name of the condition.
• components (iterable) - Iterable of the condition names that are evaulated.

Returns

None

condition_make_slice

Description

Create a 1-d slice gate on a parameter.

Parameters

• name (string) - name of the slice.
• parameter (string) - Parameter that must be inside the slice to make the condition true.
• low high (floats) - The low and high limits of the slice's region of acceptance.

Returns

Nothing

condition_make_contour

Description

Create a closed contour condition that is rue whenver the pair of parameters define a point that is inside the contour. Insidedness is evaluated using the odd crossing rule: A point is inside the contour if a line drawn in any direction crosses an odd number of figure boundaries. Note that zero is even for this evaluation.

Parameters

• name (string) - name of the contour codition.
• xparameter (string) -name of the parameter that will provide the x coordinate of the point.
• yparameter (string) _ name of the parameter that will provide the Y coordinate of a point.
• coords (itarable) - Iterable whose values are dicts that have the keys x and y with values that are floats that are the X and Y coordinates of the figure respectively.

Returns

Nothing.

condition_make_band

Description