reaction
Reaction and decay topology helpers are currently exposed from
laddu.utils.variables in Python.
Bindings for variable extractors (invariant masses, Mandelstam variables, etc.).
These helpers wrap the lower-level Rust selectors and allow Python analyses to
bind derived quantities by name. For example, the mass of a two-kaon system can
be constructed with Mass(['kshort1', 'kshort2']) and then registered inside
an laddu.extensions.NLL.
Examples
>>> import laddu as ld
>>> from laddu.variables import Mass
>>> columns = {
... 'kshort1_px': [0.1], 'kshort1_py': [0.0], 'kshort1_pz': [0.2], 'kshort1_e': [0.3],
... 'kshort2_px': [-0.1], 'kshort2_py': [0.0], 'kshort2_pz': [0.1], 'kshort2_e': [0.25],
... }
>>> dataset = ld.io.from_dict(columns)
>>> mass = Mass(['kshort1', 'kshort2'])
>>> mass
Mass { source: Selection(P4Selection { names: ["kshort1", "kshort2"], indices: [] }) }
- class laddu.utils.variables.Angles
A Variable used to define both spherical decay angles in the given frame
This class combines
laddu.CosThetaandladdu.Phiinto a single object- Parameters:
reaction (laddu.Reaction) – Reaction describing the production kinematics and decay roots.
daughter (list of str) – Names of particles which are combined to form one of the decay products of the resonance associated with the decay parent.
frame ({'Helicity', 'HX', 'HEL', 'GottfriedJackson', 'Gottfried Jackson', 'GJ', 'Gottfried-Jackson'}) – The frame to use in the calculation
- Raises:
ValueError – If frame is not one of the valid options
See also
- costheta
The Variable representing the cosine of the polar spherical decay angle
- Return type:
- phi
- class laddu.utils.variables.CosTheta
The cosine of the polar decay angle in the rest frame of the given resonance
This Variable is calculated by forming the given frame (helicity or Gottfried-Jackson) and calculating the spherical angles according to one of the decaying daughter particles.
The helicity frame is defined in terms of the following Cartesian axes in the rest frame of the resonance:
\[\hat{z} \propto -\vec{p}'_{\text{recoil}}\]\[\hat{y} \propto \vec{p}_{\text{beam}} \times (-\vec{p}_{\text{recoil}})\]\[\hat{x} = \hat{y} \times \hat{z}\]where primed vectors are in the rest frame of the resonance and unprimed vectors are in the center-of-momentum frame.
The Gottfried-Jackson frame differs only in the definition of \(\hat{z}\):
\[\hat{z} \propto \vec{p}'_{\text{beam}}\]- Parameters:
reaction (laddu.Reaction) – Reaction describing the production kinematics and decay roots.
daughter (list of str) – Names of particles which are combined to form one of the decay products of the resonance associated with the decay parent.
frame ({'Helicity', 'HX', 'HEL', 'GottfriedJackson', 'Gottfried Jackson', 'GJ', 'Gottfried-Jackson'}) – The frame to use in the calculation
- Raises:
ValueError – If frame is not one of the valid options
See also
- as_expression(*tags: str) Expression
Convert this variable into a real-valued expression.
- class laddu.utils.variables.Decay
A reaction-aware isobar decay view.
- angles(daughter, frame='Helicity')
Decay angle variables for the selected frame.
- canonical_factor(*tags, spin, projection, orbital_l, coupled_spin, daughter, daughter_1_spin, daughter_2_spin, lambda_1, lambda_2, frame='Helicity')
Construct the canonical-basis spin-angular factor for one explicit LS/helicity term.
- costheta(daughter, frame='Helicity')
Decay costheta variable for the selected frame.
- daughter_1_mass()
First daughter mass variable.
- daughter_2_mass()
Second daughter mass variable.
- daughter_mass(daughter)
Mass variable for a selected daughter.
- daughters()
Ordered daughter particle identifiers.
- helicity_factor(*tags, spin, projection, daughter, lambda_1, lambda_2, frame='Helicity')
Construct the helicity-basis angular factor for one explicit helicity term.
- mass()
Parent mass variable.
- parent_mass()
Parent mass variable.
- phi(daughter, frame='Helicity')
Decay phi variable for the selected frame.
- daughter_1
The first daughter particle identifier.
- daughter_2
The second daughter particle identifier.
- parent
The parent particle.
- reaction
The enclosing reaction.
- class laddu.utils.variables.Mandelstam(reaction, channel)
Mandelstam variables s, t, and u
By convention, the metric is chosen to be \((+---)\) and the variables are defined as follows (ignoring factors of \(c\)):
\[s = (p_1 + p_2)^2 = (p_3 + p_4)^2\]\[t = (p_1 - p_3)^2 = (p_4 - p_2)^2\]\[u = (p_1 - p_4)^2 = (p_3 - p_2)^2\]- Parameters:
reaction (laddu.Reaction) – Reaction describing the two-to-two kinematics whose Mandelstam channels should be evaluated.
channel ({'s', 't', 'u', 'S', 'T', 'U'}) – The Mandelstam channel to calculate
- Raises:
Exception – If more than one particle list is empty
ValueError – If channel is not one of the valid options
Notes
///
- as_expression(*tags: str) Expression
Convert this variable into a real-valued expression.
- class laddu.utils.variables.Mass(constituents)
The invariant mass of an arbitrary combination of constituent particles in an Event
This variable is calculated by summing up the 4-momenta of each particle listed by index in constituents and taking the invariant magnitude of the resulting 4-vector.
- Parameters:
constituents (str or list of str) – Particle names to combine when constructing the final four-momentum
See also
- as_expression(*tags: str) Expression
Convert this variable into a real-valued expression.
- class laddu.utils.variables.Particle
A kinematic particle used to define reaction-aware variables.
- static composite(label, daughters)
Construct a composite particle from daughter particles.
- static fixed(label, p4)
Construct a particle with fixed event-independent four-momentum.
- static missing(label)
Construct a missing particle solved by the reaction topology.
- static stored(id)
Construct a stored particle from a dataset p4 column name.
- label
The particle label.
- class laddu.utils.variables.Phi
The aziumuthal decay angle in the rest frame of the given resonance
This Variable is calculated by forming the given frame (helicity or Gottfried-Jackson) and calculating the spherical angles according to one of the decaying daughter particles.
The helicity frame is defined in terms of the following Cartesian axes in the rest frame of the resonance:
\[\hat{z} \propto -\vec{p}'_{\text{recoil}}\]\[\hat{y} \propto \vec{p}_{\text{beam}} \times (-\vec{p}_{\text{recoil}})\]\[\hat{x} = \hat{y} \times \hat{z}\]where primed vectors are in the rest frame of the resonance and unprimed vectors are in the center-of-momentum frame.
The Gottfried-Jackson frame differs only in the definition of \(\hat{z}\):
\[\hat{z} \propto \vec{p}'_{\text{beam}}\]- Parameters:
reaction (laddu.Reaction) – Reaction describing the production kinematics and decay roots.
daughter (list of str) – Names of particles which are combined to form one of the decay products of the resonance associated with the decay parent.
frame ({'Helicity', 'HX', 'HEL', 'GottfriedJackson', 'Gottfried Jackson', 'GJ', 'Gottfried-Jackson'}) – The frame to use in the calculation
- Raises:
ValueError – If frame is not one of the valid options
See also
- as_expression(*tags: str) Expression
Convert this variable into a real-valued expression.
- class laddu.utils.variables.PolAngle(reaction, pol_angle)
The polar angle of the given polarization vector with respect to the production plane
The beam and recoil particles define the plane of production, and this Variable describes the polar angle of the beam relative to this plane
- Parameters:
reaction (laddu.Reaction) – Reaction describing the production kinematics and decay roots.
pol_angle (str) – Name of the auxiliary scalar column storing the polarization angle in radians
- as_expression(*tags: str) Expression
Convert this variable into a real-valued expression.
- class laddu.utils.variables.PolMagnitude(pol_magnitude)
The magnitude of the given particle’s polarization vector
This Variable simply represents the magnitude of the polarization vector of the particle with the index beam
- Parameters:
pol_magnitude (str) – Name of the auxiliary scalar column storing the magnitude of the polarization vector
See also
- as_expression(*tags: str) Expression
Convert this variable into a real-valued expression.
- class laddu.utils.variables.Polarization(reaction, *, pol_magnitude, pol_angle)
A Variable used to define both the polarization angle and magnitude of the given particle``
This class combines
laddu.PolAngleandladdu.PolMagnitudeinto a single object- Parameters:
reaction (laddu.Reaction) – Reaction describing the production kinematics and decay roots.
pol_magnitude (str) – Name of the auxiliary scalar storing the polarization magnitude
pol_angle (str) – Name of the auxiliary scalar storing the polarization angle in radians
See also
- pol_angle
The Variable representing the polar angle of the polarization vector
- Return type:
- pol_magnitude
The Variable representing the magnitude of the polarization vector
- Return type:
- class laddu.utils.variables.Reaction
A reaction topology with direct particle definitions.
- static two_to_two(p1, p2, p3, p4)
Construct a two-to-two reaction from p1, p2, p3, p4.
- decay(parent)
Construct an isobar decay view.
- mandelstam(channel)
Construct a Mandelstam variable.
- mass(particle)
Construct a particle mass variable.
- pol_angle(angle_aux)
Construct a polarization-angle variable.
- polarization(*, pol_magnitude, pol_angle)
Construct polarization variables.
- production()
Construct a two-to-two production view.
- class laddu.utils.variables.VariableExpression