xSLHA: an Les Houches Accord reader for Python and Mathematica

TL;DR

xSLHA is a software package that efficiently reads and processes SLHA format files in Python and Mathematica, supporting standard and non-standard data blocks for high energy physics models.

Contribution

It introduces a fast, versatile parser for SLHA files in Python and Mathematica, accommodating deviations and large datasets for broader physics applications.

Findings

Supports large data samples efficiently

Handles non-standard blocks used by tools like HiggsBounds

Provides high-level language integration for SLHA data

Abstract

The format defined by the SUSY Les Houches Accord (SLHA) is widely used in high energy physics to store and exchange information. It is no longer applied only to a few supersymmetric models, but the general structure is adapted to all kind of models. Therefore, it is helpful to have parsers at hand which can import files in the SLHA format into high-level languages as Python and Mathematica in order to further process the data. The focus of the xSLHA package, which exists now for Python and Mathematica, was on a fast read-in of large data samples. Moreover, also some blocks used by different tools, as HiggsBounds for instance, deviate from the standard conventions. These are also supported by xSLHA.

Full text

††journal: Computer Physics Communications

morekeywords=cp,-r,make,cd, numbers=left, stepnumber=1, numberstyle=, numbersep=10pt, backgroundcolor=, basicstyle=, stringstyle=, keywordstyle=

1 Installation

In phenomenological High Energy Physics (HEP) the heavy use of numerical tools is unavoidable to obtain reliable predictions. Consequently, very sophisticated tools for collider studies, mass spectra calculations, or the prediction of dark matter properties have been developed and are widely used by the community. Since the different tools often need to be linked, a common format to represent information is necessary. The so called ’SUSY Les Houches Accord’ (SLHA) [1, 2] proposed such a format in the context of minimal supersymmetric theories already 15 years ago. In the following years, there have been proposals have to extent the format to non-minimal supersymmetric models [3], how to include information about flavour physics [4] or how to encode cross sections [5]. Nowadays, the SLHA format with its block structure is not only used in the context of supersymmetric models, but for all kind of BSM models. Therefore, code has been written to parse files in the SLHA format into different programming languages like C [6, 7], Fortran [8, 9], Mathematica [10] or Python [11, 12].

These parsers usually assume single SLHA files as input. However, re-running them very often in order to read many files into high-level languages as Mathematica or Python for further processing the data can became very time and memory consuming. Therefore, another SLHA parser appears now on the market: xSLHA for which a Python and Mathematica version exist. xSLHA makes use of fast shell tools as cat and grep to prepare the data before reading it in. Moreover, it is the first (public) model independent SLHA reader for Mathematica, and supports also some non-standard blocks as used by HiggsBounds or HiggsSignals for instance.

This manual explains the usage of xSLHA. In section 2 it is shown how to install and use the Python version of xSLHA. In section 3 the same is done for Mathematica version. A brief summary is given in section 4.

2 xSLHA for Python

2.1 Installation

The repository for the python version of xSLHA as available at

https://github.com/fstaub/xSLHA

However, the most convenient way to install it, is to make use of pip. The package is downloaded and installed by running

⬇

1> pip install xslha

in the terminal. Afterwards, it can be loaded in python by

⬇

1import xslha

2.2 Reading a single spectrum file

Reading a spectrum file file and storing the information in a class object spc is done via the command

⬇

1spc=xslha.read(file)

in python. One has afterwards access to the different information by using the Value command of the xSLHA class.

⬇

1spc.Value(’Keyword’, [Numbers])

For instance, common entries in a MSSM spectrum file are extracted as

⬇

1print("tan(beta): ",spc.Value(’MINPAR’,[3]))

2print("T_u(3,3): ",spc.Value(’TU’,[3,3]))

3print("m_h [GeV]: ",spc.Value(’MASS’,[25]))

4print("Gamma(h) [GeV]: ",spc.Value(’WIDTH’,25))

5print("BR(h->W^+W^-): ",spc.Value(’BR’,[25,[-13,13]]))

6print("Sigma(pp->N1 N1,Q=8TeV): ",spc.Value(’XSECTION’,[8000,(2212,2212),(1000021,1000021)]))

This produces the following output:

⬇

1tan(beta): 16.870458

2T_u(3,3): 954.867627

3m_h [GeV]: 117.758677

4Gamma(h) [GeV]: 0.00324670136

5BR(h->W^+W^-): 0.000265688227

