ENH: split StateTransitionManager into a workflow module

[grayson-helmholz]

• Closes Split up StateTransitionManager to facilitate use of intermediate results #305
• Closes Create struct and appropriate modification-functions for allowed_intermediate_particles #306
• Closes Struct and functions for allowed_interaction_types #307
• Closes Generate QNProblemSets without the StateTransitionManager  #284

What

Extracts the pipeline stages of the StateTransitionManager into free functions in a new qrules.workflow module, so that intermediate results — most notably QNProblemSets — can be inspected, modified, and fed back into the pipeline (GROMACS-style workflow, as proposed in #305). The STM remains as a thin facade that delegates to these functions; its public API and behavior are unchanged.

New data structures

• AllowedIntermediateParticles + filter_intermediate_particles() (Create struct and appropriate modification-functions for allowed_intermediate_particles #306) — replaces the STM-private pair __intermediate_particle_filters / __allowed_intermediate_states. Makes explicit that this selection feeds both problem-set creation (intermediate edge QN domains) and the CSPSolver (particle matching), which the STM previously shared invisibly between two private code paths.
• InteractionConfig with get/set_allowed_interaction_types() (Struct and functions for allowed_interaction_types #307) — bundles interaction-type settings, allowed types per node, and the interaction determinators (LeptonCheck, GammaCheck).

Pipeline stage functions

Stage	Extracted from
create_graph_settings()	STM.__determine_graph_settings
create_problem_sets()	STM.create_problem_sets
solve()	STM.find_quantum_number_transitions + STM._solve
convert_to_particle_transitions()	STM._find_particle_transitions + STM.__convert_to_particle_definitions
collect_reaction_info()	post-processing half of STM.find_solutions

Crucially, solve() takes strength-grouped QNProblemSets directly, closing the gap described in #305: generated QNProblemSets can now be filtered/modified (e.g. with filter_quantum_number_problem_set()) and solved, without reconstructing STM-internal state around a bare CSPSolver.

Default use-case wrappers

Two functions cover the standard workflow, meeting at the strength-grouped QNProblemSets — the natural inspection point:

qn_problem_sets = create_qn_problem_sets(["J/psi(1S)"], ["gamma", "pi0", "pi0"], particle_db)
# ... inspect / filter / modify ...
reaction = find_solutions(qn_problem_sets, particle_db, final_state=["gamma", "pi0", "pi0"])

create_qn_problem_sets() generates QNProblemSets without the StateTransitionManager, which closes #284 as written. Note that it still expands spin projections into separate problem sets internally (via the particle-level ProblemSet dual); the facts-driven generation without projection expansion is tracked separately in #338/#339.

Notes

• Pure refactor: extracted function bodies are verbatim where possible; tests/channels/ results are identical.
• The private helpers _group_by_strength, _filter_by_name_pattern, _match_final_state_ids, and _strip_spin moved from transition.py to workflow.py, next to their only remaining callers.
• Multiprocessing now pickles only the allowed-intermediate-state property maps (via functools.partial) instead of the whole STM instance.
• Pre-existing quirk kept as-is (candidate for a separate BEHAVIOR fix): STM.reaction_mode is stored as str(solving_mode), so the SolvingMode.FAST early-break in the solving loop never triggers through the STM. The new workflow.solve() compares the enum properly, so FAST works as documented when using the new API; the STM delegation preserves the old (always-FULL) behavior.
• qrules.workflow is not re-exported in qrules.__init__ for now; happy to add that if preferred.

Part of epic #336 (Stage 3 of the roadmap).

Verification

• pytest tests/unit src -m "not slow": 696 passed
• pytest tests/channels -m "slow or not slow": 55 passed
• mypy src/qrules: clean; ruff check / ruff format: clean; all pre-commit hooks (incl. pyright) pass

🤖 Generated with Claude Code

[grayson-helmholz]

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB