pyquil.quilatom module

Classes that represent the atomic building blocks of Quil expressions.

class pyquil.quilatom.Add(op1: Expression | int | float | complex, op2: Expression | int | float | complex)[source]

Bases: BinaryExp

The addition operation.

Initialize a new addition operation between two expressions.

associates: ClassVar[str] = 'both'
static fn(a: Expression | int | float | complex, b: Expression | int | float | complex) Add | int | float | complex[source]

Perform the addition operation.

operator: ClassVar[str] = ' + '
precedence: ClassVar[int] = 1
class pyquil.quilatom.BinaryExp(op1: Expression | int | float | complex, op2: Expression | int | float | complex)[source]

Bases: Expression

A Quil binary expression.

Initialize a new binary expression.

associates: ClassVar[str]
static fn(a: Expression | int | float | complex, b: Expression | int | float | complex) BinaryExp | int | float | complex[source]

Perform the operation on the two expressions.

operator: ClassVar[str]
precedence: ClassVar[int]
class pyquil.quilatom.Div(op1: Expression | int | float | complex, op2: Expression | int | float | complex)[source]

Bases: BinaryExp

The division operation.

Initialize a new division operation between two expressions.

associates: ClassVar[str] = 'left'
static fn(a: Expression | int | float | complex, b: Expression | int | float | complex) Div | int | float | complex[source]

Perform the division operation.

operator: ClassVar[str] = '/'
precedence: ClassVar[int] = 2
class pyquil.quilatom.Expression[source]

Bases: object

Expression involving some unbound parameters.

Parameters in Quil are represented as a label like ‘%x’ for the parameter named ‘x’. An example expression therefore may be ‘%x*(%y/4)’.

Expressions may also have function calls, supported functions in Quil are sin, cos, sqrt, exp, and cis.

This class overrides all the Python operators that are supported by Quil.

class pyquil.quilatom.FormalArgument(name: str)[source]

Bases: QuilAtom

Representation of a formal argument associated with a DEFCIRCUIT or DEFGATE … AS PAULI-SUM or DEFCAL form.

Initialize a formal argument.

property index: NoReturn

Formal arguments do not have an index. Using this property raises a RuntimeError.

Deprecated since version 4.0: Getting the index of a FormalArgument is invalid. This method will be removed in a future release.

out() str[source]

Return the element as a valid Quil string.

class pyquil.quilatom.Frame(qubits: Sequence[Qubit | QubitPlaceholder | FormalArgument | int], name: str)[source]

Bases: FrameIdentifier

Representation of a frame descriptor.

Initialize a new Frame.

out() str[source]

Return the frame as a valid Quil string.

property qubits: tuple[Qubit | QubitPlaceholder | FormalArgument | int, ...]

Get the qubits in the frame.

class pyquil.quilatom.Function(name: str, expression: Expression | int | float | complex, fn: Callable[[int | float | complex], int | float | complex])[source]

Bases: Expression

Base class for standard Quil functions.

Initialize a new function.

class pyquil.quilatom.Label(label_name: str)[source]

Bases: QuilAtom

Representation of a label.

Parameters:

label_name – The label name.

Initialize a new label.

property name: str

Return the label name.

out() str[source]

Return the label as a valid Quil string.

class pyquil.quilatom.LabelPlaceholder(prefix: str = 'L', *, placeholder: TargetPlaceholder | None = None)[source]

Bases: QuilAtom

A placeholder for a Quil label.

This is useful for constructing circuits without needing to name them. All placeholders must be resolved to actual labels before they can be used in a program.

Initialize a new label placeholder.

out() str[source]

Raise a RuntimeError, as label placeholders are not valid Quil.

property prefix: str

Get the prefix of the label placeholder.

class pyquil.quilatom.MemoryReference(name: str, offset: int = 0, declared_size: int | None = None)[source]

Bases: QuilAtom, Expression

Representation of a reference to a classical memory address.

Parameters:
  • name – The name of the variable

  • offset – Everything in Quil is a C-style array, so every memory reference has an offset.

  • declared_size – The optional size of the named declaration. This can be used for bounds checking, but isn’t. It is used for pretty-printing to quil by deciding whether to output memory references with offset 0 as either e.g. ro[0] or beta depending on whether the declared variable is of length >1 or 1, resp.

