How quantumlib/qsim works
Project Type and Purpose
• This is a C++ library exposing high-performance simulation engines (CPU, GPU, fused gates, state‐vector).
• It provides a Python interface (pybind11) and a Cirq plugin (qsimcirq) to simulate quantum circuits.
• It also includes sample C++ CLI applications, test suites, documentation, CI/CD pipelines, and Docker setups.
• Core C++ Simulation Library (lib/)
– State-vector kernels (basic, SSE, AVX, AVX512, CUDA, Custatevec)
– Gate fusion and circuit parsers
– Utilities (I/O, multithreading via OpenMP, per-backend optimizations)
• Sample Applications (apps/)
– CLI executables linking against the core library for different use cases
• Python Binding Layer (pybind_interface/)
– Per-backend modules (basic, SSE, AVX2, AVX512, CUDA, HIP, Custatevec, Decide)
– Uses CMake + pybind11 to generate qsim extension packages
• Cirq Integration (qsimcirq/)
– Python package exposing a qsim_simulator and qsim_circuit to end users
– Depends on the Python extension module built by pybind_interface
• Circuits Input (circuits/)
– Sample circuits in various formats as test or tutorial inputs
• Tests
– C++ unit tests (tests/) using GoogleTest
– Python tests (qsimcirq_tests/) using pytest
• Third-Party Integrations
– Optional NVIDIA cuQuantum library (third_party/cuquantum/)
• Build & CI/CD
– Bazel (WORKSPACE, BUILD files) + CMakeLists.txt + Makefile
– GitHub workflows (.github/workflows/) for build, tests, formatting, releases
• Containerization
– Dockerfile, docker-compose.yml, Jupyter environment for interactive demos
• Documentation & Tutorials (docs/, jupyter/)
– Sphinx/Book builds, Jupyter notebooks, install instructions
– Cirq or sample apps → feed circuit descriptions → pybind_interface (Python) or direct C++ API
– Python layer (qsimcirq) calls into extension modules → C++ core library
– Core library dispatches to the appropriate backend kernel (AVX, GPU, etc.)
– Simulation runs on CPU threads (OpenMP) or GPU streams
– Results returned back through Python or printed by the CLI
– CI pipelines trigger builds/tests across components
Architectural Patterns & Principles
– Layered architecture:
• Core simulation engine (performance-critical C++)
• Binding layer (pybind11)
• User-facing API (Python/C++ CLI)
– Plugin/back-end strategy: multiple simulator back ends selected at build/runtime
– Build automation: multi-language tooling (Bazel, CMake, Python packaging)
– Continuous integration: containerized tests and multi-platform coverage
Technologies & Frameworks
– C++17, OpenMP, AVX/FMA, CUDA, HIP
– GoogleTest for C++ tests, pytest for Python tests
– pybind11 for Python bindings, setup.py/pyproject.toml for packaging
– Bazel, CMake, Make, Docker, GitHub Actions
Capturing Essential Elements
– Don’t omit the build system: Bazel/CMake orchestrates C++ and Python builds across platforms.
– Include CI workflows to show how quality gates (format checks, sanitizer tests, wheel releases) fit into the pipeline.
– Represent Docker and Jupyter environments for reproducible demos and tests.