panta-sim 1.6.0

Full Rust core quantum circuit simulator with Python bindings

panta-sim

풀 Rust 코어 + Python 바인딩으로 작성한 양자 회로 시뮬레이터. Full state vector + density matrix + MPS + stabilizer + tensor-network + cross-platform GPU (wgpu) 지원. v1.0+ 안정 API (semver, docs/api-stability.md).

Qiskit Aer 대비 bit-exact + 전 영역 추월 (검증): dense statevector(gate fusion 으로 N≥20 에서 Aer 추월), stabilizer(~40×), MPS(~5×). examples/benchmarks/vs_aer.py 참조.

• Rust 코어: num-complex 기반 상태 벡터, qubit-wise multiplication
• gate fusion (v1.1~v1.3): 연속 1q + 1q→2q 흡수로 statevector sweep 감소 → dense 에서 Aer 추월 (bit-exact 유지)
• 멀티스레드: rayon 으로 게이트 적용 병렬화 (v0.2.0~), Python GIL 해제
• f32/f64 정밀도 선택 (v0.2.1~): qc.run(precision="f32") 로 메모리 50% 절감
• OpenQASM 2.0/3.0 import / export (v0.3.0~), 트랜스파일러 (Z-Y-Z 분해)
• 시각화: 회로 다이어그램, 측정 히스토그램, Bloch sphere (v0.3~)
• 외부 프레임워크 어댑터: Qiskit / PennyLane / Cirq (v0.3.5~), Aer NoiseModel
• 노이즈 모델 (v0.4~): 4 채널 stochastic trajectory (BitFlip / PhaseFlip / Depolarizing / AmplitudeDamping)
• Mid-circuit measurement / classical control / reset (v0.4.5~), block-form control flow (if_test / while_loop / for_loop / switch, v0.4.7~)
• Density matrix backend (v0.5.0~): qc.run(method="density_matrix") 로 noise 결정적 Kraus 적용, Aer 와 ‖ρ‖ < 1e-10 일치
• GPU 가속 (wgpu Tier-1, v0.5.0~): qc.run(method="wgpu") — cross-platform NVIDIA / AMD / Intel / Apple Silicon, Vulkan / DX12 / Metal 자동 선택. statevector + density matrix 모두 지원, buffer split 으로 32 큐비트 까지 동작 (v0.5.18, 아래 백엔드 표 참조).
• Python API: PyO3 + maturin, NumPy 연동
• 합성·변분·동역학 (v0.7.2~): 임의 unitary 분해 (KAK/QSD), 임의 상태 초기화 (Möttönen), 심볼릭 Parameter, 다중 제어 게이트, 커스텀 Kraus 채널, SPSA/일반 QAOA, 해밀토니안 빌더 + Trotter 시간 진화, 관측량 분산/상관
• Tensor Network Contraction 엔진 (v0.8~): qc.run(method="tensornet") / qc.amplitude(bitstring) / qc.amplitudes(bitstrings) / qc.expectation_tn(H) — MPS 가 못 하는 deep / high-entanglement 회로를 회로 자체를 tensor network 으로 표현해 contraction 으로 시뮬 (greedy / random-greedy / SA / multilevel partition / optimal / hyper path optimizer + 자동 slicing + cross-platform wgpu GPU contraction). 64-큐비트 2D 회로 amplitude + 분산 슬라이싱.
• Stabilizer (Clifford) 백엔드 (v0.8.2~): qc.run(method="stabilizer") — Aaronson–Gottesman tableau 로 Clifford 회로를 다항시간 시뮬레이션해 수천~ 수만 큐비트 까지 동작 (Gottesman–Knill). depolarizing=p 로 수천 큐비트 noisy Clifford (오류정정 코드 임계값 연구, v0.8.16).
• near-Clifford (Clifford+T) 백엔드 (v0.8.7~): qc.clifford_t_amplitude(x, low_rank=True) / qc.clifford_t_expectation(H) — Bravyi–Gosset stabilizer-rank (2^{⌈t/2⌉}) 로 큰 N · 적은 T 회로의 진폭·기댓값을 전역 위상까지 정확히 계산 (TN 이 못 하는 high-treewidth + 저-T 영역). qc.clifford_t_sample(shots) (v0.8.17) 는 Metropolis-Hastings MCMC 로 ∝|⟨x|ψ⟩|² 측정 분포를 샘플링 (아핀-구조 제안으로 GHZ 류 다봉 분포도 정확).
• 자동 백엔드 선택 (v0.8.5~): qc.run(method="auto") — 회로 분석으로 statevector / stabilizer / density / mps 자동 선택.
• 표준 알고리즘 라이브러리 (v0.8.14~): panta_sim.algorithms — QFT / Grover / QPE / Draper 덧셈기 / Bernstein–Vazirani / Deutsch–Jozsa / GHZ·W 상태 (Qiskit 교차검증, 전 백엔드 호환).
• CX-basis transpile 패스 (v0.8.3~): qc.transpile_to_basis("cx") — 모든 2/3-큐비트 게이트를 CX + 1q 로 자동 분해 (하드웨어 타깃).
• Pauli propagation (Heisenberg, v1.1~v1.3): qc.expectation(H, method="pauli_propagation", pp_threshold=, pp_depolarizing=) — 관측량을 역전파해 ⟨0|U†HU|0⟩ 추정. weighted Pauli 합 표현이라 얽힘 무관 (TN 보완재) → 큰 N · 저 비-Clifford (VQE/동역학, 예: 100큐비트 TFIM ⟨Z⟩). swap/iswap/cy/ccx/cswap, depolarizing 노이즈 (density Tr(ρH) 1e-15 일치), Monte-Carlo 무편향 변형 (pauli_propagation_expectation_mc). arXiv:2505.21606.
• RCS / Linear·Noisy XEB 벤치마크 (v0.8.1~): random_circuit / linear_xeb / xeb_ideal / xeb_noisy (Google supremacy-style cross-entropy benchmarking).
• 검증: 1700+ pytest + cargo test(전 크레이트), Qiskit/Aer cross-check 1e-9~1e-15 (StabilizerState / Operator.equiv / expectation_value / Statevector bit-exact / QFT 포함), wgpu vs CPU 1e-5 (f32 한계). fmt + clippy(-D warnings, toolchain 1.96 고정) clean.

설치

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 / Identity	h(q), id(q)
단일 큐비트	Pauli-X / Y / Z	x(q), y(q), z(q)
단일 큐비트	Phase / T (+ adjoint)	s(q), sdg(q), t(q), tdg(q)
단일 큐비트	√X / √X† (v0.4.7)	sx(q), sxdg(q)
단일 큐비트	OpenQASM p / u2 / u (v0.4.7)	p(λ, q), u2(φ, λ, q), u(θ, φ, λ, q)
회전	Rx / Ry / Rz	rx(θ, q), ry(θ, q), rz(θ, q)
1큐비트 unitary	임의 2×2 행렬	unitary(matrix, q)
k큐비트 unitary (v0.7.2)	임의 2^k×2^k → native (KAK/QSD, 전 백엔드)	unitary(matrix, qubits, decompose=True)
2큐비트	CNOT / CZ / SWAP / iSWAP	cx(c, t), cz(a, b), swap(a, b), iswap(a, b)
2큐비트 회전 (v0.7)	RXX / RYY / RZZ	rxx(θ, a, b), ryy(θ, a, b), rzz(θ, a, b)
2큐비트 controlled (v0.4.7)	CY / CH	cy(c, t), ch(c, t)
2큐비트 controlled rotation (v0.4.7)	CRx / CRy / CRz / CP	crx(θ, c, t), cry(θ, c, t), crz(θ, c, t), cp(λ, c, t)
2큐비트 controlled-U (v0.4.7)	CU3 / CU	cu3(θ, φ, λ, c, t), cu(θ, φ, λ, γ, c, t)
3큐비트	Toffoli (CCX) / Fredkin (CSWAP)	ccx(c1, c2, t), cswap(c, t1, t2)
다중 제어 (v0.7.2)	Cⁿ(X) / Cⁿ(Z) / Cⁿ(P) — ancilla-free	mcx(controls, t), mcz(controls, t), mcp(λ, controls, t)
Reset / Dynamic (v0.4.5~)	reset / classical control	reset(q), <gate>().c_if(c, value)
Block control flow (v0.4.7)	if_test / while_loop / for_loop / switch	with qc.if_test((c, v)), with qc.while_loop(...) 등
측정	부분 / 전체 측정	measure(q, c), measure_all()
상태 초기화 (v0.7.2)	statevector / int / 라벨 (Qiskit 호환)	initialize(state, qubits=None)
회로 조작 (v0.7.2)	copy / 역회로 / 합성 / 거듭제곱	copy(), inverse(), compose(other, qubits=), power(n)

