cirq.FrozenCircuit

An immutable version of the Circuit data structure.

Inherits From: AbstractCircuit, SerializableByKey, SupportsJSON

Used in the notebooks

Used in the tutorials

FrozenCircuits are immutable (and therefore hashable), but otherwise behave identically to regular Circuits. Conversion between the two is handled with the freeze and unfreeze methods from AbstractCircuit.

contents The initial list of moments and operations defining the circuit. You can also pass in operations, lists of operations, or generally anything meeting the cirq.OP_TREE contract. Non-moment entries will be inserted according to the specified insertion strategy.
strategy When initializing the circuit with operations and moments from contents, this determines how the operations are packed together.
tags A sequence of any type of object that is useful to attach metadata to this circuit as long as the type is hashable. If you wish the resulting circuit to be eventually serialized into JSON, you should also restrict the tags to be JSON serializable.

moments

tags Returns a tuple of the Circuit's tags.
untagged Returns the underlying FrozenCircuit without any tags.

Methods

all_measurement_key_names

View source

Returns the set of all measurement key names in this circuit.

Returns: FrozenSet of strings that are the measurement key names in this circuit.

all_measurement_key_objs

View source

all_operations

View source

Returns an iterator over the operations in the circuit.

Returns: Iterator over cirq.Operation elements found in this circuit.

all_qubits

View source

Returns the qubits acted upon by Operations in this circuit.

Returns: FrozenSet of cirq.Qid objects acted on by all operations in this circuit.

are_all_matches_terminal

View source

Check whether all of the ops that satisfy a predicate are terminal.

This method will transparently descend into any CircuitOperations this circuit contains; as a result, it will misbehave if the predicate refers to CircuitOperations. See the tests for an example of this.

Args
predicate A predicate on ops.Operations which is being checked.

Returns
Whether or not all Operation s in a circuit that satisfy the given predicate are terminal. Also checks within any CircuitGates the circuit may contain.

are_all_measurements_terminal

View source

Whether all measurement gates are at the end of the circuit.

Returns: True iff no measurement is followed by a gate.

are_any_matches_terminal

View source

Check whether any of the ops that satisfy a predicate are terminal.

This method will transparently descend into any CircuitOperations this circuit contains; as a result, it will misbehave if the predicate refers to CircuitOperations. See the tests for an example of this.

Args
predicate A predicate on ops.Operations which is being checked.

Returns
Whether or not any Operation s in a circuit that satisfy the given predicate are terminal. Also checks within any CircuitGates the circuit may contain.

are_any_measurements_terminal

View source

Whether any measurement gates are at the end of the circuit.

Returns: True iff some measurements are not followed by a gate.

concat_ragged

View source

Concatenates circuits, overlapping them if possible due to ragged edges.

Starts with the first circuit (index 0), then iterates over the other circuits while folding them in. To fold two circuits together, they are placed one after the other and then moved inward until just before their operations would collide. If any of the circuits do not share qubits and so would not collide, the starts or ends of the circuits will be aligned, according to the given align parameter.

Beware that this method is not associative. For example:

a, b = cirq.LineQubit.range(2)
A = cirq.Circuit(cirq.H(a))
B = cirq.Circuit(cirq.H(b))
f = cirq.Circuit.concat_ragged
f(f(A, B), A) == f(A, f(B, A))
False
len(f(f(f(A, B), A), B)) == len(f(f(A, f(B, A)), B))
False

Args
*circuits The circuits to concatenate.
align When to stop when sliding the circuits together. 'left': Stop when the starts of the circuits align. 'right': Stop when the ends of the circuits align. 'first': Stop the first time either the starts or the ends align. Circuits are never overlapped more than needed to align their starts (in case the left circuit is smaller) or to align their ends (in case the right circuit is smaller)

Returns
The concatenated and overlapped circuit.

factorize

View source

Factorize circuit into a sequence of independent circuits (factors).

Factorization is possible when the circuit's qubits can be divided into two or more independent qubit sets. Preserves the moments from the original circuit. If this is not possible, returns the set consisting of the single circuit (this one).

q0, q1, q2 = cirq.LineQubit.range(3)
circuit = cirq.Circuit()
circuit.append(cirq.Moment(cirq.H(q2)))
circuit.append(cirq.Moment(cirq.CZ(q0,q1)))
circuit.append(cirq.H(q0))
print(circuit)
0: ───────@───H───

