panta-sim 0.3.0

Full Rust core quantum circuit simulator with Python bindings

panta-sim

풀 Rust 코어 + Python 바인딩으로 작성한 양자 회로 시뮬레이터. Full state vector 방식으로 단일 머신에서 30큐비트 회로까지 시뮬레이션 한다 (충분한 RAM 기준).

• Rust 코어: num-complex 기반 상태 벡터, qubit-wise multiplication
• 멀티스레드: rayon 으로 게이트 적용 병렬화 (v0.2.0~), Python GIL 해제
• f32/f64 정밀도 선택 (v0.2.1~): qc.run(precision="f32") 로 메모리 ~50% 절감 → 같은 RAM 에서 큐비트 1개 더
• Python API: PyO3 + maturin, NumPy 연동
• 검증: 145 pytest (f32/f64 양쪽) + 93 케이스 광범위 Qiskit 교차검증 (f64 < 1e-10, f32 < 1e-5)

설치

pip install panta-sim

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

소스에서 직접 빌드하려면:

# 사전 요구 사항: 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 .

빠른 시작

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 를 반환하므로 메서드 체이닝도 가능하다:

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 의 인덱스는 동일한 비트열을 정수로 해석한 값이다.

빌드 / 테스트

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

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)

성능 (v0.2.1)

rayon 으로 게이트 적용을 멀티스레드 병렬화. amplitude < 8192 (≈ 13 큐비트) 인 작은 회로는 직렬 폴백으로 회귀 0건 유지.

f32 / f64 정밀도 선택 (v0.2.1+):

from panta_sim import QuantumCircuit
qc = QuantumCircuit(30)
qc.h(0)
for i in range(1, 30):
    qc.cx(0, i)

# f64 (default) — 16 bytes/amp, 정확도 < 1e-15
result = qc.run(shots=0)                   # ≈ 16 GB state @ 30 qubits
print(result.statevector().dtype)          # complex128

# f32 — 8 bytes/amp, 정확도 < 1e-5, 같은 RAM 으로 큐비트 1개 더
result = qc.run(shots=0, precision="f32")  # ≈ 8 GB state @ 30 qubits
print(result.statevector().dtype)          # complex64

머신	30 큐비트 GHZ statevector	31 큐비트 (f32, v0.2.1)
16 GB / 32GB+ RAM, 다코어	약 1분	(16 GB state, f32 로 가능)

자세한 벤치는 benches/results/ 와 examples/validation/RESULTS.md 참고.

로드맵 / 미구현

• v0.2 — CPU 성능 (rayon ✅ / f32 ✅ / SIMD)
• v0.3 — OpenQASM 2.0/3.0, 트랜스파일러, 시각화
• v0.4 — 노이즈 모델
• v0.5 — GPU (wgpu / cudarc) → 30+ 큐비트
• v0.6 — Tensor Network / MPS

상세 로드맵은 docs/plan.md 참고.

참고 자료

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