cirq.circuits.FrozenCircuit

See Stable See Nightly

View source on GitHub

An immutable version of the Circuit data structure.

Inherits From: AbstractCircuit, SerializableByKey, SupportsJSON

cirq.circuits.FrozenCircuit(
    strategy: "cirq.InsertStrategy" = cirq.circuits.InsertStrategy.EARLIEST,
    *contents,
    device: "cirq.Device" = cirq.devices.UNCONSTRAINED_DEVICE
) -> None

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.

Methods

all_measurement_keys

View source

all_measurement_keys() -> AbstractSet[str]

all_operations

View source

all_operations() -> Iterator[cirq.ops.Operation]

Iterates over the operations applied by this circuit.

Operations from earlier moments will be iterated over first. Operations within a moment are iterated in the order they were given to the moment's constructor.

all_qubits

View source

all_qubits() -> FrozenSet['cirq.Qid']

Returns the qubits acted upon by Operations in this circuit.

are_all_matches_terminal

View source

are_all_matches_terminal(
    predicate: cirq.optimizers.stratify.Classifier
) -> bool

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.

are_all_measurements_terminal

View source

are_all_measurements_terminal() -> bool

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

are_any_matches_terminal

View source

are_any_matches_terminal(
    predicate: cirq.optimizers.stratify.Classifier
) -> bool

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.

are_any_measurements_terminal

View source

are_any_measurements_terminal() -> bool

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

diagram_name

View source

diagram_name()

Name used to represent this in circuit diagrams.

factorize

View source

factorize() -> Iterable[cirq.circuits.circuit.CIRCUIT_TYPE]

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───────────

final_state_vector

View source

final_state_vector(
    initial_state: "cirq.STATE_VECTOR_LIKE" = 0,
    qubit_order: "cirq.QubitOrderOrList" = cirq.ops.QubitOrder.DEFAULT,
    qubits_that_should_be_present: Iterable['cirq.Qid'] = (),
    ignore_terminal_measurements: bool = True,
    dtype: Type[np.number] = np.complex128
) -> np.ndarray

Left-multiplies a state vector by the circuit's unitary effect.

A circuit's "unitary effect" is the unitary matrix produced by multiplying together all of its gates' unitary matrices. A circuit with non-unitary gates (such as measurement or parameterized gates) does not have a well-defined unitary effect, and the method will fail if such operations are present.

For convenience, terminal measurements are automatically ignored instead of causing a failure. Set the ignore_terminal_measurements argument to False to disable this behavior.

This method is equivalent to left-multiplying the input state by cirq.unitary(circuit) but it's computed in a more efficient way.

findall_operations

View source

findall_operations(
    predicate: cirq.optimizers.stratify.Classifier
) -> Iterable[Tuple[int, 'cirq.Operation']]

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.

findall_operations_between

View source

findall_operations_between(
    start_frontier: Dict['cirq.Qid', int],
    end_frontier: Dict['cirq.Qid', int],
    omit_crossing_operations: bool = False
) -> List[Tuple[int, 'cirq.Operation']]

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.

findall_operations_until_blocked

View source

findall_operations_until_blocked(
    start_frontier: Dict['cirq.Qid', int],
    is_blocker: cirq.optimizers.stratify.Classifier = (lambda op: False)
) -> List[Tuple[int, ops.Operation]]

Finds all operations until a blocking operation is hit.

An operation is considered blocking if

a) It is in the 'light cone' of start_frontier.

AND

(

1) is_blocker returns a truthy value.

OR

2) 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:

1) 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. 2) Operations that act on qubits not in start_frontier are not automatically blocking.

For every (moment_index, operation) returned:

1) moment_index >= min((start_frontier[q] for q in operation.qubits if q in start_frontier), default=0) 2) 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─)┄

findall_operations_with_gate_type

View source

findall_operations_with_gate_type(
    gate_type: Type[cirq.circuits.circuit.T_DESIRED_GATE_TYPE]
) -> Iterable[Tuple[int, ops.GateOperation, T_DESIRED_GATE_TYPE]]

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

freeze

View source

freeze() -> "cirq.FrozenCircuit"

Creates a FrozenCircuit from this circuit.

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

get_independent_qubit_sets

View source

get_independent_qubit_sets() -> List[Set['cirq.Qid']]

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)]]

has_measurements

View source

has_measurements() -> bool

map_operations

View source

map_operations(
    func: Callable[['cirq.Operation'], 'cirq.OP_TREE']
) -> cirq.circuits.circuit.CIRCUIT_TYPE

Applies the given function to all operations in this circuit.

next_moment_operating_on

View source

next_moment_operating_on(
    qubits: Iterable['cirq.Qid'],
    start_moment_index: int = 0,
    max_distance: int = None
) -> Optional[int]

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

next_moments_operating_on

View source

next_moments_operating_on(
    qubits: Iterable['cirq.Qid'],
    start_moment_index: int = 0
) -> Dict['cirq.Qid', int]

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

operation_at

View source

operation_at(
    qubit: "cirq.Qid",
    moment_index: int
) -> Optional['cirq.Operation']

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

