cirq.circuits.CircuitOperation

An operation that encapsulates a circuit.

Inherits From: Operation

cirq.circuits.CircuitOperation(
    circuit: """cirq.FrozenCircuit""",
    repetitions: int = None,
    qubit_map: Dict['cirq.Qid', 'cirq.Qid'] = <factory>,
    measurement_key_map: Dict[str, str] = <factory>,
    param_resolver: cirq.study.ParamResolver = cirq.circuits.CircuitOperation.param_resolver,
    repetition_ids: Optional[List[str]] = None,
    parent_path: Tuple[str, ...] = ()
)

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.
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.
parent_path A tuple of identifiers for any parent CircuitOperations containing this one.
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).

gate

qubits Returns the qubits operated on by this object.
tags Returns a tuple of the operation's tags.
untagged Returns the underlying operation without any tags.
circuit Dataclass field
repetitions Dataclass field
qubit_map Dataclass field
measurement_key_map Dataclass field
param_resolver Dataclass field
repetition_ids Dataclass field
parent_path Dataclass field

Methods

base_operation

View source

base_operation() -> "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_values: Optional[Sequence[Union[int, Collection[int]]]] = None,
    *control_qubits
) -> "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[INT_TYPE] = None,
    repetition_ids: Optional[List[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
) -> "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']]
) -> cirq.ops.raw_types.TSelf

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_key_path

View source

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

with_measurement_key_mapping

View source

with_measurement_key_mapping(
    key_map: Dict[str, str]
) -> "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.study.ParamResolverOrSimilarType
) -> "CircuitOperation"

Returns a copy of this operation with an updated ParamResolver.

Note that any resulting parameter mappings with no corresponding parameter in the base circuit will be omitted.

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.

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"

with_qubit_mapping

View source

with_qubit_mapping(
    qubit_map: Union[Dict['cirq.Qid', 'cirq.Qid'], Callable[['cirq.Qid'], 'cirq.Qid']]
) -> "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.
transform A function mapping old qubits to new qubits. This function 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
) -> "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]
) -> "CircuitOperation"

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.

__eq__

View source

__eq__(
    other
) -> bool

Return self==value.

__pow__

View source

__pow__(
    power: int
) -> "CircuitOperation"

param_resolver Instance of cirq.study.ParamResolver
repetition_ids None
repetitions 1