Skip to content

docs: add a sparse QSVT heat diffusion example - #89

Draft
wsttiger wants to merge 2 commits into
mainfrom
codex/v02-08-sparse-heat-equation
Draft

wsttiger wants to merge 2 commits into
mainfrom
codex/v02-08-sparse-heat-equation

Conversation

@wsttiger

@wsttiger wsttiger commented Nov 8, 2026

Copy link
Copy Markdown
Collaborator

Adds a self-verifying sparse inverse application: one backward-Euler heat-diffusion step in a rod with fixed zero endpoints. Arithmetic banded oracles encode the interior SPD matrix. Independent NumPy constructions check the analytic spectrum/default rational solution, angle-quantized matrix, circuit block, raw complex QSVT response, physical scale restoration, full-vector temperatures, and residual. Coefficient, inverse-polynomial, phase, and circuit errors have separate derived budgets.

The six-bit, 1e-3 default retains B=206 of the CKS construction. A rigorously bounded Chebyshev tail (7.33e-11 uniformly on [-1,1]) reduces its executed degree from 411 to 125; matrix precision and requested inverse accuracy are unchanged. The tail is propagated into the error budget. --full-cks executes all 411 degrees. Full-state real-response extraction is explicitly simulator postprocessing, with no fitted scale or isolated-filter success claim.

Validation on CUDA-Q 0.16.0.post1, Python 3.12.3:

  • python3 -m pytest tests/python/test_examples.py -k '10_sparse_heat_equation or 07_matrix_inversion_qsvt' -q: 2 passed in 451.08 s on qpp-cpu with OMP_NUM_THREADS=8; the existing 600-second example timeout is unchanged.
  • Default: 18 total qubits; full-vector error versus ideal NumPy 0.4454%, direction fidelity 0.999985801, relative residual 0.00400697. Quantized NumPy discrepancy is reported separately.
  • fp64 NVIDIA GPU: final default passed in 5.65 s; --full-cks passed in 9.19 s. Full CKS execution is considerably slower on CPU.
  • Seven-bit configuration passed in 6.01 s on fp64 GPU, using 19 qubits; its optional headless plot was generated and visually inspected. Tighter coefficient bounds do not imply monotonic observed solution error.
  • Dimension, width, and degree guards rejected invalid/excessive requests before state allocation or phase synthesis.
  • Sphinx HTML build with -W --keep-going, YAPF 0.43.0, and whitespace checks passed.

Independent plan 08 PR against main; includes its own helpers and documentation, with no dependency on plan 05 or other proposed examples. QSPPACK is required; Matplotlib is lazily imported only for --plot and is not added to core dependencies.

Signed-off-by: Scott Thornton <wsttiger@gmail.com>
The six-angle-bit, 1e-3 default executes a degree-125 QSVT sequence on
18 qubits: 1380 s on qpp-cpu with two threads (the CI example timeout is
600 s and the wheel-test lanes run on four-vCPU runners), against 4 s
for example 07. Make four angle bits and a 1e-2 inverse target the
default (16 qubits, executed degree 99, 244 s under the same
conditions; all checks pass with 3.4% full-vector error, dominated by
the four-bit matrix quantization) and keep the 18-qubit configuration
as the documented --value-bits 6 --inverse-epsilon 1e-3 precision run.
Update the qubit, B and degree figures in the getting-started page and
the block-encodings guide accordingly.

Remove the "physical RHS norm restores linear scaling" check: it
compared 2.5 * reconstructed with 2.5 * numpy_solution against 2.5 *
total_bound, which is the preceding check multiplied through by a
constant and verifies nothing about the recovery factor. State in the
guide what does verify it: the factor beta/(c*alpha) is fixed
analytically and the comparison with the quantized NumPy solve checks
it.

Signed-off-by: Scott Thornton <wsttiger@gmail.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant