qoro-divi 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

divi/backends/__init__.py

@@ -1,7 +1,8 @@
-# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+# SPDX-FileCopyrightText: 2025-2026 Qoro Quantum Ltd <divi@qoroquantum.de>
 #
 # SPDX-License-Identifier: Apache-2.0
 
+from ._backend_properties_conversion import create_backend_from_properties
 from ._circuit_runner import CircuitRunner
 from ._execution_result import ExecutionResult
 from ._parallel_simulator import ParallelSimulator

divi/backends/_backend_properties_conversion.py

@@ -0,0 +1,227 @@
+# SPDX-FileCopyrightText: 2025-2026 Qoro Quantum Ltd <divi@qoroquantum.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Utilities for working with Qiskit BackendProperties and BackendV2 conversion."""
+
+import datetime
+from typing import Any
+
+from qiskit.providers.fake_provider import GenericBackendV2
+from qiskit_ibm_runtime.models.backend_properties import BackendProperties
+
+
+def _normalize_properties(
+    properties: dict[str, Any],
+    default_date: datetime.datetime | None = None,
+) -> dict[str, Any]:
+    """
+    Preprocess an incomplete BackendProperties dictionary by filling in missing
+    required fields with sensible defaults.
+
+    This function makes it easier to create BackendProperties dictionaries by
+    allowing you to omit fields that have obvious defaults, such as:
+    - Missing top-level fields: `backend_name`, `backend_version`, `last_update_date`
+    - Missing `unit` field for dimensionless parameters (e.g., gate_error)
+    - Missing `general` field (empty list)
+    - Missing `gates` field (empty list)
+    - Missing `qubits` field (empty list)
+    - Missing `date` fields in Nduv objects
+
+    Args:
+        properties: Incomplete BackendProperties dictionary. Can omit:
+            - `unit` field in parameter/qubit Nduv objects (defaults to "" for
+              dimensionless quantities like gate_error, or inferred from name)
+            - `general` field (defaults to empty list)
+            - `gates` field (defaults to empty list)
+            - `qubits` field (defaults to empty list)
+            - `date` field in Nduv objects (defaults to current time or provided default)
+        default_date: Optional datetime to use for missing date fields.
+            If None, uses current time.
+
+    Returns:
+        Complete BackendProperties dictionary ready for BackendProperties.from_dict()
+
+    Example:
+        >>> props = {
+        ...     "backend_name": "test",
+        ...     "gates": [{
+        ...         "gate": "sx",
+        ...         "qubits": [0],
+        ...         "parameters": [{
+        ...             "name": "gate_error",
+        ...             "value": 0.01,
+        ...             # unit and date will be added automatically
+        ...         }]
+        ...     }]
+        ... }
+        >>> normalized = _normalize_properties(props)
+        >>> backend_props = BackendProperties.from_dict(normalized)
+    """
+    if default_date is None:
+        default_date = datetime.datetime.now()
+
+    # Create a shallow copy to avoid mutating the input
+    # (nested structures are rebuilt below to ensure no mutation)
+    normalized = properties.copy()
+
+    # Add missing required top-level fields
+    if "backend_name" not in normalized:
+        normalized["backend_name"] = "custom_backend"
+    if "backend_version" not in normalized:
+        normalized["backend_version"] = "1.0.0"
+    if "last_update_date" not in normalized:
+        normalized["last_update_date"] = default_date
+
+    # Add missing general field
+    if "general" not in normalized:
+        normalized["general"] = []
+
+    # Add missing gates field (required by BackendProperties)
+    if "gates" not in normalized:
+        normalized["gates"] = []
+
+    # Add missing qubits field (required by BackendProperties)
+    if "qubits" not in normalized:
+        normalized["qubits"] = []
+
+    # Normalize qubits (list of lists of Nduv objects)
+    if "qubits" in normalized:
+        normalized["qubits"] = [
+            [_normalize_nduv(param, default_date) for param in qubit_params]
+            for qubit_params in normalized["qubits"]
+        ]
+
+    # Normalize gates (list of gate dicts with parameters)
+    if "gates" in normalized:
+        normalized["gates"] = [
+            {
+                **gate,
+                "parameters": [
+                    _normalize_nduv(param, default_date)
+                    for param in gate.get("parameters", [])
+                ],
+            }
+            for gate in normalized["gates"]
+        ]
+
+    # Normalize general (list of Nduv objects)
+    if "general" in normalized and normalized["general"]:
+        normalized["general"] = [
+            _normalize_nduv(param, default_date) for param in normalized["general"]
+        ]
+
+    return normalized
+
+
+def _normalize_nduv(
+    nduv: dict[str, Any], default_date: datetime.datetime
+) -> dict[str, Any]:
+    """
+    Normalize a single Nduv (Name, Date, Unit, Value) object by adding
+    missing required fields.
+
+    Args:
+        nduv: Nduv dictionary (may be incomplete)
+        default_date: Default date to use if missing
+
+    Returns:
+        Complete Nduv dictionary
+    """
+    normalized = nduv.copy()
+
+    # Add missing date field
+    if "date" not in normalized:
+        normalized["date"] = default_date
+
+    # Add missing unit field
+    if "unit" not in normalized:
+        name = normalized.get("name", "").lower()
+        # Dimensionless quantities
+        if name in ("gate_error", "readout_error", "prob"):
+            normalized["unit"] = ""
+        # Time-based quantities
+        elif name in ("t1", "t2", "gate_length", "readout_length"):
+            # Infer unit from common patterns, default to "ns" for gate_length
+            if name == "gate_length":
+                normalized["unit"] = "ns"
+            elif name in ("t1", "t2"):
+                normalized["unit"] = "us"  # microseconds is common
+            else:
+                normalized["unit"] = "ns"
+        # Frequency-based quantities
+        elif name in ("frequency", "freq"):
+            normalized["unit"] = "GHz"
+        # Default to empty string for unknown quantities
+        else:
+            normalized["unit"] = ""
+
+    return normalized
+
+
+def create_backend_from_properties(
+    properties: dict[str, Any],
+    n_qubits: int | None = None,
+    default_date: datetime.datetime | None = None,
+) -> GenericBackendV2:
+    """
+    Create a populated GenericBackendV2 from a BackendProperties dictionary.
+
+    This function handles the complete workflow:
+    1. Normalizes the properties dictionary (fills in missing fields)
+    2. Infers the number of qubits from the properties if not provided
+    3. Creates a GenericBackendV2 backend
+    4. Populates it with the normalized properties
+
+    Args:
+        properties: BackendProperties dictionary.
+            Missing fields will be filled automatically.
+        n_qubits: Optional number of qubits. If None, will be inferred from the
+            length of the "qubits" list in the properties dictionary.
+        default_date: Optional datetime to use for missing date fields.
+            If None, uses current time.
+
+    Returns:
+        GenericBackendV2 backend populated with the provided properties.
+
+    Raises:
+        ValueError: If n_qubits is not provided and cannot be inferred from properties
+            (i.e., qubits list is empty or missing), or if n_qubits is less than 1.
+
+    Example:
+        >>> props = {
+        ...     "backend_name": "test",
+        ...     "qubits": [[{"name": "T1", "value": 100.0}]],  # 1 qubit
+        ...     "gates": [{"gate": "sx", "qubits": [0], "parameters": []}]
+        ... }
+        >>> # Infer qubit count from properties (will be 1)
+        >>> backend = create_backend_from_properties(props)
+        >>> backend.n_qubits
+        1
+        >>> # Override qubit count if needed
+        >>> backend_large = create_backend_from_properties(props, n_qubits=120)
+        >>> backend_large.n_qubits
+        120
+    """
+    # Normalize the properties first
+    normalized_properties = _normalize_properties(properties, default_date)
+
+    # Infer number of qubits from qubits list length if not provided
+    if n_qubits is None:
+        n_qubits = len(normalized_properties.get("qubits", []))
+        if n_qubits == 0:
+            raise ValueError(
+                "n_qubits must be provided when properties dictionary has no qubits, "
+                "or qubits list must contain at least one qubit"
+            )
+
+    if n_qubits < 1:
+        raise ValueError("n_qubits must be at least 1")
+
+    # Create the backend
+    backend = GenericBackendV2(num_qubits=n_qubits)
+
+    # Populate with properties
+    backend._properties = BackendProperties.from_dict(normalized_properties)
+
+    return backend

