Development Workflow¶
Environment Setup¶
CPU Build¶
cd QRAM-Simulator
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)
GPU Build¶
The CUDA/GPU backend is off by default; enabling it requires a local CUDA toolchain (CUDA 13 / CCCL 3 and CUDA 12.8 / sm_80 on A800-class GPUs tested; verification record: docs/verification/v1c-gpu-cuda-a800.md). The GPU code layout is described in the CUDA backend reference. For large sparse-state runs, add -DCMAKE_CUDA_FLAGS="-DCACHED_REGISTER_SIZE=<n>" (and the same for CMAKE_CXX_FLAGS) to shrink the per-amplitude payload — see the CUDA backend reference for the constraints and measured effect (docs/verification/v1d-qda-linsolver-a800.md).
cmake .. -DCMAKE_BUILD_TYPE=Release -DSPARQ_ENABLE_CUDA=ON
make -j$(nproc)
Python Bindings¶
pip install .
Core Code Structure¶
Rendered references for the headers below: core components, register/system operations, quantum arithmetic, QRAM, and the algorithm library.
Component |
Path |
Purpose |
|---|---|---|
Sparse state simulator |
|
Core state representation |
Register management |
|
Creation, lifetime, storage types |
Arithmetic operations |
|
Add, Mult, Shift, etc. |
Basic gates |
|
H, X, Y, Z, CNOT, etc. |
QRAM |
|
QRAM load operations |
High-level algorithms |
|
State preparation, block encoding, etc. |
Adding a New Experiment¶
Create the experiment directory structure:
Experiments/ └── MyAlgorithm/ ├── MyAlgorithmTest.cpp └── CMakeLists.txtWrite
CMakeLists.txt:add_executable(MyAlgorithmTest MyAlgorithmTest.cpp) target_link_libraries(MyAlgorithmTest PRIVATE SparQ SparQ_Algorithm Common)
Register it in
Experiments/CMakeLists.txt:add_subdirectory(MyAlgorithm)
Git Workflow¶
Create a branch and develop:
# Create a feature branch
git checkout -b feat/my-algorithm origin/main
# Develop, test...
# Push to your fork
git push origin feat/my-algorithm
Submit a PR to upstream after CI passes.
Running Tests¶
# Run all tests
cd build && ctest --output-on-failure
# Run a specific test
./build/bin/MyAlgorithmTest