Improving Circuit API (#587)

This PR addresses #580. The PR comprises three blocks:

## Block 1: Introduction of ancilla qubits

Concerns `graphix.transpiler.py` only.

**Now it's possible to distinguish between input and ancilla qubits in circuits.**

- Two new attributes are added to the `Circuit` class:
  - `ancillas: int` to indicate the number of ancilla qubits. Ancilla qubits are indexed from `range(width, width + ancillas - 1)`, where `width` is the number of input qubits (existing attribute).
  - `ancilla_state: State` to indicate the state of the ancilla qubits.

- Supported operations on circuits with ancillas:
  - Simulation: always
  - Transpilation to pattern or causal flow: only if `ancilla_state` is a `BasicState`:
    - If `ancilla_state` is `BasicState.PLUS`, ancilla qubits are represented as non-input nodes in the open graph.
    - Any other `BasicState` is transpiled into `BasicState.PLUS` by prepending the appropriate gates to the circuit (via `Circuit.transpile_ancilla_state`). This is unavoidable because transpilation is carried out by first constructing an open graph with causal flow, and non-input nodes in `OpenGraph` always represent `BasicState.PLUS` qubits, even if Graphix supports `N` commands with an arbitrary state.

- QASM 3 export: only if `ancilla_state` is a `BasicState`. Same mechanism as for transpilation but transforming to state |0>.

- Note: this addition is a first step towards implementing circuit compilation of PDDAGs representing isometries.

## Block 2: Introduction of conditional instructions

Concerns `graphix.instruction.py` and `graphix.transpiler.py`.

**Now it's possible to represent conditional instructions in circuits.**

- A new instruction `CONDINSTR` is added. This instruction bundles a sequence of instructions (possibly incuding other `CONDINSTR`) and a qubit domain (`set[int]`). The instruction sequence is applied when the XOR of the measurement outcomes of the qubits in ``domain`` evaluates to ``1``.

- Two side modifications:

  - #### `InstructionVisitor`
     - `InstructionVisitor` now has an additional method `visit_domain`. The method `CONDINSTR.visit` visits the instruction's domain **and** all the instructions in the instruction sequence.
     - Introduced a new `_InstructionValidatorVisitor(InstructionVisitor)` class. This visitor reimplements the method `visit_qubit` and `visit_domain` so that calling `visit` for a given instruction checks the qubit validity. As a result:
        1) Valid-qubit sanity checks are factorized into a single function. 
        
        2) There is a generic way to check the validity of any `InstructionKind`, without knowing which specific instruction it is. This allows to verify the validity of conditional instructions containing a sequence of other instructions.

    - Checking that multi-qubit gates don't act on repeated qubits is delegated to the method `visit` of the corresponding instructions instead of the `Circuit` methods.

  - #### `graphix.utils.check_kind`
    - The function `graphix.utils.check_kind` has been slightly modified to fix an error due to the self-reference in the definition of `CONDINSTR`. This modification is an LLM suggestion, it's a bit obscure.

- Supported operations on circuits with conditional instructions:
  - Simulation: always.
    - Simulation is **very inefficient**: all qubits are instantianted at the beginning.
    - Exisiting simulation logic is encapsulated in a new function `simulate_instructions` that is called recursively for `CONDINSTR`.
    - Changes in simulation are minimal to support testing conditional instructions and keeping the PR as small as possible. In a future PR we'll address the following:
      - Simulation logic should be moved to `simulator` module.
      - Currently we are rewriting some code exisiting in `MeasureMethod`. 
      - How to handle classical output results ?
        - Now keeping `classical_outputs` to achieve a minimal PR.
        - Ideally we should find a common interface for pattern and circuit simulation.
  
  - Transpilation to pattern or causal flow: always.
    - Required logic is encapsulated in `Circuit.transpile_condinstr` that is called from exisiting transpilation methods when there is any conditional instruction in the circuit.
    - Conditional instructions are replaced by controlled instructions, using measurements of their domain qubits in the $Z$ basis as control conditions. Measurements are moved to the end of the circuit. When the domain of the conditional instruction comprises various qubits (whose measurement outputs are xored), they are combined by chaining CNOT gates).
  - QASM 3 export: always (implemented by @thierry-martinez).

## Block 3: Introduction of a `Pattern.to_circuit` method.

Concerns `graphix.pattern.py`

- This method requires the changes in block 1 and block 2.
- Logic is similar to existing `Pattern.to_qasm3`, with two differences:
  - Swap gates are added at the end of circuit to ensure that active qubits are in the same order as output nodes in the pattern. This guarantees that a pattern and its circuit produce the same state up to a phase.
  - Qubits are labelled with consecutive integers starting from 0. In the qasm export, we label qubits with the same node labels.
  - `Pattern.to_qasm3` should be refactored to be a wrapper over `Pattern.to_circuit().to_qasm3`

---------

Co-authored-by: thierry-martinez <thierry.martinez@inria.fr>

Author: matulni

.github/qasm-parser-requirements.txt

@@ -1 +1,2 @@
-graphix-qasm-parser @ git+https://github.com/TeamGraphix/graphix-qasm-parser@refs/pull/15/head
+#graphix-qasm-parser @ git+https://github.com/TeamGraphix/graphix-qasm-parser@refs/pull/17/head
+graphix-qasm-parser @ git+https://github.com/matulni/graphix-qasm-parser@new-circuit-api

CHANGELOG.md

@@ -17,18 +17,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Support for Python 3.15
   - Drop support for Python 3.10 (end-of-life: 2026-10-01)
 
+- #587:
+  - Added ancilla qubits to `Circuit` API (new attributes `ancillas` and `ancilla_state`).
+  - Added conditional instructions (`CONDINSTR`). Added simulation, transpilation and qasm-conversion capabilities.
+  - Added `Pattern.to_circuit` method to convert a `Pattern` into a `Circuit` with ancillas and classical control.
+
 ### Fixed
 
 - #591: `FixedBranchSelector` now passes its RNG parameter to its `default` branch selector.
 
-- #595: `RZZ` gates are no longer incorrectly exported as `crz`; transpilation to `CNOT`-`RZ`-`CNOT` is provided.
-
 - #596, #597: Pattern's `n_node` property updated after Pauli removal.
 
-## Changed
+- #595: Fixed the export of circuit measurements and `RZZ` gates to OpenQASM. `RZZ` gates are no longer incorrectly exported as `crz`; transpilation to `CNOT`-`RZ`-`CNOT` is provided.
+
+- #592:
+  - Added the following gates specified in the OpenQASM 3.0 specification: SDG, T, TDG, SX, SXDG, CY, P, U, CP, CRX, CRY, CRZ, CU, CSWAP, and GPHASE.
+  - Subsumed `Circuit.transpile_measurements_to_z_axis`, `Circuit.transpile_j_to_rzh` and `Circuit.transpile_rzz` by `Circuit.transpile_to_qasm_gates`
 
-- #601: New documentation / tutorial
+### Changed
+
+- #587;
+  - Factorized instruction-validity checks in method `Circuit.add` via an instruction visitor.
+  - Instruction methods of the `Circuit` class now return `self` allowing method chaining.
 
+  
 ## [0.4] - 2026-08-18
 
 ### Added

COMPATIBILITY.md

@@ -2,6 +2,11 @@
 
 Graphix does not guarantee backwards compatibility between 0.x version releases. Here we list API changes which may break existing code using Graphix. 
 
+## Unreleased
+
+- #592:
+  - `Circuit.transpile_measurements_to_z_axis`, `Circuit.transpile_j_to_rzh` and `Circuit.transpile_rzz` are subsumed by `Circuit.transpile_to_qasm_gates`
+
 ## [0.4] - 2026-08-18
 
 - #484: J & CZ transpilation.

graphix/instruction.py

@@ -70,6 +70,7 @@ class InstructionKind(Enum):
     CU = enum.auto()
     CSWAP = enum.auto()
     GPHASE = enum.auto()
+    CONDINSTR = enum.auto()
 
 
 class _KindChecker:
@@ -106,6 +107,10 @@ def visit_axis(self, axis: Axis) -> Axis:
         """Rewrite an axis."""
         return axis
 
+    def visit_domain(self, domain: set[int]) -> set[int]:
+        """Rewrite a domain of a conditional instruction."""
+        return domain
+
 
 class BaseInstruction(ABC, DataclassReprMixin):
     """Base class for circuit instructions."""
@@ -171,6 +176,12 @@ def visit(self, visitor: InstructionVisitor, *, copy: bool = False) -> CCX:
         u, v = self.controls
         target = visitor.visit_qubit(self.target)
         controls = (visitor.visit_qubit(u), visitor.visit_qubit(v))
+        if controls[0] == controls[1]:
+            raise ValueError(f"Control qubits cannot be the same. Qubit index: {controls[0]}.")
+        for i, c in enumerate(controls):
+            if target == c:
+                raise ValueError(f"Target and control-{i} qubits cannot be the same. Qubit index: {target}.")
+
         if copy:
             return CCX(target, controls)
         self.target = target
@@ -218,6 +229,8 @@ class RZZ(_KindChecker, BaseInstruction):
     def visit(self, visitor: InstructionVisitor, *, copy: bool = False) -> RZZ:
         target = visitor.visit_qubit(self.target)
         control = visitor.visit_qubit(self.control)
+        if target == control:
+            raise ValueError(f"Target and control qubits cannot be the same. Qubit index: {target}.")
         angle = visitor.visit_angle(self.angle)
         if copy:
             return RZZ(target, control, angle)
@@ -238,6 +251,8 @@ class ControlledSingleTargetInstruction(BaseInstruction):
     def visit(self, visitor: InstructionVisitor, *, copy: bool = False) -> Self:
         target = visitor.visit_qubit(self.target)
         control = visitor.visit_qubit(self.control)
+        if target == control:
+            raise ValueError(f"Target and control qubits cannot be the same. Qubit index: {target}.")
         if copy:
             return type(self)(target, control)
         self.target = target
@@ -339,6 +354,8 @@ class CZ(_KindChecker, BaseInstruction):
     def visit(self, visitor: InstructionVisitor, *, copy: bool = False) -> CZ:
         u, v = self.targets
         targets = (visitor.visit_qubit(u), visitor.visit_qubit(v))
+        if targets[0] == targets[1]:
+            raise ValueError(f"Target qubits cannot be the same. Qubit index: {targets[0]}.")
         if copy:
             return CZ(targets)
         self.targets = targets
@@ -377,6 +394,8 @@ class SWAP(_KindChecker, BaseInstruction):
     def visit(self, visitor: InstructionVisitor, *, copy: bool = False) -> SWAP:
         u, v = self.targets
         targets = (visitor.visit_qubit(u), visitor.visit_qubit(v))
+        if targets[0] == targets[1]:
+            raise ValueError(f"Target qubits cannot be the same. Qubit index: {targets[0]}.")
         if copy:
             return SWAP(targets)
         self.targets = targets
@@ -836,6 +855,8 @@ def visit(self, visitor: InstructionVisitor, *, copy: bool = False) -> Self:
         target = visitor.visit_qubit(self.target)
         control = visitor.visit_qubit(self.control)
         angle = visitor.visit_angle(self.angle)
+        if target == control:
+            raise ValueError(f"Target and control qubits cannot be the same. Qubit index: {target}.")
         if copy:
             return type(self)(target, control, angle)
         self.target = target
@@ -1047,12 +1068,70 @@ def visit(self, visitor: InstructionVisitor, *, copy: bool = False) -> GPHASE:
         return self
 
 