divi/backends/_parallel_simulator.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+# SPDX-FileCopyrightText: 2025-2026 Qoro Quantum Ltd <divi@qoroquantum.de>
 #
 # SPDX-License-Identifier: Apache-2.0
 
@@ -16,6 +16,7 @@ from qiskit import QuantumCircuit, transpile
 from qiskit.converters import circuit_to_dag
 from qiskit.dagcircuit import DAGOpNode
 from qiskit.providers import Backend
+from qiskit.transpiler.exceptions import TranspilerError
 from qiskit_aer import AerSimulator
 from qiskit_aer.noise import NoiseModel
 
@@ -270,7 +271,7 @@ class ParallelSimulator(CircuitRunner):
             circuit_simulator = self._create_simulator(resolved_backend)
 
             if self.simulation_seed is not None:
-                circuit_simulator.set_option("seed_simulator", self.simulation_seed)
+                circuit_simulator.set_options(seed_simulator=self.simulation_seed)
 
             # Run the single circuit
             job = circuit_simulator.run(transpiled_circuit, shots=self.shots)
@@ -421,7 +422,7 @@ class ParallelSimulator(CircuitRunner):
         )
 
         total_run_time_s = 0.0
-        durations = resolved_backend.instruction_durations
+        durations = resolved_backend.target.durations()
 
         for node in circuit_to_dag(transpiled_circuit).longest_path():
             if not isinstance(node, DAGOpNode) or not node.num_qubits:
@@ -429,10 +430,9 @@ class ParallelSimulator(CircuitRunner):
 
             try:
                 idx = tuple(q._index for q in node.qargs)
-                total_run_time_s += durations.duration_by_name_qubits[(node.name, idx)][
-                    0
-                ]
-            except KeyError:
+                duration = durations.get(node.name, idx, unit="s")
+                total_run_time_s += duration
+            except TranspilerError:
                 if node.name != "barrier":
                     warn(f"Instruction duration not found: {node.name}")
 

divi/circuits/__init__.py

@@ -1,8 +1,13 @@
-# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+# SPDX-FileCopyrightText: 2025-2026 Qoro Quantum Ltd <divi@qoroquantum.de>
 #
 # SPDX-License-Identifier: Apache-2.0
 
-# isort: skip_file
 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
+from ._core import (
+    CircuitBundle,
+    ExecutableQASMCircuit,
+    MetaCircuit,
+    CircuitTag,
+    format_circuit_tag,
+)

divi/circuits/_core.py

@@ -1,11 +1,12 @@
-# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+# SPDX-FileCopyrightText: 2025-2026 Qoro Quantum Ltd <divi@qoroquantum.de>
 #
 # SPDX-License-Identifier: Apache-2.0
 
 import re
+from collections.abc import Callable
 from dataclasses import dataclass, field
 from itertools import product
-from typing import Callable, Literal
+from typing import Literal, NamedTuple
 
 import dill
 import numpy as np
