QubitSparsePauliList
class qiskit.quantum_info.QubitSparsePauliList
Bases: object
A list of phase-less Pauli operators 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 , for . The internal representation of a QubitSparsePauliList stores only the non-identity single-qubit Pauli operators. This makes it significantly more efficient to represent lists of Pauli operators with low weights on a large number of qubits. For example, the list of :math`n`-qubit operators , where represents The operator on qubit and identity on all others, can be stored in QubitSparsePauliList with a linear amount of memory in the number of qubits.
Indexing
QubitSparsePauliList 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 QubitSparsePauli instances.
Construction
QubitSparsePauliList 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 QubitSparsePauliList. |
from_list() | Construct from a list of dense string labels. |
from_sparse_list() | Elements given as a list of tuples of sparse string labels and the qubits they apply to. |
from_pauli() | Raise a single Pauli into a single-element QubitSparsePauliList. |
from_qubit_sparse_paulis() | Construct from a list of QubitSparsePaulis. |
__new__
__new__(data, /, num_qubits=None)
The default constructor of QubitSparsePauliList.
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
QubitSparsePauliList, in which case the input is copied, or it can be a list in a valid format for eitherfrom_list()orfrom_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 qubit-sparse Paulis acting on a given number of qubits.
Conversions
An existing QubitSparsePauliList can be converted into other formats.
| Method | Summary |
|---|---|
to_sparse_list() | Express the observable in a sparse list format with elements (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 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.layoutfield from a circuit that was transpiled for hardware. In addition, you can pass a list of new qubit indices. If given as explicitlyNone, no remapping is applied (but you can still usenum_qubitsto 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 thelayoutis 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 = QubitSparsePauliList.from_list(["IXXXYY", "ZZYZII"])
>>> pauli_list.clear()
>>> assert pauli_list == QubitSparsePauliList.empty(pauli_list.num_qubits)copy
copy()
Get a copy of this qubit sparse Pauli list.
Examples
>>> qubit_sparse_pauli_list = QubitSparsePauliList.from_list(["IXZXYYZZ", "ZXIXYYZZ"])
>>> assert qubit_sparse_pauli_list == qubit_sparse_pauli_list.copy()
>>> assert qubit_sparse_pauli_list is not 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 QubitSparsePauliList instances.
Examples
Get the empty list on 100 qubits:
>>> QubitSparsePauliList.empty(100)
<QubitSparsePauliList 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
>>> QubitSparsePauliList.from_label("IIIIXZI")
<QubitSparsePauliList with 1 element on 7 qubits: [X_2 Z_1]>
>>> label = "IYXZI"
>>> pauli = Pauli(label)
>>> assert QubitSparsePauliList.from_label(label) == QubitSparsePauliList.from_pauli(pauli)A generalization of this method that constructs a list from multiple labels.
from_list
static from_list(iter, /, *, num_qubits=None)
Construct a 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.
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
- iter (list[str]) – List of dense string labels.
- num_qubits (int | None) – It is not necessary to specify this if you are sure that
iteris not an empty sequence, since it can be inferred from the label lengths. Ifitermay be empty, you must specify this argument to disambiguate how many qubits the operators act on. If this is given anditeris not empty, the value must match the label lengths.
Examples
Construct a qubit sparse Pauli list from a list of labels:
>>> QubitSparsePauliList.from_list([
... "IIIXX",
... "IIYYI",
... "IXXII",
... "ZZIII",
... ])
<QubitSparsePauliList 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:
>>> QubitSparsePauliList.from_list([], num_qubits=10)
<QubitSparsePauliList 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 = QubitSparsePauliList.from_list(labels)
>>> from_sparse_list = QubitSparsePauliList.from_sparse_list([
... (label, (3, 2, 1, 0))
... for label in labels
... ])
>>> assert from_list == from_sparse_listConstruct 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 QubitSparsePauliList 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)
>>> QubitSparsePauliList.from_pauli(pauli)
<QubitSparsePauliList with 1 element on 5 qubits: [Y_3 X_2 Z_1]>
>>> assert QubitSparsePauliList.from_label(label) == QubitSparsePauliList.from_pauli(pauli)from_qubit_sparse_paulis
static from_qubit_sparse_paulis(obj, /, num_qubits=None)
Construct a QubitSparsePauliList out of individual QubitSparsePauli instances.
All the terms must have the same number of qubits. If supplied, the num_qubits argument must match the terms.
Parameters
- obj (Iterable[QubitSparsePauli]) – 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 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[str, Sequence[int]]]) – tuples of 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:
>>> QubitSparsePauliList.from_sparse_list(
... [("ZX", (1, 4)), ("YY", (0, 3))],
... num_qubits=5,
... )
<QubitSparsePauliList with 2 elements on 5 qubits: [X_4 Z_1, 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 = QubitSparsePauliList.from_list(labels)
>>> from_sparse_list = QubitSparsePauliList.from_sparse_list([
... (label, (3, 2, 1, 0))
... for label in labels
... ])
>>> assert from_list == from_sparse_listThe reverse of this method.
to_sparse_list
to_sparse_list()
Express the list in terms of a sparse list format.
This can be seen as counter-operation of QubitSparsePauliList.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
>>> qubit_sparse_list = QubitSparsePauliList.from_list(["IIXIZ", "IIZIX"])
>>> reconstructed = QubitSparsePauliList.from_sparse_list(qubit_sparse_list.to_sparse_list(), qubit_sparse_list.num_qubits)The constructor that can interpret these lists.