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