New PID Substitution DaVinci Tool

Start from #305 (closed), implementing the comment #305 (comment 5363235).

This MR will add a new PID substitution Tool and a new DTF Tool for DaVinci, which has integrated the PID substitution. A minimal example of the usage could be:

DTF_KstG = DecayTreeFitter(
    Name = 'DTF_KstG',
    Input = B_Data,
    Substitutions = [
        ' B0 ->  ( K*(892)0 ->  K+ K-{{pi-}} ) gamma',
    ]
)
variables_all = FC({
    # Original particle
    'ORIGINAL_ID'      : F.PARTICLE_ID,
    'ORIGINAL_ENERGY'  : F.ENERGY,
    'ORIGINAL_CHI2DOF' : F.CHI2DOF,
    # DTF Bd2KstGamma
    'DTF_KSTG_ID'      : F.VALUE_OR(-1) @ DTF_KstG.get_info( F.PARTICLE_ID ),
    'DTF_KSTG_ENERGY'  : DTF_KstG.get_info( F.ENERGY      ),
    'DTF_KSTG_CHI2DOF' : DTF_KstG.get_info( F.CHI2DOF     ),
})

A real example could be found in https://gitlab.cern.ch/lhcb/DaVinci/-/blob/jzhuo_SubsPID/DaVinciExamples/python/DaVinciExamples/tupling/option_davinci_tupling_DTF_substitutePID.py

Other example for SubstitutePID without DTF could be found in https://gitlab.cern.ch/lhcb/DaVinci/-/blob/jzhuo_SubsPID/DaVinciExamples/python/DaVinciExamples/tupling/option_davinci_tupling_substitutePID.py

This MR should be test with DaVinci!756 (merged)

FYI: @amathad @pkoppenb @erodrigu @fevolle

Closes #305 (closed) Closes #309 (closed)

Phys/DaVinciTools/python/DaVinciTools/SubstitutePID.py

