---

name: program-authoring description: "Enables construction, inspection, transformation, serialization, and diagram generation for PyQuil Programs, Quil, and Quil-T without executing a quantum job." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Program authoring

Use this route when the task is about writing or understanding Quil rather than submitting it: Program, standard gates, DECLARE, MEASURE, memory references, placeholders, custom gates, classical labels/branches, PRAGMA, Quil-T definitions, out(), parsing, or LaTeX diagrams.

This sub-skill constructs and validates program text locally. It does not compile, submit, simulate, estimate noise, query a processor, or prove that a QPU/QVM/service accepts a program.

Route the task first

Request	Use
Build, parse, compose, parameterize, address, inspect, or serialize Quil	This sub-skill
Compile, select a QuantumComputer, call QAM/QVM/QPU, or inspect job results	compile-execute
Obtain statevectors, probabilities, expectations, or local numerical dynamics	simulation
Build NoiseModel, Pauli, Experiment, calibration, or estimation workflows	noise-experiments
Build or inspect topology, ISA, processor connectivity, or gate availability	processor-isa

Read api-reference.md before relying on a signature or subtle mutability/serialization rule. Read workflows.md for end-to-end authoring recipes. Read quil-t-and-diagrams.md for pulse, frame, calibration, waveform, or LaTeX work. Read troubleshooting.md after an exception or when a program looks valid in Python but its Quil is suspect.

For a deterministic, service-free Bell construction and canonical Quil check, run scripts/build_bell_program.py. It only constructs and serializes a Program; it never calls a compiler, QVM, QPU, or external service:

python scripts/build_bell_program.py --help
python scripts/build_bell_program.py --validate-only
python scripts/build_bell_program.py

Authoring contract

1. Import Program from pyquil; import gates from pyquil.gates; use pyquil.quilatom for MemoryReference, Parameter, placeholders, labels, frames, and waveform invocations; use pyquil.quilbase for instruction and definition classes.
2. Construct from typed instructions where possible. Program(...), .inst, +=, +, and Quil strings are supported. Keep the source Program when a second variant is needed: + and .copy() avoid accidental edits to the original, while .inst, +=, .measure, .declare, and .wrap_in_numshots_loop mutate it.
3. Declare every memory region intentionally and retain the returned base MemoryReference. Check offsets yourself, especially for parsed or manually created references whose declaration size is unknown.
4. Resolve every QubitPlaceholder and LabelPlaceholder before calling out() for submission-shaped Quil. Prefer address_qubits(program, mapping) when a physical mapping is part of the requirement; it returns a copy.
5. Treat program.out() as a local serialization observation. Round-trip with Program(program.out()).out() when a stable Quil representation is needed; this is parsing/serialization validation, not execution validation.
6. Use wrap_in_numshots_loop(shots) only to set program.num_shots; it does not add a Quil loop and does not run shots. For an actual Quil loop, use with_loop with an INTEGER counter and explicit labels.
7. Use out(calibrations=False) only to omit calibration definitions. It can still contain other Quil-T/global definitions such as frames and waveforms. Use remove_quil_t_instructions() only when a deliberately stripped, non-Quil-T variant is wanted; it is not a general compiler compatibility proof.
8. For custom gates, validate matrix shape/unitarity, parameter count, and qudit argument count explicitly before composing. For classical branches, declare and populate the condition memory, then resolve generated labels.
9. For LaTeX, prefer to_latex(program) when the required output is source text. display(program) additionally needs IPython plus pdflatex, ImageMagick convert, and a suitable LaTeX installation; neither function executes the program.

Quick local skeleton

from pyquil import Program
from pyquil.gates import CNOT, H, MEASURE

program = Program()
ro = program.declare("ro", "BIT", 2)
program += [H(0), CNOT(0, 1)]
program += [MEASURE(0, ro[0]), MEASURE(1, ro[1])]
quil_text = program.out()
assert Program(quil_text).out() == quil_text

The expected output is ordinary Quil beginning with DECLARE ro BIT[2], then H 0, CNOT 0 1, and the two measurements. This confirms construction and round-trip parsing only. Hand the validated Program to compile-execute, simulation, or noise-experiments only when that later workflow is explicitly requested.