Initialize a new memory reference.

out() str[source]

Return the memory reference as a valid Quil string.

class pyquil.quilatom.Mul(op1: Expression | int | float | complex, op2: Expression | int | float | complex)[source]

Bases: BinaryExp

The multiplication operation.

Initialize a new multiplication operation between two expressions.

associates: ClassVar[str] = 'both'
static fn(a: Expression | int | float | complex, b: Expression | int | float | complex) Mul | int | float | complex[source]

Perform the multiplication operation.

operator: ClassVar[str] = '*'
precedence: ClassVar[int] = 2
class pyquil.quilatom.Parameter(name: str)[source]

Bases: QuilAtom, Expression

Parameters in Quil are represented as a label like ‘%x’ for the parameter named ‘x’.

Initialize a new parameter.

out() str[source]

Return the parameter as a valid Quil string.

class pyquil.quilatom.Pow(op1: Expression | int | float | complex, op2: Expression | int | float | complex)[source]

Bases: BinaryExp

The exponentiation operation.

Initialize a new exponentiation operation between two expressions.

associates: ClassVar[str] = 'right'
static fn(a: Expression | int | float | complex, b: Expression | int | float | complex) Pow | int | float | complex[source]

Perform the exponentiation operation.

operator: ClassVar[str] = '^'
precedence: ClassVar[int] = 3
class pyquil.quilatom.Qubit(index: int)[source]

Bases: QuilAtom

Representation of a qubit.

Parameters:

index – Index of the qubit.

Initialize a qubit.

out() str[source]

Return the element as a valid Quil string.

class pyquil.quilatom.QubitPlaceholder(placeholder: QubitPlaceholder | None = None)[source]

Bases: QuilAtom

A placeholder for a qubit.

This is useful for constructing circuits without assigning qubits to specific indices. Qubit placeholders must be resolved to actual qubits before they can be used in a program.

Initialize a qubit placeholder, or get a new handle for an existing placeholder.

property index: NoReturn

Raise a RuntimeError, as Qubit placeholders do not have an index.

out() str[source]

Raise a RuntimeError, as Qubit placeholders are not valid Quil.

static register(n: int) list[QubitPlaceholder][source]

Return a ‘register’ of n QubitPlaceholders.

>>> from pyquil import Program
>>> from pyquil.gates import H
>>> from pyquil.quil import address_qubits
>>> from pyquil.quilatom import QubitPlaceholder
>>> qs = QubitPlaceholder.register(8)  # a qubyte
>>> prog = Program(H(q) for q in qs)
>>> address_qubits(prog).out()
'H 0\nH 1\nH 2\nH 3\nH 4\nH 5\nH 6\nH 7\n'
>>>

The returned register is a Python list of QubitPlaceholder objects, so all normal list semantics apply.

Parameters:

n – The number of qubits in the register

class pyquil.quilatom.QuilAtom[source]

Bases: object

Abstract class for atomic elements of Quil.

out() str[source]

Return the element as a valid Quil string.

class pyquil.quilatom.Sub(op1: Expression | int | float | complex, op2: Expression | int | float | complex)[source]

Bases: BinaryExp

The subtraction operation.

Initialize a new addition operation between two expressions.

associates: ClassVar[str] = 'left'
static fn(a: Expression | int | float | complex, b: Expression | int | float | complex) Sub | int | float | complex[source]

Perform the subtraction operation.

operator: ClassVar[str] = ' - '
precedence: ClassVar[int] = 1
class pyquil.quilatom.TemplateWaveform(name: str, *, duration: float, **kwargs: Expression | MemoryReference | int | float | complex | number | None)[source]

Bases: WaveformInvocation, QuilAtom

Base class for creating waveform templates.

Initialize a new TemplateWaveform.

NAME: ClassVar[str]
property duration: Expression | MemoryReference | int | float | complex | number | None
get_parameter(name: str) Expression | MemoryReference | int | float | complex | number | None[source]

Get a parameter in the waveform by name.

num_samples(rate: float) int[source]

Return the number of samples in the reference implementation of the waveform.

Note: this does not include any hardware-enforced alignment (cf. documentation for samples).

