View on QuantumAI Run in Google Colab View source on GitHub Download notebook
    import cirq
except ImportError:
    print("installing cirq...")
    !pip install --quiet cirq
    print("installed cirq.")
    import cirq

Validation basics

When you are looking to run an algorithm on a real quantum computer (not a simulated one), there are often many additional constraints placed on the circuits you would like to run. Qubit connectivity, algorithm layout and the types of gates used in the circuit all become much more important. Cirq uses the abstract class Device to represent the constraints of an actual quantum processor. An example implementation of a device can be seen in the cirq_google.Sycamore class:

import cirq_google
import networkx as nx

my_device = cirq_google.Sycamore
(0, 5)───(0, 6)
                                             │        │
                                             │        │
                                    (1, 4)───(1, 5)───(1, 6)───(1, 7)
                                    │        │        │        │
                                    │        │        │        │
                           (2, 3)───(2, 4)───(2, 5)───(2, 6)───(2, 7)───(2, 8)
                           │        │        │        │        │        │
                           │        │        │        │        │        │
                  (3, 2)───(3, 3)───(3, 4)───(3, 5)───(3, 6)───(3, 7)───(3, 8)───(3, 9)
                  │        │        │        │        │        │        │        │
                  │        │        │        │        │        │        │        │
         (4, 1)───(4, 2)───(4, 3)───(4, 4)───(4, 5)───(4, 6)───(4, 7)───(4, 8)───(4, 9)
         │        │        │        │        │        │        │        │
         │        │        │        │        │        │        │        │
(5, 0)───(5, 1)───(5, 2)───(5, 3)───(5, 4)───(5, 5)───(5, 6)───(5, 7)───(5, 8)
         │        │        │        │        │        │        │
         │        │        │        │        │        │        │
         (6, 1)───(6, 2)───(6, 3)───(6, 4)───(6, 5)───(6, 6)───(6, 7)
                  │        │        │        │        │
                  │        │        │        │        │
                  (7, 2)───(7, 3)───(7, 4)───(7, 5)───(7, 6)
                           │        │        │
                           │        │        │
                           (8, 3)───(8, 4)───(8, 5)
                                    (9, 4)

This string representation of the device indicates the structure of the device and the connectivity of the qubits. In Sycamore's case, two-qubit gates can only be executed on qubits that are adjacent in the grid. Other constraints, like supported gates, are not shown in this representation.

You can access all of the constraints indirectly by validating moments, operations and circuits with the validate_*** method to verify if that structure would work on the device or not. In general, the validate_*** method will tell you what part of your operation/moment/circuit does not fit the device's constraints, and why. All devices support this functionality. For the Sycamore device:

op1 = cirq.X(cirq.GridQubit(7, 7))

except Exception as e:
Qubit not on device: cirq.GridQubit(7, 7)

The previous example used a qubit that wasn't on the device, making the operation invalid. Most validate_operation implementations also take into account things like supported gates and connectivity as well:

q1, q2, q3 = cirq.GridQubit(7, 4), cirq.GridQubit(7, 5), cirq.GridQubit(7, 6)
op1 = cirq.H(q1)
op2 = cirq_google.SYC(q1, q3)

except Exception as e:

except Exception as e:
H((7, 4)) is not a supported gate
Operation does not use valid qubit target: SYC((7, 4), (7, 6)).

These validation operations can also be used with moments of operations and full circuits:

op1 = cirq.X(q2)
op2 = cirq_google.SYC(q1, q3)
    my_device.validate_moment(cirq.Moment([op1, op2]))
except Exception as e:

