Tsim API

def __add__(self, other: Circuit | stim.Circuit) -> Circuit:
    """Return a new circuit with another circuit appended."""
    result = Circuit.from_stim_program(self._stim_circ.copy())
    result += other
    return result

def __eq__(self, other: object) -> bool:
    """Check equality with another circuit."""
    if isinstance(other, Circuit):
        return self._stim_circ == other._stim_circ
    return NotImplemented

def __getitem__(
    self,
    index_or_slice: object,
) -> object:
    """Return copies of instructions from the circuit.

    Args:
        index_or_slice: An integer index picking out an instruction to return, or a
            slice picking out a range of instructions to return as a circuit.

    Returns:
        If the index was an integer, then an instruction from the circuit.
        If the index was a slice, then a circuit made up of the instructions in that
        slice.

    """
    if isinstance(index_or_slice, int):
        return self._stim_circ[index_or_slice]
    elif isinstance(index_or_slice, slice):
        return Circuit.from_stim_program(self._stim_circ[index_or_slice])
    else:
        raise TypeError(f"Invalid index or slice: {index_or_slice}")

def __iadd__(self, other: Circuit | stim.Circuit) -> Circuit:
    """Append another circuit to this circuit in-place."""
    if isinstance(other, Circuit):
        self._stim_circ += other._stim_circ
    else:
        self._stim_circ += other
    return self

def __imul__(self, repetitions: int) -> Circuit:
    """Repeat this circuit in-place."""
    self._stim_circ *= repetitions
    return self

def __len__(self) -> int:
    """Return the number of instructions in the circuit."""
    return len(self._stim_circ)

def __mul__(self, repetitions: int) -> Circuit:
    """Return a new circuit repeated the given number of times."""
    return Circuit.from_stim_program(self._stim_circ * repetitions)

def __repr__(self) -> str:
    """Return a string representation that can recreate the circuit."""
    return f"tsim.Circuit('''\n{self!s}\n''')"

def __rmul__(self, repetitions: int) -> Circuit:
    """Return a new circuit repeated the given number of times."""
    return self * repetitions

def __str__(self) -> str:
    """Return the circuit as program text."""
    return stim_to_shorthand(str(self._stim_circ))

def append(
    self,
    name: str | stim.CircuitInstruction | stim.CircuitRepeatBlock | stim.Circuit,
    targets: (
        int
        | stim.GateTarget
        | stim.PauliString
        | Iterable[int | stim.GateTarget | stim.PauliString]
    ) = (),
    arg: float | Iterable[float] | None = None,
    *,
    tag: str = "",
) -> None:
    """Append an operation into the circuit.

    Besides Stim's gates, this accepts Tsim's gates:

    - ``T``, ``T_DAG`` on qubits, and ``TPP``, ``TPP_DAG`` on Pauli products.
    - ``R_X``, ``R_Y``, ``R_Z`` and ``U3`` on qubits, ``R_XX``, ``R_YY`` and
      ``R_ZZ`` on two distinct qubits, and ``R_PAULI`` on Pauli products.
      ``U3`` takes three angles ``(theta, phi, lambda)`` as ``arg``, the
      others one. Angles are in units of π.
    - ``CCZ`` and ``CCX`` on bare qubit targets, in groups of three. They are
      appended as their Clifford+T decomposition.

    The other Tsim gates are stored as tagged Clifford placeholders.

    Gate names are case-insensitive.

    Args:
        name: The name of the operation's gate (e.g. "H" or "M" or "CNOT").

            This argument can also be set to a `stim.CircuitInstruction`,
            `stim.CircuitRepeatBlock` or `stim.Circuit`, which results in the
            instruction, block or circuit being appended to the circuit. The
            other arguments (targets, arg and tag) can't be specified when
            doing so.

        targets: The objects operated on by the gate. This can be either a
            single target or an iterable of multiple targets.

            Each target can be:
                An int: The index of a targeted qubit.
                A `stim.GateTarget`: Could be a variety of things. Methods like
                    `stim.target_rec`, `stim.target_sweep_bit`, `stim.target_x`,
                    and `stim.CircuitInstruction.__getitem__` all return this
                    type.
                A `stim.PauliString`: This will automatically be expanded into
                    a product of pauli targets like `X1*Y2*Z3`.
        arg: The "parens arguments" for the gate, such as the probability for a
            noise operation. A double or list of doubles parameterizing the
            gate. Different gates take different parens arguments. For example,
            X_ERROR takes a probability, OBSERVABLE_INCLUDE takes an observable
            index, PAULI_CHANNEL_1 takes three disjoint probabilities, and R_X
            takes an angle in units of π.

        tag: A customizable string attached to the instruction.

    """
    if isinstance(name, str):
        # NOTE: Stim gate names are case-insensitive, and so are Tsim's.
        name = name.upper()
        if name in ("CCZ", "CCX"):
            if arg is not None:
                raise ValueError(f"For {name} gates, no arguments are accepted.")
            qubits = _bare_qubit_targets(name, targets)
            if len(qubits) % 3 != 0:
                raise ValueError(
                    f"{name} expects qubit targets in groups of three."
                )
            self.append_from_stim_program_text(
                "\n".join(
                    line
                    for i in range(0, len(qubits), 3)
                    for line in controlled_gate_decomposition_lines(
                        name, qubits[i], qubits[i + 1], qubits[i + 2], tag=tag
                    )
                )
            )
            return

        if name in _PAULI_PRODUCT_GATES:
            targets = _signed_pauli_targets(
                targets, combined=name != "OBSERVABLE_INCLUDE"
            )

        if name == "TPP":
            name = "SPP"
            tag = encode_t_tag(tag)
        elif name == "TPP_DAG":
            name = "SPP_DAG"
            tag = encode_t_tag(tag)
        elif name == "T":
            name = "S"
            tag = encode_t_tag(tag)
        elif name == "T_DAG":
            name = "S_DAG"
            tag = encode_t_tag(tag)
        elif name in ("R_X", "R_Y", "R_Z"):
            if arg is None:
                raise ValueError(f"For {name} gates, an angle must be provided.")
            args = list(arg) if isinstance(arg, Iterable) else [arg]
            if len(args) != 1:
                raise ValueError(
                    f"For {name} gates, a single angle must be provided."
                )
            tag = f"{name}(theta={args[0]}*pi)"
            name = "I"
            arg = None
        elif name == "U3":
            args = list(arg) if isinstance(arg, Iterable) else []
            if arg is None or len(args) != 3:
                raise ValueError(
                    "For U3 gates, three rotation angles must be provided."
                )
            theta, phi, lam = args
            tag = f"U3(theta={theta}*pi, phi={phi}*pi, lambda={lam}*pi)"
            name = "I"
            arg = None
        elif name in ("R_XX", "R_YY", "R_ZZ"):
            alpha = _single_angle(name, arg)
            pauli = name[2]
            q0, q1 = _two_distinct_qubits(name, targets)
            targets = _pauli_product_targets([(pauli, q0), (pauli, q1)])
            tag = f"R_PAULI(theta={alpha}*pi)"
            name = "SPP"
            arg = None
        elif name == "R_PAULI":
            alpha = _single_angle(name, arg)
            tag = f"R_PAULI(theta={alpha}*pi)"
            name = "SPP"
            arg = None

        self._stim_circ.append(name=name, targets=targets, arg=arg, tag=tag)  # type: ignore
    else:
        no_targets = isinstance(targets, (tuple, list)) and not targets
        if not no_targets or arg is not None or tag:
            raise ValueError(
                "Can't specify targets, arg or tag when appending a "
                f"{type(name).__name__}."
            )
        self._stim_circ.append(name=name)

def append_from_stim_program_text(self, stim_program_text: str) -> None:
    """Append operations described by a Stim format program into the circuit.

    Supports the same shorthand syntax as the constructor.
    """
    converted = shorthand_to_stim(stim_program_text)
    try:
        self._stim_circ.append_from_stim_program_text(converted)
    except ValueError as exc:
        raise enriched_stim_error(exc, converted) from None

def approx_equals(
    self,
    other: object,
    *,
    atol: float,
) -> bool:
    """Check if a circuit is approximately equal to another circuit.

    Two circuits are approximately equal if they are equal up to slight
    perturbations of instruction arguments such as probabilities. For example,
    `X_ERROR(0.100) 0` is approximately equal to `X_ERROR(0.099)` within an absolute
    tolerance of 0.002. All other details of the circuits (such as the ordering of
    instructions and targets) must be exactly the same.

    Args:
        other: The circuit, or other object, to compare to this one.
        atol: The absolute error tolerance. The maximum amount each probability may
            have been perturbed by.

    Returns:
        True if the given object is a circuit approximately equal up to the
        receiving circuit up to the given tolerance, otherwise False.

    """
    if isinstance(other, Circuit):
        return self._stim_circ.approx_equals(other._stim_circ, atol=atol)
    elif isinstance(other, stim.Circuit):
        return self._stim_circ.approx_equals(other, atol=atol)
    else:
        return False

