Skip to content

kinematics

analysis_helpers.kinematics

ip_all(a_x, a_y, a_z, n_x, n_y, n_z, p_x, p_y, p_z)

Function to calculate the impact parameter of a point \(\vec{p}\) from a line passing from a point \(\vec{a}\) and having direction \(\vec{n}\)

Parameters:

Name Type Description Default
a_x, a_y, a_z (float, float, float)

coordinates (x,y,z) of a point on the line

 required
n_x, n_y, n_z (float, float, float)

magnitudes (x,y,z) of the unit vector of the line direction

 required
p_x. p_y, p_z (float, float, float)

coordinates (x,y,z) of the point

 required
Source code in src/analysis_helpers/kinematics.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
def ip_all(a_x,a_y,a_z,n_x,n_y,n_z,p_x,p_y,p_z):
    r"""Function to calculate the impact parameter of a point $\vec{p}$ from a line 
    passing from a point $\vec{a}$ and having direction $\vec{n}$

    Args:
        a_x, a_y, a_z (float,float,float): coordinates (x,y,z) of a point on the line
        n_x, n_y, n_z (float,float,float): magnitudes (x,y,z) of the unit vector of the line direction
        p_x. p_y, p_z (float,float,float): coordinates (x,y,z) of the point
    """
    p_min_a_x = p_x-a_x
    p_min_a_y = p_y-a_y
    p_min_a_z = p_z-a_z
    #
    cross_p_x = p_min_a_y*n_z- n_y*p_min_a_z
    cross_p_y = p_min_a_z*n_x- n_z*p_min_a_x
    cross_p_z = p_min_a_x*n_y- n_x*p_min_a_y
    #
    num = np.sqrt(cross_p_x*cross_p_x + cross_p_y*cross_p_y + cross_p_z*cross_p_z)
    den = np.sqrt(n_x*n_x + n_y*n_y + n_z*n_z)
    return num/den

doca(Ax, Ay, Az, Atx, Aty, Bx, By, Bz, Btx, Bty)

Calculate the Distance of Closest Approach (DOCA) between two lines in 3D space.

Parameters:

Name Type Description Default
Ax float

x-coordinate of a point on line A

 required
Ay float

y-coordinate of a point on line A

 required
Az float

z-coordinate of a point on line A

 required
Atx float

x-component of the local direction (slope) vector of line A

 required
Aty float

y-component of the local direction (slope) vector of line A

 required
Bx float

x-coordinate of a point on line B

 required
By float

y-coordinate of a point on line B

 required
Bz float

z-coordinate of a point on line B

 required
Btx float

x-component of the local direction (slope) vector of line B

 required
Bty float

y-component of the local direction (slope) vector of line B

 required

Returns:

Name Type Description
float

the Distance of Closest Approach (DOCA) between the two lines
Source code in src/analysis_helpers/kinematics.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def doca(Ax,Ay,Az,Atx,Aty,
         Bx,By,Bz,Btx,Bty):
    r"""Calculate the Distance of Closest Approach (DOCA) between two lines in 3D space.

    Args:
        Ax (float): x-coordinate of a point on line A
        Ay (float): y-coordinate of a point on line A
        Az (float): z-coordinate of a point on line A
        Atx (float): x-component of the local direction (slope) vector of line A
        Aty (float): y-component of the local direction (slope) vector of line A
        Bx (float): x-coordinate of a point on line B
        By (float): y-coordinate of a point on line B
        Bz (float): z-coordinate of a point on line B
        Btx (float): x-component of the local direction (slope) vector of line B
        Bty (float): y-component of the local direction (slope) vector of line B

    Returns:
        float: the Distance of Closest Approach (DOCA) between the two lines
    """    
    secondAA =  Atx * Atx + Aty * Aty + 1.
    secondBB =  Btx * Btx + Bty * Bty + 1.
    secondAB = -Atx * Btx - Aty * Bty - 1.
    det = secondAA * secondBB - secondAB * secondAB
    #ret = -1.
    #if type(det) == ak.highlevel.Array: det = det.to_numpy()
    #if np.abs(det) > 0:
    secondinvAA =  secondBB / det
    secondinvBB =  secondAA / det
    secondinvAB = -secondAB / det
    firstA =  Atx * (Ax - Bx) + Aty * (Ay - By) + (Az - Bz)
    firstB = -Btx * (Ax - Bx) - Bty * (Ay - By) - (Az - Bz)
    muA = -(secondinvAA * firstA + secondinvAB * firstB)
    muB = -(secondinvBB * firstB + secondinvAB * firstA)
    dx = (Ax + muA * Atx) - (Bx + muB * Btx)
    dy = (Ay + muA * Aty) - (By + muB * Bty)
    dz = (Az + muA) - (Bz + muB)
    ret = np.sqrt(dx * dx + dy * dy + dz * dz)
    return ret

dira(Px, Py, Pz, Vx, Vy, Vz, PVx, PVy, PVz)

Calculate the Directional Angle (DIRA) between a particle and a vertex.

Parameters:

Name Type Description Default
Px float

x-component of the particle's momentum

 required
Py float

y-component of the particle's momentum

 required
Pz float

z-component of the particle's momentum

 required
Vx float

x-coordinate of the vertex

 required
Vy float

y-coordinate of the vertex

 required
Vz float

z-coordinate of the vertex

 required
PVx float

x-coordinate of the primary vertex

 required
PVy float

y-coordinate of the primary vertex

 required
PVz float

z-coordinate of the primary vertex

 required

Returns:

Name Type Description
float

the Directional Angle (DIRA) between the particle and the vertex
Source code in src/analysis_helpers/kinematics.py 
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def dira(Px,Py,Pz,
         Vx,Vy,Vz,
         PVx,PVy,PVz):
    """Calculate the Directional Angle (DIRA) between a particle and a vertex.

    Args:
        Px (float): x-component of the particle's momentum
        Py (float): y-component of the particle's momentum
        Pz (float): z-component of the particle's momentum
        Vx (float): x-coordinate of the vertex
        Vy (float): y-coordinate of the vertex
        Vz (float): z-coordinate of the vertex
        PVx (float): x-coordinate of the primary vertex
        PVy (float): y-coordinate of the primary vertex
        PVz (float): z-coordinate of the primary vertex

    Returns:
        float: the Directional Angle (DIRA) between the particle and the vertex
    """    
    dx, dy, dz = Vx-PVx, Vy-PVy, Vz-PVz
    fd = np.sqrt(dx*dx+dy*dy+dz*dz)
    p = np.sqrt(Px*Px+Py*Py+Pz*Pz)
    dira = np.nan_to_num( (dx*Px + dy*Py + dz*Pz) / (p*fd), nan=0, posinf=np.inf, neginf=-np.inf)
    return dira

opening_angle(P1x, P1y, P1z, P2x, P2y, P2z)

Calculate the opening angle between two 3D vectors.

Parameters:

Name Type Description Default
P1x float

x-component of the first vector

 required
P1y float

y-component of the first vector

 required
P1z float

z-component of the first vector

 required
P2x float

x-component of the second vector

 required
P2y float

y-component of the second vector

 required
P2z float

z-component of the second vector

 required

Returns:

Name Type Description
float

the opening angle between the two vectors
Source code in src/analysis_helpers/kinematics.py 
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
def opening_angle(P1x,P1y,P1z,
                  P2x,P2y,P2z):
    """Calculate the opening angle between two 3D vectors.

    Args:
        P1x (float): x-component of the first vector
        P1y (float): y-component of the first vector
        P1z (float): z-component of the first vector
        P2x (float): x-component of the second vector
        P2y (float): y-component of the second vector
        P2z (float): z-component of the second vector

    Returns:
        float: the opening angle between the two vectors
    """    
    P1_tx,P1_ty,P2_tx,P2_ty = P1x/P1z, P1y/P1z, P2x/P2z, P2y/P2z
    oa_norm = np.sqrt( (P1_tx*P1_tx + P1_ty*P1_ty + 1) * (P2_tx*P2_tx + P2_ty*P2_ty + 1) )
    oa_arg  = (P1_tx * P2_tx + P1_ty * P2_ty + 1.) / oa_norm
    opening_angle = np.nan_to_num( np.arccos(oa_arg), nan=0, posinf=np.inf, neginf=-np.inf)
    return opening_angle

ctau(L, m, p)

Calculate the proper time (CTAU) of a particle.

Parameters:

Name Type Description Default
L float

length of the particle's trajectory in millimeters

 required
m float

mass of the particle in MeV/c^2

 required
p float

momentum of the particle in MeV/c per millimeter

 required

Returns:

Name Type Description
float

proper time (CTAU) of the particle in millimeters
Source code in src/analysis_helpers/kinematics.py 
129
130
131
132
133
134
135
136
137
138
139
140
141
def ctau(L,m,p):
    """Calculate the proper time (CTAU) of a particle.

    Args:
        L (float): length of the particle's trajectory in millimeters
        m (float): mass of the particle in MeV/c^2
        p (float): momentum of the particle in MeV/c per millimeter

    Returns:
        float: proper time (CTAU) of the particle in millimeters
    """    
    ct = m*L/p # mm
    return ct

ctau_from_tau(tau)

Calculate the proper time (CTAU) from the lifetime (TAU) of a particle.

Parameters:

Name Type Description Default
tau float

lifetime of the particle in nanoseconds

 required

Returns:

Name Type Description
float

proper time (CTAU) of the particle in millimeters
Source code in src/analysis_helpers/kinematics.py 
143
144
145
146
147
148
149
150
151
152
153
def ctau_from_tau(tau):
    """Calculate the proper time (CTAU) from the lifetime (TAU) of a particle.

    Args:
        tau (float): lifetime of the particle in nanoseconds

    Returns:
        float: proper time (CTAU) of the particle in millimeters
    """    
    # from ns to mm
    return  tau * scipy.constants.c / 1e6

distance(x0, y0, z0, x1, y1, z1)

Calculate the distance between two points in 3D space.

Parameters:

Name Type Description Default
x0 float

x-coordinate of the first point

 required
y0 float

y-coordinate of the first point

 required
z0 float

z-coordinate of the first point

 required
x1 float

x-coordinate of the second point

 required
y1 float

y-coordinate of the second point

 required
z1 float

z-coordinate of the second point

 required

Returns:

Name Type Description
float

distance between the two points
Source code in src/analysis_helpers/kinematics.py 
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def distance(x0,y0,z0,x1,y1,z1):
    """Calculate the distance between two points in 3D space.

    Args:
        x0 (float): x-coordinate of the first point
        y0 (float): y-coordinate of the first point
        z0 (float): z-coordinate of the first point
        x1 (float): x-coordinate of the second point
        y1 (float): y-coordinate of the second point
        z1 (float): z-coordinate of the second point

    Returns:
        float: distance between the two points
    """    
    dl = np.sqrt( (x0-x1)*(x0-x1) + (y0-y1)*(y0-y1) + (z0-z1)*(z0-z1) )
    return dl

mass(px, py, pz, pe)

Calculate the invariant mass (M) of a particle.

Parameters:

Name Type Description Default
px float

x-component of the particle's momentum

 required
py float

y-component of the particle's momentum

 required
pz float

z-component of the particle's momentum

 required
pe float

energy of the particle

 required

Returns:

Name Type Description
float

invariant mass of the particle
Source code in src/analysis_helpers/kinematics.py 
172
173
174
175
176
177
178
179
180
181
182
183
184
def mass(px,py,pz,pe):
    """Calculate the invariant mass (M) of a particle.

    Args:
        px (float): x-component of the particle's momentum
        py (float): y-component of the particle's momentum
        pz (float): z-component of the particle's momentum
        pe (float): energy of the particle

    Returns:
        float: invariant mass of the particle
    """
    return _vector_object(px=px, py=py, pz=pz, E=pe).mass

momentum(px, py, pz)

Calculate the momentum (P) of a particle.

Parameters:

Name Type Description Default
px float

x-component of the particle's momentum

 required
py float

y-component of the particle's momentum

 required
pz float

z-component of the particle's momentum

 required

Returns:

Name Type Description
float

momentum of the particle
Source code in src/analysis_helpers/kinematics.py 
186
187
188
189
190
191
192
193
194
195
196
197
def momentum(px,py,pz):
    """Calculate the momentum (P) of a particle.

    Args:
        px (float): x-component of the particle's momentum
        py (float): y-component of the particle's momentum
        pz (float): z-component of the particle's momentum

    Returns:
        float: momentum of the particle
    """
    return _vector_object(px=px, py=py, pz=pz).mag

pt(px, py)

Calculate the transverse momentum (PT) of a particle.

Parameters:

Name Type Description Default
px float

x-component of the particle's momentum

 required
py float

y-component of the particle's momentum

 required

Returns:

Name Type Description
float

