PauliList¶

class PauliList(data=None, phase_exp=None, *, input_pauli_encoding='-iYZX', input_qubit_order='right-to-left', tuple_order='zx', order='xz', num_qubits=None, fast_load=True)[source]¶

Bases: BasePauli, LinearMixin, GroupMixin

PauliList inherits from BasePauli

Inits a PauliList

Parameters:

data (BasePauli, np.ndarray, Tuple[np.ndarray], Iterable, None) – List of Pauli Operators. Ex: [‘IIXXZ’,…], np.array([[1,0,1,1],[0,1,0,1]]), …
phase_exp (int, optional) – i**phase_exp. Defaults to 0.
input_qubit_order (str, optional) – Order to read pdata. Defaults to “right-to-left”.
order (str, optional) – Order in which data input lists X and Z. Defaults to ‘xz’
num_qubits (int, optional) – Number of qubits to use in Pauli. Defaults to None.
fast_load (bool, optional) – If True class stores individual Pauls for fast element selection. The fast_load options is much faster when loading elements from the list, say 100ns versus 2.3 us but does so at the cost of initializing speed and memory. Defaults to True

Raises:

QiskitError – Something went wrong.

Examples

>>>PauliList([“IIX”, “iIYI”, “ZII”], num_qubits=10) PauliList([‘IIIIIIIIIX’, ‘iIIIIIIIIYI’, ‘IIIIIIIZII’])

>>>paulis = PauliList([“IIX”, “iIYI”, “ZII”]) >>>%timeit pauli[1] 97.1 ns ± 0.463 ns per loop (mean ± std. dev. of 7 runs, 10,000,000 loops each)

>>>paulis.set_fast_load(False)

>>>%timeit pauli[1] 2.33 μs ± 14.9 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)

>>>PauliList([“IIX”, “iIYI”, “ZII”], fast_load=False)

>>>PauliList(np.array([[1,1,0,0],[0,1,0,1]]), order = ‘zx’) PauliList([‘ZZ’, ‘YI’])

>>>PauliList([‘XZX’,’XXX’,’YIX’], input_qubit_order=”left-to-right”) PauliList([‘XZX’, ‘XXX’, ‘XIY’])

Methods

adjoint()[source]¶: Return the adjoint of each Pauli in the list.

all_commutes(other)¶

_summary_

Parameters:: other (BasePauli) – _description_
Returns:: _description_
Return type:: np.ndarray

anticommutes(other, qargs=None)[source]¶

Return True if other Pauli that anticommutes with other.

Parameters:

other (PauliList) – another PauliList operator.
qargs (list) – qubits to apply dot product on (default: None).

Returns:

True if Pauli’s anticommute, False if they commute.

Return type:

bool

anticommutes_with_all(other)[source]¶

Return indexes of rows that commute other.

If other is a multi-row Pauli list the returned vector indexes rows of the current PauliList that anti-commute with all Pauli’s in other. If no rows satisfy the condition the returned array will be empty.

Parameters:: other (PauliList) – a single Pauli or multi-row PauliList.
Returns:: index array of the anti-commuting rows.
Return type:: array

argsort(weight=False, phase=False)[source]¶

Return indices for sorting the rows of the table.

The default sort method is lexicographic sorting by qubit number. 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.

Parameters:

weight (bool) – Optionally sort by weight if True (Default: False).
phase (bool) – Optionally sort by phase before weight or order (Default: False).

Returns:

the indices for sorting the table.

Return type:

array

commutes(other, qargs=None)[source]¶

Return True for each Pauli that commutes with other.

Parameters:

other (PauliList) – another PauliList operator.
qargs (list) – qubits to apply dot product on (default: None).

Returns:

True if Pauli’s commute, False if they anti-commute.

Return type:

bool

commutes_with_all(other)[source]¶

Return indexes of rows that commute other.

If other is a multi-row Pauli list the returned vector indexes rows of the current PauliList that commute with all Pauli’s in other. If no rows satisfy the condition the returned array will be empty.

Parameters:: other (PauliList) – a single Pauli or multi-row PauliList.
Returns:: index array of the commuting rows.
Return type:: array

compose(other, qargs=None, front=False, inplace=False)[source]¶

Return the composition self∘other for each Pauli in the list.

Parameters:

other (PauliList) – another PauliList.
qargs (None or list) – qubits to apply dot product on (Default: None).
front (bool) – If True use dot composition method [default: False].
inplace (bool) – If True update in-place (default: False).

Returns:

the list of composed Paulis.

Return type:

PauliList

Raises:

QiskitError – if other cannot be converted to a PauliList, does not have either 1 or the same number of Paulis as the current list, or has the wrong number of qubits for the specified qargs.

conjugate()[source]¶: Return the conjugate of each Pauli in the list.

copy()¶

Make a deep copy of current operator.

