Page History
Wiki Markup |
---|
*{_}This page is under construction._* h5. Introduction LCLS Data Analysis frameworks are under development, and currently three approaches are being used and/or developed: * myana ... simple C+\+ code to read 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|https://confluence.slac.stanford.edu/display/PCDS/Pyana+User+Manual] ... python-based analysis framework. Anticipate more tools and examples to appear for this one. * PSAna ... C++-based analysis framework, still in the design phase. Currently only myana and pyana are usable for analysis. 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. 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 it. How to set up your own myana executable is explained in the DAQ section ["A Simple Online Analysis Example"|https://confluence.slac.stanford.edu/display/PCDS/A+Simple+Online+Analysis+Example]. myana makes use of the pdsdata library to read the datagrams from the xtc file. {panel} h6. pdsdata - 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. {panel} h5. 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. h6. MyAna .... C+\+ program to extract information from xtc file myana.cc -This example codefetches todata makefor aeach simpleevent averaging histogram myana_morefeatures.cc - example code that doesand writes it to a little more. main.cc - definesroot histogram and stores the functionshistogram in useda byroot myana.cc Here's a brief description of the functions of myana.cc and main.cc: * myana.hh,cc: This is the "user analysis module". It reads through the xtc sequencially, and records the information according to user choice. You can't access a given event (shot) randomly, not until you've made a first pass through all the events and stored the information in your format of choice. This module contain only the following functions: beginjob() called at the beginning of an analysis job. E.g. 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 information about each event (shot). endcalib() endrun() endjob() The example here fetches data from devices for each event and writes it to a root histogram. You may want to store the information in e.g. a root ntuple for further processing. Or to some other format that you'd like to work with (ascii file, ... ). * main.hh,cc: All control and utility functions are defined in these files. The main() function is executed first, but after all other functions have been read. It calls the follwing function which controls the analysis: 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, ... ). myana.cc - example code to make a simple averaging histogram myana_morefeatures.cc - example code that does a little more. main.cc - defines the functions used by myana.cc Here's a brief description of the functions of myana.cc and main.cc: myana.hh,cc: {panel} This is the "user analysis module". It reads through the xtc sequencially, and records the information according to user choice. You can't access a given event (shot) randomly, not until you've made a first pass through all the events and stored the information in your format of choice. This module contain only the following functions: {{beginjob()}} -- called at the beginning of an analysis job. E.g. 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 information about each event (shot). {{endcalib()}} --- {{endrun()}} --- {{endjob()}} --- {panel} main.hh,cc: {panel} After the all utility functions (in main) and user functions (in myana) have been defined / read, main is executed and controls the flow of the analysis. For each xtc file it calls {{anafile(xtcname, maxevt, skip, iDebugLevel); This}} which iterates through the xtc file, keeps track of all the datagrams in it, and makes sure to execute your {{beginjob()}} and {{event()}} functions and any others you might have implemented in your myana.cc file. . {panel} All the functionality needed to get data from the xtc file is defined in main and in the files it includes (all in the package pdsdata (PDS == photon data system)). You get a list of all the available functions by looking at main.hh (implementations are in main.cc). Here are a few lines of explanation for \*a few of\* the functions defined in main: Enums: These define number mapping for each detector. E.g. AcqDetector::AmoIms is equivalent to the constant 0. You are encouraged to use the names instead of the numbers, in case the underlying order changes in a new version of the program. Configuration and L1Accept Data retrieval functions: \-----------------------------------------------------------------------------------------------------\- Acquiris digitizer -----------------------------------------------------------------------------------------------------\- int getAcqConfig (AcqDetector det, int& numChannels, int& numSamples, double& sampleInterval); --> fetches the configuration information for any of the Acquiris devices. Checks that the detector has been used / has data, and tells you the number of channels used, number of samples collected and the sample interval. This is typically done in the myana::beginjob() or myana::beginrun() functions. Specify with enum which device you want information from, and supply a pointer to two integers and a double: numChannels, numSamples, sampleInterval. 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: Specify with enum which device you want the information from, and an integer to store channel information, as well as pointers two arrays of doubles. These will be filled with time and voltage information, respectively. Optional: to also get the trigger time, you can supply a \*double as a fifth argument. 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 \-----------------------------------------------------------------------------------------------------\- Any particular hardware? -----------------------------------------------------------------------------------------------------\- int getFrameConfig (FrameDetector det); --> Checks that the xtc file has got data from this device. 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), give pointers to int frame width, frame height and short imgage of the Camera::FrameV1. Other frame detectors: AMO: AmoVmi AmoBps1 AmoBps2 SXR: SxrBeamlineOpal1 SxrBeamlineOpal2 SxrEndstationOpal1 SxrEndstationOpal2 SxrFccd XPP: XppSb1PimCvd XppMonPimCvd XppSb3PimCvd XppSb4PimCvd -----------------------------------------------------------------------------------------------------\- Princeton camera -----------------------------------------------------------------------------------------------------\- 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); --> -----------------------------------------------------------------------------------------------------\- Ipimb detector -----------------------------------------------------------------------------------------------------\- int getIpimbConfig(Pds::DetInfo::Detector det, int iDevId); --> int getIpimbVolts(Pds::DetInfo::Detector det, int iDevId, float &channel0, float &channel1, float &channel2, float &channel3); --> -----------------------------------------------------------------------------------------------------\- Encoder detector -----------------------------------------------------------------------------------------------------\- int getEncoderConfig (Pds::DetInfo::Detector det, int iDevId); \--> int getEncoderCount(Pds::DetInfo::Detector det, int iDevId, unsigned int& encoderCount); \--> -----------------------------------------------------------------------------------------------------\- Other functions that do not require (or have) configuration -----------------------------------------------------------------------------------------------------\- int getFeeGasDet (double\* shotEnergy); --> Gives you the shot energy to the array shotEnergy\[4\]. This information is obtained from the Front End Enclosure Gas Detector. int getEBeam(double& charge, double& energy, double& posx, double& posy, double& angx, double& angy); int getEBeam(double& charge, double& energy, double& posx, double& posy, double& angx, double& angy, double& pkcurr); \--> Gives electron beam values for each of these doubles. The measured charge of the beam (in nC), the measured energy of the beam (in MeV), the 2D position of the beam (in mm) away from the origin (nominal beam position), and 2D angular position (in mrad) off the assumed direction. and the pkcurr = current? in (Amps) int getPhaseCavity(double& fitTime1, double& fitTime2, double& charge1, double& charge2); --> Gives you the phase cavity fit time (low and high?) and charges (before and after?). int getPnCcdValue (int deviceId, unsigned char*& image, int& width, int& height ); int getEvrDataNumber(); int getEvrData ( int id, unsigned int& eventCode, unsigned int& fiducial, unsigned int& timeStamp ); -----------------------------------------------------------------------------------------------------\- EPICS -----------------------------------------------------------------------------------------------------\- Get integers, floats, strings from any EPICS channel (PV = process variable) int getPvInt (const char\* pvName, int& value); int getPvFloat (const char\* pvName, float& value); int getPvString (const char\* pvName, char*& value); /\* * Control data retrieval functions \*/ int getControlPvNumber(); int getControlPvName ( int pvId, const char*& pvName, int& arrayIndex ); int getControlValue (const char\* pvName, int arrayIndex, double& value ); int getMonitorPvNumber(); int getMonitorPvName ( int pvId, const char*& pvName, int& arrayIndex ); int getMonitorValue (const char\* pvName, int arrayIndex, double& hilimit, double& lolimit ); /\* * Advanced Interface \*/ int getEpicsPvNumber(); int getEpicsPvConfig( int iPvId, const char*& sPvName, int& iType, int& iNumElements ); int getEpicsPvValue ( int pvId, const void*& value, int& dbrype, struct tm& tmTimeStamp, int& nanoSec ); void fillConstFrac(double\* t, double\* v, unsigned numSamples, float baseline, float thresh, TH1\* hist); void fillConstFrac(double\* t, double\* v, unsigned numSamples, float baseline, float thresh, double\* edge, int& n); main.{hh,cc} defines a class myLevelIter, which inherits from XtcIterator. A utility class to traverse the xtc file. It has several process memeber functions, depending on which detector is being used. The MAIN function is making an output root file with the same name as the input xtc file. You can control through the myana.cc file what gets stored in the root output file. The main function calls the function anafile for one xtc file or for a list of xtc files. anafile opens the xtc file, makes and XtcFileIterator object, and loops through all the datagrams in the file. Each datagram corresponds to one event? EPICS = Experimental Physics and Industrial Control System, used for control of hardware, and EPICS also outputs all kinds of hardware related values, like voltages and currents at all given times of data collection. Example to get the value from a given Epics channel (e.g. "SXR:EXP:MMS1.RBV") for a given event, within the event() function, do: // get one PV float value; fail = getPvFloat( "SXR:EXP:MMS1.RBV", value ); This gives the value to your declared float 'value'. * Get encoder data for DetInfo::SxrBeamline device ID 0 \*/ unsigned int count; fail = getEncoderCount(DetInfo::SxrBeamline, 0, count); |
Overview
Content Tools