cirq.ops.PauliString

An effect applied to a collection of qubits.

Inherits From: Operation

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

Used in the notebooks

Used in the tutorials

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.

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

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

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.

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.

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.

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

expectation_from_wavefunction

View source

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

THIS FUNCTION IS DEPRECATED.

IT WILL BE REMOVED IN cirq v0.10.0.

Use expectation_from_state_vector instead

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

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(
    func: Callable[['cirq.Qid'], 'cirq.Qid']
) -> cirq.ops.raw_types.TSelf

Returns the same operation, but with different qubits.

Args
func The function to use to turn each current qubit into a desired new qubit.

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

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_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.TaggedOperation"

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.

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
)