Metadata-Version: 2.4
Name: panta-sim
Version: 0.1.1
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Dist: numpy>=1.20
License-File: LICENSE
Summary: Full Rust core quantum circuit simulator with Python bindings
Keywords: quantum,simulator,quantum-computing,rust,pyo3
Author: quantumfia
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Issues, https://github.com/quantumfia/quantum-sim/issues
Project-URL: Repository, https://github.com/quantumfia/quantum-sim

# panta-sim

[![PyPI](https://img.shields.io/pypi/v/panta-sim.svg)](https://pypi.org/project/panta-sim/)
[![Python](https://img.shields.io/pypi/pyversions/panta-sim.svg)](https://pypi.org/project/panta-sim/)
[![CI](https://github.com/quantumfia/quantum-sim/actions/workflows/ci.yml/badge.svg)](https://github.com/quantumfia/quantum-sim/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/pypi/l/panta-sim.svg)](https://github.com/quantumfia/quantum-sim/blob/main/LICENSE)

풀 Rust 코어 + Python 바인딩으로 작성한 양자 회로 시뮬레이터.
Full state vector 방식으로 20~25큐비트 회로를 정확히 시뮬레이션 한다.

- **Rust 코어**: `num-complex` 기반 상태 벡터, qubit-wise multiplication
- **Python API**: PyO3 + maturin, NumPy 연동
- **검증**: 100+ pytest + Qiskit statevector 교차검증 (오차 < 1e-10)

## 설치

```bash
pip install panta-sim
```

Linux (x86_64, aarch64) / macOS (Apple Silicon) / Windows (x64) 에서 Python 3.9~3.13 미리 빌드된 wheel 을 제공한다. Rust toolchain 은 필요 없다.

> 소스에서 직접 빌드하려면:
>
> ```bash
> # 사전 요구 사항: Rust toolchain (rustup), Python >= 3.9, maturin
> pip install maturin
> git clone https://github.com/quantumfia/quantum-sim
> cd quantum-sim
> maturin develop --release   # 또는 pip install .
> ```

## 빠른 시작

```python
from panta_sim import QuantumCircuit

# Bell state |Φ+⟩ = (|00⟩ + |11⟩)/√2
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

result = qc.run(shots=1024, seed=42)
print(result.counts())          # {'00': ~512, '11': ~512}
print(result.statevector())     # [0.707+0j, 0+0j, 0+0j, 0.707+0j]
print(result.probabilities())   # [0.5, 0, 0, 0.5]
```

`QuantumCircuit` 의 게이트 메서드는 모두 self 를 반환하므로 메서드 체이닝도 가능하다:

```python
counts = (
    QuantumCircuit(3)
    .h(0)
    .cx(0, 1)
    .cx(0, 2)
    .measure_all()
    .run(shots=1024, seed=0)
    .counts()
)
```

> `pip install panta-sim` (배포 이름) → `import panta_sim` (Python 모듈 이름).

## 지원 게이트

| 분류 | 게이트 | 메서드 |
| --- | --- | --- |
| 단일 큐비트 | Hadamard | `h(q)` |
| 단일 큐비트 | Pauli-X / Y / Z | `x(q)`, `y(q)`, `z(q)` |
| 단일 큐비트 | Phase / T | `s(q)`, `t(q)` |
| 단일 큐비트 | Identity | `id(q)` |
| 회전 | Rx / Ry / Rz | `rx(theta, q)`, `ry(theta, q)`, `rz(theta, q)` |
| 2큐비트 | CNOT / CZ / SWAP | `cx(c, t)`, `cz(a, b)`, `swap(a, b)` |
| 3큐비트 | Toffoli (CCX) | `ccx(c1, c2, t)` |
| 3큐비트 | Fredkin (CSWAP) | `cswap(c, t1, t2)` |
| 측정 | 부분 / 전체 측정 | `measure(q, c)`, `measure_all()` |

비트 순서 규약은 Qiskit 과 동일한 little-endian 이다 (`q_{n-1} … q_1 q_0`).
`counts()` 의 키는 MSB-first 비트 문자열, statevector 의 인덱스는 동일한 비트열을 정수로 해석한 값이다.

## 빌드 / 테스트

```bash
cargo build --release          # Rust 전체 빌드
cargo test                     # Rust 유닛 테스트 (core + simulator)
maturin develop --release      # Python 바인딩 빌드 (개발 모드)
pytest tests/                  # Python 통합 테스트 + Qiskit 교차검증
pytest tests/ -v               # 상세 출력
```

Qiskit 교차검증 테스트는 `qiskit` 패키지가 설치되어 있을 때만 실행되며,
설치되어 있지 않으면 자동으로 skip 된다.

## 예제

`examples/` 디렉터리 참고:

- `bell_state.py` — Bell 상태 생성 및 측정
- `grover.py` — 2큐비트 Grover 탐색
- `qft.py` — Quantum Fourier Transform

```bash
python examples/bell_state.py
python examples/grover.py
python examples/qft.py
```

## 프로젝트 구조

```
quantum-sim/
├── crates/
│   ├── core/              상태 벡터, 게이트 행렬, 복소수 연산
│   ├── simulator/         시뮬레이션 엔진, 측정, 회로 실행기
│   └── python-binding/    PyO3 바인딩
├── python/panta_sim/      사용자용 Python 라이브러리
├── tests/                 pytest 통합 테스트
├── examples/              사용 예제
└── docs/                  설계 문서 (plan.md, architecture.md, references.md)
```

## 5월 스코프 밖 (현재 미구현)

트랜스파일러, 노이즈 모델, OpenQASM 파싱, GPU/멀티스레딩 가속,
회로 시각화, tensor network/MPS, 실제 QPU 연동.

## 참고 자료

- 설계 문서: [`docs/architecture.md`](docs/architecture.md)
- 개발 계획(WBS): [`docs/plan.md`](docs/plan.md)
- 참고 논문: [`docs/references.md`](docs/references.md)

