Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Include Page
codeillustratorDev
codeillustratorDev

Info

Draft, in work.

Table of Contents

Include Page
Xtc Topic Map
Xtc Topic Map

Major Xtc Library Classes

In the Xtc library, the most important data containers and associated classes are:

  • XtcData:Dgram, which is the root container, essentially an envelope, for other containers.
  • XtcData:Xtc, the parent data container class for detector data and descriptive metadata.
    • XtcData:TypeId is used to identify which flavor of Xtc container listed below is being worked with when recording or parsing.
    • XtcData:Names, derived Xtc container for storing named metadata about data types and data dimensionality.
    • XtcData:ShapesData, a derived convenience Xtc container with methods to access detector data.
      • XtcData:Shapes, a derived Xtc container containing metadata about the structure of the raw detector data.
      • XtcData:Data, a derived Xtc container for raw detector data itself.
Deck of Cards
idsetup
Card
defaulttrue
idxtcdatadgrm
labelXtcData:Dgram


Card
idxtcdatanameshapesdata
labelXtcData:Names, :Shapes, :Data

The DAQ Side: Generating Xtc

For tutorial purposes, the following streamlined example shows XXX. For an example involving more detectors, formats and algorithms, see xtcdata/xtcdata/app/xtcwriter.cc.

A Notional DAQ Harness

Let's motivate the example. Assume we're developing a an Xtc writer class to output HSD data. This class will get plugged in to a (notional) DAQ framework.

Code Block
languagecpp
linenumberstrue
// %sample:intro:cpp%
// Assume some totally made-up data acquisition callback framework named DAQFramework
// Developers of the psdaq package are welcome to come in and change this toy example
// to match the real DAQ API.

HSDXtcWriter hsdwriter()

DAQFramework.registerHandler("configure", hsdwriter.setup)
DAQFramework.registerHandler("runstart", std::bind(hsdwriter.openXtcFile, filename))
// Assume we get a "readout" message per event
DAQFramework.registerHandler("readout", hsdwriter.writeFeature)
DAQFramework.registerHandler("runend", hsdwriter.closeXtcFile)

//%endsample%

"setup" Method: Set Up The Names Structure

Deck of Cards
idsetup
Card
defaulttrue
labelCoding Steps

Register the algorithms and "shape" of the data associated with detector elements so the processing pipeline knows what to do with it.

  1. First some plumbing. Here, for example, in a constructor:
    1. Declare an XtcData:Dgram as the root container for metadata (see %codesample1:14,15,38,39,45:setupexamples%). 
    2. And call a utility method to actually create and set up this metadata Dgram (see %codesample1:14,15,38,39,43,44,45,46-56:setupexamples%).
    3. Set aside a vector to store some XtcData:Names we use to annotate this data (see %codesample1:14,15,40,45:setupexamples%).
  2. In the setup method itself, call an internal method to actually populate this configuration structure. See %codesample1:85-89,68-83:setupexamples%. 
    1. We create an Xtc:Alg to record a specific feature extraction algorithm name, "fex", and version, 4.5.6, needed to process this data.
Card
idsetuptldr
labelTL;DR
Panel
  • XtcData::Dgram is your root container for metadata (Names and Shapes) as well as the data itself
  • Sub-class from XtcData::VarDef to define data shapes
    • VarDef gives you a NameVec with push_back() method to xxxx

 

 

"writeFeature" Method: Respond to Readout Events and Add Readout ShapesData and Data

Deck of Cards
idwritefeature
Card
defaulttrue
labelCoding Steps

