Skip to main contentIBM Quantum Documentation

SparsePauliOp

class qiskit.quantum_info.SparsePauliOp(data, coeffs=None, *, ignore_pauli_phase=False, copy=True)

GitHub(opens in a new tab)

Bases: LinearOp

Sparse N-qubit operator in a Pauli basis representation.

This is a sparse representation of an N-qubit matrix Operator in terms of N-qubit PauliList and complex coefficients.

It can be used for performing operator arithmetic for hundred of qubits if the number of non-zero Pauli basis terms is sufficiently small.

The Pauli basis components are stored as a PauliList object and can be accessed using the paulis attribute. The coefficients are stored as a complex Numpy array vector and can be accessed using the coeffs attribute.

Data type of coefficients

The default dtype of the internal coeffs Numpy array is complex128. Users can configure this by passing np.ndarray with a different dtype. For example, a parameterized SparsePauliOp can be made as follows:

>>> import numpy as np
>>> from qiskit.circuit import ParameterVector
>>> from qiskit.quantum_info import SparsePauliOp
 
>>> SparsePauliOp(["II", "XZ"], np.array(ParameterVector("a", 2)))
SparsePauliOp(['II', 'XZ'],
      coeffs=[ParameterExpression(1.0*a[0]), ParameterExpression(1.0*a[1])])
Note

Parameterized SparsePauliOp does not support the following methods:

  • to_matrix(sparse=True) since scipy.sparse cannot have objects as elements.
  • to_operator() since Operator does not support objects.
  • sort, argsort since ParameterExpression does not support comparison.
  • equiv since ParameterExpression cannot be converted into complex.
  • chop since ParameterExpression does not support absolute value.

Initialize an operator object.

Parameters

  • data (PauliList orSparsePauliOp orPauli orlist(opens in a new tab) orstr(opens in a new tab)) – Pauli list of terms. A list of Pauli strings or a Pauli string is also allowed.

  • coeffs (np.ndarray) –

    complex coefficients for Pauli terms.

    Note

    If data is a SparsePauliOp and coeffs is not None, the value of the SparsePauliOp.coeffs will be ignored, and only the passed keyword argument coeffs will be used.

  • ignore_pauli_phase (bool(opens in a new tab)) – if true, any phase component of a given PauliList will be assumed to be zero. This is more efficient in cases where a PauliList has been constructed purely for this object, and it is already known that the phases in the ZX-convention are zero. It only makes sense to pass this option when giving PauliList data. (Default: False)

  • copy (bool(opens in a new tab)) – copy the input data if True, otherwise assign it directly, if possible. (Default: True)

Raises

QiskitError – If the input data or coeffs are invalid.


Attributes

atol

Default value: 1e-08

coeffs

Return the Pauli coefficients.

dim

Return tuple (input_shape, output_shape).

num_qubits

Return the number of qubits if a N-qubit operator or None otherwise.

parameters

Return the free Parameters in the coefficients.

paulis

Return the PauliList.

qargs

Return the qargs for the operator.

rtol

Default value: 1e-05

settings

Return settings.

size

The number of Pauli of Pauli terms in the operator.


Methods

adjoint

adjoint()

GitHub(opens in a new tab)

Return the adjoint of the Operator.

apply_layout

apply_layout(layout, num_qubits=None)

GitHub(opens in a new tab)

Apply a transpiler layout to this SparsePauliOp

Parameters

  • layout (TranspileLayout | List[int(opens in a new tab)] | None) – Either a TranspileLayout, a list of integers or None. If both layout and num_qubits are none, a copy of the operator is returned.
  • num_qubits (int(opens in a new tab) | None) – The number of qubits to expand the operator to. If not provided then if layout is a TranspileLayout the number of the transpiler output circuit qubits will be used by default. If layout is a list of integers the permutation specified will be applied without any expansion. If layout is None, the operator will be expanded to the given number of qubits.

Returns

A new SparsePauliOp with the provided layout applied

Return type

SparsePauliOp

argsort

argsort(weight=False)

GitHub(opens in a new tab)

Return indices for sorting the rows of the table.

Returns the composition of permutations in the order of sorting by coefficient and sorting by Pauli. By using the weight kwarg the output can additionally be sorted by the number of non-identity terms in the Pauli, where the set of all Pauli’s of a given weight are still ordered lexicographically.

Example

Here is an example of how to use SparsePauliOp argsort.

import numpy as np
from qiskit.quantum_info import SparsePauliOp
 
# 2-qubit labels
labels = ["XX", "XX", "XX", "YI", "II", "XZ", "XY", "XI"]
# coeffs
coeffs = [2.+1.j, 2.+2.j, 3.+0.j, 3.+0.j, 4.+0.j, 5.+0.j, 6.+0.j, 7.+0.j]
 
# init
spo = SparsePauliOp(labels, coeffs)
print('Initial Ordering')
print(spo)
 
# Lexicographic Ordering
srt = spo.argsort()
print('Lexicographically sorted')
print(srt)
 
# Lexicographic Ordering
srt = spo.argsort(weight=False)
print('Lexicographically sorted')
print(srt)
 
# Weight Ordering
srt = spo.argsort(weight=True)
print('Weight sorted')
print(srt)
Initial Ordering
SparsePauliOp(['XX', 'XX', 'XX', 'YI', 'II', 'XZ', 'XY', 'XI'],
              coeffs=[2.+1.j, 2.+2.j, 3.+0.j, 3.+0.j, 4.+0.j, 5.+0.j, 6.+0.j, 7.+0.j])
Lexicographically sorted
[4 7 0 1 2 6 5 3]
Lexicographically sorted
[4 7 0 1 2 6 5 3]
Weight sorted
[4 7 3 0 1 2 6 5]

Parameters

  • weight (bool(opens in a new tab)) – optionally sort by weight if True (Default: False).
  • sorted (By using the weight kwarg the output can additionally be) –
  • Pauli. (by the number of non-identity terms in the) –

Returns

the indices for sorting the table.

Return type

array

assign_parameters

assign_parameters(parameters, inplace=False)

GitHub(opens in a new tab)

Bind the free Parameters in the coefficients to provided values.

Parameters

Returns

A copy of the operator with bound parameters, if inplace is False, otherwise None.

Return type

SparsePauliOp | None

chop

chop(tol=1e-14)

GitHub(opens in a new tab)

Set real and imaginary parts of the coefficients to 0 if < tol in magnitude.

For example, the operator representing 1+1e-17j X + 1e-17 Y with a tolerance larger than 1e-17 will be reduced to 1 X whereas SparsePauliOp.simplify() would return 1+1e-17j X.

If a both the real and imaginary part of a coefficient is 0 after chopping, the corresponding Pauli is removed from the operator.

Parameters

tol (float(opens in a new tab)) – The absolute tolerance to check whether a real or imaginary part should be set to 0.

Returns

This operator with chopped coefficients.

Return type

SparsePauliOp

compose

compose(other, qargs=None, front=False)

GitHub(opens in a new tab)

Return the operator composition with another SparsePauliOp.

Parameters

  • other (SparsePauliOp) – a SparsePauliOp object.
  • qargs (list(opens in a new tab) or None) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None).
  • front (bool(opens in a new tab)) – If True compose using right operator multiplication, instead of left multiplication [default: False].

Returns

The composed SparsePauliOp.

Return type

SparsePauliOp

Raises

QiskitError – if other cannot be converted to an operator, or has incompatible dimensions for specified subsystems.

Note

Composition (&) by default is defined as left matrix multiplication for matrix operators, while @ (equivalent to dot()) is defined as right matrix multiplication. That is that A & B == A.compose(B) is equivalent to B @ A == B.dot(A) when A and B are of the same type.

Setting the front=True kwarg changes this to right matrix multiplication and is equivalent to the dot() method A.dot(B) == A.compose(B, front=True).

conjugate

conjugate()

GitHub(opens in a new tab)

Return the conjugate of the SparsePauliOp.

copy

copy()

GitHub(opens in a new tab)

Make a deep copy of current operator.

dot

dot(other, qargs=None)

GitHub(opens in a new tab)

Return the right multiplied operator self * other.

Parameters

  • other (Operator) – an operator object.
  • qargs (list(opens in a new tab) or None) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None).

Returns

The right matrix multiplied Operator.

Return type

Operator

Note

The dot product can be obtained using the @ binary operator. Hence a.dot(b) is equivalent to a @ b.

equiv

equiv(other, atol=None)

