Page History
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:
- 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
- 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.components of the transmitted laser.
TimeTool results can be computed by the DAQ while data is being recorded and written directly into the .xtc files, or after data has been recorded. In AMO/XPP the time tool analysis is done by the DAQ while data is being recorded. Results can be accessed using the following epics-variables names: TTSPEC:AMPL , TTSPEC:AMPLNXT, TTSPEC:FLTPOS, TTSPEC:FLTPOSFWHM, TTSPEC:FLTPOS_PS, TTSPEC:REFAMPL or by getting the appropriate Psana.TimeTool.DataV* object from the event (either V1 or V2) from the opal camera source.
This document covers how to run the TimeTool after data has been recorded. Starting with ana-0.16.9, a Python wrapper to the TimeTool is provided which is the preferred way to run the TimeTool algorithms. Previous to ana-0.16.9 one would use Psana modules. One would loadi the C++ TimeTool.Analyze module via a psana config file.
Note: specific examples for the time tool can be found in /reg/g/psdm/sw/releases/ana-current/TimeTool/examples/.
Python Interface
In the example directory mentioned above, see:
- pyxface_evr_bykick.py
- pyxface_calib_db_ref.py
The python interface contains extensive documentation in its docstrings. To access this, from a ipython session, do
| Code Block | ||
|---|---|---|
| ||
import TimeTool
TimeTool.PyAnalyze?
TimeTool.AnalyzeOptions? |
Further documentation can be found on the PyAnalyze functions.
The docstrings will contain the most current documentation. For convenience, we include this documentation here as well:
PyAnalyze
Python interface to the TimeTool.Analyze C++ Psana module to allow conditional execution.
Basic Usage
There are several steps to using the module demonstrated in this example:
| Code Block | ||
|---|---|---|
| ||
ttOptions = TimeTool.AnalyzeOptions(get_key='TSS_OPAL',
eventcode_nobeam = 162)
ttAnalyze = TimeTool.PyAnalyze(ttOptions)
ds = psana.DataSource(self.datasource, module=ttAnalyze)
for evt in ds.events():
ttResults = ttAnalyze.process(evt) |
The steps are
Create an instance of the AnalyzeOptions class. See AnalyzeOptions docstring for detailed documentation on options.
Construct an instance of PyAnalyze (called ttAnalyze above) by passing this options object (called ttOptions above).
construct your psana DataSource by passing the PyAnalyze instance through to the module argument.
call the ttAnalyze.process() method on each event you want to process.
Parallel Processing
When doing parallel processing and distributing events among different ranks, each rank typically processes a fraction of all the events. Howevever it is important that each rank also process all events that include reference shots for the TimeTool. One can check if a shot is a reference shot or not with the isRefShot(evt) function. For example, in the above, suppose the variables numberOfRanks and rank are defined so that we can implement a round robin strategy to distribute event processing. One could implement this, while making sure all ranks process reference shots, as follows:
| Code Block | ||
|---|---|---|
| ||
for idx, evt in enumerate(ds.events()):
if ttAnalyze.isRefShot(evt):
ttAnalyze.process(evt)
if idx % numberOfRanks != rank:
continue
ttResults = ttAnalyze.process(evt) |
Note that it is Ok to call the PyAnalyze.process(evt) function more than once on the same event. The PyAnalyze class caches the results of the first call so as to not call the underlying C++ TimeTool.Analyze module twice.
Controlling Beam Logic
This is an unsual use case. It happens when users are using EPICSs to move things around to drop the beam, rather than using an event code. In this case the user will want to look at the EPICS variables and instruct the TimeTool of when the beam is off so that it can build up its reference. To do this, set controlLogic=True in AnalyzeOptions and use the controlLogic(beamOn, laserOn) function. When controlLogic is true, you must call this function for each event you subsequently call process on (if you forget, TimeTool will stop with an error).
AnalyzeOptions
Specify configuration options for the TimeTool Analyze module.
There are many options for TimeTool.Analyze, most can be left at their default values. First we document options users may want to change, then more specialized options.
Note that all options are either a Python str, or Python int, or float. Even though some options represent a list of numbers, the argument must be formatted as a string with only whitespace separating numbers (no commas, etc).
Common Options
| Code Block |
|---|
Option default data type / explanation
------ ------- -----------
get_key 'TSS_OPAL' str, this is the psana source for the TimeTool
opal camera. The default, 'TSS_OPAL', is a common
DAQ alias for this source
eventcode_nobeam 0 int, for BYKICK experiments, where an evr code
specifies when the beam is NOT present, specify that
EVR code here. If the beam is always present, keep
the default value of 0. Note - there are specialized
options to control laser on/off beam on/off logic
below.
ref_avg_fraction 0.05 float, weight assigned to next reference shot in
rolling average. 1.0 means replace reference with
next shot (no rolling average). 0.05 means next
shot is 5% of average and all previous is 95%.
sig_roi_y '425 725' str, signal roi in y, or the rows of the Opal camera
that the user may want to adjust based on where signal is.
sig_roi_x '0 1023' str, signal roi in x or columns, default is all.
calib_poly '0 1 0' str, TimeTool.Analyze returns results as both a pixel
location on the Detector, as well as a conversion
to femtoseconds by applying this quadratic polynomial. Typically a
special calibration run is performed to compute the mapping from
position on the detector to femtoseconds and the results of this
analysis are passed through this parameter. If calib_poly is 'a b c'
Then femtosecond_result = a + b*x + c*x^2 wher x is the detector position.
** Uncommon Options**
Option default data type / explanation
------ ------- -----------
projectX True bool, if true, project down to the X axis of the opal.
eventcode_skip 0 int, EVR code for events that should be skipped from
TimeTool processing.
ipm_get_key '' str, in addition to the evr code above, the timetool
will look at the threshold on a specified ipmb to decide
if the beam is present. Default is to not look at a
ipmb. Here one can specify the psana source for the
desired ipimb.
ipm_beam_threshold float, threshold for determining if beam present from
an ipm.
weights '0.00940119 ...' str, this defaults to a long string of the
weights that the TimeTool uses when performing signal
processing on the normalized, reference divided signal,
to turn a sharp drop into a peak. It is unusual for
users to modify this string. The full string can be
found in the code.
weights_file '' str, the weights can be put into a file as well
use_calib_db_ref False bool, get the initial reference from the
calibration database. This reference can be deployed
using calibman by making a pedestal for the appropriate
opal. Example use case is creating references not by
dropping the beam from shots, but rather making
reference runs (dropped shots tend to give better results).
ref_load '' str, filename to load reference file from.
ref_store '' str, filename to store reference into.
controlLogic False, bool, to bypass the normal mechanism of letting
the timetool identify when the beam or laser is on,
the user can control this. If this is set, then for
every event, one must call controlLogic before calling
process with the TimeTool.Analyze python class.
proj_cut -(1<<31), int, after projecting of the opal camera to create the
signal, one can require that at least one value in the signal
be greater than this parameter in order to continue processing.
Default is int_min, which means one always processes when the
laser is on (and a reference is available).
sb_roi_x '', str give something like 1 10 to do sideband analysis and specify
the sideband ROI. This feature, while it exists in the code, is not
maintained. Experts interested in this feature may need to contact
their POC for support.
sb_roi_y '', str, see sb_roi_x, this is for the y region (rows)
sb_avg_fraction 0.05, float, see sb_roi_x and sig_avg_fraction for information on
rolling averages.
analyze_event -1, int, special options for analyzing the first few events with respect
to a reference - feature not maintained.
dump 0, int, setting this option is not reccommended. It instructs TimeTool
to use the psana root based historgramming method - however the root
files interfere with MPI based analysis. See the eventdump option below
to access intermediate stages of TimeTool processing.
eventdump False, bool, setting this option to True will cause the underlying C++
Psana TimeTool.Analyze module to return extra data that the Psana PlotAnalyze
module can use (or users can get directly) but presently, the Python wrapper
does not expose this, or setup the plotter in a convenient way. However One can
get the ndarrays directly from the event following a call to PyAnalyze.Process().
psanaName TimeTool.Analyze, str, the logging name passed to this instance of the
underlying C++ Psana Module called TimeTool.Analyze. There should be no
reason to modify this - unless for some reason you want to configure two
separate instances of the Psana Module.
put_key TTANA, str, should be little reason to modify this. This is the key used to get
results back from the C++ TimeTool.Analyze module.
beam_on_off_key ControlLogicBeam, str, there should be no reason to modify this.
if controlLogic is true, this is the internal key string used to
communicate beam on/off with the TimeTool.Analyze module.
laser_on_off_key ControlLogicLaser, str, as above, should be no reason to modify this. |
Users migrating older code will need to discard psana config files, or remove the TimeTool.Analyze configuration from the psana config file AS WELL AS THE TimeTool.Analyze C++ Psana Module from the list of psana modules in the config file. If mixing old style Psana modules with PyAnalyze, be advised that PyAnalyze will run after any modules listed in the psana config file (so the TimeTool results will not be available to Psana modules listed in the config file). It should be easy to move Python Psana modules into the new style (C++ modules are not easy to move).
C++ Psana Module Interface
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:
...
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
...
Overview
Content Tools