H5root: a ROOT Based Graphical User Interface for H5hut

The purpose of this application is convenient graphical access to the data stored in HDF5 files written by H5hut (formerly known as H5Part) via a graphical user interface based on ROOT. H5root is tailored towards data analysis of particile accelerator simulations.

H5root snapshot H5hut on PSI Merlin
Installation Guide
Quick User Guide
Online Class Documentation
Known Bugs / Problems
Planned Features
Other Comments


Setup for the Merlin Cluster at PSI

Make sure ~adelmann/amas/bin is in your PATH.

Setup the .bashrc

Add the following lines to your .bashrc:
export ROOTSYS=/gpfs/home/adelmann/svnwork/root_v5.30.02

if [[ $PATH != *$ROOTSYS/bin* ]]; then
 export PATH=$ROOTSYS/bin:$PATH
fi
if [[ $LD_LIBRARY_PATH != *$ROOTSYS/lib* ]]; then
 export LD_LIBRARY_PATH=$ROOTSYS/lib:$LD_LIBRARY_PATH
fi
if [[ $MANPATH != *$ROOTSYS/man* ]]; then
 export MANPATH=$ROOTSYS/man:$MAN_PATH
fi

Run on Merlin

Now you should be able to start the postprocessing tool with:
H5root

Installation guide (version 1.1)

To run H5root, you will need to have installed HDF5, H5hut (serial), and ROOT. H5root 1.1 is based on HDF5 > 1.8.11, H5hut 1.99.12 and ROOT > 5.30.00. (Furthermore, we assume the presence of X11, gcc > 4.6.1 and autotools.) For simplicity, we assume that all libraries will be installed in the same location, specified by the environment variable LIBPATH. In bash for instance:
export LIBPATH=/scratch/extlib
(replace the path with your preferred location). (Of course you can also choose different locations for the libraries, you just have to tell H5root in the configure command where they are.)

HDF5 (version 1.8.11)

Download HDF5 from NCSA. Untarzip the tar ball and install it in your preferred location:
tar zxf hdf5-1.8.11.tar.gz
cd hdf5-1.8.11
./configure --enable-cxx --prefix=$LIBPATH/hdf5-1.8.11
make check
make install
Done!

H5hut (version 1.99.12)

Download the tar ball from H5hut Wiki. Untarzip the tar ball and install it in your preferred location. Keep in mind that H5hut needs to know where we have installed HDF5 (environment variable).
tar zxf H5hut-1.99.12.tar.gz
cd H5hut-1.99.12
./configure --enable-shared --prefix=$LIBPATH/H5hut --with-hdf5=$LIBPATH/hdf5-1.8.9  CXX=g++ CC=gcc
make install
If you run into trouble consider to check fPIC

ROOT (version 5.30.00)

Here we recommend to get the precompiled version from the ROOT site. If using the precompiled version, we just have to unpack it and set the right environment variables:
tar zxf root_v5.30.00.Linux.xxxx.tar.gz
mv root $LIBPATH/root-5.30.00
export ROOTSYS=$LIBPATH/root-5.30.00
export PATH=$ROOTSYS/bin/:$PATH 
export LD_LIBRARY_PATH=$ROOTSYS/lib/:$LD_LIBRARY_PATH
If you enjoy compiling, you can of course also build ROOT from source, see here for instructions.

Now we are ready to install H5root:

H5root (version 1.2)

Get the tar ball from here: h5root-1.2.0.tar.gz.
tar zxf h5root-1.2.0.tar.gz
cd h5root-1.2.0
./configure --with-hdf5=$HDF5ROOT/hdf5-1.8.5 --with-h5hut=$H5HUTROOT/H5hut-s --with-root=$ROOTSYS --enable-h5hut --enable-root --enable-hdf5
make install
Now you will find a static executable H5root in the subdirectory $LIBPATH/h5root-1.1/h5root, which you may copy anywhere you find convenient. To test the program, you can download a small (11M) test file, and do:
./H5root test.h5

