SModelS Tools

Inside SModelS there is a number of tools that may be convenient for the user:

Cross Section Calculator

This tool computes LHC production cross sections for MSSM particles and writes them out in SLHA convention. This can in particular be convenient for adding cross sections to SLHA input files, see Basic Input. The calculation is done at LO with Pythia8 or Pythia6.4 ; K-factors for colored particles are computed with NLLfast .

The usage of the cross section calculator is:

smodelsTools.py xseccomputer [-h] [-s SQRTS [SQRTS …]] [-e NEVENTS] [-v VERBOSITY] [-c NCPUS] [-p] [-P] [-q] [-C] [-k] [-6] [-8] [-n] [-N] [-O] -f FILENAME
arguments:
-h, --help show this help message and exit
-s SQRTS, --sqrts SQRTS
 sqrt(s) TeV. Can supply more than one value (as a space separated list). Default is both 8 and 13.
-e NEVENTS, --nevents NEVENTS
 number of events to be simulated.
-v VERBOSITY, --verbosity VERBOSITY
 Verbosity (debug, info, warning, error)
-c NCPUS, --ncpus NCPUS
 number of cores to be used simultaneously. -1 means ‘all’.
-p, --tofile write cross sections to file (only highest order)
-P, --alltofile
 write all cross sections to file, including lower orders
-q, --query only query if there are cross sections in the file
-C, --colors colored terminal output
-k, --keep do not unlink temporary directory
-6, --pythia6 use pythia6 for LO cross sections
-8, --pythia8 use pythia8 for LO cross sections (default)
-n, --NLO compute at the NLO level (default is LO)
-N, --NLL compute at the NLO+NLL level (takes precedence over NLO, default is LO)
-O, --LOfromSLHA
 use LO cross sections from file to compute the NLO or NLL cross sections
-f FILENAME, --filename FILENAME
 SLHA file to compute cross sections for. If a directory is given, compute cross sections for all files in directory.

Further Pythia parameters are defined in smodels/etc/pythia8.cfg (for Pythia 8) or smodels/etc/pythia.card (for Pythia 6). .

A typical usage example is:

smodelsTools.py xseccomputer -s 8 13 -e 10000 -p -f inputFiles/slha/higgsinoStop.slha

which will compute 8 TeV and 13 TeV LO cross sections (at the LHC) for all MSSM processes using 10k MC events. If, after the LO cross sections have been computed, one wants to add the NLO+NLL cross sections for gluinos and squarks:

smodelsTools.py xseccomputer -s 8 13 -p -N -O -f inputFiles/slha/higgsinoStop.slha

The resulting file will then contain LO cross sections for all MSSM processes and NLO+NLL cross sections for the available processes in NLLfast (gluino and squark production). When reading the input file, SModelS will then use only the highest order cross sections available for each process.

Input File Checks

As discussed in Basic Input, SModelS accepts both SLHA and LHE input files. It can be convenient to perform certain sanity checks on these files as described below.

LHE File Checker

For a LHE input file only very basic checks are performed, namely that

  • the file exists,
  • it contains at least one event,
  • the information on the total cross section and the center of mass energy can be found.

The usage of the LHE checker is simply:

smodelsTools.py lhechecker [-h] -f FILENAME
arguments:
-h, --help show this help message and exit
-f FILENAME, --filename FILENAME
 name of input LHE file

A typical usage example is:

smodelsTools.py lhechecker -f inputFiles/slha/gluino_squarks.lhe

SLHA File Checker

The SLHA file checker allows to perform quite rigorous checks of SLHA input files. Concretely, it verifies that

  • the file exists and is given in SLHA format,
  • the file contains masses and decay branching ratios in standard SLHA format,
  • the file contains cross sections according to the SLHA format for cross sections,

In addition, one can ask that

  • all decays listed in the DECAY block are kinematically allowed, i.e. the sum of masses of the decay products may not exceed the mother mass. This check for “illegal decays” is turned off by default.

If any of the above tests fail (return a negative result), an error message is shown.

The usage of the SLHA checker is:

smodelsTools.py slhachecker [-h] [-xS] [-s SIGMACUT] [-illegal] [-dB] -f FILENAME
arguments:
-h, --help show this help message and exit
-xS, --xsec turn off the check for xsection blocks
-s SIGMACUT, --sigmacut SIGMACUT
 give sigmacut in fb
-illegal, --illegal
 turn on check for kinematically forbidden decays
-dB, --decayBlocks
 turn off the check for missing decay blocks
-f FILENAME, --filename FILENAME
 name of input SLHA file

A typical usage example is:

smodelsTools.py slhachecker -s 0.01 -f inputFiles/slha/lightSquarks.slha

Running this will print the status flag and a message with potential warnings and error messages.

Note

In SModelS versions prior to 1.2, the SLHA file checker also checked for the existence of displaced vertices or heavy charged particles in the input file. Since the inclusion of HSCP signatures in SModelS, these checks are no longer done by the SLHA file checker. However, if the input model contains a considerable fraction of cross-section going into displaced vertex signatures, a warning is issued on the screen when running SModelS.

Database Browser

In several cases the user might be interested in an easy way to directly access the database of Experimental Results. This can be conveniently done using the database browser. The browser owns several methods to select Experimental Results or DataSets satisfying some user-defined conditions as well as to access the meta data and data inside each Experimental Result.

The usage of the browser interface is:

smodelsTools.py database-browser [-h] -p PATH_TO_DATABASE [-t]
arguments:
-h, --help show this help message and exit
-p PATH_TO_DATABASE, --path_to_database PATH_TO_DATABASE
 path to SModelS database
-t, --text load text database, dont even search for binary database file

A typical usage example is:

smodelsTools.py database-browser -p ./smodels-database

Loading the database may take a few seconds if the binary database file exists. Otherwise the pickle file will be created. Starting the browser opens an IPython session, which can be used to select specific experimental results (or groups of experimental results), check upper limits and/or efficiencies for specific masses/topologies and access all the available information in the database. A simple example is given below:

