This issue is part of unitaryHACK26. You have to be registered to complete this issue.
Learn more about the PR submission process here and about unitaryHACK rules here!

A note about AI Slop: while we are open to collaboration with LLMs for unitaryHACK, fully AI-generated PRs are not acceptable. It is at the maintainers' discretion whether or not LLM-generated PRs are the right fit for the issues, and those that appear fully AI-generated may be immediately rejected. Read unitaryHACK's full AI Policy here.

Note from the maintainer: If you have not contributed before to open source projects, no AI agent use is permitted for this issue.

Many quantum error-correction workflows use Stim detector error model (.dem)
files as an interchange format. QuantumClifford has fast Pauli-frame simulation
machinery, but there is currently no convenient way to ingest an existing .dem
file and turn it into a QuantumClifford circuit. Importing .dem files as
circuits would let users compare Stim-generated models with QuantumClifford
decoders and analysis tools while continuing to use the existing
pftrajectories backend for sampling.

Relevant links:

• QuantumClifford repository: https://github.com/QuantumSavory/QuantumClifford.jl
• Pauli-frame implementation: https://github.com/QuantumSavory/QuantumClifford.jl/blob/main/src/pauli_frames.jl
• Existing noisy circuit operations: https://github.com/QuantumSavory/QuantumClifford.jl/blob/main/src/noise.jl
• Stim detector error model format: https://github.com/quantumlib/Stim/blob/main/doc/file_format_dem_detector_error_model.md

Desired user-facing behavior

A user should be able to load a .dem file and receive a corresponding
QuantumClifford circuit that can be passed directly to pftrajectories:

using QuantumClifford

circuit = read_detector_error_model("surface_code.dem")
frames = pftrajectories(circuit; trajectories=10_000)

measurements(frames)

The exact function name can change, but the output should be a circuit-like
object, a vector of operations, that is accepted by the
existing pftrajectories methods:

circuit = detector_error_model_circuit("surface_code.dem")
frames = pftrajectories(circuit; trajectories=10_000)
measurements(frames)

The important requirement is that sampling remains implemented by
pftrajectories. This bounty should not introduce a separate sampling backend.

Suggested implementation

Implement a parser for the useful subset of Stim detector error model syntax:

• error(p) D... L...
• detector ...
• logical_observable ...
• shift_detectors ...
• repeat K { ... }
• comments and blank lines

Coordinates on detector or shift_detectors lines can be parsed and stored if
convenient, but it is acceptable to ignore them initially as long as the detector
index shifts are handled correctly.

The parser should lower the .dem file to operations that pftrajectories can
execute. If the existing gate set is not expressive enough, add a small number of
new circuit operations for detector error model semantics. For example, an
operation like this may be useful:

DetectorError(probability, detector_bits, logical_bits)

When applied to a PauliFrame, this operation would sample one independent
Bernoulli event per trajectory and XOR the corresponding detector and logical
bits into the frame's measurement storage. A no-op declaration operation may also
be needed so explicitly declared detectors or logical observables with no errors
still allocate output columns.

The semantics should match Stim's .dem documentation: each error(p) line is
an independent error mechanism, and when it occurs it flips the listed detector
and logical targets. The implementation should express that behavior through
QuantumClifford circuit operations, then rely on pftrajectories to run many
trajectories efficiently.

Minimal example

Given this file:

detector D0
detector D1
logical_observable L0
error(0.1) D0
error(0.2) D0 D1 L0

the importer should produce a model with two detectors, one logical observable,
and two independent error mechanisms. The returned circuit should be accepted by
pftrajectories; sampling that circuit many times should produce detector and
logical outcome frequencies consistent with those probabilities.

In scope

• A documented circuit representation for imported detector error models.
• A parser for common Stim .dem files, including nested repeat blocks and
  shift_detectors.
• Any small new AbstractOperation subtypes needed to represent .dem
  semantics in circuits.
• apply!/affectedbits support needed for those operations to work with
  PauliFrame and pftrajectories.
• Tests comparing small hand-written .dem files against known expected
  detector/logical distributions.
• Optional statistical comparison against Stim's own sampler when Stim is
  available.
• Clear error messages for unsupported syntax.

Out of scope

• Parsing Stim circuit (.stim) files.
• Decoding the sampled detector data.
• A new sampling engine separate from pftrajectories.
• Exact bit-for-bit matching of Stim's random number generator.
• Full preservation of coordinate metadata, unless this is straightforward.

Acceptance criteria

• read_detector_error_model(path) or an equivalent API imports a .dem file
  and returns a circuit-like object accepted by pftrajectories.
• The parser handles error, detector, logical_observable,
  shift_detectors, and repeat for representative files.
• New .dem-specific operations, if added, implement the affectedbits and
  apply! methods needed by pftrajectories.
• pftrajectories(imported_circuit; trajectories=...) returns detector and
  logical bit arrays with documented dimensions.
• Statistical tests validate the imported circuit on small models.
• Documentation includes a short imported .dem example and the expected output
  shape.