Skip to content

FEAT: add generate_qn_transitions function - #383

Open
grayson-helmholz wants to merge 3 commits into
skip-projection-combinatoricsfrom
qn-reaction-info
Open

grayson-helmholz wants to merge 3 commits into
skip-projection-combinatoricsfrom
qn-reaction-info

Conversation

@grayson-helmholz

@grayson-helmholz grayson-helmholz commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

✨ New features

  • generate_qn_transitions() is the quantum-number-level counterpart of generate_transitions(). It chains create_qn_problem_sets(spin_projections=False) with find_qn_transitions() and returns a QNReactionInfo. Because the spin-projection combinatorics is avoided both in the problem sets and in the constraint problem, it stays feasible for many-body final states, where generate_transitions() takes impractically long.
  • QNReactionInfo collects the resulting QNTransitions. Its initial and final states are Particle instances, while each intermediate state stays a property map of the quantum numbers that any particle appearing there must carry. It offers get_intermediate_quantum_numbers() to list those distinct sets and group_by_topology(), mirroring ReactionInfo.
  • find_qn_transitions() and collect_qn_transitions() take an optional particle_db with which they resolve the external states, which are fully determined by their pid, to Particle instances. Intermediate states are deliberately left as property maps, since they stand for a set of allowed states rather than one particle.
  • create_qn_problem_sets() accepts allowed_interaction_types (for instance "strong" or ["em", "weak"]), which restricts the interaction types of the default or given interaction_config without the caller having to build an InteractionConfig by hand. The given config is copied rather than mutated.

⚙️ Enhancements

  • collapse_graphs() (the collapse="topology" rendering option) now handles states that are quantum-number property maps. Such a state is reduced to the new QuantumNumberSignature, which renders as the PDG-style $I^G(J^{PC})$ summary, so a collapsed edge lists signatures such as 1⁺(1⁻⁻) instead of full property maps. The signature has both a plain and a LaTeX rendering, and the label formatters gained a superscript() method for it.
  • The DOT and Mermaid printers accept a QNReactionInfo wherever they accept a ReactionInfo, so quantum-number transitions can be visualized with the usual qrules.io entry points.
  • to_state_definitions() moved from a private helper in qrules to the public API of qrules.combinatorics, since the quantum-number workflow needs the same normalization of a single state definition into a list.

Squash commit messages

* DOC: illustrate four- and five-body decays
* ENH: collapse quantum-number transitions by topology
* ENH: render QNReactionInfo as DOT and Mermaid
* FEAT: add allowed_interaction_types argument
* FEAT: add QNReactionInfo class
* FEAT: make to_state_definitions public

@redeboer
redeboer added this pull request to stack #386 September 15, 2026 14:29
@redeboer redeboer changed the title FEAT: add QNReactionInfo for projection-free transitions FEAT: add generate_qn_transitions function Sep 15, 2026
@redeboer redeboer added ⚙️ Enhancement Improvements and optimizations of existing features ✨ Feature New feature added to the package labels Sep 15, 2026
@redeboer
redeboer self-requested a review September 15, 2026 14:41
@redeboer redeboer added this to the 0.11.0 milestone Sep 15, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

⚙️ Enhancement Improvements and optimizations of existing features ✨ Feature New feature added to the package

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Generalize output transitions and IO beyond State/ParticleWithSpin Illustrate 4- or even 5-body isobar decay in the visualization notebook

2 participants