openquantum-sdk-cirq 0.5.0__tar.gz

openquantum_sdk_cirq-0.5.0/MANIFEST.in

@@ -0,0 +1,9 @@
+# Unit tests ship in the sdist. The wheel does not install them.
+include README.md
+include pyproject.toml
+recursive-include cirq_openquantum *.py
+recursive-include tests *.py
+global-exclude *.pyc
+global-exclude __pycache__
+prune .venv
+prune .pytest_cache

openquantum_sdk_cirq-0.5.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: openquantum-sdk-cirq
+Version: 0.5.0
+Summary: Cirq Python SDK for Open Quantum
+License: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: openquantum-sdk>=1.0.0
+Requires-Dist: cirq-core>=1.4
+Requires-Dist: numpy>=1.22
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-mock>=3.10; extra == "dev"
+
+# Cirq-Open Quantum Plugin
+
+> **Beta.** This plugin is in beta; its API and defaults may still change. Feedback is welcome in the [Quantum Rings community](https://www.quantumrings.com/community).
+
+A [Cirq](https://quantumai.google/cirq) sampler that submits circuits to the
+[Open Quantum](https://www.openquantum.com) platform. Write circuits with Cirq
+and run them on real quantum hardware.
+
+## How it works
+
+Cirq exports OpenQASM natively (`cirq.Circuit.to_qasm()`), so this plugin does
+not depend on the Qiskit plugin. `OpenQuantumSampler` is a thin
+[`cirq.Sampler`](https://quantumai.google/reference/python/cirq/Sampler):
+
+- `OpenQuantumClient.from_env` (Core SDK) handles authentication and backend
+  discovery.
+- Each resolved circuit is serialized to OpenQASM and submitted through the
+  framework-agnostic `SchedulerClient`.
+- Platform counts are reconstructed into `cirq.Result` objects.
+
+Because it implements `run_sweep`, the standard `cirq.Sampler` methods —
+`run`, `sample`, `run_sweep`, and `run_batch` — all work.
+
+## Installation
+
+```bash
+# Plugin (and core SDK)
+pip install openquantum-sdk-cirq
+
+# or via extras:
+pip install "openquantum-sdk[cirq]"
+```
+
+This pulls in `cirq-core` and `openquantum-sdk`.
+
+## Quick Start
+
+```python
+import cirq
+from cirq_openquantum import OpenQuantumSampler
+
+sampler = OpenQuantumSampler(
+    backend="ionq:forte-1",
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+)
+
+q = cirq.LineQubit.range(2)
+circuit = cirq.Circuit([
+    cirq.H(q[0]),
+    cirq.CNOT(q[0], q[1]),
+    cirq.measure(*q, key="m"),
+])
+
+result = sampler.run(circuit, repetitions=1024)
+print(result.histogram(key="m"))
+# Counter({0: ~512, 3: ~512})   # 00 and 11
+```
+
+Circuits must contain at least one `cirq.measure(...)`; the QASM exporter does
+not add measurements for you.
+
+## Authentication
+
+Resolved in this order:
+
+1. **Pre-built client** — pass `client=OpenQuantumClient(...)` for full control
+   (saved accounts, custom URLs, keyring).
+2. **Bearer token** — pass `token=` or set `OPENQUANTUM_TOKEN`.
+3. **Client credentials** — pass `client_id=` + `client_secret=` or set
+   `OPENQUANTUM_CLIENT_ID` + `OPENQUANTUM_CLIENT_SECRET`.
+
+| Parameter | Environment Variable | Description |
+|-----------|---------------------|-------------|
+| `token` | `OPENQUANTUM_TOKEN` | Bearer token |
+| `client_id` | `OPENQUANTUM_CLIENT_ID` | OAuth2 client ID |
+| `client_secret` | `OPENQUANTUM_CLIENT_SECRET` | OAuth2 client secret |
+| | `OPENQUANTUM_SDK_KEY` | Path to an SDK-key JSON file (`{client_id, client_secret}`) |
+| `organization_id` | `OPENQUANTUM_ORGANIZATION_ID` | Organization UUID (optional if single org) |
+| `scheduler_url` | `OPENQUANTUM_SCHEDULER_URL` | Scheduler API base, when the argument is omitted |
+| `management_url` | `OPENQUANTUM_MANAGEMENT_URL` | Management API base, when the argument is omitted |
+| `keycloak_base` | `OPENQUANTUM_KEYCLOAK_BASE` | Keycloak base, when the argument is omitted |
+| `realm` | `OPENQUANTUM_KEYCLOAK_REALM` | Keycloak realm, when the argument is omitted |
+
+`from_env()` raises `AuthenticationError` when no credential resolves. The older `OPENQUANTUM_*_BASE` URL names are not read here; those remain an MCP-only fallback.
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `backend` | required | Backend class ID or short_code (e.g. `"ionq:forte-1"`) |
+| `job_subcategory_id` | `"oth:oth"` | Workload subcategory (set the most specific match) |
+| `execution_plan` | `"auto"` | `"auto"`, `"public"`, `"private"`, an enum, or a plan UUID. `"auto"` picks the cheapest plan |
+| `queue_priority` | `"auto"` | `"auto"`, `"standard"`, `"priority"`, `"instant"`, an enum, or a priority UUID. `"auto"` picks the cheapest priority |
+| `export_format` | `"qasm3"` | `"qasm2"` or `"qasm3"` |
+| `configuration_data` | `{}` | Backend-specific config passthrough (e.g. `{"engine": "amber_quantum_rings"}`) |
+| `reverse_bits` | `True` | Reverse platform bitstrings to Cirq's big-endian order |
+| `verbose` | `False` | Print submission progress and credit cost to stdout |
+| `job_timeout_seconds` | `86400` | Max wait for job completion (1 day) |
+
+Shots are set per run via `repetitions` and injected into `configuration_data`.
+
+## Backend-specific configuration
+
+Some backends require extra fields. The free Quantum Rings simulator
+(`qr:gpu-gb10`) requires an `engine`:
+
+```python
+sampler = OpenQuantumSampler(
+    backend="qr:gpu-gb10",
+    configuration_data={"engine": "amber_quantum_rings"},
+)
+```
+
+## Bit ordering
+
+The platform returns counts little-endian (the first classical bit is the
+rightmost character, Qiskit-style), while Cirq is big-endian (the first
+measured qubit is the most-significant bit). The sampler reverses each
+bitstring by default (`reverse_bits=True`) so the mapping is correct, verified
+live against an asymmetric `|10>` state. Set `reverse_bits=False` only for a
+backend that returns counts big-endian.
+
+## License
+
+Apache License 2.0

openquantum_sdk_cirq-0.5.0/README.md

@@ -0,0 +1,126 @@
+# Cirq-Open Quantum Plugin
+
+> **Beta.** This plugin is in beta; its API and defaults may still change. Feedback is welcome in the [Quantum Rings community](https://www.quantumrings.com/community).
+
+A [Cirq](https://quantumai.google/cirq) sampler that submits circuits to the
+[Open Quantum](https://www.openquantum.com) platform. Write circuits with Cirq
+and run them on real quantum hardware.
+
+## How it works
+
+Cirq exports OpenQASM natively (`cirq.Circuit.to_qasm()`), so this plugin does
+not depend on the Qiskit plugin. `OpenQuantumSampler` is a thin
+[`cirq.Sampler`](https://quantumai.google/reference/python/cirq/Sampler):
+
+- `OpenQuantumClient.from_env` (Core SDK) handles authentication and backend
+  discovery.
+- Each resolved circuit is serialized to OpenQASM and submitted through the
+  framework-agnostic `SchedulerClient`.
+- Platform counts are reconstructed into `cirq.Result` objects.
+
+Because it implements `run_sweep`, the standard `cirq.Sampler` methods —
+`run`, `sample`, `run_sweep`, and `run_batch` — all work.
+
+## Installation
+
+```bash
+# Plugin (and core SDK)
+pip install openquantum-sdk-cirq
+
+# or via extras:
+pip install "openquantum-sdk[cirq]"
+```
+
+This pulls in `cirq-core` and `openquantum-sdk`.
+
+## Quick Start
+
+```python
+import cirq
+from cirq_openquantum import OpenQuantumSampler
+
+sampler = OpenQuantumSampler(
+    backend="ionq:forte-1",
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+)
+
+q = cirq.LineQubit.range(2)
+circuit = cirq.Circuit([
+    cirq.H(q[0]),
+    cirq.CNOT(q[0], q[1]),
+    cirq.measure(*q, key="m"),
+])
+
+result = sampler.run(circuit, repetitions=1024)
+print(result.histogram(key="m"))
+# Counter({0: ~512, 3: ~512})   # 00 and 11
+```
+
+Circuits must contain at least one `cirq.measure(...)`; the QASM exporter does
+not add measurements for you.
+
+## Authentication
+
+Resolved in this order:
+
+1. **Pre-built client** — pass `client=OpenQuantumClient(...)` for full control
+   (saved accounts, custom URLs, keyring).
+2. **Bearer token** — pass `token=` or set `OPENQUANTUM_TOKEN`.
+3. **Client credentials** — pass `client_id=` + `client_secret=` or set
+   `OPENQUANTUM_CLIENT_ID` + `OPENQUANTUM_CLIENT_SECRET`.
+
+| Parameter | Environment Variable | Description |
+|-----------|---------------------|-------------|
+| `token` | `OPENQUANTUM_TOKEN` | Bearer token |
+| `client_id` | `OPENQUANTUM_CLIENT_ID` | OAuth2 client ID |
+| `client_secret` | `OPENQUANTUM_CLIENT_SECRET` | OAuth2 client secret |
+| | `OPENQUANTUM_SDK_KEY` | Path to an SDK-key JSON file (`{client_id, client_secret}`) |
+| `organization_id` | `OPENQUANTUM_ORGANIZATION_ID` | Organization UUID (optional if single org) |
+| `scheduler_url` | `OPENQUANTUM_SCHEDULER_URL` | Scheduler API base, when the argument is omitted |
+| `management_url` | `OPENQUANTUM_MANAGEMENT_URL` | Management API base, when the argument is omitted |
+| `keycloak_base` | `OPENQUANTUM_KEYCLOAK_BASE` | Keycloak base, when the argument is omitted |
+| `realm` | `OPENQUANTUM_KEYCLOAK_REALM` | Keycloak realm, when the argument is omitted |
+
+`from_env()` raises `AuthenticationError` when no credential resolves. The older `OPENQUANTUM_*_BASE` URL names are not read here; those remain an MCP-only fallback.
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `backend` | required | Backend class ID or short_code (e.g. `"ionq:forte-1"`) |
+| `job_subcategory_id` | `"oth:oth"` | Workload subcategory (set the most specific match) |
+| `execution_plan` | `"auto"` | `"auto"`, `"public"`, `"private"`, an enum, or a plan UUID. `"auto"` picks the cheapest plan |
+| `queue_priority` | `"auto"` | `"auto"`, `"standard"`, `"priority"`, `"instant"`, an enum, or a priority UUID. `"auto"` picks the cheapest priority |
+| `export_format` | `"qasm3"` | `"qasm2"` or `"qasm3"` |
+| `configuration_data` | `{}` | Backend-specific config passthrough (e.g. `{"engine": "amber_quantum_rings"}`) |
+| `reverse_bits` | `True` | Reverse platform bitstrings to Cirq's big-endian order |
+| `verbose` | `False` | Print submission progress and credit cost to stdout |
+| `job_timeout_seconds` | `86400` | Max wait for job completion (1 day) |
+
+Shots are set per run via `repetitions` and injected into `configuration_data`.
+
+## Backend-specific configuration
+
+Some backends require extra fields. The free Quantum Rings simulator
+(`qr:gpu-gb10`) requires an `engine`:
+
+```python
+sampler = OpenQuantumSampler(
+    backend="qr:gpu-gb10",
+    configuration_data={"engine": "amber_quantum_rings"},
+)
+```
+
+## Bit ordering
+
+The platform returns counts little-endian (the first classical bit is the
+rightmost character, Qiskit-style), while Cirq is big-endian (the first
+measured qubit is the most-significant bit). The sampler reverses each
+bitstring by default (`reverse_bits=True`) so the mapping is correct, verified
+live against an asymmetric `|10>` state. Set `reverse_bits=False` only for a
+backend that returns counts big-endian.
+
+## License
+
+Apache License 2.0

openquantum_sdk_cirq-0.5.0/cirq_openquantum/__init__.py

@@ -0,0 +1,7 @@
+"""Cirq sampler for the Open Quantum quantum computing platform."""
+
+from cirq_openquantum.result import result_from_counts
+from cirq_openquantum.sampler import OpenQuantumSampler
+
+__version__ = "0.5.0"
+__all__ = ["OpenQuantumSampler", "result_from_counts"]

openquantum_sdk_cirq-0.5.0/cirq_openquantum/result.py

@@ -0,0 +1,215 @@
+"""Build ``cirq.Result`` objects from Open Quantum platform counts.
+
+The platform returns a ``{bitstring: count}`` histogram for each submitted
+circuit. Cirq's result layer wants per-shot measurement records keyed by
+measurement key, so this module expands the histogram back into the
+``(repetitions, num_qubits)`` ``numpy`` arrays a :class:`cirq.ResultDict`
+expects.
+
+**Bitstring layout.** The platform indexes each returned bitstring by
+*classical bit*, not by qubit. It parses the exported OpenQASM, allocates one
+classical register (``creg``/``bit[]``) per measurement, and concatenates them
+little-endian in declaration order (Qiskit convention): the first-declared
+register occupies the least-significant (rightmost) bits, and the rightmost
+character of the string is classical bit 0. ``OpenQuantumSampler`` reverses each
+bitstring by default (``reverse_bits=True``) so the mapping to ascending
+classical-bit index is correct.
+
+Because the layout is classical-bit based, it is reconstructed from the exact
+QASM that was submitted: each ``measure q[i] -> m_<key>[j]`` statement ties a
+qubit to a classical bit, and the register declaration order fixes the global
+bit offsets. Slicing by qubit index (as an earlier version did) only coincided
+with the true layout when every qubit was measured once, in qubit order, under
+a single key; reordered, multi-key, or subset measurements came back wrong.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, List, Mapping, Optional, Sequence, Tuple
+
+import cirq
+import numpy as np
+
+from openquantum_sdk.exceptions import CircuitValidationError, JobError
+
+# QASM 2.0: ``creg name[width];``   QASM 3.0: ``bit[width] name;`` / ``bit name;``
+_DECL_CREG = re.compile(r"\bcreg\s+(\w+)\s*\[\s*(\d+)\s*\]")
+_DECL_BIT_N = re.compile(r"\bbit\s*\[\s*(\d+)\s*\]\s*(\w+)")
+_DECL_BIT_1 = re.compile(r"\bbit\s+(\w+)\s*;")
+# QASM 2.0: ``measure q[i] -> name[j];``   QASM 3.0: ``name[j] = measure q[i];``
+_MEAS_Q2 = re.compile(r"\bmeasure\s+q\s*\[\s*(\d+)\s*\]\s*->\s*(\w+)\s*\[\s*(\d+)\s*\]")
+_MEAS_Q3 = re.compile(r"(\w+)\s*\[\s*(\d+)\s*\]\s*=\s*measure\s+q\s*\[\s*(\d+)\s*\]")
+
+
+def _parse_qasm_registers(qasm: str):
+    """Parse classical register declarations and measurements from QASM.
+
+    Returns ``(cregs, offsets, total, creg_qubits)`` where ``cregs`` is the
+    ordered ``[(name, width)]`` list of register declarations, ``offsets`` maps
+    each register name to its global classical-bit offset (first-declared
+    register at offset 0, i.e. least significant), ``total`` is the total
+    classical-bit width, and ``creg_qubits`` maps each register name to
+    ``{creg_bit: qubit_index}`` recovered from the measure statements.
+    """
+    cregs: List[Tuple[str, int]] = []  # (name, width) in declaration order
+    creg_qubits: Dict[str, Dict[int, int]] = {}
+
+    for raw in qasm.splitlines():
+        line = raw.split("//", 1)[0]  # drop trailing comments
+        if not line.strip():
+            continue
+
+        bit_n = _DECL_BIT_N.search(line)
+        creg = _DECL_CREG.search(line)
+        bit_1 = _DECL_BIT_1.search(line)
+        if bit_n:
+            cregs.append((bit_n.group(2), int(bit_n.group(1))))
+        elif creg:
+            cregs.append((creg.group(1), int(creg.group(2))))
+        elif bit_1:
+            cregs.append((bit_1.group(1), 1))
+
+        for mo in _MEAS_Q2.finditer(line):
+            qidx, name, cbit = int(mo.group(1)), mo.group(2), int(mo.group(3))
+            creg_qubits.setdefault(name, {})[cbit] = qidx
+        for mo in _MEAS_Q3.finditer(line):
+            name, cbit, qidx = mo.group(1), int(mo.group(2)), int(mo.group(3))
+            creg_qubits.setdefault(name, {})[cbit] = qidx
+
+    offsets: Dict[str, int] = {}
+    offset = 0
+    for name, width in cregs:
+        offsets[name] = offset
+        offset += width
+    return cregs, offsets, offset, creg_qubits
+
+
+def _measurement_layout(
+    circuit, qasm: str
+) -> Tuple[List[Tuple[str, List[int]]], int]:
+    """Return ``([(key, global_classical_bits)], total_bits)`` for a circuit.
+
+    Each measurement key is matched to the classical register that captured it
+    by comparing the ordered tuple of measured qubit indices (recovered from the
+    QASM measure statements) rather than by register name, since Cirq sanitises
+    unsafe keys into names like ``m0``/``m1`` that do not echo the key. Column
+    ``c`` of a key's result array maps to its register's classical bit ``c``.
+    """
+    cregs, offsets, total, creg_qubits = _parse_qasm_registers(qasm)
+
+    ordered_qubits = cirq.QubitOrder.DEFAULT.order_for(circuit.all_qubits())
+    index_of = {q: i for i, q in enumerate(ordered_qubits)}
+
+    # Ordered qubit-index tuple each register captured, used for matching.
+    creg_tuple = {
+        name: tuple(creg_qubits.get(name, {}).get(c) for c in range(width))
+        for name, width in cregs
+    }
+
+    layout: List[Tuple[str, List[int]]] = []
+    used = set()
+    for op in circuit.all_operations():
+        gate = getattr(op, "gate", None)
+        if not isinstance(gate, cirq.MeasurementGate):
+            continue
+        key = cirq.measurement_key_name(op)
+        qtuple = tuple(index_of[q] for q in op.qubits)
+
+        match = None
+        for name, _width in cregs:
+            if name not in used and creg_tuple[name] == qtuple:
+                match = name
+                break
+        if match is None:
+            raise JobError(
+                f"Could not map measurement key {key!r} (qubits {qtuple}) to a "
+                f"classical register in the submitted QASM."
+            )
+        used.add(match)
+        base = offsets[match]
+        layout.append((key, [base + c for c in range(len(qtuple))]))
+
+    return layout, total
+
+
+def result_from_counts(
+    counts: Mapping[str, int],
+    circuit,
+    params=None,
+    *,
+    reverse_bits: bool = False,
+    qasm: Optional[str] = None,
+):
+    """Reconstruct a ``cirq.ResultDict`` from a platform counts histogram.
+
+    Args:
+        counts: ``{bitstring: count}`` as returned by the scheduler.
+        circuit: The resolved ``cirq.Circuit`` that was submitted.
+        params: The ``cirq.ParamResolver`` used for this circuit (stored on the
+            result so sweeps round-trip their parameters).
+        reverse_bits: Reverse each platform bitstring before mapping. The
+            platform returns counts little-endian (classical bit 0 is the
+            rightmost character), so this must be ``True`` to map onto ascending
+            classical-bit index. The sampler passes ``True`` by default.
+        qasm: The exact OpenQASM submitted for this circuit. When omitted it is
+            regenerated with ``circuit.to_qasm()``; pass the submitted string to
+            guarantee the layout matches what the platform parsed.
+
+    Returns:
+        A ``cirq.ResultDict`` whose ``measurements[key]`` is a
+        ``(repetitions, num_qubits_in_key)`` ``uint8`` array.
+    """
+    if qasm is None:
+        qasm = circuit.to_qasm()
+
+    layout, total = _measurement_layout(circuit, qasm)
+    if not layout:
+        raise CircuitValidationError(
+            "Circuit has no measurement gates; add cirq.measure(...) before "
+            "sampling on the Open Quantum platform."
+        )
+
+    per_key_rows: Dict[str, List[List[int]]] = {key: [] for key, _ in layout}
+    for bitstring, count in counts.items():
+        clean = bitstring.replace(" ", "")
+        if len(clean) < total:
+            # The platform may omit leading (most-significant) zero bits.
+            clean = clean.rjust(total, "0")
+        elif len(clean) > total:
+            raise JobError(
+                f"Counts bitstring {bitstring!r} has {len(clean)} bits but the "
+                f"circuit declares {total} classical bit(s)."
+            )
+        if reverse_bits:
+            clean = clean[::-1]
+        bits = [int(c) for c in clean]
+        for key, global_bits in layout:
+            segment = [bits[g] for g in global_bits]
+            per_key_rows[key].extend([segment] * int(count))
+
+    measurements = {
+        key: np.array(per_key_rows[key], dtype=np.uint8).reshape(
+            len(per_key_rows[key]), len(global_bits)
+        )
+        for key, global_bits in layout
+    }
+    resolver = params if params is not None else cirq.ParamResolver({})
+    return cirq.ResultDict(params=resolver, measurements=measurements)
+
+
+def results_from_counts_list(
+    counts_list: Sequence[Mapping[str, int]],
+    circuit,
+    resolvers,
+    *,
+    reverse_bits: bool = False,
+    qasm: Optional[str] = None,
+):
+    """Build one ``cirq.ResultDict`` per resolver from a list of histograms."""
+    return [
+        result_from_counts(
+            counts, circuit, resolver, reverse_bits=reverse_bits, qasm=qasm
+        )
+        for counts, resolver in zip(counts_list, resolvers)
+    ]