prev_moment_operating_on

View source

prev_moment_operating_on(
    qubits: Sequence['cirq.Qid'],
    end_moment_index: Optional[int] = None,
    max_distance: Optional[int] = None
) -> Optional[int]

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

qid_shape

View source

qid_shape(
    qubit_order: "cirq.QubitOrderOrList" = cirq.ops.QubitOrder.DEFAULT
) -> Tuple[int, ...]

reachable_frontier_from

View source

reachable_frontier_from(
    start_frontier: Dict['cirq.Qid', int],
    *,
    is_blocker: cirq.optimizers.stratify.Classifier = (lambda op: False)
) -> Dict['cirq.Qid', int]

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

The location L = (qubit, moment_index) is reachable if and only if:

a) There is not a blocking operation covering L.

AND

[
    b1) qubit is in start frontier and moment_index =
        max(start_frontier[qubit], 0).

    OR

    b2) There is no operation at L and prev(L) = (qubit,
        moment_index-1) is reachable.

    OR

    b3) 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

a) `is_blocker` returns a truthy value.

OR

b) The operation acts on a qubit not in start_frontier.

OR

c) 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,
}

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

save_qasm

View source

save_qasm(
    file_path: Union[str, bytes, int],
    header: Optional[str] = None,
    precision: int = 10,
    qubit_order: "cirq.QubitOrderOrList" = cirq.ops.QubitOrder.DEFAULT
) -> None

Save a QASM file equivalent to the circuit.

tetris_concat

View source

tetris_concat(
    *circuits,
    align: Union['cirq.Alignment', str] = cirq.circuits.Alignment.LEFT
) -> "cirq.FrozenCircuit"

Concatenates circuits while overlapping them if possible.

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, acording 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.tetris_concat
    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
        

to_op

View source

to_op()

Creates a CircuitOperation wrapping this circuit.

to_qasm

View source

to_qasm(
    header: Optional[str] = None,
    precision: int = 10,
    qubit_order: "cirq.QubitOrderOrList" = cirq.ops.QubitOrder.DEFAULT
) -> str

Returns QASM equivalent to the circuit.

to_quil

View source

to_quil(
    qubit_order: "cirq.QubitOrderOrList" = cirq.ops.QubitOrder.DEFAULT
) -> str

to_text_diagram

View source

to_text_diagram(
    *,
    use_unicode_characters: bool = True,
    transpose: bool = False,
    include_tags: bool = True,
    precision: Optional[int] = 3,
    qubit_order: "cirq.QubitOrderOrList" = cirq.ops.QubitOrder.DEFAULT
) -> str

Returns text containing a diagram describing the circuit.

to_text_diagram_drawer

View source

to_text_diagram_drawer(
    *,
    use_unicode_characters: bool = True,
    qubit_namer: Optional[Callable[['cirq.Qid'], str]] = None,
    transpose: bool = False,
    include_tags: bool = True,
    draw_moment_groups: bool = True,
    precision: Optional[int] = 3,
    qubit_order: "cirq.QubitOrderOrList" = cirq.ops.QubitOrder.DEFAULT,
    get_circuit_diagram_info: Optional[Callable[['cirq.Operation', 'cirq.CircuitDiagramInfoArgs'],
        'cirq.CircuitDiagramInfo']] = None
) -> cirq.circuits.TextDiagramDrawer

Returns a TextDiagramDrawer with the circuit drawn into it.

unfreeze

View source

unfreeze(
    copy: bool = True
) -> "cirq.Circuit"

Creates a Circuit from this circuit.

unitary

View source

unitary(
    qubit_order: "cirq.QubitOrderOrList" = cirq.ops.QubitOrder.DEFAULT,
    qubits_that_should_be_present: Iterable['cirq.Qid'] = (),
    ignore_terminal_measurements: bool = True,
    dtype: Type[np.number] = np.complex128
) -> np.ndarray

Converts the circuit into a unitary matrix, if possible.

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

with_device

View source

with_device(
    new_device: "cirq.Device",
    qubit_mapping: Callable[['cirq.Qid'], 'cirq.Qid'] = (lambda e: e)
) -> "FrozenCircuit"

zip

View source

zip(
    *circuits,
    align: Union['cirq.Alignment', str] = cirq.circuits.Alignment.LEFT
) -> "cirq.FrozenCircuit"

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.

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))

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

__add__

View source

__add__(
    other
) -> "FrozenCircuit"

__bool__

View source

__bool__()

__eq__

View source

__eq__(
    other
)

Return self==value.

__getitem__

View source

__getitem__(
    key
)

__iter__

View source

__iter__() -> Iterator['cirq.Moment']

__len__

View source

__len__() -> int

__mul__

View source

__mul__(
    other
) -> "FrozenCircuit"

__ne__

View source

__ne__(
    other
) -> bool

Return self!=value.

__pow__

View source

__pow__(
    other
) -> "FrozenCircuit"

__radd__

View source

__radd__(
    other
) -> "FrozenCircuit"

__rmul__

View source

__rmul__(
    other
) -> "FrozenCircuit"