--- title: QubitSparsePauliList (v2.4) description: API reference for qiskit.quantum_info.QubitSparsePauliList in qiskit v2.4 source: https://eu-de.quantum.cloud.ibm.com/docs/en/api/qiskit/2.4/qiskit.quantum_info.QubitSparsePauliList --- # QubitSparsePauliList *class* `qiskit.quantum_info.QubitSparsePauliList(data, /, num_qubits=None)` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.4/qiskit/quantum_info/__init__.py) Bases: [`object`](https://docs.python.org/3/library/functions.html#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 $P = \bigotimes_n A^{(n)}_i$, for $A^{(n)}_i \in \{I, X, Y, Z\}$. The internal representation of a [`QubitSparsePauliList`](#qiskit.quantum_info.QubitSparsePauliList "qiskit.quantum_info.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 $[Z^{(0)}, \dots Z^{(n-1)}]$, where $Z^{(j)}$ represents The $Z$ operator on qubit $j$ and identity on all others, can be stored in [`QubitSparsePauliList`](#qiskit.quantum_info.QubitSparsePauliList "qiskit.quantum_info.QubitSparsePauliList") with a linear amount of memory in the number of qubits. ### Indexing [`QubitSparsePauliList`](#qiskit.quantum_info.QubitSparsePauliList "qiskit.quantum_info.QubitSparsePauliList") behaves as [a Python sequence](https://docs.python.org/3/glossary.html#term-sequence) (the standard form, not the expanded [`collections.abc.Sequence`](https://docs.python.org/3/library/collections.abc.html#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`](/docs/api/qiskit/2.4/qiskit.quantum_info.QubitSparsePauli "qiskit.quantum_info.QubitSparsePauli") instances. ## Construction [`QubitSparsePauliList`](#qiskit.quantum_info.QubitSparsePauliList "qiskit.quantum_info.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()`](#qiskit.quantum_info.QubitSparsePauliList.from_label "qiskit.quantum_info.QubitSparsePauliList.from_label") | Convert a dense string label into a single-element [`QubitSparsePauliList`](#qiskit.quantum_info.QubitSparsePauliList "qiskit.quantum_info.QubitSparsePauliList"). | | [`from_list()`](#qiskit.quantum_info.QubitSparsePauliList.from_list "qiskit.quantum_info.QubitSparsePauliList.from_list") | Construct from a list of dense string labels. | | [`from_sparse_list()`](#qiskit.quantum_info.QubitSparsePauliList.from_sparse_list "qiskit.quantum_info.QubitSparsePauliList.from_sparse_list") | Elements given as a list of tuples of sparse string labels and the qubits they apply to. | | [`from_pauli()`](#qiskit.quantum_info.QubitSparsePauliList.from_pauli "qiskit.quantum_info.QubitSparsePauliList.from_pauli") | Raise a single [`Pauli`](/docs/api/qiskit/2.4/qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") into a single-element [`QubitSparsePauliList`](#qiskit.quantum_info.QubitSparsePauliList "qiskit.quantum_info.QubitSparsePauliList"). | | [`from_qubit_sparse_paulis()`](#qiskit.quantum_info.QubitSparsePauliList.from_qubit_sparse_paulis "qiskit.quantum_info.QubitSparsePauliList.from_qubit_sparse_paulis") | Construct from a list of [`QubitSparsePauli`](/docs/api/qiskit/2.4/qiskit.quantum_info.QubitSparsePauli "qiskit.quantum_info.QubitSparsePauli")s. | ### \_\_new\_\_ `__new__(data, /, num_qubits=None)` The default constructor of [`QubitSparsePauliList`](#qiskit.quantum_info.QubitSparsePauliList "qiskit.quantum_info.QubitSparsePauliList"). This delegates to one of [the explicit conversion-constructor methods](#qubit-sparse-pauli-list-convert-constructors), 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`](#qiskit.quantum_info.QubitSparsePauliList "qiskit.quantum_info.QubitSparsePauliList"), in which case the input is copied, or it can be a list in a valid format for either [`from_list()`](#qiskit.quantum_info.QubitSparsePauliList.from_list "qiskit.quantum_info.QubitSparsePauliList.from_list") or [`from_sparse_list()`](#qiskit.quantum_info.QubitSparsePauliList.from_sparse_list "qiskit.quantum_info.QubitSparsePauliList.from_sparse_list"). - **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#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()`](#qiskit.quantum_info.QubitSparsePauliList.empty "qiskit.quantum_info.QubitSparsePauliList.empty") can be used to construct an empty list of qubit-sparse Paulis acting on a given number of qubits. ## Conversions An existing [`QubitSparsePauliList`](#qiskit.quantum_info.QubitSparsePauliList "qiskit.quantum_info.QubitSparsePauliList") can be converted into other formats. | Method | Summary | | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | [`to_sparse_list()`](#qiskit.quantum_info.QubitSparsePauliList.to_sparse_list "qiskit.quantum_info.QubitSparsePauliList.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*](/docs/api/qiskit/2.4/qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list)*\[*[*int*](https://docs.python.org/3/library/functions.html#int)*] | None*) – The layout to apply. Most uses of this function should pass the [`QuantumCircuit.layout`](/docs/api/qiskit/2.4/qiskit.circuit.QuantumCircuit#layout "qiskit.circuit.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*](https://docs.python.org/3/library/functions.html#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`](/docs/api/qiskit/2.4/qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout"), or the same width as the input if the `layout` is given in another form. **Returns** A new [`QubitSparsePauli`](/docs/api/qiskit/2.4/qiskit.quantum_info.QubitSparsePauli "qiskit.quantum_info.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 subtraction operations resulting from composition may not need to reallocate. **Examples** ```python >>> 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** ```python >>> 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`](#qiskit.quantum_info.QubitSparsePauliList "qiskit.quantum_info.QubitSparsePauliList") instances. **Examples** Get the empty list on 100 qubits: ```python >>> QubitSparsePauliList.empty(100) ``` ### 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`](/docs/api/qiskit/2.4/qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") and [`SparsePauliOp`](/docs/api/qiskit/2.4/qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp"). **Parameters** **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)) – the dense label. **Examples** ```python >>> QubitSparsePauliList.from_label("IIIIXZI") >>> label = "IYXZI" >>> pauli = Pauli(label) >>> assert QubitSparsePauliList.from_label(label) == QubitSparsePauliList.from_pauli(pauli) ``` > **See also** > > **[`from_list()`](#qiskit.quantum_info.QubitSparsePauliList.from_list "qiskit.quantum_info.QubitSparsePauliList.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 qubit-sparse Pauli list from a list of dense labels. This is analogous to [`SparsePauliOp.from_list()`](/docs/api/qiskit/2.4/qiskit.quantum_info.SparsePauliOp#from_list "qiskit.quantum_info.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`](/docs/api/qiskit/2.4/qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") and [`SparsePauliOp`](/docs/api/qiskit/2.4/qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp"). **Parameters** - **iter** ([*list*](https://docs.python.org/3/library/stdtypes.html#list)*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*]*) – List of dense string labels. - **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#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: ```python >>> QubitSparsePauliList.from_list([ ... "IIIXX", ... "IIYYI", ... "IXXII", ... "ZZIII", ... ]) ``` Use `num_qubits` to disambiguate potentially empty inputs: ```python >>> QubitSparsePauliList.from_list([], num_qubits=10) ``` This method is equivalent to calls to [`from_sparse_list()`](#qiskit.quantum_info.QubitSparsePauliList.from_sparse_list "qiskit.quantum_info.QubitSparsePauliList.from_sparse_list") with the explicit qubit-arguments field set to decreasing integers: ```python >>> 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_list ``` > **See also** > > **[`from_sparse_list()`](#qiskit.quantum_info.QubitSparsePauliList.from_sparse_list "qiskit.quantum_info.QubitSparsePauliList.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 [`QubitSparsePauliList`](#qiskit.quantum_info.QubitSparsePauliList "qiskit.quantum_info.QubitSparsePauliList") from a single [`Pauli`](/docs/api/qiskit/2.4/qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") instance. The output list will have a single term. Note that the phase is dropped. **Parameters** **pauli** ([`Pauli`](/docs/api/qiskit/2.4/qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli")) – the single Pauli to convert. **Examples** ```python >>> label = "IYXZI" >>> pauli = Pauli(label) >>> QubitSparsePauliList.from_pauli(pauli) >>> 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`](#qiskit.quantum_info.QubitSparsePauliList "qiskit.quantum_info.QubitSparsePauliList") out of individual [`QubitSparsePauli`](/docs/api/qiskit/2.4/qiskit.quantum_info.QubitSparsePauli "qiskit.quantum_info.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*](/docs/api/qiskit/2.4/qiskit.quantum_info.QubitSparsePauli "qiskit.quantum_info.QubitSparsePauli")*]*) – Iterable of individual terms to build the list from. - **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#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()`](/docs/api/qiskit/2.4/qiskit.quantum_info.SparsePauliOp#from_sparse_list "qiskit.quantum_info.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()`](#qiskit.quantum_info.QubitSparsePauliList.from_list "qiskit.quantum_info.QubitSparsePauliList.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*](https://docs.python.org/3/library/stdtypes.html#list)*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple)*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*, Sequence\[*[*int*](https://docs.python.org/3/library/functions.html#int)*]]]*) – tuples of labels and the qubits each single-qubit term applies to. - **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int)) – the number of qubits the operators in the list act on. **Examples** Construct a simple list: ```python >>> QubitSparsePauliList.from_sparse_list( ... [("ZX", (1, 4)), ("YY", (0, 3))], ... num_qubits=5, ... ) ``` This method can replicate the behavior of [`from_list()`](#qiskit.quantum_info.QubitSparsePauliList.from_list "qiskit.quantum_info.QubitSparsePauliList.from_list"), if the qubit-arguments field of the tuple is set to decreasing integers: ```python >>> 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_list ``` > **See also** > > **[`to_sparse_list()`](#qiskit.quantum_info.QubitSparsePauliList.to_sparse_list "qiskit.quantum_info.QubitSparsePauliList.to_sparse_list")** > > The reverse of this method. ### to\_dense\_array `to_dense_array()` Express the list in a dense array format. Each entry is a u8 following the [`Pauli`](/docs/api/qiskit/2.4/qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") representation, while the rows index distinct Paulis and the columns distinct qubits. **Examples** ```python >>> paulis = QubitSparsePauliList.from_sparse_list( ... [("ZX", (1, 4)), ("YY", (0, 3)), ("XX", (0, 1))], ... num_qubits=5, ... ) >>> paulis.to_dense_array() ``` ### to\_pauli\_list `to_pauli_list()` Return a [`PauliList`](/docs/api/qiskit/2.4/qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") representing the same phaseless 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 [`QubitSparsePauliList.from_sparse_list()`](#qiskit.quantum_info.QubitSparsePauliList.from_sparse_list "qiskit.quantum_info.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** ```python >>> qubit_sparse_list = QubitSparsePauliList.from_list(["IIXIZ", "IIZIX"]) >>> reconstructed = QubitSparsePauliList.from_sparse_list(qubit_sparse_list.to_sparse_list(), qubit_sparse_list.num_qubits) ``` > **See also** > > **[`from_sparse_list()`](#qiskit.quantum_info.QubitSparsePauliList.from_sparse_list "qiskit.quantum_info.QubitSparsePauliList.from_sparse_list")** > > The constructor that can interpret these lists.