transverse momentum of the particle
Source code in src/analysis_helpers/kinematics.py 
199
200
201
202
203
204
205
206
207
208
209
210
def pt(px,py):
    """Calculate the transverse momentum (PT) of a particle.

    Args:
        px (float): x-component of the particle's momentum
        py (float): y-component of the particle's momentum

    Returns:
        float: transverse momentum of the particle
    """
    pz = 0.0 if np.ndim(px) == 0 else np.zeros_like(np.asarray(px, dtype=float))
    return _vector_object(px=px, py=py, pz=pz).pt

slope(pa, pz)

Calculate the slope of a particle.

Parameters:

Name Type Description Default
pa float

transverse momentum of the particle

 required
pz float

longitudinal momentum of the particle

 required

Returns:

Name Type Description
float

slope of the particle
Source code in src/analysis_helpers/kinematics.py 
212
213
214
215
216
217
218
219
220
221
222
223
def slope(pa,pz):
    """Calculate the slope of a particle.

    Args:
        pa (float): transverse momentum of the particle
        pz (float): longitudinal momentum of the particle

    Returns:
        float: slope of the particle
    """    
    t = pa/pz
    return t

pseudorapidity(px, py, pz)

Calculate the pseudorapidity (ETA) of a particle.

Parameters:

Name Type Description Default
px float

x-component of the particle's momentum

 required
py float

y-component of the particle's momentum

 required
pz float

z-component of the particle's momentum

 required

Returns:

Name Type Description
float

the pseudorapidity (ETA) of the particle
Source code in src/analysis_helpers/kinematics.py 
225
226
227
228
229
230
231
232
233
234
235
236
def pseudorapidity(px,py,pz):
    """Calculate the pseudorapidity (ETA) of a particle.

    Args:
        px (float): x-component of the particle's momentum
        py (float): y-component of the particle's momentum
        pz (float): z-component of the particle's momentum

    Returns:
        float: the pseudorapidity (ETA) of the particle
    """
    return _vector_object(px=px, py=py, pz=pz).eta

phi(px, py, pz)

Calculate the azimuthal angle (PHI) of a particle.

Parameters:

Name Type Description Default
px float

x-component of the particle's momentum

 required
py float

y-component of the particle's momentum

 required
pz float

z-component of the particle's momentum

 required

Returns:

Name Type Description
float

the azimuthal angle (PHI) of the particle
Source code in src/analysis_helpers/kinematics.py 
238
239
240
241
242
243
244
245
246
247
248
249
def phi(px,py,pz):
    """Calculate the azimuthal angle (PHI) of a particle.

    Args:
        px (float): x-component of the particle's momentum
        py (float): y-component of the particle's momentum
        pz (float): z-component of the particle's momentum

    Returns:
        float: the azimuthal angle (PHI) of the particle
    """
    return _vector_object(px=px, py=py, pz=pz).phi

estar2(m12, masses)

Calculate the energy of one of the daughter particles in the rest frame (E*) of a specific two-body subsystem.

Parameters:

Name Type Description Default
m12 float

invariant mass of the first two particles

 required
masses list

list of masses of the four particles

 required

Returns:

Name Type Description
float

the E* of the two-body system
Source code in src/analysis_helpers/kinematics.py 
251
252
253
254
255
256
257
258
259
260
261
262
263
264
def estar2(m12,masses):
    """Calculate the energy of one of the daughter particles in the rest frame (E*) of a specific two-body subsystem.

    Args:
        m12 (float): invariant mass of the first two particles
        masses (list): list of masses of the four particles

    Returns:
        float: the E* of the two-body system
    """
    masses = _validate_four_masses(masses)
    Est2 = m12*m12 - masses[1]*masses[1] + masses[2]*masses[2]
    Est2/= 2*m12
    return Est2

estar3(m12, masses)

Calculate the energy of one of the daughter particles in the rest frame (E*) of a specific three-body system.

Parameters:

Name Type Description Default
m12 float

invariant mass of the first two particles

 required
masses list

list of masses of the four particles

 required

Returns:

Name Type Description
float

the E* of the three-body system
Source code in src/analysis_helpers/kinematics.py 
266
267
268
269
270
271
272
273
274
275
276
277
278
279
def estar3(m12,masses):
    """Calculate the energy of one of the daughter particles in the rest frame (E*) of a specific three-body system.

    Args:
        m12 (float): invariant mass of the first two particles
        masses (list): list of masses of the four particles

    Returns:
        float: the E* of the three-body system
    """
    masses = _validate_four_masses(masses)
    Est3 = masses[0]*masses[0]- m12*m12 - masses[3]*masses[3]
    Est3/= 2*m12
    return Est3