Add Stim MPP stabilizer import

.github/pull_request_template.md

@@ -5,7 +5,7 @@ Before submitting, please check the following:
 - Format added code by `uv run ruff`
 - Type checking by `uv run mypy` and `uv run pyright`
 - Make sure the checks (github actions) pass.
-- Check that the docs compile without errors (run `uv run sphinx-build -W docs/source docs/build` after `uv sync --extra doc`.)
+- Check that the docs compile without errors (run `uv run sphinx-build -W docs/source docs/build` after `uv sync --extra doc --extra stim`.)
 
 Then, please fill in below:
 

.github/workflows/coverage.yml

@@ -30,7 +30,7 @@ jobs:
           enable-cache: true
 
       - name: Install dependencies
-        run: uv sync --locked --python 3.13 --extra dev --extra pyzx
+        run: uv sync --locked --python 3.13 --extra dev --extra pyzx --extra stim
 
       - name: Run pytest with coverage
         run: uv run --no-sync pytest --cov=graphqomb --cov-report=term-missing --cov-report=xml --cov-branch

.github/workflows/doc.yml

@@ -22,7 +22,7 @@ jobs:
           uv-version: "0.11.16"
           enable-cache: true
 
-      - run: uv sync --locked --python 3.13 --extra doc
+      - run: uv sync --locked --python 3.13 --extra doc --extra stim
 
       - name: Make docs
         run: uv run --no-sync sphinx-build -W docs/source docs/build

.github/workflows/pytest.yml

@@ -33,7 +33,7 @@ jobs:
           uv-version: "0.11.16"
           enable-cache: true
 
-      - run: uv sync --locked --python ${{ matrix.python }} --extra dev
+      - run: uv sync --locked --python ${{ matrix.python }} --extra dev --extra stim
 
       - run: uv run --no-sync pytest -m "not pyzx"
 
@@ -53,6 +53,6 @@ jobs:
           uv-version: "0.11.16"
           enable-cache: true
 
-      - run: uv sync --locked --python 3.13 --extra dev --extra pyzx
+      - run: uv sync --locked --python 3.13 --extra dev --extra pyzx --extra stim
 
       - run: uv run --no-sync pytest -m pyzx

.github/workflows/typecheck.yml

@@ -26,6 +26,6 @@ jobs:
           uv-version: "0.11.16"
           enable-cache: true
 
-      - run: uv sync --locked --python 3.10 --extra dev
+      - run: uv sync --locked --python 3.10 --extra dev --extra stim
 
       - run: uv run --no-sync ${{ matrix.tool }}

.readthedocs.yaml

@@ -21,3 +21,4 @@ python:
       command: sync
       extras:
         - doc
+        - stim

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **QEC Stim MPP Import**: Added utilities for building `StabilizerCode` inputs from unsigned Stim `MPP` layers, including sparse Stim qubit id mapping, coordinate import, multi-layer selection, detector/logical-observable import, and the optional `graphqomb[stim]` extra. Signed products using inverted Pauli targets are rejected because stabilizer signs are not retained.
+
 ### Changed
 
 - **Development Tooling**: Use uv as the default dependency manager for local development, CI, documentation builds, and publishing workflows.

README.md

@@ -50,6 +50,12 @@ Install optional PyZX integration:
 uv add "graphqomb[pyzx]"
 ```
 
+Install optional Stim integration:
+
+```bash
+uv add "graphqomb[stim]"
+```
+
 ### From Source
 
 ```bash
@@ -107,6 +113,8 @@ If you already have a graph-state design and explicit feedforward maps, you can
 - **Architecture overview**: https://graphqomb.readthedocs.io/en/latest/architecture.html
 - **Example gallery**: https://graphqomb.readthedocs.io/en/latest/gallery/index.html
 - **API reference**: https://graphqomb.readthedocs.io/en/latest/references.html
+- **QEC graph-state builder reference**: https://graphqomb.readthedocs.io/en/latest/qec.html
+- **Stim MPP import reference**: https://graphqomb.readthedocs.io/en/latest/stim_mpp.html
 - **Stim compiler reference**: https://graphqomb.readthedocs.io/en/latest/stim_compiler.html
 
 ## Current Scope

docs/source/qec.rst

@@ -0,0 +1,14 @@
+QEC graph-state builder
+=======================
+
+``graphqomb.qec.qeccode`` provides the stabilizer-code representation and the
+Type I and Type II graph-state builders used by the QEC helper workflow.
+
+Coordinate tuples are retained without restricting their dimensionality. The
+graph-state builder uses the first two qubit-coordinate components for the data
+plane and the first three explicitly supplied stabilizer-coordinate components
+for ancilla placement.
+
+.. automodule:: graphqomb.qec.qeccode
+   :members:
+   :show-inheritance:

docs/source/references.rst

@@ -21,6 +21,8 @@ Module reference
     pauli_frame
     qompiler
     scheduler
+    qec
+    stim_mpp
     stim_compiler
     noise_model
     visualizer

docs/source/stim_mpp.rst

@@ -0,0 +1,39 @@
+Stim MPP import
+===============
+
+Install the optional Stim integration before importing this module:
+
+.. code-block:: console
+
+   uv add "graphqomb[stim]"
+
+The importer converts unsigned Stim ``MPP`` products into a
+:class:`graphqomb.qec.qeccode.StabilizerCode`. It does not retain stabilizer
+signs. Consequently, signed products written with an inverted Pauli target,
+such as ``MPP !X0*Z1``, raise :class:`ValueError` instead of silently losing
+the sign.
+
+The result also provides dense-column mappings for sparse Stim qubit ids and
+can map selected ``DETECTOR`` and ``OBSERVABLE_INCLUDE`` records to graph-state
+ancilla nodes.
+
+Set ``coord_dims`` to the number of leading ``QUBIT_COORDS`` components to
+retain. The importer does not restrict this value to two or three dimensions;
+each referenced coordinate declaration must contain at least the requested
+number of components.
+
+.. code-block:: python
+
+   from graphqomb.qec.qeccode import build_graph_state
+   from graphqomb.qec.stim_mpp import stabilizer_code_from_stim_text
+
+   extraction = stabilizer_code_from_stim_text("MPP X0*Z2")
+   graph_result = build_graph_state(extraction.code)
+   detector_groups = extraction.detector_groups(graph_result.ancilla_nodes)
+
+API reference
+-------------
+
+.. automodule:: graphqomb.qec.stim_mpp
+   :members:
+   :show-inheritance:

graphqomb/qec/__init__.py

@@ -0,0 +1 @@
+"""qec submodule."""