.. index:: Output Description .. |invisible compression| replace:: :ref:`invisible compression ` .. |mass compression| replace:: :ref:`mass compression ` .. |particle| replace:: :ref:`particle ` .. |particles| replace:: :ref:`particles ` .. |SMS| replace:: :ref:`SMS ` .. |SMS topology| replace:: :ref:`SMS topology ` .. |SMS topologies| replace:: :ref:`SMS topologies ` .. |topology| replace:: :ref:`topology ` .. |topologies| replace:: :ref:`topologies ` .. |decomposition| replace:: :ref:`decomposition ` .. |theory predictions| replace:: :doc:`theory predictions ` .. |theory prediction| replace:: :doc:`theory prediction ` .. |constraint| replace:: :ref:`constraint ` .. |constraints| replace:: :ref:`constraints ` .. |runSModelS| replace:: :ref:`runSModelS.py ` .. |database| replace:: :ref:`database ` .. |output| replace:: :ref:`output ` .. |results| replace:: :ref:`experimental results ` .. |txnames| replace:: :ref:`txnames ` .. |txname| replace:: :ref:`txname ` .. |EM| replace:: :ref:`EM-type ` .. |UL| replace:: :ref:`UL-type ` .. |EMr| replace:: :ref:`EM-type result ` .. |ULr| replace:: :ref:`UL-type result ` .. |EMrs| replace:: :ref:`EM-type results ` .. |ULrs| replace:: :ref:`UL-type results ` .. |ExpRes| replace:: :ref:`Experimental Result` .. |ExpRess| replace:: :ref:`Experimental Results` .. |expres| replace:: :ref:`experimental result` .. |express| replace:: :ref:`experimental results` .. |Dataset| replace:: :ref:`DataSet` .. |Datasets| replace:: :ref:`DataSets` .. |dataset| replace:: :ref:`data set` .. |datasets| replace:: :ref:`data sets` .. |parameters| replace:: :ref:`parameters file ` .. |ssigBRe| replace:: :math:`\sum \sigma \times BR \times \epsilon` .. |canonical names| replace:: :ref:`canonical names ` .. |canonical name| replace:: :ref:`canonical name ` .. _outputDescription: Output Description ================== A detailed description of the possible output formats generated by :ref:`running SModelS ` and their content is given below. For simplicity we will assume that all printer options in the |parameters| are set to True, so the output information is maximal.\ [#f1]_ .. _screenOut: Screen (Stdout) Output ---------------------- The stdout (or :ref:`log output `) is intended to provide extensive information about the |database|, the |decomposition|, the |theory predictions| and the :ref:`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|), the screen output contains the following information: * information about the basic input parameters and the status of the run: .. literalinclude:: /images/gluino_squarks.slha.log :lines: 1-22 * a list of all the |express| considered (if **printDatabase** = True). Note that this list corresponds to all the results selected in the **database** options (see |parameters|). If **addAnaInfo** = True, for each |expres| entry a list of all the simplified models (or |SMS|) constrained by the analysis is also shown using their :ref:`string representation `: .. literalinclude:: /images/gluino_squarks.slha.log :lines: 23-28,72-89 * a full list of the |SMS topologies| generated by the |decomposition| (if **printDecomp** = True). The |SMS topologies| are grouped according to their |canonical names| (topology structure) given in the Topology field. Each group lists the number of |SMS| sharing this structure and the sum over all the |SMS| weights. If **addSMSInfo** = True, the |SMS| belonging to each topology group are also explicitly given using their :ref:`string representation `, as well as the BSM masses, weights and the SMS ID (only used internally): .. literalinclude:: /images/gluino_squarks.slha.log :lines: 2225-2245,2277-2300 * a list of all the |theory predictions| obtained and the corresponding |expres| upper limit. For each |expres|, their *label*, signal region (|dataset|) and *sqrts* as well as the constrained simplified models (|txnames| labels) are printed. A list of |txnames| and their meaning is available `here `_. After this basic information, the signal cross section (|theory prediction|), the list of :ref:`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 negative log likelihood (nll) for the BSM signal, that for the SM hypothesis, and the minimum nll are printed (see :ref:`likelihood calculation `). Finally, if **printExtendedResults** = True, the IDs of the contributing |SMS| (|SMS topologies| being constrained) is given. The ID numbers correspond to the ones printed in the decomposition/topologies table (see above) and can be used to obtain detailed information about the constrained |SMS topologies|. .. literalinclude:: /images/gluino_squarks.slha.log :lines: 2528-2563 * information about the combination of results, if **combineAnas** is defined (available from v2.2 onward): .. literalinclude:: /images/gluino_squarks.slha.log :lines: 3123-3128 * summary information about the :ref:`missing topologies `, if **testCoverage** = True. The total missing topology cross section corresponds to the sum of cross sections of all the |SMS topologies| which are not tested by any |expres|. The cross section for missing topologies with prompt (displaced) decays corresponds to the total signal cross section going into prompt (displaced) decays which are not tested by any displaced |expres| of type *prompt* (*displaced*) (see :ref:`simplified model coverage ` for more details). If the |SMS| is constrained by one or more |express|, but its masses and/or widths are outside the efficiency or upper limit grids (see |EMrs| and |ULrs|), its cross section is included in the total cross section outside the grid. .. literalinclude:: /images/gluino_squarks.slha.log :lines: 3131-3134 * detailed information about the missing topologies with highest cross sections. The :ref:`final state SMS ` cross section (weight) as well as the description of its final states (see :ref:`SMS representation `) is included for each distinct :ref:`coverage group `. If **addCoverageID** = True, all the |SMS| IDs contributing to the missing topology are shown. These IDs can be traced back to the corresponding |SMS topologies| using the decomposition information (topologies table) obtained with **printDecomp** = True and **addSMSInfo** = True. .. literalinclude:: /images/gluino_squarks.slha.log :lines: 3136-3143 * information about the missing topologies with displaced decays. If **addCoverageID** = True, all the |SMS| IDs contributing to the missing topology are shown. .. literalinclude:: /images/gluino_squarks.slha.log :lines: 3161-3162 * information about the missing topologies with prompt decays. If **addCoverageID** = True, all the |SMS| IDs contributing to the missing topology are shown. .. literalinclude:: /images/gluino_squarks.slha.log :lines: 3162-3168 * detailed information about the topologies which are outside the |express| grid. If **addCoverageID** = True, all the |SMS| IDs contributing to the missing topology are shown. .. literalinclude:: /images/gluino_squarks.slha.log :lines: 3186-3187 .. _logOut: Log Output ---------- The log-type output is identical to the :ref:`screen output `, except that it is redirected to a .log file. The filename is set as the .log and stored in the output folder (see the :ref:`runSModelS options `). .. _fileOut: Summary File Output ------------------- The summary-type output is similar to the :ref:`screen output `, but restricted to the list of |theory predictions| and model :ref:`coverage `. The output is printed to the file .smodels and stored in the output folder (see the :ref:`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: .. literalinclude:: /images/gluino_squarks.slha.smodels :lines: 1-22 * a list of all the |theory predictions| obtained and the corresponding |expres| upper limit. If **expandedSummary** = False only the most constraining |expres| is printed. For each |theory prediction| entry, the corresponding |expres| *label*, the signal region (|dataset|) used (only for |EMrs|) and the |expres| *sqrts* is printed. The |SMS topologies| contributing to the signal cross section is also shown and are identified by their |txnames| (a list of all |txnames| and their meaning can be found `here `_). Furthermore, 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 |ULrs| the condition violation (see :ref:`upper limit conditions `) is also included. . Finally, if **computeStatistics** = True, the negative log likelihood values (for |EMrs|) are printed: .. literalinclude:: /images/gluino_squarks.slha.smodels :lines: 23-39 * the maximum r value, that is the highest (theory cross section)/(observed upper limit) ratio. If this value is greater or equal 1, the input model is likely excluded by one of the |express| (see :ref:`confronting predictions `). For a more informed statistical interpretation, from v2.1 onward the ATLAS and CMS analyses with highest available *expected* r values are reported in addition. .. literalinclude:: /images/gluino_squarks.slha.smodels :lines: 243-245 * information about the combination of results, if **combineAnas** is defined (available from v2.2 onward): .. literalinclude:: /images/gluino_squarks.slha.smodels :lines: 247-250 * summary information about the :ref:`missing topologies `, if **testCoverage** = True. The total missing topology cross section corresponds to the sum of cross sections of all |SMS topologies| which are not tested by any |expres|. The cross section for missing topologies with prompt (displaced) decays corresponds to the total signal cross section going into prompt (displaced) decays which are not tested by any displaced |expres| of type *prompt* (*displaced*) (see :ref:`simplified model coverage ` for more details). If the |SMS| is constrained by one or more |express|, but its masses and/or widths are outside the efficiency or upper limit grids (see |EMrs| and |ULrs|), its cross section is included in the total cross section outside the grid. .. literalinclude:: /images/gluino_squarks.slha.smodels :lines: 254-257 * detailed information about the missing topologies with highest cross sections. The :ref:`final state SMS ` cross section (weight) as well as the description of its final states (see :ref:`SMS representation `) is included for each distinct :ref:`coverage group `. .. literalinclude:: /images/gluino_squarks.slha.smodels :lines: 259-264 * information about the missing topologies with displaced decays. .. literalinclude:: /images/gluino_squarks.slha.smodels :lines: 273-274 * information about the missing topologies with prompt decays. .. literalinclude:: /images/gluino_squarks.slha.smodels :lines: 275-280 * information about the topologies which are outside the |express| grid .. literalinclude:: /images/gluino_squarks.slha.smodels :lines: 288-289 .. _pyOut: Python Output ------------- The Python-type output is similar to the :ref:`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 :ref:`simplified model coverage `. The output is printed to the file .py and stored in the output folder (see the :ref:`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: .. literalinclude:: /images/gluino_squarks.slha.py :lines: 1-26 * a full list of the |SMS topologies| generated by the |decomposition| (if **addSMSList** = True) stored under the *SMS Decomposition* key. Each list entry contains basic information about the |SMS|. The list can be considerably long, so it is recommended to set **addSMSList** to False, unless the |decomposition| information is required by the user. .. literalinclude:: /images/gluino_squarks.slha.py :lines: 27-44 * a list of all the |theory predictions| obtained for the |express|, stored under the *ExptRes* key. For each list entry, the corresponding result *label*, the |expres| type (if |ULr| or |EMr|), the signal region (|dataset| ID), the *sqrts* and luminosity, the constrained simplified models (identified by the |txnames|), the signal cross section (theory prediction), the corresponding observed upper limit and the maximum condition violation (see :ref:`upper limit conditions `) are shown. A list of |txnames| and their meaning is available `here `_. Furthermore, the masses and widths\ [#f3]_ of the |SMS| contributing to the signal cross section, the individual contribution of each |txname| (if **addTxWeights** = True) and the negative log likelihood values (if **computeStatistics** = True) are also included. .. literalinclude:: /images/gluino_squarks.slha.py :lines: 661-695 * information about the combination of results, if **combineAnas** is defined (available from v2.2 onward): .. literalinclude:: /images/gluino_squarks.slha.py :lines: 2058-2067 * the total cross section in each :ref:`missing topology group ` (if **testCoverage** = True) followed by a list of the :ref:`final state SMS ` cross sections (weight) as well as the description of its final states. .. literalinclude:: /images/gluino_squarks.slha.py :lines: 2068-2081 .. _xmlOut: XML Output ---------- The xml-type output is identical to the :ref:`python output `, however converted to a xml format. The output is printed to the file .xml and stored in the output folder (see the :ref:`runSModelS options `). Since the output information and options are the same as described for :ref:`python output `, we simply show below an excerpt of the xml file to illustrate the output format: .. literalinclude:: /images/gluino_squarks.slha.xml :language: xml :lines: 2-51 .. _slhaOut: SLHA Output ----------- An SLHA-type output format is also available containing a summary of the |theory predictions| and :ref:`simplified model coverage `. The file contains the SLHA-type blocks: *SModelS_Settings*, *SModelS_Exclusion*, *SModelS_CombinedAnas* (**combineAnas** is defined) and *SModelS_Coverage*. Below we give a description of each block together with a sample output. * information about the main input parameters: .. literalinclude:: /images/gluino_squarks.slha.smodelsslha :lines: 1-11 * information about the status of the input model: excluded (1), not excluded (0) or not tested (-1): .. literalinclude:: /images/gluino_squarks.slha.smodelsslha :lines: 13-14 * followed by the list of experimental results. If **expandedOutput** = True, all results are printed. Otherwise, if the model is excluded, all results with :math:`r`-value greater than one are shown and if the point is not excluded, only the result with the highest :math:`r`-value is displayed. For each experimental result, the |txname| (for a list of all |txnames| and their meaning, see `SMS Dictionary `_), the :math:`r`-value, the expected :math:`r`-value (when available), the :ref:`condition violation `, the experimental result *label* and the signal region (|dataset|) are shown. If **computeStatistics** = True, the negative log likelihood values for |EMrs| are also printed: .. literalinclude:: /images/gluino_squarks.slha.smodelsslha :lines: 15-23 * information about the combination of results, if **combineAnas** is defined (available from v2.2 onward): .. literalinclude:: /images/gluino_squarks.slha.smodelsslha :lines: 515-521 * the label of each :ref:`coverage group ` (first entry) and the total cross section in each group (second entry) (if **testCoverage** = True): .. literalinclude:: /images/gluino_squarks.slha.smodelsslha :lines: 524-532 .. _scanSummary: Multiple Files Summary Output ----------------------------- When running SModelS over multiple files, it might be desirable to have a simplified output with a summary of the results for each input file. Since version 2.1 this information is stored by default in the 'summary.txt' file in the output folder. This text file lists, on a single line for each input file, the most constraining analysis (the one with largest observed :math:`r`), as well as the most sensitive ATLAS and CMS analyses (the ones with largest expected :math:`r`), together with the relevant observed and expected :math:`r`-values. And example is shown below: .. literalinclude:: /images/scan_summary.txt :lines: 1-11 If **combineAnas** is defined, the summary will also include the observed and expected :math:`r`-values for the combination of analyses. .. [#f1] Some of the output may change depending on the code and database versions used. In particular, for a description of the version 2 output format, check the v2 manual. .. [#f2] The mass shown corresponds to an average mass over all the |SMS topologies| contributing to the theory prediction. In the case where the |SMS| have distinct structures (i.e. |canonical names|) no mass is shown. .. [#f3] For particles considered with prompt decays (see :ref:`promptWidth parameter `), the width is replaced by 'prompt', while for particles considered stable (see see :ref:`stableWidth parameter `), the width is replaced by 'stable'. If more than one |SMS| contributes to the theory prediction, the average widths and masses of the BSM states are shown.