...

    shared_ptr<Image> img(new Image(...));
    evt.put(img, src, "filtered");

Job and Module Configuration

Psana framework has multiple configuration options that can be change via command line or special configuration file. Configuration file can also specify options for user modules so that modules' behavior can be changed at run time without the need to recompile the code.

If no options are specified on the command line then psana tries to read configuration file named psana.cfg from the current directory if the file exists. The location of the configuration file can be changed with the -c <path> option which should provide path of the configuration file.

Configuration File Format

Configuration file has a simple format which is similar to well-known INI file format. The file consists of the sections, each section begins with the section header in the form:

[<section-name>]

Section names can be arbitrary strings, but in psana case section names are the names of the modules which cannot be arbitrary and should not contain speces.

Following the section header there may be zero or more option lines in the form

<option-name> = <option-value>

Option name is anything between beginning of line and '=' character with leading and trailing spaces and tabs stripped. Option value is anything after '=' character with leading and trailing spaces and tabs stripped, option value can be empty. Long option value can be split over multiple lines if the line ends with the backslash character, e.g.:

files = /reg/d/psdm/AMO/amo00000/xtc/e00-r0000-s00-c00.xtc \
        /reg/d/psdm/AMO/amo00000/xtc/e00-r0000-s01-c00.xtc \
        /reg/d/psdm/AMO/amo00000/xtc/e00-r0000-s02-c00.xtc

Lines starting with '#' character are considered comments and ignored.

Option Types

Configuration file does not specify option types, all values in the file are strings. Psana framework provides conversion of these strings to several basic C++ types or sequences. Following types and conversion rules are supported by framework:

• bool
  value strings "yes", "true", "on" become true, "no", "false", "off" become false. Strings which represent non-zero numbers become true, string "0" becomes false.
• char
  value string must be single-character string and it will be assigned to a result.
• C++ numeric types
  option value must represent valid number.
• std::string
  option value will be assigned to result string without change.
• C++ sequence types (e.g. std::list<T>)
  option value will be split into single words at space/tab characters, individual words will be converted to resulting type T.

When the conversion fails because of the incorrectly formatted input framework will throw an exception with the type ExceptionCvtFail.

Psana Options

The options that are needed for the framework are defined in psana section. Here is the list of options which can appear in that section:

• 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.
• 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.
• events
  maximum number of events to process in a job.

Here is an example of the framework configuration section:

[psana]
# list of file names
files = /reg/d/psdm/AMO/amo00000/xtc/e00-r0000-s00-c00.xtc \
        /reg/d/psdm/AMO/amo00000/xtc/e00-r0000-s01-c00.xtc \
        /reg/d/psdm/AMO/amo00000/xtc/e00-r0000-s02-c00.xtc
# list of modules, PrintSeparator and PrintEventId are from psana package
# and do not need package name
modules = PrintSeparator PrintEventId psana_examples.DumpAcqiris