qoro-divi 0.2.0b1__py3-none-any.whl → 0.6.0__py3-none-any.whl

divi/backends/_qpu_system.py

@@ -0,0 +1,101 @@
+# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Data models for Quantum Processing Units (QPUs) and QPUSystems."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from threading import RLock
+
+_AVAILABLE_QPU_SYSTEMS: dict[str, QPUSystem] = {}
+_CACHE_LOCK = RLock()
+
+
+@dataclass(frozen=True, repr=True)
+class QPU:
+    """Represents a single Quantum Processing Unit (QPU).
+
+    Attributes:
+        nickname: The unique name or identifier for the QPU.
+        q_bits: The number of qubits in the QPU.
+        status: The current operational status of the QPU.
+        system_kind: The type of technology the QPU uses.
+    """
+
+    nickname: str
+    q_bits: int
+    status: str
+    system_kind: str
+
+
+@dataclass(frozen=True, repr=True)
+class QPUSystem:
+    """Represents a collection of QPUs that form a quantum computing system.
+
+    Attributes:
+        name: The name of the QPU system.
+        qpus: A list of QPU objects that are part of this system.
+        access_level: The access level granted to the user for this system (e.g., 'PUBLIC').
+        supports_expval: Whether the system supports expectation value jobs.
+    """
+
+    name: str
+    qpus: list[QPU] = field(default_factory=list)
+    access_level: str = "PUBLIC"
+    supports_expval: bool = False
+
+
+def parse_qpu_systems(json_data: list) -> list[QPUSystem]:
+    """Parses a list of QPU system data from JSON into QPUSystem objects."""
+    return [
+        QPUSystem(
+            name=system_data["name"],
+            qpus=[QPU(**qpu) for qpu in system_data.get("qpus", [])],
+            access_level=system_data["access_level"],
+        )
+        for system_data in json_data
+    ]
+
+
+def update_qpu_systems_cache(systems: list[QPUSystem]):
+    """Updates the cache of available QPU systems."""
+    with _CACHE_LOCK:
+        _AVAILABLE_QPU_SYSTEMS.clear()
+        for system in systems:
+            if system.name == "qoro_maestro":
+                system = replace(system, supports_expval=True)
+            _AVAILABLE_QPU_SYSTEMS[system.name] = system
+
+
+def get_qpu_system(name: str) -> QPUSystem:
+    """
+    Get a QPUSystem object by its name from the cache.
+
+    Args:
+        name: The name of the QPU system to retrieve.
+
+    Returns:
+        The QPUSystem object with the matching name.
+
+    Raises:
+        ValueError: If the cache is empty or the system is not found.
+    """
+    with _CACHE_LOCK:
+        if not _AVAILABLE_QPU_SYSTEMS:
+            raise ValueError(
+                "QPU systems cache is empty. Call `QoroService.fetch_qpu_systems()` to populate it."
+            )
+        try:
+            return _AVAILABLE_QPU_SYSTEMS[name]
+        except KeyError:
+            raise ValueError(
+                f"QPUSystem with name '{name}' not found in cache."
+            ) from None
+
+
+def get_available_qpu_systems() -> list[QPUSystem]:
+    """Returns a list of all available QPU systems from the cache."""
+    with _CACHE_LOCK:
+        return list(_AVAILABLE_QPU_SYSTEMS.values())

divi/backends/_results_processing.py

@@ -0,0 +1,133 @@
+# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import base64
+
+
+def _decode_qh1_b64(encoded: dict) -> dict[str, int]:
+    """
+    Decode a {'encoding':'qh1','n_bits':N,'payload':base64} histogram
+    into a dict with bitstring keys -> int counts.
+
+    If `encoded` is None, returns None.
+    If `encoded` is an empty dict or has a missing/empty payload, returns `encoded` unchanged.
+    Otherwise, decodes the payload and returns a dict mapping bitstrings to counts.
+    """
+    if not encoded or not encoded.get("payload"):
+        return encoded
+
+    if encoded.get("encoding") != "qh1":
+        raise ValueError(f"Unsupported encoding: {encoded.get('encoding')}")
+
+    blob = base64.b64decode(encoded["payload"])
+    hist_int = _decompress_histogram(blob)
+    return {str(k): v for k, v in hist_int.items()}
+
+
+def _uleb128_decode(data: bytes, pos: int = 0) -> tuple[int, int]:
+    x = 0
+    shift = 0
+    while True:
+        if pos >= len(data):
+            raise ValueError("truncated varint")
+        b = data[pos]
+        pos += 1
+        x |= (b & 0x7F) << shift
+        if (b & 0x80) == 0:
+            break
+        shift += 7
+    return x, pos
+
+
+def _int_to_bitstr(x: int, n_bits: int) -> str:
+    return format(x, f"0{n_bits}b")
+
+
+def _rle_bool_decode(data: bytes, pos=0) -> tuple[list[bool], int]:
+    num_runs, pos = _uleb128_decode(data, pos)
+    if num_runs == 0:
+        return [], pos
+    first_val = data[pos] != 0
+    pos += 1
+    total, val = [], first_val
+    for _ in range(num_runs):
+        ln, pos = _uleb128_decode(data, pos)
+        total.extend([val] * ln)
+        val = not val
+    return total, pos
+
+
+def _decompress_histogram(buf: bytes) -> dict[str, int]:
+    if not buf:
+        return {}
+    pos = 0
+    if buf[pos : pos + 3] != b"QH1":
+        raise ValueError("bad magic")
+    pos += 3
+    n_bits = buf[pos]
+    pos += 1
+    unique, pos = _uleb128_decode(buf, pos)
+    total_shots, pos = _uleb128_decode(buf, pos)
+
+    num_gaps, pos = _uleb128_decode(buf, pos)
+    gaps = []
+    for _ in range(num_gaps):
+        g, pos = _uleb128_decode(buf, pos)
+        gaps.append(g)
+
+    idxs, acc = [], 0
+    for i, g in enumerate(gaps):
+        acc = g if i == 0 else acc + g
+        idxs.append(acc)
+
+    rb_len, pos = _uleb128_decode(buf, pos)
+    is_one, _ = _rle_bool_decode(buf[pos : pos + rb_len], 0)
+    pos += rb_len
+
+    extras_len, pos = _uleb128_decode(buf, pos)
+    extras = []
+    for _ in range(extras_len):
+        e, pos = _uleb128_decode(buf, pos)
+        extras.append(e)
+
+    counts, it = [], iter(extras)
+    for flag in is_one:
+        counts.append(1 if flag else next(it) + 2)
+
+    hist = {_int_to_bitstr(i, n_bits): c for i, c in zip(idxs, counts)}
+
+    # optional integrity check
+    if sum(counts) != total_shots:
+        raise ValueError("corrupt stream: shot sum mismatch")
+    if len(counts) != unique:
+        raise ValueError("corrupt stream: unique mismatch")
+    return hist
+
+
+def reverse_dict_endianness(
+    probs_dict: dict[str, dict[str, float]],
+) -> dict[str, dict[str, float]]:
+    """Reverse endianness of all bitstrings in a dictionary of probability distributions."""
+    return {
+        tag: {bitstring[::-1]: prob for bitstring, prob in probs.items()}
+        for tag, probs in probs_dict.items()
+    }
+
+
+def convert_counts_to_probs(
+    counts: dict[str, dict[str, int]], shots: int
+) -> dict[str, dict[str, float]]:
+    """Convert raw counts to probability distributions.
+
+    Args:
+        counts (dict[str, dict[str, int]]): The counts to convert to probabilities.
+        shots (int): The number of shots.
+
+    Returns:
+        dict[str, dict[str, float]]: The probability distributions.
+    """
+    return {
+        tag: {bitstring: count / shots for bitstring, count in probs.items()}
+        for tag, probs in counts.items()
+    }

divi/circuits/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2025-2026 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from ._qasm_conversion import to_openqasm
+from ._qasm_validation import is_valid_qasm, validate_qasm, validate_qasm_count_qubits
+from ._core import (
+    CircuitBundle,
+    ExecutableQASMCircuit,
+    MetaCircuit,
+    CircuitTag,
+    format_circuit_tag,
+)

divi/{exp/cirq → circuits/_cirq}/__init__.py

@@ -2,6 +2,5 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-# TODO: delete whole module once Cirq properly supports parameters in openqasm 3.0
 from . import _qasm_export  # Does nothing, just initiates the patch
-from ._qasm_import import cirq_circuit_from_qasm
+from ._parser import ExtendedQasmParser

divi/circuits/_cirq/_parser.py

@@ -0,0 +1,110 @@
+# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import sympy
+from cirq.contrib.qasm_import._lexer import QasmLexer
+from cirq.contrib.qasm_import._parser import QasmParser
+from cirq.contrib.qasm_import.exception import QasmException
+from ply import yacc
+
+
+class ExtendedQasmLexer(QasmLexer):
+    """Extended lexer with INPUT and ANGLE keywords."""
+
+    reserved = {
+        **QasmLexer.reserved,
+        "input": "INPUT",
+        "angle": "ANGLE",
+    }
+    # Rebuild tokens list to include new reserved keywords
+    tokens = [
+        "FORMAT_SPEC",
+        "NUMBER",
+        "NATURAL_NUMBER",
+        "STDGATESINC",
+        "QELIBINC",
+        "ID",
+        "ARROW",
+        "EQ",
+    ] + list(reserved.values())
+
+    # PLY quirk: When overriding t_ID, PLY's method discovery doesn't find inherited
+    # token methods. These three have multi-character patterns that MUST be checked
+    # before t_ID (PLY matches longest patterns first). Without explicit definitions,
+    # "OPENQASM" and "include" would be tokenized as ID instead of their proper types.
+    # We keep the regex in the docstring (required by PLY) but delegate to parent.
+    def t_FORMAT_SPEC(self, t):
+        r"""OPENQASM(\s+)([^\s\t\;]*);"""
+        return super().t_FORMAT_SPEC(t)
+
+    def t_QELIBINC(self, t):
+        r"""include(\s+)"qelib1.inc";"""
+        return super().t_QELIBINC(t)
+
+    def t_STDGATESINC(self, t):
+        r"""include(\s+)"stdgates.inc";"""
+        return super().t_STDGATESINC(t)
+
+    # Override t_ID to check both parent and extended reserved dicts
+    def t_ID(self, t):
+        r"""[^\W\d_][\w_]*"""
+        # This regex matches any Unicode letter (not digit/underscore) at the start,
+        # followed by any number of Unicode word characters or underscores.
+        # Check extended reserved first, then parent's
+        if t.value in self.reserved:
+            t.type = self.reserved[t.value]
+        elif t.value in QasmLexer.reserved:
+            t.type = QasmLexer.reserved[t.value]
+        return t
+
+
+class ExtendedQasmParser(QasmParser):
+    """Extended parser with QASM 3.0 parameter support.
+
+    Only adds support for: input angle[32] param_name;
+    """
+
+    # Add new tokens
+    tokens = QasmParser.tokens + ["INPUT", "ANGLE"]
+
+    def __init__(self) -> None:
+        # Initialize parameter storage
+        self.input_params: dict[str, sympy.Symbol] = {}
+
+        # Call parent to set up everything (this will create its own lexer and parser)
+        super().__init__()
+
+        self.lexer = ExtendedQasmLexer()
+
+        self.parser = yacc.yacc(module=self, debug=False, write_tables=False)
+
+    # Add parser rule for input angle declarations
+    def p_circuit_input_angle(self, p):
+        """circuit : input_angle circuit"""
+        p[0] = self.circuit
+
+    def p_input_angle(self, p):
+        """input_angle : INPUT ANGLE '[' NATURAL_NUMBER ']' ID ';'"""
+        param_name = p[6]
+        self.input_params[param_name] = sympy.Symbol(param_name)
+        p[0] = None
+
+    # Override to check input_params first
+    def p_expr_identifier(self, p):
+        """expr : ID"""
+        # Check input_params first (QASM 3.0 parameters)
+        if p[1] in self.input_params:
+            p[0] = self.input_params[p[1]]
+            return
+
+        # Fall back to parent logic (custom gate parameters)
+        if not self.in_custom_gate_scope:
+            raise QasmException(
+                f"Parameter '{p[1]}' in line {p.lineno(1)} not supported"
+            )
+        if p[1] not in self.custom_gate_scoped_params:
+            raise QasmException(f"Undefined parameter '{p[1]}' in line {p.lineno(1)}'")
+        p[0] = sympy.Symbol(p[1])

divi/circuits/_cirq/_qasm_export.py

@@ -0,0 +1,78 @@
+# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Patch for Cirq's QasmArgs.format_field to support symbolic parameters in QASM export.
+
+This module patches Cirq's QasmArgs.format_field method to properly handle:
+1. Symbolic parameters (Sympy expressions) with "half_turns" spec for rotation gates
+2. Float precision rounding for numeric parameters
+3. Qubit ID mapping for Qid objects
+
+Note: Measurement keys are handled directly by Cirq's qasm() function and do not
+require special handling in format_field.
+
+The patch is essential for QEM (Quantum Error Mitigation) protocols that modify circuits
+with symbolic parameters. When Cirq exports QASM code using cirq.qasm(), it formats rotation
+gate angles using the "half_turns" spec. Without this patch, Sympy expressions would not be
+properly converted to QASM format (e.g., "theta*pi" instead of just "theta").
+
+Example:
+    When a circuit contains a rotation gate with a Sympy symbol:
+        rz(theta * pi) q[0]
+
+    Cirq's QASM export calls format_field with the Sympy expression and spec="half_turns".
+    This patch ensures the expression is properly formatted for QASM output.
+"""
+
+from typing import Any
+
+from cirq import ops
+from cirq.protocols.qasm import QasmArgs
+from sympy import Expr, pi
+
+
+def patched_format_field(self, value: Any, spec: str) -> str:
+    """Patched version of QasmArgs.format_field for symbolic parameter support.
+
+    This method extends Cirq's QasmArgs.format_field to handle:
+    - Sympy expressions with "half_turns" spec (for rotation gate angles)
+    - Float precision rounding
+    - Qubit ID mapping
+
+    Args:
+        self: QasmArgs instance
+        value: The value to format (can be float, int, Sympy Expr, or Qid)
+        spec: Format specifier (e.g., "half_turns" or empty string)
+
+    Returns:
+        Formatted string representation of the value suitable for QASM output
+    """
+    # Handle numeric values (floats and integers)
+    if isinstance(value, (float, int)):
+        if isinstance(value, float):
+            value = round(value, self.precision)
+        if spec == "half_turns":
+            # Format as "pi*value" for QASM rotation gates
+            value = f"pi*{value}" if value != 0 else "0"
+            spec = ""
+
+    # Handle Cirq Qid objects (qubits)
+    elif isinstance(value, ops.Qid):
+        value = self.qubit_id_map[value]
+
+    # Handle Sympy expressions (symbolic parameters)
+    if isinstance(value, Expr):
+        if spec == "half_turns":
+            # Multiply by pi for rotation gates (Cirq uses half-turns internally)
+            value *= pi
+        return str(value)
+
+    # Fall back to parent implementation for other cases
+    return super(QasmArgs, self).format_field(value, spec)
+
+
+# Apply the patch to QasmArgs.format_field
+# This is done at module import time so all QASM exports use the patched version
+QasmArgs.format_field = patched_format_field