Belle II Software development
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
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 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 recoilMass (float): invariant mass of recoil in GeV (valid only for recoilmass)
94 daughtersUpdate (bool): make copy of the daughters and update them after the vertex fit
95 smearing (float) : IP tube width is smeared by this value (cm). meaningful only with 'KFit/vertex/iptube' option.
96 path (basf2.Path): modules are added to this path
97 """
98
99 from pdg import from_names
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 pvfit.param('massConstraintList', from_names(massConstraint))
114 path.add_module(pvfit)
115
116
117def kFit(list_name,
118 conf_level,
119 fit_type='vertex',
120 constraint='',
121 daughtersUpdate=False,
122 decay_string='',
123 massConstraint=[],
124 recoilMass=0,
125 smearing=0,
126 path=None):
127 """
128 Perform KFit for each Particle in the given ParticleList.
129
130 Parameters:
131 list_name (str): name of the input ParticleList
132 conf_level (float): minimum value of the confidence level to accept the fit
133 Setting this parameter to -1 selects all particle candidates.
134 The value of 0 rejects particle candidates with a failed fit.
135 fit_type (str): type of the kinematic fit. Valid options are
136
137 * ``mass`` for a mass-constrained fit
138 * ``vertex`` for a vertex fit
139 * ``massvertex`` for a vertex fit with a mass constraint on the mother particle
140 * ``fourC`` for a vertex fit in which the mother particle's four-momentum is constrained to the beam four-momentum
141 * ``massfourC`` for a vertex fit with a 4-momentum constraint and mass constraints on the specified daughter particles
142 * ``recoilmass`` for kinematic fit in which the mass of the mother particle's recoil four-momentum with respect
143 to the beam four-momentum is constrained
144
145 constraint (str): add an additional constraint to the fit (valid options are ipprofile or iptube)
146 massConstraint (list(int) or list(str)): list of PDG ids or Names of the particles which are mass-constrained
147 recoilMass (float): invariant mass of recoil in GeV (valid only for recoilmass)
148 daughtersUpdate (bool): make copy of the daughters and update them after the KFit
149 decay_string (str): select particles used for the KFit
150 smearing (float) : IP tube width is smeared by this value (cm). meaningful only with 'iptube' constraint.
151 path (basf2.Path): modules are added to this path
152 """
153
154 _fitVertex(
155 list_name, conf_level, decay_string, 'KFit', fit_type, constraint,
156 massConstraint, recoilMass, daughtersUpdate, smearing, path)
157
158
159def raveFit(
160 list_name,
161 conf_level,
162 fit_type='vertex',
163 decay_string='',
164 constraint='',
165 daughtersUpdate=False,
166 path=None,
167 silence_warning=False,
168):
169 """
170 Performs a vertex fit using `RAVE <https://github.com/rave-package>`_
171 for each Particle in the given ParticleList.
172
173 Warning:
174 `RAVE <https://github.com/rave-package>`_ is deprecated since it is not maintained.
175 Whilst we will not remove RAVE, it is not recommended for analysis use, other than benchmarking or legacy studies.
176 Instead, we recommend :doc:`TreeFitter` (`vertex.treeFit`) or `vertex.kFit`.
177
178 Parameters:
179 list_name (str): name of the input ParticleList
180 conf_level (float): minimum value of the confidence level to accept the fit.
181 Setting this parameter to -1 selects all particle candidates.
182 The value of 0 rejects the particle candidates with failed fit.
183 fit_type (str): type of the RAVE vertex fit.Valid options are
184
185 * ``mass`` for a mass-constrained fit (the 7x7 error matrix of the mother particle has to be defined)
186 * ``vertex`` for a vertex fit without any mass constraint
187 * ``massvertex`` for a mass-constrained vertex fit
188
189 decay_string (str): select particles used for the vertex fit
190 constraint (str): add additional constraint to the fit
191 (valid options are ipprofile or iptube).
192 daughtersUpdate (bool): make copy of the daughters and update them after the Rave vertex fit
193 path (basf2.Path): modules are added to this path
194 silence_warning (bool): silence the warning advertising TreeFitter use
195 """
196
197 # verbose deprecation message
198 message_a = (
199 "RAVE is deprecated since it is not maintained.\n"
200 "Whilst we will not remove RAVE, it is not recommended for analysis use, other than benchmarking or legacy studies.\n"
201 "Instead, we recommend TreeFitter (treeFit) or KFit.\n"
202 "Try: \n treeFit(\'" + list_name + "\'," + str(conf_level) +
203 ", updateAllDaughters=False, path=mypath)\n"
204 )
205 message_b = "To silence this warning, add silence_warning=True when you call this function."
206
207 # if the user wants a constraint, they should check the doc, or send a ticket if it's not implemented
208 if constraint == '':
209 message_if = ""
210 else:
211 message_if = (
212 "Please consult the documentation at https://software.belle2.org \n"
213 "(search for TreeFitter) for special constraints.\n"
214 )
215
216 if not silence_warning:
217 B2WARNING(message_a + message_if + message_b)
218
219 _fitVertex(list_name, conf_level, decay_string, 'Rave', fit_type, constraint, None, 0, daughtersUpdate, 0, path)
220
221
222def treeFit(
223 list_name,
224 conf_level=0.001,
225 massConstraint=[],
226 ipConstraint=False,
227 updateAllDaughters=False,
228 massConstraintDecayString='',
229 massConstraintMassValues=[],
230 customOriginConstraint=False,
231 customOriginVertex=[0.001, 0, 0.0116],
232 customOriginCovariance=[0.0048, 0, 0, 0, 0.003567, 0, 0, 0, 0.0400],
233 originDimension=3,
234 treatAsInvisible='',
235 ignoreFromVertexFit='',
236 path=None,
237):
238 """
239 Perform a :doc:`TreeFitter` fit for each Particle in the given ParticleList.
240
241 :Example:
242 An example of usage for the decay chain :math:`B^0\\to\\pi^+\\pi^-\\pi^0` is the following:
243
244 ::
245
246 reconstructDecay('pi0:A -> gamma:pi0 gamma:pi0', '0.130 < InvM < 0.14', path=mypath)
247 reconstructDecay('B0:treefit -> pi+:my pi-:my pi0:A ', '', path=mypath)
248 treeFit('B0:treefit', ipConstraint=True, path=mypath)
249
250
251 .. note::
252 The Particle object loaded from the KLMCluster does not have proper covariance matrix yet (by release-06 at least).
253 The performance of TreeFit with these particles is not guaranteed.
254 Alternatively, one can perform the TreeFit ignoring these particles from the vertex fit with
255 the option ``ignoreFromVertexFit``.
256
257
258 Parameters:
259 list_name (str): name of the input ParticleList
260 conf_level (float): minimum value of the confidence level to accept the fit.
261 Setting this parameter to -1 selects all particle candidates.
262 The value of 0 rejects the particle candidates with failed fit.
263 massConstraint (list(int, str)): list of PDG ids (positive and negative values are allowed) or names of the
264 (anti-)particles which are mass-constrained
265 ipConstraint (bool): constrain head production vertex to IP (x-y-z) constraint
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 massConstraintDecayString (str): Decay string to select which particles' mass should be constrained
271 massConstraintMassValues (list(float, int, str)): list of invariant masses to be used for the mass constraints
272 of the particles selected via the decay string massConstraintDecayString. A floating point value is taken directly
273 while an integer or string is interpreted as defining the PDG id or name of a particle
274 and the corresponding PDG value is taken
275 customOriginConstraint (bool): use a custom origin vertex as the production vertex of your particle.
276 This is useful when fitting D*/D without wanting to fit a B but constraining the process to be B-decay-like.
277 (think of semileptonic modes and stuff with a neutrino in the B decay).
278 customOriginVertex (list(float)): 3d vector of the vertex coordinates you want to use as custom origin.
279 Default numbers are taken for B-mesons
280 customOriginCovariance (list(float)): 3x3 covariance matrix for the custom vertex (type: vector).
281 Default numbers extracted from generator distribution width of B-mesons.
282 originDimension (int): If the origin or IP constraint (``customOriginVertex`` or ``ipConstraint``) are used,
283 this specifies the dimension of the constraint (3D or 2D).
284 treatAsInvisible (str): Decay string to select one particle that will be treated as invisible in the fit.
285 ignoreFromVertexFit (str): Decay string to select particles that will be ignored to determine the vertex position.
286 path (basf2.Path): modules are added to this path
287 """
288
289 import pdg
290
291 treeFitter = register_module("TreeFitter")
292 treeFitter.set_name('TreeFitter_' + list_name)
293 if massConstraint:
294 treeFitter.param('massConstraintList', pdg.from_names(massConstraint))
295 treeFitter.param('particleList', list_name)
296 treeFitter.param('confidenceLevel', conf_level)
297 treeFitter.param('ipConstraint', ipConstraint)
298 treeFitter.param('updateAllDaughters', updateAllDaughters)
299 treeFitter.param('customOriginConstraint', customOriginConstraint)
300 treeFitter.param('customOriginVertex', customOriginVertex)
301 treeFitter.param('customOriginCovariance', customOriginCovariance)
302 treeFitter.param('originDimension', originDimension)
303 treeFitter.param('treatAsInvisible', treatAsInvisible)
304 treeFitter.param('ignoreFromVertexFit', ignoreFromVertexFit)
305 treeFitter.param('massConstraintDecayString', massConstraintDecayString)
306 if massConstraintMassValues:
307 treeFitter.param('massConstraintMassValues', [
308 pdg.get(item).Mass() if isinstance(item, (int, str)) else item for item in massConstraintMassValues])
309 path.add_module(treeFitter)
310
311
312def TagV(
313 list_name,
314 MCassociation='',
315 confidenceLevel=0.,
316 trackFindingType="standard_PXD",
317 constraintType="tube",
318 askMCInfo=False,
319 reqPXDHits=0,
320 maskName='all',
321 fitAlgorithm='KFit',
322 kFitReqReducedChi2=5.0,
323 useTruthInFit=False,
324 useRollBack=False,
325 path=None,
326):
327 """
328 For each Particle in the given Breco ParticleList:
329 perform the fit of tag side using the track list from the RestOfEvent dataobject
330 save the MC Btag in case of signal MC
331
332 Parameters:
333
334 list_name (str): name of the input Breco ParticleList
335 MCassociation (str): use standard MC association or the internal one
336 confidenceLevel (float): minimum value of the ConfidenceLevel to accept the fit. 0 selects CL > 0
337 constraintType (str): choose the constraint used in the fit. Can be set to
338
339 * noConstraint;
340 * IP: **default**, tag B constrained to be on the IP;
341 * tube: tube along the tag B line of flight, only for fully reconstructed signal B;
342 * boost: long tube along the boost direction;
343 * (breco): deprecated, but similar to tube;
344
345 trackFindingType (str): choose how to look for tag tracks. Can be set to
346
347 * standard: all tracks except from Kshorts;
348 * standard_PXD: **default**, same as above but consider only tracks with at least 1 PXD hit.
349 If the fit fails, attempt again with the standard option;
350
351 fitAlgorithm (str): Fitter used for the tag vertex fit: Rave or KFit (default)
352 kFitReqReducedChi2 (float): The required chi2/ndf to accept the kFit result, if it is higher, iteration procedure is applied
353 askMCInfo (bool): True when requesting MC Information from the tracks performing the vertex fit
354 reqPXDHits (int): minimum N PXD hits for a track (default is 0)
355 maskName (str): get particles from a specified ROE mask
356 useTruthInFit (bool): True when the tag vertex fit is performed with the true momentum and
357 position of the tracks (default is false). The variable :b2:var:`TagVFitTruthStatus` is set to 1
358 if the truth-matching succeeds and 2 otherwise.
359 useRollBack (bool): True when the tag vertex fit is performed with position of tracks rolled back to
360 position of the mother B (default is false). The variable :b2:var:`TagVRollBackStatus` is set to 1
361 if the truth-matching succeeds and 2 otherwise.
362 path (basf2.Path): modules are added to this path
363
364 Warning:
365 Note that the useFitAlgorithm (str) parameter is deprecated and replaced by constraintType (str)
366 and trackFindingType (str)
367
368 Warning:
369 The trackFindingType ``singleTrack`` and ``singleTrack_PXD`` are broken and **cannot** be used any more.
370 """
371
372 tvfit = register_module('TagVertex')
373 tvfit.set_name('TagVertex_' + list_name)
374 tvfit.param('listName', list_name)
375 tvfit.param('maskName', maskName)
376 tvfit.param('confidenceLevel', confidenceLevel)
377 tvfit.param('MCAssociation', MCassociation)
378 tvfit.param('trackFindingType', trackFindingType)
379 tvfit.param('constraintType', constraintType)
380 tvfit.param('askMCInformation', askMCInfo)
381 tvfit.param('reqPXDHits', reqPXDHits)
382 tvfit.param('fitAlgorithm', fitAlgorithm)
383 tvfit.param('kFitReqReducedChi2', kFitReqReducedChi2)
384 tvfit.param('useTruthInFit', useTruthInFit)
385 tvfit.param('useRollBack', useRollBack)
386 path.add_module(tvfit)
387
388
389def fitPseudo(
390 list_name,
391 path,
392):
393 """
394 Add a pseudo \"vertex fit\" which adds a covariance matrix from the combination of the four-vectors of the daughters.
395 This is similar to BaBar's "Add4" function.
396 It is commonly used for :math:`\\pi^0\\to\\gamma\\gamma` reconstruction where a vertex fit is not possible.
397
398 Here is the basic usage:
399
400 ::
401
402 from modularAnalysis import fitPseudo
403 from stdPi0s import stdPi0s
404 stdPi0s("eff40_May2020", path=mypath)
405 fitPseudo("pi0:eff40_May2020", path=mypath)
406
407 Parameters:
408 list_name (str): the name of the list to add the covariance matrix to
409 path (basf2.Path): modules are added to this path
410 """
411 pseudofit = register_module('PseudoVertexFitter')
412 pseudofit.set_name('PseudoVertexFitter_' + list_name)
413 pseudofit.param('listName', list_name)
414 path.add_module(pseudofit)
415
416
417if __name__ == '__main__':
418 from basf2.utils import pretty_print_module
419 pretty_print_module(__name__, "vertex")
get(name)
Definition pdg.py:48
from_names(names)
Definition pdg.py:74