.. title: PySLHA
.. slug: pyslha
.. date: 2010-12-29 00:00:00
.. type: text
.. category: software project slha susy bsm
`PySLHA `_ is a `Python-based
`_ reader, writer and plotter of BSM mass spectra,
parameters and decays, via the `SUSY Les Houches Accord (SLHA)
`_ data format.
.. figure:: /sps1a.png
:align: right
SPS1a benchmark point, as seen by `slhaplot`. `Click for full version. `_
Features
--------
PySLHA features include:
* Support for reading and writing SUSY/BSM spectrum/decay files in SLHA1,2,3 and ISAWIG formats
* 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 configurable via a branching ratio threshold, and line thickness scaled according to BR
* Automatic particle label collision avoidance via label shifts or merges
Installation
------------
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 `pyslha.py` 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
.. code-block:: python
>>> 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.
.. code-block:: sh
$ 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:
.. code-block:: sh
$ slhaplot myspec.slha # produces myspec.pdf
You can process multiple spectrum files at once, including files in ISAWIG format if they end in `.isa`:
.. code-block:: sh
$ 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:
.. code-block:: sh
$ slhaplot --br=0 myspec.slha
The BR can also be specified as a percentage:
.. code-block:: sh
$ 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](http://sourceforge.net/projects/pgf/) 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.
.. code-block:: sh
$ 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](http://mercurial.selenic.com/) 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 http://hg.insectnation.org/pyslha.
Thanks to Kamel Ibn Hassen Derouiche for `packaging PySLHA for NetBSD `_.