Skip to content

Latest commit

 

History

History
330 lines (204 loc) · 14.5 KB

SModelSTools.rst

File metadata and controls

330 lines (204 loc) · 14.5 KB
Raw
.. index:: SModelS Tools

SModelS Tools

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

Cross Section Calculator

This tool computes LHC production cross sections for MSSM particles and writes them out in :ref:`SLHA convention <xsecblock>`. This can in particular be convenient for adding cross sections to SLHA input files, see :doc:`Basic Input <BasicInput>`. 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:

Further Pythia parameters are defined in :download:`smodels/etc/pythia8.cfg </images/pythia8.cfg>` (for Pythia 8) or :download:`smodels/etc/pythia.card </images/pythia.card>` (for Pythia 6). .

A typical usage example is:

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

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

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

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

Input File Checks

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

LHE File Checker

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

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

The usage of the LHE checker is simply:

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

In addition, one can ask that

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

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

The usage of the SLHA checker is:

A typical usage example is:

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

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

Note

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

Database Browser

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

The usage of the browser interface is:

A typical usage example is:

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

Loading the database may take a few seconds if the :ref:`binary database file <databasePickle>` exists. Otherwise the :ref:`pickle file <databasePickle>` 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 :ref:`Howto's <Examples>`.

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:

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 :download:`iplots_parameters.py <images/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:

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: