Running SModelS

For the first-time user, SModelS ships with a command-line tool runSModelS.py, which takes an SLHA or LHE file as input (see Basic Input), and reports on the SMS decomposition and theory predictions in a simple output text file.

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, analysis database and computation of theory predictions.

The commandline tool (runSModelS.py) and the example Python code (Example.py) are described below.

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 and printing the output, evaluating the theory predictions and comparing them to the experimental limits available in the database, determining missing topologies and printing a summary text file.

These settings may be changed from their default values using the parameter file.

usage:
runSModelS.py [-h] -f FILENAME [-p PARAMETERFILE] [-o OUTPUTFILE]
optional arguments:
-h, --help show this help message and exit
-f FILENAME, --filename FILENAME
 name of SLHA or LHE input file, necessary input
-p PARAMETERFILE, --parameterfile PARAMETERFILE
 name of parameter file, optional argument, if not set, use all parameters from etc/parameters_default.ini.
-o OUTPUTFILE, --outputfile OUTPUTFILE
 name of output file, optional argument, default is: ./summary.txt

The Parameters File

The basic options and parameters used by runSModelS.py are defined in the parameter 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 (path to database): the absolute (or relative) path to the SModelS database

default values:

[path]
databasePath = ../smodels-database/
  • options: main options for turning SModelS features on and off

default values:

