HEPMCVIEW

HepMCView is a teeny Python program which allows you to look at HepMC GenEvent
final state particles as 3D vectors. The author is Andy Buckley
<andy@insectnation.org>, who mainly wrote it for the hell of it, but also
because he wanted to know how to interface C++ to Python for Rivet and AGILe
purposes.


PREREQUISITES

* vpython's "visual" module

This is the 3D system that HepMCView uses (you didn't think I was going to write
my own 3D graphics library, did you?!?). Available through the Debian/Ubuntu
packaging system as python-visual. You could build it yourself from the sources
at www.vpython.org, but beware that it doesn't build on Scientific Linux 3 or 4
since, erm, both are now more than 3 years out of date and the rest of the world
has moved on...

* Python and C++ compiler

Obviously... but less obviously you need the Python headers, possibly available
as a system package called python-dev.

* HepMC

Also obviously, and also you need the headers. Latest versions (2.04 onwards)
are recommended but shouldn't be essential.

* SWIG

The Simple Wrapper and Interface Generator - this is used to take the pain out
of writing the Python-C++ boilerplate interface code. Pretty neat.

* GNU autotools

The usual automake, autoconf and libtool combination. You won't need this if you
got HepMCView as a tarball containing a "configure" script.


BUILDING IT

The usual... autoreconf, configure, make && make install. Current wrinkles are
that you must have specified a configure prefix such that libHepMC can be found
in $(prefix)/lib and its headers in $(prefix)/include.

I can't be bothered to write more instructions just now so mail me if you have
trouble. (andy@insectnation.org)


RUNNING IT

In principle, running HepMCView should just be a matter of calling the hepmcview
script (either from the build area or the $(prefix)/bin directory after the
"make install" build phase. The command takes the name of a HepMC IO_Ascii
format dump file as an argument:

> hepmcview path/to/ioascii-events.hepmc

If the installation is to a non-system location, you'll have to make sure that
your PYTHONPATH variable is set to include them:

* To run from the build directory without installing:
export PYTHONPATH=$PYTHONPATH:$PWD/.libs:$PWD

* To run from the installed location, if prefix isn't /usr (or maybe /usr/local):
export PYTHONPATH=$PYTHONPATH:<HEPMCVIEWINSTALLPREFIX>/lib/python<PYVERSION>/site-packages
(making sure to substitute for the things in angle brackets)

You also need to make sure that libHepMC is picked up by the runtime linker -
this may require something like this:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<HEPMCINSTALLPREFIX>/lib
(making sure again to substitute for the contents of angle brackets)


CONTROLLING THE VIEW

Assuming all is well, you should now have a window with an event display in
it. This includes 3 blue arrows as a reference (left-handed) Cartesian basis, a
rudimentary beam pipe made of blue rings, and coloured lines representing the
momenta of final state particles in the current event.

The display responds to some user input:

* To rotate the display in 3D, hold down the right mouse button and move the mouse;
* To zoom in and out, hold down L & R mouse buttons and move the mouse up or down;
* To see the next event, press "n" or the space bar.
* The particle momentum vectors are all anchored at the interaction point and the lengths are 
  proportional to log(|p_3|). To toggle the scaling between this "logified" measure 
  and the raw |p_3| measure, press "l" (you'll find that some vectors become enormous 
  and totally dominate the view in the "raw" mode)
* To toggle displaying the beams, press "b"
* To quit, press "ESC"

If you keep pressing for new events, at some point the event file will end. When
this happens, hepmcview will continue to display


BUGS AND TODOS

As a flippant personal project, hepmcview is riddled with bugs and
incompletenesses. Fixing these bugs and submitting the fixes to Andy is strongly
encouraged and may result in gifts of chocolate or beer if he's feeling
generous. Check the TODO file for inspiration.
