cirq.CircuitOperation

An operation that encapsulates a circuit.

Inherits From: Operation

cirq.CircuitOperation(
    circuit: cirq.FrozenCircuit,
    repetitions: INT_TYPE = 1,
    qubit_map: Optional[Dict[cirq.Qid, cirq.Qid]] = None,
    measurement_key_map: Optional[Dict[str, str]] = None,
    param_resolver: Optional[study.ParamResolverOrSimilarType] = None,
    repetition_ids: Optional[Sequence[str]] = None,
    parent_path: Tuple[str, ...] = (),
    extern_keys: FrozenSet[cirq.MeasurementKey] = frozenset(),
    use_repetition_ids: Optional[bool] = None,
    repeat_until: Optional[cirq.Condition] = None
)

Used in the notebooks

Used in the tutorials

This class captures modifications to the contained circuit, such as tags and loops, to support more condensed serialization. Similar to GateOperation, this type is immutable.

circuit The FrozenCircuit wrapped by this operation.
repetitions How many times the circuit should be repeated. This can be integer, or a sympy expression. If sympy, the expression must resolve to an integer, or float within 0.001 of integer, at runtime.
qubit_map Remappings for qubits in the circuit.
measurement_key_map Remappings for measurement keys in the circuit. The keys and values should be unindexed (i.e. without repetition_ids). The values cannot contain the MEASUREMENT_KEY_SEPARATOR.
param_resolver Resolved values for parameters in the circuit.
repetition_ids List of identifiers for each repetition of the CircuitOperation. If populated, the length should be equal to the repetitions. If not populated and abs(repetitions) > 1, it is initialized to strings for numbers in range(repetitions).
parent_path A tuple of identifiers for any parent CircuitOperations containing this one.
extern_keys The set of measurement keys defined at extern scope. The values here are used by decomposition and simulation routines to cache which external measurement keys exist as possible binding targets for unbound ClassicallyControlledOperation keys. This field is not intended to be set or changed manually, and should be empty in circuits that aren't in the middle of decomposition.
use_repetition_ids When True, any measurement key in the subcircuit will have its path prepended with the repetition id for each repetition. When False, this will not happen and the measurement key will be repeated. The default is True, but it will be changed to False in the next release. Please pass an explicit argument use_repetition_ids=True to preserve the current behavior.
repeat_until A condition that will be tested after each iteration of the subcircuit. The subcircuit will repeat until condition returns True, but will always run at least once, and the measurement key need not be defined prior to the subcircuit (but must be defined in a measurement within the subcircuit). This field is incompatible with repetitions or repetition_ids.

TypeError if repetitions is not an integer or sympy expression, or if the provided circuit is not a FrozenCircuit.
ValueError if any of the following conditions is met.

  • Negative repetitions on non-invertible circuit
  • Number of repetition IDs does not match repetitions
  • Repetition IDs used with parameterized repetitions
  • Conflicting qubit dimensions in qubit_map
  • Measurement key map has invalid key names
  • repeat_until used with other repetition controls
  • Key(s) in repeat_until are not modified by circuit

circuit

classical_controls The classical controls gating this operation.
gate

measurement_key_map

param_resolver

parent_path

qubit_map

qubits Returns the qubits operated on by this object.
repeat_until

repetition_ids

repetitions

tags Returns a tuple of the operation's tags.
untagged Returns the underlying operation without any tags.
use_repetition_ids

Methods

base_operation

View source

base_operation() -> cirq.CircuitOperation

Returns a copy of this operation with only the wrapped circuit.

Key and qubit mappings, parameter values, and repetitions are not copied.

controlled_by

View source

controlled_by(
    *control_qubits,
    control_values: Optional[Union[cv.AbstractControlValues, Sequence[Union[int, Collection[int]]]]
        ] = None
) -> 'cirq.Operation'

Returns a controlled version of this operation. If no control_qubits are specified, returns self.

Args
*control_qubits Qubits to control the operation by. Required.
control_values For which control qubit values to apply the operation. A sequence of the same length as control_qubits where each entry is an integer (or set of integers) corresponding to the qubit value (or set of possible values) where that control is enabled. When all controls are enabled, the operation is applied. If unspecified, control values default to 1.

mapped_circuit

View source

mapped_circuit(
    deep: bool = False
) -> cirq.Circuit

Applies all maps to the contained circuit and returns the result.

Args
deep If true, this will also call mapped_circuit on any CircuitOperations this object contains.

