HTL - The Histogram Template Library (original) (raw)

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 Anaphe, 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
New features
Known bugs and limitations
A Python script to transform HTL output into HBOOK output (author Nikolas Kauer)

Documentation

• HTL UserGuide(PDF Version)
• Transient HTL Reference guide(PDF Version)
• Persistent HTL Reference Guide(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//HTL/
A copy of the checkout repository including examples is located at:
/afs/cern.ch/sw/lhcxx/share/HTL/

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 a copy of the source code to build your own transient HTL,you can download it here:

Access to HTL Source distributions

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 (X.Y.W.Z is the version number, i.e. 1.3.1.2) :
  • gunzip HTL.X.Y.W.Z.tar.gz
  • tar xvf HTL.X.Y.W.Z.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.1.1. 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).

New features

Version 1.3.1.2 introduces some limited support for exceptions. Exceptions are thrown only by histogram constructors in case of wrong binning (i.e. min value greater than max value, less than two points to define variable binned histograms).

Exceptions are disabled by default. In order to use exceptions, both the HTL library and the application must be compiled wth the additional flag HTL_USE_EXCEPTIONS, i.e. to make the libraries:

gmake all "HTL_USE_EXCEPTIONS=1" "HTL_VERSION=...."

while the application should be compiled with the additional flag-DHTL_USE_EXCEPTIONSUsers can then intercept the exception with the proper C++ try/catch mechanism, e.g.:

try { Histo1D histo ("Histo_1D", 0, 0.0, 20.0 ); }

catch (HTLExceptions::WrongBins) { std::cerr <<"Bin number is wrong" << std::endl; }

HTL_STD::vector my_points_on_X; try { Histo1DVar("Histo1DVar", my_points_on_X); }

catch (HTLExceptions::NotEnoughPoints) { std::cerr <<"Not enough points" << std::endl; }

This is the set of exceptions that could be raised:

namespace HTLExceptions { class WrongBinning {}; class WrongLimits : public WrongBinning {}; class WrongBins : public WrongBinning {};
class IncompatiblePartition : public WrongBinning {};
class NotEnoughPoints : public WrongBinning {};
}

Known Bugs/Limitations

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 )