Merge branch 'main' into spin_as_fraction

.binder/runtime.txt

@@ -1 +1 @@
-python-3.9
+python-3.12

.envrc

@@ -1,2 +1,4 @@
 uv sync --all-extras --quiet
 source .venv/bin/activate
+
+export PYTHONHASHSEED=0

.github/workflows/ci.yml

@@ -34,7 +34,6 @@ jobs:
       id-token: write
     with:
       apt-packages: graphviz
-      python-version: "3.9"
       specific-pip-packages: ${{ inputs.specific-pip-packages }}
   pytest:
     uses: ComPWA/actions/.github/workflows/[email protected]
@@ -48,5 +47,3 @@ jobs:
     secrets:
       token: ${{ secrets.PAT }}
     uses: ComPWA/actions/.github/workflows/[email protected]
-    with:
-      python-version: "3.9"

.github/workflows/lock.yml

@@ -13,8 +13,6 @@ on:
     paths:
       - .pre-commit-config.yaml
       - uv.lock
-  schedule:
-    - cron: "0 3 7 */1 *"
   workflow_dispatch:
 
 jobs:

.pre-commit-config.yaml

@@ -14,15 +14,15 @@ repos:
       - id: check-useless-excludes
 
   - repo: https://github.com/ComPWA/policy
-    rev: 0.5.5
+    rev: 0.5.6
     hooks:
       - id: check-dev-files
         args:
-          - --dev-python-version=3.9
           - --doc-apt-packages=graphviz
+          - --environment-variables=PYTHONHASHSEED=0
           - --repo-name=qrules
           - --repo-title=QRules
-          - --update-lock-files=monthly
+          - --update-lock-files=outsource
       - id: colab-toc-visible
       - id: fix-nbformat-version
       - id: remove-empty-tags
@@ -33,7 +33,7 @@ repos:
           - --extras-require=doc,viz
 
   - repo: https://github.com/kynan/nbstripout
-    rev: 0.7.1
+    rev: 0.8.0
     hooks:
       - id: nbstripout
         args:
@@ -61,7 +61,7 @@ repos:
             metadata.vscode
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.7.1
+    rev: v0.7.2
     hooks:
       - id: ruff
         args: [--fix]
@@ -123,7 +123,7 @@ repos:
         pass_filenames: false
 
   - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: v8.15.2
+    rev: v8.15.3
     hooks:
       - id: cspell
 
@@ -149,11 +149,11 @@ repos:
           - python
 
   - repo: https://github.com/ComPWA/pyright-pre-commit
-    rev: v1.1.386
+    rev: v1.1.388
     hooks:
       - id: pyright
 
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.4.28
+    rev: 0.4.30
     hooks:
       - id: uv-lock

.python-version

@@ -1 +1 @@
-3.9
+3.12

.readthedocs.yml

@@ -3,7 +3,7 @@ version: 2
 build:
   os: ubuntu-24.04
   tools:
-    python: "3.9"
+    python: "3.12"
   commands:
     - |-
       export PIXI_HOME=$READTHEDOCS_VIRTUALENV_PATH

docs/conf.py

@@ -47,6 +47,7 @@ def pick_newtype_attrs(some_type: type) -> list:
 add_module_names = False
 api_github_repo = f"{ORGANIZATION}/{REPO_NAME}"
 api_target_substitutions: dict[str, str | tuple[str, str]] = {
+    "EdgeQuantumNumberTypes": ("obj", "qrules.quantum_numbers.EdgeQuantumNumberTypes"),
     "EdgeType": "typing.TypeVar",
     "Fraction": "fraction.Fraction",
     "GraphEdgePropertyMap": ("obj", "qrules.argument_handling.GraphEdgePropertyMap"),
@@ -57,11 +58,13 @@ def pick_newtype_attrs(some_type: type) -> list:
     "NewEdgeType": "typing.TypeVar",
     "NewNodeType": "typing.TypeVar",
     "NodeQuantumNumber": ("obj", "qrules.quantum_numbers.NodeQuantumNumber"),
+    "NodeQuantumNumberTypes": ("obj", "qrules.quantum_numbers.NodeQuantumNumberTypes"),
     "NodeType": "typing.TypeVar",
     "ParticleWithSpin": ("obj", "qrules.particle.ParticleWithSpin"),
     "Path": "pathlib.Path",
     "qrules.topology.EdgeType": "typing.TypeVar",
     "qrules.topology.NodeType": "typing.TypeVar",
+    "Rule": ("obj", "qrules.argument_handling.Rule"),
     "SpinFormalism": ("obj", "qrules.transition.SpinFormalism"),
     "StateDefinition": ("obj", "qrules.combinatorics.StateDefinition"),
     "StateDefinitionInput": ("obj", "qrules.combinatorics.StateDefinition"),

docs/usage/visualize.ipynb

@@ -50,6 +50,16 @@
     "```"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    ":::{warning}\n",
+    "Currently the main user-interface is the ```StateTransitionManager```. There is work in progress to remove it and split its functionality into several functions/classes to separate concerns\n",
+    "and to facilitate the modification of intermediate results like the filtering of ```QNProblemSet```s, setting allowed interaction types, etc. (see below)\n",
+    ":::"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -103,7 +113,18 @@
     "from IPython.display import display\n",
     "\n",
     "import qrules\n",
+    "from qrules.conservation_rules import (\n",
+    "    parity_conservation,\n",
+    "    spin_magnitude_conservation,\n",
+    "    spin_validity,\n",
+    ")\n",
     "from qrules.particle import Spin\n",
+    "from qrules.quantum_numbers import EdgeQuantumNumbers, NodeQuantumNumbers\n",
+    "from qrules.solving import (\n",
+    "    CSPSolver,\n",
+    "    dict_set_intersection,\n",
+    "    filter_quantum_number_problem_set,\n",
+    ")\n",
     "from qrules.topology import create_isobar_topologies, create_n_body_topology\n",
     "from qrules.transition import State"
    ]
