Skip to content

Writing Algorithms and Tools

Note

There is some overlap with the Git tutorial, but this is an important topic and worth going over again.

Prerequisites

You should have completed the preparatory steps before the tutorial and done the Git tutorial, so we will re-use the same build directory and athena clone.

Setup runtime

Start from the athena directory and setup a recent nightly release of the Athena main branch:

cd ..
setupATLAS
mkdir build # may already exist, if it does delete the contents
cd build
asetup main,Athena,latest

Make a new branch

Now cd to the athena directory and make a new branch:

cd ../athena
git fetch upstream
git checkout -b main-create-new-package upstream/main --no-track

Step 1: Create a package

We're going to be replicating some of what was done in the previous tutorial, but this time we will concentrate on writing a typical algorithm and AlgTool.

First, let's create a package and a dummy algorithm. From the athena directory do the following:

mkdir -p MyNewPackage/src/components

Then create a CMakeLists.txt file in MyNewPackage and add the following:

atlas_subdir( MyNewPackage )

atlas_add_component( MyNewPackage
   src/*.h src/*.cxx src/components/*.cxx 
   LINK_LIBRARIES GaudiKernel AthenaBaseComps )

Note

We cover CMake in another section of this documentation. Here you can learn how to write CMakeLists.txt files for building ATLAS packages.

Now we add a simple algorithm. A few points to make about this example:

  • This algorithm will be fully re-entrant, that is one algorithm instance can be shared between multiple threads (and it inherits from AthReentrantAlgorithm). You will see many examples of AthAlgorithm in the codebase, which means that these algorithms are not guaranteed to be re-entrant (though they should still not be thread hostile).
  • ATLAS uses Doxygen to document its code, and the main nightly documentation can be found here. ATLAS authors can read more about rules and recommendations on this Twiki page.

So now let’s add the following as src/ExampleAlg.h (this should be pretty familiar from the previous tutorial):

/*
  Copyright (C) 2002-2025 CERN for the benefit of the ATLAS collaboration
*/
#ifndef MYNEWPACKAGE_EXAMPLEALG_H
#define MYNEWPACKAGE_EXAMPLEALG_H

#include "AthenaBaseComps/AthReentrantAlgorithm.h"

/** An example algorithm that reads and writes objects from the event store
 using handles.*/
class ExampleAlg
  : public AthReentrantAlgorithm
{
public:
  using AthReentrantAlgorithm::AthReentrantAlgorithm;
  virtual StatusCode initialize() override;
  virtual StatusCode execute (const EventContext& ctx) const override;
private:
};
#endif

And then add src/ExampleAlg.cxx:

/*
  Copyright (C) 2002-2025 CERN for the benefit of the ATLAS collaboration
*/

#include "ExampleAlg.h"

StatusCode ExampleAlg::initialize()
{
  return StatusCode::SUCCESS;
}

StatusCode ExampleAlg::execute(const EventContext& ctx) const
{
  return StatusCode::SUCCESS;
}

Finally (for this stage), you need to add an extra file to let Gaudi know that this library has Gaudi components src/components/MyNewPackage_entries.cxx:

#include "../ExampleAlg.h"
DECLARE_COMPONENT( ExampleAlg )

Since we're all writing MT safe code now, let's go ahead and use the GCC plugin which checks for MT hostile code, by adding a blank ATLAS_CHECK_THREAD_SAFETY file in the root of the package:

touch ATLAS_CHECK_THREAD_SAFETY

(See the documentation about the static checks provided by the package External/CheckerGccPlugins for more information on how this all works)

Exercise 1

Compile this new package. If you need a reminder see how we compiled the example AthExHive package on Day 1 of this tutorial.

Bonus: fix the compilation warning by e.g. printing the numbers of events processed.

Warning

We NEVER print anything per event at INFO level, so use ATH_MSG_VERBOSE or ATH_MSG_DEBUG

Tip

You should not need to retrieve any new objects - use the argument passed to the execute() method of your algorithm.

Step 2: Run the Algorithm

Now let's run this! Start from your package directory (i.e. which should currently contain your CMakeLists.txt file and src/) and make a python directory

Add the following python fragment as ExampleAlgConfig.py:

# Copyright (C) 2002-2025 CERN for the benefit of the ATLAS collaboration

from AthenaConfiguration.ComponentAccumulator import ComponentAccumulator
from AthenaConfiguration.ComponentFactory import CompFactory

def ExampleAlgCfg(configFlags, **kwargs):
    result=ComponentAccumulator()
    alg = CompFactory.ExampleAlg(**kwargs )
    result.addEventAlgo(alg)
    return result

if __name__=="__main__":
    from AthenaConfiguration.AllConfigFlags import initConfigFlags
    from AthenaConfiguration.MainServicesConfig import MainServicesCfg

    flags = initConfigFlags()
    flags.Exec.MaxEvents = 10
    flags.lock()

    cfg = MainServicesCfg(flags)
    cfg.merge(ExampleAlgCfg(flags))

    import sys
    sys.exit(cfg.run().isFailure())

If you haven't done so already, let's make a run directory, at the same level as the build directory (i.e. you should have a directory which contains athena, build and now run).

Try to run it : 

cd run
python -m MyNewPackage.ExampleAlgConfig

As you'll have seen, this won't work because we haven't installed the Python module yet! To see this, from build/ have a look at what is installed locally:

ls $LCG_PLATFORM/python/MyNewPackage/
MyNewPackageConf.py  __init__.py

As you can see, we only have the autogenerated MyNewPackageConf.py (feel free to have a look at this, this is what Gaudi generates from the C++ you wrote and it can be pretty interesting to check what Python 'sees' and make sure it matches up what you expect).

Fix our problem by adding the following to your CMakeLists.txt

atlas_install_python_modules( python/*.py )

and re-running make (in the build/ directory, obviously).

Now have a look at what is installed:

$ ls $LCG_PLATFORM/python/MyNewPackage/
ExampleAlgorithmConfig.py  ExampleAlgorithmConfig.pyc  MyNewPackageConf.py  __init__.py

And now you can run with e.g.

python -m MyNewPackage.ExampleAlgConfig

From the previous tutorial, this output you should be pretty familiar.

Exercise 2

Run with multiple threads, which is no longer quite as simple as adding --threads=2 since we're no longer using the athena / athena.py wrapper.

Tip

git grep "Concurrency.NumThreads" -- *.py (you will also need to take care of NumConcurrentEvents, in contrast to athena.py)

Alter the verbosity of the algorithm so you can see the event number we added earlier

Tip

There are a few ways to do this, but think about using kwargs and absolutely do not hardcode it somewhere.

Step 3: Load some track particles

Now let's make the algorithm actually do something! Let's load some tracks, using DataHandles. For more on this, look here.

So you will need to:

  • Add a dependency on the xAODTracking package to your package
  • Add a ReadHandleKey and then construct a ReadHandle from it
  • Modify the Python configuration to add an AOD file with TrackParticles in

Let's start by updating the CMakeLists.txt. You will need to add a dependency on xAODTracking. Remember: any dependency on a "component library" is a private dependency.

atlas_subdir( MyNewPackage )

atlas_add_component( MyNewPackage
   src/*.h src/*.cxx src/components/*.cxx 
   LINK_LIBRARIES GaudiKernel AthenaBaseComps xAODTracking )

atlas_install_python_modules( python/*.py )

and also add the following include to the header file:

#include "xAODTracking/TrackParticleContainer.h"

Now we need to tell Athena that this algorithm has a data dependency on tracks. So let's add a new ReadHandleKey (it should be private).

SG::ReadHandleKey<xAOD::TrackParticleContainer>   m_trackParticleKey
     { this, "TrackParticleContainerKey", "InDetTrackParticles", "Key for TrackParticle Containers" };

And then in the .cxx, initialise the key in the initialise() method:

ATH_CHECK( m_trackParticleKey.initialize());

And now we can construct a handle (and use it) inside execute(...):

SG::ReadHandle<xAOD::TrackParticleContainer> handle(m_trackParticleKey, ctx);
ATH_MSG_VERBOSE("Got back  "<<handle->size());

Lastly, we have to introduce the input file to the job. For convenience, we'll use a test file whose path is a pre-defined configuration flag and which is (exceptionally) stored in CVMFS. You can substitute this with one of your local files if you wish. Add the following lines to the python configuration file, before the flags.lock() line:

from AthenaConfiguration.TestDefaults import defaultTestFiles
flags.Input.Files = defaultTestFiles.AOD_RUN3_MC

And before you merge the ExampleAlgCfg into the component accumulator, add these lines:

from AthenaPoolCnvSvc.PoolReadConfig import PoolReadCfg
cfg.merge(PoolReadCfg(flags))

Rerun your test job and make sure it works after all these changes.

Warning

Remember to rebuild your package (you changed .h and .cxx files)

Step 4: Write an AlgTool to filter the tracks

For AlgTools it is often a good idea to have an abstract interface class - this means that a client can say what type of tools it wants (i.e. what it does) but leave the concrete implementation to be defined later. In this particular case, it's a bit pointless because we're

  • adding it to the same package
  • and it doesn't really do much

But hopefully, the principle is obvious.

So, let's start by making the interface. Since this should usually be a public file, let's make a header directory (from the base directory of the package):

cd athena/MyNewPackage
mkdir MyNewPackage

and then add to it the following as IMyAlgTool.h:

/*
  Copyright (C) 2002-2025 CERN for the benefit of the ATLAS collaboration
*/

#ifndef MYNEWPACKAGE_IMYALGTOOL_H
#define MYNEWPACKAGE_IMYALGTOOL_H
#include "GaudiKernel/IAlgTool.h"
#include "xAODTracking/TrackParticle.h"

/** @class IMyAlgTool
    @brief Interface to demonstrate how to make an interface which actually does something useful.
*/

class IMyAlgTool : virtual public IAlgTool {

public:
  /// Interface ID declaration for Gaudi
  DeclareInterfaceID( IMyAlgTool, 1, 0 );

  /// Pure virtual function to be implemented by the concrete tool
  virtual bool selectTrackParticle( const xAOD::TrackParticle& particle) const = 0 ;
};

#endif

Let's walk through this a little:

  • the DeclareInterfaceID macro sets up the code that uniquely identifies the 'type' of interface this is.
  • there is one pure virtual method, which accepts a track particle and returns a boolean
  • And since we added an interface to the package, to make this interface usable from outside of the package as well, let's also declare an interface library! So the package's configuration would now look like this:
atlas_subdir( MyNewPackage )

atlas_add_library( MyNewPackageLib
   MyNewPackage/*.h
   INTERFACE
   PUBLIC_HEADERS MyNewPackage
   LINK_LIBRARIES GaudiKernel xAODTracking )

atlas_add_component( MyNewPackage
   src/*.h src/*.cxx src/components/*.cxx 
   LINK_LIBRARIES GaudiKernel AthenaBaseComps xAODTracking MyNewPackageLib )

atlas_install_python_modules( python/*.py )

Now let's add the actual implementation, firstly MyAlgTool.h which we add to src/:

/*
  Copyright (C) 2002-2025 CERN for the benefit of the ATLAS collaboration
*/

#ifndef MYNEWPACKAGE_MYALGTOOL_H
#define MYNEWPACKAGE_MYALGTOOL_H

#include "AthenaBaseComps/AthAlgTool.h"
#include "MyNewPackage/IMyAlgTool.h"

class MyAlgTool : public extends< AthAlgTool, IMyAlgTool > {
public:
  /// Use the base class's constructor directly
  using extends::extends;

  /// Implementation for the interface's function
  virtual bool selectTrackParticle( const xAOD::TrackParticle& particle) const override;
};

#endif

Now MyAlgTool.cxx (also added to src/) 

/*
  Copyright (C) 2002-2025 CERN for the benefit of the ATLAS collaboration
*/

#include "MyAlgTool.h"

bool MyAlgTool::selectTrackParticle( const xAOD::TrackParticle& particle) const {
  return particle.pt()>2.0;
}

Finally, let's add this to the algorithm (new private data member declaration in the header):

ToolHandle<IMyAlgTool> m_algTool {this, "SelectionTool", "MyAlgTool", "The selection tool"};

Exercise 3

  • Modify the algorithm to initialize the tool handle correctly (remember, it's a handle, so look how we init the other handle in this algorithm)
  • Compile this and run. You will need to modify the entries file in the src/components directory to let Athena know about the new tool (have a look at $LCG_PLATFORM/python/MyNewPackage/MyNewPackageConf.py before you do this - it will be missing the tool).
  • Use the tool to count passing tracks, and print this out (as verbose output!)
  • Add a property to the AlgTool to change the pT cut, and update the configuration with a new value (there are several ways to do this, configure the tool before it is added to the algorithm, or modify it afterwards. Either is fine)

Optional extras

  • Can you figure out how to make a cumulative count of the number of tracks in total and the total number accepted? Hints: think about where the counters have to be initialized; also think about how to manage counters in a multi-threaded application. If you need some inspiration look at ReadxAOD in the AthExBasics package.
  • Write out a new track particle container with the selected track particles. This will involve using Write{Key]Handles (as described here) but also handling xAOD containers correctly. For hints, take a look at the WritexAOD example in the AthExBasics package.