In [1]: print ( browser )  #Print all experimental results in the browser
['ATLAS-SUSY-2015-01', 'ATLAS-SUSY-2015-01', 'ATLAS-SUSY-2015-02', 'ATLAS-SUSY-2015-02', ...

In [2]: browser.selectExpResultsWith(txName = 'T1tttt', dataType = 'upperLimit') #Select only the UL results with the topology T1tttt

In [3]: print ( browser ) #Print all experimental results in the browser (after selection)
['ATLAS-SUSY-2015-09', 'CMS-PAS-SUS-15-002', 'CMS-PAS-SUS-16-014', 'CMS-PAS-SUS-16-015', ...

In [4]: gluinoMass, LSPmass = 800.*GeV, 100.*GeV  #Define masses for the T1tttt topology

In [5]: browser.getULFor('CMS-PAS-SUS-15-002','T1tttt',[[gluinoMass,LSPmass],[gluinoMass,LSPmass]]) #Get UL for a specific experimental result
Out[5]: 5.03E-02 [pb]

In [6]: for expResult in browser[:5]:  #Get the upper limits for the first five of the selected results for the given topology and mass
   ...:     print ( expResult.getValuesFor('id'),'UL = ',expResult.getUpperLimitFor(txname='T1tttt',mass=[[gluinoMass,LSPmass],[gluinoMass,LSPmass]]) )
   ...:
   ['ATLAS-SUSY-2015-09'] UL =  None
   ['CMS-PAS-SUS-15-002'] UL =  5.03E-02 [pb]
   ['CMS-PAS-SUS-16-014'] UL =  4.10E-02 [pb]
   ['CMS-PAS-SUS-16-015'] UL =  1.80E-02 [pb]
   ['CMS-PAS-SUS-16-016'] UL =  5.76E-02 [pb]


In [7]: for expResult in browser[:5]:  #Print the luminosities for the first five selected experimental results
   ...:     print ( expResult.getValuesFor('id'),expResult.getValuesFor('lumi') )
   ...:
   ['ATLAS-SUSY-2015-09'] [3.20E+00 [1/fb]]
   ['CMS-PAS-SUS-15-002'] [2.20E+00 [1/fb]]
   ['CMS-PAS-SUS-16-014'] [1.29E+01 [1/fb]]
   ['CMS-PAS-SUS-16-015'] [1.29E+01 [1/fb]]
   ['CMS-PAS-SUS-16-016'] [1.29E+01 [1/fb]]

Further Python example codes using the functionalities of the browser can be found in Howto’s.

Interactive Plots Maker

This tool allows to easily produce interactive plots which relate the SModelS output with information on the user’s model stored in the SLHA files. It gives 2d plots in the parameter space defined by the user, with additional user-defined information appearing in hover boxes. The output is in html format for viewing in a web browser. The aim is not to make publication-ready plots but to facilitate getting an overview of e.g. the properties of points in a scan. NB: this needs SLHA model input and SModelS python output!

Required python packages are: plotly, pandas, pyslha, os, decimal

The usage of the interactive plots tool is:

smodelsTools.py interactive-plots [-h] [-p PARAMETERS] -f SMODELSFOLDER -s SLHAFOLDER [-o OUTPUTFOLDER] [-N NPOINTS] [-v VERBOSITY]
arguments:
-h, --help show this help message and exit
-p PARAMETERS, --parameters PARAMETERS
 path to the parameters file [./iplots_parameters.py]
-f SMODELSFOLDER, --smodelsFolder SMODELSFOLDER
 path to the smodels folder with the SModelS python output files.
-s SLHAFOLDER, --slhaFolder SLHAFOLDER
 path to the SLHA folder with the SLHA input files.
-o OUTPUTFOLDER, --outputFolder OUTPUTFOLDER
 path to the output folder, where the plots will be stored. [./plots]
-N NPOINTS, --npoints NPOINTS
 How many (randomly selected) points will be included in the plot. If -1 all points will be read and included (default = -1).
-v VERBOSITY, --verbosity VERBOSITY
 Verbosity (debug, info, warning, error)

A typical usage example is:

smodelsTools.py interactive-plots -f inputFiles/scanExample/smodels-output/ -s inputFiles/scanExample/slha -p iplots_parameters.py -o results/iplots/

which will produce 3x9 plots in the gluino vs squark mass plane from a small scan example, viewable in a web browser.

iplots parameters file

The options for the inteactive plots tool are defined in a parameters file, iplots_parameters.py in the above example. An example file, including all available parameters together with a short description, is stored in iplots_parameters.py. Since the plotting information is model dependent, there is no default setting – the iplots parameters file is mandatory input. Below we give more detailed information about each entry in this file.

  • plot_title: main overall title for your plots, typically the model name.
  • x and y axes: SLHA block and PDG code number of the variables you want to plot, e.g. ‘m_gluino’: [‘MASS’, 1000021].
    • variable_x: In a dictionary form, give the name of the x-axis variable, and the block and PDG code number to find it in the SLHA file. Example: variable_x = {‘m_gluino[GeV]’: [‘MASS’, 1000021]}.
    • variable_y: same for the y-axis. Example: variable_y = {‘m_suR[GeV]’: [‘MASS’, 2000002]}
  • spectrum hover information: defines which information from the input SLHA file will appear in the hover box. The syntax is again a python dictonary.
    • slha_hover_information: information from the input SLHA file, e.g. model parameters or masses. Example: slha_hover_information = {‘m_gluino’: [‘MASS’, 1000021], ‘m_suR’: [‘MASS’, 2000002], ‘m_LSP’: [‘MASS’, 1000022]}
    • ctau_hover_information: displays the mean decay length in meter for the listed particle(s). Example: ctau_hover_information = {‘ctau_chi1+’: 1000024}
    • BR_hover_information: defines for which particle(s) to display decay channels and branching ratios. Example: BR_hover_information = {‘BR_gluino’: 1000021}. WARNING: Lists of branching ratios can be very long, so the may not fit in the hover box. One can define the number of entries with BR_get_top, e.g. BR_get_top = 5 (default: BR_get_top = ‘all’).
  • SModelS hover information: defines, as a list of keywords, which information to display from the SModelS output. Example: smodels_hover_information = [‘SmodelS_excluded’, ‘r_max’, ‘Tx’, ‘Analysis’, ‘file’]. The options are:
    • SmodelS_excluded: prints whether the point is excluded or not by SModelS
    • r_max: shows the highest r-value for each parameter point
    • chi2: shows the chi^2 value, if available (if not, the output is ‘none’)
    • Tx: shows the topology/ies which give r_max
    • Analysis: shows the experimental analysis from which the strongest constraint (r_max) comes from
    • MT_max: shows the missing topology with the largest cross section (in SModelS bracket notation)
    • MT_max_xsec: shows the cross section of MT_max
    • MT_total_xsec: shows the total missing cross section (i.e. the sum of all missing topologies cross sections)
    • MT_long_xsec: shows the total missing cross section in long cascade decays
    • MT_asym_xsec: shows the total missing cross section in decays with asymmetric branches
    • MT_outgrid_xsec: shows the total missing cross section outside the mass grids of the experimental results
    • file: shows the name of the input spectrum file
  • Choice of plots to make
    • plot_data: which points you want to plot; the options are: all, non-excluded, excluded points. Example: plot_data = [‘all’, ‘non-excluded’, ‘excluded’]
    • plot_list: which quantities to plot in the x,y plane; the same options as for SModels hover information apply. Example: plot_list = [‘r_max’, ‘chi2’, ‘Tx’, ‘Analysis’, ‘MT_max’, ‘MT_max_xsec’, ‘MT_total_xsec’, ‘MT_long_xsec’, ‘MT_asym_xsec’]

File Permissions Fixer

In case the software was installed under a different user than it is used (as is the case for system-wide installs), we ship a simple tool that fixes the file permissions for the cross section calculation code.

The usage of the permissions fixer is:

smodelsTools.py fixpermissions [-h]
arguments:
-h, --help show this help message and exit

Execute the command as root, i.e.:

sudo smodelsTools.py fixpermissions

ToolBox

As a quick way to show the status of all external tools, use the toolbox:

smodelsTools.py toolbox [-h] [-c] [-l] [-m]
arguments:
-h, --help show this help message and exit
-c, --colors turn on terminal colors
-l, --long long output lines
-m, --make compile packages if needed