Versions Compared

Old Version 81

changes.mady.by.user Unknown User (ofte)

Saved on

compared with

New Version 82

changes.mady.by.user Unknown User (ofte)

Saved on

Key

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

Introduction

LCLS Data Analysis frameworks are under development, and . The currently three supported approaches are being used and/or developedfor analysis of LCLS data are:

  • myana ... simple — A C++ code program to read analyze an xtc file. Provided (and used) by the DAQ group. Will likely be expanded in support of new hardware etc., and more examples might be provided, but otherwise no big changes anticipated.
  • pyana ... python-based analysis framework. Anticipate more tools and examples to appear for this one.
  • How to set up your own myana executable is explained in the DAQ section "A Simple Online Analysis Example" .
  • pyana — A python-based analysis framework. Pyana User Manual
  • PSAna — A PSAna ... C++-based analysis framework, still in the design phase.

...

  • Not usable yet.

This document attempts to explain some of the names and functions found in the myana code as well as the structure of the data file (xtc) and how to extract useful information from itand give some working examples on how to set up your analysis software. And we try to explain the structure of the data file and how to extract useful information from your data.

In several of these examples, we fill root (histograms or NTuples. For more information on root, see http://root.cern.ch) histograms or NTuples.

Disclaimer: There is no more complete or up-to-date documentation than the code itself, so regard this document as an introduction and a user guide, not a complete documentation.

How to set up your own myana executable is explained in the DAQ section "A Simple Online Analysis Example".

myana makes use of the pdsdata library to read the datagrams from the xtc file.

Panel

pdsdata (pds = photon data system)
a library consisting of the follwing utility packages:

ipimb    - Intensity position, intensity monitor board
encoder  - SXR SLE Info (Laser Mirror Position Encoder)
pnCCD   - for device used by CAMP
acqiris     - software for the aquiris digitizer hardware. Waveform data.
camera   - camera frames, configurations, feature extractions process
evr         - Event Receiver (event code, beam code?)
opal1k     - for Opal camera
pulnix      - for Pulnix TM6740CL monochrome camera
control    - utility for DAQ control, PV (process variable) control and monitoring
xtc          - This package defines all the datagrams for the xtc file.
epics      - interface to epics (process variables (PV))
bld         - defines some build data classes
princeton - software for the Princeton camera
fccd        - LBNL/ANL Fast CCD monochrome camera
cspad      - driver for the CsPad detector
lusi         - LCLS Ultrafast Science Instruments Configs for diode, ipm, pim.
app        - Xtc and Epics readers

The header files are in the top level directories of each package, and the
implementation files are in the src directory of each package.

xtc

The data from all the LCLS experiments are stored in xtc (extended container) files. These files contain "datagrams" which are an object of some type (TypeId) with associated status (Damage), source (Src) and extent (size). It is not an indexed file and does not provide random access, and can only be read seqencially. Thus, the example way to read the file shown here makes use of 'myana', a C++ executable that reads through the whole file and picks out the requested information. You can make your own version of 'myana' to extract other information.

You can explore the contents of an xtc file by using the xtcreader utility:

Code Block

pslogin ~ >  xtcreader -f myxtcfile.xtc | less

Reading through the output, you may see sections describing the various transitions in datataking. Look for these "headings" in the text output:

...

Tha data file format: xtc

The data recorded from the LCLS experiments are stored in xtc (extended container) files. These files contain "datagrams" which are an object of some type (TypeId) with associated status (Damage), source (Src) and extent (size). It is not an indexed file and does not provide random access, and can only be read seqencially, one event (shot) at a time.

You can explore the contents of an xtc file by using the xtcreader utility:

Code Block

pslogin ~ >  xtcreader -f myxtcfile.xtc | less

Reading through the output, you may see sections describing the various transitions in datataking. Look for these "headings" in the text output:

  • Configure transition
  • BeginRun transition
  • BeginCalibCycle transition
  • Enable transition
  • L1Accept transition — This is the event data. Each event starts with "L1Accept transition:". From the text that follows, you can get an idea of what detector data is in the xtc file.

You also have the option of converting your experiments' xtc files into hdf5 files. More about data formats: Analysis Workbook. Data Formats

The pdsdata library

The pdsdata (pds = photon data system) library contains all classes needed to read the xtc datagrams. In your analysis directory you'll find it in release/pdsdata/.

Panel

ipimb    - Intensity position, intensity monitor board
encoder  - SXR SLE Info (Laser Mirror Position Encoder)
pnCCD   - for device used by CAMP
acqiris     - software for the aquiris digitizer hardware. Waveform data.
camera   - camera frames, configurations, feature extractions process
evr         - Event Receiver (event code, beam code?)
opal1k     - for Opal camera
pulnix      - for Pulnix TM6740CL monochrome camera
control    - utility for DAQ control, PV (process variable) control and monitoring
xtc          - This package defines all the datagrams for the xtc file.
epics      - interface to epics (process variables (PV))
bld         - defines some build data classes
princeton - software for the Princeton camera
fccd        - LBNL/ANL Fast CCD monochrome camera
cspad      - driver for the CsPad detector
lusi         - LCLS Ultrafast Science Instruments Configs for diode, ipm, pim.
app        - Xtc and Epics readers

The header files are in the top level directories of each package, and the
implementation files are in the src directory of each package

...

.

MyAna .... C++ program to extract information from xtc file

This example fetches data for each event and writes it to a root histogram and stores the histogram in a root file. You may want to store your data differently, e.g. one histogram for each event, or everything in a root ntuple for further processing. Or you can write some other format that you'd like to work with (ascii file, ... ).

...

Panel

examples/myana_cspad.cc, examples/CspadTemp.cc, examples/CspadTemp.hh
CsPad image

...

Configuration and L1Accept Data retrieval functions:

The following contains a few lines of explanation for some of the functions defined in main.
But first some general remarks:

  • Most of the functions return 0 if it was a successful function call, any other number means it failed.
  • Wiki Markup
    Values are obtained through the arguments of the function calls. E.g. declare an array in your myana.cc, and {{getXXXValue(&myarray\[0\])}} will fill the array for you.
  • Enums: Several of the functions can be used to extract data from several of the detectors. Which detector is specified by an enum (named constant integers). You are encouraged to use the names instead of the numbers, in case the underlying order changes in a new version of the program.
panel
Panel
Acquiris digitizer
Code Block
int getAcqConfig(AcqDetector det, int& numChannels, int& numSamples, double& sampleInterval);

Fetches the configuration information for any of the Acquiris devices. Returns 1 if the requested detector does not exist, and 2 if it was not in use. Tells you the number of channels used for this device, the number of samples collected and the sample interval. This is typically done in the beginjob() or beginrun() functions.

Code Block
int getAcqValue(AcqDetector det, int channel, double*& time, double*& voltage);
int getAcqValue(AcqDetector det, int channel, double*& time, double*& voltage, double& trigtime);

Fetches waveform data from any of the Acquiris devices. Fills your arrays with the waveform time and voltage, and optionally gives you the trigger time.

In the myana.cc example, we fetch data from the AmoITof device (AMO Ion Time-of-flight).
Other Acquiris devices (see main.hh for an up-to-date list):

Code Block
AMO:
   AmoIms      - ion momentum spectrometer
   AmoGasdet   - gas detector (in the Front End Enclusure)
   AmoETof     - electron time-of-flight
   AmoMbes     - magnetic bottle electron spectrometer
   AmoVmiAcq   - (Vmi = Velocity mapping imaging)
   AmoBpsAcq   - (Bps = Beam position screen)
   Camp        - for the CAMP experimental setup
SXR:
   SxrBeamlineAcq1
   SxrBeamlineAcq2
   SxrEndstationAcq1
   SxrEndstationAcq2
panel
Panel
Image data

There are several getters for fetching image data from the xtc file. Depending on which camera was in use, one of these should be appropriate:

  • Opal1000 camera:
    getOpal1kValue (an alias for getFrameValue)
  • Which camera?
    getTm6740Value (an alias for getFrameValue)
  • FrameDetector (general):
    Code Block
    int getFrameConfig   (FrameDetector det);
int getFrameValue(FrameDetector det, int& frameWidth, int& frameHeight, unsigned short*& image );
    Gives you the width and height (in pixels) of the image, and a pointer to the start of the pixel array of a Pds::Camera::FrameV1 object. Specify the detector (using an appropriate enum).
    Code Block
    Available frame detectors:
  AMO:
      AmoVmi
      AmoBps1
      AmoBps2
  SXR:
      SxrBeamlineOpal1
      SxrBeamlineOpal2
      SxrEndstationOpal1
      SxrEndstationOpal2
      SxrFccd
   XPP:
      XppSb1PimCvd
      XppMonPimCvd
      XppSb3PimCvd
      XppSb4PimCvd
  • XPP CsPad detector:
    Code Block
     namespace Pds { namespace CsPad { class ConfigV1; }}
 int getCspadConfig (Pds::DetInfo::Detector det, unsigned& quadMask, unsigned& asicMask);
 int getCspadConfig (Pds::DetInfo::Detector det, Pds::CsPad::ConfigV1& cfg);

 namespace Pds { namespace CsPad { class ElementV1; }}
 int getCspadQuad  (Pds::DetInfo::Detector det, unsigned quad, const uint16_t*& pixels);
 int getCspadQuad  (Pds::DetInfo::Detector det, unsigned quad, const Pds::CsPad::ElementV1*& data);
    Gives you a pointer to the first position in the array of pixel data from the XPP CsPad detector (or alternatively you can get a pointer to the Pds::CsPad::ElementV1 object itself).
    For an example of how to draw an image as a 2D root histogram, see the myana_cspad.cc example.
  • Fast CCD camera:
    Code Block
     int getFccdConfig(FrameDetector det, uint16_t& outputMode, bool& ccdEnable,
                  bool& focusMode, uint32_t& exposureTime,
                  float& dacVoltage1, float& dacVoltage2, float& dacVoltage3, float& dacVoltage4,
                  float& dacVoltage5, float& dacVoltage6, float& dacVoltage7, float& dacVoltage8,
                  float& dacVoltage9, float& dacVoltage10, float& dacVoltage11, float& dacVoltage12,
                  float& dacVoltage13, float& dacVoltage14, float& dacVoltage15, float& dacVoltage16,
                  float& dacVoltage17,
                  uint16_t& waveform0, uint16_t& waveform1, uint16_t& waveform2, uint16_t& waveform3,
                  uint16_t& waveform4, uint16_t& waveform5, uint16_t& waveform6, uint16_t& waveform7,
                  uint16_t& waveform8, uint16_t& waveform9, uint16_t& waveform10, uint16_t& waveform11,
                  uint16_t& waveform12, uint16_t& waveform13, uint16_t& waveform14);
    Configures the information from the Fast CCD. Fills arguments with values depending on how the image/waveform data were taken. There is no getFccdValue in main.hh, so I think you need to use getFrameValue for this(question) .
  • PnCCD camera (used by CAMP):
    Code Block
     int getPnCcdValue (int deviceId, unsigned char*& image, int& width, int& height );
    This camera has 4 links, each link provides a 512 x 512 x 16 bit image. This function combines the four images to a single 1024 x 1024 x 16 bit image.
    deviceId can be PnCcd0 or PnCcd1, width and height are the number of pixels in each direction.
  • Princeton camera:
    Code Block
    int getPrincetonConfig(Pds::DetInfo::Detector det, int iDevId,
                       int& width, int& height, int& orgX, int& orgY, int& binX, int&binY);
int getPrincetonValue(Pds::DetInfo::Detector det, int iDevId, unsigned short *& image);
int getPrincetonTemperature(Pds::DetInfo::Detector det, int iDevId, float& temperature);
    fetches the configuration and data from the camera. getPrincetonTemperature is there to check the temperature of the camera at the time of data taking (not necessarily available for every shot).

...