Athena Configuration

Introduction

This guide describes Athena configuration system that is intended to be used for Run 3 and later. It is also known as ComponentAccumulator based configuration or New Job Options.

The configuration system of Athena allows us to assemble and customize components (algorithms, services and tools) for a workflow. It is done by creation and manipulation of python objects. Result of the configuration process is a set of settings that are used by Athena to instantiate and appropriately configure C++ components. Even in a small workflow the number of settings can easily be a few hundreds and in a complete reconstruction or HLT setup the number of settings reaches tens of thousands. Such a set of information needs to be properly managed.

For help, contact: atlas-sw-jobconfig@cern.ch

The Athena configuration system

In broad terms the configuration system works as follows.

Each C++ component defines a set of configurable parameters (*),
- There is rich, yet restricted set of types of configurable parameters that are supported,
- Typically reasonable default values are defined as well.
During compilation a database entry is made containing information about these properties.
During the configuration this database is queried for information about a component and as a result python class is generated with class attributes corresponding to the properties defined in C++.
Set of python script creates python objects and manipulates them (set properties). (*)
Resulting set of python objects produce a serialized/textual representation of the configuration.
The configuration is read in C++ program and populates the global dictionary with all settings.
C++ components during the initialization fetch the values and set configurable parameters (see 1st point) accordingly.

The steps marked with (*) are places where developer intervention is needed. That is to define configurable parameters and to prepare scripts setting them. Other steps are automatized.

The python infrastructure for the new configuration system lives in the package Control/AthenaConfiguration

In comparison to the Run 1-2 configuration system the procedure is technically different in some steps. However the only non-technical change concerned step 4.

Naming and other conventions

For consistency, and to make a clear distinction between legacy configuration files and the Component Accumulator (CA) system, the following conventions are used:

Naming
1. the name of the file containing new configuration code should end with Config.py
  - e.g. CSC_OverlayConfig.py.
2. the name of the function generating the configuration fragments (i.e creating a ComponentAccumulator instance) should normally start with the name of the main component they configure and must end with Cfg.
Arguments:
1. Configuration functions should always accept an instance of configuration flags as first argument (even if they don’t actually rely on flags) e.g.
```
  def myComponentCfg(flags, **kwargs):
```
2. Optionally, you may choose to pass a default name as a second argument. This can be useful if you want to match legacy configurations, or you need to have multiple versions of a component. However, it is not normally recommended for private tools (see later), as for private tools the name is not really used.
```
  def myComponentCfg(flags, name = "MyComponentVersionA", **kwargs):
```
3. Other named arguments (positional arguments are not recommended) can also be required, with defaults if necessary. Examples of this would be were clients always need to specify some extra information for the configuration to be possible (inputTracks, in the example below).
```
  def Trig_TRT_TrackExtensionAlgCfg(flags, inputTracks, name = 'TrigTrackExtensionAlg', **kwargs):
```
4. Where the configuration function is configuring one component (i.e. it is named MyComponentCfg) we would normally pass kwargs as the last argument to configure the Gaudi properties of that component, for example TrackSlimmerCfg:
```
  def TrackSlimmerCfg(flags, name="TrackSlimmer", **kwargs):
  acc = ComponentAccumulator()
  if "TrackSlimmingTool" not in kwargs:
   from TrkConfig.TrkTrackSlimmingToolConfig import TrackSlimmingToolCfg
   TrackSlimmingTool = acc.popToolsAndMerge(TrackSlimmingToolCfg(flags))
   acc.addPublicTool(TrackSlimmingTool)
   kwargs.setdefault("TrackSlimmingTool", TrackSlimmingTool)
  acc.addEventAlgo(CompFactory.Trk.TrackSlimmer(name, **kwargs))
  return acc
```
5. For specialised configs of a single component where no additional customisation of the configurations is expected beyond what is laid out in the configuration method (e.g. for concrete trigger, muon, EGamma specific tools and algorithms), the kwargs argument can be potentially omitted from the inputs of the configuration function. A baseline configuration function of this component should be provided in that case, including kwargs as input, and ideally used in the specialised config. For example Trig_SCT_ClusteringToolCfg:
```
  def Trig_SCT_ClusteringToolCfg(flags, name="Trig_SCT_ClusteringTool"):
  acc = ComponentAccumulator()
  from SCT_ConditionsTools.SCT_ConditionsToolsConfig import (
   SCT_ConditionsSummaryToolCfg)
  conditionsTool = acc.popToolsAndMerge(SCT_ConditionsSummaryToolCfg(
   flags, withFlaggedCondTool=False, withTdaqTool=False))
  acc.setPrivateTools(acc.popToolsAndMerge(SCT_ClusteringToolCfg(
   flags, name,
   conditionsTool=conditionsTool,
   SCTDetElStatus=""
  )))
  return acc
```
6. For more complicated functions which configure a set of components (and therefore it is not clear which properties are being configured), kwargs should not be used.
  - e.g. MuonSegmentFindingCfg or RecoSteering.py
Return values
1. Configuration functions should always return an instance of ComponentAccumulator (even if they configure just one private AlgTool).
  - e.g. CSC_OverlayConfig.py

You can find some more examples in the later section which describes in detail how to write configuration methods.