Metadata-Version: 2.4
Name: qubecli
Version: 1.1.26
Summary: QubeCore CLI — Command Line Interface for QubeCore
License: MIT License
        
        Copyright (c) 2026 QubeCore Project
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: qubecore-client>=1.1.12
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# QubeCLI

QubeCLI는 QubeCore를 터미널에서 사용하는 공식 CLI입니다.  
서버 연결부터 인증, 작업 제출/조회, QPU 정보 조회, 캘리브레이션을 사용할 수 있습니다.

## 목차

- 설치
- 공통 명령
  - 기본 명령
  - 서버 연결
  - 인증
  - 정보 조회
  - 작업 목록
  - 작업 제어
- 게이트 제출
- 펄스 제출
- 리셋
- 캘리브레이션
  - 단일 캘리브레이션
    - 1) widescan
    - 2) punchout
    - 3) chevron
    - 4) amp-rabi
    - 5) time-rabi
    - 6) ramsey
    - 7) t1
    - 8) stack-x90
    - 9) drag-alpha
    - 10) blob-readout-freq
    - 11) readout-fidelity
    - 12) gate-fidelity
  - 다중 캘리브레이션
    - 1) full
    - 2) characterization

## 설치

```bash
pip install qubecli
```

---

## 공통 명령

### 기본 명령

| Command | Description |
|---|---|
| `qubecli` | 배너 출력 |
| `qubecli -v` / `--version` | 버전 확인 |
| `qubecli help` | 전체 명령 도움말 |

### 서버 연결

| Command | Description |
|---|---|
| `qubecli connect <host:port>` | QubeCore 서버 연결 |

### 인증

| Command | Description |
|---|---|
| `qubecli login` | 로그인 |
| `qubecli me` | 현재 로그인 사용자 정보 |
| `qubecli logout` | 로그아웃 |

### 정보 조회

| Command | Description |
|---|---|
| `qubecli qpu-info` | QPU 정보 (게이트, 결합 맵 등) |
| `qubecli qubit-info` | 큐비트 정보 (T1, T2, 주파수 등) |

### 작업 목록

| Command | Description |
|---|---|
| `qubecli jobs --page <page> --size <size>` | 작업 목록 조회 (default: page=1, size=20) |

### 작업 제어

| Command | Description |
|---|---|
| `qubecli status --job-id <job_id>` | 작업 상태 조회 |
| `qubecli result --job-id <job_id>` | 작업 결과 조회 |
| `qubecli cancel --job-id <job_id>` | 작업 취소 (PENDING만) |

---

## 게이트 제출

```bash
qubecli submit-gate --circuit '<CIRCUIT>' --shots <N>
```

| Option | Required | Description |
|---|---|---|
| `--circuit` / `--circuit-file` | O | OpenQASM 2.0 / 3.0, QIR, JSON |
| `--shots` | O | 샷 수 |
| `--optimization-level` | X | 트랜스파일 최적화 레벨 `0~3` (QIR에서는 무시) |
| `--params` | X | 파라미터 스윕용 JSON array (e.g. [{"param": 0.0}, {"param": 1.5707}]). circuit에 {param} placeholder 필요. QIR 사용 불가 |
| `--wait` | X | 제출 후 상태 폴링 → 결과 출력 |

```bash
# OpenQASM 2.0
qubecli submit-gate \
  --circuit '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

# OpenQASM 3.0
qubecli submit-gate \
  --circuit 'OPENQASM 3; include "stdgates.inc"; qubit[1] q; bit[1] c; h q[0]; c[0]=measure q[0];' \
  --shots 1000

# QIR (직접 입력)
qubecli submit-gate --circuit '<QIR_TEXT>' --shots 1000

# QIR (파일 입력)
qubecli submit-gate --circuit-file <QIR_FILE> --shots 1000

# JSON
qubecli submit-gate \
  --circuit '[{"name":"X90","qubit":"qubit_0"},{"name":"read","qubit":"qubit_0"}]' \
  --shots 1000

# Parametric sweep
qubecli submit-gate \
  --circuit 'OPENQASM 2.0; include "qelib1.inc"; qreg q[1]; creg c[1]; rx({theta}) q[0]; measure q[0]->c[0];' \
  --params '[{"theta": 0.0}, {"theta": 1.5707}, {"theta": 3.1415}]' \
  --shots 200
```

---

## 펄스 제출

```bash
qubecli submit-pulse --pulse '<JSON>' --shots <N>
```

| Option | Required | Description |
|---|---|---|
| `--pulse` | O | 펄스 게이트 JSON array |
| `--shots` | O | 샷 수 |
| `--wait` | X | 제출 후 상태 폴링 → 결과 출력 |

```bash
qubecli submit-pulse \
  --pulse '[{"name":"X90","qubit":"qubit_0"},{"name":"read","qubit":"qubit_0"}]' \
  --shots 1000
```

