Metadata-Version: 2.4
Name: computingvista-qservice
Version: 0.3.1
Summary: Official Python SDK for Computing Vista's quantum cloud service (OpenQASM job execution)
License: MIT
Project-URL: Homepage, https://computingvista.com
Project-URL: Repository, https://github.com/thinhqdinh/computingvista-qservice
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25
Dynamic: license-file

# computingvista-qservice

Python SDK chính thức của [Computing Vista](https://computingvista.com) — submit OpenQASM từ Jupyter/VS Code local, chạy trên Computing Vista Cloud.

## Cài đặt

```bash
pip install computingvista-qservice
```

Hoặc từ local clone (dev):

```bash
pip install -e .
```

## Sử dụng

Lấy API key tại `computingvista.com/dashboard/developer`.

```python
from computingvista_qservice import QuantumClient

qc = QuantumClient(token="qkey_live_...")  # hoặc set env QUANTUM_SERVICE_TOKEN

print(qc.get_usage())
# {'used_shots': 2000, 'max_shots': 100000, 'remaining_shots': 98000}

result = qc.run_qasm("""
OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0],q[1];
measure q -> c;
""", shots=1000)

print(result["counts"])
```

`run_qasm` raise `QuotaExceededError` khi vượt hạn mức trial, `QuantumServiceError` cho lỗi khác.

## Tham số QAOA pretrained

`get_qaoa_params` là hàm duy nhất bạn cần biết. Đưa vào một đồ thị, nhận lại góc (γ, β) đã pretrain cho MaxCut — không phải chạy optimizer:

```python
import networkx as nx
from computingvista_qservice import get_qaoa_params

G = nx.random_regular_graph(3, 12)
gamma, beta, confidence = get_qaoa_params(G, p=3)
```

`G` là `networkx.Graph` (đọc attribute `weight` nếu có), hoặc list cạnh `[(i, j), ...]` / `[(i, j, weight), ...]` — networkx **không** phải dependency của SDK.

Dựng mạch bằng framework nào bạn đang dùng cũng được. Convention:

```
U_C(γ_k) = exp(-i·γ_k·Σ_cạnh w_ij·Z_iZ_j)      →  cx i,j; rz(2·γ_k·w_ij) j; cx i,j
U_B(β_k) = exp(-i·β_k·Σ_i X_i)                 →  rx(2·β_k) trên mọi qubit
```

Áp lần lượt từng lớp lên `|+⟩^n`; qubit thứ k ứng với đỉnh thứ k theo thứ tự sorted. Dấu và các hệ số 2 là **một phần của convention** — các bảng góc đã công bố không thống nhất về cả hai, nên hãy kiểm tra một ca đã biết trước khi tin bản port sang convention khác: đồ thị 3-regular không trọng số ở p=1 phải đạt approximation ratio ≈ 0.69.

`confidence` cho biết có nên tốn shots tinh chỉnh không:

| | Ý nghĩa |
| --- | --- |
| `"high"` | Chạy thẳng. Gap đo được so với góc tối ưu ~0.1–2 điểm % |
| `"medium"` | Điểm khởi đầu tốt. Đồ thị có hub hoặc trọng số đuôi nặng mất ~2–18 điểm %, phần lớn lấy lại được bằng một lần quét 1 chiều |
| `"low"` | Chỉ là khởi tạo, cần optimizer đầy đủ 2p chiều |

Nguồn: bảng fixed-angle cho đồ thị d-regular (Wurtz-Lykov, [arXiv:2107.00677](https://arxiv.org/abs/2107.00677)), median 261k đồ thị 9 đỉnh (QAOAKit) + rescale theo bậc/trọng số ([arXiv:2201.11785](https://arxiv.org/abs/2201.11785)), nội suy schedule cho p>3.

## Mã lỗi

`QuantumServiceError` mang theo `error` từ response:

| `error` | HTTP | Ý nghĩa |
| --- | --- | --- |
| `invalid_or_missing_token` | 401 | Thiếu hoặc sai API token |
| `invalid_request` | 400 | Body thiếu `qasm` hoặc `shots` không hợp lệ |
| `invalid_qasm` | 400 | Không phải OpenQASM 2.x hợp lệ (cần header `OPENQASM 2.x;` và ít nhất 1 `qreg`) |
| `too_many_qubits` | 400 | Vượt giới hạn qubit của free tier |
| `too_many_gates` | 400 | Vượt giới hạn số cổng của free tier |
| `quota_exceeded` | 429 | Vượt hạn mức shot của trial (`QuotaExceededError`) |
| `execution_error` | 502 | Backend chạy circuit thất bại |
