quapp-common 0.0.13.dev1

Quapp common library supporting Quapp Platform for Quantum Computing

quapp-common

Quapp common library supporting Quapp Platform for Quantum Computing.

Overview

quapp-common is a Python library designed to support the Quapp Platform for Quantum Computing by providing common utilities, configurations, and abstractions for working with quantum providers and devices. Recent improvements add first-class asynchronous job processing with a cross-process JobManager, background task execution, and standardized result models for immediate client responses while work continues in the background.

Features

• Provider and device factory for quantum computing platforms.
• Logging and configuration utilities with improved and detailed log messages.
• Support for AWS Braket, OQC Cloud, Qiskit, PennyLane, DWave Ocean, and Quapp quantum simulators.
• Refactored classes and utilities to remove tenant-specific request, response, and promise classes.
• Standardized naming by renaming ProjectHeader to CustomHeader.
• Enhanced error handling and job metadata update mechanisms.
• Simplified and cleaner HTTP request/response logging and URL parsing utilities.
• Asynchronous job processing:
  • AsyncInvocationTask to run handlers in a background thread pool and return immediate responses.
  • JobManager for cross-process job registry with atomic add/update/get and pub-sub updates.
  • Standard Event/Result (Success, Error) models for consistent async responses.
  • Scheduler integration via callback URL; local updates are patched to the scheduler.
  • Safety: updates to jobs already DONE/FAILED are ignored to prevent post-completion mutations.
• Multi-language SDK support:
  • Language enum for validating and resolving Python, JavaScript, and Q# runtimes.
  • Standalone dispatch() function (formerly SubprocessDispatcher class) to delegate tasks to non-Python runtimes via subprocess with timeout management and JSON payload processing; supports Node.js and precompiled Q# binary (./handler_runner_bin/Function[.exe]) runners.
  • Working directory configurable via QUAPP_WORKING_DIR environment variable; falls back to os.getcwd() when unset.
  • SubprocessBridge class integrating standalone dispatcher, circuit adapter, and result serializer for seamless JS/Q#-Python handler interaction.
  • Standalone adapt() function (formerly CircuitAdapter class) for converting subprocess circuit outputs into native SDK formats (OpenQASM, QUBO, JSON) across Qiskit, Braket, PennyLane, PyQuil, Qibo, Qulacs, and CUDA Quantum.
  • Standalone serialize() function (formerly ResultSerializer class) for converting complex job results into JSON-serializable dictionaries for subprocess communication.

Installation

Install via pip:

pip install quapp-common

Notes:

• From version 0.0.11.dev7, starlette is a direct dependency to support background execution helpers.
• From version 0.0.12.dev1, qibo and dimod are added as dependencies to support Qibo and D-Wave Ocean SDK integrations.

Recently Changes Highlights

v0.0.13.dev1

• Refactor: Replace class-based subprocess components with standalone module-level functions for simpler imports and testability:
  • SubprocessDispatcher class → dispatch() and is_subprocess_language() in dispatcher.py.
  • CircuitAdapter class → adapt() and private helper functions in circuit_adapter.py.
  • ResultSerializer class → serialize() in result_serializer.py.
  • SubprocessBridge retains its class form but delegates internally to the new standalone functions.
• Refactor dispatcher.py: WORKING_DIR is now read from the QUAPP_WORKING_DIR environment variable (previously hardcoded None); falls back to os.getcwd() when the variable is unset.
• Refactor dispatcher.py: Q# runner command changed from dotnet run --project HandlerRunner.csproj to a precompiled platform-specific binary — ./handler_runner_bin/Function.exe on Windows and ./handler_runner_bin/Function on other platforms — eliminating the dotnet toolchain requirement at runtime.
• Refactor circuit_adapter.py: Extract _load_qasm_circuit(qasm_str) private utility that centralises OpenQASM 2.0 string parsing with Qiskit version compatibility — uses qiskit.qasm2.loads (Qiskit >= 1.0) and falls back to QiskitCircuit.from_qasm_str (Qiskit < 1.0).
• Fix: subprocess.run now passes check=True so a non-zero exit code raises CalledProcessError before the manual return-code branch is reached.
• Add unit tests: tests/test_circuit_adapter.py, tests/test_json_parser_utils.py, tests/test_result_serializer.py.

