...

The first just dumps datagram headers, the latter dumps xtc headers. There are some additional options, how much of the xtc payloads to print, and if you want parsed output for epics. A help string is available by typing xtclinedump with no arguments. Except for the non-default epics argument, xtclinedump does no parsing of the xtc payloads, it simply prints the first few bytes in hex. For reading through payloads, the intel architechture uses little endian, so 0x00040000 = 1024,

Package TimeTool

Note: specific examples for the time tool can be found in /reg/g/psdm/sw/releases/ana-current/TimeTool/examples/.

Modules for analyzing recorded data from a timetool camera setup. The timetool camera measures the time difference between laser and FEL in one of two methods:

1. spatial encoding, where the X-rays change the reflectivity of a material and the laser probesthat change by the incident angle of its wavefront; or
2. spectral encoding, where the X-rays change the transmission of a material and the chirped laser probes it by a change in the spectral components of the transmitted laser.

Below the package modules are described. The package includes sample configuration files that describe all the options. From a psana release directory, users are encouraged to add the TimeTool package to obtain the latest source. For instance:

newrel ana-current myrel
cd myrel
kinit             # get ticket to check out package from svn repository
addpkg TimeTool
sit_setup
scons
# now examine the files in TimeTool/data:  sxr_timetool.cfg  sxr_timetool_setup.cfg  timetool_setup.py  xpp_timetool.cfg  xpptut.cfg

 timetool_setup.py is a python script to calculate the digital filter weights.

Module Analyze

A module that analyzes the camera image by projecting a region of interest onto an axis and dividing by a reference projection acquired without the FEL.  The resulting projection is processed by a digital filter which yields a peak at the location of the change in reflectivity/transmission.  The resulting parameters are written into the psana event. The type of the parameter depends on the release. Starting with ana-0.13.10, a TimeTool::DataV2 object in put in the event store. ana-0.13.3 put a TimeTool::DataV1 object in the event store. In ana-0.14.4 and later, this is how one gets the data, a TimeTool::DataV2 object. Older releases would also add the output as doubles or ndarrays, but this is no longer the case with ana-0.14.4 and later.

Accessing Results from Analyze (ana-0.14.4 and later)

ttData = evt.get(TimeTool.DataV2, self.timeToolKey)
ttdata.position_pixel() # position of edge, in pixels
ttdata.amplitude()      # amplitude of edge, in pixels
ttdata.nxt_amplitude()  # amplitude of second-most-significant edge, in pixels
ttdata.position_fwhm()  # FullWidthHalfMax of the differentiated signal (corresponds to slope of edge) in pixels
ttdata.position_time()  # position of the most significant edge (see note below)

Note that the position_time() results depend on have appropriate calibration constants deployed to the TimeTool configuration in a variable like this (in this case done as an argument to psana.setOptions()):

'TimeTool.Analyze.calib_poly':'0 1 0'
 

The three variables are coefficients of a quadratic polynomial that convert pixel number into time.  These constants are typically determined by the hutch scientists.

In AMO/XPP the time tool analysis is done online in realtime.  Results can be accessed using the following epics-variables names: TTSPEC:AMPL , TTSPEC:AMPLNXT, TTSPEC:FLTPOS, TTSPEC:FLTPOSFWHM, TTSPEC:FLTPOS_PS, TTSPEC:REFAMPL

Controlling Laser/Beam Logic

TimeTool.Analyze is often used on experiments where both the laser and beam fire at different times. TimeTool.Analyze does the following based on what it determines about the laser and beam:

• laser on, beam off: builds a reference/background based on just the laser. The user may configure TimeTool.Analyze to load the reference from a file, in case no "beam off" data was acquired in the run.

• laser on, beam on: when it has a reference of just the laser background, computes its results and puts them in the Event.
• laser off: nothing

The laser on/off beam on/off logic is typically determined based on evr codes, and looking at energy in the beam monitors (ipmb data)  - which evr codes and ipmb's is configurable. However for some experiments, users need to override this logic and make their own decision. Starting in ana-0.13.17, this can be done as follows

• configure TimeTool.Analyze to get laser and/or beam logic from strings in the Event
• Write a Psana Module that puts "on" or "off" in the Event for the laser and/or beam based on your own logic
• Load this Psana Module before loading TimeTool.Analyze

