Loss decoding based on Pauli envelope

.ado/stages/build.yaml

@@ -116,11 +116,11 @@ stages:
                   # agents ship a much newer glibc (Ubuntu 22.04 = 2.35, Azure
                   # Linux 3 = 2.38) and a native link would raise the wheel's
                   # glibc floor above the tag we claim.
-                  pip install "maturin[zig]" pytest hypothesis more-itertools numpy
+                  pip install "maturin[zig]" pytest hypothesis more-itertools numpy scipy
                   maturin_args+=(--zig --target "$(uname -m)-unknown-linux-gnu" --compatibility $(manylinuxTag))
                   ;;
                 Darwin)
-                  pip install maturin pytest hypothesis more-itertools numpy
+                  pip install maturin pytest hypothesis more-itertools numpy scipy
                   ;;
                 *)
                   echo "Unsupported Unix platform: $(uname -s)" >&2
@@ -161,7 +161,7 @@ stages:
               python -m venv .venv
               .\.venv\Scripts\Activate.ps1
               pip install --upgrade pip
-              pip install maturin pytest hypothesis more-itertools numpy
+              pip install maturin pytest hypothesis more-itertools numpy scipy
 
               $wheelhouse = Join-Path $PWD 'target\wheels'
               function Build-AndTest([string]$cratePath, [string[]]$pytestArgs = @()) {

.github/workflows/build.yaml

@@ -74,14 +74,28 @@ jobs:
         with:
           python-version: "3.11"
           cache: 'pip'
+
+      - name: Configure Python embedding linker (Linux)
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          python_libdir="$(python -c 'import sysconfig; print(sysconfig.get_config_var("LIBDIR"))')"
+          python_soname="$(python -c 'import sysconfig; print(sysconfig.get_config_var("INSTSONAME") or sysconfig.get_config_var("LDLIBRARY"))')"
+          python_link_name="$(python -c 'import sys; print(f"libpython{sys.version_info.major}.{sys.version_info.minor}.so")')"
+          test -f "$python_libdir/$python_soname"
+          python_link_dir="$RUNNER_TEMP/python-lib"
+          mkdir -p "$python_link_dir"
+          ln -sf "$python_libdir/$python_soname" "$python_link_dir/$python_link_name"
+          echo "LIBRARY_PATH=$python_link_dir${LIBRARY_PATH:+:$LIBRARY_PATH}" >> "$GITHUB_ENV"
+          echo "LD_LIBRARY_PATH=$python_libdir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" >> "$GITHUB_ENV"
 
       - name: Create Python virtual environment and install dependencies (Linux/Mac)
         if: runner.os != 'Windows'
         run: |
           python -m venv qdk_env
           source qdk_env/bin/activate
           python -m pip install --upgrade pip
-          pip install maturin pytest pytest-asyncio hypothesis more-itertools numpy
+          pip install maturin pytest pytest-asyncio hypothesis more-itertools numpy scipy
 
       - name: Create Python virtual environment and install dependencies (Windows)
         if: runner.os == 'Windows'
@@ -90,7 +104,7 @@ jobs:
           python -m venv qdk_env
           call qdk_env\Scripts\activate.bat
           python -m pip install --upgrade pip
-          pip install maturin pytest pytest-asyncio hypothesis more-itertools numpy
+          pip install maturin pytest pytest-asyncio hypothesis more-itertools numpy scipy
 
       - name: Build binar Python bindings (Linux/Mac)
         if: runner.os != 'Windows'

deq/CHANGELOG.md

@@ -8,10 +8,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Changed
+- `deq annotate` now always retains physical noise under `@SIMULATE_ONLY` while
+  emitting canonical `ERROR` and `LOSS` metadata for decoding. Noisy
+  measurements receive clean `@DECODE_ONLY` counterparts.
+- Black-box decoders now expose capabilities and receive one unified decode
+  request. Per-shot edge reweights and structured loss may be supplied together;
+  unsupported fields fail explicitly instead of triggering a decoder-side
+  fallback.
+- Monolithic and window coordinators now apply `Outcomes.modifiers` as
+  shot-scoped probability overrides. The `decoder_reweighting` policy controls
+  whether overrides use loaded decoder support or an equivalent one-shot graph.
+- Preselection consumers now recognize QDK 1.31's `SELECT { ... REQUIRE ... }`
+  syntax. Legacy `PREPARE { ... }` input remains accepted for older generated
+  Stim files.
 
 ## [0.4.2] - 2026-08-03
 
 ### Removed
+- **Breaking:** remove the `deq annotate --keep-noise` option; its behavior is   
+  now the unconditional default.
 - **Breaking:** bare physical Pauli targets in `ERROR(p)` statements (e.g.
   `ERROR(0.05) C0 X0`) are no longer valid syntax (previously already rejected by the transpiler).
 

deq/deq/circuit/deqagram_shim.py

@@ -401,6 +401,28 @@ def _gadget_statement_impl(
                 expected_value=preselect.expected_value,
                 decorators=decorators,
             )
+        case deqagram.AttachedGadget.Statement(deqagram.GadgetStatement.Loss(loss)):
+            if loss.input_port is not None:
+                if loss.source_errors:
+                    raise SyntaxError(
+                        "input LOSS(IN<i>.L<j>) must not carry source-error (SE) "
+                        "targets"
+                    )
+            elif loss.probability is None or not 0.0 < loss.probability <= 1.0:
+                raise SyntaxError(
+                    f"LOSS probability must be in (0, 1], got {loss.probability}"
+                )
+            return model.LossStatement(
+                probability=loss.probability,
+                input_port=loss.input_port,
+                input_qubit=loss.input_qubit,
+                source_errors=list(loss.source_errors),
+                continuation_errors=list(loss.continuation_errors),
+                child_losses=list(loss.child_losses),
+                output_qubits=[(port, qubit) for port, qubit in loss.output_qubits],
+                measurement_indices=list(loss.measurement_indices),
+                decorators=decorators,
+            )
         case _:
             raise TypeError(f"unexpected gadget statement: {decorated.statement!r}")
 

deq/deq/circuit/model.py

@@ -457,6 +457,52 @@ class ErrorStatement:
     decorators: list[Decorator] = field(default_factory=list)
 
 
+@dataclass
+class LossStatement:
+    """A ``LOSS(...)`` declaration mirroring one JIT loss-model entry.
+
+    A *source* loss carries the declared ``LOSS_ERROR`` probability. An
+    *input* loss (``input_port``/``input_qubit`` set) is the continuation of
+    a loss entering on that input physical qubit; it carries no probability
+    and no source-error generators, and its position is identified by the
+    ``IN<i>.L<j>`` head rather than by list order.
+
+    ``source_errors`` / ``continuation_errors`` index the
+    gadget's ``ERROR`` mechanisms; ``child_losses`` index the source
+    losses (within-gadget children); ``output_qubits`` are ``(port, qubit)``
+    physical exits; ``measurement_indices`` are herald measurements. These
+    collections are set-valued, so explicit duplicate references are rejected.
+    """
+
+    probability: float | None = None
+    input_port: int | None = None
+    input_qubit: int | None = None
+    source_errors: list[int] = field(default_factory=list)
+    continuation_errors: list[int] = field(default_factory=list)
+    child_losses: list[int] = field(default_factory=list)
+    output_qubits: list[tuple[int, int]] = field(default_factory=list)
+    measurement_indices: list[int] = field(default_factory=list)
+    decorators: list[Decorator] = field(default_factory=list)
+
+    @property
+    def is_input(self) -> bool:
+        """Whether this is an input-continuation loss (vs a source loss)."""
+        return self.input_port is not None
+
+    def __str__(self) -> str:
+        if self.is_input:
+            head = f"LOSS(IN{self.input_port}.L{self.input_qubit})"
+        else:
+            head = f"LOSS({self.probability})"
+        parts = [head]
+        parts += [f"SE{i}" for i in self.source_errors]
+        parts += [f"CE{i}" for i in self.continuation_errors]
+        parts += [f"L{i}" for i in self.child_losses]
+        parts += [f"OUT{port}.L{qubit}" for port, qubit in self.output_qubits]
+        parts += [f"M{i}" for i in self.measurement_indices]
+        return " ".join(parts)
+
+
 @dataclass
 class ConditionalStatement:
     """A ``CONDITIONAL R<j> L<P><i>...`` or ``CONDITIONAL rec[-k] L<P><i>...`` declaration.
@@ -584,6 +630,7 @@ class PreselectStatement:
     | ReadoutStatement
     | CheckStatement
     | ErrorStatement
+    | LossStatement
     | ConditionalStatement
     | VirtualLogicalStatement
     | PropagateStatement

deq/deq/circuit/vscode-deq/README.md

@@ -9,6 +9,7 @@ Syntax highlighting for `.deq` quantum error correction files.
   - `LOGICAL`, `STABILIZER` declarations with Pauli products
   - `INPUT`, `OUTPUT`, `CHECK`, `READOUT` statements
   - `ERROR(prob)` and `MEASURE(count)` statements
+  - `LOSS_ERROR(prob)` instructions and `LOSS(...)` loss-model statements with their `SE`/`CE`/`L`/`OUT.L`/`M` targets
   - Distinct colors for check (`C0`), Pauli (`X0`/`Y0`/`Z0`), readout (`R0`), and logical Pauli shortcut (`LX0`/`LY0`/`LZ0`) targets
   - `ASSERT_EQ` assertions
   - Gadget applications with `IN(...)` / `OUT(...)` port bindings

deq/deq/circuit/vscode-deq/syntaxes/deq.tmLanguage.json

@@ -299,6 +299,9 @@
         {
           "include": "#error-statement"
         },
+        {
+          "include": "#loss-statement"
+        },
         {
           "include": "#conditional-statement"
         },
@@ -568,6 +571,62 @@
         }
       ]
     },
+    "loss-statement": {
+      "begin": "\\b(LOSS)(?![A-Za-z0-9_])\\s*(\\()",
+      "beginCaptures": {
+        "1": {
+          "name": "keyword.directive.deq"
+        },
+        "2": {
+          "name": "punctuation.bracket.deq"
+        }
+      },
+      "end": "(?=#)|$",
+      "patterns": [
+        {
+          "include": "#mako-expression"
+        },
+        {
+          "match": "IN\\d+\\.L\\d+",
+          "name": "entity.name.tag.logical.deq"
+        },
+        {
+          "include": "#loss-targets"
+        },
+        {
+          "match": "-?\\d+(?:\\.\\d*)?(?:[eE][+-]?\\d+)?",
+          "name": "constant.numeric.deq"
+        },
+        {
+          "match": "\\)",
+          "name": "punctuation.bracket.deq"
+        }
+      ]
+    },
+    "loss-targets": {
+      "patterns": [
+        {
+          "match": "SE\\d+",
+          "name": "support.class.loss.source.deq"
+        },
+        {
+          "match": "CE\\d+",
+          "name": "support.class.loss.continuation.deq"
+        },
+        {
+          "match": "OUT\\d+\\.L\\d+",
+          "name": "entity.name.tag.logical.deq"
+        },
+        {
+          "match": "L\\d+",
+          "name": "support.class.loss.child.deq"
+        },
+        {
+          "match": "M\\d+",
+          "name": "variable.other.deq"
+        }
+      ]
+    },
     "conditional-statement": {
       "begin": "\\b(CONDITIONAL)\\b",
       "beginCaptures": {

deq/deq/cli/annotate.py

@@ -8,6 +8,7 @@
 from deq.cli.strip_tags import strip_jit_library
 from deq.transpiler.jit_annotate import annotate as _annotate_impl
 from deq.transpiler.jit_library_builder import build_jit_library
+from deq.transpiler.loss import create_loss_model
 from deq.circuit.mako_support import parse_mako_vars
 
 
@@ -23,18 +24,17 @@ def annotate(
     mako: list[str] | None = None,
     #: suppress the interactive Mako safety prompt
     skip_mako_warning: bool = False,
+    #: physical loss model: "neutral-atom", "trapped-ion", "none", or a .py file
+    loss_model: str = "neutral-atom",
     #: skip verification that annotated output transpiles identically
     no_verify: bool = False,
-    #: keep noise instructions verbatim instead of commenting them
-    #: out and emitting expanded ERROR rows
-    keep_noise: bool = False,
 ) -> None:
     """
     Rewrite a .deq file to mirror the structure of its compiled .deq.jit.
 
     Inlines imports, replaces stabilizers/logicals with `_` identity
-    placeholders (originals kept as comments), comments out noise instructions,
-    forces every gadget to
+    placeholders (originals kept as comments), separates physical noise from
+    decoder metadata, and forces every gadget to
     @CHECKS("manual", verify=0), and inserts auto-derived CHECKs (marked
     `# auto`). COMPOSE/PROGRAM blocks are emitted commented-out for reference.
 
@@ -47,13 +47,15 @@ def annotate(
     error probabilities are reproducible.
     Use ``--no-verify`` to skip this (faster but no correctness guarantee).
 
-    With ``--keep-noise``, noise instructions (``X_ERROR``,
-    ``DEPOLARIZE1/2``, noisy measurements, etc.) are emitted verbatim
-    in the annotated output and the corresponding ``ERROR(p) ...``
-    rows are *not* emitted.  Re-transpilation of the annotated file
-    re-derives those ERROR rows from the kept noise instructions.
-    This is the recommended mode for producing a Stim-simulatable
-    annotated file.
+    Undecorated noise instructions (``X_ERROR``, ``DEPOLARIZE1/2``,
+    ``LOSS_ERROR``, noisy measurements, etc.) are split by visibility: the
+    original noisy instruction is retained under ``@SIMULATE_ONLY`` for Stim
+    sampling, while canonical ``ERROR(p) ...`` rows and loss metadata carry
+    its decode-side effect. A decode-visible noisy measurement additionally
+    keeps a clean ``@DECODE_ONLY`` measurement instruction. Existing
+    ``@SIMULATE_ONLY`` and ``@DECODE_ONLY`` intent is preserved; measurement
+    instructions must still be paired so both views produce the same number
+    of records.
 
     Args:
         deq_file: path to the input .deq file.
@@ -76,7 +78,8 @@ def annotate(
         skip_mako_warning=skip_mako_warning,
     )
 
-    rendered = _annotate_impl(qfile, keep_noise=keep_noise)
+    selected_loss_model = create_loss_model(loss_model)
+    rendered = _annotate_impl(qfile, loss_model=selected_loss_model)
 
     # Determine output path.
     if out is None:
@@ -94,12 +97,12 @@ def annotate(
 
     # Verify: transpile the annotated output and compare.
     print(
-        f"Verifying annotated output is equivalent to original",
-        f"(pass --no-verify to skip)...",
+        "Verifying annotated output is equivalent to original",
+        "(pass --no-verify to skip)...",
         file=sys.stderr,
     )
-    orig_lib = build_jit_library(qfile)
-    anno_lib = build_jit_library(parse_deq(rendered))
+    orig_lib = build_jit_library(qfile, loss_model=selected_loss_model)
+    anno_lib = build_jit_library(parse_deq(rendered), loss_model=selected_loss_model)
     orig_stripped, _ = strip_jit_library(orig_lib)
     anno_stripped, _ = strip_jit_library(anno_lib)
     if orig_stripped.SerializeToString() == anno_stripped.SerializeToString():

deq/deq/cli/interpret.py

@@ -241,12 +241,16 @@ def _load_library(
         import tempfile
         from deq.circuit.parser import render_and_parse_file
         from deq.transpiler.jit_library_builder import build_jit_library
+        from deq.transpiler.loss import NeutralAtomLossModel
         from deq.cli.jit import jit_compile_program_to_file
         from deq.compiler.jit_compiler import static_jit_compiler
         import deq.proto.deq_jit_pb2 as jit_pb
 
         qfile = render_and_parse_file(file)
-        jit_library = build_jit_library(qfile)
+        jit_library = build_jit_library(
+            qfile,
+            loss_model=NeutralAtomLossModel(),
+        )
         with tempfile.TemporaryDirectory() as tmpdir:
             jit_path = os.path.join(tmpdir, "temp.deq.jit")
             jit_compile_program_to_file(jit_library, qfile, jit_path, program=program)