qrules

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 MutableTransition) are allowed between a certain initial and final state. Internally, the system propagates the quantum numbers defined by the particle module through the MutableTransition, 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: StateDefinition | Sequence[StateDefinition], final_state: Sequence[StateDefinition], mass_conservation_factor: float | None = 3.0, particle_db: ParticleCollection | None = None, max_angular_momentum: int = 1, max_spin_magnitude: float = 2) → 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'})}

See also

Check allowed reactions

generate_transitions(initial_state: StateDefinitionInput | Sequence[StateDefinitionInput], final_state: Sequence[StateDefinitionInput], allowed_intermediate_particles: list[str] | None = None, allowed_interaction_types: str | Iterable[str] | None = None, formalism: SpinFormalism = 'canonical-helicity', particle_db: ParticleCollection | None = None, mass_conservation_factor: float | None = 3.0, max_angular_momentum: int = 2, max_spin_magnitude: float = 2, topology_building: str = 'isobar', number_of_threads: int | None = 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 – Number of cores with which to compute the allowed transitions. Defaults to the current value returned by settings.NumberOfThreads.get().

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.transitions)
4
>>> len(reaction.group_by_topology())
3
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