Jet Substructure

.gitignore

@@ -1,3 +1,139 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# PyCharm type checker
+.idea/
+
+# VScode type checker
+.vscode/
+
  .github_meta.log
 */*.pyc
 */*/*.pyc
@@ -13,5 +149,19 @@ tools/SampleAnalyzer/Test/Makefile_*
 */*/*.log
 doc/??????_mode.log
 doc/??????_mode.pdf
+.ma5history
+architecture.ma5
+setup.sh
+setup.csh
+tools/SampleAnalyzer/Commons/Makefile
+tools/SampleAnalyzer/Configuration/Makefile
+tools/SampleAnalyzer/Process/Makefile
+PortabilityTags.h
 .DS_Store
 ANALYSIS_*
+samples/*
+tools/fastjet
+tools/HEPTopTagger
+tools/zlib
+fastjet-config
+tools/SampleAnalyzer/Bin

README.md

@@ -7,6 +7,8 @@
 
 ![Python v3.8](https://img.shields.io/badge/python-3670A0?style=plastic&logo=python&logoColor=ffdd54&label=3.8&color=brightgreen)
 ![C++](https://img.shields.io/badge/c++-%2300599C.svg?style=plastic&logo=c%2B%2B&logoColor=white&label=11)
+[![CI](https://github.com/MadAnalysis/madanalysis5/actions/workflows/quick_validation.yml/badge.svg?style=plastic)](https://github.com/MadAnalysis/madanalysis5/actions/workflows/quick_validation.yml)
+
 ## Outline
  - [What is MadAnalysis 5?](#what-is-madanalysis-5)
  - [Requirements](#requirements)
@@ -234,7 +236,8 @@ authors thank you for this.
 In the following you can find supported third party software that can be used within MadAnalysis 5.
 The [latest release](https://github.com/MadAnalysis/madanalysis5/releases) of MadAnalysis 5 has been tested with enlisted versions.
 
-- [FastJet](http://fastjet.fr) v3.3.3
+- [FastJet](http://fastjet.fr) v3.4.0
+- [FastJet Contrib](https://fastjet.hepforge.org/contrib/) v1.048
 - [Delphes](https://github.com/delphes/delphes) v3.5.0
 - [ROOT](https://root.cern) v6.04.08
 - [pyhf](https://github.com/scikit-hep/pyhf) v0.7.3

bin/ma5

@@ -74,8 +74,8 @@ sys.path.insert(0, servicedir)
 
 # Release version
 # Do not touch it !!!!!
-version = "1.10.12"
-date = "2023/09/13"
+version = "2.0.8"
+date = "2023/05/31"
 
 # Loading the MadAnalysis session
 import madanalysis.core.launcher

doc/README.md

@@ -16,3 +16,7 @@ Information can also be found in the following files.
                      project from its early days to now.
 - [PAD](./PAD.md): guidelines to submit a new analysis to our Public Analysis Database
                    (PAD).
+
+Further details on the usage of specific modules can be found in the following files:
+- [Jet Substructure](../tools/SampleAnalyzer/Interfaces/substructure/README.md)
+- [HEPTopTagger](../tools/SampleAnalyzer/Interfaces/HEPTopTagger/README.md)

doc/makedoc

@@ -2,11 +2,11 @@
 
 ################################################################################
 #  
-#  Copyright (C) 2012-2018 Eric Conte, Benjamin Fuks
+#  Copyright (C) 2012-2022 Jack Araz, Eric Conte & Benjamin Fuks
 #  The MadAnalysis development team, email: <[email protected]>
-#  
+#
 #  This file is part of MadAnalysis 5.
-#  Official website: <https://launchpad.net/madanalysis5>
+#  Official website: <https://github.com/MadAnalysis/madanalysis5>
 #  
 #  MadAnalysis 5 is free software: you can redistribute it and/or modify
 #  it under the terms of the GNU General Public License as published by

doc/normal_mode/main_normal.tex

@@ -48,14 +48,15 @@
 
 \begin{document}
 \begin{center} 
-{\color{ao} \huge \textbf{\textsc{MadAnalysis} 5 v1.9}} \\ \vspace{0.25cm}
+{\color{ao} \huge \textbf{\textsc{MadAnalysis} 5 v2.0}} \\ \vspace{0.25cm}
 {\color{ao} \huge \textbf{Normal-Mode reference card}} \\ \vspace{0.25cm}
 \vspace{0.1cm} \textsl{\today}\\
 \vspace{0.1cm} \textsl{website: \url{http://madanalysis.irmp.ucl.ac.be/}}\\
 \vspace{0.1cm} \textsl{References:\\ \href{https://arxiv.org/abs/1206.1599}{arXiv:1206.1599 [hep-ph]}, \href{https://arxiv.org/abs/1405.3982}{arXiv:1405.3982 [hep-ph]}, 
 \href{https://arxiv.org/abs/1407.3278}{arXiv:1407.3278 [hep-ph]},\\
 \href{https://arxiv.org/abs/1910.11418}{arXiv:1910.11418 [hep-ph]},
-\href{https://arxiv.org/abs/2006.09387}{arXiv2006.09387 [hep-ph]}
+\href{https://arxiv.org/abs/2006.09387}{arXiv2006.09387 [hep-ph]}, 
+\href{https://arxiv.org/abs/2206.14870}{arXiv: 2206.14870 [hep-ph]}
 }
 \end{center}
 
@@ -604,6 +605,15 @@ \section{\Large Using \FJnorm\ through \MAnorm}\label{sec:fastjet}
   procedure of the CDF reconstruction algorithms.\\
 \color{ao} \verb?spacing? & Grid spacing in the grid jet algorithm.\\
 \color{ao} \verb?ymax? & Maximum rapidity value in the grid jet algorithm.\\
+
+\color{ao} \verb?electron_isocone_radius? & Creates an isolation cone around each electron relative to HCAL deposits.\\
+\color{ao} \verb?muon_isocone_radius? & Creates an isolation cone around each muon relative to HCAL deposits.\\
+\color{ao} \verb?photon_isocone_radius? & Creates an isolation cone around each photon relative to HCAL deposits.\\
+\color{ao} \verb?track_isocone_radius? & Creates an isolation cone around each track relative to HCAL deposits.\\
+
+\color{ao} \verb?particle_propagator? & Enables particle propagator module. Default \verb?off?.\\
+\color{ao} \verb?magnetic_field? & Sets magnetic field strength in T. Default 3.8 T.\\
+
 \hline
 \end{tabular}
 \end{center}
@@ -624,9 +634,15 @@ \section{\Large Using \FJnorm\ through \MAnorm}\label{sec:fastjet}
   a float.\\
 \color{ao} \verb?bjet_id.misid_ljet? & Mistagging rate of a light jet as a $b$-jet,
   as a float.\\
+
+\color{ao} \verb?cjet_id.status? & Enable advanced $c$-jet tagging and mistagging capabilities by setting the flag to \verb?on/off?. Default: \verb?off?.\\
+\color{ao} \verb?cjet_id.exclusive? & Allows several $c$-jets to be issued from a single charmed hadron. Only available if \verb?cjet_id.status? is on.\\
+\color{ao} \verb?cjet_id.matching_dr? & Angular distance parameter allowing us to match a $c$-jet with a given charmed hadron. Only available if \verb?cjet_id.status? is on.\\
+
 \color{ao} \verb?tau_id.efficiency? & Tau-tagging efficiency, as a float.\\
 \color{ao} \verb?tau_id.misid_ljet? &  Mistagging rate of a light jet as a hadronic tau,
    as a float.\\
+   \color{ao} \verb?tau_id.reconstruction_method? & Method to use to reconstruct hadronic taus. Jet-based reconstruction allows for the matching of truth-level taus with jets. Hadron-based reconstruction first finds all hadronic taus in the event, and then uses them as tau objects. Default: \verb?hadron-based?.\\
 \hline
 \end{tabular}
 \end{center}
@@ -756,6 +772,9 @@ \section{\Large Multipartonic matrix element merging}
     object. \\
   \color{ao} \verb?jes?   & Generates a function to scale reconstructed jet energy. \\
   \color{ao} \verb?energy_scaling?   & Generates a function to scale reconstructed object energy. \\
+
+  \color{ao} \verb?jet_algorithm?   & Defines a new jet object. \\
+
     \hline
  \end{tabular}
 \end{center}
@@ -853,7 +872,20 @@ \section{\Large Multipartonic matrix element merging}
 \end{verbatim}}
 Define the rescaling corrections to apply to the energy of a reconstructed object {\tt <p1>}.
 The corresponding energy scaling function is given by {\tt <function>}.
-The bounds correspond to the domain that scaling function applies ({\tt PT > ..., ETA < ...}, etc.).
+The bounds correspond to the domain on which the scaling function applies ({\tt PT > ..., ETA < ...}, etc.).
+
+The \verb?jet_algorithm? submodule can be used following the syntax
+{\color{ao} \begin{verbatim}
+		define jet_algorithm <jet_id> <clustering algorithm> <parameters>
+\end{verbatim}}
+or
+{\color{ao} \begin{verbatim}
+		define jet_algorithm <jet_id> <clustering algorithm> 
+		set <jet_id>.<parameter> = <value>
+\end{verbatim}}
+Here {\tt <jet\_id>} stands for the identifier of this particular jet definition, and can take any value except the same names as event samples. \texttt{<clustering algorithm>} refers to the desired clustering algorithm, and \texttt{<parameters>} are the specific parameters defining the configuration of the clustering algorithm used. Details about the usage of this module both in normal mode and expert mode can be found in {\tt madanalysis5/tools/SampleAnalyzer/Interfaces/substructure/README.md}.
+
+
 %\vspace{3cm}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \begin{shaded}

doc/releases/changelog-v2.0.md

@@ -0,0 +1,77 @@
+# Release 2.0.0-dev (development release)
+
+## New features since last release
+
+* A module allowing for jet substructure studies has been implemented in
+  MadAnalysis 5. [(#13)](https://github.com/MadAnalysis/madanalysis5/pull/13)
+  * It includes the following fastjet-contrib functionalities:
+    * VariableR: normal and expert mode
+    * SoftDrop: expert mode
+    * Clusterer: expert mode
+    * Jet Filtering: expert mode
+    * Reclustering: expert mode
+    * Nsubjettiness: expert mode
+    * Pruner: expert mode
+    * Energy Correlator: expert mode
+    * HEPTopTagger: expert mode
+  * `RecJetFormat` has been wrapped with a `PseudoJet` structure to accommodate
+     dynamic transition between two objects.
+
+  All these methods can be used through the SFS interface.
+
+* Substructure and HEPTopTagger has been redesigned to be shared libraries, so
+  that MadAnalysis could be compiled without these modules as well.
+  [(#63)](https://github.com/MadAnalysis/madanalysis5/pull/63)
+
+* The tagger module has been redesigned to accommodate the features of
+  substructure module.
+  [(#86)](https://github.com/MadAnalysis/madanalysis5/pull/86)
+
+* Multi-level object tagging has been enabled through the SFS framework.
+  ([#97](https://github.com/MadAnalysis/madanalysis5/pull/97))
+  * Option to activate charm-jet tagging has been introduced.
+  * Option to use jet-based hadronic tau matching has been introduced.
+
+* Command to fix random seed has been added.
+  [(#86)](https://github.com/MadAnalysis/madanalysis5/pull/86)
+
+## Improvements
+
+* The SFS libraries are now included in the file `analysisList.h`, instead of in
+  the main analysis file. This leads to much cleaner and independent analysis
+  construction. [(#86)](https://github.com/MadAnalysis/madanalysis5/pull/86)
+
+* Compilation time testing has been added for the jet Substructure and
+  HEPTopTagger interfaces
+  ([#86](https://github.com/MadAnalysis/madanalysis5/pull/86)).
+
+* `fatjet` and `genjet` collections have been merged into `jetcollection` map.
+  ([#135](https://github.com/MadAnalysis/madanalysis5/pull/135))
+
+* Accessors of the `MABoost` class has been extended.
+  [(#13)](https://github.com/MadAnalysis/madanalysis5/pull/13)
+
+## Bug fixes
+
+* Various bugfixes for matching the numeric results to MA5 v1.10.
+  ([#97](https://github.com/MadAnalysis/madanalysis5/pull/97))
+
+* $M_{eff}$ definition has been fixed.
+  [(#86)](https://github.com/MadAnalysis/madanalysis5/pull/86)
+
+* Jet collection accessor has been fixed in DelphesMa5Tune
+  ([#135](https://github.com/MadAnalysis/madanalysis5/pull/135))
+
+* Submit function has been modified to eliminate issues with LHCO
+  reader mentioned in issue [#136](https://github.com/MadAnalysis/madanalysis5/issues/136).
+  ([#167](https://github.com/MadAnalysis/madanalysis5/pull/167))
+
+* Delphes crash fixed due to miscommunication between libraries see issue [#204](https://github.com/MadAnalysis/madanalysis5/issues/204).
+  ([#208](https://github.com/MadAnalysis/madanalysis5/pull/208))
+
+## Contributors
+
+This release contains contributions from (in alphabetical order):
+
+[Jack Y. Araz](https://github.com/jackaraz),
+[Benjamin Fuks](https://github.com/BFuks)