The shared objets are at $LIBPATH/h5root-1.1/src/.libs/ This will give you a shared library $LIBPATH/libh5root.so, which you can load into a regular ROOT session (see below).

Quick User Guide

There are two ways to use H5root: 1) as a data browser (no knowledge whatsoever about C++ or ROOT is needed) or 2) as a shared library loaded into an interactive ROOT session (some knowledge of C++ and ROOT required). Of course you can also use the H5root shared library in ROOT macros or compiled executables.

A detailed user guide is in preparation and will be released with the next version of H5root. In the meantime you are invited to read the following quick guide, or look at the online class documentation (see below).

Data Browser

Once you have built the application (with --enable-static), just do ./H5root. The main GUI will appear. The menus are meant to be self-explaining, for instance, File -> Load pops up a file browser that lets you pick the file(s) you want to load. Up to four files may be loaded in the same session.

Then you just select variables, time step etc. and push the buttons! You can select multiple files and multiple variables, the program is supposed to produce the plot that makes most sense given the input. (Note, however, that many multi-file and/or multi-variable plots have not yet been implemented. Missing methods issue an error message for the time being and will be implemented later according to demand.)

Command line arguments

H5root comes with limited command line functionality:

Canvas editor

Edit -> Canvas will pop up ROOT's nifty Canvas editor, which lets you change the properties of the specific plot you just created. For instance, you can change the marker size on a line plot. Initially, the editor is set to the canvas, you can change its focus by simply clicking on the objects on the plot (graph, histogram, label, etc.)

Note also that you can zoom into plots clicking and dragging along the axes. This will stretch your plot without adding more information. For a true rebinning of the plot, use the zoom sliders on the left and at the bottom of the plot (or change the binning via Options -> Binning and Contours...).

The Shared Library

You create the shared libary when compiling the application. Once you have your shared object libh5root.so, you can load it into any interactive ROOT session with the command
   if (TString(gSystem->GetBuildArch()) == TString("macosx64"))
     gSystem->Load("libh5root.dylib");
   else
     gSystem->Load("libh5root.so");

You can then access all the H5root objects, such as (and most probably) TH5Dataset, while fully profiting from ROOT's powerful CINT interpreter. An example session on Linux would look like this:
gSystem->Load("libh5root.so"); -- load the shared library
TH5Style::SetStyle(); -- set the H5root plotting style
TH5Dataset data("example.h5"); -- load data in example.h5
data.Histo2d("x","y"); -- plot x and y (for default step 0, with default ranges from -1 to 1)
data.Histo2d("x","y",100,-0.02,0.02,-0.015,0.015); -- for step 100, with x-range and y-range specified
data.H<Tab> -- check what other methods starting with H... are available for this object!

The most convenient way to generate a line plot is via the method GetGraphXY. Here's an example (see source code for extensive documentation):

data.SetSlicePosition("mean"); -- slice should be centered around mean z of all particles
(other options are "median", "half" − for the position halfway between zmin and zmax − "start", "end", and "peak".
data.SetSliceLength(0.5,"mm"); -- slice length should be 0.5 mm (you can also specify in "ps").
Alternatively, you can request a slice that contains x percent of the whole bunch, via data.SetSlicePercent(x);!
TGraph* sliceEmittance = data.GetGraphXY("SPOS","emittance(x,px)","slice");
TH1F *frame = myCanv->DrawFrame(0.,0.,1.0,0.00015);
frame->SetXTitle("s [m]");
frame->SetYTitle("#varepsilon_{x} [mm mrad]");
sliceEmittance->Draw("LPsame");
myCanv->Update();

For more complex operations you will likely want to write a macro. The example macro example.C is enclosed in the package. It was used to produce this jpeg image:
H5root shared library

Online Class Documentation

The online class documentation for version 1.2 is produced with ROOT's THtml class.

Known Bugs / Problems

Planned Features

(in rough order of priority)

Other Comments





Last update:

andreas.adelmann@psi.ch