qsimcirq.QSimCircuit

View source on GitHub

A mutable list of groups of operations to apply to some qubits.

qsimcirq.QSimCircuit(
    cirq_circuit: cirq.Circuit,
    device: cirq.devices = cirq.devices.UNCONSTRAINED_DEVICE,
    allow_decomposition: bool = False
)

Methods returning information about the circuit (inherited from AbstractCircuit):

• next_moment_operating_on
• prev_moment_operating_on
• next_moments_operating_on
• operation_at
• all_qubits
• all_operations
• findall_operations
• findall_operations_between
• findall_operations_until_blocked
• findall_operations_with_gate_type
• reachable_frontier_from
• has_measurements
• are_all_matches_terminal
• are_all_measurements_terminal
• unitary
• final_state_vector
• to_text_diagram
• to_text_diagram_drawer
• qid_shape
• all_measurement_keys
• to_quil
• to_qasm
• save_qasm
• get_independent_qubit_sets

Methods for mutation:

• insert
• append
• insert_into_range
• clear_operations_touching
• batch_insert
• batch_remove
• batch_insert_into
• insert_at_frontier

Circuits can also be iterated over,

    for moment in circuit:
        ...

and sliced,

• circuit[1:3] is a new Circuit made up of two moments, the first being circuit[1] and the second being circuit[2];
• circuit[:, qubit] is a new Circuit with the same moments, but with only those operations which act on the given Qubit;
• circuit[:, qubits], where 'qubits' is list of Qubits, is a new Circuit with the same moments, but only with those operations which touch any of the given qubits;
• circuit[1:3, qubit] is equivalent to circuit[1:3][:, qubit];
• circuit[1:3, qubits] is equivalent to circuit[1:3][:, qubits];

and concatenated,

• circuit1 + circuit2 is a new Circuit made up of the moments in circuit1 followed by the moments in circuit2;

and multiplied by an integer,

• circuit * k is a new Circuit made up of the moments in circuit repeated k times.

and mutated,

• circuit[1:7] = [Moment(...)]

and factorized,

• circuit.factorize() returns a sequence of Circuits which represent independent 'factors' of the original Circuit.

Methods

all_measurement_keys

all_measurement_keys() -> AbstractSet[str]

all_operations