비트 순서 규약은 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
• vqe_h2.py — VQE 로 H₂ 분자 바닥상태 (chemical accuracy) (v0.7)
• qaoa_maxcut.py — QAOA MaxCut on C5 cycle (v0.7)
• mps/ghz_100_showcase.py — GHZ-100 (statevector OOM 영역) MPS sampling (v0.6.3)
• mps/qaoa_maxcut_ring.py — QAOA p=1 MaxCut on Ring N=30 (wraparound edge auto-handled) (v0.6.3)
• mps/hea_n30.py — Hardware-Efficient Ansatz, depth=5, N=30 + truncation error 비교 (v0.6.3)

python examples/bell_state.py
python examples/grover.py
python examples/qft.py
python examples/vqe_h2.py
python examples/qaoa_maxcut.py
python examples/mps/ghz_100_showcase.py
python examples/mps/qaoa_maxcut_ring.py
python examples/mps/hea_n30.py

변분 알고리즘 (VQE / QAOA) + 기댓값 (v0.7)

import numpy as np
from panta_sim import QuantumCircuit, VQE, maxcut_hamiltonian, qaoa_maxcut_ansatz

# 1) Observable 기댓값 — 2ⁿ 행렬 없이 statevector/density/MPS 에 직접 계산.
qc = QuantumCircuit(2)
qc.h(0).cx(0, 1)
print(qc.expectation({"ZZ": 1.0, "XX": 0.5}))   # ⟨ZZ⟩+0.5⟨XX⟩ (정확)
print(qc.expectation({"ZZ": 1.0}, shots=8000))  # shot-based 추정 (NISQ, shot noise)
#   method="mps" 로 N>20 대규모 회로도 (dense statevector 불필요)
#   method="density_matrix" 로 noisy 회로의 Tr(ρH)

# 1b) 임의 상태 초기화 (Qiskit initialize 호환) — 진폭 인코딩 (QML) 등.
qc = QuantumCircuit(2)
qc.initialize([0.5, 0.5, 0.5, 0.5])  # 균등 중첩 (statevector)
# qc.initialize(5, [0,1,2])          # 계산 기저 |101⟩ (O(k))
# qc.initialize("01")                # 라벨 (0 1 + - r l)

# 2) VQE — Hamiltonian 바닥상태.
H = {"II": -1.0523, "IZ": 0.3979, "ZI": -0.3979, "ZZ": -0.0113, "XX": 0.1809}
def ansatz(p):
    qc = QuantumCircuit(2)
    qc.ry(p[0], 0).ry(p[1], 1).cx(0, 1).ry(p[2], 0).ry(p[3], 1)
    return qc
vqe = VQE(ansatz, H, optimizer="gradient-descent", gradient="parameter-shift")
res = vqe.run(np.random.default_rng(0).uniform(0, 2*np.pi, 4))
print(res.optimal_value)   # ≈ FCI ground-state energy

# 3) QAOA MaxCut 템플릿.
edges = [(0,1),(1,2),(2,0)]
H = maxcut_hamiltonian(edges, 3)
ansatz = qaoa_maxcut_ansatz(edges, 3, p=2)

# 4) PennyLane autodiff — diff_method="parameter-shift" 로 qml.grad 동작.
# 5) panta_sim.quantum_info — state_fidelity / partial_trace / entropy / trace_distance.

# 6) 심볼릭 Parameter — 파라메트릭 회로를 한 번 만들고 값 대입 (Qiskit 패턴).
from panta_sim import Parameter
a, b = Parameter("a"), Parameter("b")
ansatz = QuantumCircuit(2)
ansatz.ry(a, 0).ry(b, 1).cx(0, 1)        # 심볼릭으로 빌드
bound = ansatz.assign_parameters({a: 0.5, b: 1.2})   # 값 대입 → 실행 가능
vqe = VQE(ansatz, H)                      # VQE 가 파라메트릭 회로 직접 수용

프로젝트 구조

