Symbolic quantum operations¶
Module name: pennylane.operation
Operation base classes¶
This module contains the symbolic base class for performing quantum operations and measuring observables in PennyLane.
 Each
Operation
subclass represents a type of quantum operation, for example a unitary quantum gate. Each instance of these subclasses represents an application of the operation with given parameter values to a given sequence of wires (subsystems).  Each
Observable
subclass represents a type of physical observable. Each instance of these subclasses represents an instruction to measure and return the respective result for the given parameter values on a sequence of wires (subsystems).
Differentiation¶
In general, an Operation
is differentiable (at least using the finitedifference
method) with respect to a parameter iff
 the domain of that parameter is continuous.
For an Operation
to be differentiable with respect to a parameter using the
analytic method of differentiation, it must satisfy an additional constraint:
 the parameter domain must be real.
Note
These conditions are not sufficient for analytic differentiation. For example, CV gates must also define a matrix representing their Heisenberg linear transformation on the quadrature operators.
For gates that are supported via the analytic method, the gradient recipe (with multiplier \(c_k\), parameter shift \(s_k\) for parameter \(\phi_k\)) works as follows:
Summary¶
Operation (*args[, wires, do_queue]) 
Base class for quantum operations supported by a device. 
Observable (*args[, wires, do_queue]) 
Base class for observables supported by a device. 
CV Operation base classes¶
Due to additional requirements, continuousvariable (CV) operations must subclass the
CVOperation
or CVObservable
classes instead of Operation
and Observable
.
Differentiation¶
To enable gradient computation using the analytic method for Gaussian CV operations, in addition, you need to
provide the static class method _heisenberg_rep()
that returns the Heisenberg representation of
the operation given its list of parameters, namely:
 For Gaussian CV Operations this method should return the matrix of the linear transformation carried out by the operation on the vector of quadrature operators \(\mathbf{r}\) for the given parameter values.
 For Gaussian CV Observables this method should return a real vector (firstorder observables) or symmetric matrix (secondorder observables) of coefficients of the quadrature operators \(\x\) and \(\p\).
PennyLane uses the convention \(\mathbf{r} = (\I, \x, \p)\) for singlemode operations and observables and \(\mathbf{r} = (\I, \x_0, \p_0, \x_1, \p_1, \ldots)\) for multimode operations and observables.
Note
NonGaussian CV operations and observables are currently only supported via the finitedifference method of gradient computation.
Summary¶
CV 
A mixin base class denoting a continuousvariable operation. 
CVOperation (*args[, wires, do_queue]) 
Base class for continuousvariable quantum operations. 
CVObservable (*args[, wires, do_queue]) 
Base class for continuousvariable observables. 
Code details¶

class
Wires
[source]¶ Integer enumeration class to represent the number of wires an operation acts on

All
= <Wires.All: 0>¶ An enumeration which represents all wires in the subsystem. It is equivalent to an integer with value 0.
Type: IntEnum

Any
= <Wires.Any: 1>¶ An enumeration which represents any wires in the subsystem. It is equivalent to an integer with value 1.
Type: IntEnum

class
ObservableReturnTypes
[source]¶ Enumeration class to represent the type of return types of an observable.

Sample
= <ObservableReturnTypes.Sample: 1>¶ An enumeration which represents sampling an observable.
Type: Enum

Variance
= <ObservableReturnTypes.Variance: 2>¶ An enumeration which represents returning the variance of an observable on specified wires.
Type: Enum

Expectation
= <ObservableReturnTypes.Expectation: 3>¶ An enumeration which represents returning the expectation value of an observable on specified wires.
Type: Enum

class
Operation
(*args, wires=None, do_queue=True)[source]¶ Base class for quantum operations supported by a device.
The following class attributes must be defined for all Operations:
The following two class attributes are optional, but in most cases should be clearly defined to avoid unexpected behavior during differentiation.
Finally, there are some additional optional class attributes that may be set, and used by certain quantum optimizers:
Parameters: args (tuple[float, int, array, Variable]) – operation parameters
Keyword Arguments:  wires (Sequence[int]) – Subsystems it acts on. If not given, args[1] is interpreted as wires.
 do_queue (bool) – Indicates whether the operation should be
immediately pushed into a
QNode
circuit queue. This flag is useful if there is some reason to run an Operation outside of a QNode context.

num_params
¶ Number of parameters the operation takes.

num_wires
¶ Number of wires the operation acts on.
The value 0 allows the operation to act on any number of wires.

par_domain
¶ Domain of the gate parameters.
'N'
: natural numbers (including zero).'R'
: floats.'A'
: arrays of real or complex values.None
: if there are no parameters.

grad_method
¶ Gradient computation method.
'A'
: analytic differentiation.'F'
: finite difference numerical differentiation.None
: the operation may not be differentiated.
Default is
'F'
, orNone
if the Operation has zero parameters.

generator
¶ Generator of the operation.
A length2 list
[generator, scaling_factor]
, wheregenerator
is an existing PennyLane operation class or \(2\times 2\) Hermitian array that acts as the generator of the current operationscaling_factor
represents a scaling factor applied to the generator operation
For example, if \(U(\theta)=e^{i0.7\theta \sigma_x}\), then \(\sigma_x\), with scaling factor \(s\), is the generator of operator \(U(\theta)\):
generator = [PauliX, 0.7]
Default is
[None, 1]
, indicating the operation has no generator.

name
= None¶ name of the operation
Type: str

grad_recipe
¶ Gradient recipe for the analytic differentiation method.
This is a list with one tuple per operation parameter. For parameter \(k\), the tuple is of the form \((c_k, s_k)\), resulting in a gradient recipe of
\[\frac{\partial}{\partial\phi_k}O = c_k\left[O(\phi_k+s_k)O(\phi_ks_k)\right].\]If this property returns
None
, the default gradient recipe \((c_k, s_k)=(1/2, \pi/2)\) is assumed for every parameter.