GitHub(opens in a new tab)

Check if two SparsePauliOp operators are equivalent.

Parameters

Returns

True if the operator is equivalent to self.

Return type

bool(opens in a new tab)

expand

expand(other)

GitHub(opens in a new tab)

Return the reverse-order tensor product with another SparsePauliOp.

Parameters

other (SparsePauliOp) – a SparsePauliOp object.

Returns

the tensor product bab \otimes a, where aa

is the current SparsePauliOp, and bb is the other SparsePauliOp.

Return type

SparsePauliOp

from_list

static from_list(obj, dtype=<class 'complex'>, *, num_qubits=None)

GitHub(opens in a new tab)

Construct from a list of Pauli strings and coefficients.

For example, the 5-qubit Hamiltonian

H=Z1X4+2Y0Y3H = Z_1 X_4 + 2 Y_0 Y_3

can be constructed as

# via tuples and the full Pauli string
op = SparsePauliOp.from_list([("XIIZI", 1), ("IYIIY", 2)])

Parameters

Returns

The SparsePauliOp representation of the Pauli terms.

Return type

SparsePauliOp

Raises

  • QiskitError – If an empty list is passed and num_qubits is None.
  • QiskitError – If num_qubits and the objects in the input list do not match.

from_operator

static from_operator(obj, atol=None, rtol=None)

GitHub(opens in a new tab)

Construct from an Operator objector.

Note that the cost of this construction is exponential in general because the number of possible Pauli terms in the decomposition is exponential in the number of qubits.

Internally this uses an implementation of the “tensorized Pauli decomposition” presented in Hantzko, Binkowski and Gupta (2023)(opens in a new tab).

Parameters

  • obj (Operator) – an N-qubit operator.
  • atol (float(opens in a new tab)) – Optional. Absolute tolerance for checking if coefficients are zero (Default: 1e-8). Since the comparison is to zero, in effect the tolerance used is the maximum of atol and rtol.
  • rtol (float(opens in a new tab)) – Optional. relative tolerance for checking if coefficients are zero (Default: 1e-5). Since the comparison is to zero, in effect the tolerance used is the maximum of atol and rtol.

Returns

the SparsePauliOp representation of the operator.

Return type

SparsePauliOp

Raises

QiskitError – if the input operator is not an N-qubit operator.

from_sparse_list

static from_sparse_list(obj, num_qubits, do_checks=True, dtype=<class 'complex'>)

GitHub(opens in a new tab)

Construct from a list of local Pauli strings and coefficients.

Each list element is a 3-tuple of a local Pauli string, indices where to apply it, and a coefficient.

For example, the 5-qubit Hamiltonian

H=Z1X4+2Y0Y3H = Z_1 X_4 + 2 Y_0 Y_3

can be constructed as

# via triples and local Paulis with indices
op = SparsePauliOp.from_sparse_list([("ZX", [1, 4], 1), ("YY", [0, 3], 2)], num_qubits=5)
 
# equals the following construction from "dense" Paulis
op = SparsePauliOp.from_list([("XIIZI", 1), ("IYIIY", 2)])

Parameters

Returns

The SparsePauliOp representation of the Pauli terms.

Return type

SparsePauliOp

Raises

  • QiskitError – If the number of qubits is incompatible with the indices of the Pauli terms.
  • QiskitError – If the designated qubit is already assigned.

group_commuting

group_commuting(qubit_wise=False)

GitHub(opens in a new tab)

Partition a SparsePauliOp into sets of commuting Pauli strings.

Parameters

qubit_wise (bool(opens in a new tab)) –

whether the commutation rule is applied to the whole operator, or on a per-qubit basis. For example:

>>> op = SparsePauliOp.from_list([("XX", 2), ("YY", 1), ("IZ",2j), ("ZZ",1j)])
>>> op.group_commuting()
[SparsePauliOp(["IZ", "ZZ"], coeffs=[0.+2.j, 0.+1j]),
 SparsePauliOp(["XX", "YY"], coeffs=[2.+0.j, 1.+0.j])]
>>> op.group_commuting(qubit_wise=True)
[SparsePauliOp(['XX'], coeffs=[2.+0.j]),
 SparsePauliOp(['YY'], coeffs=[1.+0.j]),
 SparsePauliOp(['IZ', 'ZZ'], coeffs=[0.+2.j, 0.+1.j])]