def compile_detector_sampler(
    self,
    *,
    strategy: SamplingStrategy = "active_statevector",
    seed: int | None = None,
) -> CompiledDetectorSampler:
    """Compile circuit into a detector sampler.

    Connected components whose single output is deterministically given by
    one f-variable, or is a constant, are handled via a fast direct path (no
    compilation or autoregressive sampling).  Remaining components go
    through the full compilation pipeline.

    Args:
        strategy: "active_statevector" (the default) to simulate each
            non-direct component on a dense state vector over its active
            qubits, or a stabilizer rank decomposition strategy ("cat5",
            "bss", "cutting"). "active_statevector" samples on the CPU, on
            ``numba.get_num_threads()`` threads. The stabilizer rank
            strategies are provisional.
        seed: Random seed for the sampler. If None, a random seed is drawn. A seed
            reproduces its samples only with the same versions of Tsim and its
            dependencies (such as NumPy and JAX) and the same backend (CPU or GPU).
            With "active_statevector", and under any strategy for a circuit without
            non-direct components, the samples of a seed depend on neither the batch
            size nor the thread count. With a stabilizer-rank strategy they also
            need the same explicit ``batch_size`` and the same reference sample
            settings, since the default batch size depends on the free memory.

    Returns:
        A CompiledDetectorSampler that can be used to sample detectors and observables.

    """
    from tsim.sampler import CompiledDetectorSampler

    return CompiledDetectorSampler(self, seed=seed, strategy=strategy)

def compile_m2d_converter(
    self,
    *,
    skip_reference_sample: bool = False,
) -> stim.CompiledMeasurementsToDetectionEventsConverter:
    """Create a measurement-to-detection-event converter for the given circuit.

    The converter can efficiently compute detection events and observable flips
    from raw measurement data.

    The converter uses a noiseless reference sample, collected from the circuit
    using Stim's Tableau simulator during initialization of the converter, as a
    baseline for determining what the expected value of a detector is.

    Note that the expected behavior of gauge detectors (detectors that are not
    actually deterministic under noiseless execution) can vary depending on the
    reference sample. Stim mitigates this by always generating the same reference
    sample for a given circuit.

    Args:
        skip_reference_sample: Defaults to False. When set to True, the reference
            sample used by the converter is initialized to all-zeroes instead of
            being collected from the circuit. This should only be used if it's known
            that the all-zeroes sample is actually a possible result from the
            circuit (under noiseless execution).

    Returns:
        An initialized stim.CompiledMeasurementsToDetectionEventsConverter.

    """
    return self._stim_circ.compile_m2d_converter(
        skip_reference_sample=skip_reference_sample
    )

def compile_sampler(
    self,
    *,
    strategy: SamplingStrategy = "active_statevector",
    seed: int | None = None,
) -> CompiledMeasurementSampler:
    """Compile circuit into a measurement sampler.

    Args:
        strategy: "active_statevector" (the default) to simulate each
            non-direct component on a dense state vector over its active
            qubits, or a stabilizer rank decomposition strategy ("cat5",
            "bss", "cutting"). "active_statevector" samples on the CPU, on
            ``numba.get_num_threads()`` threads. The stabilizer rank
            strategies are provisional.
        seed: Random seed for the sampler. If None, a random seed is drawn. A seed
            reproduces its samples only with the same versions of Tsim and its
            dependencies (such as NumPy and JAX) and the same backend (CPU or GPU).
            With "active_statevector", and under any strategy for a circuit without
            non-direct components, the samples of a seed depend on neither the batch
            size nor the thread count. With a stabilizer-rank strategy they also
            need the same explicit ``batch_size``, since the default batch size
            depends on the free memory.

    Returns:
        A CompiledMeasurementSampler that can be used to sample measurements.

    """
    from tsim.sampler import CompiledMeasurementSampler

    return CompiledMeasurementSampler(self, seed=seed, strategy=strategy)

def copy(self) -> Circuit:
    """Create a copy of this circuit."""
    return Circuit.from_stim_program(self._stim_circ.copy())