---

## 리셋

```bash
qubecli reset --shots <N>
```

| Option | Required | Description |
|---|---|---|
| `--shots` | O | 리셋 검증 샷 수 |
| `--qubits` | X | 대상 큐비트 (e.g. qubit_0,qubit_1, 생략 시 전체) |
| `--wait` | X | 제출 후 상태 폴링 → 결과 출력 |

```bash
# 전체 큐비트 리셋
qubecli reset --shots 100

# 특정 큐비트 리셋
qubecli reset --qubits qubit_0,qubit_1 --shots 100
```

---

## 캘리브레이션

### 단일 캘리브레이션

#### 1) widescan : 리드아웃 주파수 스캔

| Option | Required | Description |
|---|---|---|
| `--qubit` | O | 큐비트 이름 (e.g. qubit_0) |
| `--freq-span` | O | 리드아웃 주파수 스캔 범위 (Hz, e.g. 100000000) |
| `--n-freqs` | O | 주파수 스캔 포인트 수 (e.g. 200) |
| `--shots` | O | 샷 수 |
| `--wait` | X | 제출 후 상태 폴링 → 결과 출력 |

```bash
qubecli calibration widescan --qubit qubit_0 --freq-span 100000000 --n-freqs 200 --shots 100
```

#### 2) punchout : 리드아웃 진폭·주파수 2D 스캔

| Option | Required | Description |
|---|---|---|
| `--qubit` | O | 큐비트 이름 (e.g. qubit_0) |
| `--amps` | O | 리드아웃 진폭 JSON array (e.g. [0.01,0.05,0.1]) |
| `--freq-span` | O | 리드아웃 주파수 스캔 범위 (Hz, e.g. 20000000) |
| `--n-freqs` | O | 주파수 스캔 포인트 수 (e.g. 20) |
| `--shots` | O | 샷 수 |
| `--wait` | X | 제출 후 상태 폴링 → 결과 출력 |

```bash
qubecli calibration punchout --qubit qubit_0 --amps '[0.01,0.05,0.1]' --freq-span 20000000 --n-freqs 20 --shots 100
```

#### 3) chevron : 구동 주파수–펄스 폭 2D 스캔

| Option | Required | Description |
|---|---|---|
| `--qubit` | O | 큐비트 이름 (e.g. qubit_0) |
| `--freq-span` | O | 구동 주파수 스캔 범위 (Hz, e.g. 1000000) |
| `--n-freqs` | O | 주파수 스캔 포인트 수 (e.g. 20) |
| `--x-twidth` | O | X 펄스 폭 JSON array (s, e.g. [1e-8,2e-8,3e-8]) |
| `--shots` | O | 샷 수 |
| `--center-freq` | X | 구동 중심 주파수 (Hz, e.g. 4.85e9) |
| `--wait` | X | 제출 후 상태 폴링 → 결과 출력 |

```bash
qubecli calibration chevron --qubit qubit_0 --freq-span 1000000 --n-freqs 20 --x-twidth '[1e-8,2e-8,3e-8]' --shots 100
```

#### 4) amp-rabi : Rabi 진폭 스윕 (X90 진폭 보정)

| Option | Required | Description |
|---|---|---|
| `--qubit` | O | 큐비트 이름 (e.g. qubit_0) |
| `--n-amps` | O | X90 진폭 스윕 분할 수 (e.g. 20) |
| `--shots` | O | 샷 수 |
| `--target-twidth` | X | X90 목표 펄스 폭 (s, e.g. 2e-8) |
| `--amp-range-min` | X | X90 진폭 스윕 최솟값 (default: 0.0) |
| `--amp-range-max` | X | X90 진폭 스윕 최댓값 (default: 1.0) |
| `--wait` | X | 제출 후 상태 폴링 → 결과 출력 |

```bash
qubecli calibration amp-rabi --qubit qubit_0 --n-amps 20 --shots 100
```

#### 5) time-rabi : Rabi 시간 스윕 (X90 펄스 폭 보정)

| Option | Required | Description |
|---|---|---|
| `--qubit` | O | 큐비트 이름 (e.g. qubit_0) |
| `--shots` | O | 샷 수 |
| `--x-twidth` | X | X90 펄스 폭 JSON array (s, e.g. [1e-8,2e-8,3e-8]) |
| `--target-amplitude` | X | X90 목표 진폭 (e.g. 0.5) |
| `--wait` | X | 제출 후 상태 폴링 → 결과 출력 |

```bash
qubecli calibration time-rabi --qubit qubit_0 --shots 100
```

#### 6) ramsey : Ramsey 간섭 (주파수·위상 드리프트)