Parameters:

rate – The sample rate, in Hz.

Returns:

The number of samples.

out() str[source]

Return the waveform as a valid Quil string.

samples(rate: float) ndarray[source]

Generate samples of the waveform.

Note: this is close but not always exactly equivalent to the actual IQ values produced by the waveform generators on Rigetti hardware. The actual ADC process imposes some alignment constraints on the waveform duration (in particular, it must be compatible with the clock rate).

Parameters:

rate – The sample rate, in Hz.

Returns:

An array of complex samples.

set_parameter(name: str, value: Expression | MemoryReference | int | float | complex | number | None) None[source]

Set a parameter with a value.

class pyquil.quilatom.WaveformInvocation(name: str, parameters: dict[str, Expression | MemoryReference | int | float | complex | number] | None = None)[source]

Bases: WaveformInvocation, QuilAtom

A waveform invocation.

Initialize a new waveform invocation.

out() str[source]

Return the waveform invocation as a valid Quil string.

property parameters: dict[str, Expression | MemoryReference | int | float | complex | number]

The parameters in the waveform invocation.

class pyquil.quilatom.WaveformReference(*args, **kwargs)[source]

Bases: WaveformInvocation

Representation of a Waveform reference.

Deprecated since version 4.0: The WaveformReference class will be removed, consider using WaveformInvocation instead.

Initialize a new waveform invocation.

pyquil.quilatom.format_parameter(element: Expression | MemoryReference | int | float | complex | number) str[source]

Format a particular parameter.

Essentially the same as built-in formatting except using ‘i’ instead of ‘j’ for the imaginary number.

Parameters:

element – The parameter to format for Quil output.

Deprecated since version 4.0: This function has been superseded by the quil package and will be removed soon.

pyquil.quilatom.qubit_index(qubit: Qubit | QubitPlaceholder | FormalArgument | int) int[source]

Get the index of a QubitDesignator.

Parameters:

qubit – the qubit designator.

Returns:

An int that is the qubit index.

pyquil.quilatom.quil_cis(expression: Expression | int | float | complex) Function[source]

Quil CIS() function.

pyquil.quilatom.quil_cos(expression: Expression | int | float | complex) Function[source]

Quil SIN() function.

pyquil.quilatom.quil_exp(expression: Expression | int | float | complex) Function[source]

Quil EXP() function.

pyquil.quilatom.quil_sin(expression: Expression | int | float | complex) Function[source]

Quil COS() function.

pyquil.quilatom.quil_sqrt(expression: Expression | int | float | complex) Function[source]

Quil SQRT() function.

pyquil.quilatom.substitute(expr: Expression | int | float | complex, d: Mapping[Parameter | MemoryReference, int | float | complex]) Expression | int | float | complex[source]

Explicitly evaluate as much of expr as possible, using substitutions from d.

This supports substitution of both parameters and memory references. Each memory reference must be individually assigned a value at each memory offset to be substituted.

Parameters:
  • expr – The expression whose parameters or memory references are to be substituted.

  • d – Numerical substitutions for parameters or memory references.

Returns:

A partially simplified Expression, or a number.

pyquil.quilatom.substitute_array(a: Sequence[Expression] | ndarray, d: Mapping[Parameter | MemoryReference, int | float | complex]) ndarray[source]

Apply substitute to all elements of an array a and return the resulting array.

Parameters:
  • a – The array of expressions whose parameters or memory references are to be substituted.

  • d – Numerical substitutions for parameters or memory references, for all array elements.

Returns:

An array of partially substituted Expressions, or numbers.

pyquil.quilatom.unpack_classical_reg(c: MemoryReference | MemoryReference | tuple[str, int] | list[Any] | str) MemoryReference[source]

Get the address for a classical register.

Parameters:

c – A list of length 2, a pair, a string (to be interpreted as name[0]), or a MemoryReference.

Returns:

The address as a MemoryReference.

pyquil.quilatom.unpack_qubit(qubit: Qubit | QubitPlaceholder | FormalArgument | int) Qubit | QubitPlaceholder | FormalArgument[source]

Get a qubit from an object.

Parameters:

qubit – the qubit designator to unpack.

Returns:

A Qubit or QubitPlaceholder instance