• Python 2.6 or above
• graphviz (Present on lxplus)
• mcviz's source code.
• some physics events to look at.
• Examples can be found in the mcviz.examples repository
• Instructions to get HepMC with Athena
• A good svg viewer (Inkscape or Firefox will work nicely)

$ tar xf mcviz.tar.gz
$ cd mcviz
$ python2.6 mcviz_bootstrap.py

Try taking a look at MCViz's help for more information:

$ ./mcv --help
$ ./mcv --demo /my/hepmc/file && firefox mcviz.svg

MCViz is written in the spirit of open source. We especially rely on your feedback, so if you have any constructive criticism or notice any mistakes or inconsistencies no matter how small, please give us a shout at dev@mcviz.net. You can also checkout the source code and start committing to it, without needing our permission. Just let us know if you make something good!

MCViz supplies a number of ways of changing the presentation of your event. These are called "Tools". One of the basic ideas is that tools can be run one after another. Information about how to control the tools can be found with "./mcv --help".

The tool classes are applied in this order: Transforms, Annotations, Layout, Styles, Layout Engine and Painters. That might seem like more than a handful, but let's focus on one at a time:

Most tools take options of some kind. Information about these options can be done by running ./mcv --help toolname. If you want to miss out options, you can used named arguments. For example, you could write -edot:orientation=LR, which would specify the orientation parameter whilst leaving the others at their defaults.

A rough and ready list of tools and their options is available at ToolReference.

A transform can change the graph topology in some way. There are several reasons it might be desirable to do this, for example: Pythia has recoil vertices which cause particle lines to have apparent "kinks", nonphysical vertices. These can be removed with -tNoKinks.

Another example is -tGluballs, which causes all gluon self-interaction to be removed and summarized as one vertex with many gluons coming out of it.

A single transformation can be applied repeatedly, and the order in which transformations are specified matters.

These allow you to change the text that is shown next to a particle, to include information like the particle index, color, pt or MC status code. Multiple annotations can be specified at a time, and their individual locations (superscript, subscript, etc) can be specified.

The visual arrangement of the graph can be influenced with Layouts. When you specify multiple layouts, their behaviour is built up with inheritance. This means that several Layouts can be used through composition. However, some of the base layouts are mutually exclusive, and therefore incompatible with eachother, such as the Dual and Feynman layouts.

Some example uses of the Layout tool would be to change to the Dual of the Feynman representation, or to force the hadronization vertices to line up.

Styles control what colour the lines and particles will have, and how they are presented. In order to draw curly gluons, for instance, there is -sFancyLines.

MCViz does not actually perform the layout of the graph in 2D space for itself. Instead, graphviz is invoked.

Graphviz supplies multiple engines, each of which can produce very different effects and take very different lengths of time to run. More information can be found with "man graphviz", but the engines are the following programs:

• dot - Displays a heirarchical layout, which is useful for looking at the topology of an event. The orientation of the graph can be specified with -edot:orientation=XX where XX is LR or TB.

• fdp - Tries to layout the graph by using a "spring" model, where the edges attract and vertices repel. This can produce images which look more organic, but the layout can take a lot longer and it can be hard to tune it so that the result is not a mess.

These affect the way that MCViz writes the resulting image. At the moment, the main useful ones are svg, which outputs plain svg, and navisvg, which can be navigated with a recent web browser by clicking and dragging and using the mouse wheel to scroll.

For the below examples, we checked out the mcviz.examples (tarball) repository and linked mcviz.examples/mcviz/examples/inputs/ to ex/. The -psvg: option specifies to where the svg painter should save the resulting svg file.

A plain old graph:

./mcv ex/pythia/LEP/out09-zpole -psvg:doc/ex1.svg

We could add some colours using -sSimpleColors - the convention is that coloured particles are red, anti-coloured blue, gluons are green, bosons magenta and leptons almond.

./mcv ex/pythia/LEP/out09-zpole -psvg:doc/ex2.svg -sSimpleColors

Here is another way of colouring the graph, picking a hue for a given colour-anticolour pair, and using brightness to differentiate the colour from the anticolour.

./mcv ex/pythia/LEP/out09-zpole -psvg:doc/ex2.svg -sQCDRainbow

The graph is still a little cluttered. We can summarize the gluon self-interaction with the -tGluballs:

./mcv ex/pythia/LEP/out09-zpole -psvg:doc/ex4.svg -tGluballs -tClusters -sSimpleColors

It is also possible to change the orientation of the graph:

./mcv ex/pythia/LEP/out09-zpole -psvg:doc/ex5.svg -tGluballs -tClusters -sSimpleColors -edot:orientation=LR

Here is a demonstration of the dual of the "Feynman" graph.

./mcv ex/pythia/LEP/out09-zpole -psvg:doc/ex5.svg -tGluballs -tClusters -sSimpleColors -edot:orientation=LR -lDual

Here is a more complicated example, complete with an SVG you can zoom into online here.