Table of Contents
This chapter provides an overview of HTL features. Example code is based on the use of the non-templated classes that are recommended for use in typical analysis jobs. The HTL package itself includes a complete set of working examples that can be used as a basis for building more complex applications. A description of these examples can be found in Appendix Appendix D..
The basic operations of creating (booking) and filling histograms are shown below. As the code fragments illustrate, these operations are performed using methods that have the same basic signature as the equivalent HBOOK subroutines. The primary difference is that the HBOOK histogram identifier (ID) is replaced by "smart pointers". These pointers indicate both the type of the histogram to which they refer (e.g. 1D, 2D) and whether they are transient or not.
As will be familiar to all HBOOK users, the following information is specified at booking time:
For histograms of more than one dimension, the last three arguments are then repeated for each dimension.
The following example shows the booking and filling of a 1D histogram of 20 bins and a 2D histogram of 50 bins in both X and Y axes.
#include "HTL/PHistograms.h" // Persistent histograms.
...
// Booking a 20 bin 1D histogram
HepRef(PHisto1D) histo1 =
new (db_) PHisto1D("A 1D histogram",20,0.,40.);
// Booking a 50X50 bins 2D histogram
HepRef(PHisto2D) histo2 =
new (db_) PHisto2D("A 2D histogram",50,5.,15.,50,5.,15.);
// Filling
double x, w = 0.5;
for( long i=0; i<50000; i++ ) {
x = -i*sin(float(i));
histo->fill(x,w);
histo2->fill(x,x,w);
}
The current implementation of HTL uses an Object Database (ODBMS) to provide powerful and scalable persistence capabilities that go beyond what is possible with simple files. [1]
In the following, it is assumed that the reader is familiar with the basic concepts of using an ODBMS. For example, any operations on persistent objects must be performed in the context of a transaction and a database session must have been established. The necessary code to perform such operations has been omitted in the interests of clarity.
Although the basic histogram operations that are performed in the above example will be clear to HBOOK users, the use of "smart-pointers" differs from the traditional use of histogram IDs and needs further explanation. Consider the following code fragment:
HepRef(PHisto1D) histo1 = new ...
rather than
PHisto1D *histo1 = new ...
In this piece of code, HepRef is a smart pointer to a persistent histogram. As the previous example shows, a smart pointer can be used as a standard C++ pointer: that is, you can dereference it in the normal C++ manner:
histo1->fill(...)
In addition to the use of smart pointers, the new() operator should be studied. It is followed by a so-called clustering hint. A clustering hint is used to indicate where the persistent objects - histograms in this case - should be physically located on persistent storage. The database attempts to place new objects "close" to those referenced by the hint. In general, the efficient use of clustering allows performance to be maximised, as objects are transferred to and from disk and across the network in database pages. Effective clustering minimises unnecessary I/O and improves cache efficiency.
Finally, we note that the histograms created with new() are not deleted with a corresponding delete() operator. This would not only delete the histogram in the running application but also from persistent storage, which is presumably not the intention.
Simple file-based persistence is also provided - see chapter 2 for a description of the write method.