6Sigma(pp->N1 N1,Q=8TeV): [[(0, 2, 0, 0, 0, 0), 0.00496483158]]

Thus, the conventions are:

the information given in the different SLHA blocks is returned by using using the name of the block as well as the corresponding number in the block as input

• 2.

the widths of particles are returned via the keyword WIDTH and giving the PDG of the particle

• 3.

for branching ratios, the keyword BR is used together with a nested list which states the PDGs of the decaying particle as well as of the final states

• 4.

for cross-sections the keyword XSECTION is used together with a nested list which states the centre-of-mass energy and the PDGs of the initial/final states. The result is a list containing all calculated cross-sections for the given options for the renormalisation scheme, the QED & QCD order, etc. (see the SLHA recommendations for details).

Another possibility to access the information in the spectrum file is to look at the different dictionaries which are created by the read command111We comment later on widths1L and br1L.:

⬇

1spc.blocks

2spc.widths

3spc.br

4spc.widths1L

5spc.br1L

6spc.xsctions

These dictionaries contain all information stored in the SLHA file.

2.3 Reading all spectrum files from a directory

In order to read several spectrum files located in a directory dir, one can make use of the command

⬇

1list_spc=xslha.read_dir(dir)

This generates a list list_spc where each entry corresponds to one spectrum file. Thus, one can for instance use

⬇

1[[x.Value(’MINPAR’,[1]),x.Value(’MASS’,[25])] for x in list_spc]

to extract the input for a 2D-scatter plot which shows the dependence of $m_{h}$ (MASS[25]) on $m_{0}$ (MINPAR[1]).

2.4 Fast read-in of many files

Reading many spectrum files can be time consuming. However, many of the information which is given in a SLHA file is often not needed for a current study. Therefore, one can speed up the reading by extracting first all relevant information. This generates smaller files which are faster to read in. This can be done via the optional argument entries for read_dir:

⬇

1list_spc_fast=xslha.read_dir("/home/$USER/Documents/spc1000",entries=["# m0","# m12","# hh_1"])‘

entries defines a list of strings which can be used to extract the necessary lines from the SLHA file by using cat and grep. Usually, the comments which are given for most entries in a SLHA file are very suitable for this purpose. For instance, the spectrum file for a CMSSM point generated with SARAH version of SPheno looks like

⬇

1Block MINPAR # Input parameters

2 1 1.50000000E+03 # m0

3 2 1.50000000E+03 # m12

4 3 1.00000000E+01 # TanBeta

5 4 1.00000000E+00 # SignumMu

6 5 -2.00000000E+03 # Azero

7…

8Block MASS # Mass spectrum

9# PDG code mass particle

10…

11 25 1.21048604E+02 # hh_1

12 35 2.63360770E+03 # hh_2

13 36 2.63354615E+03 # Ah_2

This explains, why we have chosen entries=["# m0","# m12","# hh_1"] in the example.

The speed improvement can be easily an order of magnitude if only some entries from a SLHA file are actually needed. We demonstrate this at a short example reading 1,000 SLHA files.

Reading the full spectrum files takes about 5–6 seconds:

⬇

1%%time

2list_spc=xslha.read_dir("/home/$USER/Documents/spc1000")

3

4CPU times: user 5.05 s, sys: 105 ms, total: 5.15 s

5Wall time: 5.51 s

while the relevant information is read in less than one second:

⬇

1%%time

2list_spc_fast=xslha.read_dir("/home/$USER/Documents/spc1000",entries=["# m0","# m12","# hh_1"])

3

4CPU times: user 147 ms, sys: 132 ms, total: 280 ms

5Wall time: 917 ms

We can compare these numbers also with the running time when using other available python parsers to read in all files

pylha:

⬇

1%%time

2all_spc=[]

3for filename in os.listdir("/home/$USER/Documents/spc1000/"):

4 with open("/home/$USER/Documents/spc1000/"+filename) as f:

5 input=f.read()

6 all_spc.append(pylha.load(input))

7

8CPU times: user 21.5 s, sys: 174 ms, total: 21.7 s

9Wall time: 21.7 s

• 2.

pyslha

⬇

1%%time

2all_spc=[]

3for filename in os.listdir("/home/$USER/Documents/spc1000/"):

4 all_spc.append(pyslha.read("/home/$USER/Documents/spc1000/"+filename))

5

6CPU times: user 13.3 s, sys: 152 ms, total: 13.5 s Wall time: 13.5 s

We see that xSLHA even without any restriction is already significantly faster for a large sample of files compared to the other packages.

2.5 Reading several spectra stored in a single file

Another common approach for saving spectrum files is to produce one huge file in which the different spectra are separated by a keyword. xSLHA can read such files by setting the optional argument separator for read:

⬇

1list_spc=xslha.read(file,separator=keyword)

In order to speed up the reading of many spectra also in this case, it is possible to produce first a smaller version of the files by defining the entries which should be read. The command for this reads

⬇

1list_spc=xslha.read_small(file,entries,separator)

In this case xSLHA extract all relevant lines first using cat and grep again. For instance, in order to read efficiently large files produced with SSP [13], one can use:

⬇

1list_spc=xslha.read("SpectrumFiles.spc",["# m0", "# m12", "# hh_1"],"ENDOFPARAMETERFILE")

2.6 Special blocks

There are some programs which use blocks that are not supported by the official SLHA conventions:

HiggsBounds[14, 15, 16] expects the effective coupling ratios in the blocks

• (a)

HIGGSBOUNDSINPUTHIGGSCOUPLINGSBOSONS

• (b)

HIGGSBOUNDSINPUTHIGGSCOUPLINGSFERMIONS

which are differently ordered compared to other blocks:

⬇

1Block HiggsBoundsInputHiggsCouplingsFermions #

2 6.67667670E-01 0.00000000E+00 3 25 5 5 # h_1 b b coupling

3 5.66931862E-01 0.00000000E+00 3 25 3 3 # h_1 s s coupling

4…

5Block HiggsBoundsInputHiggsCouplingsBosons #

6 1.11812190E+00 3 25 24 24 # h_1 W W coupling

7 1.08018976E+00 3 25 23 23 # h_1 Z Z coupling

Thus, first the numerical entries are stated before the number and the PDGs of the involved particles follow

• 2.

SPheno[17, 18] version generated by SARAH[19, 20, 21, 22, 23] can calculate one-loop corrections to the decays. The results are given in the blocks DECAY1L which appear in parallel to DECAY containing the standard calculation:

⬇

1DECAY 1000001 5.02288570E+01 # Sd_1

2# BR NDA ID1 ID2

3 2.84234837E-01 2 6 -1000024 # BR(Sd_1 -> Fu_3 Cha_1 )

4 1.85835591E-01 2 6 -1000037 # BR(Sd_1 -> Fu_3 Cha_2 )

5 2.20528398E-04 2 3 1000023 # BR(Sd_1 -> Fd_2 Chi_2 )

6….

7

8DECAY1L 1000001 4.79764029E+01 # Sd_1

9# BR NDA ID1 ID2

10 2.66279140E-01 2 6 -1000024 # BR(Sd_1 -> Fu_3 Cha_1 )

11 1.59538386E-01 2 6 -1000037 # BR(Sd_1 -> Fu_3 Cha_2 )

12 2.25120157E-04 2 3 1000023 # BR(Sd_1 -> Fd_2 Chi_2 )

xSLHA will distinguish these cases when reading the file and offer the two following options for Values in addition:

⬇

1spc.Values(’WIDTH1L’,1000022)

2spc.Values(’BR1L’,[1000023,[25,1000022]])

3 xSLHA for Mathematica

The Mathematica version of xSLHA is a re-write of the SLHA parser included in SSP. It is now very similar in its functionality to the Python version of xSLHA. Thus, the reader who carefully went through the last section will recognise quite some repetition in this section. This was kept in order to have also a stand-alone manual for the Mathematica version for those who don’t want to go through the Python section.

3.1 Installation

The repository for the Mathematica version of xSLHA is available at github:

github.com/fstaub/xSLHA.m

The simplest way to install the package is to put the file xSLHA.m into a xSLHA sub-directory of the applications directory of Mathematica. Thus,

/home/$USER/.Mathematica/Applications/xSLHA/

is the best place to store xSLHA.m. Afterwards, the package can be loaded via

in Mathematica.

3.2 Reading a single spectrum file

Reading a spectrum file file and storing the information in a variable spc is done via the command

The content of the spectrum file is returned on form of a list of replacements. Those can be used as follows in order to extract specific information:

⬇

In[1]Print["T_u(3,3): ",TU[3,3]/.spc]

In[2]Print["m_h [GeV]: ",MASS[25]/.spc]

In[3]Print["Gamma(h) [GeV]: ",WIDTH[25]/.spc]

In[4]Print["BR(h->W^+W^-): ",BR[25][-13,13]/.spc]

