Skip to content

FEAT: add qrules.workflow module - #344

Open
grayson-helmholz wants to merge 27 commits into
mainfrom
split-stm-workflow
Open

FEAT: add qrules.workflow module#344
grayson-helmholz wants to merge 27 commits into
mainfrom
split-stm-workflow

Conversation

@grayson-helmholz

@grayson-helmholz grayson-helmholz commented Jul 10, 2026

Copy link
Copy Markdown
Contributor

✨ New features

  • qrules.workflow exposes the pipeline as free functions: create_graph_settings(), create_problem_sets(), solve(), convert_to_particle_transitions(), and collect_reaction_info().
  • create_qn_problem_sets() and find_solutions() cover the default use case in two calls, meeting at a QNProblemSetCollection that carries the final state, formalism, and particle selection from one to the other.
  • AllowedIntermediateParticles, built with filter_intermediate_particles() and narrowed with select() and exclude(), which take the same name patterns and return a new selection.
  • InteractionConfig, holding the interaction-type settings, the allowed types globally or per node, and the interaction determinators.
  • SolutionContainer is public, because it is the boundary between convert_to_particle_transitions() and collect_reaction_info().

⚙️ Enhancements

  • solve() takes strength-grouped QNProblemSets, so one filtered with filter_quantum_number_problem_set() can be fed straight back in.
  • find_solutions() requires formalism and allowed_intermediate_particles for a plain dict of problem sets instead of guessing. Defaulting to "helicity" strips $L$ and $S$ from canonical-helicity solutions and mislabels ReactionInfo.formalism; falling back to the whole particle database matches intermediate states the problem sets were not built for. Both are still inferred from a QNProblemSetCollection.
  • Multiprocessing pickles only the allowed-state property maps instead of the whole StateTransitionManager.

🔨 Maintenance

  • The StateTransitionManager becomes a facade over these functions. Its public methods, arguments, and output are unchanged: tests/channels/ is untouched and a new test asserts that the pipeline reproduces the STM result for both formalisms.

📝 Documentation

  • intermediate-results.ipynb is rewritten around the workflow functions. It keeps the dict_set_intersection() reduction from CSPSolver generates undesired edge_properties after filtering #301, without which the intermediate edges come back with the full PDG property maps.
  • reaction.ipynb still teaches the StateTransitionManager exclusively; converting it is left as a follow-up.

Squash commit messages

* DOC: rewrite intermediate-results notebook around `workflow`
* ENH: require formalism and particles that cannot be inferred
* ENH: solve modified `QNProblemSet`s without the `CSPSolver`
* FEAT: add `create_qn_problem_sets` and `find_solutions`
* FEAT: add structs for intermediate particles and interactions
* MAINT: reduce `StateTransitionManager` to a workflow facade

Extract the pipeline stages of the `StateTransitionManager` into free
functions in a new `qrules.workflow` module, so that intermediate
results (most notably `QNProblemSet`s) can be inspected, modified, and
fed back into the pipeline. The STM remains as a thin facade that
delegates to these functions.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@redeboer redeboer added ⚠️ Interface Breaking changes to the API ⚙️ Enhancement Improvements and optimizations of existing features labels Jul 10, 2026
@redeboer
redeboer self-requested a review July 10, 2026 13:15
@grayson-helmholz

Copy link
Copy Markdown
Contributor Author
qrules-flowchart3

grayson-helmholz and others added 10 commits July 10, 2026 15:42
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Introduce `QNProblemSetCollection`, returned by `create_qn_problem_sets()`, which
carries the intermediate-particle selection, final state, and formalism along with
the strength-grouped `QNProblemSet`s. `find_solutions()` defaults to these values,
so the solving stage can no longer silently diverge from the values with which the
problem sets were created (e.g. matching against the full PDG although the problem
sets were built for a restricted resonance selection, or deduplicating canonical
solutions with helicity filters). Explicit arguments still override, and a plain
strength-grouped dictionary is still accepted.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TWmXKcjJMmRVJCUi58JDLH
The topology creation (including the n-body mass-conservation toggle) and the
`ProblemSet` to `QNProblemSet` conversion were duplicated between the
`StateTransitionManager` and the workflow module; both now delegate to the
single implementation in `qrules.workflow`.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TWmXKcjJMmRVJCUi58JDLH
Mirrors `src/qrules/workflow.py` with `tests/unit/test_workflow.py`, covering the
intermediate-particle selection, `InteractionConfig` get/set semantics, and an
equivalence test that reproduces the STM-generated `ReactionInfo` through the
`create_qn_problem_sets`/`find_solutions` pipeline.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TWmXKcjJMmRVJCUi58JDLH
Restores the `# noqa: S403`, `# noqa: F401` and `# noqa: S324` suppression
comments that 4b79de2 (#346) rewrote into `# ruff: ignore[...]` form.

Note that the current ruff version enforces the opposite: `ruff check` reports
5 `noqa-comments` violations on this file, and `ruff check --fix` will restore
the `ruff: ignore` form.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@ComPWA ComPWA deleted a comment from review-notebook-app Bot Aug 24, 2026
@redeboer redeboer changed the title ENH: split StateTransitionManager into a workflow module FEAT: add qrules.workflow module Aug 27, 2026
@redeboer redeboer added 🔨 Maintenance Maintenance and upkeep improvements 📝 Docs Improvements or additions to documentation ✨ Feature New feature added to the package and removed ⚠️ Interface Breaking changes to the API labels Aug 27, 2026
@redeboer redeboer added this to the 0.11.0 milestone Sep 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

📝 Docs Improvements or additions to documentation ⚙️ Enhancement Improvements and optimizations of existing features ✨ Feature New feature added to the package 🔨 Maintenance Maintenance and upkeep improvements

Projects

None yet

3 participants