cirq.ops.PauliString

An effect applied to a collection of qubits.

Inherits From: Operation

View aliases

Main aliases

cirq.PauliString, cirq.ops.pauli_string.PauliString

cirq.ops.PauliString(
    *contents,
    qubit_pauli_map: Optional[Dict[TKey, 'cirq.Pauli']] = None,
    coefficient: Union[int, float, complex] = 1
)

The most common kind of Operation is a GateOperation, which separates its effect into a qubit-independent Gate and the qubits it should be applied to.

Args
`*contents`	A value or values to convert into a pauli string. This can be a number, a pauli operation, a dictionary from qubit to pauli/identity gates, or collections thereof. If a list of values is given, they are each individually converted and then multiplied from left to right in order.
`qubit_pauli_map`	Initial dictionary mapping qubits to pauli operations. Defaults to the empty dictionary. Note that, unlike dictionaries passed to contents, this dictionary must not contain any identity gate values. Further note that this argument specifies values that are logically before factors specified in `contents`; `contents` are right multiplied onto the values in this dictionary.
`coefficient`	Initial scalar coefficient. Defaults to 1.

Raises
`TypeError`	If the `qubit_pauli_map` has values that are not Paulis.

Attributes
`classical_controls`	The classical controls gating this operation.
`coefficient`
`gate`
`qubits`
`tags`	Returns a tuple of the operation's tags.
`untagged`	Returns the underlying operation without any tags.

Methods

`after`

View source

after(
    ops: 'cirq.OP_TREE'
) -> 'cirq.PauliString'

Determines the equivalent pauli string after some operations.

If the PauliString is \(P\) and the Clifford operation is \(C\), then the result is \(C P C^\dagger\).

Args
`ops`	A stabilizer operation or nested collection of stabilizer operations.

Returns
The result of propagating this pauli string from before to after the given operations.

`before`

View source

before(
    ops: 'cirq.OP_TREE'
) -> 'cirq.PauliString'

Determines the equivalent pauli string before some operations.

If the PauliString is \(P\) and the Clifford operation is \(C\), then the result is \(C^\dagger P C\).

Args
`ops`	A stabilizer operation or nested collection of stabilizer operations.

Returns
The result of propagating this pauli string from after to before the given operations.

`conjugated_by`

View source

conjugated_by(
    clifford: 'cirq.OP_TREE'
) -> 'PauliString'

Returns the Pauli string conjugated by a clifford operation.

The product-of-Paulis \(P\) conjugated by the Clifford operation \(C\) is

$$
C^\dagger P C
$$

For example, conjugating a +Y operation by an S operation results in a +X operation (as opposed to a -X operation).

In a circuit diagram where P is a pauli string observable immediately after a Clifford operation C, the pauli string P.conjugated_by(C) is the equivalent pauli string observable just before C.

--------------------------C---P---

= ---C---P------------------------

= ---C---P---------C^-1---C-------

= ---C---P---C^-1---------C-------

= --(C^-1 · P · C)--------C-------

= ---P.conjugated_by(C)---C-------

Analogously, a Pauli product P can be moved from before a Clifford C in a circuit diagram to after the Clifford C by conjugating P by the inverse of C:

---P---C---------------------------

= -----C---P.conjugated_by(C^-1)---

Args

Args
`clifford`	The Clifford operation to conjugate by. This can be an individual operation, or a tree of operations. Note that the composite Clifford operation defined by a sequence of operations is equivalent to a circuit containing those operations in the given order. Somewhat counter-intuitively, this means that the operations in the sequence are conjugated onto the Pauli string in reverse order. For example, `P.conjugated_by([C1, C2])` is equivalent to `P.conjugated_by(C2).conjugated_by(C1)`.

clifford

The Clifford operation to conjugate by. This can be an individual operation, or a tree of operations.

Note that the composite Clifford operation defined by a sequence of operations is equivalent to a circuit containing those operations in the given order. Somewhat counter-intuitively, this means that the operations in the sequence are conjugated onto the Pauli string in reverse order. For example, P.conjugated_by([C1, C2]) is equivalent to P.conjugated_by(C2).conjugated_by(C1).

Examples:

a, b = cirq.LineQubit.range(2)
print(cirq.X(a).conjugated_by(cirq.CZ(a, b)))
X(0)*Z(1)
print(cirq.X(a).conjugated_by(cirq.S(a)))
-Y(0)
print(cirq.X(a).conjugated_by([cirq.H(a), cirq.CNOT(a, b)]))
Z(0)*X(1)

Returns
The Pauli string conjugated by the given Clifford operation.

`controlled_by`

View source

