openqml 0.3.0a8__py3-none-any.whl

openqml/__init__.py

@@ -0,0 +1,161 @@
+"""Hybrid quantum learning and explicit circuit interoperability.
+
+Import once as ``import openqml as oq``. Optional integrations are available
+through ``oq.torch``, ``oq.jax`` and ``oq.flax`` and load only when accessed.
+"""
+
+from importlib import import_module as _import_module
+
+from ._scheduling import ExecutionBatch, ReadoutRoute
+from .adjoint import AdjointPlan, adjoint_jvp, adjoint_vjp
+from .aer import AerBackend
+from .backends import (
+    BackendCapabilities,
+    DensityMatrixBackend,
+    ExecutionOptions,
+    ExpectationBackend,
+    SamplingBackend,
+    StatevectorBackend,
+    get_backend,
+    list_backends,
+    register_backend,
+    unregister_backend,
+)
+from .batch import execute_batch, expectations_batch
+from .compiler import CircuitStats, circuit_stats, decompose, inverse, simplify
+from .conversion import ConversionPlan, ConversionResult, convert, diagnose, plan_conversion
+from .density import density_matrix
+from .errors import (
+    BackendError,
+    ConversionError,
+    Diagnostic,
+    MissingDependencyError,
+    OpenQMLError,
+    ResourceError,
+    ValidationError,
+)
+from .execution import ExecutionGroup, ExpectationCheck, ExpectationPlan
+from .frontends import FrameworkAdapter, list_formats, register_adapter, unregister_adapter
+from .gradients import (
+    parameter_shift,
+    parameter_shift_jacobian,
+    parameter_shift_jvp,
+    parameter_shift_vjp,
+)
+from .ir import Circuit, ClassicalCondition, Operation
+from .layers import LayerCheckpoint, LayerSpec
+from .measurement import EstimateResult, MeasurementPlan, ShotBackend, estimate, measurement_plan
+from .observables import Hamiltonian, PauliString, z_observables
+from .optimization import OptimizationResult, optimize
+from .parameters import Expression, Parameter
+from .pauli import PauliPlan
+from .planning import DensityPlan, plan_density
+from .program import QuantumProgram, as_circuit
+from .providers import CirqDensityBackend, QiskitEstimatorBackend, QiskitSamplerBackend
+from .readout import ReadoutPlan, plan_readout
+from .simulator import ExecutionResult, execute, expectation, expectations, sample, statevector
+from .templates import data_reuploading, hardware_efficient
+from .verification import ConversionCheck
+
+_INTERFACE_NAMES = frozenset({"torch", "jax", "flax"})
+
+
+def __getattr__(name):
+    if name in _INTERFACE_NAMES:
+        module = _import_module(f".interfaces.{name}", __name__)
+        globals()[name] = module
+        return module
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | _INTERFACE_NAMES)
+
+
+__version__ = "0.3.0a8"
+
+__all__ = [
+    "ReadoutRoute",
+    "ConversionCheck",
+    "ExecutionBatch",
+    "ExpectationCheck",
+    "ExpectationPlan",
+    "ExecutionGroup",
+    "PauliPlan",
+    "ReadoutPlan",
+    "plan_readout",
+    "AdjointPlan",
+    "adjoint_vjp",
+    "adjoint_jvp",
+    "ConversionPlan",
+    "plan_conversion",
+    "data_reuploading",
+    "LayerCheckpoint",
+    "OptimizationResult",
+    "optimize",
+    "DensityPlan",
+    "plan_density",
+    "Circuit",
+    "ClassicalCondition",
+    "density_matrix",
+    "DensityMatrixBackend",
+    "Operation",
+    "Parameter",
+    "Expression",
+    "PauliString",
+    "Hamiltonian",
+    "statevector",
+    "expectation",
+    "expectations",
+    "execute",
+    "sample",
+    "parameter_shift",
+    "convert",
+    "diagnose",
+    "hardware_efficient",
+    "z_observables",
+    "LayerSpec",
+    "ConversionResult",
+    "ExecutionResult",
+    "Diagnostic",
+    "OpenQMLError",
+    "ValidationError",
+    "ConversionError",
+    "ResourceError",
+    "MissingDependencyError",
+    "BackendError",
+    "BackendCapabilities",
+    "ExecutionOptions",
+    "StatevectorBackend",
+    "ExpectationBackend",
+    "SamplingBackend",
+    "register_backend",
+    "unregister_backend",
+    "list_backends",
+    "get_backend",
+    "CircuitStats",
+    "circuit_stats",
+    "decompose",
+    "inverse",
+    "simplify",
+    "QuantumProgram",
+    "as_circuit",
+    "execute_batch",
+    "expectations_batch",
+    "parameter_shift_jacobian",
+    "parameter_shift_vjp",
+    "parameter_shift_jvp",
+    "estimate",
+    "measurement_plan",
+    "MeasurementPlan",
+    "EstimateResult",
+    "ShotBackend",
+    "AerBackend",
+    "CirqDensityBackend",
+    "QiskitEstimatorBackend",
+    "QiskitSamplerBackend",
+    "FrameworkAdapter",
+    "list_formats",
+    "register_adapter",
+    "unregister_adapter",
+]

openqml/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

openqml/_native_verification.py

@@ -0,0 +1,260 @@
+"""Independent execution of exported artifacts on complete spanning inputs.
+
+Native SDK state evolution is deliberately separate from IR reimport. Channels
+use physical pure-state probes spanning the operator space, so SDKs need not
+accept nonphysical matrix units. No sampling or phase alignment is used.
+
+SDK entry points:
+https://quantum.cloud.ibm.com/docs/en/api/qiskit/qiskit.quantum_info.DensityMatrix
+https://quantumai.google/reference/python/cirq/DensityMatrixSimulator
+https://docs.pennylane.ai/en/stable/code/api/pennylane.StatePrep.html
+"""
+
+from itertools import islice
+
+import numpy as np
+
+from .errors import (
+    ConversionError,
+    MissingDependencyError,
+    ResourceError,
+    ValidationError,
+    conversion_error,
+)
+
+
+def _unsupported(message):
+    return conversion_error(
+        "NATIVE_VERIFICATION_UNSUPPORTED",
+        message,
+        hint="Use roundtrip verification for retained measurement records and feedback.",
+    )
+
+
+def _native_scope(circuit, target, source_options):
+    if source_options:
+        raise ValidationError("source_options apply to roundtrip verification only.")
+    if target not in {"qiskit", "cirq", "pennylane", "openqasm2", "openqasm3"}:
+        raise _unsupported("Native verification requires a supported SDK or OpenQASM target.")
+    if any(op.name in {"measure", "if_else"} for _, op in circuit.walk_operations()):
+        raise _unsupported(
+            "Native complete-input checks do not support recorded measurement or feedback."
+        )
+
+
+def _probes(width, channel):
+    dimension = 1 << width
+    for index in range(dimension):
+        vector = np.zeros(dimension, dtype=complex)
+        vector[index] = 1
+        yield vector
+    if channel:
+        for first in range(dimension):
+            for second in range(first + 1, dimension):
+                for phase in (1, 1j):
+                    vector = np.zeros(dimension, dtype=complex)
+                    vector[first], vector[second] = 1 / np.sqrt(2), phase / np.sqrt(2)
+                    yield vector
+
+
+def _profile(arities, width, instrument, max_operations):
+    work = 1
+    for count, arity in enumerate(arities, 1):
+        if count > max_operations:
+            raise ResourceError("Native verification exceeds max_operations.")
+        if not 0 <= arity <= width:
+            raise ValidationError("Native artifact uses an unexpected quantum register.")
+        work += 16 * (1 << (2 * arity)) if instrument else 1 << arity
+    return work
+
+
+def _qiskit(value, circuit, instrument, max_operations):
+    from qiskit.circuit import Gate
+    from qiskit.quantum_info import DensityMatrix, Statevector
+
+    if (value.num_qubits, value.num_clbits) != (circuit.num_qubits, circuit.num_clbits):
+        raise ValidationError("Native artifact changed quantum or classical register width.")
+    if value.parameters:
+        raise ValidationError("Native artifact contains unbound parameters.")
+
+    def arities():
+        for item in value.data:
+            if item.operation.name == "measure" or getattr(item.operation, "blocks", ()):
+                raise _unsupported("Native artifact contains recorded measurement or control flow.")
+            if item.clbits:
+                raise _unsupported("Native artifact contains a classical instruction.")
+            if (
+                not instrument
+                and not isinstance(item.operation, Gate)
+                and item.operation.name != "barrier"
+            ):
+                raise _unsupported("Native artifact is not unitary.")
+            yield len(item.qubits)
+
+    work = _profile(arities(), circuit.num_qubits, instrument, max_operations)
+    width = circuit.num_qubits
+    permutation = (
+        np.arange(1 << width)
+        .reshape((2,) * width)
+        .transpose(tuple(reversed(range(width))))
+        .reshape(-1)
+    )
+
+    def run(probes):
+        outputs = []
+        for vector in probes:
+            state = (DensityMatrix if instrument else Statevector)(vector[permutation]).evolve(
+                value
+            )
+            output = np.asarray(state.data)
+            outputs.append(
+                output[np.ix_(permutation, permutation)].reshape(-1)
+                if instrument
+                else output[permutation]
+            )
+        return np.stack(outputs)
+
+    return run, work
+
+
+def _cirq(value, circuit, instrument, max_operations):
+    import cirq
+
+    order = tuple(cirq.LineQubit.range(circuit.num_qubits))
+    if value.all_qubits() != frozenset(order):
+        raise ValidationError("Native artifact changed canonical quantum wires.")
+
+    def arities():
+        for op in value.all_operations():
+            if (
+                isinstance(op, cirq.CircuitOperation)
+                or cirq.is_measurement(op)
+                or op.classical_controls
+            ):
+                raise _unsupported("Native artifact contains measurement or nested control flow.")
+            if cirq.is_parameterized(op):
+                raise ValidationError("Native artifact contains unbound parameters.")
+            if not instrument and not cirq.has_unitary(op):
+                raise _unsupported(
+                    "Native artifact is not unitary; stochastic verification is refused."
+                )
+            yield len(op.qubits)
+
+    work = _profile(arities(), circuit.num_qubits, instrument, max_operations)
+    simulator = (
+        cirq.DensityMatrixSimulator(dtype=np.complex128, split_untangled_states=False)
+        if instrument
+        else cirq.Simulator(dtype=np.complex128)
+    )
+
+    def run(probes):
+        outputs = []
+        for vector in probes:
+            result = simulator.simulate(value, initial_state=vector, qubit_order=order)
+            output = result.final_density_matrix if instrument else result.final_state_vector
+            outputs.append(np.asarray(output).reshape(-1))
+        return np.stack(outputs)
+
+    return run, work
+
+
+def _pennylane(value, circuit, instrument, max_operations):
+    import pennylane as qml
+
+    if value.measurements:
+        raise _unsupported("Native PennyLane verification requires an operation-only tape.")
+    order = tuple(range(circuit.num_qubits))
+
+    def arities():
+        for op in value.operations:
+            if not set(op.wires).issubset(order):
+                raise ValidationError("Native artifact changed canonical quantum wires.")
+            if not op.has_matrix and not isinstance(op, qml.operation.Channel):
+                raise _unsupported("Native tape contains an unsupported dynamic operation.")
+            if not instrument and isinstance(op, qml.operation.Channel):
+                raise _unsupported("Native artifact is not unitary.")
+            yield len(op.wires)
+
+    work = _profile(arities(), circuit.num_qubits, instrument, max_operations)
+    device = qml.device("default.mixed" if instrument else "default.qubit", wires=order)
+
+    @qml.qnode(device, interface=None, diff_method=None)
+    def program(vector):
+        qml.StatePrep(vector, wires=order)
+        for op in value.operations:
+            qml.apply(op)
+        return qml.density_matrix(wires=order) if instrument else qml.state()
+
+    def run(probes):
+        return np.stack([np.asarray(program(vector)).reshape(-1) for vector in probes])
+
+    return run, work
+
+
+def _verify_native(
+    plan, value, instrument, records, peak, size, work, max_work, budget, chunk, atol, rtol
+):
+    from .verification import _basis_capacity, _Comparison, _evolve_basis
+
+    circuit, target = plan.circuit, plan.target_format
+    backend = "qiskit" if target.startswith("openqasm") else target
+    try:
+        if target.startswith("openqasm"):
+            from .program import QuantumProgram
+
+            value = QuantumProgram.from_qasm(
+                value,
+                version=int(target[-1]),
+                max_operations=plan.max_operations,
+                max_depth=plan.max_depth,
+                max_register_bits=circuit.num_qubits + circuit.num_clbits,
+                max_matrix_qubits=circuit.num_qubits,
+            ).native
+        runner, native_work = {"qiskit": _qiskit, "cirq": _cirq, "pennylane": _pennylane}[backend](
+            value, circuit, instrument, plan.max_operations
+        )
+    except ImportError as exc:
+        extra = "qasm" if target.startswith("openqasm") else backend
+        raise MissingDependencyError(f"Install openqml[{extra}] for native verification.") from exc
+    except (ConversionError, ResourceError, ValidationError):
+        raise
+    except Exception as exc:
+        raise conversion_error(
+            "NATIVE_VERIFICATION_PREPARATION", f"{backend} artifact preparation failed: {exc}"
+        ) from exc
+    if work + size * size * native_work > max_work:
+        raise ResourceError("Native verification exceeds max_work.")
+    capacity = _basis_capacity((circuit,), (peak, 1), size, budget)
+    chunk, probes, comparison = (
+        min(chunk, capacity, size),
+        _probes(circuit.num_qubits, instrument),
+        _Comparison(),
+    )
+    for start in range(0, size, chunk):
+        vectors = np.stack(tuple(islice(probes, min(chunk, size - start))))
+        basis = (
+            (vectors[..., :, None] * vectors[..., None, :].conj()).reshape(len(vectors), -1)
+            if instrument
+            else vectors
+        )
+        expected = _evolve_basis(circuit, basis, instrument, records)
+        try:
+            actual = {frozenset(): runner(vectors)}
+        except (ConversionError, ResourceError, ValidationError, MissingDependencyError):
+            raise
+        except Exception as exc:
+            raise conversion_error(
+                "NATIVE_VERIFICATION_EXECUTION", f"{backend} execution failed: {exc}"
+            ) from exc
+        comparison.add(expected, actual, start, atol, rtol)
+        del vectors, basis, expected, actual
+    return comparison.result(
+        circuit,
+        target,
+        "quantum_channel" if instrument else "unitary_including_global_phase",
+        size,
+        atol,
+        rtol,
+        "native",
+        backend,
+    )

openqml/_qasm.py

@@ -0,0 +1,176 @@
+"""Frontend-independent source limits and comment handling."""
+
+import re
+
+from .errors import conversion_error
+from .ir import integer
+
+
+def clean_source(text, max_source_bytes=2_000_000):
+    integer(max_source_bytes, "max_source_bytes", 1)
+    if (
+        not isinstance(text, str)
+        or len(text) > max_source_bytes
+        or len(text.encode("utf-8")) > max_source_bytes
+    ):
+        raise conversion_error("SOURCE_LIMIT", "OpenQASM source exceeds the configured byte limit.")
+    # Remove comments without changing strings, line numbers or character offsets.
+    output, index = [], 0
+    while index < len(text):
+        if text[index] == '"':
+            start = index
+            index += 1
+            while index < len(text):
+                if text[index] == "\\":
+                    index += 2
+                elif text[index] == '"':
+                    index += 1
+                    break
+                else:
+                    index += 1
+            else:
+                raise conversion_error("SYNTAX", "Unterminated source string.")
+            output.append(text[start:index])
+        elif text.startswith("//", index):
+            end = text.find("\n", index)
+            end = len(text) if end < 0 else end
+            output.append(" " * (end - index))
+            index = end
+        elif text.startswith("/*", index):
+            end = text.find("*/", index + 2)
+            if end < 0:
+                raise conversion_error("SYNTAX", "Unterminated block comment.")
+            end += 2
+            output.append("".join("\n" if c == "\n" else " " for c in text[index:end]))
+            index = end
+        else:
+            output.append(text[index])
+            index += 1
+    return "".join(output)
+
+
+def validate_header(text, version=None):
+    header = re.match(r"\s*OPENQASM\s+([23])(?:\.0)?\s*;", text)
+    if not header:
+        raise conversion_error("QASM_VERSION", "Expected an OpenQASM 2.0 or 3.0 header.")
+    actual = int(header.group(1))
+    if version is not None and (type(version) is not int or version != actual):
+        raise conversion_error(
+            "QASM_VERSION", "Source header differs from requested source format."
+        )
+    return actual
+
+
+def check_literal_registers(text, max_register_bits):
+    """Reject oversized literal declarations before an SDK constructs their storage.
+
+    SDK-resolved constant/expression sizes also receive a post-parse width check.
+    This preflight does not claim a process-level SDK parsing memory limit.
+    """
+    integer(max_register_bits, "max_register_bits", 1)
+    code = re.sub(r'"(?:\\.|[^"\\])*"', '""', text)
+    declarations = re.finditer(
+        r"\b(?:qreg|creg)\s+[A-Za-z_]\w*\s*\[\s*(\d+)\s*\]"
+        r"|\b(?:qubit|bit)\s*(?:\[\s*(\d+)\s*\])?\s+[A-Za-z_]\w*",
+        code,
+    )
+    total = 0
+    for declaration in declarations:
+        total += int(declaration.group(1) or declaration.group(2) or "1")
+        if total > max_register_bits:
+            raise conversion_error("REGISTER_LIMIT", "Register size exceeds the configured limit.")
+
+
+def expand_includes(text, include_paths, version, max_source_bytes, max_include_depth):
+    """Inline custom files from explicit roots with cumulative read/expansion limits."""
+    from pathlib import Path
+
+    integer(max_include_depth, "max_include_depth")
+    if isinstance(include_paths, (str, bytes)):
+        raise conversion_error("INCLUDE_PATH", "include_paths must be a sequence of directories.")
+    try:
+        roots = tuple(Path(p).resolve(strict=True) for p in include_paths)
+    except (TypeError, OSError, ValueError, RuntimeError) as exc:
+        raise conversion_error(
+            "INCLUDE_PATH", "Include roots must be existing directories."
+        ) from exc
+    if any(not p.is_dir() for p in roots):
+        raise conversion_error("INCLUDE_PATH", "Include roots must be directories.")
+    remaining = max_source_bytes - len(text.encode("utf-8"))
+    directive = re.compile(r'"(?:\\.|[^"\\])*"|\binclude\b(?:\s*"([^"\n]+)"\s*;)?')
+    standard = "qelib1.inc" if version == 2 else "stdgates.inc"
+
+    def expand(code, parent, stack):
+        nonlocal remaining
+        pieces, end = [], 0
+        for match in directive.finditer(code):
+            filename = match.group(1)
+            if filename is None:
+                if not match.group().startswith('"'):
+                    raise conversion_error("SYNTAX", "Malformed include directive.")
+                continue
+            if filename == standard:
+                continue
+            if not roots:
+                raise conversion_error(
+                    "INCLUDE_PATH", "Custom includes require explicit include_paths."
+                )
+            if len(stack) >= max_include_depth:
+                raise conversion_error(
+                    "INCLUDE_DEPTH_LIMIT", "Custom include nesting exceeds max_include_depth."
+                )
+            target = Path(filename)
+            searches = ((parent,) if parent is not None else ()) + roots
+            candidates = (target,) if target.is_absolute() else tuple(p / target for p in searches)
+            resolved = None
+            for candidate in candidates:
+                try:
+                    candidate = candidate.resolve()
+                except (OSError, ValueError, RuntimeError):
+                    continue
+                if any(candidate.is_relative_to(root) for root in roots) and candidate.is_file():
+                    resolved = candidate
+                    break
+            if resolved is None:
+                raise conversion_error(
+                    "INCLUDE_PATH", "Include file is missing or outside the explicit roots."
+                )
+            if resolved in stack:
+                raise conversion_error("INCLUDE_CYCLE", "Custom include files contain a cycle.")
+            try:
+                with resolved.open("rb") as stream:
+                    payload = stream.read(remaining + 1)
+            except OSError as exc:
+                raise conversion_error(
+                    "INCLUDE_PATH", "Cannot read the requested include file."
+                ) from exc
+            if len(payload) > remaining:
+                raise conversion_error(
+                    "SOURCE_LIMIT", "Source and included files exceed max_source_bytes."
+                )
+            remaining -= len(payload)
+            try:
+                child = clean_source(payload.decode("utf-8"), max_source_bytes)
+            except UnicodeError as exc:
+                raise conversion_error("INCLUDE_ENCODING", "Include files must use UTF-8.") from exc
+            pieces.extend(
+                (
+                    code[end : match.start()],
+                    "\n",
+                    expand(child, resolved.parent, stack + (resolved,)),
+                    "\n",
+                )
+            )
+            end = match.end()
+        pieces.append(code[end:])
+        return "".join(pieces)
+
+    try:
+        output = expand(text, None, ())
+    except RecursionError as exc:
+        raise conversion_error(
+            "INCLUDE_DEPTH_LIMIT", "Include nesting exceeds the Python recursion limit."
+        ) from exc
+    if len(output.encode("utf-8")) > max_source_bytes:
+        raise conversion_error("SOURCE_LIMIT", "Expanded source exceeds max_source_bytes.")
+    return output