[options]
inputType = SLHA 
checkInput = True
doInvisible = True
doCompress = True
findMissingTopos = True
  • parameters: basic parameter values for running SModelS
    • sigmacut (float): minimum value for the element weight (in fb). During decomposition all elements with weights below sigmacut are neglected. Too Small values of sigmacut (see Minimum Decomposition Weight) will result in longer running time, while too large values might eliminate relevant elements.
    • minmassgap (float): maximum mass difference value (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 analysis 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

default values:

[parameters]
sigmacut = 0.03 
minmassgap = 5.
maxcond = 0.2
  • database: select a subset of the available database analyses
    • analyses (list of analyses name): set to all to use all available analyses. If a list of analyses names are given, only these analyses will be applied. For instance, setting analyses = CMS-PAS-SUS-13-008, ATLAS-CONF-2013-024 will only use the analyses from CMS-PAS-SUS-13-008 and ATLAS-CONF-2013-024.
    • txnames (list of constraints): set to all to use all available analyses constraints. If a list of constraints are given (using the Tx name shorthand, only these constraints will be considered. For instance, setting txnames = T2 will only consider the analyses containing upper limits for \([[[jet]],[[jet]]]\). A list of all constraints and their Tx names can be found here)

default values:

[database]
analyses = all
txnames = all
  • stdout: basic options for the screen output
    • printDecomp (True/False): set to True to print basic information from the decomposition (topologies, total weights, ...)
    • addElmentInfo (True/False): set to True to include detailed information about the elements generated by the decomposition Only used if printDecomp=True.
    • printAnalyses (True/False): set to True to print basic information about the analyses being used (list of analysis names, luminosities,...)
    • addAnaInfo (True/False): set to True to include detailed information about the elements tested by each analysis (elements appearing in the analysis constraint). Only used if printAnalyses=True.
    • printResults (True/False): set to True to print information about the theory predictions computed and the respective analysis upper limits

default values:

[stdout]
printDecomp = True
addElmentInfo = False
printAnalyses = False
addAnaInfo = False
printResults = True
  • file: basic options for the file output
    • expandedSummary (True/False): set to True to print to file all applicable analyses. Set to False to print only the most constraining analysis.
    • addConstraintInfo (True/False): set to True to include the analysis constraint in bracket notation for each analysis printed to file.

default values:

[file]
expandedSummary = True
addConstraintInfo = True

The Output

The results of runSModelS.py are printed both to the screen and to the output (summary) file. If no output file is specified when calling runSModelS.py, the file output will be printed to ./summary.txt. Below we explain in detail the information contained in the screen output and the output file.

Screen Output

If all the options in stdout (printDecomp, addElmentInfo, printAnalyses, addAnaInfo and printResults) are set to True (see parameter file), the screen output contains the following information:

===================================================== 
Topology:
Number of vertices: [3, 3] 
Number of vertex parts: [[1, 1, 0], [1, 1, 0]]
Total Global topology weight :
Sqrts: 8.00E+00 [TeV], Weight:1.62E-02 [pb]

Total Number of Elements: 30
		 .........................................................................
		 Element: 
		 Particles in element: [[['jet'], ['W-']], [['jet'], ['W-']]]
		 The element masses are 
		 Branch 0: [9.94E+02 [GeV], 2.69E+02 [GeV], 1.29E+02 [GeV]]
		 Branch 1: [9.94E+02 [GeV], 2.69E+02 [GeV], 1.29E+02 [GeV]]
		 The element weights are: 
 		 Sqrts: 8.00E+00 [TeV], Weight:3.78E-04 [pb]
========================================================
Analysis Name: ATLAS-SUSY-2013-05
Tx Label: T2bb
Analysis Sqrts: 8.00E+00 [TeV]
	 -----------------------------
	 Elements tested by analysis:
	    [[['b']], [['b']]]
---------------Analysis Label = CMS-PAS-SUS-13-019:T2
Analysis sqrts: 8.00E+00 [TeV]
Masses in branch 0: [9.91E+02 [GeV], 1.29E+02 [GeV]]
Masses in branch 1: [9.91E+02 [GeV], 1.29E+02 [GeV]]
Theory prediction: 1.77E-03 [pb]
Theory conditions:[None]
Experimental limit: 3.76E-03 [pb]
  • possible (mostly harmless) warnings [†]
10:36:46.712 WARNING  __main__:46  Removing old output file in summary.txt
10:36:46.765 INFO     smodels.theory.slhaDecomposer:132 Ignoring higgs decays
10:36:46.792 INFO     smodels.theory.crossSection:512 Ignoring 76 lower order cross-sections

Summary File Output

If both expandedSummary and addConstraintInfo are set to True (see parameter file), the file output contains the following information:

  • a status flag for the input file and the decomposition indicating possible problems. These flags should be consulted in case of unexpected/missing results:
  • the version of the database used to obtain the results:
  • the list of analyses which constrain the input model. For each analysis, the analysis name, the value of the analysis center-of-mass energy (sqrts), the amount of condition violation, the theory prediction value (value for the relevant signal cross-section), the experimental upper limit and the ratio (r) of the signal cross-section and the upper limit (\(r = theory\, prediction/upper\, limit\)) are printed. A value of \(r\ge 1\) indicates that the model is likely excluded by the corresponding analysis.
  • The last line of this block gives the maximum value of r, \(R = max(r)\).
  • if findMissingTopos = True, a list of the missing topologies and their cross sections at the given value of sqrts is also included. This list represents the elements or sum of elements (shown using the bracket notation) with the highest weights (\(\sigma \times BR\)) which are not tested by any analysis:

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. Import the methods to be used later. If the file is not located in the smodels installation folder simply add “sys.path.append(<smodels installation path>)” before importing smodels
#Import basic functions (this file must be run under the installation folder
from __future__ import print_function
import sys
from smodels.theory import slhaDecomposer
from smodels.theory import lheDecomposer
from smodels.tools.physicsUnits import fb, GeV
from smodels.experiment import smsAnalysisFactory
from smodels.theory.theoryPrediction import theoryPredictionFor
from smodels.experiment import smsHelpers
  • Set the address to the dabase. Specify where the SModelS database has been installed
#Set the address of the database folder
smsHelpers.base="/home/lessa/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/lightSquarks.slha'
    sigmacut = 0.03 * fb
    mingap = 5. * GeV
    smstoplist = slhaDecomposer.decompose(slhafile, sigmacut, doCompress=True,doInvisible=True, minmassgap=mingap)
  • Print the decomposition output. Set outputLevel = 0 (no output), 1 (basic output) or 2 (extended output)
    smstoplist.printout(outputLevel=1)
  • Load the the analyses database. Load the experimental analyses and store the list of analyses
    listofanalyses = smsAnalysisFactory.load()
    analysesPredictions = [theoryPredictionFor(analysis, smstoplist) for analysis in listofanalyses]
  • Print the output. Loop over all analyses and results and print the theory predictions information
    for analysisPred in analysesPredictions:
        if not analysisPred: continue  #Skip non-applicable analyses
        #If the analysis prediction contains more than one theory prediction (cluster), loop over predictions:        
        for theoryPrediction in analysisPred:
            print("------------------------")
            print("Analysis name = ",theoryPrediction.analysis.label)   #Analysis name
            print("Prediction Mass = ",theoryPrediction.mass)    #Value for average cluster mass (average mass of the elements in cluster)
            print("Signal Cross-Section = ",theoryPrediction.value)   #Value for the cluster signal cross-section
            print("Condition Violation = ",theoryPrediction.conditions)  #Condition violation values
  • Get analysis upper limit. For each anlysis and theory prediction, obtain the experimental upper limit. This value can be compared to the theory prediction value to decide if a model is excluded or not.
            print("Analysis UL = ",theoryPrediction.analysis.getUpperLimitFor(theoryPrediction.mass)) 
[*]For an SLHA input file, the decay 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 addElmentInfo = False and/or printDecomp = False to obtain a smaller output.

Table Of Contents

Previous topic

Installation and Deployment

Next topic

More Examples

This Page