SModelS User Manual¶
These pages constitute the SModelS manual.
SModelS is an automatic, public tool for interpreting simplified-model results from the LHC. It is based on a general procedure to decompose Beyond the Standard Model (BSM) collider signatures presenting a Z2 symmetry into Simplified Model Spectrum (SMS) topologies. Our method provides a way to cast BSM predictions for the LHC in a model independent framework, which can be directly confronted with the relevant experimental constraints. Our concrete implementation currently focusses on supersymmetry searches with missing energy, for which a large variety of SMS results from ATLAS and CMS are available. The main ingredients are
- the decomposition of the BSM spectrum into SMS topologies
- a database of experimental SMS results
- the interface between decomposition and results database (to check limits)
as illustrated in the graphics below.

Contents¶
What’s New¶
Since the publication of SModelS v1.0 in December 2014, the code base has undergone significant structural changes. The major novelties of this release are as follows:
New in Version 1.1.3:¶
- Support for covariance matrices and combination of signal regions (see combineSR in parameters file)
- New plotting tool added to smodelsTools (see Interactive Plots Maker)
- Path to particles.py can now be specified in parameters.ini file (see model in parameters file)
- Wildcards allowed when selecting analyses, datasets, txnames (see analyses, txnames and dataselector in parameters file)
- Option to show individual contribution from topologies to total theory prediction (see addTxWeights in parameters file)
- URLs are allowed as database paths (see path in parameters file)
- Python default changed from python2 to python3
- Fixed lastUpdate bug, now giving correct date
- Changes in pickling (e.g. subpickling, removing redundant zeroes)
- Added fixpermissions to smodelsTools.py, for system-wide installs (see Files Permissions Fixer)
- Fixed small issue with pair production of even particles
- Moved the code documentation to the manual
- Added option for installing within the source folder
New in Version 1.1.2:¶
- Database update only, the code is the same as v1.1.1
New in Version 1.1.1:¶
- C++ Interface
- Support for pythia8 (see Cross Section Calculator)
- improved binary database
- automated SLHA and LHE file detection
- Fix and improvements for missing topologies
- Added SLHA-type output
- Small improvements in interpolation and clustering
New in Version 1.1.0:¶
- the inclusion of efficiency maps (see EM-type results)
- a new and more flexible database format (see Database structure)
- inclusion of likelihood and \(\chi^2\) calculation for EM-type results (see likelihood calculation)
- extended information on the topology coverage
- inclusion of a database broswer tool for easy access to the information stored in the database (see database browser)
- the database now supports also a more efficient binary format
- performance improvement for the decomposition of the input model
- inclusion of new simplified results to the database (including a few 13 TeV results)
- Fastlim efficiency maps can now also be used in SModelS
Installation and Deployment¶
Standard Installation¶
SModelS is a Python library that requires Python version 2.6 or later, including version 3, which is the default. It depends on the following external Python libraries:
- unum>=4.0.0
- numpy>=1.13.0
- argparse
- requests>=2.0.0
- docutils>=0.3
- scipy>=1.0.0
- pyslha>=3.1.0
In addition, the cross section computer provided by smodelsTools.py requires:
- Pythia 8.2 (requires a C++ compiler) or Pythia 6.4.27 (requires gfortran)
- NLL-fast 1.2 (7 TeV), 2.1 (8 TeV), and 3.1 (13 TeV) (requires a fortran compiler)
These tools need not be installed separately, as the SModelS build system takes care of that. The current default is that both Pythia6 and Pythia8 are installed together with NLLfast. Finally, the database browser provided by smodelsTools.py requires IPython, while the interactive plotter requires plotly and pandas.
Installation Methods¶
The first installation method installs SModelS in the source directory. After downloading the source from the SModelS releases page and extracting it, run:
make smodelsin the top-level directory. The installation will remove redundant folders, install the required dependencies (using pip install) and compile Pythia and NLL-fast. If the cross section computer is not needed, one can replace smodels with smodels_noexternaltools in the above command. In case the Python libraries can not be successfully installed, the user can install them separately using his/her preferred method. Pythia and NLL-fast can also be compiled separately running make externaltools.
If Python’s setuptools is installed in your machine, SModelS and its dependencies can also be installed without the use of pip. After downloading the source from the SModelS releases page and extracting it, run:
setup.py installwithin the main smodels directory. If the python libraries are installed in a system folder (as is the default behavior), it will be necessary to run the install command with superuser privilege. Alternatively, one can run setup.py with the “–user” flag:
setup.py install --userIf setuptools is not installed, you can try to install the external libraries manually and then rerun setup.py. For Ubuntu, SL6 machines and other platforms, a recipe is given below.
Note that this installation method will install smodels into the default system or user directory (e.g. ~/.local/lib/python3/site-packages/). Depending on your platform, the environment variables $PATH, $PYTHONPATH, $LD_LIBRARY_PATH (or $DYLD_LIBRARY_PATH) might have to be set appropriately.
Finally, if pip3 (or pip) is installed in your machine, it is also possible to install SModelS directly without the need for downloading the source code:
pip3 install smodelsin case of system-wide installs or :
pip3 install --user smodelsfor user-specific installations.
Note that this installation method will install smodels into the default system or user directory (e.g. ~/.local/lib/python3/site-packages/). Depending on your platform, the environment variables $PATH, $PYTHONPATH, $LD_LIBRARY_PATH (or $DYLD_LIBRARY_PATH) might have to be set appropriately. Be aware that the example files and the parameters file file discussed in the manual will also be located in your default system or user directory. Furthermore the database folder is not included (see database installation below).
There is also a diagnostic tool available:
smodelsTools.py toolbox
should list and check all internal tools (Pythia and NLL-fast) and external (numpy, scipy, unum, … ) dependencies.
In case everything fails, please contact smodels-users@lists.oeaw.ac.at
Installing the SModelS Database¶
The installation methods explained above (except for pip install) also install SModelS’ database of experimental results in the smodels-database subdirectory. The first time SModelS is run, a binary file will be built using this text database folder, which can then be used in all subsequent runs. However, from v1.1.3 onwards it is recommended to provide the URL of the official database as the database path when running SModelS (see path in parameters file). In this case the corresponding database version binary file will be automatically downloaded and used. The available database URLs can be found in the SModelS Database releases page .
The complete list of analyses and results included in the database can be consulted at http://smodels.hephy.at/wiki/ListOfAnalyses. We note that all the results in the official database release have been carefully validated and the validation material can be found at http://smodels.hephy.at/wiki/Validation.
The database can conveniently be updated independently from SModelS code updates. It suffices to unpack any new database tarball and replace the database directory or provide the path to the new folder, binary or URL address. In the same fashion, one can easily add additional results as explained below.
Adding FastLim data¶
The official SModelS database can be augmented with data from the fastlim results. For using SModelS with the text database, a tarball with the properly converted fastlim-1.0 efficiency maps can be found in the smodels-database folder. The tarball then needs to be exploded in the top level directory of the database:
cd <smodels-database folder>
tar -xzvf smodels-v1.1-fastlim-1.0.tgz
rm smodels-v1.1-fastlim-1.0.tgz
Once the fastlim folders have been added to the database, SModelS auto-detects fastlim results and issues an acknowledgement.
As discussed above, from v1.1.3 onwards it is also possible to directly download the database binary file using the URLs provided in the SModelS Database releases page . Separate URLs are provided for the database including the Fastlim maps, so the user can choose which database to use.
When using the Fastlim results, please properly cite the fastlim paper; for convenience, a bibtex file is provided in the smodels-fastlim tarball.
Finally we point out that when converting the Fastlim efficiency maps efficiencies with a relative statistical uncertainty greater than 25% were set to zero. Also, per default we discard zeroes-only results.
Adding one’s own results¶
The Database of Experimental Results is organized as files in an ordinary directory hierarchy. Therefore, adding additional experimental results is a matter of copying and editing text files. Once the new folders and files have been added following the database structure format, SModelS automatically rebuilds the binary (Pickle) database file. The added results will then be available for using with the the SModelS tools.
System-specific Installation Instructions¶
Installation on Ubuntu >= 16.04¶
Installation on Ubuntu machines should be straightforward with superuser privileges (if you do not have superuser privileges see instructions below):
- sudo apt install gfortran python-setuptools python-scipy python-numpy python-docutils python-argparse
- setup.py install
Note that the last command can be run as superuser, or with the “–user” flag.
Installation on SL7¶
Installation on an SL7 or CentOS7 is straightforward:
- yum install gcc-c++ scipy numpy
- pip install unum pyslha argparse
Installation on SL6¶
Installation on an SL6 (Scientific Linux 6 or Scientific Linux CERN 6) machine is tricky, because SModelS requires a more recent version of scipy than is provided by SL6. We succeeded to install SModelS on SL6 by doing:
- yum install gcc-c++ libstdc++-devel libevent-devel python-devel lapack lapack-devel blas blas-devel libgfortran python-distutils-extra
followed by:
- pip install nose unum argparse numpy pyslha scipy
Note, that these steps can safely be done within a Python virtualenv
.
Pip can also be called with the “–user” flag.
Installation on SL5 and similar distributions¶
In some distributions like SL5, the Python default version may be smaller than
2.6. In these cases, virtualenv
has to be set up for a Python version >= 2.6. E.g. for Python 2.6, do virtualenv --python=python2.6 <envname>
, and modify by hand the first line in the executable from #!/usr/bin/env python3
to #!/usr/bin/env python2.6
.
Then perform the steps listed under Installation on SL6
.
Installation on other platforms or without superuser privileges using Anaconda¶
Another easy and platform independent way of installing SModelS without superuser priviledges is via Anaconda (https://www.continuum.io/downloads). Anaconda provides a local installation of pip as well as several additional python packages. Here we assume a version of gfortran is already installed in your system.
download and install Anaconda for Python 3.6 (https://www.continuum.io/downloads)
make sure Anaconda’s bin and lib folders are added to your system and Python paths
PATH="<anaconda-folder>/bin:$PATH" PYTHONPATH=$PYTHONPATH:"<anaconda-folder>/lib/python3.6/site-packages"
and then install SModelS as a user:
setup.py install --user
In order to make sure all libraries have been correctly installed, you can run:
smodelsTools.py toolBox
Installation of the C++ interface¶
SModelS v1.1.1 comes with a simple C++ interface, see the cpp directory. Obviously, a C++ compiler is need, alongside with the python developers (header) files (libpython-dev on ubuntu, python-devel on rpm-based distros).
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 non-MSSM (incl. non-SUSY) input models the user needs to write their own 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] [-C] [-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 smodels/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 -C, --colors colored output -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 inputFiles/slha/simplyGluino.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
smodels/etc/parameters_default.ini
are used.
Below we give more detailed information about each entry in the parameters file.
- options: main options for turning SModelS features on or off
- 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.
- combineSRs (True/False): set to True to use, whenever available, covariance matrices to combine signal regions. NB this might take a few secs per point. Set to False to use only the most sensitive signal region (faster!). Available v1.1.3 onwards.
- particles: defines the particle content of the BSM model
- model: pathname to the Python file that defines the particle content of the BSM model, given either in Unix file notation (“/path/to/model.py”) or as Python module path (“path.to.model”). Defaults to share.models.mssm which is a standard MSSM. See smodels/share/models folder for more examples. Directory name can be omitted; in that case, the current working directory as well as smodels/share/models are searched for.
- 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 parallelizes to as many processes as number of CPU cores of the machine. Default value is 1. Warning: python already parallelizes many tasks internally.
- database: allows for selection of a subset of experimental results from the database
- path: 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. Since v1.1.3, also http addresses may be given, e.g. http://smodels.hephy.at/database/official113. See the github database release page for a list of public database versions.
- 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. Wildcards (, ?, [<list-of-or’ed-letters>]) are expanded in the same way the shell does wildcard expansion for file names. So analyses = CMS leads to evaluation of results from the CMS-experiment only, for example. SUS selects everything containining SUS, no matter if from CMS or ATLAS. Furthermore selection of analyses can be confined on their centre-of-mass energy with a suffix beginning with a colon and an energy string in unum-style, like :13*TeV. Note that the asterisk behind the colon is not a wildcard. :13, :13TeV and :13 TeV are also understood but discouraged.
- 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 Wildcards (*, ?, [<list-of-or’ed-letters>]) are expanded in the same way the shell does wildcard expansion for file names. So, for example, txnames = T[12]*bb* picks all txnames beginning with T1 or T2 and containg bb as of the time of writing were: T1bbbb, T1bbbt, T1bbqq, T1bbtt, T2bb, T2bbWW, T2bbWWoff
- 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. Wildcards (*, ?, [<list-of-or’ed-letters>]) are expanded in the same way the shell does wildcard expansion for file names. Wildcard examples are given above.
- dataTypes dataType of the analysis (all, efficiencyMap or upperLimit). Can be wildcarded with usual shell wildcards: * ? [<list-of-or’ed-letters>]. Wildcard examples are given above.
- 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, slha.
- 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.
- addTxWeights (True/False): set True to print the contribution from individual topologies to each theory prediction. Available v1.1.3 onwards.
- 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.
- addTxWeights (True/False): set True to print the contribution from individual topologies to each theory prediction. Available v1.1.3 onwards.
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 SLHA file containing information about the theory predictions and the missing topologies. The output follows a SLHA-type format and contains a summary of the most constraining results and the missed topologies.
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 modules and 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. Set SModelS verbosity level.
from imp import reload
from smodels.tools import runtime
from smodels import particlesLoader
from smodels.theory import slhaDecomposer,lheDecomposer
from smodels.tools.physicsUnits import fb, GeV, TeV
from smodels.theory.theoryPrediction import theoryPredictionsFor
from smodels.experiment.databaseObj import Database
from smodels.tools import coverage
from smodels.tools.smodelsLogging import setLogLevel
setLogLevel("info")
- Set the path to the database URL. Specify which database to use. It can be the path to the smodels-database folder, the path to a pickle file or (starting with v1.1.3) a URL path.
# Set the path to the database
database = Database("http://smodels.hephy.at/database/official113")
- Define the input model. By default SModelS assumes the MSSM particle content. For using SModelS with a different particle content, the user must define the new particle content and set modelFile to the path of the model file (see particles:model in Parameter File).
runtime.modelFile = 'smodels.share.models.mssm'
reload(particlesLoader) #Make sure all the model particles are up-to-date
- 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'
lhefile = 'inputFiles/lhe/gluino_squarks.lhe'
- 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.
slhaInput = True
if slhaInput:
toplist = slhaDecomposer.decompose(slhafile, sigmacut, doCompress=True, doInvisible=True, minmassgap=mingap)
else:
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, end="" )
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] (1000025, 1000037)']
0-th element from 3-th topology = [[[W+]],[[Z]]]
with cross section = ['8.00E+00 [TeV]:3.64E-04 [pb] (1000025, 1000037)']
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 40 UL results and 18 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-007
------------------------
Dataset = None
TxNames = ['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]:6.70E-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:
print ( "UL for theory prediction = ",theoryPrediction.upperLimit )
output:
UL for theory prediction = 3.69E+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. For EM-type results also compute the \(\chi^2\) and likelihood. Determine the most constraining result:
print ( "r = ",r )
#Compute likelihhod and chi^2 for EM-type results:
if dataset.dataInfo.dataType == 'efficiencyMap':
theoryPrediction.computeStatistics()
print ( 'Chi2, likelihood=', theoryPrediction.chi2, theoryPrediction.likelihood )
if r > rmax:
rmax = r
bestResult = expResult.globalInfo.id
output:
r = 1.82E-02
- 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:
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)
- Identify missing topologies. Using the output from decomposition, identify the missing topologies and print some basic information:
print ( "Total cross section where we are outside the mass grid (fb): %10.3E\n" %(uncovered.getOutOfGridXsec()) )
print ( "Total cross section in long cascade decays (fb): %10.3E\n" %(uncovered.getLongCascadeXsec()) )
print ( "Total cross section in decays with asymmetric branches (fb): %10.3E\n" %(uncovered.getAsymmetricXsec()) )
#Print some of the missing topologies:
print ( 'Missing topologies (up to 3):' )
for topo in uncovered.missingTopos.topos[:3]:
print ( 'Topology:',topo.topo )
print ( 'Contributing elements (up to 2):' )
for el in topo.contributingElements[:2]:
print ( el,'cross-section (fb):', el.missingX )
#Print elements with long cascade decay:
print ( '\nElements outside the grid (up to 2):' )
for topo in uncovered.outsideGrid.topos[:2]:
print ( 'Topology:',topo.topo )
print ( 'Contributing elements (up to 4):' )
for el in topo.contributingElements[:4]:
print ( el,'cross-section (fb):', el.missingX )
print ( '\tmass:',el.getMasses() )
output:
Total missing topology cross section (fb): 2.706E+03
Total cross section where we are outside the mass grid (fb): 5.214E+01
Total cross section in long cascade decays (fb): 3.011E+02
Total cross section in decays with asymmetric branches (fb): 2.368E+03
Missing topologies (up to 3):
Topology: [[],[]]
Contributing elements (up to 2):
[[],[]] cross-section (fb): 0.450694497
Elements outside the grid (up to 2):
Topology: [[[W]],[[Z]]]
Contributing elements (up to 4):
[[[W+]],[[Z]]] cross-section (fb): 0.363795519075
mass: [[2.93E+02 [GeV], 6.81E+01 [GeV]], [2.66E+02 [GeV], 6.81E+01 [GeV]]]
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 |
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) and NLLfast,
- 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 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.
- The cross section calculation is implemented by the computeXSec function
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
- 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,
- the lightest Z2-odd state (the LSP in supersymmetric models) is neutral,
- there are no stable charged particles nor displaced vertices (no non-prompt visible decays), as currently all the analyses considered by SModelS require a prompt MET signature.
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.
Some more comments are in order.
In order to check that the lightest Z2-odd state has zero electric and color charges, the quantum numbers of the BSM particles must be given in the
qNumbers
dictionary in particles.py
. The format is
[2*spin, 3*electric charge, dimension of SU(3) representation]
The list of quantum numbers is also required to check for displaced vertices or heavy charged particles. The check for long-lived (or stable) particles first verifies if these appear in one of the cross section blocks and their cross section exceeds the minimum cross section value defined by sigmacut (see Minimum Decomposition Weight). If the cross section is larger than sigmacut and the particle is stable, the checker verifies if it is neutral (both electric and color charges are zero). On the other hand, if the particle is unstable, but its lifetime (times c) is larger than a minimum value (default = 10 mm), the particle is considered as a non-prompt decay. For non-prompt decays, all channels are then checked for visible decay products. If the branching ratio to visible decays times the maximum production cross section for the particle exceeds sigmacut, the particle’s decay is considered as a displaced vertex.
The usage of the SLHA checker is:
smodelsTools.py slhachecker [-h] [-xS] [-lsp] [-longlived] [-m DISPLACEMENT] [-s SIGMACUT] [-illegal] [-dB] -f FILENAME
- arguments:
-h, --help show this help message and exit -xS, --xsec turn off the check for xsection blocks -lsp, --lsp turn off the check for charged lsp -longlived, --longlived turn off the check for stable charged particles and visible displaced vertices -m DISPLACEMENT, --displacement DISPLACEMENT give maximum c*tau in [m] -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 -m 0.001 -s 0.01 -f inputFiles/slha/lightSquarks.slha
Running this will print the status flag and a message with potential warnings and error messages.
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.
- 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] -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
Detailed Guide to SModelS¶
Basic Concepts and Definitions¶
Throughout this manual, several concepts are used extensively. Here we define the most important ones, their respective nomenclature and some useful notation. The concepts related to the basic building blocks of the decomposition of a full model into a sum of Simplified Models (or elements) are described in Theory Definitions, while the concepts relevant for the database of experimental results are given in Database Definitions.
Simplified Model Definitions¶
The so-called theory module contains the basic tools necessary for decomposing the input model (either in LHE or SLHA format) into simplified model topologies and using the output of the decomposition to compute the theoretical prediction for a given experimental result.
The applicability of SModelS is currently restricted to models which contain a Z2 symmetry (R-parity in SUSY, K-parity in UED, …) and result in a missing transverse energy (MET) final state at experiments. This is required in order to provide a clear structure for the simplified model topologies appearing during the decomposition of the input model. Below we describe the basic concepts and language used in SModelS to describe the simplified model topologies.
Elements¶
A simplified model topology representing a specific cascade decay of a pair of BSM states produced in the hard scattering is called an element in the SModelS language. Elements contain the final states (Z2-even) particles appearing in the cascade decay as well as the masses of the BSM (Z2-odd) states which have decayed or appear in the last step of the decay. A representation of an element is shown below:

