cirq.circuits.FrozenCircuit

An immutable version of the Circuit data structure.

Inherits From: AbstractCircuit

View aliases

Main aliases

cirq.FrozenCircuit, cirq.circuits.frozen_circuit.FrozenCircuit

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.

Args
`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.
`device`	Hardware that the circuit should be able to run on.

Attributes
`device`
`moments`

Attributes

device

moments

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.

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

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.

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

are_any_measurements_terminal() -> bool

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

`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.

Args
`initial_state`	The input state for the circuit. This can be a list of qudit values, a big endian int encoding the qudit values, a vector of amplitudes, or a tensor of amplitudes. When this is an int, it refers to a computational basis state (e.g. 5 means initialize to `\|5⟩ = \|...000101⟩`). If this is a vector of amplitudes (a flat numpy array of the correct length for the system) or a tensor of amplitudes (a numpy array whose shape equals this circuit's `qid_shape`), it directly specifies the initial state's amplitudes. The vector type must be convertible to the given `dtype` argument.
`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) numpy array storing the superposition that came out of the circuit for the given input 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.

`final_wavefunction`

View source

final_wavefunction(
    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

THIS FUNCTION IS DEPRECATED.

IT WILL BE REMOVED IN cirq v0.10.0.

Use final_state_vector instead.

Deprecated. Please use final_state_vector.

`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.

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

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.

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

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

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

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.

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

freeze() -> "cirq.FrozenCircuit"

Creates a FrozenCircuit from this circuit.

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

`has_measurements`

View source

has_measurements() -> bool

`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.

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

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.

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

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

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

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.

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

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

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

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.

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_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.

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.

`serialization_key`

View source

serialization_key()

`tetris_concat`

View source

tetris_concat(
    *circuits,
    stop_at_first_alignment: bool = False
) -> "cirq.Circuit"

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 any of:

a) Just before their operations would collide.
b) stop_at_first_alignment==True and their ends (or starts) align
    for the first time.
c) Their ends (or starts) align for the last time.

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

Args
`circuits`	The circuits to concatenate.
`stop_at_first_alignment`	Defaults to false. When true, the 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). When false, the smaller circuit can be pushed deeper into the larger circuit, past the first time their starts or ends align, until the second time their starts or ends align.

Returns
The concatenated and overlapped circuit.

`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.

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_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.

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

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.

Args
`use_unicode_characters`	Determines if unicode characters are allowed (as opposed to ascii-only diagrams).
`qubit_namer`	Names qubits in diagram. Defaults to str.
`transpose`	Arranges qubit wires vertically instead of horizontally.
`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

unfreeze() -> "cirq.Circuit"

Creates a Circuit from this circuit.

If 'self' is a Circuit, this returns a copy of that 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.

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_device`

View source

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

`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"