SModelS Tools

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

a cross section calculator based on Pythia8 (or Pythia6), NLLfast, and one based on Resummino,
SLHA and LHE file checkers to check your input files for completeness and sanity,
a database browser to provide easy access to the database of experimental results,
a plotting tool to make interactive plots based on plotly (v1.1.3 onwards),
a file permissions fixer to fix a problem with file permissions for the cross section computers in system-wide installs, and
a toolbox to quickly show the state of the external tools.

Cross Section Calculators

These tools compute LHC production cross sections for MSSM particles and write them out in SLHA convention. This is particularly convenient for adding cross sections to SLHA input files, see Basic Input.

Pythia and NLLfast Cross Sections

In the basic “xseccomputer”, the calculation is done at LO with Pythia8 or Pythia6.4 ; K-factors for colored particles are computed with NLLfast. Signal strength multipliers can optionally be supplied for each “mother” particle. However, use at your own risk! Make sure the output is sensible and contains all cross sections for all production mechanisms you are interested in!

The usage of the cross section calculator is:

smodelsTools.py xseccomputer [-h] -f FILENAME [-s SQRTS [SQRTS …]] [-6] [-8] [-e NEVENTS] [-v VERBOSITY] [-c NCPUS] [-p] [-P] [-n] [-N] [-O] [-S SSMULTIPLIERS] [-q] [-C] [-k] [–noautocompile]

options:

-h, --help: show this help message and exit
-f FILENAME, --filename FILENAME: SLHA file to compute cross sections for. If a directory is given, cross sections for all files in the directory are computed.
-s SQRTS, --sqrts SQRTS: LHC center-of-mass energy in TeV for computing the cross sections. Can be more than one value, e.g., -s 8 13 for both 8 TeV and 13 TeV cross sections. [13]
-6, --pythia6: use pythia6 for LO cross sections
-8, --pythia8: use pythia8 for LO cross sections (default)
-e NEVENTS, --nevents NEVENTS: number of events to be simulated [10000].
-v VERBOSITY, --verbosity VERBOSITY: Verbosity (debug, info, warning, error) [info]
-c NCPUS, --ncpus NCPUS: number of CPU cores to be used simultaneously. −1 means ‘all’. Used only when cross sections are computed for multiple SLHA files. [1]
-p, --tofile: write cross sections to file (only highest order)
-P, --alltofile: write all cross sections to file, including lower orders
-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
-S SSMULTIPLIERS, --ssmultipliers SSMULTIPLIERS: Signal strength multipliers, provided as dictionary of pids
-q, --query: only query if there are cross sections in the file
-C, --colors: colored terminal output
-k, --keep: do not unlink temporary directory
--noautocompile: turn off automatic compilation

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.

An example using signal strength multipliers (available from SModelS v2.0 onwards) is:

smodelsTools.py xseccomputer -s 8 13 -e 10000 --ssmultipliers "{ (1000021,1000021): 4.0, (1000001,-10000001): 2.0 }" -p -f inputFiles/slha/higgsinoStop.slha

This will compute 8 TeV and 13 TeV LO cross sections as above, but the cross section for gluino-pair production (pid 1000021) gets enhanced by a factor of 4, and squark-antisquark production gets enhanced by a factor of 2. For the pids, strings can be supplied instead of integers. Unix filename wildcard syntax is also supported. E.g. ‘100000?’ matches all left-handed squarks but no anti-squarks, ‘*1000001’ matches both (left-handed) down and anti-down. Multiple signal strength multipliers may be applicable to a single theory prediction.

Note that signal strength multipliers get applied only to LO cross sections. This means they are propagated to NLO and NLL level only if the LO cross sections are computed first and the NLO/NLL corrections added afterwards. In other words, if the xseccomputer is called with -n or -N argument but without -O (–LOfromSLHA), the –ssmultipliers argument will be ignored.

The cross section calculation is implemented by the XSecComputer class

Resummino Cross Sections

For electroweak-ino and/or slepton production cross sections, another tool based on Resummino is available. This can calculate EW cross sections at LO, NLO, and NLL+NLO orders. No K-factors are used, all orders are calculated independently.

The usage of the Resummino cross section calculator is:

smodelsTools.py xsecresummino [-h] -f FILENAME [-s SQRTS [SQRTS …]] [-part PARTICLES [PARTICLES …]] [-v VERBOSITY] [-c NCPUS] [-C CONF] [-x XSECLIMIT] [-p] [-P] [-n] [-N] [-k] [–noautocompile]

file.

options:

-h, --help: show this help message and exit
-f FILENAME, --filename FILENAME: SLHA file to compute cross sections for. If a directory is given, cross sections for all files in the directory are computed.
-s SQRTS, --sqrts SQRTS: LHC center-of-mass energy in TeV for computing the cross sections. Can be more than one value, e.g., -s 8 13 for both 8 TeV and 13 TeV cross sections. [13]

-part PARTICLES, –particles PARTICLES: list of daughter particles (given as PDG codes) to compute cross sections for. All valid combinations from the list will be considered. If no list of particles is given, the channels info from the resummino.py configuration file is used instead.