quantum-sim/
├── crates/
│   ├── core/              상태 벡터, density matrix, 게이트 행렬, 노이즈 Kraus
│   ├── simulator/         시뮬레이션 엔진, 측정, 회로 실행기, gate fusion
│   ├── transpiler/        ZYZ/CX/IBM-basis 분해, peephole 최적화
│   ├── qasm/              OpenQASM 2.0/3.0 파서·익스포터
│   ├── gpu/               wgpu Tier-1 + cuStateVec Tier-2 백엔드
│   ├── mps/               MPS (Matrix Product State) 코어
│   ├── tensornet/         Tensor Network Contraction 엔진
│   ├── stabilizer/        Stabilizer tableau + near-Clifford + CH-form
│   └── python-binding/    PyO3 바인딩
├── python/panta_sim/      사용자용 Python 라이브러리
├── tests/                 pytest 통합 테스트
├── examples/              사용 예제 + validation/ + benchmarks/
└── docs/                  설계 문서 (plan.md, architecture.md, references.md)

Backend 선택

qc.run(method=...) 으로 backend 선택 (method="auto" 는 회로 분석 자동 선택):

qc.run(method="statevector")           # 기본 — CPU rayon, f64 default
qc.run(method="density_matrix")        # CPU density matrix (Aer 와 동일 의미)
qc.run(method="wgpu")                  # GPU statevector (Vulkan / DX12 / Metal)
qc.run(method="wgpu_density_matrix")   # GPU density matrix
qc.run(method="mps")                   # MPS (저얽힘 대규모 N)
qc.run(method="wgpu_mps")              # GPU-resident MPS
qc.run(method="stabilizer")            # Clifford tableau (수천 큐비트)
qc.run(method="tensornet")             # Tensor Network contraction
qc.run(method="cuda")                  # cuStateVec (feature gpu-cuda)
qc.run(method="auto")                  # 자동 선택

Backend	메모리	최대 N (v0.5.20)	특징
statevector (CPU)	2ⁿ × 16B (f64)	RAM 한계 (~30)	기본, rayon 병렬
density_matrix (CPU)	4ⁿ × 16B	~14	noise 결정적 ρ, Aer ‖ρ‖ < 1e-10 일치
wgpu (GPU statevector)	2ⁿ × 8B (f32 강제)	32 (NVIDIA/AMD desktop) / 31 (Apple/Intel)	cross-platform, K=2/4/8/16/32 buffer split
wgpu_density_matrix	4ⁿ × 8B	~13	GPU 노이즈 시뮬
cuda (cuStateVec, gpu-cuda feature)	2ⁿ × 8B (f32) / 16B (f64)	32+ (NVIDIA only)	cuQuantum native, source 빌드 필요

N 한계 (wgpu Tier-1 의 K-buffer split, v0.5.20 시점)

N	sv 크기	K	binding	지원 GPU
≤27	≤1 GiB	1	2	모든 GPU
28	2 GiB	2	3	모든 GPU
29	4 GiB	4	5	모든 GPU
30	8 GiB	8	9	거의 모든 GPU
31	16 GiB	16	17	NVIDIA / AMD / Apple Metal / Intel Arc
32	32 GiB	32	33	NVIDIA / AMD desktop only (Apple Metal 31 binding 한계)

Cross-platform 외부 검증 (사용자 PC 보고)

Vendor	GPU	VRAM	검증 N	Driver	일자
NVIDIA	DGX Spark (GB10)	119 GiB unified	27~29	580.126.09 + Vulkan 1.4	2026-05-04
AMD	Radeon RX 6600 (RDNA 2)	8 GB	27~29 (8GB VRAM 한계)	Adrenalin 25.9.1 + Vulkan 1.4.315	2026-05-04
sandbox	lavapipe (Mesa SIMD)	host RAM	22 (시간상)	Mesa 26	모든 release

panta-sim 의 wgpu Tier-1 cross-platform claim 검증 — NVIDIA + AMD 두 vendor 모두 Qiskit Aer 와 max diff 1.21e-08 (f32 round-off) 일치 확인. Apple Silicon / Intel Arc 검증은 사용자 환경 가용성 따라 추가 예정.

Density matrix (v0.5.0~)

from panta_sim import QuantumCircuit, NoiseModel

qc = QuantumCircuit(2)
qc.h(0); qc.cx(0, 1)             # Bell |Φ+⟩

# Pure state ρ = |Φ+⟩⟨Φ+| (off-diagonal 0.5 살아 있음)
result = qc.run(shots=0, method="density_matrix")
rho = result.density_matrix()      # numpy (4, 4) complex128
print(rho)
# [[0.5+0.j 0+0.j 0+0.j 0.5+0.j]
#  [0+0.j  0+0.j 0+0.j 0+0.j ]
#  [0+0.j  0+0.j 0+0.j 0+0.j ]
#  [0.5+0.j 0+0.j 0+0.j 0.5+0.j]]

