PhasedQubitSparsePauliList

class qiskit.quantum_info.PhasedQubitSparsePauliList

Bases: object

A list of Pauli operators with phases stored in a qubit-sparse format.

Representation

Each individual Pauli operator in the list is a tensor product of single-qubit Pauli operators of the form $P = (-i)^n\bigotimes_n A^{(n)}_i$ , for $A^{(n)}_i \in \{I, X, Y, Z\}$ , and an integer $n$ called the phase exponent. The internal representation of a PhasedQubitSparsePauliList stores only the non-identity single-qubit Pauli operators.

Indexing

PhasedQubitSparsePauliList behaves as a Python sequence (the standard form, not the expanded collections.abc.Sequence). The elements of the list can be indexed by integers, as well as iterated through. Whether through indexing or iterating, elements of the list are returned as PhasedQubitSparsePauli instances.

Construction

PhasedQubitSparsePauliList defines several constructors. The default constructor will attempt to delegate to one of the more specific constructors, based on the type of the input. You can always use the specific constructors to have more control over the construction.

Method	Summary
`from_label()`	Convert a dense string label into a single-element `PhasedQubitSparsePauliList`.
`from_list()`	Construct from a list of dense string labels.
`from_sparse_list()`	Elements given as a list of tuples of the phase exponent, sparse string labels, and the qubits they apply to.
`from_pauli()`	Raise a single `Pauli` into a single-element `PhasedQubitSparsePauliList`.
`from_phased_qubit_sparse_paulis()`	Construct from a list of `PhasedQubitSparsePauli`s.

new

__new__(data, /, num_qubits=None)

The default constructor of PhasedQubitSparsePauliList.

This delegates to one of the explicit conversion-constructor methods, based on the type of the data argument. If num_qubits is supplied and constructor implied by the type of data does not accept a number, the given integer must match the input.

Parameters

data – The data type of the input. This can be another PhasedQubitSparsePauliList, in which case the input is copied, or it can be a list in a valid format for either from_list() or from_sparse_list().
num_qubits (int|None) – Optional number of qubits for the list. For most data inputs, this can be inferred and need not be passed. It is only necessary for empty lists or the sparse-list format. If given unnecessarily, it must match the data input.

In addition to the conversion-based constructors, the method empty() can be used to construct an empty list of phased qubit-sparse Paulis acting on a given number of qubits.

Conversions

An existing PhasedQubitSparsePauliList can be converted into other formats.

Method	Summary
`to_sparse_list()`	Express the observable in a sparse list format with elements `(phase, paulis, indices)`.

Attributes

num_qubits

The number of qubits the operators in the list act on.

This is not inferable from any other shape or values, since identities are not stored explicitly.

num_terms

The number of elements in the list.

Methods

apply_layout

apply_layout(layout, num_qubits=None)

Apply a transpiler layout to this phased qubit sparse Pauli list.

This enables remapping of qubit indices, e.g. if the list is defined in terms of virtual qubit labels.

Parameters

layout (TranspileLayout |list[int] | None) – The layout to apply. Most uses of this function should pass the QuantumCircuit.layout field from a circuit that was transpiled for hardware. In addition, you can pass a list of new qubit indices. If given as explicitly None, no remapping is applied (but you can still use num_qubits to expand the qubits in the list).
num_qubits (int | None) – The number of qubits to expand the list elements to. If not supplied, the output will be as wide as the given TranspileLayout, or the same width as the input if the layout is given in another form.

Returns

A new QubitSparsePauli with the provided layout applied.

clear

clear()

Clear all the elements from the list, making it equal to the empty list again.

This does not change the capacity of the internal allocations, so subsequent addition or substraction operations resulting from composition may not need to reallocate.

Examples

>>> pauli_list = PhasedQubitSparsePauliList.from_list(["IXXXYY", "ZZYZII"])
>>> pauli_list.clear()
>>> assert pauli_list == PhasedQubitSparsePauliList.empty(pauli_list.num_qubits)

copy

copy()

Get a copy of this qubit sparse Pauli list.

Examples

>>> phased_qubit_sparse_pauli_list = PhasedQubitSparsePauliList.from_list(["IXZXYYZZ", "ZXIXYYZZ"])
>>> assert phased_qubit_sparse_pauli_list == phased_qubit_sparse_pauli_list.copy()
>>> assert phased_qubit_sparse_pauli_list is not phased_qubit_sparse_pauli_list.copy()

empty

static empty(num_qubits)

Get the empty list for a given number of qubits.

The empty list contains no elements, and is the identity element for joining two PhasedQubitSparsePauliList instances.

Examples

Get the empty list on 100 qubits:

>>> PhasedQubitSparsePauliList.empty(100)
<PhasedQubitSparsePauliList with 0 elements on 100 qubits: []>

from_label

static from_label(label, /)

Construct a list with a single-term from a dense string label.

The label must be a sequence of the alphabet 'IXYZ'. The label is interpreted analogously to a bitstring. In other words, the right-most letter is associated with qubit 0, and so on. This is the same as the labels for Pauli and SparsePauliOp.

Parameters

label (str) – the dense label.

Examples

>>> PhasedQubitSparsePauliList.from_label("IIIIXZI")
<PhasedQubitSparsePauliList with 1 element on 7 qubits: [X_2 Z_1]>
>>> label = "IYXZI"
>>> pauli = Pauli(label)
>>> assert PhasedQubitSparsePauliList.from_label(label) == PhasedQubitSparsePauliList.from_pauli(pauli)

