Page History

...

Psana framework has multiple configuration options parameters that can be change changed via command line or special configuration file. Configuration file can also specify options parameters 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 that file exists. The location of the configuration file can be changed with the -c <path> option which should provide path of the configuration file.

...

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

<option<param-name> = <option<param-value>

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

...

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

...

Parameter Types

Configuration file does not specify option parameter 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:

...

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

Psana

...

Parameters

The options parameters that are needed for the framework are defined in psana section. Here is the list of options parameters 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 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

User Modules

...

Parameters

OptionsParameters for user modules appear in the separate sections named after the modules. For example the module with name "TestPackage.ExampleModule" will read its optionsparameters from the section {{\[TestPackage.ExampleModule\]}}. If the module name includes modifier after colon then it will try to find optionparameter value in the corresponding section first and if it does not exist there it will try to read optionparameter form section which does not have qualifiermodifier. In this way the modules can share common optionsparameters. For example the module "TestPackage.ExampleModule:test" will try to read ana optionparameter from {{\[TestPackage.ExampleModule:test\]}} section first and section {{\[TestPackage.ExampleModule\]}} section after that.

Here is an example of configuration for some fictional analysis job:

[psana]
modules = TestPackage.Analysis:mode1 TestPackage.Analysis:mode2

[TestPackage.Analysis]
# these are common optionsparameters for all TestPackage.Analysis modules,
# but instances can override then in their own sections
calib-mode = fancy
subpixel = off
threshold = 0.001

[TestPackage.Analysis:mode1]
# optionsparameters specific to :mode1 module
range-min = 0
range-max = 1000000

[TestPackage.Analysis:mode2]
# optionsparameters specific to :mode2 module
range-min = 1000
range-min = 10000
subpixel = on

Accessing Configuration Parameters

User module base class defines few convenience methods which simplify access to configuration parameters. Here is the list of the methods:

• std::string configStr(const std::string& param)
  this method takes the name of the parameter and returns full parameter value as a string. If parameter cannot be found the exception will be thrown.
• T config(const std::string& param)
  this method takes the name of the parameter and returns parameter value converted to type T. If parameter cannot be found the exception will be thrown.
• std::string configStr(const std::string& param, const std::string& def)
  this method takes the name of the parameter and returns full parameter value as a string. If parameter cannot be found then the value of second argument will be returned.
• T config(const std::string& param, T def)
  this method takes the name of the parameter and returns parameter value converted to type T. If parameter cannot be found then the value of second argument will be returned.
• Seq configList(const std::string& param)
  this method takes the name of the parameter and returns parameter value converted to sequence. Sequence can be any of standard container types such as std::list<std::string> or std::vector<double>. If parameter cannot be found the exception will be thrown.
• std::list<T> configList(const std::string& param, const std::list<T>& def)
  this method takes the name of the parameter and returns parameter value converted to std::list<T>. If parameter cannot be found then the value of second argument will be returned.

Here is an example of the code in user module which uses these methods:

  Source src = configStr("source", "DetInfo(:Evr)");
  int repeat = config("repeat");
  std::list<std::string> options = configList("options");