Skip to content

docs: demonstrate the packaged phase estimation API - #87

Draft
wsttiger wants to merge 2 commits into
mainfrom
codex/v02-06-phase-estimation
Draft

wsttiger wants to merge 2 commits into
mainfrom
codex/v02-06-phase-estimation

Conversation

@wsttiger

@wsttiger wsttiger commented Nov 8, 2026

Copy link
Copy Markdown
Collaborator

Extends the existing H2 QPE tutorial with PhaseEstimation using the same Hamiltonian and Hartree–Fock input. The original exact-evolution, Trotter, and centered-walk calculations remain intact. The new section executes measured circuit generation, sampling, and public count decoding, checks textbook versus centered exact folded marginals, and compares seeded unfolded sample distributions to an a priori statistical bound. Energy acceptance uses nonlinear cosine phase cells, with core energy included once.

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

  • Standalone example passed: 14 total qubits, six counting bits, 20,000 shots, 63 textbook controlled-walk steps. Seeded phase TV was 0.011999 versus a 0.038363 bound.
  • python3 -m pytest tests/python/test_examples.py -k 08_quantum_phase_estimation -q: 1 passed in 57.42 s.
  • Sphinx HTML build with -W --keep-going: passed independently.
  • YAPF 0.43.0 and whitespace checks passed.

Independent plan 06 PR against main; no sibling example, library change, or new dependency is required.

Signed-off-by: Scott Thornton <wsttiger@gmail.com>
The centered exponent schedule applies W^(n - M/2) in place of W^n; the
extra W^(-M/2) is a phase on each walk eigencomponent, so the exact
phase-register marginals of the centered shell and of PhaseEstimation's
textbook ladder agree bin by bin (total variation 7e-16 at m=6), not
only after mirror folding. Compare the unfolded marginals in the example
and the corresponding sampled histograms, drop the local folding helper,
and describe the check that way on the examples page and in the guide.

Also replace the "must not fold before the sampling check" wording with
the reason (folding coarsens a distribution and can only lower total
variation), and remove history wording from the docs.

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