helicity

helicity

import ampform.helicity

Generate an amplitude model with the helicity formalism.

ParameterValue

Allowed value types for parameters.

alias of Union[float, complex, int]

class ParameterValues(parameters: Mapping[Symbol, Union[float, complex, int]])[source]

Bases: Mapping

Ordered mapping to ParameterValue with convenient getter and setter.

>>> a, b, c = sp.symbols("a b c")
>>> parameters = ParameterValues({a: 0.0, b: 1+1j, c: -2})
>>> parameters[a]
0.0
>>> parameters["b"]
(1+1j)
>>> parameters["b"] = 3
>>> parameters[1]
3
>>> parameters[2]
-2
>>> parameters[2] = 3.14
>>> parameters[c]
3.14
__getitem__(key: Union[Symbol, int, str]) → ParameterValue[source]
__setitem__(key: Union[Symbol, int, str], value: ParameterValue) → None[source]
class HelicityModel(intensity: Expr, amplitudes: Mapping[Indexed, Expr], parameter_defaults: Mapping[Symbol, Union[float, complex, int]], kinematic_variables: Mapping[Symbol, Expr], components: Mapping[str, Expr], reaction_info: ReactionInfo)[source]

Bases: object

intensity: Expr

Main expression describing the intensity over kinematic_variables.

amplitudes: OrderedDict[Indexed, Expr]

Definitions for the amplitudes that appear in intensity.

The main intensity is a sum over amplitudes for each initial and final state helicity combination. These amplitudes are indicated with as sp.Indexed instances and this attribute provides the definitions for each of these. See also TR-014.

parameter_defaults: ParameterValues

A mapping of suggested parameter values.

Keys are Symbol instances from the main expression that should be interpreted as parameters (as opposed to kinematic_variables). The symbols are ordered alphabetically by name with natural sort order. Values have been extracted from the input ReactionInfo.

kinematic_variables: OrderedDict[Symbol, Expr]

Expressions for converting four-momenta to kinematic variables.

components: OrderedDict[str, Expr]

A mapping for identifying main components in the expression.

Keys are the component names (str), formatted as LaTeX, and values are sub-expressions in the main expression. The mapping is an OrderedDict that orders the component names alphabetically with natural sort order.

reaction_info: ReactionInfo
property expression: Expr

Expression for the intensity with all amplitudes fully expressed.

Constructed from intensity by substituting its amplitude symbols with the definitions with amplitudes.

rename_symbols(renames: Union[Iterable[Tuple[str, str]], Mapping[str, str]]) → HelicityModel[source]

Rename certain symbols in the model.

Renames all Symbol instance that appear in expression, parameter_defaults, components, and kinematic_variables. This method can be used to couple parameters.

Parameters

renames – A mapping from old to new names.

Returns

A new instance of a HelicityModel with symbols in all attributes renamed accordingly.

sum_components(components: Iterable[str]) → Expr[source]

Coherently or incoherently add components of a helicity model.

class DynamicsSelector(transitions: Union[ReactionInfo, Iterable[StateTransition]])[source]

Bases: Mapping

Configure which ResonanceDynamicsBuilder to use for each node.

assign(selection: Any, builder: ResonanceDynamicsBuilder) → None[source]

Assign a ResonanceDynamicsBuilder to a selection of nodes.

Currently, the following types of selections are implements:

class HelicityAmplitudeBuilder(reaction: ReactionInfo, stable_final_state_ids: Optional[Iterable[int]] = None, scalar_initial_state_mass: bool = False)[source]

Bases: object

Amplitude model generator for the helicity formalism.

Parameters

  • reaction – The ReactionInfo from which to formulate() an amplitude model.

  • stable_final_state_ids – Put final state ‘invariant’ masses (\(m_0, m_1, \dots\)) under HelicityModel.parameter_defaults (with a scalar suggested value) instead of kinematic_variables (which are expressions to compute an event-wise array of invariant masses). This is useful if final state particles are stable.

  • stable_final_state_ids –

    Put the invariant of the initial state (\(m_{012\dots}\)) under HelicityModel.parameter_defaults (with a scalar suggested value) instead of kinematic_variables. This is useful if four-momenta were generated with or kinematically fit to a specific initial state energy.

    See also

    Scalar masses

property adapter: HelicityAdapter

Converter for computing kinematic variables from four-momenta.

property dynamics_choices: DynamicsSelector
property stable_final_state_ids: Optional[Set[int]]

IDs of the final states that should be considered stable.

The ‘invariant’ mass symbols for these final states will be inserted as scalar values into the parameter_defaults.

property scalar_initial_state_mass: bool

Add initial state mass as scalar value to parameter_defaults.

See also

Scalar masses

set_dynamics(particle_name: str, dynamics_builder: ResonanceDynamicsBuilder) → None[source]
formulate() → HelicityModel[source]
class CanonicalAmplitudeBuilder(reaction_result: ReactionInfo)[source]

Bases: HelicityAmplitudeBuilder

Amplitude model generator for the canonical helicity formalism.

