   |   |
GAUDI User Guide
| | |
GAUDI User Guide
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) [1], and the online auto-generated reference documentation [2]. A third document [3] 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 this user guide, are available from the Gaudi home page: http://cern.ch/lhcb-comp/Components/html/GaudiMain.html
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. Chapters 7, 8, 9, 10 discuss the different types of data accessible via these stores: event data, 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, random numbers and also has a section on developing new services. Framework tools are discussed in Chapter 12.
A rather more technical subject, that of the use and implementation of converter classes is discussed in Chapter 13.
The use of certain SicB facilities from within Gaudi, and the use of FORTRAN code is discussed in Chapter 14. Chapter 15 gives pointers to the documentation for class libraries which we are recommending to be used within Gaudi.
Chapter 16 describes an implementation of visualisation facilities inside Gaudi. Finally, Chapter 17 is a small guide to designing classes that are to be used in conjunction with the application framework.
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.
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 3. Note that this differs from the convention used in SICB, where the basic units of length, time and energy are, respectively, centimetre, GeV, second.
|
Quantity
|
Unit
|
|---|---|
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 [4].
CLHEP/Units/SystemOfUnits.h
header file. For example:
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.
const double my_height = 170*cm;const double my_weight = 75*kg; |
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. ); |
CLHEP/Units/PhysicalConstants.h
header file. For example:
float my_rest_energy = my_weight * c_squared; |
The Gaudi software follows (or should follow!) the LHCb C++ coding conventions described in reference [5] . One consequence is that the specification of the C++ classes is done in two parts: the header or ".h" file and the implementation or ".cpp" file.
/stat/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.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:
AlgFactory<UserDefinedAlgorithm> s_factory; |
This is to be contrasted with the use of angle brackets to denote "replacement" such as in the specification of the string:
"<concreteAlgorithmType>/<algorithmName>" |
which implies that the string should look like:
"EmptyAlgorithm/Empty" |
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 gaudi-developers@listbox.cern.ch , you must fist subscribe to the list, using the form at http://wwwlistbox.cern.ch/mowgli/full_list?server=listbox&group=&list=gaudi-developers .
The archive of the mailing list is publically accessible on the Web, at http://home.cern.ch/~majordom/news/gaudi-developers/index.html .
This document is a snapshot of the Gaudi software at the time of the release of version 6. 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