1.1 Purpose of the document
This document is intended as a combination of user guide and tutorial for the use of the Gaudi application framework software. It is complemented principally by two other "documents": the Architecture Design Document (ADD) , and the online auto-generated reference documentation . A third document  lists the User Requirements and Scenarios that were used as input and validation of the architecture design. All these documents and other information about Gaudi, including source code documentation, are available via the Gaudi home page: http://cern.ch/proj-gaudi. Documentation of the LHCb extensions to Gaudi, and a copy of this user guide, are available on the LHCb web at: http://cern.ch/lhcb-comp/Frameworks/Gaudi/. It is recommended that you also study the material of the LHCb Gaudi tutorials given at CERN, which is available at http://cern.ch/lhcb-comp/Frameworks/Gaudi/GaudiTutorial.htm. Should you wish to enrol on a future tutorial, you should send mail to Markus.Frank@cern.ch.
The ADD contains a discussion of the architecture of the framework, the major design choices taken in arriving at this architecture and some of the reasons for these choices. It should be of interest to anyone who wishes to write anything other than private analysis code.
As discussed in the ADD the application framework should be usable for implementing the full range of offline computing tasks: the generation of events, simulation of the detector, event reconstruction, testbeam data analysis, detector alignment, visualisation, etc. etc..
In this document we present the main components of the framework which are available in the current release of the software. It is intended to increment the functionality of the software at each release, so this document will also develop as the framework increases in functionality. Having said that, physicist users and developers actually see only a small fraction of the framework code in the form of a number of key interfaces. These interfaces should change very little if at all and the user of the framework cares very little about what goes on in the background.
The document is arranged as follows: Chapter 2 is a short resume of the framework architecture, presented from an "Algorithm-centric" point of view, and re-iterating only a part of what is presented in the ADD.
Chapter 3 contains a summary of the functionality which is present in the current release, and details of how to obtain and install the software.
Chapter 4 discusses in some detail an example which comes with the framework library. It covers the main program, some of the basic aspects of implementing algorithms, the specification of job options and takes a look at how the code is actually executed. The subject of coding algorithms is treated in more depth in Chapter 5.
Chapter 6 discusses the use of the framework data stores and event data. Chapter 7 gives pointers to guidelines for defining the LHCb event data model. Chapters 8, 9, 10 discuss the other types of data accessible via these stores: detector description data (material and geometry), histogram data and n-tuples.
Chapter 11 deals with services available in the framework: job options, messages, particle properties, auditors, chrono & stat, random numbers, incidents, introspection. It also has a section on developing new services. Framework tools are discussed in Chapter 12, the use and implementation of converter classes in Chapter 13.
Chapter 14 discusses scripting as a means of configuring and controlling the application interactively. This is followed by a description in Chapter 15 of how visualisation facilities might be implemented inside Gaudi.
Chapter 16 describes the package structure of Gaudi and discusses the different types of libraries in the distribution.
Chapter 17 gives pointers to the documentation for class libraries which we are recommending to be used within Gaudi.
The use of certain SICB facilities within Gaudi and the wrapping of FORTRAN code are discussed in Chapter 18.
Appendix A contains a list of references. Appendix B lists the options which may be specified for the standard components available in the current release. Appendix C gives the details of the syntax and possible error messages of the job options compiler. Finally, Appendix D is a small guide to designing classes that are to be used in conjunction with the application framework.1.2 Conventions
We have decided to adopt the same system of units as CLHEP, as used also by GEANT4. This system is fully documented in the CLHEP web pages, at the URL: http://wwwinfo.cern.ch/asd/lhc++/clhep/manual/UserGuide/Units/units.html.
The list of basic units is reproduced in Table 1.1. Note that this differs from the convention used in SICB, where the basic units of length, time and energy are, respectively, centimetre, GeV, second..
Table 1.1 CLHEP system of units
Amount of substance
Users should not actually need to know what units are used in the internal representation of the data, as long as they are consistent throughout the Gaudi data stores. What they care about is that they can define and plot quantities with the correct units. In some specialised algorithms they may also wish to renormalise the data to a different set of units, if the default set would lead to numerical precision problems.
We therefore propose the following rules, which are discussed more fully in reference .1. All dimensioned quantities in the Gaudi data stores shall conform to the CLHEP system of units.
2. All definitions of dimensioned quantities shall be dimensioned by multiplying by the units defined in the CLHEP/Units/SystemOfUnits.h header file. For example:
const double my_height = 170*cm;
const double my_weight = 75*kg;
Note that the user should not care about the numerical value of the numbers my_height and my_weight. Internally these numbers are represented as 1700. and 4.68e+26. respectively, but the user does not need to know.
3. All output of dimensioned quantities should be converted to the required units by dividing by the units defined in the CLHEP/Units/SystemOfUnits.h header file. For example:
my_hist = histoSvc()->book( "/stat/diet","corpulence (kg/m**2)",30,10.,40.);
double my_corpulence = my_weight / (my_height*my_height);
my_hist->fill( my_corpulence/(kg/m2), 1. );
which, for a healthy person, should plot a number between 19. and 25....
4. Physical constants should not be defined in user code. They should be taken directly from the CLHEP/Units/PhysicalConstants.h header file. For example:
float my_rest_energy = my_weight * c_squared;
5. Users may wish to use a different set of units for specific purposes (e.g. when the default units may lead to precision problems). In this case algorithms can renormalise their private copy of the data (as shown in the last line of the rule 3 example) for internal use, but making sure that any data subsequently published to the public data stores is converted back to the CLHEP units.
1.2.2 Coding Conventions
The Gaudi software follows (or should follow!) the LHCb C++ coding conventions described in reference . A tool to check compliance with these coding conventions is described at http://cern.ch/lhcb-comp/Support/Conventions/RuleChecker.htm18.104.22.168 File extensions
One consequence of following the LHCb coding conventions is that the specification of the C++ classes is done in two parts: the header or ".h" file and the implementation or ".cpp" file.
We also define file extensions for Gaudi specific files. The recommended file extension for Job Options files is ".opts" (see Section 11.3.3 on page 116). For Python scripts, the extension ".py" is mandatory (see Chapter 14).1.2.3 Naming Conventions
In order to avoid clashes in histogram identifiers, we suggest that histograms are placed in named subdirectories of the transient histogram store. The top level subdirectory should be the name of a sub-detector group (e.g. VELO). Below this, users are free to define their own structure. One possibility is to group all histograms produced by a given algorithm into a directory named after the algorithm.
Naming conventions for LHCb data are discussed in reference .
1.2.4 Conventions of this document
are used in two contexts. To avoid confusion we outline the difference with an example.
The definition of a templated class uses angle brackets. These are required by C++ syntax, so in the instantiation of a templated class the angle brackets are retained:
Hopefully what is intended will be clear from the context.1.3 Reporting problems
Users of the Gaudi software are encouraged to report problems and requests for new features via the LHCb problem reporting system. This system is integrated in the CERN Problem Report Management System (CPRMS) provided by IT division, based on the Action Request System software from Remedy Corporation.
To report a new problem, go to the LHCb CPRMS home page http://cern.ch/hep-service-prms/lhcb.html, click on the Submit button, and fill in the form. This will add the report to the system and notify the developers by E-mail. You will receive E-mail notification of any changes in the status of your report.
To view the list of current problems, and their status, click the Query button on the LHCb CPRMS home page.
Active developers of the Gaudi software are encouraged to use the gaudi-developers mailing list for discussion of Gaudi features and future developments. This list is not, primarily, intended for bug reports. In order to send mail to firstname.lastname@example.org, you must first subscribe to the list, using the form at https://email@example.com. You need a CERN mailserver account to be able to use this form...
The archive of the mailing list is publically accessible on the Web, at http://cern.ch/~majordom/news/gaudi-developers/index.html.1.4 Editor's note
This document is a snapshot of the Gaudi software at the time of the release of version v9. We have made every effort to ensure that the information it contains is correct, but in the event of any discrepancies between this document and information published on the Web, the latter should be regarded as correct, since it is maintained between releases and, in the case of code documentation, it is automatically generated from the code.
We encourage our readers to provide feedback about the structure, contents and correctness of this document and of other Gaudi documentation. Please send your comments to the editor, Marco.Cattaneo@cern.ch
Voice: (512) 719-3399
Fax: (512) 719-3606