check_wires
(wires)[source]¶ Check the validity of the operation wires.
Parameters: wires (Sequence[int, Variable]) – wires to check Raises: TypeError
– list of wires is invalidReturns: p Return type: Number, array, Variable

check_domain
(p, flattened=False)[source]¶ Check the validity of a parameter.
Parameters:  p (Number, array, Variable) – parameter to check
 flattened (bool) – True means p is an element of a flattened parameter sequence (affects the handling of ‘A’ parameters)
Raises: TypeError
– parameter is not an element of the expected domainReturns: p
Return type: Number, array, Variable

wires
¶ Current wire values.
Fixed wires are returned as is, free wires represented by
Variable
instances are replaced by their current numerical value.Returns: wire values Return type: list[int]

class
Observable
(*args, wires=None, do_queue=True)[source]¶ Base class for observables supported by a device.
Observable
is used to describe Hermitian quantum observables.As with
Operation
, the following class attributes must be defined for all observables:The following two class attributes are optional, but in most cases should be clearly defined to avoid unexpected behavior during differentiation.
Parameters: args (tuple[float, int, array, Variable]) – observable parameters
Keyword Arguments:  wires (Sequence[int]) – subsystems it acts on. Currently, only one subsystem is supported.
 do_queue (bool) – Indicates whether the operation should be immediately
pushed into a
QNode
observable queue. This flag is useful if there is some reason to call an observable outside of a QNode context.

class
CV
[source]¶ A mixin base class denoting a continuousvariable operation.

heisenberg_expand
(U, num_wires)[source]¶ Expand the given local Heisenbergpicture array into a fullsystem one.
Parameters:  U (array[float]) – array to expand (expected to be of the dimension
1+2*self.num_wires
)  num_wires (int) – total number of wires in the quantum circuit. If zero, return
U
as is.
Returns: expanded array, dimension
1+2*num_wires
Return type: array[float]
 U (array[float]) – array to expand (expected to be of the dimension

static
_heisenberg_rep
(p)[source]¶ Heisenberg picture representation of the operation.
For Gaussian CV gates, this method returns the matrix of the linear transformation carried out by the gate for the given parameter values. The method is not defined for nonGaussian gates.
The existence of this method is equivalent to setting
grad_method = 'A'
.For observables, returns a real vector (firstorder observables) or symmetric matrix (secondorder observables) of expansion coefficients of the observable.
For singlemode Operations we use the basis \(\mathbf{r} = (\I, \x, \p)\). For multimode Operations we use the basis \(\mathbf{r} = (\I, \x_0, \p_0, \x_1, \p_1, \ldots)\).
Note
For gates, we assume that the inverse transformation is obtained by negating the first parameter.
Parameters: p (Sequence[float]) – parameter values for the transformation Returns: \(\tilde{U}\) or \(q\) Return type: array[float]


class
CVOperation
(*args, wires=None, do_queue=True)[source]¶ Base class for continuousvariable quantum operations.

heisenberg_pd
(idx)[source]¶ Partial derivative of the Heisenberg picture transform matrix.
Computed using grad_recipe.
Parameters: idx (int) – index of the parameter with respect to which the partial derivative is computed. Returns: partial derivative Return type: array[float]

heisenberg_tr
(num_wires, inverse=False)[source]¶ Heisenberg picture representation of the linear transformation carried out by the gate at current parameter values.
Given a unitary quantum gate \(U\), we may consider its linear transformation in the Heisenberg picture, \(U^\dagger(\cdot) U\).
If the gate is Gaussian, this linear transformation preserves the polynomial order of any observables that are polynomials in \(\mathbf{r} = (\I, \x_0, \p_0, \x_1, \p_1, \ldots)\). This also means it maps \(\text{span}(\mathbf{r})\) into itself:
\[U^\dagger \mathbf{r}_i U = \sum_j \tilde{U}_{ij} \mathbf{r}_j\]For Gaussian CV gates, this method returns the transformation matrix for the current parameter values of the Operation. The method is not defined for nonGaussian (and nonCV) gates.
Parameters:  num_wires (int) – total number of wires in the quantum circuit
 inverse (bool) – if True, return the inverse transformation instead
Returns: \(\tilde{U}\), the Heisenberg picture representation of the linear transformation
Return type: array[float]


class
CVObservable
(*args, wires=None, do_queue=True)[source]¶ Base class for continuousvariable observables.
The class attribute
ev_order
can be defined to indicate to PennyLane whether the corresponding CV observable is a polynomial in the quadrature operators. If so,ev_order = 1
indicates a first order polynomial in quadrature operators \((\x, \p)\).ev_order = 2
indicates a second order polynomial in quadrature operators \((\x, \p)\).
If
ev_order
is notNone
, then the Heisenberg representation of the observable should be defined in the static method_heisenberg_rep()
, returning an array of the correct dimension.
ev_order
= None¶ if not None, the observable is a polynomial of the given order in (x, p).
Type: None, int

heisenberg_obs
(num_wires)[source]¶ Representation of the observable in the position/momentum operator basis.
Returns the expansion \(q\) of the observable, \(Q\), in the basis \(\mathbf{r} = (\I, \x_0, \p_0, \x_1, \p_1, \ldots)\).
 For firstorder observables returns a real vector such that \(Q = \sum_i q_i \mathbf{r}_i\).
 For secondorder observables returns a real symmetric matrix such that \(Q = \sum_{ij} q_{ij} \mathbf{r}_i \mathbf{r}_j\).
Parameters: num_wires (int) – total number of wires in the quantum circuit Returns: \(q\) Return type: array[float]