hlquantum 0.1.3

HLQuantum (High Level Quantum) — A high-level Python package for working with quantum hardware using CUDA-Q and other backends.

HLQuantum

HLQuantum (High Level Quantum) is a high-level Python package designed to simplify working with quantum hardware. Write your quantum logic once and run it on any supported backend.

Features

• Backend-Agnostic Circuits — A single QuantumCircuit IR that translates to any supported framework.
• Quantum Pipelines — Build modular architectures using ML-inspired Layer and Sequential models.
• Resilient Workflows — Orchestrate complex executions with loops, branching, and state persistence (save/resume).
• Asynchronous Execution — Multi-backend concurrency with async/await support.
• Unitary-Agnostic @kernel — Write quantum logic as plain Python functions.
• GPU Acceleration — Unified GPUConfig across all backends.
• Framework Interoperability — Import circuits from Qiskit and Cirq instantly via Circuit.from_qiskit() and Circuit.from_cirq().
• Out-of-the-Box Algorithms — QFT, Grover, Bernstein-Vazirani, Deutsch-Jozsa, VQE, QAOA, GQE, QPE, AE, quantum arithmetic, and parameter-shift gradients — all accessible via friendly aliases like quantum_search() and find_minimum_energy().

Supported Backends

Backend	Framework	Install extra
CudaQBackend	NVIDIA CUDA-Q	pip install hlquantum[cudaq]
QiskitBackend	IBM Qiskit	pip install hlquantum[qiskit]
CirqBackend	Google Cirq	pip install hlquantum[cirq]
BraketBackend	Amazon Braket	pip install hlquantum[braket]
PennyLaneBackend	Xanadu PennyLane	pip install hlquantum[pennylane]
IonQBackend	IonQ (via qiskit-ionq)	pip install hlquantum[ionq]

Installation

# Core only (no backend dependencies)
pip install .

# With a specific backend
pip install ".[qiskit]"

# With all backends
pip install ".[all]"

# Development
pip install ".[dev]"

Out-of-the-Box Algorithms

HLQuantum ships with ready-to-use implementations of common quantum algorithms — each available under a friendly alias so you can express intent without memorising circuit-level details:

from hlquantum.algorithms import quantum_search
import hlquantum

# Search a 5-qubit space for the state |10101⟩
circuit = quantum_search(num_qubits=5, target_states=["10101"])
result = hlquantum.run(circuit, shots=1000)
print(result.most_probable)  # '10101'

Other algorithms include QFT (frequency_transform), VQE (find_minimum_energy), QAOA (optimize_combinatorial), Bernstein-Vazirani (find_hidden_pattern), Phase Estimation (estimate_phase), Amplitude Estimation (estimate_amplitude), and more — see the algorithms API reference for the full list.

Importing from Other Frameworks

If you already have code in qiskit or cirq, you can import it directly into hlquantum and execute it across any backend without rewriting.

from hlquantum.circuit import Circuit

# Load a Qiskit circuit
import qiskit
qc_qiskit = qiskit.QuantumCircuit(2)
qc_qiskit.h(0)
qc_qiskit.cx(0, 1)

hlq_circuit = Circuit.from_qiskit(qc_qiskit)

# Or a Cirq circuit
import cirq
q0, q1 = cirq.LineQubit(0), cirq.LineQubit(1)
cirq_circuit = cirq.Circuit(cirq.H(q0), cirq.CNOT(q0, q1))

hlq_circuit = Circuit.from_cirq(cirq_circuit)

Classical Optimizers for VQA

hlquantum.optimizers provides classical optimisation routines resilient to quantum noise, perfect for use in VQE and QAOA setups. Currently supported optimisers:

• SPSA: Simultaneous Perturbation Stochastic Approximation. Highly efficient for noisy hardware environments.
• COBYLA: Constrained Optimization BY Linear Approximations. Derivative-free gradient estimator.

from hlquantum.optimizers import SPSA, COBYLA

spsa = SPSA(maxiter=300)
result = spsa.minimize(objective_function, initial_parameters)
print("Optimal parameters:", result.x)

Quantum Pipelines (ML-Style)

Build complex circuits modularly by stacking layers:

from hlquantum.layers import Sequential, GroverLayer, QFTLayer, RealAmplitudes

# Stack algorithms and variational layers
model = Sequential([
    QFTLayer(num_qubits=4),
    GroverLayer(num_qubits=4, target_states=["1010"]),
    RealAmplitudes(num_qubits=4, reps=2)
])

# Compile to a single circuit
circuit = model.build()

Resilient Workflows

Orchestrate complex execution flows with automatic state persistence and parallel execution.

from hlquantum.workflows import Workflow, Parallel, Loop, Branch

wf = Workflow(state_file="checkpoint.json", name="Discovery")

# Add parallel paths
wf.add(Parallel(circuit1, circuit2))

# Add a loop
wf.add(Loop(base_circuit, iterations=10))

# Execute asynchronously (with optional throttling for rate-limits)
import asyncio
results = asyncio.run(wf.run(resume=True))

# Export to Mermaid for visualization
print(wf.to_mermaid())

Hybrid Quantum–Classical Workflows

Classical post-processing functions can run in the same workflow as quantum circuits. Each node receives a context dict with results from all prior steps:

from hlquantum.workflows import Workflow, Branch, WorkflowRunner

wf = Workflow(name="HybridPipeline")

# Quantum step
wf.add(Circuit(2).h(0).cx(0, 1).measure_all(), name="bell")