1: ───────@───────
<BLANKLINE>
2: ───H───────────
for i, f in enumerate(circuit.factorize()):
    print("Factor {}".format(i))
    print(f)

Factor 0
0: ───────@───H───

1: ───────@───────
Factor 1
2: ───H───────────

Returns
The sequence of circuits, each including only the qubits from one independent qubit set.

final_state_vector

View source

Returns the state vector resulting from acting operations on a state.

This is equivalent to calling cirq.final_state_vector with the same arguments and this circuit as the "program".

Args
initial_state If an int, the state is set to the computational basis state corresponding to this state. Otherwise if this is a np.ndarray it is the full initial state. In this case it must be the correct size, be normalized (an L2 norm of 1), and be safely castable to an appropriate dtype for the simulator.
qubit_order Determines the canonical ordering of the qubits. This is often used in specifying the initial state, i.e. the ordering of the computational basis states.
qubits_that_should_be_present Qubits that may or may not appear in operations within the circuit, but that should be included regardless when generating the matrix.
ignore_terminal_measurements When set, measurements at the end of the circuit are ignored instead of causing the method to fail. Defaults to False.
dtype The numpy.dtype used by the simulation. Typically one of numpy.complex64 or numpy.complex128.
param_resolver Parameters to run with the program.
seed The random seed to use for this simulator.

Returns
The state vector resulting from applying the given unitary operations to the desired initial state. Specifically, a numpy array containing the amplitudes in np.kron order, where the order of arguments to kron is determined by the qubit order argument (which defaults to just sorting the qubits that are present into an ascending order).

Raises
ValueError If the program doesn't have a well defined final state because it has non-unitary gates.

findall_operations

View source

Find the locations of all operations that satisfy a given condition.

This returns an iterator of (index, operation) tuples where each operation satisfies op_cond(operation) is truthy. The indices are in order of the moments and then order of the ops within that moment.

Args
predicate A method that takes an Operation and returns a Truthy value indicating the operation meets the find condition.

Returns
An iterator (index, operation)'s that satisfy the op_condition.

findall_operations_between

View source

Finds operations between the two given frontiers.

If a qubit is in start_frontier but not end_frontier, its end index defaults to the end of the circuit. If a qubit is in end_frontier but not start_frontier, its start index defaults to the start of the circuit. Operations on qubits not mentioned in either frontier are not included in the results.

Args
start_frontier Just before where to start searching for operations, for each qubit of interest. Start frontier indices are inclusive.
end_frontier Just before where to stop searching for operations, for each qubit of interest. End frontier indices are exclusive.
omit_crossing_operations Determines whether or not operations that cross from a location between the two frontiers to a location outside the two frontiers are included or excluded. (Operations completely inside are always included, and operations completely outside are always excluded.)

Returns
A list of tuples. Each tuple describes an operation found between the two frontiers. The first item of each tuple is the index of the moment containing the operation, and the second item is the operation itself. The list is sorted so that the moment index increases monotonically.

findall_operations_until_blocked

View source

Finds all operations until a blocking operation is hit.

An operation is considered blocking if both of the following hold:

  • It is in the 'light cone' of start_frontier.
  • is_blocker returns a truthy value, or it acts on a blocked qubit

Every qubit acted on by a blocking operation is thereafter itself blocked.

The notion of reachability here differs from that in reachable_frontier_from in two respects:

  • An operation is not considered blocking only because it is in a moment before the start_frontier of one of the qubits on which it acts.
  • Operations that act on qubits not in start_frontier are not automatically blocking.

For every (moment_index, operation) returned:

  • moment_index >= min((start_frontier[q] for q in operation.qubits if q in start_frontier), default=0)
  • set(operation.qubits).intersection(start_frontier)

