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[cirq.ParamMappingType] = None,
    repetition_ids: Optional[Sequence[str]] = None,
    parent_path: Tuple[str, ...] = (),
    extern_keys: FrozenSet['cirq.MeasurementKey'] = frozenset(),
    use_repetition_ids: bool = True,
    repeat_until: Optional['cirq.Condition'] = None
)

Used in the notebooks

Used in the tutorials
Circuits Custom Transformers Classical control Best practices Quantum Virtual Engine

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.

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

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

Raises

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

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

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.

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'

cirq.CircuitOperation

Used in the notebooks

Args

Raises

Attributes

Methods

base_operation

controlled_by

mapped_circuit

mapped_op

repeat

replace

transform_qubits

validate_args

with_classical_controls

with_key_path

with_measurement_key_mapping

with_params

with_probability

with_qubit_mapping

with_qubits

with_repetition_ids

with_tags

without_classical_controls

__eq__

__pow__

`base_operation`

`controlled_by`

`mapped_circuit`

`mapped_op`

`repeat`

`replace`

`transform_qubits`

`validate_args`

`with_classical_controls`

`with_key_path`

`with_measurement_key_mapping`

`with_params`

`with_probability`

`with_qubit_mapping`

`with_qubits`

`with_repetition_ids`

`with_tags`

`without_classical_controls`

`eq`

`pow`