def detector_error_model(
    self,
    *,
    decompose_errors: bool = False,
    flatten_loops: bool = False,
    allow_gauge_detectors: bool = False,
    approximate_disjoint_errors: bool | float = False,
    ignore_decomposition_failures: bool = False,
    block_decomposition_from_introducing_remnant_edges: bool = False,
) -> stim.DetectorErrorModel:
    """Return a stim.DetectorErrorModel describing the error processes in the circuit.

    Unlike the stim.Circuit.detector_error_model() method, this method allows for non-deterministic observables
    when `allow_gauge_detectors` is set to true.

    Warning:
        By default (`decompose_errors=False`) the model is not decomposed. Matching decoders such as
        PyMatching build their graph only from error mechanisms that flip at most two detectors, and silently
        ignore the rest, which can raise the logical error rate substantially. Set `decompose_errors=True`
        when the model is meant for a matching decoder.

    Args:
        decompose_errors: Defaults to false. When set to true, the error analysis attempts to decompose the
            components of composite error mechanisms (such as depolarization errors) into simpler errors, and
            suggest this decomposition via `stim.target_separator()` between the components. For example, in an
            XZ surface code, single qubit depolarization has a Y error term which can be decomposed into simpler
            X and Z error terms. Decomposition fails (causing this method to throw) if it's not possible to
            decompose large errors into simple errors that affect at most two detectors.

            Decomposition keeps the logical observables as observables, as Stim does, so it requires them
            to be deterministic: Stim raises a ValueError otherwise.
        flatten_loops: Defaults to false. When set to true, the output will not contain any `repeat` blocks.
            When set to false, the error analysis watches for loops in the circuit reaching a periodic steady
            state with respect to the detectors being introduced, the error mechanisms that affect them, and the
            locations of the logical observables. When it identifies such a steady state, it outputs a repeat
            block. This is massively more efficient than flattening for circuits that contain loops, but creates
            a more complex output.

            Irrelevant unless allow_gauge_detectors=False.
        allow_gauge_detectors: Defaults to false. When set to false, the error analysis verifies that detectors
            in the circuit are actually deterministic under noiseless execution of the circuit.

            Note that, unlike in Stim, logical observables are also allowed to be non-deterministic.
        approximate_disjoint_errors: Defaults to false. When set to false, composite error mechanisms with
            disjoint components (such as `PAULI_CHANNEL_1(0.1, 0.2, 0.0)`) can cause the error analysis to throw
            exceptions (because detector error models can only contain independent error mechanisms). When set
            to true, the probabilities of the disjoint cases are instead assumed to be independent
            probabilities. For example, a ``PAULI_CHANNEL_1(0.1, 0.2, 0.0)` becomes equivalent to an
            `X_ERROR(0.1)` followed by a `Z_ERROR(0.2)`. This assumption is an approximation, but it is a good
            approximation for small probabilities.

            This argument can also be set to a probability between 0 and 1, setting a threshold below which the
            approximation is acceptable. Any error mechanisms that have a component probability above the
            threshold will cause an exception to be thrown.
        ignore_decomposition_failures: Defaults to False.
            When this is set to True, circuit errors that fail to decompose into graphlike
            detector error model errors no longer cause the conversion process to abort.
            Instead, the undecomposed error is inserted into the output. Whatever tool
            the detector error model is then given to is responsible for dealing with the
            undecomposed errors (e.g. a tool may choose to simply ignore them).

            Irrelevant unless decompose_errors=True.
        block_decomposition_from_introducing_remnant_edges: Defaults to False.
            Requires that both A B and C D be present elsewhere in the detector error model
            in order to decompose A B C D into A B ^ C D. Normally, only one of A B or C D
            needs to appear to allow this decomposition.

            Remnant edges can be a useful feature for ensuring decomposition succeeds, but
            they can also reduce the effective code distance by giving the decoder single
            edges that actually represent multiple errors in the circuit (resulting in the
            decoder making misinformed choices when decoding).

            Irrelevant unless decompose_errors=True.

    """
    return get_detector_error_model(
        self._stim_circ,
        allow_non_deterministic_observables=True,
        decompose_errors=decompose_errors,
        flatten_loops=flatten_loops,
        allow_gauge_detectors=allow_gauge_detectors,
        approximate_disjoint_errors=approximate_disjoint_errors,
        ignore_decomposition_failures=ignore_decomposition_failures,
        block_decomposition_from_introducing_remnant_edges=block_decomposition_from_introducing_remnant_edges,
    )

