qoro-divi 0.3.4__py3-none-any.whl → 0.3.5__py3-none-any.whl

divi/backends/_qoro_service.py

@@ -20,7 +20,7 @@ from divi.backends._qpu_system import QPU, QPUSystem
 from divi.extern.cirq import is_valid_qasm
 
 API_URL = "https://app.qoroquantum.net/api"
-MAX_PAYLOAD_SIZE_MB = 0.95
+_MAX_PAYLOAD_SIZE_MB = 0.95
 
 session = requests.Session()
 retry_configuration = Retry(
@@ -35,6 +35,106 @@ session.mount("https://", HTTPAdapter(max_retries=retry_configuration))
 
 logger = logging.getLogger(__name__)
 
+_DEFAULT_QPU_SYSTEM = "qoro_maestro"
+
+
+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.
+
+    Returns {} if payload is empty.
+    """
+    if not encoded or not encoded.get("payload"):
+        return {}
+
+    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 _raise_with_details(resp: requests.Response):
     try:
@@ -103,6 +203,8 @@ class QoroService(CircuitRunner):
         self.auth_token = "Bearer " + auth_token
         self.polling_interval = polling_interval
         self.max_retries = max_retries
+        if qpu_system_name is None:
+            qpu_system_name = _DEFAULT_QPU_SYSTEM
         self._qpu_system_name = qpu_system_name
         self.use_circuit_packing = use_circuit_packing
 
@@ -124,11 +226,28 @@ class QoroService(CircuitRunner):
             self._qpu_system_name = system_name.name
         elif system_name is None:
             self._qpu_system_name = None
-        else:
-            raise TypeError("Expected a QPUSystem instance or str.")
+
+        raise TypeError("Expected a QPUSystem instance or str.")
 
     def _make_request(self, method: str, endpoint: str, **kwargs) -> requests.Response:
-        """A centralized helper for making API requests."""
+        """
+        Make an authenticated HTTP request to the Qoro API.
+
+        This internal method centralizes all API communication, handling authentication
+        headers and error responses consistently.
+
+        Args:
+            method (str): HTTP method to use (e.g., 'get', 'post', 'delete').
+            endpoint (str): API endpoint path (without base URL).
+            **kwargs: Additional arguments to pass to requests.request(), such as
+                'json', 'timeout', 'params', etc.
+
+        Returns:
+            requests.Response: The HTTP response object from the API.
+
+        Raises:
+            requests.exceptions.HTTPError: If the response status code is 400 or above.
+        """
         url = f"{API_URL}/{endpoint}"
 
         headers = {"Authorization": self.auth_token}
@@ -151,7 +270,19 @@ class QoroService(CircuitRunner):
         return response
 
     def test_connection(self):
-        """Test the connection to the Qoro API"""
+        """
+        Test the connection to the Qoro API.
+
+        Sends a simple GET request to verify that the API is reachable and
+        the authentication token is valid.
+
+        Returns:
+            requests.Response: The response from the API ping endpoint.
+
+        Raises:
+            requests.exceptions.HTTPError: If the connection fails or authentication
+                is invalid.
+        """
         return self._make_request("get", "", timeout=10)
 
     def fetch_qpu_systems(self) -> list[QPUSystem]:
@@ -174,7 +305,7 @@ class QoroService(CircuitRunner):
         consistent overhead calculation.
         Assumes that BASE64 encoding produces ASCI characters, which are 1 byte each.
         """
-        max_payload_bytes = MAX_PAYLOAD_SIZE_MB * 1024 * 1024
+        max_payload_bytes = _MAX_PAYLOAD_SIZE_MB * 1024 * 1024
         circuit_chunks = []
         current_chunk = {}
 
@@ -214,29 +345,34 @@ class QoroService(CircuitRunner):
         job_type: JobType = JobType.SIMULATE,
         qpu_system_name: str | None = None,
         override_circuit_packing: bool | None = None,
-    ):
+    ) -> str:
         """
         Submit quantum circuits to the Qoro API for execution.
 
+        This method first initializes a job and then sends the circuits in
+        one or more chunks, associating them all with a single job ID.
+
         Args:
             circuits (dict[str, str]):
                 Dictionary mapping unique circuit IDs to QASM circuit strings.
             tag (str, optional):
                 Tag to associate with the job for identification. Defaults to "default".
             job_type (JobType, optional):
-                Type of job to execute (e.g., SIMULATE, EXECUTE, ESTIMATE, CIRCUIT_CUT). Defaults to JobType.SIMULATE.
-            use_packing (bool):
-                Whether to use circuit packing optimization. Defaults to False.
+                Type of job to execute (e.g., SIMULATE, EXECUTE, ESTIMATE, CIRCUIT_CUT).
+                Defaults to JobType.SIMULATE.
+            qpu_system_name (str | None, optional):
+                The name of the QPU system to use. Overrides the service's default.
+            override_circuit_packing (bool | None, optional):
+                Whether to use circuit packing optimization. Overrides the service's default.
 
         Raises:
-            ValueError: If more than one circuit is submitted for a CIRCUIT_CUT job.
+            ValueError: If more than one circuit is submitted for a CIRCUIT_CUT job,
+                        or if any circuit is not valid QASM.
+            requests.exceptions.HTTPError: If any API request fails.
 
         Returns:
-            str or list[str]:
-                The job ID(s) of the created job(s). Returns a single job ID if only one job is created,
-                otherwise returns a list of job IDs if the circuits are split into multiple jobs due to payload size.
+            str: The job ID for the created job.
         """
-
         if job_type == JobType.CIRCUIT_CUT and len(circuits) > 1:
             raise ValueError("Only one circuit allowed for circuit-cutting jobs.")
 
@@ -244,9 +380,8 @@ class QoroService(CircuitRunner):
             if not (err := is_valid_qasm(circuit)):
                 raise ValueError(f"Circuit '{key}' is not a valid QASM: {err}")
 
-        circuit_chunks = self._split_circuits(circuits)
-
-        payload = {
+        # 1. Initialize the job without circuits to get a job_id
+        init_payload = {
             "shots": self.shots,
             "tag": tag,
             "job_type": job_type.value,
@@ -258,111 +393,107 @@ class QoroService(CircuitRunner):
             ),
         }
 
-        job_ids = []
-        for chunk in circuit_chunks:
-            payload["circuits"] = chunk
+        init_response = self._make_request(
+            "post", "job/init/", json=init_payload, timeout=100
+        )
+        if init_response.status_code not in [HTTPStatus.OK, HTTPStatus.CREATED]:
+            _raise_with_details(init_response)
+        job_id = init_response.json()["job_id"]
 
-            response = self._make_request(
+        # 2. Split circuits and add them to the created job
+        circuit_chunks = self._split_circuits(circuits)
+        num_chunks = len(circuit_chunks)
+
+        for i, chunk in enumerate(circuit_chunks):
+            is_last_chunk = i == num_chunks - 1
+            add_circuits_payload = {
+                "circuits": chunk,
+                "shots": self.shots,
+                "mode": "append",
+                "finalized": "true" if is_last_chunk else "false",
+            }
+
+            add_circuits_response = self._make_request(
                 "post",
-                "job/",
-                json=payload,
+                f"job/{job_id}/add_circuits/",
+                json=add_circuits_payload,
                 timeout=100,
             )
+            if add_circuits_response.status_code != HTTPStatus.OK:
+                _raise_with_details(add_circuits_response)
 
-            if response.status_code == HTTPStatus.CREATED:
-                job_ids.append(response.json()["job_id"])
-            else:
-                _raise_with_details(response)
-
-        return job_ids if len(job_ids) > 1 else job_ids[0]
+        return job_id
 
-    def delete_job(self, job_ids):
+    def delete_job(self, job_id: str) -> requests.Response:
         """
         Delete a job from the Qoro Database.
 
         Args:
-            job_id: The ID of the jobs to be deleted
+            job_id: The ID of the job to be deleted.
         Returns:
-            response: The response from the API
+            requests.Response: The response from the API.
         """
-        if not isinstance(job_ids, list):
-            job_ids = [job_ids]
-
-        responses = [
-            self._make_request(
-                "delete",
-                f"job/{job_id}",
-                timeout=50,
-            )
-            for job_id in job_ids
-        ]
-
-        return responses if len(responses) > 1 else responses[0]
+        return self._make_request(
+            "delete",
+            f"job/{job_id}",
+            timeout=50,
+        )
 
-    def get_job_results(self, job_ids):
+    def get_job_results(self, job_id: str) -> list[dict]:
         """
         Get the results of a job from the Qoro Database.
 
         Args:
-            job_id: The ID of the job to get results from
+            job_id: The ID of the job to get results from.
         Returns:
-            results: The results of the job
+            list[dict]: The results of the job, with histograms decoded.
         """
-        if not isinstance(job_ids, list):
-            job_ids = [job_ids]
-
-        responses = [
-            self._make_request(
+        try:
+            response = self._make_request(
                 "get",
-                f"job/{job_id}/results",
+                f"job/{job_id}/resultsV2/?limit=100&offset=0",
                 timeout=100,
             )
-            for job_id in job_ids
-        ]
-
-        if all(response.status_code == HTTPStatus.OK for response in responses):
-            responses = [response.json() for response in responses]
-            return sum(responses, [])
-        elif any(
-            response.status_code == HTTPStatus.BAD_REQUEST for response in responses
-        ):
-            raise requests.exceptions.HTTPError(
-                "400 Bad Request: Job results not available, likely job is still running"
-            )
-        else:
-            for response in responses:
-                if response.status_code not in [HTTPStatus.OK, HTTPStatus.BAD_REQUEST]:
-                    raise requests.exceptions.HTTPError(
-                        f"{response.status_code}: {response.reason}"
-                    )
+        except requests.exceptions.HTTPError as e:
+            # Provide a more specific error message for 400 Bad Request
+            if e.response.status_code == HTTPStatus.BAD_REQUEST:
+                raise requests.exceptions.HTTPError(
+                    "400 Bad Request: Job results not available, likely job is still running"
+                ) from e
+            # Re-raise any other HTTP error
+            raise e
+
+        # If the request was successful, process the data
+        data = response.json()
+        for result in data["results"]:
+            result["results"] = _decode_qh1_b64(result["results"])
+        return data["results"]
 
     def poll_job_status(
         self,
-        job_ids: str | list[str],
+        job_id: str,
         loop_until_complete: bool = False,
-        on_complete: Callable | None = None,
+        on_complete: Callable[[requests.Response], None] | None = None,
         verbose: bool = True,
         poll_callback: Callable[[int, str], None] | None = None,
-    ):
+    ) -> str | JobStatus:
         """
-        Get the status of a job and optionally execute function *on_complete* on the results
-        if the status is COMPLETE.
+        Get the status of a job and optionally execute a function on completion.
 
         Args:
-            job_ids: The job id of the jobs to check
-            loop_until_complete (bool): A flag to loop until the job is completed
-            on_complete (optional): A function to be called when the job is completed
-            polling_interval (optional): The time to wait between retries
-            verbose (optional): A flag to print the when retrying
-            poll_callback (optional): A function for updating progress bars while polling.
-                Definition should be `poll_callback(retry_count: int, status: str) -> None`.
+            job_id: The ID of the job to check.
+            loop_until_complete (bool): If True, polls until the job is complete or failed.
+            on_complete (Callable, optional): A function to call with the final response
+                object when the job finishes.
+            verbose (bool, optional): If True, prints polling status to the logger.
+            poll_callback (Callable, optional): A function for updating progress bars.
+                Takes `(retry_count, status)`.
+
         Returns:
-            status: The status of the job
+            str | JobStatus: The current job status as a string if not looping,
+            or a JobStatus enum member (COMPLETED or FAILED) if looping.
         """
-        if not isinstance(job_ids, list):
-            job_ids = [job_ids]
-
-        # Decide once at the start
+        # Decide once at the start which update function to use
         if poll_callback:
             update_fn = poll_callback
         elif verbose:
@@ -370,55 +501,31 @@ class QoroService(CircuitRunner):
             RESET = "\033[0m"
 
             update_fn = lambda retry_count, status: logger.info(
-                rf"Job {CYAN}{job_ids[0].split('-')[0]}{RESET} is {status}. Polling attempt {retry_count} / {self.max_retries}\r",
+                rf"Job {CYAN}{job_id.split('-')[0]}{RESET} is {status}. Polling attempt {retry_count} / {self.max_retries}\r",
                 extra={"append": True},
             )
         else:
             update_fn = lambda _, __: None
 
         if not loop_until_complete:
-            statuses = [
-                self._make_request(
-                    "get",
-                    f"job/{job_id}/status/",
-                    timeout=200,
-                ).json()["status"]
-                for job_id in job_ids
-            ]
-            return statuses if len(statuses) > 1 else statuses[0]
-
-        pending_job_ids = set(job_ids)
-        responses = []
+            response = self._make_request("get", f"job/{job_id}/status/", timeout=200)
+            return response.json()["status"]
+
         for retry_count in range(1, self.max_retries + 1):
-            # Exit early if all jobs are done
-            if not pending_job_ids:
-                break
-
-            for job_id in list(pending_job_ids):
-                response = self._make_request(
-                    "get",
-                    f"job/{job_id}/status/",
-                    timeout=200,
-                )
-
-                if response.json()["status"] in (
-                    JobStatus.COMPLETED.value,
-                    JobStatus.FAILED.value,
-                ):
-                    pending_job_ids.remove(job_id)
-                    responses.append(response)
-
-            # Exit before sleeping if no jobs are pending
-            if not pending_job_ids:
-                break
+            response = self._make_request("get", f"job/{job_id}/status/", timeout=200)
+            status = response.json()["status"]
 
-            time.sleep(self.polling_interval)
+            if status == JobStatus.COMPLETED.value:
+                if on_complete:
+                    on_complete(response)
+                return JobStatus.COMPLETED
 
-            update_fn(retry_count, response.json()["status"])
+            if status == JobStatus.FAILED.value:
+                if on_complete:
+                    on_complete(response)
+                return JobStatus.FAILED
 
-        if not pending_job_ids:
-            if on_complete:
-                on_complete(responses)
-            return JobStatus.COMPLETED
-        else:
-            raise MaxRetriesReachedError(retry_count)
+            update_fn(retry_count, status)
+            time.sleep(self.polling_interval)
+
+        raise MaxRetriesReachedError(self.max_retries)

divi/circuits/_core.py

@@ -20,6 +20,20 @@ TRANSFORM_PROGRAM.add_transform(qml.transforms.split_non_commuting)
 
 
 class Circuit:
+    """
+    Represents a quantum circuit with its QASM representation and metadata.
+
+    This class encapsulates a PennyLane quantum circuit along with its OpenQASM
+    serialization and associated tags for identification. Each circuit instance
+    is assigned a unique ID for tracking purposes.
+
+    Attributes:
+        main_circuit: The PennyLane quantum circuit/tape object.
+        tags (list[str]): List of string tags for circuit identification.
+        qasm_circuits (list[str]): List of OpenQASM string representations.
+        circuit_id (int): Unique identifier for this circuit instance.
+    """
+
     _id_counter = 0
 
     def __init__(
@@ -28,6 +42,16 @@ class Circuit:
         tags: list[str],
         qasm_circuits: list[str] = None,
     ):
+        """
+        Initialize a Circuit instance.
+
+        Args:
+            main_circuit: A PennyLane quantum circuit or tape object to be wrapped.
+            tags (list[str]): List of string tags for identifying this circuit.
+            qasm_circuits (list[str], optional): Pre-computed OpenQASM string
+                representations. If None, they will be generated from main_circuit.
+                Defaults to None.
+        """
         self.main_circuit = main_circuit
         self.tags = tags
 
@@ -44,10 +68,33 @@ class Circuit:
         Circuit._id_counter += 1
 
     def __str__(self):
+        """
+        Return a string representation of the circuit.
+
+        Returns:
+            str: String in format "Circuit: {circuit_id}".
+        """
         return f"Circuit: {self.circuit_id}"
 
 
 class MetaCircuit:
+    """
+    A parameterized quantum circuit template for batch circuit generation.
+
+    MetaCircuit represents a symbolic quantum circuit that can be instantiated
+    multiple times with different parameter values. It handles circuit compilation,
+    observable grouping, and measurement decomposition for efficient execution.
+
+    Attributes:
+        main_circuit: The PennyLane quantum circuit with symbolic parameters.
+        symbols: Array of sympy symbols used as circuit parameters.
+        qem_protocol (QEMProtocol): Quantum error mitigation protocol to apply.
+        compiled_circuits_bodies (list[str]): QASM bodies without measurements.
+        measurements (list[str]): QASM measurement strings.
+        measurement_groups (list[list]): Grouped observables for each circuit variant.
+        postprocessing_fn: Function to combine measurement results.
+    """
+
     def __init__(
         self,
         main_circuit,
@@ -55,6 +102,18 @@ class MetaCircuit:
         grouping_strategy: Literal["wires", "default", "qwc"] | None = None,
         qem_protocol: QEMProtocol | None = None,
     ):
+        """
+        Initialize a MetaCircuit with symbolic parameters.
+
+        Args:
+            main_circuit: A PennyLane quantum circuit/tape with symbolic parameters.
+            symbols: Array of sympy Symbol objects representing circuit parameters.
+            grouping_strategy (str, optional): Strategy for grouping commuting
+                observables. Options are "wires", "default", or "qwc" (qubit-wise
+                commuting). Defaults to None.
+            qem_protocol (QEMProtocol, optional): Quantum error mitigation protocol
+                to apply to the circuits. Defaults to None.
+        """
         self.main_circuit = main_circuit
         self.symbols = symbols
         self.qem_protocol = qem_protocol
@@ -81,11 +140,30 @@ class MetaCircuit:
         ]
 
     def __getstate__(self):