-v VERBOSITY, --verbosity VERBOSITY: verbosity (debug, info, warning, error). [info]
-c NCPUS, --ncpus NCPUS: number of CPU cores to be used simultaneously. -1 means ‘all’. Used only when cross sections are computed for multiple SLHA files. [1]
-C CONF, --conf CONF: path to resummino.py configuration file. [smodels/etc/resummino.py]
-x XSECLIMIT, --xseclimit XSECLIMIT: cross section limit in pb. If the LO cross section is below this value, no higher orders will be calculated. The default is 0.00001, set in the smodels/etc/resummino.py file.
-p, --tofile: write cross sections to file (only highest order)
-P, --alltofile: write all cross sections to file, including lower orders
-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)
-k, --keep: do not unlink temporary directory
--noautocompile: turn off automatic compilation

A typical usage example is:

smodelsTools.py xsecresummino -s 13 -p -n -f test/testFiles/resummino/resummino_example.slha -part 1000023 1000024

This will compute the (1000023,-1000024), (1000023, 1000024) and (-1000024,1000024) cross sections for sqrt(s)=13 TeV at NLO for the spectrum given in resummino_example.slha and append them to that SLHA file. Additional settings, like the PDF sets to use, are taken from the Resummino configuration file, smodels/etc/resummino.py. There, also the default threshold for the minimum cross section is set.

Instead of providing a list of particles via the –part argument, one can also directly specify in the resummino.py configuration file which production channels shall be considered. To this end one can either adapt the resummino.py file in the smodels/etc folder, or provide their own configuration file via the –conf argument. Note that options set directly on the command line always take precedence over the settings in the configuration file.

The resummino cross section calculation is implemented by the XSecResummino class

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.

The input file checks are implemented by the FileStatus class

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

options:

-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/lhe/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] [-illegal] [-dB] -f FILENAME

options:

-h, --help: show this help message and exit
-xS, --xsec: turn off the check for xsection blocks
-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 -f inputFiles/slha/gluino_squarks.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 stable charged particles in the input file. Since the inclusion of long lived signatures in SModelS, these checks are no longer done by the SLHA file checker.

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]

options:

-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-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-SUS-15-002','T1tttt',[[gluinoMass,LSPmass],[gluinoMass,LSPmass]]) #Get UL for a specific experimental result
Out[5]: 2.23E+01 [fb]

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-16-014'] UL =  4.10E+01 [fb]
   ['CMS-PAS-SUS-16-015'] UL =  1.80E+01 [fb]
   ['CMS-PAS-SUS-16-016'] UL =  5.76E+01 [fb]
   ['CMS-PAS-SUS-16-019'] UL =  1.37E+01 [fb]


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-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]]
   ['CMS-PAS-SUS-16-019'] [1.29E+01 [1/fb]]

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

The Database browser tool is implemented by the Browser class

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] [-m MODELFILE] -f SMODELSFOLDER -s SLHAFOLDER [-o OUTPUTFOLDER] [-N NPOINTS] [-v VERBOSITY]

options:

-h, --help: show this help message and exit
-p PARAMETERS, --parameters PARAMETERS: path to the parameters file [./iplots_parameters.py]
-m MODELFILE, --modelFile MODELFILE: path to the model.py file
-f SMODELSFOLDER, --smodelsFolder SMODELSFOLDER: path to the smodels folder or tarball (.tar.gz) with the SModelS python output files.
-s SLHAFOLDER, --slhaFolder SLHAFOLDER: path to the SLHA folder or tarball (.tar.gz) with the SLHA input files.
-o OUTPUTFOLDER, --outputFolder OUTPUTFOLDER: path to the output folder, where the plots will be stored. [./iplots]
-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) [info]

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 3x11 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 interactive 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. [‘MASS’, 1000021].
- variable_x: In a list form, give the the block and PDG code number of the x-axis variable, to find it in the SLHA file. Example: variable_x = [‘MASS’, 1000021]. Alternatively, you can provide custom names (instead of extracting them from a model.py file) to your x-axis variable in a dictionary form, e.g. {‘m_gluino’: [‘MASS’, 1000021]}.
- variable_y: same for the y-axis. Example: variable_y = [‘MASS’, 1000022] or variable_y ={‘m_neutralino1’: [‘MASS’, 1000022]}
spectrum hover information: defines which information from the input SLHA file will appear in the hover box. The syntax is again either a list or a dictionary.
- slha_hover_information: information from the input SLHA file, e.g. model parameters or masses. Example: slha_hover_information = [ [‘MASS’, 1000021], [‘MASS’, 2000002], [‘MASS’, 1000022]]. Alternatively, 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 = [1000024] or = {‘ctau_chi1+’: 1000024}
- BR_hover_information: defines for which particle(s) to display decay channels and branching ratios. Example: BR_hover_information = [1000021] or = {‘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 min_BR, e.g. min_BR = .05 (default ‘all’).
SModelS hover information: defines, as a list of keywords, which information to display from the SModelS output. Example: smodels_hover_information = [‘SModelS_status’, ‘r_max’, ‘Tx’, ‘Analysis’, ‘chi2’, ‘MT_max’, ‘MT_max_xsec’, ‘MT_total_xsec’, ‘MT_outgrid_xsec’, ‘MT_prompt_xsec’, ‘MT_displaced_xsec’, ‘file’]. The options are:
- SmodelS_status: 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_prompt_xsec: Shows the total cross section from prompt missing topologies
- MT_displaced_xsec: Shows the total cross section from displaced missing topologies
- 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 = [‘SModelS_status’, ‘r_max’, ‘Tx’, ‘Analysis’, ‘chi2’, ‘MT_max’, ‘MT_max_xsec’, ‘MT_total_xsec’, ‘MT_outgrid_xsec’, ‘MT_prompt_xsec’, ‘MT_displaced_xsec’, ‘file’]

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]

options:

-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]

options:

-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