v0.0.12.dev15

• Extend multi-language SDK support with Q# (QSharp) runtime:
  • Add QSHARP to Language enum.
  • Add Q# runner configuration to SubprocessDispatcher (dotnet run --project ., 300 s timeout).

v0.0.12.dev14

• Fix: CircuitAdapter._adapt_openqasm for Sdk.PENNYLANE now catches the "Failed to load the qasm plugin" error raised by qml.from_qasm on PennyLane versions that route QASM parsing through the IO plugin registry and require pennylane-qiskit to be installed (affects both older releases and the current latest). When the error is detected, it falls back to parsing the QASM string via Qiskit (a hard dependency) and emitting native PennyLane operations gate-by-gate through the new CircuitAdapter._qiskit_to_pennylane helper. Supported gates: H, X, Y, Z, S, Sdg (→ PhaseShift −π/2), T, Tdg (→ PhaseShift −π/4), CX, CZ, SWAP, RX, RY, RZ, P/U1 (→ PhaseShift), U2, U3/U; unrecognized gates are logged as a warning and skipped.

v0.0.12.dev13

• Fix: CircuitAdapter._adapt_openqasm for Sdk.PENNYLANE now injects string sentinels ("Expectation", "Variance", "Sample", "Probability", "State", "MidMeasure") back into pennylane.measurements when they are absent. PennyLane 0.37 removed ObservableReturnTypes from that module, but legacy plugins such as pennylane-rigetti import these names at module level and crash with ImportError before the device is created. The shim is injected inside __pre_execute, before PennylaneInvocation creates the device, so the plugin import succeeds and the removed code paths are bypassed at runtime.

v0.0.12.dev12

• Feat: add QUAPP_HPC to ProviderTag enum to support the Slurm HPC integration. Required by quapp-hpc so its SlurmProvider can register itself in the shared ProviderTag namespace; without this, importing quapp-hpc fails at SlurmProvider.__init__ with AttributeError on the enum lookup.

v0.0.12.dev11

• Enhance: CircuitAdapter now emits structured debug logs at each routing decision — SDK selected, QASM string length, qubit count, per-SDK adapter chosen, tk_to_braket return type (tuple vs bare Circuit), DenseMatrix fallback for unrecognized/parametric gates in _qiskit_to_qulacs, and QUBO entry counts before and after parsing.
• Enhance: SubprocessBridge now emits debug logs on initialisation (language, sdk), processing() (input keys, JS status, adapted circuit type), and post_processing() (job-result type, serialised keys, JS status, result type); subprocess failures are additionally promoted to logger.error before the RuntimeError is raised.

v0.0.12.dev10

• Fix: CircuitAdapter._adapt_openqasm for Sdk.BRAKET now handles the breaking API change in pytket-braket >= 0.35, where tk_to_braket returns a (Circuit, n_shots) tuple instead of a bare Circuit — the method unpacks the first element when a tuple is returned and passes through the value unchanged for older versions.

v0.0.12.dev9

• Fix: QulacsInvocation._get_qubit_amount now handles OpenQASM string input — when a JS job submits an OpenQASM 2.0 string circuit, the method parses the qreg declaration to extract the qubit count instead of raising "Invalid circuit type!".

v0.0.12.dev8

• Add Sdk.QULACS support in CircuitAdapter._adapt_openqasm with a two-stage fallback strategy:
  1. Qiskit bridge (preferred): parse OpenQASM with QiskitCircuit.from_qasm_str, then convert gate-by-gate to a qulacs.QuantumCircuit via the new CircuitAdapter._qiskit_to_qulacs helper. Fixed gates (H, X, Y, Z, S, Sdg, T, Tdg, CX, CZ, SWAP) use named qulacs methods; parametric and unrecognized gates fall back to qulacs.gate.DenseMatrix with gate.to_matrix().
  2. Raw pass-through (fallback): if qiskit is not installed or conversion raises any exception, the raw OpenQASM string is returned as-is (same approach as Sdk.CUDA_QUANTUM) and a warning is logged.