@@ -315,6 +336,102 @@
     "graphviz.Source(dot)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Filtering quantum number problem sets"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Sometimes, only a certain subset of quantum numbers and conservation rules are relevant, or the number of solutions the {class}`.StateTransitionManager` gives by default is too large for the follow-up analysis.\n",
+    "The {func}`.filter_quantum_number_problem_set` function can be used to produce a {class}`.QNProblemSet` where only the desired quantum numbers and conservation rules are considered when fed back to the solver."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "desired_edge_properties = {EdgeQuantumNumbers.spin_magnitude, EdgeQuantumNumbers.parity}\n",
+    "desired_node_properties = {\n",
+    "    NodeQuantumNumbers.l_magnitude,\n",
+    "    NodeQuantumNumbers.s_magnitude,\n",
+    "}  # has to be reused in the CSPSolver-constructor\n",
+    "filtered_qn_problem_set = filter_quantum_number_problem_set(\n",
+    "    qn_problem_set,\n",
+    "    edge_rules={spin_validity},\n",
+    "    node_rules={spin_magnitude_conservation, parity_conservation},\n",
+    "    edge_properties=desired_edge_properties,\n",
+    "    node_properties=desired_node_properties,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "jupyter": {
+     "source_hidden": true
+    },
+    "tags": [
+     "hide-output"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "dot = qrules.io.asdot(filtered_qn_problem_set, render_node=True)\n",
+    "graphviz.Source(dot)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    ":::{warning}\n",
+    "The next cell will use some (currently) internal functionality. As statet at the top, a workflow similar to this will be used in future versions of ```qrules```. Manual setup of the {obj}`.CSPSolver` like in here will then also not be necessary.\n",
+    ":::"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "solver = CSPSolver([\n",
+    "    dict_set_intersection(\n",
+    "        qrules.system_control.create_edge_properties(part),\n",
+    "        desired_edge_properties,\n",
+    "    )\n",
+    "    for part in qrules.particle.load_pdg()\n",
+    "])\n",
+    "\n",
+    "filtered_qn_solutions = solver.find_solutions(filtered_qn_problem_set)\n",
+    "filtered_qn_result = filtered_qn_solutions.solutions[6]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "jupyter": {
+     "source_hidden": true
+    },
+    "tags": [
+     "hide-input"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "dot = qrules.io.asdot(filtered_qn_result, render_node=True)\n",
+    "graphviz.Source(dot)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -672,7 +789,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.7"
+   "version": "3.9.20"
   }
  },
  "nbformat": 4,

src/qrules/argument_handling.py

@@ -26,6 +26,7 @@
 Scalar = Union[int, float, Fraction]
 
 Rule = Union[GraphElementRule, EdgeQNConservationRule, ConservationRule]
+"""Any type of rule"""
 
 _ElementType = TypeVar("_ElementType")
 

src/qrules/quantum_numbers.py

@@ -103,7 +103,6 @@ class EdgeQuantumNumbers:
         edge_qn_type.__module__ = __name__
 
 
-# for static typing
 EdgeQuantumNumber = Union[
     EdgeQuantumNumbers.pid,
     EdgeQuantumNumbers.mass,
@@ -125,8 +124,8 @@ class EdgeQuantumNumbers:
     EdgeQuantumNumbers.c_parity,
     EdgeQuantumNumbers.g_parity,
 ]
+"""Type hint for quantum numbers of edges"""
 
-# for accessing the keys of the dicts in EdgeSettings
 EdgeQuantumNumberTypes = Union[
     type[EdgeQuantumNumbers.pid],
     type[EdgeQuantumNumbers.mass],
@@ -148,6 +147,7 @@ class EdgeQuantumNumbers:
     type[EdgeQuantumNumbers.c_parity],
     type[EdgeQuantumNumbers.g_parity],
 ]
+"""Type-Union for accessing the keys of the dicts in `.EdgeSettings`"""
 
 
 @frozen(init=False)
@@ -185,6 +185,7 @@ class NodeQuantumNumbers:
     type[NodeQuantumNumbers.s_projection],
     type[NodeQuantumNumbers.parity_prefactor],
 ]
+"""Type-Union for accessing the keys of the dicts in `.NodeSettings`"""
 
 
 def _to_optional_float(optional_float: float | None) -> float | None: