Skip to main contentIBM Quantum Documentation
This page is from an old version of Qiskit SDK. Go to the latest version

SparsePauliOp

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

GitHub

Bases: qiskit.quantum_info.operators.linear_op.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.

Initialize an operator object.

Parameters

  • data (PauliList orSparsePauliOp orPauliTable orPauli or list or str) – 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) – 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) – copy the input data if True, otherwise assign it directly, if possible. (Default: True)

Raises

QiskitError – If the input data or coeffs are invalid.

Methods

adjoint

SparsePauliOp.adjoint()

Return the adjoint of the Operator.

chop

SparsePauliOp.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

SparsePauliOp

compose

SparsePauliOp.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

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

SparsePauliOp.conjugate()

Return the conjugate of the SparsePauliOp.

copy

SparsePauliOp.copy()

Make a deep copy of current operator.

dot

SparsePauliOp.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

Operator

Note

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

equiv

SparsePauliOp.equiv(other)

Check if two SparsePauliOp operators are equivalent.

Parameters

other (SparsePauliOp) – an operator object.

Returns

True if the operator is equivalent to self.

Return type

bool

expand

SparsePauliOp.expand(other)

Return the reverse-order tensor product with another SparsePauliOp.

Parameters

other (SparsePauliOp) – a SparsePauliOp object.

Returns

the tensor product b⊗ab \otimes a, where aa

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

Return type

SparsePauliOp

from_list

static SparsePauliOp.from_list(obj)

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

obj (Iterable[Tuple[str, complex]]) – The list of 2-tuples specifying the Pauli terms.

Returns

The SparsePauliOp representation of the Pauli terms.

Return type

SparsePauliOp

Raises

QiskitError – If the list of Paulis is empty.

from_operator

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

Construct from an Operator objector.

Note that the cost of this construction is exponential as it involves taking inner products with every element of the N-qubit Pauli basis.

Parameters

  • obj (Operator) – an N-qubit operator.
  • 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 SparsePauliOp representation of the operator.

Return type

SparsePauliOp

Raises

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

from_sparse_list

static SparsePauliOp.from_sparse_list(obj, num_qubits, do_checks=True)

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

  • 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.

Returns

The SparsePauliOp representation of the Pauli terms.

Return type

SparsePauliOp

Raises

  • QiskitError – If the list of Paulis is empty.
  • 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

SparsePauliOp.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:

>>> 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[SparsePauliOp]

input_dims

SparsePauliOp.input_dims(qargs=None)

Return tuple of input dimension for specified subsystems.

is_unitary

SparsePauliOp.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

bool

label_iter

SparsePauliOp.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 PauliTable.

Return type

LabelIterator

matrix_iter

SparsePauliOp.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

output_dims

SparsePauliOp.output_dims(qargs=None)

Return tuple of output dimension for specified subsystems.

power

SparsePauliOp.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

Pauli

Raises

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

reshape

SparsePauliOp.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

SparsePauliOp.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

SparsePauliOp

sum

static SparsePauliOp.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

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

SparsePauliOp.tensor(other)

Return the tensor product with another SparsePauliOp.

Parameters

other (SparsePauliOp) – a SparsePauliOp object.

Returns

the tensor product a⊗ba \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

SparsePauliOp.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

SparsePauliOp.to_matrix(sparse=False)

Convert to a dense or sparse matrix.

Parameters

sparse (bool) – if True return a sparse CSR matrix, otherwise return dense Numpy array (Default: False).

Returns

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

Return type

array

to_operator

SparsePauliOp.to_operator()

Convert to a matrix Operator object

transpose

SparsePauliOp.transpose()

Return the transpose of the SparsePauliOp.

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.

paulis

Return the the PauliList.

qargs

Return the qargs for the operator.

rtol

Default value: 1e-05

settings

Return settings.

Return type

Dict

size

The number of Pauli of Pauli terms in the operator.

table

DEPRECATED - Return the the PauliTable.

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