my_circuit = cirq.Circuit(
    cirq_google.SYC(q1, q2),
    cirq_google.SYC(q2, q3),
Operation does not use valid qubit target: SYC((7, 4), (7, 6)).

op1 is allowed on qubit q2, but op2 has the same invalid qubit target error as before. validate_moment finds this error by iterating the moment and stopping once the invalid operation is found. On the other hand, my_circuit satisfies all the device constraints and could be run on a Sycamore device, so validate_circuit does not throw an exception for it.

Metadata features

Some devices will also expose additional information via the metadata property. Metadata is usually exposed via the an instance (or subclass instance) of the cirq.DeviceMetadata class. You can access the metadata information of the Sycamore device with the metadata attribute:

metadata = my_device.metadata
<class 'cirq.devices.grid_device_metadata.GridDeviceMetadata'>
issubclass(type(metadata), cirq.DeviceMetadata)

The Sycamore device is a 2d grid device that exposes a cirq.GridDeviceMetadata with a uniform set of gates across all the qubits as well as a planar nearest neighbor connectivity graph. You can explore the properties below, starting with qubit_set and nx_graph, which are common to all instances and subclasses of the cirq.DeviceMetadata class.

First, the set of qubits available are available in the qubit_set attribute.

frozenset({cirq.GridQubit(2, 8), cirq.GridQubit(5, 7), cirq.GridQubit(9, 4), cirq.GridQubit(6, 4), cirq.GridQubit(5, 2), cirq.GridQubit(3, 5), cirq.GridQubit(7, 2), cirq.GridQubit(4, 6), cirq.GridQubit(2, 3), cirq.GridQubit(5, 8), cirq.GridQubit(6, 5), cirq.GridQubit(3, 6), cirq.GridQubit(4, 7), cirq.GridQubit(2, 4), cirq.GridQubit(5, 3), cirq.GridQubit(6, 6), cirq.GridQubit(1, 7), cirq.GridQubit(4, 2), cirq.GridQubit(2, 5), cirq.GridQubit(5, 4), cirq.GridQubit(8, 4), cirq.GridQubit(6, 1), cirq.GridQubit(4, 8), cirq.GridQubit(3, 2), cirq.GridQubit(0, 6), cirq.GridQubit(4, 3), cirq.GridQubit(6, 7), cirq.GridQubit(5, 5), cirq.GridQubit(6, 2), cirq.GridQubit(4, 9), cirq.GridQubit(5, 0), cirq.GridQubit(8, 5), cirq.GridQubit(7, 3), cirq.GridQubit(4, 4), cirq.GridQubit(3, 7), cirq.GridQubit(1, 4), cirq.GridQubit(6, 3), cirq.GridQubit(7, 4), cirq.GridQubit(5, 1), cirq.GridQubit(4, 5), cirq.GridQubit(1, 5), cirq.GridQubit(3, 8), cirq.GridQubit(7, 5), cirq.GridQubit(2, 6), cirq.GridQubit(3, 3), cirq.GridQubit(1, 6), cirq.GridQubit(4, 1), cirq.GridQubit(5, 6), cirq.GridQubit(3, 9), cirq.GridQubit(2, 7), cirq.GridQubit(3, 4), cirq.GridQubit(7, 6), cirq.GridQubit(8, 3), cirq.GridQubit(0, 5)})

The nx_graph attribute details which of the 54 different qubits are connected to one another. Connected qubit pairs can execute two-qubit gates between them.

Graph with 54 nodes and 88 edges

cirq.GridDeviceMetadata has some attributes that are not automatically included in cirq.DeviceMetadata, including gateset, which indicates the types and families of Cirq gates that are accepted by all qubits across the device.

Type GateFamily: cirq.ops.fsim_gate.FSimGate
Accepts `cirq.Gate` instances `g` s.t. `isinstance(g, cirq.ops.fsim_gate.FSimGate)`

Type GateFamily: cirq.ops.swap_gates.ISwapPowGate
Accepts `cirq.Gate` instances `g` s.t. `isinstance(g, cirq.ops.swap_gates.ISwapPowGate)`

Type GateFamily: cirq.ops.phased_x_gate.PhasedXPowGate
Accepts `cirq.Gate` instances `g` s.t. `isinstance(g, cirq.ops.phased_x_gate.PhasedXPowGate)`

Type GateFamily: cirq.ops.common_gates.XPowGate
Accepts `cirq.Gate` instances `g` s.t. `isinstance(g, cirq.ops.common_gates.XPowGate)`

Type GateFamily: cirq.ops.common_gates.YPowGate
Accepts `cirq.Gate` instances `g` s.t. `isinstance(g, cirq.ops.common_gates.YPowGate)`

Type GateFamily: cirq.ops.common_gates.ZPowGate
Accepts `cirq.Gate` instances `g` s.t. `isinstance(g, cirq.ops.common_gates.ZPowGate)`

Type GateFamily: cirq.ops.phased_x_z_gate.PhasedXZGate
Accepts `cirq.Gate` instances `g` s.t. `isinstance(g, cirq.ops.phased_x_z_gate.PhasedXZGate)`

Type GateFamily: cirq.ops.measurement_gate.MeasurementGate
Accepts `cirq.Gate` instances `g` s.t. `isinstance(g, cirq.ops.measurement_gate.MeasurementGate)`

Type GateFamily: cirq.ops.wait_gate.WaitGate
Accepts `cirq.Gate` instances `g` s.t. `isinstance(g, cirq.ops.wait_gate.WaitGate)`

These metadata features can be useful when designing/building algorithms around certain device information in order to tailor them for that device.

The cirq.Device interface

For advanced users (such as vendors) it is also possible to implement your own Device with its own unique constraints and metadata information. Below is an example of a fictitious custom device:

class MyDevice(cirq.Device):
    """Five qubits on a line, supporting X/Y/Z and CZ between neighbors."""

    def __init__(self):
        # Specify the qubits available to the device
        self._qubits = set(cirq.LineQubit.range(5))
        # Specify which gates are valid
        self._supported_gates = cirq.Gateset(
            cirq.XPowGate, cirq.YPowGate, cirq.ZPowGate, cirq.CZPowGate

    def validate_operation(self, operation):
        """Check to make sure `operation` is valid.

        `operation` must be on qubits found on the device
        and if it is a two qubit gate the qubits must be adjacent

          ValueError: if operation acts on qubits not found on the device.
          ValueError: if two qubit gates have non-local interactions.
          ValueError: if the operation is not in the supported gates.
        # Ensure that the operation's qubits are available on the device
        if any(x not in self._qubits for x in operation.qubits):
            raise ValueError("Using qubits not found on device.")

        # Ensure that the operation's qubits are adjacent if there are two of them
        if len(operation.qubits) == 2:
            p, q = operation.qubits
            if not p.is_adjacent(q):
                raise ValueError('Non-local interaction: {}'.format(repr(operation)))

        # Ensure that the operation itself is a supported one
        if operation not in self._supported_gates:
            raise ValueError("Unsupported operation type.")

    def validate_circuit(self, circuit):
        """Check to make sure `circuit` is valid.

        Calls validate_operation on all operations as well as imposing
        a global limit on the total number of CZ gates.

          ValueError: if `validate_operation` raises for any operation in the
          ValueError: if there are more than 10 CZ gates in the entire circuit.
        # Call Device's `validate_operation`, which calls the `validate_operation`
        #   function specified above on each operation in the circuit
        # Ensure that no more than 10 two-qubit CZ gates exist in the circuit
        cz_count = sum(1 for mom in circuit for op in mom if len(op.qubits) == 2)
        if cz_count > 10:
            raise ValueError("Too many total CZs")

    def metadata(self):
        """MyDevice GridDeviceMetadata."""
        # Since `MyDevice` is planar it is a good idea to subclass the
        # GridDeviceMetadata class to communicate additional device information to
        # the user.
        return cirq.GridDeviceMetadata(
            qubit_pairs=[(p, q) for p in self._qubits for q in self._qubits if p.is_adjacent(q)],

At absolute minimum, when creating a custom Device, you should inherit from cirq.Device and overwrite the __init__ and validate_operation methods.

This custom device can now be used to validate circuits:

my_custom_device = MyDevice()

my_circuit = cirq.Circuit(
too_many_czs = cirq.Circuit(cirq.CZ(*cirq.LineQubit.range(2)) for _ in range(11))

# my_circuit is valid for my_custom_device.

# each operation of too_many_czs is valid individually...
for moment in too_many_czs:
    for op in moment:

# But the device has global constraints which the circuit does not meet:
except Exception as e:
Too many total CZs

By default, the validate_circuit method of the cirq.Device class simply calls validate_moment on all the moments, which calls validate_operation on all the operations. It is advisable to maintain this behavior in your custom device, which can be implemented as above, by calling super().validate_*** when writing each method.

Depending on the scoping of constraints the custom device has, certain less local constraints might be better placed in validate_moment and certain global constraints might belong in validate_circuit. In addition to this, you can also add metadata options to your device. You can define a metadata subclass of cirq.DeviceMetadata or you can use an inbuilt metadata class like cirq.GridDeviceMetadata:

my_metadata = my_custom_device.metadata

# Display device graph:



Devices in Cirq are used to specify constraints on circuits that are imposed by quantum hardware devices. You can check that an operation, moment, or circuit is valid on a particular cirq.Device by using validate_operation, validate_moment, or validate_circuit respectively. You can also create your own custom device objects to specify constraints for a new or changed device. Device objects, custom and otherwise, also can carry around metadata that may be useful for the validation process or other processes.