| Option | Required | Description |
|---|---|---|
| `--qubit` | O | 큐비트 이름 (e.g. qubit_0) |
| `--delay-interval` | O | Ramsey 대기 시간 JSON array (s, e.g. [1e-6,2e-6,3e-6]) |
| `--shots` | O | 샷 수 |
| `--framsey-offsets` | X | Ramsey 주파수 오프셋 JSON array (Hz, e.g. [-200000,0,200000]) |
| `--wait` | X | 제출 후 상태 폴링 → 결과 출력 |

```bash
qubecli calibration ramsey --qubit qubit_0 --delay-interval '[1e-6,2e-6,3e-6]' --shots 100
```

#### 7) t1 : T1 이완 시간 측정

| Option | Required | Description |
|---|---|---|
| `--qubit` | O | 큐비트 이름 (e.g. qubit_0) |
| `--delay-interval` | O | T1 대기 시간 JSON array (s, e.g. [1e-6,2e-6,3e-6]) |
| `--shots` | O | 샷 수 |
| `--wait` | X | 제출 후 상태 폴링 → 결과 출력 |

```bash
qubecli calibration t1 --qubit qubit_0 --delay-interval '[1e-6,2e-6,5e-6]' --shots 100
```

#### 8) stack-x90 : X90 게이트 스택 (미세 보정)

| Option | Required | Description |
|---|---|---|
| `--qubit` | O | 큐비트 이름 (e.g. qubit_0) |
| `--shots` | O | 샷 수 |
| `--wait` | X | 제출 후 상태 폴링 → 결과 출력 |

```bash
qubecli calibration stack-x90 --qubit qubit_0 --shots 100
```

#### 9) drag-alpha : DRAG α 파라미터 보정

| Option | Required | Description |
|---|---|---|
| `--qubit` | O | 큐비트 이름 (e.g. qubit_0) |
| `--shots` | O | 샷 수 |
| `--alphas` | X | DRAG α JSON array (e.g. [-0.5,0.0,0.5]) |
| `--wait` | X | 제출 후 상태 폴링 → 결과 출력 |

```bash
qubecli calibration drag-alpha --qubit qubit_0 --shots 100
```

#### 10) blob-readout-freq : 리드아웃 주파수 보정

| Option | Required | Description |
|---|---|---|
| `--qubit` | O | 큐비트 이름 (e.g. qubit_0) |
| `--shots` | O | 샷 수 |
| `--dfreads` | X | 리드아웃 주파수 오프셋 JSON array (Hz, e.g. [-1e6,0,1e6]) |
| `--wait` | X | 제출 후 상태 폴링 → 결과 출력 |

```bash
qubecli calibration blob-readout-freq --qubit qubit_0 --shots 100
```

#### 11) readout-fidelity : 리드아웃 충실도 측정

| Option | Required | Description |
|---|---|---|
| `--qubit` | O | 큐비트 이름 (e.g. qubit_0) |
| `--shots` | X | 샷 수 (default: 1000) |
| `--wait` | X | 제출 후 상태 폴링 → 결과 출력 |

```bash
qubecli calibration readout-fidelity --qubit qubit_0
```

#### 12) gate-fidelity : 게이트 충실도 측정 (RB)

| Option | Required | Description |
|---|---|---|
| `--qubit` | O | 큐비트 이름 (e.g. qubit_0) |
| `--shots` | X | 샷 수 (default: 100) |
| `--lengths` | X | RB Clifford 시퀀스 길이 JSON array (e.g. [1,2,4,8,16,32]) |
| `--n-seeds` | X | 시퀀스 길이별 랜덤 시드 수 (e.g. 5) |
| `--seed-base` | X | RB 랜덤 시드 시작값 (e.g. 42) |
| `--wait` | X | 제출 후 상태 폴링 → 결과 출력 |

```bash
qubecli calibration gate-fidelity --qubit qubit_0
```

### 다중 캘리브레이션

#### 1) full : 전체 캘리브레이션

`widescan` -> `punchout` -> `chevron` -> `amp-rabi` -> `time-rabi` -> `ramsey` -> `t1` -> `drag-alpha` -> `stack-x90` -> `blob-readout-freq` -> `readout-fidelity` -> `gate-fidelity`

| Option | Required | Description |
|---|---|---|
| `--qubits` | X | 대상 큐비트 (e.g. qubit_0,qubit_1, 생략 시 전체) |
| `--wait` | X | 제출 후 상태 폴링 → 결과 출력 |
| `--timeout` | X | `--wait` 폴링 타임아웃 (초, default: 7200 = 2h) |

```bash
qubecli calibration full
```

#### 2) characterization : 4단계 캘리브레이션

`readout-fidelity` -> `t1` -> `ramsey` -> `gate-fidelity`

| Option | Required | Description |
|---|---|---|
| `--qubits` | X | 대상 큐비트 (e.g. qubit_0,qubit_1, 생략 시 전체) |
| `--wait` | X | 제출 후 상태 폴링 → 결과 출력 |

```bash
qubecli calibration characterization
```
