do your funny little dance

Home > Projects > PySLHA


PySLHA is a Python-based reader, writer and plotter of supersymmetric mass spectra, breaking parameters and decays, via data files in the SUSY Les Houches Accord (SLHA) format.

SPS1a benchmark point, as seen by slhaplot
SPS1a benchmark point, as seen by slhaplot

Features include:

  • Support for reading and writing SUSY spectrum/decay files in SLHA1 and ISAWIG format
  • Convenient programmatic access to spectrum information
  • Automatic type conversion of numeric quantities
  • Scripts for conversion of SLHA to and from the ISAWIG format
  • slhaplot script produces beautiful (and customizable) mass spectrum plots in PDF, EPS, PNG and TeX formats
  • Decay line plotting is configurable via a branching ratio threshold, and line thickness scaled according to BR
  • Automatic particle label collision avoidance via label shifts or merges


PySLHA can be installed from the Python package archive entry using the standard easy_install/pip script method. See the PyPI page for details. It should be compatible with versions of Python from 2.4 onwards, but not yet including Python 3.x.

Usage instructions

To use the Python interface programmatically, just put the file within your Python search path – easy_install/pip should already do this if you install it using that tool. Then call import pyslha in your Python program, and off you go. At an interactive Python terminal session, you can get API information using

>>> import pyslha
>>> help(pyslha)

(as with any Python module or function). All functions are documented and it’s hopefully straightforward to understand. You could use the slha2isawig, isawig2slha, and slhaplot Python scripts as templates of how to use the interface.

The slha2isawig and isawig2slha scripts have essentially no command line options: you just supply a file of the appropriate type and it will be converted, e.g.

$ slha2isawig myspec.slha  # produces myspec.isa
$ isawig2slha myspec.isa  # produces myspec.slha

The slhaplot script is a bit more complicated, so it gets its own documentation section!

Spectrum plotting

You can plot SUSY mass spectra and allowed decays using the slhaplot command. Despite the name, slhaplot will plot spectra from both SLHA and ISAWIG files. To get the default plot, just supply the spectrum file name as an argument:

$ slhaplot myspec.slha  # produces myspec.pdf

You can process multiple spectrum files at once, including files in ISAWIG format if they end in .isa:

$ slhaplot myspec.slha yourspec.isa  # produces myspec.pdf and yourspec.pdf

To enable the plotting of decay lines you must supply a branching ratio threshold below which the decay arrows will not be displayed, using the --br switch. By default, the threshold BR is 1.1, i.e. no decay lines will ever be plotted. To show all decay lines, set the BR threshold to 0:

$ slhaplot --br=0 myspec.slha

The BR can also be specified as a percentage:

$ slhaplot --br=10% myspec.slha

By default the decay arrows will be plotted with a thickness and colour related to the branching ratio: this has been tweaked to provide a reasonable distribution of widths and colours for typical decay spectra, with the dominant decays nicely emphasised. If you want constant line widths, use the --decaystyle=const option. The other options are brwidth and brcolor, with the default being the combined brwidth+brcolor style.

The output format can be changed using the -f or --format command line option: the default format is pdf, which uses the LaTeX PGF/TikZ package to make nice graphics. Other graphical format codes are eps and png, whose effect is hopefully pretty obvious! Changing the format to tex will produce a .tex output file which you can edit and run through pdflatex or latex+dvips to make your own image file. By default the label font used will be Palatino – you can change this and other options without explicitly hacking the LaTeX output by supplying your own LaTeX preamble with the --preamble switch. The format specifiers can be combined so that e.g.

$ slhaplot --br=10% --format=tex,pdf,png,eps myspec.lha yourspec.isa hisspec.spc

will make spectrum outputs in the four specified formats, for each of the provided input files. Magic!

More options, such as specifying the output filename, or changing the algorithm for avoiding clashes of particle labels, are available: you can get the details for these, as well as the other options described here, by running slhaplot with the -h or --help flag.

If you want any really special effects, you will have to either edit the slhaplot script or the LaTeX output – hopefully this won’t be necessary too often, and when it’s needed it won’t be too painful!

Development and contributions

PySLHA is developed using the Mercurial distributed version control system, which means that it should be easy for users to hack the code and provide versioned patches for me to incorporate into future releases. You can browse the hg repository and check out code from

Thanks to Kamel Ibn Hassen Derouiche for packaging PySLHA for NetBSD.