Utilities¶

Module name: pennylane.utils

This module contains utilities and auxiliary functions, which are shared across the PennyLane submodules.

Summary

 Iterate through an arbitrarily nested structure, flattening it in depth-first order. _unflatten(flat, model) Restores an arbitrary nested structure to a flattened iterable. unflatten(flat, model) Wrapper for _unflatten(). Reverse a dictionary mapping. Get the default arguments of a function. expand(U, wires, num_wires) Expand a multi-qubit operator into a full system operator. CircuitGraph(queue, observables[, parameters]) Represents a queue of operations and observables as a directed acyclic graph.

Code details

_flatten(x)[source]

Iterate through an arbitrarily nested structure, flattening it in depth-first order.

See also _unflatten().

Parameters

x (array, Iterable, other) – each element of the Iterable may itself be an iterable object

Yields

other – elements of x in depth-first order

_unflatten(flat, model)[source]

Restores an arbitrary nested structure to a flattened iterable.

See also _flatten().

Parameters
• flat (array) – 1D array of items

• model (array, Iterable, Number) – model nested structure

Returns

first elements of flat arranged into the nested structure of model, unused elements of flat

Return type

(other, array)

unflatten(flat, model)[source]

Wrapper for _unflatten().

_inv_dict(d)[source]

Reverse a dictionary mapping.

Returns multimap where the keys are the former values, and values are sets of the former keys.

Parameters

d (dict[a->b]) – mapping to reverse

Returns

reversed mapping

Return type

dict[b->set[a]]

_get_default_args(func)[source]

Get the default arguments of a function.

Parameters

func (function) – a valid Python function

Returns

dictionary containing the argument name and tuple (positional idx, default value)

Return type

dict

expand(U, wires, num_wires)[source]

Expand a multi-qubit operator into a full system operator.

Parameters
• U (array) – $$2^n \times 2^n$$ matrix where n = len(wires).

• wires (Sequence[int]) – Target subsystems (order matters! the left-most Hilbert space is at index 0).

Returns

$$2^N\times 2^N$$ matrix. The full system operator.

Return type

array

class Command(name, op, return_type, idx)
_asdict()

Return a new OrderedDict which maps field names to their values.

classmethod _make(iterable, new=<built-in method __new__ of type object>, len=<built-in function len>)

Make a new Command object from a sequence or iterable

_replace(**kwds)

Return a new Command object replacing specified fields with new values

count(value) → integer -- return number of occurrences of value
property idx

Alias for field number 3

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

property name

Alias for field number 0

property op

Alias for field number 1

property return_type

Alias for field number 2

class Layer(op_idx, param_idx)
_asdict()

Return a new OrderedDict which maps field names to their values.

classmethod _make(iterable, new=<built-in method __new__ of type object>, len=<built-in function len>)

Make a new Layer object from a sequence or iterable

_replace(**kwds)

Return a new Layer object replacing specified fields with new values

count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

property op_idx

Alias for field number 0

property param_idx

Alias for field number 1

class CircuitGraph(queue, observables, parameters=None)[source]

Represents a queue of operations and observables as a directed acyclic graph.

Parameters
• queue (list[Operation]) – the quantum operations to apply

• observables (list[Observable]) – the quantum observables to measure

• parameters (dict[int->list[(int, int)]]) – Specifies the free parameters of the quantum circuit. The dictionary key is the parameter index. The first element of the value tuple is the operation index, the second the index of the parameter within the operation.

_grid = None

dictionary representing the quantum circuit as a grid. Here, the key is the wire number, and the value is a list containing the operation index (that is, where in the queue it occured) as well as a Command object containing the operation/observable itself.

Type

dict[int, list[Command]]

property observables

Return a list of operations that have a return type.

property observable_nodes

Return a list of nodes of operations that have a return type, sorted by “idx”.

property operations

Return a list of operations that do not have a return type.

property operation_nodes

Return a list of nodes of operations that do not have a return type, sorted by “idx”.

property graph

The graph representation of the quantum program.

The resulting graph has nodes representing quantum operations, and edges representing dependent/successor operations.

Each node is labelled by an integer corresponding to the position in the queue; node attributes are used to store information about the node:

• 'name' (str): name of the quantum operation (e.g., 'PauliZ')

• 'op' (Operation or Observable): the quantum operation/observable object

• 'return_type' (pennylane.operation.ObservableReturnTypes): The observable return type. If an operation, the return type is simply None.

Returns

the directed acyclic graph representing the quantum program

Return type

networkx.DiGraph

get_op_indices(wire)[source]

The operation indices on the given wire.

Parameters

wire (int) – the wire to examine

Returns

all operation indices on the wire, in temporal order

Return type

list (int)

ancestors(ops)[source]

Returns all ancestor operations of a given set of operations.

Parameters

ops (Iterable[int]) – a given set of operations labelled by integer position in the queue

Returns

integer position of all operations in the queue that are ancestors of the given operations

Return type

set[int]

descendants(ops)[source]

Returns all descendant operations of a given set of operations.

Parameters

ops (Iterable[int]) – a given set of operations labelled by integer position in the queue

Returns

integer position of all operations in the queue that are descendants of the given operations

Return type

set[int]

get_nodes(ops)[source]

Given a set of operation indices, return the nodes corresponding to the indices.

Parameters

ops (Iterable[int]) – a given set of operations labelled by integer position in the queue

Returns

nodes corresponding to given integer positions in the queue

Return type

List[Node]

get_ops(ops)[source]

Given a set of operation indices, return the operation objects.

Parameters

ops (Iterable[int]) – a given set of operations labelled by integer position in the queue

Returns

operations or observables corresponding to given integer positions in the queue

Return type

List[Operation, Observable]

get_names(ops)[source]

Given a set of operation indices, return the operation names.

Parameters

ops (Iterable[int]) – a given set of operations labelled by integer position in the queue

Returns

operations or observables corresponding to given integer positions in the queue

Return type

List[str]

layers()[source]

Identifies and returns a metadata list describing the layer structure of the circuit.

Each layer is a named tuple containing:

• op_idx (list[int]): the list of operation indices in the layer

• param_idx (list[int]): the list of parameter indices used within the layer

Returns

a list of layers

Return type

list[Layer]

iterate_layers()[source]

Identifies and returns an iterable containing the parametrized layers.

Returns

an iterable that returns a tuple (pre_queue, layer, param_idx, post_queue) at each iteration.

• pre_queue (list[Operation]): all operations that precede the layer

• layer (list[Operation]): the parametrized gates in the layer

• param_idx (tuple[int]): The integer indices corresponding to the free parameters of this layer, in the order they appear in this layer.

• post_queue (list[Operation, Observable]): all operations that succeed the layer

Return type

Iterable[tuple[list, list, tuple, list]]

update_node(node, op)[source]

Updates a given node with a new operation, op.

Parameters
• op (Operation) – an operation to update the given node with

• node (dict) – the node to update