Loss decoding based on Pauli envelope

[Yue Wu (yuewuo)]

Adds end-to-end Pauli-envelope loss decoding support:

• Compiles configurable gate-loss policies into causal loss graphs while preserving herald identity across gadgets and decode windows.
• Adds language support for the Pauli-envelope data that can is output by the annotator and can be inspected or edited by user
• Adds coordinator strategies to ignore loss, convert it into shot-scoped edge reweights, or pass structured LossInfo to loss-aware decoders.
• Supports decoder capability negotiation, persistent graph reuse, and random imputation of lost measurement outcomes.
• Includes a herald-aware MLE reference decoder, updated protobuf/Python/CLI APIs, comprehensive tests, and tutorial documentation.

[Juan M. Bello-Rivas (jmbr)]

Why switch from expect to unwrap?

[Juan M. Bello-Rivas (jmbr)]

Use Literal['neutral-atom', 'trapped-ion', 'none'] as type instead of str. Consider an enum if it makes sense.

[Juan M. Bello-Rivas (jmbr)]

Use Literal[...] or some enum class.

[Juan M. Bello-Rivas (jmbr)]

These hard-coded defaults ought to be dealt with. The simplest way would be to centralize them somewhere (e.g., a defaults.py module with documented constants with names such as DEFAULT_TIMEOUT).

[Juan M. Bello-Rivas (jmbr)]

Same thing with these string literal constants: let's do something about them.

[Juan M. Bello-Rivas (jmbr)]

The embedded HTML tags read poorly outside of a web browser. And even in a web browser they could be simplified with CSS.

[Juan M. Bello-Rivas (jmbr)]

The same error mechanism (edge) can appear in source_edges and continuation_edges for one loss site. Processing those entries independently double-counts the physical loss and artificially increases the edge's activation and reweighted probability.

[Juan M. Bello-Rivas (jmbr)]

The transpiler can map an ordinary Pauli error and a loss-envelope generator to the same decoder edge when their detectors match. The MLE decoder then treats the shared edge as loss-only, which can make an otherwise valid decoding problem infeasible. See:

from importlib.util import module_from_spec, spec_from_file_location
from pathlib import Path
from types import SimpleNamespace as Namespace


def check_mixed_regular_loss_edge() -> None:
    module_path = Path("deq/deq_runtime/src/decoder/mle_loss_decoder.py")
    spec = spec_from_file_location("mle_loss_decoder", module_path)
    assert spec is not None and spec.loader is not None
    module = module_from_spec(spec)
    spec.loader.exec_module(module)

    graph = Namespace(
        vertex_num=2,
        hyperedges=[
            Namespace(vertices=[0], probability=0.001),
            Namespace(vertices=[1], probability=0.0),
        ],
    )

    def site(*, source=(), children=()):
        return Namespace(
            source_edges=list(source),
            continuation_edges=[],
            children=list(children),
            heralds=[0],
            probability=0.1,
        )

    def decode(sites):
        return module.Decoder(graph).decode(
            [0, 1],
            Namespace(sites=sites),
        )

    try:
        decode([
            site(source=(0,), children=(1,)),
            site(source=(1,)),
        ])
    except RuntimeError as error:
        assert "infeasible" in str(error).lower()
        print(f"mixed case: {error}")
    else:
        raise AssertionError(
            "mixed regular/loss edge unexpectedly remained feasible"
        )

    regular_control = decode([
        site(children=(1,)),
        site(source=(1,)),
    ])
    conflict_control = decode([
        site(source=(0,)),
        site(source=(1,)),
    ])

    assert regular_control == [0, 1]
    assert conflict_control == [0, 1]
    print(f"regular control: {regular_control}")
    print(f"conflict control: {conflict_control}")


check_mixed_regular_loss_edge()

[Juan M. Bello-Rivas (jmbr)]

Corner case: this returns an empty correction without checking whether the syndrome is empty. A graph with one detector, no edges, and syndrome {0} is accepted despite the fact that it can't be explained.

[Juan M. Bello-Rivas (jmbr)]

This RuntimeError will trigger a panic instead of returning a nicer, more intelligible decoder failure.

[Juan M. Bello-Rivas (jmbr)]

deq's transpile --detectors raises an exception when the generated Stim circuit contains LOSS_ERROR. The circuit is written to disk without DETECTOR or OBSERVABLE_INCLUDE annotations.

To reproduce:

deq transpile \
  deq/documents/tutorial/examples/loss-simulation/repetition_code.deq \
  --out /tmp/repetition-loss.deq.jit \
  --program Memory \
  --jobs 1 \
  --mako d=3 \
  --mako p=0.001 \
  --mako p_loss=0.01 \
  --mako rounds=9 \
  --mako replenish=0 \
  --skip-mako-warning \
  --detectors

The output:

Generated JIT library: /tmp/repetition-loss.deq.jit
  Port types: 1
  Gadget types: 3
  Program instructions: 11
Generated stim circuit: /tmp/repetition-loss.stim
Traceback (most recent call last):
  File "/home/jmbr/sources/qdk-ec-pr166/.venv/bin/deq", line 10, in <module>
    sys.exit(run())
             ^^^^^
  File "/home/jmbr/sources/qdk-ec-pr166/deq/deq/cli/__init__.py", line 45, in run
    arguably.run()
  File "/home/jmbr/sources/qdk-ec-pr166/.venv/lib/python3.12/site-packages/arguably/_context.py", line 732, in run
    result = cmd.call(parsed_args)
             ^^^^^^^^^^^^^^^^^^^^^
  File "/home/jmbr/sources/qdk-ec-pr166/.venv/lib/python3.12/site-packages/arguably/_commands.py", line 409, in call
    return self.function(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/jmbr/sources/qdk-ec-pr166/deq/deq/cli/jit.py", line 113, in transpile
    _annotate_stim_with_detectors(jit_library, _stim_path_for(out), assertions)
  File "/home/jmbr/sources/qdk-ec-pr166/deq/deq/cli/jit.py", line 310, in _annotate_stim_with_detectors
    body = stim.Circuit.from_file(stim_path)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ValueError: Gate not found: 'LOSS_ERROR'