# Noise 가 있으면 결정적 Kraus 적용 — Aer method='density_matrix' 와 동치
qc2 = QuantumCircuit(1); qc2.id(0)
nm = NoiseModel().add_bit_flip(0.3)
rho = qc2.run(shots=0, noise_model=nm, method="density_matrix").density_matrix()
print(rho.diagonal().real)       # [0.7, 0.3] — shot noise 0

GPU 가속 (v0.5.0~)

method="wgpu" 는 cross-platform — NVIDIA / AMD / Intel / Apple Silicon 모두 동작. 별도 SDK / driver 추가 설치 불필요 (OS native GPU driver 만 있으면).

from panta_sim import QuantumCircuit
import time

qc = QuantumCircuit(25)
qc.h(0)
for q in range(24):
    qc.cx(q, q + 1)
qc.measure_all()

t0 = time.perf_counter(); qc.run(shots=100, seed=42)
print(f"CPU: {time.perf_counter() - t0:.2f}s")

t0 = time.perf_counter(); qc.run(shots=100, seed=42, method="wgpu")
print(f"GPU: {time.perf_counter() - t0:.2f}s")

GPU 환경에 따른 성능 (대략, 25 큐비트 GHZ 기준):

GPU 종류	wgpu vs CPU speedup
Discrete GPU (RTX 4090 / H100 등 별도 VRAM)	5~30× (메모리 BW 차이)
Apple M-series (unified memory)	2~5×
Integrated GPU (DGX Spark / 노트북 iGPU, 메모리 공유)	0.7~1.5× (CPU 와 비슷)

GPU 가 CPU 보다 반드시 빠른 것은 아니며, 환경 (특히 메모리 대역폭) 에 따라 차이. NVIDIA H100 같은 데이터센터 GPU 에서 가장 큰 이득.

GPU 한계 초과 시 친화적 ValueError (v0.5.1~). N≤32 는 K-buffer split 으로 자동 처리되고 (위 표), adapter 한계·VRAM 초과 시 CPU 사용을 안내하는 메시지와 함께 거부한다 (v0.5.19 pre-flight 메모리 warning).

성능

• CPU rayon: 멀티스레드 병렬화 (v0.2.0~), amplitude < 8192 (≈ 13 큐비트) 인 작은 회로는 직렬 폴백으로 회귀 0건 유지.
• f32 / f64 정밀도 선택 (v0.2.1+): qc.run(precision="f32") 로 메모리 ~50% 절감 → 같은 RAM 에서 큐비트 1개 더.
• GPU wgpu (v0.5.0~): K-buffer split 으로 32 큐비트까지 (v0.5.18, 위 백엔드 표 참조).
• gate fusion (v1.1~v1.3): 연속 게이트 흡수로 dense statevector 에서 Qiskit Aer 추월 (N=20 0.80×), bit-exact 유지.

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

로드맵 / 미구현

• v0.2 — CPU 성능 ✅ (rayon, f32) / SIMD ❌ (postmortem)
• v0.3 — OpenQASM 2.0/3.0, 트랜스파일러, 시각화 ✅ / v0.3.5 — Qiskit / PennyLane / Cirq 어댑터 ✅
• v0.4 — 노이즈 모델 ✅, mid-circuit measure / classical control / block control flow ✅
• v0.5 — Density matrix ✅, GPU wgpu Tier-1 (K-split N≤32) ✅, cuStateVec Tier-2 ✅
• v0.6 — MPS (CPU/GPU, 수천 큐비트 저얽힘) ✅
• v0.7 — VQE / QAOA + parameter-shift ✅, 네이티브 기댓값 ✅, quantum_info ✅, 합성 (KAK/QSD) ✅
• v0.8 — Tensor Network 엔진 ✅, stabilizer / near-Clifford ✅, 알고리즘 라이브러리 ✅, method="auto" ✅
• v1.0 — 정식 안정 릴리스, 공개 API 동결 ✅
• v1.1~v1.4 — gate fusion (Aer 추월) ✅, Pauli propagation ✅, IBM basis transpile ✅
• 남은 항목 — 실 QPU 연동 (IBM Runtime / Azure), PyPI cuda wheel (docs/next-steps.md)

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

참고 자료

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