ant
A2 ant: class-based analysis framework
ant Documentation

ant

A2 ant logo

Just another **AN**alysis **T**oolkit ant, which can read from many input sources with minimal user intervention and let's you create Physics analyses within minutes.

Please see also the automatically generated Doxygen pages and the Wiki.

Dependencies

  • C++11 (gcc >4.9.2 should work, but >6.0 recommended, clang is also supported)
  • cmake >3.0
  • libgsl-dev, liblzma-dev (before installing root)
  • CERN ROOT (both ROOT5 and ROOT6 are supported)
  • Pluto (if you use ROOT5, you have to use the pluto5 version)
  • APLCONpp
  • doxygen (optional)

Installation

Note: A comprehensive installation guide can be found in the Wiki.

Please make sure that you fulfill the dependencies. Install ROOT and Pluto preferably in /opt/root and /opt/pluto to ensure auto-detection by ant's CMake.

Next, you need to get the APLCON C++ wrapper. The easiest way is to clone the repository relative to your ant directory at ../APLCONpp, then create the build directory at ../APLCONpp/build. This way CMake will automatically detect it.

See also the detailed steps described in the corresponding Wiki section.

Now you should be able to compile the Ant framework. Therefore clone this respository, either directly from https://github.com/A2-Collaboration/ant.git or you may want to fork it. As mentioned above, the installation works best when the APLCONpp and ant folder reside in the same directory. Inside your ant directory create a build direcory:

mkdir build && cd build && cmake ..

Then start the parallel compilation for example on a QuadCore machine with make -j5. You may want to add your ant/build/bin directory to your $PATH variable.

Parallel Processing

Ant is designed to run single threaded. This avoids a lot of programming problems and running it on the computation clusters is simpler and more efficient, since you only need to allocate one thread per job. For processing data we recommend to run an Ant process on each input file and then merge the results afterwards using Ant-hadd, Ant-chain, or ROOTs hadd tool (but prefer Ant-hadd --native for custom data type support).

There is also no builtin option to run over multiple input files in one go. This should be handled by external tools like GNU parallel, or AntSubmit on a cluster (see also --no_qsub option), or your shell.

Quick start guides

Check the Wiki to learn about the basic usage of Ant itself or how to run Ant tools on blaster using the provided job submission scripts like the aforementioned AntSubmit. Have a look at the Getting Started Guide for Physics classes if you have no idea about Ant and how to start writing your own analysis.

Ant MC tools

Ant comes with a few tools to generate MC data. It can generate photoproduction processes and decays with Ant-pluto, a frontend utilizing the Pluto event generator for A2 physics (includes the Tagger), shoot particles randomly in all directions using Ant-mcgun, or simulate a complete cocktail of various photoproduction and decay channels according to their cross sections with Ant-cocktail.

Example: Pluto Decay

To use Pluto to simulate, for example, the omega —> pi0 gamma do:

Ant-pluto --reaction "p omega [ pi0 g ]" --Emin 1400 --Emax 1600 --numEvents 10000 -v 2 -o sim.root

This will generate 10k events in the incident photon energy range 1400 MeV to 1600 MeV, saving unstable particles. The pi0 will decay into different channels according to the Pluto database. Use the option --no-unstable if you don't want to store intermediate particles and --no-bulk to disable bulk decays using the Pluto database.

Example: Random Gun

Shoot 1000 protons into TAPS, 1 proton/Event, 0 to 1 GeV

Ant-mcgun --numEvents 1000 --particle p --theta-max 20 --Emax 1000

Troubleshooting

  • If you still want to use ROOT5 you should use a not up-to-date compiler. Starting with GCC 9 and Clang 8 ROOT5 won't compile anymore. Use a version prior to those major releases if you need ROOT5, or use ROOT6 otherwise.
  • In case CMake is not able to locate your Pluto installation, you can provide the environment variable $PLUTOSYS to tell CMake where to find it. If you installed Pluto inside your home directory, ~/pluto or ~/src/pluto, or placed it in /opt/pluto, the make process may have failed. Please make sure you ran make in your Pluto directory with a proper ROOT installation.
  • There's a bug in GCC 8.2 which can lead to segfaults if make_shared is called. This is fixed with the release of 8.3, and version prior to 8.2 are not affected as well.
  • If you're using gcc version 5.x and experiencing build errors within ROOT generated dictionary files (i.e. redeclaration of struct __xfer_bufptrs), please update to a more recent ROOT version. As of November 2015, you need to clone the git branch which includes the patches. To do so:
    • get the source with git clone -b v5-34-00-patches https://github.com/root-mirror/root.git
    • cd in the cloned directory
    • create a new folder for the build process, e.g. mkdir build_dir
    • cd in it and run cmake .. && make -jN, replace N with the number of threads which should be used
    • set your $ROOTSYS accordingly
  • gdb version 7.7 crashes in combination with cereal, so use version 7.10
  • If you are using ROOT6 and run into some issues mainly related to derived classes, please have a look at the FAQ in the Wiki and see if you're problem is known already and if there's some way to avoid it.
  • If using the newest GCC release, like 7.x as of June 2017 or higher in the future (usually ArchLinux users), use the patched ROOTv5 version available here, which contains patches based on the bug report ROOT-8180. In the meantime, those patches have been merged upstream.
  • In case you encounter weird test errors (garbage output of corrupted TFiles TKey::ReadObjWithBuffer msg='Unknown class foDoubly linked listZL), make sure you recompiled Pluto properly with the identical $ROOTSYS as Ant (in particular pay attention to ROOT debug/release builds).
  • Starting with clang 5.0, there's a problem with compiling the third party tool cereal. The problem is known and reported. Please use a clang version < 5.0 as long as this issue with RapidJSON isn't fixed.

Contributing

Please read the following sections if you want to contribute to this project. Always make sure to cover your code with tests, see the wiki. Run make build_and_test before pushing.

Coding Style

  • Indentation: 4 spaces, no tabs anywhere
  • Ant-Codesytle defined in doc/Ant-Codestyle.xml (import to QtCreator)
  • #include statements:
    • header file for this .cc file first
    • then grouped by ant, ROOT, STL, others
    • one line between groups
    • each group ordered alphabetically

Have a look at the Wiki as well.

Library organization

The calibration modules specify physics classes, usually below src/analysis/physics/calibration, which produce the histograms used in the GUI part of the module. The analysis classes can access all information organized in expconfig. The slowcontrol libraries are divided to ensure proper initialization order of static registries.

The solid arrows mean "links to", whereas the dashed arrows means "includes only".

Or, automatically generated with

cd build
cp ../doc/CMakeGraphVizOptions.cmake .
cmake --graphviz=CmakeGraphViz ..
dot -Tpng CmakeGraphViz.Ant -o ../doc/library-dependencies-autogenerated.png
rm CmakeGraphViz*

Development

The following items are still to-do:

  • Implement the wire chamber detector (hard)
  • Implement the conventional tagger ladder including magnetic field energy calibration (easier)
  • ~~Implement Mk1 unpacker (many things already provided)~~ Done including GZ decompression. Scaler buffer decoding still WIP.
  • ~~Implement EPICS reader, and some more slow control variables~~ Done for tagging efficiency at least.
  • Implement the pair-spectrometer
  • Add prompt-random subtraction to the tagging efficiency class

Detector Type Mapping to Goat/Acqu

Ant Goat
CB NaI
PID PID
MWPC0 MWPC
MWPC1
TAPS BaF2
PbWO4
TAPSVeto Veto

All other Ant detectors do not have a representation in Goat/Acqu.

Data flow

The physics classes analyse TEvents provided by different sources or amenders. The main source of events is the AntReader, which itself is either fed by some unpacker or by already unpacked and possibly reconstructed treeEvents. Additionally, the SlowControlManager needs to do proper buffering to make physics classes easy to implement.

External Components

Have a look at those very nice projects, which are used here: