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

divi/backends/_qpu_system.py

@@ -2,11 +2,26 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-from dataclasses import dataclass
+"""Data models for Quantum Processing Units (QPUs) and QPUSystems."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+
+_AVAILABLE_QPU_SYSTEMS: dict[str, QPUSystem] = {}
 
 
 @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
@@ -15,6 +30,65 @@ class QPU:
 
 @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]
-    access_level: 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."""
+    _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.
+    """
+    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."""
+    return list(_AVAILABLE_QPU_SYSTEMS.values())

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,29 +68,83 @@ 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,
         symbols,
-        grouping_strategy: Literal["wires", "default", "qwc"] | None = None,
+        grouping_strategy: (
+            Literal["wires", "default", "qwc", "_backend_expval"] | 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). If the backend supports expectation value measurements,
+                "_backend_expval" to place all observables in the same measurement group.
+                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
+        self.grouping_strategy = grouping_strategy
+
+        # --- VQE Optimization ---
+        # Create a lightweight tape with only measurements to avoid deep-copying
+        # the circuit's operations inside the split_non_commuting transform.
+        measurements_only_tape = qml.tape.QuantumScript(
+            measurements=self.main_circuit.measurements
+        )
 
         transform_program = deepcopy(TRANSFORM_PROGRAM)
-        transform_program[1].kwargs["grouping_strategy"] = grouping_strategy
+        transform_program[1].kwargs["grouping_strategy"] = (
+            None if grouping_strategy == "_backend_expval" else grouping_strategy
+        )
+        # Run the transform on the lightweight tape
+        qscripts, self.postprocessing_fn = transform_program((measurements_only_tape,))
 
-        qscripts, self.postprocessing_fn = transform_program((main_circuit,))
+        if grouping_strategy == "_backend_expval":
+            wrapped_measurements_groups = [[]]
+        else:
+            wrapped_measurements_groups = [qsc.measurements for qsc in qscripts]
 
         self.compiled_circuits_bodies, self.measurements = to_openqasm(
             main_circuit,
-            measurement_groups=[qsc.measurements for qsc in qscripts],
+            measurement_groups=wrapped_measurements_groups,
             return_measurements_separately=True,
             # TODO: optimize later
             measure_all=True,
@@ -81,11 +159,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 +190,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 = ""
 
@@ -196,9 +215,7 @@ def to_openqasm(
             for wire in range(len(wires)):
                 measure_qasm_str += f"measure q[{wire}] -> c[{wire}];\n"
         else:
-            measured_wires = Wires.all_wires(
-                [m.wires for m in main_qscript.measurements]
-            )
+            measured_wires = Wires.all_wires([m.wires for m in meas_group])
 
             for w in measured_wires:
                 wire_indx = main_qscript.wires.index(w)

divi/extern/cirq/_validator.py

@@ -639,9 +639,18 @@ def validate_qasm_raise(src: str) -> None:
     Parser(toks).parse()
 
 
-def is_valid_qasm(src: str) -> bool | str:
+def validate_qasm_count_qubits(src: str) -> int:
+    """Validate QASM and return the total number of qubits."""
+    toks = _lex(src)
+    parser = Parser(toks)
+    parser.parse()
+    # Sum all qubit register sizes to get total qubit count
+    return sum(parser.qregs.values())
+
+
+def is_valid_qasm(src: str) -> int | str:
+    """Validate QASM and return the number of qubits if valid, or error message if invalid."""
     try:
-        validate_qasm_raise(src)
-        return True
+        return validate_qasm_count_qubits(src)
     except SyntaxError as e:
         return str(e)

divi/qprog/__init__.py

@@ -4,6 +4,7 @@
 
 # isort: skip_file
 from .quantum_program import QuantumProgram
+from .variational_quantum_algorithm import VariationalQuantumAlgorithm
 from .batch import ProgramBatch
 from .algorithms import (
     QAOA,

divi/qprog/algorithms/_ansatze.py

@@ -11,7 +11,7 @@ import pennylane as qml
 
 
 class Ansatz(ABC):
-    """Abstract base class for all VQE ansaetze."""
+    """Abstract base class for all VQE ansätze."""
 
     @property
     def name(self) -> str:
@@ -25,15 +25,17 @@ class Ansatz(ABC):
         raise NotImplementedError
 
     @abstractmethod
-    def build(self, params, n_qubits: int, n_layers: int, **kwargs):
+    def build(self, params, n_qubits: int, n_layers: int, **kwargs) -> None:
         """
-        Builds the ansatz circuit.
+        Builds the ansatz circuit by adding operations to the active PennyLane
+        quantum function context.
 
-        Args:
-            params (array): The parameters (weights) for the ansatz.
-            n_qubits (int): The number of qubits.
-            n_layers (int): The number of layers.
-            **kwargs: Additional arguments like n_electrons for chemistry ansaetze.
+        Note: This method is called within a PennyLane quantum function context
+        (qml.qnode or qml.tape.make_qscript). Operations are added via side effects
+        to the active quantum tape/script.
+
+        Returns:
+            None: Operations are added to the active PennyLane context
         """
         raise NotImplementedError
 
@@ -118,7 +120,7 @@ class GenericLayerAnsatz(Ansatz):
         per_qubit = sum(getattr(g, "num_params", 1) for g in self.gate_sequence)
         return per_qubit * n_qubits
 
-    def build(self, params, n_qubits: int, n_layers: int, **kwargs):
+    def build(self, params, n_qubits: int, n_layers: int, **kwargs) -> None:
         # calculate how many params each gate needs per qubit
         gate_param_counts = [getattr(g, "num_params", 1) for g in self.gate_sequence]
         per_qubit = sum(gate_param_counts)
@@ -143,11 +145,37 @@ class GenericLayerAnsatz(Ansatz):
 
 
 class QAOAAnsatz(Ansatz):
+    """
+    QAOA-style ansatz using PennyLane's QAOAEmbedding.
+
+    Implements a parameterized ansatz based on the Quantum Approximate Optimization
+    Algorithm structure, alternating between problem and mixer Hamiltonians.
+    """
+
     @staticmethod
     def n_params_per_layer(n_qubits: int, **kwargs) -> int:
+        """
+        Calculate the number of parameters per layer for QAOA ansatz.
+
+        Args:
+            n_qubits (int): Number of qubits in the circuit.
+            **kwargs: Additional unused arguments.
+
+        Returns:
+            int: Number of parameters needed per layer.
+        """
         return qml.QAOAEmbedding.shape(n_layers=1, n_wires=n_qubits)[1]
 
-    def build(self, params, n_qubits: int, n_layers: int, **kwargs):
+    def build(self, params, n_qubits: int, n_layers: int, **kwargs) -> None:
+        """
+        Build the QAOA ansatz circuit.
+
+        Args:
+            params: Parameter array to use for the ansatz.
+            n_qubits (int): Number of qubits.
+            n_layers (int): Number of QAOA layers.
+            **kwargs: Additional unused arguments.
+        """
         qml.QAOAEmbedding(
             features=[],
             weights=params.reshape(n_layers, -1),
@@ -156,11 +184,23 @@ class QAOAAnsatz(Ansatz):
 
 
 class HardwareEfficientAnsatz(Ansatz):
+    """
+    Hardware-efficient ansatz (not yet implemented).
+
+    This ansatz is designed to be easily implementable on near-term quantum hardware,
+    typically using native gate sets and connectivity patterns.
+
+    Note:
+        This class is a placeholder for future implementation.
+    """
+
     @staticmethod
     def n_params_per_layer(n_qubits: int, **kwargs) -> int:
+        """Not yet implemented."""
         raise NotImplementedError("HardwareEfficientAnsatz is not yet implemented.")
 
     def build(self, params, n_qubits: int, n_layers: int, **kwargs) -> None:
+        """Not yet implemented."""
         raise NotImplementedError("HardwareEfficientAnsatz is not yet implemented.")
 
 
@@ -168,13 +208,43 @@ class HardwareEfficientAnsatz(Ansatz):
 
 
 class UCCSDAnsatz(Ansatz):
+    """
+    Unitary Coupled Cluster Singles and Doubles (UCCSD) ansatz.
+
+    This ansatz is specifically designed for quantum chemistry calculations,
+    implementing the UCCSD approximation which includes all single and double
+    electron excitations from a reference state.
+    """
+
     @staticmethod
     def n_params_per_layer(n_qubits: int, n_electrons: int, **kwargs) -> int:
+        """
+        Calculate the number of parameters per layer for UCCSD ansatz.
+
+        Args:
+            n_qubits (int): Number of qubits in the circuit.
+            n_electrons (int): Number of electrons in the system.
+            **kwargs: Additional unused arguments.
+
+        Returns:
+            int: Number of parameters (number of single + double excitations).
+        """
         singles, doubles = qml.qchem.excitations(n_electrons, n_qubits)
         s_wires, d_wires = qml.qchem.excitations_to_wires(singles, doubles)
         return len(s_wires) + len(d_wires)
 
-    def build(self, params, n_qubits: int, n_layers: int, n_electrons: int, **kwargs):
+    def build(self, params, n_qubits: int, n_layers: int, **kwargs) -> None:
+        """
+        Build the UCCSD ansatz circuit.
+
+        Args:
+            params: Parameter array for excitation amplitudes.
+            n_qubits (int): Number of qubits.
+            n_layers (int): Number of UCCSD layers (repeats).
+            **kwargs: Additional arguments:
+                n_electrons (int): Number of electrons in the system (required).
+        """
+        n_electrons = kwargs.pop("n_electrons")
         singles, doubles = qml.qchem.excitations(n_electrons, n_qubits)
         s_wires, d_wires = qml.qchem.excitations_to_wires(singles, doubles)
         hf_state = qml.qchem.hf_state(n_electrons, n_qubits)
@@ -190,12 +260,42 @@ class UCCSDAnsatz(Ansatz):
 
 
 class HartreeFockAnsatz(Ansatz):
+    """
+    Hartree-Fock-based ansatz for quantum chemistry.
+
+    This ansatz prepares the Hartree-Fock reference state and applies
+    parameterized single and double excitation gates. It's a simplified
+    alternative to UCCSD, often used as a starting point for VQE calculations.
+    """
+
     @staticmethod
     def n_params_per_layer(n_qubits: int, n_electrons: int, **kwargs) -> int:
+        """
+        Calculate the number of parameters per layer for Hartree-Fock ansatz.
+
+        Args:
+            n_qubits (int): Number of qubits in the circuit.
+            n_electrons (int): Number of electrons in the system.
+            **kwargs: Additional unused arguments.
+
+        Returns:
+            int: Number of parameters (number of single + double excitations).
+        """
         singles, doubles = qml.qchem.excitations(n_electrons, n_qubits)
         return len(singles) + len(doubles)
 
-    def build(self, params, n_qubits: int, n_layers: int, n_electrons: int, **kwargs):
+    def build(self, params, n_qubits: int, n_layers: int, **kwargs) -> None:
+        """
+        Build the Hartree-Fock ansatz circuit.
+
+        Args:
+            params: Parameter array for excitation amplitudes.
+            n_qubits (int): Number of qubits.
+            n_layers (int): Number of ansatz layers.
+            **kwargs: Additional arguments:
+                n_electrons (int): Number of electrons in the system (required).
+        """
+        n_electrons = kwargs.pop("n_electrons")
         singles, doubles = qml.qchem.excitations(n_electrons, n_qubits)
         hf_state = qml.qchem.hf_state(n_electrons, n_qubits)