# Classical step — extract and analyse
wf.add(lambda ctx: ctx["previous_result"].counts, name="extract_counts")
wf.add(lambda ctx: sum(ctx["previous_result"].get(k, 0) for k in ("00", "11")) / 1000, name="correlation")

# Branch on the result
wf.add(Branch(
    lambda ctx: ctx["previous_result"] > 0.9,
    lambda ctx: "entangled",
    lambda ctx: "not entangled",
), name="classify")

results = asyncio.run(wf.run())

Backend Examples

CUDA-Q

from hlquantum.backends import CudaQBackend

backend = CudaQBackend(target="nvidia")
result = hlquantum.run(bell, shots=1000, backend=backend)
print(result.counts)  # {'00': ~500, '11': ~500}

Qiskit (IBM)

from hlquantum.backends import QiskitBackend

# Local AerSimulator (default)
backend = QiskitBackend()
result = hlquantum.run(bell, shots=1000, backend=backend)

# Real IBM hardware
from qiskit_ibm_runtime import QiskitRuntimeService
service = QiskitRuntimeService()
ibm_backend = service.least_busy(min_num_qubits=2)
backend = QiskitBackend(backend=ibm_backend)

Cirq (Google)

from hlquantum.backends import CirqBackend

backend = CirqBackend()
result = hlquantum.run(bell, shots=1000, backend=backend)

# With noise
import cirq
noise = cirq.ConstantQubitNoiseModel(cirq.depolarize(0.01))
noisy_backend = CirqBackend(noise_model=noise)

Amazon Braket

from hlquantum.backends import BraketBackend

# Local simulator
backend = BraketBackend()
result = hlquantum.run(bell, shots=1000, backend=backend)

# IonQ on AWS
from braket.aws import AwsDevice
ionq = AwsDevice("arn:aws:braket:::device/qpu/ionq/Harmony")
backend = BraketBackend(device=ionq, s3_destination=("my-bucket", "results"))

PennyLane (Xanadu)

from hlquantum.backends import PennyLaneBackend

# default.qubit simulator
backend = PennyLaneBackend()
result = hlquantum.run(bell, shots=1000, backend=backend)

# Lightning fast simulator
backend = PennyLaneBackend(device_name="lightning.qubit")

IonQ

from hlquantum.backends import IonQBackend

# IonQ cloud simulator (default)
backend = IonQBackend(api_key="your-ionq-api-key")
result = hlquantum.run(bell, shots=1000, backend=backend)

# IonQ trapped-ion QPU
backend = IonQBackend(backend_name="ionq_qpu", api_key="your-ionq-api-key")

GPU Acceleration

HLQuantum provides a unified GPUConfig that works across all GPU-capable backends:

from hlquantum import GPUConfig, GPUPrecision

# Simple — single GPU
gpu = GPUConfig(enabled=True)

# Multi-GPU
gpu = GPUConfig(enabled=True, multi_gpu=True, device_ids=[0, 1])

# FP64 precision
gpu = GPUConfig(enabled=True, precision=GPUPrecision.FP64)

# Enable cuStateVec (Qiskit Aer)
gpu = GPUConfig(enabled=True, custatevec=True)

GPU Support by Backend

Backend	GPU Library	Auto-selected target / device
CudaQBackend	CUDA-Q (native)	"nvidia", "nvidia-fp64", "nvidia-mqpu"
QiskitBackend	qiskit-aer-gpu	AerSimulator(device='GPU')
CirqBackend	qsimcirq	QSimSimulator(use_gpu=True)
PennyLaneBackend	pennylane-lightning[gpu]	"lightning.gpu"
BraketBackend	(not available)	(cloud-managed hardware)
IonQBackend	(not available)	(cloud-managed trapped-ion hardware)

Working with Results

result = hlquantum.run(bell, shots=1000)

result.counts           # {'00': 512, '11': 488}
result.probabilities    # {'00': 0.512, '11': 0.488}
result.most_probable    # '00'
result.expectation_value()  # 1.0 (parity-based)
result.shots            # 1000
result.backend_name     # 'qiskit (aer_simulator)'

# State Vector (Simulators only)
result = hlquantum.run(bell, include_statevector=True)
sv = result.get_state_vector()
print(sv)  # [0.707+0j, 0, 0, 0.707+0j]

# Transpilation & Error Mitigation
from hlquantum.mitigation import ThresholdMitigation

result = hlquantum.run(
    bell,
    transpile=True,
    mitigation=ThresholdMitigation(threshold=0.01)
)

Adding a Custom Backend

from hlquantum.backends import Backend
from hlquantum.circuit import QuantumCircuit
from hlquantum.result import ExecutionResult

class MyBackend(Backend):
    @property
    def name(self) -> str:
        return "my_backend"

    def run(self, circuit: QuantumCircuit, shots: int = 1000, **kwargs) -> ExecutionResult:
        # Translate circuit.gates → your framework
        # Execute and collect counts
        return ExecutionResult(counts={"00": shots}, shots=shots, backend_name=self.name)

Documentation

Full documentation — including API reference for all modules (circuits, backends, algorithms, layers, workflows, transpiler, mitigation, GPU) and runnable examples — is available via MkDocs:

pip install ".[dev]"
mkdocs serve

Sponsors

HLQuantum is made possible with the support of our sponsors. If you'd like to support this project, please reach out.

	Sponsor	Description
	Venture Chain	Supporting initial development effort & release

License

Apache License 2.0 — see LICENSE for details.