SparsePauliOp
class qiskit.quantum_info.SparsePauliOp(data, coeffs=None, *, ignore_pauli_phase=False, copy=True)
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 hundreds 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])])Parameterized SparsePauliOp does not support the following methods:
to_matrix(sparse=True)sincescipy.sparsecannot have objects as elements.to_operator()sinceOperatordoes not support objects.sort,argsortsinceParameterExpressiondoes not support comparison.equivsinceParameterExpressioncannot be converted into complex.chopsinceParameterExpressiondoes not support absolute value.
Initialize an operator object.
Parameters
-
data (PauliList orSparsePauliOp orPauli orlist orstr) – Pauli list of terms. A list of Pauli strings or a Pauli string is also allowed.
-
coeffs (np.ndarray) –
complex coefficients for Pauli terms.
NoteIf
datais aSparsePauliOpandcoeffsis notNone, the value of theSparsePauliOp.coeffswill be ignored, and only the passed keyword argumentcoeffswill be used. -
ignore_pauli_phase (bool) – if true, any
phasecomponent of a givenPauliListwill be assumed to be zero. This is more efficient in cases where aPauliListhas 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 givingPauliListdata. (Default: False) -
copy (bool) – 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
apply_layout
apply_layout(layout, num_qubits=None)
Apply a transpiler layout to this SparsePauliOp
Parameters
- layout (TranspileLayout | List[int] | 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 | None) – The number of qubits to expand the operator to. If not provided then if
layoutis aTranspileLayoutthe number of the transpiler output circuit qubits will be used by default. Iflayoutis 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
argsort
argsort(weight=False)
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) – 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)
Bind the free Parameters in the coefficients to provided values.
Parameters
- parameters (Mapping[Parameter, complex |ParameterExpression] | Sequence[complex |ParameterExpression]) – The values to bind the parameters to.
- inplace (bool) – If
False, a copy of the operator with the bound parameters is returned. IfTruethe operator itself is modified.
Returns
A copy of the operator with bound parameters, if inplace is False, otherwise None.
Return type
SparsePauliOp | None
chop
chop(tol=1e-14)
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) – The absolute tolerance to check whether a real or imaginary part should be set to 0.
Returns
This operator with chopped coefficients.
Return type
compose
compose(other, qargs=None, front=False)
Return the operator composition with another SparsePauliOp.
Parameters
- other (SparsePauliOp) – a SparsePauliOp object.
- qargs (list or None) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None).
- front (bool) – If True compose using right operator multiplication, instead of left multiplication [default: False].
Returns
The composed SparsePauliOp.
Return type
Raises
QiskitError – if other cannot be converted to an operator, or has incompatible dimensions for specified subsystems.
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
copy
dot
dot(other, qargs=None)
Return the right multiplied operator self * other.
Parameters
- other (Operator) – an operator object.
- qargs (list 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
The dot product can be obtained using the @ binary operator. Hence a.dot(b) is equivalent to a @ b.
equiv
equiv(other, atol=None)
Check if two SparsePauliOp operators are equivalent.
Parameters
- other (SparsePauliOp) – an operator object.
- atol (float | None) – Absolute numerical tolerance for checking equivalence.
Returns
True if the operator is equivalent to self.
Return type
expand
expand(other)
Return the reverse-order tensor product with another SparsePauliOp.
Parameters
other (SparsePauliOp) – a SparsePauliOp object.
Returns
the tensor product , where
is the current SparsePauliOp, and is the other SparsePauliOp.
Return type
from_list
static from_list(obj, dtype=<class 'complex'>, *, num_qubits=None)
Construct from a list of Pauli strings and coefficients.
For example, the 5-qubit Hamiltonian
can be constructed as
from qiskit.quantum_info import SparsePauliOp
# via tuples and the full Pauli string
op = SparsePauliOp.from_list([("XIIZI", 1), ("IYIIY", 2)])Parameters
- obj (Iterable[Tuple[str, complex]]) – The list of 2-tuples specifying the Pauli terms.
- dtype (type) – The dtype of coeffs (Default: complex).
- num_qubits (int) – The number of qubits of the operator (Default: None).
Returns
The SparsePauliOp representation of the Pauli terms.
Return type
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)
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).
Parameters
- obj (Operator) – an N-qubit operator.
- atol (float) – 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
atolandrtol. - rtol (float) – 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
atolandrtol.
Returns
the SparsePauliOp representation of the operator.
Return type
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'>)
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
can be constructed as
from qiskit.quantum_info import SparsePauliOp
# 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
- obj (Iterable[tuple[str, list[int], complex]]) – The list 3-tuples specifying the Paulis.
- num_qubits (int) – The number of qubits of the operator.
- do_checks (bool) – The flag of checking if the input indices are not duplicated
- **(**Default – True).
- dtype (type) – The dtype of coeffs (Default: complex).
Returns
The SparsePauliOp representation of the Pauli terms.
Return type
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)
Partition a SparsePauliOp into sets of commuting Pauli strings.
Parameters
qubit_wise (bool) –
whether the commutation rule is applied to the whole operator, or on a per-qubit basis. For example:
>>> from qiskit.quantum_info import SparsePauliOp
>>> 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
input_dims
is_unitary
is_unitary(atol=None, rtol=None)
Return True if operator is a unitary matrix.
Parameters
- atol (float) – Optional. Absolute tolerance for checking if coefficients are zero (Default: 1e-8).
- rtol (float) – Optional. relative tolerance for checking if coefficients are zero (Default: 1e-5).
Returns
True if the operator is unitary, False otherwise.
Return type
label_iter
label_iter()
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)
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) – 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)
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) – 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
output_dims
power
power(n)
Return the compose of a operator with itself n times.
Parameters
n (int) – the number of times to compose with self (n>0).
Returns
the n-times composed operator.
Return type
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)
Return a shallow copy with reshaped input and output subsystem dimensions.
Parameters
- input_dims (None or tuple) – new subsystem input dimensions. If None the original input dims will be preserved [Default: None].
- output_dims (None or tuple) – new subsystem output dimensions. If None the original output dims will be preserved [Default: None].
- num_qubits (None or int) – 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)
Simplify PauliList by combining duplicates and removing zeros.
Parameters
- atol (float) – Optional. Absolute tolerance for checking if coefficients are zero (Default: 1e-8).
- rtol (float) – Optional. relative tolerance for checking if coefficients are zero (Default: 1e-5).
Returns
the simplified SparsePauliOp operator.
Return type
sort
sort(weight=False)
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) – 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
sum
static sum(ops)
Sum of SparsePauliOps.
This is a specialized version of the builtin sum function for SparsePauliOp with smaller overhead.
Parameters
ops (list[SparsePauliOp]) – a list of SparsePauliOps.
Returns
the SparsePauliOp representing the sum of the input list.
Return type
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)
Return the tensor product with another SparsePauliOp.
Parameters
other (SparsePauliOp) – a SparsePauliOp object.
Returns
the tensor product , where
is the current SparsePauliOp, and is the other SparsePauliOp.
Return type
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)
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) – 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 or array
to_matrix
to_matrix(sparse=False, force_serial=False)
Convert to a dense or sparse matrix.
Parameters
- sparse (bool) – if
Truereturn a sparse CSR matrix, otherwise return dense Numpy array (the default). - force_serial (bool) – if
True, use an unthreaded implementation, regardless of the state of the Qiskit threading-control environment variables. By default, this will use threaded parallelism over the available CPUs.
Returns
A dense matrix if sparse=False. csr_matrix: A sparse matrix in CSR format if sparse=True.
Return type
array
to_operator
to_sparse_list
to_sparse_list()
Convert to a sparse Pauli list format with elements (pauli, qubits, coefficient).