---

name: pyquil description: "Guides PyQuil and Quil quantum-programming workflows: author programs, simulate locally, compile and execute through QVM or QPU services, model noise and experiments, and inspect processor topologies and ISA metadata." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

PyQuil

Use this repo skill when a task names PyQuil, pyquil, Quil, Rigetti Forest, Program, get_qc, QVM, QPU, quilc, QuantumComputer, PyQVM, Pauli experiments, noise models, or compiler ISA/topology metadata. It is a versioned, self-contained operating guide for PyQuil 4.18.0; it is not a replacement for QCS credentials, QVM/quilc binaries, a reservation, or a physical processor.

First decide the execution boundary

1. Author or inspect Quil locally: read program-authoring. It owns Program, gates, declarations, memory, placeholders, control flow, Quil-T, and serialization.
2. Run numerical simulation without external services: read simulation. Prefer PyQVM or the reference/NumPy simulators. Do not confuse them with the service-backed WavefunctionSimulator.
3. Compile, submit, or inspect QAM results: read compile-execute. It owns QuantumComputer, compiler/QVM/QPU selection, result maps, batching, endpoints, services, and QCS configuration.
4. Model noise, Pauli observables, or experiments: read noise-experiments. It owns construction and validation; execution remains a separate backend step.
5. Inspect connectivity or instruction-set metadata: read processor-isa. It owns NetworkX topologies, CompilerISA, QCS ISA conversion, and processor compatibility.

For a task crossing routes, start with the first route that creates the artifact, then follow its explicit handoff. Keep these distinctions visible:

Local artifact or operation	What it proves	What it does not prove
Program(...).out()	Quil construction and serialization	Compiler acceptance or execution
PyQVM / reference simulator	In-process behavior on the selected simulator	QVM/quilc availability or QPU behavior
qc.compile() / qc.run()	Backend interaction only when the configured services respond	Physical correctness beyond the returned evidence
NoiseModel, Experiment, or ISA object	Model/metadata construction and validation	A run, calibration, reservation, or hardware result

Install and inspect

Use a supported Python version from the package metadata (Python 3.11 or 3.12 for this release) in an isolated environment:

python -m pip install pyquil
python -c "import pyquil; print(pyquil.__version__)"

The optional latex extra supplies IPython for interactive display helpers:

python -m pip install 'pyquil[latex]'

The package depends on compiled Rust-backed distributions on common platforms; less common platforms may need a Rust toolchain. QVM/quilc are separate Forest SDK services and are not installed by the Python package. QCS/QPU workflows also require authorized configuration and access. Read references/concepts-and-runtime-boundaries.md for the dependency and service boundary before installing broad extras.

Run the bundled, service-free installation check from any working directory:

python scripts/check_pyquil_install.py --help
python scripts/check_pyquil_install.py

It reports package metadata/imports and small local capability checks without starting services, reading secrets, contacting QCS, or writing files. Read references/troubleshooting.md when the import, optional dependency, configuration, compiler, service, or credential boundary is unclear. Read references/repo-provenance.md before using this skill against a changed checkout; a changed commit or public API surface calls for refresh-repo-skill.

Shared operating rules

• Build and validate a Program before handing it to a simulator or compiler.
• Declare memory deliberately; validate register names, dimensions, and shot counts before interpreting returned arrays.
• Resolve qubit and label placeholders before submission-shaped serialization.
• Use explicit finite timeouts for compiler/service calls and record whether a service or credential was actually used.
• Treat qubit order, Pauli sign conventions, readout-matrix orientation, and ISA dead-resource flags as data contracts, not presentation details.
• Stop rather than inventing a QPU result when QCS credentials, a reservation, quilc, or QVM is missing.

Runtime files

All references and helpers linked by the routes above are bundled inside this skill. Review/test records, native candidate maps, environment reports, and verification notes live outside the runtime tree under the construction artifact directory; do not make later Researcher runs depend on them.