qrules

import qrules

A rule based system that facilitates particle reaction analysis.

QRules generates allowed particle transitions from a set of conservation rules and boundary conditions as specified by the user. The user boundary conditions for a particle reaction problem are for example the initial state, final state, and allowed interactions.

The core of qrules computes which transitions (represented by a StateTransitionGraph) are allowed between a certain initial and final state. Internally, the system propagates the quantum numbers defined by the particle module through the StateTransitionGraph, while satisfying the rules define by the conservation_rules module. See Generate transitions and Particle database.

Finally, the io module provides tools that can read and write the objects of this framework.

check_reaction_violations(initial_state: Union[str, Tuple[str, Sequence[float]], Sequence[Union[str, Tuple[str, Sequence[float]]]]], final_state: Sequence[Union[str, Tuple[str, Sequence[float]]]], mass_conservation_factor: Optional[float] = 3.0, particle_db: Optional[ParticleCollection] = None, max_angular_momentum: int = 1, max_spin_magnitude: float = 2.0) Set[FrozenSet[str]][source]

Determine violated interaction rules for a given particle reaction.

Warning

This function only guarantees to find P, C and G parity violations, if it’s a two body decay. If all initial and final states have the C/G parity defined, then these violations are also determined correctly.

Parameters
  • initial_state – Shortform description of the initial state w/o spin projections.

  • final_state – Shortform description of the final state w/o spin projections.

  • mass_conservation_factor – Factor with which the width is multiplied when checking for MassConservation. Set to None in order to deactivate mass conservation.

  • particle_db (Optional) – Custom ParticleCollection object. Defaults to the ParticleCollection returned by load_pdg.

  • max_angular_momentum – Maximum angular momentum over which to generate \(LS\)-couplings.

  • max_spin_magnitude – Maximum spin magnitude over which to generate \(LS\)-couplings.

Returns

Set of least violating rules. The set can have multiple entries, as several quantum numbers can be violated. Each entry in the frozenset represents a group of rules that together violate all possible quantum number configurations.

Example

>>> import qrules
>>> qrules.check_reaction_violations(
...     initial_state="pi0",
...     final_state=["gamma", "gamma", "gamma"],
... )
{frozenset({'c_parity_conservation'})}
generate_transitions(initial_state: Union[str, Tuple[str, Sequence[float]], Sequence[Union[str, Tuple[str, Sequence[float]]]]], final_state: Sequence[Union[str, Tuple[str, Sequence[float]]]], allowed_intermediate_particles: Optional[List[str]] = None, allowed_interaction_types: Optional[Union[str, Iterable[str]]] = None, formalism: str = 'canonical-helicity', particle_db: Optional[ParticleCollection] = None, mass_conservation_factor: Optional[float] = 3.0, max_angular_momentum: int = 2, max_spin_magnitude: float = 2.0, topology_building: str = 'isobar', number_of_threads: Optional[int] = None) ReactionInfo[source]

Generate allowed transitions between an initial and final state.

Serves as a facade to the StateTransitionManager (see Generate transitions).

Parameters
  • initial_state (list) – A list of particle names in the initial state. You can specify spin projections for these particles with a tuple, e.g. ("J/psi(1S)", [-1, 0, +1]). If spin projections are not specified, all projections are taken, so the example here would be equivalent to "J/psi(1S)".

  • final_state (list) – Same as initial_state, but for final state particles.

  • allowed_intermediate_particles (list, optional) – A list of particle states that you want to allow as intermediate states. This helps (1) filter out resonances and (2) speed up computation time.

  • allowed_interaction_types – Interaction types you want to consider. For instance, ["s", "em"] results in EM and STRONG and ["strong"] results in STRONG.

  • formalism (str, optional) – Formalism that you intend to use in the eventual amplitude model.

  • particle_db (ParticleCollection, optional) – The particles that you want to be involved in the reaction. Uses load_pdg by default. It’s better to use a subset for larger reactions, because of the computation times. This argument is especially useful when you want to use your own particle definitions (see Particle database).

  • mass_conservation_factor – Width factor that is taken into account for for the MassConservation rule.

  • max_angular_momentum – Maximum angular momentum over which to generate angular momenta.

  • max_spin_magnitude – Maximum spin magnitude over which to generate spins.

  • topology_building (str) –

    Technique with which to build the Topology instances. Allowed values are:

    • "isobar": Isobar model (each state decays into two states)

    • "nbody": Use one central node and connect initial and final states to it

  • number_of_threads (int) – Number of cores with which to compute the allowed transitions. Defaults to all cores on the system.

An example (where, for illustrative purposes only, we specify all arguments) would be:

>>> import qrules
>>> reaction = qrules.generate_transitions(
...     initial_state="D0",
...     final_state=["K~0", "K+", "K-"],
...     allowed_intermediate_particles=["a(0)(980)", "a(2)(1320)-"],
...     allowed_interaction_types=["e", "w"],
...     formalism="helicity",
...     particle_db=qrules.load_pdg(),
...     topology_building="isobar",
... )
>>> len(reaction.transition_groups)
3
>>> len(reaction.transitions)
4
load_default_particles() ParticleCollection[source]

Load the default particle list that comes with qrules.

Runs load_pdg and supplements its output definitions from the file additional_definitions.yml.

Submodules and Subpackages