Returns
The contained circuit with all other member variables (repetitions, qubit mapping, parameterization, etc.) applied to it. This behaves like cirq.decompose(self), but preserving moment structure.

mapped_op

View source

mapped_op(
    deep: bool = False
) -> cirq.CircuitOperation

As mapped_circuit, but wraps the result in a CircuitOperation.

repeat

View source

repeat(
    repetitions: Optional[IntParam] = None,
    repetition_ids: Optional[Sequence[str]] = None
) -> CircuitOperation

Returns a copy of this operation repeated 'repetitions' times. Each repetition instance will be identified by a single repetition_id.

Args
repetitions Number of times this operation should repeat. This is multiplied with any pre-existing repetitions. If unset, it defaults to the length of repetition_ids.
repetition_ids List of IDs, one for each repetition. If unset, defaults to default_repetition_ids(repetitions).

Returns
A copy of this operation repeated repetitions times with the appropriate repetition_ids. The output repetition_ids are the cartesian product of input repetition_ids with the base operation's repetition_ids. If the base operation has unset repetition_ids (indicates {-1, 0, 1} repetitions with no custom IDs), the input repetition_ids are directly used.

Raises
TypeError repetitions is not an integer value.
ValueError Unexpected length of repetition_ids.
ValueError Both repetitions and repetition_ids are None.

replace

View source

replace(
    **changes
) -> cirq.CircuitOperation

Returns a copy of this operation with the specified changes.

transform_qubits

View source

transform_qubits(
    qubit_map: Union[Dict['cirq.Qid', 'cirq.Qid'], Callable[['cirq.Qid'], 'cirq.Qid']]
) -> Self

Returns the same operation, but with different qubits.

This function will return a new operation with the same gate but with qubits mapped according to the argument.

For example, the following will translate LineQubits to GridQubits using a grid with 4 columns:

op = cirq.CZ(cirq.LineQubit(5), cirq.LineQubit(9))
op.transform_qubits(lambda q: cirq.GridQubit(q.x // 4, q.x % 4))
cirq.CZ(cirq.GridQubit(1, 1), cirq.GridQubit(2, 1))

This can also be used with a dictionary that has a mapping, such as the following which maps named qubits to line qubits:

a = cirq.NamedQubit('alice')
b = cirq.NamedQubit('bob')
d = {a: cirq.LineQubit(4), b: cirq.LineQubit(5)}
op = cirq.CNOT(a, b)
op.transform_qubits(d)
cirq.CNOT(cirq.LineQubit(4), cirq.LineQubit(5))

Args
qubit_map A function or a dict mapping each current qubit into a desired new qubit.

Returns
The receiving operation but with qubits transformed by the given function.

Raises
TypeError qubit_map was not a function or dict mapping qubits to qubits.

validate_args

View source

validate_args(
    qubits: Sequence['cirq.Qid']
)

Raises an exception if the qubits don't match this operation's qid shape.

Call this method from a subclass's with_qubits method.

Args
qubits The new qids for the operation.

Raises
ValueError The operation had qids that don't match it's qid shape.

with_classical_controls

View source

with_classical_controls(
    *conditions
) -> 'cirq.Operation'

Returns a classically controlled version of this operation.

An operation that is classically controlled is executed iff all conditions evaluate to True. Conditions can be either a measurement key or a user-specified cirq.Condition. A measurement key evaluates to True iff any qubit in the corresponding measurement operation evaluated to a non-zero value; cirq.Condition supports more complex, user-defined conditions.

If no conditions are specified, returns self.

The classical control will remove any tags on the existing operation, since tags are fragile, and we always opt to get rid of the tags when the underlying operation is changed.

Args
*conditions A list of measurement keys, strings that can be parsed into measurement keys, or sympy expressions where the free symbols are measurement key strings.

Returns
A ClassicallyControlledOperation wrapping the operation. If no conditions are specified, returns self.

with_key_path

View source

with_key_path(
    path: Tuple[str, ...]
)

Alias for cirq.with_key_path(self, path).

Args
path Tuple of strings representing an alternate path to assign to the measurement keys in this CircuitOperation.

Returns
A copy of this object with parent_path=path.

with_measurement_key_mapping

View source

with_measurement_key_mapping(
    key_map: Mapping[str, str]
) -> cirq.CircuitOperation

Returns a copy of this operation with an updated key mapping.

Args
key_map A mapping of old measurement keys to new measurement keys. This map will be composed with any existing key mapping. The keys and values of the map should be unindexed (i.e. without repetition_ids).

Returns
A copy of this operation with measurement keys updated as specified by key_map.

Raises
ValueError The new operation has a different number of measurement keys than this operation.

with_params

View source

with_params(
    param_values: cirq.ParamResolverOrSimilarType, recursive: bool = False
) -> cirq.CircuitOperation

Returns a copy of this operation with an updated ParamResolver.

Any existing parameter mappings will have their values updated given the provided mapping, and any new parameters will be added to the ParamResolver.

Note that any resulting parameter mappings with no corresponding parameter in the base circuit will be omitted. These parameters do not apply to the repetitions field if that is parameterized.

Args
param_values A map or ParamResolver able to convert old param values to new param values. This map will be composed with any existing ParamResolver via single-step resolution.
recursive If True, resolves parameter values recursively over the resolver; otherwise performs a single resolution step. This behavior applies only to the passed-in mapping, for the current application. Existing parameters are never resolved recursively because a->b and b->a needs to be a valid mapping.

Returns
A copy of this operation with its ParamResolver updated as specified by param_values.

with_probability

View source

with_probability(
    probability: 'cirq.TParamVal'
) -> 'cirq.Operation'

Creates a probabilistic channel with this operation.

Args
probability floating point value between 0 and 1, giving the probability this gate is applied.

Returns
cirq.RandomGateChannel that applies self with probability probability and the identity with probability 1-p.

Raises
NotImplementedError if called on an operation that lacks a gate.

with_qubit_mapping

View source

with_qubit_mapping(
    qubit_map: Union[Mapping[cirq.Qid, cirq.Qid], Callable[[cirq.Qid], cirq.Qid]]
) -> cirq.CircuitOperation

Returns a copy of this operation with an updated qubit mapping.

Users should pass either 'qubit_map' or 'transform' to this method.

Args
qubit_map A mapping of old qubits to new qubits. This map will be composed with any existing qubit mapping.

Returns
A copy of this operation targeting qubits as indicated by qubit_map.

Raises
TypeError qubit_map was not a function or dict mapping qubits to qubits.
ValueError The new operation has a different number of qubits than this operation.

with_qubits

View source

with_qubits(
    *new_qubits
) -> cirq.CircuitOperation

Returns a copy of this operation with an updated qubit mapping.

Args
*new_qubits A list of qubits to target. Qubits in this list are matched to qubits in the circuit following default qubit order, ignoring any existing qubit map.

Returns
A copy of this operation targeting new_qubits.

Raises
ValueError new_qubits has a different number of qubits than this operation.

with_repetition_ids

View source

with_repetition_ids(
    repetition_ids: List[str]
) -> cirq.CircuitOperation

Returns a copy of this CircuitOperation with the given repetition IDs.

Args
repetition_ids List of new repetition IDs to use. Must have length equal to the existing number of repetitions.

Returns
A copy of this object with repetition_ids=repetition_ids.

with_tags

View source

with_tags(
    *new_tags
) -> 'cirq.Operation'

Creates a new TaggedOperation, with this op and the specified tags.

This method can be used to attach meta-data to specific operations without affecting their functionality. The intended usage is to attach classes intended for this purpose or strings to mark operations for specific usage that will be recognized by consumers. Specific examples include ignoring this operation in optimization passes, hardware-specific functionality, or circuit diagram customizability.

Tags can be a list of any type of object that is useful to identify this operation as long as the type is hashable. If you wish the resulting operation to be eventually serialized into JSON, you should also restrict the operation to be JSON serializable.

Please note that tags should be instantiated if classes are used. Raw types are not allowed.

Args
*new_tags The tags to wrap this operation in.

without_classical_controls

View source

without_classical_controls() -> 'cirq.Operation'

Removes all classical controls from the operation.

This function removes all classical controls gating the operation. It acts recursively, so that all classical control wrappers are always removed from the current operation.

If there are no classical controls on the operation, it will return self.

Since tags are fragile, this will also remove any tags from the operation, when called on TaggedOperation (unless there are no classical controls on it). If a TaggedOperation is under all the classical control layers, that TaggedOperation will be returned from this function.

Returns
The operation with all classical controls removed.

__eq__

View source

__eq__(
    other
) -> bool

Return self==value.

__pow__

View source

__pow__(
    power: IntParam
) -> cirq.CircuitOperation