Below are some examples, where on the left the opening parentheses show start_frontier and on the right are the operations included (with their moment indices) in the output. F and T indicate that is_blocker return False or True, respectively, when applied to the gates; M indicates that it doesn't matter.

    ─(─F───F───────    ┄(─F───F─)┄┄┄┄┄
       │   │              │   │
    ─(─F───F───T─── => ┄(─F───F─)┄┄┄┄┄
               │                  ┊
    ───────────T───    ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄


    ───M─────(─F───    ┄┄┄┄┄┄┄┄┄(─F─)┄┄
       │       │          ┊       │
    ───M───M─(─F───    ┄┄┄┄┄┄┄┄┄(─F─)┄┄
           │        =>        ┊
    ───────M───M───    ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
               │                  ┊
    ───────────M───    ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄


    ───M─(─────M───     ┄┄┄┄┄()┄┄┄┄┄┄┄┄
       │       │           ┊       ┊
    ───M─(─T───M───     ┄┄┄┄┄()┄┄┄┄┄┄┄┄
           │        =>         ┊
    ───────T───M───     ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
               │                   ┊
    ───────────M───     ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄


    ─(─F───F───    ┄(─F───F─)┄
       │   │    =>    │   │
    ───F─(─F───    ┄(─F───F─)┄


    ─(─F───────────    ┄(─F─)┄┄┄┄┄┄┄┄┄
       │                  │
    ───F───F───────    ┄(─F─)┄┄┄┄┄┄┄┄┄
           │        =>        ┊
    ───────F───F───    ┄┄┄┄┄┄┄┄┄(─F─)┄
               │                  │
    ─(─────────F───    ┄┄┄┄┄┄┄┄┄(─F─)┄

Args
start_frontier A starting set of reachable locations.
is_blocker A predicate that determines if operations block reachability. Any location covered by an operation that causes is_blocker to return True is considered to be an unreachable location.

Returns
A list of tuples. Each tuple describes an operation found between the start frontier and a blocking operation. The first item of each tuple is the index of the moment containing the operation, and the second item is the operation itself.

findall_operations_with_gate_type

View source

Find the locations of all gate operations of a given type.

Args
gate_type The type of gate to find, e.g. XPowGate or MeasurementGate.

Returns
An iterator (index, operation, gate)'s for operations with the given gate type.

freeze

View source

Creates a FrozenCircuit from this circuit.

If 'self' is a FrozenCircuit, the original object is returned.

from_moments

View source

Create a circuit from moment op trees.

Args
*moments Op tree for each moment. If an op tree is a moment, it will be included directly in the new circuit. If an op tree is a circuit, it will be frozen, wrapped in a CircuitOperation, and included in its own moment in the new circuit. Otherwise, the op tree will be passed to cirq.Moment to create a new moment which is then included in the new circuit. Note that in the latter case we have the normal restriction that operations in a moment must be applied to disjoint sets of qubits.

get_independent_qubit_sets

View source

Divide circuit's qubits into independent qubit sets.

Independent qubit sets are the qubit sets such that there are no entangling gates between qubits belonging to different sets. If this is not possible, a sequence with a single factor (the whole set of circuit's qubits) is returned.

q0, q1, q2 = cirq.LineQubit.range(3)
circuit = cirq.Circuit()
circuit.append(cirq.Moment(cirq.H(q2)))
circuit.append(cirq.Moment(cirq.CZ(q0,q1)))
circuit.append(cirq.H(q0))
print(circuit)
0: ───────@───H───

1: ───────@───────
<BLANKLINE>
2: ───H───────────
[sorted(qs) for qs in circuit.get_independent_qubit_sets()]
[[cirq.LineQubit(0), cirq.LineQubit(1)], [cirq.LineQubit(2)]]

Returns
The list of independent qubit sets.

has_measurements

View source

Returns whether or not this circuit has measurements.

Returns: True if cirq.is_measurement(self) is True otherwise False.

map_operations

View source

Applies the given function to all operations in this circuit.

Args
func a mapping function from operations to OP_TREEs.

Returns
A circuit with the same basic structure as the original, but with each operation op replaced with func(op).

next_moment_operating_on

View source

Finds the index of the next moment that touches the given qubits.

Args
qubits We're looking for operations affecting any of these qubits.
start_moment_index The starting point of the search.
max_distance The number of moments (starting from the start index and moving forward) to check. Defaults to no limit.

Returns
None if there is no matching moment, otherwise the index of the earliest matching moment.

Raises
ValueError negative max_distance.

next_moments_operating_on

View source

Finds the index of the next moment that touches each qubit.

Args
qubits The qubits to find the next moments acting on.
start_moment_index The starting point of the search.

Returns
The index of the next moment that touches each qubit. If there is no such moment, the next moment is specified as the number of moments in the circuit. Equivalently, can be characterized as one plus the index of the last moment after start_moment_index (inclusive) that does not act on a given qubit.

operation_at

View source

Finds the operation on a qubit within a moment, if any.

Args
qubit The qubit to check for an operation on.
moment_index The index of the moment to check for an operation within. Allowed to be beyond the end of the circuit.

Returns
None if there is no operation on the qubit at the given moment, or else the operation.

prev_moment_operating_on

View source

Finds the index of the previous moment that touches the given qubits.

Args
qubits We're looking for operations affecting any of these qubits.
end_moment_index The moment index just after the starting point of the reverse search. Defaults to the length of the list of moments.
max_distance The number of moments (starting just before from the end index and moving backward) to check. Defaults to no limit.

Returns
None if there is no matching moment, otherwise the index of the latest matching moment.

Raises
ValueError negative max_distance.

qid_shape

View source

Get the qubit shapes of all qubits in this circuit.

Returns: A tuple containing the dimensions (shape) of all qudits found in this circuit according to qubit_order.

reachable_frontier_from

View source

Determines how far can be reached into a circuit under certain rules.

The location L = (qubit, moment_index) is reachable if and only if the following all hold true:

  • There is not a blocking operation covering L.
  • At least one of the following holds:
    • qubit is in start frontier and moment_index = max(start_frontier[qubit], 0).
    • There is no operation at L and prev(L) = (qubit, moment_index-1) is reachable.
    • There is an (non-blocking) operation P covering L such that (q', moment_index - 1) is reachable for every q' on which P acts.

An operation in moment moment_index is blocking if at least one of the following hold:

  • is_blocker returns a truthy value.
  • The operation acts on a qubit not in start_frontier.
  • The operation acts on a qubit q such that start_frontier[q] > moment_index.

In other words, the reachable region extends forward through time along each qubit in start_frontier until it hits a blocking operation. Any location involving a qubit not in start_frontier is unreachable.

For each qubit q in start_frontier, the reachable locations will correspond to a contiguous range starting at start_frontier[q] and ending just before some index end_q. The result of this method is a dictionary, and that dictionary maps each qubit q to its end_q.

Examples:

If start_frontier is

{
    cirq.LineQubit(0): 6,
    cirq.LineQubit(1): 2,
    cirq.LineQubit(2): 2
}

then the reachable wire locations in the following circuit are highlighted with '█' characters:


        0   1   2   3   4   5   6   7   8   9   10  11  12  13
    0: ───H───@─────────────────█████████████████████─@───H───
              │                                       │
    1: ───────@─██H███@██████████████████████─@───H───@───────
                      │                       │
    2: ─────────██████@███H██─@───────@───H───@───────────────
                              │       │
    3: ───────────────────────@───H───@───────────────────────

And the computed end_frontier is

{
    cirq.LineQubit(0): 11,
    cirq.LineQubit(1): 9,
    cirq.LineQubit(2): 6,
}

Note that the frontier indices (shown above the circuit) are best thought of (and shown) as happening between moment indices.

If we specify a blocker as follows:

is_blocker=lambda: op == cirq.CZ(cirq.LineQubit(1),
                                 cirq.LineQubit(2))

and use this start_frontier:

{
    cirq.LineQubit(0): 0,
    cirq.LineQubit(1): 0,
    cirq.LineQubit(2): 0,
    cirq.LineQubit(3): 0,
}

Then this is the reachable area:


        0   1   2   3   4   5   6   7   8   9   10  11  12  13
    0: ─██H███@██████████████████████████████████████─@───H───
              │                                       │
    1: ─██████@███H██─@───────────────────────@───H───@───────
                      │                       │
    2: ─█████████████─@───H───@───────@───H───@───────────────
                              │       │
    3: ─█████████████████████─@───H───@───────────────────────

and the computed end_frontier is:

{
    cirq.LineQubit(0): 11,
    cirq.LineQubit(1): 3,
    cirq.LineQubit(2): 3,
    cirq.LineQubit(3): 5,
}

Args
start_frontier A starting set of reachable locations.
is_blocker A predicate that determines if operations block reachability. Any location covered by an operation that causes is_blocker to return True is considered to be an unreachable location.

Returns
An end_frontier dictionary, containing an end index for each qubit q mapped to a start index by the given start_frontier dictionary.

To determine if a location (q, i) was reachable, you can use this expression:

q in start_frontier and start_frontier[q] <= i < end_frontier[q]

where i is the moment index, q is the qubit, and end_frontier is the result of this method.

save_qasm

View source

Save a QASM file equivalent to the circuit.

Args
file_path The location of the file where the qasm will be written.
header A multi-line string that is placed in a comment at the top of the QASM. Defaults to a cirq version specifier.
precision Number of digits to use when representing numbers.
qubit_order Determines how qubits are ordered in the QASM register.

to_op

View source

Creates a CircuitOperation wrapping this circuit.

to_qasm

View source

Returns QASM equivalent to the circuit.

Args
header A multi-line string that is placed in a comment at the top of the QASM. Defaults to a cirq version specifier.
precision Number of digits to use when representing numbers.
qubit_order Determines how qubits are ordered in the QASM register.

to_text_diagram

View source

Returns text containing a diagram describing the circuit.

Args
use_unicode_characters Determines if unicode characters are allowed (as opposed to ascii-only diagrams).
transpose Arranges qubit wires vertically instead of horizontally.
include_tags Whether tags on TaggedOperations should be printed
precision Number of digits to display in text diagram
qubit_order Determines how qubits are ordered in the diagram.

Returns
The text diagram.

to_text_diagram_drawer

View source

Returns a TextDiagramDrawer with the circuit drawn into it.

Args
use_unicode_characters Determines if unicode characters are allowed (as opposed to ascii-only diagrams).
qubit_namer Names qubits in diagram. Defaults to using _circuit_diagraminfo or str.
transpose Arranges qubit wires vertically instead of horizontally.
include_tags Whether to include tags in the operation.
draw_moment_groups Whether to draw moment symbol or not
precision Number of digits to use when representing numbers.
qubit_order Determines how qubits are ordered in the diagram.
get_circuit_diagram_info Gets circuit diagram info. Defaults to protocol with fallback.

Returns
The TextDiagramDrawer instance.

unfreeze

View source

Creates a Circuit from this circuit.

Args
copy If True and 'self' is a Circuit, returns a copy that circuit.

unitary

View source

Converts the circuit into a unitary matrix, if possible.

Returns the same result as cirq.unitary, but provides more options.

Args
qubit_order Determines how qubits are ordered when passing matrices into np.kron.
qubits_that_should_be_present Qubits that may or may not appear in operations within the circuit, but that should be included regardless when generating the matrix.
ignore_terminal_measurements When set, measurements at the end of the circuit are ignored instead of causing the method to fail.
dtype The numpy dtype for the returned unitary. Defaults to np.complex128. Specifying np.complex64 will run faster at the cost of precision. dtype must be a complex np.dtype, unless all operations in the circuit have unitary matrices with exclusively real coefficients (e.g. an H + TOFFOLI circuit).

Returns
A (possibly gigantic) 2d numpy array corresponding to a matrix equivalent to the circuit's effect on a quantum state.

Raises
ValueError The circuit contains measurement gates that are not ignored.
TypeError The circuit contains gates that don't have a known unitary matrix, e.g. gates parameterized by a Symbol.

with_tags

View source

Creates a new tagged FrozenCircuit with self.tags and new_tags combined.

zip

View source

Combines operations from circuits in a moment-by-moment fashion.

Moment k of the resulting circuit will have all operations from moment k of each of the given circuits.

When the given circuits have different lengths, the shorter circuits are implicitly padded with empty moments. This differs from the behavior of python's built-in zip function, which would instead truncate the longer circuits.

The zipped circuits can't have overlapping operations occurring at the same moment index.

Args
*circuits The circuits to merge together.
align The alignment for the zip, see cirq.Alignment.

Returns
The merged circuit.

Raises
ValueError If the zipped circuits have overlapping operations occurring at the same moment index.

Examples:

import cirq
a, b, c, d = cirq.LineQubit.range(4)
circuit1 = cirq.Circuit(cirq.H(a), cirq.CNOT(a, b))
circuit2 = cirq.Circuit(cirq.X(c), cirq.Y(c), cirq.Z(c))
circuit3 = cirq.Circuit(cirq.Moment(), cirq.Moment(cirq.S(d)))
print(circuit1.zip(circuit2))
0: ───H───@───────

1: ───────X───────
<BLANKLINE>
2: ───X───Y───Z───
print(circuit1.zip(circuit2, circuit3))
0: ───H───@───────

1: ───────X───────
<BLANKLINE>
2: ───X───Y───Z───
<BLANKLINE>
3: ───────S───────
print(cirq.Circuit.zip(circuit3, circuit2, circuit1))
0: ───H───@───────

1: ───────X───────
<BLANKLINE>
2: ───X───Y───Z───
<BLANKLINE>
3: ───────S───────

__add__

View source

__bool__

View source

__eq__

View source

Return self==value.

__getitem__

View source

__iter__

View source

__len__

View source

__mul__

View source

__ne__

View source

Return self!=value.

__pow__

View source

__radd__

View source

__rmul__

View source