HTL - The Histogram Template Library

The Histogram Template Library (HTL) is a C++ class library that provides powerful histogramming functionality.
As the name suggests, it exploits the template facility of C++ and is designed to be compact, extensible, modular and performant.
As such it only deals with histograms - i.e. binned data - and not unbinned or "Ntuple" data. Furthermore, although simple
file-based I/O and "lineprinter" output are supported, it is decoupled from more advanced I/O and visualisation techniques.
In the context of LHC++, such capabilities are provided by other components that fully interoperate with HTL.
HTL comes in two flavours:

Persistent HTL: based on Objectivity/DB for persistence (requires an Objectivity/DB license)

Transient HTL: very simple text file persistence (free)

Index

Documentation
Cern Installation
Installing/getting HTL from outside Cern
Building your own version of HTL
Current release
Known bugs and limitations

A Python script to transform HTL output into HBOOK output (author Nikolas Kauer)

Documentation

HTL User Guide (PS Version PDF Version)
Transient HTL Reference Guide (PS Version PDF Version)
Persistent HTL Reference Guide (PS Version PDF Version)

HTL installation at Cern

HTL is part of the LHC++ package release. Libraries and include files are located at:

/afs/cern.ch/sw/lhcxx/specific/<platform>/HTL/<release>

A copy of the checkout repository including examples is located at:

/afs/cern.ch/sw/lhcxx/share/HTL/<release>

The Windows/NT version of HTL is available on Nice as well at:

Z:\P32\lhcxx\share\HTL
Z:\P32\lhcxx\specific\Windows_NT\HTL

Libraries are installed as DLL, but since we exported only a subset of the library, users may find symbols which are not exported. In this case please let us know so that we can export the missing class/methods. A small batch file wich sets up the environment to use HTL is available as:

Z:\P32\lhcxx\share\HTL\pro\HTL.bat

Have a look at the script, modify it if necessary and just run it from a MS-DOS window. Be aware the NT version relies on Cygnus GNU utilities rather than on Visual C++ projects to compile and link examples (although the underlying compiler is VC++).

Getting HTL from outside Cern

If you're willing to get the whole LHC++ HEP stuff (i.e. excluding Objectivity/DB and Nag C libraries) or a copy of the source code to build your own transient HTL, have a look at our distribution page .

Building your own version of HTL

In order to build your own version of HTL:

get the tarball as explained in the previous section
unpack it with:

gunzip HTL.tar.gz
tar xvf HTL.tar

define the place where the global makefiles are:

cd HTL
setenv LHCXX_REL_DIR $PWD (csh,tcsh)
export LHCXX_REL_DIR=$PWD (sh,bash,ksh,zsh)

Check that the OS environment variable is properly set according to this list:

Linux
HP-UX
OSF1
Solaris

Now build the library according to the instructions in the file

doc/histolib.html (some information is relevant only for HTL editors)

Release status

The current production release is version 1.3.0.0. There are parallel directories named 1.X.Y.Z which contain the latest version of the library. Be aware such directories are by definition instable. A short list of release features is contained in the file README_VERSIONSwhich exists in the HTL subdirectory.

Inside each HTL release, the file release_notes gives more detailed information about the fixes (from version 1.1.0.4 onwards).

Known Bugs/Limitations

Incorrect bin centers on a slice/projection

The 1D histogram resulting from a slice or projection of a 2D histogram does contain wrong information for the bin centers. The centers are all equal to 0.5 rather then being set to the true bin center.

X and Y projections of a 2D histogram are swapped

The xProject() and yProject() methods of the 2D helpers are actually producing the wrong projection, i.e. xProject() produces the Y projection and viceversa.

These bugs have been solved in releases 1.1.1.2 and 1.2.1.0

Problems with NaN

Trying to fill an HTL histogram with a NaN (Not A Number) can result in weird HTL messages such as:

Assertion failed: an_index >= 0 && an_index <= count_, file Even_Partition.cpp, line 103

It's very likely some NaN checking code will be introduced on the next HTL release.

This limitation has been solved in release 1.1.0.4

Assertion failures doing binary operations

Binary operations on histograms with different binning cause an assertion failure.
Under some circumstances binary operations with histograms having the same binning may rise an assertion failure.

These bugs have been fixed in version 1.1.0.3

Version 1.1.0.0 (LHC++ 99a release)

The H_Bin_Helper::bin_center() method does compute the center as 0 if the bin is a Gravity bin and the bin has not been filled at least once (count = 0).
The I_Bin interface does not provide a setCenter() method.
Transient version only: the histogram title is not kept outside the creation scope if the title is passed as an automatic variable. Workaround: use a string literal.
Inclusion of Histograms.h file in more than one compilation unit caused the compiler to complain for multiple symbol definitions, e.g:

(error) H_2D_Helper::project(I_Histo&,int) is defined in files ExT_HTL_Histos_d.o and EcalHTLHistos_d.o

HTL is compiled using 'old' streams, e.g. <iostream.h> vs. <iostream>. This is a problem on NT, where users are not allowed to mix both types of streams. The HTL code has been modified so that it's possible to generate a library using the new stream definition files, although such library has been built on NT only and installed on Nice under Z:\P32\lhcxx\specific\Windows_NT\HTL\std.

These bugs/limitations have been fixed in version 1.1.0.0 (aka Sept99).

A Python script to transform HTL output into HBOOK output

Nikolas Kauer has written a Python script that transforms the "raw" HTL output in the good old HBOOK output ( download )