• Add qulacs as a direct dependency in pyproject.toml.

v0.0.12.dev7

• Fix: remove Sdk.CU_QUANTUM from the CUDA-Q branch in CircuitAdapter._adapt_openqasm — CU_QUANTUM is not a member of the Sdk enum; the only valid CUDA-Q value is Sdk.CUDA_QUANTUM, so the compound sdk in (Sdk.CUDA_QUANTUM, Sdk.CU_QUANTUM) check is replaced with a plain sdk == Sdk.CUDA_QUANTUM.

v0.0.12.dev6

• Fix: replace direct from pytket.extensions.braket import ... and from pytket.extensions.pyquil import ... with importlib.import_module() in CircuitAdapter — avoids IDE static-analysis false positives caused by pytket.extensions being a namespace package populated at runtime by separately installed pytket-braket / pytket-pyquil packages.

v0.0.12.dev5

• Version bump to 0.0.12.dev5.
• Refactor: update logger imports in SubprocessBridge, CircuitAdapter, and SubprocessDispatcher to use relative paths (from ..config.logging_config import logger) for consistency across modules.

v0.0.12.dev4

• Version bumps to 0.0.12.dev4.
• Fix: AsyncInvocationTask._on_task_done now properly fires the step error callback when a background task raises an unhandled exception — reads onErrorCallbackUrl from the event's preparation step and calls update_job_metadata with a structured error response.
• Fix: circuit preparation failure in Invocation.__pre_execute now returns None instead of raising ValueError, allowing the caller to handle the empty result gracefully without an unhandled exception propagating.
• Refactor: replace stdlib logging with the project’s loguru-based logger (via config.logging_config) in SubprocessBridge, CircuitAdapter, and SubprocessDispatcher; all three now call logger.bind(context=__name__).
• Style: reformat SubprocessBridge and SubprocessDispatcher from 2-space to 4-space indentation, consistent with the rest of the codebase.

v0.0.12.dev3

• Version bumps to 0.0.12.dev3.
• Add QUANTUM_HPC SDK enum value (display name "quantum hpc") to support the Quapp HPC backend.
• Make circuitExportUrl optional in Invocation for SDKs that do not require a circuit-export step.

v0.0.12.dev2

• Version bumps to 0.0.12.dev2.
• Fix: correct JavaScript handler runner path in SubprocessDispatcher.RUNNER_MAP — removed the erroneous function/ directory prefix so the subprocess command resolves to handler_runner.js relative to the working directory.

v0.0.12.dev1

• Version bump to 0.0.12.dev1 and dependency update (add qibo, dimod).
• Introduce multi-language SDK support primitives:
  • Language enum for validating and resolving Python/JavaScript runtimes.
  • SubprocessDispatcher for delegating tasks to non-Python runtimes via subprocess with runner configuration and timeout management.
  • SubprocessBridge integrating dispatcher, circuit adapter, and result serializer for JS-Python handler interaction.
  • CircuitAdapter for converting JS subprocess circuit outputs into native SDK formats (OpenQASM, QUBO, JSON) across Qiskit, Braket, PennyLane, etc.
  • ResultSerializer for converting complex job results (numpy, complex numbers, Enums, datetime) into JSON-serializable dictionaries.

v0.0.11.dev7 – v0.0.11.dev10

• Version bump to 0.0.11.dev7 and dependency update (add starlette).
• Introduce asynchronous job processing primitives:
  • AsyncInvocationTask for background execution with immediate client response.
  • Event and standardized Result models (Success, Error).
• Introduce JobManager for cross-process job management and update publication.
• Integrate JobManager into Request to register jobs and carry scheduler callback URL.
• Modularize update_job_metadata with clearer helpers; patch scheduler on local state changes.
• Fix: ignore updates for jobs that are already DONE or FAILED.
• Improve logging and error handling (use full tracebacks, cleaner logs).

---

For detailed usage and API references, please refer to the in-code documentation or contact the maintainers.