This class defines a full amplitude in the canonical formalism, using the helicity formalism as a foundation. The key here is that we take the full helicity intensity as a template, and just exchange the helicity amplitudes \(F\) as a sum of canonical amplitudes \(A\):

\[F^J_{\lambda_1,\lambda_2} = \sum_{LS} \mathrm{norm}(A^J_{LS})C^2.\]

Here, \(C\) stands for Clebsch-Gordan factor.

See also

HelicityAmplitudeBuilder and Helicity versus canonical.

formulate_clebsch_gordan_coefficients(transition: StateTransition, node_id: int) → Expr[source]

Compute the two Clebsch-Gordan coefficients for a state transition node.

In the canonical basis (also called partial wave basis), Clebsch-Gordan coefficients ensure that the projection of angular momentum is conserved ([3], p. 4). When calling generate_transitions() with formalism="canonical-helicity", AmpForm formulates the amplitude in the canonical basis from amplitudes in the helicity basis using the transformation in [1], Eq. (4.32). See also [3], Eq. (28).

This function produces the two Clebsch-Gordan coefficients in [1], Eq. (4.32). For a two-body decay \(1 \to 2, 3\), we get:

(1)\[C^{s_1,\lambda}_{L,0,S,\lambda} C^{S,\lambda}_{s_2,\lambda_2,s_3,-\lambda_3}\]

with:

  • \(s_i\) the intrinsic Spin.magnitude of each state \(i\),

  • \(\lambda_{2}, \lambda_{3}\) the helicities of the decay products (can be taken to be their spin_projection when following a constistent boosting procedure),

  • \(\lambda=\lambda_{2}-\lambda_{3}\),

  • \(L\) the total angular momentum of the final state pair (l_magnitude),

  • \(S\) the coupled spin magnitude of the final state pair (s_magnitude),

  • and \(C^{j_3,m_3}_{j_1,m_1,j_2,m_2} = \langle j1,m1;j2,m2|j3,m3\rangle\), as in Clebsch-Gordan Coefficients.

Example

>>> import qrules
>>> reaction = qrules.generate_transitions(
...     initial_state=[("J/psi(1S)", [+1])],
...     final_state=[("gamma", [-1]), "f(0)(980)"],
... )
>>> transition = reaction.transitions[1]  # angular momentum 2
>>> formulate_clebsch_gordan_coefficients(transition, node_id=0)
CG(1, -1, 0, 0, 1, -1)*CG(2, 0, 1, -1, 1, -1)
\[C^{s_1,\lambda}_{L,0,S,\lambda} C^{S,\lambda}_{s_2,\lambda_2,s_3,-\lambda_3} = C^{1,(-1-0)}_{2,0,1,(-1-0)} C^{1,(-1-0)}_{1,-1,0,0} = C^{1,-1}_{2,0,1,-1} C^{1,-1}_{1,-1,0,0}\]
../_images/graphviz_0.svg
formulate_wigner_d(transition: StateTransition, node_id: int) → Expr[source]

Compute WignerD for a transition node.

Following [3], Eq. (10). For a two-body decay \(1 \to 2, 3\), we get

(2)\[D^{s_1}_{m_1,\lambda_2-\lambda_3}(-\phi,\theta,0)\]

with:

  • \(s_1\) the Spin.magnitude of the decaying state,

  • \(m_1\) the spin_projection of the decaying state,

  • \(\lambda_{2}, \lambda_{3}\) the helicities of the decay products in in the restframe of \(1\) (can be taken to be their intrinsic spin_projection when following a constistent boosting procedure),

  • and \(\phi\) and \(\theta\) the helicity angles (see also get_helicity_angle_label()).

Note that \(\lambda_2, \lambda_3\) are ordered by their number of children, then by their state ID (see TwoBodyDecay).

See [3], Eq. (30) for an example of Wigner-\(D\) functions in a sequential two-body decay.

Example

>>> import qrules
>>> reaction = qrules.generate_transitions(
...     initial_state=[("J/psi(1S)", [+1])],
...     final_state=[("gamma", [-1]), "f(0)(980)"],
... )
>>> transition = reaction.transitions[0]
>>> formulate_wigner_d(transition, node_id=0)
WignerD(1, 1, -1, -phi_0, theta_0, 0)
\[D^{s_1}_{m_1,\lambda_2-\lambda_3}\left(-\phi,\theta,0\right) = D^{1}_{+1,(-1-0)}\left(-\phi_0,\theta_0,0\right) = D^{1}_{1,-1}\left(-\phi_0,\theta_0,0\right)\]
../_images/graphviz_1.svg
get_prefactor(transition: StateTransition) → float[source]

Calculate the product of all prefactors defined in this transition.

See also

qrules.quantum_numbers.InteractionProperties.parity_prefactor

group_transitions(transitions: Iterable[StateTransition]) → List[List[StateTransition]][source]

Match final and initial states in groups.

Each StateTransition corresponds to a specific state transition amplitude. This function groups together transitions, which have the same initial and final state (including spin). This is needed to determine the coherency of the individual amplitude parts.

Submodules and Subpackages

previous

kmatrix

next

decay