Return type:: BasePauli

delete(ind, qubit=False)[source]¶

Return a copy with Pauli rows deleted from table.

When deleting qubits the qubit index is the same as the column index of the underlying X and Z arrays.

Parameters:

ind (int or list) – index(es) to delete.
qubit (bool) – if True delete qubit columns, otherwise delete Pauli rows (Default: False).

Returns:

the resulting table with the entries removed.

Return type:

PauliList

Raises:

QiskitError – if ind is out of bounds for the array size or number of qubits.

Note: Update this method to work with other encodings (assumes Y type encoding in phase_exp)

dot(other, qargs=None, inplace=False)[source]¶

Return the composition other∘self for each Pauli in the list.

Parameters:

other (PauliList) – another PauliList.
qargs (None or list) – qubits to apply dot product on (Default: None).
inplace (bool) – If True update in-place (default: False).

Returns:

the list of composed Paulis.

Return type:

PauliList

Raises:

QiskitError – if other cannot be converted to a PauliList, does not have either 1 or the same number of Paulis as the current list, or has the wrong number of qubits for the specified qargs.

evolve(other, qargs=None, frame='h')[source]¶

Evolve the Pauli by a Clifford.

This returns the Pauli \(P^\prime = C.P.C^\dagger\).

By choosing the parameter frame=’s’, this function returns the Schrödinger evolution of the Pauli \(P^\prime = C.P.C^\dagger\). This option yields a faster calculation.

Parameters:

other (Pauli or Clifford or QuantumCircuit) – The Clifford operator to evolve by.
qargs (list) – a list of qubits to apply the Clifford to.
frame (string) – ‘h’ for Heisenberg or ‘s’ for Schrödinger framework.

Returns:

the Pauli \(C.P.C^\dagger\).

Return type:

Pauli

Raises:

QiskitError – if the Clifford number of qubits and qargs don’t match.

expand(other)[source]¶

Return the expand product of each Pauli in the list.

Parameters:: other (PauliList) – another PauliList.
Returns:: the list of tensor product Paulis.
Return type:: PauliList
Raises:: QiskitError – if other cannot be converted to a PauliList, does not have either 1 or the same number of Paulis as the current list.

classmethod from_symplectic(z, x, phase_exp=0)[source]¶

Construct a PauliList from a symplectic data.

Parameters:

z (np.ndarray) – 2D boolean Numpy array.
x (np.ndarray) – 2D boolean Numpy array.
phase_exp (np.ndarray or None) – Optional, 1D integer array from Z_4.

Returns:

the constructed PauliList.

Return type:

PauliList

Note: Initialization this way will copy matrices and not reference them.

TODO: Fix this method to be more general and not in old form only: (i.e. include matrix inputs …)

getaslist(slc)[source]¶

_summary_

Returns:: _description_
Return type:: _type_

group_qubit_wise_commuting()[source]¶

Partition a PauliList into sets of mutually qubit-wise commuting Pauli strings.

Returns:: List of PauliLists where each PauliList contains commutable Pauli operators.
Return type:: List[PauliList]

input_dims(qargs=None)¶: Return tuple of input dimension for specified subsystems.

insert(ind, value, qubit=False)[source]¶

Insert Pauli’s into the table.

When inserting qubits the qubit index is the same as the column index of the underlying X and Z arrays.

Parameters:

ind (int) – index to insert at.
value (PauliList) – values to insert.
qubit (bool) – if True delete qubit columns, otherwise delete Pauli rows (Default: False).

Returns:

the resulting table with the entries inserted.

Return type:

PauliList

Raises:

QiskitError – if the insertion index is invalid.

Note: Update this method to work with other encodings (assumes Y type encoding in phase_exp)

inverse()[source]¶: Return the inverse of each Pauli in the list.

label_iter()[source]¶

Return a label representation iterator.

This is a lazy iterator that converts each row into the string label only as it is used. To convert the entire table to labels use the to_labels() method.

Returns:: label iterator object for the PauliList.
Return type:: LabelIterator

matrix_iter(sparse=False)[source]¶

Return a matrix representation iterator.

This is a lazy iterator that converts each row into the Pauli matrix representation only as it is used. To convert the entire table to matrices 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(qargs=None)¶: Return tuple of output dimension for specified subsystems.

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:: Clifford
Raises:: QiskitError – if the input and output dimensions of the operator are not equal, or the power is not a positive integer.

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.

set_fast_load(fast_load)[source]¶: Set if class uses the fast_store method. Storing Pauli variables

classmethod set_pauli_encoding(encoding='-iYZX')¶

Set the Pauli encoding

Parameters:

encoding (optional) – Pauli encoding.
pauli_rep.DEFAULT_EXTERNAL_PAULI_REP_FORMAT. (Defaults to)

classmethod set_phase_encoding(encoding='-i')¶

Set the phase encoding

Parameters:

encoding (optional) – phase encoding.
pauli_rep.DEFAULT_EXTERNAL_PHASE_ENCODING. (Defaults to)

classmethod set_print_phase_encoding(phase_encoding=None)¶

_summary_

Parameters:: phase_encoding (Optional[str], optional) – _description_. Defaults to None.
Raises:: QiskitError – _description_

classmethod set_qubit_order(qubit_order=None)¶

Set external qubit order

Parameters:: qubit_order (Optional[str], optional) – _description_. Defaults to None.
Raises:: QiskitError – _description_

classmethod set_syntax(syntax_code=None, syntax_str='Product')¶

Sets the global input and output format

Parameters:

syntax_code (Optional[int], optional) – sets the syntax of Pauli tensors. Possible inputs are 0 for product syntax, 1 for index syntax and 2 for latex syntax. Defaults to None.
syntax_str (Optional[str], optional) – sets the syntax of Pauli tensors. Possible inputs are Product or Latex, if another input is given the syntax is set to Order. Defaults to “Product”.

Raises:

QiskitError – Unknown syntax: {syntax_code}. See pauli_rep for options.

classmethod set_tensor_encoding(encoding='YZX')¶

Set the external symplectic matrix format

Parameters:

encoding (optional) – Symplectic matrix tensor encoding.
pauli_rep.DEFAULT_EXTERNAL_TENSOR_ENCODING. (Defaults to)

sort(weight=False, phase=False)[source]¶

Sort the rows of the table.

Example

Consider sorting all a random ordering of all 2-qubit Paulis

from numpy.random import shuffle
from qiskit.quantum_info.operators import PauliList

# 2-qubit labels
labels = ['II', 'IX', 'IY', 'IZ', 'XI', 'XX', 'XY', 'XZ',
          'YI', 'YX', 'YY', 'YZ', 'ZI', 'ZX', 'ZY', 'ZZ']
# Shuffle Labels
shuffle(labels)
pt = PauliList(labels)
print('Initial Ordering')
print(pt)

# Lexicographic Ordering
srt = pt.sort()
print('Lexicographically sorted')
print(srt)

# Weight Ordering
srt = pt.sort(weight=True)
print('Weight sorted')
print(srt)

(Source code)

Parameters:

weight (bool) – optionally sort by weight if True (Default: False).
phase (bool) – Optionally sort by phase before weight or order (Default: False).

Returns:

a sorted copy of the original table.

Return type:

PauliList

tensor(other)[source]¶

Return the tensor product with each Pauli in the list.

Parameters:: other (PauliList) – another PauliList.
Returns:: the list of tensor product Paulis.
Return type:: PauliList
Raises:: QiskitError – if other cannot be converted to a PauliList, does not have either 1 or the same number of Paulis as the current list.

to_label(output_pauli_encoding=None, no_phase=False, return_phase=False, syntax=None, qubit_order=None, index_start=0, squeeze=True, index_str='')¶

Returns the string representatiojn for a Pauli or Paulis.

Parameters:

output_pauli_encoding (optional) – Encoding used to represent phases. A value of None will result in complex phases notation. Defaults to None which will in turn use BasePauli.EXTERNAL_PAULI_ENCODING.
no_phase (optional) – When set to True, no phase will appear no matter what encoding is selected. So the symplectic matrix [1, 1] will produce the operator Y in ‘XZY’ encoding but also (XZ) in the ‘XZ’ encoding which are different operators if phases are considered. Defaults to False.
return_phase (optional) – If True return the adjusted phase for the coefficient of the returned Pauli label. This can be used even if full_group=False.
syntax (optional) – Syntax of pauli tensor. Values are PRODUCT_SYNTAX = 0 and INDEX_SYNTAX=1. Defaults to INDEX_SYNTAX.
qubit_order (optional) – Order in which qubits are read. options aree “right-to-left” and “left-to-right”. Defaults to “right-to-left”.
index_start (optional) – Lowest value for index in index syntax tensors. Defaults to 0
squeeze (optional) – Squeezes the list of reults to a scalar if the number of Paulis is one. Defaults to True.
index_str (optional) – String that get inserted between operator and numbers in index format. Default is “”.

Returns:

the Pauli label(string) from the full Pauli group (if no_phase=False) or: from the unsigned Pauli group (if no_phase=True).
Tuple[str or List[str], Any or List[Any]]: if return_phase=True returns a: tuple of the Pauli label (from either the full or unsigned Pauli group) and the phase q for the coefficient \((-i)^(q + x.z)\) for the label from the full Pauli group.

Return type:

str

to_labels(array=False)[source]¶

Convert a PauliList to a list Pauli string labels.

For large PauliLists converting using the array=True kwarg will be more efficient since it allocates memory for the full Numpy array of labels in advance.

Table 1 Pauli Representations¶
Label	Symplectic	Matrix
`"I"`	\([0, 0]\)	\(\begin{bmatrix} 1 & 0 \\ 0 & 1 \end{bmatrix}\)
`"X"`	\([1, 0]\)	\(\begin{bmatrix} 0 & 1 \\ 1 & 0 \end{bmatrix}\)
`"Y"`	\([1, 1]\)	\(\begin{bmatrix} 0 & -i \\ i & 0 \end{bmatrix}\)
`"Z"`	\([0, 1]\)	\(\begin{bmatrix} 1 & 0 \\ 0 & -1 \end{bmatrix}\)

Parameters:: array (bool) – return a Numpy array if True, otherwise return a list (Default: False).
Returns:: The rows of the PauliList in label form.
Return type:: list or array

to_matrix(sparse=False, array=False)[source]¶

Convert to a list or array of Pauli matrices.

For large PauliLists converting using the array=True kwarg will be more efficient since it allocates memory a full rank-3 Numpy array of matrices in advance.

Table 2 Pauli Representations¶
Label	Symplectic	Matrix
`"I"`	\([0, 0]\)	\(\begin{bmatrix} 1 & 0 \\ 0 & 1 \end{bmatrix}\)
`"X"`	\([1, 0]\)	\(\begin{bmatrix} 0 & 1 \\ 1 & 0 \end{bmatrix}\)
`"Y"`	\([1, 1]\)	\(\begin{bmatrix} 0 & -i \\ i & 0 \end{bmatrix}\)
`"Z"`	\([0, 1]\)	\(\begin{bmatrix} 1 & 0 \\ 0 & -1 \end{bmatrix}\)

Parameters:

sparse (bool) – if True return sparse CSR matrices, otherwise return dense Numpy arrays (Default: False).
array (bool) – return as rank-3 numpy array if True, otherwise return a list of Numpy arrays (Default: False).

Returns:

A list of dense Pauli matrices if array=False and sparse=False. list: A list of sparse Pauli matrices if array=False and sparse=True. array: A dense rank-3 array of Pauli matrices if array=True.

Return type:

list

transpose()[source]¶: Return the transpose of each Pauli in the list.

unique(return_index=False, return_counts=False)[source]¶

Return unique Paulis from the table.

Example

from qiskit.quantum_info.operators import PauliList

pt = PauliList(['X', 'Y', '-X', 'I', 'I', 'Z', 'X', 'iZ'])
unique = pt.unique()
print(unique)

(Source code)

Parameters:

return_index (bool) – If True, also return the indices that result in the unique array. (Default: False)
return_counts (bool) – If True, also return the number of times each unique item appears in the table.

Returns:

unique: the table of the unique rows.
unique_indices: np.ndarray, optional: The indices of the first occurrences of the unique values in the original array. Only provided if return_index is True.
unique_counts: np.array, optional: The number of times each of the unique values comes up in the original array. Only provided if return_counts is True.

Return type:

PauliList

# Check is all phases used are correct (_phase_exp versus phase_exp)

Attributes

EXTERNAL_PAULI_ENCODING = '-iYZX'¶

EXTERNAL_PHASE_ENCODING = '-i'¶

EXTERNAL_QUBIT_ORDER = 'right-to-left'¶

EXTERNAL_SYNTAX = 0¶

EXTERNAL_TENSOR_ENCODING = 'YZX'¶

PRINT_PHASE_ENCODING = None¶

dim¶: Return tuple (input_shape, output_shape).

num_paulis¶: Returns the number of Pauli’s in List

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

num_y¶: Return the number of Y for each operator

pauli_encoding¶: Pauli format.

phase¶

Return the phase vector of the PauliList.

Note: This is different from the quantum_info phase property which instead returns the phase_exp

phase_encoding¶: Return the phase encoding

phase_exp¶: Return the phase exponent vector of the PauliList

print_phase_encoding¶: Prints how the phase will be displayed in when printing.

qargs¶: Return the qargs for the operator.

qubit_order¶: Get external qubit order

settings¶: Return settings.

shape¶: The full shape of the array()

size¶: The number of Pauli rows in the table.

syntax¶: Returns the syntax

tensor_encoding¶: Return the external symplectic matrix encoding

x¶

Returns the X part of symplectic representation as a 2d matrix.

Note: The Pauli class over writes this method to return a 1d array instead of a 2d array. Use the self._x method if a 2d array is needed as _x method is markeded as @final

Examples

>>> matrix = numpy.array([[1,0,0,0],[0,1,1,1]], dtype=numpy.bool_)
>>> phase_exp = numpy.array([0,1])
>>> base_pauli = BasePauli(matrix, phase_exp)
>>> base_pauli.x.astype(int)
array([[1, 0],
       [0, 1]])