controlled_by(
    *control_qubits,
    control_values: Optional[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.

`dense`

View source

dense(
    qubits: Sequence[cirq.ops.pauli_string.TKey]
) -> 'cirq.DensePauliString'

Returns a cirq.DensePauliString version of this Pauli string.

This method satisfies the invariant P.dense(qubits).on(*qubits) == P.

Args
`qubits`	The implicit sequence of qubits used by the dense pauli string. Specifically, if the returned dense Pauli string was applied to these qubits (via its `on` method) then the result would be a Pauli string equivalent to the receiving Pauli string.

Returns
A `cirq.DensePauliString` instance `D` such that `D.on(*qubits)` equals the receiving `cirq.PauliString` instance `P`.

Raises
`ValueError`	If the number of qubits is too small.

`equal_up_to_coefficient`

View source

equal_up_to_coefficient(
    other: 'cirq.PauliString'
) -> bool

`expectation_from_density_matrix`

View source

expectation_from_density_matrix(
    state: np.ndarray,
    qubit_map: Mapping[cirq.ops.pauli_string.TKey, int],
    *,
    atol: float = 1e-07,
    check_preconditions: bool = True
) -> float

Evaluate the expectation of this PauliString given a density matrix.

Compute the expectation value of this PauliString with respect to an array representing a density matrix. By convention expectation values are defined for Hermitian operators, and so this method will fail if this PauliString is non-Hermitian.

state must be an array representation of a density matrix and have shape (2 ** n, 2 ** n) or (2, 2, ..., 2) (2*n entries), where state is expressed over n qubits.

qubit_map must assign an integer index to each qubit in this PauliString that determines which bit position of a computational basis state that qubit corresponds to. For example if state represents \(|0\rangle |+\rangle\) and q0, q1 = cirq.LineQubit.range(2) then:

cirq.X(q0).expectation(state, qubit_map={q0: 0, q1: 1}) = 0
cirq.X(q0).expectation(state, qubit_map={q0: 1, q1: 0}) = 1

Args
`state`	An array representing a valid density matrix.
`qubit_map`	A map from all qubits used in this PauliString to the indices of the qubits that `state` is defined over.
`atol`	Absolute numerical tolerance.
`check_preconditions`	Whether to check that `state` represents a valid density matrix.

Returns
The expectation value of the input state.

Raises
`NotImplementedError`	If this PauliString is non-Hermitian.
`TypeError`	If the input state is not complex.
`ValueError`	If the input state does not have the correct shape.

`expectation_from_state_vector`

View source

expectation_from_state_vector(
    state_vector: np.ndarray,
    qubit_map: Mapping[cirq.ops.pauli_string.TKey, int],
    *,
    atol: float = 1e-07,
    check_preconditions: bool = True
) -> float

Evaluate the expectation of this PauliString given a state vector.

Compute the expectation value of this PauliString with respect to a state vector. By convention expectation values are defined for Hermitian operators, and so this method will fail if this PauliString is non-Hermitian.

state must be an array representation of a state vector and have shape (2 ** n, ) or (2, 2, ..., 2) (n entries) where state is expressed over n qubits.

cirq.X(q0).expectation(state, qubit_map={q0: 0, q1: 1}) = 0
cirq.X(q0).expectation(state, qubit_map={q0: 1, q1: 0}) = 1

Args
`state_vector`	An array representing a valid state vector.
`qubit_map`	A map from all qubits used in this PauliString to the indices of the qubits that `state_vector` is defined over.
`atol`	Absolute numerical tolerance.
`check_preconditions`	Whether to check that `state_vector` represents a valid state vector.

Returns
The expectation value of the input state.

Raises
`NotImplementedError`	If this PauliString is non-Hermitian.
`TypeError`	If the input state is not complex.
`ValueError`	If the input state does not have the correct shape.

`frozen`

View source

frozen() -> 'cirq.PauliString'

Returns a cirq.PauliString with the same contents.

`get`

View source

get(
    key: Any, default=None
)

`items`

View source

items() -> ItemsView[cirq.ops.pauli_string.TKey, cirq.ops.Pauli]

`keys`

View source

keys() -> KeysView[cirq.ops.pauli_string.TKey]

`map_qubits`

View source

map_qubits(
    qubit_map: Dict[cirq.ops.pauli_string.TKey, cirq.ops.pauli_string.TKeyNew]
) -> 'cirq.PauliString[TKeyNew]'

`matrix`

View source

matrix(
    qubits: Optional[Iterable[TKey]] = None
) -> np.ndarray

Returns the matrix of self in computational basis of qubits.

Args
`qubits`	Ordered collection of qubits that determine the subspace in which the matrix representation of the Pauli string is to be computed. Qubits absent from self.qubits are acted on by the identity. Defaults to self.qubits.

`mutable_copy`

View source

mutable_copy() -> 'cirq.MutablePauliString'

Returns a new cirq.MutablePauliString with the same contents.

`pass_operations_over`

View source

pass_operations_over(
    ops: Iterable['cirq.Operation'], after_to_before: bool = False
) -> 'PauliString'

Determines how the Pauli string changes when conjugated by Cliffords.

The output and input pauli strings are related by a circuit equivalence. In particular, this circuit:

───ops───INPUT_PAULI_STRING───

will be equivalent to this circuit:

───OUTPUT_PAULI_STRING───ops───

up to global phase (assuming after_to_before is not set).

If ops together have matrix C, the Pauli string has matrix P, and the output Pauli string has matrix P', then P' == C^-1 P C up to global phase.

Setting after_to_before inverts the relationship, so that the output is the input and the input is the output. Equivalently, it inverts C.

Args
`ops`	The operations to move over the string.
`after_to_before`	Determines whether the operations start after the pauli string, instead of before (and so are moving in the opposite direction).

`to_z_basis_ops`

View source

to_z_basis_ops() -> Iterator[cirq.ops.Operation]

Returns operations to convert the qubits to the computational basis.

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

`values`

View source

values() -> ValuesView[cirq.ops.Pauli]

`with_classical_controls`

View source

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

Returns a classically controlled version of this operation.

An operation that is classically controlled is executed iff all conditions evaluate to True. Currently the only condition type is a measurement key. A measurement key evaluates to True iff any qubit in the corresponding measurement operation evaluated to a non-zero value.

The classical control will hide any tags on the existing operation, since tags are considered a local attribute.

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.

`with_coefficient`

View source

with_coefficient(
    new_coefficient: Union[int, float, complex]
) -> 'PauliString'

`with_probability`

View source

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

`with_qubits`

View source

with_qubits(
    *new_qubits
) -> 'PauliString'

Returns the same operation, but applied to different qubits.

Args
`new_qubits`	The new qubits to apply the operation to. The order must exactly match the order of qubits returned from the operation's `qubits` property.

`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 considered local, this will also remove any tags from the operation (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.

`zip_items`

View source

zip_items(
    other: 'cirq.PauliString[TKey]'
) -> Iterator[Tuple[TKey, Tuple[pauli_gates.Pauli, pauli_gates.Pauli]]]

`zip_paulis`

View source

zip_paulis(
    other: 'cirq.PauliString'
) -> Iterator[Tuple[pauli_gates.Pauli, pauli_gates.Pauli]]

`add`

View source

__add__(
    other
)

`bool`

View source

__bool__()

`contains`

View source

__contains__(
    key: cirq.ops.pauli_string.TKey
) -> bool

`eq`

View source

__eq__(
    other: _SupportsValueEquality
) -> bool

`getitem`

View source

__getitem__(
    key: cirq.ops.pauli_string.TKey
) -> cirq.ops.Pauli

`iter`

View source

__iter__() -> Iterator[cirq.ops.pauli_string.TKey]

`len`

View source

__len__() -> int

`mul`

View source

__mul__(
    other
)

`ne`

View source

__ne__(
    other: _SupportsValueEquality
) -> bool

`neg`

View source

__neg__() -> 'PauliString'

`pos`

View source

__pos__() -> 'PauliString'

`pow`

View source

__pow__(
    power
)

`radd`

View source

__radd__(
    other
)

`rmul`

View source

__rmul__(
    other
) -> 'PauliString'

`rpow`

View source

__rpow__(
    base
)

`rsub`

View source

__rsub__(
    other
)

`sub`

View source

__sub__(
    other
)

`truediv`

View source

__truediv__(
    other
)

cirq.ops.PauliString

View aliases

Args

Raises

Attributes

Methods

after

before

conjugated_by

Examples:

controlled_by

dense

equal_up_to_coefficient

expectation_from_density_matrix

expectation_from_state_vector

frozen

get

items

keys

map_qubits

matrix

mutable_copy

pass_operations_over

to_z_basis_ops

transform_qubits

validate_args

values

with_classical_controls

with_coefficient

with_probability

with_qubits

with_tags

without_classical_controls

zip_items

zip_paulis

__add__

__bool__

__contains__

__eq__

__getitem__

__iter__

__len__

__mul__

__ne__

__neg__

__pos__

__pow__

__radd__

__rmul__

__rpow__

__rsub__

__sub__

__truediv__

`after`

`before`

`conjugated_by`

`controlled_by`

`dense`

`equal_up_to_coefficient`

`expectation_from_density_matrix`

`expectation_from_state_vector`

`frozen`

`get`

`items`

`keys`

`map_qubits`

`matrix`

`mutable_copy`

`pass_operations_over`

`to_z_basis_ops`

`transform_qubits`

`validate_args`

`values`

`with_classical_controls`

`with_coefficient`

`with_probability`

`with_qubits`

`with_tags`

`without_classical_controls`

`zip_items`

`zip_paulis`

`add`

`bool`

`contains`

`eq`

`getitem`

`iter`

`len`

`mul`

`ne`

`neg`

`pos`

`pow`

`radd`

`rmul`

`rpow`

`rsub`

`sub`

`truediv`