Metadata-Version: 2.4
Name: computingvista-qservice
Version: 0.3.0
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` trả về góc (γ, β) đã pretrain cho MaxCut — không cần chạy optimizer:

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

G = nx.random_regular_graph(3, 12)          # đồ thị MaxCut (hỗ trợ attribute "weight" trên cạnh)
gamma, beta, confidence = get_qaoa_params(G, p=3, family="maxcut")
```

Không có networkx thì truyền list cạnh `[(i, j), ...]` hoặc `[(i, j, weight), ...]` — networkx không phải dependency của SDK.

- `confidence="high"` — dùng one-shot luôn (gap đo được ~0.1–2 điểm % so với góc tối ưu)
- `"medium"` — nên tinh chỉnh nhẹ (ví dụ quét 7 điểm hệ số nhân trên γ, ~vài trăm shots)
- `"low"` — chỉ là điểm khởi tạo, cần optimizer đầy đủ

Sinh mạch và tinh chỉnh:

```python
from computingvista_qservice import QuantumClient, maxcut_qasm, refine_gamma_scale

qc = QuantumClient(token="qkey_live_...")

if confidence == "high":                       # chạy thẳng
    result = qc.run_qasm(maxcut_qasm(G, gamma, beta), shots=1000)
else:                                          # tinh chỉnh trước (~900 shots)
    r = refine_gamma_scale(qc, G, p=3)
    result = qc.run_qasm(maxcut_qasm(G, r["gamma"], r["beta"]), shots=1000)
```

`refine_gamma_scale` quét một hệ số nhân duy nhất trên γ (9 job) — với case `medium` thì *hình dáng* schedule đã đúng, chỉ sai thang độ lớn của γ. Trong mô phỏng, nó lấy lại tới ~20 điểm % và bám sát lưới quét 60 điểm trong ~0.3 điểm %, rẻ hơn optimizer 2p chiều khoảng 10 lần.

`cut_expectation(counts, G)` tính ⟨cut⟩ từ counts. Thứ tự bit của counts được `detect_bit_order` dò tự động bằng một job hiệu chuẩn 8 shots — đoán sai thứ tự này sẽ hoán vị đỉnh và làm sai mọi giá trị cut một cách âm thầm.

Nguồn: bảng fixed-angle cho đồ thị d-regular (Wurtz-Lykov, arXiv:2107.00677), median 261k đồ thị 9 đỉnh (QAOAKit) + rescale theo bậc/trọng số (arXiv:2201.11785), nội suy schedule cho p>3. Convention ghi trong docstring của module — kiểm tra bằng `tests/test_qaoa.py` (cần `numpy`, `networkx`).

## 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 |