@@ -96,11 +97,25 @@ def _create_final_postprocessing_fn(coefficients, partition_indices, num_total_o
     return final_postprocessing_fn
 
 
+class CircuitTag(NamedTuple):
+    """Structured tag for identifying circuit executions."""
+
+    param_id: int
+    qem_name: str
+    qem_id: int
+    meas_id: int
+
+
+def format_circuit_tag(tag: CircuitTag) -> str:
+    """Format a CircuitTag into its wire-safe string representation."""
+    return f"{tag.param_id}_{tag.qem_name}:{tag.qem_id}_{tag.meas_id}"
+
+
 @dataclass(frozen=True)
 class ExecutableQASMCircuit:
     """Represents a single, executable QASM circuit with its associated tag."""
 
-    tag: str
+    tag: CircuitTag
     qasm: str
 
 
@@ -129,7 +144,7 @@ class CircuitBundle:
         return f"CircuitBundle ({len(self.executables)} executables)"
 
     @property
-    def tags(self) -> list[str]:
+    def tags(self) -> list[CircuitTag]:
         """A list of tags for all executables in the bundle."""
         return [e.tag for e in self.executables]
 
@@ -312,7 +327,10 @@ class MetaCircuit:
         self.__dict__.update(state)
 
     def initialize_circuit_from_params(
-        self, param_list, tag_prefix: str = "", precision: int | None = None
+        self,
+        param_list: npt.NDArray[np.floating] | list[float],
+        param_idx: int = 0,
+        precision: int | None = None,
     ) -> CircuitBundle:
         """
         Instantiate a concrete CircuitBundle by substituting symbolic parameters with values.
@@ -322,10 +340,11 @@ class MetaCircuit:
         concrete numerical values.
 
         Args:
-            param_list: Array of numerical parameter values to substitute for symbols.
+            param_list (npt.NDArray[np.floating] | list[float]): 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 "".
+            param_idx (int, optional): Parameter set index used for structured tags.
+                Defaults to 0.
             precision (int | None, optional): Number of decimal places for parameter values
                 in the QASM output. If None, uses the precision set on this MetaCircuit instance.
                 Defaults to None.
@@ -354,16 +373,19 @@ class MetaCircuit:
         ]
 
         executables = []
+        param_id = param_idx
         for (i, body_str), (j, meas_str) in product(
             enumerate(final_qasm_bodies), enumerate(self._measurements)
         ):
             qasm_circuit = body_str + meas_str
-            tag_parts = [tag_prefix]
-            if self.qem_protocol:
-                tag_parts.append(f"{self.qem_protocol.name}:{i}")
-            tag_parts.append(str(j))
-
-            tag = "_".join(filter(None, tag_parts))
+            tag = CircuitTag(
+                param_id=param_id,
+                qem_name=(
+                    self.qem_protocol.name if self.qem_protocol else "NoMitigation"
+                ),
+                qem_id=i,
+                meas_id=j,
+            )
             executables.append(ExecutableQASMCircuit(tag=tag, qasm=qasm_circuit))
 
         return CircuitBundle(executables=tuple(executables))

divi/qprog/__init__.py

@@ -1,15 +1,16 @@
-# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+# SPDX-FileCopyrightText: 2025-2026 Qoro Quantum Ltd <divi@qoroquantum.de>
 #
 # SPDX-License-Identifier: Apache-2.0
 
-# isort: skip_file
 from .quantum_program import QuantumProgram
-from .variational_quantum_algorithm import VariationalQuantumAlgorithm
+from .variational_quantum_algorithm import VariationalQuantumAlgorithm, SolutionEntry
 from .batch import ProgramBatch
 from .algorithms import (
     QAOA,
     GraphProblem,
     VQE,
+    PCE,
+    CustomVQA,
     Ansatz,
     UCCSDAnsatz,
     QAOAAnsatz,

divi/qprog/algorithms/__init__.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+# SPDX-FileCopyrightText: 2025-2026 Qoro Quantum Ltd <divi@qoroquantum.de>
 #
 # SPDX-License-Identifier: Apache-2.0
 
@@ -10,5 +10,7 @@ from ._ansatze import (
     QAOAAnsatz,
     UCCSDAnsatz,
 )
-from ._qaoa import QAOA, GraphProblem, GraphProblemTypes, QUBOProblemTypes
+from ._custom_vqa import CustomVQA
+from ._qaoa import QAOA, GraphProblem
 from ._vqe import VQE
+from ._pce import PCE

divi/qprog/algorithms/_ansatze.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
+# SPDX-FileCopyrightText: 2025-2026 Qoro Quantum Ltd <divi@qoroquantum.de>
 #
 # SPDX-License-Identifier: Apache-2.0
 
@@ -10,6 +10,15 @@ from warnings import warn
 import pennylane as qml
 
 
+def _require_trainable_params(n_params: int, ansatz_name: str) -> int:
+    if n_params <= 0:
+        raise ValueError(
+            f"{ansatz_name} must define at least one trainable parameter. "
+            "Parameter-free circuits are not supported."
+        )
+    return n_params
+
+
 class Ansatz(ABC):
     """Abstract base class for all VQE ansätze."""
 
@@ -99,7 +108,7 @@ class GenericLayerAnsatz(Ansatz):
                 self._layout_fn = lambda n_qubits: zip(
                     range(n_qubits), [(i + 1) % n_qubits for i in range(n_qubits)]
                 )
-            case "all_to_all":
+            case "all-to-all":
                 self._layout_fn = lambda n_qubits: (
                     (i, j) for i in range(n_qubits) for j in range(i + 1, n_qubits)
                 )
@@ -121,7 +130,7 @@ class GenericLayerAnsatz(Ansatz):
     def n_params_per_layer(self, n_qubits: int, **kwargs) -> int:
         """Total parameters = sum of gate.num_params per qubit per layer."""
         per_qubit = sum(getattr(g, "num_params", 1) for g in self.gate_sequence)
-        return per_qubit * n_qubits
+        return _require_trainable_params(per_qubit * n_qubits, self.name)
 
     def build(
         self, params, n_qubits: int, n_layers: int, **kwargs
@@ -182,7 +191,8 @@ class QAOAAnsatz(Ansatz):
         Returns:
             int: Number of parameters needed per layer.
         """
-        return qml.QAOAEmbedding.shape(n_layers=1, n_wires=n_qubits)[1]
+        n_params = qml.QAOAEmbedding.shape(n_layers=1, n_wires=n_qubits)[1]
+        return _require_trainable_params(n_params, QAOAAnsatz.__name__)
 
     def build(
         self, params, n_qubits: int, n_layers: int, **kwargs
@@ -257,7 +267,8 @@ class UCCSDAnsatz(Ansatz):
         """
         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)
+        n_params = len(s_wires) + len(d_wires)
+        return _require_trainable_params(n_params, UCCSDAnsatz.__name__)
 
     def build(
         self, params, n_qubits: int, n_layers: int, **kwargs
@@ -313,7 +324,8 @@ class HartreeFockAnsatz(Ansatz):
             int: Number of parameters (number of single + double excitations).
         """
         singles, doubles = qml.qchem.excitations(n_electrons, n_qubits)
-        return len(singles) + len(doubles)
+        n_params = len(singles) + len(doubles)
+        return _require_trainable_params(n_params, HartreeFockAnsatz.__name__)
 
     def build(
         self, params, n_qubits: int, n_layers: int, **kwargs