coda-node 0.1.0__py3-none-any.whl

coda_node/server/ir.py

@@ -0,0 +1,182 @@
+"""Native-gate intermediate representation (IR) for quantum circuits.
+
+Jobs received from the Coda cloud carry a JSON-serialized circuit in
+this IR format.  The IR is target-aware: each hardware target (e.g.
+``cz``, ``cnot``, ``pcz``) defines a legal gate set, and
+the validators reject programs that use gates outside that set or
+reference qubits beyond the device's capacity.
+
+Schema (version ``"1.0"``)::
+
+    {
+      "version": "1.0",
+      "target": "cz",
+      "num_qubits": 5,
+      "gates": [{"gate": "rx", "qubits": [0], "params": [1.57]}],
+      "measurements": [0, 1],
+      "metadata": {
+        "source_hash": "abc123",
+        "compiled_at": "2026-01-01T00:00:00Z"
+      }
+    }
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+__all__ = [
+    "GATE_SPECS",
+    "LEGAL_GATES",
+    "GateOp",
+    "IRMetadata",
+    "NativeGate",
+    "NativeGateIR",
+]
+
+
+class NativeGate(StrEnum):
+    """Supported native gate identifiers across all hardware targets."""
+
+    RX = "rx"
+    RY = "ry"
+    RZ = "rz"
+    CZ = "cz"
+    ISWAP = "iswap"
+    CP = "cp"
+    ID = "id"
+    X90 = "x90"
+    Y_MINUS_90 = "y_minus_90"
+    VIRTUAL_Z = "virtual_z"
+    CNOT = "cnot"
+
+
+GATE_SPECS: dict[str, dict[str, int]] = {
+    "rx": {"qubits": 1, "params": 1},
+    "ry": {"qubits": 1, "params": 1},
+    "rz": {"qubits": 1, "params": 1},
+    "cz": {"qubits": 2, "params": 0},
+    "iswap": {"qubits": 2, "params": 0},
+    "cp": {"qubits": 2, "params": 1},
+    "id": {"qubits": 1, "params": 1},
+    "x90": {"qubits": 1, "params": 0},
+    "y_minus_90": {"qubits": 1, "params": 0},
+    "virtual_z": {"qubits": 1, "params": 1},
+    "cnot": {"qubits": 2, "params": 0},
+}
+
+LEGAL_GATES: dict[str, set[str]] = {
+    "cz": {"rx", "ry", "rz", "cz", "id"},
+    "iswap": {"rx", "ry", "rz", "iswap", "id"},
+    "pcz": {"rx", "ry", "rz", "cp", "id"},
+    "cnot": {
+        "rx",
+        "ry",
+        "rz",
+        "x90",
+        "y_minus_90",
+        "virtual_z",
+        "cnot",
+        "id",
+    },
+}
+
+
+class GateOp(BaseModel):
+    """A single gate operation: gate name, target qubits, and parameters."""
+
+    gate: NativeGate
+    qubits: list[int]
+    params: list[float] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def validate_gate_shape(self) -> GateOp:
+        """Ensure qubit and parameter counts match the gate specification."""
+        gate = self.gate.value
+        if gate in GATE_SPECS:
+            expected_qubits = GATE_SPECS[gate]["qubits"]
+            if len(self.qubits) != expected_qubits:
+                raise ValueError(
+                    f"Gate {gate} requires {expected_qubits} qubit(s), got {len(self.qubits)}"
+                )
+
+            expected_params = GATE_SPECS[gate]["params"]
+            if len(self.params) != expected_params:
+                raise ValueError(
+                    f"Gate {gate} requires {expected_params} param(s), got {len(self.params)}"
+                )
+        return self
+
+
+class IRMetadata(BaseModel):
+    """Provenance metadata attached to a compiled circuit."""
+
+    source_hash: str
+    compiled_at: str
+    compiler_version: str = "0.1.0"
+    optimization_level: int = Field(ge=0, le=3, default=2)
+
+
+class NativeGateIR(BaseModel):
+    """A fully validated native-gate circuit ready for execution.
+
+    Validation enforces that every gate is legal for the declared target,
+    qubit indices are within ``[0, num_qubits)``, and each gate has the
+    correct number of qubit operands and parameters.
+    """
+
+    version: Literal["1.0"] = "1.0"
+    target: str
+    num_qubits: int = Field(ge=1, le=50)
+    gates: list[GateOp]
+    measurements: list[int]
+    metadata: IRMetadata
+
+    @field_validator("target")
+    @classmethod
+    def validate_target(cls, value: str) -> str:
+        """Reject targets not present in :data:`LEGAL_GATES`."""
+        if value not in LEGAL_GATES:
+            raise ValueError(
+                f"Unknown target '{value}'. Valid: {list(LEGAL_GATES.keys())}"
+            )
+        return value
+
+    @model_validator(mode="after")
+    def validate_consistency(self) -> NativeGateIR:
+        """Validate gate legality and qubit indices against the target."""
+        legal = LEGAL_GATES[self.target]
+        for index, op in enumerate(self.gates):
+            if op.gate.value not in legal:
+                raise ValueError(
+                    f"Gate '{op.gate.value}' not legal for target '{self.target}' at index {index}"
+                )
+            for qubit in op.qubits:
+                if qubit < 0 or qubit >= self.num_qubits:
+                    raise ValueError(
+                        f"Qubit {qubit} out of range [0, {self.num_qubits}) at gate index {index}"
+                    )
+
+        for qubit in self.measurements:
+            if qubit < 0 or qubit >= self.num_qubits:
+                raise ValueError(
+                    f"Measurement qubit {qubit} out of range [0, {self.num_qubits})"
+                )
+        return self
+
+    @classmethod
+    def from_json(cls, json_str: str) -> NativeGateIR:
+        """Deserialize and validate a JSON-encoded IR program.
+
+        Raises:
+            pydantic.ValidationError: If the JSON is malformed or the
+                circuit violates gate-set or qubit-range constraints.
+        """
+        return cls.model_validate_json(json_str)
+
+    def to_json(self) -> str:
+        """Serialize the IR to a pretty-printed JSON string."""
+        return self.model_dump_json(indent=2)

coda_node/server/qasm.py

@@ -0,0 +1,377 @@
+"""OpenQASM 3.0 <-> NativeGateIR round-trip helpers.
+
+These helpers support a deliberately small OpenQASM subset so tests can
+round-trip circuits through text and keep validating that ``NativeGateIR``
+remains a valid, stable IR representation going forward. They are not meant
+to define a broader OpenQASM compatibility surface.
+
+Supports the ``cz`` and ``cnot`` IR targets for the OpenQASM round-trip subset.
+Only the QASM subset needed by these targets is handled; symbolic parameter
+expressions (for example ``pi/2``) are not supported, so callers must use
+numeric literals.
+
+Known limitation: the ``id`` gate carries a duration parameter in the IR
+(nanoseconds) that has no OpenQASM counterpart. ``ir_to_openqasm`` drops
+the duration, and ``openqasm_to_ir`` fills it with ``0.0``.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from datetime import UTC, datetime
+
+from coda_node.server.ir import GateOp, IRMetadata, NativeGate, NativeGateIR
+
+
+class QASMConversionError(Exception):
+    """Raised when an OpenQASM program cannot be converted."""
+
+
+_HALF_PI = math.pi / 2
+
+# ---------------------------------------------------------------------------
+# Regex patterns for the supported QASM subset
+# TODO: Replace regex parsing with a proper AST parser if the supported QASM
+# subset grows (e.g. multi-register circuits, barrier instructions, or new gates).
+# ---------------------------------------------------------------------------
+
+_HEADER_RE = re.compile(r"OPENQASM\s+[\d.]+\s*;")
+_INCLUDE_RE = re.compile(r'include\s+"[^"]+"\s*;')
+_QUBIT_DECL_RE = re.compile(r"qubit\[(\d+)]\s+\w+\s*;")
+_BIT_DECL_RE = re.compile(r"bit\[(\d+)]\s+\w+\s*;")
+_MEASURE_RE = re.compile(r"\w+\[(\d+)]\s*=\s*measure\s+\w+\[(\d+)]\s*;")
+_GATE_RE = re.compile(
+    r"(\w+)"
+    r"(?:\(([^)]*)\))?"
+    r"\s+"
+    r"((?:\w+\[\d+])(?:\s*,\s*\w+\[\d+])*)"
+    r"\s*;"
+)
+_QUBIT_REF_RE = re.compile(r"\w+\[(\d+)]")
+
+
+def _format_float(value: float) -> str:
+    """Format a numeric parameter for stable QASM output.
+
+    Args:
+        value: Numeric value to serialize.
+
+    Returns:
+        String form with enough precision for round-trip comparisons.
+    """
+    return f"{value:.15g}"
+
+
+# ---------------------------------------------------------------------------
+# OpenQASM → NativeGateIR
+# ---------------------------------------------------------------------------
+
+
+def openqasm_to_ir(
+    qasm: str,
+    *,
+    target: str,
+    metadata: IRMetadata | None = None,
+) -> NativeGateIR:
+    """Parse supported OpenQASM text into ``NativeGateIR``.
+
+    This parser exists primarily to support round-trip validation of the IR.
+    It accepts only the subset of OpenQASM needed to confirm that the current
+    ``NativeGateIR`` encoding can be serialized and reconstructed reliably.
+
+    Args:
+        qasm: OpenQASM 3.0 source text.
+        target: Native gate target to validate against.
+        metadata: Optional metadata to attach to the returned IR. When omitted,
+            placeholder metadata is generated.
+
+    Returns:
+        Parsed native-gate IR object.
+
+    Raises:
+        QASMConversionError: If the QASM text uses unsupported syntax, gates,
+            or targets, or if the resulting IR fails validation.
+    """
+    num_qubits: int | None = None
+    gates: list[GateOp] = []
+    measurements: list[int] = []
+
+    for raw in qasm.strip().splitlines():
+        line = raw.strip()
+        if (
+            not line
+            or line.startswith("//")
+            or _HEADER_RE.match(line)
+            or _INCLUDE_RE.match(line)
+        ):
+            continue
+        if _BIT_DECL_RE.match(line):
+            continue
+
+        m_q = _QUBIT_DECL_RE.match(line)
+        if m_q:
+            if num_qubits is not None:
+                raise QASMConversionError(
+                    "Multiple qubit register declarations are not supported"
+                )
+            num_qubits = int(m_q.group(1))
+            continue
+
+        m_m = _MEASURE_RE.match(line)
+        if m_m:
+            measurements.append(int(m_m.group(2)))
+            continue
+
+        m_g = _GATE_RE.match(line)
+        if m_g:
+            gate_name = m_g.group(1)
+            params = (
+                [float(p.strip()) for p in m_g.group(2).split(",")]
+                if m_g.group(2)
+                else []
+            )
+            qubits = [int(q) for q in _QUBIT_REF_RE.findall(m_g.group(3))]
+            gates.append(_openqasm_gate_to_ir(gate_name, params, qubits, target))
+            continue
+
+        raise QASMConversionError(f"Unsupported QASM line: {line!r}")
+
+    if num_qubits is None:
+        raise QASMConversionError("No qubit register declaration found")
+
+    if metadata is None:
+        metadata = IRMetadata(
+            source_hash="sha256:from-qasm",
+            compiled_at=datetime.now(UTC).isoformat(),
+        )
+
+    try:
+        return NativeGateIR(
+            target=target,
+            num_qubits=num_qubits,
+            gates=gates,
+            measurements=measurements,
+            metadata=metadata,
+        )
+    except Exception as exc:
+        raise QASMConversionError(str(exc)) from exc
+
+
+# ---------------------------------------------------------------------------
+# NativeGateIR → OpenQASM
+# ---------------------------------------------------------------------------
+
+
+def ir_to_openqasm(ir: NativeGateIR) -> str:
+    """Serialize ``NativeGateIR`` into the supported OpenQASM subset.
+
+    The output is intentionally limited to the subset understood by
+    :func:`openqasm_to_ir` so tests can round-trip circuits through QASM and
+    keep treating ``NativeGateIR`` as the durable representation. The only
+    known lossy case is the ``id`` gate duration.
+
+    Args:
+        ir: Native-gate IR to serialize.
+
+    Returns:
+        OpenQASM 3.0 source text.
+
+    Raises:
+        QASMConversionError: If the IR contains a gate that has no supported
+            mapping for the selected target.
+    """
+    lines: list[str] = [
+        "OPENQASM 3.0;",
+        'include "stdgates.inc";',
+        f"qubit[{ir.num_qubits}] q;",
+    ]
+    if ir.measurements:
+        lines.append(f"bit[{len(ir.measurements)}] c;")
+
+    for op in ir.gates:
+        lines.append(_ir_gate_to_openqasm(op, ir.target))
+
+    for i, qubit in enumerate(ir.measurements):
+        lines.append(f"c[{i}] = measure q[{qubit}];")
+
+    return "\n".join(lines) + "\n"
+
+
+# ---------------------------------------------------------------------------
+# Internal gate mapping helpers
+# ---------------------------------------------------------------------------
+
+
+def _openqasm_gate_to_ir(
+    name: str, params: list[float], qubits: list[int], target: str
+) -> GateOp:
+    """Map a parsed OpenQASM gate into a target-specific IR operation.
+
+    Args:
+        name: Parsed OpenQASM gate name.
+        params: Parsed numeric gate parameters.
+        qubits: Parsed qubit indices referenced by the gate.
+        target: Native gate target that determines the mapping rules.
+
+    Returns:
+        Corresponding native-gate operation.
+
+    Raises:
+        QASMConversionError: If the target is unsupported.
+    """
+    if target == "cz":
+        return _openqasm_gate_to_ir_cz(name, params, qubits)
+    if target == "cnot":
+        return _openqasm_gate_to_ir_cnot(name, params, qubits)
+    raise QASMConversionError(f"Unsupported target: {target}")
+
+
+def _openqasm_gate_to_ir_cz(
+    name: str, params: list[float], qubits: list[int]
+) -> GateOp:
+    """Map an OpenQASM gate into the ``cz`` gate set.
+
+    Args:
+        name: Parsed OpenQASM gate name.
+        params: Parsed numeric gate parameters.
+        qubits: Parsed qubit indices referenced by the gate.
+
+    Returns:
+        Corresponding native-gate operation.
+
+    Raises:
+        QASMConversionError: If the gate is not representable for this target.
+    """
+    _map: dict[str, tuple[NativeGate, bool]] = {
+        "rx": (NativeGate.RX, True),
+        "ry": (NativeGate.RY, True),
+        "rz": (NativeGate.RZ, True),
+        "cz": (NativeGate.CZ, False),
+        "id": (NativeGate.ID, False),
+    }
+    if name not in _map:
+        raise QASMConversionError(f"Gate '{name}' not supported for cz")
+    ir_gate, has_params = _map[name]
+    if ir_gate == NativeGate.ID:
+        return GateOp(gate=ir_gate, qubits=qubits, params=[0.0])
+    return GateOp(gate=ir_gate, qubits=qubits, params=params if has_params else [])
+
+
+def _openqasm_gate_to_ir_cnot(
+    name: str, params: list[float], qubits: list[int]
+) -> GateOp:
+    """Map an OpenQASM gate into the ``cnot`` gate set.
+
+    Args:
+        name: Parsed QASM gate name.
+        params: Parsed numeric gate parameters.
+        qubits: Parsed qubit indices referenced by the gate.
+
+    Returns:
+        Corresponding native-gate operation.
+
+    Raises:
+        QASMConversionError: If the gate is not representable for this target.
+    """
+    _simple: dict[str, tuple[NativeGate, bool]] = {
+        "sx": (NativeGate.X90, False),
+        "rz": (NativeGate.VIRTUAL_Z, True),
+        "cx": (NativeGate.CNOT, False),
+        "id": (NativeGate.ID, False),
+    }
+    if name in _simple:
+        ir_gate, has_params = _simple[name]
+        if ir_gate == NativeGate.ID:
+            return GateOp(gate=ir_gate, qubits=qubits, params=[0.0])
+        return GateOp(gate=ir_gate, qubits=qubits, params=params if has_params else [])
+
+    if name == "ry" and len(params) == 1:
+        if math.isclose(params[0], -_HALF_PI, rel_tol=1e-12, abs_tol=1e-12):
+            return GateOp(gate=NativeGate.Y_MINUS_90, qubits=qubits, params=[])
+        raise QASMConversionError(
+            f"ry({params[0]}) not representable in cnot "
+            f"(only ry(-π/2) maps to y_minus_90)"
+        )
+
+    raise QASMConversionError(f"Gate '{name}' not supported for cnot")
+
+
+def _ir_gate_to_openqasm(op: GateOp, target: str) -> str:
+    """Map an IR operation into target-specific OpenQASM text.
+
+    Args:
+        op: IR gate operation to serialize.
+        target: Native gate target that determines the mapping rules.
+
+    Returns:
+        Single OpenQASM instruction line.
+
+    Raises:
+        QASMConversionError: If the target is unsupported.
+    """
+    name = op.gate.value
+    qubits_str = ", ".join(f"q[{q}]" for q in op.qubits)
+
+    if target == "cz":
+        return _ir_gate_to_openqasm_cz(name, op.params, qubits_str)
+    if target == "cnot":
+        return _ir_gate_to_openqasm_cnot(name, op.params, qubits_str)
+    raise QASMConversionError(f"Unsupported target: {target}")
+
+
+def _ir_gate_to_openqasm_cz(name: str, params: list[float], qubits_str: str) -> str:
+    """Serialize a ``cz`` IR gate into OpenQASM text.
+
+    Args:
+        name: Native gate name.
+        params: Gate parameters to emit.
+        qubits_str: Preformatted OpenQASM qubit operand list.
+
+    Returns:
+        Single OpenQASM instruction line.
+
+    Raises:
+        QASMConversionError: If the gate has no supported OpenQASM mapping.
+    """
+    _parameterized = {"rx", "ry", "rz"}
+    _parameterless = {"cz", "id"}
+    if name in _parameterized:
+        ps = ", ".join(_format_float(p) for p in params)
+        return f"{name}({ps}) {qubits_str};"
+    if name == "virtual_z":
+        if not params:
+            raise QASMConversionError(
+                "IR gate 'virtual_z' requires exactly one parameter"
+            )
+        return f"rz({_format_float(params[0])}) {qubits_str};"
+    if name in _parameterless:
+        return f"{name} {qubits_str};"
+    raise QASMConversionError(f"IR gate '{name}' has no OpenQASM mapping for cz")
+
+
+def _ir_gate_to_openqasm_cnot(name: str, params: list[float], qubits_str: str) -> str:
+    """Serialize a ``cnot`` IR gate into OpenQASM text.
+
+    Args:
+        name: Native gate name.
+        params: Gate parameters to emit.
+        qubits_str: Preformatted OpenQASM qubit operand list.
+
+    Returns:
+        Single OpenQASM instruction line.
+
+    Raises:
+        QASMConversionError: If the gate has no supported OpenQASM mapping.
+    """
+    if name == "x90":
+        return f"sx {qubits_str};"
+    if name == "y_minus_90":
+        return f"ry({_format_float(-_HALF_PI)}) {qubits_str};"
+    if name == "virtual_z":
+        return f"rz({_format_float(params[0])}) {qubits_str};"
+    if name == "cnot":
+        return f"cx {qubits_str};"
+    if name == "id":
+        return f"id {qubits_str};"
+    raise QASMConversionError(f"IR gate '{name}' has no OpenQASM mapping for cnot")