+InstructionTypeWithoutM: TypeAlias = """(
+    I
+    | X
+    | Y
+    | Z
+    | H
+    | S
+    | SDG
+    | T
+    | TDG
+    | SX
+    | SXDG
+    | J
+    | P
+    | RX
+    | RY
+    | RZ
+    | U
+    | CJ
+    | CP
+    | CRX
+    | CRY
+    | CRZ
+    | CU
+    | CNOT
+    | CY
+    | CZ
+    | CCX
+    | RZZ
+    | SWAP
+    | CSWAP
+    | GPHASE
+    | CONDINSTR
+)"""
+
+
+@dataclass(repr=False)
+class CONDINSTR(_KindChecker, BaseInstruction):
+    """Base class for conditional circuit instructions.
+
+    Conditional measurements are not well defined since they would result in circuits with an indeterminate number of qubits. Therefore, the attribute ``instructions`` cannot contain instances of `Instruction.M`.
+    """
+
+    instructions: tuple[InstructionTypeWithoutM, ...]
+    domain: set[int] = field(default_factory=set)
+    kind: ClassVar[Literal[InstructionKind.CONDINSTR]] = field(default=InstructionKind.CONDINSTR, init=False)
+
+    @override
+    def visit(self, visitor: InstructionVisitor, *, copy: bool = False) -> Self:
+        instructions = tuple(instr.visit(visitor, copy=copy) for instr in self.instructions)
+        domain = visitor.visit_domain(self.domain)
+        if copy:
+            return type(self)(instructions, domain)
+        self.instructions = instructions
+        self.domain = domain
+        return self
+
+
 class Instruction:
     """Grouping of all instructions for namespace exposure.
 
     Notes
     -----
-    This class is not meant to be instantiated, but rather serves as a namespace for all instructions except RZZ.
+    This class is not meant to be instantiated, but rather serves as a namespace for all instructions.
     The type alias for "any command" is :data:`InstructionKind`.
     """
 
@@ -1088,43 +1167,25 @@ class Instruction:
     CSWAP: TypeAlias = CSWAP
     M: TypeAlias = M
     GPHASE: TypeAlias = GPHASE
+    CONDINSTR: TypeAlias = CONDINSTR
 
     def __init__(self) -> None:
         raise TypeError("Instruction is a namespace, not a class.")
 
 
 if TYPE_CHECKING:
-    InstructionType = (
-        I
-        | X
-        | Y
-        | Z
-        | H
-        | S
-        | SDG
-        | T
-        | TDG
-        | SX
-        | SXDG
-        | J
-        | P
-        | RX
-        | RY
-        | RZ
-        | U
-        | CJ
-        | CP
-        | CRX
-        | CRY
-        | CRZ
-        | CU
-        | CNOT
-        | CY
-        | CZ
-        | CCX
-        | RZZ
-        | SWAP
-        | CSWAP
-        | M
-        | GPHASE
+    InstructionTypeWithControl = (
+        Instruction.CNOT
+        | Instruction.CY
+        | Instruction.CZ
+        | Instruction.CJ
+        | Instruction.CCX
+        | Instruction.CRX
+        | Instruction.CRY
+        | Instruction.CRZ
+        | Instruction.CU
+        | Instruction.P
+        | Instruction.CP
+        | Instruction.CSWAP
     )
+    InstructionType = InstructionTypeWithoutM | M

graphix/opengraph.py

@@ -651,11 +651,11 @@ def to_circuit(
         >>> with warnings.catch_warnings():
         ...     warnings.filterwarnings("ignore", message="Open graph with non-inferred Pauli measurements.")
         ...     og.to_circuit()
-        Circuit(width=3, instr=[H(2), H(1), CNOT(2, 1), H(1), H(1), H(0), CNOT(2, 0), CNOT(1, 0), H(2), H(1), H(0)])
+        Circuit(width=3, instr=[H(2), H(1), CNOT(2, 1), H(1), H(1), H(0), CNOT(2, 0), CNOT(1, 0), H(2), H(1), H(0)], ancillas=0, ancilla_state=graphix.states.PlanarState(Plane.XY, 0))
         >>> # The default compilation passes do not exploit the lower depth of the Pauli flow
         >>> # compared the gflow.
         >>> og.infer_pauli_measurements().to_circuit()
-        Circuit(width=3, instr=[H(2), H(1), CNOT(2, 1), H(1), H(1), H(0), CNOT(2, 0), CNOT(1, 0), H(2), H(1), H(0)])
+        Circuit(width=3, instr=[H(2), H(1), CNOT(2, 1), H(1), H(1), H(0), CNOT(2, 0), CNOT(1, 0), H(2), H(1), H(0)], ancillas=0, ancilla_state=graphix.states.PlanarState(Plane.XY, 0))
         """
         return (
             self.to_pauliflow(stacklevel=stacklevel + 1)