== Simplified - Fast Simulation (SFS) of detector response ==

This page contains a brief introduction about the usage of SFS machinery, for details, please see [https://arxiv.org/abs/2006.09387 arXiv:2006.09387]. SFS machinery allows the user to simulate detector response within !MadAnalysis 5 framework using only !FastJet libraries. SFS uses transfer functions on reconstructed objects to simulate detector response. It is, also, fully integrated with [http://madanalysis.irmp.ucl.ac.be/wiki/PublicAnalysisDatabase Public Analysis Database], and the user can recast experimental analyses using SFS' fast interface, for details, please see [https://madanalysis.irmp.ucl.ac.be/wiki/SFS#LHCRecastingwithSFS below]. Although we provide default [https://madanalysis.irmp.ucl.ac.be/raw-attachment/wiki/SFS/ATLAS_default.ma5 ATLAS] and [https://madanalysis.irmp.ucl.ac.be/raw-attachment/wiki/SFS/CMS_default.ma5 CMS] cards which are validated against corresponding Delphes cards for four different physics process, this introduction will provide all information that is needed to use SFS machinery for any homebrew detector simulation. 

* Prerequisites: !FastJet
{{{
$>   ./bin/ma5 -R
ma5> install fastjet
ma5> set main.fastsim.package = fastjet
}}}

First-line activates the `RECO` mode for !MadAnalysis 5 framework which is required to use SFS machinery, the second line is to install !FasJet interface, and finally, the last line enables the !FastJet interface for the current session. User can set the desired reconstruction algorithm as before, please see [https://arxiv.org/abs/1808.00480 arXiv:1808.00480] or [https://madanalysis.irmp.ucl.ac.be/wiki/tutorials tutorials] for details on the usage of the !FastJet module in !MadAnalysis 5. After installing !FastJet one can use default SFS cards by simply typing
{{{
$> ./bin/ma5 -R madanalysis/input/<EXP>_default.ma5
}}}
where `<EXP>` can either be `ATLAS` or `CMS`.

SFS contains three submodules, namely `reco_efficiency`, `smearer`, and `tagger`. These submodules set a probability distribution to reconstruct a given object, smear carried object's four-momentum using normalized Gaussian functions and sets identification efficiencies, respectively. The goal is to create a CPU efficient, user-friendly, easy-to-use, and generic environment. Thus given transfer functions are translated into C++ functions to act on reconstructed final state objects such as jets, hadronic taus, electrons, muons, and photons. 

Jet reconstruction contains two possible options, namely jet smearing and substructure smearing. These options can be set via
{{{
ma5> set main.fastsim.jetrecomode = <opt>
}}}
where `<opt>` represents user-defined input which can either be `jets` or `constituents` (default `jets`).  `jets` option allows the `reco_efficiency` and `smearer` submodules to act on clustered jet objects. The latter option, `constituents`, enables the possibility to apply detector response at the hadron level. 

== Reconstruction Efficiencies: `reco_efficiency` ==

This submodule can act on jets (`j`, `21`), electrons (`e`, `11`), muons (`mu`, `13`), hadronic taus (`ta`, `15`) or photons (`a`, `22`). It simply takes three input;
{{{
ma5> define reco_efficiency <obj> <func> [<domain>]
}}}
where `<obj>` represents the desired object to be reconstructed, `<func>` is the transfer function which can depend on any observable like `PT`, `E`, `ETA`,`ABSETA`,`PHI` etc. which are defined in !MadAnalysis 5's interface. `<func>` can also include any functional form like trigonometric or hyperbolic functions. `<dom>` (optional) represents the domain where the defined function will be active. The module creates a piecewise function to construct a probability distribution for the given object and phase-space. This piece of input will generate a probability distribution for the desired object to decide if it's going to be used in the analysis or not. 

* Example:
{{{
ma5> define reco_efficiency e 0.0   [pt <= 10.0 or abseta > 2.5]
ma5> define reco_efficiency e 0.7   [pt > 10.0 and abseta <= 1.5]
ma5> define reco_efficiency e 0.55  [pt > 10.0 and abseta > 1.5 and abseta <= 2.5]
}}}
Here we exemplify an electron reconstruction efficiency where an electron object will not be reconstructed if it has less than 10 GeV transverse momentum or its pseudorapidity is above 2.5. Additionally, it will be reconstructed with 70% probability if it's within |\eta| < 1.5 and pT >= 10 GeV and with 55% probability if its between 1.5 < |\eta| <= 2.5. Domain inputs have to be separated with `and` or `or` keywords to be effective, `and` enforces all domain conditions to be true and `or` requires at least one domain to be true. It is also possible to connect multiple domains together such as `[(abseta>1 and abseta<1.5) or (abseta>2.5 and abseta<3)]`.

== Object Smearing: `smearer` ==

Here we introduce the smearing function, which uses a user-defined standard deviation to be used in normalized Gaussian distribution. This function can depend on any observable defined in  !MadAnalysis interface. All information regarding the reconstructed objects to be used, function and domain syntax is the same as [https://madanalysis.irmp.ucl.ac.be/wiki/SFS#ReconstructionEfficiencies before]. This submodule can be defined as follows;
{{{
define smearer <obj> with <var> <func> [<dom>]
}}}
Here `<obj>` stands for the object (jet, electron, muon, hadronic tau or photon), `<var>` is the variable to be smeared which can be `E`, `PT`, `PX`, `PY`, `PZ`, `PHI` and `ETA`. `<func>` and `<dom>` are, as defined above, stands for the function and the domain that this function will be active. Note that `<obj>` and `<var>` are separated with the keyword `with` and `<dom>` is optional.

* Example:
{{{
ma5> define smearer j with PT sqrt(0.06^2 + pt^2*1.3e-3^2) [abseta <= 0.5 and pt > 0.1]
ma5> define smearer j with PT sqrt(0.1^2  + pt^2*1.7e-3^2) [abseta > 0.5 and abseta <= 1.5 and pt > 0.1]
ma5> define smearer j with PT sqrt(0.25^2 + pt^2*3.1e-3^2) [abseta > 1.5 and abseta <= 2.5 and pt > 0.1]
}}}
Here we exemplified transverse momentum smearing of the jet object. This function simply generates a standard deviation, which depends on `PT` of the given jet. This STD will be further used in a normalized Gaussian function to simulate the uncertainty on the transverse momentum observation. The transverse momentum then shifted within the Gaussian width.

== Particle Identification: `tagger` ==

`tagger` submodule is used to set particle identification or misidentification efficiencies for desired objects. It can be defined as follows;
{{{
ma5> define tagger <true> as <reco> <func> [<dom>]
}}}

where `<true>` stands for the true object that will be reconstructed as `<reco>` object. If `<true>` and `<reco>` objects are same, the module will apply efficiency to reconstruct the given object. If, on the other hand, the `<true>` and `<reco>` objects are different, the module will apply misidentification efficiency on the `<true>` object. This submodule can be used on jets (`j`, `21`), b-jets (`b`, `5`), c-jets (`c`, `4`), electrons (`e`, `11`), muons (`mu`, `13`), hadronic taus (`ta`, `15`) or photons (`a`, `22`) where within certain physical limitations each object can be reconstructed as other objects, please see [https://arxiv.org/abs/2006.09387 arXiv:2006.09387] for the available options. It is important to note that `<true>` and `<reco>` are separated by the keyword `as`.

* Example:
{{{
ma5> define tagger j as ta 0.01 [ntracks >= 2 and abseta <= 2.7]
ma5> define tagger j as ta 0.02 [ntracks == 1 and abseta <= 2.7]
ma5> define tagger j as ta 0.0  [abseta > 2.7]

ma5> define tagger b as b 0.80*tanh(0.003*pt)*(30/(1+0.086*pt))
}}}
Here first three examples show the jet misidentification as a hadronic tau object where it can be misidentified with respect to the number of prongs inside the jet. The last line shows the b-jet tagging efficiency, which depends on its transverse momentum.

The algorithm gives the importance to first b-jets, where if a jet is mistagged as c-jet, it won't be mistagged as b, tau, electron, or photon. Similar order goes for all other objects; we simply set the importance as follows b > c > tau > muon > electron > photon, which means that if a jet is mistagged as any of the objects on this sequence, it won't be mistagged as the following objects. Similarly, user can mistag electrons, muons and photons as well;

* Example:
{{{
ma5> define tagger e as mu 0.01*exp(-pt)
}}}
This example sets a mistagging efficiency of 1% to tag an electron as a muon which decreases exponentially by the transverse momentum of the electron.
== SFS in Expert Mode ==

SFS machinery can be used with expert mode as well. Users can set up an SFS card with the desired options, which are exemplified above and given to !MadAnalysis as input;
{{{
$> ./bin/ma5 -Re <folder_name> <analysis_name> <SFS_card>
}}}
To use the SFS machinery in expert mode, the expert mode has to be initialized alongside with `RECO` mode. `<folder_name>` is optional input to create the analysis folder, `<analysis_name>` is, again, optional to write a null analysis file with the given name and finally the optional `<SFS_card>` generates the detector environment for the analysis and the detector effects will be applied live during the analysis. An expert mode interpreter can be found in [https://github.com/jackaraz/ma5_expert this link].


== LHC Recasting with SFS ==

SFS machinery can be used for LHC recasting. To install available analyses, please type;
{{{
ma5> install PADForSFS
}}}
This will install all available analyses to be used in recast. User does not need to install Delphes or ROOT to be able to use this module. In order to initialize `PADForSFS` simply type;
{{{
ma5> set main.recast = on
ma5> import <my_sample>.hepmc.gz as <sample_name>
ma5> set <sample_name>.xsection = 123
ma5> submit 
}}}
First-line initializes the recasting module; second line imports desired analysis with label `<sample_name>`, the third line sets the cross-section for the sample, and the last line submits the job. It is also possible to include theoretical uncertainties and high luminosity extrapolations, for more info, see [https://arxiv.org/abs/1910.11418 arXiv:1910.11418].

----
'''How to write an analysis?''' Details on how to write an analysis for [http://madanalysis.irmp.ucl.ac.be/wiki/PublicAnalysisDatabase Public Analysis Database] can be found [https://madanalysis.irmp.ucl.ac.be/wiki/WritingAnalyses here]. User should initialize the code with PDGIDs for hadrons and invisible particles as follows;
{{{
bool cms_cat_43_21::Initialize(const MA5::Configuration& cfg,
   const std::map<std::string,std::string>& parameters)
{
  PHYSICS->mcConfig().Reset();
  PHYSICS->mcConfig().AddHadronicId(<PDG-ID Hadron>);
  PHYSICS->mcConfig().AddInvisibleId(<PDG-ID Invisible>);
  return true;
}
}}}
a complete set or PDG-IDs to be initialized can be found in [https://madanalysis.irmp.ucl.ac.be/attachment/wiki/SFS/initialize.txt here]. Without such a list, !MadAnalysis won't be able to differentiate hadrons and invisible particles to be further used in the analysis.



----

== Available Analyses ==

**'' !! please properly cite all the re-implementation codes you are using; here are a [https://madanalysis.irmp.ucl.ac.be/raw-attachment/wiki/SFS/bib_padsfs.dat PADForSFS BibTeX file] for this purpose !! **'' 

=== ATLAS analyses, 13 TeV ===
|| '''Analysis''' || ''' Short Description''' || '''Implemented by''' || '''Code''' || '''Validation note''' || '''Version''' ||
|| [http://atlas.web.cern.ch/Atlas/GROUPS/PHYSICS/PAPERS/SUSY-2016-07/ ATLAS-SUSY-2016-07]  || Multijet + missing transverse momentum (36.1 fb-1) || G. Chalons, H. Reyes-Gonzalez || [https://madanalysis.irmp.ucl.ac.be/raw-attachment/wiki/SFS/sfs_atlas_susy_2016_07.cpp Local] || [http://madanalysis.irmp.ucl.ac.be/raw-attachment/wiki/PublicAnalysisDatabase/validation_atlas_susy_16_07.pdf PDF] [http://madanalysis.irmp.ucl.ac.be/raw-attachment/wiki/PublicAnalysisDatabase/pythia_sus_16_07.tgz Pythia files] [https://arxiv.org/abs/2006.09387 arXiv:2006.09387 Sec. 5.2] || v1.8/SFS ||
|| [https://atlas.web.cern.ch/Atlas/GROUPS/PHYSICS/CONFNOTES/ATLAS-CONF-2019-040/ ATLAS-CONF-2019-040]  || Jets + missing transverse momentum (139 fb-1) || F. Ambrogi || [https://old.inspirehep.net/record/1765842/ Inspire] || [http://madanalysis.irmp.ucl.ac.be/raw-attachment/wiki/PublicAnalysisDatabase/atlas_conf_2014_040_validation.pdf PDF] || v1.8/SFS ||

=== CMS analyses, 13 TeV ===
|| '''Analysis''' || ''' Short Description''' || '''Implemented by''' || '''Code''' || '''Validation note''' || '''Version''' ||
|| [http://cms-results.web.cern.ch/cms-results/public-results/publications/SUS-16-048/index.html CMS-SUS-16-048] || Compressed electroweakinos with soft leptons (35.9 fb-1) || B. Fuks || [https://madanalysis.irmp.ucl.ac.be/raw-attachment/wiki/SFS/sfs_cms_sus_16_048.cpp Local] ||  [https://arxiv.org/abs/2002.12220​ Sec. 19 in 2002.12220] [https://arxiv.org/abs/2006.09387 arXiv:2006.09387 Sec. 5.3] ||  v1.8/SFS ||