Using SModelS¶
SModelS can take SLHA or LHE files as input (see Basic Input). It ships with a command-line tool runSModelS.py, which reports on the SMS decomposition and theory predictions in several output formats.
For users more familiar with Python and the SModelS basics, an example code Example.py is provided showing how to access the main SModelS functionalities: decomposition, the database and computation of theory predictions.
The command-line tool (runSModelS.py) and the example Python code (Example.py) are described below.
Note
For For non-MSSM (incl. non-SUSY) input models the user needs to modify particles.py and specify which BSM particles are even or odd under the assumed Z2 symmetry (see adding new particles). Finally, if the user wants to check the input files for possible issues using SModelS’ SLHA and LHE file checkers, it is also necessary to define the BSM particle quantum numbers in particles.py [1].
runSModelS.py¶
runSModelS.py covers several different applications of the SModelS functionality, with the option of turning various features on or off, as well as setting the basic parameters. These functionalities include detailed checks of input SLHA files, running the decomposition, evaluating the theory predictions and comparing them to the experimental limits available in the database, determining missing topologies and printing the output in several available formats.
Starting on v1.1, runSModelS.py is equipped with two additional functionalities. First, it can process a folder containing a set of SLHA or LHE file, second, it supports parallelization of this input folder.
The usage of runSModelS is:
runSModelS.py [-h] -f FILENAME [-p PARAMETERFILE] [-o OUTPUTDIR] [-d] [-t] [-V] [-c] [-v VERBOSE] [-T TIMEOUT]
- arguments:
-h, --help show this help message and exit -f FILENAME, --filename FILENAME name of SLHA or LHE input file or a directory path (required argument). If a directory is given, loop over all files in the directory -p PARAMETERFILE, --parameterFile PARAMETERFILE name of parameter file, where most options are defined (optional argument). If not set, use all parameters from etc/parameters_default.ini -o OUTPUTDIR, --outputDir OUTPUTDIR name of output directory (optional argument). The default folder is: ./results/ -d, --development if set, SModelS will run in development mode and exit if any errors are found. -t, --force_txt force loading the text database -V, --version show program’s version number and exit -c, --run-crashreport parse crash report file and use its contents for a SModelS run. Supply the crash file simply via ‘– filename myfile.crash’ -v VERBOSE, --verbose VERBOSE sets the verbosity level (debug, info, warning, error). Default value is info. -T TIMEOUT, --timeout TIMEOUT define a limit on the running time (in secs).If not set, run without a time limit. If a directory is given as input, the timeout will be applied for each individual file.
A typical usage example is:
runSModelS.py -f lightSquarks.slha -p parameters.ini -o ./ -v warning
The resulting output will be generated in the current folder, according to the printer options set in the parameters file.
The Parameters File¶
The basic options and parameters used by runSModelS.py are defined in the parameters file.
An example parameter file, including all available parameters together
with a short description, is stored in parameters.ini
.
If no parameter file is specified, the default parameters stored in
/etc/parameters_default.ini
are used.
Below we give more detailed information about each entry in the parameters file.
- path: relevant folder paths
- databasePath: the absolute (or relative) path to the database. The user can supply either the directory name of the database, or the path to the pickle file.
- options: main options for turning SModelS features on or off
- inputType (SLHA/LHE): determines the type of input file (see Basic Input). Must be SLHA for SLHA input files or LHE for LHE input files.
- checkInput (True/False): if True, runSModelS.py will run the file check tool on the input file and verify if the input contains all the necessary information.
- doInvisible (True/False): turns invisible compression on or off during the decomposition.
- doCompress (True/False): turns mass compression on or off during the decomposition.
- computeStatistics (True/False): turns the likelihood and \(\chi^2\) computation on or off (see likelihood calculation). If True, the likelihood and \(\chi^2\) values are computed for the EM-type results.
- testCoverage (True/False): set to True to run the coverage tool.
- parameters: basic parameter values for running SModelS
- sigmacut (float): minimum value for an element weight (in fb). Elements with a weight below sigmacut are neglected during the decomposition of SLHA files (see Minimum Decomposition Weight). The default value is 0.03 fb. Note that, depending on the input model, the running time may increase considerably if sigmacut is too low, while too large values might eliminate relevant elements.
- minmassgap (float): maximum value of the mass difference (in GeV) for perfoming mass compression. Only used if doCompress = True
- maxcond (float): maximum allowed value (in the [0,1] interval) for the violation of upper limit conditions. A zero value means the conditions are strictly enforced, while 1 means the conditions are never enforced. Only relevant for printing the output summary.
- ncpus (int): number of CPUs. When processing multiple SLHA/LHE files, SModelS can run in a parallelized fashion, splitting up the input files in equal chunks. ncpus = -1 uses the total number of CPU cores of the machine.
- database: allows for selection of a subset of experimental results from the database
- analyses (list of results): set to all to use all available results. If a list of experimental analyses is given, only these will be used. For instance, setting analyses = CMS-PAS-SUS-13-008,ATLAS-CONF-2013-024 will only use the experimental results from CMS-PAS-SUS-13-008 and ATLAS-CONF-2013-024.
- txnames (list of topologies): set to all to use all available simplified model topologies. The topologies are labeled according to the txname convention. If a list of txnames are given, only the corresponding topologies will be considered. For instance, setting txnames = T2 will only consider experimental results for \(pp \to \tilde{q} + \tilde{q} \to (jet+\tilde{\chi}_1^0) + (jet+\tilde{\chi}_1^0)\) and the output will only contain constraints for this topology. A list of all topologies and their corresponding txnames can be found here
- dataselector (list of datasets): set to all to use all available data sets. If dataselector = upperLimit (efficiencyMap), only UL-type results (EM-type results) will be used. Furthermore, if a list of signal regions (data sets) is given, only the experimental results containing these datasets will be used. For instance, if dataselector = SRA mCT150,SRA mCT200, only these signal regions will be used.
- printer: main options for the output format
- outputType (list of outputs): use to list all the output formats to be generated. Available output formats are: summary, stdout, log, python, xml.
- stdout-printer: options for the stdout or log printer
- printDatabase (True/False): set to True to print the list of selected experimental results to stdout.
- addAnaInfo (True/False): set to True to include detailed information about the txnames tested by each experimental result. Only used if printDatabase=True.
- printDecomp (True/False): set to True to print basic information from the decomposition (topologies, total weights, ...).
- addElementInfo (True/False): set to True to include detailed information about the elements generated by the decomposition. Only used if printDecomp=True.
- printExtendedResults (True/False): set to True to print extended information about the theory predictions, including the PIDs of the particles contributing to the predicted cross section, their masses and the expected upper limit (if available).
- addCoverageID (True/False): set to True to print the list of element IDs contributing to each missing topology (see coverage). Only used if testCoverage = True. This option should be used along with addElementInfo = True so the user can precisely identify which elements were classified as missing.
- summary-printer: options for the summary printer
- expandedSummary (True/False): set True to include in the summary output all applicable experimental results, False for only the strongest one.
- python-printer: options for the Python printer
- addElementList (True/False): set True to include in the Python output all information about all elements generated in the decomposition. If set to True the output file can be quite large.
- xml-printer: options for the xml printer
- addElementList (True/False): set True to include in the xml output all information about all elements generated in the decomposition. If set to True the output file can be quite large.
The Output¶
The results of runSModelS.py are printed to the format(s) specified by the outputType in the parameters file. The following formats are available:
- a human-readable screen output (stdout) or log output. These are intended to provide detailed information about the database, the decomposition, the theory predictions and the missing topologies. The output complexity can be controlled through several options in the parameters file. Due to its size, this output is not suitable for storing the results from a large scan, being more appropriate for a single file input.
- a human-readable text file output containing a summary of the output. This format contains the main SModelS results: the theory predictions and the missing topologies. It can be used for a large scan, since the output can be made quite compact, using the options in the parameters file.
- a python dictionary printed to a file containing information about the decomposition, the theory predictions and the missing topologies. The output can be significantly long, if all options in the parameters file are set to True. However this output can be easily imported to a Python enviroment, making it easy to access the desired information. For users familiar with the Python language this is the recommended format.
- a xml file containing information about the decomposition, the theory predictions and the missing topologies. The output can be significantly long, if all options are set to True. Due to its broad usage, the xml output can be easily converted to the user’s preferred format.
A detailed explanation of the information contained in each type of output is given in SModels Output.
Example.py¶
Although runSModelS.py provides the main SModelS features with a command line interface,
users more familiar with Python and the SModelS language may prefer to write their own main program.
A simple example code for this purpose is provided in examples/Example.py
.
Below we go step-by-step through this example code:
- Import the SModelS methods. If the example code file is not located in the smodels installation folder, simply add “sys.path.append(<smodels installation path>)” before importing smodels
from smodels.theory import slhaDecomposer
from smodels.theory import lheDecomposer
from smodels.tools.physicsUnits import fb, GeV
from smodels.theory.theoryPrediction import theoryPredictionsFor
from smodels.experiment.databaseObj import Database
- Set the path to the database folder. Specify where the SModelS database has been installed and load the database.
# Set the path to the database folder
database = Database("./smodels-database/")
- Path to the input file. Specify the location of the input file. It must be a SLHA or LHE file (see Basic Input).
slhafile = 'inputFiles/slha/lightEWinos.slha'
- Set main options for decomposition. Specify the values of sigmacut and minmassgap:
sigmacut = 0.3 * fb
mingap = 5. * GeV
- Decompose model. Depending on the type of input format, choose either the slhaDecomposer.decompose or lheDecomposer.decompose method. The doCompress and doInvisible options turn the mass compression and invisible compression on/off.
toplist = slhaDecomposer.decompose(slhafile, sigmacut, doCompress=True, doInvisible=True, minmassgap=mingap)
# toplist = lheDecomposer.decompose(lhefile, doCompress=True,doInvisible=True, minmassgap=mingap)
- Access basic information from decomposition, using the topology list and topology objects:
print "\n Decomposition Results: "
print "\t Total number of topologies: %i " %len(toplist)
nel = sum([len(top.elementList) for top in toplist])
print "\t Total number of elements = %i " %nel
#Print information about the m-th topology:
m = 3
top = toplist[m]
print "\t\t %i-th topology = " %m,top,"with total cross section =",top.getTotalWeight()
#Print information about the n-th element in the m-th topology:
n = 0
el = top.elementList[n]
print "\t\t %i-th element from %i-th topology = " %(n,m),el,
print "\n\t\t\twith cross section =",el.weight,"\n\t\t\tand masses = ",el.getMasses()
output:
Decomposition Results:
Total number of topologies: 23
Total number of elements = 586
3-th topology = [1][1] with total cross-section = ['8.00E+00 [TeV]:3.64E-04 [pb]']
0-th element from 3-th topology = [[[W+]],[[Z]]]
with cross-section = ['8.00E+00 [TeV]:3.64E-04 [pb]']
and masses = [[2.93E+02 [GeV], 6.81E+01 [GeV]], [2.66E+02 [GeV], 6.81E+01 [GeV]]]
- Load the experimental results to be used to constrain the input model. Here, all results are used:
listOfExpRes = database.getExpResults()
Alternatively, the getExpResults method can take as arguments specific results to be loaded.
- Print basic information about the results loaded. Below we show how to count the number of UL-type results and EM-type results loaded:
nUL, nEM = 0, 0
for exp in listOfExpRes:
expType = exp.getValuesFor('dataType')[0]
if expType == 'upperLimit':
nUL += 1
elif expType == 'efficiencyMap':
nEM += 1
print "\n Loaded Database with %i UL results and %i EM results " %(nUL,nEM)
output:
Loaded Database with 34 UL results and 30 EM results
- Compute the theory predictions for each experimental result. The output is a list of theory prediction objects (for each experimental result):
for expResult in listOfExpRes:
predictions = theoryPredictionsFor(expResult, toplist)
- Print the results. For each experimental result, loop over the corresponding theory predictions and print the relevant information:
for theoryPrediction in predictions:
dataset = theoryPrediction.dataset
datasetID = dataset.dataInfo.dataId
mass = theoryPrediction.mass
txnames = [str(txname) for txname in theoryPrediction.txnames]
PIDs = theoryPrediction.PIDs
print "------------------------"
print "Dataset = ",datasetID #Analysis name
print "TxNames = ",txnames
print "Prediction Mass = ",mass #Value for average cluster mass (average mass of the elements in cluster)
print "Prediction PIDs = ",PIDs #Value for average cluster mass (average mass of the elements in cluster)
print "Theory Prediction = ",theoryPrediction.xsection #Signal cross section
print "Condition Violation = ",theoryPrediction.conditions #Condition violation values
output:
ATLAS-CONF-2013-024
------------------------
Dataset = SR1: MET > 200
TxNames = ['T1bbbb', 'T1bbqq', 'T1bbtt', 'T1tttt']
Prediction Mass = [[5.77E+02 [GeV], 6.81E+01 [GeV]], [5.77E+02 [GeV], 6.81E+01 [GeV]]]
Prediction PIDs = [[[1000021, 1000022], [1000021, 1000022]]]
Theory Prediction = 8.00E+00 [TeV]:1.32E-04 [pb]
Condition Violation = None
- Get the corresponding upper limit. This value can be compared to the theory prediction to decide whether a model is excluded or not:
ul = expResult.getUpperLimitFor(txname=txnames[0],mass=mass,dataID=datasetID)
print "UL for theory prediction = ",ul
output:
Theory Prediction UL = 4.90E-01 [fb]
- Compute the r-value, i.e. the ratio theory prediction/upper limit. A value of \(r \geq 1\) means that an experimental result excludes the input model. Also determine the most constraining result:
r = theoryPrediction.xsection.value/ul
print "r = ",r
if r > rmax:
rmax = r
bestResult = expResult.globalInfo.id
output:
r = 2.69E-01
- Print the most constraining experimental result. Using the largest r-value, determine if the model has been excluded or not by the selected experimental results:
print "\nThe largest r-value (theory/upper limit ratio) is ",rmax
if rmax > 1.:
print "(The input model is likely excluded by %s)" %bestResult
else:
print "(The input model is not excluded by the simplified model results)"
output:
The largest r-value (theory/upper limit ratio) is 1.20E+00
(The input model is likely excluded by CMS-SUS-13-006)
It is worth noting that SModelS does not include any statistical treatment for the results, for instance, correction factors like the “look elsewhere effect”. Due to this, the results are claimed to be “likely excluded” in the output.
- Notes:
- For an SLHA input file, the decays of final states (or Z2-even particles such as the Higgs, W,...) are always ignored during the decomposition. Furthermore, if there are two cross sections at different calculation order (say LO and NLO) for the same process, only the highest order is used.
- The list of elements can be extremely long. Try setting addElementInfo = False and/or printDecomp = False to obtain a smaller output.
- A comment of caution is in order regarding naively using the highest \(r\)-value reported by SModelS, as this does not necessarily come from the most sensitive analysis. For a rigorous statistical interpretation, one should use the \(r\)-value of the result with the highest expected \(r\) (\(r_{exp}\)). Unfortunately, for UL-type results, the expected limits are often not available; \(r_{exp}\) is then reported as N/A in the SModelS output.
[1] | We note that SLHA files including decay tables and cross sections, together with the corresponding particles.py, can conveniently be generated via the SModelS-micrOMEGAS interface, see arXiv:1606.03834 |