In[5]Print["Sigma(pp->N1 N1,Q=8TeV): ",XSECTION[8000,[2212,2212],[1000021,1000021]]/.spc]

This produces the following output

⬇

Out[1]T_u(3,3): 954.867627

Out[2]m_h [GeV]: 117.758677

Out[3]Gamma(h) [GeV]: 0.00324670136

Out[4]BR(h->W^+W^-): 0.000265688227

Out[5]Sigma(pp->N1 N1,Q=8TeV): {{{0, 2, 0, 0, 0, 0}, 0.00496483158}}

Thus, the conventions are:

the information given in the different SLHA blocks is returned by using using the name of the block as well as the corresponding number in the block as input

• 2.

the widths of particles are returned via the keyword WIDTH and giving the PDG of the particle

• 3.

for branching ratios, the keyword BR is used together with two sets of arguments which state the PDG of the decaying particle as well as of the final states

• 4.

for cross-sections the keyword XSECTION is used together with a nested list which states the centre-of-mass energy and the PDGs of the initial/final states. The result is a list containing all calculated cross-sections for the given options for the renormalisation scheme, the QED & QCD order, etc. (see the SLHA recommendations for details).

3.3 Reading all spectrum files from a directory

In order to read several spectrum files located in a directory dir, one can make use of the command

This generates a list listSPC where each entry corresponds to one spectrum. Thus, one can for instance use

to extract the input for a 2D-scatter plot showing the dependence of $m_{h}$ (MASS[25]) on $m_{0}$ (MINPAR[1]) in a CMSSM scan.

3.4 Fast read-in of many files

Reading many spectrum files can be very time consuming – especially in Mathematica. However, many of the information which is given in a SLHA file is often not needed for the current study. Therefore, one can speed up the reading by extracting first all relevant information. This generates smaller files which are faster to read. This can be done via the optional argument entries for ReadDir:

entries defines a list of strings which can be used to extract the necessary lines from the SLHA file by using cat and grep. Usually, the comments which are given for most entries in a SLHA file are very suitable for this purpose. Snippets of a CMSSM point generated with SPheno are shown in section 2.4. This explains, why we have chosen entries=["# m0","# m12","# hh_1"] in the example.

The impact of this optimisation for reading 1,000 files is as follows. Reading the full files takes about 3 minutes

⬇

In[1] ListSPC = xSLHA‘ReadDir["/home/$USER/Documents/spc1000/"];

In[2] ]

In[3]

In[4]{158.996, Null}

This needs to be compared with the 6–7 seconds needed to read the smaller files:

⬇

In[1] ListSPC =

In[2] xSLHA‘ReadDir["/home/$USER/Documents/spc1000/",

In[3] entries -> {"# m0", "# m12", "# hh_1"}];

In[4] ]

In[5]

In[6]{6.48319, Null}

We see that Mathematica is significantly slower in reading these files compared to Python. Thus, pre-processing the files is absolutely necessary for dealing with large data samples in Mathematica.

3.5 Reading several spectra stored in a single file

Another common approach for saving spectrum files is to produce one huge file in which the different spectra are separated by a keyword. xSLHA can read such files by setting the optional argument separator for Read:

In order to speed up the reading of many spectra also in this case, it is possible to define the entries as well which are need:

In this casexSLHA will produce first a smaller spectrum file using cat and grep. For instance, in order to read efficiently files produced with SSP, one can use:

3.6 Special blocks

There are some programs which use blocks that are not supported by the official SLHA conventions. We have collected them already in section 2.6 where also a bit more information about them is given. Those are also supported by xSLHA and are accessible via:

HiggsBounds blocks:

⬇

In[1]HIGGSBOUNDSINPUTHIGGSCOUPLINGSFERMIONS[25,13,-13] /.spc

• 2.

One-loop decays:

⬇

In[1]BR1L[1000023][25,1000022] /.spc

4 Summary

This manual introduces the SLHA parser xSLHA for Python and Mathematica. xSLHA is a handy and flexible reader which makes it easy to use the data stored in a SLHA spectrum file. It also provides wrapper functions to extract the relevant information from the files by using shell tools before reading it in. This can speeds up the important of large data samples by an order of magnitude and more.

Acknowledgements

I thank Martin Gabelmann Toby Opferkuch for testing xSLHA under Linux and MacOS. This work is supported by the ERC Recognition Award ERC-RA-0008 of the Helmholtz Association.