Returns

List of SparsePauliOp where each SparsePauliOp contains

commuting Pauli operators.

Return type

list(opens in a new tab)[SparsePauliOp]

input_dims

input_dims(qargs=None)

GitHub(opens in a new tab)

Return tuple of input dimension for specified subsystems.

is_unitary

is_unitary(atol=None, rtol=None)

GitHub(opens in a new tab)

Return True if operator is a unitary matrix.

Parameters

Returns

True if the operator is unitary, False otherwise.

Return type

bool(opens in a new tab)

label_iter

label_iter()

GitHub(opens in a new tab)

Return a label representation iterator.

This is a lazy iterator that converts each term in the SparsePauliOp into a tuple (label, coeff). To convert the entire table to labels use the to_labels() method.

Returns

label iterator object for the SparsePauliOp.

Return type

LabelIterator

matrix_iter

matrix_iter(sparse=False)

GitHub(opens in a new tab)

Return a matrix representation iterator.

This is a lazy iterator that converts each term in the SparsePauliOp into a matrix as it is used. To convert to a single matrix use the to_matrix() method.

Parameters

sparse (bool(opens in a new tab)) – optionally return sparse CSR matrices if True, otherwise return Numpy array matrices (Default: False)

Returns

matrix iterator object for the PauliList.

Return type

MatrixIterator

noncommutation_graph

noncommutation_graph(qubit_wise)

GitHub(opens in a new tab)

Create the non-commutation graph of this SparsePauliOp.

This transforms the measurement operator grouping problem into graph coloring problem. The constructed graph contains one node for each Pauli. The nodes will be connecting for any two Pauli terms that do _not_ commute.

Parameters

qubit_wise (bool(opens in a new tab)) – whether the commutation rule is applied to the whole operator, or on a per-qubit basis.

Returns

the non-commutation graph with nodes for each Pauli and edges

indicating a non-commutation relation. Each node will hold the index of the Pauli term it corresponds to in its data. The edges of the graph hold no data.

Return type

rustworkx.PyGraph(opens in a new tab)

output_dims

output_dims(qargs=None)

GitHub(opens in a new tab)

Return tuple of output dimension for specified subsystems.

power

power(n)

GitHub(opens in a new tab)

Return the compose of a operator with itself n times.

Parameters

n (int(opens in a new tab)) – the number of times to compose with self (n>0).

Returns

the n-times composed operator.

Return type

Clifford

Raises

QiskitError – if the input and output dimensions of the operator are not equal, or the power is not a positive integer.

reshape

reshape(input_dims=None, output_dims=None, num_qubits=None)

GitHub(opens in a new tab)

Return a shallow copy with reshaped input and output subsystem dimensions.

Parameters

  • input_dims (None or tuple(opens in a new tab)) – new subsystem input dimensions. If None the original input dims will be preserved [Default: None].
  • output_dims (None or tuple(opens in a new tab)) – new subsystem output dimensions. If None the original output dims will be preserved [Default: None].
  • num_qubits (None or int(opens in a new tab)) – reshape to an N-qubit operator [Default: None].

Returns

returns self with reshaped input and output dimensions.

Return type

BaseOperator

Raises

QiskitError – if combined size of all subsystem input dimension or subsystem output dimensions is not constant.

simplify

simplify(atol=None, rtol=None)

GitHub(opens in a new tab)

Simplify PauliList by combining duplicates and removing zeros.

Parameters

Returns

the simplified SparsePauliOp operator.

Return type

SparsePauliOp

sort

sort(weight=False)

GitHub(opens in a new tab)

Sort the rows of the table.

After sorting the coefficients using numpy’s argsort, sort by Pauli. Pauli sort takes precedence. If Pauli is the same, it will be sorted by coefficient. By using the weight kwarg the output can additionally be sorted by the number of non-identity terms in the Pauli, where the set of all Pauli’s of a given weight are still ordered lexicographically.

Example

Here is an example of how to use SparsePauliOp sort.

import numpy as np
from qiskit.quantum_info import SparsePauliOp
 