+        """
+        Prepare the MetaCircuit for pickling.
+
+        Serializes the postprocessing function using dill since regular pickle
+        cannot handle certain PennyLane function objects.
+
+        Returns:
+            dict: State dictionary with serialized postprocessing function.
+        """
         state = self.__dict__.copy()
         state["postprocessing_fn"] = dill.dumps(self.postprocessing_fn)
         return state
 
     def __setstate__(self, state):
+        """
+        Restore the MetaCircuit from a pickled state.
+
+        Deserializes the postprocessing function that was serialized with dill
+        during pickling.
+
+        Args:
+            state (dict): State dictionary from pickling with serialized
+                postprocessing function.
+        """
         state["postprocessing_fn"] = dill.loads(state["postprocessing_fn"])
 
         self.__dict__.update(state)
@@ -93,6 +171,29 @@ class MetaCircuit:
     def initialize_circuit_from_params(
         self, param_list, tag_prefix: str = "", precision: int = 8
     ) -> Circuit:
+        """
+        Instantiate a concrete Circuit by substituting symbolic parameters with values.
+
+        Takes a list of parameter values and creates a fully instantiated Circuit
+        by replacing all symbolic parameters in the QASM representations with their
+        concrete numerical values.
+
+        Args:
+            param_list: Array of numerical parameter values to substitute for symbols.
+                Must match the length and order of self.symbols.
+            tag_prefix (str, optional): Prefix to prepend to circuit tags for
+                identification. Defaults to "".
+            precision (int, optional): Number of decimal places for parameter values
+                in the QASM output. Defaults to 8.
+
+        Returns:
+            Circuit: A new Circuit instance with parameters substituted and proper
+                tags for identification.
+
+        Note:
+            The main_circuit attribute in the returned Circuit still contains
+            symbolic parameters. Only the QASM representations have concrete values.
+        """
         mapping = dict(
             zip(
                 map(lambda x: re.escape(str(x)), self.symbols),

divi/circuits/qasm.py

@@ -46,6 +46,25 @@ OPENQASM_GATES = {
 
 
 def _ops_to_qasm(operations, precision, wires):
+    """
+    Convert PennyLane operations to OpenQASM instruction strings.
+
+    Translates a sequence of PennyLane quantum operations into their OpenQASM
+    2.0 equivalent representations. Each operation is mapped to its corresponding
+    QASM gate with appropriate parameters and wire labels.
+
+    Args:
+        operations: Sequence of PennyLane operation objects to convert.
+        precision (int | None): Number of decimal places for parameter values.
+            If None, uses default Python string formatting.
+        wires: Wire labels used in the circuit for indexing.
+
+    Returns:
+        str: OpenQASM instruction string with each operation on a new line.
+
+    Raises:
+        ValueError: If an operation is not supported by the QASM serializer.
+    """
     # create the QASM code representing the operations
     qasm_str = ""