qiskit-documentation/docs/api/qiskit/0.38/qiskit.quantum_info.SparseP...

610 lines
21 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
title: SparsePauliOp
description: API reference for qiskit.quantum_info.SparsePauliOp
in_page_toc_min_heading_level: 1
python_api_type: class
python_api_name: qiskit.quantum_info.SparsePauliOp
---
# SparsePauliOp
<Class id="qiskit.quantum_info.SparsePauliOp" isDedicatedPage={true} github="https://github.com/qiskit/qiskit/tree/stable/0.21/qiskit/quantum_info/operators/symplectic/sparse_pauli_op.py" signature="SparsePauliOp(data, coeffs=None, *, ignore_pauli_phase=False, copy=True)" modifiers="class">
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`](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") in terms of N-qubit [`PauliList`](qiskit.quantum_info.PauliList "qiskit.quantum_info.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`](qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") object and can be accessed using the [`paulis`](#qiskit.quantum_info.SparsePauliOp.paulis "qiskit.quantum_info.SparsePauliOp.paulis") attribute. The coefficients are stored as a complex Numpy array vector and can be accessed using the [`coeffs`](#qiskit.quantum_info.SparsePauliOp.coeffs "qiskit.quantum_info.SparsePauliOp.coeffs") attribute.
Initialize an operator object.
**Parameters**
* **data** ([*PauliList*](qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") *or*[*SparsePauliOp*](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") *or*[*PauliTable*](qiskit.quantum_info.PauliTable "qiskit.quantum_info.PauliTable") *or*[*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") *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.
<Admonition title="Note" type="note">
If `data` is a [`SparsePauliOp`](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.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.
</Admonition>
* **ignore\_pauli\_phase** (*bool*) if true, any `phase` component of a given [`PauliList`](qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") will be assumed to be zero. This is more efficient in cases where a [`PauliList`](qiskit.quantum_info.PauliList "qiskit.quantum_info.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`](qiskit.quantum_info.PauliList "qiskit.quantum_info.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
<Function id="qiskit.quantum_info.SparsePauliOp.adjoint" signature="SparsePauliOp.adjoint()">
Return the adjoint of the Operator.
</Function>
### chop
<Function id="qiskit.quantum_info.SparsePauliOp.chop" signature="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()`](qiskit.quantum_info.SparsePauliOp#simplify "qiskit.quantum_info.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](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")
</Function>
### compose
<Function id="qiskit.quantum_info.SparsePauliOp.compose" signature="SparsePauliOp.compose(other, qargs=None, front=False)">
Return the operator composition with another SparsePauliOp.
**Parameters**
* **other** ([*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.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](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")
**Raises**
**QiskitError** if other cannot be converted to an operator, or has incompatible dimensions for specified subsystems.
<Admonition title="Note" type="note">
Composition (`&`) by default is defined as left matrix multiplication for matrix operators, while `@` (equivalent to [`dot()`](qiskit.quantum_info.SparsePauliOp#dot "qiskit.quantum_info.SparsePauliOp.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()`](qiskit.quantum_info.SparsePauliOp#dot "qiskit.quantum_info.SparsePauliOp.dot") method `A.dot(B) == A.compose(B, front=True)`.
</Admonition>
</Function>
### conjugate
<Function id="qiskit.quantum_info.SparsePauliOp.conjugate" signature="SparsePauliOp.conjugate()">
Return the conjugate of the SparsePauliOp.
</Function>
### copy
<Function id="qiskit.quantum_info.SparsePauliOp.copy" signature="SparsePauliOp.copy()">
Make a deep copy of current operator.
</Function>
### dot
<Function id="qiskit.quantum_info.SparsePauliOp.dot" signature="SparsePauliOp.dot(other, qargs=None)">
Return the right multiplied operator self \* other.
**Parameters**
* **other** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.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](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")
<Admonition title="Note" type="note">
The dot product can be obtained using the `@` binary operator. Hence `a.dot(b)` is equivalent to `a @ b`.
</Admonition>
</Function>
### equiv
<Function id="qiskit.quantum_info.SparsePauliOp.equiv" signature="SparsePauliOp.equiv(other)">
Check if two SparsePauliOp operators are equivalent.
**Parameters**
**other** ([*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")) an operator object.
**Returns**
True if the operator is equivalent to `self`.
**Return type**
bool
</Function>
### expand
<Function id="qiskit.quantum_info.SparsePauliOp.expand" signature="SparsePauliOp.expand(other)">
Return the reverse-order tensor product with another SparsePauliOp.
**Parameters**
**other** ([*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")) a SparsePauliOp object.
**Returns**
**the tensor product $b \otimes a$, where $a$**
is the current SparsePauliOp, and $b$ is the other SparsePauliOp.
**Return type**
[SparsePauliOp](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")
</Function>
### from\_list
<Function id="qiskit.quantum_info.SparsePauliOp.from_list" signature="SparsePauliOp.from_list(obj)" modifiers="static">
Construct from a list of Pauli strings and coefficients.
For example, the 5-qubit Hamiltonian
$$
H = Z_1 X_4 + 2 Y_0 Y_3
$$
can be constructed as
```python
# 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](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")
**Raises**
**QiskitError** If the list of Paulis is empty.
</Function>
### from\_operator
<Function id="qiskit.quantum_info.SparsePauliOp.from_operator" signature="SparsePauliOp.from_operator(obj, atol=None, rtol=None)" modifiers="static">
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*](qiskit.quantum_info.Operator "qiskit.quantum_info.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](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")
**Raises**
**QiskitError** if the input operator is not an N-qubit operator.
</Function>
### from\_sparse\_list
<Function id="qiskit.quantum_info.SparsePauliOp.from_sparse_list" signature="SparsePauliOp.from_sparse_list(obj, num_qubits, do_checks=True)" modifiers="static">
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 = Z_1 X_4 + 2 Y_0 Y_3
$$
can be constructed as
```python
# 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](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.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.
</Function>
### group\_commuting
<Function id="qiskit.quantum_info.SparsePauliOp.group_commuting" signature="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:
```python
>>> 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](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")]
</Function>
### input\_dims
<Function id="qiskit.quantum_info.SparsePauliOp.input_dims" signature="SparsePauliOp.input_dims(qargs=None)">
Return tuple of input dimension for specified subsystems.
</Function>
### is\_unitary
<Function id="qiskit.quantum_info.SparsePauliOp.is_unitary" signature="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
</Function>
### label\_iter
<Function id="qiskit.quantum_info.SparsePauliOp.label_iter" signature="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
</Function>
### matrix\_iter
<Function id="qiskit.quantum_info.SparsePauliOp.matrix_iter" signature="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()`](qiskit.quantum_info.SparsePauliOp#to_matrix "qiskit.quantum_info.SparsePauliOp.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
</Function>
### output\_dims
<Function id="qiskit.quantum_info.SparsePauliOp.output_dims" signature="SparsePauliOp.output_dims(qargs=None)">
Return tuple of output dimension for specified subsystems.
</Function>
### power
<Function id="qiskit.quantum_info.SparsePauliOp.power" signature="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](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli")
**Raises**
**QiskitError** if the input and output dimensions of the operator are not equal, or the power is not a positive integer.
</Function>
### reshape
<Function id="qiskit.quantum_info.SparsePauliOp.reshape" signature="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.
</Function>
### simplify
<Function id="qiskit.quantum_info.SparsePauliOp.simplify" signature="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](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")
</Function>
### sum
<Function id="qiskit.quantum_info.SparsePauliOp.sum" signature="SparsePauliOp.sum(ops)" modifiers="static">
Sum of SparsePauliOps.
This is a specialized version of the builtin `sum` function for SparsePauliOp with smaller overhead.
**Parameters**
**ops** (*list\[*[*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")*]*) a list of SparsePauliOps.
**Returns**
the SparsePauliOp representing the sum of the input list.
**Return type**
[SparsePauliOp](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.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.
</Function>
### tensor
<Function id="qiskit.quantum_info.SparsePauliOp.tensor" signature="SparsePauliOp.tensor(other)">
Return the tensor product with another SparsePauliOp.
**Parameters**
**other** ([*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")) a SparsePauliOp object.
**Returns**
**the tensor product $a \otimes b$, where $a$**
is the current SparsePauliOp, and $b$ is the other SparsePauliOp.
**Return type**
[SparsePauliOp](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")
<Admonition title="Note" type="note">
The tensor product can be obtained using the `^` binary operator. Hence `a.tensor(b)` is equivalent to `a ^ b`.
</Admonition>
</Function>
### to\_list
<Function id="qiskit.quantum_info.SparsePauliOp.to_list" signature="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
</Function>
### to\_matrix
<Function id="qiskit.quantum_info.SparsePauliOp.to_matrix" signature="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
</Function>
### to\_operator
<Function id="qiskit.quantum_info.SparsePauliOp.to_operator" signature="SparsePauliOp.to_operator()">
Convert to a matrix Operator object
</Function>
### transpose
<Function id="qiskit.quantum_info.SparsePauliOp.transpose" signature="SparsePauliOp.transpose()">
Return the transpose of the SparsePauliOp.
</Function>
## Attributes
### atol
<Attribute id="qiskit.quantum_info.SparsePauliOp.atol" attributeValue="1e-08" />
### coeffs
<Attribute id="qiskit.quantum_info.SparsePauliOp.coeffs">
Return the Pauli coefficients.
</Attribute>
### dim
<Attribute id="qiskit.quantum_info.SparsePauliOp.dim">
Return tuple (input\_shape, output\_shape).
</Attribute>
### num\_qubits
<Attribute id="qiskit.quantum_info.SparsePauliOp.num_qubits">
Return the number of qubits if a N-qubit operator or None otherwise.
</Attribute>
### paulis
<Attribute id="qiskit.quantum_info.SparsePauliOp.paulis">
Return the the PauliList.
</Attribute>
### qargs
<Attribute id="qiskit.quantum_info.SparsePauliOp.qargs">
Return the qargs for the operator.
</Attribute>
### rtol
<Attribute id="qiskit.quantum_info.SparsePauliOp.rtol" attributeValue="1e-05" />
### settings
<Attribute id="qiskit.quantum_info.SparsePauliOp.settings">
Return settings.
**Return type**
`Dict`
</Attribute>
### size
<Attribute id="qiskit.quantum_info.SparsePauliOp.size">
The number of Pauli of Pauli terms in the operator.
</Attribute>
### table
<Attribute id="qiskit.quantum_info.SparsePauliOp.table">
DEPRECATED - Return the the PauliTable.
</Attribute>
</Class>