...

• modules
  list of module names to include in the analysis job. Each module name is built of a package name and class name separated by dot (e.g. TestPackage.ExampleModule) optionally followed by colon and modifier. Modifier is not needed if there is only one instance of the module in the job. If there is more than on instance then modules need to include unique modifier to distinguish instances. If the module comes from psana package then package name can be omitted. Module names can also be specified on the command line with -m option, for multiple modules use multiple -m options or comma-separated names in single -m option.
• files
  list of file names to process. File names can also be specified on the command line which will override anything specified in configuration file. Long file names can be substituted by the string-structure like exp=cxitut13:run=11,15-22,25:xtc, which format is explained here.
• events
  maximum number of events to process in a job, can also be given on the commnad line with -n or --num-events option.
• skip-events
  number of events to skip before starting even processing, can also be given on the commnad line with -s or --skip-events option.
• instrument
  Instrument name.
• experiment
  Experiment name. Instrument and expriment names can be specified on the commnad line with -e or --experiment option, option value has format XPP:xpp12311 or xpp12311. By default instrument and experiment names are determined from input file names, you can use these options to override defaults (or when your file has non-standard naming).
• calib-dir
  Path to the calibration directory, can also be given on the commnad line with -b or --calib-dir option. Path can include {instr} and {exp} strings which will be replaced with instrument and experiment names respectively. Default value for path is /reg/d/psdm/{instr}/{exp}/calib.

...

Option -j can change job name which defines then names of the output histogram file. By default job name is constructed from the name of the first input file.

Input data files can also be specified in the configuration file or on command line, command-line arguments override configuration file values. Check section below for complete description of dataset format.

Command-line options -v and -q can increase or decrease verbosity of the output generated by messaging service. By default psana outputs messages at info and higher levels. With one -v option trace messages will be printed also, and with two or more -v options debug messages will be printed too. With -q option info messages will not be printed, only warning, error, and fatal.

...

% psana -m EventKeys /reg/d/psdm/...
% psana -m psana_examples.EBeamHist -j ebeam-hist-r1000 /reg/d/psdm/...
% psana -c psana_examples/data/DumpAll.cfg /reg/d/psdm/...exp=cxi12345:run=123
% psana                  # everything will be specified in psana.cfg file

Specifying input data

Input data for psana are specified on command line or in configuration file using special dataset syntax. More than one dataset can be specified in arbitrary order, psana will will order datasets accordingly, so that events from all datasets are time-ordered.

In simplest case dataset is  just a file name containing input data in either XTC of HDF5 format. File name should be given as a full path name, if there are more than one stream or chunk in XTC data, all of them must be specified.

More advanced and recommended way is to provide input data as a special dataset string. The dataset string encodes various parameters, some of which are needed to locate data files, while others specify optional behavior such as filtering or live data reading. The general syntax of the dataset string is:

par[=val][:par[=val][...]

• experiment name (which may optionally contain the name of an instrument)
  

   

  Code Block
  exp=CXI/cxi12313 exp=cxi12313

• run number specification (can be a single run, a range of runs, a series of runs, or a combination of all above):
  
  

   

  Code Block
  run=1 run=10-20 run=1,2,3,4 run=1,20-20,31,41

• file type (presently the default type is 'xtc')

   

  xtc h5

• a random stream (if a value is omitted) or a specific stream. Note this option only makes a sense for XTC files:

   

  one-stream one-stream=2

• allow reading from live files while they're still being recorded (by the DAQ or by the Data Migration service). Note that this feature is only available when running psanaat PCDS, in all other cases the option will be ignored:

   

  live

Putting all together one would see a data set specification which would tell the framework to read data of stream #2 from XTC files of run 41 while these files were sill being recorded (by the DAQ, or the data migration service, or by another process of the same user, etc.):

The complete description of the data set string syntax and allowed parameters can be found in the specification document.

Psana Module Examples

A set of psana modules is available in current release as explained in Psana Module Catalog. Part of them demonstrates how data can be accessed from user module code . Other modules can be used in data analysis or event filtering. Example of application for these modules are available in separate document:

...