(Introduce CreateData and its set_value (assign values explicitly) and allocate (set aside structured memory for the data then full in the structure with values) methods here. What about set_array_shape? With FexDef, we're positing that the data coming out has a well-defined shape, i.e. definable as a record, so per-event, you will update and emit this data record into the output stream)

Another list of steps/big ideas this time about appending data.

  1. .
  2. A chunk of code summary.

 

Card
idwritefeatureid
labelTL;DR
Panel
  • Use CreateData for XYZ applications:
    • set_value() for scalar data
    • allocate() for data vectors or matrices
  • Use DescribedData for XYZ applications

The Pipeline Side: Parsing Whole Xtc Files, Using Small Data Files

xtcreader.cc and XtcIterator.hh

A Notional Offline Pipeline Harness


Notes for Real-World Code

Realistic Xtc Writers

(Bullet lists of gotchas and recommendations)

  • Thread safety issue #1
  • Thread safety issue #2
  • (You'll likely need to sub-class from XYZ in order to ABC)

Realistic Xtc Readers

(Bullet lists of gotchas and recommendations)

  • Thread safety issue #1
  • Thread safety issue #2
  • (You'll likely need to sub-class from XYZ in order to ABC)

Full "Hello Xtc" Code Listings

HSDXtcWriter Example

Code Block
languagecpp
linenumberstrue
// %sample:codesample1:cpp%

#include "xtcdata/xtc/ShapesData.hh"
#include "xtcdata/xtc/DescData.hh"
#include "xtcdata/xtc/Dgram.hh"
#include "xtcdata/xtc/TypeId.hh"
#include "xtcdata/xtc/XtcIterator.hh"
#include "xtcdata/xtc/VarDef.hh"

using namespace XtcData;

#define BUFSIZE 0x4000000

HSDXtcWriter::HSDXtcWriter()
{
	// Define the "signature" of the data in
    // our feature extraction data set
	class FexDef:public VarDef
	{
		public:
		  enum index
		  {
			  floatFex,
		      arrayFex,
		      intFex
	      };

		FexDef()
   		{
       		NameVec.push_back({"floatFex",Name::DOUBLE});
			NameVec.push_back({"arrayFex",Name::FLOAT,2});
			NameVec.push_back({"intFex",Name::INT64});
		}
	};

	// Define some instance variables.
	FILE *this->xtcoutfile;
	// An Xtc::Dgram to store metadata about the output
	Dgram& this->metadataDgram;
	std::vector<NameIndex>& this->namesVec;
	this->FexDef = new FexDef();

	// Now initialize various things
	_initializeMetadataDgram();
}

void HSDXtcWriter::_initializeMetadataDgram()
{
	TypeId tid(TypeId::Parent, 0);
	void* configbuf = malloc(BUFSIZE);

    this->metadataDgram = *(Dgram*)configbuf;
	this->metadataDgram.xtc.contains = tid;
    this->metadataDgram.xtc.damage = 0;
    this->metadataDgram.xtc.extent = sizeof(Xtc);
}

void HSDXtcWriter::_initializeReadoutDataDgram()
{
	TypeId tid(TypeId::Parent, 0);
	void* buf = malloc(BUFSIZE);

    this->metadataDgram = *(Dgram*)buf;
	this->metadataDgram.xtc.contains = tid;
    this->metadataDgram.xtc.damage = 0;
    this->metadataDgram.xtc.extent = sizeof(Xtc);
}

void HSDXtcWriter::_addNames(Xtc& parent, std::vector<NameIndex>& aNamesVec)
{
	// Instantiate an Alg to define metadata for
    // a feature extraction ("fex") algorithm
	Alg hsdFexAlg("fex",4,5,6);
	// Create a Names structure that identifies
    // the location, algorithm, detector type
    // and detectorID.
	Names& fexNames = *new(parent) Names("xpphsd", hsdFexAlg, "hsd", "detnum1234")
	// And now we add the Names structure to the
    // parent Xtc metadata container along with
    // the FexDef data signature.
	fexNames.add(parent, this->FexDef);
    aNamesVec.push_back(NameIndex(this->fexNames));
}

void HSDXtcWriter::setup()
{
	// Add a Names structure to the configuration Dgram
	_addNames(this->metadataDgram.xtc, this->namesVec);
}

void HSDXtcWriter::openXtcFile(xtcoutfilename)
{
	this->xtcoutfile = fopen(xtcoutfilename, "w");
}

void HSDXtcWriter::writeFeature()
{

	// Need some makebelieve code here to show how this
    // callback method unpacks data from DAQ
	// to cram into these Xtc structures...

	// Talk to Chris. Is this event by event? Would you want
    // to destruct this CreateData after each event?
 	CreateData fex(parent, NamesVec, nameId);

	// set_value() lets you set scalar values in the data record.
    // The 'floatFex' ID is defined in our custom FexDef class.
	fex.set_value(FexDef::floatFex, (double)41.0);

	// Use allocate() to set up data that's better represented as
    // vectors or matrices.
    // The 'arrayFex' ID is defined in our custom FexDef class.
	unsigned shape[MaxRank] = {2,3}; //MaxRank is an Xtc library
                                     //global upper limit on data complexity.
    Array<float> arrayT = fex.allocate<float>(this->FexDef::arrayFex, shape);
    for(unsigned i=0; i<shape[0]; i++){
        for (unsigned j=0; j<shape[1]; j++) {
            arrayT(i,j) = 142.0+i*shape[1]+j;
        }
    };
	
	// Another scalar value setter.
    // The 'intFex' ID is defined in our custom FexDef class.
	fex.set_value(FexDef::intFex, (int64_t) 42);

}

void HSDXtcWriter::closeXtcFile()
{
	fclose(this->xtcoutfile);
}

// ...
// %endsample%

HSDXtcReader Example

Code Block
languagecpp
linenumberstrue
// %sample:codesample2:cpp%
	cout<<"Hi world?"
// %endsample%