+###############################################################################
+# (c) Copyright 2022 CERN for the benefit of the LHCb Collaboration           #
+#                                                                             #
+# This software is distributed under the terms of the GNU General Public      #
+# Licence version 3 (GPL Version 3), copied verbatim in the file "COPYING".   #
+#                                                                             #
+# In applying this licence, CERN does not waive the privileges and immunities #
+# granted to it by virtue of its status as an Intergovernmental Organization  #
+# or submit itself to any jurisdiction.                                       #
+###############################################################################
+
+from PyConf.dataflow import DataHandle
+from Gaudi.Configuration import INFO, DEBUG, VERBOSE, ALL
+from Functors.grammar import BoundFunctor
+from PyConf.Algorithms import SubstitutePIDAlg_Particles
+import Functors as F
+import re
+
+
+class SubstitutePID:
+    """
+    Python tool to help with the configuration of the PID substitution `SubstitutePIDAlg_Particles`
+    and the creation of functors to access the necessary information.
+
+    .. note::
+        You can configure the mass hypothesis subsitution using the following syntax:
+            ' Old_PID{{New_PID}} '
+
+        The '[]cc' syntax is not yet supported in the SubstitutePID tool, you have to
+        specify the substitution rule explicitly for each cc case.
+        e.g.
+        '[B+ -> K+ K+ K-{{pi-}}]cc' => ['B+ -> K+ K+ K-{{pi-}}', 'B- -> K- K- K+{{pi+}}']
+
+    Args:
+        name (str): name of the substitution algorithm, will printed in the Gaudi.
+        substitutions (list): substitution rules, using the substitution syntax.
+        input (DataHandle): the input data handle (TES)
+        output_level (int, optional): standard Gaudi Algorithm OutputLevel.
+
+    Example:
+        # Create the tool
+        Subs_PhiG = SubstitutePID(
+            name = 'Subs_PhiG',
+            input = B_Data,
+            substitutions = [
+                'B0{{B_s0}} -> ( K*(892)0{{phi(1020)}} ->  K+ K- ) gamma'
+            ]
+        )
+
+        Subs_KstG = SubstitutePID(
+            name = 'Subs_KstG',
+            input = B_Data,
+            substitutions = [
+                'B0 -> ( K*(892)0 -> K+ K-{{pi-}} ) gamma'
+            ]
+        )
+
+        # Get the energy of the substituted particle
+        allvariables['ENERGY'] = F.ENERGY
+        allvariables['PhiG_ENERGY'] = Subs_PhiG.get_info( F.ENERGY )
+        allvariables['KstG_ENERGY'] = Subs_KstG.get_info( F.ENERGY )
+    """
+
+    def __init__(self,
+                 name: str,
+                 input: DataHandle,
+                 substitutions: list,
+                 output_level=INFO):
+        # Check
+        if not substitutions:
+            raise ValueError("The 'substitutions' rules can't be empty.")
+
+        for Subs in substitutions:
+            if Subs.lower().find(']cc') != -1:
+                raise ValueError(
+                    "The '[]cc' syntax is not yet supported in the SubstitutePID tool. "
+                    "You have to specify the substitution rule explicitly for each cc case."
+                )
+
+        # Extend subsitituions
+        subsitution_map = self._get_subsitution_map(substitutions,
+                                                    output_level)
+
+        # Find all possible decays
+        decays = []
+        for decay_descriptor, _ in subsitution_map.items():
+            simple_descriptor = decay_descriptor.replace('^', ' ')
+            repeated = False
+            for decay in decays:
+                if decay.replace(' ', '') == simple_descriptor.replace(
+                        ' ', ''):
+                    repeated = True
+                    break
+            if not repeated:
+                decays.append(simple_descriptor)
+
+        # Create gaudi algorithm
+        self.Algorithm = SubstitutePIDAlg_Particles(
+            name=name,
+            Input=input,
+            Decays=decays,
+            Substitute=subsitution_map,
+            OutputLevel=output_level)
+
+        # Store the algorithm result
+        self.AllParticles = self.Algorithm.AllParticles
+        self.Particles = self.Algorithm.Particles
+        self.Relation = self.Algorithm.Relation
+
+    def get_info(self, Functor: BoundFunctor):
+        """
+        Apply a specified functor to the result particle of substitution
+
+        Args:
+            Functor (BoundFunctor): the functor to be applied
+
+        Return:
+            BoundFunctor: result functor
+
+        Example:
+            variables['SUBS_CHI2DOF'] = Subs.get_info(F.CHI2DOF)
+        """
+        return F.MAP_INPUT(Functor, self.Relation)
+
+    def _get_subsitution_map(self, substitutions: list, output_level):
+
+        if output_level in {DEBUG, VERBOSE, ALL}:
+            print("==============================")
+            print(
+                "SubstitutePID will extend the substitution rules to the following substitution map:"
+            )
+            print("{")
+
+        # Compile the regex
+        find_subs = re.compile(r'{{(.*?)}}')
+
+        substitution_map = {}
+        for substitution in substitutions:
+            # Find the targets
+            targets = find_subs.findall(substitution)
+
+            pos = 0
+            for target in targets:
+
+                # Find target
+                target_full = '{{' + target + '}}'
+                target_start = substitution.find(target_full, pos + 1)
+                target_end = target_start + len(target_full)
+                pos = target_end
+
+                # Find origin
+                origin_start = max(
+                    substitution.rfind(' ', 0, target_start) + 1, 0)
+                if substitution[origin_start] == '(':
+                    origin_start += 1
+
+                origin_end = target_start
+                origin = substitution[origin_start:origin_end]
+
+                # Extend substitution rule
+                add_hat = substitution[
+                    0:origin_start] + '^' + origin + substitution[target_end:]
+                remove_else = find_subs.sub('', add_hat)
+
+                substitution_map[remove_else] = target
+
+        if output_level in {DEBUG, VERBOSE, ALL}:
+            for key, value in substitution_map.items():
+                print(f"\t '{key}' : '{value}',")
+
+        if output_level in {DEBUG, VERBOSE, ALL}:
+            print("}")
+            print("==============================")
+
+        return substitution_map