myana user guide

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

ipimb    -Intensity position, intensity monitor board
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.cc - example code that makes a simple averaging histogram
main.cc - defines the functions used by myana.cc

myana_morefeatures.cc - example code that does a little more than myana.cc
examples/myana_cspad.cc - example code to read out data from the CsPad XPP detector.

myana.hh and myana.cc:

This is the "user analysis module". This is where you fill in your own code to extract the information that you want from your experiment's xtc file. This module contain only the following functions:

beginjob()     called at the beginning of an analysis job. You can for instance book histograms here.
beginrun()     called at the beginning of a run (the analysis job might analyze several runs)
begincalib() called for each calibration cycle
event()           this is where you fetch, process and store information about each event (shot).
endcalib()
endrun()
endjob()
In the example, a profile histogram is booked in beginjob() and voltage vs. time is filled in each event. The profile histogram displays the average value of all events.

main.hh and main.cc

This is the main control of the analysis, but you should avoid editing this file. After the all utility functions (in main) and user functions (in myana) have been read, main() is executed and controls the flow of the analysis. For each xtc file it calls

anafile(xtcname, maxevt, skip, iDebugLevel);

which iterates through the xtc file, keeps track of all the datagrams in it, and makes sure to execute your beginjob() and event() functions.

myana_morefeatures.cc

This version of the "user analysis module" shows how to obtain some more information from the xtc file:
beginjob():

• we book a profile histogram for AMO Ion Time-of-flight (AmoITof) waveform data, and also five regular histograms to fill with single event data from the first five events. To do this we need some information about the AmoITof configuration, which is obtained using the getAcqConfig(). This gives us the number of channels that were used, number of samples and sampling intervals, all needed to book the histogram.
• also a constant-fraction histogram is booked for AmoITof. This has it's own fill function, as we shall see from the event() function.
• For the Electron Time-of-flight detector (AmoETof), we similarly get the configuration data and make one profile histogram for each channel used.
• Also get config information about the Magnetic bottle electron spectrometer (AmoMbes).
• A Princeton camera and a fast CCD (FCCD) was also in use. These have their own getConfig functions: getPrincetonConfig( DetInfo::SxrBeamline, ...) and getFccdConfig(SxrFccd, ...).
  In beginrun() we get the config info from AmoITof again, to check if it changed between runs in the same job.

event():

• fills the histograms booked at the beginning of the job: getAcqValue() gets the data from a given detector for each event. The main program is already keeping track of which event we're processing at the time. The constant-fraction histogram is filled by the function fillConstFrac(), defined in main.cc. This histogram is filled with the boundary position each time the pulse crosses the threshold,
• the rest of event() uses a lot of get-functions to show how to use some of these. Generally, they all give you values through scalar or array variables passed as arguments to the functions. The example doesn't show what you would use this information for, but you might already know that

myana_etof.cc
More histogram building for ETof Acquiris

myana_itof.cc, myana_bin.cc
More ITof Aquiris averaging, and more about binning

myana_mbes.cc
Magnetic electron bottle spectrometer (Mbes) Acquiris, time resolved binning

myana_esort.cc, myana_bin.cc
Energy binning for Mbes Acquiris

ACQexp.cc, EXSavg.cc, (or EXSavgOMP.cc  for parallel processing)
Opal image processing, projections, image export

examples/myana_tuple.cc
Example of how to store several variables in a root NTuple for further processing (histogramming, correlation studies etc.).

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

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.

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):

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

There are several getters for various image data:

getFrameValue -  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.
getOpal1kValue - an alias for getFrameValue
getTm6740Value - an alias for getFrameValue
getCspadQuad   - 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).

• FrameDetector (general):

  int getFrameConfig   (FrameDetector det);
  int getFrameValue(FrameDetector det, int& frameWidth, int& frameHeight, unsigned short*& image );
  

  fetches an image from the FrameDetector of your choice.
  Specify the detector (using an appropriate enum), and getFrameValue will direct your pointers to the width and height of the image as well as the start of the pixel array.

  Other frame detectors:
    AMO:
        AmoVmi
        AmoBps1
        AmoBps2
    SXR:
        SxrBeamlineOpal1
        SxrBeamlineOpal2
        SxrEndstationOpal1
        SxrEndstationOpal2
        SxrFccd
     XPP:
        XppSb1PimCvd
        XppMonPimCvd
        XppSb3PimCvd
        XppSb4PimCvd
  

• XPP CsPad detector:

   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);
  

  For an example of how to draw an image as a 2D root histogram, see the myana_cspad.cc example.

• Fast CCD camera:

   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 .

• PnCCD camera (used by CAMP):

   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.