Repository navigation
The first public release, a research preview: APIs, dialects and numerical
behavior may change in any 0.x release.
Added
- Gate calibrations.
pulse.gatesnames the gates a quantum system is
calibrated for (X,X90,Y,Y90,READOUT,CZ), and
get_calibration(gate, transition=(0, 1))gives each one's pulse: in a
kernel from a line,get_drive_line(q).get_calibration(pulse.gates.X)(a
DragPulse, whichdrive(line, pulse)plays) and
get_readout_line(q).get_calibration(pulse.gates.READOUT)(a
ReadoutPulse); outside one from a handle,
dev.qudits[i].get_calibration(...), and from a coupling,
dev.coupling(a, b).get_calibration(pulse.gates.CZ)(aFluxCZ). A
qudit'sdriveandreadout(MicrowaveDrive,DispersiveReadout)
hold its physics; its tuned pulses are given ascalibrations=, by gate,
and read only throughget_calibration, as a coupling's are.
What a quantum system does not publish is derived: anXamplitude from the
pulse's area,X90at half of it,YandY90at +90 degrees; an
unpublishedCZ,READOUTor other transition is an error naming the
coupling or qudit. A qudit'smetadataholds the user's own JSON
values, which the library never reads and which do not make two quantum systems
differ; system files keep them. - Shared lines. A
DriveLineorReadoutLinemay reach several
qudits and play several tones at once: a readout feedline is
ReadoutLine([0, 1, 2, 3], max_concurrent_tones=4)(1 by default, at most
the qudits it reaches). Every line hasqudits; only a dedicated line has
qudit. A kernel'sget_readout_line(q)of a qudit on it gives one of
its tones, forq. The compiler checks that a line reaching several
qudits plays at mostmax_concurrent_tonestones at once (a kernel with
runtime qudits, when a call binds them); spacing andmax_amplitude
apply per tone, waveform memory andmax_frequencies_per_lineper physical
line. Format/2of the controller export lists a shared line once,
with itsmax_concurrent_tones, and gives each event on it its
tone_slotandqudits; format/1raisesUnsupportedErrorfor a
program on a shared line. System files hold one as{"qudits": [...], "max_concurrent_tones": 4, "delay_ns": 12.0}. A qudit is reached by at
most one line of each kind. A program on a delayed shared line does not
export yet. - Pickling, for process pools and caches on disk. Kernels pickle as
functions do: by reference, or with cloudpickle (Ray, Dask) by value
when defined in__main__, at the prompt or inside a function. Quantum systems, qudit handles and registers
pickle as what they were built from and unpickle equal, with equal
hashes; a process builds each quantum system it unpickles once. A quantum system's
fingerprint covers its calibration: a quantum system with and without one are
two quantum systems. A shipped calibration pickles as its name, checked against
the file shipped where it unpickles; any other, as its values. Programs
(ck.lower(...), bound or not) pickle as MLIR bytecode stamped with the
build that compiled them (hashes of its native and Python sources, taken
when it was built) and the Python, and run unpickled (export, simulate, bind)
without compiling again; another build refuses them with
UnsupportedError, saying to compile again. Errors pickle with what they
report, so a process pool re-raises them in the parent as they were
raised. Quantum systems now compare by content. - Controllers with their own clocks. Kernels count cycles of the
quantum system's program clock,pulse.quantum_system(..., clock_ghz=)(or the
quantum system's own). A controller whose clock is slower starts and times operations
only every few program cycles: the scheduler puts each line's operations
on its controller's grid and asyncon the grid its lines share, an
operation off the grid is a compile error naming the line, its controller
and the nearest valid lengths, andpulse.cycles_on(line, n)rounds a
length onto the grid (pulse.Rounding). Controller programs count their
own cycles, with"program_clock_ghz"written when it differs;
ControlSystem.reference_clock_ghzis checked against every controller
clock and exported; the simulator samples generated waveforms at the
line's controller clock. - Runtime qudits. A parameter annotated
QuditorRegister(or
list[Qudit],tuple[Qudit, ...]) is bound at each call, like a float:
the kernel compiles once and runs on any qudits of a quantum system with the same
structure, including a recalibrated one. An unannotated qudit parameter
stays static, whatever the call passes.list[float]parameters are runtime vectors. Their
controller exports carry aprogram_id, shared by every call of one
compile, andsymbols: each symbol's value in the call, and per event the
symbols its qudit, frequency, phase and waveform depend on. - Variadic qudits. A kernel may take
*qudits:
def k(tau: float, *qudits: Qudit)is called ask(tau, q0, q1, ...)or
k(tau, *dev.qudits[0:4]), and from another kernel as
k(tau, *qudits). In the kernelquditsis a register of the call's
qudits, which indexes, slices, iterates and has alen(). Annotated
Quditit is a runtime register, compiled once per number of qudits;
unannotated, the kernel is specialized on the qudits. A call may pass
none. A*parameter takes only qudit handles: another annotation is a
TypeErrorwhen the kernel is defined, another value one when it is
called. Kernels still cannot take**kwargs. A list or tuple of qudit
handles is not a register: pass aRegister(qs.qudits[0:4]) or use
*qudits.kernel.static_parametersandkernel.runtime_parameters
list parameters in the order of the signature. - Control systems. A quantum system can hold the controllers that play it:
pulse.Controller(a controller's limits, the drive and readout lines it
plays, its peer latency, clock skew and alignment tolerance, its
supports,backend,modelandversion) andpulse.ControlSystem
(its controllers, its links by name, eachLinkwith thecontrollers
it reaches).pulse.quantum_system(quantum_system, control_system=...)checks
the wiring against the quantum system and raises one
QuantumSystemDefinitionErrorlisting every problem.compile(kernel, quantum_system=qpu)checks every program against
the system: a line on no controller, each controller's own limits, a
capability (pulse.Capability) a controller lacks, and a call over a link
that does not reach its controllers fail to compile.
compile(kernel, control_system=...)takes a system, or oneController
that stands for a system of it alone: what that controller cannot take is
an error that says to describe the whole system. A system without
controllers states only its links and lanes. A controller that
supportsloopholds a rolled loop's body once againstmax_pulses; one
that does not plays it unrolled, and its limit error names the loop; unrolling adds pulses,
not waveform memory, which holds each shape once.rcpkeeps a branch
on a readout thefeedback_latency_cyclesof the controllers that read out.
A line's calibrated delay is part of its declaration,
Controller(drive_lines=[DriveLine(5, delay_ns=4.0), 6], readout_lines=[ReadoutLine(5, delay_ns=12.0)])(times or numbers of ns;
a bare carrier index is an undelayed line), and a control system's
reference_clock_ghzis its shared clock; new delays alone schedule its
programs again without tracing them. Without a
declaredclock_ghz, a quantum system's program clock is its fastest
controller clock when every other one divides it; clocks that do not
divide evenly are aQuantumSystemDefinitionErrorthat lists the program clocks
that work, and every controller clock must be a whole multiple of the
reference clock. Each controller of a system may run its own clock: every
line is scheduled on its own controller's grid, asyncand a wait from
an answer on the grid all lines share, and a runtime qudit's lines on that
shared grid too, so one schedule fits any qudits a call binds. Each
controller's limits, line delays andrcpreadout latency count its own
cycles, andcustom()samples an envelope at the rate of the line that
plays it, while samples given at another rate fail to compile.
export_to_controller(controller=k)andexport_to_emulator(controller=k)
export controllerk's part of the program in its own cycles: its
lines, the events it plays, submits or takes the answer of, its calls and
its limits, with the program's event and line ids. A program that plays
the lines of more than one controller needscontroller=; a controller
the program does not use exports a valid empty program, and a program
of calls alone is exported by the controller that makes them.
Link(per_controller=True)(per_controller = truein a system file)
gives each controller its own instance of a link, shared by default:
its own slots, so its calls do not wait for another controller's, its own
calls in its export (tagged"controller"), its own processor to place
the link on, and no cross-controller start uncertainty in its budgets. A
call whose measurements and answer are on different controllers fails to
compile.
Budgets between controllers add each one's start uncertainty, its
clock_skew_cyclesplus one of its own cycles without a
reference_clock_ghz: a pulse that branches on, or computes with,
another controller's readout waits for the reader's feedback and peer
latency and both uncertainties (rcpwaits that long for each pair of
reader and user, and a pulse on the reader's controller its feedback
latency alone; starting sooner is aControllerLimitErrornaming the
cycle), and an answer taken on another controller than the one that sent
the request is due that much later (the two controllers' uncertainty; the
link's worst pair when the scheduler cannot tell which they are). The
first pulse after a sync of several controllers' lines, on each of them,
must land within its controller'salignment_tolerance_cycles: its start
uncertainty and its rounded line delay, else aControllerLimitError.
Underrcp, a pulse that follows another controller's on one of the
max_concurrent_drivesormax_concurrent_readoutslanes starts their
start uncertainty after it. - Processors.
pulse.Processoris a classical processor on a
controller (Controller(processors=[...])), which runs the classical
functions called on itslinks; a link belongs to at most one processor
of a system (of each controller, for a per-controller link). Compiling checks each function there: an operation in its
unsupportedlist (named with its line),max_ops_per_function,
max_state_bytes_per_function,fixed_cost_only, and its compute time at
the processor'scycles_per_op(pulse.controller.OpCycles(div=20), one
cycle per class not given) andclock_ghzagainst its
max_latency_ns. It checks each processor'smax_ops_total,
max_state_bytes_total,max_calls_per_shot,max_bytes_per_shotand
max_concurrent_calls(default 1) across its functions. Operations come
in the classes ofpulse.controller.OpClass;OpClass.LOOPis a rolled
loop's counter and jump per iteration, and a processor with it
unsupportedruns loops unrolled, so their size counts unrolled.
FunctionCost.opsis anOpCounts, and a built-in'scontroller_cost
hook returns one.pulse.controller.ExpressionTermnames the terms of an
exported run-time expression.dispatch_keys={"name": key}gives the
functions a processor runs fixed dispatch keys.scheduled.controller_usagereports
each processor's functions and totals against its limits
(.within_limits;printit for a table). A program over them does not
compile: itsControllerLimitErrorcarries the report asusage, every
limit exceeded with by how much (usage.exceeded,LimitExceeded), and
ends its message with the table. Descriptions and system files state
processors as[[processors]]tables. - Controller descriptions.
pulse.controller("vendor.model", drive_lines=..., readout_lines=...)loads a controller from a TOML
description installed with cudaq-pulse (or one given by path), parsed
once, with the installation's wiring.reference.controllerships. - System files.
QuantumSystem.as_dict()writes a QPU as one mapping, format
cudaq-pulse.system/1, with the keys ofpulse.quantum_system's keywords
("name", and"qudits","couplings", ... for one not registered),
whichpulse.QuantumSystem.from_dict(data)reads back,
andpulse.QuantumSystem.load(path)from a JSON file, reporting each problem
with its line. A file written from
another version of an installed description is noticed once
(UpgradeNotice).python -m cudaq_pulse.doctor --system FILEchecks a
system file and whether its controllers' backends are installed. - A bound on how long a program runs.
Controllertakes
max_program_duration, a time or a number of ns, the longest program the
controller runs. Building the module sums the program op after op, every
iteration of its loops, and a program longer than it, or than 260
cycles without one, is aCompilationErrorat the op or loop that passes
it; trip counts multiply without overflow. A wait whose length a float
sets is counted at its lowest length, and the call checks the length
again with its value; in anifarm, it counts only as far as it makes
that arm the longer one. A line'sdelay_nscounts too: a delay longer
than 260 cycles, or one that takes the scheduled program past them, is
aCompilationError.
Changed
-
Long rolled loops are checked without playing every iteration. The
controller check walks a rolled loop of more than 64 iterations three
times when its iterations play alike one period apart, and finds what it
found with every iteration played, in the same order. Past 10,000
violations,ControllerLimitError.violationsandcheck()give a
sequence that builds each violation when read, with an exactlen();
str(error)is unchanged.ScheduledKernel.scheduleis a list up to 10,000
events and past that a sequence that builds each event when read, from
its op and its loops' iterations, so its type is now
Sequence[ScheduledEvent];ScheduledKernel.durationno longer lists the
events.classical_report()takes a long loop without classical calls
once instead of once per iteration, with the same report. -
The simulator says which systems it has no model for. Simulating a
system that is not a transmon raisesUnsupportedError(a
NotImplementedError): export and hardware runs work. -
A simulation step too coarse for its qudits warns. A
dt_nspassed to
simulatethat takes fewer than 20 steps per period of the fastest
frequency the simulation holds (a qudit's level spread with three or more
levels, or the detuning of coupled qudits) issues aPulseWarningat the
caller's line, naming that frequency and a step that resolves it; such a
step damped the coherence of levels 0 and 2 silently. Examples 03, 14,
19, 20 andtransmon/transmon_surface17_evolve_gpu.pytake steps that resolve
their qudits, so two print converged values: example 14's survival at
depth 20 is 0.952 (was 0.954), and example 20's level-2 branch
probabilities change (outcomes(1, 2, 2)0.002, was 0.006). -
The default simulation step resolves many levels. Without
dt_ns,
simulatetakes 20 steps per period of a qudit's level spread as well as
of coupled qudits' detuning: 0.025 ns for a transmon with 6 levels and a
200 MHz anharmonicity, whose levels spread over 2 GHz and which 0.05 ns
dephased. Wherever 0.05 ns already resolved the simulation (a transmon
of up to four levels whose anharmonicity is under 333 MHz, as every
qudit oftransmon_surface17), the step and the results are unchanged. -
A simulation that diverges raises instead of returning NaN. A step
too coarse for the integrator (4 transmon levels atdt_ns=1.0, about
two steps per period of their 552 MHz spread) made its state overflow,
andsimulatereturned a density matrix of NaN or of entries near
1e234. It now raisesExecutionError, naming the qudit or coupled pair
whose frequency the step misses, the step and one that resolves it, with
a note giving the line that calledsimulate; on the CPU and on the GPU,
with no cost to a run that does not diverge. -
Simulation models are read-only. A model's levels by qudit are fixed
when it is made, andSimulationModelandTransmonModelare immutable,
as built-in types are: setting or deleting one of their attributes raises
TypeError. Subclass them to change what they give a qudit; a subclass
is not immutable.simulatekeeps the step it
resolves for a quantum system with one of them, so a second call on that
quantum system skips the checks, and drops it when the quantum system is freed. -
Calibration on the controller.
cudaq_pulse.classical.calibration
adds the estimators of millisecond on-controller calibration in controller
form: adaptive T1 tracking with assignment errors (adaptive_t1_update,
adaptive_t1_wait), the frequency binary search
(binary_search_update,binary_search_wait,binary_search_phase),
the analytical decay estimator (decay_time) and the sparse phase
estimator (sparse_phase,pi_train_amplitude,ramsey_detuning).
examples/21_calibration_protocol.pyruns the millisecond calibration
chain of M. A. Marciniak, R. T. Birke, J. B. Severin, F. Berritta,
D. Kjær, F. Nilsson, S. N. Themadath, S. Kallatt, J. L. Webb, K. Bentsen,
T. Madsen, Z. Sun, S. Krøjer, C. W. Warren, J. Hastrup and M. Kjaergaard,
"Millisecond-Scale Calibration and Benchmarking of Superconducting
Qubits", arXiv:2602.11912 (2026), as one program with its estimators on
the controller link, its adaptive T1 step after F. Berritta et al.,
"Real-time adaptive tracking of fluctuating relaxation rates in
superconducting qubits", arXiv:2506.09576 (2025);
benchmarks/classical/calibration_protocol.pychecks it end to end over
many seeds against the published numbers. -
What classical functions cost a controller.
scheduled.controller_usage
reports each classical function's operations (read from its body; an
expression of constants folds, and dividing by a constant is a multiply),
state in bytes and compute time againstmax_latency_nson the
Processorthat runs it, and each link's calls, slots and bytes per
shot.processor.usage(fn)is one function's cost on a processor on its
own: its cycles, and its time when the processor has a clock. -
Faster simulation of long programs. Idle waits and square pulses in
their frame are propagated exactly, at a cost independent of their
length, and driven stretches on registers of up to four levels by RK4
maps built at once (a 100 us T1 shot: 104 s to under 1 ms). Idle waits of
coupled qudits are exact too, in the frame that turns with their
couplings, and onbackend="gpu"a long idle stretch is propagated
exactly on the host while the GPU steps the drives around it.
simulate(branches="sampled")(orpulse.BranchCoverage.SAMPLED) follows
only the branches the shots take, so a program that measures many times in
one shot does not cost time exponential in its measurements. A loop that waits each round on a variable
or blocking wait costs the same host time per round at any length (example 19's T1 tracker, 30 to 120
rounds: about 0.55 ms per interval throughout, was 1.5 to 4.7 ms); other programs with calls are scheduled
again whole after each answer, so their host time per interval grows with the rounds before it. Finding a
program's next measurement and next call is now linear in its length. -
Kernels.
@pulse.kerneltraces a Python function into Pulse-dialect
MLIR. Calling a kernel with qudit handles compiles it for their quantum system on
first use, caches the specialization, and runs it;kernel.lower(...)
stops before running, andpulse.compile(kernel)compiles ahead of the
call.floatparameters stay symbolic, so a parameter sweep compiles once.
The module with a call's values substituted, which exports and the LLVM
stage read, is shared by every call with the same values once they
recur. Kernels call other kernels, loop withrange, and branch on measurement
results. A number the arms of anifon a measurement set differently
(if m: amp = 0.3/else: amp = 0.1) holds the value of the arm that
ran, as onearith.selecton the measurement, inelifchains, nested
ifs and rolled loops too. Lowering keeps the select where the quantum system
takes that amplitude, phase or frequency at run time, so every use reads
the one value; otherwise, and for durations and waveform shapes, each op
that reads it runs in both arms of anifon the measurement. No quantum system
takes one at run time yet. Either way the ops wait for the measurement
and schedule and simulate alike. A name assigned in only one arm, with no
value before the
if, raises aCompilationErrornaming it and the line of theif.
Kernels take their qudits as parameters; a call without qudit
handles raisesNoQuantumSystemErrorunless the kernel was compiled for a quantum system
(pulse.compile(k, quantum_system=dev)). -
Lines and their tones.
get_drive_line(q)andget_readout_line(q)
return the line alone, one value that is not unpacked or iterated;
line.toneis its own tone, andline.tones[(lower, upper)], a
read-only mapping keyed by levels, the tone of each transition of its
qudit: the line's own tone is that of the model'sdefault_transition
((0, 1)in the shipped models), and another transition's starts at its
frequency from the model, with phase 0.drive(line, waveform)and
readout(line, waveform)play on the line's own tone and, by keyword
only,tone=on another, such as another line's; the frame operations
take the tone, as inshift_phase(line.tone, phase).
A transition the qudit does not have raises aKeyError
(pulse.NotFoundError) that lists those it has. -
Loop unrolling. A
rangeloop whose variable is never read is kept
as one rolled loop, unless its estimated unrolled size (trip count times
the calls in its body) is at most the unroll threshold: 8 by default, the
measured break-even point. The threshold is a compile option only, an
intof 0 or more set withpulse.compile(k, unroll_threshold=)or
@pulse.kernel(unroll_threshold=); 0 means never unroll, so every such
loop stays rolled, even one of no or one iteration. No environment
variable sets it.
Lines and tones kept in a list, tuple or dict, retuned with
set_frequencyor not, are carried through a rolled loop. A rolled body
may iterate over qudits (for q in qs) and gather their lines in a list. -
Runtime wait lengths. A
waitwhose length is computed fromfloat
parameters with+,-,*and/(wait(d, tau),wait(d, tau / 2))
keeps them runtime parameters: a T1, Ramsey or echo sweep compiles once,
and a call with a new length costs about as much as a cached call. Each
call rounds the length to the nearest clock cycle (ties up) and schedules
exactly as the kernel compiled with that length would. The optional
wait(line, length, bounds=(lowest, highest))bounds it in cycles; a
length that is not finite, is negative or is out of bounds raises
ValueErrorat the call. A literal length must be a whole number of
cycles. A length computed from the answer of a classical call makes the
wait a variable region: it is rounded the same way, clamped to its
bounds, and opens a new segment (below). A length from both, such as
wait(d, answer + tau), compiles once too: each call checks that its
float part (the length with its answers at 0) is finite and at most the
upper bound, and the whole length is clamped to the bounds at run time. -
Python in kernels. List, dict and set comprehensions, set displays
and generator expressions are unrolled while tracing, so
[get_drive_line(q) for q in qubits]builds a list of lines and
sum(a for a in amps)works; a lambda or nesteddefraises a
CompilationErrorthat says what to write instead. Calls with
*argsand**kwargsare unpacked
while tracing, sosync(*lines)synchronizes a list of lines built in a
loop. Helpers called from a kernel may take keyword-only,*argsand
**kwargsparameters; methods of helper objects,functools.partial
objects and decorated helpers that use pulse ops are inlined too. A
method is inlined like a plain helper, with its object asself(its
class ascls) and the globals of the module that defines it, also when
it reaches a pulse op only throughself,clsor an objectself
holds (self.wf(),self.gates.x90(...)), when it is inherited, a
staticmethodorclassmethod, stored as a bound method, or an
object's__call__. Lines
and tones may be kept in any container, such as a list of lines or a
dict, and lists of them supportpop,insert,extend,
removeanddel xs[i].sync()takes lists and tuples of lines, as
insync(lines). A pulse op given the wrong kind of argument, such as a
tone where its line belongs, raises aCompilationErrorthat names the
op and the argument when it is traced, not an MLIR verifier error.
Errors raised while tracing carry a note with the file, line and source
of the kernel line, and of each helper line, that raised them; a
misspelled op or attribute gets a "did you mean" suggestion, and
pulse.drive(...)says that the kernel language is incudaq_pulse.ops.
A failingassert cond, "msg"reports "assertion failed in kernel: msg".
Starred assignment,first, *rest = xs, works, and so does slice
assignment on every supported Python. A construct the tracer does not
support, such as amatchclass pattern or an assignment to a global,
is named in the error, with what to write instead, rather than reported
as an unsupported bytecode instruction. Afloatargument that tracing
makes static, becauseabs,min,math.*, a comparison, arange
bound or a waveform duration needs its value, warns once per kernel and
argument, since each new value then compiles the kernel again. The
warning, aUserWarningthat is also aRuntimeWarning, names the
argument, the operation and the kernel line (and the helper's line when
the value is needed in a helper), and suggests passing a host-computed
value, annotating the argument asint, or giving it a fixed value.
Compiles of one kernel that trace at once warn once between them, and a
cached call checks nothing new. -
Operations. The kernel language lives in
cudaq_pulse.opsand is
used by bare name inside kernels. Drive and readout channels per qudit;drive,readout,
waitandsync; phase and frequency control (shift_phasefollows the
McKay et al. 2017 virtual-Z convention); Gaussian, square, DRAG (beta in
clock cycles), cosine, tanh-ramp, Gaussian-square and sampled waveforms;
waveform sums, differences, scaling and negation (exact) and products
(sampled once per clock cycle). -
Editor support with no configuration. The wheel installs
__builtins__.pyiat the root of site-packages, generated at build time
fromcudaq_pulse.ops.__all__, so Pylance (in VS Code and VS Code-based
editors), pyright and basedpyright know the operations used by bare name
inside kernels: no undefined-name warnings, with completion, hover documentation and checked
arguments. The names are builtins in the whole environment, outside
kernels too; see the new Editor Support page. The getting-started advice
to add apyrightconfig.jsonis gone. -
python -m cudaq_pulse.doctor --setup-editorconfigures mypy and ruff,
which take no names from an installed package: it shows the change to the
project's mypy and ruff configuration and writes it when confirmed or
with--yes. The mypy change enablescudaq_pulse.mypy_plugin, which
types the operations in files that import cudaq_pulse; the ruff change
lists them asbuiltins. -
cudaq_pulse.ops.__all__lists the kernel language. -
ScheduledEvent.startandScheduledEvent.end: an event's scheduled
times in clock cycles asint, raisingValueErroron an event that is
not scheduled yet. -
KernelandCompiledKernelare generic in the decorated function's
parameters, so type checkers checkk(...),k.lower(...)and
pulse.compile(k)(...)against the kernel's signature. -
square()is typed to take the complex and[re, im]amplitudes it
accepts. -
custom(duration, f)samples the Python functionfonce per clock cycle
while the kernel is traced, so custom envelopes compile, schedule and
simulate like the built-in ones; it takes a callable, not an envelope
name, and up to 252 clock cycles, likecustom_samples. -
Compilation. Verification, constant and phase folding and pulse
fusion by default; ASAP, ALAP and resource-constrained schedules
(pulse.compile(control_system=...)); per-kernel schedule policies and
schedule blocks.pulse.ScheduledKernel.mlir(level)returns the module at an IR
level (cudaq_pulse.compiler.IRLevel:"pulse", the scheduled Pulse
MLIR,"qop","cudm"or"llvm"),ScheduledKernel.schedulethe timed events
(cudaq_pulse.compiler.ScheduledEvent),ScheduledKernel.durationhow long the
program runs as apulse.Time,ScheduledKernel.metricsthe compile
times (cudaq_pulse.compiler.CompileMetrics), andScheduledKernel.timeline()a
plot (with the[viz]extra).QuantumSystem.qudit(label)finds a qudit by
its label andQuantumSystem.coupling(a, b)the coupling of two. -
Optimization passes.
passes=takes members ofpulse.Pass, a
string enum, or their names, in any order and combination:VERIFY,
FOLD_CONSTANTS(constant arithmetic computed at compile time),
REMOVE_UNUSED(operations whose results nothing uses),MERGE_WAITS
(constant waits in a row on one line joined into one),
SIMPLIFY_CONTROL_FLOW(syncs that order nothing, blocks that take no
time, loops that run once or never),FOLD_PHASES(frame changes folded
into the next drive),FUSE_PULSES(square pulses of the same amplitude
in a row merged) andHOIST_LOOP_INVARIANTS. The default isVERIFY,
FOLD_CONSTANTS,REMOVE_UNUSED,FOLD_PHASESandFUSE_PULSES. An
unknown name is aValueErrorthat names the closest member. Pattern
passes that follow one another run as one rewrite, so compiling, binding
a call's values and exporting a new binding are faster. When a call binds
floatparameters,FOLD_PHASESandFUSE_PULSESrun again, if the
kernel compiled with them, where the values reach: a phase bound to a
number folds into the next drive, and square pulses whose amplitudes are
bound equal fuse.cudaq-pulse-optruns each pass by name
(pulse-fold-constants,pulse-remove-unused,pulse-merge-waits,
pulse-simplify-control-flow,pulse-fold-phases,pulse-fuse-pulses,
pulse-hoist-loop-invariants), as well aspulse-unroll-classical-loops
andpulse-schedule-rcpwith the control system's lanes as options (max-drives,
max-readouts,readout-latency,switch-penalty,alap). -
Quantum systems.
pulse.quantum_systemis the one quantum system getter: it
describes a machine's physics and a qudit layout, from a registered
name (pulse.quantum_system("transmon_surface17")) or built directly
(pulse.quantum_system(name="chip", qudits={...}, couplings=[...], model=...)), withlayout=,calibration=,measurement_run=,
control_system=andclock_ghz=keywords, or, with no argument, the
process quantum system; a string is always a name, and
QuantumSystem.load/QuantumSystem.from_dictread system files.
qs.replace(...)makes a variant of a quantum system with the same
keywords, asdataclasses.replacedoes; aQuantumSystempassed to
pulse.quantum_systemis aTypeError. Quantum systems compare by
content and share compiled kernels, but handles of two quantum systems, even
equal ones, do not mix in one call or in a kernel compiled for one
(QuantumSystemMismatchError), and an emptylayoutis a
QuantumSystemDefinitionError. The shipped quantum system,
"transmon_surface17", is a 17-qubit transmon quantum system built from
Krinner et al., Nature 605, 669 (2022).
A quantum system'smodel(cudaq_pulse.quantum_systems.TransmonModelby default, a
SimulationModelclass or instance, orNone) says how the simulator
treats its qudits and which operator its couplings are (the exchange
g (a^dagger b + a b^dagger), in the rotating-wave approximation, for
TransmonModel); each model class declares its levels (3 for
transmons), andTransmonModel(levels={0: 4})sets a qudit's own. No
label changes the physics: quantum systems have noarchitecture.
A coupling isCoupling(qudits=(a, b), strength_hz, calibrations={}): the
qudits it couples, in order (two in this release), the strength in Hz of
the model's operator (g / 2 pi of the exchange), orNonewhen it
is not measured yet, which compiles, schedules and exports while
simulaterefuses it by name, and its tuned gates,
{pulse.gates.CZ: FluxCZ(duration_ns, buffer_ns=None, interaction_frequency_hz=None)}; thetransmon_surface17quantum system gives its
published CZ values, andcudaq_pulse.quantum_systems.transmon.CZ_LAYERSthe
(auxiliary, data) pairs of each of its CZ time steps. A quantum system's
residual_zzlistsResidualZZ(qudits, rate_hz)entries, a static ZZ
rate beyond what the couplings produce; the simulator's module carries
them as typed static terms of its quantum system
(static_terms = [#pulse.static_term<zz, qudits = [a, b], rate_hz = ...>],
checked when parsed), and their Hamiltonian term isstatic_zz. Couplings and residual ZZ entries
are checked when the system is built, all of them at once: each is
between two distinct qudits of the system (three or more are refused in
this release), one per pair in either order, with finite strengths and
rates (zero and negative allowed), a gate's non-empty name, times of 0 ns
or more and an interaction frequency above 0 Hz. A config or file with
problems raisespulse.QuantumSystemDefinitionError(aValueError) listing all
of them inproblems, each apulse.Problemwith its path in the config
(layout[2]), the offending value and a fix, and for a file its line and
column; an unknown key or quantum system name suggests the closest one, and the
reserved keys (zones,sites,moves,transport) are problems too.
python -m cudaq_pulse.doctor --system FILE [--json]runs the same checks. -
Calibrations and the transmon model.
cudaq_pulse.quantum_systems.Calibration
loads fitted values, each with its kind, source, uncertainty and measurement run,
apart from the published quantum system, andpulse.quantum_systemtakescalibration=
andmeasurement_run=.cudaq_pulse.quantum_systems.transmon_modelcomputes
flux-tunable transmon levels and charge-coupled pairs from circuit values.
The shippedtransmon_surface17calibration has one system-wide charge coupling,
fitted to the measured|11>-|20>coupling of X2-D4, so the
transmon_surface17quantum system's exchange (5.67-6.08 MHz) and idle ZZ (-4.5 to -7.3 kHz) depend on
each pair's frequencies; calibrated qubits convert detunings to and from flux quanta.
It also holds in-model sudden-net-zero CZ knobs for all 24 pairs (mean
duration 65.0 +- 4.8 ns against the published 68(7) ns), each with its
predicted phase and leakage, flags and alternatives. -
Simulation.
pulse.simulateevolves a compiled call with T1, T2 or
Hahn-echo dephasing, thermal populations, exchange couplings, residual ZZ
and any number of transmon levels (by default those the quantum system's model
declares, 3 for a transmon;levels=sets them for every qudit or, as a
dict, per qudit), either with a NumPy reference
integrator (backend="cpu") or on NVIDIA GPUs through cuDensityMat
(backend="gpu", Linux, experimental). Programs that measure and branch
are evolved as an exact ensemble over outcomes. The simulated space holds
only the qudits the program gets a line on, whatever their quantum system indices
(a pair at qudits 13 and 3 is a two-mode problem);SimulationResult.qudits
andScheduledKernel.quditsgive the quantum system qudit of each mode, and the other
qudits are classical spectators.result.level_population(level, qudit)
andresult.level_populations(qudit)give a qudit's level probabilities
from its reduced state, for any number of levels;qudit(a quantum system index
or handle) may be left out when the result models one qudit, and a qudit
or level the result does not have is anInvalidValueErrorlisting those
it has.result.branchesholds oneBranchper measurement path: its
levels,probabilityand classicalcalls, withanswers(function)
for the answers of one function. -
Classical calls at QPU runtime.
classical, a classical real-time
dialect for co-processing at QPU runtime: pulse programs call GPU, host or
FPGA services (decoders, estimators, calibration updates) while the QPU
runs and use their answers in the same shot.@pulse.classicaldeclares a
function from its type hints (def decode(syndrome: pulse.Bits) -> bool),
with a latency model and a link; a list parameter takes its length from
the call, each length makes a version of the function (flip__3), and
list results take theirs from the body (and the plain Python helpers it
calls).pulse.Length(typing.Annotated)
states a fixed length where one schema is wanted:
pulse.Length[pulse.Bits, 8](eight measurements read as bits) and
pulse.Length[list[int], 8](eight numbers). One readout passed where a
list is taken is a compile error that gives the fix
(decode.submit([m])). A call record or
report row names the function (call.function,"flip"), its version
(call.compiled_name,"flip__3") and the key its requests are
dispatched by (call.dispatch_key: the FNV-1a hash of the compiled name,
or the key a processor'sdispatch_keysfixes; the call manifest's
"dispatch_key"). Two names that hash to one key on one link are a
compile error. An external function's stub is a
declaration whose body is a placeholder for its result (return float(),
return syndrome[:2]); its unsized list parameters make versions as for
@pulse.classical. Simulation and emulation check every answer's list
lengths.fn.submit(...).result()calls it in a kernel, withtimeout=
(a time such as350 * pulse.ns, or a number of nanoseconds, as the
declaration's latencies take) for a fallback. Type checkers and editors see
the function's own signature: a wrong argument is an error where it is
passed, and
.submit()returns aPendingof the result's type. Links are named in
ControlSystem(links={...}). Every schedule budgets the worst-case
latency, holds link slots and reports each call's slack and its hidden and
exposed latency (ScheduledKernel.classical_report());pulse-classical-check
verifies slots, deadlines and ordering. A wait whose length is an answer,
and a blocking wait for an answer, are barriers for the lines that depend
on them (through async, a measurement or answer, a branch or a shared
tone): those lines split into segments (ScheduledKernel.segments()) whose start
shifts with the run-time lengths before them, and other lines keep their
time, so qubits waiting on answers of their own run side by side. -
Simulating and emulating calls.
pulse.simulatebinds answers per
measurement path, with timeouts from the latency model, assignment errors
and relaxation during readout, IQ points from a dispersive readout model,
andquantum_system=to simulate a drifted quantum system without compiling again.
ScheduledKernel.export_to_emulator()writes the schedule, segments and call manifest
for a controller;classical.emulation.emulateruns a program in virtual
time against real services, in process or over UDP. Requests and answers
use the CUDA-Q real-time wire format (classical.wire). The
cuDensityMat runtime keeps a classical handler table per run. -
CUDA-Q QEC decoders.
pulse.classicaltakes CUDA-Q QEC's real-time
decoding functions (cudaq_qec.qec.enqueue_syndromes,get_corrections,
reset_decoder, cudaq-qec 0.6.0 to 0.8.1): a kernel calls a decoder
configured in CUDA-Q QEC with CUDA-Q QEC's arguments, its requests are the
decoding server's messages, and simulation and emulation answer with the
configured decoders through CUDA-Q QEC's simulation library. Example
27_realtime_decoding.py. -
Calibrating while the QPU runs.
classical.calibration(adaptive T1,
a frequency binary search, three-point decay and phase estimators,
golden-section and Nelder-Mead steps),classical.random_index(an
on-device random source),classical.loop(a parameter store whose values
programs read at run time, and an estimate log), and the outcome
probabilities of those experiments with ideal pulses
(survival_probability,ramsey_probability,rabi_probability), for
drawing shots without simulating them. Every time an
estimator takes is apulse.Timeor a number of ns
(ramsey_detuning(mean_hz, theta, 2 * pulse.us)); converting it costs a
controller nothing. Examples
19_classical_calls.pyand20_adaptive_calibration.py, and the
"Classical Calls at QPU Runtime" guide. -
Parameter drift.
pulse.quantum_system(..., parameter_drift=True, parameter_drift_seed=5)(orqs.replace(parameter_drift=...)) builds a
simulated quantum system whose qudit frequencies, T1 and drive amplitudes
drift:Truefor the defaultParameterDrift()on every qudit, a model
for every qudit, or{qudit: model}. Compiling reads only its calibrated
values (qs.physical_qudits), so it has its non-drifting twin's
fingerprint, compiled programs and exports;pulse.simulateplays its
true values (qs.true_qudits, the samePhysicalQudittype), which start
at the calibration. Drift time follows the run clock: eachsimulate
advances it byshots_counttimes the program's duration plus
reset_time(a newsimulatekeyword, by default five times the longest
calibrated T1 of the program's qudits), holding the true values for the
call and splitting a call longer than the drift's correlation time into
chunks of shots;qs.advance(20 * pulse.ms)moves time on between
experiments andqs.parameter_drift_timereads it. The defaults
(cudaq_pulse.quantum_systems.drift:OrnsteinUhlenbeckfrequency and
amplitude,TelegraphT1) are slow, transmon-sized drift; a model of your
own is any object withstart(calibrated, rng)and
advance(true, calibrated, seconds, rng). Example
26_drift_following.pyfollows a drifting qudit by swapping programs. -
Controller backends.
ScheduledKernel.export_to_controller()exports a
scheduled kernel for an out-of-tree controller backend, format
cudaq-pulse.controller/1(cudaq_pulse.controller.FORMAT): the lines
with their roles, and every drive, readout, wait, sync and classical call
with its exact start and end, waveform and parameters (and, with
sample_rate_ghz=, its samples), tone frequency and frame phase (including
the phase a detuned tone gains between drives), segment and the
measurement- or answer-conditioned branches it lies in. What is known only
at run time is exported as an expression over readouts and answers: a
waveform parameter (runtime, including a value a measurement selects),
a variable wait's length and bounds, a submission's operands, and, on a
tone whose frame depends on run time, the frame changes since its
previous drive (tone,frame_updates), each with where it is made
(start_cycles), so a backend can compute them where the answer arrives
and the phase the frame gains from there, and each such tone's line and
the frame every shot starts it in (runtime_tones). A program that
computes nothing at run time exports exactly as before. Within a version,
keys and event kinds are only added. AController(...), given to
pulse.compile(control_system=...)alone or in itsControlSystem,
states what a controller can play (clock, issue
spacing, waveform memory at itssample_rate_ghz, tones, the largest
amplitude, readout detectors, feedback latency, answer timeouts, program
size; the compiler itself limits no amplitude) and makes compilation fail with
ControllerLimitErrorwhen a program exceeds it, parametric kernels
included: a limit that only some values of a float parameter exceed, such
as a tone shift, a waveform width or a wait length, is checked at the call
with its values, so a call that lowers also exports.cudaq_pulse.backendsfinds backends installed under the
cudaq_pulse.backendsentry-point group; a backend that fails to load, is
not aBackendor reads none of the export formats raises
IncompatibleBackendError, and an unknown nameBackendNotFoundError,
bothBackendErrors.examples/controller_backend/is a toy backend, and
the "Writing a Controller Backend" guide walks through one. -
Controller programs that keep their loops.
export_to_controller(version=2)exports formatcudaq-pulse.controller/2,
which grows with a program's operations rather than its executions: a
loop whose iterations repeat is oneloopevent holding its body, with
its trip count, period and each tone's phase step per iteration; each
distinct waveform is listed once; and what follows from the rest is left
out. The program writes the controller'ssample_rate_ghzbeside
clock_ghz, so it states its own timing (a waveform of n samples lasts
n × clock_ghz / sample_rate_ghz cycles); the two may be in any ratio, and
the export raises rather than round a waveform that is not a whole number
of samples. A line lists its qudits and an event its tones, andprogramsand
bindingsare reserved for programs shared by several controllers.
controller.unroll()turns it into format /1. The export and the
controller limit checks are native, and the checks reason about a
repeating loop from its first two iterations and its last, so checking a
rolled loop costs the same whatever its trip count. On a 320,000-event
rolled program, compiling with limits takes 25 ms instead of 6 s,
and the /2 export 2 ms and 14 KB instead of 117 MB; /1 is built on the
same walk, 3 to 4 times faster than before. Values known only at run
time are in /2 as in /1, with references as places in the tree and a
waveform's run-time parameters as expressions in its entry, so a loop of
calls whose answers set its amplitudes stays one loop. -
Frames on the timeline. Every shot starts from the reset frame. The
four frame changes (shift_phase,set_phase,shift_frequency,
set_frequency) are points on the timeline, with a start and no
duration in the scheduled IR; the next drive or readout on the tone takes
each, in a loop the next iteration does. The compiler keeps every change:
where nothing takes one on some path, the export gives it as a
frame_updateevent of its own (Event.FRAME_UPDATE), with its change
and the tone's frame after it. A change nothing takes is one where it is
made, also in a rolled loop's body; the change a loop carries out of its
last iteration follows the loop; one made before a branch that only one
arm takes starts the other arm. A loop kept rolled stays rolled, and no
event, loop or program starts or lasts otherwise for a change.
Controller(persistent_frames=True)declares a controller whose
frames persist from shot to shot: such changes then have no event, and
the export'sframe_stategives the frame each tone ends the shot in.
Controller(blocks_on_calls=True)declares one that plays nothing while
a classical call is out: each call holds every line from its submission
until its answer is due, in every schedule, and its exports list the
limit. In a control system of several controllers, a call holds those
that block and issue it, read a measurement it sends or play with its
answer.
Programs without such changes export as before. -
Timing budgets.
@pulse.kernel(max_duration_cycles=n)fails
compilation when an execution of the kernel can take more thann
cycles: each call of a kernel with its ownschedule=(a loop body that
must fit its cycle, checked once whatever the trip count), or the whole
program for the kernel compiled.@pulse.classical(reaction_deadline_ns=...)
fails it when a call's answer is due later than that after the end of
the readouts its request carries, in any iteration. Waits whose length
is known only at run time count at their highest length. -
Waveform memory.
Controller(waveform_memory_samples=65536, waveform_memory="shared")describes a controller's waveform memory in
plain values, the same in Python and in a TOML description: its size in
samples, and whether each line has one ("per_line", the default) or one
serves every line ("shared", holding a waveform the lines share once);
WaveformMemoryScopenames the two. In format /2,
each waveform has anidfrom its content and ashape_idequal for
waveforms that differ only in amplitude and phase, andparameterssays
what eachfloatparameter reaches, so a planner can tell which values
change only amplitudes. The links are written in /2 under their new
names (send_ns,slots, ...), what the controller computes as a list
ofprocessors, and the
quantum system's name asquantum_system. Two waveforms of
one shape atfloatamplitudes share memory, and a limit that only some
floatvalues exceed is checked when a call supplies them. -
Event kinds.
pulse.Eventnames the kinds of event in format /2 for
what a controller does, whatever the modality:play,readout,
wait,sync,loop,callandanswer(/1 keepsdrive,readout
andsubmit). The export holds the plain strings. -
Backend validation.
backends.validate(backend, controller=...)runs
the export test corpus, a program per event kind, through a backend: each
program must be emitted or refused withIncompatibleBackendError, and
unknown event kinds and newer formats refused. A backend that gives its
emitted events back (events()) is checked for timing, order, program
count and limits, and one with an emulator (emulate()) against the
simulator. The report'sokandstr()say what failed. -
Public API. The top level is exactly:
- kernels and programs:
kernel,Kernel,compile,CompiledKernel,
ScheduledKernel,Pass,simulate,SimulationResult,
BranchCoverage; - quantum and control systems:
quantum_system,QuantumSystem,Qudit,
Register,Controller,ControlSystem,Processor,Capability,
Link, andgates; - time:
Time,ns,us,ms,s,round_duration,RoundDirection; - classical calls and exports:
classical,Bits,Length,Event; - errors and warnings:
PulseError,Problem,InvalidValueError,
InvalidTypeError,NotFoundError,IndexOutOfRangeError,
UnsupportedError,CompilationError,TimingError,ExecutionError,
InternalError,QuantumSystemDefinitionError,NoQuantumSystemError,
NoProcessQuantumSystemError,QuantumSystemMismatchError,
GpuRuntimeError,PulseWarning,UpgradeNotice; - modules:
viz,controllerandbackends;
plus
__version__.simulate(program, *args, **options)is the one way to simulate: it
takes a kernel and its arguments ascompiletakes a kernel, or a
program compiled already, such as one a worker process receives pickled,
without compiling it again. A module with run-time float parameters
(scheduled.generic) takes their values asbinddoes; the module of a
call, fromkernel.lower(*args)orbind, takes none.bind(values)
takes one real number per parameter, in the order ofparameters; too
few or too many values are anInvalidTypeErrornaming the parameters.
A bool, str or other non-number is anInvalidTypeError, and a NaN or
infinity anInvalidValueError, naming the parameter where the module
is used, as for a kernel call's float arguments.
Every error cudaq-pulse raises on purpose derives fromPulseErrorand
has the built-in base of its kind:InvalidValueErroris aValueError,
InvalidTypeErroraTypeError,NotFoundErroraKeyError,
IndexOutOfRangeErroranIndexError,UnsupportedErrora
NotImplementedError, andCompilationError,ExecutionErrorand
InternalErrorareRuntimeErrors. An
InternalErroris a bug in cudaq-pulse, and its message asks for a
report.Calibration.loadof a calibration that is neither shipped nor a
file raisesNotFoundError, and a malformed request or answer on a
classical channel anExecutionError. Every warning cudaq-pulse issues
is aPulseWarning.
cudaq_pulse.compiler,cudaq_pulse.runtime.simulateand
cudaq_pulse.quantum_systems.transmon_modellist their public names in
__all__, as the other documented modules do.
cudaq_pulse.quantum_systems.UnknownQuantumSystemError(an unregistered
quantum system name) and
cudaq_pulse.compiler.UnsupportedInterpreterError(a Python whose bytecode
the kernel tracer does not know) are public, and every public name is in
the API reference, errors on their own page. - kernels and programs:
-
Quantum system registration, the shipped quantum systems and calibrations, and the kernel
tracer's caches are safe to use from several threads on free-threaded
CPython: each quantum system and calibration is built once. -
Dialects and tools. The Pulse, Classical, QOp and CuDensityMat MLIR
dialects with their lowerings to LLVM. A module describes the quantum
system it plays on inpulse.quantum_system
(#pulse.quantum_system<qudit_frequency_hz = [..], level_counts = [..], anharmonicity_hz = [..], t1_ns = [..], t2_ns = [..], drive_scale_rad_per_ns = [..], static_terms = [..]>, lists by qudit,
each field optional): a compiled module gives the frequencies it is
compiled for, a module lowered for simulation the simulated system,
whose frequencies may differ from its tones'. It describes the control
system inpulse.control_system(#pulse.control_system<clock_period_fs = 1250000/3, lines = [#pulse.line<drive, qudits = [0], delay_cycles = 3>], controllers = [#pulse.controller<grid_cycles = 2, ...>]>): the
program clock's period in femtoseconds as an exact fraction, each line's
qudits, tones at once, delay and controller, and each controller's grid,
outcome latencies, start spread and uncertainty, persistent frames,
blocking on calls andmax_duration_cycles. A function's
pulse.schedule_state(#pulse.schedule_state<unscheduled|timed|placed>,
unscheduled when absent) says how far it is scheduled: scheduling marks it
timed, orplacedwhen a line delay moved some op;pulse-verify
requires a start and duration on every timed op of a timed or placed
function, andpulse-merge-waitstakes only an unscheduled one. The
tools:cudaq-pulse-opt, the MLIR driver, which
also loads out-of-tree pass plugins and whose--versionprints the
cudaq-pulse version and the LLVM it was built with;python -m cudaq_pulse.doctor, which
reports what an installation contains and whether GPU execution works.
A program in the dialects keeps its meaning through MLIR's standard
passes, such ascse,canonicalizeandinline: an operator program
ends inqop.evolve, which evolves the state, so the passes keep it. -
Packaging. One abi3 wheel per platform for CPython 3.12 and newer:
Linux x86_64 and aarch64 (manylinux_2_28) with the CUDA 12 and CUDA 13
GPU runtimes, selected by the[cu12]or[cu13]extra, and macOS arm64
(compiler only). The wheels link their own MLIR, so they need neither
CUDA-Q nor an LLVM installation. Free-threaded CPython 3.14 (3.14t) has
its own wheel per platform, whose extension runs without the GIL.
cudaq-pulse-optcomes in a distribution of its own,cudaq-pulse-tools,
onepy3-nonewheel per platform for every Python, which
pip install cudaq-pulseinstalls automatically (cudaq-pulserequires
it at the same version). Each
wheel carries its license files andTHIRD_PARTY_NOTICES, generated from
what its binaries link, with each third-party license's text. The wheels
are on PyPI (pip install cudaq-pulse, with[cu12],[cu13]or[gpu]
for GPU simulation); each GitHub release also carries them and the sdist.
Fixed
- Only the first rolled
range()loop over a name stayed rolled: every
later loop over the same name (for _ in range(n)twice in a row, or an
inner loop in each iteration of an unrolled outer one) was unrolled, even
withunroll_threshold=0, because the value the name was left holding
counted as Python state the body changed. Each such loop now stays
rolled; the program, its schedule and its simulation are as before. - A tone that an arm of a measurement-conditioned
ifchanged with
shift_phase,set_phase,shift_frequencyorset_frequencyalone,
with no drive on it in that arm and nosyncwith the readout line after
the readout, was scheduled as ready before the measurement: the next drive
on it started while the readout was still playing (ASAP or ALAP), and ALAP
could move the readout after that drive. In export and simulation the
drive used a phase or frequency the measurement had not yet chosen. A
value an arm of anifyields is now ready only once its condition is,
under every schedule, also in kernels with classical calls. Programs
without such an arm schedule as before. - Values no op can take are a
CompilationErrorthat names the op, the
value and the kernel line that wrote it, rather than compiling silently
or failing in an MLIR pass: a NaN or infinite amplitude, sigma, beta,
phase, frequency orcustom_samplessample; a sigma that is not
positive; an amplitude or other float that is not a number, such as
Noneor a string, even onefloat()would parse ("0.5"); and a
duration outside its cycles. A waveform lasts 1 to 253
cycles, and a wait, a flat top (gaussian_squarewidth) or a bound 0 to
253, whether given as anint, a time, or anintorfloatargument
the kernel is compiled for. Arange()loop runs at most 2**63 - 1
times; a longer one is aCompilationErrorat its line, not an
OverflowError. A controller holds at most
Controller.max_instructionsoperations (unset: no limit); a loop
that unrolls past them stops tracing as soon as the program does, with a
CompilationErrorat the loop's line naming the loop, about how many
operations it unrolls to and the limit.simulate(shots_count=...)andemulate(shots_count=...)
take a positiveint(InvalidTypeErrororInvalidValueError
otherwise;simulate's defaultNonestill samples nothing), and a
qudit index past a quantum system or register is anIndexOutOfRangeError, an
IndexError, that says how many qudits it has. A NaN or infinite float argument is an
InvalidValueErrornaming the parameter wherever the program is used:
run, simulated, exported or printed. Finding the line of a value the
native builder rejects traces the kernel again only up to it, and never
runs its host code again (Python functions it calls,custom()
envelopes,print,next, impure functions): when host code comes
first, the error names that call as the line the value is at or after.