An element may also hold information about its corresponding weight (cross section times branching ratio times efficiency). [*] The overall properties of an element are illustrated in the scheme below:

SModelS works under the inherent assumption that, for collider purposes, all the essential properties of a BSM model can be encapsulated by its elements. Such an assumption is extremely helpful to cast the theoretical predictions of a specific BSM model in a model-independent framework, which can then be compared against the corresponding experimental limits. For instance, as shown in the scheme above, only the masses of the BSM states are used and other properties, such as their spins or other quantum numbers are ignored (the PID’s are, however, stored for book-keeping).
Below we describe in more detail the element properties and their implementation in SModelS.
- Elements are described by the Element Class
Each Z2-odd decay is represented by a vertex containing its final states (one Z2-odd state and the Z2-even particles), as shown in the scheme above.
Final states indicate all Z2-even states coming out of a vertex (see scheme above). In most cases, these correspond to Standard Model particles (electrons, gauge bosons, Higgs,…). Note that, if the input model contains BSM states which are Z2-even (such as additional Higgs bosons), these also appear as final states. In contrast, stable or long-lived Z2-odd particles which might appear in the detector (either as MET or charged tracks) are not classified as final states.
- Z2-even states are defined (and can be easily modified) in
particles.py
The Z2-odd states are always assumed to consist of BSM particles with Z2 conserving decays of the form: (Z2-odd state) \(\rightarrow\) (Z2-odd state’) + final states. The only information kept from the intermediate states are their masses (see scheme above). If an intermediate state is stable and neutral, it is considered as a MET signal.
- Z2-odd states are defined (and can be easily modified) in
particles.py
A branch is the basic substructure of an element. It represents a series of cascade decays of a single initial Z2-odd state. The diagram below illustrates an example of a branch.

The structure of each branch is fully defined by its number of vertices and the number of final states coming out of each vertex. Furthermore, the branch also holds the information about the particle labels for the final states coming out of each vertex and the masses of the intermediate states, as shown below.

- Branches are described by the Branch Class
The structure and final states of elements are represented in textual form using a nested brackets notation. The scheme below shows how to convert between the graphical and bracket representations of an element:

The brackets are ordered and nested in the following way. The outermost brackets correspond to the branches of the element. The branches are sorted according to their size (see element sorting) and each branch contains an ordered list of vertices. Each vertex contains a list of the final states (sorted alphabetically) coming out of the vertex. Schematically, for the example in the figure above, we have:
element = [branch1, branch2]
branch1 = [vertex1]
vertex1 = [l+,l-]
branch2 = [vertex1,vertex2]
vertex1 = [l+]
vertex2 = [nu]
Using the above scheme it is possible to unambiguously describe each element with a simple list of nested brackets. However, in order to fully specify all the information relative to a single element, we must also include the list of intermediate state masses and the element weight. The intermediate state masses can also be represented by a mass array for each branch, as shown below:

Topologies¶
It is often useful to classify elements according to their overall structure or topology. Each topology corresponds to an undressed element, removed of its final states and Z2-odd masses. Therefore the topology is fully determined by its number of branches, number of vertices in each branch and number of final states coming out of each vertex. An example of a topology is shown below:

Within SModelS, elements are grouped according to their topology. Hence topologies represent a list of elements sharing a common basic structure (same number of branches, vertices and final states in each vertex).
- Topologies are described by the Topology Class
[*] | In order to treat the UL and EM map results on the same footing, SModelS applies a trivial binary efficiency to elements for UL-type results as will be explained in detail later. |
Database Definitions¶
The so-called experiment module contains the basic tools necessary for handling the database of experimental results. The SModelS database collects experimental results of SUSY searches from both ATLAS and CMS, which are used to compute the experimental constraints on specific models. Starting with version 1.1, the SModelS database includes two types of experimental constraints:
- Upper Limit (UL) constraints: constrains on \(\sigma \times BR\) of simplified models, provided by the experimental collaborations (see UL-type results);
- Efficiency Map (EM) constraints: constrains the total signal (\(\sum \sigma \times BR \times \epsilon\)) in a specific signal region. Here \(\epsilon\) denotes the acceptance times efficiency. These are either provided by the experimental collaborations or computed by theory groups (see EM-type results);
Although the two types of constraints above are very distinct, both the folder structure and the object structure of SModelS are sufficiently flexible to simutaneously handle both UL-type and EM-type results. Therefore, for both UL-type and EM-type constraints, the database obeys the following structure:
- Database: collects a list of Experimental Results.
Experimental Result: each Experimental Result corresponds to an experimental preliminary result (i.e. a CONF-NOTE or PAS) or publication and contains a list of DataSets as well as general information about the result (luminosity, publication reference,…).
DataSet: a single DataSet corresponds to one signal region of the experimental note or publication [*]. In case of UL-type results there is a single DataSet, usually corresponding to the best signal region (for more details see DataSet). For EM-type results, there is one DataSet for each signal region. Each DataSet contains the Upper Limit maps for Upper Limit results or the Efficiency maps for Efficiency Map results.
- Upper Limit map: contains the upper limit constraints for UL-type results. Each map refers to a single simplified model (or more precisely to a single element or sum of elements).
- Efficiency map: contains the efficiencies for EM-type results. Each map refers to a single simplified model (or more precisely to a single element or sum of elements).
A schematic summary of the above structure can be seen below:

In the following sections we describe the main concepts and elements which constitute the SModelS database. More details about the database folder structure and object struture can be found in Database of Experimental Results.
Database¶
Each publication or conference note can be included in the database as an Experimental Result. Hence, the database is simply a collection of experimental results.
- The Database is described by the Database Class
Experimental Result¶
An experimental result contains all the relevant information corresponding to an experimental publication or preliminary result. In particular it holds general information about the experimental analysis, such as the corresponding luminosity, center of mass energy, publication reference, etc. The current version allows for two possible types of experimental results: one containing upper limit maps (UL-type) and one containing efficiency maps (EM-type).
- Experimental Results are described by the ExpResult Class
Upper Limit (UL) experimental results contain the experimental constraints on the cross section times branching ratio ( \(\sigma \times BR\) ) for Simplified Models from a specific experimental publication or preliminary result. These constraints are typically given in the format of Upper Limit maps, which correspond to 95% confidence level (C.L.) upper limit values on \(\sigma \times BR\) as a function of the respective parameter space (usually BSM masses or slices over mass planes). The UL values usually assume the best signal region (for a given point in parameter space), a combination of signal regions or more involved limits from other methods. Hence, for UL results there is a single DataSet, containing one or more UL maps. An example of a UL map is shown below:

Within SModelS, the above UL map is used to constrain the simplified model \(\tilde{q} + \tilde{q} \to \left(jet+\tilde{\chi}_1^0\right) + \left(jet+\tilde{\chi}_1^0\right)\). Using the SModelS notation this simplified model is mapped to the element \([[[jet]],[[jet]]]\), using the notation defined in Bracket Notation. Usually a single preliminary result/publication contains several UL maps, hence each UL-type experimental result contains several UL maps, each one constraining different simplified models (elements or sum of elements). We also point out that the exclusion curve shown in the UL map above is never used by SModelS.
The upper limit constraint specifies which simplified model (represented by an element or sum of elements) is being constrained by the respective UL map. For simple constraints as the one shown in the UL map above, there is a single element being constrained (\([[[jet]],[[jet]]]\)). In some cases, however, the constraint corresponds to a sum of elements. As an example, consider the ATLAS analysis shown below:

As we can see, the upper limits apply to the sum of the cross sections:
In this case the UL constraint is simply:
where it is understood that the sum is over the weights of the respective elements and not over the elements themselves.
Note that the sum can be over particle charges, flavors or more complex combinations of elements. However, almost all experimental results sum only over elements sharing a common topology.
Finally, in some cases the UL constraint assumes specific constributions from each element. For instance, in the example above it is implicitly assumed that both the electron and muon elements contribute equally to the total cross section. Hence these conditions must also be specified along with the constraint, as described in UL conditions.
When the analysis constraints are non-trivial (refer to a sum of elements), it is often the case that there are implicit (or explicit) assumptions about the contribution of each element. For instance, in the figure above, it is implicitly assumed that each lepton flavor contributes equally to the summed cross section:
Therefore, when applying these constraints to general models, one must also verify if these conditions are satisfied. Once again we can express these conditions in bracket notation:
where it is understood that the condition refers to the weights of the respective elements and not to the elements themselves.
In several cases it is desirable to relax the analysis conditions, so the analysis upper limits can be applied to a broader spectrum of models. Once again, for the example mentioned above, it might be reasonable to impose instead:
The departure from the exact condition can then be properly quantified and one can decide whether the analysis upper limits are applicable or not to the model being considered. Concretely, SModelS computes for each condition a number between 0 and 1, where 0 means the condition is exactly satisfied and 1 means it is maximally violated. Allowing for a \(20\%\) violation of a condition corresponds approximately to a ‘’condition violation value’’ (or simply condition value) of 0.2. The condition values are given as an output of SModelS, so the user can decide what are the maximum acceptable values.
Unlike UL-type results, the main information held by Efficiency Map (EM) results are the efficiencies for simplified models (represented by an element or sum of elements). These may be provided by the experimental collaborations or independently computed by theory groups. Efficiency maps correspond to a grid of simulated acceptance times efficiency ( \(A \times \epsilon\) ) values for a specific signal region. In the following we will refer to \(A \times \epsilon\) simply as efficiency and denote it by \(\epsilon\). Furthermore, additional information, such as the luminosity, number of observed and expected events, etc is also stored in a EM-type result.
Another important difference between UL-type results and EM-type results is the existence of several signal regions, which in SModelS are mapped to DataSets. While UL-type results contain a single DataSet (‘’signal region’‘), EM results hold several DataSets, one for each signal region (see the database scheme above). Each DataSet contains one or more efficiency maps, one for each element or sum of elements. The efficiency map is usually a function of the BSM masses appearing in the element, as shown by the example below:

Within SModelS the above EM map is used to compute the efficiency for the element \([[[jet]],[[jet]]]\), where we are using the notation defined in Bracket Notation. Usually there are several EM maps for a single data set: one for each element or sum of elements. In order to use a language similar to the one used in UL-type results, the element (or elements) for which the efficiencies correspond to are still called constraint.
Although efficiencis are most useful for EM-type results, their concept can also be extended to UL-type results. For the latter, the efficiencies for a given element are either 1, if the element appears in the UL constraint, or 0, otherwise. Atlhough trivial, this extension allows us to treat EM-type results and UL-type results in a very similar fashion (see Theory Predictions for more details).
Data Sets¶
Data sets are a way to conveniently group efficiency maps corresponding to the same signal region. As discussed in UL-type results, data sets are not necessary for UL-type results, since in this case there is a single ‘’signal region’‘. Nonetheless, data sets are also present in UL-type results in order to allow for a similar structure for both EM-type and UL-type results (see database scheme).
For UL-type results the data set contains the UL maps as well as some basic information, such as the type of Experimental Result (UL). On the other hand, for EM-type results, each data set contains the EM maps for the corresponding signal region as well as some additional information: the observed and expected number of events in the signal region, the signal upper limit, etc. In the folder structure shown in database scheme, the upper limit maps and efficiency maps for each element (or sum of elements) are stored in files labeled accoring to the TxName convention.
- Data Sets are described by the DataSet Class
TxName Convention¶
Since using the bracket notation to describe the simplified models appearing in the upper limit or efficiency maps can be rather lenghty, it is useful to define a shorthand notation for the constraints. SModelS adopts a notation based on the CMS SMS conventions, where each specific constraint is labeled as T<constraint name>, which we refer as TxName. For instance, the TxName corresponding to the constraint in the example above is TSlepSlep. A complete list of TxNames can be found here.
- Upper limit and efficiency maps are described by the TxName Class
More details about the database folder structure and object structure can be found in Database of Experimental Results.
[*] | The name Data Set is used instead of signal region because its concept is slightly more general. For instance, in the case of UL-type results, a DataSet may not correspond to a single signal region, but to a combination of signal regions. |
SModelS Structure¶
The main ingredients relevant for SModelS are:
Basic Input¶
Basic Model Input¶
The main input for SModelS is the full model definition, which can be given in the two following forms:
- a SLHA (SUSY Les Houches Accord) file containing masses, branching ratios and cross sections for the BSM states
(see an example file
here
) - a LHE (Les Houches Event) file containing parton level events
(see an example file
here
)
The SLHA format is usually more compact and best suited for supersymmetric models. On the other hand, a LHE file can always be generated for any BSM model (through the use of your favorite MC generator). [*] In this case, however, the precision of the results is limited to the MC statistics used to generate the file.
In the case of SLHA input only, the production cross sections for the BSM states also have to be included
in the SLHA file as SLHA blocks, according to the SLHA cross section format
(see example file
).
For the MSSM and some of its extensions, they may
be calculated automatically using Pythia
and NLLfast,
as discussed in cross section calculator.
In the case of LHE input, the total production cross section as well as
the center-of-mass energy should be listed in the <init></init> block, according to the standard LHE format
(see example file
).
Moreover, all the Z2-even particles (see definition in final states) should be set as stable, since
in SModelS they are effectively considered as final states.
When generating the events it is also important to ensure that no mass smearing is applied, so the mass
values for a given particle are the same throughout the LHE file.
New Particles¶
Besides information about the masses and branching ratios, the user must also define
which particles are Z2-odd states (Intermediate states)
and which are Z2-even (Final states).
These definitions must be given in the particles.py
file,
where some default values (for SM and MSSM particles) are already loaded.
A path to a user’s own particles.py can be specified in the parameter file, in the [particles] section.
If the user wants to check the SLHA input file for possible errors (see SLHA Checks),
it is also necessary to define some of the particle’s quantum numbers, as illustrated in
the particles.py
file.
SLHA Format for Cross Sections¶
A list of cross section blocks (one for each production process) must be included in the SLHA file for the SLHA-based Decomposition. The SLHA format for each cross section block is shown below (see the Les Houches note):

The above example shows the cross section for \(pp \rightarrow \tilde{\tau}_1^- + \tilde{\nu}_{\tau}\) at a center-of-mass energy of 8 TeV and at leading order. The only information used by SModelS are the center-of-mass energy, the outgoing particle PDGs, the cross section value and the QCD order. If the input file contains two cross sections for the same process but at different QCD orders, only the highest order will be used.
- Reading of cross sections from an input file is implemented by the getXsecFromSLHAFile method
[*] | SModelS can easily be used for non-SUSY models as long as they present a Z2-type symmetry. However, it is the responsibility of the user to make sure that the SMS results in the database actually apply to the model under consideration. |
Decomposition into Simplified Models¶
Given an input model, the first task of SModelS is to decompose the full model into a sum of Simplified Models (or elements in SModelS language). Based on the input format, which can be
- a SLHA file or
- a LHE file
(see Basic Input), two distinct (but similar) decomposition methods are applied: the SLHA-based or the LHE-based decomposition.
SLHA-based Decomposition¶
The SLHA file describing the input model is required to contain the masses of all the BSM states as well as their production cross sections and decay branching ratios. All the above information must follow the guidelines of the SLHA format. In particular, the cross sections also have to be included as SLHA blocks according to the SLHA cross section format.
Once the production cross sections are read from the input file, all the cross sections for production of two Z2-odd states are stored and serve as the initial step for the decomposition. (All the other cross sections with a different number of Z2-odd states are ignored.) Starting from these primary mothers, all the possible decays are generated according to the information contained in the DECAY blocks. This procedure is represented in the figure below:

Each of the possible cascade decays for each mother corresponds to a branch. In order to finally generate elements, all the branches are combined in pairs according to the production cross sections, as shown below:

For instance, assume [b1,b2,b3] and [B1,B2] represent all possible branches (or cascade decays) for the primary mothers A and B, respectively. Then, if a production cross section for \(pp \rightarrow A+B\) is given in the input file, the following elements will be generated:
[b1,B1], [b1,B2], [b2,B1], [b2,B2], [b3,B1] and [b3,B2]
Each of the elements generated according to the procedure just described will also store its weight, which equals its production cross section times all the branching ratios appearing in it. In order to avoid a too large number of elements, only those satisfying a minimum weight requirement are kept. Furthermore, the elements are grouped according to their topologies. The final output of the SLHA decomposition is a list of such topologies, where each topology contains a list of the elements generated during the decomposition.
- The SLHA decomposition is implemented by the SLHA decompose method
Some models may contain a large number of new states and each may have a large number of possible decays. As a result, long cascade decays are possible and the number of elements generated by the decomposition process may become too large, and the computing time too long. For most practical purposes, however, elements with extremely small weights (cross section times BRs) can be discarded, since they will fall well below the experimental limits. Therefore, during the SLHA decomposition, whenever an element is generated with a weight below some minimum value, this element (and all elements derived from it) is ignored. The minimum weight to be considered is given by the sigcut parameter and is easily adjustable (see slhaDecomposer.decompose).
Note that, when computing the theory predictions, the weight of several elements can be combined together. Hence it is recommended to set the value of sigcut approximately one order of magnitude below the minimum signal cross sections the experimental data can constrain.
LHE-based Decomposition¶
More general models can be input through an LHE event file containing parton-level events, including the production of the primary mothers and their cascade decays. Each event can then be directly mapped to an element with the element weight corresponding to the event weight. Finally, identical elements can be combined together (adding their weights). The procedure is represented in the example below:

Notice that, for the LHE decomposition, the elements generated are restricted to the events in the input file. Hence, the uncertainties on the elements weights (and which elements are actually generated by the model) are fully dependent on the Monte Carlo statistics used to generate the LHE file. Also, when generating the events it is important to ensure that no mass smearing is applied, so the events always contain the same mass value for a given particle.
- The LHE decomposition is implemented by the LHE decompose method
Compression of Elements¶
During the decomposition process it is possible to perform several simplifications on the elements generated. In both the LHE and SLHA-based decompositions, two useful simplifications are possible: Mass Compression and Invisible Compression. The main advantage of performing these compressions is that the simplified element is always shorter (has fewer cascade decay steps), which makes it more likely to be constrained by experimental results. The details behind the compression methods are as follows:
In case of small mass differences, the decay of an intermediate state to a nearly degenerate one will in most cases produce soft final states, which can not be experimentally detected. Consequently, it is a good approximation to neglect the soft final states and compress the respective decay, as shown below:

After the compression, only the lightest of the two near-degenerate masses are kept in the element, as shown above. The main parameter which controls the compression is minmassgap, which corresponds to the maximum value of \(\epsilon\) in the figure above to which the compression is performed:
Note that the compression is an approximation since the final states, depending on the boost of the parent state, may not always be soft. It is recommended to choose values of minmassgap between 1-10 GeV; the default value is 5 GeV.
- Mass compression is implemented by the massCompress method and can be easily turned on/off by the flag doCompress in the SLHA or LHE decompositions.
Another type of compression is possible when the final states of the last decay are invisible. The most common example is
as the last step of the decay chain, where \(B\) is an insivible particle leading to a MET signature. Since both the neutrino and \(B\) are invisible, for all experimental purposes the effective MET object is \(B + \nu = A\). Hence it is possible to omit the last step in the cascade decay, resulting in a compressed element. Note that this compression can be applied consecutively to several steps of the cascade decay if all of them contain only invisible final states:

- Invisible compression is implemented by the invisibleCompress method and can be easily turned on/off by the flag doInvisible in the SLHA or LHE decompositions.
Element Sorting¶
In order to improve the code performance, elements created during decomposition and sharing a commong topology are sorted. Sorting allows for an easy ordering of the elements belonging to a topology and faster element comparison. Elements are sorted according to their branches. Branches are compared according to the following properties:
- Number of vertices
- Number of final states in each vertex
- Final state particles (particles belonging to the same vertex are alphabetically sorted)
- Mass array
As an example, consider the three elements below:

The correct ordering of the above elements is:
Element 3 < Element 2 < Element 1
Element 1 is ‘larger’ than the other two since it has a larger number of vertices. Elements 2 and 3 are identical, except for their masses. Since the mass array of Element 3 is smaller than the one in Element 2, the former is ‘smaller’ than the latter. Finally if all the branch features listed above are identical for both branches, the elements being compared are considered to be equal. Futhermore, the branches belonging to the same element are also sorted. Hence, if an element has two branches:
it implies
- Branch sorting is implemented by the sortBranches method
Theory Predictions¶
The decomposition of the input model as a sum of elements (simplified models) is the first step for confronting the model with the experimental limits. The next step consists of computing the relevant signal cross sections (or theory predictions) for comparison with the experimental limits. Below we describe the procedure for the computation of the theory predictions after the model has been decomposed.
Computing Theory Predictions¶
As discussed in Database Definitions, the SModelS database allows for two types of experimental constraints: Upper Limit constraints (see UL-type results) and Efficiency Map constraints (see EM-type results). Each of them requires different theoretical predictions to be compared against experimental data.
UL-type results constrains the weight (\(\sigma \times BR\)) of one element or sum of elements. Therefore SModelS must compute the theoretical value of \(\sigma \times BR\) summing only over the elements appearing in the respective constraint. This is done applying a 1 (zero) efficiency (\(\epsilon\)) for the elements which appear (do not appear) in the constraint. Then the final theoretical prediction is the sum over all elements with a non-zero value of \(\sum \sigma \times BR \times \epsilon\). This value can then be compared with the respective 95% C.L. upper limit extracted from the UL map (see UL-type results).
On the other hand, EM-type results constrain the total signal (\(\sum \sigma \times BR \times \epsilon\)) in a given signal region (DataSet). Consequently, in this case SModelS must compute \(\sigma \times BR \times \epsilon\) for each element, using the efficiency maps for the corresponding DataSet. The final theoretical prediction is the sum over all elements with a non-zero value of \(\sigma \times BR \times \epsilon\). This value can then be compared with the signal upper limit for the respective signal region (data set).
For experimental results for which the covariance matrix is provided, it is possible to combine all the signal regions (see Combination of Signal Regions). In this case the final theory prediction corresponds to the sum of \(\sigma \times BR \times \epsilon\) over all signal regions (and all elements) and the upper limit is computed for this sum.
Although the details of the theoretical prediction computation differ depending on the type of Experimental Result (UL-type results or EM-type results), the overall procedure is common for both type of results. Below we schematically show the main steps of the theory prediction calculation:

As shown above the procedure can always be divided in two main steps: Element Selection and Element Clustering. Once the elements have been selected and clustered, the theory prediction for each DataSet is given by the sum of all the element weights (\(\sigma \times BR \times \epsilon\)) belonging to the same cluster:
Below we describe in detail the element selection and element clustering methods for computing the theory predictions for each type of Experimental Result separately.
- Theory predictions are computed using the theoryPredictionsFor method
Theory Predictions for Upper Limit Results¶
Computation of the signal cross sections for a given UL-type result takes place in two steps. First selection of the elements generated by the model decomposition and then clustering of the selected elements according to their masses. These two steps are described below.
An UL-type result holds upper limits for the cross sections of an element or sum of elements. Consequently, the first step for computing the theory predictions for the corresponding experimental result is to select the elements that appear in the UL result constraint. This is conveniently done attributing to each element an efficiency equal to 1 (0) if the element appears (does not appear) in the constraint. After all the elements weights (\(\sigma \times BR\)) have been rescaled by these ‘’trivial’’ efficiencies, only the ones with non-zero weights are relevant for the signal cross section. The element selection is then trivially achieved by selecting all the elements with non-zero weights.
The procedure described above is illustrated graphically in the figure below for the simple example where the constraint is \([[[e^+]],[[e^-]]]\,+\,[[[\mu^+]],[[\mu^-]]]\).

- The element selection is implemented by the getElementsFrom method
Naively one would expect that after all the elements appearing in the constraint have been selected, it is trivial to compute the theory prediction: one must simply sum up the weights (\(\sigma \times BR\)) of all the selected elements. However, the selected elements usually differ in their masses [*] and the experimental limit (see Upper Limit constraint) assumes that all the elements appearing in the constraint have the same mass (or mass array). As a result, the selected elements must be grouped into clusters of equal masses. When grouping the elements, however, one must allow for small mass differences, since the experimental efficiencies should not be strongly sensitive to small mass differences. For instance, assume two elements contain identical mass arrays, except for the parent masses which differ by 1 MeV. In this case it is obvious that for all experimental purposes the two elements have identical masses and should contribute to the same theory prediction (e.g. their weights should be added when computing the signal cross section). Unfortunately there is no way to unambiguously define ‘’similar masses’’ and the definition should depend on the Experimental Result, since different results will be more or less sensitive to mass differences. SModelS uses an UL map-dependent measure of the distance between two element masses, as described in Mass Distance.
If two of the selected elements have a mass distance smaller than a maximum value (defined by maxDist), they are gouped in the same mass cluster, as illustrated by the example below:

Once all the elements have been clustered, their weights can finally be added together and compared against the experimental upper limit.
- The clustering of elements is implemented by the clusterElements method.
As mentioned above, in order to cluster the elements it is necessary to determine whether two elements have similar masses (see element and Bracket Notation for more details on element mass). Since an absolute definition of ‘’similar masses’’ is not possible and the sensitivity to mass differences depends on the experimental result, SModelS uses an ‘’upper limit map-dependent’’ definition. For each element’s mass array, the upper limit for the corresponding mass values is obtained from the UL map (see UL-type result). This way, each mass array is mapped to a single number (the cross section upper limit for the experimental result). Then the distance between the two element’s masses is simply given by the relative difference between their respective upper limits. More explicitly:
where \(M_A,M_B\) (\(x,y\)) are the mass arrays (upper limits) for the elements A and B, respectively. If the mass distance of two elements is smaller than maxDist, the two masses are considered similar.
Notice that the above definition of mass distance quantifies the experimental analysis sensitivity to mass differences, which is the relevant parameter when clustering elements. Also, a check is performed to ensure that masses with very distinct values but similar upper limits are not clustered together.
- The mass distance function is implemented by the distance method
Theory Predictions for Efficiency Map Results¶
In order to compute the signal cross sections for a given EM-type result, so it can be compared to the signal region limits, it is first necessary to apply the efficiencies (see EM-type result) to all the elements generated by the model decomposition. Notice that typically a single EM-type result contains several signal regions (DataSets) and there will be a set of efficiencies (or efficiency maps) for each data set. As a result, several theory predictions (one for each data set) will be computed. This procedure is similar (in nature) to the Element Selection applied in the case of an UL-type result, except that now it must be repeated for several data sets (signal regions).
After the element’s weights have being rescaled by the corresponding efficiencies for the given data set (signal region), all of them can be grouped together in a single cluster, which will provide a single theory prediction (signal cross section) for each DataSet. Hence the element clustering discussed below is completely trivial. On the other hand the element selection is slightly more involved than in the UL-type result case and will be discussed in more detail.
The element selection for the case of a EM-type result consists of rescaling all the elements weights by their efficiencies, according to the efficiency map of the corresponding DataSet. The efficiency for a given DataSet depends both on the element mass and on its topology and particle content. In practice the efficiencies for most of the elements will be extremely small (or zero), hence only a subset effectively contributes after the element selection [†]. In the figure below we illustrate the element selection for the case of a EM-type result/DataSet:

If, for instance, the analysis being considered vetoes \(jets\) and \(\tau\)‘s in the final state, we will have \(\epsilon_2,\, \epsilon_4 \simeq 0\) for the example in the figure above. Nonetheless, the element selection for a DataSet is usually more inclusive than the one applied for the UL-type result, resulting in less conservative values for the theory prediction.
- The element selection is implemented by the getElementsFrom method
Unlike the clustering required in the case of UL-type result (see Element Clustering for an UL analysis), after the efficiencies have been applied to the element’s weights, there is no longer the necessity to group the elements according to their masses, since the mass differences have already been accounted for by the different efficiencies. As a result, after the element selection all elements belong to a single cluster:

- The (trivial) clustering of elements is implemented by the clusterElements method.
[*] | As discussed in Database Definitions, UL-type results have a single DataSet. |
[†] | When refering to an element mass, we mean all the intermediate state masses appearing in the element (or the element mass array). Two elements are considered to have identical masses if their mass arrays are identical (see element and Bracket Notation for more details). |
[‡] | The number of elements passing the selection also depends on the availability of efficiency maps for the elements generated by the decomposition. Whenever there are no efficiencies available for a element, the efficiency is taken to be zero. |
Database of Experimental Results¶
SModelS stores all the information about the experimental results in the Database. Below we describe both the directory and object structure of the Database.
Database: Directory Structure¶
The Database is organized as files in an ordinary (UNIX) directory hierarchy, with a thin Python layer serving as the access to the database. The overall structure of the directory hierarchy and its contents is depicted in the scheme below (click to enlarge):

As seen above, the top level of the SModelS database categorizes the analyses by LHC center-of-mass energies, \(\sqrt{s}\):
- 8 TeV
- 13 TeV
Also, the top level directory contains a file called version
with the
version string of the database.
The second level splits the results up between the different experiments:
- 8TeV/CMS/
- 8TeV/ATLAS/
The third level of the directory hierarchy encodes the Experimental Results:
- 8TeV/CMS/CMS-SUS-12-024
- 8TeV/ATLAS/ATLAS-CONF-2013-047
- …
- The Database folder is described by the Database Class
Each Experimental Result folder contains:
- a folder for each DataSet (e.g.
data
) - a
globalInfo.txt
file
The globalInfo.txt
file contains the meta information about the Experimental Result.
It defines the center-of-mass energy \(\sqrt{s}\), the integrated luminosity, the id
used to identify the result and additional information about the source of the
data. Here is the content of CMS-SUS-12-024/globalInfo.txt as an example:
sqrts: 8.0*TeV
lumi: 19.4/fb
id: CMS-SUS-12-024
prettyName: \slash{E}_{T}+b
url: https://twiki.cern.ch/twiki/bin/view/CMSPublic/PhysicsResultsSUS12024
arxiv: http://arxiv.org/abs/1305.2390
publication: http://www.sciencedirect.com/science/article/pii/S0370269313005339
contact: Keith Ulmer <keith.ulmer@cern.ch>, Josh Thompson <joshua.thompson@cern.ch>, Alessandro Gaz <alessandro.gaz@cern.ch>
private: False
implementedBy: Wolfgang Waltenberger
lastUpdate: 2015/5/11
- Experimental Result folder is described by the ExpResult Class
- globalInfo files are descrived by the Info Class
Each DataSet folder (e.g. data
) contains:
- the Upper Limit maps for UL-type results or Efficiency maps for EM-type results (
TxName.txt
files) - a
dataInfo.txt
file containing meta information about the DataSet - Data Set folders are described by the DataSet Class
- TxName files are described by the TxName Class
- dataInfo files are described by the Info Class
Since UL-type results have a single dataset (see DataSets), the info file only holds some trivial information, such as the type of Experimental Result (UL) and the dataset id (None for UL-type results). Here is the content of CMS-SUS-12-024/data/dataInfo.txt as an example:
dataType: upperLimit
dataId: None
For UL-type results, each TxName.txt
file contains the UL map for a given simplified model
(element or sum of elements) as well as some meta information,
including the corresponding constraint and conditions. The
first few lines of CMS-SUS-12-024/data/T1tttt.txt read:
txName: T1tttt
conditionDescription: None
condition: None
constraint: [[['t','t']],[['t','t']]]
figureUrl: https://twiki.cern.ch/twiki/pub/CMSPublic/PhysicsResultsSUS12024/T1tttt_exclusions_corrected.pdf
validated: True
axes: 2*Eq(mother,x)_Eq(lsp,y)
publishedData: True
The second block of data contains the upper limits as a function of the BSM masses:
upperLimits: [[[[400.0*GeV, 0.0*GeV], [400.0*GeV, 0.0*GeV]], 1.815773*pb],
[[[400.0*GeV, 25.0*GeV], [400.0*GeV, 25.0*GeV]], 1.806528*pb],
[[[400.0*GeV, 50.0*GeV], [400.0*GeV, 50.0*GeV]], 2.139336*pb],
[[[400.0*GeV, 75.0*GeV], [400.0*GeV, 75.0*GeV]], 2.472143*pb],
...
As we can see, the UL map is given as a Python array with the structure: \([[\mbox{masses},\mbox{upper limit}], [\mbox{masses},\mbox{upper limit}],...]\).
For EM-type results the dataInfo.txt
contains relevant information, such as an id to
identify the DataSet (signal region), the number of observed and expected
background events for the corresponding signal region and the respective signal
upper limits. Here is the content of
CMS-SUS-13-012-eff/3NJet6_1000HT1250_200MHT300/dataInfo.txt as an example:
dataType: efficiencyMap
dataId: 3NJet6_1000HT1250_200MHT300
observedN: 335
expectedBG: 305
bgError: 41
upperLimit: 5.681*fb
expectedUpperLimit: 4.585*fb
For EM-type results, each TxName.txt
file contains the efficiency map for a given
simplified model (element or sum of elements) as well as some meta
information.
Here is the first few lines of CMS-SUS-13-012-eff/3NJet6_1000HT1250_200MHT300/T2.txt:
txName: T2
conditionDescription: None
condition: None
constraint: [[['jet']],[['jet']]]
figureUrl: https://twiki.cern.ch/twiki/pub/CMSPublic/PhysicsResultsSUS13012/Fig_7a.pdf
validated: True
axes: 2*Eq(mother,x)_Eq(lsp,y)
publishedData: False
As seen above, the first block of data in the T2.txt
file contains
information about the element (\([[[\mbox{jet}]],[[\mbox{jet}]]]\))
in bracket notation for which the
efficiencies refers to as well as reference to the original data source and
some additional information.
The second block of data contains the efficiencies as a function of the BSM masses:
efficiencyMap: [[[[312.5*GeV, 12.5*GeV], [312.5*GeV, 12.5*GeV]], 0.00109],
[[[312.5*GeV, 62.5*GeV], [312.5*GeV, 62.5*GeV]], 0.00118],
[[[312.5*GeV, 112.5*GeV], [312.5*GeV, 112.5*GeV]], 0.00073],
[[[312.5*GeV, 162.5*GeV], [312.5*GeV, 162.5*GeV]], 0.00044],
...
As we can see the efficiency map is given as a Python array with the structure: \([[\mbox{masses},\mbox{efficiency}], [\mbox{masses},\mbox{efficiency}],...]\).
Database: Object Structure¶
The Database folder structure is mapped to Python objects in SModelS. The mapping is almost one-to-one, except for a few exceptions. Below we show the overall object structure as well as the folders/files the objects represent (click to enlarge):

The type of Python object (Python class, Python list,…) is shown in brackets. For convenience, below we explicitly list the main database folders/files and the Python objects they are mapped to:
- Database folder \(\rightarrow\) Database Class
- Experimental Result folder \(\rightarrow\) ExpResult Class
- DataSet folder \(\rightarrow\) DataSet Class
globalInfo.txt
file \(\rightarrow\) Info ClassdataInfo.txt
file \(\rightarrow\) Info ClassTxname.txt
file \(\rightarrow\) TxName Class
Database: Binary (Pickle) Format¶
At the first time of instantiating the Database class, the text files in <database-path>. are loaded and parsed, and the corresponding data objects are built. The efficiency and upper limit maps themselves are subjected to standard preprocessing steps such as a principal component analysis and Delaunay triangulation (see Figure below). The simplices defined during triangulation are then used for linearly interpolating the data grid, thus allowing SModelS to compute efficiencies or upper limits for arbitrary mass values (as long as they fall inside the data grid). This procedure provides an efficient and numerically robust way of dealing with generic data grids, including arbitrary parametrizations of the mass parameter space, irregular data grids and asymmetric branches.

For the sake of efficiency, the entire database – including the Delaunay triangulation – is then serialized into a pickle file (<database-path>/database.pcl), which will be read directly the next time the database is loaded. If any changes in the database folder structure are detected, the python or the SModelS version has changed, SModelS will automatically re-build the pickle file. This action may take a few minutes, but it is again performed only once. If desired, the pickling process can be skipped using the option force_load = `txt’ in the constructor of Database .
- The pickle file is created by the createBinaryFile method
Confronting Predictions with Experimental Limits¶
Once the relevant signal cross sections (or theory predictions) have been computed for the input model, these must be compared to the respective upper limits. The upper limits for the signal are stored in the SModelS Database and depend on the type of Experimental Result: UL-type or EM-type.
In the case of a UL-type result, the theory predictions typically consist of a list of signal cross sections (one for each cluster) for the single data set (see Theory Predictions for Upper Limit Results for more details). Each theory prediction must then be compared to its corresponding upper limit. This limit is simply the cross section upper limit provided by the experimental publication or conference note and is extracted from the corresponding UL map (see UL-type results).
For EM-type results there is a single cluster for each data set (or signal region), and hence a single signal cross section value. This value must be compared to the upper limit for the corresponding signal region. This upper limit is easily computed using the number of observed and expected events for the data set and their uncertainties and is typically stored in the Database. Since most EM-type results have several signal regions (data sets), there will be one theory prediction/upper limit for each data set. By default SModelS keeps only the best data set, i.e. the one with the largest ratio \(\mbox{(theory prediction)}/\mbox{(expected limit)}\). (See below for combination of signal regions) Thus each EM-type result will have a single theory prediction/upper limit, corresponding to the best data set (based on the expected limit). If the user wants to have access to all the data sets, the default behavior can be disabled by setting useBestDataset=False in theoryPredictionsFor (see Example.py).
The procedure described above can be applied to all the Experimental Results in the database, resulting in a list of theory predictions and upper limits for each Experimental Result. A model can then be considered excluded by the experimental results if, for one or more predictions, we have theory prediction \(>\) upper limit [*].
- The upper limits for a given UL-type result or EM-type result can be obtained using the getUpperLimitFor method
Likelihood Computation¶
In the case of EM-type results, additional statistical information about the constrained model can be provided by the SModelS output. Following the procedure detailed in CMS-NOTE-2017-001, we construct a simplified likelihood which describes the plausibility of the data \(D\), given a signal strength \(\mu\):
Here, \(\theta\) denotes the nuisance parameter that describes the variations in the signal and background contribtions due to systematic effects. We assume \(p(\theta)\) to follow a Gaussian distribution centered around zero and with a variance of \(\delta^2\), whereas \(P(D)\) corresponds to a counting variable and is thus properly described by a Poissonian. The complete likelihood thus reads:
where \(n_{obs}\) is the number of observed events in the signal region. A test statistic \(T\) can now be constructed from a likelihood ratio test:
As the signal hypothesis in the numerator presents a special case of the likelihood in the denominator, the Neyman-Pearson lemma holds, and we can assume \(T\) to be distributed according to a \(\chi^2\) distribution with one degree of freedom. Because \(H_0\) assumes the signal strength of a particular model, \(T=0\) corresponds to a perfect match between that model’s prediction and the measured data. \(T \gtrsim 1.96\) corresponds to a 95% confidence level upper limit. While \(n_{\mathrm{obs}}\), \(b\) and \(\delta_{b}\) are directly extracted from the data set (coined observedN, expectedBG and bgError, respectively), \(n_{\mathrm{signal}}\) is obtained from the calculation of the theory predictions. A default 20% systematical uncertainty is assumed for \(n_{\mathrm{signal}}\), resulting in \(\delta^2 = \delta_{b}^2 + \left(0.2 n_{\mathrm{signal}}\right)^2\).
SModelS reports the \(\chi^2\) (\(T\) values) and likelihood for each EM-type result, together with the observed and expected \(r\) values. We note that in the general case analyses may be correlated, so summing up the \(T\) values will no longer follow a \(\chi^2_{(n)}\) distribution. Therefore, for a conservative interpretation, only the result with the best expected limit should be used. Moreover, for a statistically rigorous usage in scans, it is recommended to check that the analysis giving the best expected limit does not wildly jump within continuous regions of parameter space that give roughly the same phenomenology.
- The \(\chi^2\) for a given EM-type result is computed using the chi2 method
- The likelihood for a given EM-type result is computed using the likelihood method
Combination of Signal Regions¶
If the experiment provides a covariance matrix together with the efficiency maps, signal regions can be combined. This is implemented in SModelS v1.1.3 onwards, following as above the simplified likelihood approach described in CMS-NOTE-2017-001.
SModelS allows for a marginalization as well as a profiling of the nuisances, with profiling being the default (an example for using marginalisation can be found in How To’s). Since CPU performance is a concern in SModelS, we try to aggregate the official results, which can comprise >100 signal regions, to an acceptable number of aggregate regions. Here acceptable means as few aggregate regions as possible without loosing in precision or constraining power. The CPU time scales roughly linearly with the number of signal regions, so aggregating e.g. from 80 to 20 signal regions means gaining a factor 4 in computing time.
Under the assumptions described in CMS-NOTE-2017-001, the likelihood for the signal hypothesis when combining signal regions is given by:
where the product is over all \(N\) signal regions, \(\mu\) is the overall signal strength, \(s_i^r\) the relative signal strength in each signal region and \(V\) represents the covariance matrix. Note, however, that unlike the case of a single signal region, we do not include any signal uncertainties, since this should correspond to a second order effect.
Using the above likelihood we compute a 95% confidence level limit on \(\mu\) using the \(CL_s\) (\(CL_{sb}/CL_{b}\)) limit from the test statistic \(q_\mu\), as described in Eq. 14 in G. Cowan et al., Asymptotic formulae for likelihood-based tests. We then search for the value \(CL_s = 0.95\) using the Brent bracketing technique available through the scipy optimize library. Note that the limit computed through this procedure applies to the total signal yield summed over all signal regions and assumes that the relative signal strengths in each signal region are fixed by the signal hypothesis. As a result, the above limit has to be computed for each given input model (or each theory prediction), thus considerably increasing CPU time.
When using runSModelS.py, the combination of signal regions is turned on or off with the parameter options:combineSRs, see parameter file. Its default value is False, in which case only the result from the best expected signal region (best SR) is reported. If combineSRs = True, both the combined result and the one from the best SR are quoted.
In the figure below we show the constraints on the simplified model T2bbWWoff when using the best signal region (left), all the 44 signal regions considered in CMS-PAS-SUS-16-052 (center) and the aggregated signal regions included in the SModelS database (right). As we can see, while the curve obtained from the combination of all 44 signal regions is much closer to the official exclusion than the one obtained using only the best SR. Finally, the aggregated result included in the SModelS database (total of 17 aggregate regions) comes with little loss in constraining power, although it considerable reduces the running time.
![]() Best signal region |
![]() 44 signal regions |
![]() 17 aggregate regions |
Figure: Comparison of exclusion curves for CMS-PAS-SUS-16-052 using only the best signal region (left), the combination of 17 aggregate signal regions (center), and the combination of all 44 signal regions (right).
[*] | The statistical significance of the exclusion statement is difficult to quantify exactly, since the model is being tested by a large number of results simultaneously. |
Topology Coverage¶
The constraints provided by SModelS are obviously limited by its database and the available set of simplified model interpretations provided by the experimental collaborations or computed by theory groups. Therefore it is interesting to identify classes of missing simplified models (or missing topologies) which are relevant for a given input model, but are not constrained by the SModelS database. This task is performed as a last step in SModelS, once the decomposition and the theory predictions have been computed.
Given the decomposition output (list of elements), as well as the database information, it finds and classifies the elements which are not tested by any of the experimental results in the database. These elements are grouped into the following classes:
missingTopos: elements which are not tested by any of the experimental results in the database (independent of the element mass). The missing topologies are further classified as:
outsideGrid: elements which could be tested by one or more experimental result, but are not constrained because the mass array is outside the mass grid;
In order to classify the elements, the tool loops over all the elements found in the decomposition and checks if they are tested by one or more experimental results in the database [*]. All the elements which are not tested by any of the experimental results in the database (independent of their masses) are added to the missingTopos class. The remaining elements which do appear in one or more of the experimental results, but have not been tested because their masses fall outside the efficiency or upper limit grids (see EM-type results and UL-type results), are added to the outsideGrid class.
Usually the list of missing or outsideGrid elements is considerably long. Hence, to compress this list, all elements differing only by their masses (with the same final states) or electric charges are combined. Moreover, by default, electrons and muons are combined to light leptons (denoted “l”): gluons and light quarks are combined into jets. The missing topologies are then further classified (if applicable) into longCascade or asymmetricBranches topologies.
The topologies for each of the four categories are then grouped according to the final state (for the missingTopos and outsideGrid classes) or according to the PDG ids of the initially produced motherparticles (for the longCascade and asymmetricBranches classes). We note that for the latter the elements deriving from different mother particles, but with the same final states and mass configuration cannot be distinguished, and are therefore combined in this grouping. The full list of mother PDG id pairs can be accessed in the python printout or the comment of the text printout.
The topology coverage tool is normally called from within SModelS (e.g. when running runSModelS.py) by setting testCoverage=True in the parameters file. In the output, contributions in each category are ordered by cross section. By default only the ones with the ten largest cross sections are shown.
- The topology coverage tool is implemented by the Uncovered class
[*] | If mass or invisible compression are turned on, elements which can be compressed are not considered, to avoid double counting. |
In the following we discuss each of these in more detail.
Output Description¶
A detailed description of the possible output formats generated by running SModelS and their content is given below. For simplicity we will assume that all printer options in the parameters file are set to True, so the output information is maximal [*].
Screen (Stdout) Output¶
The stdout (or log output) is intended to provide extensive information about the database, the decomposition, the theory predictions and the missing topologies. It is most convenient if the input is a single file and not a folder, since the output is quite extensive. If all the options in stdout-printer are set to True (see parameters file), the screen output contains the following information:
- information about the basic input parameters and the status of the run:
Input status: 1
Decomposition output status: 1 #decomposition was successful
# Input File: inputFiles/slha/gluino_squarks.slha
# maxcond = 0.2
# minmassgap = 5.
# ncpus = 1
# sigmacut = 0.03
# Database version: 1.1.1
- a list of all the experimental results considered (if printDatabase = True). Note that this list corresponds to all the results selected in the database options (see parameters file). If addAnaInfo = True, for each experimental result entry a list of all the simplified models (or elements) constrained by the analysis is also shown using the bracket notation:
=======================================================
|| ||
|| Selected Experimental Results ||
|| ||
=======================================================
========================================================
Experimental Result ID: ATLAS-SUSY-2015-01
Tx Labels: ['T2bb']
Sqrts: 1.30E+01 [TeV]
-----------------------------
Elements tested by analysis:
[[[b]],[[b]]]
========================================================
========================================================
Experimental Result ID: CMS-SUS-13-007
Tx Labels: ['T1tttt', 'T1ttttoff', 'T5tttt', 'T5ttttoff']
Sqrts: 8.00E+00 [TeV]
-----------------------------
Elements tested by analysis:
[[[t,t]],[[t,t]]]
[[[W,W,b,b]],[[W,W,b,b]]]
[[[t],[t]],[[t],[t]]]
[[[W,b],[W,b]],[[W,b],[W,b]]]
- a full list of the topologies generated by the decomposition (if printDecomp = True). Each topology entry contains basic information about the topology as well as the number of elements with this topology and the sum over all the elements weights. If addElementInfo = True, the elements belonging to each topology are also explicitly shown, as well as the element’s mass, final states, weight, the PIDs of the intermediate particles contributing to the element and the element ID:
=======================================================
|| ||
|| Topologies Table ||
|| ||
=======================================================
=====================================================
Topology:
Number of vertices: [0, 0]
Number of vertex parts: [[], []]
Total Global topology weight :
Sqrts: 8.00E+00 [TeV], Weight:4.81E-04 [pb]
Total Number of Elements: 1
.........................................................................
Element:
Element ID: 1
Particles in element: [[], []]
The element masses are
Branch 0: [1.29E+02 [GeV]]
Branch 1: [1.29E+02 [GeV]]
The element PIDs are
PIDs: [[1000022], [1000022]]
The element weights are:
Sqrts: 8.00E+00 [TeV], Weight:4.81E-04 [pb]
=====================================================
Topology:
Number of vertices: [0, 1]
Number of vertex parts: [[], [1]]
Total Global topology weight :
Sqrts: 8.00E+00 [TeV], Weight:1.10E-03 [pb]
Total Number of Elements: 5
.........................................................................
Element:
Element ID: 2
Particles in element: [[], [['W+']]]
The element masses are
Branch 0: [1.29E+02 [GeV]]
Branch 1: [2.69E+02 [GeV], 1.29E+02 [GeV]]
The element PIDs are
PIDs: [[1000022], [1000024, 1000022]]
The element weights are:
Sqrts: 8.00E+00 [TeV], Weight:2.40E-04 [pb]
- a list of all the theory predictions obtained and the corresponding experimental result upper limit. For each experimental result, the corresponding id, signal region (data set) and sqrts as well as the constrained simplified models (txnames) are printed. After this basic information, the signal cross section (theory prediction), the list of condition values (if applicable) and the corresponding observed upper limit are shown. Also, if available, the expected upper limit is included. If computeStatistics = True, the \(\chi^2\) and likelihood values are printed (see likelihood calculation). Finally, if printExtendedResults = True, basic information about the elements being constrained, such as their masses, IDs and PIDs, is also shown.
=======================================================
|| ||
|| Theory Predictions and ||
|| Experimental Constraints ||
|| ||
=======================================================
---------------Analysis Label = CMS-SUS-13-019
-------------------Dataset Label = (UL)
-------------------Txname Labels = ['T2']
Analysis sqrts: 8.00E+00 [TeV]
Theory prediction: 1.77E-03 [pb]
Theory conditions: None
Observed experimental limit: 3.76E-03 [pb]
Masses in branch 0: [9.91E+02 [GeV], 1.29E+02 [GeV]]
Masses in branch 1: [9.91E+02 [GeV], 1.29E+02 [GeV]]
Contributing elements: [17, 18]
PIDs:[[2000002, 1000022], [2000002, 1000022]]
PIDs:[[-2000002, -1000022], [2000002, 1000022]]
PIDs:[[2000002, 1000022], [2000001, 1000022]]
---------------Analysis Label = ATLAS-SUSY-2013-02
-------------------Dataset Label = (UL)
-------------------Txname Labels = ['T6WW']
Analysis sqrts: 8.00E+00 [TeV]
Theory prediction: 6.62E-03 [pb]
Theory conditions: None
Observed experimental limit: 1.72E-02 [pb]
Masses in branch 0: [9.92E+02 [GeV], 2.69E+02 [GeV], 1.29E+02 [GeV]]
Masses in branch 1: [9.93E+02 [GeV], 2.69E+02 [GeV], 1.29E+02 [GeV]]
Contributing elements: [221, 222, 223, 225, 226, 227, 228, 233, 236, 238]
PIDs:[[-1000003, 1000024, 1000022], [1000003, -1000024, -1000022]]
PIDs:[[1000003, -1000024, -1000022], [1000002, 1000024, 1000022]]
PIDs:[[1000003, -1000024, -1000022], [1000001, -1000024, -1000022]]
PIDs:[[1000002, 1000024, 1000022], [1000002, 1000024, 1000022]]
PIDs:[[1000002, 1000024, 1000022], [1000004, 1000024, 1000022]]
- summary information about the missing topologies, if testCoverage = True. The total missing topology cross section corresponds to the sum of cross sections of all elements which are not tested by any experimental result. If, however, the element is constrained by one or more experimental results, but its mass is outside the efficiency or upper limit grids (see EM-type results and UL-type results), its cross section is included in the total cross section outside the grid. Finally, the elements which contribute to the total missing topology cross section are subdivided into elements with long decays or with asymmetric branches (see coverage tool for more details)
Total missing topology cross section (fb): 2.767E+02
Total cross section where we are outside the mass grid (fb): 1.760E-01
Total cross section in long cascade decays (fb): 1.096E+02
Total cross section in decays with asymmetric branches (fb): 1.630E+02
- detailed information about the missing topologies with highest cross sections. The element cross section (weight) as well as its description in bracket notation is included. If addCoverageID = True, all the elements IDs contributing to the missing topology are shown. These IDs can be traced back to the corresponding elements using the decomposition information obtained with printDecomp = True and addElementInfo = True.
================================================================================
Missing topologies with the highest cross sections (up to 10):
Sqrts (TeV) Weight (fb) Element description
8.0 1.601E+01 # [[[jet],[W]],[[jet,jet],[W]]]
Contributing elements [270, 271, 272, 273, 276, 277, 278, 279, 286, 287, 288, 289, 298, 299, 300, 301, 306, 307, 308, 309, 316, 317, 318, 319]
- detailed information about the topologies which are outside the experimental results grid. If addCoverageID = True, all the elements IDs contributing to the missing topology are shown.
================================================================================
Contributions outside the mass grid (up to 10):
Sqrts (TeV) Weight (fb) Element description
8.0 1.440E-01 # [[[jet]],[[t,t]]]
Contributing elements [29]
- information about the missing topologies with long cascade decays. The long cascade decays are classified by the initially produced mother particles. If more than one pair of mothers are contributing to the same class of elements, the full list is given in the comment. For definiteness all lists are sorted. If addCoverageID = True, all the elements IDs contributing to the missing topology are shown.
================================================================================
Missing topos: long cascade decays (up to 10 entries), sqrts = 8 TeV:
Mother1 Mother2 Weight (fb) # allMothers
1000021 2000002 3.743E+01 # [[1000021, 2000002]]
Contributing elements [582, 585, 588, 591, 594, 597, 600, 603, 606, 609, 610, 613, 616, 619, 622, 625, 628, 631, 634, 637, 638, 639, 640, 641, 642, 643, 812, 813, 814, 815, 816, 817, 818, 821, 825, 829, 832, 836, 840, 844, 848, 851, 852, 853, 857, 861, 865, 866, 869, 873, 877, 881, 885, 886, 889, 892, 893, 897, 901, 905, 906, 909, 913, 917, 921, 925, 926, 929, 932, 933, 934, 935, 936, 937, 938, 941, 944, 947, 950, 953, 956, 959, 962, 965, 966, 967, 971, 975, 979, 980, 983, 987, 991, 995, 999, 1000, 1003, 1006, 1007, 1011, 1015, 1019, 1020, 1023, 1027, 1031, 1035, 1039, 1040, 1043, 1046, 1047, 1051, 1055, 1059, 1060, 1063, 1067, 1071, 1075, 1079, 1080, 1083, 1086, 1087, 1091, 1095, 1099, 1100, 1103, 1107, 1111, 1115, 1119, 1120, 1123, 1126, 1127, 1128, 1129, 1130, 1131, 1132, 1135, 1138, 1141, 1144, 1147, 1150, 1153, 1156, 1159, 1160, 1161, 1164, 1167, 1168, 1171, 1174, 1177, 1180]
1000002 1000021 1.626E+01 # [[1000002, 1000021]]
Contributing elements [583, 586, 589, 592, 595, 598, 601, 604, 607, 611, 614, 617, 620, 623, 626, 629, 632, 635, 819, 822, 826, 830, 833, 837, 841, 845, 849, 854, 858, 862, 867, 870, 874, 878, 882, 887, 890, 894, 898, 902, 907, 910, 914, 918, 922, 927, 930, 939, 942, 945, 948, 951, 954, 957, 960, 963, 968, 972, 976, 981, 984, 988, 992, 996, 1001, 1004, 1008, 1012, 1016, 1021, 1024, 1028, 1032, 1036, 1041, 1044, 1048, 1052, 1056, 1061, 1064, 1068, 1072, 1076, 1081, 1084, 1088, 1092, 1096, 1101, 1104, 1108, 1112, 1116, 1121, 1124, 1133, 1136, 1139, 1142, 1145, 1148, 1151, 1154, 1157, 1162, 1165, 1169, 1172, 1175, 1178]
- information about the missing topologies with asymmetric decays. The asymmetric branch decays are classified by the initially produced mother particles. If more than one pair of mothers are contributing to the same class of elements, the full list is given in the comment. For definiteness all lists are sorted. If addCoverageID = True, all the elements IDs contributing to the missing topology are shown.
================================================================================
Missing topos: asymmetric branches (w/o long cascades, up to 10), sqrts = 8 TeV
Mother1 Mother2 Weight (fb) # allMothers
1000002 1000021 4.725E+01 # [[1000002, 1000021]]
Contributing elements [150, 151, 152, 153, 154, 155, 166, 168, 169, 171, 172, 174, 176, 177, 179, 181, 183, 185, 187, 189, 280, 281, 282, 283, 284, 285, 286, 287, 288, 289, 290, 291, 292, 293, 303, 304, 305, 306, 307, 308, 309, 324, 325, 326, 327, 328, 329, 330, 331, 332, 333, 341, 342, 343, 344, 345, 346, 347, 348, 349, 350, 351, 352, 353, 354, 376, 377, 378, 379, 380, 381, 382, 383, 384, 404, 405, 406, 407, 408, 409, 410, 411, 412]
Log Output¶
The log-type output is identical to the screen output, except that it is redirected to a .log file. The filename is set as the <input file>.log and stored in the output folder (see the runSModelS options).
Summary File Output¶
The summary-type output is similar to the screen output, but restricted to the list of theory predictions and model coverage. The output is printed to the file <input file>.smodels and stored in the output folder (see the runSModelS options).
Below we describe in detail the blocks contained in the summary output:
- information about the basic input parameters and the status of the run:
Input status: 1
Decomposition output status: 1 #decomposition was successful
# Input File: inputFiles/slha/gluino_squarks.slha
# maxcond = 0.2
# minmassgap = 5.
# ncpus = 1
# sigmacut = 0.03
# Database version: 1.1.1
- a list of all the theory predictions obtained and the corresponding experimental result upper limit. If expandedSummary = False only the most constraining experimental result is printed. For each theory prediction entry, the corresponding experimental result id, the signal region (data set) used (only for EM-type results) and the experimental result sqrts is printed. Furthermore, the txnames contributing to the signal cross section, the theory cross section (Theory_Value), the observed upper limit (Exp_limit), the (theory cross section)/(observed upper limit) ratio (r) and, when available, the (theory cross section)/(expected upper limit) ratio (r_expect) are also printed. For UL-type results the condition violation (see upper limit conditions) is also included. Finally, if computeStatistics = True, the \(\chi^2\) and likelihood values (for EM-type results) are printed:
#Analysis Sqrts Cond_Violation Theory_Value(fb) Exp_limit(fb) r r_expected
CMS-SUS-13-019 8.00E+00 0.0 1.773E+00 3.762E+00 4.713E-01 N/A
Signal Region: (UL)
Txnames: T2
--------------------------------------------------------------------------------
ATLAS-SUSY-2013-02 8.00E+00 0.0 6.617E+00 1.718E+01 3.851E-01 N/A
Signal Region: (UL)
Txnames: T6WW
--------------------------------------------------------------------------------
ATLAS-SUSY-2013-02 8.00E+00 0.0 5.525E-01 1.818E+00 3.039E-01 3.653E-01
Signal Region: SR2jt
Txnames: T1, T2
Chi2, Likelihood = 4.185E-02 2.542E-02
- the maximum value for the (theory cross section)/(observed upper limit) ratio. If this value is higher than 1 the input model is likely excluded by one of the experimental results (see confronting predictions)
================================================================================
The highest r value is = 0.471338470997
- summary information about the missing topologies, if testCoverage = True. The total missing topology cross section corresponds to the sum of all elements cross sections which are not tested by any experimental result. If, however, the element is constrained by one or more experimental results, but its mass is outside the efficiency or upper limit grids (see EM-type results and UL-type results), its cross section is included in the total cross section outside the grid. Finally, the elements which contribute to the total missing topology cross section are subdivided into elements with long decays or with asymmetric branches (see coverage tool for more details)
Total missing topology cross section (fb): 2.767E+02
Total cross section where we are outside the mass grid (fb): 1.760E-01
Total cross section in long cascade decays (fb): 1.096E+02
Total cross section in decays with asymmetric branches (fb): 1.630E+02
- detailed information about the missing topologies with highest cross sections. The element cross section (weight) as well as its description in bracket notation is included.
================================================================================
Missing topologies with the highest cross sections (up to 10):
Sqrts (TeV) Weight (fb) Element description
8.0 1.601E+01 # [[[jet],[W]],[[jet,jet],[W]]]
8.0 1.395E+01 # [[[jet],[jet,jet],[W]],[[jet,jet],[W]]]
- detailed information about the topologies which are outside the experimental results grid:
================================================================================
Contributions outside the mass grid (up to 10):
Sqrts (TeV) Weight (fb) Element description
8.0 1.440E-01 # [[[jet]],[[t,t]]]
8.0 3.203E-02 # [[[t],[W]],[[t],[W]]]
- information about the missing topologies with long cascade decays:
================================================================================
Missing topos: long cascade decays (up to 10 entries), sqrts = 8 TeV:
Mother1 Mother2 Weight (fb) # allMothers
1000021 2000002 3.743E+01 # [[1000021, 2000002]]
1000002 1000021 1.626E+01 # [[1000002, 1000021]]
- information about the missing topologies with asymmetric decays:
================================================================================
Missing topos: asymmetric branches (w/o long cascades, up to 10), sqrts = 8 TeV
Mother1 Mother2 Weight (fb) # allMothers
1000002 1000021 4.725E+01 # [[1000002, 1000021]]
1000021 1000021 4.324E+01 # [[1000021, 1000021]]
Python Output¶
The Python-type output is similar to the screen output, however converted to a Python dictionary. If all options are set to True, it includes information about the decomposition, the list of theory predictions and model coverage. The output is printed to the file <input file>.py and stored in the output folder (see the runSModelS options).
Below we describe in detail the dictionary keys and values contained in the Python dictionary output:
- information about the basic input parameters and the status of the run stored under the OutputStatus key:
smodelsOutput = {
'OutputStatus': {'minmassgap': 5.0, 'input file': 'inputFiles/slha/gluino_squarks.slha', 'decomposition status': 1, 'warnings': 'Input file ok', 'ncpus': 1, 'maxcond': 0.2, 'smodels version': '1.1.1', 'database version': '1.1.1', 'sigmacut': 0.03, 'file status': 1},
- a full list of the elements generated by the decomposition (if addElementList = True) stored under the Element key. Each list entry contains basic information about the elements. The list can be considerably long, so it is recommended to set addElementList to False, unless the decomposition information is required by the user.
'Element': [{'Particles': '[[], []]', 'Weights (fb)': {'xsec 8.0 TeV': 0.4808}, 'PIDs': [[[1000022], [1000022]]], 'Masses (GeV)': [[129.0], [129.0]], 'ID': 1},
{'Particles': "[[], [['W+']]]", 'Weights (fb)': {'xsec 8.0 TeV': 0.2404}, 'PIDs': [[[1000022], [1000024, 1000022]]], 'Masses (GeV)': [[129.0], [269.0, 129.0]], 'ID': 2},...]
- a list of all the theory predictions obtained for the experimental results, stored under the ExptRes key. For each list entry, the corresponding result id, the experimental result type (if UL-type result or EM-type result), the signal region (data set ID), the sqrts and luminosity, the constrained simplified models (txnames), the signal cross section (theory prediction), the corresponding observed upper limit and the maximum condition violation (see upper limit conditions) are shown. Furthermore, the masses of the elements contributing to the signal cross section and the \(\chi^2\) and likelihood values (if computeStatistics = True) are also included.
'ExptRes': [{'AnalysisSqrts (TeV)': 8, 'chi2': 0.1204, 'dataType': 'efficiencyMap',
'Mass (GeV)': [[991.3, 129.0], [865.0, 129.0]], 'maxcond': 0.0, 'expected upper limit (fb)': 0.235,
'likelihood': 0.198453, 'AnalysisID': 'ATLAS-CONF-2013-053',
'upper limit (fb)': 0.26, 'theory prediction (fb)': 8.58e-05,
'lumi (fb-1)': 20.1, 'TxNames': ['TGQbbq'], 'DataSetID': 'SRA mCT350', 'r': 3.3e-04, 'r_expected': 3.6e-04}, ...],
- a list of missing topologies (if testCoverage = True), stored under the Missed Topologies key. For each list entry, the element cross section (weight), the element IDs contributing to the topology and the element description in bracket notation is included.
'Missed Topologies': [{'weight (fb)': 16.007591747903355, 'sqrts (TeV)': 8.0, 'element IDs': [270, 271, 272,...],
'element': '[[[jet],[W]],[[jet,jet],[W]]]'},...]
- a list of topologies which are outside the experimental results grid (if testCoverage = True), stored under the Outside Grid key. For each list entry, the element cross section (weight) and the element description in bracket notation is included.
'Outside Grid': [{'weight (fb)': 0.14400311772342284, 'sqrts (TeV)': 8.0, 'element': '[[[jet]],[[t,t]]]'},...],
- a list of topologies with long cascade decays (if testCoverage = True), stored under the Long Cascades key. For each list entry, the element cross section (weight) and the PIDs of the mothers are included. The mother PIDs are given in a nested list, as more than one pair might contribute to the same class of elements.
'Long Cascades': [{'weight (fb)': 37.43420166036613, 'sqrts (TeV)': 8.0, 'mother PIDs': [[1000021, 2000002]]}, ...],
- a list of topologies with asymmetric branch decays (if testCoverage = True), stored under the Asymmetric Branches key. For each list entry, the element cross section (weight) and the PIDs of the mothers are included. The mother PIDs are given in a nested list, as more than one pair might contribute to the same class of elements.
'Asymmetric Branches': [{'weight (fb)': 47.25308267112802, 'sqrts (TeV)': 8.0, 'mother PIDs': [[1000002, 1000021]]}, ...]}
XML Output¶
The xml-type output is identical to the python output, however converted to a xml format. The output is printed to the file <input file>.xml and stored in the output folder (see the runSModelS options).
Since the output information and options are the same as described for python output, we simply show below an excerpt of the xml file to illustrate the output format:
<?xml version="1.0" ?>
<smodelsOutput>
<sqrts_TeV>8.0</sqrts_TeV>
<Masses_GeV_List>
<Masses_GeV>129.0</Masses_GeV>
</Masses_GeV_List>
<Masses_GeV_List>
<Masses_GeV>865.0</Masses_GeV>
<Masses_GeV>129.0</Masses_GeV>
</Masses_GeV_List>
</Masses_GeV_List>
<PIDs_List>
<PIDs_List>
<PIDs_List>
<PIDs>1000022</PIDs>
</PIDs_List>
<PIDs_List>
<PIDs>1000021</PIDs>
<PIDs>1000022</PIDs>
</PIDs_List>
</PIDs_List>
</PIDs_List>
<Particles>[[], [['q', 'q']]]</Particles>
<Weights_fb>
<xsec_8.0_TeV>0.0963414474763</xsec_8.0_TeV>
</Weights_fb>
</Element>
<Element>
<ID>9</ID>
<Masses_GeV_List>
<Masses_GeV_List>
<Masses_GeV>269.0</Masses_GeV>
<Masses_GeV>129.0</Masses_GeV>
</Masses_GeV_List>
</Masses_GeV_List>
<PIDs_List>
<PIDs_List>
<PIDs_List>
<PIDs>2000001</PIDs>
<PIDs>1000021</PIDs>
<PIDs>-1000024</PIDs>
<PIDs>-1000022</PIDs>
</PIDs_List>
<PIDs_List>
<PIDs>2000002</PIDs>
<PIDs>1000021</PIDs>
<PIDs>1000023</PIDs>
<PIDs>1000022</PIDs>
</PIDs_List>
</PIDs_List>
</PIDs_List>
<Particles>[[['q'], ['q', 'q'], ['W-']], [['q'], ['q', 'q'], ['higgs']]]</Particles>
<Weights_fb>
<xsec_8.0_TeV>0.102108555715</xsec_8.0_TeV>
</Weights_fb>
</Element>
</Element_List>
<ExptRes_List>
<ExptRes>
<AnalysisID>ATLAS-CONF-2013-053</AnalysisID>
SLHA Output¶
An SLHA-type output format is also available containing a summary of the theory predictions and missing topologies. The file contains the SLHA-type blocks: SModelS_Settings, SModelS_Exclusion, SModelS_Missing_Topos, SModelS_Outside_Grid, SModelS_Long_Cascade and SModelS_Asymmetric_Branches. Below we give a description of each block together with a sample output.
- information about the main input parameters:
BLOCK SModelS_Settings
0 v1.1.1 #SModelS version
1 1.1.1 #database version
2 0.2 #maximum condition violation
3 1 #compression (0 off, 1 on)
4 5. #minimum mass gap for mass compression [GeV]
5 0.03 #sigmacut [fb]
- information about the status of the input model: excluded (1), not excluded (0) or not tested (-1):
BLOCK SModelS_Exclusion
0 0 0 #output status (-1 not tested, 0 not excluded, 1 excluded)
- followed by the list of experimental results. If the model is excluded, all results with \(r\)-value greater than one are shown. If the point is not excluded, only the result with the highest \(r\)-value is displayed. For each experimental result, the Txname, the \(r\)-value, the condition violation and the experimental result ID are shown. If computeStatistics = True, the \(\chi^2\) and likelihood values for EM-type results are also printed:
1 0 T2 #txname
1 1 4.713E-01 #r value
1 2 N/A #expected r value
1 3 0.00 #condition violation
1 4 CMS-SUS-13-019 #analysis
1 5 (UL) #signal region
1 6 N/A #Chi2
1 7 N/A #Likelihood
- a list of missing topologies (up to 10) and their weights (if testCoverage = True):
BLOCK SModelS_Missing_Topos #sqrts[TeV] weight[fb] description
0 8 1.601E+01 [[[jet],[W]],[[jet,jet],[W]]]
1 8 1.395E+01 [[[jet],[jet,jet],[W]],[[jet,jet],[W]]]
2 8 9.206E+00 [[[b,t],[W]],[[jet,jet],[W]]]
- a list of topologies which are outside the experimental results grid (if testCoverage = True):
BLOCK SModelS_Outside_Grid #sqrts[TeV] weight[fb] description
0 8 1.440E-01 [[[jet]],[[t,t]]]
1 8 3.203E-02 [[[t],[W]],[[t],[W]]]
- a list of topologies with long cascade decays (if testCoverage = True):
BLOCK SModelS_Long_Cascade #Mother1 Mother2 Weight[fb] allMothers
0 1000021 2000002 3.743E+01 [[1000021,2000002]]
1 1000002 1000021 1.626E+01 [[1000002,1000021]]
- a list of topologies with asymmetric branch decays (if testCoverage = True):
BLOCK SModelS_Asymmetric_Branches #Mother1 Mother2 Weight[fb] allMothers
0 1000002 1000021 4.725E+01 [[1000002,1000021]]
1 1000021 1000021 4.324E+01 [[1000021,1000021]]
2 1000021 2000002 2.215E+01 [[1000021,2000002]]
[*] | Some of the output may change depending on the database version used. |
How To’s¶
Below a few examples are given for how to utilize SModelS and some of the SModelS tools as a Python library [*]:
- How to load the database (download the Python code
here
, IPython notebookhere
) - How to obtain experimental upper limits (download the Python code
here
, IPython notebookhere
) - How to obtain experimental efficiencies (download the Python code
here
, IPython notebookhere
) - How to compute leading order cross sections (for MSSM) (download the Python code
here
, IPython notebookhere
) - How to compute next-to-leading order cross sections (for MSSM) (download the Python code
here
, IPython notebookhere
) - How to print decomposition results (download the Python code
here
, IPython notebookhere
) - How to print theory predictions (download the Python code
here
, IPython notebookhere
) - How to compare theory predictions with experimental limits (download the Python code
here
, IPython notebookhere
) - How to compute the likelihood and chi2 for a theory predictions (download the Python code
here
, IPython notebookhere
) - How to find missing topologies (download the Python code
here
, IPython notebookhere
) - How to generate ascii graphs (download the Python code
here
, IPython notebookhere
) - How to marginalize a combined limit instead of profiling it (download the Python code
here
, IPython notebookhere
)
Examples using the Database Browser¶
- How to obtain upper limits (download the Python code
here
, IPython notebookhere
) - How to select specific results (download the Python code
here
, IPython notebookhere
)
Examples using the Interactive Plots tool¶
- How to make interactive plots (download the Python code
here
, IPython notebookhere
)
[*] | Some of the output may change depending on the database version used. |
SModelS Code Documentation¶
These pages constitute the SModelS code documentation.
Contents¶
theory package¶
Submodules¶
theory.auxiliaryFunctions module¶
-
theory.auxiliaryFunctions.
cGtr
(weightA, weightB)[source]¶ Define the auxiliary greater function.
Return a number between 0 and 1 depending on how much it is violated (0 = A > B, 1 = A << B).
Returns: XSectioList object with the values for each label.
-
theory.auxiliaryFunctions.
cSim
(*weights)[source]¶ Define the auxiliar similar function.
Return the maximum relative difference between any element weights of the list, normalized to [0,1].
Returns: XSectionList object with the values for each label.
-
theory.auxiliaryFunctions.
distance
(xmass1, xmass2)[source]¶ Define distance between two mass positions in upper limit space. The distance is defined as d = 2*|xmass1-xmass2|/(xmass1+xmass2).
Parameters: - xmass1 – upper limit value (in fb) for the mass1
- xmass2 – upper limit value (in fb) for the mass2
Returns: relative mass distance in upper limit space
-
theory.auxiliaryFunctions.
index_bisect
(inlist, el)[source]¶ Return the index where to insert item el in inlist. inlist is assumed to be sorted and a comparison function (lt or cmp) must exist for el and the other elements of the list. If el already appears in the list, inlist.insert(el) will insert just before the leftmost el already there.
-
theory.auxiliaryFunctions.
massAvg
(massList, method='weighted', weights=None)[source]¶ Compute the average mass of massList according to method.
If method=weighted but weights were not properly defined, switch method to harmonic. If massList contains a zero mass, switch method to mean.
Parameters: - method – possible values: harmonic, mean, weighted
- weights – weights of elements (only for weighted average)
theory.branch module¶
-
class
theory.branch.
Branch
(info=None)[source]¶ Bases:
object
An instance of this class represents a branch. A branch-element can be constructed from a string (e.g., (‘[b,b],[W]’).
Variables: - masses – list of masses for the intermediate states
- particles – list of particles (strings) for the final states
- PIDs – a list of the pdg numbers of the intermediate states appearing in the branch. If the branch represents more than one possible pdg list, PIDs will correspond to a nested list (PIDs = [[pid1,pid2,…],[pidA,pidB,…])
- maxWeight – weight of the branch (XSection object)
-
decayDaughter
(brDictionary, massDictionary)[source]¶ Generate a list of all new branches generated by the 1-step cascade decay of the current branch daughter.
Parameters: - brDictionary – dictionary with the decay information for all intermediate states (values are br objects, see pyslha)
- massDictionary – dictionary containing the masses for all intermediate states.
Returns: list of extended branches (Branch objects). Empty list if daughter is stable or if daughterID was not defined.
-
getLength
()[source]¶ Returns the branch length (number of R-odd particles).
Returns: length of branch (number of R-odd particles)
-
particlesMatch
(other)[source]¶ Compare two Branches for matching particles, allow for inclusive particle labels (such as the ones defined in particles.py)
Parameters: other – branch to be compared (Branch object) Returns: True if branches are equal (particles and masses match); False otherwise.
-
theory.branch.
decayBranches
(branchList, brDictionary, massDictionary, sigcut=0.00E+00 [fb])[source]¶ Decay all branches from branchList until all unstable intermediate states have decayed.
Parameters: - branchList – list of Branch() objects containing the initial mothers
- brDictionary – dictionary with the decay information for all intermediate states (values are br objects, see pyslha)
- massDictionary – dictionary containing the masses for all intermediate states.
- sigcut – minimum sigma*BR to be generated, by default sigcut = 0. (all branches are kept)
Returns: list of branches (Branch objects)
theory.clusterTools module¶
-
class
theory.clusterTools.
ElementCluster
[source]¶ Bases:
object
An instance of this class represents a cluster. This class is used to store the relevant information about a cluster of elements and to manipulate this information.
Variables: elements – list of elements in the cluster (Element objects) -
getAvgMass
()[source]¶ Return the average mass of all elements belonging to the cluster. If the cluster does not refer to a TxName (i.e. in efficiency map results) AND the cluster contains more than one element (assuming they differ in the masses), returns None.
Returns: average mass array
-
getDataType
()[source]¶ Checks to which type of data (efficiency map or upper limit) the cluster refers to. It uses the cluster.txnames attribute. If not defined, returns None :return: upperLimits or efficiencyMap (string)
-
getIDs
()[source]¶ Return list of all element IDs appearing in the cluster :return: list of element IDs
-
-
class
theory.clusterTools.
IndexCluster
(massMap=None, posMap=None, wMap=None, indices=set(), txdata=None)[source]¶ Bases:
object
An instance of this class represents a cluster storing element indices. This auxiliary class is used to store element indices and positions in upper limit space. It is only used by the clustering algorithm.
Variables: - indices – list of integers mapping the cluster elements to their position in the list (1st element -> index 0, 2nd element -> index 1,…)
- avgPosition – position in upper limit space for the cluster average mass
- massMap – dictionary with indices as keys and the corresponding element mass as values
- positionMap – dictionary with indices as keys and the corresponding element position in upper limit space as values
- weightMap – dictionary with indices as keys and the corresponding element weight as values
- txdata – TxNameData object to be used for computing distances in UL space
-
theory.clusterTools.
clusterElements
(elements, maxDist)[source]¶ Cluster the original elements according to their mass distance.
Parameters: - elements – list of elements (Element objects)
- txname – TxName object to be used for computing distances in UL space
- maxDist – maximum mass distance for clustering two elements
Returns: list of clusters (ElementCluster objects)
theory.crossSection module¶
-
class
theory.crossSection.
XSection
[source]¶ Bases:
object
An instance of this class represents a cross section.
This class is used to store the information of a single cross section (value, paritcle ids, center of mass, order and label).
order = 0 (LO), 1 (NLO) or 2 (NLL).
-
niceStr
()[source]¶ Generates a more human readable string. The string format is: Sqrts: self.info.sqrts, Weight: self.value
-
pid
¶
-
-
class
theory.crossSection.
XSectionInfo
(sqrts=None, order=None, label=None)[source]¶ Bases:
object
An instance of this class represents information regarding a cross section.
This class is used to store information of a cross section (center of mass, order and label).
-
class
theory.crossSection.
XSectionList
(infoList=None)[source]¶ Bases:
object
An instance of this class represents a list of cross sections.
This class is used to store a list of cross sections. The list is sorted by cross section, highest cross section first.
-
combineWith
(newXsecs)[source]¶ Add a new list of cross sections.
If the new cross sections already appear (have same order and sqrts), add its value to the original value, otherwise append it to the list. The particle IDs are ignored when adding cross sections. Hence, they are set to (None, None) if any cross sections are combined.
-
getDictionary
(groupBy='pids')[source]¶ Convert the list of XSection objects to a nested dictionary.
First level keys are the particles IDs (if groupBy == pids) or labels (if groupBy == labels) and values are the cross section labels or particle IDs and the cross section value.
-
getInfo
()[source]¶ Get basic info about the cross sections appearing in the list (order, value and label).
Returns: list of XSectionInfo objects
-
-
theory.crossSection.
getXsecFromLHEFile
(lhefile, addEvents=True)[source]¶ Obtain cross sections from input LHE file.
Parameters: - lhefile – LHE input file with unweighted MC events
- addEvents – if True, add cross sections with the same mothers, otherwise return the event weight for each pair of mothers
Returns: a XSectionList object
-
theory.crossSection.
getXsecFromSLHAFile
(slhafile, useXSecs=None, xsecUnit=1.00E+00 [pb])[source]¶ Obtain cross sections for pair production of R-odd particles from input SLHA file. The default unit for cross section is pb.
Parameters: - slhafile – SLHA input file with cross sections
- useXSecs – if defined enables the user to select cross sections to use. Must be a XSecInfoList object
- xsecUnit – cross section unit in the input file (must be a Unum unit)
Returns: a XSectionList object
theory.element module¶
-
class
theory.element.
Element
(info=None)[source]¶ Bases:
object
An instance of this class represents an element. This class possesses a pair of branches and the element weight (cross-section * BR).
Variables: - branches – list of branches (Branch objects)
- weight – element weight (cross-section * BR)
- motherElements – only for elements generated from a parent element by mass compression, invisible compression,etc. Holds a pair of (whence, mother element), where whence describes what process generated the element
-
checkConsistency
()[source]¶ Check if the particles defined in the element exist and are consistent with the element info.
Returns: True if the element is consistent. Print error message and exits otherwise.
-
combineMotherElements
(el2)[source]¶ Combine mother elements from self and el2 into self
Parameters: el2 – element (Element Object)
-
combinePIDs
(el2)[source]¶ Combine the PIDs of both elements. If the PIDs already appear in self, do not add them to the list.
Parameters: el2 – element (Element Object)
-
compressElement
(doCompress, doInvisible, minmassgap)[source]¶ Keep compressing the original element and the derived ones till they can be compressed no more.
Parameters: - doCompress – if True, perform mass compression
- doInvisible – if True, perform invisible compression
- minmassgap – value (in GeV) of the maximum mass difference for compression (if mass difference < minmassgap, perform mass compression)
Returns: list with the compressed elements (Element objects)
-
copy
()[source]¶ Create a copy of self. Faster than deepcopy.
Returns: copy of element (Element object)
-
getDaughters
()[source]¶ Get a pair of daughter IDs (PDGs of the last intermediate state appearing the cascade decay), i.e. [ [pdgLSP1,pdgLSP2] ] Can be a list, if the element combines several daughters: [ [pdgLSP1,pdgLSP2], [pdgLSP1’,pdgLSP2’]]
Returns: list of PDG ids
-
getEinfo
()[source]¶ Get topology info from particle string.
Returns: dictionary containing vertices and number of final states information
-
getMothers
()[source]¶ Get a pair of mother IDs (PDGs of the first intermediate state appearing the cascade decay), i.e. [ [pdgMOM1,pdgMOM2] ] Can be a list, if the element combines several mothers: [ [pdgMOM1,pdgMOM2], [pdgMOM1’,pdgMOM2’]]
Returns: list of PDG ids
-
getPIDs
()[source]¶ Get the list of IDs (PDGs of the intermediate states appearing the cascade decay), i.e. [ [[pdg1,pdg2,…],[pdg3,pdg4,…]] ]. The list might have more than one entry if the element combines different pdg lists: [ [[pdg1,pdg2,…],[pdg3,pdg4,…]], [[pdg1’,pdg2’,…],[pdg3’,pdg4’,…]], …]
Returns: list of PDG ids
-
hasTopInList
(elementList)[source]¶ Check if the element topology matches any of the topologies in the element list.
Parameters: elementList – list of elements (Element objects) Returns: True, if element topology has a match in the list, False otherwise.
-
invisibleCompress
()[source]¶ Perform invisible compression.
Returns: compressed copy of the element, if element ends with invisible particles; None, if compression is not possible
-
massCompress
(minmassgap)[source]¶ Perform mass compression.
Parameters: minmassgap – value (in GeV) of the maximum mass difference for compression (if mass difference < minmassgap -> perform mass compression) Returns: compressed copy of the element, if two masses in this element are degenerate; None, if compression is not possible;
-
particlesMatch
(other, branchOrder=False)[source]¶ Compare two Elements for matching particles only. Allow for inclusive particle labels (such as the ones defined in particles.py). If branchOrder = False, check both branch orderings.
Parameters: - other – element to be compared (Element object)
- branchOrder – If False, check both orderings, otherwise check the same branch ordering
Returns: True, if particles match; False, else;
-
setMasses
(mass, sameOrder=True, opposOrder=False)[source]¶ Set the element masses to the input mass array.
Parameters: - mass – list of masses ([[masses for branch1],[masses for branch2]])
- sameOrder – if True, set the masses to the same branch ordering If True and opposOrder=True, set the masses to the smaller of the two orderings.
- opposOrder – if True, set the masses to the opposite branch ordering. If True and sameOrder=True, set the masses to the smaller of the two orderings.
theory.exceptions module¶
theory.lheDecomposer module¶
-
theory.lheDecomposer.
decompose
(lhefile, inputXsecs=None, nevts=None, doCompress=False, doInvisible=False, minmassgap=-1.00E+00 [GeV])[source]¶ Perform LHE-based decomposition.
Parameters: - lhefile – LHE file with e.g. pythia events
- inputXsecs – xSectionList object with cross sections for the mothers appearing in the LHE file. If None, use information from file.
- nevts – (maximum) number of events used in the decomposition. If None, all events from file are processed.
- doCompress – mass compression option (True/False)
- doInvisible – invisible compression option (True/False)
- minmassgap – minimum mass gap for mass compression (only used if doCompress=True)
Returns: list of topologies (TopologyList object)
theory.lheReader module¶
-
class
theory.lheReader.
LheReader
(filename, nmax=None)[source]¶ Bases:
object
An instance of this class represents a reader for LHE files.
-
class
theory.lheReader.
Particle
[source]¶ Bases:
object
An instance of this class represents a particle.
theory.particleNames module¶
-
theory.particleNames.
elementsInStr
(instring, removeQuotes=True)[source]¶ Parse instring and return a list of elements appearing in instring. instring can also be a list of strings.
Parameters: - instring – string containing elements (e.g. “[[[‘e+’]],[[‘e-‘]]]+[[[‘mu+’]],[[‘mu-‘]]]”)
- removeQuotes – If True, it will remove the quotes from the particle labels. Set to False, if one wants to run eval on the output.
Returns: list of elements appearing in instring in string format
-
theory.particleNames.
getName
(pdg)[source]¶ Convert pdg number to particle name according to the dictionaries rOdd and rEven.
Returns: particle name (e.g. gluino, mu-, …)
-
theory.particleNames.
getPdg
(name)[source]¶ Convert a name to the pdg number according to the dictionaries rOdd and rEven.
Returns: particle pdg; None, if name could not be resolved
-
theory.particleNames.
simParticles
(plist1, plist2, useDict=True)[source]¶ Compares two lists of particle names. Allows for dictionary labels (Ex: L = l, l+ = l, l = l-,…). Ignores particle ordering inside the list
Parameters: - plist1 – first list of particle names, e.g. [‘l’,’jet’]
- plist2 – second list of particle names
- useDict – use the translation dictionary, i.e. allow e to stand for e+ or e-, l+ to stand for e+ or mu+, etc
Returns: True/False if the particles list match (ignoring order)
theory.slhaDecomposer module¶
-
theory.slhaDecomposer.
decompose
(slhafile, sigcut=1.00E-01 [fb], doCompress=False, doInvisible=False, minmassgap=-1.00E+00 [GeV], useXSecs=None)[source]¶ Perform SLHA-based decomposition.
Parameters: - sigcut – minimum sigma*BR to be generated, by default sigcut = 0.1 fb
- doCompress – turn mass compression on/off
- doInvisible – turn invisible compression on/off
- minmassgap – maximum value (in GeV) for considering two R-odd particles degenerate (only revelant for doCompress=True )
- useXSecs – optionally a dictionary with cross sections for pair production, by default reading the cross sections from the SLHA file.
Returns: list of topologies (TopologyList object)
theory.theoryPrediction module¶
-
theoryPrediction.
_getElementsFrom
(smsTopList, dataset)[source]¶ Get elements that belong to any of the TxNames in dataset (appear in any of constraints in the result). Loop over all elements in smsTopList and returns a copy of the elements belonging to any of the constraints (i.e. have efficiency != 0). The copied elements have their weights multiplied by their respective efficiencies.
Parameters: - dataset – Data Set to be considered (DataSet object)
- smsTopList – list of topologies containing elements (TopologyList object)
Returns: list of elements (Element objects)
-
class
theory.theoryPrediction.
TheoryPrediction
[source]¶ Bases:
object
An instance of this class represents the results of the theory prediction for an analysis.
Variables: - analysis – holds the analysis (ULanalysis or EManalysis object) to which the prediction refers
- xsection – xsection of the theory prediction (relevant cross section to be compared with the experimental limits). For EM-type analyses, it corresponds to sigma*eff, for UL-type analyses, eff is considered to be 1. It is a XSection object.
- conditions – list of values for the analysis conditions (only for upper limit-type analysis, e.g. analysis=ULanalysis)
- mass – mass of the cluster to which the theory prediction refers (only for upper limit-type analysis, e.g. analysis=ULanalysis)
-
computeStatistics
(marginalize=False, deltas_rel=0.2)[source]¶ Compute the likelihood, chi2 and expected upper limit for this theory prediction. The resulting values are stored as the likelihood and chi2 attributes. :param marginalize: if true, marginalize nuisances. Else, profile them. :param deltas_rel: relative uncertainty in signal (float). Default value is 20%.
-
getUpperLimit
(expected=False, deltas_rel=0.2)[source]¶ Get the upper limit on sigma*eff. For UL-type results, use the UL map. For EM-Type returns the corresponding dataset (signal region) upper limit. For combined results, returns the upper limit on the total sigma*eff (for all signal regions/datasets).
Parameters: - expected – return expected Upper Limit, instead of observed.
- deltas_rel – relative uncertainty in signal (float). Default value is 20%.
Returns: upper limit (Unum object)
-
class
theory.theoryPrediction.
TheoryPredictionList
(theoryPredictions=None)[source]¶ Bases:
object
An instance of this class represents a collection of theory prediction objects.
Variables: _theoryPredictions – list of TheoryPrediction objects
-
theory.theoryPrediction.
theoryPredictionsFor
(expResult, smsTopList, maxMassDist=0.2, useBestDataset=True, combinedResults=True, marginalize=False, deltas_rel=0.2)[source]¶ Compute theory predictions for the given experimental result, using the list of elements in smsTopList. For each Txname appearing in expResult, it collects the elements and efficiencies, combine the masses (if needed) and compute the conditions (if exist).
Parameters: - expResult – expResult to be considered (ExpResult object)
- smsTopList – list of topologies containing elements (TopologyList object)
- maxMassDist – maximum mass distance for clustering elements (float)
- useBestDataset – If True, uses only the best dataset (signal region). If False, returns predictions for all datasets (if combinedResults is False), or only the combinedResults (if combinedResults is True).
- combinedResults – add theory predictions that result from combining datasets.
- marginalize – If true, marginalize nuisances. If false, profile them.
- deltas_rel – relative uncertainty in signal (float). Default value is 20%.
Returns: a TheoryPredictionList object containing a list of TheoryPrediction objects
theory.topology module¶
-
class
theory.topology.
Topology
(elements=None)[source]¶ Bases:
object
An instance of this class represents a topology.
Variables: - vertnumb – list with number of vertices in each branch
- verparts – list with number of final states in each branch
- elementList – list of Element objects with this common topology
-
addElement
(newelement)[source]¶ Add an Element object to the elementList.
For all the pre-existing elements, which match the new element, add weight. If no pre-existing elements match the new one, add it to the list. OBS: newelement MUST ALREADY BE SORTED (see element.sort())
Parameters: newelement – element to be added (Element object) Returns: True, if the element was added. False, otherwise
-
checkConsistency
()[source]¶ Check if the all the elements in elementList are consistent with the topology (same number of vertices and final states)
Returns: True if all the elements are consistent. Print error message and exits otherwise.
-
describe
()[source]¶ Create a detailed description of the topology.
Returns: list of strings with a description of the topology
-
class
theory.topology.
TopologyList
(topologies=[])[source]¶ Bases:
object
An instance of this class represents an iterable collection of topologies.
Variables: topos – list of topologies (Topology objects) -
add
(newTopology)[source]¶ Check if elements in newTopology matches an entry in self.topos.
If it does, add weight. If the same topology exists, but not the same element, add element. If neither element nor topology exist, add the new topology and all its elements.
Parameters: newTopology – Topology object
-
addElement
(newelement)[source]¶ Add an Element object to the corresponding topology in the list. If the element topology does not match any of the topologies in the list, create a new topology and insert it in the list. If the element topology already exists, add it to the respective topology. :parameter newelement: element to be added (Element object) :returns: True, if the element was added. False, otherwise
-
compressElements
(doCompress, doInvisible, minmassgap)[source]¶ Compress all elements in the list and included the compressed elements in the topology list.
Parameters: - doCompress – if True, perform mass compression
- doInvisible – if True, perform invisible compression
- minmassgap – value (in GeV) of the maximum mass difference for compression (if mass difference < minmassgap, perform mass compression)
-
Module contents¶
experiment package¶
Submodules¶
experiment.databaseObj module¶
-
class
experiment.databaseObj.
Database
(base=None, force_load=None, discard_zeroes=True, progressbar=False, subpickle=True)[source]¶ Bases:
object
Database object. Holds a list of ExpResult objects.
Variables: - base – path to the database (string)
- force_load – force loading the text database (“txt”), or binary database (“pcl”), dont force anything if None
- expResultList – list of ExpResult objects
-
base
¶ This is the path to the base directory.
-
checkPathName
(path, discard_zeroes)[source]¶ checks the path name, returns the base directory and the pickle file name. If path starts with http or ftp, fetch the description file and the database. returns the base directory and the pickle file name
-
createBinaryFile
(filename=None)[source]¶ create a pcl file from the text database, potentially overwriting an old pcl file.
-
databaseVersion
¶ The version of the database, read from the ‘version’ file.
-
fetchFromScratch
(path, store, discard_zeroes)[source]¶ fetch database from scratch, together with description. :param store: filename to store json file.
-
getExpResults
(analysisIDs=['all'], datasetIDs=['all'], txnames=['all'], dataTypes=['all'], useSuperseded=False, useNonValidated=False, onlyWithExpected=False)[source]¶ Returns a list of ExpResult objects.
Each object refers to an analysisID containing one (for UL) or more (for Efficiency maps) dataset (signal region) and each dataset containing one or more TxNames. If analysisIDs is defined, returns only the results matching one of the IDs in the list. If dataTypes is defined, returns only the results matching a dataType in the list. If datasetIDs is defined, returns only the results matching one of the IDs in the list. If txname is defined, returns only the results matching one of the Tx names in the list.
Parameters: - analysisID – list of analysis ids ([CMS-SUS-13-006,…]). Can be wildcarded with usual shell wildcards: * ? [<letters>] Furthermore, the centre-of-mass energy can be chosen as suffix, e.g. “:13*TeV”. Note that the asterisk in the suffix is not a wildcard.
- datasetIDs – list of dataset ids ([ANA-CUT0,…]). Can be wildcarded with usual shell wildcards: * ? [<letters>]
- txnames – list of txnames ([TChiWZ,…]). Can be wildcarded with usual shell wildcards: * ? [<letters>]
- dataTypes – dataType of the analysis (all, efficiencyMap or upperLimit) Can be wildcarded with usual shell wildcards: * ? [<letters>]
- useSuperseded – If False, the supersededBy results will not be included
- useNonValidated – If False, the results with validated = False will not be included
- onlyWithExpected – Return only those results that have expected values also. Note that this is trivially fulfilled for all efficiency maps.
Returns: list of ExpResult objects or the ExpResult object if the list contains only one result
-
inNotebook
()[source]¶ Are we running within a notebook? Has an effect on the progressbar we wish to use.
-
loadBinaryFile
(lastm_only=False)[source]¶ Load a binary database, returning last modified, file count, database.
Parameters: lastm_only – if true, the database itself is not read. Returns: database object, or None, if lastm_only == True.
experiment.datasetObj module¶
-
class
experiment.datasetObj.
CombinedDataSet
(expResult)[source]¶ Bases:
object
Holds the information for a combined dataset (used for combining multiple datasets).
-
combinedLikelihood
(nsig, marginalize=False, deltas_rel=0.2)[source]¶ Computes the (combined) likelihood to observe nobs events, given a predicted signal “nsig”, with nsig being a vector with one entry per dataset. nsig has to obey the datasetOrder. Deltas is the error on the signal. :param nsig: predicted signal (list) :param deltas_rel: relative uncertainty in signal (float). Default value is 20%.
Returns: likelihood to observe nobs events (float)
-
getCombinedUpperLimitFor
(nsig, expected=False, deltas_rel=0.2)[source]¶ Get combined upper limit.
Parameters: - nsig – list of signal events in each signal region/dataset. The list should obey the ordering in globalInfo.datasetOrder.
- expected – return expected, not observed value
- deltas_rel – relative uncertainty in signal (float). Default value is 20%.
Returns: upper limit on sigma*eff
-
getDataSet
(datasetID)[source]¶ Returns the dataset with the corresponding dataset ID. If the dataset is not found, returns None.
Parameters: datasetID – dataset ID (string) Returns: DataSet object if found, otherwise None.
-
totalChi2
(nsig, marginalize=False, deltas_rel=0.2)[source]¶ Computes the total chi2 for a given number of observed events, given a predicted signal “nsig”, with nsig being a vector with one entry per dataset. nsig has to obey the datasetOrder. Deltas is the error on the signal efficiency. :param nsig: predicted signal (list) :param deltas_rel: relative uncertainty in signal (float). Default value is 20%.
Returns: chi2 (float)
-
-
class
experiment.datasetObj.
DataSet
(path=None, info=None, createInfo=True, discard_zeroes=True)[source]¶ Bases:
object
Holds the information to a data set folder (TxName objects, dataInfo,…)
-
checkForRedundancy
()[source]¶ In case of efficiency maps, check if any txnames have overlapping constraints. This would result in double counting, so we dont allow it.
-
chi2
(nsig, deltas_rel=0.2, marginalize=False)[source]¶ Computes the chi2 for a given number of observed events “nobs”, given number of signal events “nsig”, and error on signal “deltas”. nobs, expectedBG and bgError are part of dataInfo. :param nsig: predicted signal (float) :param deltas_rel: relative uncertainty in signal (float). Default value is 20%. :param marginalize: if true, marginalize nuisances. Else, profile them. :return: chi2 (float)
-
getAttributes
(showPrivate=False)[source]¶ Checks for all the fields/attributes it contains as well as the attributes of its objects if they belong to smodels.experiment.
Parameters: showPrivate – if True, also returns the protected fields (_field) Returns: list of field names (strings)
-
getEfficiencyFor
(txname, mass)[source]¶ convenience function. same as self.getTxName(txname).getEfficiencyFor(m)
-
getSRUpperLimit
(alpha=0.05, expected=False, compute=False, deltas_rel=0.2)[source]¶ Computes the 95% upper limit on the signal*efficiency for a given dataset (signal region). Only to be used for efficiency map type results.
Parameters: - alpha – Can be used to change the C.L. value. The default value is 0.05 (= 95% C.L.)
- expected – Compute expected limit ( i.e. Nobserved = NexpectedBG )
- deltas_rel – relative uncertainty in signal (float). Default value is 20%.
- compute – If True, the upper limit will be computed from expected and observed number of events. If False, the value listed in the database will be used instead.
Returns: upper limit value
-
getUpperLimitFor
(mass=None, expected=False, txnames=None, compute=False, alpha=0.05, deltas_rel=0.2)[source]¶ Returns the upper limit for a given mass and txname. If the dataset hold an EM map result the upper limit is independent of the input txname or mass.
Parameters: - txname – TxName object or txname string (only for UL-type results)
- mass – Mass array with units (only for UL-type results)
- alpha – Can be used to change the C.L. value. The default value is 0.05 (= 95% C.L.) (only for efficiency-map results)
- deltas_rel – relative uncertainty in signal (float). Default value is 20%.
- expected – Compute expected limit, i.e. Nobserved = NexpectedBG (only for efficiency-map results)
- compute – If True, the upper limit will be computed from expected and observed number of events. If False, the value listed in the database will be used instead.
Returns: upper limit (Unum object)
-
getValuesFor
(attribute=None)[source]¶ Returns a list for the possible values appearing in the DataSet for the required attribute.
Parameters: attribute – name of a field in the database (string). If not defined it will return a dictionary with all fields and their respective values Returns: list of values
-
likelihood
(nsig, deltas_rel=0.2, marginalize=False)[source]¶ Computes the likelihood to observe nobs events, given a predicted signal “nsig”, assuming “deltas” error on the signal efficiency. The values observedN, expectedBG, and bgError are part of dataInfo. :param nsig: predicted signal (float) :param deltas_rel: relative uncertainty in signal (float). Default value is 20%. :param marginalize: if true, marginalize nuisances. Else, profile them. :returns: likelihood to observe nobs events (float)
-
experiment.exceptions module¶
experiment.expResultObj module¶
-
class
experiment.expResultObj.
ExpResult
(path=None, discard_zeroes=True)[source]¶ Bases:
object
Object containing the information and data corresponding to an experimental result (experimental conference note or publication).
Variables: - path – path to the experimental result folder (i.e. ATLAS-CONF-2013-047)
- globalInfo – Info object holding the data in <path>/globalInfo.txt
- datasets – List of DataSet objects corresponding to the dataset folders in <path>
-
getAttributes
(showPrivate=False)[source]¶ Checks for all the fields/attributes it contains as well as the attributes of its objects if they belong to smodels.experiment.
Parameters: showPrivate – if True, also returns the protected fields (_field) Returns: list of field names (strings)
-
getEfficiencyFor
(txname, mass, dataset=None)[source]¶ Convenience function. Get the efficiency for a specific dataset for a a specific txname. Equivalent to: self.getDataset ( dataset ).getEfficiencyFor ( txname, mass )
-
getTxnameWith
(restrDict={})[source]¶ Returns a list of TxName objects satisfying the restrictions. The restrictions specified as a dictionary.
Parameters: restrDict – dictionary containing the fields and their allowed values. E.g. {‘txname’ : ‘T1’, ‘axes’ : ….} The dictionary values can be single entries or a list of values. For the fields not listed, all values are assumed to be allowed. Returns: list of TxName objects if more than one txname matches the selection criteria or a single TxName object, if only one matches the selection.
-
getUpperLimitFor
(dataID=None, alpha=0.05, expected=False, txname=None, mass=None, compute=False)[source]¶ Computes the 95% upper limit (UL) on the signal cross section according to the type of result. For an Efficiency Map type, returns the UL for the signal*efficiency for the given dataSet ID (signal region). For an Upper Limit type, returns the UL for the signal*BR for the given mass array and Txname.
Parameters: - dataID – dataset ID (string) (only for efficiency-map type results)
- alpha – Can be used to change the C.L. value. The default value is 0.05 (= 95% C.L.) (only for efficiency-map results)
- expected – Compute expected limit, i.e. Nobserved = NexpectedBG (only for efficiency-map results)
- txname – TxName object or txname string (only for UL-type results)
- mass – Mass array with units (only for UL-type results)
- compute – If True, the upper limit will be computed from expected and observed number of events. If False, the value listed in the database will be used instead.
Returns: upper limit (Unum object)
-
getValuesFor
(attribute=None)[source]¶ Returns a list for the possible values appearing in the ExpResult for the required attribute (sqrts,id,constraint,…). If there is a single value, returns the value itself.
Parameters: attribute – name of a field in the database (string). If not defined it will return a dictionary with all fields and their respective values Returns: list of values or value
experiment.infoObj module¶
-
class
experiment.infoObj.
Info
(path=None)[source]¶ Bases:
object
Holds the meta data information contained in a .txt file (luminosity, sqrts, experimentID,…). Its attributes are generated according to the lines in the .txt file which contain “info_tag: value”.
Variables: path – path to the .txt file
experiment.metaObj module¶
-
class
experiment.metaObj.
Meta
(pathname, discard_zeroes=None, mtime=None, filecount=None, hasFastLim=None, databaseVersion=None, format_version=201, python='3.6.2 (default, Oct 19 2017, 17:44:33) n[GCC 5.4.0 20160609]')[source]¶ Bases:
object
-
current_version
= 201¶ The Meta object holds all meta information regarding the database, like number of analyses, last time of modification, … This info is needed to understand if we have to re-pickle.
-
determineLastModified
(force=False)[source]¶ compute the last modified timestamp, plus count number of files. Only if text db
-
lastModifiedSubDir
(subdir)[source]¶ Return the last modified timestamp of subdir (working recursively) plus the number of files.
Parameters: - subdir – directory name that is checked
- lastm – the most recent timestamp so far, plus number of files
Returns: the most recent timestamp, and the number of files
-
needsUpdate
(current)[source]¶ do we need an update, with respect to <current>. so <current> is the text database, <self> the pcl.
-
experiment.txnameObj module¶
-
class
experiment.txnameObj.
Delaunay1D
(data)[source]¶ Bases:
object
Uses a 1D data array to interpolate the data. The attribute simplices is a list of N-1 pair of ints with the indices of the points forming the simplices (e.g. [[0,1],[1,2],[3,4],…]).
-
checkData
(data)[source]¶ Define the simplices according to data. Compute and store the transformation matrix and simplices self.point.
-
find_index
(xlist, x)[source]¶ Efficient way to find x in a list. Returns the index (i) of xlist such that xlist[i] < x <= xlist[i+1]. If x > max(xlist), returns the length of the list. If x < min(xlist), returns 0. vertices = np.take(self.tri.simplices, simplex, axis=0) temp = np.take(self.tri.transform, simplex, axis=0) d=temp.shape[2] delta = uvw - temp[:, d]
Parameters: - xlist – List of x-type objects
- x – object to be searched for.
Returns: Index of the list such that xlist[i] < x <= xlist[i+1].
-
-
class
experiment.txnameObj.
TxName
(path, globalObj, infoObj)[source]¶ Bases:
object
Holds the information related to one txname in the Txname.txt file (constraint, condition,…) as well as the data.
-
addInfo
(tag, value)[source]¶ Adds the info field labeled by tag with value value to the object.
Parameters: - tag – information label (string)
- value – value for the field in string format
-
getEfficiencyFor
(mass)[source]¶ For upper limit results, checks if the input mass falls inside the upper limit grid. If it does, returns efficiency = 1, else returns efficiency = 0. For efficiency map results, checks if the mass falls inside the efficiency map grid. If it does, returns the corresponding efficiency value, else returns efficiency = 0.
Parameters: element – Element object Returns: efficiency (float)
-
getInfo
(infoLabel)[source]¶ Returns the value of info field.
Parameters: infoLabel – label of the info field (string). It must be an attribute of the TxNameInfo object
-
getValueFor
(massarray, expected=False)[source]¶ Access txnameData and txnameDataExp to get value for massarray.
Parameters: - massarray – mass array values (with units), i.e. [[100*GeV,10*GeV],[100*GeV,10*GeV]]
- expected – query self.txnameDataExp
-
hasElementAs
(element)[source]¶ Verify if the conditions or constraint in Txname contains the element. Check both branch orderings.
Parameters: element – Element object Returns: A copy of the element on the correct branch ordering appearing in the Txname constraint or condition.
-
-
class
experiment.txnameObj.
TxNameData
(value, datatag, Id, accept_errors_upto=0.05)[source]¶ Bases:
object
Holds the data for the Txname object. It holds Upper limit values or efficiencies.
-
checkRemovableVertices
()[source]¶ check if any of the vertices in the triangulation is removable, because all adjacent simplices are zero-only
-
getValueFor
(massarray)[source]¶ Interpolates the value and returns the UL or efficiency for the respective massarray
Parameters: massarray – mass array values (with units), i.e. [[100*GeV,10*GeV],[100*GeV,10*GeV]]
-
Module contents¶
tools package¶
Submodules¶
tools.asciiGraph module¶
tools.caching module¶
tools.colors module¶
tools.coverage module¶
-
class
tools.coverage.
Uncovered
(topoList, sumL=True, sumJet=True, sqrts=None)[source]¶ Bases:
object
Object collecting all information of non-tested/covered elements :ivar topoList: sms topology list :ivar sumL: if true, sum up electron and muon to lepton, for missing topos :ivar sumJet: if true, sum up jets, for missing topos :ivar sqrts: Center of mass energy. If defined it will only consider cross-sections for this value. Otherwise the highest sqrts value will be used.
-
fill
(topoList)[source]¶ Check all elements, categorise those not tested / missing, classify long cascade decays and asymmetric branches Fills all corresponding objects :ivar topoList: sms topology list
-
getAllMothers
(topoList)[source]¶ Find all IDs of mother elements, only most compressed element can be missing topology :ivar topoList: sms topology list
-
getMissingX
(el)[source]¶ Calculate total missing cross section of element, by recursively checking if mothers are covered :ivar el: Element :returns: missing cross section in fb as number
-
getMissingXsec
(sqrts=None)[source]¶ Calculate total missing topology cross section at sqrts. If no sqrts is given use self.sqrts :ivar sqrts: sqrts
-
getOutsideX
(el)[source]¶ Calculate total outside grid cross section of element, by recursively checking if mothers are covered :ivar el: Element :returns: missing cross section in fb as number
-
-
class
tools.coverage.
UncoveredClass
(motherPIDs, el)[source]¶ Bases:
object
Object collecting all elements contributing to the same uncovered class, defined by the mother PIDs. :ivar motherPIDs: PID of initially produces particles, sorted and without charge information :ivar el: Element
-
class
tools.coverage.
UncoveredClassifier
[source]¶ Bases:
object
Object collecting elements with long cascade decays or asymmetric branches. Objects are grouped according to the initially produced particle PID pair.
-
addToClasses
(el)[source]¶ Add Element in corresponding UncoveredClass, defined by mother PIDs. If no corresponding class in self.classes, add new UncoveredClass :ivar el: Element
-
-
class
tools.coverage.
UncoveredList
(sumL, sumJet, sqrts)[source]¶ Bases:
object
Object to find and collect UncoveredTopo objects, plus printout functionality :ivar sumL: if true sum electrons and muons to leptons :ivar sumJet: if true, sum up jets :ivar sqrts: sqrts, for printout
-
addToTopos
(el)[source]¶ adds an element to the list of missing topologies if the element contributes to a missing topology that is already in the list, add weight to topology :parameter el: element to be added
-
tools.crashReport module¶
-
class
tools.crashReport.
CrashReport
[source]¶ Bases:
object
Class that handles all crash report information.
-
createCrashReportFile
(inputFileName, parameterFileName)[source]¶ Create a new SModelS crash report file.
A SModelS crash report file contains:
- a timestamp
- SModelS version
- platform information (CPU architecture, operating system, …)
- Python version
- stack trace
- input file name
- input file content
- parameter file name
- parameter file content
Parameters: - inputFileName – relative location of the input file
- parameterFileName – relative location of the parameter file
-
tools.databaseBrowser module¶
-
class
tools.databaseBrowser.
Browser
(database, force_txt=False)[source]¶ Bases:
object
Browses the database, exits if given path does not point to a valid smodels-database. Browser can be restricted to specified run or experiment.
-
getAttributes
(showPrivate=False)[source]¶ Checks for all the fields/attributes it contains as well as the attributes of its objects if they belong to smodels.experiment.
Parameters: showPrivate – if True, also returns the protected fields (_field) Returns: list of field names (strings)
-
getEfficiencyFor
(expid, dataset, txname, massarray)[source]¶ Get an efficiency for the given experimental id, the dataset name, the txname, and the massarray. Can only be used for EfficiencyMap-type experimental results. Interpolation is done, if necessary.
Parameters: - expid – experimental id (string)
- dataset – dataset name (string)
- txname – txname (string).
- massarray – list of masses with units, e.g. [[ 400.*GeV, 100.*GeV],[400.*GeV, 100.*GeV]]
Returns: efficiency
-
getULFor
(expid, txname, massarray, expected=False)[source]¶ Get an upper limit for the given experimental id, the txname, and the massarray. Can only be used for UL experimental results. Interpolation is done, if necessary.
Parameters: - expid – experimental id (string)
- txname – txname (string). ONLY required for upper limit results
- massarray – list of masses with units, e.g. [[ 400.*GeV, 100.*GeV],[400.*GeV, 100.*GeV]]
- expected – If true, return expected upper limit, otherwise return observed upper limit.
Returns: upper limit [fb]
-
getULForSR
(expid, datasetID)[source]¶ Get an upper limit for the given experimental id and dataset (signal region). Can only be used for efficiency-map results. :param expid: experimental id (string) :param datasetID: string defining the dataset id, e.g. ANA5-CUT3. :return: upper limit [fb]
-
getValuesFor
(attribute=None, expResult=None)[source]¶ Returns a list for the possible values appearing in the database for the required attribute (sqrts,id,constraint,…).
Parameters: - attribute – name of a field in the database (string). If not defined it will return a dictionary with all fields and their respective values
- expResult – if defined, restricts the list to the corresponding expResult. Must be an ExpResult object.
Returns: list of values
-
loadAllResults
()[source]¶ Saves all the results from database to the _selectedExpResults. Can be used to restore all results to _selectedExpResults.
-
selectExpResultsWith
(**restrDict)[source]¶ Loads the list of the experimental results (pair of InfoFile and DataFile) satisfying the restrictions to the _selectedExpResults. The restrictions specified as a dictionary.
Parameters: restrDict – selection fields and their allowed values. E.g. lumi = [19.4/fb, 20.3/fb], txName = ‘T1’,….} The values can be single entries or a list of values. For the fields not listed, all values are assumed to be allowed.
-
tools.externalPythonTools module¶
tools.interactivePlots module¶
tools.interactivePlotsHelpers module¶
tools.ioObjects module¶
-
class
tools.ioObjects.
FileStatus
[source]¶ Bases:
object
Object to run several checks on the input file. It holds an LheStatus (SlhaStatus) object if inputType = lhe (slha)
-
class
tools.ioObjects.
LheStatus
(filename)[source]¶ Bases:
object
Object to check if input lhe file contains errors.
Variables: filename – path to input LHE file
-
class
tools.ioObjects.
OutputStatus
(status, inputFile, parameters, databaseVersion)[source]¶ Bases:
object
Object that holds all status information and has a predefined printout.
-
class
tools.ioObjects.
Qnumbers
(pid)[source]¶ Bases:
object
An instance of this class represents quantum numbers.
Get quantum numbers (spin*2, electrical charge*3, color dimension) from qNumbers.
-
class
tools.ioObjects.
ResultList
(theoPredictionsList=[], maxcond=1.0)[source]¶ Bases:
object
Class that collects a list of theory predictions plus the corresponding upper limits.
-
addTheoPrediction
(theoPred, maxcond)[source]¶ Add a result to the theoryPredictions, unless it violates maxcond.
Parameters: - theoPred – a Theory Prediction object to be added to ResultList
- maxcond – maximum condition violation
-
getBestExpected
()[source]¶ Find EM result with the highest expected R vaue. :returns: Theory Prediction object
-
-
class
tools.ioObjects.
SlhaStatus
(filename, maxDisplacement=0.01, sigmacut=3.00E-02 [fb], checkLSP=True, findMissingDecayBlocks=True, findIllegalDecays=False, checkXsec=True, findLonglived=True)[source]¶ Bases:
object
An instance of this class represents the status of an SLHA file. The output status is: = 0 : the file is not checked, = 1: the check is ok = -1: case of a physical problem, e.g. charged LSP, = -2: case of formal problems, e.g. no cross sections
-
degenerateChi
()[source]¶ Check if chi01 is lsp and chipm1 is NLSP. If so, check mass splitting. This function is not used, the limit is arbitrary.
-
deltaMass
(pid1, pid2)[source]¶ Calculate mass splitting between particles with pid1 and pid2.
Returns: mass difference
-
emptyDecay
(pid)[source]¶ Check if any decay is listed for the particle with pid
Parameters: pid – PID number of particle to be checked Returns: True if the decay block is missing or if it is empty, None otherwise
-
evaluateStatus
()[source]¶ Get status summary from all performed checks.
Returns: a status flag and a message for explanation
-
findIllegalDecay
(findIllegal)[source]¶ Find decays for which the sum of daughter masses excels the mother mass
Parameters: findIllegal – True if check should be run Returns: status flag and message
-
findLSP
(returnmass=None)[source]¶ Find lightest particle (not in rEven).
Returns: pid, mass of the lsp, if returnmass == True
-
findLonglivedParticles
(findLonglived)[source]¶ Find meta-stable particles that decay to visible particles and stable charged particles.
Returns: status flag, message
-
findMissingDecayBlocks
(findMissingBlocks)[source]¶ For all non-rEven particles listed in mass block, check if decay block is written
Returns: status flag and message
-
findNLSP
(returnmass=None)[source]¶ Find second lightest particle (not in rEven).
Returns: pid ,mass of the NLSP, if returnmass == True
-
getLifetime
(pid, ctau=False)[source]¶ Compute lifetime from decay-width for a particle with pid.
Parameters: - pid – PID of particle
- ctau – set True to multiply lifetime by c
Returns: lifetime
-
hasXsec
(checkXsec)[source]¶ Check if XSECTION table is present in the slha file.
Parameters: checkXsec – set True to run the check Returns: status flag, message
-
sumBR
(pid)[source]¶ Calculate the sum of all branching ratios for particle with pid.
Parameters: pid – PID of particle Returns: sum of branching ratios as given in the decay table for pid
-
tools.modelTester module¶
-
tools.modelTester.
getAllInputFiles
(inFile)[source]¶ Given inFile, return list of all input files
Parameters: inFile – Path to input file or directory containing input files Returns: List of all input files, and the directory name
-
tools.modelTester.
getParameters
(parameterFile)[source]¶ Read parameter file, exit in case of errors
Parameters: parameterFile – Path to parameter File Returns: ConfigParser read from parameterFile
-
tools.modelTester.
loadDatabase
(parser, db)[source]¶ Load database
Parameters: - parser – ConfigParser with path to database
- db – binary database object. If None, then database is loaded, according to databasePath. If True, then database is loaded, and text mode is forced.
Returns: database object, database version
-
tools.modelTester.
loadDatabaseResults
(parser, database)[source]¶ Load database entries specified in parser
Parameters: - parser – ConfigParser, containing analysis and txnames selection
- database – Database object
Returns: List of experimental results
-
tools.modelTester.
runSetOfFiles
(inputFiles, outputDir, parser, databaseVersion, listOfExpRes, timeout, development, parameterFile, jobnr)[source]¶ Loop over all input files in inputFiles with testPoint
Parameters: - inputFiles – list of input files to be tested
- outputDir – path to directory where output is be stored
- parser – ConfigParser storing information from parameter.ini file
- databaseVersion – Database version (printed to output file)
- listOfExpRes – list of ExpResult objects to be considered
- development – turn on development mode (e.g. no crash report)
- parameterFile – parameter file, for crash reports
- jobnr – number of process, in parallel mode. mostly for debugging.
Returns: printers output
-
tools.modelTester.
runSingleFile
(inputFile, outputDir, parser, databaseVersion, listOfExpRes, timeout, development, parameterFile)[source]¶ Call testPoint on inputFile, write crash report in case of problems
Parameters: - inputFile – path to input file
- outputDir – path to directory where output is be stored
- parser – ConfigParser storing information from parameter.ini file
- databaseVersion – Database version (printed to output file)
- listOfExpRes – list of ExpResult objects to be considered
- crashReport – if True, write crash report in case of problems
- timeout – set a timeout for one model point (0 means no timeout)
Returns: output of printers
-
tools.modelTester.
testPoint
(inputFile, outputDir, parser, databaseVersion, listOfExpRes)[source]¶ Test model point defined in input file (running decomposition, check results, test coverage)
Parameters: - inputFile – path to input file
- outputDir – path to directory where output is be stored
- parser – ConfigParser storing information from parameters file
- databaseVersion – Database version (printed to output file)
- listOfExpRes – list of ExpResult objects to be considered
Returns: output of printers
-
tools.modelTester.
testPoints
(fileList, inDir, outputDir, parser, databaseVersion, listOfExpRes, timeout, development, parameterFile)[source]¶ Loop over all input files in fileList with testPoint, using ncpus CPUs defined in parser
Parameters: - fileList – list of input files to be tested
- inDir – path to directory where input files are stored
- outputDir – path to directory where output is stored
- parser – ConfigParser storing information from parameter.ini file
- databaseVersion – Database version (printed to output files)
- listOfExpRes – list of ExpResult objects to be considered
- timeout – set a timeout for one model point (0 means no timeout)
- development – turn on development mode (e.g. no crash report)
- parameterFile – parameter file, for crash reports
Returns: printer(s) output, if not run in parallel mode
tools.nllFastWrapper module¶
-
class
tools.nllFastWrapper.
NllFastWrapper
(sqrts, nllfastVersion, testParams, testCondition)[source]¶ Bases:
smodels.tools.wrapperBase.WrapperBase
An instance of this class represents the installation of nllfast.
-
class
tools.nllFastWrapper.
NllFastWrapper13
[source]¶ Bases:
tools.nllFastWrapper.NllFastWrapper
An instance of this class represents the installation of nllfast 8.
-
class
tools.nllFastWrapper.
NllFastWrapper7
[source]¶ Bases:
tools.nllFastWrapper.NllFastWrapper
An instance of this class represents the installation of nllfast 7.
-
class
tools.nllFastWrapper.
NllFastWrapper8
[source]¶ Bases:
tools.nllFastWrapper.NllFastWrapper
An instance of this class represents the installation of nllfast 8.
tools.physicsUnits module¶
tools.printer module¶
-
class
tools.printer.
BasicPrinter
(output, filename)[source]¶ Bases:
object
Super class to handle the basic printing methods
-
addObj
(obj)[source]¶ Adds object to the Printer.
Parameters: obj – A object to be printed. Must match one of the types defined in formatObj Returns: True if the object has been added to the output. If the object does not belong to the pre-defined printing list toPrint, returns False.
-
filename
¶
-
-
class
tools.printer.
MPrinter
[source]¶ Bases:
object
Master Printer class to handle the Printers (one printer/output type)
-
addObj
(obj)[source]¶ Adds the object to all its Printers:
Parameters: obj – An object which can be handled by the Printers.
-
flush
()[source]¶ Ask all printers to write the output and clear their cache. If the printers return anything other than None, we pass it on.
-
setOutPutFiles
(filename, silent=False)[source]¶ Set the basename for the output files. Each printer will use this file name appended of the respective extension (i.e. .py for a python printer, .smodels for a summary printer,…)
Parameters: - filename – Input file name
- silent – dont comment removing old files
-
-
class
tools.printer.
PyPrinter
(output='stdout', filename=None)[source]¶ Bases:
tools.printer.BasicPrinter
Printer class to handle the printing of one single pythonic output
-
class
tools.printer.
SLHAPrinter
(output='file', filename=None)[source]¶ Bases:
tools.printer.TxTPrinter
Printer class to handle the printing of slha format summary output. It uses the facilities of the TxTPrinter.
-
setOutPutFile
(filename, overwrite=True, silent=False)[source]¶ Set the basename for the text printer. The output filename will be filename.smodels. :param filename: Base filename :param overwrite: If True and the file already exists, it will be removed. :param silent: dont comment removing old files
-
-
class
tools.printer.
SummaryPrinter
(output='stdout', filename=None)[source]¶ Bases:
tools.printer.TxTPrinter
Printer class to handle the printing of one single summary output. It uses the facilities of the TxTPrinter.
-
setOutPutFile
(filename, overwrite=True, silent=False)[source]¶ Set the basename for the text printer. The output filename will be filename.smodels. :param filename: Base filename :param overwrite: If True and the file already exists, it will be removed. :param silent: dont comment removing old files
-
-
class
tools.printer.
TxTPrinter
(output='stdout', filename=None)[source]¶ Bases:
tools.printer.BasicPrinter
Printer class to handle the printing of one single text output
-
class
tools.printer.
XmlPrinter
(output='stdout', filename=None)[source]¶ Bases:
tools.printer.PyPrinter
Printer class to handle the printing of one single XML output
-
convertToElement
(pyObj, parent, tag='')[source]¶ Convert a python object (list,dict,string,…) to a nested XML element tree. :param pyObj: python object (list,dict,string…) :param parent: XML Element parent :param tag: tag for the daughter element
-
tools.pythia6Wrapper module¶
-
class
tools.pythia6Wrapper.
Pythia6Wrapper
(configFile='<install>/smodels/etc/pythia.card', executablePath='<install>/smodels/lib/pythia6/pythia_lhe', srcPath='<install>/smodels/lib/pythia6/')[source]¶ Bases:
smodels.tools.wrapperBase.WrapperBase
An instance of this class represents the installation of pythia6.
-
checkFileExists
(inputFile)[source]¶ Check if file exists, raise an IOError if it does not.
Returns: absolute file name if file exists.
-
replaceInCfgFile
(replacements={'NEVENTS': 10000, 'SQRTS': 8000})[source]¶ Replace strings in the config file by other strings, similar to setParameter.
This is introduced as a simple mechanism to make changes to the parameter file.
Parameters: replacements – dictionary of strings and values; the strings will be replaced with the values; the dictionary keys must be strings present in the config file
-
run
(slhafile, lhefile=None, unlink=True)[source]¶ Execute pythia_lhe with n events, at sqrt(s)=sqrts.
Parameters: - slhafile – input SLHA file
- lhefile – option to write LHE output to file; if None, do not write output to disk. If lhe file exists, use its events for xsecs calculation.
- unlink – Clean up temp directory after running pythia
Returns: List of cross sections
-
tools.pythia8Wrapper module¶
-
class
tools.pythia8Wrapper.
Pythia8Wrapper
(configFile='<install>/smodels/etc/pythia8.cfg', executablePath='<install>/smodels/lib/pythia8/pythia8.exe', srcPath='<install>/smodels/lib/pythia8/')[source]¶ Bases:
smodels.tools.wrapperBase.WrapperBase
An instance of this class represents the installation of pythia8.
-
checkFileExists
(inputFile)[source]¶ Check if file exists, raise an IOError if it does not.
Returns: absolute file name if file exists.
-
run
(slhaFile, lhefile=None, unlink=True)[source]¶ Run pythia8.
Parameters: - slhaFile – SLHA file
- lhefile – option to write LHE output to file; if None, do not write output to disk. If lhe file exists, use its events for xsecs calculation.
- unlink – clean up temporary files after run?
Returns: List of cross sections
-
tools.pythia8particles module¶
tools.pythonTools module¶
tools.runSModelS module¶
-
tools.runSModelS.
run
(inFile, parameterFile, outputDir, db, timeout, development)[source]¶ Provides a command line interface to basic SModelS functionalities.
Parameters: - inFile – input file name (either a SLHA or LHE file) or directory name (path to directory containing input files)
- parameterFile – File containing the input parameters (default = smodels/etc/parameters_default.ini)
- outputDir – Output directory to write a summary of results to
- db – supply a smodels.experiment.databaseObj.Database object, so the database doesn’t have to be loaded anymore. Will render a few parameters in the parameter file irrelevant. If None, load the database as described in parameterFile, If True, force loading the text database.
- timeout – set a timeout for one model point (0 means no timeout)
- development – turn on development mode (e.g. no crash report)
tools.runtime module¶
tools.simplifiedLikelihoods module¶
-
class
tools.simplifiedLikelihoods.
Data
(observed, backgrounds, covariance, third_moment=None, nsignal=None, name='model', deltas_rel=0.2)[source]¶ Bases:
object
A very simple observed container to collect all the data needed to fully define a specific statistical model
-
convert
(obj)[source]¶ Convert object to numpy arrays. If object is a float or int, it is converted to a one element array.
-
signals
(mu)[source]¶ Returns the number of expected signal events, for all datasets, given total signal strength mu.
Parameters: mu – Total number of signal events summed over all datasets.
-
totalCovariance
(nsig)[source]¶ get the total covariance matrix, taking into account also signal uncertainty for the signal hypothesis <nsig>. If nsig is None, the predefined signal hypothesis is taken.
-
-
class
tools.simplifiedLikelihoods.
LikelihoodComputer
(data, ntoys=10000)[source]¶ Bases:
object
-
chi2
(nsig, marginalize=False)[source]¶ Computes the chi2 for a given number of observed events nobs given the predicted background nb, error on this background deltab, expected number of signal events nsig and the relative error on signal (deltas_rel). :param marginalize: if true, marginalize, if false, profile :param nsig: number of signal events :return: chi2 (float)
-
dLdMu
(mu, signal_rel, theta_hat)[source]¶ d (ln L)/d mu, if L is the likelihood. The function whose root gives us muhat, i.e. the mu that maximizes the likelihood.
Parameters: - mu – total number of signal events
- signal_rel – array with the relative signal strengths for each dataset (signal region)
- theta_hat – array with nuisance parameters
-
debug_mode
= False¶
-
findMuHat
(signal_rel)[source]¶ Find the most likely signal strength mu given the relative signal strengths in each dataset (signal region).
Parameters: signal_rel – array with relative signal strengths Returns: mu_hat, the total signal yield.
-
findThetaHat
(nsig)[source]¶ Compute nuisance parameter theta that maximizes our likelihood (poisson*gauss).
-
getSigmaMu
(signal_rel)[source]¶ Get a rough estimate for the variance of mu around mu_max.
Parameters: signal_rel – array with relative signal strengths in each dataset (signal region)
-
getThetaHat
(nobs, nb, nsig, covb, max_iterations)[source]¶ Compute nuisance parameter theta that maximizes our likelihood (poisson*gauss).
-
likelihood
(nsig, marginalize=False, nll=False)[source]¶ compute likelihood for nsig, profiling the nuisances :param marginalize: if true, marginalize, if false, profile :param nll: return nll instead of likelihood
-
marginalizedLLHD1D
(nsig, nll)[source]¶ Return the likelihood (of 1 signal region) to observe nobs events given the predicted background nb, error on this background (deltab), expected number of signal events nsig and the relative error on the signal (deltas_rel).
Parameters: - nsig – predicted signal (float)
- nobs – number of observed events (float)
- nb – predicted background (float)
- deltab – uncertainty on background (float)
Returns: likelihood to observe nobs events (float)
-
marginalizedLikelihood
(nsig, nll)[source]¶ compute the marginalized likelihood of observing nsig signal event
-
nllHess
(theta)[source]¶ the Hessian of nll as a function of the thetas. Makes it easier to find the maximum likelihood.
-
nllprime
(theta)[source]¶ the derivative of nll as a function of the thetas. Makes it easier to find the maximum likelihood.
-
-
class
tools.simplifiedLikelihoods.
UpperLimitComputer
(ntoys=10000, cl=0.95)[source]¶ Bases:
object
-
debug_mode
= False¶
-
ulSigma
(model, marginalize=False, toys=None, expected=False)[source]¶ - upper limit obtained from the defined Data (using the signal prediction
- for each signal regio/dataset), by using the q_mu test statistic from the CCGV paper (arXiv:1007.1727).
Params marginalize: if true, marginalize nuisances, else profile them Params toys: specify number of toys. Use default is none Params expected: compute the expected value, not the observed. Returns: upper limit on production xsec (efficiencies unfolded)
-
tools.smodelsLogging module¶
-
class
tools.smodelsLogging.
ColorizedStreamHandler
(stream=None)[source]¶ Bases:
logging.StreamHandler
tools.stringTools module¶
tools.timeOut module¶
tools.toolBox module¶
-
class
tools.toolBox.
ToolBox
[source]¶ Bases:
object
A singleton-like class that keeps track of all external tools. Intended to make installation and deployment easier.
tools.wrapperBase module¶
-
class
tools.wrapperBase.
WrapperBase
[source]¶ Bases:
object
An instance of this class represents the installation of an external tool.
An external tool encapsulates a tool that is executed via commands.getoutput. The wrapper defines how the tool is tested for proper installation and how the tool is executed.
-
absPath
(path)[source]¶ Get the absolute path of <path>, replacing <install> with the installation directory.
-
tools.xsecComputer module¶
-
class
tools.xsecComputer.
ArgsStandardizer
[source]¶ Bases:
object
simple class to collect all argument manipulators
-
class
tools.xsecComputer.
XSecComputer
(maxOrder, nevents, pythiaVersion)[source]¶ Bases:
object
cross section computer class, what else?
-
addXSecToFile
(xsecs, slhafile, comment=None, complain=True)[source]¶ Write cross sections to an SLHA file.
Parameters: - xsecs – a XSectionList object containing the cross sections
- slhafile – target file for writing the cross sections in SLHA format
- comment – optional comment to be added to each cross section block
- complain – complain if there are already cross sections in file
-
compute
(sqrts, slhafile, lhefile=None, unlink=True, loFromSlha=None, pythiacard=None)[source]¶ Run pythia and compute SUSY cross sections for the input SLHA file.
Parameters: - sqrts – sqrt{s} to run Pythia, given as a unum (e.g. 7.*TeV)
- slhafile – SLHA file
- lhefile – LHE file. If None, do not write pythia output to file. If file does not exist, write pythia output to this file name. If file exists, read LO xsecs from this file (does not run pythia).
- unlink – Clean up temp directory after running pythia
- loFromSlha – If True, uses the LO xsecs from the SLHA file to compute the higher order xsecs
- pythiaCard – Optional path to pythia.card. If None, uses /etc/pythia.card
Returns: XSectionList object
-
computeForBunch
(sqrtses, inputFiles, unlink, lOfromSLHA, tofile, pythiacard=None)[source]¶ compute xsecs for a bunch of slha files
-
computeForOneFile
(sqrtses, inputFile, unlink, lOfromSLHA, tofile, pythiacard=None)[source]¶ compute the cross sections for one file. :param sqrtses: list of sqrt{s} tu run pythia, as a unum (e.g. 7*TeV)
-
xsecToBlock
(xsec, inPDGs=(2212, 2212), comment=None, xsecUnit=1.00E+00 [pb])[source]¶ Generate a string for a XSECTION block in the SLHA format from a XSection object.
Parameters: - inPDGs – defines the PDGs of the incoming states (default = 2212,2212)
- comment – is added at the end of the header as a comment
- xsecUnit – unit of cross sections to be written (default is pb). Must be a Unum unit.
-
Module contents¶
Indices and tables¶
C++ Interface¶
Since v1.1.1, a simple C++ interface is provided, see the smodels/cpp directory in the source code.
Its usage is documented in run.cpp:
#include <SModelS.h>
#include <iostream>
#include <string>
/** example only */
using namespace std;
int main( int argc, char * argv[] )
{
/** initialise SModelS, load database, second argument (installdir) must point to smodels
* installation top-level directory */
SModelS smodels ( "./parameters.ini", "../" );
/** run over one single file or directory */
int ret = smodels.run ( "test.slha" );
}
A sample Makefile is also provided. The python header files have to be installed.