Belle II Software  light-2212-foldex
vertex.py
1 #!/usr/bin/env python3
2 
3 
10 
11 from basf2 import register_module
12 from basf2 import B2WARNING
13 
14 
15 def fitVertex(
16  list_name,
17  conf_level,
18  decay_string='',
19  fitter='KFit',
20  fit_type='vertex',
21  constraint='',
22  massConstraint=[],
23  recoilMass=0,
24  daughtersUpdate=False,
25  smearing=0,
26  path=None,
27 ):
28  """
29  Perform the specified fit for each Particle in the given ParticleList.
30 
31  Info:
32  Direct use of `fitVertex` is not recommended unless you know what you are doing.
33  If you're unsure, you probably want to use `treeFit` or `kFit`.
34 
35  Parameters:
36  list_name (str): name of the input ParticleList
37  conf_level (float): minimum value of the confidence level to accept the fit.
38  Setting this parameter to -1 selects all particle candidates.
39  The value of 0 rejects the particle candidates with failed fit.
40  decay_string (str): select particles used for the vertex fit
41  fitter (str): Rave or KFit
42  fit_type (str): type of the kinematic fit (valid options are vertex/massvertex/mass/fourC/massfourC/recoilmass)
43  constraint (str): add additional constraint to the fit (valid options are empty string/ipprofile/iptube/mother)
44  massConstraint (list(int) or list(str)): list of PDG ids or Names of the particles which are mass-constrained
45  Please do not mix PDG id and particle names in massConstraint list (valid only for massfourC).
46  recoilMass (float): invariant mass of recoil in GeV (valid only for recoilmass)
47  daughtersUpdate (bool): make copy of the daughters and update them after the vertex fit
48  smearing (float) : IP tube width is smeared by this value (cm). meaningful only with 'KFit/vertex/iptube' option.
49  path (basf2.Path): modules are added to this path
50  """
51 
52  warning = (
53  "Direct use of fitVertex is not recommended unless you know what you are doing.\n"
54  "Please use treeFit or kFit.\n"
55  "See documentation at https://software.belle2.org"
56  )
57 
58  B2WARNING(warning)
59 
60  _fitVertex(
61  list_name, conf_level, decay_string, fitter, fit_type, constraint,
62  massConstraint, recoilMass, daughtersUpdate, smearing, path)
63 
64 
65 def _fitVertex(
66  list_name,
67  conf_level,
68  decay_string='',
69  fitter='KFit',
70  fit_type='vertex',
71  constraint='',
72  massConstraint=[],
73  recoilMass=0,
74  daughtersUpdate=False,
75  smearing=0,
76  path=None,
77 ):
78  """
79  An internal function, performs the specified fit for each Particle in the given ParticleList.
80 
81  Warning:
82  This is a private function, please use one of the aliases provided.
83 
84  Parameters:
85  list_name (str): name of the input ParticleList
86  conf_level (float): minimum value of the confidence level to accept the fit.
87  Setting this parameter to -1 selects all particle candidates.
88  The value of 0 rejects the particle candidates with failed fit.
89  decay_string (str): select particles used for the vertex fit
90  fitter (str): Rave or KFit
91  fit_type (str): type of the kinematic fit (valid options are vertex/massvertex/mass/fourC/massfourC/recoilmass)
92  constraint (str): add additional constraint to the fit (valid options are empty string/ipprofile/iptube/mother)
93  massConstraint (list(int) or list(str)): list of PDG ids or Names of the particles which are mass-constrained
94  Please do not mix PDG id and particle names in massConstraint list (valid only for massfourC).
95  recoilMass (float): invariant mass of recoil in GeV (valid only for recoilmass)
96  daughtersUpdate (bool): make copy of the daughters and update them after the vertex fit
97  smearing (float) : IP tube width is smeared by this value (cm). meaningful only with 'KFit/vertex/iptube' option.
98  path (basf2.Path): modules are added to this path
99  """
100 
101  pvfit = register_module('ParticleVertexFitter')
102  pvfit.set_name('ParticleVertexFitter_' + list_name)
103  pvfit.param('listName', list_name)
104  pvfit.param('confidenceLevel', conf_level)
105  pvfit.param('vertexFitter', fitter)
106  pvfit.param('fitType', fit_type)
107  pvfit.param('withConstraint', constraint)
108  pvfit.param('updateDaughters', daughtersUpdate)
109  pvfit.param('decayString', decay_string)
110  pvfit.param('recoilMass', recoilMass)
111  pvfit.param('smearing', smearing)
112  if massConstraint:
113  if isinstance(massConstraint[0], str):
114  pvfit.param('massConstraintListParticlename', massConstraint)
115  else:
116  pvfit.param('massConstraintList', massConstraint)
117  path.add_module(pvfit)
118 
119 
120 def kFit(list_name,
121  conf_level,
122  fit_type='vertex',
123  constraint='',
124  daughtersUpdate=False,
125  decay_string='',
126  massConstraint=[],
127  recoilMass=0,
128  smearing=0,
129  path=None):
130  """
131  Perform KFit for each Particle in the given ParticleList.
132 
133  Parameters:
134  list_name (str): name of the input ParticleList
135  conf_level (float): minimum value of the confidence level to accept the fit
136  Setting this parameter to -1 selects all particle candidates.
137  The value of 0 rejects particle candidates with a failed fit.
138  fit_type (str): type of the kinematic fit. Valid options are
139 
140  * ``mass`` for a mass-constrained fit
141  * ``vertex`` for a vertex fit
142  * ``massvertex`` for a vertex fit with a mass constraint on the mother particle
143  * ``fourC`` for a vertex fit in which the mother particle's four-momentum is constrained to the beam four-momentum
144  * ``massfourC`` for a vertex fit with a 4-momentum constraint and mass constraints on the specified daughter particles
145  * ``recoilmass`` for kinematic fit in which the mass of the mother particle's recoil four-momentum with respect
146  to the beam four-momentum is constrained
147 
148  constraint (str): add an additional constraint to the fit (valid options are ipprofile or iptube)
149  massConstraint (list(int) or list(str)): list of PDG ids or Names of the particles which are mass-constrained
150  Please do not mix PDG id and particle names in massConstraint list (valid only for massfourC).
151  recoilMass (float): invariant mass of recoil in GeV (valid only for recoilmass)
152  daughtersUpdate (bool): make copy of the daughters and update them after the KFit
153  decay_string (str): select particles used for the KFit
154  smearing (float) : IP tube width is smeared by this value (cm). meaningful only with 'iptube' constraint.
155  path (basf2.Path): modules are added to this path
156  """
157 
158  _fitVertex(
159  list_name, conf_level, decay_string, 'KFit', fit_type, constraint,
160  massConstraint, recoilMass, daughtersUpdate, smearing, path)
161 
162 
163 def raveFit(
164  list_name,
165  conf_level,
166  fit_type='vertex',
167  decay_string='',
168  constraint='',
169  daughtersUpdate=False,
170  path=None,
171  silence_warning=False,
172 ):
173  """
174  Performs a vertex fit using `RAVE <https://github.com/rave-package>`_
175  for each Particle in the given ParticleList.
176 
177  Warning:
178  `RAVE <https://github.com/rave-package>`_ is deprecated since it is not maintained.
179  Whilst we will not remove RAVE, it is not recommended for analysis use, other than benchmarking or legacy studies.
180  Instead, we recommend :doc:`TreeFitter` (`vertex.treeFit`) or `vertex.kFit`.
181 
182  Parameters:
183  list_name (str): name of the input ParticleList
184  conf_level (float): minimum value of the confidence level to accept the fit.
185  Setting this parameter to -1 selects all particle candidates.
186  The value of 0 rejects the particle candidates with failed fit.
187  fit_type (str): type of the RAVE vertex fit.Valid options are
188 
189  * ``mass`` for a mass-constrained fit (the 7x7 error matrix of the mother particle has to be defined)
190  * ``vertex`` for a vertex fit without any mass constraint
191  * ``massvertex`` for a mass-constrained vertex fit
192 
193  decay_string (str): select particles used for the vertex fit
194  constraint (str): add additional constraint to the fit
195  (valid options are ipprofile or iptube).
196  daughtersUpdate (bool): make copy of the daughters and update them after the Rave vertex fit
197  path (basf2.Path): modules are added to this path
198  silence_warning (bool): silence the warning advertising TreeFitter use
199  """
200 
201  # verbose deprecation message
202  message_a = (
203  "RAVE is deprecated since it is not maintained.\n"
204  "Whilst we will not remove RAVE, it is not recommended for analysis use, other than benchmarking or legacy studies.\n"
205  "Instead, we recommend TreeFitter (treeFit) or KFit.\n"
206  "Try: \n treeFit(\'" + list_name + "\'," + str(conf_level) +
207  ", updateAllDaughters=False, path=mypath)\n"
208  )
209  message_b = "To silence this warning, add silence_warning=True when you call this function."
210 
211  # if the user wants a constraint, they should check the doc, or send a ticket if it's not implemented
212  if constraint == '':
213  message_if = ""
214  else:
215  message_if = (
216  "Please consult the documentation at https://software.belle2.org \n"
217  "(search for TreeFitter) for special constraints.\n"
218  )
219 
220  if not silence_warning:
221  B2WARNING(message_a + message_if + message_b)
222 
223  _fitVertex(list_name, conf_level, decay_string, 'Rave', fit_type, constraint, None, 0, daughtersUpdate, 0, path)
224 
225 
226 def treeFit(
227  list_name,
228  conf_level=0.001,
229  massConstraint=[],
230  ipConstraint=False,
231  updateAllDaughters=False,
232  customOriginConstraint=False,
233  customOriginVertex=[0.001, 0, 0.0116],
234  customOriginCovariance=[0.0048, 0, 0, 0, 0.003567, 0, 0, 0, 0.0400],
235  originDimension=3,
236  treatAsInvisible='',
237  path=None,
238 ):
239  """
240  Perform a :doc:`TreeFitter` fit for each Particle in the given ParticleList.
241 
242  :Example:
243  An example of usage for the decay chain :math:`B^0\\to\\pi^+\\pi^-\\pi^0` is the following:
244 
245  ::
246 
247  reconstructDecay('pi0:A -> gamma:pi0 gamma:pi0', '0.130 < InvM < 0.14', path=mypath)
248  reconstructDecay('B0:treefit -> pi+:my pi-:my pi0:A ', '', path=mypath)
249  treeFit('B0:treefit', ipConstraint=True, path=mypath)
250 
251  Parameters:
252  list_name (str): name of the input ParticleList
253  conf_level (float): minimum value of the confidence level to accept the fit.
254  Setting this parameter to -1 selects all particle candidates.
255  The value of 0 rejects the particle candidates with failed fit.
256  massConstraint (list(int) or list(str)): list of PDG ids or Names of the particles which are mass-constrained
257  Please do not mix PDG id and particle names in massConstraint list.
258  ipConstraint (bool): constrain head production vertex to IP (x-y-z) constraint
259  customOriginConstraint (bool): use a custom origin vertex as the production vertex of your particle.
260  This is useful when fitting D*/D without wanting to fit a B but constraining the process to be B-decay-like.
261  (think of semileptonic modes and stuff with a neutrino in the B decay).
262  customOriginVertex (list(float)): 3d vector of the vertex coordinates you want to use as custom origin.
263  Default numbers are taken for B-mesons
264  customOriginCovariance (list(float)): 3x3 covariance matrix for the custom vertex (type: vector).
265  Default numbers extracted from generator distribution width of B-mesons.
266  updateAllDaughters (bool): if true the entire tree will be updated with the fitted values
267  for momenta and vertex position. Otherwise only the momenta of the head of the tree will be updated,
268  however for all daughters we also update the vertex position with the fit results as this would
269  otherwise be set to {0, 0, 0} contact us if this causes any hardship/confusion.
270  originDimension (int): If the origin or IP constraint (``customOriginVertex`` or ``ipConstraint``) are used,
271  this specifies the dimension of the constraint (3D or 2D).
272  treatAsInvisible (str): Decay string to select one particle that will be treated as invisible in the fit.
273  path (basf2.Path): modules are added to this path
274  """
275  treeFitter = register_module("TreeFitter")
276  treeFitter.set_name('TreeFitter_' + list_name)
277  if massConstraint:
278  if isinstance(massConstraint[0], str):
279  treeFitter.param('massConstraintListParticlename', massConstraint)
280  else:
281  treeFitter.param('massConstraintList', massConstraint)
282  treeFitter.param('particleList', list_name)
283  treeFitter.param('confidenceLevel', conf_level)
284  treeFitter.param('ipConstraint', ipConstraint)
285  treeFitter.param('updateAllDaughters', updateAllDaughters)
286  treeFitter.param('customOriginConstraint', customOriginConstraint)
287  treeFitter.param('customOriginVertex', customOriginVertex)
288  treeFitter.param('customOriginCovariance', customOriginCovariance)
289  treeFitter.param('originDimension', originDimension)
290  treeFitter.param('treatAsInvisible', treatAsInvisible)
291  path.add_module(treeFitter)
292 
293 
294 def TagV(
295  list_name,
296  MCassociation='',
297  confidenceLevel=0.,
298  trackFindingType="standard_PXD",
299  constraintType="tube",
300  askMCInfo=False,
301  reqPXDHits=0,
302  maskName='all',
303  fitAlgorithm='KFit',
304  kFitReqReducedChi2=5.0,
305  useTruthInFit=False,
306  useRollBack=False,
307  path=None,
308 ):
309  """
310  For each Particle in the given Breco ParticleList:
311  perform the fit of tag side using the track list from the RestOfEvent dataobject
312  save the MC Btag in case of signal MC
313 
314  Parameters:
315 
316  list_name (str): name of the input Breco ParticleList
317  MCassociation (str): use standard MC association or the internal one
318  confidenceLevel (float): minimum value of the ConfidenceLevel to accept the fit. 0 selects CL > 0
319  constraintType (str): choose the constraint used in the fit. Can be set to
320 
321  * noConstraint;
322  * IP: **default**, tag B constrained to be on the IP;
323  * tube: tube along the tag B line of flight, only for fully reconstructed signal B;
324  * boost: long tube along the boost direction;
325  * (breco): deprecated, but similar to tube;
326 
327  trackFindingType (str): choose how to look for tag tracks. Can be set to
328 
329  * standard: all tracks except from Kshorts;
330  * standard_PXD: **default**, same as above but consider only tracks with at least 1 PXD hit.
331  If the fit fails, attempt again with the standard option;
332 
333  fitAlgorithm (str): Fitter used for the tag vertex fit: Rave or KFit (default)
334  kFitReqReducedChi2 (float): The required chi2/ndf to accept the kFit result, if it is higher, iteration procedure is applied
335  askMCInfo (bool): True when requesting MC Information from the tracks performing the vertex fit
336  reqPXDHits (int): minimum N PXD hits for a track (default is 0)
337  maskName (str): get particles from a specified ROE mask
338  useTruthInFit (bool): True when the tag vertex fit is performed with the true momentum and
339  position of the tracks (default is false). The variable :b2:var:`TagVFitTruthStatus` is set to 1
340  if the truth-matching succeeds and 2 otherwise.
341  useRollBack (bool): True when the tag vertex fit is performed with position of tracks rolled back to
342  position of the mother B (default is false). The variable :b2:var:`TagVRollBackStatus` is set to 1
343  if the truth-matching succeeds and 2 otherwise.
344  path (basf2.Path): modules are added to this path
345 
346  Warning:
347  Note that the useFitAlgorithm (str) parameter is deprecated and replaced by constraintType (str)
348  and trackFindingType (str)
349 
350  Warning:
351  The trackFindingType ``singleTrack`` and ``singleTrack_PXD`` are broken and **cannot** be used any more.
352  """
353 
354  tvfit = register_module('TagVertex')
355  tvfit.set_name('TagVertex_' + list_name)
356  tvfit.param('listName', list_name)
357  tvfit.param('maskName', maskName)
358  tvfit.param('confidenceLevel', confidenceLevel)
359  tvfit.param('MCAssociation', MCassociation)
360  tvfit.param('trackFindingType', trackFindingType)
361  tvfit.param('constraintType', constraintType)
362  tvfit.param('askMCInformation', askMCInfo)
363  tvfit.param('reqPXDHits', reqPXDHits)
364  tvfit.param('fitAlgorithm', fitAlgorithm)
365  tvfit.param('kFitReqReducedChi2', kFitReqReducedChi2)
366  tvfit.param('useTruthInFit', useTruthInFit)
367  tvfit.param('useRollBack', useRollBack)
368  path.add_module(tvfit)
369 
370 
371 def fitPseudo(
372  list_name,
373  path,
374 ):
375  """
376  Add a pseudo \"vertex fit\" which adds a covariance matrix from the combination of the four-vectors of the daughters.
377  This is similar to BaBar's "Add4" function.
378  It is commonly used for :math:`\\pi^0\\to\\gamma\\gamma` reconstruction where a vertex fit is not possible.
379 
380  Here is the basic usage:
381 
382  ::
383 
384  from modularAnalysis import fitPseudo
385  from stdPi0s import stdPi0s
386  stdPi0s("eff40_May2020", path=mypath)
387  fitPseudo("pi0:eff40_May2020", path=mypath)
388 
389  Parameters:
390  list_name (str): the name of the list to add the covariance matrix to
391  path (basf2.Path): modules are added to this path
392  """
393  pseudofit = register_module('PseudoVertexFitter')
394  pseudofit.set_name('PseudoVertexFitter_' + list_name)
395  pseudofit.param('listName', list_name)
396  path.add_module(pseudofit)
397 
398 
399 if __name__ == '__main__':
400  from basf2.utils import pretty_print_module
401  pretty_print_module(__name__, "vertex")