The parameters to tell TimeTool.Analyze to get laser/beam logic are "beam_on_off" and "laser_on_off". For example, if you do

# in a config file
[TimeTool.Analyze]
beam_on_off_key=beam_on_off
laser_on_off_key=laser_on_off

then TimeTool.Analyze will bypass it's own logic for determining if the laser as well as the beam is on or off, and get if from variables in the event that are strings, with the keys "beam_on_off" and "laser_on_off" (you can set those to whatever you like, and you need not specify both if you only want to control the beam logic, or laser logic, respectively).

Next one needs to write a Psana Module (not a standard Python script) that adds these variables into the event. A good reference for Psana Modules is psana - User Manual. Note - this link is different then the links that discuss writing Python scripts, such as  psana - Python Script Analysis Manual. The Psana module will have to add the variables for every event - once you specify a value for beam_on_off_key, or laser_on_off_key, those keys need to be present for all events. An example Psana Module written in Python might be

class MyMod(object):
    def event(self, evt, env):
        evt.put("on","beam_on_off")
        evt.put("off","laser_on_off")

Now, assuming this Psana Module called MyMod was in a Package called MyPkg (so it resied in a file in your test release, MyPkg/src/MyMod.py) if one were to set the psana modules option like so

[psana]
modules=MyPkg.MyMod,TimeTool.Analyze

then TimeTool.Analyze would treat the beam as on and the laser as off for every event.

Plotting and Details about Analyze

A general feature of psana is to control the level of output that differnent modules cary out. To see the trace and debug messages of TimeTool.Analyze, set the following environment variable before running your code

MSGLOGCONFIG=TimeTool.Analyze=debug

Starting with ana-0.14.4, you can also set the following configuration options:

[TimeTool.Analyze]
eventdump=True

This adds a number of intermediate calculations into the event store. The TimeTool package includes a Python Psana module that will look for these results and plot them. To use this module, include it in the Psana module chain after TimeTool.Analyze, i.e:

[psana]
modules = TimeTool.Analyze TimeTool.PlotAnalyze

and then configure PlotAnalyze as follows:

[TimeTool.PlotAnalyze]
tt_get_key = TSS_OPAL     # or whatever the input key is for TimeTool.Analyze to find the camera frame
tt_put_key = TTANA        # or whatever the output key, put_key is for TimeTool.Analyze
fignumber = 11            # starting matplotlib figure number, change to not interfere with other figure numbers you may be using
pause = 1                 # set to 0 to go through events without pause, otherwise module stops each time the laser is on

Examples

The TimeTool package contains two examples (see  /reg/g/psdm/sw/releases/ana-current/TimeTool/examples/)

EVR BYKICK signals no beam

A common way to run the TimeTool is to have the laser always on, but the beam is not present when the evr bykick code is present. The TimeTool.Analyze module will build up a reference during the BYKICK shots, and attempt to compute results for all other shots. There are a few reasons why it may fail and return no results - usually related to a very poor signal during that event. To run this example, do

python TimeTool/examples/plot_analyze.py -h

You see that it is a script with a help message. If you then run it as

python TimeTool/examples/plot_analyze.py -d sxri0214 -r 158 -n 100

The -n option is a testing option that limits the number of events to the first 100. The script loads TimeTool.Analyze to get results, but it also configures TimeTool.Analyze to put extra information in the event store. This is done with the generated a log plot of the image and plots the time tool pixel position result over the plot.

Manage References using Calibration Manager

Some experiments use certain runs to form the reference for the TimeTool. They take a run where the laser is ON, but the beam is blocked. TimeTool.Analyze contains two parameters, ref_load and ref_store. These could be used to have TimeTool save a reference from such a run, and then load it when processing another run. Another option is to form a pedestal file for the camera in question using calibman. Once this pedestal file has been deployed, you can set the option

        use_calib_db_ref=1

In the TimeTool.Analyze configuration. It will then detect which run the events are coming from and attempt to load the pedestal file from the calibration manager. Look at

python TimeTool/examples/refCalibExample.py -h

for details.

Module Check

a module that retrieves results from the event for either the above module or from data recorded online.

Module Setup

a module that calculates the reference autocorrelation function from events without FEL for use in the digital filter construction.

References

• Psana User Manual - Old
• Psana Reference Manual - Old
• psana - Module Examples
• Migration from pyana to psana
• psana - Migration from pyana

...