Metadata-Version: 2.4
Name: hlquantum
Version: 0.1.3
Summary: HLQuantum (High Level Quantum) — A high-level Python package for working with quantum hardware using CUDA-Q and other backends.
Author-email: AlinDFerenczi <alindanielferenczi@gmail.com>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.10
Requires-Dist: numpy
Requires-Dist: scipy
Provides-Extra: all
Requires-Dist: amazon-braket-sdk; extra == 'all'
Requires-Dist: cirq; extra == 'all'
Requires-Dist: mcp; extra == 'all'
Requires-Dist: pennylane; extra == 'all'
Requires-Dist: qiskit; extra == 'all'
Requires-Dist: qiskit-aer; extra == 'all'
Requires-Dist: scipy; extra == 'all'
Provides-Extra: braket
Requires-Dist: amazon-braket-sdk; extra == 'braket'
Provides-Extra: cirq
Requires-Dist: cirq; extra == 'cirq'
Provides-Extra: cudaq
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: isort; extra == 'dev'
Requires-Dist: mkdocs; extra == 'dev'
Requires-Dist: mkdocs-material; extra == 'dev'
Requires-Dist: mkdocstrings[python]; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Provides-Extra: ionq
Requires-Dist: qiskit; extra == 'ionq'
Requires-Dist: qiskit-ionq; extra == 'ionq'
Provides-Extra: mcp
Requires-Dist: mcp; extra == 'mcp'
Provides-Extra: pennylane
Requires-Dist: pennylane; extra == 'pennylane'
Provides-Extra: qiskit
Requires-Dist: qiskit; extra == 'qiskit'
Requires-Dist: qiskit-aer; extra == 'qiskit'
Provides-Extra: scipy
Requires-Dist: scipy; extra == 'scipy'
Description-Content-Type: text/markdown

# 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](https://nvidia.github.io/cuda-quantum) | `pip install hlquantum[cudaq]`     |
| `QiskitBackend`    | [IBM Qiskit](https://qiskit.org)                       | `pip install hlquantum[qiskit]`    |
| `CirqBackend`      | [Google Cirq](https://quantumai.google/cirq)           | `pip install hlquantum[cirq]`      |
| `BraketBackend`    | [Amazon Braket](https://aws.amazon.com/braket/)        | `pip install hlquantum[braket]`    |
| `PennyLaneBackend` | [Xanadu PennyLane](https://pennylane.ai)               | `pip install hlquantum[pennylane]` |
| `IonQBackend`      | [IonQ](https://ionq.com) (via qiskit-ionq)             | `pip install hlquantum[ionq]`      |

## Installation

```bash
# 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:

```python
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](docs/api/algorithms.md) 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.

```python
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.

```python
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:

```python
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.

```python
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:

```python
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

```python
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)

```python
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)

```python
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

```python
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)

```python
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

```python
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:

```python
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

```python
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

```python
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:

```bash
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**](https://venture-chain.com) | Supporting initial development effort & release |

## License

Apache License 2.0 — see [LICENSE](LICENSE) for details.