def diagram(
    self,
    type: Literal[
        "zx",
        "zx-dets",
        "zx-meas",
        "timeline-svg",
        "timeslice-svg",
        "timeline-text",
    ] = "timeline-svg",
    tick: int | range | None = None,
    filter_coords: Iterable[Iterable[float] | stim.DemTarget] = ((),),
    rows: int | None = None,
    height: float | None = None,
    width: float | None = None,
    zoomable: bool = True,
    **kwargs: Any,
) -> Any:
    """Return a diagram of the circuit, from a variety of options.

    Args:
        type: The type of diagram. Available types are:
            "zx": A zxparam D3 drawing of the circuit's quantum/classical
                ZX graph.
            "zx-dets": A zxparam D3 drawing of the reduced ZX graph that is
                used to compute probabilities of detectors and observables.
            "zx-meas": A zxparam D3 drawing of the reduced ZX graph that is
                used to compute probabilities of measurements.
            "timeline-svg": An SVG image of the operations applied by
                the circuit over time. Includes annotations showing the
                measurement record index that each measurement writes
                to, and the measurements used by detectors.
            "timeslice-svg": An SVG image of the operations applied
                between two TICK instructions in the circuit, with the
                operations laid out in 2d.
            "timeline-text": An ASCII text diagram of the operations
                applied by the circuit over time, with Tsim's custom
                gates rendered under their logical names rather than
                the Clifford placeholders used to store them.
        tick: Required for time slice diagrams. Specifies
            which TICK instruction, or range of TICK instructions, to
            slice at. Note that the first TICK instruction in the
            circuit corresponds tick=1. The value tick=0 refers to the
            very start of the circuit.

            Passing `range(A, B)` for a detector slice will show the
            slices for ticks A through B including A but excluding B.

            Passing `range(A, B)` for a time slice will show the
            operations between tick A and tick B.
        rows: In diagrams that have multiple separate pieces, such as timeslice
            diagrams and detslice diagrams, this controls how many rows of
            pieces there will be. If not specified, a number of rows that creates
            a roughly square layout will be chosen.
        filter_coords: A list of things to include in the diagram. Different
            effects depending on the diagram.

            For detslice diagrams, the filter defaults to showing all detectors
            and no observables. When specified, each list entry can be a collection
            of floats (detectors whose coordinates start with the same numbers will
            be included), a stim.DemTarget (specifying a detector or observable
            to include), a string like "D5" or "L0" specifying a detector or
            observable to include.
        height: Optional height for the rendered diagram in pixels. Only applied
            to timeline-svg and timeslice-svg diagram types. For
            timeline-svg, when both height and width are None, the height is
            automatically determined based on the number of qubits. When only
            one dimension is given, the other is computed from the SVG aspect
            ratio.
        width: Optional width for the rendered diagram in pixels. Only applied
            to timeline-svg and timeslice-svg diagram types.
        zoomable: If True (default), wraps SVG diagrams in an interactive
            container with pan and Ctrl/Cmd+wheel zoom. Only applies to
            timeline-svg and timeslice-svg diagram types.
        **kwargs: Additional keyword arguments passed to the underlying diagram renderer.

    Returns:
        An object whose `__str__` method returns the diagram, so that
        writing the diagram to a file works correctly. The returned
        object may also define methods such as `_repr_html_`, so that
        ipython notebooks recognize it can be shown using a specialized
        viewer instead of as raw text.

    """
    if type in _REMOVED_DIAGRAM_TYPES:
        replacement = _REMOVED_DIAGRAM_TYPES[type]
        raise ValueError(
            f"Diagram type {type!r} was removed in Tsim 1.0; use {replacement!r}."
        )
    if type in [
        "timeline-svg",
        "timeslice-svg",
    ]:
        if height is None and width is None and type == "timeline-svg":
            height = min(30 * self.num_qubits + 50, 700)
        return render_svg(
            self._stim_circ,
            type,
            tick=tick,
            filter_coords=filter_coords,
            rows=rows,
            width=width,
            height=height,
            zoomable=zoomable,
        )
    elif type == "zx":
        builder = parse_stim_circuit(self._stim_circ)
        g = builder.build(closed=False, outputs="detectors")
        return draw_zx(g, builder.num_error_bits, kwargs)
    elif type in ("zx-dets", "zx-meas"):
        builder = parse_stim_circuit(self._stim_circ)
        outputs = "detectors" if type == "zx-dets" else "records"
        g = builder.build(closed=True, outputs=outputs)
        zx.full_reduce(g)
        g, _ = transform_error_basis(g, builder.num_error_bits)
        g.to_rg()
        return draw_zx(g, builder.num_error_bits, kwargs, layout="outputs")
    elif type == "timeline-text":
        from stim_timeline_text import render_timeline_text

        return render_timeline_text(str(self._stim_circ))
    else:
        return self._stim_circ.diagram(type=type, **kwargs)  # pragma: no cover

def flattened(self) -> Circuit:
    """Return a copy of the circuit with all repeat blocks expanded."""
    return Circuit.from_stim_program(self._stim_circ.flattened())

