Athena Python Configuration

Introduction

This guide describes the Athena Python configuration system that is in use since Run-3. It is also known as the ComponentAccumulator based configuration and the core code lives in the package Control/AthenaConfiguration.

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. The 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.

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

Overview

In broad terms the configuration system works as follows.

Each C++ component defines a set of configurable parameters via Gaudi::Property members or (deprecated) declareProperty calls.
- 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 Python "Configurable database" is built containing Python classes for each C++ class with attributes corresponding to the C++ properties.
Python scripts instantiate classes and set the relevant properties.
The resulting set of python objects produce a serialized/textual representation of the configuration.
The configuration is read by the C++ program and populates the global job options catalog.
During initialize the C++ components fetch their respective properties from the catalog.

The steps marked with *️⃣ are places where developer intervention is needed. The other steps are fully automatized.

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

Files containing CA configuration code must end with Config.py, e.g. HelloWorldConfig.py.
The name of the function generating the configuration fragment (i.e creating a ComponentAccumulator instance) should normally start with the name of the main component they configure and must end with Cfg.
If the file is supposed be executed by athena.py add a shebang to the first line (#!/usr/bin/env athena). This allows athena to recognize the file as a CA configuration as opposed to legacy job options.

Arguments

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):
```
Optionally, you may choose to pass a default name as a second argument. This can be useful if 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):
```
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):
```

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 properties of that component, e.g. 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

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:

from SCT_ConditionsTools.SCT_ConditionsToolsConfig import SCT_ConditionsSummaryToolCfg

def Trig_SCT_ClusteringToolCfg(flags, name="Trig_SCT_ClusteringTool"):
   acc = ComponentAccumulator()
   conditionsTool = acc.popToolsAndMerge(SCT_ConditionsSummaryToolCfg(
       flags, withFlaggedCondTool=False, withTdaqTool=False))

   acc.setPrivateTools(acc.popToolsAndMerge(SCT_ClusteringToolCfg(
       flags, name,
       conditionsTool=conditionsTool, SCTDetElStatus="")))

   return acc

For more complicated functions that 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

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.