# 2-qubit labels
labels = ["XX", "XX", "XX", "YI", "II", "XZ", "XY", "XI"]
# coeffs
coeffs = [2.+1.j, 2.+2.j, 3.+0.j, 3.+0.j, 4.+0.j, 5.+0.j, 6.+0.j, 7.+0.j]
 
# init
spo = SparsePauliOp(labels, coeffs)
print('Initial Ordering')
print(spo)
 
# Lexicographic Ordering
srt = spo.sort()
print('Lexicographically sorted')
print(srt)
 
# Lexicographic Ordering
srt = spo.sort(weight=False)
print('Lexicographically sorted')
print(srt)
 
# Weight Ordering
srt = spo.sort(weight=True)
print('Weight sorted')
print(srt)
Initial Ordering
SparsePauliOp(['XX', 'XX', 'XX', 'YI', 'II', 'XZ', 'XY', 'XI'],
              coeffs=[2.+1.j, 2.+2.j, 3.+0.j, 3.+0.j, 4.+0.j, 5.+0.j, 6.+0.j, 7.+0.j])
Lexicographically sorted
SparsePauliOp(['II', 'XI', 'XX', 'XX', 'XX', 'XY', 'XZ', 'YI'],
              coeffs=[4.+0.j, 7.+0.j, 2.+1.j, 2.+2.j, 3.+0.j, 6.+0.j, 5.+0.j, 3.+0.j])
Lexicographically sorted
SparsePauliOp(['II', 'XI', 'XX', 'XX', 'XX', 'XY', 'XZ', 'YI'],
              coeffs=[4.+0.j, 7.+0.j, 2.+1.j, 2.+2.j, 3.+0.j, 6.+0.j, 5.+0.j, 3.+0.j])
Weight sorted
SparsePauliOp(['II', 'XI', 'YI', 'XX', 'XX', 'XX', 'XY', 'XZ'],
              coeffs=[4.+0.j, 7.+0.j, 3.+0.j, 2.+1.j, 2.+2.j, 3.+0.j, 6.+0.j, 5.+0.j])

Parameters

  • weight (bool(opens in a new tab)) – optionally sort by weight if True (Default: False).
  • sorted (By using the weight kwarg the output can additionally be) –
  • Pauli. (by the number of non-identity terms in the) –

Returns

a sorted copy of the original table.

Return type

SparsePauliOp

sum

static sum(ops)

GitHub(opens in a new tab)

Sum of SparsePauliOps.

This is a specialized version of the builtin sum function for SparsePauliOp with smaller overhead.

Parameters

ops (list(opens in a new tab)[SparsePauliOp]) – a list of SparsePauliOps.

Returns

the SparsePauliOp representing the sum of the input list.

Return type

SparsePauliOp

Raises

  • QiskitError – if the input list is empty.
  • QiskitError – if the input list includes an object that is not SparsePauliOp.
  • QiskitError – if the numbers of qubits of the objects in the input list do not match.

tensor

tensor(other)

GitHub(opens in a new tab)

Return the tensor product with another SparsePauliOp.

Parameters

other (SparsePauliOp) – a SparsePauliOp object.

Returns

the tensor product aba \otimes b, where aa

is the current SparsePauliOp, and bb is the other SparsePauliOp.

Return type

SparsePauliOp

Note

The tensor product can be obtained using the ^ binary operator. Hence a.tensor(b) is equivalent to a ^ b.

to_list

to_list(array=False)

GitHub(opens in a new tab)

Convert to a list Pauli string labels and coefficients.

For operators with a lot of terms converting using the array=True kwarg will be more efficient since it allocates memory for the full Numpy array of labels in advance.

Parameters

array (bool(opens in a new tab)) – return a Numpy array if True, otherwise return a list (Default: False).

Returns

List of pairs (label, coeff) for rows of the PauliList.

Return type

list(opens in a new tab) or array

to_matrix

to_matrix(sparse=False, force_serial=False)

GitHub(opens in a new tab)

Convert to a dense or sparse matrix.

Parameters

Returns

A dense matrix if sparse=False. csr_matrix: A sparse matrix in CSR format if sparse=True.

Return type

array

to_operator

to_operator()

GitHub(opens in a new tab)

Convert to a matrix Operator object

Return type

Operator

transpose

transpose()

GitHub(opens in a new tab)

Return the transpose of the SparsePauliOp.

Was this page helpful?
Report a bug or request content on GitHub.