See also

from_list()

A generalization of this method that constructs a list from multiple labels.

from_list

static from_list(iter, /, *, num_qubits=None)

Construct a phased qubit-sparse Pauli list from a list of dense labels.

This is analogous to SparsePauliOp.from_list(). In this dense form, you must supply all identities explicitly in each label.

Parameters

iter (list[str]) – List of dense string labels.
num_qubits (int | None) – It is not necessary to specify this if you are sure that iter is not an empty sequence, since it can be inferred from the label lengths. If iter may be empty, you must specify this argument to disambiguate how many qubits the operators act on. If this is given and iter is not empty, the value must match the label lengths.

Examples

Construct a qubit sparse Pauli list from a list of labels:

>>> PhasedQubitSparsePauliList.from_list([
...     "IIIXX",
...     "IIYYI",
...     "IXXII",
...     "ZZIII",
... ])
<PhasedQubitSparsePauliList with 4 elements on 5 qubits:
    [X_1 X_0, Y_2 Y_1, X_3 X_2, Z_4 Z_3]>

Use num_qubits to disambiguate potentially empty inputs:

>>> PhasedQubitSparsePauliList.from_list([], num_qubits=10)
<PhasedQubitSparsePauliList with 0 elements on 10 qubits: []>

This method is equivalent to calls to from_sparse_list() with the explicit qubit-arguments field set to decreasing integers:

>>> labels = ["XYXZ", "YYZZ", "XYXZ"]
>>> from_list = PhasedQubitSparsePauliList.from_list(labels)
>>> from_sparse_list = PhasedQubitSparsePauliList.from_sparse_list([
...     (label, (3, 2, 1, 0))
...     for label in labels
... ])
>>> assert from_list == from_sparse_list

See also

from_sparse_list()

Construct the list from labels without explicit identities, but with the qubits each single-qubit operator term applies to listed explicitly.

from_pauli

static from_pauli(pauli, /)

Construct a PhasedQubitSparsePauliList from a single Pauli instance.

The output list will have a single term. Note that the phase is dropped.

Parameters

pauli (Pauli) – the single Pauli to convert.

Examples

>>> label = "IYXZI"
>>> pauli = Pauli(label)
>>> PhasedQubitSparsePauliList.from_pauli(pauli)
<PhasedQubitSparsePauliList with 1 element on 5 qubits: [Y_3 X_2 Z_1]>
>>> assert PhasedQubitSparsePauliList.from_label(label) == PhasedQubitSparsePauliList.from_pauli(pauli)

from_phased_qubit_sparse_paulis

static from_phased_qubit_sparse_paulis(obj, /, num_qubits=None)

Construct a PhasedQubitSparsePauliList out of individual PhasedQubitSparsePauli instances.

All the terms must have the same number of qubits. If supplied, the num_qubits argument must match the terms.

Parameters

obj (Iterable[PhasedQubitSparsePauli]) – Iterable of individual terms to build the list from.
num_qubits (int | None) – The number of qubits the elements of the list should act on. This is usually inferred from the input, but can be explicitly given to handle the case of an empty iterable.

Returns

The corresponding list.

from_sparse_list

static from_sparse_list(iter, /, num_qubits)

Construct a phased qubit sparse Pauli list from a list of labels and the qubits each item applies to.

This is analogous to SparsePauliOp.from_sparse_list().

The “labels” and “indices” fields of the tuples are associated by zipping them together. For example, this means that a call to from_list() can be converted to the form used by this method by setting the “indices” field of each triple to (num_qubits-1, ..., 1, 0).

Parameters

iter (list[tuple[int, str, Sequence[int]]]) – tuples of phase exponents, labels, and the qubits each single-qubit term applies to.
num_qubits (int) – the number of qubits the operators in the list act on.

Examples

Construct a simple list:

>>> PhasedQubitSparsePauliList.from_sparse_list(
...     [(0, "ZX", (1, 4)), (1, "YY", (0, 3))],
...     num_qubits=5,
... )
<PhasedQubitSparsePauliList with 2 elements on 5 qubits: [X_4 Z_1, (-i)Y_3 Y_0]>

This method can replicate the behavior of from_list(), if the qubit-arguments field of the tuple is set to decreasing integers:

>>> labels = ["XYXZ", "YYZZ", "XYXZ"]
>>> from_list = PhasedQubitSparsePauliList.from_list(labels)
>>> from_sparse_list = PhasedQubitSparsePauliList.from_sparse_list([
...     (label, (3, 2, 1, 0))
...     for label in labels
... ])
>>> assert from_list == from_sparse_list

See also

to_sparse_list()

The reverse of this method.

to_pauli_list

to_pauli_list()

Return a PauliList representing the same list of Paulis.

to_sparse_list

to_sparse_list()

Express the list in terms of a sparse list format.

This can be seen as counter-operation of PhasedQubitSparsePauliList.from_sparse_list(), however the order of terms is not guaranteed to be the same at after a roundtrip to a sparse list and back.

Examples

>>> phased_qubit_sparse_list = PhasedQubitSparsePauliList.from_list(["IIXIZ", "IIZIX"])
>>> reconstructed = PhasedQubitSparsePauliList.from_sparse_list(phased_qubit_sparse_list.to_sparse_list(), qubit_sparse_list.num_qubits)

See also

from_sparse_list()

The constructor that can interpret these lists.