Skip to content

docs: pyQuil v5 documentation (simulators, noise model, QVM removal) - #1883

Draft
bramathon wants to merge 4 commits into
masterfrom
v5-docs
Draft

bramathon wants to merge 4 commits into
masterfrom
v5-docs

Conversation

@bramathon

Copy link
Copy Markdown
Collaborator

Opened by Claude (Claude Code) on behalf of @bramathon.

Summary

The documentation update for pyQuil v5. The QVM, WavefunctionSimulator, PyQVM and the Kraus-map noise model are removed, and the JAX/quax simulators and noise model become public. Docs only: none of the code changes these pages assume are in this PR (see Assumed v5 APIs), so this is a draft until that code exists.

Four commits:

  1. conf.py: intersphinx for python, numpy, jax and quax, and jax_enable_x64 in doctest_global_setup.
  2. QVM removal across the guide:
    • wavefunction_simulator.rst is deleted. Its basis-ordering section moves to programs_and_gates.rst and is rewritten big-endian, keeping the basis_ordering label that quil.py docstrings link to.
    • QVM setup, as_qvm and -qvm names are gone from getting started, programs, the quantum computer, compiler, advanced usage, troubleshooting, exercises and Quil-T. Execution examples use the new simulators. Control-flow runs become QPU code blocks, because the simulators are straight-line only.
    • New introducing_v5.rst migration guide; README quickstart rewritten.
    • Fixes a few existing doc bugs along the way: the _new_topology label, the QPU.cancel role, and the duplicated NAIVE rewiring example.
  3. Simulation pages:
    • New task-oriented simulation.rst user guide.
    • simulation_architecture.rst loses its experimental banner and uses public paths. It also had two factual errors, now fixed: Circuit/MergePlan are in pyquil, not quax, and the parameter vector has one slot per distinct memory reference.
    • simulation-demo.ipynb added as a tutorial: public imports, hand-built noise instead of from_compiler_isa, shots via TrajectorySimulator so readout error is included, and outputs stripped.
  4. noise.rst rewritten for Channel / SuperopChannel / MeasurementChannel / reset channels / CycleChannel / NoiseModel. It covers construction, how channels are keyed to instructions and applied by each simulator, cycles, qudits and leakage, from_isa, fidelity estimation, JSON, and a migration table from the Kraus model. Superoperator, Lindbladian and instrument background is linked to the quax docs rather than repeated. The legacy noise images are deleted.

Assumed v5 APIs (must land in code before merge)

  • from pyquil.simulation import PureStateVectorSimulator, DensityMatrixSimulator, TrajectorySimulator, Circuit, MergePlan
  • from pyquil.noise import Channel, SuperopChannel, MeasurementChannel, ResetChannel, SuperopResetChannel, CycleChannel, NoiseModel, NoiseModelLike, DepolarizingNoiseModel, estimate_program_fidelity, estimate_program_observable_fidelity, get_custom_gates_from_program
  • get_qc("<N>q"), get_qc("9q-square") and the other former -qvm names without the suffix return a compile-only QuantumComputer: quilc compiles, but it cannot run.
  • pyquil.api.QuilcCompiler(quantum_processor=..., timeout=...), the renamed QVMCompiler, for custom topologies.
  • local_forest_runtime starts quilc only.
  • Big-endian qubit ordering everywhere.

CI follow-ups for the code PR: drop rigetti/qvm -S from the doctest job, and drop --extras latex from the Makefile.

Test plan

  • sphinx-build -b html with no warnings from the doc pages. pandoc isn't installed locally, so the changelog conversion and the notebooks were skipped in this build.
  • Every simulator and noise example run locally, with the private module paths substituted and x64 on; outputs match the testoutput blocks.
  • Tutorial notebook executed end to end (~35 s).
  • Examples that compile with quilc (getting started, compiler, the quantum computer, parametric compilation) were not run, because quilc isn't available locally. The asserted swaps output is unchanged from before.
  • make doctest passes once the assumed APIs land.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RaHUH4DELW7qcFEE4Ei3ki

bramathon and others added 4 commits October 8, 2026 17:35
Removes wavefunction_simulator.rst (its basis-ordering section moves to
programs_and_gates.rst, now big-endian), drops QVM setup and as_qvm usage,
compiles with the compile-only get_qc, and adds an introducing_v5 migration guide.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RaHUH4DELW7qcFEE4Ei3ki
…l notebook

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RaHUH4DELW7qcFEE4Ei3ki
Covers constructing channels, keying them to instructions, how the simulators
apply them, cycles, qudits and leakage, and migration from the Kraus model.
Quantum-information background is linked to the quax documentation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RaHUH4DELW7qcFEE4Ei3ki
@github-actions

github-actions Bot commented Oct 8, 2026

Copy link
Copy Markdown

☂️ Python Coverage

current status: ✅

Overall Coverage

Lines Covered Coverage Threshold Status
10396 9342 90% 87% 🟢

New Files

No new covered files...

Modified Files

No covered modified files...

updated for commit: 5190ce3 by action🐍

@github-actions

github-actions Bot commented Oct 8, 2026

Copy link
Copy Markdown

🐰 Bencher Report

Projectpyquil
Branchv5-docs
Testbedci-runner-linux

⚠️ WARNING: No Threshold found!

Without a Threshold, no Alerts will ever be generated.

Click here to create a new Threshold
For more information, see the Threshold documentation.
To only post results if a Threshold exists, set the --ci-only-thresholds flag.

Click to view all benchmark results
BenchmarkLatencymilliseconds (ms)
test/benchmarks/test_program.py::test_copy_everything_except_instructions📈 view plot
⚠️ NO THRESHOLD
7,865.64 ms
test/benchmarks/test_program.py::test_instructions📈 view plot
⚠️ NO THRESHOLD
2,808.96 ms
test/benchmarks/test_program.py::test_iteration📈 view plot
⚠️ NO THRESHOLD
2,761.88 ms
test/benchmarks/test_simulators.py::TestJitCompileTime::test_density_matrix_compile_depth[20L]📈 view plot
⚠️ NO THRESHOLD
171.33 ms
test/benchmarks/test_simulators.py::TestJitCompileTime::test_density_matrix_compile_depth[40L]📈 view plot
⚠️ NO THRESHOLD
197.68 ms
test/benchmarks/test_simulators.py::TestJitCompileTime::test_density_matrix_compile_depth[5L]📈 view plot
⚠️ NO THRESHOLD
167.61 ms
test/benchmarks/test_simulators.py::TestJitCompileTime::test_state_vector_compile_depth[10L]📈 view plot
⚠️ NO THRESHOLD
168.47 ms
test/benchmarks/test_simulators.py::TestJitCompileTime::test_state_vector_compile_depth[40L]📈 view plot
⚠️ NO THRESHOLD
160.39 ms
test/benchmarks/test_simulators.py::TestJitCompileTime::test_state_vector_compile_depth[80L]📈 view plot
⚠️ NO THRESHOLD
176.42 ms
test/benchmarks/test_simulators.py::TestPerformance::test_17q_batch_size[b16]📈 view plot
⚠️ NO THRESHOLD
119,469.67 ms
test/benchmarks/test_simulators.py::TestPerformance::test_17q_batch_size[b64]📈 view plot
⚠️ NO THRESHOLD
106,870.93 ms
test/benchmarks/test_simulators.py::TestPerformance::test_17q_batch_size[b8]📈 view plot
⚠️ NO THRESHOLD
130,277.30 ms
test/benchmarks/test_simulators.py::TestPerformance::test_scaling_batch_size[b16]📈 view plot
⚠️ NO THRESHOLD
37,710.78 ms
test/benchmarks/test_simulators.py::TestPerformance::test_scaling_batch_size[b64]📈 view plot
⚠️ NO THRESHOLD
28,341.70 ms
test/benchmarks/test_simulators.py::TestPerformance::test_scaling_batch_size[b8]📈 view plot
⚠️ NO THRESHOLD
50,400.22 ms
test/benchmarks/test_simulators.py::TestPerformance::test_scaling_depth[10L]📈 view plot
⚠️ NO THRESHOLD
31,868.69 ms
test/benchmarks/test_simulators.py::TestPerformance::test_scaling_depth[1L]📈 view plot
⚠️ NO THRESHOLD
10,001.02 ms
test/benchmarks/test_simulators.py::TestPerformance::test_scaling_depth[20L]📈 view plot
⚠️ NO THRESHOLD
55,662.09 ms
test/benchmarks/test_simulators.py::TestPerformance::test_scaling_depth[3L]📈 view plot
⚠️ NO THRESHOLD
15,052.92 ms
test/benchmarks/test_simulators.py::TestPerformance::test_scaling_qubits[12q]📈 view plot
⚠️ NO THRESHOLD
8,311.20 ms
test/benchmarks/test_simulators.py::TestPerformance::test_scaling_qubits[15q]📈 view plot
⚠️ NO THRESHOLD
31,561.42 ms
test/benchmarks/test_simulators.py::TestPerformance::test_scaling_qubits[3q]📈 view plot
⚠️ NO THRESHOLD
2,216.11 ms
test/benchmarks/test_simulators.py::TestPerformance::test_scaling_qubits[6q]📈 view plot
⚠️ NO THRESHOLD
3,433.21 ms
test/benchmarks/test_simulators.py::TestPerformance::test_scaling_qubits[9q]📈 view plot
⚠️ NO THRESHOLD
4,799.89 ms
test/benchmarks/test_simulators.py::TestPerformance::test_scaling_subsystem_size[s0]📈 view plot
⚠️ NO THRESHOLD
100,569.96 ms
test/benchmarks/test_simulators.py::TestPerformance::test_scaling_subsystem_size[s1]📈 view plot
⚠️ NO THRESHOLD
30,987.72 ms
test/benchmarks/test_simulators.py::TestPerformance::test_surface17_depth5_cycle_noise📈 view plot
⚠️ NO THRESHOLD
64,572.82 ms
test/benchmarks/test_simulators.py::TestPerformance::test_surface17_depth5_cycle_noise_low_trajectory📈 view plot
⚠️ NO THRESHOLD
3,960.60 ms
test/benchmarks/test_simulators.py::TestPerformance::test_surface17_depth5_cycle_noise_measurements_only_micro📈 view plot
⚠️ NO THRESHOLD
1,721.32 ms
test/benchmarks/test_simulators.py::TestPerformance::test_surface17_depth5_cycle_noise_micro📈 view plot
⚠️ NO THRESHOLD
3,161.96 ms
test/benchmarks/test_simulators.py::TestPerformance::test_surface17_depth5_cycle_noise_micro_jit📈 view plot
⚠️ NO THRESHOLD
59.89 ms
test/benchmarks/test_simulators.py::TestPerformance::test_surface17_depth5_cycle_noise_no_measurements_micro📈 view plot
⚠️ NO THRESHOLD
2,279.28 ms
🐰 View full continuous benchmarking report in Bencher

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