@classmethod
def from_file(cls, filename: str) -> Circuit:
    """Create a Circuit from a file.

    Args:
        filename: The filename to read the circuit from.

    Returns:
        A new Circuit instance.

    """
    with open(filename, encoding="utf-8") as f:
        stim_program_text = f.read()
    converted = shorthand_to_stim(stim_program_text)
    try:
        stim_circ = stim.Circuit(converted)
    except ValueError as exc:
        raise enriched_stim_error(exc, converted) from None
    return cls.from_stim_program(stim_circ)

@classmethod
def from_stim_program(cls, stim_circuit: stim.Circuit) -> Circuit:
    """Create a Circuit from a stim.Circuit object.

    Args:
        stim_circuit: The Stim circuit to wrap.

    Returns:
        A new Circuit instance.

    """
    c = cls.__new__(cls)
    c._stim_circ = stim_circuit.copy()
    return c

def get_graph(self) -> Graph:
    """Construct the circuit's quantum/classical ZX graph, with qubit ports.

    Error parameters have the error index as their ID. Each detector and
    observable is a classical XOR spider with its own classical output
    boundary; their ports follow the qubit outputs (detectors, then
    observables), so the graph's tensor is the circuit's channel together
    with the detector and observable bits. ``Circuit.to_tensor`` returns the
    channel alone.
    """
    builder = parse_stim_circuit(self._stim_circ)
    return builder.build(closed=False, outputs="detectors")

def get_sampling_graph(self, sample_detectors: bool = False) -> Graph:
    """Get a ZX graph that can be used to compute probabilities.

    The graph is not doubled: qubit wires are quantum and measurement records
    are classical spiders. It is constructed as follows:

    1. Wire starts become ``|0⟩`` and wire ends are discarded.
    2. Add outputs, which are classical boundaries:
    (a) When sampling measurements (i.e. `sample_detectors` is False),
        add an output for each measurement. Detectors and observables are
        removed since they are ignored when sampling measurements.
    (b) When sampling detectors and observables (i.e. `sample_detectors` is True),
        add an output for each detector, then for each observable.

    Error parameters have the error index as their ID, so the graph's
    ``to_tensor`` needs a bit for every error index in its bindings (unbound
    parameters raise); its tensor is then the joint distribution of the
    outputs.

    Args:
        sample_detectors: If True, sample detectors and observables instead of
            measurements.

    Returns:
        A ZX graph for sampling.

    """
    builder = parse_stim_circuit(self._stim_circ)
    return builder.build(
        closed=True, outputs="detectors" if sample_detectors else "records"
    )

def inverse(self) -> Circuit:
    """Return the inverse of the circuit."""

    def fix_tags(circuit: stim.Circuit) -> stim.Circuit:
        # Stim only inverts Clifford gates (and S[T] / S_DAG[T]).
        # Non-Clifford rotations stored as I[tag] need their parameters
        # negated (and reordered for U3).
        result = stim.Circuit()
        for instr in circuit:
            if isinstance(instr, stim.CircuitRepeatBlock):
                fixed = fix_tags(instr.body_copy())
                result.append(
                    stim.CircuitRepeatBlock(
                        instr.repeat_count, fixed, tag=instr.tag
                    )
                )
                continue

            name = instr.name
            tag = instr.tag
            targets = [t.value for t in instr.targets_copy()]
            args = instr.gate_args_copy()

            if name == "I" and tag:
                parsed = parse_parametric_tag(instr)
                if parsed is not None:
                    gate_name, params = parsed
                    if gate_name == "U3":
                        # U3(θ, φ, λ)⁻¹ = U3(-θ, -λ, -φ)
                        theta = float(-params["theta"])
                        phi = float(-params["lambda"])
                        lam = float(-params["phi"])
                        new_tag = (
                            f"U3(theta={theta}*pi, phi={phi}*pi, lambda={lam}*pi)"
                        )
                    else:
                        theta = float(-params["theta"])
                        new_tag = f"{gate_name}(theta={theta}*pi)"
                    result.append("I", targets, args, tag=new_tag)
                    continue

            result.append(instr)
        return result

    inv_stim = fix_tags(self._stim_circ.inverse())
    return Circuit.from_stim_program(inv_stim)

def pop(
    self,
    index: int = -1,
) -> stim.CircuitInstruction | stim.CircuitRepeatBlock:
    """Pops an operation from the end of the circuit, or at the given index.

    Args:
        index: Defaults to -1 (end of circuit). The index to pop from.

    Returns:
        The popped instruction or repeat block.

    Raises:
        IndexError: The given index is outside the bounds of the circuit.

    """
    return self._stim_circ.pop(index)

def tcount(self) -> int:
    """Count the spiders whose angle is not a multiple of π/2."""
    builder = parse_stim_circuit(self._stim_circ)
    return zx.tcount(builder.build(closed=False, outputs="none"))

def to_tensor(self, bindings: Mapping[int, int] | None = None) -> np.ndarray:
    """Return the circuit's doubled tensor (its channel, U ⊗ Ū for unitaries).

    Axes follow zxparam's ``Graph.to_tensor``: outputs then inputs, by qubit,
    each with a copy and a conjugate axis. Only qubits that some instruction
    targets get axes, in increasing index order; qubits that no instruction
    names are left out, so ``H 1`` gives a one-qubit tensor (add ``I q`` to
    keep qubit ``q``). Error bits default to 0 (the noiseless circuit);
    ``bindings`` maps error indices to bits and raises ``ValueError`` for any
    other key. Detector and observable annotations are left out. Needs
    ``zxparam[quimb]``.
    """
    builder = parse_stim_circuit(self._stim_circ)
    values: dict[int, Bit] = {j: 0 for j in range(builder.num_error_bits)}
    for j, bit in (bindings or {}).items():
        if j not in values:
            raise ValueError(
                f"{j!r} is not an error index of this circuit, which has "
                f"{builder.num_error_bits} error bit(s)"
            )
        values[j] = 1 if bit else 0
    return builder.build(closed=False, outputs="none").to_tensor(values)

def without_annotations(self) -> Circuit:
    """Return a copy of the circuit with all detector and observable annotations removed."""

    def strip(circuit: stim.Circuit) -> stim.Circuit:
        result = stim.Circuit()
        for instr in circuit:
            if isinstance(instr, stim.CircuitRepeatBlock):
                stripped = strip(instr.body_copy())
                result.append(
                    stim.CircuitRepeatBlock(
                        instr.repeat_count, stripped, tag=instr.tag
                    )
                )
                continue
            if instr.name in ["OBSERVABLE_INCLUDE", "DETECTOR"]:
                continue
            result.append(instr)
        return result

    return Circuit.from_stim_program(strip(self._stim_circ))

def without_noise(self) -> Circuit:
    """Return a copy of the circuit with all noise removed."""
    return Circuit.from_stim_program(self._stim_circ.without_noise())

def __repr__(self) -> str:
    """Return a string representation with compilation statistics."""
    n_direct = len(self._program.direct_f_indices)

    c_graphs = []
    c_params = []
    c_a_terms = []
    c_b_terms = []
    c_c_terms = []
    c_d_terms = []
    c_e_terms = []
    total_memory_bytes = 0
    num_outputs = []
    statevector_widths: list[int] = []
    statevector_actions = 0

    for component in self._program.components:
        if isinstance(component, StatevectorComponent):
            statevector_widths.append(component.width)
            statevector_actions += component.num_actions
            num_outputs.append(len(component.output_indices))
            total_memory_bytes += _nbytes(component)
            continue
        for circuit in component.compiled_scalar_graphs:
            num_outputs.append(len(component.output_indices))
            c_graphs.append(circuit.num_graphs)
            c_params.append(circuit.n_params)
            c_a_terms.append(circuit.node_phases.phases.size)
            c_b_terms.append(circuit.phase_terms.coeffs.size)
            c_c_terms.append(
                circuit.pi_products.psi_params.shape[0]
                * circuit.pi_products.psi_params.shape[1]
            )
            c_d_terms.append(
                circuit.phase_pairs.alpha.size + circuit.phase_pairs.beta.size
            )
            c_e_terms.append(
                circuit.float_terms.table.shape[0]
                * circuit.float_terms.table.shape[1]
            )

            total_memory_bytes += _nbytes(circuit)

    def _format_bytes(n: int) -> str:
        if n < 1024:
            return f"{n} B"
        if n < 1024**2:
            return f"{n / 1024:.1f} kB"
        return f"{n / (1024**2):.1f} MB"

    total_memory_str = _format_bytes(total_memory_bytes)
    error_channel_bits = sum(
        channel.num_bits for channel in self._channel_sampler.channels
    )

    # NOTE: only the statistics of the backends in use are shown.
    parts = [f"{n_direct} direct"]
    if statevector_widths:
        parts.append(
            f"{len(statevector_widths)} statevector components "
            f"(width ≤ {max(statevector_widths)}, "
            f"{statevector_actions} actions)"
        )
    if c_graphs:
        parts.append(f"{sum(c_graphs)} graphs")
    parts += [
        f"{error_channel_bits} error channel bits",
        f"{max(num_outputs, default=0)} outputs for largest cc",
    ]
    if c_graphs:
        parts += [
            f"≤ {max(c_params)} parameters",
            f"{sum(c_a_terms)} A terms",
            f"{sum(c_b_terms)} B terms",
            f"{sum(c_c_terms)} C terms",
            f"{sum(c_d_terms)} D terms",
            f"{sum(c_e_terms)} E terms",
        ]
    parts.append(total_memory_str)
    return f"{type(self).__name__}({', '.join(parts)})"

def sample(
    self,
    shots: int,
    *,
    batch_size: int | None = None,
    bit_packed: bool = False,
) -> np.ndarray:
    """Sample measurement outcomes from the circuit.

    Args:
        shots: The number of times to sample every measurement in the circuit.
        batch_size: The number of samples to process at once. Defaults to None,
            which chooses it from the available memory. With
            ``strategy="active_statevector"`` it bounds the shots a thread
            holds and does not change the samples.
            With a stabilizer-rank strategy on a GPU, setting this explicitly
            can help fully utilize VRAM; it changes the samples of a seed.
        bit_packed: Defaults to false. When set, results are bit-packed. The
            packed rows may be a strided view of a wider array.

    Returns:
        A boolean array of shape ``(shots, num_measurements)``, or with
        ``bit_packed`` a uint8 array of shape
        ``(shots, ceil(num_measurements / 8))`` in little-endian bit order.

    """
    columns = [np.arange(self._program.num_outputs)]
    return self._sample_outputs(shots, batch_size, columns, bit_packed=bit_packed)[
        0
    ]

def __repr__(self) -> str:
    """Return a string representation with compilation statistics."""
    n_direct = len(self._program.direct_f_indices)

    c_graphs = []
    c_params = []
    c_a_terms = []
    c_b_terms = []
    c_c_terms = []
    c_d_terms = []
    c_e_terms = []
    total_memory_bytes = 0
    num_outputs = []
    statevector_widths: list[int] = []
    statevector_actions = 0

    for component in self._program.components:
        if isinstance(component, StatevectorComponent):
            statevector_widths.append(component.width)
            statevector_actions += component.num_actions
            num_outputs.append(len(component.output_indices))
            total_memory_bytes += _nbytes(component)
            continue
        for circuit in component.compiled_scalar_graphs:
            num_outputs.append(len(component.output_indices))
            c_graphs.append(circuit.num_graphs)
            c_params.append(circuit.n_params)
            c_a_terms.append(circuit.node_phases.phases.size)
            c_b_terms.append(circuit.phase_terms.coeffs.size)
            c_c_terms.append(
                circuit.pi_products.psi_params.shape[0]
                * circuit.pi_products.psi_params.shape[1]
            )
            c_d_terms.append(
                circuit.phase_pairs.alpha.size + circuit.phase_pairs.beta.size
            )
            c_e_terms.append(
                circuit.float_terms.table.shape[0]
                * circuit.float_terms.table.shape[1]
            )

            total_memory_bytes += _nbytes(circuit)

    def _format_bytes(n: int) -> str:
        if n < 1024:
            return f"{n} B"
        if n < 1024**2:
            return f"{n / 1024:.1f} kB"
        return f"{n / (1024**2):.1f} MB"

    total_memory_str = _format_bytes(total_memory_bytes)
    error_channel_bits = sum(
        channel.num_bits for channel in self._channel_sampler.channels
    )

    # NOTE: only the statistics of the backends in use are shown.
    parts = [f"{n_direct} direct"]
    if statevector_widths:
        parts.append(
            f"{len(statevector_widths)} statevector components "
            f"(width ≤ {max(statevector_widths)}, "
            f"{statevector_actions} actions)"
        )
    if c_graphs:
        parts.append(f"{sum(c_graphs)} graphs")
    parts += [
        f"{error_channel_bits} error channel bits",
        f"{max(num_outputs, default=0)} outputs for largest cc",
    ]
    if c_graphs:
        parts += [
            f"≤ {max(c_params)} parameters",
            f"{sum(c_a_terms)} A terms",
            f"{sum(c_b_terms)} B terms",
            f"{sum(c_c_terms)} C terms",
            f"{sum(c_d_terms)} D terms",
            f"{sum(c_e_terms)} E terms",
        ]
    parts.append(total_memory_str)
    return f"{type(self).__name__}({', '.join(parts)})"