# Welcome to QRules!#

QRules is a Python package for validating and generating particle reactions using quantum number conservation rules. The user only has to provide a certain set of boundary conditions (initial and final state, allowed interaction types, expected decay topologies, etc.). QRules will then span the space of allowed quantum numbers over all allowed decay topologies and particle instances that correspond with the sets of allowed quantum numbers it has found.

The resulting state transition objects are particularly useful for amplitude analysis / Partial Wave Analysis as they contain all information (such as expected masses, widths, and spin projections) that is needed to formulate an amplitude model.

The Usage pages illustrate several features of qrules. You can run each of them as Jupyter notebooks with the launch button in the top-right corner. Enjoy!

Internal design

QRules consists of three major components:

1. State transition graphs

A StateTransitionGraph is a directed graph that consists of nodes and edges. In a directed graph, each edge must be connected to at least one node (in correspondence to Feynman graphs). This way, a graph describes the transition from one state to another.

• Edges correspond to states (particles with spin). In other words, edges are a collection of properties such as the quantum numbers that characterize a state that the particle is in.

• Nodes represents interactions and contain all information for the transition of this specific step. Most importantly, a node contains a collection of conservation rules that have to be satisfied. An interaction node has $$M$$ ingoing lines and $$N$$ outgoing lines, where $$M,N \in \mathbb{Z}$$, $$M > 0, N > 0$$.

2. Conservation rules

The central component are the conservation_rules. They belong to individual nodes and receive properties about the node itself, as well as properties of the ingoing and outgoing edges of that node. Based on those properties the conservation rules determine whether edges pass or not.

3. Solvers

The determination of the correct state properties in the graph is done by solvers. New properties are set for intermediate edges and interaction nodes and their validity is checked with the conservation rules.

QRules workflow

1. Preparation

1.1. Build all possible topologies. A topology is represented by a StateTransitionGraph, in which the edges and nodes are empty (no particle information).

1.2. Fill the topology graphs with the user provided information. Typically these are the graph’s ingoing edges (initial state) and outgoing edges (final state).

2. Solving

2.1. Propagate quantum number information through the complete graph while respecting the specified conservation laws. Information like mass is not used in this first solving step.

2.2. Clone graphs while inserting concrete matching particles for the intermediate edges (mainly adds the mass variable).

2.3. Validate the complete graphs, so run all conservation law check that were postponed from the first step.