watermarkhu/qsurface

⚛️ Qsurface: Mô phỏng Surface Code với nhiều bộ giải mã và trực quan hóa tương tác

Gói Python cho nghiên cứu sửa lỗi lượng tử: mô-đun hóa surface code, mô hình lỗi và decoder — kèm đồ họa bước-दर-bước và benchmark tự động.

Qsurface là thư viện Python mã nguồn mở (82 sao trên GitHub) được phát triển bởi watermarkhu, tập trung vào việc mô phỏng surface code — một trong những mã sửa lỗi lượng tử hứa hẹn nhất cho máy tính lượng tử chịu lỗi. Điểm thiết kế cốt lõi là tách biệt ba thành phần: surface code (toric/planar), mô hình lỗi (bit-flip, phase-flip, đo lường sai...), và bộ giải mã (decoder). Kiến trúc này cho phép nhà nghiên cứu thay thế hoặc thêm mới từng phần độc lập thông qua template có sẵn.

✨ Điểm nổi bật

• 3 bộ giải mã tích hợp: MWPM (Minimum-Weight Perfect Matching), Union-Find (Delfosse-Nickerson, độ phức tạp gần tuyến tính), và UFNS (Union-Find Node-Suspension — cải tiến threshold gần ngang MWPM nhưng giữ độ phức tạp quasi-linear).
• Hỗ trợ 2 loại surface code: Toric code (biên tuần hoàn) và Planar code (biên mở) — cả ba decoder đều tương thích đầy đủ.
• Mô hình lỗi linh hoạt: Pauli errors (bitflip/phaseflip), faulty measurements, có thể bật/tắt từng loại qua tham số enabled_errors.
• Trực quan hóa tương tác 2D/3D: Matplotlib + Tkinter/PyQt5, cho phép lùi/tiến từng bước giải mã (nhấn h để xem phím tắt). 3D axis tự động bật khi có faulty measurements.
• Benchmarking tích hợp: Gắn BenchmarkDecoder để thu thập success rate, thời gian decode (mean/std), seed — xuất ra dict sẵn sàng phân tích.
• CLI sẵn sàng dùng: python -m qsurface -e pauli -D mwpm -C toric simulation --p_bitflip 0.1 -n 10 chạy mô phỏng ngay từ terminal.
• Tích hợp Blossom V tùy chọn: Hàm mwpm.get_blossomv() tự động tải và biên dịch thuật toán MWPM nhanh hơn (license riêng).
• Hỗ trợ Jupyter/Binder: Inline plotting từng iteration, có notebook ví dụ chạy thử trên Binder không cài đặt.

💡 Vì sao đáng chú ý

Qsurface giải quyết bài toán thực tế trong nghiên cứu QEC: so sánh decoder một cách công bằng và trực quan. Thay vì viết lại boilerplate cho mỗi bài toán, nhà nghiên cứu chỉ cần chọn code/error/decoder từ menu — phần còn lại (vòng lặp mô phỏng, thu thập thống kê, vẽ đồ thị) đã được chuẩn hóa. Đặc biệt, UFNS decoder là đóng góp thuật toán mới: nó nâng threshold của Union-Find lên gần MWPM mà vẫn giữ độ phức tạp gần tuyến tính — điều quan trọng cho surface code quy mô lớn nơi MWPM (O(n³)) trở nên chậm. Tính năng step-back trong đồ họa cũng giúp debug quy trình giải mã hiệu quả hơn so với chỉ xem kết quả cuối cùng.

#QuantumComputing #QuantumErrorCorrection #SurfaceCode #Python #OpenSource #TiniX