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
Transient HTL: very simple text file persistence (free)
Installing/getting HTL from outside Cern
Building your own version of HTL
Known bugs and limitations
A Python script to transform HTL output into HBOOK output (author Nikolas Kauer)
HTL installation at Cern
HTL is part of the LHC++ package release. Libraries and include files are
A copy of the checkout repository including examples is located at:
The Windows/NT version of HTL is available on Nice as well at:
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:
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
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:
tar xvf HTL.tar
define the place where the global makefiles are:
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:
Now build the library according to the instructions in the file
doc/histolib.html (some information is relevant only for
The current production release is version 18.104.22.168. 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_VERSIONS
which exists in the HTL subdirectory.
Inside each HTL release, the file release_notes gives more
detailed information about the fixes (from version 22.214.171.124 onwards).
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 126.96.36.199 and 188.8.131.52
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
This limitation has been solved in release 184.108.40.206
Assertion failures doing binary operations
These bugs have been fixed in version 220.127.116.11
Binary operations on histograms with different binning cause an assertion
Under some circumstances binary operations with histograms having the same
binning may rise an assertion failure.
Version 18.104.22.168 (LHC++ 99a release)
These bugs/limitations have been fixed in version 22.214.171.124 (aka Sept99).
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.
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 )