all_operations() -> Iterator[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

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

Returns the qubits acted upon by Operations in this circuit.

append

append(
    moment_or_operation_tree: Union['cirq.Moment', 'cirq.OP_TREE'],
    strategy: "cirq.InsertStrategy" = InsertStrategy.EARLIEST
)

Appends operations onto the end of the circuit.

Moments within the operation tree are appended intact.

are_all_matches_terminal

are_all_matches_terminal(
    predicate: Callable[['cirq.Operation'], bool]
) -> 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

are_all_measurements_terminal() -> bool

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

are_any_matches_terminal

are_any_matches_terminal(
    predicate: Callable[['cirq.Operation'], bool]
) -> 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

are_any_measurements_terminal() -> bool

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

batch_insert

batch_insert(
    insertions: Iterable[Tuple[int, 'cirq.OP_TREE']]
) -> None

Applies a batched insert operation to the circuit.

Transparently handles the fact that earlier insertions may shift the index that later insertions should occur at. For example, if you insert an operation at index 2 and at index 4, but the insert at index 2 causes a new moment to be created, then the insert at "4" will actually occur at index 5 to account for the shift from the new moment.

All insertions are done with the strategy 'EARLIEST'.

When multiple inserts occur at the same index, the gates from the later inserts end up before the gates from the earlier inserts (exactly as if you'd called list.insert several times with the same index: the later inserts shift the earliest inserts forward).

batch_insert_into

batch_insert_into(
    insert_intos: Iterable[Tuple[int, 'cirq.OP_TREE']]
) -> None

Inserts operations into empty spaces in existing moments.

If any of the insertions fails (due to colliding with an existing operation), this method fails without making any changes to the circuit.

ValueError:

One of the insertions collided with an existing operation.

IndexError:

Inserted into a moment index that doesn't exist.

batch_remove

batch_remove(
    removals: Iterable[Tuple[int, 'cirq.Operation']]
) -> None

Removes several operations from a circuit.

ValueError:

One of the operations to delete wasn't present to start with.

IndexError:

Deleted from a moment that doesn't exist.

batch_replace

batch_replace(
    replacements: Iterable[Tuple[int, 'cirq.Operation', 'cirq.Operation']]
) -> None

Replaces several operations in a circuit with new operations.

ValueError:

One of the operations to replace wasn't present to start with.

IndexError:

Replaced in a moment that doesn't exist.

clear_operations_touching

clear_operations_touching(
    qubits: Iterable['cirq.Qid'],
    moment_indices: Iterable[int]
)

Clears operations that are touching given qubits at given moments.

copy

copy() -> "Circuit"

factorize

factorize() -> Iterable[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

final_state_vector(
    initial_state: "cirq.STATE_VECTOR_LIKE" = 0,
    qubit_order: "cirq.QubitOrderOrList" = 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

findall_operations(
    predicate: Callable[['cirq.Operation'], bool]
) -> 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

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

findall_operations_until_blocked(
    start_frontier: Dict['cirq.Qid', int],
    is_blocker: Callable[['cirq.Operation'], bool] = (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

findall_operations_with_gate_type(
    gate_type: Type[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

freeze() -> "cirq.FrozenCircuit"

Creates a FrozenCircuit from this circuit.

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

get_independent_qubit_sets

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

has_measurements()

insert

insert(
    index: int,
    moment_or_operation_tree: Union['cirq.Operation', 'cirq.OP_TREE'],
    strategy: "cirq.InsertStrategy" = InsertStrategy.EARLIEST
) -> int

Inserts operations into the circuit.

Operations are inserted into the moment specified by the index and 'InsertStrategy'. Moments within the operation tree are inserted intact.

insert_at_frontier

insert_at_frontier(
    operations: "cirq.OP_TREE",
    start: int,
    frontier: Dict['cirq.Qid', int] = None
) -> Dict['cirq.Qid', int]

Inserts operations inline at frontier.

insert_into_range

insert_into_range(
    operations: "cirq.OP_TREE",
    start: int,
    end: int
) -> int

Writes operations inline into an area of the circuit.

map_operations

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

Applies the given function to all operations in this circuit.

next_moment_operating_on

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

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

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

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

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

reachable_frontier_from

reachable_frontier_from(
    start_frontier: Dict['cirq.Qid', int],
    *,
    is_blocker: Callable[['cirq.Operation'], bool] = (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

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

Save a QASM file equivalent to the circuit.

tetris_concat

tetris_concat(
    *circuits,
    align: Union['cirq.Alignment', str] = Alignment.LEFT
) -> "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 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_qasm

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

Returns QASM equivalent to the circuit.

to_quil

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

to_text_diagram

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

Returns text containing a diagram describing the circuit.

to_text_diagram_drawer

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" = ops.QubitOrder.DEFAULT,
    get_circuit_diagram_info: Optional[Callable[['cirq.Operation', 'cirq.CircuitDiagramInfoArgs'],
        'cirq.CircuitDiagramInfo']] = None
) -> TextDiagramDrawer

Returns a TextDiagramDrawer with the circuit drawn into it.

transform_qubits

transform_qubits(
    qubit_map: Union[Dict['cirq.Qid', 'cirq.Qid'], Callable[['cirq.Qid'], 'cirq.Qid']],
    *,
    new_device: "cirq.Device" = None
) -> "cirq.Circuit"

Returns the same circuit, but with different qubits.

Note that this method does essentially the same thing as cirq.Circuit.with_device. It is included regardless because there are also transform_qubits methods on cirq.Operation and cirq.Moment.

translate_cirq_to_qsim

View source

translate_cirq_to_qsim(
    qubit_order: cirq.ops.QubitOrderOrList = cirq.ops.QubitOrder.DEFAULT
) -> qsimcirq.qsim.Circuit

Translates this Cirq circuit to the qsim representation. :qubit_order: Ordering of qubits :return: a C++ qsim Circuit object

translate_cirq_to_qtrajectory

View source

translate_cirq_to_qtrajectory(
    qubit_order: cirq.ops.QubitOrderOrList = cirq.ops.QubitOrder.DEFAULT
) -> qsimcirq.qsim.NoisyCircuit

Translates this noisy Cirq circuit to the qsim representation. :qubit_order: Ordering of qubits :return: a C++ qsim NoisyCircuit object

unfreeze

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

Creates a Circuit from this circuit.

unitary

unitary(
    qubit_order: "cirq.QubitOrderOrList" = 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

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

Maps the current circuit onto a new device, and validates.

with_noise

with_noise(
    noise: "cirq.NOISE_MODEL_LIKE"
) -> "cirq.Circuit"

Make a noisy version of the circuit.

zip

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

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__

__add__(
    other
)

__bool__

__bool__()

__eq__

View source

__eq__(
    other
)

Return self==value.

__getitem__

__getitem__(
    key
)

__iter__

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

__len__

__len__() -> int

__mul__

__mul__(
    repetitions: INT_TYPE
)

__ne__

__ne__(
    other
) -> bool

Return self!=value.

__pow__

__pow__(
    exponent: int
) -> "Circuit"

A circuit raised to a power, only valid for exponent -1, the inverse.

This will fail if anything other than -1 is passed to the Circuit by returning NotImplemented. Otherwise this will return the inverse circuit, which is the circuit with its moment order reversed and for every moment all the moment's operations are replaced by its inverse. If any of the operations do not support inverse, NotImplemented will be returned.

__radd__

__radd__(
    other
)

__rmul__

__rmul__(
    repetitions: INT_TYPE
)