.. index:: Decomposition into Simplified Models

.. |invisible compression| replace:: :ref:`invisible compression <invComp>`
.. |mass compression| replace:: :ref:`mass compression <massComp>`
.. |element| replace:: :ref:`element <element>`
.. |elements| replace:: :ref:`elements <element>`
.. |topology| replace:: :ref:`topology <topology>`
.. |topologies| replace:: :ref:`topologies <topology>`
.. |analysis| replace:: :ref:`analysis <ULanalysis>`
.. |analyses| replace:: :ref:`analyses <ULanalysis>`
.. |decomposition| replace:: :doc:`decomposition <Decomposition>`
.. |theory predictions| replace:: :doc:`theory predictions <TheoryPredictions>`
.. |theory prediction| replace:: :doc:`theory prediction <TheoryPredictions>`
.. |constraint| replace:: :ref:`constraint <ULconstraint>`
.. |constraints| replace:: :ref:`constraints <ULconstraint>`


Decomposition into Simplified Models
====================================

Given an input model, the first task of SModelS is to decompose 
the full model into a sum of :ref:`elements <element>`. 
Based on the input format, which can be  
 
* a SLHA (SUSY Les Houches Accord) file or  
* a LHE (Les Houces Event) file

as explained in the :doc:`Basic Input <BasicInput>` section,  
two distinct (but similar) decomposition methods are applied:
the :ref:`SLHA-based <slhaDecomp>` or the :ref:`LHE-based <lheDecomp>` decomposition.

.. _slhaDecomp:

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 :ref:`SLHA cross-section format <xsecSLHA>`.

Once the production cross-sections are read from the input file, all the cross-sections for *production
of two* Z\ :sub:`2`-odd *states* are stored and serve as the initial step for the decomposition. (All the other cross-sections
with a different number of Z\ :sub:`2`-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:

.. _decomp1:

.. image:: images/decomp1.png
   :height: 320px


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

.. _decomp2:

.. image:: images/decomp2.png
   :height: 410px


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 :math:`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 :ref:`elements <element>` 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 :ref:`minimum weight <minweight>` requirement are kept.
Furthermore, the elements are grouped according to their :ref:`topologies <topology>`. 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 <../../../documentation/build/html/theory.html#theory.slhaDecomposer.decompose>`_


.. _minweight:

Minimum Decomposition Weight
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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 <../../../documentation/build/html/theory.html#build/html/theory.slhaDecomposer.decompose>`_ parameter 
and is easily adjustable (see `slhaDecomposer.decompose <../../../documentation/build/html/theory.html#build/html/theory.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 <../../../documentation/build/html/theory.html#build/html/theory.slhaDecomposer.decompose>`_
approximately one order of magnitude below the minimum signal cross-sections the experimental data can constrain.
 
.. _lheDecomp:

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 :ref:`element <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: 

.. _event:

.. image:: images/eventExample.png
   :height: 520px

Notice that, for the LHE decomposition, the :ref:`elements <element>` 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 the no mass smearing is applied, so the events
always contain the mass value for a given particle.

* **The LHE decomposition is implemented by the** `LHE decompose method <../../../documentation/build/html/theory.html#build/html/theory.lheDecomposer.decompose>`_

.. _elementComp:

Compression of Elements
-----------------------


During the decomposition process it is possible to perform several simplifications on
the :ref:`elements <element>` generated. In both the :ref:`LHE <lheDecomp>` and :ref:`SLHA <slhaDecomp>`-based decompositions, two useful
simplifications are possible: :ref:`Mass Compression <massComp>` and :ref:`Invisible Compression <invComp>`.
The main advantage of performing these compressions is that the simplified :ref:`element <element>` is
always shorter (has fewer cascade decay steps), which makes it more likely to be constrained by experimental
analyses. The details behind the compression methods are as follows:

.. _massComp:

Mass Compression
^^^^^^^^^^^^^^^^

In case of small mass differences, the decay of an :ref:`intermediate state <odd states>` to a nearly degenerate
one will in most cases produce soft :ref:`final states <final states>`, which can not be experimentally detected.
Consequently, it is a good approximation to neglect the soft :ref:`final states <final states>` and *compress* the respective
decay, as shown below:

.. _massCompfig:

.. image:: images/massComp.png
   :height: 300px

After the compression, only the lightest of the two near-degenerate masses are kept in the element, as shown :ref:`above <massCompfig>`.
The main parameter which controls the compression is `minmassgap <../../../documentation/build/html/theory.html#build/html/theory.element.Element.massCompress>`_,
which corresponds to the maximum value of :math:`\epsilon`
in the :ref:`figure above <massCompfig>` to which the compression is performed:

.. math::
   & \mbox{if } |M_j - M_{j+1}| < minmassgap \rightarrow \mbox{the decay is compressed}\\ 
   & \mbox{if } |M_j - M_{j+1}| > minmassgap \rightarrow \mbox{the decay is NOT compressed}\\

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 <../../../documentation/build/html/theory.html#build/html/theory.element.Element.massCompress>`_
between 1-10 GeV; the default value is 5 GeV.

* **Mass compression is implemented by the** `massCompress <../../../documentation/build/html/theory.html#build/html/theory.element.Element.massCompress>`_ **method**
and can be easily turned on/off by the flag *doCompress* in the :ref:`SLHA <slhaDecomp>` or :ref:`LHE <lheDecomp>` decompositions

.. _invComp:

Invisible Compression
^^^^^^^^^^^^^^^^^^^^^

Another class of compression is possible when
the :ref:`final states <final states>` in the last decay as well as the last :ref:`intermediate state <odd states>`
are both invisible experimentally. 
The most common example is 

.. math::
   A \rightarrow \nu + B

as the last step of the decay chain, where :math:`B` is an insivible particle leading to a MET signature. Since both the neutrino and 
:math:`B` are invisible, for all experimental purposes the effective MET object is :math:`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:


.. _massInvpfig:

.. image:: images/invComp.png
   :height: 300px


* **Invisible compression is implemented by the** `invisibleCompress <../../../documentation/build/html/theory.html#build/html/theory.element.Element.invisibleCompress>`_ **method**
and can be easily turned on/off by the flag *doInvisible* in the :ref:`SLHA <slhaDecomp>` or :ref:`LHE <lheDecomp>` decompositions

 
